rjkaes/trueline-mcp

# trueline-mcp [](https://github.com/rjkaes/trueline-mcp/actions/workflows/ci.yml) 一个 [MCP](https://modelcontextprotocol.io/) 插件，为 AI 编程代理提供基于哈希验证的文件编辑和针对性读取功能。支持 Claude Code、Gemini CLI、VS Code Copilot、OpenCode 和 Codex CLI。 ## 安装 **Claude Code**（推荐；自动配置 hooks）： ``` /plugin marketplace add rjkaes/trueline-mcp /plugin install trueline-mcp@trueline-mcp ``` **其他平台**（Gemini CLI、VS Code Copilot、OpenCode、Codex CLI）： 请参阅 [INSTALL.md](INSTALL.md) 获取针对特定平台的配置指南。 **CLI（无 MCP）：** 对于使用 shell 命令而非 MCP 的代理，请使用 `npm i -g trueline-mcp` 进行全局安装，并将 `configs/cli/instructions.md` 添加到您代理的系统提示词（system prompt）中。详情请参阅 [INSTALL.md](INSTALL.md#cli-no-mcp)。 ## 为什么需要 AI 编程代理为了寻找单个函数会读取整个文件，然后将其要替换的所有内容原样输出。这两种行为都浪费了上下文：包含的要么是代理已经知晓的内容，要么是根本不需要的内容。这些上下文不仅消耗资金，还会占用对话窗口，进而限制了单次会话中能处理的实际工作量。 更糟糕的是，内置的编辑工具是通过字符串内容进行匹配的。如果代理产生幻觉（hallucinate）、使用了过期的上下文，或者遇到歧义匹配，您的代码就会被静默破坏。 trueline 解决了这两个问题：它读取得更少，写入得更少，并且会拒绝所有与文件实际内容不匹配的编辑操作。 ## 工作原理 trueline 提供了围绕三个工作流组织的六个 MCP 工具。 ### 探索：读取前先理解 `trueline_outline` 返回任何基于 AST 的文件结构大纲：包含函数、类、声明及其行范围。对于典型的源文件，这只需要 10-20 行，而不是几百行。 ``` 1-10: (10 imports) 12-12: const VERSION = pkg.version; 14-17: const server = new McpServer({ 25-45: async function resolveAllowedDirs(): Promise { 49-69: server.registerTool( 71-92: server.registerTool( (12 symbols, 139 source lines) ``` 代理首先查看完整结构，然后使用 `trueline_read` 仅获取所需的行范围。行范围可以直接在路径上内联指定： ``` file_paths: ["src/server.ts:25-45", "src/utils.ts:1-10,80-90"] ``` 一个 500 行的文件，而代理只需要其中的一个 20 行的函数？它只会读取这 20 行，而不是 500 行。还可以在单次调用中读取多个文件的不同范围。 `trueline_search` 通过字面字符串或 regex 查找对应行，并返回带有可直接编辑引用（refs）的结果，而无需经历大纲或读取步骤。对于代理明确知道目标位置的定向编辑来说，这是最快的路径。 ### 编辑：精简且经过验证 内置的编辑工具要求代理回显（echo back）所替换的旧文本。`trueline_edit` 将其替换为紧凑的行范围引用和内容哈希。代理只需输出新内容即可。 这种节省程度与被替换代码块的大小成正比。单行修改的节省可能不明显；但替换 30 行旧代码，可以为代理省去再次输出这 30 行的开销。 支持在单次调用中批量处理多个编辑，并实现原子化应用。 ### 审查：语义化差异 `trueline_changes` 提供基于 AST 的结构变更摘要（与 git ref 进行对比）。它不返回原始的行差异，而是报告新增/删除/重命名的符号、签名变更以及逻辑修改，并附带内联的微型差异（mini-diffs）。传入 `["*"]` 即可一次性对比所有已变更的文件。 ### 哈希验证：拒绝静默破坏 从 `trueline_read` 和 `trueline_search` 获取的每一行都带有内容哈希。每次编辑都必须提供这些哈希，以证明代理正在修改的内容与其预期一致。 如果文件在代理读取后发生了更改（如并发编辑、构建步骤或其他工具介入），编辑将被拒绝。如果代理产生幻觉，输出的内容与磁盘上的实际文件不匹配，编辑将被拒绝。如果代理锁定了错误的行，编辑也将被拒绝。除非哈希值完全匹配，否则任何内容都不会被写入磁盘。 `trueline_verify` 用于检查当前持有的引用（refs）是否依然有效，且无需重新读取文件。如果内容未发生更改（这也是最常见的情况），其响应仅需一行。 ## 代理的实际使用方式 trueline 不仅仅是注册工具然后寄希望于代理会去使用它们。在支持 hooks 的平台上，它会主动介入并接管代理的工作流： - **SessionStart** 会注入指令，告知代理如何以及何时使用每个 trueline 工具，并根据不同平台进行专门校准。 - **PreToolUse** 会拦截对内置读取和编辑工具的调用，将大于 3 KB 的文件读取重定向到 trueline，并完全阻止未经哈希验证的编辑操作。 - **内置技能（Shipped skill）**（`skills/trueline-workflow/SKILL.md`）会在处理任何文件编辑提示词时自动发现，为支持 Claude Code 技能的客户端提供更丰富的示例和工作流指导。 在支持 hooks 的环境中，代理的合规率约为 98%。如果不使用 hooks（在仅支持指令注入的平台如 OpenCode 和 Codex CLI 上），合规率约为 60%。指令文件本身依然能发挥作用，但 hooks 机制才使其变得真正可靠。 这些指令并非千篇一律的通用模板。它们会引用每个平台原生的工具名称（如 Claude Code 上的 `Read`/`Edit`，Gemini CLI 上的 `read_file`/`edit_file`，OpenCode 上的 `view`/`edit`），并据此提供量身定制的建议。 ## 最佳应用场景 trueline 的额外开销在于每次工具调用产生的一次 MCP 往返。对于小文件（小于约 3 KB），使用内置工具即可，它们非常高效且不会被拦截。 其核心价值体现在处理大型文件和多文件编辑会话时：定向读取和精简编辑能有效避免将成百上千行冗余文本送入上下文窗口。 在一次典型的 20 轮对话会话中（涉及探索 8 个文件并编辑 3 个文件），trueline 大约能节省 11,000 个中段会话上下文 token，并且凭借更精简的指令，每轮对话还能额外减少 623 个 token。据估算，这相当于每场会话通过降低 API 调用成本节省了约 1.58 美元。 ## 设计 请参阅 [DESIGN.md](DESIGN.md) 了解协议规范、哈希算法细节、流式传输架构以及安全模型。 ## 开发 需要 [Bun](https://bun.sh) ≥ 1.3。 ``` bun install # install dependencies bun test # run tests bun run build # build binary for the current platform ``` ## 安全模型 trueline-mcp 采用单用户文件系统信任模型：调用用户被视为可信主体，而以该用户身份运行的任何进程，本质上都已经具备了与 trueline 相同的文件读写权限。 `validatePath()` 在执行检查时会拦截路径遍历（path traversal）和符号链接（symlink）逃逸。它通过 `realpath()` 解析真实路径，并验证其是否包含在项目目录、`TRUELINE_ALLOWED_DIRS` 以及（在 Claude Code 环境下）`~/.claude/` 范围之内。 并发的符号链接竞争（TOCTOU）问题——即在相同 UID 下运行的另一个进程，在路径检查和后续打开文件之间替换了目录组件——不在本工具的防范范围内。彻底杜绝此类问题需要在整个代码库中采用基于文件描述符（fd-based）的 I/O 操作，但这与现有的流式传输和原子重命名设计相冲突。我们在此明确声明这种权衡，而不是将其隐匿。 作为纵深防御（defense-in-depth）措施，在 POSIX 系统中，对用户提供路径的读取操作会加上 `O_NOFOLLOW` 标志。如果叶子组件在 `validatePath` 和文件打开之间遭遇符号链接替换，该操作将直接报错中断，而不会静默跟随链接。写入和重命名目标行为则保持不变——因为编辑路径所采用的临时文件与重命名模式本身已经是符号链接安全的。 如果您在共享账户或多租户环境中运行 trueline，请务必通过强化操作系统层（如 chroot、mount namespaces）来保障安全，而不是仅仅依赖 trueline 的路径检查机制。 ## 灵感来源 受 Can Boluk 撰写的 [The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) 以及 Seth Livingston 开发的 [vscode-hashline-edit-tool](https://github.com/sethml/vscode-hashline-edit-tool) 启发。 ## 特别感谢

标签：AI编程助手, MCP插件, SOC Prime, 代码编辑, 开发工具, 效率优化, 暗色界面, 自动化payload嵌入, 自动化攻击