# nanoPencil 重构计划

> 版本：v1.0
> 日期：2026-03-11

---

## 一、项目愿景与目标

### 1.1 愿景声明

将 nanoPencil 打造成一个**轻量化内核 + 高度可扩展**的 AI 编程助手，具备以下核心特征：

- **轻量化内核**：核心代码库（core/）保持精简，仅包含支撑基础 Agent 能力所必需的模块
- **内核稳定**：核心模块经充分验证后保持 API 稳定，不随功能迭代频繁变更
- **超强扩展性**：所有非核心能力通过扩展机制提供，第三方可低成本构建扩展
- **自我进化能力**：在安全边界内支持 Agent 自我修改和演进

### 1.2 量化目标

| 指标 | 当前状态 | 目标状态 |
|------|----------|----------|
| AgentSession 直接依赖模块数 | 15+ | ≤ 8 |
| core/ 目录非核心模块数 | 2+ | 0 |
| 扩展可替代模块数 | - | ≥ 3（Soul、Export-HTML、MCP） |
| 核心与扩展代码行数比 | - | ≤ 1:2 |

---

## 二、现状分析

### 2.1 当前架构概览

nanoPencil 采用 monorepo 结构，主要组成部分：

```
nanoPencil/
├── packages/          # 子包（agent-core, ai, tui, nano-mem, soul 等）
├── core/              # 核心逻辑（AgentSession、工具、compaction 等）
├── modes/             # 运行模式（Interactive/Print/RPC）
├── extensions/        # 内置扩展（link-world、simplify、security-audit）
├── cli/               # CLI 辅助
└── utils/             # 工具函数
```

### 2.2 核心问题诊断

#### 问题 1：AgentSession 职责过重（God Object）

AgentSession 承担了会话管理、模型切换、工具编排、compaction 协调、扩展绑定、Soul 集成、HTML 导出等全部功能，直接依赖 15+ 个内部模块。

**影响**：
- 任何子系统修改都可能波及 AgentSession
- 难以单独测试某一子系统
- 新开发者理解成本高

#### 问题 2：Soul 相关包三重冗余

`packages/` 下存在 `soul`、`nanosoul`、`agent-soul` 三个包，职责高度重叠，均为"AI 人格进化引擎"。

**影响**：
- 维护成本翻倍
- 使用者和贡献者困惑
- 构建和依赖链条冗余

#### 问题 3：Soul 硬编码在核心层

`core/soul-integration.ts` 将 Soul 的初始化、system prompt 注入、会话结束时的人格更新等逻辑直接放在核心层。

**影响**：
- 非 Soul 用户承担不必要的代码加载
- 难以替换为其他人格系统实现

#### 问题 4：命名与职责不匹配

- `pencil-mem-integration.ts`：实际职责是"返回内置扩展路径列表"，但名称暗示仅与 nanomem 相关
- `nanopencil-defaults.ts`：混合了产品默认配置与扩展路径管理职责

#### 问题 5：system-prompt 静态化

工具使用指南（guidance）直接硬编码在 `core/system-prompt.ts` 中，新增工具必须修改该文件。

#### 问题 6：export-html 放在核心层

`core/export-html/` 包含 HTML 模板、CSS、JS、vendor 依赖，体积较大但并非核心必需功能。

#### 问题 7：utils/ 缺乏归属

13 个工具函数文件，缺乏清晰的依赖方向划分。

#### 问题 8：扩展接入层次混杂

默认扩展与可选扩展未做区分，`packages/nano-mem` 这类能力同时承担了“核心引擎”和“产品扩展适配”两种职责；Soul 也存在类似问题。结果是 `packages/`、`core/`、`extensions/` 三层边界被打穿，不利于贯彻“最小核心、最大扩展性”。

---

## 三、重构原则

### 3.1 核心 / 扩展边界判定模型

**核心纳入条件**（满足 2+ 项）：
- **必需性**：90%+ 用户在绝大多数会话中都会用到
- **紧密耦合**：需要访问 AgentSession、会话树、compaction 结果等内部结构
- **配置驱动**：必须写入全局/项目配置，影响启动流程

**扩展纳入条件**（满足 1+ 项）：
- **可选性**：不影响"能不能用"，只影响"好不好用"
- **可替换性**：存在多种同类实现
- **外部依赖**：引入较重第三方库、系统依赖或外部服务

