[codex] Refine BetterGPT skill routing

[XiXiphus]

重构 BetterGPT：对齐 Codex 的轻量路由层

摘要

• 把 BetterGPT 技能包从臃肿的单体指令，精简成轻量入口路由 + 若干聚焦的子技能。
• 让 subagent 编排与 Codex 支持的代理类型（default、explorer、docs_researcher、reviewer、worker）对齐，通过 intent mapping 把旧版框架标签映射过去。
• 收紧 Trellis、前端清理和语言规则：范围内的低风险修复本轮就修，不再误判 hook / runtime 状态。

背景与动机

旧版 BetterGPT 更像一个通用个人提示包，放在当前 Codex 运行时里反复出现这些问题：

问题	影响
技能文件臃肿，路由细节重复	加载时更容易占满上下文
BetterSubagents 把 trellis-check 等标签当成可调用的 agent_type	与 spawn_agent 实际能力对不上（只支持 default / explorer / docs_researcher / reviewer / worker）
Trellis 检查混用项目文件、Codex 集成文件和 hook 运行时	hook 健康状态误报
BetterLanguage 的 banned-phrase policy	正常协作用语也被殃及
明显低风险修复推到"下一轮"	用户被拖成多轮追问
用户级文档校准写进技能路由	应该放在用户 AGENTS.md，不该混在技能逻辑里

变更内容

BetterGPT（入口路由）

• BetterGPT 只做入口路由，frontmatter 的 description 保持简短、以路由为导向。
• 入口纪律：读本地指令 → 最小正确修改 → 把范围内的明显修复做完 → 窄范围验证。
• 用户级官方文档 / 高级用户校准挪出技能，归入用户 AGENTS.md。

改前 → 改后

• 大而全的单体 → 轻量路由，和子技能冲突更少。
• "下轮再修" → 范围内明确修复本轮就修。

BetterLanguage

• 用 conversation-pragmatics.md 替代僵硬的 banned-phrase 做法。
• 保留：内部技术工作以英文为主；面向用户的输出用简洁中文；不翻译代码、命令、日志、路径、API、产品名。

	改前（Bad Case）	改后（Now）
用语策略	正常有用的中文短语被一律禁用	代理自己判断措辞是否推进工作；避免死板模板，同时保持回答清晰

BetterSubagents

• 编排和 Codex 可调用的代理类型对齐。
• 旧版 framework-level labels 当作 intent，不作为 agent_type 传进去。
• 增加 runtime constraints：agents.max_depth = 1 时，subagent 不能再 spawn subagent。
• 增加 takeover behavior：subagent 或 black-box test 暴露出明确、范围内低风险修复时，主代理直接修，而不是只报问题。

Intent 映射

旧标签	映射到
code-mapper	explorer
search-specialist	explorer 或轻量 default
frontend-developer	worker + BetterFrontend
refactoring-specialist	worker + BetterVibe
browser-debugger	主代理复现；只读证据 → explorer
trellis-implement	worker + BetterTrellis
trellis-check	reviewer + BetterTrellis
trellis-research	explorer 或 docs_researcher

	改前（Bad Case）	改后（Now）
标签处理	trellis-check / frontend-developer 直接传给 spawn_agent	标签 → intent → 当前可调用的代理类型

BetterTrellis

• 阶段检测和命令罗列分开。
• 分项报告：Trellis 基础配置、Codex 集成文件、hook 配置是否存在、hook runtime 验证。
• 当前命令词表：$start、continue、$finish-work、record-session。

	改前（Bad Case）	改后（Now）
hook 证据	生成的 .codex/* 被当作 hook 已在运行	文件存在和运行时行为分开报告

BetterFrontend

• 聚焦可见产品质量：UI 上不能留开发者批注、占位说明、可见 TODO、演示式表面。
• 清理默认：保留 UI 语言；本地清理不搜网；小 diff；line budget max(原行数 + 80, 原行数 × 2)，除非用户要求重设计。
• 静态交付检查：visible text leakage；仪表盘反模式（装饰渐变、模糊、重阴影、面板圆角 > 8px）。

	改前（Bad Case）	改后（Now）
UI 表面	实现备注漏到用户可见页面	UI 视为产品表面，不是开发意图展示
清理范围	40 行仪表盘任务膨胀到 351 再 252 行，只为去掉 TODO/占位	显式触发 114 行；隐式触发 88 行；不切换 UI 语言、不加框架依赖

BetterVibe

• 范围限于边界决策：表现层、领域逻辑、持久化、跨层契约。
• 项目规格（尤其 Trellis spec）优先于打包参考材料。

	改前（Bad Case）	改后（Now）
边界	UI/后端以"还能用"为由承担过多职责	最小有用边界修正，而不是默认做架构

仓库改动

• 优化后的本地 BetterGPT 包同步到 skills/BetterGPT。
• BetterLanguage/references/banned-phrases.md → conversation-pragmatics.md。
• 更新 tests/test_skill_repo.py 中的预期文件列表。

测试计划

• diff -qr — 本地安装的 BetterGPT 和仓库副本一致
• frontmatter description 长度在预算内（各技能约 ≤ 33 词）
• 在 /home/hpcdudu/Documents/bettergpt-blackbox-lab 搭建 black-box lab（git init，无 remote）

场景

• 直接修 Python — apply_discount + python -m unittest tests/test_calculator.py
• 显式前端清理 — $better-frontend，仪表盘 ≤ 114 行，可见文本 / CSS 检查
• 隐式前端清理 — 无技能标签，88 行仪表盘，泄漏 / 依赖 / 静态检查
• BetterLanguage — 「收口」「如果需要的话」不再绝对禁用
• BetterTrellis — 只有 .trellis/config.yaml 和 spec 时，不声称 hook 已生效
• BetterVibe — 在 Trellis spec 下将后端 HTML 渲染标为最小边界问题
• BetterSubagents — 旧标签映射到可调用类型；保留 max_depth = 1
• 默认校准 — 区分未验证约束、高级用户样本、用户意图、对齐判断、需实时验证项

命令

python3 -m unittest tests.test_skill_repo
python3 -m unittest discover -s tests
# black-box lab
python3 -m unittest discover -s tests
wc -l web/dashboard.html
rg <visible-leakage-patterns>
git diff --check

结果： 仓库测试 35/35 通过；black-box lab 2/2 通过。

权衡

subagent 映射规则在 BetterSubagents/SKILL.md、agent-registry.md、dispatch-rules.md 中故意重复，这样常见路径不用加载深层引用也能走通；未来代理类型变更需要同步更新这三处。