SOP：新增用户级 Subagent `web-scout`（浏览器/网页取证专用，只读）¶

主题：web-scout-20261002 ｜变更类型：C 类（新增全局配置，改变 agent 行为）主机：本机 192.168.31.250（rain），单机｜备份台账：backup/README.md 姊妹主题：subagent-20261002（ctx-scout，只读探索型）

1. 背景¶

主对话直接操作浏览器或抓取网页时，原始输出（整页快照 / 整页 DOM / 整页 markdown）全部进入主上下文，并在后续每一轮被重放——这是本工程实测"成本 93% 集中在 ≥150k prompt" 的直接来源之一。

已上线的 ctx-scout 能隔离「读文件 / 多轮检索」，但它的 tools 行不含浏览器能力。本次验证确认了两条事实（官方文档 + 本机实测）：

Trae Subagent 的 tools 是固定白名单（Bash/Edit/Glob/Grep/Read/Skill/TodoWrite/ WebFetch/WebSearch/Write/LSP），没有浏览器工具；扩展只能经 MCP： mcpServers: 字段 + tools: mcp__<server>__<tool>；
本机浏览器工具（browser_* / external_browser_*，共 40+ 个）只在 Exec 内可用 （await tools.browser_navigate(...)），且本机 MCP server 名为 integrated_code_mode；在 Exec 内读取 ALL_TOOLS 已实测确认这些浏览器工具确在列表内。

因此新增一个专用于网页取证的只读 Subagent web-scout，只挂 Exec，把网页重活挡在主对话之外。

为什么不直接给 ctx-scout 挂 Exec：Exec 内部 ALL_TOOLS 含 Write / edit_file_update / delete_file / run_command，挂上即击穿 ctx-scout 的只读定位（其全部价值就在只读）。故两者分离，各自最小权限。

2. 目标¶

新增 ~/.trae-cn/agents/web-scout.md，可被主 Agent 按 description 自动委派；
它能在自己的独立上下文里完成「打开网页 → 多步交互 → 提取数据 → 只回结论」；
默认 trae 档（model: DeepSeek-V4-Flash，消耗 Trae 积分），可用既有脚本一键切 proxy 档。

可验证状态：switch_subagent_model.py status --agent web-scout 正确报档位；真机开新会话后出现 web-scout 子智能体卡片并能返回网页结论（见第 6 章）。

3. 前置条件¶

项	要求
Trae 开关	设置 > Beta > Subagents，`启用 Subagents 目录`必须打开（与 `ctx-scout` 同一开关）
依赖	无新依赖；浏览器能力由内置 `integrated_code_mode` MCP 提供，无需安装 Playwright
运行环境	本机 `python3`（复用既有 `switch_subagent_model.py`，仅标准库）
权限	以 `rain` 运行，无需 sudo

4. 影响范围¶

主机：仅本机，单机。是否停服：否。窗口期：无，任意时刻可执行。
新增：~/.trae-cn/agents/web-scout.md、本主题目录（SOP / RUNBOOK / backup）。
修改：docs/PROJECT-MAP.md（2 处）、docs/HANDOFF.md、~/.trae-cn/commands/subagent-mode.md。
不触碰：token_proxy 代理、hooks.json、user_rules、~/.trae-cn/agents/ctx-scout.md。
生效时机：下一个新会话（Subagent 定义在会话启动时加载）。

5. 分步操作¶

步骤 1：新建 Subagent 定义¶

tools 只给两项：Skill（按需加载 TRAE-browseruse 指南）与 mcp__integrated_code_mode__Exec（浏览器工具的唯一入口）；mcpServers 声明该 MCP Server。 只读与「禁止写文件/执行命令」由系统提示词硬约束——因为 Exec 内部能力无法用 tools 行收窄。

cat > ~/.trae-cn/agents/web-scout.md <<'EOF'
---
name: web-scout
description: 只读的网页取证子智能体。……（触发条件：打开网页 / 抓取网页 / 浏览器多步交互且只要结论）
model: DeepSeek-V4-Flash
tools: Skill, mcp__integrated_code_mode__Exec
mcpServers:
 - integrated_code_mode
