inth3shadows/runecho

# 运行 Echo [](https://github.com/inth3shadows/runecho/actions/workflows/ci.yml) RunEcho 是一个确定性的 **AI 编程代理的代码真值预言机**。它为 助手（Claude Code、Codex 或任何 MCP 客户端）提供了一种关于仓库中实际存在哪些 符号以及在两个时间点之间*结构上*发生了什么变化的基准真实视图—— 从而让代理能够基于事实做出判断，而不是盲目猜测。 它是 **无关模型且厂商中立的**：不需要 LLM，不需要 API 密钥，也不需要网络。相同的 代码会产生相同的答案。其核心价值就是确定性。 ## 为什么需要 RunEcho 编程代理非常有用，但它们经常犯以下三类错误： - 引用不存在的函数或类型 - 对结构性更改的描述不准确 - 在代码更新后，仍然基于过时的仓库状态进行推理 RunEcho 的存在就是为了给这些代理提供一个 **本地事实来源**，让它们在 发言、编辑或提交之前可以进行查询。 在以下情况可以使用它： - 确定性地回答“这个符号是否真的存在？” - 获取结构化 diff，而不是关于更改内容的模糊总结 - 使用防护机制，在虚构的辅助调用进入你的仓库之前将其捕获 如果你面临的主要问题是广泛的语义搜索或通用代码库探索， 那么 RunEcho 并不打算解决这些问题。它的职责更狭窄：**验证仓库事实并 减少产生幻觉的代码更改**。 ## 工作原理 RunEcho 将你的源代码解析为一种紧凑的 **中间表示（IR）**： 每个文件包含：其内容哈希值以及它声明的函数、类、导出和导入。 IR 具有确定性的根哈希值，因此“结构是否发生了变化？” 变成了低成本的哈希比较，而“发生了什么变化？”则变成了结构化 diff。 该 IR 的快照存储在一个单一的中心历史数据库中。每个 注册的仓库都有一个稳定的身份标识，因此预言机可以回答关于你任何 仓库的问题，并计算任意两个快照之间的偏差。 整个表面积由三个二进制文件组成： - **`runecho-ir`** — 一个 CLI，用于注册仓库、对其进行索引、获取快照，并从终端检查 diff 和变动率。 - **`runecho-mcp`** — 一个 stdio MCP 服务器，向 AI 代理公开只读的预言机工具 （`structure`、`diff`、`hash`、`status`、`health`、`locate`）。 `locate` 确定性地回答“符号 X 在哪里”（名称 → 文件:行号），因此 代理无需 grep 或猜测即可找到定义。 - **`runecho-guard`** — 一个防护工具，用于根据已索引的 IR 检查新代码，并 标记对不存在符号的引用（很可能是幻觉）。它可以作为 git pre-commit hook 运行，或者作为 Claude Code 的 `PreToolUse` hook 运行，在每次 `Edit`/`Write`/`MultiEdit` 落地之前对其进行审查。 ``` source ──▶ parser ──▶ IR (hashed) ──▶ snapshot ──▶ ~/.runecho/history.db │ AI agent ──(MCP)──▶ runecho-mcp ──▶ structure / diff / hash / ... │ git commit / agent edit ──▶ runecho-guard ──▶ "symbol X doesn't exist — block/ask" ``` ## 前置条件 - **Go 1.24+** 用于构建（不需要其他 runtime；二进制文件是自包含的）。 - 一个 POSIX 或 Windows shell。存储默认位于 `~/.runecho/` 下。 - 无需外部服务，无需 API 密钥。 目前支持解析的语言：**Go、JavaScript、TypeScript、JSX、TSX 和 Python**。 提取过程是有意设计为浅层且确定性的：只提取顶层结构，而不进行 完整的语义分析。 ## 快速开始 1. 构建并将二进制文件安装到 `~/.local/bin`： bash install.sh 2. 注册一个仓库并捕获其当前结构： runecho-ir repo add /path/to/your/repo runecho-ir repo reindex # 名称由 `repo add` 显示 如果你想注册的目录并不是你想解析的目录，请设置 一个单独的源根目录： runecho-ir repo add /path/to/worktree --source-root=/path/to/source 3. 查看已注册的内容并询问自上次快照以来的偏差： runecho-ir repo list runecho-ir diff --since=reindex /path/to/your/repo 4. 将预言机注册到你的 AI 代理中，以便它可以直接查询： claude mcp add runecho -- ~/.local/bin/runecho-mcp 对于 Codex，请将此内容添加到 `~/.codex/config.toml`： [mcp_servers.runecho] command = "/home/YOUR_USER/.local/bin/runecho-mcp" # 绝对路径；TOML 不会展开 ~ 5. 在 Claude Code 中安装编辑时防护工具： bash install.sh --print-hook-config 这会打印出用于 `~/.claude/settings.json` 的 `PreToolUse` 代码片段。如果你希望 RunEcho 在助手的编辑被 写入之前对其进行审查，这是 主要的集成方式。 6. （可选）在你已经注册的仓库中安装提交时防护工具： bash install.sh --hook # 在目标仓库的根目录下运行 它会阻止那些调用了在已索引代码中不存在的函数的提交 （当存在接近的匹配项时，会提供“你是想用 …… 吗？”的建议）。你可以通过 `RUNECHO_GUARD_SKIP=1 git commit …` 跳过任何 单次提交。 ## 目前的局限性 当你需要 **确定性的结构和防护机制**， 而不是通用代码智能时，RunEcho 的作用最为强大。 - 它追踪顶层符号以及导入/导出，而不是完整的类型信息。 - 所有解析器都是有意的浅层解析（基于行级 regex，而不是 AST）。每种语言都有 已知的缺陷——请参阅 [解析器能力矩阵](TECHNICAL.md#parser-capability-matrix) 以获取每种语言的详细客观说明。 - 防护工具寻找的是常见的幻觉形式：未解析的 **裸调用**。 它并不试图验证每一个限定调用或动态调度路径。 - 快照、diff 和哈希查询都是本地且确定性的。这里没有 语义搜索、embedding 索引或托管控制平面。 ## 项目结构 | 路径 | 用途 | |---|---| | `cmd/runecho-ir/` | CLI：index, snapshot, diff, log, churn, verify, truth-trail, validate-claims, repo, backup | | `cmd/runecho-mcp/` | stdio MCP 预言机服务器 | | `cmd/runecho-guard/` | 防护工具：pre-commit 模式 + Claude Code hook 模式 | | `internal/parser/` | 各语言结构提取（Go/JS/TS/Python） | | `internal/ir/` | IR 构建，确定性哈希，JSON 存储 | | `internal/snapshot/` | 中心存储：迁移，注册表，diff，变动率，备份 | | `internal/mcp/` | 最小化 MCP 管道 + 预言机工具 | | `internal/guard/` | Diff 解析，符号提取，验证，did-you-mean | | `internal/claims/` | 从散文中提取符号引用（`validate-claims`, `truth-trail --text`） | | `internal/gitutil/` | 规范的 git-common-dir 解析（worktree 身份） | | `install.sh` | 构建全部三个二进制文件；`--hook` 安装 pre-commit 防护工具 | ## 相关文档 - [技术参考](TECHNICAL.md) — 架构，存储 schema，IR，MCP 工具，维护 - [使用指南](USAGE.md) — 日常操作：注册仓库，集成，读取偏差，故障排除 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI编程助手, EVTX分析, MCP, 云安全监控, 代码分析, 凭证管理, 开发辅助, 文档结构分析, 日志审计, 静态分析