RUNBOOK：ctx-scout 子智能体（模型档位可切换）

面向日常使用者与值班者。照着做即可完成全部常见操作。配套变更档案见 SOP.md。

1. 它是什么

一个 Trae 用户级 Subagent，用独立上下文承接「读大量文件 / 多轮检索 / 只需结论」的 重活，避免这些内容污染主对话。只有一个可调开关：用哪个模型。

档位	model: 行	模型	花费
trae	model: DeepSeek-V4-Flash	Trae 内置模型	消耗 Trae 积分
proxy	无此行	主 Agent 当前模型（本机=自定义，走 token_proxy）	消耗上游 API ¥，不耗积分

• 组件：~/.trae-cn/agents/ctx-scout.md（定义）+ subagent-20261002/switch_subagent_model.py（开关）+ ~/.trae-cn/commands/subagent-mode.md（命令入口）。
• 依赖：Trae 设置 > Beta > Subagents 的「启用 Subagents 目录」必须打开。
• 异常影响：本工具只影响「Subagent 用哪个模型」；失效时主 Agent 照常工作，只是不再有独立上下文隔离。

2. 日常速查表

我要做什么	命令
看当前档位	cd ~/Documents/services/token_proxy/subagent-20261002 && python3 switch_subagent_model.py status
积分充足，用内置	python3 switch_subagent_model.py trae
积分不足，改走代理	python3 switch_subagent_model.py proxy
Trae 里一键切	输入 /subagent-mode，随后说「用内置」或「用代理」
改积分阈值习惯	无需改脚本；「何时切」由人判断，见第 4 章
换内置模型	编辑脚本顶部 BUILTIN_MODEL，或在 md 里手写 model: 行

3. 接入与使用

• 无端口、无凭据、无服务进程，纯本地文件与脚本。
• 唤起方式：不用手动点名。主 Agent 会在遇到「需大量检索、只要结论」的任务时， 按 description 自动把任务委派给 ctx-scout（也可在提示里点名「用 ctx-scout 探索」）。
• 生效时机：改完档位后，在下一个新会话 / 下一次 Subagent 调用生效；无需重启 Trae、无需重启代理。

4. 两个档位怎么选（判据）

• 积分 ≥ 200（当前 1666） → 用 trae 档：内置模型走 TRAE 通道，不花 API ¥。
• 积分 < 200 → 用 proxy 档：Subagent 仍提供上下文隔离，但模型走自定义（代理记账）。
• 积分是 Trae 账号侧数据，本机读不到，只能由你在 Trae 界面查看后手动切；本方案 刻意不做自动判断（见 SOP 第 1 章「硬约束」）。

5. 配置管理

• 唯一的档位开关 = ~/.trae-cn/agents/ctx-scout.md 里的 model: 行。不要手写坏 frontmatter，一律用脚本切。
• 要调整「内置模型是哪一个」：改 switch_subagent_model.py 顶部常量 BUILTIN_MODEL（注释标了取值来源：Trae 官方文档《子智能体(Subagent)》「可用模型」表）， 再切一次 trae 档即可。
• 要调整工具的可用范围：改 md 的 tools: 行（当前 Read, Glob, Grep, Bash, WebSearch, WebFetch, Skill）。
• 新增第二个 Subagent：在 ~/.trae-cn/agents/ 再放一个 md；切换脚本用 --agent <名字> 复用于它。

6. 备份与恢复

• 本主题备份在 subagent-20261002/backup/，清单见 backup/README.md。
• 本工具自身无状态（除 model: 行）；误切档位直接再切回来即可，无需恢复备份。
• 备份用于回退文档类修改（docs/*、rule-skill-index.md），命令见 SOP 第 7 章。

7. 监控与告警

• 无监控。可用性靠一次 status 即知。
• 间接观测：切到 proxy 档后，Subagent 的请求会出现在 docs/BASELINE.md 所述的 用量数据里（token_proxy 记账）；切到 trae 档则不记账（走 TRAE 通道）。

8. 故障处置

场景 A：Subagent 完全不被调用

• 症状：让它做重检索，始终不出现 ctx-scout 卡片。
• 诊断：
• ls ~/.trae-cn/agents/ctx-scout.md — 文件是否存在；
• sed -n '1,6p' ~/.trae-cn/agents/ctx-scout.md — 首行是否 ---、是否有 name/description；
• 设置 > Beta > Subagents 开关是否打开；
• 是否开了新会话。
• 处置：缺文件 → 按 SOP 第 1 步重建；frontmatter 坏 → 从 SOP 重建；开关未开 → 打开；未开新会话 → 开一个。
• 验证：新会话里让它「总结某目录下有哪些文件、各自作用」。

场景 B：切档后仍花积分 / 仍走代理

• 症状：切到 proxy 后仍在耗积分（或反之）。
• 诊断：python3 switch_subagent_model.py status 看档位是否真的变了；sed -n '1,6p' ~/.trae-cn/agents/ctx-scout.md 看 model: 行。
• 处置：多为旧会话未刷新。开新会话再试。
• 验证：新会话里触发一次 Subagent，观察积分是否变化。

场景 C：切换脚本报错

• 症状：[错误] 未找到子智能体文件 或 ValueError。
• 诊断：ls -l ~/.trae-cn/agents/；用 python3 -c "print(open('$HOME/.trae-cn/agents/ctx-scout.md').read()[:80])" 看文件头。
• 处置：文件不存在 → 重建；frontmatter 缺首行 --- → 从 SOP 第 1 步重建（脚本只接受合法 frontmatter）。
• 验证：status 正常输出。

9. 安全与权限

• 运行身份：普通用户 rain，不需要 sudo。
• 脚本对文件的改写受限于 ~/.trae-cn/agents/ 下指定文件，采用原子写；不改动系统配置。
• ctx-scout 自身是只读子智能体（tools 不含 Write/Edit），不会改文件。

10. 容量与性能

• 无容量概念。收益方向：把主对话的探索性读取搬到独立上下文，降低主对话的 prompt 规模 （本工程成本大头集中在 ≥150k prompt 请求）。
• 已知限制：只有内置模型可选；档位不可按次切换；积分不可编程读取。

11. 附录

项	位置
Subagent 定义	~/.trae-cn/agents/ctx-scout.md
切换脚本	subagent-20261002/switch_subagent_model.py
Slash 命令	~/.trae-cn/commands/subagent-mode.md
变更档案	subagent-20261002/SOP.md
备份台账	subagent-20261002/backup/README.md

修订记录：

日期	修改人	变更内容
2026-10-02	Agent	首版：新建 ctx-scout、切换脚本与 slash 命令

---

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