skyloom 1.13.6 → 1.13.8

package/docs/OPTIMIZATION_PLAN.md

@@ -1,178 +1,178 @@
-# 天空织机 · Skyloom — 顶级 Agent 框架优化计划
-
-> 目标：把 Skyloom 从「功能完整的多 Agent 终端」打磨成 **架构清晰、体验顶级、辨识度强** 的开源 Agent 框架。
-> 参照系：[opencode](https://github.com/sst/opencode)（架构）、[Claude Code](https://docs.claude.com)（交互范式）、Skyloom Python 原版（功能对等）。
->
-> 制定日期：2026-06-08 · 当前版本：v1.12.0 · 类型检查：✅ 通过
-
----
-
-## 0. 现状诊断（Analysis）
-
-### 0.1 项目规模
-
-| 层 | 文件 | 关键模块 | LOC |
-|----|------|----------|-----|
-| CLI | `src/cli/` | main, tui, mode | ~700 |
-| Core | `src/core/` | agent(1549), memory(1171), mcp(953), llm(804), factory(627) … 38 个模块 | ~11000 |
-| Agents | `src/agents/` | fog/rain/frost/snow/dew/fair | ~500 |
-| Tools | `src/tools/` | builtin, computer, delegate | ~700 |
-| Web | `src/web/` | server(水墨气象台), tts | ~720 |
-| Skills | `config/skills/` | 17 个 SKILL.md | — |
-| Tests | `tests/` | 16 套件 · 154 用例（catalog/memory/task/agent_helpers/config） | — |
-
-### 0.2 已经做得好的（保留 & 强化）
-
-- **美学辨识度强**：水墨气象台 Web UI（宣纸纹理、六矿物色、粒子气象、印章汉字）——这是项目的灵魂，是优化的审美基线，不动它的方向，只做工程化与一致性提升。
-- **功能广度大**：三层记忆、事件总线、DAG 编排、技能系统、向量检索、知识图谱、自进化、安全分级、MCP 双向桥、跨平台电脑操作。
-- **路由分级**：direct / single / orchestrate 三级路由 + 9 种 Pipeline 模板，省 LLM 调用。
-
-### 0.3 必须修复的问题（Critical）
-
-| # | 问题 | 位置 | 影响 |
-|---|------|------|------|
-| C1 | ~~虚构模型~~ **已更正**：`deepseek-v4-flash`/`v4-pro` 经 `/v1/models` 实测**是真实可调模型**（`deepseek-chat` 即其别名）。早先的"虚构"判断错误——会话初的报错来自 Claude Code **宿主**的子 agent 模型注册表，与 Skyloom 无关。已恢复入目录。 | — | — |
-| C2 | **模型数据三处重复且漂移**：`config/models.yaml`、`cli/main.ts` 向导、`README` 表格各写一份 | 多处 | 维护噩梦、数据不一致（catalog 已统一✅） |
-| C3 | **流式已实现却未接线**：`agent.chatStream()` 存在，但 CLI `chat()` 和 Web 都用阻塞式 `chat()` + 假打字机 | `cli/main.ts:314`、`web/server.ts:101` | 体验远低于 opencode/Claude Code；首字延迟高 |
-| C4 | **README 模型表含虚构条目**（`deepseek-v4-*`）；测试数随增量需同步 | `README.md` | 可信度 |
-| C5 | **`agent.ts` 1549 行巨石**：LLM 循环、工具执行、记忆、防循环启发式、委派全混在一个类 | `core/agent.ts` | 难测试、难维护 |
-
-#### 🔴 集成测试发现并已修复的严重 Bug（用真实 DeepSeek key 验证）
-
-| # | 问题 | 根因 | 修复 |
-|---|------|------|------|
-| **B1** | **首条消息必崩**：全新会话发第一条消息 → `Cannot read properties of undefined (reading 'content')`，且首轮请求**根本不含用户消息** | `Memory.addMessage` 把 push 放进**异步 mutex 回调**（fire-and-forget），而 `chatImpl`/`chatStreamImpl` 同一 tick 同步读 `getMessages()` → 读不到 | push 改为**同步**，仅保留改写数组的 prune 在锁内（[memory.ts](../src/core/memory.ts)）+ `messagesWithRecall` 防御性 guard + 回归测试 |
-| **B2** | **用户选的模型被忽略**：`~/.skyloom/config.yaml` 设了 `default_model: deepseek-v4-flash`，却仍走 `gpt-4o`（无 key 必败） | `mergeConfigs` 丢弃了 `llm`/`default_model`/`default_provider` 等顶层键；且 `getModel` 读 camelCase `defaultModel` 而 YAML 是 snake_case `default_model` | `mergeConfigs` 保留全部顶层键并深合并 `llm`；`getModel` 按 `default_model → llm.default_model → …` 解析；`default.yaml` 移除每 Agent 硬编码 `gpt-4o`，统一由 `default_model` 驱动 |
-| **B3** | **memory 配置 snake/camel 不匹配**（B2 修复后暴露）：Agent 构造崩在 `expandUserPath(undefined)` | `default.yaml` 用 `db_path`/`short_term_limit`，`Memory` 期望 `dbPath`/`shortTermLimit`；旧代码靠"配置被丢弃→走 fallback"侥幸不崩 | `BaseAgent` 构造时归一化 memory 配置，两种命名都接受 |
-| **B4** | ~~`deepseek-v4-*` 虚构~~ **判断错误**：经 `/v1/models` 实测**真实可调**，且是用户日常默认模型 | 早先误判；会话初的报错来自 Claude Code **宿主**的子 agent 模型注册表 | 已恢复入目录 + 反转测试断言 |
-
-> 这些 Bug 仅靠类型检查/单测无法发现——必须真实 API 集成验证。修复后 `fog.chat()` 返回「蓝色」、`chatStream` 实测 15–18 个 token 增量。
-
-### 0.4 架构差距（对标 opencode）
-
-| 维度 | opencode | Skyloom 现状 | 差距 |
-|------|----------|-------------|------|
-| Provider/Model | 强类型 Catalog（capabilities/cost/limit/status/variants） | 字符串前缀匹配（`isAnthropicModel`…） | **大** |
-| Session | 持久化实体 + 事件日志 + 消息投影 | 内存对象，落 SQLite 但无事件溯源 | 中 |
-| 上下文压缩 | 按 token 预算自动 compaction + checkpoint | 手动 `/compact` | 中 |
-| 工具系统 | codec 校验输入输出 + 工具内 permission.assert | 注册表 + 全局 security 回调 | 中 |
-| 插件 | 有序 hook 系统（init/provider.update…） | 目录加载器，无 hook 生命周期 | 中 |
-| UI | client/server 分离，真流式 | TUI 仅捕获输入，响应回落到线性滚动 | 中 |
-
----
-
-## 1. 优化原则
-
-1. **不破坏美学**：水墨气象台是辨识度核心。所有 UI 改动只增强，不"极简化"。详见 [AESTHETIC_DESIGN.md](./AESTHETIC_DESIGN.md)。
-2. **单一事实源**：每类数据（模型、命令、Agent 元数据、配色）只有一份定义。
-3. **小步可验证**：每个增量保持 `tsc --noEmit` 绿 + 测试通过，再进下一步。
-4. **功能对等优先于重构**：先保证不丢功能，再分层。
-5. **类型安全**：消除无谓 `any`，用 schema 校验外部边界（LLM 响应、配置、工具 IO）。
-
----
-
-## 2. 分阶段路线图
-
-### Phase 0 — 止血（Critical Fixes）｜~0.5 天 ✅ 已完成
-
-- [x] **P0.1 统一模型目录**（修 C2）
-  新建 [`src/core/catalog.ts`](../src/core/catalog.ts)：单一类型化目录（`ModelInfo`/`ProviderMeta`），从 `config/models.yaml` 读取真实数据。修复了原 `config.ts:loadModelCatalog` 的字段名错配（`context`↔`context_window`）。设置向导现从 catalog 派生。
-  ⚠️ 更正：曾误删 `deepseek-v4-flash/pro`，经 DeepSeek `/v1/models` 实测确认其真实可调后**已恢复**（见 C1）。
-- [x] **P0.2 默认模型自检**：`chat()` 启动时用 `validateModel()` 校验当前模型，不在目录则给出可选清单与提示，而非静默 404。
-- [x] **P0.3 README 校正**（修 C4）：真实模型表、移除虚构条目、链接到本计划与美学文档。
-- [x] **测试**：新增 [`tests/catalog.test.ts`](../tests/catalog.test.ts) 11 用例（含"不含虚构模型"回归断言）。
-
-**验收**：✅ 设置向导列出的每个模型都真实可调；`tsc --noEmit` 绿；9 套件 98 用例全通过。
-
-### Phase 1 — Provider/Model Catalog 强化｜~1 天
-
-对标 opencode `provider-model.md`：
-
-- [ ] **P1.1** Catalog schema：`ModelInfo { id, providerID, family, capabilities{tools,input,output}, cost[], limit{context,output}, status }`。
-- [ ] **P1.2** `LLMClient` 用 catalog 解析端点/能力，替换散落的 `isAnthropicModel`/`isDeepseekModel`/`splitProvider` 启发式。
-- [ ] **P1.3** Provider 鉴权统一：env → `~/.skyloom/config.yaml` → 交互向导，三级回退集中到一处。
-- [ ] **P1.4** 上下文窗口与成本从 catalog 取，喂给自动压缩（Phase 4）和成本统计。
-
-### Phase 2 — 真流式接线（最高体验收益）｜~1 天 ✅ 基本完成
-
-- [x] **P2.0 LLM 层真流式**（关键）：`streamWithTools` 原本只是包装阻塞 `complete()` 一次性吐出。新增 `callOpenAIStream` —— 对所有 OpenAI 兼容 provider 做真正的 SSE（`stream:true` + `stream_options.include_usage`），逐 token yield content/reasoning、按 index 累积 tool_calls、末帧取 usage 记成本。Anthropic 与流早期失败回落阻塞路径。**实测 DeepSeek 15–18 个增量**。
-- [x] **P2.1 CLI 流式**：`chat()` 改为消费 `agent.chatStream()`（新 `streamResponse()`），逐字渲染真实 token，`reasoning` 淡墨斜体、正文矿物色、工具调用以天气符号脉冲呈现。删除旧的阻塞 `render()`。
-- [x] **P2.2 Web 流式**：`/api/chat` 改 SSE（`text/event-stream`），前端 `fetch` + `ReadableStream` 真流式替换假打字机，工具调用呈现为"气象事件"系统消息。已 curl + 真实 API 验证。
-- [x] **P2.3 中断**：`AbortSignal` 从 CLI 贯穿 `chatStream → streamWithTools → callOpenAIStream → fetch`。Ctrl-C 中断当前 turn 并**保留已产出内容**（轮间检测 abort → `interrupted` 事件 + 落库部分内容），二次 Ctrl-C 强退。实测 DeepSeek：abort 后 ~26ms 内停流（不再跑满整段生成）。
-
-### Phase 3 — `agent.ts` 分层（可维护性）｜~1.5 天 🔵 进行中（1549 → 1396 行）
-
-把巨石拆成职责单一的模块（保持对外 API 不变，re-export 兜底）：
-
-- [x] `core/agent/task.ts` — 域模型 `Task`/`TaskState`/`TaskResult`/`AgentState`（纯、可测，re-export 验证身份一致）。
-- [x] `agent_helpers.ts` += `parseExtractedFacts`（纯解析器，移出 BaseAgent）。
-- [ ] `core/agent/loop.ts` — LLM 推理循环（`llmLoop` / `chatStreamImpl`，~275 行热路径）
-- [ ] `core/agent/tools.ts` — 工具选择/执行/结果记录
-- [x] `core/agent/guard.ts` — 防循环启发式抽成 `LoopGuard` 类（持有每轮状态，`observe()` 返回 hints/stop 决策，无副作用）。忠实迁移行为；agent 守卫终止测试仍通过。新增 [`tests/guard.test.ts`](../tests/guard.test.ts) 单测各分支（叙述循环/签名循环/失败堆积/搜索风暴）——这些此前**零覆盖**。期间发现并**修复**两处死安全网：all-failed 硬停（`>=8`）的 outcomes 缓冲上限 6→8；search-storm 硬停（`>=12`）改用**每轮累计搜索计数**（不再受 SIG_WINDOW=8 截断）。两个安全网现在如设计般触发，单测覆盖。
-- [ ] `core/agent/delegate.ts` — 跨 Agent 委派与汇总
-- [ ] `core/agent.ts` — 仅保留 `BaseAgent` 编排与公共 API（目标 < 500 行）
-
-> ✅ **热路径测试网已就位**：[`tests/agent.test.ts`](../tests/agent.test.ts) 用**脚本化 mock LLM** 特征化了核心循环 —— 简单对话、阻塞 `chat()`、推理流、**工具调用回合**、**防循环 guard 终止**（模型重复同一工具 60 次仍能有界终止）。`loop/tools/guard/delegate` 的拆分现在可以安全进行（每步跑这套网 + 真实 API 抽查）。纯单元（task/helpers）已先抽出。
-
-### Phase 4 — Session & 自动上下文管理｜~1.5 天
-
-对标 opencode `session.md`：
-
-- [x] **P4.1 Session 恢复 + 持久化修复**：新增 CLI `/sessions`（编号列表、标记当前）、`/resume <序号|id>`、`/new`。**并修复了一个严重 bug**：`persistDb()`（唯一写盘的代码）**从未被调用** → sql.js 纯内存 → 会话/长期记忆/工作记忆**重启全丢**（"启动自动恢复最新会话"形同虚设）。改为所有写经 `dbRun` 触发**防抖落盘** + `close()` 同步保存。新增跨实例持久化回归测试。
-- [x] **P4.2 自动压缩（catalog 感知触发）**：`shouldAutoCompact()`/`contextUsage()` 不再硬编码 128K —— 改为按当前模型在 catalog 里的真实 `context` 窗口判断（留 20% 余量给回复）。修复了小窗口模型（deepseek-reasoner 64K、mixtral 32K）长聊时**先于压缩就溢出**的隐患；状态栏 % 与模型名也正确了。压缩本身（摘要 + 保留近 N 条 + 指令保真）已存在并已接线。后续：结构化 checkpoint + 溢出后重试（对标 opencode）。
-- [ ] **P4.3 上下文快照**：环境信息、日期、工作区、激活技能合成一份"系统上下文"，模型可见但与历史分离（轻量版 Context Epoch）。
-
-### Phase 5 — 工具与插件健壮性｜~1 天
-
-- [ ] **P5.1 工具 IO 校验**：工具定义带 input/output schema，非法输入不执行、非法输出不算成功（对标 opencode `tools.md`）。
-- [ ] **P5.2 权限内聚**：危险操作的 `permission.assert` 由工具自身发起，security 模块只评估策略 + 管理审批，统一 `ask/allow/deny` 语义。
-- [ ] **P5.3 插件 hook**：目录加载器升级为有序 hook（`init` / `tool.register` / `provider.update`），插件在自己的 scope 注册，卸载即移除。
-
-### Phase 6 — 测试与质量门禁｜~1.5 天
-
-- [ ] **P6.1** 把覆盖率提到核心全覆盖：仍需 `llm`(mock)、`factory`、`pipelines`、`security` 套件（已建 `catalog`✅ `memory`✅ `task`✅ `agent_helpers`✅ `config`✅ `tui`✅ **`agent`✅(mock LLM)**，共 15 套件 142 用例）。`agent` 套件特征化了 chat/stream/工具回合/防循环 guard，为 `agent.ts` 拆分提供安全网。
-- [ ] **P6.2** CI 加门禁：`type-check` + `lint` + `test` + 覆盖率阈值。
-- [ ] **P6.3** 修正所有 `README`/文档与代码的数字一致性（测试数自动从 `vitest` 输出取）。
-
-### Phase 7 — 美学工程化｜~1 天（详见 [AESTHETIC_DESIGN.md](./AESTHETIC_DESIGN.md)）
-
-- [x] **P7.1 设计 token 单一源**：新建 [`src/core/theme.ts`](../src/core/theme.ts)（`PALETTE` + `AGENT_THEMES`：矿物色/汉字/天气符号/诗句/动势）。CLI 已接入；TUI/Web 待接（Web 仍内联 PIGMENTS，P7.3 抽取时统一）。
-- [x] **P7.2 CLI 视觉升级（部分）**：欢迎横幅六灵各显矿物真彩 + 活动灵印章 `▣`；切灵时落朱印 + 诗句；流式正文矿物色、工具调用天气符号。"墨迹晕染"逐字过场待做。
-- [ ] **P7.3 Web 抽出静态资源**：`server.ts` 内联 HTML 拆为 `web/ui/`（html/css/js），加构建步骤，便于演进与缓存。
-- [ ] **P7.4 品牌资产**：SVG logo（印章风）、社交卡片、`docs/` 截图。
-
----
-
-## 3. 里程碑与顺序
-
-```
-M1 止血+目录   Phase 0 + 1   → 真实可用、单一事实源
-M2 体验飞跃     Phase 2 + 7.2 → 真流式 + CLI 视觉，最高感知收益
-M3 工程地基     Phase 3 + 6   → 拆巨石 + 测试网，安全重构
-M4 框架深度     Phase 4 + 5   → Session/压缩/工具/插件，对标 opencode
-M5 打磨成品     Phase 7        → 美学工程化 + 品牌资产 + 发布
-```
-
-建议执行顺序：**M1 → M2 → M3 → M4 → M5**。M1/M2 立刻提升可信度与体验；M3 在动大手术前先织好测试网。
-
----
-
-## 4. 成功标准（Definition of Done）
-
-- 设置向导/文档中**每个模型都真实可调**，模型数据全局一份。
-- CLI 与 Web **真流式**输出，首字延迟显著下降，可中断。
-- `agent.ts` 拆分后**单文件 < 500 行**，核心模块均有单测，CI 绿且有覆盖率门禁。
-- Session 可列举/恢复，超长上下文**自动压缩**不崩。
-- 美学系统单一源驱动 CLI/TUI/Web，品牌资产齐备。
-- README 与实现**零失真**。
-
----
-
-## 5. 风险
-
-| 风险 | 缓解 |
-|------|------|
-| 重构 `agent.ts` 引入回归 | Phase 6 测试网先行；逐块拆 + 每步跑测 |
-| 流式与工具执行交错复杂 | 复用已存在的 `chatStreamImpl` 事件模型，只接线不重写 |
-| Catalog 迁移漏模型 | 以 `config/models.yaml` 为真值源迁移，向导/README 派生 |
-| 美学改动破坏现有观感 | 设计 token 抽取为"提取"非"重画"，先快照对比 |
+# 天空织机 · Skyloom — 顶级 Agent 框架优化计划
+
+> 目标：把 Skyloom 从「功能完整的多 Agent 终端」打磨成 **架构清晰、体验顶级、辨识度强** 的开源 Agent 框架。
+> 参照系：[opencode](https://github.com/sst/opencode)（架构）、[Claude Code](https://docs.claude.com)（交互范式）、Skyloom Python 原版（功能对等）。
+>
+> 制定日期：2026-06-08 · 当前版本：v1.12.0 · 类型检查：✅ 通过
+
+---
+
+## 0. 现状诊断（Analysis）
+
+### 0.1 项目规模
+
+| 层 | 文件 | 关键模块 | LOC |
+|----|------|----------|-----|
+| CLI | `src/cli/` | main, tui, mode | ~700 |
+| Core | `src/core/` | agent(1549), memory(1171), mcp(953), llm(804), factory(627) … 38 个模块 | ~11000 |
+| Agents | `src/agents/` | fog/rain/frost/snow/dew/fair | ~500 |
+| Tools | `src/tools/` | builtin, computer, delegate | ~700 |
+| Web | `src/web/` | server(水墨气象台), tts | ~720 |
+| Skills | `config/skills/` | 17 个 SKILL.md | — |
+| Tests | `tests/` | 16 套件 · 154 用例（catalog/memory/task/agent_helpers/config） | — |
+
+### 0.2 已经做得好的（保留 & 强化）
+
+- **美学辨识度强**：水墨气象台 Web UI（宣纸纹理、六矿物色、粒子气象、印章汉字）——这是项目的灵魂，是优化的审美基线，不动它的方向，只做工程化与一致性提升。
+- **功能广度大**：三层记忆、事件总线、DAG 编排、技能系统、向量检索、知识图谱、自进化、安全分级、MCP 双向桥、跨平台电脑操作。
+- **路由分级**：direct / single / orchestrate 三级路由 + 9 种 Pipeline 模板，省 LLM 调用。
+
+### 0.3 必须修复的问题（Critical）
+
+| # | 问题 | 位置 | 影响 |
+|---|------|------|------|
+| C1 | ~~虚构模型~~ **已更正**：`deepseek-v4-flash`/`v4-pro` 经 `/v1/models` 实测**是真实可调模型**（`deepseek-chat` 即其别名）。早先的"虚构"判断错误——会话初的报错来自 Claude Code **宿主**的子 agent 模型注册表，与 Skyloom 无关。已恢复入目录。 | — | — |
+| C2 | **模型数据三处重复且漂移**：`config/models.yaml`、`cli/main.ts` 向导、`README` 表格各写一份 | 多处 | 维护噩梦、数据不一致（catalog 已统一✅） |
+| C3 | **流式已实现却未接线**：`agent.chatStream()` 存在，但 CLI `chat()` 和 Web 都用阻塞式 `chat()` + 假打字机 | `cli/main.ts:314`、`web/server.ts:101` | 体验远低于 opencode/Claude Code；首字延迟高 |
+| C4 | **README 模型表含虚构条目**（`deepseek-v4-*`）；测试数随增量需同步 | `README.md` | 可信度 |
+| C5 | **`agent.ts` 1549 行巨石**：LLM 循环、工具执行、记忆、防循环启发式、委派全混在一个类 | `core/agent.ts` | 难测试、难维护 |
+
+#### 🔴 集成测试发现并已修复的严重 Bug（用真实 DeepSeek key 验证）
+
+| # | 问题 | 根因 | 修复 |
+|---|------|------|------|
+| **B1** | **首条消息必崩**：全新会话发第一条消息 → `Cannot read properties of undefined (reading 'content')`，且首轮请求**根本不含用户消息** | `Memory.addMessage` 把 push 放进**异步 mutex 回调**（fire-and-forget），而 `chatImpl`/`chatStreamImpl` 同一 tick 同步读 `getMessages()` → 读不到 | push 改为**同步**，仅保留改写数组的 prune 在锁内（[memory.ts](../src/core/memory.ts)）+ `messagesWithRecall` 防御性 guard + 回归测试 |
+| **B2** | **用户选的模型被忽略**：`~/.skyloom/config.yaml` 设了 `default_model: deepseek-v4-flash`，却仍走 `gpt-4o`（无 key 必败） | `mergeConfigs` 丢弃了 `llm`/`default_model`/`default_provider` 等顶层键；且 `getModel` 读 camelCase `defaultModel` 而 YAML 是 snake_case `default_model` | `mergeConfigs` 保留全部顶层键并深合并 `llm`；`getModel` 按 `default_model → llm.default_model → …` 解析；`default.yaml` 移除每 Agent 硬编码 `gpt-4o`，统一由 `default_model` 驱动 |
+| **B3** | **memory 配置 snake/camel 不匹配**（B2 修复后暴露）：Agent 构造崩在 `expandUserPath(undefined)` | `default.yaml` 用 `db_path`/`short_term_limit`，`Memory` 期望 `dbPath`/`shortTermLimit`；旧代码靠"配置被丢弃→走 fallback"侥幸不崩 | `BaseAgent` 构造时归一化 memory 配置，两种命名都接受 |
+| **B4** | ~~`deepseek-v4-*` 虚构~~ **判断错误**：经 `/v1/models` 实测**真实可调**，且是用户日常默认模型 | 早先误判；会话初的报错来自 Claude Code **宿主**的子 agent 模型注册表 | 已恢复入目录 + 反转测试断言 |
+
+> 这些 Bug 仅靠类型检查/单测无法发现——必须真实 API 集成验证。修复后 `fog.chat()` 返回「蓝色」、`chatStream` 实测 15–18 个 token 增量。
+
+### 0.4 架构差距（对标 opencode）
+
+| 维度 | opencode | Skyloom 现状 | 差距 |
+|------|----------|-------------|------|
+| Provider/Model | 强类型 Catalog（capabilities/cost/limit/status/variants） | 字符串前缀匹配（`isAnthropicModel`…） | **大** |
+| Session | 持久化实体 + 事件日志 + 消息投影 | 内存对象，落 SQLite 但无事件溯源 | 中 |
+| 上下文压缩 | 按 token 预算自动 compaction + checkpoint | 手动 `/compact` | 中 |
+| 工具系统 | codec 校验输入输出 + 工具内 permission.assert | 注册表 + 全局 security 回调 | 中 |
+| 插件 | 有序 hook 系统（init/provider.update…） | 目录加载器，无 hook 生命周期 | 中 |
+| UI | client/server 分离，真流式 | TUI 仅捕获输入，响应回落到线性滚动 | 中 |
+
+---
+
+## 1. 优化原则
+
+1. **不破坏美学**：水墨气象台是辨识度核心。所有 UI 改动只增强，不"极简化"。详见 [AESTHETIC_DESIGN.md](./AESTHETIC_DESIGN.md)。
+2. **单一事实源**：每类数据（模型、命令、Agent 元数据、配色）只有一份定义。
+3. **小步可验证**：每个增量保持 `tsc --noEmit` 绿 + 测试通过，再进下一步。
+4. **功能对等优先于重构**：先保证不丢功能，再分层。
+5. **类型安全**：消除无谓 `any`，用 schema 校验外部边界（LLM 响应、配置、工具 IO）。
+
+---
+
+## 2. 分阶段路线图
+
+### Phase 0 — 止血（Critical Fixes）｜~0.5 天 ✅ 已完成
+
+- [x] **P0.1 统一模型目录**（修 C2）
+  新建 [`src/core/catalog.ts`](../src/core/catalog.ts)：单一类型化目录（`ModelInfo`/`ProviderMeta`），从 `config/models.yaml` 读取真实数据。修复了原 `config.ts:loadModelCatalog` 的字段名错配（`context`↔`context_window`）。设置向导现从 catalog 派生。
+  ⚠️ 更正：曾误删 `deepseek-v4-flash/pro`，经 DeepSeek `/v1/models` 实测确认其真实可调后**已恢复**（见 C1）。
+- [x] **P0.2 默认模型自检**：`chat()` 启动时用 `validateModel()` 校验当前模型，不在目录则给出可选清单与提示，而非静默 404。
+- [x] **P0.3 README 校正**（修 C4）：真实模型表、移除虚构条目、链接到本计划与美学文档。
+- [x] **测试**：新增 [`tests/catalog.test.ts`](../tests/catalog.test.ts) 11 用例（含"不含虚构模型"回归断言）。
+
+**验收**：✅ 设置向导列出的每个模型都真实可调；`tsc --noEmit` 绿；9 套件 98 用例全通过。
+
+### Phase 1 — Provider/Model Catalog 强化｜~1 天
+
+对标 opencode `provider-model.md`：
+
+- [ ] **P1.1** Catalog schema：`ModelInfo { id, providerID, family, capabilities{tools,input,output}, cost[], limit{context,output}, status }`。
+- [ ] **P1.2** `LLMClient` 用 catalog 解析端点/能力，替换散落的 `isAnthropicModel`/`isDeepseekModel`/`splitProvider` 启发式。
+- [ ] **P1.3** Provider 鉴权统一：env → `~/.skyloom/config.yaml` → 交互向导，三级回退集中到一处。
+- [ ] **P1.4** 上下文窗口与成本从 catalog 取，喂给自动压缩（Phase 4）和成本统计。
+
+### Phase 2 — 真流式接线（最高体验收益）｜~1 天 ✅ 基本完成
+
+- [x] **P2.0 LLM 层真流式**（关键）：`streamWithTools` 原本只是包装阻塞 `complete()` 一次性吐出。新增 `callOpenAIStream` —— 对所有 OpenAI 兼容 provider 做真正的 SSE（`stream:true` + `stream_options.include_usage`），逐 token yield content/reasoning、按 index 累积 tool_calls、末帧取 usage 记成本。Anthropic 与流早期失败回落阻塞路径。**实测 DeepSeek 15–18 个增量**。
+- [x] **P2.1 CLI 流式**：`chat()` 改为消费 `agent.chatStream()`（新 `streamResponse()`），逐字渲染真实 token，`reasoning` 淡墨斜体、正文矿物色、工具调用以天气符号脉冲呈现。删除旧的阻塞 `render()`。
+- [x] **P2.2 Web 流式**：`/api/chat` 改 SSE（`text/event-stream`），前端 `fetch` + `ReadableStream` 真流式替换假打字机，工具调用呈现为"气象事件"系统消息。已 curl + 真实 API 验证。
+- [x] **P2.3 中断**：`AbortSignal` 从 CLI 贯穿 `chatStream → streamWithTools → callOpenAIStream → fetch`。Ctrl-C 中断当前 turn 并**保留已产出内容**（轮间检测 abort → `interrupted` 事件 + 落库部分内容），二次 Ctrl-C 强退。实测 DeepSeek：abort 后 ~26ms 内停流（不再跑满整段生成）。
+
+### Phase 3 — `agent.ts` 分层（可维护性）｜~1.5 天 🔵 进行中（1549 → 1396 行）
+
+把巨石拆成职责单一的模块（保持对外 API 不变，re-export 兜底）：
+
+- [x] `core/agent/task.ts` — 域模型 `Task`/`TaskState`/`TaskResult`/`AgentState`（纯、可测，re-export 验证身份一致）。
+- [x] `agent_helpers.ts` += `parseExtractedFacts`（纯解析器，移出 BaseAgent）。
+- [ ] `core/agent/loop.ts` — LLM 推理循环（`llmLoop` / `chatStreamImpl`，~275 行热路径）
+- [ ] `core/agent/tools.ts` — 工具选择/执行/结果记录
+- [x] `core/agent/guard.ts` — 防循环启发式抽成 `LoopGuard` 类（持有每轮状态，`observe()` 返回 hints/stop 决策，无副作用）。忠实迁移行为；agent 守卫终止测试仍通过。新增 [`tests/guard.test.ts`](../tests/guard.test.ts) 单测各分支（叙述循环/签名循环/失败堆积/搜索风暴）——这些此前**零覆盖**。期间发现并**修复**两处死安全网：all-failed 硬停（`>=8`）的 outcomes 缓冲上限 6→8；search-storm 硬停（`>=12`）改用**每轮累计搜索计数**（不再受 SIG_WINDOW=8 截断）。两个安全网现在如设计般触发，单测覆盖。
+- [ ] `core/agent/delegate.ts` — 跨 Agent 委派与汇总
+- [ ] `core/agent.ts` — 仅保留 `BaseAgent` 编排与公共 API（目标 < 500 行）
+
+> ✅ **热路径测试网已就位**：[`tests/agent.test.ts`](../tests/agent.test.ts) 用**脚本化 mock LLM** 特征化了核心循环 —— 简单对话、阻塞 `chat()`、推理流、**工具调用回合**、**防循环 guard 终止**（模型重复同一工具 60 次仍能有界终止）。`loop/tools/guard/delegate` 的拆分现在可以安全进行（每步跑这套网 + 真实 API 抽查）。纯单元（task/helpers）已先抽出。
+
+### Phase 4 — Session & 自动上下文管理｜~1.5 天
+
+对标 opencode `session.md`：
+
+- [x] **P4.1 Session 恢复 + 持久化修复**：新增 CLI `/sessions`（编号列表、标记当前）、`/resume <序号|id>`、`/new`。**并修复了一个严重 bug**：`persistDb()`（唯一写盘的代码）**从未被调用** → sql.js 纯内存 → 会话/长期记忆/工作记忆**重启全丢**（"启动自动恢复最新会话"形同虚设）。改为所有写经 `dbRun` 触发**防抖落盘** + `close()` 同步保存。新增跨实例持久化回归测试。
+- [x] **P4.2 自动压缩（catalog 感知触发）**：`shouldAutoCompact()`/`contextUsage()` 不再硬编码 128K —— 改为按当前模型在 catalog 里的真实 `context` 窗口判断（留 20% 余量给回复）。修复了小窗口模型（deepseek-reasoner 64K、mixtral 32K）长聊时**先于压缩就溢出**的隐患；状态栏 % 与模型名也正确了。压缩本身（摘要 + 保留近 N 条 + 指令保真）已存在并已接线。后续：结构化 checkpoint + 溢出后重试（对标 opencode）。
+- [ ] **P4.3 上下文快照**：环境信息、日期、工作区、激活技能合成一份"系统上下文"，模型可见但与历史分离（轻量版 Context Epoch）。
+
+### Phase 5 — 工具与插件健壮性｜~1 天
+
+- [ ] **P5.1 工具 IO 校验**：工具定义带 input/output schema，非法输入不执行、非法输出不算成功（对标 opencode `tools.md`）。
+- [ ] **P5.2 权限内聚**：危险操作的 `permission.assert` 由工具自身发起，security 模块只评估策略 + 管理审批，统一 `ask/allow/deny` 语义。
+- [ ] **P5.3 插件 hook**：目录加载器升级为有序 hook（`init` / `tool.register` / `provider.update`），插件在自己的 scope 注册，卸载即移除。
+
+### Phase 6 — 测试与质量门禁｜~1.5 天
+
+- [ ] **P6.1** 把覆盖率提到核心全覆盖：仍需 `llm`(mock)、`factory`、`pipelines`、`security` 套件（已建 `catalog`✅ `memory`✅ `task`✅ `agent_helpers`✅ `config`✅ `tui`✅ **`agent`✅(mock LLM)**，共 15 套件 142 用例）。`agent` 套件特征化了 chat/stream/工具回合/防循环 guard，为 `agent.ts` 拆分提供安全网。
+- [ ] **P6.2** CI 加门禁：`type-check` + `lint` + `test` + 覆盖率阈值。
+- [ ] **P6.3** 修正所有 `README`/文档与代码的数字一致性（测试数自动从 `vitest` 输出取）。
+
+### Phase 7 — 美学工程化｜~1 天（详见 [AESTHETIC_DESIGN.md](./AESTHETIC_DESIGN.md)）
+
+- [x] **P7.1 设计 token 单一源**：新建 [`src/core/theme.ts`](../src/core/theme.ts)（`PALETTE` + `AGENT_THEMES`：矿物色/汉字/天气符号/诗句/动势）。CLI 已接入；TUI/Web 待接（Web 仍内联 PIGMENTS，P7.3 抽取时统一）。
+- [x] **P7.2 CLI 视觉升级（部分）**：欢迎横幅六灵各显矿物真彩 + 活动灵印章 `▣`；切灵时落朱印 + 诗句；流式正文矿物色、工具调用天气符号。"墨迹晕染"逐字过场待做。
+- [ ] **P7.3 Web 抽出静态资源**：`server.ts` 内联 HTML 拆为 `web/ui/`（html/css/js），加构建步骤，便于演进与缓存。
+- [ ] **P7.4 品牌资产**：SVG logo（印章风）、社交卡片、`docs/` 截图。
+
+---
+
+## 3. 里程碑与顺序
+
+```
+M1 止血+目录   Phase 0 + 1   → 真实可用、单一事实源
+M2 体验飞跃     Phase 2 + 7.2 → 真流式 + CLI 视觉，最高感知收益
+M3 工程地基     Phase 3 + 6   → 拆巨石 + 测试网，安全重构
+M4 框架深度     Phase 4 + 5   → Session/压缩/工具/插件，对标 opencode
+M5 打磨成品     Phase 7        → 美学工程化 + 品牌资产 + 发布
+```
+
+建议执行顺序：**M1 → M2 → M3 → M4 → M5**。M1/M2 立刻提升可信度与体验；M3 在动大手术前先织好测试网。
+
+---
+
+## 4. 成功标准（Definition of Done）
+
+- 设置向导/文档中**每个模型都真实可调**，模型数据全局一份。
+- CLI 与 Web **真流式**输出，首字延迟显著下降，可中断。
+- `agent.ts` 拆分后**单文件 < 500 行**，核心模块均有单测，CI 绿且有覆盖率门禁。
+- Session 可列举/恢复，超长上下文**自动压缩**不崩。
+- 美学系统单一源驱动 CLI/TUI/Web，品牌资产齐备。
+- README 与实现**零失真**。
+
+---
+
+## 5. 风险
+
+| 风险 | 缓解 |
+|------|------|
+| 重构 `agent.ts` 引入回归 | Phase 6 测试网先行；逐块拆 + 每步跑测 |
+| 流式与工具执行交错复杂 | 复用已存在的 `chatStreamImpl` 事件模型，只接线不重写 |
+| Catalog 迁移漏模型 | 以 `config/models.yaml` 为真值源迁移，向导/README 派生 |
+| 美学改动破坏现有观感 | 设计 token 抽取为"提取"非"重画"，先快照对比 |

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "skyloom",
-  "version": "1.13.6",
-  "description": "天空织机 Skyloom — 6 weather-themed AI agents: Fog, Rain, Frost, Snow, Dew, Fair",
-  "preferGlobal": true,
-  "type": "commonjs",
-  "main": "./dist/index.js",
-  "bin": {
-    "sky": "dist/cli/main.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node ./dist/cli/main.js",
-    "chat": "node ./dist/cli/main.js chat",
-    "task": "node ./dist/cli/main.js task",
-    "web": "node ./dist/cli/main.js web",
-    "test": "vitest",
-    "test:coverage": "vitest --coverage",
-    "lint": "eslint src --ext .ts",
-    "type-check": "tsc --noEmit",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "pretest": "npm run type-check",
-    "setup": "node scripts/install.js",
-    "postinstall": "node scripts/link.js"
-  },
-  "keywords": [
-    "multi-agent",
-    "llm",
-    "orchestration",
-    "ai",
-    "tool-use"
-  ],
-  "author": "Skyloom Team",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/susurrune/skyloom-ts.git"
-  },
-  "homepage": "https://github.com/susurrune/skyloom-ts#readme",
-  "bugs": {
-    "url": "https://github.com/susurrune/skyloom-ts/issues"
-  },
-  "dependencies": {
-    "axios": "^1.7.7",
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "glob": "^11.0.0",
-    "sql.js": "^1.14.1",
-    "yaml": "^2.4.1"
-  },
-  "devDependencies": {
-    "@types/glob": "^8.1.0",
-    "@types/node": "^22.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "@vitest/coverage-v8": "^2.0.0",
-    "@vitest/ui": "^2.0.0",
-    "eslint": "^9.0.0",
-    "prettier": "^3.2.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.4.0",
-    "vitest": "^2.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "skyloom",
+  "version": "1.13.8",
+  "description": "天空织机 Skyloom — 6 weather-themed AI agents: Fog, Rain, Frost, Snow, Dew, Fair",
+  "preferGlobal": true,
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "bin": {
+    "sky": "dist/cli/main.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node ./dist/cli/main.js",
+    "chat": "node ./dist/cli/main.js chat",
+    "task": "node ./dist/cli/main.js task",
+    "web": "node ./dist/cli/main.js web",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts",
+    "type-check": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "pretest": "npm run type-check",
+    "setup": "node scripts/install.js",
+    "postinstall": "node scripts/link.js"
+  },
+  "keywords": [
+    "multi-agent",
+    "llm",
+    "orchestration",
+    "ai",
+    "tool-use"
+  ],
+  "author": "Skyloom Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/susurrune/skyloom-ts.git"
+  },
+  "homepage": "https://github.com/susurrune/skyloom-ts#readme",
+  "bugs": {
+    "url": "https://github.com/susurrune/skyloom-ts/issues"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "glob": "^11.0.0",
+    "sql.js": "^1.14.1",
+    "yaml": "^2.4.1"
+  },
+  "devDependencies": {
+    "@types/glob": "^8.1.0",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "@vitest/ui": "^2.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.2.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scripts/install.js

@@ -1,48 +1,48 @@
-#!/usr/bin/env node
-/**
- * 天空织机 · Skyloom — 一键安装
- *
- * Usage:
- *   npm run setup          # 自动 install → build → link
- *   npm install -g ./      # 全局安装（装完后 sky 命令可用）
- *   npx skyloom            # 免安装直接运行
- */
-
-const { execSync } = require("child_process");
-const { existsSync } = require("fs");
-
-const CYAN = "\x1b[36m";
-const GREEN = "\x1b[32m";
-const DIM = "\x1b[2m";
-const RESET = "\x1b[0m";
-
-function run(cmd, label) {
-  process.stdout.write(`  ${CYAN}✦${RESET} ${label} ${DIM}...${RESET}`);
-  try {
-    execSync(cmd, { stdio: "pipe", encoding: "utf-8" });
-    process.stdout.write(` ${GREEN}✓${RESET}\n`);
-  } catch (e) {
-    process.stdout.write(` ${GREEN}✓${RESET}\n`);
-  }
-}
-
-console.log(`\n  ${CYAN}✦  天空织机 · Skyloom  ✦${RESET}\n`);
-
-run("npm install --no-fund --no-audit", "Installing dependencies");
-run("npx tsc", "Building TypeScript");
-
-// Try global link so `sky` works anywhere
-try {
-  execSync("npm link", { stdio: "pipe", encoding: "utf-8", timeout: 10000 });
-  process.stdout.write(`  ${CYAN}✦${RESET} Global 'sky' command ${GREEN}✓${RESET}\n`);
-} catch {
-  process.stdout.write(`  ${CYAN}✦${RESET} Global 'sky' command ${DIM}(use: npm install -g .)${RESET}\n`);
-}
-
-console.log(`\n  ${GREEN}✅  天空织机 已就绪${RESET}\n`);
-console.log(`  ${DIM}────────────────────────────────${RESET}`);
-console.log(`  ${CYAN}sky chat        ${DIM}开始对话${RESET}`);
-console.log(`  ${CYAN}sky web         ${DIM}启动 Web UI → http://localhost:3000${RESET}`);
-console.log(`  ${CYAN}sky task <goal> ${DIM}多 Agent 编排${RESET}`);
-console.log(`  ${CYAN}sky help        ${DIM}所有命令${RESET}`);
-console.log(`  ${DIM}────────────────────────────────${RESET}\n`);
+#!/usr/bin/env node
+/**
+ * 天空织机 · Skyloom — 一键安装
+ *
+ * Usage:
+ *   npm run setup          # 自动 install → build → link
+ *   npm install -g ./      # 全局安装（装完后 sky 命令可用）
+ *   npx skyloom            # 免安装直接运行
+ */
+
+const { execSync } = require("child_process");
+const { existsSync } = require("fs");
+
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+function run(cmd, label) {
+  process.stdout.write(`  ${CYAN}✦${RESET} ${label} ${DIM}...${RESET}`);
+  try {
+    execSync(cmd, { stdio: "pipe", encoding: "utf-8" });
+    process.stdout.write(` ${GREEN}✓${RESET}\n`);
+  } catch (e) {
+    process.stdout.write(` ${GREEN}✓${RESET}\n`);
+  }
+}
+
+console.log(`\n  ${CYAN}✦  天空织机 · Skyloom  ✦${RESET}\n`);
+
+run("npm install --no-fund --no-audit", "Installing dependencies");
+run("npx tsc", "Building TypeScript");
+
+// Try global link so `sky` works anywhere
+try {
+  execSync("npm link", { stdio: "pipe", encoding: "utf-8", timeout: 10000 });
+  process.stdout.write(`  ${CYAN}✦${RESET} Global 'sky' command ${GREEN}✓${RESET}\n`);
+} catch {
+  process.stdout.write(`  ${CYAN}✦${RESET} Global 'sky' command ${DIM}(use: npm install -g .)${RESET}\n`);
+}
+
+console.log(`\n  ${GREEN}✅  天空织机 已就绪${RESET}\n`);
+console.log(`  ${DIM}────────────────────────────────${RESET}`);
+console.log(`  ${CYAN}sky chat        ${DIM}开始对话${RESET}`);
+console.log(`  ${CYAN}sky web         ${DIM}启动 Web UI → http://localhost:3000${RESET}`);
+console.log(`  ${CYAN}sky task <goal> ${DIM}多 Agent 编排${RESET}`);
+console.log(`  ${CYAN}sky help        ${DIM}所有命令${RESET}`);
+console.log(`  ${DIM}────────────────────────────────${RESET}\n`);

package/scripts/link.js

@@ -1,10 +1,10 @@
-#!/usr/bin/env node
-/**
- * Post-install hook — runs `npm link` so `sky` is globally available.
- * Silently skipped on CI or when permissions are insufficient.
- */
-if (process.env.CI || process.env.NODE_ENV === "production") process.exit(0);
-const { execSync } = require("child_process");
-try {
-  execSync("npm link", { stdio: "pipe", encoding: "utf-8", timeout: 10000 });
-} catch (_) {}
+#!/usr/bin/env node
+/**
+ * Post-install hook — runs `npm link` so `sky` is globally available.
+ * Silently skipped on CI or when permissions are insufficient.
+ */
+if (process.env.CI || process.env.NODE_ENV === "production") process.exit(0);
+const { execSync } = require("child_process");
+try {
+  execSync("npm link", { stdio: "pipe", encoding: "utf-8", timeout: 10000 });
+} catch (_) {}