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:
1 parent
fbece725e1
commit
d1b33c78c6
55 files changed
+3498
-169
No files matched your search
@@ -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) |
|
||||
|
||||
@@ -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
|
||||
```
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -22,6 +22,7 @@
|
||||
*.pdb
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
**/.marqdo/
|
||||
.env
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
|
||||
Generated
+2
-1
@@ -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
@@ -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
@@ -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` 行为一致。
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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** |
|
||||
|
||||
### 非目标
|
||||
|
||||
|
||||
@@ -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) 为准** |
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
@@ -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=今天吃`果`
|
||||
|
||||
@@ -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)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 分管工程目录与自我成长。**
|
||||
@@ -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`。
|
||||
|
||||
@@ -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
@@ -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
@@ -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=`探索次数`**
|
||||
@@ -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
@@ -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`
|
||||
|
||||
@@ -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
@@ -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`
|
||||
|
||||
@@ -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=`文本`**
|
||||
@@ -43,3 +43,10 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
## 列出
|
||||
|
||||
**> host_writeback_list**
|
||||
|
||||
## 扫描路径
|
||||
+ `路径`
|
||||
|
||||
扫描任意文件中的 `<!-- marqdo-out … -->` 槽(工作簿观察)。
|
||||
|
||||
**> host_writeback_scan_path path=`路径`**
|
||||
@@ -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`
|
||||
@@ -12,3 +12,4 @@ crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -15,6 +15,6 @@ description: 文件、函数或外联代码并行执行
|
||||
| `代码=` | 外联代码块子进程 | stdout 文本 |
|
||||
| `语言=` + `源码=` | 外联源码子进程 | stdout 文本 |
|
||||
|
||||
另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。
|
||||
文件子任务默认静默;`静默=假` 时继承父终端。另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。
|
||||
|
||||
> 打印 内容=子任务总览就绪
|
||||
@@ -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) |
|
||||
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,
|
||||
}
|
||||
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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") {
|
||||
|
||||
@@ -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
@@ -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
@@ -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";
|
||||
|
||||
@@ -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`
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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`
|
||||
@@ -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`
|
||||
@@ -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
@@ -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");
|
||||
|
||||
@@ -4,4 +4,4 @@ title: subtask child
|
||||
|
||||
# main
|
||||
|
||||
> print text=child-ok
|
||||
**child_ok**
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in new issue
Block a user