### 3.2 重构纪律

1. **渐进式重构**：每完成一项验证功能完整性后再进入下一项
2. **向后兼容**：扩展 API、CLI 接口、配置格式保持不变
3. **功能完整**：不删除任何现有功能，仅调整内部归属
4. **充分测试**：关键模块拆分后需有集成测试覆盖

### 3.3 扩展接入模式（新增）

所有高级能力统一采用 **“`*-core` + extension adapter” 双层接入模式**：

- `packages/*-core`：放置宿主无关的领域模型、算法、存储、管理器等可复用能力
- `extensions/*`：放置与 NanoPencil 扩展 API 绑定的适配层，负责生命周期事件桥接、命令注册、工具注册、prompt 注入
- `builtin-extensions.ts`：仅作为**内置扩展注册表 / manifest**，负责声明哪些扩展存在、是否默认启用、入口路径在哪里；不承载具体业务适配逻辑

**依赖规则**：

- `core/` 不直接依赖 `mem-core`、`soul-core` 等高级能力库
- `extensions/*` 可以依赖 `packages/*-core`
- `builtin-extensions.ts` 只做声明式管理，不写 Soul / Memory / 未来 `xxx-core` 的具体集成逻辑
- 新增高级能力时，优先新增 `packages/xxx-core` + `extensions/<group>/xxx/`，而不是进入 `core/`

---

## 四、重构阶段与任务

### 阶段一：消除冗余、澄清命名

**目标**：清理明显冗余，使命名与职责匹配

| 任务 | 动作 | 影响范围 | 依赖 |
|------|------|----------|------|
| P1-1 | 废弃 `packages/nanosoul`、`packages/agent-soul`，保留 `packages/soul` | packages/ | 无 |
| P1-2 | 重命名 `pencil-mem-integration.ts` → `builtin-extensions.ts` | 根目录 | 无 |
| P1-3 | 收窄 `nanopencil-defaults.ts` 职责，仅负责产品默认配置 | 根目录 | 无 |

**验收标准**：
- packages/ 下仅保留一个 soul 包
- 内置扩展路径管理明确归口到 `builtin-extensions.ts`
- `nanopencil-defaults.ts` 不再包含扩展路径相关代码

---

### 阶段二：Soul 迁移至扩展层

**目标**：将 Soul 从核心层迁移为标准扩展，实现核心与可选人格系统的解耦；Soul 作为“外置大脑”存在，NanoPencil 仅通过扩展适配层接入

| 任务 | 动作 | 影响范围 | 依赖 |
|------|------|----------|------|
| P2-1 | 将 `core/soul-integration.ts` 改写为标准扩展 `extensions/defaults/soul/` | core/、extensions/ | P1-1 |
| P2-2 | 简化 `core/sdk.ts`，移除 Soul 初始化分支 | core/sdk.ts | P2-1 |
| P2-3 | 将 settings 中的 `disable-soul` 开关改为控制扩展加载 | settings | P2-2 |

**技术要点**：
- 利用现有扩展事件：`before_agent_start`（注入 prompt）、`agent_end`（人格更新）
- 如现有扩展 API 有缺口，需先补全再迁移
- 保留配置迁移路径，现有用户配置无需变更
- Soul 具体逻辑归入 `packages/soul-core`，扩展层只保留 NanoPencil 适配代码

**验收标准**：
- `core/soul-integration.ts` 不再存在
- `core/sdk.ts` 启动流程不再包含 Soul 特殊处理
- 用户可通过设置关闭 Soul 扩展

---

### 阶段三：AgentSession 职责拆分

**目标**：将 AgentSession 从 God Object 拆分为多个职责清晰的协调者

| 任务 | 动作 | 影响范围 | 依赖 |
|------|------|----------|------|
| P3-1 | 抽取 `CompactionCoordinator`：封装 compaction 触发判断、执行、结果处理 | core/ | P2-2 |
| P3-2 | 抽取 `ToolOrchestrator`：封装工具注册、查找、执行、包装（扩展 hook） | core/ | P3-1 |
| P3-3 | 抽取 `ModelSwitcher`：封装模型切换、cycling、fallback 逻辑 | core/ | P3-2 |
| P3-4 | AgentSession 瘦身：只保留生命周期管理、事件协调、对外 API | core/agent-session.ts | P3-3 |

