@zhushanwen/pi-plan 0.4.9 → 0.5.0

package/src/prompts.ts

@@ -0,0 +1,151 @@
+import type { PlanReviewComment } from "@zhushanwen/extension-protocol";
+
+import { formatAvailablePlans, listTemplates } from "./templates.js";
+
+/**
+ * 提示词注入的技能引用：名字 + SKILL.md 路径。
+ * 路径来自 pi.getCommands() 的 source === "skill" 条目的 sourceInfo.path——
+ * 技能枚举与路径经 pi 取得（不自扫描 7 源目录，D2），AI 自行 read 技能文件。
+ */
+export interface SkillRef {
+  name: string;
+  skillPath: string;
+}
+
+/** --template 直传的模板材料（与 --skills 互斥，命令层校验通过并读好全文后传入） */
+export interface ProvidedTemplate {
+  /** 展开后模板文件绝对路径（声明行展示用） */
+  absPath: string;
+  /** 模板文件全文（内嵌注入——不赌模型自发 read，D5） */
+  content: string;
+}
+
+/** buildPlanModePrompt 的入参（requirement/planFilePath/projectRoot 来自命令解析，skills 来自 E1 校验后的解析结果） */
+export interface PlanPromptInput {
+  requirement: string;
+  planFilePath: string;
+  /**
+   * 项目级模板源锚点（设计 D2 锚定 = 命令层 ctx.cwd），注入段扫描
+   * <projectRoot>/.agents/plans。显式传入而非从 planFilePath 逆推层级——
+   * planFilePath = <ctx.cwd>/.tmp/plans/<slug>/plan.md（slug 目录嵌套），层级逆推
+   * 曾差层级致项目级源恒扫空（U1），且与
+   * select-template 侧（listTemplates({ projectRoot: ctx.cwd })）同锚点双轨同源。
+   */
+  projectRoot: string;
+  skills: SkillRef[];
+  /** --template 直传时给出（D5）：抑制 <available-plans> 清单段 + 提示词内嵌全文 */
+  template?: ProvidedTemplate;
+}
+
+/** Phase B/D 与模板来源无关，清单流程与直传流程共用 */
+const PHASE_B_SECTION =
+  `## Phase B: Brainstorming\n` +
+  `1. **Quick Overview**: ls project root, read README, package.json — build context (< 30s).\n` +
+  `2. **Explore before asking**: grep/read code first. Only ask user for preferences, not code-fact questions.\n` +
+  `3. **Progressive questioning**: Ask 2-3 questions at a time. Use ask_user tool if available.\n` +
+  `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.`;
+
+// Phase D 第 3 点的选项集描述必须与 buildExecOptions（tool.ts）产出的实际选项一致
+// （≤2 个 plan-exec skill 档 + Execute + Not now，label 与 i18n exec.* 词典同源）——
+// 选项集重排后此处描述漂移会诱导模型向用户预告不存在的执行方式。
+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).`;
+
+/**
+ * /plan 命令的提示词四段注入（D2）：
+ * ① 技能指令（仅挂载 --skills 时）——按技能 SKILL.md 流程产出计划文档；
+ * ② 产物纪律（恒注入）——register-doc 登记 / 修订重调 version+1 / 全部完成调
+ *    submit-review / submit-review 被消费后当轮回应完重挂直到确认；
+ * ③ 只读纪律（恒注入，现状 pi-ext-021 提示词保持）；
+ * ④ 模板流程（仅未指定 --skills 时）——<available-plans> 三源清单注入（内置 5
+ *    + 用户级 + 项目级，模型自选模板，D8）；空发现不注入段（warn 另落）。
+ *    --template 直传（D5）走 ④ 的直传变体：不注入清单段（guide 行「Pick a
+ *    template」与「模板已指定」并存会诱导模型画蛇添足调 select-template），
+ *    改为内嵌模板全文——文件内容直达模型，不赌自发 read。
+ */
+export function buildPlanModePrompt(input: PlanPromptInput): string {
+  const sections: string[] = [`[PLAN MODE] Entered plan mode.\n\nRequirement: ${input.requirement || "(from conversation context)"}\nPlan manifest file: ${input.planFilePath}`];
+
+  // ① 技能指令
+  if (input.skills.length > 0) {
+    const skillLines = input.skills
+      .map((s) => `- ${s.name}: read ${s.skillPath} and follow its workflow to produce the plan documents it specifies.`)
+      .join("\n");
+    sections.push(
+      `## Skill Workflow\n` +
+      `You are working through the following skills (mounted via --skills), in order:\n` +
+      `${skillLines}\n` +
+      `Read each skill file FIRST before producing any document. The skills define WHAT documents to produce and their structure; the plan-mode rules below define WHERE to write them and HOW to register them.`,
+    );
+  }
+
+  // ② 产物纪律
+  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.`,
+  );
+
+  // ③ 只读纪律（现状 pi-ext-021 提示词保持）
+  sections.push(
+    `## Constraints\n` +
+    `- READ-ONLY: Do NOT edit any files except plan documents under the plan directory.\n` +
+    `- Do NOT run write commands (mkdir, echo, sed, etc.) on non-plan files.\n` +
+    `- All plan content goes to plan documents only.`,
+  );
+
+  // ④ 模板流程（无 --skills 回落；--template 直传走变体分支）
+  if (input.template !== undefined) {
+    sections.push(
+      `${PHASE_B_SECTION}\n\n` +
+      `## Phase C: Writing\n` +
+      `1. The template was provided via --template — its full content is embedded below. Do NOT call plan(action='select-template'); the template is already chosen.\n` +
+      `2. Write chapters in template order — do NOT skip unwritten chapters.\n` +
+      `3. Write all chapters in one turn, then ask user to review.\n\n` +
+      `## Template (via --template): ${input.template.absPath}\n\n` +
+      `<template>\n${input.template.content}\n</template>` +
+      `\n\n${PHASE_D_SECTION}`,
+    );
+  } else if (input.skills.length === 0) {
+    // <available-plans> 三源清单随本提示词一次性注入（D3：选型期一次性信息，
+    // select-template 报错自带清单兜底自愈）
+    const plansSection = formatAvailablePlans(listTemplates({ projectRoot: input.projectRoot }));
+    const pickTemplateStep = plansSection !== ""
+      ? `1. Pick the template that best fits this requirement from the <available-plans> list below and call plan tool (select-template, templateName='<name>') — you pick the template yourself; the user can override by replying.`
+      : `1. No plan templates were discovered — structure the plan document with your own chapter skeleton (e.g. Overview / Requirements / Implementation Steps).`;
+    sections.push(
+      `${PHASE_B_SECTION}\n\n` +
+      `## Phase C: Writing\n` +
+      `${pickTemplateStep}\n` +
+      `2. Write chapters in template order — do NOT skip unwritten chapters.\n` +
+      `3. Write all chapters in one turn, then ask user to review.` +
+      (plansSection !== "" ? `\n\n${plansSection}` : "") +
+      `\n\n${PHASE_D_SECTION}`,
+    );
+  }
+
+  return sections.join("\n\n");
+}
+
+/**
+ * revise decision 的评论清单注入文本（D5 decision 消费；explain 决策已删，
+ * PlanReviewDecision 收敛为 'approve' | 'revise'，approve 走 complete 流程不经本函数）。
+ * 评论语义：quote 是用户划选引文（agent 定位段落用），comment 是评语。
+ */
+export function formatReviewComments(comments: PlanReviewComment[]): string {
+  const header = `[PLAN REVIEW] The user submitted ${comments.length} comment(s) and requested document revision. For each comment: locate the quoted passage, apply the requested change, rewrite the file, then re-register it via plan(action='register-doc') — after ALL comments are addressed, call plan(action='submit-review') again to re-hang the review.`;
+
+  const lines = comments.map((c, i) => {
+    const quote = c.quote.trim() || "(no selection)";
+    const comment = c.comment.trim() || "(no text)";
+    return `${i + 1}. Quote: "${quote}"\n   Comment: ${comment}`;
+  });
+
+  return `${header}\n\n${lines.join("\n")}`;
+}

