From d1b33c78c6f41561bddfd7091d2835d05e9fabdb Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 7 Aug 2026 17:53:14 +0800 Subject: [PATCH] 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 --- .cursor/skills/marqdo/SKILL.md | 5 +- .cursor/skills/marqdo/examples.md | 9 + .cursor/skills/marqdo/reference.md | 2 +- .gitignore | 1 + Cargo.lock | 3 +- doc/README.md | 5 +- doc/design/catalog-cli.md | 65 +- doc/design/ext-abi.md | 9 +- doc/design/ext-agent-plan.md | 101 ++- doc/design/ext-agent.md | 18 +- doc/design/generated-yaml-manifest.md | 4 +- doc/design/markdown-mapping.md | 18 +- doc/design/module-namespace.md | 6 +- doc/design/okf.md | 468 ++++++++++++++ doc/design/stdlib-subtask.md | 8 +- doc/research/okf-and-marqdo.md | 2 +- ext/ai/agent.mq.md | 532 +++++++++++++++- ext/ai/智能体.mq.md | 25 +- lib/fs.mq.md | 17 + lib/subtask.mq.md | 6 +- lib/writeback.mq.md | 7 + lib/子任务.mq.md | 6 +- lib/文件.mq.md | 17 + lib/自写回.mq.md | 7 + man-test/ext/agent-plan.mq.md | 22 + plugins/agent/Cargo.toml | 1 + plugins/agent/src/kb.rs | 760 +++++++++++++++++++++++ plugins/agent/src/lib.rs | 73 ++- public/stdlib/subtask.mq.md | 2 +- public/stdlib/子任务.mq.md | 2 +- skills/marqdo/SKILL.md | 2 +- skills/marqdo/examples.md | 9 + skills/marqdo/reference.md | 2 +- src/catalog.rs | 375 ++++++++++- src/host/dispatch.rs | 27 +- src/host/fs.rs | 185 ++++++ src/host/mod.rs | 4 +- src/host/plugin.rs | 3 + src/host/subtask.rs | 94 ++- src/host/writeback.rs | 18 +- src/lib.rs | 22 +- src/load.rs | 26 +- src/main.rs | 7 + src/parse/expr.rs | 98 ++- src/parse/mod.rs | 84 ++- tests/ext/agent-inspect-fixture.mq.md | 30 + tests/ext/agent-kb-reuse.mq.md | 67 ++ tests/ext/agent-plan-confirm.mq.md | 36 ++ tests/ext/agent-plan-decision.mq.md | 48 ++ tests/ext/agent-plan-live.mq.md | 43 ++ tests/ext/fs-text-patch.mq.md | 23 + tests/gold.rs | 211 ++++++- tests/lib/subtask-child.mq.md | 2 +- tests/lib/subtask-spawn.mq.md | 26 +- tests/structure/branch-consecutive.mq.md | 24 + 55 files changed, 3498 insertions(+), 169 deletions(-) create mode 100644 doc/design/okf.md create mode 100644 man-test/ext/agent-plan.mq.md create mode 100644 plugins/agent/src/kb.rs create mode 100644 tests/ext/agent-inspect-fixture.mq.md create mode 100644 tests/ext/agent-kb-reuse.mq.md create mode 100644 tests/ext/agent-plan-confirm.mq.md create mode 100644 tests/ext/agent-plan-decision.mq.md create mode 100644 tests/ext/agent-plan-live.mq.md create mode 100644 tests/ext/fs-text-patch.mq.md create mode 100644 tests/structure/branch-consecutive.mq.md diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 91cbfda..dbcc6f3 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -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) | diff --git a/.cursor/skills/marqdo/examples.md b/.cursor/skills/marqdo/examples.md index 8c1e2a4..0db0205 100644 --- a/.cursor/skills/marqdo/examples.md +++ b/.cursor/skills/marqdo/examples.md @@ -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 ``` diff --git a/.cursor/skills/marqdo/reference.md b/.cursor/skills/marqdo/reference.md index b5b95c2..2ea9a30 100644 --- a/.cursor/skills/marqdo/reference.md +++ b/.cursor/skills/marqdo/reference.md @@ -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. diff --git a/.gitignore b/.gitignore index 806411f..4282030 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,7 @@ *.pdb .DS_Store .marqdo/ +**/.marqdo/ .env # Generated HTML beside tracked public/*.mq.md (sources stay in git) diff --git a/Cargo.lock b/Cargo.lock index f9f23cf..bbb4113 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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", ] diff --git a/doc/README.md b/doc/README.md index 91d679d..285ce75 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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/`)** | diff --git a/doc/design/catalog-cli.md b/doc/design/catalog-cli.md index e9312e1..76788ce 100644 --- a/doc/design/catalog-cli.md +++ b/doc/design/catalog-cli.md @@ -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/ - .md # 每个 .mq.md 一个概念页(frontmatter + 摘要) + .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/` | -不在 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` 行为一致。 diff --git a/doc/design/ext-abi.md b/doc/design/ext-abi.md index 8de51e1..510a649 100644 --- a/doc/design/ext-abi.md +++ b/doc/design/ext-abi.md @@ -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 diff --git a/doc/design/ext-agent-plan.md b/doc/design/ext-agent-plan.md index 7df5c0e..f68b9b0 100644 --- a/doc/design/ext-agent-plan.md +++ b/doc/design/ext-agent-plan.md @@ -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. **允许工作簿在「跑 → 看结果 → 改代码 / 改写回 → 再跑」中演化**——既更新可执行语句,也更新 ``。 -4. **父智能体持有与单步同等级的上下文**(源码、Skill、调用位置、历史),并能创建 / 修改 / 再执行工作簿。 -5. **能固化的步骤尽量固化为 Marqdo 代码**;仅不确定分支继续交给子智能体。 +3. **父智能体作为「智能体开发大师」**:结构化读取执行结果与写回,再二次规划;用**精确补丁**改工作簿代码,并把确定步骤**固化为普通 Marqdo `##`**。 +4. **允许工作簿演化**——代码与 `` 均可更新,但**禁止**以整文件 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、位置、历史与工作簿观察面**,二次规划后以**精确补丁**修改再执行(禁止整文件重写主路径)。 --- diff --git a/doc/design/ext-agent.md b/doc/design/ext-agent.md index b52aa34..993d692 100644 --- a/doc/design/ext-agent.md +++ b/doc/design/ext-agent.md @@ -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** | ### 非目标 diff --git a/doc/design/generated-yaml-manifest.md b/doc/design/generated-yaml-manifest.md index 86abae4..7b038a5 100644 --- a/doc/design/generated-yaml-manifest.md +++ b/doc/design/generated-yaml-manifest.md @@ -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) 为准** | --- ## 决策 diff --git a/doc/design/markdown-mapping.md b/doc/design/markdown-mapping.md index 483bcbe..0986388 100644 --- a/doc/design/markdown-mapping.md +++ b/doc/design/markdown-mapping.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=今天吃`果` diff --git a/doc/design/module-namespace.md b/doc/design/module-namespace.md index 6f8b3d6..cd740f5 100644 --- a/doc/design/module-namespace.md +++ b/doc/design/module-namespace.md @@ -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)。 --- diff --git a/doc/design/okf.md b/doc/design/okf.md new file mode 100644 index 0000000..fa916c1 --- /dev/null +++ b/doc/design/okf.md @@ -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 +/ + 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/ + .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/ +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/ + # type: Marqdo Task + # title: … + # status: … + # page: concepts/tasks/.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/ +# 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--.mq.md # 仅当显式 workbook_dir= 时(可 gc) + agent-kb/ # 任务知识包 bundle(默认首次 plan 就写这里) + index.md + log.md # 可选 + catalog.yaml # 可选;可由 promote 或 catalog 刷新 + concepts/ + tasks/.md # type: Marqdo Task;sig 在 frontmatter + skills/.md # type: Marqdo Agent Skill + resources/ + .mq.md # 默认可执行工作簿(探索与晋升同一路径) +``` + +默认根可通过 `plan` 参数 `kb_dir` / `知识库目录` 覆盖。`.gitignore` 已忽略 `**/.marqdo/`。 + +路径用可读 **slug**(由 goal 派生:拉丁小写、CJK 保留、其它变 `-`,最长约 48 字符)。**`sig` 仅写在 frontmatter**,用于精确匹配。同 slug 异 sig 时用 `slug-`。旧包若仍以 `` 为文件名,lookup 会回退识别。 + +### 7.2 概念页模板 + +**Task**(匹配入口): + +```yaml +--- +type: Marqdo Task +title: <短摘要> +description: <规范化 goal> +sig: <12hex> +status: stable +tags: [agent-task] +skill: ../skills/.md +generated: + by: marqdo-agent/plan +verified: + by: marqdo-agent/spawn + at: +--- + +# Task + +See [skill](../skills/.md). +``` + +**Skill**(可执行绑定): + +```yaml +--- +type: Marqdo Agent Skill +title: <短名> +sig: <12hex> +resource: ../../resources/.mq.md +status: stable | candidate +llm_free: true | false +quality: +hits: +generated: + by: marqdo-agent/plan + at: +verified: + by: marqdo-agent/spawn + at: +--- + +# 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/.md` +- `concepts/skills/.md` +- `resources/.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/.mq.md`;显式传入则用该目录下的临时 `workbook--.mq.md` | +| `improve_every` / `改进周期` | `3` | candidate 每 N 次命中触发 ≤1 轮改进 | +| `explore_n` / `探索次数` | `3` | 同任务已有文件数 `< N` 且非 `llm_free` 时,强制新建 `explore//.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/.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 分管工程目录与自我成长。** diff --git a/doc/design/stdlib-subtask.md b/doc/design/stdlib-subtask.md index 9e0a037..fdd9fa8 100644 --- a/doc/design/stdlib-subtask.md +++ b/doc/design/stdlib-subtask.md @@ -9,15 +9,17 @@ **并发**执行单元。`spawn` 四选一: -| 参数 | 执行方式 | `join` 返回值 | -|------|----------|---------------| -| `path=` | `marqdo run ` 子进程 | 退出码 `Int` | +| 参数 | 执行方式 | `join` / `wait` 返回值 | +|------|----------|------------------------| +| `path=` | `marqdo run --emit-result ` 子进程 | 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`。 diff --git a/doc/research/okf-and-marqdo.md b/doc/research/okf-and-marqdo.md index 67200e0..8f25e17 100644 --- a/doc/research/okf-and-marqdo.md +++ b/doc/research/okf-and-marqdo.md @@ -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(后期)** — 文档内求值结果的可验证性。 diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index c9f17e8..cc37b61 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -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: \nOR\nDECISION: CONTINUE\nPATCH:\n<<<\nFIND\n\n===\nREPLACE\n\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/.mq.md`. While task file count `< explore_n` and skill is not llm_free, force a new explore variant under `kb_dir/explore//`. 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`** diff --git a/ext/ai/智能体.mq.md b/ext/ai/智能体.mq.md index 3f6793d..fccbefa 100644 --- a/ext/ai/智能体.mq.md +++ b/ext/ai/智能体.mq.md @@ -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/.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=`探索次数`** diff --git a/lib/fs.mq.md b/lib/fs.mq.md index 78aca38..2e7aa35 100644 --- a/lib/fs.mq.md +++ b/lib/fs.mq.md @@ -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`** diff --git a/lib/subtask.mq.md b/lib/subtask.mq.md index 7e8af31..d53cb04 100644 --- a/lib/subtask.mq.md +++ b/lib/subtask.mq.md @@ -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` diff --git a/lib/writeback.mq.md b/lib/writeback.mq.md index c1e4ed8..0b7ea9f 100644 --- a/lib/writeback.mq.md +++ b/lib/writeback.mq.md @@ -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 `` slots in any file (workbook inspection). + +**> host_writeback_scan_path path=`path`** diff --git a/lib/子任务.mq.md b/lib/子任务.mq.md index 8ee8afe..bf86773 100644 --- a/lib/子任务.mq.md +++ b/lib/子任务.mq.md @@ -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` diff --git a/lib/文件.mq.md b/lib/文件.mq.md index 1505148..bc6181e 100644 --- a/lib/文件.mq.md +++ b/lib/文件.mq.md @@ -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=`文本`** diff --git a/lib/自写回.mq.md b/lib/自写回.mq.md index f357194..1d40170 100644 --- a/lib/自写回.mq.md +++ b/lib/自写回.mq.md @@ -43,3 +43,10 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回) ## 列出 **> host_writeback_list** + +## 扫描路径 + + `路径` + +扫描任意文件中的 `` 槽(工作簿观察)。 + +**> host_writeback_scan_path path=`路径`** diff --git a/man-test/ext/agent-plan.mq.md b/man-test/ext/agent-plan.mq.md new file mode 100644 index 0000000..c968f84 --- /dev/null +++ b/man-test/ext/agent-plan.mq.md @@ -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` diff --git a/plugins/agent/Cargo.toml b/plugins/agent/Cargo.toml index 858f371..a5e4910 100644 --- a/plugins/agent/Cargo.toml +++ b/plugins/agent/Cargo.toml @@ -12,3 +12,4 @@ crate-type = ["cdylib"] [dependencies] serde_json = "1" +chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } diff --git a/plugins/agent/src/kb.rs b/plugins/agent/src/kb.rs new file mode 100644 index 0000000..e0bb610 --- /dev/null +++ b/plugins/agent/src/kb.rs @@ -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 = 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 { + 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::() + ); + 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 { + 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 { + let goal = arg_text(args, "goal")?; + Ok(Value::String(goal_slug_str(goal))) +} + +pub fn kb_lookup(args: &Value) -> Result { + 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::().ok()) + .unwrap_or(0); + let hits = extract_fm_field(&skill_src, "hits") + .and_then(|s| s.parse::().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 { + 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::().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 { + 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::().ok()) + .unwrap_or(0); + let old_q = extract_fm_field(&old, "quality") + .and_then(|s| s.parse::().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 { + 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 { + 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 { + 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 { + 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 = 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); + } +} diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 47b1f92..8e2d29d 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -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 { +pub(crate) fn host_query_json(name: &str) -> Result { 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 } diff --git a/public/stdlib/subtask.mq.md b/public/stdlib/subtask.mq.md index ed401cb..0780863 100644 --- a/public/stdlib/subtask.mq.md +++ b/public/stdlib/subtask.mq.md @@ -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 diff --git a/public/stdlib/子任务.mq.md b/public/stdlib/子任务.mq.md index f74f1ba..2fa0354 100644 --- a/public/stdlib/子任务.mq.md +++ b/public/stdlib/子任务.mq.md @@ -15,6 +15,6 @@ description: 文件、函数或外联代码并行执行 | `代码=` | 外联代码块子进程 | stdout 文本 | | `语言=` + `源码=` | 外联源码子进程 | stdout 文本 | -另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。 +文件子任务默认静默;`静默=假` 时继承父终端。另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。 > 打印 内容=子任务总览就绪 diff --git a/skills/marqdo/SKILL.md b/skills/marqdo/SKILL.md index 8b1f108..e41b654 100644 --- a/skills/marqdo/SKILL.md +++ b/skills/marqdo/SKILL.md @@ -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) | diff --git a/skills/marqdo/examples.md b/skills/marqdo/examples.md index 8c1e2a4..0db0205 100644 --- a/skills/marqdo/examples.md +++ b/skills/marqdo/examples.md @@ -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 ``` diff --git a/skills/marqdo/reference.md b/skills/marqdo/reference.md index b5b95c2..2ea9a30 100644 --- a/skills/marqdo/reference.md +++ b/skills/marqdo/reference.md @@ -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. diff --git a/src/catalog.rs b/src/catalog.rs index b38801d..46a5add 100644 --- a/src/catalog.rs +++ b/src/catalog.rs @@ -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, exports: Vec, + /// Optional OKF trust fields copied from source frontmatter. + verified_by: Option, + sources: Vec, +} + +struct ConceptInfo { + /// Relative id e.g. `concepts/tasks/` + id: String, + concept_type: String, + title: String, + status: String, + resource: Option, + skill: Option, + description: Option, + verified_by: Option, + /// 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) -> 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, +) -> 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) -> Result<()> Ok(()) } +/// Find `**/.marqdo/agent-kb/concepts/**/*.md` under scan root. +fn collect_agent_concepts( + root: &Path, + out_canon: &Path, + out: &mut Vec, +) -> Result<()> { + walk_for_concepts(root, root, out_canon, out) +} + +fn walk_for_concepts( + root: &Path, + dir: &Path, + out_canon: &Path, + out: &mut Vec, +) -> 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 { 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 { title, imports, exports, + verified_by, + sources, }) } @@ -165,23 +311,100 @@ fn extract_frontmatter_imports(source: &str) -> Vec { } fn extract_frontmatter_title(source: &str) -> Option { + extract_fm_field(source, "title") +} + +fn extract_fm_field(source: &str, key: &str) -> Option { 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 { + 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 { + 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::>() + .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'); } diff --git a/src/host/dispatch.rs b/src/host/dispatch.rs index af8cbf1..0685929 100644 --- a/src/host/dispatch.rs +++ b/src/host/dispatch.rs @@ -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")?, diff --git a/src/host/fs.rs b/src/host/fs.rs index eacda34..13dadb4 100644 --- a/src/host/fs.rs +++ b/src/host/fs.rs @@ -106,3 +106,188 @@ pub fn remove(ctx: &HostContext, path: &Value) -> Result { } 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 { + 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 +/// +/// === +/// REPLACE +/// +/// >>> +/// ``` +pub fn apply_patch_blocks(ctx: &HostContext, path: &Value, text: &Value) -> Result { + 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, 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 { + 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); + } +} diff --git a/src/host/mod.rs b/src/host/mod.rs index dbe52ec..a291755 100644 --- a/src/host/mod.rs +++ b/src/host/mod.rs @@ -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, /// Concurrent subtasks (`lib/subtask`): file / function / foreign. - pub subtasks: HashMap, + pub(crate) subtasks: HashMap, pub subtask_seq: u64, } diff --git a/src/host/plugin.rs b/src/host/plugin.rs index 8bed612..5c8d4bd 100644 --- a/src/host/plugin.rs +++ b/src/host/plugin.rs @@ -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}`")), }; diff --git a/src/host/subtask.rs b/src/host/subtask.rs index 3ea97cf..08e8043 100644 --- a/src/host/subtask.rs +++ b/src/host/subtask.rs @@ -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, @@ -44,7 +49,7 @@ enum FnState { Killed, } -struct FunctionTask { +pub(crate) struct FunctionTask { state: Arc>, handle: Option>, } @@ -121,9 +126,10 @@ fn fn_args_from_value(args: Option<&Value>) -> Result, 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) -> Result, + quiet: Option<&Value>, ) -> Result { 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 { .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 { .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::(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 { let status = task .child @@ -428,9 +487,12 @@ pub fn kill(ctx: &mut HostContext, id: &Value) -> Result { .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}"))?; diff --git a/src/host/writeback.rs b/src/host/writeback.rs index 4fb6c1b..0e43cb1 100644 --- a/src/host/writeback.rs +++ b/src/host/writeback.rs @@ -528,6 +528,22 @@ pub fn list(ctx: &HostContext) -> Result { .entry_source .as_deref() .ok_or_else(|| "writeback: no entry source".to_string())?; + Ok(slots_from_source(source)) +} + +/// Scan `path` for `` slots (any file, not only the entry). +pub fn scan_path(ctx: &HostContext, path: &Value) -> Result { + 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 = scan_blocks(source) .into_iter() .map(|b| { @@ -544,7 +560,7 @@ pub fn list(ctx: &HostContext) -> Result { 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. diff --git a/src/lib.rs b/src/lib.rs index d016c7d..1e9bcf3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -75,6 +75,8 @@ pub struct RunOptions { pub fs_root: Option, /// Sleep clamp when capturing (None = host default; view export uses `Some(0)`). pub sleep_limit_ms: Option, + /// When set, write `# main` return value as JSON to this path (file subtasks). + pub emit_result: Option, } 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 { 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 { 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 { 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 { let source = std::fs::read_to_string(path) diff --git a/src/load.rs b/src/load.rs index fd5cc63..aa45460 100644 --- a/src/load.rs +++ b/src/load.rs @@ -107,12 +107,17 @@ pub fn resolve_import(from_dir: &Path, rel: &str) -> Result { 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 { 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 { 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 { + 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 { let mut roots = Vec::new(); if let Ok(h) = env::var("MARQDO_LIB") { diff --git a/src/main.rs b/src/main.rs index 3e613d1..d2ffb94 100644 --- a/src/main.rs +++ b/src/main.rs @@ -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, + + /// Write `# main` return value as JSON (used by file subtasks). + #[arg(long, value_name = "FILE")] + emit_result: Option, }, /// Browse `.mq.md` structure + execution (live server or static output) View { @@ -177,6 +181,7 @@ fn try_main() -> Result { 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 { 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 { trace_eval, backend: backend.into(), stdin_lines, + emit_result, ..RunOptions::default() } }; diff --git a/src/parse/expr.rs b/src/parse/expr.rs index 448878b..736a494 100644 --- a/src/parse/expr.rs +++ b/src/parse/expr.rs @@ -16,11 +16,18 @@ pub fn parse_expr(input: &str) -> Result { /// 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 { 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 { } } +/// 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 { + 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 = 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 { )); } } + + diff --git a/src/parse/mod.rs b/src/parse/mod.rs index 69a5dca..6801824 100644 --- a/src/parse/mod.rs +++ b/src/parse/mod.rs @@ -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 { 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 { + 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"; diff --git a/tests/ext/agent-inspect-fixture.mq.md b/tests/ext/agent-inspect-fixture.mq.md new file mode 100644 index 0000000..eb86835 --- /dev/null +++ b/tests/ext/agent-inspect-fixture.mq.md @@ -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\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` diff --git a/tests/ext/agent-kb-reuse.mq.md b/tests/ext/agent-kb-reuse.mq.md new file mode 100644 index 0000000..17563cd --- /dev/null +++ b/tests/ext/agent-kb-reuse.mq.md @@ -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 diff --git a/tests/ext/agent-plan-confirm.mq.md b/tests/ext/agent-plan-confirm.mq.md new file mode 100644 index 0000000..03c0fb2 --- /dev/null +++ b/tests/ext/agent-plan-confirm.mq.md @@ -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 diff --git a/tests/ext/agent-plan-decision.mq.md b/tests/ext/agent-plan-decision.mq.md new file mode 100644 index 0000000..afec892 --- /dev/null +++ b/tests/ext/agent-plan-decision.mq.md @@ -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` diff --git a/tests/ext/agent-plan-live.mq.md b/tests/ext/agent-plan-live.mq.md new file mode 100644 index 0000000..776ff1f --- /dev/null +++ b/tests/ext/agent-plan-live.mq.md @@ -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` diff --git a/tests/ext/fs-text-patch.mq.md b/tests/ext/fs-text-patch.mq.md new file mode 100644 index 0000000..376a895 --- /dev/null +++ b/tests/ext/fs-text-patch.mq.md @@ -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` diff --git a/tests/gold.rs b/tests/gold.rs index 180a6bd..5cf5e4d 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -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) { + 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"); diff --git a/tests/lib/subtask-child.mq.md b/tests/lib/subtask-child.mq.md index 45247a9..dc63ead 100644 --- a/tests/lib/subtask-child.mq.md +++ b/tests/lib/subtask-child.mq.md @@ -4,4 +4,4 @@ title: subtask child # main -> print text=child-ok +**child_ok** diff --git a/tests/lib/subtask-spawn.mq.md b/tests/lib/subtask-spawn.mq.md index 4cee48d..910fd1f 100644 --- a/tests/lib/subtask-spawn.mq.md +++ b/tests/lib/subtask-spawn.mq.md @@ -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 diff --git a/tests/structure/branch-consecutive.mq.md b/tests/structure/branch-consecutive.mq.md new file mode 100644 index 0000000..a099f4b --- /dev/null +++ b/tests/structure/branch-consecutive.mq.md @@ -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