企业官网建设流程全解析

ruflo-ruvector 完整命令手册：基于 ruvector@0.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/ruflo

ruflo-ruvector 是 ruflo 项目中的向量数据库插件，将 npm 包ruvector@0.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 ruvector@0.2.25 <subcommand> [options]调用。-y用于跳过 npm 交互式确认，版本号0.2.25是插件契约的一部分——ADR-0001 记录了此前因未钉版本导致的真实故障：ruvector@0.1.x缺少brain、route、sona子命令，且历史文档中引用的 2.x 功能在 npm 上并不存在。

# 钉版本安装 npm install ruvector@0.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）：

设计上这些附加包是可选扩展而非必需依赖：ONNX 运行时体积庞大，强制安装会惩罚只需要 hooks 路由或 RVF 存储的用户。若首次运行遇到以下报错，对照安装缺失的包即可：

装好后运行健康检查：npx -y ruvector@0.2.25 doctor，它会依次检查 Node、npm、原生绑定与 Rust 环境。

二、Embedding：384 维 ONNX 向量生成

embed系列共 4 个子命令。注意真实形式是embed text "TEXT"（text 为位置参数），不存在embed "TEXT"这种旧文档写法，否则会得到unknown command 'TEXT'。

# 1. 单文本嵌入（ONNX all-MiniLM-L6-v2，384 维） npx -y ruvector@0.2.25 embed text "TEXT" # 2. LoRA 自适应嵌入，针对特定领域微调 npx -y ruvector@0.2.25 embed text "TEXT" --adaptive --domain code # 3. 文件嵌入：先读文件再传入内容（0.2.25 无 --file 标志） npx -y ruvector@0.2.25 embed text "$(cat <path>)" -o <path>.vec.json # 4. 基准对比：base 与 adaptive 对比 npx -y ruvector@0.2.25 embed benchmark

关键细节：若embed text报ONNX WASM files not bundled，先运行/vector setup或npm install ruvector-onnx-embeddings-wasm。vector-embed 技能 补充了实践要点：ruvector@0.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 ruvector@0.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 ruvector@0.2.25 insert project.db corpus.json # 用查询文本嵌入结果检索 Top-5 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

三、数据库生命周期：建库、写入、检索、备份

从 commands/vector.md 第 5–10 条，覆盖 HNSW 索引从创建到导入导出的完整生命周期：

# 5. 创建数据库：维度 384，距离度量 cosine npx -y ruvector@0.2.25 create <path> -d 384 -m cosine # 6. 查看数据库统计信息 npx -y ruvector@0.2.25 stats <path> # 7. 从 JSON 文件插入向量 npx -y ruvector@0.2.25 insert <database> <json-file> # 8. 相似度检索：-v 传 JSON 向量，-k 指定返回条数 npx -y ruvector@0.2.25 search <database> -v '[0.1,...]' -k N # 9. 导出备份（默认 JSON，支持 binary/parquet，可压缩） npx -y ruvector@0.2.25 export <database> -o backup.json # 10. 导入（--merge 合并 / --replace 替换） npx -y ruvector@0.2.25 import <file> -d <database> [--merge|--replace]

距离度量在创建时固化，可选cosine、euclidean、dot（create <path> -m cosine|euclidean|dot）。HNSW 索引有三个核心调优参数（源自 vector-engineer agent）：

在 README 的能力表 中，HNSW 检索延迟约 0.045ms、插入吞吐 52,000+/秒、每向量内存约 50 字节，这些数据来自 ruvector 自带基准而非插件自行测得，使用时请以上游实际环境为准。

四、RVF 认知容器：带血缘追踪的向量存储

RVF（第 11–19 条）是 ruvector 的“认知容器”格式，在普通向量库之上增加了段（segment）、血缘派生（derive）与回收（compact）能力，替代普通数据库时连同上文步骤 1–3 一并替换：

