@foolsecret/pi-planmode 1.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+# 发布到 npm：推送 v* tag 时自动执行
+# 认证：GitHub Secret NPM_TOKEN（granular token，勾选 bypass 2FA）
+#   更换 token：gh secret set NPM_TOKEN（本地 gh CLI 已登录）
+name: Publish to npm
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org/
+      - name: Check version matches tag
+        run: node -e "const v=require('./package.json').version; const t=process.env.GITHUB_REF_NAME.slice(1); if(v!==t){console.error(`package.json ${v} != tag v${t}`);process.exit(1)}"
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Titor-Z
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+<div align="center">
+
+# pi-planning
+
+**Plan mode for Pi Agent — read-only exploration, plan extraction & execution progress tracking.**
+
+计划模式：只读探索 → 生成计划 → 全量执行 → 进度追踪，一站式完成。
+
+</div>
+
+---
+
+## ✨ 它是什么？
+
+一个开关，让 AI 先想清楚再动手：
+
+- 🔒 **只读探索**：禁用 edit/write，Bash 限制在只读命令白名单内，安全分析代码
+- 📋 **计划提取**：AI 在 `Plan:` 标题下输出编号步骤，自动提取为待办清单
+- 🚀 **全量执行**：确认后恢复全部工具，按步骤执行
+- ☑️ **进度追踪**：AI 每完成一步输出 `[DONE:n]`，侧边 widget 实时勾选进度
+
+### 使用方式
+
+| 入口 | 说明 |
+|---|---|
+| `/plan` | 切换计划模式（只读 ⇄ 正常） |
+| `Ctrl+Alt+P` | 同上，快捷键 |
+| `pi --plan` | 启动时直接进入计划模式 |
+| `/todos` | 查看当前计划进度 |
+| 计划确认弹窗 | 执行计划 / 继续探索 / 修改计划 |
+
+### 视觉反馈
+
+- Plan 模式：输入框边框变为半透明橙色，footer 显示 `[ PLAN ]` 徽章
+- 执行模式：widget 显示 `📋 2/5` 式进度，已完成步骤划线勾选
+
+## 📦 安装
+
+```bash
+pi install npm:@foolsecret/pi-planmode
+# 或从 GitHub
+pi install git:github.com/Titor-Z/pi-planmode
+```
+
+## 🧠 工作原理
+
+1. **激活**：`/plan` 后注入只读上下文，收窄工具集（保留 read/bash/grep 等，移除 edit/write）
+2. **防护**：`tool_call` 拦截非白名单 Bash 命令（写文件、包管理、git 写操作、系统命令等 60+ 模式）
+3. **提取**：回合结束从 AI 回复的 `Plan:` 段提取编号步骤
+4. **执行**：用户确认后恢复完整工具集，逐步执行；`turn_end` 扫描 `[DONE:n]` 标记更新进度
+5. **持久化**：状态写入会话（custom entry），`--resume` 恢复会话时自动还原进度
+
+## 📁 结构
+
+```
+extensions/index.ts       薄入口：命令/快捷键/事件注册
+extensions/mode-editor.ts 输入框边框变色（独立扩展，与主扩展共享状态）
+src/state.ts              globalThis 共享状态（跨扩展通信）
+src/utils.ts              纯函数：命令白名单、计划提取、进度标记
+src/prompt.ts             注入给模型的提示词常量
+```
+
+## ⚠️ 说明
+
+- npm 包名为 `@foolsecret/pi-planmode`（scope 保住了 planmode 原名）；本 GitHub 仓库名为 `pi-planmode`（仓库名不受
+  npm 规则约束）
+
+- npm 上的 `pi-plan-mode`（qmx 维护）为无关项目；npm 名称混淆保护也不允许
+  发布 `pi-planmode`（与 pi-plan-mode 过似），故定名 `pi-planning`
+- Bash 白名单为保守设计：不在白名单内一律拦截，宁严勿松
+
+## English
+
+**@foolsecret/pi-planmode** adds plan mode to Pi Agent: a toggle that switches the agent into read-only exploration (write tools disabled, bash restricted to a safe allowlist), extracts numbered plan steps from the AI's "Plan:" section, then executes with full tool access while tracking progress via `[DONE:n]` markers. Includes an input-box border tint and progress widget. Install with `pi install npm:@foolsecret/pi-planmode`, toggle with `/plan` or Ctrl+Alt+P.
+
+## License
+
+MIT © 2026 Titor-Z
+
+---
+
+**Star 🌟 让每一次执行都先有计划。**

