Make file subtasks return #main value and expose it as plan.result.

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>
This commit is contained in:
cflmyandCursor committed 2026-08-07 17:53:14 +08:00
1 parent fbece725e1
commit d1b33c78c6
55 files changed
+3498 -169

No files matched your search

+3 -2
View File
@@ -22,8 +22,9 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
5. **Identifiers use backticks** — params `` + `name` ``, bindings `` `x` ``, foreach `` [`item`](`coll`) ``. **Complex text** uses `"..."` with escapes; bare tokens stay literal (no `\n` magic).
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths in bare expressions:** `/` is division. Prefer `` `path` `` vars, same-dir names, or call args — not raw `a/b` in expressions.
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed.
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
## Markup → meaning (v0.2)
@@ -32,7 +33,7 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
| `#` | **Object / type** (constructor body). `# main` = entry object. |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
+9
View File
@@ -159,4 +159,13 @@ if x > 0:
# GOOD — ordered list arms
1. `x` > 0
> print text=pos
2. *
> print text=other
# GOOD — another independent branch (restart at 1.)
1. `y` > 0
> print text=y-pos
2. *
> print text=y-other
```
+1 -1
View File
@@ -18,7 +18,7 @@ marqdo ext remove llm|agent
Diagnostics look like `path:line:col: message` (1-based line/col).
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * ``; loops `` - [`item`](`coll`) ``; identifiers in backticks. See `doc/design/markdown-mapping.md`.
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [`item`](`coll`) ``; identifiers in backticks. See `doc/design/markdown-mapping.md`.
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
+1
View File
@@ -22,6 +22,7 @@
*.pdb
.DS_Store
.marqdo/
**/.marqdo/
.env
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
Generated
+2 -1
View File
@@ -1,6 +1,6 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 3
version = 4
[[package]]
name = "adler2"
@@ -477,6 +477,7 @@ dependencies = [
name = "marqdo_plugin_agent"
version = "0.1.0"
dependencies = [
"chrono",
"serde_json",
]
+3 -2
View File
@@ -20,7 +20,9 @@
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 |
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单(早期方向) |
| [design/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
@@ -41,7 +43,6 @@
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
| [design/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
+32 -33
View File
@@ -2,18 +2,18 @@
| | |
|---|---|
| 状态 | 已定(v0 命令落地) |
| 日期 | 2026-08-04 |
| 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) |
| 日期 | 2026-08-07 |
| 取代 | [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) |
| 相关 | [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` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。完整词汇、任务知识包与路线图见 [**okf.md**](okf.md)。生成式方向见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
本文件规定 **CLI 与 v0 落盘格式**。
本文件规定 **CLI 与工程目录包落盘格式**(含 O3:扫入本地 `agent-kb` 概念,供人与工具同览)。
---
@@ -28,26 +28,31 @@ marqdo sync [PATH] -o OUT_DIR
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件) |
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
---
## 3. 生成物(v0)
## 3. 生成物
```
OUT_DIR/
catalog.yaml # 机器向总清单(OKF 风格字段)
index.md # 人/Agent 可读总览(含 YAML frontmatter)
index.md # 人可读总览:Modules + Agent knowledge
modules/
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
<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
@@ -55,12 +60,11 @@ OUT_DIR/
type: Marqdo Catalog
title: marqdo-project
generated:
by: marqdo/0.0.1
# at: 可选 ISO8601;CI 比对时可忽略
by: marqdo/0.1.2
modules:
- id: structure/hello
resource: structure/hello.mq.md
title: Hello World # 来自源 frontmatter title,缺省用文件名
title: Hello World
imports: []
exports:
- name: Hello World
@@ -72,35 +76,28 @@ modules:
exports:
- name: main
kind: fn
concepts: [] # 有 agent-kb 时为 Task/Skill 条目列表
```
字段约定(v0 最小集):
| 字段 | 含义 |
|------|------|
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
| `modules[].resource` | 相对 `PATH` 的源路径 |
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`) |
| `modules[].verified` / `sources` | 源 frontmatter 有则透传(O3) |
| `concepts[]` | 本地 agent-kb 概念摘要(`id`/`type`/`page`/…) |
| `generated.by` | `marqdo/<crate version>` |
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
不在现行范围:版本锁定哈希、跨仓 URL、完整符号类型、`log.md`(见 okf O4)。
### 3.2 模块概念页 frontmatter
### 3.2 模块概念页
```yaml
---
type: Marqdo Module
title: …
resource: structure/hello.mq.md
depends: [] # imports 列表
exports: [Hello World]
generated:
by: marqdo/0.0.1
---
```
Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Dependencies** 链到同包其它 Module 页(人可点)。源若带 `verified` / `sources` 则写入页头。
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
### 3.3 Agent knowledge
`index.md` 的 **Agent knowledge** 节列出扫到的 Task/Skill,链到 `concepts/…`。概念页内容从本地 `agent-kb` **复制**,与 Agent 运行时包同源,便于人审阅晋升结果。
---
@@ -109,7 +106,7 @@ generated:
| 命令 | 产物 | 受众 |
|------|------|------|
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引(含 agent-kb) | 人浏览依赖/技能 · 工具 / Agent |
二者都从同一源树生成,互不替代。发布用户文档时可同时:
@@ -122,7 +119,9 @@ marqdo catalog tests -o .marqdo
## 5. 验收
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml`、`modules/`、`concepts:` 键。
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
4. `marqdo sync` 与 `catalog` 行为一致。
3. 模块页 Dependencies 对已解析导入为 Markdown 链接。
4. 若扫描根下有 `.marqdo/agent-kb/concepts/`,则复制进 `OUT_DIR/concepts/` 且 `index.md` 有 Agent knowledge 条目。
5. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
6. `marqdo sync` 与 `catalog` 行为一致。
+6 -3
View File
@@ -45,6 +45,7 @@ Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` o
| `module_source` | string | Entry `.mq.md` text |
| `call_site` | `{path,function,line}` | Active call site |
| `marqdo_skill` | string | Skill pack text |
| `cwd` | string | Host `cwd` (entry file directory) for path resolution |
Unknown names fail. Queries are only valid during a plugin function call (host sets thread-local context).
@@ -82,15 +83,17 @@ cargo build -p marqdo_plugin_agent
```
- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
- Agent (ABI v2): layout + session bag + `agent_module_source` / `agent_format_tools` / … — [`plugins/agent`](../../plugins/agent); used by [`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md). Lookup: `plugin.native_path name=agent` or [ext-cli.md](ext-cli.md) install / `MARQDO_AGENT_PLUGIN`.
- Agent (ABI v2): layout + session bag + context queries + **OKF agent-kb** (`agent_goal_sig`, `agent_goal_slug`, `agent_kb_lookup`, `agent_kb_promote`, `agent_kb_record_hit`, `agent_workbook_solidify`, `agent_kb_task_files`) — [`plugins/agent`](../../plugins/agent); used by [`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md). Lookup: `plugin.native_path name=agent` or [ext-cli.md](ext-cli.md) install / `MARQDO_AGENT_PLUGIN`.
## Layering
| Layer | May call `host_*` |
|-------|-------------------|
| `lib/*` | Yes (only L1 wrappers) |
| `lib/*` | Yes (only L1 wrappers of generic L0.5) |
| `ext/*` | **No** — compose `lib/*` or ABI plugin names via `lib/plugin` |
| Application `.mq.md` | Same as ext |
| Application `.mq.md` | Prefer same as ext; do not add agent/OKF originals to `src/host` |
**Hard rule:** agent / OKF domain primitives live in `plugins/agent`, never in `HostFn` / `src/host/kb.rs`.
## Non-goals
+71 -30
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **Accepted;D2a(`step` 默认写回)已落地;其余 D2 待实现** |
| 状态 | **Accepted;D2a 已落地;D2b–D2d(观察→补丁式多步)实现中** |
| 日期 | 2026-08-07 |
| 父文档 | [ext-agent.md](ext-agent.md) |
| 相关 | [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) |
@@ -15,9 +15,9 @@
1. **把分解与执行过程落成一份可运行的 `.mq.md`**(工作簿),而不是藏在进程内的任务图。
2. **用子任务真正跑这份工作簿**,与主推理隔离。
3. **允许工作簿在「跑 → 看结果 → 改代码 / 改写回 → 再跑」中演化**——既更新可执行语句,也更新 `<!-- marqdo-out … -->`。
4. **父智能体持有与单步同等级的上下文**(源码、Skill、调用位置、历史),并能创建 / 修改 / 再执行工作簿。
5. **能固化的步骤尽量固化为 Marqdo 代码**;仅不确定分支继续交给子智能体。
3. **父智能体作为「智能体开发大师」**:结构化读取执行结果与写回,再二次规划;用**精确补丁**改工作簿代码,并把确定步骤**固化为普通 Marqdo `##`**。
4. **允许工作簿演化**——代码与 `<!-- marqdo-out … -->` 均可更新,但**禁止**以整文件 LLM 重写作为修订主路径。
5. 子智能体只做不确定的 `单步`;能写成代码的就不要再问模型。
本文锁定 **`## 多步` / `## plan`** 的语义。总览与分层见 [ext-agent.md](ext-agent.md);实现以 D2 为准。
@@ -25,7 +25,7 @@
## 2. 一句话
**多步 = 父智能体生成(并持续修订)一份子 runbook `.mq.md`,用与父相同的大模型配置,经 `lib/subtask` 启动该文件;子文件内推荐多个 `# 智能体`(或一个智能体多次单步);结果靠单步默认写回 + 父侧汇总写回沉淀;确定步骤优先写成普通 Marqdo 代码。**
**多步 = 父智能体(开发大师)生成并演进一份子 Marqdo 程序:经 `lib/subtask` 运行它,结构化观察写回与源码,再二次规划并精确打补丁;子 `# 智能体` 只跑 `单步`,确定步骤固化为代码。**
---
@@ -41,7 +41,7 @@
| 产物 | 说明 |
|------|------|
| 工作簿路径 | 默认目录 `.marqdo/agent-runs/`(可参数覆盖);文件名含时间 / 短 id |
| 父侧返回值 | 结构化 map:`status`、`goal`、`workbook`(路径)、`summary` / `error`;可选引用子写回摘要 |
| 父侧返回值 | 结构化 map:`status`、`goal`、`workbook`(路径)、`result`(子 `# main` 返回值优先)、`summary` / `error`;可选 `observation` |
| 写回 | 工作簿内各 `单步` 默认落盘;父 `多步` 调用行亦可汇总写回 |
---
@@ -62,11 +62,11 @@
▼
④ lib/subtask:spawn path=<工作簿绝对或相对路径>
▼
⑤ wait → 收集退出码、stdout、工作簿内写回块
⑤ wait → 收集 `{code, value}`(`# main` 返回)+ 工作簿内写回块;TTY 默认静默
▼
⑥ 父智能体阅读结果(源码最新版 + 写回 + 子输出)
- 成功且充分 → 汇总,写回父文档,返回
- 不足 / 失败 → **修改工作簿**(代码与/或 marqdo-out)→ 回到 ④
⑥ 父智能体 **结构化观察**(工作簿最新源码 + 写回槽 + 退出码 + `value`)
- 充分 → 汇总,写回父文档,返回
- 不足 / 失败 → **二次规划** → 对工作簿打**精确补丁**(禁止整文件重写)→ 回到 ④
▼
⑦ 触达最大修订轮次或深度 → 以 error / 部分摘要返回
```
@@ -75,10 +75,56 @@
- **创建文件发生在 `多步` 内**,不是调用方手写脚手架(调用方可传已有 `工作簿=` 路径以续跑)。
- **执行工作簿 = 子任务跑整文件**(入口 `# main`),不是父进程内嵌解释子 AST。
- **修订循环属于父智能体职责**:同一 `多步` 调用内可多轮「改文件 → 再 spawn」。
- **父是智能体开发大师**:读真实执行结果再规划;修订靠精确补丁与代码固化,不靠整文件重生。
- **修订循环属于父智能体职责**:同一 `多步` 调用内可多轮「观察 → 规划 → 补丁 → 再 spawn」。
---
## 4.1 观察面与补丁(锁定)
父每次二次规划前必须拿到观察 map(`inspect_workbook`):
| 字段 | 含义 |
|------|------|
| `path` | 工作簿路径 |
| `source` | 最新全文 |
| `exit_code` | 上一轮子任务退出码 |
| `value` | 子 `# main` 返回值(经 `await_workbook` / `wait.value`) |
| `slots` | 命名写回列表(`key` + `body`) |
| `last_ok` / `last_error` | 便捷字段 |
二次规划输出协议(机器可解析;**禁止**只输出整份 `.mq.md`):
```text
DECISION: DONE
SUMMARY: <汇总>
DECISION: CONTINUE
PATCH:
<<<
FIND
<确切旧片段>
===
REPLACE
<新片段>
>>>
```
应用器对文件做**精确** FIND→REPLACE;找不到则报错,由父缩小补丁。优先把已验证的 `step` **固化为返回答案的普通代码**(`**…**`,不要只靠 `print`)。
---
## 4.2 多轮哲学:仅子智能体接力(模式 C)
复杂 / 多轮目标 = **多份可执行 `.mq.md` 接力**,经 OKF 索引与复用;父 `plan` 聚合各子 `wait.value` 为 `result`。
| 做 | 不做 |
|----|------|
| 每主题 / 子目标一份工作簿(`resources/` / `explore/`) | 单文件无限追加「对话日志」 |
| OKF task/skill 做索引与命中 | 单文件状态机表冒充流程 UI |
| `# main` **返回**答案;`quiet` 只管 TTY | 依赖子 `print` 把答案刷到父终端 |
---
## 5. 大模型配置与父保持一致
工作簿内构造子智能体时:
@@ -183,7 +229,7 @@ title: agent-run-…
| 子 `step`(默认开) | 该步 decision / tool / result 或 error |
| 父 `plan` | 工作簿路径、轮次、汇总摘要;可选把关键子 ok 块索引写在父调用行下 |
**推荐**:子结果以工作簿内写回为真相;父维护「总状态」写回,避免只靠 stdout。
**推荐**:载荷以子 `# main` 返回值(`wait.value` → `plan.result`)为准;写回作审计与 step 缓存。避免只靠 stdout(默认静默会丢弃)。
### 7.3 返回值
@@ -202,18 +248,11 @@ title: agent-run-…
| **父文件源码** | `agent_module_source` |
| **调用位置** | `agent_call_site` |
| **Marqdo Skill** | `agent_marqdo_skill` |
| **工作簿路径与全文**(或增量 diff) | 磁盘读回 |
| **工作簿内写回块** | `writeback.list` / 扫描 `marqdo-out` |
| **子任务 stdout / 退出码** | `subtask.wait` 结果 |
| **对话 / 历史**(若有) | 父 session;真相仍以文档写回为准,历史仅辅助 |
| 工作簿全文 / 写回 / 子返回 | `inspect_workbook`(源码 + slots + 退出码 + `value`) |
| 子任务退出码 | `subtask.wait` |
| 对话 / 历史 | 父 session;真相以写回为准 |
父模型输出应优先是:
1. **对工作簿的具体修改意图**(增删改哪些段落 / 固化哪一步);或
2. **判定完成**并给出汇总文案;或
3. **请求再跑一轮**(无改或小改后 spawn)。
禁止把「只能改内存状态、不落盘」当作多步的主路径。
父模型输出必须是 **DONE / CONTINUE+精确补丁** 协议(见 §4.1),禁止整文件重写。
---
@@ -229,6 +268,8 @@ title: agent-run-…
| 最大深度 | `最大深度` / `max_depth` | `2` | 工作簿内再调 `多步` 的嵌套上限;叶强制单步 |
| 最大轮次 | `最大轮次` / `max_rounds` | 实现选定(如 `4`) | 父「改文件 → 再执行」循环上限 |
| 确认分解 | `确认分解` / `confirm` | `假` | `真` 时首版工作簿生成后暂停(返回 pending + 路径),不自动 spawn |
| 写回 | `写回` / `writeback` | `真` | 父侧汇总写回 |
| 骨架 | `骨架` / `skeleton` | `single` | `single` 单 worker;`dual` 为 research→writer 两子智能体 |
返回 map(字段名英文字段,中文面可读同一结构):
@@ -274,7 +315,7 @@ title: agent-run-…
|--------|----------|
| 分解表 + 每行一个子智能体实例 | **整文件工作簿**可含多智能体与固化代码;表只是可选骨架 |
| 子任务默认单步,写回在流水线步骤里点到为止 | **单步默认自动写回**;父负责修订循环与汇总 |
| 缓存命中略写 | 仍有效:读工作簿 `ok` 槽,签名命中可跳过模型(D2 可后置) |
| 缓存命中略写 | **以 OKF 任务知识包为准**([okf.md §7](okf.md)):Task→Skill→resource 命中则跳过父模型;D2 + O2 已落地;人读目录见 O3 `marqdo catalog` |
| 父上下文未强调工作簿全文 | 父每次修订前必须能读**最新工作簿 + 写回** |
---
@@ -284,11 +325,11 @@ title: agent-run-…
| 项 | 内容 |
|----|------|
| D2a | `step` 增加 `writeback=`(默认真);金样例改默认行为并保留 `writeback=False` 测例 | **done** |
| D2b | 工作簿模板 + 创建路径 + 父 llm 继承约定 |
| D2c | `plan`:生成 → `spawn path` → wait → 读写回;无修订循环的最小闭环 |
| D2d | 父修订循环(改文件再执行)+ `max_rounds` |
| D2e | 多子智能体模板与「固化为代码」提示写入 Skill / standing 片段 |
| D2f | 离线骨架金样例 + 可选 live 多步 |
| D2b | 工作簿模板 + 创建路径 + 父 llm 继承;`inspect_workbook` 观察面 | **done** |
| D2c | `plan`:生成 → `spawn path` → wait → **观察** → 返回;`confirm` | **done** |
| D2d | 二次规划 + **精确补丁**循环(`max_rounds`);禁止整文件重写 | **done**(主路径) |
| D2e | 多子智能体模板与固化提示 | **done**(`skeleton=dual` + Solidify 段 + 父规划优先级) |
| D2f | 离线骨架金样例 + 可选 live 多步 | **done**(decision 离线 + `agent-plan-live`) |
---
@@ -300,7 +341,7 @@ title: agent-run-…
4. **工作簿内推荐多个智能体**;也允许单智能体多 `step`;**确定步骤固化为代码**。
5. **工作簿持续更新**:代码 + `marqdo-out`。
6. **`单步` 默认自动写回**(`写回=` 可关);父维护汇总写回。
7. **父具备源码、Skill、位置、历史与工作簿全文**,并能按结果修改后再执行。
7. **父具备源码、Skill、位置、历史与工作簿观察面**,二次规划后以**精确补丁**修改再执行(禁止整文件重写主路径)。
---
+13 -5
View File
@@ -4,7 +4,7 @@
|---|---|
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
| Date | 2026-08-07 |
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
## 0. 为什么要改掉旧方案
@@ -112,7 +112,7 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
|---|---|
| **输入** | 复杂目标 |
| **过程** | 父智能体**创建(或续跑)一份工作簿 `.mq.md`** → 子文件大模型配置与父一致 → **`lib/subtask` `spawn path=`** 运行该文件 → 读结果与写回 → **改代码 / 改写回后再执行**(有轮次上限) |
| **输出** | 汇总 map + 磁盘上的工作簿(代码与 `marqdo-out` 均可演化) |
| **输出** | 汇总 map(含 `result`)+ 磁盘上的工作簿(代码与 `marqdo-out` 均可演化) |
| **适用** | 需分解、多情形、可固化步骤、可复用子成果的任务 |
公开方法:`## 多步` / `## plan`。
@@ -122,7 +122,7 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
1. **创建工作簿** — 默认 `.marqdo/agent-runs/`;内容为任务的详细可执行步骤(导入、工具、`# main`、子智能体)。
2. **模型配置继承父智能体** — 共享 env / 等价 llm 句柄;v1 不静默换模。
3. **子任务执行整文件** — 不是父进程内嵌解释。
4. **工作簿内推荐多个 `# 智能体`**;也允许一个智能体多次 `单步`;**已确定步骤应固化为普通 `##` 代码**。
4. **工作簿内推荐多个 `# 智能体`**;也允许一个智能体多次 `单步`;**已确定步骤应固化为返回答案的普通代码**(多轮 = 多文件接力 + OKF,见 [ext-agent-plan.md §4.2](ext-agent-plan.md))。
5. **持续更新** — 代码修订 + 写回注释刷新(替换不累积空行)。
6. **`单步` 默认自动写回**(`写回=` / `writeback=` 可关),父侧再汇总写回。
7. **父上下文** — 与单步同级的源码 / Skill / 调用位置 / 历史,外加工作簿全文与子写回。
@@ -164,7 +164,14 @@ ext/
本地开发须先 `cargo build -p marqdo_plugin_agent`(或 `ext add agent` / 设 `MARQDO_AGENT_PLUGIN`)。详见 [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md)。
**分层纪律**:`ext/*` **禁止** `host_*`;用 `lib/*` 包装或插件注册名。进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
**分层纪律(硬规则,勿破)**:
1. `ext/**/*.mq.md` **禁止**出现任何 `host_*` / `host_` 调用。
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
---
@@ -320,9 +327,10 @@ lib/subtask:spawn fn=<名> → wait
|------|------|------|
| D0 | 本文 Accepted;废弃 thin TOOL 设计叙述 | **本文件** |
| D1 | 重写 `ext/ai/agent.mq.md` / `智能体.mq.md`:`单步` + 源码/位置注入 + **子任务调工具** + **结构化返回值**;运行时经 **ABI v2 agent 插件**(禁 ext 直调 host) | **done** |
| D2 | `多步`:按 [ext-agent-plan.md](ext-agent-plan.md)(工作簿创建、`spawn path`、修订循环);**D2a `step` 默认写回已落地** | D2a done;其余 TODO |
| D2 | `多步`:按 [ext-agent-plan.md](ext-agent-plan.md)(观察→精确补丁;禁止整文件重写);**D2a–D2f 主路径已落地** | **done** |
| D3 | 金样例:离线单步 / 写回;**live 单步**(`tests/ext/agent-run-live.mq.md`);多步骨架(可不打网) | **live done** |
| D4 | `view` / `debug` 对工作簿与写回块的导航体验 | TODO |
| O2 | OKF 任务知识包:`plan` reuse/promote([okf.md §7](okf.md)) | **done** |
### 非目标
+2 -2
View File
@@ -4,9 +4,9 @@
|---|---|
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
| 日期 | 2026-08-04 |
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) · **实现规范 [okf.md](okf.md)** |
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
| 说明 | 原则仍有效;**类型表、任务知识包、路线图以 [okf.md](okf.md) 为准** |
---
## 决策
+17 -1
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、标识符反引号、`-` 专用于循环) |
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
| 日期 | 2026-08-07 |
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) |
@@ -209,6 +209,22 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
> print text=False
```
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`**(无论中间有无空行)开启**下一条**独立分支语句,不得并入上一段的臂列表:
```markdown
1. `a`
> print text=A
2. *
> print text=not-A
1. `b`
> print text=B
2. *
> print text=not-B
```
上例为两次独立判断(先 `a` 再 `b`),不是「四个臂的一个分支」。臂序号在同一分支内递增(`1.` → `2.` → `3.` …);**不要**在同一分支中途把序号重置为 `1.`。
```markdown
- [`果`](`篮子`)
> print text=今天吃`果`
+4 -2
View File
@@ -223,8 +223,10 @@ path_callee ::= ident ('.' ident)+
| 层 | 影响 |
|----|------|
| L0 内置 | 仍为全局短名 |
| L1 / 官方 ext | 经库路径调用;`ext` 仍禁 `host_*` |
| ABI 插件 | 仍为插件注册表;不强制并入点号树 v1 |
| L1 / 官方 ext | 经库路径调用;**`ext/**/*.mq.md` 严禁 `host_*`** |
| ABI 插件 | 插件注册表;agent/OKF 等领域逻辑放这里,**不得**塞进 `HostFn` |
**硬规则**:不得为「方便」把 `ext/ai` 领域能力写进 `src/host/dispatch.rs` / `src/host/*.rs`。标准库可走 `lib/*` → 薄 `host_*`;智能体专属走 `plugins/agent` 注册名(见 [ext-agent.md](ext-agent.md) §4)。
---
+468
View File
@@ -0,0 +1,468 @@
# 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` | **v0 已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
| `Marqdo Module` | **v0 已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
| `Marqdo Task` | **规范已定;实现待做** | 一项可匹配的任务意图 | `plan` 晋升 |
| `Marqdo Agent Skill` | **规范已定;实现待做** | 指向可执行工作簿的技能 | `plan` 晋升 |
| 其他 | 开放 | 第三方/未来扩展 | — |
**不**引入 Google OKF 的 `Metric` / BigQuery 表类型作为 Marqdo 核心词汇;需要时可由用户包自行使用,运行时降级。
---
## 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
llm_free: true | false
quality: <int>
hits: <int>
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 次改进)。失败运行不晋升;质量更差不覆盖。
### 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`
匹配:先按 slug 试探并核对 frontmatter `sig`,再扫目录按 `sig:`,最后回退旧 hex 文件名。v1 **精确命中**;不做 embedding。
### 7.4 与 `## plan` 的契约
| 参数 | 默认 | 含义 |
|------|------|------|
| `reuse` / `复用` | `True` | 允许知识包快路径 |
| `optimize` / `优化` | `False` | 跳过知识包,强制再规划 |
| `force` / `强制` | `False` | 忽略知识包 |
| `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/` 可复制(格式即契约) |
---
## 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) | 远期 |
O2 设计落盘后,智能体侧实现文档可薄化为指向本文 §7,避免两套真理。
---
## 11. 非目标
- 在 Marqdo 内核实现完整 OKF 验证器产品或云托管知识库。
- 用 OKF 清单替代模块命名空间 / 导入语义([module-namespace.md](module-namespace.md))。
- 强制用户提交 `.marqdo/` 进 git。
- 语义相似检索 / 跨仓技能市场(可后续在概念图上扩展)。
- 照搬 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 分管工程目录与自我成长。**
+5 -3
View File
@@ -9,15 +9,17 @@
**并发**执行单元。`spawn` 四选一:
| 参数 | 执行方式 | `join` 返回值 |
|------|----------|---------------|
| `path=` | `marqdo run <file>` 子进程 | 退出码 `Int` |
| 参数 | 执行方式 | `join` / `wait` 返回值 |
|------|----------|------------------------|
| `path=` | `marqdo run <file> --emit-result <tmp>` 子进程 | map `{ code: Int, value: Value\|null }`(`# main` 返回值;与 `quiet` 无关) |
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
`quiet=` / `静默=`(默认 `True`):仅影响 **文件** 子任务的 **TTY**。默认接到 null(父终端不被子 `print` 污染);`False` 时继承父进程 stdout/stderr。**答案载荷走 `# main` 的返回值**(经 `--emit-result` 旁路),不依赖 print。外联子任务仍经管道收集 stdout 供 `join` 返回,不受此参数影响。
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
+1 -1
View File
@@ -192,7 +192,7 @@ OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.md))。
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳;**实现规范见 [okf.md](../design/okf.md)**,命令见 [catalog-cli.md](../design/catalog-cli.md))。
3. **正文中的依赖声明语法** — import / 链接如何写出,供工具提取进生成清单。
4. **Agent 友好但不 Agent 绑定** — 源格式对 LLM 可写,语义对确定性工具可检。
5. **可渲染结果的 attestation(后期)** — 文档内求值结果的可验证性。
+527 -5
View File
@@ -4,6 +4,8 @@ description: Document-driven agent — step / plan; tools via lib/subtask; runti
> ext/ai/llm.mq.md
> lib/json.mq.md
> lib/sys.mq.md
> lib/fs.mq.md
> lib/time.mq.md
> lib/writeback.mq.md
> lib/subtask.mq.md
> lib/plugin.mq.md
@@ -91,6 +93,255 @@ Allowlist check, then invoke the runbook `##` via `lib/subtask` (`spawn fn=` →
*`msg` = Tool not allowed: *
**`msg` + `name`**
## render_workbook_skeleton
+ `goal`
+ `skeleton`=single
Build a runnable workbook. `skeleton=single` (default): one worker `step`. `skeleton=dual`: research then write agents. Solidify notes remind the parent to replace proven `step` calls with ordinary `##` code.
*`q` = > json.quote text=`goal` *
*`esc` = > json.parse text={"h":"---\ntitle: agent workbook\n> ext/ai/llm.mq.md\n> ext/ai/agent.mq.md\n> lib/json.mq.md\n> lib/sys.mq.md\n> lib/writeback.mq.md\n> lib/subtask.mq.md\n---\n\n# Goal\n\nParent goal is embedded as JSON in # main.\n\n## Solidify\n\nWhen a step is proven, replace worker.step with ordinary code that returns the answer via **…** (not print). Quiet file subtasks discard stdout; the parent reads wait.value.\n\n# main\n\n> llm.load_env\n\n","s1":"\u002a\u0060model\u0060 = > llm.llm \u002a\n","s2":"\u002a\u0060tools\u0060 = > json.parse text=[] \u002a\n","s3":"\u002a\u0060worker\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You are a workbook worker. Finish the task; do not invent tools. Prefer a direct answer. \u002a\n","s4":"\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","s5":"} \u002a\n","s6":"\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task \u002a\n","s7":"\u002a\u0060out\u0060 = > \u0060worker\u0060.step task=\u0060task\u0060 \u002a\n","s7b":"\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result \u002a\n","s8":"\u002a\u002a\u0060text\u0060\u002a\u002a\n","d3":"\u002a\u0060research\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You gather facts for the goal. Be concise. Do not invent tools. \u002a\n","d3b":"\u002a\u0060writer\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You write the final answer from research notes. Do not invent tools. \u002a\n","d4":"\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","d5":"} \u002a\n","d6":"\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task \u002a\n","d7":"\u002a\u0060notes\u0060 = > \u0060research\u0060.step task=\u0060task\u0060 \u002a\n","d8":"\u002a\u0060ns\u0060 = > json.stringify value=\u0060notes\u0060 \u002a\n","d9":"\u002a\u0060wt\u0060 = Write the final answer. Research notes: \u002a\n","d10":"\u002a\u0060wt\u0060 = \u0060wt\u0060 + \u0060ns\u0060 \u002a\n","d11":"\u002a\u0060out\u0060 = > \u0060writer\u0060.step task=\u0060wt\u0060 \u002a\n","d11b":"\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result \u002a\n","d12":"\u002a\u002a\u0060text\u0060\u002a\u002a\n"} *
*`h` = > json.get value=`esc` key=h *
*`s1` = > json.get value=`esc` key=s1 *
*`s2` = > json.get value=`esc` key=s2 *
1. `skeleton` == dual
*`s3` = > json.get value=`esc` key=d3 *
*`s3b` = > json.get value=`esc` key=d3b *
*`s4` = > json.get value=`esc` key=d4 *
*`s5` = > json.get value=`esc` key=d5 *
*`s6` = > json.get value=`esc` key=d6 *
*`s7` = > json.get value=`esc` key=d7 *
*`s8` = > json.get value=`esc` key=d8 *
*`s9` = > json.get value=`esc` key=d9 *
*`s10` = > json.get value=`esc` key=d10 *
*`s11` = > json.get value=`esc` key=d11 *
*`s11b` = > json.get value=`esc` key=d11b *
*`s12` = > json.get value=`esc` key=d12 *
**`h` + `s1` + `s2` + `s3` + `s3b` + `s4` + `q` + `s5` + `s6` + `s7` + `s8` + `s9` + `s10` + `s11` + `s11b` + `s12`**
2. *
*`s3` = > json.get value=`esc` key=s3 *
*`s4` = > json.get value=`esc` key=s4 *
*`s5` = > json.get value=`esc` key=s5 *
*`s6` = > json.get value=`esc` key=s6 *
*`s7` = > json.get value=`esc` key=s7 *
*`s7b` = > json.get value=`esc` key=s7b *
*`s8` = > json.get value=`esc` key=s8 *
**`h` + `s1` + `s2` + `s3` + `s4` + `q` + `s5` + `s6` + `s7` + `s7b` + `s8`**
---
## inspect_workbook
+ `path`
+ `exit_code`=None
+ `value`=None
Structured observation for the parent developer-agent: source, named writeback slots, exit code, and optional child return value.
*`source` = > fs.read_text path=`path` *
*`slots` = > writeback.scan_path path=`path` *
*`obs` = > json.parse text={"path":""} *
*`obs` = > json.set map=`obs` key=path value=`path` *
*`obs` = > json.set map=`obs` key=source value=`source` *
*`obs` = > json.set map=`obs` key=slots value=`slots` *
*`obs` = > json.set map=`obs` key=exit_code value=`exit_code` *
1. `value`
*`obs` = > json.set map=`obs` key=value value=`value` *
2. *
*`_` = 1*
*`last_ok` = None*
*`last_error` = None*
- [`slot`](`slots`)
*`k` = > json.get value=`slot` key=key *
*`body` = > json.get value=`slot` key=body *
1. `k` == ok
*`last_ok` = `body`*
2. `k` == error
*`last_error` = `body`*
3. *
*`_` = 1*
1. `last_ok`
*`obs` = > json.set map=`obs` key=last_ok value=`last_ok` *
2. *
*`_` = 1*
1. `last_error`
*`obs` = > json.set map=`obs` key=last_error value=`last_error` *
2. *
*`_` = 1*
**`obs`**
---
## await_workbook
+ `path`
Spawn a workbook file (quiet by default), wait for `{code,value}`, and inspect. Parent consumes `value` — not child stdout.
*`id` = > subtask.spawn path=`path` *
*`waited` = > subtask.wait id=`id` *
*`code` = > json.get value=`waited` key=code *
*`value` = > json.get value=`waited` key=value *
*`obs` = > inspect_workbook path=`path` exit_code=`code` value=`value` *
*`out` = > json.parse text={"code":0} *
*`out` = > json.set map=`out` key=code value=`code` *
*`out` = > json.set map=`out` key=value value=`value` *
*`out` = > json.set map=`out` key=observation value=`obs` *
**`out`**
---
## extract_plan_decision
+ `reply`
Parse `DECISION: DONE` / `DECISION: CONTINUE` (Chinese: `决定:完成` / `决定:继续`).
*`esc` = > json.parse text={"nl":"\n","fw":":"} *
*`nl` = > json.get value=`esc` key=nl *
*`fw` = > json.get value=`esc` key=fw *
*`text` = > trim value=`reply` *
*`lines` = > split value=`text` sep=`nl` *
*`found` = None*
- [`line`](`lines`)
*`t` = > trim value=`line` *
*`parts` = > split value=`t` sep=: *
*`n` = > len value=`parts` *
1. `n` > 1
*`head` = > at value=`parts` index=0 *
*`head` = > trim value=`head` *
*`rest` = > at value=`parts` index=1 *
*`rest` = > trim value=`rest` *
1. `head` == DECISION
*`found` = `rest`*
2. `head` == 决定
*`found` = `rest`*
3. *
*`_` = 1*
2. *
*`parts` = > split value=`t` sep=`fw` *
*`n` = > len value=`parts` *
1. `n` > 1
*`head` = > at value=`parts` index=0 *
*`head` = > trim value=`head` *
*`rest` = > at value=`parts` index=1 *
*`rest` = > trim value=`rest` *
1. `head` == 决定
*`found` = `rest`*
2. `head` == DECISION
*`found` = `rest`*
3. *
*`_` = 1*
2. *
*`_` = 1*
1. `found` == DONE
**DONE**
2. `found` == CONTINUE
**CONTINUE**
3. `found` == 完成
**DONE**
4. `found` == 继续
**CONTINUE**
5. *
**`found`**
---
## extract_plan_summary
+ `reply`
First `SUMMARY:` / `汇总:` / `汇总:` line body, else trimmed reply.
*`esc` = > json.parse text={"nl":"\n","fw":":"} *
*`nl` = > json.get value=`esc` key=nl *
*`fw` = > json.get value=`esc` key=fw *
*`text` = > trim value=`reply` *
*`lines` = > split value=`text` sep=`nl` *
*`found` = None*
- [`line`](`lines`)
*`t` = > trim value=`line` *
*`parts` = > split value=`t` sep=: *
*`n` = > len value=`parts` *
1. `n` > 1
*`head` = > at value=`parts` index=0 *
*`head` = > trim value=`head` *
*`rest` = > at value=`parts` index=1 *
*`rest` = > trim value=`rest` *
1. `head` == SUMMARY
*`found` = `rest`*
2. `head` == 汇总
*`found` = `rest`*
3. *
*`_` = 1*
2. *
*`parts` = > split value=`t` sep=`fw` *
*`n` = > len value=`parts` *
1. `n` > 1
*`head` = > at value=`parts` index=0 *
*`head` = > trim value=`head` *
*`rest` = > at value=`parts` index=1 *
*`rest` = > trim value=`rest` *
1. `head` == 汇总
*`found` = `rest`*
2. `head` == SUMMARY
*`found` = `rest`*
3. *
*`_` = 1*
2. *
*`_` = 1*
1. `found`
**`found`**
2. *
**`text`**
---
## build_plan_context
+ `agent`
+ `goal`
+ `observation`
+ `explore_attempt`=None
+ `explore_n`=None
Parent developer-agent prompt: observe → decide DONE or CONTINUE with exact FIND/REPLACE patches (never rewrite the whole workbook).
*`standing` = > json.get value=`agent` key=standing *
1. `standing`
*`up` = `standing`*
2. *
*`up` = None*
*`skill` = > agent_marqdo_skill *
*`obs_s` = > json.stringify value=`observation` *
*`goal_s` = > json.stringify value=`goal` *
*`esc` = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- goal ---\n","c":"\n\n--- workbook observation ---\n","d":"\n\n--- marqdo skill ---\n","e":"\n\n--- how to act ---\nYou are a Marqdo agent-development master.\nPriority order:\n1) Code first: if the goal is a fixed answer, solidify to a **return** (e.g. **pong**) or ordinary ## — no further LLM worker.step. Do not rely on > print; file subtasks are quiet and the parent consumes wait.value.\n2) If exit_code is 0 AND the workbook source still contains worker.step (or .单步), you MUST CONTINUE with a FIND/REPLACE that solidifies to a returned answer. Never DONE while .step remains.\n3) If exit_code is 0 AND already solidified (no worker.step) with a clear main return, DECISION: DONE with a short SUMMARY.\n4) If exploring an alternate path, try a meaningfully DIFFERENT structure than prior attempts (e.g. dual agents, narrower standing, or pure code). Do not merely re-run the same step.\n5) Prefer multiple narrow agents over one giant standing when roles differ.\nNever rewrite the whole .mq.md file.\nReply with EXACTLY one protocol:\nDECISION: DONE\nSUMMARY: <one line>\nOR\nDECISION: CONTINUE\nPATCH:\n<<<\nFIND\n<exact old snippet>\n===\nREPLACE\n<new snippet>\n>>>\n(You may repeat <<< blocks.)\n","f":"\n\n--- explore attempt ---\n"} *
*`a` = > json.get value=`esc` key=a *
*`b` = > json.get value=`esc` key=b *
*`c` = > json.get value=`esc` key=c *
*`d` = > json.get value=`esc` key=d *
*`e` = > json.get value=`esc` key=e *
*`f` = > json.get value=`esc` key=f *
*`p` = You develop and revise Marqdo workbooks with surgical patches. *
*`p` = `p` + `a` + `up` + `b` + `goal_s` + `c` + `obs_s` + `d` + `skill` + `e` *
1. `explore_attempt`
*`p` = `p` + `f` *
*`p` = `p` + Attempt *
*`p` = `p` + `explore_attempt` *
*`p` = `p` + of *
*`p` = `p` + `explore_n` *
*`p` = `p` + . Try a different path; prefer code when the answer is fixed. *
2. *
*`_` = 1*
**`p`**
---
# agent
+ `model`
+ `tools`
@@ -192,10 +443,281 @@ One atomic turn: context → LLM → optional tool via subtask. Returns a **map*
## plan
+ `goal`
+ `workbook_dir`
+ `workbook_dir`=None
+ `workbook`=None
+ `max_rounds`=4
+ `confirm`=False
+ `writeback`=True
+ `skeleton`=single
+ `reuse`=True
+ `optimize`=False
+ `force`=False
+ `promote`=True
+ `kb_dir`=.marqdo/agent-kb
+ `improve_every`=3
+ `explore_n`=3
Multi-step workbook (D2) — not implemented yet.
Multi-step with OKF agent-kb. Default workbook is `kb_dir/resources/<slug>.mq.md`. While task file count `< explore_n` and skill is not llm_free, force a new explore variant under `kb_dir/explore/<slug>/`. Code-first: llm_free hits skip parent LLM. File children return via `# main`; `plan` exposes that as `result`.
*`_` = `workbook_dir`*
*`msg` = plan (multi-step workbook) is not implemented yet; goal was: *
**`msg` + `goal`**
*`tools` = > json.get value=`self` key=tools *
*`cache` = miss*
*`path` = None*
*`improve` = None*
*`explore` = None*
*`explore_attempt` = None*
*`skel_kind` = `skeleton`*
*`tf` = > agent_kb_task_files kb_dir=`kb_dir` goal=`goal` tools=`tools` *
*`nfiles` = > json.get value=`tf` key=count *
1. `force`
*`_` = 1*
2. `optimize`
*`_` = 1*
3. `reuse`
*`hit` = > agent_kb_lookup kb_dir=`kb_dir` goal=`goal` tools=`tools` *
1. `hit`
*`lf` = > json.get value=`hit` key=llm_free *
1. `lf`
*`path` = > json.get value=`hit` key=resource *
*`aw` = > await_workbook path=`path` *
*`code` = > json.get value=`aw` key=code *
*`child_val` = > json.get value=`aw` key=value *
*`last_obs` = > json.get value=`aw` key=observation *
1. `code` == 0
> agent_kb_record_hit kb_dir=`kb_dir` goal=`goal` tools=`tools` improve_every=`improve_every`
*`cache` = hit*
*`out` = > json.parse text={"status":"ok"} *
*`out` = > json.set map=`out` key=status value=ok *
*`out` = > json.set map=`out` key=goal value=`goal` *
*`out` = > json.set map=`out` key=workbook value=`path` *
*`out` = > json.set map=`out` key=rounds value=1 *
*`out` = > json.set map=`out` key=cache value=hit *
*`sk` = > json.get value=`hit` key=skill *
*`out` = > json.set map=`out` key=skill value=`sk` *
*`st` = > json.get value=`hit` key=status *
*`out` = > json.set map=`out` key=skill_status value=`st` *
*`sum` = OKF llm_free skill hit; spawned resource *
*`out` = > json.set map=`out` key=summary value=`sum` *
*`out` = > json.set map=`out` key=observation value=`last_obs` *
*`out` = > json.set map=`out` key=result value=`child_val` *
1. `writeback`
*`body` = > json.stringify value=`out` *
> writeback.record value=`body` key=ok
2. *
*`_` = 1*
**`out`**
2. *
*`path` = None*
2. `nfiles` < `explore_n`
*`explore` = 1*
*`cache` = explore*
*`path` = None*
*`explore_attempt` = `nfiles` + 1*
1. `explore_attempt` == 2
*`skel_kind` = dual*
2. *
*`skel_kind` = `skeleton`*
3. *
*`path` = > json.get value=`hit` key=resource *
*`aw` = > await_workbook path=`path` *
*`code` = > json.get value=`aw` key=code *
*`child_val` = > json.get value=`aw` key=value *
*`last_obs` = > json.get value=`aw` key=observation *
1. `code` == 0
*`rec` = > agent_kb_record_hit kb_dir=`kb_dir` goal=`goal` tools=`tools` improve_every=`improve_every` *
*`due` = > json.get value=`rec` key=improve_due *
1. `due`
*`improve` = 1*
*`cache` = improve*
2. *
*`cache` = hit*
*`out` = > json.parse text={"status":"ok"} *
*`out` = > json.set map=`out` key=status value=ok *
*`out` = > json.set map=`out` key=goal value=`goal` *
*`out` = > json.set map=`out` key=workbook value=`path` *
*`out` = > json.set map=`out` key=rounds value=1 *
*`out` = > json.set map=`out` key=cache value=hit *
*`sk` = > json.get value=`hit` key=skill *
*`out` = > json.set map=`out` key=skill value=`sk` *
*`st` = > json.get value=`hit` key=status *
*`out` = > json.set map=`out` key=skill_status value=`st` *
*`sum` = OKF skill hit; spawned resource *
*`out` = > json.set map=`out` key=summary value=`sum` *
*`out` = > json.set map=`out` key=observation value=`last_obs` *
*`out` = > json.set map=`out` key=result value=`child_val` *
1. `writeback`
*`body` = > json.stringify value=`out` *
> writeback.record value=`body` key=ok
2. *
*`_` = 1*
**`out`**
2. *
*`path` = None*
2. *
1. `nfiles` < `explore_n`
*`explore` = 1*
*`cache` = explore*
*`explore_attempt` = `nfiles` + 1*
1. `explore_attempt` == 2
*`skel_kind` = dual*
2. *
*`skel_kind` = `skeleton`*
2. *
*`_` = 1*
4. *
1. `nfiles` < `explore_n`
*`explore` = 1*
*`cache` = explore*
*`explore_attempt` = `nfiles` + 1*
2. *
*`_` = 1*
*`skel` = > render_workbook_skeleton goal=`goal` skeleton=`skel_kind` *
1. `workbook`
*`path` = `workbook`*
*`ex` = > fs.exists path=`path` *
1. `ex`
*`_` = 1*
2. *
> fs.write_text path=`path` text=`skel`
2. *
1. `path`
*`_` = 1*
2. *
*`slug` = > agent_goal_slug goal=`goal` *
1. `workbook_dir`
> fs.make_dir path=`workbook_dir`
*`ts` = > time.now_ms *
*`parts` = > json.parse text={"a":"/workbook-","b":"-","c":".mq.md"} *
*`a` = > json.get value=`parts` key=a *
*`b` = > json.get value=`parts` key=b *
*`c` = > json.get value=`parts` key=c *
*`path` = `workbook_dir` + `a` + `slug` + `b` + `ts` + `c` *
2. `explore`
*`parts` = > json.parse text={"a":"/explore/","b":"/","c":".mq.md"} *
*`a` = > json.get value=`parts` key=a *
*`b` = > json.get value=`parts` key=b *
*`c` = > json.get value=`parts` key=c *
*`path` = `kb_dir` + `a` + `slug` + `b` + `explore_attempt` + `c` *
3. *
*`parts` = > json.parse text={"a":"/resources/","b":".mq.md"} *
*`a` = > json.get value=`parts` key=a *
*`b` = > json.get value=`parts` key=b *
*`path` = `kb_dir` + `a` + `slug` + `b` *
> fs.write_text path=`path` text=`skel`
1. `confirm`
*`out` = > json.parse text={"status":"pending"} *
*`out` = > json.set map=`out` key=goal value=`goal` *
*`out` = > json.set map=`out` key=workbook value=`path` *
*`out` = > json.set map=`out` key=summary value=workbook created; confirm to run *
*`out` = > json.set map=`out` key=cache value=bypass *
1. `writeback`
*`body` = > json.stringify value=`out` *
> writeback.record value=`body` key=ok
2. *
*`_` = 1*
**`out`**
2. *
*`_` = 1*
*`model` = > json.get value=`self` key=model *
*`round` = 0*
*`last_obs` = None*
*`last_reply` = None*
*`child_val` = None*
*`done` = None*
*`summary` = None*
*`status` = error*
*`err` = max_rounds exhausted *
1. `improve`
*`left` = 1*
2. *
*`left` = `max_rounds`*
- `left` > 0
1. `done`
*`left` = 0*
2. *
*`round` = `round` + 1*
*`aw` = > await_workbook path=`path` *
*`code` = > json.get value=`aw` key=code *
*`child_val` = > json.get value=`aw` key=value *
*`last_obs` = > json.get value=`aw` key=observation *
*`ctx` = > build_plan_context agent=`self` goal=`goal` observation=`last_obs` explore_attempt=`explore_attempt` explore_n=`explore_n` *
*`last_reply` = > `model`.complete prompt=`ctx` *
*`last_reply` = > trim value=`last_reply` *
*`dec` = > extract_plan_decision reply=`last_reply` *
1. `dec` == DONE
> agent_workbook_solidify path=`path` observation=`last_obs`
*`done` = 1*
*`status` = ok*
*`summary` = > extract_plan_summary reply=`last_reply` *
*`err` = None*
*`left` = 0*
2. `dec` == CONTINUE
*`n` = > fs.apply_patch_blocks path=`path` text=`last_reply` *
1. `n`
*`left` = `left` - 1*
2. *
*`done` = 1*
*`status` = error*
*`err` = no patches applied *
*`summary` = > extract_plan_summary reply=`last_reply` *
*`left` = 0*
3. *
*`done` = 1*
*`status` = error*
*`err` = unrecognized plan decision *
*`summary` = `last_reply`*
*`left` = 0*
1. `status` == ok
1. `promote`
*`prom` = > agent_kb_promote kb_dir=`kb_dir` goal=`goal` workbook=`path` tools=`tools` *
*`cache` = refreshed*
2. *
*`cache` = miss*
2. *
*`_` = 1*
*`out` = > json.parse text={"status":"ok"} *
*`out` = > json.set map=`out` key=status value=`status` *
*`out` = > json.set map=`out` key=goal value=`goal` *
*`out` = > json.set map=`out` key=workbook value=`path` *
*`out` = > json.set map=`out` key=rounds value=`round` *
*`out` = > json.set map=`out` key=cache value=`cache` *
1. `summary`
*`out` = > json.set map=`out` key=summary value=`summary` *
2. *
*`_` = 1*
1. `err`
*`out` = > json.set map=`out` key=error value=`err` *
2. *
*`_` = 1*
1. `last_obs`
*`out` = > json.set map=`out` key=observation value=`last_obs` *
2. *
*`_` = 1*
1. `child_val`
*`out` = > json.set map=`out` key=result value=`child_val` *
2. `summary`
*`out` = > json.set map=`out` key=result value=`summary` *
3. *
*`_` = 1*
1. `writeback`
*`body` = > json.stringify value=`out` *
1. `status` == ok
> writeback.record value=`body` key=ok
2. *
> writeback.record value=`body` key=error
2. *
*`_` = 1*
**`out`**
+20 -5
View File
@@ -2,6 +2,7 @@
title: ext/ai/智能体
description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务;运行时经 ABI v2 agent 插件。
> ext/ai/大模型.mq.md
> ext/ai/agent.mq.md
> lib/json.mq.md
> lib/系统.mq.md
> lib/自写回.mq.md
@@ -192,10 +193,24 @@ description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务
## 多步
+ `目标`
+ `工作簿目录`
+ `工作簿目录`=None
+ `工作簿`=None
+ `最大轮次`=4
+ `确认分解`=False
+ `写回`=True
+ `骨架`=single
+ `复用`=True
+ `优化`=False
+ `强制`=False
+ `晋升`=True
+ `知识库目录`=.marqdo/agent-kb
+ `改进周期`=3
+ `探索次数`=3
多步工作簿(D2)— 尚未实现。
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。
*`_` = `工作簿目录`*
*`msg` = plan (multi-step workbook) is not implemented yet; goal was: *
**`msg` + `目标`**
*`model` = > json.get value=`self` key=model *
*`tools` = > json.get value=`self` key=tools *
*`standing` = > json.get value=`self` key=standing *
*`en` = > agent.agent model=`model` tools=`tools` standing=`standing` *
**> `en`.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数`**
+17
View File
@@ -39,3 +39,20 @@ description: English filesystem wrappers
+ `path`
**> host_remove path=`path`**
## text_patch
+ `path`
+ `find`
+ `replace`
Exact FIND→REPLACE once in a UTF-8 text file. `find` must match exactly once.
**> host_text_patch path=`path` find=`find` replace=`replace`**
## apply_patch_blocks
+ `path`
+ `text`
Apply plan-style `<<<` / FIND / === / REPLACE / `>>>` blocks from `text` to `path`.
**> host_apply_patch_blocks path=`path` text=`text`**
+5 -1
View File
@@ -11,8 +11,12 @@ description: Concurrent subtasks — file, function, or foreign code
+ `lang`=None
+ `source`=None
+ `stdin`=None
+ `quiet`=True
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin`**
File children are silent by default; set `quiet=False` to inherit parent stdout/stderr.
File `wait` returns `{code, value}` where `value` is the child's `# main` return (not stdout).
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin` quiet=`quiet`**
## poll
+ `id`
+7
View File
@@ -45,3 +45,10 @@ Create a named slot with `placeholder` if missing. Never overwrites an existing
List all output blocks in the entry file (includes `key` when named).
**> host_writeback_list**
## scan_path
+ `path`
List `<!-- marqdo-out … -->` slots in any file (workbook inspection).
**> host_writeback_scan_path path=`path`**
+5 -1
View File
@@ -11,8 +11,12 @@ description: 并发子任务 — 文件、函数或外联代码
+ `语言`=None
+ `源码`=None
+ `输入`=None
+ `静默`=True
**> host_subtask_spawn path=`路径` fn=`函数` args=`参数` code=`代码` lang=`语言` source=`源码` stdin=`输入`**
文件子任务默认静默;`静默=假` 时继承父进程终端输出。
文件 `等待` 返回 `{code, value}`,`value` 为子 `# main` 返回值(不是 stdout)。
**> host_subtask_spawn path=`路径` fn=`函数` args=`参数` code=`代码` lang=`语言` source=`源码` stdin=`输入` quiet=`静默`**
## 探测
+ `id`
+17
View File
@@ -39,3 +39,20 @@ description: 中文文件系统包装
+ `路径`
**> host_remove path=`路径`**
## 文本补丁
+ `路径`
+ `查找`
+ `替换`
对 UTF-8 文本文件做精确 FIND→REPLACE(`查找` 必须唯一匹配一次)。
**> host_text_patch path=`路径` find=`查找` replace=`替换`**
## 应用补丁块
+ `路径`
+ `文本`
解析规划回复中的 `<<<` / FIND / === / REPLACE / `>>>` 块并应用到 `路径`。
**> host_apply_patch_blocks path=`路径` text=`文本`**
+7
View File
@@ -43,3 +43,10 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回)
## 列出
**> host_writeback_list**
## 扫描路径
+ `路径`
扫描任意文件中的 `<!-- marqdo-out … -->` 槽(工作簿观察)。
**> host_writeback_scan_path path=`路径`**
+22
View File
@@ -0,0 +1,22 @@
---
title: ext/agent plan live (DeepSeek)
description: Full plan loop — spawn workbook, inspect; simple pong goal.
> ext/ai/llm.mq.md
> ext/ai/agent.mq.md
> lib/json.mq.md
> lib/fs.mq.md
---
# main
*`goal`=> input "你想完成什么任务?"*
> llm.load_env path=.env
*`model` = > llm.llm *
*`tools` = > json.parse text=[] *
*`助手` = > agent.agent model=`model` tools=`tools` standing=You are a Marqdo agent-development master. Prefer DONE when the workbook already satisfies the goal. *
*`out` = > `助手`.plan goal=`goal` max_rounds=3 writeback=False *
> print `out`
+1
View File
@@ -12,3 +12,4 @@ crate-type = ["cdylib"]
[dependencies]
serde_json = "1"
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
+760
View File
@@ -0,0 +1,760 @@
//! OKF agent-kb helpers (plugin-side). No dependency on marqdo `src/host`.
use std::fs;
use std::path::{Path, PathBuf};
use serde_json::{json, Value};
pub fn normalize_goal(raw: &str) -> String {
let t = raw.trim();
let mut out = String::with_capacity(t.len());
let mut prev_space = false;
for c in t.chars() {
if c.is_whitespace() {
if !prev_space && !out.is_empty() {
out.push(' ');
prev_space = true;
}
} else {
out.push(c);
prev_space = false;
}
}
out
}
pub fn goal_sig_hex(material: &str) -> String {
let mut h: u64 = 5381;
for b in material.as_bytes() {
h = h.wrapping_mul(33).wrapping_add(u64::from(*b));
}
format!("{h:016x}")[..12].to_string()
}
pub fn goal_slug_str(raw: &str) -> String {
let n = normalize_goal(raw);
let mut out = String::new();
for c in n.chars() {
if c.is_ascii_alphanumeric() {
out.push(c.to_ascii_lowercase());
} else if !c.is_ascii()
&& !c.is_whitespace()
&& !matches!(c, '/' | '\\' | ':' | '*' | '?' | '"' | '<' | '>' | '|')
{
if c.is_alphanumeric() {
out.push(c);
} else if !out.is_empty() && !out.ends_with('-') {
out.push('-');
}
} else if !out.is_empty() && !out.ends_with('-') {
out.push('-');
}
}
while out.ends_with('-') {
out.pop();
}
let mut truncated = String::new();
for c in out.chars() {
if truncated.chars().count() >= 48 {
break;
}
truncated.push(c);
}
while truncated.ends_with('-') {
truncated.pop();
}
if truncated.is_empty() {
"task".into()
} else {
truncated
}
}
fn tools_fingerprint(tools: Option<&Value>) -> String {
match tools {
None | Some(Value::Null) => String::new(),
Some(Value::Array(items)) => {
let mut names: Vec<String> = items
.iter()
.filter_map(|v| match v {
Value::String(s) => Some(s.trim().to_string()),
Value::Object(entries) => entries
.get("工具")
.or_else(|| entries.get("name"))
.or_else(|| entries.get("tool"))
.and_then(|v| v.as_str())
.map(|s| s.trim().to_string()),
_ => None,
})
.filter(|s| !s.is_empty())
.collect();
names.sort();
names.join("\n")
}
Some(Value::String(s)) => {
let t = s.trim();
if t.is_empty() {
String::new()
} else {
t.to_string()
}
}
_ => String::new(),
}
}
fn material_for(goal: &str, tools: Option<&Value>) -> String {
let mut material = normalize_goal(goal);
let fp = tools_fingerprint(tools);
if !fp.is_empty() {
material.push('\n');
material.push_str(&fp);
}
material
}
fn resolve_path(rel: &str) -> PathBuf {
let p = PathBuf::from(rel);
if p.is_absolute() {
return p;
}
// Prefer host cwd (entry file directory) via host_query when available.
let base = (|| {
let q = crate::host_query_json("cwd")?;
q.as_str()
.map(PathBuf::from)
.ok_or_else(|| "cwd not text".to_string())
})()
.or_else(|_| std::env::current_dir().map_err(|e| e.to_string()))
.unwrap_or_else(|_| PathBuf::from("."));
base.join(p)
}
fn yaml_escape(s: &str) -> String {
if s.is_empty()
|| s.contains(':')
|| s.contains('#')
|| s.contains('"')
|| s.contains('\'')
|| s.contains('\n')
|| s.starts_with(' ')
{
format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
} else {
s.to_string()
}
}
fn extract_fm_field(source: &str, key: &str) -> Option<String> {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return None;
}
let prefix = format!("{key}:");
for line in lines.iter().skip(1) {
let t = line.trim();
if t == "---" {
break;
}
if let Some(rest) = t.strip_prefix(&prefix) {
return Some(rest.trim().trim_matches('"').to_string());
}
}
None
}
fn set_fm_field(source: &str, key: &str, value: &str) -> String {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return source.to_string();
}
let prefix = format!("{key}:");
let mut out = Vec::new();
let mut replaced = false;
let mut in_fm = true;
for (i, line) in lines.iter().enumerate() {
if i == 0 {
out.push((*line).to_string());
continue;
}
if in_fm && line.trim() == "---" {
if !replaced {
out.push(format!("{key}: {value}"));
}
in_fm = false;
out.push((*line).to_string());
continue;
}
if in_fm && line.trim().starts_with(&prefix) {
out.push(format!("{key}: {value}"));
replaced = true;
} else {
out.push((*line).to_string());
}
}
out.join("\n") + if source.ends_with('\n') { "\n" } else { "" }
}
fn kb_rel(kb_dir: &str, parts: &str) -> String {
format!("{}/{}", kb_dir.trim_end_matches('/'), parts)
}
fn resolve_skill_paths(
root: &Path,
sig: &str,
slug_hint: &str,
) -> Option<(PathBuf, PathBuf, PathBuf, String)> {
let tasks_dir = root.join("concepts/tasks");
let skills_dir = root.join("concepts/skills");
let res_dir = root.join("resources");
let sig4 = if sig.len() >= 4 { &sig[..4] } else { sig };
for slug in [slug_hint.to_string(), format!("{slug_hint}-{sig4}")] {
let task = tasks_dir.join(format!("{slug}.md"));
if task.is_file() {
if let Ok(src) = fs::read_to_string(&task) {
let fm_sig = extract_fm_field(&src, "sig");
if fm_sig.as_deref() == Some(sig) || fm_sig.is_none() {
let skill = skills_dir.join(format!("{slug}.md"));
let res = res_dir.join(format!("{slug}.mq.md"));
if skill.is_file() && res.is_file() {
return Some((task, skill, res, slug));
}
}
}
}
}
if tasks_dir.is_dir() {
if let Ok(rd) = fs::read_dir(&tasks_dir) {
for ent in rd.flatten() {
let p = ent.path();
if p.extension().and_then(|e| e.to_str()) != Some("md") {
continue;
}
let Ok(src) = fs::read_to_string(&p) else {
continue;
};
if extract_fm_field(&src, "sig").as_deref() == Some(sig) {
let stem = p.file_stem()?.to_string_lossy().into_owned();
let skill = skills_dir.join(format!("{stem}.md"));
let res = res_dir.join(format!("{stem}.mq.md"));
if skill.is_file() && res.is_file() {
return Some((p, skill, res, stem));
}
}
}
}
}
let task = tasks_dir.join(format!("{sig}.md"));
let skill = skills_dir.join(format!("{sig}.md"));
let res = res_dir.join(format!("{sig}.mq.md"));
if task.is_file() && skill.is_file() && res.is_file() {
return Some((task, skill, res, sig.to_string()));
}
None
}
fn unique_slug(root: &Path, base: &str, sig: &str) -> String {
let tasks = root.join("concepts/tasks");
let candidate = tasks.join(format!("{base}.md"));
if !candidate.is_file() {
return base.to_string();
}
if let Ok(src) = fs::read_to_string(&candidate) {
if extract_fm_field(&src, "sig").as_deref() == Some(sig) {
return base.to_string();
}
}
let sig4 = if sig.len() >= 4 { &sig[..4] } else { sig };
format!("{base}-{sig4}")
}
fn llm_free_score(src: &str) -> (bool, i64) {
let lower = src.to_ascii_lowercase();
let has_step = src.contains(".step") || src.contains(".单步") || src.contains("agent.step");
let has_llm = lower.contains("llm.llm")
|| lower.contains("llm.complete")
|| src.contains("大模型")
|| src.contains(".complete");
let free = !has_step && !has_llm;
let len = src.len() as i64;
let quality = if free {
1_000_000 - len.min(999_999)
} else {
100_000 - len.min(99_999)
};
(free, quality)
}
fn write_task_concept(
path: &Path,
sig: &str,
slug: &str,
goal: &str,
now: &str,
) -> Result<(), String> {
if let Some(p) = path.parent() {
fs::create_dir_all(p).map_err(|e| format!("mkdir: {e}"))?;
}
let title: String = goal.chars().take(48).collect();
let body = format!(
r#"---
type: Marqdo Task
title: {title}
description: {goal_e}
sig: {sig}
status: stable
tags: [agent-task]
skill: ../skills/{slug}.md
generated:
by: marqdo-agent/plan
at: {now}
verified:
by: marqdo-agent/spawn
at: {now}
---
# Task
See [skill](../skills/{slug}.md).
"#,
title = yaml_escape(&title),
goal_e = yaml_escape(goal),
sig = sig,
slug = slug,
now = now,
);
fs::write(path, body).map_err(|e| format!("write task: {e}"))
}
fn write_skill_concept(
path: &Path,
sig: &str,
slug: &str,
goal: &str,
status: &str,
llm_free: bool,
quality: i64,
hits: i64,
now: &str,
) -> Result<(), String> {
if let Some(p) = path.parent() {
fs::create_dir_all(p).map_err(|e| format!("mkdir: {e}"))?;
}
let title: String = goal.chars().take(48).collect();
let body = format!(
r#"---
type: Marqdo Agent Skill
title: {title}
sig: {sig}
resource: ../../resources/{slug}.mq.md
status: {status}
llm_free: {llm_free}
quality: {quality}
hits: {hits}
generated:
by: marqdo-agent/plan
at: {now}
verified:
by: marqdo-agent/spawn
at: {now}
---
# Skill
Prefer spawning `resource` over re-planning.
"#,
title = yaml_escape(&title),
sig = sig,
slug = slug,
status = status,
llm_free = if llm_free { "true" } else { "false" },
quality = quality,
hits = hits,
now = now,
);
fs::write(path, body).map_err(|e| format!("write skill: {e}"))
}
fn refresh_index(root: &Path, slug: &str, goal: &str) -> Result<(), String> {
let index = root.join("index.md");
let line = format!(
"- [`{slug}`](concepts/tasks/{slug}.md) — {}\n",
goal.chars().take(60).collect::<String>()
);
if index.is_file() {
let mut cur = fs::read_to_string(&index).map_err(|e| format!("read index: {e}"))?;
let marker = format!("concepts/tasks/{slug}.md");
if !cur.contains(&marker) {
if !cur.ends_with('\n') {
cur.push('\n');
}
cur.push_str(&line);
fs::write(&index, cur).map_err(|e| format!("write index: {e}"))?;
}
} else {
let body = format!(
"---\ntype: Marqdo Catalog\ntitle: agent-kb\ngenerated:\n by: marqdo-agent/plan\n---\n\n# Agent knowledge base\n\n{line}"
);
fs::write(&index, body).map_err(|e| format!("write index: {e}"))?;
}
Ok(())
}
fn now_rfc3339() -> String {
chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
args.get(key)
.and_then(|v| v.as_str())
.ok_or_else(|| format!("missing text `{key}`"))
}
fn opt_tools(args: &Value) -> Option<&Value> {
args.get("tools").filter(|t| !t.is_null())
}
pub fn goal_sig(args: &Value) -> Result<Value, String> {
let goal = arg_text(args, "goal")?;
Ok(Value::String(goal_sig_hex(&material_for(
goal,
opt_tools(args),
))))
}
pub fn goal_slug(args: &Value) -> Result<Value, String> {
let goal = arg_text(args, "goal")?;
Ok(Value::String(goal_slug_str(goal)))
}
pub fn kb_lookup(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let goal = arg_text(args, "goal")?;
let sig = goal_sig_hex(&material_for(goal, opt_tools(args)));
let slug_hint = goal_slug_str(goal);
let root = resolve_path(kb);
let Some((_task, skill_path, _res, slug)) = resolve_skill_paths(&root, &sig, &slug_hint) else {
return Ok(Value::Null);
};
let skill_src =
fs::read_to_string(&skill_path).map_err(|e| format!("kb_lookup read skill: {e}"))?;
let mut status = extract_fm_field(&skill_src, "status").unwrap_or_else(|| "stable".into());
if status == "deprecated" || status == "draft" {
return Ok(Value::Null);
}
let mut llm_free = extract_fm_field(&skill_src, "llm_free")
.map(|s| s == "true" || s == "True")
.unwrap_or(false);
let mut quality = extract_fm_field(&skill_src, "quality")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
let hits = extract_fm_field(&skill_src, "hits")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
let res_path = root.join("resources").join(format!("{slug}.mq.md"));
if res_path.is_file() {
if let Ok(res_src) = fs::read_to_string(&res_path) {
let (res_free, res_q) = llm_free_score(&res_src);
if res_free {
llm_free = true;
status = "stable".into();
}
if res_q > quality {
quality = res_q;
}
}
}
Ok(json!({
"hit": true,
"sig": sig,
"slug": slug,
"status": status,
"llm_free": llm_free,
"quality": quality,
"hits": hits,
"resource": kb_rel(kb, &format!("resources/{slug}.mq.md")),
"task": kb_rel(kb, &format!("concepts/tasks/{slug}.md")),
"skill": kb_rel(kb, &format!("concepts/skills/{slug}.md")),
}))
}
pub fn kb_record_hit(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let goal = arg_text(args, "goal")?;
let sig = goal_sig_hex(&material_for(goal, opt_tools(args)));
let slug_hint = goal_slug_str(goal);
let root = resolve_path(kb);
let Some((_t, skill_path, _r, slug)) = resolve_skill_paths(&root, &sig, &slug_hint) else {
return Ok(Value::Null);
};
let src = fs::read_to_string(&skill_path).map_err(|e| format!("read skill: {e}"))?;
let status = extract_fm_field(&src, "status").unwrap_or_else(|| "stable".into());
let llm_free = extract_fm_field(&src, "llm_free")
.map(|s| s == "true" || s == "True")
.unwrap_or(false);
let hits = extract_fm_field(&src, "hits")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0)
+ 1;
let next = set_fm_field(&src, "hits", &hits.to_string());
fs::write(&skill_path, next).map_err(|e| format!("write skill hits: {e}"))?;
let every = match args.get("improve_every") {
None | Some(Value::Null) => 0i64,
Some(Value::Number(n)) => n.as_i64().unwrap_or(0),
Some(Value::String(s)) => s.parse().unwrap_or(0),
_ => 0,
};
let improve_due = every > 0
&& status == "candidate"
&& !llm_free
&& hits > 0
&& hits % every == 0;
Ok(json!({
"hits": hits,
"slug": slug,
"sig": sig,
"status": status,
"llm_free": llm_free,
"improve_due": improve_due,
}))
}
pub fn kb_promote(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let goal = arg_text(args, "goal")?;
let workbook = arg_text(args, "workbook")?;
let goal_n = normalize_goal(goal);
let sig = goal_sig_hex(&material_for(goal, opt_tools(args)));
let base_slug = goal_slug_str(&goal_n);
let root = resolve_path(kb);
let slug = unique_slug(&root, &base_slug, &sig);
let src_path = resolve_path(workbook);
let src = fs::read_to_string(&src_path)
.map_err(|e| format!("kb_promote read workbook: {e}"))?;
let (llm_free, quality) = llm_free_score(&src);
let status = if llm_free { "stable" } else { "candidate" };
let skill_path = root.join("concepts/skills").join(format!("{slug}.md"));
let mut prev_hits = 0i64;
if skill_path.is_file() {
let old = fs::read_to_string(&skill_path).unwrap_or_default();
prev_hits = extract_fm_field(&old, "hits")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
let old_q = extract_fm_field(&old, "quality")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
if quality < old_q {
return Ok(json!({
"promoted": false,
"reason": "quality_worse",
"sig": sig,
"slug": slug,
}));
}
}
let res_path = root.join("resources").join(format!("{slug}.mq.md"));
if let Some(p) = res_path.parent() {
fs::create_dir_all(p).map_err(|e| format!("mkdir resources: {e}"))?;
}
fs::write(&res_path, &src).map_err(|e| format!("write resource: {e}"))?;
let now = now_rfc3339();
write_task_concept(
&root.join("concepts/tasks").join(format!("{slug}.md")),
&sig,
&slug,
&goal_n,
&now,
)?;
write_skill_concept(
&skill_path,
&sig,
&slug,
&goal_n,
status,
llm_free,
quality,
prev_hits,
&now,
)?;
refresh_index(&root, &slug, &goal_n)?;
Ok(json!({
"promoted": true,
"sig": sig,
"slug": slug,
"resource": kb_rel(kb, &format!("resources/{slug}.mq.md")),
"llm_free": llm_free,
"quality": quality,
"status": status,
"hits": prev_hits,
}))
}
fn extract_result_text(observation: Option<&Value>) -> Option<String> {
let obs = observation?;
if let Some(v) = obs.get("value") {
if let Some(t) = value_as_result_text(v) {
return Some(t);
}
}
let last_ok = obs.get("last_ok")?;
let result_val = match last_ok {
Value::Object(_) => last_ok.get("result")?.clone(),
Value::String(s) => {
let parsed: Value = serde_json::from_str(s).ok()?;
match &parsed {
Value::Object(_) => parsed.get("result")?.clone(),
other => other.clone(),
}
}
_ => return None,
};
value_as_result_text(&result_val)
}
fn value_as_result_text(result_val: &Value) -> Option<String> {
match result_val {
Value::Null => None,
Value::String(t) => {
let t = t.trim();
if t.is_empty() {
None
} else {
Some(t.to_string())
}
}
Value::Number(n) => Some(n.to_string()),
Value::Bool(b) => Some(if *b { "true" } else { "false" }.into()),
_ => None,
}
}
fn marqdo_quoted_text(s: &str) -> String {
let mut out = String::from("\"");
for c in s.chars() {
match c {
'\\' => out.push_str("\\\\"),
'"' => out.push_str("\\\""),
'\n' => out.push_str("\\n"),
'\t' => out.push_str("\\t"),
c => out.push(c),
}
}
out.push('"');
out
}
fn needs_step_solidify(src: &str) -> bool {
src.contains(".step") || src.contains(".单步") || src.contains("worker.step")
}
pub fn workbook_solidify(args: &Value) -> Result<Value, String> {
let path = arg_text(args, "path")?;
let p = resolve_path(path);
let src = fs::read_to_string(&p).map_err(|e| format!("solidify read: {e}"))?;
if !needs_step_solidify(&src) {
return Ok(json!({
"solidified": false,
"reason": "already_solid",
}));
}
let Some(result) = extract_result_text(args.get("observation")) else {
return Ok(json!({
"solidified": false,
"reason": "no_result",
}));
};
let lit = marqdo_quoted_text(&result);
let body = format!(
"---\ntitle: agent workbook\n---\n\n# main\n\n*`result` = {lit} *\n**`result`**\n"
);
fs::write(&p, body).map_err(|e| format!("solidify write: {e}"))?;
Ok(json!({
"solidified": true,
"result": result,
"path": path,
}))
}
pub fn kb_task_files(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let goal = arg_text(args, "goal")?;
let _sig = goal_sig_hex(&material_for(goal, opt_tools(args)));
let slug = goal_slug_str(goal);
let root = resolve_path(kb);
let mut files: Vec<Value> = Vec::new();
let res = root.join("resources").join(format!("{slug}.mq.md"));
if res.is_file() {
files.push(Value::String(res.to_string_lossy().into_owned()));
}
let explore = root.join("explore").join(&slug);
if explore.is_dir() {
if let Ok(rd) = fs::read_dir(&explore) {
for ent in rd.flatten() {
let p = ent.path();
let name = p.file_name().and_then(|n| n.to_str()).unwrap_or("");
if name.ends_with(".mq.md") {
files.push(Value::String(p.to_string_lossy().into_owned()));
}
}
}
}
let runs = match args.get("runs_dir").and_then(|v| v.as_str()) {
None => resolve_path(".marqdo/agent-runs"),
Some(s) => resolve_path(s),
};
if runs.is_dir() {
let prefix = format!("workbook-{slug}-");
if let Ok(rd) = fs::read_dir(&runs) {
for ent in rd.flatten() {
let p = ent.path();
let name = p.file_name().and_then(|n| n.to_str()).unwrap_or("");
if name.starts_with(&prefix) && name.ends_with(".mq.md") {
files.push(Value::String(p.to_string_lossy().into_owned()));
}
}
}
}
let count = files.len() as i64;
Ok(json!({
"count": count,
"slug": slug,
"files": files,
}))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn slug_readable() {
let s = goal_slug_str("Reply with exactly the word pong and nothing else.");
assert!(s.contains("pong"), "{s}");
assert!(!s.contains(' '));
}
#[test]
fn sig_stable() {
let a = goal_sig_hex("hello");
assert_eq!(a, goal_sig_hex("hello"));
assert_eq!(a.len(), 12);
}
}
+71 -2
View File
@@ -1,4 +1,6 @@
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query.
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb.
mod kb;
use std::collections::HashMap;
use std::ffi::{CStr, CString};
@@ -544,7 +546,7 @@ fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) ->
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
}
fn host_query_json(name: &str) -> Result<serde_json::Value, String> {
pub(crate) fn host_query_json(name: &str) -> Result<serde_json::Value, String> {
let query = unsafe { HOST_QUERY }.ok_or_else(|| "host_query not available".to_string())?;
let userdata = unsafe { HOST_USERDATA };
let c_name = CString::new(name).map_err(|e| e.to_string())?;
@@ -845,6 +847,46 @@ unsafe extern "C" fn agent_tool_allowed(
0
}
macro_rules! kb_ffi {
($fn_name:ident, $call:expr, $label:expr) => {
unsafe extern "C" fn $fn_name(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let v = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("{}: {e}", $label));
return 1;
}
};
match $call(&v) {
Ok(out) => {
set_out(out_json, &out.to_string());
0
}
Err(e) => {
set_err(err_msg, &format!("{}: {e}", $label));
1
}
}
}
};
}
kb_ffi!(agent_goal_sig, kb::goal_sig, "agent_goal_sig");
kb_ffi!(agent_goal_slug, kb::goal_slug, "agent_goal_slug");
kb_ffi!(agent_kb_lookup, kb::kb_lookup, "agent_kb_lookup");
kb_ffi!(agent_kb_promote, kb::kb_promote, "agent_kb_promote");
kb_ffi!(agent_kb_record_hit, kb::kb_record_hit, "agent_kb_record_hit");
kb_ffi!(
agent_workbook_solidify,
kb::workbook_solidify,
"agent_workbook_solidify"
);
kb_ffi!(agent_kb_task_files, kb::kb_task_files, "agent_kb_task_files");
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
ABI_VERSION
@@ -914,6 +956,33 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
if register(host, "agent_tool_allowed", "tools,name", agent_tool_allowed) != 0 {
return 1;
}
if register(host, "agent_goal_sig", "goal", agent_goal_sig) != 0 {
return 1;
}
if register(host, "agent_goal_slug", "goal", agent_goal_slug) != 0 {
return 1;
}
if register(host, "agent_kb_lookup", "kb_dir,goal", agent_kb_lookup) != 0 {
return 1;
}
if register(
host,
"agent_kb_promote",
"kb_dir,goal,workbook",
agent_kb_promote,
) != 0
{
return 1;
}
if register(host, "agent_kb_record_hit", "kb_dir,goal", agent_kb_record_hit) != 0 {
return 1;
}
if register(host, "agent_workbook_solidify", "path", agent_workbook_solidify) != 0 {
return 1;
}
if register(host, "agent_kb_task_files", "kb_dir,goal", agent_kb_task_files) != 0 {
return 1;
}
0
}
+1 -1
View File
@@ -15,6 +15,6 @@ description: Spawn file, function, or foreign code in parallel
| `code=` | foreign ``` fence ``` subprocess | stdout text |
| `lang=` + `source=` | foreign source subprocess | stdout text |
Also: `poll id=`, `kill id=`, `wait_all`. Parent exit kills file/foreign children.
File children are silent unless `quiet=False`. Also: `poll id=`, `kill id=`, `wait_all`. Parent exit kills file/foreign children.
> print text=subtask overview ok
+1 -1
View File
@@ -15,6 +15,6 @@ description: 文件、函数或外联代码并行执行
| `代码=` | 外联代码块子进程 | stdout 文本 |
| `语言=` + `源码=` | 外联源码子进程 | stdout 文本 |
另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。
文件子任务默认静默;`静默=假` 时继承父终端。另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。
> 打印 内容=子任务总览就绪
+1 -1
View File
@@ -32,7 +32,7 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
| `#` | **Object / type** (constructor body). `# main` = entry object. |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
+9
View File
@@ -159,4 +159,13 @@ if x > 0:
# GOOD — ordered list arms
1. `x` > 0
> print text=pos
2. *
> print text=other
# GOOD — another independent branch (restart at 1.)
1. `y` > 0
> print text=y-pos
2. *
> print text=y-other
```
+1 -1
View File
@@ -18,7 +18,7 @@ marqdo ext remove llm|agent
Diagnostics look like `path:line:col: message` (1-based line/col).
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * ``; loops `` - [`item`](`coll`) ``; identifiers in backticks. See `doc/design/markdown-mapping.md`.
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [`item`](`coll`) ``; identifiers in backticks. See `doc/design/markdown-mapping.md`.
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
+348 -27
View File
@@ -1,4 +1,4 @@
//! OKF-compatible catalog generation: `marqdo catalog` / `sync`.
//! OKF-compatible catalog generation: `marqdo catalog` / `sync` (O1+O3).
use std::fs;
use std::path::{Path, PathBuf};
@@ -19,6 +19,25 @@ struct ModuleInfo {
title: String,
imports: Vec<String>,
exports: Vec<String>,
/// Optional OKF trust fields copied from source frontmatter.
verified_by: Option<String>,
sources: Vec<String>,
}
struct ConceptInfo {
/// Relative id e.g. `concepts/tasks/<sig>`
id: String,
concept_type: String,
title: String,
status: String,
resource: Option<String>,
skill: Option<String>,
description: Option<String>,
verified_by: Option<String>,
/// Absolute path of source concept page (to copy).
abs: PathBuf,
/// Relative path under out_dir e.g. `concepts/tasks/x.md`
out_rel: String,
}
pub fn write_catalog(opts: CatalogOptions) -> Result<()> {
@@ -31,17 +50,20 @@ pub fn write_catalog(opts: CatalogOptions) -> Result<()> {
opts.path.clone()
};
let root = root.canonicalize().unwrap_or(root);
let out_canon = opts.out_dir.canonicalize().unwrap_or(opts.out_dir.clone());
let mut files = Vec::new();
if opts.path.is_file() {
files.push(opts.path.canonicalize().unwrap_or(opts.path.clone()));
} else {
collect_mq_md(&root, &root, &mut files)?;
collect_mq_md(&root, &root, &out_canon, &mut files)?;
files.sort();
}
fs::create_dir_all(opts.out_dir.join("modules"))
.with_context(|| format!("create {}", opts.out_dir.display()))?;
fs::create_dir_all(opts.out_dir.join("concepts"))
.with_context(|| format!("create concepts under {}", opts.out_dir.display()))?;
let version = env!("CARGO_PKG_VERSION");
let mut modules = Vec::new();
@@ -53,6 +75,10 @@ pub fn write_catalog(opts: CatalogOptions) -> Result<()> {
.unwrap_or(abs)
.to_string_lossy()
.replace('\\', "/");
// Skip agent-kb resources (executable skills) from Module table — they appear as concepts.
if rel.contains("/.marqdo/agent-kb/") || rel.starts_with(".marqdo/agent-kb/") {
continue;
}
match inspect_file(abs, &rel) {
Ok(info) => modules.push(info),
Err(e) => {
@@ -62,22 +88,36 @@ pub fn write_catalog(opts: CatalogOptions) -> Result<()> {
}
}
let catalog_yaml = render_catalog_yaml(&modules, version);
let mut concepts = Vec::new();
collect_agent_concepts(&root, &out_canon, &mut concepts)?;
concepts.sort_by(|a, b| a.id.cmp(&b.id));
for c in &concepts {
let dest = opts.out_dir.join(&c.out_rel);
if let Some(p) = dest.parent() {
fs::create_dir_all(p)?;
}
let body = fs::read_to_string(&c.abs)
.with_context(|| format!("read concept {}", c.abs.display()))?;
fs::write(&dest, body)?;
}
let catalog_yaml = render_catalog_yaml(&modules, &concepts, version);
fs::write(opts.out_dir.join("catalog.yaml"), catalog_yaml)?;
let index_md = render_index_md(&modules, version);
let index_md = render_index_md(&modules, &concepts, version);
fs::write(opts.out_dir.join("index.md"), index_md)?;
for m in &modules {
let stem = m.resource.replace('/', "__").replace('\\', "__");
let stem = stem.trim_end_matches(".mq.md");
let stem = module_stem(&m.resource);
let path = opts.out_dir.join("modules").join(format!("{stem}.md"));
fs::write(&path, render_module_md(m, version))?;
fs::write(&path, render_module_md(m, &modules, version))?;
}
eprintln!(
"marqdo catalog: {} module(s) → {}",
"marqdo catalog: {} module(s), {} concept(s) → {}",
modules.len(),
concepts.len(),
opts.out_dir.display()
);
if had_err {
@@ -86,12 +126,30 @@ pub fn write_catalog(opts: CatalogOptions) -> Result<()> {
Ok(())
}
fn collect_mq_md(root: &Path, dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
fn module_stem(resource: &str) -> String {
resource
.replace('/', "__")
.replace('\\', "__")
.trim_end_matches(".mq.md")
.to_string()
}
fn collect_mq_md(
root: &Path,
dir: &Path,
out_canon: &Path,
out: &mut Vec<PathBuf>,
) -> Result<()> {
for entry in fs::read_dir(dir)? {
let entry = entry?;
let p = entry.path();
if p.is_dir() {
collect_mq_md(root, &p, out)?;
if let Ok(canon) = p.canonicalize() {
if canon == *out_canon {
continue;
}
}
collect_mq_md(root, &p, out_canon, out)?;
} else if p
.file_name()
.and_then(|s| s.to_str())
@@ -104,14 +162,100 @@ fn collect_mq_md(root: &Path, dir: &Path, out: &mut Vec<PathBuf>) -> Result<()>
Ok(())
}
/// Find `**/.marqdo/agent-kb/concepts/**/*.md` under scan root.
fn collect_agent_concepts(
root: &Path,
out_canon: &Path,
out: &mut Vec<ConceptInfo>,
) -> Result<()> {
walk_for_concepts(root, root, out_canon, out)
}
fn walk_for_concepts(
root: &Path,
dir: &Path,
out_canon: &Path,
out: &mut Vec<ConceptInfo>,
) -> Result<()> {
for entry in fs::read_dir(dir)? {
let entry = entry?;
let p = entry.path();
if p.is_dir() {
if let Ok(canon) = p.canonicalize() {
if canon == *out_canon {
continue;
}
}
walk_for_concepts(root, &p, out_canon, out)?;
continue;
}
let Some(name) = p.file_name().and_then(|s| s.to_str()) else {
continue;
};
if !name.ends_with(".md") || name.ends_with(".mq.md") {
continue;
}
let rel = p
.strip_prefix(root)
.unwrap_or(&p)
.to_string_lossy()
.replace('\\', "/");
let marker = "/.marqdo/agent-kb/concepts/";
let idx = if let Some(i) = rel.find(marker) {
i + marker.len()
} else if let Some(rest) = rel.strip_prefix(".marqdo/agent-kb/concepts/") {
// path relative from agent-kb concepts
let _ = rest;
0
} else {
continue;
};
let under = if idx == 0 {
rel.strip_prefix(".marqdo/agent-kb/concepts/")
.unwrap_or("")
.to_string()
} else {
rel[idx..].to_string()
};
if under.is_empty() {
continue;
}
let source = fs::read_to_string(&p)?;
let concept_type =
extract_fm_field(&source, "type").unwrap_or_else(|| "Marqdo Concept".into());
let title = extract_fm_field(&source, "title").unwrap_or_else(|| under.clone());
let status = extract_fm_field(&source, "status").unwrap_or_else(|| "stable".into());
let resource = extract_fm_field(&source, "resource");
let skill = extract_fm_field(&source, "skill");
let description = extract_fm_field(&source, "description");
let verified_by = extract_nested_by(&source, "verified");
let id = format!("concepts/{}", under.trim_end_matches(".md"));
let out_rel = format!("concepts/{under}");
out.push(ConceptInfo {
id,
concept_type,
title,
status,
resource,
skill,
description,
verified_by,
abs: p,
out_rel,
});
}
Ok(())
}
fn inspect_file(abs: &Path, rel: &str) -> Result<ModuleInfo> {
let source = fs::read_to_string(abs)?;
let imports = extract_frontmatter_imports(&source);
let title = extract_frontmatter_title(&source)
.unwrap_or_else(|| rel.trim_end_matches(".mq.md").to_string());
let verified_by = extract_nested_by(&source, "verified");
let sources = extract_fm_list(&source, "sources");
let mut exports = Vec::new();
// Prefer parse for accurate top-level fn names
match parse_source(&source) {
Ok(module) => {
for f in &module.functions {
@@ -140,6 +284,8 @@ fn inspect_file(abs: &Path, rel: &str) -> Result<ModuleInfo> {
title,
imports,
exports,
verified_by,
sources,
})
}
@@ -165,23 +311,100 @@ fn extract_frontmatter_imports(source: &str) -> Vec<String> {
}
fn extract_frontmatter_title(source: &str) -> Option<String> {
extract_fm_field(source, "title")
}
fn extract_fm_field(source: &str, key: &str) -> Option<String> {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return None;
}
let prefix = format!("{key}:");
for line in lines.iter().skip(1) {
let t = line.trim();
if t == "---" {
break;
}
if let Some(v) = t.strip_prefix("title:") {
return Some(v.trim().trim_matches('"').to_string());
if let Some(rest) = t.strip_prefix(&prefix) {
return Some(rest.trim().trim_matches('"').to_string());
}
}
None
}
/// `verified:\n by: foo` → Some("foo")
fn extract_nested_by(source: &str, block: &str) -> Option<String> {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return None;
}
let mut in_block = false;
for line in lines.iter().skip(1) {
let t = line.trim_end();
if t.trim() == "---" {
break;
}
if t.trim() == format!("{block}:") || t.trim().starts_with(&format!("{block}:")) {
// inline `verified: { by: x }` not supported; block form:
if t.trim() == format!("{block}:") {
in_block = true;
continue;
}
}
if in_block {
let trimmed = t.trim();
if trimmed.starts_with("by:") {
return Some(
trimmed
.trim_start_matches("by:")
.trim()
.trim_matches('"')
.to_string(),
);
}
if !trimmed.is_empty() && !line.starts_with(' ') && !line.starts_with('\t') {
break;
}
}
}
None
}
fn extract_fm_list(source: &str, key: &str) -> Vec<String> {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return Vec::new();
}
let mut out = Vec::new();
let mut in_list = false;
let header = format!("{key}:");
for line in lines.iter().skip(1) {
let t = line.trim_end();
if t.trim() == "---" {
break;
}
if t.trim() == header || t.trim() == format!("{key}: []") {
if t.trim().ends_with("[]") {
return Vec::new();
}
in_list = true;
continue;
}
if in_list {
let trimmed = t.trim();
if let Some(rest) = trimmed.strip_prefix("- ") {
out.push(rest.trim().trim_matches('"').to_string());
} else if !trimmed.is_empty() && !line.starts_with(' ') && !line.starts_with('\t') {
break;
}
}
}
out
}
fn yaml_escape(s: &str) -> String {
if s.is_empty()
|| s.contains(':')
@@ -197,7 +420,20 @@ fn yaml_escape(s: &str) -> String {
}
}
fn render_catalog_yaml(modules: &[ModuleInfo], version: &str) -> String {
fn import_path(imp: &str) -> &str {
imp.split(" as ").next().unwrap_or(imp).trim()
}
fn resolve_import_module<'a>(imp: &str, modules: &'a [ModuleInfo]) -> Option<&'a ModuleInfo> {
let path = import_path(imp);
modules.iter().find(|m| {
m.resource == path
|| m.resource.ends_with(path)
|| m.resource.ends_with(&format!("/{path}"))
})
}
fn render_catalog_yaml(modules: &[ModuleInfo], concepts: &[ConceptInfo], version: &str) -> String {
let mut out = String::new();
out.push_str("# GENERATED by marqdo — do not edit by hand\n");
out.push_str("type: Marqdo Catalog\n");
@@ -226,11 +462,47 @@ fn render_catalog_yaml(modules: &[ModuleInfo], version: &str) -> String {
out.push_str(" kind: fn\n");
}
}
if let Some(ref v) = m.verified_by {
out.push_str(" verified:\n");
out.push_str(&format!(" by: {}\n", yaml_escape(v)));
}
if !m.sources.is_empty() {
out.push_str(" sources:\n");
for s in &m.sources {
out.push_str(&format!(" - {}\n", yaml_escape(s)));
}
}
}
out.push_str("concepts:\n");
if concepts.is_empty() {
// keep key present for consumers
out.push_str(" []\n");
} else {
for c in concepts {
out.push_str(&format!(" - id: {}\n", yaml_escape(&c.id)));
out.push_str(&format!(" type: {}\n", yaml_escape(&c.concept_type)));
out.push_str(&format!(" title: {}\n", yaml_escape(&c.title)));
out.push_str(&format!(" status: {}\n", yaml_escape(&c.status)));
out.push_str(&format!(" page: {}\n", yaml_escape(&c.out_rel)));
if let Some(ref r) = c.resource {
out.push_str(&format!(" resource: {}\n", yaml_escape(r)));
}
if let Some(ref s) = c.skill {
out.push_str(&format!(" skill: {}\n", yaml_escape(s)));
}
if let Some(ref d) = c.description {
out.push_str(&format!(" description: {}\n", yaml_escape(d)));
}
if let Some(ref v) = c.verified_by {
out.push_str(" verified:\n");
out.push_str(&format!(" by: {}\n", yaml_escape(v)));
}
}
}
out
}
fn render_index_md(modules: &[ModuleInfo], version: &str) -> String {
fn render_index_md(modules: &[ModuleInfo], concepts: &[ConceptInfo], version: &str) -> String {
let mut out = String::new();
out.push_str("---\n");
out.push_str("type: Marqdo Catalog\n");
@@ -240,26 +512,56 @@ fn render_index_md(modules: &[ModuleInfo], version: &str) -> String {
out.push_str("---\n\n");
out.push_str("# Catalog\n\n");
out.push_str("> Generated by Marqdo. Do not edit by hand.\n\n");
out.push_str("## Modules\n\n");
out.push_str("| Module | Resource | Imports |\n");
out.push_str("|--------|----------|--------|\n");
for m in modules {
let stem = m.resource.replace('/', "__");
let stem = stem.trim_end_matches(".mq.md");
let stem = module_stem(&m.resource);
let imports_cell = if m.imports.is_empty() {
"—".to_string()
} else {
m.imports
.iter()
.map(|i| {
if let Some(dep) = resolve_import_module(i, modules) {
format!(
"[{}](modules/{}.md)",
dep.title,
module_stem(&dep.resource)
)
} else {
format!("`{i}`")
}
})
.collect::<Vec<_>>()
.join(", ")
};
out.push_str(&format!(
"| [{}](modules/{stem}.md) | `{}` | {} |\n",
m.title,
m.resource,
if m.imports.is_empty() {
"—".into()
} else {
m.imports.join(", ")
}
"| [{}](modules/{stem}.md) | `{}` | {imports_cell} |\n",
m.title, m.resource
));
}
out.push_str("\n## Agent knowledge (OKF concepts)\n\n");
if concepts.is_empty() {
out.push_str("_No `.marqdo/agent-kb` concepts found under the scan root._\n");
} else {
out.push_str("| Concept | Type | Status | Page |\n");
out.push_str("|---------|------|--------|------|\n");
for c in concepts {
out.push_str(&format!(
"| {} | `{}` | {} | [{}]({}) |\n",
c.title, c.concept_type, c.status, c.id, c.out_rel
));
}
out.push_str(
"\nThese pages are copied from local `agent-kb` for human browsing alongside modules.\n",
);
}
out
}
fn render_module_md(m: &ModuleInfo, version: &str) -> String {
fn render_module_md(m: &ModuleInfo, modules: &[ModuleInfo], version: &str) -> String {
let mut out = String::new();
out.push_str("---\n");
out.push_str("type: Marqdo Module\n");
@@ -283,6 +585,16 @@ fn render_module_md(m: &ModuleInfo, version: &str) -> String {
}
out.push_str("generated:\n");
out.push_str(&format!(" by: marqdo/{version}\n"));
if let Some(ref v) = m.verified_by {
out.push_str("verified:\n");
out.push_str(&format!(" by: {v}\n"));
}
if !m.sources.is_empty() {
out.push_str("sources:\n");
for s in &m.sources {
out.push_str(&format!(" - {s}\n"));
}
}
out.push_str("---\n\n");
out.push_str(&format!("# {}\n\n", m.title));
out.push_str(&format!(
@@ -294,7 +606,16 @@ fn render_module_md(m: &ModuleInfo, version: &str) -> String {
out.push_str("_None_\n\n");
} else {
for i in &m.imports {
out.push_str(&format!("- `{i}`\n"));
if let Some(dep) = resolve_import_module(i, modules) {
out.push_str(&format!(
"- [{}]({}.md) (`{}`)\n",
dep.title,
module_stem(&dep.resource),
i
));
} else {
out.push_str(&format!("- `{i}`\n"));
}
}
out.push('\n');
}
+26 -1
View File
@@ -94,6 +94,9 @@ pub enum HostFn {
SubtaskWaitAll = 92,
WritebackEnsure = 93,
OuterCallLine = 94,
TextPatch = 95,
ApplyPatchBlocks = 96,
WritebackScanPath = 97,
}
impl HostFn {
@@ -184,6 +187,9 @@ impl HostFn {
92 => Self::SubtaskWaitAll,
93 => Self::WritebackEnsure,
94 => Self::OuterCallLine,
95 => Self::TextPatch,
96 => Self::ApplyPatchBlocks,
97 => Self::WritebackScanPath,
_ => return None,
})
}
@@ -273,6 +279,9 @@ impl HostFn {
"host_writeback_list" | "writeback_list" => Self::WritebackList,
"host_writeback_ensure" | "writeback_ensure" => Self::WritebackEnsure,
"host_outer_call_line" | "outer_call_line" => Self::OuterCallLine,
"host_text_patch" | "text_patch" => Self::TextPatch,
"host_apply_patch_blocks" | "apply_patch_blocks" => Self::ApplyPatchBlocks,
"host_writeback_scan_path" | "writeback_scan_path" => Self::WritebackScanPath,
"host_subtask_spawn" | "subtask_spawn" => Self::SubtaskSpawn,
"host_subtask_poll" | "subtask_poll" => Self::SubtaskPoll,
"host_subtask_join" | "subtask_join" => Self::SubtaskJoin,
@@ -368,6 +377,9 @@ impl HostFn {
Self::WritebackList => "host_writeback_list",
Self::WritebackEnsure => "host_writeback_ensure",
Self::OuterCallLine => "host_outer_call_line",
Self::TextPatch => "host_text_patch",
Self::ApplyPatchBlocks => "host_apply_patch_blocks",
Self::WritebackScanPath => "host_writeback_scan_path",
Self::SubtaskSpawn => "host_subtask_spawn",
Self::SubtaskPoll => "host_subtask_poll",
Self::SubtaskJoin => "host_subtask_join",
@@ -419,6 +431,9 @@ impl HostFn {
Self::PluginUnload | Self::PluginList => &[],
Self::ExtNativePath => &["name"],
Self::OuterCallLine => &[],
Self::TextPatch => &["path", "find", "replace"],
Self::ApplyPatchBlocks => &["path", "text"],
Self::WritebackScanPath => &["path"],
Self::MapSet => &["map", "key", "value"],
Self::ListAppend => &["list", "item"],
Self::WritebackRecord => &["value"],
@@ -449,7 +464,7 @@ impl HostFn {
&["at_end", "key", "line"]
}
Self::WritebackEnsure => &["placeholder", "line"],
Self::SubtaskSpawn => &["path", "fn", "args", "code", "lang", "source", "stdin"],
Self::SubtaskSpawn => &["path", "fn", "args", "code", "lang", "source", "stdin", "quiet"],
_ => &[],
}
}
@@ -634,6 +649,16 @@ pub fn call_host(
.copied()
.unwrap_or(ctx.current_line) as i64,
)),
HostFn::TextPatch => fs::text_patch(
ctx,
require(bound, "path")?,
require(bound, "find")?,
require(bound, "replace")?,
),
HostFn::ApplyPatchBlocks => {
fs::apply_patch_blocks(ctx, require(bound, "path")?, require(bound, "text")?)
}
HostFn::WritebackScanPath => writeback::scan_path(ctx, require(bound, "path")?),
HostFn::WritebackRecord => writeback::record(
ctx,
require(bound, "value")?,
+185
View File
@@ -106,3 +106,188 @@ pub fn remove(ctx: &HostContext, path: &Value) -> Result<Value, String> {
}
Ok(Value::None)
}
/// Exact UTF-8 FIND→REPLACE on a file. `find` must occur exactly once.
pub fn text_patch(ctx: &HostContext, path: &Value, find: &Value, replace: &Value) -> Result<Value, String> {
if !ctx.allow_fs_write() {
return Err("text_patch denied by host policy".into());
}
let p = ctx.resolve_path(text_path(path)?)?;
let find = text_body(find)?;
let replace = text_body(replace)?;
if find.is_empty() {
return Err("text_patch: find must be non-empty".into());
}
let src = fs::read_to_string(&p).map_err(|e| format!("text_patch {}: {e}", p.display()))?;
let count = src.matches(find).count();
if count == 0 {
return Err(format!(
"text_patch: find not found in {}",
p.display()
));
}
if count > 1 {
return Err(format!(
"text_patch: find matched {count} times in {} (must be unique)",
p.display()
));
}
let next = src.replacen(find, replace, 1);
fs::write(&p, next).map_err(|e| format!("text_patch write {}: {e}", p.display()))?;
Ok(Value::Int(1))
}
/// Apply one or more FIND/REPLACE blocks from plan-reply text.
///
/// Blocks:
/// ```text
/// <<<
/// FIND
/// <old>
/// ===
/// REPLACE
/// <new>
/// >>>
/// ```
pub fn apply_patch_blocks(ctx: &HostContext, path: &Value, text: &Value) -> Result<Value, String> {
if !ctx.allow_fs_write() {
return Err("apply_patch_blocks denied by host policy".into());
}
let blocks = parse_patch_blocks(text_body(text)?)?;
if blocks.is_empty() {
return Ok(Value::Int(0));
}
let p = ctx.resolve_path(text_path(path)?)?;
let mut src = fs::read_to_string(&p).map_err(|e| format!("apply_patch_blocks {}: {e}", p.display()))?;
let mut applied = 0i64;
for (find, replace) in blocks {
if find.is_empty() {
return Err("apply_patch_blocks: empty FIND".into());
}
let count = src.matches(&find).count();
if count == 0 {
return Err(format!(
"apply_patch_blocks: FIND not found in {}",
p.display()
));
}
if count > 1 {
return Err(format!(
"apply_patch_blocks: FIND matched {count} times in {} (must be unique)",
p.display()
));
}
src = src.replacen(&find, &replace, 1);
applied += 1;
}
fs::write(&p, src).map_err(|e| format!("apply_patch_blocks write {}: {e}", p.display()))?;
Ok(Value::Int(applied))
}
fn parse_patch_blocks(text: &str) -> Result<Vec<(String, String)>, String> {
let mut out = Vec::new();
let mut rest = text;
while let Some(start) = rest.find("<<<") {
let after = &rest[start + 3..];
let end = after
.find(">>>")
.ok_or_else(|| "apply_patch_blocks: unclosed <<< block".to_string())?;
let body = after[..end].trim();
rest = &after[end + 3..];
let (find_part, replace_part) = body
.split_once("===")
.ok_or_else(|| "apply_patch_blocks: block missing ===".to_string())?;
let find = strip_labeled(find_part, "FIND")?;
let replace = strip_labeled(replace_part, "REPLACE")?;
out.push((find, replace));
}
Ok(out)
}
fn strip_labeled(chunk: &str, label: &str) -> Result<String, String> {
let t = chunk.trim();
let upper = t.to_ascii_uppercase();
let label_u = label.to_ascii_uppercase();
if upper.starts_with(&label_u) {
let after = t[label.len()..].trim_start_matches([':', ' ', '\t']);
let after = after.strip_prefix('\n').unwrap_or(after);
Ok(after.to_string())
} else {
Ok(t.to_string())
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::host::{HostCaps, HostContext};
use std::fs;
use std::time::{SystemTime, UNIX_EPOCH};
fn write_ctx(dir: &std::path::Path) -> HostContext {
let entry = dir.join("entry.mq.md");
let _ = fs::write(&entry, "# main\n");
let mut ctx = HostContext::for_run(Some(&entry), HostCaps::default(), vec![]);
ctx.cwd = dir.to_path_buf();
ctx.fs_root = Some(dir.to_path_buf());
ctx
}
fn temp_workspace(tag: &str) -> std::path::PathBuf {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos();
let dir = std::env::temp_dir().join(format!("marqdo-fs-{tag}-{nanos}"));
fs::create_dir_all(&dir).unwrap();
dir
}
#[test]
fn text_patch_unique() {
let dir = temp_workspace("patch");
let path = dir.join("a.md");
fs::write(&path, "hello OLD world").unwrap();
let ctx = write_ctx(&dir);
let n = text_patch(
&ctx,
&Value::Text("a.md".into()),
&Value::Text("OLD".into()),
&Value::Text("NEW".into()),
)
.unwrap();
assert_eq!(n, Value::Int(1));
assert_eq!(fs::read_to_string(&path).unwrap(), "hello NEW world");
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn apply_patch_blocks_two() {
let dir = temp_workspace("blocks");
let path = dir.join("a.md");
fs::write(&path, "aa bb cc").unwrap();
let ctx = write_ctx(&dir);
let reply = r#"
DECISION: CONTINUE
PATCH:
<<<
FIND
aa
===
REPLACE
AA
>>>
<<<
FIND
cc
===
REPLACE
CC
>>>
"#;
let n = apply_patch_blocks(&ctx, &Value::Text("a.md".into()), &Value::Text(reply.into())).unwrap();
assert_eq!(n, Value::Int(2));
assert_eq!(fs::read_to_string(&path).unwrap(), "AA bb CC");
let _ = fs::remove_dir_all(&dir);
}
}
+2 -2
View File
@@ -8,7 +8,7 @@ pub mod agent_rt;
mod dispatch;
pub mod foreign;
mod fs;
mod json;
pub(crate) mod json;
pub mod math;
mod net;
pub mod plugin;
@@ -78,7 +78,7 @@ pub struct HostContext {
/// Entry-file line of each active user call (for writeback anchoring).
pub call_site_lines: Vec<u32>,
/// Concurrent subtasks (`lib/subtask`): file / function / foreign.
pub subtasks: HashMap<u64, subtask::Handle>,
pub(crate) subtasks: HashMap<u64, subtask::Handle>,
pub subtask_seq: u64,
}
+3
View File
@@ -243,6 +243,9 @@ unsafe extern "C" fn host_query(
"module_source" => agent_rt::module_source(ctx).and_then(|v| value_to_json(&v)),
"call_site" => agent_rt::call_site(ctx, Some(ctx.current_line)).and_then(|v| value_to_json(&v)),
"marqdo_skill" => agent_rt::marqdo_skill(ctx).and_then(|v| value_to_json(&v)),
"cwd" => Ok(serde_json::Value::String(
ctx.cwd.to_string_lossy().into_owned(),
)),
other => Err(format!("host_query: unknown `{other}`")),
};
+78 -16
View File
@@ -15,7 +15,7 @@ use crate::value::{CodeBlock, Value};
/// Stored subtask handle (tagged by spawn kind).
pub(crate) enum Handle {
File(Child),
File(FileTask),
Foreign(ForeignTask),
Function(FunctionTask),
}
@@ -30,7 +30,12 @@ impl std::fmt::Debug for Handle {
}
}
struct ForeignTask {
pub(crate) struct FileTask {
child: Child,
result_path: PathBuf,
}
pub(crate) struct ForeignTask {
child: Child,
temp_script: PathBuf,
stdout: JoinHandle<String>,
@@ -44,7 +49,7 @@ enum FnState {
Killed,
}
struct FunctionTask {
pub(crate) struct FunctionTask {
state: Arc<Mutex<FnState>>,
handle: Option<JoinHandle<()>>,
}
@@ -121,9 +126,10 @@ fn fn_args_from_value(args: Option<&Value>) -> Result<Vec<(String, Value)>, Stri
pub fn kill_all(ctx: &mut HostContext) {
for (_, handle) in ctx.subtasks.drain() {
match handle {
Handle::File(mut child) => {
let _ = child.kill();
let _ = child.wait();
Handle::File(mut task) => {
let _ = task.child.kill();
let _ = task.child.wait();
let _ = std::fs::remove_file(&task.result_path);
}
Handle::Foreign(mut task) => {
let _ = task.child.kill();
@@ -161,6 +167,7 @@ pub fn spawn(ctx: &mut HostContext, bound: &HashMap<String, Value>) -> Result<Va
ctx,
require(bound, "path")?,
bound.get("args"),
bound.get("quiet"),
)
} else if has_fn {
spawn_fn(ctx, require(bound, "fn")?, bound.get("args"))
@@ -180,21 +187,51 @@ fn spawn_file(
ctx: &mut HostContext,
path: &Value,
args: Option<&Value>,
quiet: Option<&Value>,
) -> Result<Value, String> {
if !ctx.caps.exec {
return Err("subtask spawn disabled (exec capability off)".into());
}
let rel = as_text(path, "path")?;
let file = if std::path::Path::new(rel).is_absolute() {
let joined = if std::path::Path::new(rel).is_absolute() {
std::path::PathBuf::from(rel)
} else {
ctx.cwd.join(rel)
};
// Absolutize so the child `for_run` cwd/parent resolution does not double-prefix
// a relative path like `tests/ext/.marqdo/...` when current_dir is already `tests/ext`.
let file = std::fs::canonicalize(&joined).unwrap_or_else(|_| {
if joined.is_absolute() {
joined.clone()
} else {
std::env::current_dir()
.unwrap_or_else(|_| std::path::PathBuf::from("."))
.join(&joined)
}
});
let exe = std::env::current_exe().map_err(|e| format!("subtask: current_exe: {e}"))?;
let id = next_id(ctx);
let result_path = std::env::temp_dir().join(format!(
"marqdo-subtask-{}-{}.json",
std::process::id(),
id
));
let mut cmd = Command::new(&exe);
cmd.arg("run").arg(&file);
cmd.arg("--emit-result").arg(&result_path);
cmd.current_dir(&ctx.cwd);
cmd.stdin(Stdio::null());
let quiet = match quiet {
None | Some(Value::None) => true,
Some(v) => v.truthy(),
};
if quiet {
cmd.stdout(Stdio::null());
cmd.stderr(Stdio::null());
} else {
cmd.stdout(Stdio::inherit());
cmd.stderr(Stdio::inherit());
}
if let Some(Value::List(items)) = args {
for item in items {
cmd.arg(as_text(item, "arg")?);
@@ -203,8 +240,13 @@ fn spawn_file(
let child = cmd
.spawn()
.map_err(|e| format!("subtask spawn {}: {e}", file.display()))?;
let id = next_id(ctx);
ctx.subtasks.insert(id, Handle::File(child));
ctx.subtasks.insert(
id,
Handle::File(FileTask {
child,
result_path,
}),
);
Ok(Value::Int(id as i64))
}
@@ -319,7 +361,7 @@ pub fn poll(ctx: &mut HostContext, id: &Value) -> Result<Value, String> {
.get_mut(&id)
.ok_or_else(|| format!("subtask: unknown id {id}"))?;
match handle {
Handle::File(child) => poll_child(child),
Handle::File(task) => poll_child(&mut task.child),
Handle::Foreign(task) => poll_child(&mut task.child),
Handle::Function(task) => poll_function(&task.state),
}
@@ -364,17 +406,34 @@ pub fn join(ctx: &mut HostContext, id: &Value) -> Result<Value, String> {
.remove(&id)
.ok_or_else(|| format!("subtask: unknown id {id}"))?;
match handle {
Handle::File(mut child) => {
let status = child
Handle::File(mut task) => {
let status = task
.child
.wait()
.map_err(|e| format!("subtask join: {e}"))?;
Ok(Value::Int(status.code().unwrap_or(-1) as i64))
let code = status.code().unwrap_or(-1) as i64;
let value = read_emitted_result(&task.result_path);
let _ = std::fs::remove_file(&task.result_path);
Ok(Value::Map(vec![
("code".into(), Value::Int(code)),
("value".into(), value),
]))
}
Handle::Foreign(task) => join_foreign(task),
Handle::Function(task) => join_function(task),
}
}
fn read_emitted_result(path: &PathBuf) -> Value {
match std::fs::read_to_string(path) {
Ok(text) => match serde_json::from_str::<serde_json::Value>(text.trim()) {
Ok(j) => crate::host::json::json_to_value(&j).unwrap_or(Value::None),
Err(_) => Value::None,
},
Err(_) => Value::None,
}
}
fn join_foreign(mut task: ForeignTask) -> Result<Value, String> {
let status = task
.child
@@ -428,9 +487,12 @@ pub fn kill(ctx: &mut HostContext, id: &Value) -> Result<Value, String> {
.remove(&id)
.ok_or_else(|| format!("subtask: unknown id {id}"))?;
match handle {
Handle::File(mut child) => {
child.kill().map_err(|e| format!("subtask kill: {e}"))?;
let _ = child.wait();
Handle::File(mut task) => {
task.child
.kill()
.map_err(|e| format!("subtask kill: {e}"))?;
let _ = task.child.wait();
let _ = std::fs::remove_file(&task.result_path);
}
Handle::Foreign(mut task) => {
task.child.kill().map_err(|e| format!("subtask kill: {e}"))?;
+17 -1
View File
@@ -528,6 +528,22 @@ pub fn list(ctx: &HostContext) -> Result<Value, String> {
.entry_source
.as_deref()
.ok_or_else(|| "writeback: no entry source".to_string())?;
Ok(slots_from_source(source))
}
/// Scan `path` for `<!-- marqdo-out … -->` slots (any file, not only the entry).
pub fn scan_path(ctx: &HostContext, path: &Value) -> Result<Value, String> {
let rel = match path {
Value::Text(s) => s.as_str(),
_ => return Err("writeback scan_path: path must be text".into()),
};
let p = ctx.resolve_path(rel)?;
let source = std::fs::read_to_string(&p)
.map_err(|e| format!("writeback scan_path {}: {e}", p.display()))?;
Ok(slots_from_source(&source))
}
fn slots_from_source(source: &str) -> Value {
let items: Vec<Value> = scan_blocks(source)
.into_iter()
.map(|b| {
@@ -544,7 +560,7 @@ pub fn list(ctx: &HostContext) -> Result<Value, String> {
Value::Map(entries)
})
.collect();
Ok(Value::List(items))
Value::List(items)
}
/// Ensure named slots exist with a placeholder body; **does not** overwrite non-empty bodies.
+20 -2
View File
@@ -75,6 +75,8 @@ pub struct RunOptions {
pub fs_root: Option<std::path::PathBuf>,
/// Sleep clamp when capturing (None = host default; view export uses `Some(0)`).
pub sleep_limit_ms: Option<u64>,
/// When set, write `# main` return value as JSON to this path (file subtasks).
pub emit_result: Option<std::path::PathBuf>,
}
impl Default for RunOptions {
@@ -94,6 +96,7 @@ impl Default for RunOptions {
argv: Vec::new(),
fs_root: None,
sleep_limit_ms: None,
emit_result: None,
}
}
}
@@ -181,12 +184,13 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
if opts.trace_eval {
eprintln!("=== marqdo: trace-eval ({path_label}) ===");
}
interp.run_module(&module)?;
let value = interp.run_module(&module)?;
if opts.trace_eval {
eprintln!("=== marqdo: end trace-eval ===");
}
let plots = interp.take_plots();
flush_auto_plots(Some(path), &plots).map_err(|e| anyhow::anyhow!(e))?;
emit_result_file(opts, &value)?;
}
Backend::Bytecode => {
let program = compile_module(Some(path), &module)?;
@@ -202,12 +206,13 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
if opts.trace_eval {
eprintln!("=== marqdo: trace-eval ({path_label}) ===");
}
vm.run(&program)?;
let value = vm.run(&program)?;
if opts.trace_eval {
eprintln!("=== marqdo: end trace-eval ===");
}
let plots = vm.take_plots();
flush_auto_plots(Some(path), &plots).map_err(|e| anyhow::anyhow!(e))?;
emit_result_file(opts, &value)?;
}
}
@@ -220,6 +225,19 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
Ok(0)
}
fn emit_result_file(opts: &RunOptions, value: &crate::value::Value) -> Result<()> {
let Some(path) = &opts.emit_result else {
return Ok(());
};
let json = crate::host::json::value_to_json(value).map_err(|e| anyhow::anyhow!(e))?;
let text = serde_json::to_string(&json).map_err(|e| anyhow::anyhow!(e))?;
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).map_err(|e| anyhow::anyhow!(e))?;
}
std::fs::write(path, text).map_err(|e| anyhow::anyhow!("emit-result {}: {e}", path.display()))?;
Ok(())
}
/// Run and capture stdout (used by `view` and tests).
pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
let source = std::fs::read_to_string(path)
+24 -2
View File
@@ -107,12 +107,17 @@ pub fn resolve_import(from_dir: &Path, rel: &str) -> Result<PathBuf> {
return Ok(p);
}
}
// Walk importer ancestors so workbooks under `.marqdo/…` still find repo `lib/`.
if let Some(p) = find_in_ancestor_dir(from_dir, "lib", rest) {
return Ok(p);
}
// Embedded stdlib: synthesize a path under lib/ for read_module_source.
return Ok(PathBuf::from("lib").join(rest));
}
if rel.starts_with("ext/") {
let rest = rel.strip_prefix("ext/").unwrap();
for root in ext_search_roots() {
let p = root.join(rel.strip_prefix("ext/").unwrap_or(&rel));
let p = root.join(rest);
// also try full ext/rel under root
let p2 = root.join(&rel);
if p.is_file() {
@@ -122,11 +127,14 @@ pub fn resolve_import(from_dir: &Path, rel: &str) -> Result<PathBuf> {
return Ok(p2);
}
// MARQDO_EXT is the ext root itself (contains ai/)
let under = root.join(rel.strip_prefix("ext/").unwrap());
let under = root.join(rest);
if under.is_file() {
return Ok(under);
}
}
if let Some(p) = find_in_ancestor_dir(from_dir, "ext", rest) {
return Ok(p);
}
}
// Relative again with normalize
if direct.exists() {
@@ -135,6 +143,20 @@ pub fn resolve_import(from_dir: &Path, rel: &str) -> Result<PathBuf> {
bail!("cannot resolve import `{rel}` from {}", from_dir.display())
}
/// Look for `anchor/rest` under `from` or any parent directory (e.g. repo root `ext/ai/…`).
fn find_in_ancestor_dir(from: &Path, anchor: &str, rest: &str) -> Option<PathBuf> {
let mut cur = from.to_path_buf();
loop {
let candidate = cur.join(anchor).join(rest);
if candidate.is_file() {
return Some(candidate);
}
if !cur.pop() {
return None;
}
}
}
fn lib_search_roots() -> Vec<PathBuf> {
let mut roots = Vec::new();
if let Ok(h) = env::var("MARQDO_LIB") {
+7
View File
@@ -60,6 +60,10 @@ enum Commands {
/// Feed `input` from a text file (one line per call), instead of / after the terminal.
#[arg(long, value_name = "FILE")]
stdin_file: Option<PathBuf>,
/// Write `# main` return value as JSON (used by file subtasks).
#[arg(long, value_name = "FILE")]
emit_result: Option<PathBuf>,
},
/// Browse `.mq.md` structure + execution (live server or static output)
View {
@@ -177,6 +181,7 @@ fn try_main() -> Result<i32> {
trace_eval,
dump_all,
stdin_file,
emit_result,
} => {
let path = file.unwrap_or_else(|| PathBuf::from("index.mq.md"));
let stdin_lines = match stdin_file {
@@ -186,6 +191,7 @@ fn try_main() -> Result<i32> {
let mut opts = if dump_all {
RunOptions {
stdin_lines: stdin_lines.clone(),
emit_result: emit_result.clone(),
..RunOptions::dump_all()
}
} else {
@@ -198,6 +204,7 @@ fn try_main() -> Result<i32> {
trace_eval,
backend: backend.into(),
stdin_lines,
emit_result,
..RunOptions::default()
}
};
+96 -2
View File
@@ -16,11 +16,18 @@ pub fn parse_expr(input: &str) -> Result<Expr> {
/// Argument / template RHS: prefer a full expression; else interpolated text.
/// Hyphenated prose (`none-falsy`) is not parsed as subtraction.
/// Quoted `"..."` always uses the expression parser (never the hyphen short-circuit).
pub fn parse_value_or_interp(input: &str) -> Result<Expr> {
let s = input.trim();
if s.is_empty() {
return Ok(Expr::Literal(Literal::Text(String::new())));
}
if s.starts_with('"') {
return match parse_expr(s) {
Ok(e) => Ok(e),
Err(_) => Ok(parse_interp(s)),
};
}
if has_hyphenated_prose(s) {
return Ok(parse_interp(s));
}
@@ -30,6 +37,60 @@ pub fn parse_value_or_interp(input: &str) -> Result<Expr> {
}
}
/// Call-arg / param-default values: like [`parse_value_or_interp`], but also treat a chain of
/// unspaced `Text / Text` divisions as a single path string (`a/b`, `.marqdo/agent-kb`).
/// Real math (`1/2`, `` `n` / 2 ``) is unchanged.
pub fn parse_call_arg_value(input: &str) -> Result<Expr> {
let s = input.trim();
if s.is_empty() {
return Ok(Expr::Literal(Literal::Text(String::new())));
}
if s.starts_with('"') {
return match parse_expr(s) {
Ok(e) => Ok(e),
Err(_) => Ok(parse_interp(s)),
};
}
if has_hyphenated_prose(s) {
return Ok(parse_interp(s));
}
match parse_expr(s) {
Ok(e) => Ok(collapse_text_div_path(e, s)),
Err(_) => Ok(parse_interp(s)),
}
}
fn is_text_only_div_chain(e: &Expr) -> bool {
match e {
Expr::Literal(Literal::Text(_)) => true,
Expr::Binary {
op: BinaryOp::Div,
left,
right,
} => is_text_only_div_chain(left) && matches!(right.as_ref(), Expr::Literal(Literal::Text(_))),
_ => false,
}
}
fn expr_has_div(e: &Expr) -> bool {
match e {
Expr::Binary {
op: BinaryOp::Div, ..
} => true,
Expr::Binary { left, right, .. } => expr_has_div(left) || expr_has_div(right),
Expr::Unary { expr, .. } => expr_has_div(expr),
_ => false,
}
}
fn collapse_text_div_path(e: Expr, raw: &str) -> Expr {
if expr_has_div(&e) && is_text_only_div_chain(&e) {
parse_interp(raw)
} else {
e
}
}
fn has_hyphenated_prose(s: &str) -> bool {
let chars: Vec<char> = s.chars().collect();
for i in 1..chars.len().saturating_sub(1) {
@@ -472,7 +533,7 @@ pub fn parse_call_tail(s: &str) -> Result<(CallExpr, usize)> {
let val_raw = after_eq[..val_end].trim_end();
args.push(Arg::Named {
name: key,
value: parse_value_or_interp(val_raw)?,
value: parse_call_arg_value(val_raw)?,
});
args_str = after_eq[val_end..].trim_start();
} else {
@@ -483,7 +544,7 @@ pub fn parse_call_tail(s: &str) -> Result<(CallExpr, usize)> {
if tok.is_empty() {
break;
}
args.push(Arg::Positional(parse_value_or_interp(tok)?));
args.push(Arg::Positional(parse_call_arg_value(tok)?));
args_str = rest.trim_start();
}
}
@@ -675,6 +736,37 @@ mod tests {
assert!(matches!(e, Expr::Interp(_)));
}
#[test]
fn call_arg_quoted_path_keeps_slashes() {
let e = parse_call_arg_value("\".marqdo/agent-runs\"").unwrap();
assert!(matches!(
e,
Expr::Literal(Literal::Text(ref s)) if s == ".marqdo/agent-runs"
));
let e = parse_value_or_interp("\".marqdo/agent-kb\"").unwrap();
assert!(matches!(
e,
Expr::Literal(Literal::Text(ref s)) if s == ".marqdo/agent-kb"
));
}
#[test]
fn call_arg_bare_path_not_division() {
let e = parse_call_arg_value("a/b/c").unwrap();
assert!(matches!(
e,
Expr::Literal(Literal::Text(ref s)) if s == "a/b/c"
));
let e = parse_call_arg_value("1/2").unwrap();
assert!(matches!(
e,
Expr::Binary {
op: BinaryOp::Div,
..
}
));
}
#[test]
fn bare_token_no_escape() {
let e = parse_expr("a\\nb").unwrap();
@@ -698,3 +790,5 @@ mod tests {
));
}
}
+79 -5
View File
@@ -2,7 +2,7 @@
mod expr;
pub use expr::{parse_call_after_gt, parse_expr, parse_value_or_interp};
pub use expr::{parse_call_after_gt, parse_call_arg_value, parse_expr, parse_value_or_interp};
use anyhow::{bail, Result};
@@ -521,14 +521,17 @@ impl<'a> Cursor<'a> {
break;
}
let trimmed = l.text.trim();
let cond_src = if let Some(rest) = strip_ordered(trimmed) {
rest
} else {
let Some(num) = ordered_item_number(trimmed) else {
break;
};
if ind != base_indent {
break;
}
// Same-indent restart at `1.` begins a new Branch statement.
if !arms.is_empty() && num == 1 {
break;
}
let cond_src = strip_ordered(trimmed).unwrap();
self.bump();
let condition = if cond_src == "*" || cond_src.is_empty() {
@@ -673,7 +676,7 @@ fn parse_param_line(trimmed: &str) -> Option<crate::ast::Param> {
if def_s.is_empty() {
return None;
}
Some(parse_value_or_interp(def_s).ok()?)
Some(parse_call_arg_value(def_s).ok()?)
} else if after.is_empty() {
None
} else {
@@ -843,6 +846,25 @@ fn is_ordered_branch(trimmed: &str) -> bool {
strip_ordered(trimmed).is_some()
}
/// Leading `N` in an ordered-list item `N. …` (1-based Markdown marker).
fn ordered_item_number(trimmed: &str) -> Option<u32> {
let mut chars = trimmed.chars();
let mut n: u32 = 0;
let mut saw_digit = false;
while let Some(c) = chars.next() {
if let Some(d) = c.to_digit(10) {
saw_digit = true;
n = n.saturating_mul(10).saturating_add(d);
continue;
}
if c == '.' && saw_digit {
return Some(n);
}
return None;
}
None
}
fn strip_ordered(trimmed: &str) -> Option<&str> {
let mut chars = trimmed.chars();
let mut saw_digit = false;
@@ -956,6 +978,58 @@ mod tests {
assert!(main.body.iter().any(|s| matches!(s, Stmt::Branch { .. })));
}
#[test]
fn consecutive_branches_restart_at_one() {
let m = parse_source(include_str!(
"../../tests/structure/branch-consecutive.mq.md"
))
.unwrap();
let branches: Vec<_> = m.functions[0]
.body
.iter()
.filter(|s| matches!(s, Stmt::Branch { .. }))
.collect();
assert_eq!(
branches.len(),
3,
"expected three Branch stmts, got {:?}",
m.functions[0].body
);
for b in &branches {
match b {
Stmt::Branch { arms, .. } => assert_eq!(arms.len(), 2),
_ => unreachable!(),
}
}
// Arm bodies must hold the prints (not leaked as sibling Calls).
match branches[0] {
Stmt::Branch { arms, .. } => {
assert!(
matches!(arms[0].body[0], Stmt::Call { .. }),
"first arm body={:?}",
arms[0].body
);
}
_ => unreachable!(),
}
}
#[test]
fn consecutive_branches_without_blank_line() {
let src = "# main\n\n1. True\n > print text=A\n2. *\n > print text=skip\n1. True\n > print text=B\n";
let m = parse_source(src).unwrap();
let branches: Vec<_> = m.functions[0]
.body
.iter()
.filter(|s| matches!(s, Stmt::Branch { .. }))
.collect();
assert_eq!(branches.len(), 2, "got {:?}", m.functions[0].body);
match branches[0] {
Stmt::Branch { arms, .. } => assert_eq!(arms.len(), 2),
_ => unreachable!(),
}
}
#[test]
fn parse_formula_assign_fence() {
let src = "# main\n\n`f` =\n$$\nx^2 - 2\n$$\n\n> print text=`f`\n";
+30
View File
@@ -0,0 +1,30 @@
---
title: agent inspect_workbook (offline)
description: Parse named writeback slots from a fixture workbook path.
> ext/ai/agent.mq.md
> lib/json.mq.md
> lib/fs.mq.md
---
# main
*`paths` = > json.parse text={"f":".marqdo/agent-runs/inspect-fixture.mq.md"} *
*`fixture` = > json.get value=`paths` key=f *
*`body` = > json.parse text={"t":"# main\n\n> print text=hi\n<!-- marqdo-out ok\n{\"status\":\"ok\",\"result\":\"done\"}\n-->\n<!-- marqdo-out error\npending\n-->\n"} *
*`t` = > json.get value=`body` key=t *
> fs.write_text path=`fixture` text=`t`
*`obs` = > agent.inspect_workbook path=`fixture` exit_code=0 *
*`code` = > json.get value=`obs` key=exit_code *
> print text=`code`
*`ok` = > json.get value=`obs` key=last_ok *
*`has` = > split value=`ok` sep=done *
*`n` = > len value=`has` *
1. `n` > 1
> print text=ok-slot
2. *
> print text=ok-missing
*`err` = > json.get value=`obs` key=last_error *
> print text=`err`
+67
View File
@@ -0,0 +1,67 @@
---
title: OKF agent-kb promote + lookup + spawn (offline)
description: Promote a solidified workbook, lookup by goal, spawn without parent LLM.
> ext/ai/agent.mq.md
> lib/fs.mq.md
> lib/json.mq.md
> lib/subtask.mq.md
> lib/plugin.mq.md
> lib/sys.mq.md
---
# main
*`p` = > plugin.native_path name=agent *
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
*`paths` = > json.parse text={"kb":".marqdo/agent-kb","wb":".marqdo/agent-runs/pong-solid.mq.md","goal":"Reply with exactly the word pong and nothing else.","body":"---\ntitle: pong skill\n---\n\n# main\n\n**pong**\n"} *
*`kb` = > json.get value=`paths` key=kb *
*`wb` = > json.get value=`paths` key=wb *
*`goal` = > json.get value=`paths` key=goal *
*`body` = > json.get value=`paths` key=body *
> fs.write_text path=`wb` text=`body`
*`sig` = > agent_goal_sig goal=`goal` *
> print text=`sig`
*`slug0` = > agent_goal_slug goal=`goal` *
> print text=`slug0`
*`prom` = > agent_kb_promote kb_dir=`kb` goal=`goal` workbook=`wb` *
*`okp` = > json.get value=`prom` key=promoted *
1. `okp`
> print text=promoted
2. *
> print text=promote-fail
*`st` = > json.get value=`prom` key=status *
> print text=`st`
*`slug` = > json.get value=`prom` key=slug *
> print text=`slug`
*`hit` = > agent_kb_lookup kb_dir=`kb` goal=`goal` *
1. `hit`
> print text=lookup-ok
2. *
> print text=lookup-miss
*`res` = > json.get value=`hit` key=resource *
*`id` = > subtask.spawn path=`res` *
*`waited` = > subtask.wait id=`id` *
*`code` = > json.get value=`waited` key=code *
*`val` = > json.get value=`waited` key=value *
> print text=`code`
> print text=`val`
*`hit2` = > agent_kb_lookup kb_dir=`kb` goal=`goal` *
*`res2` = > json.get value=`hit2` key=resource *
1. `res` == `res2`
> print text=stable-path
2. *
> print text=path-drift
+36
View File
@@ -0,0 +1,36 @@
---
title: agent plan confirm (offline)
description: Create workbook skeleton with confirm=True; no LLM spawn loop.
> ext/ai/llm.mq.md
> ext/ai/agent.mq.md
> lib/json.mq.md
> lib/fs.mq.md
---
# main
> llm.load_env path=.env
*`model` = > llm.llm *
*`tools` = > json.parse text=[] *
*`助手` = > agent.agent model=`model` tools=`tools` standing=offline plan confirm *
*`out` = > `助手`.plan goal=say hi confirm=True workbook_dir=".marqdo/agent-runs" writeback=False *
*`st` = > json.get value=`out` key=status *
> print text=`st`
*`path` = > json.get value=`out` key=workbook *
*`ex` = > fs.exists path=`path` *
1. `ex`
> print text=workbook-ok
2. *
> print text=workbook-missing
*`src` = > fs.read_text path=`path` *
*`parts` = > split value=`src` sep=agent.agent *
*`n` = > len value=`parts` *
1. `n` > 1
> print text=skeleton-ok
2. *
> print text=skeleton-bad
+48
View File
@@ -0,0 +1,48 @@
---
title: agent plan decision + dual skeleton (offline)
description: extract_plan_decision/summary; dual skeleton contains research+writer; patch apply on fixture.
> ext/ai/agent.mq.md
> lib/json.mq.md
> lib/fs.mq.md
---
# main
*`samples` = > json.parse text={"done":"DECISION: DONE\nSUMMARY: all good\n","cont":"DECISION: CONTINUE\nPATCH:\n<<<\nFIND\nold\n===\nREPLACE\nnew\n>>>\n","zh":"决定:完成\n汇总:好了\n"} *
*`d1` = > json.get value=`samples` key=done *
*`r1` = > agent.extract_plan_decision reply=`d1` *
> print text=`r1`
*`s1` = > agent.extract_plan_summary reply=`d1` *
> print text=`s1`
*`d2` = > json.get value=`samples` key=cont *
*`r2` = > agent.extract_plan_decision reply=`d2` *
> print text=`r2`
*`d3` = > json.get value=`samples` key=zh *
*`r3` = > agent.extract_plan_decision reply=`d3` *
> print text=`r3`
*`dual` = > agent.render_workbook_skeleton goal=demo skeleton=dual *
*`has_r` = > split value=`dual` sep=research *
*`n_r` = > len value=`has_r` *
1. `n_r` > 1
> print text=dual-ok
2. *
> print text=dual-missing
*`has_s` = > split value=`dual` sep=Solidify *
*`n_s` = > len value=`has_s` *
1. `n_s` > 1
> print text=solidify-ok
2. *
> print text=solidify-missing
*`paths` = > json.parse text={"p":".marqdo/agent-runs/decision-patch.md","t":"keep old keep"} *
*`path` = > json.get value=`paths` key=p *
*`seed` = > json.get value=`paths` key=t *
> fs.write_text path=`path` text=`seed`
*`n` = > fs.apply_patch_blocks path=`path` text=`d2` *
> print text=`n`
*`out` = > fs.read_text path=`path` *
> print text=`out`
+43
View File
@@ -0,0 +1,43 @@
---
title: ext/agent plan live (DeepSeek)
description: Full plan loop — spawn workbook, inspect, secondary plan; simple pong goal.
> ext/ai/llm.mq.md
> ext/ai/agent.mq.md
> lib/json.mq.md
> lib/fs.mq.md
---
# main
> llm.load_env path=.env
*`model` = > llm.llm *
*`tools` = > json.parse text=[] *
*`助手` = > agent.agent model=`model` tools=`tools` standing=You are a Marqdo agent-development master. Prefer DONE when the workbook already satisfies the goal. *
*`out` = > `助手`.plan goal=Reply with exactly the word pong and nothing else. max_rounds=3 writeback=False *
*`st` = > json.get value=`out` key=status *
> print text=`st`
*`sum` = > json.get value=`out` key=summary *
1. `sum`
> print text=`sum`
2. *
> print text=no-summary
*`cache` = > json.get value=`out` key=cache *
> print text=`cache`
*`path` = > json.get value=`out` key=workbook *
*`ex` = > fs.exists path=`path` *
1. `ex`
> print text=workbook-ok
2. *
> print text=workbook-missing
*`out2` = > `助手`.plan goal=Reply with exactly the word pong and nothing else. max_rounds=3 writeback=False *
*`st2` = > json.get value=`out2` key=status *
> print text=`st2`
*`cache2` = > json.get value=`out2` key=cache *
> print text=`cache2`
+23
View File
@@ -0,0 +1,23 @@
---
title: fs text_patch / apply_patch_blocks (offline)
> lib/fs.mq.md
> lib/json.mq.md
---
# main
*`paths` = > json.parse text={"p":".marqdo/agent-runs/patch-demo.md","t":"alpha beta gamma"} *
*`path` = > json.get value=`paths` key=p *
*`seed` = > json.get value=`paths` key=t *
> fs.write_text path=`path` text=`seed`
> fs.text_patch path=`path` find=beta replace=BETA
*`s1` = > fs.read_text path=`path` *
> print text=`s1`
*`reply` = > json.parse text={"t":"DECISION: CONTINUE\n<<<\nFIND\nalpha\n===\nREPLACE\nALPHA\n>>>\n<<<\nFIND\ngamma\n===\nREPLACE\nGAMMA\n>>>\n"} *
*`t` = > json.get value=`reply` key=t *
*`n` = > fs.apply_patch_blocks path=`path` text=`t` *
> print text=`n`
*`s2` = > fs.read_text path=`path` *
> print text=`s2`
+207 -4
View File
@@ -85,6 +85,14 @@ fn structure_branch() {
assert_out("tests/structure/branch.mq.md", "零");
}
#[test]
fn structure_branch_consecutive() {
assert_out(
"tests/structure/branch-consecutive.mq.md",
"A\nB\nelse-ok",
);
}
#[test]
fn structure_loop() {
assert_out(
@@ -452,6 +460,15 @@ fn bytecode_branch() {
assert_out_backend("tests/structure/branch.mq.md", "bytecode", "零");
}
#[test]
fn bytecode_branch_consecutive() {
assert_out_backend(
"tests/structure/branch-consecutive.mq.md",
"bytecode",
"A\nB\nelse-ok",
);
}
#[test]
fn bytecode_loop() {
assert_out_backend(
@@ -591,10 +608,92 @@ fn catalog_writes_yaml() {
assert!(yaml.contains("type: Marqdo Catalog"));
assert!(yaml.contains("structure/hello"));
assert!(yaml.contains("utils.mq.md"), "{yaml}");
assert!(yaml.contains("concepts:"), "{yaml}");
let index = std::fs::read_to_string(dir.join("index.md")).unwrap();
assert!(index.contains("## Modules"), "{index}");
assert!(index.contains("## Agent knowledge"), "{index}");
// Import graph: structure/import/main depends on utils — clickable on module page.
let import_page = std::fs::read_to_string(
dir.join("modules")
.join("structure__import__main.md"),
)
.unwrap();
assert!(
yaml.contains("???????") || yaml.contains("imports:
- utils.mq.md"),
"{yaml}"
import_page.contains("](") && import_page.contains("utils"),
"depends should link to utils module: {import_page}"
);
}
#[test]
fn ext_mq_md_never_calls_host() {
// Hard rule: ext/**/*.mq.md must not invoke host_* (use lib/* or plugin names).
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("ext");
let mut offenders = Vec::new();
fn walk(dir: &std::path::Path, out: &mut Vec<String>) {
let Ok(rd) = std::fs::read_dir(dir) else {
return;
};
for ent in rd.flatten() {
let p = ent.path();
if p.is_dir() {
walk(&p, out);
continue;
}
let name = p.file_name().and_then(|n| n.to_str()).unwrap_or("");
if !name.ends_with(".mq.md") {
continue;
}
let Ok(src) = std::fs::read_to_string(&p) else {
continue;
};
for (i, line) in src.lines().enumerate() {
let t = line.trim_start();
// Executable call lines / bindings that invoke host_*.
if (t.starts_with('>') || t.starts_with('*')) && t.contains("host_") {
out.push(format!("{}:{}: {line}", p.display(), i + 1));
}
}
}
}
walk(&root, &mut offenders);
assert!(
offenders.is_empty(),
"ext must not call host_* (use lib/* or agent_* plugin names):\n{}",
offenders.join("\n")
);
}
#[test]
fn catalog_includes_agent_kb_concepts() {
let dir = tempfile_dir("mq-cat-kb");
// Ensure a concept exists under tests/ext agent-kb (offline reuse test leaves one).
let (code, _, stderr) = run(&[
"run",
"tests/ext/agent-kb-reuse.mq.md",
]);
assert_eq!(code, 0, "seed kb via reuse test: {stderr}");
let (code, _, stderr) = run(&[
"catalog",
"tests/ext",
"-o",
dir.to_str().unwrap(),
]);
assert_eq!(code, 0, "{stderr}");
let yaml = std::fs::read_to_string(dir.join("catalog.yaml")).unwrap();
assert!(
yaml.contains("Marqdo Task") || yaml.contains("Marqdo Agent Skill"),
"expected agent-kb concepts in catalog: {yaml}"
);
assert!(
dir.join("concepts").join("tasks").exists()
|| dir.join("concepts").join("skills").exists(),
"concepts should be copied into catalog out dir"
);
let index = std::fs::read_to_string(dir.join("index.md")).unwrap();
assert!(
!index.contains("No `.marqdo/agent-kb` concepts"),
"{index}"
);
}
@@ -687,7 +786,7 @@ fn lib_writeback_get() {
#[test]
fn lib_subtask_spawn() {
assert_out("tests/lib/subtask-spawn.mq.md", "done");
assert_out("tests/lib/subtask-spawn.mq.md", "child-ok\ndone\nquiet-ok");
}
#[test]
@@ -874,6 +973,55 @@ fn ext_agent_framework_smoke() {
);
}
#[test]
fn ext_fs_text_patch() {
assert_out(
"tests/ext/fs-text-patch.mq.md",
"alpha BETA gamma\n2\nALPHA BETA GAMMA",
);
}
#[test]
fn ext_agent_inspect_workbook() {
assert_out(
"tests/ext/agent-inspect-fixture.mq.md",
"0\nok-slot\npending",
);
}
#[test]
fn ext_agent_plan_confirm() {
let status = Command::new("cargo")
.args(["build", "-p", "marqdo_plugin_agent"])
.current_dir(env!("CARGO_MANIFEST_DIR"))
.status()
.expect("build agent plugin");
assert!(status.success(), "failed to build marqdo_plugin_agent");
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/agent-plan-confirm.mq.md"])
.current_dir(env!("CARGO_MANIFEST_DIR"))
.output()
.expect("run agent-plan-confirm");
let code = output.status.code().unwrap_or(1);
let stdout = String::from_utf8_lossy(&output.stdout);
let stderr = String::from_utf8_lossy(&output.stderr);
assert_eq!(code, 0, "agent-plan-confirm stderr={stderr}");
assert_eq!(
stdout.trim_end(),
"pending\nworkbook-ok\nskeleton-ok",
"agent-plan-confirm"
);
}
#[test]
fn ext_agent_plan_decision() {
assert_out(
"tests/ext/agent-plan-decision.mq.md",
"DONE\nall good\nCONTINUE\nDONE\ndual-ok\nsolidify-ok\n1\nkeep new keep",
);
}
#[test]
fn ext_llm_complete_live() {
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
@@ -932,6 +1080,61 @@ fn ext_agent_run_live() {
"writeback must not be printed to stdout"
);
}
#[test]
fn ext_agent_plan_live() {
let status = Command::new("cargo")
.args(["build", "-p", "marqdo_plugin_agent"])
.current_dir(env!("CARGO_MANIFEST_DIR"))
.status()
.expect("build agent plugin");
assert!(status.success(), "failed to build marqdo_plugin_agent");
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/agent-plan-live.mq.md"])
.current_dir(env!("CARGO_MANIFEST_DIR"))
.output()
.expect("run agent-plan-live");
let code = output.status.code().unwrap_or(1);
let stdout = String::from_utf8_lossy(&output.stdout);
let stderr = String::from_utf8_lossy(&output.stderr);
assert_eq!(code, 0, "agent-plan-live stderr={stderr}");
let lines: Vec<&str> = stdout.trim_end().lines().collect();
assert!(
lines.iter().any(|l| *l == "ok"),
"agent-plan-live missing ok: stdout={stdout}"
);
assert!(
lines.iter().any(|l| *l == "workbook-ok"),
"agent-plan-live missing workbook-ok: stdout={stdout}"
);
assert!(
lines.iter().filter(|l| **l == "hit").count() >= 1,
"agent-plan-live expected OKF hit: stdout={stdout}"
);
}
#[test]
fn ext_agent_kb_reuse() {
let status = Command::new("cargo")
.args(["build", "-p", "marqdo_plugin_agent"])
.current_dir(env!("CARGO_MANIFEST_DIR"))
.status()
.expect("build agent plugin");
assert!(status.success(), "failed to build marqdo_plugin_agent");
let goal = "Reply with exactly the word pong and nothing else.";
let mut h: u64 = 5381;
for b in goal.as_bytes() {
h = h.wrapping_mul(33).wrapping_add(u64::from(*b));
}
let sig = format!("{h:016x}")[..12].to_string();
let slug = "reply-with-exactly-the-word-pong-and-nothing-els";
// Default file-subtask quiet: no child print on parent stdout; answer via wait.value.
let expect = format!("{sig}\n{slug}\npromoted\nstable\n{slug}\nlookup-ok\n0\npong\nstable-path");
assert_out("tests/ext/agent-kb-reuse.mq.md", &expect);
}
#[test]
fn lib_net_encode() {
assert_out("tests/lib/net-encode.mq.md", "a+b");
+1 -1
View File
@@ -4,4 +4,4 @@ title: subtask child
# main
> print text=child-ok
**child_ok**
+24 -2
View File
@@ -1,12 +1,34 @@
---
title: subtask spawn join
> lib/subtask.mq.md
> lib/json.mq.md
---
# main
*`id` = > subtask.spawn path=subtask-child.mq.md *
*`id` = > subtask.spawn path=subtask-child.mq.md quiet=False *
*`code` = > subtask.wait id=`id` *
*`waited` = > subtask.wait id=`id` *
*`code` = > json.get value=`waited` key=code *
*`val` = > json.get value=`waited` key=value *
1. `code` == 0
> print text=`val`
2. *
> print text=fail
> print text=done
*`id2` = > subtask.spawn path=subtask-child.mq.md *
*`waited2` = > subtask.wait id=`id2` *
*`code2` = > json.get value=`waited2` key=code *
*`val2` = > json.get value=`waited2` key=value *
1. `code2` == 0
1. `val2` == "child-ok"
> print text=quiet-ok
2. *
> print text=quiet-bad-value
2. *
> print text=quiet-fail
+24
View File
@@ -0,0 +1,24 @@
---
title: consecutive branches restart at 1.
description: Same-indent `1.` after a completed list is a new Branch, not more arms.
---
# main
*`a` = True*
*`b` = True*
1. `a`
> print text=A
2. *
> print text=not-A
1. `b`
> print text=B
2. *
> print text=not-B
1. False
> print text=no
2. *
> print text=else-ok