Pi Agent 集成指南：为 Pi Coding Agent 部署 planning-with-files 持久化规划扩展-编程实验室

Pi Agent 集成指南：为 Pi Coding Agent 部署 planning-with-files 持久化规划扩展

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files

本文是基于 planning-with-files 官方文档 docs/pi-agent.md 的完整实战指南，讲解如何为 Pi Coding Agent 安装 skill 与扩展、理解其八类生命周期事件、配置 DeepSeek-aware 四模式运行系统，并通过/plan-execute、/plan-attest等命令完成从被动评审到主动执行的规划闭环。读完本文，你将掌握在 Pi 中让规划文件（task_plan.md、findings.md、progress.md）穿越/clear、压缩与会话崩溃而持续生效的完整方案。

概述：为什么 Pi 需要文件级规划

planning-with-files 的核心思想是把 Agent 的「工作记忆」从易失的上下文窗口搬到磁盘上：上下文窗口相当于易失的 RAM，而文件系统是持久化的磁盘。任何重要信息都应写入磁盘，而不是塞进窗口。在 Pi Coding Agent 中，这套机制由一个skill（三文件规划工作流）和一个extension（hook 行为对等运行时）共同承载，后者把 Claude Code 插件路径上的生命周期钩子行为，以 Pi 的扩展事件机制原样复刻，让 Pi 获得与 Claude Code 对等的规划注入与完成门控能力。

安装

推荐方式：通过 npm 安装

pi install npm:planning-with-files

这条命令现在会一次性安装两样东西：

Skill：planning-with-files（三文件规划工作流，对应task_plan.md、findings.md、progress.md）
Extension：planning-with-fileshook 对等运行时（八类生命周期事件处理器）

手动安装（仓库拷贝）

# 克隆仓库 git clone https://github.com/OthmanAdi/planning-with-files.git cd planning-with-files # 将 skill 包拷贝到你的 Pi skills 目录 mkdir -p ~/.pi/agent/skills/planning-with-files cp -r .pi/skills/planning-with-files/* ~/.pi/agent/skills/planning-with-files/

仓库内的 .pi/skills/planning-with-files/ 目录即是 Pi 适配器的完整载体，包含SKILL.md、scripts/（与主项目同一套 26 个脚本，如attest-plan.sh、session-catchup.py、resolve-plan-dir.sh等）、templates/（含task_plan.md、findings.md、progress.md、loop.md模板）以及extensions/planning-with-files/下的 TypeScript 扩展源码。

Pi 现已支持的能力

Pi 集成通过扩展事件提供 Claude 风格的生命周期行为（对应源码实现见 runtime.ts）：

生命周期事件	行为
`session_start`	会话追赶（session catchup），读取项目规划文件恢复上下文
`before_agent_start`	`/plan-execute`之后的计划上下文提醒/注入
`tool_call`	`/plan-execute`之后的工具调用前计划背诵（pre-tool recitation）对等物
`tool_result`	`/plan-execute`之后的写后提醒
`agent_end`	`/plan-execute`之后的自动继续守卫（上限 3 次）
`session_before_compact`	压缩前的提醒
计划证明守卫	`[PLAN TAMPERED — injection blocked]`，篡改即阻止注入

除上述七个事件外，源码中还注册了session_shutdown（清理定时器与状态）和input（用户输入时重置前缀状态）两个内部清理事件。测试 test_pi_extension_capabilities.py 通过正则断言验证了这些必需事件（session_start、before_agent_start、tool_call、tool_result、agent_end、session_before_compact、input）均已在运行时中注册。

模式系统（DeepSeek-aware）

扩展支持四种模式：

auto（默认）：自动检测模型——DeepSeek 模型走cache-safe，其他模型走parity
parity：最大程度对等 Claude 行为（动态计划注入，每轮注入===BEGIN PLAN DATA===围栏的计划头 50 行与进度尾部 20 行）
cache-safe：稳定的固定提醒，为 DeepSeek 等对 KV-cache 命中率敏感的模型保持注入字节前缀稳定
notify：仅 UI 通知，不向对话注入任何内容

在源码 runtime.ts 中，auto模式通过deriveEffectiveMode检查ctx.model.provider与ctx.model.id是否包含deepseek来决定有效模式；cache-safe模式使用 constants.ts 中固定的CACHE_SAFE_REMINDER（"Read task_plan.md for current phase and status..."），而parity模式则构造完整的计划数据块注入。

