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>
4.5 KiB
4.5 KiB
OKF 兼容清单:marqdo catalog
| 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) |
| 日期 | 2026-08-07 |
| 取代 | generated-yaml-manifest.md 中「待决:sync/doc 命令」的命令名部分 |
| 相关 | okf.md(实现规范总览)· generated-yaml-manifest.md · view.md · okf-and-marqdo.md |
1. 决策(重申)
YAML / OKF 风格清单是从 .mq.md 派生的生成物,不是手写配置。完整词汇、任务知识包与路线图见 okf.md。生成式方向见 generated-yaml-manifest.md。
本文件规定 CLI 与工程目录包落盘格式(含 O3:扫入本地 agent-kb 概念,供人与工具同览)。
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. 生成物
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(示意)
# 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 |
二者都从同一源树生成,互不替代。发布用户文档时可同时:
marqdo view output public -o public
marqdo catalog tests -o .marqdo
5. 验收
marqdo catalog tests -o /tmp/mq-cat写出catalog.yaml、modules/、concepts:键。catalog.yaml含structure/hello与 import 模块的imports: [utils.mq.md]。- 模块页 Dependencies 对已解析导入为 Markdown 链接。
- 若扫描根下有
.marqdo/agent-kb/concepts/,则复制进OUT_DIR/concepts/且index.md有 Agent knowledge 条目。 - 文件头或
generated标明 GENERATED;文档声明勿手改。 marqdo sync与catalog行为一致。