Quiet spawn still hides child stdout; workbooks solidify to **returns**, agent-kb lives in the plugin, and multi-step follows OKF file relay rather than print-based answers. Co-authored-by: Cursor <cursoragent@cursor.com>
128 lines
4.5 KiB
Markdown
128 lines
4.5 KiB
Markdown
# 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/
|
||
<stem>.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/<crate version>` |
|
||
|
||
不在现行范围:版本锁定哈希、跨仓 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` 行为一致。
|