# OKF 兼容清单:`marqdo catalog` | | | |---|---| | 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) | | 日期 | 2026-08-07 | | 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 | | 相关 | [okf.md](okf.md)(**实现规范总览**)· [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` 派生的生成物**,不是手写配置。完整词汇、任务知识包与路线图见 [**okf.md**](okf.md)。生成式方向见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。 本文件规定 **CLI 与工程目录包落盘格式**(含 O3:扫入本地 `agent-kb` 概念,供人与工具同览)。 --- ## 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. 生成物 ``` OUT_DIR/ catalog.yaml # 机器向总清单(OKF 风格字段) index.md # 人可读总览:Modules + Agent knowledge modules/ .md # 每个工程 .mq.md 一个 Module 页 concepts/ # 从 **/.marqdo/agent-kb/concepts/ 复制(O3) tasks/… skills/… ``` 路径中的目录层级拍扁为文件名时用 `__` 连接,例如: `structure/import/main.mq.md` → `modules/structure__import__main.md` `.marqdo/agent-kb/` 下的可执行 `.mq.md` **不**进 Module 表(由 Task/Skill 概念页的 `resource` 指向)。 ### 3.1 `catalog.yaml`(示意) ```yaml # GENERATED by marqdo — do not edit by hand type: Marqdo Catalog title: marqdo-project generated: by: marqdo/0.1.2 modules: - id: structure/hello resource: structure/hello.mq.md title: Hello World 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 concepts: [] # 有 agent-kb 时为 Task/Skill 条目列表 ``` | 字段 | 含义 | |------|------| | `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) | | `modules[].resource` | 相对 `PATH` 的源路径 | | `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` | | `modules[].exports` | 顶层 `#` 函数名(`kind: fn`) | | `modules[].verified` / `sources` | 源 frontmatter 有则透传(O3) | | `concepts[]` | 本地 agent-kb 概念摘要(`id`/`type`/`page`/…) | | `generated.by` | `marqdo/` | 不在现行范围:版本锁定哈希、跨仓 URL、完整符号类型、`log.md`(见 okf O4)。 ### 3.2 模块概念页 Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Dependencies** 链到同包其它 Module 页(人可点)。源若带 `verified` / `sources` 则写入页头。 ### 3.3 Agent knowledge `index.md` 的 **Agent knowledge** 节列出扫到的 Task/Skill,链到 `concepts/…`。概念页内容从本地 `agent-kb` **复制**,与 Agent 运行时包同源,便于人审阅晋升结果。 --- ## 4. 与 `view output` 的分工 | 命令 | 产物 | 受众 | |------|------|------| | `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 | | `marqdo catalog` | OKF 风格 YAML + Markdown 索引(含 agent-kb) | 人浏览依赖/技能 · 工具 / 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/`、`concepts:` 键。 2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。 3. 模块页 Dependencies 对已解析导入为 Markdown 链接。 4. 若扫描根下有 `.marqdo/agent-kb/concepts/`,则复制进 `OUT_DIR/concepts/` 且 `index.md` 有 Agent knowledge 条目。 5. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。 6. `marqdo sync` 与 `catalog` 行为一致。