package/extensions/index.ts

@@ -0,0 +1,364 @@
+/**
+ * Plan Mode Extension
+ *
+ * Read-only exploration mode for safe code analysis.
+ * When enabled, built-in write tools are disabled.
+ *
+ * Features:
+ * - /plan command or Ctrl+Alt+P to toggle
+ * - Bash restricted to allowlisted read-only commands
+ * - Extracts numbered plan steps from "Plan:" sections
+ * - [DONE:n] markers to complete steps during execution
+ * - Progress tracking widget during execution
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+import { extractTodoItems, isSafeCommand, markCompletedSteps, type TodoItem } from "../src/utils.ts";
+import { setPlanMode, PLAN_BADGE } from "../src/state.ts";
+import { PLAN_MODE_PROMPT, executionPrompt, executionReminder } from "../src/prompt.ts";
+
+// Tools
+const PLAN_MODE_TOOLS = ["read", "bash", "grep", "find", "ls", "questionnaire"];
+const NORMAL_MODE_TOOLS = ["read", "bash", "edit", "write"];
+const PLAN_MODE_DISABLED_TOOLS = new Set<string>(["edit", "write"]);
+const PLAN_MANAGED_TOOLS = new Set<string>([...PLAN_MODE_TOOLS, ...NORMAL_MODE_TOOLS]);
+
+interface PlanModeState {
+	enabled: boolean;
+	todos?: TodoItem[];
+	executing?: boolean;
+	toolsBeforePlanMode?: string[];
+}
+
+// Type guard for assistant messages
+function isAssistantMessage(m: AgentMessage): m is AssistantMessage {
+	return m.role === "assistant" && Array.isArray(m.content);
+}
+
+// Extract text content from an assistant message
+function getTextContent(message: AssistantMessage): string {
+	return message.content
+		.filter((block): block is TextContent => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
+}
+
+export default function planModeExtension(pi: ExtensionAPI): void {
+	let planModeEnabled = false;
+	let executionMode = false;
+	let todoItems: TodoItem[] = [];
+	let toolsBeforePlanMode: string[] | undefined;
+
+	pi.registerFlag("plan", {
+		description: "Start in plan mode (read-only exploration)",
+		type: "boolean",
+		default: false,
+	});
+
+	function updateStatus(ctx: ExtensionContext): void {
+		// Footer status
+		if (executionMode && todoItems.length > 0) {
+			const completed = todoItems.filter((t) => t.completed).length;
+			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("accent", `📋 ${completed}/${todoItems.length}`));
+		} else if (planModeEnabled) {
+			ctx.ui.setStatus("plan-mode", PLAN_BADGE);
+		} else {
+			ctx.ui.setStatus("plan-mode", undefined);
+		}
+
+		// Widget showing todo list
+		if (executionMode && todoItems.length > 0) {
+			const lines = todoItems.map((item) => {
+				if (item.completed) {
+					return (
+						ctx.ui.theme.fg("success", "☑ ") + ctx.ui.theme.fg("muted", ctx.ui.theme.strikethrough(item.text))
+					);
+				}
+				return `${ctx.ui.theme.fg("muted", "☐ ")}${item.text}`;
+			});
+			ctx.ui.setWidget("plan-todos", lines);
+		} else {
+			ctx.ui.setWidget("plan-todos", undefined);
+		}
+	}
+
+	function uniqueToolNames(toolNames: string[]): string[] {
+		return [...new Set(toolNames)];
+	}
+
+	function getPlanModeTools(activeToolNames: string[]): string[] {
+		return uniqueToolNames([
+			...activeToolNames.filter((name) => !PLAN_MODE_DISABLED_TOOLS.has(name)),
+			...PLAN_MODE_TOOLS,
+		]);
+	}
+
+	function getNormalModeTools(activeToolNames: string[]): string[] {
+		return uniqueToolNames([
+			...NORMAL_MODE_TOOLS,
+			...activeToolNames.filter((name) => !PLAN_MANAGED_TOOLS.has(name)),
+		]);
+	}
+
+	function enablePlanModeTools(): void {
+		const previous = toolsBeforePlanMode ?? (toolsBeforePlanMode = pi.getActiveTools());
+		pi.setActiveTools(getPlanModeTools(previous));
+	}
+
+	function restoreNormalModeTools(): void {
+		pi.setActiveTools(toolsBeforePlanMode ?? getNormalModeTools(pi.getActiveTools()));
+		toolsBeforePlanMode = undefined;
+	}
+
+	function persistState(): void {
+		pi.appendEntry("plan-mode", {
+			enabled: planModeEnabled,
+			todos: todoItems,
+			executing: executionMode,
+			toolsBeforePlanMode,
+		});
+	}
+
+	function togglePlanMode(ctx: ExtensionContext): void {
+		planModeEnabled = !planModeEnabled;
+		executionMode = false;
+		todoItems = [];
+		setPlanMode(planModeEnabled);
+
+		if (planModeEnabled) {
+			enablePlanModeTools();
+			ctx.ui.notify("Plan mode enabled. Built-in write tools disabled.");
+		} else {
+			restoreNormalModeTools();
+			ctx.ui.notify("Plan mode disabled. Full access restored.");
+		}
+		updateStatus(ctx);
+		persistState();
+	}
+
+	pi.registerCommand("plan", {
+		description: "Toggle plan mode (read-only exploration)",
+		handler: async (_args, ctx) => togglePlanMode(ctx),
+	});
+
+	pi.registerCommand("todos", {
+		description: "Show current plan todo list",
+		handler: async (_args, ctx) => {
+			if (todoItems.length === 0) {
+				ctx.ui.notify("No todos. Create a plan first with /plan", "info");
+				return;
+			}
+			const list = todoItems.map((item, i) => `${i + 1}. ${item.completed ? "✓" : "○"} ${item.text}`).join("\n");
+			ctx.ui.notify(`Plan Progress:\n${list}`, "info");
+		},
+	});
+
+	pi.registerShortcut(Key.ctrlAlt("p"), {
+		description: "Toggle plan mode",
+		handler: async (ctx) => togglePlanMode(ctx),
+	});
+
+	// Block destructive bash commands in plan mode
+	pi.on("tool_call", async (event) => {
+		if (!planModeEnabled || event.toolName !== "bash") return;
+
+		const command = event.input.command as string;
+		if (!isSafeCommand(command)) {
+			return {
+				block: true,
+				reason: `Plan mode: command blocked (not allowlisted). Use /plan to disable plan mode first.\nCommand: ${command}`,
+			};
+		}
+	});
+
+	// Filter out stale plan mode context when not in plan mode
+	pi.on("context", async (event) => {
+		if (planModeEnabled) return;
+
+		return {
+			messages: event.messages.filter((m) => {
+				const msg = m as AgentMessage & { customType?: string };
+				if (msg.customType === "plan-mode-context") return false;
+				if (msg.role !== "user") return true;
+
+				const content = msg.content;
+				if (typeof content === "string") {
+					return !content.includes("[PLAN MODE ACTIVE]");
+				}
+				if (Array.isArray(content)) {
+					return !content.some(
+						(c) => c.type === "text" && (c as TextContent).text?.includes("[PLAN MODE ACTIVE]"),
+					);
+				}
+				return true;
+			}),
+		};
+	});
+
+	// Inject plan/execution context before agent starts
+	pi.on("before_agent_start", async () => {
+		if (planModeEnabled) {
+			return {
+				message: {
+					customType: "plan-mode-context",
+					content: PLAN_MODE_PROMPT,
+					display: false,
+				},
+			};
+		}
+
+		if (executionMode && todoItems.length > 0) {
+			const remaining = todoItems.filter((t) => !t.completed);
+			const todoList = remaining.map((t) => `${t.step}. ${t.text}`).join("\n");
+			return {
+				message: {
+					customType: "plan-execution-context",
+					content: executionReminder(todoList),
+					display: false,
+				},
+			};
+		}
+	});
+
+	// Track progress after each turn
+	pi.on("turn_end", async (event, ctx) => {
+		if (!executionMode || todoItems.length === 0) return;
+		if (!isAssistantMessage(event.message)) return;
+
+		const text = getTextContent(event.message);
+		if (markCompletedSteps(text, todoItems) > 0) {
+			updateStatus(ctx);
+		}
+		persistState();
+	});
+
+	// Handle plan completion and plan mode UI
+	pi.on("agent_end", async (event, ctx) => {
+		// Check if execution is complete
+		if (executionMode && todoItems.length > 0) {
+			if (todoItems.every((t) => t.completed)) {
+				const completedList = todoItems.map((t) => `~~${t.text}~~`).join("\n");
+				pi.sendMessage(
+					{ customType: "plan-complete", content: `**Plan Complete!** ✓\n\n${completedList}`, display: true },
+					{ triggerTurn: false },
+				);
+				executionMode = false;
+				todoItems = [];
+				updateStatus(ctx);
+				persistState(); // Save cleared state so resume doesn't restore old execution mode
+			}
+			return;
+		}
+
+		if (!planModeEnabled || !ctx.hasUI) return;
+
+		// Extract todos from last assistant message
+		const lastAssistant = [...event.messages].reverse().find(isAssistantMessage);
+		if (lastAssistant) {
+			const extracted = extractTodoItems(getTextContent(lastAssistant));
+			if (extracted.length > 0) {
+				todoItems = extracted;
+			}
+		}
+
+		if (todoItems.length === 0) return;
+		persistState();
+
+		// Show plan steps and prompt for next action
+		const todoListText = todoItems.map((t, i) => `${i + 1}. ☐ ${t.text}`).join("\n");
+		const planTodoListMessage = {
+			customType: "plan-todo-list",
+			content: `**Plan Steps (${todoItems.length}):**\n\n${todoListText}`,
+			display: true,
+		};
+
+		const choice = await ctx.ui.select("Plan mode - what next?", [
+			"Execute the plan (track progress)",
+			"Stay in plan mode",
+			"Refine the plan",
+		]);
+
+		if (choice?.startsWith("Execute")) {
+			const firstTodoItem = todoItems[0];
+			if (!firstTodoItem) return;
+
+			planModeEnabled = false;
+			executionMode = true;
+			setPlanMode(false);
+			restoreNormalModeTools();
+			updateStatus(ctx);
+			persistState();
+
+			const remainingList = todoItems.map((t) => `${t.step}. ${t.text}`).join("\n");
+			const execMessage = executionPrompt(remainingList, firstTodoItem.text);
+			pi.sendMessage(planTodoListMessage, { deliverAs: "followUp" });
+			pi.sendMessage(
+				{ customType: "plan-mode-execute", content: execMessage, display: true },
+				{ triggerTurn: true, deliverAs: "followUp" },
+			);
+		} else if (choice === "Refine the plan") {
+			const refinement = await ctx.ui.editor("Refine the plan:", "");
+			if (refinement?.trim()) {
+				pi.sendMessage(planTodoListMessage, { deliverAs: "followUp" });
+				pi.sendUserMessage(refinement.trim(), { deliverAs: "followUp" });
+			}
+		}
+	});
+
+	// Restore state on session start/resume
+	pi.on("session_start", async (_event, ctx) => {
+		if (pi.getFlag("plan") === true) {
+			planModeEnabled = true;
+		}
+
+		const entries = ctx.sessionManager.getEntries();
+
+		// Restore persisted state
+		const planModeEntry = entries
+			.filter((e: { type: string; customType?: string }) => e.type === "custom" && e.customType === "plan-mode")
+			.pop() as { data?: PlanModeState } | undefined;
+
+		if (planModeEntry?.data) {
+			planModeEnabled = planModeEntry.data.enabled ?? planModeEnabled;
+			todoItems = planModeEntry.data.todos ?? todoItems;
+			executionMode = planModeEntry.data.executing ?? executionMode;
+			toolsBeforePlanMode = planModeEntry.data.toolsBeforePlanMode ?? toolsBeforePlanMode;
+		}
+
+		// On resume: re-scan messages to rebuild completion state
+		// Only scan messages AFTER the last "plan-mode-execute" to avoid picking up [DONE:n] from previous plans
+		const isResume = planModeEntry !== undefined;
+		if (isResume && executionMode && todoItems.length > 0) {
+			// Find the index of the last plan-mode-execute entry (marks when current execution started)
+			let executeIndex = -1;
+			for (let i = entries.length - 1; i >= 0; i--) {
+				const entry = entries[i] as { type: string; customType?: string };
+				if (entry.customType === "plan-mode-execute") {
+					executeIndex = i;
+					break;
+				}
+			}
+
+			// Only scan messages after the execute marker
+			const messages: AssistantMessage[] = [];
+			for (let i = executeIndex + 1; i < entries.length; i++) {
+				const entry = entries[i];
+				if (entry.type === "message" && "message" in entry && isAssistantMessage(entry.message as AgentMessage)) {
+					messages.push(entry.message as AssistantMessage);
+				}
+			}
+			const allText = messages.map(getTextContent).join("\n");
+			markCompletedSteps(allText, todoItems);
+		}
+
+		setPlanMode(planModeEnabled);
+
+		if (planModeEnabled) {
+			enablePlanModeTools();
+		}
+		updateStatus(ctx);
+	});
+}

package/extensions/mode-editor.ts

@@ -0,0 +1,55 @@
+/**
+ * Mode Editor —— 让输入框边框随模式变色（类似 opencode 的模式切换视觉反馈）
+ *
+ * - plan 模式:   半透明橙边框（[ PLAN ] 徽章统一显示在 DeepSeek footer 左侧）
+ * - 正常/执行模式: 主题默认边框
+ *
+ * 通过 src/state.ts（globalThis 共享）与 plan-mode 扩展联动：
+ * /plan、Ctrl+Alt+P、--plan 都会实时反映到输入框上。
+ */
+
+import { CustomEditor, type ExtensionAPI, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import type { EditorTheme, TUI } from "@earendil-works/pi-tui";
+import { isPlanMode, onPlanModeChange, PLAN_BORDER } from "../src/state.ts";
+
+class ModeEditor extends CustomEditor {
+	private lastPlanMode: boolean | null = null;
+	private defaultBorder: (text: string) => string;
+
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		keybindings: KeybindingsManager,
+		private planBorder: (text: string) => string,
+	) {
+		super(tui, theme, keybindings);
+		// 保存默认边框色。注意：pi 的 setCustomEditorComponent 在工厂返回后会把
+		// borderColor 强制覆盖为默认值，因此这里只保存引用，真正的换色在 render()
+		// 每次渲染前重新安装（见 render）。
+		this.defaultBorder = theme.borderColor;
+	}
+
+	render(width: number): string[] {
+		// pi 会覆盖构造时设置的 borderColor，所以每次渲染前重新安装我们的着色函数
+		this.borderColor = isPlanMode() ? this.planBorder : this.defaultBorder;
+
+		const planMode = isPlanMode();
+		if (planMode !== this.lastPlanMode) {
+			this.lastPlanMode = planMode;
+			// 模式翻转时主动请求一次重绘，保证颜色立即生效
+			this.tui.requestRender();
+		}
+
+		return super.render(width);
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+			// 状态变化（含退出 plan）时立即重绘，保证颜色即时生效
+			onPlanModeChange(() => tui.requestRender());
+			return new ModeEditor(tui, theme, keybindings, PLAN_BORDER);
+		});
+	});
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@foolsecret/pi-planmode",
+	"version": "1.1.0",
+	"description": "为 Pi Agent 打造的计划模式 — 只读探索、计划提取与执行进度追踪 | Plan mode for Pi Agent — read-only exploration, plan extraction & execution progress tracking",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"plan-mode",
+		"planning",
+		"agent",
+		"read-only"
+	],
+	"license": "MIT",
+	"author": "Titor-Z",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Titor-Z/pi-planmode.git"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/index.ts",
+			"./extensions/mode-editor.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-agent-core": "*",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}

