10. 扩展路径

扩展 Claude Code 时，先判断你要扩展的是哪一层。很多复杂问题来自把技能、工具、MCP、权限和入口混在一起。正确的切分是：技能改变任务表达和提示词；工具增加模型可请求的动作；处理器执行本地副作用；权限决定能否执行；MCP 把外部服务的能力接入工具池；入口负责把外部请求装配进查询引擎。

本章里的英文名词都按边界使用：技能（skill）是任务说明，工具（tool）是模型可请求的动作，处理器（handler）是本地执行代码，权限（permission）是本地放行条件，MCP 是外部能力协议，入口是把请求交给查询引擎的装配层。

新增内置工具时，需要同时考虑模型可见和本地可执行两面。模型可见面包括名称、描述、输入结构、是否延迟加载和提示文本；本地执行面包括校验、权限检查、调用逻辑、输出大小、渲染、并发安全和是否只读。工具加入工具池后，还要确认它是否会被简单模式、权限拒绝、MCP 去重、工具搜索或提示词缓存策略影响。只写处理器而不写清权限和结构说明，会让模型很难稳定调用；只写结构说明而不控制处理器，则会扩大不必要的动作面。

新增技能时，重点不是写代码，而是写清“模型什么时候使用它”和“它会改变什么”。一个技能可以提供提示模板、参数说明、允许工具、模型选择、推理强度、钩子、路径条件或分叉语义。如果技能只是把一段人工流程包装成模型可调用能力，通常不需要新增工具。如果它需要真实副作用，应该通过已有工具或新增工具执行，而不是把权限逻辑藏在技能文本里。

接入 MCP 时，应把 MCP 服务看成工具和资源的外部来源。运行时会把 MCP 工具包装进统一工具系统，所以仍要经过结构校验、权限、钩子和结果处理。MCP 还可能提供提示命令或资源，这些会影响技能/命令和上下文层。扩展 MCP 时要特别注意命名稳定性、服务级权限规则、认证失败后的状态更新，以及是否应该把工具结构说明全量加载给模型。

新增权限策略时，优先放在权限层，而不是提示词。提示模型“不要做危险事”只能降低请求概率，不能阻止执行。真正的限制应表现为拒绝/询问/允许规则、工具自身权限检查、安全检查或沙箱配置。若某个工具支持钩子，钩子也只能参与决策，不能替代规则层。

新增上下文或记忆来源时，要明确三个问题：它何时加载，放在哪一层，压缩/恢复后如何恢复。会话开始时加载的内容适合放入用户上下文或系统上下文；任务过程中动态发现的内容适合作为附件或后续消息；长期记忆需要有索引、边界和写入规则；容易变大的内容必须考虑压缩和截断。否则扩展很快会变成上下文污染。

新增入口时，目标应是汇入查询引擎，而不是复制查询循环。入口需要准备应用状态、工具、命令、MCP、权限上下文、界面或 SDK 回调、会话 id 和中断控制器。交互式入口要处理权限弹窗和进度展示；非交互入口要明确遇到询问时的策略；服务端入口要把协议字段映射到同一套运行时配置。

常见改造顺序可以保持一致：

定义能力边界
  -> 写清模型可见说明或技能说明
  -> 接入本地处理器或外部 MCP 服务
  -> 接入权限、沙箱和失败结果
  -> 定义事件与结果回填
  -> 确认压缩、恢复和分叉后的表现

判断扩展是否合理，可以用一条检查线：模型看到什么，运行时验证什么，权限限制什么，处理器执行什么，结果如何回到模型，转录记录如何恢复。如果这六个问题都清楚，扩展通常能自然接入现有架构。下一章会用修复测试失败的任务把这些边界串起来。