内容
# QMDG — 面向人类和智能代理的 Markdown 原生上下文图
<!-- [](https://github.com/mikilabs/qmdc/actions/workflows/ci.yml) -->
[](https://pypi.org/project/qmdc/)
[](https://crates.io/crates/qmdc)
[](https://www.npmjs.com/package/@qmdc/qmdc)
[](https://marketplace.visualstudio.com/items?itemName=MiKiLabs.qmdc-vscode)
[](https://open-vsx.org/extension/mikilabs/qmdc-vscode)
[](LICENSE)
> [!WARNING]
> **Alpha 版本。** QMDG 仍处于早期阶段且发展迅速 — 格式、API 和工具链可能会发生变化，部分功能可能尚未完善或存在问题，特别是在 Windows 平台上。如果您遇到问题，请 [提交问题](https://github.com/mikilabs/qmdc/issues) — 我们非常欢迎错误报告和反馈。
**人类可读的文档。机器可查询的图。智能代理准备就绪的上下文。**
QMDG 将文档转换为知识图谱 — 无需离开 Markdown。标题成为对象，列表项成为字段，`[[#references]]` 创建有类型的边。结果是一个统一的源，可以被三类用户使用：人类以 Markdown 的形式阅读，机器以 SQL 查询，智能代理以 MCP 导航。
```qmd.md
## API 网关 [[gateway: Service]]
- 端口: 8080
- 依赖: [[#auth]]，[[#users]]
## 认证服务 [[auth: Service]]
- 协议: JWT
- 数据库: [[#postgres]]
```
一个文件，一次解析，一个可查询的图谱，包含有类型的边（`depends`、`database`、`protocol`）— 所有这些都来自纯 Markdown。
## QMD.md 与 QMDG
**QMD.md** 是 *格式* — 您编写的 Markdown 惯例，存储在 `.qmd.md` 文件中。**QMDG** 是 *工具链*，读取它：`qmdc` 命令行工具、`qmdc-py` / `qmdc-ts` / `qmdc-rs` 解析器，VS Code 扩展和文档站点生成器。您编写 **QMD.md**；**QMDG** 解析、验证和查询它。文件扩展名保持为 `.qmd.md`。
## 安装
`qmdc` 命令行工具（快速的原生 Rust 二进制文件）已发布到每个主要注册表 — 请选择适合您的工具链：
```bash
uvx qmdc --help # PyPI（捆绑原生二进制文件）
npx @qmdc/qmdc --help # npm（捆绑原生二进制文件）
cargo install qmdc # crates.io（从源代码构建）
```
编辑器支持在 **[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MiKiLabs.qmdc-vscode)** 和 **[Open VSX](https://open-vsx.org/extension/mikilabs/qmdc-vscode)** 上可用 — 搜索 **QMDG**（发布者 `mikilabs`）。
## 快速入门
```bash
# 1. 编写 QMD.md 文件
cat > services.qmd.md <<'EOF'
## API 网关 [[gateway: Service]]
- 端口: 8080
- 依赖: [[#auth]]
## 认证服务 [[auth: Service]]
- 协议: JWT
EOF
# 2. 解析为 JSON
qmdc parse -i services.qmd.md
# 3. 在工作区中验证跨文件引用
qmdc workspace validate .
# 4. 使用 SQL 查询图谱
qmdc query . "SELECT __id, __kind FROM objects WHERE __kind = 'Service'"
# 5. 或通过 MCP 将整个图谱交给您的智能代理
qmdc mcp --force-root .
```
## 软件包
| 软件包 | 注册表 | 描述 |
| --- | --- | --- |
| `qmdc` | PyPI / npm (`@qmdc/qmdc`) / crates.io | 解析器 + 快速 `qmdc` 命令行工具（原生二进制文件） |
| `qmdc-semantic` | PyPI (`uvx qmdc-semantic`) | QMDC 工作区的语义搜索（混合搜索，图遍历，推断边） |
| `qmdc-mkdocs` | PyPI (`uvx qmdc-mkdocs`) | MkDocs 集成 — 从 QMDC 工作区构建文档站点 |
| `qmdc-vscode` | Open VSX（所有平台）+ VS Code Marketplace（macOS） | LSP 支持的编辑器支持（捆绑相同的原生二进制文件） |
`import qmdc`（Python）/ `import { parse } from '@qmdc/qmdc'`（TypeScript）/ `qmdc` crate（Rust）提供库；`qmdc` 命令提供命令行工具。
## 命令行工具
所有三个解析器都暴露相同的命令集：
```bash
qmdc parse -i doc.qmd.md # QMD.md → JSON
qmdc parse -i doc.qmd.md --format full # 包括 __line、__references、__positions
cat doc.qmd.md | qmdc parse # 从 stdin 读取
qmdc rebuild -i data.json # JSON → QMD.md
qmdc parse -i doc.qmd.md | qmdc rebuild # 规范格式化（往返）
qmdc workspace parse ./project # 解析多文件工作区
qmdc workspace validate ./project # 验证跨文件引用
qmdc query ./project "SELECT * FROM objects LIMIT 10"
```
查询针对两个表运行：`objects`（`__id`、`__kind`、`__label`、`__file`、`__line`、`data`）和 `edges`（`source_id`、`target_id`、`field_name`）。
## MCP — 适用于您的智能代理的上下文
QMDG 配备了一个内置的 [MCP](https://modelcontextprotocol.io/) 服务器，因此智能代理可以直接查询您的项目图谱，而不是将散文粘贴到提示中。它通过 stdio（JSON-RPC 2.0）公开与编辑器相同的 workspace 智能 — 引用解析、搜索、SQL、图遍历、重命名：
```bash
qmdc mcp # 启动 MCP 服务器（stdio）
qmdc mcp --force-root ./project # 失败关闭：限制每个调用到此目录
```
将任何 MCP 客户端指向它（Claude Desktop、Cursor、Kiro、…）：
```json
{
"mcpServers": {
"qmdc": {
"command": "qmdc",
"args": ["mcp", "--force-root", "/path/to/your/project"]
}
}
}
```
服务器提供 **14 种工具** 和 **4 种 `qmdc://` 资源**，按意图分组：
- **发现** — `qmdc_search_objects`、`qmdc_locate_object`、`qmdc_describe_object`、`qmdc_describe_metamodel`、`qmdc_get_tree`、`qmdc_outline_file`、`qmdc_get_guide`
- **图谱** — `qmdc_find_references`、`qmdc_find_path`、`qmdc_traverse_graph`、`qmdc_validate_references`
- **查询** — `qmdc_query_sql`（只读）、`qmdc_dump_index`
- **重构** — `qmdc_rename_object`（返回 diff；从不写入）
MCP 服务器、[LSP](https://qmdc.mikilabs.io/lsp/) 和命令行工具都共享一个核心，因此智能代理和您的编辑器始终获得相同的答案。有关完整的工具参考，请参阅 [MCP 文档](https://qmdc.mikilabs.io/mcp/)。
## 三种实现
| 实现 | 目录 | 亮点 |
| --- | --- | --- |
| Python | `qmdc-py/` | 参考实现；完整的 workspace + SQL 支持 |
| Rust | `qmdc-rs/` | 高性能原生二进制文件；LSP 和 MCP 服务器 |
| TypeScript | `qmdc-ts/` | 适用于 Node.js 和浏览器 |
所有三个实现都通过 `tests/` 下的共享一致性测试 corpus 保持字节对字节的对齐。
## 从源代码构建
先决条件：Python 3.12+，Node.js 18+，Rust 1.70+，和 [`uv`](https://docs.astral.sh/uv/)。
```bash
make init # 安装所有依赖，构建每个解析器，运行完整的测试套件
make test # 运行完整的顺序测试套件
make lint # 校验所有三个实现
make format # 格式化所有三个实现
```
构建完成后，包装脚本 `./bin/qmdc-py`、`./bin/qmdc-ts` 和 `./bin/qmdc-rs` 在本地运行每个实现。
## 文档
- **[文档站点](https://qmdc.mikilabs.io/)** — 快速入门、指南和完整的格式规范
- **[格式规范](https://qmdc.mikilabs.io/format/)** — 对象、字段、引用、数组、类型
- **[贡献](CONTRIBUTING.md)** — 如何构建、测试和提交更改
- **[发布](RELEASING.md)** — 每个组件如何发布和重建级联
- 每个软件包的 README：[Python](qmdc-py/README.md) · [Rust](qmdc-rs/README.md) · [TypeScript](qmdc-ts/README.md)
## 许可证
[AGPL-3.0-or-later](LICENSE) © mikilabs
