@chengzhiyi/pi-plan-mode

Pi 只读计划模式，通过 pi-webapp 协议提供计划审批、交互式提问和文档预览。

使用

• /plan 或输入框菜单中的“计划模式”：进入模式。
• /plan <任务>：进入模式并发送任务；/plan on、/plan off 显式切换。
• 开启后输入区显示“计划”徽章，悬停显示关闭图标。
• 首次请求也必须走到计划审批或交互式澄清。先询问会改变交付内容的关键选择，再根据回答制定计划：未明确的示例技术栈、部署方向和时间约束不能用推荐默认值替用户决定。通常集中问 1～3 个问题，明确要求的内容直接保留，不重复问是否需要。关键选择已给出、或用户明确授权采用默认值时直接提交。普通文字提问不能替代交互。模型未提交计划时在同一请求内最多续跑两次，仍未提交则明确提示，保持只读；网络失败和中断不触发续跑。
• 选择式澄清：代理用 ask_user 提交 1～5 个问题，每题 2～5 个选项，可标记推荐项。支持上一题、下一题、键盘选择及 1～4000 字符的自定义回答；最终提交才发送整组回答。回答记录留在会话中，代理在同一请求内继续生成或修订计划。取消提问会中止请求并保持计划模式。
• 代理调用 submit_plan 后停在等待审批的工具调用中：自动打开计划全文，审批卡接管输入区。
• 提交修改意见：输入 1～4000 字符的意见，在本次请求内自动生成修订版，再次等待审批；修订期间保持只读。旧的无反馈讨论响应仍会暂停等待下一条消息。
• 取消计划：记录独立的取消决定，中止请求，保持计划模式。
• 同意执行：仅为获批版本授予本次请求的临时执行权限，徽章显示“执行已批准计划”。可随时停止；请求结束、失败或中断后恢复只读计划模式。自动重试期间保留授权，在 agent_settled 撤销。
• 审批期间普通输入框保持挂载但隐藏、禁用；审批结束后恢复草稿、附件和编辑状态。切换会话仍清理草稿及附件。
• 计划卡片和全文显示版本、审批、替代与执行状态。“执行回合结束”不表示交付验收通过。历史卡片只打开全文，审批操作只属于当前待审批请求。

Web 预览支持多标签、分栏、浮动、全屏、收起；文档由宿主渲染，支持代码复制、换行、语法高亮、表格及数学公式。窄屏使用全屏预览，收起后可操作审批卡。

状态、计划文档和审批决定写入 Pi 会话自定义记录。页面刷新会恢复仍在等待的审批；进程重启会恢复模式和历史文档，但不会把已经中断的工具调用伪装为仍在等待审批。空闲时可点击未获批、中断计划的“重新提交审批”，生成新的真实 submit_plan 和审批请求。已批准后停止、失败或重启中断的最新版本提供“重新审批并继续”：先只读检查已有进度，再提交同一计划的新版本，重新批准后仅继续未完成步骤。已结束、已取消、已替代的历史版本不提供继续入口，旧授权不会恢复。

计划记录使用 schemaVersion: 2、planId、revision 和 callId。反馈修订沿用 planId 并增加版本，新任务生成新计划。旧记录按 callId 映射为第一版并读取已有决定。临时授权只存在内存中，会话、分支切换、卸载或重启均清除；通用 Web 协议仍为 v1。

计划模式下只允许 read、grep、find、ls、submit_plan 和只读交互工具 ask_user。未知工具、写入工具与 shell 都被工具调用边界阻止；用户主动修改宿主设置不受这个约束。Web 不可用时，Pi TUI 用原生选择框审批和回答问题；无 UI 的打印会话保存文档或问题后停止等待后续指令。刷新恢复仍有效的提问；浏览器存储可用时，按会话和请求恢复未提交的选项、自定义回答与当前题目，普通输入框草稿的保留仅限本次页面挂载。

代码结构

• src/extension.ts：计划模式、只读工具约束与审批执行流程。
• src/state.ts、src/questions.ts、src/question-drafts.ts：会话记录、问题校验与草稿恢复。
• src/client.tsx：浏览器插件声明与宿主交互。
• src/ui/：计划徽章、文档卡片、预览、审批与提问组件。
• src/ui/primitives/：按钮、状态点、文档图标与 Markdown 摘要。

React、文档渲染与主题令牌由宿主提供，布局使用宿主的 --piw-* 变量。许可声明随包包含在 LICENSE 中。 部分 UI 原语与 Markdown 处理代码源自 MIT 许可的 DeepSeek Harness，对应版权声明保留在 LICENSE 中。