package/src/prompt.ts

@@ -0,0 +1,47 @@
+/**
+ * Plan mode 注入给模型的提示词常量。
+ * 抽离为独立模块便于调优与审阅，避免散落在扩展主逻辑中。
+ */
+
+/** plan 模式激活时注入的只读探索上下文 */
+export const PLAN_MODE_PROMPT = `[PLAN MODE ACTIVE]
+You are in plan mode - a read-only exploration mode for safe code analysis.
+
+Restrictions:
+- Built-in edit and write tools are disabled
+- Other currently active tools remain available
+- Bash is restricted to an allowlist of read-only commands
+
+Ask clarifying questions using the questionnaire tool.
+Use brave-search skill via bash for web research.
+
+Create a detailed numbered plan under a "Plan:" header:
+
+Plan:
+1. First step description
+2. Second step description
+...
+
+Do NOT attempt to make changes - just describe what you would do.`;
+
+/** 执行模式开始时注入的执行上下文（含剩余步骤清单） */
+export function executionPrompt(remainingList: string, firstStep: string): string {
+	return `Execute the plan.
+
+Remaining steps:
+${remainingList}
+
+Start with: ${firstStep}
+After completing a step, include a [DONE:n] tag in your response.`;
+}
+
+/** 执行过程中每轮注入的剩余步骤提醒 */
+export function executionReminder(todoList: string): string {
+	return `[EXECUTING PLAN - Full tool access enabled]
+
+Remaining steps:
+${todoList}
+
+Execute each step in order.
+After completing a step, include a [DONE:n] tag in your response.`;
+}

