@minko-ai/minko 0.1.0 → 0.1.1

package/dist/agent/loop.js

@@ -0,0 +1,337 @@
+import path from 'node:path';
+import { parseToolArguments } from "../providers/types.js";
+import { toolSpecs } from "../tools/registry.js";
+import { compactMessages, estimateTokens, isContextWindowError } from "./compact.js";
+import { runHookEvent } from "./hooks.js";
+import { decidePermission } from "./permissions.js";
+import { PLAN_TOOL_NAMES } from "./plan.js";
+import { repairTranscript } from "./transcript.js";
+const MAX_TOOL_OUTPUT = 64 * 1024;
+/** What the model sees in history is capped much lower than what the UI shows,
+ * otherwise every round resends tens of kilobytes and the context balloons. */
+const MAX_HISTORY_OUTPUT = 8 * 1024;
+/** Safety cap for one request's estimated input. This is deliberately not the
+ * cumulative usage of a turn: every tool round resends the conversation, so
+ * summing rounds would stop long tasks that still fit the model's window. */
+const REQUEST_BUDGET = 400000;
+const DENIED_READONLY = '当前权限模式是「禁止访问文件」，这次调用没有执行。运行 minko power 可以修改。';
+const DENIED_WORKSPACE = '当前权限模式是「工作区权限」，只能读写当前工作目录内的内容，这次调用没有执行。';
+function outsideWorkspace(args, cwd) {
+    const raw = typeof args.path === 'string' ? args.path : undefined;
+    if (!raw) {
+        return false;
+    }
+    const target = path.resolve(cwd, raw);
+    const relative = path.relative(cwd, target);
+    return relative.startsWith('..') || path.isAbsolute(relative);
+}
+/** 400000 → "40", 1240000 → "124", 9500 → "0.9". */
+function formatWanTokens(tokens) {
+    const wan = tokens / 10000;
+    return wan >= 10 ? String(Math.round(wan)) : wan.toFixed(1);
+}
+export async function runAgent(options) {
+    const { provider, tools, cwd, signal, approval, hooks } = options;
+    const power = options.power ?? 'restricted';
+    const specs = toolSpecs(tools);
+    const messages = options.messages.slice();
+    const maxRounds = options.maxRounds ?? 40;
+    const usage = { input: 0, output: 0 };
+    let rounds = 0;
+    const compactConfig = {
+        maxEstimatedTokens: options.compaction?.maxTokens ?? 100_000,
+        preserveRecent: options.compaction?.preserveRecent ?? 4,
+    };
+    const contextRecoveryPreserve = [4, 2, 1, 0];
+    let contextRecoveries = 0;
+    for (let round = 0; round < maxRounds; round += 1) {
+        if (signal.aborted) {
+            break;
+        }
+        const compacted = compactMessages(messages, compactConfig);
+        if (compacted.removed > 0) {
+            messages.splice(0, messages.length, ...compacted.messages);
+            hooks.onNotice?.('上下文已压缩：较早的 ' + compacted.removed + ' 条消息已折叠为摘要');
+        }
+        // The cap applies to what is about to be sent, not to the summed input of
+        // every round in this turn. Compact once more when the current request is
+        // still oversized; only stop when even the preserved tail is too large.
+        let estimated = estimateTokens(messages);
+        if (estimated > REQUEST_BUDGET) {
+            const forced = compactMessages(messages, {
+                maxEstimatedTokens: 0,
+                preserveRecent: compactConfig.preserveRecent,
+            });
+            if (forced.removed > 0) {
+                messages.splice(0, messages.length, ...forced.messages);
+                estimated = estimateTokens(messages);
+                hooks.onNotice?.('当前请求约 ' + formatWanTokens(estimated) + ' 万 token，已压缩较早内容后继续');
+            }
+            if (estimated > REQUEST_BUDGET) {
+                hooks.onNotice?.('当前请求约 ' + formatWanTokens(estimated) + ' 万 token，超过单次上限且无法再压缩；'
+                    + '请把任务拆小，或用 /new 开新会话');
+                break;
+            }
+        }
+        rounds += 1;
+        let result;
+        for (;;) {
+            try {
+                result = await provider.stream(messages, specs, {
+                    onText: hooks.onText,
+                    onReasoning: hooks.onReasoning,
+                    onRetry: (info) => {
+                        const seconds = (info.delayMs / 1000).toFixed(1);
+                        hooks.onNotice?.('请求失败，' + seconds + ' 秒后第 ' + info.attempt + ' 次重试');
+                    },
+                    onFallback: (info) => {
+                        hooks.onNotice?.('服务商 ' + info.from + ' 失败，切换到 ' + info.to);
+                    },
+                }, signal);
+                break;
+            }
+            catch (error) {
+                if (signal.aborted) {
+                    throw error;
+                }
+                if (contextRecoveries < contextRecoveryPreserve.length && isContextWindowError(error)) {
+                    const preserve = contextRecoveryPreserve[contextRecoveries];
+                    contextRecoveries += 1;
+                    const forced = compactMessages(messages, {
+                        maxEstimatedTokens: 0,
+                        preserveRecent: preserve,
+                    });
+                    if (forced.removed > 0) {
+                        messages.splice(0, messages.length, ...forced.messages);
+                        hooks.onNotice?.('上下文超限，已压缩较早内容后重试（保留 ' + preserve + ' 条最近消息）');
+                        continue;
+                    }
+                }
+                throw error;
+            }
+        }
+        usage.input += result.usage.input;
+        usage.output += result.usage.output;
+        if (result.usage.cached && result.usage.cached > 0) {
+            usage.cached = (usage.cached ?? 0) + result.usage.cached;
+        }
+        const assistant = {
+            role: 'assistant',
+            content: result.text,
+            toolCalls: result.toolCalls,
+            reasoning: result.reasoning.length > 0 ? result.reasoning : undefined,
+        };
+        messages.push(assistant);
+        hooks.onAssistantMessage?.(assistant);
+        if (result.toolCalls.length === 0) {
+            break;
+        }
+        for (const call of result.toolCalls) {
+            if (signal.aborted) {
+                break;
+            }
+            const output = await executeTool(call, tools, cwd, signal, approval, power, hooks, options.permissions, options.toolHooks, options.planState, options.config, options.approvalStore);
+            messages.push({
+                role: 'tool',
+                toolCallId: call.id,
+                name: call.name,
+                content: output,
+            });
+            hooks.onAssistantMessage?.(messages[messages.length - 1]);
+        }
+    }
+    // An abort or a provider failure can leave an assistant tool call without
+    // its result. Fill those holes so the session stays valid when resumed.
+    const repaired = repairTranscript(messages);
+    return { messages: repaired.messages, usage, rounds };
+}
+async function executeTool(call, tools, cwd, signal, approval, power, hooks, permissions, toolHooks, planState, config, approvalStore) {
+    const tool = tools.find((candidate) => candidate.spec.name === call.name);
+    const startedAt = Date.now();
+    let args = {};
+    try {
+        args = parseToolArguments(call.arguments);
+    }
+    catch (error) {
+        const message = '工具参数不是合法 JSON：' + (error instanceof Error ? error.message : String(error));
+        hooks.onToolEnd?.(call, { ok: false, output: message, ms: 0 });
+        return message;
+    }
+    if (!tool) {
+        const message = '没有名为 ' + call.name + ' 的工具。可用工具：' + tools.map((item) => item.spec.name).join('、');
+        hooks.onToolEnd?.(call, { ok: false, output: message, ms: 0 });
+        return message;
+    }
+    hooks.onToolStart?.(call, args);
+    try {
+        const pre = await runHookEvent({
+            event: 'PreToolUse',
+            config: toolHooks,
+            toolName: call.name,
+            toolInput: JSON.stringify(args),
+            signal,
+        });
+        if (pre.cancelled) {
+            return deniedTool(call, hooks, startedAt, '已中断，hook 取消了这个工具调用。');
+        }
+        if (pre.denied || pre.failed) {
+            const reason = pre.messages.length > 0 ? pre.messages.join('；') : 'hook 判定阻止';
+            return deniedTool(call, hooks, startedAt, '工具调用被 hook 阻止：' + reason);
+        }
+        if (pre.updatedInput !== undefined) {
+            try {
+                const parsed = JSON.parse(pre.updatedInput);
+                if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    args = parsed;
+                }
+            }
+            catch {
+                // Keep the model's original arguments when the hook sends invalid JSON.
+            }
+        }
+        const rule = decidePermission(permissions, call.name, args);
+        if (rule === 'deny' || pre.permission === 'deny') {
+            const reason = pre.permissionReason ?? '匹配到 deny 规则';
+            return deniedTool(call, hooks, startedAt, '权限规则拒绝了这个工具调用：' + call.name + '（' + reason + '）。');
+        }
+        if (planState?.planMode && !tool.readOnly && !PLAN_TOOL_NAMES.has(call.name)) {
+            return deniedTool(call, hooks, startedAt, '计划模式只允许只读调查和计划工具；请先调用 exit_plan_mode 提交计划，或让用户退出计划模式。');
+        }
+        if (power === 'readonly') {
+            hooks.onToolEnd?.(call, { ok: false, output: DENIED_READONLY, ms: Date.now() - startedAt });
+            return DENIED_READONLY;
+        }
+        const needsApproval = !tool.readOnly
+            && (tool.needsApproval ? tool.needsApproval(args, cwd) : true);
+        if (power === 'workspace' && !PLAN_TOOL_NAMES.has(call.name)) {
+            const outside = outsideWorkspace(args, cwd);
+            if ((!tool.readOnly && needsApproval) || (tool.readOnly && outside)) {
+                hooks.onToolEnd?.(call, { ok: false, output: DENIED_WORKSPACE, ms: Date.now() - startedAt });
+                return DENIED_WORKSPACE;
+            }
+        }
+        const forcedAsk = rule === 'ask' || pre.permission === 'ask';
+        const ruleAllows = rule === 'allow' || pre.permission === 'allow';
+        const autoAllows = power === 'full' || approval === 'auto';
+        const needsPrompt = forcedAsk || (!autoAllows && !ruleAllows && needsApproval);
+        let approved = true;
+        if (needsPrompt) {
+            const token = approvalStore?.consume(call.name, args) ?? null;
+            if (token) {
+                hooks.onNotice?.('使用审批令牌 ' + token.id + '（'
+                    + token.uses + '/' + token.maxUses + '）');
+            }
+            else {
+                approved = await hooks.approve({
+                    tool: tool.spec.name,
+                    title: forcedAsk ? '规则要求确认' : approvalTitle(tool.spec.name),
+                    detail: describeCall(tool.spec.name, args)
+                        + (pre.permissionReason ? '（' + pre.permissionReason + '）' : ''),
+                    danger: tool.spec.name === 'run_shell' ? 'exec' : 'write',
+                });
+            }
+        }
+        if (!approved) {
+            return deniedTool(call, hooks, startedAt, forcedAsk
+                ? '规则要求确认，用户拒绝了这个工具调用。'
+                : '用户拒绝执行这个工具调用，没有产生任何改动。');
+        }
+        let output;
+        let failed = false;
+        try {
+            output = await withTimeout(tool.run(args, {
+                cwd,
+                signal,
+                approve: hooks.approve,
+                config,
+                planMode: Boolean(planState?.planMode),
+            }), signal, 120000);
+        }
+        catch (error) {
+            failed = true;
+            output = '工具执行失败：' + (error instanceof Error ? error.message : String(error));
+        }
+        const post = await runHookEvent({
+            event: failed ? 'PostToolUseFailure' : 'PostToolUse',
+            config: toolHooks,
+            toolName: call.name,
+            toolInput: JSON.stringify(args),
+            toolOutput: output,
+            isError: failed,
+            signal,
+        });
+        if (pre.messages.length > 0 || post.messages.length > 0) {
+            output = appendHookMessages(output, [...pre.messages, ...post.messages]);
+        }
+        if (post.denied || post.failed) {
+            output = '[hook] ' + (post.messages.join('；') || 'hook 判定失败') + '\n' + output;
+        }
+        const clipped = output.length > MAX_TOOL_OUTPUT
+            ? output.slice(0, MAX_TOOL_OUTPUT) + '\n（输出过长，已截断）'
+            : output;
+        hooks.onToolEnd?.(call, { ok: !failed, output: clipped, ms: Date.now() - startedAt });
+        return clipped.length > MAX_HISTORY_OUTPUT
+            ? clipped.slice(0, MAX_HISTORY_OUTPUT) + '\n…（结果过长，已截断）'
+            : clipped;
+    }
+    catch (error) {
+        const message = '工具执行失败：' + (error instanceof Error ? error.message : String(error));
+        hooks.onToolEnd?.(call, { ok: false, output: message, ms: Date.now() - startedAt });
+        return message;
+    }
+}
+function deniedTool(call, hooks, startedAt, message) {
+    hooks.onToolEnd?.(call, { ok: false, output: message, ms: Date.now() - startedAt });
+    return message;
+}
+function appendHookMessages(output, messages) {
+    if (messages.length === 0) {
+        return output;
+    }
+    const block = '[hook] ' + messages.join('\n[hook] ');
+    return output.length > 0 ? output + '\n' + block : block;
+}
+function approvalTitle(name) {
+    if (name === 'run_shell') {
+        return '执行命令';
+    }
+    if (name === 'exit_plan_mode') {
+        return '确认计划';
+    }
+    if (name === 'todo_write' || name === 'enter_plan_mode') {
+        return '计划';
+    }
+    return '修改文件';
+}
+function describeCall(name, args) {
+    if (name === 'run_shell') {
+        return String(args.command ?? '');
+    }
+    if (name === 'exit_plan_mode') {
+        return '提交计划并退出计划模式';
+    }
+    if (name === 'enter_plan_mode') {
+        return '进入计划模式';
+    }
+    if (name === 'todo_write') {
+        const todos = Array.isArray(args.todos) ? args.todos.length : 0;
+        return '更新 ' + todos + ' 项待办';
+    }
+    if (name === 'write_file') {
+        const content = typeof args.content === 'string' ? args.content : '';
+        return String(args.path ?? '') + '（' + content.length + ' 字符）';
+    }
+    return String(args.path ?? '');
+}
+function withTimeout(promise, signal, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('工具执行超时')), ms);
+        const onAbort = () => reject(new Error('已中断'));
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => { cleanup(); resolve(value); }, (error) => { cleanup(); reject(error); });
+    });
+}