---
（系统提示词：只读红线、必须用 Exec 调 browser_*、批量 evaluate、先结论后证据、遇登录/验证码即停）
EOF

坑： - name 须字母开头、只含字母数字与连字符、≤50 字符；frontmatter 必须是标准 YAML、首尾 ---、无 BOM，否则文件被静默忽略； - mcpServers 的名称必须与 Trae 中已启用的一致（本机实测为 integrated_code_mode）； - 系统提示词越短调用成本越低，只写边界与输出格式，不写教程。

正本以文件 ~/.trae-cn/agents/web-scout.md 为准。

步骤 2：备份将被修改的既有文档¶

高危：下列文件将被覆盖式编辑，先备份（位置与命名见 backup/README.md）。

D=~/Documents/services/token_proxy/web-scout-20261002
TS=$(date +%Y%m%d-%H%M%S)
mkdir -p "$D/backup/docs" "$D/backup/trae-cn/commands"
cp -p ~/Documents/services/token_proxy/docs/PROJECT-MAP.md "$D/backup/docs/PROJECT-MAP.md.bak.$TS"
cp -p ~/Documents/services/token_proxy/docs/HANDOFF.md    "$D/backup/docs/HANDOFF.md.bak.$TS"
cp -p ~/.trae-cn/commands/subagent-mode.md                "$D/backup/trae-cn/commands/subagent-mode.md.bak.$TS"
chmod 600 "$D"/backup/docs/*.bak.* "$D"/backup/trae-cn/commands/*.bak.*

预期：3 个 .bak.<时间戳> 文件、权限 600。失败判断：任一 cp 非 0 → 停止，勿继续编辑。

步骤 3：把 `web-scout` 登记进项目地图¶

docs/PROJECT-MAP.md 两处：① 第 2 节「装载来源」的路径列表，在 ~/.trae-cn/agents/ctx-scout.md 后补 ~/.trae-cn/agents/web-scout.md； ② 第 3 节项目卡片表新增一行 web-scout-20261002/（说明：网页取证 Subagent 上线）。

grep -n "ctx-scout\|web-scout" ~/Documents/services/token_proxy/docs/PROJECT-MAP.md

预期：能同时看到 ctx-scout.md 与新增的 web-scout.md 两处引用。

步骤 4：让档位命令支持 `web-scout`¶

switch_subagent_model.py 已支持 --agent（无需改脚本）；只需在 slash 命令正文补一句说明，使 /subagent-mode 也能切换 web-scout。

grep -n "agent" ~/.trae-cn/commands/subagent-mode.md

预期：正文出现 --agent web-scout 的用法说明。slash 命令只在被调用时展开，改完无需开新会话。

6. 验证¶

# ① frontmatter 合法：首行为 ---，且含四个关键字段
sed -n '1,8p' ~/.trae-cn/agents/web-scout.md
grep -c "^name:\|^description:\|^tools:\|^mcpServers:" ~/.trae-cn/agents/web-scout.md   # 预期 4

# ② 档位可读（复用既有脚本）
cd ~/Documents/services/token_proxy/subagent-20261002
python3 switch_subagent_model.py status --agent web-scout   # 预期 trae / DeepSeek-V4-Flash

真机端到端验证（需用户动作）：

确认设置 > Beta > Subagents 开关为开；
开新会话；
让它做一件「打开某网页并把关键信息带回来」的事，观察是否出现 web-scout 子智能体卡片。

本次仍待实机确认的 3 点（未确认前不得声称路径 A 完全打通）：

#	待确认项	判据
1	子智能体的 Exec 是否同样暴露 `browser_*`	新会话里让它打开一个页面，能返回快照即成立
2	是否与主对话共享同一浏览器会话（tab / 登录态）	观察是否影响主对话正在用的 tab
3	`mcpServers` 名称是否需要带项目前缀	若子智能体报「MCP 不可用」，改填带前缀的实例名

7. 回滚¶

# ① 删除新增的 Subagent（回滚即失效于下一个新会话）
rm -f ~/.trae-cn/agents/web-scout.md

# ② 用备份覆盖 3 份被修改的既有文档（<TS> 取步骤 2 的时间戳）
D=~/Documents/services/token_proxy/web-scout-20261002
cp -p "$D/backup/docs/PROJECT-MAP.md.bak.<TS>"                       ~/Documents/services/token_proxy/docs/PROJECT-MAP.md
cp -p "$D/backup/docs/HANDOFF.md.bak.<TS>"                           ~/Documents/services/token_proxy/docs/HANDOFF.md
cp -p "$D/backup/trae-cn/commands/subagent-mode.md.bak.<TS>"         ~/.trae-cn/commands/subagent-mode.md

# ③（可选）删除本主题目录
rm -rf ~/Documents/services/token_proxy/web-scout-20261002

回滚后验证：ls ~/.trae-cn/agents/ 中不再有 web-scout.md；PROJECT-MAP.md 不含 web-scout。 备份存放位置与清单见 backup/README.md；删除由用户对照该表自行决定。

回滚触发条件（任一达标即回滚）：① 真机验证出现子智能体无法返回结果且原因不可修； ② 子智能体越权写文件或执行变更命令；③ 与主对话浏览器会话冲突导致主流程受阻。

8. 风险说明¶

风险	缓解
Exec 是万能跳板：其内部含写文件 / 跑命令能力，`tools` 行无法收窄	系统提示词硬性禁止写文件与变更命令；`web-scout` 与只读的 `ctx-scout` 分离，不污染后者；本次不授予主对话额外权限
子智能体无法处理登录/验证码	`browser_waiting_for_user_interaction` 不能在 Exec 内调用，且不在 Subagent 工具白名单；提示词要求立即中止并回报「需人工接管」，由主对话弹交互
`mcpServers` 名称或前缀不符	第 6 章第 3 项待确认；报错时改用带前缀实例名
子智能体与主对话争用同一浏览器 tab	待确认；一旦冲突，主对话改用独立 tab 或暂停并行
子智能体 `description` 过宽导致误触发	描述限定为「网页取证、只要结论」，并写明不适用登录/变更场景
本次变更改变 agent 行为，不进每轮前缀	Subagent 定义在会话启动时加载，故须开新会话验证；无需重启 Trae

附录：本次实测与决策留痕¶

项	结论
Subagent 能否用浏览器	能，但只能经 `mcpServers` + `mcp__<server>__Exec`（官方 `ide_subagents` 文档）
浏览器工具的调用位置	必须 `await tools.browser_*(...)` 在 Exec 内（`TRAE-browseruse/SKILL.md`）
本机 MCP server 名	`integrated_code_mode`（`~/.trae-cn/mcps/s_*/solo_agent/integrated_code_mode/SERVER_METADATA.json`）
Exec 内是否含浏览器工具	实测含（Exec 内读 `ALL_TOOLS`，列出 40+ 个 `browser_` 与 `external_browser_`）
与 `ctx-scout` 的关系	分离的两个 Subagent；`web-scout` 不替代 `ctx-scout`，前者管网页、后者管本地检索

附录 C：挂账 `#31` 修复（2026-10-02 第二轮）¶

