@zhushanwen/pi-plan 0.5.2 → 1.1.0

package/src/index.ts

@@ -1,138 +1,150 @@
 import type {
-  BeforeAgentStartEvent,
-  BeforeAgentStartEventResult,
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
 import { registerPlanCommand } from "./command.js";
-import { registerPlanEventHandlers } from "./compact.js";
 import {
-  type PlanAbortControllers,
-  type PlanSessionMap,
   PLAN_CONTEXT_CUSTOM_TYPE,
   PLAN_MODE_TOOLS,
+  applyPlanEvent,
+  createPlanCtx,
+  isTaijiGuiHost,
   persistPlanState,
   reconstructPlanState,
 } from "./state.js";
 import { registerPlanTool } from "./tool.js";
 import { updatePlanWidget } from "./widget.js";
 
-const logger = getLogger("pi-plan");
-
-/**
- * D9 引导文案（约 60 token）：仅在 taiji 宿主注入。plan 模式是只读子集（读代码、产
- * 文档、不改源码），进入它不是危险操作——agent 可在合适时机**自行进入**（plan-mode-
- * agent-enter U1 后 enter 是 tool action，无需用户确认；用户随时可经 PlanModeBar 退出）。
- */
-const PLAN_MODE_SUGGESTION_PROMPT =
-  "\n\n" +
-  "When the user's request involves large-scale refactoring, cross-module changes, or other high-risk modifications, " +
-  "proactively enter plan mode yourself by calling plan(action='enter', requirement='<the task>', skills=[...relevant skills]). " +
-  "Plan mode is read-only for source code: you explore and write plan documents, then the user reviews before implementation. " +
-  "Do not ask for permission to enter — entering plan mode is safe and reversible (the user can exit anytime).";
-
 export default function planExtension(pi: ExtensionAPI) {
-  // Per-session state cache — keyed by sessionId
-  const sessions: PlanSessionMap = new Map();
-  // 挂起 select 的 per-session AbortController（E10：submit-review 审批 + complete
-  // 执行方式选择两处共用注册表；发挂起 select 前 fresh，settled/重建/关闭即弃）
-  const abortControllers: PlanAbortControllers = new Map();
+  // 单 ctx 对象（D-B4-3）：states（per-session 生命周期态缓存）+ controllers（挂起
+  // select 注册表——E10：submit-review 审批 + complete 执行方式选择两处共用；值 =
+  // PendingSelect 含解散来源槽位，D-B1-2；发挂起 select 前 fresh，settled/重建/关闭
+  // 即弃）两表收敛 + dissolveAll 解散方法（exitPlanMode 入口经它打 'self' 标）
+  const planCtx = createPlanCtx();
 
   // Register tool and command
-  registerPlanTool(pi, sessions, abortControllers);
-  registerPlanCommand(pi, sessions, abortControllers);
-
-  // Register compact/tree event handlers
-  registerPlanEventHandlers(pi, sessions);
+  registerPlanTool(pi, planCtx);
+  registerPlanCommand(pi, planCtx);
 
   // Reconstruct state on session start
   pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
     const sessionId = ctx.sessionManager.getSessionId();
     const state = reconstructPlanState(ctx);
-    sessions.set(sessionId, state);
+    planCtx.states.set(sessionId, state);
     // session 重建即弃旧 controller：挂起 select 只存在于 tool execute 进行中的
     // turn，pi 重生后不可能有存活的 select；残留的已 abort controller 禁止复用
     // （发起新挂起 select 会 fresh 新建，此处删除是防御性清理）
-    abortControllers.delete(sessionId);
+    planCtx.controllers.delete(sessionId);
     updatePlanWidget(ctx, state);
     // If plan mode was active, re-restrict tools to the plan-mode set (includes bash — file-write constraints come from the injected plan mode prompt)
     if (state.isActive) {
       pi.setActiveTools(PLAN_MODE_TOOLS);
 
-      // E3：挂起交互点（审批 select / 执行方式 form）随 pi 进程消亡。本 hook 跑在
-      // pi 懒重生之后（taiji 冷启动不拉 pi 进程——用户重开 session 发首条消息时 pi
-      // 才重生、hook 才跑），此时冷启动扫描已恢复持久态但挂起交互不复存在（上方
-      // delete 已清残留 controller，pi 重生后不可能有存活的挂起）→ 按 reviewState
-      // 三态 steer 恢复（恢复动作全部在 extension 侧，前端不造失败信号链）：
-      // - awaiting：重调 submit-review 重挂审批；
+      // E3 按 state 查表恢复（D5/D9④）：挂起交互点（审批 select / 执行方式 form）随 pi
+      // 进程消亡。本 hook 跑在 pi 懒重生之后（taiji 冷启动不拉 pi 进程——用户重开 session
+      // 发首条消息时 pi 才重生、hook 才跑），此时冷启动扫描已恢复持久态但挂起交互不复存在
+      //（上方 delete 已清残留 controller，pi 重生后不可能有存活的挂起）→ 按 state 查表
+      // steer 恢复（恢复动作全部在 extension 侧，前端不造失败信号链；旧 entry 无 state 字段
+      // 经 reconstructPlanState 的 reviewState 映射后同样落本表，D2 读方①）：
+      // - reviewing：按宿主分流（F-W3-1，见分支内注释）；
       // - revising：继续按评论修订并重新提交（P1-1：原实现只覆盖 awaiting，revising
-      //   崩溃后审批条恒显假「修订中」且无任何恢复指引）。
-      // 不覆盖「approve 后执行方式选择窗口中断」：该态（isActive + docs>0 + 无
-      // reviewState）与「探索期 pi 重生」在持久态上不可区分，steer「计划已批准」会
-      // 对正常探索期误报——防误报优先，该窗口中断由用户重发消息自然恢复。
-      if (state.reviewState === "awaiting" || state.reviewState === "revising") {
-        const revising = state.reviewState === "revising";
+      //   崩溃后审批条恒显假「修订中」且无任何恢复指引）；
+      // - dispatching（D5 E3 新支，覆盖现状自认的不可恢复窗口）：崩溃消散的表单即
+      //   「无选择解散」极端形态——先走 review_aborted 边落 approved（批准事实保留，
+      //   且使重调 complete 的 approve 边合法），再 steer 重调 complete 重新选执行方式。
+      //   其余态（planning/approved/终态）不打扰（S16「重开 session 无 E3 重挂打扰」）。
+      if (state.state === "reviewing") {
+        // F-W3-1 审批条复活拦截（S8①/S2「stop 后不复活」+ D8/S6 恢复语义）：taiji GUI
+        // 宿主下 E3 **不自动 steer 重挂**——steer triggerTurn 是无人值守自动重提通道
+        // （pi 进程重启 → agent 自动 submit-review → 新 select 挂起 → 审批条复活，
+        // 用户停止/搁置的审批在无任何用户输入介入时自己回来）。宿主形态只落
+        // resumeHint='resubmit'：renderer degraded 分支（state=reviewing ∧ 无挂起，
+        // PlanReviewBar）据此呈现「审批提问已随会话重启失效 + 重新提交审批」按钮，
+        // 用户点击（= 用户输入介入）才重提——agent 侧 submit-review 对 reviewing 降级
+        // 态的自环重挂照常放行，恢复触发权归用户。独立 pi（TUI）没有 degraded 按钮，
+        // 自动重挂是唯一恢复路径（F8 死路防护），steer 保留。
+        // 分流判定与 executeSubmitReview 的 E8 宿主分流同源（isTaijiGuiHost，D-B1-7）。
+        if (!isTaijiGuiHost(ctx)) {
+          // D9④：E3 重挂是唯一「不重新思考」场景——steer 原样回传上轮 selfReview 全文，
+          // 豁免只发生在「自审内容」（复用既有结论），不存在绕过「过门义务」的路径
+          const carried =
+            state.selfReview ?? "(none recorded — write a brief self-review before re-submitting)";
+          pi.sendMessage(
+            {
+              customType: PLAN_CONTEXT_CUSTOM_TYPE,
+              content:
+                "[PLAN MODE] A previous review request was interrupted (session restarted). " +
+                "The registered documents are still waiting for user approval. " +
+                "The self-review for this exact document set is already done — carry it back VERBATIM as the selfReview parameter, no need to redo the thinking:\n\n" +
+                `<self-review>\n${carried}\n</self-review>\n\n` +
+                "Call plan(action='submit-review', selfReview='<the text above>') now to re-hang the review dialog.",
+              display: false,
+            },
+            { deliverAs: "steer", triggerTurn: true },
+          );
+        }
+        // E3 重挂即落 'resubmit' resumeHint + persist（此处原只发 steer 不落盘，renderer
+        // 冷启动扫描的 View 恒无 hint、恒渲染通用文案；落盘后才能渲染「会话已重启，
+        // 尚未重新提交」分支）。无条件覆盖既有 hint 为有意——「会话已重启」语义
+        // 优先成立（P3-9 登记）；清除 = submit-review 重挂起点（clearRoundFields 单函数
+        // 出口，D4）。宿主形态该 hint 即 degraded 分源文案的判定源（无 steer，按钮文案依赖它）。
+        state.resumeHint = "resubmit";
+        persistPlanState(pi, state);
+      } else if (state.state === "revising") {
         pi.sendMessage(
           {
             customType: PLAN_CONTEXT_CUSTOM_TYPE,
-            content: revising
-              ? "[PLAN MODE] A revision round was interrupted (session restarted). The user's revision comments were already injected — continue handling them: rewrite the documents, re-register each revised document via plan(action='register-doc'), then re-submit via plan(action='submit-review')."
-              : "[PLAN MODE] A previous review request was interrupted (session restarted). " +
-                "The registered documents are still waiting for user approval. " +
-                "Call plan(action='submit-review') now to re-hang the review dialog.",
+            content:
+              "[PLAN MODE] A revision round was interrupted (session restarted). The user's revision comments were already injected — continue handling them: rewrite the documents, re-register each revised document via plan(action='register-doc'), then re-submit via plan(action='submit-review', selfReview='<a fresh self-review for the revised documents>').",
+            display: false,
+          },
+          { deliverAs: "steer", triggerTurn: true },
+        );
+        // revising 恢复不落 resumeHint（'resubmit' 只描述 reviewing 降级等待；revising 由
+        // steer triggerTurn 立即开轮接续，恢复期间显示的 revising 是真实进行中）
+      } else if (state.state === "dispatching") {
+        // review_aborted 边（D1：dispatching --review_aborted--> approved）+ steer 双动作：
+        // 转移/落盘先于 steer，恢复后持久态与指示一致；ok:false（坏数据格）不落盘照常 steer
+        const moved = applyPlanEvent(state, "review_aborted");
+        if (moved.ok) persistPlanState(pi, state);
+        pi.sendMessage(
+          {
+            customType: PLAN_CONTEXT_CUSTOM_TYPE,
+            content:
+              "[PLAN MODE] The plan was approved and the execution-method choice was interrupted (session restarted). " +
+              "The approval stands. Re-initiate the execution-method choice by calling plan(action='complete') now. " +
+              "Do not implement any changes before the user picks an execution method.",
             display: false,
           },
           { deliverAs: "steer", triggerTurn: true },
         );
-        if (!revising) {
-          // E3 重挂即落 'resubmit' 源标记 + persist（此处原只发 steer 不落盘，renderer
-          // 冷启动扫描的 View 恒无 source、恒渲染通用文案；落盘后才能渲染「会话已重启，
-          // 尚未重新提交」分支）。无条件覆盖既有 source 为有意——「会话已重启」语义
-          // 优先成立（P3-9 登记；旧 entry 存量的其他 source 值一并被覆盖归一）。
-          state.reviewStateSource = "resubmit";
-          persistPlanState(pi, state);
-        }
       }
     }
   });
 
-  // D9：AI 主动建议（轻量引导），仅 taiji 形态注入。
-  // 信号用 TAIJI_AGENT_EXT_LOG 而非 TAIJI_RUNTIME_TOKEN——后者在 SPAWN_ENV 出站
-  // deny list 被强制剥除（C-proc-09），pi 子进程 env 里恒不可见，照抄即引导
-  // 静默失效且诱导实施者动 deny list 造成安全回归；前者由 taiji runtime 对托管
-  // pi 恒注入（rpc-client buildPiOutboundEnv）。独立 pi（信号缺失）不注入——
-  // universal 包语义不变。
-  pi.on("before_agent_start", (event: BeforeAgentStartEvent): BeforeAgentStartEventResult | undefined => {
-    if (process.env.TAIJI_AGENT_EXT_LOG !== "1") return undefined;
-    // Never block the agent loop（system-prompt extension 同款先例）
-    try {
-      return { systemPrompt: event.systemPrompt + PLAN_MODE_SUGGESTION_PROMPT };
-    } catch (error) {
-      const msg = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-      // 注入失败只损失一句引导，不值得中断 agent loop——先走 extension-logger 落盘
-      // （~/.pi/agent/logs/ 文件通道，诊断可见）；logger 自身抛错才降级 stderr
-      // （system-prompt logHookFailure 同款形态：logger 首选、stderr 内层兜底）
-      try {
-        logger.warn("plan: before_agent_start injection failed", { error: msg });
-      } catch (nestedErr) {
-        try {
-          process.stderr.write(`[pi-plan] before_agent_start injection log also failed: ${String(nestedErr)}\n`);
-        } catch (finalErr) {
-          // 完全静默：两层兜底都失败时无处可写
-          void finalErr;
-        }
-      }
-      return undefined;
-    }
+  // U6b：树回退（撤回 __taiji_nav__ → navigateTree / 用户树跳转）后即时重建 plan
+  // 内存态，消除 getPlanState 缓存命中短路的 stale 窗口（运行中撤回后压缩摘要会按
+  // 陈旧 state 注入被撤 requirement）。
+  //
+  // 纯重建体（todo 的 session_tree handler 同款）——只做 reconstruct + 缓存同步 +
+  // widget 刷新。为什么绝不复刻 session_start 块的副作用（E3 steer 重挂 /
+  // setActiveTools / persistPlanState）：本事件由撤回编排触发，steer 会让撤回编排
+  // 自己注入消息（违背「被撤内容从未发生」语义），persist 会向回退后的新分支追加
+  // entry 污染文件尾。缓存同步（planCtx.states.set）保持「getPlanState 缓存命中 = 最新
+  // 重建态」——session_start 块的重建走同一 reconstructPlanState（已含活跃路径裁剪）。
+  pi.on("session_tree", async (_event: unknown, ctx: ExtensionContext) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const state = reconstructPlanState(ctx);
+    planCtx.states.set(sessionId, state);
+    updatePlanWidget(ctx, state);
   });
 
+
   // Clean up on session end
   pi.on("session_shutdown", async (_event: unknown, ctx: ExtensionContext) => {
     const sessionId = ctx.sessionManager.getSessionId();
-    sessions.delete(sessionId);
-    abortControllers.delete(sessionId);
+    planCtx.states.delete(sessionId);
+    planCtx.controllers.delete(sessionId);
   });
 }

package/src/prompts.ts

@@ -46,20 +46,47 @@ const PHASE_B_SECTION =
   `4. **Propose 2-3 approaches** with trade-offs + recommendation.\n` +
   `5. **Assumption audit**: Grep-verify interfaces/types exist. Mark [UNVERIFIED] what can't be verified.`;
 
+/**
+ * 执行方式选项集的技能档上限（SSOT）：PHASE_D 散文（本文件）与 buildExecOptions
+ * （tool.ts）共同消费——散文数量与实际截断同源，对齐测试锁定。
+ */
+export const MAX_SKILL_OPTIONS = 2;
+
 // Phase D 第 3 点的选项集描述必须与 buildExecOptions（tool.ts）产出的实际选项一致
-// （≤2 个 plan-exec skill 档 + Execute + Not now，label 与 i18n exec.* 词典同源）——
-// 选项集重排后此处描述漂移会诱导模型向用户预告不存在的执行方式。
+// （有 plan-exec 技能时 = ≤MAX_SKILL_OPTIONS 个技能档 + Execute + Not now，label 与
+// i18n exec.* 词典同源；无技能时不弹表单直通 execute，D7②）——描述漂移会诱导模型
+// 向用户预告不存在的执行方式。对齐测试（exec-options-alignment.test.ts）锁定散文锚点。
 const PHASE_D_SECTION =
   `## Phase D: Completion\n` +
   `1. Ask user to review the complete plan.\n` +
-  `2. Call plan tool (complete) with isolation method (compact/direct).\n` +
-  `3. After plan complete: the user picks an execution method in the completion dialog — up to 2 detected plan-exec skills (Execute via skill: <name>, when detected), Execute (goal tracking integrated when available), or Not now (stay in plan mode).`;
+  `2. Call plan tool (complete).\n` +
+  `3. After plan complete: when plan-exec skills are detected, the user picks an execution method in the completion dialog — up to ${MAX_SKILL_OPTIONS} detected plan-exec skills (Execute via skill: <name>), Execute (goal tracking integrated when available), or Not now (stay in plan mode). When NO plan-exec skill is detected, no dialog appears and the plan executes directly.`;
+
+/** 对齐测试消费（exec-options-alignment.test.ts）——PHASE_D 散文的机器防线锚点。 */
+export const PHASE_D_PROSE = PHASE_D_SECTION;
+
+/**
+ * Phase C.5 自审清单（D9②）：submit-review 前的自审引导——产物纪律段之后恒注入（全流程，
+ * 不随模板/技能流程分叉——自审硬门对每次 submit-review 生效，含修订后重挂）。
+ * 门语义三层边界：存在性 = 结构保证（tool 参数门）/ 防照抄 = 启发式（逐字节拒收）/
+ * 语义级新鲜度 = 本提示词纪律（机器不可判）。自审发现的问题先修文档再提交。
+ */
+const PHASE_C_5_SECTION =
+  `## Phase C.5: Self-Review Before Submission\n` +
+  `Before every plan(action='submit-review'), do a self-review and put the conclusions into the selfReview parameter:\n` +
+  `1. **Requirement coverage**: check each requirement item is covered by the documents, one by one.\n` +
+  `2. **Assumption audit**: clear or explicitly list every [UNVERIFIED] assumption.\n` +
+  `3. **Chapter completeness**: compare against the template's chapter structure — no unwritten chapters.\n` +
+  `4. **Acceptance realism**: verify the acceptance scenarios are truly executable.\n` +
+  `Fix any issues found DURING the self-review in the documents first (then re-register), then submit with the self-review conclusions.`;
 
 /**
- * /plan 命令的提示词四段注入（D2）：
+ * /plan 命令的提示词段注入（D2）：
  * ① 技能指令（仅挂载 --skills 时）——按技能 SKILL.md 流程产出计划文档；
- * ② 产物纪律（恒注入）——register-doc 登记 / 修订重调 version+1 / 全部完成调
- *    submit-review / submit-review 被消费后当轮回应完重挂直到确认；
+ * ② 产物纪律（恒注入）——register-doc 登记 / 修订重调 version+1 / 全部完成先自审再调
+ *    submit-review（必带 selfReview）/ submit-review 被消费后当轮回应完重挂直到确认 /
+ *    收到重挂请求直接 submit-review（D8 提示词纪律）；
+ * ②.5 Phase C.5 自审清单（恒注入，产物纪律段之后，D9②）；
  * ③ 只读纪律（恒注入，现状 pi-ext-021 提示词保持）；
  * ④ 模板流程（仅未指定 --skills 时）——<available-plans> 三源清单注入（内置 5
  *    + 用户级 + 项目级，模型自选模板，D8）；空发现不注入段（warn 另落）。
@@ -83,14 +110,16 @@ export function buildPlanModePrompt(input: PlanPromptInput): string {
     );
   }
 
-  // ② 产物纪律
+  // ② 产物纪律 + ②.5 Phase C.5 自审清单（D9②：产物纪律段之后恒注入）
   sections.push(
     `## Deliverable Discipline\n` +
     `- Write every deliverable document into the plan directory (.tmp/plans/<slug>/), then register it: plan(action='register-doc', fileName='design.md', sourceSkill='<skill name or omit>').\n` +
     `- After revising a document, REWRITE the file and re-register it with plan(action='register-doc', fileName=...) again — the version is bumped so the UI refreshes its content.\n` +
-    `- When ALL documents are done, call plan(action='submit-review') to request user review.\n` +
-    `- After submit-review is consumed (a revision request), finish responding for the current turn, then call plan(action='submit-review') again to re-hang the review — repeat until the user confirms execution.`,
+    `- When ALL documents are done, self-review first (Phase C.5), then call plan(action='submit-review', selfReview='<your self-review conclusions>') to request user review — selfReview is REQUIRED every time (including re-submissions after revisions).\n` +
+    `- After submit-review is consumed (a revision request), finish responding for the current turn, revise the documents, redo the self-review for the revised versions, then call plan(action='submit-review', selfReview='...') again to re-hang the review — repeat until the user confirms execution.\n` +
+    `- When the user asks to re-submit the plan review (e.g. a re-submit notice like "请重新提交计划审批"), call plan(action='submit-review', selfReview='...') IMMEDIATELY — carry back your previous self-review VERBATIM when the documents are unchanged.`,
   );
+  sections.push(PHASE_C_5_SECTION);
 
   // ③ 只读纪律（现状 pi-ext-021 提示词保持）
   sections.push(
@@ -134,8 +163,9 @@ export function buildPlanModePrompt(input: PlanPromptInput): string {
 }
 
 /**
- * revise decision 的评论清单注入文本（D5 decision 消费；explain 决策已删，
- * PlanReviewDecision 收敛为 'approve' | 'revise'，approve 走 complete 流程不经本函数）。
+ * revise decision 的评论清单注入文本（D5 decision 消费；explain 决策已删——PlanReviewDecision
+ * 现为三键值域 'approve' | 'revise' | 'dismiss'（D3 加员）：approve 走 complete 流程、
+ * dismiss 走搁置分支，均不经本函数）。
  * 评论语义：quote 是用户划选引文（agent 定位段落用），comment 是评语。
  */
 export function formatReviewComments(comments: PlanReviewComment[]): string {