把 AI Coding 工作流做成插件：资产、契约与运行时的三层拆分

ZzT 2026-08-15 0 阅读11分钟

DeepSeek Harness 开源后很快突破十万 star。热度之外，更值得研究的是它的设计原则：Everything is a Plugin。

模型适配器是插件，工具注册表是插件，会话日志是插件，连驱动对话的 Agent Loop（Agent 执行循环）也只是默认实现之一。系统没有一个需要靠修改源码才能扩展的特权内核。

这套思路不只适用于 Agent Runtime（Agent 运行时）。再往上一层，团队每天使用的代码规范、评审要求、交付流程和架构约定，也面临同样的问题：公共部分需要复用，差异部分需要替换，而且不能随着项目和 Coding Agent 的增加不断复制。

本文先用 DeepSeek Harness 解释插件化的边界，再给出一套适用于 AI Coding 工作流的三层拆分：把工作流运行时与静态资产分开，把资产组织成可装配插件，最后允许同一套资产运行在不同引擎上。

DeepSeek Harness 的插件模型

DeepSeek Harness 的架构文档用一句话概括了它的扩展方式：

there is no privileged core to patch: you extend dsh by mounting a plugin beside the others, and registrations are effects that unwind when their plugin unloads.

这句话包含两个机制。

第一，插件之间没有官方与第三方的等级差异。传统插件系统通常由内核预留扩展点，使用者只能修改作者事先开放的部分；DeepSeek Harness 则把模型、工具、日志和执行循环都放进同一棵插件树，通过配置完成替换。

第二，注册是可逆的副作用。插件卸载时，它注册的服务、事件和行为会一并撤销。替换不只是把新实现装上去，还要保证旧实现退出后不留下状态和行为残片。

它的配置采用有序分层：预置 Bundle、Profile 补丁、用户级补丁和命令行补丁依次叠加。上层可以按 ID 替换下层配置，所以分发包提供的是默认组合，而不是不可修改的最终答案。

深度定制的代价

这种设计把“哪些部分允许修改”的决定权交给了使用者。领域检索方式不同，可以替换工具提供者；模型调度策略不同，可以替换 Agent Loop；某个会话需要单独的能力集合，也可以通过配置组合。

代价并没有消失，只是换了位置。使用者需要理解插件职责、加载顺序、配置覆盖和兼容关系；框架维护者则要提供稳定契约、可追踪的配置树和足够可靠的默认组合。DeepSeek Harness 目前仍处于 Developer Preview，官方也明确提醒会出现破坏兼容性的变更。

因此，开箱即用与深度定制并非严格的二选一。好的默认配置可以降低上手成本，但替换面越深，组合与治理成本通常越高。真正的问题是：团队的差异化需求，是否已经多到值得承担这部分成本。

规范文件越积越多

常见做法是让规范跟着项目走：每个仓库放一份供 Agent 读取的说明文件，代码约定、目录结构和评审要求都写在里面，随代码一起提交。

只有一个项目和一种 Coding Agent 时，这样最简单。规模扩大后，副本会沿两个方向增长：

• 项目增加，同一套公共约定被复制到多个仓库；
• Coding Agent 增加，同一项目又要维护 CLAUDE.md、AGENTS.md 或其他平台文件。

最终维护量接近“项目数 × Agent 数”。这些文件表达的是同一批约定，却会在独立修改中逐渐分叉。公共规则改了一次，某个仓库或某个平台漏改，事实来源就不再唯一。

更麻烦的是，交付流程也可能被写死在工具里。需求如何澄清、何时进入评审、缺少哪些产物必须停止，往往散落在提示词、脚本和平台配置中。此时想调整流程，改的已经不只是一份规范，而是整套工具。

要解除这组绑定，可以分三步处理：先划清资产与运行时的边界，再让资产可装配，最后解除资产对单一运行时的依赖。

第一层：分离静态资产与工作流运行时

先定义边界。

