@bolloon/bolloon-agent 0.3.23 → 0.3.25

package/dist/agents/pi-sdk-tools.js

@@ -271,16 +271,18 @@ export function registerBuiltinTools(ctx) {
     // add_friend_by_id — 通过 Hyperswarm publicKey 添加 P2P 好友
     ctx.tools.set('add_friend_by_id', {
         name: 'add_friend_by_id',
-        description: '通过 Hyperswarm P2P publicKey (64 字符 hex) 添加好友. 对方在线时会收到好友申请弹窗, 接受后自动分享 channel.',
+        description: '通过 Hyperswarm P2P publicKey (64 字符 hex) 添加好友. 对方在线时会收到好友申请弹窗, 接受后自动分享 channel. 强烈建议填 note 备注 (自我介绍/来源), 对方才能分辨你是谁.',
         parameters: {
             publicKey: '64 字符 hex publicKey (必填)',
             name: '可选, 给好友的备注名 (如: 同事-张磊)',
-            message: '可选, 附加的好友申请消息'
+            message: '可选, 附加的好友申请消息',
+            note: '可选, 备注 (自我介绍/来源), 对方接受时会看到. 如 "我是[姓名]的 Bolloon agent[name], 来自[来源], 想加你为好友共享 channel 协作,技能: [技能列表]"'
         },
         execute: async (args) => {
             const publicKey = String(args.publicKey || '').trim();
             const name = String(args.name || '').trim();
             const message = String(args.message || '想加你为 P2P 好友, 共享 channel 协作').trim();
+            const note = String(args.note || '').trim();
             if (!publicKey || publicKey.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(publicKey)) {
                 return { success: false, error: 'publicKey 必须是 64 字符 hex 格式' };
             }
@@ -289,7 +291,7 @@ export function registerBuiltinTools(ctx) {
                 const res = await fetch(`http://127.0.0.1:${port}/api/friend-request`, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ targetPublicKey: publicKey, name: name || undefined, message })
+                    body: JSON.stringify({ targetPublicKey: publicKey, name: name || undefined, message, note: note || undefined })
                 });
                 const data = await res.json();
                 if (!res.ok) {
@@ -303,6 +305,95 @@ export function registerBuiltinTools(ctx) {
             }
         }
     });
