mocode-ai 0.2.8 → 0.2.9

package/dist/config/index.js

@@ -91,7 +91,14 @@ ${PLATFORM_NOTE}
 - Use web_search for information beyond training data (new versions, news, real-time data, latest APIs); don't answer potentially outdated info from memory.
 - Use web_fetch to read a specific URL (a link from search results, or a URL given by the user); it only fetches static HTML — if a JS-rendered page yields no body, switch to web_search (its results include cleaned body text).
 - Call ask_human when you hit a decision point requiring user input (multiple implementation approaches, unclear intent, or needing extra info to proceed) — list options for the user to pick (they can also choose "custom input" to answer freely). Don't call it frequently when the task is clear and you can decide yourself; if the user cancels, switch approach or proceed with available info — don't re-ask the same question.
-- **Drop irrelevant context** (use sparingly): call drop_context to stub-replace tool results in history that are BOTH (a) irrelevant to the current task AND (b) large (the freed tokens must clearly exceed the ~300 tokens the call itself costs — roughly only worth it when targeting ≥2 bulky results, e.g. wide grep/read sweeps that returned mostly-irrelevant hits). The call itself adds a tool-call round-trip, so don't call it for one small result or when you're near done. It preserves tool_call_id pairing (only content changes); the system prompt and current turn are never dropped. Use filters (toolNames / contains) to target precisely.
+- **Drop irrelevant context** (use sparingly): call drop_context to stub-replace tool results in history that are BOTH (a) irrelevant to the current task AND (b) large (the freed tokens must clearly exceed the ~300 tokens the call itself costs — roughly only worth it when targeting ≥2 bulky results, e.g. wide grep/read sweeps that returned mostly-irrelevant hits). The call itself adds a tool-call round-trip, so don't call it for one small result or when you're near done. It preserves tool_call_id pairing (only content changes); the system prompt and current turn are never dropped. Use filters (toolNames / contains) to target precisely.
+
+## Large file writes (avoid token-cap truncation)
+- \`write_file\` / \`edit_file\` arguments are part of the model's JSON output — a single tool call's content > ~5K tokens risks mid-stream truncation when the model's max output (default 8K–16K tokens) is exceeded, producing a "arguments 不是合法 JSON" error. Even with \`MAX_TOKENS=32000\` set, huge files still risk truncation.
+- **For large files (rough threshold: >200 lines OR >5K tokens of content)**, default to one of these strategies instead of one giant \`write_file\`:
+  - **Skeleton + edit**: \`write_file\` a small skeleton (head + placeholders), then call \`edit_file\` repeatedly to append/replace sections — each edit stays well under the cap, and partial progress survives a stream error.
+  - **Shell heredoc**: \`run_command\` with \`cat > path <<'EOF' ... EOF\` (bash) or \`Set-Content -Path ... -Value @"..."@\` (PowerShell) — the file content bypasses the model's JSON output entirely, so no token cap applies. Prefer this for generated/structured content (JSON config, full HTML pages, large code dumps).
+- For small files (≤200 lines, ≤5K tokens) just use \`write_file\` directly — no need to over-engineer.
 
 ## Failure Handling
 - Tools return errors as strings (edit_file no match or non-unique, run_command non-zero exit, etc.). Analyze the root cause, adjust, then retry — don't resend the same call verbatim.
@@ -112,6 +119,12 @@ ${PLATFORM_NOTE}
 - Default is AUTO mode: you research and execute with all tools (read/edit/run_command/memory/web/skills).
 - For complex or multi-step tasks, the user may switch to PLAN mode (Shift+Tab): your editing/command/memory-write tools are then removed from your tool list, and you must research with read-only tools only and produce a step-by-step plan (no execution). On approval the session returns to auto mode to execute the plan.
 
+## Working notepad (todolist) — checklist for complex tasks
+- For **complex multi-step tasks** (≥3 file changes OR ≥5 tool calls expected OR user says "先计划再执行" / "plan then do" / "按步骤来"), call the \`todolist\` tool FIRST to write a plan to \`.mocode/plans/<id>.md\`, then execute step by step, calling \`todolist update\` to mark progress. For trivial single-step tasks, skip it and just execute.
+- The plan is file-backed (survives context compression, user can see/edit). The active plan summary is auto-injected into the system prompt each turn, so you can re-read it via \`todolist read\` whenever you're unsure of your place.
+- Single plan per session: \`todolist create\` refuses if an in-progress plan already exists — finish or abandon it first. After \`todolist finish\`, the plan is archived and a new one can be created.
+- Don't over-use it: for a single edit or a quick lookup, \`todolist\` is overhead. The threshold is "this needs ≥3 steps OR I might forget the plan after context compaction."
+
 ## Termination & Reporting
 - Stop immediately when no more tools are needed; give conclusions directly.
 - Report honestly: say success when successful, say where you're stuck when failing, and mention anything skipped. Reference code in "path:line" format (e.g., src/index.ts:42). Keep it concise.`;

package/dist/context/classifier.js

