dg-ai-notes README

The project's README from github.com/buchidonggua/dg-ai-notes. As one markdown file: README.md.

Pi源码解读和二次开发实战

🌐 在线阅读:dg-ai-notes.pages.dev —— 双轨教程 · 沉浸式阅读 · 深浅色主题

在线电子书首页


🤔 Pi-Agent 是什么?为什么值得学?

Pi-Agent 是 @earendil-works 开源的 Agent SDK,定位是生产级 AI Agent 的运行时底座——也是 OpenClaw 这类 Agent 产品的底层框架。

它不是玩具框架:Claude Code、Cursor、Cline 等同类产品的内部架构,都能在 Pi 里找到对应实现。Agent Loop、工具系统、消息系统、事件驱动、会话管理、扩展机制——一个 Agent SDK 该有的东西它都有。看懂 Pi,等于看懂一个完整的 Agent SDK 应该怎么设计。


🎯 三大内容,总有一个你用得上

🔬 源码解读 · 10 章拆完一个生产级 SDK

不是贴代码加注释,而是每章回答「是什么 / 怎么做 / 为什么」:从三层架构、Agent Loop 一路讲到上下文工程、会话管理,把 Pi 的设计取舍讲透。TypeScript + Python 双版本对照,30+ 配图,还配了一个可单步运行、随便改参数的 Agent Loop 实验场。

怎么读:TS 版目录 · Python 版目录 · 在线版 · PDF 下载

🚀 实战案例 · 7 章搭一个能上线的 Agent

拿真实场景(企业数据分析助手 DataAgent)从零开始:环境部署 → 模型接入评估 → 系统提示词 → 定义工具 → 事件监听 → 封装成服务。讲的是「改哪一层、为什么这样接」,7 组配套代码(L01–L07)npm install 即跑——跟着敲完,你手里就有一个能部署的垂直 Agent。

怎么学:教程目录 · 配套代码 · 在线版

🧩 Skill 应用 · 让你的 AI 助手秒懂 pi-agent

dg-piagent 是与教程同步维护的 SDK 开发助手 skill(API 核对到 pi-coding-agent v0.83.0)。它从两个视角装订成册:SDK 功能视角可当官方文档查,场景应用视角可当学习手册翻。装进智能体后,写 pi-agent 代码不用再翻文档——你只管提需求,AI 查 skill 完成开发。

快速上手示例(装好后对 AI 直接说人话):

你说 AI 做
"使用 dg-piagent skill,开发一个 DataAgent:web 应用、数据自己造、拦截危险 SQL" 按需求匹配场景、查 SDK 用法,从零搭环境到跑通一步到位
"使用 dg-piagent skill,根据这份模型接口文档生成模型配置" 判断内网模型能否接入 pi-agent(缺哪些参数、如何绕过),直接输出一份可用的模型配置文件
"使用 dg-piagent skill,帮我实现 XX 功能,没有设计思路" 搜索社区同类扩展、自行解读源码,结合你的项目给出一套设计方案

skill 里还沉淀了作者踩过的坑与最佳实践(比如工具报错时把原因和解决办法封装成结果交还模型自行纠错),AI 会照着这些经验做设计,比让它自己搜网上的零散文档靠谱。

怎么装:下载 skills/dg-piagent/ 文件夹,放进你所用智能体的 skills 目录即可——Claude Code / ZCode / Codex / pi 通用,无需其他配置,详见安装说明。

🗺️ 全部章节目录与推荐阅读路径(先实战上手、再源码精读),见 Pi-Agent 教程 README。


📺 配套讲解视频

不想干读文字?B 站有视频版:


📚 三种阅读方式

方式 入口 适合场景
🌐 Web 在线版(推荐) https://dg-ai-notes.pages.dev PC 端沉浸式阅读,双轨切换 + 深浅色主题
📥 Markdown 下载版 pi-agent/ 目录下两系列 下载到本地,配合 AI 边读边问、对照源码
📕 PDF 版 Releases 离线阅读、打印、长期存档(源码精读篇)

🤝 贡献

发现 typo / 内容错误?欢迎:

详见 CONTRIBUTING.md。


📜 License


👋 关于作者

大家好,我是冬瓜,一个热衷于拆解 AI 工程的博主

如果你觉得内容有帮助,欢迎关注,一起交流 AI / Agent / LLM 的工程实践——

冬瓜的抖音二维码
抖音 · 冬瓜
AI 技术科普 · 源码拆解
冬瓜的 B 站二维码
B 站 · 冬瓜
长视频教程 · 直播 coding

🙏 Acknowledgments

dg-ai-notes (buchidonggua/dg-ai-notes)

Searching Database…

What is this?A deep-dive learning notes project (book) that reverse-engineers the Pi-Agent SDK, the runtime behind OpenClaw and similar in architecture to Claude Code, Cursor and Cline internals, paired with hands-on tutorials and a ready-made AI skill.
Is this a book, a code library, or a tool?It is mainly a bilingual written tutorial (TypeScript and Python versions, 30+ diagrams) covering source-code analysis and a runnable hands-on project, plus one installable 'skill' package you drop into an AI coding agent — not a standalone app.
How do I read or use this?Read online at dg-ai-notes.pages.dev, download the Markdown files from the pi-agent/ folder, or grab the PDF from Releases; for the hands-on track, run the L01-L07 lesson code with 'npm install'.
Which coding agents can use the dg-piagent skill?The skill works with Claude Code, ZCode, Codex, or pi itself — just drop the skills/dg-piagent/ folder into that agent's skills directory with no other configuration.
Is the skill kept up to date with the real SDK?It is maintained alongside the tutorials and verified against pi-coding-agent v0.83.0, but as a manually-curated digest it can lag behind brand-new SDK API changes.
What does the dg-piagent skill actually let my AI agent do?It is distilled from the book into two reference views — an SDK-API view and a scenario/how-to view — so your agent can look up Pi-Agent usage and best practices on the fly instead of you reading docs.
What is the DataAgent hands-on tutorial about?A 7-chapter (L01-L07) walkthrough that builds a real enterprise data-analysis agent end to end: environment setup, model evaluation, system prompts, tool definitions, event listeners, and packaging it as a deployable service.
Why did the author write a whole book about Pi-Agent's source instead of just using it?The author ('冬瓜') wanted to show how a production-grade Agent SDK is actually designed, since Pi's internal architecture mirrors what powers Claude Code, Cursor, and Cline under the hood.
Are there video versions of the material?Yes, the author posts companion explainer videos on Bilibili and Douyin covering the same source-code breakdown and skill-building topics as the written book.
Size
2 MB
Stars
3.4K
Age
3mo
Commits · 90 Days