Files
marqdo/doc/design/okf.md
cflmyandCursor 0f72173d08 feat(ext/ai): land Agent/LLM optimize waves O1–O5
Wire opt-in sandbox trial into agent, require sandbox proof before OKF
promote, add step_route/EFI/cost surfaces, style lint + quarantine, and
offline policy optimize script—keeping GFM tables over json glue.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:47:28 +08:00

504 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Marqdo 的 OKF 实现
| | |
|---|---|
| 状态 | **Accepted(规范);实现分层见 §10** |
| 日期 | 2026-08-07 |
| 调研 | [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
| 命令现状 | [catalog-cli.md](catalog-cli.md)(v0 已落地) |
| 生成式清单方向 | [generated-yaml-manifest.md](generated-yaml-manifest.md) |
| 智能体消费面 | [ext-agent.md](ext-agent.md) · [ext-agent-plan.md](ext-agent-plan.md) · 任务知识包见本文 §7 |
| 外部规范 | [OKF SPEC v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
本文是 **Marqdo 语言侧 OKF 实现的详细设计**:界定我们借鉴什么、已经实现什么、下一阶段必须补什么。
**不把 Google OKF 整本照搬进语言语义**;Marqdo 的可执行真相永远是 `.mq.md` 源。
---
## 1. 定位
### 1.1 OKF 是什么(对我们)
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) 用 **目录中的 Markdown + YAML frontmatter** 表示可交换知识:概念一页一文、路径即 ID、链接成图、最小强制面(几乎只强制 `type`),并在 v0.2 加入信任信号。
Marqdo 对齐的判断是:
> 人类可读的 Markdown 可以成为人与 Agent 的一等交换面;**程序本身也应能投影成同一形态的知识包**。
### 1.2 Marqdo 多走的一步
| | OKF(通用知识) | Marqdo |
|--|-----------------|--------|
| 正文 | 自由散文 | **可执行语法**(`.mq.md`) |
| 成功标准 | 互通、可策展、可信任 | 能跑 + 能读 + 可被 Agent 索引 |
| 清单角色 | 知识本身 | **从源派生的投影**(非第二套权威配置) |
一句话:
**OKF 形、Marqdo 义 — 形态对齐 OKF;词汇与生命周期服务模块、依赖、任务技能与信任,而不是 BigQuery 业务概念表。**
### 1.3 三层文档(勿混)
| 层 | 谁写 | 是什么 |
|----|------|--------|
| **源** | 人 / 编码 Agent | `.mq.md`:唯一语义权威,打开即读、即可跑 |
| **工程目录包** | `marqdo catalog` | 模块依赖/导出总览(`Marqdo Module`) |
| **任务知识包** | `plan` 晋升等 | 任务↔技能↔可执行资源(`Marqdo Task` / `Marqdo Agent Skill`) |
`marqdo view output` 出 HTML 站点,与 OKF 包**分工**:人读程序站 vs Agent/工具读知识包。见 [view.md](view.md)、[catalog-cli.md](catalog-cli.md) §4。
---
## 2. 设计原则(锁定)
1. **源为唯一权威** — 依赖、导出、可执行行为以 `.mq.md` 为准;知识包是提取或晋升结果。
2. **生成、可复现** — 同一源树 + 同一工具版本 → 同一工程目录包(时间戳字段可规范化忽略)。
3. **勿手改生成物** — 文件头 / `generated` 标明 GENERATED;手改不被承认为权威。
4. **最小强制面** — 互通只要求:合法 frontmatter、`type` 字段、可解析的 `resource` / 链接;未知 `type` **必须优雅降级**(仍可读正文与已知字段)。
5. **格式而非平台** — 包可 `cat` / `git clone`;不绑定某一云或某一模型。
6. **清单可删可再生** — 无 catalog 时解释器仍能直接从源工作;catalog **不是**语言语义的一部分。
7. **可执行资源显式** — 凡声称「可跑」的概念必须有 `resource:` 指向 `.mq.md`(或等价路径),禁止只靠散文描述冒充程序。
---
## 3. 概念模型
### 3.1 Bundle(知识包)
一个 OKF 风格 bundle 是目录树:
```text
<bundle-root>/
index.md # 可选:人/Agent 总览
log.md # 可选:变更史(策展用)
catalog.yaml # 可选:机器向总清单
concepts/… # 或 modules/…:概念页(frontmatter + Markdown)
resources/… # 可选:被引用的可执行 .mq.md(任务包常用)
```
**Concept ID** = 相对 bundle 根、去掉扩展名的路径(OKF 惯例)。
例:`concepts/tasks/a1b2c3d4e5f6.md` → ID `concepts/tasks/a1b2c3d4e5f6`。
**联系** = frontmatter 中的路径字段 + 正文中的 Markdown 链接,形成可遍历图。
### 3.2 Marqdo 使用的两类 bundle
| Bundle | 默认根 | 生产者 | 消费者 |
|--------|--------|--------|--------|
| **工程目录包** | `.marqdo/`(`-o` 可改) | `marqdo catalog` / `sync` | 人、CI、未来编译加速、通用 Agent |
| **任务知识包** | `.marqdo/agent-kb/` | `ext/ai` 的 `plan` 晋升等 | 父智能体快路径、策展、复用 |
二者词汇共享(`type` / `generated` / `verified` / `status`),目录职责分离:
**不要**把探索用的 `agent-runs/` 时间戳文件当成稳定概念 ID。
---
## 4. Frontmatter 词汇表
### 4.1 所有概念页的公共字段
| 字段 | 必填 | 含义 |
|------|------|------|
| `type` | **是** | 概念类型字符串(见 §5) |
| `title` | 推荐 | 短标题 |
| `description` | 可选 | 一句话说明 |
| `tags` | 可选 | 字符串列表 |
| `resource` | 视类型 | 指向权威源或可执行 `.mq.md` 的相对路径 |
| `status` | 推荐 | `draft` \| `stable` \| `deprecated` |
| `generated` | 生成物必有 | `{ by, at? }` — 谁生成 |
| `verified` | 可选 | `{ by, at? }` — 谁核验(非 LLM 口述) |
| `sources` | 可选 | 出处列表(OKF v0.2) |
| `stale_after` | 可选 | 绝对日期,过期后消费者应降级信任 |
| 未知字段 | — | **保留、不拒绝** |
信任档位(推导,不必单独存字段):
| 条件 | 档位 |
|------|------|
| 无 `verified` | 未验证(机器生成草稿) |
| 有 `verified.by` 为确定性工具(如 `marqdo-agent/spawn`) | 机器确认 |
| 有人工审核约定(未来) | 人工审核 |
### 4.2 工程模块页额外字段(v0 已用)
| 字段 | 含义 |
|------|------|
| `depends` | 导入列表(从源 frontmatter `> path` 提取) |
| `exports` | 顶层 `#` 导出名列表 |
### 4.3 任务 / 技能页额外字段(目标词汇)
| 字段 | 所在 type | 含义 |
|------|-----------|------|
| `skill` | `Marqdo Task` | 指向 Skill 概念页的相对路径 |
| `goal` 或正文中的规范化 goal | `Marqdo Task` | 匹配材料(规范化规则见 §7.3) |
| `llm_free` | `Marqdo Agent Skill` | 资源是否仍含 `agent.step` / LLM 调用(机器启发) |
| `quality` | `Marqdo Agent Skill` | 整数启发分(长度、llm_free 等),**非**模型打分 |
---
## 5. `type` 注册表(Marqdo 义)
未知 type **不得**导致解析失败;工具可跳过专用逻辑,仍展示 title/正文/链接。
| `type` | 状态 | 含义 | 主要生产者 |
|--------|------|------|------------|
| `Marqdo Catalog` | **已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
| `Marqdo Module` | **已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
| `Marqdo Task` | **已实现** | 一项可匹配的任务意图 | `plan` 晋升 |
| `Marqdo Agent Skill` | **已实现** | 指向可执行工作簿的技能 | `plan` 晋升 |
| `Capability` / `Function` | **EKC** | 工程能力 / 符号投影 | `marqdo knowledge` |
| `Decision` / `Constraint` / `Failure` / `AntiPattern` / `Pattern` / `Migration` / `Fact` | **EKC** | L4 工程知识 | 源 frontmatter + learn |
| `Marqdo Context Pack` | **EKC** | Agent EFI 上下文制品 | `reuse` / `preflight` |
| `Marqdo Policy` | **EKC** | 复用决议编译 | `marqdo reuse` |
| `Marqdo Engineering Knowledge` | **EKC** | 工程知识总览 | `engineering.yaml` / `index.mq.md` |
| 其他 | 开放 | 第三方/未来扩展 | — |
完整 EKC 规范见 [engineering-knowledge.md](engineering-knowledge.md)。
---
## 6. 工程目录包(v0 — 已实现)
### 6.1 CLI
```bash
marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR # 别名
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或单文件;目录则递归 `*.mq.md` |
| `-o` | `.marqdo` | 输出根;写入前创建,**覆盖**同名生成文件 |
实现:[`src/catalog.rs`](../../src/catalog.rs)。金样:`tests/gold.rs` → `catalog_writes_yaml`、`catalog_includes_agent_kb_concepts`。
### 6.2 生成物布局
```text
OUT_DIR/
catalog.yaml
index.md
modules/
<path-with-__>.md
concepts/ # O3:从 **/.marqdo/agent-kb/concepts/ 复制
tasks/…
skills/…
```
路径拍扁:`structure/import/main.mq.md` → `modules/structure__import__main.md`。
`agent-kb` 下的可执行 `.mq.md` **不**进 Module 表(避免与概念/资源重复);Task/Skill 概念页进 `concepts/` 与 `catalog.yaml` 的 `concepts:`。
### 6.3 `catalog.yaml`(现行字段)
```yaml
# GENERATED by marqdo — do not edit by hand
type: Marqdo Catalog
title: marqdo-project
generated:
by: marqdo/<crate-version>
modules:
- id: structure/hello # resource 去掉 .mq.md
resource: structure/hello.mq.md
title: … # 源 frontmatter title,否则用路径
imports: [] # 或 ["lib/x.mq.md as x", …]
exports:
- name: Hello World
kind: fn
# 可选(源 frontmatter 有则透传):
# verified: { by: … }
# sources: […]
concepts: [] # 或 Task/Skill 条目(O3)
# - id: concepts/tasks/<sig>
# type: Marqdo Task
# title: …
# status: …
# page: concepts/tasks/<sig>.md
# resource: …
# skill: …
```
提取规则:
- **imports**:源文件 YAML frontmatter 中以 `>` 开头的导入行(经 `parse_import_spec`)。
- **exports**:解析成功则用 AST 顶层函数名;否则回退扫描 `# ` 标题行。
- **verified / sources**:源 frontmatter 有则写入 module/concept 条目(O3)。
- **concepts**:扫描 `**/.marqdo/agent-kb/concepts/**/*.md`,复制到 `OUT_DIR/concepts/`。
- **不**提取正文 `>` 动态调用图、不写锁哈希、不写跨仓 URL。
### 6.4 模块概念页(现行)
```yaml
---
type: Marqdo Module
title: …
resource: path/to/file.mq.md
depends: […]
exports: […]
generated:
by: marqdo/<version>
# verified / sources:源有则透传
---
```
正文含「勿手改」、**可点击依赖链接**(解析到同包其它 Module 页)、导出表。`index.md` 含 Modules 表与 **Agent knowledge** 节(链到 `concepts/`)。
### 6.5 仍相对完整 OKF 愿景的缺口
| 缺口 | 说明 |
|------|------|
| 无通用 Concept ID 遍历 API | catalog 为生成物;无独立查询命令 |
| 无 `stale_after` / Attested 再现 | 信任信号仅可选 `verified`/`sources` |
| 无 `log.md` | 无策展历史(O4) |
| 运行时不读 catalog | 解释器不依赖生成物(有意为之) |
O2/O3 已补:Task/Skill 知识包、catalog 扫入 agent-kb、模块页可点依赖、可选信任字段。
---
## 7. 任务知识包(规范 — 实现路线 O2)
服务「父智能体优化过的工作簿,同任务应直接执行」:把子 Marqdo / 技能登记为 OKF 概念,用 ID 与链接匹配,而不是私有 `index.json`。
### 7.1 布局(锁定)
```text
.marqdo/
agent-runs/workbook-<slug>-<ts>.mq.md # 仅当显式 workbook_dir= 时(可 gc)
agent-kb/ # 任务知识包 bundle(默认首次 plan 就写这里)
index.md
log.md # 可选
catalog.yaml # 可选;可由 promote 或 catalog 刷新
concepts/
tasks/<slug>.md # type: Marqdo Task;sig 在 frontmatter
skills/<slug>.md # type: Marqdo Agent Skill
resources/
<slug>.mq.md # 默认可执行工作簿(探索与晋升同一路径)
```
默认根可通过 `plan` 参数 `kb_dir` / `知识库目录` 覆盖。`.gitignore` 已忽略 `**/.marqdo/`。
路径用可读 **slug**(由 goal 派生:拉丁小写、CJK 保留、其它变 `-`,最长约 48 字符)。**`sig` 仅写在 frontmatter**,用于精确匹配。同 slug 异 sig 时用 `slug-<sig前4位>`。旧包若仍以 `<sig>` 为文件名,lookup 会回退识别。
### 7.2 概念页模板
**Task**(匹配入口):
```yaml
---
type: Marqdo Task
title: <短摘要>
description: <规范化 goal>
sig: <12hex>
status: stable
tags: [agent-task]
skill: ../skills/<slug>.md
generated:
by: marqdo-agent/plan
verified:
by: marqdo-agent/spawn
at: <ISO8601>
---
# Task
See [skill](../skills/<slug>.md).
```
**Skill**(可执行绑定):
```yaml
---
type: Marqdo Agent Skill
title: <短名>
sig: <12hex>
resource: ../../resources/<slug>.mq.md
status: stable | candidate | quarantine
llm_free: true | false
quality: <int>
hits: <int>
# O2 optional metadata (from workbook frontmatter; see §7.5):
applies_when: <text condition or tag>
fixtures: <relative .mq.md proof path>
sandbox_profile: default | readonly | <name>
proof: <relative .mq.md> # alias of fixtures for sandbox gate
generated:
by: marqdo-agent/plan
at: <ISO8601>
verified:
by: marqdo-agent/spawn
at: <ISO8601>
---
# Skill
Prefer spawning `resource` over re-planning.
```
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。**O2:** `agent_kb_promote` 默认要求 sandbox proof(`proof` / `fixtures` / workbook 本身经 `sandbox.run` 成功)才写入;失败返回 `promoted: false` / `reason: sandbox_proof_failed`。传 `require_proof=false` 仅用于明确豁免。
### 7.3 任务签名 → Concept 路径
材料:
1. `goal`:Unicode NFC → trim → 连续空白折叠为单空格。
2. 若调用方工具表非空:工具名排序后追加进材料。
3. **不**把父 `standing` 计入签名(易变导致永不命中)。
输出:稳定短哈希 `sig`(`agent_goal_sig`)+ 可读 `slug`(`agent_goal_slug`)。路径:
- `concepts/tasks/<slug>.md`
- `concepts/skills/<slug>.md`
- `resources/<slug>.mq.md`
匹配顺序:
1. **精确**:slug 试探 + frontmatter `sig` → 扫目录 `sig:` → 旧 hex 文件名。
2. **别名(Accepted)**:精确 miss 后,扫 Task FM `aliases:`(YAML 列表或 `[a, b]`);`normalize_goal(query)` 与某条 alias **精确相等**则命中同一 Skill/resource。lookup 返回 `match: exact|alias`;`plan` 对 alias 写 `cache=soft-hit`。
3. **规范句(Accepted)**:仍 miss 时对 goal 做轻量 `agent_kb_canonicalize`(剥站立前缀、去尾标点),再精确/别名各试一次;命中返回 `match: canonical`,`cache=soft-hit`。
4. **近义(Accepted,默认开)**:仍 miss 且 `near_match=True` 时,对 Task `title|description|aliases` 做本地**字符 bigram 词袋 + 余弦**;`best.score >= near_threshold`(默认 `0.78`)则 `match: near` 并带 `score`,`cache=soft-hit`,并可 `agent_kb_add_alias`。这是稀疏词法近邻,**不是** embedding 模型。
5. **父裁决 soft_match(Accepted,默认关)**:仍 miss 且 `plan soft_match=True` 时,把 `agent_kb_near_match` 排序候选(含 score;空则退回 `list_tasks`)交给父模型:`DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`;REUSE 后可 `agent_kb_add_alias`。
6. **不做**默认 dense embedding / 远程向量库。远期 dense 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) E。
`agent_kb_promote` 可选 `aliases=`(字符串或列表)写入 Task;再晋升时合并既有 aliases。
### 7.4 与 `## plan` 的契约
| 参数 | 默认 | 含义 |
|------|------|------|
| `reuse` / `复用` | `True` | 允许知识包快路径 |
| `optimize` / `优化` | `False` | 跳过知识包,强制再规划 |
| `force` / `强制` | `False` | 忽略知识包 |
| `soft_match` / `软命中` | `False` | miss 后父裁决 REUSE/NEW(须显式打开;候选为 near 排序列表) |
| `near_match` / `近义命中` | `True` | lookup 第四趟本地 n-gram;`False` 关闭 |
| `near_threshold` / `近义阈值` | `0.78` | near 自动命中最低余弦分 |
| `promote` / `晋升` | `True` | DONE 后固化并写入/更新概念与 resource |
| `kb_dir` / `知识库目录` | `.marqdo/agent-kb` | bundle 根 |
| `workbook_dir` / `工作簿目录` | `None` | 默认直接写 `kb_dir/resources/<slug>.mq.md`;显式传入则用该目录下的临时 `workbook-<slug>-<ts>.mq.md` |
| `improve_every` / `改进周期` | `3` | candidate 每 N 次命中触发 ≤1 轮改进 |
| `explore_n` / `探索次数` | `3` | 同任务已有文件数 `< N` 且非 `llm_free` 时,强制新建 `explore/<slug>/<k>.mq.md` 尝试不同路径(第 2 次默认 dual 骨架) |
调用示例(路径可直接写在参数里,无需 `json.parse`):
```markdown
> `助手`.plan goal=… max_rounds=3
> `助手`.plan goal=… workbook_dir=".marqdo/agent-runs"
> `助手`.plan goal=… explore_n=3
```
快路径:
1. lookup 命中且 resource **llm_free**(含现场检测已固化源)→ spawn → `cache=hit`,**父 LLM 不调用**。
2. 否则若任务相关文件数 `< explore_n` → 写入新的 explore 变体,父 LLM 被提示尝试不同路径;成功则固化并晋升。
3. 否则走 candidate 命中 / `improve_every` 改进逻辑。
`DECISION: DONE` 时先 `agent_workbook_solidify`(把仍含 `worker.step` 的簿固化为 `# main` **返回**答案,而非仅 `print`),再晋升并写 `verified`。
显式 `workbook=` 续跑优先于知识包查找。
质量启发(覆盖 skill 时,不调模型):`llm_free` 优先;源更短优先;同质取较新。更差 `quality` 不覆盖现 skill。
### 7.5 自我成长如何落在 OKF 上
| 能力 | 机制 |
|------|------|
| 优化 | 规划循环固化代码 → 更优 `resources/<slug>.mq.md` |
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
| **证明晋升(O2)** | `applies_when` / `fixtures` / `sandbox_profile` / `proof` 写在技能与 workbook frontmatter;promote 前 `sandbox.run` 绿才 `llm_free` |
| **隔离(O5)** | 失败技能 `status: quarantine`;回归 fixture 跟随 slug |
### 7.5a 技能 frontmatter 约定(O2 B1)
| 字段 | 含义 |
|------|------|
| `applies_when` | 适用条件(短文本 / 标签);路由与 harness 可读 |
| `fixtures` | 相对路径:sandbox 证明用 `.mq.md` |
| `sandbox_profile` | `default` / `readonly` / 其它 `sandbox.profile` 名 |
| `proof` | 与 `fixtures` 同义;promote 优先读 `proof` 再 `fixtures`,否则跑 workbook 自身 |
---
## 8. 运行时与工具职责
| 组件 | 读 OKF? | 写 OKF? | 备注 |
|------|----------|----------|------|
| 解释器 / 字节码 VM | 否(语义) | 否 | 只跑 `.mq.md` |
| `marqdo catalog` | — | 工程目录包 | v0 |
| `plugins/agent`(`agent_kb_*`)+ `ext/ai` `plan` | 任务包 | 晋升时写任务包 | O2;**不**进核心 `src/host` |
| `lib/fs` | 通用文件 | 通用文件 | L1 包装 |
| `marqdo view` | 否 | 否 | HTML 另一轨 |
| 未来 `marqdo kb query` | 是 | 否 | 可选:按 type/tag/链接查询 |
agent-kb 运行时实现归属 **agent 插件**(`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / `agent_kb_record_hit` / `agent_workbook_solidify` / `agent_kb_task_files`),由 `ext/ai/agent` 调用;禁止把这些原语加回 `HostFn`。
解释器**不得**因缺少 catalog 而拒绝运行源文件。
---
## 9. 安全与边界
| 风险 | 对策 |
|------|------|
| 把生成物当配置手改 | 文档 + GENERATED 头;CI 可选校验 |
| 错误技能被复用 | 快路径必 spawn+inspect;失败标 `draft` 并重规划 |
| 签名过宽 | tools 指纹;文档强调 exact goal |
| 密钥进入知识包 | 继承 env;禁止把 key 写入 resource/概念正文 |
| 包膨胀 | runs 与 kb 分离;仅 DONE 晋升 |
| 与语言语义耦合 | catalog/kb 失败不影响 `marqdo run` 源文件 |
---
## 10. 实现路线
| 阶段 | 内容 | 状态 |
|------|------|------|
| **O0** | 调研 + 生成式清单方向 + `.mq.md` 后缀 | **done** |
| **O1** | `marqdo catalog` / `sync`:Module + Catalog YAML | **done**(v0) |
| **O2** | 本文锁定的任务知识包:`Marqdo Task` / `Agent Skill`;`plan` reuse/promote | **done**(host kb_* + plan 快路径) |
| **O3** | catalog 增强:`verified`/`sources` 可选;模块页可点击依赖;扫入 `agent-kb` 概念供人浏览 | **done** |
| **O4** | `log.md` 策展、可选 `kb query`、Attested-style「再现跑通」收据(非 BigQuery) | 远期 |
| **O5** | 相近任务软命中:aliases + canonicalize + 本地 n-gram `near` + `soft_match` 父裁决已落地;dense embedding 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) E | **A/B/C/D-near done** |
O2 设计落盘后,智能体侧实现文档可薄化为指向本文 §7,避免两套真理。
---
## 11. 非目标
- 在 Marqdo 内核实现完整 OKF 验证器产品或云托管知识库。
- 用 OKF 清单替代模块命名空间 / 导入语义([module-namespace.md](module-namespace.md))。
- 强制用户提交 `.marqdo/` 进 git。
- **默认**语义相似检索 / 向量库(可选软命中见 O5 / [okf-near-match.md](../roadmap/okf-near-match.md);不进内核)。
- 跨仓技能市场(可后续在概念图上扩展)。
- 照搬 OKF `Attested Computation` 的 BigQuery executor 模型。
---
## 12. 与既有文档的关系
| 文档 | 关系 |
|------|------|
| [okf-and-marqdo.md](../research/okf-and-marqdo.md) | 调研;产业背景与借鉴边界 |
| [generated-yaml-manifest.md](generated-yaml-manifest.md) | 早期「生成式清单」方向;**词汇与原则并入本文,命令细节见 catalog-cli** |
| [catalog-cli.md](catalog-cli.md) | O1 CLI 与 v0 落盘的操作说明 |
| [ext-agent-plan.md](ext-agent-plan.md) | 多步执行;缓存/复用应引用本文 §7 |
| [ext-agent.md](ext-agent.md) | 框架总览;自写回 ≠ 跨调用 OKF 知识包 |
---
## 13. 决议摘要
1. Marqdo 的 OKF 实现 = **形态对齐 + Marqdo 类型词汇 + 生成/晋升管道**,不是语言换皮。
2. **O1–O3 已落地**(工程目录包、任务知识包、catalog 扫入 agent-kb + 人读链接图);**O4** 策展/查询为远期。
3. 可执行真相是 `.mq.md`;概念页负责**寻址、信任与联系**——人与 Agent 都是闭环里的一环。
4. 父智能体复用优化结果,应走 **Task → Skill → resource → spawn**,而不是私有 JSON 缓存主路径。
5. 未知 `type` 降级;无清单亦可运行源码。
---
## 14. 一句话
**Marqdo 用 OKF 风格的知识包索引程序与任务技能:源负责跑,概念负责找与信,catalog 与 agent-kb 分管工程目录与自我成长。**