ln-820-dependency-optimization-coordinator

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

ln-820-dependency-optimization-coordinator

类型： L2 领域协调器 类别： 8XX 优化

由运行时支持的跨技术栈依赖项升级协调器。检测包管理器，为每个包管理器委派一个工作器，记录机器可读的工作器摘要，并生成最终协调器摘要。

---

概述

方面	详情
输入	项目路径及可选的升级策略
输出	汇总的依赖项升级报告，包含各工作器的结果
工作器	ln-821（npm）、ln-822（nuget）、ln-823（pip）
运行时	.hex-skills/dependency/runtime/runs/{run_id}/

---

工作流

阶段： 预检 -> 检测包管理器 -> 安全审计 -> 委派升级 -> 收集结果 -> 验证摘要 -> 报告

---

运行时契约

必须读取： 加载 references/ci_tool_detection.md 必须读取： 加载 references/coordinator_runtime_contract.md、references/dependency_runtime_contract.md、references/coordinator_summary_contract.md

运行时 CLI：

node references/scripts/dependency-runtime/cli.mjs start --identifier repo-deps --manifest-file <file>
node references/scripts/dependency-runtime/cli.mjs status --identifier repo-deps
node references/scripts/dependency-runtime/cli.mjs checkpoint --phase PHASE_3_DELEGATE_UPGRADES --payload '{...}'
node references/scripts/dependency-runtime/cli.mjs record-worker-result --payload '{...}'
node references/scripts/dependency-runtime/cli.mjs record-summary --payload '{...}'
node references/scripts/dependency-runtime/cli.mjs advance --to PHASE_4_COLLECT_RESULTS
node references/scripts/dependency-runtime/cli.mjs complete

必需的状态字段：

• worker_plan
• worker_results
• child_runs
• verification_passed
• report_ready
• summary_recorded

领域检查点：

• PHASE_1_DETECT_PACKAGE_MANAGERS：已检测的包管理器、指示文件、已跳过的包管理器
• PHASE_2_SECURITY_AUDIT：各包管理器的审计判定、阻断性发现、发行时间策略
• PHASE_3_DELEGATE_UPGRADES：每个受委派工作器对应一个 child_run，包含工作器名称、标识符、runId 和 summaryArtifactPath
• PHASE_4_COLLECT_RESULTS：已记录的工作器摘要，以及未解决的失败或警告
• PHASE_5_VERIFY_SUMMARY：最终报告路径、验证判定、摘要就绪状态

守卫规则：

• 在每个计划中的工作器都生成有效的 dependency-worker 摘要之前，不得从 PHASE_3_DELEGATE_UPGRADES 进入下一阶段
• 在最终报告检查点存在且已记录 dependency-coordinator 摘要之前，不得完成
• 仅使用工作器 JSON 摘要；切勿根据文本输出推断工作器状态

---

阶段 0：预检

启动运行时之前，确认项目符合依赖项处理的条件。

检查	方法	阻止条件
清单存在	运行时 start 验证	缺失
项目路径存在	文件检查	缺失
已提供升级策略	清单或默认值	否
标识符存在活动运行	运行时活动指针	存在冲突的活动运行

默认选项：

选项	默认值	含义
upgradeType	major	major、minor 或 patch
allowBreaking	true	允许进行主版本迁移
minimumReleaseAge	14	除非安全要求，否则跳过近期发布的版本
testAfterUpgrade	true	工作器在变更后验证构建和测试

---

阶段 1：检测包管理器

为每个包管理器系列检测一个工作器目标。

包管理器	指示文件	工作器
npm	package.json + package-lock.json	ln-821
yarn	package.json + yarn.lock	ln-821
pnpm	package.json + pnpm-lock.yaml	ln-821
nuget	*.csproj 或 *.sln	ln-822
pip	requirements.txt	ln-823
poetry	pyproject.toml + poetry.lock	ln-823
pipenv	Pipfile + Pipfile.lock	ln-823

