别让每个 AI 编码会话从头读仓库：用 Rune 把代码理解图变成持续更新的本地 MCP 上下文
AI 编码工具最常见的低效，不是模型不会生成代码，而是每换一个会话、每切一次任务，它都得重新问一遍：入口在哪里？这个页面由谁渲染？某条 API 路由从哪里注册？相关组件之间有什么依赖？如果回答只能来自一轮轮文件搜索，工具调用会变多，结论也难以复查。
Rune 选择了一个很具体的切入点：在项目本地扫描代码，写出一个理解图；再把这份图作为 MCP 服务提供给 Claude Code、Cursor 或其他 MCP 客户端查询。它不是替代编辑器里的搜索，也不是要替代完整的静态分析器，而是尝试把“本次会话临时拼出来的仓库认识”变成可持续维护、可给出证据的上下文层。
这个项目采用 MIT 许可证。npm 上的 @pypl100/rune 和 PyPI 上的 north-rune 当前均为 0.2.0；前者要求 Node.js 18 及以上，后者要求 Python 3.10 及以上。仓库创建于 2026 年 7 月，仍是早期项目，因此更适合在小到中等规模的 React、Next.js 或 Express 项目中先做验证，而不是把它当成已经成熟的跨语言代码情报平台。
问题不在“能不能搜”，而在上下文是否能积累
普通的仓库检索往往是一次性动作：Agent 根据当前提问搜索文件，读到若干片段后给出判断。这个过程有三个问题。
第一，结论会随会话消失。下一次会话即使面对同一仓库，也要再次定位路由、组件和依赖。第二，结论的根据不稳定。一个“这个组件依赖某模块”的说法，如果没有文件位置与匹配片段，开发者很难快速判断它是事实、推测，还是过时的上下文。第三，仓库变化后，旧上下文容易悄悄失效：新路由、移动文件和重构都可能让先前摘要不再可靠。
Rune 的工作流可以概括为三步：rune scan 进行一次扫描，rune watch 在代码变更时重新构建理解图，rune serve 以 MCP stdio 服务暴露查询接口。扫描产物放在项目的 .rune/graph.json 中；README 表述其不会修改用户源代码。对 Agent 来说，重点不是直接读取一个长摘要，而是按问题调用概览、组件、路由、依赖和证据查询。
这种设计尤其适合“先理解，再改动”的任务。例如让 Agent 修复一个 Next.js 页面时，先问它需要改哪个入口、该页面依赖哪些组件；或者在 Express 服务里排查某个端点时，先确认路由表和文件依赖，再生成补丁。把定位阶段显式化，能减少“看似合理、实际改错层”的机会。
从本地初始化开始：让图文件跟随仓库更新
如果团队使用 Node.js，README 给出的全局安装方式如下：
npm install -g @pypl100/rune cd your-project rune init rune scan rune watch & rune serve
rune init 会为项目准备 Rune 配置；rune scan 用于立即生成当前图；随后 rune watch 持续观察代码变动，而 rune serve 则启动 MCP 服务。想避免全局安装，也可以用 npm 的临时执行方式：
cd your-project npx -p @pypl100/rune rune init npx -p @pypl100/rune rune scan
Python 生态可以安装 north-rune，但这里有一个容易踩到的边界：两个发行包都提供名为 rune 的命令。同一台机器同时安装 npm 与 pip 版本时，实际运行哪个取决于 PATH 顺序。把它接入 CI 或团队脚本前，应先执行 which -a rune，并统一安装路径或包管理方案；否则“本机能运行”不等于每位开发者运行的是同一个实现。
README 展示了以 npx 启动 MCP 服务的配置形态。下面的路径必须替换成真实项目的绝对路径：
{
"mcpServers": {
"rune": {
"command": "npx",
"args": [
"-p",
"@pypl100/rune",
"rune",
"serve",
"/absolute/path/to/your-project"
]
}
}
}
接入后，客户端可以使用 rune_get_overview 获取项目概览，使用 rune_list_components 和 rune_list_routes 查看已识别的组件与路由，使用 rune_search 做图内查询；当 Agent 需要解释一个结论时，可以调用 rune_explain。此外，README 还列出 rune_get_file_dependencies 与 rune_rescan。这里的关键是把“答案”与“证据”分开：设计评审或修复前，要求 Agent 先给出对应文件、行号和匹配文本，再讨论改动方案。
适合把它放在什么位置
Rune 目前明确针对 React 组件、Next.js 的 pages 与 app router、以及 Express 路由做识别；其他项目会获得通用的文件与 import 扫描。因此，它最适合做一层轻量的本地上下文服务，而不是承担类型检查、安全审计或构建依赖图的全部职责。
一个可执行的团队约定是：在开始跨文件改动前，先用 Rune 取得相关路由或组件清单；在提交前，重新扫描并让 Agent 检查变更是否影响已有依赖。这样，图文件是辅助决策的索引，Git diff、测试和人工审查仍然是最终正确性的依据。对涉及密钥、客户代码或受监管数据的仓库，还应把 .rune/graph.json 视作需要管理的派生产物：它可能包含源文件片段，是否提交、共享给哪个 MCP 客户端，都应有明确规则。
把 MCP 查询纳入改动前检查，而不是让它替你下结论
要把这套能力用得更稳，可以给编码 Agent 一份简短但可执行的“改动前协议”。接到跨文件需求时，先获取项目概览；若需求涉及 HTTP 接口，再列出路由；若涉及页面，再列出组件；最后针对候选文件查询依赖关系。只有当这些查询返回的证据与当前任务相符，才开始编辑。完成改动后重新扫描，并把新旧路由或组件清单与 Git diff、测试结果一起审阅。
这套流程的好处是把上下文获取从隐含提示变成显式步骤。它也提供了一个很实用的失败信号：如果图中找不到预期路由、组件或依赖，不能立刻把“未找到”解释成“不存在”。更合理的处理是回退到 git grep、框架约定和源码阅读，确认这是扫描器漏检、动态代码，还是确实没有对应实现。对动态路由、生成代码和大量 re-export 的项目，这一步尤其重要。
证据优先还有一个协作收益：它能把 Agent 的上下文消费变成可审查的输入。评审者不必相信“模型已经读过代码库”，而是可以追问它依据了哪个文件、哪一段匹配结果，以及该结果是否刚刚扫描生成。对于线上故障修复，这种顺序也有助于避免 Agent 因为一个相似文件名或过期摘要而扩大改动范围。Rune 不能消除误判，但它让误判更容易被暴露和复现。
还可以把 .rune/graph.json 当作本地缓存，而非永远可信的知识库。切换分支、更新依赖、批量重命名或合并大改动后，应主动运行一次 rune scan；当图文件与工作树的状态不一致时，优先相信源码和测试。若团队决定提交该文件，也应先确认它不会把不应共享的路径或代码片段带进仓库，并在 code review 中明确其更新是否符合预期。
先接受它的边界，才能避免把“上下文”误当“真相”
Rune 的 README 对限制写得很直接。当前提取器是启发式、基于正则的模式匹配，而不是 AST 解析；非常规组件写法、动态拼接路由字符串和深层 re-export 都可能漏检。Express 跨文件的路由前缀组合也尚不能完整还原。watch 每次变更仍会做整图重建，并不等于增量索引；大仓库上的资源消耗需要自行压测。
MCP 端同样是早期架构：单进程、stdio transport，尚未提供多客户端 daemon。换句话说，别在生产流程中假定它已经有长期运行服务应具备的并发、隔离和运维能力。最稳妥的做法，是用一个真实但可控的项目试运行：记录扫描耗时、图文件大小、识别遗漏案例，以及 Agent 是否真的减少了重复读文件；再决定是否推广。
对于 AI 编码工作流而言，持久上下文的价值不在于制造一个“全知 Agent”，而在于让每一次结论都有可检查的来处、让变化后的上下文能够重新生成。Rune 给出了一个清晰的本地 MCP 实验方向：先把代码理解做成可查询的图，再让 Agent 在证据和边界内工作。