@minko-ai/minko 0.1.0 → 0.1.1

package/README.md

@@ -26,6 +26,39 @@ minko config --preset anthropic --api-key sk-ant-xxxx
 minko config --list
 ```
 
+## 服务商矩阵与 fallback
+
+`minko config` 内置这些预设：
+
+| 预设 | 类型 | 默认地址 |
+| --- | --- | --- |
+| DeepSeek | OpenAI 兼容 | `https://api.deepseek.com` |
+| Claude | Anthropic | `https://api.anthropic.com` |
+| OpenAI | OpenAI 兼容 | `https://api.openai.com/v1` |
+| xAI | OpenAI 兼容 | `https://api.x.ai/v1` |
+| DashScope / Qwen | OpenAI 兼容 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| Kimi | OpenAI 兼容 | `https://api.moonshot.cn/v1` |
+| OpenRouter | OpenAI 兼容 | `https://openrouter.ai/api/v1` |
+| Ollama（本地） | OpenAI 兼容 | `http://127.0.0.1:11434/v1`，无需 Key |
+
+也可以配置任意 OpenAI / Anthropic 兼容地址。本地 `localhost` / `127.0.0.1` 服务允许空 API Key，
+OpenAI 兼容请求不会发送空的 `Authorization`。
+
+失败切换链：
+
+```json
+{
+  "active": "deepseek",
+  "providers": { "...": "..." },
+  "fallbackProviders": ["claude-backup", "openai"],
+  "modelAliases": { "fast": "deepseek-chat" }
+}
+```
+
+- 主服务商重试耗尽后按顺序切换；401/403/429/5xx 和网络错误会触发，400 不切换；
+- 每次切换会在终端显示提示；`minko status` 显示 fallback 链；
+- `modelAliases` 可自定义别名；Anthropic 还内置 `sonnet` / `opus` / `haiku` 短名。
+
 ## 用法
 
 ```bash
@@ -35,6 +68,16 @@ minko -p "总结 README"      # 一次性输出，适合管道
 minko -c                    # 继续当前目录最近一次会话
 minko -r <会话id>           # 继续指定会话
 minko sessions              # 列出保存的会话
+minko fork <id> [名字]       # 复制会话分支（id 可以是 latest）
+minko login                 # OAuth 设备码登录
+minko status                # 查看配置、模型、会话、插件状态
+minko doctor                # 检查运行环境与配置
+minko export latest --out chat.md   # 导出会话（md/json）
+minko rag --port 8787       # 启动本地 RAG HTTP 服务
+minko mcp-server            # 把只读工具暴露为 MCP stdio server
+minko mcp-login <server>    # 远程 MCP server 的 OAuth 登录
+minko sdk                   # 启动 NDJSON JSON-RPC SDK
+minko commands [--json]     # slash command 元数据
 minko --auto "..."          # 不再逐条确认（危险）
 ```
 
@@ -45,12 +88,24 @@ minko --auto "..."          # 不再逐条确认（危险）
 | `/help` | 帮助 |
 | `/new` | 新会话 |
 | `/clear` | 清空上下文 |
+| `/compact [n]` | 把较早对话折叠成摘要，保留最近 n 条（默认 4） |
+| `/plan` | 切换只读计划模式 |
+| `/todos` | 查看当前待办清单 |
+| `/fork [名字]` | 从当前会话复制一个分支 |
 | `/model <id>` | 临时切换模型 |
 | `/sessions` | 最近会话 |
 | `/exit` | 退出 |
 
+在会话里输入 `/help` 查看完整命令列表（按会话/上下文/状态/工具/设置分组，支持别名与拼写建议）。
+其余命令：`/status`、`/usage`、`/workers`、`/tasks`、`/crons`、`/lanes`、`/approvals`、
+`/plugins`、`/skills`、`/memory`、`/sandbox`、`/export [路径]`。
+
 `Ctrl+C` 中断当前回复，再按一次退出。
 
+终端界面里，思考过程会先以灰色斜体流式显示，结束后折叠成一行耗时；工具调用显示为
+`● run_shell  npm test · 1.4s · 472 B` 这样的单行状态，连续同名工具会合并成 `×N`，
+输出只保留末尾几行。按 `Ctrl+O` 展开/收起这些详情；回答、思考和工具调用按实际发生的顺序交错出现。
+
 ## 工具与确认
 
 | 工具 | 说明 | 确认 |
