用途
ln-831-oss-replacer 是一个 L3 Worker 类型的技能，属于 8XX Optimization 分类。它执行来自 ln-645-architecture-modernization-auditor 的 OSS 替换计划。对于每个存在可行 OSS 替代方案的自定义模块，它会安装软件包、重写导入、运行验证，然后原子化地保留或丢弃。
主要能力
- 输入：来自审计输出的迁移计划，或一个目标模块。
- 输出：被替换的模块，以及一份机器可读的现代化摘要。
- 配套：ln-645-architecture-modernization-auditor 识别候选，ln-831 执行替换。
工作流程
阶段：Pre-flight -> Load Plan -> Prioritize -> Replace Loop -> Report
Phase 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。独立运行仍受支持；如果省略运行时参数，则在返回前生成一个独立运行范围的工件。
Phase 1：加载迁移计划
从审计报告中提取：custom_module（自定义实现路径）、loc（自定义模块代码行数）、oss_package（推荐的 OSS 替代）、confidence（HIGH、MEDIUM 或 LOW）、api_mapping（自定义函数到 OSS 等价物的映射）。如果不存在审计报告，则分析目标模块并搜索 Context7 或 Ref 以寻找可行的 OSS 替代方案。
强制阅读：加载 references/research_tool_fallback.md
Phase 2：替换优先级
优先级 1：HIGH 置信度且 >200 LOC；优先级 2：HIGH 置信度且 100-200 LOC；优先级 3：MEDIUM 置信度且 >200 LOC；优先级 4：MEDIUM 置信度且 100-200 LOC；跳过：LOW 置信度。
Phase 3：替换循环（保留/丢弃）
每个模块的循环：安装 OSS 包 -> 使用 api_mapping 更新导入和调用点 -> 运行测试；若测试失败则丢弃并回滚该候选的所有更改 -> 仅在验证通过后保留 -> 保留后删除旧自定义模块 -> 记录结果用于最终报告。
停止条件：所有候选处理完毕则停止并报告；连续 3 次丢弃则警告并停止等待人工审查；测试基础设施本身损坏则停止并回滚到最后一个已知良好状态；没有超过置信度阈值的候选则停止并报告无可行的替换。
丢弃时的原子回滚：已安装的包则卸载；已修改的文件则恢复模块文件；锁文件已更改则恢复锁文件。
安全规则：一次只处理一个模块，绝不同时替换多个模块；不允许 API 签名漂移，公共接口必须保持兼容；需要测试，当风险不明确时跳过没有覆盖的模块；置信度门控，跳过 LOW 置信度的替换。
Phase 4：报告结果
报告字段包括：source（审计报告路径或目标模块）、candidates_total（替换候选总数）、replacements_applied（成功替换的模块）、replacements_discarded（失败的替换及原因）、replacements_skipped（因低置信度或缺少测试而跳过）、loc_removed（移除的自定义代码总行数）、packages_added（新安装的 OSS 包）、details[]（每个替换的摘要）、artifact_path（持久化 worker 报告路径，如果已写入）。
配置
选项：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。