Skill Graph 跑起来之后：一次 Claude 团队插件的四轮工程化改造

上一篇讲清了 Graph、Chain、next-skill 和 Harness。这一篇不再解释它们是什么，只聊一件事：当这套设计真的装进 Claude Plugin、交给团队使用后，我们又踩了哪些坑。

今年 4 月，我整理过一版 Claude Code 团队实践。当时的思路是三层：CLAUDE.md 保存项目约束，Skill 固化团队流程，Plugin 负责安装、升级和工具接入。

这套结构解决的是“每个人手里的 Claude 不一样”。团队终于可以分发同一套规范和能力，不必在每次会话里重新解释技术栈、目录结构和开发流程。

到了 8 月，我又往前走了一步。在《数字人的三层骨架》里，我把重心放到 Skill Graph：Graph 是地图，Chain 是记忆，next-skill 负责计算下一步，Harness 让这套东西跑起来。

那篇文章偏设计原理。写完之后，我们把 Skill Graph 真正放进企业 UI Plugin，用真实任务连续跑。然后发现，从“设计成立”到“团队可用”，中间还隔着四轮改造。

这篇就是后半段。

一、第一轮：Graph 里有节点，Plugin 里却没有能力

第一版 Graph 看起来很完整。需求范围、用户故事、设计简报、页面实现、异常状态、质量检查，该有的步骤都有。

可真正执行时，有些节点只是 JSON 里的逻辑名称，没有对应的 Skill。

Graph 告诉 Agent 下一步应该进入某个节点，Claude Code 却找不到可以调用的能力。最后只能由 Agent 根据自己的 Prompt 临时模拟。

短期能跑，时间一长就会出问题：Agent Prompt 越写越大，Graph 和执行逻辑逐渐分叉，单个节点也没法独立测试。换一个宿主，还得把 Agent 里那套隐含规则重新解释一遍。

这次调整不复杂，但工作量很大：Graph 中的每个节点都必须落成真实 Skill。

我们把 product-design 里的方法和资产迁入 Enterprise UI Plugin，为范围分析、Stories、页面实现、图表、异常状态、无障碍和验收分别建立 Skill。Graph 的 handler 必须指向真实目录，节点 id 必须与 Skill 的 name 一致。

同时加上验证器，检查：

• 节点是否真实存在；
• Skill 是否已被 Plugin 注册；
• 依赖引用是否有效；
• 硬依赖是否形成环路；
• Graph 和实际目录是否发生漂移。

迁移时还遇到一个细节。原始方法论里保留着旧的 .spark、旧 Dashboard 和外部 Plugin 指令。如果直接复制，表面上完成了本地化，运行时仍会偷偷回到旧协议。

最后采用的办法是：原始材料保留在 PRODUCT_DESIGN_METHOD.md 中，用于追溯；新的 SKILL.md 只负责当前 Plugin 的执行规则。

第一轮结束后，Graph 不再是一张概念图。每个节点都有真实能力可接。

二、第二轮：Claude 说完成了，链路却没有留下任何东西

节点真实可调用后，我们在另一台服务器上跑了一次 Enterprise UI 任务。

Claude 正确激活了 Skill，也完成了页面修改，最终回复看起来没有问题。可回到 workspace 一看，没有 .chain，没有 context，也没有 Dashboard。

从聊天记录看，任务完成了；从工作流看，这个节点从未发生。

上一篇文章里，我把 Chain 定义为跨步骤记忆。这次实践让我意识到，只定义一个 JSON 格式还不够。如果写盘只是建议，Agent 忙起来就可能跳过。

所以第二轮没有继续增加状态字段，重点改成强制完成顺序：

写入 context
  → 重新解析 JSON
  → 检查 artifact 是否存在
  → 更新 Dashboard
  → 验证 Dashboard
  → 输出 Handoff

写盘被放在最前面。这条规则有点笨，但很实用。以前把写盘留到最后，Claude 经常先整理报告、组织回复，最该留下的状态反而漏了。

现在每个节点都要执行同一份 node-completion 契约。只在对话里说“已完成”不算完成，context 无法解析、artifact 不存在、Dashboard 没更新，同样不算。

Claude Plugin 里还增加了一个条件式 Stop Hook。它只在项目已经存在 Enterprise UI context 时补刷新 Dashboard，不会在无关项目里创建 .chain。

Hook 的位置也很明确：它是兜底，不是主流程。节点仍然要自己完成写盘和验证，否则换到不支持同类 Hook 的宿主，链路又会断。

到这里，Chain 才从“有一份状态文件”变成“节点完成协议”。

三、第三轮：流程跑通了，但一个小改动花了 30 多分钟

接下来暴露的问题很有意思：流程确实跑通了，也因此每次都跑得过于完整。

我们用 delivery 优化一个已有的 API Token 管理页面，最终只改了 3 个代码文件。整个过程却走了 5 个节点：

scope → stories → brief → flow-web → check

实际写代码只用了几分钟，其余时间都在整理范围、Stories、设计简报、context 和 Dashboard。文档数量甚至超过了代码文件。

这些步骤并非没有价值。新模块、多页面或权限复杂的功能确实需要完整链路。问题是，这次只是一个模式明确的单页优化。

我们回头检查 Graph，还发现所谓“快速路径”其实走不通。next_hint 里虽然推荐单页任务直接进入页面实现，但 flow-web 的硬依赖仍包含设计简报。文字说可以跳，依赖规则不允许跳。