@@ -38,6 +38,8 @@ const BY_NAME = {
     memory_forget: 'status',
     // summary:子 agent 摘要(轻量)
     task: 'summary',
+    // status:工作记事本 plan(单 plan/会话,文件级;state 一行 chip 即可)
+    todolist: 'status',
 };
 /**
  * 形状启发:对未在 BY_NAME 登记的工具输出做模式识别(为 MCP / 未来工具兜底)。

package/dist/plan/active.js

@@ -0,0 +1,45 @@
+// 活跃 plan 进程级缓存:单 plan/会话的内存状态 + 变更通知。
+//
+// 仿 src/agent/mode.ts 形态:零依赖、setter/getter/listener,不反向引用业务。
+// todo 工具每次改 plan → 调 setActivePlan(newPlan) → listener 触发(repl 刷 status 行 + history[0])。
+// store 仍是文件源(本缓存与之可能短暂不一致——以文件为准,缓存仅供快速读)。
+import { renderPlanChip } from './store.js';
+let active = null;
+const listeners = new Set();
+/** 取当前活跃 plan(完整对象,工具用)。无 → null。 */
+export function getActivePlan() {
+    return active;
+}
+/** 设活跃 plan。同一 id 重复设也走 listener(repl 借此刷 status 行——即使内容未变,显式刷新有助)。 */
+export function setActivePlan(plan) {
+    active = plan;
+    const snap = plan ? toSnapshot(plan) : null;
+    for (const cb of listeners) {
+        try {
+            cb(snap);
+        }
+        catch { /* listener 抛错不阻断其他 listener */ }
+    }
+}
+/** 清活跃 plan(plan finish/abandon 后由 repl/todolist 调)。 */
+export function clearActivePlan() {
+    setActivePlan(null);
+}
+/** 注册活跃 plan 变更监听器。返注销函数(不常用,模式 listener 一次性常驻)。 */
+export function onActivePlanChange(cb) {
+    listeners.add(cb);
+    return () => listeners.delete(cb);
+}
+/** 是否有活跃 plan(in_progress 状态)。finished/abandoned 不算「活跃」。 */
+export function hasActivePlan() {
+    return active !== null && active.status === 'in_progress';
+}
+/** 给 status 行用的极简摘要(避免调用方读 Plan 全字段)。无 → 空串。 */
+/** 状态行 chip 用的短摘要(无 ANSI 颜色,由 layout 上色)。maxWidth 默认 56,留 room 给右段。 */
+export function getActivePlanSummary(maxWidth = 56) {
+    return renderPlanChip(active, maxWidth);
+}
+function toSnapshot(p) {
+    const done = p.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+    return { id: p.id, title: p.title, status: p.status, done, total: p.steps.length };
+}

package/dist/plan/index.js

