• 开发工具
• 云原生
• CLI

导读

mirrord 的 MCP 服务器（mirrord mcp）为 AI 编码 Agent 提供了validate_config、explain_config_option等离线工具与mirrord://info资源。为了让 Agent 在完全不依赖网络的情况下也能获得准确的 mirrord 文档与操作技能，项目将官方文档（docs）和操作技能（skills）以**固定提交（pinned commit）**的形式打包进mirrord mcp二进制，并在每次发布 PR 中统一升级这些版本。本文以 changelog 条目 changelog.d/+mcp-corpus.added.md 为线索，结合源码深入讲解这套 "corpus"（知识库）机制的目录结构、版本钉扎（pin）、构建期打包、运行期解包、内容校验测试与mirrord://info报告流程，帮助你理解 mirrord MCP 服务器"离线可答"的底层原理。

一、为什么要内嵌文档与 Skills：MCP 服务器的离线知识来源

mirrord 的 MCP 服务器通过标准输入/输出（stdio）与 Agent 宿主交换 JSON-RPC 消息，其定位在 mirrord/mcp/src/lib.rs 的模块注释中写得非常明确：

The mirrord docs and skills compiled into this binary, whichmirrord mcpanswers from without network access.

也就是说，mirrord mcp工具的回答（包括校验配置、解释配置项）不依赖任何网络请求，而是直接读取编译进二进制的知识内容。这些内容分为两大部分：

• docs：mirrord 官方文档（Quick Start、安装、使用、故障排查、AI 使用指南等）的 Markdown 全文；
• skills：面向 AI Agent 的操作技能（skill），每个技能是一个带 YAML front matter 的SKILL.md，告诉模型"什么场景下该做什么、边界在哪里"。

这两部分内容并非手工复制进仓库，而是从上游仓库的指定提交整体 vendored（供应商化）而来，并由mirrord://info资源对外报告当前的版本钉扎情况。这正是 changelog 条目所描述的核心变更：

Vendored the mirrord docs and skills into themirrord mcpbinary from pinned commits, whichmirrord://inforeports and every release PR bumps.

二、corpus 目录结构：docs 与 skills 的落盘形态

知识库内容存放在 mirrord/mcp/corpus 目录下，包含四个组成部分：

mirrord/mcp/corpus/ ├── docs/ # 官方文档 Markdown 全文 ├── docs.pin.json # docs 上游仓库与提交钉扎 ├── skills/ # 各技能的 SKILL.md └── skills.pin.json # skills 上游仓库与提交钉扎

2.1 docs 语料

docs/下按主题组织为多级目录，包括：

• README.md、SUMMARY.md、contributing.md：文档入口与目录；
• getting-started/、installing-mirrord/、using-mirrord/：入门与使用；
• reference/、managing-mirrord/、sharing-the-cluster/：参考与运维；
• troubleshooting/、faq/、use-cases/、using-mirrord-with-ai/：排查、FAQ、用例与 AI 使用指南。

这些文档以原始字节（raw blob）形式 vendored，保证与上游提交逐字节一致。

2.2 skills 语料

skills/下每个子目录对应一个技能，当前共 11 个：

• mirrord-chaos/、mirrord-ci/、mirrord-config/、mirrord-db-branching/
• mirrord-header-propagation/、mirrord-kafka/、mirrord-operator/、mirrord-prev-env/
• mirrord-quickstart/、mirrord-temporal/、mirrord-up/

每个技能目录内必须有一个SKILL.md，其 YAML front matter 声明技能名（name）与用途说明（description），正文则给出触发场景、安全边界与操作步骤。例如 skills/mirrord-up/SKILL.md 用于指导用户通过mirrord-up.yaml一次运行多个并发 mirrord 会话。

值得注意的排除规则：在 xtask/src/tasks/corpus.rs 中，skills 语料明确排除了mirrord-config/references/configuration.md，原因正如源码注释所述——这是一份配置参考的副本，而mirrord mcp已经通过编译进二进制的配置 schema 提供相同信息，无需重复携带。

三、版本钉扎：pin 文件记录"从哪个提交 vendored"

每个语料对应一个 pin 文件，记录上游仓库、提交哈希与同步时间。当前仓库中的实际钉扎为：

docs.pin.json：

