RUNBOOK：web-scout 子智能体（网页取证专用）¶
面向日常使用者与值班者。照着做即可完成全部常见操作。变更档案见 SOP.md。 姊妹手册：
ctx-scout（本地检索专用）。
1. 服务概览¶
一个 Trae 用户级 Subagent，专用于「打开网页 / 抓取网页 / 浏览器多步交互，且只要结论」的 任务：它在独立上下文窗口里跑完浏览器操作，只把结论交回主对话，避免整页快照与 DOM 污染主对话（主对话成本的大头是每轮重放整个上下文）。
| 组件 | 位置 |
|---|---|
| Subagent 定义 | ~/.trae-cn/agents/web-scout.md |
| 档位开关（复用） | subagent-20261002/switch_subagent_model.py --agent web-scout |
| Slash 命令入口 | ~/.trae-cn/commands/subagent-mode.md |
| 浏览器能力来源 | 内置 MCP integrated_code_mode 的 Exec（await tools.browser_*） |
- 依赖：Trae 设置 > Beta > Subagents 的「启用 Subagents 目录」必须打开。
- 异常影响：本工具失效时主 Agent 照常工作，只是网页重活重新落回主对话。
- 重要性：可选优化项（非关键路径），失效不阻塞任何业务。
2. 接入与凭据¶
- 无端口、无服务进程、无凭据；纯本地 Markdown 定义 + 内置 MCP。
- 唤起方式：不用点名。主 Agent 遇到「需网页取证且只要结论」的任务时按
description自动委派；也可在提示里点名「用 web-scout 抓一下这个页面」。 - 生效时机：改定义后开新会话生效；无需重启 Trae 或代理。
3. 日常速查表¶
| 我要做什么 | 命令 |
|---|---|
| 看档位 | cd ~/Documents/services/token_proxy/subagent-20261002 && python3 switch_subagent_model.py status --agent web-scout |
| 积分充足，用内置 | python3 switch_subagent_model.py trae --agent web-scout |
| 积分不足，走代理 | python3 switch_subagent_model.py proxy --agent web-scout |
| 检查定义是否合法 | sed -n '1,8p' ~/.trae-cn/agents/web-scout.md |
| 停用它 | rm -f ~/.trae-cn/agents/web-scout.md（下一个新会话生效） |
4. 日常操作¶
- 调用：无需操作，主 Agent 自动委派；或提示中直接点名。
- 档位切换（trae 档耗 Trae 积分，proxy 档走 token_proxy 代理记账、不耗积分）：
bash cd ~/Documents/services/token_proxy/subagent-20261002 python3 switch_subagent_model.py status --agent web-scout预期：[status] web-scout 当前档位 = trae（内置模型 DeepSeek-V4-Flash，消耗 Trae 积分）。 - 临时停用：删除 md 文件即可，见第 3 章速查表。
5. 配置管理¶
- 可调项只有三处，都在
~/.trae-cn/agents/web-scout.md： model:行 —— 档位开关（用脚本改，不要手写坏 frontmatter）；tools:行 —— 当前Skill, mcp__integrated_code_mode__Exec；不要再加Write/Edit之类；- 系统提示词 —— 只读边界与输出格式；
- 不要给
web-scout挂disallowedTools来"限制只读"：Exec 内部的写能力不由tools行控制， 只能靠提示词约束 + 事后审查。 mcpServers:里的名称须与 Trae 中已启用的 MCP 名一致（当前integrated_code_mode）。
6. 备份与恢复¶
- 本工具无状态（除
model:行），误切档位再切回来即可。 - 本主题备份在
web-scout-20261002/backup/，清单见 backup/README.md； 仅用于回退本次修改的既有文档（PROJECT-MAP.md/HANDOFF.md/subagent-mode.md）。
7. 监控与告警¶
- 无监控。间接观测：切到
proxy档后，其请求会出现在 token_proxy 的用量数据里（记账）；trae档不记账（走 TRAE 通道）。 - 用法与
ctx-scout一致：判「走内置还是走代理」看logs/usage.jsonl是否新增conv_key。
8. 故障处置¶
场景 A：始终不出现 web-scout 卡片¶
症状：让它抓网页，主对话自己干了，没有子智能体卡片。
诊断
1. ls -l ~/.trae-cn/agents/web-scout.md —— 文件是否存在；
2. sed -n '1,8p' ~/.trae-cn/agents/web-scout.md —— 首行是否 ---、description 是否在；
3. 设置 > Beta > Subagents 开关是否打开；
4. 是否开了新会话。
处置：缺文件 → 按 SOP.md 第 5 章步骤 1 重建；开关未开 → 打开；未开新会话 → 开一个。 验证：新会话里说「用 web-scout 打开 example.com 并告诉我标题」。
场景 B：子智能体报「MCP 不可用 / 工具不存在」¶
症状：子智能体启动后无法调用浏览器，报错提到 Exec 或 MCP。
诊断
1. python3 switch_subagent_model.py status --agent web-scout —— 定义可解析；
2. sed -n '1,8p' ~/.trae-cn/agents/web-scout.md —— mcpServers: 与 tools: 行是否完好；
3. Trae 中该 MCP Server（integrated_code_mode）是否为启用状态。
处置：名称不符 → 改为 Trae 中实际名称（可能带项目前缀）；定义损坏 → 从 SOP 重建。 验证：新会话重试抓取。
场景 C：需要登录 / 验证码 / 安全警告¶
症状：目标是登录后页面，子智能体中途停止并回报「需要人工接管」。
诊断：这是设计内行为——browser_waiting_for_user_interaction 无法在子智能体内调用。
处置：由主对话调用浏览器工具打开同一页面并弹出「请用户接管」；用户登录后，
把结论直接交给主对话（或重新委派 web-scout，若会话状态可复用）。
验证：页面已进入登录后状态。
场景 D：子智能体越权（写了文件 / 跑了命令）¶
症状：审查发现 web-scout 期间产生了文件改动或命令执行。
诊断：Exec 内确实具备写能力，属提示词约束失效（非权限模型兜底）。 处置：① 立即回滚被改内容（见 backup/README.md）； ② 强化系统提示词中的只读红线措辞；③ 复查该轮工具审计。
9. 安全与权限¶
- 运行身份：普通用户
rain，不需要 sudo。 - 子智能体声明为只读，但技术上其 Exec 具备写文件与执行命令的能力—— 这是本方案已知的最大安全缺口，缓解措施仅为提示词约束 + 事后审查，不可当作强隔离。
- 因此不要把含凭据的页面交给它，也不要在提示词里传密码；涉及登录一律走人工接管。
10. 容量与性能¶
- 无容量概念。收益方向：把网页取证的原始输出挡在主对话之外，降低主对话 prompt 规模。
- 已知限制：① 只有内置模型可选；② 档位不可按次切换；③ 无法处理登录/验证码； ④ 与主对话的浏览器会话是否共享、是否互相干扰，尚未实测确认。
11. 附录¶
| 项 | 位置 |
|---|---|
| Subagent 定义 | ~/.trae-cn/agents/web-scout.md |
| 档位脚本 | subagent-20261002/switch_subagent_model.py |
| Slash 命令 | ~/.trae-cn/commands/subagent-mode.md |
| 变更档案 | SOP.md |
| 备份台账 | backup/README.md |
修订记录：
| 日期 | 修改人 | 变更内容 |
|---|---|---|
| 2026-10-02 | Agent | 首版：新建 web-scout，仅挂 Exec，用于网页/浏览器取证 |
来源：
/home/rain/Documents/services/token_proxy/web-scout-20261002/RUNBOOK.md｜ 最后更新：2026-10-02 21:37（由build/sync.py同步，请勿在站点侧修改）