foliko 1.1.92 → 2.0.0

package/REFACTORING_PLAN.md

@@ -0,0 +1,645 @@
+# Foliko 重构方案
+
+> **项目**：Foliko（简约的插件化 Agent 框架）
+> **源仓库**：`D:\code\vb-agent`
+> **重构目标**：`D:\date\20260624\agent`
+> **状态**：方案已确认，待执行
+> **版本**：v1.0
+
+---
+
+## 目录
+
+- [1. 项目背景](#1-项目背景)
+- [2. 现状分析](#2-现状分析)
+- [3. 问题诊断](#3-问题诊断)
+- [4. 重构目标](#4-重构目标)
+- [5. 已确认的关键决策](#5-已确认的关键决策)
+- [6. 目标目录结构](#6-目标目录结构)
+- [7. 核心模块重构细节](#7-核心模块重构细节)
+- [8. 命名与编码规范](#8-命名与编码规范)
+- [9. 公共 API 门面](#9-公共-api-门面)
+- [10. 迁移策略](#10-迁移策略)
+- [11. 风险与缓解](#11-风险与缓解)
+- [12. 度量指标](#12-度量指标)
+- [13. 后续文档](#13-后续文档)
+
+---
+
+## 1. 项目背景
+
+Foliko 是一个纯 JavaScript（无 TypeScript）的插件化 Agent 框架，提供：
+
+- 极简核心 + 插件扩展机制
+- Vercel AI SDK 集成，支持 Anthropic / OpenAI / DeepSeek / OpenAI-Compatible
+- 工具调用循环（ToolLoopAgent）
+- 技能系统（Skill）、工作流（Workflow）
+- MCP（Model Context Protocol）集成
+- 多会话（Session）与子 Agent（Subagent / Worker）
+- Ambient Agent 模式（持续后台运行）
+- CLI 工具（`foliko chat` / `foliko plugin` / `foliko start` 等）
+
+## 2. 现状分析
+
+### 2.1 规模
+
+| 维度 | 数量 |
+|---|---|
+| JS 文件总数 | 111 |
+| 代码总行数 | ~43,530 |
+| `src/core/` | 30 文件 |
+| `src/utils/` | 16 文件 |
+| `plugins/` 顶层 | 30+（仅 2 个有子目录） |
+| `cli/src/` | 17 文件 |
+| 巨型单文件 | framework.js 1422 行、mcp-executor.js 1316 行、memory-plugin.js 1293 行、python-plugin-loader.js 1142 行、workflow-engine.js 1110 行、agent-chat.js 1051 行 |
+
+### 2.2 第三方依赖
+
+详见 `package.json` 核心依赖：AI SDK 生态、MCP SDK、hono、pino、zod、@larksuiteoapi/node-sdk、@chnak/* 系列（QQ/微信 Bot）、@earendil-works/pi-tui 等。
+
+## 3. 问题诊断
+
+### 3.1 架构层
+
+1. **`Framework` 是上帝类**（1422 行，30+ 职责）
+   - 子系统管理（PluginManager / ToolRegistry）
+   - 三层上下文（3 个独立的 `AsyncLocalStorage`）
+   - 三类 Agent 工厂（`createAgent` / `createSubAgent` / `createSessionAgent` / `createWorker`）
+   - Worker / Coordinator 协调
+   - Session TTL 清理、JSONL 存储
+   - Prompt Parts 同步
+   - 工作目录 / `.foliko` 目录管理
+   - `rescanProject`（114 行，深度耦合 PluginManager / DefaultPlugins / SkillManager）
+   - `createFrameworkLogger`（78 行，应在 `logger.js`）
+
+2. **目录职责不清**
+   - `src/core/` 同时塞了基础设施（`framework`, `agent`）和次级模块（`context-compressor`, `jsonl-storage`, `session-manager`, `token-counter`, `system-prompt-builder`）
+   - `src/utils/` 收容了真正的 utils（`id.js`, `error.js`）和体量不小、明显不该叫 util 的（`data-splitter.js`, `sandbox.js`, `download.js`, `circuit-breaker.js`, `error-boundary.js`）
+   - `src/capabilities/` 装了 `skill-manager` 和 `workflow-engine`，但 `mcp-executor` 又在 `src/executors/`，命名风格混乱
+
+3. **上下文概念拆得过散**
+   - `context-compressor.js`（958 行）与 `enhanced-context-compressor.js`（重复 / 增强版）
+   - `context-manager.js` / `request-context.js` / `session-manager.js` / `session-entry.js` / `chat-session.js` 五个文件交叉引用
+
+4. **Agent 变体过多**
+   - `Agent`（主对话）/`Subagent`（轻量子代理）/`WorkerAgent`（Coordinator 模式）/`ChatSession`（消息队列）
+   - `coordinator-manager.js` / `coordinator-plugin.js` / `sub-agent-config.js`，一个"子任务"概念衍生出 6 个文件
+
+5. **Plugin 平面化**
+   - 30+ 插件全在 `plugins/` 根目录
+   - 混合了"系统核心插件"（`ai-plugin`、`tools-plugin`）、"执行器"（`shell-executor-plugin`）、"集成"（`qq-plugin`、`weixin-plugin`）、"功能"（`memory-plugin`、`web-plugin`）四类
+
+### 3.2 工程层
+
+6. **命名风格不统一**
+   - `subagent.js` vs `sub-agent-config.js`
+   - `framework.js` vs `notification-manager.js`
+   - 插件命名：有的 `Plugin` 后缀（`ai-plugin`），有的 `Manager` 后缀（`skill-manager`），有的啥都没有
+
+7. **死代码 / 实验代码混入主干**
+   - `cli/src/ui/chat-ui-old.js`（469 行）
+   - `framework.js` 中 `createSubAgent` 里有 14 行被注释掉的旧 toolList 构造逻辑
+   - 8 个 `examples/test-*.js`（实验）混在示例目录
+
+8. **public API 暴露面不可控**
+   - `src/index.js` 只导出 8 个符号
+   - 但 `framework` 实例上却有 60+ 公共方法
+   - 入口不清晰，新人上手难
+
+9. **配置 / 日志 / 错误处理分散**
+   - 日志在 `src/utils/logger.js`，但 `createFrameworkLogger` 又在 `framework.js`
+   - 错误有 `error.js` + `error-boundary.js` 两个文件
+   - CLI 的 `cli/src/utils/{config,plugin-config}.js` 跟主项目配置分层
+
+10. **没有测试目录**
+    - `package.json` 里 `npm test` 都不存在
+    - 重构没有安全网
+
+### 3.3 使用层
+
+11. **"使用方法不够简单"具体表现**
+    - 跑 demo 需要 4 步：`new Framework` → `loadPlugin(new AIPlugin({...}))` → `framework.createAgent({...})` → `agent.chat(...)`
+    - 换模型链路长：`ai-plugin.js` → `provider.js` → `provider-registry.js` → `agent-chat.js` 四处
+    - 工具 schema 混用 Zod / JSON Schema，README 不说明
+    - CLI 启动要 `.env`，还要单独建 `mcp_config.json` / `agents/*.json` / `plugins/*.json`
+
+## 4. 重构目标
+
+1. **清晰的分层**：核心 / 运行时 / 公共组件 / 插件 / CLI / 示例，各司其职
+2. **精简的公共 API**：≤ 10 个 `foliko.xxx()` 工厂函数完成 80% 场景
+3. **单一职责**：每个文件 ≤ 400 行，单个类 ≤ 8 个公共方法
+4. **插件分类**：核心 / 执行器 / 存储 / 消息 / 观察 / 业务，每个插件自带 README
+5. **零破坏性迁移**：保留旧导入路径 6~12 个月（带 deprecation warning）
+6. **可测性**：所有核心模块可独立 mock，关键路径有单元测试
+
+## 5. 已确认的关键决策
+
+| 决策项 | 决定 |
+|---|---|
+| 重构后项目位置 | `D:\date\20260624\agent`（当前目录） |
+| Framework 拆分粒度 | 5 个文件：framework / lifecycle / registry / loader + index |
+| 插件目录化 | 全部 30+ 插件按 8 大类迁移 |
+| 测试策略 | 边重构边补 vitest 单测（目标覆盖率 60%） |
+| 源仓库处理 | `D:\code\vb-agent` 保留作只读 mirror，对照参考 |
+| 旧路径兼容 | `src/compat/` 转发 + deprecation warning，保留到下个 major |
+
+## 6. 目标目录结构
+
+```
+foliko/                                    # 项目根
+├── package.json
+├── README.md
+├── SPEC.md
+├── CHANGELOG.md
+├── Dockerfile
+├── docker-compose.yml
+├── .env.example
+│
+├── bin/                                   # CLI 入口（薄壳）
+│   └── foliko.js
+│
+├── src/                                   # 框架源码
+│   ├── index.js                           # 统一公共 API 门面
+│   ├── framework/
+│   │   ├── index.js
+│   │   ├── framework.js                   # 瘦身后的容器（目标 ~250 行）
+│   │   ├── lifecycle.js                   # bootstrap / ready / destroy
+│   │   ├── registry.js                    # 统一注册表
+│   │   └── loader.js                      # 加载 .foliko 配置
+│   ├── agent/
+│   │   ├── index.js
+│   │   ├── base.js                        # BaseAgent 公共基类
+│   │   ├── main.js                        # 主对话 Agent
+│   │   ├── sub.js                         # 子 Agent
+│   │   ├── worker.js                      # Coordinator Worker
+│   │   └── prompt.js                      # SystemPromptBuilder
+│   ├── session/
+│   │   ├── index.js
+│   │   ├── session.js                     # SessionManager
+│   │   ├── entry.js                       # JSONL 读写
+│   │   ├── chat.js                        # ChatSession
+│   │   └── ttl.js                         # 过期清理
+│   ├── context/
+│   │   ├── index.js
+│   │   ├── request.js                     # RequestContext
+│   │   ├── session.js                     # SessionContext
+│   │   ├── agent.js                       # AgentContext
+│   │   ├── storage.js                     # AsyncLocalStorage 单例
+│   │   └── compressor.js                  # 合并后的 Compressor
+│   ├── llm/
+│   │   ├── index.js
+│   │   ├── provider.js                    # 抽象 Provider
+│   │   ├── registry.js                    # Provider 注册表
+│   │   ├── streaming.js
+│   │   └── tokens.js                      # TokenCounter
+│   ├── tool/
+│   │   ├── index.js
+│   │   ├── registry.js                    # ToolRegistry
+│   │   ├── executor.js                    # ToolExecutor
+│   │   ├── router.js
+│   │   └── schema.js                      # Zod/JSON-Schema 适配
+│   ├── plugin/
+│   │   ├── index.js
+│   │   ├── base.js                        # Plugin 基类
+│   │   ├── manager.js                     # PluginManager
+│   │   └── loader.js
+│   ├── skills/
+│   │   ├── index.js
+│   │   ├── manager.js                     # SkillManager
+│   │   ├── workflow.js                    # WorkflowEngine
+│   │   └── registry.js
+│   ├── mcp/
+│   │   ├── index.js
+│   │   ├── executor.js                    # MCPExecutor
+│   │   └── client.js
+│   ├── notification/
+│   │   ├── index.js
+│   │   └── manager.js
+│   ├── storage/
+│   │   ├── index.js
+│   │   ├── jsonl.js
+│   │   └── kv.js
+│   ├── common/                            # 真正的通用工具
+│   │   ├── logger.js                      # Logger + createFrameworkLogger
+│   │   ├── events.js                      # EventEmitter
+│   │   ├── errors.js                      # 错误类型 + 边界处理（合并）
+│   │   ├── retry.js
+│   │   ├── id.js
+│   │   ├── path.js
+│   │   ├── queue.js
+│   │   ├── circuit.js
+│   │   └── diff.js
+│   ├── config/
+│   │   ├── index.js
+│   │   ├── env.js
+│   │   ├── foliko.js
+│   │   └── plugin-config.js
+│   ├── cli/                               # CLI（从 cli/src/ 移过来）
+│   │   ├── index.js
+│   │   ├── runner.js
+│   │   ├── commands/
+│   │   │   ├── chat.js
+│   │   │   ├── list.js
+│   │   │   ├── plugin.js
+│   │   │   └── daemon.js
+│   │   ├── ui/
+│   │   │   ├── chat.js                    # 合并 chat-ui + chat-ui-old
+│   │   │   └── components/
+│   │   │       ├── footer.js
+│   │   │       ├── status.js
+│   │   │       ├── message-bubble.js
+│   │   │       ├── mention-provider.js
+│   │   │       └── chained-autocomplete.js
+│   │   └── utils/
+│   │       ├── ansi.js
+│   │       ├── markdown.js
+│   │       └── config.js
+│   └── compat/                            # 旧路径兼容层
+│       ├── core/
+│       └── ...
+│
+├── plugins/                               # 内置插件（按职能分组）
+│   ├── README.md
+│   ├── core/
+│   │   ├── default/
+│   │   ├── ai/
+│   │   ├── tool-manager/
+│   │   ├── plugin-manager/
+│   │   ├── session/
+│   │   ├── sub-agent/
+│   │   ├── coordinator/
+│   │   ├── scheduler/
+│   │   ├── skill-manager/
+│   │   ├── workflow/
+│   │   ├── mcp/
+│   │   ├── storage/
+│   │   ├── audit/
+│   │   ├── rules/
+│   │   └── think/
+│   ├── executors/
+│   │   ├── shell/
+│   │   ├── python/
+│   │   ├── extension/
+│   │   └── data-splitter/
+│   ├── io/
+│   │   ├── file-system/
+│   │   ├── web/
+│   │   └── download/
+│   ├── messaging/
+│   │   ├── email/
+│   │   ├── telegram/
+│   │   ├── qq/
+│   │   ├── weixin/
+│   │   └── feishu/
+│   ├── memory/
+│   ├── ambient/
+│   ├── install/
+│   └── trading/
+│
+├── examples/                              # 整理后的示例
+│   ├── README.md
+│   ├── 01-basic.js
+│   ├── 02-bootstrap.js
+│   ├── 03-custom-tool.js
+│   ├── 04-custom-plugin.js
+│   ├── 05-mcp.js
+│   ├── 06-skills.js
+│   ├── 07-workflow.js
+│   ├── 08-ambient.js
+│   ├── 09-coordinator.js
+│   └── 10-streaming.js
+│
+├── docs/
+│   ├── REFACTORING_PLAN.md                # 本文档
+│   ├── architecture.md
+│   ├── public-api.md
+│   ├── context-system.md
+│   ├── plugin-dev.md
+│   ├── mcp.md
+│   ├── migration.md
+│   └── ...
+│
+├── skills/                                # 知识库/工作流（保留原结构）
+│
+└── tests/                                 # 新增
+    ├── setup.js
+    ├── core/
+    ├── plugins/
+    └── cli/
+```
+
+## 7. 核心模块重构细节
+
+### 7.1 Framework 拆分
+
+旧 `framework.js`（1422 行）按职责拆 5 个文件：
+
+| 新文件 | 行数目标 | 职责 |
+|---|---|---|
+| `framework/framework.js` | ~250 | 容器协调：构造、销毁、事件总线、就绪信号 |
+| `framework/registry.js` | ~200 | 聚合 plugin/tool/command 注册表 |
+| `framework/lifecycle.js` | ~150 | `bootstrap()` / `ready()` / `destroy()` / `setCwd()` / `rescanProject()` |
+| `framework/loader.js` | ~150 | 读取 `.foliko/` 配置并加载默认插件 |
+| `framework/index.js` | ~30 | barrel export |
+
+**`rescanProject`（114 行）继续拆**：
+- 把"卸载 keepSet 之外的"逻辑抽到 `plugin/manager.js` 的 `unloadExcept(keepSet)`
+- 把"同步 SkillManager._skillsDirs"抽到 `skills/manager.js` 的 `setSearchDirs()`
+
+**Logger 工厂迁移**：`createFrameworkLogger` 整段移到 `common/logger.js`，改成 `Logger.attachTo(framework)` 方法。
+
+### 7.2 三层上下文重整
+
+新 `context/storage.js` 集中所有 `AsyncLocalStorage`：
+
+```js
+// src/context/storage.js
+class ContextStorage {
+  constructor() {
+    this._request = new AsyncLocalStorage();
+    this._session = new AsyncLocalStorage();
+  }
+  runRequest(ctx, fn) { return this._request.run(ctx, fn); }
+  runSession(ctx, fn) { return this._session.run(ctx, fn); }
+  getRequest() { return this._request.getStore(); }
+  getSession() { return this._session.getStore(); }
+}
+module.exports = new ContextStorage(); // 单例
+```
+
+- `context/compressor.js` 合并 `context-compressor.js`（958 行）+ `enhanced-context-compressor.js`，保留更强的版本，删除旧 export
+- `session/ttl.js` 单独实现 TTL 清理，`framework` 通过组合 `SessionTTL` 引用
+
+### 7.3 Agent 变体统一
+
+让 `MainAgent` / `SubAgent` / `WorkerAgent` 共享一个 `BaseAgent`：
+
+```js
+// src/agent/base.js
+class BaseAgent extends EventEmitter {
+  constructor(framework, config) { ... }
+  // 公共：chat / chatStream / registerPromptPart
+}
+```
+
+每个子类的差异通过策略字段注入：
+
+| 维度 | MainAgent | SubAgent | WorkerAgent |
+|---|---|---|---|
+| 生命周期 | 常驻 | 单次任务 | 由 Coordinator 回收 |
+| 工具来源 | Framework 全量 | parentTools ∪ 自定义 | 注册到 coordinator |
+| Prompt | 完整 | 角色 + 父 prompt 切片 | 任务描述 |
+| 创建 | `framework.createAgent()` | `framework.createSubAgent()` | `framework.createWorker()` |
+
+`framework.createSessionAgent` 本质是"带 sessionId 的 MainAgent"，改成 `framework.createAgent({ sessionId })`。
+
+### 7.4 插件目录化
+
+每个插件一个目录，**统一结构**：
+
+```
+plugins/messaging/email/
+├── index.js            # 导出 Plugin 类
+├── monitor.js
+├── parser.js
+├── reply.js
+├── handlers.js
+├── constants.js
+├── utils.js
+└── README.md           # 用途、配置项、依赖
+```
+
+`plugins/core/default/` 拆 `default-plugins.js`（735 行）：
+- `bootstrap.js` 负责"哪些是默认必装"
+- `config.js` 负责"读取 agent 配置"
+- `index.js` 拼装
+
+### 7.5 LLM 层抽象
+
+`llm/provider.js` 提供统一接口：
+
+```js
+class LLMProvider {
+  async chat(messages, options) { ... }
+  async *stream(messages, options) { ... }
+  countTokens(text) { ... }
+}
+```
+
+`ai-plugin` 通过 `provider-registry` 适配多种后端（Anthropic / OpenAI / DeepSeek / OpenAI-Compat），把"如何选 provider"的逻辑从 `agent-chat.js` 移到这里。
+
+### 7.6 CLI 重整
+
+- 删除 `chat-ui-old.js`（469 行）
+- 删除 `cli/src/daemon.js`（与 `commands/daemon.js` 重名）
+- `cli/src/` 整目录移到 `src/cli/`
+- 命令分派改成 commander / yargs 等成熟库
+
+## 8. 命名与编码规范
+
+| 类别 | 规则 | 示例 |
+|---|---|---|
+| 文件名 | kebab-case | `chat-session.js` |
+| 类名 | PascalCase | `SessionManager` |
+| 公开方法 | camelCase | `createAgent` |
+| 私有方法 | `_camelCase` | `_registerListeners` |
+| 插件目录 | 单数名词 | `plugins/messaging/email/` |
+| 插件入口 | `index.js` | — |
+| 命名空间常量 | UPPER_SNAKE | `LOG_LEVELS` |
+| 测试文件 | `<unit>.test.js` | `framework.test.js` |
+| 临时/实验文件 | 不进 `examples/`，改 `sandbox/` | — |
+
+## 9. 公共 API 门面
+
+新建 `src/index.js`（替换旧的 25 行文件）：
+
+```js
+// src/index.js
+'use strict';
+
+const { Framework } = require('./framework');
+const { createAgent } = require('./agent');
+const { bootstrap } = require('./framework/lifecycle');
+
+// === 入门三件套 ===
+exports.bootstrap = bootstrap;                  // 加载 .foliko 配置并启动
+exports.createAgent = createAgent;              // 显式构造 Agent
+exports.createApp = createApp;                  // 构造一个未启动的 Framework
+
+// === 工具 ===
+exports.registerTool = ...;                     // 全局工具快捷注册
+exports.use = use;                              // app.use(plugin/trait)
+
+// === 上下文 ===
+exports.runInSession = runInSession;
+exports.runInRequest = runInRequest;
+
+// === 常用插件快捷注册 ===
+exports.withAI = withAI;                        // 链式 app.use(withAI({...}))
+exports.withShell = withShell;
+exports.withPython = withPython;
+
+// === 类型/常量 ===
+exports.z = require('zod');
+exports.LLM = require('./llm');                // Provider 枚举
+```
+
+### 9.1 "3 行启动"示例
+
+```js
+// examples/01-basic.js
+const foliko = require('foliko');
+const agent = await foliko.bootstrap();
+const reply = await agent.chat('你好');
+```
+
+```js
+// examples/03-custom-tool.js
+const foliko = require('foliko');
+const { z } = foliko;
+
+const app = foliko.createApp()
+  .use(foliko.withAI({ provider: 'deepseek', apiKey: 'sk-xxx' }));
+app.tool({
+  name: 'sum',
+  input: z.object({ a: z.number(), b: z.number() }),
+  execute: async ({ a, b }) => ({ result: a + b }),
+});
+
+const agent = await app.start();
+const reply = await agent.chat('3 + 5 等于几？');
+```
+
+## 10. 迁移策略
+
+> **原则**：始终保持 `main` 可跑，每一步可单独发布 minor 版本。
+
+### Phase 0：项目初始化与基线（1 周）
+
+- 在 `D:\date\20260624\foliko` 初始化 git
+- 从 `D:\code\vb-agent` 同步源码（跳过 `node_modules` / `.git` / `xhs_auth.json` / `system.md`）
+- 加 `vitest` 依赖
+- 写 3 个 smoke test：`framework.createAgent` / `agent.chat` / 工具调用
+- 跑通 `npm start` 确认基线
+
+**验收**：3 个 smoke test 全绿，`npm start` 行为与源仓库一致。
+
+### Phase 1：建新目录骨架与 compat 兼容层（半周）
+
+- 创建所有新目录占位
+- 新位置放空文件 + `index.js` barrel export
+- `src/compat/` 转发旧路径并加 deprecation warning
+- 验证所有 examples 仍可跑
+
+**验收**：旧代码 `require('foliko/src/core/framework')` 仍可工作（带 warning）。
+
+### Phase 2：拆分 common/ 与 config/（1 周）
+
+- 迁移 `logger.js`、`errors.js`、`events.js`、`retry.js`、`id.js`、`queue.js`、`circuit.js`、`diff.js` 到 `src/common/`
+- 迁移 `env.js`、`foliko.js`、`plugin-config.js` 到 `src/config/`
+- 改内部引用，旧路径 compat 转发
+
+**验收**：`npm start` 行为不变，单元测试覆盖 logger / retry / id。
+
+### Phase 3：重整 context/ 与 session/（1.5 周）
+
+- 5 个上下文/会话相关文件按 `src/context/`、`src/session/` 归位
+- 合并 `context-compressor.js` + `enhanced-context-compressor.js`
+- 抽 `ContextStorage` 单例
+- 新加单测覆盖三层隔离
+
+**验收**：所有 examples 通过；context 隔离有专门测试。
+
+### Phase 4：拆分 agent/ 为 BaseAgent 体系（1 周）
+
+- 提取 `BaseAgent` 公共基类
+- 子类化 `MainAgent` / `SubAgent` / `WorkerAgent`
+- `framework.createAgent` 保持签名，行为通过现有 smoke test
+- `createSessionAgent` 简化为 `createAgent({ sessionId })`
+
+**验收**：所有 agent 变体的 smoke test 通过；新增 BaseAgent 单测。
+
+### Phase 5：拆分 framework/ 核心 5 文件（1.5 周）
+
+- 1422 行 `framework.js` → 5 个文件
+- `rescanProject` 重构为组合调用
+- `createFrameworkLogger` 移到 `common/logger`
+
+**验收**：framework 集成测试通过；`setCwd` / `rescanProject` 路径覆盖。
+
+### Phase 6：LLM / Tool / Plugin 体系抽象（2 周）
+
+- 抽象 `LLMProvider` 接口
+- `ai-plugin` 改为基于 `provider-registry`
+- 合并 `provider.js` + `provider-registry.js`
+- 重组 `tool-registry` + `tool-executor` + `tool-router`
+- `plugin` 系统抽 `loader`
+
+**验收**：所有 AI 后端切换测试通过；tool 路由有专门测试。
+
+### Phase 7：插件目录化与死代码清理（2 周）
+
+- 按 `core / executors / io / messaging / memory / ambient / install / trading` 八大类迁移 30+ 插件
+- 每个插件加 `README.md`（用途、配置、依赖）
+- 删除 `chat-ui-old.js`、`cli/src/daemon.js`、注释老代码
+- 整理 `examples/`：8 个 `test-*.js` 移到 `sandbox/`
+
+**验收**：所有插件在新位置加载成功；compat 仍能加载旧路径。
+
+### Phase 8：公共 API 门面 + 文档（1 周）
+
+- 实现 `src/index.js` 门面（`bootstrap` / `createAgent` / `createApp` / `withAI` 等）
+- 写 `docs/public-api.md`、`docs/migration.md`、`docs/architecture.md`
+- `compat/` 维护到下一个 major 版本
+
+**验收**：examples/01~10 全部基于新门面跑通；migration.md 覆盖所有旧路径。
+
+### 10.1 时间表
+
+| Phase | 周期 | 累计 |
+|---|---|---|
+| 0 | 1 周 | 1 周 |
+| 1 | 0.5 周 | 1.5 周 |
+| 2 | 1 周 | 2.5 周 |
+| 3 | 1.5 周 | 4 周 |
+| 4 | 1 周 | 5 周 |
+| 5 | 1.5 周 | 6.5 周 |
+| 6 | 2 周 | 8.5 周 |
+| 7 | 2 周 | 10.5 周 |
+| 8 | 1 周 | 11.5 周 |
+
+总周期 ~10~12 周，可分 3~4 个 milestone 发布。
+
+## 11. 风险与缓解
+
+| 风险 | 缓解 |
+|---|---|
+| 行为回归（context / agent 拆分最容易改语义） | Phase 0 起的 smoke test + 每个 Phase 跑全部 example |
+| 插件作者引用了 `plugins/xxx-plugin.js` 路径 | `compat/` 转发 + `migration.md` 列出所有改动 |
+| 单测覆盖不足 | 先 end-to-end 行为锚点，再逐步加单元；先核心后边缘 |
+| 重构与新功能并行 | 重构期间不接大需求；小修小补用 branch 隔离 |
+| Ambient Agent / 邮件等大插件（>500 行）拆分困难 | 单文件插件可保留 `index.js` 主文件，子模块放同目录 `*.js` |
+| 上下文 AsyncLocalStorage 切换引入竞态 | Phase 3 阶段保留新旧两套并跑 1 周再切换默认路径 |
+
+## 12. 度量指标
+
+- **代码质量**：单文件 ≤ 400 行；单类公开方法 ≤ 8 个
+- **覆盖率**：核心模块（framework / agent / context / session）≥ 70%
+- **公共 API 稳定性**：Phase 8 后 `src/index.js` 导出符号 ≤ 15 个
+- **可读性**：每个目录有 `README.md` 解释职责
+- **运行时间**：从 `npm install` 到 `npm start` 可用 ≤ 2 分钟（CI 中验证）
+
+## 13. 后续文档
+
+重构过程中会持续输出：
+
+- `docs/architecture.md`：整体架构图与数据流
+- `docs/public-api.md`：对外 API 速查
+- `docs/context-system.md`：三层上下文详解
+- `docs/plugin-dev.md`：插件开发指南
+- `docs/mcp.md`：MCP 集成
+- `docs/migration.md`：旧路径 → 新路径迁移对照表
+
+---
+
+> **本文件作为重构的权威参考，所有 Phase 执行过程中如发现与方案不一致，须先更新本文件再动代码。**