ln-645-open-source-replacer

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

开源替代方案

类型： L3 Worker

L3 Worker，通过 MCP Research 发现自定义模块、分析其用途，并寻找经过实战检验的开源替代方案。

目的与范围

• 发现重要的自定义模块（>=100 LOC，工具/集成类型）
• 通过阅读代码分析每个模块的用途（基于目标，而非基于模式）
• 通过 WebSearch、Context7、Ref 搜索开源替代方案
• 评估替代方案：星标数、维护情况、许可证、CVE 状态、API 兼容性
• 评定替代方案的可信度（HIGH/MEDIUM/LOW）
• 为可行的替代方案生成迁移计划
• 输出：运行时产物中的 Markdown 证据报告，以及供协调器传递的机器可读 JSON 摘要

范围之外：

• 基于模式检测已知的重复造轮子情况（自定义排序、手写验证）
• 软件包漏洞扫描（现有依赖项的 CVE/CVSS）
• 通过 OPT- 前缀进行故事级最优性检查

输入

- codebase_root: string        # Project root
- tech_stack: object            # Language, framework, package manager, existing dependencies
- output_dir: string            # e.g., ".hex-skills/runtime-artifacts/runs/{run_id}/audit-report"

# Domain-aware (optional, from coordinator)
- domain_mode: "global" | "domain-aware"   # Default: "global"
- current_domain: string                   # e.g., "users", "billing" (only if domain-aware)
- scan_path: string                        # e.g., "src/users/" (only if domain-aware)

工作流

必须阅读： 加载 references/two_layer_detection.md 以了解检测方法。 必须阅读： 加载 references/mcp_tool_preferences.md 和 references/mcp_integration_patterns.md

当架构或跨文件引用能显著提升模块发现效果时，优先使用 hex-graph。如果可用，读取本地代码时优先使用 hex-line。如果 MCP 不可用、不受支持或未编入索引，请继续使用内置的 Read/Grep/Glob/Bash，并在报告中说明所用的备用方案。

阶段 1：发现与分类

scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root

# Step 1: Find significant custom files
candidates = []
FOR EACH file IN Glob("**/*.{ts,js,py,rb,go,java,cs}", root=scan_root):
  IF file in node_modules/ OR vendor/ OR .venv/ OR dist/ OR build/ OR test/ OR __test__/:
    SKIP
  line_count = wc -l {file}
  IF line_count >= 100:
    candidates.append(file)

# Step 2: Filter to utility/library-like modules
utility_paths = ["utils/", "lib/", "helpers/", "common/", "shared/", "pkg/", "internal/"]
name_patterns = ["parser", "formatter", "validator", "converter", "encoder",
                 "decoder", "serializer", "logger", "cache", "queue", "scheduler",
                 "mailer", "http", "client", "wrapper", "adapter", "connector",
                 "transformer", "mapper", "builder", "factory", "handler"]

modules = []
FOR EACH file IN candidates:
  is_utility_path = any(p in file.lower() for p in utility_paths)
  is_utility_name = any(p in basename(file).lower() for p in name_patterns)
  export_count = count_exports(file)  # Grep for export/module.exports/def/class
  IF is_utility_path OR is_utility_name OR export_count > 5:
    modules.append(file)

# Step 3: Pre-classification gate
FOR EACH module IN modules:
  # Read first 30 lines to classify
  header = Read(module, limit=30)
  classify as:
    - "utility": generic reusable logic (validation, parsing, formatting, HTTP, caching)
    - "integration": wrappers around external services (email, payments, storage)
    - "domain-specific": business logic unique to project (scoring, routing, pricing rules)

  IF classification == "domain-specific":
    no_replacement_found.append({module, reason: "Domain-specific business logic"})
    REMOVE from modules

# Cap: analyze max 15 utility/integration modules per invocation
modules = modules[:15]

阶段 2：目标提取

FOR EACH module IN modules:
  # Read code (first 200 lines + exports summary)
  code = Read(module, limit=200)
  exports = Grep("export|module\.exports|def |class |func ", module)

  # Extract goal: what problem does this module solve?
  goal = {
    domain: "email validation" | "HTTP retry" | "CSV parsing" | ...,
    inputs: [types],
    outputs: [types],
    key_operations: ["validates email format", "checks MX records", ...],
    complexity_indicators: ["regex", "network calls", "state machine", "crypto", ...],
    summary: "Custom email validator with MX record checking and disposable domain filtering"
  }

