Files
marqdo/doc/design/catalog-cli.md
T
cflmyandCursor 96a7c6ce76 Consolidate layout: tests fixtures, public user docs, and view site.
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>
2026-08-04 14:49:44 +08:00

3.7 KiB
Raw Blame History

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. 验收

  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 行为一致。