**架构设计**：

```
AgentSession (瘦身后)
├── 生命周期：init, run, pause, resume, end
├── 事件协调：事件总线分发、扩展 hook 触发
├── 对外 API：sendMessage, getSessionInfo, 状态查询
│
├── CompactionCoordinator (新增)
│   ├── 触发条件判断
│   ├── 执行编排
│   └── 结果处理
│
├── ToolOrchestrator (新增)
│   ├── 工具注册表管理
│   ├── 工具查找与匹配
│   ├── 执行管道（前置 hook → 执行 → 后置 hook）
│   └── 工具来源统一（内置/MCP/扩展）
│
└── ModelSwitcher (新增)
    ├── 模型选择策略
    ├── 切换执行
    ├── 失败fallback
    └── 状态同步
```

**验收标准**：
- AgentSession 直接依赖模块数降至 ≤ 8
- 各 Coordinator 可独立测试
- AgentSession 代码行数减少 ≥ 40%

---

### 阶段四：system-prompt 动态化

**目标**：实现工具 guidance 的动态聚合，消除硬编码

| 任务 | 动作 |影响范围 | 依赖 |
|------|------|---------|------|
| P4-1 | `core/tools/*.ts` 每个工具增加 `guidance` 字段 | core/tools/ | P3-4 |
| P4-2 | `core/system-prompt.ts` 改为动态聚合工具 guidance | core/system-prompt.ts | P4-1 |
| P4-3 | `core/extensions/types.ts` 的 `ToolDefinition` 增加 `guidance` 字段 | core/extensions/ | P4-2 |

**技术要点**：
- guidance 字段为可选，默认为空字符串
- system-prompt 构建时按优先级截断超长内容
- 支持多语言 guidance（通过扩展实现 i18n）

**验收标准**：
- 新增工具无需修改 system-prompt.ts
- 扩展注册的工具也能携带 guidance
- 动态聚合结果与原有硬编码等效

---

### 阶段五：export-html 迁移

**目标**：将 HTML 导出功能从核心迁至扩展层

| 任务 | 动作 | 影响范围 | 依赖 |
|------|------|----------|------|
| P5-1 | 将 `core/export-html/` 改写为内置扩展 `extensions/export-html/` | core/、extensions/ | P3-4 |
| P5-2 | 从 `core/agent-session.ts` 移除 `exportToHtml` 方法 | core/agent-session.ts | P5-1 |

**技术要点**：
- 利用扩展的 `commands` 机制注册 `/export` 命令
- 扩展通过 `ExtensionContext.sessionManager` 访问完整会话消息历史
- 保持现有 HTML 输出格式不变

**验收标准**：
- `core/export-html/` 不再存在
- `/export` 命令功能保持不变
- 可通过扩展机制扩展导出格式（如 PDF、Markdown）

---

### 阶段六：MCP 抽象化

**目标**：将 MCP 抽象为"工具源 + 扩展适配"模式，使核心与外部工具协议解耦，并将具体协议实现迁出 core/

| 任务 | 动作 | 影响范围 | 依赖 |
|------|------|----------|------|
| P6-1 | 定义 `ToolSource` 接口，抽象"工具来源"概念 | `core/tools/` | P5-1 |
| P6-2 | 将 MCP 协议适配实现迁至 `extensions/defaults/mcp/`，通过 adapter 暴露 ToolSource | extensions/ | P6-1 |
| P6-3 | `core/runtime/sdk.ts` 通过 `ToolSource` 统一注册所有来源的工具 | core/ | P6-2 |

**接口设计**：

```typescript
interface ToolSource {
  id: string;
  type: 'builtin' | 'mcp' | 'extension';
  load(): Promise<ToolDefinition[]>;
  unload(): Promise<void>;
}
```

**验收标准**：
- 新增工具源类型不影响核心代码
- MCP 不再驻留于 `core/`，而是以默认扩展形态接入
- ToolOrchestrator 通过 ToolSource 统一管理

---

### 阶段七：utils 归类

**目标**：明确 utils 目录的归属，消除模糊地带

