Skip to content

Plan Mode 规划模式

版本: v0.29.0 | Claude Code风格 | 安全规划

概述

Plan Mode 提供类似 Claude Code 的安全规划模式,AI 在执行敏感操作前自动进入规划模式,仅使用只读工具进行分析并生成执行计划,经用户审批后才执行写入操作。系统通过 PreToolUse 钩子自动检测高风险操作,支持完整批准、部分批准、计划修改和单步调试执行。

Plan Mode 提供类似 Claude Code 的安全规划模式,让 AI 在执行敏感操作前先制定计划并获得用户批准。

核心特性

  • 📋 安全规划模式: AI 执行敏感操作前自动进入规划模式,生成执行计划供用户审批
  • 🔒 工具分级限制: 规划模式下仅允许只读工具(Read/Glob/Grep),写入工具需审批后执行
  • 灵活审批流: 支持完整批准、部分批准、拒绝和计划修改,逐步或自动执行
  • 🪝 Hooks 集成: 通过 PreToolUse 钩子自动检测高风险操作,强制进入规划模式
  • ⏱️ 计划生命周期: 支持计划过期、自动保存、历史查询和单步调试执行

系统架构

用户请求


┌──────────────────┐
│  风险评估引擎     │──── 低风险 ──▶ 直接执行
│  (PreToolUse钩子) │
└────────┬─────────┘
         │ 高风险

┌──────────────────┐
│  规划模式引擎     │
│  (只读工具分析)   │
└────────┬─────────┘


┌──────────────────┐    ┌──────────────┐
│  执行计划生成     │───▶│  用户审批界面  │
│  (步骤/风险/依赖) │    │ (批准/拒绝/改) │
└──────────────────┘    └──────┬───────┘
                               │ 批准

                        ┌──────────────┐
                        │  计划执行器   │
                        │ (逐步/自动)   │
                        └──────────────┘

工作原理

模式切换

普通模式 ←→ 规划模式

普通模式: AI 可以直接执行工具
规划模式: AI 只能读取和分析,执行操作需要审批

规划模式流程

1. 进入规划模式

2. AI 分析任务,只使用只读工具

3. 生成执行计划

4. 用户审批计划

5. 批准后执行(或修改计划)

6. 退出规划模式

进入规划模式

自动进入

某些情况下系统自动进入规划模式:

  • 检测到高风险操作
  • 配置了需要审批的工具
  • 用户设置了强制规划模式

手动进入

javascript
// 通过命令进入
/plan

// 通过 API 进入
await planMode.enter({
  task: '重构认证模块',
  reason: '涉及多文件修改'
})

规划模式工具限制

允许的工具(只读)

工具说明
Read读取文件
Glob搜索文件
Grep搜索内容
WebFetch获取网页
WebSearch搜索网络

阻止的工具(写入)

工具说明
Write写入文件
Edit编辑文件
Bash执行命令
NotebookEdit编辑笔记本

配置工具限制

javascript
// 自定义允许的工具
planMode.configure({
  allowedTools: ["Read", "Glob", "Grep", "WebFetch"],
  blockedTools: ["Write", "Edit", "Bash", "NotebookEdit"],
});

生成计划

计划结构

javascript
{
  "id": "plan-123",
  "task": "重构认证模块",
  "status": "pending",  // pending, approved, rejected, partial
  "createdAt": "2026-02-11T10:00:00Z",

  "analysis": {
    "summary": "需要重构 3 个文件,添加 1 个新文件",
    "risks": ["可能影响现有登录流程"],
    "dependencies": ["auth-service", "user-model"]
  },

  "steps": [
    {
      "id": "step-1",
      "description": "备份现有认证模块",
      "tool": "Bash",
      "params": { "command": "cp -r src/auth src/auth.bak" },
      "status": "pending"
    },
    {
      "id": "step-2",
      "description": "更新认证逻辑",
      "tool": "Edit",
      "params": { "file_path": "src/auth/index.js", "..." },
      "status": "pending"
    },
    // ...更多步骤
  ]
}

自动生成计划

javascript
// AI 分析任务并生成计划
const plan = await planMode.generatePlan({
  task: "添加用户头像功能",
  context: "当前使用 Gravatar,需要支持自定义上传",
});

console.log("计划步骤:", plan.steps.length);
console.log("预计修改文件:", plan.analysis.files);

审批工作流

完整批准

