Codewhale 内置 help 技能解析：零 Prompt 开销的显式路由卡片设计-港品优选

Codewhale 内置 help 技能解析：零 Prompt 开销的显式路由卡片设计

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale

Codewhale（Rust 编写的开源终端编程 Agent）随产品内置了一批可复用的SKILL.md技能包，其中help是一个刻意反直觉的存在：它不是手册，而是一张只有几十行的"路由卡片"——当用户显式询问"Codewhale 怎么用"时，它负责把问题导向安装环境中真正拥有事实的四个表面（/help、/skills、/config、doctor），而不是凭模型记忆复述文档。这篇指南将以 crates/tui/assets/skills/help/SKILL.md 为骨架，结合 docs/SKILLS.md 与crates/tui/src/skills/下的源码与测试，说明这张卡片的设计动机、完整路由规则、在 Codewhale 检出目录内外的工作方式，以及它如何被编译期测试锁定为"永不超 80 行、永不进入模型目录"的边界技能。

技能定位：路由卡片，不是手册

help技能的 frontmatter 自述极为克制：

--- name: help description: Route a "how do I use Codewhale" question to the installed help, config, and doctor surfaces instead of reciting a manual from memory. Explicit-only. invocation: explicit-only ---

其正文开篇即点明设计哲学：

Invocation：Explicit-only。这个技能是一个路由器，而不是手册。它刻意被排除在 ambient（常驻）模型目录之外，因此从不消耗 prompt 预算，也从不复述正在运行的构建版本已经暴露的文档。

在 docs/SKILLS.md 的"starter-pack parity decisions"一节中，这一决策被表述得更完整：参考技能help在 Codewhale 中被定为"有边界的explicit-only路由器，而非 ambient 手册——路由到/help、/skills、/config、doctor以及已安装的docs/树；其正文不内嵌任何手册文本"。它从第 7 代（generation 7）起随内置包发布，见 crates/tui/src/skills/system.rs 中BundledSkill { name: "help", body: HELP_BODY, introduced_in: 7 }。

为什么选择"路由"而非"复述"

事实所有权分离：Codewhale 的命令、配置键、键位绑定由各自的注册表与运行时生成，唯一权威来源是安装环境本身，而不是模型的训练记忆或另一套 harness 的惯例。卡片明确写道："不要凭另一个 harness 的记忆回答；Codewhale 的表面是不同的。"
零 ambient 成本：explicit-only意味着技能保持可按名称加载，但不会作为模型可选择项出现在目录里，也不会挤占 2 400 字符的MAX_AVAILABLE_SKILLS_CHARS预算。测试explicit_only_skills_do_not_reduce_ambient_index_capacity（crates/tui/src/skills/tests.rs）甚至向注册表塞入 10 000 个 explicit-only 技能，验证渲染结果仍不出现 "additional skills omitted" 警告行——opt-in 型强技能永远不会变成 ambient 指令。
不猜测、不编造：技能的三条 Non-goals 直接禁止粘贴手册/命令列表/设置表进上下文、禁止凭记忆回答、禁止猜测 flag、配置键或路径："读它们，或者说你没有读到。"

机制内核：`explicit-only`调用模式如何落地

help是 Codewhale 技能 frontmatter 中invocation字段的直接应用。运行时解析逻辑位于 crates/tui/src/skills/mod.rs：

pub enum SkillInvocation { ModelAndUser, ExplicitOnly, } impl SkillInvocation { fn from_frontmatter(value: Option<&str>) -> Self { match value.map(str::trim).map(|value| value.to_ascii_lowercase()) { Some(value) if value == "explicit-only" || value == "explicit_only" => { Self::ExplicitOnly } _ => Self::ModelAndUser, } } }

关键行为：

两个可接受写法：explicit-only与explicit_only都会被解析为ExplicitOnly；缺省或未知取值保持历史默认的ModelAndUser，保证兼容（对应测试missing_or_unknown_invocation_keeps_model_and_user_compatibility，见 crates/tui/src/skills/tests.rs）。
加载与目录解耦：explicit-only 技能仍可通过规范名或别名被load_skill加载（测试断言"an explicit-only skill remains loadable"），但渲染模型目录时会被过滤掉——crates/tui/src/skills/mod.rs 中render_skills_block对invocation != SkillInvocation::ExplicitOnly的条目做.filter()，并注释说明："explicit-only 技能仍可按规范名或别名加载，但绝不可作为模型可选的目录条目呈现。这使 opt-in 型强技能不会变成 ambient 指令或消耗 prompt 预算。"

在 crates/tui/assets/skills-catalog-matrix.json 中，help的目录矩阵条目与解析行为完全一致："invocation": "explicit-only"、"in_model_catalogue": false，并属于tools分层。这个 fixture 与BUNDLED_SKILLS之间的双射由 crates/tui/src/skills/catalog_matrix.rs 的测试强制锁定——内置包的任何变动都必须显式更新 fixture。

