ruflo-ruvector 版本锁定实战：以 ADR-0001 为准绳，将 ruvector 固定到 0.2.25 并重建可验证的 CLI 契约

ruflo-ruvector 版本锁定实战：以 ADR-0001 为准绳，将 ruvector 固定到 0.2.25 并重建可验证的 CLI 契约

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

本文是ruflo-ruvector插件核心架构决策（ADR-0001）的深度解读与实战指南。它回答了三个具体问题：为什么一个包装ruvectornpm 包的插件必须把版本钉死在 0.2.25、如何用npx -y ruvector@0.2.25统一全部调用面、以及如何用smoke.sh把"文档里写了什么"变成"被自动化验证的契约"。读完本文，你将掌握一套可直接复用的插件版本治理方法论：可选增强包（ONNX / Brain / SONA）的按需安装策略、MCP 服务的同版本注册方式、以及针对"被移除的 CLI 表面"的回归防护手段。

背景：文档漂移如何摧毁一个插件的可信度

ruflo-ruvector是 Ruflo 体系中的自学习向量数据库插件，底层包装ruvectornpm 包，为 Agent 提供向量嵌入、语义搜索、代码图聚类、自学习 hooks 与 Brain/SONA 集体智能能力。在 ADR-0001 被采纳之前，插件的文档（README、agent 文件、skills、命令规范）与实际 CLI 表面之间出现了两处严重漂移：

1. 理想化功能清单。旧文档把FlashAttention-3、Graph RAG、Hybrid Search、DiskANN、ColBERT、Matryoshka、MLA、TurboQuant、Brain AGI、Midstream当作可调用的 CLI 子命令来宣传。事实上，原生 Rust 绑定确实暴露了其中大部分原语，但没有任何 CLI 子命令把它们接线起来——唯一的入口是attention list枚举机制。
2. 未指定的版本。插件用裸的npx ruvector ...调用，未做版本钉定。用户解析到ruvector@0.1.x时（没有brain、route、sona），得到的表面与ruvector@0.2.x用户完全不同，同样一段文档在不同环境里行为不一致。

对线上ruvector@0.2.25的实测审计，确认了一长串"文档这么写、命令不存在"的具体失败案例：

npx ruvector embed "TEXT" # → unknown command 'TEXT'（真实形式是 embed text "TEXT"） npx ruvector compare A B # → command does not exist npx ruvector cluster --namespace ... --k N # → cluster 是分布式集群操作，不是 k-means npx ruvector hooks route --task X # → unknown option `--task`（应为位置参数） npx ruvector brain agi status # → 没有 agi 子组 npx ruvector midstream status # → command does not exist npx ruvector index create N # → command does not exist（应使用 create <path>）

这些失败不是用户操作错误，而是插件文档与真实 CLI 契约脱节造成的系统性误导。ADR-0001 正是为了终结这种漂移而诞生。

决策核心：把版本钉定上升为不可违反的契约

ADR-0001 的决策可以概括为一句话：插件将ruvector钉定到 0.2.25，并将全部可选增强包作为按需扩展而非强制依赖进行文档化。它由六条可执行规则组成，下面逐一拆解。

1. 钉定每一次 CLI 调用

插件内所有npx调用（README、agent、skills、commands、scripts）必须采用如下形式：

npx -y ruvector@0.2.25 <subcommand> [args]

两个要素各有其理：

• -y抑制 npm 的交互式确认提示，保证命令在无人值守环境（脚本、CI、Agent 工作流）中可执行；
• 版本钉定@0.2.25防止未来 ruvector 发布新版本时，在插件不知情的情况下破坏其契约。

这条规则在源码中有直接体现：vector-engineeragent 的第一步就是确保钉定版本已安装——npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install ruvector@0.2.25（见 agents/vector-engineer.md），而 commands/vector.md 的 80+ 个子命令条目无一例外都以npx -y ruvector@0.2.25 ...开头。

2. 增强包按需安装，而非强制依赖

决策理由是务实的：这些是重量级依赖（仅 ONNX 运行时体积就很大）。若在安装时强制全部拉取，会惩罚那些只想要 hooks 路由或 RVF 存储的用户。因此 ADR 选择提供vector-setup技能，并文档化"错误消息 → 安装命令"的精确映射。

