第 14 讲安全、容器化与综合实战项目

学习目标

• 精读：pi-main/packages/coding-agent/docs/security.md（全文约 90 行，句句是边界定义）
• 精读：pi-main/packages/coding-agent/docs/containerization.md（四种隔离方式的操作步骤与限制）
• 通读：pi-main/AGENTS.md（开发规则全文）与 pi-main/CONTRIBUTING.md（贡献门）
• 拓展：pi-main/packages/durable/README.md（Persist and Resume）、pi-main/apps/p2/README.md（前半）

§14.1信任模型：完整用户权限与「有意的极简」

一句话类比：Pi 不是沙箱里的实验宠物，而是一个拿着你的工牌、坐在你的工位上的自动化助手——它能做什么，完全取决于你的操作系统账户能做什么。

security.md 开篇第一句就是原则：「Treat model-generated commands and code as untrusted.」（把模型生成的命令和代码当作不可信输入。）Pi 可以以启动它的账户权限读取、修改、执行文件，并且不会在每次工具调用前请求批准。扩展（extensions）、包安装器（package installers）、语言服务器（language servers）以及其他子进程，除非被操作系统或虚拟化边界限制，否则都以同样的权限运行。

不可信输入从哪里来？文档列举得很具体：文件内容、代码注释、说明文字、命令输出、模型回复本身，都可以通过提示注入（prompt injection）操纵模型。第 9 讲我们讲过上下文组装——凡是进入上下文的文本，都是模型的「指令候选」。一个恶意仓库的 README、一段被注入的测试输出，都可能在下一次工具调用中变成行动。

Treat model-generated commands and code as untrusted.
Pi can read, change, and execute files with the permissions of the
account that started it, and it does not ask for approval before
every tool call. Extensions, package installers, language servers,
and other child processes run with those same permissions unless an
operating-system or virtualization boundary restricts them.

...
Watching the transcript, using project trust, and reviewing changes
do not create a security boundary.

为什么「不内置权限系统」是设计决策，而不是缺失

第一讲我们就介绍过 Pi 的哲学：极简、可扩展的 Agent Harness。这个哲学在安全上的直接推论是：核心不实现权限系统，把它留给操作系统层与扩展生态。仓库里其实「有」权限门——只是它们是扩展示例，而不是核心功能：

• packages/coding-agent/examples/extensions/permission-gate.ts——工具调用前的权限确认；
• packages/coding-agent/examples/extensions/confirm-destructive.ts——破坏性操作二次确认；
• packages/coding-agent/examples/extensions/timed-confirm.ts——带倒计时的确认。

这些扩展通过第 11 讲的 tool_call 事件拦截调用、弹确认框，本质上是在进程内加流程闸门。它们能防「手滑」，防不了「恶意」——因为闸门本身与被拦截的工具运行在同一个进程、同一个用户身份里。真正对抗恶意输出的边界，必须由不属于 Pi 进程的东西来执行：专用 OS 用户、容器、虚拟机或策略沙箱。

这个取舍还有一层工程理由：一个 TypeScript 进程内的权限检查，覆盖不住 bash 拉起的任意子进程、覆盖不住 node 的原生调用、更覆盖不住 MCP 服务器。与其做一个「看起来安全」的进程内开关，不如明确告诉用户：边界请画在进程外。这与 CONTRIBUTING.md 的第一句哲学一致——「pi's core is minimal. If your feature does not belong in the core, it should be an extension.」（核心保持极简；不属于核心的功能做成扩展。）

§14.2Project Trust：启动边界，不是运行时边界

一句话类比：project trust 像 IDE 打开陌生项目时问你的那句「是否信任此项目并加载它的构建脚本」——它管的是启动时加载不加载，不是运行时能不能碰你的文件。

Pi 在工作目录中发现以下任何一项时，会要求你做出项目信任（project trust）决策，防止一个文件夹在你批准之前悄悄加载可执行扩展：

