mdoc 定制化工具包：把修复文档管理系统搬到新机器

使用 AI 编程助手时，我长期维护着一套「修复方案文档管理系统」（mdoc）：每次排查、修复、改造的结论都会被归档成结构化文档，形成可搜索的个人知识库；在此基础上还有一套发布流水线，能把归档内容去敏后自动变成博客文章。这套系统是高度定制化的——命令协议、发布规则、归档格式都经过多轮打磨。本文分享的，是把它完整迁移到另一台机器的便携工具包。

mdoc 是什么#

mdoc 是一个「把修复经验沉淀成文档」的个人系统：用 /mdoc 斜杠命令管理文档，分类、命名、索引、搜索全部由 CLI 程序保证一致性；文档采用统一的格式规范，并附带一套「归档 → 审查 → 发布」的博客流水线。它的前世今生记录在 《mdoc 重构：从 Claude Code skill 到任意目录可解析的 CLI 工具库》 一文里。

问题在于：这套系统由技能、子代理、CLI 工具和配置文件共同组成，散落在本机的几个目录里，路径还是硬编码的。换一台机器就要全部重配，几乎不可能手动复刻。于是我把它们整理打包，做成了一个自包含、可移植、无敏感信息的部署工具包。

工具包里有什么#

解压后包含四类内容：

内容	作用
CLI 工具本体	纯 Python、零第三方依赖的安装包，可离线安装，负责文档系统的全部确定性操作
主技能	命令协议与发布规则：搜索、列表、创建、更新、删除、发布规范
发布流水线技能 + 三个子代理	归档 → 审查 → 发布一条龙；三个子代理各自独立工作，减少幻觉
配置模板	文档库路径、索引文件名、分类规则、内容风格等

工具包内不含任何敏感信息：所有个人路径都被替换成了 {{占位符}}，安装时按配置清单填好即可。

下载与三步部署#

📥 下载 mdoc 部署工具包

拿到压缩包后，三步即可完成部署：

安装 CLI：用 pip 安装包内的 wheel 文件，运行版本命令验证；
放置技能与子代理：把解压后的 skills 和 agents 目录复制到 Claude Code 的用户配置目录（Windows 在 C:\Users\<你>\.claude\，macOS/Linux 在 ~/.claude/）；
配置：复制配置模板为 ~/.mdoc.toml，按下表填写占位符。

需要设置的部分（配置清单）#

占位符	含义	是否必填
文档库目录	存放修复方案文档和索引文件的目录（绝对路径）	必填
博客项目目录	静态博客项目根目录（发布流水线需要）	仅用发布功能时
服务器附件目录	博客随文附件的服务器存放目录	仅用附件上传时

填好文档库目录后，系统功能即与当前机器一致；博客项目和附件相关项只在你需要发布流水线时才配置。

使用（以 Claude Code 为例）#

部署完成后，在 Claude Code 会话里直接用斜杠命令：

/mdoc 关键词 — 搜索修复方案文档
/mdoc -l — 列出文档
/mdoc -c 标题 — 新建文档
/mdoc -u 参考名 — 更新文档
/mdoc -d 参考名 — 删除文档

完整命令清单在技能文件里有速查表，也可以跑 /mdoc --help 查看。

AI 部署教程#

不想手动操作？把工具包交给新机器上的 AI 助手（Claude Code 或任何 AI CLI），粘贴下面的提示词即可：

请帮我在当前机器上部署 mdoc 工具包。工具包已解压到 某目录。

用 pip 安装其中的 CLI 安装包；

把 skills/ 和 agents/ 复制到我的 Claude Code 用户配置目录；

阅读配置模板，帮我创建 ~/.mdoc.toml，把文档库目录填成我指定的路径；

检查技能与子代理文件里的占位符，替换成我的实际路径；

运行版本命令和列表命令验证可用。

AI 会按提示逐步完成安装、放置和配置，最后给出验证结果。

安全说明#

工具包不含服务器地址、密钥、个人机器路径等敏感信息；
所有需要按本机环境填写的内容都以占位符形式给出，并集中列在配置清单里；
如果新机器与本文场景不同，只需在替换占位符时同步调整技能中的相关说明即可。

关联阅读#

工具包在博客上以附件形式提供下载，所用的随文附件机制见 《让博客文章携带可下载文件：随文附件功能实现记录》；
mdoc 系统的设计历程见 《mdoc 重构：从 Claude Code skill 到任意目录可解析的 CLI 工具库》。

音乐