# 11. 创建 RVF 容器 npx -y ruvector@0.2.25 rvf create <path> # 12. 摄取数据（喂入向量/文本） npx -y ruvector@0.2.25 rvf ingest <path> # 13. 最近邻查询 npx -y ruvector@0.2.25 rvf query <path> # 14. 查看容器状态 npx -y ruvector@0.2.25 rvf status <path> # 15. 查看段信息 npx -y ruvector@0.2.25 rvf segments <path> # 16. 派生子容器（血缘追踪） npx -y ruvector@0.2.25 rvf derive <parent> <child> # 17. 压缩回收已删除空间 npx -y ruvector@0.2.25 rvf compact <path> # 18. 列出 45 个参考示例库 npx -y ruvector@0.2.25 rvf examples # 19. 下载参考库（如 agent_memory、swarm_knowledge） npx -y ruvector@0.2.25 rvf download <name>

README 中给出了替代普通建库流程的 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

smoke.sh 用rvf examples的输出行数（≥10 个示例）来验证 RVF 子命令可用性，可作为环境自检的自动化手段。

五、GNN：图神经网络操作

第 20–23 条，ruvector 的 GNN 能力走真实 Rust 原生绑定，CLI 暴露了四个入口：

# 20. 查看 GNN 状态（smoke 测试要求输出 "Status:...Available"） npx -y ruvector@0.2.25 gnn info # 21. 构建/测试多头注意力 GNN 层 npx -y ruvector@0.2.25 gnn layer # 22. 可微分软注意力检索 npx -y ruvector@0.2.25 gnn search # 23. 5 级自适应张量压缩 npx -y ruvector@0.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 ruvector@0.2.25 attention list # DotProduct, MultiHead, Flash, Hyperbolic, Linear, MoE, GraphRoPe, EdgeFeatured, DualSpace, LocalGlobal # 25. 计算注意力 npx -y ruvector@0.2.25 attention compute # 26. 注意力基准 npx -y ruvector@0.2.25 attention benchmark # 27. 双曲注意力：Poincare 球几何运算（0.2.25 中真正的双曲表面） npx -y ruvector@0.2.25 attention hyperbolic # 28. 注意力信息 npx -y ruvector@0.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 ruvector@0.2.25 hooks init --pretrain --build-agents quality # 30. 查看统计：Q-learning 模式、向量记忆、轨迹 npx -y ruvector@0.2.25 hooks stats # 31. 智能路由（注意：位置参数，不是 --task） npx -y ruvector@0.2.25 hooks route "DESCRIPTION" # 32. 增强路由 npx -y ruvector@0.2.25 hooks route-enhanced "DESCRIPTION" # 33. 建议上下文 npx -y ruvector@0.2.25 hooks suggest-context

ADR-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 ruvector@0.2.25 hooks ast-analyze <file> # 35. AST 复杂度（可多文件，输出含 cyclomatic 圈复杂度） npx -y ruvector@0.2.25 hooks ast-complexity <files...> # 36. diff 分析（git 感知，默认 HEAD） npx -y ruvector@0.2.25 hooks diff-analyze HEAD # 37. diff 分类 npx -y ruvector@0.2.25 hooks diff-classify HEAD # 38. diff 相似度 npx -y ruvector@0.2.25 hooks diff-similar

7.3 覆盖率与图聚类（39–41）

# 39. 覆盖率感知路由 npx -y ruvector@0.2.25 hooks coverage-route <file> # 40. 测试缺口建议 npx -y ruvector@0.2.25 hooks coverage-suggest <files...> # 41. 代码图聚类（谱聚类 / Louvain） npx -y ruvector@0.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 ruvector@0.2.25 hooks rag-context "QUERY" # 43. 安全扫描（先运行 hooks init） npx -y ruvector@0.2.25 hooks security-scan <files...>

7.5 记忆与自学习回路（44–49）