检查点载荷必须包含：

• detected_managers
• indicator_paths
• worker_plan
• skipped_reasons

---

阶段 2：安全审计

在委派繁重的升级工作之前，执行轻量级的预检安全性和新鲜度检查。

管理器系列	命令	阻止条件
Node.js	npm audit --audit-level=high 或管理器等效命令	存在未获准覆盖的严重漏洞
NuGet	dotnet list package --vulnerable	存在未获准覆盖的严重漏洞
Python	pip-audit --json 或管理器等效命令	存在未获准覆盖的严重漏洞

发布时长门槛：

选项	默认值	说明
minimumReleaseAge	14 days	跳过发布时长过短的软件包
ignoreReleaseAge	false	紧急安全补丁的覆盖选项

检查点载荷必须包含：

• audit_results
• blocking_findings
• release_age_policy
• managers_cleared_for_delegation

---

阶段 3：委派升级

为每个工作器系列委派一个子运行。子运行必须是确定性的，并由产物驱动。

使用下方路由表选出的具体工作器标识进行委派。不要在提示词中自行生成系列占位符或猜测技能 ID。

委派上下文：

字段	类型	说明
projectPath	string	目标项目的绝对路径
packageManager	enum	npm、yarn、pnpm、nuget、pip、poetry、pipenv
identifier	string	运行中的稳定工作器标识符
runId	string	确定性子运行 ID
summaryArtifactPath	string	工作器摘要的确切 JSON 路径
options	object	升级策略、验证标记、安全标记

工作器选择：

管理器系列	工作器	备注
npm、yarn、pnpm	ln-821-npm-upgrader	每个检测到的 Node 管理器对应一个子运行
nuget	ln-822-nuget-upgrader	.NET 对应一个子运行
pip、poetry、pipenv	ln-823-pip-upgrader	每个检测到的 Python 管理器对应一个子运行

启动每个工作器后：

1. 在 PHASE_3_DELEGATE_UPGRADES 下记录 child_run 检查点。
2. 等待发出的 dependency-worker 摘要信封。
3. 使用 record-worker-result 记录工作器摘要。

---

阶段 4：收集结果

仅汇总经过验证的工作器摘要。

协调器使用的工作器摘要字段：

字段	说明
producer_skill	工作器标识（ln-821、ln-822、ln-823）
summary_kind	必须为 dependency-worker
identifier	稳定的工作器标识符
payload.status	已完成、部分完成或失败
payload.upgrades	已应用的升级及升级前后的版本
payload.warnings	非阻塞问题
payload.verification	构建/测试验证结果
payload.artifact_path	工作器拥有的持久报告路径（如有）

收集输出：

• worker_results
• success_count
• partial_count
• failed_count
• blocking_failures

---

阶段 5：验证摘要

准备最终持久报告，并验证协调器能否以确定性方式完成。

验证清单：

• 每个计划中的工作器都生成了一个有效的摘要信封
• 汇总计数与记录的工作器结果一致
• 最终报告路径已存在或已准备好写入
• 完成前，report_ready 和 verification_passed 均为 true

失败处理：

1. 保留成功的工作器结果。
2. 在协调器报告中明确标记失败的工作器。
3. 不要编造工作器尚未验证的回滚操作。

---

阶段 6：报告

协调器报告架构：

字段	说明
package_managers	本次运行中检测并处理的包管理器
workers_activated	已委派的工作器
total_packages	各工作器分析的包总数
upgraded	成功升级的包
skipped	已是最新版本或因策略而跳过的包
failed	失败的包或工作器运行
breaking_changes	主版本升级或迁移
verification_passed	汇总验证结果
per_worker[]	机器可读的工作器结果摘要
warnings[]	跨工作器警告

完成顺序：

1. 写入持久化报告。
2. 检查点记录报告路径和验证结果。
3. 使用 record-summary 记录 dependency-coordinator 摘要封装。
4. 仅在报告检查点和协调器摘要均存在后，才完成运行时。