第三轮改造引入了三种执行档位：

Quick
  enterprise-ui-patch

Standard
  scope → stories → flow-web → check

Full
  完整设计、实现、状态与验收链路

用户正常使用时不必选择模式。delivery 会先看任务描述和少量项目证据，再自动判断。

已有单页、预计不超过 5 个源码文件、没有路由、权限、API 和依赖变化，可以走 Quick。单模块功能走 Standard。新模块、多页面或跨系统约束变化，才进入 Full。

--quick、--standard、--full 仍然保留，但只是人工覆盖。执行中一旦发现任务比预期复杂，链路可以升级，不能为了省步骤绕过风险。

Quick 也不是把完整链路“跑快一点”。它只有一个真实节点 enterprise-ui-patch，在同一次执行中检查现有模式、修改代码、运行针对性验证、写入 context，然后结束。它不会把用户已经说清楚的需求再加工成三份文档。

这轮改造也改变了我对流程完整性的理解：任务走过与自身风险相称的路径，就已经完整。

四、第四轮：链路还没结束，主会话的上下文先满了

执行档位解决了简单任务的时间问题。Full 和部分 Standard 任务继续运行时，又碰到了上下文溢出。

Enterprise UI 的方法论来自一套完整设计 Plugin。单是 enterprise-ui-flow-web 目录就有大约 710 KB，不少节点的方法文件有几百行。页面实现节点一度明确要求完整阅读超过 1000 行的 PRODUCT_DESIGN_METHOD.md。

多个节点在同一个会话里连续运行，方法论、源码、日志和 artifact 会一直累积。我们原本期待 Claude 自动 compact，但 compact 只会在接近阈值时触发。一次文件读取或工具输出太大，可能还没等到压缩，窗口已经被塞满。

而且节点之间没有给 compact 留出自然的人工窗口。delivery 会自动接着往下跑，等用户看到提示，往往已经晚了。

PreCompact Hook 也解决不了这个问题。它只能在压缩即将发生时响应，不能替 Skill 主动发起压缩。

第四轮没有继续调 compact 参数，而是改了执行结构：主会话只做协调，每个 Graph 节点交给一个全新的 worker。

用户请求
  ↓
delivery：判断模式、读取 Graph
  ↓
fresh worker：只执行当前节点
  ↓
.chain/context：保存详细结果
  ↓
短 HANDOFF：返回主会话

每个节点都启动 fresh worker，不 resume，也不复用上一节点的对话。worker 只加载当前 Node Skill，从 .chain/context 读取上游事实，完成后返回一份不超过 1200 字符的结构化 Handoff。

代码、设计产物和测试日志留在文件系统中，不再搬回主会话。主会话只保留节点状态、context 路径、变更文件、验证结果和下一步建议。

单个 worker 内部也增加了读取预算：

• 先检索方法论的标题和关键词；
• 首轮最多读取两个相关章节；
• 场景库只选与当前任务匹配的文件；
• 大型日志先定位错误，不整段读入；
• 后续节点读取 context，不重新加载 artifact 正文。

delivery 自己同样有预算。为了判断 Quick、Standard 还是 Full，它最多读取少量目标文件片段。证据不足就选择 Standard，不通过扫描半个仓库来追求“精准分类”。

这轮改造之后，Chain 又多了一层作用：它既是中断恢复的记忆，也是不同 worker 之间的低成本通信协议。

五、Graph 跑起来以后，各层的边界反而更清楚了

回头看这四轮改造，最初那套三层 Plugin 架构并没有被推翻，只是往下补齐了执行层。

这些层一旦混在一起，系统就会越来越难维护。

把节点逻辑塞进 Agent，Agent Prompt 会膨胀。让 Skill 自己接管整条链路，执行和编排会混在一起。只有 Graph 没有 Chain，流程一中断就失忆。只依赖 compact、不控制读取范围，上下文迟早还会溢出。

现在这套分工比较克制：Graph 只管路由，Skill 只做单节点，worker 只跑一次，.chain 保存事实，主会话拿到短 Handoff 后继续调度。

六、从“设计一张图”到“维护一个运行系统”

上一篇写 Skill Graph 时，我最关心的是地图、记忆和下一步算法。这次真正跑进 Claude Plugin 后，关注点变了。

我开始在意另一组问题：节点是不是真实能力，完成状态有没有落盘，流程成本是否匹配任务重量，一条长链会不会把上下文拖垮。

这些问题没有哪一个靠更长的 Prompt 解决。

最后留下来的，是可调用的 Skill、可计算的 Graph、先写盘的完成协议、分档执行路径、fresh worker 和一组防回归验证器。

这也是这次实践最有价值的地方：每踩一次坑，就把它从“下次提醒 Claude 注意”变成机器可以检查的规则。

现在，Claude Code 仍然是这套 Plugin 的主要运行场景。下一步要处理的是另一类问题：同一套 Skill Package 和 Skill Graph，怎样在 Codex 中复用？哪些部分可以共享，哪些 Agent、Hook 和 frontmatter 必须按宿主适配？再往后，Graph 又该怎样与 MCP、权限和企业执行系统连接？

这些会是后面的文章。

Skill Graph 跑起来，只是起点。真正难的是让它在真实项目里跑得稳、跑得动，还能在出问题时知道为什么。