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

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

项目定位

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，不是无限自治团队。

7 天学习路线

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

Day	主题	你会读到
Day 1	Agent Loop 是怎么跑起来的	AgentRuntime、turn loop、消息流
Day 2	Tool Registry 与工具调用	ToolRegistry、工具元数据、调用边界
Day 3	文件读写、Patch 与代码修改	file tools、pending edits、效果绑定
Day 4	Approval Gate 与安全策略	policy、pending actions、审批执行
Day 5	Session、Timeline 与 Checkpoint	SessionHost、timeline、safe rewind
Day 6	Memory 检索与上下文注入	memory retrieval、learning、recall builder
Day 7	MCP、Browser 与 SubAgent 扩展	MCP manager、browser runtime、subagents

核心模块导览

学习问题	完整工程路径
一轮对话如何进入运行时	src/pp_agent/runtime/runtime.py, src/pp_agent/runtime/turn_loop.py
会话如何创建、恢复、分支、回退	src/pp_agent/runtime/session_host.py, src/pp_agent/storage/sessions.py
工具如何注册、筛选、执行	src/pp_agent/tools/registry.py, src/pp_agent/tools/base.py
审批和安全策略在哪里发生	src/pp_agent/tools/policy.py, src/pp_agent/tools/effects.py, src/pp_agent/storage/approvals.py
文件、Git、Shell 工具如何实现	src/pp_agent/tools/file_tools.py, src/pp_agent/tools/repo_tools.py, src/pp_agent/tools/shell_tool.py
checkpoint 和 safe rewind 如何串起来	src/pp_agent/runtime/git_checkpoint.py, src/pp_agent/runtime/safe_rewind.py
记忆如何检索并进入上下文	src/pp_agent/memory/*, src/pp_agent/learning/*
MCP 工具如何发现和调用	src/pp_agent/mcp/*, example-mcp.jsonc
Browser 工具如何受控执行	src/pp_agent/browser/*, src/pp_agent/web_tools/*
SubAgent 如何受控分工	src/pp_agent/tools/subagent_tool.py, src/pp_agent/subagents/*

Agent Eval Baseline

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

最近一次 100-case deterministic baseline：

指标	结果
Total cases	100
Pass / fail / pending	86 / 0 / 14
Task success rate	86.00%
Safety rate	100.00%
Tool success rate	100.00%
Approval recall	100.00%

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

文档导航

在GitHub项目中文档导航

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

实习经历

小厂oc

携程oc

华为二面已过

感谢

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

https://github.com/CHEN2003-CHIP/pp-Echo