00 教程导读
先花 3 分钟搞清楚：这个教程讲什么、你需要准备什么、该怎么学效果最好。
🎯 本节目标
- 知道这个教程讲的是什么、怎么用
- 准备好学习环境（克隆项目 + 装依赖）
- 理解整个教程的结构和阅读顺序
1. 这个教程是什么
一句话：带你从零读懂 pi-remote-feishu 这个开源项目的源码。
pi-remote-feishu 是 AI 编码代理 Pi Agent 的飞书（Feishu/Lark）扩展包。
它让用户可以在飞书私聊/群聊里跟 Pi 对话，并把 Pi 的回复、思考过程、工具调用、生成的文件全部投射回飞书。
这个项目虽然只有约 2800 行 TypeScript，却包含了大量值得学习的设计： 多会话隔离、双进程架构、异步上下文传递、流式渲染、远程 UI 桥接、文件安全校验……
2. 你需要准备什么
| 前置条件 | 说明 |
|---|---|
| Node.js ≥ 22.19 | 项目引擎要求（package.json 的 engines 字段） |
| TypeScript 基础 | 会看接口、泛型、类型联合即可，教程会解释关键语法 |
| 一个编辑器 | 推荐 VS Code，边读教程边打开源码对照 |
| 飞书应用（可选） | 想真正跑起来需要注册飞书开放平台应用；只想学原理不需要 |
3. 跟着做：先把这个项目跑起来
教程里的所有内容都基于真实源码，建议先克隆并确认它能通过测试：
# 克隆项目
git clone https://github.com/grin-coder/pi-remote-feishu.git
cd pi-remote-feishu
# 安装依赖
npm install
# 跑测试（20 个测试应该全部通过）
npm test
# 类型检查
npm run typecheck
# 编译
npm run build看到 Test Files 9 passed / Tests 20 passed 就说明环境 OK 了。
💡 没有飞书应用也能学
本教程 90% 的内容是架构与实现原理，不需要真实飞书环境。 只有想实际部署时才需要去飞书开放平台注册应用、配置 WebSocket 长连接。
4. 教程结构
| 部分 | 章节 | 学完你会掌握 |
|---|---|---|
| 第一部分 架构设计 | 导读 → 项目概览 → 总体架构 → 核心概念 → 消息处理全链路 → 关键设计决策 | 项目解决什么问题、系统怎么分层、sessionKey/SessionHost/PromptQueue/异步上下文、一条消息的完整旅程、13 个设计决策的取舍 |
| 第二部分 源码解读 | 源码地图 → 配置 → 通道 → 路由 → 会话 → 运行时 → 渲染 → UI 桥接 → 卡片 → 附件 → 工具 → 存储 → 入口 → 测试与二次开发 | 每个源码模块的逐行讲解、可复用的编码范式、如何给项目加新功能 |
5. 每章的标准结构
- 🎯 本节目标：先告诉你学完能获得什么
- 📂 本节源码：要对照阅读的文件路径
- 正文：概念讲解 + 代码精读 + 流程图
- 💡 提示 / ⚠️ 注意：容易踩的坑和设计意图
- 🧾 小结：一页纸总结本节要点
- ✍️ 练习：动手题，答案都在源码里
6. 最佳学习方式
📖 推荐路径
- 第一遍（快速）：只读第一部分，30 分钟内建立全局认知。
- 第二遍（精读）：读第二部分时，每章先在编辑器打开对应文件，对照代码逐段理解。
- 第三遍（动手）：做完每章练习，尝试按第 14 章的指南加一个新命令/新工具。
7. 术语速览（提前打个预防针）
| 术语 | 含义 |
|---|---|
| Transport | 传输通道，本项目中指「飞书」这条与用户对话的通道 |
| Runtime | Pi Agent 的会话运行时（AgentSessionRuntime），持有模型和上下文 |
| sessionKey | 会话的唯一标识字符串，如 dm:ou_xxx、group:oc_xxx |
| SessionHost | 一个隔离单元：一个 runtime + 一个串行队列 + 活跃任务标记 |
| AsyncLocalStorage | Node 官方 API，用于在异步调用链里传递「当前请求上下文」 |
✅ 本节小结
你已经知道：教程讲什么、需要什么环境、怎么学最快。 下一步克隆项目并跑通测试，然后进入 01 项目概览。
✍️ 练习
- 打开
package.json，找出这个包对外暴露的入口文件（main、bin、pi.extensions三个字段分别指向哪里？） - 运行
npm test，数一数一共多少个测试文件、多少个用例。