{ "repo": "metalbear-co/docs", "commit": "68a00068ded06dbe3f894b6e01e79fdd2b94606b", "synced_at": "2026-10-06T12:16:59Z" }

skills.pin.json：

{ "repo": "metalbear-co/skills", "commit": "7c64f3c209362674ce9c4b858af16dc27d39e247", "synced_at": "2026-10-06T12:17:02Z" }

在源码中，pin 结构由 mirrord/mcp/src/corpus.rs 的Pin类型定义，包含repo、commit与 RFC 3339 格式的synced_at三个字段；运行时通过include_str!将这两个 JSON 文件编译进二进制，并用LazyLock惰性解析为静态常量DOCS_PIN与SKILLS_PIN。

四、vendoring 工作流：cargo xtask corpus同步与校验

知识库的同步与校验由 xtask 子命令corpus驱动，CLI 定义在 xtask/src/main.rs，实现位于 xtask/src/tasks/corpus.rs。

4.1 两个子命令

4.2 同步过程（sync）

以 xtask/src/tasks/corpus.rs 的实现来看，同步流程为：

1. 读取（或在--bump时通过git ls-remote获取上游 HEAD 并写入）pin 文件；
2. 在临时目录初始化一个最小 git 仓库，git fetch --depth 1拉取 pin 提交；
3. 用git ls-tree -r列出docs/（或skills/）根目录下所有文件，仅保留.md后缀、非隐藏路径、且不在排除清单中的文件；
4. 用git cat-file blob FETCH_HEAD:<path>取出每个文件的原始 blob（不受 checkout 过滤器或行尾转换影响）；
5. 清空并重建corpus/下对应目录，逐文件写入。

4.3 校验过程（check）

check函数（xtask/src/tasks/corpus.rs）重新拉取 pin 提交，将上游文件树与本地 vendored 树逐路径、逐字节比对，收集三类差异：

• 本地缺少上游文件（missing）；
• 本地文件与上游内容不一致（differs from upstream）；
• 本地存在上游没有的文件（not in upstream）。

只要存在任何差异，命令即失败并提示运行cargo xtask corpus sync。这保证了发布的可复现性：一个 release 提交对应的知识库内容是完全确定的，这也是 changelog 中 "every release PR bumps" 的工程基础——发布 PR 负责--bump升级 pin，CI 负责check守住一致性。

五、构建期打包：build.rs 将语料压缩进二进制

vendored 的 Markdown 并不会以原始大小直接进入二进制，而是先由构建脚本 mirrord/mcp/build.rs 打包成一个 gzip 压缩的 tar 归档。

关键实现细节：

• 遍历corpus/docs与corpus/skills两个目录，收集全部文件路径；
• 文件列表排序，且所有 tar 头使用固定元数据（mode 0o644、mtime 0），从而保证"同一份语料总是打包出相同的字节"，有利于二进制可复现构建；
• 使用Compression::best()最高压缩级别，产物写入OUT_DIR/corpus.tar.gz；
• 通过cargo:rerun-if-changed=corpus声明依赖，语料变化时自动触发重新打包。

六、运行期解包：corpus.rs 的惰性加载

在运行期，mirrord/mcp/src/corpus.rs 通过include_bytes!把OUT_DIR/corpus.tar.gz直接嵌入二进制，再由LazyLock驱动的静态FILES完成一次性的解包：

static ARCHIVE: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/corpus.tar.gz")); pub(crate) static FILES: LazyLock<BTreeMap<String, String>> = LazyLock::new(|| { let mut archive = tar::Archive::new(GzDecoder::new(ARCHIVE)); // ... 逐条目读取，路径用 "/" 连接，内容按 UTF-8 读取 });

最终得到一个以corpus/内相对路径为键（例如skills/mirrord-up/SKILL.md）、以文件全文为值的映射。FILES当前被标注为expect(dead_code)，因为读取它的 docs/skills 工具"即将到来"（注释原文：read by the docs and skills tools, still to come），但它已经承担了语料内容的结构化加载与测试职责。

七、mirrord://info资源：对外报告安装与语料版本

mirrord://info是 MCP 服务器暴露的唯一定制资源，处理逻辑位于 mirrord/mcp/src/lib.rs。当客户端请求该资源时，服务器返回一段 JSON：