通过环境变量配置

PWF_MODE=auto pi PWF_MODE=parity pi PWF_MODE=cache-safe pi PWF_MODE=notify pi

通过设置文件配置

项目级配置（.pi/settings.json）覆盖全局配置（~/.pi/agent/settings.json）：

{ "planningWithFiles": { "mode": "auto" } }

配置解析顺序在源码中有明确实现（resolveConfiguredMode）：优先读环境变量PWF_MODE，其次项目级.pi/settings.json，再其次全局~/.pi/agent/settings.json，全部缺失时回落到auto。设置文件采用容错读取（safeReadJson），JSON 解析失败或被截断不会导致扩展崩溃。

命令

安装后，以下扩展命令可用（Pi 中直接输入，无前缀）：

命令	作用
`/plan-status`	显示当前计划的数量统计与路径
`/plan-attest [--show\\|--clear]`	管理计划 SHA-256 证明
`/plan-execute`	批准当前活动计划并启用 hook 激活
`/plan-execute reset`	将活动计划恢复到被动评审模式
`/plan-goal <text\\|default\\|clear>`	设置/清除继续目标文本
`/plan-loop [10m] [prompt...]`	周期性规划 tick；用`stop`取消

命令背后的源码行为

/plan-status（runtime.ts）：读取readPlanStatus，通过ctx.ui.notify输出计划路径、作用域（root/scoped）、阶段总数、已完成/进行中/待处理阶段数；计划缺失或会话歧义时给出对应警告。
/plan-attest（L382-L397）：调用attest-plan.sh（Windows 下优先attest-plan.ps1），--show展示当前 SHA-256，--clear清除证明。Pi 运行时读取与 Claude Code 相同的.attestation文件（scoped 计划在.planning/<id>/.attestation，root 计划在项目根.plan-attestation），因此在任一运行时证明一次即可锁定两个运行时的计划。
/plan-execute（L416-L454）：检查计划存在性与会话歧义后，先做证明校验——若checkPlanAttestation判定tampered，直接拒绝批准并输出[PLAN TAMPERED — injection blocked]及期望/实际哈希与Run /plan-attest指引；校验通过则将sessionId:planPath键加入executionApprovedBySessionPlan集合，此后的before_agent_start、tool_call、tool_result、agent_end处理器才会真正注入或背诵计划。
/plan-goal（L399-L414）：按会话存储目标字符串，clear/off/disable清除，default使用内置DEFAULT_GOAL_CONDITION（"all phases in task_plan.md report Status: complete and check-complete.sh reports ALL PHASES COMPLETE"）。该目标会追加到自动继续消息中。
/plan-loop（L456-L510）：解析间隔规格（10m、30s、2h、1d等），默认10 * 60 * 1000ms 即 10 分钟，定时执行默认 tick 提示（重读task_plan.md与progress.md、运行check-complete.sh、按需更新状态行并继续下一阶段）；全部阶段完成或计划closed时自动停止；stop立即取消。

使用流程

第一步：初始化 skill

/skill:planning-with-files

第二步：让 Pi 创建/更新三个规划文件

task_plan.md— 阶段与检查项（### Phase N头 +**Status:**状态行或[complete]/[in_progress]/[pending]标记）
findings.md— 研究笔记与决策
progress.md— 会话日志与测试结果

计划解析逻辑见 plan.ts：优先按PLAN_ID精确绑定（slug 必须通过安全正则^[A-Za-z0-9_][A-Za-z0-9._-]*$且经realpath包含性校验，防止符号链接逃逸出项目根），其次.planning/.active_plan指针，再次按task_plan.mdmtime 最新的 slug 目录，最后回落到根级task_plan.md。resolveAnchor还会从实时 shell cwd 向上查找最近携带规划状态的祖先目录（受.git边界与 10 层深度上限约束），因此 Agent 即使cd进子目录也不会丢失计划。

第三步：评审并批准

在评审阶段，扩展保持被动：可能显示计划状态，但不会注入计划上下文、在工具调用前背诵计划，也不会自动继续。计划符合预期后执行：

/plan-execute

第四步：长任务执行

