Claude Code 的计划模式

Plan Mode 解决的不是“让模型更礼貌地先问一句”，而是一个更硬的工程问题：在代码被修改之前，如何先让 Agent 探索代码库、写出可审阅计划、等待用户批准，然后再恢复写入能力。

它真正改变的是权限模式、工具可用性、计划持久化、附件提示词和退出恢复路径。

先看源码入口

读 Plan Mode 不能只看 /plan 命令。真正的核心是：ToolPermissionContext.mode 如何切到 plan，prePlanMode 如何保存和恢复，以及 plan 文件如何从对话里独立出来。

总流程图

这张图里有两个关键状态：

• mode: 'plan'：权限系统进入计划模式，写入类动作被限制。
• prePlanMode：进入 plan 前的模式，用于退出时恢复。

进入 Plan Mode：prePlanMode 是可逆性的关键

Plan Mode 有两条进入路径：

两条路径最终都要准备权限上下文。原文给出的核心函数：

export function prepareContextForPlanMode(
  context: ToolPermissionContext,
): ToolPermissionContext {
  const currentMode = context.mode;
  if (currentMode === 'plan') return context;
  if (feature('TRANSCRIPT_CLASSIFIER')) {
    const planAutoMode = shouldPlanUseAutoMode();
    if (currentMode === 'auto') {
      if (planAutoMode) {
        return { ...context, prePlanMode: 'auto' };
      }
      // ... 关闭 auto mode 并恢复被 auto 剥离的权限
    }
    if (planAutoMode && currentMode !== 'bypassPermissions') {
      autoModeStateModule?.setAutoModeActive(true);
      return {
        ...stripDangerousPermissionsForAutoMode(context),
        prePlanMode: currentMode,
      };
    }
  }
  return { ...context, prePlanMode: currentMode };
}

这段代码证明 Plan Mode 不是一个孤立布尔值。进入时必须保存当前模式：

当前 mode = default / acceptEdits / auto / ...
-> prepareContextForPlanMode()
-> context.prePlanMode = currentMode
-> permission update: mode = plan

prePlanMode 的作用是退出时恢复用户原来的权限意图。否则用户从 acceptEdits 进入 plan，退出后系统不知道应该回 default 还是 acceptEdits。

与 auto mode 的交互

上面代码里 TRANSCRIPT_CLASSIFIER 和 auto 分支说明：Plan Mode 还要处理自动权限模式。进入 plan 时可能剥离危险 allow 规则，退出时还要根据 gate 状态和熔断器决定能不能恢复 auto。

这体现一个边界：Plan Mode 可以暂存权限状态，但不能绕过权限系统的安全降级。

EnterPlanModeTool：模型能请求进入，但不能在任何地方进入

EnterPlanModeTool 的定义里有几个关键约束：

export const EnterPlanModeTool: Tool<InputSchema, Output> = buildTool({
  name: ENTER_PLAN_MODE_TOOL_NAME,
  shouldDefer: true,
  isEnabled() {
    if ((feature('KAIROS') || feature('KAIROS_CHANNELS')) &&
        getAllowedChannels().length > 0) {
      return false;
    }
    return true;
  },
  isConcurrencySafe() { return true },
  isReadOnly() { return true },
  async call(_input, context) {
    if (context.agentId) {
      throw new Error('EnterPlanMode tool cannot be used in agent contexts');
    }
    // ... 执行模式切换
  },
});

这段代码证明了四个设计点：

退出 Plan Mode：审批和权限恢复比进入更复杂

退出由 ExitPlanModeV2Tool 处理。原文把路径分成三类：

退出时最关键的是这段状态恢复逻辑：

context.setAppState(prev => {
  if (prev.toolPermissionContext.mode !== 'plan') return prev;
  setHasExitedPlanMode(true);
  setNeedsPlanModeExitAttachment(true);
  let restoreMode = prev.toolPermissionContext.prePlanMode ?? 'default';

  if (feature('TRANSCRIPT_CLASSIFIER')) {
    if (restoreMode === 'auto' &&
        !(permissionSetupModule?.isAutoModeGateEnabled() ?? false)) {
      restoreMode = 'default';
    }
    // ... auto mode 激活状态同步
  }

  const restoringToAuto = restoreMode === 'auto';
  if (restoringToAuto) {
    baseContext = permissionSetupModule?.stripDangerousPermissionsForAutoMode(baseContext);
  } else if (prev.toolPermissionContext.strippedDangerousRules) {
    baseContext = permissionSetupModule?.restoreDangerousPermissions(baseContext);
  }

  return {
    ...prev,
    toolPermissionContext: {
      ...baseContext,
      mode: restoreMode,
      prePlanMode: undefined,
    },
  };
});

这段代码证明退出不是简单 mode = prePlanMode。它还会：

• 设置 hasExitedPlanMode。
• 设置 needsPlanModeExitAttachment，下一轮注入退出提示。
• 如果原来是 auto 但 auto gate 已关闭，恢复到 default。
• 如果恢复到 auto，继续剥离危险权限。
• 如果不恢复 auto，则恢复此前被剥离的危险规则。
• 清理 prePlanMode。

状态转换防抖：进入和退出附件不能乱发

handlePlanModeTransition() 管的是进入/退出 plan 时的通知标志：

export function handlePlanModeTransition(fromMode: string, toMode: string): void {
  if (toMode === 'plan' && fromMode !== 'plan') {
    STATE.needsPlanModeExitAttachment = false;
  }
  if (fromMode === 'plan' && toMode !== 'plan') {
    STATE.needsPlanModeExitAttachment = true;
  }
}

