reverse-engineer-rpi

/reverse-engineer-rpi

对产品进行逆向工程，生成可通过机器验证的功能清单、注册表和规范集，并可选生成安全审计工件和验证门禁。

严格护栏（强制）

• 仅分析你拥有或已获得明确书面授权的代码／二进制文件。
• 不得提供绕过保护措施／服务条款或从第三方产品提取专有源代码／系统提示词的步骤。
• 不得输出从二进制文件中重建的专有源代码或嵌入式提示词（仅建立索引；在报告中进行编辑遮盖）。
• 如发现机密信息／令牌／密钥，应将其编辑遮盖；对输出运行机密信息扫描门禁。
• 始终区分：文档说明、代码证实与托管／控制平面。

单命令示例

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py ao \
  --authorized \
  --mode=binary \
  --binary-path="$(command -v ao)" \
  --output-dir=".agents/research/ao/"

如果你没有明确的书面授权来分析该二进制文件，请勿运行上述命令。请改用随附的演示固件（参见下文的自测）。

仅针对仓库的示例（无需二进制文件）：

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --output-dir=".agents/research/cc-sdd/"

固定克隆版本（可复现）：

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --upstream-ref=v1.0.0 \
  --output-dir=".agents/research/cc-sdd/"

调用约定

必需：

• product_name

可选：

• --docs-sitemap-url（有条件时建议提供；支持 https://... 和 file:///...）
• --docs-features-prefix（默认值：auto；检测最佳本地文档前缀，若未检测到则回退到 docs/features/）
• --upstream-repo（可选）
• --upstream-ref（将克隆固定到特定提交、标签或分支；在 clone-metadata.json 中记录解析后的 SHA）
• --local-clone-dir（默认值：.tmp/<product_name>）
• --output-dir（默认值：.agents/research/<product_name>/）
• --mode（默认值：repo；允许值：repo|binary|both）
• --binary-path（如果 --mode 包含 binary，则为必需）
• --no-materialize-archives（仅限已获授权的情况；二进制模式默认会提取嵌入的 ZIP；此选项会禁用提取，仅保留索引）

安全审计标志（可选）：

• --security-audit（启用安全工件和门禁）
• --sbom（在可行时生成 SBOM 和依赖风险报告；可能会跳过并附带说明）
• --fuzz（仅当存在安全的测试框架时使用；限定运行时长）

强制护栏标志：

• --authorized（二进制模式必需；未提供时拒绝运行二进制分析）

固定上游引用（--upstream-ref）

使用 --upstream-ref 将仓库模式的克隆固定到特定提交、标签或分支。这样可以确保分析可复现，并可将黄金固件与已知基线进行差异比较。

# Pin to a tag (reproducible)
python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --upstream-ref=v1.0.0 \
  --output-dir=".agents/research/cc-sdd/"

# Pin to a specific commit SHA
python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --upstream-ref=abc1234 \
  --output-dir=".agents/research/cc-sdd/"

提供 --upstream-ref 时：

• 使用 git fetch --depth=1 origin <ref> 获取克隆，并检出 FETCH_HEAD。
• 将解析后的提交 SHA 记录到 output_dir/clone-metadata.json 中，以便追溯。
• 如果未提供 --upstream-ref，则会浅克隆默认分支的 HEAD，深度为 --depth=1。

clone-metadata.json 模式：

{
  "upstream_repo": "https://github.com/gotalab/cc-sdd.git",
  "upstream_ref": "v1.0.0",
  "resolved_commit": "<full SHA>",
  "clone_date": "YYYY-MM-DD"
}

契约输出（output_dir/）

仓库模式分析会在 output_dir/ 下写入可供机器检查的契约文件。这些文件仅使用相对路径、排序后的列表和稳定键——不包含绝对路径或每次运行都不同的时间戳——因此可以提交为黄金固件，并在不同运行之间进行差异比较。

主要契约文件：

文件	说明
feature-registry.yaml	结构化功能清单，包含通过机械方式提取的 CLI、配置／环境变量和工件接口
cli-surface-contracts.txt	CLI 接口：命令、标志、帮助文本、框架、语言
docs-features.txt	从文档中提取的功能（文档说明与代码证实）
clone-metadata.json	上游仓库 URL、固定引用、解析后的提交 SHA、克隆日期

feature-registry.yaml 结构示例：

schema_version: 1
product_name: cc-sdd
upstream_commit: "abc1234..."
features:
  - name: cli-entry
    cli:
      language: node
      bin:
        cc-sdd: dist/cli.js
      help_text: "Usage: cc-sdd [options] ..."
  - name: config-surface
    config_env:
      config_file: ".cc-sdd/config.json"
      env_vars:
        - name: CC_SDD_TOKEN
          evidence: ["src/config.ts"]

注意：契约输出由 --mode=repo（或 --mode=both）写入。二进制模式输出（binary-analysis.md、binary-symbols.txt 等）仍直接写入 output_dir/ 下。

固件测试工作流

黄金固件可用于检测回归：提交已知良好的固件快照（契约文件与固定的 clone-metadata.json 一同保存），然后将未来的运行结果与其进行差异比较。

运行 Fixture 测试

bash skills/reverse-engineer-rpi/scripts/repo_fixture_test.sh

此脚本（在 ag-w77.3 中实现）：

1. 读取 skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/clone-metadata.json，以确定固定的上游引用。
2. 在仓库模式下，使用该引用运行 reverse_engineer_rpi.py，并将输出写入临时目录。
3. 将生成的输出与已提交的黄金 Fixture（feature-registry.yaml、cli-surface-contracts.txt、docs-features.txt）进行差异比较。
4. 如果内容匹配则以 0 退出；如果存在偏差，则以非零状态退出并输出统一差异。