package/src/state.ts

@@ -1,10 +1,55 @@
+import { readdirSync, rmdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+import type { PlanDocMeta } from "@zhushanwen/extension-protocol";
 import type { CustomEntry, ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("pi-plan");
+
+/**
+ * 审阅态两值（D1）——awaiting = 文档就绪等审批；revising = 修订中；
+ * 无值 = 进行中。approve 不设中间态：直接走 complete → resetPlanState 落
+ * isActive=false，PlanModeBar 消失由 isActive 驱动。
+ */
+export type PlanReviewState = "awaiting" | "revising";
+
+/**
+ * 降级态来源标记（plan-mode-ux-refactor §3.4）：reviewState='awaiting' 且无挂起 select
+ * 时区分等待原因——'resubmit' = 会话重启（E3）后 agent 尚未重新提交。写入点 =
+ * index.ts E3 steer 重挂处；清除点三处（resetPlanState 终态清理组 / activatePlanMode
+ * 新轮次重置组 / submit-review 重挂起点重置）——缺清除 = 跨 plan run 残留（C-U2 同型
+ * 缺陷：bad-response 等罕见路径可渲染上一轮的来源文案）。字面量与 shared
+ * PlanStateView.reviewStateSource 严格一致。
+ */
+export type PlanReviewStateSource = "resubmit";
 
 export interface PlanState {
   isActive: boolean;
   planFilePath: string;
   requirement: string;
   templateName: string;
+  /**
+   * --template 直传标记（D7 select-template 防御的判定信号）：直传进入时 =
+   * 展开后模板文件绝对路径；模板流程进入缺失。templateName 字段两流程共用
+   * （直传存 basename / 选中存模板名），单看它无法区分「已直传」与「已选中」，
+   * 故独立持久化直传事实——重启经 entry 恢复，reset 时随退出失效。
+   */
+  templateProvidedPath?: string;
+  /** 挂载技能名清单（--skills 解析产物；模板流程为空数组——挂载声明，reset 时随退出失效） */
+  skills: string[];
+  /** 产物文档清单（register-doc 登记；reset 时保留——产物 tab 与 isActive 解耦，跨重开留存） */
+  docs: PlanDocMeta[];
+  reviewState?: PlanReviewState;
+  /** 降级态来源标记（见 PlanReviewStateSource）；仅 reviewState 有值时有语义，无值 = 来源未知 */
+  reviewStateSource?: PlanReviewStateSource;
+  /**
+   * 上次 submit-review 时的 docs 快照指纹（planDocsFingerprint 产物）。缺失 = 无既往
+   * 提交（首次提交 / reset 后 / 旧版 entry 重挂），重提交无变化检测不警告；reset 随
+   * 退出失效（新 plan 轮次重新计数），重开 session 经 entry 恢复（E3 重挂同款受益）。
+   */
+  lastSubmitReviewDocsFingerprint?: string;
 }
 
 export const DEFAULT_PLAN_STATE: PlanState = {
@@ -12,11 +57,79 @@ export const DEFAULT_PLAN_STATE: PlanState = {
   planFilePath: "",
   requirement: "",
   templateName: "",
+  skills: [],
+  docs: [],
 };
 
+/**
+ * 计划态工具白名单（进入计划模式三处共用——slash 命令 / plan(enter) tool / session_start
+ * 恢复；bash 在白名单内，文件写约束来自注入的计划模式提示词，见 pi-ext-021）。
+ * 放在 state.ts（叶模块）而非 tool.ts：enter.ts 与本常量互需会造成 enter↔tool 循环依赖。
+ */
+export const PLAN_MODE_TOOLS = ["read", "bash", "grep", "find", "ls", "plan"];
+
+/**
+ * plan 包注入消息的 customType（pi.sendMessage custom message 注入的 8 处调用
+ * 统一使用）。命名对齐本包 entry customType 字面量 'plan-state' 的连字符风格
+ * （设计 §2.1 双命名范式决策：各包跟随所在包 entry 惯例，跨包不统一）。
+ * 放 state.ts（叶模块）理由同 PLAN_MODE_TOOLS。
+ */
+export const PLAN_CONTEXT_CUSTOM_TYPE = "plan-context";
+
 /** Per-session state cache. Keyed by sessionId. */
 export type PlanSessionMap = Map<string, PlanState>;
 
+/**
+ * requirement 长度封顶（64KB）：session.planState 帧在 runtime 出站守卫（outbound-frame-registry）
+ * 按「requirement 有界」归入不登记 LARGE_FIELD_REGISTRY 的标量/小列表类——超 32MB 的未登记帧
+ * 会被整帧丢弃（前端 plan 面板缺失）。本封顶把该隐含前提变为代码保障（进入写侧 + entry 重建
+ * 读侧双点）。截断只影响 state/entry/帧；进入提示词仍携带全文直达模型（message content 通路
+ * 有既有注册表登记兜底）。
+ */
+// eslint-disable-next-line no-magic-numbers -- 64KB = 64 * 1024 字节换算常数（同 event-journal.ts 32KB 先例）
+export const MAX_PLAN_REQUIREMENT_LENGTH = 64 * 1024;
+
+/** requirement 封顶：超长截断 + 省略标记（含被省略字符数），短文本原样返回 */
+export function capPlanRequirement(requirement: string): string {
+  if (requirement.length <= MAX_PLAN_REQUIREMENT_LENGTH) return requirement;
+  const omitted = requirement.length - MAX_PLAN_REQUIREMENT_LENGTH;
+  return `${requirement.slice(0, MAX_PLAN_REQUIREMENT_LENGTH)}\n[requirement truncated: ${omitted} characters omitted]`;
+}
+
+/**
+ * docs 快照指纹：fileName:version 按登记序拼接。register-doc 任何形态（新增 /
+ * 同名原位 version+1）都会改变指纹 ⇒「与上次 submit-review 快照相同 ⇔ 期间无任何
+ * register-doc」。空 docs 的指纹是空串，但 submit-review 的 no-docs 守卫先行拦截，
+ * 空串指纹不会入库。
+ */
+export function planDocsFingerprint(docs: PlanDocMeta[]): string {
+  return docs.map((d) => `${d.fileName}:${d.version}`).join("|");
+}
+
+/**
+ * 挂起 select 的 per-session AbortController 注册表（E10）。
+ * 生命周期钉死：每次发挂起 select 前 fresh 一个（见 freshAbortController），
+ * select settled 即弃；session_start / session_shutdown / abort 联动处清理。
+ */
+export type PlanAbortControllers = Map<string, AbortController>;
+
+/**
+ * 发挂起 select 前新建 controller 并登记。禁复用已 abort 的 controller——
+ * pi 实装对已 abort 的 signal 在 createDialogPromise 首行短路立即 resolve undefined，
+ * 复用会让退出后再入 plan 的 submit-review 瞬时静默取消。
+ * pi 实装锚点：dist/modes/rpc/rpc-mode.js:48（0.84.4）——createDialogPromise 首行
+ * `opts?.signal?.aborted` 即 `return Promise.resolve(defaultValue)`，select 的
+ * defaultValue = undefined（E10 生命周期设计依据）。
+ */
+export function freshAbortController(
+  controllers: PlanAbortControllers,
+  sessionId: string,
+): AbortController {
+  const controller = new AbortController();
+  controllers.set(sessionId, controller);
+  return controller;
+}
+
 /**
  * Get plan state for a session. Returns cached state if available,
  * otherwise reconstructs from sessionManager and caches it.
@@ -35,15 +148,46 @@ export function getPlanState(
 }
 
 export function persistPlanState(pi: ExtensionAPI, state: PlanState): void {
+  // customType 字面量 'plan-state' 是 runtime 投影链的派生锚点（u1-proj 侧用同字面量
+  // 派生扫描），两侧独立常量，勿改字面量。optional 字段（reviewState /
+  // reviewStateSource / lastSubmitReviewDocsFingerprint）为 undefined 时 JSON 序列化
+  // 自然消失，旧 entry 消费方对该字段惰性（D4 向后兼容）。
   pi.appendEntry("plan-state", {
     isActive: state.isActive,
     planFilePath: state.planFilePath,
     requirement: state.requirement,
     templateName: state.templateName,
+    templateProvidedPath: state.templateProvidedPath,
+    skills: state.skills,
+    docs: state.docs,
+    reviewState: state.reviewState,
+    reviewStateSource: state.reviewStateSource,
+    lastSubmitReviewDocsFingerprint: state.lastSubmitReviewDocsFingerprint,
   });
 }
 
-/** Reset plan state to idle, persist, and clean up session cache. */
+/**
+ * Reset plan state to idle, persist, and clean up session cache.
+ *
+ * 终态矩阵（D5/E10）：isActive=false + reviewState 清空 + skills 清空（挂载声明失效）+
+ * docs 保留——产物 tab 由 docs.length 驱动、与 isActive 解耦，执行期（approve 后）与
+ * 退出后（abort 后）都可回看产物文档；reset entry 持久，重开 session 后冷启动首拉仍恢复
+ * docs 显示，至下次 /plan 同 slug 覆写。
+ */
+/** 空 slug 目录清理（状态审查 P3-10）：enter 即 mkdir，未产任何文档即退出会留空目录残盘。
+ * 仅删「真正为空」的 slug 目录——目录里有任何残留文件（含未登记杂文件）一律保留（保守，
+ * 不做递归删除）；目录不存在 / 非空 / 不可读均降级跳过（warn 留痕），清理失败不影响退出主流程。
+ */
+function removeEmptyPlanDir(planFilePath: string): void {
+  if (!planFilePath) return;
+  try {
+    const dir = dirname(planFilePath);
+    if (readdirSync(dir).length === 0) rmdirSync(dir);
+  } catch (error) {
+    logger.warn("plan: empty plan dir cleanup skipped", { error: toErrorMessage(error) });
+  }
+}
+
 export function resetPlanState(
   pi: ExtensionAPI,
   sessions: PlanSessionMap,
@@ -52,16 +196,28 @@ export function resetPlanState(
 ): PlanState {
   const state = getPlanState(sessions, sessionId, ctx);
   state.isActive = false;
+  // 空目录清理必须在 planFilePath 清空之前（路径是唯一的目录推导来源）
+  removeEmptyPlanDir(state.planFilePath);
   state.planFilePath = "";
   state.requirement = "";
   state.templateName = "";
+  delete state.templateProvidedPath;
+  state.skills = [];
+  delete state.reviewState;
+  // 来源标记与 reviewState 同生命周期随退出失效：残留 'explain' 会让下一轮经
+  // bad-response 等罕见路径渲染「已收到你的问题」而本轮无人提问（C-U2 同型残留）
+  delete state.reviewStateSource;
+  // 指纹快照随退出失效：approve/abort 后的新 plan 轮次从「无既往提交」重新计数，
+  // 首次 submit-review 不触发无变化警告（docs 虽保留供回看，但不作为检测基线）
+  delete state.lastSubmitReviewDocsFingerprint;
   persistPlanState(pi, state);
   sessions.delete(sessionId);
   return state;
 }
 
 function isPlanStateEntry(entry: SessionEntry): entry is CustomEntry<Partial<PlanState>> & { customType: "plan-state" } {
-  // 判别式收窄（type === "custom"）后可直接访问 customType/data，无需 cast
+  // 判别式收窄（type === "custom"）后可直接访问 customType/data，无需 cast。
+  // 「字段存在即合法」：新字段全部 optional，旧四字段 entry 同样合法（D4 向后兼容）。
   return (
     entry.type === "custom" &&
     entry.customType === "plan-state" &&
@@ -70,6 +226,77 @@ function isPlanStateEntry(entry: SessionEntry): entry is CustomEntry<Partial<Pla
   );
 }
 
+/** skills 白名单式读取：数组 + 逐项 string 守卫，垃圾项丢弃（垃圾数据不进内存态） */
+function readSkills(data: Partial<PlanState>): string[] {
+  if (!Array.isArray(data.skills)) return [];
+  return data.skills.filter((s): s is string => typeof s === "string");
+}
+
+/** PlanDocMeta 最小结构守卫：fileName/absPath 必要字段（渲染与 file.read 的锚点） */
+function isPlanDocMeta(value: unknown): value is PlanDocMeta {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("fileName" in value) || !("absPath" in value)) return false;
+  return typeof value.fileName === "string" && typeof value.absPath === "string";
+}
+
+/** docs 白名单式读取：逐项校验 PlanDocMeta 必要字段（fileName/absPath），缺字段的条目丢弃 */
+function readDocs(data: Partial<PlanState>): PlanDocMeta[] {
+  if (!Array.isArray(data.docs)) return [];
+  return data.docs.filter(isPlanDocMeta);
+}
+
+/** reviewState 值域守卫：'awaiting' | 'revising' 之外的值按无值处理 */
+function readReviewState(data: Partial<PlanState>): PlanReviewState | undefined {
+  return data.reviewState === "awaiting" || data.reviewState === "revising"
+    ? data.reviewState
+    : undefined;
+}
+
+/** reviewStateSource 值域守卫：域外值按无值处理（与 readReviewState 同风格）。
+ * 旧版 entry 的 'explain' 存量值同样归无值——explain 交互已删（2026-09-21 审批两键
+ * 收敛），renderer 缺省分支据此渲染通用文案，无需为存量值保留枚举成员。 */
+function readReviewStateSource(data: Partial<PlanState>): PlanReviewStateSource | undefined {
+  return data.reviewStateSource === "resubmit" ? data.reviewStateSource : undefined;
+}
+
+/** requirement 白名单式读取 + 长度封顶：非 string（含缺失）归空串；封顶前旧版 entry 的
+ * 超长文本在重建时同样封顶（读侧防御，保证派生 plan 帧恒有界） */
+function readRequirement(data: Partial<PlanState>): string {
+  return typeof data.requirement === "string" ? capPlanRequirement(data.requirement) : "";
+}
+
+/** 快照指纹白名单式读取：非 string（含缺失）按无既往提交处理（D4 字段级降级） */
+function readDocsFingerprint(data: Partial<PlanState>): string | undefined {
+  return typeof data.lastSubmitReviewDocsFingerprint === "string"
+    ? data.lastSubmitReviewDocsFingerprint
+    : undefined;
+}
+
+/** 直传标记白名单式读取：非 string（含缺失）按模板流程处理（D4 字段级降级） */
+function readTemplateProvidedPath(data: Partial<PlanState>): string | undefined {
+  return typeof data.templateProvidedPath === "string" ? data.templateProvidedPath : undefined;
+}
+
+/**
+ * 单条 plan-state entry 数据的逐字段应用（调用方已过 isPlanStateEntry 门，data 为
+ * 非空对象；`?? {}` 仅为 data?: T 的类型 shim）。
+ */
+function applyPlanStateEntry(state: PlanState, data: Partial<PlanState> | undefined): void {
+  // 逐字段 ?? 白名单式读取：旧版 entry 残留的 phase 字段被自然忽略（D6 兼容读）；
+  // 新字段缺失（旧 entry）归一为空清单/无值（D4 字段级降级）
+  const entryData = data ?? {};
+  state.isActive = entryData.isActive ?? false;
+  state.planFilePath = entryData.planFilePath ?? "";
+  state.requirement = readRequirement(entryData);
+  state.templateName = entryData.templateName ?? "";
+  state.templateProvidedPath = readTemplateProvidedPath(entryData);
+  state.skills = readSkills(entryData);
+  state.docs = readDocs(entryData);
+  state.reviewState = readReviewState(entryData);
+  state.reviewStateSource = readReviewStateSource(entryData);
+  state.lastSubmitReviewDocsFingerprint = readDocsFingerprint(entryData);
+}
+
 export function reconstructPlanState(ctx: ExtensionContext): PlanState {
   const state = { ...DEFAULT_PLAN_STATE };
   const entries = ctx.sessionManager.getEntries();
@@ -78,12 +305,7 @@ export function reconstructPlanState(ctx: ExtensionContext): PlanState {
     // entries[i] 是复杂表达式（TS 不收窄），守卫移到 const 变量上
     const entry = entries[i];
     if (!isPlanStateEntry(entry)) continue;
-    const data = entry.data;
-    // 逐字段 ?? 白名单式读取：旧版 entry 残留的 phase 字段被自然忽略（D6 兼容读）
-    state.isActive = data?.isActive ?? false;
-    state.planFilePath = data?.planFilePath ?? "";
-    state.requirement = data?.requirement ?? "";
-    state.templateName = data?.templateName ?? "";
+    applyPlanStateEntry(state, entry.data);
     break;
   }
 

package/src/templates.ts

@@ -1,35 +1,113 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const logger = getLogger("pi-plan");
+
 export interface TemplateInfo {
   name: string;
   path: string;
 }
 
+/**
+ * 内置模板目录双形态探测：本文件在两种布局下被加载，templates/ 相对位置不同——
+ *  - 源码形态（npm 安装 / dev jiti 直接加载 src/templates.ts）：__dirname = <pkg>/src，
+ *    模板在 `../templates`（包根 templates/，随 files 白名单发布）。
+ *  - bundle 形态（staged 打包内置，esbuild 把本文件 inline 进包根 index.js）：
+ *    __dirname = …/extensions/@zhushanwen/pi-plan，模板由 bundle-extensions.mjs
+ *    专项拷贝到同级 `templates/`。若仍按 `../templates` 推导会错位一级解析到
+ *    …/@zhushanwen/templates（不存在）→ 打包版模板发现恒空、select-template
+ *    恒 null（scanTemplateDir 的 existsSync 防御不崩溃但静默失效）。
+ * 探测先 bundle 形态后源码形态：两形态目录互斥（staged 无 src/；源码布局 src/ 下
+ * 无 templates/），existsSync 判别即可定位；均缺失时回退源码形态路径，由
+ * scanTemplateDir 的存在性防御兜底（保持既有静默语义，不抛错）。
+ */
 export function getBuiltinTemplateDir(): string {
+  const bundleForm = path.resolve(__dirname, "templates");
+  if (fs.existsSync(bundleForm)) return bundleForm;
   return path.resolve(__dirname, "..", "templates");
 }
 
+/**
+ * 单源目录扫描：纯 readdir 枚举 .md 文件，不读内容。existsSync 通过后 readdir
+ * 仍可能失败（权限 / TOCTOU 竞态）——此处属发现/注入增强面，降级为已扫到的
+ * 清单（空/部分）+ warn 不向上抛（U3）：命令层进入顺序 persist → setActiveTools
+ * → buildPlanModePrompt（内含本扫描），throw 会留下「entry 已写、工具已限、
+ * 提示词未注入」半进入态；与 --template 直传 readFileSync 的 fail-fast（用户
+ * 显式输入，R3）形成对称降级边界——显式输入 fail-fast，增强面降级。
+ */
 function scanTemplateDir(dir: string): TemplateInfo[] {
   const results: TemplateInfo[] = [];
   if (!fs.existsSync(dir)) return results;
-  for (const file of fs.readdirSync(dir)) {
-    if (file.endsWith(".md")) {
-      results.push({ name: file.replace(/\.md$/, ""), path: path.join(dir, file) });
+  try {
+    for (const file of fs.readdirSync(dir)) {
+      if (file.endsWith(".md")) {
+        results.push({ name: file.replace(/\.md$/, ""), path: path.join(dir, file) });
+      }
     }
+  } catch (error) {
+    logger.warn("plan: template source scan failed — source degraded to empty, entering plan mode continues", {
+      dir,
+      error: error instanceof Error ? error.message : String(error),
+    });
   }
   return results;
 }
 
-export function listTemplates(): TemplateInfo[] {
-  return scanTemplateDir(getBuiltinTemplateDir());
+/**
+ * 三源目录参数（D2/D4）——测试隔离注入点：默认路径会读运行机真实
+ * ~/.agents/plans 与项目根，「恰 N 条」类全集断言必须注入 tmp 目录才确定。
+ */
+export interface TemplateSources {
+  /** 内置源目录；缺省 getBuiltinTemplateDir()（双形态探测，本函数零改动沿用） */
+  builtinDir?: string;
+  /** 用户级源目录；缺省 ~/.agents/plans（os.homedir() 内部推导，G2 个人级投放点） */
+  userPlansDir?: string;
+  /** 项目根；给出则扫描 <projectRoot>/.agents/plans（项目级源锚点 = 调用方 ctx.cwd，G2 项目级投放点） */
+  projectRoot?: string;
+}
+
+/**
+ * 三源合并发现器（D2/D4）：内置 → 用户级 → 项目级逐源扫描，同名
+ * last-writer-wins（项目 > 用户 > 内置，<location> 指向胜者路径——注入段里
+ * 同名只出现一条，模型不会选到被遮蔽版本）。纯 readdir 不读文件内容（D6
+ * 砍 description 的连带收益：frontmatter 解析与坏文件防御整面不存在）。
+ * 内置源扫描为空时经 pi-extension-logger 落 warn——不是不可达态，是 bundle
+ * 布局错位的事故信号（staged 错位曾致打包版模板恒 0，见 getBuiltinTemplateDir
+ * 注释）；即使外部源有模板遮蔽该信号也照落（内置丢失本身就该被看见）。
+ */
+export function listTemplates(sources?: TemplateSources): TemplateInfo[] {
+  const builtinDir = sources?.builtinDir ?? getBuiltinTemplateDir();
+  const userPlansDir = sources?.userPlansDir ?? path.join(os.homedir(), ".agents", "plans");
+  const projectPlansDir = sources?.projectRoot !== undefined
+    ? path.join(sources.projectRoot, ".agents", "plans")
+    : undefined;
+
+  const builtin = scanTemplateDir(builtinDir);
+  if (builtin.length === 0) {
+    logger.warn("plan: builtin template source resolved empty — bundle layout mismatch? templates/ missing next to the extension", { builtinDir });
+  }
+
+  const merged = new Map<string, TemplateInfo>();
+  for (const template of builtin) merged.set(template.name, template);
+  for (const template of scanTemplateDir(userPlansDir)) merged.set(template.name, template);
+  if (projectPlansDir !== undefined) {
+    for (const template of scanTemplateDir(projectPlansDir)) merged.set(template.name, template);
+  }
+  return [...merged.values()];
 }
 
-export function loadTemplate(name: string): string | null {
-  const template = listTemplates().find((t) => t.name === name);
+/**
+ * 按名解析模板内容（发现视图的读取侧）。sources 透传给 listTemplates——
+ * 测试与后续合并视图消费方（select-template）注入目录用；缺省走默认路径。
+ */
+export function loadTemplate(name: string, sources?: TemplateSources): string | null {
+  const template = listTemplates(sources).find((t) => t.name === name);
   if (!template) return null;
 
   try {
@@ -38,3 +116,43 @@ export function loadTemplate(name: string): string | null {
     return null;
   }
 }
+
+// ── <available-plans> 段拼装（D6） ─────────────────────────────────
+
+/** XML 特殊字符转义：注入段进 LLM 上下文，字段含 < > & 等会破坏 XML 结构（自写，不引 subagent-core——plan 是轻量 universal 包） */
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/** 码点序比较（禁 localeCompare——宿主 locale 差异会破坏跨环境字节一致） */
+function compareByCodepoint(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** 段内 guide 行（选型主体 = 模型自选，D8：名字自解释，一次选中；用户可对话覆盖） */
+const AVAILABLE_PLANS_GUIDE =
+  "Pick a template from this list, then call plan(action='select-template', templateName='<name>').";
+
+/**
+ * <available-plans> 段拼装纯函数（D6）：条目 <plan><name/><location/></plan>
+ * 两字段必有（不含 description——name 是 select-template 唯一键，location 是
+ * 绝对路径）；全字段 escapeXml；name 码点序排序（与 readdir 枚举序解耦）；
+ * 空清单返回空串——调用方据此不注入段（防御分支，空发现另有 warn 信号）。
+ */
+export function formatAvailablePlans(templates: TemplateInfo[]): string {
+  if (templates.length === 0) return "";
+  const items = [...templates]
+    .sort((a, b) => compareByCodepoint(a.name, b.name))
+    .map((t) => `  <plan><name>${escapeXml(t.name)}</name><location>${escapeXml(t.path)}</location></plan>`);
+  return [
+    "<available-plans>",
+    AVAILABLE_PLANS_GUIDE,
+    ...items,
+    "</available-plans>",
+  ].join("\n");
+}