javascript
// 批准整个计划
await planMode.approve(planId, {
  comment: "计划看起来没问题",
});

// 批准后自动执行

部分批准

javascript
// 只批准部分步骤
await planMode.approvePartial(planId, {
  approvedSteps: ["step-1", "step-2"],
  rejectedSteps: ["step-3"],
  comment: "step-3 需要修改",
});

拒绝计划

javascript
// 拒绝计划
await planMode.reject(planId, {
  reason: "需要更多分析",
  feedback: "请先确认现有测试覆盖率",
});

修改计划

javascript
// 修改计划中的步骤
await planMode.modifyStep(planId, 'step-2', {
  description: '更新为使用新的 API',
  params: { ... }
})

// 添加步骤
await planMode.addStep(planId, {
  afterStep: 'step-2',
  description: '添加单元测试',
  tool: 'Write',
  params: { ... }
})

// 删除步骤
await planMode.removeStep(planId, 'step-3')

执行计划

自动执行

javascript
// 批准后自动执行所有步骤
await planMode.execute(planId);

单步执行

javascript
// 逐步执行,每步确认
await planMode.executeStep(planId, 'step-1')

// 执行结果
{
  "stepId": "step-1",
  "status": "completed",
  "result": { ... },
  "duration": 150
}

暂停和恢复

javascript
// 暂停执行
await planMode.pause(planId);

// 恢复执行
await planMode.resume(planId);

Hooks 集成

Plan Mode 与 Hooks 系统集成:

PreToolUse 钩子

javascript
// .chainlesschain/hooks/plan-mode-check.js
module.exports = {
  event: "PreToolUse",
  priority: 10,

  async handler(context) {
    const { tool, params } = context;

    // 检查是否需要进入规划模式
    if (isHighRiskOperation(tool, params)) {
      const inPlanMode = await planMode.isActive();

      if (!inPlanMode) {
        // 阻止操作,提示进入规划模式
        return {
          proceed: false,
          error: "此操作需要在规划模式下执行",
          suggestion: "使用 /plan 进入规划模式",
        };
      }
    }

    return { proceed: true };
  },
};

配置选项

全局配置

javascript
{
  "planMode": {
    // 是否默认启用
    "defaultEnabled": false,

    // 强制需要规划的操作
    "requirePlanFor": [
      { "tool": "Bash", "pattern": "rm -rf" },
      { "tool": "Edit", "pathPattern": "src/core/**" }
    ],

    // 计划过期时间
    "planExpiration": 24 * 60 * 60 * 1000,  // 24小时

    // 自动保存计划
    "autoSave": true
  }
}

IPC 处理器

Plan Mode 提供 14 个 IPC 处理器:

处理器功能
planMode:enter进入规划模式
planMode:exit退出规划模式
planMode:isActive检查是否在规划模式
planMode:generatePlan生成计划
planMode:getPlan获取计划
planMode:approve批准计划
planMode:approvePartial部分批准
planMode:reject拒绝计划
planMode:modify修改计划
planMode:execute执行计划
planMode:executeStep执行单步
planMode:pause暂停执行
planMode:resume恢复执行
planMode:getHistory获取历史计划

使用场景

1. 大型重构

用户: 帮我重构整个认证模块,使用 JWT 替换 Session

AI: 这是一个较大的改动,让我进入规划模式分析...

[自动进入规划模式]

AI: 我已经分析了代码库,生成了以下执行计划:

1. 备份现有认证模块
2. 安装 JWT 依赖 (jsonwebtoken)
3. 创建 JWT 工具模块
4. 修改登录逻辑
5. 修改验证中间件
6. 更新相关测试
7. 更新文档

预计修改 8 个文件,风险评估:中等

是否批准执行?

2. 数据库迁移

用户: 执行数据库迁移脚本

AI: 数据库迁移是敏感操作,需要在规划模式下进行。

[进入规划模式]

执行计划:
1. 备份当前数据库
2. 执行迁移脚本
3. 验证数据完整性
4. 回滚准备(如果失败)

请确认是否继续?

最佳实践

1. 适时使用规划模式

javascript
// 配置需要规划的场景
{
  "requirePlanFor": [
    { "tool": "Bash", "pattern": "npm publish" },
    { "tool": "Bash", "pattern": "git push" },
    { "tool": "Edit", "pathPattern": "**/config/**" }
  ]
}

2. 详细的计划描述

