feat: release v0.2.2 — TCVDB backend, BM25 hybrid retrieval, pipeline refactor

Author: chrishuan

.gitignore

@@ -10,5 +10,10 @@ workspace/
 # Test caches
 __tests__/soak/.model-cache/
 
+# Migration build output
+scripts/export-tencent-vdb/dist/
+scripts/migrate-sqlite-to-tcvdb/dist/
+scripts/read-local-memory/dist/
+
 node_modules/
-benchmark-runs/
+benchmark-runs/

.npmignore

@@ -0,0 +1,22 @@
+# 测试文件
+*.test.ts
+*.test.js
+*.spec.ts
+*.spec.js
+__tests__/
+
+# 开发文档与辅助
+docs/
+benchmark-runs/
+workspace/
+
+# 环境与配置
+.env
+.env.*
+.gitignore
+.codebuddy/
+.coding-ci.yaml
+
+# 运行时产物
+node_modules/
+*.tgz

CHANGELOG.md

@@ -4,6 +4,101 @@
 
 ---
 
+## [0.2.2] - 2026-04-17
+
+### 🐛 修复
+
+- 修复因未声明 `undici` 依赖导致 TCVDB 客户端加载失败的问题（开发环境之前依赖 monorepo 根 `node_modules` 的传递解析）
+- 将插件注册阶段的大量 INFO 日志降级为 DEBUG，避免 CLI 模式下输出过多无关日志
+
+## [0.2.1] - 2026-04-16 (deprecated)
+
+> NOTE: 此版本由于存在 undici 依赖导致插件启动失败的问题，已废弃
+> 相关问题在 0.2.2 及以后版本中已修复
+
+### 🚀 新功能
+
+- TCVDB 新增 HTTPS 连接支持，可通过插件配置 `caPemPath` 或迁移脚本参数 `--tcvdb-ca-pem` 指定自定义 CA 证书 PEM 文件
+- `read-local-memory` 脚本新增 L2 单文件查询，并将 L0 / L1 查询切换为直接从 `vectors.db` 读取，支持 SQL 层过滤、排序与分页
+
+### ✨ 改进
+
+- TCVDB 的 L0 / L1 向量索引默认调整为 `DISK_FLAT`，并在不支持该索引类型的实例上自动回退到 `HNSW`
+- 默认服务端 embedding 模型调整为 `bge-large-zh`
+- TCVDB 所有读接口统一启用 `readConsistency: "strongConsistency"`，消除 read-after-write 不一致
+- 健康检测脚本 VDB 连接支持 HTTPS 自签证书
+
+### 🐛 修复
+
+- 修复 L3 persona sync 因未拉取远端 baseline 导致版本冲突跳过写入的问题
+- 修复 `memories_since_last_persona` 被 L0 和 L1 双重计数导致 persona 触发阈值膨胀的问题
+- 移除 `CheckpointManager` 中已被 `captureAtomically()` 替代的废弃方法
+
+---
+
+## [0.2.0] - 2026-04-15
+
+### 🚀 新功能
+
+**腾讯云向量数据库（TCVDB）存储后端**
+
+- 新增腾讯云向量数据库存储后端，支持向量 + BM25 混合召回
+- 支持 SQLite 与 TCVDB 之间的索引结构同步
+- L2 场景 / L3 画像支持在本地缓存与向量数据库之间双向同步
+- 插件配置（manifest）暴露 `storeBackend`、`tcvdb`、`bm25`、`embedding.timeoutMs` 等配置项
+
+**本地 BM25 关键字检索**
+
+- 使用本地 tcvdb-text 编码器替代原有的 BM25 HTTP sidecar 服务，消除外部依赖
+
+**Seed 数据导入工具**
+
+- 新增 CLI `seed` 命令，支持从外部数据批量导入记忆
+- 提取共享的 pipeline-factory，供 seed 和正常运行时复用
+- 支持 ISO 8601 时间戳格式（移除 JSONL 支持）
+
+**数据迁移与运维工具**
+
+- 新增 SQLite → 腾讯云向量数据库迁移脚本，支持 `--help` / `-h` 展示完整参数说明和使用示例
+- 新增 VDB 数据导出脚本（含预编译 JS 和 CLI 启动器）
+- 新增本地 Memory 数据查询脚本
+- 注册全部 CLI bin 入口：`migrate-sqlite-to-tcvdb`、`export-tencent-vdb`、`read-local-memory`
+
+**记忆搜索工具调用限制**
+
+- `tdai_memory_search` + `tdai_conversation_search` 增加每轮合计最多 3 次的调用次数限制，通过 tool description 和召回引导提示词约束模型行为，防止陷入无效重复搜索
+
+### 🐛 修复
+
+- 修复 L2 场景合并（MERGE）无法删除旧文件的问题：OpenClaw 4.1+ 的 write 工具拒绝空白内容，改用 `[DELETED]` 标记实现软删除，SceneExtractor cleanup 阶段同步识别并清理
+- 修复 L2 抽取产生孤立 BATCH/ARCHIVE 文件的问题，统一 maxScenes 上限为 15
+- 修复 L3 启动时重复拉取 profile 的问题
+- 过滤 skill wrapper 噪声标记（`¥¥[...]¥¥`）
+- 处理 `createCollection` 并发竞态（错误码 15202）
+
+### ♻️ 重构
+
+- Pipeline checkpoint 游标语义从 timestamp 改为 update_at
+- Runner 改用 `api.runtime.agent.runEmbeddedPiAgent`，避免跨环境导入失败
+- 统一脚本构建流程：新增 `build:scripts` 一键编译命令，`prepack` 钩子确保 `npm pack` 前自动编译全部脚本产物
+
+### 📚 文档
+
+- 新增 AI Agent 长期记忆插件设计与实现技术文档
+- 新增项目指南、研发系统分层架构文档
+- 新增 VDB 存储设计文档及迁移指南
+
+---
+
+<details>
+<summary>预发布版本</summary>
+
+## [0.2.0-beta.1] - 2026-04-14
+
+*此版本的内容已合并至 [0.2.0] 正式版。*
+
+</details>
+
 ## [0.1.4] - 2026-04-10
 
 ### 🚀 Features

SKILL-DIAGNOSTIC-EXPORT.md

@@ -0,0 +1,152 @@
+---
+name: openclaw-diagnostic-export
+description: 帮助用户导出 OpenClaw + memory-tencentdb（原 memory-tdai）记忆插件的现场诊断数据，用于排查问题。当用户提到"导出诊断数据""export diagnostic""现场数据""排查问题""导出日志""收集现场""打包现场数据"时应触发。
+version: 1.0.0
+---
+
+## 目的
+
+将 OpenClaw 日志、记忆插件数据（L0~L3）、脱敏后的配置打包为本地压缩包，由用户确认后手动发送给研发团队排查问题。
+
+> **名称说明**：插件已从 `@tdai/memory-tdai` 更名为 `@tencentdb-agent-memory/memory-tencentdb`，但数据目录始终为 `~/.openclaw/memory-tdai/`（代码中硬编码）。本 skill 中所有对 `memory-tdai` 目录的引用均指实际数据目录路径，与插件 ID 无关。
+
+## 导出工作流
+
+### Step 1: 确认环境
+
+在导出前，先确认 OpenClaw 工作目录存在且可访问：
+
+```bash
+# 探测工作目录（优先级：环境变量 > ~/.openclaw > ~/.clawdbot）
+OPENCLAW_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+[ -d "$OPENCLAW_DIR" ] || OPENCLAW_DIR="$HOME/.clawdbot"
+ls -la "$OPENCLAW_DIR/" 2>/dev/null && echo "✅ 找到: $OPENCLAW_DIR" || echo "❌ 未找到 OpenClaw 工作目录"
+```
+
+确认 memory-tdai 子目录存在：
+
+```bash
+ls -la "$OPENCLAW_DIR/memory-tdai/" 2>/dev/null
+```
+
+### Step 2: 执行导出脚本
+
+运行项目 `scripts/` 目录下的导出脚本：
+
+```bash
+bash scripts/export-diagnostic.sh
+```
+
+> 脚本位于本项目的 `scripts/export-diagnostic.sh`，如果通过 `pnpm` 或其他方式运行，需确保工作目录在项目根目录下。
+
+脚本默认将压缩包输出到 `~/Downloads/openclaw-diagnostic-<timestamp>.tar.gz`。
+
+如需指定其他输出目录：
+
+```bash
+bash scripts/export-diagnostic.sh /tmp
+```
+
+### Step 3: 确认导出结果
+
+脚本执行完成后，检查输出：
+
+1. **确认压缩包已生成** — 脚本末尾会打印压缩包路径和大小
+2. **向用户说明包含内容**：
+
+| 文件/目录 | 内容 | 隐私风险 |
+|-----------|------|---------|
+| `env-info.txt` | 系统版本、OpenClaw 版本、目录结构、磁盘占用 | 低 |
+| `logs/` | OpenClaw 网关日志 + 滚动日志（最近 3 天，每文件最多 5000 行） | 低 |
+| `memory-tdai/` | 记忆插件全量数据：L0 对话、L1 记忆、L2 场景、L3 画像、SQLite 数据库、checkpoint | **高** — 包含用户对话原文 |
+| `openclaw-config-redacted.json` | 脱敏后的配置（已移除 API Key/Token/Password/Secret，models/channels/env 整体替换） | 低 |
+| `plugins-info.txt` | 已安装插件列表和版本 | 低 |
+
+3. **提醒用户**：
+   - 配置文件已自动脱敏，API Key、Token 等敏感信息已被替换为 `***REDACTED***`
+   - **记忆数据（memory-tdai/）包含用户对话原文**，请确认可以分享后再发送
+   - 压缩包存放在本地，**不会自动上传**，需要用户手动发送给研发团队
+
+### Step 4: 告知用户后续操作
+
+导出完成后，告知用户：
+
+1. 压缩包已保存在本地（打印具体路径）
+2. 请检查内容后，通过企微/邮件等方式手动发送给研发团队
+3. 如只需部分数据（如仅日志或仅配置），可解压后选择性发送
+
+## 导出内容详解
+
+### OpenClaw 日志位置
+
+| 日志类型 | 路径 | 说明 |
+|---------|------|------|
+| 网关 stdout | `~/.openclaw/logs/gateway.log` | 网关守护进程标准输出 |
+| 网关 stderr | `~/.openclaw/logs/gateway.err.log` | 网关守护进程错误输出 |
+| 滚动日志 | `/tmp/openclaw/openclaw-YYYY-MM-DD.log` | 按日期滚动，JSON Lines 格式，24h 自动清理 |
+| 配置审计 | `~/.openclaw/logs/config-audit.jsonl` | 配置写入审计记录 |
+| 命令日志 | `~/.openclaw/logs/commands.log` | 命令事件日志（hook 可选） |
+
+### 记忆插件数据结构
+
+```
+~/.openclaw/memory-tdai/
+├── conversations/          — L0 原始对话（每日 JSONL 分片）
+├── records/                — L1 结构化记忆（每日 JSONL 分片）
+├── scene_blocks/           — L2 场景 Markdown 文件
+├── persona.md              — L3 用户画像
+├── vectors.db              — SQLite 数据库（向量 + 全文索引）
+├── .metadata/              — checkpoint、scene_index.json
+└── .backup/                — 滚动备份
+```
+
+### 配置脱敏规则
+
+导出脚本对 `openclaw.json` 执行以下脱敏：
+
+| 规则 | 处理方式 |
+|------|---------|
+| 字段名匹配 `apiKey/token/password/secret/credential` 且值为字符串 | 替换为 `***REDACTED(Nchars)***` |
+| SecretRef 对象（含 source/provider/id） | id 替换为 `***REDACTED***` |
+| 顶层 `models`、`secrets`、`channels`、`env` 块 | 整体替换为 `***REDACTED_SECTION***` |
+| `gateway.auth` 下的 token/password | 替换为 `***REDACTED***` |
+| 其余字段（含 `plugins` 完整配置） | **保留原样**（插件配置是排查重点） |
+
+## 手动导出（脚本不可用时的备选方案）
+
+如果导出脚本无法执行（如 Node.js 不可用），按以下步骤手动收集：
+
+```bash
+# 1. 创建导出目录
+EXPORT_DIR=~/Downloads/openclaw-diagnostic-$(date +%Y%m%d-%H%M%S)
+mkdir -p "$EXPORT_DIR"
+
+# 2. 复制日志
+cp -r ~/.openclaw/logs/ "$EXPORT_DIR/logs/" 2>/dev/null
+cp /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log "$EXPORT_DIR/" 2>/dev/null
+
+# 3. 复制记忆插件数据
+cp -r ~/.openclaw/memory-tdai/ "$EXPORT_DIR/memory-tdai/" 2>/dev/null
+
+# 4. 手动脱敏配置（⚠️ 必须手动删除敏感字段！）
+# 复制配置并用编辑器删除 models/secrets/channels 块和所有 apiKey/token 值
+cp ~/.openclaw/openclaw.json "$EXPORT_DIR/openclaw-config-NEEDS-MANUAL-REDACTION.json"
+
+# 5. 打包
+cd ~/Downloads && tar -czf "$EXPORT_DIR.tar.gz" "$(basename $EXPORT_DIR)"
+
+echo "⚠️ 请务必在发送前手动检查并删除配置中的敏感信息！"
+```
+
+## 常见问题排查线索
+
+导出数据后，研发团队通常关注以下方面：
+
+| 排查方向 | 查看文件 | 关键信息 |
+|---------|---------|---------|
+| 插件是否加载 | `logs/` 中搜索 `[memory-tdai]` | 插件注册、配置解析日志（注：日志标签仍为 `[memory-tdai]`，与插件 ID 无关） |
+| 记忆召回是否工作 | `logs/` 中搜索 `[recall]` | 搜索策略、耗时、命中数 |
+| L1 提取是否触发 | `logs/` 中搜索 `[pipeline]` | 调度触发、L1/L2/L3 执行状态 |
+| 向量搜索是否可用 | `openclaw-config-redacted.json` 的 `plugins.entries` | embedding 配置是否正确 |
+| 数据量/磁盘占用 | `env-info.txt` | du 输出、文件数量 |
+| checkpoint 状态 | `memory-tdai/.metadata/recall_checkpoint.json` | 进度、游标、计数器 |