层次	负责什么	不负责什么
静态资产	声明流程拓扑、阶段契约、Agent 角色、Skill 和领域知识	不执行调度，不写运行状态，不处理恢复
工作流运行时	è§£æžé ç½®ã€æŽ¨è¿›é˜¶æ®µã€è°ƒç”¨æ£€æŸ¥å™¨ã€ç»´æŠ¤çŠ¶æ€ã€å¤„ç†æš‚åœä¸Žæ¢å¤	ä¸å† ç½®å ·ä½“é¡¹ç›®çš„è§„èŒƒä¸ŽçŸ¥è¯†

静态资产可以声明阶段顺序、依赖关系和 Gate（阶段检查点），但不包含执行这些声明的调度代码。运行时知道“怎样推进”，资产定义“要推进到哪里，以及什么条件下才算完成”。

判断一个内容属于哪一层，可以看它更换执行引擎后是否仍然成立。需求阶段必须交付哪些产物，不依赖具体引擎，属于资产；状态写入哪里、进程中断后如何恢复，则由运行时决定。

用投影生成各平台的原生配置

资产与运行时分离后，还需要一个适配层把同一份资产转换成不同 Coding Agent 能读取的格式。这里把这个过程称为“投影”：源资产保持平台中立，投影器负责生成宿主平台的目录与配置文件。

targets:
  - claude-code
  - codex
  - deepseek-harness

执行投影后，Claude Code、Codex 和 DeepSeek Harness 分别得到符合自身约定的文件。新增宿主的工作主要落在适配器，而不是复制并维护全部规范。

投影产物必须是只读的派生结果。它们可以忽略提交，也可以在 CI 中重新生成并校验，但不能成为新的编辑入口。行为变更只能回到源资产修改，否则事实来源重新分裂，副本问题也会回来。

第二层：把静态资产组织成插件

分离能消除跨平台复制，却不能消除项目差异。如果所有团队只能使用一份固定资产，统一管理很快会变成强制标准。因此，资产还要继续拆成有契约的装配单元。

阶段声明：可跳过，也可替换

一个交付阶段可以写成声明式配置：

{
  "id": "verify",
  "skill": "<默认验证实现>",
  "gate": "verify-to-delivery",
  "capabilities": ["review", "runtime-verification"],
  "mandatory_review": false
}

skill 指向默认实现，capabilities 声明阶段可以使用的能力，mandatory_review 决定是否必须人工确认，gate 则定义离开阶段前要通过的检查。

阶段内部还可以继续拆成节点：

verify.review:
  contract: code-review-signal/v2
  enabled: true
  depends_on: [verify.execution]
  uses:
    skill: <代码评审实现>
  activation:
    metric: changed_lines
    threshold: <团队阈值>

enabled 控制节点是否启用，uses 是实现替换点，depends_on 声明依赖，activation 负责按条件触发。运行时解释这些字段，资产本身不执行任何调度。

契约约束产物，不绑定实现

以需求澄清为例。默认实现可以替换为 Matt Pocock 的 grill-with-docs Skill：它沿决策树逐项消除歧义，并在澄清过程中同步维护术语表和架构决策记录（Architecture Decision Record，ADR）。

requirements.clarification:
  uses:
    skill: grill-with-docs

替换成立的前提不是两个 Skill 的提示词相似，而是它们满足同一份输出契约。流程只要求需求澄清节点交付术语定义、已定决策和未决事项，不关心这些产物由哪个 Skill 生成。

Gate 负责在阶段边界验证契约，并且应由独立检查器执行。停用默认节点只表示不再使用默认实现，不等于降低交付要求；替代实现交不出必需产物，流程仍然停止。这样才能把“实现可替换”和“质量标准稳定”同时保留下来。

互斥知识应当物理隔离

架构约定最容易在插件化时出错。如果把两套互斥规范塞进同一份文件，再用条件分支告诉 Agent 何时使用哪一段，模型仍可能同时吸收两套规则，最终产出混合实现。