package/dist/agent/memory.js

@@ -0,0 +1,159 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { minkoHome } from "../config/paths.js";
+const MEMORY_TYPES = ['user', 'feedback', 'project', 'reference'];
+const MAX_CONTENT = 20_000;
+export function defaultMemoryDir() {
+    return path.join(minkoHome(), 'memory');
+}
+export function writeMemory(dir, input) {
+    const name = input.name.trim();
+    const description = input.description.trim();
+    const content = input.content.trim();
+    if (name.length === 0 || name.length > 80) {
+        throw new Error('name 必须是 1-80 个字符');
+    }
+    if (description.length === 0 || description.length > 200) {
+        throw new Error('description 必须是 1-200 个字符');
+    }
+    if (!MEMORY_TYPES.includes(input.type)) {
+        throw new Error('type 必须是 user / feedback / project / reference');
+    }
+    if (content.length === 0 || content.length > MAX_CONTENT) {
+        throw new Error('content 必须是 1-' + MAX_CONTENT + ' 个字符');
+    }
+    const slug = slugFor(name);
+    const file = path.join(dir, slug + '.md');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, [
+        '---',
+        'name: ' + oneLine(name),
+        'description: ' + oneLine(description),
+        'type: ' + input.type,
+        '---',
+        content,
+    ].join('\n'), 'utf8');
+    updateIndex(dir, name, description, slug);
+    return file;
+}
+export function readMemory(dir, name) {
+    const file = path.join(dir, slugFor(name.trim()) + '.md');
+    try {
+        const raw = fs.readFileSync(file, 'utf8');
+        const frontmatter = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+        return (frontmatter ? raw.slice(frontmatter[0].length) : raw).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function listMemoryIndex(dir) {
+    try {
+        return fs.readFileSync(path.join(dir, 'MEMORY.md'), 'utf8').trim();
+    }
+    catch {
+        return '';
+    }
+}
+export function loadMemoryContext(dir) {
+    const index = listMemoryIndex(dir);
+    if (index.length === 0) {
+        return undefined;
+    }
+    return { dir, index };
+}
+/** Read/write tools over a user-owned memory directory. */
+export function createMemoryTools(dir) {
+    const write = {
+        readOnly: false,
+        // Writing to Minko's own memory store is low-risk and should not prompt.
+        needsApproval: () => false,
+        spec: {
+            name: 'memory_write',
+            description: '把跨会话仍有价值的信息写入长期记忆（用户偏好、纠正、项目背景）。不要保存代码结构、临时任务状态。',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: '短名称，1-80 字符' },
+                    description: { type: 'string', description: '一句话摘要，1-200 字符' },
+                    type: {
+                        type: 'string',
+                        enum: ['user', 'feedback', 'project', 'reference'],
+                    },
+                    content: { type: 'string', description: '记忆正文，最多 20000 字符' },
+                },
+                required: ['name', 'description', 'type', 'content'],
+                additionalProperties: false,
+            },
+        },
+        async run(args) {
+            const name = typeof args.name === 'string' ? args.name : '';
+            const description = typeof args.description === 'string' ? args.description : '';
+            const type = typeof args.type === 'string' ? args.type : 'user';
+            const content = typeof args.content === 'string' ? args.content : '';
+            const file = writeMemory(dir, { name, description, type, content });
+            return '已保存记忆：' + name.trim() + '（' + type + '）\n' + file;
+        },
+    };
+    const read = {
+        readOnly: true,
+        spec: {
+            name: 'memory_read',
+            description: '读取一条长期记忆的完整内容；MEMORY.md 索引会自动出现在上下文里。',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: '记忆名称' },
+                },
+                required: ['name'],
+                additionalProperties: false,
+            },
+        },
+        async run(args) {
+            const name = typeof args.name === 'string' ? args.name.trim() : '';
+            if (name.length === 0) {
+                throw new Error('缺少 name 参数');
+            }
+            const content = readMemory(dir, name);
+            if (content === null) {
+                throw new Error('没有找到记忆「' + name + '」。先用 memory_write 创建。');
+            }
+            return '记忆「' + name + '」：\n' + content;
+        },
+    };
+    return [write, read];
+}
+function updateIndex(dir, name, description, slug) {
+    const indexPath = path.join(dir, 'MEMORY.md');
+    let lines = [];
+    try {
+        lines = fs.readFileSync(indexPath, 'utf8').split(/\r?\n/);
+    }
+    catch {
+        // First entry.
+    }
+    const link = '(' + slug + '.md)';
+    lines = lines.filter((line) => !line.includes(link));
+    while (lines.length > 0 && lines[lines.length - 1].trim().length === 0) {
+        lines.pop();
+    }
+    if (lines.length === 0) {
+        lines.push('# Memory index', '');
+    }
+    lines.push('- [' + oneLine(name) + '](' + slug + '.md) — ' + oneLine(description));
+    fs.writeFileSync(indexPath, lines.join('\n') + '\n', 'utf8');
+}
+function slugFor(name) {
+    const base = name.toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40);
+    if (base.length > 0) {
+        return base;
+    }
+    return 'm-' + crypto.createHash('sha1').update(name).digest('hex').slice(0, 8);
+}
+function oneLine(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}