javascript
// 好的计划步骤描述
{
  "description": "修改 AuthService.login() 方法,添加 JWT token 生成逻辑",
  "changes": [
    "添加 generateToken() 方法",
    "修改返回值包含 token",
    "添加 token 过期时间配置"
  ]
}

3. 保存计划历史

javascript
// 查看历史计划
const history = await planMode.getHistory({
  limit: 10,
  status: "completed",
});

下一步


关键文件

文件职责
src/main/ai-engine/plan-mode/plan-mode-manager.jsPlan Mode 核心引擎
src/main/ai-engine/plan-mode/plan-mode-ipc.jsIPC 处理器(14 个)
src/main/hooks/plan-mode-check.jsPreToolUse 风险检测钩子
src/renderer/stores/planMode.tsPinia 规划模式状态管理

使用示例

CLI 规划模式

bash
# 进入 Agent 模式(支持 Plan Mode)
chainlesschain agent

# 在对话中使用 /plan 命令
> /plan 重构用户认证模块,使用 JWT 替换 Session

桌面端规划操作

javascript
// 进入规划模式
await planMode.enter({
  task: '迁移数据库从 SQLite 到 PostgreSQL',
  reason: '涉及多表结构变更和数据迁移'
});

// 生成执行计划
const plan = await planMode.generatePlan({
  task: '添加用户头像上传功能',
  context: '需要图片压缩、存储和CDN分发'
});

// 部分批准(只批准安全的步骤)
await planMode.approvePartial(planId, {
  approvedSteps: ['step-1', 'step-2'],
  rejectedSteps: ['step-3'],
  comment: 'step-3 的删除操作需要修改'
});

// 单步执行并确认
await planMode.executeStep(planId, 'step-1');

故障排查

规划模式未自动触发

  • 风险检测规则: 确认 requirePlanFor 配置覆盖了目标操作模式
  • Hooks 未注册: 检查 PreToolUse 钩子是否正确加载和启用
  • 模式冲突: 确认当前未处于另一个活跃的规划模式会话中

计划生成失败

  • LLM 不可用: 计划生成依赖 AI 分析,确认本地 LLM 服务正常运行
  • 上下文不足: 提供更详细的任务描述和上下文信息提高计划质量
  • 工具限制: 规划模式下仅允许只读工具,确认分析所需文件可访问

计划执行中断

  • 步骤依赖失败: 前置步骤失败会阻塞后续步骤,检查错误日志
  • 计划已过期: 超过 planExpiration(默认 24 小时)的计划需重新生成
  • 权限不足: 某些操作可能需要额外权限,检查当前用户的角色权限

审批流程异常

  • 审批超时: 默认 24 小时超时,超时后需重新提交审批请求
  • 部分批准冲突: 被拒绝的步骤如有依赖关系,后续步骤可能无法执行
  • 并发修改: 多人同时修改计划可能导致冲突,建议使用版本锁定

配置参考

完整 Plan Mode 配置项

javascript
// .chainlesschain/config.json
{
  "planMode": {
    // 是否默认启用规划模式
    "defaultEnabled": false,

    // 自动触发规划模式的高风险操作规则
    "requirePlanFor": [
      { "tool": "Bash", "pattern": "rm -rf" },
      { "tool": "Bash", "pattern": "npm publish" },
      { "tool": "Bash", "pattern": "git push" },
      { "tool": "Bash", "pattern": "docker rm" },
      { "tool": "Edit", "pathPattern": "src/core/**" },
      { "tool": "Edit", "pathPattern": "**/config/**" },
      { "tool": "Write", "pathPattern": "**/migrations/**" }
    ],

    // 规划模式下允许的只读工具(白名单)
    "allowedTools": ["Read", "Glob", "Grep", "WebFetch", "WebSearch"],

    // 规划模式下阻止的写入工具(黑名单)
    "blockedTools": ["Write", "Edit", "Bash", "NotebookEdit"],

    // 计划过期时间(毫秒),默认 24 小时
    "planExpiration": 86400000,

    // 是否自动保存计划到磁盘
    "autoSave": true,

    // 计划保存目录(相对于 .chainlesschain/)
    "planStorageDir": "plans/",

    // 审批超时时间(毫秒),超时后计划自动失效,默认 24 小时
    "approvalTimeout": 86400000,

    // 单步执行模式下是否在每步后暂停等待确认
    "stepwiseConfirm": false,

    // 是否在执行计划前自动插入备份步骤
    "autoInsertBackup": false,

    // 计划历史保留条数(0 = 不限)
    "historyLimit": 50
  }
}

