附录 C：常见问题 FAQ
关于本书
Q：这本书为什么选 pi 作参考实现？ 市面上讲 Agent 的资料，要么停留在概念、要么绑定某个闭源产品。本书选择开源 agent harness pi，是因为它是你能直接 clone、直接读源码、直接改的 TypeScript harness——每一个设计模式都能落到真实、可运行的代码上，而不是纸上谈兵。本书秉持“模式先于框架”的理念：讲的是可迁移的设计模式，pi 只是让这些模式看得见、摸得着的载体。
Q：不懂 TypeScript 能读吗？ 能。书里的代码是为了说明模式，都做了简化和注释，重点是“思路”而非语法。你只需理解基本编程概念和“LLM 是什么”。
Q：学完能直接用别的框架吗？ 这正是本书的目标。你学的是模式（ReAct、上下文工程、多 Agent 协作、成本分层……），它们不绑定 pi。换到 LangGraph、CrewAI、PydanticAI、Agno，你会发现自己早就懂了。（见第 35 章）
关于 pi
Q：pi 是什么？和 Claude Code 什么关系？ pi 是一个开源的 agent harness（TypeScript），包含 agent runtime、多 provider LLM 层、工具调用、扩展、技能、会话管理、实验性的多 Agent 编排。它和 Claude Code 是同一类东西——都是“承载并运行 Agent 的宿主”。（见第 1、22 章）
Q：pi 适合做生产系统吗？ pi 的运行时、会话、RPC、可观测基础是扎实的，适合中小规模、或作为大系统里的“执行单元”。但它是单进程 harness，不内建权限系统、不是多租户平台。要做大规模企业级 SaaS，需要在 pi 之外自建身份、调度、计费等基础设施。（见第 26、28 章）
Q：pi 的 orchestrator 能用吗？ 可以用，但它是实验性（Experimental）的——官方明确说 API 和行为可能变动或移除。所以书里多 Agent 部分重点讲模式（模式稳定），具体 API 请以你使用时的 pi 文档为准。（见第 16 章）
Q：pi 安全吗？会不会执行危险命令？ pi 本身不含权限系统，默认以启动它的用户权限运行。这是它诚实的定位选择。需要安全边界时，用扩展做确认门（第 8 章）、用容器化做硬隔离（第 28 章：Gondolin 微 VM / Docker / OpenShell）。
关于选型
Q：我该用 pi 还是 LangGraph / CrewAI / PydanticAI / Agno？ 它们底层都是同样的模式，差别在抽象层次和易用性——按你的视角和场景选：
- LangGraph：要精细控制复杂流程、把 Agent 画成显式状态图（含循环、分支、可恢复），选它。
- CrewAI：要快速搭多 Agent 协作、用“团队 + 角色 + 任务”的心智组织分工，选它。
- PydanticAI：要类型安全、结构化可靠的输出、像写普通 Python 一样写 Agent，选它。
- Agno：要开箱即用、内置 Team/Memory/RAG/工具快速搭有记忆有检索的应用，选它。
- pi：要 harness 视角、读懂运行时、做编码/后台 Agent、用 TypeScript 在宿主上构建，选它。
（见各章“对比”小节、第 35 章）
Q：什么时候不该用 Agent？ 当流程完全确定时。Agent 的价值在“自主决策”，流程越固定，Agent 的不确定性越是负担——这时普通脚本更合适。（见附录 B 决策一）
Q：单 Agent 和多 Agent 怎么选？ 能单 Agent 就别多 Agent。 只有当职责太杂、上下文会被塞爆、或需要独立视角时，才拆成多 Agent——它的成本和复杂度高得多。（见第 16 章、附录 B）
关于成本与生产
Q：Agent 太烧钱怎么办？ 三管齐下：预算控制（把上限嵌进循环，第 26 章）+ 分层模型（简单事用便宜模型，第 34 章）+ 上下文压缩（控制长度，第 9 章）。前提是能准确度量成本（pi-ai 提供定价，第 25 章）。
Q：Agent 出了问题怎么查？ 靠可观测性。pi 的会话格式本身就是结构化的完整追踪——翻出那次会话，一步步看它当时想了什么、调了什么。所以务必从第一天就持久化会话，很多问题只发生一次。（见第 25 章）
Q：怎么让 Agent 在后台/Web 上跑？ 用 pi 的 RPC + 可寻址会话远程驱动。同一个运行时，交互式和后台是“一体两面”，区别只在“谁来驱动”。后台 Agent 因无人监督，护栏（预算、隔离、追踪）要求更高。（见第 23、32 章）
还有问题？
本书讲的是模式，pi 的具体用法请查官方文档与源码仓库——正如 pi 自己说的，你也可以直接问 Agent 让它解释自己。