# 44. 记住内容 npx -y ruvector@0.2.25 hooks remember "CONTENT" # 45. 回忆查询 npx -y ruvector@0.2.25 hooks recall "QUERY" # 46. 共编辑记录 / 建议：记录并检索一起编辑的文件 npx -y ruvector@0.2.25 hooks coedit-record npx -y ruvector@0.2.25 hooks coedit-suggest # 47. 错误→修复对学习 / 检索 npx -y ruvector@0.2.25 hooks error-record npx -y ruvector@0.2.25 hooks error-suggest # 48. 执行轨迹三段式记录 npx -y ruvector@0.2.25 hooks trajectory-begin npx -y ruvector@0.2.25 hooks trajectory-step npx -y ruvector@0.2.25 hooks trajectory-end # 49. Claude Code 钩子生命周期 npx -y ruvector@0.2.25 hooks pre-edit npx -y ruvector@0.2.25 hooks post-edit npx -y ruvector@0.2.25 hooks pre-command npx -y ruvector@0.2.25 hooks post-command npx -y ruvector@0.2.25 hooks session-start npx -y ruvector@0.2.25 hooks session-end

7.6 0.2.25 hooks 已知缺陷

0.2.25 已知 bug：force-learn会抛intel.tick is not a function（替代方案：用trajectory-begin/step/end记录真实轨迹）；graph-mincut抛Cannot read properties of undefined（替代：hooks graph-cluster）；git-churn在 git 仓库外会失败（请进入仓库内运行或使用已播种智能状态的实例）。

八、Native 与 Workers：后台分析

第 50–54 条，native 系列是无外部依赖的原生 worker：

# 50. 列出 worker 类型（security、analysis、learning） npx -y ruvector@0.2.25 native list # 51. 运行指定类型 worker npx -y ruvector@0.2.25 native run security # 或 analysis | learning # 52. native 基准 npx -y ruvector@0.2.25 native benchmark # 53. native 对比 npx -y ruvector@0.2.25 native compare

workers子命令族包含triggers / presets / phases / dispatch / status / stats / cleanup / cancel / run / create / init-config，全部经npx -y ruvector@0.2.25 workers <subcmd>调用。首次调用会自动安装agentic-flow（较慢），这是预期行为。

九、Brain：集体知识库（需 @ruvector/pi-brain）

第 55–58 条，Brain 提供跨实例共享的 Brainpedia 与 LoRA 权重管理。先npm install @ruvector/pi-brain：

# 55. 状态 npx -y ruvector@0.2.25 brain status # 56. 语义检索 npx -y ruvector@0.2.25 brain search "QUERY" # 57. 分享知识条目 npx -y ruvector@0.2.25 brain share "TITLE" # 58. 完整管理面 npx -y ruvector@0.2.25 brain list # 列表 npx -y ruvector@0.2.25 brain get # 获取 npx -y ruvector@0.2.25 brain vote # 投票 npx -y ruvector@0.2.25 brain delete # 删除 npx -y ruvector@0.2.25 brain drift # 领域知识漂移检测（如 brain drift code） npx -y ruvector@0.2.25 brain partition npx -y ruvector@0.2.25 brain transfer npx -y ruvector@0.2.25 brain sync npx -y ruvector@0.2.25 brain page

十、SONA 与 LLM 编排（需 @ruvector/ruvllm）

第 59–66 条。SONA（Self-Optimizing Neural Architecture）记录训练轨迹并导出学习到的权重：

# 59. SONA 状态 / 信息 / 统计 npx -y ruvector@0.2.25 sona status npx -y ruvector@0.2.25 sona info npx -y ruvector@0.2.25 sona stats # 60. 模式检索 npx -y ruvector@0.2.25 sona patterns "QUERY" # 61. 记录训练轨迹 npx -y ruvector@0.2.25 sona train <data> # 62. 导出学习权重 npx -y ruvector@0.2.25 sona export

LLM 编排子命令（RuvLLM 后端）：

# 63. 列出模型 npx -y ruvector@0.2.25 llm models # 64. RuvLLM 后端嵌入 npx -y ruvector@0.2.25 llm embed "TEXT" # 65. LLM 基准 npx -y ruvector@0.2.25 llm benchmark # 66. LLM 信息 npx -y ruvector@0.2.25 llm info