- .pi/settings.json
- .pi/mcp.json
- .pi/extensions, .pi/skills, .pi/prompts, .pi/themes
- .pi/SYSTEM.md 或 .pi/APPEND_SYSTEM.md
- 当前目录或祖先目录中的项目级 .agents/skills

授予信任后，Pi 才会加载：项目设置、.pi/mcp.json 里的项目 MCP 服务器、.pi 下的扩展/技能/提示模板/主题/系统提示词文件、项目设置声明的缺失包（missing packages），以及项目本地与项目包扩展。拒绝信任则跳过这些受保护资源——但有两个关键例外：

1. sessionDir 先读例外：Pi 在解析 project trust 之前，就要读取项目的 sessionDir 设置来选择/创建会话。拒绝信任无法撤销这次初始目录查找——所以文档说 project trust 「不是一个完整的启动边界」。
2. 上下文文件不设门：AGENTS.override.md、AGENTS.md、CLAUDE.md 无论是否授信都会加载（除非你关闭 context loading）。所以仓库里的说明文件永远要当作不可信输入对待。

更要紧的一句：project trust 不限制工具调用能访问或影响什么。Pi 启动之后，启用的工具仍然使用 Pi 进程的操作系统权限；目录里的指令内容也照样能影响模型。信任决策只回答「启动时加载哪些资源」，不回答「运行时能做什么」。

决策顺序与保存位置

当受保护资源存在且没有命令行覆盖时，Pi 按以下顺序决策：

1. 命令行 --approve / --no-approve 优先级最高；
2. 用户级与命令行扩展可处理 project_trust 事件，第一个返回 yes/no 的扩展拥有决定权；
3. 否则查保存过的决策：当前目录或祖先目录的最近决策生效（保存在 ~/.pi/agent/trust.json，按规范化路径记录）；
4. 仍无决策时，遵循全局设置 defaultProjectTrust，默认值 "ask"。交互中用 /trust 可保存决策供未来进程使用。

print、JSON、RPC 模式无法弹出内置信任提示。没有覆盖、扩展决策或保存决策时：defaultProjectTrust: "always" 会加载受保护资源；"ask" 或 "never" 则跳过。自动化运行需要一次性明确决策时，用 --approve 或 --no-approve。

§14.3凭据、会话导出与 /bug：三条容易被忽视的泄露面

容器化解决「模型能碰什么」；这一节解决「我们自己会把什么带出去」。三条泄露面都写在文档里，却最容易被日常习惯掩盖。

泄露面一：~/.pi/agent 是你的全部身家

用户级配置目录 ~/.pi/agent 集中了认证文件 auth.json（/login 的产物）、设置、已安装扩展与全部会话记录。containerization.md 的警告非常直白：挂载宿主的 ~/.pi/agent 等于把你的 Pi 凭据、设置、扩展和会话全部交进容器。对 p2 这类服务器形态，README 同样强调 provider 凭据保存在服务端私有的 auth.json 里、数据目录必须保持私有。

泄露面二：会话导出与分享

security.md 要求：导出或分享会话前必须先审查——会话可能包含提示词、工具参数、命令输出、文件内容，以及对话过程中暴露出来的凭据。第 10 讲我们看过 JSONL 会话文件的结构：user 消息、toolCall 参数、toolResult 全文落盘。你在会话里 cat 过一次 .env、粘贴过一次 token，它就永远在导出物里。分享 session 文件、HTML 导出、截图求助之前，先把这三类内容过一遍。

泄露面三：/bug 报告内容

/bug [description] 用于准备一份发给 Pi 开发者的私密错误报告（sessions.md）。你可以选择包含会话 transcript、不包含、或让当前模型先总结一遍问题。关键动作是提交前审查：transcript 或模型生成的摘要都可能含敏感对话数据。让模型代写摘要并不等于脱敏——它只是把原文压短，敏感字段大概率原样保留。上传目标可以通过环境变量 PI_RADIUS_GATEWAY 覆盖（environment-variables.md）。

