{"_id":"@adamcjm/pi-plan-mode","_rev":"2-2c6cf352c40378331173c8c0efc1e1c4","name":"@adamcjm/pi-plan-mode","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@adamcjm/pi-plan-mode","version":"1.0.0","keywords":["pi-package","pi","plan-mode","read-only","planning","todo"],"license":"MIT","_id":"@adamcjm/pi-plan-mode@1.0.0","maintainers":[{"name":"adamcjm","email":"adamcjm@163.com"}],"homepage":"https://github.com/adamcjm/pi-plan-mode#readme","bugs":{"url":"https://github.com/adamcjm/pi-plan-mode/issues"},"pi":{"extensions":["./extensions/plan-mode"]},"dist":{"shasum":"adbf931d2505666837d651d2eea0f4d3cfad8aa5","tarball":"https://registry.npmjs.org/@adamcjm/pi-plan-mode/-/pi-plan-mode-1.0.0.tgz","fileCount":7,"integrity":"sha512-bCR88ggTzBA2qnrxI44OrclIPrifzbjS4FGVQrgrfXgVB7pqusSRrcjEyGGsHs3yX+c3fZnaic6zLQf3v2H7Cg==","signatures":[{"sig":"MEUCIBdnh8HKQH48gHtuUwiPa9YE2WDtlu5R7i6Yzw4bWHoTAiEAqSxYCWpy9e8nndPL3jYDr41mF4vJgx5bqbY0fvGASgU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37410},"gitHead":"79a0e5b635702f4f564db074154eecfe0ca7a707","_npmUser":{"name":"adamcjm","email":"adamcjm@163.com"},"repository":{"url":"git+https://github.com/adamcjm/pi-plan-mode.git","type":"git"},"_npmVersion":"10.9.4","description":"Plan mode for pi: enforced read-only exploration (no write/modify/delete), plan extraction from Plan: output, and [DONE:n] execution tracking","directories":{},"_nodeVersion":"22.21.0","_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-plan-mode_1.0.0_1786701309389_0.27566220854559353","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@adamcjm/pi-plan-mode","version":"1.0.1","description":"Plan mode for pi: enforced read-only exploration (no write/modify/delete), plan extraction from Plan: output, and [DONE:n] execution tracking","keywords":["pi-package","pi","plan-mode","read-only","planning","todo"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/adamcjm/pi-plan-mode.git"},"pi":{"extensions":["./extensions/plan-mode"]},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*"},"_id":"@adamcjm/pi-plan-mode@1.0.1","gitHead":"f66402fd3e437c210edc05e8ce79a49f689bb42f","bugs":{"url":"https://github.com/adamcjm/pi-plan-mode/issues"},"homepage":"https://github.com/adamcjm/pi-plan-mode#readme","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-/Qrk97qnAI/VQ9nrhxH46JkxvKJgDHXr1TJMnmMo+Tx21lbWvyumR+NrdsWz+a2F8jTQYJf2sT32+/0PRKjtRw==","shasum":"f467fbf8e197f700f5fa6205eb70d8226d339fc6","tarball":"https://registry.npmjs.org/@adamcjm/pi-plan-mode/-/pi-plan-mode-1.0.1.tgz","fileCount":7,"unpackedSize":37232,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIESKPPsmILcCcsymnFAnI4Twff3qATlDtzaruXm1paXjAiBSvGhd1zvb4o0/vjaFUc3LnZOH3lEGdFtalhYgfQIbYQ=="}]},"_npmUser":{"name":"adamcjm","email":"adamcjm@163.com"},"directories":{},"maintainers":[{"name":"adamcjm","email":"adamcjm@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-plan-mode_1.0.1_1786701360573_0.2124231322940171"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T09:55:09.238Z","modified":"2026-08-14T09:56:00.923Z","1.0.0":"2026-08-14T09:55:09.544Z","1.0.1":"2026-08-14T09:56:00.741Z"},"bugs":{"url":"https://github.com/adamcjm/pi-plan-mode/issues"},"license":"MIT","homepage":"https://github.com/adamcjm/pi-plan-mode#readme","keywords":["pi-package","pi","plan-mode","read-only","planning","todo"],"repository":{"type":"git","url":"git+https://github.com/adamcjm/pi-plan-mode.git"},"description":"Plan mode for pi: enforced read-only exploration (no write/modify/delete), plan extraction from Plan: output, and [DONE:n] execution tracking","maintainers":[{"name":"adamcjm","email":"adamcjm@163.com"}],"readme":"# pi-plan-mode\n\n[pi](https://github.com/earendil-works/pi) 的计划模式扩展：**强制只读探索模式** + 计划提取 + 执行进度跟踪。\n\n开启计划模式后安全地探索代码库，让模型输出编号计划，然后一键执行——模型每完成一步标记 `[DONE:n]`，侧边 widget 实时显示进度。\n\n[English](README.md)\n\n## 特性\n\n- **硬性只读保证**——三层独立防线：\n  1. **工具层**：从活动工具集中移除 `edit`/`write`/`computer_use*`\n  2. **命令层**：每条 `bash` 命令必须通过严格白名单（安全命令且不含破坏性模式）\n  3. **提示层**：明确告知模型处于只读模式\n- **bash 白名单**：只允许单个只读命令——禁止重定向、管道、命令链接、命令替换、多行脚本；`curl` 仅限 GET 查询\n- **计划提取**：从 `Plan:` 段落提取编号步骤\n- **执行跟踪**：`[DONE:n]` 标记 + 实时进度 widget（☑/☐）\n- **会话持久化**：状态跨会话恢复，恢复后重扫 `[DONE:n]`\n- **子代理支持**：计划模式下 `subagent` 保持可用，子 pi 进程继承同样的只读限制（需要带计划模式传播的 subagent 扩展，见下文）\n- **CLI 参数**：`pi --plan` 直接以计划模式启动\n\n## 安装\n\n```bash\npi install npm:@adamcjm/pi-plan-mode\n```\n\n或仅本次运行：\n\n```bash\npi -e npm:@adamcjm/pi-plan-mode\n```\n\n> **安全提示：** 扩展以完整系统权限执行任意代码，安装前请审查源码。\n\n## 使用\n\n```\n1. 开启计划模式：/plan   （或 Ctrl+Alt+P，或启动时加 --plan）\n2. 让模型分析代码并生成计划\n3. 模型在 \"Plan:\" 标题下输出编号计划：\n\n   Plan:\n   1. 第一步做什么\n   2. 第二步做什么\n   3. 第三步做什么\n\n4. 弹窗选择\"执行计划\"（也可先\"完善计划\"）\n5. 执行中模型每完成一步标记 [DONE:n]\n6. 进度 widget 显示 ☑/☐ 完成状态\n```\n\n### 命令\n\n| 命令 | 说明 |\n|------|------|\n| `/plan` | 切换计划模式 |\n| `/todos` | 显示当前计划步骤与进度 |\n| `Ctrl+Alt+P` | 切换计划模式 |\n\n### 状态机\n\n```\nIDLE ──/plan──▶ PLAN（只读探索）\nPLAN ──\"执行计划\"──▶ EXECUTE（完整工具 + [DONE:n] 跟踪）\nEXECUTE ──全部完成──▶ IDLE（完成消息）\nPLAN ──\"完善计划\"──▶ 回到 PLAN（编辑器输入反馈）\n```\n\n## 只读保证\n\n纵深防御，计划模式无法写入、修改或删除文件：\n\n1. **工具列表**：`edit`、`write`、`computer_use*` 从活动工具中移除。进入前的工具集快照保存，退出时原样恢复（自定义工具不受影响）。\n2. **bash 过滤**：每条命令必须同时满足：在白名单中、不含破坏性模式。\n3. **提示词**：模型收到明确的只读指令。\n\n### bash 白名单（放行）\n\n| 类别 | 命令 |\n|------|------|\n| 文件查看 | `cat`、`head`、`tail`、`less`、`more`、`strings`、`xxd`、`hexdump`、`md5`、`shasum` |\n| 搜索 | `grep`、`find`、`rg`、`fd` |\n| 目录 | `ls`、`pwd`、`tree`、`du`、`df` |\n| git 只读 | `status`、`log`、`diff`、`show`、`blame`、`grep`、`rev-parse`、`describe`、`remote -v`、`config --get` |\n| 包信息 | `npm list/view/audit`、`pip list/show`、`pnpm outdated`、`brew info` |\n| 版本检查 | `node --version`、`python3 --version`、`go version`、`java -version`、`rustc --version` |\n| 系统信息 | `uname`、`whoami`、`date`、`ps`、`uptime` |\n| 网络 | `curl` 仅 GET 查询、`wget -O -`（仅输出到 stdout） |\n\n### 拦截（写 / 改 / 删 / 执行）\n\n- **文件操作**：`rm`、`rmdir`、`mv`、`cp`、`mkdir`、`touch`、`unlink`、`ln`、`chmod`、`chown`、`chflags`、`truncate`、`tee`、`dd`、`shred`、`install`、`mkfifo`、重定向 `>` `>>`\n- **git 写操作**：`commit`、`push`、`add`、`fetch`、`merge`、`reset`、`checkout`、`stash`、`remote add/set-url`、`clean`、`worktree add`（含 `git -C dir ...` 变体）\n- **包安装**：`npm install`、`npm audit fix`、`yarn add`、`pip install`、`brew install`\n- **curl 写标志**：`-o`、`-O`、`-d`、`-T`、`-F`、`-X POST/PUT/PATCH/DELETE`、`--output`、`--data*`、`--cookie-jar`\n- **执行**：shell（`sh`、`bash`、`zsh`…）、`python -c`、`node -e`、`osascript`、`eval`、`source`、`find -exec/-delete`\n- **命令链接**：`;` `&&` `||` `|` `&`、反引号、`$(...)`、多行命令\n- **系统**：`sudo`、`doas`、`kill`、`reboot`、`systemctl restart`\n- **编辑器/应用**：`vim`、`nano`、`nvim`、`code`、`open`\n\n## 子代理集成\n\n计划模式下 `subagent` 保持可用。subagent 扩展检测计划模式（持久化的会话状态），spawn 子 pi 进程时附加 `--plan`；子进程在同样的只读限制下运行（写工具被剥离、bash 被过滤）。嵌套子代理通过 `PI_SUBAGENT` 环境变量逐层传播。\n\n这需要带计划模式传播逻辑的 subagent 扩展：\n\n```ts\n// subagent 工具的 execute() 中：\nconst planModeActive = /* 从会话条目或 PI_SUBAGENT 环境变量读取 */;\nif (planModeActive) args.push(\"--plan\"); // 子 pi 进程\n```\n\n## 开发\n\n```bash\ngit clone git@github.com:adamcjm/pi-plan-mode.git\ncd pi-plan-mode\nbun extensions/plan-mode/test_utils.ts   # 153 个过滤断言\n```\n\n命令过滤器位于 `extensions/plan-mode/utils.ts`（纯函数）；修改白名单/黑名单时同步扩展 `test_utils.ts`。\n\n## License\n\nMIT\n","readmeFilename":"README.zh-CN.md"}