dependency-coordinator

用途

Dependency Coordinator 用于在契约优先的多智能体构建流程中，解决并行实现智能体之间的依赖版本漂移问题。它位于流水线的特定位置：在 plan-builder 之后运行，在编排器派发并行智能体之前运行，为智能体之间的依赖固定版本，避免并发工作发生冲突。

该技能在 monorepo 中编写跨包依赖清单，使并行实现智能体能够填写各自的 package.json（或等价文件），而不会在共享传递依赖上产生版本漂移。任何将要写入包清单的智能体被派发之前，都应先运行本技能。

适用前提

本技能假设采用契约优先的多智能体构建模型：

编排器并行派发角色智能体
每个角色智能体消费来自 /contracts/ 的机器可读契约
qe-agent 通过 qa-report.json 把关构建

对于单智能体或临时性工作，本技能不是合适的工具。

为什么需要它

据 orchestrator 技能说明，规范问题导致约 42% 的多智能体失败。contract-author 技能可防止 API/数据/事件边界出现此类问题，但不覆盖包清单。如果没有协调的依赖清单，并行智能体会固定相互冲突的传递版本（最常见的是通过 vite + drizzle-kit + vitest 引入的 esbuild），导致 pnpm install / pip install / cargo build 在 postinstall 阶段因版本不匹配而中途失败。

本技能与 contract-author 并列位于编排器的 Phase 4（契约阶段），编写的是另一种契约：依赖契约。

角色

作为依赖协调者，需要读取项目的技术栈画像（来自 .claude/profile.yaml 或计划），枚举所有可能漂移的共享传递依赖，并产出：

根清单，通过 overrides/resolutions 将共享传递依赖固定到单一版本
各包清单模板，供消费智能体填写（而非从零编写）
人类可读的 DEPENDENCIES.md，记录版本策略
简短的派发建议，供编排器粘贴到每个智能体的提示中

输入

技术栈画像：来自 .claude/profile.yaml 或计划文档，具体包括语言、运行时、包管理器、测试框架、构建工具、ORM、Web 框架、UI 框架。
工作区形态：计划组件列表中要创建的 apps/* 和 packages/* 列表。
固定策略（可选）：strict（每个依赖一个版本）或 flexible（使用脱字符范围，仅对已知冲突依赖使用 overrides）。默认：flexible。

流程

各步骤的详细配方见 references/pinning-strategies.md，编写前应先阅读。流程如下：

枚举共享传递依赖：针对检测到的技术栈，列出已知会漂移的依赖（见 references/known-conflict-deps.md）。
为每个传递依赖选择目标版本：选择满足最多消费者要求的版本，并记录理由。
编写根清单：根据工作区的包管理器（pnpm/npm/yarn/poetry/uv/cargo）产出对应的 overrides/resolutions 块。各技术栈模板见 references/pinning-strategies.md。
编写各包清单模板：为每个工作区包生成一个 package.json.template（或等价文件），头部注释列出继承的固定版本。
编写 DEPENDENCIES.md：以人类可读形式记录版本策略，包括理由、各包边界、升级流程和迁移手册。见 references/dependencies-md-template.md。
产出派发建议：一段简短字符串，逐字粘贴到每个实现智能体的提示中，警告其不要修改根 overrides。

完成步骤 1–6 后，在派发智能体之前于工作区根目录运行一次 dry install（各工具命令见 references/pinning-strategies.md）。dry install 失败意味着 overrides 块有误，需在派发前修复。

规模适配

根据项目规模匹配输出复杂度：

单包项目：完全跳过本技能，不存在跨智能体漂移面。
2–3 个包的 monorepo：仅编写 overrides + DEPENDENCIES.md，跳过各包模板。
4 个以上包且并行派发智能体：完整输出——根 overrides + 各包模板 + DEPENDENCIES.md + 派发建议。
多语言 monorepo（如 TS + Python）：每种语言产出一份清单（根 package.json overrides + 工作区级 pyproject.toml 约束）。

协调关系

与 contract-author 的分工：contract-author 负责 API/数据/事件边界，本技能负责依赖边界。两者都在编排器的 Phase 4 运行。先运行 contract-author（它决定存在哪些包），再运行本技能（为这些包固定依赖）。
与 infrastructure-agent 的分工：infrastructure-agent 负责 Dockerfile、CI、部署配置，本技能负责它们安装所依据的包清单。本技能的输出位于其上游，它们会自动采用已固定的版本。

运行顺序：plan → contract-author → dependency-coordinator → 实现智能体 → contract-auditor（验证没有智能体破坏固定策略）。

输出

文件	必需条件	格式
根 package.json（或 pyproject.toml、Cargo.toml），含 overrides 块	始终	语言原生
packages/<each>/package.json.template	4 个以上包	语言原生
工作区根目录的 DEPENDENCIES.md	始终	Markdown
派发建议字符串	始终	纯文本，粘贴到智能体提示中

质量检查清单

每个 override 在 DEPENDENCIES.md 中都有理由条目
编排器计划派发的每个工作区包都有对应的各包模板
没有模板硬编码与根 override 冲突的版本
DEPENDENCIES.md 列出了升级固定版本的迁移手册
派发建议提及：不要修改根、使用模板、冲突时升级
编写后运行 pnpm install --dry-run（或等价命令），必须在派发智能体前成功

应避免的反模式

空的 overrides 块：如果找不到值得固定的共享传递依赖，不要产出空块。本技能的价值在于固定，而非形式。
全部严格固定：超出目标并造成维护负担。只固定该技术栈中已表现出漂移的依赖。
直接编写各包 package.json：那是实现智能体的工作。本技能编写的是模板，由智能体填写。
跳过 DEPENDENCIES.md：未记录的 override 是未来维护者的地雷。

参考文件

references/pinning-strategies.md：各技术栈的完整配方——枚举、版本选择逻辑、pnpm/npm/yarn/Poetry/uv/Cargo 的根清单模板、各包模板模式、dry-install 验证命令
references/known-conflict-deps.md：各技术栈（TS/Python/Go/Rust）中频繁漂移的传递依赖表
references/dependencies-md-template.md：DEPENDENCIES.md 模板

组合关系

contract-author：紧接本技能之前运行
infrastructure-agent：消费已固定的清单
contract-auditor：事后验证没有智能体破坏固定策略
orchestrator：在 Phase 4（契约）运行本技能