package/dist/agent/permissions.js

@@ -0,0 +1,71 @@
+/**
+ * Rule syntax:
+ *   run_shell
+ *   run_shell(git push*)
+ *   write_file(src/*)
+ * A pattern without `*` or `?` is a case-insensitive prefix match.
+ */
+export function parsePermissionRule(raw) {
+    const trimmed = raw.trim();
+    const match = trimmed.match(/^([A-Za-z0-9_.-]+)(?:\((.*)\))?$/s);
+    if (!match) {
+        return null;
+    }
+    const pattern = match[2] === undefined ? undefined : match[2].trim();
+    return pattern && pattern.length > 0
+        ? { tool: match[1], pattern }
+        : { tool: match[1] };
+}
+export function permissionSubject(toolName, args) {
+    if (toolName === 'run_shell' && typeof args.command === 'string') {
+        return args.command;
+    }
+    if (typeof args.path === 'string') {
+        return args.path.replace(/\\/g, '/');
+    }
+    if (typeof args.pattern === 'string') {
+        return args.pattern.replace(/\\/g, '/');
+    }
+    try {
+        return JSON.stringify(args) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+export function ruleMatches(rule, toolName, args) {
+    if (rule.tool.toLowerCase() !== toolName.toLowerCase()) {
+        return false;
+    }
+    if (rule.pattern === undefined) {
+        return true;
+    }
+    const subject = permissionSubject(toolName, args);
+    const pattern = rule.pattern.replace(/\\/g, '/');
+    if (/[*?]/.test(pattern)) {
+        return globToRegExp(pattern).test(subject);
+    }
+    return subject.toLowerCase().startsWith(pattern.toLowerCase());
+}
+/** deny > ask > allow; the first matching list wins. */
+export function decidePermission(rules, toolName, args) {
+    if (!rules) {
+        return undefined;
+    }
+    for (const decision of ['deny', 'ask', 'allow']) {
+        for (const raw of rules[decision]) {
+            const rule = parsePermissionRule(raw);
+            if (rule && ruleMatches(rule, toolName, args)) {
+                return decision;
+            }
+        }
+    }
+    return undefined;
+}
+function globToRegExp(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.');
+    return new RegExp('^' + escaped + '$', 'i');
+}

package/dist/agent/plan.js

@@ -0,0 +1,118 @@
+export const PLAN_TOOL_NAMES = new Set(['todo_write', 'enter_plan_mode', 'exit_plan_mode']);
+export function normalizeTodos(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    for (const raw of value) {
+        if (out.length >= 50) {
+            break;
+        }
+        if (raw === null || typeof raw !== 'object') {
+            continue;
+        }
+        const record = raw;
+        if (typeof record.content !== 'string') {
+            continue;
+        }
+        const content = record.content.trim().slice(0, 500);
+        if (content.length === 0) {
+            continue;
+        }
+        const status = record.status === 'in_progress' || record.status === 'completed'
+            ? record.status
+            : 'pending';
+        out.push({ content, status });
+    }
+    return out;
+}
+export function renderTodos(todos) {
+    if (todos.length === 0) {
+        return '（清单为空）';
+    }
+    return todos.map((todo) => {
+        const mark = todo.status === 'completed' ? 'x' : todo.status === 'in_progress' ? '~' : ' ';
+        return '- [' + mark + '] ' + todo.content;
+    }).join('\n');
+}
+/**
+ * Plan/Todo tools operate on the session's plan state. They are created per
+ * session so state survives turns and is persisted with the session meta.
+ */
+export function createPlanTools(state) {
+    const todoWrite = {
+        readOnly: true,
+        spec: {
+            name: 'todo_write',
+            description: '维护多步骤任务的待办清单；每次调用整表替换。状态：pending / in_progress / completed。',
+            parameters: {
+                type: 'object',
+                properties: {
+                    todos: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                content: { type: 'string' },
+                                status: {
+                                    type: 'string',
+                                    enum: ['pending', 'in_progress', 'completed'],
+                                },
+                            },
+                            required: ['content'],
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                required: ['todos'],
+                additionalProperties: false,
+            },
+        },
+        async run(args) {
+            const todos = normalizeTodos(args.todos);
+            state.todos = todos;
+            return '清单已更新（' + todos.length + ' 项）：\n' + renderTodos(todos);
+        },
+    };
+    const enterPlanMode = {
+        readOnly: true,
+        spec: {
+            name: 'enter_plan_mode',
+            description: '进入只读计划模式：先调查，再提交分步骤计划；此模式不能写文件或执行命令。',
+            parameters: { type: 'object', properties: {}, additionalProperties: false },
+        },
+        async run() {
+            state.planMode = true;
+            return '已进入计划模式：只能只读调查；完成后调用 exit_plan_mode 提交计划。';
+        },
+    };
+    const exitPlanMode = {
+        readOnly: false,
+        needsApproval: () => true,
+        spec: {
+            name: 'exit_plan_mode',
+            description: '提交计划并退出计划模式；需要用户确认。',
+            parameters: {
+                type: 'object',
+                properties: {
+                    plan: {
+                        type: 'string',
+                        description: '分步骤计划：改哪些文件、怎么验证、有什么风险。',
+                    },
+                },
+                required: ['plan'],
+                additionalProperties: false,
+            },
+        },
+        async run(args) {
+            const plan = typeof args.plan === 'string' ? args.plan.trim() : '';
+            if (plan.length === 0) {
+                throw new Error('缺少 plan 参数');
+            }
+            state.planMode = false;
+            state.plan = plan;
+            return '计划已确认，退出计划模式：\n\n' + plan;
+        },
+    };
+    return [todoWrite, enterPlanMode, exitPlanMode];
+}