---

配置

Options:
  upgradeType: major          # major | minor | patch
  allowBreaking: true
  minimumReleaseAge: 14
  auditLevel: high            # none | low | moderate | high | critical
  testAfterUpgrade: true
  buildAfterUpgrade: true
  rollbackOnFailure: true
  skipDev: false
  skipOptional: true

---

错误处理

可恢复：

错误	恢复方式
对等依赖冲突	将工作器结果保留为部分结果，继续收集
某个工作器中的构建失败	保留失败状态，继续处理其他工作器
网络超时	工作器在本地重试，然后报告失败

致命错误：

错误	操作
未找到包管理器	以空结果报告结束
运行时验证失败	暂停运行并要求人工介入
缺少计划子运行的工作器摘要	不要从收集阶段继续推进

---

参考资料

• breaking_changes_patterns.md
• security_audit_guide.md

---

TodoWrite 格式（必填）：

- Detect package managers (in_progress)
- Delegate ln-821-npm-upgrader child runs (pending)
- Delegate ln-822-nuget-upgrader child runs (pending)
- Delegate ln-823-pip-upgrader child runs (pending)
- Aggregate dependency-worker summaries (pending)

工作器调用（必填）

宿主 Skill 调用： Skill(skill: "...", args: "...") 是必需的委派方式。

• Claude：必须严格按所示方式调用 Skill 工具。
• Codex：如果没有 Skill 工具，则在可用技能中找到指定技能，读取其 SKILL.md，将 args 视为 $ARGUMENTS，执行该技能工作流，然后携带其结果/产物返回此处。
• 不要内联工作器逻辑，也不要在未执行目标技能的情况下将工作器标记为完成。

阶段	工作器	上下文
3	ln-821-npm-upgrader	隔离的子运行，包含 packageManager、runId 和确切的 summaryArtifactPath
3	ln-822-nuget-upgrader	隔离的子运行，包含 packageManager、runId 和确切的 summaryArtifactPath
3	ln-823-pip-upgrader	隔离的子运行，包含 packageManager、runId 和确切的 summaryArtifactPath

所有工作器：启动子运行时，检查点记录 child_run 元数据，然后显式调用工作器技能，并通过 record-worker-result 获取发出的 dependency-worker 摘要封装。

# One invocation per detected package manager (sequential per family):
node references/scripts/dependency-runtime/cli.mjs start --skill {worker} --identifier {packageManager} --manifest-file {workerManifestPath} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}
node references/scripts/optimization-runtime/cli.mjs checkpoint --phase PHASE_3_DELEGATE --payload '{"child_run":{"worker":"{worker}","run_id":"{childRunId}","summary_artifact_path":"{childSummaryArtifactPath}","package_manager":"{packageManager}"}}'
Skill(skill: "{worker}", args: "{packageManager} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
Read {childSummaryArtifactPath}
node references/scripts/optimization-runtime/cli.mjs record-worker-result --payload-file {childSummaryArtifactPath}

工作器令牌替换：{worker} 是 ln-821-npm-upgrader、ln-822-nuget-upgrader 或 ln-823-pip-upgrader 之一。

---

完成定义

• 运行时已启动，并使用经过验证的清单和稳定标识符
• 已根据项目指示检测包管理器
• 已完成预检安全性和发布时长检查
• 已为每个计划的工作器系列委派一个子运行
• 每个子运行都已发出有效的 dependency-worker 摘要
• 协调器报告汇总各工作器的升级、警告和验证结果
• 完成前已记录最终的 dependency-coordinator 摘要

---

阶段 7：元分析

可选参考：仅当用户要求运行后元分析或采用协议格式的运行回顾时，才加载 references/meta_analysis_protocol.md。

技能类型：optimization-coordinator。收到请求时，在所有阶段完成后运行。使用 optimization-coordinator 格式在聊天中输出。

---

版本： 1.1.0 最后更新： 2026-01-10