C.1 背景与本次判定¶

上一轮以「子智能体只拿到 Skill」判定 web-scout 的 Exec 路径未打通，列入挂账 #31。本轮复测 仍同结论，并补做两项查证：

写法合规性：官方 docs.trae.cn/ide_subagents 明确 tools 支持 mcp__<server_name>__<tool_name> 且须配合 mcpServers 字段；本机 SERVER_METADATA.json 的 server_name 确为 integrated_code_mode。即当前写法的形式与官方一致，问题不在拼写或字段名。
行为验证（本轮新增）：派 web-scout 执行「必须用浏览器」的任务（导航 about:blank 后取 document.title），它明确回报工具集只有 Skill，Exec / mcp__integrated_code_mode__Exec 均不存在。结论：不是「模型不会用」，而是工具确未注入。

根因假设（未确证）：integrated_code_mode 是 SOLO 模式会话内挂载的内置 server （~/.trae-cn/mcps/s_<工作区哈希>/solo_agent/integrated_code_mode/），而 Subagent 的 mcpServers 可能只识别「用户在 MCP 设置中配置的 server 名」。若如此，内置 code-mode 无法经 mcpServers 授权给 Subagent。未确证原因：无法在不重启会话的前提下取到 Trae 侧的授权解析日志。

C.2 本次改动（降级兜底 + 自检要求）¶

