mocode-ai 1.5.0 → 1.5.1

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.1",
   "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/*"