pi-dev-kit1.1.3

Pi Dev Kit

English | 简体中文

让 Pi Coding Agent 从理解项目、澄清需求到规划和实施，形成可审阅、可接续的开发流程。

Pi Dev Kit 将项目导航、持久化计划、交互式问答和权限控制组合在一起：先按需理解源码，再把改动方案写成 Plan，审阅后授权执行。日常命令可自动运行，需要更大权限时再确认，而不是每一步都打断你。

特色功能

功能	能做什么	使用价值
源码驱动的项目导航	/init 引导 agent 根据源码、配置解析和测试生成 .ai/map.md 与业务流程图；后续项目级任务引导按需读取相关文档并核验源码	建立可复用的项目上下文，不要求每次把全部文档塞入上下文
可落盘、可审阅的 Plan	开启 Plan 后只允许探索、澄清和写当前计划；/run-plan 将用户授权记录写回文件，再启动实施	将目标、范围、方案和验收标准留在项目中，便于审阅及跨会话接续
交互式需求澄清	agent 通过 questionnaire 提出问题；支持多题选择、自由填写、回看修改和汇总提交	把关键分歧先问清楚，减少基于猜测实施
少打扰的权限控制	Default 放行白名单只读 Bash；Auto 自动运行沙箱内的普通命令和符合边界的文件写入	普通探索和开发无需反复确认，越界或提权时再审批
Git 元数据保护	Auto Bash 将当前仓库的 Git 元数据与 .git 入口只读挂载，包括 worktree 的独立和共享元数据	查看状态和差异不必审批，写 Git 元数据则需要显式提权
三个模块按需组合	Workflow、Permissions、Questionnaire 可分别启用；Plan 开关与权限档位互不改变	根据任务选择工作方式，不强制整套使用

安装与快速开始

需要已安装 Pi、Node.js 22.19+。当前验证的 Pi 版本为 0.84.4。

pi install npm:pi-dev-kit

也可以从 GitHub 安装，二选一即可：

pi install git:github.com/Lytherion/pi-dev-kit

默认启用全部三个模块。新会话默认 Plan 关闭、权限 Auto；已有会话按当前分支恢复状态。

Auto Bash 沙箱仅支持 Linux/WSL，需要 Git 2.31+、Bash、bubblewrap 和可用的 user namespaces。Debian/Ubuntu 可安装：

sudo apt-get install git bash bubblewrap

依赖缺失或 namespace 不可用时，Auto Bash 会失败，不会自动降级到无沙箱执行。macOS、原生 Windows 不支持本包的 Auto Bash 沙箱，可按需只启用 Workflow/Questionnaire，或选择本地无沙箱的 Default/YOLO；这些平台尚未完成运行验证。

安装后，在项目目录启动 pi。以下 /init、/plan 等命令均在 Pi 会话中输入，不是终端 Shell 命令。

推荐使用流程

理解项目 → 澄清需求 → 写 Plan → 审阅并授权 → 实施与验收 → 维护项目知识
 /init                 /plan on   /run-plan

1. 先建立项目导航。 对已有项目，在项目根目录运行 /init。agent 会基于当前源码生成或同步项目地图和流程图；期间只开放读取、受限项目文档和同包问答工具，不修改业务代码、配置或 Plan，也不运行 Bash。完成后审阅覆盖范围、关键分支和未核验项，不能把生成文档视为已经验证的业务事实。

.ai/
├── map.md                 # 项目概览、入口和相关流程导航
├── flows/                 # 可追溯到源码的业务流程图
└── plan/                  # 具体任务的方案、授权与进度记录

2. 先澄清需求，按需保存计划。 运行 /plan 或 /plan on，直接进入只读规划，不需要选择或创建文件。随后输入任务，例如：

分析当前登录过期处理，先不要实施。

请核验相关源码和调用方，必要时用 questionnaire 向我澄清需求。
先在对话中展示目标、当前行为、拟改规则、影响范围、实施步骤和验收样例，暂不保存文档。

明确要求保存方案后，agent 才调用 plan_document。尚未绑定文档且已有 Plan 时，先选择“修改已有 Plan / 新建 Plan”；修改时上下选择文档，agent 先读取并合并现有内容再保存。没有文件时直接新建：agent 提供几个中文／英文语义名，也可选择“自定义名称”输入语义名，工具自动生成 YYYYMMDD-NN-语义名.md（当天日期、递增序号）。取消不会写入或改变绑定。首次保存成功后绑定当前文档，后续保存直接更新它，无需重复选择。

Plan 期间，agent 可使用内建读取工具、白名单只读 Bash、问答和仅写当前文件的 plan_document；不能修改业务代码或配置。问答回答和保存方案均不构成实施授权。

3. 审阅后再启动实施。 核对 Plan 是否回答了“为什么改、改哪里、哪些行为不能变、如何验收”。确认后运行 /run-plan，每次都展示 Plan 列表，当前绑定文件优先置于首项，否则默认第一项；上下切换，回车选中即授权执行，不再二次确认。插件按当前内容实施：插件先记录授权，再关闭 Plan 限制并启动任务；权限档位保持不变，Default 的后续受控写入仍需要确认。取消选择不会修改文件或开关。

建议要求 agent 逐项记录进度与验证证据；发现范围扩大、业务契约冲突或信息不足时暂停询问。新会话可通过项目地图与同一份已授权 Plan 接续任务，而不是依赖旧聊天记忆。

4. 验收并维护知识。 按改动风险检查测试、diff、受影响的共享调用方和实际业务结果。让 agent 更新受影响的 map/flow，或运行 /init 同步，再人工审阅；不要为无关的小修改反复全量生成文档。进度、验收和文档语义依赖 agent 与你的核验，不由命令自动保证，也不会自动提交、推送或回滚 Git。