§14.4容器化三方案：把边界画在进程外

一句话类比：与其给助手配一个「按步审批」的监工，不如把它关进一间只能碰到指定工具的房间——房间由操作系统或虚拟机看守，Pi 自己说了不算。

隔离的总体思路只有两种：把整个 Pi 进程放进隔离环境（Plain Docker、Docker Sandboxes、OpenShell），或者 Pi 留在宿主、只把工具执行路由进隔离环境（Gondolin 扩展）。位置不同，扩展的运行位置就不同：整进程隔离时扩展跟着进边界；Gondolin 模式下，其他扩展工具仍在宿主运行，除非它们也把工作委托进 micro-VM。

方案一：Plain Docker——最直接的整进程边界

官方文档给出的最小镜像基于 node:24-bookworm-slim，全局安装 CLI 后以 pi 为入口。两条关键纪律：凭据通过 -e 环境变量显式传入（只传任务需要的那一个）；容器本地的 Pi 主目录用命名卷 pi-agent-home 保存，而不是挂载宿主的 ~/.pi/agent。

FROM node:24-bookworm-slim
RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
WORKDIR /workspace
ENTRYPOINT ["pi"]

# 启动（宿主工作目录即要访问的目录）：
# docker run --rm -it -e ANTHROPIC_API_KEY \
#   -v "$PWD:/workspace" -v pi-agent-home:/root/.pi/agent pi-sandbox

方案二：Gondolin——宿主保存认证，工具进 micro-VM

Gondolin 是一个本地 Linux micro-VM（QEMU），示例扩展把 Pi 进程与文件型 provider 凭据留在宿主，把内置工具与用户 ! 命令路由进 VM 执行。它覆盖（override）的工具恰好是七个：read、write、edit、bash、grep、find、ls；宿主工作目录挂载为 VM 内的 /workspace，文件修改直通宿主。环境要求：Node.js 23.6+ 与系统包管理器安装的 QEMU。

三个必须记住的限制：第一，VM 内命令继承宿主进程的环境变量——如果你的 API key 走环境变量，它在 VM 里同样可见，这种模式就不是凭据边界，除非先移除敏感变量或改造扩展的环境处理；第二，其他扩展工具仍在宿主运行，除非它们显式把操作委托进 VM——给 Gondolin 加工具前先读示例源码，别无意中凿穿边界；第三，它保护的是「工具执行」这一段，不保护 Pi 进程本身。

方案三：OpenShell——按策略画出最细的线

NVIDIA OpenShell 提供本地或远程沙箱，策略覆盖文件系统、进程、网络、凭据与推理路由。每个沙箱需要一个激活的 gateway：openshell gateway add 后 gateway select；然后 openshell sandbox create --name pi-sandbox --from pi -- pi 让 Pi 连同工具与扩展整进程进入边界。远程 gateway 不做宿主目录 bind-mount，需要 sandbox upload / sandbox download 显式传文件。配置推理路由后，原始模型凭据可以留在沙箱外，Pi 指向 gateway 暴露的 OpenAI / Anthropic 兼容端点。

无论选哪种：先决定「暴露什么」

隔离环境里能碰到什么，取决于你暴露了什么：读写挂载 = 容器可改宿主文件；挂载 ~/.pi/agent = 交出凭据与会话；传入的环境变量对内部进程全量可见；开放网络 = 代码与工具输出可以外传。原则只有一句：只暴露任务需要的工作目录、凭据与网络目的地；不需要写入就用只读挂载或复制进出。

§14.5安全清单：把「不可信输入」当作默认前提

把 security.md 的建议浓缩成一张可以贴在团队 Wiki 上的清单。它不能替代隔离，但能显著缩小暴露面、加快恢复：