package/src/state.ts

@@ -0,0 +1,53 @@
+/**
+ * plan 模式共享状态与样式常量（跨扩展通信）。
+ *
+ * 重要：pi 的扩展加载器用 moduleCache:false 的 jiti 加载扩展，
+ * 同一个模块在不同扩展里会被求值成不同实例。
+ * 因此状态必须挂到 globalThis 上，才能保证 plan-mode 写入、
+ * mode-editor 读取到的是同一个对象。
+ * （常量是字符串/纯函数，各实例自带一份相同值即可，无影响。）
+ */
+
+interface PlanModeSharedState {
+	enabled: boolean;
+	listeners: Set<() => void>;
+}
+
+const GLOBAL_KEY = "__pi_plan_mode_shared_state__";
+
+function getState(): PlanModeSharedState {
+	const g = globalThis as Record<string, unknown>;
+	const existing = g[GLOBAL_KEY] as PlanModeSharedState | undefined;
+	if (existing) return existing;
+	const state: PlanModeSharedState = { enabled: false, listeners: new Set() };
+	g[GLOBAL_KEY] = state;
+	return state;
+}
+
+export function setPlanMode(enabled: boolean): void {
+	const s = getState();
+	s.enabled = enabled;
+	for (const listener of s.listeners) listener();
+}
+
+export function isPlanMode(): boolean {
+	return getState().enabled;
+}
+
+/** 订阅模式变化，返回取消订阅函数。用于触发 UI 重绘。 */
+export function onPlanModeChange(listener: () => void): () => void {
+	const s = getState();
+	s.listeners.add(listener);
+	return () => {
+		s.listeners.delete(listener);
+	};
+}
+
+/** 橙色背景 + 白色字体的 [ PLAN ] 徽章（ANSI 256 色 208 = 橙色，97 = 亮白） */
+export const PLAN_BADGE = "\x1b[48;5;208m\x1b[97m PLAN \x1b[0m";
+
+/**
+ * 半透明橙色边框（dim 橙色，模拟半透明质感；不支持 dim 的终端会回退为亮橙）。
+ * 用在输入框边框上，与 footer 里的实心橙色徽章区分层次。
+ */
+export const PLAN_BORDER = (text: string): string => `\x1b[2m\x1b[38;5;208m${text}\x1b[0m`;

