标准模式切换到 PTC 模式后技能第一轮调用报错

[Yeeeee1211]

[Bug] 标准模式切换到 PTC 模式后，技能第一轮调用报错 unknown tool "skill"，仅 run_code 可被直接调用

一、现象与复现步骤

复现步骤

1. 连接工作区，会话以默认「标准模式」创建（此时会话为 blank，尚未开始）。
2. 在会话输入框输入 /skill，技能菜单正常出现（技能"看似已加载"），先不发送。
3. 在新会话页的模式选择器切换为「PTC 模式」——blank 会话被 host 成功 recompose 到 code preset（此路径要求会话未开始，因此报错必然出现在切换后的第一轮），此时skill由蓝色变为灰色。
4. 发送 `/skill。
5. 第一轮模型回复前出现工具错误：

Error: unknown tool "skill": only `run_code` is callable directly — call `skill` from inside a `run_code` program instead

补充观察：技能正文实际已被注入上下文（"AI 会查找这个 skill 并加入上下文"）——说明 /name 手势的 pre-step 注入是成功的；报错来自模型在 code 模式下对 skill 工具的顶层直接调用被工具注册表拒绝。模型随后读取错误信息自愈，所以只有第一轮报错、后续轮次正常。

期望行为：切换模式后技能应正常可用——要么按 PTC 的 SDK 方式经 run_code 程序内 tools.skill(...) 加载，要么第一轮就不应引导模型做一次必然失败的直接调用。

二、根因分析（机制链）

1. PTC 模式 = Code Mode 呈现。code preset 的 tool-presentation 行声明 mode: code（apps/cli/config/agent-presets/code/agent.cordis.yml L259–262）。在 code 模式下，工具注册表只向模型展示 run_code 一个工具（wireSchemas 过滤，packages/core/tools/src/index.ts L994–998），并确定性拒绝除 run_code 之外的任何模型直接调用（collapses()，L1324–1326；拒绝发生在 L1423–1444，错误文案 L1439–1442）。这是刻意的安全口径，有测试固定（packages/core/tools/tests/code-mode.spec.ts L1595–1613）。

2. 技能目录文案对呈现模式无感知（bug 本体）。packages/skill/tool-skill/src/index.ts 的 pre-step 监听器在每轮注入技能目录 system-reminder，其中固定写死：

   • L266（首次目录）：

     If the user names a skill, or the task clearly matches a skill's description, call the skill tool with the exact skill name before taking task actions. …

   • L286–287（目录更新）：

     … call the skill tool with the exact name before acting.

   该指令以会话消息形式注入，位于系统提示（含 "only run_code is callable directly" 规则）之后、离模型回答最近，是模型最注意到的指令。标准模式下直接调用 skill 可执行，因此一切正常；PTC 模式下该指令引导模型做一次注册表必然拒绝的调用。

3. 第一轮必然触发：切换 PTC 后第一次发送 /grill，pre-step 注入技能正文（成功）+ 发布上述目录消息；模型按目录指令发出顶层 skill 调用 → collapses('skill', agent, false) 判定 code 模式 → ToolNotFoundError，即用户看到的报错。

结论：这不是"切换状态管理"的 bug——客户端缓存失效、host 端 recompose、事件转发链路均正确（均有单测覆盖）。这是技能目录的模型可见文案未随呈现模式（per-agent tool presentation，见 Agent Note 2026-08-05-per-agent-tool-presentation.md）更新的集成缺口：dsh-tool-skill 早于 per-agent presentation 功能存在，其目录文案从未做过模式感知。

三、为什么"切换模式"后必现

• 标准模式：modeFor(agent) === 'native'，直接调用 skill 可执行 → 正常。
• 切换后：recompose 到 code preset，modeFor(agent) === 'code'，目录照常发布但文案不变 → 第一轮模型按旧文案直接调用 → 确定性拒绝。
• 严格说该机制并非切换特有：直接以 PTC 模式新建会话、第一轮调用技能同样会报错；切换只是用户最容易触发的复现路径（同一个手势在标准模式可用、切到 PTC 后必现）。

四、源代码位置

角色	文件	位置
Bug 本体：目录文案写死"直接调用"	packages/skill/tool-skill/src/index.ts	L254–311（renderCatalogMessage/renderCatalogUpdate），核心 L266、L286–287
手势注入（正常，非 bug）	packages/skill/tool-skill/src/index.ts	L177–204（agent/pre-step）
code 模式拒绝直接调用（设计内）	packages/core/tools/src/index.ts	collapses() L1324–1326；拒绝 L1423–1444；modeFor() L900–911；wireSchemas() L994–998；ToolNotFoundError L494–510
code 模式提示与 SDK 段	packages/core/tools/src/index.ts	CODE_ONLY_INSTRUCTION L58；collapseSection L855–863；sdkSection L875–892
PTC 模式定义	apps/cli/config/agent-presets/code/agent.cordis.yml	L90–94（skill 行）、L259–262（tool-presentation，mode: code）
相关设计文档	.agents/notes/implemented/feature/2026-08-05-per-agent-tool-presentation.md	—
既有测试（固定拒绝行为/固定文案）	packages/core/tools/tests/code-mode.spec.ts L1595–1613；packages/skill/tool-skill/tests/tool-skill.spec.ts L289	—

五、修复建议

方案 A（推荐）：目录文案按 agent 有效呈现模式分支

① packages/core/tools/src/index.ts — 暴露模式只读查询

将私有 modeFor（L900–911）公开为 modeOf（更新内部 collapseSection/sdkSection/wireSchemas/view/collapses 五处调用点）：

/**
 * The presentation one scope's agent sees: its own declaration, else the
 * deployment default.
 * @param scope - the calling agent, or undefined for the global view.
 * @returns the resolved presentation mode.
 */
modeOf(scope?: ScopeKey): ToolPresentationMode {
  const layers = this.layers.chainLayers(scope)
  for (let index = layers.length - 1; index >= 0; index -= 1) {
    const mode = layers[index]?.mode
    if (mode !== undefined) return mode
  }
  return this.defaultMode
}

② packages/skill/tool-skill/src/index.ts — 目录发布时按模式选文案

pre-step 目录监听器中，渲染时传入 agent 的有效模式：

// The route a skill loads through follows the agent's effective
// presentation: under `code` the registry collapses every model-direct
// call except run_code, so the catalog must not instruct a direct `skill`
// call — that is the first-round UNKNOWN_TOOL failure this fixes.
const catalog = history.published
  ? renderCatalogUpdate(entries, ctx.tools.modeOf(agent))
  : renderCatalogMessage(entries, ctx.tools.modeOf(agent))

renderCatalogMessage/renderCatalogUpdate 增加 mode 参数，并把固定的直接调用句抽为模式感知辅助函数：

/**
 * The mode-correct skill-loading instruction. A `code` agent cannot call
 * `skill` directly (only `run_code` may be named), so the catalog states the
 * SDK route instead of inciting the denial.
 * @param mode - the agent's effective presentation mode.
 * @returns the trailing reminder lines, complete for the mode.
 */
function loadInstruction(mode: ToolPresentationMode): string[] {
  const load = mode === 'code'
    ? "If the user names a skill, or the task clearly matches a skill's description, load it from inside a `run_code` program via `tools.skill` with the exact skill name before taking task actions."
    : "If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions."
  return [
    `${load} Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.`,
    'A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.',
  ]
}

native/both 分支保持原文不变（both 下直接调用可执行，无需改）。

为什么 digest 不需要改：会话一旦开始（发出第一轮）呈现模式即固定（host 只允许 blank 会话 recompose），同一会话内的目录帧文本不会变，现有 entry-only 的 digestCatalogEntries（L328–335）依旧正确，无需改动会话日志格式，也不影响 history.visibleDigest 的重放推导。

可选加固：skill 工具的 description（packages/skill/tool-skill/src/index.ts L82–84，"Call this with the exact skill name…"）在 code 模式下会进入 SDK 投影，可一并按模式限定措辞，进一步降低模型误判概率。

方案 B（替代，改动最小）

不引入模式读取，把目录文案改为模式无关的中性表述，例如：

If the user names a skill, or the task clearly matches a skill's description, load it through the skill tool as your tool catalog declares it before taking task actions.

该方案不依赖 dsh-tools 改动，但指令不如方案 A 精确（模型需要自行推断 run_code 路线），按仓库"模型视角、明确措辞"的约定，推荐方案 A。