rune

Rune

询问有关代码的问题。获取可核查的答案。

Rune 会将项目扫描成事实图谱，每条事实都会指向其来源的确切文件和行号。提出问题后，你会得到按相关性排序、附有引用的发现。随后，你自己的 AI 模型可以对这些发现进行解释，而 Rune 会舍弃任何缺乏证据支持的陈述。

以下是在 Express 仓库中的实际输出，由一个小型本地模型撰写解释：

$ cd express
$ rune "how does routing work"

2 insight(s):

1. lib/application.js
   Why it matters: Loads the external package `router` (var Router = require('router');)
   - logic tied to this name likely lives there, not in this repo.
   Evidence: lib/application.js:26
...
Explanation (written by local / qwen2.5:1.5b; every statement checked against cited evidence)

  - Router is the external package used for routing logic in this project.  [lib/application.js:26, lib/express.js:19]

答案很简短，因为它属实：Express 将路由交由一个独立的包处理，而 Rune 不仅指出了这一点，还展示了对应代码行。

为什么选择 Rune

• 每条陈述都有出处。 每条事实都包含文件、行号、确切代码片段和置信度。rune explain <id> 会展示任何事实背后的证据链。
• 模型由你选择。 可以使用 Anthropic、OpenAI、任何兼容 OpenAI 的 API，或本地模型。Rune 自身不带模型。
• 只读。 Rune 只会观察并报告，绝不会修改你的项目。
• 融入你的工作环境。 它是一个 MCP 服务，因此 AI 客户端可以直接使用它。

安装

Linux（x64）和 macOS（Apple Silicon）：

curl -fsSL https://raw.githubusercontent.com/thecolourfoundation/rune/main/install.sh | sh

Windows：从最新版本下载 rune-windows-x64.exe，然后在终端中运行。

安装程序会校验 SHA-256 校验和，并将 rune 放入 ~/.local/bin。

使用

cd your-project
rune "how does routing work"
rune "give me 5 architectural insights"

首次运行时会扫描项目，这需要几秒钟。之后，Rune 会打印按相关性排序的发现，并附上文件:行号证据，然后由你的模型根据这些证据撰写简短解释。

命令	作用
rune "<question>"	询问当前文件夹中的项目
rune scan [dir]	构建或重建图谱，并打印安全摘要
rune watch [dir]	在文件发生变化时持续更新图谱
rune serve [dir]	启动 MCP 服务
rune explain <id>	展示某条事实背后的证据链
rune verify [dir]	根据当前文件检查已存储的事实
rune memory ... / rune experience ...	保存项目笔记和过往结果日志

运行 rune --help 查看所有选项，并参阅 Docs.md 了解详情。

使用自己的模型

# Anthropic（早期支持）
export ANTHROPIC_API_KEY=your-key

# OpenAI 或任何兼容 OpenAI 的 API
export OPENAI_API_KEY=your-key
export RUNE_LLM_MODEL=model-name

# 使用 Ollama 的本地模型（无需密钥，数据不会离开你的设备）
export RUNE_LLM_BASE_URL=http://localhost:11434/v1
export RUNE_LLM_MODEL=model-name

模型撰写的每条陈述都必须引用 Rune 检索到的证据。对于引用了未检索内容、没有引用任何内容，或引用的文本不在相应证据中的陈述，Rune 都会将其舍弃，并告知你舍弃了多少条。

这只能检查依据是否充分，不能保证内容属实：模型仍可能误读真实证据。解释质量取决于你选择的模型。

如果未配置模型，Rune 会打印证据，然后显示设置帮助，并以代码 2 退出。添加 --evidence-only 可跳过模型。设置 RUNE_LLM_DEBUG=1 可查看模型的原始回复，以及舍弃陈述的原因。

会从你的设备发送哪些内容

只有与你的问题相关的证据会发送给你配置的模型提供商：最多 40 段简短代码片段，绝不会发送整个项目。Rune 会在发送前显示发送的片段数量。使用 --evidence-only 或本地模型，即可不发送任何内容。

在 AI 工具中使用（MCP）

Rune 是一个 MCP 服务。将任意 MCP 客户端指向它：

{"command": "rune", "args": ["serve", "/absolute/path/to/your-project"]}

客户端会获得 13 个工具，包括 rune_agent、rune_search、rune_explain、rune_verify_fact、rune_check_drift、rune_list_routes 和 rune_get_security_findings。回答会附带文件、行号和代码片段引用。这里不需要密钥，因为使用的是客户端自身的模型。

rune_agent 始终会报告快速、无需模型的 triage 判断，说明浅层证据是否足够。传入 deep: true，即可在 triage 判断问题需要时，执行更深入、由大模型驱动的调查（也可以传入 force: true，始终执行调查）——这是唯一可能调用你所配置模型的情况，其费用会像其他内容一样计入响应的令牌预算。

Rune 已列入官方 MCP Registry，登记名称为 io.github.thecolourfoundation/rune。每个版本还附带 .mcpb 捆绑包，可在 Claude Desktop 中一键安装。这些捆绑包是新推出的，尚未在 Claude Desktop 中测试。

Rune 能理解什么

• JavaScript 和 TypeScript： 导入、函数调用、React 组件和 hooks、Express 路由、Next.js 路由、Vue 组件。
• Shell、Lua、配置文件（TOML、YAML、JSON）和 Markdown。
• 安全问题： 硬编码的密钥、存在风险的 Shell 执行、GitHub Actions 工作流问题和依赖问题。

工作原理

1. 扫描。 Rune 会将文件解析为事实，每条事实都包含文件、行号、代码片段和置信度。
2. 推导。 Rune 根据这些事实得出结论，并列出每条结论所依据的事实 ID。
3. 调查。 对于问题，Rune 会检索相关事实、提出假设、根据当前文件进行核查，并对假设进行排序。
4. 先分流，需要时再升级。 快速、无需模型的检查会查看排序后的假设——包括其置信度、是否难以区分，以及问题中的术语是否匹配到任何内容——并判断答案是否足够，或问题是否需要更深入的推理。此步骤不产生费用，也不会调用模型。
5. 先解释，再验证。 你的模型会撰写解释，Rune 则会根据证据核查每一条陈述。如果 triage 将问题标记为需要深入调查，可选的深入调查步骤会综合推理所有假设的证据（仍由模型撰写，仍提供完整引用，并以相同方式验证）。

rune verify 会重新读取源文件，并告知你哪些已存储的事实与上次扫描时相比发生了变化。

须知

• 最适用于 JavaScript/TypeScript、Shell、Lua 和配置文件。目前对其他语言的支持较弱。
• Rune 会将扫描结果保存在项目内的 .rune/ 中。请将 .rune/ 添加到 .gitignore。
• 二进制文件未经签名，因此 macOS 或 Windows 可能会显示安全警告。目前尚未提供适用于 Intel Mac 或 ARM Linux 的预构建二进制文件。

未来计划

Rune 的扫描器通过提取器注册表接入，而图谱、证据和验证层并不专用于代码。计划支持其他类型的来源。目前，Rune 能理解软件项目。

贡献

欢迎提交问题和拉取请求。

许可证

MIT。由 Colour Foundation 构建。