chore: release v0.3.5

2026-07-10 12:34:27 +00:00 · 2026-05-20 22:58:05 +08:00
parent f81b79e4ac
commit 0d462e0b63
19 changed files with 3140 additions and 7 deletions
@@ -0,0 +1,239 @@
+# SQLite → 腾讯云向量数据库迁移工具
+
+离线迁移工具，用于将 memory-tdai 的数据从本地 SQLite 存储迁移到腾讯云向量数据库（TCVDB）。
+
+## 前置条件
+
+- Node.js >= 22.16.0
+- 插件已通过 `openclaw plugins install` 安装
+- 迁移脚本已编译（见下方）
+
+## 编译
+
+迁移脚本使用 TypeScript 编写，运行前需要先编译：
+
+```bash
+npm run build:migrate-sqlite-to-vdb
+```
+
+编译产物输出到 `scripts/migrate-sqlite-to-tcvdb/dist/`，可直接用 Node 运行。
+
+## 使用方法
+
+```bash
+# 预检模式（仅查看源数据，不执行写入）
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --dry-run
+
+# 正式迁移
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --yes
+```
+
+### 更多示例
+
+```bash
+# 直接传入 API Key（不通过环境变量）
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key 'your-api-key-here' \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --yes
+```
+
+```bash
+# 指定自定义 SQLite 路径（数据库不在默认 vectors.db 位置时）
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --sqlite-path /backup/2026-04/vectors-snapshot.db \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --yes
+```
+
+```bash
+# 只迁移 L1 记忆层（跳过 L0 原始消息和 Profile）
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --layers l1 \
+  --yes
+```
+
+```bash
+# 只迁移 L0 和 L1（不迁移 Profile）
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --layers l0,l1 \
+  --yes
+```
+
+```bash
+# 英文语料场景：使用英文 BM25 分词
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-en-v1.5 \
+  --bm25-language en \
+  --yes
+```
+
+```bash
+# 禁用 BM25 稀疏向量（仅使用密集向量检索）
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --no-bm25-enabled \
+  --yes
+```
+
+```bash
+# 仅迁移数据，不自动更新 openclaw.json 和 manifest（手动管理配置）
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --no-apply-config \
+  --no-rewrite-manifest \
+  --yes
+```
+
+```bash
+# 追加迁移：允许目标库已有数据，跳过非空检查
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --no-fail-if-target-nonempty \
+  --no-verify-counts \
+  --yes
+```
+
+```bash
+# 输出迁移摘要到 JSON 文件（适合 CI/自动化流水线）
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://127.0.0.1:80 \
+  --tcvdb-username root \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --summary-json-path ./migration-report.json \
+  --job-id "migrate-2026-04-13" \
+  --yes
+```
+
+```bash
+# 设置自定义超时和别名
+npm run migrate:sqlite-to-tcvdb -- \
+  --plugin-data-dir ~/.openclaw/memory-tdai \
+  --openclaw-config-path ~/.openclaw/openclaw.json \
+  --tcvdb-url http://10.0.1.50:80 \
+  --tcvdb-username admin \
+  --tcvdb-api-key-env TCVDB_API_KEY \
+  --tcvdb-database agent_memory_prod \
+  --tcvdb-embedding-model bge-large-zh \
+  --tcvdb-alias "生产环境-主库" \
+  --tcvdb-timeout-ms 30000 \
+  --yes
+```
+
+## 参数说明
+
+| 参数 | 必填 | 默认值 | 说明 |
+|---|---|---|---|
+| `--plugin-data-dir` | 是 | — | 插件数据目录路径 |
+| `--openclaw-config-path` | 是 | — | `openclaw.json` 配置文件路径 |
+| `--sqlite-path` | 否 | `<plugin-data-dir>/vectors.db` | SQLite 数据库文件路径（默认取数据目录下的 `vectors.db`） |
+| `--plugin-id` | 否 | `memory-tencentdb` | 写入配置时使用的插件 ID |
+| `--tcvdb-url` | 是 | — | TCVDB 服务地址 |
+| `--tcvdb-username` | 是 | — | TCVDB 用户名 |
+| `--tcvdb-api-key` | * | — | TCVDB API 密钥（明文） |
+| `--tcvdb-api-key-env` | * | — | 包含 API 密钥的环境变量名 |
+| `--tcvdb-database` | 是 | — | TCVDB 数据库名 |
+| `--tcvdb-embedding-model` | 是 | — | Embedding 模型名称 |
+| `--tcvdb-alias` | 否 | `""` | 用户自定义别名 |
+| `--tcvdb-timeout-ms` | 否 | `10000` | 请求超时时间（毫秒） |
+| `--layers` | 否 | `l0,l1,l2,l3` | 要迁移的层（逗号分隔） |
+| `--dry-run` | 否 | `false` | 仅预览，不执行写入 |
+| `--yes` | 否 | `false` | 跳过交互确认 |
+| `--apply-config` | 否 | `true` | 迁移后更新 openclaw.json |
+| `--config-backup` | 否 | `true` | 写入配置前先备份原配置文件 |
+| `--rewrite-manifest` | 否 | `true` | 将 manifest.json 更新为 tcvdb |
+| `--fail-if-target-nonempty` | 否 | `true` | 目标库非空时中止 |
+| `--verify-counts` | 否 | `true` | 迁移后校验记录数 |
+| `--summary-json-path` | 否 | — | 将迁移摘要写入此文件 |
+| `--job-id` | 否 | — | 迁移任务 ID（用于追踪） |
+| `--bm25-enabled` | 否 | `true` | 启用 BM25 稀疏向量 |
+| `--bm25-language` | 否 | `zh` | BM25 语言（`zh` 或 `en`） |
+
+\* `--tcvdb-api-key` 和 `--tcvdb-api-key-env` 二选一，必须提供其中一个。
+
+## 目录结构
+
+```
+scripts/migrate-sqlite-to-tcvdb/
+├── cli-entry.ts          # CLI 入口
+├── sqlite-to-tcvdb.ts    # 迁移核心逻辑（参数解析、预检、数据迁移）
+├── config-write.ts       # OpenClaw 配置更新（JSON5，自包含）
+├── manifest-write.ts     # Manifest 重写
+├── *.test.ts             # 就近放置的测试文件
+├── tsconfig.json         # 迁移脚本编译配置
+├── dist/                 # 编译产物（已 gitignore）
+└── README.md             # 本文件
+
+bin/migrate-sqlite-to-tcvdb.mjs     # 极薄 bin 包装 → dist/
+```
+
+迁移脚本通过 `../../src/` 引用存储实现（VectorStore、TcvdbMemoryStore 等），但**不依赖 `openclaw/plugin-sdk`**。配置写回直接使用 `json5`。