更稳妥的做法是让每套架构规范成为独立资产。每份资产都要声明适用范围、禁用范围、版本、风险等级和人工复核要求：

description: >
  仅当工程冻结的架构标识为 architecture-a/v1 时使用。
  不适用于 architecture-b/v1，也不负责替项目选择架构。
metadata:
  version: 1.0.5
  risk_level: high
  human_review: required

工程初始化时冻结架构选择，运行期只读取结果，不再临时推断。工程侧负责安装哪份资产，资产内部不需要知道其他互斥实现的存在。新增第三套规范时，新增一份资产即可，不必继续扩大原文件里的条件分支。

Agent 角色和领域知识也可以沿用这套结构：角色绑定默认 Skill，知识按领域切片，索引负责发现与装配。高风险能力即使已经插件化，也不能绕过人工确认。插件化解决的是替换与复用，不会自动解决权限问题。

第三层：让工作流运行时也可替换

资产可以替换，执行资产的引擎也不必只有一个。

一套自有运行时可以解析流程图，按有向无环图（Directed Acyclic Graph，DAG）推进阶段，在 Gate 上调用检查器，并记录状态与证据。它还要处理暂停、恢复、并发和写入互斥。这些都是运行时职责，不应混入 Skill 或领域知识。

当资产保持运行时中立时，同一套阶段契约和知识可以映射到外部引擎，但这里需要区分两个层次。

Trellis 更接近单条研发流程的 Harness。它把 Spec、任务 PRD、实现上下文、检查上下文和 Workspace Journal 保存在仓库中，并向多种 Coding Agent 投影原生文件。接入 Trellis 时，适配器把阶段与资产映射到它的目录和工作流表面，流程状态由 Trellis 管理。

Multica 处理的是团队级协作：把 Agent、Runtime 和 Task 分开管理，通过 Issue、评论、任务分配和运行记录协调多个 Agent。它可以承载某条研发流程，但关注点不是阶段如何逐步推进，而是谁来执行、在哪个 Runtime 执行，以及结果如何回到团队工作区。

从职责边界推断，两者不一定互斥。Trellis 可以承接单个任务内部的计划、实现和验证，Multica 则在更外层负责任务分派与跨 Agent 协作。真正需要替换的是某一层的实现，而不是把不同层次的工具硬放进同一个候选列表。

多运行时的冲突控制

一套资产允许多个运行时读取，不代表它们可以同时推进同一个任务。至少要补上两类控制：

• 执行权仲裁：每个任务在任一时刻只能由一个运行时持有写权限，释放后其他运行时才能接管；
• 契约兼容：运行前检查资产版本、运行时能力和 Gate 接口，不能识别的字段必须明确报错，不能静默忽略。

缺少执行权仲裁，多个引擎会同时写状态；缺少兼容检查，同一份资产在不同引擎上可能得到不同语义。运行时可替换的难点不在“能否读取同一份 YAML”，而在切换之后是否仍能保持一致的状态机和质量约束。

总结

回到 DeepSeek Harness 的争议：它确实比固定功能的成品更难理解，但原因不是插件越多越先进，而是系统把原本藏在内核里的选择显式交给了使用者。

AI Coding 工作流也一样。把资产与运行时分开，可以消除跨平台副本；用契约封装资产，可以隔离项目差异；允许替换运行时，则能避免流程长期绑定在一个宿主上。与此同时，团队也要承担版本管理、依赖解析、冲突检测、权限审查和迁移兼容。

这套设计适合项目之间确实存在差异、同时使用多种 Coding Agent，并且愿意维护统一资产源的团队。如果项目技术栈和交付流程高度一致，一份共享规范加少量项目配置通常更省事。插件化不是默认答案，它只在“复制与绑定的成本”已经高于“组合与治理的成本”时成立。

参考

• DeepSeek Harness 项目主页
• DeepSeek Harness 架构文档
• Matt Pocock：grill-with-docs Skill
• Trellis 项目主页
• Multica 项目主页