ln-831-oss-replacer

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

ln-831-oss-replacer

类型： L3 Worker 类别： 8XX 优化

执行 ln-645-architecture-modernization-auditor 制定的 OSS 替换计划。对于每个存在可行 OSS 替代方案的自定义模块：安装软件包、重写导入、运行验证，然后以原子方式保留或丢弃。

---

概述

方面	详情
输入	审计输出中的迁移计划或目标模块
输出	已替换模块以及机器可读的现代化摘要
配套工具	ln-645-architecture-modernization-auditor 识别候选项，ln-831 执行替换

---

工作流

阶段： 预检 -> 加载计划 -> 排定优先级 -> 替换循环 -> 报告

---

阶段 0：预检

检查项	必需	缺失时的操作
迁移计划或目标模块	是	阻止替换
测试基础设施	是	阻止替换
包管理器可用	是	阻止替换
工作区基线安全	是	在托管运行中，协调器已做好准备；在独立运行中，在本地保护回滚能力

必须阅读： 加载 references/ci_tool_detection.md 以检测测试。 工具策略：遵循宿主 AGENTS.md 中的 MCP 偏好；仅当宿主策略缺失或 MCP 行为不明确时，才加载 references/mcp_tool_preferences.md 和 references/mcp_integration_patterns.md。

如果可用，优先使用 hex-line 进行本地代码编辑和读取；当跨文件引用检查能显著提升替换安全性时，优先使用 hex-graph。如果 MCP 不可用、不受支持或未建立索引，则使用内置的 Read/Grep/Glob/Bash 继续，并在摘要中说明回退方案。

运行时协调

托管运行会从 ln-830 接收确定性的 runId 和精确的 summaryArtifactPath。 仍支持独立运行；如果省略运行时参数，则在返回前生成一个作用域为该次独立运行的产物。

---

阶段 1：加载迁移计划

从审计报告中提取：

字段	说明
custom_module	自定义实现的路径
loc	自定义模块中的代码行数
oss_package	推荐的 OSS 替代方案
confidence	HIGH、MEDIUM 或 LOW
api_mapping	自定义函数到 OSS 等效项的映射

如果不存在审计报告，则分析目标模块，并搜索 Context7 或 Ref，寻找可行的 OSS 替代方案。

必须阅读： 加载 references/research_tool_fallback.md

---

阶段 2：排定替换优先级

优先级	标准
1	HIGH 置信度且超过 200 LOC
2	HIGH 置信度且为 100-200 LOC
3	MEDIUM 置信度且超过 200 LOC
4	MEDIUM 置信度且为 100-200 LOC
跳过	LOW 置信度

---

阶段 3：替换循环（保留/丢弃）

每个模块的循环：

FOR each replacement candidate:
  1. INSTALL: add the OSS package
  2. REWRITE: update imports and call sites using api_mapping
  3. VERIFY: run tests
     IF tests fail -> DISCARD and revert all changes for this candidate
  4. KEEP: only after verification passes
  5. DELETE: remove old custom module after keep
  6. LOG: record result for the final report

停止条件：

条件	操作
所有候选项均已处理	停止并报告
连续丢弃 3 次	发出警告并停止，等待人工审查
测试基础设施本身发生故障	停止并回滚到上一个已知良好状态
没有达到置信度阈值的候选项	停止并报告没有可行的替代方案

丢弃时的原子回滚：

步骤	回滚操作
已安装软件包	卸载该软件包
已修改文件	恢复模块文件
锁文件已更改	恢复锁文件

安全规则：

规则	说明
一次处理一个模块	绝不同时替换多个模块
不得改变 API 签名	必须保持公共接口兼容
必须有测试	风险不明确且没有覆盖时，跳过该模块
置信度门槛	跳过 LOW 置信度的替换

---

阶段 4：报告结果

字段	描述
source	审计报告路径或目标模块
candidates_total	替换候选项总数
replacements_applied	已成功替换的模块
replacements_discarded	替换失败的模块及原因
replacements_skipped	因置信度较低或缺少测试而跳过的模块
loc_removed	移除的自定义代码总行数
packages_added	新安装的 OSS 包
details[]	每项替换的摘要
artifact_path	持久化的工作器报告路径（如已写入）

---

配置

Options:
  audit_report: "docs/project/codebase_audit.md"
  target_module: ""
  min_confidence: "MEDIUM"
  run_tests: true
  require_test_coverage: true
  delete_old_module: true

---

错误处理

错误	原因	解决方案
未找到包	OSS 包名称已更改	查阅最新文档，查找新的包名称
API 不匹配	映射与实际库 API 不一致	查阅文档，仅在修复方案明确时重试
循环依赖	新包与当前架构冲突	跳过并报告，后续手动处理
没有测试覆盖	自动替换风险过高	跳过并报告

---

参考资料

• ../ln-645-architecture-modernization-auditor/SKILL.md
• references/ci_tool_detection.md
• references/research_tool_fallback.md
• references/epistemic_protocol.md

---

运行时摘要产物

必须阅读： 加载 references/coordinator_summary_contract.md

生成 modernization-worker 摘要信封。

托管模式：

• ln-830 会传递确定性的 runId 和准确的 summaryArtifactPath
• 将摘要写入提供的 summaryArtifactPath

独立模式：

• 省略 runId 和 summaryArtifactPath
• 写入 .hex-skills/runtime-artifacts/runs/{run_id}/modernization-worker/ln-831--{identifier}.json

Monitor（2.1.98+）： 对于预计超过 30 秒的安装与测试验证循环，请使用 Monitor。回退方案：Bash(run_in_background=true)。

完成标准

• 已加载迁移计划或分析目标模块
• 已按置信度和代码缩减价值确定候选项优先级
• 每项替换均以原子方式执行，并验证保留或丢弃
• 已完全还原被丢弃的替换
• 仅在验证通过后，保留的替换才会移除旧的自定义代码
• 报告记录已应用、已丢弃、已跳过的替换项以及移除的 LOC
• 已将 modernization-worker 摘要产物写入托管或独立模式的路径

---

版本： 1.0.0 最近更新： 2026-03-08