| 任务 | 动作 | 影响范围 | 依赖 |
|------|------|----------|------|
| P7-1 | 将 `utils/shell`、`sleep`、`tools-manager` 迁移至 `core/utils/` | core/、utils/ | P6-3 |
| P7-2 | 将 `utils/clipboard*`、`image*` 迁移至 `modes/utils/` | modes/、utils/ | P7-1 |
| P7-3 | 保留 `utils/mime`、`frontmatter` 在顶层 `utils/` | utils/ | P7-2 |

**验收标准**：
- utils/ 目录依赖方向清晰
- core/ 专用的 utils 不再放在顶层
- modes/ 专用的 utils 归口到 modes/

---

## 五、目标架构（子域拆分版）

### 5.1 目录结构

```
nanoPencil/
├── cli.ts                          # CLI 入口
├── main.ts                         # 主入口
├── index.ts                        # SDK 导出
├── config.ts                       # 路径配置
├── nanopencil-defaults.ts          # 产品默认模型/配置（已收窄职责）
├── builtin-extensions.ts           # 内置扩展注册表（manifest + 路径解析）
│
├── core/
│   ├── runtime/                    # 运行时内核（最小不可分割单元）
│   │   ├── agent-session.ts        # 会话生命周期 + 事件协调 + 对外 API
│   │   ├── event-bus.ts            # 事件总线
│   │   └── sdk.ts                  # 引导启动（工厂函数）
│   │
│   ├── extensions/                 # 扩展运行时
│   │   ├── loader.ts
│   │   ├── runner.ts
│   │   ├── types.ts
│   │   └── wrapper.ts
│   │
│   ├── tools/                      # 工具框架 + 内置工具
│   │   ├── orchestrator.ts         # [新] 工具编排 + ToolSource 接口
│   │   ├── bash.ts                 # 内置工具
│   │   ├── bash-executor.ts        # bash 执行引擎
│   │   ├── read.ts, write.ts, edit.ts, grep.ts, find.ts, ls.ts
│   │   └── truncate.ts
│   │
│   ├── model/                      # 模型管理
│   │   ├── registry.ts             # 模型注册表
│   │   ├── switcher.ts             # [新] 切换 + fallback
│   │   └── resolver.ts             # 模型解析
│   │
│   ├── session/                    # 会话持久化 + 上下文管理
│   │   ├── manager.ts              # 会话持久化
│   │   ├── compaction-coordinator.ts  # [新] compaction 编排
│   │   └── compaction/             # compaction 算法
│   │
│   ├── config/                     # 配置基础设施
│   │   ├── settings-manager.ts
│   │   ├── auth-storage.ts
│   │   └── resource-loader.ts
│   │
│   └── prompt/                     # Prompt 构建
│       └── system-prompt.ts        # 动态聚合工具 guidance
│
├── modes/
│   ├── interactive/                # 不变
│   ├── print-mode.ts               # 不变
│   ├── rpc/                        # 不变
│   └── utils/                      # [新] modes 专用 utils
│
├── extensions/
│   ├── defaults/                   # 默认扩展（默认启用）
│   │   ├── nano-mem/               # 记忆扩展适配层（外置大脑入口）
│   │   ├── soul/                   # 人格扩展适配层（外置大脑入口）
│   │   ├── link-world/             # 联网搜索
│   │   ├── security-audit/         # 安全审计
│   │   └── mcp/                    # [新] MCP 协议适配（从 core/mcp/ 迁出）
│   ├── optional/                   # 可选扩展
│   │   ├── simplify/               # 代码简化
│   │   └── export-html/            # [新] HTML 导出
│
├── packages/
│   ├── agent-core/                 # 不变
│   ├── ai/                         # 不变
│   ├── tui/                        # 不变
│   ├── mem-core/                   # 记忆核心库（算法/存储/管理器，宿主无关）
│   └── soul-core/                  # Soul 核心库（演化/注入/管理器，宿主无关）
│
├── cli/                            # 不变
├── utils/                          # 瘦身后：仅保留通用工具
└── docs/
```

### 5.2 core/ 子域职责一览

| 子域 | 文件数 | 职责 | 变更频率 |
|------|--------|------|----------|
| `runtime/` | 3 | 会话生命周期、事件总线、引导启动 | 极低（内核稳定后几乎不改） |
| `extensions/` | 4 | 扩展加载、运行、类型、包装 | 低 |
| `tools/` | ~10 | 工具编排框架 + 内置工具实现 | 中（新增工具时扩展） |
| `model/` | 3 | 模型注册、切换、解析 | 低 |
| `session/` | 3+子目录 | 会话持久化、compaction | 低 |
| `config/` | 3 | 配置、认证、资源加载 | 低 |
| `prompt/` | 1 | system prompt 动态构建 | 低 |

