GeoloeG-IsT/agents-reverse-engineer

## 为什么开发这个工具 AI 编程助手很强大，但它们不了解你的代码库。每次会话都是全新的。你需要反复解释相同的架构、相同的模式、相同的文件位置——一遍又一遍。 一些助手提供内置的初始化功能（例如 Claude Code 的 `/init`），但这些功能比较浅层——它们生成的只是薄薄的一层顶层摘要，对于具有深层模块层级的大型既有项目来说远远不够。更糟糕的是，没有相应的更新机制：随着代码库的演进，生成的上下文会悄无声息地过时。 **agents-reverse-engineer** 解决了这个问题。它生成 AI 助手真正会阅读的、丰富的多级文档——并保持同步： - **`.sum` 文件** — 每个文件的摘要，包含用途、导出、依赖项 - **`AGENTS.md`** — 每个目录的概览，包含文件组织结构（标准格式） - **`CLAUDE.md`** / **`GEMINI.md`** / **`OPENCODE.md`** — 特定运行时的项目入口点 - **增量更新** — 基于Git感知的变更检测，仅重新生成发生变化的部分 结果是：你的 AI 助手从第一条消息就能理解你的代码库——并且随着代码增长保持准确。 ## 适用人群 使用 AI 编程助手（Claude Code、Codex、OpenCode、Gemini CLI 或任何支持 `AGENTS.md` 的工具）的开发者，希望他们的助手真正理解项目结构——无需手动编写文档或每次会话重复说明上下文。 ## 快速开始 ### 1. 安装命令 ``` npx agents-reverse-engineer@latest ``` 交互式安装程序会提示你： 1. **选择运行时** — Claude Code、Codex、OpenCode、Gemini CLI 或全部 2. **选择位置** — 全局（`~/.claude/`、`~/.agents/` 等）或本地（`./.claude/`、`./.agents/` 等） 这将安装： - **命令** — `/are-init`、`/are-discover`、`/are-generate`、`/are-update`、`/are-specify`、`/are-plan`、`/are-implement`、`/are-clean`、`/are-dashboard` - **Codex 上下文规则** — 本地安装写入 `./AGENTS.override.md`；全局安装写入 `~/.codex/AGENTS.override.md`，包含延迟 AGENTS 层级加载指南 ### 2. 初始化配置 安装完成后，在你的 AI 助手中创建配置文件： ``` /are-init ``` 这将创建带有默认设置的 `.agents-reverse-engineer/config.yaml` 文件。 ### 3. 生成文档 在你的 AI 助手中运行： ``` /are-discover /are-generate ``` 助手会创建计划并生成所有文档。 ### 非交互式安装 ``` # 全局安装 Claude Code npx agents-reverse-engineer@latest --runtime claude -g # 全局安装 Codex npx agents-reverse-engineer@latest --runtime codex -g # 本地安装所有运行时 npx agents-reverse-engineer@latest --runtime all -l ``` ### 卸载 ``` npx agents-reverse-engineer@latest uninstall ``` 移除： - 命令文件（`/are-*` 命令） - settings.json 中的 ARE 权限 - `.agents-reverse-engineer` 文件夹（仅限本地安装） 使用 `--runtime` 和 `-g`/`-l` 标志指定特定目标。 ### 检查版本 ``` npx agents-reverse-engineer@latest --version ``` ## 工作原理 ### 1. 安装命令 ``` npx agents-reverse-engineer@latest ``` 交互式安装程序为你选择的运行时安装命令和钩子。 **运行时：** Claude Code、Codex、OpenCode、Gemini CLI（或一次全部安装） ### 2. 初始化配置 ``` /are-init ``` 创建带有排除模式和选项的 `.agents-reverse-engineer/config.yaml`。 ### 3. 发现与规划 ``` /are-discover ``` 扫描你的代码库（遵循 `.gitignore`），检测文件类型，并创建包含所有待分析文件的 `GENERATION-PLAN.md`。 使用**后序遍历**——最深的目录优先，这样在记录父目录之前子文档就已经存在。 ### 4. 生成（在你的 AI 助手中） ``` /are-generate ``` 你的 AI 助手执行计划： 1. **文件分析** — 为每个源文件创建 `.sum` 文件 2. **目录文档** — 为每个目录创建 `AGENTS.md` 和 `CLAUDE.md` 指针 ### 5. 增量更新 ``` /are-update ``` 仅重新生成自上次运行以来发生变化的文件的文档。 ### 6. 生成规范（实验性） ``` /are-specify ``` 将所有 AGENTS.md 文档综合成一个项目规范文档（`specs/SPEC.md`）。使用 `--multi-file` 拆分为单独的文件，或使用 `--dry-run` 预览而不调用 AI。 ### 7. 计划对比（A/B 测试）（实验性） ``` are plan "Add user authentication with JWT" ``` 对同一任务运行 **两次** AI 规划——一次使用 ARE 文档，一次不使用——然后比较输出质量（细节、文件引用、可操作步骤）。使用 `--eval` 进行盲测 AI 质量评分。 ### 8. 实现对比（A/B 测试）（实验性） ``` are implement "Add user authentication with JWT" ``` 需要先运行一次 `are plan`。在隔离的 git worktree 中执行 AI 计划，提取实现指标（创建的文件、更改的行数、提交次数），并可选择运行测试/构建/代码检查。使用 `--eval` 进行盲测 AI 质量评估。 ``` are implement "Add auth" --run-tests --run-build --eval are implement --list # List saved comparisons are implement --show 2026-02-16 # View a comparison ``` ## 命令 | 令 | 描述 | | ------------------------------- | ------------------------------------------------ | | `are` | 交互式安装程序（默认） | | `are install` | 带提示安装 | | `are install --runtime -g` | 全局安装到运行时 | | `are install --runtime -l` | 本地安装到运行时 | | `are uninstall` | 卸载（移除文件/钩子） | | `are init` | 创建配置文件 | | `are discover` | 扫描文件并创建 GENERATION-PLAN.md | | `are generate` | 生成所有文档 | | `are update` | 仅更新变化的文件 | | `are specify` | 生成项目规范（实验性） | | `are rebuild` | 从规范重建项目（实验性） | | `are plan ""` | 对比有文档 vs 无文档的 AI 规划（实验性） | | `are implement ""` | 对比有文档 vs 无文档的 AI 实现（实验性） | | `are clean` | 移除所有生成的文档 | | `are dashboard` | 显示遥测仪表板（成本、token、追踪）（实验性） | **运行时：** `claude`、`codex`、`opencode`、`gemini`、`all` ### 通用 CLI 选项 | 标志 | 描述 | 适用命令 | | -------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- | | `--model ` | 要使用的 AI 模型（如 sonnet、opus、haiku） | generate, update, specify, rebuild | | `--backend ` | AI 后端（claude、codex、gemini、opencode、auto） | generate, update, specify, rebuild | | `--concurrency ` | 并发 AI 调用数（默认：自动） | generate, update, rebuild | | `--dry-run` | 显示计划但不写入文件 | generate, update, specify, rebuild, clean | | `--force` | 覆盖现有文件 | init, install, generate, specify, rebuild | | `--fail-fast` | 首次文件分析失败时停止 | generate, update, rebuild | | `--show-excluded` | 在发现过程中显示被排除的文件 | discover | | `--uncommitted` | 包含未提交的更改 | update | | `--eval` | 对两个结果运行 AI 质量评估器 | plan, implement | | `--eval-model ` | AI 评估器使用的模型（默认为 --model） | plan, implement | | `--task-slug ` | 覆盖自动生成的任务 slug | plan, implement | | `--plan-id ` | 通过 ID 引用现有计划 | implement | | `--list` | 列出已保存的对比 | plan, implement | | `--show ` | 按 ID 显示之前的对比 | plan, implement | | `--run-tests` | 运行测试套件并提取指标 | implement | | `--run-build` | 运行构建并检查成功 | implement | | `--run-lint` | 运行代码检查器并提取指标 | implement | | `--debug` | 显示 AI 提示和后端详情 | discover, generate, update, specify, rebuild, plan, implement | | `--trace` | 启用并发追踪（.agents-reverse-engineer/traces/） | generate, update, specify, rebuild | | `--run ` | 显示特定运行的每个条目详情 | dashboard | | `--trends` | 显示跨运行的成本和使用趋势 | dashboard | | `--format ` | 输出格式：table（默认）、json、html | dashboard | ### AI 助手命令 | 命令 | 描述 | 支持的运行时 | | ---------------- | ------------------------------------------- | ------------------------------- | | `/are-init` | 初始化配置和命令 | Claude, Codex, OpenCode, Gemini | | `/are-discover` | 重新发现并重新生成计划 | Claude, Codex, OpenCode, Gemini | | `/are-generate` | 生成所有文档 | Claude, Codex, OpenCode, Gemini | | `/are-update` | 仅更新变化的文件 | Claude, Codex, OpenCode, Gemini | | `/are-specify` | 生成项目规范（实验性） | Claude, Codex, OpenCode, Gemini | | `/are-rebuild` | 从规范重建项目（实验性） | Claude, Codex, OpenCode, Gemini | | `/are-plan` | 对比有文档 vs 无文档的规划（实验性） | Claude, Codex, OpenCode, Gemini | | `/are-implement` | 对比有文档 vs 无文档的实现（实验性） | Claude, Codex, OpenCode, Gemini | | `/are-clean` | 移除所有生成的文档 | Claude, Codex, OpenCode, Gemini | | `/are-dashboard` | 显示遥测仪表板（实验性） | Claude, Codex, OpenCode, Gemini | ## 遥测仪表板（实验性） ARE 记录每次运行的遥测数据（成本、token、延迟、追踪）。使用仪表板分析成本和性能。 ``` are dashboard # Summary table of all runs are dashboard --run 2026-02-14 # Per-entry drill-down for a run are dashboard --trace 2026-02-14 # ASCII Gantt timeline of execution are dashboard --trends # Cost trends over time are dashboard --format html > report.html # Self-contained HTML report with charts ``` 在你的 AI 助手中：`/are-dashboard`、`/are-dashboard --trends` 等。 **提示：** 如需查看总会话成本（不仅是 ARE），请使用 [ccusage](https://github.com/ryoppippi/ccusage)： - Claude Code: `npx ccusage@latest` - Codex: `npx @ccusage/codex@latest` - OpenCode: `npx @ccusage/opencode@latest` ## 生成的文档 ### `.sum` 文件（每个文件） ``` --- file_type: service generated_at: 2026-01-30T12:00:00Z --- ## 目的 Handles user authentication via JWT tokens. ## 公共接口 - `authenticate(token: string): User` - `generateToken(user: User): string` ## 依赖 - jsonwebtoken: Token signing/verification - ./user-repository: User data access ## 实现说明 Tokens expire after 24 hours. Refresh handled by client. ``` ### `AGENTS.md`（每个目录） 目录概览包含： - 目录角色的描述 - 按用途分组的文件（Types、Services、Utils 等） - 子目录及简要描述 ### 指针文件 - **`CLAUDE.md`** — 为 Claude Code 导入 `AGENTS.md`（每个目录自动加载） ### 根目录概览 - **`AGENTS.md`** — 根目录概览（通用格式） ## 配置 编辑 `.agents-reverse-engineer/config.yaml`： ``` # 文件和目录排除 exclude: patterns: [] # Custom glob patterns (e.g., ["*.log", "temp/**"]) vendorDirs: # Directories to skip - node_modules - dist - .git binaryExtensions: # File types to skip - .png - .jpg - .pdf # Discovery 选项 options: followSymlinks: false # Follow symbolic links during traversal maxFileSize: 1048576 # Max file size in bytes (1MB default) # Output 格式 output: colors: true # Use colors in terminal output # AI 服务配置 ai: backend: auto # Backend: 'claude', 'codex', 'gemini', 'opencode', 'auto' model: sonnet # Model identifier (backend-specific) timeoutMs: 300000 # Subprocess timeout in ms (5 minutes) maxRetries: 3 # Max retries for transient errors concurrency: 10 # Parallel AI calls (1-20, auto-detected from CPU/RAM) telemetry: keepRuns: 50 # Number of run logs to keep ``` ### 关键配置选项 **并发数（`ai.concurrency`）** - 默认：根据 CPU 核心数和可用内存自动检测 - 范围：`1-20` - 资源受限环境建议使用较低值 - 较高的值可加快生成速度，但会使用更多内存 **超时（`ai.timeoutMs`）** - 默认：`300000`（5 分钟） - 每个文件分析的 AI 子进程超时时间 - 对于非常大的文件或慢速连接，请增加此值 ## 系统要求 - **Node.js 18+** - **AI 编程助手** — 以下之一： - [Claude Code](https://claude.ai/claude-code)（完全支持） - [Gemini CLI](https://github.com/google-gemini/gemini-cli)（完全支持） - [OpenCode](https://github.com/opencode-ai/opencode)（支持 AGENTS.md） - 任何支持 `AGENTS.md` 格式的助手 ## 贡献 欢迎贡献！无论是错误报告、功能请求还是 pull request——所有意见都很宝贵。 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置和指南。 ## 许可证 MIT

标签：Agent, AGENTS.md, AI 辅助编程, Claude Code, Codebase, DLL 劫持, LLM 上下文, MITM代理, NPM 包, OpenCode, RAG, 云资产清单, 代码分析, 代码库文档生成, 代码摘要, 代码理解, 凭证管理, 大语言模型, 威胁情报, 开发者工具, 提示词工程, 数据管道, 知识库构建, 策略决策点, 网络安全研究, 自动化攻击, 自动化文档, 软件工程, 逆向工程, 项目脚手架