foliko 2.0.19 → 2.0.20

package/plugins/core/planner/index.js

@@ -0,0 +1,926 @@
+'use strict';
+
+/**
+ * Planner Plugin
+ * 计划模式：为复杂/可中断任务创建持久化步骤、记录执行状态、重启可继续
+ *
+ * 触发方式：
+ * 1. LLM 自主判断：PROMPT.md 注入 system prompt 引导
+ * 2. 显式命令：WeChat /plan <task>、/plan_list、/plan_continue <id>、/plan_show <id>
+ *
+ * 文件结构：每个计划一个 .md 文件，存于 .foliko/plans/
+ *   - frontmatter: 计划元数据
+ *   - 正文: 任务描述 + 步骤清单 (GFM checkbox) + 执行日志
+ */
+
+const { Plugin } = require('../../../src/plugin/base');
+const { logger } = require('../../../src/common/logger');
+const { z } = require('zod');
+const fs = require('fs');
+const path = require('path');
+const { randomUUID } = require('crypto');
+
+const log = logger.child('Planner');
+
+// ============================================================
+// 持久化层：原子写（先 .tmp 再 rename）
+// 复用 plugins/core/scheduler/index.js:60-86 TaskStore 模式
+// ============================================================
+class PlanStore {
+  constructor(dir) {
+    this._dir = dir;
+    this._ensureDir();
+  }
+
+  _ensureDir() {
+    if (!fs.existsSync(this._dir)) {
+      fs.mkdirSync(this._dir, { recursive: true });
+    }
+  }
+
+  _toFilePath(planId) {
+    return path.join(this._dir, `${planId}.md`);
+  }
+
+  /**
+   * 原子写：先写 .tmp 再 rename（同卷下原子替换）
+   * 避免进程在 writeFileSync 中途崩溃导致 .md 半残
+   */
+  save(plan) {
+    const finalPath = this._toFilePath(plan.planId);
+    const tmpPath = finalPath + '.tmp';
+    try {
+      const md = PlanSerializer.toMarkdown(plan);
+      fs.writeFileSync(tmpPath, md, 'utf-8');
+      fs.renameSync(tmpPath, finalPath);
+    } catch (err) {
+      log.error(`[PlanStore] 保存 ${plan.planId} 失败:`, err.message);
+      try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+      throw err;
+    }
+  }
+
+  load(planId) {
+    const fp = this._toFilePath(planId);
+    if (!fs.existsSync(fp)) return null;
+    try {
+      return PlanSerializer.fromMarkdown(fs.readFileSync(fp, 'utf-8'));
+    } catch (err) {
+      log.error(`[PlanStore] 加载 ${planId} 失败:`, err.message);
+      return null;
+    }
+  }
+
+  list({ status, limit } = {}) {
+    if (!fs.existsSync(this._dir)) return [];
+    const files = fs.readdirSync(this._dir).filter(f => f.endsWith('.md') && !f.endsWith('.tmp'));
+    const plans = [];
+    for (const f of files) {
+      try {
+        const plan = PlanSerializer.fromMarkdown(
+          fs.readFileSync(path.join(this._dir, f), 'utf-8')
+        );
+        if (status && plan.status !== status) continue;
+        plans.push(plan);
+      } catch (err) {
+        log.warn(`[PlanStore] 跳过无效文件 ${f}: ${err.message}`);
+      }
+    }
+    plans.sort((a, b) => new Date(b.updatedAt || 0) - new Date(a.updatedAt || 0));
+    return limit ? plans.slice(0, limit) : plans;
+  }
+
+  delete(planId) {
+    const fp = this._toFilePath(planId);
+    let ok = false;
+    if (fs.existsSync(fp)) {
+      fs.unlinkSync(fp);
+      ok = true;
+    }
+    // 清理残留 .tmp
+    try { fs.unlinkSync(fp + '.tmp'); } catch { /* ignore */ }
+    return ok;
+  }
+
+  exists(planId) {
+    return fs.existsSync(this._toFilePath(planId));
+  }
+}
+
+// ============================================================
+// 序列化：手写 frontmatter 解析（不引入 gray-matter）
+// 理由：格式固定无需泛化、减少 supply chain 风险
+// ============================================================
+class PlanSerializer {
+  static CHECKBOX_MAP = {
+    completed: '[x]',
+    in_progress: '[-]',
+    failed: '[!]',
+    skipped: '[~]',
+    pending: '[ ]',
+  };
+
+  static CHECKBOX_REVERSE = {
+    'x': 'completed',
+    '-': 'in_progress',
+    '!': 'failed',
+    '~': 'skipped',
+    ' ': 'pending',
+  };
+
+  static _escapeYaml(s) {
+    if (s == null) return '';
+    return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  }
+
+  /**
+   * 从 markdown 中提取指定 step 的日志段
+   * 日志格式：### Step N (尝试 M) - ...，段间用 --- 或下一个 Step 标题分隔
+   * @param {string} md 完整 markdown
+   * @param {number} stepIndex 0-based
+   * @returns {string|null}
+   */
+  static _extractStepLog(md, stepIndex) {
+    if (!md) return null;
+    const stepNum = stepIndex + 1;
+    // 匹配 ### Step N (尝试 M) - ... 到下一个 ### Step N+1 或 ## 📋 或文件结尾
+    const re = new RegExp(
+      `### Step ${stepNum}[\\s\\S]*?(?=### Step ${stepNum + 1}\\b|## 📋|## 执行日志结束|$)`,
+      'm'
+    );
+    // 上面匹配整个日志节；我们只需要从 "## 执行日志" 之后到下一个分隔符的内容
+    const logsStart = md.indexOf('## 执行日志');
+    if (logsStart === -1) return null;
+    const logsBlock = md.slice(logsStart);
+    const stepRe = new RegExp(
+      `### Step ${stepNum}\\b[\\s\\S]*?(?=### Step ${stepNum + 1}\\b|## 📋|## 完成总结|$)`
+    );
+    const match = logsBlock.match(stepRe);
+    return match ? match[0] : null;
+  }
+
+  static toMarkdown(plan) {
+    const fm = [
+      '---',
+      `planId: "${PlanSerializer._escapeYaml(plan.planId)}"`,
+      `title: "${PlanSerializer._escapeYaml(plan.title)}"`,
+      `status: "${plan.status || 'in_progress'}"`,
+      `totalSteps: ${plan.totalSteps || 0}`,
+      `completedSteps: ${plan.completedSteps || 0}`,
+      `failedSteps: ${plan.failedSteps || 0}`,
+      `createdAt: "${plan.createdAt || ''}"`,
+      `updatedAt: "${plan.updatedAt || ''}"`,
+      plan.sessionId ? `sessionId: "${PlanSerializer._escapeYaml(plan.sessionId)}"` : null,
+      '---',
+    ].filter(Boolean).join('\n');
+
+    const stepList = (plan.steps || []).map((s, i) => {
+      const box = PlanSerializer.CHECKBOX_MAP[s.status] || '[ ]';
+      const line = `- ${box} ${i + 1}. ${s.name || ''}${s.description ? ` — ${s.description}` : ''}`;
+      return line;
+    }).join('\n');
+
+    const logs = (plan.steps || [])
+      .filter(s => s.log)
+      .map(s => s.log)
+      .join('\n\n') || '_暂无日志_';
+
+    return [
+      fm,
+      '',
+      `# ${plan.title || '(无标题)'}`,
+      '',
+      `## 任务描述`,
+      '',
+      plan.task || '(无)',
+      '',
+      `## 计划步骤`,
+      '',
+      stepList,
+      '',
+      `## 执行日志`,
+      '',
+      logs,
+      '',
+    ].join('\n');
+  }
+
+  static fromMarkdown(md) {
+    if (!md || !md.startsWith('---\n')) {
+      throw new Error('无效的计划格式：缺少 frontmatter');
+    }
+    const fmEnd = md.indexOf('\n---', 4);
+    if (fmEnd === -1) {
+      throw new Error('无效的计划格式：frontmatter 未闭合');
+    }
+    const fmBlock = md.slice(4, fmEnd);
+    const meta = {};
+    for (const line of fmBlock.split('\n')) {
+      const m = line.match(/^([\w-]+):\s*(.*)$/);
+      if (!m) continue;
+      let val = m[2];
+      if (val.startsWith('"') && val.endsWith('"')) {
+        val = val.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+      }
+      if (['totalSteps', 'completedSteps', 'failedSteps'].includes(m[1])) {
+        val = parseInt(val, 10) || 0;
+      }
+      meta[m[1]] = val;
+    }
+
+    // 解析步骤清单：- [x] 1. 名称 — 描述
+    const steps = [];
+    const stepRegex = /^- \[(.)\] (\d+)\. (.+?)(?: — (.+))?$/gm;
+    let match;
+    while ((match = stepRegex.exec(md)) !== null) {
+      steps.push({
+        index: Number(match[2]) - 1,
+        name: match[3],
+        description: match[4] || null,
+        status: PlanSerializer.CHECKBOX_REVERSE[match[1]] || 'pending',
+        attempts: 0,
+        log: null,
+      });
+    }
+
+    // 从日志的"### Step N (尝试 M) - ..."模式恢复 attempts 和 log
+    for (const step of steps) {
+      const logText = PlanSerializer._extractStepLog(md, step.index);
+      if (logText) {
+        step.log = logText;
+        const attemptsMatches = logText.match(/尝试 (\d+)/g) || [];
+        const nums = attemptsMatches.map(s => parseInt(s.match(/\d+/)[0], 10));
+        step.attempts = nums.length ? Math.max(...nums) : 0;
+      }
+    }
+
+    return {
+      planId: meta.planId,
+      title: meta.title,
+      task: '',
+      status: meta.status || 'in_progress',
+      totalSteps: meta.totalSteps || steps.length,
+      completedSteps: meta.completedSteps || 0,
+      failedSteps: meta.failedSteps || 0,
+      createdAt: meta.createdAt,
+      updatedAt: meta.updatedAt,
+      sessionId: meta.sessionId || null,
+      steps,
+    };
+  }
+}
+
+// ============================================================
+// 主插件类
+// ============================================================
+class PlannerPlugin extends Plugin {
+  constructor(config = {}) {
+    super();
+    this.name = 'planner';
+    this.version = '1.0.0';
+    this.description = '计划模式：为复杂/可中断任务创建持久化步骤、记录执行状态、重启可继续';
+    this.priority = 50;
+    this.enabled = true;
+    this.system = false;
+    this.config = {
+      dir: config.dir || '.foliko/plans',
+      autoPlanThreshold: config.autoPlanThreshold || 3,
+    };
+    this._framework = null;
+    this._store = null;
+    this._index = new Map();   // planId → in-memory plan
+  }
+
+  // === 声明式 prompt 注入（基类自动注册/清理） ===
+  // 参考 src/plugin/base.js:811-842 _autoRegisterPrompts
+  // 文件路径相对插件目录，由 base.js:850-880 _createFilePromptProvider 解析
+  prompts = [
+    {
+      name: 'planner-mode',
+      file: './PROMPT.md',
+      scope: 'global',
+      priority: 70,
+      description: '计划模式触发条件与工作流',
+    },
+    // ★ 关键：动态状态提示。每次 LLM 调用重新渲染，
+    //   防止 messages 被压缩/截断后 LLM 忘记计划进度。
+    //   priority 58 排在 CAPABILITIES (60) 之前，确保显眼。
+    {
+      name: 'planner-status',
+      scope: 'global',
+      priority: 58,
+      description: '当前活跃计划状态摘要（每次 LLM 调用重渲染）',
+      provider() {
+        return this._buildPlanStatusReminder();
+      },
+    },
+  ];
+
+  /**
+   * 失效 planner-status 缓存，让下次 LLM 调用看到最新状态
+   */
+  _invalidatePlanStatusPrompt() {
+    try {
+      this._framework?.prompts?.invalidate?.('planner', 'planner-status');
+    } catch { /* ignore */ }
+  }
+
+  /**
+   * 渲染当前活跃计划的状态摘要（注入 system prompt）
+   * - 只显示当前 session 的 in_progress 计划
+   * - 即使 messages 被压缩/截断，LLM 仍能从此处读到"执行到第几步"
+   * @returns {string} 摘要文本（空字符串表示无活跃计划）
+   */
+  _buildPlanStatusReminder() {
+    if (!this._framework || !this._store) return '';
+
+    // 从多个来源尝试获取 sessionId
+    const sessionId =
+      this._framework.getCurrentSessionId?.() ||
+      this._framework.getExecutionContext?.()?.sessionId ||
+      null;
+    if (!sessionId) return '';
+
+    // ★ 关键：通过 _loadPlan 读（内存优先）而非直接 _store.list（只读磁盘），
+    //   这样能拿到运行期字段（completedAt、attempts、log 等），
+    //   这些字段在 markdown 序列化时被丢弃，必须从内存取。
+    let plans = [];
+    try {
+      const files = fs.readdirSync(this._store._dir)
+        .filter(f => f.endsWith('.md') && !f.endsWith('.tmp'));
+      for (const f of files) {
+        const planId = f.replace(/\.md$/, '');
+        try {
+          const plan = this._loadPlan(planId);
+          if (plan && plan.status === 'in_progress') plans.push(plan);
+        } catch { /* skip */ }
+      }
+      plans.sort((a, b) => new Date(b.updatedAt || 0) - new Date(a.updatedAt || 0));
+    } catch { return ''; }
+    const myPlans = plans.filter(p => p.sessionId === sessionId);
+    if (myPlans.length === 0) return '';
+
+    const lines = ['## 📋 当前活跃计划', ''];
+    for (const plan of myPlans.slice(0, 3)) {
+      const inProgressStep = plan.steps.find(s => s.status === 'in_progress');
+      const lastFinished = plan.steps
+        .filter(s => s.completedAt)
+        .sort((a, b) => new Date(b.completedAt) - new Date(a.completedAt))[0];
+
+      lines.push(`### ${plan.title}`);
+      lines.push(`- **planId**: \`${plan.planId}\``);
+      lines.push(`- **进度**: ${plan.completedSteps}/${plan.totalSteps}（✅ ${plan.completedSteps} 完成，❌ ${plan.failedSteps} 失败）`);
+      if (inProgressStep) {
+        lines.push(`- **当前步骤**: Step ${inProgressStep.index + 1} — **${inProgressStep.name}**`);
+        if (inProgressStep.attempts > 1) {
+          lines.push(`  - 已尝试 ${inProgressStep.attempts} 次`);
+        }
+      } else {
+        lines.push(`- **当前步骤**: 全部已执行，等待 plan_complete/plan_fail`);
+      }
+      if (lastFinished) {
+        const dur = lastFinished.durationMs ? ` (${lastFinished.durationMs}ms)` : '';
+        let lastLabel;
+        if (lastFinished.status === 'completed') {
+          lastLabel = `✅ 完成${dur}`;
+        } else if (lastFinished.status === 'failed') {
+          lastLabel = `❌ 失败${lastFinished.error ? `: ${lastFinished.error}` : ''}${dur}`;
+        } else if (lastFinished.status === 'skipped') {
+          lastLabel = `⏭️ 跳过${lastFinished.note ? `: ${lastFinished.note}` : ''}`;
+        } else {
+          lastLabel = lastFinished.status;
+        }
+        lines.push(`- **上一步**: Step ${lastFinished.index + 1} ${lastLabel}`);
+      }
+      lines.push('');
+    }
+    lines.push('💡 即使上下文被压缩/截断，**继续用 planId 调 `plan_execute_step` 即可恢复执行**。');
+    lines.push('完整计划可调 `plan_show({planId})` 查看。');
+    return lines.join('\n');
+  }
+
+  install(framework) {
+    this._framework = framework;
+    const cwd = framework?.getCwd?.() ?? process.cwd();
+    this._store = new PlanStore(path.resolve(cwd, this.config.dir));
+    this._initIndex();
+    return this;
+  }
+
+  start(framework) {
+    this._registerTools();
+    return this;
+  }
+
+  // === 启动时把所有 .md 加载到内存索引 ===
+  _initIndex() {
+    if (!this._store) return;
+    for (const plan of this._store.list()) {
+      this._index.set(plan.planId, plan);
+    }
+    log.info(`已加载 ${this._index.size} 个计划（${this.config.dir}）`);
+  }
+
+  // === 生成 planId: plan_<ts>-<slug>-<rand6> ===
+  _generatePlanId(title) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 16);
+    const slug = (title || 'untitled')
+      .toLowerCase()
+      .replace(/[^\w一-龥-]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 40) || 'untitled';
+    return `plan_${ts}-${slug}-${randomUUID().slice(0, 6)}`;
+  }
+
+  // === 内部：从内存或磁盘加载 ===
+  _loadPlan(planId) {
+    let plan = this._index.get(planId);
+    if (plan) return plan;
+    plan = this._store?.load(planId);
+    if (!plan) {
+      const err = new Error(`Plan ${planId} not found`);
+      err.code = 'PLAN_NOT_FOUND';
+      throw err;
+    }
+    // 从磁盘 markdown 中补回 log 字段（log 是衍生视图，不存 frontmatter）
+    if (this._store) {
+      try {
+        const md = fs.readFileSync(this._store._toFilePath(planId), 'utf-8');
+        plan.steps = plan.steps.map(s => ({
+          ...s,
+          log: PlanSerializer._extractStepLog(md, s.index),
+        }));
+      } catch { /* 文件可能不存在，忽略 */ }
+    }
+    this._index.set(planId, plan);
+    return plan;
+  }
+
+  // === 内部：是否应该中止（最近已执行步骤中连续 2 步失败） ===
+  // 跳过 pending 步骤，只看已执行（completed/failed/skipped）的最近序列
+  _shouldAbort(plan) {
+    let consec = 0;
+    for (let i = plan.steps.length - 1; i >= 0; i--) {
+      const s = plan.steps[i];
+      if (s.status === 'pending') continue;  // 跳过未启动
+      if (s.status === 'failed') consec++;
+      else break;  // 遇到成功/跳过/进行中 → 中断计数
+    }
+    return consec >= 2;
+  }
+
+  // ============================================================
+  // 工具实现（8 个）
+  // ============================================================
+
+  async _createPlan({ title, task, steps, sessionId }) {
+    if (!title) return { success: false, error: 'title 不能为空' };
+    if (!Array.isArray(steps) || steps.length === 0) {
+      return { success: false, error: 'steps 不能为空数组' };
+    }
+    // 死循环防护
+    for (const s of steps) {
+      if (s.tool === 'plan_create' || s.tool === 'plan_continue') {
+        return { success: false, error: `禁止将 ${s.tool} 作为步骤工具（防止循环）` };
+      }
+    }
+
+    const planId = this._generatePlanId(title);
+    const now = new Date().toISOString();
+    const resolvedSessionId = sessionId
+      || this._framework?.getExecutionContext?.()?.sessionId
+      || null;
+
+    const plan = {
+      planId,
+      title,
+      task: task || '',
+      sessionId: resolvedSessionId,
+      status: 'in_progress',
+      totalSteps: steps.length,
+      completedSteps: 0,
+      failedSteps: 0,
+      createdAt: now,
+      updatedAt: now,
+      steps: steps.map((s, i) => ({
+        index: i,
+        name: s.name,
+        description: s.description || null,
+        status: i === 0 ? 'in_progress' : 'pending',
+        startedAt: i === 0 ? now : null,
+        completedAt: null,
+        durationMs: null,
+        tool: s.tool || null,
+        args: s.args || null,
+        result: null,
+        error: null,
+        note: null,
+        log: null,
+        attempts: 0,
+      })),
+    };
+
+    try {
+      this._store.save(plan);
+    } catch (err) {
+      return { success: false, error: `保存失败: ${err.message}` };
+    }
+    this._index.set(planId, plan);
+    this._invalidatePlanStatusPrompt();
+
+    return {
+      success: true,
+      planId,
+      stepsCount: steps.length,
+      markdownPath: this._store._toFilePath(planId),
+      currentStep: 0,
+    };
+  }
+
+  async _listPlans({ status, sessionId, limit } = {}) {
+    let plans = this._store.list({ status, limit });
+    if (sessionId) {
+      plans = plans.filter(p => p.sessionId === sessionId);
+    }
+    return {
+      success: true,
+      count: plans.length,
+      plans: plans.map(p => ({
+        planId: p.planId,
+        title: p.title,
+        status: p.status,
+        totalSteps: p.totalSteps,
+        completedSteps: p.completedSteps,
+        failedSteps: p.failedSteps,
+        sessionId: p.sessionId,
+        createdAt: p.createdAt,
+        updatedAt: p.updatedAt,
+      })),
+    };
+  }
+
+  async _showPlan({ planId }) {
+    if (!planId) return { success: false, error: 'planId 必填' };
+    const plan = this._loadPlan(planId);
+    // 重新从磁盘读最新 markdown（确保展示与文件一致）
+    let markdown;
+    try {
+      markdown = fs.readFileSync(this._store._toFilePath(planId), 'utf-8');
+    } catch (err) {
+      return { success: false, error: `读取失败: ${err.message}` };
+    }
+    return {
+      success: true,
+      planId,
+      markdown,
+      plan: {
+        planId: plan.planId,
+        title: plan.title,
+        status: plan.status,
+        completedSteps: plan.completedSteps,
+        totalSteps: plan.totalSteps,
+      },
+    };
+  }
+
+  async _executeStep({ planId, stepIndex, status, tool, args, result, error, note, durationMs }) {
+    if (!planId) return { success: false, error: 'planId 必填' };
+    if (stepIndex === undefined || stepIndex === null) {
+      return { success: false, error: 'stepIndex 必填' };
+    }
+    if (!['in_progress', 'completed', 'failed', 'skipped'].includes(status)) {
+      return { success: false, error: `invalid status: ${status}` };
+    }
+
+    let plan;
+    try {
+      plan = this._loadPlan(planId);
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+
+    const step = plan.steps[stepIndex];
+    if (!step) {
+      return { success: false, error: `Step ${stepIndex} not found (total ${plan.steps.length})` };
+    }
+
+    const now = new Date().toISOString();
+    const attemptNumber = (step.attempts || 0) + 1;
+    const isRetry = attemptNumber > 1;
+
+    // ★ 修复：每次 executeStep 视为"新一次尝试"，
+    //   即使没传 error/note/result，也要清空旧的（避免日志残留上一次失败的信息）。
+    //   显式传值则用新值（用 ?? 让 null/undefined 都视为清空）。
+    step.status = status;
+    step.tool = tool !== undefined ? tool : null;
+    step.args = args !== undefined ? args : null;
+    step.result = result !== undefined ? result : null;
+    step.error = error !== undefined ? error : null;
+    step.note = note !== undefined ? note : null;
+    step.durationMs = durationMs !== undefined ? durationMs : null;
+    if (status === 'in_progress') {
+      step.startedAt = now;
+    }
+    if (['completed', 'failed', 'skipped'].includes(status)) {
+      step.completedAt = now;
+    }
+    step.attempts = attemptNumber;
+
+    // 重算汇总
+    plan.completedSteps = plan.steps.filter(s => s.status === 'completed').length;
+    plan.failedSteps = plan.steps.filter(s => s.status === 'failed').length;
+    plan.updatedAt = now;
+
+    // 自动推进：completed 时下一步自动 in_progress
+    if (status === 'completed') {
+      const nextStep = plan.steps[stepIndex + 1];
+      if (nextStep && nextStep.status === 'pending') {
+        nextStep.status = 'in_progress';
+        nextStep.startedAt = now;
+      }
+    }
+
+    // 追加本次尝试的日志块（保留历史）
+    const attemptLog = [
+      `### Step ${stepIndex + 1} (尝试 ${attemptNumber}) - ${now} - ${status}`,
+      `- 工具: ${step.tool || 'N/A'}`,
+      step.args ? `- 参数: ${JSON.stringify(step.args, null, 2)}` : null,
+      step.error ? `- 错误: ${step.error}` : null,
+      step.result !== null && step.result !== undefined
+        ? `- 结果: ${JSON.stringify(step.result, null, 2).slice(0, 800)}`
+        : null,
+      `- 耗时: ${step.durationMs ?? 'N/A'}ms`,
+      step.note ? `- 备注: ${step.note}` : null,
+    ].filter(Boolean).join('\n');
+
+    // 累加日志：每次新尝试追加（用 --- 分隔），第一次直接赋值
+    step.log = step.log
+      ? step.log + '\n\n---\n\n' + attemptLog
+      : attemptLog;
+
+    try {
+      this._store.save(plan);
+    } catch (err) {
+      return { success: false, error: `保存失败: ${err.message}` };
+    }
+    this._index.set(planId, plan);
+    this._invalidatePlanStatusPrompt();
+
+    const shouldAbort = this._shouldAbort(plan);
+    const next = plan.steps[stepIndex + 1];
+    return {
+      success: true,
+      stepIndex,
+      status: step.status,
+      attempts: attemptNumber,
+      isRetry,
+      progress: `${plan.completedSteps}/${plan.totalSteps}`,
+      nextStep: next && next.status === 'in_progress' ? stepIndex + 1 : null,
+      shouldAbort,
+      abortReason: shouldAbort ? '连续失败 >= 2 步，建议中止' : null,
+    };
+  }
+
+  async _continuePlan({ planId }) {
+    if (!planId) return { success: false, error: 'planId 必填' };
+    let plan;
+    try {
+      plan = this._loadPlan(planId);
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+    if (plan.status === 'completed') {
+      return { success: false, error: '计划已完成，无需 continue', plan };
+    }
+
+    // 找到第一个非 completed/failed/skipped 的 step
+    let resumableFrom = -1;
+    for (let i = 0; i < plan.steps.length; i++) {
+      if (!['completed', 'failed', 'skipped'].includes(plan.steps[i].status)) {
+        resumableFrom = i;
+        break;
+      }
+    }
+    if (resumableFrom === -1) {
+      return { success: false, error: '没有可恢复的步骤', plan };
+    }
+
+    // 把当前 step 标记为 in_progress（若不是）
+    const step = plan.steps[resumableFrom];
+    if (step.status === 'pending') {
+      step.status = 'in_progress';
+      step.startedAt = step.startedAt || new Date().toISOString();
+    }
+    plan.status = 'in_progress';
+    plan.updatedAt = new Date().toISOString();
+    try {
+      this._store.save(plan);
+    } catch (err) {
+      return { success: false, error: `保存失败: ${err.message}` };
+    }
+    this._index.set(planId, plan);
+    this._invalidatePlanStatusPrompt();
+
+    return {
+      success: true,
+      planId,
+      plan: {
+        planId: plan.planId,
+        title: plan.title,
+        status: plan.status,
+        totalSteps: plan.totalSteps,
+        completedSteps: plan.completedSteps,
+        failedSteps: plan.failedSteps,
+        task: plan.task,
+        steps: plan.steps.map(s => ({
+          index: s.index,
+          name: s.name,
+          description: s.description,
+          status: s.status,
+        })),
+      },
+      resumableFrom,
+      nextStepName: step.name,
+    };
+  }
+
+  async _completePlan({ planId, summary }) {
+    if (!planId) return { success: false, error: 'planId 必填' };
+    let plan;
+    try {
+      plan = this._loadPlan(planId);
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+    const incomplete = plan.steps.filter(
+      s => !['completed', 'skipped'].includes(s.status)
+    );
+    if (incomplete.length > 0) {
+      return {
+        success: false,
+        error: `还有 ${incomplete.length} 步未完成：${incomplete.map(s => `#${s.index + 1}`).join(', ')}`,
+        plan,
+      };
+    }
+    plan.status = 'completed';
+    plan.updatedAt = new Date().toISOString();
+    if (summary) {
+      // 在最后一个 completed step 的日志中附加 summary
+      const last = plan.steps[plan.steps.length - 1];
+      last.log = (last.log || '') + `\n\n## 📋 完成总结\n${summary}`;
+    }
+    try {
+      this._store.save(plan);
+    } catch (err) {
+      return { success: false, error: `保存失败: ${err.message}` };
+    }
+    this._index.set(planId, plan);
+    this._invalidatePlanStatusPrompt();
+    return { success: true, planId, status: 'completed' };
+  }
+
+  async _failPlan({ planId, reason }) {
+    if (!planId) return { success: false, error: 'planId 必填' };
+    let plan;
+    try {
+      plan = this._loadPlan(planId);
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+    plan.status = 'failed';
+    plan.updatedAt = new Date().toISOString();
+    if (reason) {
+      const logIdx = plan.steps.findIndex(s => s.status === 'in_progress');
+      const target = logIdx >= 0 ? plan.steps[logIdx] : plan.steps[plan.steps.length - 1];
+      target.log = (target.log || '') + `\n\n## ❌ 计划中止\n原因: ${reason}`;
+    }
+    try {
+      this._store.save(plan);
+    } catch (err) {
+      return { success: false, error: `保存失败: ${err.message}` };
+    }
+    this._index.set(planId, plan);
+    this._invalidatePlanStatusPrompt();
+    return { success: true, planId, status: 'failed', reason };
+  }
+
+  async _deletePlan({ planId }) {
+    if (!planId) return { success: false, error: 'planId 必填' };
+    const ok = this._store.delete(planId);
+    this._index.delete(planId);
+    this._invalidatePlanStatusPrompt();
+    return { success: ok, planId, deleted: ok };
+  }
+
+  // ============================================================
+  // 工具注册（用 this.tool.register 注入到 ToolRegistry，
+  // LLM 在 system prompt 中直接看到 plan_create 等顶层工具名）
+  // ============================================================
+  _registerTools() {
+    this.tool.register({
+      name: 'plan_create',
+      description: '创建一个执行计划：把多步任务拆解为可追踪步骤并持久化到 .foliko/plans/。返回 planId 后请按 planId 依次 plan_execute_step。',
+      inputSchema: z.object({
+        title: z.string().describe('计划标题，简短描述任务'),
+        task: z.string().optional().describe('原始任务描述，用于 continue 时回放上下文'),
+        steps: z.array(z.object({
+          name: z.string().describe('步骤名（如"读取配置文件"）'),
+          description: z.string().optional().describe('步骤详细说明'),
+          tool: z.string().optional().describe('预计要调用的工具名（仅提示）'),
+          args: z.record(z.any()).optional().describe('预计参数（仅提示）'),
+        })).min(1).describe('至少 1 步'),
+        sessionId: z.string().optional().describe('关联的 sessionId（可选，自动从执行上下文取）'),
+      }),
+      execute: this._createPlan.bind(this),
+    });
+
+    this.tool.register({
+      name: 'plan_list',
+      description: '列出 .foliko/plans/ 下的所有计划。',
+      inputSchema: z.object({
+        status: z.enum(['in_progress', 'completed', 'failed', 'paused']).optional().describe('按状态过滤'),
+        sessionId: z.string().optional().describe('按 session 过滤'),
+        limit: z.number().int().min(1).max(100).optional().describe('最多返回几条'),
+      }),
+      execute: this._listPlans.bind(this),
+    });
+
+    this.tool.register({
+      name: 'plan_show',
+      description: '显示计划完整 markdown 内容（含任务、步骤、执行日志）。',
+      inputSchema: z.object({
+        planId: z.string().describe('计划 ID（plan_create 返回）'),
+      }),
+      execute: this._showPlan.bind(this),
+    });
+
+    this.tool.register({
+      name: 'plan_execute_step',
+      description: '记录一步执行结果：LLM 在调用某个工具完成/失败/跳过后，**必须**调用此工具持久化状态。返回 {progress, nextStep, shouldAbort}。',
+      inputSchema: z.object({
+        planId: z.string().describe('计划 ID'),
+        stepIndex: z.number().int().min(0).describe('步骤索引（0-based）'),
+        status: z.enum(['in_progress', 'completed', 'failed', 'skipped']).describe('步骤新状态'),
+        tool: z.string().optional().describe('实际调用的工具名'),
+        args: z.record(z.any()).optional().describe('实际参数'),
+        result: z.any().optional().describe('工具返回结果（可序列化部分）'),
+        error: z.string().optional().describe('失败时的错误信息'),
+        note: z.string().optional().describe('备注（如"重试 2 次后"）'),
+        durationMs: z.number().int().optional().describe('本步耗时（毫秒）'),
+      }),
+      execute: this._executeStep.bind(this),
+    });
+
+    this.tool.register({
+      name: 'plan_continue',
+      description: '恢复一个 in_progress/paused/failed 的计划：返回 plan 详情 + 从哪一步（resumableFrom）继续。',
+      inputSchema: z.object({
+        planId: z.string().describe('计划 ID'),
+      }),
+      execute: this._continuePlan.bind(this),
+    });
+
+    this.tool.register({
+      name: 'plan_complete',
+      description: '把计划标记为已完成。只能所有步骤都 completed/skipped 时调用。',
+      inputSchema: z.object({
+        planId: z.string().describe('计划 ID'),
+        summary: z.string().optional().describe('完成总结（写入日志）'),
+      }),
+      execute: this._completePlan.bind(this),
+    });
+
+    this.tool.register({
+      name: 'plan_fail',
+      description: '中止并标记计划为失败。',
+      inputSchema: z.object({
+        planId: z.string().describe('计划 ID'),
+        reason: z.string().optional().describe('中止原因'),
+      }),
+      execute: this._failPlan.bind(this),
+    });
+
+    this.tool.register({
+      name: 'plan_delete',
+      description: '删除计划文件（不可恢复）。',
+      inputSchema: z.object({
+        planId: z.string().describe('计划 ID'),
+      }),
+      execute: this._deletePlan.bind(this),
+    });
+  }
+
+  // ============================================================
+  // 卸载清理（基类已自动管理 _registeredTools）
+  // ============================================================
+  uninstall(framework) {
+    this._framework = null;
+    this._store = null;
+    this._index.clear();
+  }
+}
+
+module.exports = PlannerPlugin;
+module.exports.PlannerPlugin = PlannerPlugin;
+module.exports.PlanStore = PlanStore;
+module.exports.PlanSerializer = PlanSerializer;