打开 `core/` 后看到 7 个子域目录（而非 19 个混杂条目），新人可在 5 秒内定位要改的领域。

### 5.3 模块依赖关系

```
                    ┌───────────────────────────────────────────┐
                    │        core/runtime/agent-session         │
                    │   (生命周期 + 事件协调 + 对外 API)          │
                    └──────────────────┬────────────────────────┘
                                       │
         ┌─────────────────────────────┼─────────────────────────────┐
         │                             │                             │
         ▼                             ▼                             ▼
┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│ core/session/       │    │ core/tools/         │    │ core/model/         │
│ compaction-         │    │ orchestrator        │    │ switcher            │
│ coordinator         │    │ (ToolSource 接口)    │    │ registry            │
└─────────┬───────────┘    └─────────┬───────────┘    └─────────┬───────────┘
          │                          │                          │
          │                ┌─────────┴──────────┐               │
          │                ▼                    ▼               │
          │        ┌──────────────┐    ┌──────────────┐         │
          │        │ Builtin      │    │ Extension    │         │
          │        │ Tools        │    │ ToolSource   │         │
          │        └──────────────┘    └──────┬───────┘         │
          │                                   │                 │
          │         ┌─────────────────────────┘                 │
          │         ▼                                           │
          │  ┌─────────────────────────────────────┐            │
          │  │        extensions/ (adapters)        │            │
          │  │  defaults: mem, soul, mcp, ...       │            │
          │  │  optional: simplify, export-html     │            │
          │  └──────────────┬──────────────────────┘            │
          │                 │                                    │
          │                 ▼                                    │
          │  ┌─────────────────────────────────────┐            │
          │  │        packages/*-core              │            │
          │  │  mem-core, soul-core                │            │
          │  │  (宿主无关的能力本体)                  │            │
          │  └─────────────────────────────────────┘            │
          │                                                     │
          ▼                                                     ▼
   ┌─────────────┐                                   ┌──────────────────┐
   │ core/session│                                   │ core/config/     │
   │ compaction/ │                                   │ settings-manager │
   │ (算法层)     │                                   │ auth-storage     │
   └─────────────┘                                   └──────────────────┘
```

### 5.4 分层职责与依赖规则

- `core/runtime/`：最小内核，仅 3 文件，稳定后几乎不改
- `core/` 其它子域：内核必要基础设施，按领域独立演进
- `builtin-extensions.ts`：统一管理“有哪些内置扩展”，不写具体业务集成逻辑
- `extensions/*`：每个扩展各自持有 adapter，负责把宿主事件映射到对应的 `*-core`
- `packages/*-core`：能力本体，保持宿主无关，可被其他宿主或未来产品复用

**明确禁止**：

- `core/` 直接 import `mem-core`、`soul-core`
- `builtin-extensions.ts` 直接实现 Soul / Memory / 未来 `xxx-core` 的业务桥接
- 将高级能力重新塞回 `core/`，破坏“最小核心、最大扩展性”

---

## 六、风险与注意事项

### 6.1 高风险项

| 风险 | 描述 | 缓解措施 |
|------|------|----------|
| AgentSession 拆分 | 涉及面广，是最大风险项 | 放在最后阶段执行，需充分集成测试覆盖 |
| Soul 迁移为扩展 | 需确保扩展 API 能完整支持 Soul 当前所有行为 | 先补全扩展 API 缺口，再执行迁移 |
| export-html 迁移 | 需确保扩展可以访问完整的会话消息历史 | 验证 ExtensionContext.sessionManager 可用性 |

### 6.2 中风险项

| 风险 | 描述 | 缓解措施 |
|------|------|----------|
| system-prompt 动态化 | 动态聚合时需处理 prompt 长度预算 | 设计截断/优先级策略 |
| MCP 抽象化 | 短期可能增加代码复杂度 | 保持向后兼容，逐步迁移 |

### 6.3 实施注意事项