• 只用可信来源的扩展与包：扩展在 Pi 进程内执行，等于「以你的身份运行别人的代码」；第三方包可能内置指示模型运行程序的技能，安装前先读源码，项目包声明在授予 project trust 前先审查。
• 逐行审查 SKILL.md 与 scripts/：技能的本质是「指示模型做什么」的文本 + 可执行脚本。看三处：frontmatter 的 description 何时触发加载、正文指令是否要求运行脚本、scripts/ 与 references/ 里有没有奇怪的内容。不熟的技能，在授予 project trust 前别加载。
• 导出与会话分享前脱敏：提示词、工具参数、命令输出、文件内容、对话中暴露的凭据都在会话里；/bug 的 transcript 与模型摘要同样要过目。
• 最小授权：专用 OS 用户或容器边界收窄权限；只挂载任务所需目录；能只读就只读；网络按需开放。
• 短命且窄域的凭据：优先使用小范围、短时效凭据；能留在外层（宿主 / gateway / 代理）就不带进环境；进入过会话上下文的 secret 视为已泄露，及时轮换。
• 可恢复性：大改动前打快照、备份或确认版本控制干净；应用生成结果到另一个系统前先 review diff。

最后重申一条否定式结论，方便你在 code review 里引用：盯 transcript、project trust、事后审查 diff，都不构成安全边界。它们回答「发生了什么」，不回答「能发生什么」。

§14.6综合实战：pi-java-review 包从零到可分发

这是全课程的毕业项目：用第 11 讲的扩展、第 12 讲的技能与包、第 13 讲的 RPC，为一个真实 Java 工作流组装一个可安装、可分享的 Pi 包。它不新增框架知识，只考验「把零件装成机器」的能力。

目标场景：团队用 Pi 辅助维护一个 Maven 单模块 Java 服务。我们希望——① 模型只能写 src/main 与测试目录，误碰别处直接拦截；② 每轮改动后自动跑 mvn compile 把结果喂回给模型；③ 评审遵循团队规范（技能 + 参考清单）；④ CI 或本地一条命令批量预审 PR 里的 Java 文件。

pi-java-review/
├── package.json                # pi 清单：声明扩展/技能/模板
├── extensions/
│   └── java-guard.ts           # 写保护 + mvn 校验
├── skills/
│   └── java-review-standards/
│       ├── SKILL.md            # 技能入口（frontmatter + 指令）
│       └── references/
│           └── checklist.md    # 评审清单（按需加载的参考）
├── prompts/
│   └── pr-review.md            # /pr-review 提示模板
└── scripts/
    └── pr-precheck.mjs         # RPC 批量预审脚本（不随包加载）

14.6.1 扩展：写路径拦截 + mvn compile 回灌

两个钩子各司其职：tool_call 在工具执行前拦截（可返回 { block: true, reason }，文档明确该事件可阻塞）；agent_end 在一轮运行结束时做编译校验，用 pi.exec 不经 shell 执行 Maven，再把结果通过 pi.sendMessage 以 followUp 方式送回上下文（文档：followUp 等待 agent 空闲后投递）。骨架中所有需要按环境调整的点都用 ★ 注释标出：

/**
 * pi-java-review · java-guard
 * 1) 拦截对允许前缀之外的 write / edit
 * 2) 一轮运行若有写操作，结束后跑 mvn compile 并把结果回灌给模型
 */
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

// ★ 按团队规范调整：允许写入的路径前缀（相对工作目录，/ 分隔）
const WRITABLE_PREFIXES = ["src/main/java/", "src/main/resources/", "src/test/java/"];
// ★ Windows 通常可执行名是 mvn.cmd；也可改用 mvnw（包装器）
const MVN = process.platform === "win32" ? "mvn.cmd" : "mvn";
// ★ 编译超时（毫秒）：按项目体量调整
const MVN_TIMEOUT_MS = 120_000;