@@ -60,18 +115,538 @@ minko --auto "..."          # 不再逐条确认（危险）
 | `write_file` | 写文件（工作区内直接写） | 工作区外需要 |
 | `run_shell` | 在电脑上执行命令 | 每次需要 |
 
+另外还有 `notebook_edit`（编辑 .ipynb 的 replace / insert / delete）和
+`structured_output`（按 JSON Schema 子集校验并输出结构化结果）。
+
 确认时可选 `y` 允许一次、`a` 本会话总是允许、`n` 拒绝。
 `--auto` 跳过所有确认，只建议在可信目录里用。
 
+## 权限规则
+
+在 `~/.minko/config.json` 增加：
+
+```json
+{
+  "permissions": {
+    "deny": ["run_shell(rm -rf*)", "write_file(.git/*)"],
+    "ask": ["run_shell(git push*)"],
+    "allow": ["read_file", "write_file(src/*)"]
+  }
+}
+```
+
+规则格式为 `工具名` 或 `工具名(匹配内容)`。`*` / `?` 是通配符；没有通配符时按前缀匹配。
+匹配对象：`run_shell` 用命令，文件工具用路径，其他工具用 JSON 参数。优先级 **deny > ask > allow**；
+`ask` 即使加了 `--auto` 也会走确认；`allow` 不能绕过 `readonly` / `workspace` 模式。
+
+## Hooks
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "run_shell", "hooks": [{ "command": "node scripts/audit.js" }] }
+    ],
+    "PostToolUse": ["echo checked"],
+    "PostToolUseFailure": []
+  }
+}
+```
+
+hook 从 stdin 收到 `{ event, tool_name, tool_input, tool_output?, is_error }`，向 stdout 输出 JSON：
+
+```json
+{ "continue": false, "reason": "blocked" }
+{ "systemMessage": "lint passed" }
+{ "hookSpecificOutput": {
+    "permissionDecision": "allow|deny|ask",
+    "permissionDecisionReason": "why",
+    "updatedInput": { "command": "改写后的参数" },
+    "additionalContext": "给模型的额外说明"
+} }
+```
+
+非 JSON 的 stdout 会作为消息追加到工具结果；命令非零退出视为 hook 失败并阻止工具执行。
+`matcher` 支持 `*`、逗号或 `|` 分隔的工具名。
+
+## 长会话与重试
+
+- 上下文超过约 100k token 时，较早的对话会自动折叠成摘要，保留最近 4 条；摘要随会话保存。
+- 发送前会估算这一次请求的大小；超过约 40 万 token 时先强制压缩较早内容再继续，压缩后仍超限才停止本轮。判断依据是当前请求，不是整个任务的累计用量。
+- 429 / 5xx / 网络错误自动重试（指数退避，尊重 `Retry-After`）；400 / 401 / 403 不重试。
+- 服务端判定请求超长时，会逐步压缩较早内容后重试。
+- Anthropic 协议会在 system、tools 和对话末尾设置 `cache_control` 缓存断点；网关不支持缓存时自动退回普通请求。终端统计会显示缓存命中的 token 数。
+- 项目内的 `MINKO.md` / `AGENTS.md` / `CLAUDE.md`、`.minko/rules/*.md` 和 git 状态会自动进入上下文（单文件 16KB、总量 32KB 上限）。
+
+## MCP 工具
+
+在 `~/.minko/config.json` 里声明 MCP server：
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/work"]
+    }
+  }
+}
+```
+
+启动 `minko` 或 `minko serve` 时会自动连接（stdio + JSON-RPC）。工具名形如
+`mcp__filesystem__read_file`，和内置工具一样参与权限规则；默认需要确认（MCP 没有统一的
+只读标记），可用 `permissions.allow: ["mcp__filesystem__read_file"]` 放行。
+某个 server 启动失败只会打印错误，不影响内置工具和其他 server。
+
+## 子任务
+
+内置 `agent` 工具：模型可以启动一个独立上下文的只读子任务，只能使用
+`read_file` / `list_dir` / `search_files`，完成后把结论返回主对话。
+子任务不能写文件、不能执行命令，也不能再启动子任务。
+
+## 计划模式与待办
+
+- `enter_plan_mode` 进入只读计划模式：只能读文件、列目录、搜索和启动只读子任务；
+  写文件、执行命令、MCP 写工具都会被拒绝。计划完成后用 `exit_plan_mode` 提交，需要用户确认。
+- `todo_write` 维护多步骤清单（pending / in_progress / completed），随会话保存。
+- 终端里用 `/plan` 手动切换计划模式，`/todos` 查看当前清单。
+
+## RAG 检索
+
+内置 `retrieve_context` 工具，在本地给工作区建索引：
+
+- 默认 BM25 关键词检索：英文按单词、中文按二元词切分，支持文件名命中；
+- 配置 embeddings 后自动变成「关键词 + 语义」混合检索；
+- 自动跳过 `node_modules`、`.git`、`dist` 等目录，二进制文件、锁文件，以及 `.env` / `*.pem` 等敏感文件；
+- 默认最多索引 3000 个文件、单文件 256KB，索引缓存 30 秒；传 `refresh: true` 强制重建；
+- 返回 `file:line` 和片段；计划模式、子任务里都可以用。
+
+开启语义检索（OpenAI 兼容 embeddings）：
+
+```json
+{
+  "rag": {
+    "embeddings": {
+      "enabled": true,
+      "baseUrl": "https://api.openai.com/v1",
+      "model": "text-embedding-3-small",
+      "apiKey": "sk-xxxx",
+      "maxChunks": 1000
+    }
+  }
+}
+```
+
+也可以接远程 RAG 服务（HTTP）：
+
+```json
+{
+  "rag": {
+    "remote": {
+      "baseUrl": "http://127.0.0.1:8787",
+      "apiKey": "optional",
+      "topK": 6
+    }
+  }
+}
+```
+
+配置了远程服务时优先走远程；失败自动回退本地索引。远程接口约定：`POST /v1/query`
+body `{ "query": "...", "top_k": 6 }`，返回 `{ "results": [{ "path", "start_line",
+"end_line", "text", "score" }] }`（也接受 `hits` 和 `camelCase` 字段）。
+
+`baseUrl` / `apiKey` 省略时会复用当前 OpenAI 兼容服务商；`maxChunks` 控制最多给多少个块建向量。
+向量缓存在 `~/.minko/rag/`，内容没变就不会重复调用 embeddings；语义服务不可用时自动回退 BM25。
+
+## 长期记忆
+
+内置 `memory_write` / `memory_read` 工具：
+- 记忆存在 `~/.minko/memory/`，`MEMORY.md` 是索引，单条记忆是带 frontmatter 的 Markdown；
+- 模型可保存用户偏好、纠正、项目背景等跨会话信息，索引会自动注入上下文；
+- 记忆内容会被标注为「数据不是指令」；
+- `/fork` 会把当前会话（含计划/待办）复制成一个新分支。
+
+## 会话状态
+
+每个打开或正在运行的会话会定期写入 `sessions/<id>.status.json`：
+- `minko sessions` 显示 `正在跑` / `等确认` / `空闲` / `离线`；
+- 手机远控的 `GET /sessions` 返回每个会话的 `status` 和 `live` 字段；
+- 心跳 15 秒一次，超过 60 秒没有更新就视为离线。
+
+## 插件
+
+插件放在 `~/.minko/plugins/<name>/`，目录里需要 `plugin.json`：
+
+```json
+{
+  "name": "hello",
+  "version": "1.0.0",
+  "description": "示例插件",
+  "tools": [{
+    "name": "greet",
+    "description": "打招呼",
+    "readOnly": true,
+    "parameters": {
+      "type": "object",
+      "properties": { "name": { "type": "string" } },
+      "required": ["name"]
+    },
+    "command": "node tool.js",
+    "timeoutMs": 30000
+  }],
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "run_shell", "hooks": [{ "command": "node audit.js" }] }
+    ]
+  }
+}
+```
+
+- 工具命令从 stdin 收 JSON 参数，stdout 作为结果；cwd 是插件目录，环境变量含
+  `MINKO_PLUGIN` / `MINKO_PLUGIN_DIR` / `MINKO_TOOL`。
+- 工具名统一为 `plugin__<插件名>__<工具名>`。
+- `readOnly` 默认 `true`；设为 `false` 时走确认和 `workspace` 限制。
+- 插件 hooks 与 `config.hooks` 合并，命令默认在插件目录运行。
+- 坏插件只报错，不影响其他插件。
+
+管理命令：
+
+```bash
+minko plugin list
+minko plugin search [关键词]
+minko plugin install <名字|git 地址|本地目录>
+minko plugin uninstall <名字>
+minko plugin disable <名字>
+minko plugin enable <名字>
+```
+
+### 插件市场
+
+配置 `plugins.registryUrl` 指向 JSON 索引：
+
+```json
+{
+  "plugins": {
+    "registryUrl": "https://plugins.example/index.json"
+  }
+}
+```
+
+索引格式：
+
+```json
+{
+  "plugins": [
+    { "name": "hello", "version": "1.0.0", "description": "...", "git": "https://github.com/you/hello" }
+  ]
+}
+```
+
+`plugin search` 按名称/描述过滤；`plugin install <名字>` 从索引找到 git 地址，
+`git clone --depth 1` 后复制到 `~/.minko/plugins/<name>`。需要本机安装 git。
+
+## LSP 代码导航
+
+内置 `lsp` 工具，支持 `definition` / `references` / `hover` / `symbols`（文件符号）。
+语言服务器按需启动并复用，退出时关闭。
+
+默认命令：
+
+| 语言 | 命令 |
+| --- | --- |
+| TypeScript / JavaScript | `typescript-language-server --stdio` |
+| Python | `pyright-langserver --stdio` |
+| Rust | `rust-analyzer` |
+| Go | `gopls` |
+
+可在 `~/.minko/config.json` 覆盖：
+
+```json
+{
+  "lsp": {
+    "servers": {
+      "typescript": { "command": "typescript-language-server", "args": ["--stdio"] },
+      "python": { "command": "pyright-langserver", "args": ["--stdio"] }
+    }
+  }
+}
+```
+
+没装对应语言服务器时会返回安装提示，不影响其他工具。
+
+## 后台 worker 与团队
+
+内置一组后台编排工具：
+
+- `worker_create` 启动一个后台 worker，立即返回 id；`allow_write: true` 时允许
+  `write_file` / `edit_file`，每次写入都需要确认，写入 worker 串行运行；
+- `worker_wait` 等结果，`worker_list` / `worker_get` 查看状态，`worker_stop` 停止；
+- `team_create` 一次创建最多 8 个 worker 并行调查，`team_wait` 收集全部结果；
+- 只读 worker 只能读文件/列目录/搜索/检索，不能写文件或执行命令；写入 worker 也不能执行 shell；
+- 默认最多 2 个 worker 同时跑，单个 5 分钟超时；输出上限 8KB。
+
+worker 在进程内运行：交互模式关闭时全部停止；一次性模式在本轮结束时停止未完成的任务；
+后台服务（`minko serve`）里跨会话共享。手机远控中的写入 worker 只有在 `power: full` 时才会被批准。
+
+worker 记录和完整对话会持久化到 `~/.minko/workers/`：
+- 元数据 `<id>.json`，对话 `<id>.messages.jsonl`；
+- 进程重启后仍可查看历史；上次进程里还在 running/queued 的 worker 会被标记为 stopped；
+- 手机接口：
+  - `GET /workers` 列出 worker；
+  - `GET /workers/<id>` 返回元数据和对话；
+  - `POST /workers/<id>/stop` 停止当前进程里仍在运行的 worker；
+  - `GET /sessions` 额外返回 `workers: { total, active }`。
+
+## Git worktree lane
+
+在 git 仓库里可以给写入 worker 一个独立分支和目录：
+
+- `lane_create`：创建 `minko/lane-<id>` 分支和 worktree，启动写入 worker；
+- `lane_wait` / `lane_status`：等待并查看状态；
+- `lane_diff`：查看 git 状态、差异统计和 diff；
+- `lane_close`：停止 worker 并删除 worktree（`keep_branch: true` 保留分支供手动合并）；
+- `lane_merge`：自动提交 lane 里的改动并合并到当前分支：
+  - `strategy: merge | squash | ff`，默认 `merge --no-ff`；
+  - 主工作区有未提交改动时拒绝，除非 `allow_dirty: true`；
+  - 冲突会自动 `merge --abort` 并保留 lane；
+  - 成功后清理 worktree、删除分支并释放锁；合并操作需要确认。
+
+lane 不会改动主工作区；计划模式下不能创建 lane 或合并。
+
+## 任务板与定时任务
+
+- `task_create` / `task_start` / `task_list` / `task_get` / `task_output` / `task_stop` / `task_update`：
+  持久化任务板，任务启动后对应一个后台 worker；
+- 任务记录在 `~/.minko/tasks/`，进程重启后仍可查看，失去 worker 的 running 任务会标记为 failed；
+- `cron_create` / `cron_list` / `cron_run` / `cron_delete`：按分钟间隔定时启动只读 worker；
+- 定时任务在 TUI 和 `minko serve` 常驻期间自动检查；一次性模式用 `cron_run` 手动触发；
+- 同一个 cron 上一次 worker 还在运行时不会重复启动；
+- 定时任务记录在 `~/.minko/cron/`。
+
+## 分支锁与分支状态
+
+- `branch_lock` / `branch_unlock` / `branch_locks`：跨进程的分支锁，存在 `~/.minko/locks/`；
+  另一个 holder 持锁时会被拒绝，超过 30 分钟的锁可被替换；
+- `branch_status`：当前分支、上游、领先/落后提交数、分支锁状态；
+- git worktree lane 创建时会自动加锁，关闭时释放。
+
+## 手机审批
+
+流式请求（`?stream=1`，默认）遇到需要确认的工具时，SSE 会先发：
+
+```text
+event: approval_request
+data: { "id": "...", "tool": "run_shell", "title": "执行命令", "detail": "...", "danger": "exec" }
+```
+
+手机调用下面的接口批准或拒绝，之后会收到 `approval_resolved` 并继续执行：
+
+```http
+POST /sessions/<id>/approve
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "id": "<approval id>", "allow": true }
+```
+
+120 秒未处理会自动拒绝；SSE 连接断开也会拒绝。非流式请求（`?stream=0`）无法交互，
+需要确认的操作默认拒绝。等待审批期间，`GET /sessions` 的状态是 `waiting_approval`。
+
+## Web 工具
+
+- `web_fetch`：抓取 http/https 页面并转成可读文本；HTML 会去掉脚本和样式，响应上限 2MB、超时 20 秒。
+- `web_search`：请求 HTML 搜索页，返回标题、链接和摘要；默认 DuckDuckGo，可用
+  `web.searchUrl` 换成自建或兼容的搜索页。
+
+```json
+{ "web": { "searchUrl": "https://html.duckduckgo.com/html/" } }
+```
+
+网页内容会被当作数据而不是指令。
+
+## OAuth 登录
+
+支持通用 OAuth 2.0 设备码流程（RFC 8628）。在 `~/.minko/config.json` 配置：
+
+```json
+{
+  "oauth": {
+    "deviceAuthorizationUrl": "https://id.example/device",
+    "tokenUrl": "https://id.example/token",
+    "clientId": "your-client-id",
+    "scopes": ["openid", "profile"],
+    "provider": "gateway",
+    "name": "work"
+  }
+}
+```
+
+运行 `minko login`，按提示打开 URL 并输入代码。成功后：
+
+- 令牌保存在 `~/.minko/oauth.json`（`0600`）；
+- `oauth.provider`（或当前激活服务商）的 `apiKey` 更新为 access token，并设置 `auth: "bearer"`；
+- Anthropic 兼容网关会改用 `Authorization: Bearer`，而不是 `x-api-key`。
+
+## Docker 沙箱
+
+开启后 `run_shell` 在容器里执行，当前工作目录挂载到 `/workspace`：
+
+```json
+{
+  "sandbox": {
+    "mode": "docker",
+    "image": "node:22",
+    "network": false,
+    "allowFallback": false,
+    "extraArgs": ["--memory=1g"]
+  }
+}
+```
+
+- 默认 `--network none`，容器内无法联网；
+- Docker 不可用时默认拒绝执行（fail closed）；`allowFallback: true` 才回退普通 shell；
+- `minko sandbox` 查看状态；`minko doctor` 会检查 Docker 可用性。
+
+## 审批令牌
+
+- `approval_create` 创建有限次数、会过期的审批令牌；令牌按工具名 + 命令/路径模式匹配；
+- 创建令牌本身需要用户确认；deny 规则和 readonly/workspace 限制仍然优先；
+- 匹配到有效令牌时，工具调用直接通过并扣减次数，不再弹确认；
+- `approval_list` / `approval_revoke` 查看和撤销；
+- 令牌存在 `~/.minko/approvals/`；
+- 手机接口：`GET /approvals`、`POST /approvals`、`DELETE /approvals/<id>`。
+
+## RAG 服务
+
+`minko rag --port 8787 [--host 127.0.0.1]` 启动本地 HTTP 服务：
+
+- `GET /health`
+- `GET /v1/stats`
+- `POST /v1/query` `{ "query": "...", "top_k": 6, "root": "可选子目录" }`
+- `POST /v1/rebuild`
+- `GET /` 一个简单的查询页面
+
+返回格式与 `rag.remote` 客户端兼容（`results[].path/start_line/end_line/text/score`）。
+`root` 必须位于服务启动目录内；默认只监听本机。
+
+## MCP server
+
+`minko mcp-server` 把 Minko 的只读工具通过 stdio MCP 暴露给其他 agent，使用
+newline-delimited JSON-RPC：
+
+- `initialize` / `notifications/initialized`
+- `tools/list` / `tools/call`
+- `shutdown` / `exit`
+
+默认只暴露只读工具：`read_file`、`list_dir`、`search_files`、`retrieve_context`、
+`lsp`、`web_fetch`、`web_search`；不暴露 `write_file`、`run_shell`。
+MCP client 可配置 `command: "minko", args: ["mcp-server"]`。
+
+MCP resources：
+
+- 客户端会为每个 server 生成 `mcp__<server>__list_resources` 和
+  `mcp__<server>__read_resource`；
+- 同时支持 prompts 与 resource templates：
+  `mcp__<server>__list_prompts`、`mcp__<server>__get_prompt`、
+  `mcp__<server>__list_resource_templates`；
+- `minko mcp-server` 通过 `resources/list` 暴露工作区里的 `MINKO.md`、`AGENTS.md`、
+  `CLAUDE.md`、`README.md`、`package.json` 和项目技能文件，`resources/read` 只能读取
+  工作目录内的文件；
+- `prompts/list` 把项目技能暴露为 prompts，`prompts/get` 返回技能正文；
+  `resources/templates/list` 提供 `file://{path}` 模板。
+
+### 远程 MCP + OAuth
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "url": "https://mcp.example/rpc",
+      "token": "可选，已有的 Bearer token",
+      "oauth": {
+        "deviceAuthorizationUrl": "https://id.example/device",
+        "tokenUrl": "https://id.example/token",
+        "clientId": "client-id",
+        "scopes": ["mcp.read"]
+      }
+    }
+  }
+}
+```
+
+- 配置 `url` 时使用 Streamable HTTP 客户端，支持 JSON 和 SSE 响应、`Mcp-Session-Id` 和 Bearer 鉴权；
+- `minko mcp-login remote` 走 OAuth 设备码流程，把 token 写回配置，并保存为
+  `~/.minko/oauth.json` 里的 `mcp:remote`；
+- 目前没有自动 refresh，token 过期后重新运行 `mcp-login`。
+
+## SDK
+
+`minko sdk` 通过 stdin/stdout 收发 NDJSON JSON-RPC 2.0，方法：
+
+- `initialize`
+- `session.create` `{ cwd?, model? }`
+- `session.list` / `session.get` `{ session }` / `session.delete` `{ session }`
+- `chat` `{ session, text, approval?: "ask" | "auto" }`
+- `shutdown` / `exit`
+
+`chat` 执行期间会输出 `minko.event` 通知（text / reasoning / tool_start / tool_end /
+notice / done），并在结束时返回文本、usage 和会话信息。默认 `ask` 会拒绝需要确认的操作；
+需要无人值守时传 `approval: "auto"`。
+
+## 技能包（Skills）
+
+Minko 读取 Agent Skills 规范（`SKILL.md` + YAML frontmatter）的技能包，并兼容 Claude Code 与 Codex 的目录约定：
+
+| 来源 | 位置 | 优先级 |
+| --- | --- | --- |
+| 内置 | 随 Minko 打包（`assets/skills`） | 最低，可被覆盖 |
+| Claude Code 用户级 | `~/.claude/skills/` | |
+| Codex 用户级 | `~/.agents/skills/`（也兼容 `~/.codex/skills/`） | |
+| Minko 用户级 | `~/.minko/skills/` | |
+| 项目级 | 从 git 根目录到 cwd 的 `.claude/skills`、`.agents/skills`、`.minko/skills` | 最高，同目录下 `.minko` 优先 |
+
+同名技能按上表从低到高覆盖；离 cwd 更近的项目技能优先。
+
+```md
+---
+name: review
+description: 审查代码；在用户要求评审改动时使用。
+license: MIT
+allowed-tools: Read Grep Bash
+---
+检查 {{args}} 的改动，列出风险。
+```
+
+- 解析 `name` / `description` / `license` / `compatibility` / `allowed-tools` / `metadata`，支持 `|`、`>` 多行描述和引号；
+- 目录内的 `references/`、`scripts/`、`assets/` 会在加载时列为参考文件，可用 `read_file` 读取或 `run_shell` 执行；
+- `skill_list` 列出全部技能及来源，`skill` 加载完整说明；
+- `{{args}}` 和 `$ARGUMENTS` 会被调用参数替换；
+- 内置技能：`code-review`、`systematic-debugging`、`test-driven-development`、`verification-before-completion`、`five-whys`、`buddhist-method`、`cyclomatic-complexity`、`vibe-sec`、`code-humanizer`、`brainstorming`、`writing-plans`（来源与许可见 `assets/skills/README.md`）；
+- 会话里可以用 `/skills` 查看；技能内容会标注为“任务指导”，不能覆盖系统安全规则。
+
 ## 数据位置
 
 ```
 ~/.minko/
   config.json          模型与服务地址（含 API Key）
   sessions/*.jsonl     会话记录
+  sessions/*.status.json 会话运行状态
+  memory/              长期记忆
+  skills/              用户技能包
+  plugins/             插件
+  rag/*.json           embeddings 向量缓存
+  oauth.json           OAuth 令牌
+  workers/             worker 元数据与对话
+  tasks/               任务板
+  cron/                定时任务
+  locks/               分支锁
+  approvals/           审批令牌
+  lanes/               git worktree lane 状态
 ```
 
-删除会话直接删对应文件；`minko sessions` 可查 id。
+会话按消息增量落盘：每个 assistant / tool 消息产生后立即保存，进程崩溃或 `Ctrl+C`
+之后仍能续接；加载旧会话时会自动补齐未返回结果的工具调用。删除会话直接删对应文件；
+`minko sessions` 可查 id。
 
 ## 手机远控（规划中）
 
@@ -80,7 +655,7 @@ minko --auto "..."          # 不再逐条确认（危险）
 ## 开发
 
 ```bash
-npm test        # node:test，49 条
+npm test        # node:test，310 条
 npm run typecheck
 node bin/minko.js --help
 ```

package/assets/mascot-preview.txt

@@ -0,0 +1,46 @@
+palette: #171b34 x35 #7ff7ba x7 #9a88dc x16 #b9aaf0 x14 #cfc4e7 x33 #fef6e6 x42
+frame 0
+   ▄█▀▀         
+ ▄███▄▄   ▄     
+ ████████████   
+ ▀███████████▄  
+  ███████████▀  
+  ▀████████████ 
+  ██████████▀▀  
+  ▀ ▀██▀███▀    
+frame 1
+   ▄█▀▀         
+ ▄███▄▄   ▄     
+ ████████████   
+ ▀███████████▄  
+  ███████████▀  
+  ▀████████████ 
+  ██████████▀▀  
+  ▀ ▀██▀███▀    
+frame 2
+   ▄█▀▀         
+ ▄███▄▄   ▄     
+ ████████████   
+ ▀███████████▄  
+  ███████████▀  
+  ▀████████████ 
+  ██████████▀▀  
+  ▀ ▀██▀███▀    
+frame 3
+    ▄▄▄         
+  ▄██           
+ ██████▄▄▄█▄▄   
+ ████████████   
+  ████████████  
+  ███████████▄▄ 
+  ▄███████████▀ 
+  █▀████████    
+frame 4
+   ▄█▀▀         
+ ▄███▄▄   ▄     
+ ████████████   
+ ▀███████████▄  
+  ███████████▀  
+  ▀████████████ 
+  ██████████▀▀  
+  ▀ ▀██▀███▀