Files
marqdo/doc/design/generated-yaml-manifest.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

6.7 KiB
Executable File
Raw Permalink Blame History

设计草案:机器生成的 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 的概念目录)来承载这份生成结果,从而一举两得:

  1. 给编译器 / 包管理:依赖图、模块身份、导出符号、版本锁定等可查询元数据
  2. 给本项目文档:同一份生成物可直接渲染为「项目知识目录」——模块说明、依赖关系、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)。


原则

  1. 源为唯一权威 — 依赖与导出以 .mq.md 正文中的语言构造为准;YAML 是提取结果。
  2. 生成、可复现 — 同一源树 + 同一工具版本 → 同一清单(允许时间戳等字段除外或规范化)。
  3. 勿手改生成物 — 生成文件应带头注释或 generated 字段;CI 可校验「未提交脏生成」或「提交的生成与源一致」。
  4. OKF 形、Marqdo 义 — 文件形态对齐 OKF(type、链接、目录),词汇服务模块/依赖/导出,而不是照搬 BigQuery 概念类型。
  5. 清单可删可再生 — 没有清单时,编译器仍须能直接从源工作(可能更慢);清单是缓存与文档面,不是语言语义的一部分。

待决问题(后续 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 自动生成的依赖与项目元数据,并可据此自动生成本项目文档;不是人手填写的配置文件。
人写源,工具写清单与目录文档;编译器与文档站共同消费生成物,语义始终回到源。