Move gold samples under tests/, put executable user docs in public/, restyle view, and add catalog plus gh-pages publish workflow. Co-authored-by: Cursor <cursoragent@cursor.com>
3.7 KiB
3.7 KiB
OKF 兼容清单:marqdo catalog
| 状态 | 已定(v0 命令落地) |
| 日期 | 2026-08-04 |
| 取代 | generated-yaml-manifest.md 中「待决:sync/doc 命令」的命令名部分 |
| 相关 | generated-yaml-manifest.md · view.md · okf-and-marqdo.md |
1. 决策(重申)
YAML / OKF 风格清单是从 .mq.md 派生的生成物,不是手写配置。详见 generated-yaml-manifest.md。
本文件规定 CLI 与 v0 落盘格式。
2. CLI
marqdo catalog [PATH] -o OUT_DIR
# 别名(与早期草案一致)
marqdo sync [PATH] -o OUT_DIR
| 参数 | 默认 | 说明 |
|---|---|---|
PATH |
. |
工程根或含 .mq.md 的目录(递归扫描) |
-o / --out |
.marqdo |
生成目录(写入前创建;覆盖同名生成文件) |
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 diagnostics 并继续其余文件,最终若有失败则非 0)。
3. 生成物(v0)
OUT_DIR/
catalog.yaml # 机器向总清单(OKF 风格字段)
index.md # 人/Agent 可读总览(含 YAML frontmatter)
modules/
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
路径中的目录层级拍扁为文件名时用 __ 连接,例如:
structure/import/main.mq.md → modules/structure__import__main.md
3.1 catalog.yaml(示意)
# GENERATED by marqdo — do not edit by hand
type: Marqdo Catalog
title: marqdo-project
generated:
by: marqdo/0.0.1
# at: 可选 ISO8601;CI 比对时可忽略
modules:
- id: structure/hello
resource: structure/hello.mq.md
title: Hello World # 来自源 frontmatter title,缺省用文件名
imports: []
exports:
- name: Hello World
kind: fn
- id: structure/import/main
resource: structure/import/main.mq.md
imports:
- utils.mq.md
exports:
- name: main
kind: fn
字段约定(v0 最小集):
| 字段 | 含义 |
|---|---|
type |
固定 Marqdo Catalog(OKF:未知 type 可降级) |
modules[].resource |
相对 PATH 的源路径 |
modules[].imports |
源 frontmatter 中的 > *.mq.md |
modules[].exports |
顶层 # 函数名(kind: fn);嵌套 ## 列入 children(可选,v0 可扁平只列顶层) |
generated.by |
marqdo/<crate version> |
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
3.2 模块概念页 frontmatter
---
type: Marqdo Module
title: …
resource: structure/hello.mq.md
depends: [] # imports 列表
exports: [Hello World]
generated:
by: marqdo/0.0.1
---
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
4. 与 view output 的分工
| 命令 | 产物 | 受众 |
|---|---|---|
marqdo view output |
静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
marqdo catalog |
OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
二者都从同一源树生成,互不替代。发布用户文档时可同时:
marqdo view output public -o public
marqdo catalog tests -o .marqdo
5. 验收
marqdo catalog tests -o /tmp/mq-cat写出catalog.yaml与modules/。catalog.yaml含structure/hello与 import 模块的imports: [utils.mq.md]。- 文件头或
generated标明 GENERATED;文档声明勿手改。 marqdo sync与catalog行为一致。