export default function (pi: ExtensionAPI) {
  let dirty = false;   // 本轮是否发生过成功的写操作
  let checking = false; // mvn 运行中的重入保护

  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName !== "write" && event.toolName !== "edit") return undefined;

    // event.input 是 schema 校验后的工具参数——这里是「决定的信任边界」，
    // 做一次形状收敛符合 AGENTS.md 的校验规则；正式版可改用 isToolCallEventType 窄化。
    const path = String((event.input as { path?: unknown }).path ?? "");
    const rel = path.replaceAll("\\", "/").replace(/^\.?\//, "");
    const allowed = WRITABLE_PREFIXES.some((p) => rel.startsWith(p));

    if (!allowed) {
      if (ctx.hasUI) ctx.ui.notify(`已拦截对 ${path} 的写入`, "warning");
      return { block: true, reason:
        `pi-java-review: ${path} 不在允许写入的前缀内（${WRITABLE_PREFIXES.join(", ")}）` };
    }

    dirty = true; // 放行的写操作，留待本轮结束校验
    return undefined;
  });

  pi.on("agent_end", async (_event, ctx) => {
    if (!dirty || checking) return;
    dirty = false;
    checking = true;
    try {
      const result = await pi.exec(MVN, ["-q", "-DskipTests", "compile"],
        { timeout: MVN_TIMEOUT_MS, signal: ctx.signal });
      const output = [result.stdout, result.stderr].filter(Boolean).join("\n").slice(0, 4000);
      pi.sendMessage({
        customType: "pi-java-review",
        content: result.code === 0
          ? "mvn compile 通过。"
          : `mvn compile 失败（exit ${result.code}）：\n${output}`,
        display: true,
      }, { triggerTurn: true, deliverAs: "followUp" });
    } finally {
      checking = false;
    }
  });
}

两个工程细节值得强调。其一，dirty 只在放行写入时置位、checking 防重入，避免「编译失败 → 回灌 → 新一轮又触发编译」的死循环——回灌那一轮通常没有写操作，循环自然收敛。其二，这是防呆闸门而不是安全边界（§14.1）：它与工具同进程，真正对抗恶意输出的仍是容器化方案。

14.6.2 技能：规范正文 + 按需加载的 references

第 12 讲的关键结论在这里落地：启动时只有 name 与 description 进入系统提示词，完整指令在任务匹配时才被读取——所以 SKILL.md 保持短小，把大清单放进 references/，由技能正文指示模型「先读再审」：

---
name: java-review-standards
description: 团队 Java 代码评审规范。在评审、修改 Java 源码、
  处理 PR 或解释 Java 改动时使用。
---

# Java 评审规范

1. 审查任何 Java 改动前，先完整读取 `references/checklist.md`。
2. 评审结论按严重级别分组：blocker / major / minor / nit。
3. 每条发现必须给出：位置（文件:行）、问题、为什么、建议修复。
4. 未经明确要求不要直接修改文件；建议修复以 diff 形式给出。
5. ★ 在此追加团队特有规则（框架版本、日志库、异常规范等）。

references/checklist.md（骨架）按团队习惯填充，例如：空安全与边界、异常与资源关闭（try-with-resources）、并发与不可变、日志级别与敏感字段、事务边界、API 兼容性、测试覆盖缺口。分发前记得用第 12 讲的验证流程：启动看诊断、/skill:java-review-standards 强制加载、改完 /reload。

14.6.3 提示模板：/pr-review

---
description: 按团队规范审查当前 git 改动
argument-hint: "[focus]"
---
按 java-review-standards 技能中的规范，审查当前 git 改动
（未暂存与已暂存都要看）。重点：${1:-空安全、异常处理、并发安全、日志规范}。
输出按文件分组的发现列表；只报告问题，不要修改文件。

14.6.4 RPC 脚本：PR 批量预审

第 13 讲的 RpcClient 在这里变成 CI 的第一道闸：对 git diff --name-only 得到的每个 Java 文件发一次审查 prompt，收集文本输出。脚本放在 scripts/（不进 pi 清单，不会被 Pi 加载），由人或流水线显式运行：