文件	改动	目的
`~/.trae-cn/agents/web-scout.md`	`tools` 由 `Skill, mcp__integrated_code_mode__Exec` 改为 `Skill, WebSearch, WebFetch, mcp__integrated_code_mode__Exec`	`WebSearch` / `WebFetch` 是 Subagent 文档明列的可用工具、确定可注入；即使 MCP 路径始终不通，`web-scout` 仍能承担「搜索 + 定向抓单页」的网页取证，不再是空壳
同文件正文	新增「开工前先确认实际工具集，自检时如实列名与报错原文」+「无 Exec 时降级到 `WebSearch`/`WebFetch`，并在结论首句标注降级模式」	把上一轮踩到的验证方法缺陷（凭文档推断替代实测）写成行为约束；把降级路径写死，避免它假装读到动态页面

C.3 验证¶

离线（已通过）：frontmatter 四个关键字段齐全（grep -c 得 4）；档位脚本可读（switch_subagent_model.py status --agent web-scout → trae / DeepSeek-V4-Flash）。
真机（待新会话，需用户动作）：Subagent 定义在会话启动时加载，本轮改动必须开新会话才生效。新会话里派一次 web-scout 做「打开某页并带回关键信息」： ① 若回报「降级模式」且给出可核对的网页事实 → 兜底路径成立； ② 若同时出现 Exec → MCP 路径也通，#31 可结案； ③ 若仍旧只有 Skill → 说明内置联网工具也未注入，需转查 Beta「Subagents 目录」开关与 Trae 版本。

C.3.1 真机验证结果（2026-10-02 22:20 新会话，已执行）¶

派一次 web-scout 打开 https://example.com 并自报工具集，实测：

降级兜底成立（对应判据 ①）：子智能体实际工具集为 Skill + ToolSearch + DeferExecuteTool （后两者为本机 Trae 的工具延迟加载机制）；经 ToolSearch 加载、DeferExecuteTool 调用了 WebSearch / WebFetch，成功取回该页正文首段。即内置联网工具确实注入且可用， web-scout 不再是空壳。
MCP / Exec 路径仍未打通（判据 ② 不成立）：工具清单中没有 Exec / mcp__integrated_code_mode__Exec，无任何 browser_*；子智能体自报「未通过任何方式拿到它们」。
根因收窄：tools 行中的内置工具名（WebSearch / WebFetch）被正确解析并注入，而 mcp__<server>__<tool> 形式的条目未被解析。故问题不在 mcpServers 字段整体被忽略，而在 MCP 前缀工具名的授权解析——与 C.1「内置 server 不可经 mcpServers 授权给 Subagent」的假设一致。
判定：#31 保持挂账，但性质由「空壳」转为「有可用降级路径」。下一步二选一：① 查 Trae 版本 / 官方 issue 确认 mcp__<server>__<tool> 写法是否支持； ② 接受降级能力并将其结案。

C.3.2 真机验证结果（2026-10-02 22:29 新会话，已执行）¶

实验②（把 mcp__<server>__<tool> 换成裸内置名）：C.3.1 后按「实验②」把 tools 行中的 mcp__integrated_code_mode__Exec 换成内置名 Exec（mcpServers 字段保留），用于判定 C.3.1 的根因推断「只是 MCP 前缀名不被解析」是否成立。当时 ~/.trae-cn/agents/web-scout.md 的 tools 行为 Skill, WebSearch, WebFetch, Exec。

新会话派一次 web-scout 做工具自检，要求如实列名、禁止按文档倒推，实测：

工具集仍恒为 5 个：直接暴露 Skill / ToolSearch / DeferExecuteTool，经 ToolSearch 加载的 WebSearch / WebFetch（与 C.3.1 完全一致）。
Exec 未出现：用 ToolSearch 以 tool_names:["Exec"] 与 queries:["Exec"] 双路径精确查询，均只返回 WebSearch/WebFetch；queries:["mcp"]、queries:["integrated_code_mode"] 同样无结果。
无任何 mcp__* / browser_*：queries:["browser"] 返回 Found 0 tool(s)。
降级链路复验通过：WebFetch 取回 example.com 正文首行，WebSearch 返回 5 条结果。

