1. 为什么我又折腾了一个文档工具：从 README 到 AI Agent 可读的文档站
如果你维护过稍微有点规模的开源项目，大概都经历过这个阶段：一开始一个 README.md 走天下，功能一多就拆成 docs 目录，再往后目录层级乱到自己都记不住，搜索靠 Ctrl+F，多语言和版本管理想都不敢想。等到项目里接了 AI Agent 或者 MCP 服务，问题更明显——大模型根本读不懂你那一堆散落的 Markdown，它不知道哪个文件是入口、哪个是 API 说明、哪个是配置示例。
Docmd 就是冲着这个痛点来的。它是一个零配置的 Markdown 文档生成工具，核心定位是「从 Markdown 到生产环境文档站，只需要一条命令」，同时原生支持 AI Agent 和 MCP 服务。换句话说，它不只是给人看的文档站，还是给模型和 Agent 读的上下文来源。适合谁？我总结下来是三类人：一是开源项目维护者，想快速把 docs 目录变成带搜索、带 SEO 的站点；二是做 AI Agent、MCP Server、RAG 项目的开发者，需要一份机器可读的文档描述；三是企业内部做技术文档、开发手册的团队，不想引入 Docusaurus 那种重配置方案。
这篇教程我会按「本地跑通 → 接入 MCP → 排错」的顺序走一遍，所有命令和配置都能直接复制。中间涉及模型调用和 API Key 的部分，我会用 TaoToken 来做演示，因为它的接口格式和主流 SDK 兼容，配置起来省事。你不需要先理解全部概念，跟着敲一遍就能看到文档站跑起来。
先明确一个预期：Docmd 主打零配置，但不是零文件。你至少得有一个 Markdown 文件，它才能生成东西。所以第一步不是装工具，而是确认你手上有没有现成的 Markdown 内容。有的话，后面基本就是一条命令的事。
2. 前置准备：Node 环境、TaoToken API Key 与目录规划
在正式跑 Docmd 之前，我建议先把三件事准备好，不然后面容易卡在环境问题上。
第一是 Node.js 环境。Docmd 是基于 Node 的工具，推荐 Node 18 以上。你可以用node -v确认版本，如果低于 18，建议用 nvm 切一个 LTS 版本。这一步没什么好说的，但确实是新手最容易忽略的地方——版本太低会出现各种奇怪的模块解析错误。
第二是 TaoToken 的 API Key。为什么文档生成工具需要 API Key？因为 Docmd 的 AI Context 和 MCP 服务在部分场景下需要调用模型来生成或校验内容，比如自动生成 llms.txt 的摘要、或者在 MCP 服务里做内容验证。TaoToken 的接入地址是https://taotoken.net/api，你可以在控制台创建 Key，然后配置到环境变量里。我习惯把它写成TAOTOKEN_API_KEY，这样在配置文件和脚本里都能引用。
第三是目录规划。Docmd 对目录结构很宽容，最简单的形态就是一个 README.md 放在根目录，它也能跑。但如果你想认真做一个文档站，建议按下面这种结构组织：
my-docs/ ├── docs/ │ ├── index.md │ ├── getting-started.md │ └── api/ │ └── reference.md ├── assets/ │ └── logo.png ├── docmd.config.json └── package.jsondocs/放正文，assets/放图片，docmd.config.json是可选配置，package.json用来管理依赖和脚本。如果你已经有现成的 Markdown，直接把它们丢进docs/就行，不用改文件名，Docmd 会自动解析目录结构生成导航和路由。
这里有个小坑提前说：如果你的 Markdown 文件名里有中文或空格，建议改成英文短横线连接，比如快速开始.md改成getting-started.md。不是 Docmd 不支持，而是生成的路由和 sitemap 里带中文容易出编码问题，后面接搜索引擎或者 Agent 读取时会麻烦。
环境准备好之后，先别急着全局安装。我建议用npx直接跑，这样不污染全局环境，也方便对比不同版本。等你确定要长期用了，再考虑全局安装或者写进 package.json 的 scripts 里。
3. 可复制配置：docmd.config.json、package.json 与 MCP 描述文件
这一节是全文的核心，我会把三个关键配置文件完整写出来，你直接复制改路径就能用。
先说package.json。哪怕你不想管依赖，也建议建一个，因为后面跑脚本、接 CI 都靠它：
{ "name": "my-docs", "version": "1.0.0", "private": true, "scripts": { "dev": "docmd dev", "build": "docmd build", "mcp": "docmd mcp", "migrate": "docmd migrate" }, "devDependencies": { "@docmd/core": "latest" } }注意这里我把dev、build、mcp都写成了脚本，这样你只需要npm run dev就能启动，不用记完整命令。@docmd/core是核心包，版本用 latest 就行，等稳定了再锁版本号。
接下来是docmd.config.json。虽然 Docmd 主打零配置，但一旦你要开 i18n、版本管理、MCP 服务，还是得写点配置。下面这份是我实测能跑通的完整配置，包含站点信息、i18n、版本管理和 MCP 开关：
{ "site": { "title": "My Project Docs", "description": "面向 AI Agent 与 MCP 服务的项目文档", "baseUrl": "https://docs.example.com", "logo": "/assets/logo.png" }, "i18n": { "default": "zh", "locales": [ { "id": "zh", "label": "中文" }, { "id": "en", "label": "English" } ] }, "versions": { "current": "v2", "all": [ { "id": "v2", "dir": "docs" }, { "id": "v1", "dir": "docs-v1" } ] }, "mcp": { "enabled": true, "name": "my-project-docs", "description": "项目文档的 MCP 服务，支持搜索与读取", "transport": "stdio" }, "llms": { "enabled": true, "output": "llms.txt", "fullOutput": "llms-full.txt" } }几个关键点解释一下。site.baseUrl影响 sitemap 和 canonical URL，部署前一定要改成你的真实域名。i18n里 default 是默认语言，locales 数组里每个语言对应一个目录，比如中文内容放docs/zh/，英文放docs/en/，Docmd 会自动切换。versions用来做多版本文档，current 指向当前版本目录，all 里列出所有版本，SDK 类项目特别需要这个。mcp.enabled打开后，docmd mcp命令才会提供 MCP 服务，transport 用 stdio 是最通用的方式，Claude Desktop、Cursor 这类客户端都支持。
然后是 MCP 描述文件。Docmd 在开启 MCP 后，会基于你的文档生成一份服务描述，但如果你想自定义工具暴露给 Agent 的能力，可以在项目根目录放一个mcp.manifest.json：
{ "name": "my-project-docs", "version": "1.0.0", "description": "提供项目文档的搜索、读取与内容验证能力", "tools": [ { "name": "search_docs", "description": "根据关键词搜索文档内容", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "description": "搜索关键词" } }, "required": ["query"] } }, { "name": "read_doc", "description": "读取指定路径的文档内容", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", "description": "文档相对路径" } }, "required": ["path"] } } ] }这份 manifest 的作用是告诉 Agent「这个 MCP 服务能做什么、参数长什么样」。如果你不写，Docmd 会用默认的工具集，但自定义之后，Agent 调用会更精准，减少瞎猜参数的情况。
最后提醒一句：配置文件里的路径都是相对项目根目录的，别写成绝对路径，不然换台机器就崩。API Key 不要写进配置文件，用环境变量注入，下面验证环节我会演示。
4. 验证请求：启动 dev、构建产物与 MCP 服务连通性测试
配置写完之后，就到了最爽的验证环节。我会分三步走：先跑 dev 看文档站，再 build 看产物，最后测 MCP 服务能不能被 Agent 调用。
第一步，启动开发服务器。在项目根目录执行：
npm install npm run dev如果你没建 package.json，直接用npx @docmd/core dev也一样。启动后终端会打印本地地址，默认是http://localhost:3000。打开浏览器，你应该能看到自动生成的导航、目录树和搜索框。这时候随便点几个页面，确认 Markdown 渲染正常、图片能加载、代码块有高亮。
第二步，构建生产产物：
npm run build构建完成后会生成一个静态站点目录，通常是dist/或.docmd/dist/，具体看版本。这个目录可以直接丢到 Nginx、Cloudflare Pages、Vercel、Netlify 或者 GitHub Pages 上。我实测下来，构建速度很快，几十个 Markdown 文件基本秒级完成。构建产物里会自动包含sitemap.xml、llms.txt和llms-full.txt，后面两个是给大模型读的，你可以打开看看内容是不是完整。
第三步，测 MCP 服务。先启动 MCP：
npm run mcp如果配置里mcp.enabled是 true，终端会显示 MCP 服务已启动，并监听 stdio。接下来你要在 Agent 客户端里配置这个服务。以 Claude Desktop 为例，编辑它的配置文件，加上一段：
{ "mcpServers": { "my-project-docs": { "command": "npx", "args": ["@docmd/core", "mcp"], "env": { "TAOTOKEN_API_KEY": "你的Key" } } } }保存后重启客户端，你应该能在工具列表里看到search_docs和read_doc。然后试着问它「帮我搜索文档里关于配置的部分」，如果它能返回你 Markdown 里的真实内容，说明 MCP 链路通了。
这里涉及模型调用时，TaoToken 的接入地址是https://taotoken.net/api，你可以在环境变量里配置TAOTOKEN_BASE_URL指向它。如果你用的是 Claude Code 或者 Cline 这类编码 Agent，配置方式类似，把 Base URL、API Key、Model ID 三件套填全就行。Model ID 根据你实际用的模型填，比如claude-sonnet-4-20250514这类。
验证成功的标志有三个：浏览器能访问文档站、构建目录里有 llms.txt、Agent 能通过 MCP 读到文档内容。三个都过了，说明整条链路是通的。
5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth
这一节我把我踩过的坑和社区里高频出现的报错整理出来，对照着查能省不少时间。
第一个，401 Unauthorized。这个基本是 API Key 没配好。检查三处：环境变量名是不是和配置文件里引用的一致、Key 有没有多余空格、Base URL 是不是写成了https://taotoken.net/api而不是带路径的完整地址。如果你在 MCP 客户端的 env 里写 Key，注意 JSON 里不能有注释，也不能用单引号。
第二个，local proxy failed。这个报错通常出现在 Agent 客户端连本地 MCP 服务时。原因一般是command或args写错了，比如npx找不到、包名拼错、或者工作目录不对。解决办法是在终端里手动执行一遍npx @docmd/core mcp，看能不能起来。如果手动能起、客户端起不来，那就是客户端配置的路径问题，把command改成npx的绝对路径试试。
第三个，reading choices 相关报错。这个多出现在模型返回格式不符合预期时，比如你让模型基于文档生成内容，但它返回的结构和 SDK 解析的不一致。排查方法是先确认 Model ID 填对了，不同模型对返回格式的要求不一样；其次检查你的 prompt 是不是要求了结构化输出，如果是，确认模型支持。TaoToken 的接口兼容主流 SDK，一般不会在这个环节出问题，但 Model ID 写错会直接导致解析失败。
第四个，OAuth 相关报错。如果你在 MCP 客户端里配了需要 OAuth 的服务，可能会遇到 token 过期或回调失败。Docmd 的 MCP 服务默认走 stdio，不涉及 OAuth，所以这个报错一般是你同时配了别的服务导致的。建议先把其他 MCP 服务注释掉，只留 Docmd 的，确认能通之后再逐个加回来。
除了这四个，还有一个隐蔽的坑：Node 版本太低导致@docmd/core安装失败。表现是npm install报一堆 engine 相关的警告，然后运行时报模块找不到。解决办法就是升级 Node，别硬扛。
排查的时候有个通用思路：先手动跑命令，再放到客户端里跑；先最小配置，再逐步加功能。大部分问题都是配置路径或环境变量的问题，不是工具本身的 bug。
6. 从文档站到 Agent 上下文：把 llms.txt 和 MCP 用起来
文档站跑起来只是第一步，Docmd 真正有意思的地方是它把文档和 AI 生态打通了。我最后说说怎么把这两个能力用起来。
先说 llms.txt。构建完成后，你会在产物目录里看到llms.txt和llms-full.txt。前者是精简版，列出文档结构和关键链接；后者是完整版，包含所有正文内容。这两个文件的作用是让大模型快速理解你的项目。你可以把它们放到站点根目录，然后在 README 或者官网里加一行说明，告诉模型「项目文档见 /llms.txt」。现在越来越多的 AI 工具会主动去读这个文件，比如一些编码 Agent 在分析项目时会先找 llms.txt。
再说 MCP 服务。一旦 Agent 能通过 MCP 读你的文档，它就不再是靠猜来回答问题了。比如你在 Cursor 里写代码，问它「这个项目的配置项有哪些」，它会调用search_docs去你的文档里搜，然后基于真实内容回答。这比把文档塞进 prompt 里靠谱得多，因为文档更新后 Agent 读到的也是最新的。
如果你做的是长期编码或者 Agent 项目，建议把文档生成和 MCP 服务写进 CI。每次合并到主分支，自动跑docmd build和docmd mcp的健康检查，确保文档站和 MCP 描述文件都是最新的。这样团队里任何人改完 Markdown，Agent 那边立刻就能读到新内容。
最后给一个实用技巧：Docmd 支持从 Docusaurus、VitePress、MkDocs 迁移，命令是docmd migrate。如果你手上已经有这些工具的文档，不用手动搬，跑一遍迁移命令，它会帮你转换目录结构和配置。迁移完再跑docmd dev确认没问题，然后就可以把旧工具卸了。
整个流程走下来，我的感受是 Docmd 把「文档生成」和「AI 可读」这两件事合并了。以前你得维护两套东西，一套给人看的站点，一套给模型读的上下文；现在一套 Markdown，两个输出都有了。如果你正在做 AI Agent 或者 MCP 相关的项目，值得花半小时跑一遍。
