# OKF 兼容清单:`marqdo catalog` | | | |---|---| | 状态 | 已定(v0 命令落地) | | 日期 | 2026-08-04 | | 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 | | 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) | --- ## 1. 决策(重申) YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。 本文件规定 **CLI 与 v0 落盘格式**。 --- ## 2. CLI ```bash 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/ .md # 每个 .mq.md 一个概念页(frontmatter + 摘要) ``` 路径中的目录层级拍扁为文件名时用 `__` 连接,例如: `structure/import/main.mq.md` → `modules/structure__import__main.md` ### 3.1 `catalog.yaml`(示意) ```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/` | 不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。 ### 3.2 模块概念页 frontmatter ```yaml --- 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 / 依赖总览 | 二者都从同一源树生成,互不替代。发布用户文档时可同时: ```bash marqdo view output public -o public marqdo catalog tests -o .marqdo ``` --- ## 5. 验收 1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。 2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。 3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。 4. `marqdo sync` 与 `catalog` 行为一致。