这段代码证明一个细节：用户可能快速切换模式，系统要避免同时发送“进入 plan”和“退出 plan”的混乱提醒。进入 plan 时清掉待发的退出附件，离开 plan 时再标记需要发送退出附件。

计划文件：把计划从对话里拿出来

Plan Mode 的计划不是只存在聊天记录里，而是写入磁盘。核心路径函数：

export const getPlansDirectory = memoize(function getPlansDirectory(): string {
  const settings = getInitialSettings();
  const settingsDir = settings.plansDirectory;
  let plansPath: string;

  if (settingsDir) {
    const cwd = getCwd();
    const resolved = resolve(cwd, settingsDir);
    if (!resolved.startsWith(cwd + sep) && resolved !== cwd) {
      logError(new Error(`plansDirectory must be within project root: ${settingsDir}`));
      plansPath = join(getClaudeConfigHomeDir(), 'plans');
    } else {
      plansPath = resolved;
    }
  } else {
    plansPath = join(getClaudeConfigHomeDir(), 'plans');
  }
  // ...
});

export function getPlanFilePath(agentId?: AgentId): string {
  const planSlug = getPlanSlug(getSessionId());
  if (!agentId) {
    return join(getPlansDirectory(), `${planSlug}.md`);
  }
  return join(getPlansDirectory(), `${planSlug}-agent-${agentId}.md`);
}

这段代码证明 plan 文件有明确的存储策略：

getPlanSlug() 再生成每个 session 的可读 slug：

export function getPlanSlug(sessionId?: SessionId): string {
  const id = sessionId ?? getSessionId();
  const cache = getPlanSlugCache();
  let slug = cache.get(id);
  if (!slug) {
    const plansDir = getPlansDirectory();
    for (let i = 0; i < MAX_SLUG_RETRIES; i++) {
      slug = generateWordSlug();
      const filePath = join(plansDir, `${slug}.md`);
      if (!getFsImplementation().existsSync(filePath)) {
        break;
      }
    }
    cache.set(id, slug!);
  }
  return slug!;
}

这里不是 UUID，而是 adjective-noun 风格词组 slug。目的很直接：计划文件需要给人看、给人找、给人打开。

/plan 命令：用户入口如何接到权限状态机

用户命令在 commands/plan/plan.tsx：

export async function call(onDone, context, args) {
  const currentMode = appState.toolPermissionContext.mode;

  if (currentMode !== 'plan') {
    handlePlanModeTransition(currentMode, 'plan');
    setAppState(prev => ({
      ...prev,
      toolPermissionContext: applyPermissionUpdate(
        prepareContextForPlanMode(prev.toolPermissionContext),
        { type: 'setMode', mode: 'plan', destination: 'session' },
      ),
    }));
    const description = args.trim();
    if (description && description !== 'open') {
      onDone('Enabled plan mode', { shouldQuery: true });
    } else {
      onDone('Enabled plan mode');
    }
    return null;
  }

  if (argList[0] === 'open') {
    const result = await editFileInEditor(planPath);
    // ...
  }
}

这段代码证明 /plan 命令有几种行为：

用户入口不是绕过状态机，而是同样调用 prepareContextForPlanMode() 和 applyPermissionUpdate()。

计划附件：提示词工作流也要节流

进入 Plan Mode 后，系统会通过附件消息把工作流提醒注入给模型。原文提到三种附件：

核心函数：

function getPlanModeAttachments(messages, toolUseContext) {
  const { turnCount, foundPlanModeAttachment } =
    getPlanModeAttachmentTurnCount(messages);

  if (foundPlanModeAttachment &&
      turnCount < PLAN_MODE_ATTACHMENT_CONFIG.TURNS_BETWEEN_ATTACHMENTS) {
    return [];
  }

  const attachmentCount = countPlanModeAttachmentsSinceLastExit(messages);
  const reminderType = attachmentCount %
    PLAN_MODE_ATTACHMENT_CONFIG.FULL_REMINDER_EVERY_N_ATTACHMENTS === 1
    ? 'full' : 'sparse';

  attachments.push({ type: 'plan_mode', reminderType, isSubAgent, planFilePath, planExists });
  return attachments;
}

这段代码证明附件注入不是每轮都重复完整提示词。它会：

• 检查距离上次 plan 附件的人类轮次数。
• 未达到间隔就跳过。
• 按计数决定注入 full 还是 sparse reminder。
• 附带 planFilePath 和 planExists，让模型知道计划文件状态。

它如何改造 Agent Loop

普通 Agent Loop 往往是：

读一点 -> 改一点 -> 跑一下 -> 再改一点

Plan Mode 把它改成：

进入 plan -> 只读探索 -> 写计划文件 -> ExitPlanMode 提交审批 -> 恢复权限 -> 执行实现

这条链路的关键是把“理解是否正确”的检查点放在写入之前。模型可以先探索和表达计划，但不能把未确认的理解直接落成代码。

状态和数据结构

设计取舍

读源码抓手

1. 先看 prepareContextForPlanMode()，确认 prePlanMode 如何保存。
2. 再看 EnterPlanModeTool，重点看 shouldDefer、agentId 禁止、channels 禁用。
3. 读 ExitPlanModeV2Tool 的 setAppState 恢复逻辑，尤其是 auto gate 熔断。
4. 看 handlePlanModeTransition()，理解进入/退出附件标志如何防抖。
5. 进入 utils/plans.ts，追 getPlansDirectory()、getPlanFilePath()、getPlanSlug()。
6. 看 /plan 命令，确认用户入口如何调用同一套权限状态机。
7. 最后读 getPlanModeAttachments()，理解 plan 工作流提示词如何注入和节流。