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/CodewhaleCodewhaleRust 编写的开源终端编程 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 ---其正文开篇即点明设计哲学InvocationExplicit-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_capacitycrates/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.rspub enum SkillInvocation { ModelAndUser, ExplicitOnly, } impl SkillInvocation { fn from_frontmatter(value: Optionstr) - 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正文给出了唯一的权威路由顺序。它要求从拥有该事实的表面回答按以下优先级优先级表面职责与用法1Slash 命令/help列出当前构建注册的命令/help command打印该命令的用法行。这是唯一权威命令列表因为它由注册表生成2Skills/skills打开管理器/skills inspect打印发现模式、搜索目录与源路径/skill name激活单个技能。文档见 docs/SKILLS.md3配置/config是实时设置表面配置文件键在 docs/CONFIGURATION.mdprovider/模型路由在 docs/PROVIDERS.md4键位绑定见 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_shellpdf技能必须使用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.rslet 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技能本身不需要配置但它路由到的技能发现机制受配置控制相关键在 docs/CONFIGURATION.md 有完整说明skills_dir字符串可选默认~/.codewhale/skills每个技能是包含SKILL.md的目录。工作区局部的.agents/skills或./skills存在时优先运行时还会发现全局 agentskills.io 兼容的~/.agents/skills与更广的 Claude 生态~/.claude/skills。首次启动会安装版本化的内置技能包。只有Codewhale 自有根workspace/.codewhale/skills与~/.codewhale/skills是可写安装/导入目标兼容 harness 根保持只读。[skills].scan_codewhale_only布尔默认false为true时会话技能发现跳过.claude/skills、.opencode/skills、.cursor/skills、~/.agents/skills等跨工具根但仍扫描自有根与显式skills_dir。[skills].registry_url/[skills].max_install_size_bytes可选供/skills --remote、/skills suggest task、/skills sync与/skill install|update使用默认管理器打开路径不接触注册表。想深入了解技能系统本身推荐按此顺序阅读先是本文主题 crates/tui/assets/skills/help/SKILL.md然后是其路由目标总览 docs/SKILLS.md架构四层、审计状态、.installed-from/.trusted来源标记与包摘要安全、配置面 docs/CONFIGURATION.md以及决定help是否进入模型目录的目录矩阵 crates/tui/assets/skills-catalog-matrix.json。技能如何被编译进二进制的入口在 crates/tui/src/skills/system.rsconst HELP_BODY: str include_str!(../../assets/skills/help/SKILL.md);加载与渲染逻辑在 crates/tui/src/skills/mod.rs。小结help是 Codewhale 技能体系中一个精悍的样板它证明帮助不一定要靠塞进模型上下文的大段手册而是可以做成一张由测试锁定的、零 prompt 开销的显式路由卡片。理解它的四个要点——explicit-only调用模式、五级路由优先级、检出目录内外的差异化策略、以及表面优先、无解即停的边界——也就理解了 Codewhale 把权威事实交给运行时表面而非模型记忆的整体设计取向。下次在 TUI 里键入/help、/skills或codewhale-tui doctor时不妨想想这张卡片正在帮你把问题交给真正知道答案的那个表面。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考