平台差异提示（源自 vector-setup 技能）：SONA 的原生绑定@ruvector/sona不一定随 npm 包分发；macOS arm64 上@ruvector/ruvllm的 JS 回退已足够，Linux x64 则有独立原生绑定。

十一、Identity 与 Edge 计算网络

11.1 pi 身份密钥（67–70）

pi key 是 brain、edge、MCP 的身份凭证，64 位十六进制字符：

# 67. 生成 pi key npx -y ruvector@0.2.25 identity generate # 68. 查看 npx -y ruvector@0.2.25 identity show # 69. 加密导出备份 npx -y ruvector@0.2.25 identity export -o key.enc # 70. 导入 npx -y ruvector@0.2.25 identity import <file>

11.2 Edge 计算网络（71–75）

# 71. 节点状态 npx -y ruvector@0.2.25 edge status # 72. 查询 rUv 余额（可指定节点） npx -y ruvector@0.2.25 edge balance [nodeId] # 73. 任务列表 npx -y ruvector@0.2.25 edge tasks # 74. 以节点身份加入网络 npx -y ruvector@0.2.25 edge join # 75. 浏览器打开仪表盘 npx -y ruvector@0.2.25 edge dashboard

十二、服务器、反编译与演示

第 76–78 条：

# 76. 启动服务器：-p HTTP 端口、-g gRPC 端口、-d 数据目录 npx -y ruvector@0.2.25 server -p 8080 # 77. 反编译目标（npm 包 / 文件 / URL），-f 可选 modules|single|json npx -y ruvector@0.2.25 decompile <npm-pkg-or-file-or-url> # 78. 交互式教程 npx -y ruvector@0.2.25 demo --basic # 或 --gnn | --graph

server默认 gRPC 端口 50051（-g 50051），可指定-d># 79. 诊断：Node、npm、绑定、Rust npx -y ruvector@0.2.25 doctor # 80. 版本与环境信息（smoke 测试断言 "CLI Version: 0.2.25"） npx -y ruvector@0.2.25 info # 81. 全量基准（已知问题见下） npx -y ruvector@0.2.25 benchmark # 82. 列出/安装可选附加组件 npx -y ruvector@0.2.25 install --all # 83. 安装向导 npx -y ruvector@0.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 ruvector@0.2.25 # 2. 安装附加包（幂等，只装缺失项） npm install ruvector-onnx-embeddings-wasm \ @ruvector/pi-brain \ @ruvector/ruvllm # 精简安装可跳过；--full 额外拉取 @ruvector/graph-node 与 @ruvector/router # 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原生绑定（JS 回退已足够）。

十五、MCP 服务器：91 个工具的注册与调用

ruvector@0.2.25 暴露 91 个 MCP 工具（vector-engineer.md 注明经ruvector mcp tools验证；ADR-0001 则提到其 MCP 传输层在 minor 版本间会变化，因此注册命令同样必须钉版本）：

# 一次性注册 claude mcp add ruvector -- npx -y ruvector@0.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-brain）：brain_search、brain_share、brain_status
• SONA 学习（需 ruvllm）：sona_status、sona_patterns、sona_stats
• 注意力调度：attention_list、attention_compute
• GNN：gnn_info、gnn_layer、gnn_search
• RVF 容器：rvf_create、rvf_query、rvf_status

十六、0.2.25 不存在的命令：请勿调用

经 ADR-0001 的实际审计，以下命令在 0.2.25不存在或不可用，切勿调用：

冒烟测试作为契约：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 生态中处于向量基础设施位置，与以下插件协作（详见 README）：

• ruflo-agentdb：HNSW 存储后端，可持久化 ruvector 索引与向量元数据
• ruflo-intelligence：SONA 模式学习集成
• ruflo-knowledge-graph：Graph RAG 多跳检索
• ruflo-rag-memory：通过 ruvector 实现的轻量语义搜索

典型的落地组合是：用hooks graph-cluster做代码模块聚类、用hooks route做任务智能路由、用hooks rag-context做语义上下文注入、用embed text+create+search构建项目级语义检索，再通过 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