+    // list_pending_friend_requests — 查看待处理的好友申请 (智能体侧处理入口)
+    ctx.tools.set('list_pending_friend_requests', {
+        name: 'list_pending_friend_requests',
+        description: '查看当前待处理的好友申请列表 (对方想加你为好友但还没接受). 每个申请带 fromName / note 备注 (自我介绍/来源), 便于判断是否接受. 用 accept_friend_request 接受, 或 ignore_friend_request 忽略.',
+        parameters: {},
+        execute: async () => {
+            try {
+                const port = process.env.PORT || '54188';
+                const res = await fetch(`http://127.0.0.1:${port}/api/friend-requests`);
+                const data = await res.json();
+                if (!res.ok)
+                    return { success: false, error: data.error || '查询失败' };
+                if (data.count === 0) {
+                    return { success: true, output: '当前没有待处理的好友申请。' };
+                }
+                const lines = data.requests.map((r, i) => `${i + 1}. ${r.fromName} (publicKey=${r.fromPublicKey.substring(0, 16)}...)\n   备注: ${r.note || r.message || '(无)'}\n   requestId: ${r.requestId}`);
+                return { success: true, output: `待处理好友申请 ${data.count} 个:\n${lines.join('\n')}\n\n用 accept_friend_request 接受, 或 ignore_friend_request 忽略.` };
+            }
+            catch (e) {
+                return { success: false, error: `查询好友申请失败: ${String(e.message || e)}` };
+            }
+        }
+    });
+    // accept_friend_request — 接受一个待处理的好友申请 (智能体侧一键通过)
+    ctx.tools.set('accept_friend_request', {
+        name: 'accept_friend_request',
+        description: '接受一个待处理的好友申请. 对方会出现在你的 P2P 好友列表, 对方分享的 channel 自动可见. 参数 requestId 来自 list_pending_friend_requests 的返回.',
+        parameters: {
+            requestId: '待处理申请的 requestId (必填, 来自 list_pending_friend_requests)',
+            name: '可选, 给这个新好友的备注名 (默认用对方自称的名字)'
+        },
+        execute: async (args) => {
+            const requestId = String(args.requestId || '').trim();
+            if (!requestId) {
+                return { success: false, error: 'requestId 必填 (先调 list_pending_friend_requests 获取)' };
+            }
+            try {
+                const port = process.env.PORT || '54188';
+                // 先查 pending 拿到 fromPublicKey / fromName
+                const q = await fetch(`http://127.0.0.1:${port}/api/friend-requests`);
+                const qd = await q.json();
+                const req = (qd.requests || []).find((r) => r.requestId === requestId);
+                if (!req) {
+                    return { success: false, error: `未找到 requestId=${requestId} 的申请 (可能已被处理或过期)` };
+                }
+                const acceptName = String(args.name || '').trim() || req.fromName;
+                const res = await fetch(`http://127.0.0.1:${port}/api/friend-accept`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ fromPublicKey: req.fromPublicKey, name: acceptName, requestId })
+                });
+                const data = await res.json();
+                if (!res.ok)
+                    return { success: false, error: data.error || '接受失败' };
+                return { success: true, output: `✅ 已接受 ${req.fromName} 的好友申请 (备注: ${req.note || req.message || '(无)'}), 已加为好友: ${data.persistedAs || acceptName}` };
+            }
+            catch (e) {
+                return { success: false, error: `接受好友申请失败: ${String(e.message || e)}` };
+            }
+        }
+    });
+    // ignore_friend_request — 忽略一个待处理的好友申请
+    ctx.tools.set('ignore_friend_request', {
+        name: 'ignore_friend_request',
+        description: '忽略 (拒绝) 一个待处理的好友申请, 不加入好友. 参数 requestId 来自 list_pending_friend_requests 的返回.',
+        parameters: {
+            requestId: '待处理申请的 requestId (必填, 来自 list_pending_friend_requests)'
+        },
+        execute: async (args) => {
+            const requestId = String(args.requestId || '').trim();
+            if (!requestId)
+                return { success: false, error: 'requestId 必填' };
+            try {
+                const port = process.env.PORT || '54188';
+                const res = await fetch(`http://127.0.0.1:${port}/api/friend-requests/ignore`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ requestId })
+                });
+                const data = await res.json();
+                if (!res.ok)
+                    return { success: false, error: data.error || '忽略失败' };
+                return { success: true, output: `已忽略好友申请 ${requestId.substring(0, 8)}...` };
+            }
+            catch (e) {
+                return { success: false, error: `忽略好友申请失败: ${String(e.message || e)}` };
+            }
+        }
+    });
     // delegate_to_engine — 把编码任务委派给本机已安装的其他 AI 编码智能体 CLI
     // (codex / claude-code / opencode / openclaw / hermes). 它们必须已安装且可达 PATH.
     // 实验 API 引擎 (experiment:xxx) 是供应商不是 CLI, 不支持委派, 工具会提示改用 import.
