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>
504 lines
22 KiB
Markdown
504 lines
22 KiB
Markdown
# 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 分管工程目录与自我成长。**
|