advaidg/reverse-engineer-agent

# 逆向工程 Agent 一个完整的 Agent 系统，能够对任何应用进行逆向工程——无论是代码库还是已部署的应用——并生成结构化的、基于证据的知识文档。 **一次安装即可同时支持 GitHub Copilot (VS Code) 和 Claude Code。** ## 生成内容 一个包含以下内容的 `docs/re/` 文件夹： ``` docs/re/ ├── 00-plan.md # Run plan, target ID, scope flags ├── 01-inventory.md # File tree, languages, deps, build, entry points ├── 02-architecture.md # Components, layers, sequence diagrams, debt ├── 03-data-model.md # Stores, ER diagrams, ORM drift, PII inventory ├── 04-api.md # Every endpoint, schema, auth, rate limits ├── 05-behavior.md # State machines, business rules, jobs, edge cases ├── 06-security.md # AuthN/AuthZ, STRIDE, CVEs, compliance ├── 07-infrastructure.md # Hosting, IaC, CI/CD, observability, cost ├── 08-history.md # Git timeline, ownership, bus factor, dead code ├── KNOWLEDGE.md # ★ Final integrated knowledge document └── openapi.generated.yaml # Generated OpenAPI 3.1 stub if missing ``` `KNOWLEDGE.md` 是最终交付物——一份单一、可导航且引用密集的文档，能够让新工程师（或审计员、收购方，以及未来的你）无需与原作者交流即可理解整个系统。 ## 为什么一次安装适用于两种工具 VS Code 中的 GitHub Copilot 会读取 `.github/agents/` **和** `.claude/agents/` 目录。 Claude Code 会读取 `.claude/agents/` 目录。这两种工具都支持 Claude 子 Agent 格式。因此，整个包只需存放在一个位置。 ## Agent 组合包 | Agent | 阶段 | 目的 | 工具 | 模型 | |-------|-------|---------|-------|-------| | `reverse-engineer` | 协调器 | 协调流水线 | RW + web | Opus | | `cartographer` | 1 | 清单：文件树、语言、依赖、构建 | 只读 | Sonnet | | `architect` | 2 | 架构：组件、流转、技术债务 | 只读 | Opus | | `data-modeler` | 3 | 数据：存储、ER图、PII、偏差 | 只读 | Opus | | `api-inspector` | 4 | API 接口：REST/gRPC/GQL/WS/队列 | 只读 | Opus | | `behavior-tracer` | 5 | 行为：状态、规则、任务、边界 | 只读 | Opus | | `security-auditor` | 6 | 安全：AuthN/Z、STRIDE、CVEs | Read + web | Opus | | `infra-scout` | 7 | 基础设施：托管、IaC、CI/CD、可观测性 | Read + web | Sonnet | | `history-archaeologist` | 8 | Git 历史、所有权、死代码 | 只读 | Sonnet | | `documentation-synthesizer` | 9 | 最终整合的 `KNOWLEDGE.md` | Read + Write | Opus | ## 安装 — 选项 A：按项目安装 将 `.claude/` 目录复制到你要分析的代码库的根目录： ``` cp -r reverse-engineer-agent/.claude /path/to/target-repo/ ``` 两种工具都会自动识别它。 ## 安装 — 选项 B：全局安装（适用于所有项目） 将 Agent 放在你的主目录中，以便在每个工作区中都能使用它们。 **Claude Code (任何操作系统):** ``` mkdir -p ~/.claude/agents cp reverse-engineer-agent/.claude/agents/*.md ~/.claude/agents/ ``` **VS Code Copilot (用户级别):** ``` # macOS / Linux mkdir -p ~/.copilot/agents cp reverse-engineer-agent/.claude/agents/*.md ~/.copilot/agents/ # Windows (PowerShell) mkdir -Force $env:USERPROFILE\.copilot\agents copy reverse-engineer-agent\.claude\agents\*.md $env:USERPROFILE\.copilot\agents\ ``` ## 安装 — 选项 C：一行命令安装器 **macOS / Linux:** ``` bash <(curl -fsSL https://raw.githubusercontent.com/advaidg/reverse-engineer-agent/main/install.sh) ``` **Windows (PowerShell):** ``` iwr -useb https://raw.githubusercontent.com/advaidg/reverse-engineer-agent/main/install.ps1 | iex ``` 安装器会询问你希望将 Agent 放置在何处（Claude 全局、Copilot 全局，还是当前项目），并进行复制。 ## 使用说明 ### 在 VS Code Copilot 中 1. 打开 Chat 面板 (Ctrl/Cmd+Alt+I)。 2. 点击 Agent 下拉菜单——你会看到列表中的 **reverse-engineer**。 3. 选择它。输入你的目标： 或者专注于特定维度： 4. 协调器将运行每个阶段，并在每个阶段后发布 3 行更新， 并将所有输出写入 `docs/re/`。最终的 `KNOWLEDGE.md` 就是你的 交付物。 你也可以直接调用任何专家——例如，仅对现有清单运行安全 审计： ### 在 Claude Code 中 ``` cd /path/to/target-repo # 最简单：在普通会话中通过提及来调用 claude > @reverse-engineer reverse-engineer this repo, depth=standard # 或者：以 orchestrator 身份启动整个会话 claude --agent reverse-engineer > Begin. Target is the current repo. # 列出可用的 agents claude agents ``` 你也可以单独使用任何专家： ``` claude --agent security-auditor > Audit the codebase. Output to docs/re/06-security.md ``` ## 范围标记 在你的提示中传递这些标记以控制深度： | 标记 | 默认值 | 效果 | |------|---------|--------| | `depth=quick` | — | 仅阶段 1–4 + 9（中型代码库约需 1 小时） | | `depth=standard` | ✓ | 所有 9 个阶段 | | `depth=deep` | — | 所有阶段 + 运行测试 + 依赖项 CVE 深度扫描 | | `focus=security` | — | 优先运行安全阶段；遇到严重发现时直接短路结束 | | `focus=data` | — | 优先考虑数据模型；适用于迁移规划 | | `focus=api` | — | 优先考虑 API 接口；适用于客户端 SDK 生成 | | `focus=ui` | — | 优先考虑前端行为 | | `focus=all` | ✓ | 标准顺序 | | `format=md` | ✓ | 仅 Markdown | | `format=html` | — | 将最终 KNOWLEDGE.md 转换为 HTML | | `format=both` | — | 两者皆有 | 示例： ## 目标 协调器处理三种目标类型： 1. **本地路径**（默认）：当前工作区或子路径 2. **Git URL**：首先克隆到 `/tmp/re-target/` 3. **已部署的应用 URL**（黑盒）：仅运行阶段 4 + 阶段 5， 针对线上 API 使用 web 抓取。所有其他阶段标记为 `N/A — black-box analysis`。 ## 设计说明 - **证据优先于推断。** 最终文档中的每一项声明都可 追溯到 `[file:line]` 或 `[commit-sha]`。推断会 明确标记为 `⟦INFERRED⟧` 并附带置信度。 - **默认只读。** 阶段 1–8 严格为只读。只有 协调器和整合器可以写入——并且仅限于 `docs/re/`。 - **可恢复。** 每个阶段在下一个阶段运行前持久化其输出。 随时可以在任何阶段停止和恢复。 - **Token 高效。** 子 Agent 在它们自己的上下文窗口中运行， 因此庞大的发现结果不会污染协调器的上下文。只有摘要 会向上回传。 - **多语言感知。** Agent 会检测技术栈并自我适应。它们不会 假设特定的语言或框架。 - **引用图表。** 每个 mermaid 图表中的每个节点都对应 代码中的具体内容，而非理想化的架构。 ## 自定义 每个 Agent 都是一个带有 YAML frontmatter 的单一 Markdown 文件。想要增加一个用于性能分析的第十阶段？添加 `performance-profiler.md` 并将其注册到协调器的流水线列表中。想要将整合器替换为生成 Confluence 标记的工具？修改输出契约即可。 ## 限制 - 仅限静态分析——Agent 永远不会运行系统 （除了 `git`、`find`、清单读取器，以及可选的读取清单的 CVE 扫描器）。 - 无实时数据库、云或 API 访问权限——Agent 读取 IaC 和 配置，但不会向任何内容进行认证。 - 对于真正庞大的代码库（超过 100 万行代码），建议使用限定为 一次一个限界上下文的 `focus=` 运行。 - 不能替代渗透测试、正式的合规性审计或 性能基准测试。 ## 许可证 MIT。请参阅 [LICENSE](./LICENSE)。 ## 贡献 欢迎提交 Pull request。每个 Agent 都是一个独立的 Markdown 文件—— 添加阶段、替换整合器的输出格式或收紧专家的契约 都是单文件的修改。

标签：API文档生成, Claude Code, DevSecOps, DLL 劫持, GitHub Copilot, Libemu, OpenAPI, PyRIT, Ruby, STRIDE威胁建模, Subfinder, VS Code, 上游代理, 云资产清单, 代码分析, 凭证管理, 多智能体系统, 大语言模型, 应用架构分析, 技术尽职调查, 数据管道, 知识库, 系统重构, 自动化文档, 证据溯源, 软件工程, 逆向工程, 防御加固