mocode-ai 0.2.9 → 0.3.0

package/README.md

@@ -18,16 +18,18 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 - **Plan / Auto dual mode** — In `plan` mode the agent is read-only (reads code, queries indexes, searches — never writes to disk, runs commands, or spawns sub-agents) and produces a plan; `auto` mode unlocks the full toolset. The agent can switch between the two on its own — scope out an unfamiliar codebase first, then start making changes.
 - **Automatic context compression** — As the context window fills up, a three-tier compression kicks in (trim individual results → compact older tool results in place → summarize older turns), so long sessions never overflow. `/context` shows live token usage; `/compact` triggers manual compression (optionally with a focus hint to preserve what matters).
 - **Cross-session long-term memory** — The agent can save project architecture, conventions, and lessons learned as long-term memory, auto-loaded in future sessions. A background process periodically reflects on conversations to mine things worth remembering. Memories can be created, searched, updated, and forgotten, with recall-based decay.
+- **Working notepad (todolist)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent first writes a plan to `.mocode/plans/<id>.md` (file-based, survives context compression), then ticks each step as it goes. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`. `finish` auto-archives completed plans to `plans/archive/`, with explicit `list / delete / unarchive` actions.
 - **Interruptible and reversible** — Ctrl+C interrupts the current turn at any time (kills child processes recursively, rolls history back to before the turn started, leaves no half-finished tool calls). `/rollback` restores file changes from per-turn snapshots, with a per-file keep/undo choice — no git dependency required.
 - **Sandbox protection** — File reads/writes go through a sandbox that blocks out-of-bounds paths (`../../`, absolute paths outside the root, symlink escapes, etc.), so the agent never touches files outside your working directory.
 
 ## Features
 
-- **Streaming output + visible reasoning** — Responses render as they're generated; when the model supports reasoning, the thinking process is visible in real time and auto-collapses to save screen space, with `/think N` to expand it on demand.
+- **Streaming output + visible reasoning** — Responses render as they're generated; when the model supports reasoning, the thinking process is visible in real time and auto-collapses to save screen space.
 - **Full-screen TUI** — Alt-screen mode with a fixed status bar, scrollback (PgUp/PgDn), typeahead while the agent is running, and auto-prefill for the next turn.
 - **Session persistence** — Every turn is saved automatically; `--resume` / `/resume` picks up a past session.
 - **Skills system** — Scans directories like `~/.mocode/skills/` automatically; each skill's description is injected into the system prompt, and the model calls `use_skill` to load the full instructions only when relevant (progressive disclosure: skim the summary first, load the body only if needed).
-- **Slash commands** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/think` `/rollback`, with dropdown filtering as you type.
+- **Optional desktop pet** — A small floating window (`/pet`) shows a stateful character that mirrors agent activity (idle / thinking / tool running / waiting for human). Works as a separate process over WebSocket; quit it with `/pet quit`. Sits beside the terminal, never blocks it.
+- **Slash commands** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`, with dropdown filtering as you type.
 
 ## Installation
 
@@ -141,6 +143,7 @@ The agent operates in **the working directory it was launched from** — to have
 | `switch_mode`      | Switch between `plan` (read-only planning) and `auto` (full execution); the agent can call this itself to explore before acting |
 | `drop_context`     | Replace irrelevant old tool results in history with stubs to free up context (preserves tool_call_id pairing, leaves system prompt and current turn untouched, idempotent) |
 | `task`             | Spawn a sub-agent for an independent subtask (isolated history, optional restricted toolset, optional step cap); consecutive calls run in parallel automatically, returning only a summary |
+| `todolist`         | Working notepad: write a multi-step plan to `.mocode/plans/<id>.md` (survives compression) and tick steps as you go; `finish` auto-archives, with `list / delete / unarchive` for history |
 | `memory_save`      | Save a piece of cross-session long-term memory (title indexed, body fetched on demand) |
 | `memory_search`    | Search memory bodies by keyword; hits boost the recall count (affects forgetting decay) |
 | `memory_list`       | List the memory index (id/title/summary, no body)                        |
@@ -157,13 +160,17 @@ The agent operates in **the working directory it was launched from** — to have
 | `/skills`           | List discovered skills                                               |
 | `/compact`          | Compress history (optionally with a focus hint: `/compact …`)        |
 | `/resume`           | Resume a saved session                                                |
-| `/think`            | Expand a collapsed reasoning section (`/think N`)                    |
 | `/rollback`         | Menu to pick a turn to roll back to (↑↓ · Enter)                     |
+| `/memory`           | Show memory library: entry count + recent index                       |
+| `/reflect`          | Manually trigger a background memory reflection pass                  |
 | `/model`            | Configure the LLM (baseURL / apiKey / model / context window), applied immediately + persisted |
 | `/init`             | Scan the project and generate `MOCODE.md` project memory (dispatched to the agent) |
 | `/theme`            | Switch color theme (↑↓ · Enter, or `/theme <name>` directly)         |
 | `/plan`             | Switch to plan mode (read-only exploration + plan output, approve to switch to auto) |
 | `/auto`             | Switch back to auto mode (full toolset execution)                     |
+| `/pet`              | Toggle the optional desktop pet (floating window mirroring agent state) |
+| `/pet skin`         | Pick a pet skin (↑↓ · Enter)                                          |
+| `/pet quit`         | Fully shut down the pet process (not just disconnect)                 |
 
 Type `/` to trigger the dropdown menu, keep typing to filter; Esc to cancel.
 
@@ -199,4 +206,4 @@ npm run typecheck   # tsc --noEmit
 
 ## Future extensions
 
-Sub-agents / parallel tasks, MCP tool integration, a permission confirmation UI. The current version is a streaming, reasoning-visible, rollback-capable terminal coding agent.
+MCP tool integration, a permission confirmation UI, and a real worktree-isolated sub-agent mode. The current version is a streaming, reasoning-visible, rollback-capable terminal coding agent with 20 tools, working-notepad planning, cross-session memory, parallel sub-agents, and an optional desktop pet.

package/README.zh-CN.md

@@ -18,16 +18,18 @@ mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 - **计划 / 执行双模式** — `plan` 模式下只读探查(读代码、查索引、搜索,绝不写盘、不跑命令、不派生子 agent),产出计划;`auto` 模式全量工具放开。agent 还能在两者间自切换——先把陌生代码库摸清,再动手改。
 - **上下文自动压缩** — 接近窗口上限时三层压缩(单条结果裁剪 → 旧工具结果原地微压缩 → 旧对话摘要),长会话也不爆窗口;`/context` 实时显示 token 用量,`/compact` 可手动压缩(能带焦点指令聚焦保留)。
 - **跨会话长期记忆** — agent 能把项目架构、约定、踩过的坑存成长期记忆,下次会话自动加载;后台还会定期从对话里反思挖掘值得记住的事。记忆可增删改、带召回衰减。
+- **工作记事本(todolist)** — 复杂多步任务(≥3 处文件改动 / ≥5 步工具调用)时,agent 先把计划写到 `.mocode/plans/<id>.md`(落盘抗压缩),执行过程逐步勾选;TUI 状态栏实时显示进度 chip:`plan: [标题] (3/7) ▸ [当前步]`。`finish` 自动归档到 `plans/archive/`,`list / delete / unarchive` 管理历史。
 - **可中断、可回滚** — Ctrl+C 随时打断当前轮次(树杀子进程,历史还原到本轮开始前,不留残半的工具调用);`/rollback` 按轮次快照恢复文件改动,逐个文件「保留/撤销」,不依赖 git。
 - **沙箱防护** — 文件读写经沙箱拦截,挡掉越界路径(`../../`、绝对外圈、软链出圈等),不碰工作目录之外的文件。
 
 ## 特性
 
-- **流式输出 + 思考可见** — 回复边生成边显示;模型支持 reasoning 时思考过程实时可见,思考段自动折叠(不占屏),`/think N` 按需展开
+- **流式输出 + 思考可见** — 回复边生成边显示;模型支持 reasoning 时思考过程实时可见,思考段自动折叠(不占屏)
 - **全屏 TUI** — 备用屏(alt screen)+ 固定底栏状态行 + 滚动回看(PgUp/PgDn),运行中可打字(typeahead),下一轮自动预填
 - **会话持久化** — 每轮自动落盘,`--resume` / `/resume` 续接历史会话
 - **Skills 系统** — 自动扫描 `~/.mocode/skills/` 等目录,description 注入系统提示,模型按需调 `use_skill` 加载完整指令(渐进式披露:先看简介,任务相关才加载正文)
-- **斜杠命令** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/think` `/rollback`,输入时下拉过滤
+- **可选桌宠** — 独立悬浮窗(`/pet`)显示一个小角色,镜像 agent 活动(空闲 / 思考 / 跑工具 / 等人工),独立进程走 WebSocket,`/pet quit` 完全关闭。挂在终端外,绝不挡终端。
+- **斜杠命令** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`,输入时下拉过滤
 
 ## 安装
 
@@ -141,6 +143,7 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `switch_mode`   | 在 `plan`(只读规划)与 `auto`(全量执行)间切换;agent 可自行调用,先探查再动手       |
 | `drop_context`  | 把历史里无关的旧工具结果替换为存根释放上下文(保 tool_call_id 配对,不动 system 与当前轮;幂等) |
 | `task`          | 派生子 agent 执行独立子任务(独立历史、可受限工具集、可设步数上限);连续多个自动并行,只回摘要      |
+| `todolist`      | 工作记事本:把多步计划写到 `.mocode/plans/<id>.md`(抗压缩),边执行边勾选;`finish` 自动归档,`list / delete / unarchive` 管历史 |
 | `memory_save`   | 存一条跨会话长期记忆(标题进索引,正文按需取)                                  |
 | `memory_search` | 按关键词搜记忆正文,命中即提升召回计数(影响遗忘衰减)                              |
 | `memory_list`   | 列记忆索引(id/标题/摘要,无正文)                                      |
@@ -157,13 +160,17 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `/skills`       | 列出已发现的 skill                                       |
 | `/compact`      | 压缩历史(可带焦点 `/compact …`)                            |
 | `/resume`       | 续接已保存的会话                                           |
-| `/think`        | 展开折叠思考段(`/think N`)                                |
 | `/rollback`     | 菜单选轮次回滚(↑↓ · Enter)                                |
+| `/memory`       | 看记忆库:条目数 + 近期索引                                    |
+| `/reflect`      | 手动触发一次后台记忆反思 pass                                   |
 | `/model`        | 配置大模型(baseURL / apiKey / model / 上下文窗口),即时生效 + 持久化 |
 | `/init`         | 扫描项目生成 `MOCODE.md` 项目记忆(发给 agent 执行)               |
 | `/theme`        | 切换颜色主题(↑↓ · Enter,或 `/theme <name>` 直切)            |
 | `/plan`         | 切到 plan 模式(只读探查 + 产出计划,审批后切 auto 执行)              |
 | `/auto`         | 切回 auto 模式(全量工具执行)                                  |
+| `/pet`          | 开关桌宠(独立悬浮窗,镜像 agent 状态动画)                          |
+| `/pet skin`     | 选桌宠皮肤(↑↓ · Enter)                                  |
+| `/pet quit`     | 完全关闭桌宠进程(而非仅断开本连接)                                 |
 
 输入 `/` 触发下拉菜单,继续打字过滤;Esc 取消。
 
@@ -199,4 +206,4 @@ npm run typecheck   # tsc --noEmit
 
 ## 可后续扩展
 
-子 agent / 并行任务、MCP 工具集成、权限确认 UI。当前版本是一个流式、思考可见、可回滚的终端编码 agent。
+MCP 工具集成、权限确认 UI、真·worktree 隔离的子 agent 模式。当前版本已是流式、思考可见、可回滚的终端编码 agent:20 个工具、工作记事本规划、跨会话记忆、并行子 agent、可选桌宠。

package/dist/agent/index.js

@@ -11,6 +11,13 @@ import { beginTurn } from '../rollback/index.js';
 import { config } from '../config/index.js';
 import { runAgentCore, isMutationTool, } from './core.js';
 import { createPetHooks } from '../pet/state.js';
+/** 取 userInput 的首行:字符串直接 split;多模态 parts 找首个 text part 再 split。 */
+function firstLineOf(ui) {
+    if (typeof ui === 'string')
+        return ui.split('\n')[0] ?? '';
+    const first = ui.find((p) => p.type === 'text');
+    return first?.text.split('\n')[0] ?? '';
+}
 /** 工具调用 ● 头:工具名 + 参数摘要(按 tool_calls 原顺序打印,让用户看到本轮跑哪些工具)。 */
 function writeToolHeader(tc) {
     const summary = summarizeToolCall(tc.name, tc.arguments);
@@ -54,7 +61,7 @@ export async function runAgent(history, userInput, signal,
 /** 每步 chat() 返回后回调:repl 据此重算并重画状态行 context 用量条(运行中实时刷新,不冻结在轮首)。 */
 onContextUpdate) {
     // 开新轮次(回滚用):首行截断 40,供 /rollback 轮次菜单展示。
-    beginTurn(truncateDisplay(userInput.split('\n')[0] ?? '', 40));
+    beginTurn(truncateDisplay(firstLineOf(userInput), 40));
     layout.contentMode(); // 防御性:运行态光标归输入框光标位供 IME 锚定(enterRunningMode 已置,这里兜底)
     // spinner:状态行最前面转圈(思考中 / 生成 / 执行 工具时,状态栏 lead 位显帧 + 文字)。
     // 经 setStatus 注入状态行(spinnerFrame + statusText),composeStatus 把帧 + 文字放 lead 位;

package/dist/attachments/image.js

@@ -0,0 +1,78 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { jailResolve } from '../sandbox/jail.js';
+export const MAX_INLINE_BYTES_DEFAULT = 4 * 1024 * 1024;
+const MIME_BY_EXT = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+};
+export function detectMime(p) {
+    return MIME_BY_EXT[extname(p).toLowerCase()] ?? null;
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+export function renderChip(att) {
+    return `📷 ${att.name} (${formatBytes(att.bytes)})`;
+}
+export async function loadImageAttachment(input, opts) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return { ok: false, reason: '路径为空' };
+    const mime = detectMime(trimmed);
+    if (!mime) {
+        return { ok: false, reason: `unsupported: ${extname(trimmed) || '(无扩展名)'} — 仅支持 png/jpg/jpeg/gif/webp` };
+    }
+    let abs;
+    try {
+        abs = jailResolve(trimmed);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { ok: false, reason: `outside sandbox: ${msg}` };
+    }
+    let st;
+    try {
+        st = await stat(abs);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { ok: false, reason: `无法访问文件: ${msg}` };
+    }
+    if (!st.isFile())
+        return { ok: false, reason: '不是普通文件' };
+    if (st.size > opts.maxBytes) {
+        return {
+            ok: false,
+            reason: `too large: ${formatBytes(st.size)} (max ${formatBytes(opts.maxBytes)}) — TODO: URL upload not yet supported`,
+        };
+    }
+    const buf = await readFile(abs);
+    const dataUrl = `data:${mime};base64,${buf.toString('base64')}`;
+    const id = createHash('sha1')
+        .update(abs)
+        .update('\0')
+        .update(String(st.size))
+        .update('\0')
+        .update(String(st.mtimeMs))
+        .digest('hex');
+    return {
+        ok: true,
+        att: {
+            id,
+            path: abs,
+            name: basename(abs),
+            bytes: st.size,
+            mime,
+            dataUrl,
+        },
+    };
+}

package/dist/config/index.js

@@ -91,13 +91,15 @@ ${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.
-
-## 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).
+- **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.
+- **Batch independent tool calls in one turn**: the executor runs ALL returned tool calls before the next LLM call, so emitting [read_file, glob, read_file] together is dramatically cheaper than three separate turns. Default to bundling exploration reads and parallel writes.
+- **Chain shell workflows in a single \`run_command\`**: use \`&&\`, \`;\`, \`|\`, \`>\`, heredocs to fold multi-step scripts (\`mkdir -p x && cat > x/file.ts <<'EOF' ... EOF && npm test\`) into one call. Only emit a follow-up turn when the result forces a decision (error, ambiguous output, branching logic).
+
+## 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
@@ -122,7 +124,8 @@ ${PLATFORM_NOTE}
 ## 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.
+- Single plan per session: \`todolist create\` refuses if an in-progress plan already exists — finish or abandon it first.
+- **Lifecycle** (5 actions total): \`create\` / \`read\` / \`update\` / \`add_step\` / \`finish\` for normal flow. \`finish plan_status=finished\` AUTO-ARCHIVES the plan to \`.mocode/plans/archive/<id>.md\` (history preserved, active dir stays clean). To revisit old plans: \`list scope=archived\` (or \`all\`) + \`unarchive id=<id>\` to bring back. \`delete id=<id>\` permanently removes (any location); cannot delete the currently active plan.
 - 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
@@ -160,6 +163,9 @@ export const config = {
     searchApiKey: process.env.ANYSEARCH_API_KEY,
     sandboxRoot: process.env.SANDBOX_ROOT || undefined,
     searchBaseUrl: process.env.ANYSEARCH_BASE_URL || 'https://api.anysearch.com',
+    maxImageBytes: process.env.MOCODE_MAX_IMAGE_BYTES
+        ? Number(process.env.MOCODE_MAX_IMAGE_BYTES)
+        : undefined,
     theme: process.env.MOCODE_THEME || 'default',
     themeFromShell,
     llmKeysFromShell,

package/dist/llm/capabilities.js

@@ -0,0 +1,82 @@
+/**
+ * 模型能力检测:仅用于 /image 等多模态输入的友好提示。
+ *
+ * 策略 — 保守 + 显式白名单/黑名单:
+ * - 命中 KNOWN_TEXT_ONLY_PREFIXES 任一前缀 → false(确定无视觉)
+ * - 命中 KNOWN_VISION_FAMILIES 任一前缀 → true(确定有视觉)
+ * - 其它(未识别 / 自定义代理 / 新发布模型)→ 默认 true(放行,让 API 拒收兜底)
+ *
+ * 理由:视觉能力在 2024 后已成新模型默认;自定义 OpenAI 代理常把上游视觉模型重命名;
+ * 过度保守会误伤合法配置。
+ */
+const KNOWN_TEXT_ONLY_PREFIXES = [
+    'gpt-3.5',
+    'gpt-3.5-turbo',
+    'gpt-4-0613', // 早期 gpt-4,无视觉
+    'gpt-4-0314',
+    'gpt-4-32k',
+    'o1-mini', // 纯推理,无视觉
+    'o1-preview',
+    'o3-mini',
+    'text-embedding-',
+    'text-davinci-',
+    'dall-e-', // 反过来:它是图像生成不是视觉理解
+    'whisper-',
+    'tts-',
+    'babbage-',
+    'davinci-',
+    'gpt-4o-mini-search', // 搜索专用,无视觉入口
+];
+const KNOWN_VISION_FAMILIES = [
+    'gpt-4o',
+    'gpt-4-turbo',
+    'gpt-4-vision',
+    'gpt-4.1',
+    'gpt-4.5',
+    'gpt-5',
+    'chatgpt-4o',
+    'o1', // o1 / o1-pro 支持视觉(与 o1-mini 不同)
+    'claude-3',
+    'claude-3.5',
+    'claude-3.7',
+    'claude-4',
+    'claude-sonnet-4',
+    'claude-opus-4',
+    'gemini-1.5',
+    'gemini-2',
+    'gemini-exp',
+    'pixtral',
+    'qwen-vl',
+    'qwen2-vl',
+    'qwen2.5-vl',
+    'llava',
+    'internvl',
+    'minicpm-v',
+    'glm-4v',
+    'yi-vl',
+];
+/** 归一化:小写、去空白;用于前缀比较。 */
+function normalize(model) {
+    return model.trim().toLowerCase();
+}
+/**
+ * 判断模型是否支持视觉(多模态 image_url)。
+ * - 模型未配置(`config.model` 为空或 default 兜底字符串)→ true(不阻断,等 API 报错)
+ * - 命中 KNOWN_TEXT_ONLY_PREFIXES 任一前缀 → false(确定无视觉,优先查,避免 gpt-4o-mini vs -search 系列名冲突)
+ * - 命中 KNOWN_VISION_FAMILIES 任一前缀 → true
+ * - 其它(未识别 / 自定义代理 / 新发布模型)→ true(保守放行)
+ */
+export function modelSupportsVision(model) {
+    const m = normalize(model);
+    if (!m)
+        return true;
+    for (const p of KNOWN_TEXT_ONLY_PREFIXES) {
+        if (m === p || m.startsWith(p))
+            return false;
+    }
+    for (const p of KNOWN_VISION_FAMILIES) {
+        if (m === p || m.startsWith(p))
+            return true;
+    }
+    return true;
+}

package/dist/llm/index.js

@@ -2,9 +2,25 @@ import OpenAI from 'openai';
 import { config } from '../config/index.js';
 import { tools } from '../tools/registry.js';
 import { PLAN_DISABLED_TOOLS } from '../tools/constants.js';
+/**
+ * LLM 调用重试策略:
+ *   可重试  →  429 (rate limit) / 5xx (server) / APIConnectionError / Node 网络错 (ETIMEDOUT 等)
+ *   不重试  →  400 (bad request) / 401 (auth) / 其他 4xx / 用户中断 (AbortError / APIUserAbortError)
+ *
+ * 退避:指数 + ±20% jitter,首等 1s,翻倍,封顶 30s;若后端返回 Retry-After 头则优先按其值。
+ * 默认 4 次尝试(1 初始 + 3 重试),要调改 RETRY_MAX_ATTEMPTS。
+ *
+ * SDK 内置 maxRetries 默认 2(对所有 5xx+网络错重试),与本策略叠加会双重重试 5xx —— 显式置 0 让
+ * 全部重试由 chat() 外层重试循环统一控,行为可预期。
+ */
+const RETRY_MAX_ATTEMPTS = 4;
+const RETRY_BASE_MS = 1000;
+const RETRY_MAX_MS = 30000;
+const RETRY_JITTER = 0.2;
 let client = new OpenAI({
     baseURL: config.baseURL,
     apiKey: config.apiKey,
+    maxRetries: 0,
 });
 /**
  * 运行时重建 OpenAI 客户端(/model 切换 baseURL/apiKey 后调)。
@@ -16,8 +32,110 @@ export function reconfigureClient() {
     client = new OpenAI({
         baseURL: config.baseURL,
         apiKey: config.apiKey,
+        maxRetries: 0,
+    });
+}
+// ── 重试 helper(纯函数 + sleep,被 chat() 调用;亦可单测导入验证)──────
+/** 可被 AbortSignal 取消的 sleep;signal 已 abort 时立即抛 AbortError。 */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new DOMException('This operation was aborted', 'AbortError'));
+            return;
+        }
+        let onAbort;
+        const t = setTimeout(() => {
+            if (onAbort)
+                signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        onAbort = () => {
+            clearTimeout(t);
+            reject(new DOMException('This operation was aborted', 'AbortError'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
     });
 }
+/**
+ * 判定一个 chat 失败是否值得重试。
+ * 用户中断(signal.aborted / AbortError / APIUserAbortError)始终返回 false,避免退避中把中断吞了。
+ * 4xx(除 429)全不重试 —— 这是客户端请求错,重试只会再错一次。
+ */
+export function isRetryableError(err, signal) {
+    if (signal?.aborted)
+        return false;
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.name === 'AbortError' || e.name === 'APIUserAbortError')
+        return false;
+    // OpenAI SDK APIError 走 status 分支(覆盖 4xx/5xx/429)
+    const status = e.status;
+    if (typeof status === 'number') {
+        if (status === 429)
+            return true;
+        if (status >= 500 && status < 600)
+            return true;
+        return false;
+    }
+    // Node 网络错 code(APIConnectionError 内部也会带一个)
+    const code = e.code;
+    if (code === 'ETIMEDOUT' ||
+        code === 'ECONNRESET' ||
+        code === 'ENOTFOUND' ||
+        code === 'EAI_AGAIN' ||
+        code === 'ECONNREFUSED' ||
+        code === 'EPIPE') {
+        return true;
+    }
+    // OpenAI SDK 的网络错类(无 status)
+    if (e.name === 'APIConnectionError' || e.name === 'APIConnectionTimeoutError')
+        return true;
+    // 兜底:错误信息里出现 timeout 字样(部分代理把错误折叠成普通 Error)
+    if (typeof e.message === 'string' && /\btime(d|ed)?\s*out\b|ETIMEDOUT/i.test(e.message)) {
+        return true;
+    }
+    return false;
+}
+/** 从 OpenAI APIError.headers 解析 Retry-After(秒);不支持或缺失返回 undefined。封顶 RETRY_MAX_MS。 */
+export function getRetryAfterMs(err) {
+    const headers = err?.headers;
+    if (!headers)
+        return undefined;
+    let raw = null;
+    if (typeof headers.get === 'function') {
+        raw = headers.get('retry-after');
+    }
+    else if (typeof headers === 'object') {
+        raw = headers['retry-after'] ?? null;
+    }
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return Math.min(n * 1000, RETRY_MAX_MS);
+}
+/** 第 N 次失败后等多久(retryAfterMs 有就用它,否则指数;再加 ±RETRY_JITTER 抖动)。 */
+export function computeBackoff(attempt, retryAfterMs) {
+    const exp = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** (attempt - 1));
+    const base = retryAfterMs ?? exp;
+    const lo = base * (1 - RETRY_JITTER);
+    const hi = base * (1 + RETRY_JITTER);
+    return Math.max(0, Math.round(lo + Math.random() * (hi - lo)));
+}
+function logRetry(attempt, err, waitMs) {
+    const e = err;
+    const tag = e.status ? `HTTP ${e.status}` : e.name || 'Error';
+    const msg = e.message ?? '未知错误';
+    // stderr 而非 stdout —— 不污染流式正文;行首换行防止黏在上一行尾巴。
+    process.stderr.write(`\n[llm] 第 ${attempt}/${RETRY_MAX_ATTEMPTS} 次失败(${tag}: ${msg}),${(waitMs / 1000).toFixed(1)}s 后重试…\n`);
+}
+let createImplOverride = null;
+/** 仅供单测用:覆盖 chat() 内部实际调用的 create 桩。生产代码不要碰。 */
+export function __setChatCreateImpl(impl) {
+    createImplOverride = impl;
+}
 /** 把内部工具定义转成 OpenAI 的 tool 格式 */
 export const chatTools = tools.map((t) => ({
     type: 'function',
@@ -37,12 +155,43 @@ export const planChatTools = chatTools.filter((t) => !PLAN_DISABLED_TOOLS.has(t.
  * 流式调一次 LLM:增量回调文本,内部累加 tool_calls 片段。
  * tool_calls 跨 chunk 按 index 累加(id / name / arguments 拼接)。
  * include_usage 时末尾 chunk 携带 usage,先读再 continue(末尾 chunk 无 delta)。
+ *
+ * 包了一层重试:429/5xx/timeout/网络错按指数退避重试(默认 4 次),400/401/用户中断立即抛。
+ * 重试由 chat() 统一管,chatOnce() 只负责单次请求,职责单一便于单测。
  */
 export async function chat(messages, handlers = {}, signal, 
 /** 覆盖默认工具 schema;plan 模式传 planChatTools(只读子集),缺省=全量 chatTools。 */
 toolsOverride) {
+    let lastErr;
+    for (let attempt = 1; attempt <= RETRY_MAX_ATTEMPTS; attempt++) {
+        if (signal?.aborted) {
+            throw new DOMException('This operation was aborted', 'AbortError');
+        }
+        try {
+            return await chatOnce(messages, handlers, signal, toolsOverride);
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= RETRY_MAX_ATTEMPTS || !isRetryableError(err, signal)) {
+                throw err;
+            }
+            const wait = computeBackoff(attempt, getRetryAfterMs(err));
+            logRetry(attempt, err, wait);
+            // sleep 自己会在 signal abort 时抛 AbortError——透传,让 runAgentCore 的 catch 按中断处理。
+            await sleep(wait, signal);
+        }
+    }
+    // 循环要么 return 要么 throw,理论上走不到这里;写出来让 TS 控制流分析满意。
+    throw lastErr;
+}
+/** 单次流式 LLM 请求(无重试);chat() 的内部实现,可被 __setChatCreateImpl 注入桩以做单测。 */
+async function chatOnce(messages, handlers, signal, toolsOverride) {
     // signal 透传给 SDK 第二参(RequestOptions);abort 后 for await 抛错,chat 不 catch,透传 runAgent 处理。
-    const stream = await client.chat.completions.create({
+    // createImplOverride 的 body 类型故意宽成 Record(测试桩用),生产走 client 分支时由 OpenAI 自己的类型守门。
+    const create = createImplOverride
+        ? createImplOverride
+        : (body, opts) => client.chat.completions.create(body, opts);
+    const stream = await create({
         model: config.model,
         messages,
         tools: toolsOverride ?? chatTools,
@@ -63,7 +212,7 @@ toolsOverride) {
                 totalTokens: chunk.usage.total_tokens,
             };
         }
-        const delta = chunk.choices[0]?.delta;
+        const delta = chunk.choices?.[0]?.delta;
         if (!delta)
             continue; // 末尾 usage-only chunk 等无 delta
         if (delta.content) {
@@ -146,6 +295,33 @@ function contentToText(content) {
         return String(content);
     }
 }
+/** OpenAI 视觉模型单图固定 token(低细节 / auto 模式);高细节更大但属罕见路径,保守按 85 计。 */
+const IMAGE_TOKEN_COST = 85;
+/** 单个 content part 的 token:text part 走 estimateTokens,image_url part 固定 85。+2 结构开销。 */
+function partTokens(part) {
+    if (!part || typeof part !== 'object')
+        return 0;
+    const p = part;
+    if (p.type === 'text')
+        return 2 + estimateTokens(p.text ?? '');
+    if (p.type === 'image_url')
+        return 2 + IMAGE_TOKEN_COST;
+    return 2;
+}
+/** 估算多模态 content 的 token(text parts + 固定每图 85);不把 base64 走 estimateTokens,避免 1MB 图算成 25 万 token。 */
+export function contentTokens(content) {
+    if (content == null)
+        return 0;
+    if (typeof content === 'string')
+        return estimateTokens(content);
+    if (Array.isArray(content)) {
+        let sum = 0;
+        for (const p of content)
+            sum += partTokens(p);
+        return sum;
+    }
+    return estimateTokens(contentToText(content));
+}
 /** 估算单条消息的 token 数:结构开销 + content + tool_calls 参数。 */
 export function messageTokens(m) {
     const role = m.role;
@@ -154,14 +330,14 @@ export function messageTokens(m) {
         structural = 3;
     else if (role === 'tool')
         structural = 6;
-    let body = contentToText(m.content);
+    let body = contentTokens(m.content);
     const tcs = m
         .tool_calls;
     if (tcs) {
         for (const tc of tcs)
-            body += tc?.function?.arguments ?? '';
+            body += estimateTokens(tc?.function?.arguments ?? '');
     }
-    return structural + estimateTokens(body);
+    return structural + body;
 }
 /** 估算整段 messages 的 token 数(不含工具 schema,含 priming 常数)。 */
 export function estimateMessagesTokens(messages) {

package/dist/plan/index.js

@@ -6,7 +6,7 @@
 // 被 repl 依赖(注入 systemPrompt + 状态行 + listener 注册)+ tools/builtins/todolist 依赖。
 export { 
 // store
-plansDir, planPath, ensurePlansDir, newPlanId, parsePlan, serializePlan, readPlan, writePlan, deletePlan, updatePlan, listPlans, renderPlanForLLM, renderPlanChip, } from './store.js';
+plansDir, archiveDir, planPath, ensurePlansDir, ensureArchiveDir, newPlanId, parsePlan, serializePlan, readPlan, writePlan, deletePlan, deletePlanAnywhere, updatePlan, listPlans, archivePlan, unarchivePlan, 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';

package/dist/plan/store.js

@@ -16,9 +16,13 @@ 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`);
+/** 归档目录:<root>/.mocode/plans/archive/。finish 自动归档、用户手动 unarchive 都走这里。 */
+export function archiveDir() {
+    return join(plansDir(), 'archive');
+}
+/** 单 plan 文件路径:<root>/.mocode/plans/<id>.md。可选 baseDir:默认 plans,也可指 archive。 */
+export function planPath(id, baseDir = plansDir()) {
+    return join(baseDir, `${id}.md`);
 }
 /** 确保 plans 目录存在(惰性,工具每次写前调)。 */
 export function ensurePlansDir() {
@@ -26,7 +30,24 @@ export function ensurePlansDir() {
     if (!existsSync(d))
         mkdirSync(d, { recursive: true });
 }
+/** 确保归档目录存在(惰性)。 */
+export function ensureArchiveDir() {
+    const d = archiveDir();
+    if (!existsSync(d))
+        mkdirSync(d, { recursive: true });
+}
 // ── ID 生成 ──
+/** 本地时间戳(无时区后缀),与 filename 的 YYYY-MM-DDTHH-mm-ss 风格一致。
+ *  例:2026-07-04T22:54:51.729(本地时,便于人对读 frontmatter / progress log,
+ *  且与同 plan id 文件名"2026-07-04T22-54-51"对应)。
+ *  不带 Z 后缀 → JS Date 解析会按本地时读(一致 round-trip);
+ *  反例:toISOString() 返 2026-07-04T14:54:51.729Z(UTC),跟用户当地差 8 小时,易误解。 */
+export function localIsoTimestamp(d = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const padMs = (n) => String(n).padStart(3, '0');
+    return (`${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+        `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${padMs(d.getMilliseconds())}`);
+}
 /** 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');
@@ -52,7 +73,7 @@ const LOG_RE = /^-\s+(\S+)\s+(.+?)\s*$/;
  * 解析成功但 step id 缺序 / 重号:按出现顺序重排为 1..N(保稳定)。
  */
 export function parsePlan(raw, fallbackId) {
-    const now = new Date().toISOString();
+    const now = localIsoTimestamp();
     let meta = {};
     let body = raw;
     const m = FRONTMATTER_RE.exec(raw);
@@ -184,9 +205,10 @@ function checkboxMarker(s) {
     }
 }
 // ── CRUD(直接落盘)──
-/** 读 plan 文件;不存在 → null,坏文件 → fallbackId 最小可用 Plan(不抛,工具契约)。 */
-export function readPlan(id) {
-    const p = planPath(id);
+/** 读 plan 文件;不存在 → null,坏文件 → fallbackId 最小可用 Plan(不抛,工具契约)。
+ *  可选 baseDir:默认 plans,传 archiveDir() 可读归档。 */
+export function readPlan(id, baseDir = plansDir()) {
+    const p = planPath(id, baseDir);
     if (!existsSync(p))
         return null;
     try {
@@ -210,9 +232,9 @@ export function writePlan(p) {
         return false;
     }
 }
-/** 删 plan 文件;不存在静默 ok。 */
-export function deletePlan(id) {
-    const p = planPath(id);
+/** 删 plan 文件;不存在静默 ok。可选 baseDir:默认 plans,传 archiveDir() 删归档。 */
+export function deletePlan(id, baseDir = plansDir()) {
+    const p = planPath(id, baseDir);
     if (!existsSync(p))
         return true;
     try {
@@ -243,33 +265,89 @@ export function updatePlan(id, mutator) {
     }
     if (next === false)
         return cur; // 无改动:返原对象
-    next.updated = new Date().toISOString();
+    next.updated = localIsoTimestamp();
     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 [];
+/** 列 plans 目录下所有 plan(按 updated 倒序,最新在前)。解析失败的跳过。
+ *  scope: 'active'(默认)=仅 plans/;'archived'=仅 archive/;'all'=合并(去重按 id)。 */
+export function listPlans(scope = 'active') {
+    const dirs = [];
+    if (scope === 'active')
+        dirs.push(plansDir());
+    else if (scope === 'archived')
+        dirs.push(archiveDir());
+    else {
+        dirs.push(plansDir());
+        dirs.push(archiveDir());
     }
     const out = [];
-    for (const n of names) {
-        const id = n.slice(0, -3);
-        const p = readPlan(id);
-        if (p)
-            out.push(p);
+    const seen = new Set();
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        let names;
+        try {
+            names = readdirSync(dir).filter((n) => n.endsWith('.md'));
+        }
+        catch {
+            continue;
+        }
+        for (const n of names) {
+            const id = n.slice(0, -3);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const p = readPlan(id, dir);
+            if (p)
+                out.push(p);
+        }
     }
     out.sort((a, b) => (a.updated < b.updated ? 1 : a.updated > b.updated ? -1 : 0));
     return out;
 }
+// ── 归档/还原/全删 ──
+/** 把 plans/<id>.md mv 到 plans/archive/<id>.md(atomic rename)。
+ *  源不存在 → false(已归档 / 删了 / 从未存在都算)。 */
+export function archivePlan(id) {
+    const src = planPath(id, plansDir());
+    if (!existsSync(src))
+        return false;
+    ensureArchiveDir();
+    const dst = planPath(id, archiveDir());
+    try {
+        renameSync(src, dst);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/** 把 plans/archive/<id>.md 还原到 plans/<id>.md。源不存在 → false。 */
+export function unarchivePlan(id) {
+    const src = planPath(id, archiveDir());
+    if (!existsSync(src))
+        return false;
+    ensurePlansDir();
+    const dst = planPath(id, plansDir());
+    try {
+        renameSync(src, dst);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/** 任一处存在就都删(活跃 + 归档)。用于 todolist delete 不关心来源。 */
+export function deletePlanAnywhere(id) {
+    let any = false;
+    if (existsSync(planPath(id, plansDir())))
+        any = deletePlan(id, plansDir()) || any;
+    if (existsSync(planPath(id, archiveDir())))
+        any = deletePlan(id, archiveDir()) || any;
+    return any;
+}
 // ── 渲染(给 LLM / UI 用)──
 /** 把 Plan 渲成给 LLM 看的紧凑摘要(多行文本)。 */
 export function renderPlanForLLM(p) {

package/dist/repl/index.js

@@ -15,6 +15,7 @@ import { promptWithSlashMenu, promptTurnPicker, promptSessionPicker, promptTheme
 import { promptIntervention } from '../ui/intervention.js';
 import { tools } from '../tools/registry.js';
 import { estimateMessagesTokens, reconfigureClient, } from '../llm/index.js';
+import { loadImageAttachment, renderChip, MAX_INLINE_BYTES_DEFAULT, } from '../attachments/image.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';
@@ -44,6 +45,7 @@ const SLASH_COMMANDS = [
     { name: '/pet', desc: '开关桌宠(独立悬浮窗,展示 agent 状态动画)' },
     { name: '/pet skin', desc: '选择桌宠皮肤(↑↓·Enter)' },
     { name: '/pet quit', desc: '完全关闭桌宠进程(而非仅断开本连接)' },
+    { name: '/image', desc: '附加本地图片到下一条消息(/image <path> · list · clear)' },
 ];
 /** 主题名 → 一句描述(供 /theme 菜单 / 列表显示)。新增主题时在 src/ui/theme.ts THEMES 加键后于此补一句。 */
 const THEME_DESCRIPTIONS = {
@@ -187,6 +189,10 @@ let runningPlaceholder = '';
 let currentAbort = null;
 let pendingPrefill = null; // /rollback 选中后预填的 user 输入(下轮 INPUT 态消费)
 // agent 模式状态已提到 src/agent/mode.ts(共享叶子:switch_mode 工具可写、agent 每步读、repl 注册 onModeChange 监听器)。
+/** 多模态 user 输入的附件状态。pending = 本轮尚未提交的待发图片;messageAttachments = 已 push 进 history 的图片元数据
+ *  (供 renderHistory 复显文件名——base64 不可逆地塞进 history 后,只能从侧 channel 拿原文件名)。 */
+let pendingAttachments = [];
+const messageAttachments = new Map();
 /** 运行态按键:滚动优先,再 Ctrl+C 中断,再 typeahead 编辑(单行,Enter=无操作)。 */
 function onRunningKey(_str, key) {
     if (!key)
@@ -307,6 +313,10 @@ function echoInput(lines) {
     if (!layout.isActive())
         return;
     layout.contentWrite(formatUserMessage(lines));
+    // 多模态附件:每张一行 chip 跟在 user bubble 后(原 /rollback /resume 复显一致)
+    for (const a of pendingAttachments) {
+        layout.contentWrite(`  ${ui.dim}${renderChip(a)}${ui.reset}\n`);
+    }
 }
 /** 把任意消息 content 拍平成字符串(OpenAI 可能 string / null / 多模态数组)。 */
 function textOf(c) {
@@ -326,15 +336,35 @@ function textOf(c) {
  * user→❯ 回显、assistant→正文(+ tool_calls 作 ● 行)、tool→↳ 结果预览;system 跳过。
  * 思考段不持久(history 只存正文),故无思考折叠。渲染后续写位在末尾,紧接 enterInputMode 画输入框。
  * 内容长于屏时 viewport 显尾(最近轮次),PgUp 可看更早——与流式态一致。
+ * user 多模态:用 textOf 取 text parts;若侧 channel messageAttachments 有原文件名则追加 chip 行
+ * (避免 base64 解码不可逆,旧 session 没侧 channel 时只显文本,文件名 fallback 到 image/* mime)。
  */
 export function renderHistory(history) {
     const idToName = new Map();
-    for (const m of history) {
+    for (let idx = 0; idx < history.length; idx++) {
+        const m = history[idx];
         if (m.role === 'system')
             continue;
         if (m.role === 'user') {
             const lines = textOf(m.content).split('\n');
             layout.contentWrite(formatUserMessage(lines));
+            const atts = messageAttachments.get(idx);
+            if (atts && atts.length > 0) {
+                for (const a of atts) {
+                    layout.contentWrite(`  ${ui.dim}${renderChip(a)}${ui.reset}\n`);
+                }
+            }
+            else if (Array.isArray(m.content)) {
+                // 旧 session 没侧 channel:从 data URL 头抽 mime,显一个通用 chip
+                const c = m.content;
+                for (const p of c) {
+                    if (p && typeof p === 'object' && p.type === 'image_url') {
+                        const url = p.image_url?.url ?? '';
+                        const mime = url.startsWith('data:') ? url.slice(5, url.indexOf(';')) : 'image';
+                        layout.contentWrite(`  ${ui.dim}📷 ${mime}${ui.reset}\n`);
+                    }
+                }
+            }
             continue;
         }
         if (m.role === 'assistant') {
@@ -540,8 +570,26 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
      * 跑一轮 agent(enterRunningMode 已由调用方完成):startRunningListener → runAgent → autosave / reflect。
      * plan 模式传 planMode=true(runAgent 用 planChatTools 只读子集)。返 ok=正常结束(未中断 / 未抛错),
      * 供调用方决定是否弹审批面板。execute 轮的合成输入也走这里。
+     *
+     * 多模态:把 pendingAttachments flush 进 userInput:有图时构造 ContentPart[] 数组;
+     * 无图时保持 string(向后兼容,且 messageTokens 走 estimateTokens 不走 IMAGE_TOKEN_COST)。
+     * side channel 记录本轮 msg 在 history 的 index → attachments,供 renderHistory 复显文件名。
      */
     const runTurn = async (input, planMode, placeholder) => {
+        const imgs = pendingAttachments;
+        pendingAttachments = []; // 入口即清,即使后续抛错也不留陈旧附件
+        const userInput = imgs.length === 0
+            ? input
+            : [
+                { type: 'text', text: input },
+                ...imgs.map((a) => ({
+                    type: 'image_url',
+                    image_url: { url: a.dataUrl, detail: 'auto' },
+                })),
+            ];
+        const msgIndex = history.length; // runAgent push 后 = 这个 index
+        if (imgs.length)
+            messageAttachments.set(msgIndex, imgs);
         let ok = false;
         try {
             const signal = startRunningListener(placeholder);
@@ -550,7 +598,7 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             setAgentMode(planMode ? 'plan' : 'auto');
             // 运行中每步 chat() 返回后刷新状态行 context 用量条(用 fresh lastUsage / 估算),
             // 否则整轮冻结在轮首 refreshStatusBase 的值,「执行 grep」时 2k/1000k 不动。
-            await runAgent(history, input, signal, () => {
+            await runAgent(history, userInput, signal, () => {
                 refreshStatusBase(history);
                 layout.drawStatusBar();
             });
@@ -574,7 +622,20 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
         }
         catch (e) {
             ok = false;
-            layout.contentWrite(`${ui.red}[错误]${ui.reset} ${e instanceof Error ? e.message : String(e)}\n`);
+            // 多模态相关错误友好提示:OpenAI/Anthropic 等会报 "does not support image" / "vision" / "multimodal" 等关键词,
+            // 直接给原文对中文用户不友好。这里翻译成中文 + 提示 /model 换视觉模型。
+            const msg = e instanceof Error ? e.message : String(e);
+            const lower = msg.toLowerCase();
+            const looksLikeImageError = /\b(image|vision|multimodal|vision[-_ ]?capable|unsupported (media|image))\b/i.test(lower) ||
+                /不支持(视觉|图片|图像|多模态)/.test(msg) ||
+                (/图片|图像|视觉|多模态/.test(msg) && /不支持|invalid|reject|fail/i.test(lower));
+            if (looksLikeImageError) {
+                layout.contentWrite(`${ui.red}[错误]${ui.reset} 当前模型 ${ui.cyan}${config.model}${ui.reset} 不支持视觉输入。${ui.dim}原始:${msg}${ui.reset}\n`);
+                layout.contentWrite(`${ui.dim}提示:运行 /model 切换到支持视觉的模型(如 gpt-4o / claude-3.5-sonnet / gemini-1.5-pro)。${ui.reset}\n`);
+            }
+            else {
+                layout.contentWrite(`${ui.red}[错误]${ui.reset} ${msg}\n`);
+            }
         }
         finally {
             stopRunningListener();
@@ -709,11 +770,55 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             currentSessionId = undefined; // 下轮起新会话文件
             turnCount = 0; // 反思 cadence 重新计数
             contextState.lastUsage = undefined;
+            pendingAttachments = []; // 一并清空待发图片
             layout.clearContent();
             layout.contentWrite(bannerString(banner()));
             layout.contentWrite(`${ui.dim}(历史已清空,保留系统提示)${ui.reset}\n`);
             continue;
         }
+        // /image:附加本地图片到下一条 user 消息(支持 /image <path> · /image list · /image clear)。
+        // dispatch 阶段不调 runTurn:仅 mutate pendingAttachments 状态,提交时(runTurn 入口)才 flush 进 history。
+        if (line === '/image' || line === '/image list' || line === '/image clear' || line.startsWith('/image ')) {
+            if (line === '/image list' || (line === '/image' && pendingAttachments.length > 0)) {
+                // 空 /image 视为 list(无歧义;若用户想加图必须 /image <path>)
+                if (pendingAttachments.length === 0) {
+                    layout.contentWrite(`${ui.dim}(无待发送图片)${ui.reset}\n`);
+                }
+                else {
+                    for (const a of pendingAttachments) {
+                        layout.contentWrite(`  ${ui.dim}${renderChip(a)}${ui.reset}\n`);
+                    }
+                }
+                continue;
+            }
+            if (line === '/image clear' || (line === '/image' && pendingAttachments.length === 0)) {
+                // /image 单独输入 + 无 pending:也走 list(空集)
+                if (line === '/image' && pendingAttachments.length === 0) {
+                    layout.contentWrite(`${ui.dim}(无待发送图片)${ui.reset}\n`);
+                }
+                else {
+                    pendingAttachments = [];
+                    layout.contentWrite(`${ui.dim}(已清空待发送图片)${ui.reset}\n`);
+                }
+                continue;
+            }
+            const arg = line.slice('/image'.length).trim().replace(/^["']|["']$/g, '');
+            if (!arg) {
+                layout.contentWrite(`${ui.dim}用法: /image <path>${ui.reset}\n`);
+                continue;
+            }
+            const maxBytes = config.maxImageBytes ?? MAX_INLINE_BYTES_DEFAULT;
+            const r = await loadImageAttachment(arg, { maxBytes });
+            if (!r.ok) {
+                layout.contentWrite(`${ui.red}[image] ${r.reason}${ui.reset}\n`);
+                continue;
+            }
+            if (!pendingAttachments.find((a) => a.id === r.att.id)) {
+                pendingAttachments.push(r.att);
+            }
+            layout.contentWrite(`  ${ui.dim}${renderChip(r.att)} — will attach to next message${ui.reset}\n`);
+            continue;
+        }
         if (line === '/context') {
             layout.contentWrite(`  ${renderContextBar(history)}\n`);
             continue;

package/dist/session/compact.js

@@ -109,6 +109,36 @@ function toText(content) {
         return String(content);
     }
 }
+/**
+ * 把多模态 content 拍平成纯文本(供摘要 transcript 用):text parts 拼接;image_url parts
+ * 替换为 `[图片已剥离: <mime>]` stub,避免 base64 进摘要 prompt(LLM 看到也无意义,反而撑爆 token)。
+ * 其它情况(string / 其它形状)原样返回。
+ */
+export function stripImagesForSummary(m) {
+    const c = m.content;
+    if (Array.isArray(c)) {
+        const parts = [];
+        let imageCount = 0;
+        for (const p of c) {
+            if (p && typeof p === 'object') {
+                const part = p;
+                if (part.type === 'text')
+                    parts.push(part.text ?? '');
+                else if (part.type === 'image_url') {
+                    imageCount++;
+                    const mime = part.image_url?.url?.startsWith('data:')
+                        ? part.image_url.url.slice(5, part.image_url.url.indexOf(';'))
+                        : 'image';
+                    parts.push(`[图片已剥离: ${mime}]`);
+                }
+            }
+        }
+        if (imageCount > 0) {
+            return { ...m, content: parts.join('') };
+        }
+    }
+    return m;
+}
 /** 从尾向头划分 group;history[0](system)排除。连续 tool 归到前导 assistant。 */
 function groupFromEnd(history) {
     const groups = [];
@@ -168,7 +198,9 @@ function flattenGroups(groups) {
 }
 // ── 默认摘要器:复用 chat(),空 handlers 不打印 ──────────────────────────
 async function defaultSummarize(older, focus) {
-    let transcript = older
+    // 摘要前剥离多模态 user 消息里的图片(base64 会撑爆摘要 prompt;image 对摘要无信息量)。
+    const stripped = older.map(stripImagesForSummary);
+    let transcript = stripped
         .map((m) => {
         const role = m.role;
         let line = `${role}: ${toText(m.content)}`;

package/dist/tools/builtins/todolist.js

@@ -6,7 +6,7 @@
 // 单 plan/会话:create 前若有 in_progress 活跃 plan → 拒绝(避免误覆盖);finish/abandoned 后可再建。
 //
 // 工具返回:把当前 plan 紧凑渲染给 LLM(不只返操作结果——让 LLM 单次调用后看到完整状态,无需再 read)。
-import { newPlanId, readPlan, writePlan, updatePlan, listPlans, renderPlanForLLM, } from '../../plan/store.js';
+import { newPlanId, readPlan, writePlan, updatePlan, listPlans, archivePlan, unarchivePlan, deletePlanAnywhere, renderPlanForLLM, localIsoTimestamp, } from '../../plan/store.js';
 import { getActivePlan, setActivePlan, hasActivePlan, clearActivePlan } from '../../plan/active.js';
 import { MAX_OUTPUT } from '../constants.js';
 const VALID_STATUS = new Set([
@@ -23,14 +23,15 @@ export const todolistTool = {
         '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.',
+        'Lifecycle: finish AUTO-ARCHIVES the plan to .mocode/plans/archive/ (history preserved, active dir stays clean). To revisit, call list with scope=archived or unarchive. Use delete to permanently remove a plan (any location).',
     ].join(''),
     parameters: {
         type: 'object',
         properties: {
             action: {
                 type: 'string',
-                enum: ['create', 'read', 'update', 'add_step', 'finish'],
-                description: 'create=新计划;read=读当前活跃;update=改步骤状态;add_step=追加步骤;finish=收尾',
+                enum: ['create', 'read', 'update', 'add_step', 'finish', 'list', 'delete', 'unarchive'],
+                description: 'create=新计划;read=读当前活跃;update=改步骤状态;add_step=追加步骤;finish=收尾(自动归档);list=列计划;delete=永久删除;unarchive=从归档还原到活跃',
             },
             title: { type: 'string', description: 'create 必填:计划标题' },
             goal: { type: 'string', description: 'create 可选:目标描述(写进「目标」段)' },
@@ -55,7 +56,16 @@ export const todolistTool = {
             plan_status: {
                 type: 'string',
                 enum: ['finished', 'abandoned'],
-                description: 'finish 必填:finished=完成;abandoned=放弃(中途取消)',
+                description: 'finish 必填:finished=完成;abandoned=放弃(中途取消)。finished 触发自动归档。',
+            },
+            scope: {
+                type: 'string',
+                enum: ['active', 'archived', 'all'],
+                description: 'list 可选:范围(active=默认,仅进行中;archived=仅归档;all=全)。',
+            },
+            id: {
+                type: 'string',
+                description: 'delete / unarchive 必填:目标 plan id(list 可拿到)。',
             },
         },
         required: ['action'],
@@ -69,8 +79,11 @@ export const todolistTool = {
                 case 'update': return doUpdate(args);
                 case 'add_step': return doAddStep(args);
                 case 'finish': return doFinish(args);
+                case 'list': return doList(args);
+                case 'delete': return doDelete(args);
+                case 'unarchive': return doUnarchive(args);
                 default:
-                    return `错误:未知 action「${action}」,合法值:create / read / update / add_step / finish。`;
+                    return `错误:未知 action「${action}」,合法值:create / read / update / add_step / finish / list / delete / unarchive。`;
             }
         }
         catch (e) {
@@ -99,7 +112,7 @@ function doCreate(args) {
         return `错误:已存在进行中的 plan「${cur?.title ?? ''}」(id=${cur?.id ?? ''}),需先 finish 后再建。`;
     }
     // 旧 plan 残留(finished/abandoned)→ 允许新建,不删历史(用户可后续 read 历史 plan)
-    const now = new Date().toISOString();
+    const now = localIsoTimestamp();
     const plan = {
         id: newPlanId(),
         title,
@@ -195,7 +208,7 @@ function doFinish(args) {
     const updated = updatePlan(cur.id, (p) => {
         p.status = ps;
         p.log.push({
-            at: new Date().toISOString(),
+            at: localIsoTimestamp(),
             text: note || (ps === 'finished' ? '完成' : '放弃'),
         });
         return p;
@@ -203,14 +216,65 @@ function doFinish(args) {
     if (!updated)
         return '错误:finish 写盘失败。';
     setActivePlan(updated);
+    // finished → 自动归档到 plans/archive/(历史完整保留,活跃目录保持干净)。
+    //   abandoned → 不归档(用户想丢就丢,但仍在 plans/ 下,可显式 delete 删掉)。
+    let archived = false;
+    if (ps === 'finished') {
+        archived = archivePlan(updated.id);
+    }
     // finish 后清活跃缓存(下轮 read 自动从 in_progress 列表兜底,本会话不再「活跃」)
-    if (ps === 'abandoned')
-        clearActivePlan();
-    else {
-        // finished 也清:「活跃」专指 in_progress;finished 是历史归档
-        clearActivePlan();
+    clearActivePlan();
+    const archivedNote = ps === 'finished'
+        ? (archived ? '(已自动归档到 plans/archive/)' : '(⚠ 归档失败,plan 仍留在 plans/,可手动 list 排查)')
+        : '';
+    return `${renderSuccess('finish', updated)}\n${archivedNote}`.trimEnd();
+}
+function doList(args) {
+    const scopeRaw = String(args.scope ?? 'active');
+    const scope = scopeRaw === 'archived' || scopeRaw === 'all' ? scopeRaw : 'active';
+    const plans = listPlans(scope);
+    if (plans.length === 0) {
+        return `list: 无 ${scope === 'active' ? '进行中' : scope === 'archived' ? '已归档' : ''}plan。`;
+    }
+    // 一行一条:id | status | 标题 | 进度
+    const lines = [`list (${scope},${plans.length} 条):`];
+    for (const p of plans) {
+        const done = p.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+        const status = p.status === 'in_progress' ? 'live' : p.status === 'finished' ? 'done' : 'gone';
+        lines.push(`  ${p.id}  [${status}]  ${p.title}  (${done}/${p.steps.length})`);
+    }
+    return lines.join('\n');
+}
+function doDelete(args) {
+    const id = String(args.id ?? '').trim();
+    if (!id)
+        return '错误:delete 必填 id(从 list 拿)。';
+    // 安全护栏:active 状态下不能直接 delete 当前活跃(避免误删正在用的 plan)
+    const cur = getActivePlan();
+    if (cur && cur.id === id) {
+        return `错误:不能 delete 当前活跃 plan「${cur.title}」,需先 finish(自动归档)再 delete 归档副本。`;
+    }
+    const ok = deletePlanAnywhere(id);
+    if (!ok)
+        return `错误:delete 失败,id「${id}」在 plans/ 和 plans/archive/ 都找不到。`;
+    return `delete ✓: 已永久删除「${id}」(.mocode/plans/ 与 archive/ 都不再存在)。`;
+}
+function doUnarchive(args) {
+    const id = String(args.id ?? '').trim();
+    if (!id)
+        return '错误:unarchive 必填 id(从 list scope=archived 拿)。';
+    if (!unarchivePlan(id)) {
+        return `错误:unarchive 失败,id「${id}」在 plans/archive/ 找不到(可能已还原,或被 delete)。`;
+    }
+    // 还原后读一次拿回 plan 对象(若 status=in_progress 还可顺手恢复为活跃)
+    const fresh = readPlan(id);
+    if (!fresh)
+        return `unarchive ✓: 「${id}」已还原到 plans/(读取失败,但文件在)。`;
+    if (fresh.status === 'in_progress') {
+        setActivePlan(fresh);
+        return `${renderSuccess('unarchive', fresh)}\n(已自动设为活跃)。`.trimEnd();
     }
-    return renderSuccess('finish', updated);
+    return `${renderSuccess('unarchive', fresh)}\n(注:该 plan 状态为 ${fresh.status},未自动激活 —— 显式 create 才激活)`;
 }
 // ── helpers ──
 /** 从盘上找一个 in_progress plan(进程级 state 丢失/首次访问时兜底)。无 → null。 */

package/dist/ui/layout.js

@@ -774,7 +774,7 @@ function composePlanLine(status, cols) {
     if (!plan)
         return ''; // 无 plan:画空,等 paint 路径 clearLine
     // 整行左对齐,不留右段(plan 自带进度信息,不需要 cwd)
-    return `${ui.dim}│ ${ui.yellow}${plan}${ui.reset}${ui.dim}`;
+    return `${ui.yellow}${plan}${ui.reset}`;
 }
 /** 画状态行(plan 行 + spinner 行 + model 行,三行)。RUNNING 态 spinner 频繁调。
  *  行号(footerH=6):

package/package.json

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