ApprovalGate 策略配置

javascript
// 与 session-core ApprovalGate 集成的策略配置
{
  "approvalGate": {
    // strict: 所有写操作均需审批
    // trusted: 低风险写操作自动通过,高风险需审批
    // autopilot: 全部自动通过(仅限受信任环境)
    "policy": "trusted",

    // 高风险阈值(riskLevel >= threshold 触发强制审批)
    "riskThreshold": "high",

    // 是否将审批决策持久化到 approval-policies.json
    "persistPolicy": true
  }
}

工具风险级别映射

javascript
// plan-mode-manager.js — 内置风险级别映射
const TOOL_RISK_LEVELS = {
  // 只读工具 — 规划模式默认允许
  Read:        { riskLevel: "low",    availableInPlanMode: true  },
  Glob:        { riskLevel: "low",    availableInPlanMode: true  },
  Grep:        { riskLevel: "low",    availableInPlanMode: true  },
  WebFetch:    { riskLevel: "low",    availableInPlanMode: true  },
  WebSearch:   { riskLevel: "low",    availableInPlanMode: true  },

  // 写入工具 — 规划模式默认阻止,审批后可执行
  Write:       { riskLevel: "medium", availableInPlanMode: false, requiresPlanApproval: true },
  Edit:        { riskLevel: "medium", availableInPlanMode: false, requiresPlanApproval: true },
  Bash:        { riskLevel: "high",   availableInPlanMode: false, requiresPlanApproval: true },
  NotebookEdit:{ riskLevel: "medium", availableInPlanMode: false, requiresPlanApproval: true },
};

性能指标

计划生成耗时

任务规模涉及文件数本地 LLM (7B)云端 LLM (Claude 3 Sonnet)云端 LLM (Claude 3 Opus)
小型任务1–5 个~3 s~1.5 s~2 s
中型任务6–20 个~8 s~3 s~4 s
大型任务21–50 个~18 s~6 s~8 s
超大任务50+ 个~35 s~12 s~15 s

本地 LLM 耗时受硬件(GPU/CPU)影响较大;云端 LLM 受网络延迟影响。

审批响应延迟

操作P50 延迟P95 延迟说明
planMode:enter12 ms45 msIPC 进入规划模式
planMode:generatePlan变量变量取决于 LLM 响应和文件扫描量
planMode:approve8 ms22 ms写入审批记录 + 状态变更
planMode:approvePartial10 ms30 ms部分步骤标记 + 依赖检查
planMode:reject6 ms18 ms记录拒绝原因 + 状态归档
planMode:execute15 ms50 ms首步骤前初始化 + 权限校验
planMode:executeStep5 ms20 ms单步调度延迟(不含工具执行)
planMode:getHistory3 ms12 ms磁盘读取 + 反序列化

内存占用

场景增量内存占用说明
规划模式空闲~2 MB状态管理 + 钩子监听
单个活跃计划~5–15 MB计划 JSON + 上下文缓存
10 个历史计划~30 MB磁盘序列化,内存中仅索引
PreToolUse 钩子< 1 ms/次每次工具调用前的风险检测开销

测试覆盖率

单元测试

测试文件测试数覆盖模块
tests/unit/ai-engine/plan-mode-manager.test.js42PlanModeManager 核心逻辑、计划 CRUD、状态机
tests/unit/ai-engine/plan-mode-ipc.test.js2814 个 IPC 处理器、参数校验、错误处理
tests/unit/ai-engine/plan-approval-gate.test.js31ApprovalGate 策略合流、strict/trusted/autopilot 三模式
tests/unit/hooks/plan-mode-check.test.js18PreToolUse 钩子风险检测、高风险操作模式匹配
packages/cli/src/lib/__tests__/interactive-planner.test.js24InteractivePlanner LLM 驱动计划生成、步骤推荐
packages/cli/src/lib/__tests__/slot-filler.test.js19SlotFiller 槽位识别、上下文推断、终端/WS 双模

集成测试

测试文件测试数覆盖场景
tests/integration/plan-mode-flow.test.js16完整规划→审批→执行端到端流程
tests/integration/plan-mode-hooks.test.js12PreToolUse 钩子与规划模式联动
tests/integration/plan-mode-partial-approve.test.js10部分批准、依赖步骤跳过、恢复执行

