@jpssff/vanor 0.1.0

package/docs/TECH_DESIGN.md

@@ -0,0 +1,544 @@
+# Vanor 技术设计
+
+> 本文是 [README](../README.md) 的实现级展开：README 讲「是什么」，本文讲「怎么实现」。
+> 标 `[v2]` 者为后续版本，MVP 不实现但预留接口。
+
+## 目录
+
+1. [设计目标与约束](#1-设计目标与约束)
+2. [架构总览](#2-架构总览)
+3. [统一消息协议 Message](#3-统一消息协议-message)
+4. [AgentLoop](#4-agentloop)
+5. [LLM 层](#5-llm-层)
+6. [工具系统](#6-工具系统)
+7. [技能 Skills](#7-技能-skills)
+8. [记忆系统](#8-记忆系统)
+9. [会话 Session](#9-会话-session)
+10. [配置 config.json](#10-配置-configjson)
+11. [多语言 i18n](#11-多语言-i18n)
+12. [日志与事件](#12-日志与事件)
+13. [安全模型](#13-安全模型)
+14. [进程模型](#14-进程模型)
+15. [自我更新 self-evolve `[v2]`](#15-自我更新-self-evolve-v2)
+16. [插件机制 `[v2]`](#16-插件机制-v2)
+17. [模块与文件职责](#17-模块与文件职责)
+18. [里程碑](#18-里程碑)
+19. [开放问题](#19-开放问题)
+
+---
+
+## 1. 设计目标与约束
+
+- **通用智能体**：大模型驱动，自主推理、规划、执行多步任务。
+- **零依赖**：仅用 Node 原生模块。运行环境 **Node ≥ 18**（依赖原生 `fetch`、`node:test`、`AbortController`、`readline/promises` 等）。
+- **隐私优先**：默认本地文件存储，不外发数据（LLM 调用除外）。
+- **可观测**：关键动作全部落 JSONL，事件名全局可枚举。
+- **可自我改写** `[v2]`：见 §15。
+
+**非目标（MVP）**：分布式 / 多租户、向量数据库、GUI、内置鉴权服务。
+
+---
+
+## 2. 架构总览
+
+| 层 | 模块 | 职责 |
+|----|------|------|
+| Transport | `transport/` | 外部 I/O ↔ 统一 `Message`；CLI 内置，其他通道由插件实现 |
+| Core (Harness) | `core/harness.js` | 编排：会话、phase、配置快照、compaction 触发、事件分发 |
+| Loop | `core/loop.js` | 单轮 LLM ↔ 工具迭代 |
+| LLM | `llm/` | provider 适配、流式、failover |
+| Tools | `tools/` | 工具注册、参数校验、执行 |
+| Skills | `skills/` | 技能加载与 prompt 注入 |
+| Memory | `memory/` | 短期 / 长期 / 工作记忆 |
+| 横切 | `security/` `logger.js` `events.js` `config.js` `i18n/` | 审批、日志、事件枚举、配置、多语言 |
+
+**依赖方向**（单向，无循环）：
+
+```text
+Transport → Core → Loop → { LLM, Tools, Memory }
+                    Skills / Security 被 Core、Loop 调用
+        Config / Logger / Events / i18n 为横切，被各层只读引用
+```
+
+### 2.1 Phase 状态机
+
+```text
+        ┌─────────────────────────────────────────┐
+        ▼                                          │
+     [idle] ──prompt──▶ [turn] ──tool_calls──▶ [tool_exec]
+        ▲                 │  ▲                      │
+        │                 │  └──────results─────────┘
+        │           over_threshold
+        │                 ▼
+        └──── done ── [compaction]
+                              （self_update 仅 [v2]，见 §15）
+```
+
+- **结构性操作**（切换 base-user、reset 会话）仅允许在 `idle`。
+- 运行中修改 `config.json` 后，下一轮前自动检查 mtime 并热重载；也可用 `/reload` 手动重载。重载只更新 **core config**、i18n 与运行时对象，下一轮构造 system prompt / LLM 请求时生效，不影响进行中的 turn。
+
+### 2.2 turn snapshot vs core config
+
+借鉴 pi 的分离：`core config` 是最新运行时配置（可随时改）；`turn snapshot` 是某一轮开始时冻结的具体配置（model、tools、system prompt、记忆快照）。一轮内所有逻辑用同一 snapshot，保证一致性与 prefix cache 命中。
+
+---
+
+## 3. 统一消息协议 Message
+
+所有通道、Core、Loop 全程使用 `Message`，仅在 LLM 边界转换为各 provider 格式。
+
+```ts
+type Role = "system" | "user" | "assistant" | "tool";
+
+interface Message {
+  id: string;                    // msg_<ulid>
+  role: Role;
+  content: string | ContentPart[]; // 文本或多模态（图片等）
+  toolCalls?: ToolCall[];        // 仅 assistant：本轮要调用的工具
+  toolCallId?: string;           // 仅 tool：对应的调用 id
+  name?: string;                 // 仅 tool：工具名
+  channel?: string;              // cli | telegram | web ...
+  meta?: Record<string, unknown>; // timestamp、model、usage 等
+}
+
+interface ToolCall {
+  id: string;                    // call_<id>
+  name: string;
+  arguments: unknown;            // 已解析的 JSON 参数
+}
+
+type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image"; url: string };  // [v2] 多模态
+```
+
+**角色交替规则**（provider 强约束，Core 在持久化前校验）：
+
+- 系统消息后：`user → assistant → user → ...`
+- 工具调用中：`assistant(toolCalls) → tool → tool → ... → assistant`
+- 不得连续两条 `assistant` 或两条 `user`；仅 `tool` 可连续（并行结果）。
+
+---
+
+## 4. AgentLoop
+
+```ts
+async function runTurn(ctx: Context, snap: TurnSnapshot, signal: AbortSignal) {
+  for (let i = 0; i < snap.maxIterations; i++) {
+    if (signal.aborted) return emit("agent.turn.aborted");
+
+    const llmMessages = buildMessages(ctx, snap); // 系统prompt + 记忆快照 + 历史
+    const assistant = await streamLLM(llmMessages, snap, signal); // 内含 retry/failover
+    ctx.push(assistant);
+
+    if (!assistant.toolCalls?.length) {           // 纯文本 → 结束
+      await maybeFlushMemory(ctx, snap);
+      return emit("agent.turn.end", assistant);
+    }
+
+    // 执行工具：默认并行；标记 exclusive 的工具串行
+    const results = await runTools(assistant.toolCalls, snap, signal);
+    ctx.push(...results);                         // role: "tool"
+
+    if (overThreshold(ctx, snap)) await compact(ctx, snap); // → compaction phase
+  }
+  return emit("agent.turn.max_iterations");
+}
+```
+
+- **终止条件**：assistant 无 toolCalls / 达 `maxIterations` / `abort` / 致命错误。
+- **中断**：CLI `Ctrl+C` → `AbortController.abort()`；进行中的 LLM 流与工具收到 signal 后尽快收敛。
+- **错误处理**：
+  - LLM 失败 → 按错误分类重试（指数退避），耗尽后走 failover 模型（§5）。
+  - 工具失败 → 包装为 `ToolResult{ isError:true }` 回传给模型，由模型决定后续，不中断 loop。
+
+---
+
+## 5. LLM 层
+
+### 统一接口
+
+```ts
+interface LLMRequest {
+  model: string;                 // "<provider>/<model-id>"
+  messages: Message[];
+  tools?: ToolSchema[];
+  thinking?: "off" | "low" | "high";
+  stream: true;
+}
+
+interface LLMProvider {
+  name: string;                  // openai | anthropic
+  complete(req: LLMRequest, signal: AbortSignal): AsyncIterable<LLMChunk>;
+}
+
+type LLMChunk =
+  | { type: "text"; delta: string }
+  | { type: "tool_call"; call: ToolCall }
+  | { type: "usage"; usage: Usage }
+  | { type: "done"; finishReason: string };
+```
+
+### Provider 适配
+
+| Provider | 协议 | 适用 |
+|----------|------|------|
+| `openai` | Chat Completions | OpenAI、兼容端点、多数国产/开源厂商 |
+| `anthropic` | Messages | Claude 原生 |
+| `openai-responses` `[v2]` | Responses | Codex / Responses API |
+
+- **流式**：原生 `fetch` + `response.body`（`ReadableStream`）逐块解析 SSE，零依赖。
+- **工具调用格式**：内部统一为 `ToolCall`，各 provider 在适配层双向转换。
+- **failover**：`llm.fallback` 列出备用模型；错误分为「可重试（限流/超时/5xx）」与「致命（鉴权/参数）」，可重试耗尽后切下一模型。
+- **事件**：`llm.request` `llm.response` `llm.retry` `llm.error`。
+
+---
+
+## 6. 工具系统
+
+### 定义
+
+```ts
+interface ToolSchema {
+  name: string;
+  description: string;           // 供模型理解何时调用
+  parameters: JSONSchema;        // 供模型生成参数 + 运行时校验
+}
+
+interface Tool extends ToolSchema {
+  danger: "safe" | "confirm" | "deny-default"; // 审批级别，见 §13
+  exclusive?: boolean;           // 是否禁止与其他工具并行
+  handler(args: unknown, ctx: ToolContext): Promise<ToolResult>;
+}
+
+interface ToolResult { content: string; isError?: boolean; }
+```
+
+### 内置工具（MVP）
+
+| 工具 | 参数 | danger | 说明 |
+|------|------|--------|------|
+| `read_file` | `path, offset?, limit?` | safe | 读文件，限 workspace |
+| `write_file` | `path, content` | confirm | 写 / 覆盖文件 |
+| `edit_file` | `path, old_string, new_string` | confirm | 唯一匹配后替换 |
+| `list_dir` | `path` | safe | 列目录 |
+| `exec` | `command, cwd?, timeout?` | confirm | 执行命令，受 allowlist/denylist |
+
+`[v2]`：`spawn`（常驻子进程）、`search`（grep）、`fetch_url`、`delegate`（子 Agent）。
+
+### 执行约束
+
+- **参数校验**：用 `parameters` 的 JSON Schema 校验，非法直接回 `isError`。
+- **工作区边界**：所有文件工具限制在 `security.workspaceRoot`（默认启动目录）内；越界路径需审批或被拒（`allowOutsideWorkspace`）。
+- **命令执行**：在 workspace cwd 运行，套用审批与 allow/deny，超时杀进程，输出超限截断；清理敏感环境变量。
+- **并行**：同一 assistant 的多个 toolCalls 默认 `Promise.all` 并行，`exclusive` 工具串行。
+- **事件**：`tool.call` `tool.result` `tool.error` `tool.denied`。
+
+---
+
+## 7. 技能 Skills
+
+技能是**过程性记忆**：把「做某类任务的步骤」沉淀为可复用单元。
+
+### 格式
+
+```text
+<skill-dir>/
+├── SKILL.md      # frontmatter: name, description；正文为操作说明
+└── ...           # 可选脚本 / 模板，由工具（exec/read_file）调用
+```
+
+### 加载
+
+| 优先级 | 路径 | 范围 |
+|--------|------|------|
+| 最高 | `~/.vanor/skills/` | Vanor 专属 |
+| 高 | `<workspace>/.skills/`、`<workspace>/skills/` | 当前项目技能 |
+| 中 | `~/.cursor/skills-cursor/`、`~/.claude/skills/`、`~/.agents/skills/`、`~/.codex/skills/` | 本机已有 Agent 技能 |
+| 低 | `~/.agent/skills/`、`~/.skills/` | 兼容旧路径 / 全局 |
+
+- 兼容 [agentskills.io](https://agentskills.io) 的 `SKILL.md`；同名按优先级去重。
+- **调用方式**：每次请求前刷新技能目录，并将各技能的 `name + description` 注入 system prompt（低成本）；模型判断需要时，再用 `skills.read` / `read_file` 读取 `SKILL.md` 全文与脚本，按说明执行。
+- **管理工具**：`skills.list/read/write/edit/remove`；读取可作用于所有已加载技能，写入/修改/删除仅作用于 `~/.vanor/skills/`，避免误改共享技能。
+- **事件**：`skill.load` `skill.invoke` `skill.save`。
+
+---
+
+## 8. 记忆系统
+
+### 短期（会话）
+
+即 `sessions/<id>.jsonl` 本身，不另存。超过 `compactThreshold`（默认上下文 75%）触发 compaction：
+
+```text
+保留：最近 N 轮完整消息 + 被读/写文件清单 + pinned 内容
+压缩：更早的历史 → 一条 summary（compaction 条目，见 §9）
+```
+
+### 长期（有界 Markdown）
+
+| 文件 | 用途 | 上限 |
+|------|------|------|
+| `MEMORY.md` | 环境事实、约定、经验 | ~2200 字符 |
+| `USER.md` | 用户偏好、沟通风格 | ~1375 字符 |
+
+- 条目以 `§` 分隔；超限时模型自行整合/替换。
+- **冻结快照**：会话开始时注入系统 prompt，会话中途变更立即落盘但下一会话才进 prompt（保 prefix cache）。
+- `memory` 工具：`add` / `replace` / `remove`（子串唯一匹配），无 `read`（已在 prompt 中）。
+- **检索**：MVP 用关键词倒排（Node 实现）补充召回；`[v2]` 可选向量（sqlite-vec / 本地 embedding）。
+
+### 工作记忆
+
+`memory/working/`：任务内的 plan、中间结果。任务结束清理，或选择性 `promote` 到长期。
+
+**事件**：`memory.store` `memory.retrieve` `memory.compress` `memory.promote`。
+
+---
+
+## 9. 会话 Session
+
+- **sessionId**：`<yyyymmddHHMMSS>-<rand>`，每会话一文件 `sessions/<id>.jsonl`。
+- **快速恢复索引**：退出 / 会话 start / resume 时写入 `~/.vanor/state.json`，维护 `workspaces[workspaceRoot].latestSessionId`；启动恢复优先按当前工作区读取对应单个 JSONL 文件，失效时才回退扫描 `sessions/` 全目录。保留顶层 `latestSessionId` 兼容旧状态。
+- **存储条目**：
+
+```ts
+type SessionEntry =
+  | { type: "message"; ts: string; message: Message }
+  | { type: "compaction"; ts: string; summary: string;
+      readFiles: string[]; modifiedFiles: string[] }
+  | { type: "meta"; ts: string; key: string; value: unknown }; // 模型切换、leaf 等
+```
+
+- **路由**：MVP 单一 `main` 会话；`[v2]` IM 多用户按 `per-channel-peer` 隔离。
+- **生命周期**：MVP 手动 `/new`、`/reset`；`[v2]` daily / idle 自动重置。
+- **slash 命令**：`/new` `/reset` `/messages` `/compact` `/retry` `/model` `/language` `/usage` `/skills` `/reload` `/auto-run`。
+- **事件**：`session.start` `session.reset` `session.compact`。
+
+---
+
+## 10. 配置 config.json
+
+```jsonc
+{
+  "llm": {
+    "defaultModel": "wanyou/deepseek/deepseek-v4-pro",
+    "providers": {
+      "wanyou":    { "type": "openai", "apiKey": "env:VANOR_API_KEY", "baseURL": "https://wanyouzhisuan.com/api/v1", "models": ["deepseek/deepseek-v4-pro", "deepseek/deepseek-v4-flash"] },
+      "anthropic": { "apiKey": "env:ANTHROPIC_API_KEY" }
+    },
+    "fallback": ["wanyou/deepseek/deepseek-v4-flash"]   // 主模型失败后依次尝试
+  },
+  "agent":  { "maxIterations": 25, "thinking": "off", "contextWindow": 256000 },
+  "memory": { "memoryMaxChars": 2200, "userMaxChars": 1375, "compactThreshold": 0.75 },
+  "security": {
+    "approval": "ask",                 // ask | auto | deny
+    "allowlist": ["git *", "ls *", "cat *"],
+    "denylist":  ["rm -rf *", "sudo *"],
+    "workspaceRoot": ".",
+    "allowOutsideWorkspace": false
+  },
+  "session": { "restore": "last", "reset": { "idleMinutes": 0, "daily": false }, "dmScope": "main" },
+  "logging": { "level": "info", "llmTrace": false, "llmTraceRedact": true },
+  "ui": { "color": true, "stream": true, "language": "auto" }
+}
+```
+
+- **加载顺序**：内置默认 → `~/.vanor/config.json` → 环境变量覆盖。`config.js` 负责校验与归一。
+- **密钥**：值以 `env:` 前缀表示从环境变量读取；apiKey 永不写入日志。
+- **模型列表**：provider 可选 `models` 数组，供 `/model <关键词>` 搜索与选择；未配置时使用当前模型、默认模型和 fallback 作为候选。
+- **会话恢复**：`session.restore = "last" | "none"`；默认按当前工作区恢复最近会话。
+- **LLM Trace**：`logging.llmTrace` 默认关闭；开启后记录 LLM 请求 / 响应详情，`llmTraceRedact` 默认脱敏敏感 header。
+- **语言**：`ui.language` 支持 `auto | en | zh-CN`。`auto` 按 `VANOR_LANG`、`LC_ALL`、`LC_MESSAGES`、`LANGUAGE`、`LANG`、`Intl` 顺序检测，无法确认则英文；CLI 内 `/language [auto|en|zh-CN]` 可即时切换并只写回 `ui.language`。
+
+---
+
+## 11. 多语言 i18n
+
+```text
+base/i18n/
+├── index.js              # detectLanguage / createI18n / t(key, vars)
+└── locales/
+    ├── en.js
+    └── zh-CN.js
+```
+
+- 文案使用嵌套 key 管理，如 `cli.help.text`、`prompt.runtimeTitle`。
+- `t(key, vars)` 支持 `{name}` 插值；缺失翻译回退英文，英文也缺失时返回 key。
+- 语言检测优先级：显式 `config.ui.language`（非 `auto`）→ 环境变量 → `Intl.DateTimeFormat().resolvedOptions().locale` → `en`。
+- Harness 持有当前 i18n 状态；配置热重载或 `/language` 后重建 i18n，后续 CLI 输出与 system prompt 立即使用新语言。
+- `/language` 写回配置时使用 raw config，只更新 `ui.language`，避免把 `env:` 密钥解析值写回明文。
+- system prompt 会注入当前 UI 语言，并要求模型默认使用该语言回复；用户显式要求其它语言时，以用户要求为准。
+- CLI 的 `helpText(t)`、确认提示、模型选择、`/messages` 表头、`/skills` 汇总、`/reload`、`/auto-run` 等用户文案均通过 i18n key 生成。
+- 工具链的模型可见 / 用户可见文案也接入 i18n：内置工具 schema 描述、工具执行结果、审批确认描述、参数校验错误、workspace 路径错误、skills 工具返回值。
+
+---
+
+## 12. 日志与事件
+
+- **行格式**：`{ "ts": ISO8601, "level": "debug|info|warn|error", "event": "<domain>.<action>", "detail": {...} }`，每行一条，写入 `logs/`。
+- **命名规范**：`<domain>.<action>`。`events.js` 为唯一定义源（枚举对象），杜绝散落字符串。
+
+| domain | 关键事件 | 级别 |
+|--------|----------|------|
+| `agent` | `turn.start` `turn.end` `turn.aborted` `turn.max_iterations` | info |
+| `llm` | `request` `response` `retry` `error` | info/warn |
+| `tool` | `call` `result` `error` `denied` | info/warn |
+| `memory` | `store` `retrieve` `compress` `promote` | info |
+| `session` | `start` `resume` `reset` `compact` | info |
+| `skill` | `load` `invoke` `save` | info |
+| `security` | `approve` `deny` | info/warn |
+| `config` | `load` `change` | info |
+| `process` `[v2]` | `spawn` `exit` `daemon.start` `daemon.stop` | info |
+| `self_update` `[v2]` | `diff` `test` `rollback` | info/warn |
+| `error` | `*` | error |
+
+---
+
+## 13. 安全模型
+
+**威胁模型**：MVP 单用户本地，主要防误操作；`[v2]` IM 暴露后，入站消息视为不可信。
+
+- **命令审批**：`approval = ask`（默认逐次确认）| `auto`（仅 allowlist 放行）| `deny`。`danger: confirm` 的工具受此约束。
+- **allowlist / denylist**：glob/前缀匹配；denylist 优先级最高。
+- **文件边界**：`workspaceRoot` 内自由读写，越界需审批（`allowOutsideWorkspace` 控制）。
+- `[v2]` **DM pairing**：未知发送者先发配对码，批准前不处理其消息。
+- `[v2]` **隔离**：建议对非 main 会话启用子进程 / 容器沙箱。
+- **`vanor doctor`**：检查弱审批配置、公开暴露、明文密钥、越权 workspace 等。
+- **事件**：`security.approve` `security.deny`。
+
+---
+
+## 14. 进程模型
+
+### MVP（前台 CLI）
+
+- 单个前台进程承载 TUI + Core + Loop。
+- **重活子进程化**：`exec` 等命令、自测等用 `child_process.fork/spawn`，崩溃隔离、便于中断。
+- **IPC**：子进程经 stdio 传 JSON 消息（请求 / 结果 / 进度）。
+
+### `[v2]` 常驻 daemon
+
+- 常驻进程负责：定时任务（`tasks/`）、IM 网关常驻监听。
+- `run/daemon.pid`、`run/daemon.sock`（daemon ↔ 子进程 IPC）、`run/state.json`。
+- 管理：`vanor daemon start|stop|status`。
+- **热重启**：daemon 收到「切换 base-user」请求 → 先以 `--canary` 子进程验证（§15）→ 通过后平滑切换处理进程；MVP 无 daemon，直接重启进程即可。
+
+---
+
+## 15. 自我更新 self-evolve `[v2]`
+
+`evolve.js` 负责 Agent 对自身代码的改写、校验、切换、回退。
+
+- **隔离**：禁改包内 `base/`；首次改写时 `base/` → `~/.vanor/base-user/`，记派生版本于 `base-user/.base-version`。
+- **改写边界**：默认仅 `base-user/` 内非核心模块、`~/.vanor/plugins/`、`~/.vanor/skills/`；`core/`、`tools/` 等核心需显式解锁。
+- **四级自测**（任一失败即判无效，保留 `base/`，失败副本归 `backups/`，记 `self_update.test`）：
+  1. 静态：`node --check`、模块可加载、无循环依赖
+  2. 单元：逐模块跑契约测试（`base/test/`，mock LLM、零 token）
+  3. 集成冒烟：mock LLM 跑最小 loop，验证 Transport→Core→Loop→Tools 全链路
+  4. 金丝雀：子进程 `--canary` 健康自检，通过才切主进程
+- **契约测试**：随 `base/` 分发，定义各模块对外接口；base-user 复用同一套，Agent 新增能力须同步补测。
+- **版本兼容**：`vanor update` 后比对 `.base-version`，不一致则提示——pin 旧 base 继续运行，或基于新 base 重新 fork。
+- **回退**：`vanor rollback` 从 `backups/` 恢复；用户可随时切回 `base/`。
+- **审计**：`self_update.diff` `self_update.test` `self_update.rollback`。
+
+---
+
+## 16. 插件机制 `[v2]`
+
+插件主要用于扩展**通道（Transport）**，可选注册工具。
+
+```ts
+interface TransportPlugin {
+  name: string;                              // telegram | web | ...
+  start(ctx: PluginContext): Promise<void>;  // 建立连接，入站调 ctx.dispatch(msg)
+  stop(): Promise<void>;
+  send(sessionId: string, msg: Message): Promise<void>; // 出站
+  tools?: Tool[];                            // 可选：注册额外工具
+}
+```
+
+- **加载**：包内 `plugins/`（官方）+ `~/.vanor/plugins/`（用户）。
+- **plugin vs skill**：
+
+| | plugin | skill |
+|--|--------|-------|
+| 形态 | 代码（JS 模块） | 数据 + 说明（`SKILL.md`） |
+| 用途 | 通道 / 集成 | 任务步骤（过程性记忆） |
+| 加载 | 进程启动时 | prompt 注入 + 按需读取 |
+| 信任 | 高（执行代码） | 中（被模型引用） |
+
+- **安全**：DM pairing 由插件层与 Core 协作（§13）。
+
+---
+
+## 17. 模块与文件职责
+
+| 路径 | 职责 |
+|------|------|
+| `index.js` | CLI 入口；解析子命令、配置向导、诊断、会话恢复启动 |
+| `base/core/harness.js` | 编排、phase、配置热重载、i18n 状态、事件分发 |
+| `base/core/loop.js` | LLM ↔ 工具迭代 |
+| `base/core/session.js` | 会话读写、路由、生命周期 |
+| `base/core/compaction.js` | 上下文压缩算法 |
+| `base/core/prompt.js` | 系统 prompt 组装（记忆快照、技能、工具说明） |
+| `base/i18n/index.js` | 语言检测、翻译器创建、key 插值与英文 fallback |
+| `base/i18n/locales/` | 各语言翻译字典（当前 `en`、`zh-CN`） |
+| `base/llm/index.js` | 统一 LLM 接口、failover |
+| `base/llm/providers/` | 各 provider 适配 |
+| `base/tools/` | 工具注册表与内置工具 |
+| `base/skills/loader.js` | 技能发现、加载、去重 |
+| `base/memory/` | 短 / 长 / 工作记忆 |
+| `base/transport/message.js` | Message 协议与校验 |
+| `base/transport/cli.js` | CLI TUI 与编解码 |
+| `base/security/` | 审批、allow/deny、workspace 边界 |
+| `base/evolve.js` `[v2]` | 自我更新 |
+| `base/events.js` | 全局事件枚举 |
+| `base/logger.js` | JSONL 日志 |
+| `base/config.js` | 配置加载、校验、`env:` 解析、`ui.language` 安全写回 |
+| `base/test/` | 契约测试（mock LLM） |
+
+---
+
+## 18. 里程碑
+
+- **MVP**：CLI 交互；`read_file`/`write_file`/`edit_file`/`list_dir`/`exec`；有界记忆 + 关键词检索；工作区会话恢复与 compaction；技能加载与管理；多语言 i18n；命令审批 + workspace 边界；JSONL 日志；OpenAI/Anthropic 两 provider + failover。
+- **v1.5**：子 Agent（`delegate`）、`search`/`fetch_url`、向量检索（可选 SQLite）。
+- **v2**：自我改写（base-user + 四级自测）、IM 多通道插件、常驻 daemon（定时任务、网关、热重启）。
+
+---
+
+## 19. 开放问题
+
+1. failover 默认策略：自动切换 vs 仅提示？跨 provider 的 thinking 等参数如何降级。
+2. 关键词检索的召回上限，何时必须引入向量。
+3. daemon 是否提前到 v1.5（定时任务需求强烈时）。
+4. 技能调用是否需要独立 `skill` 工具，而非复用 `read_file`。
+5. 配置热加载范围：哪些键可运行时改、哪些需重启。
+6. Windows 原生支持（命令执行、路径、子进程差异）。
+7. base-user 改写的人类闸门：是否所有核心改动都需 `vanor diff` + 用户确认。
+
+
+## 测试大模型
+
+密钥通过环境变量注入，避免明文入库（原先贴在此处的明文 key 请尽快轮换作废）：
+
+```bash
+export VANOR_API_KEY="<your-key>"
+```
+
+`~/.vanor/config.json`：
+
+```jsonc
+{
+  "llm": {
+    "defaultModel": "wanyou/deepseek/deepseek-v4-pro",
+    "providers": {
+      "wanyou": {
+        "type": "openai",
+        "baseURL": "https://wanyouzhisuan.com/api/v1",
+        "apiKey": "env:VANOR_API_KEY"
+      }
+    }
+  }
+}
+```