ruflo-ruvector 完整命令手册基于 ruvector0.2.25 的向量嵌入、RVF 认知容器与自学习智能实战指南【免费下载链接】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/rufloruflo-ruvector 是 ruflo 项目中的向量数据库插件将 npm 包ruvector0.2.25的 80 个子命令封装为 Claude Code 的/vector斜杠命令覆盖 ONNX 向量嵌入、HNSW 语义检索、RVF 认知容器、GNN 图神经网络、注意力机制、hooks 自学习代码智能、Brain 集体知识库、SONA 自优化架构、Edge 边缘计算与 MCP 服务器注册。本文以 commands/vector.md 为核心骨架逐条解析全部子命令的调用形式、依赖前提与已知坑点并结合 vector-setup 技能、ADR-0001 与 smoke.sh 冒烟测试 给出可验证的实践路径。读完本文你将能独立完成从首次环境初始化、文本嵌入、建库检索到代码智能 hooks、GNN/注意力实验、Brain/SONA 集体智能与 MCP 工具注册的完整向量工作流。一、使用前提版本钉死与可选附加包所有/vector子命令底层均通过npx -y ruvector0.2.25 subcommand [options]调用。-y用于跳过 npm 交互式确认版本号0.2.25是插件契约的一部分——ADR-0001 记录了此前因未钉版本导致的真实故障ruvector0.1.x缺少brain、route、sona子命令且历史文档中引用的 2.x 功能在 npm 上并不存在。# 钉版本安装 npm install ruvector0.2.25 # 可选附加包按需安装 npm install ruvector-onnx-embeddings-wasm # 必需embed text 依赖的 ONNX WASM 运行时 npm install ruvector/pi-brain # 必需brain 子命令 npm install ruvector/ruvllm # 必需sona 子命令JS 回退与 llm 子命令 npm install ruvector/graph-node # 可选图数据库Cypher对应 graph -q ... npm install ruvector/router # 可选语义路由器对应 router --route ...附加包与子命令的依赖映射源自 ADR-0001包启用能力被门控的子命令ruvector-onnx-embeddings-wasmONNX 运行时embed text、embed adaptive、llm embedruvector/pi-brain集体大脑brain *ruvector/ruvllmRuvLLM SONA JS 回退sona *、llm *ruvector/graph-node图数据库Cyphergraph -q ...ruvector/router语义路由器router --route ...设计上这些附加包是可选扩展而非必需依赖ONNX 运行时体积庞大强制安装会惩罚只需要 hooks 路由或 RVF 存储的用户。若首次运行遇到以下报错对照安装缺失的包即可报错信息缺失包ONNX WASM files not bundled. The onnx/ directory is missing.ruvector-onnx-embeddings-wasmBrain commands require ruvector/pi-brainruvector/pi-brainSONA not available. Native error: Cannot find module /.../ruvector/sona/index.jsruvector/ruvllmJS 回退LLM commands require ruvector/ruvllmruvector/ruvllm装好后运行健康检查npx -y ruvector0.2.25 doctor它会依次检查 Node、npm、原生绑定与 Rust 环境。二、Embedding384 维 ONNX 向量生成embed系列共 4 个子命令。注意真实形式是embed text TEXTtext 为位置参数不存在embed TEXT这种旧文档写法否则会得到unknown command TEXT。# 1. 单文本嵌入ONNX all-MiniLM-L6-v2384 维 npx -y ruvector0.2.25 embed text TEXT # 2. LoRA 自适应嵌入针对特定领域微调 npx -y ruvector0.2.25 embed text TEXT --adaptive --domain code # 3. 文件嵌入先读文件再传入内容0.2.25 无 --file 标志 npx -y ruvector0.2.25 embed text $(cat path) -o path.vec.json # 4. 基准对比base 与 adaptive 对比 npx -y ruvector0.2.25 embed benchmark关键细节若embed text报ONNX WASM files not bundled先运行/vector setup或npm install ruvector-onnx-embeddings-wasm。vector-embed 技能 补充了实践要点ruvector0.2.25没有内置--batch/--glob批量标志批量嵌入需要用 shell 循环逐文件调用自适应变体--adaptive --domain code输出 LoRA 微调后的向量维度仍为 384。README 的端到端示例 给出了批量嵌入全部 TS 源文件的完整脚本# 对 src 下每个 .ts 文件嵌入并落盘 mkdir -p .vec for f in $(find src -name *.ts); do npx -y ruvector0.2.25 embed text $(cat $f) -o .vec/${f//\//_}.json done # 汇总为 JSON 数组 {id, vector, metadata} 后插入数据库 jq -s [.[] | {id: input_filename, vector: .vector}] .vec/*.json corpus.json npx -y ruvector0.2.25 insert project.db corpus.json # 用查询文本嵌入结果检索 Top-5 QV$(npx -y ruvector0.2.25 embed text JWT refresh-token rotation --output -) npx -y ruvector0.2.25 search project.db -v $QV -k 5三、数据库生命周期建库、写入、检索、备份从 commands/vector.md 第 5–10 条覆盖 HNSW 索引从创建到导入导出的完整生命周期# 5. 创建数据库维度 384距离度量 cosine npx -y ruvector0.2.25 create path -d 384 -m cosine # 6. 查看数据库统计信息 npx -y ruvector0.2.25 stats path # 7. 从 JSON 文件插入向量 npx -y ruvector0.2.25 insert database json-file # 8. 相似度检索-v 传 JSON 向量-k 指定返回条数 npx -y ruvector0.2.25 search database -v [0.1,...] -k N # 9. 导出备份默认 JSON支持 binary/parquet可压缩 npx -y ruvector0.2.25 export database -o backup.json # 10. 导入--merge 合并 / --replace 替换 npx -y ruvector0.2.25 import file -d database [--merge|--replace]距离度量在创建时固化可选cosine、euclidean、dotcreate path -m cosine|euclidean|dot。HNSW 索引有三个核心调优参数源自 vector-engineer agent参数默认值作用调优方向M16图连通度越大召回越高、内存越多efConstruction200建图质量越大索引越好、建库越慢efSearch50查询质量越大召回越高、查询越慢在 README 的能力表 中HNSW 检索延迟约 0.045ms、插入吞吐 52,000/秒、每向量内存约 50 字节这些数据来自 ruvector 自带基准而非插件自行测得使用时请以上游实际环境为准。四、RVF 认知容器带血缘追踪的向量存储RVF第 11–19 条是 ruvector 的“认知容器”格式在普通向量库之上增加了段segment、血缘派生derive与回收compact能力替代普通数据库时连同上文步骤 1–3 一并替换# 11. 创建 RVF 容器 npx -y ruvector0.2.25 rvf create path # 12. 摄取数据喂入向量/文本 npx -y ruvector0.2.25 rvf ingest path # 13. 最近邻查询 npx -y ruvector0.2.25 rvf query path # 14. 查看容器状态 npx -y ruvector0.2.25 rvf status path # 15. 查看段信息 npx -y ruvector0.2.25 rvf segments path # 16. 派生子容器血缘追踪 npx -y ruvector0.2.25 rvf derive parent child # 17. 压缩回收已删除空间 npx -y ruvector0.2.25 rvf compact path # 18. 列出 45 个参考示例库 npx -y ruvector0.2.25 rvf examples # 19. 下载参考库如 agent_memory、swarm_knowledge npx -y ruvector0.2.25 rvf download nameREADME 中给出了替代普通建库流程的 RVF 最小三连npx -y ruvector0.2.25 rvf create project.rvf npx -y ruvector0.2.25 rvf ingest project.rvf corpus.json npx -y ruvector0.2.25 rvf query project.rvfsmoke.sh 用rvf examples的输出行数≥10 个示例来验证 RVF 子命令可用性可作为环境自检的自动化手段。五、GNN图神经网络操作第 20–23 条ruvector 的 GNN 能力走真实 Rust 原生绑定CLI 暴露了四个入口# 20. 查看 GNN 状态smoke 测试要求输出 Status:...Available npx -y ruvector0.2.25 gnn info # 21. 构建/测试多头注意力 GNN 层 npx -y ruvector0.2.25 gnn layer # 22. 可微分软注意力检索 npx -y ruvector0.2.25 gnn search # 23. 5 级自适应张量压缩 npx -y ruvector0.2.25 gnn compress六、注意力机制十种可枚举的 Rust 绑定第 24–28 条。attention list是 0.2.25 中唯一能枚举全部注意力机制的入口——早期文档宣传的 FlashAttention-3、Graph RAG、Hybrid Search、DiskANN、ColBERT、Matryoshka、MLA、TurboQuant 等均没有独立的 CLI 子命令它们只是可通过attention list枚举的 Rust 原生原语见 vector-engineer.md# 24. 列出全部机制 npx -y ruvector0.2.25 attention list # DotProduct, MultiHead, Flash, Hyperbolic, Linear, MoE, GraphRoPe, EdgeFeatured, DualSpace, LocalGlobal # 25. 计算注意力 npx -y ruvector0.2.25 attention compute # 26. 注意力基准 npx -y ruvector0.2.25 attention benchmark # 27. 双曲注意力Poincare 球几何运算0.2.25 中真正的双曲表面 npx -y ruvector0.2.25 attention hyperbolic # 28. 注意力信息 npx -y ruvector0.2.25 attention info各机制及其复杂度源自 agent 文档中的对照表DotProduct O(n²)、MultiHead O(n²)、Flash O(n²) IO 优化、Hyperbolic O(n²)、Linear O(n)、MoE O(n·k)、GraphRoPe O(n²)、EdgeFeatured O(n²)、DualSpace O(n²)、LocalGlobal O(n·k)。其中 Flash 可通过attention benchmark验证双曲机制走attention hyperbolic。七、代码智能 hooks自学习工作流第 29–49 条是插件最重的部分hooks 系统让 ruvector 具备“自学习”能力路由、AST 分析、diff 分类、覆盖率路由、图聚类、RAG 上下文、安全扫描、记忆/回忆、共编辑/报错模式学习、执行轨迹记录以及 Claude Code 钩子生命周期。7.1 初始化与路由29–33# 29. 初始化完整预训练管线 按质量构建 agent npx -y ruvector0.2.25 hooks init --pretrain --build-agents quality # 30. 查看统计Q-learning 模式、向量记忆、轨迹 npx -y ruvector0.2.25 hooks stats # 31. 智能路由注意位置参数不是 --task npx -y ruvector0.2.25 hooks route DESCRIPTION # 32. 增强路由 npx -y ruvector0.2.25 hooks route-enhanced DESCRIPTION # 33. 建议上下文 npx -y ruvector0.2.25 hooks suggest-contextADR-0001 明确记录hooks route --task X会报unknown option --task必须改为位置参数hooks route X。smoke 测试对hooks route的断言是输出 JSON 中包含recommended字段。hooks init --pretrain --build-agents quality对应的 9 阶段预训练管线为AST 分析 → diff 嵌入 → 覆盖率路由 → 神经训练 → 图分析 → 安全扫描 → 共编辑模式学习 → agent 构建 → RAG 上下文索引见 vector-engineer.md。7.2 静态分析34–37# 34. AST 分析位置参数传文件 npx -y ruvector0.2.25 hooks ast-analyze file # 35. AST 复杂度可多文件输出含 cyclomatic 圈复杂度 npx -y ruvector0.2.25 hooks ast-complexity files... # 36. diff 分析git 感知默认 HEAD npx -y ruvector0.2.25 hooks diff-analyze HEAD # 37. diff 分类 npx -y ruvector0.2.25 hooks diff-classify HEAD # 38. diff 相似度 npx -y ruvector0.2.25 hooks diff-similar7.3 覆盖率与图聚类39–41# 39. 覆盖率感知路由 npx -y ruvector0.2.25 hooks coverage-route file # 40. 测试缺口建议 npx -y ruvector0.2.25 hooks coverage-suggest files... # 41. 代码图聚类谱聚类 / Louvain npx -y ruvector0.2.25 hooks graph-cluster files...注意顶层cluster子命令在 0.2.25 中被保留给分布式集群操作--status/--join/--leave/--nodes/--leader/--info状态为 Coming Soon真正的社区发现必须走hooks graph-cluster。若报graph.nodes is not iterable先运行hooks init播种图状态见 vector-cluster 技能。7.4 RAG 与安全42–43# 42. RAG 上下文检索CLI 与 MCP 下均可用 npx -y ruvector0.2.25 hooks rag-context QUERY # 43. 安全扫描先运行 hooks init npx -y ruvector0.2.25 hooks security-scan files...7.5 记忆与自学习回路44–49# 44. 记住内容 npx -y ruvector0.2.25 hooks remember CONTENT # 45. 回忆查询 npx -y ruvector0.2.25 hooks recall QUERY # 46. 共编辑记录 / 建议记录并检索一起编辑的文件 npx -y ruvector0.2.25 hooks coedit-record npx -y ruvector0.2.25 hooks coedit-suggest # 47. 错误→修复对学习 / 检索 npx -y ruvector0.2.25 hooks error-record npx -y ruvector0.2.25 hooks error-suggest # 48. 执行轨迹三段式记录 npx -y ruvector0.2.25 hooks trajectory-begin npx -y ruvector0.2.25 hooks trajectory-step npx -y ruvector0.2.25 hooks trajectory-end # 49. Claude Code 钩子生命周期 npx -y ruvector0.2.25 hooks pre-edit npx -y ruvector0.2.25 hooks post-edit npx -y ruvector0.2.25 hooks pre-command npx -y ruvector0.2.25 hooks post-command npx -y ruvector0.2.25 hooks session-start npx -y ruvector0.2.25 hooks session-end7.6 0.2.25 hooks 已知缺陷0.2.25 已知 bugforce-learn会抛intel.tick is not a function替代方案用trajectory-begin/step/end记录真实轨迹graph-mincut抛Cannot read properties of undefined替代hooks graph-clustergit-churn在 git 仓库外会失败请进入仓库内运行或使用已播种智能状态的实例。八、Native 与 Workers后台分析第 50–54 条native 系列是无外部依赖的原生 worker# 50. 列出 worker 类型security、analysis、learning npx -y ruvector0.2.25 native list # 51. 运行指定类型 worker npx -y ruvector0.2.25 native run security # 或 analysis | learning # 52. native 基准 npx -y ruvector0.2.25 native benchmark # 53. native 对比 npx -y ruvector0.2.25 native compareworkers子命令族包含triggers / presets / phases / dispatch / status / stats / cleanup / cancel / run / create / init-config全部经npx -y ruvector0.2.25 workers subcmd调用。首次调用会自动安装agentic-flow较慢这是预期行为。九、Brain集体知识库需 ruvector/pi-brain第 55–58 条Brain 提供跨实例共享的 Brainpedia 与 LoRA 权重管理。先npm install ruvector/pi-brain# 55. 状态 npx -y ruvector0.2.25 brain status # 56. 语义检索 npx -y ruvector0.2.25 brain search QUERY # 57. 分享知识条目 npx -y ruvector0.2.25 brain share TITLE # 58. 完整管理面 npx -y ruvector0.2.25 brain list # 列表 npx -y ruvector0.2.25 brain get # 获取 npx -y ruvector0.2.25 brain vote # 投票 npx -y ruvector0.2.25 brain delete # 删除 npx -y ruvector0.2.25 brain drift # 领域知识漂移检测如 brain drift code npx -y ruvector0.2.25 brain partition npx -y ruvector0.2.25 brain transfer npx -y ruvector0.2.25 brain sync npx -y ruvector0.2.25 brain page十、SONA 与 LLM 编排需 ruvector/ruvllm第 59–66 条。SONASelf-Optimizing Neural Architecture记录训练轨迹并导出学习到的权重# 59. SONA 状态 / 信息 / 统计 npx -y ruvector0.2.25 sona status npx -y ruvector0.2.25 sona info npx -y ruvector0.2.25 sona stats # 60. 模式检索 npx -y ruvector0.2.25 sona patterns QUERY # 61. 记录训练轨迹 npx -y ruvector0.2.25 sona train data # 62. 导出学习权重 npx -y ruvector0.2.25 sona exportLLM 编排子命令RuvLLM 后端# 63. 列出模型 npx -y ruvector0.2.25 llm models # 64. RuvLLM 后端嵌入 npx -y ruvector0.2.25 llm embed TEXT # 65. LLM 基准 npx -y ruvector0.2.25 llm benchmark # 66. LLM 信息 npx -y ruvector0.2.25 llm info平台差异提示源自 vector-setup 技能SONA 的原生绑定ruvector/sona不一定随 npm 包分发macOS arm64 上ruvector/ruvllm的 JS 回退已足够Linux x64 则有独立原生绑定。十一、Identity 与 Edge 计算网络11.1 pi 身份密钥67–70pi key 是 brain、edge、MCP 的身份凭证64 位十六进制字符# 67. 生成 pi key npx -y ruvector0.2.25 identity generate # 68. 查看 npx -y ruvector0.2.25 identity show # 69. 加密导出备份 npx -y ruvector0.2.25 identity export -o key.enc # 70. 导入 npx -y ruvector0.2.25 identity import file11.2 Edge 计算网络71–75# 71. 节点状态 npx -y ruvector0.2.25 edge status # 72. 查询 rUv 余额可指定节点 npx -y ruvector0.2.25 edge balance [nodeId] # 73. 任务列表 npx -y ruvector0.2.25 edge tasks # 74. 以节点身份加入网络 npx -y ruvector0.2.25 edge join # 75. 浏览器打开仪表盘 npx -y ruvector0.2.25 edge dashboard十二、服务器、反编译与演示第 76–78 条# 76. 启动服务器-p HTTP 端口、-g gRPC 端口、-d 数据目录 npx -y ruvector0.2.25 server -p 8080 # 77. 反编译目标npm 包 / 文件 / URL-f 可选 modules|single|json npx -y ruvector0.2.25 decompile npm-pkg-or-file-or-url # 78. 交互式教程 npx -y ruvector0.2.25 demo --basic # 或 --gnn | --graphserver默认 gRPC 端口 50051-g 50051可指定-d># 79. 诊断Node、npm、绑定、Rust npx -y ruvector0.2.25 doctor # 80. 版本与环境信息smoke 测试断言 CLI Version: 0.2.25 npx -y ruvector0.2.25 info # 81. 全量基准已知问题见下 npx -y ruvector0.2.25 benchmark # 82. 列出/安装可选附加组件 npx -y ruvector0.2.25 install --all # 83. 安装向导 npx -y ruvector0.2.25 setup已知问题benchmark在部分安装上会报Missing field dimensions此时可用gnn search或attention benchmark替代做基准。十四、首次运行vector-setup 一条龙针对三类高频报错ONNX WASM files not bundled、Brain commands require ruvector/pi-brain、SONA not available插件提供了/vector-setup技能一次完成安装、注册与验证# 1. 钉版本 npm install ruvector0.2.25 # 2. 安装附加包幂等只装缺失项 npm install ruvector-onnx-embeddings-wasm \ ruvector/pi-brain \ ruvector/ruvllm # 精简安装可跳过--full 额外拉取 ruvector/graph-node 与 ruvector/router # 3. 验证二进制 npx -y ruvector0.2.25 doctor npx -y ruvector0.2.25 info # 4. 注册 MCP 服务器 claude mcp add ruvector -- npx -y ruvector0.2.25 mcp start claude mcp list | grep ruvector # 5. 抽查最常用子命令 npx -y ruvector0.2.25 hooks route test npx -y ruvector0.2.25 attention list npx -y ruvector0.2.25 rvf examples # 6.可选为 brain edge 生成 pi 身份 npx -y ruvector0.2.25 identity generate npx -y ruvector0.2.25 identity show该技能不安装的内容原生 Rust 工具链仅源码构建需要、平台专属原生绑定由ruvector/core自动探测、ruvector/sona原生绑定JS 回退已足够。十五、MCP 服务器91 个工具的注册与调用ruvector0.2.25 暴露 91 个 MCP 工具vector-engineer.md 注明经ruvector mcp tools验证ADR-0001 则提到其 MCP 传输层在 minor 版本间会变化因此注册命令同样必须钉版本# 一次性注册 claude mcp add ruvector -- npx -y ruvector0.2.25 mcp start # 验证 claude mcp list | grep ruvector注册后即可直接调用 MCP 工具例如hooks_route、hooks_ast_analyze、hooks_rag_context、brain_search、attention_list。工具按能力分组的速查源自 agent 文档智能路由hooks_route、hooks_route_enhanced代码结构hooks_ast_analyze、hooks_ast_complexity变更分类hooks_diff_analyze、hooks_diff_classify测试感知hooks_coverage_route、hooks_coverage_suggest代码边界hooks_graph_mincut、hooks_graph_cluster安全检测hooks_security_scan语义上下文hooks_rag_context集体知识需 pi-brainbrain_search、brain_share、brain_statusSONA 学习需 ruvllmsona_status、sona_patterns、sona_stats注意力调度attention_list、attention_computeGNNgnn_info、gnn_layer、gnn_searchRVF 容器rvf_create、rvf_query、rvf_status十六、0.2.25 不存在的命令请勿调用经 ADR-0001 的实际审计以下命令在 0.2.25不存在或不可用切勿调用旧形式无效替代方案compare、顶层index、midstreamcreate path/stats pathcompare需自行嵌入后算余弦embed --file、embed --batch --glob自行读取文件 / shell 循环embed --model poincare正常嵌入后在用户代码中投影到 Poincare 球cluster --namespace --k顶层hooks graph-cluster files...hooks route --task X、hooks ast-analyze --file F位置参数brain agi *直接使用brain status等optimize上游 issue 401尚未在本版本发布embed neural0.2.25 无此 CLI未来版本或可提供更丰富的投影能力冒烟测试作为契约smoke.sh 将上述契约固化为 11 项自动化断言——版本钉死为 0.2.25、顶层子命令可见性hooks/embed/rvf/attention/gnn/brain/sona/create/stats/search/insert、hooks route与hooks ast-analyze位置参数、ast-complexity输出圈复杂度、attention list含 FlashAttention、rvf examples不少于 10 个示例、gnn info状态 Available、info报告 0.2.25、doctor退出码 0以及compare/midstream/index返回unknown command。运行验证bash plugins/ruflo-ruvector/scripts/smoke.sh # 预期输出11 passed, 0 failed十七、相关插件与生态位ruflo-ruvector 在 ruflo 生态中处于向量基础设施位置与以下插件协作详见 READMEruflo-agentdbHNSW 存储后端可持久化 ruvector 索引与向量元数据ruflo-intelligenceSONA 模式学习集成ruflo-knowledge-graphGraph RAG 多跳检索ruflo-rag-memory通过 ruvector 实现的轻量语义搜索典型的落地组合是用hooks graph-cluster做代码模块聚类、用hooks route做任务智能路由、用hooks rag-context做语义上下文注入、用embed textcreatesearch构建项目级语义检索再通过 MCP 工具面把这些能力开放给 Claude Code 的任意工作流。本仓库中的data/目录如clone-data.rvf与agentdb.rvf即此类向量容器的实际产物可作为观察 ruvector RVF 文件格式的现成样本。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考