把套件接进现有内容流程:三条改造路径与各自代价

原创2026-11-02 13:09:501,637 阅读
文章标签:人工智能AI 应用AI Agent代码智能体MCP 服务逆向工程桌面应用开发工具

把套件接进现有内容流程:三条改造路径与各自代价

把一套分析或生成能力接进团队已有的内容流程,难的从来不是“跑起来”,而是“接进去之后不把别人的东西弄坏”。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 和桌面应用里——这也是“局部嵌入”能长期维护的前提:扩展点只有一处,而不是每个前端各写一套。

登录后查看全文
craft-anything