agentscope-ai / agentscope-ai/QwenPaw
[Feature]: Add plain-language explanations and optional AI summaries to tool approval prompts
- Vorherrschende Sprache
- Python
- Sterne
- 34.9k
- Forks
- 3.1k
- Ø Merge
- 1 T. 15 Std.
- Gemergte PRs (30 T.)
- 225
Beschreibung
## 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).
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.