reverse-engineer

逆向工程

将外部系统逆向工程为两项内容：拆解报告（功能清单、阅读位置索引、CLI 和契约规范，以及可选的安全审计）和借鉴方案图（决定哪些内容纳入我们的界面，哪些内容不予采用）。必须引用证据的决策条目，任何人都可以重新核查；仅凭印象做出的决策，连作者本人也无法重新核查。本技能旨在防止的，正是根据竞争对手的 README 做出决策。

⚠️ 约束 — 严格护栏（必须遵守）

• 仅分析你拥有或已获得明确书面授权的代码/二进制文件——这一点很重要，因为未经授权的拆解会触及法律/IP 的界限。
• 不得提供绕过保护措施/服务条款或提取专有源代码/系统提示词的步骤。
• 不得输出还原出的专有源代码或内嵌提示词（仅编制索引；在报告中脱敏）——以避免复现受保护的 IP。
• 如发现机密/令牌/密钥，必须脱敏。输出验证器会在每个阶段对整个输出目录运行本技能的 scripts/security/scan_secrets.sh；只要检测到命中项，就必须先脱敏，否则验证会失败。
• 始终区分文档所述、代码所证和托管/控制平面。

证据规则

• 按来源标记每项能力。 code：其源代码或二进制文件能证明该能力；引用你打开过的文件:行号（对于二进制文件，引用拆解输出行），并记录代码实际执行的操作，这通常比其宣称的范围更窄。docs：README、文档页或公告中有所描述；尚未验证。hosted：你无法检查的服务或控制平面。
• 索引只是索引，不是证据。 它会列出阅读位置。在代码库模式下，其分组以 impl: unclassified 开头（二进制模式会写入以 binary-symbols.txt 为锚点的 client 分组，但仍不构成 code 证据）；client 或 mixed 需要锚点，而 control-plane 表示 hosted。索引条目本身绝不能让某一行成为 code。
• 无法访问代码，就不能借鉴。 如果只有文档、README 或落地页，那么所有有关其实现的条目都属于 docs，且未经验证。此类条目可以标记为 gap、park 或 reject，但绝不能标记为 steal。
• 在实时工作树中验证我方情况。 have 条目必须引用我方文件。每个“缺失”条目都必须附带证明其缺失的搜索记录（命令和范围）。将任何内容判定为缺失之前，先检查我方现有技术栈已经提供了什么。
• 借鉴前重新打开文件。 将某项标记为 steal 之前，必须重新打开每个引用的文件；凭记忆整理的摘要不算证据。
• 借鉴的是模式，不是平台。 对方的健壮性通常来自一个想法（统一化、门控、协调循环）。应使用我方原语重新表达；绝不要引入对方的运行时或存储引擎。

阶段 1 — 拆解

<skill-dir> 是包含此 SKILL.md 的目录。Claude Code 将其显示为“此技能的基目录”；Codex 会列出此技能的 SKILL.md 路径；在 AgentOps 源代码检出中，它是 skills/reverse-engineer。运行命令前，请将 <skill-dir> 替换为该绝对路径。工作目录仍是用户的代码仓库。如果宿主未显示此技能的安装位置，请使用你读取的 SKILL.md 所在目录。如果无法确定，请勿猜测路径，也不要从当前代码仓库运行同名脚本；请说明捆绑脚本不可用，并按下方仅文档模式中的说明手动构建清单和借鉴映射。

使用经过授权的克隆或二进制文件时，脚本会克隆（固定版本）、扫描 CLI/配置/制品相关内容，写入清单、注册表和规范，并验证拆解结果：

python3 "<skill-dir>/scripts/reverse_engineer.py" <product> --mode=repo \
  --upstream-repo="https://github.com/org/repo.git" --upstream-ref=v1.0.0 \
  --output-dir=".agents/scratch/reverse-engineer/<product>/"