Pinia Store 测试

测试文件测试数覆盖模块
src/renderer/stores/__tests__/planMode.test.ts35Pinia planMode store、状态同步、IPC 响应处理

测试总计

类别文件数测试用例数
单元测试6162
集成测试338
Store 测试135
合计10235

安全考虑

操作安全

  • 高风险操作(rm -rf、核心配置修改等)强制进入规划模式,必须人工审批
  • 规划模式下 AI 仅能使用 只读工具(Read/Glob/Grep),无法执行写入操作
  • 所有计划步骤在执行前需要显式批准,支持逐步执行和随时暂停

审批安全

  • 计划审批记录保存在审计日志中,包含审批人、时间、评论等完整信息
  • 支持部分批准机制,敏感步骤可单独审查,降低批量审批风险
  • 计划过期自动失效,防止过时的计划被误执行

回滚保护

  • 计划执行前建议包含备份步骤,支持在执行失败时快速回滚
  • 单步执行模式允许在每步完成后检查结果,发现问题及时暂停
  • 执行历史记录完整保留,支持事后审查和问题定位

钩子安全

  • PreToolUse 钩子以最高优先级运行,确保风险检测不被绕过
  • 钩子配置文件存储在 .chainlesschain/hooks/ 中,受文件权限保护
  • 自定义钩子脚本需要人工审查,防止恶意钩子绕过安全检查

CLI SlotFiller 集成 (v0.41.0)

从桌面版 slot-filler.js 移植到 CLI,支持终端和 WebSocket 两种交互模式。

SlotFiller 概述

当 AI 检测到用户意图但缺少关键参数时,SlotFiller 自动向用户提问收集缺失信息:

用户: "创建一个 API 文件"

SlotFiller 检测: create_file 意图缺少 fileType, path

尝试上下文推断: 项目是 Node.js → fileType = "javascript"

仍缺 path → 通过 InteractionAdapter 向用户提问

终端模式: readline 提问
WebSocket模式: 发送 question 消息,等待 session-answer

槽位定义

javascript
REQUIRED_SLOTS = {
  create_file: ['fileType', 'path'],
  edit_file: ['target'],
  deploy: ['platform'],
  refactor: ['scope'],
  test: ['target'],
  analyze: ['target'],
}

使用方式

bash
# 在 Agent REPL 中,SlotFiller 自动工作
chainlesschain agent

> /plan interactive 重构用户认证模块
# SlotFiller 检测缺少参数,自动提问:
# ? 重构范围是什么? (全部/登录模块/注册模块)
# ? 使用什么认证方案? (JWT/Session/OAuth)

关键文件

文件职责
packages/cli/src/lib/slot-filler.jsSlotFiller 核心引擎
packages/cli/src/lib/interaction-adapter.js交互抽象层(终端/WebSocket)

CLI InteractivePlanner (v0.41.0)

从桌面版 task-planner-interactive.js 简化移植,支持 LLM 驱动的计划生成。

交互式规划流程

用户请求 → LLM 分析 → 生成计划 → 推荐技能 → 用户确认
    ↓           ↓           ↓           ↓          ↓
 /plan       分析上下文    步骤列表    匹配Skills   confirm/
interactive   + 代码库    + 风险评估   + 解释原因   adjust/
                                                  regenerate/
                                                  cancel

CLI 命令

bash
chainlesschain agent

# 进入交互式规划
> /plan interactive 添加用户头像上传功能

# 系统生成计划:
#   Plan: 用户头像上传功能
#   需要图片压缩、存储和 CDN 分发
#
#   1. 安装 sharp 依赖 [run_shell]
#   2. 创建 upload 中间件 [write_file]
#   3. 添加图片压缩逻辑 [write_file]
#   4. 更新路由 [edit_file]
#   5. 编写测试 [write_file]
#
#   Recommended skills:
#     - code-review: 代码审查
#     - unit-test: 单元测试生成

> /plan interactive:confirm    # 确认执行
> /plan interactive:cancel     # 取消
> /plan interactive:regenerate # 重新生成

关键文件

文件职责
packages/cli/src/lib/interactive-planner.js交互式计划生成器
packages/cli/src/lib/slot-filler.js参数槽填充(计划前信息收集)

相关文档


先规划,再执行,更安全 📋

基于 MIT 许可发布