对于长任务，保持task_plan.md作为事实来源（source of truth），让激活后的 hooks/扩展事件强制执行循环：

before_agent_start：每轮开始注入计划（parity 模式为完整计划块，cache-safe 模式为固定提醒，notify 模式仅状态栏）
tool_call：write/edit/bash/read/grep/find/ls等可追踪工具前排队背诵（每叶子一次）；同时用词边界正则检测危险 bash 命令（rm -rf、sudo、chmod 777、git push --force/--mirror、git reset --hard、git clean -fd、fork bomb、dd写裸盘等）并弹出警告
tool_result：write/edit之后发送"更新 progress.md，阶段完成则更新 task_plan.md 状态"的写后提醒
agent_end：计划未完成时自动继续（上限 3 次，AUTO_CONTINUE_LIMIT = 3），追加/plan-goal设置的目标；provider 报错或用户中止的回合不计入次数（防止向故障 provider 重复轰炸）
session_before_compact：压缩发生前提醒刷新progress.md与task_plan.md，parity 模式下输出压缩前提醒并附Plan-SHA256

规划证明（Attestation）

扩展内置计划证明守卫：/plan-attest将task_plan.md以 SHA-256 锁定（scoped 计划写入.planning/<id>/.attestation，root 计划写入.plan-attestation）。每次注入前 attestation.ts 会重算计划文件哈希并与期望值比对：

期望哈希缺失或无法读取 → 视为tampered，阻止注入
实际哈希与期望不符 → 输出[PLAN TAMPERED — injection blocked]、期望/实际哈希与重新批准指引

/plan-execute在批准阶段同样先做此校验，被篡改的计划无法获得批准。

排查指南

确认包已安装：
```
pi list
```
重载运行时：
```
/reload
```
检查 skill 与扩展路径：
- skill：.pi/skills/planning-with-files/
- extension：extensions/planning-with-files/index.ts（入口将运行时委托给runtime.ts）
若计划注入被阻止，先查看证明状态：
```
/plan-attest --show
```
然后对有意修改过的计划重新证明：
```
/plan-attest
```

扩展源码结构参考

Pi 扩展的 TypeScript 源码位于 .pi/skills/planning-with-files/extensions/planning-with-files/，包内package.json声明对@earendil-works/pi-coding-agent的 peer 依赖：

文件	职责
index.ts	扩展入口，导出默认插件函数
runtime.ts	八类生命周期事件处理器、五个命令注册、模式解析、计划注入/背诵/提醒构造
plan.ts	计划路径解析（anchor 锚定、slug 校验、包含性检查、会话隔离）与阶段状态统计
attestation.ts	SHA-256 证明校验
constants.ts	围栏标记、固定提醒文案、自动继续上限、loop 默认参数

扩展自带 Vitest 测试套件（__tests__/下的runtime.test.ts、attestation.test.ts、plan-anchor.test.ts），可在扩展目录内通过npm test运行。此外，仓库根级测试 test_pi_extension_capabilities.py 与 test_pi_docs_hook_support.py 以行为契约方式验证扩展源码覆盖 Claude 对等 hooks、DeepSeek cache-safe 模式、session_start追赶仅使用--no-history（不读取会话历史）、自动继续上限为 3、plan-execute命令已注册、篡改阻止消息存在以及计划解析保留PLAN_ID/.active_plan/最新目录三级回退。

与上下文丢失对抗的完整机制

结合 README.md 中描述的通用机制，Pi 路径上的完整防护如下：

/clear与会话崩溃：计划文件在磁盘上，session_start事件通过session-catchup.py --no-history做纯文件追赶（自动恢复只读项目规划文件，不读取宿主会话存储），下一轮before_agent_start即把当前阶段重新注入
上下文压缩：session_before_compact在压缩完成前刷新进度提醒，并打印压缩时的Plan-SHA256
目标漂移：每轮重新注入计划头，配合cache-safe模式的 KV-cache 稳定前缀
过早宣告完成：agent_end自动继续守卫按需追加"更新 progress.md、读取 task_plan.md、继续剩余阶段"的消息（上限 3 次）
计划被静默改写：SHA-256 证明在注入与批准两个环节双重拦截篡改
危险命令：词边界正则对rm -rf、强制 push 等破坏性操作在tool_call阶段给出"先审查 task_plan.md 当前阶段再批准"的警告