# Zettelkasten 第二记忆系统 - 技术选型与路线图

## 一、关键技术选型

### 1. 数据库选型

| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| **复用现有 SQLite** | 无需额外依赖，与 OpenClaw 一致，简单可靠 | 大规模图查询性能有限 | ⭐⭐⭐⭐⭐ |
| SQLite + 图数据库 (如 neo4j) | 图查询性能优秀 | 引入新依赖，增加复杂度 | ⭐⭐ |
| PostgreSQL + pgvector | 功能强大，扩展性好 | 需要额外部署 | ⭐⭐⭐ |

**决策**: 复用现有 SQLite
- 理由：OpenClaw 已有成熟的 SQLite 基础设施，包括 FTS5 和 sqlite-vec
- 图查询通过 SQL + 应用层算法实现，初期数据量不大时完全够用
- 未来如有需要可迁移到专用图数据库

### 2. 向量搜索选型

| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| **sqlite-vec** | 已集成到 OpenClaw，无需额外依赖 | 功能相对简单 | ⭐⭐⭐⭐⭐ |
| LanceDB | 已集成到 OpenClaw，性能更好 | 需要额外学习成本 | ⭐⭐⭐⭐ |
| 纯内存向量库 (如 usearch) | 性能极高 | 数据持久化需要额外处理 | ⭐⭐⭐ |

**决策**: 复用 sqlite-vec
- 理由：OpenClaw 已使用 sqlite-vec，保持一致性
- 对于笔记级别的向量搜索，sqlite-vec 性能足够

### 3. Markdown 处理选型

| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| **remark** | 生态丰富，插件多，TypeScript 友好 | 包体积较大 | ⭐⭐⭐⭐⭐ |
| marked | 轻量快速 | 功能相对简单 | ⭐⭐⭐⭐ |
| 原生实现 | 无依赖 | 需要自己处理所有边界情况 | ⭐⭐ |

**决策**: remark + gray-matter
- `gray-matter` 用于解析 YAML frontmatter
- `remark` 用于 Markdown 解析和转换
- `remark-gfm` 支持 GitHub Flavored Markdown

### 4. 图算法选型

| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| **应用层实现** | 简单直接，无依赖 | 性能有限 | ⭐⭐⭐⭐⭐ |
| graphlib | 功能完善 | 需要额外依赖 | ⭐⭐⭐⭐ |
| ngraph | 性能较好 | 学习成本 | ⭐⭐⭐ |

**决策**: 应用层实现 + 必要时引入 graphlib
- 初期在应用层实现基础图遍历算法
- 如果性能成为瓶颈，再考虑引入 graphlib

### 5. 日期/ID 生成

| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| **dayjs + 自定义格式** | 轻量，灵活 | 需要自定义 | ⭐⭐⭐⭐⭐ |
| date-fns | 功能强大 | 包体积较大 | ⭐⭐⭐⭐ |
| 原生 Date | 无依赖 | 格式化麻烦 | ⭐⭐⭐ |

**决策**: dayjs
- OpenClaw 可能已有日期处理库，保持一致
- 生成格式：`YYYYMMDDHHMMSS`

---

## 二、实现路线图

### Phase 1: 基础架构 (预计 1-2 周)

**目标**: 建立基础数据层，实现核心 CRUD

**任务清单**:
- [ ] 创建 `src/zettelkasten/` 目录结构
- [ ] 实现核心类型定义 (`types.ts`)
- [ ] 实现数据库 Schema 和迁移脚本
- [ ] 实现 NoteRepository (基础 CRUD)
- [ ] 实现 LinkRepository (基础 CRUD)
- [ ] 实现 TagRepository (基础 CRUD)
- [ ] 编写单元测试

**技术要点**:
- 复用 `memory-host-sdk` 的数据库连接
- 使用 `node:sqlite` (Node.js 内置)
- 实现事务支持

### Phase 2: 核心服务 (预计 1-2 周)

**目标**: 实现业务逻辑层

**任务清单**:
- [ ] 实现 NoteService (CRUD + 搜索)
- [ ] 实现 LinkService (链接管理 + 基础图查询)
- [ ] 实现 TagService (标签管理)
- [ ] 实现基础全文搜索 (FTS5)
- [ ] 实现 Markdown 文件读写
- [ ] 集成测试

**技术要点**:
- 使用 `gray-matter` 解析 YAML frontmatter
- 使用 `remark` 处理 Markdown
- 实现双向链接的自动维护

### Phase 3: 高级功能 (预计 2-3 周)

**目标**: AI 增强和高级搜索

**任务清单**:
- [ ] 实现 CEQRC 工作流引擎
- [ ] 集成 OpenClaw LLM 能力生成摘要
- [ ] 实现链接建议算法
- [ ] 实现语义搜索 (向量搜索)
- [ ] 实现图遍历算法 (最短路径、连通子图等)
- [ ] 性能优化

**技术要点**:
- 复用 OpenClaw 的 LLM 调用接口
- 使用 sqlite-vec 存储笔记向量
- 实现向量相似度计算

### Phase 4: 集成与接口 (预计 1-2 周)

**目标**: 与 OpenClaw 深度集成

**任务清单**:
- [ ] 实现 MemoryHostBridge
- [ ] 实现 SessionBridge (会话关联笔记)
- [ ] 实现 MCP Server
- [ ] 实现 CLI 命令
- [ ] 编写集成测试
- [ ] 编写使用文档

**技术要点**:
- MCP Server 遵循 Model Context Protocol 规范
- CLI 使用 OpenClaw 现有的命令框架

---

## 三、MVP 功能范围

### 必须包含 (MVP)
1. ✅ 笔记 CRUD (创建、读取、更新、删除)
2. ✅ 基础双向链接 (创建、查询)
3. ✅ 标签系统
4. ✅ 全文搜索 (FTS5)
5. ✅ Markdown 文件存储
6. ✅ MCP Server 基础工具 (create_note, get_note, search_notes)

### 可以延后 (Phase 2+)
1. ⏳ CEQRC 完整工作流
2. ⏳ AI 自动生成摘要
3. ⏳ 智能链接建议
4. ⏳ 语义搜索
5. ⏳ 图可视化
6. ⏳ 高级图算法

---

## 四、依赖清单

### 必需依赖
```json
{
  "gray-matter": "^4.0.3",
  "remark": "^15.0.0",
  "remark-gfm": "^4.0.0",
  "remark-stringify": "^11.0.0",
  "dayjs": "^1.11.0"
}
```

### 可选依赖 (Phase 3+)
```json
{
  "graphlib": "^2.1.8"
}
```

### 开发依赖
```json
{
  "@types/gray-matter": "^4.0.0"
}
```

---

## 五、风险评估与应对

| 风险 | 影响 | 可能性 | 应对措施 |
|------|------|--------|----------|
| SQLite 性能瓶颈 | 高 | 中 | 监控查询性能，必要时引入缓存或迁移 |
| 向量搜索精度不足 | 中 | 中 | 调优 embedding 模型，结合 FTS 混合搜索 |
| 与 OpenClaw 集成冲突 | 高 | 低 | 充分测试，渐进式集成 |
| Markdown 格式兼容性问题 | 低 | 中 | 使用标准库，充分测试边界情况 |

---

## 六、下一步行动建议

### 立即开始 (本周)
1. **确认技术选型** - 审查上述选型决策
2. **搭建开发环境** - 创建目录结构，安装依赖
3. **实现数据库 Schema** - 创建表结构和迁移脚本

### 短期目标 (2周内)
1. 完成 Phase 1 基础架构
2. 实现基础 CRUD 功能
3. 编写核心单元测试
