SOP：启用 ctx-scout 子智能体 + 积分门控一键切换¶
主题：
subagent-20261002｜ 变更类型：C 类（新增全局配置与工具，改变 agent 行为） 备份台账：backup/README.md
1. 背景¶
Trae 支持用 Markdown 定义 Subagent（~/.trae-cn/agents/*.md），其价值是独立上下文
窗口——把需要读大量文件 / 多轮检索的重活挡在主对话之外，直接打击本工程实测的
「成本 93% 集中在 ≥150k prompt 请求」这一项。
用户当前有 1666 Trae 积分，希望： - 积分充足时，Subagent 用 Trae 内置模型（消耗积分、走 TRAE 通道）； - 积分不足（阈值 200）时，Subagent 只保留上下文隔离价值，改用自定义模型（走本机 token_proxy 代理，消耗上游 ¥、不耗积分）。
硬约束（决定了本方案形态）：Trae 官方文档明确，Subagent 的 model 字段
「仅支持指定内置模型，不支持自定义模型」，且只能静态写死在文件里，无法按次切换；
Trae 积分是账号侧数据，本机无可编程读取入口。因此「按积分门控」只能做成
人工触发的一键开关，而不是自动判断。
2. 目标¶
- 新增一个用户级只读 Subagent
ctx-scout，默认处于 trae 档（写内置模型名）； - 提供一个幂等的一键切换脚本与 slash 命令，可在 trae 档 / proxy 档之间切换；
- 切换只改
~/.trae-cn/agents/ctx-scout.md的model:行，不动其它任何配置。
可验证状态：switch_subagent_model.py status 能正确报出当前档位；切换两次到同一档位，
第二次零变更。
3. 前置条件¶
| 项 | 要求 |
|---|---|
| Trae 开关 | 设置 > Beta > Subagents，打开「启用 Subagents 目录」；否则 agents/ 不被加载 |
| 运行环境 | 本机 python3（仅用标准库，无需 venv） |
| 目录 | ~/.trae-cn/agents/ 存在（本次已建） |
| 权限 | 以 rain 用户运行即可，无需 sudo |
4. 影响范围¶
- 主机：仅本机 192.168.31.250（rain），单机。
- 组件：新增
~/.trae-cn/agents/ctx-scout.md、~/.trae-cn/commands/subagent-mode.md； 新增脚本subagent-20261002/switch_subagent_model.py。 - 是否停服：否。不触碰 代理
token-proxy、hooks.json、user_rules现有内容（仅规则索引追加一行）。 - 窗口期：无。可在任意时刻执行；切换对在途会话无影响，下一个新会话 / Subagent 调用生效。
5. 分步操作¶
步骤 1：建用户级 Subagent 定义¶
Subagent 靠 description 被主 Agent 自动匹配调用，model 行是唯一的档位开关。
本步写入 model: DeepSeek-V4-Flash（与代理 ds 路由的 DeepSeek V4-Flash 族同款）。
坑：name 必须字母开头、只含字母数字与连字符、≤50 字符；frontmatter 必须是标准
YAML（首尾 ---、无 BOM），否则文件被静默忽略。
mkdir -p ~/.trae-cn/agents
cat > ~/.trae-cn/agents/ctx-scout.md <<'EOF'
---
name: ctx-scout
description: 只读的探索型子智能体，用于需要大量检索、读取多份文件、跨文件取证或多轮统计、但最终只需返回结论的任务……
model: DeepSeek-V4-Flash
tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, Skill
---
（系统提示词：只读、先结论后证据、限定目录检索、保持简短。全文见文件本身。）
EOF
预期：文件存在且首行为 ---。
失败判断：无 description / frontmatter 不合法 → 该 Subagent 不会被调用（见第 6 章排查）。
步骤 2：建一键切换脚本¶
脚本对 ~/.trae-cn/agents/<agent>.md 的 frontmatter 做原子改写：trae 档确保有
model: <内置模型名> 行，proxy 档删除该行。幂等（目标档已满足即零变更）。
坑：改写 frontmatter 时必须保留文件首行的 ---——拆分函数返回的「front 部分」
不含首定界符，重组时要显式补回，否则文件会坏掉、Subagent 加载失败（本次实机验证时
第一版就踩到，已修并回归）。
cd ~/Documents/services/token_proxy/subagent-20261002
chmod +x switch_subagent_model.py
python3 switch_subagent_model.py status
预期：[status] ctx-scout 当前档位 = trae（内置模型 DeepSeek-V4-Flash，消耗 Trae 积分）。
失败判断：报 未找到子智能体文件 → 第 1 步未完成或 --agent 名称不符。
步骤 3：建 slash 命令¶
让用户在 Trae 里 /subagent-mode 一键触发脚本，命令正文只做「意图 → 参数」映射，
不改任何文件。
cat > ~/.trae-cn/commands/subagent-mode.md <<'EOF'
---
name: "subagent-mode"
description: "切换 ctx-scout 子智能体的模型档位：积分充足用 Trae 内置，积分不足改走自定义代理模型"
---
（正文：用户意图映射 trae/proxy/status，运行 switch_subagent_model.py，原样回报输出。）
EOF
预期：ls ~/.trae-cn/commands/subagent-mode.md 存在。slash 命令在被调用时展开、不进系统提示，无需为它开新会话。
步骤 4：切换档位（日常操作）¶
cd ~/Documents/services/token_proxy/subagent-20261002
python3 switch_subagent_model.py status # 看当前
python3 switch_subagent_model.py proxy # 积分 < 200：删除 model 行，走代理
python3 switch_subagent_model.py trae # 积分充足：写回内置模型名
预期：[完成] … 或 [跳过] 已是 …档，零变更。
失败判断：非零退出且打印 [错误] → 按提示核对文件路径。
6. 验证¶
# ① 档位正确
cd ~/Documents/services/token_proxy/subagent-20261002 && python3 switch_subagent_model.py status
# ② 幂等：同档位连切两次，第二次必须零变更
python3 switch_subagent_model.py trae && python3 switch_subagent_model.py trae # 预期第二次 [跳过]
python3 switch_subagent_model.py proxy && python3 switch_subagent_model.py proxy # 预期第二次 [跳过]
# ③ 文件未损坏：首行为 --- 、含 name/description
sed -n '1,6p' ~/.trae-cn/agents/ctx-scout.md
离线用例已在实机跑通 10 项（见附录）。真机端到端验证（需用户动作）：
- 设置 > Beta 打开「启用 Subagents 目录」；
- 开新会话；
- 让它做一件「读多份文件、只要结论」的事，观察是否出现
ctx-scout子智能体卡片。
7. 回滚¶
本变更全部新增，回滚即删除新增文件，不改回任何既有配置：
rm -f ~/.trae-cn/agents/ctx-scout.md # 移除 Subagent
rm -f ~/.trae-cn/commands/subagent-mode.md # 移除 slash 命令
rm -rf ~/Documents/services/token_proxy/subagent-20261002 # 移除脚本与档案（含备份）
若是文档类修改（docs/HANDOFF.md / docs/PROJECT-MAP.md / docs/SOP.md /
~/.trae-cn/user_rules/rule-skill-index.md）需回退，用同目录下的备份覆盖：
cp -p <主题>/backup/docs/HANDOFF.md.bak.<原时间戳> ~/Documents/services/token_proxy/docs/HANDOFF.md
cp -p <主题>/backup/docs/PROJECT-MAP.md.bak.<原时间戳> ~/Documents/services/token_proxy/docs/PROJECT-MAP.md
cp -p <主题>/backup/docs/SOP.md.bak.<原时间戳> ~/Documents/services/token_proxy/docs/SOP.md
cp -p <主题>/backup/trae-cn/user_rules/rule-skill-index.md.bak.<原时间戳> ~/.trae-cn/user_rules/rule-skill-index.md
备份存放位置与清单见 backup/README.md。
回滚后验证：~/.trae-cn/agents/ 下无 ctx-scout.md；开新会话不再出现该 Subagent。
注意：回退规则文件后需再开一次新会话（规则进每轮前缀）。
8. 风险说明¶
| 风险 | 缓解 |
|---|---|
| 阈值（200）与本机实际积分口径可能不同；积分无法自动读取 | 阈值由人判断，切换为人工一键操作，不存在「自动切错」 |
| 误以为切档立即生效 | 脚本输出与本文均提示：下一个新会话 / Subagent 调用才生效；无需重启代理 |
| 脚本改写 frontmatter 写坏文件 | 原子写（临时文件 + os.replace）；离线 10 项回归含「首行保留 / 幂等 / 未知对象报错」 |
子智能体 description 过宽导致误触发 |
描述已限定为「只读、需大量检索且只需结论」，并写明「不用于改文件/变更任务」 |
| 多档位并存造成状态发散 | 只有 model: 行一个开关，同一时刻只有一个档位；不存在两份文件 |
附录：离线验证用例（实机跑通 10 项）¶
| # | 用例 | 预期 | 结果 |
|---|---|---|---|
| 1 | 初始 status |
trae / DeepSeek-V4-Flash | 通过 |
| 2 | 重复 trae |
[跳过] 零变更 |
通过 |
| 3 | proxy |
删除 model 行，首行 --- 保留 |
通过 |
| 4 | 落盘校验 | 行数 26、frontmatter 完整 | 通过 |
| 5 | status |
proxy | 通过 |
| 6 | 重复 proxy |
[跳过] 零变更 |
通过 |
| 7 | trae 还原 |
写回 model 行 | 通过 |
| 8 | 还原后 frontmatter | 含 model: DeepSeek-V4-Flash |
通过 |
| 9 | --agent no-such |
[错误] + exit 2 |
通过 |
| 10 | 正文完整性 | 末行未丢失 | 通过 |
来源：
/home/rain/Documents/services/token_proxy/subagent-20261002/SOP.md｜ 最后更新：2026-10-02 19:21（由build/sync.py同步，请勿在站点侧修改）