// 用法示例：
//   git diff --name-only origin/main...HEAD -- "*.java" | xargs node scripts/pr-precheck.mjs
// 前置：npm install @earendil-works/pi-coding-agent（本脚本自行依赖）
import { RpcClient } from "@earendil-works/pi-coding-agent";

const files = process.argv.slice(2).filter((f) => f.endsWith(".java"));
if (files.length === 0) { console.error("没有待审的 .java 文件"); process.exit(1); }

const client = new RpcClient({
  cliPath: process.env.PI_CLI ?? "pi",  // ★ 仓库示例用 dist/cli.js，按安装方式调整
  args: ["--no-session",
         "--provider", "anthropic",        // ★ 按团队默认调整
         "--model", "claude-sonnet-4-5"], // ★ 按团队默认调整
});

let text = "";
const unsubscribe = client.onEvent((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    text += event.assistantMessageEvent.delta;
  } else if (event.type === "tool_execution_start") {
    console.error(`  [tool] ${event.toolName}`);
  }
});

try {
  await client.start();
  for (const [i, file] of files.entries()) {
    text = "";
    console.error(`(${i + 1}/${files.length}) ${file}`);
    await client.promptAndWait(
      `按 java-review-standards 技能审查 ${file} 在本次 diff 中的改动；` +
      `只报告问题（blocker/major/minor/nit），不要修改任何文件。`);
    console.log(`\n=== ${file} ===\n${text.trim()}`);
  }
} finally {
  unsubscribe();
  await client.stop();
}

把这个脚本接入 CI 时，回到 §14.4 的纪律：RPC 子进程继承流水线环境的凭据与网络；预审任务只需要读仓库 + 调模型，那么就在只读挂载、无多余凭据的容器里跑它。

14.6.5 打包与分发

{
  "name": "pi-java-review",
  "version": "0.1.0",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions/java-guard.ts"],
    "skills": ["./skills/java-review-standards"],
    "prompts": ["./prompts/*.md"]
  },
  "peerDependencies": {
    "@earendil-works/pi-coding-agent": "*"
  }
}

§14.7贡献流程：从 issue 到 PR

学完源码之后，最自然的下一步是回馈一个文档修正或小 bugfix。Pi 的贡献流程比多数开源项目更「硬」——先理解规则，再动手。

协作规则要点（AGENTS.md）

