Compare commits
22
Commits
ext-v1.3.1
..
v1.4.4
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b43a08b2e2 | ||
|
|
1908bf1a53 | ||
|
|
c44ea38ae2 | ||
|
|
d489f7c088 | ||
|
|
a993cfd76a | ||
|
|
d5f826a8c8 | ||
|
|
0f72173d08 | ||
|
|
a707758d47 | ||
|
|
63bcb882a6 | ||
|
|
1bb16dd6db | ||
|
|
58ec2172d6 | ||
|
|
66926e9e0a | ||
|
|
dcf4c05663 | ||
|
|
f47a1e143a | ||
|
|
9cf98a98b5 | ||
|
|
f99d552d87 | ||
|
|
7d49c358c1 | ||
|
|
a32c0cd78f | ||
|
|
0a8f76d9b4 | ||
|
|
4e2419b598 | ||
|
|
f6374d1593 | ||
|
|
9ede4bc63d |
No files matched your search
@@ -38,7 +38,7 @@ A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data
|
||||
|
||||
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
|
||||
|
||||
### 2. Good patterns
|
||||
### 2. Good patterns (copy these — not `json.set`)
|
||||
|
||||
**Wire / steps / commands** — `@` record table:
|
||||
|
||||
@@ -60,7 +60,53 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
|
||||
| `wire` | `set_text` |
|
||||
```
|
||||
|
||||
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
|
||||
**Agent / LLM result map** — one readable row, not a `json.parse` + `json.set` chain:
|
||||
|
||||
```markdown
|
||||
`out` =
|
||||
|
||||
| status | task | result | llm_calls | tokens |
|
||||
|--------|------|--------|-----------|--------|
|
||||
| ok | `task` | `reply` | `llm_calls` | `tokens` |
|
||||
|
||||
*out*
|
||||
```
|
||||
|
||||
**Soft error pack** (transport / gate failure) — still a table humans can skim:
|
||||
|
||||
```markdown
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
**Optional / conditional key** — sparse `table.put` after the static table (one dynamic key only):
|
||||
|
||||
```markdown
|
||||
`out` =
|
||||
|
||||
| status | task |
|
||||
|--------|------|
|
||||
| error | `task` |
|
||||
|
||||
1. `err`
|
||||
**out = > table.put in=`out` at="error" value=`err`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
```
|
||||
|
||||
**Empty list / empty map** — prefer stdlib seeds over `json.parse text=[]` / `{}`:
|
||||
|
||||
```markdown
|
||||
**empty_tc = > table.empty_list**
|
||||
**empty_map = > table.empty_map**
|
||||
```
|
||||
|
||||
**Single dynamic key from scratch** — one `table.put` (or a helper), not a json chain:
|
||||
|
||||
```markdown
|
||||
**`set_text` = table.put in=None at="#log" value=msg**
|
||||
@@ -73,14 +119,20 @@ Better still — call a named helper:
|
||||
**browser.set_text sel="#log" text=msg**
|
||||
```
|
||||
|
||||
### 3. Bad pattern (do not write)
|
||||
**When `json.*` is OK:** `json.parse` / `json.stringify` / `json.quote` on **wire text**; `json.get` to read an opaque map. Never use `json.set` / `json.append` to *build* author-facing structures.
|
||||
|
||||
### 3. Bad pattern (do not write — and do not copy from old `ext/ai`)
|
||||
|
||||
```markdown
|
||||
**`ret` = json.set map=None key="set_text" value=…**
|
||||
**`ret` = json.set map=ret key="canvas" value=…**
|
||||
**`cmds` = json.append list=cmds item=c0**
|
||||
**`out` = json.parse text={"status":"ok"}**
|
||||
**`out` = json.set map=out key="task" value=task**
|
||||
```
|
||||
|
||||
Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compliance. Refactor the call site to tables / `table.put` instead of extending the glue.
|
||||
|
||||
## Writing application `.mq.md`
|
||||
|
||||
1. Frontmatter: title + imports (`table`, domain libs). **Do not import `json` unless parsing strings.**
|
||||
|
||||
+42
-154
@@ -4,95 +4,40 @@ description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
|
||||
building dynamic sites with ext/web, quantum circuits with ext/quantum,
|
||||
formula-first linear algebra with ext/linalg, or when the user mentions
|
||||
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
|
||||
or linalg/线性代数 extension.
|
||||
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
|
||||
sites with ext/web, quantum circuits with ext/quantum, or when the user
|
||||
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
|
||||
quantum/量子 extension.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
|
||||
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
|
||||
|
||||
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets, **ext → R2+GitHub**, **CLI → Ubuntu PPA**): use [marqdo-release](../marqdo-release/SKILL.md) — detect versions, **ask for SemVer + mode (`full` / `cli` / `ext`)**, then follow that playbook. Ext-only releases are allowed. If sudo/GPG/PPA steps need the user, print the exact commands.
|
||||
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
|
||||
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
|
||||
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
|
||||
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
|
||||
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
|
||||
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
|
||||
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
|
||||
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
|
||||
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
|
||||
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
|
||||
|
||||
## 记不住语法细节?查 MLSP(AI 必读)
|
||||
|
||||
**不必背 Marqdo 语法细节**——语法可查、程序可验、修复有界。写码前后走**查询式**工作流:
|
||||
|
||||
```bash
|
||||
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":2,"method":"locate","params":{"path":"a.mq.md","symbol":"加一"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":3,"method":"validate","params":{"path":"a.mq.md"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":4,"method":"schema","params":{"path":"a.mq.md","unit":"加一"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_mismatch","doc_anchor":"a.mq.md#L9-L15"}}' | marqdo mlsp
|
||||
```
|
||||
|
||||
| method | 何时用 |
|
||||
|--------|--------|
|
||||
| `syntax` | 不确定某个语法怎么写(关键字/别名 → 构造卡片:「返回」「表」「调用」「循环」…) |
|
||||
| `locate` | 找符号定义位置 + 契约;或反查构造卡片 |
|
||||
| `validate` | 提交前校验(结构化诊断数组;`ok:false` 就修) |
|
||||
| `schema` | 查单元契约(形参/返回/字段) |
|
||||
| `repair_targets` | 拿错误的**有界**修复靶点:只改锚点范围内行,越界必弃权(abstain) |
|
||||
|
||||
行分隔 JSON:每行请求 `{"id","method","params"}` → 每行响应 `{"id","ok","result"|"error"}`。
|
||||
语法唯一事实来源 = `doc/design/core-surface.md`(CI 守卫同步);卡片带 `manual` 指回文档行。
|
||||
所有错误诊断都是结构化 JSON:`code` / `severity` / `span` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`。
|
||||
|
||||
### 渐进式契约(可选标注;schema 就长在文档表里)
|
||||
|
||||
契约是**未绑定文档表**(绑定表是数据,永远不是契约)。三种形状、严格位置:
|
||||
|
||||
| 形状(须含 `类型` 列) | 允许位置 | 附着 |
|
||||
|--------------------------|----------|------|
|
||||
| `参数`/`类型`/`说明` 表 + `返回`/`类型`/`说明` 表 | 函数体首个可执行行之前 | 函数 |
|
||||
| `字段`/`类型`/`可空`/`说明` 表 | 紧邻 `` `名` = `` 绑定之前 | 集合(变量) |
|
||||
| `字段`/`类型`/`可空`/`说明` 表 | 对象(`#`)体首成员之前 | 对象类型 |
|
||||
|
||||
````text
|
||||
## 加一
|
||||
|
||||
对于输入变量`n`,期望是数字。
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| n | number | 输入值 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | number | 加一结果 |
|
||||
|
||||
*n+1*
|
||||
````
|
||||
|
||||
- 类型词汇:`text` / `number` / `bool` / `list` / `map` / `any` / `#` 对象名(拼错 ⇒ `contract.unknown_type` + 最近建议)。
|
||||
- 契约表**永不执行**、不污染升参推断;无契约文件行为逐字节不变(动态默认,零摩擦)。
|
||||
- 运行时只在四个边界校验:调用实参 / 字段访问 `[键](集合)` / 表绑定 / 返回。
|
||||
- `marqdo check [FILE] [--json]` 静态互查:契约行 vs 升参推断形参**双向**漂移(错行=Error;新升参未覆盖=Warning)、未知类型、错位契约;有 Error 非零退出。
|
||||
- 契约诊断带 `doc_anchor` + `doc_quote`(表原文)——修复只照锚点局部改。
|
||||
|
||||
## Markup → meaning (v0.3)
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
@@ -103,14 +48,13 @@ printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
|
||||
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
|
||||
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
|
||||
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
|
||||
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
|
||||
| `- [item](coll)` | Foreach (unchanged) |
|
||||
@@ -159,17 +103,17 @@ 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
|
||||
**n = 0**
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -192,16 +136,16 @@ import clock:lib/time.mq.md
|
||||
|
||||
# main
|
||||
|
||||
**xs = > text.str_split s="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).
|
||||
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). **`ext/llm`** — intelligence primitive (`ask` / `stream` / `collect`; `complete` is compat); **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
@@ -216,61 +160,24 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
|
||||
|
||||
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
|
||||
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only. **Engineering Knowledge(EKC)**:`marqdo knowledge|find|reuse|…` + `agent.preflight`(REUSE→ADAPT→CREATE)——见 [engineering-knowledge.md](../../doc/design/engineering-knowledge.md)。
|
||||
4. **Skill Compilation (v2)** — successful runs become `.mq.md` episodes; after enough evidence, `maybe_learn` compiles an executable skill (`llm_free`). Prefer `## run` over bare `## plan` when you want learning.
|
||||
5. **Adaptive Routing (P4)** — router is abstract (`marqdo` / `small-llm` / `llm` / `auto`); `jev` is a compat alias of `small-llm`. Decision via `router_model` (any llm handle). Policy Compilation writes `policies/router.mq.md`.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
|
||||
|
||||
APIs: `# agent` / `# 智能体` → `## run` / `## route` / `## step` / `## plan` (+ `resolve` / `record_episode` / `maybe_learn` / `compile` / `compile_policy` / `metrics`). Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
|
||||
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`).
|
||||
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) · v2: [doc/next/003.md](../../doc/next/003.md) · P4: [doc/next/004.md](../../doc/next/004.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/) · [agent-sandbox-okf](../../examples/agent-sandbox-okf/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · optimize O1–O5: [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
|
||||
**Sandbox (O1):** `import sandbox:ext/ai/sandbox.mq.md` · `agent.trial` / `智能体.试跑` · `run`/`step` take `sandbox=` / `沙盒=` (default `False`). Profile caps are tables via `sandbox.profile`. Gold: `tests/ext/agent-sandbox-optin.mq.md`.
|
||||
|
||||
## Official extension: `ext/web` (Document / Endpoint / Resource)
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin: `scripts/build-web-plugin.sh` / `marqdo ext add web`.
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifact.md](../../doc/design/ext-web-artifact.md).
|
||||
|
||||
**Constitution (ADR 0007 — do not degrade):**
|
||||
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
|
||||
|
||||
1. **Document / Endpoint / Resource** — `.mq.md` with `type: web|endpoint` (ZH `类型: 网页|端点`) is the site surface; not a Flask-style class pile.
|
||||
2. **Code is documentation** — the file is docs + route + handler.
|
||||
3. **Table = data** — View schema only `|type|slot|value|attrs|style|`. No `compose_*` dialects, no `json.set` glue.
|
||||
4. **Facade only** — `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect`. DB → `ext/data`; auth → `ext/security`; ws/http → `ext/net`.
|
||||
5. **No author `ensure_plugin` / `host_*`**; import web = capability (plugin auto-load).
|
||||
6. **Declared vs system routes**; `web.inspect` lists both. No silent user routes.
|
||||
|
||||
Import **one language** per file:
|
||||
|
||||
- EN: `import web:ext/web/web.mq.md` (+ `import data:ext/data/db.mq.md` as needed)
|
||||
- EN: `import web:ext/web/web.mq.md`
|
||||
- ZH: `导入 网页:ext/web/网页.mq.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: web
|
||||
route: /
|
||||
title: Hello
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# Hello
|
||||
|
||||
Executable document as a page.
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: endpoint
|
||||
method: POST
|
||||
path: /api/ping
|
||||
response: json
|
||||
---
|
||||
|
||||
*{"ok": true}*
|
||||
```
|
||||
|
||||
Site entry may `# main` → `web.serve root="."`. Client WASM: `ext/web/client.mq.md` / `lib/browser` — no author JS.
|
||||
|
||||
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · ADR [0007](../../doc/adr/0007-web-document-endpoint.md) · rule: `.cursor/rules/web-artifact-no-degrade.mdc` · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
|
||||
Web patterns: [examples.md](examples.md) · API index: [reference.md](reference.md).
|
||||
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
|
||||
## Official extension: `ext/quantum` (circuits + Q7/Q8)
|
||||
|
||||
@@ -296,29 +203,13 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
|
||||
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/).
|
||||
|
||||
## Official extension: `ext/linalg` (formula-first LA)
|
||||
|
||||
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
|
||||
|
||||
- EN: `import la:ext/linalg/linalg.mq.md`
|
||||
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
|
||||
|
||||
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
|
||||
|
||||
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. **查再写**:不确定语法就 `marqdo mlsp`(`syntax` / `locate`)——不必背语法细节。
|
||||
2. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
3. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
4. 可选:给函数/集合写**渐进式契约**(上节三种表格形状;写全或不写,别写一半)。
|
||||
5. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
6. On errors:结构化诊断(含 `doc_anchor` / `suggestion`)→ `repair_targets` 取有界靶点,**只改锚点范围内**的行。
|
||||
7. 提交前:`marqdo check path/to/file.mq.md`(或 `mlsp validate`)清到零 Error。
|
||||
8. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
4. On `path:line:col: message`, fix that span; re-run until exit 0.
|
||||
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
|
||||
## Anti-patterns (common model mistakes)
|
||||
|
||||
@@ -339,8 +230,7 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
|
||||
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
|
||||
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
|
||||
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
|
||||
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
|
||||
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
|
||||
|
||||
@@ -357,5 +247,3 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
- [ ] Browser client: `lib/browser` + tables when returning effects
|
||||
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
- [ ] 语法拿不准的地方已查 MLSP(`syntax`/`locate`),而不是凭记忆发明
|
||||
- [ ] 契约(如有)与升参一致:`marqdo check` 零 Error
|
||||
@@ -162,6 +162,56 @@ import browser:lib/browser.mq.md
|
||||
|
||||
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
|
||||
|
||||
## 6e. Agent / LLM result maps — GFM first (positive)
|
||||
|
||||
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
|
||||
|
||||
```markdown
|
||||
---
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
## step_ok
|
||||
+ `task`
|
||||
+ `reply`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | result |
|
||||
|--------|------|--------|
|
||||
| ok | `task` | `reply` |
|
||||
|
||||
*out*
|
||||
|
||||
## step_err
|
||||
+ `task`
|
||||
+ `err`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | error |
|
||||
|--------|------|-------|
|
||||
| error | `task` | `err` |
|
||||
|
||||
*out*
|
||||
|
||||
## soft_http_pack
|
||||
+ `msg`
|
||||
+ `usage0`
|
||||
|
||||
**empty_tc = > table.empty_list**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -126,16 +126,22 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v1.4.4**:LLM 传输软失败 + `ext/ai` 表优先——`status=error` 不 abort · 去 json.set 胶水
|
||||
- **v1.4.4**: Soft LLM transport errors + table-first ext/ai — structured status=error, no json.set glue
|
||||
- **v1.4.2**:Agent/LLM 优化 O1–O5——sandbox trial · promote proof · step_route/EFI/cost · lint · quarantine
|
||||
- **v1.4.2**: Agent/LLM optimize O1–O5 — sandbox trial, promote proof, step_route/EFI/cost, lint, quarantine
|
||||
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
|
||||
- **v1.4.1**: View annot leaders — SVG mid→mid (mark bottom-center → chip top-center), frame chip id unify, L→R density
|
||||
- **v1.4.0**:叙述统一——`% marqdo: var=` · 臂/循环体叙述 · foreach 中英糖 · 图片自写回 · view 推断形参
|
||||
- **v1.4.0**: Prose-unified control flow — formula meta bind, arm/loop narrative, foreach sugar, image writeback, inferred-param view
|
||||
- **v1.3.3**:view 文档面 Structure——叙述保真 · 标记面 · 调用/循环帧 · `#mq-view-trace` · 静态站同源
|
||||
- **v1.3.3**: Browse document-surface Structure — narration, markers, call/loop frames, `#mq-view-trace`, static site parity
|
||||
- **v1.3.0**:Engineering Knowledge Compiler——L0–L4 · `reuse`/`find`/`duplicate` · Agent preflight(REUSE→ADAPT→CREATE)
|
||||
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
|
||||
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
|
||||
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
|
||||
- **v1.1.1**:AI 栈收口——llm `ask`/`stream`/`collect` · Metadata Binding · Skill Compilation + Adaptive Routing · MCP 客户端 + resume · 可选 `plugins/llm`
|
||||
- **v1.1.1**: AI stack — llm ask/stream/collect, Metadata Binding, Skill Compilation + Adaptive Routing, MCP client + resume, optional plugins/llm
|
||||
- **v1.0.7**:WS/网络边界加固;`url_encode` `%20`
|
||||
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com)
|
||||
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-ai-optimize](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/ext-ai-optimize.md)
|
||||
|
||||
### Downloads
|
||||
|
||||
|
||||
@@ -87,3 +87,9 @@ tests/ext/:memory:
|
||||
|
||||
# local secrets
|
||||
.env
|
||||
|
||||
# sandbox gold leftovers
|
||||
tests/ext/_sbx_cow/
|
||||
|
||||
tests/ext/_sbx_*/
|
||||
examples/**/_example_sbx/
|
||||
+176
@@ -8,6 +8,182 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v1.4.4 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**LLM 传输软失败 + `ext/ai` 表优先重构**:上游连接拒绝/超时/HTTP≠200 时,Runtime 返回结构化 `finish|status=error`(不再硬中断 VM);`agent` / `智能体` / `llm/openai` 去掉 `json.set`/`json.append` 袋胶水。含 CLI host · `plugins/llm` · Ext pack **1.4.4**。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.4 && cargo build --release
|
||||
cargo build --release -p marqdo_plugin_llm
|
||||
marqdo run tests/ext/agent-llm-transport-soft.mq.md
|
||||
marqdo ext add agent # CDN → 1.4.4
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——HTTP 宿主软失败契约 + Extension 风格重构;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **LLM / Agent 传输软失败**:`host_http_post` / SSE · `plugins/llm` · `ext/ai/llm/openai` 结构化 `finish=error`;`agent.step` / `plan` / `run` 收成 `status=error`。金样 `tests/ext/agent-llm-transport-soft.mq.md`。说明:[doc/research/agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)。
|
||||
- **`agent.run`**:`cache == "soft-hit"` 引号比较(裸 `soft-hit` 曾被解析为减法)。
|
||||
|
||||
### Changed
|
||||
|
||||
- **`ext/ai` 去 json 胶水**:结果 map / 事件用 GFM 表 + `table.put` / `table.append` / `table.empty_*`。SKILL 正面示例:`.cursor/skills/marqdo-dev` §2 · `marqdo/examples.md` §6e。
|
||||
- CLI / Ext / wasm SemVer **1.4.4**。
|
||||
|
||||
## Ext pack v1.4.3 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent cold EFI / resolve 硬崩修复(CLI 仍为 v1.4.2)**:qdagent 接通 `agent.run` 时空 OKF 触发 `unknown function preflight` 与 `missing map key llm_free`。本包修复 `ext/ai/agent` facade 与 `agent` native;金样 `tests/ext/agent-run-cold-efi.mq.md`。说明:[`doc/research/agent-run-efi-resolve-bugs-2026-10.md`](doc/research/agent-run-efi-resolve-bugs-2026-10.md)。
|
||||
|
||||
```bash
|
||||
marqdo ext add agent # CDN latest → 1.4.3
|
||||
# 或:MARQDO_EXT_VERSION=1.4.3 marqdo ext add agent
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime 契约修补。
|
||||
|
||||
### Fixed
|
||||
- **`agent.run`**:`efi=True` 改为 `` `self`.preflight ``(不再裸调全局 `preflight`)。
|
||||
- **`agent_resolve` miss**:返回字段对齐命中路径,含 `llm_free: false`;facade 对 `llm_free` / route 字段改用 `json.get`。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.4.3**(`ext/VERSION`);与 CLI **v1.4.2** 可独立安装。
|
||||
|
||||
## v1.4.2 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent/LLM 优化 O1–O5**:`ext/ai/sandbox` CoW 试跑接入 `agent.trial` / `run sandbox=`(默认关);promote 强制 sandbox proof;步骤路由 `step_route` + EFI preflight + `usage`/`token_cost`;风格 lint 与 `sandbox.report`;技能 `quarantine` 与离线 standing/policy 优化脚本。表优先、少 json 胶水。路线:[ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.2 && cargo build --release
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
marqdo run tests/ext/agent-sandbox-optin.mq.md
|
||||
marqdo run examples/agent-sandbox-okf/index.mq.md
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add agent # CDN latest → 1.4.2
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Extension / Agent Runtime**(`ext/ai` 沙盒与晋升闸门),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **`ext/ai/sandbox`**:CoW 工作区(`open` / `run` / `diff` / `commit` / `discard` / `inspect` / `profile` / `report`);经 `plugins/agent` `sandbox_*` → `host_query`;默认拒 `plugin`/`exec`/`net`。
|
||||
- **O1**:`agent.trial` · `run`/`step` `sandbox=` · 中文 `试跑`/`沙盒=` · 示例 `examples/agent-sandbox-okf/` · 金样 `agent-sandbox-optin`。
|
||||
- **O2**:`agent_kb_promote` 默认 sandbox proof;OKF `applies_when`/`fixtures`/`sandbox_profile`/`proof`;harness Skill Lift。
|
||||
- **O3**:`agent.step_route` · `ext/ai/policies/step-route.mq.md` · `run efi=`(缺工程知识时软放行)· 结果 `usage`/`token_cost`。
|
||||
- **O4**:`scripts/mq-style-lint.sh` · `sandbox.report` markdown 审阅面。
|
||||
- **O5**:`agent_kb_quarantine` / `agent.quarantine` · `scripts/optimize-standing-policy.sh`。
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.2**。
|
||||
- Skill:强制表/链接取元、禁同文件混 EN/ZH、点名 sandbox 试跑习惯。
|
||||
|
||||
## v1.4.1 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 叙述标注连线**:Browse / `view output` 中 underline→chip 改为 SVG 正交连线(描述底边中点 → 轨道 → 短竖线 → 值顶边中点);同跨度多帧 chip 共用 annot id;可见 chip 按锚点 L→R;帧切换后重算密度。设计:[view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.1 && cargo build --release
|
||||
marqdo view public/00-welcome.mq.md --no-open
|
||||
marqdo view output public -o /tmp/mq-public
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.4.1
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 标注几何与帧 chip 对齐),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- 设计缺口文档 [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md):叙述 fence 卡、帧感知 chip 密度、L-leader 几何约定。
|
||||
|
||||
### Fixed
|
||||
- view L-leader:id 与 mark 错配、chip 逆序交叉、border 无色变黑碎段、横线穿过 chip 文字;现为 mid→mid SVG path。
|
||||
- 叙述 fence / 代码卡单层渲染;静态页隐藏 Run;主文函数引用 call chip + leader。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.1**。
|
||||
|
||||
## v1.4.0 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**叙述统一 + 公式 meta + 图片自写回**:块公式 `% marqdo: var=`;分支/循环体与函数体同权叙述;foreach 中英糖;自写回图片 ``(扩展名校验)与 view/静态站同源标记;view 展示推断形参实值;欢迎页迁到 v0.3 叙述面。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.0 && cargo build --release
|
||||
marqdo run tests/markup-v03/formula-meta-var.mq.md
|
||||
marqdo run tests/markup-v03/foreach-narrative.mq.md
|
||||
marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.4.0
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。Language 层在既有 `formula` / `branch-list` / `loop-list` 上扩展语义(块公式 TeX 注释绑定、臂/循环体叙述、foreach 糖);Runtime:自写回图片形态 + view 推断形参展示。设计:[fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)。
|
||||
|
||||
### Added
|
||||
- **块公式 meta 绑定**:`$$` 内 `% marqdo: var=<ident>`(剥离后解析;可无空 RHS);金样 `tests/markup-v03/formula-meta-var.mq.md`。
|
||||
- **控制流叙述统一**:臂/循环体 `parse_indented_body` 与函数体同权;分支条件行支持叙述前缀与行内 `**…**`;foreach 糖 `- 对…的每一项…` / `- for each … in …`。
|
||||
- **图片自写回**:路径/URL 且扩展名合法 → ``;文本仍 HTML 注释;view / `view output` 同源样式卡与 `<img>`。
|
||||
- **view 推断形参实值**:Browse 展示 body-inferred 参数绑定值;欢迎页 EN/ZH 迁 v0.3 叙述。
|
||||
|
||||
### Fixed
|
||||
- `ext/net/url.encode`:经 `lib/net` 包装,不再直接 `host_*`(金样 `ext_mq_md_never_calls_host`)。
|
||||
- PPA 源包:`ppa-build-source.sh` 本地 `.orig` 已在 build-area 时跳过重复 `cp`。
|
||||
- view:嵌套调用欢迎页与公式/代码卡渲染清理。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.0**;词法评论段遇有序分支臂 / 循环头 / 图片自写回标记时断开,避免吞掉控制流行。
|
||||
|
||||
## v1.3.3 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 文档面 Structure**:Browse 保真叙述与标记面(变量/语句/返回无源码定界符);表/循环/分支结构块;语句后绑定值、分支命中臂、函数多调用与循环迭代下拉(默认末帧);`#mq-view-trace` AI JSON。静态 `marqdo view output` 与 live view **同源渲染**(含用户站 `public/` → gh-pages)。
|
||||
|
||||
```bash
|
||||
git checkout v1.3.3 && cargo build --release
|
||||
marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
marqdo view output public -o public
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.3.3
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 文档面 + 帧选择),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **Browse Structure 文档面**(`src/view/document.rs` · `annot.rs`):叙述保真、标记面、GFM 表 / `doc-loop` / `doc-branch`、CSS L-leader 标注带。
|
||||
- **StmtEvent / CallFrame / LoopFrame** 静默轨迹:post-stmt 绑定、分支 `call_id`、循环 `分 = 分数表[i] · value`;调用/迭代 picker(源码常显,只滤 chip)。
|
||||
- **`ViewExecutionReport`** JSON(`#mq-view-trace` · `/api/view-trace` · SSE `trace_json`)。
|
||||
- 设计:[view-document-annotations.md](doc/design/view-document-annotations.md) · [view-execution-trace.md](doc/design/view-execution-trace.md) · [view-frame-selection.md](doc/design/view-frame-selection.md);样例 `tests/view/document-annot-demo.mq.md`。
|
||||
|
||||
### Fixed
|
||||
- 多调用分支 taken 混叠;调用切换误藏未执行臂源码;循环头重复 chip。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.3.3**;静态导出与 live view 共用 `build_file_view` → 文档面。
|
||||
|
||||
## Ext pack v1.3.2 — 2026-10-13
|
||||
|
||||
### Highlights
|
||||
|
||||
**Trailing slash 路由修复(CLI 仍为 v1.3.0)**:Go `ServeMux` 精确匹配导致 `/post/foo/`(带尾部斜杠)落入 404。新增 `withStripTrailingSlash` 中间件作为最外层 handler wrapper,所有下游中间件(RBAC、Tenant、路由)均看到规范化路径。覆盖静态路由、动态路由、根路径、查询参数保留。
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.3.2
|
||||
# 或:MARQDO_EXT_VERSION=1.3.2 marqdo ext add web
|
||||
```
|
||||
|
||||
### Fixed
|
||||
|
||||
- **web**: `/post/foo/` trailing slash now routes the same as `/post/foo` (dynamic and static routes). Root `/` unchanged. Query strings preserved after normalization.
|
||||
|
||||
## Ext pack v1.3.1 — 2026-10-08
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+2
-2
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "1.3.0"
|
||||
version = "1.4.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -603,7 +603,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.3.0"
|
||||
version = "1.4.4"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.3.0"
|
||||
version = "1.4.4"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
|
||||
@@ -149,15 +149,21 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.3.0)
|
||||
## 现状(v1.4.4)
|
||||
|
||||
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
|
||||
- **Ext pack 1.4.3**:修复 `agent.run` cold EFI(`` `self`.preflight `` + miss resolve `llm_free`);已并入 **1.4.4** · [agent-run-efi-resolve-bugs-2026-10.md](doc/research/agent-run-efi-resolve-bugs-2026-10.md)
|
||||
- **Agent/LLM 优化 O1–O5(v1.4.2)**:`ext/ai/sandbox` CoW · `agent.trial` / `sandbox=` · promote sandbox proof · `step_route` / EFI / cost · style lint · quarantine · [ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)
|
||||
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
|
||||
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)
|
||||
- **view 文档面(v1.3.3)**:Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI `#mq-view-trace` · 静态 `view output` / gh-pages 同源 · [view-document-annotations.md](doc/design/view-document-annotations.md)
|
||||
- **Engineering Knowledge(v1.3.0)**:EKC L0–L4 · `marqdo knowledge|find|reuse|duplicate|verify|…` · Agent `preflight` / REUSE→ADAPT→CREATE · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
- **Web Artifact(v1.2.0 · ADR 0007)**:Document/Endpoint 一等公民(`type: web|endpoint`)· facade `page`/`route`/`serve`/`render`/`inspect`/`use` · Resource 拆到 `ext/data`/`security`/`net` · 统一 View 表 · 破坏性移除 `compose_*`/`configure`
|
||||
- **AI 栈(v1.1.1)**:`ext/ai/llm` 语义 `ask`/`stream`/`collect` · Artifact Metadata Binding(`${env|arg|sys|secret}`)· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 `plugins/llm` Transport ABI
|
||||
- **AI 原生闭环(v1.1.0)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
|
||||
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
|
||||
- **`marqdo view`**:文档浏览器(**文档面** Structure + 标注 / 调用·循环帧 + 函数大纲/搜索 + Execution + Variables 浮窗;`view output` 同构)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页(默认挂钩 EKC)
|
||||
- **`marqdo knowledge` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`**:Engineering Knowledge Compiler([engineering-knowledge.md](doc/design/engineering-knowledge.md))
|
||||
@@ -176,7 +182,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(v1.3.0)
|
||||
### 如何使用最新 Marqdo(v1.4.4)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -191,7 +197,7 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.3.0 # 或留在 main
|
||||
git checkout v1.4.4 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -230,7 +236,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/v1.3.0
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.4.4
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.3.0"
|
||||
version = "1.4.4"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+37
@@ -1,3 +1,40 @@
|
||||
marqdo (1.4.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.4: Soft LLM transport errors (structured status=error);
|
||||
ext/ai table-first refactor (no json.set glue).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 14:40:00 +0800
|
||||
|
||||
marqdo (1.4.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.2: Agent/LLM optimize O1–O5 — sandbox trial opt-in,
|
||||
promote sandbox proof, step_route/EFI/cost, style lint, quarantine.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 11:51:05 +0800
|
||||
|
||||
marqdo (1.4.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.1: View annot leaders — SVG mid-to-mid (mark bottom-center
|
||||
to chip top-center), unify frame chip ids, L-to-R chip density.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 15 Oct 2026 20:40:00 +0800
|
||||
|
||||
marqdo (1.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.0: Prose-unified control flow — block formula % marqdo: var=,
|
||||
arm/loop narrative + foreach sugar, image writeback ,
|
||||
view inferred-param values; welcome pages on v0.3 prose surface.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 15:53:00 +0800
|
||||
|
||||
marqdo (1.3.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.3.3: Browse document-surface Structure — narration-preserving
|
||||
markers, branch/loop frame pickers, ViewExecutionReport JSON; static
|
||||
view output / gh-pages share the same render path as live view.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 13:20:00 +0800
|
||||
|
||||
marqdo (1.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.3.0: Engineering Knowledge Compiler (EKC) — L0–L4 catalog,
|
||||
|
||||
+7
-1
@@ -90,10 +90,16 @@
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
|
||||
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
|
||||
| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
|
||||
| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) |
|
||||
| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 |
|
||||
| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
|
||||
| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **Accepted**:Agent/LLM 优化 O1–O5 locked |
|
||||
| [roadmap/ext-ai-optimize.md](roadmap/ext-ai-optimize.md) | **O1–O5 实现路线**(沙盒接入→证明晋升→路由/成本→lint→隔离) |
|
||||
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
# 方案:智能体 / 大模型优化方向(代码即文档 · OKF · 沙盒)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · O1–O5 locked** |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 调研 | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
|
||||
| 路线 | [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md) |
|
||||
| 相关 | [ext-ai-sandbox.md](ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [okf.md](okf.md) · [engineering-knowledge.md](engineering-knowledge.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) · [ai-stack.md](../roadmap/ai-stack.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 方案立场
|
||||
|
||||
1. **强化差异化**:可执行 `.mq.md` 为权威;OKF 为复用;沙盒为证明;LLM 为探索。
|
||||
2. **不向隐藏 TOOL: 循环 / 向量权威回退。**
|
||||
3. 下列方向均为**可行**;推荐波次见 §3,最终裁剪由你选型。
|
||||
4. **不改** `doc/next/*`;落地时另开 roadmap 切片。
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构愿景(闭环)
|
||||
|
||||
```text
|
||||
目标 / 任务
|
||||
│
|
||||
▼
|
||||
EFI / OKF lookup ──hit──► llm_free / marqdo 执行 ──► writeback
|
||||
│ miss
|
||||
▼
|
||||
small-llm 路由 / 父分解
|
||||
│
|
||||
▼
|
||||
生成或修补 .mq.md(代码即文档风格)
|
||||
│
|
||||
▼
|
||||
sandbox.open → sandbox.run(caps)→ diff
|
||||
│
|
||||
├─ 失败 → writeback error / 隔离,不 promote
|
||||
└─ 成功 → 人审或策略 → commit → solidify / OKF promote
|
||||
│
|
||||
▼
|
||||
下次 REUSE(降本)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 可行方向全集
|
||||
|
||||
每个方向标注:解决的问题(Pn)、依赖、风险、粗粒度成本。
|
||||
|
||||
### A. 沙盒 × Agent 闭环
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **A1** | `step`/`plan` 默认经 sandbox 试跑再写实树 | P1 | 生成落 upper;绿才 `commit` | sandbox | 破坏现有金样默认 | 中 |
|
||||
| **A2** | Promote / solidify 强制 sandbox proof | P1 | OKF 写入前要求 proof fixture 绿 | sandbox+OKF | 过严挡复用 | 中 |
|
||||
| **A3** | Sandbox profile 表(caps 宣告) | P1/P3 | GFM 表声明 net/plugin/fs | sandbox | 表方言膨胀 | 低 |
|
||||
| **A4** | Guest 风格门禁(表优先、禁 json 胶水) | P5 | commit 前 lint / preflight | sandbox+parser | 误杀合法 json.parse | 中 |
|
||||
| **A5** | 会话 diff → view 审阅卡 | P1/P4 | HITL 看 CoW diff | view+sandbox | UI 工时 | 中高 |
|
||||
| **A6** | 多会话并行 CoW(fan-out 实验) | — | 每假设一 session | sandbox | 隔离/合并复杂 | 高 |
|
||||
|
||||
### B. OKF / EKC / 技能层
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **B1** | OKF 技能元数据:适用条件 / fixtures / sandbox_profile | P2 | frontmatter + 目录约定 | okf | 与 catalog 字段冲突 | 中 |
|
||||
| **B2** | Progressive disclosure(索引轻、正文按需 READ) | P2/P6 | 对齐 Anthropic Skills 层级 | agent A3 | 实现重复 | 中 |
|
||||
| **B3** | Skill Lift 评测(有/无技能配对) | P4 | harness 指标 | B1 评测 | 样本少噪声大 | 中 |
|
||||
| **B4** | 失败技能隔离(quarantine)+ 回归用例跟随血缘 | P1 | ForgeAgent 式 | OKF | 状态机复杂 | 中高 |
|
||||
| **B5** | near-match / soft_match 产品化默认开 | P6 | 已有 roadmap | okf-near | 误复用 | 低中 |
|
||||
| **B6** | EKC preflight 默认硬门槛(REUSE→ADAPT→CREATE) | P6 | step 前强制 EFI | EKC | 拖慢探索 | 中 |
|
||||
| **B7** | Capability 包与 `llm_free` 资源双向链接 | P2 | catalog L3↔任务包 | EKC+OKF | 图维护 | 中 |
|
||||
|
||||
### C. 大模型 / 路由 / 成本
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **C1** | 步骤级路由(lookup / patch / sandbox_run / net) | P3 | 扩展 route policy 表 | routing | 策略过拟合 | 中 |
|
||||
| **C2** | 总成本计量(含推理 token 膨胀)写回文档 | P7 | usage→writeback/metrics | llm result | 噪声 | 低中 |
|
||||
| **C3** | 用强模型「反思」优化 standing / policy `.mq.md`(类 GEPA) | P3/P5 | 离线优化环,产物仍是文件 | llm | 需评测集 | 高 |
|
||||
| **C4** | 高频 OKF 技能蒸馏/微调小模型(编译进权重) | — | 长期研究 | 数据+算力 | 运维重;偏离「源码权威」 | 很高 |
|
||||
| **C5** | Named model 绑定任务类型(fast=路由,reasoning=分解) | P3 | 已有 named handles 加深 | llm | 配置漂移 | 低 |
|
||||
| **C6** | Prompt document 强制:无参 ask 必须来自 type:prompt 文件 | P5 | 硬化 005 | llm | 破坏脚本式调用 | 低 |
|
||||
|
||||
### D. 代码即文档(产出质量)
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **D1** | 官方「可读 Marqdo」Skill 强化(表/链接取元/禁混名) | P5 | skills/marqdo 加厚 | skill | 模型仍违规 | 低 |
|
||||
| **D2** | AST/结构 lint:json.set 链、混 EN/ZH API | P5 | `marqdo lint` 或 sandbox 钩子 | parser | 误报 | 中 |
|
||||
| **D3** | 工作簿补丁只允许表驱动 / 命名槽写回 | P5 | 收紧 A0 补丁面 | agent | 表达力下降 | 中 |
|
||||
| **D4** | 示例库:sandbox+OKF+表风格 canonical demos | P4/P5 | examples/ | 文档 | 维护 | 低 |
|
||||
|
||||
### E. 评测与产品化
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **E1** | 完成 Wave B1 harness(constitution / writeback / call_site) | P4 | 已规划 | agent | — | 中 |
|
||||
| **E2** | 指标面板:ReuseRate / ProofRate / TokenCost | P4/P7 | metrics 写回或 catalog | agent | 虚荣指标 | 中 |
|
||||
| **E3** | Live 金样矩阵(sandbox 开/关 × 路由后端) | P4 | CI optional | CI | flaky | 中 |
|
||||
| **E4** | 教程:「只读一份 .mq.md 理解 Agent」 | — | doc/tutorial | 文档 | — | 低 |
|
||||
|
||||
### F. 明确不优先 / 需单独论证
|
||||
|
||||
| ID | 方向 | 理由 |
|
||||
|----|------|------|
|
||||
| **F1** | 第二套 Agent Framework(Python/TS 对象图权威) | 违宪 |
|
||||
| **F2** | 向量库升为记忆权威 | 违宪;可作证据工具 |
|
||||
| **F3** | 默认通用 shell Agent | 与 Marqdo-only 沙盒战略冲突 |
|
||||
| **F4** | 整库 `ext/web` 进默认沙盒 | 已否决 |
|
||||
| **F5** | 人人 microVM 本地默认 | DX 过重;留给 hosted |
|
||||
|
||||
---
|
||||
|
||||
## 3. 执行顺序(O1→O5 locked)
|
||||
|
||||
| 波次 | 方向组合 | 为何先做 |
|
||||
|------|----------|----------|
|
||||
| **O1** | A1 轻量(opt-in `sandbox=True`)+ A3 + D1 + D4 | 立刻接上刚落地的沙盒,风险可控 |
|
||||
| **O2** | A2 + B1 + B3 + E1 | 验证→晋升→可度量 Skill Lift |
|
||||
| **O3** | C1 + C2 + B6 | 降本与 EFI 硬门槛 |
|
||||
| **O4** | A4 + D2 + A5 | 质量门禁与人审 |
|
||||
| **O5** | B4 + C3 | 失败隔离与离线提示优化 |
|
||||
| **O∞** | C4 / A6 | 研究项,单独立项 |
|
||||
|
||||
切片实现见 [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收原则(任一波次)
|
||||
|
||||
- 金样:有/无沙盒、有/无 OKF hit、路由后端切换。
|
||||
- 指标:至少报告 ReuseRate 或 TokenCost 之一相对基线变化。
|
||||
- 文档:`.mq.md` 示例仍可读为 Markdown(表/链接取元,少 json 胶水)。
|
||||
- 红线:不改 `doc/next/*`;ext 不调 `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 落地
|
||||
|
||||
O1–O5 已锁定;实现见 [roadmap/ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。**仍不改** `doc/next/*`。
|
||||
@@ -0,0 +1,104 @@
|
||||
# Official AI sandbox (`ext/ai/sandbox`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted · implementing** |
|
||||
| Date | 2026-10-16 |
|
||||
| Related | [research/ai-agent-sandbox.md](../research/ai-agent-sandbox.md) · [roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [stdlib-writeback.md](stdlib-writeback.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. One-liner
|
||||
|
||||
**Agent-only Marqdo trial runtime:** capability-isomorphic to browser Wasm defaults, CoW workspace until explicit `commit`, author surface under `ext/ai` (not stdlib).
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals / non-goals
|
||||
|
||||
### Goals
|
||||
|
||||
| # | Goal |
|
||||
|---|------|
|
||||
| G1 | Open a CoW session over a workspace root; edits stay in upper until `commit` |
|
||||
| G2 | `run` executes `.mq.md` (or in-memory source) under deny-by-default caps with core `lib/*` usable |
|
||||
| G3 | `diff` / `discard` / `inspect` for review gates |
|
||||
| G4 | Stable `unavailable in sandbox` for plugin.load, exec foreign/subtask path|code|lang, net (default), `ext/web` server APIs |
|
||||
| G5 | Author API in `ext/ai/sandbox` via `plugins/agent` — **no** public `lib/sandbox` |
|
||||
|
||||
### Non-goals (this wave)
|
||||
|
||||
| # | Non-goal |
|
||||
|---|----------|
|
||||
| N1 | Embed wasmtime in CLI |
|
||||
| N2 | True Wasm ABI plugins (linalg/quantum) |
|
||||
| N3 | bwrap / microVM |
|
||||
| N4 | Full `ext/web` listen/DB/WS inside sandbox |
|
||||
| N5 | Symlink-forest workspace isolation |
|
||||
| N6 | Default host-proxy of all native ABI plugins |
|
||||
| N7 | Wire `agent.step`/`plan` through sandbox automatically (later) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Layering
|
||||
|
||||
```text
|
||||
ext/ai/sandbox.mq.md → plugin.load agent → sandbox_* ABI
|
||||
↓ host_query
|
||||
HostContext + CowSession
|
||||
(fs / writeback see upper)
|
||||
```
|
||||
|
||||
| Layer | May call `host_*` | Role |
|
||||
|-------|-------------------|------|
|
||||
| `ext/ai/sandbox` | **No** | Author facade |
|
||||
| `plugins/agent` | via `host_query` only | Register `sandbox_*`; forward to host |
|
||||
| `src/host` | — | CoW session store; fs/writeback intercept; nested `run` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Author API
|
||||
|
||||
EN: `ext/ai/sandbox.mq.md` · ZH: `ext/ai/沙盒.mq.md` (separate files, no mixed names in one module).
|
||||
|
||||
| Method | Params | Result |
|
||||
|--------|--------|--------|
|
||||
| `open` | optional `root=` (default entry dir / cwd) | map `{ id, root }` |
|
||||
| `write` | `id=`, `path=`, `text=` | none |
|
||||
| `read` | `id=`, `path=` | text |
|
||||
| `remove` | `id=`, `path=` | none (whiteout) |
|
||||
| `diff` | `id=` | list of `{ path, kind: write\|remove }` |
|
||||
| `commit` | `id=` | `{ ok, applied }` |
|
||||
| `discard` | `id=` | `{ ok }` |
|
||||
| `run` | `id=`, `path=` **or** `source=` | `{ ok, value, stdout?, error? }` |
|
||||
| `inspect` | `id=` | caps, root, change count, notes |
|
||||
|
||||
Default `run` caps: `fs_write=true` (CoW only), `exec=false`, `net=false`, `plugin=false`.
|
||||
|
||||
---
|
||||
|
||||
## 4. CoW semantics
|
||||
|
||||
- **lower** = real workspace root (read-through).
|
||||
- **upper** = session map path → bytes.
|
||||
- **whiteout** = logical deletes; reads miss; commit unlinks lower.
|
||||
- No symlink-as-isolation; resolve paths under root; reject `..` escape.
|
||||
- Until `commit`, host tree unchanged (verifiable with `git status` / file mtime).
|
||||
|
||||
---
|
||||
|
||||
## 5. Hard bans
|
||||
|
||||
1. No public `lib/sandbox`.
|
||||
2. No symlink forest as the isolation story.
|
||||
3. No silent success when capability missing — diagnose `unavailable in sandbox`.
|
||||
4. `ext/**` must not call `host_*`.
|
||||
5. Do not treat empty `# main` as sandbox completeness.
|
||||
|
||||
---
|
||||
|
||||
## 6. ABI / host_query
|
||||
|
||||
Plugin exports (registered on agent plugin): `sandbox_open`, `sandbox_write`, `sandbox_read`, `sandbox_remove`, `sandbox_diff`, `sandbox_commit`, `sandbox_discard`, `sandbox_run`, `sandbox_inspect`.
|
||||
|
||||
Implementation: each forwards to allowlisted `host_query` names of the same stem (e.g. `sandbox_open`), which mutate the process-local CoW store and (for `run`) invoke nested capture with a sandboxed `HostContext`.
|
||||
@@ -0,0 +1,60 @@
|
||||
# 块公式元数据绑定 · 控制流叙述统一
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | Active |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 块公式 `% marqdo: var=`
|
||||
|
||||
在 `$$…$$` 块内用 **TeX 行注释**声明绑定名(渲染通常不可见;运行时剥离后解析公式体):
|
||||
|
||||
```markdown
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
```
|
||||
|
||||
- 指令:`% marqdo:` + 空白 + `var=<ident>`;未知键 → Error。
|
||||
- 可无前置 `` `f` = ``;若同时写空 RHS 与 `var=`,**同名允许、异名 Error**。
|
||||
- **保留**旧空 RHS + 后随 `$$`。
|
||||
- **不做**:行内 `$% marqdo:…$`;\`\`\` 代码围栏内语言注释 meta(本波)。
|
||||
- 行内公式继续传统绑定:`` `g` = $x+1$ ``(单 `$…$` → `formula`)或 `` `g` = $$x+1$$ ``。
|
||||
|
||||
无名叙述区 `$$` 仍仅展示;可执行区裸块既无空 RHS 又无 `var=` → Error。
|
||||
|
||||
---
|
||||
|
||||
## 2. 臂 / 循环体叙述(与函数体同权)
|
||||
|
||||
`parse_indented_body` 与函数体相同:消费 `` `名` `` / `**代码**` / `*返回*`;纯叙述跳过。
|
||||
斜体返回结束**当前臂或当前循环体**,不结束外层函数。
|
||||
|
||||
---
|
||||
|
||||
## 3. 循环头
|
||||
|
||||
| 面 | 写法 | 说明 |
|
||||
|----|------|------|
|
||||
| **推荐** | `- [项](xs)` / `- [`项`](`xs`)` | 支持嵌套 |
|
||||
| 中文糖 | `- 对`xs`的每一项`项`` | 可选后缀「遍历」 |
|
||||
| 英文糖 | `- for each `item` in `xs`` | 大小写不敏感 `for each` / `in` |
|
||||
|
||||
糖与链接头语义相同,可混用嵌套。
|
||||
|
||||
---
|
||||
|
||||
## 4. 分支条件行叙述
|
||||
|
||||
结构行仍以 `1.` / `2.` 开头。条件提取顺序:
|
||||
|
||||
1. 整段可解析为表达式(现状);
|
||||
2. 行内粗体代码条件 `**`n` > 0**`;
|
||||
3. 剥离「当/若/如果/when/if」与「时/则」后,将「大于/小于/等于…」映射为运算符再解析。
|
||||
|
||||
else:`N. *`(可夹「否则」等叙述,条件位仍为 `*`)。
|
||||
禁止无标记自然语言整句当条件。
|
||||
@@ -215,7 +215,9 @@ v0.3:
|
||||
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
|
||||
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
|
||||
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
|
||||
| ` ```lang ` | 外联(不变) |
|
||||
| ` ```lang ` | 外联(不变;绑定仍用 `` `名` = `` + 围栏) |
|
||||
| `$$` 内 `% marqdo: var=名` | 块公式绑定([fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)) |
|
||||
| `- 对`集`的每一项`项`` / `for each` | foreach 叙述糖;推荐 `- [项](集)` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
|
||||
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
|
||||
|
||||
|
||||
+18
-2
@@ -314,10 +314,15 @@ type: Marqdo Agent Skill
|
||||
title: <短名>
|
||||
sig: <12hex>
|
||||
resource: ../../resources/<slug>.mq.md
|
||||
status: stable | candidate
|
||||
status: stable | candidate | quarantine
|
||||
llm_free: true | false
|
||||
quality: <int>
|
||||
hits: <int>
|
||||
# O2 optional metadata (from workbook frontmatter; see §7.5):
|
||||
applies_when: <text condition or tag>
|
||||
fixtures: <relative .mq.md proof path>
|
||||
sandbox_profile: default | readonly | <name>
|
||||
proof: <relative .mq.md> # alias of fixtures for sandbox gate
|
||||
generated:
|
||||
by: marqdo-agent/plan
|
||||
at: <ISO8601>
|
||||
@@ -331,7 +336,7 @@ verified:
|
||||
Prefer spawning `resource` over re-planning.
|
||||
```
|
||||
|
||||
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。
|
||||
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。**O2:** `agent_kb_promote` 默认要求 sandbox proof(`proof` / `fixtures` / workbook 本身经 `sandbox.run` 成功)才写入;失败返回 `promoted: false` / `reason: sandbox_proof_failed`。传 `require_proof=false` 仅用于明确豁免。
|
||||
|
||||
### 7.3 任务签名 → Concept 路径
|
||||
|
||||
@@ -401,6 +406,17 @@ Prefer spawning `resource` over re-planning.
|
||||
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
|
||||
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
|
||||
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
|
||||
| **证明晋升(O2)** | `applies_when` / `fixtures` / `sandbox_profile` / `proof` 写在技能与 workbook frontmatter;promote 前 `sandbox.run` 绿才 `llm_free` |
|
||||
| **隔离(O5)** | 失败技能 `status: quarantine`;回归 fixture 跟随 slug |
|
||||
|
||||
### 7.5a 技能 frontmatter 约定(O2 B1)
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `applies_when` | 适用条件(短文本 / 标签);路由与 harness 可读 |
|
||||
| `fixtures` | 相对路径:sandbox 证明用 `.mq.md` |
|
||||
| `sandbox_profile` | `default` / `readonly` / 其它 `sandbox.profile` 名 |
|
||||
| `proof` | 与 `fixtures` 同义;promote 优先读 `proof` 再 `fixtures`,否则跑 workbook 自身 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -34,7 +34,16 @@
|
||||
|
||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
||||
|
||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
||||
**推荐(块内元数据)**:在 `$$` 体内用 TeX 注释声明变量(见 [fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)):
|
||||
|
||||
````markdown
|
||||
$$
|
||||
% marqdo: var=f
|
||||
sin(x) + x
|
||||
$$
|
||||
````
|
||||
|
||||
**兼容**:空 RHS 赋值后跟展示数学块(与 `` `xs` = `` 后跟表格一致):
|
||||
|
||||
````markdown
|
||||
# main
|
||||
@@ -52,13 +61,14 @@ $$
|
||||
也支持:
|
||||
|
||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`(历史面)
|
||||
- 行内:`` `g` = $x+1$ `` 或 `` `g` = $$x+1$$ ``
|
||||
|
||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
||||
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区裸 `$$` 若既无空 RHS 又无 `% marqdo: var=` → 报错。
|
||||
|
||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
||||
**行内 `$…$`:** 传统绑定 `` `名` = $…$ `` → `formula`;**不**使用 `$% marqdo:…$`(会破坏 Markdown/TeX 识别)。
|
||||
|
||||
### 2.3 从文本构造
|
||||
|
||||
|
||||
@@ -8,9 +8,11 @@
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` → `marqdo view`(及静态 `view output`)在对应语句下显示 **output-card**,并在源码面用 **writeback** 样式标出块本身。
|
||||
|
||||
## 存储格式
|
||||
## 存储格式(两种,可并存)
|
||||
|
||||
### 1. HTML 注释(文本 / 结构化输出)
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
@@ -30,11 +32,26 @@ pending
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
### 2. Markdown 图片(生成图 / 审计友好)
|
||||
|
||||
当 `value` **看起来像图片引用**(扩展名 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.svg` / …,或 `data:image/…`)时,`record` **自动**写成:
|
||||
|
||||
```markdown
|
||||

|
||||

|
||||
```
|
||||
|
||||
- 普通 Markdown 预览即可看见图;view / 静态站额外加 writeback 标记与 output-card 中的 `<img>`。
|
||||
- 非图片路径仍走注释块;把非图片硬写成 `` 时扫描会忽略(校验失败)。
|
||||
- `list` / `scan_path` 结果带 `kind`: `comment` | `image`。
|
||||
|
||||
### 共用规则
|
||||
|
||||
- 标记字为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
- 默认在**调用行下方**插入或替换紧邻**无键**块
|
||||
- `at_end=true`:替换文件末尾的**无键**块
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
|
||||
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽;`ensure` 在缺失时写入占位且不覆盖已有正文
|
||||
- `line=` / `行=`:显式锚点行号;主机侧有全局互斥锁
|
||||
|
||||
### 替换跨度与空行
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
||||
| 相关 | [view.md](view.md) · [view-static-interactive.md](view-static-interactive.md)(静态交互 / 公式代码视觉 · Proposal) · 源目录 [`public/`](../../public/) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,14 +4,14 @@
|
||||
|---|---|
|
||||
| 状态 | **v1(独立 debug 页)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [view-document-annotations.md](view-document-annotations.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
|
||||
## 分工
|
||||
|
||||
| 命令 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
||||
| `marqdo view` | 文档浏览器:**叙述保真文档面** Structure + Execution + Source;函数大纲与搜索;跑后引出标注;**无断点**(见 [view-document-annotations.md](view-document-annotations.md)) |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;AST Structure + BP;**仅 live** |
|
||||
|
||||
静态 `gh-pages` / `view output` **不能**真断点。
|
||||
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
# View:文档面与结果引出标注
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [view-prose-annot-gaps.md](view-prose-annot-gaps.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 是叙述与程序的同一载体。`marqdo view` 的 Structure 必须**保真叙述**,并在可执行标记旁展示运行结果。
|
||||
|
||||
旧 Browse Structure 用 AST 卡片重建语句,并用 `emit_comments` 只插入**语句行之前**的注释。当叙述与 `**…**` / `*…*` / `` `名` `` 在同一行时,该行被 Stmt 占用,叙述被丢弃——信息密度接近 debug,不适合文档浏览。
|
||||
|
||||
## 2. 模式分工
|
||||
|
||||
| 命令 | Structure | 叙述 | 结果 |
|
||||
|------|-----------|------|------|
|
||||
| `marqdo view`(Browse) | **文档面** | 保留并为主 | 跑后引出标注(callout + CSS L-leader) |
|
||||
| `marqdo debug` | AST 卡片 + BP gutter | 弱化/可折叠 | Variables / 步进;不做文档 callout |
|
||||
|
||||
断点与逐步执行**仅**在 debug。静态 `view output` 与 live view **共用** Browse 文档面渲染。
|
||||
|
||||
## 3. 视觉语法
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注
|
||||
```
|
||||
|
||||
1. 叙述正文正常排版(Markdown)。
|
||||
2. 可执行片段高亮,并带底部分割线(underline)。
|
||||
3. 段落下方 **annotation band** 放结果 callout。
|
||||
4. **CSS L-leader**(绝对定位小盒 + `border-left` + `border-bottom`)连接锚点与 callout。**不使用 SVG。**
|
||||
5. 拥挤 / 极窄屏 / `prefers-reduced-motion`:取消长横折,改为编号 keyed 列表。
|
||||
|
||||
关联强度(递减):同色 underline + callout 色条 + label → CSS L-leader → keyed 编号。
|
||||
|
||||
对齐 [view.md](view.md) HIG:系统字体、无外链、浅色、克制装饰。
|
||||
|
||||
## 4. 文档面渲染
|
||||
|
||||
实现:`src/view/document.rs`;Browse 入口经 `render_module_structure` 调用。
|
||||
|
||||
| 源内容 | 呈现 |
|
||||
|--------|------|
|
||||
| 纯叙述段 | Markdown HTML;无 `comment` badge / 厚卡片 |
|
||||
| 含 `ProseBit` 的行 | 原文保留;Decl / BoldCode / ItalicReturn 包 `mark.mq-anchor`(字节偏移来自 `scan_prose_line`) |
|
||||
| 整行结构(`#` / `>` / `-` / `1.` / 表) | 表面语法保真(见 [view-markup-surface.md](view-markup-surface.md));整句可作锚点 |
|
||||
| 函数标题 | 轻量 heading + `id="fn-{line}"`(大纲跳转不变) |
|
||||
|
||||
Debug 仍走 `render_module_structure_mode(..., Debug)` 的 AST 卡片路径。
|
||||
|
||||
## 5. ViewAnnot
|
||||
|
||||
跑后(或 `--no-exec` 时为空)组装标注集,嵌入文档面 `data-*` 与 band HTML。
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `id` | 稳定短 id(页内唯一) |
|
||||
| `kind` | `bind` · `return` · `call` · `expr` · `branch` · `loop` · `writeback` |
|
||||
| `anchor_line` | 1-based 源行 |
|
||||
| `anchor_byte_start` / `anchor_byte_end` | 行内字节范围(可选;整行锚点可省略 end) |
|
||||
| `label` | 短标题(名 / return / arm / loop) |
|
||||
| `value` | 截断显示 |
|
||||
| `detail` | 完整文本(inspect) |
|
||||
|
||||
| kind | 数据来源 | 锚点 |
|
||||
|------|----------|------|
|
||||
| `bind` | **StmtEvent post-stmt**(赋值执行后的值);禁止用入口终态回填初始化行 | 该赋值行 |
|
||||
| `return` | 返回事件或入口返回 | ItalicReturn / Return |
|
||||
| `call` / `expr` / `writeback` | writeback 槽、调用摘要 | 语句行或 BoldCode |
|
||||
| `branch` | `ViewTrace`:命中 arm、次数 | 条件 / arm |
|
||||
| `loop` | `ViewTrace`:迭代次数、末次 item | While / ForEach 头 |
|
||||
|
||||
标记面、结构块、多调用帧与 AI JSON 见 [view-execution-trace.md](view-execution-trace.md)。
|
||||
|
||||
`ViewTrace` 由 tree 解释器在 capture 时静默收集,**不**写入 stderr;与 `trace_eval` 调试轨迹分离。Bytecode 后端可暂无 trace(标注降级为 writeback)。
|
||||
|
||||
## 6. 布局与密度
|
||||
|
||||
- 每段默认最多 **4** 个常显 callout;其余 hover / 「show more」。
|
||||
- Leader:按锚点 x 排序 callout,避免交叉;窄屏改为短竖线 + 堆叠。
|
||||
- 客户端:`ResizeObserver` 重算 leader 盒的 `left/top/width/height`。
|
||||
- 静态导出:页载 JS 跑一次布局。
|
||||
|
||||
右侧 **Variables** 仍为全集绑定;callout 为就地摘要,点击可打开同一 inspect。
|
||||
|
||||
## 7. 非目标
|
||||
|
||||
- 不在 view 内做断点 / 单步(见 [view-debug.md](view-debug.md))。
|
||||
- 不新增作者侧标注 DSL / frontmatter 指令。
|
||||
- 不引入外链字体、npm 组件或 SVG leader。
|
||||
- 不把 DB/auth 等塞进 view 壳层。
|
||||
|
||||
## 8. 验收
|
||||
|
||||
1. `inc-prose.mq.md`:叙述「对于输入变量…」完整可见;`n` / `n=n+1` / 返回高亮。
|
||||
2. 跑完后:值经 underline + CSS L-leader 连到下方标注(无 SVG)。
|
||||
3. 分支/循环样例:可见命中 arm 与迭代次数(有 ViewTrace 时)。
|
||||
4. `marqdo debug` 仍为 AST + 断点;叙述不抢主视觉。
|
||||
5. 无外链字体/新依赖;`view output` 可离线打开。
|
||||
|
||||
## 9. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:文档面、ViewAnnot、CSS L-leader、与 debug 分工 |
|
||||
| 2026-10-15 | bind = post-stmt;交叉链 view-execution-trace |
|
||||
@@ -0,0 +1,103 @@
|
||||
# View:执行轨迹与文档面保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [view.md](view.md) · [view-markup-surface.md](view-markup-surface.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`marqdo view` Browse Structure 必须同时做到:
|
||||
|
||||
1. **标记面**:变量名 / 可执行语句 / 返回值按表面渲染(无源码定界符字面量)。
|
||||
2. **结构块**:GFM 表、循环(`-`)、分支(`1.`)有正确 HTML 与缩进。
|
||||
3. **语句后值**:赋值行标注该语句执行后的值,不用入口终态回填。
|
||||
4. **执行臂**:高亮实际走的分支臂。
|
||||
5. **多调用帧**:同函数多次调用可用下拉切换经历。
|
||||
6. **AI 可读**:与 HTML 同源的 `ViewExecutionReport` JSON。
|
||||
|
||||
Debug 仍用 AST 卡片 + 断点;不做文档 callout。
|
||||
|
||||
## 2. 标记面
|
||||
|
||||
| 源标记 | 显示(无定界符) | class |
|
||||
|--------|------------------|-------|
|
||||
| `` `名` `` / `` `名`=默认 `` | `名`(默认次要后缀) | `mq-anchor mq-decl` |
|
||||
| `**…**`(可执行) | 内层文本 | `mq-anchor mq-code` |
|
||||
| `*…*`(返回) | 内层文本 | `mq-anchor mq-return` |
|
||||
|
||||
`data-byte-start/end` 仍为源码字节偏移(供 CSS L-leader)。软强调不进 anchor。
|
||||
|
||||
## 3. 结构块
|
||||
|
||||
| 块 | 呈现 |
|
||||
|----|------|
|
||||
| GFM 表 | `<table class="doc-table">` |
|
||||
| `-` 循环 | `<ul class="doc-loop">`,体按源缩进 `--doc-indent` |
|
||||
| `1.` 分支 | `<ol class="doc-branch">`;命中 `arm-taken`,未走 `arm-miss` |
|
||||
| 公式 / 外联代码 | 现有 formula-card / code-card |
|
||||
| `>` 调用 | 表面高亮,非整行灰 code |
|
||||
|
||||
## 4. StmtEvent / CallFrame
|
||||
|
||||
解释器 capture 时静默采集(非 `trace_eval` stderr):
|
||||
|
||||
```text
|
||||
StmtEvent {
|
||||
line, kind, // assign | return | call | branch | loop | bind_ref
|
||||
name?, value_after?, // post-stmt 或求值结果
|
||||
arm_index?, iter?,
|
||||
call_id // 当前用户函数调用帧
|
||||
}
|
||||
|
||||
CallFrame {
|
||||
call_id, fn_name, fn_line, ordinal,
|
||||
args_brief, // 短摘要供下拉
|
||||
events[] // 或全局 events 用 call_id 过滤
|
||||
}
|
||||
```
|
||||
|
||||
- Assign → 写入后的值挂在**该行**。
|
||||
- 循环内多次写入:UI 默认末次;可带次数。
|
||||
- Branch → taken `arm_index` + 条件摘要。
|
||||
- 进入用户函数分配 `call_id`;`# main` 单帧无下拉。
|
||||
|
||||
## 5. ViewExecutionReport(AI)
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"path": "…",
|
||||
"ok": true,
|
||||
"calls": [{ "call_id": 1, "fn": "等级说明", "ordinal": 1, "args_brief": "等级=及格" }],
|
||||
"events": [{ "line": 24, "kind": "assign", "name": "总分", "value_after": "0", "call_id": 0 }],
|
||||
"bindings_final": { "均分": "73", "等级": "及格" }
|
||||
}
|
||||
```
|
||||
|
||||
产出:页内 `#mq-view-trace` JSON;live `GET /api/view-trace?path=`;SSE `done.trace_json`。
|
||||
|
||||
## 6. UI
|
||||
|
||||
- 函数标题旁 `<select class="call-picker">`(调用数 ≥ 2)。
|
||||
- 循环头旁 `<select class="loop-picker">`(迭代数 ≥ 2);默认最后一轮;摘要 `分 = 分数表[i] · value`。
|
||||
- **源码常显**:切换帧只改 chip / 臂高亮,不 `hidden` 结构节点。详见 [view-frame-selection.md](view-frame-selection.md)。
|
||||
- CSS L-leader(非 SVG);拥挤 keyed 降级。
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. 无字面 `**` / 返回定界 `*` / 变量外层 `` ` ``(Source 除外)。
|
||||
2. 表为真表格;循环/分支有缩进列表;未选中臂源码仍可见。
|
||||
3. `总分 = 0` 标注 `0`,非终态累加。
|
||||
4. 命中臂可视化;多调用下只显示当前帧的 taken。
|
||||
5. 循环可按迭代切换;JSON 含 `loops`;单测覆盖。
|
||||
|
||||
## 8. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:标记面、结构块、StmtEvent、CallFrame、AI 报告 |
|
||||
| 2026-10-15 | 帧选择保真:call_id 分支、LoopFrame、源码常显 |
|
||||
@@ -0,0 +1,123 @@
|
||||
# View:调用帧 / 循环帧选择与结构保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-execution-trace.md](view-execution-trace.md) · [view-document-annotations.md](view-document-annotations.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题(对照实测)
|
||||
|
||||
1. **结构缺失**:切换函数调用下拉时,JS 按 `data-call-id` **隐藏** `.doc-exec`。未在本帧执行的分支臂体(赋值/返回)只有其它帧的 call_id,或仅有执行帧的 id → **未选中臂的源码被藏掉**,看起来像「臂消失 / 代码没渲染」。
|
||||
2. **调用记录混叠**:`Branch` 标注未带 `call_id`;`taken_arms` 按行号只保留最后一次命中。多帧下同一分支同时出现 `arm 1 taken` 与 `arm 2 taken`。
|
||||
3. **循环无帧**:循环只有总次数摘要;无法按迭代查看;`` - [分](分数表) `` 不能展示「当前是集合第几个元素」。
|
||||
|
||||
## 2. 定稿原则
|
||||
|
||||
| 原则 | 含义 |
|
||||
|------|------|
|
||||
| **源码常显** | 表 / 列表 / 分支臂 / 语句源码**永不**因帧选择 `hidden` |
|
||||
| **轨迹随帧** | 标注 chip、臂高亮、变量值随「当前调用帧 / 当前迭代」变化 |
|
||||
| **默认末帧** | 函数默认最后一次调用;循环默认最后一次迭代 |
|
||||
| **一帧一真相** | 同时只展示一个 call_id(函数)或一个 (loop_id, iter)(循环)的轨迹 |
|
||||
|
||||
## 3. 函数调用帧
|
||||
|
||||
### 数据
|
||||
|
||||
`BranchHit` / 相关 `StmtEvent` 必须带 `call_id`。`ViewAnnot` 的 branch/bind/return 同样带 `call_id`。
|
||||
|
||||
### UI
|
||||
|
||||
- 函数标题旁 `<select class="call-picker" data-fn="…" data-scope="fn">`
|
||||
- 选项:`1: 等级=及格` / `2: 等级=优秀`
|
||||
- 默认选中最后一次
|
||||
|
||||
### 客户端(`applyCallFrame`)
|
||||
|
||||
1. 读 `#mq-view-trace` JSON。
|
||||
2. 过滤 `events` where `call_id == selected`。
|
||||
3. **不**设置结构节点 `hidden`。
|
||||
4. 更新该函数作用域内:
|
||||
- `.annot-chip[data-call-id]`:仅显示匹配帧;无 call_id 的结构说明类可保留
|
||||
- `.doc-branch[data-line]`:按该帧的 branch 事件设置 `arm-taken` / `arm-miss`(全部臂仍可见)
|
||||
- 绑定 chip 的 `.annot-value`:用该帧 assign/return 事件刷新(同名同行取末次)
|
||||
|
||||
## 4. 循环迭代帧
|
||||
|
||||
### 数据
|
||||
|
||||
```text
|
||||
LoopFrame {
|
||||
loop_id, line,
|
||||
item_name?, // "分"
|
||||
collection?, // "分数表"
|
||||
iterations: [{ index, item_value, call_id }] // index 0-based
|
||||
}
|
||||
```
|
||||
|
||||
`StmtEvent` 增加可选 `loop_id`;循环体内事件带 `iter`(1-based 或 0-based,JSON 内统一 **0-based index**)。
|
||||
|
||||
### UI
|
||||
|
||||
- 循环头(`- [分](分数表)`)旁:`<select class="loop-picker" data-loop-id="…">`
|
||||
- 选项:`迭代 1: 分=92` … `迭代 4: 分=88`
|
||||
- 默认最后一次
|
||||
- 头旁摘要 chip:`分 = 分数表[3] · 88`(下标 0-based 显示为 `[i]`)
|
||||
|
||||
### 客户端(`applyLoopFrame`)
|
||||
|
||||
1. **只显示当前迭代**:带 `data-iter` 的 chip 仅保留选中项;其余 `hidden` + `is-frame-hidden`(SSR 默认已按末轮预隐藏)。
|
||||
2. 更新头摘要 chip(无 `data-iter`)为当前选项文案。
|
||||
3. 不隐藏循环体源码。
|
||||
|
||||
## 5. 分支臂渲染
|
||||
|
||||
- 所有臂(含 else)**始终**渲染完整头 + 体(含 `*返回*` / 赋值)。
|
||||
- `arm-miss` 仅降低不透明度,**不** `display:none` / `hidden`。
|
||||
- 高亮仅反映**当前帧**的 taken `arm_index`。
|
||||
|
||||
## 6. AI JSON 增量
|
||||
|
||||
`ViewExecutionReport` 增加:
|
||||
|
||||
```json
|
||||
"loops": [{
|
||||
"loop_id": 1,
|
||||
"line": 27,
|
||||
"item": "分",
|
||||
"collection": "分数表",
|
||||
"iters": [{ "index": 0, "value": "92" }, { "index": 3, "value": "88" }]
|
||||
}]
|
||||
```
|
||||
|
||||
`events[].call_id` 必填;循环体内事件带 `loop_id` + `iter`(index)。
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. 未选中分支臂源码始终可见(含返回句)。
|
||||
2. 切换「等级说明」调用:只显示该帧的 arm taken;变量/返回值对应该帧。
|
||||
3. 循环下拉默认最后一轮;`分 = 分数表[3] · 88`;切换迭代后体内累加值变化。
|
||||
4. `#mq-view-trace` 含 `loops` 与带 `call_id` 的 branch 事件。
|
||||
5. `cargo test --lib view::` 全绿。
|
||||
|
||||
## 8. 开发计划(已执行)
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| D0 | 本文档 + `view-execution-trace.md` 交叉引用 | ✅ |
|
||||
| D1 | `BranchHit.call_id`;`LoopFrame` / `LoopIter`;`StmtEvent.loop_id` | ✅ |
|
||||
| D2 | 解释器:foreach/while 推栈;BindRef `分=分数表[i]`;assign 带 iter | ✅ |
|
||||
| D3 | `build_view_annots`:分支带 call_id;LoopFrame 选项;报告 JSON `loops` | ✅ |
|
||||
| D4 | 文档面:源码不贴 `data-call-ids`;call picker `value=call_id`;loop picker;SSR taken=末帧 | ✅ |
|
||||
| D5 | JS:`applyCallFrame` / `applyLoopFrame` — 只滤 chip + 重算 arm,不 hidden 结构 | ✅ |
|
||||
| D6 | 单测:多调用不同臂、loop 末项、HTML 三臂返回 + picker | ✅ |
|
||||
|
||||
## 9. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:源码常显、帧过滤、循环迭代 picker |
|
||||
| 2026-10-15 | 按计划落地 D1–D6 |
|
||||
@@ -0,0 +1,145 @@
|
||||
# View:叙述面标注缺口(prose annot gaps)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [view-frame-selection.md](view-frame-selection.md) · [view-execution-trace.md](view-execution-trace.md) |
|
||||
|
||||
> **定位**:对既有文档面设计的**缺口专章**——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何「改了却几乎没变化」
|
||||
|
||||
| 原因 | 说明 |
|
||||
|------|------|
|
||||
| 错二进制 | PATH 上的 `marqdo` 可能仍是旧版(如 1.3.0);改动在源码 / `./target/debug/marqdo`。验收必须用 `cargo build && ./target/debug/marqdo view …` |
|
||||
| Chip 被溢出藏掉 | 同 band 堆多帧 return/print/who;`MAX_VISIBLE_ANNOTS=4` 把当前帧的 `who` 打成 `annot-chip-overflow`(`display:none`);帧切换不重算溢出 |
|
||||
| L-leader 几何错位 | `initAnnotLeaders` 里 `y0=0` 只在 `.annot-band` 顶画短折,**连不到**上方 underline;窄屏或 chip>4 时整段关掉 leaders |
|
||||
| 旧静态快照 | gh-pages / 旧 `view output` 不会自动刷新 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标视觉语法(既有,不新造)
|
||||
|
||||
锚定 [view-document-annotations.md](view-document-annotations.md) §3:
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注 chip
|
||||
```
|
||||
|
||||
- underline:`mark.mq-anchor.mq-{decl|code|return}`
|
||||
- band:段落下方 `.annot-band` → leaders + chips
|
||||
- L-leader:CSS `border-left` + `border-bottom`(禁止 SVG)
|
||||
- 公式/代码:[view-static-interactive.md](view-static-interactive.md) G3 **一层主视觉**;卡下不叠 Bind dump
|
||||
- 帧:[view-frame-selection.md](view-frame-selection.md) **源码常显、只滤 chip**;默认末帧
|
||||
|
||||
---
|
||||
|
||||
## 3. 管线
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
CLI["marqdo view / view output"] --> build["build_file_view"]
|
||||
build --> cap["run_file_capture"]
|
||||
cap --> annot["build_view_annots"]
|
||||
annot --> doc["document::render_module_document"]
|
||||
doc --> page["html.rs page_file"]
|
||||
page --> js["initAnnotLeaders + initCallPickers"]
|
||||
```
|
||||
|
||||
| 步骤 | 位置 |
|
||||
|------|------|
|
||||
| CLI / 导出 | `src/main.rs` · `src/view/mod.rs` · `src/view/output.rs` |
|
||||
| Capture + Call 事件 | `src/interp.rs` |
|
||||
| Annot 组装 | `src/view/annot.rs` `build_view_annots` |
|
||||
| 文档面 HTML | `src/view/document.rs` |
|
||||
| 卡片 chrome | `src/view/render.rs` `render_*_assign_card` |
|
||||
| CSS / leader JS | `src/view/html.rs` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 四条用户问题 → 根因 → 验收
|
||||
|
||||
复现源:`public/00-welcome.mq.md` · `public/00-欢迎.mq.md`
|
||||
对照金样:`tests/view/document-annot-demo.mq.md` · `tests/markup-v03/inc-prose.mq.md`
|
||||
|
||||
### P1 — 叙述与代码同段时信息不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | underline 在,chip / 连线弱或无 |
|
||||
| 根因 | `html.rs` `initAnnotLeaders`:`y0=0` 相对 band;`document.rs` `MAX_VISIBLE_ANNOTS` 把当前帧 chip 溢出;PATH 旧 CLI |
|
||||
| 目标 | 同 `inc-prose`:underline + L-leader(从锚点底到 chip)+ 可见 chip |
|
||||
| 验收 | `./target/debug/marqdo view public/00-welcome.mq.md`:主文 `**greet…**` 与 `## greet` 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
|
||||
|
||||
### P2 — 函数内变量不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `` `who` `` 有浅蓝 underline,无值 chip |
|
||||
| 根因 | bind chip 存在但带 `annot-chip-overflow`;`applyCallFrame` 只 `hidden` 非选中帧,不解除当前帧 overflow |
|
||||
| 目标 | 选中调用帧时常显 `who` · `print` · `return` 各一枚 |
|
||||
| 验收 | 切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
|
||||
|
||||
### P3 — ` ```text ` 渲染不一致
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 变成内联 `text marqdo ext add…`,无卡片 |
|
||||
| 根因 | Comment 围栏若进 `flush_para` → `join(" ")` → pulldown 当 inline code;应走 `render_narrative_fence` |
|
||||
| 目标 | 与 bound python 同 `.code-card` chrome(badge + `pre.code-body`),**无** Run/foot |
|
||||
| 验收 | welcome install 段:`data-lang="text"` + 两行 `marqdo ext add`;无 `<code>text marqdo` |
|
||||
|
||||
### P4 — 函数引用 / 代码卡未渲染
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `**greet who=…**` 无结果;或 `hi` python 只见头/Run、不见源码 |
|
||||
| 根因 | 同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
|
||||
| 目标 | 主文两 greet 各有 call chip(stdout 摘要);`hi` = `render_code_assign_card` head→body→foot;静态藏 Run |
|
||||
| 验收 | 两枚 greet mark 均有非空 `data-annot-id`;`code-body` 含 `hello-from-python`;`MARQDO_VIEW_LIVE=false` 无 Run 按钮 |
|
||||
|
||||
### call_id 语义(写死)
|
||||
|
||||
| 位置 | call_id |
|
||||
|------|---------|
|
||||
| 主文 `**greet…**` 的 call chip | 入口帧(`# main` 的 call);结果为 stdout/返回摘要 |
|
||||
| `## greet` 体内 print / who / return | callee 的 CallFrame id;跟函数标题旁 picker |
|
||||
|
||||
---
|
||||
|
||||
## 5. 修复约定(实现红线)
|
||||
|
||||
1. **帧感知密度**:band 内按选中 `call_id` 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + `layoutAll()`。
|
||||
2. **Leader 容器**:提升到 `.doc-block`(prose + band);`y0` = 锚点底相对 block;按锚点 x 排序再画线。
|
||||
3. **卡片**:只复用 Browse `render_*_assign_card` / `render_narrative_fence` + `html.rs` `.code-*` / `.formula-card`;本波不改 Debug AST 路径(除非回归红)。
|
||||
4. **静态 Run**:`MARQDO_VIEW_LIVE=false` 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
|
||||
5. **非目标**:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收命令
|
||||
|
||||
```bash
|
||||
cargo build -q
|
||||
./target/debug/marqdo version # 须为当前工作树版本
|
||||
./target/debug/marqdo view public/00-welcome.mq.md --no-open
|
||||
./target/debug/marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
cargo test -q --lib view::
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
|
||||
| 2026-10-15 | L-leader 拥挤/消失:同跨度多帧 chip **共用 annot id**;可见 chip 按锚点 x 重排;leader 挂 doc-block |
|
||||
| 2026-10-15 | L-leader 黑线碎段:JS `border*: "1.5px solid"` 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
|
||||
| 2026-10-15 | L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |
|
||||
@@ -0,0 +1,239 @@
|
||||
# View:静态页交互与公式/代码卡视觉
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view.md](view.md) · [user-site.md](user-site.md) · [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [ADR 0002 browser WASM](../adr/0002-browser-marqdo-wasm.md) |
|
||||
|
||||
**已确认(2026-10-15)**
|
||||
|
||||
| 决策 | 选择 |
|
||||
|------|------|
|
||||
| 引擎 | **B**(快照 + S1 帧切换 + 可选懒加载 WASM S2) |
|
||||
| 体验原则 | 静态页与 live view **尽量同构**;控件形态对齐;无服务端时用 WASM/JS 补齐 |
|
||||
| 视觉原则 | **一层主视觉**;一眼能懂;公式/代码不与 Bind chip / 源残留叠床架屋 |
|
||||
| 演示参数条 | **要**(历史实参 select + 可编辑;S1 切帧 / S2 重跑) |
|
||||
| code-card Run | 有 WASM 时可用;否则隐藏(不对齐「假按钮」) |
|
||||
| 公式 Bind chip | **卡内不显示**;Variables 可留终值 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机(对照 `public/00-欢迎.mq.md` / gh-pages)
|
||||
|
||||
静态导出(`marqdo view output` → `gh-pages`)与 live `marqdo view` 已共用**文档面 Structure** 渲染路径,但用户站实测仍有三类落差:
|
||||
|
||||
1. **交互控件缺失 / 偏弱**
|
||||
- 函数「问候」仅有参数 chip「谁」,没有可切换的调用帧下拉(即便源里 `> 问候` 写了两次)。
|
||||
- 参数行 `+ 谁` 在文档面呈声明高亮,读者无法在静态页改「谁」并看到新输出。
|
||||
- 外联 `code-card` 的 Run 在静态模式被禁用(`Run is available in live marqdo view`)。
|
||||
- 静态 stdin 仅在有 preset 时显示只读提示,**不能**再跑。
|
||||
|
||||
2. **无服务端时仍可交互的预期**
|
||||
用户站是纯静态托管:没有 `/api/run`。合理路径是 **页内 JS** 和/或 **嵌入 Marqdo WASM**,在浏览器里重算 Structure 标注、Execution 区,甚至模拟 `input` / 外联(沙箱约束另定)。
|
||||
|
||||
3. **公式 / 代码块视觉凌乱**
|
||||
同一赋值同时出现多层表象,信息重复、线框错位:
|
||||
|
||||
| 层 | 公式 `f = $$…$$` | 外联 `hi = ```python…``` |
|
||||
|----|------------------|---------------------------|
|
||||
| A 卡片 | `formula` badge + KaTeX | `code` badge + 高亮源码 + cmd/Run |
|
||||
| B 标注 chip | `f` → `x^2 - 2` | `hi` → 整段 fence 摘要 |
|
||||
| C 源残留 | 卡片外/旁再露 `$$` 或 ASCII | 卡片下再露 `python print…` 明文 |
|
||||
|
||||
再叠加 CSS L-leader 与卡内边框,首屏显得碎、重复、「坏掉的线」。
|
||||
|
||||
**本文件只定问题与方案;确认前不改代码。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状解剖
|
||||
|
||||
### 2.1 静态 vs live(同一 `page_file`)
|
||||
|
||||
| 能力 | Live | Static(`LinkMode::Static`) |
|
||||
|------|------|------------------------------|
|
||||
| 文档面 Structure + annot | ✅(跑后) | ✅(导出时跑后写入) |
|
||||
| call / loop picker JS | ✅(读 `#mq-view-trace`) | ✅(同源 JS;若轨迹未写入则无控件) |
|
||||
| `/api/run` · Stream | ✅ | ❌ |
|
||||
| stdin 表单 | ✅ 可再跑 | 只读 hint(或无) |
|
||||
| code-card Run | ✅ `POST` 外联 | ❌ 禁用按钮 |
|
||||
| WASM 重算 | ❌(未接) | ❌(未接) |
|
||||
|
||||
结论:**不是「静态另做一套皮肤」**,而是「导出瞬间的快照 + 部分 JS 帧切换」;**没有**浏览器内重执行闭环。
|
||||
|
||||
### 2.2 欢迎页结构(问题复现源)
|
||||
|
||||
```text
|
||||
> 问候 谁=marqdo
|
||||
> 问候 谁=marqdo user
|
||||
## 问候
|
||||
+ `谁`
|
||||
> 打印 内容=欢迎,`谁`!
|
||||
`f` = $$ x^2 - 2 $$
|
||||
`hi` = ```python … ```
|
||||
```
|
||||
|
||||
- 期望:`## 问候` 旁 **调用** 下拉(`1: 谁=marqdo` / `2: 谁=marqdo user`),切换时打印行的绑定/输出随帧变。
|
||||
- 现状风险:若导出时 CallFrame < 2、或 picker 未挂上、或读者期望的是「编辑谁」而非「选历史调用」,都会表现为「没有下拉框」。
|
||||
- 公式/代码:`SpecialAssign` → formula/code **card**,同时又对同名绑定建 **Bind annot**,文档面还可能保留块源视觉 → 三重展示。
|
||||
|
||||
### 2.3 已有红线(方案不得破坏)
|
||||
|
||||
- 代码即文档:`.mq.md` 源可读;不发明第二套嵌套 DSL(见 web-artifact / marqdo-dev)。
|
||||
- Browse ≠ Debug:静态站不做断点。
|
||||
- `public/**/*.html` 不入库;gh-pages 由 CI/`view output` 生成([user-site.md](user-site.md))。
|
||||
- 外链字体禁令仍在 [view.md](view.md);WASM/重型资源须 **可选加载**,默认站可降级为纯快照。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标(验收口径)
|
||||
|
||||
### G1 — 帧与参数交互(静态可读、可拨)
|
||||
|
||||
1. 同函数 ≥2 次调用时,静态页 **必有**「调用」下拉;默认末次;切换只改 chip/臂/相关输出,**源码常显**(同 [view-frame-selection.md](view-frame-selection.md))。
|
||||
2. 导出保证写入完整 `#mq-view-trace`(含 `calls` / `events` / 可选 `loops`)。
|
||||
3. (增强)演示向参数可提供 **受控输入**:默认值来自末次调用或 FM;改参后可触发页内重算(见 §5 引擎选项)。
|
||||
|
||||
### G2 — 无服务端可重算(可选引擎)
|
||||
|
||||
| 档位 | 能力 | 依赖 |
|
||||
|------|------|------|
|
||||
| **S0 快照**(现状加强) | 导出时跑完;帧 picker;只读 Execution | 无 WASM |
|
||||
| **S1 页内重放轨迹** | 不重跑程序,只切换已序列化帧/标注 | JSON only |
|
||||
| **S2 WASM 重跑** | `marqdo_wasm` + bridge:改 stdin/实参后重跑,刷新 Structure/Execution | WASM 包(可 CDN/`public/wasm/`) |
|
||||
| **S3 外联沙箱** | code-card Run:浏览器内 pyodide **或** 明确标「仅 live」 | 可选;默认可关 |
|
||||
|
||||
默认用户站:**S0 + S1 必达**;**S2 为推荐主路径**(与「用 wasm 模拟输出」对齐);S3 单独开关。
|
||||
|
||||
### G3 — 公式 / 代码视觉单层真相
|
||||
|
||||
对「特殊赋值」块约定 **一层主视觉 + 至多一层结果**:
|
||||
|
||||
| 块 | 主视觉 | 允许的结果层 | 禁止 |
|
||||
|----|--------|--------------|------|
|
||||
| 公式 | KaTeX(formula-card 精简) | 无 Bind chip,或仅在 Variables | 再渲一份 `$$` 明文;annot 与卡重复同一 TeX |
|
||||
| 外联代码 | 高亮源码(code-card) | 运行输出区 `code-out`;静态可藏 Run 或接 S2/S3 | annot 再贴整段 fence;卡下重复裸源 |
|
||||
| 普通赋值 | 标记面语句 | Bind chip + L-leader | — |
|
||||
|
||||
Leader:仅连接「主视觉锚点 → 唯一结果 chip」;卡内不用第二套 L 线。
|
||||
|
||||
---
|
||||
|
||||
## 4. 问题清单(成文)
|
||||
|
||||
| ID | 问题 | 严重度 | 根因假设 |
|
||||
|----|------|--------|----------|
|
||||
| P1 | 静态页看不到调用/循环下拉 | 高 | 轨迹未导出完整 / picker 条件(≥2)未满足 / 读者要的是编辑参而非选帧 |
|
||||
| P2 | 不能改参/stdin 再看输出 | 高 | Static 禁用 `/api/run`;无 WASM 闭环 |
|
||||
| P3 | code-card Run 静态无效 | 中 | `initForeignCards` 显式禁用 |
|
||||
| P4 | 公式卡 + chip + `$$` 三重 | 高 | card 与 Bind annot 叠加;块源未完全被 SpecialAssign 吞掉 |
|
||||
| P5 | 代码卡 + chip + 明文三重 | 高 | 同 P4 |
|
||||
| P6 | 卡内/旁碎线、错位 | 中 | leader 锚到错误节点;卡 CSS 与 annot-band 叠层 |
|
||||
| P7 | 静态 stdin 体验差 | 中 | 仅有只读 hint |
|
||||
|
||||
---
|
||||
|
||||
## 5. 解决方案(详案,待选)
|
||||
|
||||
### 5.1 引擎策略(三选一,推荐 **B**)
|
||||
|
||||
| 方案 | 做法 | 优点 | 代价 |
|
||||
|------|------|------|------|
|
||||
| **A. 纯快照 + S1** | 加强导出轨迹与 picker;不引入 WASM | 体积小、离线稳 | 不能改参真重算 |
|
||||
| **B. 快照默认 + 可选 WASM(S0/S1/S2)** | `view output` 仍嵌入跑后 HTML;页脚/侧栏「在浏览器中重跑」懒加载 WASM;改参后 patch Structure/Execution | 对齐用户预期;无 WASM 时仍可读 | 打包/加载体积;宿主能力子集 |
|
||||
| **C. 静态页全面 WASM 首屏** | 打开即 WASM 跑 | 交互最强 | 冷启动慢;gh-pages 带宽;与「文档先可读」冲突 |
|
||||
|
||||
**推荐 B**:文档先可读(S0),帧切换不依赖 WASM(S1),需要改参/演示时再拉 WASM(S2)。
|
||||
|
||||
### 5.2 交互控件(与文档面一致)
|
||||
|
||||
1. **调用 / 循环 picker**(已有组件)
|
||||
- 导出验收:欢迎页「问候」必须出现调用下拉。
|
||||
- 单测:对 `00-欢迎.mq.md` / `document-annot-demo` 断言 HTML 含 `call-picker` 且 options≥2。
|
||||
|
||||
2. **演示参数条(新,窄范围)**
|
||||
- 仅当函数被标记为「可演示」**或**静态页检测到 ≥1 形参且存在 CallFrame 时,在函数标题旁增加:
|
||||
`谁 [ text input | select(历史实参) ] [应用]`
|
||||
- **不**改 `.mq.md` 语法;数据来自 trace 的 `args_brief` / 末次绑定。
|
||||
- 「应用」:S1 仅切换已有帧;S2 调 WASM `run` 后替换 `#structure` / Execution。
|
||||
|
||||
3. **stdin**
|
||||
- 静态:若源含 `input`,渲染与 live 同形的 textarea +「重跑」(S2)或说明「需 WASM」。
|
||||
- 无 input 则不显示。
|
||||
|
||||
### 5.3 公式 / 代码去重(视觉)
|
||||
|
||||
**规则:SpecialAssign 行只走 card,不再为同名同值挂 Bind chip。**
|
||||
|
||||
```text
|
||||
公式赋值行
|
||||
└─ formula-card(badge + 名 + KaTeX)
|
||||
└─ ✗ 不再 render_annot_band(Bind f)
|
||||
└─ ✗ 不再在卡外输出 $$ 源
|
||||
|
||||
外联赋值行
|
||||
└─ code-card(badge + 名 + 高亮体 + 可选 Run)
|
||||
└─ ✗ 不再 Bind chip 贴 fence 全文
|
||||
└─ 运行结果只进 .code-out
|
||||
```
|
||||
|
||||
静态 Run 策略(与 §5.1 对齐):
|
||||
|
||||
- S0:隐藏 Run,或保留禁用并 tooltip「打开 live view / 启用 WASM」。
|
||||
- S2:Run → WASM 宿主 `foreign`(若 WASM 支持)或提示不支持。
|
||||
- S3:可选 Pyodide(默认关)。
|
||||
|
||||
CSS:formula-card / code-card 与 `.annot-band` 垂直节奏统一;禁止对 KaTeX 节点拉 L-leader。
|
||||
|
||||
### 5.4 导出管线
|
||||
|
||||
```text
|
||||
marqdo view output
|
||||
→ build_file_view(跑 + annot + trace_json) // 已有
|
||||
→ page_file(Static)
|
||||
+ 嵌入 #mq-view-trace
|
||||
+ (可选)data-wasm-url / 懒加载脚本
|
||||
+ 公式/代码去重后的 structure_html
|
||||
→ public/ + gh-pages
|
||||
```
|
||||
|
||||
`--no-exec`:文档面无标注;可提示「本页为结构-only」;S2 仍可尝试 WASM 首跑(可选,默认关以免惊喜执行)。
|
||||
|
||||
### 5.5 明确不做(本提案)
|
||||
|
||||
- 静态页断点调试(仍属 `marqdo debug`)。
|
||||
- 在 `public/*.mq.md` 发明新的「交互表」DSL(除非另开设计并获批)。
|
||||
- 默认全站加载 Pyodide。
|
||||
- 提交生成 HTML 进 `main`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 分阶段开发计划(确认后执行)
|
||||
|
||||
| 阶段 | 内容 | 交付 | 依赖确认 |
|
||||
|------|------|------|----------|
|
||||
| **D0** | 本文定稿;选定引擎 **A/B/C**;是否要「演示参数条」 | 状态 → Active | **本次决策** |
|
||||
| **D1** | P4/P5/P6:SpecialAssign 与 Bind 互斥;卡 CSS;去掉重复源 | 欢迎页公式/代码干净;单测 | D0 |
|
||||
| **D2** | P1:导出轨迹验收 + 欢迎页 call-picker 金样;修任何「≥2 调用无下拉」bug | HTML 断言 | D0 |
|
||||
| **D3** | P2/P7 S1 夯实:静态 stdin UI 形态;无 WASM 时文案清晰 | UX | D0 |
|
||||
| **D4** | (若选 B)S2:静态页懒加载 WASM;「应用参数 / 重跑」刷新 Structure+Execution | `public/wasm` 或 CDN 策略;体积预算 | D0=B |
|
||||
| **D5** | P3:code-card 与 S2/S3 策略落地;默认隐藏无效 Run | — | D1+D4 |
|
||||
| **D6** | `build-public` / pages CI 回归;更新 [user-site.md](user-site.md) · [view.md](view.md) 验收条 | gh-pages 抽检欢迎页 | D1–D5 |
|
||||
|
||||
建议默认路径:**D0 选 B → D1 → D2 → D3 → D4 → D5 → D6**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 决策记录
|
||||
|
||||
见文首「已确认」。开发按 §6:D1 → D2 → D3 → D4 → D5 → D6。
|
||||
|
||||
---
|
||||
|
||||
## 8. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:静态交互缺口、公式/代码凌乱、S0–S3 与阶段 D0–D6 |
|
||||
| 2026-10-15 | Active:引擎 B;对齐 live;干净视觉;演示参数条;Run 接 WASM 否则隐藏 |
|
||||
+6
-4
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.0.2 方向) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
|
||||
---
|
||||
|
||||
@@ -77,7 +77,7 @@ OUT_DIR/
|
||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
||||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||||
- 渲染逻辑与实时 `view` **共用**同一路径:`build_file_view` → 文档面 Structure(`document.rs` + annots)→ `page_file`(同一 CSS/JS,含 call/loop picker、`#mq-view-trace`)。禁止第二套皮肤。`--no-exec` 时仍出文档面,但无运行标注。
|
||||
|
||||
示例:
|
||||
|
||||
@@ -90,14 +90,16 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
|
||||
## 4. 信息架构
|
||||
|
||||
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
|
||||
侧栏文件索引 + 主区:**文档面 Structure** · 执行 · 源码。Structure(Browse)为叙述保真文档面:标记面(变量/语句/返回无源码定界符)、表/列表/分支结构保真,跑后结果经 **CSS L-leader** 引出——见 [view-document-annotations.md](view-document-annotations.md) · [view-execution-trace.md](view-execution-trace.md)。**不是** AST 卡片栈(那是 debug)。
|
||||
|
||||
结构旁**右侧栏**(现有 outline 槽)为:
|
||||
|
||||
| 区块 | 内容 |
|
||||
|------|------|
|
||||
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
|
||||
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
|
||||
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板;终态亦可刷新 Structure 内标注。
|
||||
|
||||
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# 缺陷记录:LLM 传输失败硬中断 Agent Runtime
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-llm-transport-soft.mq.md` |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 发现方 | qdagent(接通 `agent.run` live 路径时) |
|
||||
| 影响面 | `host/net` · `plugins/llm` · `ext/ai/llm` · `ext/ai/llm/openai` · `ext/ai/agent` |
|
||||
| 相关 | [agent-run-efi-resolve-bugs-2026-10.md](agent-run-efi-resolve-bugs-2026-10.md) · [ext-agent.md](../design/ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
上游 LLM **连接拒绝 / 超时 / 非 200** 时,Runtime 曾以 **硬错误** 终止整个 `marqdo run`;产品(qdagent ASK/BUILD)无法落到结构化 `status=error`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 复现
|
||||
|
||||
```bash
|
||||
OPENAI_API_KEY=offline OPENAI_BASE_URL=http://127.0.0.1:9 \
|
||||
marqdo run tests/ext/agent-llm-transport-soft.mq.md
|
||||
# 修复前:exit≠0,error: http POST …
|
||||
# 修复后:exit 0,ask/step/run 均带 finish|status=error + error 文本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因
|
||||
|
||||
| 层 | 行为 |
|
||||
|----|------|
|
||||
| `host_http_post` / SSE | 传输失败 `Err(...)` → VM abort |
|
||||
| `plugins/llm` `llm_chat_completions` | 同上 `Err` |
|
||||
| `ext/ai/llm/openai` | HTTP≠200 → `sys.exit 1` |
|
||||
| `agent.model_turn` / `step` / `plan` | 无软失败臂 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 修复清单
|
||||
|
||||
| # | 改动 | 文件 |
|
||||
|---|------|------|
|
||||
| 1 | 传输失败 → `{status:0, body}` / SSE error event | `src/host/net.rs` |
|
||||
| 2 | 插件返回 `{finish:error, error, …}` 而非 `Err` | `plugins/llm/src/lib.rs` |
|
||||
| 3 | openai 非 200 → 结构化 pack,禁止 `sys.exit` | `ext/ai/llm/openai.mq.md` |
|
||||
| 4 | `llm.ask` 透传 `error` / `finish` | `ext/ai/llm.mq.md` |
|
||||
| 5 | `model_turn` / `step` / `plan` 收成 `status=error` | `ext/ai/agent.mq.md` |
|
||||
| 6 | 金样 | `tests/ext/agent-llm-transport-soft.mq.md` |
|
||||
|
||||
**契约**:Agent Runtime 对 LLM 传输失败必须可捕获;`status=error` + `error` 字符串;进程退出码 0(程序正常返回错误图)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 对 qdagent
|
||||
|
||||
`ensure_llm` 有 key 但上游不可达时,`ask`/`build` 可走既有 `mode=error` 臂写 workbook,不再整 CLI 崩。
|
||||
@@ -0,0 +1,117 @@
|
||||
# 缺陷记录:`agent.run` EFI / resolve 在消费方崩溃(qdagent 复现)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-run-cold-efi.mq.md` |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 发现方 | qdagent(`~/work/qdagent`)接通 Marqdo ≥1.4.2 Agent EFI 全路径时 |
|
||||
| 影响面 | `ext/ai/agent` · `## run` · `plugins/agent` `agent_resolve` |
|
||||
| 相关 | [ext-agent.md](../design/ext-agent.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
`agent.run` 在 **空 OKF / 无 skill 命中** 或 **`efi=True`** 时,会以硬错误退出,而不是降级到 `plan` 探索。
|
||||
这是 **Agent Runtime 契约不完整**,不是 qdagent 业务写错。
|
||||
|
||||
---
|
||||
|
||||
## 1. 复现(qdagent)
|
||||
|
||||
环境:工作区 Marqdo `1.4.2` + `MARQDO_EXT=~/work/marqdo/ext`;qdagent 调用:
|
||||
|
||||
```text
|
||||
助手 = > agent.agent …
|
||||
`助手`.run task=… efi=True # 或 efi=False 后仍进 resolve
|
||||
```
|
||||
|
||||
本仓几乎没有 `.marqdo/agent-kb` 编译 skill。
|
||||
|
||||
### Bug A — `efi=True` → `unknown function preflight`
|
||||
|
||||
**位置**:[`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md) `## run`
|
||||
|
||||
```markdown
|
||||
1. `efi`
|
||||
**efi_pf = preflight task=`task`**
|
||||
```
|
||||
|
||||
同文件其它同对象方法一律写 `` `self`.route `` / `` `self`.resolve ``。
|
||||
裸标识 `preflight` 在导入消费方(如 `cli/求道-构建.mq.md`)里被解析成**全局函数**,找不到 → 硬错。
|
||||
|
||||
**期望**:`` **efi_pf = > `self`.preflight task=`task`** ``(或等价 method call)。
|
||||
|
||||
### Bug B — miss resolve → `missing map key llm_free`
|
||||
|
||||
**位置**:
|
||||
|
||||
1. Plugin:[`plugins/agent/src/memory.rs`](../../plugins/agent/src/memory.rs) `resolve_task`
|
||||
当 `kb_lookup` 返回 null:
|
||||
|
||||
```rust
|
||||
Ok(json!({
|
||||
"mode": "unknown",
|
||||
"skill": null,
|
||||
"resource": null,
|
||||
"confidence": 0.0,
|
||||
// 缺 llm_free
|
||||
}))
|
||||
```
|
||||
|
||||
2. Facade:`## run` 在 resolve 之后:
|
||||
|
||||
```markdown
|
||||
**llm_free = [llm_free](resolved)**
|
||||
```
|
||||
|
||||
脚注式取键在缺键时 **硬失败**,无法落到后面的 `plan` 探索臂。
|
||||
|
||||
**期望**:
|
||||
|
||||
- miss 结果始终带 `"llm_free": false`(与命中路径字段集对齐)
|
||||
- facade 侧对可选键用 `json.get`(缺省 `False`),防御其它调用方
|
||||
|
||||
---
|
||||
|
||||
## 2. 为何金样没拦住
|
||||
|
||||
| 金样 | 为何漏网 |
|
||||
|------|----------|
|
||||
| `tests/ext/agent-zero-llm.mq.md` | 先编译 skill / policy,再 `run`;resolve **命中** |
|
||||
| `tests/ext/eng-preflight.mq.md` | 只测 `agent_eng_preflight`,**不**走 `agent.run efi=` |
|
||||
| 多数 `agent-*-live` | 自带 kb 或 `efi=False` / 不经过 cold miss |
|
||||
|
||||
qdagent 是第一个「冷库 + 产品 EFI + `run`」消费方,因此打穿。
|
||||
|
||||
---
|
||||
|
||||
## 3. 修复清单(本轮)
|
||||
|
||||
| # | 改动 | 文件 |
|
||||
|---|------|------|
|
||||
| 1 | miss resolve 补 `llm_free: false` | `plugins/agent/src/memory.rs` |
|
||||
| 2 | `` `self`.preflight ``;`llm_free`/`mode` 用 `json.get` | `ext/ai/agent.mq.md` |
|
||||
| 3 | 回归金样:冷 kb + `run efi=True` 不崩溃,落到 explore/plan | `tests/ext/agent-run-cold-efi.mq.md` |
|
||||
| 4 | 重建 `marqdo_plugin_agent` 并跑金样 | `cargo build -p marqdo_plugin_agent --release` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 对 qdagent 的含义
|
||||
|
||||
修复后 qdagent 可恢复:
|
||||
|
||||
```text
|
||||
product preflight → latch → agent.run (efi=True|False) / plan
|
||||
```
|
||||
|
||||
而不必长期绕开 `agent.run`。
|
||||
在插件未装入新 so 前,qdagent 侧 EFI latch + `step`/`plan` 仍是合法降级。
|
||||
|
||||
---
|
||||
|
||||
## 5. 非目标
|
||||
|
||||
- 不改 EKC / `agent_eng_preflight` 语义
|
||||
- 不引入第二套 Agent loop
|
||||
- 不把向量检索升为权威真相
|
||||
@@ -0,0 +1,136 @@
|
||||
# 调研:代码即文档 × OKF × 沙盒 下的智能体 / 大模型优化(2026-10)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研 + 问题分析 · 供方案 [ext-ai-optimize.md](../design/ext-ai-optimize.md) 参考** |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [agent-framework-2026-09.md](agent-framework-2026-09.md) · [ai-agent-sandbox.md](ai-agent-sandbox.md) · [okf-and-marqdo.md](okf-and-marqdo.md) |
|
||||
| 本仓能力 | [ext-agent.md](../design/ext-agent.md) · [okf.md](../design/okf.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
|
||||
| 外部抽样 | Anthropic Agent Skills · SoK Agentic Skills (arXiv 2602.20867) · ForgeAgent · ACES / Skill Lift · Switchcraft 路由 · DSPy/GEPA ·「工作流编译进权重」· MalSkillBench |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
业界正把 Agent 优化从「更好的 chat loop」转向 **可验证、可复用、可隔离执行的技能层**;Marqdo 已具备 **可执行 Markdown(代码即文档)+ OKF/EKC 复用 + CoW 沙盒** 三件套,优化目标应是把这三件套焊成闭环:**试跑 → 证据 → 晋升 → 零/少 LLM 复用**,而不是追平 LangChain 功能清单。
|
||||
|
||||
---
|
||||
|
||||
## 1. 调研方法
|
||||
|
||||
| 动作 | 说明 |
|
||||
|------|------|
|
||||
| 扫业界技能层 | Anthropic Skills(渐进披露 `SKILL.md`);SoK Agentic Skills 生命周期;ForgeAgent「能力铸造」;ACES Skill Lift |
|
||||
| 扫成本/路由 | Switchcraft 工具调用路由;DSPy+GEPA 提示优化;工作流编译进小模型权重 |
|
||||
| 扫安全 | MalSkillBench 运行时验证恶意技能;沙盒粒度讨论(per-skill / per-session) |
|
||||
| 对照本仓 | A0–A4 / Wave B 已落地;沙盒 S0–S4 已落地;OKF + EKC + adaptive routing 现状 |
|
||||
|
||||
**不修改** `doc/next/*`(手写真相源);本文件只进 `doc/research/`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 业界态势(与 Marqdo 相关的收敛点)
|
||||
|
||||
### 2.1 技能层取代「纯工具调用叙事」
|
||||
|
||||
| 来源 | 要点 | 对 Marqdo |
|
||||
|------|------|-----------|
|
||||
| Anthropic Agent Skills | 目录 + `SKILL.md`;元数据预载、正文按需;脚本可执行 | 形态近 OKF 任务包,但 Marqdo 技能 **本身可跑** |
|
||||
| SoK Agentic Skills | 发现→练习→蒸馏→存储→组合→评测→更新;代码技能需沙盒 | 生命周期与 OKF promote / sandbox.run 对齐 |
|
||||
| ForgeAgent | 生成能力 → 沙盒证明 → 信任复用;失败进回归隔离 | **验证后晋升** 正是 solidify / `llm_free` 缺的硬闸 |
|
||||
| ACES | 有/无技能配对试验 → Skill Lift | 可作 Marqdo 评测 harness 指标 |
|
||||
|
||||
### 2.2 成本:路由 + 编译 + 小模型
|
||||
|
||||
| 来源 | 要点 | 对 Marqdo |
|
||||
|------|------|-----------|
|
||||
| Switchcraft | 工具调用场景路由到最便宜仍正确的模型;报道大幅降本 | 已有 `marqdo \| small-llm \| llm \| auto`;可加 **工具步/试跑步** 细分 |
|
||||
| DSPy / GEPA | 用反馈改写指令,小模型追上大模型 | 优化对象应是 **`.mq.md` 提示文档 / standing / 路由策略文件**,不是黑盒字符串 |
|
||||
| 工作流编译进权重 | 程序化流程进小模型权重,上下文常数级 | 长期对应「高频 OKF 技能 → 专用小模型」;短期优先 **llm_free 源码路径** |
|
||||
|
||||
### 2.3 安全:技能不可信 + 沙盒必验
|
||||
|
||||
恶意技能基准与 SoK 均强调:**技能说明与代码默认不可信**,须运行时隔离。Marqdo 新沙盒(默认拒 plugin/net/exec)正好是技能晋升前的证明场。
|
||||
|
||||
---
|
||||
|
||||
## 3. Marqdo 已有资产(优化起点)
|
||||
|
||||
| 资产 | 现状 | 优化杠杆 |
|
||||
|------|------|----------|
|
||||
| 代码即文档 | `.mq.md` = 程序 = 提示工作面;GFM 表 / 链接取元 | 减少 json 胶水;让模型「看见」结构 |
|
||||
| 写回 | `marqdo-out` 槽;step 默认写回 | 晋升证据、失败避坑 |
|
||||
| OKF / agent-kb | 命中 / near / promote / solidify / `llm_free` | 复用率、降本主轴 |
|
||||
| EKC / EFI | L0–L4 catalog;preflight REUSE/ADAPT/CREATE | 生成前先查工程知识 |
|
||||
| Adaptive routing | marqdo / small-llm / llm / auto + policy 文件 | 再细分 sandbox 试跑 vs 开放推理 |
|
||||
| Sandbox | CoW + capped `run`;`ext/ai/sandbox` | **试跑闸门**;未 commit 不污染仓库 |
|
||||
| MCP / corpus | 证据工具,`authority=workbook` | 保持不升权威 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 问题分析(差距,不是功能羡慕)
|
||||
|
||||
### P1 — 试跑与晋升未焊死
|
||||
|
||||
沙盒已能 CoW 试跑,但 **`agent.step` / `plan` 默认仍可直接改真实树**;OKF `llm_free` 晋升不强制「沙盒金样绿」。
|
||||
→ 风险:未验证技能进入复用池(业界 ForgeAgent / MalSkillBench 已证明此问题)。
|
||||
|
||||
### P2 — 技能形态双轨
|
||||
|
||||
Anthropic Skills = 文件夹 + 渐进披露;Marqdo = 可执行 `.mq.md` + OKF 类型。
|
||||
→ 机会:用 **OKF frontmatter + 可执行体** 统一,不必引入第二套 SKILL.md 权威;缺的是 **披露层级与验证元数据**(适用条件、fixture、sandbox profile)。
|
||||
|
||||
### P3 — 路由粒度偏粗
|
||||
|
||||
现有路由偏「整任务后端」;未区分:查 OKF / 写补丁 / 沙盒 `run` / 对外 HTTP。
|
||||
→ Switchcraft 启示:按 **步骤类型** 选模型,且「便宜模型推理 token 爆炸」要计入总成本。
|
||||
|
||||
### P4 — 评测未锁差异化
|
||||
|
||||
Wave B1 仍 Active:缺稳定 **Skill Lift / 沙盒证明率 / llm_free 命中率 / 文档可读性** 指标。
|
||||
→ 没有指标,优化会滑回「多调几次模型」。
|
||||
|
||||
### P5 — 代码即文档在 Agent 产出侧仍易腐化
|
||||
|
||||
模型仍可能吐 `json.set` 链、混用 EN/ZH API、跳过表结构。
|
||||
→ 沙盒可跑通语法,但 **风格门禁**(lint / preflight)未默认卡在 commit 前。
|
||||
|
||||
### P6 — 上下文与 EKC 未默认进每步
|
||||
|
||||
EFI / catalog 能力在,但 step 默认上下文仍可能偏源码切片,缺少「先 REUSE」硬门槛。
|
||||
|
||||
### P7 — LLM 表面与 Agent 成本账未统一
|
||||
|
||||
`llm.ask` / `stream` / usage 已有;Agent 侧缺 **按会话/技能的成本仪表盘** 写回文档(可 git 审)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 优化目标函数(建议)
|
||||
|
||||
在固定任务集上最大化:
|
||||
|
||||
\[
|
||||
\begin{align*}
|
||||
& \text{ReuseRate}(\text{OKF hit} + \text{llm\_free}) \\
|
||||
&+ \text{SandboxProofRate}(\text{试跑绿再 commit/promote}) \\
|
||||
&- \lambda_1 \cdot \text{TokenCost} - \lambda_2 \cdot \text{HostMutationsWithoutCommit}
|
||||
\end{align*}
|
||||
\]
|
||||
|
||||
约束:权威真相仍是 `.mq.md`;不引入隐藏 TOOL 主循环;不改 `doc/next/*`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 外部资料索引(抽样)
|
||||
|
||||
| 类型 | 链接 |
|
||||
|------|------|
|
||||
| Skills | [Anthropic engineering: Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) · [Claude Code skills](https://code.claude.com/docs/en/skills) · [agentskills / anthropics/skills](https://github.com/anthropics/skills) |
|
||||
| 论文 | [SoK: Agentic Skills](https://arxiv.org/html/2602.20867) · [Skill Issue (repo SKILL 优化)](https://arxiv.org/html/2609.12742v1) · [ACES Skill Lift](https://arxiv.org/html/2608.20614) · [MalSkillBench](https://arxiv.org/html/2606.07131v3) · [Compiling workflows into weights](https://arxiv.org/html/2605.22502) |
|
||||
| 开源/产品 | [ForgeAgent](https://github.com/Yashasm18/ForgeAgent) · [DSPy GEPA](https://dspy.ai/current/getting-started/gepa-optimization/) · [Switchcraft](https://www.microsoft.com/en-us/research/publication/switchcraft-ai-model-router-for-agentic-tool-calling/) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 结语
|
||||
|
||||
Marqdo 不缺「再一个 Agent SDK」;缺的是把 **文档真相、知识晋升、沙盒证明、模型路由** 收成可度量闭环。下一篇方案文档按问题编号给出可选方向与推荐波次,**不预设唯一银弹**。
|
||||
@@ -0,0 +1,392 @@
|
||||
# 调研:AI 扩展库沙盒设计(执行隔离 × 工作区暂存 × 写回)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 供 `ext/ai/*` 沙盒设计锁定参考**(**2026-10-16 修订**:纳入「AI 只生成 Marqdo」产品约束) |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 范围 | 浏览器 WASM / WASI、OS 进程沙盒、容器 / microVM、CoW 叠加工作区、符号链接暂存方案;对照 Marqdo AI 栈 |
|
||||
| 相关设计 | **[ext-ai-sandbox.md](../design/ext-ai-sandbox.md)** · **[roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md)** · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [adr/0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-modules.md](../design/stdlib-modules.md) |
|
||||
| 姊妹调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) · [ext-ai-optimize.md](../design/ext-ai-optimize.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**在「Agent 只生成 / 只执行 Marqdo(`.mq.md`)」这一产品约束下,Marqdo AI 沙盒应以 Wasm 为主沙盒——且必须是「内核 + `lib/*` + `ext/*`」可运行的完整运行时沙盒,而不是只跑光秃解释器。**
|
||||
|
||||
锁定方向:
|
||||
|
||||
1. **执行隔离 = Marqdo Wasm 运行时(与 ADR 0002 同构)** — deny-by-default 能力导入;**默认不授予** shell / 外联 / `dlopen` 原生插件。AI 产出面收窄到 Markdown 程序后,不必为通用 coding Agent 的「任意二进制」付沙盒税。
|
||||
2. **库完备性是验收线,不是加分项** — 沙盒内须能 `import lib/…` 与受支持的 `ext/…`;缺能力时 **显式失败**,禁止静默空成功(对齐 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5)。
|
||||
3. **工作区突变 = CoW / whiteout / 显式 commit**(应用层 VFS,必要时 overlay)— 「修改短暂不生效 → 确认写回」保留;**禁止以符号链接森林作为隔离边界**。
|
||||
4. **OS 沙盒 / microVM** — 降为 **逃逸舱 / 托管 Profile**:仅当显式启用 foreign、`subtask` 真子进程、或未来多租户托管时使用;**不是** Marqdo-only Agent 的默认主路径。
|
||||
|
||||
初稿曾按「通用 coding Agent 还需 shell」把 Wasm 与 bwrap 并列;在 Marqdo-only 约束下,主结论改为 **Wasm-first + 库完备 + CoW 写回**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 调研方法与边界
|
||||
|
||||
### 1.1 做了什么
|
||||
|
||||
| 动作 | 说明 |
|
||||
|------|------|
|
||||
| 厂商/产品文档 | Anthropic Claude Code sandbox / `@anthropic-ai/sandbox-runtime`;VS Code Copilot agent sandboxing;Docker AI Sandboxes;Turso AgentFS CoW overlay;OpenSandbox isolation sessions;WASI / jco preview2-shim;VS Code for the Web WASM webshell |
|
||||
| 工程对比文 | Northflank / Cosmonic 2026 agent sandbox 指南;gVisor vs Firecracker vs Docker 对比;ContainAI security comparison |
|
||||
| 学术与标准 | USENIX SEC'22 *Provably-Safe Multilingual Software Sandboxing using WebAssembly*;KTH 论文 *Intra-process Fault Isolation Using WebAssembly*(SFI 通信开销);ACM TOSEM *Research on WebAssembly Runtimes: A Survey*(2025);WASI Design Principles(capability / 无 ambient authority) |
|
||||
| 安全案例 | brig 项目挂载 symlink 逃逸(CVSS 8.2);Anthropic sandbox-runtime 对 bwrap bind 跟随 symlink 的修复;Docker Sandbox「direct mount vs clone」威胁说明 |
|
||||
| 对照本仓 | `ext/ai/{llm,agent}`、`lib/writeback`、`lib/subtask`、ADR 0002 浏览器 WASM、`RunOptions.allow_fs_write` 默认关 |
|
||||
|
||||
### 1.2 不做的
|
||||
|
||||
- 不把「发版用的容器镜像」与「Agent 工具沙盒」混为一谈。
|
||||
- 不宣称某一云厂商托管沙盒(E2B / Modal / Daytona)为 Marqdo 默认依赖。
|
||||
- 不修改 `doc/next/*`(手写真相源);本文件只进 `doc/research/`。
|
||||
|
||||
### 1.3 产品约束(修订要点):AI 只生成 Marqdo
|
||||
|
||||
这是相对通用 coding Agent(Claude Code / Codex)的 **结构性好消息**:
|
||||
|
||||
| 通用 Agent | Marqdo AI Agent(本调研采纳) |
|
||||
|------------|------------------------------|
|
||||
| 模型可产出 shell / Python / 任意仓库补丁 | 模型产出面收束为 **`.mq.md`(文档即程序)** |
|
||||
| 沙盒必须兼容「整台开发机能力」 | 沙盒只需跑 **同构 Marqdo 运行时** |
|
||||
| Wasm 往往只能罩住工具子集 | Wasm **可以**成为主执行边界 |
|
||||
| 标准库 = 语言运行时 + OS 工具链 | 标准库 / 扩展 = **`lib/*.mq.md` + `ext/**`(+ 受控宿主能力)** |
|
||||
|
||||
硬规则建议(后续 design 应写死):
|
||||
|
||||
1. Agent 工具表 **不提供** 通用 `bash` / 任意语言 `exec`(除非显式 opt-in 逃逸舱,且另套 OS 沙盒)。
|
||||
2. Agent 改仓库的权威动作是 **写 / 修订 `.mq.md`(含写回块)**,经 CoW 会话再 `commit`。
|
||||
3. 运行 Agent 生成的程序 = 在沙盒里 `run` 该 `.mq.md`,且其 `import` 的 **lib 与 ext 必须可用或显式报不可用**。
|
||||
|
||||
### 1.4 威胁模型(在 Marqdo-only 下收窄)
|
||||
|
||||
| 威胁 | 典型路径 | Marqdo-only 下的权重 |
|
||||
|------|----------|----------------------|
|
||||
| T1 提示注入 | 诱导读密钥、外泄、破坏 `.mq.md` | 仍高 — 靠能力拒绝 + CoW |
|
||||
| T2 工具侧信道 | `subtask`/`foreign` 子进程 | **默认关闭**;opt-in 才升权 |
|
||||
| T3 工作区即时破坏 | 直接写穿源树 | 靠 CoW;commit 闸门 |
|
||||
| T4 挂载逃逸 | symlink / bind 打穿 | 仍相关 — **勿用 symlink 作 W 层** |
|
||||
| T5 网络外泄 | `lib/net` / llm 出站 | 能力开关 + 域名策略 |
|
||||
| T6 Wasm 宿主桥过宽 | `host_fs_*` / 插件桥过宽 | **主威胁** — 桥 = 权限表 |
|
||||
| T7 库残缺假安全 | 沙盒能跑 `# main` 但 `import lib/fs` 怪崩或静默空 | **产品验收威胁** |
|
||||
|
||||
**成功标准:** 失败域止于会话 upper + 已授予能力;真实工作区默认只读直至 commit;**代表性 `lib/*` 与 `ext/*` 金样在沙盒内可跑或得到明确 `unavailable in sandbox` 诊断**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 先拆三个「沙盒放哪里」(Marqdo-only 版)
|
||||
|
||||
业界「Harness / Workspace / Execution」三分法仍成立,但 **Execution 的内容变了**:
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Pattern H — Harness(编排环) │
|
||||
│ ext/ai/agent · parent Plan-and-Move ·(可选)MCP client │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Pattern W — Workspace mutation(.mq.md 真相如何变) │
|
||||
│ CoW upper / whiteout / diff / commit → writeback │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Pattern X — 执行 Agent 产出的 Marqdo 程序 │
|
||||
│ Wasm Marqdo runtime + embedded/packaged lib + sandboxed │
|
||||
│ ext 能力面(非「任意 shell」) │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| Pattern | Marqdo 落点 | 沙盒要解决什么 |
|
||||
|---------|-------------|----------------|
|
||||
| H | `ext/ai/agent` | 编排是否持有过宽宿主权限;模型 I/O 与执行隔离 |
|
||||
| W | `lib/writeback` · 工作簿 | 编辑是否立刻污染仓库;人审/父裁决后落盘 |
|
||||
| X | **Wasm 内 `run` `.mq.md`** | 计算隔离;**lib/ext 能力是否完备且受控** |
|
||||
|
||||
用户提案在 Marqdo-only 下:**Wasm 作 X 主底层是正确方向**;仍须改掉 symlink,并补上 **库完备性** 这一环。
|
||||
|
||||
---
|
||||
|
||||
## 3. 方案谱系(横向对比)
|
||||
|
||||
> **读法(修订后):** 下表仍保留通用 Agent 对照。对 **Marqdo-only** 产品,请以 §0 / §5 / §6 的 Wasm-first 结论为准;本节 A/B 升权,F/G/H 降为逃逸舱或托管。
|
||||
|
||||
评分:● 强 / ◐ 中 / ○ 弱 / — 不适用。维度按「隔离强度」等客观属性;**产品适配**见 §5。
|
||||
|
||||
| 方案 | 隔离强度 | 启动成本 | 任意二进制 | 工作区暂存语义 | 与 Marqdo 契合 | 主要风险 |
|
||||
|------|----------|----------|------------|----------------|----------------|----------|
|
||||
| **A. 浏览器 WASM + 虚拟 FS** | ●(计算)◐(经桥的 FS) | ● | ○ | ◐(需自建 overlay) | ●(已有 ADR 0002) | 宿主桥过宽;无原生 toolchain |
|
||||
| **B. WASI / Component Model(非浏览器亦可)** | ● | ● | ○(仅 WASI 目标) | ●(preopens + 自建 VFS) | ● | 工具链不全则需降级 |
|
||||
| **C. 符号链接映射工作区 + 延迟写回** | ○ | ● | —(本身不是执行沙盒) | ◐(似是而非) | ○ | **symlink 逃逸是已知高危类** |
|
||||
| **D. 应用层 CoW VFS(upper/lower/whiteout)** | ◐(逻辑) | ● | — | ● | ●● | 必须配合 X 层 OS 隔离 |
|
||||
| **E. OS overlayfs / FUSE / AgentFS 式 CoW** | ●(配合命名空间) | ◐ | ●(在沙盒内) | ●● | ● | Linux/macOS 实现分叉;运维 |
|
||||
| **F. bubblewrap / Seatbelt(Anthropic SRT 类)** | ● | ● | ● | ○(默认可写 cwd) | ● | 需另加 CoW 才有「暂不生效」 |
|
||||
| **G. Docker / 硬化容器 / gVisor** | ◐→● | ◐ | ● | ◐(volume 策略) | ◐ | 共享内核或兼容性;重 |
|
||||
| **H. microVM(Firecracker / Kata)** | ●● | ◐ | ● | ◐ | ○(本地 CLI 过重) | KVM/运维;适合多租户托管 |
|
||||
| **I. 纯语言沙盒(RestrictedPython 等)** | ○ | ● | ○ | — | ○ | 对 Agent 工具链几乎无用 |
|
||||
|
||||
### 3.1 A — 浏览器 WASM + 虚拟 FS
|
||||
|
||||
**机制:** Wasm 线性内存 + 校验 + 仅经 import 碰宿主;FS 多为内存树 / OPFS / 经 JS bridge 的映射。Marqdo 已锁定「解释器进 WASM」(ADR 0002),默认 `allow_fs_write=false`。
|
||||
|
||||
**文献支撑:** Wasm 作为 SFI 窄腰(Bosamiya et al., USENIX SEC'22);进程内沙盒跨边界通信可比 IPC 快数量级(KTH Wasm-SFI 论文);WASI 明确 **capability / 无 ambient authority**。
|
||||
|
||||
**优点:** 与「代码即文档」浏览器运行同构;deny-by-default;适合跑 `.mq.md`、公式库、受控插件。
|
||||
**缺点:** 不能原生跑 `cargo test` / `npm` / 任意 shell;安全上限取决于 **bridge 授予了什么**;浏览器场景下「符号链接用户工作区」通常要落到 File System Access API 或服务端中继,**不是** POSIX symlink 语义。
|
||||
|
||||
**判定:** 在 **Marqdo-only** 约束下,作为 **Pattern X 主沙盒** 与浏览器内 Marqdo 的正解;完备性取决于 **lib 嵌入 + ext 能力桥**(§4.1),不取决于 shell。通用「任意二进制 Agent」场景下仍不够——但那不是本产品默认。
|
||||
|
||||
### 3.2 B — WASI / Component Model(CLI 宿主)
|
||||
|
||||
**机制:** preopens 显式挂载;`WASIShim({ sandbox: { preopens, enableNetwork: false } })`(Bytecode Alliance jco);Component imports = 权限表。
|
||||
|
||||
**优点:** 与 Wasm 同族,可在 Node/Wasmtime 跑,不绑浏览器;能力模型清晰。
|
||||
**缺点:** 同 A,任意 Linux 工具链需「宿主机再包一层」或改编译目标。
|
||||
|
||||
**判定:** Marqdo **官方扩展 / 插件中可 Wasm 化的部分**应走这条;与 ADR 0002 一条能力谱。
|
||||
|
||||
### 3.3 C — 符号链接映射工作区(用户设想的核心)
|
||||
|
||||
**设想:** 沙盒根下用 symlink 指向用户文件;写改暂存别处;确认后写回;删除 = 删 symlink。
|
||||
|
||||
**表面吸引力:** 零拷贝读、实现「像」有暂存。
|
||||
|
||||
**为何行业不把它当隔离原语:**
|
||||
|
||||
1. **Bind/mount 跟随 symlink 是经典逃逸。** Anthropic `sandbox-runtime` 明确修复:`allowWrite` 若为指向界外的 symlink,bwrap `--bind` 会把真实目标变成可写(PR #138 类修复)。
|
||||
2. **项目挂载未解析 symlink 可致高危。** Endor Labs 披露 brig「project mount symlink traversal」(CVSS 8.2):Agent 在可写项目内把子目录换成指向 `/etc` 的 symlink,下一轮宿主机按字符串挂载即打穿。
|
||||
3. **「删除 = 删 symlink」语义错误。** 删链接只去掉别名,**不等于**对 lower 层文件的 whiteout;若链接指向真实文件且曾被打开写穿,删除链接也救不回。
|
||||
4. **写穿风险。** 若某路径被解析成真实 inode 且可写,暂存承诺立刻破产。
|
||||
5. **跨平台。** Windows junction/reparse、浏览器虚拟 FS、容器 bind,行为不一致。
|
||||
|
||||
**判定:** **否决作为 Marqdo 默认工作区隔离方案。** 允许在 **只读、已解析、拒绝可写路径上的 symlink 组件** 的前提下作实现细节,但不得当作安全边界叙事。
|
||||
|
||||
### 3.4 D — 应用层 CoW VFS(推荐作 W 层默认)
|
||||
|
||||
**机制:**
|
||||
|
||||
```text
|
||||
lower = 真实工作区(只读打开 / 只读能力)
|
||||
upper = 会话 delta(内存 map / 目录树 / SQLite blob)
|
||||
whiteout = 逻辑删除集合
|
||||
view(path) = upper ?? (!whiteout && lower)
|
||||
commit() = 把 upper/whiteout 应用到 lower(可经人审)
|
||||
discard() = 丢弃会话
|
||||
diff() = 可审变更集
|
||||
```
|
||||
|
||||
与 Turso AgentFS、OpenSandbox `workspace.mode: overlay` 的 **语义同构**,但不强制 FUSE。
|
||||
|
||||
**与 Marqdo 对齐点:**
|
||||
|
||||
| VFS 操作 | Marqdo 真相 |
|
||||
|----------|-------------|
|
||||
| `diff()` | 父 Agent / 人审材料;可进 view |
|
||||
| `commit()` 文本结果 | `writeback.record` / 工作簿补丁 |
|
||||
| `discard()` | 失败回合不污染仓库 |
|
||||
| 只读 lower | 防止 T3 即时破坏 |
|
||||
|
||||
**优点:** 纯用户态、可测、可嵌入 `plugins/agent`;不依赖 root/FUSE;金样可锁。
|
||||
**缺点:** 对 **沙盒内原生工具**(它们走真实 POSIX)不可见,除非再挂 E 或把工具 I/O 也改走 VFS API。
|
||||
|
||||
**判定:** **Pattern W 的默认实现。**
|
||||
|
||||
### 3.5 E — OS CoW overlay(AgentFS / overlayfs / OpenSandbox)
|
||||
|
||||
**机制(AgentFS 公开设计):** lower=宿主只读;upper=SQLite delta;删除=whiteout;Linux 用 FUSE+user/mount ns;macOS 用 NFS+`sandbox-exec`。OpenSandbox 默认 `overlay`,会话结束可丢 upper。
|
||||
|
||||
**优点:** 对 **任意 shell 工具**透明;「改了但宿主机 `git status` 仍干净」体验业界已验证。
|
||||
**缺点:** 平台依赖;FUSE 权限;与应用层 D 双实现成本。
|
||||
|
||||
**判定:** **当 Pattern X 需要真实 shell 且要求暂存对工具透明时**启用(Linux 优先);作为 D 的「native 加速后端」,不是替代 Wasm。
|
||||
|
||||
### 3.6 F — OS 进程沙盒(bwrap / Seatbelt / VS Code Copilot)
|
||||
|
||||
**机制:** Anthropic:文件系统隔离 + **网络隔离(缺一不可)**;Linux bubblewrap + 代理;macOS Seatbelt。VS Code Copilot:同类依赖;路径分 readwrite / readonly / denied;明确「不是 VM,削弱授权即削弱边界」。
|
||||
|
||||
**优点:** 本地编码 Agent 的事实标准;覆盖子进程;启动轻。
|
||||
**缺点:** 默认可写 cwd → **没有**「暂不生效」;必须与 D/E 组合。Symlink 配置路径需解析与拒绝。
|
||||
|
||||
**判定:** **Pattern X(shell/外联/MCP)本地默认。**
|
||||
|
||||
### 3.7 G / H — 容器与 microVM
|
||||
|
||||
**共识:** 裸 Docker 共享内核,不适合作唯一边界应对不可信代码;gVisor 加强 syscall 拦截;Firecracker/Kata 适合多租户与高威胁(~125ms 级启动)。Docker AI Sandboxes 区分 **direct mount(即时写穿)** vs **clone(只读源 + 私有副本)**——后者才接近「确认后写回」。
|
||||
|
||||
**判定:** Marqdo **本地 CLI 默认不强制 microVM**;若未来 `ext` 提供托管执行 / 多租户,再把 H 定为服务端 Profile。G 可作为打包/CI Profile。
|
||||
|
||||
### 3.8 I — 语言级沙盒
|
||||
|
||||
对「Agent 会跑 shell」场景基本无效;仅作极窄解释器内嵌参考。
|
||||
|
||||
---
|
||||
|
||||
## 4. 专门评估:用户提案(修订)
|
||||
|
||||
> 浏览器 WASM 作沙盒底层 + 符号链接用户工作区 + 修改短暂不生效 + 确认后写回 + 删除变删 symlink。
|
||||
> **补充约束:** AI 只生成 Marqdo;沙盒须能用标准库与扩展库。
|
||||
|
||||
| 子命题 | 评价 | 说明 |
|
||||
|--------|------|------|
|
||||
| Wasm 作主执行隔离 | **在 Marqdo-only 下正确** | 与 ADR 0002 同构;不必为 shell 全集付税 |
|
||||
| 沙盒须含 lib + ext | **正确且关键** | 「能跑 `# main`」≠ 好沙盒;见 §4.1 |
|
||||
| 「短暂不生效」 | **正确** | CoW / staging(方案 D,必要时 E) |
|
||||
| 「确认后写回」 | **正确且极契合 Marqdo** | 与 writeback、父裁决、workbook 同一哲学 |
|
||||
| 「symlink 映射工作区」 | **仍错误** | 与是否只用 Marqdo 无关;换 CoW/whiteout |
|
||||
| 「删除 = 删 symlink」 | **仍错误** | 应为 whiteout;commit 时再对 lower 删除 |
|
||||
| 「性能最好且安全性最高」 | **Wasm 主路径下接近成立** | 前提是桥最小权限 + CoW;symlink 仍拉低安全 |
|
||||
|
||||
**修订后的正确表述:**
|
||||
|
||||
> **以 Wasm Marqdo 运行时为主沙盒,打包/嵌入 `lib/*`,经能力桥提供受支持的 `ext/*`;工作区用 lower 只读 + upper/whiteout;人审/父裁决后 commit。符号链接不作隔离原语。shell/外联/原生 dlopen 默认关闭,仅作显式逃逸舱。**
|
||||
|
||||
### 4.1 库完备性:什么叫「标准库和扩展库也能用」
|
||||
|
||||
沙盒若只能跑内置算术、却不能 `import lib/json` 或跑 `ext/ai/llm` 的离线金样,对 Agent 开发几乎无用——模型生成的 `.mq.md` **本来就会依赖 lib/ext**。
|
||||
|
||||
三类库进沙盒的路径不同:
|
||||
|
||||
| 类别 | 今日形态 | 沙盒策略 |
|
||||
|------|----------|----------|
|
||||
| **纯 `.mq.md` 库**(多数 `lib/*`、部分 `ext` 门面) | 源码 import | **嵌入或会话导入图**(已有 `embedded_lib` / import map)— 必须默认可用 |
|
||||
| **需宿主能力的 lib**(`fs` / `net` / `writeback` / `subtask` / `datetime.now`…) | `host_*` | **经能力表桥接**到会话 VFS / 受控 clock / 受控 fetch;默认最小集 |
|
||||
| **原生 ABI 扩展**(`plugins/web`、`plugins/agent`、quantum 等 `.so`) | `plugin.load` + dlopen | 浏览器/Wasm **无 dlopen**(ADR 0002 N2)。沙盒内应:**纯 mq 门面 + Wasm 插件**、或 **宿主代执行且权限计入会话**、或 **显式 `unavailable`** — 禁止假装成功 |
|
||||
|
||||
与 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5 对齐并扩展为 **Agent 沙盒能力矩阵(草案)**:
|
||||
|
||||
| 能力 | 沙盒默认 | 备注 |
|
||||
|------|----------|------|
|
||||
| builtins / 表 / 控制流 / 对象 | ✓ | 内核 |
|
||||
| `lib/math` `json` `table` `text` `collection`… | ✓ | embedded |
|
||||
| `lib/fs` | ✓(仅会话 VFS) | 写进 upper;禁越出 root |
|
||||
| `lib/writeback` | ✓(写会话内 `.mq.md`) | commit 后才进真实树 |
|
||||
| `lib/net` / llm HTTP | 默认关 / 域名白名单 | 与 T5 |
|
||||
| `lib/subtask` `fn=` | ✓(同 Wasm 会话) | |
|
||||
| `lib/subtask` `path=`/`code=`/`lang=` | **默认拒** | 逃逸舱 + OS 沙盒 |
|
||||
| `lib/plugin` + 原生 `.so` | **默认拒** | 改 Wasm 插件或宿主代执行 |
|
||||
| `ext/ai/llm` · `ext/ai/agent`(mq 门面) | ✓(能力允许时) | 网络/密钥另授 |
|
||||
| `ext/web` 服务端 listen/DB | **默认拒或只读 stub** | 完整 axum 不进沙盒;可测「装配/渲染」子集 |
|
||||
| `ext/quantum` / `ext/linalg` | 目标 ✓ | 优先纯逻辑 / Wasm 插件,避免强依赖宿主机 .so |
|
||||
|
||||
**验收金样建议(S 阶段):**
|
||||
一套「沙盒烟囱」:`import` 常用 lib → 写会话文件 → writeback → `diff` → `commit`;再各挑一个 **纯逻辑 ext** 与一个 **需网络的 ext**(后者验证拒绝/白名单)。缺能力必须诊断含 `unavailable in sandbox`(或同等措辞)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 综合评分(面向 Marqdo-only 产品)
|
||||
|
||||
加权(修订):执行隔离契合 Marqdo-only 30%、**lib/ext 完备** 25%、与 writeback 真相 20%、实现成本 15%、跨端(CLI↔浏览器)10%。
|
||||
(「任意 shell 工具完备」不再作为主权重。)
|
||||
|
||||
| 候选架构 | 分(相对) | 备注 |
|
||||
|----------|------------|------|
|
||||
| **A/B Wasm-first + D CoW + 库完备能力表** | **100(推荐)** | 主路径 |
|
||||
| 同上 + 逃逸舱 F(opt-in shell) | 95 | 兼容少数 foreign 需求 |
|
||||
| D + E + F(通用 coding 向) | 75 | 过重;非 Marqdo-only 默认 |
|
||||
| 仅 F(可写 cwd) | 55 | 缺 CoW;且鼓励非 mq 工具 |
|
||||
| 仅 A 但无 CoW、无 lib 嵌入 | 40 | 「半沙盒」 |
|
||||
| 仅 C(symlink) | 20 | 否决 |
|
||||
| 仅 H(人人 microVM) | 50 | 托管可选;本地默认过重 |
|
||||
|
||||
**绝对「最硬」单点**仍可以是 microVM(托管 Profile)。
|
||||
**Marqdo「最合适」:** **Wasm 完整运行时沙盒(内核+lib+受控 ext)+ CoW 工作区 + commit 闸门**。
|
||||
|
||||
---
|
||||
|
||||
## 6. Marqdo 应采用的沙盒设计(推荐锁定草案 · 修订)
|
||||
|
||||
### 6.1 产品形态
|
||||
|
||||
| Profile | 场景 | 执行(X) | 工作区(W) |
|
||||
|---------|------|-----------|------------|
|
||||
| **`mq-sandbox`(默认)** | Agent 生成并试跑 `.mq.md` | **Wasm Marqdo** + embedded `lib/*` + 能力桥 `ext` | 应用层 CoW;commit→真实树 / writeback |
|
||||
| **`browser`** | 页内同构运行 | 同左(ADR 0002) | 内存/OPFS;无 POSIX symlink |
|
||||
| **`escape`(显式)** | foreign / 真子进程 | OS 沙盒包一层 | 仍建议 CoW 可见 |
|
||||
| **`hosted`(可选)** | 多租户 | Wasm 或 microVM | 会话隔离;凭证外置 |
|
||||
|
||||
### 6.2 推荐架构图
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────┐
|
||||
│ ext/ai/agent (Harness) │
|
||||
│ 只产出 / 编排 .mq.md · 人审闸门 │
|
||||
└──────────────────┬───────────────────┘
|
||||
│
|
||||
┌─────────────────────┼─────────────────────┐
|
||||
▼ ▼
|
||||
┌────────────────────┐ ┌────────────────────┐
|
||||
│ Workspace CoW (W) │ │ Marqdo Wasm (X) │
|
||||
│ lower = RO 工作区 │◄── fs/writeback ───│ 同构解释器/VM │
|
||||
│ upper / whiteout │ 能力导入 │ + embedded lib/* │
|
||||
│ diff·commit·discard│ │ + ext 能力面 │
|
||||
└─────────┬──────────┘ │ 默认: 无 shell/so │
|
||||
│ └────────────────────┘
|
||||
▼
|
||||
真实工作区 / <!-- marqdo-out -->
|
||||
(代码即文档真相源)
|
||||
|
||||
(可选)escape: subtask path|code|lang → OS sandbox
|
||||
```
|
||||
|
||||
### 6.3 API 面建议(设计级,非立即实现)
|
||||
|
||||
落点倾向:宿主能力进 `plugins/agent` / Wasm HostContext;作者面经 `ext/ai` 或 `lib`(**禁止** `ext/**` 直调 `host_*`)。
|
||||
|
||||
| 概念 | 语义 |
|
||||
|------|------|
|
||||
| `sandbox.open(root, mode=cow)` | 打开会话;lower 只读 |
|
||||
| `sandbox.read/write/list/remove` | 经 view;remove → whiteout |
|
||||
| `sandbox.diff` / `stat` | 供父 Agent / view |
|
||||
| `sandbox.commit` / `discard` | 闸门;可要求 HITL |
|
||||
| `sandbox.run(source\|path, caps=…)` | **Wasm 跑 Marqdo**;caps 声明 fs/net/llm/… |
|
||||
| `sandbox.caps` / `inspect` | 列出已授能力与 lib/ext 可用性(对齐 `web.inspect` 哲学) |
|
||||
| `sandbox.exec(...)` | **仅 escape Profile**;默认不存在于作者工具表 |
|
||||
|
||||
与现有衔接:
|
||||
|
||||
- `lib/*`:优先 embedded;FS/时间/网络走会话 caps。
|
||||
- `ext/*`:mq 门面可加载;原生插件默认不可用并诊断;长期可 Wasm 化的(linalg/quantum 逻辑)优先进 Wasm。
|
||||
- `lib/writeback`:写入会话内文件;`commit` 时进入真实树。
|
||||
- `lib/subtask`:默认仅 `fn=`;`path`/`code`/`lang` 要 escape。
|
||||
|
||||
### 6.4 硬禁(写入后续 design 时应保留)
|
||||
|
||||
1. **不以 symlink 森林作为隔离或暂存原语。**
|
||||
2. **不以「能跑空 `# main`」宣称沙盒完成** — 必须过 lib/ext 完备金样或显式 unavailable。
|
||||
3. **默认工具表不提供通用 shell / 任意语言 exec。**
|
||||
4. **不默认可写 bind 真实工作区。**
|
||||
5. **宿主桥 = 权限表**:未授能力不得 ambient 成功。
|
||||
6. **不静默降级**:缺 Wasm/能力时不得假装已隔离。
|
||||
7. **`ext/**` 不调 `host_*`**(既有宪法)。
|
||||
|
||||
### 6.5 分阶段落地(建议,非 `doc/next`)
|
||||
|
||||
| 阶段 | 交付 | 验收线索 |
|
||||
|------|------|----------|
|
||||
| S0 | 威胁模型 + 本调研(含 Marqdo-only) | 本文 |
|
||||
| S1 | Wasm `run` + embedded 核心 `lib/*` + 会话 VFS 读 | 常用 lib 金样在沙盒绿 |
|
||||
| S2 | CoW upper/whiteout + diff/commit/discard | 未 commit 时宿主机 `git status` 干净 |
|
||||
| S3 | writeback / 工作簿在会话内可写;commit 对齐 | agent step 金样 |
|
||||
| S4 | caps:net/llm 白名单;`subtask` 非 fn 默认拒 | 诊断字符串稳定 |
|
||||
| S5 | 代表性 ext(纯逻辑 + 需网)沙盒金样 | 完备性验收 |
|
||||
| S6 | (可选)escape OS 沙盒;hosted microVM | 文档标明非默认 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 外部资料索引(抽样)
|
||||
|
||||
| 类型 | 引用 |
|
||||
|------|------|
|
||||
| 产品 | [Anthropic: Claude Code sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) · [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) · [VS Code agent sandboxing](https://code.visualstudio.com/docs/agents/run/agent-sandboxing) · [Docker AI Sandboxes security](https://docs.docker.com/ai/sandboxes/security/) · [Turso AgentFS overlay](https://turso.tech/blog/agentfs-overlay) · [OpenSandbox isolation sessions](https://open-sandbox.ai/guides/isolation-sessions) |
|
||||
| 标准 | [WASI Design Principles](https://github.com/WebAssembly/WASI/blob/main/docs/DesignPrinciples.md) · [jco preview2-shim sandbox](https://github.com/bytecodealliance/jco/blob/main/packages/preview2-shim/README.md) |
|
||||
| 论文 | Bosamiya et al., *Provably-Safe Multilingual Software Sandboxing using WebAssembly*, USENIX Security 2022 · *Intra-process Fault Isolation Using WebAssembly* (KTH) · *Research on WebAssembly Runtimes: A Survey*, ACM TOSEM 2025 |
|
||||
| 综述 | [Cosmonic: Choosing an AI agent sandbox (2026)](https://cosmonic.com/ai-sandbox/choosing-an-agent-sandbox/) · [Northflank: MicroVMs, gVisor & isolation](https://northflank.com/blog/how-to-sandbox-ai-agents) |
|
||||
| 安全案例 | [brig symlink traversal / Endor Labs](https://www.endorlabs.com/learn/project-mount-symlink-traversal-in-brig-how-a-sandbox-reaches-host-directories-it-was-never-given) · Anthropic sandbox-runtime symlink bind 修复 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 结语
|
||||
|
||||
- **产品好消息:** Agent 只生成 Marqdo → **Wasm 主沙盒设计成立**,不必默认扛通用 shell Agent 的复杂度。
|
||||
- **好沙盒的定义:** 不只跑内核,还要 **`lib/*` 可用、`ext/*` 在能力表内可用或显式不可用**;再加 **CoW + commit** 保护仓库真相。
|
||||
- **仍要改掉的:** 符号链接当暂存/隔离;默认开放 foreign/dlopen;「空 main 能跑」就算完工。
|
||||
- **降级为非默认的:** bwrap/microVM — 留给 escape / hosted,而不是 Marqdo-only 主路径。
|
||||
|
||||
不急着实现。下一步若继续收敛,再开 `doc/design/ext-ai-sandbox.md` 把 **能力矩阵 + 库完备金样清单** 锁死即可;**仍不要改 `doc/next/*`**。
|
||||
@@ -18,6 +18,7 @@
|
||||
|----|------|------|
|
||||
| **Intelligence primitive** | `ask` / `stream` / `collect`;结果对象 | `ext/ai/llm` |
|
||||
| **Agent runtime** | `run` / `step` / `plan` / `route` | `ext/ai/agent` |
|
||||
| **Sandbox (trial)** | CoW workspace + capped `run` | `ext/ai/sandbox` · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
| **Memory / compile** | episode → skill → policy | `plugins/agent`(ABI;**不进** `src/host`) |
|
||||
| **Transport** | HTTP / SSE / provider | `ext/ai/llm/openai` · `ollama`;用户不可见 |
|
||||
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.md)** |
|
||||
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
|
||||
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
|
||||
| 后续 | 优化波次 O1–O5 见 [ext-ai-optimize.md](ext-ai-optimize.md)(沙盒证明 · Skill Lift · 路由/成本 · lint · 隔离) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Roadmap: Agent/LLM 优化波次 O1–O5
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** |
|
||||
| Date | 2026-10-16 |
|
||||
| Design | [ext-ai-optimize.md](../design/ext-ai-optimize.md) |
|
||||
| Research | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
|
||||
| Prior | [ext-agent-optimize.md](ext-agent-optimize.md) (A0–A4 / Wave B) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
|
||||
## Principles
|
||||
|
||||
1. Executable `.mq.md` remains authority; OKF reuses; sandbox proves; LLM explores.
|
||||
2. No hidden TOOL: loop; no vector-store memory authority; no default shell Agent.
|
||||
3. Do not edit `doc/next/*`.
|
||||
|
||||
## Waves
|
||||
|
||||
| Wave | Scope | Gold / deliverable | Status |
|
||||
|------|-------|--------------------|--------|
|
||||
| **O1** | A1 opt-in `sandbox=` · A3 profile table · D1 skill · D4 example | `agent-sandbox-optin` · `examples/agent-sandbox-okf` | **done** |
|
||||
| **O2** | A2 promote proof · B1 OKF meta · B3/E1 harness Skill Lift | `agent-sandbox-promote` · harness subset | **done** |
|
||||
| **O3** | C1 step route · C2 cost · B6 EFI default | `agent-step-route` · run usage/efi | **done** |
|
||||
| **O4** | A4/D2 lint · A5 diff review report | `scripts/mq-style-lint.sh` · `sandbox.report` | **done** |
|
||||
| **O5** | B4 quarantine · C3 offline policy rewrite | `agent-sandbox-quarantine` · `optimize-standing-policy.sh` | **done** |
|
||||
|
||||
## Non-goals
|
||||
|
||||
F1–F5 · wasmtime CLI embed · default `sandbox=True` without ADR · edit `doc/next/*`
|
||||
@@ -0,0 +1,28 @@
|
||||
# Roadmap: `ext/ai/sandbox` (AI CoW trial runtime)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** |
|
||||
| Date | 2026-10-16 |
|
||||
| Design | [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
| Research | [ai-agent-sandbox.md](../research/ai-agent-sandbox.md) |
|
||||
|
||||
## Milestones
|
||||
|
||||
| ID | Deliverable | Done when |
|
||||
|----|-------------|-----------|
|
||||
| S0 | Design + this roadmap + research cross-links | **done** |
|
||||
| S1 | CoW open/write/read/remove/diff/commit/discard | **done** (`sandbox-cow`) |
|
||||
| S2 | `run` + default caps + core lib inside run | **done** (`sandbox-run-lib`) |
|
||||
| S3 | `inspect` + deny plugin.load | **done** (`sandbox-deny`) |
|
||||
| S4 | Polish: ai-stack + CHANGELOG | **done** |
|
||||
|
||||
## Gold samples (target)
|
||||
|
||||
- `tests/ext/sandbox-cow.mq.md`
|
||||
- `tests/ext/sandbox-run-lib.mq.md`
|
||||
- `tests/ext/sandbox-deny.mq.md`
|
||||
|
||||
## Out of scope this wave
|
||||
|
||||
wasmtime CLI embed · Wasm ABI plugins · bwrap/microVM · full web in sandbox · auto-wire agent.step · edit `doc/next/*`
|
||||
@@ -0,0 +1,13 @@
|
||||
# agent-sandbox-okf(O1)
|
||||
|
||||
演示 **opt-in 沙盒试跑 + 表风格**(少 json 胶水):`agent.trial` 写入先落 upper,`commit=False` 时宿主不变,成功后再 `commit=True`。
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent
|
||||
export MARQDO_EXT="$PWD/ext"
|
||||
./target/release/marqdo run examples/agent-sandbox-okf/index.mq.md
|
||||
```
|
||||
|
||||
期望:`dry-ok` · `host-clean` · `wet-ok` · `proof-visible` · `profile-default`。
|
||||
|
||||
见 [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md) · 金样 [agent-sandbox-optin.mq.md](../../tests/ext/agent-sandbox-optin.mq.md)。
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: agent-sandbox-okf — trial then commit
|
||||
description: >
|
||||
O1 example: opt-in sandbox trial with GFM-table returns and link-index reads.
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Short demo: write via `agent.trial`, prove the host is clean until commit.
|
||||
|
||||
**had = fs.exists path="_example_sbx"**
|
||||
1. `had`
|
||||
> fs.remove path="_example_sbx"
|
||||
2. *
|
||||
**_ = 0**
|
||||
|
||||
> fs.make_dir path="_example_sbx"
|
||||
|
||||
**dry = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=False**
|
||||
**dry_ok = [ok](dry)**
|
||||
**dry_committed = [committed](dry)**
|
||||
1. `dry_ok`
|
||||
1. not `dry_committed`
|
||||
> print text=dry-ok
|
||||
2. *
|
||||
> print text=dry-bad-commit
|
||||
2. *
|
||||
> print text=dry-fail
|
||||
|
||||
**leaked = fs.exists path="_example_sbx/note.txt"**
|
||||
1. `leaked`
|
||||
> print text=host-leaked
|
||||
2. *
|
||||
> print text=host-clean
|
||||
|
||||
**wet = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=True**
|
||||
**wet_ok = [ok](wet)**
|
||||
**wet_committed = [committed](wet)**
|
||||
1. `wet_ok`
|
||||
1. `wet_committed`
|
||||
> print text=wet-ok
|
||||
2. *
|
||||
> print text=wet-no-commit
|
||||
2. *
|
||||
> print text=wet-fail
|
||||
|
||||
**body = fs.read_text path="_example_sbx/note.txt"**
|
||||
1. `body` == "sandbox-okf"
|
||||
> print text=proof-visible
|
||||
2. *
|
||||
> print text=proof-missing
|
||||
|
||||
**pname = [name]([profile](wet))**
|
||||
1. `pname` == "default"
|
||||
> print text=profile-default
|
||||
2. *
|
||||
> print text=profile-other
|
||||
+1
-1
@@ -1 +1 @@
|
||||
1.3.1
|
||||
1.4.4
|
||||
+639
-340
File diff suppressed because it is too large.
Load diff
+29
-5
@@ -5,6 +5,7 @@ description: >-
|
||||
OpenAI-compatible and Ollama HTTP stay behind the semantic surface.
|
||||
import sys:lib/sys.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
import text:lib/text.mq.md
|
||||
import openai:ext/ai/llm/openai.mq.md
|
||||
@@ -283,9 +284,21 @@ Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `
|
||||
**text = > json.get value=`pack` key="text"**
|
||||
**usage = > json.get value=`pack` key="usage"**
|
||||
**finish = > json.get value=`pack` key="finish"**
|
||||
**err = > json.get value=`pack` key="error"**
|
||||
**tc = > json.get value=`pack` key="tool_calls"**
|
||||
1. not `tc`
|
||||
**tc = > json.parse text=[]**
|
||||
**tc = > table.empty_list**
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `text`
|
||||
**text = ""**
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `finish`
|
||||
1. `err`
|
||||
**finish = "error"**
|
||||
2. *
|
||||
**finish = "stop"**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
@@ -296,13 +309,24 @@ inside the table is unsafe.
|
||||
**mdl = [model](self)**
|
||||
**b = [backend](self)**
|
||||
**nm = [name](self)**
|
||||
**tt = [total_tokens](usage)**
|
||||
1. `usage`
|
||||
**tt = [total_tokens](usage)**
|
||||
2. *
|
||||
**tt = 0**
|
||||
1. not `tt`
|
||||
**tt = 0**
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. `err`
|
||||
**calls = 0**
|
||||
2. *
|
||||
**calls = 1**
|
||||
|
||||
`result` =
|
||||
|
||||
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls |
|
||||
|------|-------|--------|---------|-------|------|-----------|--------|------------|
|
||||
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | 1 | `tt` | `tc` |
|
||||
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls | error |
|
||||
|------|-------|--------|---------|-------|------|-----------|--------|------------|-------|
|
||||
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | `calls` | `tt` | `tc` | `err` |
|
||||
|
||||
*result*
|
||||
|
||||
|
||||
+57
-21
@@ -4,6 +4,7 @@ description: >-
|
||||
OpenAI-compatible chat completions transport (HTTP + SSE).
|
||||
Prefers optional plugins/llm ABI when present; falls back to lib/net.
|
||||
Used by ext/ai/llm; authors should prefer llm.ask / llm.stream.
|
||||
Result packs are GFM tables / table.put (code-as-documentation).
|
||||
import net:lib/net.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import table:lib/table.mq.md
|
||||
@@ -53,21 +54,18 @@ Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
|
||||
|
||||
**choices = > json.get value=`data` key="choices"**
|
||||
1. not `choices`
|
||||
**empty = > json.parse text=[]**
|
||||
*empty*
|
||||
*> table.empty_list*
|
||||
2. *
|
||||
**c0 = [1](choices)**
|
||||
**msg = > json.get value=`c0` key="message"**
|
||||
1. not `msg`
|
||||
**empty = > json.parse text=[]**
|
||||
*empty*
|
||||
*> table.empty_list*
|
||||
2. *
|
||||
**tc = > json.get value=`msg` key="tool_calls"**
|
||||
1. `tc`
|
||||
*tc*
|
||||
2. *
|
||||
**empty = > json.parse text=[]**
|
||||
*empty*
|
||||
*> table.empty_list*
|
||||
|
||||
## chat_completions
|
||||
+ `base_url`
|
||||
@@ -79,7 +77,7 @@ Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
|
||||
+ `suffix`=/chat/completions
|
||||
+ `bearer`="Bearer "
|
||||
|
||||
POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_completions`) when the native plugin is resolvable; otherwise `lib/net` HTTP/SSE. Non-stream → `{text,usage,finish,tool_calls}`; stream → `{events,finish}`.
|
||||
POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_completions`) when the native plugin is resolvable; otherwise `lib/net` HTTP/SSE. Non-stream → `{text,usage,finish,tool_calls}`; stream → `{events,finish}`. Soft transport / HTTP failures return `finish=error` packs (never abort the VM).
|
||||
|
||||
**p = > plugin.native_path name="llm"**
|
||||
1. `p`
|
||||
@@ -107,13 +105,32 @@ POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_c
|
||||
**body = > json.stringify value=`req`**
|
||||
**resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`**
|
||||
1. [status](resp) == 200
|
||||
**pack = > json.parse text={"finish":"stop"}**
|
||||
**pack = > json.set map=`pack` key="events" value=[events](resp)**
|
||||
**evs = [events](resp)**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | events |
|
||||
|--------|--------|
|
||||
| stop | `evs` |
|
||||
|
||||
*pack*
|
||||
2. *
|
||||
> print text=ext/ai/llm/openai: HTTP error (stream)
|
||||
> print text=[status](resp)
|
||||
> sys.exit code=1
|
||||
Soft transport / HTTP failure — structured pack, never abort the VM.
|
||||
**st = [status](resp)**
|
||||
**msg = "HTTP " + `st`**
|
||||
**evs = [events](resp)**
|
||||
1. `evs`
|
||||
**e0 = [1](evs)**
|
||||
**m2 = > json.get value=`e0` key="message"**
|
||||
1. `m2`
|
||||
**msg = `m2`**
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | events |
|
||||
|--------|------|-------|--------|
|
||||
| error | "" | `msg` | `evs` |
|
||||
|
||||
*pack*
|
||||
2. *
|
||||
**body = > json.stringify value=`req`**
|
||||
**resp = > net.http_post url=`url` body=`body` headers=`headers`**
|
||||
@@ -132,14 +149,33 @@ POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_c
|
||||
2. *
|
||||
**_ = 1**
|
||||
**tc = > tool_calls_from data=`data`**
|
||||
**pack = > json.parse text={"finish":"stop"}**
|
||||
**pack = > json.set map=`pack` key="text" value=`text`**
|
||||
**pack = > json.set map=`pack` key="usage" value=`usage`**
|
||||
**pack = > json.set map=`pack` key="finish" value=`fr`**
|
||||
**pack = > json.set map=`pack` key="tool_calls" value=`tc`**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | usage | tool_calls |
|
||||
|--------|------|-------|------------|
|
||||
| `fr` | `text` | `usage` | `tc` |
|
||||
|
||||
*pack*
|
||||
2. *
|
||||
> print text=ext/ai/llm/openai: HTTP error
|
||||
> print text=[status](resp)
|
||||
> print text=[body](resp)
|
||||
> sys.exit code=1
|
||||
Soft transport / HTTP failure — structured pack, never abort the VM.
|
||||
**st = [status](resp)**
|
||||
**raw = [body](resp)**
|
||||
**msg = "HTTP " + `st`**
|
||||
1. `raw`
|
||||
**msg = `msg` + ": " + `raw`**
|
||||
`usage0` =
|
||||
|
||||
| prompt_tokens | completion_tokens | total_tokens |
|
||||
|---------------|-------------------|--------------|
|
||||
| 0 | 0 | 0 |
|
||||
|
||||
**empty_tc = > table.empty_list**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: step-route policy (O3)
|
||||
description: >
|
||||
Table-driven map from step class → Adaptive Routing backend.
|
||||
Readable authority for agent.step_route; do not invent a second dialect.
|
||||
---
|
||||
|
||||
# Step class → backend
|
||||
|
||||
Authors and `agent.step_route` read this table. Backends match Adaptive Routing:
|
||||
`marqdo` | `small-llm` | `llm` | `auto`.
|
||||
|
||||
**routes = **
|
||||
|
||||
| kind | backend | note |
|
||||
|------|---------|------|
|
||||
| lookup | marqdo | OKF / kb skill hit — no parent LLM |
|
||||
| patch | small-llm | Local patch / soft match |
|
||||
| sandbox_run | marqdo | CoW trial of `.mq.md` |
|
||||
| net | llm | Needs network / toolful turn |
|
||||
| default | auto | Cascade policy → kb → small-llm |
|
||||
|
||||
# main
|
||||
|
||||
*routes*
|
||||
@@ -0,0 +1,191 @@
|
||||
---
|
||||
title: ext/ai/sandbox
|
||||
description: >-
|
||||
CoW trial workspace for AI-generated Marqdo: open / run / diff / commit.
|
||||
Native work lives in plugins/agent (`sandbox_*` → host_query).
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
---
|
||||
|
||||
Load the agent plugin once per call (same pattern as other `ext/ai` helpers).
|
||||
|
||||
Capability profiles are GFM tables under `## profile` (readable authority; `open` / `inspect` echo them). Do not invent a second table dialect.
|
||||
|
||||
## ensure_plugin
|
||||
|
||||
**p = plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/sandbox: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)
|
||||
> sys.exit code=1
|
||||
|
||||
## profile
|
||||
+ `name`=default
|
||||
|
||||
Named caps row as a map table (`name`, `fs_write`, `exec`, `net`, `plugin`). Unknown names → `default`.
|
||||
|
||||
Catalog (documentation + authority):
|
||||
|
||||
| name | fs_write | exec | net | plugin |
|
||||
|------|----------|------|-----|--------|
|
||||
| default | true | false | false | false |
|
||||
| readonly | false | false | false | false |
|
||||
|
||||
1. `name` == "readonly"
|
||||
**row = **
|
||||
|
||||
| name | fs_write | exec | net | plugin |
|
||||
|------|----------|------|-----|--------|
|
||||
| readonly | false | false | false | false |
|
||||
|
||||
2. *
|
||||
**row = **
|
||||
|
||||
| name | fs_write | exec | net | plugin |
|
||||
|------|----------|------|-----|--------|
|
||||
| default | true | false | false | false |
|
||||
|
||||
*row*
|
||||
|
||||
## open_native
|
||||
+ `root`=None
|
||||
|
||||
Native CoW open (plugin ABI italic return). Prefer `## open` for the profile-aware facade.
|
||||
|
||||
> ensure_plugin
|
||||
|
||||
1. `root`
|
||||
*> sandbox_open root=`root`*
|
||||
2. *
|
||||
*> sandbox_open*
|
||||
|
||||
## open
|
||||
+ `root`=None
|
||||
+ `profile`=default
|
||||
|
||||
Open a CoW session. Optional `root=` (directory). Default: entry file directory.
|
||||
`profile=` selects the caps row from `## profile` (echoed by `inspect`).
|
||||
|
||||
**sess = open_native root=`root`**
|
||||
**prof = profile name=`profile`**
|
||||
**sess = table.put in=`sess` at="profile" value=`prof`**
|
||||
*sess*
|
||||
|
||||
## write
|
||||
+ `id`
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
Write text into the session upper layer (host tree unchanged until `commit`).
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_write id=`id` path=`path` text=`text`*
|
||||
|
||||
## read
|
||||
+ `id`
|
||||
+ `path`
|
||||
|
||||
Read through CoW (upper, else lower; whiteout misses).
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_read id=`id` path=`path`*
|
||||
|
||||
## remove
|
||||
+ `id`
|
||||
+ `path`
|
||||
|
||||
Logical delete (whiteout).
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_remove id=`id` path=`path`*
|
||||
|
||||
## diff
|
||||
+ `id`
|
||||
|
||||
List of `{ path, kind }` pending changes (`write` | `remove`).
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_diff id=`id`*
|
||||
|
||||
## commit
|
||||
+ `id`
|
||||
|
||||
Apply upper / whiteout to the real workspace root.
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_commit id=`id`*
|
||||
|
||||
## discard
|
||||
+ `id`
|
||||
|
||||
Drop the session without writing the host tree.
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_discard id=`id`*
|
||||
|
||||
## run
|
||||
+ `id`
|
||||
+ `source`=None
|
||||
+ `path`=None
|
||||
|
||||
Run Marqdo under sandbox caps (`exec` / `net` / `plugin` off; fs via CoW).
|
||||
Pass `source=` or `path=` (relative to session root).
|
||||
|
||||
> ensure_plugin
|
||||
|
||||
1. `source`
|
||||
*> sandbox_run id=`id` source=`source`*
|
||||
2. `path`
|
||||
*> sandbox_run id=`id` path=`path`*
|
||||
3. *
|
||||
> print text=ext/ai/sandbox.run: need source= or path=
|
||||
> sys.exit code=1
|
||||
|
||||
## inspect_native
|
||||
+ `id`
|
||||
|
||||
> ensure_plugin
|
||||
*> sandbox_inspect id=`id`*
|
||||
|
||||
## inspect
|
||||
+ `id`
|
||||
+ `profile`=default
|
||||
|
||||
Native caps / change counts, plus the GFM `## profile` row under key `profile`.
|
||||
|
||||
**raw = inspect_native id=`id`**
|
||||
**prof = profile name=`profile`**
|
||||
**out = table.put in=`raw` at="profile" value=`prof`**
|
||||
*out*
|
||||
|
||||
## report
|
||||
+ `id`
|
||||
+ `path`=sandbox-diff.md
|
||||
|
||||
O4: write a markdown review of `## diff` for `marqdo view` / HITL (static report file, not a UI rewrite).
|
||||
|
||||
**pending = diff id=`id`**
|
||||
**n = len value=`pending`**
|
||||
**body = "# Sandbox diff report\n\nPending changes: "**
|
||||
**body = body + n**
|
||||
**body = body + "\n\n| path | kind |\n|------|------|\n"**
|
||||
- [row](pending)
|
||||
**p = [path](row)**
|
||||
**k = [kind](row)**
|
||||
**body = body + "| "**
|
||||
**body = body + p**
|
||||
**body = body + " | "**
|
||||
**body = body + k**
|
||||
**body = body + " |\n"**
|
||||
> fs.write_text path=`path` text=`body`
|
||||
|
||||
**out = **
|
||||
|
||||
| path | count |
|
||||
|------|-------|
|
||||
| `path` | `n` |
|
||||
|
||||
*out*
|
||||
+57
-21
@@ -3,6 +3,8 @@ title: ext/ai/智能体
|
||||
description: 文档驱动智能体 v2 — 单步 / 多步 / 运行;技能编译经 ABI v2 agent 插件(情景 → 学习 → llm_free)。
|
||||
导入 大模型:ext/ai/大模型.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import sandbox:ext/ai/sandbox.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import json:lib/json.mq.md
|
||||
导入 系统:lib/系统.mq.md
|
||||
导入 自写回:lib/自写回.mq.md
|
||||
@@ -86,13 +88,14 @@ import json:lib/json.mq.md
|
||||
> 系统.退出 码=1
|
||||
|
||||
**id = > agent_alloc**
|
||||
**h = > json.parse text={"_type":"智能体"}**
|
||||
**h = > json.set map=`h` key="id" value=`id`**
|
||||
**h = > json.set map=`h` key="model" value=`大模型`**
|
||||
**h = > json.set map=`h` key="tools" value=`工具`**
|
||||
`h` =
|
||||
|
||||
| _type | id | model | tools |
|
||||
|-------|-----|-------|-------|
|
||||
| 智能体 | `id` | `大模型` | `工具` |
|
||||
|
||||
1. `站立提示`
|
||||
**h = > json.set map=`h` key="standing" value=`站立提示`**
|
||||
**h = table.put in=`h` at="standing" value=`站立提示`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
@@ -106,23 +109,42 @@ import json:lib/json.mq.md
|
||||
> agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## 试跑
|
||||
+ `路径`=None
|
||||
+ `源码`=None
|
||||
+ `根目录`=None
|
||||
+ `写入路径`=None
|
||||
+ `文本`=None
|
||||
+ `提交`=真
|
||||
+ `配置`=default
|
||||
|
||||
O1 可选沙盒试跑。转发 `agent.trial`(表风格返回;宿主树在成功 `提交` 前不变)。
|
||||
|
||||
*> agent.trial path=`路径` source=`源码` root=`根目录` write_path=`写入路径` text=`文本` commit=`提交` profile=`配置`*
|
||||
|
||||
## 单步
|
||||
+ `任务`
|
||||
+ `写回`=真
|
||||
+ `流式`=假
|
||||
+ `打印增量`=假
|
||||
+ `沙盒`=假
|
||||
+ `沙盒配置`=default
|
||||
|
||||
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 *map*(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
|
||||
|
||||
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。
|
||||
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。`沙盒=真` 时结果附带沙盒配置行。
|
||||
|
||||
**ctx = > 构建单步上下文 智能体=`自` 任务=`任务`**
|
||||
**id = > json.get value=`自` key="id"**
|
||||
**model = > json.get value=`自` key="model"**
|
||||
**tools = > json.get value=`自` key="tools"**
|
||||
|
||||
**user_turn = > json.parse text={"role":"user"}**
|
||||
**user_turn = > json.set map=`user_turn` key="content" value=`任务`**
|
||||
`user_turn` =
|
||||
|
||||
| role | content |
|
||||
|------|---------|
|
||||
| user | `任务` |
|
||||
|
||||
> agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
1. `流式`
|
||||
@@ -134,9 +156,11 @@ import json:lib/json.mq.md
|
||||
**reply = > trim value=`reply`**
|
||||
**decision = reply**
|
||||
**tool_name = > 提取工具名 回复=`reply`**
|
||||
**out = > json.parse text={"status":"ok"}**
|
||||
**out = > json.set map=`out` key="task" value=`任务`**
|
||||
**out = > json.set map=`out` key="decision" value=`decision`**
|
||||
`out` =
|
||||
|
||||
| status | task | decision |
|
||||
|--------|------|----------|
|
||||
| ok | `任务` | `decision` |
|
||||
|
||||
1. `tool_name`
|
||||
**tool_out = > 运行工具 工具=`tools` 名=`tool_name`**
|
||||
@@ -144,8 +168,8 @@ import json:lib/json.mq.md
|
||||
**deny = > split value=`tool_s` sep="Tool not allowed"**
|
||||
**deny_n = > len value=`deny`**
|
||||
1. `deny_n` > 1
|
||||
**out = > json.set map=`out` key="status" value="error"**
|
||||
**out = > json.set map=`out` key="error" value=`tool_s`**
|
||||
**out = table.put in=`out` at="status" value="error"**
|
||||
**out = table.put in=`out` at="error" value=`tool_s`**
|
||||
**reply = tool_s**
|
||||
2. *
|
||||
**task_s = > json.stringify value=`任务`**
|
||||
@@ -161,16 +185,25 @@ import json:lib/json.mq.md
|
||||
**reply = > 大模型.流式结果 事件=`evs2`**
|
||||
2. *
|
||||
**reply = > model.运行 提示=`fp`**
|
||||
**out = > json.set map=`out` key="tool" value=`tool_name`**
|
||||
**out = > json.set map=`out` key="tool_result" value=`tool_s`**
|
||||
**out = > json.set map=`out` key="result" value=`reply`**
|
||||
**out = table.put in=`out` at="tool" value=`tool_name`**
|
||||
**out = table.put in=`out` at="tool_result" value=`tool_s`**
|
||||
**out = table.put in=`out` at="result" value=`reply`**
|
||||
2. *
|
||||
**out = > json.set map=`out` key="result" value=`reply`**
|
||||
**out = table.put in=`out` at="result" value=`reply`**
|
||||
|
||||
**as_turn = > json.parse text={"role":"assistant"}**
|
||||
**as_turn = > json.set map=`as_turn` key="content" value=`reply`**
|
||||
`as_turn` =
|
||||
|
||||
| role | content |
|
||||
|------|---------|
|
||||
| assistant | `reply` |
|
||||
> agent_history_append id=`id` item=`as_turn`
|
||||
|
||||
1. `沙盒`
|
||||
**配置行 = sandbox.profile name=`沙盒配置`**
|
||||
**out = table.put in=`out` at="sandbox_profile" value=`配置行`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
1. `写回`
|
||||
**body = > json.stringify value=`out`**
|
||||
**st = > json.get value=`out` key="status"**
|
||||
@@ -296,14 +329,17 @@ Engineering First Information 门闩。转发 `agent.preflight`。
|
||||
+ `强制`=False
|
||||
+ `路由`=auto
|
||||
+ `路由模型`=None
|
||||
+ `沙盒`=False
|
||||
+ `沙盒配置`=default
|
||||
+ `工程预检`=True
|
||||
|
||||
v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`|`marqdo`|`small-llm`|`llm`(`jev` 为 `small-llm` 兼容别名);决策器用 `路由模型`(任意 llm 句柄)。
|
||||
v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`|`marqdo`|`small-llm`|`llm`(`jev` 为 `small-llm` 兼容别名);决策器用 `路由模型`(任意 llm 句柄)。`沙盒=真` 走 CoW 试跑;`工程预检` 对应 `efi`。
|
||||
|
||||
**model = > json.get value=`self` key="model"**
|
||||
**tools = > json.get value=`self` key="tools"**
|
||||
**standing = > json.get value=`self` key="standing"**
|
||||
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
|
||||
*> en.run task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` learn=`学习` verify=`校验` writeback=`写回` reuse=`复用` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` improve_every=`改进周期` explore_n=`探索次数` max_rounds=`最大轮次` stream=`流式` echo=`打印增量` trace=`轨迹` force=`强制` router=`路由` router_model=`路由模型`*
|
||||
*> en.run task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` learn=`学习` verify=`校验` writeback=`写回` reuse=`复用` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` improve_every=`改进周期` explore_n=`探索次数` max_rounds=`最大轮次` stream=`流式` echo=`打印增量` trace=`轨迹` force=`强制` router=`路由` router_model=`路由模型` sandbox=`沙盒` sandbox_profile=`沙盒配置` efi=`工程预检`*
|
||||
|
||||
## 路由
|
||||
+ `任务`
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: ext/ai/沙盒
|
||||
description: >-
|
||||
AI 试跑 CoW 工作区:打开 / 运行 / 差异 / 提交(中文面,委托英文 sandbox 模块)。
|
||||
import sandbox:ext/ai/sandbox.mq.md
|
||||
---
|
||||
|
||||
## 打开
|
||||
+ `根`=None
|
||||
|
||||
*> sandbox.open root=`根`*
|
||||
|
||||
## 写入
|
||||
+ `id`
|
||||
+ `路径`
|
||||
+ `文本`
|
||||
|
||||
*> sandbox.write id=`id` path=`路径` text=`文本`*
|
||||
|
||||
## 读取
|
||||
+ `id`
|
||||
+ `路径`
|
||||
|
||||
*> sandbox.read id=`id` path=`路径`*
|
||||
|
||||
## 删除
|
||||
+ `id`
|
||||
+ `路径`
|
||||
|
||||
*> sandbox.remove id=`id` path=`路径`*
|
||||
|
||||
## 差异
|
||||
+ `id`
|
||||
|
||||
*> sandbox.diff id=`id`*
|
||||
|
||||
## 提交
|
||||
+ `id`
|
||||
|
||||
*> sandbox.commit id=`id`*
|
||||
|
||||
## 丢弃
|
||||
+ `id`
|
||||
|
||||
*> sandbox.discard id=`id`*
|
||||
|
||||
## 运行
|
||||
+ `id`
|
||||
+ `源码`=None
|
||||
+ `路径`=None
|
||||
|
||||
1. `源码`
|
||||
*> sandbox.run id=`id` source=`源码`*
|
||||
2. `路径`
|
||||
*> sandbox.run id=`id` path=`路径`*
|
||||
3. *
|
||||
> print text=沙盒.运行: 需要 源码= 或 路径=
|
||||
> sys.exit code=1
|
||||
|
||||
## 检查
|
||||
+ `id`
|
||||
|
||||
*> sandbox.inspect id=`id`*
|
||||
+3
-2
@@ -1,9 +1,10 @@
|
||||
---
|
||||
title: ext/net/url
|
||||
description: URL helpers (stdlib host wrappers). ADR 0007.
|
||||
description: URL helpers (stdlib wrappers). ADR 0007.
|
||||
import net:lib/net.mq.md
|
||||
---
|
||||
|
||||
## encode
|
||||
+ `text`
|
||||
|
||||
*> host_url_encode text=`text`*
|
||||
*> net.url_encode text=`text`*
|
||||
+2
-2
@@ -11,7 +11,7 @@ Persist run output in .mq.md (Jupyter-style writeback)
|
||||
+ `key`=None
|
||||
+ `line`=None
|
||||
|
||||
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` replaces the unkeyed EOF block. With `key=` (e.g. `ok` / `error`), replace or create that named slot only — slots do not overwrite each other. Optional `line=` anchors the block under that source line (needed when writing from a subtask).
|
||||
Write `value` into the entry file. Image-like values (`.png` / `.svg` / … or `data:image/…`) become `` (or ``); other values use `<!-- marqdo-out … -->`. Default: insert or replace the block immediately below the call; `at_end=true` replaces the unkeyed EOF block. With `key=` (e.g. `ok` / `error`), replace or create that named slot only — slots do not overwrite each other. Optional `line=` anchors the block under that source line (needed when writing from a subtask).
|
||||
|
||||
*> host_writeback_record value=`value` at_end=`at_end` key=`key` line=`line`*
|
||||
|
||||
@@ -51,6 +51,6 @@ List all output blocks in the entry file (includes `key` when named).
|
||||
## scan_path
|
||||
+ `path`
|
||||
|
||||
List `<!-- marqdo-out … -->` slots in any file (workbook inspection).
|
||||
List writeback slots in any file (HTML comment and `` image forms; workbook inspection).
|
||||
|
||||
*> host_writeback_scan_path path=`path`*
|
||||
+2
-2
@@ -11,7 +11,7 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
+ `键`=None
|
||||
+ `行`=None
|
||||
|
||||
在入口文件中写入 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时替换无键末尾块。带 `键=`(如 `ok` / `error` / `成功` / `失败`)时只更新该命名槽,互不覆盖。可选 `行=` 锚定到指定源码行(子任务写回时需要)。
|
||||
在入口文件中写入自写回块:若 `值` 像图片路径/URL(`.png` / `.svg` / … 或 `data:image/…`)则写成 ``,否则写成 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时替换无键末尾块。带 `键=`(如 `ok` / `error` / `成功` / `失败`)时只更新该命名槽,互不覆盖。可选 `行=` 锚定到指定源码行(子任务写回时需要)。
|
||||
|
||||
*> host_writeback_record value=`值` at_end=`末尾` key=`键` line=`行`*
|
||||
|
||||
@@ -51,6 +51,6 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
## 扫描路径
|
||||
+ `路径`
|
||||
|
||||
扫描任意文件中的 `<!-- marqdo-out … -->` 槽(工作簿观察)。
|
||||
扫描任意文件中的自写回槽(注释块与 `` 图片;工作簿观察)。
|
||||
|
||||
*> host_writeback_scan_path path=`路径`*
|
||||
+170
-1
@@ -511,11 +511,25 @@ fn write_skill_concept(
|
||||
quality: i64,
|
||||
hits: i64,
|
||||
now: &str,
|
||||
meta: &SkillMeta,
|
||||
) -> Result<(), String> {
|
||||
if let Some(p) = path.parent() {
|
||||
fs::create_dir_all(p).map_err(|e| format!("mkdir: {e}"))?;
|
||||
}
|
||||
let title: String = goal.chars().take(48).collect();
|
||||
let mut extra = String::new();
|
||||
if let Some(ref s) = meta.applies_when {
|
||||
extra.push_str(&format!("applies_when: {}\n", yaml_escape(s)));
|
||||
}
|
||||
if let Some(ref s) = meta.fixtures {
|
||||
extra.push_str(&format!("fixtures: {}\n", yaml_escape(s)));
|
||||
}
|
||||
if let Some(ref s) = meta.sandbox_profile {
|
||||
extra.push_str(&format!("sandbox_profile: {}\n", yaml_escape(s)));
|
||||
}
|
||||
if let Some(ref s) = meta.proof {
|
||||
extra.push_str(&format!("proof: {}\n", yaml_escape(s)));
|
||||
}
|
||||
let body = format!(
|
||||
r#"---
|
||||
type: Marqdo Agent Skill
|
||||
@@ -526,7 +540,7 @@ status: {status}
|
||||
llm_free: {llm_free}
|
||||
quality: {quality}
|
||||
hits: {hits}
|
||||
generated:
|
||||
{extra}generated:
|
||||
by: marqdo-agent/plan
|
||||
at: {now}
|
||||
verified:
|
||||
@@ -545,11 +559,29 @@ Prefer spawning `resource` over re-planning.
|
||||
llm_free = if llm_free { "true" } else { "false" },
|
||||
quality = quality,
|
||||
hits = hits,
|
||||
extra = extra,
|
||||
now = now,
|
||||
);
|
||||
fs::write(path, body).map_err(|e| format!("write skill: {e}"))
|
||||
}
|
||||
|
||||
#[derive(Default)]
|
||||
struct SkillMeta {
|
||||
applies_when: Option<String>,
|
||||
fixtures: Option<String>,
|
||||
sandbox_profile: Option<String>,
|
||||
proof: Option<String>,
|
||||
}
|
||||
|
||||
fn skill_meta_from_src(src: &str) -> SkillMeta {
|
||||
SkillMeta {
|
||||
applies_when: extract_fm_field(src, "applies_when"),
|
||||
fixtures: extract_fm_field(src, "fixtures"),
|
||||
sandbox_profile: extract_fm_field(src, "sandbox_profile"),
|
||||
proof: extract_fm_field(src, "proof"),
|
||||
}
|
||||
}
|
||||
|
||||
fn refresh_index(root: &Path, slug: &str, goal: &str) -> Result<(), String> {
|
||||
let index = root.join("index.md");
|
||||
let line = format!(
|
||||
@@ -585,6 +617,10 @@ fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
|
||||
.ok_or_else(|| format!("missing text `{key}`"))
|
||||
}
|
||||
|
||||
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 opt_tools(args: &Value) -> Option<&Value> {
|
||||
args.get("tools").filter(|t| !t.is_null())
|
||||
}
|
||||
@@ -1107,6 +1143,54 @@ pub fn kb_record_hit(args: &Value) -> Result<Value, String> {
|
||||
}))
|
||||
}
|
||||
|
||||
/// Run workbook (or FM `proof:` / `fixtures:` path) inside CoW sandbox; discard after.
|
||||
/// O2: llm_free promote requires this proof to succeed (unless `require_proof=false`).
|
||||
fn sandbox_proof(workbook: &Path, proof_rel: Option<&str>) -> Result<(bool, String), String> {
|
||||
let root = workbook
|
||||
.parent()
|
||||
.ok_or_else(|| "sandbox_proof: workbook has no parent".to_string())?;
|
||||
// Always pass an absolute root so host `sandbox_open` does not re-join cwd.
|
||||
let root_abs = if root.is_absolute() {
|
||||
root.to_path_buf()
|
||||
} else {
|
||||
fs::canonicalize(root).unwrap_or_else(|_| {
|
||||
std::env::current_dir()
|
||||
.unwrap_or_else(|_| PathBuf::from("."))
|
||||
.join(root)
|
||||
})
|
||||
};
|
||||
let root_abs = fs::canonicalize(&root_abs).unwrap_or(root_abs);
|
||||
let default_name = workbook
|
||||
.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.ok_or_else(|| "sandbox_proof: bad workbook name".to_string())?;
|
||||
let path = proof_rel.unwrap_or(default_name);
|
||||
let open = crate::host_query_json_args(
|
||||
"sandbox_open",
|
||||
&json!({ "root": root_abs.to_string_lossy() }),
|
||||
)?;
|
||||
let id = open
|
||||
.get("id")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "sandbox_proof: open missing id".to_string())?
|
||||
.to_string();
|
||||
let run = crate::host_query_json_args("sandbox_run", &json!({ "id": id, "path": path }));
|
||||
let _ = crate::host_query_json_args("sandbox_discard", &json!({ "id": id }));
|
||||
match run {
|
||||
Ok(r) => {
|
||||
let ok = r.get("ok").and_then(|v| v.as_bool()).unwrap_or(false);
|
||||
let detail = r
|
||||
.get("stderr")
|
||||
.and_then(|v| v.as_str())
|
||||
.or_else(|| r.get("stdout").and_then(|v| v.as_str()))
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
Ok((ok, detail))
|
||||
}
|
||||
Err(e) => Ok((false, e)),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn kb_promote(args: &Value) -> Result<Value, String> {
|
||||
let kb = arg_text(args, "kb_dir")?;
|
||||
let goal = arg_text(args, "goal")?;
|
||||
@@ -1119,6 +1203,26 @@ pub fn kb_promote(args: &Value) -> Result<Value, String> {
|
||||
let src_path = resolve_path(workbook);
|
||||
let src = fs::read_to_string(&src_path)
|
||||
.map_err(|e| format!("kb_promote read workbook: {e}"))?;
|
||||
let require_proof = args
|
||||
.get("require_proof")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(true);
|
||||
let proof_rel = extract_fm_field(&src, "proof")
|
||||
.or_else(|| extract_fm_field(&src, "fixtures"));
|
||||
if require_proof {
|
||||
let (ok, detail) = sandbox_proof(&src_path, proof_rel.as_deref())?;
|
||||
if !ok {
|
||||
return Ok(json!({
|
||||
"promoted": false,
|
||||
"reason": "sandbox_proof_failed",
|
||||
"detail": detail,
|
||||
"sig": sig,
|
||||
"slug": slug,
|
||||
"workbook": workbook,
|
||||
"proof": proof_rel.unwrap_or_else(|| src_path.file_name().and_then(|s| s.to_str()).unwrap_or("").to_string()),
|
||||
}));
|
||||
}
|
||||
}
|
||||
let (llm_free, quality) = llm_free_score(&src);
|
||||
let status = if llm_free { "stable" } else { "candidate" };
|
||||
|
||||
@@ -1168,6 +1272,7 @@ pub fn kb_promote(args: &Value) -> Result<Value, String> {
|
||||
&now,
|
||||
&extra_aliases,
|
||||
)?;
|
||||
let meta = skill_meta_from_src(&src);
|
||||
write_skill_concept(
|
||||
&skill_path,
|
||||
&sig,
|
||||
@@ -1178,6 +1283,7 @@ pub fn kb_promote(args: &Value) -> Result<Value, String> {
|
||||
quality,
|
||||
prev_hits,
|
||||
&now,
|
||||
&meta,
|
||||
)?;
|
||||
refresh_index(&root, &slug, &goal_n)?;
|
||||
|
||||
@@ -1190,6 +1296,69 @@ pub fn kb_promote(args: &Value) -> Result<Value, String> {
|
||||
"quality": quality,
|
||||
"status": status,
|
||||
"hits": prev_hits,
|
||||
"proof_ok": true,
|
||||
"applies_when": meta.applies_when,
|
||||
"fixtures": meta.fixtures,
|
||||
"sandbox_profile": meta.sandbox_profile,
|
||||
}))
|
||||
}
|
||||
|
||||
/// O5: mark a skill concept as `status: quarantine` and keep fixtures path in FM.
|
||||
pub fn kb_quarantine(args: &Value) -> Result<Value, String> {
|
||||
let kb = arg_text(args, "kb_dir")?;
|
||||
let slug = arg_text(args, "slug")?;
|
||||
let reason = opt_text(args, "reason").unwrap_or("sandbox_or_harness_failed");
|
||||
let root = resolve_path(kb);
|
||||
let skill_path = root.join("concepts/skills").join(format!("{slug}.md"));
|
||||
if !skill_path.is_file() {
|
||||
return Ok(json!({
|
||||
"ok": false,
|
||||
"reason": "skill_not_found",
|
||||
"slug": slug,
|
||||
"path": skill_path.to_string_lossy(),
|
||||
}));
|
||||
}
|
||||
let src = fs::read_to_string(&skill_path)
|
||||
.map_err(|e| format!("kb_quarantine read: {e}"))?;
|
||||
let mut lines: Vec<String> = Vec::new();
|
||||
let mut saw_status = false;
|
||||
let mut in_fm = false;
|
||||
for line in src.lines() {
|
||||
let t = line.trim();
|
||||
if t == "---" {
|
||||
if !in_fm {
|
||||
in_fm = true;
|
||||
lines.push(line.to_string());
|
||||
continue;
|
||||
} else {
|
||||
if !saw_status {
|
||||
lines.push("status: quarantine".to_string());
|
||||
}
|
||||
lines.push(format!("quarantine_reason: {}", yaml_escape(reason)));
|
||||
in_fm = false;
|
||||
lines.push(line.to_string());
|
||||
continue;
|
||||
}
|
||||
}
|
||||
if in_fm && t.starts_with("status:") {
|
||||
lines.push("status: quarantine".to_string());
|
||||
saw_status = true;
|
||||
continue;
|
||||
}
|
||||
if in_fm && t.starts_with("llm_free:") {
|
||||
lines.push("llm_free: false".to_string());
|
||||
continue;
|
||||
}
|
||||
lines.push(line.to_string());
|
||||
}
|
||||
let body = lines.join("\n") + "\n";
|
||||
fs::write(&skill_path, body).map_err(|e| format!("kb_quarantine write: {e}"))?;
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"slug": slug,
|
||||
"status": "quarantine",
|
||||
"reason": reason,
|
||||
"path": skill_path.to_string_lossy(),
|
||||
}))
|
||||
}
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@ mod mcp_server;
|
||||
mod memory;
|
||||
mod resume;
|
||||
mod route;
|
||||
mod sandbox;
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::ffi::{CStr, CString};
|
||||
@@ -900,6 +901,7 @@ kb_ffi!(agent_corpus_search, corpus::corpus_search, "agent_corpus_search");
|
||||
kb_ffi!(agent_mcp_fixture, corpus::mcp_fixture, "agent_mcp_fixture");
|
||||
kb_ffi!(agent_kb_add_alias, kb::kb_add_alias, "agent_kb_add_alias");
|
||||
kb_ffi!(agent_kb_promote, kb::kb_promote, "agent_kb_promote");
|
||||
kb_ffi!(agent_kb_quarantine, kb::kb_quarantine, "agent_kb_quarantine");
|
||||
kb_ffi!(agent_kb_record_hit, kb::kb_record_hit, "agent_kb_record_hit");
|
||||
kb_ffi!(
|
||||
agent_workbook_solidify,
|
||||
@@ -1066,6 +1068,15 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_kb_quarantine",
|
||||
"kb_dir,slug",
|
||||
agent_kb_quarantine,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_record_hit", "kb_dir,goal", agent_kb_record_hit) != 0 {
|
||||
return 1;
|
||||
}
|
||||
@@ -1180,6 +1191,34 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
// Optional JSON keys only — empty params CSV so omitted args are not required.
|
||||
if register(host, "sandbox_open", "", sandbox::sandbox_open) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_write", "", sandbox::sandbox_write) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_read", "", sandbox::sandbox_read) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_remove", "", sandbox::sandbox_remove) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_diff", "", sandbox::sandbox_diff) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_commit", "", sandbox::sandbox_commit) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_discard", "", sandbox::sandbox_discard) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_inspect", "", sandbox::sandbox_inspect) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "sandbox_run", "", sandbox::sandbox_run) != 0 {
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
|
||||
@@ -1038,10 +1038,17 @@ pub fn resolve_task(args: &Value) -> Result<Value, String> {
|
||||
"tools": args.get("tools").cloned().unwrap_or(Value::Null),
|
||||
}))?;
|
||||
if hit.is_null() {
|
||||
// Keep field set aligned with hit path so facades can safely read llm_free
|
||||
// (qdagent / agent.run crashed on missing key when OKF is cold).
|
||||
return Ok(json!({
|
||||
"mode": "unknown",
|
||||
"match": null,
|
||||
"skill": null,
|
||||
"resource": null,
|
||||
"slug": null,
|
||||
"status": null,
|
||||
"llm_free": false,
|
||||
"score": null,
|
||||
"confidence": 0.0,
|
||||
}));
|
||||
}
|
||||
@@ -1078,6 +1085,25 @@ pub fn resolve_task(args: &Value) -> Result<Value, String> {
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn resolve_miss_includes_llm_free() {
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-resolve-miss-{}",
|
||||
std::process::id()
|
||||
));
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
let out = resolve_task(&json!({
|
||||
"task": "no-such-skill-cold-miss",
|
||||
"kb_dir": dir.to_string_lossy(),
|
||||
"near_match": false,
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(out.get("mode").and_then(|v| v.as_str()), Some("unknown"));
|
||||
assert_eq!(out.get("llm_free").and_then(|v| v.as_bool()), Some(false));
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn record_and_cluster_and_compile() {
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
//! Forward `sandbox_*` plugin calls to host_query (CoW lives in the host).
|
||||
|
||||
use super::{
|
||||
host_query_json_args, parse_args, set_err, set_out,
|
||||
};
|
||||
use std::os::raw::c_char;
|
||||
|
||||
fn forward(
|
||||
query_name: &str,
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> i32 {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("{query_name}: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match host_query_json_args(query_name, &v) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &e);
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
macro_rules! sandbox_ffi {
|
||||
($fn_name:ident, $query:expr) => {
|
||||
pub unsafe extern "C" fn $fn_name(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> i32 {
|
||||
forward($query, args_json, out_json, err_msg)
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
sandbox_ffi!(sandbox_open, "sandbox_open");
|
||||
sandbox_ffi!(sandbox_write, "sandbox_write");
|
||||
sandbox_ffi!(sandbox_read, "sandbox_read");
|
||||
sandbox_ffi!(sandbox_remove, "sandbox_remove");
|
||||
sandbox_ffi!(sandbox_diff, "sandbox_diff");
|
||||
sandbox_ffi!(sandbox_commit, "sandbox_commit");
|
||||
sandbox_ffi!(sandbox_discard, "sandbox_discard");
|
||||
sandbox_ffi!(sandbox_inspect, "sandbox_inspect");
|
||||
sandbox_ffi!(sandbox_run, "sandbox_run");
|
||||
+42
-6
@@ -245,7 +245,12 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
let status = r.status();
|
||||
if status != 200 {
|
||||
let text = read_limited(r.into_reader())?;
|
||||
return Err(format!("HTTP {status}: {text}"));
|
||||
return Ok(json!({
|
||||
"events": [{"type": "error", "message": format!("HTTP {status}: {text}")}],
|
||||
"finish": "error",
|
||||
"error": format!("HTTP {status}: {text}"),
|
||||
"transport": "plugin",
|
||||
}));
|
||||
}
|
||||
let events = parse_sse_events(BufReader::new(r.into_reader()), echo)?;
|
||||
Ok(json!({
|
||||
@@ -256,9 +261,19 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
}
|
||||
Err(ureq::Error::Status(code, r)) => {
|
||||
let text = read_limited(r.into_reader()).unwrap_or_default();
|
||||
Err(format!("HTTP {code}: {text}"))
|
||||
Ok(json!({
|
||||
"events": [{"type": "error", "message": format!("HTTP {code}: {text}")}],
|
||||
"finish": "error",
|
||||
"error": format!("HTTP {code}: {text}"),
|
||||
"transport": "plugin",
|
||||
}))
|
||||
}
|
||||
Err(e) => Err(format!("http POST sse {url}: {e}")),
|
||||
Err(e) => Ok(json!({
|
||||
"events": [{"type": "error", "message": format!("http POST sse {url}: {e}")}],
|
||||
"finish": "error",
|
||||
"error": format!("http POST sse {url}: {e}"),
|
||||
"transport": "plugin",
|
||||
})),
|
||||
}
|
||||
} else {
|
||||
match req.send_string(&body) {
|
||||
@@ -266,7 +281,14 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
let status = r.status();
|
||||
let text = read_limited(r.into_reader())?;
|
||||
if status != 200 {
|
||||
return Err(format!("HTTP {status}: {text}"));
|
||||
return Ok(json!({
|
||||
"text": "",
|
||||
"usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
|
||||
"finish": "error",
|
||||
"error": format!("HTTP {status}: {text}"),
|
||||
"tool_calls": [],
|
||||
"transport": "plugin",
|
||||
}));
|
||||
}
|
||||
let data: Value = serde_json::from_str(&text).map_err(|e| e.to_string())?;
|
||||
let msg = data
|
||||
@@ -299,9 +321,23 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
}
|
||||
Err(ureq::Error::Status(code, r)) => {
|
||||
let text = read_limited(r.into_reader()).unwrap_or_default();
|
||||
Err(format!("HTTP {code}: {text}"))
|
||||
Ok(json!({
|
||||
"text": "",
|
||||
"usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
|
||||
"finish": "error",
|
||||
"error": format!("HTTP {code}: {text}"),
|
||||
"tool_calls": [],
|
||||
"transport": "plugin",
|
||||
}))
|
||||
}
|
||||
Err(e) => Err(format!("http POST {url}: {e}")),
|
||||
Err(e) => Ok(json!({
|
||||
"text": "",
|
||||
"usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
|
||||
"finish": "error",
|
||||
"error": format!("http POST {url}: {e}"),
|
||||
"tool_calls": [],
|
||||
"transport": "plugin",
|
||||
})),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -247,6 +247,7 @@ func NewHandler(appBag map[string]any, entryDir string) (http.Handler, error) {
|
||||
handler := withMiddleware(mux, mw)
|
||||
handler = withRBAC(handler, authCfg.gates, authCfg.loginPath)
|
||||
handler = withTenant(handler, st.tenant)
|
||||
handler = withStripTrailingSlash(handler)
|
||||
return handler, nil
|
||||
}
|
||||
|
||||
@@ -641,6 +642,21 @@ func withTenant(next http.Handler, cfg tenant.Config) http.Handler {
|
||||
})
|
||||
}
|
||||
|
||||
// withStripTrailingSlash rewrites request URLs so that paths like /post/foo/
|
||||
// are routed as /post/foo. The root path "/" is left unchanged.
|
||||
func withStripTrailingSlash(next http.Handler) http.Handler {
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
path := r.URL.Path
|
||||
if len(path) > 1 && path[len(path)-1] == '/' {
|
||||
r.URL.Path = strings.TrimRight(path, "/")
|
||||
if r.URL.Path == "" {
|
||||
r.URL.Path = "/"
|
||||
}
|
||||
}
|
||||
next.ServeHTTP(w, r)
|
||||
})
|
||||
}
|
||||
|
||||
func withMiddleware(next http.Handler, mw middleware.Config) http.Handler {
|
||||
h := next
|
||||
if mw.BodyLimit != nil && *mw.BodyLimit > 0 {
|
||||
|
||||
@@ -152,3 +152,65 @@ func TestNewHandlerIconsRedirectSitemap404(t *testing.T) {
|
||||
t.Fatalf("home missing icon link: %s", rec.Body.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestTrailingSlashNormalization(t *testing.T) {
|
||||
page := map[string]any{"title": "Home", "intro": "<p>home</p>"}
|
||||
a := app.New(map[string]any{"page": page})
|
||||
about := map[string]any{"title": "About", "intro": "<h1>About</h1>", "_route": "/about"}
|
||||
var err error
|
||||
a, err = app.Route(a, "/about", about)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
// Dynamic route: /post/{slug}
|
||||
post := map[string]any{"title": "Post", "intro": "<h1>Post</h1>", "_route": "/post/{slug}"}
|
||||
a, err = app.Route(a, "/post/{slug}", post)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
h, err := httpx.NewHandler(a, "")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
// Static route: /about should work with and without trailing slash.
|
||||
rec := httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/about", nil))
|
||||
if rec.Code != 200 || !strings.Contains(rec.Body.String(), "About") {
|
||||
t.Fatalf("about (no slash) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/about/", nil))
|
||||
if rec.Code != 200 || !strings.Contains(rec.Body.String(), "About") {
|
||||
t.Fatalf("about (trailing slash) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
// Dynamic route: /post/hello should work with and without trailing slash.
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/post/hello", nil))
|
||||
if rec.Code != 200 {
|
||||
t.Fatalf("post/hello (no slash) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/post/hello/", nil))
|
||||
if rec.Code != 200 {
|
||||
t.Fatalf("post/hello (trailing slash) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
// Root path "/" should still work.
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
|
||||
if rec.Code != 200 || !strings.Contains(rec.Body.String(), "Home") {
|
||||
t.Fatalf("root code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
// Query string should be preserved after trailing slash strip.
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/about/?foo=bar", nil))
|
||||
if rec.Code != 200 || !strings.Contains(rec.Body.String(), "About") {
|
||||
t.Fatalf("about (trailing slash + query) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
}
|
||||
+41
-52
@@ -1,29 +1,59 @@
|
||||
---
|
||||
title: Welcome to Marqdo
|
||||
description: User docs home — code is documentation (English)
|
||||
description: User-docs home — code as documentation (English)
|
||||
import math:lib/math.mq.md
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Hi — thanks for reading this far. I am Marqdo’s developer. Marqdo is a language where *code is documentation, and documentation is code*: Markdown markers are the program structure, so what you read is what runs.
|
||||
Hello — and welcome. I built Marqdo so that code is documentation and documentation is code: Markdown markers are the program structure, so what you read is what runs.
|
||||
|
||||
AI already prefers Markdown-shaped output. The idea was: why keep docs and code as two separate worlds? So Marqdo was born as a “docs are code” language. To keep every source renderable as Markdown, files use the `.mq.md` suffix. From early on we aimed for richer tooling — auto-generated YAML for OKF-style knowledge bases, even auto-generated slides — those are later goals. Happily, it already works well as a blogging tool: yes, this site is generated by Marqdo. And when AI writes Marqdo, you tend to burn fewer tokens — wallets everywhere thank you.
|
||||
AI systems already favor Markdown-shaped output. That raised a simple question: why keep docs and programs as two separate artifacts? Marqdo is the answer. The `.mq.md` suffix exists so a file stays renderable as Markdown while remaining executable. Richer OKF-style YAML catalogs and even slide decks are on the roadmap; for now this site itself is generated by Marqdo — and that often saves tokens when an AI is writing with you.
|
||||
|
||||
The language is still young: structure markers, bilingual core names (`print` / `打印`, …), importable stdlibs (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
|
||||
The language is still early: structural markers, English/Chinese builtin aliases (`print` / `打印` …), an importable standard library (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Join in at [GitHub](https://github.com/cflmy/marqdo).
|
||||
|
||||
## Install
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
Pick one way to get the CLI:
|
||||
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"**.
|
||||
|
||||
| Method | Notes |
|
||||
|--------|-------|
|
||||
Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention.
|
||||
|
||||
Write a math block and bind it with a TeX comment:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it: **_svg = math.plot formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
Foreign lets you embed another language. Bind `hi` to a small Python block:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
|
||||
## greet
|
||||
|
||||
When we meet a visitor `who`, we **print text="Welcome, `who`!"** and close with*None*.
|
||||
|
||||
## install
|
||||
|
||||
Install the interpreter (CLI) in any of these ways:
|
||||
|
||||
| Way | Notes |
|
||||
|------|------|
|
||||
| Ubuntu PPA | `sudo add-apt-repository ppa:cflmy/marqdo` then `sudo apt install marqdo` |
|
||||
| GitHub Releases | Prebuilt Windows / Linux zips at [releases](https://github.com/cflmy/marqdo/releases) |
|
||||
| From source | `cargo build --release` (needs Rust) |
|
||||
| GitHub Releases | Prebuilt Windows / Linux packages from [releases](https://github.com/cflmy/marqdo/releases) |
|
||||
| From source | `cargo build --release` (needs a local Rust toolchain) |
|
||||
|
||||
Official extensions version independently of the CLI:
|
||||
Official extensions update independently of the CLI:
|
||||
|
||||
```text
|
||||
marqdo ext add web
|
||||
@@ -31,44 +61,3 @@ marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` tries CDN https://ext.marqdo.com first, then GitHub, then the proxy mirror. See [`features/05-extensions.mq.md`](features/05-extensions.mq.md).
|
||||
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
A small function to say hello:
|
||||
|
||||
> greet who=marqdo
|
||||
|
||||
Named args can include spaces:
|
||||
|
||||
> greet who=marqdo user
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Welcome, `who`!
|
||||
|
||||
*None*
|
||||
|
||||
Beyond the basics above, Marqdo also ships standard libraries: table, time, text, files, system, math, foreign, and more.
|
||||
|
||||
Math and foreign deserve a special mention. With the math library you can bind a formula like this:
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it:
|
||||
|
||||
**`_svg` = > math.plot formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
The foreign library lets you call external code, for example:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: Marqdo’s design is code as documentation, documentation as code.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
+32
-44
@@ -7,12 +7,42 @@ description: 用户文档首页 — 代码即文档(中文版)
|
||||
|
||||
# main
|
||||
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门*代码即文档,文档即代码*的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门「代码即文档,文档即代码」的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
|
||||
AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和代码拆成两套?我们来实现一个文档即代码的语言,所以marqdo应运而生,为了确保代码一定可以被渲染,marqdo的文件后缀定义为了`.mq.md`。在开发之处我们就尝试希望更丰富的支持,自动生成一个yaml文件使得 OKF 式知识库便捷的自动配置,乃至自动生成ppt,自然这都是以后的目标了。不过相当不错的是,至少这会成为一个不错的博客工具——对,这个站点就是 Marqdo 生成的,而且AI输出的时候会节约不少token,你知道的,token烧的太多,钱包会可怜的饿瘦的。
|
||||
AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套?于是有了 marqdo。为了让文件既能当文档渲染又能执行,后缀定为 `.mq.md`。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT;眼下它至少已经是个不错的博客工具——对,这个站点就是 Marqdo 生成的。AI 写 `.mq.md` 时往往更省 token,钱包也会轻松一点。
|
||||
|
||||
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md)(English prose and English builtins).
|
||||
|
||||
想先打个招呼?调用写在入口 `# main` 里才会真的跑——子标题里的方法要等你叫到它。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。
|
||||
|
||||
除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
|
||||
|
||||
比方说,直接写一块公式,并用 TeX 注释标上变量名:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
接着画出来:**_svg = 数学.绘图 formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
外联则允许嵌一段别的语言。把`hi`绑成下面这样即可:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。
|
||||
|
||||
最后,再次欢迎你,尽情体验 marqdo 吧!
|
||||
|
||||
## 问候
|
||||
|
||||
见到访客`谁`时,我们 **打印 内容="欢迎,`谁`!"**,然后收束为*None*。
|
||||
|
||||
## 安装
|
||||
|
||||
解释器(CLI)任选其一:
|
||||
@@ -31,45 +61,3 @@ marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` 下载顺序:CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 [`features/05-扩展.mq.md`](features/05-扩展.mq.md)。
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
|
||||
|
||||
用一个小函数打个招呼:
|
||||
|
||||
> 问候 谁=marqdo
|
||||
|
||||
具名实参可以带空格:
|
||||
|
||||
> 问候 谁=marqdo user
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> 打印 内容=欢迎,`谁`!
|
||||
|
||||
*None*
|
||||
|
||||
除了上面的一些基本内容之外,我还开发了这个语言的一些标准库,包括表、时间、文本、文件、系统、数学和外联等标准库。
|
||||
|
||||
其中数学库和外联库是我要着重提到的,例如数学库,你可以通过下面的方式调用:
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
之后让我们画个图像吧!
|
||||
|
||||
**`_svg` = > 数学.绘图 formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
外联库则允许你调用外部代码,例如:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
这些代码在markdown下面都非常的易读,就像我说的,marqdo的设计思想就是代码即文档,
|
||||
文档即代码。
|
||||
|
||||
最后,再次欢迎你,尽情体验marqdo吧!
|
||||
@@ -5,12 +5,14 @@ description: Local browse and static export from the interpreter
|
||||
|
||||
# main
|
||||
|
||||
Milestone: `marqdo view` and `view output`.
|
||||
Milestone: `marqdo view` and `view output` (v1.4.1 mid→mid annot leaders + document surface).
|
||||
|
||||
Local: `marqdo view public`
|
||||
|
||||
Static export: `marqdo view output public -o public`
|
||||
|
||||
Executable user docs live under `public/`. Generated HTML (`index.html` / `pages/`) is for hosting; CI publishes to `gh-pages`.
|
||||
Browse Structure keeps narration, highlights executable markers, and attaches
|
||||
run results (values, taken branch arms, call/loop frames). The same render path
|
||||
builds this user docs site; CI publishes to `gh-pages`.
|
||||
|
||||
> print text=Docs site: generated by the Marqdo interpreter, not hand-written HTML.
|
||||
@@ -5,12 +5,13 @@ description: 本地浏览与静态导出由解释器生成
|
||||
|
||||
# main
|
||||
|
||||
里程碑:`marqdo view` 与 `view output`。
|
||||
里程碑:`marqdo view` 与 `view output`(v1.4.1 mid→mid 标注连线 + 文档面)。
|
||||
|
||||
本地浏览:`marqdo view public`
|
||||
|
||||
静态导出:`marqdo view output public -o public`
|
||||
|
||||
用户可执行文档在 `public/`;生成的 HTML(`index.html` / `pages/`)供静态托管,CI 发布到 `gh-pages`。
|
||||
Browse Structure 保真叙述、高亮可执行标记,并挂载运行结果(变量值、分支命中臂、调用/循环帧)。
|
||||
用户站与 live view 同源渲染;CI 发布到 `gh-pages`。
|
||||
|
||||
> 打印 内容=文档站:由 Marqdo 解释器生成,不是手写 HTML。
|
||||
@@ -39,6 +39,32 @@ run tests/ext/agent-zero-llm.mq.md
|
||||
run tests/ext/agent-plan-preserve.mq.md
|
||||
run examples/agent-okf-flywheel/index.mq.md
|
||||
run examples/agent-pong/index.mq.md
|
||||
run examples/agent-sandbox-okf/index.mq.md
|
||||
run tests/ext/agent-sandbox-optin.mq.md
|
||||
run tests/ext/agent-sandbox-promote.mq.md
|
||||
|
||||
# Skill Lift subset (O2 B3/E1): with-skill vs without — constitution / writeback / call_site markers.
|
||||
skill_lift_pass=0
|
||||
skill_lift_fail=0
|
||||
assert_out_has() {
|
||||
local f="$1"
|
||||
local needle="$2"
|
||||
local label="$3"
|
||||
local out
|
||||
out="$("$MQ" run "$f" 2>/dev/null || true)"
|
||||
if printf '%s' "$out" | grep -q -- "$needle"; then
|
||||
echo "SkillLift OK $label ($needle)"
|
||||
skill_lift_pass=$((skill_lift_pass + 1))
|
||||
else
|
||||
echo "SkillLift MISS $label (need $needle)" >&2
|
||||
skill_lift_fail=$((skill_lift_fail + 1))
|
||||
fail=1
|
||||
fi
|
||||
}
|
||||
assert_out_has tests/ext/agent-constitution-b0.mq.md "constitution-ok" "constitution"
|
||||
assert_out_has tests/ext/agent-writeback-shadow.mq.md "writeback-shadow-ok" "writeback"
|
||||
assert_out_has tests/ext/agent-dump-context.mq.md "dump-context-ok" "call_site"
|
||||
echo "SkillLift summary: pass=$skill_lift_pass fail=$skill_lift_fail"
|
||||
|
||||
if [[ "${AGENT_HARNESS_LIVE:-}" == "1" ]]; then
|
||||
export AGENT_LIVE=1
|
||||
|
||||
Executable
+45
@@ -0,0 +1,45 @@
|
||||
#!/usr/bin/env bash
|
||||
# O4 — style gate: flag json.set dict chains and mixed EN/ZH API hints in .mq.md.
|
||||
# Exit 0 when clean; 1 when findings (unless MQ_STYLE_LINT_SOFT=1).
|
||||
set -euo pipefail
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
TARGETS=("$@")
|
||||
if [[ ${#TARGETS[@]} -eq 0 ]]; then
|
||||
TARGETS=(ext/ai/sandbox.mq.md ext/ai/policies examples/agent-sandbox-okf)
|
||||
fi
|
||||
|
||||
fail=0
|
||||
findings=0
|
||||
|
||||
scan_file() {
|
||||
local f="$1"
|
||||
[[ -f "$f" ]] || return 0
|
||||
# Long json.set pipelines (3+ consecutive) — style bug per marqdo-dev.
|
||||
if awk '
|
||||
/json\.set/ { c++; if (c >= 3) { found=1 } next }
|
||||
{ c=0 }
|
||||
END { exit found ? 0 : 1 }
|
||||
' "$f"; then
|
||||
echo "STYLE json.set-chain: $f" >&2
|
||||
findings=$((findings + 1))
|
||||
fail=1
|
||||
fi
|
||||
# Same file imports both EN agent and ZH 智能体 (or web/网页) — mixed surface.
|
||||
if grep -qE 'import[[:space:]]+agent:|import[[:space:]]+web:' "$f" \
|
||||
&& grep -qE '导入[[:space:]]+(智能体|网页):' "$f"; then
|
||||
echo "STYLE mixed-EN/ZH-import: $f" >&2
|
||||
findings=$((findings + 1))
|
||||
fail=1
|
||||
fi
|
||||
}
|
||||
|
||||
while IFS= read -r -d '' f; do
|
||||
scan_file "$f"
|
||||
done < <(find "${TARGETS[@]}" -type f -name '*.mq.md' -print0 2>/dev/null)
|
||||
|
||||
echo "mq-style-lint: findings=$findings"
|
||||
if [[ "${MQ_STYLE_LINT_SOFT:-}" == "1" ]]; then
|
||||
exit 0
|
||||
fi
|
||||
exit "$fail"
|
||||
Executable
+58
@@ -0,0 +1,58 @@
|
||||
#!/usr/bin/env bash
|
||||
# O5 — offline standing / policy rewrite hint (GEPA-like, products stay repo files).
|
||||
# Does NOT change the runtime agent path. Reads harness failure log + current files,
|
||||
# writes a suggested patch under .marqdo/optimize/ for human review.
|
||||
set -euo pipefail
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
LOG="${1:-}"
|
||||
STANDING="${2:-ext/ai/agent.mq.md}"
|
||||
POLICY="${3:-ext/ai/policies/step-route.mq.md}"
|
||||
OUT_DIR="${OUT_DIR:-.marqdo/optimize}"
|
||||
mkdir -p "$OUT_DIR"
|
||||
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
|
||||
REPORT="$OUT_DIR/standing-policy-$STAMP.md"
|
||||
|
||||
{
|
||||
echo "# Offline standing / policy optimize suggestion"
|
||||
echo
|
||||
echo "Generated: $STAMP"
|
||||
echo
|
||||
echo "This is a **review artifact**, not an automatic runtime rewrite."
|
||||
echo "Strong models may rewrite \`standing\` / \`policies/*.mq.md\` offline;"
|
||||
echo "commit only after harness green."
|
||||
echo
|
||||
echo "## Inputs"
|
||||
echo
|
||||
echo "- standing source: \`$STANDING\`"
|
||||
echo "- policy source: \`$POLICY\`"
|
||||
if [[ -n "$LOG" && -f "$LOG" ]]; then
|
||||
echo "- harness log: \`$LOG\`"
|
||||
echo
|
||||
echo "## Harness failure excerpt"
|
||||
echo
|
||||
echo '```'
|
||||
tail -n 80 "$LOG" || true
|
||||
echo '```'
|
||||
else
|
||||
echo "- harness log: _(none — pass path as \$1)_"
|
||||
fi
|
||||
echo
|
||||
echo "## Current policy table (copy)"
|
||||
echo
|
||||
if [[ -f "$POLICY" ]]; then
|
||||
echo '```markdown'
|
||||
cat "$POLICY"
|
||||
echo '```'
|
||||
else
|
||||
echo "_missing $POLICY_"
|
||||
fi
|
||||
echo
|
||||
echo "## Suggested next edits"
|
||||
echo
|
||||
echo "1. Keep step-class → backend as a **GFM table** (no json glue)."
|
||||
echo "2. Quarantine failing skills (\`status: quarantine\`) before promoting again."
|
||||
echo "3. Re-run \`scripts/agent-harness.sh\` and confirm Skill Lift summary."
|
||||
} > "$REPORT"
|
||||
|
||||
echo "wrote $REPORT"
|
||||
@@ -124,7 +124,10 @@ if [ "$REUSE_ORIG" -eq 1 ]; then
|
||||
echo "==> reusing published ${ORIG_NAME} (debian-only bump; do not rewrite orig)"
|
||||
echo " source: ${ORIG_SRC}"
|
||||
sha256sum "$ORIG_SRC"
|
||||
cp -f "$ORIG_SRC" "$BUILD_AREA/$ORIG_NAME"
|
||||
# Local fallback may already be build-area/ORIG_NAME — do not cp onto itself.
|
||||
if [ "$(realpath "$ORIG_SRC")" != "$(realpath "$BUILD_AREA/$ORIG_NAME" 2>/dev/null || echo "")" ]; then
|
||||
cp -f "$ORIG_SRC" "$BUILD_AREA/$ORIG_NAME"
|
||||
fi
|
||||
# Unpack orig (top dir is usually ${VER} or marqdo-${VER})
|
||||
tar -xJf "$BUILD_AREA/$ORIG_NAME" -C "$(dirname "$PKG_ROOT")"
|
||||
if [ ! -d "$PKG_ROOT" ]; then
|
||||
|
||||
@@ -32,7 +32,9 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code.
|
||||
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
|
||||
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
|
||||
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
@@ -162,7 +164,9 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
|
||||
|
||||
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`).
|
||||
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/) · [agent-sandbox-okf](../../examples/agent-sandbox-okf/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · optimize O1–O5: [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
|
||||
**Sandbox (O1):** `import sandbox:ext/ai/sandbox.mq.md` · `agent.trial` / `智能体.试跑` · `run`/`step` take `sandbox=` / `沙盒=` (default `False`). Profile caps are tables via `sandbox.profile`. Gold: `tests/ext/agent-sandbox-optin.mq.md`.
|
||||
|
||||
## Official extension: `ext/web` (Document / Endpoint / Resource)
|
||||
|
||||
|
||||
+94
-1
@@ -1,7 +1,98 @@
|
||||
//! Captured program run (for tests and `view`).
|
||||
|
||||
use crate::value::Value;
|
||||
use crate::host::PlotArtifact;
|
||||
use crate::value::Value;
|
||||
|
||||
/// Silent execution trace for view annotations (not stderr `trace_eval`).
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct ViewTrace {
|
||||
pub branches: Vec<BranchHit>,
|
||||
pub loops: Vec<LoopHit>,
|
||||
/// Per-statement post-state / control events (tree capture).
|
||||
pub events: Vec<StmtEvent>,
|
||||
/// User-function invocations (tree capture).
|
||||
pub calls: Vec<CallFrame>,
|
||||
/// Foreach / while loop frames with per-iteration item values.
|
||||
pub loop_frames: Vec<LoopFrame>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct BranchHit {
|
||||
pub line: u32,
|
||||
pub arm_index: usize,
|
||||
pub count: u32,
|
||||
/// Call frame that took this arm (`0` = entry / `# main`).
|
||||
pub call_id: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct LoopHit {
|
||||
pub line: u32,
|
||||
pub iterations: u32,
|
||||
pub last_item: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct LoopFrame {
|
||||
pub loop_id: u32,
|
||||
pub line: u32,
|
||||
pub item_name: Option<String>,
|
||||
pub collection: Option<String>,
|
||||
pub iterations: Vec<LoopIter>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct LoopIter {
|
||||
/// 0-based iteration index.
|
||||
pub index: u32,
|
||||
pub item_value: String,
|
||||
pub call_id: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct StmtEvent {
|
||||
pub line: u32,
|
||||
pub kind: StmtEventKind,
|
||||
pub name: Option<String>,
|
||||
pub value_after: Option<String>,
|
||||
pub arm_index: Option<usize>,
|
||||
/// 0-based iteration index when inside a loop.
|
||||
pub iter: Option<u32>,
|
||||
pub call_id: u32,
|
||||
pub loop_id: Option<u32>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum StmtEventKind {
|
||||
Assign,
|
||||
Return,
|
||||
Call,
|
||||
Branch,
|
||||
Loop,
|
||||
BindRef,
|
||||
}
|
||||
|
||||
impl StmtEventKind {
|
||||
pub fn as_str(self) -> &'static str {
|
||||
match self {
|
||||
StmtEventKind::Assign => "assign",
|
||||
StmtEventKind::Return => "return",
|
||||
StmtEventKind::Call => "call",
|
||||
StmtEventKind::Branch => "branch",
|
||||
StmtEventKind::Loop => "loop",
|
||||
StmtEventKind::BindRef => "bind_ref",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CallFrame {
|
||||
pub call_id: u32,
|
||||
pub fn_name: String,
|
||||
pub fn_line: u32,
|
||||
pub ordinal: u32,
|
||||
pub args_brief: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct RunCapture {
|
||||
@@ -10,4 +101,6 @@ pub struct RunCapture {
|
||||
pub plots: Vec<PlotArtifact>,
|
||||
/// Entry-function bindings after a successful tree-backend run (empty for bytecode).
|
||||
pub bindings: std::collections::HashMap<String, Value>,
|
||||
/// Branch/loop/stmt hits collected during tree capture (empty for bytecode).
|
||||
pub view_trace: ViewTrace,
|
||||
}
|
||||
+14
-1
@@ -34,6 +34,9 @@ fn text_body(v: &Value) -> Result<&str, String> {
|
||||
|
||||
pub fn read_text(ctx: &HostContext, path: &Value) -> Result<Value, String> {
|
||||
let p = ctx.resolve_path(text_path(path)?)?;
|
||||
if let Some(hit) = crate::host::sandbox_fs::cow_read_text(ctx, &p)? {
|
||||
return Ok(Value::Text(hit));
|
||||
}
|
||||
let s = fs::read_to_string(&p).map_err(|e| format!("read_text {}: {e}", p.display()))?;
|
||||
Ok(Value::Text(s))
|
||||
}
|
||||
@@ -43,10 +46,14 @@ pub fn write_text(ctx: &HostContext, path: &Value, text: &Value) -> Result<Value
|
||||
return Err("write_text denied by host policy".into());
|
||||
}
|
||||
let p = ctx.resolve_path(text_path(path)?)?;
|
||||
let body = text_body(text)?;
|
||||
if crate::host::sandbox_fs::cow_write_text(ctx, &p, body)? {
|
||||
return Ok(Value::None);
|
||||
}
|
||||
if let Some(parent) = p.parent() {
|
||||
fs::create_dir_all(parent).map_err(|e| format!("write_text mkdir: {e}"))?;
|
||||
}
|
||||
fs::write(&p, text_body(text)?).map_err(|e| format!("write_text {}: {e}", p.display()))?;
|
||||
fs::write(&p, body).map_err(|e| format!("write_text {}: {e}", p.display()))?;
|
||||
Ok(Value::None)
|
||||
}
|
||||
|
||||
@@ -68,6 +75,9 @@ pub fn append_text(ctx: &HostContext, path: &Value, text: &Value) -> Result<Valu
|
||||
|
||||
pub fn exists(ctx: &HostContext, path: &Value) -> Result<Value, String> {
|
||||
let p = ctx.resolve_path(text_path(path)?)?;
|
||||
if let Some(hit) = crate::host::sandbox_fs::cow_exists(ctx, &p)? {
|
||||
return Ok(Value::Bool(hit));
|
||||
}
|
||||
Ok(Value::Bool(p.exists()))
|
||||
}
|
||||
|
||||
@@ -109,6 +119,9 @@ pub fn remove(ctx: &HostContext, path: &Value) -> Result<Value, String> {
|
||||
return Err("remove denied by host policy".into());
|
||||
}
|
||||
let p = ctx.resolve_path(text_path(path)?)?;
|
||||
if crate::host::sandbox_fs::cow_remove(ctx, &p)? {
|
||||
return Ok(Value::None);
|
||||
}
|
||||
if p.is_dir() {
|
||||
fs::remove_dir_all(&p).map_err(|e| format!("remove {}: {e}", p.display()))?;
|
||||
} else {
|
||||
|
||||
@@ -40,6 +40,7 @@ pub mod subtask;
|
||||
#[cfg(not(feature = "exec-host"))]
|
||||
#[path = "subtask_stub.rs"]
|
||||
pub mod subtask;
|
||||
pub mod sandbox_fs;
|
||||
mod sys;
|
||||
pub mod writeback;
|
||||
|
||||
@@ -111,6 +112,8 @@ pub struct HostContext {
|
||||
pub subtask_seq: u64,
|
||||
/// Minimum log level (`lib/log`); default Info (20). See `host::log::Level`.
|
||||
pub log_min_level: u8,
|
||||
/// Active `ext/ai/sandbox` CoW session id (nested `sandbox_run`).
|
||||
pub sandbox_session: Option<String>,
|
||||
}
|
||||
|
||||
impl Default for HostContext {
|
||||
@@ -135,6 +138,7 @@ impl Default for HostContext {
|
||||
subtasks: HashMap::new(),
|
||||
subtask_seq: 0,
|
||||
log_min_level: 20, // Info
|
||||
sandbox_session: None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+26
-3
@@ -120,6 +120,9 @@ pub fn http_get(
|
||||
headers: Option<&Value>,
|
||||
) -> Result<Value, String> {
|
||||
if !ctx.allow_net() {
|
||||
if ctx.sandbox_session.is_some() {
|
||||
return Err("net unavailable in sandbox".into());
|
||||
}
|
||||
return Err("http_get denied by host policy".into());
|
||||
}
|
||||
let url = as_text(url, "url")?;
|
||||
@@ -137,6 +140,9 @@ pub fn http_post(
|
||||
headers: Option<&Value>,
|
||||
) -> Result<Value, String> {
|
||||
if !ctx.allow_net() {
|
||||
if ctx.sandbox_session.is_some() {
|
||||
return Err("net unavailable in sandbox".into());
|
||||
}
|
||||
return Err("http_post denied by host policy".into());
|
||||
}
|
||||
let url = as_text(url, "url")?;
|
||||
@@ -146,8 +152,13 @@ pub fn http_post(
|
||||
Some(v) => as_text(v, "content_type")?,
|
||||
};
|
||||
let hdrs = headers_from_value(headers)?;
|
||||
let (status, resp) = http_exchange("POST", url, Some(body), Some(ct), &hdrs)?;
|
||||
Ok(response_map(status, resp))
|
||||
// Transport failures → status 0 + body message (soft). Callers that need
|
||||
// hard errors can still treat status!=200 as failure; Agent/LLM surfaces
|
||||
// map this into structured `{finish:error}` instead of aborting the VM.
|
||||
match http_exchange("POST", url, Some(body), Some(ct), &hdrs) {
|
||||
Ok((status, resp)) => Ok(response_map(status, resp)),
|
||||
Err(e) => Ok(response_map(0, e)),
|
||||
}
|
||||
}
|
||||
|
||||
/// Generic request: method + url + optional body / content_type / headers.
|
||||
@@ -161,6 +172,9 @@ pub fn http_request(
|
||||
headers: Option<&Value>,
|
||||
) -> Result<Value, String> {
|
||||
if !ctx.allow_net() {
|
||||
if ctx.sandbox_session.is_some() {
|
||||
return Err("net unavailable in sandbox".into());
|
||||
}
|
||||
return Err("http_request denied by host policy".into());
|
||||
}
|
||||
let method = as_text(method, "method")?.to_uppercase();
|
||||
@@ -838,7 +852,16 @@ pub fn http_post_sse(
|
||||
),
|
||||
]))
|
||||
}
|
||||
Err(e) => Err(format!("http POST sse {url}: {e}")),
|
||||
Err(e) => Ok(Value::Map(vec![
|
||||
("status".into(), Value::Int(0)),
|
||||
(
|
||||
"events".into(),
|
||||
Value::List(vec![event_map(vec![
|
||||
("type", Value::Text("error".into())),
|
||||
("message", Value::Text(format!("http POST sse {url}: {e}"))),
|
||||
])]),
|
||||
),
|
||||
])),
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -417,6 +417,16 @@ unsafe extern "C" fn host_query(
|
||||
});
|
||||
Ok(serde_json::json!({ "ok": true }))
|
||||
})(),
|
||||
name if name.starts_with("sandbox_") => (|| {
|
||||
let raw = args_owned.as_deref().unwrap_or("{}");
|
||||
let args: serde_json::Value = serde_json::from_str(if raw.trim().is_empty() {
|
||||
"{}"
|
||||
} else {
|
||||
raw
|
||||
})
|
||||
.map_err(|e| format!("{name} args: {e}"))?;
|
||||
crate::host::sandbox_fs::query(name, &args, ctx)
|
||||
})(),
|
||||
// ADR 0007: run a Document/Endpoint `.mq.md` for HTTP handlers.
|
||||
"run_artifact" => (|| {
|
||||
let raw = args_owned.as_deref().unwrap_or("{}");
|
||||
@@ -472,6 +482,9 @@ unsafe extern "C" fn host_query(
|
||||
|
||||
pub fn load(ctx: &mut HostContext, path: &Value) -> Result<Value, String> {
|
||||
if !ctx.allow_plugin() {
|
||||
if ctx.sandbox_session.is_some() {
|
||||
return Err("plugin.load unavailable in sandbox".into());
|
||||
}
|
||||
return Err("plugin_load denied by host policy".into());
|
||||
}
|
||||
let rel = as_text(path, "path")?;
|
||||
|
||||
@@ -0,0 +1,475 @@
|
||||
//! Application-level CoW workspace for `ext/ai/sandbox` (via host_query).
|
||||
//!
|
||||
//! lower = real root (read-through); upper = session bytes; whiteout = logical delete.
|
||||
//! Not a symlink forest. Symlink targets are not followed as isolation primitives.
|
||||
|
||||
use std::collections::{HashMap, HashSet};
|
||||
use std::path::{Component, Path, PathBuf};
|
||||
use std::sync::{Mutex, OnceLock};
|
||||
|
||||
use serde_json::json;
|
||||
|
||||
use crate::host::HostContext;
|
||||
use crate::value::Value;
|
||||
|
||||
#[derive(Debug, Default)]
|
||||
pub struct CowSession {
|
||||
pub root: PathBuf,
|
||||
/// Relative path (forward slashes) → file bytes.
|
||||
pub upper: HashMap<String, Vec<u8>>,
|
||||
pub whiteout: HashSet<String>,
|
||||
}
|
||||
|
||||
static SESSIONS: OnceLock<Mutex<HashMap<String, CowSession>>> = OnceLock::new();
|
||||
static SEQ: OnceLock<Mutex<u64>> = OnceLock::new();
|
||||
|
||||
fn sessions() -> &'static Mutex<HashMap<String, CowSession>> {
|
||||
SESSIONS.get_or_init(|| Mutex::new(HashMap::new()))
|
||||
}
|
||||
|
||||
fn next_id() -> String {
|
||||
let mut g = SEQ
|
||||
.get_or_init(|| Mutex::new(0))
|
||||
.lock()
|
||||
.unwrap_or_else(|e| e.into_inner());
|
||||
*g = g.wrapping_add(1);
|
||||
format!("sbx-{g}")
|
||||
}
|
||||
|
||||
fn normalize_rel(rel: &str) -> Result<String, String> {
|
||||
let rel = rel.trim().trim_start_matches('/');
|
||||
if rel.is_empty() {
|
||||
return Err("sandbox path must not be empty".into());
|
||||
}
|
||||
let p = Path::new(rel);
|
||||
if p.is_absolute() {
|
||||
return Err("sandbox path must be relative to session root".into());
|
||||
}
|
||||
let mut out = Vec::new();
|
||||
for c in p.components() {
|
||||
match c {
|
||||
Component::Normal(s) => out.push(s.to_string_lossy().into_owned()),
|
||||
Component::CurDir => {}
|
||||
Component::ParentDir => {
|
||||
return Err("sandbox path must not contain '..'".into());
|
||||
}
|
||||
_ => return Err(format!("sandbox path invalid component in `{rel}`")),
|
||||
}
|
||||
}
|
||||
if out.is_empty() {
|
||||
return Err("sandbox path must not be empty".into());
|
||||
}
|
||||
Ok(out.join("/"))
|
||||
}
|
||||
|
||||
fn abs_under_root(root: &Path, rel: &str) -> Result<PathBuf, String> {
|
||||
let rel_n = normalize_rel(rel)?;
|
||||
let abs = root.join(Path::new(&rel_n));
|
||||
let root_canon = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
|
||||
// Parent may not exist yet for writes — check by prefix components.
|
||||
let mut check = abs.clone();
|
||||
loop {
|
||||
if check == *root || check == root_canon {
|
||||
return Ok(root.join(Path::new(&rel_n)));
|
||||
}
|
||||
if !check.pop() {
|
||||
break;
|
||||
}
|
||||
if let Ok(c) = check.canonicalize() {
|
||||
if crate::host::path_under_root(&c, &root_canon) || c == root_canon {
|
||||
return Ok(root.join(Path::new(&rel_n)));
|
||||
}
|
||||
}
|
||||
}
|
||||
if crate::host::path_under_root(&abs, root) {
|
||||
return Ok(abs);
|
||||
}
|
||||
Err(format!("path escapes sandbox root: {rel_n}"))
|
||||
}
|
||||
|
||||
pub fn open(root: Option<&str>, ctx: &HostContext) -> Result<serde_json::Value, String> {
|
||||
let root_pb = if let Some(r) = root.filter(|s| !s.is_empty()) {
|
||||
let p = PathBuf::from(r);
|
||||
if p.is_absolute() {
|
||||
p
|
||||
} else {
|
||||
ctx.cwd.join(p)
|
||||
}
|
||||
} else if let Some(ep) = &ctx.entry_path {
|
||||
ep.parent()
|
||||
.unwrap_or(ep.as_path())
|
||||
.to_path_buf()
|
||||
} else {
|
||||
ctx.cwd.clone()
|
||||
};
|
||||
let root_pb = if root_pb.is_absolute() {
|
||||
root_pb
|
||||
} else {
|
||||
std::env::current_dir()
|
||||
.unwrap_or_else(|_| PathBuf::from("."))
|
||||
.join(root_pb)
|
||||
};
|
||||
if !root_pb.is_dir() {
|
||||
return Err(format!(
|
||||
"sandbox_open: root is not a directory: {}",
|
||||
root_pb.display()
|
||||
));
|
||||
}
|
||||
let id = next_id();
|
||||
let sess = CowSession {
|
||||
root: root_pb.clone(),
|
||||
upper: HashMap::new(),
|
||||
whiteout: HashSet::new(),
|
||||
};
|
||||
sessions()
|
||||
.lock()
|
||||
.unwrap_or_else(|e| e.into_inner())
|
||||
.insert(id.clone(), sess);
|
||||
Ok(json!({
|
||||
"id": id,
|
||||
"root": root_pb.to_string_lossy(),
|
||||
}))
|
||||
}
|
||||
|
||||
fn with_session_mut<F, T>(id: &str, f: F) -> Result<T, String>
|
||||
where
|
||||
F: FnOnce(&mut CowSession) -> Result<T, String>,
|
||||
{
|
||||
let mut map = sessions().lock().unwrap_or_else(|e| e.into_inner());
|
||||
let sess = map
|
||||
.get_mut(id)
|
||||
.ok_or_else(|| format!("sandbox: unknown session `{id}`"))?;
|
||||
f(sess)
|
||||
}
|
||||
|
||||
fn with_session<F, T>(id: &str, f: F) -> Result<T, String>
|
||||
where
|
||||
F: FnOnce(&CowSession) -> Result<T, String>,
|
||||
{
|
||||
let map = sessions().lock().unwrap_or_else(|e| e.into_inner());
|
||||
let sess = map
|
||||
.get(id)
|
||||
.ok_or_else(|| format!("sandbox: unknown session `{id}`"))?;
|
||||
f(sess)
|
||||
}
|
||||
|
||||
pub fn write(id: &str, path: &str, text: &str) -> Result<serde_json::Value, String> {
|
||||
with_session_mut(id, |sess| {
|
||||
let rel = normalize_rel(path)?;
|
||||
let _ = abs_under_root(&sess.root, &rel)?;
|
||||
sess.whiteout.remove(&rel);
|
||||
sess.upper.insert(rel, text.as_bytes().to_vec());
|
||||
Ok(json!({ "ok": true }))
|
||||
})
|
||||
}
|
||||
|
||||
pub fn read(id: &str, path: &str) -> Result<serde_json::Value, String> {
|
||||
with_session(id, |sess| {
|
||||
let rel = normalize_rel(path)?;
|
||||
if sess.whiteout.contains(&rel) {
|
||||
return Err(format!("sandbox_read: not found (whiteout): {rel}"));
|
||||
}
|
||||
if let Some(bytes) = sess.upper.get(&rel) {
|
||||
let s = String::from_utf8(bytes.clone())
|
||||
.map_err(|e| format!("sandbox_read: not utf-8: {e}"))?;
|
||||
return Ok(json!(s));
|
||||
}
|
||||
let abs = abs_under_root(&sess.root, &rel)?;
|
||||
let s = std::fs::read_to_string(&abs)
|
||||
.map_err(|e| format!("sandbox_read {}: {e}", abs.display()))?;
|
||||
Ok(json!(s))
|
||||
})
|
||||
}
|
||||
|
||||
pub fn remove(id: &str, path: &str) -> Result<serde_json::Value, String> {
|
||||
with_session_mut(id, |sess| {
|
||||
let rel = normalize_rel(path)?;
|
||||
let _ = abs_under_root(&sess.root, &rel)?;
|
||||
sess.upper.remove(&rel);
|
||||
sess.whiteout.insert(rel);
|
||||
Ok(json!({ "ok": true }))
|
||||
})
|
||||
}
|
||||
|
||||
pub fn diff(id: &str) -> Result<serde_json::Value, String> {
|
||||
with_session(id, |sess| {
|
||||
let mut items: Vec<serde_json::Value> = Vec::new();
|
||||
for p in sess.upper.keys() {
|
||||
items.push(json!({ "path": p, "kind": "write" }));
|
||||
}
|
||||
for p in &sess.whiteout {
|
||||
items.push(json!({ "path": p, "kind": "remove" }));
|
||||
}
|
||||
items.sort_by(|a, b| {
|
||||
let pa = a.get("path").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let pb = b.get("path").and_then(|v| v.as_str()).unwrap_or("");
|
||||
pa.cmp(pb)
|
||||
});
|
||||
Ok(json!(items))
|
||||
})
|
||||
}
|
||||
|
||||
pub fn commit(id: &str) -> Result<serde_json::Value, String> {
|
||||
with_session_mut(id, |sess| {
|
||||
let mut applied = 0i64;
|
||||
let writes: Vec<(String, Vec<u8>)> = sess
|
||||
.upper
|
||||
.iter()
|
||||
.map(|(k, v)| (k.clone(), v.clone()))
|
||||
.collect();
|
||||
let removes: Vec<String> = sess.whiteout.iter().cloned().collect();
|
||||
for (rel, bytes) in writes {
|
||||
let abs = abs_under_root(&sess.root, &rel)?;
|
||||
if let Some(parent) = abs.parent() {
|
||||
std::fs::create_dir_all(parent)
|
||||
.map_err(|e| format!("sandbox_commit mkdir: {e}"))?;
|
||||
}
|
||||
std::fs::write(&abs, &bytes)
|
||||
.map_err(|e| format!("sandbox_commit write {}: {e}", abs.display()))?;
|
||||
applied += 1;
|
||||
}
|
||||
for rel in removes {
|
||||
let abs = abs_under_root(&sess.root, &rel)?;
|
||||
if abs.exists() {
|
||||
if abs.is_dir() {
|
||||
std::fs::remove_dir_all(&abs)
|
||||
.map_err(|e| format!("sandbox_commit remove {}: {e}", abs.display()))?;
|
||||
} else {
|
||||
std::fs::remove_file(&abs)
|
||||
.map_err(|e| format!("sandbox_commit remove {}: {e}", abs.display()))?;
|
||||
}
|
||||
applied += 1;
|
||||
}
|
||||
}
|
||||
sess.upper.clear();
|
||||
sess.whiteout.clear();
|
||||
Ok(json!({ "ok": true, "applied": applied }))
|
||||
})
|
||||
}
|
||||
|
||||
pub fn discard(id: &str) -> Result<serde_json::Value, String> {
|
||||
let mut map = sessions().lock().unwrap_or_else(|e| e.into_inner());
|
||||
if map.remove(id).is_none() {
|
||||
return Err(format!("sandbox: unknown session `{id}`"));
|
||||
}
|
||||
Ok(json!({ "ok": true }))
|
||||
}
|
||||
|
||||
pub fn inspect(id: &str) -> Result<serde_json::Value, String> {
|
||||
with_session(id, |sess| {
|
||||
Ok(json!({
|
||||
"id": id,
|
||||
"root": sess.root.to_string_lossy(),
|
||||
"upper_count": sess.upper.len(),
|
||||
"whiteout_count": sess.whiteout.len(),
|
||||
"caps_default": {
|
||||
"fs_write": true,
|
||||
"exec": false,
|
||||
"net": false,
|
||||
"plugin": false
|
||||
},
|
||||
"notes": [
|
||||
"ext/web listen/DB/WS unavailable in sandbox",
|
||||
"plugin.load denied during sandbox.run",
|
||||
"subtask path/code/lang unavailable in sandbox"
|
||||
]
|
||||
}))
|
||||
})
|
||||
}
|
||||
|
||||
/// Read file bytes through CoW for an active host sandbox session (lib/fs).
|
||||
pub fn cow_read_text(ctx: &HostContext, abs: &Path) -> Result<Option<String>, String> {
|
||||
let Some(id) = ctx.sandbox_session.as_deref() else {
|
||||
return Ok(None);
|
||||
};
|
||||
with_session(id, |sess| {
|
||||
let rel = rel_from_root(&sess.root, abs)?;
|
||||
if sess.whiteout.contains(&rel) {
|
||||
return Err(format!("read_text: not found (sandbox whiteout): {rel}"));
|
||||
}
|
||||
if let Some(bytes) = sess.upper.get(&rel) {
|
||||
let s = String::from_utf8(bytes.clone())
|
||||
.map_err(|e| format!("read_text: not utf-8: {e}"))?;
|
||||
return Ok(Some(s));
|
||||
}
|
||||
Ok(None)
|
||||
})
|
||||
}
|
||||
|
||||
pub fn cow_write_text(ctx: &HostContext, abs: &Path, text: &str) -> Result<bool, String> {
|
||||
let Some(id) = ctx.sandbox_session.as_deref() else {
|
||||
return Ok(false);
|
||||
};
|
||||
with_session_mut(id, |sess| {
|
||||
let rel = rel_from_root(&sess.root, abs)?;
|
||||
sess.whiteout.remove(&rel);
|
||||
sess.upper.insert(rel, text.as_bytes().to_vec());
|
||||
Ok(true)
|
||||
})
|
||||
}
|
||||
|
||||
pub fn cow_remove(ctx: &HostContext, abs: &Path) -> Result<bool, String> {
|
||||
let Some(id) = ctx.sandbox_session.as_deref() else {
|
||||
return Ok(false);
|
||||
};
|
||||
with_session_mut(id, |sess| {
|
||||
let rel = rel_from_root(&sess.root, abs)?;
|
||||
sess.upper.remove(&rel);
|
||||
sess.whiteout.insert(rel);
|
||||
Ok(true)
|
||||
})
|
||||
}
|
||||
|
||||
pub fn cow_exists(ctx: &HostContext, abs: &Path) -> Result<Option<bool>, String> {
|
||||
let Some(id) = ctx.sandbox_session.as_deref() else {
|
||||
return Ok(None);
|
||||
};
|
||||
with_session(id, |sess| {
|
||||
let rel = rel_from_root(&sess.root, abs)?;
|
||||
if sess.whiteout.contains(&rel) {
|
||||
return Ok(Some(false));
|
||||
}
|
||||
if sess.upper.contains_key(&rel) {
|
||||
return Ok(Some(true));
|
||||
}
|
||||
Ok(None)
|
||||
})
|
||||
}
|
||||
|
||||
fn rel_from_root(root: &Path, abs: &Path) -> Result<String, String> {
|
||||
let root_canon = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
|
||||
let abs_canon = abs.canonicalize().unwrap_or_else(|_| abs.to_path_buf());
|
||||
let rel = abs_canon
|
||||
.strip_prefix(&root_canon)
|
||||
.or_else(|_| abs.strip_prefix(root))
|
||||
.map_err(|_| format!("path not under sandbox root: {}", abs.display()))?;
|
||||
normalize_rel(&rel.to_string_lossy().replace('\\', "/"))
|
||||
}
|
||||
|
||||
pub fn run(
|
||||
id: &str,
|
||||
source: Option<&str>,
|
||||
path: Option<&str>,
|
||||
) -> Result<serde_json::Value, String> {
|
||||
let (root, body) = with_session(id, |sess| {
|
||||
let body = if let Some(src) = source.filter(|s| !s.trim().is_empty()) {
|
||||
src.to_string()
|
||||
} else if let Some(p) = path.filter(|s| !s.is_empty()) {
|
||||
let rel = normalize_rel(p)?;
|
||||
if sess.whiteout.contains(&rel) {
|
||||
return Err(format!("sandbox_run: path whiteout: {rel}"));
|
||||
}
|
||||
if let Some(bytes) = sess.upper.get(&rel) {
|
||||
String::from_utf8(bytes.clone())
|
||||
.map_err(|e| format!("sandbox_run: path not utf-8: {e}"))?
|
||||
} else {
|
||||
let abs = abs_under_root(&sess.root, &rel)?;
|
||||
std::fs::read_to_string(&abs)
|
||||
.map_err(|e| format!("sandbox_run read {}: {e}", abs.display()))?
|
||||
}
|
||||
} else {
|
||||
return Err("sandbox_run requires `source` or `path`".into());
|
||||
};
|
||||
Ok((sess.root.clone(), body))
|
||||
})?;
|
||||
|
||||
let opts = crate::RunOptions {
|
||||
allow_fs_write: true,
|
||||
allow_exec: false,
|
||||
allow_net: false,
|
||||
allow_plugin: false,
|
||||
fs_root: Some(root),
|
||||
sandbox_session: Some(id.to_string()),
|
||||
sleep_limit_ms: Some(0),
|
||||
..crate::RunOptions::default()
|
||||
};
|
||||
|
||||
match crate::run_source(&body, &opts) {
|
||||
Ok(cap) => {
|
||||
let value = crate::host::json::value_to_json(&cap.value)
|
||||
.unwrap_or(serde_json::Value::Null);
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"value": value,
|
||||
"stdout": cap.stdout,
|
||||
}))
|
||||
}
|
||||
Err(e) => {
|
||||
let msg = e.to_string();
|
||||
Ok(json!({
|
||||
"ok": false,
|
||||
"error": msg,
|
||||
"value": null,
|
||||
"stdout": "",
|
||||
}))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse host_query JSON args helper used from plugin.rs.
|
||||
pub fn query(name: &str, args: &serde_json::Value, ctx: &HostContext) -> Result<serde_json::Value, String> {
|
||||
let id = || {
|
||||
args.get("id")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| format!("{name}: missing `id`"))
|
||||
};
|
||||
match name {
|
||||
"sandbox_open" => {
|
||||
let root = args.get("root").and_then(|v| v.as_str());
|
||||
open(root, ctx)
|
||||
}
|
||||
"sandbox_write" => {
|
||||
let path = args
|
||||
.get("path")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "sandbox_write: missing `path`".to_string())?;
|
||||
let text = args
|
||||
.get("text")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "sandbox_write: missing `text`".to_string())?;
|
||||
write(id()?, path, text)
|
||||
}
|
||||
"sandbox_read" => {
|
||||
let path = args
|
||||
.get("path")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "sandbox_read: missing `path`".to_string())?;
|
||||
read(id()?, path)
|
||||
}
|
||||
"sandbox_remove" => {
|
||||
let path = args
|
||||
.get("path")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "sandbox_remove: missing `path`".to_string())?;
|
||||
remove(id()?, path)
|
||||
}
|
||||
"sandbox_diff" => diff(id()?),
|
||||
"sandbox_commit" => commit(id()?),
|
||||
"sandbox_discard" => discard(id()?),
|
||||
"sandbox_inspect" => inspect(id()?),
|
||||
"sandbox_run" => {
|
||||
let source = args.get("source").and_then(|v| v.as_str());
|
||||
let path = args.get("path").and_then(|v| v.as_str());
|
||||
run(id()?, source, path)
|
||||
}
|
||||
other => Err(format!("sandbox query unknown `{other}`")),
|
||||
}
|
||||
}
|
||||
|
||||
#[allow(dead_code)]
|
||||
pub fn unavailable(feature: &str) -> String {
|
||||
format!("{feature} unavailable in sandbox")
|
||||
}
|
||||
|
||||
/// Used by fs layer when session is active — map Value path through resolve then CoW.
|
||||
pub fn try_read_value(ctx: &HostContext, path: &Value) -> Result<Option<Value>, String> {
|
||||
let rel = match path {
|
||||
Value::Text(s) => s.as_str(),
|
||||
_ => return Ok(None),
|
||||
};
|
||||
let abs = ctx.resolve_path(rel)?;
|
||||
match cow_read_text(ctx, &abs)? {
|
||||
Some(s) => Ok(Some(Value::Text(s))),
|
||||
None => Ok(None),
|
||||
}
|
||||
}
|
||||
@@ -150,6 +150,9 @@ pub fn exec(
|
||||
{
|
||||
use std::process::Stdio;
|
||||
if !ctx.allow_exec() {
|
||||
if ctx.sandbox_session.is_some() {
|
||||
return Err("exec unavailable in sandbox".into());
|
||||
}
|
||||
return Err("exec denied by host policy".into());
|
||||
}
|
||||
let cmd = as_text(cmd, "cmd")?;
|
||||
|
||||
+244
-26
@@ -1,7 +1,11 @@
|
||||
//! Jupyter-style output persistence in `.mq.md` (`<!-- marqdo-out … -->`).
|
||||
//! Jupyter-style output persistence in `.mq.md`.
|
||||
//!
|
||||
//! Optional **named slots**: `<!-- marqdo-out ok -->` / `<!-- marqdo-out error -->`
|
||||
//! so success and failure results do not overwrite each other.
|
||||
//! Two surface forms (both scanned / replaced):
|
||||
//! - HTML comment: `<!-- marqdo-out … -->` (text / structured output)
|
||||
//! - Markdown image: `` (image refs; validated)
|
||||
//!
|
||||
//! Optional **named slots**: `marqdo-out ok` / `marqdo-out error` so success and
|
||||
//! failure results do not overwrite each other.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::sync::Mutex;
|
||||
@@ -14,14 +18,30 @@ const MAGIC: &str = "marqdo-out";
|
||||
/// Serialize all writeback file mutations (sync + subtask writers).
|
||||
static WRITEBACK_LOCK: Mutex<()> = Mutex::new(());
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
enum BlockKind {
|
||||
Comment,
|
||||
Image,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
struct BlockSpan {
|
||||
start: usize,
|
||||
end: usize,
|
||||
/// Comment body text, or image URL/path for [`BlockKind::Image`].
|
||||
body: String,
|
||||
start_line: u32,
|
||||
/// Named slot from header (`marqdo-out ok` → `ok`); `None` = legacy unkeyed.
|
||||
key: Option<String>,
|
||||
kind: BlockKind,
|
||||
}
|
||||
|
||||
/// View-facing writeback piece under a statement line.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct WritebackEntry {
|
||||
pub key: Option<String>,
|
||||
pub body: String,
|
||||
pub is_image: bool,
|
||||
}
|
||||
|
||||
fn display_value(v: &Value) -> String {
|
||||
@@ -119,13 +139,71 @@ fn line_number_at(source: &str, byte: usize) -> u32 {
|
||||
+ 1
|
||||
}
|
||||
|
||||
fn format_block(body: &str, key: Option<&str>) -> String {
|
||||
fn format_comment_block(body: &str, key: Option<&str>) -> String {
|
||||
match key {
|
||||
Some(k) => format!("<!-- {MAGIC} {k}\n{body}\n-->"),
|
||||
None => format!("<!-- {MAGIC}\n{body}\n-->"),
|
||||
}
|
||||
}
|
||||
|
||||
fn format_image_block(url: &str, key: Option<&str>) -> String {
|
||||
match key {
|
||||
Some(k) => format!(""),
|
||||
None => format!(""),
|
||||
}
|
||||
}
|
||||
|
||||
fn format_block_for_value(body: &str, key: Option<&str>) -> Result<String, String> {
|
||||
if looks_like_image_ref(body) {
|
||||
validate_image_ref(body)?;
|
||||
Ok(format_image_block(body.trim(), key))
|
||||
} else {
|
||||
Ok(format_comment_block(body, key))
|
||||
}
|
||||
}
|
||||
|
||||
/// True when `s` looks like a path/URL that should persist as ``.
|
||||
pub fn looks_like_image_ref(s: &str) -> bool {
|
||||
validate_image_ref(s).is_ok()
|
||||
}
|
||||
|
||||
/// Accept local/relative paths and http(s) URLs with a known image extension,
|
||||
/// or `data:image/…` URIs.
|
||||
pub fn validate_image_ref(s: &str) -> Result<(), String> {
|
||||
let t = s.trim().trim_matches('"').trim_matches('\'');
|
||||
if t.is_empty() {
|
||||
return Err("writeback image: empty path".into());
|
||||
}
|
||||
if t.starts_with("data:image/") {
|
||||
return Ok(());
|
||||
}
|
||||
// Strip query/fragment for extension check.
|
||||
let no_query = t.split_once('?').map(|(p, _)| p).unwrap_or(t);
|
||||
let path_part = no_query.split_once('#').map(|(p, _)| p).unwrap_or(no_query);
|
||||
let file = path_part.rsplit('/').next().unwrap_or(path_part);
|
||||
// Require a real extension (reject bare names like `svg` / `png`).
|
||||
let Some((stem, ext)) = file.rsplit_once('.') else {
|
||||
return Err(format!(
|
||||
"writeback image: path needs an image extension (got `{t}`)"
|
||||
));
|
||||
};
|
||||
if stem.is_empty() {
|
||||
return Err(format!("writeback image: invalid file name `{t}`"));
|
||||
}
|
||||
let ext = ext.to_ascii_lowercase();
|
||||
const OK: &[&str] = &[
|
||||
"png", "jpg", "jpeg", "gif", "webp", "svg", "bmp", "ico", "avif", "tif", "tiff",
|
||||
];
|
||||
if OK.contains(&ext.as_str()) {
|
||||
Ok(())
|
||||
} else {
|
||||
Err(format!(
|
||||
"writeback image: not an image path/URL (got `{t}`; need .{})",
|
||||
OK.join("/.")
|
||||
))
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_header_key(header: &str) -> Option<String> {
|
||||
let mut parts = header.split_whitespace();
|
||||
let first = parts.next()?;
|
||||
@@ -160,11 +238,43 @@ fn parse_one_block(block: &str, start_byte: usize, source: &str) -> Option<Block
|
||||
body,
|
||||
start_line: line_number_at(source, start_byte),
|
||||
key,
|
||||
kind: BlockKind::Comment,
|
||||
})
|
||||
}
|
||||
|
||||
/// `` on a single source line.
|
||||
fn parse_image_line(line: &str, line_start: usize, source: &str) -> Option<BlockSpan> {
|
||||
let trimmed = line.trim();
|
||||
let rest = trimmed.strip_prefix("?;
|
||||
let alt = rest[..alt_end].trim();
|
||||
if !alt.split_whitespace().any(|t| t == MAGIC) {
|
||||
return None;
|
||||
}
|
||||
let key = parse_header_key(alt);
|
||||
let after_alt = &rest[alt_end + 2..];
|
||||
let url_end = after_alt.rfind(')')?;
|
||||
let url = after_alt[..url_end].trim();
|
||||
if url.is_empty() || validate_image_ref(url).is_err() {
|
||||
return None;
|
||||
}
|
||||
// Span covers the trimmed image on its line (indent kept outside).
|
||||
let trim_start = line.find(trimmed).unwrap_or(0);
|
||||
let start = line_start + trim_start;
|
||||
let end = start + trimmed.len();
|
||||
Some(BlockSpan {
|
||||
start,
|
||||
end,
|
||||
body: url.to_string(),
|
||||
start_line: line_number_at(source, start),
|
||||
key,
|
||||
kind: BlockKind::Image,
|
||||
})
|
||||
}
|
||||
|
||||
fn scan_blocks(source: &str) -> Vec<BlockSpan> {
|
||||
let mut out = Vec::new();
|
||||
// HTML comment blocks
|
||||
let mut i = 0usize;
|
||||
while i < source.len() {
|
||||
let rest = &source[i..];
|
||||
@@ -186,6 +296,16 @@ fn scan_blocks(source: &str) -> Vec<BlockSpan> {
|
||||
}
|
||||
i = abs + end_rel + 3;
|
||||
}
|
||||
// Image writebacks (line-oriented)
|
||||
let mut line_start = 0usize;
|
||||
for line in source.split_inclusive('\n') {
|
||||
let content = line.trim_end_matches(['\r', '\n']);
|
||||
if let Some(b) = parse_image_line(content, line_start, source) {
|
||||
out.push(b);
|
||||
}
|
||||
line_start += line.len();
|
||||
}
|
||||
out.sort_by_key(|b| b.start);
|
||||
out
|
||||
}
|
||||
|
||||
@@ -323,7 +443,7 @@ fn find_keyed_in_cluster(source: &str, after_line: u32, key: &str) -> Option<Blo
|
||||
/// Replace keyed block under `anchor` line, or insert into that cluster (not EOF).
|
||||
fn replace_or_insert_keyed_at(source: &str, anchor: u32, key: &str, body: &str) -> Result<String, String> {
|
||||
let key = normalize_slot_key(key);
|
||||
let block = format_block(body, Some(&key));
|
||||
let block = format_block_for_value(body, Some(&key))?;
|
||||
if let Some(existing) = find_keyed_in_cluster(source, anchor, &key) {
|
||||
return Ok(splice_block(source, existing.start, existing.end, &block));
|
||||
}
|
||||
@@ -438,13 +558,13 @@ pub fn record(
|
||||
let stripped = find_eof_block(&source)
|
||||
.map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end)))
|
||||
.unwrap_or_else(|| source.clone());
|
||||
append_eof(&stripped, &format_block(&body, None))
|
||||
append_eof(&stripped, &format_block_for_value(&body, None)?)
|
||||
} else {
|
||||
let line = anchor.ok_or_else(|| "writeback: missing anchor line".to_string())?;
|
||||
let stripped = find_adjacent_block(&source, line)
|
||||
.map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end)))
|
||||
.unwrap_or_else(|| source.clone());
|
||||
insert_after_line(&stripped, line, &format_block(&body, None))?
|
||||
insert_after_line(&stripped, line, &format_block_for_value(&body, None)?)?
|
||||
};
|
||||
persist(ctx, &next)?;
|
||||
Ok(Value::Text(body.clone()))
|
||||
@@ -549,10 +669,15 @@ fn slots_from_source(source: &str) -> Value {
|
||||
.map(|b| {
|
||||
let anchor = anchor_line_above(source, b.start_line);
|
||||
let at_eof = b.key.is_none() && is_eof_block(source, &b);
|
||||
let kind = match b.kind {
|
||||
BlockKind::Comment => "comment",
|
||||
BlockKind::Image => "image",
|
||||
};
|
||||
let mut entries = vec![
|
||||
("line".into(), Value::Int(anchor as i64)),
|
||||
("body".into(), Value::Text(b.body)),
|
||||
("at_end".into(), Value::Bool(at_eof)),
|
||||
("kind".into(), Value::Text(kind.into())),
|
||||
];
|
||||
if let Some(k) = b.key {
|
||||
entries.push(("key".into(), Value::Text(k)));
|
||||
@@ -584,29 +709,49 @@ pub fn ensure_slot(
|
||||
})
|
||||
}
|
||||
|
||||
/// Map statement line → body for adjacent blocks (keyed slots included under their anchor).
|
||||
pub fn writeback_map(source: &str) -> HashMap<u32, String> {
|
||||
let mut map = HashMap::new();
|
||||
/// Structured writebacks keyed by the statement line above the block cluster.
|
||||
pub fn writeback_entries(source: &str) -> HashMap<u32, Vec<WritebackEntry>> {
|
||||
let mut map: HashMap<u32, Vec<WritebackEntry>> = HashMap::new();
|
||||
for b in scan_blocks(source) {
|
||||
let anchor = anchor_line_above(source, b.start_line);
|
||||
let piece = match &b.key {
|
||||
Some(k) => format!("[{k}]\n{}", b.body),
|
||||
None => b.body.clone(),
|
||||
};
|
||||
if b.key.is_none() && is_eof_block(source, &b) {
|
||||
map.insert(0, piece);
|
||||
let anchor = if b.key.is_none() && is_eof_block(source, &b) {
|
||||
0
|
||||
} else {
|
||||
map.entry(anchor)
|
||||
.and_modify(|e| {
|
||||
e.push_str("\n\n");
|
||||
e.push_str(&piece);
|
||||
})
|
||||
.or_insert(piece);
|
||||
}
|
||||
anchor_line_above(source, b.start_line)
|
||||
};
|
||||
let entry = WritebackEntry {
|
||||
key: b.key.clone(),
|
||||
body: b.body.clone(),
|
||||
is_image: b.kind == BlockKind::Image,
|
||||
};
|
||||
map.entry(anchor).or_default().push(entry);
|
||||
}
|
||||
map
|
||||
}
|
||||
|
||||
/// Map statement line → combined body for adjacent blocks (keyed slots included).
|
||||
/// Image slots are encoded as a markdown image line so view/static can render `<img>`.
|
||||
pub fn writeback_map(source: &str) -> HashMap<u32, String> {
|
||||
let mut map = HashMap::new();
|
||||
for (anchor, entries) in writeback_entries(source) {
|
||||
let mut pieces = Vec::new();
|
||||
for e in entries {
|
||||
let content = if e.is_image {
|
||||
format!("", e.body)
|
||||
} else {
|
||||
e.body
|
||||
};
|
||||
let piece = match &e.key {
|
||||
Some(k) => format!("[{k}]\n{content}"),
|
||||
None => content,
|
||||
};
|
||||
pieces.push(piece);
|
||||
}
|
||||
map.insert(anchor, pieces.join("\n\n"));
|
||||
}
|
||||
map
|
||||
}
|
||||
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -614,7 +759,7 @@ mod tests {
|
||||
#[test]
|
||||
fn parse_and_insert_adjacent() {
|
||||
let src = "# main\n\n**x = 1**\n";
|
||||
let block = format_block("1", None);
|
||||
let block = format_comment_block("1", None);
|
||||
let next = insert_after_line(src, 3, &block).unwrap();
|
||||
assert!(next.contains("marqdo-out"));
|
||||
assert!(!next.contains("@line"));
|
||||
@@ -625,6 +770,79 @@ mod tests {
|
||||
assert!(!replaced.contains("marqdo-out"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn image_writeback_scan_and_format() {
|
||||
assert!(looks_like_image_ref("plot.svg"));
|
||||
assert!(looks_like_image_ref("https://ex.com/a.PNG"));
|
||||
assert!(looks_like_image_ref("data:image/png;base64,xx"));
|
||||
assert!(looks_like_image_ref("plots/a.svg?v=1"));
|
||||
assert!(!looks_like_image_ref("readme.txt"));
|
||||
assert!(!looks_like_image_ref("42"));
|
||||
assert!(!looks_like_image_ref("svg")); // bare name, not an extension
|
||||
assert!(!looks_like_image_ref(".svg"));
|
||||
let block = format_image_block("out/plot.svg", Some("ok"));
|
||||
assert_eq!(block, "");
|
||||
let src = "# main\n\n**x = 1**\n\n\n> print text=tail\n";
|
||||
let blocks = scan_blocks(src);
|
||||
assert_eq!(blocks.len(), 1);
|
||||
assert_eq!(blocks[0].kind, BlockKind::Image);
|
||||
assert_eq!(blocks[0].body, "out/plot.svg");
|
||||
assert_eq!(blocks[0].key.as_deref(), Some("ok"));
|
||||
let map = writeback_map(src);
|
||||
assert_eq!(
|
||||
map.get(&3).map(|s| s.as_str()),
|
||||
Some("[ok]\n")
|
||||
);
|
||||
// Invalid image URL in marqdo-out alt → not a writeback slot
|
||||
let bad = "# main\n\n\n";
|
||||
assert!(scan_blocks(bad).is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unkeyed_comment_and_image_replace_each_other() {
|
||||
let src = "# main\n\n**x = 1**\n<!-- marqdo-out\nold\n-->\n\n> print text=tail\n";
|
||||
let line = 3u32;
|
||||
let to_image = {
|
||||
let stripped = find_adjacent_block(src, line)
|
||||
.map(|b| strip_span(src, b.start, span_end_including_nl(src, b.end)))
|
||||
.unwrap_or_else(|| src.to_string());
|
||||
insert_after_line(
|
||||
&stripped,
|
||||
line,
|
||||
&format_block_for_value("fig.svg", None).unwrap(),
|
||||
)
|
||||
.unwrap()
|
||||
};
|
||||
assert!(to_image.contains(""));
|
||||
assert!(!to_image.contains("<!-- marqdo-out"));
|
||||
let blocks = scan_blocks(&to_image);
|
||||
assert_eq!(blocks.len(), 1);
|
||||
assert_eq!(blocks[0].kind, BlockKind::Image);
|
||||
|
||||
let to_text = {
|
||||
let stripped = find_adjacent_block(&to_image, line)
|
||||
.map(|b| strip_span(&to_image, b.start, span_end_including_nl(&to_image, b.end)))
|
||||
.unwrap_or_else(|| to_image.clone());
|
||||
insert_after_line(
|
||||
&stripped,
|
||||
line,
|
||||
&format_block_for_value("hello", None).unwrap(),
|
||||
)
|
||||
.unwrap()
|
||||
};
|
||||
assert!(to_text.contains("<!-- marqdo-out\nhello\n-->"));
|
||||
assert!(!to_text.contains("![marqdo-out]"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn record_format_picks_image_for_svg_path() {
|
||||
let s = format_block_for_value("figs/a.svg", None).unwrap();
|
||||
assert_eq!(s, "");
|
||||
let t = format_block_for_value("hello", None).unwrap();
|
||||
assert!(t.contains("<!-- marqdo-out"));
|
||||
assert!(format_block_for_value("notes.txt", None).unwrap().contains("<!--"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn writeback_map_uses_line_above() {
|
||||
let src = "# main\n\n**x = 1**\n<!-- marqdo-out\n42\n-->\n\n> print text=tail\n";
|
||||
@@ -671,7 +889,7 @@ mod tests {
|
||||
let stripped = find_adjacent_block(s, line)
|
||||
.map(|b| strip_span(s, b.start, span_end_including_nl(s, b.end)))
|
||||
.unwrap_or_else(|| s.to_string());
|
||||
insert_after_line(&stripped, line, &format_block(body, None)).unwrap()
|
||||
insert_after_line(&stripped, line, &format_comment_block(body, None)).unwrap()
|
||||
};
|
||||
let once = strip_insert(src, "a");
|
||||
let twice = strip_insert(&once, "b");
|
||||
|
||||
+357
-3
@@ -17,6 +17,9 @@ use crate::debug::{emit_trace, DebugController};
|
||||
use crate::diagnostics::{bail_at, Span};
|
||||
use crate::host::{call_host, HostContext, HostFn};
|
||||
use crate::input_feed::InputFeed;
|
||||
use crate::capture::{
|
||||
BranchHit, CallFrame, LoopFrame, LoopHit, LoopIter, StmtEvent, StmtEventKind, ViewTrace,
|
||||
};
|
||||
use crate::value::Value;
|
||||
use std::sync::Arc;
|
||||
|
||||
@@ -27,6 +30,14 @@ pub struct Interpreter {
|
||||
pub captured_stdout: String,
|
||||
/// Bindings in the entry (`# main` / sole object) env after it finishes.
|
||||
pub entry_bindings: HashMap<String, Value>,
|
||||
/// Silent branch/loop hits for `marqdo view` annotations.
|
||||
pub view_trace: ViewTrace,
|
||||
next_call_id: u32,
|
||||
call_stack: Vec<u32>,
|
||||
fn_ordinals: HashMap<String, u32>,
|
||||
next_loop_id: u32,
|
||||
/// Active loops: `(loop_id, iter_index_0based)`.
|
||||
loop_stack: Vec<(u32, u32)>,
|
||||
current_span: Span,
|
||||
input: InputFeed,
|
||||
host: HostContext,
|
||||
@@ -82,6 +93,12 @@ impl Interpreter {
|
||||
capture: false,
|
||||
captured_stdout: String::new(),
|
||||
entry_bindings: HashMap::new(),
|
||||
view_trace: ViewTrace::default(),
|
||||
next_call_id: 1,
|
||||
call_stack: Vec::new(),
|
||||
fn_ordinals: HashMap::new(),
|
||||
next_loop_id: 1,
|
||||
loop_stack: Vec::new(),
|
||||
current_span: Span::new(1, 1),
|
||||
input: InputFeed::new(false, Vec::new()),
|
||||
host: HostContext::for_run(path, Default::default(), Vec::new()),
|
||||
@@ -97,6 +114,12 @@ impl Interpreter {
|
||||
capture: true,
|
||||
captured_stdout: String::new(),
|
||||
entry_bindings: HashMap::new(),
|
||||
view_trace: ViewTrace::default(),
|
||||
next_call_id: 1,
|
||||
call_stack: Vec::new(),
|
||||
fn_ordinals: HashMap::new(),
|
||||
next_loop_id: 1,
|
||||
loop_stack: Vec::new(),
|
||||
current_span: Span::new(1, 1),
|
||||
input: InputFeed::new(true, Vec::new()),
|
||||
host: HostContext::for_capture(path, Default::default()),
|
||||
@@ -150,6 +173,172 @@ impl Interpreter {
|
||||
}
|
||||
}
|
||||
|
||||
fn current_call_id(&self) -> u32 {
|
||||
self.call_stack.last().copied().unwrap_or(0)
|
||||
}
|
||||
|
||||
fn loop_ctx(&self) -> (Option<u32>, Option<u32>) {
|
||||
self.loop_stack
|
||||
.last()
|
||||
.map(|(id, iter)| (Some(*id), Some(*iter)))
|
||||
.unwrap_or((None, None))
|
||||
}
|
||||
|
||||
fn push_view_call(&mut self, fun: &Function, env: &Env) {
|
||||
if !self.capture {
|
||||
return;
|
||||
}
|
||||
let call_id = self.next_call_id;
|
||||
self.next_call_id += 1;
|
||||
let ordinal = {
|
||||
let e = self.fn_ordinals.entry(fun.name.clone()).or_insert(0);
|
||||
*e += 1;
|
||||
*e
|
||||
};
|
||||
let args_brief = fun
|
||||
.params
|
||||
.iter()
|
||||
.filter_map(|p| {
|
||||
env.get(&p.name)
|
||||
.map(|v| format!("{}={}", p.name, brief_trace_val(v)))
|
||||
})
|
||||
.collect::<Vec<_>>()
|
||||
.join(", ");
|
||||
self.view_trace.calls.push(CallFrame {
|
||||
call_id,
|
||||
fn_name: fun.name.clone(),
|
||||
fn_line: fun.span.line,
|
||||
ordinal,
|
||||
args_brief,
|
||||
});
|
||||
self.call_stack.push(call_id);
|
||||
}
|
||||
|
||||
fn pop_view_call(&mut self) {
|
||||
if self.capture {
|
||||
self.call_stack.pop();
|
||||
}
|
||||
}
|
||||
|
||||
fn begin_view_loop(
|
||||
&mut self,
|
||||
line: u32,
|
||||
item: Option<&str>,
|
||||
collection: Option<&str>,
|
||||
) -> u32 {
|
||||
let loop_id = self.next_loop_id;
|
||||
self.next_loop_id += 1;
|
||||
self.view_trace.loop_frames.push(LoopFrame {
|
||||
loop_id,
|
||||
line,
|
||||
item_name: item.map(|s| s.to_string()),
|
||||
collection: collection.map(|s| s.to_string()),
|
||||
iterations: Vec::new(),
|
||||
});
|
||||
self.loop_stack.push((loop_id, 0));
|
||||
loop_id
|
||||
}
|
||||
|
||||
fn enter_loop_iter(&mut self, loop_id: u32, index: u32, item_value: &str) {
|
||||
if let Some((_, cur)) = self.loop_stack.iter_mut().rev().find(|(id, _)| *id == loop_id)
|
||||
{
|
||||
*cur = index;
|
||||
}
|
||||
let call_id = self.current_call_id();
|
||||
if let Some(fr) = self
|
||||
.view_trace
|
||||
.loop_frames
|
||||
.iter_mut()
|
||||
.find(|f| f.loop_id == loop_id)
|
||||
{
|
||||
fr.iterations.push(LoopIter {
|
||||
index,
|
||||
item_value: item_value.to_string(),
|
||||
call_id,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
fn end_view_loop(&mut self, loop_id: u32) {
|
||||
if self
|
||||
.loop_stack
|
||||
.last()
|
||||
.map(|(id, _)| *id == loop_id)
|
||||
.unwrap_or(false)
|
||||
{
|
||||
self.loop_stack.pop();
|
||||
}
|
||||
}
|
||||
|
||||
fn record_stmt_event(&mut self, mut ev: StmtEvent) {
|
||||
if self.capture {
|
||||
if ev.loop_id.is_none() || ev.iter.is_none() {
|
||||
let (lid, iter) = self.loop_ctx();
|
||||
if ev.loop_id.is_none() {
|
||||
ev.loop_id = lid;
|
||||
}
|
||||
if ev.iter.is_none() {
|
||||
ev.iter = iter;
|
||||
}
|
||||
}
|
||||
self.view_trace.events.push(ev);
|
||||
}
|
||||
}
|
||||
|
||||
fn record_branch_hit(&mut self, line: u32, arm_index: usize) {
|
||||
let call_id = self.current_call_id();
|
||||
if let Some(existing) = self.view_trace.branches.iter_mut().find(|h| {
|
||||
h.line == line && h.arm_index == arm_index && h.call_id == call_id
|
||||
}) {
|
||||
existing.count += 1;
|
||||
} else {
|
||||
self.view_trace.branches.push(BranchHit {
|
||||
line,
|
||||
arm_index,
|
||||
count: 1,
|
||||
call_id,
|
||||
});
|
||||
}
|
||||
let (loop_id, iter) = self.loop_ctx();
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line,
|
||||
kind: StmtEventKind::Branch,
|
||||
name: None,
|
||||
value_after: Some(format!("arm {}", arm_index + 1)),
|
||||
arm_index: Some(arm_index),
|
||||
iter,
|
||||
call_id,
|
||||
loop_id,
|
||||
});
|
||||
}
|
||||
|
||||
fn record_loop_hit(&mut self, line: u32, iterations: u32, last_item: Option<String>) {
|
||||
if let Some(existing) = self.view_trace.loops.iter_mut().find(|h| h.line == line) {
|
||||
existing.iterations = iterations;
|
||||
if last_item.is_some() {
|
||||
existing.last_item = last_item.clone();
|
||||
}
|
||||
} else {
|
||||
self.view_trace.loops.push(LoopHit {
|
||||
line,
|
||||
iterations,
|
||||
last_item: last_item.clone(),
|
||||
});
|
||||
}
|
||||
let (loop_id, _) = self.loop_ctx();
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line,
|
||||
kind: StmtEventKind::Loop,
|
||||
name: None,
|
||||
value_after: Some(format!("{iterations} iters")),
|
||||
arm_index: None,
|
||||
// Summary event: total count (not 0-based index).
|
||||
iter: Some(iterations),
|
||||
call_id: self.current_call_id(),
|
||||
loop_id,
|
||||
});
|
||||
}
|
||||
|
||||
/// Run a function by name anywhere in the module (for `lib/subtask` workers).
|
||||
pub fn invoke_function(
|
||||
&mut self,
|
||||
@@ -337,6 +526,7 @@ impl Interpreter {
|
||||
}
|
||||
|
||||
let ret = Value::None;
|
||||
self.push_view_call(fun, &env);
|
||||
self.host.push_call_frame(&fun.name);
|
||||
let body_result = (|| -> Result<Value> {
|
||||
for stmt in &fun.body {
|
||||
@@ -347,6 +537,7 @@ impl Interpreter {
|
||||
Ok(ret)
|
||||
})();
|
||||
self.host.pop_call_frame();
|
||||
self.pop_view_call();
|
||||
let ret = body_result?;
|
||||
if capture_entry_env {
|
||||
self.entry_bindings = env.vars_clone();
|
||||
@@ -402,6 +593,18 @@ impl Interpreter {
|
||||
],
|
||||
);
|
||||
}
|
||||
if self.capture {
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::Assign,
|
||||
name: Some(name.clone()),
|
||||
value_after: Some(v.as_display()),
|
||||
arm_index: None,
|
||||
iter: None,
|
||||
call_id: self.current_call_id(),
|
||||
loop_id: None,
|
||||
});
|
||||
}
|
||||
env.set(name.clone(), v);
|
||||
Ok(None)
|
||||
}
|
||||
@@ -425,6 +628,18 @@ impl Interpreter {
|
||||
&[("kind", "return"), ("value", display.as_str())],
|
||||
);
|
||||
}
|
||||
if self.capture {
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::Return,
|
||||
name: None,
|
||||
value_after: Some(v.as_display()),
|
||||
arm_index: None,
|
||||
iter: None,
|
||||
call_id: self.current_call_id(),
|
||||
loop_id: None,
|
||||
});
|
||||
}
|
||||
Ok(Some(v))
|
||||
}
|
||||
Stmt::Call { call, span } => {
|
||||
@@ -437,7 +652,26 @@ impl Interpreter {
|
||||
&[("kind", "call"), ("callee", call.callee.as_str())],
|
||||
);
|
||||
}
|
||||
let _ = self.eval_call(module, fun, env, call)?;
|
||||
let stdout_before = self.captured_stdout.len();
|
||||
let v = self.eval_call(module, fun, env, call)?;
|
||||
if self.capture {
|
||||
let (loop_id, iter) = self.loop_ctx();
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::Call,
|
||||
name: Some(call.callee.clone()),
|
||||
value_after: Some(call_event_brief(
|
||||
&v,
|
||||
&self.captured_stdout,
|
||||
stdout_before,
|
||||
&call.callee,
|
||||
)),
|
||||
arm_index: None,
|
||||
iter,
|
||||
call_id: self.current_call_id(),
|
||||
loop_id,
|
||||
});
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
Stmt::Expr { value, span } => {
|
||||
@@ -450,7 +684,30 @@ impl Interpreter {
|
||||
&[("kind", "expr")],
|
||||
);
|
||||
}
|
||||
let _ = self.eval_expr(module, fun, env, value)?;
|
||||
let stdout_before = self.captured_stdout.len();
|
||||
let v = self.eval_expr(module, fun, env, value)?;
|
||||
if self.capture {
|
||||
let (loop_id, iter) = self.loop_ctx();
|
||||
let name = match value {
|
||||
Expr::Call(c) => Some(c.callee.clone()),
|
||||
_ => None,
|
||||
};
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::Call,
|
||||
name: name.clone(),
|
||||
value_after: Some(call_event_brief(
|
||||
&v,
|
||||
&self.captured_stdout,
|
||||
stdout_before,
|
||||
name.as_deref().unwrap_or("expr"),
|
||||
)),
|
||||
arm_index: None,
|
||||
iter,
|
||||
call_id: self.current_call_id(),
|
||||
loop_id,
|
||||
});
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
Stmt::Branch { arms, span } => {
|
||||
@@ -463,12 +720,15 @@ impl Interpreter {
|
||||
&[("kind", "branch")],
|
||||
);
|
||||
}
|
||||
for arm in arms {
|
||||
for (arm_index, arm) in arms.iter().enumerate() {
|
||||
let take = match &arm.condition {
|
||||
None => true,
|
||||
Some(cond) => self.eval_expr(module, fun, env, cond)?.truthy(),
|
||||
};
|
||||
if take {
|
||||
if self.capture {
|
||||
self.record_branch_hit(span.line, arm_index);
|
||||
}
|
||||
for s in &arm.body {
|
||||
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
|
||||
return Ok(Some(v));
|
||||
@@ -493,18 +753,38 @@ impl Interpreter {
|
||||
&[("kind", "while")],
|
||||
);
|
||||
}
|
||||
let loop_id = if self.capture {
|
||||
Some(self.begin_view_loop(span.line, None, None))
|
||||
} else {
|
||||
None
|
||||
};
|
||||
let mut guard = 0u32;
|
||||
while self.eval_expr(module, fun, env, condition)?.truthy() {
|
||||
guard += 1;
|
||||
if guard > 1_000_000 {
|
||||
return Err(self.err("while loop exceeded iteration limit"));
|
||||
}
|
||||
if let Some(lid) = loop_id {
|
||||
self.enter_loop_iter(lid, guard - 1, &format!("iter {guard}"));
|
||||
}
|
||||
for s in body {
|
||||
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
|
||||
if self.capture {
|
||||
if let Some(lid) = loop_id {
|
||||
self.end_view_loop(lid);
|
||||
}
|
||||
self.record_loop_hit(span.line, guard, None);
|
||||
}
|
||||
return Ok(Some(v));
|
||||
}
|
||||
}
|
||||
}
|
||||
if self.capture {
|
||||
if let Some(lid) = loop_id {
|
||||
self.end_view_loop(lid);
|
||||
}
|
||||
self.record_loop_hit(span.line, guard, None);
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
Stmt::ForEach {
|
||||
@@ -534,14 +814,56 @@ impl Interpreter {
|
||||
Ok(_) => unreachable!(),
|
||||
Err(m) => return Err(self.err(m)),
|
||||
};
|
||||
let loop_id = if self.capture {
|
||||
Some(self.begin_view_loop(
|
||||
span.line,
|
||||
Some(item.as_str()),
|
||||
Some(collection.as_str()),
|
||||
))
|
||||
} else {
|
||||
None
|
||||
};
|
||||
let mut iterations = 0u32;
|
||||
let mut last_item: Option<String> = None;
|
||||
for val in items {
|
||||
let index = iterations;
|
||||
iterations += 1;
|
||||
let display = val.as_display();
|
||||
last_item = Some(display.clone());
|
||||
if let Some(lid) = loop_id {
|
||||
self.enter_loop_iter(lid, index, &display);
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::BindRef,
|
||||
name: Some(item.clone()),
|
||||
value_after: Some(format!(
|
||||
"{collection}[{index}]={display}"
|
||||
)),
|
||||
arm_index: None,
|
||||
iter: Some(index),
|
||||
call_id: self.current_call_id(),
|
||||
loop_id: Some(lid),
|
||||
});
|
||||
}
|
||||
env.set(item.clone(), val);
|
||||
for s in body {
|
||||
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
|
||||
if self.capture {
|
||||
if let Some(lid) = loop_id {
|
||||
self.end_view_loop(lid);
|
||||
}
|
||||
self.record_loop_hit(span.line, iterations, last_item.clone());
|
||||
}
|
||||
return Ok(Some(v));
|
||||
}
|
||||
}
|
||||
}
|
||||
if self.capture {
|
||||
if let Some(lid) = loop_id {
|
||||
self.end_view_loop(lid);
|
||||
}
|
||||
self.record_loop_hit(span.line, iterations, last_item);
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
}
|
||||
@@ -1399,6 +1721,38 @@ fn cmp_ord(l: &Value, r: &Value, f: impl Fn(std::cmp::Ordering) -> bool) -> Resu
|
||||
}
|
||||
}
|
||||
|
||||
fn brief_trace_val(v: &Value) -> String {
|
||||
let s = v.as_display();
|
||||
if s.chars().count() > 24 {
|
||||
format!("{}…", s.chars().take(24).collect::<String>())
|
||||
} else {
|
||||
s
|
||||
}
|
||||
}
|
||||
|
||||
/// Prefer real result; else last stdout line emitted by the call; else callee name.
|
||||
fn call_event_brief(v: &Value, stdout: &str, stdout_before: usize, callee: &str) -> String {
|
||||
if !matches!(v, Value::None) {
|
||||
return brief_trace_val(v);
|
||||
}
|
||||
if stdout.len() > stdout_before {
|
||||
let delta = &stdout[stdout_before..];
|
||||
let line = delta
|
||||
.trim_end()
|
||||
.lines()
|
||||
.last()
|
||||
.unwrap_or(delta.trim_end());
|
||||
if !line.is_empty() {
|
||||
return if line.chars().count() > 48 {
|
||||
format!("{}…", line.chars().take(48).collect::<String>())
|
||||
} else {
|
||||
line.to_string()
|
||||
};
|
||||
}
|
||||
}
|
||||
callee.to_string()
|
||||
}
|
||||
|
||||
fn stmt_span(stmt: &Stmt) -> Span {
|
||||
match stmt {
|
||||
Stmt::Assign { span, .. }
|
||||
|
||||
+80
-1
@@ -279,7 +279,52 @@ fn breaks_comment_paragraph(trimmed: &str) -> bool {
|
||||
if trimmed.starts_with('#') || trimmed.starts_with('>') {
|
||||
return true;
|
||||
}
|
||||
is_marqdo_star_line(trimmed)
|
||||
if is_marqdo_star_line(trimmed) {
|
||||
return true;
|
||||
}
|
||||
// Branch arms / loops / params must not be swallowed after prose in an arm body.
|
||||
if looks_like_ordered_list_item(trimmed) {
|
||||
return true;
|
||||
}
|
||||
if trimmed.starts_with("- ") || trimmed.starts_with("-\t") || trimmed == "-" {
|
||||
return true;
|
||||
}
|
||||
if trimmed.starts_with('+') {
|
||||
return true;
|
||||
}
|
||||
if is_image_writeback_line(trimmed) {
|
||||
return true;
|
||||
}
|
||||
false
|
||||
}
|
||||
|
||||
/// `` — image writeback surface (see stdlib-writeback).
|
||||
pub fn is_image_writeback_line(trimmed: &str) -> bool {
|
||||
let t = trimmed.trim();
|
||||
let Some(rest) = t.strip_prefix(" else {
|
||||
return false;
|
||||
};
|
||||
let alt = rest[..alt_end].trim();
|
||||
alt.split_whitespace().any(|tok| tok == "marqdo-out")
|
||||
}
|
||||
|
||||
fn looks_like_ordered_list_item(trimmed: &str) -> bool {
|
||||
let mut chars = trimmed.chars();
|
||||
let mut saw_digit = false;
|
||||
while let Some(c) = chars.next() {
|
||||
if c.is_ascii_digit() {
|
||||
saw_digit = true;
|
||||
continue;
|
||||
}
|
||||
if c == '.' && saw_digit {
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
false
|
||||
}
|
||||
|
||||
/// Classify a single logical line (no trailing newline required).
|
||||
@@ -353,6 +398,9 @@ pub fn classify_source(source: &str) -> Vec<ClassifiedLine> {
|
||||
in_writeback = false;
|
||||
}
|
||||
LineKind::Writeback
|
||||
} else if is_image_writeback_line(trimmed) {
|
||||
in_comment_paragraph = false;
|
||||
LineKind::Writeback
|
||||
} else {
|
||||
match base {
|
||||
LineKind::Blank => {
|
||||
@@ -439,6 +487,26 @@ pub fn format_lines_dump(path: &str, lines: &[ClassifiedLine]) -> String {
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn ordered_arm_breaks_prose_paragraph() {
|
||||
let src = "\
|
||||
# main\n\
|
||||
\n\
|
||||
1. `n` > 0\n\
|
||||
此时我们 **打印 内容=\"正\"**\n\
|
||||
2. *\n\
|
||||
否则 **打印 内容=\"非正\"**\n\
|
||||
";
|
||||
let lines = classify_source(src);
|
||||
let l12 = lines.iter().find(|l| l.text.trim() == "2. *").expect("2. *");
|
||||
assert_eq!(
|
||||
l12.kind,
|
||||
LineKind::Code,
|
||||
"else arm must stay Code after prose, got dump:\n{}",
|
||||
format_lines_dump("t", &lines)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn blank_and_comment_and_code() {
|
||||
assert_eq!(classify_line(""), LineKind::Blank);
|
||||
@@ -498,6 +566,17 @@ mod tests {
|
||||
assert_eq!(lines[3].kind, LineKind::Writeback);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn image_writeback_line_classified() {
|
||||
assert!(is_image_writeback_line(""));
|
||||
assert!(is_image_writeback_line(""));
|
||||
assert!(!is_image_writeback_line(""));
|
||||
let src = "# main\n\n**x = 1**\n\n\n> print text=x\n";
|
||||
let lines = classify_source(src);
|
||||
let img = lines.iter().find(|l| l.text.contains("marqdo-out]")).unwrap();
|
||||
assert_eq!(img.kind, LineKind::Writeback, "{:?}", lines);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn paragraph_comment_keeps_backtick_continuation() {
|
||||
let src = "采用了\n`.mq.md`的双层后缀\n\n> print text=ok\n";
|
||||
|
||||
+15
-1
@@ -92,6 +92,8 @@ pub struct RunOptions {
|
||||
pub allow_fs_write: bool,
|
||||
pub allow_exec: bool,
|
||||
pub allow_net: bool,
|
||||
/// Native `plugin.load` (default true for CLI; false inside `sandbox.run`).
|
||||
pub allow_plugin: bool,
|
||||
/// Exposed via `host_args` / `args`.
|
||||
pub argv: Vec<String>,
|
||||
/// Override filesystem sandbox root (default: source file's directory).
|
||||
@@ -102,6 +104,8 @@ pub struct RunOptions {
|
||||
pub emit_result: Option<std::path::PathBuf>,
|
||||
/// CLI `--bind KEY=VALUE` pairs for Artifact Metadata Binding (`arg` + overlay).
|
||||
pub binds: Vec<(String, String)>,
|
||||
/// Attach CoW session for `ext/ai/sandbox` nested runs.
|
||||
pub sandbox_session: Option<String>,
|
||||
}
|
||||
|
||||
impl Default for RunOptions {
|
||||
@@ -118,11 +122,13 @@ impl Default for RunOptions {
|
||||
allow_fs_write: true,
|
||||
allow_exec: true,
|
||||
allow_net: true,
|
||||
allow_plugin: true,
|
||||
argv: Vec::new(),
|
||||
fs_root: None,
|
||||
sleep_limit_ms: None,
|
||||
emit_result: None,
|
||||
binds: Vec::new(),
|
||||
sandbox_session: None,
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -154,7 +160,7 @@ impl RunOptions {
|
||||
fs_write: self.allow_fs_write,
|
||||
exec: self.allow_exec,
|
||||
net: self.allow_net,
|
||||
plugin: true,
|
||||
plugin: self.allow_plugin,
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -289,6 +295,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
|
||||
host.set_entry_source(Some(path), &source);
|
||||
host.argv = opts.argv.clone();
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
host.sandbox_session = opts.sandbox_session.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
@@ -306,6 +313,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
|
||||
value,
|
||||
plots,
|
||||
bindings: interp.entry_bindings,
|
||||
view_trace: interp.view_trace,
|
||||
})
|
||||
}
|
||||
Backend::Bytecode => {
|
||||
@@ -314,6 +322,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
|
||||
host.set_entry_source(Some(path), &source);
|
||||
host.argv = opts.argv.clone();
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
host.sandbox_session = opts.sandbox_session.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
@@ -331,6 +340,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
|
||||
value,
|
||||
plots,
|
||||
bindings: Default::default(),
|
||||
view_trace: Default::default(),
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -349,6 +359,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
|
||||
host.set_entry_source(None, source);
|
||||
host.argv = opts.argv.clone();
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
host.sandbox_session = opts.sandbox_session.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
@@ -366,6 +377,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
|
||||
value,
|
||||
plots,
|
||||
bindings: interp.entry_bindings,
|
||||
view_trace: interp.view_trace,
|
||||
})
|
||||
}
|
||||
Backend::Bytecode => {
|
||||
@@ -374,6 +386,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
|
||||
host.set_entry_source(None, source);
|
||||
host.argv = opts.argv.clone();
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
host.sandbox_session = opts.sandbox_session.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
@@ -391,6 +404,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
|
||||
value,
|
||||
plots,
|
||||
bindings: Default::default(),
|
||||
view_trace: Default::default(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
+411
-30
@@ -358,6 +358,13 @@ impl<'a> Cursor<'a> {
|
||||
continue;
|
||||
}
|
||||
|
||||
if self.peek_is_formula_fence() {
|
||||
if let Some(stmt) = self.try_parse_meta_formula_assign()? {
|
||||
fun.body.push(stmt);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
if is_ordered_branch(trimmed) {
|
||||
fun.body.push(self.parse_branch()?);
|
||||
continue;
|
||||
@@ -405,9 +412,10 @@ impl<'a> Cursor<'a> {
|
||||
}
|
||||
|
||||
if trimmed.starts_with("$$") {
|
||||
// Standalone meta formulas are handled before parse_simple_stmt.
|
||||
bail!(
|
||||
"{span}: formula fence must follow an empty assignment (`name` =); \
|
||||
`$$:name` binding was removed"
|
||||
"{span}: formula fence must follow an empty assignment (`name` =) \
|
||||
or include `% marqdo: var=name` inside the block"
|
||||
);
|
||||
}
|
||||
|
||||
@@ -503,7 +511,7 @@ impl<'a> Cursor<'a> {
|
||||
if crate::aliases::is_reserved_keyword(&name) {
|
||||
bail!("{span}: `{name}` is a reserved keyword");
|
||||
}
|
||||
let (value, end_line) = self.resolve_assign_rhs(&rhs, span, true)?;
|
||||
let (value, end_line) = self.resolve_assign_rhs(&name, &rhs, span, true)?;
|
||||
return Ok(Stmt::Assign {
|
||||
name,
|
||||
value,
|
||||
@@ -544,7 +552,7 @@ impl<'a> Cursor<'a> {
|
||||
if crate::aliases::is_reserved_keyword(&name) {
|
||||
bail!("{span}: `{name}` is a reserved keyword");
|
||||
}
|
||||
let (value, end_line) = self.resolve_assign_rhs(&rhs, span, true)?;
|
||||
let (value, end_line) = self.resolve_assign_rhs(&name, &rhs, span, true)?;
|
||||
Ok(Stmt::Assign {
|
||||
name,
|
||||
value,
|
||||
@@ -570,7 +578,7 @@ impl<'a> Cursor<'a> {
|
||||
return Ok(None);
|
||||
}
|
||||
let rhs = after[1..].trim().to_string();
|
||||
let (value, end_line) = self.resolve_assign_rhs(&rhs, span, false)?;
|
||||
let (value, end_line) = self.resolve_assign_rhs(&name, &rhs, span, false)?;
|
||||
Ok(Some(Stmt::Assign {
|
||||
name,
|
||||
value,
|
||||
@@ -584,6 +592,7 @@ impl<'a> Cursor<'a> {
|
||||
/// `prefer_var`: italic RHS uses variable-preferring expression syntax.
|
||||
fn resolve_assign_rhs(
|
||||
&mut self,
|
||||
assign_name: &str,
|
||||
rhs: &str,
|
||||
span: Span,
|
||||
prefer_var: bool,
|
||||
@@ -592,7 +601,9 @@ impl<'a> Cursor<'a> {
|
||||
if rhs.is_empty() {
|
||||
self.skip_blanks();
|
||||
if self.peek_is_formula_fence() {
|
||||
return self.consume_formula_fence(span);
|
||||
let (expr, end_line, meta_var) = self.consume_formula_fence(span)?;
|
||||
check_formula_meta_var(assign_name, meta_var.as_deref(), span)?;
|
||||
return Ok((expr, end_line));
|
||||
}
|
||||
if self.peek_is_code_fence() {
|
||||
return self.consume_code_fence(span);
|
||||
@@ -698,7 +709,8 @@ impl<'a> Cursor<'a> {
|
||||
))
|
||||
}
|
||||
|
||||
fn consume_formula_fence(&mut self, span: Span) -> Result<(Expr, u32)> {
|
||||
/// Consume `$$…$$`. Returns `(expr, end_line, optional var from % marqdo: var=)`.
|
||||
fn consume_formula_fence(&mut self, span: Span) -> Result<(Expr, u32, Option<String>)> {
|
||||
let open = self
|
||||
.bump()
|
||||
.ok_or_else(|| anyhow::anyhow!("{span}: expected `$$` formula fence"))?;
|
||||
@@ -707,7 +719,7 @@ impl<'a> Cursor<'a> {
|
||||
if trimmed.starts_with("$$:") || trimmed.starts_with("$$ name=") {
|
||||
bail!(
|
||||
"{open_line}:1: `$$:name` / `$$ name=` binding was removed; \
|
||||
use `name` = then a `$$…$$` fence"
|
||||
use `% marqdo: var=name` inside `$$…$$` or `name` = then a fence"
|
||||
);
|
||||
}
|
||||
// Single-line: $$body$$
|
||||
@@ -716,15 +728,21 @@ impl<'a> Cursor<'a> {
|
||||
if body.is_empty() {
|
||||
bail!("{open_line}:1: empty formula");
|
||||
}
|
||||
let (meta_var, tex) = strip_formula_marqdo_meta(body)
|
||||
.map_err(|e| anyhow::anyhow!("{open_line}:1: {e}"))?;
|
||||
if tex.is_empty() {
|
||||
bail!("{open_line}:1: empty formula");
|
||||
}
|
||||
return Ok((
|
||||
formula_fence_to_expr(body)
|
||||
formula_fence_to_expr(&tex)
|
||||
.map_err(|e| anyhow::anyhow!("{open_line}:1: formula: {e}"))?,
|
||||
open_line,
|
||||
meta_var,
|
||||
));
|
||||
}
|
||||
if trimmed != "$$" {
|
||||
bail!(
|
||||
"{open_line}:1: expected `$$` fence opener after empty assignment, got: {trimmed}"
|
||||
"{open_line}:1: expected `$$` fence opener, got: {trimmed}"
|
||||
);
|
||||
}
|
||||
let mut body_lines: Vec<String> = Vec::new();
|
||||
@@ -743,13 +761,45 @@ impl<'a> Cursor<'a> {
|
||||
if !closed {
|
||||
bail!("{open_line}:1: unclosed formula fence `$$`");
|
||||
}
|
||||
let text = body_lines.join("\n").trim().to_string();
|
||||
if text.is_empty() {
|
||||
let raw = body_lines.join("\n");
|
||||
let (meta_var, tex) = strip_formula_marqdo_meta(&raw)
|
||||
.map_err(|e| anyhow::anyhow!("{open_line}:1: {e}"))?;
|
||||
if tex.is_empty() {
|
||||
bail!("{open_line}:1: empty formula");
|
||||
}
|
||||
let expr = formula_fence_to_expr(&text)
|
||||
let expr = formula_fence_to_expr(&tex)
|
||||
.map_err(|e| anyhow::anyhow!("{open_line}:1: formula: {e}"))?;
|
||||
Ok((expr, end_line))
|
||||
Ok((expr, end_line, meta_var))
|
||||
}
|
||||
|
||||
/// Standalone `$$` with `% marqdo: var=` → Assign (no empty RHS required).
|
||||
fn try_parse_meta_formula_assign(&mut self) -> Result<Option<Stmt>> {
|
||||
if !self.peek_is_formula_fence() {
|
||||
return Ok(None);
|
||||
}
|
||||
let Some(l) = self.peek() else {
|
||||
return Ok(None);
|
||||
};
|
||||
let span = Span {
|
||||
line: l.line_no,
|
||||
col: 1,
|
||||
};
|
||||
let (value, end_line, meta_var) = self.consume_formula_fence(span)?;
|
||||
let Some(name) = meta_var else {
|
||||
bail!(
|
||||
"{span}: formula fence must follow an empty assignment (`name` =) \
|
||||
or include `% marqdo: var=name` inside the block"
|
||||
);
|
||||
};
|
||||
if crate::aliases::is_reserved_keyword(&name) {
|
||||
bail!("{span}: `{name}` is a reserved keyword");
|
||||
}
|
||||
Ok(Some(Stmt::Assign {
|
||||
name,
|
||||
value,
|
||||
span,
|
||||
end_line,
|
||||
}))
|
||||
}
|
||||
|
||||
/// GFM table after empty RHS:
|
||||
@@ -878,11 +928,7 @@ impl<'a> Cursor<'a> {
|
||||
let cond_src = strip_ordered(trimmed).unwrap();
|
||||
self.bump();
|
||||
|
||||
let condition = if cond_src == "*" || cond_src.is_empty() {
|
||||
None
|
||||
} else {
|
||||
Some(parse_expr_str(cond_src)?)
|
||||
};
|
||||
let condition = parse_branch_condition(cond_src)?;
|
||||
|
||||
let body = self.parse_indented_body(base_indent)?;
|
||||
arms.push(BranchArm { condition, body });
|
||||
@@ -904,8 +950,10 @@ impl<'a> Cursor<'a> {
|
||||
let trimmed = line.text.trim();
|
||||
let rest = trimmed.strip_prefix('-').unwrap().trim();
|
||||
|
||||
// foreach: [item](collection)
|
||||
if let Some((item, coll)) = parse_foreach_header(rest) {
|
||||
// foreach: [item](collection) or narrative sugar
|
||||
if let Some((item, coll)) = parse_foreach_header(rest)
|
||||
.or_else(|| parse_foreach_narrative(rest))
|
||||
{
|
||||
let body = self.parse_indented_body(base_indent)?;
|
||||
return Ok(Stmt::ForEach {
|
||||
item,
|
||||
@@ -931,7 +979,7 @@ impl<'a> Cursor<'a> {
|
||||
let Some(l) = self.peek() else { break };
|
||||
let ind = indent_of(&l.text);
|
||||
if ind <= parent_indent {
|
||||
// Same-indent `+`/`-` ends body (next arm / sibling).
|
||||
// Same-indent `2.` / `-` ends body (next arm / sibling).
|
||||
break;
|
||||
}
|
||||
let trimmed = l.text.trim();
|
||||
@@ -951,6 +999,39 @@ impl<'a> Cursor<'a> {
|
||||
body.push(self.parse_loop_or_err()?);
|
||||
continue;
|
||||
}
|
||||
// Same prose rights as function body (fixes arm/loop narrative escape).
|
||||
if self.peek_is_prose() {
|
||||
let line = self.bump().unwrap();
|
||||
let span = Span {
|
||||
line: line.line_no,
|
||||
col: 1,
|
||||
};
|
||||
let bits = scan_prose_line(line.text.trim_end_matches(['\r', '\n']));
|
||||
let mut end_arm = false;
|
||||
for bit in bits {
|
||||
match bit {
|
||||
ProseBit::Decl { .. } => {}
|
||||
ProseBit::BoldCode { inner, .. } => {
|
||||
body.push(self.stmt_from_bold_inner(&inner, span.clone())?);
|
||||
}
|
||||
ProseBit::ItalicReturn { inner, .. } => {
|
||||
body.push(stmt_from_italic_return(&inner, span.clone())?);
|
||||
end_arm = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
if end_arm {
|
||||
break;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if self.peek_is_formula_fence() {
|
||||
if let Some(stmt) = self.try_parse_meta_formula_assign()? {
|
||||
body.push(stmt);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
let stmt = self.parse_simple_stmt()?;
|
||||
let end_arm = matches!(stmt, Stmt::Return { .. });
|
||||
body.push(stmt);
|
||||
@@ -998,26 +1079,101 @@ fn is_bare_assign_ident(s: &str) -> bool {
|
||||
true
|
||||
}
|
||||
|
||||
/// Same-line `$$body$$` → Formula or numeric matrix List; otherwise None.
|
||||
/// Same-line `$$body$$` or `$body$` → Formula; otherwise None.
|
||||
fn try_parse_inline_formula(rhs: &str) -> Result<Option<Expr>> {
|
||||
let rhs = rhs.trim();
|
||||
if !rhs.starts_with("$$") {
|
||||
return Ok(None);
|
||||
}
|
||||
if rhs.starts_with("$$:") || rhs.starts_with("$$ name=") {
|
||||
bail!(
|
||||
"`$$:name` / `$$ name=` binding was removed; use `name` = then a `$$…$$` fence"
|
||||
"`$$:name` / `$$ name=` binding was removed; use `% marqdo: var=name` \
|
||||
inside `$$…$$` or `name` = then a fence"
|
||||
);
|
||||
}
|
||||
if rhs.ends_with("$$") && rhs.len() > 4 {
|
||||
let body = rhs[2..rhs.len() - 2].trim();
|
||||
if rhs.starts_with("$$") {
|
||||
if rhs.ends_with("$$") && rhs.len() > 4 {
|
||||
let body = rhs[2..rhs.len() - 2].trim();
|
||||
if body.is_empty() {
|
||||
bail!("empty formula");
|
||||
}
|
||||
let (_meta, tex) = strip_formula_marqdo_meta(body)
|
||||
.map_err(|e| anyhow::anyhow!("{e}"))?;
|
||||
if tex.is_empty() {
|
||||
bail!("empty formula");
|
||||
}
|
||||
let expr = formula_fence_to_expr(&tex).map_err(|e| anyhow::anyhow!("formula: {e}"))?;
|
||||
return Ok(Some(expr));
|
||||
}
|
||||
bail!("incomplete inline formula (expected `$$…$$` on one line)");
|
||||
}
|
||||
// Traditional inline: $…$ (not $$)
|
||||
if rhs.starts_with('$') && rhs.ends_with('$') && rhs.len() > 2 && !rhs.starts_with("$$") {
|
||||
let body = rhs[1..rhs.len() - 1].trim();
|
||||
if body.is_empty() {
|
||||
bail!("empty formula");
|
||||
}
|
||||
if body.contains('%') && body.to_lowercase().contains("marqdo:") {
|
||||
bail!(
|
||||
"inline `$…$` must not use `% marqdo:` (breaks Markdown/TeX); \
|
||||
bind with `name` = $…$ or use a `$$` block with `% marqdo: var=`"
|
||||
);
|
||||
}
|
||||
let expr = formula_fence_to_expr(body).map_err(|e| anyhow::anyhow!("formula: {e}"))?;
|
||||
return Ok(Some(expr));
|
||||
}
|
||||
bail!("incomplete inline formula (expected `$$…$$` on one line)");
|
||||
Ok(None)
|
||||
}
|
||||
|
||||
/// Strip `% marqdo: var=name` directive lines from formula fence body.
|
||||
/// Returns `(optional var name, remaining TeX)`.
|
||||
fn strip_formula_marqdo_meta(body: &str) -> Result<(Option<String>, String), String> {
|
||||
let mut meta_var: Option<String> = None;
|
||||
let mut out: Vec<&str> = Vec::new();
|
||||
for line in body.lines() {
|
||||
let t = line.trim();
|
||||
if let Some(rest) = t.strip_prefix('%') {
|
||||
let rest = rest.trim_start();
|
||||
if rest.to_ascii_lowercase().starts_with("marqdo:") {
|
||||
let after = rest["marqdo:".len()..].trim_start();
|
||||
let mut got_var = false;
|
||||
for part in after.split_whitespace() {
|
||||
if let Some(v) = part.strip_prefix("var=") {
|
||||
if v.is_empty() {
|
||||
return Err("% marqdo: var= requires a name".into());
|
||||
}
|
||||
if !is_bare_assign_ident(v) {
|
||||
return Err(format!("invalid marqdo var name `{v}`"));
|
||||
}
|
||||
if meta_var.as_deref() == Some(v) || meta_var.is_none() {
|
||||
meta_var = Some(v.to_string());
|
||||
} else {
|
||||
return Err(format!(
|
||||
"conflicting % marqdo: var= ({} vs {v})",
|
||||
meta_var.as_deref().unwrap_or("")
|
||||
));
|
||||
}
|
||||
got_var = true;
|
||||
} else {
|
||||
return Err(format!("unknown marqdo key `{part}` (only var= is supported)"));
|
||||
}
|
||||
}
|
||||
if !got_var {
|
||||
return Err("% marqdo: requires var=<name>".into());
|
||||
}
|
||||
continue; // strip directive line
|
||||
}
|
||||
}
|
||||
out.push(line);
|
||||
}
|
||||
Ok((meta_var, out.join("\n").trim().to_string()))
|
||||
}
|
||||
|
||||
fn check_formula_meta_var(assign_name: &str, meta: Option<&str>, span: Span) -> Result<()> {
|
||||
match meta {
|
||||
None => Ok(()),
|
||||
Some(v) if v == assign_name => Ok(()),
|
||||
Some(v) => bail!(
|
||||
"{span}: formula `% marqdo: var={v}` conflicts with assignment `{assign_name}`"
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
fn formula_fence_to_expr(body: &str) -> Result<Expr, String> {
|
||||
@@ -1112,6 +1268,148 @@ fn parse_foreach_header(rest: &str) -> Option<(String, String)> {
|
||||
Some((item, coll))
|
||||
}
|
||||
|
||||
/// Narrative foreach sugar (recommended remains `- [item](coll)`).
|
||||
/// - ZH: `对`xs`的每一项`项`` optional `遍历`
|
||||
/// - EN: `for each `item` in `xs``
|
||||
fn parse_foreach_narrative(rest: &str) -> Option<(String, String)> {
|
||||
let rest = rest.trim();
|
||||
if let Some(after) = rest.strip_prefix('对') {
|
||||
let (coll, after) = take_backtick_token(after.trim_start())?;
|
||||
let after = after.trim_start().strip_prefix("的每一项")?;
|
||||
let (item, after) = take_backtick_token(after.trim_start())?;
|
||||
let after = after
|
||||
.trim()
|
||||
.trim_end_matches('。')
|
||||
.trim();
|
||||
let after = after.strip_prefix("遍历").unwrap_or(after).trim();
|
||||
if after.is_empty() {
|
||||
return Some((item, coll));
|
||||
}
|
||||
return None;
|
||||
}
|
||||
let lower = rest.to_ascii_lowercase();
|
||||
let Some(idx) = lower.find("for each ") else {
|
||||
return None;
|
||||
};
|
||||
if idx != 0 {
|
||||
return None;
|
||||
}
|
||||
let after = rest["for each ".len()..].trim_start();
|
||||
let (item, after) = take_backtick_token(after)?;
|
||||
let after = after.trim_start();
|
||||
let after_l = after.to_ascii_lowercase();
|
||||
if !after_l.starts_with("in ") && !after_l.starts_with("in\t") {
|
||||
// require ` in `
|
||||
let Some(in_at) = after_l.find("in ") else {
|
||||
return None;
|
||||
};
|
||||
if in_at != 0 {
|
||||
return None;
|
||||
}
|
||||
}
|
||||
let after = after["in ".len()..].trim_start();
|
||||
let (coll, after) = take_backtick_token(after)?;
|
||||
if after.trim().is_empty() {
|
||||
return Some((item, coll));
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn take_backtick_token(s: &str) -> Option<(String, &str)> {
|
||||
let s = s.trim_start();
|
||||
if !s.starts_with('`') {
|
||||
return None;
|
||||
}
|
||||
let end = s[1..].find('`')?;
|
||||
let name = s[1..1 + end].to_string();
|
||||
if name.is_empty() {
|
||||
return None;
|
||||
}
|
||||
Some((name, &s[1 + end + 1..]))
|
||||
}
|
||||
|
||||
/// Branch arm condition: expr, bold code, narrative (当`n`大于 0 时), or else `*`.
|
||||
fn parse_branch_condition(cond_src: &str) -> Result<Option<Expr>> {
|
||||
let t = cond_src.trim();
|
||||
if t.is_empty() || t == "*" {
|
||||
return Ok(None);
|
||||
}
|
||||
// "否则 *" / "else *"
|
||||
if let Some(before) = t.strip_suffix('*') {
|
||||
let before = before.trim();
|
||||
if before.is_empty()
|
||||
|| before == "否则"
|
||||
|| before == "其它"
|
||||
|| before == "其他"
|
||||
|| before.eq_ignore_ascii_case("else")
|
||||
|| before.eq_ignore_ascii_case("otherwise")
|
||||
{
|
||||
return Ok(None);
|
||||
}
|
||||
}
|
||||
if let Ok(e) = parse_expr_str(t) {
|
||||
return Ok(Some(e));
|
||||
}
|
||||
if let Some(inner) = extract_first_bold_inner(t) {
|
||||
if let Ok(e) = parse_expr_str(inner.trim()) {
|
||||
return Ok(Some(e));
|
||||
}
|
||||
}
|
||||
if let Some(e) = try_narrative_condition(t) {
|
||||
return Ok(Some(e));
|
||||
}
|
||||
bail!(
|
||||
"branch condition: cannot parse `{t}` \
|
||||
(use an expression, **`n` > 0**, or 当`n`大于 0 时)"
|
||||
)
|
||||
}
|
||||
|
||||
fn extract_first_bold_inner(s: &str) -> Option<&str> {
|
||||
let start = s.find("**")?;
|
||||
let rest = &s[start + 2..];
|
||||
let end = rest.find("**")?;
|
||||
Some(&rest[..end])
|
||||
}
|
||||
|
||||
fn try_narrative_condition(s: &str) -> Option<Expr> {
|
||||
let mut s = s.trim();
|
||||
for p in ["当且仅当", "当", "若", "如果"] {
|
||||
if let Some(r) = s.strip_prefix(p) {
|
||||
s = r.trim_start();
|
||||
break;
|
||||
}
|
||||
}
|
||||
let lower = s.to_ascii_lowercase();
|
||||
if let Some(r) = lower.strip_prefix("when ") {
|
||||
let _ = r;
|
||||
s = s[5..].trim_start();
|
||||
} else if let Some(r) = lower.strip_prefix("if ") {
|
||||
let _ = r;
|
||||
s = s[3..].trim_start();
|
||||
}
|
||||
for suf in ["的话", "时", "则"] {
|
||||
if let Some(r) = s.strip_suffix(suf) {
|
||||
s = r.trim_end();
|
||||
}
|
||||
}
|
||||
let mut mapped = s.to_string();
|
||||
let replacements = [
|
||||
("大于等于", ">="),
|
||||
("小于等于", "<="),
|
||||
("不等于", "!="),
|
||||
("等于", "=="),
|
||||
("大于", ">"),
|
||||
("小于", "<"),
|
||||
];
|
||||
for (zh, op) in replacements {
|
||||
if mapped.contains(zh) {
|
||||
mapped = mapped.replace(zh, op);
|
||||
break;
|
||||
}
|
||||
}
|
||||
parse_expr_str(mapped.trim()).ok()
|
||||
}
|
||||
|
||||
fn parse_heading(trimmed: &str) -> Option<(u8, &str)> {
|
||||
if !trimmed.starts_with('#') {
|
||||
return None;
|
||||
@@ -1882,6 +2180,89 @@ mod tests {
|
||||
use super::*;
|
||||
use crate::ast::Stmt;
|
||||
|
||||
#[test]
|
||||
fn parse_formula_meta_var_standalone() {
|
||||
let src = "# main\n\n$$\n% marqdo: var=f\nx^2 - 2\n$$\n";
|
||||
let m = parse_source(src).unwrap();
|
||||
match &m.functions[0].body[0] {
|
||||
Stmt::Assign { name, value, .. } => {
|
||||
assert_eq!(name, "f");
|
||||
assert!(matches!(value, Expr::Formula(_)));
|
||||
}
|
||||
other => panic!("expected formula assign, got {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_formula_meta_conflicts_with_assign() {
|
||||
let src = "# main\n\n`f` =\n$$\n% marqdo: var=g\nx\n$$\n";
|
||||
let err = parse_source(src).unwrap_err().to_string();
|
||||
assert!(
|
||||
err.contains("conflicts") || err.contains("var=g"),
|
||||
"{err}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_foreach_narrative_zh_en() {
|
||||
let src = "# main\n\n- 对`xs`的每一项`项`\n > print text=`项`\n\n- for each `item` in `ys`\n > print text=`item`\n";
|
||||
let m = parse_source(src).unwrap();
|
||||
match &m.functions[0].body[0] {
|
||||
Stmt::ForEach { item, collection, .. } => {
|
||||
assert_eq!(item, "项");
|
||||
assert_eq!(collection, "xs");
|
||||
}
|
||||
other => panic!("zh foreach: {other:?}"),
|
||||
}
|
||||
match &m.functions[0].body[1] {
|
||||
Stmt::ForEach { item, collection, .. } => {
|
||||
assert_eq!(item, "item");
|
||||
assert_eq!(collection, "ys");
|
||||
}
|
||||
other => panic!("en foreach: {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn branch_arm_prose_stays_inside_arm() {
|
||||
let src = include_str!("../../tests/markup-v03/branch-arm-prose.mq.md");
|
||||
let m = parse_source(src).unwrap();
|
||||
let main = &m.functions[0];
|
||||
let branches: Vec<_> = main
|
||||
.body
|
||||
.iter()
|
||||
.filter(|s| matches!(s, Stmt::Branch { .. }))
|
||||
.collect();
|
||||
assert_eq!(
|
||||
branches.len(),
|
||||
1,
|
||||
"expected one Branch, body={:?}",
|
||||
main.body
|
||||
);
|
||||
match &main.body[1] {
|
||||
Stmt::Branch { arms, .. } => {
|
||||
assert_eq!(arms.len(), 2, "arms={arms:?}");
|
||||
assert!(
|
||||
!arms[0].body.is_empty(),
|
||||
"then arm must contain prose stmts: {:?}",
|
||||
arms[0].body
|
||||
);
|
||||
assert!(
|
||||
!arms[1].body.is_empty(),
|
||||
"else arm must contain prose stmts: {:?}",
|
||||
arms[1].body
|
||||
);
|
||||
}
|
||||
other => panic!("expected Branch as body[1] after assign, got {other:?}"),
|
||||
}
|
||||
// No Call/Assign print siblings after the branch
|
||||
assert!(
|
||||
!main.body.iter().skip(2).any(|s| matches!(s, Stmt::Call { .. } | Stmt::Assign { .. })),
|
||||
"prose escaped branch: {:?}",
|
||||
main.body
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_hello() {
|
||||
let src = include_str!("../../tests/structure/hello.mq.md");
|
||||
|
||||
+1155
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
+671
-4
@@ -330,6 +330,236 @@ section.block > h2 {
|
||||
background: transparent;
|
||||
padding-left: calc(1.1rem - 2px);
|
||||
}
|
||||
/* Document surface (Browse Structure) */
|
||||
.document-surface {
|
||||
padding: 0.5rem 1rem 1.25rem;
|
||||
color: var(--ink);
|
||||
line-height: 1.55;
|
||||
}
|
||||
.doc-imports { margin: 0 0 0.85rem; }
|
||||
.doc-fun {
|
||||
margin: 1.1rem 0 0.65rem;
|
||||
padding-bottom: 0.35rem;
|
||||
border-bottom: 1px solid var(--line);
|
||||
}
|
||||
.doc-fun-title {
|
||||
margin: 0;
|
||||
font-size: 1.15rem;
|
||||
font-weight: 650;
|
||||
letter-spacing: -0.01em;
|
||||
}
|
||||
.doc-fun-bar {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
gap: 0.5rem 1rem;
|
||||
}
|
||||
.call-picker-label {
|
||||
font-size: 0.78rem;
|
||||
color: var(--muted);
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.35rem;
|
||||
}
|
||||
.call-picker, .loop-picker {
|
||||
font-size: 0.78rem;
|
||||
padding: 0.2rem 0.4rem;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 8px;
|
||||
background: var(--surface);
|
||||
color: var(--ink);
|
||||
}
|
||||
.loop-picker-label {
|
||||
font-size: 0.78rem;
|
||||
color: var(--muted);
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.35rem;
|
||||
}
|
||||
li.doc-list-meta {
|
||||
list-style: none;
|
||||
margin: 0.25rem 0 0.5rem;
|
||||
margin-left: -1.25rem;
|
||||
}
|
||||
.doc-block { position: relative; margin: 0.55rem 0 0.85rem; }
|
||||
.doc-block > .annot-leaders {
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
pointer-events: none;
|
||||
overflow: visible;
|
||||
z-index: 1; /* below .annot-chips */
|
||||
}
|
||||
.doc-block > .annot-leaders svg {
|
||||
position: absolute;
|
||||
left: 0;
|
||||
top: 0;
|
||||
overflow: visible;
|
||||
}
|
||||
.doc-block.is-keyed > .annot-leaders { display: none; }
|
||||
.doc-block.doc-exec[style*="--doc-indent"] {
|
||||
margin-left: calc(var(--doc-indent, 1) * 1.5rem);
|
||||
}
|
||||
.doc-prose { color: var(--ink); }
|
||||
.doc-prose > :first-child { margin-top: 0; }
|
||||
.doc-prose > :last-child { margin-bottom: 0; }
|
||||
.doc-line { margin: 0.15rem 0; }
|
||||
.doc-prose-line { white-space: pre-wrap; }
|
||||
.doc-stmt, .doc-call, .doc-cond {
|
||||
font-family: var(--mono);
|
||||
font-size: 0.92em;
|
||||
}
|
||||
.mq-call-gt { color: var(--muted); margin-right: 0.25rem; }
|
||||
.mq-else { font-family: var(--mono); color: var(--muted); font-style: italic; }
|
||||
.doc-table-wrap { overflow-x: auto; }
|
||||
.doc-table {
|
||||
border-collapse: collapse;
|
||||
width: auto;
|
||||
min-width: 12rem;
|
||||
font-size: 0.92rem;
|
||||
margin: 0.35rem 0;
|
||||
}
|
||||
.doc-table th, .doc-table td {
|
||||
border: 1px solid var(--line);
|
||||
padding: 0.35rem 0.7rem;
|
||||
text-align: left;
|
||||
}
|
||||
.doc-table th {
|
||||
background: var(--fill);
|
||||
font-weight: 600;
|
||||
}
|
||||
ul.doc-loop, ol.doc-branch {
|
||||
margin: 0.5rem 0 0.75rem;
|
||||
padding-left: calc(var(--doc-indent, 1) * 1.5rem + 1.25rem);
|
||||
}
|
||||
.doc-list-item { margin: 0.45rem 0; }
|
||||
.doc-list-head { font-family: var(--mono); font-size: 0.92em; }
|
||||
.doc-list-body {
|
||||
margin: 0.35rem 0 0.2rem;
|
||||
padding-left: 1.5rem;
|
||||
border-left: 2px solid var(--line);
|
||||
}
|
||||
.doc-list-item.arm-taken {
|
||||
border-left: 3px solid #bf5af2;
|
||||
padding-left: 0.55rem;
|
||||
margin-left: -0.15rem;
|
||||
}
|
||||
.doc-list-item.arm-taken > .doc-list-head { font-weight: 600; }
|
||||
.doc-list-item.arm-miss { opacity: 0.45; }
|
||||
.doc-code {
|
||||
font-family: var(--mono);
|
||||
font-size: 0.9em;
|
||||
white-space: pre-wrap;
|
||||
}
|
||||
.mq-anchor {
|
||||
background: transparent;
|
||||
color: inherit;
|
||||
padding: 0 0.05em;
|
||||
border-radius: 0;
|
||||
border-bottom: 2px solid var(--line-strong);
|
||||
font-style: normal;
|
||||
font-weight: inherit;
|
||||
cursor: default;
|
||||
}
|
||||
.mq-anchor.mq-decl {
|
||||
border-bottom-color: #5ac8fa;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.95em;
|
||||
}
|
||||
.mq-anchor.mq-code {
|
||||
border-bottom-color: #ff9f0a;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.95em;
|
||||
font-weight: 600;
|
||||
}
|
||||
.mq-anchor.mq-return {
|
||||
border-bottom-color: #30d158;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.95em;
|
||||
font-style: italic;
|
||||
}
|
||||
.mq-anchor.is-focus { background: rgba(0,0,0,0.04); }
|
||||
.annot-band {
|
||||
position: relative;
|
||||
margin: 0.55rem 0 0.15rem;
|
||||
min-height: 1.6rem;
|
||||
padding-top: 1.15rem; /* room for mid→mid leaders (rail + stub) */
|
||||
z-index: 1;
|
||||
}
|
||||
/* Band-local leaders kept for keyed fallback; geometry uses .doc-block > .annot-leaders */
|
||||
.annot-band > .annot-leaders { display: none; }
|
||||
.annot-leader {
|
||||
fill: none;
|
||||
stroke-width: 1.5;
|
||||
stroke-linecap: round;
|
||||
stroke-linejoin: round;
|
||||
pointer-events: none;
|
||||
}
|
||||
.annot-chips {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.45rem 0.7rem;
|
||||
position: relative;
|
||||
z-index: 3; /* chips above leaders */
|
||||
}
|
||||
.annot-chip {
|
||||
display: inline-flex;
|
||||
align-items: baseline;
|
||||
gap: 0.35rem;
|
||||
max-width: 100%;
|
||||
margin: 0;
|
||||
padding: 0.22rem 0.5rem;
|
||||
border: 1px solid var(--line);
|
||||
border-left-width: 3px;
|
||||
border-radius: 8px;
|
||||
background: var(--fill);
|
||||
color: var(--ink);
|
||||
font-family: var(--mono);
|
||||
font-size: 0.72rem;
|
||||
cursor: pointer;
|
||||
text-align: left;
|
||||
}
|
||||
/* Author `display:inline-flex` must not defeat frame filtering. */
|
||||
.annot-chip[hidden],
|
||||
.annot-chip.is-frame-hidden {
|
||||
display: none !important;
|
||||
}
|
||||
.annot-chip:hover,
|
||||
.annot-chip.is-focus { background: #fff; }
|
||||
.annot-chip.annot-bind { border-left-color: #5ac8fa; }
|
||||
.annot-chip.annot-return { border-left-color: #30d158; }
|
||||
.annot-chip.annot-call,
|
||||
.annot-chip.annot-expr,
|
||||
.annot-chip.annot-code { border-left-color: #ff9f0a; }
|
||||
.annot-chip.annot-branch { border-left-color: #bf5af2; }
|
||||
.annot-chip.annot-loop { border-left-color: #64d2ff; }
|
||||
.annot-chip.annot-writeback { border-left-color: #8e8e93; }
|
||||
.annot-chip.annot-chip-overflow { display: none !important; }
|
||||
.annot-band.is-expanded .annot-chip.annot-chip-overflow:not([hidden]):not(.is-frame-hidden) {
|
||||
display: inline-flex !important;
|
||||
}
|
||||
.annot-label { color: var(--muted); font-weight: 600; }
|
||||
.annot-value { color: var(--ink); word-break: break-word; }
|
||||
.annot-more {
|
||||
border: 1px dashed var(--line);
|
||||
border-radius: 8px;
|
||||
background: transparent;
|
||||
color: var(--muted);
|
||||
font-size: 0.72rem;
|
||||
padding: 0.22rem 0.45rem;
|
||||
cursor: pointer;
|
||||
}
|
||||
.annot-band.is-keyed .annot-chip::before,
|
||||
.doc-block.is-keyed .annot-chip::before {
|
||||
content: attr(data-annot-key) " ";
|
||||
color: var(--muted);
|
||||
}
|
||||
@media (max-width: 640px) {
|
||||
.annot-band { padding-top: 0.25rem; }
|
||||
.doc-block > .annot-leaders { display: none; }
|
||||
}
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.doc-block > .annot-leaders { display: none; }
|
||||
}
|
||||
.badge {
|
||||
display: inline-block;
|
||||
font-family: var(--mono);
|
||||
@@ -365,6 +595,15 @@ section.block > h2 {
|
||||
font-size: 0.65em;
|
||||
opacity: 0.7;
|
||||
}
|
||||
.chip .chip-val {
|
||||
font-weight: 500;
|
||||
opacity: 0.78;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.92em;
|
||||
}
|
||||
.chip .chip-val:empty {
|
||||
display: none;
|
||||
}
|
||||
.nested {
|
||||
margin: 0.45rem 0 0.15rem 0.15rem;
|
||||
padding-left: 0.85rem;
|
||||
@@ -735,6 +974,9 @@ section.block > h2 {
|
||||
border-left: 3px solid #2563eb;
|
||||
background: #f8fafc;
|
||||
}
|
||||
.output-card.output-card-image {
|
||||
border-left-color: #0d9488;
|
||||
}
|
||||
.output-card .wb-badges {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
@@ -750,6 +992,58 @@ section.block > h2 {
|
||||
white-space: pre-wrap;
|
||||
color: #0f172a;
|
||||
}
|
||||
.wb-figure {
|
||||
margin: 0.5rem 0 0;
|
||||
padding: 0;
|
||||
}
|
||||
.wb-image {
|
||||
display: block;
|
||||
max-width: 100%;
|
||||
height: auto;
|
||||
border-radius: 6px;
|
||||
border: 1px solid var(--line);
|
||||
background: #fff;
|
||||
}
|
||||
.wb-image-url {
|
||||
margin: 0.35rem 0 0;
|
||||
font: 0.75rem/1.35 var(--mono);
|
||||
color: var(--muted);
|
||||
word-break: break-all;
|
||||
}
|
||||
.doc-writeback {
|
||||
margin: 0.35rem 0;
|
||||
padding: 0.4rem 0.55rem;
|
||||
border-radius: 8px;
|
||||
border: 1px dashed #94a3b8;
|
||||
background: #f1f5f9;
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.4rem 0.65rem;
|
||||
align-items: baseline;
|
||||
}
|
||||
.doc-writeback[data-wb-kind="image"] {
|
||||
border-color: #0d9488;
|
||||
background: #f0fdfa;
|
||||
}
|
||||
.wb-source-badge {
|
||||
font: 0.68rem/1.2 var(--sans);
|
||||
letter-spacing: 0.04em;
|
||||
text-transform: uppercase;
|
||||
color: #334155;
|
||||
background: #e2e8f0;
|
||||
padding: 0.12rem 0.4rem;
|
||||
border-radius: 4px;
|
||||
}
|
||||
.doc-writeback[data-wb-kind="image"] .wb-source-badge {
|
||||
background: #ccfbf1;
|
||||
color: #115e59;
|
||||
}
|
||||
.wb-source-text {
|
||||
font: 0.82rem/1.4 var(--mono);
|
||||
color: #0f172a;
|
||||
white-space: pre-wrap;
|
||||
word-break: break-all;
|
||||
}
|
||||
.wb-outline {
|
||||
margin-top: 0.75rem;
|
||||
padding-top: 0.75rem;
|
||||
@@ -1048,6 +1342,16 @@ section.block > h2 {
|
||||
align-items: center;
|
||||
gap: 0.4rem;
|
||||
}
|
||||
.code-foot {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
gap: 0.45rem 0.65rem;
|
||||
padding: 0.5rem 0.85rem;
|
||||
border-top: 1px solid var(--line);
|
||||
background: #fafafa;
|
||||
}
|
||||
.code-foot .code-actions { margin-left: auto; }
|
||||
.code-cmd {
|
||||
min-width: 9rem;
|
||||
max-width: 16rem;
|
||||
@@ -1084,6 +1388,7 @@ section.block > h2 {
|
||||
background: #1e1e1e;
|
||||
color: #d4d4d4;
|
||||
font: 0.82rem/1.45 var(--mono);
|
||||
min-height: 2.4rem;
|
||||
}
|
||||
.code-body code {
|
||||
font: inherit;
|
||||
@@ -1287,17 +1592,23 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
function initForeignCards() {{
|
||||
var live = !!window.MARQDO_VIEW_LIVE;
|
||||
document.querySelectorAll(".code-card").forEach(function (card) {{
|
||||
var foot = card.querySelector(".code-foot");
|
||||
var btn = card.querySelector(".code-run");
|
||||
var cmd = card.querySelector(".code-cmd");
|
||||
var out = card.querySelector(".code-out");
|
||||
var body = card.querySelector(".code-body code");
|
||||
if (!btn || !out || !body) return;
|
||||
// Narrative ```text``` cards have no Run chrome — leave as-is.
|
||||
if (!btn) return;
|
||||
if (!live) {{
|
||||
btn.disabled = true;
|
||||
btn.title = "Run is available in live marqdo view";
|
||||
if (cmd) cmd.disabled = true;
|
||||
// Static: hide fake Run (view-static-interactive D5 / view-prose-annot-gaps P4).
|
||||
if (foot) foot.hidden = true;
|
||||
else {{
|
||||
btn.hidden = true;
|
||||
if (cmd) cmd.hidden = true;
|
||||
}}
|
||||
return;
|
||||
}}
|
||||
if (!out || !body) return;
|
||||
btn.addEventListener("click", function () {{
|
||||
btn.disabled = true;
|
||||
out.hidden = false;
|
||||
@@ -1740,6 +2051,19 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
initVarsPanel();
|
||||
}}
|
||||
}}
|
||||
if (typeof ev.structure_html === "string" && ev.structure_html) {{
|
||||
var structEl = document.getElementById("structure");
|
||||
if (structEl) {{
|
||||
structEl.innerHTML = ev.structure_html;
|
||||
initAnnotLeaders();
|
||||
initCallPickers();
|
||||
initLoopPickers();
|
||||
}}
|
||||
}}
|
||||
if (typeof ev.trace_json === "string" && ev.trace_json) {{
|
||||
var tr = document.getElementById("mq-view-trace");
|
||||
if (tr) tr.textContent = ev.trace_json;
|
||||
}}
|
||||
}}
|
||||
}}
|
||||
}}
|
||||
@@ -1938,18 +2262,352 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
renderMath(panel);
|
||||
}}
|
||||
|
||||
function readViewTrace() {{
|
||||
var el = document.getElementById("mq-view-trace");
|
||||
if (!el) return null;
|
||||
try {{ return JSON.parse(el.textContent || "{{}}"); }} catch (e) {{ return null; }}
|
||||
}}
|
||||
|
||||
function parseArgsBrief(brief) {{
|
||||
var out = {{}};
|
||||
if (!brief) return out;
|
||||
String(brief).split(", ").forEach(function (part) {{
|
||||
var i = part.indexOf("=");
|
||||
if (i <= 0) return;
|
||||
out[part.slice(0, i)] = part.slice(i + 1);
|
||||
}});
|
||||
return out;
|
||||
}}
|
||||
|
||||
function applyParamChipValues(fnName, callId, trace) {{
|
||||
if (!trace || !Array.isArray(trace.calls)) return;
|
||||
var brief = "";
|
||||
for (var i = 0; i < trace.calls.length; i++) {{
|
||||
var c = trace.calls[i];
|
||||
if (String(c.call_id) === String(callId) && String(c.fn || "") === String(fnName)) {{
|
||||
brief = c.args_brief || "";
|
||||
break;
|
||||
}}
|
||||
}}
|
||||
var args = parseArgsBrief(brief);
|
||||
document.querySelectorAll('.chip[data-fn="' + fnName + '"][data-param-name]').forEach(function (chip) {{
|
||||
var name = chip.getAttribute("data-param-name") || "";
|
||||
var slot = chip.querySelector(".chip-val");
|
||||
if (!slot) return;
|
||||
var v = args[name];
|
||||
slot.textContent = v ? ("=" + v) : "";
|
||||
}});
|
||||
}}
|
||||
|
||||
var MAX_VISIBLE_ANNOTS = 4;
|
||||
|
||||
function setFrameHidden(el, hide) {{
|
||||
el.hidden = !!hide;
|
||||
if (hide) el.classList.add("is-frame-hidden");
|
||||
else el.classList.remove("is-frame-hidden");
|
||||
}}
|
||||
|
||||
/** After frame filter: overflow only among chips visible in the selected frame. */
|
||||
function recomputeAnnotOverflow(scope) {{
|
||||
var root = scope || document.getElementById("structure") || document;
|
||||
root.querySelectorAll("[data-annot-band]").forEach(function (band) {{
|
||||
band.classList.remove("is-expanded");
|
||||
var chips = band.querySelectorAll(".annot-chip");
|
||||
var visible = [];
|
||||
chips.forEach(function (chip) {{
|
||||
chip.classList.remove("annot-chip-overflow");
|
||||
if (chip.hidden || chip.classList.contains("is-frame-hidden")) return;
|
||||
visible.push(chip);
|
||||
}});
|
||||
var overflow = 0;
|
||||
visible.forEach(function (chip, i) {{
|
||||
if (i >= MAX_VISIBLE_ANNOTS) {{
|
||||
chip.classList.add("annot-chip-overflow");
|
||||
overflow++;
|
||||
}}
|
||||
}});
|
||||
var more = band.querySelector("[data-annot-more]");
|
||||
if (more) {{
|
||||
if (overflow > 0) {{
|
||||
more.hidden = false;
|
||||
more.textContent = "+" + overflow;
|
||||
}} else {{
|
||||
more.hidden = true;
|
||||
}}
|
||||
}}
|
||||
}});
|
||||
}}
|
||||
|
||||
/** Source structure always stays visible; only chips + arm classes follow the frame. */
|
||||
function initCallPickers() {{
|
||||
document.querySelectorAll(".call-picker").forEach(function (sel) {{
|
||||
function apply() {{
|
||||
var callId = String(sel.value || "");
|
||||
var fnName = String(sel.getAttribute("data-fn") || "");
|
||||
var allowed = {{}};
|
||||
Array.prototype.forEach.call(sel.options, function (o) {{
|
||||
allowed[String(o.value)] = true;
|
||||
}});
|
||||
var root = document.getElementById("structure") || document;
|
||||
// Only touch chips whose call_id belongs to this function's calls.
|
||||
root.querySelectorAll(".annot-chip[data-call-id]").forEach(function (chip) {{
|
||||
var cid = String(chip.getAttribute("data-call-id") || "");
|
||||
if (!allowed[cid]) return;
|
||||
setFrameHidden(chip, cid !== callId);
|
||||
}});
|
||||
var trace = readViewTrace();
|
||||
applyParamChipValues(fnName, callId, trace);
|
||||
if (trace && Array.isArray(trace.events)) {{
|
||||
var takenByLine = {{}};
|
||||
trace.events.forEach(function (ev) {{
|
||||
if (ev.kind === "branch" && String(ev.call_id) === callId && ev.arm_index != null) {{
|
||||
takenByLine[ev.line] = ev.arm_index;
|
||||
}}
|
||||
}});
|
||||
root.querySelectorAll("ol.doc-branch").forEach(function (ol) {{
|
||||
var line = parseInt(ol.getAttribute("data-line") || "0", 10);
|
||||
var taken = takenByLine[line];
|
||||
if (taken === undefined) return;
|
||||
ol.querySelectorAll(":scope > li.doc-list-item[data-arm-index]").forEach(function (li) {{
|
||||
var idx = parseInt(li.getAttribute("data-arm-index") || "-1", 10);
|
||||
li.classList.remove("arm-taken", "arm-miss");
|
||||
if (idx === taken) li.classList.add("arm-taken");
|
||||
else li.classList.add("arm-miss");
|
||||
}});
|
||||
}});
|
||||
}}
|
||||
recomputeAnnotOverflow(root);
|
||||
initAnnotLeaders();
|
||||
}}
|
||||
if (sel.dataset.bound !== "1") {{
|
||||
sel.dataset.bound = "1";
|
||||
sel.addEventListener("change", apply);
|
||||
}}
|
||||
apply();
|
||||
}});
|
||||
}}
|
||||
|
||||
function initLoopPickers() {{
|
||||
document.querySelectorAll(".loop-picker").forEach(function (sel) {{
|
||||
function apply() {{
|
||||
var iter = String(sel.value || "");
|
||||
var loopId = String(sel.getAttribute("data-loop-id") || "");
|
||||
var ul = sel.closest("ul.doc-loop");
|
||||
var scope = ul || document.getElementById("structure");
|
||||
if (!scope) return;
|
||||
// Only the selected iteration's chips; structure source stays visible.
|
||||
scope.querySelectorAll(".annot-chip").forEach(function (chip) {{
|
||||
var lid = chip.getAttribute("data-loop-id");
|
||||
var chipIter = chip.getAttribute("data-iter");
|
||||
if (loopId && lid && String(lid) !== loopId) return;
|
||||
if (chipIter == null) {{
|
||||
// No data-iter: leave alone (foreach uses BindRef chips; while may have one summary).
|
||||
return;
|
||||
}}
|
||||
// Chips with data-iter but no loop-id still filter by iter inside this ul.
|
||||
if (lid && loopId && String(lid) !== loopId) return;
|
||||
setFrameHidden(chip, String(chipIter) !== iter);
|
||||
}});
|
||||
recomputeAnnotOverflow(scope);
|
||||
initAnnotLeaders();
|
||||
}}
|
||||
if (sel.dataset.bound !== "1") {{
|
||||
sel.dataset.bound = "1";
|
||||
sel.addEventListener("change", apply);
|
||||
}}
|
||||
apply();
|
||||
}});
|
||||
}}
|
||||
|
||||
function ensureBlockLeaders(block) {{
|
||||
var leaders = block.querySelector(":scope > .annot-leaders");
|
||||
if (!leaders) {{
|
||||
leaders = document.createElement("div");
|
||||
leaders.className = "annot-leaders";
|
||||
leaders.setAttribute("aria-hidden", "true");
|
||||
block.insertBefore(leaders, block.firstChild);
|
||||
}}
|
||||
return leaders;
|
||||
}}
|
||||
|
||||
function leaderColor(kind) {{
|
||||
if (kind === "bind") return "#5ac8fa";
|
||||
if (kind === "return") return "#30d158";
|
||||
if (kind === "call" || kind === "expr" || kind === "code") return "#ff9f0a";
|
||||
if (kind === "branch") return "#bf5af2";
|
||||
if (kind === "loop") return "#64d2ff";
|
||||
return "#8e8e93";
|
||||
}}
|
||||
|
||||
function initAnnotLeaders() {{
|
||||
var bands = document.querySelectorAll("[data-annot-band]");
|
||||
if (!bands.length) return;
|
||||
var reduce = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
|
||||
var narrow = window.matchMedia && window.matchMedia("(max-width: 640px)").matches;
|
||||
|
||||
function layoutBand(band) {{
|
||||
var block = band.closest(".doc-block");
|
||||
if (!block) return;
|
||||
var leaders = ensureBlockLeaders(block);
|
||||
leaders.innerHTML = "";
|
||||
var chipsEl = band.querySelector(".annot-chips");
|
||||
var chips = Array.prototype.slice.call(
|
||||
band.querySelectorAll(".annot-chip:not(.annot-chip-overflow):not([hidden]):not(.is-frame-hidden)")
|
||||
);
|
||||
// Pair chips with anchors; reorder DOM left→right under underlines so
|
||||
// L-leaders do not cross (crowded reverse order looked like missing lines).
|
||||
var items = [];
|
||||
chips.forEach(function (chip) {{
|
||||
var id = chip.getAttribute("data-annot-id") || "";
|
||||
var kind = chip.getAttribute("data-annot-kind") || "";
|
||||
var anchor = id
|
||||
? (block.querySelector('.mq-anchor[data-annot-id="' + id + '"]')
|
||||
|| document.querySelector('.mq-anchor[data-annot-id="' + id + '"]'))
|
||||
: null;
|
||||
// Fallback: match mark kind on this block (frame chips may share a span).
|
||||
if (!anchor) {{
|
||||
var cls = kind === "bind" ? "mq-decl"
|
||||
: kind === "return" ? "mq-return"
|
||||
: (kind === "call" || kind === "expr" || kind === "code") ? "mq-code"
|
||||
: "";
|
||||
if (cls) anchor = block.querySelector(".mq-anchor." + cls);
|
||||
}}
|
||||
if (!anchor) return;
|
||||
if (id) anchor.setAttribute("data-annot-id", id);
|
||||
items.push({{
|
||||
chip: chip,
|
||||
anchor: anchor,
|
||||
kind: kind,
|
||||
x: anchor.getBoundingClientRect().left
|
||||
}});
|
||||
}});
|
||||
items.sort(function (a, b) {{ return a.x - b.x; }});
|
||||
if (chipsEl && items.length) {{
|
||||
items.forEach(function (it) {{ chipsEl.appendChild(it.chip); }});
|
||||
var more = band.querySelector("[data-annot-more]");
|
||||
if (more) chipsEl.appendChild(more);
|
||||
}}
|
||||
if (reduce || narrow || items.length > MAX_VISIBLE_ANNOTS) {{
|
||||
block.classList.add("is-keyed");
|
||||
band.classList.add("is-keyed");
|
||||
items.forEach(function (it, i) {{
|
||||
it.chip.setAttribute("data-annot-key", String(i + 1));
|
||||
}});
|
||||
return;
|
||||
}}
|
||||
block.classList.remove("is-keyed");
|
||||
band.classList.remove("is-keyed");
|
||||
// Mid-bottom of mark → mid-top of chip: vertical, horizontal rail, short stub.
|
||||
var blockRect = block.getBoundingClientRect();
|
||||
var bw = Math.max(1, block.offsetWidth);
|
||||
var bh = Math.max(1, block.offsetHeight);
|
||||
var svgNS = "http://www.w3.org/2000/svg";
|
||||
var svg = document.createElementNS(svgNS, "svg");
|
||||
svg.setAttribute("width", String(bw));
|
||||
svg.setAttribute("height", String(bh));
|
||||
svg.setAttribute("viewBox", "0 0 " + bw + " " + bh);
|
||||
svg.setAttribute("aria-hidden", "true");
|
||||
items.forEach(function (it) {{
|
||||
var a = it.anchor.getBoundingClientRect();
|
||||
var c = it.chip.getBoundingClientRect();
|
||||
var x0 = a.left + a.width / 2 - blockRect.left;
|
||||
var y0 = a.bottom - blockRect.top + 1;
|
||||
var x1 = c.left + c.width / 2 - blockRect.left;
|
||||
var y1 = c.top - blockRect.top;
|
||||
if (y1 < y0 + 8) {{
|
||||
y1 = y0 + 12;
|
||||
}}
|
||||
// Short stub into chip top-center; rail sits above that.
|
||||
var stub = Math.min(10, Math.max(6, (y1 - y0) * 0.28));
|
||||
var yRail = y1 - stub;
|
||||
if (yRail < y0 + 4) {{
|
||||
yRail = (y0 + y1) / 2;
|
||||
}}
|
||||
var path = document.createElementNS(svgNS, "path");
|
||||
path.setAttribute("class", "annot-leader annot-" + it.kind);
|
||||
path.setAttribute("stroke", leaderColor(it.kind));
|
||||
// Orthogonal: down from mark mid → across → short down to chip mid.
|
||||
path.setAttribute(
|
||||
"d",
|
||||
"M " + x0.toFixed(1) + " " + y0.toFixed(1) +
|
||||
" L " + x0.toFixed(1) + " " + yRail.toFixed(1) +
|
||||
" L " + x1.toFixed(1) + " " + yRail.toFixed(1) +
|
||||
" L " + x1.toFixed(1) + " " + y1.toFixed(1)
|
||||
);
|
||||
svg.appendChild(path);
|
||||
}});
|
||||
leaders.appendChild(svg);
|
||||
}}
|
||||
|
||||
function layoutAll() {{
|
||||
bands.forEach(layoutBand);
|
||||
}}
|
||||
layoutAll();
|
||||
// Second pass after fonts/layout settle (first paint often has zero chip width).
|
||||
requestAnimationFrame(function () {{ layoutAll(); }});
|
||||
if (document.documentElement.dataset.annotLeadersRo === "1") return;
|
||||
document.documentElement.dataset.annotLeadersRo = "1";
|
||||
if (typeof ResizeObserver !== "undefined") {{
|
||||
var ro = new ResizeObserver(function () {{ layoutAll(); }});
|
||||
bands.forEach(function (b) {{
|
||||
ro.observe(b);
|
||||
var blk = b.closest(".doc-block");
|
||||
if (blk) ro.observe(blk);
|
||||
}});
|
||||
var surface = document.querySelector(".document-surface");
|
||||
if (surface) ro.observe(surface);
|
||||
}}
|
||||
window.addEventListener("resize", layoutAll);
|
||||
|
||||
document.querySelectorAll("[data-annot-more]").forEach(function (btn) {{
|
||||
if (btn.dataset.bound === "1") return;
|
||||
btn.dataset.bound = "1";
|
||||
btn.addEventListener("click", function () {{
|
||||
var band = btn.closest("[data-annot-band]");
|
||||
if (!band) return;
|
||||
band.classList.add("is-expanded");
|
||||
btn.hidden = true;
|
||||
layoutAll();
|
||||
}});
|
||||
}});
|
||||
document.querySelectorAll(".annot-chip").forEach(function (chip) {{
|
||||
if (chip.dataset.focusBound === "1") return;
|
||||
chip.dataset.focusBound = "1";
|
||||
chip.addEventListener("mouseenter", function () {{
|
||||
var id = chip.getAttribute("data-annot-id");
|
||||
if (!id) return;
|
||||
var a = document.querySelector('.mq-anchor[data-annot-id="' + id + '"]');
|
||||
if (a) a.classList.add("is-focus");
|
||||
chip.classList.add("is-focus");
|
||||
}});
|
||||
chip.addEventListener("mouseleave", function () {{
|
||||
var id = chip.getAttribute("data-annot-id");
|
||||
if (!id) return;
|
||||
var a = document.querySelector('.mq-anchor[data-annot-id="' + id + '"]');
|
||||
if (a) a.classList.remove("is-focus");
|
||||
chip.classList.remove("is-focus");
|
||||
}});
|
||||
}});
|
||||
}}
|
||||
|
||||
if (document.readyState === "loading") {{
|
||||
document.addEventListener("DOMContentLoaded", function () {{
|
||||
initForeignCards();
|
||||
initOutlineSearch();
|
||||
initStreamPanel();
|
||||
initVarsPanel();
|
||||
initAnnotLeaders();
|
||||
initCallPickers();
|
||||
initLoopPickers();
|
||||
}});
|
||||
}} else {{
|
||||
initForeignCards();
|
||||
initOutlineSearch();
|
||||
initStreamPanel();
|
||||
initVarsPanel();
|
||||
initAnnotLeaders();
|
||||
initCallPickers();
|
||||
initLoopPickers();
|
||||
}}
|
||||
|
||||
function initOutlineSearch() {{
|
||||
@@ -2293,6 +2951,9 @@ pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkM
|
||||
.to_string(),
|
||||
_ => String::new(),
|
||||
};
|
||||
let trace_safe = vm
|
||||
.trace_json
|
||||
.replace("</", "<\\/");
|
||||
let main = format!(
|
||||
r#"
|
||||
<script>
|
||||
@@ -2300,6 +2961,7 @@ window.MARQDO_VIEW_LIVE = {live};
|
||||
window.MARQDO_FILE_PATH = {path_js};
|
||||
window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
</script>
|
||||
<script type="application/json" id="mq-view-trace">{trace}</script>
|
||||
<h1 class="page">{title}<span class="status-pill {status}">{status_label}</span></h1>
|
||||
<p class="meta">{rel}</p>
|
||||
<section class="block">
|
||||
@@ -2322,6 +2984,11 @@ window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
live = live_flag,
|
||||
path_js = escape_js_string(rel),
|
||||
auto_stream = if vm.auto_stream { "true" } else { "false" },
|
||||
trace = if trace_safe.is_empty() {
|
||||
"{}"
|
||||
} else {
|
||||
trace_safe.as_str()
|
||||
},
|
||||
title = escape(title),
|
||||
status = status,
|
||||
status_label = status_label,
|
||||
|
||||
+57
-13
@@ -1,8 +1,10 @@
|
||||
//! `marqdo view` — local HTML browser for `.mq.md` structure + output.
|
||||
//! `marqdo debug` — separate debugger host (tree-walk breakpoints).
|
||||
|
||||
mod annot;
|
||||
mod debug_api;
|
||||
mod debug_page;
|
||||
mod document;
|
||||
mod html;
|
||||
mod output;
|
||||
mod render;
|
||||
@@ -23,9 +25,10 @@ use tiny_http::{Header, Method, Request, Response, Server, StatusCode};
|
||||
use crate::input_feed::{effective_stdin, extract_frontmatter_stdin, split_stdin_text};
|
||||
use crate::view::debug_page::{build_debug_model, page_debug};
|
||||
use crate::view::html::{escape, page_file, page_index, LinkMode};
|
||||
use crate::view::annot::{build_view_annots, view_execution_report_json};
|
||||
use crate::view::render::{
|
||||
collect_input_prompts, render_bindings_html, render_module_structure, render_right_rail,
|
||||
uses_stream_panel, FileViewModel,
|
||||
collect_input_prompts, render_bindings_html, render_module_structure,
|
||||
render_module_structure_with_annots, render_right_rail, uses_stream_panel, FileViewModel,
|
||||
};
|
||||
use crate::{run_file_capture, RunOptions};
|
||||
|
||||
@@ -212,6 +215,24 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
|
||||
let json = files_json(&root.files);
|
||||
respond_json(request, json)
|
||||
}
|
||||
"/api/view-trace" => {
|
||||
let rel = query_param(query, "path").unwrap_or_default();
|
||||
if rel.is_empty() {
|
||||
return respond_json_status(
|
||||
request,
|
||||
StatusCode(400),
|
||||
serde_json::json!({ "ok": false, "error": "missing path" }).to_string(),
|
||||
);
|
||||
}
|
||||
let resolved = resolve_rel(root, &rel)?;
|
||||
let vm = build_file_view(root, &resolved, &rel, &[], true)?;
|
||||
let body = if vm.trace_json.is_empty() {
|
||||
serde_json::json!({ "version": 1, "path": rel, "ok": vm.ok, "calls": [], "events": [], "bindings_final": {} }).to_string()
|
||||
} else {
|
||||
vm.trace_json
|
||||
};
|
||||
respond_json(request, body)
|
||||
}
|
||||
"/api/events" => api_events(request),
|
||||
_ => {
|
||||
let resp = Response::from_string("not found").with_status_code(StatusCode(404));
|
||||
@@ -345,6 +366,7 @@ pub(crate) fn build_file_view(
|
||||
opts.sleep_limit_ms = if live { Some(30_000) } else { Some(0) };
|
||||
// Optional: sandbox to the whole view tree so sibling folders are reachable.
|
||||
opts.fs_root = Some(root.root.clone());
|
||||
let mut captured: Option<crate::capture::RunCapture> = None;
|
||||
let (stdout, stderr, ok, plots, mut bindings_html) = if awaiting_input || auto_stream {
|
||||
(
|
||||
String::new(),
|
||||
@@ -355,13 +377,13 @@ pub(crate) fn build_file_view(
|
||||
)
|
||||
} else {
|
||||
match run_file_capture(abs, &opts) {
|
||||
Ok(cap) => (
|
||||
cap.stdout,
|
||||
String::new(),
|
||||
true,
|
||||
cap.plots.into_iter().map(|p| p.svg).collect(),
|
||||
render_bindings_html(&cap.bindings),
|
||||
),
|
||||
Ok(cap) => {
|
||||
let stdout = cap.stdout.clone();
|
||||
let plots = cap.plots.iter().map(|p| p.svg.clone()).collect();
|
||||
let bindings_html = render_bindings_html(&cap.bindings);
|
||||
captured = Some(cap);
|
||||
(stdout, String::new(), true, plots, bindings_html)
|
||||
}
|
||||
Err(e) => (
|
||||
String::new(),
|
||||
tidy_user_error(&format!("{e:#}"), abs, rel),
|
||||
@@ -375,10 +397,14 @@ pub(crate) fn build_file_view(
|
||||
if !awaiting_input && !auto_stream {
|
||||
if let Ok(next) = fs::read_to_string(abs) {
|
||||
source = next;
|
||||
if let Ok(module) = crate::parse::parse_source(&source) {
|
||||
structure = render_module_structure(&module, &source);
|
||||
module_opt = Some(module);
|
||||
}
|
||||
}
|
||||
if let Ok(module) = crate::parse::parse_source(&source) {
|
||||
let annots = match &captured {
|
||||
Some(cap) => build_view_annots(&module, &source, cap),
|
||||
None => Vec::new(),
|
||||
};
|
||||
structure = render_module_structure_with_annots(&module, &source, &annots);
|
||||
module_opt = Some(module);
|
||||
}
|
||||
}
|
||||
let wb = crate::view::render::render_writeback_outline(&source);
|
||||
@@ -392,6 +418,10 @@ pub(crate) fn build_file_view(
|
||||
}
|
||||
}
|
||||
};
|
||||
let trace_json = match &captured {
|
||||
Some(cap) => view_execution_report_json(rel, ok, cap),
|
||||
None => String::new(),
|
||||
};
|
||||
Ok(FileViewModel {
|
||||
rel_path: rel.to_string(),
|
||||
source,
|
||||
@@ -407,6 +437,7 @@ pub(crate) fn build_file_view(
|
||||
show_stream,
|
||||
plots,
|
||||
bindings_html: std::mem::take(&mut bindings_html),
|
||||
trace_json,
|
||||
})
|
||||
}
|
||||
|
||||
@@ -641,6 +672,17 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> {
|
||||
// Keep the terminal frame small — tokens already streamed via bus.
|
||||
let preview: String = cap.stdout.chars().take(500).collect();
|
||||
let bindings_html = render_bindings_html(&cap.bindings);
|
||||
let source_now = fs::read_to_string(&abs).unwrap_or(source);
|
||||
let (structure_html, trace_json) = match crate::parse::parse_source(&source_now) {
|
||||
Ok(module) => {
|
||||
let annots = build_view_annots(&module, &source_now, &cap);
|
||||
(
|
||||
render_module_structure_with_annots(&module, &source_now, &annots),
|
||||
view_execution_report_json(&rel_clone, true, &cap),
|
||||
)
|
||||
}
|
||||
Err(_) => (String::new(), String::new()),
|
||||
};
|
||||
let done = serde_json::json!({
|
||||
"type": "done",
|
||||
"run_id": run_id,
|
||||
@@ -648,6 +690,8 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> {
|
||||
"ok": true,
|
||||
"result": preview,
|
||||
"bindings_html": bindings_html,
|
||||
"structure_html": structure_html,
|
||||
"trace_json": trace_json,
|
||||
});
|
||||
crate::host::event_bus::EventBus::global().publish_json(&done.to_string());
|
||||
}
|
||||
|
||||
+7
-1
@@ -32,11 +32,17 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
|
||||
vm.ok = true;
|
||||
vm.plots.clear();
|
||||
vm.bindings_html = String::from(r#"<p class="vars-skipped">skipped</p>"#);
|
||||
// Rebuild outline so Variables shows skipped.
|
||||
vm.trace_json.clear();
|
||||
// Rebuild outline + Structure without run annotations.
|
||||
if let Ok(module) = crate::parse::parse_source(&vm.source) {
|
||||
let wb = crate::view::render::render_writeback_outline(&vm.source);
|
||||
vm.outline_html =
|
||||
crate::view::render::render_right_rail(&module, &vm.bindings_html, &wb);
|
||||
vm.structure_html = crate::view::render::render_module_structure_with_annots(
|
||||
&module,
|
||||
&vm.source,
|
||||
&[],
|
||||
);
|
||||
}
|
||||
}
|
||||
let links = LinkMode::Static {
|
||||
|
||||
+185
-17
@@ -45,6 +45,8 @@ pub struct FileViewModel {
|
||||
pub plots: Vec<String>,
|
||||
/// HTML for Variables panel (entry bindings after run).
|
||||
pub bindings_html: String,
|
||||
/// ViewExecutionReport JSON for AI / call-picker (empty if no run).
|
||||
pub trace_json: String,
|
||||
}
|
||||
|
||||
/// Collect prompt strings from every `input` / `输入` call in the module (pre-order).
|
||||
@@ -187,14 +189,36 @@ fn prompt_expr_text(expr: &Expr) -> String {
|
||||
}
|
||||
}
|
||||
|
||||
/// Browse Structure without run annotations (empty callouts).
|
||||
pub fn render_module_structure(module: &Module, source: &str) -> String {
|
||||
render_module_structure_mode(module, source, StructureMode::Browse)
|
||||
}
|
||||
|
||||
/// Browse Structure: document surface with optional result annotations.
|
||||
pub fn render_module_structure_with_annots(
|
||||
module: &Module,
|
||||
source: &str,
|
||||
annots: &[crate::view::annot::ViewAnnot],
|
||||
) -> String {
|
||||
crate::view::document::render_module_document(module, source, annots)
|
||||
}
|
||||
|
||||
pub fn render_module_structure_mode(
|
||||
module: &Module,
|
||||
source: &str,
|
||||
mode: StructureMode,
|
||||
) -> String {
|
||||
match mode {
|
||||
StructureMode::Browse => render_module_structure_with_annots(module, source, &[]),
|
||||
StructureMode::Debug => render_module_structure_cards(module, source, mode),
|
||||
}
|
||||
}
|
||||
|
||||
/// Legacy AST-card Structure (debug + tests that need card markup).
|
||||
pub fn render_module_structure_cards(
|
||||
module: &Module,
|
||||
source: &str,
|
||||
mode: StructureMode,
|
||||
) -> String {
|
||||
let lines = classify_source(source);
|
||||
let writebacks = writeback::writeback_map(source);
|
||||
@@ -905,7 +929,7 @@ fn emit_comments(lines: &[ClassifiedLine], from_line: u32, before_line: u32) ->
|
||||
}
|
||||
|
||||
/// Render narrative comments as Markdown (links, emphasis, code, lists, …).
|
||||
fn comment_markdown_to_html(md: &str) -> String {
|
||||
pub(crate) fn comment_markdown_to_html(md: &str) -> String {
|
||||
let mut opts = Options::empty();
|
||||
opts.insert(Options::ENABLE_STRIKETHROUGH);
|
||||
opts.insert(Options::ENABLE_TABLES);
|
||||
@@ -947,10 +971,11 @@ fn render_fun(
|
||||
("chip", "explicit + param")
|
||||
};
|
||||
s.push_str(&format!(
|
||||
"<span class=\"{cls}\" title=\"{title}\">{name}</span>",
|
||||
"<span class=\"{cls}\" data-param-name=\"{name}\" data-fn=\"{fn}\" title=\"{title}\">{name}<span class=\"chip-val\"></span></span>",
|
||||
cls = cls,
|
||||
title = title,
|
||||
name = escape(&p.name),
|
||||
fn = escape(&fun.name),
|
||||
));
|
||||
}
|
||||
s.push_str("</div>");
|
||||
@@ -1045,17 +1070,89 @@ fn stmt_end_line(stmt: &Stmt) -> u32 {
|
||||
|
||||
fn output_card(line: u32, writebacks: &HashMap<u32, String>) -> String {
|
||||
match writebacks.get(&line) {
|
||||
Some(body) => {
|
||||
let badges = writeback_badges(body);
|
||||
format!(
|
||||
r#"<div class="card output-card" id="wb-{line}"><div class="wb-badges">{badges}</div><pre class="output-body">{}</pre></div>"#,
|
||||
escape(body)
|
||||
)
|
||||
}
|
||||
Some(body) => render_output_card(line, body),
|
||||
None => String::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Live view + static site: text `<pre>` and/or `<img>` for image writebacks.
|
||||
pub fn render_output_card(line: u32, combined: &str) -> String {
|
||||
if combined.trim().is_empty() {
|
||||
return String::new();
|
||||
}
|
||||
let badges = writeback_badges(combined);
|
||||
let mut body_html = String::new();
|
||||
let mut buf_text = String::new();
|
||||
let flush_text = |buf: &mut String, out: &mut String| {
|
||||
if buf.is_empty() {
|
||||
return;
|
||||
}
|
||||
out.push_str(&format!(
|
||||
r#"<pre class="output-body">{}</pre>"#,
|
||||
escape(buf.trim_end())
|
||||
));
|
||||
buf.clear();
|
||||
};
|
||||
for line_s in combined.lines() {
|
||||
let t = line_s.trim();
|
||||
if let Some(url) = extract_md_image_url(t) {
|
||||
flush_text(&mut buf_text, &mut body_html);
|
||||
body_html.push_str(&format!(
|
||||
r#"<figure class="wb-figure"><img class="wb-image" src="{src}" alt="writeback"/><figcaption class="wb-image-url">{cap}</figcaption></figure>"#,
|
||||
src = escape(&url),
|
||||
cap = escape(&url),
|
||||
));
|
||||
} else {
|
||||
if !buf_text.is_empty() {
|
||||
buf_text.push('\n');
|
||||
}
|
||||
buf_text.push_str(line_s);
|
||||
}
|
||||
}
|
||||
flush_text(&mut buf_text, &mut body_html);
|
||||
let has_img = body_html.contains("wb-image");
|
||||
format!(
|
||||
r#"<div class="card output-card{img_cls}" id="wb-{line}" data-wb="1"><div class="wb-badges">{badges}</div>{body}</div>"#,
|
||||
line = line,
|
||||
img_cls = if has_img { " output-card-image" } else { "" },
|
||||
badges = badges,
|
||||
body = body_html,
|
||||
)
|
||||
}
|
||||
|
||||
fn extract_md_image_url(line: &str) -> Option<String> {
|
||||
let t = line.trim();
|
||||
let rest = t.strip_prefix("?;
|
||||
let after = &rest[alt_end + 2..];
|
||||
let url_end = after.rfind(')')?;
|
||||
let url = after[..url_end].trim();
|
||||
if url.is_empty() {
|
||||
None
|
||||
} else {
|
||||
Some(url.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
/// Document-surface marker for a writeback source line (comment or image).
|
||||
pub fn render_writeback_source_line(line_no: u32, text: &str) -> String {
|
||||
let trimmed = text.trim();
|
||||
let is_image = trimmed.starts_with("![") && trimmed.contains("marqdo-out");
|
||||
let kind = if is_image { "image" } else { "comment" };
|
||||
let label = if is_image {
|
||||
"writeback · image"
|
||||
} else {
|
||||
"writeback"
|
||||
};
|
||||
format!(
|
||||
r#"<div class="doc-block doc-writeback" data-line="{line}" data-wb-kind="{kind}"><span class="wb-source-badge">{label}</span><code class="wb-source-text">{text}</code></div>"#,
|
||||
line = line_no,
|
||||
kind = kind,
|
||||
label = label,
|
||||
text = escape(trimmed),
|
||||
)
|
||||
}
|
||||
|
||||
fn writeback_badges(body: &str) -> String {
|
||||
let mut keys = Vec::new();
|
||||
for line in body.lines() {
|
||||
@@ -1162,12 +1259,14 @@ fn render_stmt(
|
||||
<span class="badge">code</span>
|
||||
<code class="expr">`{name}` =</code>
|
||||
<span class="code-lang">{lang}</span>
|
||||
</div>
|
||||
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
|
||||
<div class="code-foot">
|
||||
<div class="code-actions">
|
||||
<input type="text" class="code-cmd" placeholder="{placeholder}" spellcheck="false" autocomplete="off"/>
|
||||
<button type="button" class="code-run">Run</button>
|
||||
</div>
|
||||
</div>
|
||||
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
|
||||
<pre class="code-out" hidden></pre>
|
||||
</div>"#,
|
||||
lang = lang,
|
||||
@@ -1412,6 +1511,49 @@ fn expr_prec(expr: &Expr, parent_prec: u8) -> String {
|
||||
}
|
||||
|
||||
/// Best-effort ASCII formula → TeX for KaTeX in view Structure.
|
||||
pub(crate) fn formula_ascii_to_tex_pub(ascii: &str) -> String {
|
||||
formula_ascii_to_tex(ascii)
|
||||
}
|
||||
|
||||
/// Formula assign card for document surface embedding (single visual layer).
|
||||
pub(crate) fn render_formula_assign_card(name: &str, tex: &str) -> String {
|
||||
format!(
|
||||
r#"<div class="card formula-card" data-formula-name="{name}">
|
||||
<div class="formula-head"><span class="badge">formula</span> <span class="formula-name">{name}</span></div>
|
||||
<div class="math-block">$${tex}$$</div>
|
||||
</div>"#,
|
||||
name = escape(name),
|
||||
tex = escape(tex),
|
||||
)
|
||||
}
|
||||
|
||||
/// Foreign code assign card for document surface embedding (single visual layer).
|
||||
/// Head → body → foot(actions) so the source is never collapsed under the Run row.
|
||||
pub(crate) fn render_code_assign_card(name: &str, lang: &str, source: &str) -> String {
|
||||
let placeholder = escape(&crate::foreign::default_cmd_display(lang));
|
||||
format!(
|
||||
r#"<div class="card code-card" data-lang="{lang}" data-code-name="{name}">
|
||||
<div class="code-head">
|
||||
<span class="badge">code</span>
|
||||
<span class="code-name">{name}</span>
|
||||
<span class="code-lang">{lang}</span>
|
||||
</div>
|
||||
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
|
||||
<div class="code-foot">
|
||||
<div class="code-actions">
|
||||
<input type="text" class="code-cmd" placeholder="{placeholder}" spellcheck="false" autocomplete="off"/>
|
||||
<button type="button" class="code-run">Run</button>
|
||||
</div>
|
||||
</div>
|
||||
<pre class="code-out" hidden></pre>
|
||||
</div>"#,
|
||||
lang = escape(lang),
|
||||
name = escape(name),
|
||||
placeholder = placeholder,
|
||||
src = escape(source),
|
||||
)
|
||||
}
|
||||
|
||||
fn formula_ascii_to_tex(ascii: &str) -> String {
|
||||
let mut out = String::new();
|
||||
let chars: Vec<char> = ascii.chars().collect();
|
||||
@@ -1525,7 +1667,7 @@ mod tests {
|
||||
let src = include_str!("../../tests/structure/nested-call.mq.md");
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&module, src);
|
||||
assert!(html.contains("comment-card"));
|
||||
assert!(html.contains("doc-prose") || html.contains("打印一句问候"), "{html}");
|
||||
assert!(html.contains("print"));
|
||||
assert!(!html.contains("Binary {"));
|
||||
assert!(!html.contains("Literal(Int"));
|
||||
@@ -1536,9 +1678,9 @@ mod tests {
|
||||
let src = "段首说明\n续行仍属同段\n\n下一段\n\n# main\n\n> print text=x\n";
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&module, src);
|
||||
let cards = html.matches("comment-card").count();
|
||||
assert_eq!(cards, 2, "blank line should split comment paragraphs: {html}");
|
||||
assert!(html.contains("段首说明 续行仍属同段") || html.contains("段首说明</p>"));
|
||||
let blocks = html.matches("doc-prose").count();
|
||||
assert!(blocks >= 2, "blank line should split comment paragraphs: {html}");
|
||||
assert!(html.contains("段首说明 续行仍属同段") || html.contains("段首说明</p>") || html.contains("段首说明"));
|
||||
assert!(html.contains("下一段"));
|
||||
}
|
||||
|
||||
@@ -1575,11 +1717,10 @@ mod tests {
|
||||
let src = "---\ntitle: t\nimport text:lib/text.mq.md\n---\n\n# main\n\n> print text=hi\n";
|
||||
let local = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&local, src);
|
||||
assert!(html.contains("badge\">import"), "{html}");
|
||||
assert!(html.contains("doc-imports") || html.contains("lib/text.mq.md"), "{html}");
|
||||
assert!(html.contains("lib/text.mq.md"), "{html}");
|
||||
assert!(html.contains("main"), "{html}");
|
||||
assert!(!html.contains("trim"), "{html}");
|
||||
assert!(html.contains("class=\"stmt\""), "{html}");
|
||||
assert!(html.contains("data-line="), "{html}");
|
||||
assert_eq!(local.functions.len(), 1);
|
||||
assert_eq!(local.functions[0].name, "main");
|
||||
@@ -1624,9 +1765,21 @@ mod tests {
|
||||
let browse = render_module_structure_mode(&module, src, StructureMode::Browse);
|
||||
let debug = render_module_structure_mode(&module, src, StructureMode::Debug);
|
||||
assert!(browse.contains("id=\"fn-"), "{browse}");
|
||||
assert!(browse.contains("document-surface"), "{browse}");
|
||||
assert!(!browse.contains("bp-gutter"), "{browse}");
|
||||
assert!(debug.contains("bp-gutter"), "{debug}");
|
||||
assert!(debug.contains("id=\"stmt-"), "{debug}");
|
||||
assert!(debug.contains("card"), "{debug}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn browse_preserves_prose_unified_line() {
|
||||
let src = include_str!("../../tests/markup-v03/inc-prose.mq.md");
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&module, src);
|
||||
assert!(html.contains("对于输入变量"), "{html}");
|
||||
assert!(html.contains("mq-anchor"), "{html}");
|
||||
assert!(!html.contains("badge\">bind"), "{html}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -1663,6 +1816,20 @@ mod tests {
|
||||
assert!(html.contains(">xs<") || html.contains("vars-name\">xs"), "{html}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn output_card_renders_image_writeback() {
|
||||
let html = render_output_card(3, "[ok]\n");
|
||||
assert!(html.contains("output-card-image"), "{html}");
|
||||
assert!(html.contains(r#"src="plots/a.svg""#), "{html}");
|
||||
assert!(html.contains("wb-ok") || html.contains(">ok<"), "{html}");
|
||||
let text = render_output_card(1, "plain-42");
|
||||
assert!(text.contains("output-body"), "{text}");
|
||||
assert!(!text.contains("wb-image"), "{text}");
|
||||
let src = render_writeback_source_line(4, "");
|
||||
assert!(src.contains(r#"data-wb-kind="image""#), "{src}");
|
||||
assert!(src.contains("writeback · image"), "{src}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_marks_inferred_params() {
|
||||
let src = include_str!("../../tests/markup-v03/inc-prose.mq.md");
|
||||
@@ -1675,7 +1842,8 @@ mod tests {
|
||||
assert!(add.params.iter().any(|p| p.name == "n" && p.inferred));
|
||||
let html = render_module_structure(&module, src);
|
||||
assert!(
|
||||
html.contains("chip inferred") && html.contains(">n<"),
|
||||
html.contains("chip inferred")
|
||||
&& (html.contains(">n<") || html.contains(r#"data-param-name="n""#)),
|
||||
"expected inferred chip for n: {html}"
|
||||
);
|
||||
let outline = render_function_outline(&module);
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: agent / llm soft transport errors
|
||||
description: >-
|
||||
Regression (2026-10): unreachable OpenAI upstream must not abort the VM.
|
||||
`llm.ask` / `agent.step` / `agent.run` return structured status=error.
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> sys.env_set name="OPENAI_API_KEY" value="offline-transport-soft"
|
||||
> sys.env_set name="OPENAI_BASE_URL" value="http://127.0.0.1:9"
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=no-agent-plugin
|
||||
> sys.exit code=1
|
||||
|
||||
**model = > llm.llm**
|
||||
**ask = > model.ask prompt="ping soft transport"**
|
||||
**fin = > json.get value=`ask` key="finish"**
|
||||
**aerr = > json.get value=`ask` key="error"**
|
||||
1. `fin` == "error"
|
||||
1. `aerr`
|
||||
> print text=llm-ask-soft-ok
|
||||
2. *
|
||||
> print text=llm-ask-missing-error
|
||||
> print text=`ask`
|
||||
> sys.exit code=1
|
||||
2. *
|
||||
> print text=llm-ask-hard-or-ok-unexpected
|
||||
> print text=`ask`
|
||||
> sys.exit code=1
|
||||
|
||||
`tools` =
|
||||
|
||||
| 工具 |
|
||||
|------|
|
||||
|
||||
**ag = > agent.agent model=`model` tools=`tools` standing="transport soft probe"**
|
||||
**step = > `ag`.step task="unreachable upstream probe" writeback=False max_reads=1**
|
||||
**sst = > json.get value=`step` key="status"**
|
||||
**serr = > json.get value=`step` key="error"**
|
||||
1. `sst` == "error"
|
||||
1. `serr`
|
||||
> print text=agent-step-soft-ok
|
||||
2. *
|
||||
> print text=agent-step-missing-error
|
||||
> print text=`step`
|
||||
> sys.exit code=1
|
||||
2. *
|
||||
> print text=agent-step-unexpected
|
||||
> print text=`step`
|
||||
> sys.exit code=1
|
||||
|
||||
**out = > `ag`.run task="unreachable upstream probe" efi=False learn=False verify=False writeback=False reuse=False near_match=False max_rounds=1**
|
||||
**rst = > json.get value=`out` key="status"**
|
||||
**rerr = > json.get value=`out` key="error"**
|
||||
1. `rst` == "error"
|
||||
1. `rerr`
|
||||
> print text=agent-run-soft-ok
|
||||
2. *
|
||||
> print text=agent-run-missing-error
|
||||
> print text=`out`
|
||||
> sys.exit code=1
|
||||
2. *
|
||||
> print text=agent-run-unexpected
|
||||
> print text=`out`
|
||||
> sys.exit code=1
|
||||
|
||||
*"agent-llm-transport-soft-ok"*
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: agent.run cold OKF — resolve llm_free + self.preflight
|
||||
description: >-
|
||||
Regression for qdagent-facing bugs (2026-10):
|
||||
(A) miss resolve must expose llm_free=false;
|
||||
(B) `self`.preflight must resolve when agent is imported by a consumer.
|
||||
Offline — dummy API key; no live network required for assertions A/B.
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> sys.env_set name="OPENAI_API_KEY" value="offline-cold-efi-dummy"
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=no-agent-plugin
|
||||
> sys.exit code=1
|
||||
|
||||
**kb = ".marqdo/agent-kb-cold-efi"**
|
||||
**ex = > fs.exists path=`kb`**
|
||||
1. `ex`
|
||||
> fs.remove_tree path=`kb`
|
||||
2. *
|
||||
**_ = 1**
|
||||
> fs.make_dir path=`kb`
|
||||
|
||||
**resolved = > agent_resolve task="qdagent-cold-unknown-task-xyz-20261016" kb_dir=`kb`**
|
||||
**lf = > json.get value=`resolved` key="llm_free"**
|
||||
**mode = > json.get value=`resolved` key="mode"**
|
||||
1. `lf` == False
|
||||
> print text=resolve-miss-llm_free-ok
|
||||
2. *
|
||||
> print text=resolve-miss-llm_free-MISSING
|
||||
> print text=`resolved`
|
||||
> sys.exit code=1
|
||||
|
||||
1. `mode` == "unknown"
|
||||
> print text=resolve-miss-mode-ok
|
||||
2. *
|
||||
> print text=resolve-miss-mode-unexpected
|
||||
> sys.exit code=1
|
||||
|
||||
**model = > llm.llm**
|
||||
`tools` =
|
||||
|
||||
| 工具 |
|
||||
|------|
|
||||
|
||||
**ag = > agent.agent model=`model` tools=`tools` standing="cold efi preflight probe"**
|
||||
**pf = > `ag`.preflight task="qdagent-cold-unknown-task-xyz-20261016" marqdo_dir=".marqdo"**
|
||||
**st = > json.get value=`pf` key="status"**
|
||||
1. `st`
|
||||
> print text=self-preflight-ok
|
||||
> print text=`st`
|
||||
2. *
|
||||
> print text=self-preflight-failed
|
||||
> print text=`pf`
|
||||
> sys.exit code=1
|
||||
|
||||
**via = > `ag`.resolve task="qdagent-cold-unknown-task-xyz-20261016" kb_dir=`kb`**
|
||||
**via_lf = > json.get value=`via` key="llm_free"**
|
||||
1. `via_lf` == False
|
||||
> print text=method-resolve-llm_free-ok
|
||||
2. *
|
||||
> print text=method-resolve-llm_free-MISSING
|
||||
> sys.exit code=1
|
||||
|
||||
*"agent-run-cold-efi-ok"*
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: agent trial sandbox opt-in — host unchanged until commit
|
||||
description: >
|
||||
O1: agent.trial write stays upper until commit=True.
|
||||
Prefer link index over json.get.
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import sandbox:ext/ai/sandbox.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Reset leftover workspace from prior runs.
|
||||
|
||||
**had = fs.exists path="_sbx_optin"**
|
||||
1. `had`
|
||||
> fs.remove path="_sbx_optin"
|
||||
2. *
|
||||
**_ = 0**
|
||||
|
||||
> fs.make_dir path="_sbx_optin"
|
||||
|
||||
Trial with `commit=False`: upper write must not touch the host tree.
|
||||
|
||||
**dry = agent.trial root="_sbx_optin" write_path="proof.txt" text=optin-ok commit=False**
|
||||
**dry_ok = [ok](dry)**
|
||||
**dry_committed = [committed](dry)**
|
||||
> print text=`dry_ok`
|
||||
> print text=`dry_committed`
|
||||
|
||||
**before = fs.exists path="_sbx_optin/proof.txt"**
|
||||
> print text=`before`
|
||||
|
||||
Trial with `commit=True`: host sees the file after success.
|
||||
|
||||
**wet = agent.trial root="_sbx_optin" write_path="proof.txt" text=optin-ok commit=True**
|
||||
**wet_ok = [ok](wet)**
|
||||
**wet_committed = [committed](wet)**
|
||||
> print text=`wet_ok`
|
||||
> print text=`wet_committed`
|
||||
|
||||
**after = fs.read_text path="_sbx_optin/proof.txt"**
|
||||
> print text=`after`
|
||||
|
||||
Profile row is attached (link-index readable).
|
||||
|
||||
**prof = [profile](wet)**
|
||||
**pname = [name](prof)**
|
||||
> print text=`pname`
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: promote requires sandbox proof (O2)
|
||||
description: >
|
||||
Good workbook promotes; broken workbook is rejected (sandbox_proof_failed).
|
||||
Link-index reads; no json glue.
|
||||
import plugin:lib/plugin.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**p = plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=no-plugin
|
||||
> sys.exit code=1
|
||||
|
||||
**kb = "_sbx_promote_kb"**
|
||||
**had = fs.exists path=`kb`**
|
||||
1. `had`
|
||||
> fs.remove path=`kb`
|
||||
2. *
|
||||
**_ = 0**
|
||||
|
||||
**prom = agent_kb_promote kb_dir=`kb` goal="sandbox promote good" workbook="sandbox-fixtures/promote-good.mq.md"**
|
||||
**ok = [promoted](prom)**
|
||||
> print text=`ok`
|
||||
|
||||
**rej = agent_kb_promote kb_dir=`kb` goal="sandbox promote bad" workbook="sandbox-fixtures/promote-bad.mq.md"**
|
||||
**rej_ok = [promoted](rej)**
|
||||
**reason = [reason](rej)**
|
||||
> print text=`rej_ok`
|
||||
> print text=`reason`
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: O5 quarantine skill status
|
||||
description: Promote good skill then quarantine — status becomes quarantine.
|
||||
import plugin:lib/plugin.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**p = plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=no-plugin
|
||||
> sys.exit code=1
|
||||
|
||||
**kb = "_sbx_quar_kb"**
|
||||
**had = fs.exists path=`kb`**
|
||||
1. `had`
|
||||
> fs.remove path=`kb`
|
||||
2. *
|
||||
**_ = 0**
|
||||
|
||||
**prom = agent_kb_promote kb_dir=`kb` goal="quarantine demo" workbook="sandbox-fixtures/promote-good.mq.md"**
|
||||
**ok = [promoted](prom)**
|
||||
**slug = [slug](prom)**
|
||||
> print text=`ok`
|
||||
|
||||
**q = agent_kb_quarantine kb_dir=`kb` slug=`slug` reason="fixture_regression"**
|
||||
**qok = [ok](q)**
|
||||
**st = [status](q)**
|
||||
> print text=`qok`
|
||||
> print text=`st`
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: O3 step_route table backends
|
||||
description: lookup → marqdo; net → llm; default → auto.
|
||||
import agent:ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**a = agent.step_route kind="lookup"**
|
||||
**ba = [backend](a)**
|
||||
> print text=`ba`
|
||||
|
||||
**b = agent.step_route kind="net"**
|
||||
**bb = [backend](b)**
|
||||
> print text=`bb`
|
||||
|
||||
**c = agent.step_route kind="default"**
|
||||
**bc = [backend](c)**
|
||||
> print text=`bc`
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: sandbox CoW — write stays upper until commit
|
||||
description: >
|
||||
Readable trial: seed on disk, mutate in session, host tree unchanged,
|
||||
then commit / discard. Prefer link index over json.get.
|
||||
import sandbox:ext/ai/sandbox.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Prepare a tiny workspace under this test directory (reset leftovers from prior runs).
|
||||
|
||||
**had = fs.exists path="_sbx_cow"**
|
||||
1. `had`
|
||||
> fs.remove path="_sbx_cow"
|
||||
2. *
|
||||
**_ = 0**
|
||||
|
||||
> fs.make_dir path="_sbx_cow"
|
||||
> fs.write_text path="_sbx_cow/seed.txt" text=seed-lower
|
||||
|
||||
**sb = sandbox.open root="_sbx_cow"**
|
||||
**id = [id](sb)**
|
||||
|
||||
Session edits (upper / whiteout only).
|
||||
|
||||
> sandbox.write id=`id` path="seed.txt" text=seed-upper
|
||||
> sandbox.write id=`id` path="new.txt" text=brand-new
|
||||
> sandbox.remove id=`id` path="seed.txt"
|
||||
|
||||
**pending = sandbox.diff id=`id`**
|
||||
**n = len value=`pending`**
|
||||
> print text=`n`
|
||||
|
||||
Host tree must still show the lower seed; `new.txt` must not exist yet.
|
||||
|
||||
**lower = fs.read_text path="_sbx_cow/seed.txt"**
|
||||
> print text=`lower`
|
||||
**ex_new = fs.exists path="_sbx_cow/new.txt"**
|
||||
> print text=`ex_new`
|
||||
|
||||
Commit applies upper + whiteout.
|
||||
|
||||
> sandbox.commit id=`id`
|
||||
|
||||
**after = fs.read_text path="_sbx_cow/new.txt"**
|
||||
> print text=`after`
|
||||
**seed_gone = fs.exists path="_sbx_cow/seed.txt"**
|
||||
> print text=`seed_gone`
|
||||
|
||||
Discard must not touch the host.
|
||||
|
||||
**sb2 = sandbox.open root="_sbx_cow"**
|
||||
**id2 = [id](sb2)**
|
||||
> sandbox.write id=`id2` path="new.txt" text=should-discard
|
||||
> sandbox.discard id=`id2`
|
||||
|
||||
**kept = fs.read_text path="_sbx_cow/new.txt"**
|
||||
> print text=`kept`
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: sandbox.run — plugin.load denied; inspect lists notes
|
||||
description: >
|
||||
Guest that loads a native plugin must fail with unavailable in sandbox.
|
||||
No json.get chains — link index + a small expect table.
|
||||
import sandbox:ext/ai/sandbox.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**sb = sandbox.open root="sandbox-fixtures"**
|
||||
**id = [id](sb)**
|
||||
|
||||
**ret = sandbox.run id=`id` path="guest-plugin.mq.md"**
|
||||
**ok = [ok](ret)**
|
||||
**err = [error](ret)**
|
||||
> print text=`ok`
|
||||
|
||||
**parts = split value=`err` sep="unavailable in sandbox"**
|
||||
**hits = len value=`parts`**
|
||||
1. `hits` > 1
|
||||
> print text=deny-ok
|
||||
2. *
|
||||
> print text=`err`
|
||||
|
||||
**info = sandbox.inspect id=`id`**
|
||||
**notes = [notes](info)**
|
||||
**nn = len value=`notes`**
|
||||
1. `nn` > 0
|
||||
> print text=inspect-ok
|
||||
2. *
|
||||
> print text=inspect-missing
|
||||
|
||||
> sandbox.discard id=`id`
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**m = > json.parse text={"a":1}**
|
||||
**x = > json.get value=`m` key="a"**
|
||||
> print text=`x`
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
import plugin:lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
> plugin.load path=`p`
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: promote-bad
|
||||
proof: promote-bad.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> this_is_not_a_real_builtin_xyz
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: promote-ok
|
||||
type: skill
|
||||
applies_when: demo
|
||||
fixtures: promote-good.mq.md
|
||||
sandbox_profile: default
|
||||
proof: promote-good.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> print text=proof-ok
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: sandbox.run — core lib/json inside the trial
|
||||
description: Guest fixture imports lib/json; print ok and guest stdout via link index.
|
||||
import sandbox:ext/ai/sandbox.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Open a session on the fixture directory (guest programs live here).
|
||||
|
||||
**sb = sandbox.open root="sandbox-fixtures"**
|
||||
**id = [id](sb)**
|
||||
|
||||
Run the guest that imports `lib/json` and prints `1`.
|
||||
|
||||
**ret = sandbox.run id=`id` path="guest-json.mq.md"**
|
||||
**ok = [ok](ret)**
|
||||
**out = [stdout](ret)**
|
||||
> print text=`ok`
|
||||
> print text=`out`
|
||||
|
||||
> sandbox.discard id=`id`
|
||||
+113
@@ -2951,6 +2951,89 @@ fn ext_agent_zero_llm() {
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_ai_sandbox_cow() {
|
||||
ensure_agent_plugin_built();
|
||||
assert_out(
|
||||
"tests/ext/sandbox-cow.mq.md",
|
||||
"2
|
||||
seed-lower
|
||||
False
|
||||
brand-new
|
||||
False
|
||||
brand-new",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_ai_sandbox_run_lib() {
|
||||
ensure_agent_plugin_built();
|
||||
assert_out(
|
||||
"tests/ext/sandbox-run-lib.mq.md",
|
||||
"True
|
||||
1",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_ai_sandbox_deny() {
|
||||
ensure_agent_plugin_built();
|
||||
assert_out(
|
||||
"tests/ext/sandbox-deny.mq.md",
|
||||
"False
|
||||
deny-ok
|
||||
inspect-ok",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_ai_agent_sandbox_optin() {
|
||||
ensure_agent_plugin_built();
|
||||
assert_out(
|
||||
"tests/ext/agent-sandbox-optin.mq.md",
|
||||
"True
|
||||
False
|
||||
False
|
||||
True
|
||||
True
|
||||
optin-ok
|
||||
default",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_ai_agent_sandbox_promote() {
|
||||
ensure_agent_plugin_built();
|
||||
assert_out(
|
||||
"tests/ext/agent-sandbox-promote.mq.md",
|
||||
"True
|
||||
False
|
||||
sandbox_proof_failed",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_ai_agent_step_route() {
|
||||
ensure_agent_plugin_built();
|
||||
assert_out(
|
||||
"tests/ext/agent-step-route.mq.md",
|
||||
"marqdo
|
||||
llm
|
||||
auto",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_ai_agent_sandbox_quarantine() {
|
||||
ensure_agent_plugin_built();
|
||||
assert_out(
|
||||
"tests/ext/agent-sandbox-quarantine.mq.md",
|
||||
"True
|
||||
True
|
||||
quarantine",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_llm_named_offline() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
@@ -3365,3 +3448,33 @@ fn markup_v03_decl_ident_only() {
|
||||
fn markup_v03_bold_expr() {
|
||||
assert_out_v03("tests/markup-v03/bold-expr.mq.md", "42");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_formula_meta_var() {
|
||||
assert_out_v03("tests/markup-v03/formula-meta-var.mq.md", "x^2 - 2");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_inline_dollar_formula() {
|
||||
assert_out_v03("tests/markup-v03/inline-dollar-formula.mq.md", "x + 1");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_branch_arm_prose() {
|
||||
assert_out_v03("tests/markup-v03/branch-arm-prose.mq.md", "正");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_branch_cond_narrative() {
|
||||
assert_out_v03("tests/markup-v03/branch-cond-narrative.mq.md", "正");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_foreach_narrative() {
|
||||
assert_out_v03("tests/markup-v03/foreach-narrative.mq.md", "a\nb\n1\n2");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_foreach_nested_link() {
|
||||
assert_out_v03("tests/markup-v03/foreach-nested-link.mq.md", "x\ny");
|
||||
}
|
||||
@@ -17,6 +17,8 @@
|
||||
|
||||
代码即文档叙述面(G1–G4):`module-hr` / `soft-emphasis` / `float-discount` / `dynamic-footnote` —— 设计见 [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md)。
|
||||
|
||||
块公式 meta / 控制流叙述:`formula-meta-var` / `inline-dollar-formula` / `branch-arm-prose` / `branch-cond-narrative` / `foreach-narrative` / `foreach-nested-link` —— 见 [fence-meta-and-control-prose.md](../../doc/design/fence-meta-and-control-prose.md)。
|
||||
|
||||
```bash
|
||||
cargo test --test gold markup_v03
|
||||
marqdo run tests/markup-v03/inc-prose.mq.md
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: v0.3 分支臂内叙述
|
||||
description: 臂内 prose 不得逃逸;n>0 时仅 then
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**n = 1**
|
||||
|
||||
1. `n` > 0
|
||||
此时`n`为正,我们 **打印 内容="正"**
|
||||
2. *
|
||||
否则 **打印 内容="非正"**
|
||||
|
||||
*None*
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: v0.3 条件行夹叙述
|
||||
description: 当`n`大于 0 时 / 否则 *
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**n = 1**
|
||||
|
||||
1. 当`n`大于 0 时
|
||||
我们 **打印 内容="正"**
|
||||
2. 否则 *
|
||||
我们 **打印 内容="非正"**
|
||||
|
||||
*None*
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: v0.3 循环头叙述糖
|
||||
description: 对`xs`的每一项`项` / for each `item` in `ys`
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`xs` =
|
||||
|
||||
| v |
|
||||
|---|
|
||||
| a |
|
||||
| b |
|
||||
|
||||
- 对`xs`的每一项`项`
|
||||
**打印 内容=`项`**
|
||||
|
||||
`ys` =
|
||||
|
||||
| v |
|
||||
|---|
|
||||
| 1 |
|
||||
| 2 |
|
||||
|
||||
- for each `item` in `ys`
|
||||
**print text=`item`**
|
||||
|
||||
*None*
|
||||
Loaded 100 of 104 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user