fix(pipes): fix mcp tool filtering and force-enable autonomous web search
- Fix issue where mcp tool filtering logic (function_name_filter_list) in admin backend caused all tools to be hidden due to ID prefix mismatch - Force enable web_search tool for Copilot Agent regardless of UI toggles, providing full autonomy for search-related intents - Updated README and version to v0.9.1
This commit is contained in:
fujie
@@ -0,0 +1,192 @@
|
||||
# 🧭 Agents 稳定性与友好性指南
|
||||
|
||||
本文聚焦如何提升 `github_copilot_sdk.py` 中 Agent 的**稳定性**与**交互友好性**。
|
||||
|
||||
---
|
||||
|
||||
## 1）目标
|
||||
|
||||
- 降低可避免失败（超时、工具死路、输出不可解析）。
|
||||
- 在高压场景保持可预期（大上下文、上游不稳定、部分工具失败）。
|
||||
- 提升交互体验（进度可见、风险操作先澄清、优雅降级）。
|
||||
- 在不破坏兼容性的前提下逐步增强默认行为。
|
||||
|
||||
---
|
||||
|
||||
## 2）稳定性模型（4 层）
|
||||
|
||||
## A 层：输入安全
|
||||
|
||||
- 会话创建前验证关键上下文（user/chat/model/tool 可用性）。
|
||||
- 对 JSON/配置采用严格解析，不信任自由文本。
|
||||
- 对不支持的模式组合做前置拦截（例如：任务需要工具但工具被禁用）。
|
||||
|
||||
**落地建议**
|
||||
- `create_session` 前增加 preflight validator。
|
||||
- 快速失败并返回结构化恢复建议。
|
||||
|
||||
## B 层：会话安全
|
||||
|
||||
- 使用 profile 驱动默认值（`model`、`reasoning_effort`、`infinite_sessions`）。
|
||||
- 请求未知 profile 时自动回退到安全默认 profile。
|
||||
- 每个 chat 使用确定性 workspace 路径隔离。
|
||||
|
||||
**落地建议**
|
||||
- 增加 `AGENT_PROFILE`，未知值回退 `default`。
|
||||
- 长任务默认开启 `infinite_sessions`。
|
||||
|
||||
## C 层：工具调用安全
|
||||
|
||||
- 增加 `on_pre_tool_use` 做参数校验与净化。
|
||||
- 增加高风险操作 allow/deny 规则。
|
||||
- 按工具类别配置超时预算（文件/网络/命令）。
|
||||
|
||||
**落地建议**
|
||||
- 保留现有 `on_post_tool_use`。
|
||||
- 先补 `on_pre_tool_use`，再补 `on_error_occurred`。
|
||||
|
||||
## D 层：恢复安全
|
||||
|
||||
- 仅对幂等操作重试，且有次数上限。
|
||||
- 区分可恢复/不可恢复错误。
|
||||
- 提供确定性降级输出（摘要 + 限制说明）。
|
||||
|
||||
**落地建议**
|
||||
- 按错误类型配置重试策略。
|
||||
- 统一输出“成功了什么 / 失败了什么 / 下一步”。
|
||||
|
||||
---
|
||||
|
||||
## 3）友好性模型（UX 合约）
|
||||
|
||||
## A. 歧义先澄清
|
||||
|
||||
通过 `on_user_input_request` 处理：
|
||||
- 约束缺失（范围、目标路径、输出格式）
|
||||
- 高风险动作（删除/迁移/覆盖）
|
||||
- 用户指令互相冲突
|
||||
|
||||
**规则**：一次提问给出有限选项，避免反复追问。
|
||||
|
||||
## B. 进度可见
|
||||
|
||||
按阶段发状态：
|
||||
1. 上下文检查
|
||||
2. 规划/分析
|
||||
3. 工具执行
|
||||
4. 验证
|
||||
5. 结果输出
|
||||
|
||||
**规则**：超过 8 秒不能无状态输出。
|
||||
|
||||
## C. 失败友好
|
||||
|
||||
每次失败都要包含：
|
||||
- 失败点
|
||||
- 简短原因
|
||||
- 已完成部分
|
||||
- 下一步可执行建议
|
||||
|
||||
## D. 输出可读
|
||||
|
||||
统一最终输出结构：
|
||||
- `Outcome`
|
||||
- `Changes`
|
||||
- `Validation`
|
||||
- `Limitations`
|
||||
- `Next Step`
|
||||
|
||||
---
|
||||
|
||||
## 4）高价值增强项（优先级）
|
||||
|
||||
## P0（立即）
|
||||
|
||||
1. `on_user_input_request` + 默认答复策略
|
||||
2. `on_pre_tool_use` 参数检查 + 风险闸门
|
||||
3. 阶段化状态事件
|
||||
|
||||
## P1（短期）
|
||||
|
||||
4. 错误分类 + 重试策略（`network/provider/tool/validation`）
|
||||
5. profile 化 session 工厂 + 安全回退
|
||||
6. 最终输出质量门（结构校验）
|
||||
|
||||
## P2（中期）
|
||||
|
||||
7. 传输配置能力（`cli_url/use_stdio/port`）
|
||||
8. Azure provider 支持完善
|
||||
9. foreground session 生命周期能力（高级多会话）
|
||||
|
||||
---
|
||||
|
||||
## 5）建议新增 valves
|
||||
|
||||
- `AGENT_PROFILE`: `default | builder | analyst | reviewer`
|
||||
- `ENABLE_USER_INPUT_REQUEST`: `bool`
|
||||
- `DEFAULT_USER_INPUT_ANSWER`: `str`
|
||||
- `TOOL_CALL_TIMEOUT_SECONDS`: `int`
|
||||
- `MAX_RETRY_ATTEMPTS`: `int`
|
||||
- `ENABLE_SAFE_TOOL_GUARD`: `bool`
|
||||
- `ENABLE_PHASE_STATUS_EVENTS`: `bool`
|
||||
- `ENABLE_FRIENDLY_FAILURE_TEMPLATE`: `bool`
|
||||
|
||||
---
|
||||
|
||||
## 6）故障应对手册（实用）
|
||||
|
||||
## 场景 A：Provider 超时
|
||||
|
||||
- 若请求幂等，重试一次。
|
||||
- 仍超时则降低 reasoning 强度。
|
||||
- 返回简洁降级结果并保留已有中间成果。
|
||||
|
||||
## 场景 B：工具参数不匹配
|
||||
|
||||
- 在 `on_pre_tool_use` 阻断。
|
||||
- 可恢复则提一个澄清问题。
|
||||
- 不可恢复则跳过工具并说明影响。
|
||||
|
||||
## 场景 C：输出过大
|
||||
|
||||
- 大输出落盘到 workspace 文件。
|
||||
- 返回文件路径 + 简要摘要。
|
||||
- 避免把超大内容直接刷屏。
|
||||
|
||||
## 场景 D：用户指令冲突
|
||||
|
||||
- 明确指出冲突点。
|
||||
- 给 2-3 个固定选项。
|
||||
- 用户选定后再继续。
|
||||
|
||||
---
|
||||
|
||||
## 7）建议监控指标
|
||||
|
||||
- 会话成功率
|
||||
- 工具调用成功率
|
||||
- 首次失败后的恢复率
|
||||
- 澄清率 vs 幻觉率
|
||||
- 首次可用输出耗时
|
||||
- 用户不满意信号（如“不是我要的”）
|
||||
|
||||
---
|
||||
|
||||
## 8）最小落地路径
|
||||
|
||||
1. 先加 `on_user_input_request` + `on_pre_tool_use`（功能开关控制）。
|
||||
2. 增加阶段状态事件和失败友好模板。
|
||||
3. 增加错误分类与重试策略。
|
||||
4. 增加 profile 安全回退与传输配置能力。
|
||||
5. 观察 1-2 周指标，再逐步收紧默认策略。
|
||||
|
||||
---
|
||||
|
||||
## 9）验收速查
|
||||
|
||||
- 仅在必要时澄清，不重复追问。
|
||||
- 无长时间无状态“沉默”。
|
||||
- 失败输出包含下一步动作。
|
||||
- profile/provider 配置异常不导致会话崩溃。
|
||||
- 超大输出可安全转文件。
|
||||
- 最终响应结构稳定一致。
|
||||
Reference in New Issue
Block a user