这套映射在 skills/vector-setup/SKILL.md 里被固化成一张可查的故障表：

3. MCP 服务器使用同一钉定版本注册

claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start

MCP 传输层在 ruvector 的 minor 版本之间会发生变化，因此钉定 MCP 启动命令至关重要——它保证了下游 Agent 可见的 103 个（README 口径为 91 个，均来自ruvector mcp tools实测）MCP 工具的稳定性。注册后用claude mcp list | grep ruvector验证，即可直接调用hooks_route、hooks_ast_analyze、hooks_rag_context、brain_search、attention_list等工具。

4. 已移除的表面保持移除

ADR 明确要求插件不得在未经协调的情况下重新引入以下调用形式，即使上游将来以不同名称提供了等价功能：

• compare、midstream、顶层index（由create <path>/stats <path>取代）
• embed --file、embed --batch --glob、embed --model poincare（不存在等价 flag）
• cluster --namespace --k（由hooks graph-cluster <files>取代）
• hooks route --task、hooks ast-analyze --file（改为位置参数）
• brain agi *（由brain status、brain search等取代）

完整的"旧形式 → 替代方案"映射表记录在 agents/vector-engineer.md，例如ruvector embed "TEXT"→ruvector embed text "TEXT"、ruvector index create N→ruvector create <path> -d 384、ruvector hooks route --task X→ruvector hooks route "X"（位置参数）。ADR 同时预留了演进通道：若上游引入稳定的等价物，且 smoke 测试同步更新，未来 ADR 可以放宽本条款。

5. 以 smoke 测试作为契约本身

scripts/smoke.sh 是对任何已安装ruvector@0.2.25验证契约表面的自动化脚本，要求在任何插件变更后保持全绿。测试覆盖范围：

• 版本钉定：--version输出必须为0.2.25（脚本用grep -E '^[0-9]+\.[0-9]+\.[0-9]+$'过滤 npm 警告行后取最后一行比对）
• 顶层子命令可见性：hooks、embed、rvf、attention、gnn、brain、sona、create、stats、search、insert必须出现在--help中
• 位置参数正确性：hooks route "test task"必须返回含"recommended"字段的 JSON；hooks ast-analyze sample.ts必须返回AST Analysis摘要
• 功能可工作性：hooks ast-complexity返回含"cyclomatic"的 JSON、attention list提及FlashAttention、rvf examples至少列出 10 个存储、gnn info报告Available、info报告CLI Version: 0.2.25、doctor退出码为 0
• 已移除表面回归防护：compare、midstream、index必须返回unknown command '<c>'——脚本特意注释"不要传--help"，因为 Commander 会显示顶层帮助而非报错，从而绕开检测

运行方式与期望输出：

bash plugins/ruflo-ruvector/scripts/smoke.sh # Expected: "11 passed, 0 failed"

脚本还以mktemp -d建立隔离工作目录并在退出时清理，用trap保证任何路径下都不会污染用户目录。

6. 插件自身版本策略

插件在.claude-plugin/plugin.json中的version字段，每当 CLI 契约发生变化就 bump（patch 级）——无论变化是新增子命令（additive）还是修复。这使得下游消费者可以观察插件版本差异：下游只需比较版本号即可知道契约是否发生了变化。

实操：从零开始的一键初始化流程

对于首次接触该插件的用户，正确的打开方式不是手抄命令，而是调用vector-setup技能：

/vector-setup # 基础安装 /vector-setup --full # 额外拉取 @ruvector/graph-node 与 @ruvector/router

其内部执行序列（来自 skills/vector-setup/SKILL.md）为：

第 1 步：钉定 ruvector

npm install ruvector@0.2.25

第 2 步：按需安装增强包（幂等，只补缺失项）

npm install ruvector-onnx-embeddings-wasm \ @ruvector/pi-brain \ @ruvector/ruvllm

第 3 步：验证二进制

npx -y ruvector@0.2.25 doctor npx -y ruvector@0.2.25 info

第 4 步：注册 MCP 服务器

claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start claude mcp list | grep ruvector

第 5 步：冒烟验证常用子命令

npx -y ruvector@0.2.25 hooks route "test" npx -y ruvector@0.2.25 attention list npx -y ruvector@0.2.25 rvf examples

第 6 步（可选）：为 brain + edge 生成 pi 身份