• The One Rule：You must understand your code.（必须理解你提交的代码。）用 AI 写代码可以，提交不理解的东西不行；在仓库根目录跑 agent，让它自动读取 AGENTS.md 并遵守。
• 核心极简：不属于核心的功能做成扩展；会让核心膨胀的 PR 大概率被拒。
• 代码质量：读全文件再大改；尽量避免 any；不在 TypeScript 已保证类型的地方做运行时检查，只在「决定的信任边界」（wire 输入、schema 校验后的参数）校验；只用可擦除 TypeScript 语法（Node strip-only 模式）；不用内联 import；packages/ai/src/models.generated.ts 不许手改。
• Git 纪律：同目录可能有多个 pi 会话并行工作——只提交自己改的文件、显式 git add <path>、禁止 git add -A / git add . / reset --hard / stash / --no-verify；提交信息格式 {feat,fix,docs}[(ai,tui,agent,coding-agent)]: 说明；关闭 issue 在信息里写 fixes #123（每个 issue 重复一次关键字）。
• CHANGELOG 规范：位置在 packages/*/CHANGELOG.md（每个包一个）。新条目一律追加到 ## [Unreleased] 下既有的 ### Breaking Changes / Added / Changed / Fixed / Removed 小节，不重复建节；已发布版本段落（如 ## [0.12.2]）不可修改；分支不是 main 的改动不写 changelog。外部贡献按模板标注 issue/PR 号与作者。注意分工：CONTRIBUTING.md 明确外部贡献者不要改 CHANGELOG.md，条目由维护者添加。

贡献门（CONTRIBUTING.md）

新贡献者的 issue 与 PR 默认自动关闭，维护者每日复查并重新打开值得处理的。解锁方式是维护者在 issue 回复中的口令：lgtmi（未来 issue 不再自动关闭）与 lgtm（未来 issue 和 PR 不再自动关闭；只有它授予 PR 提交权）。口令必须出现在回复的开头（可前置 @username）或结尾。issue 质量标准：用模板、一屏以内、用自己的话写、说清 bug 与影响、想自己实现就说明。周五到周日的 issue 不保证被看；紧急问题去 Discord。大改动先看 RFC：rfc.earendil.com（关键词 pi）。

提交前的检查命令

# 提交 PR 前，两条必须全部通过：
npm run check     # biome + 依赖检查 + tsc --noEmit + 浏览器冒烟等
./test.sh         # 在隔离环境中跑完整测试套件

# pi-test.sh：从源码直接运行 pi（source resolver，无需构建）；
# --no-env 会清掉全部 provider 凭据环境变量（列表见
# packages/ai/src/env-api-keys.ts），适合验证「无凭据」行为：
./pi-test.sh --no-env -p "hello"

§14.8延伸阅读：durable、p2 与 pi-chat

课程主线止步于 coding-agent 的当前形态；仓库里还有三个值得持续关注的方向，它们回答同一个问题的不同侧面：Agent 运行时要变得更可靠、更长期，还需要什么？

pi-durable：Persist and Resume

packages/durable（实验性）是一个持久化 Agent 运行时：会话、模型轮次、工具调用与你自己的状态，在对外可见之前先提交到存储。进程在执行中途死掉，重开存储后从停止处继续；死掉时所处的那次模型请求计为一次失败尝试并被重试——一个反复杀死进程的请求最终会结束（Persist and Resume）。类比 Java：这是 WAL（预写日志）+ 幂等重试在 Agent 上的翻版，「先落盘再响应」换来了崩溃恢复能力。它基于 pi-ai 与 chord（文档状态层），API 随版本变化且不作通知。

p2：自托管的 Durable UI（原型）

apps/p2 是用独立 Chord 插件搭的自托管 Pi Durable UI 原型，README 第一行就警告：实验性、即将被替换、不要在其上构建任何依赖。安全模型与本章呼应：所有者对服务器与 worker 拥有完整 agent 与 shell 控制——这不是服务端文件系统隔离；服务只监听 loopback，身份由私有数据目录（0700）中的 owner-key 决定，签名 cookie、一次性登录 token、设备会话各有细粒度撤销语义。它是「把第 14 讲的威胁模型搬到服务端形态」的活教材：凭据仍在私有 auth.json，隧道与代理的每个环节都可能成为泄露面。

pi-chat：聊天平台自动化

根 README.md 指向独立仓库 earendil-works/pi-chat：面向 Slack 等聊天平台的自动化与工作流集成。结合 p2 文档里的 Discord 集成（提到机器人即可唤醒沙箱会话）可以窥见方向——Pi 的扩展、技能与包体系正在被复用到「多入口、长驻、多人共享」的形态。学完 14 讲的你，已经有能力直接读这些上游项目的源码。

§14.9课程回顾：1–14 讲知识地图

最后一页纸，把十四讲串成一张地图。每个阶段解决一层问题，下一层站在上一层之上；点击任意讲次可回跳复习。

如果只带走一条主线：Pi 把「大模型请求 → 工具执行 → 结果回填 → 再请求」这个循环做成了可插拔的骨架——模型层可换（pi-ai）、工具可换（tool registry）、能力可注入（extensions / skills / packages）、进程边界可画（容器化）、可靠性可持续演进（durable）。理解了骨架，任何一层的新变化都只是插件的位置变了。

动手实践

常见误区