ruvnet-brain

<div align="center">  # 🧠 RuvNet Brain ### 🧠 RuvNet Brain — [](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json) **一个便携、源代码为基础的脑部，适用于 Reuven Cohen（rUv）的 RuvNet 堆栈 — 以 Claude Code 插件的形式交付，使 Claude _使用_ 该堆栈而不是抗拒它。** [](plugin/.claude-plugin/plugin.json) [](https://www.npmjs.com/package/ruvnet-brain) [](https://github.com/stuinfla/ruvnet-brain/releases/latest) [](https://isovision.ai/ruvnet-brain/) [](LICENSE) [](#testing--proof) > **三个独立的部分分别版本控制 — 按设计，而不是漂移。下面的每个数字都是实时的（直接从其真实源读取，而非手动输入），因此它们都不会过时：** > - **`插件`** （上面的徽章）— Claude Code 插件本身：SKILL.md、基础钩子、MCP 服务器。从 [`plugin/.claude-plugin/plugin.json`](plugin/.claude-plugin/plugin.json) 读取。经常更新 — 这是行为修复落地的地方。 > - **`安装程序（npm）`** （上面的徽章）— `npx ruvnet-brain` 设置脚本。从 [npm 注册表](https://www.npmjs.com/package/ruvnet-brain) 读取。只有当安装脚本本身更改时才会移动 — 很罕见。 > - **脑部发布** （可下载的 512MB 知识包，链接到上面的“下载”徽章）— 始终解析到 [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest)，目前为 `v0.5.0-dev`。仅当基础知识库重建时才会移动 — 再次独立于上述两个。 _{由 **[Stuart Kerr](https://isovision.ai)** 在 [Isovision.ai](https://isovision.ai) 构建 · 免费及公平使用，帮助每个人利用高端代理编码。} ### [▶ 来看视觉解释](https://isovision.ai/ruvnet-brain/) _{交互式、动画演示您可以实际构建的内容 — **点击预览** 以打开它。} [](https://isovision.ai/ruvnet-brain/) </div> --- ## 首先要了解的一件事 **Reuven Cohen（rUv）构建了大约九个月的领先于当前技术水平。** 他的 RuvNet 构建块 — Ruflo、RuVector、AgentDB、agentic-flow、SPARC 等约 20 个 — 是成为主流 AI 工具的实际原型，大约四分之三个季度后。但 **Claude 在经典软件开发上进行了训练。** 将它指向 rUv 的堆栈，它无法识别工作：它会漂移，它会 **怀疑实际能力** （“ruflo 无法编辑文件”，“RuvNet 没有向量数据库 — 使用 Pinecone”），并且它会悄悄地恢复到它所知道的模式（pgvector、LangChain、手动滚动余弦循环）。新用户会遇到 **两难境地** — 一个具有革命性的工具集，没有使用手册，_和_ 一个告诉他们不要使用它的助手。 > **RuvNet Brain 是缺失的使用手册。** 它读取 rUv 的实际源代码，向 Claude 提供 _答案钥匙_，并消除 Claude 编造堆栈的许可。安装一次，指向任何存储库，新用户可以在无需成为 rUv 的情况下构建约 9 个月的前沿技术。 新颖之处在于 **结构化基础，而不是简单的检索。** 普通 RAG 只决定了要 _添加_ 到上下文中。这款产品提供了一个 `UserPromptSubmit` 钩子，该钩子在每个 **RuvNet 相关** 的回合中注入了一个基础指令 — 套件会结构化地消耗该标准输出，因此该指令始终存在，而不是一个可拒绝的建议。这是一个 **强烈、始终开启的提示** — Claude 被指向实际源代码，并被告知在每个相关回合中，在断言之前进行基础 — 而不是一个硬性阻止模型的输出。**RAG 决定添加什么；这使得基础成为模型必须积极争论才能退出默认设置。** --- ## 它解决的问题 你知道故障模式。你要求 Claude 使用 Ruflo 或 RuVector 构建，代替从 rUv 的实际代码中读取，它会调用其训练优先级：_“我们使用 pgvector 吧，” “我会手动滚动余弦相似度，” “我认为 ruflo 无法编辑文件。”_ 它会浏览，它会猜测，它会怀疑工作正常的工具 — 结果就会 **偏离** 您选择的堆栈。  <details><summary>ASCII 版本（适用于 AI / 无障碍访问）</summary> ``` 没有脑部 — 漂移 | 使用 RuvNet Brain — 基础 | 你：使用 Ruflo/RuVector 构建 | 你：相同的请求 | | | v | v Claude 回归到优先级 | 强制钩子基础该回合 | | | v | v “直接使用 pgvector” | search_ruvnet -> 引用的 rUv 源代码 手动滚动余弦相似度 | （整个文件，标记存储库 + 路径） “ruflo 无法编辑文件” | | | | v v | 在堆栈上构建（RVF/HNSW，群集） 偏离堆栈 | ``` </details> --- ## 安装 — 一行命令 ```bash npx ruvnet-brain ``` 该命令运行整个设置，并解释 **它正在执行的操作以及原因**：它从 [最新 GitHub 发布](https://github.com/stuinfla/ruvnet-brain/releases/latest) 下载脑部（~512 MB），解压到 `~/.cache/ruvnet-brain/kb`，安装其本地读取器（无云调用，无 API 密钥），并连接 Claude Code 插件 — `search_ruvnet` MCP 工具和 `UserPromptSubmit` 基础钩子 — 在用户范围内。安装程序和 `search_ruvnet` 工具在 **macOS、Linux 和 Windows** 上运行；基础/强制 **钩子是 POSIX shell**，因此它们在 macOS、Linux 和 WSL/Git-Bash 上的 Windows（在原生 Windows 上没有 WSL，搜索工具仍然有效，但自动基础钩子不会触发 — 钩子的 Node 端口在路线图中）。可以安全地重新运行，并且脑部本身始终获取当前版本，无论使用哪个安装路径 — 您只需安装一次；不需要重复下载。 > 需要最新的安装程序，甚至在上一次 npm 发布之前？`npx github:stuinfla/ruvnet-brain` 始终直接从最新的 GitHub 提交运行。 <details><summary>手动安装（单行命令自动化操作）</summary> ```bash claude plugin marketplace add stuinfla/ruvnet-brain claude plugin install ruvnet-brain@ruvnet-brain --scope user ``` 注册 `search_ruvnet` MCP 工具、基础技能和 `UserPromptSubmit` 强制钩子 — 在用户范围内全局。插件期望脑部位于 `~/.cache/ruvnet-brain/kb`（或将 `RUVNET_BRAIN_KB` 指向您自己的副本）。第一次安装可能会显示一次性信任提示，用于钩子。 </details> **然后直接提问。** _“Ruflo 如何编排代理群集，什么实现了它？”_ 钩子基础了该回合，Claude 调用 `search_ruvnet`，它从引用的源代码中回答 — 直到函数体。  --- ## 保持当前状态 — 更新如何工作 您只需安装一次。之后，三个机制让您保持在脑部的当前版本，无需您记住更新命令。 - **同意门控自动更新心跳** （`SessionStart` 钩子，`plugin/scripts/session-start.sh`）。插件在机器上运行的 **第一次** 会询问您 **一次** 是否允许在后台保持更新 — 一个有安全意识的选项，因为自我更新可以更改模型的自身指令。您的答案被记住（`~/.cache/ruvnet-brain/.auto-update-pref`），并且永远不会再次询问。在每个会话启动时，它都会进行速率限制（~15 分钟）的 3 秒上限检查实时 GitHub `plugin.json`。如果存在新插件版本 **并且** 您选择了加入，它会在后台通过 Claude Code 的受信任市场路径下载 — 但新版本是 **暂存的，而不是活动的**：Claude Code 只在进程启动时加载插件，因此 **此会话继续运行启动时的版本**，直到您重启（`claude --continue` 会将您的对话直接带回新版本）。如果您拒绝，它只会告诉您运行的命令。 512 MB 知识包更保守地处理 — **检测 + 通知仅限**，绝不自动应用，因为该包尚未加密签名，应用它会覆盖可执行工具文件（SEC-0010 #6）。 - **堆栈观察状态页脚** （`UserPromptSubmit` 钩子的始终开启的 Gate 0，`plugin/scripts/ground-ruvnet.sh`）。每个响应都以一个淡色状态行结尾 — 例如 `🧠 RuvNet Brain v1.11.0-dev · Ruflo: 是 · AgentDB 内存：开启` — 从 **文件系统基本事实** 读取，而不是印象。显示的版本始终是 **实际加载在内存中的版本**，用于此会话；如果新版本已暂存等待重启，该行会明确说明（`... vX 已暂存，重启以加载`）。因此，您永远不必想知道脑部是否开启、哪个版本正在运行，或者项目内存是否已连接。 - **夜间发布 → `releases/latest` 链** （`scripts/self-update.mjs --publish`，由 `deploy/com.ruvnet.brain-nightly.plist` LaunchAgent 在 03:15 运行）。夜间重建仅重建上游更改的存储库，**如果有任何重建**，则会增加产品版本，切割 GitHub 发布，并推进 [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest)。插件和知识包在 **一个** 版本号下移动，因此上述心跳自动拾取两者。（LaunchAgent 不会自动安装 — 启用系统调度器需要明确的属主批准。） --- ## 知识包的作用 — 堆栈 **深入代码** 早期的知识包了解 **文档和架构**。当前知识包重新索引代码丰富的存储库以获取 **完整的函数体**，针对每个存储库的实际源代码布局 — 因此“它是如何实际实现的？”会返回实现，而不是摘要： | 存储库 | 完整的函数体段落 | | |---|---:|---| | `agentic-flow` | 296 → **984** | 模型路由，ReasoningBank | | `ruv-fann` | 52 → **779** | ruv-swarm，cuda-wasm，神经分歧 | | `qudag` | → **531** | 后量子加密核心，交换，MCP | | `daa` | → **266** | 协调器，经济，规则，群集 | | `safla` | 0 → **136** | 元认知/自我修改层 | 另外：**“接管”行为管道** （下文），一个 **4 级行为测试框架**，一个构建完整性修复（空文件不再污染索引），以及一个私有存储库围栏，防止未发布的存储库进入公共知识包。 --- ## 工作原理 昂贵的工作 **一次完成，在构建时**：每个涵盖的存储库都会进行深度遍历（整个文件、完整的函数体和符号索引），嵌入到 **两个** 向量变体（MiniLM-384 用于边缘/便携性，bge-768 用于深度）并存储在磁盘上，存储在 **RVF / HNSW** 中，并提炼成一个概念 + 能力层，每个存储库的引物和卡片。这是 **90,842 个源代码块**。在 **查询时**，`search_ruvnet` 一次搜索每个存储库的存储库，汇集命中结果，并将它们通过 **一个跨编码器重新排序**，在通用尺度上 — 因此真正相关的文件获胜，无论它位于哪个存储库中 — 然后返回整个源代码文件，每个文件都由存储库和路径标记。  - **每个存储库的 RVF 存储** — 每个存储库都有自己的 HNSW 图；该工具跨存储库查询并规范化。 - **双重嵌入 + 跨编码器** — MiniLM-384 用于边缘/便携性，bge-768 用于深度；单个跨编码器重新排序将每个候选者放在一个可比较的尺度上。（跨编码器 — 一个同时读取查询 + 段落的第三个模型 — 是真正的质量杠杆，而不是两个嵌入器的融合。） - **概念/能力层** — 每个存储库的引物和能力卡片让模型基础 **能力** 声明，并将描述的需求路由到正确的存储库，而不是仅仅进行文件查找。 --- ## 它如何改变 Claude 的行为 — 它掌控一切 基础 **在每个回合中注入，而不是任其发展。** 在 RuvNet 相关的提示下，`UserPromptSubmit` 钩子将指令注入上下文；Claude 调用 `search_ruvnet`，获取标记存储库和路径的整个源代码文件，并从中回答。因为钩子的标准输出被套件在每个回合中消耗，所以指令 **始终存在** — 一个强大的基础提示在每个相关回合中。（这是一个提示，而不是一个硬性门控：钩子不能重写 Claude 的输出，所以它引导而不是阻止 — 参见 [ADR-0005](docs/adr/0005-behavioral-grounding-not-lock.md) 以获取确切的发货内容。）  而在 **构建请求** 上，脑部不会等待被告知每个步骤 — 它以 **Ruv 的方式** 运行流程： > **首先提出架构** → 一个 go/no-go → 然后端到端执行：**SPARC** （规范 → 伪代码 → 架构 → 改进 → 完成）· 模型化领域（**DDD**）并捕获 **ADR** · 启动 **并行 Ruflo 群集** · 将决策持久化到 **AgentDB** · 将设计视为构建步骤（**前端设计 + AI 图像生成**，而非“可用但丑陋”）· **测试 → 得分 1-100 → 循环到 ≥98** · 当步骤需要时，它会要求 **API 密钥** 而不是静默跳过。 下游效应：Claude **更喜欢 RuvNet 构建块而不是通用默认值** （RVF/HNSW 而非 pgvector/Pinecone，Ruflo 群集而非手动滚动编排），并驱动整个评估 → 构建 → 验证 → 评分循环，而不仅仅是回答一个问题。 --- ## 能力置信路由 脑部回答 **两种** 类型的问题。 **命名存储库或提出具体问题**，它会解析到正确的存储库（**47/48，98%**）。 **描述一个需求而无需命名存储库** — 新用户会这样做 — 它仍然会找到正确的存储库（**26/28，93%**）。以前，新用户路径很弱（**33% 在修复前**）；添加 **能力卡** — 每个构建块的用能力描述段 — 弥补了这一缺陷。  --- ## 它涵盖的内容 ~21 个 rUv 的 **构建块** 存储库，在 [ruvnet](https://github.com/ruvnet) 组织中 — 您实际上会将这些可重用的部分组成一个系统，每个部分都经过深度遍历、嵌入了两种变体、符号索引，并获得了一张能力卡。  | 存储库 | 提供的内容 | 存储库 | 提供的内容 | |---|---|---|---| | [`ruflo`](https://github.com/ruvnet/ruflo) | 代理编排/群集 | [`ruvector`](https://github.com/ruvnet/ruvector) | RVF + 磁盘上的 HNSW 向量 | | [`agentdb`](https://github.com/ruvnet/agentdb) | 代理内存 + 图谱/Cypher | [`rulake`](https://github.com/ruvnet/rulake) | 向量缓存层 | | [`ruview`](https://github.com/ruvnet/ruview) | 无摄像头 WiFi/CSI 感知（存在、姿势、生命体征） | [`agentic-flow`](https://github.com/ruvnet/agentic-flow) | 廉价的多提供商模型路由 | | [`agenticow`](https://github.com/ruvnet/agenticow) | 复制代理内存（分支 1M 向量 ~162 B） | [`sparc`](https://github.com/ruvnet/sparc) | 5 阶段构建方法论 | | [`qudag`](https://github.com/ruvnet/qudag) | 量子抗 DAG 消息传递 | [`safla`](https://github.com/ruvnet/safla) | 自我意识反馈环 | | [`ruv-fann`](https://github.com/ruvnet/ruv-FANN) | 快速神经网络（Rust/WASM）+ ruv-swarm | [`daa`](https://github.com/ruvnet/daa) | 去中心化自主代理 | | [`synthlang`](https://github.com/ruvnet/synthlang) | 提示压缩（~75% 标记削减） | [`rupixel`](https://github.com/ruvnet/rupixel) | 设备视觉嵌入 | | [`dspy.ts`](https://github.com/ruvnet/dspy.ts) | TS 中的 DSPy 样式可编程 LLM 管道 | [`fact`](https://github.com/ruvnet/fact) | 快速访问缓存工具 + 电路中断器 | | [`cve-bench`](https://github.com/ruvnet/cve-bench) | 安全修复基准 | [`agent-harness-generator`](https://github.com/ruvnet/agent-harness-generator) | 套件脚手架/元套件 | | [`rvm`](https://github.com/ruvnet/rvm) | 证明门控能力微超虚拟机 | [`rUv-dev`](https://github.com/ruvnet/rUv-dev) · [`open-claude-code`](https://github.com/ruvnet/open-claude-code) | 开发工作流 + 代理工具 | | [`cognitum-one`](https://github.com/ruvnet/cognitum-one) · [`helix`](https://github.com/ruvnet/helix) | 不在公共知识包中 | > **公共知识包中不包含** rUv 的私有 **Cognitum One** 存储库（种子，v0-appliance，平台文档） — 通过设计验证了零泄漏。 **Helix** （rUv 的本地优先健康应用程序）是一个成品，而非构建块，因此也被排除在外。 ## 测试与证明 以下所有内容均**可重复运行** —— 证明是命令的输出，而不是声明。 ```bash bash scripts/gate.sh # 通过/失败路由门控 node scripts/behavioral-l1-l4.mjs # 四级行为测试框架 node plugin/test/run-tests.mjs # 完整的插件质量保证，基于真实的 JSON-RPC ``` | 测试 | 结果 | 证明内容 | |---|---|---| | **命名/特定路由** | **47 / 48 (98%)** | 命名工具 → 正确仓库 | | **描述需求路由** | **26 / 28 (93%)** | 描述需求，无需命名 → 正确仓库（在能力卡之前为 33%） | | **上下文场景路由** | **7 / 8 (88%)** | 完整的场景提示路由正确 | | **L1–L4 行为测试框架** | **全部通过** | 路由 · 深度回忆（返回代码） · 实现（引用 API） · 协调（钩子驱动整个流程） | | **插件质量保证** | **26 / 26** | 清单、钩子触发、MCP `initialize`/`tools/list`、能力测试 | | **干净环境安装** | **3 / 3** | 下载发布的 512 MB 包 → 解压 → 查询 → 接地、引用答案 | 两个诚实的残留问题，未隐藏：一个描述的问题（“路由到更便宜的模型以降低成本”）仍然偏向 `ruflo` 而不是 `agentic-flow`（协调/成本重叠）；一个未命名的“方法论”问题路由到 `synthlang` 而不是 `sparc`。证明报告位于 [`PROOF.md`](PROOF.md)、[`DESCRIBED-PROOF.md`](DESCRIBED-PROOF.md) 和 [`HELIX-DEMO-NOHELIX.md`](HELIX-DEMO-NOHELIX.md)。 **直接查询（命令行）：** ```bash cd kb export KB_MODEL_CACHE=/path/to/models-cache node forge-ask-all.mjs --dir . --q "RuVector 如何实现 HNSW 向量搜索？" --k 3 ``` > 跨仓库答案质量**需要跨编码器**，而跨编码器需要 `npm i` 才能在包中使用。否则，搜索将退回到原始向量并排名较差。 --- ## 当前状态 这是一个 **`-dev`** 项目（参见顶部的实时版本徽章以获取确切的插件版本；可下载的知识包是一个单独的跟踪）—— 我们不声称“完成”、“完整”或“零幻觉”。 目前状态： - ✅ **基础大脑是真实且经过验证的** —— 约 21 个基础仓库，90,842 个区块，双重嵌入，跨编码器重新排序，插件（MCP 工具 + 执行钩子 + 技能），所有内容均可重新运行。 - ✅ **代码级深度** —— 富含代码的仓库被索引到完整的函数体；“如何实现？”返回实现。已在发布的包中验证（干净环境 3/3）。 - ✅ **路由保持** —— 命名 47/48，描述 26/28，场景 7/8；行为 L1–L4 全部通过；私有存储库与公共包隔离（验证无泄漏）。 - ⚠️ **两个路由残留问题** （上面）—— 已暴露，未隐藏。 - ✅ **已发布到 npm** —— `npx ruvnet-brain`（简写形式）；`npx github:stuinfla/ruvnet-brain` 始终跟踪最新提交，如果您想要更新鲜的版本。 - ⏳ **全自主工程循环** （ [ADR-0008](docs/adr/) ）—— 行为钩子 **驱动** 评估 → SPARC → ADR/DDD → 质量保证 → 评分循环；通用始终循环到 ≥98 引擎是下一阶段。 --- ## 内容列表 - `kb/` —— 大脑：每个仓库的 `.rvf` + `.big.rvf` 存储、全文副车、符号索引、每个仓库的启动器、概念存储和 `forge-*` 查询工具（命令行 + MCP `search_ruvnet`）。 - `plugin/` —— Claude Code 插件（MCP 服务器、接地技能、`UserPromptSubmit` 执行钩子、市场清单、测试套件）。 - `scripts/` —— `gate.sh`（路由门控）、`behavioral-l1-l4.mjs`（行为测试框架）、`prove.mjs`、`build-bundle.mjs`、`brain-stamp.mjs`。 - `docs/` —— [`VISION.md`](docs/VISION.md) （原因）、 [`adr/`](docs/adr/) （锁定决策，包括 ADR-0008）、 [`DDD.md`](docs/DDD.md)。 - `explainer/` —— [实时解释器](https://isovision.ai/ruvnet-brain/) 的源代码。 - `SPEC.md` · `PROGRESS.md` —— 主规格和带时间戳的构建日志。 大脑二进制文件通过 [Release](https://github.com/stuinfla/ruvnet-brain/releases/tag/v0.5.0-dev) 发布，而不是 git —— fresh clone 很轻量；`npx` 获取 512 MB 包。 --- ## 链接 - **▶ 实时解释器：** https://isovision.ai/ruvnet-brain/ - **下载/发布：** https://github.com/stuinfla/ruvnet-brain/releases/tag/v0.5.0-dev - **rUv 的 RuvNet 组织：** https://github.com/ruvnet - **构建者：** [Stuart Kerr — Isovision.ai](https://isovision.ai) <div align="center">_{MIT 许可 · 免费及公平使用 · 基于 rUv 的真实源代码，每次引用。}</div>