pp-Echo

5 分钟跑通，7 天读懂，从 0 实现一个能规划、能调用工具、能审批、能回退、能记忆的Claude Code / Cursor 式本地 Agent。

5 分钟跑通，7 天读懂，从 0 实现一个能规划、能调用工具、能审批、能回退、能记忆的Claude Code / Cursor 式本地 Agent。

pp-Echo 现在首先是一个教学向 Agent 工程项目：它不是把 LangChain / AutoGen 当黑箱接起来，也不是只会聊天的 Prompt Demo，而是把本地编程 Agent 背后的工程骨架拆开给你看。

你可以从 mini-pp-echo/ 的 7 个独立小脚本开始，理解 Agent Loop、工具调用、文件修改、审批、记忆、checkpoint 和 MCP mock；再回到完整工程，阅读 SessionHost、AgentRuntime、ToolRegistry、memory、MCP、SubAgent 等真实模块。

你应该从哪里开始？

我是新手，只想先跑起来

先看 mini-pp-echo/，从最小 Agent Loop 开始。

我想系统学习 Agent 工程

看 tutorials/README.md，按 7 天路线学习。

我已经跑通 mini，想读完整源码

看 docs/source-reading-roadmap.md，按 Stage 0 到 Stage 6 闯关阅读。

我想用于实习和面试

优先看 docs/source-reading-roadmap.md 里的“可以写进简历”，再看 docs/interview-guide.md 做面试表达自查。

项目定位

pp-Echo 想回答一个学习者真正关心的问题：

如果我要从 0 实现一个 Claude Code / Cursor 式的本地编程 Agent，除了调用大模型，我到底还要写哪些工程机制？

这里的答案包括：

• 可见的 planning 与 turn loop，而不是一次性 prompt 拼接。
• 统一的 tool registry，而不是散落在各处的函数调用。
• 对文件、Git、Shell、Browser、Memory、MCP、SubAgent 的工具化封装。
• Approval Gate：高风险动作先预览、再确认、再执行。
• Git-backed checkpoint / safe rewind：代码状态和会话状态都能回退。
• Memory 检索与上下文注入：让 Agent 不只活在当前一轮对话里。
• 受控 SubAgent：能分工，但要有工具白名单、轮次限制和产物边界。

它仍然是一个 Windows-first 的本地工程项目，但首页不再把重点放在“怎么部署一个工具”，而是放在“怎么读懂并复现一个 Agent 工程系统”。

为什么值得看

• 从 0 到完整链路：先看最小教学版，再看真实工程版，学习路径是连续的。
• 不依赖高层黑箱：核心机制直接落在 Python 代码里，适合拆解、改写和复现。
• 机制足够真实：规划、工具调用、审批、回退、记忆、MCP、Browser、SubAgent 都不是概念图。
• 适合对标学习：你可以借它理解 Claude Code / Cursor 背后的本地 Agent 工程骨架，但它不是商业产品替代品。
• 边界说清楚：pp-Echo 有策略门和审批流，但不是完整 shell sandbox；SubAgent 是受控 worker，不是无限自治团队。

5 分钟快速开始

推荐先跑教学最小版，不需要 LLM API：

python mini-pp-echo/01_loop.py
python mini-pp-echo/02_tool_call.py
python mini-pp-echo/04_approval.py

然后启动完整工程。pp-Echo 当前推荐 Windows + Python 3.9+。

方式一：clone 后双击启动

如果你只是想最快跑起来：

1. 安装 Python 3.9+，并勾选 Add python.exe to PATH。
2. 如果要启动 Web UI，安装 Node.js 20+，并确保 npm 在 PATH 中。
3. 设置模型 API key：

setx PP_AGENT_API_KEY "your_api_key"

重新打开一个 PowerShell 或双击脚本窗口，让环境变量生效。

然后在仓库根目录双击：

start-agent.bat    启动 CLI Agent
start-web.bat      启动 Web UI，会自动打开 http://127.0.0.1:8765

这两个脚本会检查依赖；缺少 Python 包时会自动执行 pip install。start-web.bat 还会在需要时进入 web/ 安装前端依赖并构建页面。

注意：如果不设置 PP_AGENT_API_KEY，脚本仍会打开 CLI 或 Web UI，但真正请求模型时会失败。

方式二：推荐的隔离环境

git clone https://github.com/CHEN2003-CHIP/pp-Echo.git
cd pp-Echo
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e .[web]
set PYTHONPATH=src
set PP_AGENT_API_KEY=your_api_key
python -m pp_agent.cli.main chat

也可以使用仓库里的脚本入口：

.\start-agent.bat
.\echo-cli.bat
.\start-web.bat

Web UI 默认访问：

http://127.0.0.1:8765

常用诊断命令：