@@ -642,15 +733,12 @@ export function registerBuiltinTools(ctx) {
     // 通用文件读取 (M4)
     ctx.tools.set('read_file', {
         name: 'read_file',
-        description: '读取任意文件内容 (相对 cwd). 受 shell-guard 路径白名单保护.',
+        description: '读取任意文件内容 (相对 cwd). 只读操作, 无白名单限制.',
         parameters: { path: '相对路径 (必填)', startLine: '起始行号 (可选, 默认 0)', maxLines: '最大行数 (可选, 默认 500)' },
         execute: async (args) => {
             const relPath = String(args.path || '').trim();
             if (!relPath)
                 return { success: false, error: 'path 必填' };
-            const pathResult = checkWritePath(relPath);
-            if (!pathResult.allowed)
-                return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
             try {
                 const absPath = path.resolve(ctx.cwd, relPath);
                 const content = fsSync.readFileSync(absPath, 'utf-8');
@@ -740,16 +828,13 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('grep_files', {
         name: 'grep_files',
-        description: '在文件中搜索匹配 pattern 的行. 类似 grep -rn. 路径必须在白名单.',
+        description: '在文件中搜索匹配 pattern 的行. 类似 grep -rn. 只读操作, 无白名单限制.',
         parameters: { pattern: '搜索 pattern (必填, 字符串, 不是正则)', path: '搜索目录 (可选, 默认 .)', filePattern: '文件名 glob (可选)' },
         execute: async (args) => {
             const pattern = String(args.pattern || '').trim();
             if (!pattern)
                 return { success: false, error: 'pattern 必填' };
             const searchPath = String(args.path || '.').trim();
-            const pathResult = checkWritePath(searchPath);
-            if (!pathResult.allowed)
-                return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
             try {
                 const { execFile } = await import('child_process');
                 const { promisify } = await import('util');
@@ -768,16 +853,13 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('glob_files', {
         name: 'glob_files',
-        description: '用 glob pattern 找文件. 例如 "**/*.test.ts".',
+        description: '用 glob pattern 找文件. 例如 "**/*.test.ts". 只读操作, 无白名单限制.',
         parameters: { pattern: 'glob pattern (必填, e.g. "src/**/*.ts")' },
         execute: async (args) => {
             const pattern = String(args.pattern || '').trim();
             if (!pattern)
                 return { success: false, error: 'pattern 必填' };
             try {
-                const pathResult = checkWritePath(pattern.replace(/\*\*.*$/, '').replace(/\/\*.*$/, '') || '.');
-                if (!pathResult.allowed && pattern !== '**/*' && pattern !== '*')
-                    return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
                 const { execFile } = await import('child_process');
                 const { promisify } = await import('util');
                 const pExecFile = promisify(execFile);
@@ -1111,6 +1193,246 @@ export function registerBuiltinTools(ctx) {
             }
         }
     });
+    // ============================================================
+    // skill 写工具 (2026-08-02) — 让 agent 从成功经验沉淀技能
+    // create_skill / update_skill / list_skill_candidates / promote_skill
+    // 实现: skill-writer.ts (写 ~/.bolloon/skills/<name>/SKILL.md)
+    // ============================================================
+    ctx.tools.set('create_skill', {
+        name: 'create_skill',
+        description: '创建/覆盖一个 skill (SKILL.md). 当你学会一个可复用的做事方法 (成功流程/命令组合/踩坑教训) 时调用, 沉淀成技能供以后复用. 写 ~/.bolloon/skills/<name>/SKILL.md. 只读技能请用 update_skill 追加.',
+        parameters: {
+            name: 'skill 名 (必填, 小写字母数字连字符, e.g. "p2p-debug")',
+            description: '一句话描述这个 skill 什么时候用 (必填)',
+            body: 'Markdown 正文 (必填): 步骤 / 命令 / 注意事项',
+            scope: '可选: user (默认, ~/.bolloon/skills) 或 project (.bolloon/skills)',
+            triggers: '可选: 触发条件数组 (JSON 字符串数组, e.g. ["p2p", "连接失败"])',
+        },
+        execute: async (args) => {
+            try {
+                const { createSkill } = await import('./skill-writer.js');
+                const name = String(args.name || '').trim();
+                if (!name)
+                    return { success: false, error: 'name 必填' };
+                const body = String(args.body || '').trim();
+                if (!body)
+                    return { success: false, error: 'body 必填' };
+                let triggers;
+                try {
+                    const t = JSON.parse(String(args.triggers || '[]'));
+                    if (Array.isArray(t))
+                        triggers = t.map(String);
+                }
+                catch { /* triggers 解析失败忽略 */ }
+                const r = await createSkill(name, String(args.description || ''), body, {
+                    scope: args.scope === 'project' ? 'project' : 'user',
+                    triggers,
+                });
+                return r.ok
+                    ? { success: true, output: `✅ skill '${name}' 已写入 ${r.path}` }
+                    : { success: false, error: r.error };
+            }
+            catch (e) {
+                return { success: false, error: `create_skill 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('update_skill', {
+        name: 'update_skill',
+        description: '更新已有 skill: 追加新经验 (append_body) 或整体替换 (body), 或改描述/触发条件. skill 不存在时用 create_skill.',
+        parameters: {
+            name: 'skill 名 (必填)',
+            append_body: '追加到正文尾部的增量经验 (可选)',
+            body: '整体替换正文 (可选, 与 append_body 二选一)',
+            description: '新描述 (可选)',
+            triggers: '新触发条件数组 JSON (可选)',
+        },
+        execute: async (args) => {
+            try {
+                const { updateSkill } = await import('./skill-writer.js');
+                const name = String(args.name || '').trim();
+                if (!name)
+                    return { success: false, error: 'name 必填' };
+                let triggers;
+                try {
+                    const t = JSON.parse(String(args.triggers || '[]'));
+                    if (Array.isArray(t))
+                        triggers = t.map(String);
+                }
+                catch { /* 忽略 */ }
+                const r = await updateSkill(name, {
+                    description: args.description ? String(args.description) : undefined,
+                    appendBody: args.append_body ? String(args.append_body) : undefined,
+                    body: args.body ? String(args.body) : undefined,
+                    triggers,
+                });
+                return r.ok
+                    ? { success: true, output: `✅ skill '${name}' 已更新 ${r.path}` }
+                    : { success: false, error: r.error };
+            }
+            catch (e) {
+                return { success: false, error: `update_skill 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('list_skill_candidates', {
+        name: 'list_skill_candidates',
+        description: '查看待沉淀的 skill 候选 (后台任务从成功的工具调用模式生成的候选). 返回候选列表, 可用 promote_skill 转正.',
+        parameters: {},
+        execute: async () => {
+            try {
+                const { listSkillCandidates } = await import('./skill-writer.js');
+                const cands = await listSkillCandidates();
+                if (cands.length === 0)
+                    return { success: true, output: '暂无待沉淀的 skill 候选.' };
+                const lines = cands.map(c => `- ${c.name}: ${c.description} [来源 ${c.source}]`).join('\n');
+                return { success: true, output: `📋 ${cands.length} 个 skill 候选:\n${lines}` };
+            }
+            catch (e) {
+                return { success: false, error: `list_skill_candidates 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('promote_skill', {
+        name: 'promote_skill',
+        description: '把 skill 候选转正为正式 skill. 转正后候选文件自动清理.',
+        parameters: { name: '候选名 (必填, 见 list_skill_candidates)' },
+        execute: async (args) => {
+            try {
+                const { promoteCandidate } = await import('./skill-writer.js');
+                const name = String(args.name || '').trim();
+                if (!name)
+                    return { success: false, error: 'name 必填' };
+                const r = await promoteCandidate(name);
+                return r.ok
+                    ? { success: true, output: `✅ 候选 '${name}' 已转正 → ${r.path}` }
+                    : { success: false, error: r.error };
+            }
+            catch (e) {
+                return { success: false, error: `promote_skill 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    // ============================================================
+    // plan / todo / review 工具 (2026-08-02) — 显式执行闭环
+    // create_plan / update_plan / review_plan / list_plans
+    // 实现: plan-store.ts (~/.bolloon/plans/<planId>.json)
+    // ============================================================
+    ctx.tools.set('create_plan', {
+        name: 'create_plan',
+        description: '执行复杂任务前先显式列计划: 拆成 3-8 个可执行步骤. 之后每完成一步调 update_plan 勾选, 全部完成调 review_plan 总结. 落盘 ~/.bolloon/plans/.',
+        parameters: {
+            goal: '一句话目标 (必填)',
+            steps: '步骤数组 JSON (必填, e.g. ["读需求", "写代码", "测试"])',
+        },
+        execute: async (args) => {
+            try {
+                const { createPlan, planToContext } = await import('./plan-store.js');
+                const goal = String(args.goal || '').trim();
+                let steps = [];
+                try {
+                    const s = JSON.parse(String(args.steps || '[]'));
+                    if (Array.isArray(s))
+                        steps = s.map(String);
+                }
+                catch { /* steps 解析失败 */ }
+                const r = await createPlan({ goal, steps, createdBy: 'agent', originChannel: ctx.channelId || '' });
+                if (!r.ok || !r.plan)
+                    return { success: false, error: r.error };
+                return { success: true, output: `✅ 计划已创建 ${r.plan.planId}\n\n${planToContext(r.plan)}` };
+            }
+            catch (e) {
+                return { success: false, error: `create_plan 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('update_plan', {
+        name: 'update_plan',
+        description: '更新计划: 勾选某步完成/阻塞 (step_id + status), 或追加新步骤 (append_steps), 或整体结束 (finish=true). 执行中每完成一步必调.',
+        parameters: {
+            plan_id: '计划 ID (必填, create_plan 返回)',
+            step_id: '步骤 ID (可选, e.g. step_1)',
+            status: '步骤新状态: done / blocked (可选)',
+            note: '完成/阻塞备注 (可选)',
+            append_steps: '追加步骤数组 JSON (可选)',
+            finish: 'true 表示整个计划结束 (可选)',
+        },
+        execute: async (args) => {
+            try {
+                const { updatePlan, planToContext } = await import('./plan-store.js');
+                const planId = String(args.plan_id || '').trim();
+                if (!planId)
+                    return { success: false, error: 'plan_id 必填' };
+                let appendSteps;
+                try {
+                    const s = JSON.parse(String(args.append_steps || '[]'));
+                    if (Array.isArray(s))
+                        appendSteps = s.map(String);
+                }
+                catch { /* 忽略 */ }
+                const r = await updatePlan(planId, {
+                    stepId: args.step_id ? String(args.step_id) : undefined,
+                    status: (args.status === 'done' || args.status === 'blocked') ? args.status : undefined,
+                    note: args.note ? String(args.note) : undefined,
+                    appendSteps,
+                    finish: String(args.finish) === 'true',
+                });
+                if (!r.ok || !r.plan)
+                    return { success: false, error: r.error };
+                return { success: true, output: `✅ 计划已更新\n\n${planToContext(r.plan)}` };
+            }
+            catch (e) {
+                return { success: false, error: `update_plan 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('review_plan', {
+        name: 'review_plan',
+        description: '计划全部执行完后审查: 总结完成度 + 产出结论. 完成后 plan 标记 done.',
+        parameters: {
+            plan_id: '计划 ID (必填)',
+            summary: '审查总结 (必填, 说明完成了什么/卡在哪/下一步)',
+        },
+        execute: async (args) => {
+            try {
+                const { reviewPlan } = await import('./plan-store.js');
+                const planId = String(args.plan_id || '').trim();
+                if (!planId)
+                    return { success: false, error: 'plan_id 必填' };
+                const summary = String(args.summary || '').trim();
+                if (!summary)
+                    return { success: false, error: 'summary 必填' };
+                const r = await reviewPlan(planId, summary);
+                if (!r.ok || !r.plan)
+                    return { success: false, error: r.error };
+                return {
+                    success: true,
+                    output: `✅ 计划审查完成: ${r.plan.review.completedSteps}/${r.plan.review.totalSteps} 步\n📝 ${summary}`,
+                };
+            }
+            catch (e) {
+                return { success: false, error: `review_plan 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('list_plans', {
+        name: 'list_plans',
+        description: '列出所有进行中的计划 (active). 用于恢复上下文/继续未完成的计划.',
+        parameters: {},
+        execute: async () => {
+            try {
+                const { listActivePlans, planToContext } = await import('./plan-store.js');
+                const plans = await listActivePlans();
+                if (plans.length === 0)
+                    return { success: true, output: '暂无进行中的计划.' };
+                const text = plans.map(p => planToContext(p)).join('\n\n');
+                return { success: true, output: `📋 ${plans.length} 个进行中的计划:\n\n${text}` };
+            }
+            catch (e) {
+                return { success: false, error: `list_plans 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
 }
 /**
  * 注册 Wallet + Polymarket + Safe 工具 (基于 constraint-runtime/src/tools/).

package/dist/agents/plan-store.js

@@ -0,0 +1,167 @@
+/**
+ * plan-store.ts — 轻量 plan / todo / review 原语 (2026-08-02)
+ *
+ * 补齐 agent 执行闭环里的显式环节:
+ *   - plan:    执行前显式列出步骤 (LLM 写计划)
+ *   - todo:    步骤级状态 (pending / done / blocked), 执行中勾选
+ *   - review:  执行后审查 (对照计划看完成度, 产出结论)
+ *
+ * 设计原则 (减法):
+ *   - 不建数据库. 落盘 = ~/.bolloon/plans/<planId>.json (单文件, append 不适用, 直接重写)
+ *   - 不引入新调度. 工具入口在 pi-sdk-tools.ts 注册, 复用现有 LLM 调度.
+ *   - 任何 IO 失败静默返回 error 对象, 不阻塞主对话.
+ *   - plan 上下文注入: create_plan 后会把计划摘要写回 messageHistory (由工具返回, LLM 自己看到),
+ *     同时 planId 存 session, 后续 update_plan / review_plan 按 planId 操作.
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+// ============================================================
+// 落盘路径
+// ============================================================
+export function getPlansDir(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'plans');
+}
+export function getPlanPath(planId, home = os.homedir()) {
+    return path.join(getPlansDir(home), `${planId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+}
+export function sanitizePlanId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+}
+export async function createPlan(input, home) {
+    const goal = String(input.goal || '').trim();
+    const steps = Array.isArray(input.steps) ? input.steps.map(s => String(s).trim()).filter(Boolean) : [];
+    if (!goal)
+        return { ok: false, error: 'goal 必填' };
+    if (steps.length === 0)
+        return { ok: false, error: 'steps 至少 1 步' };
+    const now = new Date().toISOString();
+    const planId = `plan_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+    const plan = {
+        planId,
+        goal,
+        createdBy: input.createdBy || 'agent',
+        createdAt: now,
+        originChannel: input.originChannel || '',
+        steps: steps.map((s, i) => ({
+            id: `step_${i + 1}`,
+            description: s,
+            status: 'pending',
+        })),
+        status: 'active',
+        updatedAt: now,
+    };
+    try {
+        const dir = getPlansDir(home);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(getPlanPath(planId, home), JSON.stringify(plan, null, 2), 'utf-8');
+        return { ok: true, plan };
+    }
+    catch (e) {
+        return { ok: false, error: `写入失败: ${e?.message || String(e)}` };
+    }
+}
+export async function loadPlan(planId, home) {
+    try {
+        const raw = await fs.readFile(getPlanPath(planId, home), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function savePlan(plan, home) {
+    plan.updatedAt = new Date().toISOString();
+    await fs.writeFile(getPlanPath(plan.planId, home), JSON.stringify(plan, null, 2), 'utf-8');
+}
+export async function updatePlan(planId, input, home) {
+    const plan = await loadPlan(planId, home);
+    if (!plan)
+        return { ok: false, error: `plan '${planId}' 不存在` };
+    if (input.stepId && input.status) {
+        const step = plan.steps.find(s => s.id === input.stepId);
+        if (!step)
+            return { ok: false, error: `步骤 '${input.stepId}' 不存在` };
+        step.status = input.status;
+        if (input.note)
+            step.note = input.note;
+        step.updatedAt = new Date().toISOString();
+    }
+    if (Array.isArray(input.appendSteps) && input.appendSteps.length > 0) {
+        for (const s of input.appendSteps) {
+            const desc = String(s).trim();
+            if (!desc)
+                continue;
+            plan.steps.push({ id: `step_${plan.steps.length + 1}`, description: desc, status: 'pending' });
+        }
+    }
+    if (input.finish) {
+        plan.status = 'done';
+        // 未完成的步骤标 blocked (收尾语义)
+        for (const s of plan.steps) {
+            if (s.status === 'pending')
+                s.status = 'blocked';
+        }
+    }
+    try {
+        await savePlan(plan, home);
+        return { ok: true, plan };
+    }
+    catch (e) {
+        return { ok: false, error: `保存失败: ${e?.message || String(e)}` };
+    }
+}
+export async function reviewPlan(planId, summary, home) {
+    const plan = await loadPlan(planId, home);
+    if (!plan)
+        return { ok: false, error: `plan '${planId}' 不存在` };
+    const completedSteps = plan.steps.filter(s => s.status === 'done').length;
+    plan.review = {
+        completedSteps,
+        totalSteps: plan.steps.length,
+        summary: String(summary || '').trim() || `完成 ${completedSteps}/${plan.steps.length} 步`,
+        reviewedAt: new Date().toISOString(),
+    };
+    plan.status = 'done';
+    try {
+        await savePlan(plan, home);
+        return { ok: true, plan };
+    }
+    catch (e) {
+        return { ok: false, error: `保存失败: ${e?.message || String(e)}` };
+    }
+}
+export async function listActivePlans(home) {
+    const dir = getPlansDir(home);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of entries.filter(f => f.endsWith('.json')).sort().slice(-50)) {
+        try {
+            const raw = await fs.readFile(path.join(dir, f), 'utf-8');
+            const p = JSON.parse(raw);
+            if (p.status === 'active')
+                out.push(p);
+        }
+        catch { /* 坏文件跳过 */ }
+    }
+    return out;
+}
+/** 把 plan 渲染成注入 context 的文本 (LLM 看到计划 + 进度) */
+export function planToContext(plan) {
+    const lines = [`📋 当前计划: ${plan.goal} (${plan.planId})`];
+    for (const s of plan.steps) {
+        const mark = s.status === 'done' ? '✅' : s.status === 'blocked' ? '⛔' : '⬜';
+        lines.push(`  ${mark} ${s.id}: ${s.description}${s.note ? ` — ${s.note}` : ''}`);
+    }
+    if (plan.review) {
+        lines.push(`  📝 审查: ${plan.review.summary} (${plan.review.completedSteps}/${plan.review.totalSteps} 步)`);
+    }
+    return lines.join('\n');
+}