1. **每阶段独立验证**：完成一项后运行完整测试，确认功能无损再进入下一项
2. **保留迁移脚本**：配置迁移、用户数据迁移需提供平滑路径
3. **文档同步更新**：重构完成后同步更新 README、API 文档
4. **版本号策略**：重大重构完成后考虑升级主版本号

---

## 七、验收标准

### 7.1 完成标准

| 阶段 | 验收条件 |
|------|----------|
| 阶段一 | 命名清晰，无冗余包；所有相关引用已更新 |
| 阶段二 | Soul 功能完整迁移至扩展；disable-soul 配置生效 |
| 阶段三 | AgentSession 直接依赖 ≤ 8 个模块；各 Coordinator 可独立测试 |
| 阶段四 | 新增工具无需修改 system-prompt.ts；动态聚合结果正确 |
| 阶段五 | /export 命令功能保持不变；可扩展导出格式 |
| 阶段六 | ToolSource 接口稳定；MCP 通过接口加载 |
| 阶段七 | utils 依赖方向清晰；无循环依赖 |

**额外架构验收项**：

- `builtin-extensions.ts` 仅承担注册表职责，不包含 Soul / Memory 的业务适配逻辑
- Soul / Memory 始终以 extension 形态接入，而不是重新回流到 `core/`
- `packages/mem-core`、`packages/soul-core` 可独立测试，且不依赖 NanoPencil 的 `ExtensionAPI`

### 7.2 回归测试清单

- [ ] 基础对话流程正常
- [ ] 文件读写编辑工具正常
- [ ] Bash 执行工具正常
- [ ] 模型切换正常
- [ ] 扩展加载/卸载正常
- [ ] 内置扩展（link-world、security-audit、nano-mem）正常
- [ ] 会话持久化正常
- [ ] compaction 触发和执行正常
- [ ] 三种运行模式（Interactive/Print/RPC）正常
- [ ] 配置读取/写入正常

---

## 八、后续演进路线

### 8.1 阶段 1 完成后的架构能力

重构完成后，项目将具备以下架构能力：

1. **最小核心**：`core/runtime/` 收敛为 3 文件，其余基础设施按子域组织
2. **最大扩展性**：所有高级能力通过扩展提供
3. **清晰边界**：核心与扩展职责边界明确
4. **可测试性**：各模块可独立单元测试

### 8.2 下一阶段演进方向

#### 方向一：扩展协议与生态建设

- 固化扩展 API 类型签名
- 设计 `extension.json` manifest 规范
- 提供扩展模板脚手架
- 建立扩展市场/社区机制

#### 方向二：自我进化轨道

- 实现 `self_edit` / `self_eval` 工具
- 设计变更提案协议
- 与 git 集成实现版本控制
- 建立安全边界和权限模型

#### 方向三：高级特性

- 多模型协同支持
- 协同 Agent / 审阅 Agent
- 性能分析 Agent
- MCP 服务器生态集成

---

## 九、附录

### 附录 A：任务总览

| 阶段 | 任务数 | 关键文件变更 |
|------|--------|--------------|
| P1 消除冗余、澄清命名 | 3 | packages/, 根目录 |
| P2 Soul 迁移至扩展层 | 3 | core/soul-integration.ts, core/sdk.ts |
| P3 AgentSession 职责拆分 | 4 | core/agent-session.ts |
| P4 system-prompt 动态化 | 3 | core/tools/, core/system-prompt.ts |
| P5 export-html 迁移 | 2 | core/export-html/, extensions/ |
| P6 MCP 抽象化 | 3 | core/tools/, extensions/defaults/mcp/, core/runtime/sdk.ts |
| P7 utils 归类 | 3 | core/utils/, modes/utils/, utils/ |

**总计：21 个任务**

### 附录 B：术语表

| 术语 | 定义 |
|------|------|
| AgentSession | 会话管理器，负责 Agent 循环、状态管理、工具执行 |
| Compaction | 上下文压缩，负责 token 预算管理、摘要生成 |
| ToolOrchestrator | 工具编排器，负责工具注册、查找、执行 |
| ModelSwitcher | 模型切换器，负责模型选择、切换、fallback |
| ToolSource | 工具来源接口，抽象内置/MCP/扩展等工具来源 |
| Guidance | 工具使用指南，描述工具的正确使用方法 |
| Extension | 扩展，提供可选功能的插件机制 |

---

*本文档与 `架构演进.md`、`架构优化.md` 配合阅读。*