阶段 3：替代方案搜索（MCP Research）

FOR EACH module WHERE module.goal extracted:
  # Strategy 1: WebSearch (primary)
  WebSearch("{goal.domain} {tech_stack.language} library package 2026")
  WebSearch("{goal.summary} open source alternative {tech_stack.language}")

  # Strategy 2: Context7 (for known ecosystems)
  IF tech_stack.package_manager == "npm":
    WebSearch("{goal.domain} npm package weekly downloads")
  IF tech_stack.package_manager == "pip":
    WebSearch("{goal.domain} python library pypi")

  # Strategy 3: Ref (documentation search)
  ref_search_documentation("{goal.domain} {tech_stack.language} recommended library")

  # Strategy 4: Ecosystem alignment -- check if existing project dependencies
  # already cover this goal (e.g., project uses Zod -> check zod plugins first)
  FOR EACH dep IN tech_stack.existing_dependencies:
    IF dep.ecosystem overlaps goal.domain:
      WebSearch("{dep.name} {goal.domain} plugin extension")

  # Collect candidates (max 5 per module)
  alternatives = top_5_by_relevance(search_results)

阶段 4：评估

必须： 在分配可信度之前，必须对每个候选方案执行安全检查和许可证分类。

FOR EACH module, FOR EACH alternative:
  # 4a. Basic info
  info = {
    name: "zod" | "email-validator" | ...,
    version: "latest stable",
    weekly_downloads: N,
    github_stars: N,
    last_commit: "YYYY-MM-DD",
  }

  # 4b. Security Gate (mandatory)
  WebSearch("{alternative.name} CVE vulnerability security advisory")
  IF unpatched HIGH/CRITICAL CVE found:
    security_status = "VULNERABLE"
    -> Cap confidence at LOW, add warning to Findings
  ELIF patched CVE (older version):
    security_status = "PATCHED_CVE"
    -> Note in report, no confidence cap
  ELSE:
    security_status = "CLEAN"

  # 4c. License Classification
  license = detect_license(alternative)
  IF license IN ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "Unlicense"]:
    license_class = "PERMISSIVE"
  ELIF license IN ["GPL-2.0", "GPL-3.0", "AGPL-3.0", "LGPL-2.1", "LGPL-3.0"]:
    IF project_license is copyleft AND compatible:
      license_class = "COPYLEFT_COMPATIBLE"
    ELSE:
      license_class = "COPYLEFT_INCOMPATIBLE"
  ELSE:
    license_class = "UNKNOWN"

  # 4d. Ecosystem Alignment
  ecosystem_match = alternative.name IN tech_stack.existing_dependencies
                    OR alternative.ecosystem == tech_stack.framework
  # Prefer: zod plugin over standalone if project uses zod

  # 4e. Feature & API Evaluation
  api_surface_match = HIGH | MEDIUM | LOW
  feature_coverage = percentage  # what % of custom module features covered
  migration_effort = S | M | L   # S=<4h, M=4-16h, L=>16h

  # 4f. Confidence Assignment
  # HIGH: >10k stars, active (commit <6mo), >90% coverage,
  #       PERMISSIVE license, CLEAN security, ecosystem_match preferred
  # MEDIUM: >1k stars, maintained (commit <1yr), >70% coverage,
  #         PERMISSIVE license, no unpatched CRITICAL CVEs
  # LOW: <1k stars OR unmaintained OR <70% coverage
  #      OR COPYLEFT_INCOMPATIBLE OR VULNERABLE

阶段 5：撰写报告与迁移计划

必须阅读： 加载 references/audit_worker_core_contract.md 和 references/templates/audit_worker_report_template.md。

根据 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会同时传入 runId 和 summaryArtifactPath；在独立模式下，Worker 会根据共享契约生成其自身的运行级产物路径。

在内存中构建报告，并写入 {output_dir}/645-open-source-replacer[-{domain}].md。

# Open Source Replacement Audit Report



## Checks

