pi-planning-with-files-zh

Pi 扩展：为 planning-with-files-zh 技能提供自动上下文注入和进度跟踪。

功能

• 内置 skills：扩展包包含完整的 planning-with-files-zh 技能
• 自动发现规划文件：在会话开始时自动查找 task_plan.md、findings.md、progress.md
• 上下文注入：每次对话时自动注入规划数据到上下文
• 工具调用闭环：工具调用前注入计划摘要，文件写入后把进度提醒追加到当前工具结果
• 自动继续：当计划未完成但 Agent 停止时，自动发起 follow-up turn 要求更新进度并继续
• 压缩保护：在上下文压缩前确保状态已保存
• 完整性检查：会话结束时检查所有阶段是否完成

安装

pi install npm:pi-planning-with-files-zh

更新

当源仓库 (planning-with-files) 更新后，本扩展也会发布新版本：

# 检查更新
pi update pi-planning-with-files-zh

# 或更新所有包
pi update

命令

• /refresh-plan - 强制重新读取并注入规划文件
• /plan-status - 显示当前计划状态和进度

文件位置

扩展会按以下顺序查找规划文件：

1. .planning/<plan-id>/task_plan.md（scoped 模式）
2. .planning/.active_plan 指向的计划
3. task_plan.md（root 模式）

工作原理

┌─────────────────────────────────────────────────────────────┐
│                   pi-planning-with-files-zh                  │
├─────────────────────────────────────────────────────────────┤
│  内置 skills/ 目录                                           │
│  ├── SKILL.md                                               │
│  ├── templates/                                             │
│  └── scripts/                                               │
├─────────────────────────────────────────────────────────────┤
│  Pi Extension API                                           │
│  ├── resources_discover → 注册技能并发现规划文件            │
│  ├── before_agent_start → 注入 task_plan.md + progress.md   │
│  ├── tool_call          → PreToolUse 等价计划复述           │
│  ├── tool_result        → 将更新提醒追加到当前工具结果      │
│  ├── agent_end          → 未完成计划时发起 follow-up turn   │
│  ├── session_before_compact → 压缩前提醒刷新规划文件        │
│  └── session_shutdown   → 清理和完整性提示                  │
└─────────────────────────────────────────────────────────────┘

版本同步

本扩展内置了 planning-with-files-zh 的 skills。当源仓库更新时：

1. 维护者运行 npm run sync-skills 同步最新 skills
2. 发布新版本到 npm
3. 用户通过 pi update 获取最新版本

源仓库版本与扩展版本对应关系：

| 扩展版本 | 源仓库版本 | |----------|-----------| | 1.0.x | v3.1.3 |

开发

cd pi-planning-with-files-zh

# 安装依赖
npm install

# 同步最新 skills（自动移除 hooks）
npm run sync-skills

# 构建
npm run build

# 测试 Pi 事件闭环
npm test

自动移除 Hooks

npm run sync-skills 命令会：

1. 从远程仓库克隆最新代码
2. 自动移除 Claude Code hooks（Pi 扩展使用自己的事件系统）
3. 指定中文版路径 skills/planning-with-files-zh
4. 添加 Pi 兼容性注释

这样即使源仓库更新，也不会重新添加 hooks。

许可证

MIT