判定：实验②否证【已验证】——把 MCP 前缀名改成内置名 Exec 后仍旧不注入。根因推断再收窄【未验证】：问题不在「前缀写法」，而在 Exec 并非可经 Subagent tools 行授权/注入的工具名，且 mcpServers: integrated_code_mode 声明的该 MCP server 整体未被加载 （工具清单中无任何 mcp__* 条目）。#31 保持挂账，按 C.3.1 的路径 ① 处置：查 Trae 版本 / 官方 issue，或接受降级能力结案（降级路径已连续两轮实测可用）。

C.4 回滚¶

cp -p ~/Documents/services/token_proxy/web-scout-20261002/backup/trae-cn/agents/web-scout.md.bak.20261002-215416 \
      ~/.trae-cn/agents/web-scout.md

回滚触发条件：新会话中 web-scout 行为异常（越权写文件 / 执行变更命令 / 与主对话争用浏览器 tab）。备份位置与清单见 backup/README.md。

C.5 风险说明¶

风险	缓解
兜底路径不含 JS 渲染，SPA / 登录后页面取不到	正文要求结论首句标注降级模式，主对话据此判断是否改走主对话浏览器
根因未确证（两种写法均不注入）	已走 C.6 结案：接受降级能力、不再追查；日后若要恢复浏览器能力，按 C.6 回退表逐条还原
放开 WebFetch 会否削弱只读约束	不会：`WebSearch` / `WebFetch` 均只读；`Write` / `Edit` / `Bash` 仍未授予

C.6 结案（2026-10-02，接受降级能力）¶

决定：用户明确指示「结案」——不再追查 Exec 注入问题，接受 web-scout 的降级能力（纯联网抓取）。挂账 #31 关闭（总账「一、挂账」删除、「二、已做」#24 登记、过账记录追加一行）。

依据：两轮真机验证（C.3.1 / C.3.2）证明 mcp__<server>__<tool> 与裸内置名 Exec 两种写法均不注入；降级路径（WebSearch + WebFetch）连续两轮实测可用。

落地改动（~/.trae-cn/agents/web-scout.md）：

项	改动前	改动后
`tools`	`Skill, WebSearch, WebFetch, Exec`	`Skill, WebSearch, WebFetch`
`mcpServers`	`- integrated_code_mode`	删除（该 MCP server 整体未被加载，留着只会误导）
`description`	含「浏览器多步交互（点击、翻页、填表、登录后查看）」	改为「搜索 / 抓取静态页」，并明示降级边界（无 JS 渲染 / 无多步交互 / 无登录态、SPA 与登录后页面取不到）
正文第 3~7 条	以 Exec 内 `browser_*` 调用为主、附降级分支	收敛为「固定降级模式」3 条（路径 / 一次抓全 / 够用即停），原浏览器规范以一行指引留痕
硬约束首句	含「Exec 内部暴露写文件与执行命令，一律不得使用」	删除该句（Exec 已不存在）

副作用（正向）：安全缺口缩小——不再存在 Exec 的写文件 / 执行命令隐式能力，只读约束回归纯提示词层面；但仍不可当强隔离（WebFetch 可带出内网内容，且约束全靠提示词）。

生效条件：Subagent 定义在会话启动时加载，须开新会话生效。

若日后要恢复浏览器能力：先查 Trae 版本 / 官方 issue 确认 Subagent 的 tools 行是否支持 MCP 工具注入，再按上表左列逐条回退（原始写法已在本节留痕，无需翻备份）。

回滚：backup/trae-cn/agents/web-scout.md.bak.20261002-223656（清单见 backup/README.md）。

来源：/home/rain/Documents/services/token_proxy/web-scout-20261002/SOP.md ｜最后更新：2026-10-02 22:38（由 build/sync.py 同步，请勿在站点侧修改）

SOP：新增用户级 Subagent web-scout（浏览器/网页取证专用，只读）¶