| ID | Check | Status | Details |
|----|-------|--------|---------|
| module_discovery | Module Discovery | passed/warning | Found N modules >= 100 LOC |
| classification | Pre-Classification | passed | N utility, M integration, K domain-specific (excluded) |
| goal_extraction | Goal Extraction | passed/warning | Extracted goals for N/M modules |
| alternative_search | Alternative Search | passed/warning | Found alternatives for N modules |
| security_gate | Security Gate | passed/warning | N candidates checked, M clean, K vulnerable |
| evaluation | Replacement Evaluation | passed/failed | N HIGH confidence, M MEDIUM |
| migration_plan | Migration Plan | passed/skipped | Generated for N replacements |

## Findings

| Severity | Location | Issue | Principle | Recommendation | Effort |
|----------|----------|-------|-----------|----------------|--------|
| HIGH | src/utils/email-validator.ts (245 LOC) | Custom email validation with MX checking | Reuse / OSS Available | Replace with zod + zod-email (28k stars, MIT, 95% coverage) | M |

## Migration Plan

| Priority | Module | Lines | Replacement | Confidence | Effort | Steps |
|----------|--------|-------|-------------|------------|--------|-------|
| 1 | src/utils/email-validator.ts | 245 | zod + zod-email | HIGH | M | 1. Install 2. Create schema 3. Replace calls 4. Remove module 5. Test |

阶段 6：返回摘要

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/645-open-source-replacer[-{domain}].md
Score: X.X/10 | Issues: N (C:0 H:N M:N L:N)

评分

使用 references/audit_scoring.md 中的标准惩罚公式：

penalty = (critical x 2.0) + (high x 1.0) + (medium x 0.5) + (low x 0.2)
score = max(0, 10 - penalty)

严重程度映射：

• HIGH： 对 >200 LOC 的模块有 HIGH 可信度的替代方案
• MEDIUM： 可信度为 MEDIUM，或对 100-200 LOC 的模块有 HIGH 可信度的替代方案
• LOW： 可信度为 LOW（仅部分覆盖）
• 例外： 未被 OSS 软件包覆盖的领域特定逻辑自定义模块 -> 跳过。功能对等度 <80% -> 跳过推荐。第 2 层： 推荐前确认替代方案具备完整的功能对等性

关键规则

必须阅读： 加载 references/audit_worker_core_contract.md。

• 以目标为依据，而非以模式为依据： 阅读代码以了解其用途，然后再搜索替代方案
• 必须进行 MCP 调研： 始终通过 WebSearch/Context7/Ref 搜索，绝不假设某个包存在
• 必须通过安全审查： 推荐任何包之前，先通过 WebSearch 搜索 CVE；绝不推荐存在未修复的 HIGH/CRITICAL CVE 的包
• 必须进行许可证分类： 优先选择宽松许可证（MIT/Apache/BSD）；仅在与项目兼容时选择 copyleft 许可证
• 与生态系统保持一致： 优先选择项目现有依赖树中的包（例如，项目使用 zod 时，优先选择 zod 插件，而非独立方案）
• 预分类审查： 在分析前对模块分类；排除特定领域的业务逻辑
• 不自动修复： 仅报告，绝不安装包或修改代码
• 合理评估工作量： S = <4h，M = 4-16h，L = >16h（迁移所需工作量高于简单修复）
• 限制分析范围： 每次调用最多分析 15 个模块，以控制 token 预算
• 始终提供证据： 每项发现都附上文件路径和行数

完成定义

必须阅读： 加载 references/audit_worker_core_contract.md。

• 已发现自定义模块（>= 100 LOC，工具/集成类型）
• 已应用预分类审查：排除特定领域的模块，并记录原因
• 已提取每个模块的目标（领域、输入、输出、操作）
• 已通过 MCP 调研（WebSearch、Context7、Ref）搜索开源替代方案
• 已通过安全审查：通过 WebSearch 检查所有候选方案是否存在 CVE
• 已对每个候选方案进行许可证分类：宽松许可证/著佐权许可证/未知
• 已检查生态系统一致性：考虑了项目现有依赖
• 已对每项替换方案评定置信度（HIGH/MEDIUM/LOW）
• 已为置信度为 HIGH/MEDIUM 的替换方案生成迁移计划
• 已将报告写入 {output_dir}/645-open-source-replacer[-{domain}].md
• 已按约定撰写摘要

参考文件

• 评分算法： references/audit_scoring.md
• 必须阅读： 加载 references/research_tool_fallback.md

---

版本： 1.0.0 最后更新： 2026-02-26