@@ -0,0 +1,33 @@
+// plan 子系统 barrel:
+//  - store:文件级 CRUD(markdown 解析/序列化,落盘原子)
+//  - active:进程级活跃 plan 缓存 + 变更通知(单 plan/会话)
+//  - buildActivePlanSection:给 systemPrompt 用的活跃 plan 摘要段
+//
+// 被 repl 依赖(注入 systemPrompt + 状态行 + listener 注册)+ tools/builtins/todolist 依赖。
+export { 
+// store
+plansDir, planPath, ensurePlansDir, newPlanId, parsePlan, serializePlan, readPlan, writePlan, deletePlan, updatePlan, listPlans, renderPlanForLLM, renderPlanChip, } from './store.js';
+export { getActivePlan, setActivePlan, clearActivePlan, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from './active.js';
+import { getActivePlan } from './active.js';
+import { renderPlanForLLM } from './store.js';
+const ACTIVE_PLAN_HEADER = '## 当前活跃计划';
+/**
+ * 拼给 systemPrompt 注入的活跃 plan 摘要段。
+ *  - 无活跃 plan → 空串(repl 直接跳过拼接,systemPrompt 长度不变)。
+ *  - 有 → 紧凑 markdown(目标 + 步骤 checkbox + 进度日志末 5 条),header + 内容。
+ *
+ * 触发:setActivePlan 后由 repl listener 调;也供 buildSystemMessage 直接同步取(repl 入口)。
+ * 上限:超 MAX_ACTIVE_PLAN_CHARS 截到尾部(罕见,plan 文件本身就小)。
+ */
+export function buildActivePlanSection() {
+    const p = getActivePlan();
+    if (!p)
+        return '';
+    const body = renderPlanForLLM(p);
+    const full = `${ACTIVE_PLAN_HEADER}\n${body}`;
+    if (full.length <= MAX_ACTIVE_PLAN_CHARS)
+        return full;
+    return full.slice(0, MAX_ACTIVE_PLAN_CHARS) + '\n…(plan 摘要已截断)';
+}
+/** 注入 systemPrompt 的活跃 plan 摘要上限(字符)。 */
+export const MAX_ACTIVE_PLAN_CHARS = 3000;

package/dist/plan/state.js

@@ -0,0 +1,11 @@
+// 活跃 plan 的进程级状态(共享叶子)。
+//
+// 职责:
+//  - 跟踪「当前会话的活跃 plan」——单 plan/会话(state 缓存,store 是文件源)。
+//  - 暴露 onActivePlanChange listener(repl 借此刷 status 行 + history[0])。
+//
+// 与 mode.ts 同形态:零依赖、不落盘、不反向引用业务;被 plan/、tools/builtins/todolist.ts、repl 依赖。
+//
+// 不在子 agent 持久化(子 agent 走 spawn,独立 history,不该继承主 plan——但 plan 文件本身在 sandboxRoot
+// 下,子 agent 仍能 readPlan 看到全部历史 plan;state 缓存不传,只属于主 agent)。
+export { getActivePlan, setActivePlan, clearActivePlan, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from './active.js';

package/dist/plan/store.js

@@ -0,0 +1,351 @@
+// 单 plan 的文件级存储:CRUD + markdown 解析/序列化。
+//
+// 设计目标
+//  - 文件是唯一事实源(抗压缩、可视化、用户可改)。每次写都 atomic(rename 覆盖)。
+//  - 同会话单 plan(state.ts 跟踪「活跃」,本模块不参与并发控制——单进程单活跃 plan 串行调用)。
+//  - 解析宽松:坏 frontmatter / 缺段 → 退化到最小可用 Plan,不抛。
+//  - 序列化稳定:每段顺序固定(frontmatter → 目标 → 步骤 → 进度日志),便于 git diff 友好。
+//
+// 不依赖 agent / ui / llm;仅 node:fs + node:path。仿 memory/store.ts 的「叶子」分层。
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSandboxRoot } from '../sandbox/root.js';
+// ── 路径 ──
+/** plans 目录:<sandboxRoot>/.mocode/plans/。无 sandboxRoot 退到 cwd(防御)。 */
+export function plansDir() {
+    const root = getSandboxRoot() ?? process.cwd();
+    return join(root, '.mocode', 'plans');
+}
+/** 单 plan 文件路径:<root>/.mocode/plans/<id>.md。 */
+export function planPath(id) {
+    return join(plansDir(), `${id}.md`);
+}
+/** 确保 plans 目录存在(惰性,工具每次写前调)。 */
+export function ensurePlansDir() {
+    const d = plansDir();
+    if (!existsSync(d))
+        mkdirSync(d, { recursive: true });
+}
+// ── ID 生成 ──
+/** plan id:YYYY-MM-DDTHH-mm-ss-xxxxxx(本地时间,文件名安全)。xxxxxx = 4 字节随机 hex(防同秒并发撞)。 */
+export function newPlanId(now = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const y = now.getFullYear();
+    const mo = pad(now.getMonth() + 1);
+    const d = pad(now.getDate());
+    const h = pad(now.getHours());
+    const mi = pad(now.getMinutes());
+    const s = pad(now.getSeconds());
+    // crypto 不必要;Math.random 够防同秒撞(碰撞概率 ~1/2^32)
+    const r = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, '0');
+    return `${y}-${mo}-${d}T${h}-${mi}-${s}-${r}`;
+}
+// ── 解析(宽松,坏文件不抛,退化到最小可用 Plan)──
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+const CHECKBOX_RE = /^(\s*)-\s+\[([ xX\/~])\]\s+(\d+)\.\s+(.+?)\s*$/;
+const LOG_RE = /^-\s+(\S+)\s+(.+?)\s*$/;
+/**
+ * 解析 plan 文件为 Plan 对象。失败(无 frontmatter / 段缺失 / 坏 checkbox)→ 退化:
+ *  - 无 frontmatter:把整文当 title 段
+ *  - 缺字段:空串 / 空数组
+ *  - 坏 checkbox:跳过该行,不污染好行
+ * 解析成功但 step id 缺序 / 重号:按出现顺序重排为 1..N(保稳定)。
+ */
+export function parsePlan(raw, fallbackId) {
+    const now = new Date().toISOString();
+    let meta = {};
+    let body = raw;
+    const m = FRONTMATTER_RE.exec(raw);
+    if (m) {
+        meta = parseFrontmatter(m[1]);
+        body = m[2];
+    }
+    const id = meta.id || fallbackId;
+    const title = meta.title || extractFirstHeading(body) || '(无标题)';
+    const status = normalizePlanStatus(meta.status);
+    const created = meta.created || now;
+    const updated = meta.updated || now;
+    const { goal, steps, log } = parseBody(body);
+    // 步骤 id 规范化:1..N(防文件手改致 id 跳号)
+    const normSteps = steps.map((s, i) => ({ ...s, id: i + 1 }));
+    return { id, title, status, created, updated, goal, steps: normSteps, log };
+}
+function parseFrontmatter(s) {
+    const out = {};
+    for (const line of s.split('\n')) {
+        const idx = line.indexOf(':');
+        if (idx <= 0)
+            continue;
+        const k = line.slice(0, idx).trim();
+        const v = line.slice(idx + 1).trim();
+        if (k)
+            out[k] = v;
+    }
+    return out;
+}
+function normalizePlanStatus(s) {
+    if (s === 'finished' || s === 'abandoned')
+        return s;
+    return 'in_progress';
+}
+function extractFirstHeading(body) {
+    const m = /^#\s+(.+?)\s*$/m.exec(body);
+    return m ? m[1] : '';
+}
+function parseBody(body) {
+    const sections = {};
+    const re = /^##\s+(.+?)\s*$/gm;
+    let lastKey = '';
+    let lastStart = -1;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        if (lastKey)
+            sections[lastKey] = body.slice(lastStart, m.index);
+        lastKey = m[1].trim();
+        lastStart = m.index + m[0].length;
+    }
+    if (lastKey)
+        sections[lastKey] = body.slice(lastStart);
+    const goal = (sections['目标'] || sections['Goal'] || '').trim();
+    const stepBlock = sections['步骤'] || sections['Steps'] || '';
+    const logBlock = sections['进度日志'] || sections['Log'] || sections['进度'] || '';
+    const steps = [];
+    for (const line of stepBlock.split('\n')) {
+        const cm = CHECKBOX_RE.exec(line);
+        if (!cm)
+            continue;
+        const marker = cm[2].toLowerCase();
+        const status = marker === 'x' ? 'done' :
+            marker === '/' ? 'in_progress' :
+                marker === '~' ? 'skipped' :
+                    'pending';
+        const id = Number(cm[3]);
+        const title = cm[4].trim();
+        if (!Number.isFinite(id) || id < 1)
+            continue;
+        steps.push({ id, title, status });
+    }
+    const log = [];
+    for (const line of logBlock.split('\n')) {
+        const lm = LOG_RE.exec(line);
+        if (!lm)
+            continue;
+        log.push({ at: lm[1], text: lm[2] });
+    }
+    return { goal, steps, log };
+}
+// ── 序列化 ──
+/** 序列化为 markdown 文本。固定段序:frontmatter → 目标 → 步骤 → 进度日志。 */
+export function serializePlan(p) {
+    const lines = [];
+    lines.push('---');
+    lines.push(`id: ${p.id}`);
+    lines.push(`title: ${p.title}`);
+    lines.push(`status: ${p.status}`);
+    lines.push(`created: ${p.created}`);
+    lines.push(`updated: ${p.updated}`);
+    lines.push('---');
+    lines.push('');
+    lines.push(`# ${p.title}`);
+    lines.push('');
+    lines.push('## 目标');
+    lines.push(p.goal || '(未填写)');
+    lines.push('');
+    lines.push('## 步骤');
+    if (p.steps.length === 0) {
+        lines.push('(无步骤)');
+    }
+    else {
+        for (const s of p.steps) {
+            lines.push(`- [${checkboxMarker(s.status)}] ${s.id}. ${s.title}`);
+        }
+    }
+    lines.push('');
+    lines.push('## 进度日志');
+    if (p.log.length === 0) {
+        lines.push('(无)');
+    }
+    else {
+        for (const e of p.log) {
+            lines.push(`- ${e.at} ${e.text}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function checkboxMarker(s) {
+    switch (s) {
+        case 'done': return 'x';
+        case 'in_progress': return '/';
+        case 'skipped': return '~';
+        case 'failed': return 'x'; // 用 x + log 标 failed(checkbox 集 [ ]/x/[x] 之外的细态不上,降级)
+        case 'pending':
+        default: return ' ';
+    }
+}
+// ── CRUD(直接落盘)──
+/** 读 plan 文件;不存在 → null,坏文件 → fallbackId 最小可用 Plan(不抛,工具契约)。 */
+export function readPlan(id) {
+    const p = planPath(id);
+    if (!existsSync(p))
+        return null;
+    try {
+        return parsePlan(readFileSync(p, 'utf8'), id);
+    }
+    catch {
+        return null;
+    }
+}
+/** 写 plan 文件(atomic:写 .tmp 再 rename)。返回是否成功。 */
+export function writePlan(p) {
+    try {
+        ensurePlansDir();
+        const target = planPath(p.id);
+        const tmp = target + '.tmp';
+        writeFileSync(tmp, serializePlan(p), 'utf8');
+        renameSync(tmp, target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 删 plan 文件;不存在静默 ok。 */
+export function deletePlan(id) {
+    const p = planPath(id);
+    if (!existsSync(p))
+        return true;
+    try {
+        unlinkSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 原子读-改-写:读 → mutator 改 → 写。mutator 返回 false 视为"无改动",跳过写。
+ * mutator 抛错 → 写失败 → 返 null(不抛,工具契约)。
+ *
+ * mutator 同步:本 store 走同步 fs,mutator 必须同步(返 Promise 视为"无信号"——返原对象);
+ *  设计如此以避免把 fs API 改成 async(同步 fs 在 node 单 tick 原子,无需锁)。
+ */
+export function updatePlan(id, mutator) {
+    const cur = readPlan(id);
+    if (!cur)
+        return null;
+    let next;
+    try {
+        next = mutator(cur);
+    }
+    catch {
+        return null;
+    }
+    if (next === false)
+        return cur; // 无改动:返原对象
+    next.updated = new Date().toISOString();
+    if (!writePlan(next))
+        return null;
+    return next;
+}
+/** 列 plans 目录下所有 plan(按 updated 倒序,最新在前)。解析失败的跳过。 */
+export function listPlans() {
+    const dir = plansDir();
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => n.endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        const id = n.slice(0, -3);
+        const p = readPlan(id);
+        if (p)
+            out.push(p);
+    }
+    out.sort((a, b) => (a.updated < b.updated ? 1 : a.updated > b.updated ? -1 : 0));
+    return out;
+}
+// ── 渲染(给 LLM / UI 用)──
+/** 把 Plan 渲成给 LLM 看的紧凑摘要(多行文本)。 */
+export function renderPlanForLLM(p) {
+    const lines = [];
+    lines.push(`# ${p.title} [${p.status}]`);
+    if (p.goal)
+        lines.push(`\n## 目标\n${p.goal}`);
+    const done = p.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+    lines.push(`\n## 步骤 (${done}/${p.steps.length} 完成)`);
+    if (p.steps.length === 0) {
+        lines.push('(无)');
+    }
+    else {
+        for (const s of p.steps) {
+            lines.push(`- [${checkboxMarker(s.status)}] ${s.id}. ${s.title}`);
+        }
+    }
+    if (p.log.length > 0) {
+        lines.push(`\n## 进度日志(最近 ${Math.min(p.log.length, 5)} 条)`);
+        for (const e of p.log.slice(-5))
+            lines.push(`- ${e.at} ${e.text}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * 状态行 chip 的短摘要:`plan: 标题 (done/total) ▸ <当前 in_progress 步骤>`。
+ * 无活跃 plan → 空串。
+ *
+ * 字符截断(非终端宽,固定长度 ~50 字符,方便状态行收纳):
+ *  - 标题(plan 标题):超 10 字截断,加 "..."
+ *  - 步骤标题:超 17 字截断,加 "..."
+ *  - 例:`plan: 3D 贪吃蛇游戏 (0/9) ▸ 1. 搭建项目骨架:创建 snake3d...`
+ *
+ * 当前步骤取 status=in_progress;无 in_progress 但有 pending 时回退到第一项 pending
+ * (LLM 刚标记某步 done 还没动 next 时,这样能看清下一步)。
+ * 全 done → 不带 tail;finished → 拼「✓ N/N」。
+ *
+ * maxWidth 是软上限:极端窄(<26)时只保 head+count 不带 tail;否则按上述字符限。
+ */
+const PLAN_TITLE_MAX = 10;
+const STEP_TITLE_MAX = 17;
+const TRUNC_DOTS = '...';
+export function renderPlanChip(p, maxWidth = 56) {
+    if (!p)
+        return '';
+    const title = truncateByChars(p.title, PLAN_TITLE_MAX);
+    const head = p.status === 'finished'
+        ? `plan ✓ ${title}`
+        : `plan: ${title}`;
+    const total = p.steps.length;
+    const done = p.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+    const count = `(${done}/${total})`;
+    const fixed = `${head} ${count}`;
+    // 极窄:没空间塞步骤,只保 head+count
+    if (maxWidth < 26)
+        return fixed;
+    const cur = p.status === 'in_progress'
+        ? p.steps.find((s) => s.status === 'in_progress')
+            ?? p.steps.find((s) => s.status === 'pending')
+        : null; // finished / abandoned → 不显当前步
+    if (!cur)
+        return fixed;
+    const stepTitle = truncateByChars(cur.title, STEP_TITLE_MAX);
+    return `${fixed} ▸ ${cur.id}. ${stepTitle}`;
+}
+/** 字符数截断(非显示宽):超 max 字符截到 max + "..."(3 字符省略号固定)。
+ *  <= max → 原样返回;> max → 前 max 字符 + "..."。 */
+function truncateByChars(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + TRUNC_DOTS;
+}
+function truncateForChip(s, max = 18) {
+    if (s.length <= max)
+        return s;
+    if (max <= 1)
+        return '…';
+    return s.slice(0, max - 1) + '…';
+}

package/dist/repl/index.js

@@ -17,8 +17,9 @@ import { tools } from '../tools/registry.js';
 import { estimateMessagesTokens, reconfigureClient, } from '../llm/index.js';
 import { compactHistory, contextState, newSessionId, saveSession, loadSession, listSessions, } from '../session/index.js';
 import { listTurns, planRollback, applyRollback, persistSnapshots, loadSnapshots, rebuildFromHistory, resetState, } from '../rollback/index.js';
-import { listSkills, effectiveSystemPrompt } from '../skills/index.js';
+import { listSkills, effectiveSystemPrompt, } from '../skills/index.js';
 import { buildMemorySection, buildMemoryIndexSection, kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, loadAll, } from '../memory/index.js';
+import { buildActivePlanSection, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from '../plan/index.js';
 /**
  * readline 的 prompt 必须是纯文本(无 ANSI):readline 按字符数算光标位置,
  * 颜色码会让光标错位、编辑时漂移。颜色只用在直接 stdout.write 的横幅 / 工具行 / 回复。
@@ -138,13 +139,14 @@ function renderContextBarInline(history) {
     const pctCol = pct >= config.compactThreshold ? ui.yellow : ui.cyan;
     return `${ui.gray}[${pctCol}${bar}${ui.reset}] ${pctCol}${Math.round(pct * 100)}%${ui.reset} ${ui.dim}${k(est)}/${k(win)}${ui.reset}`;
 }
-/** 状态行基线:模型 / context / cwd / 模式标识。repl 在轮次边界与切模式时调,刷新 context 用量与 mode chip。 */
+/** 状态行基线:模型 / context / cwd / 模式标识 / 活跃 plan chip。repl 在轮次边界、切模式、plan 变更时调。 */
 function refreshStatusBase(history) {
     layout.setStatusBase({
         model: config.model,
         contextBar: renderContextBarInline(history),
         cwd: process.cwd(),
         modeTag: getAgentMode() === 'plan' ? 'plan' : 'auto',
+        planSummary: hasActivePlan() ? getActivePlanSummary(process.stdout.columns ?? 80) : '',
     });
 }
 /** 命令 → 运行态状态文字 + 底栏 dim 占位。 */
@@ -378,10 +380,12 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
     setSandboxRoot(sandboxRootOverride ?? config.sandboxRoot ?? process.cwd());
     // 构造系统提示:auto 用 base;plan 在 config.systemPrompt 后追加 PLAN_MODE_SUFFIX。
     // 切模式时 applyMode 重算 history[0](history[0] 恒 system,compaction 保它,不破坏)。
+    // 活跃 plan 摘要拼在 memory 段后(systemPrompt 的尾段),todo 工具变更后 listener 重写 history[0]。
     const buildSystemMessage = (planMode) => effectiveSystemPrompt(config.systemPrompt +
         (planMode ? PLAN_MODE_SUFFIX : '') +
         buildMemorySection() +
-        buildMemoryIndexSection());
+        buildMemoryIndexSection() +
+        buildActivePlanSection());
     // 有预加载(--resume)则用它,并把 history[0] 刷成当前 system prompt(config 可能已变);
     // 否则新会话只塞 system 提示(默认 auto)。
     const history = initialHistory && initialHistory.length
@@ -447,6 +451,16 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
         applyMode(m === 'plan');
         refreshStatusBase(history);
     });
+    // 注册活跃 plan 变更监听器:todolist 工具每次 create/update/add_step/finish 后调 setActivePlan,
+    // 触发本 listener 重写 history[0](plan 摘要段刷新)+ 刷状态行 plan chip。
+    // 不调 drawStatusBar:INPUT 态靠 prompt.ts redraw;RUNNING 态靠 200ms turnTimer 兜底。
+    // listener 内访问 history 是闭包捕获,保持同一引用(repl 持有)。
+    onActivePlanChange(() => {
+        if (history[0]?.role === 'system') {
+            history[0] = { role: 'system', content: buildSystemMessage(getAgentMode() === 'plan') };
+        }
+        refreshStatusBase(history);
+    });
     /**
      * 回滚子流程(由 /rollback 触发):菜单(↑/↓)选轮次 → 选中第 X 轮 = 删第 X 轮及之后 + 预填第 X 轮 user 输入
      * (仿 Claude Code rewind,Enter 重新跑该轮);被删轮次的文件改动走二选一菜单(promptRevertChoice:

package/dist/sandbox/policy.js

@@ -17,6 +17,7 @@ export const SANDBOX_EXEMPT_TOOLS = new Set([
     'ask_human', 'switch_mode',
     'codegraph',
     'task',
+    'todolist', // 写 .mocode/plans/<id>.md(id 服务端生成,无路径注入);操作项目内元数据
 ]);
 /**
  * 路径类工具:enforceSandbox 集中把 args.path 重写为牢内绝对路径(默认安全;工具内

package/dist/tools/builtins/index.js

@@ -17,6 +17,7 @@ import { memoryListTool } from './memory-list.js';
 import { memoryUpdateTool } from './memory-update.js';
 import { memoryForgetTool } from './memory-forget.js';
 import { taskTool } from './task.js';
+import { todolistTool } from './todolist.js';
 /**
  * 所有内置工具,按注册顺序排列。
  * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。无需改 agent / llm。
@@ -41,4 +42,5 @@ export const builtinTools = [
     memoryUpdateTool,
     memoryForgetTool,
     taskTool, // 派生子 agent(独立 history + 可受限工具集);plan 模式禁用(见 PLAN_DISABLED_TOOLS)
+    todolistTool, // 工作记事本(plan 文件:复杂任务 checklist,落盘抗压缩);plan 模式可用(便于「先 plan 再 auto」时落地执行清单)
 ];

package/dist/tools/builtins/todolist.js

@@ -0,0 +1,231 @@
+// todolist 工具:LLM 的「工作记事本」——把隐式思考外化为持久 checklist,抗压缩、可视化。
+//
+// 落地:plan/store.ts(文件源)+ plan/active.ts(进程级活跃缓存)+ 本工具(写盘 + 通知 listener)。
+//
+// 契约对齐「调度器永不抛错、永远返回字符串」(tools/registry.ts executeTool)。
+// 单 plan/会话:create 前若有 in_progress 活跃 plan → 拒绝(避免误覆盖);finish/abandoned 后可再建。
+//
+// 工具返回:把当前 plan 紧凑渲染给 LLM(不只返操作结果——让 LLM 单次调用后看到完整状态,无需再 read)。
+import { newPlanId, readPlan, writePlan, updatePlan, listPlans, renderPlanForLLM, } from '../../plan/store.js';
+import { getActivePlan, setActivePlan, hasActivePlan, clearActivePlan } from '../../plan/active.js';
+import { MAX_OUTPUT } from '../constants.js';
+const VALID_STATUS = new Set([
+    'pending', 'in_progress', 'done', 'skipped', 'failed',
+]);
+const VALID_PLAN_STATUS = new Set([
+    'in_progress', 'finished', 'abandoned',
+]);
+// ── 工具定义 ──
+export const todolistTool = {
+    name: 'todolist',
+    description: [
+        'Maintain a working "notepad" plan in .mocode/plans/<id>.md (file-based, survives context compression).',
+        'For complex multi-step tasks (≥3 file changes or ≥5 tool calls expected, OR user says "先计划再执行" / "plan then do"), CALL THIS FIRST to write the plan, then update each step as you go.',
+        'For simple single-step tasks, skip it and just execute.',
+        'Single plan per session: create refuses if an in-progress plan already exists — finish or abandon it first.',
+    ].join(''),
+    parameters: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['create', 'read', 'update', 'add_step', 'finish'],
+                description: 'create=新计划;read=读当前活跃;update=改步骤状态;add_step=追加步骤;finish=收尾',
+            },
+            title: { type: 'string', description: 'create 必填:计划标题' },
+            goal: { type: 'string', description: 'create 可选:目标描述(写进「目标」段)' },
+            steps: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'create 必填:步骤标题数组(从 1 起自动编号)',
+            },
+            step_id: {
+                type: 'number',
+                description: 'update 必填:步骤编号(1-based;create 后 read 返回的 id)',
+            },
+            status: {
+                type: 'string',
+                enum: ['pending', 'in_progress', 'done', 'skipped', 'failed'],
+                description: 'update 必填:目标状态',
+            },
+            note: {
+                type: 'string',
+                description: 'update / finish 可选:追加到进度日志的一行说明(可空)',
+            },
+            plan_status: {
+                type: 'string',
+                enum: ['finished', 'abandoned'],
+                description: 'finish 必填:finished=完成;abandoned=放弃(中途取消)',
+            },
+        },
+        required: ['action'],
+    },
+    async execute(args) {
+        const action = String(args.action ?? '');
+        try {
+            switch (action) {
+                case 'create': return doCreate(args);
+                case 'read': return doRead();
+                case 'update': return doUpdate(args);
+                case 'add_step': return doAddStep(args);
+                case 'finish': return doFinish(args);
+                default:
+                    return `错误:未知 action「${action}」,合法值:create / read / update / add_step / finish。`;
+            }
+        }
+        catch (e) {
+            // 兜底:工具内部不抛,但防御性 catch 一道(契约对齐「永不抛」)。
+            const why = e instanceof Error ? e.message : String(e);
+            return `错误:todolist 内部异常: ${why}`;
+        }
+    },
+};
+// ── actions ──
+function doCreate(args) {
+    const title = String(args.title ?? '').trim();
+    if (!title)
+        return '错误:create 必填 title。';
+    const goal = String(args.goal ?? '').trim();
+    const rawSteps = Array.isArray(args.steps) ? args.steps : null;
+    if (!rawSteps || rawSteps.length === 0)
+        return '错误:create 必填 steps(非空字符串数组)。';
+    const steps = rawSteps
+        .map((s) => String(s ?? '').trim())
+        .filter((s) => s.length > 0);
+    if (steps.length === 0)
+        return '错误:create 的 steps 全是空字符串。';
+    if (hasActivePlan()) {
+        const cur = getActivePlan();
+        return `错误:已存在进行中的 plan「${cur?.title ?? ''}」(id=${cur?.id ?? ''}),需先 finish 后再建。`;
+    }
+    // 旧 plan 残留(finished/abandoned)→ 允许新建,不删历史(用户可后续 read 历史 plan)
+    const now = new Date().toISOString();
+    const plan = {
+        id: newPlanId(),
+        title,
+        status: 'in_progress',
+        created: now,
+        updated: now,
+        goal,
+        steps: steps.map((t, i) => ({ id: i + 1, title: t, status: 'pending' })),
+        log: [{ at: now, text: `创建计划: ${steps.length} 步` }],
+    };
+    if (!writePlan(plan))
+        return '错误:写 plan 文件失败(检查 .mocode/plans 目录权限)。';
+    setActivePlan(plan);
+    return renderSuccess('create', plan);
+}
+function doRead() {
+    const cur = getActivePlan();
+    if (!cur) {
+        // 兜底:state 缓存空但文件可能存在(sandboxRoot 切了 / 进程重启)→ 列 plans 找一个最新的 in_progress
+        const fallback = findInProgressFromDisk();
+        if (fallback) {
+            setActivePlan(fallback);
+            return renderSuccess('read', fallback);
+        }
+        return '错误:无活跃 plan。先用 action=create 开一个。';
+    }
+    // 重新读盘以保最新(其他路径可能改了文件)
+    const fresh = readPlan(cur.id);
+    if (fresh)
+        setActivePlan(fresh);
+    return renderSuccess('read', fresh ?? cur);
+}
+function doUpdate(args) {
+    const cur = getActivePlan();
+    if (!cur)
+        return '错误:无活跃 plan 可 update。先 create。';
+    const stepId = Number(args.step_id);
+    if (!Number.isFinite(stepId) || stepId < 1) {
+        return `错误:update 必填 step_id(>=1 的整数),收到「${args.step_id}」。`;
+    }
+    const status = String(args.status ?? '');
+    if (!VALID_STATUS.has(status)) {
+        return `错误:update 的 status 非法「${status}」,合法:pending / in_progress / done / skipped / failed。`;
+    }
+    const note = String(args.note ?? '').trim();
+    const updated = updatePlan(cur.id, (p) => {
+        const step = p.steps.find((s) => s.id === stepId);
+        if (!step)
+            return false; // 无改动,工具返错
+        step.status = status;
+        const at = new Date().toISOString();
+        const logText = note || `step ${stepId} → ${status}`;
+        p.log.push({ at, text: logText });
+        return p;
+    });
+    if (!updated) {
+        return `错误:update 失败(找不到 step_id=${stepId},可能 plan 已不存在或 step 编号越界)。`;
+    }
+    // step 不存在(updatePlan 内 mutator 返 false → updatePlan 返原对象,需二次校验)
+    if (!updated.steps.some((s) => s.id === stepId)) {
+        return `错误:找不到 step_id=${stepId}(plan 共 ${updated.steps.length} 步)。`;
+    }
+    setActivePlan(updated);
+    return renderSuccess('update', updated);
+}
+function doAddStep(args) {
+    const cur = getActivePlan();
+    if (!cur)
+        return '错误:无活跃 plan 可 add_step。先 create。';
+    const text = String(args.title ?? args.note ?? '').trim();
+    if (!text)
+        return '错误:add_step 必填 title(单条步骤标题)。';
+    const updated = updatePlan(cur.id, (p) => {
+        const nextId = p.steps.length > 0 ? Math.max(...p.steps.map((s) => s.id)) + 1 : 1;
+        p.steps.push({ id: nextId, title: text, status: 'pending' });
+        p.log.push({ at: new Date().toISOString(), text: `add step: ${text}` });
+        return p;
+    });
+    if (!updated)
+        return '错误:add_step 写盘失败。';
+    setActivePlan(updated);
+    return renderSuccess('add_step', updated);
+}
+function doFinish(args) {
+    const cur = getActivePlan();
+    if (!cur)
+        return '错误:无活跃 plan 可 finish。';
+    const ps = String(args.plan_status ?? 'finished');
+    if (!VALID_PLAN_STATUS.has(ps)) {
+        return `错误:finish 的 plan_status 非法「${ps}」,合法:finished / abandoned。`;
+    }
+    const note = String(args.note ?? '').trim();
+    const updated = updatePlan(cur.id, (p) => {
+        p.status = ps;
+        p.log.push({
+            at: new Date().toISOString(),
+            text: note || (ps === 'finished' ? '完成' : '放弃'),
+        });
+        return p;
+    });
+    if (!updated)
+        return '错误:finish 写盘失败。';
+    setActivePlan(updated);
+    // finish 后清活跃缓存(下轮 read 自动从 in_progress 列表兜底,本会话不再「活跃」)
+    if (ps === 'abandoned')
+        clearActivePlan();
+    else {
+        // finished 也清:「活跃」专指 in_progress;finished 是历史归档
+        clearActivePlan();
+    }
+    return renderSuccess('finish', updated);
+}
+// ── helpers ──
+/** 从盘上找一个 in_progress plan(进程级 state 丢失/首次访问时兜底)。无 → null。 */
+function findInProgressFromDisk() {
+    const all = listPlans();
+    return all.find((p) => p.status === 'in_progress') ?? null;
+}
+/** 工具结果统一格式:`<action>: <一行摘要>\n\n<完整 plan 渲染>`。
+ *  超 MAX_OUTPUT 截 plan 渲染尾部(罕见;plan 文件本身就小)。 */
+function renderSuccess(action, p) {
+    const done = p.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+    const head = `${action} ✓: 「${p.title}」 进度 ${done}/${p.steps.length} (status=${p.status})`;
+    const body = renderPlanForLLM(p);
+    const full = `${head}\n\n${body}`;
+    if (full.length <= MAX_OUTPUT)
+        return full;
+    return full.slice(0, MAX_OUTPUT) + `\n\n…(plan 渲染已截断 ${full.length - MAX_OUTPUT} 字符)`;
+}

package/dist/ui/layout.js

@@ -742,15 +742,19 @@ function composeSpinnerLine(status, cols) {
     const rightStr = tail ? `${ui.yellow}${tail}${ui.reset}` : '';
     return twoColumn(lead, leadW, rightStr, tailW, cols);
 }
-/** 下线之下那行(model 行):左 = 模式标识(auto 跟随主题色 / plan 显亮黄);右 = context + cwd,右端对齐。 */
+/** 下线之下那行(model 行):左 = 模式标识;右 = context + cwd,右端对齐。
+ *  活跃 plan chip 不再放这里,改放 spinner 行上方的「虚拟空行」(contentBottom+1,见 drawStatusBar),
+ *  既不挤 model 行,又给输入区上方留出可视分隔带。 */
 function composeModelLine(status, cols) {
     const ctx = status.contextBar; // 已带色
     const ctxW = ansiDisplayWidth(ctx);
-    // 左段:模式标识(auto 显 brightCyan 随主题 / plan 显亮黄)
+    // 左段:仅模式标识
     const modeTag = status.modeTag ?? '';
-    const leftStr = modeTag
-        ? `${modeTag === 'plan' ? ui.yellow : ui.brightCyan}${modeTag}${ui.reset}`
+    const modeColor = modeTag === 'plan' ? ui.yellow : ui.brightCyan;
+    const modePart = modeTag
+        ? `${modeColor}${modeTag}${ui.reset}`
         : '';
+    const leftStr = modePart;
     const leftW = modeTag ? displayWidth(modeTag) : 0;
     // 右段:ctx + sep + cwd,右端对齐。cwd 按预算截断,极窄(<6)隐藏。
     const minGap = 2;
@@ -761,18 +765,36 @@ function composeModelLine(status, cols) {
     const rightW = ctxW + STATUS_SEP_W + cwdW;
     return twoColumn(leftStr, leftW, rightStr, rightW, cols);
 }
-/** 画状态行(spinner 行 + model 行,两行)。RUNNING 态 spinner 频繁调。
- *  行号(footerH=6):spinner 行=contentBottom+2,model 行=rows(屏底)。
- *  上线 contentBottom+3 / 输入 contentBottom+4 / 下线 contentBottom+5 由 paintInput 画,此函数只刷两行信息。 */
+/** spinner 行上方的「虚拟空行」(contentBottom+1)。
+ *  - 有活跃 plan:显「plan: <summary> ▸ N. step」整行左对齐(yellow + dim)
+ *  - 无活跃 plan:空(保留原分隔视觉,避免内容贴输入区)
+ *  这行在 DECSTBM 滚动区外([1, contentBottom]),稳定不滚。 */
+function composePlanLine(status, cols) {
+    const plan = (status.planSummary ?? '').trim();
+    if (!plan)
+        return ''; // 无 plan:画空,等 paint 路径 clearLine
+    // 整行左对齐,不留右段(plan 自带进度信息,不需要 cwd)
+    return `${ui.dim}│ ${ui.yellow}${plan}${ui.reset}${ui.dim}`;
+}
+/** 画状态行(plan 行 + spinner 行 + model 行,三行)。RUNNING 态 spinner 频繁调。
+ *  行号(footerH=6):
+ *    plan 行     = contentBottom+1  (活跃 plan 时显 chip;无则空)
+ *    spinner 行  = contentBottom+2  (◆ 空闲 / ⠹ 思考中… / etc)
+ *    上线        = contentBottom+3  (画在 paintInput)
+ *    输入行      = contentBottom+4
+ *    下线        = contentBottom+5
+ *    model 行    = rows              (屏底:auto + ctx + cwd) */
 export function drawStatusBar(status) {
     if (!active || !base)
         return;
     const s = status ?? { ...base, status: statusText, spinnerFrame };
     const g = getGeo();
-    const spinnerRow = g.contentBottom + 2; // +1 虚拟空行,+2 spinner 行
+    const planRow = g.contentBottom + 1;
+    const spinnerRow = g.contentBottom + 2;
     const modelRow = g.rows; // 屏底:model 行
-    // 一次写入:cup spinner 行 + clearLine + spinner 行内容 + cup model 行 + clearLine + model 行内容 + cup 回。
-    let out = cup(spinnerRow, 1) + esc.clearLine + composeSpinnerLine(s, g.cols) +
+    // 一次写入:三行 cup+clear+内容,末尾 cup 回续写位/输入框光标
+    let out = cup(planRow, 1) + esc.clearLine + composePlanLine(s, g.cols) +
+        cup(spinnerRow, 1) + esc.clearLine + composeSpinnerLine(s, g.cols) +
         cup(modelRow, 1) + esc.clearLine + composeModelLine(s, g.cols);
     if (mode === 'running') {
         // 运行态(回尾 / 滚动回看均):cup 回输入框光标位(供 IME 锚定)。
@@ -907,7 +929,7 @@ export function clearLiveAtCursor() {
     frameRow = 0;
     frameCol = 0;
 }
-/** 更新状态行基线(模型 / context / cwd / 模式标识)。repl 在轮次边界与切模式时调。 */
+/** 更新状态行基线(模型 / context / cwd / 模式标识 / 活跃 plan chip)。repl 在轮次边界与切模式时调。 */
 export function setStatusBase(b) {
     base = b;
 }
@@ -1037,10 +1059,17 @@ export function paintInput(view) {
         const line = slice[g.contentBottom - 1] ?? '';
         buf += cup(g.contentBottom, 1) + esc.clearLine + line;
     }
-    // 2c. 虚拟空行(内容区与状态栏之间的视觉间隔,属底栏非内容):恒清空,防底栏撑高时旧内容残留该行。
-    buf += cup(g.contentBottom + 1, 1) + esc.clearLine;
+    // 2c. 虚拟空行(内容区与状态栏之间的视觉间隔,属底栏非内容):
+    //     - 无活跃 plan:清空保留作分隔(原设计)
+    //     - 有活跃 plan:渲染 plan chip(整帧重画时也要更新,避免 listener 漏触发后残留)
+    {
+        const plan = (base.planSummary ?? '').trim();
+        buf += cup(g.contentBottom + 1, 1) + esc.clearLine;
+        if (plan)
+            buf += `${ui.yellow}${plan}${ui.reset}`;
+    }
     // 3. 状态行:spinner 行 + model 行(两行式底栏)
-    const spinnerRow = g.contentBottom + 2; // +1 虚拟空行,+2 spinner 行
+    const spinnerRow = g.contentBottom + 2; // +1 虚拟空行(plan 行),+2 spinner 行
     const modelRow = g.rows; // 屏底:model 行
     const status = { ...base, status: statusText, spinnerFrame };
     buf += cup(spinnerRow, 1) + esc.clearLine + composeSpinnerLine(status, g.cols);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {