agentscope-ai / agentscope-ai/QwenPaw

[Feature]: Add plain-language explanations and optional AI summaries to tool approval prompts

Ouverte
#7,108 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub
enhancement
Langage dominant
TypeScript
Étoiles
35k
Forks
3.1k
Merge moyen
1 j 13 h
PR mergées (30 j)
228

Description

## Summary

Improve the tool approval experience in QwenPaw 2.0.1 for users without a technical background.

Before asking for approval, QwenPaw should explain in plain language:

- what action is about to happen;
- which file, URL, application, account, or data will be affected;
- whether the action is read-only, writes data, deletes data, or sends data externally;
- the likely impact, risk, and whether the action can be undone.

For built-in tools, these explanations can be deterministic and maintained as tool metadata. If approval scenarios cannot be exhaustively described—especially for custom tools, plugins, and skills—QwenPaw could offer an optional model-generated summary as a fallback.

## Component(s) Affected

- [x] Core / Backend (app, agents, config, providers, utils, local_models)
- [x] Console (frontend web UI)
- [x] Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
- [ ] Skills
- [ ] CLI
- [ ] Documentation (website)
- [ ] Tests
- [ ] CI/CD
- [ ] Scripts / Deploy

## Problem / Motivation

The current approval content is primarily oriented around technical tool details. A user may see a tool name, command, path, URL, or argument payload, but still not understand the practical consequence of approving it.

This creates several problems for non-technical users:

1. They cannot confidently distinguish a harmless read-only action from a destructive or privacy-sensitive action.
2. They may approve requests blindly because the technical details are difficult to interpret.
3. They may deny safe requests unnecessarily, interrupting otherwise useful workflows.
4. Custom tools and plugins make a fully hand-written list of approval explanations difficult to maintain.

An approval dialog only improves safety when the user can understand the decision being requested.

## Proposed Solution

### 1. Add a plain-language approval summary

Show a compact, structured explanation above the raw tool-call details:

- **Action:** What the tool intends to do
- **Target:** The affected resource, such as a file, directory, URL, service, or account
- **Data boundary:** Whether data stays local or may be sent to an external service
- **Impact:** Read, create, modify, overwrite, delete, execute, or publish
- **Risk:** Low / Medium / High, with a short reason
- **Reversibility:** Whether the result can be undone
- **Source:** Built-in explanation or AI-generated explanation

Keep the original tool name and arguments available under an expandable "Technical details" section so advanced users can verify the exact request.

Example:

> **Action:** Delete untracked files from the current repository
> **Target:** The current project directory
> **Risk:** High — deleted untracked files cannot be restored by Git
> **Reversibility:** Not automatically reversible

### 2. Use deterministic descriptions for known tools

Built-in tools could declare user-facing metadata or a formatter for common approval fields. This provides predictable, localizable explanations without an extra model call for common cases.

### 3. Offer an optional model-generated fallback

When no curated explanation is available, provide either:

- an "Explain this request" button; or
- a configurable option to generate the explanation automatically.

The summarizer could receive the tool name, schema, arguments, and tool-guard findings, then return a small structured result matching the fields above.

The generated explanation should:

- be clearly labeled as AI-generated;
- be advisory only and never change the tool call or automatically approve it;
- preserve the original request as the source of truth;
- redact credentials, tokens, and other sensitive values before any model call;
- respect privacy settings, especially when a remote model would receive tool arguments;
- fall back to the original approval view if summarization is unavailable or fails.

### 4. Keep approval actions explicit

Use clear actions such as **Allow once** and **Deny**, and keep the risk explanation visible next to those actions. Longer-lived trust scopes, if added, should remain visually distinct from one-time approval.

## Alternatives Considered

1. **Maintain explanations for every approval scenario manually:** Reliable for built-in tools, but difficult to scale to custom tools, plugins, and skills.
2. **Continue showing only raw tool names and arguments:** Technically precise, but inaccessible to many users.
3. **Use only a model-generated summary:** More scalable, but introduces latency, privacy concerns, and the risk of an inaccurate explanation.

A hybrid approach—deterministic descriptions first, optional model summary as a fallback—provides a better balance of reliability, coverage, and usability.

## Acceptance Criteria

- [ ] Common built-in approval requests display a plain-language action, target, impact, and risk.
- [ ] Users can inspect the original tool name and arguments before deciding.
- [ ] Unknown or custom tools can use an optional model-generated explanation.
- [ ] AI-generated explanations are clearly labeled and never cause automatic approval.
- [ ] Sensitive values are redacted before remote summarization.
- [ ] Summary failures safely fall back to the original approval UI.
- [ ] User-facing text follows the configured locale where possible.
- [ ] Tests cover representative read-only, write, destructive, network, redaction, and summary-failure scenarios.

## Additional Context

- Observed in QwenPaw 2.0.1.
- This is a UX and informed-consent follow-up to #174 and the tool-guard work merged in #563.
- It complements #4450, which focuses on approval commands and approval scopes rather than explaining the requested action.
- The feature could be introduced incrementally: deterministic summaries for built-in tools first, followed by the optional model fallback.

## Willing to Contribute

- [ ] I am willing to open a PR for this feature (after discussion).

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Start by tracing the existing approval flow across the Core/Backend, Console, and Channels components, and review the tool-guard work in #563 plus related approval issues #174 and #4450. Define the deterministic metadata path and optional model fallback before implementing. Done means the acceptance criteria pass for built-in, custom, destructive, network, redaction, locale, and summary-failure scenarios without changing approval behavior.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
backend, frontend, security, testing
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
Active
Clarté
Plutôt claire
Accessibilité débutants
42/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.