309 lines
9.8 KiB
Markdown
309 lines
9.8 KiB
Markdown
# 织忆 MemoryWeave 实施计划 v0.1
|
||
|
||
> **目标**：Python 原型 → Go+Rust 生产级基础设施
|
||
> **代码生成**：全部由 opencode 生成，不做手工编码
|
||
> **仓库**：http://192.168.123.11:3000/xiaoxue_admin/memoryweave
|
||
|
||
---
|
||
|
||
## 里程碑概览
|
||
|
||
| 里程碑 | 天数 | 输出 | 验收标准 |
|
||
|--------|------|------|---------|
|
||
| **M1: 骨架** | 1-2 | go build + cargo build 通过 | `/health` 200 OK |
|
||
| **M2: 存储** | 3-5 | LanceDB 集成 + Embedding 管线 | recall 延迟 < 200ms（本地 BGE） |
|
||
| **M3: 核心 API** | 6-10 | /commit + /recall + /bootstrap | 对比 Python 版本结果一致 |
|
||
| **M4: 蒸馏** | 11-15 | 自动蒸馏 + 质量评分 | commit → distill → LanceDB 全链路 |
|
||
| **M5: 治理** | 16-20 | 冲突检测 + 遗忘 + 知识图谱 | /conflicts/scan 返回正确结果 |
|
||
| **M6: 自优化** | 21-25 | 仪表盘 + 缺口检测 + 因果追踪 | 7 项指标产出有效趋势 |
|
||
| **M7: 分布式** | 26-30 | Redis Streams + CRDT | 双实例 doc_count 一致 |
|
||
| **M8: 切换** | 31-35 | 影子部署 → 灰度 → 全量 | 7821 端口 Go 服务稳定 72h |
|
||
|
||
---
|
||
|
||
## M1: 项目骨架（Day 1-2）
|
||
|
||
### 任务
|
||
|
||
| ID | 任务 | 文件 | 预估 |
|
||
|----|------|------|------|
|
||
| M1.1 | Go `go mod tidy` 通过 | go/go.mod | 0.5h |
|
||
| M1.2 | Rust `cargo check` 通过 | rust/Cargo.toml | 0.5h |
|
||
| M1.3 | `/health` 端点 + Auth 中间件 | go/internal/api/server.go | 2h |
|
||
| M1.4 | Protobuf 定义 (Go↔Rust IPC) | go/proto/consolidate.proto | 1h |
|
||
| M1.5 | Rust main.rs 参数解析 | rust/src/main.rs | 1h |
|
||
| M1.6 | systemd unit 文件 | deploy/*.service | 0.5h |
|
||
| M1.7 | CI: build + test (Makefile) | Makefile | 1h |
|
||
|
||
### 验收
|
||
|
||
```bash
|
||
make build # go build + cargo build 通过
|
||
sudo make install # systemd 服务安装成功
|
||
curl http://localhost:7821/health # {"status":"ok"}
|
||
```
|
||
|
||
---
|
||
|
||
## M2: 存储层（Day 3-5）
|
||
|
||
### 任务
|
||
|
||
| ID | 任务 | 文件 | 预估 |
|
||
|----|------|------|------|
|
||
| M2.1 | LanceDB schema 创建（memories/episodes/tombstones） | go/internal/storage/lancedb.go | 3h |
|
||
| M2.2 | LanceDB 读写（Insert/Search/Update） | go/internal/storage/lancedb.go | 3h |
|
||
| M2.3 | bge-m3 编码客户端（本地 vLLM + 模力方舟 fallback） | go/internal/storage/embedder.go | 3h |
|
||
| M2.4 | bge-reranker-v2-m3 客户端 | go/internal/storage/reranker.go | 2h |
|
||
| M2.5 | Recall pipeline: encode → LanceDB search → rerank | go/internal/storage/recall.go | 3h |
|
||
| M2.6 | JSONL 分片读写（episodes 历史数据） | go/internal/storage/jsonl.go | 2h |
|
||
| M2.7 | Redis 客户端（commit store + 事件流） | go/internal/storage/redis.go | 2h |
|
||
| M2.8 | SQLite 初始化（distill_queue + graph + audit_log） | go/internal/storage/sqlite.go | 2h |
|
||
| M2.9 | Rust LanceDB 原生读写（lancedb crate） | rust/src/lancedb.rs | 2h |
|
||
| M2.10 | Rust Embedding 管线（Candle/ort） | rust/src/embed.rs | 3h |
|
||
|
||
### 验收
|
||
|
||
```bash
|
||
# LanceDB 创建表 + 插入 10 条测试数据 + 搜索 → 返回正确结果
|
||
curl -X POST -H "X-API-Key: $KEY" localhost:7821/api/v1/recall \
|
||
-d '{"query":"牧尘的系统配置","limit":5}'
|
||
# → 返回 5 条相关记忆，延迟 < 200ms
|
||
```
|
||
|
||
---
|
||
|
||
## M3: 核心 API（Day 6-10）
|
||
|
||
### 任务
|
||
|
||
| ID | 任务 | 预估 |
|
||
|----|------|------|
|
||
| M3.1 | `POST /api/v1/commit` — 写入 episode | 3h |
|
||
| M3.2 | `POST /api/v1/recall` — 混合检索（向量+图谱+MMR） | 3h |
|
||
| M3.3 | `GET /api/v1/bootstrap` — 冷启动 | 1h |
|
||
| M3.4 | `POST /api/v1/batch-commit` — 批量提交 | 2h |
|
||
| M3.5 | `GET /api/v1/stats` — 统计 | 1h |
|
||
| M3.6 | 全端点 Auth 中间件 | 1h |
|
||
| M3.7 | API 对比测试（Python vs Go） | 3h |
|
||
| M3.8 | WebSocket `/api/v1/ws/{agent_id}` — 实时推送 | 3h |
|
||
|
||
### 验收
|
||
|
||
```bash
|
||
# 与 Python 版本相同输入 → 相同输出
|
||
python -m pytest tests/api_compat.py -v
|
||
# → 全部通过
|
||
```
|
||
|
||
---
|
||
|
||
## M4: 蒸馏引擎（Day 11-15）
|
||
|
||
### 任务
|
||
|
||
| ID | 任务 | 预估 |
|
||
|----|------|------|
|
||
| M4.1 | 硬规则过滤（Layer 1） | 2h |
|
||
| M4.2 | LLM 评估蒸馏（Layer 2）— 5 维度评分 | 4h |
|
||
| M4.3 | commit → 自动触发蒸馏 | 2h |
|
||
| M4.4 | Distilled 写入 LanceDB | 2h |
|
||
| M4.5 | 批量蒸馏（攒 N 条一起处理） | 2h |
|
||
| M4.6 | 每日 LLM 调用限额（50 次/agent） | 2h |
|
||
| M4.7 | 降级策略（LLM 不可用 → 规则提取） | 2h |
|
||
| M4.8 | `/api/v1/feedback/useful` + `/not-useful` 端点 | 2h |
|
||
| M4.9 | 质量评分（quality_score = useful/(useful+not_useful)） | 1h |
|
||
|
||
### 验证
|
||
|
||
```bash
|
||
# 提交 3 条 episode → 自动蒸馏 → 检查 distilled 表
|
||
curl -X POST /api/v1/commit -d '{...}' # x3
|
||
curl /api/v1/stats | jq '.distilled_count'
|
||
# → 3
|
||
```
|
||
|
||
---
|
||
|
||
## M5: 治理引擎（Day 16-20）
|
||
|
||
### 任务
|
||
|
||
| ID | 任务 | 预估 |
|
||
|----|------|------|
|
||
| M5.1 | 冲突检测 — entity/fact/decision 三种冲突 | 4h |
|
||
| M5.2 | `/api/v1/conflicts` 端点 | 2h |
|
||
| M5.3 | 冲突自动裁决（latest_wins / primary_wins） | 2h |
|
||
| M5.4 | 遗忘策略：线性衰减 + 核心记忆保护 | 3h |
|
||
| M5.5 | 知识图谱 SQL schema + 建图 | 4h |
|
||
| M5.6 | 多跳导航（双向 BFS + 打分） | 4h |
|
||
| M5.7 | 图谱修剪（4 条规则） | 2h |
|
||
| M5.8 | Namespace 隔离（shared vs agent-local graph） | 2h |
|
||
| M5.9 | `/api/v1/graph/*` 端点 | 2h |
|
||
| M5.10 | WebSocket 冲突通知 → 牧尘裁决 | 2h |
|
||
|
||
### 验收
|
||
|
||
```bash
|
||
# 写入两条冲突事实 → 检测冲突
|
||
curl -X POST /api/v1/commit -d '{"content":"Docker used_by hermes"}'
|
||
curl -X POST /api/v1/commit -d '{"content":"Docker used_by openclaw"}'
|
||
curl /api/v1/conflicts | jq '.count'
|
||
# → 1
|
||
|
||
# 知识图谱多跳导航
|
||
curl /api/v1/graph/navigate -d '{"entity":"Docker","max_hops":2}'
|
||
# → 返回 Docker → hermes, Docker → openclaw 完整路径
|
||
```
|
||
|
||
---
|
||
|
||
## M6: 自优化引擎（Day 21-25）
|
||
|
||
### 任务
|
||
|
||
| ID | 任务 | 预估 |
|
||
|----|------|------|
|
||
| M6.1 | 自优化仪表盘 (`GET /api/v1/metrics/self`) — 7 项指标 | 3h |
|
||
| M6.2 | 知识缺口检测（连续 3 次 miss → gap） | 3h |
|
||
| M6.3 | 缺口自动分类（Type A/B/C/D） | 3h |
|
||
| M6.4 | Type B/C 自动修复（同义词映射/阈值重试） | 2h |
|
||
| M6.5 | Type A 学习任务创建 + WebSocket 推送 | 2h |
|
||
| M6.6 | 记忆预取 — 共访关系图谱 | 3h |
|
||
| M6.7 | 记忆刷新 — freshness 字段 + stale 标记 | 2h |
|
||
| M6.8 | 溯源链 — version_history + source + trigger | 2h |
|
||
| M6.9 | 来源信任加权（牧尘 1.0 > 配置 0.7 > LLM 0.4） | 1h |
|
||
| M6.10 | Rust 深度整合（DBSCAN + 衰减回归 + 质量回溯） | 5h |
|
||
| M6.11 | 蒸馏质量反向测试（L0→L1→L0' cosine 检验） | 3h |
|
||
| M6.12 | 周期性触发器（条件触发 > 24h 定时） | 2h |
|
||
|
||
### 验收
|
||
|
||
```bash
|
||
# 仪表盘有数据
|
||
curl /api/v1/metrics/self | jq '.recall_useful_rate'
|
||
# → 0.85
|
||
|
||
# 缺口检测正常工作
|
||
curl /api/v1/gaps | jq '.count'
|
||
# → > 0
|
||
|
||
# Rust 深度整合
|
||
sudo systemctl start zhiyi-consolidate
|
||
journalctl -u zhiyi-consolidate | grep "completed"
|
||
# → "consolidation completed: 3 clusters, decay calibrated, quality score 0.92"
|
||
```
|
||
|
||
---
|
||
|
||
## M7: 分布式部署（Day 26-30）
|
||
|
||
### 任务
|
||
|
||
| ID | 任务 | 预估 |
|
||
|----|------|------|
|
||
| M7.1 | Redis Streams 事件传播（XADD/XREAD） | 4h |
|
||
| M7.2 | CRDT 合并策略（时间戳 + 来源优先） | 4h |
|
||
| M7.3 | 服务发现（Redis Hash + TTL 心跳） | 2h |
|
||
| M7.4 | 速率限制（per-agent 令牌桶） | 2h |
|
||
| M7.5 | Nginx 负载均衡配置 | 1h |
|
||
| M7.6 | 备份原子性（LanceDB checkpoint + SQLite .backup） | 2h |
|
||
| M7.7 | 灾难恢复脚本 | 1h |
|
||
| M7.8 | Prometheus metrics 端点 | 2h |
|
||
| M7.9 | 双实例 E2E 测试 | 3h |
|
||
|
||
### 验收
|
||
|
||
```bash
|
||
# 双实例同步
|
||
# Instance A commit → Instance B 30s 内可见
|
||
# Instance B 宕机重启 → 自动补齐缺失数据
|
||
# doc_count 一致
|
||
```
|
||
|
||
---
|
||
|
||
## M8: 灰度切换（Day 31-35）
|
||
|
||
| ID | 任务 | 预估 |
|
||
|----|------|------|
|
||
| M8.1 | FAISS → LanceDB 迁移脚本 | 3h |
|
||
| M8.2 | 影子部署：Go 在 7822 运行 48h | — |
|
||
| M8.3 | 灰度：Nginx upstream 10% → 50% → 100% | — |
|
||
| M8.4 | systemd 切换：zhiyi.service → Go 二进制 | 1h |
|
||
| M8.5 | Hermes bridge 验证：memory_search/write 正常 | 1h |
|
||
| M8.6 | 旧 Python 代码归档（7 天可快速回滚） | 0.5h |
|
||
| M8.7 | Go 版本稳定运行 72h 无回滚 | — |
|
||
|
||
### 验收
|
||
|
||
```bash
|
||
curl http://localhost:7821/health
|
||
# → {"status":"ok","service":"zhiyid","version":"1.0.0","uptime":"72h"}
|
||
```
|
||
|
||
---
|
||
|
||
## 关键路径
|
||
|
||
```
|
||
M1 → M2 → M3 → M4 → M5 → M6 → M7 → M8
|
||
↘ M5（可与 M4 并行）
|
||
↘ M6（依赖 M5 图谱）
|
||
```
|
||
|
||
### 可并行
|
||
|
||
| 并行组 | 任务 |
|
||
|--------|------|
|
||
| M2.9-M2.10（Rust） | 与 M2.1-M2.8（Go）并行 |
|
||
| M5（治理） | 可与 M4（蒸馏）部分并行 |
|
||
| M7.5-M7.8（运维） | 与 M7.1-M7.4 并行 |
|
||
|
||
---
|
||
|
||
## 风险
|
||
|
||
| 风险 | 概率 | 缓解 |
|
||
|------|------|------|
|
||
| opencode 限流 | 中 | 核心路径优先；多轮生成 |
|
||
| LanceDB Go 绑定不稳定 | 低 | 备选：Rust `lancedb` crate 原生 |
|
||
| bge-m3 向量不一致 | 中 | cosine_sim ≥ 0.99 阈值检验 |
|
||
| FAISS 数据迁移丢失 | 低 | 备份 → 迁移 → 数目对比 → 抽查 |
|
||
| Rust Candle/ort 编译失败 | 中 | 先 HTTP 调用 vLLM，Rust 仅用 LanceDB |
|
||
|
||
---
|
||
|
||
## 分支策略
|
||
|
||
```
|
||
main ← 稳定版本，只接受 PR
|
||
develop ← 开发主线
|
||
feature/m1-* ← 各里程碑特性分支
|
||
release/v1.0 ← 发布分支
|
||
```
|
||
|
||
## Commit 规范
|
||
|
||
```
|
||
feat: M3.1 POST /api/v1/commit 实现
|
||
fix: LanceDB schema timestamp 类型修正
|
||
docs: IMPLEMENTATION.md M2 验收标准更新
|
||
refactor: recall pipeline 提取为独立模块
|
||
```
|
||
|
||
---
|
||
|
||
## 版本标签
|
||
|
||
| 标签 | 对应 | 日期目标 |
|
||
|------|------|---------|
|
||
| v0.1.0-dev | M1 骨架完成 | Day 2 |
|
||
| v0.2.0-dev | M2 存储完成 | Day 5 |
|
||
| v0.3.0-dev | M3 核心 API | Day 10 |
|
||
| v0.4.0-dev | M4 蒸馏 | Day 15 |
|
||
| v0.5.0-dev | M5 治理 | Day 20 |
|
||
| v0.6.0-dev | M6 自优化 | Day 25 |
|
||
| v0.7.0-dev | M7 分布式 | Day 30 |
|
||
| v1.0.0 | M8 全量切换 | Day 35 |
|