路由表：问题应该由哪个表面回答

help正文给出了唯一的权威路由顺序。它要求"从拥有该事实的表面回答"，按以下优先级：

优先级	表面	职责与用法
1	Slash 命令	`/help`列出当前构建注册的命令；`/help <command>`打印该命令的用法行。这是唯一权威命令列表，因为它由注册表生成
2	Skills	`/skills`打开管理器；`/skills inspect`打印发现模式、搜索目录与源路径；`/skill <name>`激活单个技能。文档见 docs/SKILLS.md
3	配置	`/config`是实时设置表面；配置文件键在 docs/CONFIGURATION.md，provider/模型路由在 docs/PROVIDERS.md
4	键位绑定	见 docs/KEYBINDINGS.md。没有键位绑定斜杠命令，不得发明一个
5	环境问题	`codewhale-tui doctor`报告解析后的配置路径、provider 凭证存在性（绝不输出值）与工作区状态。优先采用其输出而非推断

这套排序的深层逻辑是"谁生成谁权威"：命令列表来自命令注册表（/help的注册行为有专项验收测试，见 crates/tui/src/commands/epic_dispatch_acceptance.rs，覆盖/help config这类带参调用），技能发现信息来自注册表扫描，配置真相来自解析后的配置文档与/config，环境诊断则来自 doctor 的实测探针。文档 docs/SKILLS.md 进一步列出了/skills家族的完整命令面（/skills <prefix>前缀过滤、/skills --remote注册表列表、/skills suggest <task>任务建议、/skills sync缓存同步、/skill install|update|uninstall|trust变更操作），以及 Skills Manager 的按键布局（i导入、u更新、r移除、t信任、s切换 project/global 目标、c切换 compatible 扫描、Esc取消/关闭）。

安装环境之外

如果用户所在的目录不是Codewhale 检出（docs/通常不存在于磁盘上），卡片给出的策略是：

依靠/help、/config、doctor这三个始终存在的运行时表面；
明确说明参考文档未在本地安装，而不是假装读过或从记忆里"引用"。

在 Codewhale 检出目录中工作

当工作区本身是 Codewhale 检出时，docs/就在磁盘上，此时正确的读取工具是内置的File工具（action: "read"）——注意，卡片刻意使用当前代 CLI 的工具命名，而不是已经退役的read_file/exec_shell。约束如下：

只读取单个最相关的文件，并引用其中的具体行；
不要为了寻找上下文而扫描整个docs/树（见下节 Bounds）；
仓库维护类技能（如docs/skills/下的gh-*系列与codew-release-qa-sweep）不属于终端用户的 starter pack，不会被自动安装。

编译期测试锁定了这一点：crates/tui/src/skills/system/tests.rs 对pdf、help、delegate、best-of-n断言正文不得包含已退役工具名read_file与exec_shell，pdf技能必须使用built-in \File` tool (`action: "read"`)` 的当前措辞——帮助技能不得教用户使用已经无法分派的旧工具。

Bounds：边界与失效策略

卡片以三条边界收束行为：

每个问题一个表面：不要扫荡docs/寻找上下文。
表面优先于记忆：如果某个表面与模型的记忆不一致，以表面为准。
无解即停：如果本地没有任何表面能回答，直接说明并停止，不要发明一个 flag。

这三点与 docs/SKILLS.md 对"有界路由卡片"的定义互为印证：help的正文受一个已检查的 invariant 约束，必须保持在 80 行以内，并且必须点名/help、/skills、/config、doctor四个表面。对应测试help_is_a_bounded_explicit_only_router位于 crates/tui/src/skills/catalog_matrix.rs：

let help = registry.get("help").expect("help must be installed"); assert_eq!(help.invocation, SkillInvocation::ExplicitOnly); assert!( help.body.lines().count() < 80, "help must stay a router, not a manual: {} lines", help.body.lines().count() ); for surface in ["/help", "/skills", "/config", "doctor"] { assert!( help.body.contains(surface), "help must route to the installed {surface} surface" ); }

一旦有人在编辑SKILL.md时把手册段落粘进卡片、或删掉了某个 surface 名，cargo test会直接失败——这正是"路由卡片"约束得以长期成立的原因：它不是口头约定，而是编译进测试矩阵的边界。

小结

help是 Codewhale 技能体系中一个精悍的样板：它证明"帮助"不一定要靠塞进模型上下文的大段手册，而是可以做成一张由测试锁定的、零 prompt 开销的显式路由卡片。理解它的四个要点——explicit-only调用模式、五级路由优先级、检出目录内外的差异化策略、以及"表面优先、无解即停"的边界——也就理解了 Codewhale 把权威事实交给运行时表面而非模型记忆的整体设计取向。下次在 TUI 里键入/help、/skills或codewhale-tui doctor时，不妨想想：这张卡片正在帮你把问题交给真正知道答案的那个表面。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析