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>
129 lines
3.7 KiB
Markdown
129 lines
3.7 KiB
Markdown
# 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/
|
||
<stem>.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/<crate version>` |
|
||
|
||
不在 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` 行为一致。
|