如何在 Pi 中安装 planning-with-files 扩展并用 /plan-execute 激活钩子-二趣网

如何在 Pi 中安装 planning-with-files 扩展并用 /plan-execute 激活钩子

【免费下载链接】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

这篇文档面向使用 Pi Coding Agent 的开发者：你需要把 planning-with-files 以「skill + 扩展」的形式装进 Pi，让它在长任务中持续提供计划上下文；装好后，计划默认处于被动评审状态，只有你运行/plan-execute批准当前计划后，扩展才会激活全部生命周期钩子。整个流程的依据来自仓库中的 Pi Agent 安装指南与 README。

安装扩展

主路径是从 npm 安装：

pi install npm:planning-with-files

这条命令一次安装两个东西：

Skill：planning-with-files（3 文件计划工作流）；
Extension：planning-with-fileshook parity runtime（把 Pi 的生命周期事件映射为 Claude Code 同等的钩子行为）。

安装完成后的验证与加载步骤：

pi list

用pi list确认包已安装；随后在 Pi 会话内重新加载运行时：

/reload

如果命令仍不可用，按文档检查两处路径是否存在：

skill：.pi/skills/planning-with-files/
extension：extensions/planning-with-files/index.ts

可选分支：从仓库手动安装

文档给出的手动安装方式是克隆仓库后把 skill 包复制进你的 Pi skills 目录：

# Clone repo git clone https://github.com/OthmanAdi/planning-with-files.git cd planning-with-files # Copy skill package into your Pi skills directory mkdir -p ~/.pi/agent/skills/planning-with-files cp -r .pi/skills/planning-with-files/* ~/.pi/agent/skills/planning-with-files/

副作用说明：该分支会克隆仓库到你当前目录，并写入~/.pi/agent/skills/下的文件；仅当你无法使用 npm 通道时才需要走这条路径。

配置注入模式（可选）

扩展有四种模式，影响计划上下文如何注入对话：

模式	行为
`auto`（默认）	DeepSeek 模型 ->`cache-safe`；其他模型 ->`parity`
`parity`	最大 Claude 等效行为（动态计划注入）
`cache-safe`	固定的稳定提醒，提升 DeepSeek KV-cache 命中率
`notify`	只做 UI 通知，不注入对话

两种配置方式：

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

或在 settings 中配置，项目级.pi/settings.json覆盖全局~/.pi/agent/settings.json：

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

默认auto即可满足大多数场景；使用 DeepSeek 且关心缓存命中率时才需要显式指定。

创建计划并进入被动评审

安装后在 Pi 中先启动 skill：

/skill:planning-with-files

然后让 Pi 创建/更新三个文件：

task_plan.md
findings.md
progress.md

注意 Pi 上没有/plan命令来创建这些文件——由 skill 负责创建，/plan-execute只负责批准（这是 README 中「Pi extension commands」一节明确的差异）。此时扩展保持被动：可以显示计划状态，但不会注入计划上下文、不会在工具调用前复述计划，也不会自动继续。评审并编辑计划，直到内容符合你的意图。

用 /plan-execute 激活钩子

计划就绪后运行：

/plan-execute

该命令批准当前激活的计划并启用钩子激活（Pi 特有命令，无/planning-with-files:前缀）。激活后，扩展在以下生命周期事件上生效：

session_start：会话恢复（session catchup）；
before_agent_start：计划上下文提醒/注入；
tool_call：工具调用前的计划复述（pre-tool recitation 等效行为）；
tool_result：写入/编辑输出后的 post-write 提醒；
agent_end：未完成计划的自动继续保护，限制 3 次；
session_before_compact：压缩前的计划提醒；
计划证明保护：检测到篡改的计划会得到[PLAN TAMPERED — injection blocked]。

对长任务，把task_plan.md当作唯一事实来源，由激活后的钩子/扩展事件执行循环。如果不想再执行当前计划，用下面命令回到被动评审模式：

/plan-execute reset

结果验证与排查

按文档的 Troubleshooting 顺序判断安装是否到位：

确认包已安装：
```
pi list
```
重载运行时：
```
/reload
```
检查 skill 与 extension 路径（见安装一节列出的两个路径）。
如果计划注入被拦截（出现计划被篡改拦截），先查看当前证明状态，再对有意修改过的计划重新证明：
```
/plan-attest --show
```
```
/plan-attest
```
证明使用 SHA-256 锁定task_plan.md，且与 Claude Code 共享同一个.attestation文件——证明一次即可同时锁定两个运行时。

安装后还会注册这些扩展命令，可在会话内直接输入（无插件前缀）：

/plan-status— 显示当前计划计数与路径
/plan-attest [--show|--clear]— 管理计划 SHA-256 证明
/plan-execute//plan-execute reset— 批准激活 / 回到被动评审
/plan-goal <text|default|clear>— 设置/清除继续目标文本
/plan-loop [10m] [prompt...]— 周期性计划 tick，用stop取消

边界说明

钩子激活前，扩展只展示被动状态；所有注入与自动继续行为都以运行/plan-execute为前提。
agent_end的自动继续每个会话+计划最多 3 次，不会无限续跑。
TypeScript 扩展运行时只在 Pi 进程加载时运行，仓库没有针对 Pi 扩展运行时的 CI 测试（见 CHANGELOG v2.39.0 相关说明）；遇到 Pi 上的行为回归，问题应指向.pi/skills/planning-with-files/extensions/目录。

更多细节（模式选择、事件映射、证明机制）可继续查阅 docs/pi-agent.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析