把套件接进现有内容流程:三条改造路径与各自代价
把套件接进现有内容流程:三条改造路径与各自代价
把一套分析或生成能力接进团队已有的内容流程,难的从来不是“跑起来”,而是“接进去之后不把别人的东西弄坏”。Craft Anything 这个纯 Rust 的逆向与重建引擎提供了一个很好的样本:它既要被 Claude Code、Codex、Cursor 这类编码代理调用,也要能被自己的桌面应用、CLI 和无头流水线驱动,还要允许第三方以插件形式扩展。为了同时满足这三种诉求,它在仓库里演化出了三条明显不同的接入路径——配置面嵌入、协议面嵌入、代码面嵌入。
三条路径的实现、边界和代价都写在源码里,本文按“能支撑多少就写多少”的原则,只讨论仓库中确实存在的机制。
一、先把“接入”拆成三个面
Craft Anything 的能力出口被统一收束在一个契约上:ToolSpec。无论是 UI、CLI、MCP 服务器,还是内置代理,最终都通过同一张工具表分发,见 工具契约。这条设计决定了接入可以发生在三个不同层次:
| 层次 | 你改的是什么 | 仓库中的实现 | 影响半径 |
|---|---|---|---|
| 配置面 | 别人家代理应用的配置文件 | crates/setup | 只落在 MCP 注册条目与技能目录 |
| 协议面 | MCP 会话里的工具可见性与调用策略 | crates/mcp | 只影响当前连接与上下文预算 |
| 代码面 | 工具表本身 | 扩展点文档、WASM 插件 | 影响构建产物与版本兼容 |
三者不是互斥选项,而是不同的“改造深度”。深度越大,能表达的东西越多,需要承担的兼容成本也越高。
二、路径一:配置面嵌入,把套件注册进现有代理
这是最轻的一层:不碰别人的代码,只在现有编码代理的配置里写一条 stdio MCP 服务器条目,再往技能目录放一份使用方法。
2.1 客户端矩阵是真实的工程负担
很多人以为这一步就是往 mcpServers 里塞一个 {command, args},但 clients.rs 里的表格说明了现实:24 个客户端入口,配置格式分成 Jsonc、StrictJson、Toml、Yaml、Manual 五类,注册条目的形状分成七种:
pub enum Shape {
Plain, // {command, args}
Stdio, // {type: "stdio", command, args}
StdioAllTools, // {type: "stdio", command, args, tools: ["*"]}
LocalArray, // {type: "local", command: [cmd, ...args], enabled: true}
TransportStdio, // {transport: "stdio", enabled: true, command, args}
Enabled, // {command, args, enabled: true}
WithStartupTimeout, // {command, args, startup_timeout_sec: 30}
}
同一个语义(“启动这个程序并说 MCP”),在不同客户端里落成七种 JSON/TOML 结构。再加上配置文件位置本身就受环境变量影响——CLAUDE_CONFIG_DIR、CODEX_HOME、OPENCODE_CONFIG、KIMI_CODE_HOME、FACTORY_HOME_OVERRIDE 等被显式列在 ENV_KEYS 白名单里,只读这些,不读别的环境变量。这一条常被忽略,却是可测试性的关键:Host 结构把 home、env、os 都做成可注入的,测试才能用临时目录模拟 Windows、macOS、Linux 三种路径规则。
2.2 三条不变式
真正让这条路径“可交付”的,是三条在源码里被反复贯彻的不变式。
第一,只认自己的条目。 is_owned_entry 的判断非常窄:文件名必须是 craft-anything-cli(或 .exe),且第一个参数必须是 mcp。
(file == "craft-anything-cli" || file.eq_ignore_ascii_case("craft-anything-cli.exe"))
&& args.first().is_some_and(|a| a == "mcp")
所以 npx craft-anything-cli mcp、指向 doctor 的条目、或者任何 URL 型条目都不会被当成“我们的”。这条规则同时服务于更新和卸载:卸载时只删匹配项,别人的服务器一个都不动。
第二,保留原文,不做整体重写。 JSONC 走自己的解析器,容忍并保留注释与尾逗号;TOML 用 toml_edit 保留装饰和注释;Grok Build 还额外处理 disabled_mcp_servers,把 craft-anything 从禁用列表里摘掉而不是整表覆盖。测试 toml_merge_preserves_comments 直接断言注释行在合并后仍然存在。这是“局部嵌入”能不能被用户接受的分水岭——一旦工具把配置文件格式化重排,用户就会失去对文件的信任。
第三,先计划,再原子应用,失败回滚。 plan.rs 把接入拆成两段:
let plan = plan(&host, &req)?; // 只读,产出 Create/Update/AlreadyCurrent/Invalid/Manual
if !plan.blocked { let report = apply(&plan); }
plan 阶段只读不写,逐文件给出 preview(- 旧行 / + 新行)、reason 和 remediation。apply 阶段则做了四件事:比对文件在计划之后有没有被改动(不一致直接报 FileChanged 并提示重跑)、首次写入前做一次备份(backup_once 语义是“已存在就不覆盖”,避免多次运行把好备份冲掉)、原子写入并设 0600 权限、写后回读校验条目是否等价。任一文件失败,已改动的文件按逆序恢复,结果标记为 RolledBack。
2.3 这条路径的代价
代价集中在“格式兼容”上,而不是 AI 能力上:
- 客户端数量是线性成本。每支持一个新代理,就要维护它的路径、格式、table 路径、条目形状、技能目录,还有可能出现的特例(
pi的空文件即非法、zsh/zcode的嵌套 table、dsh只能手工配置)。 - 配置解析失败时必须整体停手。
plan.blocked为真时apply一个字节都不写,所有动作标为Skipped。这个设计牺牲了“部分成功”,换来的是用户不会面对半套状态。 - 需要技能文件的所有权标识。skill.rs 用
---\nname: craft-anything\n前缀判定文件归属,遇到Foreign状态既不覆盖也不删除;卸载时只删自己写过的两个文件,目录里用户自己加的notes.md会保留。
适用场景很清晰:已有 Claude Code / Codex / Cursor 工作流、希望“零代码改动”获得能力的团队。它不适合需要深度定制工具语义的场景,因为你只能拿到工具列表,改不了工具行为。
三、路径二:协议面嵌入,控制“看见多少”
注册成功只是开始。把 284 个工具一次性丢给模型,上下文会被工具描述吃掉,模型也更容易选错。Craft Anything 在 MCP 层做了三件事来收窄暴露面。
3.1 渐进式工具集
tools/list 默认只返回 Core 工具集,其余工具通过一个元工具 enable_toolset 打开,打开后服务端发送 notifications/tools/list_changed 让客户端刷新。--all-tools 或 CRAFT_ANYTHING_MCP_ALL_TOOLS=1 才全量暴露。服务端的 instructions 也把这条写成了显式建议:先 list_toolsets,再 enable_toolset。
对应到内容流程,这就是一个天然的灰度开关:第一阶段只给模型“打开目标、看概览、查证据”这几个能力,跑通之后再按需打开 native、android、web 等工具集。工具集的定义在 tool.rs 里是 17 个内置组加一个 Toolset::Custom,组名就是稳定契约。
3.2 响应预算与证据分页
大结果不适合直接塞进上下文。mcp/lib.rs 设了默认 8 MB 的单行响应预算,并针对 Claude Code 单独降到 80 KB,注释里说明了原因:结果会以文本和 structuredContent 各带一份,而客户端默认工具输出上限约 25k token。超过预算的响应不是截断,而是返回 over_limit 错误并指向保留的证据 evidence://<id>,调用方再用 core_evidence_browse 分页取。
这条设计对内容流程特别重要:报告生成、批量比对这类任务的结果天然巨大,直接返回会撞上下文墙,而“摘要优先 + 按需翻页”把一次调用变成可控的多轮读取。
3.3 副作用声明与同意
每个工具都要声明 Effects 位标志,MCP 的 annotations(readOnlyHint、destructiveHint、idempotentHint、openWorldHint)由它推导。needs_consent 的判定是两个位:EXECUTES_FOREIGN_CODE | MUTATES_DEVICE。setup 层的四个工具就是这个机制的直接受益者:setup_apply 与 setup_uninstall 声明了 WRITES_FILESYSTEM | EXECUTES_FOREIGN_CODE,从 MCP 调用时统一返回 ConsentRequired,把批准权交给客户端自己的审批流。测试里明确断言了这一点。
还有一层更硬的边界:Clean room。clean_room.rs 是一份白名单,只有列在 TOOLS 里的工具能在 Deep 模式关闭时运行,其余一律拒绝,并在 details.reason 里写 clean_room,同时给出开启 Deep 模式的三种方式。新工具默认只能是 Deep-only——这是“默认安全”的实现方式:忘记登记只会让工具不可用,而不是让工具越权。
3.4 这条路径的代价
- 工具集划分是长期维护成本。新增工具必须决定归属组,还要决定是否进 Clean room 白名单,两个决定都会影响下游行为。
- 预算参数与客户端耦合。80 KB 这个数字是对特定客户端限制的工程折中,客户端升级后需要重新校准;代码里用
budget_for_client开关允许显式覆盖,就是为了留退路。 - 渐进发现增加一次往返。对一次性脚本影响很小,对延迟敏感的高频调用则不划算,这也是 CLI 直接调用工具而不是走 MCP 的原因之一。
四、路径三:代码面嵌入,把“工具”变成可编译单元
当现有工具语义不够用,接入就从“注册”变成“扩展”。仓库给了三档深度。
第一档:编译期 ToolSpec。 在 crates/engine/src/tools/<area>.rs 定义一个 ToolSpec(id、标题、摘要、面向新手的说明、工具集、诚实的 effects、schemars 参数类型、run),再在 tools/mod.rs 加一行 v.extend(...)。之后它自动成为 CLI 子命令、MCP 工具,也能被内置代理和桌面应用调用。高层工具(例如 AI 层的 rebuild 工具)走 Engine::shared(session, extra),通过 ctx.session.ext 拿到引擎引用。
第二档:运行时工具。 RuntimeTool 允许在启动时动态注册工具,接受外部 JSON schema,并用 ctx.tool 区分同一个函数服务的多个工具。这里有一组强校验:id 必须是 1–64 个小写字母、数字或下划线;工具集 id 同规则;schema 必须是 object;与已有 id 冲突则跳过并记日志,不会中断进程。自定义工具集 id 会被 Box::leak 保留到进程结束,保证 Toolset::Custom(&'static str) 的生命周期成立。
第三档:WASM 组件插件。 配置写在 config.toml:
[[plugins.wasm]]
id = "wordtools"
path = "C:/plugins/wordtools.wasm"
它能导出 craft-anything:plugin/tools 提供工具,也能导出 craft-anything:plugin/checks 参与构建检查。隔离策略很明确:插件不允许 import 任何东西——没有文件、网络、环境变量和时钟,所以它的工具调用不需要征求同意;每次调用在全新实例中运行,带 fuel 工作量上限和 256 MiB 内存上限,超限即报错。版本策略是 semver,但在 0.x 阶段要求主次版本都一致(0.1.0 与 0.1.7 兼容,0.2.0 不兼容),不兼容的插件会被点名拒绝而不是静默跳过。
这条路径的代价
- WASM 插件需要
--features wasm-plugins构建,而该特性默认关闭,因为它会编译 wasmtime。没开特性的构建会记录“skipped”日志而不是报错——这种“静默降级”在排查时很费时间,必须靠启动日志确认。 - 无 IO 是硬约束。需要读写文件、访问网络的扩展做不了纯 WASM 插件,只能回落到外部 MCP 服务器(
[[plugins.mcp]],本地 stdio 或远程 Streamable HTTP),而外部服务器默认consent = true,每次调用都要批准。 - API 版本与宿主绑定。
API_VERSION与 WIT 包必须同步升级,仓库里专门有测试检查二者一致。
五、局部嵌入法的接口设计要点
把三条路径放在一起看,能提炼出四条对任何“套件嵌入现有流程”都成立的接口原则,且每一条都能在仓库里找到对应实现。
其一,标识优先于配置。 判断“这是不是我的东西”时,用可执行文件名加子命令,而不是用配置键名或路径字符串。is_owned_entry 的窄判定让更新和卸载都不会误伤,代价是用户手工写错路径时工具不会接管它——这是有意为之的保守。
其二,计划与应用必须分离。 plan 返回可打印、可序列化、可比较的结构(ActionKind、preview、blocked、change_count),apply 才落盘。CLI 的 --dry-run 直接复用同一个 plan,所以“预览到的”和“真正执行的”不可能漂移。
其三,写入必须可回读、可撤销。 原子写加回读校验解决“写了一半”,backup_once 加逆序回滚解决“写错了一半”。备份文件名是固定的 .craft-anything.backup,且永不覆盖,避免第二次故障把第一次的干净副本冲掉。
其四,错误必须能指向下一步。 几乎每个失败路径都带 remediation:配置无法解析时提示“修好或移走该文件后重跑”,回滚失败时提示“从备份手工恢复”。在内容流水线里,这条决定了值班同学能不能自己解决。
六、灰度切换与回退预案
仓库里的接入流程本身就是一个可复制的灰度模板。
分级启用。 setup 支持三种选择范围:显式 --client <id>(可重复)、--all-detected、以及都不给时的“刷新已经接入过的客户端”。最后一种是天然的幂等操作,适合放进日常巡检;前两种适合首次上线,先单客户端验证再铺开。
先看后写。 --dry-run 打印每个文件的动作、变更行、原因与建议,status: planned 后退出。CI 里可以先跑 dry-run 断言 blocked == false 且 change_count 符合预期,再跑 --yes。
阻断式失败。 只要有一个配置文件不可读或不可解析,blocked 为真,整批动作降级为 Skipped,status: blocked 且退出码为 1。这条规则牺牲了局部成功率,但把“半接入状态”从可能变成了不可能。
健康检查独立成命令。 doctor 不只查注册条目,还会真正启动一次 MCP 服务器:发 initialize、notifications/initialized、tools/list,校验 serverInfo.name、协议版本、工具列表非空,并且必须能找到会话工具(按客户端可能使用的任何别名,通过 registry.canonical 归一化)。同时它会提示 PATH 上存在多份 craft-anything-cli 的风险——这正是“接进去了但跑的是旧版本”这类事故的根因。
卸载是最小化删除。 uninstall 先做一遍只读扫描:任何配置读不出来就整批 blocked,什么都不删;能删的只删 is_owned_entry 匹配项,并且写后回读确认条目确实消失,失败则用旧文本恢复。技能目录只删带自己前缀的两个文件。报告里还显式列出“保留了什么”:项目与证据、设置、其他 MCP 服务器与无关技能、分析引擎。
运行期的灰度在工具集层。 上线新能力时,先让它待在默认不可见的工具集里,通过 enable_toolset 对个别会话开放;确认无误后再调整默认暴露策略。配合 Clean room 白名单,还能做到“默认只允许从外部观察,读内部必须显式开 Deep 模式”。
七、怎么选
| 判断条件 | 选路径一(配置面) | 选路径二(协议面) | 选路径三(代码面) |
|---|---|---|---|
| 团队已在用 Claude Code / Codex / Cursor | 直接可用 | 配合使用 | 不必 |
| 只需要“能问、能查、能出报告” | 足够 | 关键 | 不必 |
| 上下文预算紧张、工具太多导致选错 | 不解决 | 核心手段 | 不解决 |
| 需要新的判定规则或新的输出格式 | 做不到 | 做不到 | 必须 |
| 需要读写文件或联网的扩展 | 做不到 | 做不到 | 走外部 MCP 插件 |
| 需要强隔离的第三方扩展 | 做不到 | 做不到 | WASM 插件(无 IO) |
| 最贵的成本 | 客户端格式矩阵 | 工具集划分与预算校准 | 构建特性、API 版本 |
如果要把这套结论落成一句可执行的话:先用路径一把注册做对(幂等、可预览、可回滚),再用路径二把暴露面收到最小(Core 起步、按需开组、大结果分页),最后才用路径三补语义缺口(先试 RuntimeTool,隔离要求高再上 WASM)。三条路径共用同一张 ToolSpec 表,所以任何一层新增的能力,都会自动出现在 CLI、MCP 和桌面应用里——这也是“局部嵌入”能长期维护的前提:扩展点只有一处,而不是每个前端各写一套。
