## nanoPencil 架构演进与自我进化说明

本文在 `docs/版本2.md` 的基础上，从专业架构师视角，对 **core / extensions 边界**、**自我进化能力** 和 **演进路线图** 进行系统化梳理，作为后续设计、开发和评审的架构依据。

---

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

### 1.1 主项目 `core/` 收纳条件（满足任意 2+ 即可）

- **必需性（必备体验）**
  - 没有它，agent 无法完成“基础编码对话 + 文件操作 + 运行命令”等核心任务。
  - 90%+ 用户在绝大多数会话中都会用到。

- **紧密耦合（强依赖核心状态）**
  - 需要访问 `AgentSession`、会话树、compaction 结果、会话元数据等内部结构。
  - 会显著影响 token 预算、上下文构造策略或状态持久化策略。

- **配置驱动（全局配置影响启动流程）**
  - 必须写入 `~/.nanopencil/agent/` 或 `.pi/settings.json` 等全局/项目配置。
  - 会改变模型选择、鉴权、启动模式、资源加载策略等。

### 1.2 扩展 `extensions/` 收纳条件（满足任意 1+ 即可）

- **可选性**
  - 不影响“能不能用”，只影响“好不好用 / 适不适配场景”。
  - 典型场景：数据库、浏览器、CI 集成、特定语言框架辅助等。

- **可替换性**
  - 市场上/社区中存在多种“同类能力”实现（例如不同 MCP 服务器、不同 LSP、不同 test runner）。
  - 用户可能基于成本、性能、隐私等选择不同实现。

- **外部依赖**
  - 引入较重第三方库、系统依赖或外部服务，安装成本高。
  - 大概率只有少数用户群体需要。

### 1.3 判定流程（决策树）

从“新能力需求”出发，按顺序判断：

1. **是否基础 Agent 能力？**
   - 如：读写文件、编辑补丁、执行 shell、grep 搜索。
   - **YES → `core/tools/` 或对应核心子系统。**

2. **是否需要强耦合会话状态？**
   - 如：需要访问内部对话树、compaction 历史、分支信息等。
   - **YES → 进一步判断：**
     - 强耦合、不可抽象为通用 Hook → **进入 `core/`**  
     - 能抽象为扩展 Hook（在 extension context 中暴露必要的只读视图）→ **进入 `extensions/`**

3. **是否引入外部服务/库？**
   - 如：数据库、浏览器、第三方 API、MCP、CI/CD、云存储等。
   - **YES → `extensions/`**

4. **适用用户比例是否 < 50%？**
   - 面向特定语言栈 / 特殊场景（嵌入式、游戏引擎、特定云厂商等）。
   - **YES → `extensions/`**

5. 若以上都不明显：
   - 作为 **“默认扩展”** 处理：实现为扩展，放在 `extensions/`，但在默认配置中启用，可一键关闭。

---

## 2. 目标架构结构（演进版目录蓝图）

### 2.1 核心目录建议

- **`core/tools/`**
  - `read.ts`, `write.ts`, `edit.ts`, `bash.ts`, `grep.ts`
  - `search.ts`（对 `grep` 的高阶封装，面向“语义 + 结构感知”增强）
  - 未来可能增加：`test.ts` 或 `core/testing/`（统一测试运行抽象）

- **`core/session-manager.ts`**
  - 负责会话树、分支、迁移、持久化。

- **`core/compaction/`**
  - 负责 token 预算、摘要、分支总结策略。

- **`core/model-registry.ts`**
  - 管理模型清单、provider 配置、API key 解析。

- **`core/extensions/`**
  - `loader.ts` / `runner.ts` / `wrapper.ts` / `types.ts`
  - 要求：**扩展运行时自身必须足够稳定简洁**，避免“扩展系统本身变成新一层复杂内核”。

### 2.2 扩展目录建议

- **`extensions/defaults/`**
  - `nanomem/`（默认开启，负责长期记忆）
  - `nanosoul/`（默认开启，负责人格/偏好）
  - 特性：逻辑上属于扩展，但视作“系统自带插件”，用户可显式关闭。

- **`extensions/mcp/`**
  - MCP 服务器集成：git、sqlite、http 客户端、浏览器、云服务等。

- **`extensions/integrations/`**
  - GitHub / GitLab、Jira、Notion、飞书、企业微信等第三方服务集成。

- **`extensions/community/`**
  - 社区贡献 & 用户自定义扩展。
  - 建议：增加简单 **manifest 规范**（如 `extension.json`）来描述依赖、能力、兼容版本等元信息。

---

## 3. 关键能力的归属判定（典型场景）

### 3.1 Git 工具

- **判定**：依赖外部 `git` 命令，不是所有用户需要，且已有 MCP Git 实现。
- **结论**：**应在扩展层实现**，优先选择 MCP 方案（例如 `extensions/mcp/git.ts`）。

### 3.2 测试运行器

- **判定**：
  - 单元/集成测试运行，对大部分工程项目都是“核心开发场景”。
  - 需要理解项目结构、读配置（`jest.config`, `vitest.config`, `pytest.ini` 等）。
  - 不一定引入重依赖（可通过 shell 集成现有测试命令）。

