mocode-ai 1.5.0 → 1.5.2

package/dist/i18n/index.js

@@ -225,6 +225,7 @@ const zhCN = {
     'repl.llmTimeoutError': '请求超时：模型服务响应过慢。可重试，或输入 /model switch 换一个模型。',
     'repl.llmNetworkError': '网络错误：无法连接 {base}。检查网络连接，或输入 /model 核对 baseURL 配置。',
     'repl.llmContextError': '上下文超长：输入 /compact 压缩会话后重试。',
+    'repl.llmServerError': '模型服务端在生成中途中断（错误来自响应流内部，非 HTTP 层）。该轮未写入会话历史，直接重发即可；若反复出现，用 /model switch 换模型或 /compact 压缩会话。',
     'permission.path': '路径: {value}',
     'permission.command': '命令: {value}',
     'permission.task': '任务: {value}',
@@ -553,6 +554,7 @@ const en = {
     'repl.llmTimeoutError': 'Request timed out: the model service responded too slowly. Retry, or run /model switch to use another model.',
     'repl.llmNetworkError': 'Network error: cannot reach {base}. Check your connection, or run /model to verify the baseURL.',
     'repl.llmContextError': 'Context too long: run /compact to compress the session, then retry.',
+    'repl.llmServerError': 'The model backend aborted mid-stream (the error came from inside the response stream). This turn was not written to session history — just resend it. If it repeats, run /model switch or /compact.',
     'permission.path': 'Path: {value}',
     'permission.command': 'Command: {value}',
     'permission.task': 'Task: {value}',
@@ -658,7 +660,13 @@ const resources = {
     'zh-CN': zhCN,
     en,
 };
-let currentLanguage = 'zh-CN';
+/**
+ * 未显式配置语言时的默认值。刻意固定为 en 而**不**探测系统 locale：
+ * 中文 Windows 的 `Intl.DateTimeFormat().resolvedOptions().locale` 为 zh-CN，
+ * 会让新装用户一开就是中文界面。要中文须显式 /language zh-CN 或 MOCODE_LANGUAGE=zh-CN。
+ */
+export const DEFAULT_LANGUAGE = 'en';
+let currentLanguage = DEFAULT_LANGUAGE;
 export function normalizeLanguage(value) {
     const normalized = value?.trim().toLowerCase().replace('_', '-');
     if (!normalized)
@@ -669,12 +677,12 @@ export function normalizeLanguage(value) {
         return 'en';
     return null;
 }
+/**
+ * 解析生效语言：只认显式配置（MOCODE_LANGUAGE / ~/.mocode/config / 项目级 config），
+ * 无法识别或未配置时落 DEFAULT_LANGUAGE（en）。不再回退系统 locale。
+ */
 export function detectLanguage(preferred) {
-    const explicit = normalizeLanguage(preferred);
-    if (explicit)
-        return explicit;
-    const system = normalizeLanguage(process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || Intl.DateTimeFormat().resolvedOptions().locale);
-    return system ?? 'zh-CN';
+    return normalizeLanguage(preferred) ?? DEFAULT_LANGUAGE;
 }
 export function setLanguage(language) {
     currentLanguage = language;

package/dist/llm/index.js

@@ -5,6 +5,7 @@ import { getPlanDisabledTools, getProfileDisabledTools } from '../tools/constant
 import { imageSizeFromDataUrl } from '../attachments/image.js';
 import { ThinkTagFilter } from './think-filter.js';
 import { sanitizeToolSchemas } from './tool-schema.js';
+import { isMarkedStreamInterrupted } from './stream-interrupt.js';
 import { defaultAnthropicFetch, anthropicChatOnce } from './providers/anthropic.js';
 import { registerModelProvider, getModelProvider, listModelProviders } from './provider.js';
 // 强制关闭第三方调试日志泄漏:openai SDK 在 process.env.DEBUG === 'true' 时用裸
@@ -29,6 +30,12 @@ const RETRY_MAX_ATTEMPTS = 10;
 const RETRY_BASE_MS = 1000;
 const RETRY_MAX_MS = 30000;
 const RETRY_JITTER = 0.2;
+/**
+ * 「流中途故障」(见 isStreamInterruptedError)单独的重试预算,不共享 HTTP 层的 10 次。
+ * 这类错误绝大多数是推理后端瞬时故障,重试两次足够;若它其实是永久故障,10 次指数退避
+ * (封顶 30s)会让用户干等近两分钟,代价远大于收益。
+ */
+const STREAM_RETRY_MAX_ATTEMPTS = 2;
 /**
  * 流式响应里出现的推理模型自创 `think` 标签(DeepSeek R1 / Qwen3 / 部分自训模型):
  * 与 OpenAI 兼容协议的独立 `reasoning_content` 字段不同,这些模型把 thinking 直接嵌进 content
@@ -130,6 +137,77 @@ export function isRetryableError(err, signal) {
     }
     return false;
 }
+/**
+ * 「传输/协议层的流中断」判据:连接被掐断、响应提前结束、cause 里藏着 errno。
+ *
+ * 实测(Node 22 + openai SDK + 服务端 destroy socket):HTTP 200 建连并已吐出 chunk 后
+ * 连接被掐,抛的是 `Error: Premature close`(code `ERR_STREAM_PREMATURE_CLOSE`)——
+ * 既不是 APIError 也没有 status,`isRetryableError` 一条都不命中。网关超时、NAT 回收、
+ * 推理进程 OOM 被杀、k8s pod 重启都属于这一类,是线上最常见的「半路断流」。
+ *
+ * undici 还会把底层 errno 藏在 `cause` 里(`TypeError: fetch failed` → cause
+ * `SocketError: other side closed` / `read ECONNRESET`),只看顶层必然漏,故沿 cause 链找。
+ */
+const STREAM_BREAK_CODES = new Set([
+    'ERR_STREAM_PREMATURE_CLOSE',
+    'ERR_STREAM_DESTROYED',
+    'ERR_STREAM_UNABLE_TO_PIPE',
+    'ERR_HTTP2_STREAM_CANCEL',
+    'UND_ERR_SOCKET',
+    'ECONNRESET',
+    'ECONNABORTED',
+    'EPIPE',
+    'ETIMEDOUT',
+    'ERR_SOCKET_CONNECTION_TIMEOUT',
+]);
+const STREAM_BREAK_MESSAGE = /premature close|other side closed|socket hang up|\bterminated\b|stream (?:closed|ended) (?:prematurely|unexpectedly)|econnreset|econnaborted/i;
+/** 沿 cause 链(≤3 层)找「连接被掐断」的信号;命中即认为响应流非正常结束。 */
+function hasStreamBreakSignal(err, depth = 0) {
+    if (!err || typeof err !== 'object' || depth > 3)
+        return false;
+    const e = err;
+    if (typeof e.code === 'string' && STREAM_BREAK_CODES.has(e.code))
+        return true;
+    if (typeof e.message === 'string' && STREAM_BREAK_MESSAGE.test(e.message))
+        return true;
+    return hasStreamBreakSignal(e.cause, depth + 1);
+}
+/**
+ * 判定「服务端在响应流中途报错 / 流被中途掐断」——HTTP 层已建连并开始流式返回(状态码 200),
+ * 失败发生在流内部。两条命中路径:
+ *
+ * ① **SSE error chunk**:SDK 的两条流内抛错路径(node_modules/openai/streaming.mjs:41 / :57)
+ *    都构造 `new APIError(undefined, data.error, …)`:status 为 undefined,code/message 取自
+ *    负载,例如 DashScope 的 `ClientError` + `Backend buffer overflow.`。
+ * ② **传输层断流**:见 hasStreamBreakSignal;或 provider 显式打了标记
+ *    (`providers/anthropic.ts` 的 SSE `event: error`,由 markStreamInterrupted 标注)。
+ *
+ * 为什么要单独识别:isRetryableError 只认 status(429 / 5xx)、Node errno 白名单与 timeout 字样,
+ * 这三类都不沾 → 被当成「不可重试的客户端请求错」一次即抛,整轮 run 直接终止。但它们的真实语义
+ * 是「服务端/链路在生成到一半时挂了」,属瞬时故障,重试是正确处置(已实测同一会话更大 prompt 可成功)。
+ *
+ * 只认 APIError 本身,不认子类:APIConnectionError / APIConnectionTimeoutError 已由
+ * isRetryableError 的 name 分支覆盖,而 APIUserAbortError 是用户中断、绝不能重试。
+ * 判据用构造器名而非 instanceof:同进程若存在 openai 的多份模块实例(ESM/CJS 混载),
+ * instanceof 会失配。
+ *
+ * 注意:这里只判定「类别」;能否真的重试还要看调用方的「本次尝试零产出」前提。
+ */
+export function isStreamInterruptedError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.name === 'AbortError' || e.name === 'APIUserAbortError')
+        return false;
+    if (isMarkedStreamInterrupted(err))
+        return true;
+    // 有 HTTP 状态码 = 建连阶段失败,交由 isRetryableError 既有规则处理。
+    if (typeof e.status === 'number')
+        return false;
+    if ((e.constructor?.name ?? '') === 'APIError')
+        return true;
+    return hasStreamBreakSignal(err);
+}
 /**
  * 判定一次失败是否是「请求上下文超长」(后端实测拒绝了我们的 prompt)。
  *
@@ -187,6 +265,13 @@ export function classifyChatError(msg) {
     if (/\benotfound\b|\beconnrefused\b|\beai_again\b|getaddrinfo|fetch failed|network error|certificate/.test(m) ||
         /无法连接|网络(?:错误|异常|不可用)|域名解析/.test(msg))
         return 'network';
+    // 服务端在生成中途故障(流内报错,无 HTTP 状态码):推理后端崩溃 / 网关缓冲溢出等瞬时故障。
+    // 已实测 DashScope compatible-mode 会回 `code=ClientError` + `message="Backend buffer overflow."`。
+    // 走到这里说明重试预算已用尽(或已有半截输出不能重试),给「直接重发」的引导而非裸报错。
+    if (/backend\s+buffer|buffer\s+overflow|engine\s+(?:crash|error|failed|aborted)|internal\s+server\s+error|server\s+(?:overloaded|busy|unavailable)/.test(m) ||
+        /premature close|other side closed/.test(m) ||
+        /后端.{0,10}(?:溢出|崩溃|异常)|服务(?:端|器)(?:内部)?(?:错误|异常|繁忙|不可用)/.test(msg))
+        return 'server';
     return null;
 }
 /** 从 OpenAI APIError.headers 解析 Retry-After(秒);不支持或缺失返回 undefined。封顶 RETRY_MAX_MS。 */
@@ -352,23 +437,50 @@ toolsOverride) {
 }
 async function chatWithRuntime(runtime, messages, handlers, signal, toolsOverride) {
     let lastErr;
+    // 本次尝试是否已向调用方产出过内容(可见文本 / 工具名)。用于判断「流中途故障可否安全重试」:
+    // 重试会从请求头重放,已流出并显示在内容区的半截文本会再写一遍(history 因异常未落,倒是不脏)。
+    // 用包装 handler 而非改各 provider 内部,OpenAI / Anthropic 两条路径统一生效。
+    let producedOutput = false;
+    const guardedHandlers = {
+        ...handlers,
+        onText: (text) => {
+            producedOutput = true;
+            handlers.onText?.(text);
+        },
+        onToolCall: (name) => {
+            producedOutput = true;
+            handlers.onToolCall?.(name);
+        },
+    };
+    // 流中途故障用独立计数,避免与 HTTP 层共享 10 次预算(理由见 STREAM_RETRY_MAX_ATTEMPTS)。
+    let streamRetries = 0;
     for (let attempt = 1; attempt <= RETRY_MAX_ATTEMPTS; attempt++) {
         if (signal?.aborted) {
             throw new DOMException('This operation was aborted', 'AbortError');
         }
+        producedOutput = false;
         try {
             const provider = getModelProvider(runtime.config.provider);
             if (!provider) {
                 // 未注册的 provider:给出可用名单,避免悄悄落到错误实现。
                 throw new Error(`未知的 LLM provider "${runtime.config.provider}";已注册:${listModelProviders().join(', ') || '(空)'}`);
             }
-            return await provider.chatOnce(messages, handlers, signal, toolsOverride, runtime);
+            return await provider.chatOnce(messages, guardedHandlers, signal, toolsOverride, runtime);
         }
         catch (err) {
             lastErr = err;
-            if (attempt >= RETRY_MAX_ATTEMPTS || !isRetryableError(err, signal)) {
+            // 流中途故障的额外可重试窗口:仅当本次尝试零产出(否则重试会重放半截文本)、用户没有中断、
+            // 且未超它的独立预算。HTTP 层规则(isRetryableError)保持原样,两条判定取并集。
+            // 用户中断必须显式排除:undici 在 abort 时也可能抛「连接被掐断」形态的错,只看错误本身会误判。
+            const streamRetryable = !signal?.aborted &&
+                isStreamInterruptedError(err) &&
+                !producedOutput &&
+                streamRetries < STREAM_RETRY_MAX_ATTEMPTS;
+            if (attempt >= RETRY_MAX_ATTEMPTS || (!isRetryableError(err, signal) && !streamRetryable)) {
                 throw err;
             }
+            if (streamRetryable)
+                streamRetries++;
             const wait = computeBackoff(attempt, getRetryAfterMs(err));
             const retry = {
                 attempt,

package/dist/llm/providers/anthropic.js

@@ -1,4 +1,5 @@
 import { config, getActiveModel } from '../../config/index.js';
+import { markStreamInterrupted } from '../stream-interrupt.js';
 let fetchImplOverride = null;
 /** 仅供单测注入；生产路径使用 Node 18+ 全局 fetch。 */
 export function __setAnthropicFetchImpl(impl) {
@@ -292,6 +293,11 @@ export async function anthropicChatOnce(messages, handlers, signal, tools, runti
             const error = event.error;
             const thrown = new Error(typeof error?.message === 'string' ? error.message : 'Anthropic stream error');
             thrown.name = typeof error?.type === 'string' ? error.type : 'AnthropicStreamError';
+            // 打「流中途中断」标记:HTTP 层已 200 建连说明请求本身被接受了,流内报错必然是服务端侧
+            // (overloaded_error / api_error 等瞬时故障)。没有这个标记,它就是个无 status 的普通
+            // Error → isRetryableError 一条都不命中 → 整轮 run 直接终止、一次都不重试。
+            // 真正的重试门槛由 chatWithRuntime 的「本次尝试零产出」前提把关。
+            markStreamInterrupted(thrown);
             throw thrown;
         }
         if (type === 'message_start') {

package/dist/llm/stream-interrupt.js

@@ -0,0 +1,24 @@
+/**
+ * 「流中途被打断」的显式标记。
+ *
+ * 为什么需要它:能否安全重试取决于「错误是否发生在响应流**里面**」(HTTP 层已 200 建连),
+ * 而这类错误的判定只能由**抛错方**知道 —— OpenAI 兼容路径是 SDK 造的 status-less `APIError`,
+ * Anthropic 路径是 SSE `event: error`(一个 name 被设成供应商错误类型的普通 Error)。
+ * 与其在 transport 层猜 vendor 的错误名,不如让 provider 在抛错时打标。
+ *
+ * 独立成 leaf 模块(零 import):`llm/index.ts` 与 `llm/providers/*.ts` 都要用它,
+ * 而 providers 只对 index 做 type-only import(见 provider.ts 头注),放 index 会成环。
+ *
+ * 只标记「错误类别」,不代表可以无条件重试:调用方仍必须叠加「本次尝试零产出」前提
+ * (见 chatWithRuntime 的 producedOutput),否则重试会在内容区重放半截文本。
+ */
+const interrupted = new WeakSet();
+/** 由 provider 在「响应流内部报错」时调用,标记该错误为可重试的流中断。 */
+export function markStreamInterrupted(err) {
+    if (err && typeof err === 'object')
+        interrupted.add(err);
+}
+/** 该错误是否被标记为流中途中断。 */
+export function isMarkedStreamInterrupted(err) {
+    return !!err && typeof err === 'object' && interrupted.has(err);
+}

package/dist/repl/commands.js

@@ -148,6 +148,7 @@ export const LLM_ERROR_HINT_KEYS = {
     timeout: 'repl.llmTimeoutError',
     network: 'repl.llmNetworkError',
     context: 'repl.llmContextError',
+    server: 'repl.llmServerError',
 };
 /** /help 的分组:按使用场景归组,组内保持菜单树顺序。未列入的顶层命令兜底进「其他」。 */
 export const HELP_GROUPS = [

package/docs/usage.md

@@ -0,0 +1,344 @@
+# MoCode 使用指南
+
+> 面向首次使用和日常开发的菜单式帮助。命令在全屏 TUI 中输入；输入 `/` 可打开并筛选命令菜单。
+
+## 帮助菜单
+
+| 入口                               | 适用场景                                     |
+| ---------------------------------- | -------------------------------------------- |
+| [01 快速开始](#快速开始)           | 安装、配置并启动第一个会话                   |
+| [02 日常对话](#日常对话)           | 把需求交给 Agent，控制执行范围               |
+| [03 命令行](#命令行)               | 新建、恢复会话和设置沙箱根目录               |
+| [04 TUI 命令菜单](#tui-命令菜单)   | 在会话内管理配置、上下文、文件与界面         |
+| [05 PLAN / AUTO](#plan--auto-模式) | 先调研规划，或直接执行                       |
+| [06 会话与回滚](#会话与回滚)       | 恢复历史、中断任务、撤销文件变更             |
+| [07 项目上下文](#项目上下文)       | `AGENTS.md` 与 Skills                        |
+| [08 配置参考](#配置参考)           | 配置优先级和常用环境变量                     |
+| [09 常见问题](#常见问题)           | 连不上模型、工具不调用、上下文过长等         |
+| [10 输入框快捷键](#输入框快捷键)   | 输入框内的所有键盘快捷键、命令菜单与鼠标操作 |
+
+---
+
+## 快速开始
+
+**1. 安装 Node.js 18 或更高版本，然后安装 MoCode：**
+
+```bash
+npm install -g mocode-ai
+```
+
+不想全局安装时，直接运行 `npx mocode-ai`。
+
+**2. 配置一个支持 OpenAI 风格 function calling 的模型：**
+
+```bash
+mocode config
+```
+
+向导会写入全局配置 `~/.mocode/config`。也可以先运行 `mocode`，再在 TUI 输入 `/model` 配置。
+
+**3. 在目标项目目录启动：**
+
+```bash
+mocode
+```
+
+例如：`cd your-project` 后再运行 `mocode`。Agent 的默认文件操作范围就是启动目录。
+
+**4. 用一个可验证的目标开始：**
+
+```text
+请先阅读 README 和 package.json，告诉我如何启动项目；不要修改文件。
+```
+
+确认连通后，再给出明确的开发目标，例如“为登录接口补充参数校验，并运行相关验证”。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## 日常对话
+
+MoCode 会在“思考 → 调用工具 → 观察结果 → 再思考”的循环中自主推进任务。把**目标、约束和验证要求**放在一条消息里，效果最好：
+
+```text
+检查支付模块的重试逻辑，找出可能重复扣款的路径；先给我一个只读分析和修复计划，未经确认不要改文件。
+```
+
+实用提示：
+
+- 先说明是否允许修改、是否允许执行命令，以及希望运行的验证。
+- 对陌生项目，可先用 `/plan`，或直接要求“只读分析，不修改文件”。
+- 任务运行中可按 `Ctrl+C` 打断当前轮次；不会留下半完成的工具调用。
+- 在复杂任务中，Agent 可能维护 `.mocode/sessions/<session-id>/notes.md` 记录计划、发现与未决问题。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## 命令行
+
+| 命令                           | 说明                                        |
+| ------------------------------ | ------------------------------------------- |
+| `mocode`                       | 在当前目录开启新会话。                      |
+| `mocode config`                | 运行模型配置向导，写入 `~/.mocode/config`。 |
+| `mocode --resume`              | 列出已保存会话。                            |
+| `mocode --resume <id>`         | 恢复指定会话。                              |
+| `mocode --sandbox-root <path>` | 覆盖本次运行的文件操作沙箱根目录。          |
+| `npx mocode-ai`                | 无需全局安装，直接运行。                    |
+
+从源码开发时使用 `npm start`；它直接通过 `tsx` 运行源码，不会执行发布版的后台更新检查。修改 TypeScript 后请重启该命令。
+
+> `--sandbox-root` 的优先级高于 `SANDBOX_ROOT`；没有设置时，沙箱根目录为当前工作目录。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## TUI 命令菜单
+
+输入 `/` 打开下拉菜单，继续输入可筛选，`Esc` 取消。以下命令均在 TUI 中执行。
+
+### 会话、上下文与界面
+
+| 命令                       | 作用                                                 |
+| -------------------------- | ---------------------------------------------------- |
+| `/exit`、`/quit`           | 退出 MoCode。                                        |
+| `/clear`                   | 清空会话历史并清屏，保留系统提示。                   |
+| `/context`                 | 查看 token 与消息数的上下文使用情况。                |
+| `/compact [focus]`         | 压缩旧历史；可附焦点，例如 `/compact 保留接口约定`。 |
+| `/compact --force [focus]` | 即使可压缩内容很少也强制压缩早期对话。               |
+| `/resume`                  | 在最近会话中选择并恢复。                             |
+| `/sessions`                | 浏览全部已保存会话。                                 |
+| `/rollback`                | 选择一个轮次，按文件决定保留或撤销其快照中的改动。   |
+| `/theme [name]`            | 选择或直接切换颜色主题。                             |
+
+### 模型、输入与工具能力
+
+| 命令                      | 作用                                                             |
+| ------------------------- | ---------------------------------------------------------------- |
+| `/model`                  | 交互设置 Base URL、API Key、模型和上下文窗口；立即生效并持久化。 |
+| `/skills`                 | 列出已发现的 Skills。                                            |
+| `/image <path>`           | 将本地图片附加到下一条消息。                                     |
+| `/image list`             | 查看待发送图片。                                                 |
+| `/image clear`            | 清除待发送图片。                                                 |
+| `/fe on/off/status`       | 允许或硬禁用 `browser-debug` / `desktop-observe` 自动路由。      |
+| `/cu on/off/status`       | 允许或硬禁用高危 `computer-control` 自动路由。                   |
+| `/subagent on/off/status` | 允许或硬禁用 `orchestration` 自动路由。                          |
+| `/mcp on/off/status`      | 管理 MCP 连接生命周期及其动态工具簇。                            |
+| `/pet`                    | 打开或断开可选桌宠窗口。                                         |
+| `/pet skin`               | 为已运行的桌宠选择皮肤。                                         |
+| `/pet quit`               | 完全关闭桌宠进程。                                               |
+
+### 记忆与项目上下文
+
+| 命令                           | 作用                                                                |
+| ------------------------------ | ------------------------------------------------------------------- |
+| `/init`                        | 让 Agent 扫描项目，生成或刷新 `AGENTS.md` 项目记忆。                |
+| `/memory`                      | 查看跨会话长期记忆的索引。                                          |
+| `/memory_switch on/off/status` | 同时管理 memory 自动路由 gate 与 Memory Index；下一真实用户轮生效。 |
+| `/memory_status`               | 分别查看 memory route gate 与 Memory Index / 反思状态。             |
+| `/reflect`                     | 手动触发一次后台记忆反思。                                          |
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## PLAN / AUTO 模式
+
+| 模式     | 适用情况                             | 能力                                                                           |
+| -------- | ------------------------------------ | ------------------------------------------------------------------------------ |
+| **PLAN** | 先理解代码、评估风险、产出可审阅方案 | 只读调研与规划；不写文件、不执行命令、不派生子 Agent。                         |
+| **AUTO** | 需求明确，允许自主完成实现与验证     | 每轮由 LLM router 选择最小充分工具簇；能力不足时主模型可在下一 step 单向扩容。 |
+
+- `/plan` 切换到 PLAN 模式。它适合“先分析、不要改动”的任务。
+- `/auto` 切回 AUTO 模式，允许执行方案。
+- 在支持的终端中，`Shift+Tab` 也可切换到 PLAN；若输入法或终端吞掉该按键，使用 `/plan` 即可。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## 会话与回滚
+
+每轮对话会自动保存。启动时可用 `mocode --resume` 查找会话，或在 TUI 用 `/resume` 选择最近会话；需要浏览更久以前的历史时使用 `/sessions`。
+
+文件修改前会按轮次创建快照。使用 `/rollback` 选中目标轮次后，可逐文件决定**保留**或**撤销**。从旧会话恢复但没有相应快照的改动无法通过该功能撤销；重要改动仍建议放在 Git 版本控制下。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## 项目上下文
+
+MoCode 通过 `AGENTS.md` 与 Skills 理解项目：
+
+| 功能            | 默认状态           | 内容与操作                                                                                                               |
+| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| **`AGENTS.md`** | 按文件存在情况加载 | 每轮自动加载的 Markdown 项目记忆（同时覆盖静态文件结构、命令清单与项目约定/坑点）。用 `/init` 生成初稿，随后可手工维护。 |
+| **Skills**      | 按需加载           | 通过 `use_skill` 工具按需加载的额外能力。详见 `~/.mocode/skills/` 与 `.mocode/skills/`。                                 |
+
+Skills 则是可复用的任务说明。MoCode 默认扫描：
+
+- `~/.claude/skills/`
+- `~/.mocode/skills/`
+- `<项目目录>/.mocode/skills/`
+
+每个 Skill 是带 frontmatter 的 `<名称>/SKILL.md`。系统先加载其 `description`，任务相关时再加载完整内容。用 `SKILLS_DIRS` 可覆盖默认扫描目录；Windows 用 `;` 分隔多个路径，macOS/Linux 用 `:`。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## MCP 与浏览器能力
+
+MCP 和浏览器相关能力是可选扩展，不影响基本的文件编辑与命令执行。使用前先确认：
+
+- MCP：在配置文件中设置 MCP 服务后，使用 `/mcp status` 查看连接状态，使用 `/mcp on` 或 `/mcp off` 管理运行时连接；不同 MCP 服务的配置格式以对应服务文档为准。
+- 浏览器：`browser` 默认只访问本机 `http/https` 地址；需要访问远程站点时显式设置 `MOCODE_BROWSER_ALLOW_REMOTE=true`。首次使用前安装 Chromium：
+
+  ```bash
+  npx playwright install chromium
+  ```
+
+- `dev_server` 会执行你提供的启动命令，风险等级与 `run_command` 相同；它需要确认，不要把不可信字符串直接作为启动命令传入。
+- PLAN 模式禁用浏览器和 `dev_server`；切换到 AUTO 后才允许 Agent 使用这些能力。
+- 退出 MoCode 时，已登记的开发服务器会被清理，浏览器会话也会关闭；如果进程是外部启动的，请自行检查并停止。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## 安全边界与已知限制
+
+MoCode 可以读写项目文件并执行命令，使用前请把它当作一个需要监督的自动化开发工具：
+
+- 默认沙箱根目录是启动目录；可用 `--sandbox-root <path>` 或 `SANDBOX_ROOT` 缩小文件操作范围。沙箱限制不等于操作系统级隔离，仍应避免在包含敏感文件的目录中运行。
+- `safe`、`confirm`、`dangerous` 是工具风险等级。看到确认提示时，请核对命令、路径和参数，而不是只按回车。
+- API Key 只放在 `~/.mocode/config`、项目级配置或 shell 环境变量中，不要提交到 Git，也不要粘贴到对话内容里。
+- 回滚依赖每轮快照；从没有对应快照的旧会话恢复时，不能保证通过 `/rollback` 撤销外部产生的改动。重要项目仍建议使用 Git 提交或工作树备份。
+- Agent 不会因为任务结束而自动运行完整测试或构建，也不会强制追加一轮验证。需要验证时，在任务中明确要求它运行哪些命令，并自行检查结果。
+- 当前模型需要支持 OpenAI 风格 function calling；只支持普通文本生成的模型无法可靠使用工具。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## 常见问题
+
+### 配置加载优先级
+
+以下来源从低到高覆盖；已在 shell 中设置的环境变量始终最高优先级：
+
+1. `<当前目录>/.env`（兼容旧用法）
+2. `~/.mocode/config`（`mocode config` 与 `/model` 写入的位置）
+3. `<当前目录>/.mocode/config`（项目级覆盖）
+4. Shell 环境变量
+
+最小配置：
+
+```env
+LLM_BASE_URL=https://api.example.com/v1
+LLM_API_KEY=your-api-key
+LLM_MODEL=your-model-name
+```
+
+模型必须支持 **OpenAI 风格的 function calling**，否则 MoCode 无法可靠调用工具。
+
+### 常用环境变量
+
+| 变量                            | 用途                                                                        | 默认值                   |
+| ------------------------------- | --------------------------------------------------------------------------- | ------------------------ |
+| `CONTEXT_WINDOW_TOKENS`         | 模型实际上下文窗口大小。                                                    | `256000`                 |
+| `MAX_TOKENS`                    | 单次回复最大 token 数。                                                     | 不限制                   |
+| `AUTO_COMPACT`                  | 上下文自动压缩开关；开启时统一在 80% 占用触发。                             | `true`                   |
+| `MAX_STEPS`                     | 每轮 Agent 工具循环的最大步数。                                             | `200`                    |
+| `SUB_AGENT_MAX_STEPS`           | 子 Agent 默认最大步数。                                                     | `50`                     |
+| `SANDBOX_ROOT`                  | 文件操作与命令工作目录的沙箱根。                                            | 当前工作目录             |
+| `MOCODE_SUBAGENT_ENABLED`       | 设 `false` 硬禁用 `orchestration`；unset/`true` 允许按需路由。              | 未设置                   |
+| `MOCODE_FRONTEND_TOOLS_ENABLED` | 设 `false` 硬禁用 browser/desktop 路由簇；unset/`true` 允许。               | 未设置                   |
+| `MOCODE_COMPUTER_USE_ENABLED`   | 设 `false` 硬禁用高危 `computer-control`；unset/`true` 允许明确意图时路由。 | 未设置                   |
+| `MEMORY_ENABLED`                | 设 `false` 硬禁用 memory 簇；`true` 还会启用 Memory Index。                 | 未设置                   |
+| `MOCODE_THEME`                  | TUI 颜色主题。                                                              | `default`                |
+| `ANYSEARCH_API_KEY`             | 可选联网搜索 API Key。                                                      | 未设置时使用匿名免费额度 |
+
+完整注释示例见仓库根目录的 [`.env.example`](../.env.example)。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+## 输入框快捷键
+
+在 TUI 底部的输入框内，几乎所有编辑都通过键盘完成。下表覆盖当前版本支持的全部快捷键；若与你的终端有冲突（例如某些终端把 `Ctrl+Backspace` 当作普通退格），以终端实际发送为准。
+
+### 光标移动
+
+| 按键                         | 作用                                                                                                     |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `←` / `→`                    | 左 / 右移动一个字符；已到行首或行尾时跨到上一行 / 下一行                                                 |
+| `↑` / `↓`                    | 多行输入时上下移动一行；已在首行 / 末行且未打开命令菜单时，改为**滚动内容区**（每格 3 行，等同鼠标滚轮） |
+| `Home` / `Ctrl+A` / `Ctrl+Q` | 跳到当前行行首                                                                                           |
+| `End` / `Ctrl+E`             | 跳到当前行行尾（`Ctrl+Q` 与 `Ctrl+E` 在键盘顶行相邻，构成左右对称的行首/行尾对）                         |
+
+### 编辑与删除
+
+| 按键        | 作用                                                                   |
+| ----------- | ---------------------------------------------------------------------- |
+| `Backspace` | 删除光标前一个字符；在行首时并入上一行；光标紧贴粘贴块时删除整个粘贴块 |
+| `Delete`    | 删除光标后一个字符；在行尾时并入下一行                                 |
+| `Ctrl+U`    | 删除从行首到光标处的所有内容                                           |
+| `Ctrl+K`    | 删除从光标到行尾的所有内容；在行尾时并入下一行                         |
+
+### 撤销清空
+
+| 按键     | 作用                                                                           |
+| -------- | ------------------------------------------------------------------------------ |
+| `Ctrl+Z` | 撤销一次 `Ctrl+C` 造成的输入框清空（单次：仅还原清空前的内容，再次按下无效果） |
+
+### 换行、发送与会话控制
+
+| 按键                                                  | 作用                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------- |
+| `Enter`                                               | 发送消息，开始一轮 Agent 执行                           |
+| `Ctrl+J` / `Ctrl+Enter` / `Alt+Enter` / `Shift+Enter` | 在输入框内插入换行，用于编写多行消息（不直接发送）      |
+| `Ctrl+C`                                              | 输入框**有内容**时清空输入框；**空**输入框时退出 MoCode |
+| `Ctrl+D`                                              | 输入框为空时退出 MoCode；有内容时忽略                   |
+
+> 提示：`Ctrl+C` 在 Agent **运行中**用于中断当前轮次（见[日常对话](#日常对话)），在输入框**空闲**时用于清空——两者行为不同。
+
+### 滚动内容区（输入框聚焦时也可使用）
+
+| 按键     | 作用          |
+| -------- | ------------- |
+| `PgUp`   | 向上翻一页    |
+| `PgDn`   | 向下翻一页    |
+| `Ctrl+↑` | 向上滚动 5 行 |
+| `Ctrl+↓` | 向下滚动 5 行 |
+
+### 命令菜单与补全
+
+| 按键      | 作用                                           |
+| --------- | ---------------------------------------------- |
+| `/`       | 进入命令菜单，继续输入可筛选命令               |
+| `↑` / `↓` | 菜单打开时在候选间移动                         |
+| `Tab`     | 选中当前高亮项并补全（例如 `/model` 的子命令） |
+| `Esc`     | 处于子菜单时回到上一级；否则关闭菜单           |
+
+### 模式切换
+
+| 按键        | 作用                                                                 |
+| ----------- | -------------------------------------------------------------------- |
+| `Shift+Tab` | 在 PLAN / AUTO 模式之间切换（若终端吞掉该键，改用 `/plan`、`/auto`） |
+
+### 粘贴
+
+- 直接 `Ctrl+V`（或中键 / 右键，取决于终端）粘贴大段文本或多行内容时，MoCode 会识别为粘贴：整段作为**不可编辑的粘贴块**一次性插入，提交时还原为原文。这避免逐字符触发编辑，也防止超长文本卡顿。
+- **连续粘贴会生成多个独立的粘贴块**（如 `[📋 121 行 · 2.7K 字符][📋 121 行 · 2.7K 字符]` 紧邻），每个块互不影响，不会把新内容并入旧块。
+- **两个粘贴块之间的文字是可编辑的**：在块之间敲的字、回退、插入都正常生效；在块前按 `Backspace` 删除该块、在块后按 `Delete` 删除下一块。
+- 短小的单行粘贴（≤8 行且 ≤200 字符）会当作普通可编辑文本插入，不生成块。
+
+[↑ 返回帮助菜单](#帮助菜单)
+
+---
+
+## 常见问题
+
+**启动后无法回复，或提示未配置模型**  
+运行 `mocode config` 或 TUI 中的 `/model`，检查 `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL` 三项。若 shell 中设置了同名变量，它会覆盖配置文件值。
+
+**Agent 不调用工具**  
+确认模型和后端支持 OpenAI 风格 function calling；纯文本聊天模型无法可靠执行工具调用。
+
+**Agent 操作了错误目录，或文件被沙箱拒绝**  
+在正确项目目录启动 `mocode`，或明确设置 `--sandbox-root <path>` / `SANDBOX_ROOT`。沙箱会拒绝越界相对路径、沙箱外绝对路径和符号链接逃逸。
+
+**上下文快满了**  
+使用 `/context` 查看用量，使用 `/compact` 压缩；也可以缩小任务、明确焦点，或将 `CONTEXT_WINDOW_TOKENS` 设置为模型真实窗口。
+
+**联网搜索失败或限流**  
+可设置 `ANYSEARCH_API_KEY` 使用自己的额度；不设置时会使用匿名免费额度并受 IP 限流。
+
+---
+
+还需要定位具体能力时，可从 [帮助菜单](#帮助菜单) 返回，或在 TUI 输入 `/` 查看当前版本实际提供的命令。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 25 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {
@@ -10,7 +10,9 @@
   "files": [
     "dist",
     "bin",
-    "README.md"
+    "README.md",
+    "README.zh-CN.md",
+    "docs/usage.md"
   ],
   "workspaces": [
     "packages/*"