Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
142ab523d6 | ||
|
|
82c8d78fd3 | ||
|
|
58791fc7d9 | ||
|
|
1730f26fc7 | ||
|
|
4018e9928a | ||
|
|
628e3b6e5d | ||
|
|
5c6c612edd | ||
|
|
41587f319e | ||
|
|
298fbd51ea | ||
|
|
265dfdbcc4 | ||
|
|
42a43f5ffd | ||
|
|
037a963547 | ||
|
|
a32638e935 | ||
|
|
43eebe5671 | ||
|
|
e833dc05e2 | ||
|
|
11bb7ef277 | ||
|
|
6bd90bb2d0 | ||
|
|
4683f2e067 | ||
|
|
5912164039 | ||
|
|
303c06f773 | ||
|
|
a1086fd6c3 | ||
|
|
6ffe5ceb19 | ||
|
|
6b568aff3d | ||
|
|
16f26d7d60 | ||
|
|
b8265a92aa | ||
|
|
9af929971c | ||
|
|
2c4fa4bb05 |
No files matched your search
@@ -21,7 +21,7 @@ Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation a
|
||||
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
|
||||
|
||||
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
|
||||
2. **`**…**` = code / return expression.** `*…*` = statement (bind / expr). Closing markers touch the last token (no trailing space).
|
||||
2. **`**…**` = statement** (assign / call / expression). `*…*` = return. Closing markers touch the last token (no trailing space).
|
||||
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
|
||||
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
|
||||
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
|
||||
@@ -34,8 +34,8 @@ These rules are the **current default**. Do **not** teach Classic `[key](map)` i
|
||||
| Marker | Meaning (v2.1) |
|
||||
|--------|----------------|
|
||||
| `#` / `##`+ | Object/type · function/method |
|
||||
| `*…*` | Statement |
|
||||
| `**…**` | Return / code expression |
|
||||
| `**…**` | Statement (assign / call / expression) |
|
||||
| `*…*` | Return |
|
||||
| `[描述](payload)` | Occlusion step (payload executes) |
|
||||
| `access(c, k)` | Collection read |
|
||||
| `> fn …` | Call |
|
||||
@@ -57,6 +57,24 @@ Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executabl
|
||||
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
|
||||
|
||||
|
||||
## Call one function
|
||||
|
||||
```markdown
|
||||
# 计算器
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
```
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
prints `5`. The same command works on any `.mq.md`; the file does not need a special skill name.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
@@ -96,13 +114,13 @@ Chinese builtins (same functions, no import):
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
**x = 1**
|
||||
**y = x + 2**
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
```markdown
|
||||
@@ -130,9 +148,9 @@ import:
|
||||
|
||||
# main
|
||||
|
||||
*xs = > text.split value="a,b,c" sep=","*
|
||||
**xs = > text.split value="a,b,c" sep=","**
|
||||
> print text=`xs`
|
||||
*t = > clock.now_unix*
|
||||
**t = > clock.now_unix**
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
|
||||
@@ -191,8 +209,8 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
|
||||
|
||||
```markdown
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="probs" theme="light"*
|
||||
**_ = > `qc`.draw kind="circuit" theme="dark"**
|
||||
**_ = > `qc`.draw kind="probs" theme="light"**
|
||||
```
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
@@ -203,7 +221,7 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
|
||||
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
|
||||
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
|
||||
- `session_open` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`.
|
||||
- `session_open` returns an opaque `handle` (not text; not JSON-serializable). `session_eval` / `set` / `get` borrow the handle; `session_close` consumes it (double-close / use-after-close fault). Prefer `replay_check` against the oracle journal when comparing recordings (`replay_snapshot` only re-runs). JSON integers outside \(\pm(2^{53}-1)\) and ragged table columns are refused (`doc/design/v-safe-json.md`, `foreign-strong-correspondence.md`).
|
||||
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
|
||||
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
|
||||
|
||||
@@ -223,8 +241,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `**a = 1**` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (italic is return, and bare text args) | `**xs = > text.split value="a,b" sep=","**` — statement; quote text literals |
|
||||
| Forgetting empty return after nested `##` helper when outer continues | Add `*None*` / `**` / `****` (not `---`) |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
|
||||
@@ -126,9 +126,20 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v2.3.0**:Foreign Strong——不透明 `handle`、仿射 close、`replay_check`/oracle journal、表 arity refuse、Ω∈V_safe
|
||||
- **v2.3.0**: Foreign Strong — opaque handle, affine close, replay_check/oracle journal, table arity refuse, Ω∈V_safe
|
||||
- **v2.3.0 ext**:扩展包同步 2.3.0 / Ext pack 2.3.0
|
||||
- **v2.2.1**:view / 静态导出——修复 occlusion 与中等宽度下大纲侧栏掉到正文下方
|
||||
- **v2.2.1**: view / static export — fix outline rail nested under document (occlusion + mid-width layout)
|
||||
- **v2.2.1 ext**:扩展包同步 2.2.1 / Ext pack 2.2.1
|
||||
- **v2.2.0**:函数级调用 `marqdo call`——同一份 .mq.md 就是文档、知识和工具;Tree/Bytecode 执行被点名的函数;外部调用默认只跑纯函数
|
||||
- **v2.2.0**: `marqdo call` runs one function in any .mq.md — the file is the document, the knowledge and the tool; Tree and Bytecode execute that function; external calls stay pure
|
||||
- **v2.2.0 ext**:扩展包同步 2.2.0 / Ext pack 2.2.0
|
||||
- **v2.1.5**:Agent 可靠工作台——ResourceView / ToolSpec / CheckpointV2 / EffectLedger · EKC ir.json 暖机 · Web 短读槽隔离
|
||||
- **v2.1.5**: Agent reliability workbench — ResourceView / ToolSpec / CheckpointV2 / EffectLedger, EKC ir.json warm-load, web short/read lane isolation
|
||||
- **v2.1.5 ext**:扩展包同步 2.1.5 / Ext pack 2.1.5
|
||||
- **v2.1.4**:默认隔离 HTTP execute(ADR 0009)——worker 池 / `--call-lib-path` · `/_runtime/*` · MR-01 双流金样例 · `runtime.isolated_execution=1`
|
||||
- **v2.1.4**: Default isolated HTTP execute (ADR 0009) — worker pool / `--call-lib-path`, `/_runtime/*`, MR-01 dual-stream gold, `runtime.isolated_execution=1`
|
||||
- **v2.1.4 ext**:扩展包同步 2.1.4 / Ext pack 2.1.4
|
||||
- **v2.1.3**:知识工作台运行时——ModelSelection/RunContext/usage · view document 只读嵌入 · LLM selection/messages/cancel · agent selection e2e
|
||||
- **v2.1.3**: Workbench runtime — ModelSelection/RunContext/usage, view document read-only embed, LLM selection/messages/cancel, agent selection e2e
|
||||
- **v2.1.1**:可执行知识主链——BoundCall · NarrativeRef · 来源/适用期 · patch/extract · 整代 CURRENT + closure · 发票示例 113
|
||||
|
||||
+131
@@ -8,6 +8,137 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v2.3.0 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**Foreign Strong(session / value / replay)**:会话句柄改为不透明 `handle`(不可 JSON 过桥、禁止 text 伪造);`close` 仿射消费(双 close / use-after-close 故障);`replay_check` 对照 oracle journal(旧 `replay_snapshot` 仅重跑保留);GFM 表行 arity 与列长映射拒绝静默补空;Ω 返回域外整数故障。对齐 PLDI Strong 叙事与 Lean SessionReg / \(V_{\mathsf{safe}}\)。CLI · wasm · ext **2.3.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——破坏面在宿主 foreign/session/JSON 与表解析纪律,不增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`Value::Handle`**:`session_open` 返回句柄;session 操作拒绝 text 伪造。
|
||||
- **`DocumentSession::replay_check`** + API `/api/session/snapshot/replay_check`;snapshot 录音字段 + **`oracle_journal`**(与 execution journal 分名)。
|
||||
- **API** `/api/session/oracle_journal`。
|
||||
- **文档**:`doc/design/foreign-strong-correspondence.md`;`v-safe-json.md` 补 Handle / 列 arity / Ω 门。
|
||||
- **回归**:`foreign-session-{use-before-open,use-after-close,double-close,cold-replay-empty,isolation,handle-no-serialize,result-vsafe-refuse}`;`tests/errors/table-arity.mq.md`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 不等宽 GFM 表不再静默补空单元格;解析报 `table row arity mismatch`。
|
||||
- Py/Node session bootstrap:Ω 结果 OOD 整数不再 `default=str` 偷渡,宿主升级为故障。
|
||||
|
||||
### Changed
|
||||
|
||||
- **`session_close`**:未知 / 已关闭句柄 → 故障(不再返回 `False`)。
|
||||
- **`session_list`**:`id` 字段为 `handle`。
|
||||
- Snapshot export 含 `ok`/`code`/`stdout`/`result`/`source_hash` 与 `oracle_journal`。
|
||||
|
||||
## v2.2.2 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**\(V_{\mathsf{safe}}\) JSON 整数契约落地**:外联 / `json.parse` / `json.stringify` / `session_set` 等共用映射对齐 Lean ForeignJSON——`|n| > 2^{53}-1` 的 JSON 整数显式拒绝(错误前缀 `json: integer outside V_safe`),禁止 Node 路径静默扭曲;宽整数仍用十进制字符串 + 对端 `BigInt`。CLI · wasm · ext **2.2.2**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——宿主 JSON 契约与测试,不改 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`doc/design/v-safe-json.md`**:宿主 ↔ Lean \(V_{\mathsf{safe}}\) 契约锁定(`MAX_SAFE`、encode/decode refuse、嵌套、float 为宿主扩展)。
|
||||
- **回归**:`tests/lib/json-vsafe-*`、`foreign-vsafe-*`、`foreign-session-vsafe-refuse`(含算术后越界 refuse)。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`src/host/json.rs`**:对域外整数与 `u64 > i64::MAX` 显式失败;不再经 `f64`/`Text` 静默降级。
|
||||
- **`doc/design/foreign-kernel.md`**:Int→number 仅当 `|n| ≤ 2^{53}-1`;宽整数走 string 桥。
|
||||
|
||||
### Changed
|
||||
|
||||
- 外联 JSON 桥与 `lib/json` 行为:OOD 整数从「可能静默失真」改为「诊断失败」。
|
||||
|
||||
## v2.2.1 — 2026-10-30
|
||||
|
||||
### Highlights
|
||||
|
||||
**view / 静态导出大纲侧栏修复**:带遮蔽(occlusion)语句的文档页里,Functions / Variables 右侧栏会掉到正文下面;中等窗口宽度下也会被错误叠成单列。CLI · wasm · ext **2.2.1**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——布局与 HTML 闭合修复,不改 Markdown 标记。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`marqdo view` / `view output`**:occlusion 行提前返回时未关闭 `.doc-block`,把 `#outline-rail` 嵌进 `document-surface`,侧栏排到文档下方;现已闭合并保留标注带。
|
||||
- **view 壳 CSS**:大纲折叠改为按主栏 `@container mq-panel` 宽度(32rem),不再用视口 `960px` 媒体查询把右侧栏压到正文下;极窄时大纲上移到文档上方。
|
||||
|
||||
## v2.2.0 — 2026-10-30
|
||||
|
||||
### Highlights
|
||||
|
||||
**函数级调用 `marqdo call`**:同一份 `.mq.md` 已经是文档、知识和程序。这一版补上从外部调用其中某个函数的入口。人继续读这一页;开发者、测试和 Agent 用同一条命令传入参数并执行。知识复用、把函数当工具、逐个函数做测试、改完再跑,都是这一入口的用法,不是另一套 Skill 系统。CLI · wasm · ext **2.2.0**。
|
||||
|
||||
```bash
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
# 5
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
|
||||
```
|
||||
|
||||
**作用**:最小可执行单位从「整份文件」扩展到「文件里的一个函数」。不必为了试一个函数再写 `# main`、打印和包装程序。
|
||||
|
||||
**价值**:说明和实现仍在同一页。Agent 读函数旁边的叙述,定位函数,传入参数,得到可检查的结果。正式发布和权限仍走已有的项目验证;`call` 默认不开放写文件、进程、网络和插件。
|
||||
|
||||
说明页:[public/features/22-函数调用.mq.md](public/features/22-函数调用.mq.md) · [public/features/22-call.mq.md](public/features/22-call.mq.md)
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——新增的是 CLI 入口,不新增 Markdown 标记。`**…**` 仍是语句,`*…*` 仍是返回。
|
||||
|
||||
### Added
|
||||
|
||||
- **`marqdo call <文件.mq.md> <函数> [名字=值 ...]`**:加载该文件及其 import,按显示路径、SymbolId 或唯一短名定位函数,用现有签名和契约绑定参数,再用现有运行时执行。
|
||||
- **`--json`**:成功 `{"ok":true,"result":...}`,失败 `{"ok":false,"error":...}`,错误带诊断 `code`。`--backend tree|bytecode` 与 `marqdo run` 相同;指定函数时两个后端都不会改去跑 `# main`。
|
||||
- **默认纯函数**:效应含写入、网络、进程或插件时,执行前返回 `artifact.effect_denied`,副作用不会发生。
|
||||
- **参照文档** `examples/calculator.mq.md`,以及用户说明页 `public/features/22-*`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 官方语法说明与 Agent 语法卡的标记极性与解析器对齐:粗体是语句,斜体是返回。同步测试会实际运行说明里的调用示例。
|
||||
- Bytecode 的 `marqdo run --call-lib-path` 执行被点名的导入函数,不再忽略该参数去跑入口。
|
||||
- 隔离运行时冒烟测试补上 `InvokeContext.fs_root`,`--tests` 可以编过。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.2.0**。扩展包版本号对齐;这一版的新能力在 CLI。
|
||||
|
||||
## v2.1.5 — 2026-10-27
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent 可靠工作台 + EKC 热路径**:ResourceView(JSON/CSV/PDF/image `blob_ref`、locator 页/行)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制面与 execute 槽隔离。CLI · wasm · ext **2.1.5**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.5 && cargo build --release
|
||||
marqdo ext add web # CDN / Releases → 2.1.5
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台协议与 Agent 运行时合同,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **ResourceView v1**:有界 JSON/CSV 渲染;PDF/image `blob_ref`;`locator.page` / 行定位;CSV `text` 供 TablePreview。
|
||||
- **Agent 合同**:ToolSpec 注册与 authorize-before-call;CheckpointV2 原子 resume;AgentErrorV1;输出通道;ContextPackV2;EffectLedger(含 mutating `run_tool` 水印)。
|
||||
- **Workbench fixtures/schemas**:`tests/workbench_contracts` 协议金样例。
|
||||
- **EKC `ir.json` 快照**:`marqdo knowledge` 写入 `.marqdo/ekc/graph/ir.json`;查询命令暖机热加载,免全量重编译。
|
||||
- **`--refresh`**:`knowledge preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify` 可强制重编译。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **工程预检热路径**:`knowledge preflight`(及 find/reuse 等)默认不再每次 `ensure_compiled` 全量 compile,修复聊天「工程预检」墙钟过长。
|
||||
- **Web 槽隔离**:`short`/`read`/`control` 不再填满 execute 槽;disconnect≠cancel。
|
||||
- **CSV ResourceView**:去掉尾部空行伪影。
|
||||
|
||||
### Changed
|
||||
|
||||
- 查询类 knowledge CLI:**缺投影才 compile**;CI / 源变更请先 `marqdo knowledge` 或 `--refresh`。
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.5**。
|
||||
|
||||
## v2.1.4 — 2026-10-26
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+2
-2
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "2.1.4"
|
||||
version = "2.3.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -611,7 +611,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.1.4"
|
||||
version = "2.3.0"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "2.1.4"
|
||||
version = "2.3.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
|
||||
|
||||
v2.2.0 起,`marqdo call` 可以直接调用这份文件里的一个函数。读的是同一页说明,跑的是同一个实现。知识因此可以当工具用,测试也不必再包一层 `# main`。
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
**链接语法**:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
@@ -29,6 +31,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| 真正的核心优势 | 说明 |
|
||||
|------|------|
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **函数即工具**<br>`marqdo call` | 最小可执行单位是文件中的函数,不只是整份文件。人阅读函数旁边的叙述;开发者、测试和 Agent 用 `marqdo call 文件 函数 名字=值` 执行它。知识复用、工具调用、函数级测试和局部改进是同一入口的四种用法。 |
|
||||
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
|
||||
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
|
||||
@@ -281,10 +284,16 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v2.1.4)
|
||||
## 现状(v2.3.0)
|
||||
|
||||
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例;扩展包同步 **2.1.4**
|
||||
- **Foreign Strong(v2.3.0)**:会话 `handle`(不可过桥)· 仿射 close · `replay_check`/oracle journal · 表 arity refuse · Ω∈\(V_{\mathsf{safe}}\)。扩展包同步 **2.3.0**
|
||||
- **\(V_{\mathsf{safe}}\) JSON 整数(v2.2.2)**:外联与 `lib/json` 拒绝 `|n| > 2^{53}-1` 的 JSON 整数(对齐 Lean ForeignJSON);宽整数用十进制字符串 + Node `BigInt`。
|
||||
- **view 大纲侧栏(v2.2.1)**:修复 occlusion 文档与中等宽度下 Functions / Variables 掉到正文下方的问题;静态 `view output` 同源。
|
||||
- **函数级调用(v2.2.0)**:`marqdo call <文件.mq.md> <函数> 名字=值`。同一份文档给人读,也按函数执行;Tree 与 Bytecode 都跑被点名的函数,不回退到 `# main`。默认只执行纯函数。`--json` 给 Agent 读取结果或诊断。说明与价值见 [22-函数调用](public/features/22-函数调用.mq.md)。示例:`marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3` → `5`。扩展包同步 **2.2.1**
|
||||
- **Agent 可靠工作台(v2.1.5)**:ResourceView(JSON/CSV/PDF/image)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制与 execute 槽隔离;扩展包同步 **2.1.5**
|
||||
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例
|
||||
- **知识工作台运行时(v2.1.3)**:ModelSelection / RunContext / usage null≠0 · `view document` 只读嵌入 · LLM selection/messages/cancel · agent.step selection e2e · live smoke(设计 Partial:原生适配器 unavailable)
|
||||
|
||||
- **可执行知识生产链(v2.1.2)**:证据/闭包失效 · `verify`/`adjudicate` · `reuse_execute` / `eng_bind_execute`+`publish_gate` · `document.extract` · View `KnowledgePresentation`+SSE `page_token` · 上传限流 · 门禁 45 项(100/1000 单元)
|
||||
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113`
|
||||
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock)
|
||||
@@ -323,7 +332,7 @@ marqdo catalog public -o .marqdo
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v2.1.4)
|
||||
### 如何使用最新 Marqdo(v2.3.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -338,14 +347,16 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v2.1.4 # 或留在 main
|
||||
git checkout v2.3.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
marqdo version --check
|
||||
|
||||
# 2) 跑解释器 / 文档站 / catalog
|
||||
# 2) 跑整个文件,或只调用其中一个函数
|
||||
marqdo run tests/structure/hello.mq.md
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
|
||||
marqdo run tests/structure/hello.mq.md --backend bytecode
|
||||
marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
@@ -377,7 +388,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.1.4
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.3.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.1.4"
|
||||
version = "2.3.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+43
@@ -1,3 +1,46 @@
|
||||
marqdo (2.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.3.0: Strong foreign session — opaque Handle, affine close,
|
||||
replay_check vs oracle journal, table arity refuse, Omega V_safe gate.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 01 Nov 2026 14:45:00 +0800
|
||||
|
||||
marqdo (2.2.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.2: V_safe JSON integer contract on foreign/json bridge —
|
||||
refuse integers outside +/- (2^53-1); wide ints via decimal string.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Sat, 01 Nov 2026 09:45:00 +0800
|
||||
|
||||
marqdo (2.2.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.1: fix view/static-export outline rail under document
|
||||
(occlusion doc-block close + panel container query layout).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 11:45:00 +0800
|
||||
|
||||
marqdo (2.2.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.0: marqdo call runs one named function in any .mq.md.
|
||||
The same file stays the document, the knowledge and the program.
|
||||
Tree and bytecode both execute that function. External calls stay
|
||||
pure: write, process, network and plugin stay off by default.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 09:20:00 +0800
|
||||
|
||||
marqdo (2.1.5-1ppa2) noble; urgency=medium
|
||||
|
||||
* Rebuild 2.1.5 against Launchpad (previous 1ppa1 failed with no build log).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 09:35:49 +0000
|
||||
|
||||
marqdo (2.1.5-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.5: agent reliability workbench — ResourceView / ToolSpec /
|
||||
CheckpointV2 / EffectLedger; EKC ir.json warm-load; web short/read lanes.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 07:39:08 +0000
|
||||
|
||||
marqdo (2.1.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.4: default isolated HTTP execute (ADR 0009) — Supervisor
|
||||
|
||||
@@ -19,6 +19,9 @@
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [roadmap/agent-reliability-crossrepo-2026-10-27.md](roadmap/agent-reliability-crossrepo-2026-10-27.md) | **Proposed:跨仓 Agent 可靠性开发计划**;M-A0–M-A6 ∥ Q-A0–Q-A7 排期、依赖图、F01–F20 映射、MA-T*/QA-* 验收与第一刀切片;协议真源仍见下方设计文档 |
|
||||
| [design/agent-reliability-tools-resources-2026-10-27.md](design/agent-reliability-tools-resources-2026-10-27.md) | **Proposed:智能体能力补足**;基于 `16f26d7`,增量设计错误恢复、检查点/效应账本、结构化工具、输出通道、上下文与只读资源视图;含跨仓边界、阶段计划和故障验收 |
|
||||
| [research/agent-capabilities-2026-10-27.md](research/agent-capabilities-2026-10-27.md) | **官方能力调研与源码复核**;OpenAI/Claude/Gemini/LangGraph/Deep Agents/MCP,求道当前问题 F01–F20;区分现有能力、设计推导与待实测项 |
|
||||
| [design/isolated-web-runtime-development-2026-10-26.md](design/isolated-web-runtime-development-2026-10-26.md) | **隔离执行与响应式 Web 运行时**:进程池、控制/读取分离、取消、事件恢复、发布一致性;实现见 `src/runtime/` |
|
||||
| [adr/0009-isolated-web-runtime.md](adr/0009-isolated-web-runtime.md) | **ADR 0009**:隔离 Web 运行时决策;金样例通过后替代 ADR 0008 的并行性结论 |
|
||||
| [跨库缺陷复核(2026-10-26)](../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) | **最新源码与测试证据**:实际 HTTP 路由、知识发布/阅读断点、旧缺陷处置及 1000 单元编译性能失败;需同级 qdagent checkout |
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**;HTTP **execute** 路径正式替代 [ADR 0008](0008-web-invoke-serialization.md) 的并行性结论。`legacy_serial`(未声明且非流式)仍引用 0008 单飞 / 父进程 `CallLibPath`。 |
|
||||
| 日期 | 2026-10-26 |
|
||||
| 日期 | 2026-10-26(修订 2026-10-27:disconnect≠cancel;control/read/short 无父锁) |
|
||||
| 设计 | [isolated-web-runtime-development-2026-10-26.md](../design/isolated-web-runtime-development-2026-10-26.md) |
|
||||
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝) |
|
||||
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝;disconnect-keeps-running;control-under-dual-execute) |
|
||||
|
||||
## 背景
|
||||
|
||||
@@ -14,18 +14,20 @@ ADR 0008 确认:Go HTTP 多线程,但所有 Endpoint 共享一把解释器
|
||||
## 决策
|
||||
|
||||
1. **首选架构**:预热的一次性 Marqdo worker 进程池;每个租约独占一个进程与 HostContext。
|
||||
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` 或 body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);禁止父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。`short` / `read` / `control` 仍父进程短路径;未声明非流式 → `legacy_serial`。
|
||||
3. **控制/读取分离**:取消与事件订阅不进入任务解释器锁;短业务与长执行有独立容量(execute 槽默认 2)。
|
||||
4. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
|
||||
5. **能力探测**:`runtime.isolated_execution=1`(默认)、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`;`runtime.read_lane` 仍 0。
|
||||
6. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
|
||||
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` / body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);**禁止**父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。声明的 `short`/`read`/`control` 走父进程短路径(execute 已离进程,父锁通常空闲);未声明非流式 → `legacy_serial`。
|
||||
3. **控制/读取分离**:`/_runtime/*`(cancel、events、task get)不进入解释器锁。短读勿挤占 execute worker 槽(池默认 2);产品 cancel 优先 `/_runtime`。
|
||||
4. **订阅 ≠ 取消**:`sse-live` 观察者 `ctx.Done()` 默认**只结束订阅**,不 `runtime.cancel`;后台仍 reap worker 以释放槽。仅显式 header `X-Marqdo-Cancel-On-Disconnect: 1` 才 disconnect=cancel。同步 `waitIsolatedJSON` 可保留 disconnect 取消。重连:`GET /_runtime/tasks/{id}/events` + `Last-Event-ID` / `after_seq`。
|
||||
5. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
|
||||
6. **能力探测**:`runtime.isolated_execution=1`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane=1`(短读不与 execute 抢父锁)。
|
||||
7. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
|
||||
|
||||
## 后果
|
||||
|
||||
- Execute / live SSE 不再抢进程级 SSE 桥;双流可并行(MR-01)。
|
||||
- 短读走父进程:在 dual execute 下通常仍 200(父锁空闲);勿把 short/read/control 塞进 2 槽 execute 池。
|
||||
- Legacy 未声明非流式路径仍可走父进程锁(ADR 0008)。
|
||||
- 产品(qdagent)cancel / Last-Event-ID 接线仍为后续;不阻碍本框架发版。
|
||||
- 产品(qdagent)`turn_events` / Last-Event-ID / cancel CAS 接线由 qdagent 验收;框架侧 disconnect≠cancel 与 `/_runtime` 无锁控制面已落地。
|
||||
|
||||
## 验收(摘要)
|
||||
|
||||
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`。其余见设计文档 §12。
|
||||
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`、`runtime.read_lane=1`。观察者断连后任务仍跑完并可经 `/_runtime` 重放。其余见设计文档 §12。
|
||||
@@ -0,0 +1,348 @@
|
||||
# Marqdo 智能体能力补足:恢复、工具、上下文与资源视图
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed**;本次交付设计,不代表以下新接口已实现 |
|
||||
| 日期 / 基线 | 2026-10-27(Asia/Shanghai);Marqdo `16f26d7` / 2.1.4;qdagent `68b757e` |
|
||||
| 调研与现状 | [官方资料与源码证据 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品配套 | [qdagent 智能体能力与预览设计](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 继承 | [ext/agent](ext-agent.md)、[隔离 Web 运行时](isolated-web-runtime-development-2026-10-26.md)、[工作台合同](qdagent-workbench-runtime-and-view-2026-10-25.md) |
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;让工具可发现、可验证、可审计;让结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位,不把框架改成第二套产品聊天服务。
|
||||
|
||||
现有 `src/runtime/` 已实现隔离进程、任务/事件与控制通道,本设计在其上补 Agent 步骤语义。现有 `ext/ai/agent.mq.md` 已有 step/plan/run、CALL/READ、观察压缩,继续扩展。框架不持有求道“笔记”业务表、中文按钮、默认回答字数或具体供应商账户。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | 错误分类、预算、检查点、工具效应、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | 结果分通道、输出预算、角色消息、finish reason | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD 行为 |
|
||||
| 资源 | ResourceRef、只读内容/派生预览、定位、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览组件和布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
APP[qdagent 产品策略与授权] --> RUN[ext/ai/agent step / plan / run]
|
||||
RUN --> CTX[ContextPack 与预算]
|
||||
RUN --> LLM[LLM Adapter]
|
||||
RUN --> DISPATCH[Tool Dispatcher]
|
||||
DISPATCH --> LOCAL[受控 Marqdo 函数]
|
||||
DISPATCH --> MCP[MCP Client]
|
||||
DISPATCH --> RES[资源读取 / 转换]
|
||||
RUN --> REC[Checkpoint / Effect Ledger]
|
||||
REC --> RT[既有 runtime task store / event log]
|
||||
RUN --> OUTPUT[answer / artifact / progress / diagnostic]
|
||||
RES --> VIEW[DocumentView / ResourceView]
|
||||
OUTPUT --> APP
|
||||
VIEW --> APP
|
||||
```
|
||||
|
||||
## 2. 现状与增量
|
||||
|
||||
| 已有能力 | 本轮不能误判为缺失 | 要补的具体语义 |
|
||||
|---|---|---|
|
||||
| runtime.task_control_v2/event_replay/read_lane | 不再新建一套队列与 SSE 框架 | Agent 步骤恢复与传输重放的边界 |
|
||||
| resume_save/load | 不再新建平行 checkpoint 命名空间 | 原子提交、版本摘要、作用域、效应关联 |
|
||||
| CALL、ARGS、READ、plan patch | 不废弃文档式编排 | 类型化 schema、校验错误、有限修复、稳定 call_id |
|
||||
| MCP stdio client | 不从零重写连接器 | timeout/cancel、resource、远程 transport 的能力探测 |
|
||||
| DocumentViewV1 / Locator | 不另写 `.mq.md` 解析器 | 普通资源类型、明确 renderer、历史与相对资源处理 |
|
||||
| LLM messages/usage | 不把 provider 行为交给产品猜测 | 输出预算、原生工具适配探测、角色边界与分通道 |
|
||||
|
||||
新模块路径及协议名以下均是**建议落点**。首批开发先固化 schema 与 fixture,再开放 feature bit;不得只更新 capabilities 把未实现能力标真。
|
||||
|
||||
## 3. 错误和恢复合同
|
||||
|
||||
### 3.1 ErrorV1
|
||||
|
||||
现有字符串错误保留兼容适配,新工具与 Agent 结果返回:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentErrorV1",
|
||||
"code": "tool.timeout",
|
||||
"category": "transient",
|
||||
"stage": "tool",
|
||||
"message": "读取资源超时",
|
||||
"retryable": true,
|
||||
"retry_after_ms": 1200,
|
||||
"effect_state": "none",
|
||||
"recovery_action": "retry_step",
|
||||
"call_id": "call_01",
|
||||
"details_ref": "resource:diagnostic_01"
|
||||
}
|
||||
```
|
||||
|
||||
`retryable` 仅是候选信息,最终动作由可信策略结合效应、截止时间、预算、取消状态决定。远端工具声称 readOnly/idempotent 不构成授权依据。凭证和原始堆栈不进入公开 message。
|
||||
|
||||
| 错误类别 / 例子 | 框架动作 | 不允许的动作 |
|
||||
|---|---|---|
|
||||
| transient:429、部分 5xx、连接失败 | 只在安全步骤重试,遵守 Retry-After | 无限重试、复用同一流片段直接追加 |
|
||||
| invalid_arguments:schema 不匹配 | 把字段级错误作为 observation,最多 1 次参数修复 | 启动工具后才校验;静默丢弃字段 |
|
||||
| validation_failed:编译/文档校验 | 保留候选与诊断,局部修复后重新验证 | 将未验证草稿标为成功 |
|
||||
| context_overflow | 压缩可重建上下文,保留任务/限制/未决效应 | 丢失最新用户指令、授权或版本 |
|
||||
| auth / forbidden | 直接 needs_input/blocked,交应用处理 | 换身份、扩大范围或匿名绕过 |
|
||||
| conflict / stale_revision | 重新读取版本并重新规划 | 覆盖用户修改、对写操作盲重试 |
|
||||
| capability_unavailable | 返回可行替代操作清单 | 假称已搜索、已渲染或已执行 |
|
||||
| policy_denied | 显式拒绝该动作 | 把限制当工具错误让模型规避 |
|
||||
| budget_exhausted | 保存状态与已完成结果,返回 partial | 自动增预算或伪造 completed |
|
||||
| unknown_effect / worker_crash | 对账、查询外部状态,不能判断则 needs_reconciliation | 重跑整个工作簿 |
|
||||
| cancelled | 停止新调用、保留可读产物、传播取消 | 在后台悄悄修复或恢复 |
|
||||
|
||||
初始建议:传输最多 2 次重试(总 3 次尝试),指数退避基准 0.5/1 秒并加 jitter;有 Retry-After 时使用服务端建议并受总 deadline 限制。参数修复最多 1 次,内容修复最多 2 次。预算由应用传入,框架只提供默认上限与执行机制。所有重试、修复和摘要模型调用计入同一成本账本。
|
||||
|
||||
错误指纹 `hash(tool_id, normalized_arguments, error_code, relevant_revision)` 连续出现 2 次且没有新证据时中止该策略,允许一次有依据的替代路径;不能通过改写错误文本绕过循环检测。
|
||||
|
||||
### 3.2 四类“恢复”必须分开
|
||||
|
||||
1. **续订事件**:客户端从 cursor 重放和订阅同一个 task,不发起新推理。
|
||||
2. **重试步骤**:相同逻辑 operation、同幂等键;新 invocation attempt,复用成功的前序结果。
|
||||
3. **恢复工作流**:从兼容 checkpoint 建立新 runtime task / attempt,关联 `resumed_from`,不把旧终态改回 running。
|
||||
4. **重新生成答案**:新的输出版本;已有成功工具结果可复用,用户明确重新执行才重新产生效应。
|
||||
|
||||
当前 TaskState 把 interrupted/needs_reconciliation 视为终态,沿用此约定。新增 `AgentRun` 逻辑关联只管理目标和 attempt 链;调度权仍在原 runtime。恢复请求带 `expected_revision`、checkpoint digest 与幂等键,相同请求返回同一新 attempt,冲突返回 409 对应的框架错误。
|
||||
|
||||
执行失败不必丢掉有用内容:`outcome.status = succeeded | partial | failed | needs_input | cancelled`,伴随 `answer_ref/artifacts/error/recovery_options`。HTTP 调用成功与 Agent 业务 succeeded 不再混为同一字段。
|
||||
|
||||
## 4. 检查点与工具效应
|
||||
|
||||
### 4.1 CheckpointV2
|
||||
|
||||
在 `plugins/agent/src/resume.rs` 扩展已有实现,统一根目录由宿主提供,客户端不能传任意绝对路径。保留 legacy load,但旧 checkpoint 无效应信息时默认 `manual_review`,不能自动重做写操作。
|
||||
|
||||
| 字段组 | 内容 |
|
||||
|---|---|
|
||||
| 身份 | schema、checkpoint_id、logical_run_id、task_id、attempt_id、step_id、parent_checkpoint_id |
|
||||
| 作用域 | principal_ref、workspace_id、session_id、授权 scope digest |
|
||||
| 输入 | task revision、workbook revision/hash、输入资源 revisions、knowledge generation |
|
||||
| 运行配置 | ModelSnapshot public ref、tool registry digest、policy revision、runtime compatibility |
|
||||
| 进度 | completed_steps、pending_operation、observation refs、context summary ref |
|
||||
| 约束 | 剩余 token/tool/time/cost 预算、deadline、cancel epoch |
|
||||
| 一致性 | effect ledger watermark、event seq、manifest digest、committed_at |
|
||||
|
||||
写入协议:写唯一临时文件→flush/fsync→原子 rename→提交 checkpoint 指针;持久化配置下目录 fsync 按平台支持实现。所有引用 blob 在指针提交前落盘。损坏记录报 `checkpoint.corrupt` 并尝试上一个完整版本,不能读取半个 JSON 当无历史。
|
||||
|
||||
恢复前校验身份/授权、源版本、工具 schema 与模型兼容性。权限撤销立即生效;checkpoint 不是永久授权。源文件改变返回 `checkpoint.input_changed`,重新计划受影响步骤,不能偷偷使用最新文件继续旧验证结果。
|
||||
|
||||
### 4.2 Effect ledger
|
||||
|
||||
```text
|
||||
prepared → started → committed
|
||||
↘ failed_no_effect
|
||||
↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
|
||||
```
|
||||
|
||||
每个 operation 持久记录 `operation_id/idempotency_key/args_digest/resource_scope/expected_revision/effect_class/result_ref`。幂等键作用域是 principal + workspace + logical_run + step + operation,不用随机 attempt ID 替换稳定 operation key。对同 key 不同 payload 拒绝。
|
||||
|
||||
读工具可重试;确定幂等写由服务端去重;可补偿写仅在补偿明确安全时执行;未知写先查询 receipt/版本。对外部系统不能承诺通用 exactly-once。关键 crash 窗口是“远端已成功、本地尚未记账”,必须返回 unknown 并对账。
|
||||
|
||||
本地文件使用 expected revision + staging + atomic replace;变更提交后检查点失败也靠 operation receipt 恢复。`tool.completed` 必须在结果与 receipt 可读取后提交,再对外发事件。事件发送失败不回滚已发生的业务效应。
|
||||
|
||||
不要复制 runtime 事件存储:Agent ledger 与 artifact manifest 是步骤事实,现有 runtime event log 是传输/调度事实;以 ID 关联,采用可重建投影与 outbox。跨 DB/文件不能声称一个事务完成,使用 manifest 提交点和恢复扫描补齐索引。
|
||||
|
||||
## 5. 结构化工具与调度
|
||||
|
||||
### 5.1 ToolSpecV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ToolSpecV1",
|
||||
"id": "workspace.read",
|
||||
"version": "1",
|
||||
"description": "读取授权资源的指定行范围",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"resource_id": {"type": "string"},
|
||||
"revision": {"type": "string"},
|
||||
"start_line": {"type": "integer", "minimum": 1},
|
||||
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
|
||||
},
|
||||
"required": ["resource_id"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"output_schema_ref": "ResourceReadV1",
|
||||
"effect": "read",
|
||||
"scopes": ["workspace:read"],
|
||||
"timeout_ms": 10000,
|
||||
"max_result_bytes": 65536,
|
||||
"idempotency": "safe",
|
||||
"concurrency_group": "resource-read",
|
||||
"availability": "ready"
|
||||
}
|
||||
```
|
||||
|
||||
定义由宿主/可信模块注册;用户认证、scope 与资源根由宿主注入,不接受模型提供 principal 或任意 root。`read`、`write`、`execute`、`external_write` 是策略分类,不是靠工具命名推断。
|
||||
|
||||
ToolCallV1:`call_id/tool_id/tool_version/arguments/operation_id/parent_span_id`。ToolResultV1:`ok/status/summary/structured_content/resources/citations/error/usage/truncated/next_cursor/effect_receipt_ref`。超限结果先写 artifact,再返回摘要和范围读取句柄;不把几十 MB 文本送进 prompt。
|
||||
|
||||
### 5.2 一条执行通道
|
||||
|
||||
```text
|
||||
发现 → 加载 schema → schema 校验 → 授权与范围解析 → 预算/取消检查
|
||||
→ 幂等查询 → 执行 → 结果 schema/大小校验 → receipt/结果提交 → 事件 → observation
|
||||
```
|
||||
|
||||
provider 原生 function call 与文档 `CALL:name + ARGS:{...}` 都归一到该通道。保留旧白名单适配,已有 `.mq.md ##` 可根据形参推导初始 schema,再允许显式描述收紧。转换不允许调用未暴露的框架内部函数。禁止对模型参数使用 eval/任意代码反序列化。
|
||||
|
||||
`tools.search` 返回已授权且当前可用的工具摘要;`tools.describe` 按 ID 返回完整 schema。核心 5–8 个工具可常驻,其余按需加载;此数量是产品起始配置,不写死框架。每次真正调用仍重新检查授权;搜索索引可列 unavailable 原因供诊断,但不能让未授权工具名字泄露私有连接信息。
|
||||
|
||||
初始支持 JSON Schema 的明确子集并公开能力;不支持的 schema 拒绝注册,不静默放宽。原生工具能力、并行工具调用、图片输入、结构化输出分别探测;纯文本兼容 provider 继续走 CALL,但并发和可靠性承诺按测试能力开放。
|
||||
|
||||
### 5.3 并发、MCP 与程序化执行
|
||||
|
||||
独立只读调用可并发,默认最多 4 个;修改同一资源的调用串行且用 revision CAS。依赖链、审批与取消检查保持顺序。一个并发调用失败不丢弃其他已成功结果。
|
||||
|
||||
MCP 扩展现有 client:先完善 timeout/cancel、错误映射、工具分页与 schema、resource read/link,再按 capability 增加远程 Streamable HTTP 与连接认证。stdio 不应允许模型选择任意宿主可执行文件。连接元数据归应用,凭证通过 secret handle 注入 worker,工具输出和 trace 不记录密钥。
|
||||
|
||||
工具 annotations 只是提示,可信策略确定真实效应。外部结果全部为数据,不能提升为 standing/system。MCP resource URI 转成宿主授权 ResourceRef,不允许前端直接请求任意 file:// 或内部网地址。
|
||||
|
||||
程序化工具编排和子 Agent 为后续切片:在沙箱中仅暴露注册 dispatcher,逐次执行同样的授权、预算和效应日志;禁止通过一段脚本绕过逐工具控制。子任务继承更小权限和共享总预算,不默认开放写同一资源。
|
||||
|
||||
## 6. 输出通道与上下文
|
||||
|
||||
### 6.1 AgentOutputV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentOutputV1",
|
||||
"status": "succeeded",
|
||||
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
|
||||
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
|
||||
"citations": [],
|
||||
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
|
||||
"finish_reason": "completed",
|
||||
"recovery_options": []
|
||||
}
|
||||
```
|
||||
|
||||
这是结果传输协议,不要求模型每次逐字生成这张 JSON。文档式编排仍可产出 `.mq.md`,框架把稳定产物、摘要与事件归一化。普通文本回答可没有 artifact 和 validation;未运行的内容标 `not_applicable/not_run`,不能填 passed。
|
||||
|
||||
channel 至少区分 `answer/artifact/progress/diagnostic`。只有 answer delta 可追加到聊天正文;工作簿 token 和工具日志进入其他通道。进度是可观察动作摘要,不要求或泄露模型内部思维链。
|
||||
|
||||
应用传 `ResponsePolicy`:detail level、目标长度、最大输出 tokens、是否允许 artifact、用户显式需求。框架负责 budget 和 finish_reason,中文字符数与最终文案由应用决定。达到 token 上限返回 `length_limited` 和完整/不完整标记,不能裁剪 JSON/代码后假装成功。
|
||||
|
||||
优先从已验证产物结构投影摘要。必要时增加一次受预算控制的摘要模型调用;摘要不得新增未经证据支持的结论。修复成功后 accepted candidate、结果正文、artifact revision 与 verification digest 必须全部一致。
|
||||
|
||||
### 6.2 ContextPackV2
|
||||
|
||||
按优先级组装:可信运行规则→最新用户目标/约束→用户选中资源范围→未决操作/成功步骤摘要→检索证据→近期对话→可回读历史。保持角色结构,不把用户/工具文本简单拼进系统指令。
|
||||
|
||||
每个 item 携带 `origin/trust/resource_ref/revision/token_estimate/priority`。预算初值建议保留模型窗口 20% 给输出与协议开销;上下文使用达到可用预算 70% 时触发整理,具体比例配置化。优先剔除可重读的完整工具输出,保留摘要、引用和失败恢复锚点。
|
||||
|
||||
Compaction 必须保留:目标、用户限制、当前计划、已完成步骤、待决写入、授权范围、输入版本、已接受产物与引用、余量。summary 绑定其 source event range 和 digest,不能当成新的已验证知识。工具输入过时须重读,不能依赖压缩摘要执行写入。
|
||||
|
||||
已有 EKC/agent memory 继续提供知识发现和复用。长期用户记忆的创建/修改/删除政策归 qdagent;网页中的指令不能自动变成长期偏好。
|
||||
|
||||
## 7. 统一资源与只读视图
|
||||
|
||||
### 7.1 ResourceRefV1 / ResourceViewV1
|
||||
|
||||
ResourceRef 统一携带 `resource_id/workspace_id/kind/media_type/revision/digest/title/size/origin/locator`;opaque ID 由宿主映射,不将浏览器 path 直接当文件权限。revision 是内容版本,generation 是知识发布代,两者不混用。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ResourceViewV1",
|
||||
"resource": {
|
||||
"resource_id": "res_01", "workspace_id": "ws_01", "kind": "file",
|
||||
"revision": "sha256:example", "media_type": "text/markdown", "title": "设计说明"
|
||||
},
|
||||
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
|
||||
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
|
||||
"outline": [],
|
||||
"locators": [],
|
||||
"completeness": "complete",
|
||||
"no_exec": true,
|
||||
"diagnostics": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
```
|
||||
|
||||
继续把 `.mq.md` 交 `view.document`,ResourceView 只包装/扩展,不能另解释一套 Marqdo 语义。普通 `.md/.txt/代码/JSON/CSV` 走媒体类型处理,避免全仓语义编译。浏览器组件由 qdagent 实现,框架只提供可读内容、受控片段或短期授权 blob 引用。
|
||||
|
||||
`fragment`、`text`、`blob_ref` 是互斥载荷,按严格 format enum 解码。未知格式返回 unsupported,不能用 `format.includes('html')` 猜测 HTML。为空与加载失败必须有独立状态。
|
||||
|
||||
### 7.2 格式矩阵
|
||||
|
||||
| 格式 | 框架提供 | 前端消费 | 未具备能力时 |
|
||||
|---|---|---|---|
|
||||
| `.mq.md` | 静态 DocumentView、outline、节点/引用 | 正文、语义链接、源码切换 | 只读源码 + 明确诊断,不执行 |
|
||||
| Markdown / 笔记正文 | 共享静态 Markdown→受控结构/HTML、相对资源引用 | 标题、列表、表格、代码、链接 | 纯文本 |
|
||||
| 文本/代码 | 分页行片段、编码信息、行定位 | 行号与语法高亮 | 编码提示/下载 |
|
||||
| JSON / CSV | 有界解析、路径/行列定位、分页 | 树/表/源码 | 原始文本,标格式错误 |
|
||||
| 图片 | 授权 blob、尺寸/元信息 | 缩放/旋转/替代文本 | 下载,不暗示已做 OCR |
|
||||
| PDF | blob、页元信息,可选提取插件 | PDF.js 页渲染与定位 | 文件卡;提取不可用不阻止支持的视觉预览 |
|
||||
| DOCX/XLSX/PPTX | 受限转换插件,可选 PDF/HTML 派生物 | 按派生格式预览 | 未安装转换器,保留下载 |
|
||||
| HTML/SVG | 默认源码;允许时经严格清洗或受限派生物 | 隔离预览 | 不以内联可执行页面显示 |
|
||||
| 未知二进制/压缩包 | 元数据 | 下载卡 | 不自动解压/执行 |
|
||||
|
||||
提取、预览、执行各有独立 capability。办公转换、OCR 使用受限 worker,禁宏与网络、限制时间/内存/页数/解压膨胀比;结果绑定原件 digest、转换器版本和参数。首期不承诺保真编辑。
|
||||
|
||||
### 7.3 安全、定位、缓存
|
||||
|
||||
所有读取先校验宿主授予的 workspace/resource scope,canonicalize 并处理 symlink 逃逸;读取句柄与校验对象一致,防路径检查后替换。读取原件的身份权限不可被缓存绕过。
|
||||
|
||||
预览绝不调用 `run/verify` 或有执行副作用的 view 路径;正文中的 Marqdo 调用链接只展示语义与导航,执行需单独工具调用与授权。远程图片、相对链接、资源 URL 经受控解析;下载入口不允许任意内网 fetch。
|
||||
|
||||
HTML 清洗在框架产出侧和浏览器插入侧都有明确边界;用成熟 allowlist 实现而非正则。禁止 script/event handler、危险 URI、任意 style/form/嵌入对象。前端配 CSP;对需要交互的产物另建无权限 sandbox,不复用文档渲染器。
|
||||
|
||||
缓存 key:workspace + resource ID + revision + renderer version + render options + policy version;命中前重新授权。历史 revision 不存在就返回 `version_unavailable`,不能默默展示当前版。locator 支持 node/span/line/page/cell,失效时标 stale 并提供用户主动查看最新版的操作。
|
||||
|
||||
建议首期限制:文本片段 256 KiB、代码单次 500 行、CSV 单次 200 行;更大内容分页,完整文件保留。数值需压测校准,不作为现有系统性能声明。
|
||||
|
||||
## 8. 事件、可观测性与能力协商
|
||||
|
||||
复用 RuntimeEventV2 的 task/run/attempt/seq/event_id。拟增加事件类型:`agent.step.started/completed`、`tool.started/completed/failed`、`recovery.scheduled/exhausted`、`checkpoint.committed`、`artifact.updated`、`answer.delta/committed`、`context.compacted`。现有 `message.delta` 由兼容适配映射 answer channel,不能同时重复消费两套事件。
|
||||
|
||||
终态提交包含 accepted output manifest、last_seq、result digest;断流客户端能通过快照补齐最终答案。stream delta 是预览,最终 committed revision 是权威。统计每次尝试的 usage,摘要和修复调用分别标 purpose;未知计量保持 unknown。
|
||||
|
||||
拟新增 capability:`agent.error_v1`、`agent.checkpoint_v2`、`agent.tool_schema_v1`、`agent.output_channels_v1`、`agent.context_pack_v2`、`resource.view_v1`,以及各 media renderer 的独立版本/可用状态。保持现有 probe,新增字段向后兼容;未知 feature 当不可用。
|
||||
|
||||
trace 记录因果 ID、耗时、错误类别、参数摘要、资源版本和 effect receipt。正文与密钥按配置脱敏,不默认把用户全文件复制进日志。输出中不包含模型私有推理;可审计的是实际动作与结果。
|
||||
|
||||
## 9. 分阶段实现与文件落点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 依赖 / 退出条件 |
|
||||
|---|---|---|---|
|
||||
| M-A0 | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | 上述协议、旧适配、状态映射 | 先冻结跨仓字段,未知字段/版本可降级 |
|
||||
| M-A1 | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、新 recovery/effects 支撑模块 | 分类错误、有界修复、accepted candidate、原子检查点 | M-A0;故障注入不重复写、旧记录不冒险自动恢复 |
|
||||
| M-A2 | `plugins/agent/src/lib.rs`、`mcp_client.rs`、新 tool registry/dispatcher | schema 工具、调用统一、分页与结果资源 | M-A0;未授权调用为 0,失败结果结构正确 |
|
||||
| M-A3 | `src/workbench/document_view.rs`、新 resource_view、媒体适配模块 | ResourceRef/View、普通格式静态阅读、no-exec | M-A0;资源定位与安全语料通过 |
|
||||
| M-A4 | `ext/ai/agent.mq.md`、`plugins/llm/src/lib.rs`、`src/workbench/run_context.rs` | 输出分通道、预算、ContextPackV2 | M-A1/2;原生和纯文本 provider fixture 都可用 |
|
||||
| M-A5 | `src/runtime/` 的既有存储/事件适配、MCP 与转换插件 | 恢复对账、PDF/Office 插件、远程 MCP | M-A1/2/3;持久模式 crash/restart 通过 |
|
||||
| M-A6 | plan/subtask/sandbox 扩展 | 程序化工具、有界委派与可选浏览器 | 后置;须证明任务收益和预算/效应可控 |
|
||||
|
||||
先交 M-A0 与 qdagent P0 的静态阅读/错误结果修复;不要让完整 checkpoint v2 阻塞笔记预览。M-A1 可先上只读重试,写恢复待 ledger 通过再开放。新特性默认关闭直到对应合同实测通过,旧路径继续可读。
|
||||
|
||||
## 10. 验收与评测
|
||||
|
||||
所有目标是 proposed gate,尚未实测。基础机制用确定性 fake provider/tool;真实 provider 做少量单独 smoke 并记录费用,不能把随机模型输出作为唯一门禁。
|
||||
|
||||
| 编号 | 故障/任务 | 必须观察到的结果 |
|
||||
|---|---|---|
|
||||
| MA-T01 | 第一次 429、第二次成功 | 尊重退避、计量 2 次、最终只有一个 accepted answer |
|
||||
| MA-T02 | 连续 schema 参数错误 | 一次修复后停止;工具未在无效参数下执行 |
|
||||
| MA-T03 | 工具写成功但 receipt 提交前杀 worker | unknown_effect→查询对账;写计数不增加 |
|
||||
| MA-T04 | checkpoint 写一半杀进程 | 读取上个完整 checkpoint 或明确 corrupt,不产生伪成功 |
|
||||
| MA-T05 | 终态事件丢失、cursor 重放 | 最终快照恢复完整消息,工具执行次数不增加 |
|
||||
| MA-T06 | 恢复请求重复/并发 | 同一幂等键只产生一个恢复 attempt |
|
||||
| MA-T07 | 用户取消与重试定时器竞争 | 取消生效后无新工具调用,旧任务不复活 |
|
||||
| MA-T08 | 执行中资源/权限改变 | stale/conflict/forbidden,不覆盖新版本 |
|
||||
| MA-T09 | 恶意文本伪造 CALL/system | 不跨越工具白名单和授权范围 |
|
||||
| MA-T10 | `.mq.md` 预览含写文件/联网语句 | 哨兵文件/网络计数不变;只读渲染成功或安全降级 |
|
||||
| MA-T11 | 资源格式、超长输出、路径逃逸 | 正确 renderer/分页;越界拒绝;无 HTML 注入 |
|
||||
| MA-T12 | 修复原文 A 得到通过验证的 B | answer/artifact/verification 都绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后继续 | 最新约束、待决效应、资源版本与剩余预算不丢失 |
|
||||
| MA-T14 | 旧 CALL、旧 DocumentView 消费端 | 基础行为可用,能力缺失有明确返回 |
|
||||
|
||||
先运行受影响的 Rust/Go/Marqdo 合同与既有隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标:已缓存 100 KiB 文本视图服务端 p95 < 300 ms、核心工具发现 p95 < 100 ms,基准机器/并发/冷暖缓存必须记录;第三方网络延迟单独列出。
|
||||
|
||||
## 11. 迁移、回滚与未决项
|
||||
|
||||
兼容迁移按“新增协议→双读→新写→验证→逐步移除旧适配”推进。`.mq.md` 源码与旧运行产物不批量重写;旧 resume JSON 可读取但不能自动升级成带副作用保证的检查点。v2 checkpoint/ledger 保留 schema 版本,新老版本不并发写同一运行。
|
||||
|
||||
回滚关闭新工具自动发现、输出通道或转换器时,已提交资源和最终答案仍可读;执行恢复中的任务先 drain/停止接纳,不能切回会盲重做写操作的旧路径。迁移前备份可变索引与 manifest,回滚不删除用户产物。
|
||||
|
||||
实现前验证项:现有 runtime 持久存储可提供的原子提交边界、各平台 fsync/rename 行为、LLM adapter 原生 tool call 流式兼容、转换插件部署体积。协议优先按本文保守语义实现,验证不能满足则 feature 保持不可用,不阻塞已经完成的只读预览切片。
|
||||
@@ -53,22 +53,23 @@ Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识
|
||||
|
||||
落盘(G01 分离后):
|
||||
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
|
||||
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json`
|
||||
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json` · **`ir.json`**(完整 IR 快照,供查询热路径)
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认)
|
||||
marqdo knowledge preflight "task"
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认;写投影 + ir.json)
|
||||
marqdo knowledge preflight "task" # 暖机读 ir.json;缺图才 compile
|
||||
marqdo knowledge preflight "task" --refresh # 强制全量重编译后再预检
|
||||
marqdo knowledge record REUSE
|
||||
marqdo knowledge learn --task ... --failure ...
|
||||
marqdo find "authentication"
|
||||
marqdo find "authentication" # 同上:缺图才 compile;--refresh 强制
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo impact path/to/file.mq.md
|
||||
marqdo conflicts | stale | duplicate [--fail] | verify
|
||||
```
|
||||
|
||||
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
统一 `--json`。查询类命令(`preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`)默认 **读已编译投影**;CI 或源变更后应先 `marqdo knowledge` 或加 `--refresh`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
|
||||
## 6. Reuse 协议
|
||||
|
||||
|
||||
@@ -214,19 +214,23 @@ template = ["php", "-r", "{inline}"]
|
||||
|
||||
### 4.1 值映射
|
||||
|
||||
Canonical integer contract: [`v-safe-json.md`](v-safe-json.md) (Lean \(V_{\mathsf{safe}}\): `|n| ≤ 2^{53}-1`).
|
||||
|
||||
| Marqdo | JSON |
|
||||
|---|---|
|
||||
| None | null |
|
||||
| Bool | bool |
|
||||
| Int | number |
|
||||
| Num | number(NaN/Inf → null) |
|
||||
| Text | string |
|
||||
| List | array |
|
||||
| Map | object |
|
||||
| Int | number **仅当** `|n| ≤ 2^{53}-1`;越界 → 显式失败(禁止静默扭曲) |
|
||||
| Num | number(NaN/Inf → null);float 为宿主扩展,∉ mechanized \(V_{\mathsf{safe}}\) |
|
||||
| Text | string(宽整数用十进制字符串过桥,对端 `BigInt` / Python `int`) |
|
||||
| List | array(子树递归;任一越界整数使整体失败) |
|
||||
| Map | object(同上) |
|
||||
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
|
||||
| Code | 源码字符串 |
|
||||
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
|
||||
|
||||
错误前缀:`json: integer outside V_safe (±(2^53-1)): <n>`。
|
||||
|
||||
### 4.2 输入
|
||||
|
||||
- `input=` → JSON;写 stdin;同时提供 `MARQDO_INPUT`(≤8 KiB)与 `MARQDO_INPUT_FILE`(任意大小)。
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# Foreign Strong: Lean ↔ host correspondence
|
||||
|
||||
Pinned with PLDI Strong narrative (`FOREIGN-NARRATIVE-ASSESSMENT-2026-11-01.md`).
|
||||
**Not** verified compilation — conformance evidence only.
|
||||
|
||||
| Lean / paper rule | Host surface | Evidence |
|
||||
|---|---|---|
|
||||
| `SessionReg` + `sessionOpen` / `Close` / `sessionEval` | `HostContext.foreign_sessions` + `Value::Handle` | `DocCalc.lean`; `foreign_session.rs` |
|
||||
| `Ω(s, τ, c)` | Persistent kernel + process order | Oracle journal records `(cell, source_hash, stdout, result)` |
|
||||
| `SafeVal` / Encode / Decode | `src/host/json.rs` + session bootstrap sanitize | `ForeignJSON.lean`; `v-safe-json.md`; gold `foreign-*-vsafe-*` |
|
||||
| Handle ∉ \(V_{\mathsf{safe}}\) | `value_to_json(Handle) → Err` | `foreign-session-handle-no-serialize.mq.md` |
|
||||
| Closed / Closed-Close | use-after-close / double-close `Err` | gold misuse suite |
|
||||
| Oracle-Domain | Ω OOD integer → host `Err` | `foreign-session-result-vsafe-refuse.mq.md` |
|
||||
| Table arity stuck | Parse refuse unequal GFM row width; JSON refuse unequal column lists | `Surface.lean` `table_arity_*`; `tests/errors/table-arity.mq.md` |
|
||||
| Snapshot hash match/mismatch | `view/output.rs` `snapshot_page` | unit `snapshot_page_rejects_source_hash_mismatch` |
|
||||
| `replay_check` vs journal \(J\) | `DocumentSession::replay_check` | unit + `defense/fate_matrix/run_replay_pack.py` |
|
||||
| Dual-backend differential | `tests/gold.rs` tree + bytecode | 308 tests × 2; foreign subset includes session/V_safe |
|
||||
|
||||
## Intentional non-claims
|
||||
|
||||
- No static affine/linear session types (host death unsound).
|
||||
- Floats are host extension outside Lean `SafeVal`.
|
||||
- `replay_check` is host/document-session API, not a second interpreter backend.
|
||||
@@ -0,0 +1,78 @@
|
||||
# \(V_{\mathsf{safe}}\) JSON integer contract (host ↔ Lean)
|
||||
|
||||
Canonical Lean model: `MarqdoThesis/PLDI/proofs/MarqdoProof/MarqdoProof/ForeignJSON.lean`.
|
||||
Host mapper: `src/host/json.rs` (`json_to_value` / `value_to_json`).
|
||||
|
||||
This document freezes **runtime conformance** of the Marqdo JSON bridge to the
|
||||
mechanized \(V_{\mathsf{safe}}\) integer domain. It is **not** a verified
|
||||
compilation of the Rust interpreter.
|
||||
|
||||
## Domain
|
||||
|
||||
```
|
||||
MAX_SAFE = 9007199254740991 # 2^53 - 1
|
||||
```
|
||||
|
||||
\(V_{\mathsf{safe}}\) values (mechanized):
|
||||
|
||||
| JSON | Marqdo |
|
||||
|---|---|
|
||||
| `null` | `None` |
|
||||
| `bool` | `Bool` |
|
||||
| integer with `\|n\| ≤ MAX_SAFE` | `Int` |
|
||||
| `string` | `Text` |
|
||||
| `array` | `List` |
|
||||
| `object` | `Map` |
|
||||
|
||||
**Host extension (not in Lean `SafeVal`):** JSON non-integer numbers → `Value::Num(f64)` (NaN/Inf encode as `null`). Floats are documented host behavior; they are **not** claimed as mechanized \(V_{\mathsf{safe}}\) fidelity.
|
||||
|
||||
## Encode (`value_to_json`)
|
||||
|
||||
- `Value::Int(n)` with `|n| ≤ MAX_SAFE` → JSON number.
|
||||
- `Value::Int(n)` with `|n| > MAX_SAFE` → **refuse** (error).
|
||||
- `Value::Handle(_)` → **refuse** (`json: session handle cannot be serialized`).
|
||||
- Column-table `Map` whose fields are all `List` with **unequal lengths** →
|
||||
**refuse** (`json: table column arity mismatch`).
|
||||
- Nested `List` / `Map`: any child refuse fails the whole tree.
|
||||
- GFM table **parse** also refuses unequal row width
|
||||
(`table row arity mismatch`) before a value is built.
|
||||
- Wide integers that must cross a language boundary: author converts to a
|
||||
**decimal string** (∈ \(V_{\mathsf{safe}}\)); the foreign program may use
|
||||
`BigInt` / Python `int` on that string.
|
||||
|
||||
## Foreign oracle (`session_eval` / `session_get`)
|
||||
|
||||
Python/Node session bootstraps sanitize results with the same integer gate
|
||||
before JSON emission. An Ω response containing an OOD integer is a **fault**
|
||||
(host `Err`), not a soft `ok:false` cell record. Stdout text that authors
|
||||
`json.parse` themselves is still gated by host `json_to_value`.
|
||||
|
||||
## Decode (`json_to_value`)
|
||||
|
||||
- JSON integer with `|n| ≤ MAX_SAFE` → `Int`.
|
||||
- JSON integer with `|n| > MAX_SAFE` → **refuse**.
|
||||
- JSON unsigned integer `> i64::MAX` → **refuse** (do **not** coerce via `f64` or `Text`).
|
||||
- Nested array/object: any child refuse fails the whole tree.
|
||||
- Decimal-string encodings of wide integers → `Text` (in domain).
|
||||
|
||||
## Error prefix
|
||||
|
||||
All refuse messages use a fixed prefix for probes and diagnostics:
|
||||
|
||||
```
|
||||
json: integer outside V_safe (±(2^53-1)): <n>
|
||||
```
|
||||
|
||||
## In-domain roundtrip
|
||||
|
||||
`±MAX_SAFE`, bool, null, string, array, and object roundtrips through
|
||||
`encode → decode` must succeed. Integers `MAX_SAFE+1`, `-MAX_SAFE-1`, `2^53`,
|
||||
`2^60`, `2^60+1` (and nested forms) must refuse.
|
||||
|
||||
## Non-claims
|
||||
|
||||
- Not verified Rust ↔ Lean compilation.
|
||||
- Not arbitrary host-object fidelity (DataFrame, functions, heap sharing).
|
||||
- Not automatic BigInt promotion inside Node/Python bootstraps.
|
||||
- Document-level `Value::Int` may still hold i64 values that are OOD for JSON;
|
||||
the gate fires when those values enter JSON encode/decode.
|
||||
+124
-1
@@ -450,4 +450,127 @@ AI 优先使用既有知识,而非反复解释和重新生成
|
||||
|
||||
如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它?
|
||||
|
||||
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
|
||||
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
|
||||
|
||||
# Marqdo 可执行知识体系:设计规范与完整范例
|
||||
|
||||
我已经基于 Marqdo 当前仓库的语法规范、`[]()` 设计、知识分层、对象模型和 EKC,整理了两份详细文档。
|
||||
|
||||
这次设计保留了你的原始理念:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
核心目标不是让 AI 更容易生成 Marqdo 代码,而是让 AI 尽可能不必重新生成已经存在的知识,转而通过编译器确定性地发现、引用、验证和执行既有知识。
|
||||
|
||||
第一份:完整架构设计规范
|
||||
|
||||
涵盖语义制品、知识引用、编译器架构、解析优先级、效应安全、版本管理、EKC 集成、Agent 复用协议和实施验收。
|
||||
|
||||
阅读设计文档
|
||||
|
||||
第二份:多文件可执行知识范例
|
||||
|
||||
以虚构书店定价为例,从原始政策文档开始,逐步构造知识定义、对象、计算能力、业务入口、AI 问答、知识复用和错误验证。
|
||||
|
||||
阅读完整示例
|
||||
|
||||
两份文档打包
|
||||
|
||||
下载 ZIP
|
||||
|
||||
## 一、这份设计最重要的三个决定
|
||||
|
||||
# Marqdo 可执行知识体系:核心设计纲领
|
||||
|
||||
**核心理念:代码即文档,文档即知识库,知识即可执行。**
|
||||
|
||||
## 1. 知识是可编译的语义制品
|
||||
|
||||
文档经过 Marqdo 编译器处理后,不只产生可执行逻辑,还应产生具有稳定身份、类型、签名、契约、依赖关系、来源和验证状态的语义制品(Semantic Artifact)。
|
||||
|
||||
知识可以表现为事实、函数、能力、约束、数据集或类型。它们无需全部被强制编码为类。
|
||||
|
||||
## 2. `[]()` 是知识使用的统一入口
|
||||
|
||||
`[描述](目标)` 保留 Markdown 的可读性。
|
||||
|
||||
- `[]` 面向人类,描述意图、意义或用途。
|
||||
- `()` 面向编译器,包含既有 Marqdo 表达式或者可解析的知识目标。
|
||||
- 描述不改变执行结果,也不能作为可信性依据。
|
||||
- 编译器负责将目标解析为确定的符号身份,并验证使用条件。
|
||||
|
||||
既支持隐藏不易阅读的代码,也支持引用已经编译的知识。
|
||||
|
||||
## 3. AI 复用知识,而不是重新解释知识
|
||||
|
||||
AI 面对新任务时,应该遵循:
|
||||
|
||||
**Discover → Resolve → Verify → Reuse → Execute → Trace**
|
||||
|
||||
当知识缺失或不适用时,才进入 ADAPT 或 CREATE 流程。
|
||||
|
||||
检索可以模糊,但最终绑定必须确定。验证必须区分程序可执行性、契约符合性和现实事实正确性。
|
||||
|
||||
## 4. 编译器是知识系统的基础
|
||||
|
||||
AST、Semantic IR、符号索引、链接关系和知识验证应当由同一套语义体系产生。
|
||||
|
||||
解释器、字节码 VM、View、EKC 和 Agent 消费统一的编译结果,而不是各自重新解析文档。
|
||||
|
||||
## 5. 最终验收标准
|
||||
|
||||
一个 AI 能够发现现有知识、确定其身份、检查适用条件、直接执行既有能力、引用结果和来源,并在知识发生变化时识别受影响的调用者。
|
||||
|
||||
只有这条链条成立,Marqdo 才真正实现知识的可执行复用。
|
||||
|
||||
## 二、示例将展示什么
|
||||
|
||||
我选择了一个具有明确规则和复用价值的业务案例,而不只是使用“李白出生年份”这样的静态事实。
|
||||
|
||||
用户购买两件单价 60 元的商品,金卡折扣为 90%,满 100 元免运费。
|
||||
|
||||
AI 要处理的业务请求
|
||||
|
||||
> 请计算这笔金卡订单的最终应付款,并解释依据。
|
||||
|
||||
传统路径
|
||||
|
||||
检索政策 → AI 阅读规则 → 重新推导计算 → 生成新代码或答案
|
||||
|
||||
Marqdo 目标路径
|
||||
|
||||
发现定价能力 → 绑定已编译函数 → 检查输入与政策 → 执行 → 引用结果
|
||||
|
||||
目标语法示意(v2.1+,不是 v2.0.0 实测)
|
||||
|
||||
```
|
||||
**应付 = [订单最终应付款](定价.计算应付金额(60, 2, "金卡"))**
|
||||
```
|
||||
|
||||
根据演示政策计算
|
||||
|
||||
# ¥108
|
||||
|
||||
这套例子进一步展示了参数和返回值、类与继承、表格、条件分支、循环、跨文档调用、自然语言遮蔽,以及知识来源改变时的影响分析。
|
||||
|
||||
## 三、与当前版本的兼容边界
|
||||
|
||||
我特别保留了一个重要区分:设计目标不等于当前已经实现的功能。
|
||||
|
||||
根据这次读取的仓库内容,v2.0.0 已支持本地表达式遮蔽、对象、方法、控制流、表格集合、导入以及现有 EKC 基础;但无实例类函数调用、跨文档知识自动解析、完整 LinkInfo 和语义制品绑定仍需要进一步开发。
|
||||
|
||||
因此示例文档明确标注了目标语法和现有兼容写法,没有将尚未验证的代码描述为已经跑通。
|
||||
|
||||
## 四、我的主要架构建议
|
||||
|
||||
我认为接下来的开发不应该从 `[]()` 的外观继续扩展,而应该先实现:
|
||||
|
||||
统一符号索引 → 稳定知识身份 → 引用绑定 → 契约验证 → EKC 复用。
|
||||
|
||||
还有一点值得特别强调:我不赞成为了建立知识系统,再单独实现一个与 Marqdo 解释器并列的“知识编译器”。那样会重新制造你希望消除的表示碎片。
|
||||
|
||||
更合适的架构是让现有 Marqdo 编译管线产出统一的语义中间表示,然后由运行时、View、EKC 和 Agent 各自消费。
|
||||
|
||||
这意味着 Marqdo 的知识体系不是一个外挂的 RAG 框架,而是语言本身的语义能力。
|
||||
|
||||
我认为这才是整个设计中最值得投入资源,也最有可能形成独立研究贡献的部分。
|
||||
+374
@@ -0,0 +1,374 @@
|
||||
请你重新阅读marqdo的官方库,掌握marqdo的最新进度。在我对marqdo项目的仔细审视之下我发现有一点没有闭环,我终于找到了,考虑现在智能体开发最常用的SKILL,这是一个markdown文件写明了智能体该干什么,我想要更推荐一步,因为marqdo使用markdown语法,支持叙述和代码相互混合,这就使得marqdo满足这样一个条件,当分章节的SKILL撰写下来,只要经过调整就能成为一份marqdo代码其中包含若干函数,我打算开发新的CLI命令marqdo > 函数名 函数参数或者marqdo call 函数名 函数参数 此时SKILL的不同章节就变成了不同的函数,智能体就真正的成为了将知识复现的作用,这让代码即文档、文档即知识,知识即可执行推进了一步变成了知识即工具,真正发挥了marqdo的优势,同样这样的执行还以为着智能体能够自行改进SKILL并接受确定的问题后修改而不会出错,这让自我进化的智能体成为了具备理论支撑和清晰边界的可能
|
||||
|
||||
# Marqdo 从“可执行知识”走向“知识即工具”:最新仓库审查与架构建议
|
||||
|
||||
我认为你这次找到了 Marqdo 一个非常重要、而且比单纯增加 `marqdo call` 命令更深层的突破口。
|
||||
|
||||
你实际上提出了一个新的统一关系:
|
||||
|
||||
> SKILL 是人和 AI 都能阅读的操作知识;Marqdo 可以让其中具有确定性执行语义的章节,直接成为可调用的工具。
|
||||
|
||||
这样,Agent 的职责就有机会从“阅读说明、理解步骤、临时生成实现”,转向“定位已有能力、填入参数、执行和验证结果”。
|
||||
|
||||
这与 Marqdo 原来的三句话是连续的,不需要推翻原来的定位:
|
||||
|
||||
代码即文档 → 文档即知识库 → 知识即可执行 → 知识即可作为工具使用。
|
||||
|
||||
不过我建议把“知识即工具”视为可执行知识的对外使用形态,而不是再创造一套与语言、知识库平行的 Skill 运行系统。
|
||||
|
||||
## 一、重新检查仓库后的最新情况
|
||||
|
||||
本次核对的是 [cflmy/marqdo](https://github.com/cflmy/marqdo?utm_source=chatgpt.com) 的 `main` 分支,HEAD 为 `4018e992`,`Cargo.toml` 版本为 2.1.5。最近的 v2.1.5 版本记录日期是 2026 年 10 月 27 日。
|
||||
|
||||
与我们之前讨论 v2.0.0 时相比,项目已经完成了不少与你的构想直接相关的基础建设。
|
||||
|
||||
| 相关能力 | 最新仓库证据 | 判断 |
|
||||
| --------------------- | ---------------------------------------------------------------- | -------- |
|
||||
| 跨文档确定性函数绑定 | `BoundCall`、`SymbolId`,Tree/Bytecode 双后端测试 | 已有核心基础 |
|
||||
| 已编译知识的执行复用 | MLSP `artifact.bind`、`artifact.execute`、`artifact.reuse_execute` | 已有子集 |
|
||||
| Agent 复用已有函数 | `agent_eng_bind_execute`、发布门禁 | 已有子集 |
|
||||
| 指定函数执行 | `marqdo run --call-lib-path`、JSON 参数、隔离 worker | 已有底层入口 |
|
||||
| 智能体工具规范 | `ToolSpecV1`、效应分类、权限检查与恢复设计 | 已有框架基础 |
|
||||
| 章节式 SKILL 自动成为 CLI 工具 | 目前没有独立的 `marqdo call` 或 Skill 编译命令 | 待开发 |
|
||||
| SKILL 自修改、自动测试和受控发布 | 已有局部修改、验证与沙盒组件 | 尚未形成完整闭环 |
|
||||
|
||||
因此,现在不是重新开发一个 Skill 执行器,而是将已存在的 Marqdo 函数、知识制品、工具协议和 Agent 机制统一起来。
|
||||
|
||||
还有一个与你的新构想直接相关的问题值得先修复:
|
||||
|
||||
最新官方 `skills/marqdo/SKILL.md` 的核心语法说明,与仓库中的现行解析器、v0.3 语法规范和可执行测试存在冲突。
|
||||
|
||||
目前解析器与测试使用的是:
|
||||
|
||||
- `**…**`:代码、赋值、调用等语句;
|
||||
- `*…*`:返回值。
|
||||
|
||||
但官方 Skill 顶部却把两者反过来描述。这不是小的文档笔误:如果 Agent 按照错误规则自我修改 Skill,就可能产生与实际运行时不一致的程序。
|
||||
|
||||
这个真实存在的不一致,恰好证明了你所说的闭环为什么重要——SKILL 不能仅靠自然语言说明自己的正确性,它需要由语言编译器和实际测试提供独立验证。
|
||||
|
||||
## 二、你真正提出的是一种新的 Skill 体系
|
||||
|
||||
我建议把它暂时命名为 Executable Skill(可执行技能)。
|
||||
|
||||
它不应被理解为“给 Markdown Skill 增加一点代码”,而应当满足一个更严格的定义:
|
||||
|
||||
> Executable Skill 是一份以 Markdown 为人类可读接口、以 Marqdo 函数为确定性执行单元、以编译后的语义制品为工具身份、能够由 Agent 发现、调用、验证和改进的技能文档。
|
||||
|
||||
传统 Skill 与你的目标之间,存在一个非常重要的区别。
|
||||
|
||||
| 维度 | 普通 Markdown Skill | Marqdo Executable Skill |
|
||||
| ---- | ----------------------- | ----------------------- |
|
||||
| 技能说明 | 自然语言 | 自然语言 |
|
||||
| 操作步骤 | Agent 阅读后自行实施 | 可以绑定已有 Marqdo 函数 |
|
||||
| 函数接口 | 通常需要额外编写工具代码 | 从 `.mq.md` 的函数和契约生成 |
|
||||
| 执行 | 依赖 Agent 选择工具、生成代码或操作软件 | 对已实现的步骤直接执行 |
|
||||
| 输出验证 | 往往需要单独建立 | 可连接编译器、契约和测试 |
|
||||
| 改进 | 编辑说明或脚本 | 编辑同源的知识与实现,验证后发布 |
|
||||
| 可追踪性 | 主要依赖工具日志 | 可关联 SymbolId、源码、版本和执行结果 |
|
||||
|
||||
但不是每个 Skill 章节都应该自动变成可执行函数。
|
||||
|
||||
比如“适用场景”“注意事项”“禁止操作”是知识或约束;“检查订单”“生成报价”“汇总报告”才可能成为可调用能力。编译器应区分文档章节与可执行章节,不能把所有二级标题不加判断地暴露成工具。
|
||||
|
||||
### 这实际上使 Agent 的结构发生变化
|
||||
|
||||
SKILL.md
|
||||
|
||||
目标 · 流程 · 函数 · 契约 · 示例 · 约束
|
||||
|
||||
Marqdo Skill Compiler
|
||||
|
||||
章节解析 · 符号绑定 · 类型检查 · 效应分析
|
||||
|
||||
Knowledge View
|
||||
|
||||
Agent 阅读技能与限制
|
||||
|
||||
Tool Registry
|
||||
|
||||
Agent 调用已编译函数
|
||||
|
||||
Agent:选择、组合、执行、观察与改进
|
||||
|
||||
由语言运行时执行确定性部分,由模型处理非确定性判断
|
||||
|
||||
特别值得注意的是:这不仅是执行接口的统一,还是知识交付接口的统一。
|
||||
|
||||
同一份 Skill 能够投影成可读说明、CLI 函数、Agent Tool Schema、MCP 工具描述,以及知识库中的能力节点。实现这些投影的系统仍是同一个 Marqdo 编译器。
|
||||
|
||||
## 三、CLI 应采用 `marqdo call`,不要采用 `marqdo >`
|
||||
|
||||
你提出了两个命令形式:
|
||||
|
||||
```
|
||||
marqdo > 函数名 函数参数
|
||||
marqdo call 函数名 函数参数
|
||||
```
|
||||
|
||||
我明确建议采用第二种。
|
||||
|
||||
原因是 `>` 在 Bash、PowerShell、CMD 等 Shell 中已经具有输出重定向语义。`marqdo > xxx` 会被 Shell 先行解释,无法可靠地作为传递给 Marqdo 的函数调用语法。
|
||||
|
||||
推荐设计为:
|
||||
|
||||
```
|
||||
# 按函数名调用
|
||||
marqdo call "订单计算.商品小计" \
|
||||
--skill ./skills/order-calculator \
|
||||
--arg 单价=30 \
|
||||
--arg 数量=2
|
||||
|
||||
# 结构化调用,供 Agent 使用
|
||||
marqdo call "订单计算.商品小计" \
|
||||
--skill ./skills/order-calculator \
|
||||
--args-json inputs.json \
|
||||
--output json \
|
||||
--policy pure
|
||||
```
|
||||
|
||||
上述是建议新增的 CLI 接口,不是 v2.1.5 已支持的命令。
|
||||
|
||||
我还建议在 CLI 层保留一个便利别名:`marqdo skill call`。它与 `marqdo call` 进入同一个 dispatcher,不应分别实现两套调用逻辑。
|
||||
|
||||
### 最小必要的 CLI 能力
|
||||
|
||||
| 命令 | 作用 |
|
||||
| ---------------------------- | ----------------------- |
|
||||
| `marqdo skill inspect PATH` | 解析 Skill 文档、章节、可调用函数和依赖 |
|
||||
| `marqdo skill list PATH` | 列出对 Agent 暴露的工具 |
|
||||
| `marqdo skill check PATH` | 检查语法、绑定、签名、效应和工具导出规则 |
|
||||
| `marqdo call TARGET` | 调用指定 Marqdo 函数并返回结果 |
|
||||
| `marqdo skill test PATH` | 执行 Skill 的测试与契约检查 |
|
||||
| `marqdo skill export PATH` | 生成通用工具描述或 MCP 暴露接口 |
|
||||
| `marqdo skill trial PATH` | 对修改后的候选版本进行隔离验证 |
|
||||
| `marqdo skill promote PATH` | 在门禁通过后发布新版本 |
|
||||
| `marqdo skill rollback PATH` | 恢复到指定已接受版本 |
|
||||
|
||||
不过不建议一次性实现这九项命令。最小可用产品只需要 `inspect`、`call`、`check`、`test` 四项,版本发布与改进机制可以随后补齐。
|
||||
|
||||
最重要的技术决策是:
|
||||
|
||||
`marqdo call` 必须调用现有编译器绑定的函数,不得重新用字符串搜索源码、猜测章节位置再执行。
|
||||
|
||||
当前 [src/mlsp.rs](https://github.com/cflmy/marqdo/blob/main/src/mlsp.rs?utm_source=chatgpt.com) 已有 `artifact.bind` 与 `artifact.execute`,能够检查制品指纹、依赖闭包、来源摘要和效应策略。新的 CLI 应复用相同的应用服务和语义校验,而不是通过进程内调用 MLSP JSON 接口制造另一层重复协议。
|
||||
|
||||
还有一个现有实现细节:`marqdo run --call-lib-path` 已支持隔离 worker 通过 JSON 参数调用函数,但当前 `src/lib.rs` 的这个入口只在树遍历分支中处理,Bytecode 分支仍按普通程序入口执行。新的公开 `call` 命令需要补齐这一差异,或者明确在第一版只支持 Tree backend,不能静默忽略所选后端。
|
||||
|
||||
## 四、完整示例:让一份 Skill 同时成为文档、知识和工具
|
||||
|
||||
我建议第一版尽量保持作者体验简单:人只维护一份 Markdown 源文件,编译器自动生成工具描述、函数索引和知识制品。
|
||||
|
||||
例如,我们建立一个订单计算 Skill。
|
||||
|
||||
下面是目标设计示例。其中 `runtime` 和 `tools` 是我建议为 Skill 编译增加的元数据约定,目前不能将这份 `SKILL.md` 直接交给 v2.1.5 的 CLI,期待自动注册工具。
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
name: order-calculator
|
||||
description: 订单价格计算,包括商品小计和含税金额
|
||||
runtime: marqdo
|
||||
tools:
|
||||
- 订单计算.商品小计
|
||||
- 订单计算.含税金额
|
||||
---
|
||||
|
||||
# 订单计算
|
||||
|
||||
这份技能用于计算订单金额。
|
||||
|
||||
所有金额使用同一货币单位。税率使用小数表示,
|
||||
例如 0.10 表示 10%。
|
||||
|
||||
## 商品小计
|
||||
|
||||
给定商品单价`单价`和购买数量`数量`,
|
||||
计算未税商品小计。
|
||||
|
||||
*[商品小计](单价 * 数量)*
|
||||
|
||||
## 含税金额
|
||||
|
||||
给定商品单价`单价`、购买数量`数量`
|
||||
和适用税率`税率`,计算含税金额。
|
||||
|
||||
**小计 = [计算商品小计](订单计算.商品小计(单价=单价, 数量=数量))**
|
||||
|
||||
*[最终含税金额](小计 * (1 + 税率))*
|
||||
|
||||
```
|
||||
|
||||
这里的计算是演示规则。正式业务技能还需要校验数量范围、金额精度、货币单位、税率适用条件与舍入规则;这些不能由函数名字自动推断为正确。
|
||||
|
||||
### 这份 Skill 会产生三种投影
|
||||
|
||||
给人阅读: 它是一份正常的 Markdown 文档。读者能理解每个步骤的目的,以及所需输入和返回值。
|
||||
|
||||
给 Marqdo 编译器: 两个 `##` 单元构成可解析的函数;第二个函数可以确定性地调用第一个函数;符号索引能够记录它们的依赖关系。
|
||||
|
||||
给 Agent 使用: 编译器输出两个工具的结构化描述。Agent 不需要重新生成乘法计算程序,只需选择工具并提供参数。
|
||||
|
||||
例如,编译后的工具描述可以是:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "order-calculator::订单计算.商品小计",
|
||||
"description": "计算未税商品小计",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"单价": {"type": "number"},
|
||||
"数量": {"type": "number"}
|
||||
},
|
||||
"required": ["单价", "数量"]
|
||||
},
|
||||
"output_schema": {
|
||||
"type": "number"
|
||||
},
|
||||
"effect": "pure"
|
||||
}
|
||||
```
|
||||
|
||||
但这个 Schema 必须由明确的类型契约和编译器检查生成。若源文件没有足够的类型信息,应标记为未知或要求补全,不能因为变量参加了乘法就无条件断言它一定是 `number`。
|
||||
|
||||
需要强调:不是 `##` 标题自动等于一个公开工具。 `##` 让章节具备 Marqdo 函数的结构,`tools` 则声明哪些函数允许对外暴露。这样才能避免“安全说明”一类章节被意外注册成工具,也避免内部辅助函数被 Agent 随意调用。
|
||||
|
||||
### 为什么采用显式的 `runtime: marqdo`?
|
||||
|
||||
因为普通 Skill 的 Markdown 本来就可能包含 `**加粗内容**`、编号列表、代码块和二级标题。这些在现有 Marqdo 中可能具有执行语义。
|
||||
|
||||
如果直接把所有 `SKILL.md` 当成 `.mq.md` 执行,很可能发生严重的语义误读。
|
||||
|
||||
所以我建议:
|
||||
|
||||
- 未明确声明 Marqdo 运行时的 `SKILL.md`,仍然是普通 Markdown 文档。
|
||||
- 明确声明 `runtime: marqdo` 的 Skill 才进入 Marqdo 编译流程。
|
||||
- 内嵌示例代码块不应因展示而执行。
|
||||
- 编辑器应对具有执行意义的 Markdown 标记提供可视化提示。
|
||||
- 导出的工具必须经过独立检查和授权。
|
||||
|
||||
未来还可以支持从已有普通 Skill 中自动提取候选函数,但那应当是生成可审阅的转换补丁,而不是默认把自然语言步骤当成已经实现的代码。
|
||||
|
||||
## 五、这次最有价值的部分:自我改进的 Skill
|
||||
|
||||
你提出的第二层意义,我认为甚至比 `marqdo call` 更值得研究。
|
||||
|
||||
传统 Agent 修改一个 Skill 时,常见问题是:它修改了一段说明或脚本,却无法可靠判断其他步骤是否受到影响。
|
||||
|
||||
Marqdo 已经具备一些适合解决这个问题的基础,例如 `SymbolId`、依赖闭包、`artifact.patch`、`artifact.verify` 和知识影响分析。
|
||||
|
||||
但是,不能由此推出“智能体修改 Skill 就不会出错”。
|
||||
|
||||
更精确的目标是:智能体可以提出改进,系统能够判定一组明确、可测试的性质是否被保持,并且只有通过门禁的版本才有资格替换原有 Skill。
|
||||
|
||||
我建议采用以下演化协议:
|
||||
|
||||
已发布 Skill v1
|
||||
|
||||
现有稳定版本与完整依赖
|
||||
|
||||
1\. 发现确定的问题
|
||||
|
||||
失败测试、诊断、复现步骤或用户提出的明确修改要求
|
||||
|
||||
2\. AI 生成局部修改候选
|
||||
|
||||
只修改获准的章节或函数,记录版本与修改意图
|
||||
|
||||
3\. 编译与静态验证
|
||||
|
||||
语法、符号、参数、返回类型、效应、依赖关系
|
||||
|
||||
4\. 隔离测试与回归验证
|
||||
|
||||
目标问题修复、历史行为保持、异常输入、性能与权限边界
|
||||
|
||||
5\. 发布门禁
|
||||
|
||||
仅当策略允许且必要验证通过时晋升新版本;否则保留旧版本
|
||||
|
||||
Skill v2 · 已接受版本
|
||||
|
||||
可追溯、可回滚、后续调用绑定到明确版本
|
||||
|
||||
### 举一个真正的自我改进案例
|
||||
|
||||
原 Skill 中存在:
|
||||
|
||||
```
|
||||
## 商品小计
|
||||
|
||||
商品单价`单价`,购买数量`数量`。
|
||||
|
||||
*[小计](单价 * 数量)*
|
||||
```
|
||||
|
||||
现在发现一个确定的问题:输入 `数量=-1` 时,函数返回负数,但业务要求数量必须大于零。
|
||||
|
||||
Agent 不应该只是把说明修改成“数量必须大于零”。这不会改变执行行为。
|
||||
|
||||
它应当在候选版本中增加可执行的校验逻辑,并补充至少三个测试:
|
||||
|
||||
| 测试 | 输入 | 期望 |
|
||||
| ---- | ----------- | ------------- |
|
||||
| 正常订单 | 单价 30,数量 2 | 返回 60 |
|
||||
| 非法数量 | 单价 30,数量 -1 | 返回结构化参数错误 |
|
||||
| 边界数量 | 单价 30,数量 0 | 根据业务契约决定接受或拒绝 |
|
||||
|
||||
如果 Marqdo 尚不具备合适的语言级错误返回或异常处理方式,这个案例还会暴露一个语言能力缺口:需要一种由 Marqdo 程序自身构造、传递和处理错误的机制,而不是只能依赖 Rust 宿主报错。
|
||||
|
||||
这与此前我们讨论的通用语言能力重构是直接关联的。
|
||||
|
||||
### 自我进化的边界必须比普通代码修改更严格
|
||||
|
||||
我建议把以下约束固定下来:
|
||||
|
||||
1. 修改不能自动扩大权限。 原 Skill 只有纯计算权限,新版本不能因为 Agent 自己添加网络或文件操作就获得这些权限。
|
||||
2. 候选版不能直接覆盖运行中的正式版本。 需要隔离工作区、原子发布和固定引用版本。
|
||||
3. 必须证明目标问题被修复。 不允许通过删除测试、放宽断言或隐藏失败来宣称成功。
|
||||
4. 测试通过不是绝对正确的证明。 未覆盖的业务情况、外部事实和依赖服务仍可能出错。
|
||||
5. 高风险修改需要更严格的发布决策。 尤其是支付、外部写入、删除、凭证和安全策略变更,不能由被修改的 Skill 自己批准。
|
||||
|
||||
最新仓库的 `artifact.patch` 已经提供基于摘要的修改和有限回滚,但它还不是完整的候选版本事务与测试后晋升系统。现有 `HostCaps` 的默认值也允许文件写入、执行、网络和插件,因此新 `call` 的安全默认值应当收紧,不能简单继承普通本地运行的全部宿主权限。
|
||||
|
||||
这就是“有界自我进化”的含义:不保证 Agent 永不犯错,而是让它能够在可验证、可回滚、可限制权限的范围内持续改进。
|
||||
|
||||
## 六、我建议如何安排开发
|
||||
|
||||
| 阶段 | 目标 | 关键验收 |
|
||||
| ---------------- | ---------------------------------------- | ------------------------ |
|
||||
| S0 · Skill 语义一致性 | 修复官方 Skill 与解析器的标记冲突,建立 Skill 语法同步测试 | Skill 记载的每条核心语法都有可运行金样例 |
|
||||
| S1 · 函数调用 CLI | `marqdo call` 调用已绑定的普通函数、类函数和跨文档函数 | JSON 参数正确绑定;错误路径和双后端行为明确 |
|
||||
| S2 · Skill 编译 | 对显式启用的 `SKILL.md` 解析章节和可执行函数 | 自动产生 SymbolId、签名、依赖、导出清单 |
|
||||
| S3 · 知识即工具 | 将公开函数编译为 ToolSpec,并接入现有 Agent dispatcher | Agent 不重新生成实现即可调用并取得结果 |
|
||||
| S4 · Skill 测试 | 增加 `skill check/test`、负例、效应门禁和回归测试 | 未通过验证的 Skill 不得自动发布 |
|
||||
| S5 · Skill 演化 | 实现候选修改、隔离验证、影响分析、版本晋升与回滚 | 修改失败不影响已发布版本,权限不能自行扩大 |
|
||||
|
||||
这里还需要一项对你的研究目标尤其重要的对照实验。
|
||||
|
||||
让相同模型分别使用普通 Markdown Skill、Markdown Skill 加外部脚本工具、以及 Marqdo Executable Skill 完成相同的一组任务。分别测量正确率、模型需要重新生成的代码量、工具调用参数错误、修改后的回归失败率、token 消耗和完成时间。
|
||||
|
||||
只有与“Markdown + 现有工具调用”进行公平对照,才能证明 Marqdo 的优势来自文档、程序与知识的统一,而不只是因为它额外提供了一个执行器。
|
||||
|
||||
## 七、我对这项构想的最终评价
|
||||
|
||||
我认为这次构想具有三个非常值得肯定的性质。
|
||||
|
||||
第一,它有明确的语言基础。`#`、`##`、自然语言叙述、函数参数、`[]()`、契约表和跨文档符号绑定并不是为了 Skill 重新创造的。Skill 可以成为现有语言的一种应用形态。
|
||||
|
||||
第二,它有真实的工程基础。当前 Marqdo 已经具备部分确定性绑定、制品验证、Agent 复用与隔离运行能力。你需要做的是将这些能力收敛到统一的公开接口,而不是重新实现一套 Agent 框架。
|
||||
|
||||
第三,它能够引出一个更有研究价值的问题:自然语言描述的操作知识,如何逐步转化为可调用、可检查、可维护,并可由 Agent 在受限条件下自行改进的程序制品?
|
||||
|
||||
但是,“SKILL 章节即函数”本身还不足以证明新的编程范式。Markdown 章节映射函数,与文学编程、文档驱动工作流及现有工具包装有明显的共同点。
|
||||
|
||||
更有价值的是把三个原本需要单独维护的对象——Skill 说明、函数实现、Agent Tool Schema——统一为一个可编译的源事实,并展示这种统一确实降低了错误、维护成本和重复生成成本。
|
||||
|
||||
我建议为 Marqdo 保留原来的核心理念,并将这一阶段的技术方向明确为:
|
||||
|
||||
> 知识即工具(Knowledge as Tool):将可执行知识直接编译为 Agent 能够发现、调用和验证的工具,并允许智能体在明确的语义、测试和权限边界内持续改进这些知识。
|
||||
|
||||
这可能是 Marqdo 从“AI 可以使用的编程语言”,进一步走向“AI 能够使用并维护的可执行知识体系”的关键一步。
|
||||
|
||||
备注,这里实际上有一点叙述错误,marqdo支持mq.md文件,所以最好针对SKILL也是SKILL.mq.md这样会比较统一。
|
||||
+249
@@ -0,0 +1,249 @@
|
||||
SKILL的名称应该是.mq.md有一点必须提及,SKILL其实命名不一定必须得是SKILL,平常的一个marqdo文件也可以是一份skill这里的设计太复杂了没有抽离出来核心本质,你看对于一个平常的marqdo文件,完全也可以和SKILL一样,这都是没有区别的,所谓的知识即工具作为高度抽象本质就是带参数调用函数,所以你的inspect等等命令其实完全可以对传统的marqdo也生效而不是非要绑定SKILL对吧,而且这样处理还有好处是方面智能体做单元测试,单个函数是否可以带参数直接运行,换句话说,你仔细思考就会发现这些好处是marqdo的设计哲学在增加一点点call自然派生的优势,所以不需要繁复的设计
|
||||
|
||||
你说得对。这次我认为你抓住了真正的核心,而且我的上一版设计确实把一个本来很自然的语言能力复杂化了。
|
||||
|
||||
Marqdo 根本不需要引入一种叫作 Executable Skill 的新概念,也不需要专门建立 Skill 编译器。
|
||||
|
||||
因为在 Marqdo 的设计哲学下:
|
||||
|
||||
> 一个 `.mq.md` 文件本身就是文档、知识与程序。只要允许从外部直接调用其中的函数,它自然也就能够成为 Skill。
|
||||
|
||||
这不是为 Skill 开发一套新系统,而是为 Marqdo 补齐一个非常基础的语言使用入口。
|
||||
|
||||
## 一、真正缺少的只有一件事:函数级执行入口
|
||||
|
||||
Marqdo 当前已经支持函数定义、参数、返回值、模块引用,以及确定性符号绑定。
|
||||
|
||||
但是日常使用时,我们往往仍然站在“运行整个文件”的角度:
|
||||
|
||||
```
|
||||
marqdo run example.mq.md
|
||||
```
|
||||
|
||||
你现在提出的是:
|
||||
|
||||
```
|
||||
marqdo call example.mq.md 函数名 参数
|
||||
```
|
||||
|
||||
这实际上意味着:
|
||||
|
||||
Marqdo 的最小可执行单位,从文件进一步扩展为文件中的任意可调用函数。
|
||||
|
||||
而这一点会自然派生大量优势。
|
||||
|
||||
普通 `.mq.md` 文件
|
||||
|
||||
自然语言叙述 + 函数 + 参数 + 返回值
|
||||
|
||||
marqdo call
|
||||
|
||||
指定函数 + 绑定参数 + 直接执行
|
||||
|
||||
知识复用
|
||||
|
||||
调用已存在的实现
|
||||
|
||||
Agent Skill
|
||||
|
||||
直接暴露函数为工具
|
||||
|
||||
单元测试
|
||||
|
||||
逐个函数验证结果
|
||||
|
||||
自我改进
|
||||
|
||||
修改函数并重新测试
|
||||
|
||||
这里不存在四套实现,只有一个底层能力的四种使用方式。
|
||||
|
||||
## 二、一个普通的 Marqdo 文件就足够了
|
||||
|
||||
比如,文件 `calculator.mq.md`:
|
||||
|
||||
```
|
||||
# 计算器
|
||||
|
||||
这是一个普通的 Marqdo 文档。
|
||||
|
||||
其中包含一些可以复用的数学计算知识。
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
|
||||
## 乘法
|
||||
|
||||
计算两个数字`a`和`b`的积。
|
||||
|
||||
*[计算结果](a * b)*
|
||||
```
|
||||
|
||||
它既是可阅读的文档,也包含两个函数。
|
||||
|
||||
现在只需要支持:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```
|
||||
5
|
||||
```
|
||||
|
||||
再比如:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.乘法 a=4 b=6
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```
|
||||
24
|
||||
```
|
||||
|
||||
以上 `marqdo call` 是拟新增的命令形式;函数示例遵循当前 `*…*` 返回、`[]()` 遮蔽的语义。
|
||||
|
||||
这时候,一个 Agent 只要能够读取这个 `.mq.md` 文档,就可以理解函数的用途;只要能够调用 Marqdo CLI,就能执行其中的能力。
|
||||
|
||||
它根本不需要关心这个文件是不是 Skill,也不需要一份特殊的 `SKILL.md`。
|
||||
|
||||
如果 Agent 把它当成 Skill 阅读和使用,它就是 Skill;如果开发者把它当成程序库调用,它就是程序库;如果研究者把它作为知识库中的一部分,它就是可执行知识。
|
||||
|
||||
文件的身份没有变化,变化的是使用方式。
|
||||
|
||||
## 三、这项能力会自然解决三个问题
|
||||
|
||||
### 1. 让知识成为工具
|
||||
|
||||
传统 Skill:
|
||||
|
||||
Agent 阅读操作说明,决定如何完成任务。
|
||||
|
||||
Marqdo:
|
||||
|
||||
Agent 阅读函数说明,找到适合的函数,传入参数,直接执行。
|
||||
|
||||
这就将原来的:
|
||||
|
||||
知识 → Agent 理解 → 重新实现 → 执行
|
||||
|
||||
缩短为:
|
||||
|
||||
知识 → 函数定位 → 参数调用 → 执行
|
||||
|
||||
但模型仍然需要负责判断应该调用哪个函数、传入哪些参数。确定性的是被调用函数的语言语义,而不是整个 Agent 决策过程。
|
||||
|
||||
### 2. 让单元测试成为语言的天然能力
|
||||
|
||||
我非常赞同你提到的单元测试价值。
|
||||
|
||||
有了 `marqdo call`,可以直接测试:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
# 期望 5
|
||||
|
||||
marqdo call calculator.mq.md 计算器.加法 a=-2 b=3
|
||||
# 期望 1
|
||||
|
||||
marqdo call calculator.mq.md 计算器.乘法 a=0 b=100
|
||||
# 期望 0
|
||||
```
|
||||
|
||||
不必为了测试一个函数,再创建一个 `# main`,再编写调用、打印和结果检查的包装程序。
|
||||
|
||||
未来即使增加 `marqdo test`,底层仍然可以复用同一个函数调用接口。
|
||||
|
||||
### 3. 让 Agent 可以针对知识进行局部改进
|
||||
|
||||
这是你提出的最有意义的延伸。
|
||||
|
||||
假设一个 Agent 发现 `计算器.乘法` 对某类输入存在错误。
|
||||
|
||||
它可以:
|
||||
|
||||
1. 阅读相应函数及其上下文。
|
||||
2. 修改这个 `.mq.md` 文件中的函数实现。
|
||||
3. 直接用 `marqdo call` 传入错误输入验证。
|
||||
4. 再运行该函数的历史测试。
|
||||
5. 如果检查通过,就提交候选修改;否则保留原有实现。
|
||||
|
||||
这使得 Agent 的改进对象不再仅仅是自然语言提示词,而是有明确输入、输出和可执行语义的知识单元。
|
||||
|
||||
当然,测试不能证明函数在所有输入上都正确;正式发布和权限控制仍需要遵循已有的项目验证机制。但不需要为此创造一套 Skill 专属的演化协议。
|
||||
|
||||
## 四、真正的 CLI 设计可以非常简单
|
||||
|
||||
我建议第一阶段只做一个命令:
|
||||
|
||||
```
|
||||
marqdo call <文件> <函数> [具名参数...]
|
||||
```
|
||||
|
||||
比如:
|
||||
|
||||
```
|
||||
marqdo call book.mq.md 订单.计算总价 单价=30 数量=2
|
||||
```
|
||||
|
||||
它只需要完成五件事:
|
||||
|
||||
| 步骤 | 职责 |
|
||||
| -- | -------------------- |
|
||||
| 1 | 加载指定 `.mq.md` 文件及其导入 |
|
||||
| 2 | 解析并唯一定位目标函数 |
|
||||
| 3 | 根据现有函数签名绑定、校验参数 |
|
||||
| 4 | 使用现有运行时执行该函数 |
|
||||
| 5 | 返回函数结果和结构化错误 |
|
||||
|
||||
额外提供一个 `--json` 输出选项就足够方便 Agent 调用。
|
||||
|
||||
如果未来需要 `marqdo inspect`,它也应该针对任何 `.mq.md` 文件,列出其中函数、参数和文档描述,而非限定 Skill。
|
||||
|
||||
此外,当前仓库已经有 `--call-lib-path` 和 `artifact.execute` 的相关基础,因此实现时应尽量复用现有函数定位与执行机制,而不是重复开发解释器。
|
||||
|
||||
唯一值得坚持的边界是:外部调用仍必须经过现有权限检查,不能因为新增了 `call` 就默认允许 Agent 对任意函数执行文件删除、网络写入等操作。
|
||||
|
||||
## 五、我认为你的设计哲学现在更加清晰了
|
||||
|
||||
你原来的理念:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
实际上已经足够完整。
|
||||
|
||||
“知识即工具”不是额外的设计理念,而是“知识即可执行”在函数级调用能力成熟后自然出现的结果。
|
||||
|
||||
进一步看,这件事还有一个很漂亮的对称性:
|
||||
|
||||
| 参与者 | 对同一个 `.mq.md` 的使用方式 |
|
||||
| ---------- | ------------------- |
|
||||
| 人类 | 阅读文档、理解知识 |
|
||||
| 编译器 | 解析并验证函数 |
|
||||
| 开发者 | 调用函数、组合程序 |
|
||||
| Agent | 发现知识、调用工具 |
|
||||
| 测试系统 | 输入参数、检查结果 |
|
||||
| 维护者或 Agent | 修改实现、验证改进 |
|
||||
|
||||
这些角色并没有要求作者维护六份不同的东西。
|
||||
|
||||
同一份文件,同一套语义,同一个函数调用接口。
|
||||
|
||||
这也恰恰是我认为 Marqdo 相比传统“Markdown 文档 + 外部工具”组合最值得证明的优势:知识描述与执行实现共址,而且能够直接由语言工具链消费,避免维护重复的工具包装和操作说明。
|
||||
|
||||
所以,我现在的建议与上一轮不同:
|
||||
|
||||
不要开发 Executable Skill 系统。不要设计 Skill 专属语法。不要引入新的 Skill 注册、编译和执行机制。
|
||||
|
||||
先完成 `marqdo call`,使普通 `.mq.md` 中的可调用函数都能被精确定位、传参执行,并用现有语义系统验证。
|
||||
|
||||
这是一个相对很小的接口变化,却可能自然打通 Marqdo 的编程、知识复用、Agent 工具调用和函数级测试四个场景。
|
||||
|
||||
我认为这才是你所说的:让 Marqdo 自己的设计哲学发挥作用,而不是不断增加外部框架来证明它的价值。
|
||||
@@ -0,0 +1,102 @@
|
||||
# 智能体能力调研与求道差距复核(2026-10-27)
|
||||
|
||||
| 项目 | 说明 |
|
||||
|---|---|
|
||||
| 状态 | Research / 设计输入;不是功能交付声明 |
|
||||
| 调研日期 | 2026-10-27,Asia/Shanghai |
|
||||
| 源码基线 | Marqdo `16f26d7d60ce9fbc62feb0e8e83f93951f7b53fe`;qdagent `68b757e02ebfb64833b5262b0c8a683512581e8b` |
|
||||
| 框架设计 | [Agent 恢复、工具与资源协议](../design/agent-reliability-tools-resources-2026-10-27.md) |
|
||||
| 产品设计 | [求道智能体能力与预览体验](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级仓库) |
|
||||
|
||||
## 1. 方法与结论边界
|
||||
|
||||
先以 `git pull --ff-only` 同步两仓,再追踪真实调用链与前端入口;对比公开官方文档,不以营销介绍、工具数量或旧设计中的 done 标签代替实现证据。本次是静态源码复核与官方资料研究,没有启动部署实例,没有调用付费模型,没有进行竞品账号实测。因此,下表“源码确认”仅代表代码路径可见,“设计判断”与“待实测”不能写成已复现或已交付。
|
||||
|
||||
主流能力的共同方向是:可恢复的执行、结构化工具与资源、按需上下文、可追溯结果、独立产物展示。不同产品和模型支持范围不同;这里不是市场占有率调查,也不声称所有智能体都具备全部能力。求道应保留文档原生、EKC、验证后沉淀的定位,吸收机制,不引入第二套 Agent Runtime。
|
||||
|
||||
## 2. 官方资料与可借鉴机制
|
||||
|
||||
以下页面均在调研日实际打开;MCP 特意引用固定 `2025-06-18` 版本,作为兼容基线,不宣称它是最新协议。厂商专有能力必须探测,不能因为端点兼容 `/v1` 就认为全部可用。
|
||||
|
||||
| 编号 | 官方来源 | 已核实内容 | 对求道的设计启示 |
|
||||
|---|---|---|---|
|
||||
| S01 | [OpenAI Agents:集成与可观测性](https://developers.openai.com/api/docs/guides/agents/integrations-observability) | MCP 接入与运行、模型、工具等 tracing | 统一 call/attempt/span 关联;产品只显示阶段摘要,详细事件可展开 |
|
||||
| S02 | [OpenAI:Memory 与 Compaction](https://developers.openai.com/cookbook/examples/agents_sdk/building_reliable_agents_memory_compaction) | 区分当前任务上下文压缩、跨运行记忆、可审阅产物 | 历史不要无限拼接;完整产物不等于聊天全文 |
|
||||
| S03 | [LangGraph Persistence](https://docs.langchain.com/oss/python/langgraph/persistence) | checkpointer 保存 thread 状态,store 支撑跨 thread 数据 | 恢复执行状态和用户长期知识是两种生命周期 |
|
||||
| S04 | [LangGraph Interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) | 恢复时节点代码可能重新执行 | 检查点不能单独保证写操作只执行一次,必须记录效应与幂等键 |
|
||||
| S05 | [Claude Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | 工具定义按需进入模型上下文 | 工具多不代表每轮注入全部定义;检索后再校验权限 |
|
||||
| S06 | [Claude Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | 在执行环境中编排工具、筛选结果 | 大批量只读处理可减少模型往返;后置于基础工具可靠性 |
|
||||
| S07 | [Deep Agents overview](https://docs.langchain.com/oss/python/deepagents/overview) | 文件系统、上下文管理、子任务与可选规划能力 | 规划应按任务启用;简单问答不强制复杂工作流 |
|
||||
| S08 | [Gemini Tools](https://ai.google.dev/gemini-api/docs/tools) | 检索、URL、文件搜索、代码执行等工具面 | 覆盖“找资料—读内容—计算—形成产物”,不能只有工程检索 |
|
||||
| S09 | [Gemini File search](https://ai.google.dev/gemini-api/docs/file-search) | 文件检索与引用信息 | 命中要能定位原文,检索摘要不能代替源文件版本 |
|
||||
| S10 | [MCP Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) | schema、结构化结果、资源链接;annotations 有信任边界 | 工具结果包含短摘要和资源引用;注解不是权限凭证 |
|
||||
| S11 | [MCP Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) | URI 资源、读取和应用决定的上下文注入 | “预览”“加入上下文”“执行”必须是独立动作 |
|
||||
| S12 | [Claude Artifacts](https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them) | 产物在会话旁独立打开,可继续查看与编辑 | 右栏应承载正文;不应只提供离开当前会话的入口 |
|
||||
| S13 | [Mozilla PDF.js](https://mozilla.github.io/pdf.js/) | Web PDF 解析和渲染 | PDF 视觉预览和 OCR/知识提取分开交付 |
|
||||
| S14 | [DOMPurify 官方仓库](https://github.com/cure53/DOMPurify) | DOM 清洗、标签/属性配置;插入前清洗 | 替换前端正则“清洗器”,配合同源资源代理和 CSP |
|
||||
|
||||
上述设计启示是本次推导,相关性能收益、成本下降比例不照搬厂商基准。工程路线不绑定某个最新模型或套餐。
|
||||
|
||||
## 3. 源码事实清单
|
||||
|
||||
下列 qdagent 路径相对该仓库;Marqdo 路径相对本仓库。基线 commit 已固定,后续实现需按符号再定位。
|
||||
|
||||
| 编号 | 当前实现证据 | 结论与限制 |
|
||||
|---|---|---|
|
||||
| F01 | qdagent `agent/qdagent.mq.md::契约提示`、`ask` | ASK 和 BUILD 都要求完整六段式 `.mq.md`,包含 main、验证和元数据;普通回答变长有明确结构性诱因。不能断言这是唯一原因 |
|
||||
| F02 | 同文件 `ask` 的门禁修复分支 | `r2` 送入第二次门禁后,成功分支仍 `result = raw`;可能展示修复前内容,设计必须绑定同一 accepted candidate |
|
||||
| F03 | 同文件 `ask` 返回表 | `gated_error` 路径仍可能保留 `status=ok` 且返回 `ok=True`;必须明确业务失败与输送成功的不同含义 |
|
||||
| F04 | 同文件 `eng_tools` | 默认白名单是 `tool_find/reuse/bind/verify/summarize` 五个工程工具;不是整个框架只有五个工具,也不代表已覆盖网页、笔记、文件编辑 |
|
||||
| F05 | `ext/ai/agent.mq.md` | 有 step/plan/run、READ、CALL、观察压缩、工作簿和恢复接口;应扩展这些原语,不另造循环 |
|
||||
| F06 | `plugins/agent/src/resume.rs::resume_save` | JSON 直接 `fs::write`;现有恢复接口不等于具备原子检查点、工具效应对账及任意步骤自动续跑 |
|
||||
| F07 | `src/runtime/`、`src/workbench/capabilities.rs` | 已有隔离执行、取消、事件回放与读通道;这一轮是 Agent 级恢复补足,不重新规划整个进程池 |
|
||||
| F08 | qdagent `session-store.ts::resumeTurn` | 终态 completed/failed/interrupted 直接返回;已有事件续订,但终态消息补齐与中断后的执行恢复需分别处理 |
|
||||
| F09 | qdagent `DesktopFrame.tsx::RightNotesPanel` | 实际只有“查看全部笔记”导航至 `/notes`,没有侧栏笔记正文 |
|
||||
| F10 | 同文件 `RightFilesPanel`、`WorkspacePage.tsx::openFile` | 文件点击已调 `openTarget`;右栏取首个 workspace,根目录最多 40 个非目录项。不能笼统写“所有按钮都跳转” |
|
||||
| F11 | `DesktopFrame.tsx` 的 reader/rightbar 条件 | `DocumentReader` 与右侧 tab 容器互斥,且使用两套开关/宽度状态;不是统一的资源浏览面板 |
|
||||
| F12 | qdagent `NotesPage.tsx` detail | 剥离 frontmatter 后以 `whiteSpace: pre-wrap` 显示文本;没有 Markdown/Marqdo 正文结构渲染 |
|
||||
| F13 | qdagent `DocumentReader.tsx` | 已有 DocumentView、引用版本传递、请求代数防迟到覆盖;`profile_item` target 未进入读取分支,格式不是通用资源分派 |
|
||||
| F14 | 同文件 `sanitizeHtmlFragment` | 主要靠正则移除 script/事件/javascript URL;不能当作完整 HTML 白名单安全边界。未在本次做漏洞利用实验 |
|
||||
| F15 | `src/workbench/document_view.rs` | 有只读文档视图,注释与实现明确避开执行路径;已解析语义应继续复用 |
|
||||
| F16 | `src/workbench/capabilities.rs` | text/markdown 提取可用,pdf/docx/ocr 标 unavailable;提取能力与浏览器 PDF 预览能力须分别探测 |
|
||||
| F17 | qdagent `lib/web_search.mq.md` | 既有网页搜索桥使用 legacy 脚本和固定 `last_web_search.json`;存在并发覆盖设计风险,不能直接作为新工具通道 |
|
||||
| F18 | `plugins/agent/src/mcp_client.rs` | 已有 stdio connect/list/call/close;不能把本轮描述为“从零添加 MCP”,远程连接和资源能力需另验 |
|
||||
| F19 | qdagent `compose_messages` / `ask` | 对话按角色标记拼成字符串注入 standing;会话语义、上下文预算和外部内容信任层级仍需强化 |
|
||||
| F20 | qdagent `lib/workbench.mq.md::documents_read` | 临时文件名以秒和环境 RANDOM 构造,RANDOM 缺失又退到秒;设计仍需真正唯一临时文件。workspace 缺省 `.` 不应作为新授权资源接口规则 |
|
||||
|
||||
这些是本轮优先级依据。10-26 release notes 所列修复作为已有基础保留,但“Implemented(本仓)”不能替代浏览器、真实 HTTP、进程中断与模型输出的联合验收。
|
||||
|
||||
## 4. 能力覆盖与差距优先级
|
||||
|
||||
| 能力 | 当前基础 | 本轮目标 | 优先级 / 归属 |
|
||||
|---|---|---|---|
|
||||
| 自动纠错 | 一次文档门禁修复、plan patch | 分类错误、有限修复、正确结果替换、可恢复失败 | P0 / 两仓 |
|
||||
| 执行恢复 | 任务隔离、取消、事件回放、JSON checkpoint | 传输续订与执行续跑分离;效应对账 | P0 / Marqdo 原语,qdagent UX |
|
||||
| 回答长度 | 六段式文档、完整历史 | 直接回答、摘要+产物、显式详述三种表达 | P0 / qdagent 策略,Marqdo 输出通道 |
|
||||
| 资源阅读 | DocumentView / Locator | 笔记、工作文件、引用、产物统一入口 | P0 / 两仓 |
|
||||
| 侧栏预览 | 两套状态与导航入口 | 单一右栏,点击即预览,聊天不中断 | P0 / qdagent |
|
||||
| 工具使用 | 五工具默认白名单、MCP/库原语 | schema 注册、按需发现、资源读取/搜索/写入/验证 | P1 / 两仓 |
|
||||
| 联网研究 | legacy 搜索脚本 | search+fetch、来源时间、限量正文、可定位引用 | P1 / 两仓 |
|
||||
| 上下文与记忆 | EFI pack、profile、history | 分层上下文、预算、可编辑记忆、资源 pin | P1 / 两仓 |
|
||||
| 多格式 | 文档视图、文本提取 | text/md/mq/code/json/csv/image;PDF 后续 | P0→P1 / 两仓 |
|
||||
| 长任务与计划 | plan 工作簿 | 里程碑、预算、暂停/继续、产物进度 | P1 / 两仓 |
|
||||
| 多智能体与浏览器 | 不作为当前完成前提 | 有界委派、隔离执行、受控浏览器工具 | P2 / 框架主导 |
|
||||
| 可观测评测 | usage、事件与既有测试 | 工具/恢复指标、实际任务语料、回归门禁 | P0 起持续 / 两仓 |
|
||||
|
||||
## 5. 采用与暂缓的决策
|
||||
|
||||
采用:有界失败恢复;工具结果摘要+资源引用;结构化参数;步骤效应账本;产物与聊天投影分离;资源预览与“加入上下文”分离;用户可检查的引用;按需工具发现。原有源码、知识、工作簿与验证证据仍是权威,衍生视图可重建。
|
||||
|
||||
暂缓:全自动跨站电脑操作、任意外部 MCP 自动信任、默认多智能体协作、所有 Office 格式保真编辑、每次问答都规划/运行代码。它们不能先于当前恢复、工具授权和预览闭环。
|
||||
|
||||
不采用:把长回答直接 substring 截断、把失败原文当最终成功、前端断流即重发任务、把所有文件当 HTML、用网页内容改写 system 指令、把预览等同于执行可执行文档。
|
||||
|
||||
## 6. 必须补做的动态验证
|
||||
|
||||
1. 在真实聊天中验证六段式输出与门禁失败/修复的最终消息和持久产物是否一致。
|
||||
2. 丢弃最后一帧、断网、刷新、worker 崩溃分别注入,确认事件重放不重做工具副作用。
|
||||
3. 使用真实 HTTP 入口验证右栏笔记、嵌套文件、历史引用、跨 workspace 资源;不只调用兄弟辅助函数。
|
||||
4. 用恶意/畸形 HTML、路径与符号链接、过大文件验证预览隔离;no-exec 通过哨兵副作用测试。
|
||||
5. 对无凭证模型、text-only provider、不可用转换器做明确降级;记录版本与环境,禁止以 mock 成功声称上线成功。
|
||||
|
||||
后续设计文档中的时间、轮数、字符数、成功率阈值均为拟定验收目标,需用该语料校准。
|
||||
@@ -0,0 +1,194 @@
|
||||
# 跨仓 Agent 可靠性开发计划(2026-10-27)
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed / planning**;本文是排期与验收编排,**不是**已实现声明 |
|
||||
| 日期 | 2026-10-27(Asia/Shanghai) |
|
||||
| 基线 | Marqdo `6ffe5ce` / 2.1.4;qdagent `c4c976c`(设计文档基线曾为 `16f26d7` / `68b757e`;排期以当前 HEAD 为准) |
|
||||
| 协议真源 | [智能体能力补足设计](../design/agent-reliability-tools-resources-2026-10-27.md) |
|
||||
| 产品真源 | [qdagent 智能体能力与预览](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 证据 | [官方调研与 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品侧镜像 | [qdagent 开发计划镜像](../../../qdagent/doc/roadmap/agent-capabilities-development-2026-10-27.md) |
|
||||
|
||||
本文只编排依赖、落点、门禁与发布次序。**不发明第二套 Agent Framework**;不修改 `doc/next/`;不把 capability bit 在合同实测前标真。协议字段以设计文档为准,路线图只引用不另造 schema。
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;工具可发现、可验证、可审计;结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | ErrorV1、预算、CheckpointV2、效应账本、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | AgentOutput 分通道、输出预算、ContextPackV2 | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD |
|
||||
| 资源 | ResourceRef/View、只读预览、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
## 2. 现状(不再重做)
|
||||
|
||||
| 已落地基础 | 说明 |
|
||||
|---|---|
|
||||
| Agent A0–A4、O1–O5 | 文档原生 step/plan/run、沙盒与优化波次;扩展 `ext/ai/agent`,不另造循环 |
|
||||
| 隔离 Web 运行时(ADR 0009) | `src/runtime/` Verified;本轮补 Agent 步骤语义,不重建进程池 |
|
||||
| Workbench 合同切片 | DocumentView / Locator / capabilities;Partial,随本轮补 F 矩阵 |
|
||||
| 可执行知识 S0–S6 | 本地确定性子集已门禁;**不重开 S0–S6** |
|
||||
|
||||
本轮增量(设计已锁、代码待做):`AgentErrorV1`、`CheckpointV2` + effect ledger、`ToolSpecV1` 统一调度、`ResourceViewV1`、`AgentOutputV1` 通道、`ContextPackV2`。
|
||||
|
||||
**产品措辞约束**:本地门禁绿 ≠ 远程/多租户安全;≠「知识验证 + Agent 复用闭环」全产品完成。
|
||||
|
||||
## 3. 跨仓依赖与日历顺序
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
MA0[M-A0 contracts] --> QA0[Q-A0 fixtures]
|
||||
MA0 --> MA3[M-A3 ResourceView]
|
||||
MA0 --> MA1[M-A1 Error and Checkpoint]
|
||||
MA0 --> MA2[M-A2 ToolSpec]
|
||||
QA0 --> QA1[Q-A1 answer outcome]
|
||||
QA0 --> QA2[Q-A2 right panel]
|
||||
MA3 --> QA2
|
||||
QA1 --> QA3[Q-A3 recovery UX]
|
||||
MA1 --> QA3
|
||||
MA2 --> QA4[Q-A4 product tools]
|
||||
MA1 --> MA4[M-A4 channels ContextPack]
|
||||
MA2 --> MA4
|
||||
MA4 --> QA4
|
||||
MA3 --> QA5[Q-A5 formats]
|
||||
MA5[M-A5 ledger PDF MCP] --> QA5
|
||||
MA4 --> QA6[Q-A6 plan memory]
|
||||
MA5 --> QA7[Q-A7 connectors]
|
||||
MA6[M-A6 subagents] --> QA7
|
||||
```
|
||||
|
||||
### 3.1 强制顺序原则
|
||||
|
||||
1. 先 **M-A0 ∥ Q-A0** 冻结跨仓字段与缺陷 fixtures。
|
||||
2. 立刻 **Q-A1 + Q-A2 + M-A3(文本/md/mq)**——**不得**被完整 CheckpointV2 阻塞。
|
||||
3. **M-A1** 可先上只读重试 + 原子 checkpoint;**Q-A3** 终态快照可先行,写恢复等 effect ledger。
|
||||
4. 再 **M-A2 ∥ Q-A4** → **M-A4 / Q-A6** → **M-A5 / Q-A5** → **M-A6 / Q-A7**。
|
||||
5. 四类恢复必须分开:事件续订 / 步骤重试 / 工作流 resume(新 attempt + `resumed_from`)/ 答案再生成。
|
||||
|
||||
## 4. 阶段包明细
|
||||
|
||||
### Wave 0 — 合同
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A0** | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | Error/Tool/Resource/Output/Context 协议、旧适配、状态映射;capability **默认 false** | 跨仓字段冻结;未知字段/版本可降级 |
|
||||
| **Q-A0** | 缺陷样例、HTTP 路由清单、answer/resource fixtures;设计入口 | 固化 F01–F20 相关 fixtures;`mock`/`live` 证据区分 | 与 M-A0 字段一致;不把 mock 当 live |
|
||||
|
||||
### Wave 1 — 可见痛点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **Q-A1** | `agent/qdagent.mq.md`、`gateway/openai`、api 映射 | accepted candidate;`outcome` ≠ HTTP `ok`;摘要投影;ASK 不强制六节 | 修复后只展示 B;未通过不标成功(F01/F02/F03) |
|
||||
| **M-A3(首批)** | `src/workbench/document_view.rs`、新 `resource_view`、媒体适配 | ResourceRef/View;md/txt/code/mq 静态阅读;no-exec | 资源定位与安全语料通过(F15) |
|
||||
| **Q-A2** | `DesktopFrame`、panel store、`DocumentReader`、ResourcePanel/Preview | 统一右栏;笔记/文件点击不导航;同 renderer | 所有入口同预览(F09–F14) |
|
||||
|
||||
### Wave 2 — 恢复
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A1** | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、recovery/effects 模块 | ErrorV1、有界修复、accepted candidate 绑定、CheckpointV2 原子写 | 故障注入不重复写;旧记录不冒险自动恢复(F06) |
|
||||
| **Q-A3** | `execution/turns`、session store、`api.ts` | 终态快照补齐、恢复动作、错误卡 | 事件恢复 0 工具调用;写恢复须 ledger(F08) |
|
||||
|
||||
### Wave 3 — 工具与通道
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A2** | `plugins/agent/src/lib.rs`、`mcp_client.rs`、tool registry/dispatcher | ToolSpec/Call/Result;CALL+native 单通道;分页与结果资源 | 未授权调用为 0;失败结果结构正确(F04/F05/F18) |
|
||||
| **M-A4** | `ext/ai/agent.mq.md`、`plugins/llm`、`src/workbench/run_context.rs` | AgentOutput 通道、预算、ContextPackV2 | 原生与纯文本 provider fixture 可用(F01/F19) |
|
||||
| **Q-A4** | `agent/tools/`、工具目录、ContextAttachment | 业务工具;保留旧五工程工具别名 | 找→读→改→验证→预览真实闭环 |
|
||||
| **Q-A6** | 计划折叠、预算 UI、profile 忘记、候选沉淀 | ResponsePolicy UX、记忆边界 | 压缩与恢复不丢用户约束 |
|
||||
|
||||
### Wave 4 — 持久与格式
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A5** | `src/runtime/` 存储/事件适配、MCP 与转换插件 | ledger↔runtime 对账、PDF/Office 插件、远程 MCP | crash/restart 通过;诚实探测(F16–F18) |
|
||||
| **Q-A5** | JSON/CSV/图片/PDF UI、网页来源与页/行引用 | 格式扩展与转换进度 | 缺插件可读降级;PDF 不假称 OCR |
|
||||
| **M-A6 / Q-A7** | plan/subtask/sandbox;MCP 配置与委派 | 程序化工具、有界委派、可选浏览器 | **后置**;须证明收益与预算/效应可控 |
|
||||
|
||||
## 5. F01–F20 → 包映射
|
||||
|
||||
| ID | 摘要 | Marqdo | qdagent | 主要验收 |
|
||||
|---|---|---|---|---|
|
||||
| F01 | ASK/BUILD 强制六节 | M-A4 输出通道 | Q-A1 ResponsePolicy | QA-01、MA-T12 |
|
||||
| F02 | 修复后仍返回 raw | M-A1 accepted 绑定 | Q-A1 | QA-03、MA-T12 |
|
||||
| F03 | `gated_error` 仍 `status=ok` | M-A0/M-A1 ErrorV1 | Q-A1 envelope | QA-04 |
|
||||
| F04 | 默认仅五工程工具 | M-A2 registry | Q-A4 目录 | QA-17 |
|
||||
| F05 | 已有 step/plan/run | **扩展** agent.mq.md | — | 不另造 loop |
|
||||
| F06 | `resume_save` 裸 `fs::write` | M-A1 CheckpointV2 | Q-A3 UX | MA-T03/T04 |
|
||||
| F07 | runtime 已有 | 复用,不重建 | 接线恢复 API | — |
|
||||
| F08 | `resumeTurn` 终态直返 | 事件 vs 再执行分离 | Q-A3 快照补齐 | QA-13、MA-T05 |
|
||||
| F09–F12 | 右栏/笔记预览缺陷 | M-A3 ResourceView | Q-A2 | QA-06–QA-09 |
|
||||
| F13 | DocumentReader 非通用分派 | DocumentView 保留 mq;ResourceView 其它 | 预览分派 | QA-09 |
|
||||
| F14 | 正则 HTML 清洗 | 生产侧 allowlist | DOMPurify + CSP | QA-11、MA-T11 |
|
||||
| F15 | DocumentView no-exec | 保持;ResourceView 禁 run/verify | — | MA-T10 |
|
||||
| F16 | pdf/docx/ocr unavailable | M-A5 插件 + 诚实探测 | Q-A5 | QA-10 |
|
||||
| F17 | legacy web_search 临时文件 | 优先框架 net 工具 | 迁移工具 | QA-17、F20 |
|
||||
| F18 | MCP stdio 已有 | M-A2/5 timeout/cancel/remote | 连接器配置 | MA-T07 |
|
||||
| F19 | 历史字符串 standing | M-A4 ContextPackV2 | compose_messages | QA-19、MA-T13 |
|
||||
| F20 | 弱临时名;workspace `.` | 安全临时文件 + ResourceRef | 资源解析 | QA-08、MA-T11 |
|
||||
|
||||
## 6. 验收与发布
|
||||
|
||||
### 6.1 Marqdo 门禁(MA-T01–T14)
|
||||
|
||||
以设计文档 §10 为准;基础机制用确定性 fake provider/tool;真实 provider 少量单独 smoke 并记费用。摘要:
|
||||
|
||||
| 编号 | 必须观察到 |
|
||||
|---|---|
|
||||
| MA-T01 | 429 后成功:退避、计量、单一 accepted answer |
|
||||
| MA-T02 | schema 连续错:一次修复后停;无效参数不执行工具 |
|
||||
| MA-T03 | 写成功但 receipt 前提杀:unknown_effect→对账;写计数不增 |
|
||||
| MA-T04 | checkpoint 写一半杀进程:完整上一检查点或明确 corrupt |
|
||||
| MA-T05 | 终态事件丢失:快照恢复完整消息;工具次数不增 |
|
||||
| MA-T06 | 重复/并发恢复:同一幂等键一个 attempt |
|
||||
| MA-T07 | 取消 vs 重试:取消后无新工具调用 |
|
||||
| MA-T08 | 权限/版本变更:stale/conflict/forbidden |
|
||||
| MA-T09 | 伪造 CALL/system:不越白名单 |
|
||||
| MA-T10 | `.mq.md` 预览含写/联网:哨兵不变;只读或安全降级 |
|
||||
| MA-T11 | 格式/超长/路径逃逸:正确 renderer;越界拒绝;无注入 |
|
||||
| MA-T12 | 修复 A→B:answer/artifact/verification 均绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后:约束、待决效应、版本、预算不丢 |
|
||||
| MA-T14 | 旧 CALL/DocumentView:基础可用;缺失能力明确返回 |
|
||||
|
||||
先跑受影响的 Rust/Go/Marqdo 合同与隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标(须记录机器/并发/冷暖缓存):已缓存 100 KiB 文本视图服务端 p95 < 300 ms;核心工具发现 p95 < 100 ms。
|
||||
|
||||
### 6.2 qdagent 门禁(QA-01–QA-20)
|
||||
|
||||
以产品设计 §13 为准;路径必须 `serve → api → 权威业务函数 →` 真实前端。零容忍:重复写效应、预览执行副作用、跨 workspace 越权。
|
||||
|
||||
实现时:`python3 scripts/check-contracts.py`、相关 workbench 测试、前端 `npm test` / `npm run build`,再跑 Playwright;无服务时 E2E 须明确 skip/失败原因。
|
||||
|
||||
### 6.3 Feature flags 与灰度
|
||||
|
||||
建议开关:`agent_output_v2`、`resource_panel_v2`、`agent_tools_v1`、`agent_recovery_v2`。启用取决于 runtime capability + 服务端政策,不由前端单独决定。
|
||||
|
||||
灰度:内部单 workspace → 多 workspace → 真 provider/断网 → 默认开启。关闭恢复时必须停止接纳新恢复请求并保留 attempt 状态,**禁止**切回会盲重做写操作的旧路径。
|
||||
|
||||
兼容迁移:新增协议 → 双读 → 新写 → 验证 → 逐步移除旧适配。旧 resume JSON 可读但不能自动升级成带副作用保证的检查点。
|
||||
|
||||
## 7. 伴生轨(登记,不阻塞主线)
|
||||
|
||||
| 轨 | 动作 |
|
||||
|---|---|
|
||||
| 可执行知识 S0–S6 | **不重开**;消费 BoundCall/EKC;话术保持「本地子集」 |
|
||||
| 知识支撑 F0(M02/M03/M05) | **并行伴生**:provenance/closure invalidate、真 verify API、Skill 无冲突 |
|
||||
| Workbench Partial | 随 M-A0/M-A3 补 F 矩阵与 adapters;不重写 M00–M05 |
|
||||
| 语言 next-phase P3 / Wave B1 评测 | **延后** |
|
||||
| Web Document/Endpoint | 遵守 ADR 0007;禁止 compose_/json bag 回退 |
|
||||
|
||||
## 8. 下一步开工(第一刀实现切片)
|
||||
|
||||
确认本路线图入库后,**另开实现回合**(本文件仅文档):
|
||||
|
||||
1. **M-A0 + Q-A0**:合同与 fixtures
|
||||
2. **Q-A1**:raw→accepted、outcome 一致性
|
||||
3. **Q-A3 子集**:终态快照补齐
|
||||
4. **Q-A2 + M-A3 子集**:右栏真实预览(笔记 / md / mq / txt / code)
|
||||
|
||||
发布判据是 MA-T* / QA-* 与真实 HTTP/browser 证据,不是接口返回 200 或代码中出现某符号名。
|
||||
@@ -0,0 +1,17 @@
|
||||
# 计算器
|
||||
|
||||
这是一个普通的 Marqdo 文档。
|
||||
|
||||
其中包含一些可以复用的数学计算知识。
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
|
||||
## 乘法
|
||||
|
||||
计算两个数字`a`和`b`的积。
|
||||
|
||||
*[计算结果](a * b)*
|
||||
+1
-1
@@ -1 +1 @@
|
||||
2.1.4
|
||||
2.3.0
|
||||
+567
-29
@@ -67,7 +67,11 @@ One LLM turn via the semantic surface (`ask` / `stream`+`collect`). Returns `{te
|
||||
1. `stream`
|
||||
**evs = > model.stream prompt=`prompt` echo=`echo` stream_kind=`stream_kind`**
|
||||
**text = > llm.collect events=`evs`**
|
||||
**tokens = 0**
|
||||
**tokens = > llm.collect_usage events=`evs`**
|
||||
1. `tokens` == None
|
||||
**tokens = 0**
|
||||
2. *
|
||||
**_ = 1**
|
||||
**err = None**
|
||||
**calls = 1**
|
||||
1. not `text`
|
||||
@@ -89,12 +93,16 @@ One LLM turn via the semantic surface (`ask` / `stream`+`collect`). Returns `{te
|
||||
**tokens = > json.get value=`r` key="tokens"**
|
||||
**err = > json.get value=`r` key="error"**
|
||||
**fin = > json.get value=`r` key="finish"**
|
||||
1. `tokens` == None
|
||||
**usage = > json.get value=`r` key="usage"**
|
||||
1. `usage`
|
||||
**tokens = > json.get value=`usage` key="total_tokens"**
|
||||
2. *
|
||||
**text = > str value=`r`**
|
||||
**tokens = 0**
|
||||
**err = None**
|
||||
**fin = None**
|
||||
1. not `tokens`
|
||||
1. `tokens` == None
|
||||
**tokens = 0**
|
||||
2. *
|
||||
**_ = 1**
|
||||
@@ -181,16 +189,335 @@ Find a human-readable call line: `CALL:<name>` or `调用:<name>` / `调用:<n
|
||||
## run_tool
|
||||
+ `tools`
|
||||
+ `name`
|
||||
+ `arguments`=None
|
||||
+ `ledger_dir`=.marqdo/agent-effects
|
||||
+ `logical_run_id`=None
|
||||
+ `step_id`=None
|
||||
+ `call_id`=None
|
||||
+ `operation_id`=None
|
||||
|
||||
Allowlist check, then invoke the runbook `##` via `lib/subtask` (`spawn fn=` → `wait`).
|
||||
Allowlist and ToolSpec prepare (M-A2), then invoke the runbook section via lib/subtask.
|
||||
Unauthorized or invalid-args calls return ToolResultV1 failure without spawning (0 executions).
|
||||
Mutating effects (write / execute / external_write) go through EffectLedger (M-A5a).
|
||||
State flow is prepared then started then spawn then committed, failed_no_effect, or unknown.
|
||||
Read tools skip the ledger. Matching idempotency_key and args_digest that already committed skips re-exec.
|
||||
|
||||
**allowed = > agent_tool_allowed tools=`tools` name=`name`**
|
||||
1. `allowed`
|
||||
**id = > subtask.spawn fn=`name`**
|
||||
*> subtask.wait id=`id`*
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
**msg = "Tool not allowed:"**
|
||||
*msg + name*
|
||||
**_ = 1**
|
||||
|
||||
1. not `arguments`
|
||||
**arguments = > table.empty_map**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
**prepared = None**
|
||||
**needs = False**
|
||||
**opid = None**
|
||||
**digest = None**
|
||||
**idem = None**
|
||||
**effect = "read"**
|
||||
**receipt = None**
|
||||
**raw = None**
|
||||
|
||||
1. not `p`
|
||||
**allowed = > agent_tool_allowed tools=`tools` name=`name`**
|
||||
1. not `allowed`
|
||||
**msg = "Tool not allowed:"**
|
||||
*msg + name*
|
||||
2. *
|
||||
**id = > subtask.spawn fn=`name`**
|
||||
*> subtask.wait id=`id`*
|
||||
|
||||
**prepared = > agent_tools_prepare_call tool_id=`name` tools=`tools` arguments=`arguments` call_id=`call_id` operation_id=`operation_id` logical_run_id=`logical_run_id` step_id=`step_id`**
|
||||
**pok = > json.get value=`prepared` key="ok"**
|
||||
1. not `pok`
|
||||
*prepared*
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
**needs = > json.get value=`prepared` key="needs_ledger"**
|
||||
**call = > json.get value=`prepared` key="call"**
|
||||
**opid = > json.get value=`call` key="operation_id"**
|
||||
**digest = > json.get value=`prepared` key="args_digest"**
|
||||
**idem = > json.get value=`prepared` key="idempotency_key"**
|
||||
**tspec = > json.get value=`prepared` key="spec"**
|
||||
**effect = > json.get value=`tspec` key="effect"**
|
||||
|
||||
1. `needs`
|
||||
**led = > agent_effects_prepare operation_id=`opid` idempotency_key=`idem` args_digest=`digest` effect_class=`effect` logical_run_id=`logical_run_id` step_id=`step_id` ledger_dir=`ledger_dir`**
|
||||
**rec = > json.get value=`led` key="record"**
|
||||
**st0 = > json.get value=`rec` key="state"**
|
||||
1. `st0` == "committed"
|
||||
**receipt = > json.get value=`rec` key="result_ref"**
|
||||
1. not `receipt`
|
||||
**receipt = "effect:" + `opid`**
|
||||
*> agent_tools_wrap_result ok=True status="succeeded" summary="deduped committed effect; skipped re-exec" structured_content=`rec` effect_receipt_ref=`receipt`*
|
||||
2. *
|
||||
1. `st0` == "reconciled_committed"
|
||||
**receipt = > json.get value=`rec` key="result_ref"**
|
||||
1. not `receipt`
|
||||
**receipt = "effect:" + `opid`**
|
||||
*> agent_tools_wrap_result ok=True status="succeeded" summary="deduped reconciled effect; skipped re-exec" structured_content=`rec` effect_receipt_ref=`receipt`*
|
||||
2. *
|
||||
1. `st0` == "unknown"
|
||||
**receipt = "effect:" + `opid`**
|
||||
*> agent_tools_wrap_result ok=False status="unknown_effect" summary="prior effect unknown; reconcile before retry" structured_content=`rec` effect_receipt_ref=`receipt`*
|
||||
2. *
|
||||
1. `st0` == "started"
|
||||
> agent_effects_transition operation_id=`opid` state="unknown" note="retry saw started without commit; mark unknown" ledger_dir=`ledger_dir`
|
||||
**receipt = "effect:" + `opid`**
|
||||
*> agent_tools_wrap_result ok=False status="unknown_effect" summary="interrupted after started; reconcile before retry" structured_content=`rec` effect_receipt_ref=`receipt`*
|
||||
2. *
|
||||
1. `st0` == "needs_input"
|
||||
**receipt = "effect:" + `opid`**
|
||||
*> agent_tools_wrap_result ok=False status="needs_input" summary="effect needs_input; will not re-exec" structured_content=`rec` effect_receipt_ref=`receipt`*
|
||||
2. *
|
||||
> agent_effects_transition operation_id=`opid` state="started" ledger_dir=`ledger_dir`
|
||||
**_ = 1**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
**id = > subtask.spawn fn=`name`**
|
||||
**raw = > subtask.wait id=`id`**
|
||||
1. `needs`
|
||||
**raw_s = > json.stringify value=`raw`**
|
||||
1. not `raw`
|
||||
> agent_effects_transition operation_id=`opid` state="unknown" note="empty tool outcome; reconcile required" ledger_dir=`ledger_dir`
|
||||
**receipt = "effect:" + `opid`**
|
||||
*> agent_tools_wrap_result ok=False status="unknown_effect" summary="tool outcome empty after started; ledger=unknown" structured_content=`raw` effect_receipt_ref=`receipt`*
|
||||
2. *
|
||||
**is_err = > text.starts_with text=`raw_s` prefix="Tool not allowed"**
|
||||
1. `is_err`
|
||||
> agent_effects_transition operation_id=`opid` state="failed_no_effect" note="rejected before effect" ledger_dir=`ledger_dir`
|
||||
**receipt = "effect:" + `opid`**
|
||||
*> agent_tools_wrap_result ok=False status="failed" summary=`raw_s` effect_receipt_ref=`receipt`*
|
||||
2. *
|
||||
**receipt = "effect:" + `opid`**
|
||||
> agent_effects_transition operation_id=`opid` state="committed" result_ref=`receipt` ledger_dir=`ledger_dir`
|
||||
*> agent_tools_wrap_result ok=True status="succeeded" summary="tool executed; effect committed" structured_content=`raw` effect_receipt_ref=`receipt`*
|
||||
2. *
|
||||
*raw*
|
||||
|
||||
## tools_register
|
||||
+ `spec`=None
|
||||
+ `specs`=None
|
||||
|
||||
Register ToolSpecV1 document(s). Unsupported schema keywords are refused.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_tools_register spec=`spec` specs=`specs`*
|
||||
|
||||
## tools_clear
|
||||
|
||||
Clear the in-process ToolSpec registry (tests / reseeding).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_tools_clear*
|
||||
|
||||
## tools_search
|
||||
+ `query`=""
|
||||
+ `tools`=None
|
||||
|
||||
Search authorized registered tools (summaries only).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_tools_search query=`query` tools=`tools`*
|
||||
|
||||
## tools_describe
|
||||
+ `id`
|
||||
+ `tools`=None
|
||||
|
||||
Return full ToolSpecV1 for an authorized tool id.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_tools_describe id=`id` tools=`tools`*
|
||||
|
||||
## tools_register_eng_defaults
|
||||
|
||||
Seed the five engineering tool specs (`tool_find` … `tool_summarize`).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_tools_register_eng_defaults*
|
||||
|
||||
## tools_prepare_call
|
||||
+ `tool_id`
|
||||
+ `arguments`=None
|
||||
+ `tools`=None
|
||||
+ `call_id`=None
|
||||
+ `operation_id`=None
|
||||
+ `logical_run_id`=None
|
||||
+ `step_id`=None
|
||||
+ `idempotency_key`=None
|
||||
|
||||
Validate schema + authorize; returns ToolCallV1 or ToolResultV1 error (no side effects).
|
||||
Also returns `args_digest` / `idempotency_key` / `needs_ledger` for EffectLedger wiring.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_tools_prepare_call tool_id=`tool_id` arguments=`arguments` tools=`tools` call_id=`call_id` operation_id=`operation_id` logical_run_id=`logical_run_id` step_id=`step_id` idempotency_key=`idempotency_key`*
|
||||
|
||||
## output_build
|
||||
+ `status`="succeeded"
|
||||
+ `text`=""
|
||||
+ `format`="markdown"
|
||||
+ `answer`=None
|
||||
+ `artifacts`=None
|
||||
+ `citations`=None
|
||||
+ `validation`=None
|
||||
+ `finish_reason`=None
|
||||
+ `recovery_options`=None
|
||||
+ `channels`=None
|
||||
+ `allow_passed_without_report`=False
|
||||
|
||||
Build an `AgentOutputV1` document (M-A4). `validation.status=passed` requires `report_ref`.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_output_build status=`status` text=`text` format=`format` answer=`answer` artifacts=`artifacts` citations=`citations` validation=`validation` finish_reason=`finish_reason` recovery_options=`recovery_options` channels=`channels` allow_passed_without_report=`allow_passed_without_report`*
|
||||
|
||||
## output_apply_policy
|
||||
+ `status`="succeeded"
|
||||
+ `text`=""
|
||||
+ `format`="markdown"
|
||||
+ `answer`=None
|
||||
+ `artifacts`=None
|
||||
+ `citations`=None
|
||||
+ `validation`=None
|
||||
+ `policy`=None
|
||||
+ `schema`=None
|
||||
+ `schema_version`=None
|
||||
+ `finish_reason`=None
|
||||
+ `recovery_options`=None
|
||||
+ `channels`=None
|
||||
|
||||
Apply `ResponsePolicy` (detail / max_chars / max_output_tokens / artifact_allowed) to an AgentOutputV1 or raw text.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_output_apply_policy status=`status` text=`text` format=`format` answer=`answer` artifacts=`artifacts` citations=`citations` validation=`validation` policy=`policy` schema=`schema` schema_version=`schema_version` finish_reason=`finish_reason` recovery_options=`recovery_options` channels=`channels`*
|
||||
|
||||
## output_channel_event
|
||||
+ `channel`
|
||||
+ `delta`=""
|
||||
+ `resource_id`=None
|
||||
+ `meta`=None
|
||||
|
||||
Split a stream delta by channel. Only `answer` sets `append_to_chat=true`.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_output_channel_event channel=`channel` delta=`delta` resource_id=`resource_id` meta=`meta`*
|
||||
|
||||
## output_project_conclusion
|
||||
+ `document`=""
|
||||
+ `text`=""
|
||||
|
||||
Deterministic chat projection from `# 结论` / `# conclusion` (F01 transition). Falls back to the first body paragraph.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_output_project_conclusion document=`document` text=`text`*
|
||||
|
||||
## context_pack_build
|
||||
+ `items`=None
|
||||
+ `budget_tokens`=8000
|
||||
+ `output_reserve_pct`=20
|
||||
+ `compact_threshold_pct`=70
|
||||
+ `goal`=None
|
||||
+ `constraints`=None
|
||||
|
||||
Assemble `ContextPackV2` with origin/trust/priority. Web/tool items cannot be `trust=trusted`.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_context_pack_build items=`items` budget_tokens=`budget_tokens` output_reserve_pct=`output_reserve_pct` compact_threshold_pct=`compact_threshold_pct` goal=`goal` constraints=`constraints`*
|
||||
|
||||
## context_pack_compact
|
||||
+ `items`=None
|
||||
+ `budget_tokens`=8000
|
||||
+ `output_reserve_pct`=20
|
||||
+ `compact_threshold_pct`=70
|
||||
+ `goal`=None
|
||||
+ `constraints`=None
|
||||
+ `schema`=None
|
||||
+ `schema_version`=None
|
||||
+ `available_tokens`=None
|
||||
+ `used_tokens`=None
|
||||
+ `source_event_range`=None
|
||||
|
||||
Compact over-threshold packs; retain goal/constraints/pending_write/plan/trusted anchors (F19).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_context_pack_compact items=`items` budget_tokens=`budget_tokens` output_reserve_pct=`output_reserve_pct` compact_threshold_pct=`compact_threshold_pct` goal=`goal` constraints=`constraints` schema=`schema` schema_version=`schema_version` available_tokens=`available_tokens` used_tokens=`used_tokens` source_event_range=`source_event_range`*
|
||||
|
||||
## render_workbook_skeleton
|
||||
+ `goal`
|
||||
@@ -677,8 +1004,12 @@ Close a stdio MCP client session.
|
||||
+ `route`=None
|
||||
+ `result`=None
|
||||
+ `resume_dir`=.marqdo/agent-resume
|
||||
+ `checkpoint_v2`=False
|
||||
+ `attempt_id`=None
|
||||
+ `effect_ledger_watermark`=None
|
||||
|
||||
Persist a plan/run checkpoint as `.marqdo/agent-resume/<id>.json`.
|
||||
Persist a plan/run checkpoint as `.marqdo/agent-resume/<id>.json` (atomic write).
|
||||
Pass `checkpoint_v2=True` for CheckpointV2 schema. `resume_dir` must be host-relative.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
@@ -687,16 +1018,56 @@ Persist a plan/run checkpoint as `.marqdo/agent-resume/<id>.json`.
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_resume_save id=`id` goal=`goal` task=`task` status=`status` round=`round` workbook=`workbook` events=`events` route=`route` result=`result` resume_dir=`resume_dir`*
|
||||
*> agent_resume_save id=`id` goal=`goal` task=`task` status=`status` round=`round` workbook=`workbook` events=`events` route=`route` result=`result` resume_dir=`resume_dir` checkpoint_v2=`checkpoint_v2` attempt_id=`attempt_id` effect_ledger_watermark=`effect_ledger_watermark`*
|
||||
|
||||
## resume_load
|
||||
+ `id`
|
||||
+ `resume_dir`=.marqdo/agent-resume
|
||||
|
||||
Load a resume checkpoint (or `{ok:false,found:false}`).
|
||||
Legacy / missing effect ledger → `recovery_mode=manual_review`, `write_auto_resume=false`.
|
||||
|
||||
*> agent_resume_load id=`id` resume_dir=`resume_dir`*
|
||||
|
||||
## error_make
|
||||
+ `code`
|
||||
+ `message`=None
|
||||
+ `category`=None
|
||||
+ `stage`=agent
|
||||
+ `retryable`=None
|
||||
+ `effect_state`=none
|
||||
+ `recovery_action`=None
|
||||
+ `call_id`=None
|
||||
|
||||
Build an `AgentErrorV1` document (M-A1).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_error_make code=`code` message=`message` category=`category` stage=`stage` retryable=`retryable` effect_state=`effect_state` recovery_action=`recovery_action` call_id=`call_id`*
|
||||
|
||||
## error_decide_retry
|
||||
+ `error`
|
||||
+ `attempts`=0
|
||||
+ `effect_class`=read
|
||||
+ `cancelled`=False
|
||||
+ `fingerprint_repeats`=0
|
||||
|
||||
Bounded recovery decision. Write / unknown effect → `manual_review` (no auto redo).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_error_decide_retry error=`error` attempts=`attempts` effect_class=`effect_class` cancelled=`cancelled` fingerprint_repeats=`fingerprint_repeats`*
|
||||
|
||||
## resume_clear
|
||||
+ `id`
|
||||
+ `resume_dir`=.marqdo/agent-resume
|
||||
@@ -720,6 +1091,113 @@ Author entry: load checkpoint for continuation. Returns the checkpoint map (`fou
|
||||
|
||||
*> resume_load id=`id` resume_dir=`resume_dir`*
|
||||
|
||||
## effects_prepare
|
||||
+ `operation_id`
|
||||
+ `idempotency_key`
|
||||
+ `args_digest`
|
||||
+ `effect_class`="write"
|
||||
+ `resource_scope`=None
|
||||
+ `expected_revision`=None
|
||||
+ `result_ref`=None
|
||||
+ `logical_run_id`=None
|
||||
+ `step_id`=None
|
||||
+ `attempt_id`=None
|
||||
+ `ledger_dir`=.marqdo/agent-effects
|
||||
|
||||
Create (or dedupe) an `EffectLedgerRecordV1` in `prepared`. Same idempotency_key + args_digest returns the existing record; same key with different digest is rejected.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_effects_prepare operation_id=`operation_id` idempotency_key=`idempotency_key` args_digest=`args_digest` effect_class=`effect_class` resource_scope=`resource_scope` expected_revision=`expected_revision` result_ref=`result_ref` logical_run_id=`logical_run_id` step_id=`step_id` attempt_id=`attempt_id` ledger_dir=`ledger_dir`*
|
||||
|
||||
## effects_transition
|
||||
+ `operation_id`
|
||||
+ `state`
|
||||
+ `result_ref`=None
|
||||
+ `note`=None
|
||||
+ `reconcile_hint`=None
|
||||
+ `ledger_dir`=.marqdo/agent-effects
|
||||
|
||||
Advance ledger state (`prepared→started→committed|failed_no_effect|unknown→reconciled_*`).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_effects_transition operation_id=`operation_id` state=`state` result_ref=`result_ref` note=`note` reconcile_hint=`reconcile_hint` ledger_dir=`ledger_dir`*
|
||||
|
||||
## effects_get
|
||||
+ `operation_id`
|
||||
+ `ledger_dir`=.marqdo/agent-effects
|
||||
|
||||
Load one ledger record.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_effects_get operation_id=`operation_id` ledger_dir=`ledger_dir`*
|
||||
|
||||
## effects_list
|
||||
+ `ledger_dir`=.marqdo/agent-effects
|
||||
+ `logical_run_id`=None
|
||||
+ `state`=None
|
||||
|
||||
List ledger records (optional filters).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_effects_list ledger_dir=`ledger_dir` logical_run_id=`logical_run_id` state=`state`*
|
||||
|
||||
## effects_watermark
|
||||
+ `ledger_dir`=.marqdo/agent-effects
|
||||
+ `logical_run_id`=None
|
||||
|
||||
Digest committed/open effects for CheckpointV2. `write_auto_resume_safe` is false while unknown or pending writes remain.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_effects_watermark ledger_dir=`ledger_dir` logical_run_id=`logical_run_id`*
|
||||
|
||||
## effects_reconcile
|
||||
+ `operation_id`
|
||||
+ `outcome`
|
||||
+ `result_ref`=None
|
||||
+ `note`=None
|
||||
+ `ledger_dir`=.marqdo/agent-effects
|
||||
|
||||
Reconcile an `unknown` record: `outcome` = committed | no_effect | needs_input.
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found
|
||||
> sys.exit code=1
|
||||
|
||||
*> agent_effects_reconcile operation_id=`operation_id` outcome=`outcome` result_ref=`result_ref` note=`note` ledger_dir=`ledger_dir`*
|
||||
|
||||
---
|
||||
|
||||
## extract_call_args
|
||||
@@ -869,7 +1347,7 @@ Write a scratch tool workbook under `.marqdo/agent-runs/tools/<name>.mq.md`.
|
||||
|
||||
Protected v2.1 Occlusion card always prepended to skill_brief (M05). Must not be truncated by budget.
|
||||
|
||||
**esc = > json.parse text={"card":"## CORE SYNTAX (v2.1 Occlusion)\n1. Print with > print / > 打印 — never use bold markers to print.\n2. Bold markers = return/code; italic markers = statement.\n3. [desc](payload) = occlusion; brackets never execute.\n4. Read with access(coll, key) — never Classic [key](map) index.\n5. Foreach: - [desc](for coll as item). import + one language per file.\n6. # type · ## function · + params · numbered branches · - loops.\n"}**
|
||||
**esc = > json.parse text={"card":"## CORE SYNTAX (v2.1 Occlusion)\n1. Print with > print / > 打印 — never use bold markers to print.\n2. Bold markers = statement; italic markers = return.\n3. [desc](payload) = occlusion; brackets never execute.\n4. Read with access(coll, key) — never Classic [key](map) index.\n5. Foreach: - [desc](for coll as item). import + one language per file.\n6. # type · ## function · + params · numbered branches · - loops.\n"}**
|
||||
*> json.get value=`esc` key="card"*
|
||||
|
||||
---
|
||||
@@ -2343,19 +2821,31 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o
|
||||
2. *
|
||||
**out = > `self`.plan goal=`task` kb_dir=`kb_dir` writeback=`writeback` reuse=`reuse` near_match=`near_match` near_threshold=`near_threshold` promote=`promote` improve_every=`improve_every` explore_n=`explore_n` max_rounds=`max_rounds` stream=`stream` echo=`echo` trace=`trace` force=`force`**
|
||||
**exec_mode = "explore"**
|
||||
**llm_calls = 1**
|
||||
**llm_calls = > json.get value=`out` key="llm_calls"**
|
||||
**tokens = > json.get value=`out` key="tokens"**
|
||||
1. `llm_calls` == None
|
||||
**llm_calls = 1**
|
||||
1. `tokens` == None
|
||||
**tokens = 0**
|
||||
2. *
|
||||
**out = > `self`.plan goal=`task` kb_dir=`kb_dir` writeback=`writeback` reuse=`reuse` near_match=`near_match` near_threshold=`near_threshold` promote=`promote` improve_every=`improve_every` explore_n=`explore_n` max_rounds=`max_rounds` stream=`stream` echo=`echo` trace=`trace` force=`force`**
|
||||
**cache = > json.get value=`out` key="cache"**
|
||||
1. `cache` == "hit"
|
||||
**exec_mode = "compiled"**
|
||||
**llm_calls = 0**
|
||||
**tokens = 0**
|
||||
2. `cache` == "soft-hit"
|
||||
**exec_mode = "near"**
|
||||
**llm_calls = 0**
|
||||
**tokens = 0**
|
||||
3. *
|
||||
**exec_mode = "explore"**
|
||||
**llm_calls = 1**
|
||||
**llm_calls = > json.get value=`out` key="llm_calls"**
|
||||
**tokens = > json.get value=`out` key="tokens"**
|
||||
1. `llm_calls` == None
|
||||
**llm_calls = 1**
|
||||
1. `tokens` == None
|
||||
**tokens = 0**
|
||||
|
||||
**st = > json.get value=`out` key="status"**
|
||||
**res = > json.get value=`out` key="result"**
|
||||
@@ -2414,8 +2904,10 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o
|
||||
**_ = 1**
|
||||
|
||||
1. `resume_id`
|
||||
**_ckpt = resume_save id=`resume_id` goal=`task` task=`task` status=`st` round=1 workbook=`wb_path` result=`res` route=`routed` resume_dir=`resume_dir`**
|
||||
**_wm = > effects_watermark ledger_dir=".marqdo/agent-effects" logical_run_id=`resume_id`**
|
||||
**_ckpt = resume_save id=`resume_id` goal=`task` task=`task` status=`st` round=1 workbook=`wb_path` result=`res` route=`routed` resume_dir=`resume_dir` checkpoint_v2=True attempt_id="attempt_1" effect_ledger_watermark=`_wm`**
|
||||
**out = table.put in=`out` at="resume" value=`_ckpt`**
|
||||
**out = table.put in=`out` at="effect_ledger_watermark" value=`_wm`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
@@ -2429,8 +2921,10 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o
|
||||
+ `max_reads`=2
|
||||
+ `sandbox`=False
|
||||
+ `sandbox_profile`=default
|
||||
+ `resume_id`=None
|
||||
|
||||
One atomic turn: budgeted context → LLM → optional `READ:` deepen → optional tool via subtask. Returns a *map* (`status`, `task`, `decision`, and on success `result` plus optional `tool` / `tool_result`; on failure `error`). By default (`writeback=True`) persists that map under named slots `ok` / `error` at the call site; pass `writeback=False` to skip.
|
||||
Optional `resume_id` scopes EffectLedger idempotency for mutating tools.
|
||||
|
||||
With `stream=True`, the model call uses SSE; `echo=True` prints delta text to stdout as it arrives. The returned map is unchanged (final `result` string). Context source/skill start at default budget; up to `max_reads` of `READ:source` / `READ:skill` deepen before CALL/answer.
|
||||
`sandbox=True` (O1 opt-in): attach the sandbox profile row on the result map (trial via `## trial` / `run sandbox=`).
|
||||
@@ -2521,7 +3015,7 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
|
||||
| ok | `task` | `decision` |
|
||||
|
||||
1. `tool_name`
|
||||
**tool_out = > run_tool tools=`tools` name=`tool_name`**
|
||||
**tool_out = > run_tool tools=`tools` name=`tool_name` logical_run_id=`resume_id`**
|
||||
**tool_s = > json.stringify value=`tool_out`**
|
||||
**deny = > split value=`tool_s` sep="Tool not allowed"**
|
||||
**deny_n = > len value=`deny`**
|
||||
@@ -3018,6 +3512,8 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
|
||||
**status = "error"**
|
||||
**err = "max_rounds exhausted"**
|
||||
**skip_loop = None**
|
||||
**plan_llm_calls = 0**
|
||||
**plan_tokens = 0**
|
||||
|
||||
> plan_echo_decompose workbook=`path` stream=`stream` echo=`echo`
|
||||
**last_obs = > inspect_workbook path=`path`**
|
||||
@@ -3031,6 +3527,12 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
|
||||
**last_reply = > json.get value=`turn` key="reply"**
|
||||
**last_obs = > json.get value=`turn` key="observation"**
|
||||
**events = > json.get value=`turn` key="events"**
|
||||
**_c = > json.get value=`turn` key="llm_calls"**
|
||||
**_t = > json.get value=`turn` key="tokens"**
|
||||
1. `_c` != None
|
||||
**plan_llm_calls = plan_llm_calls + _c**
|
||||
1. `_t` != None
|
||||
**plan_tokens = plan_tokens + _t**
|
||||
2. *
|
||||
**dec = "TRANSPORT_ERROR"**
|
||||
**last_reply = "plan_llm_act_loop_not_map"**
|
||||
@@ -3079,11 +3581,27 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
|
||||
2. *
|
||||
**_ = 1**
|
||||
5. *
|
||||
**done = 1**
|
||||
**status = "error"**
|
||||
**err = "unrecognized plan decision"**
|
||||
**summary = last_reply**
|
||||
**skip_loop = 1**
|
||||
Free-form parent reply with no DECISION/CALL/READ (dec=unknown): accept as DONE
|
||||
when there is prose — chat soft-recover depends on result/summary surviving.
|
||||
1. `dec` == "unknown"
|
||||
1. `last_reply`
|
||||
**done = 1**
|
||||
**status = "ok"**
|
||||
**err = None**
|
||||
**summary = `last_reply`**
|
||||
**skip_loop = 1**
|
||||
2. *
|
||||
**done = 1**
|
||||
**status = "error"**
|
||||
**err = "unrecognized plan decision"**
|
||||
**summary = last_reply**
|
||||
**skip_loop = 1**
|
||||
2. *
|
||||
**done = 1**
|
||||
**status = "error"**
|
||||
**err = "unrecognized plan decision"**
|
||||
**summary = last_reply**
|
||||
**skip_loop = 1**
|
||||
|
||||
1. `skip_loop`
|
||||
**left = 0**
|
||||
@@ -3132,6 +3650,12 @@ Deterministic success stop (loop engineering): when the child already returned a
|
||||
**last_reply = > json.get value=`turn` key="reply"**
|
||||
**last_obs = > json.get value=`turn` key="observation"**
|
||||
**events = > json.get value=`turn` key="events"**
|
||||
**_c = > json.get value=`turn` key="llm_calls"**
|
||||
**_t = > json.get value=`turn` key="tokens"**
|
||||
1. `_c` != None
|
||||
**plan_llm_calls = plan_llm_calls + _c**
|
||||
1. `_t` != None
|
||||
**plan_tokens = plan_tokens + _t**
|
||||
1. `dec` == DONE
|
||||
> agent_workbook_solidify path=`path` observation=`last_obs`
|
||||
**done = 1**
|
||||
@@ -3152,11 +3676,25 @@ Deterministic success stop (loop engineering): when the child already returned a
|
||||
3. `dec` == RUN
|
||||
**left = left - 1**
|
||||
4. *
|
||||
**done = 1**
|
||||
**status = "error"**
|
||||
**err = "unrecognized plan decision"**
|
||||
**summary = last_reply**
|
||||
**left = 0**
|
||||
1. `dec` == "unknown"
|
||||
1. `last_reply`
|
||||
**done = 1**
|
||||
**status = "ok"**
|
||||
**err = None**
|
||||
**summary = `last_reply`**
|
||||
**left = 0**
|
||||
2. *
|
||||
**done = 1**
|
||||
**status = "error"**
|
||||
**err = "unrecognized plan decision"**
|
||||
**summary = last_reply**
|
||||
**left = 0**
|
||||
2. *
|
||||
**done = 1**
|
||||
**status = "error"**
|
||||
**err = "unrecognized plan decision"**
|
||||
**summary = last_reply**
|
||||
**left = 0**
|
||||
|
||||
1. `status` == "ok"
|
||||
1. `promote`
|
||||
@@ -3169,9 +3707,9 @@ Deterministic success stop (loop engineering): when the child already returned a
|
||||
|
||||
`out` =
|
||||
|
||||
| status | goal | workbook | rounds | cache |
|
||||
|--------|------|----------|--------|-------|
|
||||
| `status` | `goal` | `path` | `round` | `cache` |
|
||||
| status | goal | workbook | rounds | cache | llm_calls | tokens |
|
||||
|--------|------|----------|--------|-------|-----------|--------|
|
||||
| `status` | `goal` | `path` | `round` | `cache` | `plan_llm_calls` | `plan_tokens` |
|
||||
|
||||
1. `summary`
|
||||
**out = table.put in=`out` at="summary" value=`summary`**
|
||||
|
||||
@@ -92,6 +92,35 @@ Alias: `stream_result`.
|
||||
**answer = ""**
|
||||
*answer*
|
||||
|
||||
## collect_usage
|
||||
+ `events`
|
||||
|
||||
Best-effort `total_tokens` from stream frames (requires `stream_options.include_usage`).
|
||||
|
||||
**tokens = None**
|
||||
1. `events`
|
||||
- [ev](遍历 events 为 ev)
|
||||
**t = > json.get value=`ev` key="type"**
|
||||
**raw = None**
|
||||
1. `t` == "data"
|
||||
**raw = > json.get value=`ev` key="data"**
|
||||
2. *
|
||||
**u0 = > json.get value=`ev` key="usage"**
|
||||
1. `u0`
|
||||
**tt0 = > json.get value=`u0` key="total_tokens"**
|
||||
1. `tt0` != None
|
||||
**tokens = `tt0`**
|
||||
1. `raw`
|
||||
1. not `raw` == "[DONE]"
|
||||
**parsed = > json.parse text=`raw`**
|
||||
1. `parsed`
|
||||
**u = > json.get value=`parsed` key="usage"**
|
||||
1. `u`
|
||||
**tt = > json.get value=`u` key="total_tokens"**
|
||||
1. `tt` != None
|
||||
**tokens = `tt`**
|
||||
*tokens*
|
||||
|
||||
## stream_result
|
||||
+ `events`
|
||||
|
||||
|
||||
@@ -115,6 +115,13 @@ Pass either `messages=` (role/content list) or legacy `prompt=` (single user mes
|
||||
|
||||
1. `stream`
|
||||
**req = > table.put in=`req` at="stream" value=True**
|
||||
`stream_opts` =
|
||||
|
||||
| include_usage |
|
||||
|---------------|
|
||||
| True |
|
||||
|
||||
**req = > table.put in=`req` at="stream_options" value=`stream_opts`**
|
||||
**body = > json.stringify value=`req`**
|
||||
**resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`**
|
||||
**st = > json.get value=`resp` key="status"**
|
||||
|
||||
+6
-3
@@ -177,8 +177,9 @@ view has no persistent kernel state.
|
||||
+ `cwd`=None
|
||||
+ `timeout`=None
|
||||
|
||||
Start a persistent Python/Node kernel; returns a session id. `timeout` is the
|
||||
default per-eval timeout.
|
||||
Start a persistent Python/Node kernel; returns an opaque `handle` value.
|
||||
Text fabrications are refused by session ops; handles cannot cross the JSON
|
||||
bridge. `timeout` is the default per-eval timeout.
|
||||
|
||||
*> host_foreign_session_open lang=`lang` cmd=`cmd` env=`env` cwd=`cwd` timeout=`timeout`*
|
||||
|
||||
@@ -223,7 +224,9 @@ List kernel variable names.
|
||||
## session_close
|
||||
+ `id`
|
||||
|
||||
Kill and remove a session; returns whether it existed.
|
||||
Consume (affine close) a live session handle: kill and remove it. Returns
|
||||
`True` on success. Closing an unknown or already-closed id is a fault
|
||||
(`foreign session … not found`), matching use-after-close on eval/set/get.
|
||||
|
||||
*> host_foreign_session_close id=`id`*
|
||||
|
||||
|
||||
@@ -0,0 +1,266 @@
|
||||
//! ContextPackV2 assemble + compact (M-A4).
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
|
||||
args.get(key)
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
}
|
||||
|
||||
fn item_tokens(item: &Value) -> u64 {
|
||||
item.get("token_estimate")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or_else(|| {
|
||||
item.get("text")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| (s.chars().count() as u64).div_ceil(2))
|
||||
.unwrap_or(32)
|
||||
})
|
||||
}
|
||||
|
||||
fn normalize_item(raw: &Value, default_priority: i64) -> Result<Value, String> {
|
||||
let origin = raw
|
||||
.get("origin")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("unknown");
|
||||
let trust = raw
|
||||
.get("trust")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(match origin {
|
||||
"system" | "policy" => "trusted",
|
||||
"user" => "user",
|
||||
"tool" => "tool",
|
||||
"web" => "untrusted",
|
||||
_ => "unknown",
|
||||
});
|
||||
// External / web content must never be trust=trusted.
|
||||
if matches!(origin, "web" | "tool") && trust == "trusted" {
|
||||
return Err("tool/web origin cannot have trust=trusted".into());
|
||||
}
|
||||
Ok(json!({
|
||||
"origin": origin,
|
||||
"trust": trust,
|
||||
"resource_ref": raw.get("resource_ref").cloned().unwrap_or(Value::Null),
|
||||
"revision": raw.get("revision").cloned().unwrap_or(Value::Null),
|
||||
"token_estimate": item_tokens(raw),
|
||||
"priority": raw.get("priority").and_then(|v| v.as_i64()).unwrap_or(default_priority),
|
||||
"role": raw.get("role").cloned().unwrap_or(json!(origin)),
|
||||
"text": raw.get("text").cloned().unwrap_or(Value::Null),
|
||||
"kind": raw.get("kind").cloned().unwrap_or(json!("content")),
|
||||
"retain": raw.get("retain").and_then(|v| v.as_bool()).unwrap_or(false),
|
||||
}))
|
||||
}
|
||||
|
||||
/// Build ContextPackV2 from items + optional budget.
|
||||
pub fn context_pack_build(args: &Value) -> Result<Value, String> {
|
||||
let raw_items = args
|
||||
.get("items")
|
||||
.and_then(|v| v.as_array())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let mut items = Vec::new();
|
||||
for (i, raw) in raw_items.iter().enumerate() {
|
||||
items.push(normalize_item(raw, i as i64)?);
|
||||
}
|
||||
// Stable priority order: lower priority number first (more important).
|
||||
items.sort_by(|a, b| {
|
||||
let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
|
||||
let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
|
||||
pa.cmp(&pb)
|
||||
});
|
||||
let budget = args
|
||||
.get("budget_tokens")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(8_000);
|
||||
let reserve_pct = args
|
||||
.get("output_reserve_pct")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(20)
|
||||
.min(50);
|
||||
let available = budget.saturating_mul(100 - reserve_pct) / 100;
|
||||
let used: u64 = items.iter().map(item_tokens).sum();
|
||||
Ok(json!({
|
||||
"schema": "ContextPackV2",
|
||||
"schema_version": 2,
|
||||
"items": items,
|
||||
"budget_tokens": budget,
|
||||
"available_tokens": available,
|
||||
"used_tokens": used,
|
||||
"output_reserve_pct": reserve_pct,
|
||||
"compact_threshold_pct": args.get("compact_threshold_pct").and_then(|v| v.as_u64()).unwrap_or(70),
|
||||
"goal": args.get("goal").cloned().unwrap_or(Value::Null),
|
||||
"constraints": args.get("constraints").cloned().unwrap_or_else(|| json!([])),
|
||||
}))
|
||||
}
|
||||
|
||||
/// Compact pack when over threshold; must retain anchors listed in design §6.2.
|
||||
pub fn context_pack_compact(args: &Value) -> Result<Value, String> {
|
||||
let mut pack = if args.get("schema").and_then(|v| v.as_str()) == Some("ContextPackV2") {
|
||||
args.clone()
|
||||
} else {
|
||||
context_pack_build(args)?
|
||||
};
|
||||
let available = pack
|
||||
.get("available_tokens")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(6400);
|
||||
let threshold_pct = pack
|
||||
.get("compact_threshold_pct")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(70);
|
||||
let threshold = available.saturating_mul(threshold_pct) / 100;
|
||||
let used = pack
|
||||
.get("used_tokens")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(0);
|
||||
if used <= threshold {
|
||||
if let Some(obj) = pack.as_object_mut() {
|
||||
obj.insert("compacted".into(), json!(false));
|
||||
obj.insert("reason".into(), json!("under_threshold"));
|
||||
}
|
||||
return Ok(pack);
|
||||
}
|
||||
|
||||
let items = pack
|
||||
.get("items")
|
||||
.and_then(|v| v.as_array())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
// Retain: goal/constraints (pack fields), retain=true, high priority (<=2),
|
||||
// pending writes, failures — drop bulky tool dumps first (kind=tool_output, low priority).
|
||||
let mut kept = Vec::new();
|
||||
let mut dropped = Vec::new();
|
||||
for item in items {
|
||||
let retain = item.get("retain").and_then(|v| v.as_bool()).unwrap_or(false);
|
||||
let priority = item.get("priority").and_then(|v| v.as_i64()).unwrap_or(99);
|
||||
let kind = item.get("kind").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let trust = item.get("trust").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let must = retain
|
||||
|| priority <= 2
|
||||
|| matches!(kind, "goal" | "constraint" | "pending_write" | "plan" | "failure")
|
||||
|| trust == "trusted";
|
||||
if must {
|
||||
kept.push(item);
|
||||
} else if kind == "tool_output" || priority >= 8 {
|
||||
dropped.push(item);
|
||||
} else {
|
||||
kept.push(item);
|
||||
}
|
||||
}
|
||||
// If still over budget, drop lowest-priority non-retain from kept.
|
||||
let mut kept_tokens: u64 = kept.iter().map(item_tokens).sum();
|
||||
if kept_tokens > threshold {
|
||||
kept.sort_by(|a, b| {
|
||||
let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
|
||||
let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
|
||||
pb.cmp(&pa) // high priority number first for dropping
|
||||
});
|
||||
let mut next = Vec::new();
|
||||
for item in kept.into_iter().rev() {
|
||||
// rebuild ascending later
|
||||
let retain = item.get("retain").and_then(|v| v.as_bool()).unwrap_or(false);
|
||||
let priority = item.get("priority").and_then(|v| v.as_i64()).unwrap_or(99);
|
||||
let t = item_tokens(&item);
|
||||
if (retain || priority <= 1) || kept_tokens <= threshold {
|
||||
next.push(item);
|
||||
} else if kept_tokens > threshold {
|
||||
kept_tokens = kept_tokens.saturating_sub(t);
|
||||
dropped.push(item);
|
||||
} else {
|
||||
next.push(item);
|
||||
}
|
||||
}
|
||||
next.sort_by(|a, b| {
|
||||
let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
|
||||
let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
|
||||
pa.cmp(&pb)
|
||||
});
|
||||
kept = next;
|
||||
kept_tokens = kept.iter().map(item_tokens).sum();
|
||||
}
|
||||
|
||||
let digest_src = format!(
|
||||
"kept={} dropped={} used={}",
|
||||
kept.len(),
|
||||
dropped.len(),
|
||||
kept_tokens
|
||||
);
|
||||
let digest = format!("sha256-lite:{}", simple_hash(&digest_src));
|
||||
|
||||
if let Some(obj) = pack.as_object_mut() {
|
||||
obj.insert("items".into(), json!(kept));
|
||||
obj.insert("used_tokens".into(), json!(kept_tokens));
|
||||
obj.insert("compacted".into(), json!(true));
|
||||
obj.insert(
|
||||
"compaction".into(),
|
||||
json!({
|
||||
"dropped_count": dropped.len(),
|
||||
"source_event_range": args.get("source_event_range").cloned().unwrap_or(Value::Null),
|
||||
"digest": digest,
|
||||
"retained": ["goal", "constraints", "pending_write", "plan", "trusted_policy"],
|
||||
}),
|
||||
);
|
||||
// Goal / constraints fields stay untouched.
|
||||
if obj.get("goal").map(|v| v.is_null()).unwrap_or(true) {
|
||||
if let Some(g) = opt_text(args, "goal") {
|
||||
obj.insert("goal".into(), json!(g));
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(pack)
|
||||
}
|
||||
|
||||
fn simple_hash(s: &str) -> u64 {
|
||||
let mut h: u64 = 0xcbf29ce484222325;
|
||||
for b in s.as_bytes() {
|
||||
h ^= u64::from(*b);
|
||||
h = h.wrapping_mul(0x100000001b3);
|
||||
}
|
||||
h
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn build_sorts_and_rejects_trusted_web() {
|
||||
let pack = context_pack_build(&json!({
|
||||
"budget_tokens": 1000,
|
||||
"items": [
|
||||
{"origin": "user", "text": "goal", "priority": 0, "kind": "goal", "retain": true},
|
||||
{"origin": "tool", "text": "big dump", "priority": 9, "kind": "tool_output", "token_estimate": 500}
|
||||
]
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(pack["schema"], "ContextPackV2");
|
||||
assert_eq!(pack["items"][0]["priority"], 0);
|
||||
|
||||
let bad = context_pack_build(&json!({
|
||||
"items": [{"origin": "web", "trust": "trusted", "text": "x"}]
|
||||
}));
|
||||
assert!(bad.is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn compact_keeps_goal_drops_tool_output() {
|
||||
let pack = context_pack_build(&json!({
|
||||
"budget_tokens": 200,
|
||||
"output_reserve_pct": 20,
|
||||
"compact_threshold_pct": 50,
|
||||
"goal": "finish task",
|
||||
"items": [
|
||||
{"origin": "user", "text": "do it", "priority": 0, "kind": "goal", "retain": true, "token_estimate": 20},
|
||||
{"origin": "tool", "text": "x".repeat(400), "priority": 9, "kind": "tool_output", "token_estimate": 200}
|
||||
]
|
||||
}))
|
||||
.unwrap();
|
||||
let compacted = context_pack_compact(&pack).unwrap();
|
||||
assert_eq!(compacted["compacted"], true);
|
||||
let items = compacted["items"].as_array().unwrap();
|
||||
assert!(items.iter().any(|i| i["kind"] == "goal"));
|
||||
assert!(!items.iter().any(|i| i["kind"] == "tool_output"));
|
||||
assert_eq!(compacted["goal"], "finish task");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,623 @@
|
||||
//! EffectLedgerRecordV1 — operation receipts for write-safe resume (M-A5 subset).
|
||||
//!
|
||||
//! State machine (design §4.2):
|
||||
//! prepared → started → committed
|
||||
//! ↘ failed_no_effect
|
||||
//! ↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
|
||||
|
||||
use std::fs::{self, File, OpenOptions};
|
||||
use std::io::Write;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
const DEFAULT_LEDGER_DIR: &str = ".marqdo/agent-effects";
|
||||
|
||||
const STATES: &[&str] = &[
|
||||
"prepared",
|
||||
"started",
|
||||
"committed",
|
||||
"failed_no_effect",
|
||||
"unknown",
|
||||
"reconciled_committed",
|
||||
"reconciled_no_effect",
|
||||
"needs_input",
|
||||
];
|
||||
|
||||
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
|
||||
args.get(key)
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
}
|
||||
|
||||
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
|
||||
opt_text(args, key).ok_or_else(|| format!("missing text `{key}`"))
|
||||
}
|
||||
|
||||
fn now_rfc3339() -> String {
|
||||
chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
|
||||
}
|
||||
|
||||
fn resolve_path(rel: &str) -> PathBuf {
|
||||
let p = PathBuf::from(rel);
|
||||
if p.is_absolute() {
|
||||
return p;
|
||||
}
|
||||
if p.exists() {
|
||||
return p;
|
||||
}
|
||||
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 ledger_root(args: &Value) -> Result<PathBuf, String> {
|
||||
let rel = opt_text(args, "ledger_dir").unwrap_or(DEFAULT_LEDGER_DIR);
|
||||
let p = PathBuf::from(rel);
|
||||
if p.is_absolute() {
|
||||
return Err(
|
||||
"ledger_dir must be host-relative; absolute client paths are rejected".into(),
|
||||
);
|
||||
}
|
||||
if rel.contains("..") {
|
||||
return Err("ledger_dir must not contain '..'".into());
|
||||
}
|
||||
Ok(resolve_path(rel))
|
||||
}
|
||||
|
||||
fn safe_id(id: &str) -> String {
|
||||
id.chars()
|
||||
.map(|c| {
|
||||
if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
|
||||
c
|
||||
} else {
|
||||
'_'
|
||||
}
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
fn record_path(root: &Path, operation_id: &str) -> PathBuf {
|
||||
root.join(format!("{}.json", safe_id(operation_id)))
|
||||
}
|
||||
|
||||
fn ensure_dir(root: &Path) -> Result<(), String> {
|
||||
fs::create_dir_all(root).map_err(|e| format!("effects mkdir: {e}"))
|
||||
}
|
||||
|
||||
fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
|
||||
let parent = path
|
||||
.parent()
|
||||
.ok_or_else(|| "ledger path has no parent".to_string())?;
|
||||
ensure_dir(parent)?;
|
||||
let tmp_name = format!(
|
||||
".{}.tmp-{}-{}",
|
||||
path.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or("op.json"),
|
||||
std::process::id(),
|
||||
now_rfc3339().replace(':', "")
|
||||
);
|
||||
let tmp = parent.join(tmp_name);
|
||||
let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
|
||||
{
|
||||
let mut f = OpenOptions::new()
|
||||
.create(true)
|
||||
.write(true)
|
||||
.truncate(true)
|
||||
.open(&tmp)
|
||||
.map_err(|e| format!("effects temp open: {e}"))?;
|
||||
f.write_all(text.as_bytes())
|
||||
.map_err(|e| format!("effects temp write: {e}"))?;
|
||||
f.flush().map_err(|e| format!("effects temp flush: {e}"))?;
|
||||
f.sync_all()
|
||||
.map_err(|e| format!("effects temp fsync: {e}"))?;
|
||||
}
|
||||
if let Ok(dir) = File::open(parent) {
|
||||
let _ = dir.sync_all();
|
||||
}
|
||||
fs::rename(&tmp, path).map_err(|e| {
|
||||
let _ = fs::remove_file(&tmp);
|
||||
format!("effects atomic rename: {e}")
|
||||
})?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn load_record(path: &Path) -> Result<Option<Value>, String> {
|
||||
if !path.is_file() {
|
||||
return Ok(None);
|
||||
}
|
||||
let text = fs::read_to_string(path).map_err(|e| format!("effects read: {e}"))?;
|
||||
let doc: Value = serde_json::from_str(&text).map_err(|e| format!("effects corrupt: {e}"))?;
|
||||
Ok(Some(doc))
|
||||
}
|
||||
|
||||
fn valid_transition(from: &str, to: &str) -> bool {
|
||||
matches!(
|
||||
(from, to),
|
||||
("prepared", "started")
|
||||
| ("started", "committed")
|
||||
| ("started", "failed_no_effect")
|
||||
| ("started", "unknown")
|
||||
| ("unknown", "reconciled_committed")
|
||||
| ("unknown", "reconciled_no_effect")
|
||||
| ("unknown", "needs_input")
|
||||
// Idempotent no-ops / crash retries of the same terminal.
|
||||
| ("committed", "committed")
|
||||
| ("failed_no_effect", "failed_no_effect")
|
||||
| ("reconciled_committed", "reconciled_committed")
|
||||
| ("reconciled_no_effect", "reconciled_no_effect")
|
||||
| ("needs_input", "needs_input")
|
||||
// Re-prepare of same op is handled separately via idempotency.
|
||||
| ("prepared", "prepared")
|
||||
)
|
||||
}
|
||||
|
||||
fn effect_class_ok(c: &str) -> bool {
|
||||
matches!(c, "read" | "write" | "execute" | "external_write" | "none")
|
||||
}
|
||||
|
||||
/// Prepare (or return existing) an EffectLedgerRecordV1.
|
||||
pub fn effects_prepare(args: &Value) -> Result<Value, String> {
|
||||
let operation_id = arg_text(args, "operation_id")?;
|
||||
let idempotency_key = arg_text(args, "idempotency_key")?;
|
||||
let args_digest = arg_text(args, "args_digest")?;
|
||||
let effect_class = opt_text(args, "effect_class").unwrap_or("write");
|
||||
if !effect_class_ok(effect_class) {
|
||||
return Err(format!("invalid effect_class={effect_class}"));
|
||||
}
|
||||
let root = ledger_root(args)?;
|
||||
ensure_dir(&root)?;
|
||||
let path = record_path(&root, operation_id);
|
||||
|
||||
if let Some(existing) = load_record(&path)? {
|
||||
let same_key = existing
|
||||
.get("idempotency_key")
|
||||
.and_then(|v| v.as_str())
|
||||
== Some(idempotency_key);
|
||||
let same_digest = existing.get("args_digest").and_then(|v| v.as_str()) == Some(args_digest);
|
||||
if same_key && same_digest {
|
||||
return Ok(json!({
|
||||
"ok": true,
|
||||
"deduped": true,
|
||||
"record": existing,
|
||||
}));
|
||||
}
|
||||
if same_key && !same_digest {
|
||||
return Err(
|
||||
"idempotency_key collision: same key with different args_digest".into(),
|
||||
);
|
||||
}
|
||||
// Different operation_id path can't collide; same path different key is corrupt reuse.
|
||||
return Err("operation_id already exists with different idempotency_key".into());
|
||||
}
|
||||
|
||||
// Also scan for same idempotency_key under other operation_ids in this ledger dir.
|
||||
if let Ok(rd) = fs::read_dir(&root) {
|
||||
for ent in rd.flatten() {
|
||||
let p = ent.path();
|
||||
if p.extension().and_then(|e| e.to_str()) != Some("json") {
|
||||
continue;
|
||||
}
|
||||
if let Ok(Some(doc)) = load_record(&p) {
|
||||
if doc.get("idempotency_key").and_then(|v| v.as_str()) == Some(idempotency_key) {
|
||||
let dig = doc.get("args_digest").and_then(|v| v.as_str());
|
||||
if dig == Some(args_digest) {
|
||||
return Ok(json!({
|
||||
"ok": true,
|
||||
"deduped": true,
|
||||
"record": doc,
|
||||
}));
|
||||
}
|
||||
return Err(
|
||||
"idempotency_key collision: same key with different args_digest".into(),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let doc = json!({
|
||||
"schema": "EffectLedgerRecordV1",
|
||||
"schema_version": 1,
|
||||
"operation_id": operation_id,
|
||||
"idempotency_key": idempotency_key,
|
||||
"args_digest": args_digest,
|
||||
"resource_scope": args.get("resource_scope").cloned().unwrap_or(Value::Null),
|
||||
"expected_revision": args.get("expected_revision").cloned().unwrap_or(Value::Null),
|
||||
"effect_class": effect_class,
|
||||
"result_ref": args.get("result_ref").cloned().unwrap_or(Value::Null),
|
||||
"state": "prepared",
|
||||
"logical_run_id": args.get("logical_run_id").cloned().unwrap_or(Value::Null),
|
||||
"step_id": args.get("step_id").cloned().unwrap_or(Value::Null),
|
||||
"attempt_id": args.get("attempt_id").cloned().unwrap_or(Value::Null),
|
||||
"prepared_at": now_rfc3339(),
|
||||
"updated_at": now_rfc3339(),
|
||||
});
|
||||
atomic_write_json(&path, &doc)?;
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"deduped": false,
|
||||
"record": doc,
|
||||
"path": path.to_string_lossy(),
|
||||
}))
|
||||
}
|
||||
|
||||
/// Transition an existing record to a new state.
|
||||
pub fn effects_transition(args: &Value) -> Result<Value, String> {
|
||||
let operation_id = arg_text(args, "operation_id")?;
|
||||
let to = arg_text(args, "state")?;
|
||||
if !STATES.contains(&to) {
|
||||
return Err(format!("invalid state={to}"));
|
||||
}
|
||||
let root = ledger_root(args)?;
|
||||
let path = record_path(&root, operation_id);
|
||||
let mut doc = load_record(&path)?
|
||||
.ok_or_else(|| format!("operation_id not found: {operation_id}"))?;
|
||||
let from = doc
|
||||
.get("state")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("prepared")
|
||||
.to_string();
|
||||
if !valid_transition(&from, to) {
|
||||
return Err(format!("illegal transition {from} → {to}"));
|
||||
}
|
||||
if let Some(obj) = doc.as_object_mut() {
|
||||
obj.insert("state".into(), json!(to));
|
||||
obj.insert("updated_at".into(), json!(now_rfc3339()));
|
||||
if let Some(r) = args.get("result_ref") {
|
||||
if !r.is_null() {
|
||||
obj.insert("result_ref".into(), r.clone());
|
||||
}
|
||||
}
|
||||
if let Some(n) = args.get("note") {
|
||||
if !n.is_null() {
|
||||
obj.insert("note".into(), n.clone());
|
||||
}
|
||||
}
|
||||
if to == "unknown" || to.starts_with("reconciled") {
|
||||
obj.insert(
|
||||
"reconcile_hint".into(),
|
||||
args.get("reconcile_hint")
|
||||
.cloned()
|
||||
.unwrap_or_else(|| json!("check receipt / resource revision")),
|
||||
);
|
||||
}
|
||||
}
|
||||
atomic_write_json(&path, &doc)?;
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"from": from,
|
||||
"to": to,
|
||||
"record": doc,
|
||||
}))
|
||||
}
|
||||
|
||||
pub fn effects_get(args: &Value) -> Result<Value, String> {
|
||||
let operation_id = arg_text(args, "operation_id")?;
|
||||
let root = ledger_root(args)?;
|
||||
let path = record_path(&root, operation_id);
|
||||
match load_record(&path)? {
|
||||
Some(doc) => Ok(json!({
|
||||
"ok": true,
|
||||
"found": true,
|
||||
"record": doc,
|
||||
"path": path.to_string_lossy(),
|
||||
})),
|
||||
None => Ok(json!({
|
||||
"ok": true,
|
||||
"found": false,
|
||||
"operation_id": operation_id,
|
||||
"path": path.to_string_lossy(),
|
||||
})),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn effects_list(args: &Value) -> Result<Value, String> {
|
||||
let root = ledger_root(args)?;
|
||||
let mut records = Vec::new();
|
||||
if root.is_dir() {
|
||||
let mut paths: Vec<_> = fs::read_dir(&root)
|
||||
.map_err(|e| e.to_string())?
|
||||
.flatten()
|
||||
.map(|e| e.path())
|
||||
.filter(|p| p.extension().and_then(|e| e.to_str()) == Some("json"))
|
||||
.collect();
|
||||
paths.sort();
|
||||
for p in paths {
|
||||
if let Ok(Some(doc)) = load_record(&p) {
|
||||
if let Some(run) = opt_text(args, "logical_run_id") {
|
||||
if doc.get("logical_run_id").and_then(|v| v.as_str()) != Some(run) {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
if let Some(st) = opt_text(args, "state") {
|
||||
if doc.get("state").and_then(|v| v.as_str()) != Some(st) {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
records.push(doc);
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"count": records.len(),
|
||||
"records": records,
|
||||
"ledger_dir": root.to_string_lossy(),
|
||||
}))
|
||||
}
|
||||
|
||||
/// Compute a watermark digest over committed / reconciled records for a run.
|
||||
pub fn effects_watermark(args: &Value) -> Result<Value, String> {
|
||||
let listed = effects_list(args)?;
|
||||
let records = listed
|
||||
.get("records")
|
||||
.and_then(|v| v.as_array())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let mut parts = Vec::new();
|
||||
let mut open_unknown = 0u64;
|
||||
let mut pending_writes = 0u64;
|
||||
for r in &records {
|
||||
let state = r.get("state").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let oid = r.get("operation_id").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let cls = r.get("effect_class").and_then(|v| v.as_str()).unwrap_or("");
|
||||
parts.push(format!("{oid}:{state}"));
|
||||
if state == "unknown" || state == "needs_input" {
|
||||
open_unknown += 1;
|
||||
}
|
||||
if matches!(cls, "write" | "external_write" | "execute")
|
||||
&& matches!(state, "prepared" | "started" | "unknown" | "needs_input")
|
||||
{
|
||||
pending_writes += 1;
|
||||
}
|
||||
}
|
||||
parts.sort();
|
||||
let joined = parts.join("|");
|
||||
let digest = format!("sha256-lite:{:x}", fnv64(&joined));
|
||||
let write_auto_resume_safe = open_unknown == 0 && pending_writes == 0;
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"schema": "EffectLedgerWatermarkV1",
|
||||
"schema_version": 1,
|
||||
"watermark": digest,
|
||||
"record_count": records.len(),
|
||||
"open_unknown": open_unknown,
|
||||
"pending_writes": pending_writes,
|
||||
"write_auto_resume_safe": write_auto_resume_safe,
|
||||
"logical_run_id": args.get("logical_run_id").cloned().unwrap_or(Value::Null),
|
||||
}))
|
||||
}
|
||||
|
||||
/// Reconcile an `unknown` record after inspecting the external receipt / revision.
|
||||
pub fn effects_reconcile(args: &Value) -> Result<Value, String> {
|
||||
let outcome = arg_text(args, "outcome")?; // committed | no_effect | needs_input
|
||||
let state = match outcome {
|
||||
"committed" => "reconciled_committed",
|
||||
"no_effect" => "reconciled_no_effect",
|
||||
"needs_input" => "needs_input",
|
||||
other => return Err(format!("invalid reconcile outcome={other}")),
|
||||
};
|
||||
let mut targs = args.clone();
|
||||
if let Some(obj) = targs.as_object_mut() {
|
||||
obj.insert("state".into(), json!(state));
|
||||
}
|
||||
effects_transition(&targs)
|
||||
}
|
||||
|
||||
fn fnv64(s: &str) -> u64 {
|
||||
let mut h: u64 = 0xcbf29ce484222325;
|
||||
for b in s.as_bytes() {
|
||||
h ^= u64::from(*b);
|
||||
h = h.wrapping_mul(0x100000001b3);
|
||||
}
|
||||
h
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn scratch(tag: &str) -> PathBuf {
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"mq-effects-{}-{}-{}",
|
||||
tag,
|
||||
std::process::id(),
|
||||
now_rfc3339().replace(':', "")
|
||||
));
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
dir
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prepare_dedupe_and_collision() {
|
||||
let dir = scratch("prep");
|
||||
let prev = std::env::current_dir().unwrap();
|
||||
std::env::set_current_dir(&dir).unwrap();
|
||||
let a = effects_prepare(&json!({
|
||||
"operation_id": "op1",
|
||||
"idempotency_key": "idem1",
|
||||
"args_digest": "sha256:a",
|
||||
"effect_class": "write",
|
||||
"ledger_dir": "led",
|
||||
"logical_run_id": "run1",
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(a["deduped"], false);
|
||||
assert_eq!(a["record"]["state"], "prepared");
|
||||
|
||||
let again = effects_prepare(&json!({
|
||||
"operation_id": "op1",
|
||||
"idempotency_key": "idem1",
|
||||
"args_digest": "sha256:a",
|
||||
"ledger_dir": "led",
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(again["deduped"], true);
|
||||
|
||||
let clash = effects_prepare(&json!({
|
||||
"operation_id": "op2",
|
||||
"idempotency_key": "idem1",
|
||||
"args_digest": "sha256:b",
|
||||
"ledger_dir": "led",
|
||||
}));
|
||||
assert!(clash.unwrap_err().contains("collision"));
|
||||
|
||||
std::env::set_current_dir(prev).unwrap();
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn transition_and_watermark_gates_write_resume() {
|
||||
let dir = scratch("wm");
|
||||
let prev = std::env::current_dir().unwrap();
|
||||
std::env::set_current_dir(&dir).unwrap();
|
||||
effects_prepare(&json!({
|
||||
"operation_id": "op_w",
|
||||
"idempotency_key": "idem_w",
|
||||
"args_digest": "sha256:w",
|
||||
"effect_class": "write",
|
||||
"ledger_dir": "led",
|
||||
"logical_run_id": "run1",
|
||||
}))
|
||||
.unwrap();
|
||||
effects_transition(&json!({
|
||||
"operation_id": "op_w",
|
||||
"state": "started",
|
||||
"ledger_dir": "led",
|
||||
}))
|
||||
.unwrap();
|
||||
// Crash window: unknown — write auto-resume must stay closed.
|
||||
effects_transition(&json!({
|
||||
"operation_id": "op_w",
|
||||
"state": "unknown",
|
||||
"ledger_dir": "led",
|
||||
}))
|
||||
.unwrap();
|
||||
let wm1 = effects_watermark(&json!({
|
||||
"ledger_dir": "led",
|
||||
"logical_run_id": "run1",
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(wm1["write_auto_resume_safe"], false);
|
||||
assert_eq!(wm1["open_unknown"], 1);
|
||||
|
||||
effects_reconcile(&json!({
|
||||
"operation_id": "op_w",
|
||||
"outcome": "committed",
|
||||
"ledger_dir": "led",
|
||||
"result_ref": "receipt:1",
|
||||
}))
|
||||
.unwrap();
|
||||
let wm2 = effects_watermark(&json!({
|
||||
"ledger_dir": "led",
|
||||
"logical_run_id": "run1",
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(wm2["write_auto_resume_safe"], true);
|
||||
assert_eq!(wm2["open_unknown"], 0);
|
||||
assert!(wm2["watermark"].as_str().unwrap().starts_with("sha256-lite:"));
|
||||
|
||||
std::env::set_current_dir(prev).unwrap();
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ma_t03_unknown_then_reconcile_no_second_commit_path() {
|
||||
// Write "succeeds" locally only after reconcile; retry while unknown must not
|
||||
// look write_auto_resume_safe (MA-T03 watermark gate).
|
||||
let dir = scratch("mat03");
|
||||
let prev = std::env::current_dir().unwrap();
|
||||
std::env::set_current_dir(&dir).unwrap();
|
||||
effects_prepare(&json!({
|
||||
"operation_id": "op_kill",
|
||||
"idempotency_key": "run|s|write_probe|sha256-lite:1",
|
||||
"args_digest": "sha256-lite:1",
|
||||
"effect_class": "write",
|
||||
"ledger_dir": "led",
|
||||
"logical_run_id": "run_kill",
|
||||
}))
|
||||
.unwrap();
|
||||
effects_transition(&json!({
|
||||
"operation_id": "op_kill",
|
||||
"state": "started",
|
||||
"ledger_dir": "led",
|
||||
}))
|
||||
.unwrap();
|
||||
// Crash before commit:
|
||||
effects_transition(&json!({
|
||||
"operation_id": "op_kill",
|
||||
"state": "unknown",
|
||||
"ledger_dir": "led",
|
||||
}))
|
||||
.unwrap();
|
||||
let wm = effects_watermark(&json!({
|
||||
"ledger_dir": "led",
|
||||
"logical_run_id": "run_kill",
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(wm["write_auto_resume_safe"], false);
|
||||
|
||||
// Idempotent re-prepare returns same unknown record (no new op).
|
||||
let again = effects_prepare(&json!({
|
||||
"operation_id": "op_kill",
|
||||
"idempotency_key": "run|s|write_probe|sha256-lite:1",
|
||||
"args_digest": "sha256-lite:1",
|
||||
"effect_class": "write",
|
||||
"ledger_dir": "led",
|
||||
"logical_run_id": "run_kill",
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(again["deduped"], true);
|
||||
assert_eq!(again["record"]["state"], "unknown");
|
||||
|
||||
effects_reconcile(&json!({
|
||||
"operation_id": "op_kill",
|
||||
"outcome": "committed",
|
||||
"ledger_dir": "led",
|
||||
"result_ref": "effect:op_kill",
|
||||
}))
|
||||
.unwrap();
|
||||
let wm2 = effects_watermark(&json!({
|
||||
"ledger_dir": "led",
|
||||
"logical_run_id": "run_kill",
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(wm2["write_auto_resume_safe"], true);
|
||||
assert_eq!(wm2["pending_writes"], 0);
|
||||
|
||||
std::env::set_current_dir(prev).unwrap();
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn illegal_skip_started() {
|
||||
let dir = scratch("bad");
|
||||
let prev = std::env::current_dir().unwrap();
|
||||
std::env::set_current_dir(&dir).unwrap();
|
||||
effects_prepare(&json!({
|
||||
"operation_id": "op_x",
|
||||
"idempotency_key": "idem_x",
|
||||
"args_digest": "sha256:x",
|
||||
"ledger_dir": "led",
|
||||
}))
|
||||
.unwrap();
|
||||
let err = effects_transition(&json!({
|
||||
"operation_id": "op_x",
|
||||
"state": "committed",
|
||||
"ledger_dir": "led",
|
||||
}))
|
||||
.unwrap_err();
|
||||
assert!(err.contains("illegal transition"));
|
||||
std::env::set_current_dir(prev).unwrap();
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,274 @@
|
||||
//! AgentErrorV1 — classified errors and bounded recovery decisions (M-A1).
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
/// Build an AgentErrorV1 document from caller fields (compat: missing → defaults).
|
||||
pub fn make_error(args: &Value) -> Result<Value, String> {
|
||||
let code = args
|
||||
.get("code")
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.ok_or_else(|| "missing text `code`".to_string())?;
|
||||
let category = args
|
||||
.get("category")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or_else(|| infer_category(code));
|
||||
let stage = args
|
||||
.get("stage")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("agent");
|
||||
let message = args
|
||||
.get("message")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(code);
|
||||
let retryable = args
|
||||
.get("retryable")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or_else(|| default_retryable(category));
|
||||
let effect_state = args
|
||||
.get("effect_state")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("none");
|
||||
let recovery_action = args
|
||||
.get("recovery_action")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or_else(|| default_recovery(category, effect_state));
|
||||
|
||||
let mut out = json!({
|
||||
"schema": "AgentErrorV1",
|
||||
"schema_version": 1,
|
||||
"code": code,
|
||||
"category": category,
|
||||
"stage": stage,
|
||||
"message": message,
|
||||
"retryable": retryable,
|
||||
"effect_state": effect_state,
|
||||
"recovery_action": recovery_action,
|
||||
});
|
||||
if let Some(obj) = out.as_object_mut() {
|
||||
if let Some(v) = args.get("retry_after_ms") {
|
||||
obj.insert("retry_after_ms".into(), v.clone());
|
||||
} else {
|
||||
obj.insert("retry_after_ms".into(), Value::Null);
|
||||
}
|
||||
for key in ["call_id", "details_ref", "fingerprint"] {
|
||||
if let Some(v) = args.get(key) {
|
||||
if !v.is_null() {
|
||||
obj.insert(key.into(), v.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Decide whether a step may auto-retry (read-only / no-effect only in M-A1).
|
||||
///
|
||||
/// Returns `{ok, action, reason, attempts_used, max_attempts}`.
|
||||
pub fn decide_retry(args: &Value) -> Result<Value, String> {
|
||||
let error = args
|
||||
.get("error")
|
||||
.cloned()
|
||||
.ok_or_else(|| "missing map `error`".to_string())?;
|
||||
let attempts = args
|
||||
.get("attempts")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(0) as u32;
|
||||
let max_transport = args
|
||||
.get("max_transport_attempts")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(3) as u32; // 1 initial + 2 retries
|
||||
let max_arg_repair = args
|
||||
.get("max_arg_repairs")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(1) as u32;
|
||||
let effect_class = args
|
||||
.get("effect_class")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("read");
|
||||
let cancelled = args
|
||||
.get("cancelled")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(false);
|
||||
let fingerprint_repeats = args
|
||||
.get("fingerprint_repeats")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(0) as u32;
|
||||
|
||||
if cancelled {
|
||||
return Ok(decision("stop", "cancelled", attempts, max_transport));
|
||||
}
|
||||
|
||||
let category = error
|
||||
.get("category")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("unknown");
|
||||
let retryable = error
|
||||
.get("retryable")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(false);
|
||||
let effect_state = error
|
||||
.get("effect_state")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("none");
|
||||
let recovery = error
|
||||
.get("recovery_action")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("none");
|
||||
|
||||
// Write / unknown effect: never auto-retry in M-A1 (ledger required).
|
||||
if effect_class != "read" || matches!(effect_state, "unknown" | "started" | "committed") {
|
||||
return Ok(decision(
|
||||
"manual_review",
|
||||
"write_or_unknown_effect_requires_ledger",
|
||||
attempts,
|
||||
max_transport,
|
||||
));
|
||||
}
|
||||
|
||||
if fingerprint_repeats >= 2 {
|
||||
return Ok(decision(
|
||||
"stop",
|
||||
"error_fingerprint_loop",
|
||||
attempts,
|
||||
max_transport,
|
||||
));
|
||||
}
|
||||
|
||||
match category {
|
||||
"transient" if retryable && attempts + 1 < max_transport => Ok(decision(
|
||||
"retry_step",
|
||||
"transient_read_safe",
|
||||
attempts,
|
||||
max_transport,
|
||||
)),
|
||||
"invalid_arguments" if recovery == "repair_args" && attempts < max_arg_repair => Ok(
|
||||
decision("repair_args", "one_arg_repair", attempts, max_arg_repair),
|
||||
),
|
||||
"auth" | "forbidden" | "policy_denied" => Ok(decision(
|
||||
"needs_input",
|
||||
category,
|
||||
attempts,
|
||||
max_transport,
|
||||
)),
|
||||
"budget_exhausted" => Ok(decision("partial", category, attempts, max_transport)),
|
||||
"cancelled" => Ok(decision("stop", "cancelled", attempts, max_transport)),
|
||||
"unknown_effect" | "worker_crash" => Ok(decision(
|
||||
"manual_review",
|
||||
category,
|
||||
attempts,
|
||||
max_transport,
|
||||
)),
|
||||
_ => Ok(decision("stop", "not_auto_retryable", attempts, max_transport)),
|
||||
}
|
||||
}
|
||||
|
||||
fn decision(action: &str, reason: &str, attempts: u32, max_attempts: u32) -> Value {
|
||||
json!({
|
||||
"ok": true,
|
||||
"schema": "AgentRetryDecisionV1",
|
||||
"schema_version": 1,
|
||||
"action": action,
|
||||
"reason": reason,
|
||||
"attempts_used": attempts,
|
||||
"max_attempts": max_attempts,
|
||||
"auto": matches!(action, "retry_step" | "repair_args"),
|
||||
})
|
||||
}
|
||||
|
||||
fn infer_category(code: &str) -> &'static str {
|
||||
let c = code.to_ascii_lowercase();
|
||||
if c.contains("timeout") || c.contains("429") || c.contains("5xx") || c.contains("connect") {
|
||||
"transient"
|
||||
} else if c.contains("schema") || c.contains("argument") {
|
||||
"invalid_arguments"
|
||||
} else if c.contains("auth") {
|
||||
"auth"
|
||||
} else if c.contains("forbid") {
|
||||
"forbidden"
|
||||
} else if c.contains("policy") {
|
||||
"policy_denied"
|
||||
} else if c.contains("budget") {
|
||||
"budget_exhausted"
|
||||
} else if c.contains("cancel") {
|
||||
"cancelled"
|
||||
} else if c.contains("conflict") || c.contains("stale") {
|
||||
"conflict"
|
||||
} else if c.contains("effect") || c.contains("crash") {
|
||||
"unknown_effect"
|
||||
} else {
|
||||
"unknown"
|
||||
}
|
||||
}
|
||||
|
||||
fn default_retryable(category: &str) -> bool {
|
||||
matches!(category, "transient")
|
||||
}
|
||||
|
||||
fn default_recovery(category: &str, effect_state: &str) -> &'static str {
|
||||
if effect_state == "unknown" {
|
||||
return "reconcile";
|
||||
}
|
||||
match category {
|
||||
"transient" => "retry_step",
|
||||
"invalid_arguments" => "repair_args",
|
||||
"auth" | "forbidden" | "policy_denied" | "needs_input" => "needs_input",
|
||||
"budget_exhausted" => "return_partial",
|
||||
"cancelled" => "stop",
|
||||
"unknown_effect" | "worker_crash" => "manual_review",
|
||||
_ => "stop",
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn make_error_defaults() {
|
||||
let err = make_error(&json!({"code": "tool.timeout", "message": "t"})).unwrap();
|
||||
assert_eq!(err["schema"], "AgentErrorV1");
|
||||
assert_eq!(err["category"], "transient");
|
||||
assert_eq!(err["retryable"], true);
|
||||
assert_eq!(err["recovery_action"], "retry_step");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn read_transient_retries_once() {
|
||||
let err = make_error(&json!({"code": "tool.timeout"})).unwrap();
|
||||
let d = decide_retry(&json!({
|
||||
"error": err,
|
||||
"attempts": 0,
|
||||
"effect_class": "read"
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(d["action"], "retry_step");
|
||||
assert_eq!(d["auto"], true);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn write_never_auto_retries() {
|
||||
let err = make_error(&json!({"code": "tool.timeout"})).unwrap();
|
||||
let d = decide_retry(&json!({
|
||||
"error": err,
|
||||
"attempts": 0,
|
||||
"effect_class": "write"
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(d["action"], "manual_review");
|
||||
assert_eq!(d["auto"], false);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn fingerprint_loop_stops() {
|
||||
let err = make_error(&json!({"code": "tool.timeout"})).unwrap();
|
||||
let d = decide_retry(&json!({
|
||||
"error": err,
|
||||
"attempts": 0,
|
||||
"effect_class": "read",
|
||||
"fingerprint_repeats": 2
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(d["action"], "stop");
|
||||
}
|
||||
}
|
||||
+150
-1
@@ -1,14 +1,19 @@
|
||||
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route.
|
||||
|
||||
mod context_pack;
|
||||
mod corpus;
|
||||
mod effects;
|
||||
mod eng;
|
||||
mod error;
|
||||
mod kb;
|
||||
mod mcp_client;
|
||||
mod mcp_server;
|
||||
mod memory;
|
||||
mod output;
|
||||
mod resume;
|
||||
mod route;
|
||||
mod sandbox;
|
||||
mod tools;
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::ffi::CString;
|
||||
@@ -667,7 +672,7 @@ unsafe extern "C" fn agent_marqdo_skill(
|
||||
}
|
||||
}
|
||||
|
||||
fn tool_names(tools: &serde_json::Value) -> Vec<String> {
|
||||
pub(crate) fn tool_names(tools: &serde_json::Value) -> Vec<String> {
|
||||
let mut out = Vec::new();
|
||||
let rows = match tools {
|
||||
serde_json::Value::Array(a) => a.as_slice(),
|
||||
@@ -829,6 +834,86 @@ kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save");
|
||||
kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load");
|
||||
kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear");
|
||||
kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list");
|
||||
kb_ffi!(agent_error_make, error::make_error, "agent_error_make");
|
||||
kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry");
|
||||
kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register");
|
||||
kb_ffi!(agent_tools_clear, tools::tools_clear, "agent_tools_clear");
|
||||
kb_ffi!(agent_tools_search, tools::tools_search, "agent_tools_search");
|
||||
kb_ffi!(agent_tools_describe, tools::tools_describe, "agent_tools_describe");
|
||||
kb_ffi!(agent_tools_prepare_call, tools::tools_prepare_call, "agent_tools_prepare_call");
|
||||
kb_ffi!(agent_tools_wrap_result, tools::tools_wrap_result, "agent_tools_wrap_result");
|
||||
kb_ffi!(
|
||||
agent_tools_args_digest,
|
||||
tools::tools_args_digest,
|
||||
"agent_tools_args_digest"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_tools_needs_ledger,
|
||||
tools::tools_needs_ledger,
|
||||
"agent_tools_needs_ledger"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_tools_register_eng_defaults,
|
||||
tools::tools_register_eng_defaults,
|
||||
"agent_tools_register_eng_defaults"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_tools_seed_allowlist,
|
||||
tools::seed_from_allowlist_args,
|
||||
"agent_tools_seed_allowlist"
|
||||
);
|
||||
kb_ffi!(agent_output_build, output::output_build, "agent_output_build");
|
||||
kb_ffi!(
|
||||
agent_output_apply_policy,
|
||||
output::output_apply_policy,
|
||||
"agent_output_apply_policy"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_output_channel_event,
|
||||
output::output_channel_event,
|
||||
"agent_output_channel_event"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_output_project_conclusion,
|
||||
output::output_project_conclusion,
|
||||
"agent_output_project_conclusion"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_context_pack_build,
|
||||
context_pack::context_pack_build,
|
||||
"agent_context_pack_build"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_context_pack_compact,
|
||||
context_pack::context_pack_compact,
|
||||
"agent_context_pack_compact"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_effects_prepare,
|
||||
effects::effects_prepare,
|
||||
"agent_effects_prepare"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_effects_transition,
|
||||
effects::effects_transition,
|
||||
"agent_effects_transition"
|
||||
);
|
||||
kb_ffi!(agent_effects_get, effects::effects_get, "agent_effects_get");
|
||||
kb_ffi!(
|
||||
agent_effects_list,
|
||||
effects::effects_list,
|
||||
"agent_effects_list"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_effects_watermark,
|
||||
effects::effects_watermark,
|
||||
"agent_effects_watermark"
|
||||
);
|
||||
kb_ffi!(
|
||||
agent_effects_reconcile,
|
||||
effects::effects_reconcile,
|
||||
"agent_effects_reconcile"
|
||||
);
|
||||
kb_ffi!(agent_eng_preflight, eng::eng_preflight, "agent_eng_preflight");
|
||||
kb_ffi!(agent_eng_reuse, eng::eng_reuse, "agent_eng_reuse");
|
||||
kb_ffi!(agent_eng_bind_execute, eng::eng_bind_execute, "agent_eng_bind_execute");
|
||||
@@ -878,6 +963,70 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
|
||||
("agent_resume_load", "id,resume_dir", agent_resume_load),
|
||||
("agent_resume_clear", "id,resume_dir", agent_resume_clear),
|
||||
("agent_resume_list", "resume_dir", agent_resume_list),
|
||||
("agent_error_make", "code,message,category", agent_error_make),
|
||||
("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry),
|
||||
("agent_tools_register", "spec,specs", agent_tools_register),
|
||||
("agent_tools_clear", "", agent_tools_clear),
|
||||
("agent_tools_search", "query,tools", agent_tools_search),
|
||||
("agent_tools_describe", "id,tools", agent_tools_describe),
|
||||
("agent_tools_prepare_call", "tool_id,arguments,tools", agent_tools_prepare_call),
|
||||
("agent_tools_wrap_result", "ok,status,summary", agent_tools_wrap_result),
|
||||
("agent_tools_args_digest", "arguments", agent_tools_args_digest),
|
||||
("agent_tools_needs_ledger", "effect", agent_tools_needs_ledger),
|
||||
(
|
||||
"agent_tools_register_eng_defaults",
|
||||
"",
|
||||
agent_tools_register_eng_defaults,
|
||||
),
|
||||
("agent_tools_seed_allowlist", "tools", agent_tools_seed_allowlist),
|
||||
("agent_output_build", "status,text,validation", agent_output_build),
|
||||
(
|
||||
"agent_output_apply_policy",
|
||||
"status,text,policy",
|
||||
agent_output_apply_policy,
|
||||
),
|
||||
(
|
||||
"agent_output_channel_event",
|
||||
"channel,delta",
|
||||
agent_output_channel_event,
|
||||
),
|
||||
(
|
||||
"agent_output_project_conclusion",
|
||||
"document",
|
||||
agent_output_project_conclusion,
|
||||
),
|
||||
(
|
||||
"agent_context_pack_build",
|
||||
"items,budget_tokens",
|
||||
agent_context_pack_build,
|
||||
),
|
||||
(
|
||||
"agent_context_pack_compact",
|
||||
"items,budget_tokens",
|
||||
agent_context_pack_compact,
|
||||
),
|
||||
(
|
||||
"agent_effects_prepare",
|
||||
"operation_id,idempotency_key,args_digest",
|
||||
agent_effects_prepare,
|
||||
),
|
||||
(
|
||||
"agent_effects_transition",
|
||||
"operation_id,state",
|
||||
agent_effects_transition,
|
||||
),
|
||||
("agent_effects_get", "operation_id", agent_effects_get),
|
||||
("agent_effects_list", "ledger_dir", agent_effects_list),
|
||||
(
|
||||
"agent_effects_watermark",
|
||||
"ledger_dir",
|
||||
agent_effects_watermark,
|
||||
),
|
||||
(
|
||||
"agent_effects_reconcile",
|
||||
"operation_id,outcome",
|
||||
agent_effects_reconcile,
|
||||
),
|
||||
("agent_kb_add_alias", "kb_dir,slug,alias", agent_kb_add_alias),
|
||||
("agent_kb_promote", "kb_dir,goal,workbook", agent_kb_promote),
|
||||
("agent_kb_quarantine", "kb_dir,slug", agent_kb_quarantine),
|
||||
|
||||
@@ -0,0 +1,289 @@
|
||||
//! AgentOutputV1 + ResponsePolicy (M-A4).
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
|
||||
args.get(key)
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
}
|
||||
|
||||
/// Normalize / build an AgentOutputV1 document.
|
||||
pub fn output_build(args: &Value) -> Result<Value, String> {
|
||||
let status = opt_text(args, "status").unwrap_or("succeeded");
|
||||
if !matches!(
|
||||
status,
|
||||
"succeeded" | "partial" | "failed" | "needs_input" | "cancelled"
|
||||
) {
|
||||
return Err(format!("invalid status={status}"));
|
||||
}
|
||||
let answer = args.get("answer").cloned().unwrap_or_else(|| {
|
||||
json!({
|
||||
"format": opt_text(args, "format").unwrap_or("markdown"),
|
||||
"text": opt_text(args, "text").unwrap_or(""),
|
||||
})
|
||||
});
|
||||
let validation = args.get("validation").cloned().unwrap_or_else(|| {
|
||||
json!({
|
||||
"status": "not_run",
|
||||
"report_ref": Value::Null
|
||||
})
|
||||
});
|
||||
let vstatus = validation
|
||||
.get("status")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("not_run");
|
||||
if !matches!(
|
||||
vstatus,
|
||||
"passed" | "failed" | "not_applicable" | "not_run"
|
||||
) {
|
||||
return Err(format!("invalid validation.status={vstatus}"));
|
||||
}
|
||||
// Never claim passed without an explicit report when status says passed.
|
||||
if vstatus == "passed" && validation.get("report_ref").map(|v| v.is_null()).unwrap_or(true) {
|
||||
if args.get("allow_passed_without_report").and_then(|v| v.as_bool()) != Some(true) {
|
||||
return Err("validation.status=passed requires report_ref".into());
|
||||
}
|
||||
}
|
||||
|
||||
let finish = opt_text(args, "finish_reason").unwrap_or(match status {
|
||||
"succeeded" => "completed",
|
||||
"partial" => "length_limited",
|
||||
"cancelled" => "cancelled",
|
||||
"needs_input" => "needs_input",
|
||||
_ => "error",
|
||||
});
|
||||
|
||||
Ok(json!({
|
||||
"schema": "AgentOutputV1",
|
||||
"schema_version": 1,
|
||||
"status": status,
|
||||
"answer": answer,
|
||||
"artifacts": args.get("artifacts").cloned().unwrap_or_else(|| json!([])),
|
||||
"citations": args.get("citations").cloned().unwrap_or_else(|| json!([])),
|
||||
"validation": validation,
|
||||
"finish_reason": finish,
|
||||
"recovery_options": args.get("recovery_options").cloned().unwrap_or_else(|| json!([])),
|
||||
"channels": args.get("channels").cloned().unwrap_or_else(|| json!({
|
||||
"answer": true,
|
||||
"artifact": true,
|
||||
"progress": true,
|
||||
"diagnostic": true
|
||||
})),
|
||||
}))
|
||||
}
|
||||
|
||||
/// Apply ResponsePolicy budgets to an answer text → possibly partial output.
|
||||
pub fn output_apply_policy(args: &Value) -> Result<Value, String> {
|
||||
let mut out = if args.get("schema").and_then(|v| v.as_str()) == Some("AgentOutputV1") {
|
||||
args.clone()
|
||||
} else {
|
||||
output_build(args)?
|
||||
};
|
||||
let policy = args.get("policy").cloned().unwrap_or(json!({}));
|
||||
let detail = policy
|
||||
.get("detail")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("standard");
|
||||
let max_chars = match policy.get("max_chars").and_then(|v| v.as_u64()) {
|
||||
Some(n) if n > 0 => n as usize,
|
||||
_ => match detail {
|
||||
"concise" => 250,
|
||||
"detailed" => 8_000,
|
||||
_ => 700,
|
||||
},
|
||||
};
|
||||
let max_tokens = policy
|
||||
.get("max_output_tokens")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(0) as usize;
|
||||
let artifact_allowed = policy
|
||||
.get("artifact_allowed")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(true);
|
||||
|
||||
let text = out
|
||||
.pointer("/answer/text")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
// Soft char budget (CJK-aware enough: count Unicode scalars).
|
||||
let chars: Vec<char> = text.chars().collect();
|
||||
let mut finish = out
|
||||
.get("finish_reason")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("completed")
|
||||
.to_string();
|
||||
let mut status = out
|
||||
.get("status")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("succeeded")
|
||||
.to_string();
|
||||
let mut answer_text = text.clone();
|
||||
if chars.len() > max_chars {
|
||||
answer_text = chars.into_iter().take(max_chars).collect();
|
||||
// Prefer not to cut mid-code fence if possible — soft trim at last newline.
|
||||
if let Some(pos) = answer_text.rfind('\n') {
|
||||
if pos > max_chars / 2 {
|
||||
answer_text.truncate(pos);
|
||||
}
|
||||
}
|
||||
finish = "length_limited".into();
|
||||
if status == "succeeded" {
|
||||
status = "partial".into();
|
||||
}
|
||||
}
|
||||
// Token budget is advisory here (chars/4 approx) when max_output_tokens set.
|
||||
if max_tokens > 0 {
|
||||
let approx = answer_text.chars().count().div_ceil(2); // rough CJK token estimate
|
||||
if approx > max_tokens {
|
||||
let keep = max_tokens.saturating_mul(2);
|
||||
answer_text = answer_text.chars().take(keep).collect();
|
||||
finish = "length_limited".into();
|
||||
status = "partial".into();
|
||||
}
|
||||
}
|
||||
|
||||
if let Some(obj) = out.as_object_mut() {
|
||||
obj.insert("status".into(), json!(status));
|
||||
obj.insert("finish_reason".into(), json!(finish));
|
||||
if let Some(ans) = obj.get_mut("answer").and_then(|v| v.as_object_mut()) {
|
||||
ans.insert("text".into(), json!(answer_text));
|
||||
}
|
||||
if !artifact_allowed {
|
||||
obj.insert("artifacts".into(), json!([]));
|
||||
}
|
||||
obj.insert(
|
||||
"response_policy".into(),
|
||||
json!({
|
||||
"detail": detail,
|
||||
"max_chars": max_chars,
|
||||
"max_output_tokens": max_tokens,
|
||||
"artifact_allowed": artifact_allowed,
|
||||
}),
|
||||
);
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Split a channel event. Only `answer` is meant for chat body append.
|
||||
pub fn output_channel_event(args: &Value) -> Result<Value, String> {
|
||||
let channel = opt_text(args, "channel").ok_or_else(|| "missing channel".to_string())?;
|
||||
if !matches!(channel, "answer" | "artifact" | "progress" | "diagnostic") {
|
||||
return Err(format!("invalid channel={channel}"));
|
||||
}
|
||||
let delta = opt_text(args, "delta").unwrap_or("");
|
||||
Ok(json!({
|
||||
"schema": "AgentChannelEventV1",
|
||||
"schema_version": 1,
|
||||
"channel": channel,
|
||||
"delta": delta,
|
||||
"append_to_chat": channel == "answer",
|
||||
"resource_id": args.get("resource_id").cloned().unwrap_or(Value::Null),
|
||||
"meta": args.get("meta").cloned().unwrap_or(json!({})),
|
||||
}))
|
||||
}
|
||||
|
||||
/// Project `# 结论` (or first non-empty paragraph) from a marqdo document for chat.
|
||||
pub fn output_project_conclusion(args: &Value) -> Result<Value, String> {
|
||||
let doc = opt_text(args, "document")
|
||||
.or_else(|| opt_text(args, "text"))
|
||||
.unwrap_or("");
|
||||
let mut in_conclusion = false;
|
||||
let mut buf = String::new();
|
||||
for line in doc.lines() {
|
||||
let t = line.trim();
|
||||
if t == "# 结论" || t.eq_ignore_ascii_case("# conclusion") {
|
||||
in_conclusion = true;
|
||||
continue;
|
||||
}
|
||||
if in_conclusion {
|
||||
if t.starts_with("# ") {
|
||||
break;
|
||||
}
|
||||
if t.is_empty() {
|
||||
if !buf.is_empty() {
|
||||
buf.push('\n');
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if !buf.is_empty() {
|
||||
buf.push('\n');
|
||||
}
|
||||
buf.push_str(t);
|
||||
}
|
||||
}
|
||||
if buf.trim().is_empty() {
|
||||
// Fallback: first non-frontmatter paragraph.
|
||||
let mut past_fm = !doc.starts_with("---");
|
||||
let mut fm_done = past_fm;
|
||||
for line in doc.lines() {
|
||||
if !fm_done {
|
||||
if line.trim() == "---" {
|
||||
if past_fm {
|
||||
fm_done = true;
|
||||
} else {
|
||||
past_fm = true;
|
||||
}
|
||||
}
|
||||
continue;
|
||||
}
|
||||
let t = line.trim();
|
||||
if t.is_empty() || t.starts_with('#') || t.starts_with('|') {
|
||||
continue;
|
||||
}
|
||||
buf = t.to_string();
|
||||
break;
|
||||
}
|
||||
}
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"text": buf.trim(),
|
||||
"channel": "answer",
|
||||
"source": "conclusion_projection",
|
||||
}))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn build_and_policy_limits() {
|
||||
let out = output_build(&json!({
|
||||
"status": "succeeded",
|
||||
"text": "短答",
|
||||
"validation": {"status": "not_applicable", "report_ref": null}
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(out["schema"], "AgentOutputV1");
|
||||
assert_eq!(out["answer"]["text"], "短答");
|
||||
|
||||
let long: String = "字".repeat(400);
|
||||
let limited = output_apply_policy(&json!({
|
||||
"status": "succeeded",
|
||||
"text": long,
|
||||
"validation": {"status": "not_applicable"},
|
||||
"policy": {"detail": "concise", "max_chars": 100}
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(limited["status"], "partial");
|
||||
assert_eq!(limited["finish_reason"], "length_limited");
|
||||
assert!(limited["answer"]["text"].as_str().unwrap().chars().count() <= 100);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn channel_answer_only_appends_chat() {
|
||||
let e = output_channel_event(&json!({"channel": "progress", "delta": "检索中"})).unwrap();
|
||||
assert_eq!(e["append_to_chat"], false);
|
||||
let a = output_channel_event(&json!({"channel": "answer", "delta": "hi"})).unwrap();
|
||||
assert_eq!(a["append_to_chat"], true);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn project_conclusion() {
|
||||
let doc = "---\ntitle: t\n---\n\n# 任务\n问\n\n# 结论\n答案是 42。\n\n# main\nprint\n";
|
||||
let p = output_project_conclusion(&json!({"document": doc})).unwrap();
|
||||
assert!(p["text"].as_str().unwrap().contains("42"));
|
||||
}
|
||||
}
|
||||
+348
-16
@@ -1,6 +1,8 @@
|
||||
//! Agent plan/run resume checkpoints under `.marqdo/agent-resume/`.
|
||||
//! M-A1: CheckpointV2 atomic write (temp→fsync→rename); legacy load → manual_review.
|
||||
|
||||
use std::fs;
|
||||
use std::fs::{self, File, OpenOptions};
|
||||
use std::io::Write;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde_json::{json, Value};
|
||||
@@ -27,7 +29,9 @@ fn resolve_path(rel: &str) -> PathBuf {
|
||||
}
|
||||
|
||||
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
|
||||
args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty())
|
||||
args.get(key)
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
}
|
||||
|
||||
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
|
||||
@@ -43,9 +47,19 @@ fn opt_i64(args: &Value, key: &str, default: i64) -> i64 {
|
||||
}
|
||||
}
|
||||
|
||||
fn resume_root(args: &Value) -> PathBuf {
|
||||
/// Host-relative resume roots only — reject absolute client paths (M-A1).
|
||||
fn resume_root(args: &Value) -> Result<PathBuf, String> {
|
||||
let rel = opt_text(args, "resume_dir").unwrap_or(DEFAULT_RESUME_DIR);
|
||||
resolve_path(rel)
|
||||
let p = PathBuf::from(rel);
|
||||
if p.is_absolute() {
|
||||
return Err(
|
||||
"resume_dir must be host-relative; absolute client paths are rejected".into(),
|
||||
);
|
||||
}
|
||||
if rel.contains("..") {
|
||||
return Err("resume_dir must not contain '..'".into());
|
||||
}
|
||||
Ok(resolve_path(rel))
|
||||
}
|
||||
|
||||
fn checkpoint_path(root: &Path, id: &str) -> PathBuf {
|
||||
@@ -70,11 +84,106 @@ fn ensure_dir(root: &Path) -> Result<(), String> {
|
||||
fs::create_dir_all(root).map_err(|e| format!("resume mkdir: {e}"))
|
||||
}
|
||||
|
||||
pub fn resume_save(args: &Value) -> Result<Value, String> {
|
||||
let id = arg_text(args, "id")?;
|
||||
let root = resume_root(args);
|
||||
ensure_dir(&root)?;
|
||||
let path = checkpoint_path(&root, id);
|
||||
/// Atomic durable write: unique temp → write → flush/fsync → rename.
|
||||
fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
|
||||
let parent = path
|
||||
.parent()
|
||||
.ok_or_else(|| "checkpoint path has no parent".to_string())?;
|
||||
ensure_dir(parent)?;
|
||||
let tmp_name = format!(
|
||||
".{}.tmp-{}-{}",
|
||||
path.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or("ckpt.json"),
|
||||
std::process::id(),
|
||||
now_rfc3339().replace(':', "")
|
||||
);
|
||||
let tmp = parent.join(tmp_name);
|
||||
let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
|
||||
{
|
||||
let mut f = OpenOptions::new()
|
||||
.create(true)
|
||||
.write(true)
|
||||
.truncate(true)
|
||||
.open(&tmp)
|
||||
.map_err(|e| format!("resume temp open: {e}"))?;
|
||||
f.write_all(text.as_bytes())
|
||||
.map_err(|e| format!("resume temp write: {e}"))?;
|
||||
f.flush().map_err(|e| format!("resume temp flush: {e}"))?;
|
||||
f.sync_all()
|
||||
.map_err(|e| format!("resume temp fsync: {e}"))?;
|
||||
}
|
||||
// Best-effort directory fsync (platform may ignore).
|
||||
if let Ok(dir) = File::open(parent) {
|
||||
let _ = dir.sync_all();
|
||||
}
|
||||
fs::rename(&tmp, path).map_err(|e| {
|
||||
let _ = fs::remove_file(&tmp);
|
||||
format!("resume atomic rename: {e}")
|
||||
})?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn wants_checkpoint_v2(args: &Value) -> bool {
|
||||
matches!(
|
||||
args.get("schema").and_then(|v| v.as_str()),
|
||||
Some("CheckpointV2")
|
||||
) || args.get("schema_version").and_then(|v| v.as_u64()) == Some(2)
|
||||
|| args.get("checkpoint_v2").and_then(|v| v.as_bool()) == Some(true)
|
||||
}
|
||||
|
||||
fn build_checkpoint_v2(args: &Value, id: &str) -> Value {
|
||||
let committed = now_rfc3339();
|
||||
let mut doc = json!({
|
||||
"schema": "CheckpointV2",
|
||||
"schema_version": 2,
|
||||
"checkpoint_id": args.get("checkpoint_id").cloned().unwrap_or_else(|| json!(id)),
|
||||
"logical_run_id": args.get("logical_run_id").cloned().unwrap_or_else(|| json!(id)),
|
||||
"task_id": args.get("task_id").cloned().unwrap_or_else(|| json!(id)),
|
||||
"attempt_id": args.get("attempt_id").cloned().unwrap_or_else(|| json!("attempt_1")),
|
||||
"step_id": args.get("step_id").cloned().unwrap_or(Value::Null),
|
||||
"parent_checkpoint_id": args.get("parent_checkpoint_id").cloned().unwrap_or(Value::Null),
|
||||
"principal_ref": args.get("principal_ref").cloned().unwrap_or(Value::Null),
|
||||
"workspace_id": args.get("workspace_id").cloned().unwrap_or(Value::Null),
|
||||
"session_id": args.get("session_id").cloned().unwrap_or(Value::Null),
|
||||
"completed_steps": args.get("completed_steps").cloned().unwrap_or_else(|| json!([])),
|
||||
"pending_operation": args.get("pending_operation").cloned().unwrap_or(Value::Null),
|
||||
"deadline": args.get("deadline").cloned().unwrap_or(Value::Null),
|
||||
"committed_at": args.get("committed_at").cloned().unwrap_or_else(|| json!(committed)),
|
||||
// Effect watermark — absent/null means no ledger yet (write auto-resume closed).
|
||||
"effect_ledger_watermark": args.get("effect_ledger_watermark").cloned().unwrap_or(Value::Null),
|
||||
"event_seq": args.get("event_seq").cloned().unwrap_or(Value::Null),
|
||||
"manifest_digest": args.get("manifest_digest").cloned().unwrap_or(Value::Null),
|
||||
});
|
||||
if let Some(obj) = doc.as_object_mut() {
|
||||
// Preserve legacy author fields for dual-read.
|
||||
for key in [
|
||||
"goal", "task", "status", "workbook", "events", "route", "result", "round", "meta",
|
||||
"id",
|
||||
] {
|
||||
if let Some(v) = args.get(key) {
|
||||
if !v.is_null() {
|
||||
obj.insert(key.to_string(), v.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
if !obj.contains_key("id") {
|
||||
obj.insert("id".into(), json!(id));
|
||||
}
|
||||
if !obj.contains_key("updated_at") {
|
||||
obj.insert("updated_at".into(), json!(committed.clone()));
|
||||
}
|
||||
if !obj.contains_key("round") {
|
||||
obj.insert("round".into(), json!(opt_i64(args, "round", 0)));
|
||||
}
|
||||
if !obj.contains_key("status") {
|
||||
obj.insert("status".into(), json!("running"));
|
||||
}
|
||||
}
|
||||
doc
|
||||
}
|
||||
|
||||
fn build_legacy_doc(args: &Value, id: &str) -> Value {
|
||||
let mut doc = json!({
|
||||
"id": id,
|
||||
"updated_at": now_rfc3339(),
|
||||
@@ -96,19 +205,84 @@ pub fn resume_save(args: &Value) -> Result<Value, String> {
|
||||
obj.insert("status".into(), json!("running"));
|
||||
}
|
||||
}
|
||||
let text = serde_json::to_string_pretty(&doc).map_err(|e| e.to_string())?;
|
||||
fs::write(&path, text).map_err(|e| format!("resume save: {e}"))?;
|
||||
doc
|
||||
}
|
||||
|
||||
pub fn resume_save(args: &Value) -> Result<Value, String> {
|
||||
let id = arg_text(args, "id")?;
|
||||
let root = resume_root(args)?;
|
||||
ensure_dir(&root)?;
|
||||
let path = checkpoint_path(&root, id);
|
||||
let v2 = wants_checkpoint_v2(args);
|
||||
let doc = if v2 {
|
||||
build_checkpoint_v2(args, id)
|
||||
} else {
|
||||
build_legacy_doc(args, id)
|
||||
};
|
||||
atomic_write_json(&path, &doc)?;
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"id": id,
|
||||
"path": path.to_string_lossy(),
|
||||
"updated_at": doc.get("updated_at").cloned().unwrap_or(Value::Null),
|
||||
"schema": doc.get("schema").cloned().unwrap_or(Value::Null),
|
||||
"schema_version": doc.get("schema_version").cloned().unwrap_or(Value::Null),
|
||||
"updated_at": doc.get("updated_at").or_else(|| doc.get("committed_at")).cloned().unwrap_or(Value::Null),
|
||||
"atomic": true,
|
||||
}))
|
||||
}
|
||||
|
||||
fn watermark_allows_write_auto(wm: &Value) -> bool {
|
||||
match wm {
|
||||
Value::Null => false,
|
||||
Value::String(s) => !s.is_empty(),
|
||||
Value::Object(obj) => {
|
||||
// Prefer explicit safety bit from effects_watermark; bare digest objects
|
||||
// without the bit are treated as unsafe (open unknown / pending writes).
|
||||
match obj.get("write_auto_resume_safe").and_then(|v| v.as_bool()) {
|
||||
Some(b) => b,
|
||||
None => obj
|
||||
.get("watermark")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| !s.is_empty())
|
||||
.unwrap_or(false)
|
||||
&& obj.get("open_unknown").and_then(|v| v.as_u64()).unwrap_or(1) == 0
|
||||
&& obj.get("pending_writes").and_then(|v| v.as_u64()).unwrap_or(1) == 0,
|
||||
}
|
||||
}
|
||||
_ => false,
|
||||
}
|
||||
}
|
||||
|
||||
fn annotate_recovery(mut doc: Value) -> Value {
|
||||
let is_v2 = doc.get("schema").and_then(|v| v.as_str()) == Some("CheckpointV2")
|
||||
&& doc.get("schema_version").and_then(|v| v.as_u64()) == Some(2);
|
||||
let wm = doc
|
||||
.get("effect_ledger_watermark")
|
||||
.cloned()
|
||||
.unwrap_or(Value::Null);
|
||||
let ledger_safe = watermark_allows_write_auto(&wm);
|
||||
let (recovery_mode, write_auto_resume) = if is_v2 && ledger_safe {
|
||||
("checkpoint_v2", true)
|
||||
} else if is_v2 {
|
||||
// V2 without a safe ledger watermark: read resume OK; write auto-resume closed.
|
||||
("checkpoint_v2_read_only", false)
|
||||
} else {
|
||||
// Legacy: no effect info → manual_review; never auto redo writes.
|
||||
("manual_review", false)
|
||||
};
|
||||
if let Some(obj) = doc.as_object_mut() {
|
||||
obj.insert("recovery_mode".into(), json!(recovery_mode));
|
||||
obj.insert("write_auto_resume".into(), json!(write_auto_resume));
|
||||
if !is_v2 {
|
||||
obj.insert("legacy_adaptation".into(), json!("manual_review"));
|
||||
}
|
||||
}
|
||||
doc
|
||||
}
|
||||
|
||||
pub fn resume_load(args: &Value) -> Result<Value, String> {
|
||||
let id = arg_text(args, "id")?;
|
||||
let root = resume_root(args);
|
||||
let root = resume_root(args)?;
|
||||
let path = checkpoint_path(&root, id);
|
||||
if !path.is_file() {
|
||||
return Ok(json!({
|
||||
@@ -119,7 +293,31 @@ pub fn resume_load(args: &Value) -> Result<Value, String> {
|
||||
}));
|
||||
}
|
||||
let text = fs::read_to_string(&path).map_err(|e| format!("resume load: {e}"))?;
|
||||
let mut doc: Value = serde_json::from_str(&text).map_err(|e| format!("resume json: {e}"))?;
|
||||
let parsed: Value = match serde_json::from_str(&text) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
return Ok(json!({
|
||||
"ok": false,
|
||||
"found": true,
|
||||
"id": id,
|
||||
"path": path.to_string_lossy(),
|
||||
"error": {
|
||||
"schema": "AgentErrorV1",
|
||||
"schema_version": 1,
|
||||
"code": "checkpoint.corrupt",
|
||||
"category": "unknown_effect",
|
||||
"stage": "checkpoint",
|
||||
"message": format!("corrupt checkpoint json: {e}"),
|
||||
"retryable": false,
|
||||
"effect_state": "unknown",
|
||||
"recovery_action": "manual_review",
|
||||
},
|
||||
"recovery_mode": "manual_review",
|
||||
"write_auto_resume": false,
|
||||
}));
|
||||
}
|
||||
};
|
||||
let mut doc = annotate_recovery(parsed);
|
||||
if let Some(obj) = doc.as_object_mut() {
|
||||
obj.insert("ok".into(), json!(true));
|
||||
obj.insert("found".into(), json!(true));
|
||||
@@ -130,7 +328,7 @@ pub fn resume_load(args: &Value) -> Result<Value, String> {
|
||||
|
||||
pub fn resume_clear(args: &Value) -> Result<Value, String> {
|
||||
let id = arg_text(args, "id")?;
|
||||
let root = resume_root(args);
|
||||
let root = resume_root(args)?;
|
||||
let path = checkpoint_path(&root, id);
|
||||
let existed = path.is_file();
|
||||
if existed {
|
||||
@@ -145,7 +343,7 @@ pub fn resume_clear(args: &Value) -> Result<Value, String> {
|
||||
}
|
||||
|
||||
pub fn resume_list(args: &Value) -> Result<Value, String> {
|
||||
let root = resume_root(args);
|
||||
let root = resume_root(args)?;
|
||||
if !root.is_dir() {
|
||||
return Ok(json!({ "ok": true, "items": [], "resume_dir": root.to_string_lossy() }));
|
||||
}
|
||||
@@ -156,6 +354,14 @@ pub fn resume_list(args: &Value) -> Result<Value, String> {
|
||||
if p.extension().and_then(|e| e.to_str()) != Some("json") {
|
||||
continue;
|
||||
}
|
||||
// Skip leftover temp files from crashed writers.
|
||||
if p.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.map(|s| s.starts_with('.'))
|
||||
.unwrap_or(false)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
let id = p
|
||||
.file_stem()
|
||||
.and_then(|s| s.to_str())
|
||||
@@ -179,3 +385,129 @@ pub fn resume_list(args: &Value) -> Result<Value, String> {
|
||||
"resume_dir": root.to_string_lossy(),
|
||||
}))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
|
||||
fn scratch(label: &str) -> PathBuf {
|
||||
let nanos = SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos();
|
||||
let dir = std::env::temp_dir().join(format!("marqdo-resume-{label}-{nanos}"));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
dir
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn absolute_resume_dir_rejected() {
|
||||
let err = resume_root(&json!({"resume_dir": "/tmp/evil"})).unwrap_err();
|
||||
assert!(err.contains("host-relative"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn atomic_v2_roundtrip_and_legacy_manual_review() {
|
||||
let dir = scratch("v2");
|
||||
// Use relative path via env cwd — chdir into scratch for this test.
|
||||
let prev = std::env::current_dir().unwrap();
|
||||
std::env::set_current_dir(&dir).unwrap();
|
||||
let rel = "ckpts";
|
||||
let saved = resume_save(&json!({
|
||||
"id": "run1",
|
||||
"schema": "CheckpointV2",
|
||||
"schema_version": 2,
|
||||
"goal": "ping",
|
||||
"status": "running",
|
||||
"round": 1,
|
||||
"resume_dir": rel,
|
||||
"attempt_id": "a1",
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(saved["ok"], true);
|
||||
assert_eq!(saved["atomic"], true);
|
||||
assert_eq!(saved["schema"], "CheckpointV2");
|
||||
|
||||
let loaded = resume_load(&json!({"id": "run1", "resume_dir": rel})).unwrap();
|
||||
assert_eq!(loaded["found"], true);
|
||||
assert_eq!(loaded["schema"], "CheckpointV2");
|
||||
assert_eq!(loaded["recovery_mode"], "checkpoint_v2_read_only");
|
||||
assert_eq!(loaded["write_auto_resume"], false);
|
||||
|
||||
// Legacy document without schema.
|
||||
let _ = resume_save(&json!({
|
||||
"id": "legacy1",
|
||||
"goal": "pong",
|
||||
"status": "interrupted",
|
||||
"round": 2,
|
||||
"resume_dir": rel,
|
||||
}))
|
||||
.unwrap();
|
||||
let legacy = resume_load(&json!({"id": "legacy1", "resume_dir": rel})).unwrap();
|
||||
assert_eq!(legacy["recovery_mode"], "manual_review");
|
||||
assert_eq!(legacy["write_auto_resume"], false);
|
||||
assert_eq!(legacy["legacy_adaptation"], "manual_review");
|
||||
|
||||
// V2 + safe watermark → write_auto_resume opens.
|
||||
let _ = resume_save(&json!({
|
||||
"id": "run_safe",
|
||||
"schema": "CheckpointV2",
|
||||
"schema_version": 2,
|
||||
"status": "running",
|
||||
"round": 3,
|
||||
"resume_dir": rel,
|
||||
"attempt_id": "a2",
|
||||
"effect_ledger_watermark": {
|
||||
"schema": "EffectLedgerWatermarkV1",
|
||||
"watermark": "sha256-lite:abc",
|
||||
"write_auto_resume_safe": true,
|
||||
"open_unknown": 0,
|
||||
"pending_writes": 0
|
||||
}
|
||||
}))
|
||||
.unwrap();
|
||||
let safe = resume_load(&json!({"id": "run_safe", "resume_dir": rel})).unwrap();
|
||||
assert_eq!(safe["recovery_mode"], "checkpoint_v2");
|
||||
assert_eq!(safe["write_auto_resume"], true);
|
||||
|
||||
// Unsafe watermark (open unknown) keeps write auto-resume closed.
|
||||
let _ = resume_save(&json!({
|
||||
"id": "run_unsafe",
|
||||
"schema": "CheckpointV2",
|
||||
"schema_version": 2,
|
||||
"status": "running",
|
||||
"round": 4,
|
||||
"resume_dir": rel,
|
||||
"attempt_id": "a3",
|
||||
"effect_ledger_watermark": {
|
||||
"watermark": "sha256-lite:def",
|
||||
"write_auto_resume_safe": false,
|
||||
"open_unknown": 1
|
||||
}
|
||||
}))
|
||||
.unwrap();
|
||||
let unsafe_ck = resume_load(&json!({"id": "run_unsafe", "resume_dir": rel})).unwrap();
|
||||
assert_eq!(unsafe_ck["recovery_mode"], "checkpoint_v2_read_only");
|
||||
assert_eq!(unsafe_ck["write_auto_resume"], false);
|
||||
|
||||
std::env::set_current_dir(prev).unwrap();
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corrupt_checkpoint_reports_error() {
|
||||
let dir = scratch("corrupt");
|
||||
let prev = std::env::current_dir().unwrap();
|
||||
std::env::set_current_dir(&dir).unwrap();
|
||||
fs::create_dir_all("ckpts").unwrap();
|
||||
fs::write("ckpts/bad.json", "{not-json").unwrap();
|
||||
let loaded = resume_load(&json!({"id": "bad", "resume_dir": "ckpts"})).unwrap();
|
||||
assert_eq!(loaded["found"], true);
|
||||
assert_eq!(loaded["ok"], false);
|
||||
assert_eq!(loaded["error"]["code"], "checkpoint.corrupt");
|
||||
assert_eq!(loaded["recovery_mode"], "manual_review");
|
||||
std::env::set_current_dir(prev).unwrap();
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,794 @@
|
||||
//! ToolSpecV1 registry + call validation (M-A2).
|
||||
//! Discovery → schema validate → authorize. Execution of Marqdo `##` stays in subtask;
|
||||
//! this module never evals model-supplied code.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::sync::{Mutex, OnceLock};
|
||||
|
||||
use serde_json::{json, Map, Value};
|
||||
|
||||
fn registry() -> &'static Mutex<HashMap<String, Value>> {
|
||||
static REG: OnceLock<Mutex<HashMap<String, Value>>> = OnceLock::new();
|
||||
REG.get_or_init(|| Mutex::new(HashMap::new()))
|
||||
}
|
||||
|
||||
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
|
||||
args.get(key)
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
}
|
||||
|
||||
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
|
||||
opt_text(args, key).ok_or_else(|| format!("missing text `{key}`"))
|
||||
}
|
||||
|
||||
/// Supported JSON Schema subset for tool input (reject unsupported constructs).
|
||||
fn validate_schema_subset(schema: &Value) -> Result<(), String> {
|
||||
let obj = schema
|
||||
.as_object()
|
||||
.ok_or_else(|| "input_schema must be object".to_string())?;
|
||||
let ty = obj
|
||||
.get("type")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("object");
|
||||
if ty != "object" {
|
||||
return Err(format!("unsupported root type={ty}; only object"));
|
||||
}
|
||||
if let Some(props) = obj.get("properties") {
|
||||
let props = props
|
||||
.as_object()
|
||||
.ok_or_else(|| "properties must be object".to_string())?;
|
||||
for (name, prop) in props {
|
||||
let p = prop
|
||||
.as_object()
|
||||
.ok_or_else(|| format!("property {name} must be object"))?;
|
||||
let pty = p.get("type").and_then(|v| v.as_str()).unwrap_or("string");
|
||||
match pty {
|
||||
"string" | "integer" | "number" | "boolean" | "array" | "object" => {}
|
||||
other => {
|
||||
return Err(format!(
|
||||
"unsupported property type {other} for {name}; refuse register"
|
||||
))
|
||||
}
|
||||
}
|
||||
// Reject constructs we do not implement.
|
||||
for banned in ["$ref", "oneOf", "anyOf", "allOf", "not", "if", "then", "else"] {
|
||||
if p.contains_key(banned) {
|
||||
return Err(format!(
|
||||
"unsupported schema keyword {banned} on {name}; refuse register"
|
||||
));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
for banned in ["$ref", "oneOf", "anyOf", "allOf", "not", "if", "then", "else"] {
|
||||
if obj.contains_key(banned) {
|
||||
return Err(format!(
|
||||
"unsupported schema keyword {banned}; refuse register"
|
||||
));
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn normalize_spec(mut spec: Value) -> Result<Value, String> {
|
||||
let obj = spec
|
||||
.as_object_mut()
|
||||
.ok_or_else(|| "spec must be object".to_string())?;
|
||||
obj.insert("schema".into(), json!("ToolSpecV1"));
|
||||
obj.entry("schema_version".to_string())
|
||||
.or_insert(json!(1));
|
||||
let id = obj
|
||||
.get("id")
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.ok_or_else(|| "ToolSpecV1 requires id".to_string())?
|
||||
.to_string();
|
||||
obj.entry("version".to_string()).or_insert(json!("1"));
|
||||
obj.entry("description".to_string())
|
||||
.or_insert(json!(""));
|
||||
let input = obj
|
||||
.get("input_schema")
|
||||
.cloned()
|
||||
.unwrap_or_else(|| json!({"type": "object", "properties": {}, "additionalProperties": false}));
|
||||
validate_schema_subset(&input)?;
|
||||
obj.insert("input_schema".into(), input);
|
||||
obj.entry("effect".to_string()).or_insert(json!("read"));
|
||||
let effect = obj.get("effect").and_then(|v| v.as_str()).unwrap_or("read");
|
||||
if !matches!(effect, "read" | "write" | "execute" | "external_write") {
|
||||
return Err(format!("invalid effect={effect}"));
|
||||
}
|
||||
obj.entry("scopes".to_string()).or_insert(json!([]));
|
||||
obj.entry("timeout_ms".to_string()).or_insert(json!(10_000));
|
||||
obj.entry("max_result_bytes".to_string())
|
||||
.or_insert(json!(65_536));
|
||||
obj.entry("idempotency".to_string())
|
||||
.or_insert(json!("safe"));
|
||||
obj.entry("availability".to_string())
|
||||
.or_insert(json!("ready"));
|
||||
let _ = id;
|
||||
Ok(spec)
|
||||
}
|
||||
|
||||
fn validate_args_against_schema(schema: &Value, arguments: &Value) -> Result<(), String> {
|
||||
let args = arguments
|
||||
.as_object()
|
||||
.ok_or_else(|| "arguments must be object".to_string())?;
|
||||
let sch = schema.as_object().ok_or_else(|| "input_schema invalid".to_string())?;
|
||||
let props = sch
|
||||
.get("properties")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let additional = sch
|
||||
.get("additionalProperties")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(true);
|
||||
if !additional {
|
||||
for key in args.keys() {
|
||||
if !props.contains_key(key) {
|
||||
return Err(format!("unknown argument `{key}`"));
|
||||
}
|
||||
}
|
||||
}
|
||||
if let Some(req) = sch.get("required").and_then(|v| v.as_array()) {
|
||||
for r in req {
|
||||
let name = r.as_str().unwrap_or("");
|
||||
if name.is_empty() {
|
||||
continue;
|
||||
}
|
||||
if !args.contains_key(name) || args.get(name).map(|v| v.is_null()).unwrap_or(true) {
|
||||
return Err(format!("missing required argument `{name}`"));
|
||||
}
|
||||
}
|
||||
}
|
||||
for (key, val) in args {
|
||||
if let Some(prop) = props.get(key) {
|
||||
if let Some(pty) = prop.get("type").and_then(|v| v.as_str()) {
|
||||
let ok = match pty {
|
||||
"string" => val.is_string(),
|
||||
"integer" => val.as_i64().is_some() || val.as_u64().is_some(),
|
||||
"number" => val.as_f64().is_some(),
|
||||
"boolean" => val.is_boolean(),
|
||||
"array" => val.is_array(),
|
||||
"object" => val.is_object(),
|
||||
_ => true,
|
||||
};
|
||||
if !ok {
|
||||
return Err(format!("argument `{key}` type mismatch (want {pty})"));
|
||||
}
|
||||
}
|
||||
if let Some(min) = prop.get("minimum").and_then(|v| v.as_f64()) {
|
||||
if let Some(n) = val.as_f64() {
|
||||
if n < min {
|
||||
return Err(format!("argument `{key}` below minimum {min}"));
|
||||
}
|
||||
}
|
||||
}
|
||||
if let Some(max) = prop.get("maximum").and_then(|v| v.as_f64()) {
|
||||
if let Some(n) = val.as_f64() {
|
||||
if n > max {
|
||||
return Err(format!("argument `{key}` above maximum {max}"));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn authorized(allowlist: Option<&Value>, tool_id: &str) -> bool {
|
||||
match allowlist {
|
||||
None => true, // registry-only call sites may omit; still need registered spec
|
||||
Some(tools) => crate::tool_names(tools).iter().any(|n| n == tool_id),
|
||||
}
|
||||
}
|
||||
|
||||
/// Register one ToolSpecV1 (or list). Host/trusted only — model cannot invent principal/root.
|
||||
pub fn tools_register(args: &Value) -> Result<Value, String> {
|
||||
let specs = if let Some(arr) = args.get("specs").and_then(|v| v.as_array()) {
|
||||
arr.clone()
|
||||
} else if args.get("spec").is_some() || args.get("id").is_some() {
|
||||
let raw = args.get("spec").cloned().unwrap_or_else(|| args.clone());
|
||||
vec![raw]
|
||||
} else {
|
||||
return Err("tools.register requires spec or specs[]".into());
|
||||
};
|
||||
let mut registered = Vec::new();
|
||||
let mut guard = registry()
|
||||
.lock()
|
||||
.map_err(|_| "tools registry lock poisoned".to_string())?;
|
||||
for raw in specs {
|
||||
let spec = normalize_spec(raw)?;
|
||||
let id = spec
|
||||
.get("id")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap()
|
||||
.to_string();
|
||||
guard.insert(id.clone(), spec);
|
||||
registered.push(id);
|
||||
}
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"registered": registered,
|
||||
"count": registered.len(),
|
||||
}))
|
||||
}
|
||||
|
||||
pub fn tools_clear(args: &Value) -> Result<Value, String> {
|
||||
let _ = args;
|
||||
let mut guard = registry()
|
||||
.lock()
|
||||
.map_err(|_| "tools registry lock poisoned".to_string())?;
|
||||
let n = guard.len();
|
||||
guard.clear();
|
||||
Ok(json!({"ok": true, "cleared": n}))
|
||||
}
|
||||
|
||||
pub fn tools_search(args: &Value) -> Result<Value, String> {
|
||||
let query = opt_text(args, "query").unwrap_or("").to_ascii_lowercase();
|
||||
let allow = args.get("tools");
|
||||
let guard = registry()
|
||||
.lock()
|
||||
.map_err(|_| "tools registry lock poisoned".to_string())?;
|
||||
let mut items = Vec::new();
|
||||
for (id, spec) in guard.iter() {
|
||||
let avail = spec
|
||||
.get("availability")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("ready");
|
||||
let auth = authorized(allow, id);
|
||||
if !auth {
|
||||
// Do not leak unauthorized private connector names in search hits.
|
||||
continue;
|
||||
}
|
||||
if !query.is_empty() {
|
||||
let desc = spec
|
||||
.get("description")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("");
|
||||
if !id.to_ascii_lowercase().contains(&query)
|
||||
&& !desc.to_ascii_lowercase().contains(&query)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
}
|
||||
items.push(json!({
|
||||
"id": id,
|
||||
"version": spec.get("version").cloned().unwrap_or(json!("1")),
|
||||
"description": spec.get("description").cloned().unwrap_or(json!("")),
|
||||
"effect": spec.get("effect").cloned().unwrap_or(json!("read")),
|
||||
"availability": avail,
|
||||
"authorized": true,
|
||||
}));
|
||||
}
|
||||
items.sort_by(|a, b| {
|
||||
let ai = a.get("id").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let bi = b.get("id").and_then(|v| v.as_str()).unwrap_or("");
|
||||
ai.cmp(bi)
|
||||
});
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"schema": "ToolSearchResultV1",
|
||||
"schema_version": 1,
|
||||
"items": items,
|
||||
"count": items.len(),
|
||||
}))
|
||||
}
|
||||
|
||||
pub fn tools_describe(args: &Value) -> Result<Value, String> {
|
||||
let id = arg_text(args, "id")?;
|
||||
let allow = args.get("tools");
|
||||
if !authorized(allow, id) {
|
||||
return Ok(json!({
|
||||
"ok": false,
|
||||
"found": false,
|
||||
"authorized": false,
|
||||
"error": {
|
||||
"schema": "AgentErrorV1",
|
||||
"schema_version": 1,
|
||||
"code": "tool.forbidden",
|
||||
"category": "forbidden",
|
||||
"stage": "tool",
|
||||
"message": format!("tool `{id}` not in allowlist"),
|
||||
"retryable": false,
|
||||
"effect_state": "none",
|
||||
"recovery_action": "needs_input",
|
||||
}
|
||||
}));
|
||||
}
|
||||
let guard = registry()
|
||||
.lock()
|
||||
.map_err(|_| "tools registry lock poisoned".to_string())?;
|
||||
match guard.get(id) {
|
||||
Some(spec) => Ok(json!({
|
||||
"ok": true,
|
||||
"found": true,
|
||||
"authorized": true,
|
||||
"spec": spec,
|
||||
})),
|
||||
None => Ok(json!({
|
||||
"ok": false,
|
||||
"found": false,
|
||||
"authorized": true,
|
||||
"error": {
|
||||
"schema": "AgentErrorV1",
|
||||
"schema_version": 1,
|
||||
"code": "tool.not_found",
|
||||
"category": "capability_unavailable",
|
||||
"stage": "tool",
|
||||
"message": format!("tool `{id}` not registered"),
|
||||
"retryable": false,
|
||||
"effect_state": "none",
|
||||
"recovery_action": "stop",
|
||||
}
|
||||
})),
|
||||
}
|
||||
}
|
||||
|
||||
/// Validate + authorize a ToolCallV1. Does not execute side effects.
|
||||
pub fn tools_prepare_call(args: &Value) -> Result<Value, String> {
|
||||
let tool_id = arg_text(args, "tool_id")
|
||||
.or_else(|_| arg_text(args, "id"))
|
||||
.or_else(|_| arg_text(args, "name"))?;
|
||||
let allow = args.get("tools");
|
||||
if !authorized(allow, tool_id) {
|
||||
return Ok(tool_result_err(
|
||||
"tool.forbidden",
|
||||
"forbidden",
|
||||
format!("unauthorized call to `{tool_id}`"),
|
||||
false,
|
||||
));
|
||||
}
|
||||
let guard = registry()
|
||||
.lock()
|
||||
.map_err(|_| "tools registry lock poisoned".to_string())?;
|
||||
let spec = match guard.get(tool_id) {
|
||||
Some(s) => s.clone(),
|
||||
None => {
|
||||
return Ok(tool_result_err(
|
||||
"tool.not_found",
|
||||
"capability_unavailable",
|
||||
format!("tool `{tool_id}` not registered"),
|
||||
false,
|
||||
));
|
||||
}
|
||||
};
|
||||
drop(guard);
|
||||
|
||||
let avail = spec
|
||||
.get("availability")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("ready");
|
||||
if avail != "ready" {
|
||||
return Ok(tool_result_err(
|
||||
"tool.unavailable",
|
||||
"capability_unavailable",
|
||||
format!("tool `{tool_id}` availability={avail}"),
|
||||
false,
|
||||
));
|
||||
}
|
||||
|
||||
let arguments = match args.get("arguments") {
|
||||
None | Some(Value::Null) => json!({}),
|
||||
Some(v) => v.clone(),
|
||||
};
|
||||
let schema = spec
|
||||
.get("input_schema")
|
||||
.cloned()
|
||||
.unwrap_or_else(|| json!({"type":"object"}));
|
||||
if let Err(e) = validate_args_against_schema(&schema, &arguments) {
|
||||
return Ok(tool_result_err(
|
||||
"tool.invalid_arguments",
|
||||
"invalid_arguments",
|
||||
e,
|
||||
true,
|
||||
));
|
||||
}
|
||||
|
||||
let call_id = opt_text(args, "call_id")
|
||||
.map(|s| s.to_string())
|
||||
.unwrap_or_else(|| format!("call_{}", std::process::id()));
|
||||
let operation_id = opt_text(args, "operation_id")
|
||||
.map(|s| s.to_string())
|
||||
.unwrap_or_else(|| format!("op_{tool_id}_{call_id}"));
|
||||
let version = spec
|
||||
.get("version")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("1");
|
||||
let effect = spec
|
||||
.get("effect")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("read");
|
||||
let digest = args_digest(&arguments);
|
||||
let logical_run = opt_text(args, "logical_run_id").unwrap_or("-");
|
||||
let step = opt_text(args, "step_id").unwrap_or("-");
|
||||
let idempotency_key = opt_text(args, "idempotency_key")
|
||||
.map(|s| s.to_string())
|
||||
.unwrap_or_else(|| format!("{logical_run}|{step}|{tool_id}|{digest}"));
|
||||
let needs_ledger = matches!(effect, "write" | "execute" | "external_write");
|
||||
|
||||
let call = json!({
|
||||
"schema": "ToolCallV1",
|
||||
"schema_version": 1,
|
||||
"call_id": call_id,
|
||||
"tool_id": tool_id,
|
||||
"tool_version": version,
|
||||
"arguments": arguments,
|
||||
"operation_id": operation_id,
|
||||
"parent_span_id": args.get("parent_span_id").cloned().unwrap_or(Value::Null),
|
||||
});
|
||||
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"status": "prepared",
|
||||
"call": call,
|
||||
"spec": {
|
||||
"id": tool_id,
|
||||
"effect": effect,
|
||||
"timeout_ms": spec.get("timeout_ms").cloned().unwrap_or(json!(10000)),
|
||||
"max_result_bytes": spec.get("max_result_bytes").cloned().unwrap_or(json!(65536)),
|
||||
},
|
||||
"args_digest": digest,
|
||||
"idempotency_key": idempotency_key,
|
||||
"needs_ledger": needs_ledger,
|
||||
"summary": format!("prepared authorized call to `{tool_id}`"),
|
||||
}))
|
||||
}
|
||||
|
||||
/// Stable digest of tool arguments for effect ledger idempotency (M-A5a).
|
||||
pub fn tools_args_digest(args: &Value) -> Result<Value, String> {
|
||||
let arguments = args
|
||||
.get("arguments")
|
||||
.cloned()
|
||||
.or_else(|| args.get("value").cloned())
|
||||
.unwrap_or_else(|| json!({}));
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"args_digest": args_digest(&arguments),
|
||||
}))
|
||||
}
|
||||
|
||||
fn args_digest(arguments: &Value) -> String {
|
||||
let text = serde_json::to_string(arguments).unwrap_or_else(|_| "{}".into());
|
||||
format!("sha256-lite:{:x}", fnv1a64(&text))
|
||||
}
|
||||
|
||||
fn fnv1a64(s: &str) -> u64 {
|
||||
let mut h: u64 = 0xcbf29ce484222325;
|
||||
for b in s.as_bytes() {
|
||||
h ^= u64::from(*b);
|
||||
h = h.wrapping_mul(0x100000001b3);
|
||||
}
|
||||
h
|
||||
}
|
||||
|
||||
/// True when effect_class requires EffectLedger before/after execution.
|
||||
pub fn tools_needs_ledger(args: &Value) -> Result<Value, String> {
|
||||
let effect = opt_text(args, "effect")
|
||||
.or_else(|| opt_text(args, "effect_class"))
|
||||
.unwrap_or("read");
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"needs_ledger": matches!(effect, "write" | "execute" | "external_write"),
|
||||
"effect": effect,
|
||||
}))
|
||||
}
|
||||
|
||||
/// Wrap a successful / failed tool execution into ToolResultV1.
|
||||
pub fn tools_wrap_result(args: &Value) -> Result<Value, String> {
|
||||
let ok = args.get("ok").and_then(|v| v.as_bool()).unwrap_or(false);
|
||||
let status = opt_text(args, "status").unwrap_or(if ok { "succeeded" } else { "failed" });
|
||||
let summary = opt_text(args, "summary").unwrap_or("");
|
||||
let mut out = json!({
|
||||
"schema": "ToolResultV1",
|
||||
"schema_version": 1,
|
||||
"ok": ok,
|
||||
"status": status,
|
||||
"summary": summary,
|
||||
"structured_content": args.get("structured_content").cloned().unwrap_or(Value::Null),
|
||||
"resources": args.get("resources").cloned().unwrap_or_else(|| json!([])),
|
||||
"citations": args.get("citations").cloned().unwrap_or_else(|| json!([])),
|
||||
"error": args.get("error").cloned().unwrap_or(Value::Null),
|
||||
"usage": args.get("usage").cloned().unwrap_or(Value::Null),
|
||||
"truncated": args.get("truncated").and_then(|v| v.as_bool()).unwrap_or(false),
|
||||
"next_cursor": args.get("next_cursor").cloned().unwrap_or(Value::Null),
|
||||
"effect_receipt_ref": args.get("effect_receipt_ref").cloned().unwrap_or(Value::Null),
|
||||
});
|
||||
// Truncate oversized summary into artifact hint (do not dump MB into prompt).
|
||||
let max_bytes = args
|
||||
.get("max_result_bytes")
|
||||
.and_then(|v| v.as_u64())
|
||||
.unwrap_or(65_536) as usize;
|
||||
if summary.len() > max_bytes {
|
||||
if let Some(obj) = out.as_object_mut() {
|
||||
obj.insert("truncated".into(), json!(true));
|
||||
obj.insert(
|
||||
"summary".into(),
|
||||
json!(format!(
|
||||
"{}… [truncated; use resource handle]",
|
||||
&summary[..max_bytes.min(summary.len())]
|
||||
)),
|
||||
);
|
||||
}
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Seed the five engineering tools used by qdagent (aliases remain CALL:tool_*).
|
||||
pub fn tools_register_eng_defaults(args: &Value) -> Result<Value, String> {
|
||||
let _ = args;
|
||||
let specs = eng_default_specs();
|
||||
tools_register(&json!({"specs": specs}))
|
||||
}
|
||||
|
||||
fn eng_default_specs() -> Vec<Value> {
|
||||
vec![
|
||||
json!({
|
||||
"id": "tool_find",
|
||||
"version": "1",
|
||||
"description": "Engineering find via EKC (read-only)",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {"query": {"type": "string"}},
|
||||
"required": ["query"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"effect": "read",
|
||||
"scopes": ["knowledge:read"],
|
||||
"availability": "ready"
|
||||
}),
|
||||
json!({
|
||||
"id": "tool_reuse",
|
||||
"version": "1",
|
||||
"description": "Engineering reuse / preflight discovery (read-only)",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {"task": {"type": "string"}},
|
||||
"required": ["task"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"effect": "read",
|
||||
"scopes": ["knowledge:read"],
|
||||
"availability": "ready"
|
||||
}),
|
||||
json!({
|
||||
"id": "tool_bind",
|
||||
"version": "1",
|
||||
"description": "Bind and execute a verified knowledge artifact",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {"type": "string"},
|
||||
"policy": {"type": "string"},
|
||||
"project": {"type": "string"}
|
||||
},
|
||||
"required": ["query"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"effect": "execute",
|
||||
"scopes": ["knowledge:execute"],
|
||||
"availability": "ready"
|
||||
}),
|
||||
json!({
|
||||
"id": "tool_verify",
|
||||
"version": "1",
|
||||
"description": "Run L3 knowledge verification checks",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"effect": "read",
|
||||
"scopes": ["knowledge:verify"],
|
||||
"availability": "ready"
|
||||
}),
|
||||
json!({
|
||||
"id": "tool_summarize",
|
||||
"version": "1",
|
||||
"description": "Summarize a Context Pack / preflight map",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {"preflight": {"type": "object"}},
|
||||
"required": ["preflight"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"effect": "read",
|
||||
"scopes": ["knowledge:read"],
|
||||
"availability": "ready"
|
||||
}),
|
||||
]
|
||||
}
|
||||
|
||||
fn tool_result_err(code: &str, category: &str, message: String, retryable: bool) -> Value {
|
||||
let recovery = if category == "invalid_arguments" {
|
||||
"repair_args"
|
||||
} else if category == "forbidden" {
|
||||
"needs_input"
|
||||
} else {
|
||||
"stop"
|
||||
};
|
||||
json!({
|
||||
"ok": false,
|
||||
"status": "failed",
|
||||
"summary": message,
|
||||
"schema": "ToolResultV1",
|
||||
"schema_version": 1,
|
||||
"structured_content": null,
|
||||
"resources": [],
|
||||
"citations": [],
|
||||
"error": {
|
||||
"schema": "AgentErrorV1",
|
||||
"schema_version": 1,
|
||||
"code": code,
|
||||
"category": category,
|
||||
"stage": "tool",
|
||||
"message": message,
|
||||
"retryable": retryable,
|
||||
"retry_after_ms": null,
|
||||
"effect_state": "none",
|
||||
"recovery_action": recovery,
|
||||
},
|
||||
"usage": null,
|
||||
"truncated": false,
|
||||
"next_cursor": null,
|
||||
"effect_receipt_ref": null,
|
||||
})
|
||||
}
|
||||
|
||||
/// Seed stub specs from a CALL allowlist (args.tools).
|
||||
pub fn seed_from_allowlist_args(args: &Value) -> Result<Value, String> {
|
||||
let tools = args
|
||||
.get("tools")
|
||||
.ok_or_else(|| "tools.seed_allowlist requires tools".to_string())?;
|
||||
seed_from_allowlist(tools)
|
||||
}
|
||||
|
||||
fn seed_from_allowlist(tools: &Value) -> Result<Value, String> {
|
||||
let names = crate::tool_names(tools);
|
||||
let mut specs = Vec::new();
|
||||
for name in names {
|
||||
// Minimal stub if not already registered — CALL whitelist compatibility.
|
||||
let already = {
|
||||
let guard = registry()
|
||||
.lock()
|
||||
.map_err(|_| "tools registry lock poisoned".to_string())?;
|
||||
guard.contains_key(&name)
|
||||
};
|
||||
if already {
|
||||
continue;
|
||||
}
|
||||
let mut m = Map::new();
|
||||
m.insert("id".into(), json!(name));
|
||||
m.insert("version".into(), json!("1"));
|
||||
m.insert(
|
||||
"description".into(),
|
||||
json!(format!("Allowlist-derived tool `{name}`")),
|
||||
);
|
||||
m.insert(
|
||||
"input_schema".into(),
|
||||
json!({"type":"object","properties":{},"additionalProperties":true}),
|
||||
);
|
||||
m.insert("effect".into(), json!("execute"));
|
||||
m.insert("scopes".into(), json!(["call:allowlist"]));
|
||||
m.insert("availability".into(), json!("ready"));
|
||||
specs.push(Value::Object(m));
|
||||
}
|
||||
if specs.is_empty() {
|
||||
return Ok(json!({"ok": true, "registered": [], "count": 0}));
|
||||
}
|
||||
tools_register(&json!({"specs": specs}))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn register_search_describe_and_forbid() {
|
||||
let _ = tools_clear(&json!({}));
|
||||
let reg = tools_register_eng_defaults(&json!({})).unwrap();
|
||||
assert_eq!(reg["count"], 5);
|
||||
|
||||
let allow = json!(["tool_find", "tool_reuse"]);
|
||||
let search = tools_search(&json!({"tools": allow, "query": "find"})).unwrap();
|
||||
assert_eq!(search["count"], 1);
|
||||
assert_eq!(search["items"][0]["id"], "tool_find");
|
||||
|
||||
// Unauthorized tool must not appear.
|
||||
let search2 = tools_search(&json!({"tools": allow, "query": "bind"})).unwrap();
|
||||
assert_eq!(search2["count"], 0);
|
||||
|
||||
let denied = tools_describe(&json!({"id": "tool_bind", "tools": allow})).unwrap();
|
||||
assert_eq!(denied["authorized"], false);
|
||||
assert_eq!(denied["ok"], false);
|
||||
|
||||
let ok = tools_describe(&json!({"id": "tool_find", "tools": allow})).unwrap();
|
||||
assert_eq!(ok["found"], true);
|
||||
assert_eq!(ok["spec"]["schema"], "ToolSpecV1");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prepare_rejects_bad_args_and_unauthorized() {
|
||||
let _ = tools_clear(&json!({}));
|
||||
tools_register_eng_defaults(&json!({})).unwrap();
|
||||
let allow = json!(["tool_find"]);
|
||||
|
||||
let bad = tools_prepare_call(&json!({
|
||||
"tool_id": "tool_find",
|
||||
"tools": allow,
|
||||
"arguments": {}
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(bad["ok"], false);
|
||||
assert_eq!(bad["error"]["category"], "invalid_arguments");
|
||||
|
||||
let unauth = tools_prepare_call(&json!({
|
||||
"tool_id": "tool_bind",
|
||||
"tools": allow,
|
||||
"arguments": {"query": "x"}
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(unauth["ok"], false);
|
||||
assert_eq!(unauth["error"]["category"], "forbidden");
|
||||
|
||||
let good = tools_prepare_call(&json!({
|
||||
"tool_id": "tool_find",
|
||||
"tools": allow,
|
||||
"arguments": {"query": "foo"},
|
||||
"call_id": "c1"
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(good["ok"], true);
|
||||
assert_eq!(good["call"]["schema"], "ToolCallV1");
|
||||
assert_eq!(good["call"]["tool_id"], "tool_find");
|
||||
assert_eq!(good["needs_ledger"], false);
|
||||
assert!(good["args_digest"].as_str().unwrap().starts_with("sha256-lite:"));
|
||||
|
||||
let allow2 = json!(["tool_bind"]);
|
||||
let bind = tools_prepare_call(&json!({
|
||||
"tool_id": "tool_bind",
|
||||
"tools": allow2,
|
||||
"arguments": {"query": "x"},
|
||||
"call_id": "c2",
|
||||
"logical_run_id": "run1",
|
||||
"step_id": "s1"
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(bind["ok"], true);
|
||||
assert_eq!(bind["needs_ledger"], true);
|
||||
assert_eq!(bind["spec"]["effect"], "execute");
|
||||
assert!(bind["idempotency_key"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.starts_with("run1|s1|tool_bind|"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn needs_ledger_only_for_mutating_effects() {
|
||||
assert_eq!(
|
||||
tools_needs_ledger(&json!({"effect": "read"})).unwrap()["needs_ledger"],
|
||||
false
|
||||
);
|
||||
assert_eq!(
|
||||
tools_needs_ledger(&json!({"effect": "write"})).unwrap()["needs_ledger"],
|
||||
true
|
||||
);
|
||||
assert_eq!(
|
||||
tools_needs_ledger(&json!({"effect": "execute"})).unwrap()["needs_ledger"],
|
||||
true
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refuse_unsupported_schema_keywords() {
|
||||
let err = tools_register(&json!({
|
||||
"id": "bad",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"oneOf": [{"type": "object"}]
|
||||
}
|
||||
}));
|
||||
assert!(err.is_err());
|
||||
}
|
||||
}
|
||||
@@ -211,6 +211,10 @@ fn parse_sse_events(
|
||||
{
|
||||
accumulated.push_str(c);
|
||||
}
|
||||
// Preserve provider usage as a first-class event for llm.collect_usage.
|
||||
if let Some(u) = v.get("usage").filter(|u| u.is_object()) {
|
||||
events.push(json!({"type": "usage", "usage": u}));
|
||||
}
|
||||
}
|
||||
events.push(json!({"type": "data", "data": data}));
|
||||
}
|
||||
@@ -365,6 +369,11 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
}
|
||||
if stream {
|
||||
req_body.insert("stream".into(), Value::Bool(true));
|
||||
// OpenAI / DeepSeek / compatible: final SSE chunk carries usage only when requested.
|
||||
req_body.insert(
|
||||
"stream_options".into(),
|
||||
json!({ "include_usage": true }),
|
||||
);
|
||||
}
|
||||
let body = Value::Object(req_body).to_string();
|
||||
let auth = format!("{bearer}{api_key}");
|
||||
|
||||
@@ -38,6 +38,7 @@ type invokeRoute struct {
|
||||
BodyMode string
|
||||
ReturnMode string
|
||||
Class string
|
||||
Path string
|
||||
}
|
||||
|
||||
func parseInvokeRoute(v any) invokeRoute {
|
||||
@@ -66,6 +67,7 @@ func (st *state) mountInvokeRoutes(mux *http.ServeMux) {
|
||||
for _, key := range sortedKeys(st.invokeRoutes) {
|
||||
cfg := parseInvokeRoute(st.invokeRoutes[key])
|
||||
path := routePathKey(key)
|
||||
cfg.Path = path
|
||||
method := cfg.Method
|
||||
if method == "" {
|
||||
method = http.MethodPost
|
||||
@@ -140,6 +142,25 @@ func (st *state) handleInvoke(w http.ResponseWriter, r *http.Request, route invo
|
||||
payload["api_key"] = key
|
||||
}
|
||||
}
|
||||
if last := strings.TrimSpace(r.Header.Get("Last-Event-ID")); last != "" {
|
||||
if _, exists := payload["last_event_id"]; !exists {
|
||||
payload["last_event_id"] = last
|
||||
}
|
||||
}
|
||||
// Merge Go ServeMux path wildcards (e.g. /turns/{id}/events → id / turn_id).
|
||||
if route.Path != "" {
|
||||
pathVals := pathValuesOf(r, route.Path)
|
||||
for k, v := range pathVals {
|
||||
if _, exists := payload[k]; !exists {
|
||||
payload[k] = v
|
||||
}
|
||||
}
|
||||
if id, ok := pathVals["id"]; ok {
|
||||
if _, exists := payload["turn_id"]; !exists {
|
||||
payload["turn_id"] = id
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
args := invokeArgsFromPayload(payload)
|
||||
|
||||
@@ -151,9 +172,14 @@ func (st *state) handleInvoke(w http.ResponseWriter, r *http.Request, route invo
|
||||
class := resolveInvokeClass(route, liveSSE)
|
||||
switch class {
|
||||
case "execute":
|
||||
st.handleInvokeIsolated(w, r, route, args, liveSSE)
|
||||
// Isolated workers: do not take parent INVOKE_LOCK (ADR 0009).
|
||||
st.handleInvokeIsolated(w, r, route, args, liveSSE, class)
|
||||
return
|
||||
case "short", "read", "control":
|
||||
// Stay on parent: execute already runs off-process, so parent lock is free.
|
||||
// Putting short/read/control on the 2-slot execute worker pool caused
|
||||
// systemic no_slot (and zombies held slots after observer disconnect).
|
||||
// Product cancel/events prefer /_runtime/* (lock-free).
|
||||
st.handleInvokeParent(w, r, route, args)
|
||||
return
|
||||
default:
|
||||
@@ -243,14 +269,17 @@ func (st *state) handleInvokeParent(w http.ResponseWriter, r *http.Request, rout
|
||||
}
|
||||
}
|
||||
|
||||
// handleInvokeIsolated runs execute-class invokes on a Supervisor worker (no
|
||||
// parent CallLibPath, no process Setenv, no legacySSEBridgeMu).
|
||||
func (st *state) handleInvokeIsolated(w http.ResponseWriter, r *http.Request, route invokeRoute, args map[string]any, liveSSE bool) {
|
||||
// handleInvokeIsolated runs admits on a Supervisor worker (no parent
|
||||
// CallLibPath / Setenv / legacySSEBridgeMu). admissionClass is execute|short|read|control.
|
||||
func (st *state) handleInvokeIsolated(w http.ResponseWriter, r *http.Request, route invokeRoute, args map[string]any, liveSSE bool, admissionClass string) {
|
||||
if admissionClass == "" {
|
||||
admissionClass = "execute"
|
||||
}
|
||||
taskID := fmt.Sprintf("exec_%d", time.Now().UnixNano())
|
||||
adm, err := runtimeQuery("admit", map[string]any{
|
||||
"task_id": taskID,
|
||||
"idempotency_key": taskID,
|
||||
"class": "execute",
|
||||
"class": admissionClass,
|
||||
"payload": map[string]any{"fn": route.FnPath},
|
||||
})
|
||||
if err != nil {
|
||||
@@ -324,6 +353,14 @@ func (st *state) handleInvokeIsolated(w http.ResponseWriter, r *http.Request, ro
|
||||
st.waitIsolatedJSON(w, r, route, taskID, eventPath, cancelTok, emitResult)
|
||||
}
|
||||
|
||||
// cancelOnDisconnect reports whether the client opted into legacy
|
||||
// disconnect=cancel (header X-Marqdo-Cancel-On-Disconnect: 1|true).
|
||||
// Default is false: subscription close must not cancel the task (ADR 0009 / design §7.2).
|
||||
func cancelOnDisconnect(r *http.Request) bool {
|
||||
v := strings.TrimSpace(strings.ToLower(r.Header.Get("X-Marqdo-Cancel-On-Disconnect")))
|
||||
return v == "1" || v == "true" || v == "yes"
|
||||
}
|
||||
|
||||
func (st *state) streamIsolatedSSE(w http.ResponseWriter, r *http.Request, route invokeRoute, taskID, eventPath, cancelTok, emitResult string) {
|
||||
w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
|
||||
w.Header().Set("Cache-Control", "no-cache")
|
||||
@@ -384,27 +421,46 @@ func (st *state) streamIsolatedSSE(w http.ResponseWriter, r *http.Request, route
|
||||
}
|
||||
}
|
||||
|
||||
doCancelOnDisconnect := cancelOnDisconnect(r)
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
_, _ = runtimeQuery("cancel", map[string]any{"task_id": taskID})
|
||||
_ = writeCancelToken(cancelTok)
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.interrupted",
|
||||
"payload": map[string]any{
|
||||
"reason": "client_disconnect",
|
||||
"cancel_propagated": cancelTok != "",
|
||||
"status": "stopping",
|
||||
"task_id": taskID,
|
||||
},
|
||||
})
|
||||
// Brief wait so worker can notice cancel and flush.
|
||||
deadline := time.Now().Add(3 * time.Second)
|
||||
for time.Now().Before(deadline) {
|
||||
if workerDone(taskID, emitResult) {
|
||||
break
|
||||
// Default: observer gone ≠ cancel. Task keeps running; client may
|
||||
// reattach via GET /_runtime/tasks/{id}/events (Last-Event-ID).
|
||||
if doCancelOnDisconnect {
|
||||
_, _ = runtimeQuery("cancel", map[string]any{"task_id": taskID})
|
||||
_ = writeCancelToken(cancelTok)
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.interrupted",
|
||||
"payload": map[string]any{
|
||||
"reason": "client_disconnect",
|
||||
"cancel_propagated": cancelTok != "",
|
||||
"status": "stopping",
|
||||
"task_id": taskID,
|
||||
},
|
||||
})
|
||||
deadline := time.Now().Add(3 * time.Second)
|
||||
for time.Now().Before(deadline) {
|
||||
if workerDone(taskID, emitResult) {
|
||||
break
|
||||
}
|
||||
time.Sleep(50 * time.Millisecond)
|
||||
}
|
||||
time.Sleep(50 * time.Millisecond)
|
||||
} else {
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.interrupted",
|
||||
"payload": map[string]any{
|
||||
"reason": "client_disconnect",
|
||||
"cancel_propagated": false,
|
||||
"status": "observer_closed",
|
||||
"task_id": taskID,
|
||||
"resume": "/_runtime/tasks/" + taskID + "/events",
|
||||
},
|
||||
})
|
||||
// Observer gone ≠ cancel, but still reap when the worker exits so
|
||||
// execute slots are not held forever by zombies.
|
||||
go reapIsolatedTask(taskID, emitResult, 10*time.Minute)
|
||||
}
|
||||
finish(true)
|
||||
return
|
||||
@@ -476,23 +532,47 @@ func (st *state) waitIsolatedJSON(w http.ResponseWriter, r *http.Request, route
|
||||
}
|
||||
}
|
||||
|
||||
func workerDone(taskID, emitResult string) bool {
|
||||
if emitResult != "" {
|
||||
if st, err := os.Stat(emitResult); err == nil && st.Size() > 0 {
|
||||
return true
|
||||
// reapIsolatedTask polls runtime get until the worker exits (or timeout),
|
||||
// so supervisor/scheduler slots are released after observer disconnect.
|
||||
func reapIsolatedTask(taskID, emitResult string, budget time.Duration) {
|
||||
deadline := time.Now().Add(budget)
|
||||
for time.Now().Before(deadline) {
|
||||
if workerDone(taskID, emitResult) {
|
||||
return
|
||||
}
|
||||
time.Sleep(200 * time.Millisecond)
|
||||
}
|
||||
// Sibling of event file written by Supervisor even if emit_result was omitted.
|
||||
if taskID != "" {
|
||||
// Last-chance cancel so slots can free.
|
||||
_, _ = runtimeQuery("cancel", map[string]any{"task_id": taskID})
|
||||
for i := 0; i < 25; i++ {
|
||||
if workerDone(taskID, emitResult) {
|
||||
return
|
||||
}
|
||||
time.Sleep(200 * time.Millisecond)
|
||||
}
|
||||
}
|
||||
|
||||
func workerDone(taskID, emitResult string) bool {
|
||||
// Always runtime.get when probing completion: get runs try_reap and
|
||||
// releases execute slots. Do not return early on emit_result alone —
|
||||
// that left zombie workers holding both pool slots (no_slot).
|
||||
if taskID == "" {
|
||||
return false
|
||||
}
|
||||
g, err := runtimeQuery("get", map[string]any{"task_id": taskID})
|
||||
if err != nil {
|
||||
// Fallback: result file present (get may fail during early boot).
|
||||
if emitResult != "" {
|
||||
if st, err := os.Stat(emitResult); err == nil && st.Size() > 0 {
|
||||
return true
|
||||
}
|
||||
}
|
||||
if dir := os.Getenv("MARQDO_RUNTIME_DIR"); dir != "" {
|
||||
p := filepath.Join(dir, "events", taskID+".result.json")
|
||||
if st, err := os.Stat(p); err == nil && st.Size() > 0 {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
g, err := runtimeQuery("get", map[string]any{"task_id": taskID})
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
if _, ok := g["exit_code"]; ok {
|
||||
|
||||
@@ -45,7 +45,8 @@ func TestLegacySSEBridgeSingleFlight(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// M-R0: disconnect marks cancel; token file must not be deleted while holder waits.
|
||||
// M-R0: cancel-token file must not be deleted while bridge holder waits.
|
||||
// (sse-live observer disconnect no longer cancels by default — see cancelOnDisconnect.)
|
||||
func TestCancelTokenSurvivesUntilHolderExits(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
tok := filepath.Join(dir, "cancel.tok")
|
||||
|
||||
@@ -17,7 +17,9 @@ The language is still early: structural markers, English/Chinese builtin aliases
|
||||
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
Want a quick hello? Calls only run when they sit in the entry `# main` — `##` children are methods until something calls them. Try **greet who="marqdo"**. Names can include spaces: **greet who="marqdo user"**.
|
||||
Want a quick hello? `marqdo run` executes the entry `# main`. Try **greet who="marqdo"**. Names can include spaces: **greet who="marqdo user"**.
|
||||
|
||||
This version also runs one function on its own. `marqdo call` takes the file, the function and named arguments. The page you read is the program that runs. What that is for, and why it matters, is in [features/22-call.mq.md](features/22-call.mq.md).
|
||||
|
||||
Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention.
|
||||
|
||||
|
||||
+3
-1
@@ -17,7 +17,9 @@ AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md)(English prose and English builtins).
|
||||
|
||||
想先打个招呼?调用写在入口 `# main` 里才会真的跑——子标题里的方法要等你叫到它。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。
|
||||
想先打个招呼?`marqdo run` 会运行入口 `# main`。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。
|
||||
|
||||
从这一版起,不必为了试用一个函数再包一层入口。`marqdo call` 直接运行文件里的某个函数,参数写在命令上。同一页仍然是给人读的文档。作用和价值写在 [features/22-函数调用.mq.md](features/22-函数调用.mq.md)。
|
||||
|
||||
除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
|
||||
|
||||
|
||||
@@ -14,6 +14,7 @@
|
||||
| [`features/19-foreign-view-cells.mq.md`](features/19-foreign-view-cells.mq.md) / [`19-外联视图单元.mq.md`](features/19-外联视图单元.mq.md) | 外联 v2 完整 Python 示例:probe / JSON call / 并行 / 持久内核 / 状态桥 / view 单元 |
|
||||
| [`features/20-okf-ekc.mq.md`](features/20-okf-ekc.mq.md) / [`20-OKF与EKC.mq.md`](features/20-OKF与EKC.mq.md) | 代码即文档、文档即知识:OKF 形态与 EKC 工程知识编译器 |
|
||||
| [`features/21-persistence.mq.md`](features/21-persistence.mq.md) / [`21-持久化.mq.md`](features/21-持久化.mq.md) | 外联结果持久化:静态快照与 writeback |
|
||||
| [`features/22-call.mq.md`](features/22-call.mq.md) / [`22-函数调用.mq.md`](features/22-函数调用.mq.md) | `marqdo call`:同一份文档按函数执行,知识可以直接当工具 |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent`、`ext/web`、`ext/quantum`、`ext/linalg` — 见 `features/05-*.mq.md`、`06-*.mq.md`、`07-linalg.mq.md` / `07-线性代数.mq.md` 与 `doc/design/ext-*.md`。
|
||||
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Call one function: the same document is the tool
|
||||
description: v2.2.0 marqdo call runs a function inside any .mq.md. The explanation, the implementation and the call are one page.
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
v2.2.0 adds one command: `marqdo call`. It adds no Markdown marker and no skill system. An ordinary .mq.md file is already a document, a piece of knowledge and a program. What was missing is a way to call one of its functions from outside.
|
||||
|
||||
The usual command runs the whole file. Functions inside it run only when the entry calls them. Trying one calculation meant writing an entry, a print and a check. The smallest unit you can execute is now a function.
|
||||
|
||||
```text
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
Standard output is 5. `--json` is for programs and agents: success carries the result, failure carries a diagnostic code, and the process exits non-zero. `--backend tree` and `--backend bytecode` both run that function. Another entry in the file is not used as a fallback.
|
||||
|
||||
The second half of this page is itself a calculator. This command calls this page:
|
||||
|
||||
```text
|
||||
marqdo call public/features/22-call.mq.md calculator.add a=2 b=3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
The change is how the file is used.
|
||||
|
||||
A person reads the sentences next to the function and sees what add computes. The compiler reads the same markers and checks parameters and the return. A developer composes the function into another program. A test passes inputs to this function and looks at the output, without a wrapper whose only job is to print. An agent reads what the function is for and runs the implementation that is already there, instead of reading the page and rewriting it.
|
||||
|
||||
Those four uses are one call. Knowledge becomes a tool because knowledge can already run, now at function scope. The file does not need a special name, and it does not need to declare itself a skill.
|
||||
|
||||
---
|
||||
|
||||
The command keeps a boundary.
|
||||
|
||||
An external call runs a pure function. Writing files, starting a process, using the network or loading a plugin is refused before the function runs, so the side effect does not happen. Wider permission stays on the checks the project already has. An instance method needs its receiver; this command does not invent one.
|
||||
|
||||
The function must resolve to exactly one declaration. No match, or one short name that hits two functions, is a structured error. The command does not pick the first hit. Arguments bind through the signature and contract that the function already has. Missing, unknown and ill-typed arguments are diagnostics.
|
||||
|
||||
After editing a function, call it again with the inputs that failed. A passing check is a reason to keep the edit. A test does not prove every input. It gives the edit a check that can be repeated.
|
||||
|
||||
# calculator
|
||||
|
||||
This is an ordinary Marqdo document.
|
||||
|
||||
It holds a little reusable arithmetic.
|
||||
|
||||
## add
|
||||
|
||||
Add the numbers `a` and `b`.
|
||||
|
||||
*[result](a + b)*
|
||||
|
||||
## multiply
|
||||
|
||||
Multiply the numbers `a` and `b`.
|
||||
|
||||
*[result](a * b)*
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 函数级调用:同一份文档成为工具
|
||||
description: v2.2.0 的 marqdo call 让任意 .mq.md 里的函数可以带参数执行。说明、实现和调用是同一页。
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
v2.2.0 增加一条命令:`marqdo call`。它不新增 Markdown 标记,也不另建一套技能系统。一个普通的 .mq.md 本来就是文档、知识和程序。缺的是从外部直接调用其中某个函数。
|
||||
|
||||
以前日常用法是运行整份文件。入口对象跑完,里面的函数要等文件自己去调用。要试验一个计算,往往得再写入口、打印和检查。现在最小可执行单位是函数。
|
||||
|
||||
```text
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
标准输出是 5。`--json` 给程序和 Agent 读:成功时是带结果的对象,失败时是带诊断码的对象,退出码非 0。`--backend tree` 与 `--backend bytecode` 执行同一个函数。文件里即使还有别的入口,也不会改去跑那个入口。
|
||||
|
||||
本页后半本身就是一份计算器。下面这条命令调用的就是这一页:
|
||||
|
||||
```text
|
||||
marqdo call public/features/22-函数调用.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
它解决的是使用方式,不是再写一份说明书。
|
||||
|
||||
人打开这一页,读函数旁边的句子,知道加法在算什么。编译器解析同一批标记,检查参数和返回。开发者把函数嵌进别的程序。测试对这个函数传入输入,看输出是不是期望值,不必为它包一层只用来打印的程序。Agent 读到的是函数的用途,执行的是已经写好的实现,而不是读完说明再临时重写一遍。
|
||||
|
||||
这四件事共用一次调用。知识成为工具,是「知识即可执行」在函数这一层上的结果。文件不需要改名,也不需要声明自己是技能。运行时和工具清单都不会把一页普通文档挡在门外。
|
||||
|
||||
---
|
||||
|
||||
边界也写在命令里。
|
||||
|
||||
外部调用默认只执行纯函数。写文件、起进程、访问网络、加载插件,会在运行前被拒绝,副作用不会发生。要放宽权限,仍走项目里已有的验证,而不是在这条命令上新开一个开关。实例方法需要接收者,不能靠这条命令凭空调用。
|
||||
|
||||
函数名必须能唯一对上。没有这个函数,或同一个短名指向两个函数,都会返回结构化错误,不会擅自挑第一个。参数按函数已有的签名和契约绑定:缺了、多了、类型不对,都是诊断,不是静默猜一个值。
|
||||
|
||||
改一个函数之后,用原来的输入再调用一次。结果对了,这个实现就留下来;不对,就还是原来的实现。测试不能证明所有输入都正确。它让修改有一个可以重复的检查点。
|
||||
|
||||
# 计算器
|
||||
|
||||
这是一个普通的 Marqdo 文档。
|
||||
|
||||
其中包含一些可以复用的数学计算知识。
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
|
||||
## 乘法
|
||||
|
||||
计算两个数字`a`和`b`的积。
|
||||
|
||||
*[计算结果](a * b)*
|
||||
@@ -27,6 +27,13 @@ need curl curl
|
||||
need tar tar
|
||||
need xz xz-utils
|
||||
|
||||
# /tmp is often a small tmpfs; vendor + Rust extract exceed quota. Prefer disk.
|
||||
if [ -z "${TMPDIR:-}" ] || [ "$TMPDIR" = /tmp ] || [ "$TMPDIR" = /var/tmp ]; then
|
||||
TMPDIR="${HOME}/.cache/marqdo-ppa/work"
|
||||
fi
|
||||
mkdir -p "$TMPDIR"
|
||||
export TMPDIR
|
||||
|
||||
VER="$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)"
|
||||
# Debian revision comes from debian/changelog (e.g. 1.0.2-1ppa2); we append ~series.
|
||||
CHG_VER="$(dpkg-parsechangelog -l debian/changelog -S Version)"
|
||||
@@ -43,7 +50,7 @@ if [[ "$BASE_DEB_VER" != "$VER"-* ]]; then
|
||||
fi
|
||||
fi
|
||||
DEB_VER="${BASE_DEB_VER}~${SERIES}"
|
||||
PKG_ROOT="${TMPDIR:-/tmp}/marqdo-ppa/${VER}"
|
||||
PKG_ROOT="${TMPDIR}/marqdo-ppa/${VER}"
|
||||
BUILD_AREA="${ROOT}/../build-area"
|
||||
GPG_KEY="${MARQDO_PPA_GPG_KEY:-505943294D04C803}"
|
||||
RUST_VER="${MARQDO_PPA_RUST_VERSION:-1.85.0}"
|
||||
@@ -212,18 +219,20 @@ PY
|
||||
exit 1
|
||||
fi
|
||||
# Launchpad builds need only rustc + cargo + rust-std (debian/rules PATH).
|
||||
# Skip docs/json-docs/rustfmt/rls — ~1G of dead weight in the orig tarball.
|
||||
# install.sh's --without is a *single* comma-separated valopt; repeating
|
||||
# --without=… keeps only the last flag, so rust-docs still installed and
|
||||
# blew /tmp quota. Prefer explicit --components= instead.
|
||||
bash "$INSTALL_SH" \
|
||||
--prefix="$PKG_ROOT/third_party/rust" \
|
||||
--without=rust-docs \
|
||||
--without=rust-docs-json-preview \
|
||||
--without=rustfmt-preview \
|
||||
--without=rls-preview \
|
||||
--components="rustc,cargo,rust-std-${RUST_TRIPLE}" \
|
||||
--disable-ldconfig
|
||||
# Belt: docs must never ship in .orig (even if component list drifts).
|
||||
rm -rf "$PKG_ROOT/third_party/rust/share/doc"
|
||||
rm -rf "$RUST_EXTRACT"
|
||||
trap - EXIT
|
||||
"$PKG_ROOT/third_party/rust/bin/rustc" --version
|
||||
"$PKG_ROOT/third_party/rust/bin/cargo" --version
|
||||
du -sh "$PKG_ROOT/third_party/rust"
|
||||
|
||||
cd "$(dirname "$PKG_ROOT")"
|
||||
echo "==> packing ${ORIG_NAME} (vendor + third_party/rust)"
|
||||
|
||||
+30
-12
@@ -21,7 +21,7 @@ Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation a
|
||||
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
|
||||
|
||||
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
|
||||
2. **`**…**` = code / return expression.** `*…*` = statement (bind / expr). Closing markers touch the last token (no trailing space).
|
||||
2. **`**…**` = statement** (assign / call / expression). `*…*` = return. Closing markers touch the last token (no trailing space).
|
||||
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
|
||||
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
|
||||
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
|
||||
@@ -34,8 +34,8 @@ These rules are the **current default**. Do **not** teach Classic `[key](map)` i
|
||||
| Marker | Meaning (v2.1) |
|
||||
|--------|----------------|
|
||||
| `#` / `##`+ | Object/type · function/method |
|
||||
| `*…*` | Statement |
|
||||
| `**…**` | Return / code expression |
|
||||
| `**…**` | Statement (assign / call / expression) |
|
||||
| `*…*` | Return |
|
||||
| `[描述](payload)` | Occlusion step (payload executes) |
|
||||
| `access(c, k)` | Collection read |
|
||||
| `> fn …` | Call |
|
||||
@@ -57,6 +57,24 @@ Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executabl
|
||||
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
|
||||
|
||||
|
||||
## Call one function
|
||||
|
||||
```markdown
|
||||
# 计算器
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
```
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
prints `5`. The same command works on any `.mq.md`; the file does not need a special skill name.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
@@ -96,13 +114,13 @@ Chinese builtins (same functions, no import):
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
**x = 1**
|
||||
**y = x + 2**
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
```markdown
|
||||
@@ -130,9 +148,9 @@ import:
|
||||
|
||||
# main
|
||||
|
||||
*xs = > text.split value="a,b,c" sep=","*
|
||||
**xs = > text.split value="a,b,c" sep=","**
|
||||
> print text=`xs`
|
||||
*t = > clock.now_unix*
|
||||
**t = > clock.now_unix**
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
|
||||
@@ -191,8 +209,8 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
|
||||
|
||||
```markdown
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="probs" theme="light"*
|
||||
**_ = > `qc`.draw kind="circuit" theme="dark"**
|
||||
**_ = > `qc`.draw kind="probs" theme="light"**
|
||||
```
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
@@ -223,8 +241,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `**a = 1**` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (italic is return, and bare text args) | `**xs = > text.split value="a,b" sep=","**` — statement; quote text literals |
|
||||
| Forgetting empty return after nested `##` helper when outer continues | Add `*None*` / `**` / `****` (not `---`) |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
|
||||
@@ -42,6 +42,7 @@ pub fn builtin_type(v: &Value) -> Value {
|
||||
Value::Num(_) => "num",
|
||||
Value::Text(_) => "text",
|
||||
Value::Secret(_) => "secret",
|
||||
Value::Handle(_) => "handle",
|
||||
Value::List(_) => "list",
|
||||
Value::Map(_) => "map",
|
||||
Value::Formula(_) => "formula",
|
||||
|
||||
+21
-3
@@ -33,6 +33,16 @@ struct FlatFun {
|
||||
}
|
||||
|
||||
pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
|
||||
compile_with(path, module, true)
|
||||
}
|
||||
|
||||
/// Compile every function even when the file has no single program entry.
|
||||
/// `Program::entry` is then only a placeholder; callers must use [`Vm::call_function`].
|
||||
pub fn compile_for_call(path: Option<&Path>, module: &Module) -> Result<Program> {
|
||||
compile_with(path, module, false)
|
||||
}
|
||||
|
||||
fn compile_with(path: Option<&Path>, module: &Module, require_entry: bool) -> Result<Program> {
|
||||
let mut flat = Vec::new();
|
||||
let mut next_scope = 1u32;
|
||||
let _exports = collect_module_tree(module, &mut flat, 0, &mut next_scope);
|
||||
@@ -40,7 +50,7 @@ pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
|
||||
bail!("bytecode: no functions to compile");
|
||||
}
|
||||
|
||||
let entry = flat
|
||||
let chosen = flat
|
||||
.iter()
|
||||
.position(|f| f.name == "main" && f.parent.is_none())
|
||||
.or_else(|| {
|
||||
@@ -55,8 +65,14 @@ pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
|
||||
} else {
|
||||
None
|
||||
}
|
||||
})
|
||||
.ok_or_else(|| anyhow::anyhow!("bytecode: no `# main` object"))?;
|
||||
});
|
||||
let entry = match chosen {
|
||||
Some(index) => index,
|
||||
None if !require_entry => 0,
|
||||
None => bail!("bytecode: no `# main` object"),
|
||||
};
|
||||
// Imports are compiled first, so a missing entry must take paths from the file's own functions.
|
||||
let path_owner = if chosen.is_some() { entry } else { flat.len() - 1 };
|
||||
|
||||
let mut objects = Vec::new();
|
||||
let mut methods = Vec::new();
|
||||
@@ -95,6 +111,7 @@ pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
|
||||
|
||||
let parents: Vec<Option<usize>> = flat.iter().map(|f| f.parent).collect();
|
||||
let children: Vec<Vec<usize>> = flat.iter().map(|f| f.children.clone()).collect();
|
||||
let path_index = flat[path_owner].path_index.clone();
|
||||
|
||||
Ok(Program {
|
||||
functions,
|
||||
@@ -104,6 +121,7 @@ pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
|
||||
methods,
|
||||
parents,
|
||||
children,
|
||||
path_index,
|
||||
})
|
||||
}
|
||||
|
||||
|
||||
+5
-1
@@ -3,9 +3,11 @@
|
||||
mod compile;
|
||||
mod vm;
|
||||
|
||||
pub use compile::compile_module;
|
||||
pub use compile::{compile_for_call, compile_module};
|
||||
pub use vm::Vm;
|
||||
|
||||
use std::collections::HashMap;
|
||||
|
||||
use crate::diagnostics::Span;
|
||||
use crate::value::Value;
|
||||
|
||||
@@ -100,6 +102,8 @@ pub struct Program {
|
||||
pub parents: Vec<Option<usize>>,
|
||||
/// Parallel to `functions`: child fn indices.
|
||||
pub children: Vec<Vec<usize>>,
|
||||
/// Dotted path (`计算器.加法`, `inc.加一`) → function index. Entry module exports plus imports.
|
||||
pub path_index: HashMap<Vec<String>, usize>,
|
||||
}
|
||||
|
||||
impl Program {
|
||||
|
||||
+42
-4
@@ -102,7 +102,6 @@ impl Vm {
|
||||
}
|
||||
|
||||
pub fn run(&mut self, program: &Program) -> Result<Value> {
|
||||
let mut stack: Vec<Value> = Vec::new();
|
||||
let entry = program.entry;
|
||||
let arity = program.functions[entry].params.len();
|
||||
if arity != 0 {
|
||||
@@ -113,14 +112,53 @@ impl Vm {
|
||||
.unwrap_or(Span::new(1, 1));
|
||||
return Err(self.err_at(span, "bytecode: entry function needs arguments"));
|
||||
}
|
||||
self.execute(program, entry, &[])
|
||||
}
|
||||
|
||||
/// Run `fn_idx` with named arguments already bound to local slots.
|
||||
/// Does not fall back to [`Program::entry`].
|
||||
pub fn call_function(
|
||||
&mut self,
|
||||
program: &Program,
|
||||
fn_idx: usize,
|
||||
args: &[(String, Value)],
|
||||
) -> Result<Value> {
|
||||
if fn_idx >= program.functions.len() {
|
||||
return Err(self.err_at(
|
||||
Span::new(1, 1),
|
||||
format!("bytecode: function index {fn_idx} is out of range"),
|
||||
));
|
||||
}
|
||||
self.execute(program, fn_idx, args)
|
||||
}
|
||||
|
||||
fn execute(
|
||||
&mut self,
|
||||
program: &Program,
|
||||
fn_idx: usize,
|
||||
args: &[(String, Value)],
|
||||
) -> Result<Value> {
|
||||
let mut stack: Vec<Value> = Vec::new();
|
||||
let mut slots = vec![Value::None; program.functions[fn_idx].locals.len().max(1)];
|
||||
for (name, value) in args {
|
||||
if let Some(i) = program.functions[fn_idx]
|
||||
.locals
|
||||
.iter()
|
||||
.position(|local| local == name)
|
||||
{
|
||||
if i < slots.len() {
|
||||
slots[i] = value.clone();
|
||||
}
|
||||
}
|
||||
}
|
||||
let mut frames = vec![Frame {
|
||||
fn_idx: entry,
|
||||
fn_idx,
|
||||
ip: 0,
|
||||
slots: vec![Value::None; program.functions[entry].locals.len().max(1)],
|
||||
slots,
|
||||
retag_matrix: None,
|
||||
}];
|
||||
self.host
|
||||
.push_call_frame(&program.functions[entry].name.clone());
|
||||
.push_call_frame(&program.functions[fn_idx].name.clone());
|
||||
|
||||
loop {
|
||||
let frame = frames.last_mut().unwrap();
|
||||
|
||||
+295
@@ -0,0 +1,295 @@
|
||||
//! `marqdo call`: run one already-bound function in a `.mq.md` file.
|
||||
//!
|
||||
//! Location, effects, and execution go through the existing compiler and runtime.
|
||||
//! The command does not scan headings, and it does not run the program entry when
|
||||
//! the named function cannot be compiled.
|
||||
|
||||
use std::path::Path;
|
||||
|
||||
use anyhow::Result;
|
||||
|
||||
use crate::ast::Function;
|
||||
use crate::bytecode::{compile_for_call, Vm};
|
||||
use crate::diagnostics::{Diagnostic, Span};
|
||||
use crate::host::{HostCaps, HostContext};
|
||||
use crate::interp::Interpreter;
|
||||
use crate::load::load_module;
|
||||
use crate::sema::{compile_file_closure, SemanticArtifact, SemanticProject};
|
||||
use crate::value::Value;
|
||||
use crate::Backend;
|
||||
|
||||
/// Call `function` in `path` with named arguments.
|
||||
///
|
||||
/// Non-pure effects are refused before the function runs. Host write, exec, net,
|
||||
/// and plugin capabilities stay off for the call.
|
||||
pub fn call_file(
|
||||
path: &Path,
|
||||
function: &str,
|
||||
args: &[(String, Value)],
|
||||
backend: Backend,
|
||||
) -> Result<Value> {
|
||||
let path = path
|
||||
.canonicalize()
|
||||
.map_err(|e| call_diag(None, 1, "call.compile", format!("failed to read {}: {e}", path.display())))?;
|
||||
let compilation = compile_file_closure(&path).map_err(|e| preserve_diag(&path, e))?;
|
||||
let artifact = locate_artifact(&compilation.semantics, &path, function)?;
|
||||
deny_unsafe(&path, artifact)?;
|
||||
execute_source_function(
|
||||
&path,
|
||||
artifact.source.line,
|
||||
&artifact.display_name,
|
||||
args,
|
||||
tight_caps(),
|
||||
backend,
|
||||
true,
|
||||
)
|
||||
.map(|(value, _stdout)| value)
|
||||
}
|
||||
|
||||
/// Run the function declared at `line` in `path`.
|
||||
///
|
||||
/// `display_name` is the declaration path (`计算器.加法`). The query the caller
|
||||
/// typed is not used as a heading search and is not used as the bytecode path,
|
||||
/// so a unique short name or SymbolId still executes that function.
|
||||
/// `caps` are the host capabilities for this run. `call` passes them all off.
|
||||
pub(crate) fn execute_source_function(
|
||||
path: &Path,
|
||||
line: u32,
|
||||
display_name: &str,
|
||||
args: &[(String, Value)],
|
||||
caps: HostCaps,
|
||||
backend: Backend,
|
||||
strict_args: bool,
|
||||
) -> Result<(Value, String)> {
|
||||
let module = load_module(path)?;
|
||||
let fun = find_function_at_line(&module.functions, line).ok_or_else(|| {
|
||||
call_diag(
|
||||
Some(path),
|
||||
line,
|
||||
"artifact.unresolved",
|
||||
format!("无法在 {}:{} 定位函数 {display_name}", path.display(), line),
|
||||
)
|
||||
})?;
|
||||
let expected = display_name
|
||||
.rsplit('.')
|
||||
.next()
|
||||
.unwrap_or(display_name);
|
||||
if fun.name != expected {
|
||||
return Err(call_diag(
|
||||
Some(path),
|
||||
line,
|
||||
"artifact.unresolved",
|
||||
format!("源码行 {line} 上的函数是 `{}`,与 `{display_name}` 不一致", fun.name),
|
||||
));
|
||||
}
|
||||
let mut interp = Interpreter::with_capture(Some(path), false)
|
||||
.with_host(HostContext::for_capture(Some(path), caps));
|
||||
// `call` checks the signature. `artifact.execute` keeps its previous
|
||||
// environment injection so an input the body reads is not rejected as unknown.
|
||||
let bound;
|
||||
let invoke_args: &[(String, Value)] = if strict_args {
|
||||
bound = interp.bind_external_args(&module, fun, args)?;
|
||||
&bound
|
||||
} else {
|
||||
args
|
||||
};
|
||||
match backend {
|
||||
Backend::Tree => {
|
||||
let value = interp.invoke_bound_function(&module, fun, invoke_args)?;
|
||||
Ok((value, interp.captured_stdout))
|
||||
}
|
||||
Backend::Bytecode => {
|
||||
let program = compile_for_call(Some(path), &module)?;
|
||||
let key: Vec<String> = display_name
|
||||
.split('.')
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string())
|
||||
.collect();
|
||||
let idx = program.path_index.get(&key).copied().ok_or_else(|| {
|
||||
call_diag(
|
||||
Some(path),
|
||||
line,
|
||||
"artifact.unresolved",
|
||||
format!("bytecode 没有编译出 `{display_name}`;拒绝改去执行程序入口"),
|
||||
)
|
||||
})?;
|
||||
let mut vm = Vm::with_capture(Some(path))
|
||||
.with_host(HostContext::for_capture(Some(path), caps));
|
||||
let value = vm.call_function(&program, idx, invoke_args)?;
|
||||
Ok((value, vm.captured_stdout))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse `name=value` tokens. Values are integers, decimals, quoted text, or True/False/None.
|
||||
pub fn parse_call_args(tokens: &[String]) -> Result<Vec<(String, Value)>> {
|
||||
let mut out = Vec::new();
|
||||
for token in tokens {
|
||||
let Some((name, raw)) = token.split_once('=') else {
|
||||
return Err(call_diag(
|
||||
None,
|
||||
0,
|
||||
"call.bad_arg",
|
||||
format!("参数 `{token}` 需要写成 名字=值"),
|
||||
));
|
||||
};
|
||||
if name.is_empty() {
|
||||
return Err(call_diag(
|
||||
None,
|
||||
0,
|
||||
"call.bad_arg",
|
||||
format!("参数 `{token}` 缺少名字"),
|
||||
));
|
||||
}
|
||||
let value = parse_literal(raw).map_err(|message| {
|
||||
call_diag(None, 0, "call.bad_value", format!("参数 `{name}`: {message}"))
|
||||
})?;
|
||||
out.push((name.to_string(), value));
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
fn tight_caps() -> HostCaps {
|
||||
HostCaps {
|
||||
fs_write: false,
|
||||
exec: false,
|
||||
net: false,
|
||||
plugin: false,
|
||||
}
|
||||
}
|
||||
|
||||
fn locate_artifact<'a>(
|
||||
project: &'a SemanticProject,
|
||||
entry: &Path,
|
||||
query: &str,
|
||||
) -> Result<&'a SemanticArtifact> {
|
||||
let in_entry: Vec<&SemanticArtifact> = project
|
||||
.artifacts
|
||||
.iter()
|
||||
.filter(|artifact| same_file(&project.root, &artifact.source.file, entry))
|
||||
.collect();
|
||||
let exact: Vec<&SemanticArtifact> = in_entry
|
||||
.iter()
|
||||
.copied()
|
||||
.filter(|artifact| {
|
||||
artifact.display_name == query
|
||||
|| artifact
|
||||
.symbol_id
|
||||
.as_ref()
|
||||
.is_some_and(|id| id.as_str() == query)
|
||||
|| artifact.artifact_id.0 == query
|
||||
})
|
||||
.collect();
|
||||
let hits = if !exact.is_empty() {
|
||||
exact
|
||||
} else if !query.contains('.') {
|
||||
in_entry
|
||||
.iter()
|
||||
.copied()
|
||||
.filter(|artifact| {
|
||||
artifact.kind == "function"
|
||||
&& artifact.display_name.rsplit('.').next() == Some(query)
|
||||
})
|
||||
.collect()
|
||||
} else {
|
||||
Vec::new()
|
||||
};
|
||||
match hits.len() {
|
||||
1 => Ok(hits[0]),
|
||||
0 => Err(call_diag(
|
||||
Some(entry),
|
||||
1,
|
||||
"artifact.unresolved",
|
||||
format!("无法唯一绑定 `{query}`"),
|
||||
)),
|
||||
_ => Err(call_diag(
|
||||
Some(entry),
|
||||
1,
|
||||
"artifact.ambiguous",
|
||||
format!("无法唯一绑定 `{query}`"),
|
||||
)),
|
||||
}
|
||||
}
|
||||
|
||||
fn deny_unsafe(path: &Path, artifact: &SemanticArtifact) -> Result<()> {
|
||||
if artifact.kind != "function" || artifact.callable.as_deref() == Some("instance_method") {
|
||||
return Err(call_diag(
|
||||
Some(path),
|
||||
artifact.source.line,
|
||||
"artifact.not_executable",
|
||||
"只有非实例函数可由 call 直接执行".to_string(),
|
||||
));
|
||||
}
|
||||
if !artifact.effects.is_pure() {
|
||||
return Err(call_diag(
|
||||
Some(path),
|
||||
artifact.source.line,
|
||||
"artifact.effect_denied",
|
||||
format!(
|
||||
"call 默认只执行纯函数,拒绝效应 {}",
|
||||
artifact.effects.values().join(", ")
|
||||
),
|
||||
));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn same_file(root: &Path, rel: &str, entry: &Path) -> bool {
|
||||
let abs = root.join(rel);
|
||||
match (abs.canonicalize(), entry.canonicalize()) {
|
||||
(Ok(left), Ok(right)) => left == right,
|
||||
_ => false,
|
||||
}
|
||||
}
|
||||
|
||||
fn find_function_at_line(functions: &[Function], line: u32) -> Option<&Function> {
|
||||
for fun in functions {
|
||||
if fun.span.line == line {
|
||||
return Some(fun);
|
||||
}
|
||||
if let Some(found) = find_function_at_line(&fun.children, line) {
|
||||
return Some(found);
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn parse_literal(raw: &str) -> Result<Value, String> {
|
||||
match raw {
|
||||
"True" | "true" => return Ok(Value::Bool(true)),
|
||||
"False" | "false" => return Ok(Value::Bool(false)),
|
||||
"None" | "none" => return Ok(Value::None),
|
||||
_ => {}
|
||||
}
|
||||
if raw.len() >= 2 {
|
||||
let bytes = raw.as_bytes();
|
||||
if (bytes[0] == b'"' && bytes[raw.len() - 1] == b'"')
|
||||
|| (bytes[0] == b'\'' && bytes[raw.len() - 1] == b'\'')
|
||||
{
|
||||
return Ok(Value::Text(raw[1..raw.len() - 1].to_string()));
|
||||
}
|
||||
}
|
||||
if let Ok(n) = raw.parse::<i64>() {
|
||||
return Ok(Value::Int(n));
|
||||
}
|
||||
if raw.contains('.') {
|
||||
if let Ok(n) = raw.parse::<f64>() {
|
||||
return Ok(Value::Num(n));
|
||||
}
|
||||
}
|
||||
Err(format!(
|
||||
"无法解析 `{raw}`(整数、小数、引号文本、True/False/None)"
|
||||
))
|
||||
}
|
||||
|
||||
fn preserve_diag(path: &Path, err: anyhow::Error) -> anyhow::Error {
|
||||
if Diagnostic::find(&err).is_some() {
|
||||
err
|
||||
} else {
|
||||
call_diag(Some(path), 1, "call.compile", format!("{err:#}"))
|
||||
}
|
||||
}
|
||||
|
||||
fn call_diag(path: Option<&Path>, line: u32, code: &str, message: String) -> anyhow::Error {
|
||||
anyhow::Error::new(Diagnostic::new(path, Span::new(line, 1), message).with_code(code))
|
||||
}
|
||||
@@ -109,6 +109,7 @@ pub fn type_of(v: &Value) -> &'static str {
|
||||
Value::Num(_) => "num",
|
||||
Value::Text(_) => "text",
|
||||
Value::Secret(_) => "secret",
|
||||
Value::Handle(_) => "handle",
|
||||
Value::List(_) => "list",
|
||||
Value::Map(_) => "map",
|
||||
Value::Formula(_) => "formula",
|
||||
|
||||
+372
-26
@@ -1,4 +1,9 @@
|
||||
//! Document session: cells, kernels, execution journal, state store.
|
||||
//! Document session: cells, kernels, journals, state store.
|
||||
//!
|
||||
//! Two journals (do not mix names):
|
||||
//! - **execution journal** (`JournalRecord`): UI timing / status / errors.
|
||||
//! - **oracle journal** (`OracleRecord`): Ω step recordings for `replay_check`
|
||||
//! (source hash, stdout, result, ok, code).
|
||||
//!
|
||||
//! Stateful cells live here, owned by the foreign runtime. The view reads a
|
||||
//! `会话 = > foreign.session ...` handle; no table names are reserved, and a
|
||||
@@ -56,6 +61,9 @@ pub struct Cell {
|
||||
pub last_ms: u64,
|
||||
pub last_ok: bool,
|
||||
pub last_error: String,
|
||||
/// Captured stdout from the last evaluation (recording surface for replay_check).
|
||||
pub last_stdout: String,
|
||||
pub last_code: i64,
|
||||
/// Value returned by the last successful evaluation, used by explicit persist.
|
||||
pub last_result: Value,
|
||||
}
|
||||
@@ -81,6 +89,20 @@ pub struct JournalRecord {
|
||||
pub error: String,
|
||||
}
|
||||
|
||||
/// One recorded Ω step: what a later `replay_check` compares against.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct OracleRecord {
|
||||
pub seq: u64,
|
||||
pub cell: String,
|
||||
pub kernel: String,
|
||||
pub lang: String,
|
||||
pub source_hash: String,
|
||||
pub ok: bool,
|
||||
pub code: i64,
|
||||
pub stdout: String,
|
||||
pub result: Value,
|
||||
}
|
||||
|
||||
pub struct DocumentSession {
|
||||
pub path: PathBuf,
|
||||
root: PathBuf,
|
||||
@@ -89,6 +111,7 @@ pub struct DocumentSession {
|
||||
pub kernels: Vec<KernelDecl>,
|
||||
pub order: Vec<String>,
|
||||
pub journal: Vec<JournalRecord>,
|
||||
pub oracle_journal: Vec<OracleRecord>,
|
||||
pub value_store: HashMap<String, Value>,
|
||||
pub cursor: usize,
|
||||
pub generation: u64,
|
||||
@@ -289,6 +312,8 @@ fn collect_cells(stmts: &[crate::ast::Stmt], out: &mut Vec<Cell>, seen: &mut Has
|
||||
last_ms: 0,
|
||||
last_ok: false,
|
||||
last_error: String::new(),
|
||||
last_stdout: String::new(),
|
||||
last_code: 0,
|
||||
last_result: Value::None,
|
||||
});
|
||||
}
|
||||
@@ -464,6 +489,7 @@ impl DocumentSession {
|
||||
kernels,
|
||||
order,
|
||||
journal: Vec::new(),
|
||||
oracle_journal: Vec::new(),
|
||||
value_store: HashMap::new(),
|
||||
cursor: 0,
|
||||
generation: 1,
|
||||
@@ -484,7 +510,7 @@ impl DocumentSession {
|
||||
let id = session.ensure_kernel_session(&kernel)?;
|
||||
foreign_session::set(
|
||||
&mut session.host,
|
||||
&Value::Text(id),
|
||||
&Value::Handle(id),
|
||||
&Value::Text(name),
|
||||
&value,
|
||||
)?;
|
||||
@@ -545,7 +571,7 @@ impl DocumentSession {
|
||||
.collect();
|
||||
for k in orphans {
|
||||
if let Some(id) = fresh.kernel_sessions.remove(&k) {
|
||||
let _ = foreign_session::close(&mut fresh.host, &Value::Text(id));
|
||||
let _ = foreign_session::close(&mut fresh.host, &Value::Handle(id));
|
||||
}
|
||||
}
|
||||
*self = fresh;
|
||||
@@ -590,8 +616,8 @@ impl DocumentSession {
|
||||
None,
|
||||
)?;
|
||||
let id = match id {
|
||||
Value::Text(s) => s,
|
||||
_ => return Err("session_open returned non-text id".into()),
|
||||
Value::Handle(s) => s,
|
||||
_ => return Err("session_open returned non-handle id".into()),
|
||||
};
|
||||
self.kernel_sessions
|
||||
.insert(kernel_name.to_string(), id.clone());
|
||||
@@ -618,23 +644,34 @@ impl DocumentSession {
|
||||
Some(Value::Int(n)) => n,
|
||||
_ => 0,
|
||||
};
|
||||
let lang = self
|
||||
.cell_index(cell)
|
||||
.map(|i| self.cells[i].lang.clone())
|
||||
let stdout = field("stdout")
|
||||
.and_then(|v| v.reveal_text().map(|s| s.to_string()))
|
||||
.unwrap_or_default();
|
||||
let (lang, source_hash) = self
|
||||
.cell_index(cell)
|
||||
.map(|i| {
|
||||
(
|
||||
self.cells[i].lang.clone(),
|
||||
self.cells[i].source_hash.clone(),
|
||||
)
|
||||
})
|
||||
.unwrap_or_default();
|
||||
let last_result = field("result")
|
||||
.filter(|v| !matches!(v, Value::None))
|
||||
.unwrap_or_else(|| {
|
||||
field("stdout")
|
||||
.and_then(|v| v.reveal_text().map(|s| Value::Text(s.to_string())))
|
||||
.unwrap_or(Value::None)
|
||||
});
|
||||
if let Some(i) = self.cell_index(cell) {
|
||||
let c = &mut self.cells[i];
|
||||
c.runs += 1;
|
||||
c.last_ms = ms;
|
||||
c.last_ok = ok;
|
||||
c.last_error = error.clone();
|
||||
c.last_result = field("result")
|
||||
.filter(|v| !matches!(v, Value::None))
|
||||
.unwrap_or_else(|| {
|
||||
field("stdout")
|
||||
.and_then(|v| v.reveal_text().map(|s| Value::Text(s.to_string())))
|
||||
.unwrap_or(Value::None)
|
||||
});
|
||||
c.last_stdout = stdout.clone();
|
||||
c.last_code = code;
|
||||
c.last_result = last_result.clone();
|
||||
c.status = if ok { CellStatus::Clean } else { CellStatus::Error };
|
||||
}
|
||||
self.seq += 1;
|
||||
@@ -642,13 +679,24 @@ impl DocumentSession {
|
||||
seq: self.seq,
|
||||
cell: cell.to_string(),
|
||||
kernel: kernel.to_string(),
|
||||
lang,
|
||||
lang: lang.clone(),
|
||||
ok,
|
||||
code,
|
||||
ms,
|
||||
timestamp_ms: now_ms(),
|
||||
error,
|
||||
});
|
||||
self.oracle_journal.push(OracleRecord {
|
||||
seq: self.seq,
|
||||
cell: cell.to_string(),
|
||||
kernel: kernel.to_string(),
|
||||
lang,
|
||||
source_hash,
|
||||
ok,
|
||||
code,
|
||||
stdout,
|
||||
result: last_result,
|
||||
});
|
||||
Ok(())
|
||||
}
|
||||
|
||||
@@ -727,7 +775,7 @@ impl DocumentSession {
|
||||
let source = Value::Text(self.cells[ci].source.clone());
|
||||
let record = foreign_session::eval_with_stdin(
|
||||
&mut self.host,
|
||||
&Value::Text(id),
|
||||
&Value::Handle(id),
|
||||
None,
|
||||
Some(&source),
|
||||
None,
|
||||
@@ -847,7 +895,7 @@ impl DocumentSession {
|
||||
let mut out = Vec::new();
|
||||
for name in ids {
|
||||
if let Some(id) = self.kernel_sessions.get(&name) {
|
||||
match foreign_session::interrupt(&mut self.host, &Value::Text(id.clone())) {
|
||||
match foreign_session::interrupt(&mut self.host, &Value::Handle(id.clone())) {
|
||||
Ok(_) => out.push(Value::Text(name)),
|
||||
Err(e) => out.push(Value::Text(format!("{name}: {e}"))),
|
||||
}
|
||||
@@ -858,7 +906,7 @@ impl DocumentSession {
|
||||
|
||||
pub fn restart_kernel(&mut self, name: &str) -> Result<Value, String> {
|
||||
if let Some(id) = self.kernel_sessions.remove(name) {
|
||||
let _ = foreign_session::close(&mut self.host, &Value::Text(id));
|
||||
let _ = foreign_session::close(&mut self.host, &Value::Handle(id));
|
||||
}
|
||||
for c in &mut self.cells {
|
||||
if c.kernel == name {
|
||||
@@ -938,6 +986,8 @@ impl DocumentSession {
|
||||
last_ms: 0,
|
||||
last_ok: false,
|
||||
last_error: String::new(),
|
||||
last_stdout: String::new(),
|
||||
last_code: 0,
|
||||
last_result: Value::None,
|
||||
});
|
||||
self.order.push(cell.to_string());
|
||||
@@ -974,7 +1024,7 @@ impl DocumentSession {
|
||||
let mut vars = Vec::new();
|
||||
if let Some(id) = live {
|
||||
if self.host.foreign_sessions.contains_key(&id) {
|
||||
if let Ok(names) = foreign_session::names(&mut self.host, &Value::Text(id)) {
|
||||
if let Ok(names) = foreign_session::names(&mut self.host, &Value::Handle(id)) {
|
||||
if let Value::List(xs) = names {
|
||||
vars = xs;
|
||||
}
|
||||
@@ -997,7 +1047,7 @@ impl DocumentSession {
|
||||
let id = self.ensure_kernel_session(kernel)?;
|
||||
foreign_session::set(
|
||||
&mut self.host,
|
||||
&Value::Text(id),
|
||||
&Value::Handle(id),
|
||||
&Value::Text(name.to_string()),
|
||||
&value,
|
||||
)?;
|
||||
@@ -1009,7 +1059,7 @@ impl DocumentSession {
|
||||
let id = self.ensure_kernel_session(kernel)?;
|
||||
let value = foreign_session::get(
|
||||
&mut self.host,
|
||||
&Value::Text(id),
|
||||
&Value::Handle(id),
|
||||
&Value::Text(name.to_string()),
|
||||
)?;
|
||||
self.value_store
|
||||
@@ -1095,10 +1145,14 @@ impl DocumentSession {
|
||||
self.cells[i].last_ms = 0;
|
||||
self.cells[i].last_ok = false;
|
||||
self.cells[i].last_error.clear();
|
||||
self.cells[i].last_stdout.clear();
|
||||
self.cells[i].last_code = 0;
|
||||
self.cells[i].last_result = Value::None;
|
||||
if self.cells[i].listed {
|
||||
self.cells[i].status = CellStatus::Never;
|
||||
}
|
||||
self.journal.retain(|j| j.cell != cell);
|
||||
self.oracle_journal.retain(|j| j.cell != cell);
|
||||
Ok(self.summary())
|
||||
}
|
||||
|
||||
@@ -1110,13 +1164,13 @@ impl DocumentSession {
|
||||
let mut values = Vec::new();
|
||||
if let Some(id) = self.kernel_sessions.get(&decl.name).cloned() {
|
||||
if let Ok(Value::List(names)) =
|
||||
foreign_session::names(&mut self.host, &Value::Text(id.clone()))
|
||||
foreign_session::names(&mut self.host, &Value::Handle(id.clone()))
|
||||
{
|
||||
for name in names {
|
||||
if let Value::Text(n) = &name {
|
||||
if let Ok(v) = foreign_session::get(
|
||||
&mut self.host,
|
||||
&Value::Text(id.clone()),
|
||||
&Value::Handle(id.clone()),
|
||||
&Value::Text(n.clone()),
|
||||
) {
|
||||
values.push(Value::Map(vec![
|
||||
@@ -1144,10 +1198,16 @@ impl DocumentSession {
|
||||
("lang".into(), Value::Text(c.lang.clone())),
|
||||
("kernel".into(), Value::Text(c.kernel.clone())),
|
||||
("source".into(), Value::Text(c.source.clone())),
|
||||
("source_hash".into(), Value::Text(c.source_hash.clone())),
|
||||
("stdin".into(), Value::Text(c.stdin.clone())),
|
||||
("status".into(), Value::Text(c.status.as_str().into())),
|
||||
("runs".into(), Value::Int(c.runs as i64)),
|
||||
("last_ok".into(), Value::Bool(c.last_ok)),
|
||||
// Recording fields: replay_check compares a later run against these.
|
||||
("ok".into(), Value::Bool(c.last_ok)),
|
||||
("code".into(), Value::Int(c.last_code)),
|
||||
("stdout".into(), Value::Text(c.last_stdout.clone())),
|
||||
("result".into(), c.last_result.clone()),
|
||||
])
|
||||
})
|
||||
.collect();
|
||||
@@ -1163,6 +1223,7 @@ impl DocumentSession {
|
||||
self.order.iter().cloned().map(Value::Text).collect(),
|
||||
)),
|
||||
("journal".into(), journal),
|
||||
("oracle_journal".into(), self.oracle_journal_json()),
|
||||
]))
|
||||
}
|
||||
|
||||
@@ -1208,7 +1269,7 @@ impl DocumentSession {
|
||||
let Some(value) = getv("value") else { continue };
|
||||
foreign_session::set(
|
||||
&mut self.host,
|
||||
&Value::Text(id.clone()),
|
||||
&Value::Handle(id.clone()),
|
||||
&Value::Text(vname),
|
||||
&value,
|
||||
)?;
|
||||
@@ -1243,6 +1304,8 @@ impl DocumentSession {
|
||||
}
|
||||
|
||||
/// Replay recorded cells in order, using the snapshot's per-cell stdin.
|
||||
/// Re-runs only; does not compare against the recording. Prefer
|
||||
/// [`Self::replay_check`] when equivalence against a recording matters.
|
||||
pub fn replay_snapshot(&mut self, snapshot: &Value) -> Result<Value, String> {
|
||||
let Value::Map(fields) = snapshot else {
|
||||
return Err("snapshot must be a map".into());
|
||||
@@ -1287,6 +1350,157 @@ impl DocumentSession {
|
||||
]))
|
||||
}
|
||||
|
||||
/// Replay cells and compare each step against the snapshot recording.
|
||||
///
|
||||
/// Expected fields per cell (when present): `ok`, `code`, `stdout`, `result`.
|
||||
/// A difference is localized to the first mismatched field on that cell.
|
||||
/// Cells without any recording fields are skipped for comparison but still run.
|
||||
pub fn replay_check(&mut self, snapshot: &Value) -> Result<Value, String> {
|
||||
let Value::Map(fields) = snapshot else {
|
||||
return Err("snapshot must be a map".into());
|
||||
};
|
||||
let cells = fields
|
||||
.iter()
|
||||
.find(|(k, _)| k == "cells")
|
||||
.and_then(|(_, v)| match v {
|
||||
Value::List(xs) => Some(xs.clone()),
|
||||
_ => None,
|
||||
})
|
||||
.ok_or_else(|| "snapshot: missing cells".to_string())?;
|
||||
let mut checks = Vec::new();
|
||||
let mut matched = 0i64;
|
||||
let mut mismatched = 0i64;
|
||||
let mut skipped = 0i64;
|
||||
for item in cells {
|
||||
let Value::Map(cfields) = item else { continue };
|
||||
let getc = |name: &str| {
|
||||
cfields
|
||||
.iter()
|
||||
.find(|(k, _)| k == name)
|
||||
.map(|(_, v)| v.clone())
|
||||
};
|
||||
let Some(Value::Text(name)) = getc("name") else { continue };
|
||||
if self.cell_index(&name).is_none() {
|
||||
continue;
|
||||
}
|
||||
let has_recording = getc("ok").is_some()
|
||||
|| getc("code").is_some()
|
||||
|| getc("stdout").is_some()
|
||||
|| getc("result").is_some();
|
||||
let stdin = getc("stdin").and_then(|v| match v {
|
||||
Value::Text(s) if !s.is_empty() => Some(s),
|
||||
_ => None,
|
||||
});
|
||||
let record = self.run_cell_with_stdin(&name, None, stdin.as_deref())?;
|
||||
let observed_ok = match &record {
|
||||
Value::Map(m) => matches!(
|
||||
m.iter().find(|(k, _)| k == "ok").map(|(_, v)| v),
|
||||
Some(Value::Bool(true))
|
||||
),
|
||||
_ => false,
|
||||
};
|
||||
let observed_code = match &record {
|
||||
Value::Map(m) => match m.iter().find(|(k, _)| k == "code").map(|(_, v)| v) {
|
||||
Some(Value::Int(n)) => *n,
|
||||
_ => 0,
|
||||
},
|
||||
_ => 0,
|
||||
};
|
||||
let observed_stdout = match &record {
|
||||
Value::Map(m) => m
|
||||
.iter()
|
||||
.find(|(k, _)| k == "stdout")
|
||||
.and_then(|(_, v)| v.reveal_text().map(|s| s.to_string()))
|
||||
.unwrap_or_default(),
|
||||
_ => String::new(),
|
||||
};
|
||||
// Match record_result: prefer explicit result, else stdout as text.
|
||||
let observed_result = match &record {
|
||||
Value::Map(m) => {
|
||||
let explicit = m
|
||||
.iter()
|
||||
.find(|(k, _)| k == "result")
|
||||
.map(|(_, v)| v.clone())
|
||||
.filter(|v| !matches!(v, Value::None));
|
||||
explicit.unwrap_or_else(|| {
|
||||
m.iter()
|
||||
.find(|(k, _)| k == "stdout")
|
||||
.and_then(|(_, v)| v.reveal_text().map(|s| Value::Text(s.to_string())))
|
||||
.unwrap_or(Value::None)
|
||||
})
|
||||
}
|
||||
_ => Value::None,
|
||||
};
|
||||
if !has_recording {
|
||||
skipped += 1;
|
||||
checks.push(Value::Map(vec![
|
||||
("cell".into(), Value::Text(name)),
|
||||
("match".into(), Value::Bool(true)),
|
||||
("compared".into(), Value::Bool(false)),
|
||||
("diff".into(), Value::Text(String::new())),
|
||||
]));
|
||||
continue;
|
||||
}
|
||||
let mut diff = String::new();
|
||||
if let Some(Value::Bool(exp_ok)) = getc("ok") {
|
||||
if exp_ok != observed_ok {
|
||||
diff = format!("ok: expected {exp_ok}, got {observed_ok}");
|
||||
}
|
||||
}
|
||||
if diff.is_empty() {
|
||||
if let Some(Value::Int(exp_code)) = getc("code") {
|
||||
if exp_code != observed_code {
|
||||
diff = format!("code: expected {exp_code}, got {observed_code}");
|
||||
}
|
||||
}
|
||||
}
|
||||
if diff.is_empty() {
|
||||
if let Some(Value::Text(exp_stdout)) = getc("stdout") {
|
||||
if exp_stdout != observed_stdout {
|
||||
diff = format!(
|
||||
"stdout: expected {:?}, got {:?}",
|
||||
exp_stdout, observed_stdout
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
if diff.is_empty() {
|
||||
if let Some(exp_result) = getc("result") {
|
||||
if exp_result != observed_result {
|
||||
diff = format!(
|
||||
"result: expected {}, got {}",
|
||||
exp_result.as_display(),
|
||||
observed_result.as_display()
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
let is_match = diff.is_empty();
|
||||
if is_match {
|
||||
matched += 1;
|
||||
} else {
|
||||
mismatched += 1;
|
||||
}
|
||||
checks.push(Value::Map(vec![
|
||||
("cell".into(), Value::Text(name)),
|
||||
("match".into(), Value::Bool(is_match)),
|
||||
("compared".into(), Value::Bool(true)),
|
||||
("diff".into(), Value::Text(diff)),
|
||||
("observed_ok".into(), Value::Bool(observed_ok)),
|
||||
("observed_code".into(), Value::Int(observed_code)),
|
||||
("observed_stdout".into(), Value::Text(observed_stdout)),
|
||||
("observed_result".into(), observed_result),
|
||||
]));
|
||||
}
|
||||
Ok(Value::Map(vec![
|
||||
("ok".into(), Value::Bool(mismatched == 0)),
|
||||
("matched".into(), Value::Int(matched)),
|
||||
("mismatched".into(), Value::Int(mismatched)),
|
||||
("skipped".into(), Value::Int(skipped)),
|
||||
("checks".into(), Value::List(checks)),
|
||||
]))
|
||||
}
|
||||
|
||||
/// Explicitly persist the last cell result through lib/writeback.
|
||||
pub fn persist_cell(&mut self, cell: &str, key: &str) -> Result<Value, String> {
|
||||
let i = self
|
||||
@@ -1315,11 +1529,15 @@ impl DocumentSession {
|
||||
cell.last_ms = 0;
|
||||
cell.last_ok = false;
|
||||
cell.last_error.clear();
|
||||
cell.last_stdout.clear();
|
||||
cell.last_code = 0;
|
||||
cell.last_result = Value::None;
|
||||
if cell.listed {
|
||||
cell.status = CellStatus::Never;
|
||||
}
|
||||
}
|
||||
self.journal.clear();
|
||||
self.oracle_journal.clear();
|
||||
self.cursor = 0;
|
||||
self.summary()
|
||||
}
|
||||
@@ -1345,10 +1563,31 @@ impl DocumentSession {
|
||||
)
|
||||
}
|
||||
|
||||
pub fn oracle_journal_json(&self) -> Value {
|
||||
Value::List(
|
||||
self.oracle_journal
|
||||
.iter()
|
||||
.map(|j| {
|
||||
Value::Map(vec![
|
||||
("seq".into(), Value::Int(j.seq as i64)),
|
||||
("cell".into(), Value::Text(j.cell.clone())),
|
||||
("kernel".into(), Value::Text(j.kernel.clone())),
|
||||
("lang".into(), Value::Text(j.lang.clone())),
|
||||
("source_hash".into(), Value::Text(j.source_hash.clone())),
|
||||
("ok".into(), Value::Bool(j.ok)),
|
||||
("code".into(), Value::Int(j.code)),
|
||||
("stdout".into(), Value::Text(j.stdout.clone())),
|
||||
("result".into(), j.result.clone()),
|
||||
])
|
||||
})
|
||||
.collect(),
|
||||
)
|
||||
}
|
||||
|
||||
pub fn close(&mut self) {
|
||||
let ids: Vec<String> = self.kernel_sessions.values().cloned().collect();
|
||||
for id in ids {
|
||||
let _ = foreign_session::close(&mut self.host, &Value::Text(id));
|
||||
let _ = foreign_session::close(&mut self.host, &Value::Handle(id));
|
||||
}
|
||||
self.kernel_sessions.clear();
|
||||
}
|
||||
@@ -2066,4 +2305,111 @@ console.log("after error");
|
||||
s.close();
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn oracle_journal_records_stdout_separate_from_execution_journal() {
|
||||
if !node_available() {
|
||||
return;
|
||||
}
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join("tests/notebook/shared.mq.md");
|
||||
let mut s = DocumentSession::open(&path, &root).unwrap();
|
||||
s.run_all(true).unwrap();
|
||||
assert!(!s.journal.is_empty());
|
||||
assert_eq!(s.oracle_journal.len(), s.journal.len());
|
||||
let read = s
|
||||
.oracle_journal
|
||||
.iter()
|
||||
.find(|j| j.cell == "读取")
|
||||
.expect("oracle entry for 读取");
|
||||
assert!(read.ok);
|
||||
assert!(
|
||||
read.stdout.contains('4') || read.stdout.contains("42"),
|
||||
"oracle must capture stdout, got {:?}",
|
||||
read.stdout
|
||||
);
|
||||
assert!(!read.source_hash.is_empty());
|
||||
// Execution journal must not pretend to be the oracle (no stdout field).
|
||||
let exec = s.journal.iter().find(|j| j.cell == "读取").unwrap();
|
||||
assert_eq!(exec.ok, read.ok);
|
||||
s.close();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn replay_check_matches_exported_recording() {
|
||||
if !node_available() {
|
||||
return;
|
||||
}
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join("tests/notebook/shared.mq.md");
|
||||
let mut a = DocumentSession::open(&path, &root).unwrap();
|
||||
a.run_all(true).unwrap();
|
||||
let snap = a.export_snapshot().unwrap();
|
||||
a.close();
|
||||
|
||||
let mut b = DocumentSession::open(&path, &root).unwrap();
|
||||
let check = b.replay_check(&snap).unwrap();
|
||||
assert_eq!(field(&check, "ok"), Some(Value::Bool(true)));
|
||||
assert_eq!(field(&check, "mismatched"), Some(Value::Int(0)));
|
||||
let matched = field(&check, "matched").and_then(|v| match v {
|
||||
Value::Int(n) => Some(n),
|
||||
_ => None,
|
||||
});
|
||||
assert!(matched.unwrap_or(0) >= 1, "expected at least one compared cell");
|
||||
b.close();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn replay_check_localizes_stdout_mismatch() {
|
||||
if !node_available() {
|
||||
return;
|
||||
}
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join("tests/notebook/shared.mq.md");
|
||||
let mut a = DocumentSession::open(&path, &root).unwrap();
|
||||
a.run_all(true).unwrap();
|
||||
let mut snap = a.export_snapshot().unwrap();
|
||||
a.close();
|
||||
|
||||
// Tamper with the recording for cell 读取.
|
||||
if let Value::Map(ref mut fields) = snap {
|
||||
if let Some((_, Value::List(cells))) =
|
||||
fields.iter_mut().find(|(k, _)| k == "cells")
|
||||
{
|
||||
for cell in cells.iter_mut() {
|
||||
let Value::Map(cfields) = cell else { continue };
|
||||
let name = cfields
|
||||
.iter()
|
||||
.find(|(k, _)| k == "name")
|
||||
.and_then(|(_, v)| v.reveal_text().map(|s| s.to_string()));
|
||||
if name.as_deref() == Some("读取") {
|
||||
if let Some((_, v)) = cfields.iter_mut().find(|(k, _)| k == "stdout") {
|
||||
*v = Value::Text("wrong-recording\n".into());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let mut b = DocumentSession::open(&path, &root).unwrap();
|
||||
let check = b.replay_check(&snap).unwrap();
|
||||
assert_eq!(field(&check, "ok"), Some(Value::Bool(false)));
|
||||
assert_eq!(field(&check, "mismatched"), Some(Value::Int(1)));
|
||||
let Some(Value::List(checks)) = field(&check, "checks") else {
|
||||
panic!("missing checks");
|
||||
};
|
||||
let bad = checks.iter().find(|c| {
|
||||
field(c, "cell")
|
||||
.and_then(|v| v.reveal_text().map(|s| s.to_string()))
|
||||
.as_deref()
|
||||
== Some("读取")
|
||||
});
|
||||
let Some(bad) = bad else { panic!("missing 读取 check") };
|
||||
assert_eq!(field(bad, "match"), Some(Value::Bool(false)));
|
||||
let diff = field(bad, "diff")
|
||||
.and_then(|v| v.reveal_text().map(|s| s.to_string()))
|
||||
.unwrap_or_default();
|
||||
assert!(diff.contains("stdout"), "diff should localize to stdout: {diff}");
|
||||
b.close();
|
||||
}
|
||||
}
|
||||
+87
-13
@@ -22,8 +22,35 @@ const MAX_PROCESS_STDERR: usize = 1_048_576;
|
||||
|
||||
const PY_BOOTSTRAP: &str = r#"import sys, json, io, ast, traceback, contextlib
|
||||
_out = sys.stdout
|
||||
_MAX_SAFE = 9007199254740991
|
||||
def _sanitize(o):
|
||||
if o is None or isinstance(o, bool):
|
||||
return o
|
||||
if isinstance(o, int):
|
||||
if abs(o) > _MAX_SAFE:
|
||||
raise ValueError("json: integer outside V_safe (±(2^53-1)): %s" % o)
|
||||
return o
|
||||
if isinstance(o, float):
|
||||
return o
|
||||
if isinstance(o, str):
|
||||
return o
|
||||
if isinstance(o, (list, tuple)):
|
||||
return [_sanitize(x) for x in o]
|
||||
if isinstance(o, dict):
|
||||
return {str(k): _sanitize(v) for k, v in o.items()}
|
||||
raise TypeError("not JSON-safe: %s" % type(o).__name__)
|
||||
def _send(o):
|
||||
_out.write(json.dumps(o, ensure_ascii=False, default=str) + "\n")
|
||||
try:
|
||||
line = json.dumps(_sanitize(o), ensure_ascii=False)
|
||||
except Exception as e:
|
||||
rid = o.get("id") if isinstance(o, dict) else None
|
||||
line = json.dumps({
|
||||
"id": rid, "ok": False,
|
||||
"stdout": (o.get("stdout") if isinstance(o, dict) else "") or "",
|
||||
"stderr": (o.get("stderr") if isinstance(o, dict) else "") or "",
|
||||
"result": None, "error": str(e),
|
||||
}, ensure_ascii=False)
|
||||
_out.write(line + "\n")
|
||||
_out.flush()
|
||||
_g = {"__name__": "__main__", "marqdo_input": None}
|
||||
for _line in sys.stdin:
|
||||
@@ -81,10 +108,40 @@ const JS_BOOTSTRAP: &str = r#"const readline = require("readline");
|
||||
const util = require("util");
|
||||
const vm = require("vm");
|
||||
const out = process.stdout.write.bind(process.stdout);
|
||||
const MAX_SAFE = Number.MAX_SAFE_INTEGER;
|
||||
globalThis.require = require;
|
||||
const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
|
||||
function send(o) { out(JSON.stringify(o) + "\n"); }
|
||||
function toJSON(v) { try { return JSON.parse(JSON.stringify(v)); } catch (e) { return String(v); } }
|
||||
function sanitize(v) {
|
||||
if (v === null || typeof v === "boolean" || typeof v === "string") return v;
|
||||
if (typeof v === "number") {
|
||||
if (Number.isInteger(v) && Math.abs(v) > MAX_SAFE)
|
||||
throw new Error("json: integer outside V_safe (±(2^53-1)): " + v);
|
||||
return v;
|
||||
}
|
||||
if (typeof v === "bigint") {
|
||||
if (v > BigInt(MAX_SAFE) || v < -BigInt(MAX_SAFE))
|
||||
throw new Error("json: integer outside V_safe (±(2^53-1)): " + v.toString());
|
||||
return Number(v);
|
||||
}
|
||||
if (Array.isArray(v)) return v.map(sanitize);
|
||||
if (v && typeof v === "object") {
|
||||
const o = {};
|
||||
for (const k of Object.keys(v)) o[k] = sanitize(v[k]);
|
||||
return o;
|
||||
}
|
||||
throw new Error("not JSON-safe: " + (typeof v));
|
||||
}
|
||||
function send(o) {
|
||||
try { out(JSON.stringify(sanitize(o)) + "\n"); }
|
||||
catch (e) {
|
||||
out(JSON.stringify({
|
||||
id: o && o.id !== undefined ? o.id : null, ok: false,
|
||||
stdout: (o && o.stdout) || "", stderr: (o && o.stderr) || "",
|
||||
result: null, error: String(e && e.message ? e.message : e)
|
||||
}) + "\n");
|
||||
}
|
||||
}
|
||||
function toJSON(v) { return sanitize(v); }
|
||||
async function capture(fn) {
|
||||
const logs = [], errs = [];
|
||||
const ow = process.stdout.write.bind(process.stdout);
|
||||
@@ -182,6 +239,15 @@ fn opt_text(v: Option<&Value>) -> Result<Option<String>, String> {
|
||||
}
|
||||
}
|
||||
|
||||
/// Session ids are opaque handles — text fabrications are refused.
|
||||
fn as_session_id<'a>(id: &'a Value) -> Result<&'a str, String> {
|
||||
match id {
|
||||
Value::Handle(s) => Ok(s.as_str()),
|
||||
Value::Text(_) => Err("session id must be a handle (not text)".into()),
|
||||
_ => Err("session id must be a handle".into()),
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_timeout(v: Option<&Value>, default: f64) -> Result<Duration, String> {
|
||||
let secs = match v {
|
||||
None | Some(Value::None) => default,
|
||||
@@ -418,7 +484,7 @@ pub fn open(
|
||||
};
|
||||
ctx.foreign_sessions.insert(id.clone(), session);
|
||||
let _ = timeout;
|
||||
Ok(Value::Text(id))
|
||||
Ok(Value::Handle(id))
|
||||
}
|
||||
|
||||
fn session_dead_stderr(ctx: &HostContext, id: &str) -> String {
|
||||
@@ -453,7 +519,7 @@ pub fn eval_with_stdin(
|
||||
timeout: Option<&Value>,
|
||||
) -> Result<Value, String> {
|
||||
ensure_config(ctx);
|
||||
let id = as_text(id, "id")?.to_string();
|
||||
let id = as_session_id(id)?.to_string();
|
||||
if !ctx.foreign_sessions.contains_key(&id) {
|
||||
return Err(format!("foreign session `{id}` not found"));
|
||||
}
|
||||
@@ -544,6 +610,10 @@ pub fn eval_with_stdin(
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
// Ω ∉ V_safe is a language fault, not a soft cell failure.
|
||||
if error.contains("outside V_safe") {
|
||||
return Err(error);
|
||||
}
|
||||
let result = reply
|
||||
.get("result")
|
||||
.map(json_to_value)
|
||||
@@ -650,7 +720,7 @@ fn kill_session(ctx: &mut HostContext, id: &str) {
|
||||
/// Interrupt the current evaluation without destroying the kernel. Python
|
||||
/// reports KeyboardInterrupt through the normal result frame.
|
||||
pub fn interrupt(ctx: &mut HostContext, id: &Value) -> Result<Value, String> {
|
||||
let id = as_text(id, "id")?.to_string();
|
||||
let id = as_session_id(id)?.to_string();
|
||||
let session = ctx
|
||||
.foreign_sessions
|
||||
.get_mut(&id)
|
||||
@@ -675,7 +745,7 @@ pub fn set(
|
||||
name: &Value,
|
||||
value: &Value,
|
||||
) -> Result<Value, String> {
|
||||
let id = as_text(id, "id")?.to_string();
|
||||
let id = as_session_id(id)?.to_string();
|
||||
let name = as_text(name, "name")?.to_string();
|
||||
if !valid_name(&name) {
|
||||
return Err("session_set: name must be an identifier".into());
|
||||
@@ -695,7 +765,7 @@ pub fn set(
|
||||
}
|
||||
|
||||
pub fn get(ctx: &mut HostContext, id: &Value, name: &Value) -> Result<Value, String> {
|
||||
let id = as_text(id, "id")?.to_string();
|
||||
let id = as_session_id(id)?.to_string();
|
||||
let name = as_text(name, "name")?.to_string();
|
||||
if !valid_name(&name) {
|
||||
return Err("session_get: name must be an identifier".into());
|
||||
@@ -716,7 +786,7 @@ pub fn get(ctx: &mut HostContext, id: &Value, name: &Value) -> Result<Value, Str
|
||||
}
|
||||
|
||||
pub fn names(ctx: &mut HostContext, id: &Value) -> Result<Value, String> {
|
||||
let id = as_text(id, "id")?.to_string();
|
||||
let id = as_session_id(id)?.to_string();
|
||||
let request = serde_json::json!({"id": 1, "op": "names"});
|
||||
let reply = send_and_wait(ctx, &id, &request, Duration::from_secs(10))?;
|
||||
if !reply.get("ok").and_then(|v| v.as_bool()).unwrap_or(false) {
|
||||
@@ -733,10 +803,14 @@ pub fn names(ctx: &mut HostContext, id: &Value) -> Result<Value, String> {
|
||||
}
|
||||
|
||||
pub fn close(ctx: &mut HostContext, id: &Value) -> Result<Value, String> {
|
||||
let id = as_text(id, "id")?.to_string();
|
||||
let existed = ctx.foreign_sessions.contains_key(&id);
|
||||
let id = as_session_id(id)?.to_string();
|
||||
// Affine close: consuming an absent / already-closed handle is a fault
|
||||
// (same surface as eval/set/get after close).
|
||||
if !ctx.foreign_sessions.contains_key(&id) {
|
||||
return Err(format!("foreign session `{id}` not found"));
|
||||
}
|
||||
kill_session(ctx, &id);
|
||||
Ok(Value::Bool(existed))
|
||||
Ok(Value::Bool(true))
|
||||
}
|
||||
|
||||
pub fn list(ctx: &HostContext) -> Result<Value, String> {
|
||||
@@ -745,7 +819,7 @@ pub fn list(ctx: &HostContext) -> Result<Value, String> {
|
||||
let mut out = Vec::new();
|
||||
for s in sessions {
|
||||
out.push(Value::Map(vec![
|
||||
("id".into(), Value::Text(s.id.clone())),
|
||||
("id".into(), Value::Handle(s.id.clone())),
|
||||
("lang".into(), Value::Text(s.lang.clone())),
|
||||
("cmd".into(), Value::Text(s.cmd.clone())),
|
||||
("evals".into(), Value::Int(s.evals as i64)),
|
||||
|
||||
+145
-2
@@ -1,7 +1,21 @@
|
||||
//! JSON host primitives + Value↔JSON mapping.
|
||||
//!
|
||||
//! Integer gate matches Lean \(V_{\mathsf{safe}}\) (`doc/design/v-safe-json.md`):
|
||||
//! JSON integers with `|n| > 2^53-1` refuse on encode and decode.
|
||||
|
||||
use crate::value::Value;
|
||||
|
||||
/// JavaScript `Number.MAX_SAFE_INTEGER` / Lean `ForeignJSON.maxSafe`.
|
||||
pub const MAX_SAFE_INT: i64 = 9_007_199_254_740_991; // 2^53 - 1
|
||||
|
||||
pub fn in_safe_int(n: i64) -> bool {
|
||||
(-MAX_SAFE_INT..=MAX_SAFE_INT).contains(&n)
|
||||
}
|
||||
|
||||
fn ood_int_err(n: impl std::fmt::Display) -> String {
|
||||
format!("json: integer outside V_safe (±(2^53-1)): {n}")
|
||||
}
|
||||
|
||||
pub fn parse(text: &Value) -> Result<Value, String> {
|
||||
let s = match text {
|
||||
Value::Text(s) => s.as_str(),
|
||||
@@ -70,11 +84,18 @@ pub(crate) fn json_to_value(v: &serde_json::Value) -> Result<Value, String> {
|
||||
serde_json::Value::Bool(b) => Value::Bool(*b),
|
||||
serde_json::Value::Number(n) => {
|
||||
if let Some(i) = n.as_i64() {
|
||||
if !in_safe_int(i) {
|
||||
return Err(ood_int_err(i));
|
||||
}
|
||||
Value::Int(i)
|
||||
} else if let Some(u) = n.as_u64() {
|
||||
// Always > i64::MAX ⇒ outside V_safe; never coerce via f64/Text.
|
||||
return Err(ood_int_err(u));
|
||||
} else if let Some(f) = n.as_f64() {
|
||||
// Host extension: non-integer JSON numbers → Num (not in Lean SafeVal).
|
||||
Value::Num(f)
|
||||
} else {
|
||||
Value::Text(n.to_string())
|
||||
return Err(format!("json: unsupported number: {n}"));
|
||||
}
|
||||
}
|
||||
serde_json::Value::String(s) => Value::Text(s.clone()),
|
||||
@@ -99,7 +120,12 @@ pub(crate) fn value_to_json(v: &Value) -> Result<serde_json::Value, String> {
|
||||
Ok(match v {
|
||||
Value::None => serde_json::Value::Null,
|
||||
Value::Bool(b) => serde_json::Value::Bool(*b),
|
||||
Value::Int(n) => serde_json::Value::Number((*n).into()),
|
||||
Value::Int(n) => {
|
||||
if !in_safe_int(*n) {
|
||||
return Err(ood_int_err(*n));
|
||||
}
|
||||
serde_json::Value::Number((*n).into())
|
||||
}
|
||||
Value::Num(n) => serde_json::Number::from_f64(*n)
|
||||
.map(serde_json::Value::Number)
|
||||
.unwrap_or(serde_json::Value::Null),
|
||||
@@ -112,6 +138,22 @@ pub(crate) fn value_to_json(v: &Value) -> Result<serde_json::Value, String> {
|
||||
serde_json::Value::Array(arr)
|
||||
}
|
||||
Value::Map(entries) => {
|
||||
// Column-table maps (all fields lists): refuse unequal list lengths.
|
||||
let list_lens: Vec<usize> = entries
|
||||
.iter()
|
||||
.filter_map(|(_, v)| match v {
|
||||
Value::List(xs) => Some(xs.len()),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
if list_lens.len() == entries.len() && list_lens.len() >= 2 {
|
||||
let n0 = list_lens[0];
|
||||
if list_lens.iter().any(|&n| n != n0) {
|
||||
return Err(
|
||||
"json: table column arity mismatch (unequal list lengths)".into(),
|
||||
);
|
||||
}
|
||||
}
|
||||
let mut map = serde_json::Map::new();
|
||||
for (k, v) in entries {
|
||||
map.insert(k.clone(), value_to_json(v)?);
|
||||
@@ -147,6 +189,9 @@ pub(crate) fn value_to_json(v: &Value) -> Result<serde_json::Value, String> {
|
||||
},
|
||||
Value::Code(c) => serde_json::Value::String(c.source.clone()),
|
||||
Value::Secret(_) => serde_json::Value::String("<secret>".into()),
|
||||
Value::Handle(_) => {
|
||||
return Err("json: session handle cannot be serialized".into());
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
@@ -159,4 +204,102 @@ mod tests {
|
||||
let q = quote(&Value::Text("a\"b".into())).unwrap();
|
||||
assert_eq!(q, Value::Text("\"a\\\"b\"".into()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn roundtrip_max_safe() {
|
||||
for n in [MAX_SAFE_INT, -MAX_SAFE_INT, 0_i64, 1, -1] {
|
||||
let j = value_to_json(&Value::Int(n)).unwrap();
|
||||
let v = json_to_value(&j).unwrap();
|
||||
assert_eq!(v, Value::Int(n));
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refuse_ood_encode() {
|
||||
for n in [
|
||||
MAX_SAFE_INT + 1,
|
||||
-MAX_SAFE_INT - 1,
|
||||
1_i64 << 53, // 2^53
|
||||
1_i64 << 60, // 2^60
|
||||
(1_i64 << 60) + 1, // 2^60+1
|
||||
] {
|
||||
let err = value_to_json(&Value::Int(n)).unwrap_err();
|
||||
assert!(
|
||||
err.contains("outside V_safe"),
|
||||
"encode {n}: {err}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refuse_ood_decode() {
|
||||
for n in [
|
||||
MAX_SAFE_INT + 1,
|
||||
-MAX_SAFE_INT - 1,
|
||||
1_i64 << 53,
|
||||
1_i64 << 60,
|
||||
(1_i64 << 60) + 1,
|
||||
] {
|
||||
let raw = format!("{n}");
|
||||
let j: serde_json::Value = serde_json::from_str(&raw).unwrap();
|
||||
let err = json_to_value(&j).unwrap_err();
|
||||
assert!(
|
||||
err.contains("outside V_safe"),
|
||||
"decode {n}: {err}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refuse_nested_ood() {
|
||||
let j: serde_json::Value =
|
||||
serde_json::from_str("{\"a\":[1152921504606846977]}").unwrap();
|
||||
let err = json_to_value(&j).unwrap_err();
|
||||
assert!(err.contains("outside V_safe"), "{err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn decimal_string_ok() {
|
||||
let j = serde_json::Value::String("1152921504606846977".into());
|
||||
assert_eq!(
|
||||
json_to_value(&j).unwrap(),
|
||||
Value::Text("1152921504606846977".into())
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn float_host_extension_ok() {
|
||||
let j: serde_json::Value = serde_json::from_str("1.5").unwrap();
|
||||
match json_to_value(&j).unwrap() {
|
||||
Value::Num(f) => assert!((f - 1.5).abs() < 1e-12),
|
||||
other => panic!("expected Num, got {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refuse_u64_above_i64_max() {
|
||||
// 2^63 as JSON integer: as_i64 fails, as_u64 succeeds.
|
||||
let j: serde_json::Value = serde_json::from_str("9223372036854775808").unwrap();
|
||||
let err = json_to_value(&j).unwrap_err();
|
||||
assert!(err.contains("outside V_safe"), "{err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refuse_session_handle_encode() {
|
||||
let err = value_to_json(&Value::Handle("s1".into())).unwrap_err();
|
||||
assert!(
|
||||
err.contains("session handle cannot be serialized"),
|
||||
"{err}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refuse_unequal_column_table_encode() {
|
||||
let ragged = Value::Map(vec![
|
||||
("a".into(), Value::List(vec![Value::Int(1), Value::Int(2)])),
|
||||
("b".into(), Value::List(vec![Value::Int(3)])),
|
||||
]);
|
||||
let err = value_to_json(&ragged).unwrap_err();
|
||||
assert!(err.contains("arity mismatch"), "{err}");
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -67,7 +67,7 @@ use std::collections::HashMap;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
/// Host capability flags. Default: all enabled.
|
||||
#[derive(Debug, Clone)]
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
pub struct HostCaps {
|
||||
pub fs_write: bool,
|
||||
pub exec: bool,
|
||||
|
||||
+108
-29
@@ -151,6 +151,13 @@ impl Interpreter {
|
||||
bail_at(self.path.as_deref(), self.current_span, message)
|
||||
}
|
||||
|
||||
fn err_code(&self, code: &str, message: impl Into<String>) -> anyhow::Error {
|
||||
anyhow::Error::new(
|
||||
crate::diagnostics::Diagnostic::new(self.path.as_deref(), self.current_span, message)
|
||||
.with_code(code),
|
||||
)
|
||||
}
|
||||
|
||||
fn emit_line(&mut self, text: &str) {
|
||||
if self.capture {
|
||||
self.captured_stdout.push_str(text);
|
||||
@@ -363,6 +370,68 @@ impl Interpreter {
|
||||
self.run_function(module, fun, Env::new(), args, false)
|
||||
}
|
||||
|
||||
/// Bind named arguments for an external call. Unknown names, missing
|
||||
/// required parameters, and contract mismatches are errors. Defaults run.
|
||||
pub fn bind_external_args(
|
||||
&mut self,
|
||||
module: &Module,
|
||||
fun: &Function,
|
||||
args: &[(String, Value)],
|
||||
) -> Result<Vec<(String, Value)>> {
|
||||
self.current_span = fun.span;
|
||||
self.host.current_line = fun.span.line;
|
||||
let mut named: HashMap<String, Value> = HashMap::new();
|
||||
for (k, v) in args {
|
||||
if named.insert(k.clone(), v.clone()).is_some() {
|
||||
return Err(self.err_code(
|
||||
"call.duplicate_arg",
|
||||
format!("duplicate named argument `{k}`"),
|
||||
));
|
||||
}
|
||||
}
|
||||
for k in named.keys() {
|
||||
if !fun.params.iter().any(|p| &p.name == k) {
|
||||
return Err(self.err_code(
|
||||
"call.unknown_arg",
|
||||
format!("unknown argument `{k}`"),
|
||||
));
|
||||
}
|
||||
}
|
||||
let ev: Vec<EvArg> = named
|
||||
.into_iter()
|
||||
.map(|(k, v)| EvArg::Named(k, v))
|
||||
.collect();
|
||||
let mut env = Env::new();
|
||||
let bound = bind_function_args(self, module, fun, &mut env, &fun.params, &ev, false)
|
||||
.map_err(|m| {
|
||||
if m.starts_with("missing argument") {
|
||||
self.err_code("call.missing_arg", m)
|
||||
} else if m.starts_with("duplicate named argument") {
|
||||
self.err_code("call.duplicate_arg", m)
|
||||
} else {
|
||||
self.err(m)
|
||||
}
|
||||
})?;
|
||||
if let Some(c) = &fun.contract {
|
||||
if let Some(d) = crate::contract::call_arg_diag(
|
||||
c,
|
||||
&fun.name,
|
||||
&bound,
|
||||
self.path.as_deref(),
|
||||
fun.span,
|
||||
) {
|
||||
return Err(d.into());
|
||||
}
|
||||
}
|
||||
let mut out = Vec::new();
|
||||
for p in &fun.params {
|
||||
if let Some(v) = bound.get(&p.name) {
|
||||
out.push((p.name.clone(), v.clone()));
|
||||
}
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Call a function using (and updating) [`Self::entry_bindings`] from `# main`.
|
||||
/// Used by browser WASM sessions so handlers share state with the entry object.
|
||||
pub fn invoke_in_entry(
|
||||
@@ -1450,36 +1519,8 @@ impl Interpreter {
|
||||
path: &[String],
|
||||
ev_args: &[EvArg],
|
||||
) -> Result<Value> {
|
||||
let (lib, node) = locate_import_function(module, path).map_err(|m| self.err(m))?;
|
||||
let display = path.join(".");
|
||||
if path.len() < 2 {
|
||||
return Err(self.err(format!("library path `{display}`: need at least `lib.member`")));
|
||||
}
|
||||
let lib_name = &path[0];
|
||||
let lib = module.import_modules.get(lib_name).ok_or_else(|| {
|
||||
self.err(format!("unknown library `{lib_name}` (import it in frontmatter)"))
|
||||
})?;
|
||||
|
||||
let mut parent_is_object = false;
|
||||
let mut node = lib
|
||||
.functions
|
||||
.iter()
|
||||
.find(|f| f.name == path[1])
|
||||
.ok_or_else(|| self.err(format!("unknown `{display}`")))?;
|
||||
for seg in &path[2..] {
|
||||
parent_is_object = node.is_object();
|
||||
node = node
|
||||
.children
|
||||
.iter()
|
||||
.find(|c| c.name == *seg)
|
||||
.ok_or_else(|| self.err(format!("unknown `{display}`")))?;
|
||||
}
|
||||
|
||||
if parent_is_object && !node.is_object() && crate::ast::function_uses_receiver(node) {
|
||||
return Err(self.err(format!(
|
||||
"`{display}` is an instance method; call it as `var`.{}",
|
||||
node.name
|
||||
)));
|
||||
}
|
||||
|
||||
let bound = {
|
||||
let mut dummy_env = Env::new();
|
||||
@@ -1613,6 +1654,44 @@ fn tag_instance(type_name: &str, value: Value) -> Value {
|
||||
}
|
||||
}
|
||||
|
||||
/// `lib.member` / `lib.Type.member` against frontmatter imports. Does not execute.
|
||||
pub(crate) fn locate_import_function<'a>(
|
||||
module: &'a Module,
|
||||
path: &[String],
|
||||
) -> Result<(&'a Module, &'a Function), String> {
|
||||
let display = path.join(".");
|
||||
if path.len() < 2 {
|
||||
return Err(format!(
|
||||
"library path `{display}`: need at least `lib.member`"
|
||||
));
|
||||
}
|
||||
let lib = module
|
||||
.import_modules
|
||||
.get(&path[0])
|
||||
.ok_or_else(|| format!("unknown library `{}` (import it in frontmatter)", path[0]))?;
|
||||
let mut parent_is_object = false;
|
||||
let mut node = lib
|
||||
.functions
|
||||
.iter()
|
||||
.find(|f| f.name == path[1])
|
||||
.ok_or_else(|| format!("unknown `{display}`"))?;
|
||||
for seg in &path[2..] {
|
||||
parent_is_object = node.is_object();
|
||||
node = node
|
||||
.children
|
||||
.iter()
|
||||
.find(|c| c.name == *seg)
|
||||
.ok_or_else(|| format!("unknown `{display}`"))?;
|
||||
}
|
||||
if parent_is_object && !node.is_object() && crate::ast::function_uses_receiver(node) {
|
||||
return Err(format!(
|
||||
"`{display}` is an instance method; call it as `var`.{}",
|
||||
node.name
|
||||
));
|
||||
}
|
||||
Ok((lib, node))
|
||||
}
|
||||
|
||||
/// Bind evaluated args onto parameter names. Err is a plain message (caller adds span/path).
|
||||
fn bind_function_args(
|
||||
interp: &mut Interpreter,
|
||||
|
||||
+38
-34
@@ -114,7 +114,23 @@ pub fn ekc_graph_dir(out_dir: &Path) -> std::path::PathBuf {
|
||||
out_dir.join("ekc").join("graph")
|
||||
}
|
||||
|
||||
/// Path of the full IR snapshot used by warm query paths (preflight/find/reuse).
|
||||
pub fn ir_snapshot_path(out_dir: &Path) -> std::path::PathBuf {
|
||||
ekc_graph_dir(out_dir).join("ir.json")
|
||||
}
|
||||
|
||||
/// Load a previously compiled KnowledgeGraph without re-extracting sources.
|
||||
/// Prefers `ekc/graph/ir.json`. Does **not** walk the source tree.
|
||||
pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
|
||||
let ir_path = ir_snapshot_path(out_dir);
|
||||
if ir_path.exists() {
|
||||
let raw = fs::read_to_string(&ir_path)
|
||||
.with_context(|| format!("read {}", ir_path.display()))?;
|
||||
let graph: KnowledgeGraph = serde_json::from_str(&raw)
|
||||
.with_context(|| format!("parse {}", ir_path.display()))?;
|
||||
return Ok(graph);
|
||||
}
|
||||
|
||||
let graph_path = ekc_graph_dir(out_dir).join("graph.json");
|
||||
let edges_path = ekc_graph_dir(out_dir).join("edges.json");
|
||||
if !graph_path.exists() {
|
||||
@@ -123,47 +139,19 @@ pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
|
||||
graph_path.display()
|
||||
);
|
||||
}
|
||||
// Prefer re-extract for freshness when source path known; for query commands
|
||||
// we rebuild from JSON snapshot fields + re-scan if catalog sibling exists.
|
||||
// Snapshot load: reconstruct minimal IR from written pages + edges.json.
|
||||
|
||||
// Legacy projections without ir.json: edges-only fallback (no source walk).
|
||||
let edges_raw = fs::read_to_string(&edges_path).unwrap_or_else(|_| "{\"edges\":[]}".into());
|
||||
let edges_v: serde_json::Value = serde_json::from_str(&edges_raw)?;
|
||||
let graph_raw = fs::read_to_string(&graph_path)?;
|
||||
let graph_v: serde_json::Value = serde_json::from_str(&graph_raw)?;
|
||||
|
||||
// Re-compile from recorded root if present in graph.json
|
||||
if let Some(root) = graph_v
|
||||
.pointer("/repository/root")
|
||||
.and_then(|v| v.as_str())
|
||||
{
|
||||
let root_path = Path::new(root);
|
||||
if root_path.exists() {
|
||||
return extract_graph(&ExtractOptions {
|
||||
path: root_path.to_path_buf(),
|
||||
out_dir: out_dir.to_path_buf(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback: empty-ish graph with edges only
|
||||
let mut edges = Vec::new();
|
||||
if let Some(arr) = edges_v.get("edges").and_then(|e| e.as_array()) {
|
||||
for e in arr {
|
||||
let kind = match e.get("kind").and_then(|k| k.as_str()).unwrap_or("") {
|
||||
"implements" => crate::knowledge::ir::EdgeKind::Implements,
|
||||
"uses" => crate::knowledge::ir::EdgeKind::Uses,
|
||||
"depends_on" => crate::knowledge::ir::EdgeKind::DependsOn,
|
||||
"tested_by" => crate::knowledge::ir::EdgeKind::TestedBy,
|
||||
"documented_by" => crate::knowledge::ir::EdgeKind::DocumentedBy,
|
||||
"constrained_by" => crate::knowledge::ir::EdgeKind::ConstrainedBy,
|
||||
"decided_by" => crate::knowledge::ir::EdgeKind::DecidedBy,
|
||||
"supersedes" => crate::knowledge::ir::EdgeKind::Supersedes,
|
||||
"conflicts_with" => crate::knowledge::ir::EdgeKind::ConflictsWith,
|
||||
"deprecated_by" => crate::knowledge::ir::EdgeKind::DeprecatedBy,
|
||||
"derived_from" => crate::knowledge::ir::EdgeKind::DerivedFrom,
|
||||
"failed_by" => crate::knowledge::ir::EdgeKind::FailedBy,
|
||||
_ => crate::knowledge::ir::EdgeKind::RelatedTo,
|
||||
};
|
||||
let kind = crate::knowledge::ir::EdgeKind::parse(
|
||||
e.get("kind").and_then(|k| k.as_str()).unwrap_or(""),
|
||||
);
|
||||
edges.push(crate::knowledge::ir::Edge {
|
||||
from: e.get("from").and_then(|v| v.as_str()).unwrap_or("").into(),
|
||||
to: e.get("to").and_then(|v| v.as_str()).unwrap_or("").into(),
|
||||
@@ -204,14 +192,27 @@ pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
|
||||
})
|
||||
}
|
||||
|
||||
/// Force a full knowledge compile (write path / `--refresh`).
|
||||
pub fn ensure_compiled(path: &Path, out_dir: &Path) -> Result<KnowledgeGraph> {
|
||||
// Always refresh from source when path is given.
|
||||
compile(KnowledgeOptions {
|
||||
path: path.to_path_buf(),
|
||||
out_dir: out_dir.to_path_buf(),
|
||||
})
|
||||
}
|
||||
|
||||
/// Query path loader: compile if missing (or `refresh`), else hot-load `ir.json`.
|
||||
pub fn graph_for_query(path: &Path, out_dir: &Path, refresh: bool) -> Result<KnowledgeGraph> {
|
||||
if refresh {
|
||||
return ensure_compiled(path, out_dir);
|
||||
}
|
||||
let has_ir = ir_snapshot_path(out_dir).exists();
|
||||
let has_graph = ekc_graph_dir(out_dir).join("graph.json").exists();
|
||||
if has_ir || has_graph {
|
||||
return load_graph(out_dir);
|
||||
}
|
||||
ensure_compiled(path, out_dir)
|
||||
}
|
||||
|
||||
fn write_projections(out_dir: &Path, graph: &KnowledgeGraph) -> Result<()> {
|
||||
let dirs = [
|
||||
"catalog/modules",
|
||||
@@ -299,6 +300,9 @@ fn write_projections(out_dir: &Path, graph: &KnowledgeGraph) -> Result<()> {
|
||||
fs::write(ekc.join("graph.json"), graph_json)?;
|
||||
let edges_json = serde_json::to_string_pretty(&graph.to_edges_json())?;
|
||||
fs::write(ekc.join("edges.json"), edges_json)?;
|
||||
// Full IR snapshot for warm query paths (preflight/find/reuse) — no re-extract.
|
||||
let ir_json = serde_json::to_string(&graph)?;
|
||||
fs::write(ekc.join("ir.json"), ir_json)?;
|
||||
|
||||
// Search index
|
||||
let index = json!({
|
||||
|
||||
+67
-9
@@ -1,5 +1,6 @@
|
||||
//! Engineering Knowledge IR (L0–L4) — projections of `.mq.md`, not a second source of truth.
|
||||
|
||||
use serde::{Deserialize, Deserializer, Serialize, Serializer};
|
||||
use serde_json::{json, Value};
|
||||
use std::collections::BTreeMap;
|
||||
|
||||
@@ -13,6 +14,19 @@ pub enum Lifecycle {
|
||||
Superseded,
|
||||
}
|
||||
|
||||
impl Serialize for Lifecycle {
|
||||
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
|
||||
serializer.serialize_str(self.as_str())
|
||||
}
|
||||
}
|
||||
|
||||
impl<'de> Deserialize<'de> for Lifecycle {
|
||||
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
|
||||
let s = String::deserialize(deserializer)?;
|
||||
Ok(Self::parse(&s))
|
||||
}
|
||||
}
|
||||
|
||||
impl Lifecycle {
|
||||
pub fn as_str(&self) -> &'static str {
|
||||
match self {
|
||||
@@ -35,7 +49,7 @@ impl Lifecycle {
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Default)]
|
||||
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
|
||||
pub struct Evidence {
|
||||
pub sources: Vec<String>,
|
||||
pub tests: Vec<String>,
|
||||
@@ -55,7 +69,7 @@ impl Evidence {
|
||||
}
|
||||
|
||||
/// Graded confidence with explanation (not a bare float).
|
||||
#[derive(Debug, Clone)]
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct Confidence {
|
||||
pub level: String, // high | medium | low
|
||||
pub implementation: String,
|
||||
@@ -87,7 +101,7 @@ impl Confidence {
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct RepositoryInfo {
|
||||
pub title: String,
|
||||
pub root: String,
|
||||
@@ -98,7 +112,7 @@ pub struct RepositoryInfo {
|
||||
pub knowledge_count: usize,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct ModuleInfo {
|
||||
pub id: String,
|
||||
pub resource: String,
|
||||
@@ -111,7 +125,7 @@ pub struct ModuleInfo {
|
||||
pub status: Lifecycle,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct SymbolInfo {
|
||||
pub id: String,
|
||||
pub name: String,
|
||||
@@ -135,7 +149,7 @@ pub struct SymbolInfo {
|
||||
pub confidence: Confidence,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct CapabilityInfo {
|
||||
pub id: String,
|
||||
pub name: String,
|
||||
@@ -215,7 +229,20 @@ impl KnowledgeKind {
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
impl Serialize for KnowledgeKind {
|
||||
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
|
||||
serializer.serialize_str(self.as_str())
|
||||
}
|
||||
}
|
||||
|
||||
impl<'de> Deserialize<'de> for KnowledgeKind {
|
||||
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
|
||||
let s = String::deserialize(deserializer)?;
|
||||
Ok(Self::parse(&s))
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct KnowledgeItem {
|
||||
pub id: String,
|
||||
pub kind: KnowledgeKind,
|
||||
@@ -269,9 +296,40 @@ impl EdgeKind {
|
||||
Self::RelatedTo => "related_to",
|
||||
}
|
||||
}
|
||||
|
||||
pub fn parse(s: &str) -> Self {
|
||||
match s.trim() {
|
||||
"implements" => Self::Implements,
|
||||
"uses" => Self::Uses,
|
||||
"depends_on" => Self::DependsOn,
|
||||
"tested_by" => Self::TestedBy,
|
||||
"documented_by" => Self::DocumentedBy,
|
||||
"constrained_by" => Self::ConstrainedBy,
|
||||
"decided_by" => Self::DecidedBy,
|
||||
"supersedes" => Self::Supersedes,
|
||||
"conflicts_with" => Self::ConflictsWith,
|
||||
"deprecated_by" => Self::DeprecatedBy,
|
||||
"derived_from" => Self::DerivedFrom,
|
||||
"failed_by" => Self::FailedBy,
|
||||
_ => Self::RelatedTo,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
impl Serialize for EdgeKind {
|
||||
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
|
||||
serializer.serialize_str(self.as_str())
|
||||
}
|
||||
}
|
||||
|
||||
impl<'de> Deserialize<'de> for EdgeKind {
|
||||
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
|
||||
let s = String::deserialize(deserializer)?;
|
||||
Ok(Self::parse(&s))
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct Edge {
|
||||
pub from: String,
|
||||
pub to: String,
|
||||
@@ -336,7 +394,7 @@ pub struct ReuseResult {
|
||||
pub recommended: Vec<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct KnowledgeGraph {
|
||||
pub repository: RepositoryInfo,
|
||||
pub modules: Vec<ModuleInfo>,
|
||||
|
||||
@@ -20,7 +20,10 @@ pub mod preflight;
|
||||
pub mod reuse;
|
||||
pub mod util;
|
||||
|
||||
pub use compile::{compile, ekc_graph_dir, ensure_compiled, load_graph, KnowledgeOptions};
|
||||
pub use compile::{
|
||||
compile, ekc_graph_dir, ensure_compiled, graph_for_query, ir_snapshot_path, load_graph,
|
||||
KnowledgeOptions,
|
||||
};
|
||||
pub use duplicate::{find_duplicates, format_duplicates_text};
|
||||
pub use find::{find, find_json, format_find_text};
|
||||
pub use impact::{format_impact_text, impact, impact_json};
|
||||
@@ -32,7 +35,9 @@ pub use lifecycle::{
|
||||
};
|
||||
pub use metrics::{load_metrics, record_decision, save_metrics, ReuseMetrics};
|
||||
pub use policy::compile_policy;
|
||||
pub use preflight::{format_preflight_yaml, preflight, preflight_json, PreflightResult};
|
||||
pub use preflight::{
|
||||
format_preflight_yaml, preflight, preflight_from_reuse, preflight_json, PreflightResult,
|
||||
};
|
||||
pub use reuse::{format_reuse_text, resolve, reuse_json, ReuseBudget};
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
@@ -33,6 +33,16 @@ pub fn preflight(
|
||||
out_dir: Option<&Path>,
|
||||
) -> Result<PreflightResult> {
|
||||
let reuse = resolve(graph, task, budget);
|
||||
preflight_from_reuse(graph, task, &reuse, out_dir)
|
||||
}
|
||||
|
||||
/// Build a Context Pack from an already-resolved reuse result (avoids a second `resolve`).
|
||||
pub fn preflight_from_reuse(
|
||||
graph: &KnowledgeGraph,
|
||||
task: &str,
|
||||
reuse: &crate::knowledge::ir::ReuseResult,
|
||||
out_dir: Option<&Path>,
|
||||
) -> Result<PreflightResult> {
|
||||
let intent = reuse
|
||||
.capability
|
||||
.clone()
|
||||
@@ -46,7 +56,7 @@ pub fn preflight(
|
||||
.map(|c| c.title.clone())
|
||||
.collect();
|
||||
|
||||
let pack = render_context_pack(task, &intent, &reuse, graph);
|
||||
let pack = render_context_pack(task, &intent, reuse, graph);
|
||||
let mut context_path = None;
|
||||
if let Some(out) = out_dir {
|
||||
let contexts = out.join("agent/contexts");
|
||||
|
||||
+43
-1
@@ -12,6 +12,7 @@ pub mod binding;
|
||||
pub mod browser_session;
|
||||
pub mod builtin;
|
||||
pub mod bytecode;
|
||||
pub mod call;
|
||||
pub mod capture;
|
||||
#[cfg(feature = "cli")]
|
||||
pub mod catalog;
|
||||
@@ -260,6 +261,23 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
}
|
||||
let bound_call = if let Some(lib_path) = &opts.call_lib_path {
|
||||
let named = named_call_args(opts)?;
|
||||
let segments: Vec<String> = lib_path
|
||||
.split('.')
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string())
|
||||
.collect();
|
||||
let (lib, fun) = crate::interp::locate_import_function(&module, &segments)
|
||||
.map_err(|m| anyhow::anyhow!(m))?;
|
||||
let mut binder = Interpreter::with_capture(Some(path), false).with_host(
|
||||
HostContext::for_capture(Some(path), opts.host_caps()),
|
||||
);
|
||||
let bound = binder.bind_external_args(lib, fun, &named)?;
|
||||
Some((lib_path.clone(), bound))
|
||||
} else {
|
||||
None
|
||||
};
|
||||
let mut vm = Vm::new(Some(path))
|
||||
.with_stdin(stdin_lines)
|
||||
.with_trace(opts.trace_eval)
|
||||
@@ -267,7 +285,21 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
|
||||
if opts.trace_eval {
|
||||
eprintln!("=== marqdo: trace-eval ({path_label}) ===");
|
||||
}
|
||||
let value = vm.run(&program)?;
|
||||
let value = if let Some((lib_path, bound)) = bound_call {
|
||||
let key: Vec<String> = lib_path
|
||||
.split('.')
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string())
|
||||
.collect();
|
||||
let idx = program.path_index.get(&key).copied().ok_or_else(|| {
|
||||
anyhow::anyhow!(
|
||||
"bytecode: `{lib_path}` did not compile to a function; refusing to run the program entry"
|
||||
)
|
||||
})?;
|
||||
vm.call_function(&program, idx, &bound)?
|
||||
} else {
|
||||
vm.run(&program)?
|
||||
};
|
||||
if opts.trace_eval {
|
||||
eprintln!("=== marqdo: end trace-eval ===");
|
||||
}
|
||||
@@ -301,6 +333,16 @@ fn run_call_lib_path(
|
||||
Ok(value)
|
||||
}
|
||||
|
||||
fn named_call_args(opts: &RunOptions) -> Result<Vec<(String, crate::value::Value)>> {
|
||||
let Some(value) = load_args_json(opts)? else {
|
||||
return Ok(Vec::new());
|
||||
};
|
||||
match value {
|
||||
crate::value::Value::Map(pairs) => Ok(pairs),
|
||||
_ => bail!("args-json must be a JSON object"),
|
||||
}
|
||||
}
|
||||
|
||||
fn load_args_json(opts: &RunOptions) -> Result<Option<crate::value::Value>> {
|
||||
let Some(path) = &opts.args_json else {
|
||||
return Ok(None);
|
||||
|
||||
+119
-17
@@ -9,12 +9,12 @@ use marqdo::diagnostics::{Diagnostic, Span};
|
||||
use marqdo::ext_cli::{add_ext, list_ext, remove_ext};
|
||||
use marqdo::input_feed::load_stdin_file;
|
||||
use marqdo::knowledge::{
|
||||
compile_policy, conflicts_json, ensure_compiled, find, find_conflicts, find_duplicates,
|
||||
find_json, find_stale, format_conflicts_text, format_duplicates_text, format_find_text,
|
||||
format_impact_text, format_preflight_yaml, format_reuse_text, format_stale_text,
|
||||
format_verify_text, impact, impact_json, learn, preflight, preflight_json, record_decision,
|
||||
resolve, reuse_json, stale_json, verify, verify_json, write_knowledge, KnowledgeOptions,
|
||||
LearnInput, ReuseBudget,
|
||||
compile_policy, conflicts_json, find, find_conflicts, find_duplicates, find_json, find_stale,
|
||||
format_conflicts_text, format_duplicates_text, format_find_text, format_impact_text,
|
||||
format_preflight_yaml, format_reuse_text, format_stale_text, format_verify_text, graph_for_query,
|
||||
impact, impact_json, learn, preflight_from_reuse, preflight_json, record_decision, resolve,
|
||||
reuse_json, stale_json, verify, verify_json, write_knowledge, KnowledgeOptions, LearnInput,
|
||||
ReuseBudget,
|
||||
};
|
||||
use marqdo::view::{
|
||||
serve, serve_debug, write_capture, write_static, CaptureOptions, DebugOptions, OutputOptions,
|
||||
@@ -137,6 +137,26 @@ enum Commands {
|
||||
#[arg(long)]
|
||||
legacy_markup: bool,
|
||||
},
|
||||
/// Call one function in a `.mq.md` file: `marqdo call <file> <function> name=value`.
|
||||
Call {
|
||||
/// Source file.
|
||||
file: PathBuf,
|
||||
|
||||
/// Function display path, for example `计算器.加法`.
|
||||
function: String,
|
||||
|
||||
/// Named arguments `name=value` (integer, decimal, quoted text, True/False/None).
|
||||
/// A value may be negative (`a=-2`). `--json` and `--backend` remain flags.
|
||||
args: Vec<String>,
|
||||
|
||||
/// Print one JSON object: `{"ok":true,"result":...}` or `{"ok":false,"error":...}`.
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Runtime. Both backends execute the named function.
|
||||
#[arg(long, value_enum, default_value_t = BackendCli::Tree)]
|
||||
backend: BackendCli,
|
||||
},
|
||||
/// Static contract cross-check (渐进式契约): drift, unknown types, misplaced tables
|
||||
Check {
|
||||
/// Program path (.mq.md)
|
||||
@@ -265,6 +285,10 @@ enum Commands {
|
||||
|
||||
#[arg(long, global = true)]
|
||||
json: bool,
|
||||
|
||||
/// Force a full knowledge recompile before query actions (preflight, …)
|
||||
#[arg(long, global = true)]
|
||||
refresh: bool,
|
||||
},
|
||||
/// Find engineering capabilities / symbols / knowledge
|
||||
Find {
|
||||
@@ -282,6 +306,10 @@ enum Commands {
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Force a full knowledge recompile before querying
|
||||
#[arg(long)]
|
||||
refresh: bool,
|
||||
},
|
||||
/// Engineering First Information: REUSE / ADAPT / CREATE
|
||||
Reuse {
|
||||
@@ -306,6 +334,10 @@ enum Commands {
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Force a full knowledge recompile before querying
|
||||
#[arg(long)]
|
||||
refresh: bool,
|
||||
},
|
||||
/// Knowledge impact of changed paths
|
||||
Impact {
|
||||
@@ -320,6 +352,10 @@ enum Commands {
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Force a full knowledge recompile before querying
|
||||
#[arg(long)]
|
||||
refresh: bool,
|
||||
},
|
||||
/// Detect knowledge conflicts / possible duplicates edges
|
||||
Conflicts {
|
||||
@@ -335,6 +371,10 @@ enum Commands {
|
||||
/// Exit non-zero when conflicts found (CI gate; default remains report-only)
|
||||
#[arg(long)]
|
||||
fail: bool,
|
||||
|
||||
/// Force a full knowledge recompile before querying
|
||||
#[arg(long)]
|
||||
refresh: bool,
|
||||
},
|
||||
/// List stale / deprecated / superseded knowledge
|
||||
Stale {
|
||||
@@ -350,6 +390,10 @@ enum Commands {
|
||||
/// Exit non-zero when stale items found (CI gate; default remains report-only)
|
||||
#[arg(long)]
|
||||
fail: bool,
|
||||
|
||||
/// Force a full knowledge recompile before querying
|
||||
#[arg(long)]
|
||||
refresh: bool,
|
||||
},
|
||||
/// Detect duplicate capabilities via symbol fingerprints
|
||||
Duplicate {
|
||||
@@ -368,6 +412,10 @@ enum Commands {
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Force a full knowledge recompile before querying
|
||||
#[arg(long)]
|
||||
refresh: bool,
|
||||
},
|
||||
/// Verify code ↔ knowledge consistency (EKC structural; exit 1 only on errors)
|
||||
Verify {
|
||||
@@ -383,6 +431,10 @@ enum Commands {
|
||||
/// Also fail on warnings (does not change default success-when-no-errors)
|
||||
#[arg(long)]
|
||||
fail_on_warning: bool,
|
||||
|
||||
/// Force a full knowledge recompile before querying
|
||||
#[arg(long)]
|
||||
refresh: bool,
|
||||
},
|
||||
/// Official extension installer (`list` / `add` / `remove`)
|
||||
Ext {
|
||||
@@ -752,6 +804,47 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Call {
|
||||
file,
|
||||
function,
|
||||
args,
|
||||
json,
|
||||
backend,
|
||||
} => {
|
||||
let outcome = (|| -> Result<marqdo::value::Value> {
|
||||
let parsed = marqdo::call::parse_call_args(&args)?;
|
||||
marqdo::call::call_file(&file, &function, &parsed, backend.into())
|
||||
})();
|
||||
match outcome {
|
||||
Ok(value) => {
|
||||
if json {
|
||||
let result = marqdo::value_as_json(&value)
|
||||
.map_err(|e| anyhow::anyhow!(e))?;
|
||||
println!(
|
||||
"{}",
|
||||
serde_json::json!({"ok": true, "result": result})
|
||||
);
|
||||
} else {
|
||||
println!("{}", value.as_display());
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Err(err) => {
|
||||
let diag = Diagnostic::find(&err).cloned().unwrap_or_else(|| {
|
||||
Diagnostic::new(None, Span::new(0, 0), format!("{err:#}")).with_code("call.failed")
|
||||
});
|
||||
if json {
|
||||
println!(
|
||||
"{}",
|
||||
serde_json::json!({"ok": false, "error": diag.to_json()})
|
||||
);
|
||||
} else {
|
||||
eprintln!("error: {diag}");
|
||||
}
|
||||
Ok(1)
|
||||
}
|
||||
}
|
||||
}
|
||||
Commands::Check {
|
||||
file,
|
||||
json,
|
||||
@@ -1235,6 +1328,7 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
path,
|
||||
out,
|
||||
json,
|
||||
refresh,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
match action.unwrap_or(KnowledgeAction::Compile) {
|
||||
@@ -1479,14 +1573,15 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
min_candidates,
|
||||
allow_create_after,
|
||||
} => {
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let graph = graph_for_query(&path, &out, refresh)?;
|
||||
let budget = ReuseBudget {
|
||||
min_candidates,
|
||||
allow_create_after,
|
||||
..ReuseBudget::default()
|
||||
};
|
||||
let pf = preflight(&graph, &task, &budget, Some(&out))?;
|
||||
let _ = compile_policy(&out, &task, &resolve(&graph, &task, &budget));
|
||||
let reuse = resolve(&graph, &task, &budget);
|
||||
let pf = preflight_from_reuse(&graph, &task, &reuse, Some(&out))?;
|
||||
let _ = compile_policy(&out, &task, &reuse);
|
||||
if json {
|
||||
println!("{}", preflight_json(&pf));
|
||||
} else {
|
||||
@@ -1554,9 +1649,10 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
out,
|
||||
limit,
|
||||
json,
|
||||
refresh,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let graph = graph_for_query(&path, &out, refresh)?;
|
||||
let hits = find(&graph, &query, limit);
|
||||
if json {
|
||||
println!("{}", find_json(&query, &hits));
|
||||
@@ -1573,9 +1669,10 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
min_candidates,
|
||||
allow_create_after,
|
||||
json,
|
||||
refresh,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let graph = graph_for_query(&path, &out, refresh)?;
|
||||
let budget = ReuseBudget {
|
||||
min_candidates,
|
||||
allow_create_after,
|
||||
@@ -1584,7 +1681,7 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
let result = resolve(&graph, &task, &budget);
|
||||
let _ = compile_policy(&out, &task, &result);
|
||||
if do_preflight {
|
||||
let _ = preflight(&graph, &task, &budget, Some(&out))?;
|
||||
let _ = preflight_from_reuse(&graph, &task, &result, Some(&out))?;
|
||||
}
|
||||
if json {
|
||||
println!("{}", reuse_json(&task, &result));
|
||||
@@ -1598,8 +1695,9 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
root,
|
||||
out,
|
||||
json,
|
||||
refresh,
|
||||
} => {
|
||||
let graph = ensure_compiled(&root, &out)?;
|
||||
let graph = graph_for_query(&root, &out, refresh)?;
|
||||
let path_strs: Vec<String> = paths
|
||||
.iter()
|
||||
.map(|p| p.to_string_lossy().replace('\\', "/"))
|
||||
@@ -1617,9 +1715,10 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
out,
|
||||
json,
|
||||
fail,
|
||||
refresh,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let graph = graph_for_query(&path, &out, refresh)?;
|
||||
let items = find_conflicts(&graph);
|
||||
if json {
|
||||
println!("{}", conflicts_json(&items));
|
||||
@@ -1633,9 +1732,10 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
out,
|
||||
json,
|
||||
fail,
|
||||
refresh,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let graph = graph_for_query(&path, &out, refresh)?;
|
||||
let items = find_stale(&graph, &path);
|
||||
if json {
|
||||
println!("{}", stale_json(&items));
|
||||
@@ -1650,9 +1750,10 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
threshold,
|
||||
fail,
|
||||
json,
|
||||
refresh,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let graph = graph_for_query(&path, &out, refresh)?;
|
||||
let pairs = find_duplicates(&graph.symbols, threshold);
|
||||
if json {
|
||||
println!(
|
||||
@@ -1682,9 +1783,10 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
out,
|
||||
json,
|
||||
fail_on_warning,
|
||||
refresh,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let graph = graph_for_query(&path, &out, refresh)?;
|
||||
let issues = verify(&graph);
|
||||
if json {
|
||||
println!("{}", verify_json(&issues));
|
||||
|
||||
+26
-33
@@ -77,6 +77,13 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
|
||||
"mlsp.unsupported",
|
||||
"view.document requires the view feature",
|
||||
)),
|
||||
#[cfg(feature = "view")]
|
||||
Some("resource.view") => resource_view(¶ms),
|
||||
#[cfg(not(feature = "view"))]
|
||||
Some("resource.view") => Err(err(
|
||||
"mlsp.unsupported",
|
||||
"resource.view requires the view feature",
|
||||
)),
|
||||
Some("view.reference_resolve") => crate::workbench::resolve_reference(¶ms),
|
||||
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
|
||||
Some("labels.search") => labels_search(¶ms),
|
||||
@@ -84,7 +91,7 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
|
||||
Some("session.summary") => session_summary(),
|
||||
other => Err(err(
|
||||
"mlsp.unknown_method",
|
||||
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.reuse_execute / artifact.patch / artifact.extract_pure / document.extract / capabilities / view.document / view.reference_resolve"),
|
||||
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.reuse_execute / artifact.patch / artifact.extract_pure / document.extract / capabilities / view.document / resource.view / view.reference_resolve"),
|
||||
)),
|
||||
}
|
||||
}
|
||||
@@ -96,6 +103,13 @@ fn view_document(params: &Value) -> Result<Value, Value> {
|
||||
crate::workbench::build_document_view(&req)
|
||||
}
|
||||
|
||||
#[cfg(feature = "view")]
|
||||
fn resource_view(params: &Value) -> Result<Value, Value> {
|
||||
let req = crate::workbench::ResourceViewRequest::from_params(params)
|
||||
.map_err(|e| err("mlsp.bad_request", e))?;
|
||||
crate::workbench::build_resource_view(&req)
|
||||
}
|
||||
|
||||
fn artifact_extract_pure(params: &Value) -> Result<Value, Value> {
|
||||
let name = params
|
||||
.get("name")
|
||||
@@ -819,28 +833,22 @@ fn artifact_execute(params: &Value) -> Result<Value, Value> {
|
||||
let denied: Vec<String> = artifact.effects.values().into_iter().filter(|effect| effect != "pure" && !allowed.contains(&effect.as_str())).collect();
|
||||
if !denied.is_empty() { return Err(json!({"code":"artifact.effect_denied","message":"效果策略拒绝执行","denied":denied,"effects":artifact.effects.values()})); }
|
||||
let path = compilation.semantics.root.join(&artifact.source.file);
|
||||
let module = load::load_module(&path).map_err(|e| diagnostic_err("artifact.load", &e))?;
|
||||
let input = params.get("inputs").cloned().unwrap_or_else(|| json!({}));
|
||||
let object = input.as_object().ok_or_else(|| err("mlsp.bad_request", "inputs 必须是 JSON 对象"))?;
|
||||
let mut args = Vec::new();
|
||||
for (name, value) in object { args.push((name.clone(), crate::host::json::json_to_value(value).map_err(|e| err("mlsp.bad_input", e))?)); }
|
||||
let caps = crate::host::HostCaps { fs_write: allowed.contains(&"fs.write"), exec: allowed.iter().any(|e| matches!(*e, "process.exec" | "plugin.call" | "llm.call")), net: allowed.iter().any(|e| matches!(*e, "network.read" | "network.write" | "llm.call")), plugin: allowed.contains(&"plugin.call") };
|
||||
let host = crate::host::HostContext::for_capture(Some(&path), caps);
|
||||
let mut interpreter = crate::interp::Interpreter::with_capture(Some(&path), false).with_host(host);
|
||||
// Bind by source line / declaration identity — never by bare display_name suffix (G07).
|
||||
let fun = find_function_at_line(&module.functions, artifact.source.line).ok_or_else(|| {
|
||||
err(
|
||||
"artifact.unresolved",
|
||||
format!(
|
||||
"无法在 {}:{} 定位绑定函数 {}",
|
||||
artifact.source.file, artifact.source.line, artifact.display_name
|
||||
),
|
||||
)
|
||||
})?;
|
||||
let value = interpreter
|
||||
.invoke_bound_function(&module, fun, &args)
|
||||
.map_err(|e| diagnostic_err("artifact.execution_failed", &e))?;
|
||||
let stdout = std::mem::take(&mut interpreter.captured_stdout);
|
||||
// Same line identity, argument binding, and runtime as `marqdo call`.
|
||||
let (value, stdout) = crate::call::execute_source_function(
|
||||
&path,
|
||||
artifact.source.line,
|
||||
&artifact.display_name,
|
||||
&args,
|
||||
caps,
|
||||
crate::Backend::Tree,
|
||||
false,
|
||||
)
|
||||
.map_err(|e| diagnostic_err("artifact.execution_failed", &e))?;
|
||||
Ok(json!({
|
||||
"schema_version": 1,
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
@@ -852,21 +860,6 @@ fn artifact_execute(params: &Value) -> Result<Value, Value> {
|
||||
}))
|
||||
}
|
||||
|
||||
fn find_function_at_line<'a>(
|
||||
functions: &'a [crate::ast::Function],
|
||||
line: u32,
|
||||
) -> Option<&'a crate::ast::Function> {
|
||||
for fun in functions {
|
||||
if fun.span.line == line {
|
||||
return Some(fun);
|
||||
}
|
||||
if let Some(found) = find_function_at_line(&fun.children, line) {
|
||||
return Some(found);
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn err(code: &str, message: impl Into<String>) -> Value {
|
||||
json!({"code": code, "message": message.into()})
|
||||
}
|
||||
|
||||
@@ -891,6 +891,24 @@ impl<'a> Cursor<'a> {
|
||||
if !header_done {
|
||||
bail!("expected GFM table after empty assignment");
|
||||
}
|
||||
// Strong / Surface: unequal row arity is stuck — no silent pad/truncate.
|
||||
for (line_no, cells) in &data_rows {
|
||||
if cells.len() != header.len() {
|
||||
return Err(Diagnostic::new(
|
||||
None,
|
||||
Span {
|
||||
line: *line_no,
|
||||
col: 1,
|
||||
},
|
||||
format!(
|
||||
"table row arity mismatch: expected {} columns, got {}",
|
||||
header.len(),
|
||||
cells.len()
|
||||
),
|
||||
)
|
||||
.into());
|
||||
}
|
||||
}
|
||||
let row_oriented = header
|
||||
.first()
|
||||
.map(|h| is_row_table_marker(h))
|
||||
|
||||
+64
-6
@@ -8,7 +8,7 @@ use std::collections::{BTreeMap, BTreeSet};
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use anyhow::{Context, Result};
|
||||
use anyhow::{bail, Context, Result};
|
||||
use serde_json::{json, Value};
|
||||
use sha2::{Digest as _, Sha256};
|
||||
|
||||
@@ -240,10 +240,20 @@ pub struct Compilation {
|
||||
/// side-effect free: it never loads plugins, evaluates expressions or fetches
|
||||
/// sources.
|
||||
pub fn compile_project(options: &CompileOptions) -> Result<Compilation> {
|
||||
let t_index = std::time::Instant::now();
|
||||
let root = ProjectRoot::new(&options.project_root)?;
|
||||
let index = ProjectIndex::build(root.clone())?;
|
||||
let index_ms = t_index.elapsed().as_millis();
|
||||
compile_index(ProjectIndex::build(root)?)
|
||||
}
|
||||
|
||||
/// Compile `entry` and the modules it imports. Sibling files in the directory are not included.
|
||||
pub fn compile_file_closure(entry: &Path) -> Result<Compilation> {
|
||||
let files = import_closure(entry)?;
|
||||
let ancestor = common_ancestor(&files)?;
|
||||
let root = ProjectRoot::new(&ancestor)?;
|
||||
compile_index(ProjectIndex::from_files(root, files)?)
|
||||
}
|
||||
|
||||
fn compile_index(index: ProjectIndex) -> Result<Compilation> {
|
||||
let root = index.root().clone();
|
||||
// Reuse parsed modules from ProjectIndex — same input snapshot, no second parse (M-R5b).
|
||||
let mut files = BTreeMap::new();
|
||||
let mut diagnostics = Vec::new();
|
||||
@@ -257,8 +267,6 @@ pub fn compile_project(options: &CompileOptions) -> Result<Compilation> {
|
||||
),
|
||||
);
|
||||
}
|
||||
let _ = index_ms; // ProjectIndex build duration (M-R5b span)
|
||||
|
||||
// Wire import_modules from already-parsed project files so BoundCall path
|
||||
// resolve shares `resolve_for_exec` (no plugin load / no re-parse).
|
||||
attach_project_imports(&mut files);
|
||||
@@ -349,6 +357,56 @@ pub fn compile_project(options: &CompileOptions) -> Result<Compilation> {
|
||||
})
|
||||
}
|
||||
|
||||
fn import_closure(entry: &Path) -> Result<Vec<PathBuf>> {
|
||||
let mut out = Vec::new();
|
||||
let mut seen = std::collections::HashSet::new();
|
||||
fn walk(path: &Path, out: &mut Vec<PathBuf>, seen: &mut std::collections::HashSet<PathBuf>) -> Result<()> {
|
||||
if !path.is_file() {
|
||||
return Ok(());
|
||||
}
|
||||
let canon = path.canonicalize().with_context(|| format!("resolve {}", path.display()))?;
|
||||
if !seen.insert(canon.clone()) {
|
||||
return Ok(());
|
||||
}
|
||||
out.push(canon.clone());
|
||||
let source = fs::read_to_string(&canon).with_context(|| format!("read {}", canon.display()))?;
|
||||
let module = crate::load::parse_source_auto(&source)
|
||||
.with_context(|| format!("parse {}", canon.display()))?;
|
||||
let base = canon.parent().unwrap_or_else(|| Path::new("."));
|
||||
for imp in &module.imports {
|
||||
let dep = crate::load::resolve_import(base, &imp.path)
|
||||
.with_context(|| format!("import `{}` from {}", imp.path, canon.display()))?;
|
||||
walk(&dep, out, seen)?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
if !entry.is_file() {
|
||||
bail!("call target {} is not a file", entry.display());
|
||||
}
|
||||
walk(entry, &mut out, &mut seen)?;
|
||||
out.sort();
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
fn common_ancestor(files: &[PathBuf]) -> Result<PathBuf> {
|
||||
let Some(first) = files.first() else {
|
||||
bail!("call target has no source files");
|
||||
};
|
||||
let mut ancestor = first
|
||||
.parent()
|
||||
.map(|p| p.to_path_buf())
|
||||
.unwrap_or_else(|| PathBuf::from("."));
|
||||
for file in files.iter().skip(1) {
|
||||
while !file.starts_with(&ancestor) {
|
||||
ancestor = ancestor
|
||||
.parent()
|
||||
.map(|p| p.to_path_buf())
|
||||
.ok_or_else(|| anyhow::anyhow!("source files have no common directory"))?;
|
||||
}
|
||||
}
|
||||
Ok(ancestor)
|
||||
}
|
||||
|
||||
fn module_artifact(index: &ProjectIndex, module: &ModuleId, path: &Path, text: &str) -> SemanticArtifact {
|
||||
let implementation = digest(normalize_source(text));
|
||||
let interface = digest(module.as_str());
|
||||
|
||||
+2
-1
@@ -16,7 +16,8 @@ pub use bind::{
|
||||
};
|
||||
pub use extract::{plan_pure_extract, ExtractError, ExtractPlan};
|
||||
pub use ir::{
|
||||
artifact_json, compile_project, semantic_generation_dir, write_semantic_projections, ArtifactId,
|
||||
artifact_json, compile_file_closure, compile_project, semantic_generation_dir,
|
||||
write_semantic_projections, ArtifactId,
|
||||
BoundCall, CompileOptions, Compilation, Digest, DynamicCall, EffectSet, LockMode,
|
||||
SemanticArtifact, SemanticProject,
|
||||
};
|
||||
|
||||
+6
-1
@@ -119,8 +119,13 @@ pub struct ProjectIndex {
|
||||
|
||||
impl ProjectIndex {
|
||||
pub fn build(root: ProjectRoot) -> Result<Self> {
|
||||
let project_id = project_id(root.path());
|
||||
let files = root.source_files()?;
|
||||
Self::from_files(root, files)
|
||||
}
|
||||
|
||||
/// Index exactly `files` (already chosen by the caller). Paths must sit under `root`.
|
||||
pub fn from_files(root: ProjectRoot, files: Vec<PathBuf>) -> Result<Self> {
|
||||
let project_id = project_id(root.path());
|
||||
let mut modules = BTreeMap::new();
|
||||
let mut path_to_module = BTreeMap::new();
|
||||
let mut symbols = Vec::new();
|
||||
|
||||
@@ -29,6 +29,8 @@ pub enum Value {
|
||||
Code(CodeBlock),
|
||||
/// Sensitive text from `${secret.*}` — Display shows `<secret>`; reveal on Text concat.
|
||||
Secret(String),
|
||||
/// Opaque foreign-session handle. Not JSON-serializable; not printable structure.
|
||||
Handle(String),
|
||||
}
|
||||
|
||||
impl Value {
|
||||
@@ -40,6 +42,7 @@ impl Value {
|
||||
Value::Num(n) => *n != 0.0 && !n.is_nan(),
|
||||
Value::Text(s) => !s.is_empty(),
|
||||
Value::Secret(s) => !s.is_empty(),
|
||||
Value::Handle(s) => !s.is_empty(),
|
||||
Value::List(xs) => !xs.is_empty(),
|
||||
Value::Map(xs) => !xs.is_empty(),
|
||||
Value::Formula(_) => true,
|
||||
@@ -64,6 +67,7 @@ impl Value {
|
||||
Value::Num(n) => crate::formula::format_num(*n),
|
||||
Value::Text(s) => s.clone(),
|
||||
Value::Secret(_) => "<secret>".into(),
|
||||
Value::Handle(_) => "<handle>".into(),
|
||||
Value::List(xs) => {
|
||||
let parts: Vec<String> = xs.iter().map(|v| v.as_display()).collect();
|
||||
format!("[{}]", parts.join(", "))
|
||||
|
||||
@@ -916,6 +916,17 @@ fn render_line_block(
|
||||
if let Some(body) = writeback_body {
|
||||
s.push_str(&crate::view::render::render_output_card(line_no, body));
|
||||
}
|
||||
// Must close `.doc-block` — an early return left the wrapper open and
|
||||
// nested the Functions/Variables outline under the document surface.
|
||||
let band_annots: Vec<ViewAnnot> = annots
|
||||
.iter()
|
||||
.filter(|a| !is_noisy_result_chip(a))
|
||||
.map(|a| (*a).clone())
|
||||
.collect();
|
||||
if !band_annots.is_empty() {
|
||||
s.push_str(&render_annot_band(&band_annots, MAX_VISIBLE_ANNOTS));
|
||||
}
|
||||
s.push_str("</div>");
|
||||
return s;
|
||||
}
|
||||
if bits.is_empty() {
|
||||
@@ -1545,6 +1556,52 @@ When we meet `who`, we **print text="Hi, `who`!"** and close with*None*.
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod occl_render_tests {
|
||||
use super::render_module_document;
|
||||
|
||||
fn div_balance(html: &str) -> i32 {
|
||||
let mut depth = 0i32;
|
||||
let b = html.as_bytes();
|
||||
let mut i = 0usize;
|
||||
while i + 3 < b.len() {
|
||||
if b[i] == b'<' {
|
||||
if i + 4 <= b.len() && &b[i..i + 4] == b"<div" && (b.get(i + 4) == Some(&b' ') || b.get(i + 4) == Some(&b'>')) {
|
||||
depth += 1;
|
||||
} else if i + 6 <= b.len() && &b[i..i + 6] == b"</div>" {
|
||||
depth -= 1;
|
||||
}
|
||||
}
|
||||
i += 1;
|
||||
}
|
||||
depth
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn occlusion_line_closes_doc_block() {
|
||||
let src = r#"---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`v` = [描述](1)
|
||||
"#;
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_document(&module, src, &[]);
|
||||
assert!(html.contains("doc-occl"), "{html}");
|
||||
assert_eq!(
|
||||
div_balance(&html),
|
||||
0,
|
||||
"occlusion must not leave .doc-block open: {html}"
|
||||
);
|
||||
assert!(
|
||||
html.contains("doc-occl") && html.contains("</div></div>"),
|
||||
"doc-block around occlusion must close: {html}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod occl_split_tests {
|
||||
use super::split_occlusion;
|
||||
|
||||
+34
-2
@@ -237,6 +237,11 @@ a:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
|
||||
min-width: 0;
|
||||
overflow: auto;
|
||||
background: var(--bg);
|
||||
/* Content-pane width (excludes file nav) drives outline stacking — not the
|
||||
* viewport. A 960px viewport media query wrongly put Functions/Variables
|
||||
* under a tall Structure while the left nav was still visible. */
|
||||
container-type: inline-size;
|
||||
container-name: mq-panel;
|
||||
}
|
||||
main.panel {
|
||||
padding: 2rem 2.25rem 3.5rem;
|
||||
@@ -719,9 +724,17 @@ body.notebook-page .exec-clear:hover { border-color: var(--nb-accent); color: va
|
||||
gap: 0.75rem;
|
||||
align-items: start;
|
||||
}
|
||||
@media (max-width: 960px) {
|
||||
/* Stack only when the *panel* is too narrow for Structure + outline rail.
|
||||
* Prefer keeping the rail beside the doc at tablet widths (matches ≤800px
|
||||
* shell collapse in doc/design/view.md). When stacked, pull the rail above
|
||||
* so it is not buried under a long document. */
|
||||
@container mq-panel (max-width: 32rem) {
|
||||
.struct-wrap { grid-template-columns: 1fr; }
|
||||
.outline-rail, .outline-panel { position: static; }
|
||||
.outline-rail {
|
||||
order: -1;
|
||||
position: static;
|
||||
}
|
||||
.outline-panel { position: static; }
|
||||
}
|
||||
.outline-rail {
|
||||
position: sticky;
|
||||
@@ -4527,6 +4540,25 @@ mod plan_card_tests {
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn outline_rail_stacks_by_panel_container_not_960_viewport() {
|
||||
let css = stylesheet();
|
||||
assert!(
|
||||
css.contains("container-name: mq-panel"),
|
||||
"panel-wrap should be a size container for outline layout"
|
||||
);
|
||||
assert!(
|
||||
css.contains("@container mq-panel (max-width: 32rem)"),
|
||||
"outline must stack from panel width, not a mid-width viewport media query"
|
||||
);
|
||||
assert!(
|
||||
!css.contains("@media (max-width: 960px) {\n .struct-wrap"),
|
||||
"960px viewport media wrongly buried the outline under Structure"
|
||||
);
|
||||
let html = layout("t", "<p>nav</p>", "<p>main</p>");
|
||||
assert!(html.contains("container-name: mq-panel"), "{html}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn notebook_ui_has_controls() {
|
||||
let ui = notebook_ui();
|
||||
|
||||
@@ -199,6 +199,7 @@ const API_ROUTES: &[(&str, ApiRoute)] = &[
|
||||
("/api/session/snapshot/export", ApiRoute::Notebook(notebook_api::api_export_snapshot)),
|
||||
("/api/session/snapshot/import", ApiRoute::Notebook(notebook_api::api_import_snapshot)),
|
||||
("/api/session/snapshot/replay", ApiRoute::Notebook(notebook_api::api_replay_snapshot)),
|
||||
("/api/session/snapshot/replay_check", ApiRoute::Notebook(notebook_api::api_replay_check)),
|
||||
("/api/session/plan/assign", ApiRoute::Notebook(notebook_api::api_plan_assign)),
|
||||
("/api/session/plan/add", ApiRoute::Notebook(notebook_api::api_plan_add)),
|
||||
("/api/session/plan/remove", ApiRoute::Notebook(notebook_api::api_plan_remove)),
|
||||
@@ -216,6 +217,7 @@ const API_ROUTES: &[(&str, ApiRoute)] = &[
|
||||
("/api/session/state/push", ApiRoute::Notebook(notebook_api::api_state_push)),
|
||||
("/api/session/state/pull", ApiRoute::Notebook(notebook_api::api_state_pull)),
|
||||
("/api/session/journal", ApiRoute::Notebook(notebook_api::api_journal)),
|
||||
("/api/session/oracle_journal", ApiRoute::Notebook(notebook_api::api_oracle_journal)),
|
||||
("/api/debug/start", ApiRoute::Notebook(debug_api::api_debug_start)),
|
||||
("/api/debug/continue", ApiRoute::Action(crate::debug::DebugAction::Continue)),
|
||||
("/api/debug/step", ApiRoute::Action(crate::debug::DebugAction::Step)),
|
||||
|
||||
@@ -208,6 +208,16 @@ pub fn api_replay_snapshot(root: &Path, body: &str) -> serde_json::Value {
|
||||
with_session(root, body, "replay", |s| s.replay_snapshot(&snapshot))
|
||||
}
|
||||
|
||||
pub fn api_replay_check(root: &Path, body: &str) -> serde_json::Value {
|
||||
let v = body_value(body);
|
||||
let snapshot = v.get("snapshot").cloned().unwrap_or(serde_json::Value::Null);
|
||||
let snapshot = match json_to_value(&snapshot) {
|
||||
Ok(v) => v,
|
||||
Err(e) => return err(e),
|
||||
};
|
||||
with_session(root, body, "replay_check", |s| s.replay_check(&snapshot))
|
||||
}
|
||||
|
||||
pub fn api_clear_cell(root: &Path, body: &str) -> serde_json::Value {
|
||||
let v = body_value(body);
|
||||
let cell = v.get("cell").and_then(|x| x.as_str()).unwrap_or("");
|
||||
@@ -352,6 +362,10 @@ pub fn api_journal(root: &Path, body: &str) -> serde_json::Value {
|
||||
with_session(root, body, "journal", |s| Ok(s.journal_json()))
|
||||
}
|
||||
|
||||
pub fn api_oracle_journal(root: &Path, body: &str) -> serde_json::Value {
|
||||
with_session(root, body, "oracle_journal", |s| Ok(s.oracle_journal_json()))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
@@ -542,6 +542,7 @@ fn value_kind_label(v: &crate::value::Value) -> String {
|
||||
Value::Num(_) => "num".into(),
|
||||
Value::Text(_) => "text".into(),
|
||||
Value::Secret(_) => "secret".into(),
|
||||
Value::Handle(_) => "handle".into(),
|
||||
Value::Formula(crate::formula::Expr::Matrix { rows, .. }) => {
|
||||
format!("formula · {}×{}", rows.len(), rows.first().map(|r| r.len()).unwrap_or(0))
|
||||
}
|
||||
|
||||
@@ -47,6 +47,14 @@ pub fn probe_capabilities(params: &Value) -> Value {
|
||||
json!({"format": "pdf", "available": false}),
|
||||
json!({"format": "docx", "available": false}),
|
||||
json!({"format": "ocr", "available": false}),
|
||||
// M-A0 freeze: format matrix rows remain unavailable until M-A3/M-A5.
|
||||
json!({"format": "json", "available": true}),
|
||||
json!({"format": "csv", "available": true}),
|
||||
json!({"format": "image", "available": false}),
|
||||
json!({"format": "html", "available": false}),
|
||||
json!({"format": "svg", "available": false}),
|
||||
json!({"format": "xlsx", "available": false}),
|
||||
json!({"format": "pptx", "available": false}),
|
||||
];
|
||||
|
||||
let loaded_plugins = probe_loaded_plugins(params);
|
||||
@@ -95,7 +103,8 @@ pub fn probe_capabilities(params: &Value) -> Value {
|
||||
// task_control_v2 / event_replay: host_query("runtime") + /_runtime/* system routes.
|
||||
features.insert("runtime.task_control_v2".into(), json!(1));
|
||||
features.insert("runtime.event_replay".into(), json!(1));
|
||||
features.insert("runtime.read_lane".into(), json!(0));
|
||||
// short/read/control HTTP invokes use isolated admission (no parent INVOKE_LOCK).
|
||||
features.insert("runtime.read_lane".into(), json!(1));
|
||||
#[cfg(feature = "view")]
|
||||
{
|
||||
features.insert("view.analysis_cache_v2".into(), json!(1));
|
||||
@@ -108,6 +117,20 @@ pub fn probe_capabilities(params: &Value) -> Value {
|
||||
features.insert("view.document".into(), json!(0));
|
||||
features.insert("view.reference_resolve".into(), json!(0));
|
||||
}
|
||||
// M-A0–M-A4: protocol capability bits.
|
||||
features.insert("agent.error_v1".into(), json!(1));
|
||||
features.insert("agent.checkpoint_v2".into(), json!(1));
|
||||
features.insert("agent.tool_schema_v1".into(), json!(1));
|
||||
features.insert("agent.output_channels_v1".into(), json!(1));
|
||||
features.insert("agent.context_pack_v2".into(), json!(1));
|
||||
#[cfg(feature = "view")]
|
||||
{
|
||||
features.insert("resource.view_v1".into(), json!(1));
|
||||
}
|
||||
#[cfg(not(feature = "view"))]
|
||||
{
|
||||
features.insert("resource.view_v1".into(), json!(0));
|
||||
}
|
||||
|
||||
json!({
|
||||
"schema_version": 1,
|
||||
@@ -220,5 +243,14 @@ mod tests {
|
||||
assert_eq!(caps["features"]["runtime.event_stream"], 0);
|
||||
assert_eq!(caps["features"]["runtime.cancel"], 0);
|
||||
assert_eq!(caps["features"]["llm.messages"], 0);
|
||||
assert_eq!(caps["features"]["agent.error_v1"], 1);
|
||||
assert_eq!(caps["features"]["agent.checkpoint_v2"], 1);
|
||||
assert_eq!(caps["features"]["agent.tool_schema_v1"], 1);
|
||||
assert_eq!(caps["features"]["agent.output_channels_v1"], 1);
|
||||
assert_eq!(caps["features"]["agent.context_pack_v2"], 1);
|
||||
#[cfg(feature = "view")]
|
||||
assert_eq!(caps["features"]["resource.view_v1"], 1);
|
||||
#[cfg(not(feature = "view"))]
|
||||
assert_eq!(caps["features"]["resource.view_v1"], 0);
|
||||
}
|
||||
}
|
||||
@@ -10,6 +10,8 @@ pub mod capabilities;
|
||||
pub mod document_view;
|
||||
pub mod event_sink;
|
||||
pub mod locator;
|
||||
#[cfg(feature = "view")]
|
||||
pub mod resource_view;
|
||||
pub mod run_context;
|
||||
pub mod selection;
|
||||
pub mod snapshot;
|
||||
@@ -24,6 +26,8 @@ pub use capabilities::probe_capabilities;
|
||||
#[cfg(feature = "view")]
|
||||
pub use document_view::{build_document_view, DocumentViewRequest};
|
||||
pub use event_sink::{bind_event_sink, clear_event_sink, emit_event, emit_message_delta};
|
||||
#[cfg(feature = "view")]
|
||||
pub use resource_view::{build_resource_view, ResourceViewRequest};
|
||||
pub use locator::{resolve_reference, KnowledgeLocator};
|
||||
pub use run_context::{
|
||||
cancel_requested, cancel_token_body_means_cancel, RequestContext, RunContext,
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,11 @@
|
||||
# 甲
|
||||
|
||||
## 加法
|
||||
|
||||
*[计算结果](1)*
|
||||
|
||||
# 乙
|
||||
|
||||
## 加法
|
||||
|
||||
*[计算结果](2)*
|
||||
@@ -0,0 +1,11 @@
|
||||
# 校验
|
||||
|
||||
## 加一
|
||||
|
||||
对于输入变量`n`,期望是数字。
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| n | 数值 | 输入值 |
|
||||
|
||||
*[结果](n + 1)*
|
||||
@@ -0,0 +1,13 @@
|
||||
# 危险
|
||||
|
||||
## 写入
|
||||
|
||||
> fs.write_text path=sent.txt text=no
|
||||
|
||||
*None*
|
||||
|
||||
## 联网
|
||||
|
||||
> net.http_post url="http://127.0.0.1:9/nope" body="{}"
|
||||
|
||||
*None*
|
||||
@@ -0,0 +1,5 @@
|
||||
## 加一
|
||||
|
||||
给定`n`。
|
||||
|
||||
*[结果](n + 1)*
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
import:
|
||||
inc: inc.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*0*
|
||||
|
||||
# 包装
|
||||
|
||||
## 再加一
|
||||
|
||||
给定`n`。
|
||||
|
||||
**结果 = [调用增量](inc.加一(n=n))**
|
||||
*结果*
|
||||
@@ -0,0 +1,11 @@
|
||||
# main
|
||||
|
||||
*0*
|
||||
|
||||
# 计算器
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
runtime: markdown
|
||||
tools: 计算器.加法
|
||||
---
|
||||
|
||||
# 计算器
|
||||
|
||||
这份文件不是 SKILL。`runtime` 和 `tools` 不参与调用。
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
@@ -0,0 +1,7 @@
|
||||
# 点
|
||||
|
||||
## 横坐标
|
||||
|
||||
读取`self`。
|
||||
|
||||
*[结果](self)*
|
||||
@@ -0,0 +1,219 @@
|
||||
//! `marqdo call` runs one function. These tests start the real binary.
|
||||
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::Command;
|
||||
|
||||
fn bin() -> &'static str {
|
||||
env!("CARGO_BIN_EXE_marqdo")
|
||||
}
|
||||
|
||||
fn root() -> PathBuf {
|
||||
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
}
|
||||
|
||||
fn run(args: &[&str]) -> std::process::Output {
|
||||
Command::new(bin())
|
||||
.args(args)
|
||||
.current_dir(root())
|
||||
.output()
|
||||
.expect("spawn marqdo")
|
||||
}
|
||||
|
||||
fn text(bytes: &[u8]) -> String {
|
||||
String::from_utf8_lossy(bytes).trim().to_string()
|
||||
}
|
||||
|
||||
fn assert_value(file: &Path, function: &str, args: &[&str], backend: &str, expect: &str) {
|
||||
let file = file.to_str().unwrap();
|
||||
let mut cmd = vec!["call", "--backend", backend, file, function];
|
||||
cmd.extend_from_slice(args);
|
||||
let out = run(&cmd);
|
||||
assert_eq!(
|
||||
out.status.code(),
|
||||
Some(0),
|
||||
"backend={backend} stdout={} stderr={}",
|
||||
text(&out.stdout),
|
||||
text(&out.stderr)
|
||||
);
|
||||
assert_eq!(text(&out.stdout), expect, "backend={backend}");
|
||||
}
|
||||
|
||||
fn assert_code(file: &Path, function: &str, args: &[&str], code: &str) {
|
||||
let file = file.to_str().unwrap();
|
||||
let mut cmd = vec!["call", "--json", file, function];
|
||||
cmd.extend_from_slice(args);
|
||||
let out = run(&cmd);
|
||||
assert_ne!(out.status.code(), Some(0), "stdout={}", text(&out.stdout));
|
||||
let body: serde_json::Value = serde_json::from_str(&text(&out.stdout)).unwrap_or_else(|e| {
|
||||
panic!("json stdout: {e}\n{}", text(&out.stdout));
|
||||
});
|
||||
assert_eq!(body["ok"], false, "{body}");
|
||||
assert_eq!(body["error"]["code"], code, "{body}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn calculator_matches_the_documented_examples() {
|
||||
let file = root().join("examples/calculator.mq.md");
|
||||
for backend in ["tree", "bytecode"] {
|
||||
assert_value(&file, "计算器.加法", &["a=2", "b=3"], backend, "5");
|
||||
assert_value(&file, "计算器.加法", &["a=-2", "b=3"], backend, "1");
|
||||
assert_value(&file, "计算器.乘法", &["a=4", "b=6"], backend, "24");
|
||||
assert_value(&file, "计算器.乘法", &["a=0", "b=100"], backend, "0");
|
||||
assert_value(&file, "加法", &["a=2", "b=3"], backend, "5");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn symbol_id_selects_the_same_function_on_both_backends() {
|
||||
let file = root().join("examples/calculator.mq.md");
|
||||
let compiled = marqdo::sema::compile_file_closure(&file).expect("compile calculator");
|
||||
let artifact = compiled
|
||||
.semantics
|
||||
.artifacts
|
||||
.iter()
|
||||
.find(|artifact| artifact.display_name == "计算器.加法")
|
||||
.expect("加法 artifact");
|
||||
let id = artifact
|
||||
.symbol_id
|
||||
.as_ref()
|
||||
.expect("symbol id")
|
||||
.as_str()
|
||||
.to_string();
|
||||
let args = vec![
|
||||
("a".to_string(), marqdo::value::Value::Int(2)),
|
||||
("b".to_string(), marqdo::value::Value::Int(3)),
|
||||
];
|
||||
for backend in [marqdo::Backend::Tree, marqdo::Backend::Bytecode] {
|
||||
let value = marqdo::call::call_file(&file, &id, &args, backend).unwrap_or_else(|err| {
|
||||
panic!("symbol id call failed on {backend:?}: {err:#}")
|
||||
});
|
||||
assert_eq!(value, marqdo::value::Value::Int(5));
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn json_envelope_and_metadata_are_not_a_skill_gate() {
|
||||
let file = root().join("tests/call/metadata.mq.md");
|
||||
let out = run(&[
|
||||
"call",
|
||||
"--json",
|
||||
file.to_str().unwrap(),
|
||||
"计算器.加法",
|
||||
"a=2",
|
||||
"b=3",
|
||||
]);
|
||||
assert_eq!(out.status.code(), Some(0), "{}", text(&out.stderr));
|
||||
let body: serde_json::Value = serde_json::from_str(&text(&out.stdout)).unwrap();
|
||||
assert_eq!(body, serde_json::json!({"ok": true, "result": 5}));
|
||||
|
||||
let trailing = run(&[
|
||||
"call",
|
||||
file.to_str().unwrap(),
|
||||
"计算器.加法",
|
||||
"a=2",
|
||||
"b=3",
|
||||
"--backend",
|
||||
"bytecode",
|
||||
"--json",
|
||||
]);
|
||||
assert_eq!(trailing.status.code(), Some(0), "{}", text(&trailing.stderr));
|
||||
let body: serde_json::Value = serde_json::from_str(&text(&trailing.stdout)).unwrap();
|
||||
assert_eq!(body, serde_json::json!({"ok": true, "result": 5}));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bytecode_does_not_run_main() {
|
||||
let file = root().join("tests/call/main-split.mq.md");
|
||||
for backend in ["tree", "bytecode"] {
|
||||
assert_value(&file, "计算器.加法", &["a=2", "b=3"], backend, "5");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn missing_unknown_and_contract_args_are_structured() {
|
||||
let calc = root().join("examples/calculator.mq.md");
|
||||
assert_code(&calc, "没有这个函数", &[], "artifact.unresolved");
|
||||
assert_code(&calc, "计算器.加法", &["a=2"], "call.missing_arg");
|
||||
assert_code(
|
||||
&calc,
|
||||
"计算器.加法",
|
||||
&["a=2", "b=3", "c=1"],
|
||||
"call.unknown_arg",
|
||||
);
|
||||
let contract = root().join("tests/call/contract.mq.md");
|
||||
assert_code(&contract, "校验.加一", &["n=True"], "contract.arg_mismatch");
|
||||
assert_value(&contract, "校验.加一", &["n=3"], "tree", "4");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn same_short_name_is_ambiguous() {
|
||||
let file = root().join("tests/call/ambiguous.mq.md");
|
||||
assert_code(&file, "加法", &[], "artifact.ambiguous");
|
||||
assert_value(&file, "甲.加法", &[], "tree", "1");
|
||||
assert_value(&file, "乙.加法", &[], "bytecode", "2");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn instance_method_is_refused() {
|
||||
let file = root().join("tests/call/method.mq.md");
|
||||
assert_code(&file, "点.横坐标", &[], "artifact.not_executable");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn import_is_executed_and_call_lib_path_stays_on_bytecode() {
|
||||
let site = root().join("tests/call/import/site.mq.md");
|
||||
for backend in ["tree", "bytecode"] {
|
||||
assert_value(&site, "包装.再加一", &["n=4"], backend, "5");
|
||||
}
|
||||
let tmp = std::env::temp_dir().join(format!("mq-call-lib-{}", std::process::id()));
|
||||
let _ = fs::remove_dir_all(&tmp);
|
||||
fs::create_dir_all(&tmp).unwrap();
|
||||
let args = tmp.join("args.json");
|
||||
let emit = tmp.join("out.json");
|
||||
fs::write(&args, r#"{"n":4}"#).unwrap();
|
||||
let out = Command::new(bin())
|
||||
.args([
|
||||
"run",
|
||||
site.to_str().unwrap(),
|
||||
"--backend",
|
||||
"bytecode",
|
||||
"--call-lib-path",
|
||||
"inc.加一",
|
||||
"--args-json",
|
||||
args.to_str().unwrap(),
|
||||
"--emit-result",
|
||||
emit.to_str().unwrap(),
|
||||
])
|
||||
.current_dir(root())
|
||||
.output()
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
out.status.code(),
|
||||
Some(0),
|
||||
"stderr={} stdout={}",
|
||||
text(&out.stderr),
|
||||
text(&out.stdout)
|
||||
);
|
||||
assert_eq!(fs::read_to_string(&emit).unwrap().trim(), "5");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn impure_calls_do_not_run() {
|
||||
let src = root().join("tests/call/effects.mq.md");
|
||||
let dir = std::env::temp_dir().join(format!("mq-call-fx-{}", std::process::id()));
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
let file = dir.join("effects.mq.md");
|
||||
fs::copy(&src, &file).unwrap();
|
||||
for function in ["危险.写入", "危险.联网"] {
|
||||
let out = run(&["call", "--json", file.to_str().unwrap(), function]);
|
||||
assert_ne!(out.status.code(), Some(0), "{function} {}", text(&out.stdout));
|
||||
let body: serde_json::Value = serde_json::from_str(&text(&out.stdout)).unwrap();
|
||||
assert_eq!(body["error"]["code"], "artifact.effect_denied", "{body}");
|
||||
}
|
||||
assert!(
|
||||
!dir.join("sent.txt").exists(),
|
||||
"denied write must not create sent.txt"
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: table row arity mismatch is a fault
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`t` =
|
||||
|
||||
| a | b |
|
||||
|---|---|
|
||||
| 1 | 2 |
|
||||
| 3 |
|
||||
|
||||
> print text=`t`
|
||||
@@ -1417,6 +1417,56 @@ fn m05_skill_front_has_occlusion_core_not_classic_index() {
|
||||
root.join("skills/marqdo/migration-classic.md").is_file(),
|
||||
"Classic rules must live in migration-classic.md"
|
||||
);
|
||||
for rel in ["skills/marqdo/SKILL.md", ".cursor/skills/marqdo/SKILL.md"] {
|
||||
let text = std::fs::read_to_string(root.join(rel)).unwrap();
|
||||
let core = text.split("## Minimal program").next().unwrap_or(&text);
|
||||
assert!(
|
||||
core.contains("| `**…**` | Statement") && core.contains("| `*…*` | Return |"),
|
||||
"{rel} marker table must match the parser: bold statement, italic return"
|
||||
);
|
||||
assert!(
|
||||
!core.contains("= code / return expression") && !core.contains("| `*…*` | Statement"),
|
||||
"{rel} still teaches the inverted marker polarity"
|
||||
);
|
||||
}
|
||||
let skill = std::fs::read_to_string(root.join("skills/marqdo/SKILL.md")).unwrap();
|
||||
let golden = fence_after(&skill, "## Call one function");
|
||||
let dir = std::env::temp_dir().join(format!("mq-skill-call-{}", std::process::id()));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
let file = dir.join("calculator.mq.md");
|
||||
std::fs::write(&file, golden).unwrap();
|
||||
let out = std::process::Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"call",
|
||||
file.to_str().unwrap(),
|
||||
"计算器.加法",
|
||||
"a=2",
|
||||
"b=3",
|
||||
])
|
||||
.output()
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
out.status.code(),
|
||||
Some(0),
|
||||
"skill golden failed\nstderr={}\nstdout={}\nsource=\n{golden}",
|
||||
String::from_utf8_lossy(&out.stderr),
|
||||
String::from_utf8_lossy(&out.stdout)
|
||||
);
|
||||
assert_eq!(String::from_utf8_lossy(&out.stdout).trim(), "5");
|
||||
}
|
||||
|
||||
fn fence_after<'a>(body: &'a str, heading: &str) -> &'a str {
|
||||
let rest = body
|
||||
.split_once(heading)
|
||||
.unwrap_or_else(|| panic!("missing {heading}"))
|
||||
.1;
|
||||
let start = rest
|
||||
.find("```markdown\n")
|
||||
.unwrap_or_else(|| panic!("{heading} has no markdown fence"));
|
||||
let rest = &rest[start + "```markdown\n".len()..];
|
||||
let end = rest.find("\n```").expect("fence end");
|
||||
rest[..end].trim()
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -1643,6 +1693,14 @@ fn m05_skill_core_card_has_access_not_classic_index() {
|
||||
agent.contains("## skill_core_card") && agent.contains("access(coll, key)"),
|
||||
"skill_core_card must teach access()"
|
||||
);
|
||||
assert!(
|
||||
agent.contains("Bold markers = statement; italic markers = return."),
|
||||
"skill card must match parser polarity"
|
||||
);
|
||||
assert!(
|
||||
!agent.contains("italic markers = statement"),
|
||||
"skill card still teaches inverted markers"
|
||||
);
|
||||
assert!(
|
||||
!agent.contains("never **bold** to print") || agent.contains("never use bold markers"),
|
||||
"core card must not rely on conflicting bold-as-print Classic wording"
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: agent-effects-run-tool
|
||||
description: >-
|
||||
M-A5a / MA-T03 subset — mutating run_tool goes through EffectLedger;
|
||||
committed effects dedupe; started-without-commit becomes unknown (no re-exec).
|
||||
import:
|
||||
agent: /home/cflmy/work/marqdo/ext/ai/agent.mq.md
|
||||
json: lib/json.mq.md
|
||||
sys: lib/sys.mq.md
|
||||
table: lib/table.mq.md
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
## write_probe
|
||||
|
||||
Probe side-effect tool body (count stays in ledger, not here).
|
||||
|
||||
*"wrote"*
|
||||
|
||||
# main
|
||||
|
||||
**schema = > json.parse text={"type":"object","properties":{},"additionalProperties":true}**
|
||||
**scopes = > json.parse text=["workspace:write"]**
|
||||
`spec` =
|
||||
|
||||
| id | version | description | input_schema | effect | scopes | availability |
|
||||
|----|---------|-------------|--------------|--------|--------|--------------|
|
||||
| write_probe | 1 | test write tool | `schema` | write | `scopes` | ready |
|
||||
|
||||
> agent.tools_clear
|
||||
**reg = > agent.tools_register spec=`spec`**
|
||||
**allow = > json.parse text=["write_probe"]**
|
||||
**args = > json.parse text={}**
|
||||
|
||||
**out1 = > agent.run_tool tools=`allow` name="write_probe" arguments=`args` logical_run_id="run_ma5a" step_id="s1" call_id="c1" operation_id="op_write_probe_c1" ledger_dir=".marqdo/agent-effects-ma5a"**
|
||||
**ok1 = > json.get value=`out1` key="ok"**
|
||||
**st1 = > json.get value=`out1` key="status"**
|
||||
**rc1 = > json.get value=`out1` key="effect_receipt_ref"**
|
||||
> print text=`ok1`
|
||||
> print text=`st1`
|
||||
> print text=`rc1`
|
||||
|
||||
**out2 = > agent.run_tool tools=`allow` name="write_probe" arguments=`args` logical_run_id="run_ma5a" step_id="s1" call_id="c1" operation_id="op_write_probe_c1" ledger_dir=".marqdo/agent-effects-ma5a"**
|
||||
**sum2 = > json.get value=`out2` key="summary"**
|
||||
> print text=`sum2`
|
||||
|
||||
**wm = > agent.effects_watermark ledger_dir=".marqdo/agent-effects-ma5a" logical_run_id="run_ma5a"**
|
||||
**safe = > json.get value=`wm` key="write_auto_resume_safe"**
|
||||
> print text=`safe`
|
||||
|
||||
**got = > agent.effects_get operation_id="op_write_probe_c1" ledger_dir=".marqdo/agent-effects-ma5a"**
|
||||
**rec = > json.get value=`got` key="record"**
|
||||
**state = > json.get value=`rec` key="state"**
|
||||
> print text=`state`
|
||||
@@ -5,12 +5,22 @@ description: Dual-stream execute + short models for ADR 0009 gold sample.
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
site: ./site.mq.md
|
||||
sys: lib/sys.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**port_s = > sys.env_get name="MARQDO_SITE_PORT"**
|
||||
**port = 18220**
|
||||
1. `port_s`
|
||||
**port = > json.parse text=`port_s`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
**pg = > web.page title="isolated-execute"**
|
||||
**app = > web.app page=`pg` host="127.0.0.1" port=18220**
|
||||
**app = > web.app page=`pg` host="127.0.0.1" port=`port`**
|
||||
**app = > web.route app=`app` path="/v1/chat/completions" method="POST" fn="site.chat" request="json" response="sse-live" class="execute"**
|
||||
**app = > web.route app=`app` path="/v1/models" method="GET" fn="site.models" request="query" response="json" class="short"**
|
||||
**app = > web.route app=`app` path="/v1/ping" method="GET" fn="site.ping" request="query" response="json" class="control"**
|
||||
> `app`.listen
|
||||
@@ -70,3 +70,16 @@ Short-class read: list models without holding an execute slot.
|
||||
| list | True |
|
||||
|
||||
*out*
|
||||
|
||||
# ping
|
||||
+ `payload`=None
|
||||
|
||||
Control-class noop: must succeed under dual execute without parent INVOKE_LOCK.
|
||||
|
||||
`out` =
|
||||
|
||||
| ok | lane |
|
||||
|----|------|
|
||||
| True | control |
|
||||
|
||||
*out*
|
||||
+223
@@ -827,6 +827,15 @@ fn error_bad_arity() {
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn error_table_arity() {
|
||||
assert_err(
|
||||
"tests/errors/table-arity.mq.md",
|
||||
"13:1",
|
||||
"table row arity mismatch",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn error_syntax_bad_line() {
|
||||
assert_err(
|
||||
@@ -1431,6 +1440,49 @@ fn knowledge_preflight_writes_context_pack() {
|
||||
assert!(!packs.is_empty(), "expected context pack");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn knowledge_preflight_warm_loads_ir_without_recompile() {
|
||||
let dir = tempfile_dir("mq-pf-warm");
|
||||
let out = dir.to_str().unwrap();
|
||||
let (code, _, stderr) = run(&["knowledge", "tests/engineering", "-o", out]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
assert!(
|
||||
dir.join("ekc/graph/ir.json").exists(),
|
||||
"expected ir.json snapshot after compile"
|
||||
);
|
||||
let gens = dir.join("generations");
|
||||
let before: Vec<_> = if gens.exists() {
|
||||
std::fs::read_dir(&gens).unwrap().flatten().collect()
|
||||
} else {
|
||||
Vec::new()
|
||||
};
|
||||
let (code2, stdout, stderr2) = run(&[
|
||||
"knowledge",
|
||||
"tests/engineering",
|
||||
"preflight",
|
||||
"resolve configuration",
|
||||
"-o",
|
||||
out,
|
||||
"--json",
|
||||
]);
|
||||
assert_eq!(code2, 0, "{stderr2}\n{stdout}");
|
||||
assert!(stdout.contains("create_allowed"), "{stdout}");
|
||||
assert!(
|
||||
!stderr2.contains("marqdo knowledge timing_ms:"),
|
||||
"warm preflight must not full-compile: {stderr2}"
|
||||
);
|
||||
let after: Vec<_> = if gens.exists() {
|
||||
std::fs::read_dir(&gens).unwrap().flatten().collect()
|
||||
} else {
|
||||
Vec::new()
|
||||
};
|
||||
assert_eq!(
|
||||
before.len(),
|
||||
after.len(),
|
||||
"warm preflight must not create a new generations/ tree"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn catalog_hooks_knowledge_by_default() {
|
||||
let dir = tempfile_dir("mq-cat-ekc");
|
||||
@@ -1814,6 +1866,41 @@ fn lib_json_roundtrip() {
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_json_vsafe_max_safe_ok() {
|
||||
assert_out(
|
||||
"tests/lib/json-vsafe-max-safe-ok.mq.md",
|
||||
"9007199254740991\n{\"n\":9007199254740991}",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_json_vsafe_string_ok() {
|
||||
assert_out(
|
||||
"tests/lib/json-vsafe-string-ok.mq.md",
|
||||
"1152921504606846977",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_json_vsafe_refuse() {
|
||||
// Span points at lib/json.mq.md `parse` body while path stays the caller file.
|
||||
assert_err(
|
||||
"tests/lib/json-vsafe-refuse.mq.md",
|
||||
"16:1",
|
||||
"json: integer outside V_safe",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_json_vsafe_stringify_refuse() {
|
||||
assert_err(
|
||||
"tests/lib/json-vsafe-stringify-refuse.mq.md",
|
||||
"24:1",
|
||||
"json: integer outside V_safe",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_table_collections() {
|
||||
assert_out(
|
||||
@@ -3536,6 +3623,142 @@ fn lib_foreign_session_python() {
|
||||
assert_out("tests/lib/foreign-session-python.mq.md", "42\n5");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_session_vsafe_refuse() {
|
||||
if !node_available() {
|
||||
eprintln!("skip lib_foreign_session_vsafe_refuse: no node on PATH");
|
||||
return;
|
||||
}
|
||||
// Span points at lib/foreign.mq.md session_set body.
|
||||
assert_err(
|
||||
"tests/lib/foreign-session-vsafe-refuse.mq.md",
|
||||
"207:1",
|
||||
"json: integer outside V_safe",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_session_use_after_close() {
|
||||
if !node_available() {
|
||||
eprintln!("skip lib_foreign_session_use_after_close: no node on PATH");
|
||||
return;
|
||||
}
|
||||
assert_err(
|
||||
"tests/lib/foreign-session-use-after-close.mq.md",
|
||||
"198:1",
|
||||
"foreign session",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_session_double_close() {
|
||||
if !node_available() {
|
||||
eprintln!("skip lib_foreign_session_double_close: no node on PATH");
|
||||
return;
|
||||
}
|
||||
assert_err(
|
||||
"tests/lib/foreign-session-double-close.mq.md",
|
||||
"231:1",
|
||||
"foreign session",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_session_use_before_open() {
|
||||
// Text fabrication is refused before registry lookup (opaque handle discipline).
|
||||
assert_err(
|
||||
"tests/lib/foreign-session-use-before-open.mq.md",
|
||||
"198:1",
|
||||
"session id must be a handle",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_session_handle_no_serialize() {
|
||||
if !node_available() {
|
||||
eprintln!("skip lib_foreign_session_handle_no_serialize: no node on PATH");
|
||||
return;
|
||||
}
|
||||
assert_err(
|
||||
"tests/lib/foreign-session-handle-no-serialize.mq.md",
|
||||
"24:1",
|
||||
"session handle cannot be serialized",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_session_result_vsafe_refuse() {
|
||||
if !python_available() {
|
||||
eprintln!("skip lib_foreign_session_result_vsafe_refuse: no python on PATH");
|
||||
return;
|
||||
}
|
||||
assert_err(
|
||||
"tests/lib/foreign-session-result-vsafe-refuse.mq.md",
|
||||
"198:1",
|
||||
"json: integer outside V_safe",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_session_isolation() {
|
||||
if !node_available() {
|
||||
eprintln!("skip lib_foreign_session_isolation: no node on PATH");
|
||||
return;
|
||||
}
|
||||
assert_out("tests/lib/foreign-session-isolation.mq.md", "41\nFalse");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_session_cold_replay_empty() {
|
||||
if !node_available() {
|
||||
eprintln!("skip lib_foreign_session_cold_replay_empty: no node on PATH");
|
||||
return;
|
||||
}
|
||||
assert_err(
|
||||
"tests/lib/foreign-session-cold-replay-empty.mq.md",
|
||||
"198:1",
|
||||
"foreign session",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_vsafe_refuse() {
|
||||
if !python_available() {
|
||||
eprintln!("skip lib_foreign_vsafe_refuse: no python on PATH");
|
||||
return;
|
||||
}
|
||||
assert_err(
|
||||
"tests/lib/foreign-vsafe-refuse.mq.md",
|
||||
"16:1",
|
||||
"json: integer outside V_safe",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_vsafe_postarith_refuse() {
|
||||
if !python_available() {
|
||||
eprintln!("skip lib_foreign_vsafe_postarith_refuse: no python on PATH");
|
||||
return;
|
||||
}
|
||||
assert_err(
|
||||
"tests/lib/foreign-vsafe-postarith-refuse.mq.md",
|
||||
"16:1",
|
||||
"json: integer outside V_safe",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lib_foreign_vsafe_string_ok() {
|
||||
if !node_available() {
|
||||
eprintln!("skip lib_foreign_vsafe_string_ok: no node on PATH");
|
||||
return;
|
||||
}
|
||||
assert_out(
|
||||
"tests/lib/foreign-vsafe-string-ok.mq.md",
|
||||
"{\"out\":\"1152921504606846978\"}",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bytecode_lib_math_formula() {
|
||||
assert_out_backend(
|
||||
|
||||
@@ -238,6 +238,7 @@ fn mr01_dual_isolated_execute_and_short_reads() {
|
||||
.env("MARQDO_WEB_PLUGIN", std::env::var_os("MARQDO_WEB_PLUGIN").unwrap())
|
||||
.env("MARQDO_LLM_PLUGIN", std::env::var_os("MARQDO_LLM_PLUGIN").unwrap())
|
||||
.env("MARQDO_RUNTIME_DIR", &runtime_dir)
|
||||
.env("MARQDO_SITE_PORT", "18220")
|
||||
.env("OPENAI_API_KEY", "mr01-key")
|
||||
.stdout(Stdio::null())
|
||||
.stderr(Stdio::piped())
|
||||
@@ -417,5 +418,244 @@ fn mr01_dual_isolated_execute_and_short_reads() {
|
||||
assert!(sok > 10, "expected many short 200s, got ok={sok} fail={sfail}");
|
||||
assert_eq!(sfail, 0, "short reads failed: {sfail}");
|
||||
|
||||
assert_eq!(
|
||||
caps["features"]["runtime.read_lane"],
|
||||
1,
|
||||
"read_lane must be on; caps={caps}"
|
||||
);
|
||||
|
||||
let _ = std::fs::remove_dir_all(&runtime_dir);
|
||||
}
|
||||
|
||||
/// Observer disconnect must not cancel the execute task (default).
|
||||
#[test]
|
||||
fn disconnect_keeps_running_and_replay() {
|
||||
if TcpListener::bind("127.0.0.1:0").is_err() {
|
||||
eprintln!("skip disconnect-keeps-running: local sockets unavailable");
|
||||
return;
|
||||
}
|
||||
ensure_plugins();
|
||||
|
||||
let secs: u64 = 6;
|
||||
let (base_a, stop_a, join_a) = spawn_fake_sse("A", secs, 10);
|
||||
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let site = root.join("tests/ext/isolated-execute-site");
|
||||
let runtime_dir = std::env::temp_dir().join(format!("mq-disc-rt-{}", std::process::id()));
|
||||
let _ = std::fs::create_dir_all(&runtime_dir);
|
||||
|
||||
let bin = env!("CARGO_BIN_EXE_marqdo");
|
||||
let mut child: Child = Command::new(bin)
|
||||
.args(["run", "serve.mq.md"])
|
||||
.current_dir(&site)
|
||||
.env("MARQDO_EXT", root.join("ext"))
|
||||
.env("MARQDO_WEB_PLUGIN", std::env::var_os("MARQDO_WEB_PLUGIN").unwrap())
|
||||
.env("MARQDO_LLM_PLUGIN", std::env::var_os("MARQDO_LLM_PLUGIN").unwrap())
|
||||
.env("MARQDO_RUNTIME_DIR", &runtime_dir)
|
||||
.env("MARQDO_SITE_PORT", "18221")
|
||||
.env("OPENAI_API_KEY", "mr01-key")
|
||||
.stdout(Stdio::null())
|
||||
.stderr(Stdio::piped())
|
||||
.spawn()
|
||||
.expect("spawn site");
|
||||
|
||||
let base = "http://127.0.0.1:18221";
|
||||
if !wait_http_ok(&format!("{base}/v1/models"), Duration::from_secs(45)) {
|
||||
let _ = child.kill();
|
||||
let err = child
|
||||
.stderr
|
||||
.take()
|
||||
.map(|mut s| {
|
||||
let mut t = String::new();
|
||||
let _ = s.read_to_string(&mut t);
|
||||
t
|
||||
})
|
||||
.unwrap_or_default();
|
||||
panic!("site did not start for disconnect test; stderr={err}");
|
||||
}
|
||||
|
||||
let chat_url = format!("{base}/v1/chat/completions");
|
||||
let body = format!(
|
||||
r#"{{"model":"mr01","stream":true,"base_url":"{base_a}","messages":[{{"role":"user","content":"hi"}}]}}"#
|
||||
);
|
||||
// Observer disconnects after ~1.2s; task must keep running.
|
||||
let out = Command::new("curl")
|
||||
.args([
|
||||
"-s",
|
||||
"-N",
|
||||
"--max-time",
|
||||
"1",
|
||||
"-H",
|
||||
"Content-Type: application/json",
|
||||
"-d",
|
||||
&body,
|
||||
&chat_url,
|
||||
])
|
||||
.output()
|
||||
.expect("curl disconnect");
|
||||
let text = String::from_utf8_lossy(&out.stdout);
|
||||
let mut task_id = String::new();
|
||||
for line in text.lines() {
|
||||
let line = line.trim();
|
||||
if let Some(rest) = line.strip_prefix("data: ") {
|
||||
if let Ok(v) = serde_json::from_str::<serde_json::Value>(rest) {
|
||||
if v.get("type").and_then(|t| t.as_str()) == Some("run.started") {
|
||||
if let Some(tid) = v.pointer("/payload/task_id").and_then(|x| x.as_str()) {
|
||||
task_id = tid.to_string();
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
assert!(!task_id.is_empty(), "missing task_id in early SSE; raw={text}");
|
||||
|
||||
// Wait until task finishes (observer already gone).
|
||||
let mut terminal = false;
|
||||
let deadline = Instant::now() + Duration::from_secs(secs + 8);
|
||||
while Instant::now() < deadline {
|
||||
let get_url = format!("{base}/_runtime/tasks/{task_id}");
|
||||
let out = Command::new("curl")
|
||||
.args(["-s", &get_url])
|
||||
.output()
|
||||
.expect("runtime get");
|
||||
let body = String::from_utf8_lossy(&out.stdout);
|
||||
if body.contains("\"completed\"")
|
||||
|| body.contains("\"succeeded\"")
|
||||
|| body.contains("\"failed\"")
|
||||
|| body.contains("\"cancelled\"")
|
||||
{
|
||||
assert!(
|
||||
!body.contains("\"cancelled\""),
|
||||
"disconnect must not cancel task: {body}"
|
||||
);
|
||||
terminal = true;
|
||||
break;
|
||||
}
|
||||
thread::sleep(Duration::from_millis(200));
|
||||
}
|
||||
assert!(terminal, "task {task_id} did not finish after observer disconnect");
|
||||
|
||||
// Replay via events (JSON after_seq=0).
|
||||
let ev_url = format!("{base}/_runtime/tasks/{task_id}/events?after_seq=0");
|
||||
let ev = Command::new("curl")
|
||||
.args(["-s", &ev_url])
|
||||
.output()
|
||||
.expect("events");
|
||||
let ev_body = String::from_utf8_lossy(&ev.stdout);
|
||||
assert!(
|
||||
ev_body.contains('A') || ev_body.contains("delta") || ev_body.contains("event"),
|
||||
"replay empty: {ev_body}"
|
||||
);
|
||||
|
||||
stop_a.store(true, Ordering::Relaxed);
|
||||
let _ = join_a.join();
|
||||
let _ = child.kill();
|
||||
let _ = child.wait();
|
||||
let _ = std::fs::remove_dir_all(&runtime_dir);
|
||||
}
|
||||
|
||||
/// Control + short reads stay 200 while two execute streams hold slots.
|
||||
#[test]
|
||||
fn control_under_dual_execute() {
|
||||
if TcpListener::bind("127.0.0.1:0").is_err() {
|
||||
eprintln!("skip control-under-dual-execute: local sockets unavailable");
|
||||
return;
|
||||
}
|
||||
ensure_plugins();
|
||||
|
||||
let secs: u64 = 8;
|
||||
let (base_a, stop_a, join_a) = spawn_fake_sse("A", secs, 10);
|
||||
let (base_b, stop_b, join_b) = spawn_fake_sse("B", secs, 10);
|
||||
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let site = root.join("tests/ext/isolated-execute-site");
|
||||
let runtime_dir = std::env::temp_dir().join(format!("mq-ctl-rt-{}", std::process::id()));
|
||||
let _ = std::fs::create_dir_all(&runtime_dir);
|
||||
|
||||
let bin = env!("CARGO_BIN_EXE_marqdo");
|
||||
let mut child: Child = Command::new(bin)
|
||||
.args(["run", "serve.mq.md"])
|
||||
.current_dir(&site)
|
||||
.env("MARQDO_EXT", root.join("ext"))
|
||||
.env("MARQDO_WEB_PLUGIN", std::env::var_os("MARQDO_WEB_PLUGIN").unwrap())
|
||||
.env("MARQDO_LLM_PLUGIN", std::env::var_os("MARQDO_LLM_PLUGIN").unwrap())
|
||||
.env("MARQDO_RUNTIME_DIR", &runtime_dir)
|
||||
.env("MARQDO_SITE_PORT", "18222")
|
||||
.env("OPENAI_API_KEY", "mr01-key")
|
||||
.stdout(Stdio::null())
|
||||
.stderr(Stdio::piped())
|
||||
.spawn()
|
||||
.expect("spawn site");
|
||||
|
||||
let base = "http://127.0.0.1:18222";
|
||||
if !wait_http_ok(&format!("{base}/v1/models"), Duration::from_secs(45)) {
|
||||
let _ = child.kill();
|
||||
let err = child
|
||||
.stderr
|
||||
.take()
|
||||
.map(|mut s| {
|
||||
let mut t = String::new();
|
||||
let _ = s.read_to_string(&mut t);
|
||||
t
|
||||
})
|
||||
.unwrap_or_default();
|
||||
panic!("site did not start for control test; stderr={err}");
|
||||
}
|
||||
|
||||
let chat_url = format!("{base}/v1/chat/completions");
|
||||
let body_tmpl = r#"{"model":"mr01","stream":true,"base_url":"__BASE__","messages":[{"role":"user","content":"hi"}]}"#;
|
||||
let t_a = {
|
||||
let u = chat_url.clone();
|
||||
let b = body_tmpl.to_string();
|
||||
let ba = base_a.clone();
|
||||
thread::spawn(move || {
|
||||
let _ = collect_sse_deltas(&u, &b, &ba);
|
||||
})
|
||||
};
|
||||
let t_b = {
|
||||
let u = chat_url.clone();
|
||||
let b = body_tmpl.to_string();
|
||||
let bb = base_b.clone();
|
||||
thread::spawn(move || {
|
||||
let _ = collect_sse_deltas(&u, &b, &bb);
|
||||
})
|
||||
};
|
||||
|
||||
thread::sleep(Duration::from_secs(1));
|
||||
let mut ok_n = 0u32;
|
||||
let mut fail_n = 0u32;
|
||||
let start = Instant::now();
|
||||
while start.elapsed() < Duration::from_secs(3) {
|
||||
for path in ["/v1/models", "/v1/ping"] {
|
||||
let url = format!("{base}{path}");
|
||||
let t0 = Instant::now();
|
||||
let out = Command::new("curl")
|
||||
.args(["-s", "-o", "/dev/null", "-w", "%{http_code}", &url])
|
||||
.output();
|
||||
let elapsed = t0.elapsed();
|
||||
match out {
|
||||
Ok(o) if String::from_utf8_lossy(&o.stdout) == "200" => {
|
||||
assert!(
|
||||
elapsed < Duration::from_millis(1500),
|
||||
"{path} p95 budget; took {elapsed:?}"
|
||||
);
|
||||
ok_n += 1;
|
||||
}
|
||||
_ => fail_n += 1,
|
||||
}
|
||||
}
|
||||
thread::sleep(Duration::from_millis(80));
|
||||
}
|
||||
assert!(ok_n > 4, "expected control/short 200s, ok={ok_n} fail={fail_n}");
|
||||
assert_eq!(fail_n, 0, "control/short failed under dual execute: {fail_n}");
|
||||
|
||||
let _ = t_a.join();
|
||||
let _ = t_b.join();
|
||||
stop_a.store(true, Ordering::Relaxed);
|
||||
stop_b.store(true, Ordering::Relaxed);
|
||||
let _ = join_a.join();
|
||||
let _ = join_b.join();
|
||||
let _ = child.kill();
|
||||
let _ = child.wait();
|
||||
let _ = std::fs::remove_dir_all(&runtime_dir);
|
||||
}
|
||||
@@ -124,6 +124,7 @@ fn mr07_supervisor_dry_run_slots_and_publish_recover() {
|
||||
selection_ref: None,
|
||||
capabilities_ref: None,
|
||||
deadline_at: "2099-01-01T00:00:00Z".into(),
|
||||
fs_root: Some(root.display().to_string()),
|
||||
},
|
||||
};
|
||||
let a = sup.dispatch(req("a")).unwrap();
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: closed handle cannot be reused across a later step
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**会话 = > foreign.session_open lang="node" timeout=30**
|
||||
**> foreign.session_eval id=`会话` source="var x = 1"**
|
||||
**> foreign.session_close id=`会话`**
|
||||
**> foreign.session_eval id=`会话` source="x"**
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: foreign session double-close is a fault
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**会话 = > foreign.session_open lang="node" timeout=30**
|
||||
**> foreign.session_close id=`会话`**
|
||||
**> foreign.session_close id=`会话`**
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: foreign session handle cannot cross JSON bridge
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**会话 = > foreign.session_open lang="node" timeout=30**
|
||||
**> json.stringify value=`会话`**
|
||||
**> foreign.session_close id=`会话`**
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: two same-lang sessions do not share bindings
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**a = > foreign.session_open lang="node" timeout=30**
|
||||
**b = > foreign.session_open lang="node" timeout=30**
|
||||
**> foreign.session_eval id=`a` source="var shared = 41"**
|
||||
**ra = > foreign.session_eval id=`a` source="shared"**
|
||||
**rb = > foreign.session_eval id=`b` source="shared"**
|
||||
**> print text=[result](access(`ra`, "result"))**
|
||||
**> print text=[ok](access(`rb`, "ok"))**
|
||||
**> foreign.session_close id=`a`**
|
||||
**> foreign.session_close id=`b`**
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: foreign session_eval result outside V_safe is a fault
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**py = > foreign.session_open lang="python" timeout=30**
|
||||
**> foreign.session_eval id=`py` source="2**60 + 1"**
|
||||
**> foreign.session_close id=`py`**
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: foreign session use-after-close is a fault
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**会话 = > foreign.session_open lang="node" timeout=30**
|
||||
**> foreign.session_close id=`会话`**
|
||||
**> foreign.session_eval id=`会话` source="1 + 1"**
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: foreign session text id fabrication is a fault
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**> foreign.session_eval id="no-such-session" source="1 + 1"**
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: foreign session_set V_safe refuse
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**node = > foreign.session_open lang="node" timeout=30**
|
||||
**n = 1152921504606846977**
|
||||
**> foreign.session_set id=`node` name="__n" value=`n`**
|
||||
**> foreign.session_close id=`node`**
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: foreign V_safe refuse after Python arithmetic
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**py = > foreign.session_open lang="python" timeout=30**
|
||||
|
||||
`emit` =
|
||||
```python
|
||||
import json
|
||||
n = 2**53 - 1
|
||||
print(json.dumps({"n": 2 * n}))
|
||||
```
|
||||
|
||||
**raw = > foreign.session_eval id=`py` code=`emit`**
|
||||
**stdout = > json.get value=`raw` key="stdout"**
|
||||
**payload = > json.parse text=`stdout`**
|
||||
**> print text=`payload`**
|
||||
**> foreign.session_close id=`py`**
|
||||
Loaded 100 of 131 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user