• version：当前 mirrord 安装版本（来自CARGO_PKG_VERSION）；
• docs：docs 语料的 pin（repo、commit、synced_at）；
• skills：skills 语料的 pin。

这正好对应 changelog 中 "whichmirrord://inforeports" 的行为。资源描述文本为"The installed mirrord version, and the docs and skills commits it ships."，MIME 类型为application/json。

配套的指令与工具

同一个模块还提供了：

• INSTRUCTIONS常量（mirrord/mcp/src/lib.rs）：交给模型的行为指引，强调"任何生成的配置在写入前都必须用validate_config校验，不要依赖自己记忆的配置格式，遇到不明确的选项用explain_config_option查询"；
• 两个离线工具（mirrord/mcp/src/tools.rs）：
  • validate_config：按当前安装版本编译进二进制的 schema 校验mirrord.json/mirrord-up.yaml，返回每个问题的 JSON pointer、消息与允许值；
  • explain_config_option：按 dotted path（如feature.network.incoming.mode）解释单个配置项的作用、类型、默认值、所需 plan，未知路径则返回最接近的已知路径建议。

这些工具的答案全部来自编译进二进制的配置 schema（schema.rs 中的LAYER_SCHEMA与UP_SCHEMA），与语料一样不需要任何网络访问。

八、内容质量保障：语料必须通过的测试

语料不是"塞进去就行"，而是要满足严格的校验测试才能随发布 PR 合入。相关测试在 mirrord/mcp/src/corpus.rs 与集成测试 mirrord/mcp/tests/server.rs 中。

8.1 单元测试：pages_parse 与 skills_load

• pages_parse：遍历所有文档页，解析开头的 YAML front matter（---之间的内容），任何页面的 front matter 不是合法 YAML 即失败；
• skills_load：对skills/下每个目录（视为一个技能）检查：
  • 必须存在SKILL.md，否则报missing；
  • 必须有 front matter；
  • front matter 中的name必须等于目录名（防止改名后目录与声明不一致）；
  • 必须有非空的description（模型要靠它决定何时使用该技能）。

8.2 反向测试：broken_corpus_is_caught

该测试刻意构造三份"坏"语料（YAML 未闭合的 front matter、缺少SKILL.md的技能目录、name与目录名不符的SKILL.md），断言page_issues与skill_issues能分别把它们全部识别出来——即"一个错误的 pin bump 会让发布 PR 失败"。

8.3 集成测试：serves_info_resource

mirrord/mcp/tests/server.rs 通过真实 MCP 客户端（内存管道）驱动服务器，验证：

• list_resources能列出mirrord://info；
• read_resource返回的 JSON 中version等于CARGO_PKG_VERSION；
• docs与skills两个语料的repo分别为metalbear-co/docs与metalbear-co/skills，commit为 40 位十六进制哈希，synced_at为字符串。

同一文件中的serves_validate_config、serves_explain_config_option还验证了工具在initialize与discover两种协议生命周期下都能正常工作。

九、机制总结与延伸阅读

将 docs 与 skills 以固定提交 vendored 进mirrord mcp二进制，带来三点直接收益：

1. 离线可用：Agent 环境即使完全断网，也能基于准确的文档与技能工作；
2. 版本对齐：知识库与二进制出自同一 release 提交，mirrord://info让客户端随时可查"当前安装配套哪个版本的文档与技能"；
3. 发布可控：cargo xtask corpus sync --bump升级 pin，cargo xtask corpus check守住逐字节一致性，单元/集成测试拦截损坏的语料，形成完整的变更流水线。

如果你想进一步深入，可以从以下文件开始：

• 语料目录：mirrord/mcp/corpus/docs 与 mirrord/mcp/corpus/skills；
• vendoring 实现：xtask/src/tasks/corpus.rs；
• 构建期打包：mirrord/mcp/build.rs；
• 运行期加载与 pin 解析：mirrord/mcp/src/corpus.rs；
• MCP 服务器与mirrord://info：mirrord/mcp/src/lib.rs；
• 工具与 schema：mirrord/mcp/src/tools.rs、mirrord/mcp/src/schema.rs；
• 质量测试：mirrord/mcp/tests/server.rs。

• 开发工具
• 云原生
• CLI