- **结论**：
  - 若仅做“shell 封装现有测试命令” → 可以是扩展。
  - 若要做到“跨项目、跨语言一致的测试发现和执行体验” → 更适合进入 **`core/tools/test.ts` 或 `core/testing/`**。
  - 建议：**核心提供最小统一抽象（测试命令执行 + 结果结构化）**，具体框架适配器可通过扩展实现。

### 3.3 数据库操作

- **判定**：强外部依赖（如 sqlite、Postgres driver）、场景特定、占包体。
- **结论**：**放在 `extensions/mcp/sqlite.ts` 等扩展中，不进 core。**

### 3.4 代码搜索增强（超越 grep）

- **判定**：
  - 在代码助手场景下，强搜索/导航能力是核心生产力之一。
  - 基于 `grep` 的语义/结构增强属于自然演进。

- **结论**：**应放在核心 `core/tools/search.ts`**，提供稳定 API；外围的“智能索引服务”（如 LSP server、embeddings 服务）可以由扩展提供。

---

## 4. 自我进化能力的架构支撑

从“自我进化的 AI 助手”视角，核心需要提供以下“轨道”：

### 4.1 元信息与可观测性

- 所有工具调用、扩展调用、compaction、模型切换，都有结构化日志。
- Agent 可以查询“自身结构”和“最近一次修改代码的上下文”。

### 4.2 安全写入轨道

- 明确划分：
  - 可由 Agent 自动修改的区域（如扩展、技能脚本、部分配置）。
  - 必须人工复核的区域（如核心工具、session-manager、compaction 策略）。
- 通过扩展机制暴露“安全编辑入口”（例如 `self_edit` 工具，只允许编辑 `extensions/` 和技能目录下文件）。

### 4.3 回滚与版本控制集成

- 与 git / MCP‑Git 集成，为“自我修改”提供自动 commit、标签与回滚建议。
- 自我演进过程应是“有版本、有解释、可回退”的。

**结论**：  
自我进化的主要实现落点应该在 **扩展层 + 技能层**，核心只提供：

- 稳定的工具 API（读/写/编辑/grep/bash 等）。
- 可观测性与元数据接口。
- 安全边界与权限模型（“能改哪里、能改多少”）。

---

## 5. 演进路线图

### 5.1 阶段 1：核心边界收紧 & 扩展清晰化

- **目标**：让 core 足够小、足够稳定。
- **动作**：
  - 盘点现有 core 模块，按照本说明文档的判定标准做“迁出/保留”决策。
  - 将已引入重量级依赖或强场景需求的逻辑迁到 `extensions/`。
  - 建立“默认扩展列表”（基于 `DEFAULT_EXTENSIONS`，完善为带版本/兼容信息的结构）。

### 5.2 阶段 2：扩展协议与生态

- **目标**：让第三方扩展开发者可以低成本、低风险地构建能力。
- **动作**：
  - 固化 `defineExtension()` 的类型签名和生命周期 hook。
  - 设计简单 manifest（`extension.json`）描述：
    - 扩展 id / 名称 / 版本 / 最低兼容 nanoPencil 版本。
    - 所需权限（读写文件、执行 bash、访问网络等）。
  - 提供 **扩展模板脚手架**（如 `npx nano-pencil create-extension`）。

### 5.3 阶段 3：自我进化轨道

- **目标**：让 nanoPencil 可以在“安全范围内”改造自己。
- **动作**：
  - 在工具层增加：`self_edit` / `self_eval` 等“自我操作工具”，其内部严格限定路径和操作。
  - 设计“变更提案协议”：Agent 生成变更 → 写入提案文件 → 由用户或“审阅 Agent”批准后落地。
  - 与 git 集成，自动为自我修改创建分支和 commit。

### 5.4 阶段 4：高级特性（多模型、协同、多 Agent）

- 基于 `model-registry` 扩展对多 provider、多模型协作的支持。
- 在扩展层引入“协同 Agent” / “审阅 Agent” / “性能分析 Agent”等，不污染核心。

---

## 6. 架构决策清单（用于新增能力评审）

在添加或改造任何能力前，请按顺序回答：

- **是否是基础工具（读/写/执行/搜索/测试核心）？**
- **是否必须访问内部会话状态或影响 compaction / session tree？**
- **是否需要写入全局配置并影响启动流程？**
- **是否引入外部服务或重量级依赖？**
- **目标用户比例预计是否 < 50%？**
- **是否存在多种可替代实现希望由社区/生态共建？**

**决策规则**：

- 若前三个问题中有 2+ 个回答为 YES → **进入核心 `core/`**。
- 若后三个问题中有 2+ 个回答为 YES → **进入扩展 `extensions/`**。
- 介于两者之间 → **默认扩展**：实现为扩展，但在配置中默认启用。

---

## 7. 总结

- 主项目的原则是：**“最小主项目，最大扩展性”**。
- 自我进化的主要舞台在扩展和技能层，核心负责提供稳定轨道和安全边界。
- 本文可作为后续新增能力、重构和社区扩展评审时的统一判断基准。