除非通过 --local-clone-dir 指定其他位置，否则克隆内容会放在当前目录下的 .tmp/<product>/ 中；请勿将其提交。二进制模式需要 --authorized；如果未获准使用真实二进制文件，请运行 bash "<skill-dir>/scripts/self_test.sh"，此命令会构建一个演示二进制文件（需要 Go）。标志、完整输出列表、测试夹具和测试见调用参考。

如果无法访问代码（只有 README、文档网站或落地页），请跳过脚本：手动构建清单和借鉴映射，并为每一行标注 docs 或 hosted，同时说明未运行拆解验证器。如果代码可读但脚本无法运行，请直接阅读代码，并为每个 code 行注明 file:line；仍须报告验证器缺失这一情况。

阶段 2 — 借鉴映射

将每项能力映射到我们在 .agents/scratch/reverse-engineer/<product>/steal-map.md 中的现有实现。脚本会在验证阶段 1 后停止；它无法如实判断我们的当前代码树是否具备、缺少或应采用某项能力。调用方应根据拆解结果、拆解结果指向的代码，以及对我们代码仓库的最新检查来编写映射。缺失或格式错误的映射意味着技能结果不完整，不能把脚本成功重新标记为一项决策。

对方的能力	我们当前的实现	判定
<feature>（代码：<file:line>）、（文档）或（托管服务）	<我们的文件 / 技能 / CLI>，或填写“无”并附上证明这一点的搜索记录	已有 / 缺口 / 借鉴 / 暂缓 / 拒绝

每一行必须且只能有一个判定：

• 已有 — 我们当前的代码树已实现此功能；注明文件并确认仍然有效。
• 借鉴 — 我们缺少此功能，code 证据展示了对方的实现方式，而且它能推进我们的核心目标。采用其模式，并用我们的原语重新表达。
• 缺口 — 我们缺少此功能，若其经验证有效，我们会希望具备；但尚不足以判定应借鉴：对方的机制只有 docs 或 hosted 证据，或尚未证明其对我们核心目标的价值。指出需要哪些证据才能作出判断。
• 暂缓 — 此功能确实存在，但目前有意不由我们构建：这是我们委托给其他方的底层能力（对于 AgentOps，ADR-0009 规定调度、监督和队列由外部负责），或依赖于我们尚未下注的方向。注明该功能，但不要构建。
• 拒绝 — 与我们的原则冲突（例如，没有检查支撑的完成边界；而我们要求检查和 CI，并且对代价高昂的错误进行一次新的判断）。

如果两个判定似乎都适用，则拒绝优先于暂缓，暂缓优先于借鉴或缺口；借鉴与缺口之间则由证据决定。

验证与交接

编写完 steal-map.md 后，使用 $output_dir、$security_audit、$sbom 和 $upstream_ref_set（每个标志均为数值 0|1）验证完整输出：

bash "<skill-dir>/scripts/validate-output.sh" \
  --output-dir "$output_dir" --phase complete \
  --security-audit "$security_audit" --sbom "$sbom" \
  --upstream-ref-set "$upstream_ref_set"

如果有任何表格行缺少来源标签或五种判定之一，或者任何 steal 缺少 code 证据，验证就会失败；如果有上游引用，则要求在 clone-metadata.json 中包含解析后的提交。交接前必须以 0 退出，否则报告会说明验证未运行（仅文档模式）。

如果采纳某项 steal 属于单向门（架构分叉、新建有界上下文、存储或数据迁移），请勿在此处做出决定：将通过验证的 steal-map 交给 Plan，由其在现有意图源中制定所选方案。Idea Genie 的 duel 模式或 Premortem 可将其作为咨询性证据提出质疑；两者都不授予就绪或继续执行的权限。普通的 have、park 和 reject 行都是有证据支持的终局决策。

如需探索某个外部系统以外的一般主题，请使用 Research。reverse-engineer.feature 中的场景记录了相关行为；此技能的 scripts/validate.sh 和 scripts/self_test.sh 会对其进行检查。