@zhushanwen/pi-plan 0.4.9 → 0.5.0

package/src/command.ts

@@ -1,21 +1,107 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import type { PlanSessionMap, PlanState } from "./state.js";
-import { getPlanState, persistPlanState, resetPlanState } from "./state.js";
+import { activatePlanMode, resolveSkills } from "./enter.js";
+import type { SkillResolution } from "./enter.js";
+import type { SkillRef } from "./prompts.js";
+import type { PlanAbortControllers, PlanSessionMap, PlanState } from "./state.js";
+import { PLAN_CONTEXT_CUSTOM_TYPE, getPlanState, resetPlanState } from "./state.js";
 import { updatePlanWidget } from "./widget.js";
 
-const MAX_SLUG_LENGTH = 30;
+/** /plan 参数解析产物：requirement = 最早 flag 标记前的自由文本；skills / templatePath 为 undefined = 未提供对应 flag */
+export interface ParsedPlanArgs {
+  requirement: string;
+  skills: string[] | undefined;
+  /** --template 的原始值（flag 后至命令结尾整段 trim，不切分——含空格路径天然支持，无需引号约定） */
+  templatePath: string | undefined;
+}
+
+/**
+ * --skills / --template 解析定则：
+ * - 标记 = 独立 token（\b 词边界防 `--skillsabc` / `--templatex` 误切）；
+ * - 值语义两 flag 同构 = flag 之后至命令结尾的整段文本（requirement 取最早出现
+ *   flag 之前的部分）：
+ *   - `--skills` 按逗号原样切分 + 每项去首尾空格——内部空格保留（「code review」
+ *     「中文 技能」不丢字符），切分后空项丢弃（容忍尾逗号/连续逗号）；
+ *   - `--template` 不切分——trim 后整段即路径（D5）；
+ * - flag 提供但值为空 = 显式错误（E1 fail-fast，不静默忽略——用户显式用了 flag
+ *   却没给值多半是打错了）；
+ * - 两 flag 同给 = 互斥 fail-fast（消费方 handleEnterPlanMode 判定，§3.1——
+ *   解析层照常返回两个字段供其判定）。
+ */
+export function parsePlanArgs(args: string): ParsedPlanArgs {
+  const skillsMatch = /(?:^|\s)--skills\b/.exec(args);
+  const templateMatch = /(?:^|\s)--template\b/.exec(args);
+  if (!skillsMatch && !templateMatch) {
+    return { requirement: args.trim(), skills: undefined, templatePath: undefined };
+  }
+  const firstFlagIndex = Math.min(
+    skillsMatch?.index ?? Number.POSITIVE_INFINITY,
+    templateMatch?.index ?? Number.POSITIVE_INFINITY,
+  );
+  const requirement = args.slice(0, firstFlagIndex).trim();
+  const skills = skillsMatch === null
+    ? undefined
+    : args
+        .slice(skillsMatch.index + skillsMatch[0].length)
+        .trim()
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+  const templatePath = templateMatch === null
+    ? undefined
+    : args.slice(templateMatch.index + templateMatch[0].length).trim();
+  return { requirement, skills, templatePath };
+}
+
+/** --template 校验结果：ok=false 时 problem 为 fail-fast 回复的问题句（自带用法样例） */
+export type TemplateFileResolution =
+  | { ok: true; absPath: string }
+  | { ok: false; problem: string };
+
+/** --template 系报错附带的用法样例（错误 → 纠正闭环） */
+const TEMPLATE_USAGE_SAMPLE = "e.g. /plan <requirement> --template /path/to/template.md";
+
+/**
+ * --template 值解析与校验（D5）：
+ * - `~` 前缀展开（os.homedir，仅 `~` 本身与 `~/` 前缀——`~name` 不展开，
+ *   无 per-user home 展开语义）；
+ * - 相对路径相对 ctx.cwd（pi 进程 cwd = 项目根）解析，不做额外路径猜测；
+ * - 存在性校验先于 .md 校验，两失败文案分家（not found / not a markdown file），
+ *   报错一律带解析后的绝对路径供用户核对。
+ */
+export function resolveTemplateFile(raw: string, projectDir: string): TemplateFileResolution {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return { ok: false, problem: `--template was given but no path followed it. ${TEMPLATE_USAGE_SAMPLE}` };
+  }
+  const expanded = trimmed === "~" || trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(1)) : trimmed;
+  const absPath = path.resolve(projectDir, expanded);
+  if (!fs.existsSync(absPath)) {
+    return { ok: false, problem: `Template file not found: ${absPath}. ${TEMPLATE_USAGE_SAMPLE}` };
+  }
+  if (!absPath.endsWith(".md")) {
+    return { ok: false, problem: `Not a markdown file: ${absPath}. ${TEMPLATE_USAGE_SAMPLE}` };
+  }
+  return { ok: true, absPath };
+}
+
+/**
+ * E1 校验与技能名归一已迁至 enter.ts（slash 与 plan(enter) tool 两入口共用）。
+ * 本文件只保留 slash 命令的入参解析（--skills/--template flag）与投递通道。
+ */
 
 export function registerPlanCommand(
   pi: ExtensionAPI,
   sessions: PlanSessionMap,
+  controllers: PlanAbortControllers,
 ): void {
   pi.registerCommand("plan", {
     description:
-      "Enter plan mode: /plan [description]. " +
+      "Enter plan mode: /plan [description] [--skills a,b] or /plan [description] --template <path-to-markdown>. " +
       "Subcommands: /plan abort, /plan status. " +
       "With no args, show status or detect existing plan.",
     getArgumentCompletions(prefix: string) {
@@ -36,7 +122,7 @@ export function registerPlanCommand(
 
       // Subcommand: abort
       if (trimmed === "abort") {
-        await handleAbort(pi, sessions, sessionId, ctx, state);
+        await handleAbort(pi, sessions, controllers, sessionId, ctx, state);
         return;
       }
 
@@ -58,13 +144,14 @@ export function registerPlanCommand(
         return;
       }
 
-      // Reentry: check for existing plan files in .taiji-harness/
+      // Reentry: check for existing plan files in .tmp/plans/
       if (!state.isActive && !trimmed) {
         const projectDir = ctx.cwd;
-        const harnessDir = path.join(projectDir, ".taiji-harness");
-        const existingPlans = findExistingPlans(harnessDir);
+        const plansDir = path.join(projectDir, ".tmp", "plans");
+        const existingPlans = findExistingPlans(plansDir);
         if (existingPlans.length > 0) {
-          pi.sendUserMessage(
+          sendPlanContextMessage(
+            pi,
             `[PLAN MODE] Found existing plan files:\n${existingPlans.map((p, i) => `  ${i + 1}. ${p}`).join("\n")}\n\n` +
             `Choose an option:\n` +
             `  a) Continue existing plan\n` +
@@ -77,7 +164,7 @@ export function registerPlanCommand(
       }
 
       // Enter plan mode
-      handleEnterPlanMode(pi, sessions, sessionId, ctx, state, trimmed);
+      handleEnterPlanMode(pi, sessions, sessionId, ctx, state, args);
     },
   });
 }
@@ -86,6 +173,7 @@ export function registerPlanCommand(
 async function handleAbort(
   pi: ExtensionAPI,
   sessions: PlanSessionMap,
+  controllers: PlanAbortControllers,
   sessionId: string,
   ctx: ExtensionContext,
   state: PlanState,
@@ -94,6 +182,12 @@ async function handleAbort(
     ctx.ui.notify("No active plan mode.", "info");
     return;
   }
+  // E10 顺序不可反（因果链）：controller.abort() → 挂起 select resolve undefined →
+  // tool execute 走「已取消」分支返回 → turn 正常结束 → agent_settled 到达 →
+  // busy defer 队列恢复投递。若先 reset 后 abort，挂起 select 无人 resolve 且
+  // runtime 不超时 → pi turn 永占用 → 后续消息永 defer → session 只能 forceQuit。
+  controllers.get(sessionId)?.abort();
+  controllers.delete(sessionId);
   const updatedState = resetPlanState(pi, sessions, sessionId, ctx);
   updatePlanWidget(ctx, updatedState);
   // Restore full tool set (SDK does NOT support undefined)
@@ -110,26 +204,69 @@ function handleStatus(
     ctx.ui.notify("No active plan mode.", "info");
     return;
   }
+  const skillsLine = state.skills.length > 0 ? `\nSkills: ${state.skills.join(", ")}` : "";
+  const docsLine = state.docs.length > 0 ? `\nDocuments: ${state.docs.map((d) => `${d.fileName} (v${d.version})`).join(", ")}` : "";
   ctx.ui.notify(
-    `Plan: ${state.planFilePath}\nTemplate: ${state.templateName || "(not selected)"}`,
+    `Plan: ${state.planFilePath}\nTemplate: ${state.templateName || "(not selected)"}${skillsLine}${docsLine}`,
     "info",
   );
 }
 
-/** Find existing plan.md files in .taiji-harness/ subdirectories */
-function findExistingPlans(harnessDir: string): string[] {
+/** Find existing plan.md files in .tmp/plans/ subdirectories */
+function findExistingPlans(plansDir: string): string[] {
   try {
-    return fs.readdirSync(harnessDir)
+    return fs.readdirSync(plansDir)
       .filter((f) => {
-        const subDir = path.join(harnessDir, f);
+        const subDir = path.join(plansDir, f);
         return fs.statSync(subDir).isDirectory() && fs.existsSync(path.join(subDir, "plan.md"));
       })
-      .map((f) => path.join(harnessDir, f, "plan.md"));
+      .map((f) => path.join(plansDir, f, "plan.md"));
   } catch {
     return [];
   }
 }
 
+/**
+ * plan 上下文消息单点（slash 通道 4 个 sendMessage 位共用形态）：custom message 注入
+ * （display:false——提示词全文消费者是 LLM，用户感知走 plan widget 状态呈现，不占用户
+ * 气泡）+ triggerTurn:true 保留原开轮语义。
+ */
+function sendPlanContextMessage(pi: ExtensionAPI, content: string): void {
+  pi.sendMessage(
+    { customType: PLAN_CONTEXT_CUSTOM_TYPE, content, display: false },
+    { triggerTurn: true },
+  );
+}
+
+/** E1 fail-fast 回复：不进入计划模式（不写 entry / 不限制工具 / 不注入计划提示词），回复可用技能清单与纠正命令 */
+function reportUnknownSkills(pi: ExtensionAPI, resolution: Extract<SkillResolution, { ok: false }>): void {
+  const available = resolution.available.length > 0
+    ? resolution.available.map((n) => `  - ${n}`).join("\n")
+    : "  (no skills installed)";
+  const problem = resolution.missing.length > 0
+    ? `unknown skill(s): ${resolution.missing.join(", ")}`
+    : "--skills was given but no skill names followed it";
+  sendPlanContextMessage(
+    pi,
+    `[PLAN MODE] Failed to enter: ${problem}.\n\n` +
+    `Available skills:\n${available}\n\n` +
+    `Do NOT enter plan mode. Reply to the user listing the available skills and the corrected command, e.g. /plan <requirement> --skills <skill1>,<skill2>.`,
+  );
+}
+
+/**
+ * --template 系 fail-fast 回复（E1 同款形态）：不进入计划模式（不写 entry /
+ * 不限制工具 / 不注入计划提示词），回复问题句（互斥/不存在/非 md，problem 内
+ * 已带用法样例）。
+ */
+function reportTemplateFlagError(pi: ExtensionAPI, problem: string): void {
+  sendPlanContextMessage(
+    pi,
+    `[PLAN MODE] Failed to enter: ${problem}.\n\n` +
+    `Do NOT enter plan mode. Reply to the user with the problem and the corrected command.`,
+  );
+}
+
 /** Handle entering plan mode */
 function handleEnterPlanMode(
   pi: ExtensionAPI,
@@ -137,51 +274,72 @@ function handleEnterPlanMode(
   sessionId: string,
   ctx: ExtensionContext,
   state: PlanState,
-  requirement: string,
+  args: string,
 ): void {
-  const slug = requirement
-        ? requirement.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, MAX_SLUG_LENGTH)
-    : "untitled";
-
-  const projectDir = ctx.cwd;
-  const planDir = path.join(projectDir, ".taiji-harness", slug);
-  fs.mkdirSync(planDir, { recursive: true });
-  const planFilePath = path.join(planDir, "plan.md");
-
-  state.isActive = true;
-  state.planFilePath = planFilePath;
-  state.requirement = requirement;
-  state.templateName = "";
-
-  persistPlanState(pi, state);
-  updatePlanWidget(ctx, state);
-
-  // Restrict tools to the plan-mode set (includes bash — file-write constraints come from the injected plan mode prompt below)
-  pi.setActiveTools(["read", "bash", "grep", "find", "ls", "plan"]);
-
-  // Inject plan mode system prompt inline
-  pi.sendUserMessage(
-    `[PLAN MODE] Entered plan mode.\n\n` +
-    `Requirement: ${requirement || "(from conversation context)"}\n` +
-    `Plan file: ${planFilePath}\n\n` +
-    `## Constraints\n` +
-    `- READ-ONLY: Do NOT edit any files except the plan file (${planFilePath}).\n` +
-    `- Do NOT run write commands (mkdir, echo, sed, etc.) on non-plan files.\n` +
-    `- All plan content goes to the plan file only.\n\n` +
-    `## 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.\n\n` +
-    `## Phase C: Writing\n` +
-    `1. Call plan tool (list-template) to show available templates.\n` +
-    `2. After user selects template, call plan tool (select-template).\n` +
-    `3. Write chapters in template order — do NOT skip unwritten chapters.\n` +
-    `4. Write all chapters in one turn, then ask user to review.\n\n` +
-    `## 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 path (subagent-driven / goal-driven / single-agent) via the completion dialog.`,
-  );
+  // flag 解析 + 校验先行：--template / --skills 任一校验失败 fail-fast，
+  // 不产生任何进入动作（PlanModeBar 不出现：不写 entry / 不限制工具 / 不注入提示词）
+  const parsed = parsePlanArgs(args);
+
+  // 互斥 fail-fast（§3.1）：两 flag 同给先于一切值校验报错
+  if (parsed.skills !== undefined && parsed.templatePath !== undefined) {
+    reportTemplateFlagError(
+      pi,
+      "--template and --skills are mutually exclusive. Use one: /plan <requirement> --skills a,b | /plan <requirement> --template <path>",
+    );
+    return;
+  }
+
+  let templateAbsPath: string | undefined;
+  let templateContent: string | undefined;
+  if (parsed.templatePath !== undefined) {
+    const resolution = resolveTemplateFile(parsed.templatePath, ctx.cwd);
+    if (!resolution.ok) {
+      reportTemplateFlagError(pi, resolution.problem);
+      return;
+    }
+    // 全文在校验通过后、任何进入副作用（entry/工具限制）之前读好——读失败
+    // （权限/竞态删除）同族 fail-fast，不留「已持久 isActive 但提示词没注入」
+    // 的半进入态（D5）
+    try {
+      templateContent = fs.readFileSync(resolution.absPath, "utf-8");
+    } catch {
+      reportTemplateFlagError(pi, `Template file not readable: ${resolution.absPath}. ${TEMPLATE_USAGE_SAMPLE}`);
+      return;
+    }
+    templateAbsPath = resolution.absPath;
+  }
+
+  // --skills E1 校验（互斥已判过后，走到这里 templatePath 必为 undefined）
+  const requested = parsed.skills ?? [];
+  if (parsed.skills !== undefined && requested.length === 0) {
+    reportUnknownSkills(pi, { ok: false, available: pi.getCommands().filter((c) => c.source === "skill").map((c) => c.name), missing: [] });
+    return;
+  }
+  let resolved: SkillRef[] = [];
+  if (requested.length > 0) {
+    const resolution = resolveSkills(pi, requested);
+    if (!resolution.ok) {
+      reportUnknownSkills(pi, resolution);
+      return;
+    }
+    resolved = resolution.resolved;
+  }
+
+  const requirement = parsed.requirement;
+  // 进入核心收敛到 enter.ts（plan(enter) tool 与 slash 命令共用）；本入口只负责
+  // flag 解析/校验（上方）与提示词投递（下方 sendMessage custom message 注入）。
+  // state 由 activatePlanMode 就地改 + persist（getPlanState 缓存同一对象）。
+  const { prompt } = activatePlanMode(pi, sessions, sessionId, ctx, {
+    requirement,
+    skills: resolved,
+    projectDir: ctx.cwd,
+    ...(templateAbsPath !== undefined && templateContent !== undefined
+      ? { template: { absPath: templateAbsPath, content: templateContent } }
+      : {}),
+  });
+
+  // Inject plan mode prompt as custom message（display/triggerTurn 语义见 sendPlanContextMessage。
+  // 非 streaming 直调 _runAgentPrompt 跳过 prompt() 前置链，首轮 systemPrompt 叠加
+  // 差异已登记为可接受——设计 §1.1-⑥ / §2.2 P1。tool 入口走 tool result）
+  sendPlanContextMessage(pi, prompt);
 }

package/src/compact.ts

@@ -6,8 +6,9 @@ import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import type { GoalInitFn } from "@zhushanwen/pi-goal";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
+import { t } from "./i18n.js";
 import type { PlanSessionMap, PlanState } from "./state.js";
-import { getPlanState } from "./state.js";
+import { PLAN_CONTEXT_CUSTOM_TYPE, getPlanState } from "./state.js";
 
 const logger = getLogger("pi-plan");
 
@@ -115,6 +116,9 @@ function buildPlanSlug(planFilePath: string): string {
 
 /** step preview 条数上限（1 条总述 + 3 条 preview，合计 ≤4 条，满足 goal schema maxItems:8） */
 const PREVIEW_COUNT = 3;
+
+/** skill 档 execMode 前缀（D10：`skill:<name>` 动态项，与 tool.ts 选项构造同源约定） */
+const SKILL_MODE_PREFIX = "skill:";
 /** 单条 preview 最大长度（超出部分截断，以 "..." 结尾） */
 const PREVIEW_MAX_CHARS = 80;
 const ELLIPSIS = "...";
@@ -151,7 +155,7 @@ export function buildPlanSuccessCriteria(planFilePath: string, tasks: string[]):
 
 /** goalInit 失败原因——五值与 tryGoalInit 的 5 个失败出口一一对应（设计 §6.2 D2）。 */
 export type GoalBridgeFailureReason =
-  | "goal-unavailable" // goal 未加载（slot 不存在/值非函数——桥修复后是真实可达的防御分支：goal 档仅在 detectGoalCapability 通过时出现，但 slot 残留 fn 失效等窗口仍可能触发）
+  | "goal-unavailable" // goal 未加载（slot 不存在/值非函数——execute 档无条件尝试 goalInit，goal 扩展未装/未挂 slot 时即走此出口，独立 pi 常态分支）
   | "plan-unreadable" // plan 文件读取失败
   | "no-steps" // plan 内容提取到 0 条步骤
   | "init-refused" // goalInit 返回 false（已有 active goal / ctx 缺失）
@@ -164,7 +168,7 @@ export type GoalBridgeOutcome =
 
 /** 每个 reason 指向一个具体恢复动作（不做纯日志字符串，设计 §4.2）。 */
 export const GOAL_FAILURE_RECOVERY: Record<GoalBridgeFailureReason, string> = {
-  "goal-unavailable": "The goal extension is not loaded — choose another execution method.",
+  "goal-unavailable": "The goal extension is not loaded — execute directly without goal tracking.",
   "plan-unreadable": "Check that the plan file exists and is readable, then call plan(action='complete') again.",
   "no-steps": "Add numbered steps under a '## Implementation Steps' section in the plan file, then call plan(action='complete') again.",
   "init-refused": "An active goal already exists — run /goal clear first, or continue with the existing goal.",
@@ -241,34 +245,42 @@ export function extractPlanSteps(planContent: string): string[] {
 
 
 /**
- * 投递 complete 后的执行通知（D2：goal 档先 goalInit、后按结果选 steer）。
- * 成功发 goal steer——「Execute via /goal」只在 goal 真实创建成功时说出；失败发
- * 含 reason 与恢复动作的降级 steer + warning notify。非 goal 档无 goalInit，按
- * execMode 组 steer。返回 goalInit 的 outcome（非 goal 档为 undefined）。
+ * 投递 complete 后的执行通知（2026-09-21 选项集重排：mode 值域 = execute | skill:<name>；
+ * execute 档整合 goal 桥 + auto-parallel subagent——goal 可用时先 goalInit 建跟踪，
+ * 失败/不可用降级为直接执行的 steer 指令，用户可见失败提示走 notify i18n）。
+ * skill 档动态构造 steer（含 skillEntryPath 路径，对齐 register-doc sourceSkill 的 skill 关联
+ * 先例；skillEntryPath = skill 入口文件路径——标准形态 SKILL.md 路径 / 散 .md 形态文件本身，
+ * 直接 read 不再拼 SKILL.md）。返回 goalInit 的 outcome（非 execute 档为 undefined）。
  */
 function deliverExecutionNotice(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   planFilePath: string,
   execMode: string,
+  skillEntryPath?: string,
 ): GoalBridgeOutcome | undefined {
-  const outcome = execMode === "goal" ? tryGoalInit(planFilePath, ctx) : undefined;
-
-  const modeMessages: Record<string, string> = {
-    subagent: "Execute via subagent-driven development: delegate each task to an independent subagent for parallel execution.",
-    goal: "Execute via /goal: set up tracked task decomposition with budget control using the goal extension.",
-    "single-agent": "Execute step by step in the current session.",
-  };
+  // execute 档整合 goal 桥：tryGoalInit 内部含 goal-unavailable gate（goal 未挂载走
+  // started:false 降级），无需前置 detectGoalCapability 探测
+  const outcome = execMode === "execute" ? tryGoalInit(planFilePath, ctx) : undefined;
 
   let modeHint: string;
-  if (outcome === undefined) {
-    modeHint = modeMessages[execMode] ?? modeMessages["single-agent"];
-  } else if (outcome.started) {
-    modeHint = modeMessages.goal;
-  } else {
-    modeHint = `Goal execution was not started (${outcome.reason}). ${GOAL_FAILURE_RECOVERY[outcome.reason]} Execute step by step in the current session.`;
+  if (execMode.startsWith(SKILL_MODE_PREFIX)) {
+    const skillName = execMode.slice(SKILL_MODE_PREFIX.length);
+    modeHint = skillEntryPath
+      ? `Execute via skill: read the ${skillName} skill at ${skillEntryPath} first, then follow its workflow to execute the plan file.`
+      : `Execute via skill: load the ${skillName} skill and follow its workflow to execute the plan file.`;
+  } else if (outcome?.started) {
+    modeHint =
+      "Goal tracking is active via /goal — execute the plan through the goal workflow: delegate independent, parallelizable tasks to subagents; run small or tightly-coupled steps in this session.";
+  } else if (outcome !== undefined) {
+    modeHint =
+      `Goal tracking was not started (${outcome.reason}). ${GOAL_FAILURE_RECOVERY[outcome.reason]} ` +
+      `Execute directly instead: judge by task complexity — delegate independent, parallelizable tasks to subagents; run small or tightly-coupled steps step by step in the current session.`;
     const detail = outcome.detail ? ` (${outcome.detail})` : "";
-    ctx.ui.notify(`Goal execution was not started (${outcome.reason})${detail}. ${GOAL_FAILURE_RECOVERY[outcome.reason]}`, "warning");
+    ctx.ui.notify(`${t("exec.goalFailedNotify", { reason: outcome.reason })}${detail}`, "warning");
+  } else {
+    modeHint =
+      "Execute by judging task complexity: delegate independent, parallelizable tasks to subagents; execute small or tightly-coupled steps step by step in the current session.";
   }
 
   const executeMessage =
@@ -277,16 +289,19 @@ function deliverExecutionNotice(
     `${modeHint}\n\n` +
     `Read the plan file and start implementing.`;
 
-  pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
+  pi.sendMessage(
+    { customType: PLAN_CONTEXT_CUSTOM_TYPE, content: executeMessage, display: false },
+    { deliverAs: "steer", triggerTurn: true },
+  );
   return outcome;
 }
 
 /**
  * complete 的 isolation 分发（D1 后仅 compact | direct，两档都投递执行通知）。
  *
- * 返回值：execMode=goal 且 isolation=direct 时同步返回 goalInit 的 outcome
+ * 返回值：execMode=execute 且 isolation=direct 时同步返回 goalInit 的 outcome
  * （executeComplete 写进 result content 与 details）；其余情形返回 undefined——
- * 非 goal 档无 goalInit，compact 档 goalInit 在 onComplete 回调内执行（goal 状态
+ * skill 档无 goalInit，compact 档 goalInit 在 onComplete 回调内执行（goal 状态
  * entry 须在压缩后的世界里创建，提前到 compact 前有被压缩边界丢弃的风险，时序
  * 不动——设计 §6.2 D2），该档 result 已返回，失败报告走 steer + notify 通道。
  */
@@ -296,6 +311,7 @@ export function handlePlanComplete(
   state: PlanState,
   isolation: string,
   execMode: string,
+  skillEntryPath?: string,
 ): GoalBridgeOutcome | undefined {
   const planFilePath = state.planFilePath;
 
@@ -311,7 +327,7 @@ export function handlePlanComplete(
         // 守卫的 stale 文案兜底（D1 降级语义声明的合法形态）。
         onComplete: () => {
           guardStaleCtx(() => {
-            deliverExecutionNotice(pi, ctx, planFilePath, execMode);
+            deliverExecutionNotice(pi, ctx, planFilePath, execMode, skillEntryPath);
           }, {
             label: "plan:compact-onComplete",
             onStale: (error) => logger.warn("plan execution notice delivery skipped (stale ctx)", { error: toErrorMessage(error) }),
@@ -320,7 +336,7 @@ export function handlePlanComplete(
         onError: (_error: Error) => {
           guardStaleCtx(() => {
             ctx.ui.notify("Compact failed, continuing without isolation.", "warning");
-            deliverExecutionNotice(pi, ctx, planFilePath, execMode);
+            deliverExecutionNotice(pi, ctx, planFilePath, execMode, skillEntryPath);
           }, {
             label: "plan:compact-onError",
             onStale: (error) => logger.warn("plan execution notice delivery skipped (stale ctx)", { error: toErrorMessage(error) }),
@@ -332,7 +348,7 @@ export function handlePlanComplete(
 
     case "direct":
     default: {
-      return deliverExecutionNotice(pi, ctx, planFilePath, execMode);
+      return deliverExecutionNotice(pi, ctx, planFilePath, execMode, skillEntryPath);
     }
   }
 }

package/src/enter.ts

@@ -0,0 +1,133 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { buildPlanModePrompt } from "./prompts.js";
+import type { SkillRef } from "./prompts.js";
+import type { PlanSessionMap, PlanState } from "./state.js";
+import { capPlanRequirement, getPlanState, persistPlanState, PLAN_MODE_TOOLS } from "./state.js";
+import { updatePlanWidget } from "./widget.js";
+
+export const MAX_SLUG_LENGTH = 30;
+
+/** E1 技能解析结果：ok=false 时携带缺失项与可用清单（fail-fast 回复的材料） */
+export type SkillResolution =
+  | { ok: true; resolved: SkillRef[] }
+  | { ok: false; available: string[]; missing: string[] };
+
+/**
+ * 技能名归一：剥掉 pi 命令命名空间前导 `skill:` 前缀，得到自然技能名。
+ * pi.getCommands() 枚举 skill 类命令时 name 带 `skill:` 前缀（如 `skill:tech-design`），
+ * 这是 pi 的实现细节，不得泄漏到输入面——slash `--skills` 与 plan(enter) 的 skills 参数
+ * 都用自然技能名。枚举侧与输入侧双向剥前缀后比对，兼容两种形态。
+ */
+export function normalizeSkillName(name: string): string {
+  return name.startsWith("skill:") ? name.slice("skill:".length) : name;
+}
+
+/**
+ * E1 校验：pi.getCommands() 过滤 source === "skill" 枚举比对（技能枚举与路径
+ * 经 pi 取得，不自扫描目录——D2）。比对前双向剥 `skill:` 前缀归一：resolved/missing
+ * 用归一后的短名；available 维持枚举原形态（错误信息里可直接复制为 pi 命令）。
+ * slash 命令与 plan(enter) tool 两入口共用（自 command.ts 迁入 enter.ts）。
+ */
+export function resolveSkills(pi: ExtensionAPI, requested: string[]): SkillResolution {
+  const skillCommands = pi.getCommands().filter((c) => c.source === "skill");
+  const byShortName = new Map(skillCommands.map((c) => [normalizeSkillName(c.name), c.sourceInfo.path]));
+  const available = skillCommands.map((c) => c.name);
+  const resolved: SkillRef[] = [];
+  const missing: string[] = [];
+  for (const raw of requested) {
+    const name = normalizeSkillName(raw);
+    const skillPath = byShortName.get(name);
+    if (skillPath === undefined) {
+      missing.push(name);
+    } else {
+      resolved.push({ name, skillPath });
+    }
+  }
+  return missing.length > 0 ? { ok: false, available, missing } : { ok: true, resolved };
+}
+
+/** 进入 plan 模式的归一入参（slash 命令与 plan(enter) tool 两入口共用） */
+export interface ActivatePlanModeInput {
+  requirement: string;
+  /** E1 校验后的技能引用（未挂载传空数组） */
+  skills: SkillRef[];
+  /** 项目根锚点（= ctx.cwd），plan 目录与模板扫描的公共锚 */
+  projectDir: string;
+  /** --template 直传时给出（与 skills 互斥，命令层已校验并读好全文） */
+  template?: { absPath: string; content: string };
+}
+
+/** 进入产物：状态引用 + 直达模型的 plan 模式提示词（两入口分别走 sendMessage custom message / tool result 投递） */
+export interface ActivatePlanModeOutcome {
+  state: PlanState;
+  prompt: string;
+}
+
+/**
+ * 进入 plan 模式的共享核心（plan-mode-agent-enter U1）：slash 命令 handler 与 plan(enter)
+ * tool 两入口收敛同一实现——状态建立 + 持久化 + widget + 工具收拢 + 提示词构造。
+ *
+ * 不做的事（留给调用方）：
+ * - 提示词投递通道：slash 入口经 sendMessage custom message（display:false——提示词
+ *   全文消费者是 LLM，用户感知走 plan widget 状态呈现；triggerTurn:true 开轮）；tool 入口经
+ *   tool result content 直返（对本次 tool 调用的直接响应，agent 同轮即见——不赌 steer 排队）。
+ * - flag 解析 / 模板文件读取 / 技能名归一：命令层与 tool 层各自的入参形态不同，前置已完成。
+ *
+ * 副作用顺序钉死：状态字段 → persistPlanState（entry 落盘）→ updatePlanWidget →
+ * setActiveTools → 构造 prompt。persist 先于工具收拢，保证「已持久 isActive 但工具未收」
+ * 的半进入态不可达（崩溃窗口内重开 session 经 entry 恢复 isActive，session_start hook
+ * 会补 setActiveTools）。
+ */
+export function activatePlanMode(
+  pi: ExtensionAPI,
+  sessions: PlanSessionMap,
+  sessionId: string,
+  ctx: ExtensionContext,
+  input: ActivatePlanModeInput,
+): ActivatePlanModeOutcome {
+  const state = getPlanState(sessions, sessionId, ctx);
+  const { requirement, skills, projectDir } = input;
+
+  const slug = requirement
+    ? requirement.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, MAX_SLUG_LENGTH)
+    : "untitled";
+
+  const planDir = path.join(projectDir, ".tmp", "plans", slug);
+  fs.mkdirSync(planDir, { recursive: true });
+  const planFilePath = path.join(planDir, "plan.md");
+
+  state.isActive = true;
+  state.planFilePath = planFilePath;
+  // state/entry/plan 帧侧 requirement 64KB 封顶（帧有界前提）；prompt 仍用未封顶全文直达模型
+  state.requirement = capPlanRequirement(requirement);
+  // --template 直传：templateName = 去扩展名 basename（GUI / /plan status 展示）；
+  // 直传事实另落 templateProvidedPath（select-template 防御的判定信号，D7）
+  state.templateName = input.template ? path.basename(input.template.absPath, ".md") : "";
+  state.templateProvidedPath = input.template?.absPath;
+  state.skills = skills.map((s) => s.name);
+  state.docs = [];
+  // 新轮次重置：reviewState、来源标记与指纹基线随进入失效（与 resetPlanState 对齐；
+  // reviewStateSource 残留会让新一轮降级态渲染上一轮来源文案——C-U2 同型残留）
+  delete state.reviewState;
+  delete state.reviewStateSource;
+  delete state.lastSubmitReviewDocsFingerprint;
+
+  persistPlanState(pi, state);
+  updatePlanWidget(ctx, state);
+  // 收拢工具到 plan 模式白名单（含 bash——文件写约束来自下方注入的只读纪律提示词）
+  pi.setActiveTools(PLAN_MODE_TOOLS);
+
+  const prompt = buildPlanModePrompt({
+    requirement,
+    planFilePath,
+    projectRoot: projectDir,
+    skills,
+    ...(input.template !== undefined ? { template: input.template } : {}),
+  });
+
+  return { state, prompt };
+}