npx -y ruvector@0.2.25 identity generate npx -y ruvector@0.2.25 identity show

该技能还明确说明它不会安装什么：原生 Rust 工具链（仅源码构建需要）、平台特定原生绑定（由@ruvector/core自动探测）、@ruvector/sona原生绑定（macOS arm64 上@ruvector/ruvllm的 JS 回退已足够，Linux x64 有独立原生绑定）。若执行后doctor仍报错，将输出原样贴出即可诊断。

0.2.25 真实 CLI 表面速览：从embed到edge

钉定版本后，插件承诺的 CLI 表面以 commands/vector.md 为准，主要分区如下：

嵌入（Embedding）

npx -y ruvector@0.2.25 embed text "TEXT" # 384 维 ONNX 向量 npx -y ruvector@0.2.25 embed text "TEXT" --adaptive --domain code # LoRA 领域适配 npx -y ruvector@0.2.25 embed benchmark # 对比 base vs adaptive

注意子命令是embed text，文本是位置参数；不存在embed "TEXT"形式，也没有--file、--batch、--globflag（批量需要自己循环）。自适应变体是 LoRA 调优的领域嵌入；vector-embed技能确认模型为 ONNX all-MiniLM-L6-v2，维度 384。

数据库生命周期

npx -y ruvector@0.2.25 create project.db -d 384 -m cosine # -m 可选 cosine|euclidean|dot npx -y ruvector@0.2.25 stats project.db npx -y ruvector@0.2.25 insert project.db corpus.json npx -y ruvector@0.2.25 search project.db -v '[0.1,0.2,...]' -k 5 npx -y ruvector@0.2.25 export project.db -o backup.json npx -y ruvector@0.2.25 import backup.json -d project.db --merge

RVF 认知容器（含 45 个示例存储）

npx -y ruvector@0.2.25 rvf create project.rvf npx -y ruvector@0.2.25 rvf ingest project.rvf < corpus.json npx -y ruvector@0.2.25 rvf query project.rvf npx -y ruvector@0.2.25 rvf derive <parent> <child> # 血缘追踪 npx -y ruvector@0.2.25 rvf compact project.rvf # 回收删除空间 npx -y ruvector@0.2.25 rvf examples # 45 个参考存储

GNN 与注意力机制（真实原生绑定）

npx -y ruvector@0.2.25 gnn info|layer|search|compress npx -y ruvector@0.2.25 attention list # DotProduct、MultiHead、Flash、Hyperbolic、 # Linear、MoE、GraphRoPe、EdgeFeatured、DualSpace、LocalGlobal npx -y ruvector@0.2.25 attention hyperbolic # Poincare 球几何操作

attention list是理解"哪些机制真实存在"的唯一权威入口。vector-engineeragent 给出了复杂度对照：FlashAttention与MultiHeadAttention为 O(n²) 且 IO 优化、LinearAttention为 O(n)、MoEAttention与LocalGlobalAttention为 O(n·k)。

代码智能 hooks（自学习管线）

npx -y ruvector@0.2.25 hooks init --pretrain --build-agents quality npx -y ruvector@0.2.25 hooks route "implement OAuth flow" # 位置参数！ npx -y ruvector@0.2.25 hooks ast-analyze src/module.ts # 位置参数！ npx -y ruvector@0.2.25 hooks ast-complexity <files...> npx -y ruvector@0.2.25 hooks diff-analyze HEAD npx -y ruvector@0.2.25 hooks coverage-route src/module.ts npx -y ruvector@0.2.25 hooks graph-cluster <files...> # spectral / Louvain npx -y ruvector@0.2.25 hooks rag-context "QUERY" npx -y ruvector@0.2.25 hooks security-scan src/ npx -y ruvector@0.2.25 hooks remember "CONTENT" | hooks recall "QUERY"

hooks init --pretrain会执行九阶段预训练管线：AST 分析 → diff 嵌入 → 覆盖率路由 → 神经训练 → 图分析 → 安全扫描 → 协同编辑模式学习 → Agent 构建 → RAG 上下文索引。

集体智能（依赖增强包）

npx -y ruvector@0.2.25 brain status|search "..."|list|drift code # 需 @ruvector/pi-brain npx -y ruvector@0.2.25 sona status|patterns "..."|stats|train|export # 需 @ruvector/ruvllm npx -y ruvector@0.2.25 llm models|embed "..."|benchmark|info # 需 @ruvector/ruvllm

