`import json:lib/json.mq.md` binds file libraries; `import fmt:time.format` binds member short names (replaces `> use`). Legacy `> path.mq.md` / `> use` now hard-error with a hint. Migrates repo docs, skills, ext, lib, public, examples, man-test and tests; adds a negative gold and updates view/catalog rendering. Co-authored-by: Cursor <cursoragent@cursor.com>
6.7 KiB
设计草案:机器生成的 YAML 清单(OKF 风格)
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
| 日期 | 2026-08-04 |
| 相关 | OKF 调研 · 实现规范 okf.md |
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
| 说明 | 原则仍有效;类型表、任务知识包、路线图以 okf.md 为准 |
决策
Marqdo 项目中的 YAML(及由其组成的 OKF 风格知识包)是工具自动生成的产物,不是给人填的配置文件。
它的角色接近其它语言里由工具维护的依赖与包元数据,例如:
| 生态 | 类比(职责相近,不是语法相同) |
|---|---|
| Rust | Cargo.toml / 解析后的依赖图(由源与清单共同推导,工具可改写) |
| Python | requirements.txt(常由解析/冻结生成) |
| Go | go.mod + go.sum(go mod tidy 维护) |
我们选择 OKF 的形态(Markdown + YAML frontmatter 的概念目录)来承载这份生成结果,从而一举两得:
- 给编译器 / 包管理:依赖图、模块身份、导出符号、版本锁定等可查询元数据
- 给本项目文档:同一份生成物可直接渲染为「项目知识目录」——模块说明、依赖关系、API 索引等自动生成本项目文档内容
唯一手写真相仍是 .mq.md 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
与源 frontmatter 的分工(见 markdown-mapping.md):源文件 --- 块可含 title 等元信息,以及人手声明的跨文件导入行 import other:other.mq.md。那是源上的导入声明,不是工程依赖锁。工具仍应据此(及正文 > 调用)生成 OKF 风格依赖/模块目录;不要把生成目录手改成权威。
纠正:它不是什么
| ❌ 不是 | ✅ 是 |
|---|---|
人手维护的 run / target / 路径配置 |
从源码 推导 出的依赖与模块元数据 |
| 编译器「怎么跑」的 ini/配置替代品 | 解析、链接、文档站共用的 生成清单 |
| 与正文平行的第二套程序描述 | 正文的 投影(projection):结构化、可查询、可渲染 |
执行方式(解释 / 检查 / 编译到某后端)由 CLI、子命令或工程约定 决定,不塞进这份 YAML 让人配置。
数据流
手写 .mq.md 源
(叙事 + 类型 + 函数 + 正文中的引用/导入)
│
▼
marqdo 工具链
· 解析正文 AST
· 收集 import / 链接 / 导出
· 解析依赖、锁定版本
│
├──────────────────────────────┐
▼ ▼
生成 OKF 风格清单 编译 / 类型检查 / 运行
(YAML + 概念 Markdown) (消费清单加速解析)
│
▼
自动生成本项目文档
(模块索引、依赖图、API 目录……)
- 源 → 清单:单向派生;清单不得反向成为「唯一写依赖的地方」。
- 清单 → 文档:OKF 包本身即可浏览;也可再生成站点/目录页。
- 清单 → 编译:编译器可读生成结果以跳过重复发现,但语义仍以源为准;清单缺失时应能从源重建。
生成物长什么样(示意)
工程在构建或 marqdo sync 类命令后,可得到类似 OKF bundle 的目录(路径未定):
.marqdo/ # 或 docs/catalog/ 等 — 待 ADR
index.md # 生成:项目总览
modules/
cart.md # 生成:每个模块一个概念文档
prelude-list.md
deps/
lock.yaml # 生成:依赖锁定(机器向)
单个生成的概念文件可呈 OKF 形:
---
type: Marqdo Module # 生成
title: cart
description: 购物车:行项目与总额
resource: src/cart.mq.md # 指向源文件
depends:
- prelude/list
- math/sum
exports: [Line, total]
generated:
by: "marqdo/0.1"
at: 2026-08-04T01:00:00Z
---
# cart
> 本页由 Marqdo 工具链根据 [`src/cart.mq.md`](../../src/cart.mq.md) **自动生成**,请勿手改。
## 依赖
- [prelude/list](../modules/prelude-list.md)
- [math/sum](../modules/math-sum.md)
## 导出
| 符号 | 种类 |
|------|------|
| `Line` | type |
| `total` | fn |
人要改行为或说明 → 改 src/cart.mq.md;再生成,文档与依赖清单一起更新。
与「代码即文档」的关系
Marqdo 有两层「文档」,不要混为一谈:
| 层 | 谁写 | 是什么 |
|---|---|---|
| 源文档 | 人(及协助编写的 Agent) | .mq.md:程序本身,打开即读、即可跑 |
| 项目目录文档 | 机器 | OKF 风格 YAML/Markdown:从全项目源 汇总 的依赖、模块图、索引 |
前者消灭「实现与说明漂移」;后者消灭「仓库级总览靠手维护 README 目录」——总览从源自动长出,格式还对 Agent / 搜索友好(OKF)。
原则
- 源为唯一权威 — 依赖与导出以
.mq.md正文中的语言构造为准;YAML 是提取结果。 - 生成、可复现 — 同一源树 + 同一工具版本 → 同一清单(允许时间戳等字段除外或规范化)。
- 勿手改生成物 — 生成文件应带头注释或
generated字段;CI 可校验「未提交脏生成」或「提交的生成与源一致」。 - OKF 形、Marqdo 义 — 文件形态对齐 OKF(
type、链接、目录),词汇服务模块/依赖/导出,而不是照搬 BigQuery 概念类型。 - 清单可删可再生 — 没有清单时,编译器仍须能直接从源工作(可能更慢);清单是缓存与文档面,不是语言语义的一部分。
待决问题(后续 ADR)
- 生成物默认路径:
.marqdo/(-o可改)— 见 catalog-cli.md marqdo catalog/sync;静态用户文档:marqdo view output— 见 view.md- 是否提交生成物进 git(项目自定;CI 可校验干净生成)
- 与「可手写包身份 name/version」的边界
- 是否沿用 OKF v0.2 的
sources等溯源字段
结论
YAML(OKF 风格清单)= 机器从 .mq.md 自动生成的依赖与项目元数据,并可据此自动生成本项目文档;不是人手填写的配置文件。
人写源,工具写清单与目录文档;编译器与文档站共同消费生成物,语义始终回到源。