拓冰网站定制 
如何为 context-mode 编写符合 ADR-0002 风格契约的 ctx_* 工具描述【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-modecontext-mode 通过server.registerTool()在 src/server.ts 中注册 11 个ctx_*MCP 工具每个工具的description字段都会被 Claude、GPT、Gemini、Llama 等各类宿主 LLM 在工具选择时读取。项目用 docs/adr/0002-tool-description-style.md下称 ADR-0002锁定了这些描述必须遵循的结构与用词规则并由 tests/core/server.test.ts 中名为tool description style contract (#683 ADR-0002)的静态契约测试在每次提交时逐条校验。这篇文章面向要在本仓库新增ctx_*工具或重写某个现有工具描述的开发者任务是产出一段能直接通过契约测试的描述文本。规则来源只有两处——ADR-0002 的 Decision 与 Canonical structure 章节以及契约测试的断言本身两者冲突时测试是最终裁判ADR 中也明确“this section is the source of truth”测试在每个 commit 上强制每条规则。描述写在哪个位置测试如何扫描它所有工具描述都在src/server.ts的server.registerTool()调用块内形如server.registerTool( ctx_execute, { title: ..., description: ..., // 本文要写的部分 inputSchema: ... }, ... )契约测试的提取逻辑见 tests/core/server.test.ts决定了两个硬性格式约束工具名必须是ctx_xxx形式的独立一行正则^\s*(ctx_[a-z_])\s*,\s*$紧跟在server.registerTool(之后描述是description:键下的字符串字面量模板字符串或拼接的字符串均可以扫描到下一个同缩进的inputSchema:/outputSchema:/annotations:行结束。也就是说工具名、description:起始行、inputSchema:结束行的排版不能偏离现有 11 个工具的写法否则测试的提取器直接找不到这个工具sanity 断言要求至少提取到 11 个ctx_*工具。规范结构WHEN / WHEN NOT / RETURNS / EXAMPLE除豁免工具外每个描述必须按以下模板组织模板来自 ADR-0002 的 Decision 章节1 行标题≤ 120 字符祈使句正面表述 WHEN: - 正面触发条件逐条列出 WHEN NOT: - 与兄弟工具的正面区分逐条列出 RETURNS: agent 调用后看到什么1-3 行 EXAMPLE: 一个带真实参数的规范调用各条规则对应 ADR-0002 §Canonical structure测试逐一断言章节顺序固定为WHEN - WHEN NOT - RETURNS - EXAMPLE正面选择线索必须排在负向区分之前。WHEN NOT:在工具没有兄弟工具歧义时可以省略其余章节全部必选测试对WHEN:、RETURNS:、EXAMPLE:做存在性断言。列表符号只能用 markdown 的-。1.、1-、*、•一律被拒原因是这些形式在不同 LLM 家族的 tokenizer 下表现不一致且契约要求每条 bullet 独立成立、不隐含序号顺序。章节头必须是大写 冒号、顶格写在行首测试用^([A-Z][A-Z _]):提取任何不在规范集合与豁免集合内的大写章节头都会报错错误信息会提示“把 CONCURRENCY、TIPS 之类的操作性子指导折进 WHEN:/RETURNS: 的正文里”。每个章节头下的 bullet 用两空格缩进。测试不强制缩进数LLM 对 2 与 4 空格都容忍但src/server.ts中所有已发布描述统一用两空格新描述应保持一致。章节之间空一行。一个工具一个EXAMPLE:。确有双输入形态的工具ADR 举的例子是ctx_purge的 per-session 与 per-project允许写两行相邻的EXAMPLE:但不能与其他章节交错。RETURNS:头必须独占一行正文换行缩进在下方。这是测试单独锁定的一条RETURNS: 只返回你的打印输出这类行内写法会失败必须写成RETURNS:\n 正文。注意EXAMPLE:保持行内形式是有意为之的不对称ADR 模板第 59 行即为EXAMPLE: one canonical call。一个真实例子是 src/server.ts 中ctx_search的描述节选正文省略Search a unified knowledge base with a multi-strategy ranking pipeline. ... WHEN: - You want to recall something that exists in storage (...) instead of re-reading raw sources - You have multiple related questions about the same body of knowledge — batch every question into one call - You want to scope the query to one labelled source (pass source — partial match is fine) WHEN NOT: - The data you want to query has never been stored in the knowledge base ... RETURNS: Per-query ranked sections with window-extracted snippets. ... EXAMPLE: ctx_search(queries: [root cause, proposed fix], source: issue-#683)新写描述时可以直接对照这一块的排版标题行、空行、大写章节头、两空格 bullet、RETURNS:头独占一行。禁用词与保留字ADR-0002 的 Forbidden tokens 表与测试的FORBIDDEN规则列表一致描述中不得出现禁用词原因ADR 原文口径替代写法MANDATORY:作开头开发者政策口吻不是选择线索角色定义 WHEN:章节BLOCKED保留给 ADR-0003 的 CASE B真实安全/策略限制见 docs/adr/0003-routing-deny-reasons.md工具描述里本就没有安全限制可表达删掉即可PREFER X OVER Y测试正则精确匹配PREFER THIS OVER把选择框定成取舍用正面WHEN:表述Do NOT read/use/pull/call肯定句优于否定句rubric #2改写为WHEN:/WHEN NOT:条款Never use禁止式语气改写为WHEN NOT:条款SESSION STATE子句skill/role 持久化属于 hooks/routing-block.mjs 的职责移到 routing-block 层✅/❌emoji bullet在 Llama/Gemini 家族中分词不一致且构成负样本泄漏用 prose如USE concurrency 4-8 for ...另有一条用词规则RFC 2119 的 MUST/SHOULD/MAY 层级只允许用于“调用后的义务”post-call obligations绝不用于工具选择线索。ADR 给的正例是ctx_upgrade“you MUST run the returned shell command and display the output as a checklist”——这是对 agent 的调用后契约不是选择提示。选择线索一律用WHEN:/WHEN NOT:表达。长度方面描述 SHOULD ≤ 1,000 字符硬上限 1,500。豁免与 carve-out哪些工具不受某条规则约束测试代码里的两个集合界定了豁免范围写描述前先确认你的工具属于哪一档ctx_stats、ctx_doctor、ctx_insight设计上就是一行最小描述诊断/GUI 能力不是路由目标豁免WHEN:结构要求。ctx_upgrade豁免WHEN:要求但允许MUSTpost-call obligation 规则。ctx_purge不豁免任何规则但有 allow-list 的额外章节头DESTRUCTIVE、SCOPES、CONTRACT对应测试中的ALLOWED_EXTRA_SECTIONS见 tests/core/server.test.ts。依据是审计 Probe 4 的实证对这个工具重表述框架反而保住小模型的参数保真度Haiku 上 5/5 vs 3/5。这里的DESTRUCTIVE是准确的用户侧信号与 rubric 禁止的跨 LLM 偏差式负面框架是两回事。它仍然必须满足完整的WHEN / WHEN NOT / RETURNS / EXAMPLE结构carve-out 章节只是共存。遗留别名WHEN TO USE:被接受为过渡形式ctx_index现在就用它但新工具必须用WHEN:——测试正则同时匹配两种写法而 ADR 明确要求新工具用WHEN:。如果你的新需求落在这些豁免之外比如想要一个新的章节头或一个新的豁免ADR 明确规定贡献者不能自创章节名必须开一个新 ADR 来修订本 ADR契约测试在 allow-list 更新前会失败这正是设计意图“locked to make future PRs ungameable”。操作步骤新增一个 ctx_* 工具描述在src/server.ts按现有registerTool块的排版新增你的工具server.registerTool(一行下一行ctx_your_tool,再下一个对象里写description:描述块结束于同缩进的inputSchema:行。按规范模板写描述标题一行≤ 120 字符祈使句、正面表述WHEN:下列正面触发条件-符号、两空格缩进与兄弟工具有歧义时加WHEN NOT:没有则省略RETURNS:头独占一行正文换行两空格缩进写清 agent 调用后拿回什么行内EXAMPLE: ctx_your_tool(...)一个规范调用章节之间空一行全文 ≤ 1,000 字符硬上限 1,500。自查禁用词过一遍上表七个禁用项确认没有MANDATORY:、BLOCKED、PREFER ... OVER、Do NOT ...、Never use、SESSION STATE、✅/❌MUST只出现在 post-call 义务句里。在 PR 描述中引用 ADR-0002——这是 ADR Consequences 章节对新工具的要求。运行契约测试并解读失败信息契约测试是纯静态扫描不做 LLM 调用因此反馈很快。仓库的pretest脚本会先执行完整构建npm run build只想快速校验描述风格时用文件级运行更省时间npx vitest run tests/core/server.test.ts -t tool description style contract完整回归用npm test即vitest run。测试按工具名生成describe(tool.name)分组每个失败信息都自带定位与整改方向例如禁用词命中ctx_xxx description (src/server.ts:行号) contains forbidden token MANDATORY: (rule: MANDATORY: opener). 该规则的整改说明——行号直接指向你该改的位置缺章节ctx_xxx (src/server.ts:行号) missing mandatory section WHEN: per ADR-0002 canonical structure顺序错误section WHEN NOT: appears before a sibling that should follow it并附上四个章节的实际位置值非规范大写章节uses off-spec UPPERCASE sections [TIPS] ... Fold operational sub-guidance ... into WHEN: / RETURNS: prosebullet 违规bullet uniformity violation: numeric-dot bullet (e.g. 1.) at description-line N。全部通过即说明你的描述满足 ADR-0002测试同时校验hooks/routing-block.mjs与hooks/core/routing.mjs两个提示词面如果你动了这两个文件同样的禁用词规则另加forbidden_actions、NEVER、FORBIDDEN、- NO X for Y四条也会在同一个 describe 块中执行。边界与限制结构被锁定想偏离规范结构新章节头、新豁免的唯一正路是开新 ADR 修订 ADR-0002 并同步更新测试的 allow-list测试会先失败、ADR 合并后放行。“训练者语气”的文本如THINK IN CODE、MANDATORY routing rules不属于工具描述层按 ADR 的分工应放在 hooks/routing-block.mjssystem-prompt 注入和CLAUDE.md中。重写现有工具描述时注意审计结论风格不能一刀切ctx_purge的重表述若丢了DESTRUCTIVE/SCOPES/CONTRACT信号会回归 Haiku 上的参数保真度Probe 4 数据这类 carve-out 以测试里的 allow-list 为准。【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何为 context-mode 编写符合 ADR-0002 风格契约的 ctx_* 工具描述？
如何为 context-mode 编写符合 ADR-0002 风格契约的 ctx_* 工具描述【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-modecontext-mode 通过server.registerTool()在 src/server.ts 中注册 11 个ctx_*MCP 工具每个工具的description字段都会被 Claude、GPT、Gemini、Llama 等各类宿主 LLM 在工具选择时读取。项目用 docs/adr/0002-tool-description-style.md下称 ADR-0002锁定了这些描述必须遵循的结构与用词规则并由 tests/core/server.test.ts 中名为tool description style contract (#683 ADR-0002)的静态契约测试在每次提交时逐条校验。这篇文章面向要在本仓库新增ctx_*工具或重写某个现有工具描述的开发者任务是产出一段能直接通过契约测试的描述文本。规则来源只有两处——ADR-0002 的 Decision 与 Canonical structure 章节以及契约测试的断言本身两者冲突时测试是最终裁判ADR 中也明确“this section is the source of truth”测试在每个 commit 上强制每条规则。描述写在哪个位置测试如何扫描它所有工具描述都在src/server.ts的server.registerTool()调用块内形如server.registerTool( ctx_execute, { title: ..., description: ..., // 本文要写的部分 inputSchema: ... }, ... )契约测试的提取逻辑见 tests/core/server.test.ts决定了两个硬性格式约束工具名必须是ctx_xxx形式的独立一行正则^\s*(ctx_[a-z_])\s*,\s*$紧跟在server.registerTool(之后描述是description:键下的字符串字面量模板字符串或拼接的字符串均可以扫描到下一个同缩进的inputSchema:/outputSchema:/annotations:行结束。也就是说工具名、description:起始行、inputSchema:结束行的排版不能偏离现有 11 个工具的写法否则测试的提取器直接找不到这个工具sanity 断言要求至少提取到 11 个ctx_*工具。规范结构WHEN / WHEN NOT / RETURNS / EXAMPLE除豁免工具外每个描述必须按以下模板组织模板来自 ADR-0002 的 Decision 章节1 行标题≤ 120 字符祈使句正面表述 WHEN: - 正面触发条件逐条列出 WHEN NOT: - 与兄弟工具的正面区分逐条列出 RETURNS: agent 调用后看到什么1-3 行 EXAMPLE: 一个带真实参数的规范调用各条规则对应 ADR-0002 §Canonical structure测试逐一断言章节顺序固定为WHEN - WHEN NOT - RETURNS - EXAMPLE正面选择线索必须排在负向区分之前。WHEN NOT:在工具没有兄弟工具歧义时可以省略其余章节全部必选测试对WHEN:、RETURNS:、EXAMPLE:做存在性断言。列表符号只能用 markdown 的-。1.、1-、*、•一律被拒原因是这些形式在不同 LLM 家族的 tokenizer 下表现不一致且契约要求每条 bullet 独立成立、不隐含序号顺序。章节头必须是大写 冒号、顶格写在行首测试用^([A-Z][A-Z _]):提取任何不在规范集合与豁免集合内的大写章节头都会报错错误信息会提示“把 CONCURRENCY、TIPS 之类的操作性子指导折进 WHEN:/RETURNS: 的正文里”。每个章节头下的 bullet 用两空格缩进。测试不强制缩进数LLM 对 2 与 4 空格都容忍但src/server.ts中所有已发布描述统一用两空格新描述应保持一致。章节之间空一行。一个工具一个EXAMPLE:。确有双输入形态的工具ADR 举的例子是ctx_purge的 per-session 与 per-project允许写两行相邻的EXAMPLE:但不能与其他章节交错。RETURNS:头必须独占一行正文换行缩进在下方。这是测试单独锁定的一条RETURNS: 只返回你的打印输出这类行内写法会失败必须写成RETURNS:\n 正文。注意EXAMPLE:保持行内形式是有意为之的不对称ADR 模板第 59 行即为EXAMPLE: one canonical call。一个真实例子是 src/server.ts 中ctx_search的描述节选正文省略Search a unified knowledge base with a multi-strategy ranking pipeline. ... WHEN: - You want to recall something that exists in storage (...) instead of re-reading raw sources - You have multiple related questions about the same body of knowledge — batch every question into one call - You want to scope the query to one labelled source (pass source — partial match is fine) WHEN NOT: - The data you want to query has never been stored in the knowledge base ... RETURNS: Per-query ranked sections with window-extracted snippets. ... EXAMPLE: ctx_search(queries: [root cause, proposed fix], source: issue-#683)新写描述时可以直接对照这一块的排版标题行、空行、大写章节头、两空格 bullet、RETURNS:头独占一行。禁用词与保留字ADR-0002 的 Forbidden tokens 表与测试的FORBIDDEN规则列表一致描述中不得出现禁用词原因ADR 原文口径替代写法MANDATORY:作开头开发者政策口吻不是选择线索角色定义 WHEN:章节BLOCKED保留给 ADR-0003 的 CASE B真实安全/策略限制见 docs/adr/0003-routing-deny-reasons.md工具描述里本就没有安全限制可表达删掉即可PREFER X OVER Y测试正则精确匹配PREFER THIS OVER把选择框定成取舍用正面WHEN:表述Do NOT read/use/pull/call肯定句优于否定句rubric #2改写为WHEN:/WHEN NOT:条款Never use禁止式语气改写为WHEN NOT:条款SESSION STATE子句skill/role 持久化属于 hooks/routing-block.mjs 的职责移到 routing-block 层✅/❌emoji bullet在 Llama/Gemini 家族中分词不一致且构成负样本泄漏用 prose如USE concurrency 4-8 for ...另有一条用词规则RFC 2119 的 MUST/SHOULD/MAY 层级只允许用于“调用后的义务”post-call obligations绝不用于工具选择线索。ADR 给的正例是ctx_upgrade“you MUST run the returned shell command and display the output as a checklist”——这是对 agent 的调用后契约不是选择提示。选择线索一律用WHEN:/WHEN NOT:表达。长度方面描述 SHOULD ≤ 1,000 字符硬上限 1,500。豁免与 carve-out哪些工具不受某条规则约束测试代码里的两个集合界定了豁免范围写描述前先确认你的工具属于哪一档ctx_stats、ctx_doctor、ctx_insight设计上就是一行最小描述诊断/GUI 能力不是路由目标豁免WHEN:结构要求。ctx_upgrade豁免WHEN:要求但允许MUSTpost-call obligation 规则。ctx_purge不豁免任何规则但有 allow-list 的额外章节头DESTRUCTIVE、SCOPES、CONTRACT对应测试中的ALLOWED_EXTRA_SECTIONS见 tests/core/server.test.ts。依据是审计 Probe 4 的实证对这个工具重表述框架反而保住小模型的参数保真度Haiku 上 5/5 vs 3/5。这里的DESTRUCTIVE是准确的用户侧信号与 rubric 禁止的跨 LLM 偏差式负面框架是两回事。它仍然必须满足完整的WHEN / WHEN NOT / RETURNS / EXAMPLE结构carve-out 章节只是共存。遗留别名WHEN TO USE:被接受为过渡形式ctx_index现在就用它但新工具必须用WHEN:——测试正则同时匹配两种写法而 ADR 明确要求新工具用WHEN:。如果你的新需求落在这些豁免之外比如想要一个新的章节头或一个新的豁免ADR 明确规定贡献者不能自创章节名必须开一个新 ADR 来修订本 ADR契约测试在 allow-list 更新前会失败这正是设计意图“locked to make future PRs ungameable”。操作步骤新增一个 ctx_* 工具描述在src/server.ts按现有registerTool块的排版新增你的工具server.registerTool(一行下一行ctx_your_tool,再下一个对象里写description:描述块结束于同缩进的inputSchema:行。按规范模板写描述标题一行≤ 120 字符祈使句、正面表述WHEN:下列正面触发条件-符号、两空格缩进与兄弟工具有歧义时加WHEN NOT:没有则省略RETURNS:头独占一行正文换行两空格缩进写清 agent 调用后拿回什么行内EXAMPLE: ctx_your_tool(...)一个规范调用章节之间空一行全文 ≤ 1,000 字符硬上限 1,500。自查禁用词过一遍上表七个禁用项确认没有MANDATORY:、BLOCKED、PREFER ... OVER、Do NOT ...、Never use、SESSION STATE、✅/❌MUST只出现在 post-call 义务句里。在 PR 描述中引用 ADR-0002——这是 ADR Consequences 章节对新工具的要求。运行契约测试并解读失败信息契约测试是纯静态扫描不做 LLM 调用因此反馈很快。仓库的pretest脚本会先执行完整构建npm run build只想快速校验描述风格时用文件级运行更省时间npx vitest run tests/core/server.test.ts -t tool description style contract完整回归用npm test即vitest run。测试按工具名生成describe(tool.name)分组每个失败信息都自带定位与整改方向例如禁用词命中ctx_xxx description (src/server.ts:行号) contains forbidden token MANDATORY: (rule: MANDATORY: opener). 该规则的整改说明——行号直接指向你该改的位置缺章节ctx_xxx (src/server.ts:行号) missing mandatory section WHEN: per ADR-0002 canonical structure顺序错误section WHEN NOT: appears before a sibling that should follow it并附上四个章节的实际位置值非规范大写章节uses off-spec UPPERCASE sections [TIPS] ... Fold operational sub-guidance ... into WHEN: / RETURNS: prosebullet 违规bullet uniformity violation: numeric-dot bullet (e.g. 1.) at description-line N。全部通过即说明你的描述满足 ADR-0002测试同时校验hooks/routing-block.mjs与hooks/core/routing.mjs两个提示词面如果你动了这两个文件同样的禁用词规则另加forbidden_actions、NEVER、FORBIDDEN、- NO X for Y四条也会在同一个 describe 块中执行。边界与限制结构被锁定想偏离规范结构新章节头、新豁免的唯一正路是开新 ADR 修订 ADR-0002 并同步更新测试的 allow-list测试会先失败、ADR 合并后放行。“训练者语气”的文本如THINK IN CODE、MANDATORY routing rules不属于工具描述层按 ADR 的分工应放在 hooks/routing-block.mjssystem-prompt 注入和CLAUDE.md中。重写现有工具描述时注意审计结论风格不能一刀切ctx_purge的重表述若丢了DESTRUCTIVE/SCOPES/CONTRACT信号会回归 Haiku 上的参数保真度Probe 4 数据这类 carve-out 以测试里的 allow-list 为准。【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考