身份与边缘计算（pi 网络）

npx -y ruvector@0.2.25 identity generate|show|export -o key.enc|import <file> npx -y ruvector@0.2.25 edge status|balance|tasks|join|dashboard

服务与系统

npx -y ruvector@0.2.25 server -p 8080 -g 50051 npx -y ruvector@0.2.25 decompile <npm-pkg-or-file-or-url> npx -y ruvector@0.2.25 demo --basic | --gnn | --graph npx -y ruvector@0.2.25 doctor | info | install --all | setup

端到端案例：为项目文件建库、嵌入、检索

README 给出了一个完整的落地流程（注意第 2 步的循环——0.2.25 没有内置--batch）：

# 0. 一次性初始化 /vector-setup # 1. 创建数据库 npx -y ruvector@0.2.25 create project.db -d 384 -m cosine # 2. 逐个嵌入 TypeScript 源文件 mkdir -p .vec for f in $(find src -name '*.ts'); do npx -y ruvector@0.2.25 embed text "$(cat "$f")" -o ".vec/${f//\//_}.json" done # 3. 批量插入（假设是 {id, vector, metadata} 的 JSON 数组） jq -s '[.[] | {id: input_filename, vector: .vector}]' .vec/*.json > corpus.json npx -y ruvector@0.2.25 insert project.db corpus.json # 4. 用查询向量搜索 QV=$(npx -y ruvector@0.2.25 embed text "JWT refresh-token rotation" --output -) npx -y ruvector@0.2.25 search project.db -v "$QV" -k 5 # 5. 检查索引健康度 npx -y ruvector@0.2.25 stats project.db

需要血缘追踪时，可将 1–3 步替换为 RVF 格式：

npx -y ruvector@0.2.25 rvf create project.rvf npx -y ruvector@0.2.25 rvf ingest project.rvf < corpus.json npx -y ruvector@0.2.25 rvf query project.rvf

0.2.25 的已知缺陷与规避策略

ADR 和 README 共同记录了一张"缺陷清单"，帮助用户避开上游 bug：

后果评估：这份 ADR 带来了什么

正向收益：

• 插件中每个被文档化的调用都与一个真实、且经 smoke 测试验证的 CLI 表面吻合；
• 新用户走确定性的vector-setup流程，不再撞见晦涩的 ONNX/Brain/SONA 报错；
• 评估未来 ruvector 版本时，只需对候选版本运行 smoke 测试，通过后再升级钉定版本；
• README 中的"Capabilities"表格从愿望清单变成了真正的契约。

代价：

• 升级钉定版本需要一次刻意的测试通过；ruvector 的新功能必须经过人工审查才能进入插件；
• 增强包（ruvector-onnx-embeddings-wasm、@ruvector/pi-brain、@ruvector/ruvllm）必须手动安装或通过/vector-setup安装，跳过者执行embed text时会命中文档化的错误。

中性影响：

• 插件的"Search Capabilities"特性表现在反映真实 CLI 表面：FlashAttention-3 等机制被列在attention list之下，而不是独立的搜索模式。

面向下游的验证清单

1. 版本钉定是否处处生效：grep -r "npx ruvector"不应命中任何无@0.2.25的调用；
2. MCP 注册是否使用钉定版本：claude mcp list | grep ruvector；
3. 契约是否全绿：bash plugins/ruflo-ruvector/scripts/smoke.sh期望输出11 passed, 0 failed；
4. 已移除表面是否保持移除：npx -y ruvector@0.2.25 compare应报unknown command 'compare'；
5. 插件版本是否在每次契约变更后 bump。

这套方法论对任何"包装第三方 npm 包并暴露给 Agent"的插件都具有普适价值：把版本钉定 + 按需增强包 + smoke 契约 + 移除面回归防护组合起来，文档就不会再漂移，用户得到的永远是"文档即契约、契约即测试"的确定性体验。相关的四个插件（ruflo-agentdb、ruflo-intelligence、ruflo-knowledge-graph、ruflo-rag-memory）分别在 HNSW 存储、SONA 模式学习、Graph RAG 多跳检索与简单语义搜索上与 ruvector 协同，可继续深入阅读各自 README 了解组合用法。

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo