SaieshwarTech/reverse-engineering-claude-code

官方文档告诉你 Claude Code 能做*什么*。本项目则面向开发者、研究人员以及任何构建 AI 编码 Agent 的人员，解释它是*如何*运作的——即其底层的运行机制。本项目包含 **11 章**原创分析、一个检查器 CLI（**`recc`**）以及一个可运行的开源克隆版（**`recc-agent`**）。 ### 为什么会有这个项目 Claude Code 以混淆打包的形式发布，但它的行为、它的开源基础（[Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-typescript)）以及它的 API 流量都是**可以在你自己的机器上观察到的**。通过研究这些——在合法范围内，针对你运行的软件——我们可以重构出生产级编码 Agent 的完整工程蓝图。Agent 循环模式正在成为现代开发工具的基础，人们理应获得一张清晰、真实的架构图谱。

CLI

今天即可直接从 GitHub 安装；包名 **`recc-cli`** 已在 PyPI 和 npm 上预留（经核实，预计 2026-07-03 可用），发布流程已记录在 [`PUBLISHING.md`](PUBLISHING.md) 中——一旦正式发布，`pip install recc-cli` / `npm i -g recc-cli` 即可直接解析，无需源码。 ``` # pip，从源码安装（目前可用） pip install "git+https://github.com/SaieshwarTech/reverse-engineering-claude-code" # pip，一旦发布到 PyPI pip install recc-cli # npm，一旦发布（PyPI package 的 wrapper；PATH 中需要 Python 3.9+） npm install -g recc-cli export ANTHROPIC_API_KEY=sk-ant-... # your own key recc-agent ``` 你将获得五个命令：**`recc-agent`**（终端克隆版）、**`recc`**（检查器），以及三个 OpenClaw 风格的聊天通道——**`recc-bridge`** (Telegram)、**`recc-mail`** (Gmail/IMAP)、 **`recc-whatsapp`** (Meta Cloud API)。使用内置的 `Dockerfile` 在线上托管它们——参见 [第 13 章](docs/13-deploy.md)。 **`recc-agent` 的运行效果：** ``` ╭───────────────────────────────────────────────────────────────╮ │ recc-agent model: claude-sonnet-5 session: 8f2a1c9d │ │ ─────────────────────────────────────────────────────────── │ │ │ │ › fix the failing test │ │ │ │ I'll run the tests first to see what's failing. │ │ ⚙ bash npm test 2>&1 | tail -30 │ │ ⧗ in≈18,204 out≈96 cost≈$0.0021 │ │ │ │ Off-by-one in sum() — expected 42, got 41. Reading it. │ │ ⚙ read src/sum.js │ │ ⚙ edit src/sum.js (i < n -> i <= n) │ │ │ │ ⚠ bash wants to run: npm test │ │ allow? [y]es [a]lways [N]o › a │ │ ⚙ bash npm test │ │ │ │ ✓ All tests pass. The bug was an off-by-one in sum(). │ │ │ │ › _ │ ╰───────────────────────────────────────────────────────────────╯ ``` **通过手机与它对话**——[OpenClaw](https://openclaw.ai/) 风格的聊天通道，全部基于同一个 Agent 循环。默认安全（只读）；显式开启写入权限；始终锁定为你自己使用。参见[第 12 章](docs/12-chat-bridge.md)和[第 13 章](docs/13-deploy.md)。 ``` recc-bridge --allow-chat # Telegram (TELEGRAM_BOT_TOKEN) recc-mail --allow-from you@gmail.com # Email (EMAIL_USER/EMAIL_PASS) recc-whatsapp --allow-from 15551234567 # WhatsApp (WHATSAPP_TOKEN/PHONE_ID) # add --allow-writes 以让它编辑文件 / 运行 shell（小心！） ```

recc-agent — 克隆版	recc — 检查器
``` recc-agent "add a --version flag" # one-shot recc-agent # REPL recc-agent --resume # continue recc-agent --model claude-haiku-4-5 # cheaper recc-agent --yolo # auto-approve ```	``` recc tokens ./prompt.md # count tokens recc cost ~/.claude/**/*.jsonl # session cost recc sessions # list sessions recc inspect # pretty-print recc proxy # log API traffic ```

两者都**使用你自己的密钥调用官方 API**。这是一个学习级别的克隆项目，旨在了解 *Claude Code 是如何构建的*——而不是免费使用 Claude 的途径。详情见：[`agent/README.md`](agent/README.md) 和 [`tool/README.md`](tool/README.md)。

它是如何组合运作的

``` flowchart TB U([You · terminal]) -->|prompt| UI[Terminal UI · render + permission prompts] subgraph LOOP["The Agent Loop — ch. 2"] direction TB CTX[Assemble context
system + tools + full history] API{{POST /v1/messages · model streams}} DEC[text or tool_use?] EXEC[Execute tool] RES[tool_result] CTX --> API --> DEC DEC -->|tool_use| EXEC --> RES --> CTX end UI --> CTX DEC -->|text, no tools| OUT([Final answer]) EXEC -.permit?.-> SEC CTX -.reads.-> CE EXEC -.uses.-> TL TL["Tool Layer — ch. 3
Read · Write · Edit
Bash · Grep · Glob
Task · WebFetch · MCP"] CE["Context Engine — ch. 4
system prompt · CLAUDE.md
compaction · prompt caching"] SEC["Security — ch. 5
permission rules + modes
hooks · sandbox"] DISK[("State on disk — ch. 9
~/.claude/ · settings
JSONL transcripts · memory")] LOOP --- DISK classDef loop fill:#1e3a8a,stroke:#3B82F6,stroke-width:2px,color:#fff classDef tools fill:#134e4a,stroke:#14b8a6,color:#fff classDef ctx fill:#4c1d95,stroke:#a78bfa,color:#fff classDef sec fill:#7f1d1d,stroke:#ef4444,color:#fff classDef disk fill:#092d3a,stroke:#22d3ee,color:#fff classDef io fill:#09090B,stroke:#3B82F6,color:#fff class CTX,API,DEC,EXEC,RES loop class TL tools class CE ctx class SEC sec class DISK disk class U,UI,OUT io ``` ### recc-agent 与 Claude Code 的对比 ``` flowchart LR subgraph OC["recc-agent · this repo"] direction TB A1[Agent loop] A2[Read/Write/Edit/Bash/Grep/Glob] A3[Permission prompts + hard blocks] A4[Streaming + token/cost meter] A5[CLAUDE.md + session resume] end subgraph CC["Claude Code · production"] direction TB B1[Everything in recc-agent] B2[Rich TUI] B3[Sandboxed Bash] B4[Subagents · MCP · Skills · Hooks] B5[Prompt caching · compaction] end OC ==>|"add features, one chapter at a time"| CC classDef oc fill:#134e4a,stroke:#14b8a6,color:#fff classDef cc fill:#1e3a8a,stroke:#3B82F6,color:#fff class A1,A2,A3,A4,A5 oc class B1,B2,B3,B4,B5 cc ```

指南

| # | 章节 | 你将学到什么 | |---|---------|-------------------| | 1 | [全局概览](docs/01-architecture.md) | 整体架构：CLI → Agent 循环 → API → 工具 | | 2 | [Agent 循环](docs/02-agent-loop.md) | 将 LLM 转化为 Agent 的核心 while 循环 | | 3 | [工具系统](docs/03-tools.md) | 每个内置工具、其 schema 及其如此设计的原因 | | 4 | [系统提示词与上下文](docs/04-prompts-and-context.md) | 上下文窗口是如何组装的，CLAUDE.md，压缩机制 | | 5 | [权限与 Hooks](docs/05-permissions-and-hooks.md) | 安全模型：权限模式、允许列表、Hook 生命周期 | | 6 | [子代理与技能](docs/06-subagents-and-skills.md) | 任务委派、技能、斜杠命令、MCP | | 7 | [构建你自己的 Agent](docs/07-build-your-own.md) | 用大约 200 行代码实现一个极简的 Claude Code 风格 Agent | | 8 | [网络传输解析](docs/08-wire-format.md) | Claude Code 到底向 API 发送了什么——抓包并解读 | | 9 | [磁盘状态](docs/09-state-on-disk.md) | 深入剖析 `~/.claude/`：设置、JSONL 记录、记忆 | | 10 | [研究方法](docs/10-methodology.md) | 如何合法地对*任何* AI Agent 进行逆向工程 | | 11 | [术语表与参考](docs/11-glossary.md) | 所有术语，外加一份“验证任何声明”的备忘录 | | 12 | [聊天桥接](docs/12-chat-bridge.md) | 基于同一个循环构建的 OpenClaw 风格 Telegram/WhatsApp/邮件助手 | | 13 | [线上托管](docs/13-deploy.md) | systemd、Docker、PaaS、隧道——让通道 7x24 小时运行 |

亲自观察

对于本指南的内容，你无需盲目相信： - **阅读 SDK** —— `npm i @anthropic-ai/claude-agent-sdk`；Agent 引擎就在其中。 - **拦截流量** —— 将 `ANTHROPIC_BASE_URL` 指向 `recc proxy`（或 mitmproxy）以查看每个请求。（第 8 章。） - **检查磁盘状态** —— `~/.claude/`：设置、记录、待办事项、记忆。（第 9 章。） - **Verbose 模式** —— `claude --verbose` / `--debug` 会暴露内部决策过程。 ## 构建基于

**集成对象** —— 聊天通道使用你自己的凭证与这些平台的官方 API 进行通信：

- **[anthropic](https://pypi.org/project/anthropic/)** —— 官方 Python SDK，唯一的运行时依赖。 - **Telegram Bot API** —— `recc-bridge`（第 12 章）。 - **Meta WhatsApp Cloud API** —— `recc-whatsapp`（第 12 章）；需要 Meta 开发者应用。 - **Gmail / 任何 IMAP+SMTP 提供商** —— `recc-mail`（第 12 章）；仅使用标准库，无需 Google API 密钥。 - **Docker** —— 内置的 `Dockerfile`，用于 7x24 小时托管聊天通道（第 13 章）。 - **PyPI 与 npm** —— `recc-cli` 的目标注册表；参见 [`PUBLISHING.md`](PUBLISHING.md)。 - 零依赖的标准库为检查器和日志记录代理提供支持。 ### 路线图 - [x] 13 章指南：架构、Agent 循环、工具、上下文、权限、子代理、网络传输格式、磁盘状态、研究方法 - [x] `recc-agent` —— 一个可运行的终端克隆版（循环、工具、权限、流式传输、会话） - [x] `recc`` —— 检查器 CLI（Token、成本、会话、代理） - [x] 聊天通道 —— Telegram、Gmail/IMAP、WhatsApp Cloud API - [x] Docker 镜像 + 托管指南（systemd、Compose、PaaS、隧道） - [ ] Discord 通道 - [ ] 在 `recc-agent` 中实现子代理（上下文隔离的任务委派） - [ ] 在 `recc-agent` 中实现 Prompt 缓存（降低成本/延迟） - [ ] 作为 `recc-cli` 发布到 PyPI + npm（参见 [`PUBLISHING.md`](PUBLISHING.md)） ## 范围与道德声明 本项目属于**研究与教育**用途——旨在*理解*，而非盗版。它**不会**帮助你绕过 Anthropic 的计费、逃避身份验证或不付费使用 Claude；那是滥用，而不是逆向工程，会导致账号被封禁。它所教授的是 Agent 的工作原理，以及如何使用你自己的密钥针对官方 API 运行你自己的 Agent。如果考虑到成本问题，指南中涵盖了所有正当的应对手段——更便宜的模型、Prompt 缓存、上下文裁剪、以及 Anthropic 公布的速率限制。 ## 许可证 [MIT](LICENSE)。“Claude”和“Claude Code”是 Anthropic 的商标；这是一个非官方的独立项目。所有内容均为基于公开来源和作者在自己机器上观察到的行为所做的原创分析。

标签：AI智能体, Claude, CVE检测, MITM代理, 云资产清单, 技术文档, 教程, 请求拦截, 逆向工具, 逆向工程