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三文件规划工作流和一个extensionhook 行为对等运行时共同承载后者把 Claude Code 插件路径上的生命周期钩子行为以 Pi 的扩展事件机制原样复刻让 Pi 获得与 Claude Code 对等的规划注入与完成门控能力。安装推荐方式通过 npm 安装pi install npm:planning-with-files这条命令现在会一次性安装两样东西Skillplanning-with-files三文件规划工作流对应task_plan.md、findings.md、progress.mdExtensionplanning-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其他模型走parityparity最大程度对等 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_REMINDERRead task_plan.md for current phase and status...而parity模式则构造完整的计划数据块注入。通过环境变量配置PWF_MODEauto pi PWF_MODEparity pi PWF_MODEcache-safe pi PWF_MODEnotify pi通过设置文件配置项目级配置.pi/settings.json覆盖全局配置~/.pi/agent/settings.json{ planningWithFiles: { mode: auto } }配置解析顺序在源码中有明确实现resolveConfiguredMode优先读环境变量PWF_MODE其次项目级.pi/settings.json再其次全局~/.pi/agent/settings.json全部缺失时回落到auto。设置文件采用容错读取safeReadJsonJSON 解析失败或被截断不会导致扩展崩溃。命令安装后以下扩展命令可用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-statusruntime.ts读取readPlanStatus通过ctx.ui.notify输出计划路径、作用域root/scoped、阶段总数、已完成/进行中/待处理阶段数计划缺失或会话歧义时给出对应警告。/plan-attestL382-L397调用attest-plan.shWindows 下优先attest-plan.ps1--show展示当前 SHA-256--clear清除证明。Pi 运行时读取与 Claude Code 相同的.attestation文件scoped 计划在.planning/id/.attestationroot 计划在项目根.plan-attestation因此在任一运行时证明一次即可锁定两个运行时的计划。/plan-executeL416-L454检查计划存在性与会话歧义后先做证明校验——若checkPlanAttestation判定tampered直接拒绝批准并输出[PLAN TAMPERED — injection blocked]及期望/实际哈希与Run /plan-attest指引校验通过则将sessionId:planPath键加入executionApprovedBySessionPlan集合此后的before_agent_start、tool_call、tool_result、agent_end处理器才会真正注入或背诵计划。/plan-goalL399-L414按会话存储目标字符串clear/off/disable清除default使用内置DEFAULT_GOAL_CONDITIONall phases in task_plan.md report Status: complete and check-complete.sh reports ALL PHASES COMPLETE。该目标会追加到自动继续消息中。/plan-loopL456-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_callwrite/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_resultwrite/edit之后发送更新 progress.md阶段完成则更新 task_plan.md 状态的写后提醒agent_end计划未完成时自动继续上限 3 次AUTO_CONTINUE_LIMIT 3追加/plan-goal设置的目标provider 报错或用户中止的回合不计入次数防止向故障 provider 重复轰炸session_before_compact压缩发生前提醒刷新progress.md与task_plan.mdparity 模式下输出压缩前提醒并附Plan-SHA256规划证明Attestation扩展内置计划证明守卫/plan-attest将task_plan.md以 SHA-256 锁定scoped 计划写入.planning/id/.attestationroot 计划写入.plan-attestation。每次注入前 attestation.ts 会重算计划文件哈希并与期望值比对期望哈希缺失或无法读取 → 视为tampered阻止注入实际哈希与期望不符 → 输出[PLAN TAMPERED — injection blocked]、期望/实际哈希与重新批准指引/plan-execute在批准阶段同样先做此校验被篡改的计划无法获得批准。排查指南确认包已安装pi list重载运行时/reload检查 skill 与扩展路径skill.pi/skills/planning-with-files/extensionextensions/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.tsSHA-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 当前阶段再批准的警告这套机制的目标与 README 的定位一致让计划存活在磁盘上在/clear、压缩或崩溃之后Agent 能从当前阶段继续而不是重新描述任务、重新发现已完成的工作。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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三文件规划工作流和一个extensionhook 行为对等运行时共同承载后者把 Claude Code 插件路径上的生命周期钩子行为以 Pi 的扩展事件机制原样复刻让 Pi 获得与 Claude Code 对等的规划注入与完成门控能力。安装推荐方式通过 npm 安装pi install npm:planning-with-files这条命令现在会一次性安装两样东西Skillplanning-with-files三文件规划工作流对应task_plan.md、findings.md、progress.mdExtensionplanning-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其他模型走parityparity最大程度对等 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_REMINDERRead task_plan.md for current phase and status...而parity模式则构造完整的计划数据块注入。通过环境变量配置PWF_MODEauto pi PWF_MODEparity pi PWF_MODEcache-safe pi PWF_MODEnotify pi通过设置文件配置项目级配置.pi/settings.json覆盖全局配置~/.pi/agent/settings.json{ planningWithFiles: { mode: auto } }配置解析顺序在源码中有明确实现resolveConfiguredMode优先读环境变量PWF_MODE其次项目级.pi/settings.json再其次全局~/.pi/agent/settings.json全部缺失时回落到auto。设置文件采用容错读取safeReadJsonJSON 解析失败或被截断不会导致扩展崩溃。命令安装后以下扩展命令可用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-statusruntime.ts读取readPlanStatus通过ctx.ui.notify输出计划路径、作用域root/scoped、阶段总数、已完成/进行中/待处理阶段数计划缺失或会话歧义时给出对应警告。/plan-attestL382-L397调用attest-plan.shWindows 下优先attest-plan.ps1--show展示当前 SHA-256--clear清除证明。Pi 运行时读取与 Claude Code 相同的.attestation文件scoped 计划在.planning/id/.attestationroot 计划在项目根.plan-attestation因此在任一运行时证明一次即可锁定两个运行时的计划。/plan-executeL416-L454检查计划存在性与会话歧义后先做证明校验——若checkPlanAttestation判定tampered直接拒绝批准并输出[PLAN TAMPERED — injection blocked]及期望/实际哈希与Run /plan-attest指引校验通过则将sessionId:planPath键加入executionApprovedBySessionPlan集合此后的before_agent_start、tool_call、tool_result、agent_end处理器才会真正注入或背诵计划。/plan-goalL399-L414按会话存储目标字符串clear/off/disable清除default使用内置DEFAULT_GOAL_CONDITIONall phases in task_plan.md report Status: complete and check-complete.sh reports ALL PHASES COMPLETE。该目标会追加到自动继续消息中。/plan-loopL456-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_callwrite/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_resultwrite/edit之后发送更新 progress.md阶段完成则更新 task_plan.md 状态的写后提醒agent_end计划未完成时自动继续上限 3 次AUTO_CONTINUE_LIMIT 3追加/plan-goal设置的目标provider 报错或用户中止的回合不计入次数防止向故障 provider 重复轰炸session_before_compact压缩发生前提醒刷新progress.md与task_plan.mdparity 模式下输出压缩前提醒并附Plan-SHA256规划证明Attestation扩展内置计划证明守卫/plan-attest将task_plan.md以 SHA-256 锁定scoped 计划写入.planning/id/.attestationroot 计划写入.plan-attestation。每次注入前 attestation.ts 会重算计划文件哈希并与期望值比对期望哈希缺失或无法读取 → 视为tampered阻止注入实际哈希与期望不符 → 输出[PLAN TAMPERED — injection blocked]、期望/实际哈希与重新批准指引/plan-execute在批准阶段同样先做此校验被篡改的计划无法获得批准。排查指南确认包已安装pi list重载运行时/reload检查 skill 与扩展路径skill.pi/skills/planning-with-files/extensionextensions/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.tsSHA-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 当前阶段再批准的警告这套机制的目标与 README 的定位一致让计划存活在磁盘上在/clear、压缩或崩溃之后Agent 能从当前阶段继续而不是重新描述任务、重新发现已完成的工作。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考