c6279240b9
- 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
4.8 KiB
4.8 KiB
🧭 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. 进度可见
按阶段发状态：
- 上下文检查
- 规划/分析
- 工具执行
- 验证
- 结果输出
规则：超过 8 秒不能无状态输出。
C. 失败友好
每次失败都要包含：
- 失败点
- 简短原因
- 已完成部分
- 下一步可执行建议
D. 输出可读
统一最终输出结构：
OutcomeChangesValidationLimitationsNext Step
4）高价值增强项（优先级）
P0（立即）
on_user_input_request+ 默认答复策略on_pre_tool_use参数检查 + 风险闸门- 阶段化状态事件
P1（短期）
- 错误分类 + 重试策略（
network/provider/tool/validation） - profile 化 session 工厂 + 安全回退
- 最终输出质量门（结构校验）
P2（中期）
- 传输配置能力（
cli_url/use_stdio/port） - Azure provider 支持完善
- foreground session 生命周期能力（高级多会话）
5）建议新增 valves
AGENT_PROFILE:default | builder | analyst | reviewerENABLE_USER_INPUT_REQUEST:boolDEFAULT_USER_INPUT_ANSWER:strTOOL_CALL_TIMEOUT_SECONDS:intMAX_RETRY_ATTEMPTS:intENABLE_SAFE_TOOL_GUARD:boolENABLE_PHASE_STATUS_EVENTS:boolENABLE_FRIENDLY_FAILURE_TEMPLATE:bool
6）故障应对手册（实用）
场景 A：Provider 超时
- 若请求幂等，重试一次。
- 仍超时则降低 reasoning 强度。
- 返回简洁降级结果并保留已有中间成果。
场景 B：工具参数不匹配
- 在
on_pre_tool_use阻断。 - 可恢复则提一个澄清问题。
- 不可恢复则跳过工具并说明影响。
场景 C：输出过大
- 大输出落盘到 workspace 文件。
- 返回文件路径 + 简要摘要。
- 避免把超大内容直接刷屏。
场景 D：用户指令冲突
- 明确指出冲突点。
- 给 2-3 个固定选项。
- 用户选定后再继续。
7）建议监控指标
- 会话成功率
- 工具调用成功率
- 首次失败后的恢复率
- 澄清率 vs 幻觉率
- 首次可用输出耗时
- 用户不满意信号（如“不是我要的”）
8）最小落地路径
- 先加
on_user_input_request+on_pre_tool_use（功能开关控制）。 - 增加阶段状态事件和失败友好模板。
- 增加错误分类与重试策略。
- 增加 profile 安全回退与传输配置能力。
- 观察 1-2 周指标，再逐步收紧默认策略。
9）验收速查
- 仅在必要时澄清，不重复追问。
- 无长时间无状态“沉默”。
- 失败输出包含下一步动作。
- profile/provider 配置异常不导致会话崩溃。
- 超大输出可安全转文件。
- 最终响应结构稳定一致。