From 04057637e0a607f9c3a8a22d0ec299b4775b1dc4 Mon Sep 17 00:00:00 2001 From: xiaowei Date: Sat, 30 May 2026 18:58:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20=E7=BB=87=E5=BF=86=E4=BA=94?= =?UTF-8?q?=E6=AD=A5=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92=20E1-E5=EF=BC=8C?= =?UTF-8?q?=E9=99=84=E6=B5=8B=E8=AF=95=E9=AA=8C=E8=AF=81=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit E1: 图谱导航激活 E2: 多agent命名空间 E3: 增量embedding E4: 图谱推理 E5: 产品UI（长期） 每个阶段含阻塞记录+进度追踪 --- IMPLEMENTATION-FIVE.md | 288 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 IMPLEMENTATION-FIVE.md diff --git a/IMPLEMENTATION-FIVE.md b/IMPLEMENTATION-FIVE.md new file mode 100644 index 0000000..9cecf68 --- /dev/null +++ b/IMPLEMENTATION-FIVE.md @@ -0,0 +1,288 @@ +# 织忆五步实施计划 +> 创建时间：2026-05-30 +> 状态：规划阶段，未开始 +> 禁止：偷懒、随意更改变动设计语言 + +--- + +## 总览 + +| 阶段 | 内容 | 优先级 | 预计工期 | 状态 | +|------|------|--------|---------|------| +| **E1** | 图谱导航激活 | 🔴 高 | 1-2 天 | ⏳ | +| **E2** | 多 agent 命名空间激活 | 🔴 高 | 1 天 | ⏳ | +| **E3** | 增量 embedding | 🟡 中 | 1 天 | ⏳ | +| **E4** | 图谱推理 | 🟡 中 | 2-3 天 | ⏳ | +| **E5** | 产品 UI | 🔵 低 | 长期 | ⏳ | + +--- + +## E1：图谱导航激活 + +### 目标 +改造 `/recall` 链路，向量搜索后接图谱 BFS 扩展，让搜索结果融合结构化知识。 + +### 现状 +- 图谱数据：1269 节点 / 31248 边（`graph/stats` 确认） +- `navigate.go` BFS 导航代码已写好，但 `/recall` 没调用 +- `/recall` 当前纯语义搜索，不走图谱 + +### 实施步骤 + +#### E1.1 确认 navigate.go 接口 +- 找到 `navigate.go` 的函数签名和参数 +- 确认 BFS 扩展是 1 跳还是 2 跳 +- 确认输出格式（节点列表还是边列表） + +#### E1.2 改造 recall 链路 +修改 `internal/api/routes/recall.go`： +``` +语义搜索 → 向量 top-K → +图谱 BFS 扩展（navigate 1跳邻居）→ +合并去重 → bge-reranker 重排 → +返回最终结果 +``` + +#### E1.3 测试验证 +```bash +# 验证图谱有数据 +curl http://localhost:7821/api/v1/graph/stats + +# 验证 recall 走图谱（找有图谱关联的记忆） +curl "http://localhost:7821/api/v1/recall?query=织忆图谱导航&top_k=5" + +# 对比：图谱激活前 vs 激活后的召回结果差异 +# 激活后应该出现更多 1 跳邻居相关结果 +``` + +### 验收标准 +- `graph/stats` node_count > 1000（已有，确认不变） +- recall 结果中包含图谱扩展内容（通过日志或响应标记确认） +- 延迟 < 500ms（可接受范围） + +--- + +## E2：多 agent 命名空间激活 + +### 目标 +Hermes 和 OpenClaw 使用独立 namespace，数据物理隔离，互不串味。 + +### 现状 +- 所有记忆 `agent_id=default`，混在一起 +- Go 代码已有 namespace 隔离逻辑，配置未激活 + +### 实施步骤 + +#### E2.1 确认当前 namespace 配置 +- 查 `config.go` 或环境变量，看当前默认 namespace +- 查 Hermes 插件 `__init__.py` 的 `agent_id` 写法 + +#### E2.2 配置 Hermes namespace +在 `~/.hermes/plugins/zhiyi/__init__.py` 或 config 中： +```python +# 设为 "hermes"，所有 Hermes 发起的记忆走这个 namespace +self.namespace = "hermes" +``` + +#### E2.3 配置 OpenClaw namespace +在 OpenClaw 的 zhiyi 集成配置中： +```yaml +zhiyi: + namespace: "openclaw" +``` + +#### E2.4 迁移历史数据（可选，先做新数据隔离） +```bash +# 备份 +cp /var/lib/memoryweave/memories.lance /var/lib/memoryweave/memories.lance.bak + +# 将 default namespace 的老数据标记为 hermes（如果确认都是 Hermes 的） +# 或保持 default 不动，等自然过期 +``` + +#### E2.5 测试验证 +```bash +# Hermes 写入记忆，验证 namespace=hermes +curl -X POST http://localhost:7821/api/v1/commit \ + -H "Content-Type: application/json" \ + -d '{"content":"E2测试记忆 hermes namespace","namespace":"hermes"}' + +# OpenClaw 写入记忆，验证 namespace=openclaw +curl -X POST http://localhost:7821/api/v1/commit \ + -H "Content-Type: application/json" \ + -d '{"content":"E2测试记忆 openclaw namespace","namespace":"openclaw"}' + +# 各自查询，只看到自己的 +curl "http://localhost:7821/api/v1/recall?query=E2测试记忆&namespace=hermes" +# → 应只有 hermes 那条 + +curl "http://localhost:7821/api/v1/recall?query=E2测试记忆&namespace=openclaw" +# → 应只有 openclaw 那条 +``` + +### 验收标准 +- `namespace=hermes` 查询不到 `namespace=openclaw` 的记忆 +- `namespace=openclaw` 查询不到 `namespace=hermes` 的记忆 +- 各自 recall 结果只包含同 namespace 内容 + +--- + +## E3：增量 embedding + +### 目标 +commit 时同步调用 vLLM embedding，不等 Rust sidecar batch，延迟从分钟级降到毫秒级。 + +### 现状 +- commit 只写原始文本，embedding 要等 Rust sidecar 批处理 +- vLLM BGE-M3 已在 `localhost:8000` 运行，17ms/条 + +### 实施步骤 + +#### E3.1 确认当前 embedding 流程 +- 查 `commit` API 在 Go 层的处理逻辑 +- 确认 vLLM embedding 调用在哪里（Go 还是 Rust？） + +#### E3.2 Go 层直接调用 vLLM +在 `internal/api/routes/commit.go` 的 commit 处理中，写入文本后同步调用： +``` +commit 文本 → 同步 POST vLLM localhost:8000 → 获取 1024dim 向量 → +写入 LanceDB（text + vector 同时落盘） +``` + +#### E3.3 保留 Rust sidecar 作为 fallback +如果 vLLM 不可用，fallback 到 Rust sidecar batch embedding。 + +#### E3.4 测试验证 +```bash +# 测试 embedding 延迟 +time curl -X POST http://localhost:7821/api/v1/commit \ + -H "Content-Type: application/json" \ + -d '{"content":"E3增量embedding测试，验证同步embedding延迟","namespace":"hermes"}' + +# 验证：写入后立即 recall 能搜到（不等 batch） +sleep 1 +curl "http://localhost:7821/api/v1/recall?query=同步embedding延迟测试&top_k=3" + +# 验证 LanceDB 中该条记忆有向量（查不到具体值，但 recall 能用说明有） +``` + +### 验收标准 +- commit 响应时间 < 100ms（包含 embedding 调用） +- commit 后 5 秒内 recall 能搜到（无需等待 Rust sidecar） +- vLLM 不可用时 fallback 正常，不报错 + +--- + +## E4：图谱推理 + +### 目标 +图谱真正参与推理：矛盾检测、跨 agent 共享、遗忘决策参考图谱结构。 + +### 现状 +- 图谱存了 1269 节点/31248 边，但只搜不用 +- 没有基于图谱结构的推理逻辑 + +### 实施步骤 + +#### E4.1 矛盾检测 +当 commit 新记忆时，检查图谱中是否有同一实体相斥属性： +``` +commit 新记忆 → 解析实体 + 属性 → +查图谱中该实体所有属性 → +如果存在矛盾属性（e.g. "是" vs "不是"）→ 标记为矛盾 → +不阻止写入，但记录到矛盾表中 +``` + +#### E4.2 跨 agent 知识共享 +当 Hermes 找不到答案时，主动查 OpenClaw namespace 的相关记忆： +``` +hermes recall 无结果 → 查 openclaw namespace 相同实体的记忆 → +如有，标记为"跨 agent 共享"，合并结果 +``` + +#### E4.3 遗忘决策参考图谱 +当前遗忘策略只看时间 + 质量分数，加上图谱： +``` +节点度（连接数）高的节点优先保留 +跨 namespace 共享的节点不允许遗忘 +``` + +#### E4.4 测试验证 +```bash +# E4.1 矛盾检测 +curl -X POST http://localhost:7821/api/v1/commit \ + -H "Content-Type: application/json" \ + -d '{"content":"小唯是牧尘的女朋友","namespace":"hermes"}' +curl -X POST http://localhost:7821/api/v1/commit \ + -H "Content-Type: application/json" \ + -d '{"content":"小唯不是牧尘的女朋友","namespace":"hermes"}' + +# 验证矛盾标记 +curl "http://localhost:7821/api/v1/graph/conflicts?entity=小唯" + +# E4.2 跨 agent 共享 +curl "http://localhost:7821/api/v1/recall?query=小唯&namespace=hermes&cross_agent=true" +# 应能看到 openclaw 相关的记忆（如果有） + +# E4.3 图谱度优先保留 +# 验证图谱度高的节点在遗忘测试后仍然存在 +``` + +### 验收标准 +- 矛盾检测能识别出相斥属性对 +- 跨 agent recall 能返回其他 namespace 相关记忆 +- 高连接度节点在遗忘后仍存在 + +--- + +## E5：产品 UI（长期） + +### 目标 +给织忆做一个简单的可视化界面，用于查看记忆、图谱、搜索结果。 + +### 现状 +- 只能 API 调，没有界面 +- 个人用足够，但不方便查看图谱结构 + +### 实施步骤 +待定，优先级最低。前 4 个阶段完成后再规划。 + +### 可能的方案 +- 简单 Web UI（React + Go API） +- Obsidian 插件直接可视化 +- CLI 增强（tree/graph 可视化） + +--- + +## 阶段推进规则 + +1. **必须按顺序完成**：E1 → E2 → E3 → E4 → E5 +2. **每个阶段必须测试验证后才能进入下一阶段** +3. **禁止跳过测试验证步骤** +4. **禁止偷懒：实施步骤必须逐条执行** +5. **禁止随意更改变动设计语言**：阶段目标和验收标准锁定 +6. **如有阻塞，记录到 BLOCKED 章节，继续下一个阶段** + +--- + +## BLOCKED（阻塞记录） + +| 时间 | 阶段 | 阻塞原因 | 尝试方案 | +|------|------|---------|---------| +| - | - | 无阻塞 | - | + +--- + +## 进度追踪 + +| 阶段 | 开始时间 | 完成时间 | 状态 | +|------|---------|---------|------| +| E1 图谱导航激活 | - | - | ⏳ | +| E2 多 agent 命名空间 | - | - | ⏳ | +| E3 增量 embedding | - | - | ⏳ | +| E4 图谱推理 | - | - | ⏳ | +| E5 产品 UI | - | - | ⏳ | + +--- + +*最后更新：2026-05-30* \ No newline at end of file