小任务不必强制建 Plan：可以在只读规划模式中交流方案而不保存文件，之后关闭 Plan，明确确认后实施。全新项目先澄清目标并实现可核验的源码，再用 /init 建立导航；空项目不能凭空还原业务流程。

命令与权限速查

命令 / 快捷键	作用
/init	关闭 Plan，临时限定工具维护 .ai/map.md 和 .ai/flows/*.md；结束恢复普通工具，不自动重启 Plan
/plan on / /plan off	开启规划限制 / 关闭限制并恢复原工具集，不改变权限档位
/plan / Alt+N	切换 Plan 开关，不选择或创建文件；忙碌或 /init 期间不可切换
/plan select	选择已有或新建 Plan 并绑定，不改变模式；新文档首次保存才创建
/plan clear	清除当前绑定，不删除文件、不改变模式
/run-plan	始终展示列表，当前绑定优先；回车选中即记录授权并启动实施，不改变权限档位
/permission default|auto|yolo	选择权限档位；不带参数打开选择菜单
Alt+M	循环切换 Default → Auto → YOLO
questionnaire	agent 调用的问答工具，不是用户输入的斜杠命令；取消或非 TUI 视为未回答

Plan 是工具限制，不是独立执行模式。 开启时状态栏显示 Plan · 文件名（未绑定时仅显示 Plan）；关闭后保留绑定并显示 当前计划 · 文件名。已有会话恢复绑定，新会话清空绑定。关闭只是恢复普通工具，绑定、切换和保存均不代表任务获得授权。插件没有强制所有普通任务先经过 /run-plan 的执行锁；YOLO 也不能绕过 Plan 的工具限制。

权限档位	受控文件写入 / 文档删除	Bash
Default	逐次确认	白名单只读命令免审批；其余逐次确认。执行时无沙箱
Auto（默认）	项目及系统临时目录中的普通目标自动允许；Git 保护路径、已有硬链接或其他路径需确认	普通命令自动走沙箱；项目与系统临时目录可写，其他位置及当前 Git 元数据只读
YOLO	本包不加权限提示	本包不加权限提示或沙箱；仍受 Plan 与 /init 限制

bash 工具只接受 command 和可选 timeout；Auto 下始终在沙箱内运行，不弹审批。确需写受保护 Git 元数据或可写范围外路径时，使用独立的 bash_escalated 工具，提供 command、可选 timeout、必填的受限路径 path 和必要写入操作说明 reason。Default/Auto 每次确认，YOLO 不审批；Plan 和 /init 禁止该工具。只读查询、网络、Python/uv、测试和复杂 Shell 本身不是提权理由。批准解除该次调用的整个沙箱，不是只开放声明的路径。 路径只用于解释申请，不约束命令的真实行为。需要审批时，没有交互界面、拒绝或取消都不会执行。bash 的旧提权参数不再支持。

Default 和 Plan 共享保守的只读 Bash 白名单，典型支持：

pwd
ls -alh src
git status --short --branch
git log --oneline -n 10
git diff --stat
git diff --cached --name-only

这不是任意只读命令识别器：仅支持单条命令、简单 ASCII 参数和明确允许的选项。引号、非 ASCII 参数、通配符、替换、重定向、管道、连接符、脚本、多行和未知参数，Default 询问、Plan 拒绝；复杂路径读取可改用内建 read/grep/find/ls。完整规则见 extensions/lib/read-only.ts。

Default 免审批或 Plan 允许的 Git 查看会禁用分页、可选索引写入、fsmonitor，log/diff 另禁用 external diff 和 textconv。普通状态下 Auto/YOLO 不因白名单而改写命令。

按需启用与旧包迁移

运行 pi config，在本包下选择需要的扩展：

模块	入口	负责范围
Workflow	extensions/workflow.ts	Plan、项目导航、文档工具及任务入口
Permissions	extensions/permissions.ts	三档权限、受控写入审批与 Bash 沙箱
Questionnaire	extensions/questionnaire.ts	交互式多题问答

模块可独立运行。未启用 Permissions 时，Workflow 的受限文档写入不经过本包权限确认，但路径与工具限制仍生效。Plan 只接受内建或同包 Permissions 的 Bash，以及同包 Questionnaire；未经核验的第三方同名工具不会进入受信工具集。

本项目承接 pi-simple-permissions 的后续开发。旧包不会因新包安装而自动移除；先用 pi list 确认来源，避免同时加载两份扩展。旧包来自 npm 时：

pi remove npm:pi-simple-permissions
pi install npm:pi-dev-kit

Git 或本地路径安装按列表中的实际来源移除；项目级安装使用 --local。迁移后检查模块配置与权限档位，按需开启 Plan。

安全与限制

• Git 保护不是所有 Git 命令的禁令。 Auto 保护调用开始时当前仓库的元数据；仅改工作区的操作、临时目录中的其他仓库或命令中新建的仓库不在同一保护范围内。
• 检查失败不等于批准。 Auto 文件目标按符号链接真实路径判断，能解析但越界时询问；断开链接、损坏 Git 元数据或保护路径发现失败，使依赖该检查的当前调用报错，不自动询问或降级，也不自动终止整个 agent 会话。符号链接形式的 .git 入口不支持 Auto，Bash 需显式申请提权。
• 不是恶意程序安全沙箱。 白名单依赖可信的宿主 Bash、PATH 和标准程序，不防恶意启动脚本、Shell 函数或被替换程序。沙箱不隔离读取，网络仍开放；Bash 硬链接、并发路径替换、本地服务及其他扩展/工具不提供完整对抗性保护。用户直接运行的终端命令不受本包工具限制。只加载可信扩展，批准提权前审阅完整命令。

本项目使用 MIT 许可证。