set PYTHONPATH=src
python -m pp_agent.cli.main workflow doctor --json
python -m pp_agent.cli.main config show --workspace .
python -m pp_agent.cli.main memory search "project conventions" --scope workspace

7 天学习路线

完整路线见 tutorials/README.md。建议每天只抓一个核心问题：

核心模块导览

Agent Eval Baseline

在升级 Agent Kernel、EventBus、ContextEngine、SessionTree 之前，pp-Echo 先建立了一套可回归的 Agent Eval baseline。当前默认 baseline 使用 deterministic 模式跑 100 条 case，不依赖真实 LLM，适合 CI 和重构前后对比。

最近一次 100-case deterministic baseline：

这张图展示的是当前 Agent 工程能力的基线，而不是宣传分数。pending 的 14 条全部来自 memory_recall：scorer 已经设计了 memory recall trace 接口，但真实 runtime 的 memory event/trace 还需要后续接入。也就是说，当前 baseline 主要覆盖文件编辑、工具选择、审批、安全路径、checkpoint rewind 和受控 SubAgent；memory recall 会在事件流补齐后转为可判定 case。

运行方式：

python evals/runner.py --suite baseline --mode deterministic --cases 100
python evals/runner.py --suite baseline --mode live --model your_model_name --cases 10 --timeout-seconds 180

报告会写入 evals/reports/latest.json、evals/reports/latest.md 和 evals/reports/latest.svg，并自动保存带时间戳的历史报告，方便后续重构后做趋势对比。

mini-pp-echo 教学版

mini-pp-echo/ 是这个仓库的教学入口。它不依赖真实 LLM API，也不追求功能完整，只用 7 个可单独运行的脚本演示核心工程机制：

01_loop.py        最小 Agent Loop
02_tool_call.py   工具注册与调用
03_file_edit.py   文件读写与最小 patch
04_approval.py    高风险动作审批
05_memory.py      记忆检索与上下文注入
06_checkpoint.py  checkpoint 与回退
07_mcp_mock.py    MCP 风格工具发现与调用

建议先把这 7 个脚本读完，再读完整工程。这样你看到 SessionHost、ToolRegistry、safe_rewind 时，不会被真实项目的边界条件淹没。

完整工程版

完整 pp-Echo 是一个可运行的本地编程 Agent 工程版，提供 CLI、TUI、Web UI、会话树、审批流、checkpoint、memory、MCP、Browser、SubAgent 和测试覆盖。

它适合三类学习者：

• 想理解 Claude Code / Cursor 类产品工程结构的人。
• 想自己实现本地 Agent runtime 的开发者。
• 想研究“工具调用 + 审批 + 回退 + 记忆”怎样组合成可靠系统的人。

安全边界说明

pp-Echo 的安全设计重点是“可见、可审、可回退”：

• 高风险工具会进入 Approval Gate。
• 文件和 shell 操作会尽量生成可预览的效果摘要。
• checkpoint / safe rewind 用 Git-backed 方式帮助恢复代码状态。
• SubAgent 默认受工具、轮次和工作区策略约束。

但也要诚实说明：

• 它不是完整的系统级 sandbox。
• 它不能替代人工代码审查。
• 它不能保证模型永远按预期规划。
• 在真实仓库中运行前，应先看 docs/safety.md 和 workflow doctor 输出。

文档导航

• tutorials/README.md：7 天读懂 pp-Echo。
• mini-pp-echo/README.md：从 0 开始的教学最小版。
• docs/teaching-positioning.md：为什么 pp-Echo 适合做 Agent 工程课。
• docs/source-reading-roadmap.md：完整工程源码阅读路线。
• docs/source-map.md：源码路径导览。
• docs/interview-guide.md：实习与面试准备索引。
• docs/safety.md：安全边界与审批策略。
• docs/configuration.md：配置模型、工具和项目设置。
• docs/mcp-fetch-integration.md：MCP 集成说明。
• docs/multi_agent_demo.md：SubAgent 演示。
• README_en.md：英文参考文档。
• docs/legacy/README_ZH.md：旧版中文参考文档。
• docs/legacy/：历史文档入口。

贡献路线

欢迎围绕“更适合学习”来贡献：

• 把完整工程中的复杂机制拆成更小的 tutorial。
• 为 mini-pp-echo/ 增加配套图解或练习题。
• 补充“从教学脚本跳到真实源码”的源码阅读注释。
• 增加小而稳的测试，覆盖新增教学模块。
• 改进 docs，让学习者更快定位 AgentRuntime、ToolRegistry、SessionHost 的关系。

如果这个项目帮你把本地 Agent 的工程骨架看清楚了，点一个 Star 就很好。它会让我知道：这个仓库值得继续朝“可运行、可拆解、可复现的 Agent 工程课”打磨下去。

License

MIT