开发工具云原生CLI【免费下载链接】mirrordRun any process, on your machine or in an AI agents environment, as if it were a pod in your Kubernetes cluster: real env vars, DNS, network, traffic.项目地址https://gitcode.com/gh_mirrors/mi/mirrord点击查看免费下载导读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 服务器离线可答的底层原理。一、为什么要内嵌文档与 SkillsMCP 服务器的离线知识来源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工具的回答包括校验配置、解释配置项不依赖任何网络请求而是直接读取编译进二进制的知识内容。这些内容分为两大部分docsmirrord 官方文档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 两个子命令子命令作用cargo xtask corpus sync从 pin 文件指定的提交重新拉取内容替换corpus/下的 vendored 文件cargo xtask corpus sync --bump先把 pin 移动到上游仓库的 HEAD再执行同步发布 PR 使用cargo xtask corpus check校验 vendored 文件与 pin 提交是否逐字节一致不一致则失败4.2 同步过程sync以 xtask/src/tasks/corpus.rs 的实现来看同步流程为读取或在--bump时通过git ls-remote获取上游 HEAD 并写入pin 文件在临时目录初始化一个最小 git 仓库git fetch --depth 1拉取 pin 提交用git ls-tree -r列出docs/或skills/根目录下所有文件仅保留.md后缀、非隐藏路径、且不在排除清单中的文件用git cat-file blob FETCH_HEAD:path取出每个文件的原始 blob不受 checkout 过滤器或行尾转换影响清空并重建corpus/下对应目录逐文件写入。4.3 校验过程checkcheck函数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升级 pinCI 负责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-changedcorpus声明依赖语料变化时自动触发重新打包。六、运行期解包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: LazyLockBTreeMapString, 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。当客户端请求该资源时服务器返回一段 JSONversion当前 mirrord 安装版本来自CARGO_PKG_VERSIONdocsdocs 语料的 pinrepo、commit、synced_atskillsskills 语料的 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.rsvalidate_config按当前安装版本编译进二进制的 schema 校验mirrord.json/mirrord-up.yaml返回每个问题的 JSON pointer、消息与允许值explain_config_option按 dotted path如feature.network.incoming.mode解释单个配置项的作用、类型、默认值、所需 plan未知路径则返回最接近的已知路径建议。这些工具的答案全部来自编译进二进制的配置 schemaschema.rs 中的LAYER_SCHEMA与UP_SCHEMA与语料一样不需要任何网络访问。八、内容质量保障语料必须通过的测试语料不是塞进去就行而是要满足严格的校验测试才能随发布 PR 合入。相关测试在 mirrord/mcp/src/corpus.rs 与集成测试 mirrord/mcp/tests/server.rs 中。8.1 单元测试pages_parse 与 skills_loadpages_parse遍历所有文档页解析开头的 YAML front matter---之间的内容任何页面的 front matter 不是合法 YAML 即失败skills_load对skills/下每个目录视为一个技能检查必须存在SKILL.md否则报missing必须有 front matterfront 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_resourcemirrord/mcp/tests/server.rs 通过真实 MCP 客户端内存管道驱动服务器验证list_resources能列出mirrord://inforead_resource返回的 JSON 中version等于CARGO_PKG_VERSIONdocs与skills两个语料的repo分别为metalbear-co/docs与metalbear-co/skillscommit为 40 位十六进制哈希synced_at为字符串。同一文件中的serves_validate_config、serves_explain_config_option还验证了工具在initialize与discover两种协议生命周期下都能正常工作。九、机制总结与延伸阅读将 docs 与 skills 以固定提交 vendored 进mirrord mcp二进制带来三点直接收益离线可用Agent 环境即使完全断网也能基于准确的文档与技能工作版本对齐知识库与二进制出自同一 release 提交mirrord://info让客户端随时可查当前安装配套哪个版本的文档与技能发布可控cargo xtask corpus sync --bump升级 pincargo xtask corpus check守住逐字节一致性单元/集成测试拦截损坏的语料形成完整的变更流水线。如果你想进一步深入可以从以下文件开始语料目录mirrord/mcp/corpus/docs 与 mirrord/mcp/corpus/skillsvendoring 实现xtask/src/tasks/corpus.rs构建期打包mirrord/mcp/build.rs运行期加载与 pin 解析mirrord/mcp/src/corpus.rsMCP 服务器与mirrord://infomirrord/mcp/src/lib.rs工具与 schemamirrord/mcp/src/tools.rs、mirrord/mcp/src/schema.rs质量测试mirrord/mcp/tests/server.rs。赞分享开发工具云原生CLI【免费下载链接】mirrordRun any process, on your machine or in an AI agents environment, as if it were a pod in your Kubernetes cluster: real env vars, DNS, network, traffic.项目地址https://gitcode.com/gh_mirrors/mi/mirrord点击查看免费下载相关推荐Goose 桌面端 Windows 运行时文件机制解析Node.js 引导脚本与固定版本 uv 二进制的构建链路Goose 桌面端 Windows 运行时文件机制解析Node.js 引导脚本与固定版本 uv 二进制的构建链路 ui/desktop 是 Goose 桌面应人工智能大模型AI AgentAI 应用本地部署MCP ClientsMCP 服务工具调用桌面应用CLI如何使用DiCE快速生成多样化反事实解释初学者完整指南如何使用DiCE快速生成多样化反事实解释初学者完整指南 DiCEDiverse Counterfactual Explanations是一款强大的开源工具人工智能机器学习AI 可解释性mirrord 的 Rosetta 就绪机制SIP 保护二进制本地回退收集与 mirrord diagnose sip-report 上报指南mirrord 的 Rosetta 就绪机制SIP 保护二进制本地回退收集与 mirrord diagnose sip report 上报指南 本篇技术指南聚开发工具云原生CLI上一篇Reacher 自托管部署实战基于 check-if-email-exists 的 Docker 邮箱验证服务 20 分钟安装指南下一篇Segment 1: [Name]创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考