package/src/utils.ts

@@ -0,0 +1,168 @@
+/**
+ * Pure utility functions for plan mode.
+ * Extracted for testability.
+ */
+
+// Destructive commands blocked in plan mode
+const DESTRUCTIVE_PATTERNS = [
+	/\brm\b/i,
+	/\brmdir\b/i,
+	/\bmv\b/i,
+	/\bcp\b/i,
+	/\bmkdir\b/i,
+	/\btouch\b/i,
+	/\bchmod\b/i,
+	/\bchown\b/i,
+	/\bchgrp\b/i,
+	/\bln\b/i,
+	/\btee\b/i,
+	/\btruncate\b/i,
+	/\bdd\b/i,
+	/\bshred\b/i,
+	/(^|[^<])>(?!>)/,
+	/>>/,
+	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
+	/\byarn\s+(add|remove|install|publish)/i,
+	/\bpnpm\s+(add|remove|install|publish)/i,
+	/\bpip\s+(install|uninstall)/i,
+	/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
+	/\bbrew\s+(install|uninstall|upgrade)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bsudo\b/i,
+	/\bsu\b/i,
+	/\bkill\b/i,
+	/\bpkill\b/i,
+	/\bkillall\b/i,
+	/\breboot\b/i,
+	/\bshutdown\b/i,
+	/\bsystemctl\s+(start|stop|restart|enable|disable)/i,
+	/\bservice\s+\S+\s+(start|stop|restart)/i,
+	/\b(vim?|nano|emacs|code|subl)\b/i,
+];
+
+// Safe read-only commands allowed in plan mode
+const SAFE_PATTERNS = [
+	/^\s*cat\b/,
+	/^\s*head\b/,
+	/^\s*tail\b/,
+	/^\s*less\b/,
+	/^\s*more\b/,
+	/^\s*grep\b/,
+	/^\s*find\b/,
+	/^\s*ls\b/,
+	/^\s*pwd\b/,
+	/^\s*echo\b/,
+	/^\s*printf\b/,
+	/^\s*wc\b/,
+	/^\s*sort\b/,
+	/^\s*uniq\b/,
+	/^\s*diff\b/,
+	/^\s*file\b/,
+	/^\s*stat\b/,
+	/^\s*du\b/,
+	/^\s*df\b/,
+	/^\s*tree\b/,
+	/^\s*which\b/,
+	/^\s*whereis\b/,
+	/^\s*type\b/,
+	/^\s*env\b/,
+	/^\s*printenv\b/,
+	/^\s*uname\b/,
+	/^\s*whoami\b/,
+	/^\s*id\b/,
+	/^\s*date\b/,
+	/^\s*cal\b/,
+	/^\s*uptime\b/,
+	/^\s*ps\b/,
+	/^\s*top\b/,
+	/^\s*htop\b/,
+	/^\s*free\b/,
+	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
+	/^\s*git\s+ls-/i,
+	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
+	/^\s*yarn\s+(list|info|why|audit)/i,
+	/^\s*node\s+--version/i,
+	/^\s*python\s+--version/i,
+	/^\s*curl\s/i,
+	/^\s*wget\s+-O\s*-/i,
+	/^\s*jq\b/,
+	/^\s*sed\s+-n/i,
+	/^\s*awk\b/,
+	/^\s*rg\b/,
+	/^\s*fd\b/,
+	/^\s*bat\b/,
+	/^\s*eza\b/,
+];
+
+export function isSafeCommand(command: string): boolean {
+	const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
+	const isSafe = SAFE_PATTERNS.some((p) => p.test(command));
+	return !isDestructive && isSafe;
+}
+
+export interface TodoItem {
+	step: number;
+	text: string;
+	completed: boolean;
+}
+
+export function cleanStepText(text: string): string {
+	let cleaned = text
+		.replace(/\*{1,2}([^*]+)\*{1,2}/g, "$1") // Remove bold/italic
+		.replace(/`([^`]+)`/g, "$1") // Remove code
+		.replace(
+			/^(Use|Run|Execute|Create|Write|Read|Check|Verify|Update|Modify|Add|Remove|Delete|Install)\s+(the\s+)?/i,
+			"",
+		)
+		.replace(/\s+/g, " ")
+		.trim();
+
+	if (cleaned.length > 0) {
+		cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+	}
+	if (cleaned.length > 50) {
+		cleaned = `${cleaned.slice(0, 47)}...`;
+	}
+	return cleaned;
+}
+
+export function extractTodoItems(message: string): TodoItem[] {
+	const items: TodoItem[] = [];
+	const headerMatch = message.match(/\*{0,2}Plan:\*{0,2}\s*\n/i);
+	if (!headerMatch) return items;
+
+	const planSection = message.slice(message.indexOf(headerMatch[0]) + headerMatch[0].length);
+	const numberedPattern = /^\s*(\d+)[.)]\s+\*{0,2}([^*\n]+)/gm;
+
+	for (const match of planSection.matchAll(numberedPattern)) {
+		const text = match[2]
+			.trim()
+			.replace(/\*{1,2}$/, "")
+			.trim();
+		if (text.length > 5 && !text.startsWith("`") && !text.startsWith("/") && !text.startsWith("-")) {
+			const cleaned = cleanStepText(text);
+			if (cleaned.length > 3) {
+				items.push({ step: items.length + 1, text: cleaned, completed: false });
+			}
+		}
+	}
+	return items;
+}
+
+export function extractDoneSteps(message: string): number[] {
+	const steps: number[] = [];
+	for (const match of message.matchAll(/\[DONE:(\d+)\]/gi)) {
+		const step = Number(match[1]);
+		if (Number.isFinite(step)) steps.push(step);
+	}
+	return steps;
+}
+
+export function markCompletedSteps(text: string, items: TodoItem[]): number {
+	const doneSteps = extractDoneSteps(text);
+	for (const step of doneSteps) {
+		const item = items.find((t) => t.step === step);
+		if (item) item.completed = true;
+	}
+	return doneSteps.length;
+}