此测试需要网络访问权限，以便克隆上游仓库。

更新 Fixture

当合约发生合理变更时（新增标志、新增环境变量、架构升级），请更新黄金 Fixture：

# 1. Re-run with the pinned ref to generate fresh contracts
python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --upstream-ref=<new-tag-or-sha> \
  --output-dir=".tmp/cc-sdd-refresh/"

# 2. Copy contracts into the fixture directory
cp .tmp/cc-sdd-refresh/feature-registry.yaml \
  skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/feature-registry.yaml

# 3. Update the pinned clone metadata
cp .tmp/cc-sdd-refresh/clone-metadata.json \
  skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/clone-metadata.json

# 4. Commit the updated fixtures
git add skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/
git commit -m "fix(reverse-engineer-rpi): update cc-sdd golden fixtures to <new-tag-or-sha>"

测试通过所需提交的 Fixture 文件：

• skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/clone-metadata.json
• skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/feature-registry.yaml
• skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/cli-surface-contracts.txt
• skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/docs-features.txt

脚本驱动的工作流

运行：

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py <product_name> --authorized [flags...]

这会在 output_dir/ 下生成所需输出，并在适用时生成 .agents/council/ 和 .agents/learnings/。

输出（必须生成）

output_dir/ 下的核心输出：

1. feature-inventory.md
2. feature-registry.yaml
3. validate-feature-registry.py
4. feature-catalog.md
5. spec-architecture.md
6. spec-code-map.md
7. spec-cli-surface.md（检测到 Node、Python 或 Go CLI 时生成；否则会在 spec-code-map.md 中写入说明）
8. spec-clone-vs-use.md
9. spec-clone-mvp.md（原始 MVP 规格；不要从目标中复制）
10. clone-metadata.json（使用 --upstream-repo 时生成；记录解析后的提交 SHA）

二进制模式额外输出：

• binary-analysis.md（尽力生成的摘要）
• binary-embedded-archives.md（仅索引；不转储）

仓库模式额外输出：

• spec-artifact-surface.md（尽力生成；由模板/清单驱动的安装界面）
• artifact-registry.json（尽力生成；存在清单/模板时提供带哈希的模板清单）

如果指定了 --security-audit，还需创建 output_dir/security/：

• threat-model.md
• attack-surface.md
• dataflow.md
• crypto-review.md
• authn-authz.md
• findings.md
• reproducibility.md
• validate-security-audit.sh

自测（验收标准）

端到端 Fixture（包含嵌入式 ZIP 的安全、自有演示二进制文件）：

bash skills/reverse-engineer-rpi/scripts/self_test.sh

必须显示：

• 已生成特性清单
• 已生成注册表
• 注册表验证器以 0 退出
• 在安全模式下：validate-security-audit.sh 以 0 退出，且机密扫描通过

示例

场景：在仓库模式下对开源 CLI 进行逆向工程

用户说： /reverse-engineer-rpi cc-sdd --mode=repo --upstream-repo="https://github.com/gotalab/cc-sdd.git" --upstream-ref=v1.0.0

执行过程：

1. 脚本会在固定标签 v1.0.0 处浅克隆上游仓库，并将解析后的 SHA 记录到 clone-metadata.json。
2. 它会扫描仓库中的 CLI 入口点、配置/环境变量界面、架构文件和制品清单，然后在输出目录下写入 feature-inventory.md、feature-registry.yaml、合约 JSON 以及所有规格文件。

结果： 完整的特性目录和可供机器检查的 feature-registry.yaml 会生成在 .agents/research/cc-sdd/ 下，可用于与黄金 Fixture 进行差异比较。

场景：通过安全审计进行二进制分析

用户输入： /reverse-engineer-rpi ao --authorized --mode=binary --binary-path="$(command -v ao)" --security-audit

执行过程：

1. 脚本对 ao 二进制文件运行静态分析（文件元数据、链接库、嵌入式归档签名），并写入 binary-analysis.md 和 binary-embedded-archives.md。
2. 脚本在 output_dir/security/ 下生成完整的安全审计套件（threat-model.md、attack-surface.md、findings.md 等），并对所有输出运行机密扫描门禁。

结果： 生成二进制分析产物和经过验证的安全审计；validate-security-audit.sh 以 0 退出，确认所有安全交付物均已生成且不含机密。

故障排除

问题	原因	解决方案
脚本拒绝运行二进制分析	缺少 --authorized 标志	添加 --authorized，确认你已获得分析该二进制文件的明确书面授权。
未生成 clone-metadata.json	未提供 --upstream-repo	传入 --upstream-repo（以及可选的 --upstream-ref），以启用克隆元数据跟踪。
Fixture 测试差异意外失败	上游仓库已更改，或黄金 fixture 已过时	使用固定的 ref 重新运行，将新的合约复制到 fixtures/，并提交更新后的黄金文件（参见更新 Fixture）。
未生成 spec-cli-surface.md	仓库中未检测到可识别的 CLI 框架（Node/Python/Go）	检查目标仓库是否有可发现的 CLI 入口点；否则，CLI 表面会记录在 spec-code-map.md 中。
仓库克隆期间发生网络错误	防火墙、VPN 或 GitHub 速率限制阻止了浅克隆	检查网络连接；如果仓库是私有的，请使用 gh auth login 进行身份验证；或者使用 --local-clone-dir 指向预先克隆的目录。

参考文档

• references/reverse-engineer-rpi.feature — 可执行规范：仓库模式功能目录和代码映射、二进制模式安全审计、持久化规范产物（soc-qk4b）