Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
9ea5bebfc3 | ||
|
|
c7c329341b | ||
|
|
8cf5288481 | ||
|
|
69c4e74872 | ||
|
|
af0bda2e40 | ||
|
|
090b026547 | ||
|
|
03396afd02 | ||
|
|
663a8ba2c0 | ||
|
|
dc853fb580 | ||
|
|
0b80ff8e50 |
No files matched your search
@@ -28,6 +28,7 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg
|
||||
9. **Extension packs always publish to both** Cloudflare R2 (`https://ext.marqdo.com` via `scripts/upload-ext-r2.py`) **and** GitHub (Release assets / `ext-v*` tag). Credentials only in `~/.marqdo/r2.env` / CI — **never** commit. See [ext-cdn.md](../../../doc/design/ext-cdn.md).
|
||||
10. **CLI Ubuntu package = PPA** (`ppa:cflmy/marqdo`) via `./scripts/ppa-ship.sh` / `ppa-build-source.sh`. GitHub zips remain for Windows and non-apt Linux.
|
||||
11. **When a step needs the user** (sudo password, GPG passphrase, Launchpad UI, interactive `dput`): **stop, state what failed, and give the exact commands** to run in their terminal. Do not pretend the step succeeded.
|
||||
12. **GitHub auto-build must be green before declaring a release done.** For full/cli: wait for the tag-triggered **Release** workflow (`windows` + `linux`) **and** the push-triggered **`executable-knowledge`** workflow on the release commit / `main` tip. Release asset zips alone are **not** sufficient — a green Release job with a red EK gate is an incomplete release. Do not skip or reframe a red `executable-knowledge` as “assets already uploaded.”
|
||||
|
||||
## Release modes
|
||||
|
||||
@@ -78,6 +79,7 @@ Release progress:
|
||||
```
|
||||
|
||||
Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
|
||||
Also confirm the latest `main` **`executable-knowledge`** Actions run is green (or that this release commit will be covered after push) — do not proceed to tag if EK is already red on tip without a fix in the same release PR.
|
||||
|
||||
## Phase 2 — Docs & version bumps (main)
|
||||
|
||||
@@ -129,7 +131,9 @@ git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
|
||||
|
||||
## Phase 5 — GitHub Release notes & assets
|
||||
|
||||
1. Wait for Actions (full/cli): both `windows` and `linux` green when ext natives required.
|
||||
1. Wait for Actions (full/cli):
|
||||
- Tag **Release** workflow: both `windows` and `linux` green when ext natives required.
|
||||
- Push **`executable-knowledge`** workflow on the release commit / `main`: **must be success**. Poll with `gh run list --workflow=executable-knowledge.yml --branch main` / `gh run watch`. If EK is red → **stop**; fix plugin/harness on `main`, re-run; do **not** declare the release complete from assets alone.
|
||||
2. Rewrite release body 中英双语 — [reference.md § Notes](reference.md).
|
||||
3. Confirm Linux `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` when mode ships ext.
|
||||
|
||||
@@ -174,10 +178,11 @@ On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `
|
||||
## Phase 8 — Post-release
|
||||
|
||||
1. `gh release view TAG` — assets + notes.
|
||||
2. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
|
||||
3. PPA build green (if cli shipped).
|
||||
4. Tell user URLs: GitHub release, CDN, PPA install one-liner.
|
||||
5. Optional gh-pages only if asked.
|
||||
2. Confirm **`executable-knowledge`** and **Release** Actions are both green for this tag/commit; if either is red, say so and do not claim “发版完成”.
|
||||
3. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
|
||||
4. PPA build green (if cli shipped).
|
||||
5. Tell user URLs: GitHub release, CDN, PPA install one-liner.
|
||||
6. Optional gh-pages only if asked.
|
||||
|
||||
## Extension-only release (mode=ext)
|
||||
|
||||
@@ -194,7 +199,8 @@ On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `
|
||||
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; see [reference § Proxy](reference.md) |
|
||||
| GitHub blocked | proxy.cflmy.top, then HK jump; **print commands** if agent cannot push |
|
||||
| Tag exists | Stop; ask user |
|
||||
| CI red | Fix on main; retag only if user allows |
|
||||
| CI red (Release assets) | Fix on main; retag only if user allows |
|
||||
| `executable-knowledge` red | Fix agent plugin / test harness (e.g. `ensure_agent_plugin_built`); push `main`; wait for EK green. **Do not** treat uploaded Release zips as a successful release |
|
||||
| R2 upload fails | Print `upload-ext-r2.py` command; do not skip silently |
|
||||
| PPA / sudo / GPG | Print `./scripts/ppa-ship.sh noble` (or `dput …`); do not skip silently |
|
||||
| Launchpad `Cargo.lock` v4 / old cargo | Ensure bundled `third_party/rust` via current `ppa-build-source.sh`; bump `1ppaN` |
|
||||
|
||||
@@ -304,6 +304,15 @@ gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else f
|
||||
|
||||
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
|
||||
|
||||
**Also required before declaring release done:** the push-triggered **`executable-knowledge`** workflow on the release commit / `main` tip must be **success**. Poll with:
|
||||
|
||||
```bash
|
||||
gh run list --workflow=executable-knowledge.yml --branch main --limit 5
|
||||
gh run watch <run-id>
|
||||
```
|
||||
|
||||
A green Release asset job with a red `executable-knowledge` gate is an **incomplete** release — fix the plugin/harness (e.g. `ensure_agent_plugin_built` for agent-dependent EK tests), push `main`, and wait for EK green. Do not skip.
|
||||
|
||||
### HK SSH jump (Paramiko CONNECT)
|
||||
|
||||
**When to use:** local → GitHub fails (timeout / TLS / Clash flaky / reverse-proxy `proxy.cflmy.top` connect drops), but this host can reach an overseas box that has stable GitHub (default `hk.cflmy.de`). Proven path for v0.3.9 push/tag/`gh`.
|
||||
|
||||
@@ -14,68 +14,49 @@ description: >-
|
||||
|
||||
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): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
<!-- CORE_SYNTAX_V2.1: must stay at the top so skill_brief budgets never truncate it -->
|
||||
|
||||
**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/*`.
|
||||
## CORE SYNTAX (v2.1 Occlusion — mandatory)
|
||||
|
||||
**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.
|
||||
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
|
||||
|
||||
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
|
||||
2. **`**…**` = code / return expression.** `*…*` = statement (bind / expr). Closing markers touch the last token (no trailing space).
|
||||
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
|
||||
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
|
||||
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
|
||||
6. **Import / call:** frontmatter `import:` / `导入:`; call `lib.member`. One language (EN or ZH) per file.
|
||||
7. **Control flow:** `#` object/type, `##`+ function, `+` params, `1.`/`2.` branches, `-` loops, `N. *` else. No invented `if`/`for`/`def`/`return` keywords.
|
||||
8. **Prose vs code:** blank line separates comment paragraphs from executable lines.
|
||||
9. **GFM tables** for data; prefer `table.put` over `json.set` chains. `ext/**` never calls `host_*`.
|
||||
10. Body narrative `[描述](target)` is lazy (NarrativeRef) — reading does not execute side effects.
|
||||
|
||||
| Marker | Meaning (v2.1) |
|
||||
|--------|----------------|
|
||||
| `#` / `##`+ | Object/type · function/method |
|
||||
| `*…*` | Statement |
|
||||
| `**…**` | Return / code expression |
|
||||
| `[描述](payload)` | Occlusion step (payload executes) |
|
||||
| `access(c, k)` | Collection read |
|
||||
| `> fn …` | Call |
|
||||
| GFM table | Collection literal |
|
||||
|
||||
Canonical: `doc/design/core-surface.md`, `doc/design/document-native-development-guide.md`. Deeper tables: [reference.md](reference.md). Patterns: [examples.md](examples.md). Authoring craft: [marqdo-dev](../marqdo-dev/SKILL.md). Release: [marqdo-release](../marqdo-release/SKILL.md).
|
||||
|
||||
Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md).
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
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. Read collections with **`[key](map)`**, not footnote indexes for new code. In `markup: occlusion` files read with **`access(map, key)`** — there `[x](y)` is occlusion, not index. **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.
|
||||
1. Obey **CORE SYNTAX** above — Occlusion is default; do not emit Classic index links.
|
||||
2. **Identifiers:** params `` + `name` ``; inside `*…*` / `**…**` bare ids are variables. Quote text literals. Standalone `>` calls: backticks where bare would be text.
|
||||
3. **Structure lines** (`#` `>` `+` `-` `|`) are not wrapped in italics.
|
||||
4. **Paths:** bare `/` in expressions is division; in call args / table cells unspaced `a/b` is path text. Ratios as text need quotes (`"1/5"`).
|
||||
5. End side-effect-only helpers with `*None*` / `*空*` / `**` / `****` when the outer function continues. Lone `---` is a thematic break, not function end.
|
||||
6. **`ext/**` never calls `host_*`.** Prefer tables over `json.set` / `json.append`.
|
||||
7. **One language per file.** Sandbox trial before promoting Agent-generated trees.
|
||||
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
|
||||
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
|
||||
| `##` … `######` | **Function / method** (nesting by heading depth). |
|
||||
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter nested `import:` / `导入:` map | Import file (`bind: path.mq.md`) or short name (`bind: lib.member`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | 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 `access(coll, "key")` (legacy `` `m`[^key] `` remains available) |
|
||||
| `- [item](遍历 coll 为 item)` | Foreach |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
|
||||
## Occlusion syntax (v2.1.0+) · Executable knowledge (v2.1.1)
|
||||
|
||||
Occlusion is the default syntax. Shipped source declares `markup: occlusion` (or `标记: 遮蔽`) explicitly so imports stay deterministic. Legacy `[key](collection)` requires `markup: classic` or the one-cycle CLI flag `--legacy-markup`; `MARQDO_MARKUP` does not change parsing.
|
||||
|
||||
Executable-knowledge **S0 author baseline** (six tasks, offline gate): [`tests/executable_knowledge/`](../../../tests/executable_knowledge/README.md). Design goals ≠ shipped knowledge reuse — see [`doc/design/document-native-development-guide.md`](../../../doc/design/document-native-development-guide.md).
|
||||
|
||||
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
|
||||
- `[顾客留存率](0.42)` · `[总价](access(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
|
||||
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
|
||||
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
|
||||
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
|
||||
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --mark --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -11,6 +11,12 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Build agent + llm plugins (EK / workbench gates)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_agent --locked
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
- name: Workbench contracts (M00–M06 / F-subset)
|
||||
run: cargo test --test workbench_contracts --locked
|
||||
- name: Offline executable-knowledge gate
|
||||
run: cargo test --test executable_knowledge --locked
|
||||
- name: no ignored tests counted as success
|
||||
|
||||
@@ -126,9 +126,11 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v2.1.3**:知识工作台运行时——ModelSelection/RunContext/usage · view document 只读嵌入 · LLM selection/messages/cancel · agent selection e2e
|
||||
- **v2.1.3**: Workbench runtime — ModelSelection/RunContext/usage, view document read-only embed, LLM selection/messages/cancel, agent selection e2e
|
||||
- **v2.1.3 ext**:扩展包同步 2.1.3 / Ext pack 2.1.3
|
||||
- **v2.1.1**:可执行知识主链——BoundCall · NarrativeRef · 来源/适用期 · patch/extract · 整代 CURRENT + closure · 发票示例 113
|
||||
- **v2.1.1**: Executable-knowledge spine — BoundCall, NarrativeRef, sources, patch/extract, generation CURRENT + closure, invoice example 113
|
||||
- **v2.1.1 ext**:扩展包同步 2.1.1 / Ext pack 2.1.1
|
||||
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
|
||||
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
|
||||
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
|
||||
|
||||
@@ -1,5 +1,41 @@
|
||||
# Changelog
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
## v2.1.3 — 2026-10-25
|
||||
|
||||
### Highlights
|
||||
|
||||
**知识工作台运行时合同(M00–M06)**:`ModelSelectionV1` / `RunContextV1` / `ModelCallUsageV1` / `DocumentViewV1` / locator / snapshot;严格 selection;usage null≠0;`view document` 只读嵌入;LLM messages + cancel;agent.step selection 继承假模型 e2e;USTC 兼容 live smoke(env 注入)。CLI · wasm · ext **2.1.3**。设计证据仍为 Partial(原生适配器 unavailable;完整宿主 F12 留给应用)。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.3 && cargo build --release
|
||||
marqdo ext add llm # CDN / Releases → 2.1.3
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台合同与 View/LLM/Agent 扩展面,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **Workbench M00–M06**:capabilities / selection / RunContext / usage / DocumentView / locator / SnapshotManifest;`tests/workbench_contracts`(含 F02 agent.step+resume、F14 并发);`marqdo view document --out` 只读 HTML 嵌入。
|
||||
- **LLM**:`messages=` / `selection=` / `strict_selection`;cancel token;reasoning_content 回退;双端点隔离门禁。
|
||||
- **Live**:`tests/workbench_live`(`OPENAI_*` env only;`MARQDO_EXT` 指向仓内 `ext/`)。
|
||||
- **Agent skeleton**:子工作簿禁 `llm.llm`,从 env selection `llm.create`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`llm.ask` 升参**:hoist `p` 避免缺参 `missing argument for parameter p`;避免 `~/.marqdo/ext` 陈旧包遮蔽仓内 `ext/`(测试强制 `MARQDO_EXT`)。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.3**。
|
||||
|
||||
## v2.0.0 — 2026-10-22
|
||||
|
||||
### Highlights
|
||||
@@ -75,6 +111,41 @@ marqdo ext add web
|
||||
|
||||
### Changed
|
||||
|
||||
## v2.1.2 — 2026-10-24
|
||||
|
||||
### Highlights
|
||||
|
||||
**可执行知识生产消费链 + View 阅读体验发版门槛**:证据摘要进闭包/句柄;`artifact.verify` / `knowledge adjudicate` 结构化裁决;`artifact.reuse_execute` 与 `agent_eng_bind_execute` / `publish_gate` 实际复用(非 n-gram);`document.extract` 文本/Markdown + PDF/OCR 显式失败;View `KnowledgePresentation`、说明锚点、SSE `page_token` 过期包拒绝;上传 `max_bytes`;门禁 45 项(含 100/1000 单元)。CLI · wasm · ext **2.1.2**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.2 && cargo build --release
|
||||
marqdo ext add web
|
||||
cargo test --offline --locked --test executable_knowledge
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删关键词**——语义/MLSP/View/Agent 宿主扩展;不改变默认 Occlusion 链接读法与表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **证据与闭包(F0/M02)**:来源 digests 进入 artifact/evidence/closure;business handle 改/删来源失效;锚点/可读性诊断。
|
||||
- **验证裁决(F0/M03)**:`artifact.verify` 结构化 `may_bind` / `may_publish`;policy 枚举;`knowledge adjudicate`;CLI `--fail`。
|
||||
- **语法 Skill(F0/M05)**:CORE SYNTAX 置顶;`migration-classic.md`;`skill_core_card` 与预算截断防护。
|
||||
- **绑定执行(F1/M04)**:`artifact.reuse_execute`;`agent_eng_bind_execute` + `eng_publish_gate`(`candidate_only` / product gate);host_query `mlsp`;`tests/ext/agent-eng-bind-gate.mq.md`。
|
||||
- **发布与来源(F2/M06–M07)**:统一 `EXCLUDED_DIRS`;`publish_manifest.json`;`function_sources` 函数级来源覆盖。
|
||||
- **文档提取(F3/M01)**:`document.extract` DocumentSource→ExtractedDocument;PDF/DOCX/OCR 显式 `failed`;超限截断 `partial`;Web 上传 `MaxBytesReader` / `LimitReader`。
|
||||
- **View V0–V3(子集)**:正文优先;no-exec;`KnowledgePresentation`(`semantic_generation` / `page_token` / `local_deps`);SSE 过期包拒绝与帧选择保留;print/响应式;1000 单元 compile smoke。
|
||||
- **故事门禁(M08)**:建库→复用→来源变更失效→修复重绑。
|
||||
|
||||
### Fixed
|
||||
|
||||
- View 说明链接 raw-string 截断;skill_brief / CORE SYNTAX 预算不被冲突旧规则吃掉。
|
||||
- 上传体积限制在 multipart 解析前生效(不再只靠内存 form 预算)。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.2**。
|
||||
- `tests/executable_knowledge` 门禁扩至 45 项;README 切片进度表与发版子集对齐。
|
||||
|
||||
## v2.1.1 — 2026-10-23
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+16
-16
@@ -1,6 +1,6 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
version = 3
|
||||
|
||||
[[package]]
|
||||
name = "adler2"
|
||||
@@ -264,9 +264,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "crossbeam-utils"
|
||||
version = "0.8.21"
|
||||
version = "0.8.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
|
||||
checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
|
||||
|
||||
[[package]]
|
||||
name = "crypto-common"
|
||||
@@ -539,9 +539,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
||||
|
||||
[[package]]
|
||||
name = "js-sys"
|
||||
version = "0.3.104"
|
||||
version = "0.3.106"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
|
||||
checksum = "7883d941dae510fb2d978fc3fe018c71c9e2892fd38854de3e8b92c2e5ad9cc5"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"futures-util",
|
||||
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "2.1.1"
|
||||
version = "2.1.3"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -610,7 +610,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.1.1"
|
||||
version = "2.1.3"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -1290,9 +1290,9 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen"
|
||||
version = "0.2.127"
|
||||
version = "0.2.129"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
|
||||
checksum = "9bb54f33acc68fd454578d9820b0bde1a1a3d17aa17bb7b6595806d02886d409"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"once_cell",
|
||||
@@ -1303,9 +1303,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro"
|
||||
version = "0.2.127"
|
||||
version = "0.2.129"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
|
||||
checksum = "2e29d0c35b16e224a7eeb5cd2d25e3e1968fbd65604117b44d3b789d00ee8535"
|
||||
dependencies = [
|
||||
"quote",
|
||||
"wasm-bindgen-macro-support",
|
||||
@@ -1313,22 +1313,22 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro-support"
|
||||
version = "0.2.127"
|
||||
version = "0.2.129"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
|
||||
checksum = "6f501a8bc3719dba86ef8ae4728879c08001bea749eb1333ac5b91e040e2a6b7"
|
||||
dependencies = [
|
||||
"bumpalo",
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
"syn 3.0.3",
|
||||
"wasm-bindgen-shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-shared"
|
||||
version = "0.2.127"
|
||||
version = "0.2.129"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
|
||||
checksum = "23f0c9c52aa7cd7d77769a4cfe2a9adb1b331f489a41d912ce14513d5ab995c6"
|
||||
dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "2.1.1"
|
||||
version = "2.1.3"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
|
||||
@@ -281,9 +281,11 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v2.1.1)
|
||||
## 现状(v2.1.3)
|
||||
|
||||
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113` · 门禁 `tests/executable_knowledge`(含 100 单元)· 扩展包同步 **2.1.1**
|
||||
- **知识工作台运行时(v2.1.3)**:ModelSelection / RunContext / usage null≠0 · `view document` 只读嵌入 · LLM selection/messages/cancel · agent.step selection e2e · live smoke · 扩展包同步 **2.1.3**(设计 Partial:原生适配器 unavailable)
|
||||
- **可执行知识生产链(v2.1.2)**:证据/闭包失效 · `verify`/`adjudicate` · `reuse_execute` / `eng_bind_execute`+`publish_gate` · `document.extract` · View `KnowledgePresentation`+SSE `page_token` · 上传限流 · 门禁 45 项(100/1000 单元)
|
||||
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113`
|
||||
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock)
|
||||
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
|
||||
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
|
||||
@@ -320,7 +322,7 @@ marqdo catalog public -o .marqdo
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v2.1.1)
|
||||
### 如何使用最新 Marqdo(v2.1.3)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -335,7 +337,7 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v2.1.1 # 或留在 main
|
||||
git checkout v2.1.3 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -374,7 +376,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.1.1
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.1.3
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.1.1"
|
||||
version = "2.1.3"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+16
@@ -1,3 +1,19 @@
|
||||
marqdo (2.1.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.3: workbench M00–M06 runtime contracts (ModelSelection,
|
||||
RunContext, DocumentView, usage null≠0, LLM selection/cancel,
|
||||
agent.step selection e2e, view document CLI, live smoke).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 25 Oct 2026 15:20:00 +0000
|
||||
|
||||
marqdo (2.1.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.2: executable-knowledge F0–F3 + View V0–V3 release bar
|
||||
(evidence/closure, verify gates, bind/reuse_execute, document.extract,
|
||||
KnowledgePresentation, SSE page_token, upload max_bytes).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sat, 24 Oct 2026 14:50:00 +0000
|
||||
|
||||
marqdo (2.1.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.1: executable-knowledge spine (BoundCall, NarrativeRef,
|
||||
|
||||
@@ -19,6 +19,9 @@
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/qdagent-workbench-runtime-and-view-2026-10-25.md](design/qdagent-workbench-runtime-and-view-2026-10-25.md) | **qdagent 知识工作台框架支持**:M00–M05 合同落地中(`src/workbench/`、MLSP `capabilities` / `view.document` / `view.reference_resolve`、`tests/workbench_contracts.rs`);完整 verified 以切片验收证据为准 |
|
||||
| [design/view-knowledge-reading-experience-2026-10-24.md](design/view-knowledge-reading-experience-2026-10-24.md) | **View 知识阅读体验重设计(建议)**:正文优先、结构导航、就地知识说明、来源与运行状态、响应式线框、实现契约与验收;含当前呈现和 no-exec 反例 |
|
||||
| [roadmap/qdagent-knowledge-support-gaps-2026-10-24.md](roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) | **求道知识沉淀与文档编译支撑缺口**:2.1.1 源码复核、来源/依赖失效反例、验证与 Agent 协议、语法提示词、导入底座及跨库分工 |
|
||||
| [design/document-native-development-guide.md](design/document-native-development-guide.md) | **下一阶段开发指导**:语法审查裁决、正文→命名→复用工作流、AI 上下文与局部编辑、渐进严格、作者成本及 S0–S6 验收 |
|
||||
| [design/core-surface.md](design/core-surface.md) | **核心构造清单**:v2.1 默认链接/循环说明与构造守卫;不是全部实现状态清单 |
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **历史 v0.2 映射**:不再代表现行默认链接语义 |
|
||||
|
||||
@@ -0,0 +1,435 @@
|
||||
# qdagent 知识工作台所需的多模型运行与 View 嵌入支持
|
||||
|
||||
日期:2026-10-25。状态:Partial / in progress(M00–M06 合同门禁 + F02 agent.step/resume 假模型 e2e + USTC live selection smoke + DocumentView 浏览器只读核对已落地;F 矩阵未全绿,不得整文宣称 Verified;原生非兼容适配器仍 unavailable)。
|
||||
|
||||
源码基线:Marqdo `dc853fb`(2.1.2),qdagent `643dd31`,已同步远端。应用侧配套:[qdagent 多提供商与知识工作台](../../../qdagent/doc/design/multi-provider-and-knowledge-workbench-2026-10-25.md)。跨仓相对链接以兄弟仓库工作区布局为准。
|
||||
|
||||
沿用 [文档原生开发指导](document-native-development-guide.md)、[可执行知识规范](../next/Marqdo_Executable_Knowledge_Development.md) 与 [View 阅读体验设计](view-knowledge-reading-experience-2026-10-24.md)。本规格补充嵌入、调用身份和运行观测,不另造语言或第二套知识真相。
|
||||
|
||||
## 1. 框架目标与责任边界
|
||||
|
||||
让任何宿主应用可以按请求构造模型、追踪所有真实模型调用、以只读 View 展示知识文档,并从引用定位到版本一致的知识与来源。qdagent 的设置页、模型目录持久化、账单展示、会话导航、工作区授权和画像管理由应用实现。
|
||||
|
||||
| 能力 | Marqdo 拥有 | qdagent 拥有 |
|
||||
|---|---|---|
|
||||
| 多提供商 | 协议适配、模型 handle、能力协商、调用参数、归一化错误 | 提供商账户/端点/模型 CRUD、默认选择、凭证管理 |
|
||||
| 模型路由 | Runtime 执行显式选择和允许的辅助模型策略 | 用户选择、工作区模型允许列表、路由授权 |
|
||||
| 用量 | 每次请求/重试的身份、usage 来源与完整性、子任务传播 | 持久化账本、价格版本、费用估算、筛选/导出/预算策略 |
|
||||
| 实时运行 | 逐事件输出、取消传播、背压、终态 | HTTP 会话鉴权、轮次映射、持久化事件重放、断线 UX |
|
||||
| View | 文档语义、正文/目录/步骤、纯读取、稳定定位、可嵌入输出 | 容器/主题/深链/阅读历史/产品操作 |
|
||||
| 知识引用 | 解析/歧义/版本/来源定位、验证多维事实 | 消息引用标识、授权、历史资料保存与入口 |
|
||||
| 工作区 | 按显式 project 编译/查询,缓存及输出隔离 | 工作区 registry、root 解析、用户权限、文件管理 |
|
||||
| 画像与笔记 | 通用文档渲染、来源关联、验证/编译原语 | 内容策略、提案/确认、生命周期、展示和上下文选择 |
|
||||
|
||||
不在语言核心添加 provider/workspace/profile 关键字;沿用 `.mq.md` 函数、结构化参数、扩展插件和 MLSP。不得让“可读”取决于用户手填 hash、node id、source span 等机器字段。
|
||||
|
||||
## 2. 2.1.2 已完成的基础与剩余缺口
|
||||
|
||||
### 2.1 当前可复用基础
|
||||
|
||||
| 源码 | 已有内容 | 本规格的增量 |
|
||||
|---|---|---|
|
||||
| [ext/ai/llm](../../ext/ai/llm.mq.md) | `create(model,base_url,api_key,backend,name)`、命名 handle、ask/stream | 无需重做基础 handle;增加隔离策略、协议能力、完整消息与调用身份 |
|
||||
| [LLM plugin](../../plugins/llm/src/lib.rs) | 兼容 chat completions HTTP、SSE 文本读取、非流 usage 三项 | SSE usage/异常终态/每次调用观测、可取消持续输出 |
|
||||
| [Agent](../../ext/ai/agent.mq.md) | Agent 唯一 loop、router_model、EFI、绑定/发布门闩 | 主/路由/修复/生成工作簿的模型及计量上下文传播 |
|
||||
| [语义 IR](../../src/sema/ir.rs) | Artifact、KnowledgeStep、KnowledgeRef、SourceLocation、BoundCall | View 面向阅读的完整投影及 ID/版本映射 |
|
||||
| [MLSP](../../src/mlsp.rs) | `artifact.inspect`、`link.resolve`、verify/bind/execute、document.extract | 只读 document/引用解析及 capabilities 版本握手 |
|
||||
| [KnowledgePresentation](../../src/view/knowledge_present.rs) | schema v1,artifact nodes、依赖、generation/page token | 保留兼容,新增正文/目录/refs/source spans/结构化诊断 |
|
||||
| [View output](../../src/view/output.rs) | `--no-exec` 在构建前跳过 capture | 将纯读取能力暴露给嵌入客户端,不复用会执行的 live 默认路径 |
|
||||
| [document extract](../../src/document_extract.rs) | TXT/MD,partial,PDF/DOCX/OCR 显式不支持 | 能力查询及稳定来源定位;不要求本阶段重造 OCR |
|
||||
| [数据资源](../../ext/data/db.mq.md) | SQLite migrate/exec/事务、唯一/索引声明 | 应用可直接承载 registry/账本/索引;不需另加产品专用数据库框架 |
|
||||
|
||||
2.1.2 已把知识辅助块移到正文后并折叠,跳过 module/type 卡片,显示“结构步骤非实际执行时序”。旧 View 截图中的最初顺序问题已有改进;但这不意味着已提供能直接放进 qdagent 右栏的独立阅读 SDK。
|
||||
|
||||
### 2.2 直接影响集成的事实
|
||||
|
||||
1. `llm.complete_result` 当前仍走 `openai.chat_completions`,Ollama 也是兼容路径;`backend` 名称不是任意原生协议适配器。
|
||||
2. `plugins/llm::chat_completions` 从 `prompt` 构造一条 user 消息,没有完整消息列表契约;不能靠模型选择 UI 弥补历史丢失。
|
||||
3. `usage_from` 缺字段填零;Agent `model_turn(stream=True)` 直接 `tokens=0`,最终 `token_cost=tokens`。现有输出无法支撑准确货币或流式用量显示。
|
||||
4. 原生 LLM SSE parser 返回事件数组;`ext/ai` 有流事件机制,但应用所用 [web invoke](../../plugins/web/internal/httpx/routes_invoke.go) 在 `CallLibPath` 返回后才写 `{sse}`。需要打通实际增量路径,不能只换 Content-Type。
|
||||
5. Agent 生成子工作簿的模板仍能构造默认 `llm.llm`;只传主 agent handle 不足以证明嵌套调用沿用了用户选定模型。
|
||||
6. `build_file_view` 默认传 `execute=true`;live GET 路径使用它。嵌入阅读绝不能直接暴露这个入口。
|
||||
7. Presentation 目前按 artifacts 投影,缺全量 prose/heading/step/ref 的统一阅读树;`render_knowledge_html` 另从 steps/refs 渲染,容易与 JSON 事实发生覆盖差异。
|
||||
8. `source_digest` 当前由语义 artifact hashes 汇总,`semantic_generation` 是语义散列截短,`page_token` 来自原文件。它们不能直接分别冒充原文 revision、`.marqdo/CURRENT` generation 和跨请求完整版本。
|
||||
9. `sse_accepts_packet` 对缺 token 的 legacy 包放行;正式嵌入客户端必须采用严格版本匹配,而不是继承这项兼容宽容。
|
||||
10. `artifact.inspect/link.resolve` 每次走当前 semantic_project;现有入口不保证可以读任意历史 generation。历史引用需要明确的保留与解析合同。
|
||||
|
||||
## 3. 共用合同、版本与能力发现
|
||||
|
||||
合同名字固定为 `ModelSelectionV1`、`ModelCallUsageV1`、`RuntimeEventV1`、`DocumentViewV1`、`KnowledgeLocatorV1`;它们是这次扩展的 v1,与当前 KnowledgePresentation `schema_version:1` 不混用。新增 read model 不强行给已有 JSON 改含义。
|
||||
|
||||
新增 MLSP `capabilities`(拟议):
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"runtime_version": "implementation-version",
|
||||
"features": {
|
||||
"llm.explicit_selection": 1,
|
||||
"llm.call_usage": 1,
|
||||
"runtime.event_stream": 1,
|
||||
"runtime.cancel": 1,
|
||||
"view.document": 1,
|
||||
"view.reference_resolve": 1
|
||||
},
|
||||
"adapters": [{"id": "openai-compatible", "available": true}],
|
||||
"extract_formats": [{"format": "text", "available": true}],
|
||||
"loaded_plugins": [{"name": "llm", "capabilities": ["call_usage_v1"]}]
|
||||
}
|
||||
```
|
||||
|
||||
只返回实际探测且加载可用的功能。不能仅从 CLI 版本推断 native plugin 符号存在;字段未知时应用降级或解释不支持。协议允许新增可选字段;删除/改变状态语义必须提升 major contract version。能力查询不调用供应商、不执行项目代码。
|
||||
|
||||
MLSP 继续使用现有 `{id,ok,result|error}` envelope;qdagent `/api/app` 转为自己的 `{ok,schema_version,data|error}`,不要要求它们共享同一层 envelope。所有合同提供成功、partial、unknown、unsupported、stale、cancelled、错误 fixtures 与 JSON Schema;应用和框架从相同样本跑消费测试。
|
||||
|
||||
## 4. M01:请求级模型身份与适配器
|
||||
|
||||
### 4.1 显式选择合同
|
||||
|
||||
应用将配置解析成可信 `ModelSelectionV1` 后传入 runtime,核心字段:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"selection_id": "sel-1",
|
||||
"provider_id": "provider-1",
|
||||
"model_id": "model-2",
|
||||
"provider_revision": 3,
|
||||
"model_revision": 5,
|
||||
"adapter": "openai-compatible",
|
||||
"endpoint_ref": "endpoint-local-1",
|
||||
"credential_ref": "credential-local-1",
|
||||
"credential_version": 2,
|
||||
"upstream_model_id": "example-model",
|
||||
"parameters": {"max_output_tokens": 2048},
|
||||
"fallback_policy": "disabled"
|
||||
}
|
||||
```
|
||||
|
||||
endpoint/credential 引用由宿主 resolver 解析为调用局部配置;短期直接向现有 `llm.create` 传参数亦可,但这不是可序列化的 public snapshot。API key 不能出现在 events、debug JSON、生成工作簿、prompt、错误 URI 或持久化模型对象中。
|
||||
|
||||
当前显式 args 优先的能力保留;新增 strict selection 模式:字段缺失报错,不回退 process env/frontmatter。无凭证端点通过 `auth_mode:none` 显式表达,避免 falsy key 触发环境 fallback。legacy 命令行未传 selection 时仍可沿用原有 env 行为;本地便利兼容不扩散到应用请求。
|
||||
|
||||
每个运行绑定 selection snapshot,后续设置改变不修改它。主模型与 router_model 分开但同属受控 selection 集;manual 模式所有需要 LLM 的步骤固定选择,REUSE 无模型调用仍允许。fallback 必须由宿主明确授予、列出允许目标,不能因额度/网络错误静默转到另一个供应商。
|
||||
|
||||
### 4.2 子任务和工作簿传播
|
||||
|
||||
统一 `RunContextV1 = run_id,parent_run_id?,turn_id?,workspace_scope,selection_context,usage_sink,event_sink,cancellation_token`。进入 ask/step/plan、repair、summary、learn、子工作簿时显式继承;新 run/call id 关联父节点。
|
||||
|
||||
生成工作簿只包含不可重放滥用的运行上下文引用,不写密钥;执行时宿主注入/解析。独立导出工作簿在缺凭证/选择时清晰要求配置,不偷偷取默认模型。在任何 child/spawn/resume 路径遗漏 selection 都应由 strict 模式拒绝并给出定位诊断。
|
||||
|
||||
同时审查环境变量不只是凭证:project root、temp request、输出目录、event sink 也必须请求局部,不能在并发运行中依靠进程可变状态串联。
|
||||
|
||||
### 4.3 适配器与消息
|
||||
|
||||
适配器最小职责:验证 selection、报告能力、序列化请求、解析增量结果、usage 归一化、取消传输、错误归一化。可选 discovery/probe;无模型列表 API 仍允许手工配置。
|
||||
|
||||
V1 消息包含 role 和 content parts,parts 最低 text,附件通过受控引用;tool call/result 要保持配对及 role。不支持的 part/parameter 返回 `llm.unsupported_input/parameter`,不能悄悄转成空字符串。适配器决定协议格式,Agent 决定行为;qdagent 不拥有供应商协议代码。
|
||||
|
||||
阶段一验证两个不同兼容端点,分别至少两个模型,以及无密钥本地兼容服务。阶段二增加原生非兼容协议:每个适配器需具名能力、流式/非流式/错误/取消/usage fixtures 和独立接入说明后才能在 capabilities 中置 available。不能把所有厂商默认走兼容接口后统称全支持。
|
||||
|
||||
统一参数采用 `max_output_tokens,temperature?,stop?,reasoning?` 等语义键,能力不支持时明确拒绝;不随意透传客户端未知参数。实际 upstream model 若与请求 id 不同,在 result 中保留 requested/resolved 两者。供应商版本与价格随时变化,本文仅锁定内部合同;实施原生适配器时另附当时官方协议核验记录。
|
||||
|
||||
## 5. M02:用量、事件流与取消
|
||||
|
||||
### 5.1 ModelCallUsageV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"call_id": "call-1",
|
||||
"attempt_id": "attempt-1",
|
||||
"parent_call_id": null,
|
||||
"run_id": "run-1",
|
||||
"turn_id": "turn-1",
|
||||
"workspace_scope": "ws-1",
|
||||
"purpose": "answer",
|
||||
"selection_id": "sel-1",
|
||||
"provider_id": "provider-1",
|
||||
"model_id": "model-2",
|
||||
"requested_model": "example-model",
|
||||
"resolved_model": "example-model",
|
||||
"status": "succeeded",
|
||||
"usage_state": "final",
|
||||
"measurement_source": "provider",
|
||||
"input_tokens": 1200,
|
||||
"output_tokens": 300,
|
||||
"total_tokens": 1500,
|
||||
"cached_input_tokens": 800,
|
||||
"reasoning_output_tokens": null,
|
||||
"revision": 2,
|
||||
"provider_request_id": "opaque-provider-id",
|
||||
"started_at": "2026-10-25T01:00:00Z",
|
||||
"finished_at": "2026-10-25T01:00:03Z"
|
||||
}
|
||||
```
|
||||
|
||||
字段要求:tokens 非负整数或 null;`usage_state = pending|partial|final|unknown`;`measurement_source = provider|estimated|none`。估算可作为单独 estimate 字段返回,不能覆盖实测字段。供应商没有报告时用 null/unknown,传输失败不能自动解释成零消耗。
|
||||
|
||||
`status = started|succeeded|failed|cancelled|interrupted`,status 和 usage_state 独立。每个真实发出的 HTTP attempt 一个唯一 id;预检拒绝只产生 call-rejected 事件,不伪造已发送请求。框架重试必须可观测:所有 attempts 包括失败/有部分输出的 attempt;重复 delivery 的 usage revision 不算新请求。
|
||||
|
||||
累计 SSE usage 在同 attempt 内按 revision 发布完整快照,不让上层猜是 delta 还是 total。provider 总量与 input/output 不一致时保留原始读数及 `usage.inconsistent` 诊断,不自行强制改账;细分字段要标 inclusion 关系以避免缓存、reasoning 与总量重复相加。只保留脱敏的必要 provider usage 扩展字段,不把完整原始响应当 public usage。
|
||||
|
||||
纯知识复用用 run summary 中 `llm_calls=0`、`measurement_source=none` 表示,而不是伪造一条耗费为零的模型请求。框架输出 `call_count,known_tokens,unknown_call_count`,宿主据此显示覆盖程度。
|
||||
|
||||
### 5.2 事件流合同
|
||||
|
||||
```text
|
||||
run.started
|
||||
→ model.resolved
|
||||
→ model.call.started
|
||||
→ message.delta / tool.progress / usage.updated(零到多次)
|
||||
→ model.call.finished(每个 attempt 各一条)
|
||||
→ document.produced / citation.produced(仅有真实对象时)
|
||||
→ run.completed | run.failed | run.cancelled | run.interrupted
|
||||
```
|
||||
|
||||
`RuntimeEventV1` 公共字段:`schema_version,event_id,seq,run_id,parent_run_id?,turn_id?,workspace_scope,timestamp,type,payload`。seq 每个 run 单调;不同子 run 可以并发,宿主按所属 turn 另分配产品流序号。runtime terminal 事件仅一次;后续补全计量用有 revision 的 `usage.updated`,不能改变内容终态。
|
||||
|
||||
事件 sink 支持有界队列和背压;慢客户端不能无限堆积 token。丢弃可合并 progress 时记录 gap;内容与终态事件不可无声丢失。连接终止不会自动重跑;持久化/重放由应用,但框架需在实时回调后仍提供可核对的 final result/call summaries。
|
||||
|
||||
同一真实调用所有数据使用同一 run/call identity,不能流与最终结果各生成一套 id。工具参数/结果按 policy 脱敏,不把 secret、完整私有文件、模型内部推理链写入默认进度事件。
|
||||
|
||||
### 5.3 打通传输而不重造 Agent
|
||||
|
||||
需要同时打通 LLM provider reader → Agent event sink → host callback → web streaming handler → 浏览器。现有 `sys.stream_publish` 可以作为底座,但要验证它是否绑定正确请求且在 `CallLibPath` 返回前可写出;不能用进程全局事件广播混流。
|
||||
|
||||
可实施路径:新增 web 流式 invoke/job primitive,由框架注册 run handle 和 event sink;调用返回 handle 后宿主可订阅/取消。采用插件 ABI 增量接口及能力检测,旧 ABI 未支持时拒绝新 streaming 模式,保留旧完整返回。qdagent 只挂产品鉴权、event id 持久化和 HTTP 端点,不添加另一个推理循环。
|
||||
|
||||
SSE parser 必须处理任意 TCP 分块、UTF-8 跨块、CRLF、多行 data、注释 heartbeat、尾帧、usage-only 帧、[DONE]、连接在结束前关闭。未知可选事件可忽略且记诊断;已知事件无效、异常截断不能静默当成功完成。公共 framing 不包含供应商私有认证信息。
|
||||
|
||||
### 5.4 取消与重试
|
||||
|
||||
取消 token 传到 HTTP reader、循环、工具边界、子任务。取消后不得启动新模型调用/新工具;正在进行的不可抢占操作返回 `cancelling` 和是否仍运行,结束后才报告 cancelled。明确“停止生成”不能撤销已经完成的外部写入。
|
||||
|
||||
调用超时、连接错误、鉴权失败、限流、协议错误分开;错误字段包含 `code,retryable,retry_after_ms?,call_id,attempt_id,usage_state`。不要将原始包含密钥/完整 prompt 的错误直接传到 UI。限流/短暂网络错误按有界策略重试;已产生输出的重试不能接在同一条文字后假装连续,也不能把未知结果的外部工具操作自动重做。
|
||||
|
||||
费用价格由应用管理。框架保留 legacy `tokens/token_cost` 并标注 deprecated/单位为 token,新功能只消费 ModelCallUsageV1,避免破坏旧脚本的同时停止误用。
|
||||
|
||||
## 6. M03:无执行的嵌入式 View
|
||||
|
||||
### 6.1 新入口与纯度约束
|
||||
|
||||
新增内部公共服务 `analyze_document → project_read_model → render_fragment`;MLSP 暴露 `view.document`,可选 CLI `view document --json --no-exec` 与它共享实现。不要让新入口先进入 `build_file_view` 再隐藏按钮/清空输出。
|
||||
|
||||
读取允许:授权范围内原文/已编译快照/已有验证记录。读取禁止:运行模块入口、加载文档声明插件、执行外国代码、LLM、自动抓取 URL、写回、重新验证执行测试、隐式发布/重编译写盘。静态分析/内存投影允许;缺完整依赖时明确 partial。任何需要执行的行为必须另走显式 execute/verify 产品流程。
|
||||
|
||||
当前 `compile_project` 声明不加载插件/不求值/不抓取来源,可复用;缓存写入若需要,作为单独的宿主管理路径,不能把“读文档”隐含写项目目录。
|
||||
|
||||
### 6.2 DocumentViewV1 结构
|
||||
|
||||
请求由宿主传入受控 project 和文档定位,宿主必须已授权;框架仍做路径边界校验。
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "view.document",
|
||||
"params": {
|
||||
"project": "/authorized/project",
|
||||
"document": "knowledge/example.mq.md",
|
||||
"revision": "sha256:requested-source",
|
||||
"generation": "generation-id-or-null",
|
||||
"mode": "read",
|
||||
"node_id": "optional-node",
|
||||
"include": ["fragment", "outline", "nodes", "refs", "diagnostics"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "DocumentViewV1",
|
||||
"schema_version": 1,
|
||||
"document": {
|
||||
"id": "project-relative-document-id",
|
||||
"title": "知识标题",
|
||||
"source_revision": "sha256:raw-bytes-digest",
|
||||
"semantic_digest": "sha256:semantic-facts",
|
||||
"generation_id": null,
|
||||
"presentation_token": "opaque-token"
|
||||
},
|
||||
"execution": {"state": "not_run", "run_id": null},
|
||||
"render": {"format": "sanitized_html", "fragment": "<article class=\"mq-document\">…</article>", "renderer_version": "1"},
|
||||
"outline": [],
|
||||
"nodes": [],
|
||||
"refs": [],
|
||||
"diagnostics": [],
|
||||
"completeness": "complete",
|
||||
"capabilities": {"read_only": true, "has_semantics": true}
|
||||
}
|
||||
```
|
||||
|
||||
`generation_id` 来自实际编译投影;即时分析但未编译发布时为 null,同时给 semantic_digest。`source_revision` 是原始文件字节摘要,不能复用当前基于 artifacts 的 `source_digest`;`presentation_token` 覆盖 source revision、generation/semantic digest、依赖版本、renderer/schema、读取策略与请求范围。应用缓存还必须含用户授权范围。
|
||||
|
||||
`completeness = complete|partial`;语法损坏时允许返回原文与结构化诊断,但不能展示猜测出来的正常知识图。失败用 error envelope,不能空字符串伪装“文档无内容”。大文档 response 支持 section cursor 和 truncated 标识,限制要可配置并在响应中标明。
|
||||
|
||||
### 6.3 统一正文、目录、节点与引用
|
||||
|
||||
节点包含 `id,parent_id,kind,label,order,source_span,artifact_id?,ref_ids[],children[]`。kind 包括 heading/prose/table/code/observe/derive/call/iterate/narrate/navigation;正文树来自 parser/classifier/sema 的共同投影,不能只枚举 functions 后把每个步骤标 call。
|
||||
|
||||
outline 描述读者文档层级,不简单把函数和对象全铺成同一级。HTML 中节点带 `data-mq-node`,引用带 `data-mq-ref`;实现 payload 按需展开,说明作为正文。动态调用/无法解析引用保持原文并解释原因,不虚构执行边。
|
||||
|
||||
首批 renderer 共享 `src/view/document.rs` 的文档表面,standalone/full page 和嵌入模式调用同一 read model;只改变容器和导航外观,不产生第二种语义解释。替换当前 `KnowledgePresentation` 与 `render_knowledge_html` 双路径重复组装。
|
||||
|
||||
稳定 ID 的保证范围要写明:
|
||||
|
||||
- 同一 revision 再次读取,node/ref id 必须相同。
|
||||
- 仅前插空行/叙述时,已有命名符号保持 symbol id;步骤 id 由结构身份映射,不能只靠行号。
|
||||
- 同一行多个节点需要 column/offset/span 区分,不能都映射成 `stmt-N`。
|
||||
- 匿名步骤重排/重复同名内容可能无法唯一映射;返回 unmapped/ambiguous,不能声称任意编辑下永恒稳定。
|
||||
- source span 明确 1-based line/column 和 UTF-8 byte offset;JavaScript UTF-16 偏移不直接当 Rust 字节偏移。
|
||||
|
||||
旧 `#stmt-{line}` 可保留为当前版本兼容锚点,但不得作为跨版本唯一身份。
|
||||
|
||||
### 6.4 嵌入渲染、主题与访问性
|
||||
|
||||
fragment 不包含 html/body、应用导航、运行按钮、内联可执行 script、全局 CSS;CSS 以 `.mq-document` namespace 限定。主题暴露 `--mq-bg/surface/text/muted/border/accent/font-body/font-code`,宿主映射自己的设计 tokens;不把独立 View 的全局 `*`/body 样式注入 qdagent。
|
||||
|
||||
首批推荐 fragment + 结构化引用 + 宿主事件代理;无需为 iframe 和 React 各重做 parser。可选 iframe embedded shell 必须只读、无重复导航,宿主/子页通信校验 origin/source/nonce/schema,仅允许 open-reference/selection/ready 等已定义消息,不能从内容发任意运行指令。
|
||||
|
||||
所有文本/属性转义,允许的 Markdown HTML 白名单净化;链接 scheme 限制;外部资源不默认跨网加载;代码/公式不得执行。静态导出、独立页面、嵌入三者都测试恶意文本/闭合标签/危险 URL。不要把 KnowledgePresentation 内 JSON 的转义当作所有正文 XSS 防护。
|
||||
|
||||
标题/列表/表格用语义 HTML;说明链接有可访问名称,焦点可见,视觉排序和键盘顺序一致。折叠只隐藏技术细节,不隐藏理解结论所需的正文。320–720px 容器宽、暗色、200% 缩放和 print 都要能读,不出现遮住正文的关系连线。无 JS 时仍能读正文和普通链接。
|
||||
|
||||
## 7. M04:知识、来源与历史引用定位
|
||||
|
||||
### 7.1 KnowledgeLocatorV1
|
||||
|
||||
统一 locator:`project_id,document_id,source_revision,generation_id?,artifact_id?,node_id?,source_ref_id?,span?,relation`。relation 区分 cites/supports/derived_from/executes。普通链接导航、NarrativeRef 和 BoundCall 都能定位,但语义不同;点击说明永不成为 BoundCall 的执行。
|
||||
|
||||
新增 `view.reference_resolve`:接受 locator 或当前文档 ref_id,返回 `resolution = resolved|stale|unresolved|ambiguous|version_unavailable|unsupported`、目标 locator、候选(若有)、定位精度、诊断、读者标签。框架内部路径不作为浏览器 href,应用根据授权映射为 document/source route。
|
||||
|
||||
扩展 `artifact.inspect` 的版本参数,旧无版本调用仍查当前;新调用带 expected source/generation mismatch 时不能自动降到当前。来源读取接口可由宿主取实际文件,再调用框架 locator 映射;框架不自动 fetch 外部网页。`mq://` 必须按框架规则解析,不能交给浏览器或把 URI 直接当文件路径。
|
||||
|
||||
### 7.2 历史版本与保留责任
|
||||
|
||||
生成 artifact/generation 元数据不等于保存了原文历史。框架须输出可保存的 snapshot manifest:原文 revision、依赖 revision、source refs、artifact hashes、renderer/schema version;应用决定哪些源版本随引用保留及保留周期。已有 Git 或内容寻址存储可提供 snapshot resolver;不强制应用部署 Git。
|
||||
|
||||
source revision 定位到存储快照后,框架基于该快照解析;缺失任何必要版本时返回 version_unavailable/partial,不读取最新文件填充旧快照。如果只留 artifact 元数据、原始资料已删除,仍可展示历史元数据但明确“原文不可读取”。
|
||||
|
||||
知识改名、移动或 source anchor 改变可返回候选映射,只有唯一可靠匹配才自动导航;否则用户选择最新版/候选。保持旧引用与新引用两个对象,防止历史回答证据在后台悄悄改变。
|
||||
|
||||
### 7.3 验证和运行事实
|
||||
|
||||
节点详情至少携带 purpose/description、signature、applicability、provenance、effects、dependencies,以及 parse/resolve/contract/tests/evidence/execution 各自状态与记录来源。sourced 只能说“已关联来源”;static verify 成功不表示执行成功或适用业务正确。
|
||||
|
||||
真实执行证据独立结构 `run_id,artifact_digest,closure_digest,source_revision,generation_id,inputs_digest,executed_at,result_state,evidence_ref`,展示时匹配版本。旧运行结果不涂成当前文档的绿色通过。知识复用必须存在实际 bind/execute trace,不能凭 find 命中显示“已执行”。
|
||||
|
||||
View 不运行验证测试以填满状态。若用户点“验证”,应用走已有 verify/policy 门禁并记录新 evidence,之后读取才刷新详情。
|
||||
|
||||
### 7.4 错误与授权协作
|
||||
|
||||
| 内部结果 | 应用建议呈现 | 不能做 |
|
||||
|---|---|---|
|
||||
| unresolved | 无法定位该知识,可读原引用 | 跳转到第一个同名 artifact |
|
||||
| ambiguous | 显示已授权候选和位置 | 自动选择或暴露不可见候选 |
|
||||
| stale | 该知识/来源已变化,提供版本选择 | 静默替换旧引用 |
|
||||
| version_unavailable | 回答所用版本不可用,可查看最新版 | 用最新版伪装历史证据 |
|
||||
| partial | 部分依赖或来源缺失,说明范围 | 默认绿色通过 |
|
||||
| permission denied(应用) | 无权访问 | 在错误中泄漏标题、路径、片段 |
|
||||
|
||||
用户权限归应用;框架服务在调用边界接受 scoped project/source resolver,不把传来一个 root 视为可遍历整个服务器。所有路径经过 canonicalize/symlink 检查;缓存的语义事实可共享,带原文的响应必须按权限复核,不能只靠 artifact id 缓存授权。
|
||||
|
||||
## 8. M05:工作区、笔记与导入所需的通用底座
|
||||
|
||||
不为 qdagent 画像加语言特殊节点。通用能力应支持普通文档元信息读取、来源范围、内容修订、diff/patch 的 expected digest、提取格式 capability。
|
||||
|
||||
document.extract 继续使用 DocumentSource→ExtractedDocument,报告 format/status/segments/source locator/diagnostics。TXT/MD 可支持;PDF/DOCX/OCR 没有适配器时明确 unsupported/failed,不能将空文本当成功。partial 保留已提取片段及原文范围、遗漏原因;发布政策由应用决定。
|
||||
|
||||
同一资料可产生多个知识单元,provenance 必须到具体片段,不能所有函数只指向文件根。原始资料 digest 改动的失效由现有 provenance/closure 保证;应用用户画像也可用普通来源引用,但不自动进入公共知识发布。
|
||||
|
||||
ProjectRoot/CompileOptions 显式传递,工作区 A/B 的 source id、输出 generation、缓存、临时目录必须隔离。避免每读一个节点就全项目编译:引入按 project snapshot 复用的分析服务,针对来源/依赖变化失效;并发同 snapshot 请求合并,不能分别写同一个 CURRENT。
|
||||
|
||||
上传 multipart/大小限制已有 web 底座,框架只提供安全提取和可消费结果;浏览器上传、作业生命周期、发布确认、权限和历史保存仍在 qdagent。多文件任务桥接采用结构化参数,禁止拼接用户文件名进 shell/JSON 或共用固定请求临时文件。
|
||||
|
||||
## 9. 实现落点与兼容策略
|
||||
|
||||
| 模块 | 改动方向 | 兼容要求 |
|
||||
|---|---|---|
|
||||
| `plugins/llm/src/lib.rs` | adapter boundary、消息数组、usage、event sink、取消 | 保留已有符号;新能力有 probe 和合同版本 |
|
||||
| `ext/ai/llm.mq.md` 与 `ext/ai/llm/*` | strict selection、结构化 result、public snapshot | 无 selection 的旧调用仍可运行;不得回显密钥 |
|
||||
| `ext/ai/agent.mq.md` | run context、子工作簿传播、逐调用观测 | 不复制 Agent loop,EFI/verify/publish_gate 不被绕过 |
|
||||
| `plugins/agent/src/*` | 子任务/恢复上下文、cancel、event identity | resume 不重发已结算请求;不可恢复说明 interrupted |
|
||||
| `src/host/*`、插件 SDK、web invoke | 请求局部 event/cancel 桥接 | ABI 旧宿主不伪支持;并发请求不混流 |
|
||||
| `src/view/knowledge_present.rs` | DocumentView read model/兼容 adapter | 旧 presentation v1 不被新字段语义污染 |
|
||||
| `src/view/document.rs,render.rs,html.rs,mod.rs,output.rs` | 共享纯读取、fragment、scope CSS、定位 | live/debug 与 read 明确分离;旧 no-exec 门禁保留 |
|
||||
| `src/mlsp.rs` | capabilities、view/document/reference、版本 inspect | 使用现有 envelope;未知 feature 可探测 |
|
||||
| `src/sema/ir.rs,provenance.rs` | span、snapshot/locator、依赖与来源失效 | 不改变核心语法,不把读请求变为执行 |
|
||||
| `src/document_extract.rs` | capability 和片段定位完整性 | 保留不支持格式的显式失败 |
|
||||
|
||||
测试分层对应 plugin HTTP fixtures、Agent 假模型、MLSP read contracts、web 持续流集成、独立/嵌入 DOM 和浏览器交互。应用共享样本文件必须注明 schema 版本;两仓 PR 在各自文档索引相互链接对应实现说明。
|
||||
|
||||
迁移顺序为新增合同/接口 → 旧输出 adapter → qdagent 按 capability 接入 → 切默认 → 后续版本再考虑弃用。不要同时移除 legacy 行为且要求应用一次完成全链升级。发布包对 CLI/ext/native 插件做组合测试,缺插件给功能不可用诊断而非 unknown function 直到用户点击才暴露。
|
||||
|
||||
## 10. 交付切片与验收门槛
|
||||
|
||||
| 切片 | 前置 | 验收输出 | 支撑应用任务 |
|
||||
|---|---|---|---|
|
||||
| M00 合同冻结/探测 | 无 | schemas、fixtures、capabilities、版本和插件清单 | Q00、所有升级探测 |
|
||||
| M01 多模型隔离 | M00 | 兼容适配器、strict handles、history、子任务选择一致 | Q01/Q02 |
|
||||
| M02 调用观测与流 | M01 | 每 attempt usage、真流式、取消、错误/重放一致 | Q03/Q06 |
|
||||
| M03 只读嵌入 View | M00,可与模型线独立 | DocumentViewV1、fragment、目录/节点、无执行证明 | Q04 |
|
||||
| M04 引用与快照 | M03 | 历史 locator、来源详情、版本失效/歧义 | Q05 |
|
||||
| M05 文档工作区底座 | M03/M04 + 已有 extract | 范围隔离、提取定位、并发与缓存 | Q07/Q08 |
|
||||
| M06 集成与性能 | 全部所选切片 | 旧门禁 + 新 contracts + 浏览器与负载报告 | Q09 |
|
||||
|
||||
M01 支持多个兼容提供商不等待原生协议全做完;但原生适配器需另列完成状态。M03 不等待计费系统。M04 未完成历史快照前,应用可以显示当前文档,但必须把历史引用标“版本不可用”,不能宣布引用链闭合。
|
||||
|
||||
每个切片的 Definition of Done:实际接口可调用、失败合同覆盖、无副作用/隔离测试、文档示例由测试消费、版本能力可探测、qdagent integration fixture 通过。只有可运行的验收证据才可将 proposed 改为 verified。
|
||||
|
||||
## 11. 框架测试矩阵
|
||||
|
||||
| 编号 | 用例 | 断言 |
|
||||
|---|---|---|
|
||||
| F01 | 两端点各两模型、并行 A/B、无密钥本地端点 | 请求 payload/端点/鉴权正确,环境不串扰 |
|
||||
| F02 | step/plan/router/repair/child/resume | strict selection 和 parent identity 完整,不退回默认模型 |
|
||||
| F03 | multi-turn、system/tool roles、超限/不支持模态 | 顺序和边界完整,不吞最新 user,不静默降级 |
|
||||
| F04 | 非流/流式/usage-only/缺 usage/错误后部分 usage | null 与 0 区分,终态和用量独立 |
|
||||
| F05 | 相同累计 usage 多次、重放、新重试 | 同 attempt revision 覆盖,不重复相加;真重试新增 attempt |
|
||||
| F06 | 慢供应商、慢消费者、断连、取消、超时 | 完成前有 delta;队列有界;取消不启动后续工具/模型 |
|
||||
| F07 | 外部工具已写后取消、恢复未知状态 | 不声称撤销,不自动重做可能有副作用的动作 |
|
||||
| F08 | 带写文件/网络/foreign/插件的文档被阅读 | read API 不加载/运行这些效果,无项目写回 |
|
||||
| F09 | prose/heading/6 类步骤、同一行多引用、中文 span | HTML/outline/节点/ref 同源,定位唯一准确 |
|
||||
| F10 | 仅说明变化、依赖变化、旧 SSE 包、无 token | token 正确失效,嵌入 strict 拒绝过期/无身份包 |
|
||||
| F11 | 来源改删、历史 generation 未留原文、同名歧义 | 明确 stale/unavailable/ambiguous,无猜测替代 |
|
||||
| F12 | no-js/390px/暗色/长表格/键盘 | 正文可读,可返回,有清晰标题和焦点 |
|
||||
| F13 | 原始 HTML/危险 URL/闭合 script/越界路径 | 无脚本执行/越权读取/泄漏;不靠应用猜净化 |
|
||||
| F14 | 两项目同相对路径/并发 100 读取 | scope 缓存隔离,同 snapshot 合并分析 |
|
||||
| F15 | 编译成功但验证/证据未知、旧执行记录 | 各状态独立;不把 static/sourced 标 verified |
|
||||
| F16 | CLI/ext/native 版本错配 | capability 早发现不可用,而非运行时静默失败 |
|
||||
|
||||
性能目标需实测而非发版文字:固定机器与 release/debug 分开记录,1000 单元分析冷/热、单文档 fragment 体积/时间、并发读取 P95/内存、UI 首屏。应用目标见 Q 文档;如果全量 compile 超时,优先分析重复全库扫描、依赖计算与缓存,不通过删除 fixture 或抬高阈值宣布可用。
|
||||
|
||||
## 12. 本次验证结果与已知阻碍
|
||||
|
||||
### 12.1 M00–M06 落地证据(2026-10-25 续)
|
||||
|
||||
命令(本机):
|
||||
|
||||
```bash
|
||||
cargo test --offline --locked --test workbench_contracts
|
||||
cargo test --offline --locked -p marqdo_plugin_llm
|
||||
cargo test --offline --locked --test executable_knowledge f1_agent_eng_bind_gate_mq_offline -- --exact
|
||||
```
|
||||
|
||||
已交付并通过自动化子集(**非** F01–F16 全绿):
|
||||
|
||||
| 切片 | 证据 |
|
||||
|---|---|
|
||||
| M00 | fixtures + JSON Schema 消费;`capabilities`;`force_unloaded` / `force_*_off`(F16) |
|
||||
| M01 | strict selection;`RunContextV1` 并行不串扰;llm plugin messages/roles;workbook 禁 `llm.llm`;**F02** `m01_f02_agent_step_selection_and_resume`(mock HTTP + `llm.create` 抗 env poison + resume save/load) |
|
||||
| M02 | usage null≠0;revision 替换(F05);cancel token(F06/F07);event_sink;web `sse-live` 断连 cancel |
|
||||
| M03 | `view.document`;CJK outline/nodes;path escape;静态 a11y 子集;F08 无副作用标记;**浏览器** `workbench-docview.html`(`article.mq-document`、0 script、无 `javascript:`) |
|
||||
| M04 | stale / version_unavailable / **ambiguous**;`SnapshotManifestV1` 输出(retention=application);`artifact.version_mismatch`;embed strict SSE |
|
||||
| M05 | extract `:B`;analysis_cache begin/finish;**F14 并发 100** 同 snapshot + 跨 project 隔离 |
|
||||
| M06 | CI 预构建 agent+llm + `workbench_contracts`;Go `drainForward` / cancel-token 桥 |
|
||||
| Live | `tests/workbench_live.rs`:USTC OpenAI-compatible(`OPENAI_*` env only)`qwen3.8-chat` / `deepseek-flash` selection ask → `pong` + usage;`MARQDO_EXT` 指向仓内 `ext/` 避免 `~/.marqdo/ext` 陈旧遮蔽 |
|
||||
|
||||
已知限制(发版前须书面接受或继续补):
|
||||
|
||||
- F02 repair/plan **全路径**假模型仍薄于 step+resume;RunContext 三级继承 + skeleton 禁 `llm.llm` + 子任务 env 已有。
|
||||
- 历史正文由应用按 SnapshotManifest 保留;框架缺快照 → `version_unavailable`(不静默降级)。
|
||||
- 完整宿主嵌入 F12 / 产品鉴权留给 qdagent;原生适配器 / PDF/OCR 仍 unavailable。
|
||||
|
||||
### 12.2 历史基线记录(设计起草时)
|
||||
|
||||
起草时 `executable_knowledge` 曾出现 `f1` 缺插件与 `v3_corpus_1000` debug 超时;其后 `ensure_agent_plugin_built` + CI 预构建已修复 f1 路径。1000 单元性能仍按剖面单独记录。
|
||||
@@ -0,0 +1,463 @@
|
||||
# View 可执行知识阅读体验重设计
|
||||
|
||||
| 项目 | 说明 |
|
||||
|---|---|
|
||||
| 日期 | 2026-10-24 |
|
||||
| 状态 | 详细设计建议,待实施;不是已交付能力声明 |
|
||||
| 审计基线 | `b8a4ddd` / Marqdo 2.1.1;使用当前源码构建的 debug CLI 复核 |
|
||||
| 输入 | 用户提供的 view 截图:Executable Knowledge 在 Structure 前,Steps、Target、Kind、Signature、Effects、Verification、Lock digest 等字段大量铺开 |
|
||||
| 范围 | Live view、静态导出、正文结构、知识说明、运行结果、来源与状态呈现;不改语言语义,不增加作者必填的展示 DSL |
|
||||
| 关联 | [文档原生开发指导](document-native-development-guide.md)、[View 总体设计](view.md)、[文档面与标注](view-document-annotations.md)、[求道相关框架缺口](../roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) |
|
||||
|
||||
## 1. 设计决策
|
||||
|
||||
**View 首先呈现知识文档本身,结构帮助读者理解和定位,机器信息解释当前所读内容。** 正文、程序结构、知识关系与执行证据应由同一份源文档关联起来,而不是顺序展示几份互相脱节的报告。
|
||||
|
||||
确定以下方向:
|
||||
|
||||
1. 移除正文之前整块展开的 Executable Knowledge。主阅读流首先出现作者的标题、介绍和内容;不把完整机器报告简单搬到正文后继续平铺。
|
||||
2. 保留并改进现有 Structure 的叙述保真文档面,面向读者命名为“文档”。正文、表格、公式、函数和可执行步骤在原位置阅读,不生成一份模型改写的平行说明书。
|
||||
3. 右侧“本文结构”负责章节与知识单元定位;选中知识片段后,在同一辅助栏展示它的解释、输入输出、来源和验证依据。源码标识、摘要与完整协议放在可展开的技术详情中。
|
||||
4. 运行结果就地关联到对应步骤,明确运行实例与输入;完整日志、运行控制和源码放在正文后。看见一个数值时,读者必须能知道它是文档声明、计算结果还是历史快照。
|
||||
5. 静态分析、程序运行、测试断言、来源关联和领域确认分别表达。不能用一个 `ok`、`pure` 或绿色“已验证”覆盖不同事实。
|
||||
6. 功能渐进增强:无 JavaScript、静态导出、移动端、打印时仍能读完文档、定位知识和查看必要依据。普通短文不变成复杂仪表盘。
|
||||
|
||||
这些决策恢复 [view.md](view.md) 原有“文档面为主、Browse 与 Debug 分工”的方向,同时修订过度依赖引出线和默认展开技术面板的呈现方式。
|
||||
|
||||
## 2. 现状审计:为什么截图难读
|
||||
|
||||
### 2.1 可定位的实现依据
|
||||
|
||||
| 观察 | 当前代码 | 对阅读的影响 |
|
||||
|---|---|---|
|
||||
| 知识面板位于正文前 | [html.rs / page_file](../../src/view/html.rs) 的模板顺序为 notebook → knowledge → Structure → Execution → Source | 必须先越过辅助资料才能看到文档;模块越多越严重 |
|
||||
| 所有制品一律展开 | [render.rs / render_knowledge_html](../../src/view/render.rs) 按文件筛选 artifacts,并逐项输出完整 `<dl>` | module/type/function 同等突出,容器元信息挤占知识内容 |
|
||||
| Steps 脱离所属结构 | 同函数把当前文件所有 steps 放在单一 `<ol>` 中,展示 kind、label、完整目标 ID | 静态步骤容易被误读为实际执行顺序;调用/循环/正文引用混在一起 |
|
||||
| 内部字段未经阅读转译 | URI、签名、effects、verification 拼接文本、完整 sha256 默认可见 | 读者仍不知道这项知识解决什么问题、怎样用、依据在哪里 |
|
||||
| “Lock digest”名实不符 | 该字段实际显示 `artifact.hashes.artifact`;[mod.rs](../../src/view/mod.rs) 编译使用 `LockMode::Off` | 制品摘要被误读为已经锁定且通过复现检查 |
|
||||
| 静态说明与运行脱节 | 每张卡固定输出 `Not executed by knowledge preview.`;实际 run capture 在另一条路径 | 即使页面有运行结果,也很难理解“未执行”到底指什么 |
|
||||
| 分析失败静默消失 | `build_file_view` 对语义编译结果使用 `unwrap_or_default` | 无知识、分析失败、尚未分析在界面上都可能表现为空 |
|
||||
| 标题与层级表达较弱 | `page_file` 标题取文件名;[document.rs / render_fun_heading](../../src/view/document.rs)统一用 h3 | 作者 frontmatter 标题未用于页标题,嵌套结构主要靠其它线索判断 |
|
||||
| 知识组件缺少专用布局 | `knowledge-*` 在 HTML 中有类名,但 `html.rs` 没有与面板匹配的专用样式规则 | 大量使用默认列表/定义列表排版,空白多、关系弱,和正文主题缺少一致约束 |
|
||||
| 新旧皮肤叠加 | `html.rs` 内基础 view CSS 与 `notebook_ui` 大块 notebook 主题共存 | 正文、注释、知识区的字号和密度不一致;不能只修一个卡片颜色 |
|
||||
| 验收主要看元素存在 | [executable_knowledge.rs](../../tests/executable_knowledge.rs) 的 view 用例检查 step 类名、kind 和 `#stmt-` 链接 | 没检查正文优先、跳转目标存在、可读文案和实际布局 |
|
||||
|
||||
已有能力应保留:[document.rs](../../src/view/document.rs) 的叙述/表格保真、Occlusion 描述与实现分离、函数大纲、调用帧/循环帧选择、[annot.rs](../../src/view/annot.rs) 的真实执行标注。重新设计应基于这些能力,而不是退回 AST 卡片浏览器。
|
||||
|
||||
### 2.2 对截图的解释边界
|
||||
|
||||
截图可直接确认:机器字段先于正文、Steps 只有 `call print`、长 URI/摘要显著占位、英文状态串缺少解释,以及深色底上的孤立黑色短线。
|
||||
|
||||
黑色短线的具体来源尚未在浏览器中复现。代码中存在 annotation leader、布局重算和主题覆盖,可能需要检查,但本文件不把它们断言为唯一根因。实施时应使用用户截图对应页面复现,检查实际 DOM、computed style 和几何位置;不能用全局隐藏所有 SVG/边框来掩盖问题。
|
||||
|
||||
### 2.3 本轮实际复核
|
||||
|
||||
把 [public/features/01-phase-i-treewalk.mq.md](../../public/features/01-phase-i-treewalk.mq.md) 复制到临时目录,使用 debug 2.1.1 执行静态导出并检查生成 HTML:knowledge 确实在 structure 前,共 3 个 `knowledge-card`(含 Steps)和 2 个完整 sha256。该短文的核心只是介绍 tree-walk 流程并打印一句话,当前辅助内容明显过重。
|
||||
|
||||
另用隔离临时文件复核 `view output --no-exec`:嵌入的 `fs.write_text` 仍创建了临时标记文件。原因是 [output.rs / write_static](../../src/view/output.rs) 先调用会执行的 `build_file_view`,再在 `opts.no_exec` 分支清空结果。**这是已复现的执行/呈现不一致,必须修复,不能仅把标签改成“未运行”。** §9 给出新的构建边界。未执行线上浏览器像素比对,本文线框为目标设计。
|
||||
|
||||
## 3. 读者任务与设计成效
|
||||
|
||||
| 读者任务 | 默认应看到 | 按需展开 | 成功判据 |
|
||||
|---|---|---|---|
|
||||
| 理解这篇文档 | 作者标题、介绍、正文和核心表格/步骤 | 完整源码 | 不滚过机器报告就能开始阅读 |
|
||||
| 看懂文档结构 | 章节、类/规则/函数的真实层级,当前位置 | 参数和局部步骤树 | 能判断一个步骤属于哪个知识单元 |
|
||||
| 理解某项知识 | 描述、简洁公式/调用、条件、返回含义 | payload、契约、精确目标 | 能解释它做什么、需要什么、产生什么 |
|
||||
| 判断结果是否可信 | 来源状态和所选运行的明确结果 | 测试、来源片段、版本和诊断 | 能区分“可以运行”和“事实成立” |
|
||||
| 跟踪跨文档复用 | 友好目标名、所属文档、输入输出 | 依赖关系、完整标识 | 能到达定义并返回原阅读位置 |
|
||||
| 检查某次运行 | 本次输入、选中调用/迭代、对应结果 | 日志、历史帧 | 不把不同运行的值混在一起 |
|
||||
|
||||
不要求所有读者理解 SymbolId、IR、hash 或 effect 协议。开发者仍能找到这些信息,但它们不再成为阅读的前置条件。
|
||||
|
||||
## 4. 页面信息架构
|
||||
|
||||
### 4.1 默认桌面布局
|
||||
|
||||
```text
|
||||
┌ Marqdo 项目 / 文档路径 搜索 主题 ┐
|
||||
├───────────┬───────────────────────────────┬────────────┤
|
||||
│ 文件目录 │ Phase I — tree-walk interpreter│ 本文结构 │
|
||||
│ │ Lex · parse · check … │ 介绍 │
|
||||
│ 当前文件 │ [运行记录:尚未运行] [详情] │ main 入口 │
|
||||
│ │ │ │
|
||||
│ │ Milestone: Phase I … │ │
|
||||
│ │ Pipeline: load → … → eval │ 选中后: │
|
||||
│ │ │ 当前知识 │
|
||||
│ │ main · 入口 │ 作用 │
|
||||
│ │ 输出说明 print text=… [说明] │ 输入/返回 │
|
||||
│ │ │ 来源/条件 │
|
||||
│ │ ▸ 运行与结果 │ 检查/运行 │
|
||||
│ │ ▸ 完整源码 │ 技术详情 ▸ │
|
||||
└───────────┴───────────────────────────────┴────────────┘
|
||||
```
|
||||
|
||||
布局是文件导航、主文档、一个辅助栏,不能增加第四条永久侧栏。右栏上部保留可收起的“本文结构”;用户选中片段后,下部显示“当前知识”。空间不足时以当前知识替换下部内容,并提供“返回目录”操作。打开/关闭详情不改变正文宽度,避免重排导致阅读位置跳动。
|
||||
|
||||
主文档的默认顺序:
|
||||
|
||||
1. 文档标题、已有 description、简短状态入口;title 缺失时退回文件名。
|
||||
2. 源文档的正文、结构和轻量就地知识说明,保持作者顺序。
|
||||
3. “运行与结果”:运行按钮、输入、所选运行结果、输出图形/日志;已有重要失败有就地入口。
|
||||
4. “完整源码”及“文档技术信息”,默认折叠。
|
||||
|
||||
不在顶部强制生成内容摘要、全量函数清单、巨大状态矩阵或知识关系图。没有 description 时不调用 LLM 补写。结构大纲始终可达,正文不因折叠辅助栏而变成无结构的文章。
|
||||
|
||||
### 4.2 尺寸与响应式规则(设计目标)
|
||||
|
||||
| 可用宽度 | 布局 |
|
||||
|---|---|
|
||||
| ≥1280 CSS px | 文件栏约 220–260px;正文弹性;辅助栏约 280–320px;正文中文行长约 32–44 字 |
|
||||
| 900–1279px | 文件栏可收起;正文优先,辅助栏可切换为有标题的侧抽屉 |
|
||||
| <900px | 单列文档;“目录”“当前知识”作为明确按钮打开抽屉或块内 details |
|
||||
| 320–390px 手机 | 标题、正文、状态不横向溢出;长表格/代码局部滚动,整页不左右拖动 |
|
||||
| 打印 | 正文展开,必要来源/验证摘要转为节后附注;交互按钮和导航隐藏;技术原始字段按导出选项包含 |
|
||||
|
||||
在 1440×900、100% 缩放的短文验收样例中,首屏应包含至少一段正文和首个主要结构单元;状态头不得因每个 artifact 增长而把正文推出首屏。此约束不截断作者自己的长标题或介绍。
|
||||
|
||||
### 4.3 普通文档与复杂知识文档采用同一布局
|
||||
|
||||
- 普通说明页只有 main/print:显示原文与输出操作,技术区保留模块信息;不强制展示“1 项可执行知识”卡。
|
||||
- 可复用函数库:目录列出函数;函数标题下出现紧凑签名和“说明”入口;即使无 main,也能正常阅读。
|
||||
- 事实/规则文档:来源、条件与验证紧邻相应知识;来源问题不能藏进页尾。
|
||||
- 教程/Notebook:保留源文档的代码单元与结果;全局单元运行条收进运行区域或显式工作模式,不能把所有文章永久变为 notebook 工具台。
|
||||
- 大文档:目录按真实层级和顺序组织,可搜索;正文不因知识数量膨胀为另一份报告。
|
||||
|
||||
## 5. 文档与结构呈现规范
|
||||
|
||||
### 5.1 标题、类与函数层级
|
||||
|
||||
页标题优先来自解析后的 frontmatter `title`,其次使用合适的源文档标题,再回退文件名;不要自行用正则重解析 YAML。保留原文标题内容,不擅自把技术名称改成模型生成的名称。
|
||||
|
||||
“本文结构”同时服务阅读和程序定位,但明确区分:
|
||||
|
||||
- 作者章节按实际文档关系展示。
|
||||
- 可执行的类/类型、函数、入口附轻量类型词,例如“规则”“函数”“入口”;类型词来自编译结果或已声明元数据,不由标题猜业务类型。
|
||||
- 同一节点既是章节又是函数时只有一个目录项,旁边标类型,避免两棵树重复。
|
||||
- 嵌套函数、分支、循环在对应父节点下展开;语义归属与 Markdown 可视层级分别保留,不把所有内容都扁平化为 h3。
|
||||
- 普通段落引用不提升为函数;module 容器不自动成为一张与业务函数同权的卡。
|
||||
|
||||
DOM 标题使用连续、可访问的层级;实际语法的 `#`/`##` 层数在源码面保留。用户复制源码时取得原始合法语法,而非为了 HTML 标题级别改写过的内容。
|
||||
|
||||
### 5.2 可执行步骤:就地解释并保留上下文
|
||||
|
||||
| 编译器步骤 | 默认阅读文案 | 展开后 |
|
||||
|---|---|---|
|
||||
| observe | “读取:商品单价” | 集合、取元表达式、字段说明、当前调用下的值 |
|
||||
| derive | “计算:商品小计” | 公式、输入来源、计算条件、当前结果 |
|
||||
| call | 优先作者标签;无标签时“调用 商品小计” | 目标、所属文档、实参映射、返回和运行记录 |
|
||||
| iterate | “逐项处理:订单商品” | 集合、循环体、迭代数、所选迭代 |
|
||||
| narrate | 正文保留作者描述,附“知识引用”入口 | 定义与来源;不当作已执行步骤 |
|
||||
| navigation | 标准文档链接 | 正常导航,不显示虚构的执行结果 |
|
||||
| 空 payload / stub | 作者描述 + “待实现” | 缺失的实现和已有诊断,不能展示成功数值 |
|
||||
|
||||
名称来自当前节点的 label、声明说明、目标可读名,依次回退;没有业务描述时就显示“调用 print”,不得自动声称它是“验证知识”或“输出最终结论”。普通 print 在所属文档位置解释输出作用,放在“输出”类信息中,不作为高价值知识卡突出。
|
||||
|
||||
“步骤”列表只在当前知识详情中显示,标为“文档中的步骤”或“结构步骤”。静态序号不能暗示实际执行时序;实际轨迹另按运行事件呈现,分支和循环保留嵌套。
|
||||
|
||||
### 5.3 描述、实现与结果的三层关系
|
||||
|
||||
以 `**总价 = [计算订单小计](pricing.小计(数量, 单价))**` 为说明示意:
|
||||
|
||||
```text
|
||||
计算订单小计 [说明]
|
||||
总价 = pricing.小计(数量, 单价) ← 简短实现,次一级视觉
|
||||
本次示例:数量 2,单价 30 → 60 ← 仅有匹配运行记录时出现
|
||||
```
|
||||
|
||||
作者的上下文句、返回说明、单位和条件仍在原位。短公式/实现可次级显示,长 payload 默认折叠到详情;显式“展开实现”控制可对当前知识单元生效。不得把所有代码完全藏掉,使“代码即文档”退化成只有自然语言标签。
|
||||
|
||||
复制操作区分“复制说明”和“复制源码”;源码来自源 span,保留必要定界符、参数和 import 依赖提示。显示为漂亮文本的结果不能被复制成伪造的可执行代码。
|
||||
|
||||
### 5.4 表格、条件与关系
|
||||
|
||||
数据表按作者结构呈现,表头固定语义,单位与列说明常显;契约表按输入/返回/约束组织。显示层不能把 Marqdo 列向集合悄悄换成行向记录;需要另一种预览时明确标为预览,并能查看真实形状。
|
||||
|
||||
前提条件与失败分支不得因“简洁”隐藏。默认显示全部分支结构,所选运行只突出实际命中的分支,继续遵守 [调用帧与结构保真](view-frame-selection.md)。
|
||||
|
||||
跨文档关系默认用可读链接,例如“使用:标准税率 · tax.mq.md”,而非 `mq://…`。直接依赖与被引用者各列前几项并可展开;可选局部关系图放在详情层,不作为默认阅读画布。关系图必须有等价文字列表,并显示未知/动态关系,不能补画不存在的边。
|
||||
|
||||
## 6. 当前知识详情:回答问题,而非列出字段
|
||||
|
||||
### 6.1 内容顺序
|
||||
|
||||
```text
|
||||
商品小计 函数
|
||||
根据数量与单价计算商品金额。 ← 仅引用已有描述
|
||||
|
||||
输入 数量:整数;单价:金额 ← 类型/单位未知则明确未知
|
||||
返回 金额
|
||||
条件 数量非负 ← 仅当已声明且可定位
|
||||
实现 数量 × 单价
|
||||
|
||||
来源 定价说明 / 第 2 节 [打开]
|
||||
检查 契约未检查;测试未运行 [查看依据]
|
||||
运行记录 示例 #2:2 × 30 → 60 [定位输出]
|
||||
使用 … [查看定义]
|
||||
|
||||
▸ 技术详情:精确标识、完整签名、效应、摘要、诊断 JSON
|
||||
```
|
||||
|
||||
此处“金额”“数量非负”等只用于解释布局,不宣称当前样例具有这些元数据。没有信息就省略非关键行或写“未声明”,不得推断成“无限制”“没有来源也可靠”。缺失影响可用性时常显;纯工具没有业务来源并不自动是错误。
|
||||
|
||||
### 6.2 当前字段的去向
|
||||
|
||||
| 当前字段 | 新的主要位置与文案 |
|
||||
|---|---|
|
||||
| Target / `mq://…` | 标题处可读定义链接;完整 ID 在技术详情,可复制 |
|
||||
| Kind / callable | 标题旁简短类型词;module 信息进入文档技术信息 |
|
||||
| Signature | 输入/返回紧凑表;完整规范签名可展开 |
|
||||
| Effects | “涉及的操作”,说明文件读写、网络等;未知明确显示,非纯不等于失败 |
|
||||
| Verification 长串 | 分项检查和证据表,见 §7 |
|
||||
| Lock digest | 更名“制品摘要”,技术详情内显示;锁状态单独来自真实 lock report |
|
||||
| Depends on | 可读目标列表,指向定义与引用位置;未分析不能写“无依赖” |
|
||||
| Execution 固定句 | 匹配运行记录,或“尚无该知识的运行记录” |
|
||||
| SourceRef / applicability | 当前遗漏的关键内容:放入“来源”和“适用条件” |
|
||||
|
||||
默认不铺完整 hash。技术详情可显示缩略摘要并提供全值/复制;缩略值不用于识别唯一性。没有读取锁报告时写“未检查锁定状态”,不能把拥有摘要显示成“已锁定”。
|
||||
|
||||
### 6.3 交互、跳转与返回
|
||||
|
||||
1. 点击正文的“说明”或目录知识项,选中同一 `node_id`;正文轻量高亮,右栏同步。键盘和触屏具有等价入口,不依赖 hover。
|
||||
2. 跳转到定义时保留来源文件、锚点、滚动位置和所选运行;返回恢复阅读位置。
|
||||
3. 文件、符号与语句不能只靠显示名称匹配。同名函数的详情显示所在文档和父结构。
|
||||
4. 默认不自动抢焦点、不因滚动不停替换用户正在阅读的详情。滚动只更新目录当前位置;点击选择才改变详情。
|
||||
5. 手机抽屉有标题、关闭、返回焦点和滚动管理;无 JS 时使用正文附近的原生 details 或页尾知识附注锚点。
|
||||
6. 当前 URI 不在导出范围内时显示“定义未包含在此次导出”,提供可读路径和复制引用;禁止输出必然失效的 `mq://` 或 live `/file` 链接。
|
||||
|
||||
## 7. 状态设计:读者必须知道什么被证明了
|
||||
|
||||
### 7.1 分离三个状态来源
|
||||
|
||||
| 状态来源 | 可以说明 | 不能说明 |
|
||||
|---|---|---|
|
||||
| 编译/静态分析 | 结构解析、目标绑定、契约检查结果、已建模效应 | 程序已运行、答案正确、资料真实 |
|
||||
| 运行记录 | 指定输入、环境、源码版本下的执行与输出 | 覆盖所有输入、测试通过、来源可信 |
|
||||
| 证据/验证记录 | 哪个断言/测试/来源核验通过,何时失效 | 未执行或未核验的其它部分也可靠 |
|
||||
|
||||
顶部仅给紧凑事实,例如“静态分析完成 · 尚无运行记录”,或“有 1 项来源问题 · 查看”。普通 unknown/unchecked 不应制造全页红色警报;与当前结论直接相关的失败、过期、未解析必须就地提示且可定位。
|
||||
|
||||
### 7.2 分项文案映射
|
||||
|
||||
| 机器状态 | 阅读文案 |
|
||||
|---|---|
|
||||
| parse=passed | 文档结构可解析 |
|
||||
| resolve=passed | 此项检查报告目标已解析;覆盖范围见详情 |
|
||||
| contract=unchecked | 契约尚未检查 |
|
||||
| execution=not_run | 尚无执行记录 |
|
||||
| tests=unknown | 尚无测试记录 |
|
||||
| evidence=sourced | 已关联来源,内容尚未核验 |
|
||||
| evidence=unverified | 来源内容尚未核验;结合来源列表判断是否已关联 |
|
||||
| missing_source / expired | 来源缺失 / 已过适用期 |
|
||||
| domain=unreviewed | 尚无领域审阅记录 |
|
||||
| effects=pure | 静态分析未发现已建模的外部操作;展开可看范围 |
|
||||
| effects=unknown | 涉及的操作尚不能完全确定 |
|
||||
| 无对应字段 | 未提供该项检查结果 |
|
||||
|
||||
分项取值不能自动升级成综合“可信”。只有宿主选定的政策实际给出聚合结论,才显示“满足 ×× 政策”,同时附政策名称、版本与证据;业务条件还须明确展示。
|
||||
|
||||
### 7.3 结果来源与失效
|
||||
|
||||
每个运行值绑定 `run_id + source_digest + node_id + call_id + loop/iteration` 中适用的字段,展示本次输入或简短上下文。无节点映射时只展示整次运行输出,不硬塞到某个函数旁边。
|
||||
|
||||
静态导出有快照时标“导出快照”,附生成时间/输入;读者切换调用帧是在看历史结果,不叫“重新计算”。源码、依赖或来源与记录不匹配时标“历史结果,版本已变化”,不继续用成功样式绑定到新正文。
|
||||
|
||||
正文里的字面量可以显示为“文档声明值”;解释器实际执行得到的值才叫“运行结果”。没有值、返回 None、stdout 为空、尚未运行、执行失败必须分开,不能统一成 `(no stdout)`。
|
||||
|
||||
### 7.4 空态与错误态
|
||||
|
||||
| 情况 | 处理 |
|
||||
|---|---|
|
||||
| 没有可识别知识单元 | 正常显示文档,不插空知识面板 |
|
||||
| 语义分析失败 | 保留可读正文/源码,显示“知识关系暂不可用”及可定位诊断 |
|
||||
| 局部未解析 | 仅对应片段显示问题,保留其它已知结果 |
|
||||
| 无运行或 no-exec | 运行区说明原因,使用中性状态,无绿色运行成功标记 |
|
||||
| 运行失败 | 错误摘要定位到源片段;日志在运行区,静态知识仍可读 |
|
||||
| 证据过期/冲突 | 相关知识常显问题、来源与影响;不静默选择一个结论 |
|
||||
| 分析被截断/超过扫描范围 | 显示范围和未覆盖项;“未发现”不能替代“没有” |
|
||||
|
||||
## 8. 视觉、密度与可访问性
|
||||
|
||||
### 8.1 排版与主题
|
||||
|
||||
正文建议 16–18px、行高约 1.65;辅助说明 13–14px、行高约 1.5;代码使用等宽字体,全文不因进入 notebook 主题缩为密集工具面板。主次依赖字号、间距和位置共同表达,不能仅靠颜色。
|
||||
|
||||
使用现有系统字体和主题机制,建立统一的 view tokens:正文/辅助文字、背景、细分隔、焦点、成功/警告/错误。知识组件只依赖 tokens,不硬编码黑色线条或白底。支持明暗主题,首次尊重系统/显式设置,不为这次改版再写第三套皮肤。
|
||||
|
||||
表格与长公式允许局部滚动;ID、路径在详情中可换行;主文无整页水平滚动。重要来源和适用条件不使用极浅灰隐藏。对比度验收目标:普通文字至少 4.5:1,大字和必要非文本边界至少 3:1;这些是实现验收目标,尚非本轮测量结果。
|
||||
|
||||
### 8.2 注释和连线
|
||||
|
||||
默认使用紧邻内容的短结果行或有标签的注释块,优先通过“同一节点名 + 明确位置”关联。长 L-leader 不再是默认必需元素;复杂节点可保留短连线,必须满足端点存在、在同一块内、不交叉、不覆盖文字。
|
||||
|
||||
当目标折叠、帧过滤、元素隐藏或几何测量失败时,不绘制连线。主题/字体/容器宽度变化后只重算当前可见块;采用可取消的局部布局更新,不全页不断测量。窄屏、打印、reduced-motion 下直接使用有编号的注释。截图中的孤立线条归入专门视觉回归场景。
|
||||
|
||||
### 8.3 键盘、屏幕阅读器与退化
|
||||
|
||||
- 目录用 nav,正文用 main/article,详情用有名字的 aside/section;标题层级连续。
|
||||
- 展开按钮有 `aria-expanded/controls`;选中状态、失败和待验证都有文字,不依赖颜色或图标。
|
||||
- 深链接滚动有 `scroll-margin-top`,聚焦目标不被固定工具条遮住;关闭详情后焦点回到触发点。
|
||||
- 不使用只有鼠标悬停才能看到的来源、代码或错误。大表格有标题与表头关系,日志可复制。
|
||||
- 无 JS 时正文、目录锚点、来源链接、原生 details 和静态结果仍工作;只失去实时联动与运行操作。
|
||||
- 选择帧不隐藏源结构;隐藏实现也不能删除文档含义和必需条件。
|
||||
|
||||
## 9. 技术设计与数据契约
|
||||
|
||||
### 9.1 从预拼 HTML 改为可关联的展示模型
|
||||
|
||||
当前 `FileViewModel.knowledge_html` 是独立 HTML 字符串,难以与正文、trace、诊断同步。建议新增结构化 `KnowledgePresentation`,在 Rust 端形成同一份模型,由正文、目录、详情共同消费。兼容阶段可保留旧字段,但不让它继续成为唯一知识接口。
|
||||
|
||||
```text
|
||||
ViewDocument
|
||||
document_id, source_digest, semantic_generation, title, description
|
||||
blocks[] 保真正文结构及 source span
|
||||
outline[] 标题/知识单元父子关系
|
||||
knowledge_nodes[] 对应 artifact/ref/step,不复制语义解释器
|
||||
diagnostics[] 范围、严重性、可读说明、定位
|
||||
execution_state 明确未运行/运行中/成功/失败/快照
|
||||
run_records[] 与文档版本相匹配的证据
|
||||
|
||||
KnowledgeNode
|
||||
node_id, artifact_id?, symbol_id?, ref_id?, step_id?
|
||||
owner_id?, source_span, display_name, authored_description?
|
||||
kind, signature?, payload?, dependencies[], provenance[]
|
||||
applicability?, verification[], effects, coverage
|
||||
execution_refs[]
|
||||
```
|
||||
|
||||
这些字段为建议契约,未承诺当前 IR 已提供所有信息。语义事实来自 `SemanticProject`,文档叙述来自解析后的源结构,执行事实来自 capture;缺少关系时展示 unknown,不让 UI 用名称模糊匹配或调用模型编造。
|
||||
|
||||
### 9.2 数据流
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S[源文档与项目边界] --> P[解析与语义分析]
|
||||
P --> B[正文块与结构]
|
||||
P --> K[知识节点与诊断]
|
||||
R[显式运行或匹配的历史快照] --> T[执行记录]
|
||||
B --> V[统一展示模型]
|
||||
K --> V
|
||||
T --> V
|
||||
V --> D[正文与就地说明]
|
||||
V --> O[目录与当前知识]
|
||||
V --> E[运行区域与技术详情]
|
||||
```
|
||||
|
||||
知识模型不通过“render HTML → 再抓取文本”生成。页面分析失败不可用空字符串吞掉,应保留有状态的结果;部分成功与整体失败分开。
|
||||
|
||||
### 9.3 源位置、稳定身份与锚点
|
||||
|
||||
目前 step 跳转用 `#stmt-{line}`,函数用 `#fn-{line}`。一行多个表达式、正文段落合并、同名函数、源码插行都会使单纯行号不够。
|
||||
|
||||
新增内部节点锚点注册表,将文档块、函数、语义 step/ref 与真实 DOM id 映射;使用 artifact/node 身份和源 span 生成页内唯一 ID,不把未经编码的 URI 当 DOM id。当前编译器没有稳定 SyntaxNodeId 的地方,退化为“源码版本 + span”,明确跨版本不可保证稳定;不能只把行号哈希一下就宣称稳定身份。
|
||||
|
||||
兼容现有 `#structure`、`#fn-N`、`#stmt-N` 链接,保留别名或定位映射;所有生成链接都验目标存在。跨文件 href 复用 [html.rs 的 LinkMode/href_file](../../src/view/html.rs),静态导出保持相对路径;路径展示解码与 URL 安全编码分离。
|
||||
|
||||
### 9.4 分离分析与执行,修正 no-exec
|
||||
|
||||
将当前 `build_file_view` 拆成可组合路径(名称为建议):
|
||||
|
||||
1. `analyze_document`:读取、解析、语义检查、生成静态展示数据,不执行目标程序。
|
||||
2. `capture_execution`:只有执行策略明确允许时调用 run/cell runtime,返回真实状态与源版本。
|
||||
3. `assemble_view`:关联正文、语义和匹配的结果,生成同一个展示模型。
|
||||
|
||||
`--no-exec` 必须在第 2 步之前分支,不能先跑后清空;snapshot 模式使用匹配快照,不为了构造 UI 又运行一次。Live 现有自动执行兼容行为在首轮不静默改变,必须通过显式 execution policy 传入并如实标注;若后续将 live 默认改为阅读时不执行,作为独立 CLI 行为变更发布和迁移。点击详情、查看来源、展开关系等阅读操作绝不能触发执行。
|
||||
|
||||
知识详情不要求通过运行得出静态信息。实现参数预览/试跑时,使用既有受控执行路径,不因“pure”字样绕过宿主能力边界。本文不新增一套求值器或权限系统。
|
||||
|
||||
### 9.5 Live 更新一致性
|
||||
|
||||
当前 SSE 会替换 structure_html/bindings_html/trace_json,而知识面板来自另一次静态编译,容易新旧混用。建议更新包包含文档摘要、语义代、run_id 和变更节点;前端仅合并兼容版本的数据。
|
||||
|
||||
运行写回导致源码变化时,重新分析后一次更新相互关联的正文、目录、知识与运行映射。原选中节点仍存在则保留选择/焦点/滚动;已消失则明确提示,不能悄悄指向同名节点。旧请求返回晚于新请求时按版本丢弃,不覆盖较新阅读状态。
|
||||
|
||||
### 9.6 性能与导出体积
|
||||
|
||||
避免每个页面重复编译整个项目。一次静态导出共享同一项目语义结果,逐页投影;live 按项目源指纹、编译器版本、配置和适用性时钟缓存,读取使用一致的语义代。来源/有效期变化必须使相关状态失效,不能无限缓存 sourced。
|
||||
|
||||
正文服务端生成,不等待 JS 初始化或全部知识图完成才出现。默认只嵌入当前文档必要知识,深层依赖按需取;静态导出则包含保证离线可用的局部数据与明确范围。大量结果采用折叠/分页,但不能让屏幕阅读器和查找失去正文。
|
||||
|
||||
性能验收目标:100 个知识单元的本地选择/展开交互 p95 ≤100ms;1000 单元目录可搜索而不阻塞正文滚动;导出项目的语义编译次数不随页面数线性重复。记录硬件、样例和体积,目标未达时先优化数据重复和布局测量,不以截断关键来源达标。
|
||||
|
||||
## 10. 实施文件与兼容策略
|
||||
|
||||
| 位置 | 建议变更 |
|
||||
|---|---|
|
||||
| [src/view/render.rs](../../src/view/render.rs) | 提取知识展示模型;替换全量 dl 面板;关联步骤归属、友好名称与诊断 |
|
||||
| [src/view/document.rs](../../src/view/document.rs) | 源块/知识节点映射、正文就地入口、层级标题、可复制原始 span |
|
||||
| [src/view/html.rs](../../src/view/html.rs) | 正文优先布局、辅助栏、详情/目录交互、状态组件、统一 tokens;保留 LinkMode |
|
||||
| [src/view/mod.rs](../../src/view/mod.rs) | 分离分析/执行、保留诊断、组装统一模型、项目分析缓存 |
|
||||
| [src/view/output.rs](../../src/view/output.rs) | 提前应用 no-exec/snapshot 策略、共享项目分析、静态详情与相对跳转 |
|
||||
| [src/view/annot.rs](../../src/view/annot.rs) | 运行标注与节点/帧/版本关联,减少重复输出;缺映射不伪绑定 |
|
||||
| [src/view/debug_page.rs](../../src/view/debug_page.rs) | 仅回归检查共享组件;不把阅读布局强加给 debug |
|
||||
| [tests/executable_knowledge.rs](../../tests/executable_knowledge.rs)、view 单测 | 从字符串存在升级到顺序、锚点、状态和执行边界断言 |
|
||||
| 文档与 public 示例 | 更新旧 View 布局说明、截图和行为描述,区分历史默认与新设计 |
|
||||
|
||||
默认展示不要求作者补特殊 frontmatter;title/description、函数说明、契约和来源已有时直接受益。尚无信息的旧文档保真显示,并在详情中如实缺省。
|
||||
|
||||
与现有文档的关系:保留 [view-document-annotations](view-document-annotations.md) 的叙述主导和真实结果,修订“长 L-leader 为默认”;保留 [view-frame-selection](view-frame-selection.md) 的源码常显与帧隔离;[view-markup-surface](view-markup-surface.md) 的历史 Classic 例子需按当前默认语法同步,不能在新 UI 继续教授旧取元。外联/WASM 交互沿既有独立路线发展,不作为完成本次阅读改版的前置。
|
||||
|
||||
## 11. 分阶段交付
|
||||
|
||||
### V0:先纠正顺序、误导状态和执行边界
|
||||
|
||||
正文提前;完整知识报告收进明确的辅助入口,module/type 容器默认不铺卡;“Lock digest”改为准确的摘要标签;状态不再共用一个 ok。修复 no-exec 先执行问题,分析错误可见。暂不等待完整节点模型,就能显著改善截图场景。
|
||||
|
||||
V0 不算最终完成:仅把面板搬到后面/折叠,仍未解决正文与知识的关联。
|
||||
|
||||
### V1:完成阅读与结构理解的主闭环
|
||||
|
||||
统一展示模型、标题/目录层级、就地说明、当前知识详情、友好定义跳转与返回。完成函数、计算、来源、空态与基本运行结果的正负例;live/static 共用。
|
||||
|
||||
### V2:贯通运行、来源和跨文档关系
|
||||
|
||||
匹配运行实例与版本、调用/循环帧、来源定位/失效、局部依赖关系、SSE 原子更新。上游证据能力尚不完整的地方明确显示未知,不能以 UI 补出“验证通过”。
|
||||
|
||||
### V3:移动端、离线和规模验收
|
||||
|
||||
完成键盘/读屏、无 JS、打印、暗色/浅色、100/1000 单元性能、视觉回归与读者测试。发布前同步 public 示例与说明,保留旧锚点兼容。
|
||||
|
||||
## 12. 验收矩阵
|
||||
|
||||
### 12.1 必测文档
|
||||
|
||||
| 样例 | 必须验证 |
|
||||
|---|---|
|
||||
| 截图对应 Phase I 页 | 正文先出现;无 full URI/hash 瀑布;print 在所属正文解释;无孤立线条 |
|
||||
| 纯叙述/少量 Markdown 页 | 阅读无知识空卡、无误导运行徽章 |
|
||||
| 单个纯函数,无 main | 参数/返回与调用方式清楚,不因无入口标全文失败 |
|
||||
| 订单定价、多文档 import | 小计/税率/总额归属和依赖可追踪;输入和结果可对应 |
|
||||
| 带来源的事实与过期/缺失来源 | sourced 不显示已证实;问题在对应知识旁可见 |
|
||||
| 同名函数、多次调用和循环分支 | 定义唯一;切换帧只改结果和高亮,不隐藏结构 |
|
||||
| 空 payload、动态调用、未解析引用 | 待实现/动态/未解析准确可辨,不能展示虚构结果 |
|
||||
| 一行多个链接、嵌套表达式、中英文/长路径 | span 对应、锚点唯一、文本不丢失、不水平溢出 |
|
||||
| 运行失败、分析失败、快照过期 | 三种情况分开,仍能读到正文与具体诊断 |
|
||||
| 外联单元、变量大表、长日志 | 单层主体与对应结果,不重复三份输出;局部滚动 |
|
||||
|
||||
### 12.2 自动化判据
|
||||
|
||||
1. DOM 中文档主体先于全量知识技术详情,标题来自既有元数据;短文没有隐藏正文的默认展开报告。
|
||||
2. 每个知识/目录链接都能定位真实节点;一行多节点和同名跨模块不冲突;live/static 路径均有效。
|
||||
3. 验证、运行、来源状态按固定真值表渲染;无证据时绝不输出综合已验证。
|
||||
4. no-exec 用隔离目录的副作用计数测试证明没有执行;snapshot 不重跑;展开详情也不执行。
|
||||
5. 帧选择和 SSE 更新保留正文结构、选中身份与焦点,拒绝过期结果包。
|
||||
6. 明暗主题/320、390、1024、1440 宽度/200% 缩放下无遮挡、截断关键条件和整页横向溢出;孤立 leader 数为零。
|
||||
7. 无 JS、file 静态打开、打印预览都保留正文、定义/来源导航和必要证据说明。
|
||||
8. 输出中的作者内容、label、URI/属性与嵌入 JSON 按原上下文转义;资料中的 HTML/脚本不能因为新详情组件被直接执行。
|
||||
|
||||
字符串断言只能覆盖结构,不能替代浏览器布局验收;需截图基线和真实键盘交互测试。可复用现有测试基础,避免测试只镜像组件实现。
|
||||
|
||||
### 12.3 读者任务测试
|
||||
|
||||
建议用至少 5 位未参与实现的读者,分别完成三个任务,并与当前页面对照:
|
||||
|
||||
- 在 30 秒内说清文档目的并找到主要规则/函数。
|
||||
- 在 60 秒内找到某个结果的输入、定义和原始来源。
|
||||
- 正确区分“来源已关联但未核验”“本次运行成功”“未运行/历史结果”,不得误认为都已验证。
|
||||
|
||||
目标为至少 4/5 完成前两项,第三项无误导性判断;小样本仅作为可用性门槛,不声称统计显著。记录失败位置并修正信息架构,不能只问“是否好看”。
|
||||
|
||||
## 13. 完成定义与本次交付边界
|
||||
|
||||
完成的 view 应让读者先读懂文档,再自然看到其中的知识与执行结构;需要深入时能沿着一个具体片段追到实现、输入、结果和证据。全量技术字段仍可查,但不要求读者先理解编译器才能读文档。
|
||||
|
||||
本次只提交设计文档与索引,不修改渲染实现。实证包括用户截图、当前模板/渲染路径、静态 HTML 顺序检查和临时 no-exec 反例;布局尺寸、交互、性能和读者任务结果均为待实施的验收目标。
|
||||
@@ -0,0 +1,250 @@
|
||||
# Marqdo 支撑求道知识沉淀与文档编译的框架缺口
|
||||
|
||||
| 项目 | 基线 |
|
||||
|---|---|
|
||||
| 日期 | 2026-10-24 |
|
||||
| 框架源码 | `b8a4ddd`,Cargo 声明 2.1.1 |
|
||||
| 消费者源码 | 工作区 qdagent,`7f8f19d` |
|
||||
| 文档性质 | 当前源码复核、实测反例和增量建议;不重开已完成的 S0–S6 工作 |
|
||||
| 配套文档 | [求道产品侧缺口](../../../qdagent/doc/gaps/03-knowledge-ingestion-and-sedimentation-2026-10-24.md) |
|
||||
| 设计依据 | [文档原生开发指导](../design/document-native-development-guide.md)、[既有缺口路线](executable-knowledge-gaps-2026-10-23.md) |
|
||||
|
||||
## 1. 核心判断
|
||||
|
||||
Marqdo 已具备让求道采用文档原生知识的主要语言和执行基础。求道尚未接入的能力,不能统称为“框架不支持”。本轮框架侧优先工作是:**让生成知识的语言指导可信,让来源和验证真正约束发布与复用,让新语义制品进入默认 Agent 链路,并提供文档导入所需的通用适配接口。**
|
||||
|
||||
`knowledge` 编译的是已有源码和声明,不是把任意 PDF/DOCX 自动变成正确知识的转换器。上传、抽取、模型建模、语义编译、验证、发布是不同阶段。语义编译器保证程序和依赖的确定性;来源支撑、业务适用性以及领域审阅需要明确证据,不能由成功退出或 LLM 自述推导。
|
||||
|
||||
现有 [2026-10-23 路线](executable-knowledge-gaps-2026-10-23.md)的审计基线较早,之后已有多次实现提交。本文件按当前源码重新划分:已实现、有限子集、仍有断点;不照抄旧文档中的“无正文引用”“未知效应全为 pure”“两图互相覆盖”等历史判断。
|
||||
|
||||
## 2. 当前可直接复用的能力
|
||||
|
||||
| 能力 | 当前证据 | 给求道的边界说明 |
|
||||
|---|---|---|
|
||||
| 默认 Occlusion、`access`、显式遍历 | [核心表面](../design/core-surface.md)、[基线 01–04](../../tests/executable_knowledge/README.md) | 求道须迁移旧取元;无需增加新语法 |
|
||||
| 函数、契约、表格、import、关联函数 | `src/parse/`、[check.rs](../../src/check.rs)、[sema/bind.rs](../../src/sema/bind.rs) | 支持编写可复用知识;不是所有知识都要塞进 main 或建类 |
|
||||
| 项目身份、语义制品、绑定调用 | [project](../../src/project/mod.rs)、[symbols](../../src/sema/symbols.rs)、[IR](../../src/sema/ir.rs) | 已有 SymbolId/ArtifactId、BoundCall/DynamicCall;消费方不另造执行身份 |
|
||||
| 语义图与检索图隔离 | [knowledge/compile.rs](../../src/knowledge/compile.rs) | 权威语义 `graph/` 与检索 `ekc/graph/` 已分开,旧覆盖问题不再作为未实现项 |
|
||||
| 知识步骤、正文引用、view | `collect_named_steps`、NarrativeRef、现有集成测试 | 已含 observe/derive/iterate/call/narrate/navigation 子集;正文引用保持惰性 |
|
||||
| 来源与适用期初版 | [provenance.rs](../../src/sema/provenance.rs) | 已解析 `sources` block list、region、valid_until;sourced 不等于事实已经验证 |
|
||||
| 精确绑定与本地执行 | [mlsp.rs](../../src/mlsp.rs) 的 artifact.find/inspect/bind/execute | 已有摘要及 SymbolId 检查、按源行定位函数、pure 效应门槛;剩余失效问题见 M02/M03 |
|
||||
| 局部修改 | MLSP artifact.patch / artifact.extract_pure | 已有摘要保护、措辞修改守卫、纯片段提取;不应要求模型每次重写整库 |
|
||||
| 整代语义投影、锁、影响 | `write_semantic_projections`、[lock.rs](../../src/sema/lock.rs) | 已有 generations/CURRENT 与多类摘要;覆盖边界及实测失败见 M02/M06 |
|
||||
| Agent 工作簿、技能、沙箱 | [ext/ai/agent](../../ext/ai/agent.mq.md)、[plugins/agent](../../plugins/agent/src/lib.rs) | 可复用 Runtime、CoW、工具协议和诊断修复;求道不另建 Agent loop |
|
||||
| 文件上传/存储 | [storage.mq.md](../../ext/data/storage.mq.md)、[routes_media.go](../../plugins/web/internal/httpx/routes_media.go) | 已有上传路由、类型/大小验证和保存;不等于文档知识转换已存在 |
|
||||
|
||||
本轮离线执行 `cargo test --offline --locked --test executable_knowledge`:**25 passed / 1 failed / 0 ignored**。通过项包括双后端基线、绑定复用、正文引用、来源状态、局部补丁、100 单元和 CLI 冒烟。失败项为 `s5_closure_digest_moves_with_dependency`,单独重跑仍失败。存在大量有效基础,也存在需要先处理的失效缺口。
|
||||
|
||||
## 3. 框架缺口与可验收交付
|
||||
|
||||
### M01 · P1:上传底座尚未形成文档提取与来源映射协议
|
||||
|
||||
**现状。** Web 插件已注册 `web_upload_validate/save/app_upload`,`handleUpload` 接收 multipart 并存储字节。本轮在 `src/`、`plugins/`、`ext/` 的搜索未找到可供求道直接调用的 PDF/DOCX/OCR → 标准化正文 → 页段来源映射的完整链路。不要把 HTTP 文件保存或 `knowledge compile` 命令包装成已有文档转换器。
|
||||
|
||||
**建议。** 在扩展/插件层定义通用 `DocumentSource → ExtractedDocument` 协议,字段至少包括原件 URI/摘要、格式、提取器版本、段落/表格/页码定位、可提取文本、缺失部分、置信度及诊断。先支持 text/Markdown;PDF/DOCX/OCR 可通过独立插件或受控外部提取器接入。格式解析留在扩展,语言核心不引入 OCR 或模型业务。
|
||||
|
||||
知识生成由求道选模式、检索既有知识、调用模型并提供 patch;框架提供 compile/diagnostics/sandbox,而不是默默替作者推断领域真相。转换的外部程序必须服从宿主权限和资源边界。
|
||||
|
||||
**现有上传实现需补强的具体点。** `handleUpload` 先 `ParseMultipartForm(32 << 20)`、`io.ReadAll`,再按完整字节数做 Validate;32 MiB 是 multipart 内存阈值,不是请求总量硬限。应在解析/读取前限制请求与文件字节数,采用受限流式读取,并测试清理临时文件与失败路径。已有类型/路径验证应复用,不能将此描述为“没有任何上传校验”。
|
||||
|
||||
**验收。** 对文本、表格、跨页、坏编码、空文档、密码 PDF、扫描件、超限文件分别返回成功/部分/失败;每条抽取事实都可定位回原件;上传 `.mq.md` 不自动执行;相同文件及提取器版本输出可比较,重试不产生不同身份。
|
||||
|
||||
**责任。** Marqdo 提供提取与存储适配规范;求道负责上传界面、任务进度、知识库选择、发布政策与业务模型。
|
||||
|
||||
### M02 · P0:来源与依赖变化未完整进入摘要、锁与执行失效
|
||||
|
||||
**来源反例(实测)。** 2.1.1 下给函数声明 `sources: source.md#missing-anchor`,实际文件存在但锚点不存在,仍得 `evidence=sourced`;business bind 成功。修改 source.md 后 SourceRef.content_digest 变化,artifact.hashes.artifact 不变;旧 handle 继续执行。删除 source.md 后,旧 business handle 仍执行并返回原值。
|
||||
|
||||
**源码原因与边界。** [provenance.resolve_provenance](../../src/sema/provenance.rs)将 `#anchor` 存为 locator,但没有校验锚点;对来源文件计算哈希后,[IR artifact_for_function](../../src/sema/ir.rs)仍用 `digest(contract_summary(&contract))` 构造 evidence 摘要,没有包含来源内容和适用条件。`artifact.execute` 重编译并比较自身 artifact 摘要,但不重验 handle.policy 对应的证据状态。来源改变、来源删除、时间到期可以不改变函数实现,因此自身摘要检查不足。
|
||||
|
||||
**依赖反例(实测)。** [现有集成测试](../../tests/executable_knowledge.rs) `s5_closure_digest_moves_with_dependency` 中 `main` 调用 `d.rate()`,仅将被依赖函数返回值从 0.13 改为 0.14;测试读取到的 main closure 摘要未变。已重复验证。这里只确认该夹具失败:需要区分符号/模块同名选择、依赖边和闭包算法各自责任,不据此直接断言所有函数闭包都失效。
|
||||
|
||||
**其他源码缺口。** bind/execute 传递的是自身 `hashes.artifact`,没有把已有 `hashes.closure` 纳入句柄复核。`lock.impact` 从制品定义文件和依赖/正文边找反向影响,未把 `provenance` 的外部 corpus URI 纳入来源反向边。
|
||||
|
||||
**交付。**
|
||||
|
||||
1. evidence 摘要包含规范化来源 URI、定位、内容摘要、提取器/验证版本及适用性;锚点不存在返回不同于文件缺失的诊断。读取错误不能以空文件摘要冒充成功。
|
||||
2. 修复上述闭包失败,并明确 type/module/function 的身份与测试选择。依赖递归/环用确定的 SCC 或等价闭包摘要规则;无关文件增删不应导致任意漂移。
|
||||
3. 句柄记录并复核所需的依赖闭包、证据、政策及有效期;execute 重验 business/pure 等政策,不只相信 bind 时的状态。文件变化与时间变化都能使句柄失效。
|
||||
4. 将 corpus → artifact → caller/answer 的影响关系纳入同一编译结果,来源改动能查询受影响对象;报告接口、实现、证据、依赖分别发生了什么变化。
|
||||
|
||||
**验收。** 仅修改来源、删来源、改锚点、时间越过有效期、改直接/传递依赖都拒绝不再有效的句柄;原有测试恢复通过。不得为让测试变绿删除断言或改成只检查命令成功。普通无业务来源要求的纯函数仍可按相应政策执行。
|
||||
|
||||
### M03 · P0:验证 API 尚不是可发布知识的完整判据
|
||||
|
||||
**现状。** `VerificationRecord` 已分 parse/resolve/contract/execution/tests/evidence/domain,但 `semantic_artifact` 的默认值仍包括 `contract=unchecked`、`execution=not_run`、`tests=unknown`、`domain=unreviewed`、`lifecycle=draft`。MLSP `artifact.verify` 主要返回编译记录并附 policy,没有实际执行对应测试或回写证据。不能把它宣传为已经验证业务事实。
|
||||
|
||||
`artifact.bind(policy=business)` 接受 sourced/verified,尚未检查 region 与本次输入、单位、前提、输入域等;`provenance` 用日期字符串比较有效期,没有完整日期格式校验。当前“business”至多表示来源已关联且未被判过期,不等于适用性或事实成立。unknown policy 字符串也未通过枚举校验形成明确拒绝。
|
||||
|
||||
`knowledge verify` 检查的是旧 EKC 结构一致性;`conflicts/stale` 是报告命令,`duplicate` 的默认行为也是报告。它们都有价值,但消费方不能从退出码 0 得出“候选可晋升”。求道正存在这种误用。
|
||||
|
||||
**交付。** 给调用方稳定的验证结果结构:验证对象/摘要、所选政策、每个检查的 passed/failed/unknown/skipped、证据记录、阻断原因、是否允许绑定或发布。测试运行器生成执行/断言事实;来源存在、引文一致、计算正确、领域结论分别报告。政策和结果字段应有版本化 schema,未知政策拒绝。
|
||||
|
||||
保留报告命令兼容性,提供清晰的机器裁决入口或明确 fail 选项;不要悄悄改变已有 CLI 的退出语义。发布政策可渐进:纯工具先证明程序行为,业务事实额外要求来源与适用条件,领域审阅按场景要求;不为所有函数强加人工审批。
|
||||
|
||||
**验收。** `sandbox failed`、模型声称“passed”、空证据、无效日期、地区不符、输入越界、测试未运行均不能被标成对应级别的 verified;缺证据与执行失败不同;实际通过的记录绑定内容摘要,修改后自动失效。
|
||||
|
||||
### M04 · P1:新语义复用协议尚未进入默认 Agent 学习与执行闭环
|
||||
|
||||
**现状。** [plugins/agent/eng.rs](../../plugins/agent/src/eng.rs) 的 `eng_reuse`、[knowledge/reuse.rs](../../src/knowledge/reuse.rs) 已输出 `discovery_only`、`bind_required`、`bind_targets`。这是真实进展,不再列为完全缺失。
|
||||
|
||||
但 [ext/ai/agent.mq.md](../../ext/ai/agent.mq.md) 的默认 `run` 仍以 route/resolve、agent-kb workbook、plan 为主;EFI 分支主要检查 create_allowed,未在该编排中找到 artifact.bind/execute 的完整消费。`run verify=True` 依据 `status==ok` 拼接 `verification="status: passed"`;随后可 maybe_learn/promote,并非调用 M03 所需的验证器。求道 BUILD 开启 `learn=True/promote=True` 后才做自己的 docgate,因此两层发布时序有冲突风险。
|
||||
|
||||
`build_step_context` 的 CALL 白名单只有名字协议;parent CALL 支持 ARGS 的能力与 step 工具路径不同。求道若要调用精确制品与输入,需要正式适配,不能在提示词中虚构已可调用的工具。
|
||||
|
||||
**交付。** 提供现有 Runtime 内的适配步骤:discover → inspect → bind → execute → record。执行工具使用宿主选择的 project/KB/policy,LLM 只提交候选及输入。REUSE 只有在绑定执行成功且有 trace 后计为实际复用;ADAPT 用现有 patch/extract 形成可审阅修改;CREATE 保留检索范围与原因。
|
||||
|
||||
提供产品可接入的发布前验证钩子或 candidate-only 模式:产品门禁失败时框架也不能先把技能标为可复用。知识文件、技能、episode 可以保留不同存储职责,但都关联同一版本化 artifact/evidence;不要新增另一套知识语义。
|
||||
|
||||
**验收。** 用真实 `agent.run` 编排和确定性假模型/工具响应验证,而不只直调 MLSP:已有知识被调用、无同义实现新增;错误来源/错输入被拒绝;验证失败无 promote;trace 对应符号、摘要、输入与输出。不得将 n-gram 高分或字符串 REUSE 当作成功。
|
||||
|
||||
### M05 · P0/P1:提供给模型的语言 Skill 与当前语法冲突
|
||||
|
||||
**源码事实。** [skills/marqdo/SKILL.md](../../skills/marqdo/SKILL.md) 前部 Hard rules 2/4 和 v0.2 表仍写“粗体是返回”、斜体是语句,旧 `[key](map)` 取元也仍在前部。后面虽有 v2.1 默认 Occlusion 段落,不能消除同一提示包的冲突。
|
||||
|
||||
[host/agent_rt.rs](../../src/host/agent_rt.rs) 的 `load_marqdo_skill/read_skill_pack` 加载 Skill/reference/examples;[agent.skill_brief](../../ext/ai/agent.mq.md) 默认只取前 1200 字符/80 行,deep 预算 4000 字符。因此旧规则可能优先进入窗口,新的说明反而被截掉。实际读取哪个包受 MARQDO_SKILL 和搜索路径影响,部署须记录真实来源,不能假定总在读工作区文件。
|
||||
|
||||
**交付。** 从现行核心表面、解析器与金样例维护一份版本化语法卡片,最前面即当前含义:`**…**` 代码、`*…*` 返回、`[描述](payload)`、`access`、显式 import/遍历、正文惰性。旧语法迁入独立迁移卡片,不继续与默认规则并列。模型可按需取契约、来源、表格、类/函数等卡片;语言核心规则和权限边界不可被预算截掉。
|
||||
|
||||
使用已有 MLSP syntax/schema/validate/repair 能力,但明确 validate 的范围:当前主要是契约/标签检查,不等于完整事实、所有变量/调用和业务验证。诊断附 span、相关源码、目标语法版本及建议修复范围;优先局部 patch,避免整篇重生成。
|
||||
|
||||
**验收。** `dump_step_context` 和 plan 上下文的脱敏快照中没有冲突规则;基础/deep 预算均保留必需语法。卡片中可执行示例在当前 CLI 双后端通过;同一批含旧取元、错误返回、表格几何误用、缺 import 的负例给明确诊断。记录实际 skill path/hash、CLI/Ext/schema/prompt 版本。
|
||||
|
||||
### M06 · P1:整代发布已存在,但扫描范围与消费者一致性仍需约束
|
||||
|
||||
**现状。** [IR](../../src/sema/ir.rs)已将语义投影写 generations,再原子替换 CURRENT;遵循 `semantic_generation_dir` 的读者可获得完整语义代。但随后还写根目录兼容镜像,[knowledge.compile](../../src/knowledge/compile.rs)另写 engineering.yaml / ekc 等检索投影;不能把语义代原子性推广为“所有消费者、所有索引都属于同一代”。并发构建共用 CURRENT.tmp、.tmp-sema-publish,需明确串行化或独占发布规则。
|
||||
|
||||
[project 扫描器](../../src/project/mod.rs)与 [EKC extract](../../src/knowledge/extract.rs)的排除集不同,后者遍历子目录时排除 data/docker,前者不排除 data。求道有多个原文、候选和运行目录,导入 `.mq.md` 后可能在不同消费者里出现不同可见性。已有 .marqdo 排除、深度/文件大小/数量限制值得保留,但尚不能替代显式源范围和信任范围。
|
||||
|
||||
**交付。** 项目配置声明 authored sources、corpus、draft/generated 的范围;语义、EKC、Agent/view 使用同一选择规则。发布 manifest 关联语义代、检索代、源码/证据摘要和 schema;消费者拒绝混代并能回退到旧完整代。多库使用独立项目身份,索引聚合不扩大执行文件范围。
|
||||
|
||||
**验收。** 暂存上传代码不会进入活动能力;data/ 路径不会因消费者不同而忽隐忽现;并发编译/失败注入期间读者只看到一套可用版本;旧索引可重建,源文档不受损。迁移期明确旧 graph 路径兼容期限。
|
||||
|
||||
### M07 · P1:来源粒度和知识类型不足以覆盖文档沉淀
|
||||
|
||||
**现状。** 来源主要来自模块 frontmatter,容易将一整篇资料附给该文件所有函数;SourceRef 有 uri/locator/digest,但缺少标准的“具体断言 → 原文片段/表格单元/页码 → 提取版本”关联。普通 EKC `KnowledgeKind` 有 Fact/Decision/Constraint 等,而语义 artifact 主要是 module/type/function;旧 `.md` Fact 的存在不等于可调用事实函数。作者写来源 inline list 时当前解析器会忽略,未知字段也缺少强诊断。
|
||||
|
||||
**交付。** 用现有 Markdown/frontmatter/契约表定义轻量知识约定,而不增加求道专属语法:可选的函数/断言级来源、适用范围、单位、负例、冲突/取代关系。明确知识内容类型与运行时类型的区别;事实可以是返回值、规则可以是函数、决策可以是声明性文档,类只用于真实模式复用。
|
||||
|
||||
由编译器生成身份、图边和 SourceRef,作者只维护实际内容与必要来源。为 plain note → draft fact/rule → verified callable 提供金样例和机器可读投影,不能仅把文本包在一个 print 中。字段不支持或位置错误时给诊断,避免“写了来源,编译却无声忽略”。
|
||||
|
||||
**验收。** 一文多来源、一事实多来源、原文冲突、缺失字段、单位不同、来源片段变化、声明性决策和可执行规则都能区分;无依据的信息保持 unknown;不要求每个纯工具函数带业务来源。
|
||||
|
||||
### M08 · P1/P2:生成式知识验收与真实复用评估不足
|
||||
|
||||
**现状。** 既有 26 项集成测试和 100 单元是有效基础,但不覆盖资料导入/模型沉淀全过程。现有 `eng_reuse` 协议测试证明 JSON 字段,不证明默认 Agent 调用了句柄;MLSP 直调测试证明本地纯函数复用,不证明模型按正确来源建库。测试 README、旧路线和示例中存在历史状态残留;此次 closure 测试失败也说明“done”必须和当前门禁分开。
|
||||
|
||||
**交付。** 两层评测:确定性 fixtures 验证协议和失败边界,固定任务集验证模型沉淀质量。每个样本保存原文、期望知识、可执行断言、来源定位、错误复用反例、实际上下文及版本;明确事实正确率与程序运行率不同。性能指标包括编译/检索延迟、上下文规模、修复轮次、真实 token、知识重复率和误晋升率。
|
||||
|
||||
**验收。** 用同一资料完成“首次建库→再次调用→原文更新→旧知识失效→修复发布”的完整故事;包括断网/缺插件/截断/OCR 错误/资料内指令/冲突来源。只统计有目标与结果 trace 的执行复用,不按 REUSE 决策估算零推理成本。核心发布门禁不能以 skip 计成功。
|
||||
|
||||
## 4. 建议的跨库接口边界
|
||||
|
||||
下表是待实现或待稳定的契约,不暗示现在已有同名函数/CLI。
|
||||
|
||||
| 契约 | Marqdo 保证 | 求道负责 |
|
||||
|---|---|---|
|
||||
| Document extraction | 原件摘要、标准正文、定位、诊断;扩展层实现格式转换 | 上传、任务、库范围、用户预览 |
|
||||
| Knowledge draft | 当前语法卡片、检查/修复、可调用元数据 | 事实/规则选择、提示词、冲突与去重决策 |
|
||||
| Verification report | 每个检查的真实状态、证据/制品摘要、阻断原因 | 项目政策、需要人工处理的歧义、发布编排 |
|
||||
| Artifact handle | 唯一身份、依赖/证据失效、宿主能力边界 | 提交候选与输入、记录实际使用和解释 |
|
||||
| Publish manifest | 一致的语义/索引代及可回滚读取 | 知识源码发布、迁移、当前活动版本 |
|
||||
| Trace | 实际目标、输入、输出、版本与执行结果 | 回答来源展示、知识质量指标、运行记录关联 |
|
||||
|
||||
现有 `artifact.*`、sandbox、knowledge 等接口优先扩展;新增 façade 必须复用它们。工具协议、输出 schema 与提示词版本一起管理。首次本地试点可以使用固定目录与已授权项目政策;远程多租户的身份、凭据和隔离单独验收,不能把本地 MLSP 直接当公网授权协议。
|
||||
|
||||
## 5. 实施顺序
|
||||
|
||||
| 阶段 | 工作 | 完成条件 |
|
||||
|---|---|---|
|
||||
| F0 正确性基线 | M02/M03/M05:闭包反例、证据失效、验证状态、语法卡片 | 现有测试全过;来源变更/删除拒绝旧 business handle;提示词不含冲突语法 |
|
||||
| F1 最小生产消费链 | M04 + 求道文本导入:candidate-only、验证钩子、绑定执行 trace | 同一资料第一次生成,第二次实际复用,门禁失败不学习发布 |
|
||||
| F2 来源与更新 | M06/M07:统一源范围、来源定位/影响、发布 manifest | 改原文能找全受影响对象,发布失败旧版本仍可用 |
|
||||
| F3 格式覆盖与评测 | M01/M08:PDF/DOCX/OCR 适配、资源限制、模型对照 | 文档可追溯,不完整提取显式报告,效果和失败分布有数据 |
|
||||
|
||||
框架不承担求道的登录界面、笔记列表、项目业务政策;求道不复制框架的 parser、binder、effect、lock 或执行器。无需为了这条主链先完成万能本体、全格式解析或远程授权平台。
|
||||
|
||||
## 6. 本轮可复核实验
|
||||
|
||||
### 6.1 当前门禁与失败复核
|
||||
|
||||
在框架仓库执行:
|
||||
|
||||
```bash
|
||||
cargo test --offline --locked --test executable_knowledge
|
||||
cargo test --offline --locked --test executable_knowledge \
|
||||
s5_closure_digest_moves_with_dependency -- --exact
|
||||
```
|
||||
|
||||
第一条结果为 25 passed、1 failed;第二条仍在 `tests/executable_knowledge.rs:586` 报 `caller closure digest must move with dependency`。两次比较结果相同。这是既有测试的执行结果;本次未修改其实现或断言。
|
||||
|
||||
审计开始时 `target/release/marqdo --version` 与旧 debug 都是 2.1.0;上述构建生成的 debug 是 2.1.1。后续最小实验使用新 debug,不能把旧 release 输出充当当前源码能力证据。
|
||||
|
||||
### 6.2 来源变化与旧句柄复现
|
||||
|
||||
以下程序仅在新建临时目录写测试文件,通过本地 MLSP 调用,不联网、不调用模型。构建当前 debug 后在仓库根运行:
|
||||
|
||||
```python
|
||||
import json
|
||||
import subprocess
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
binary = str(Path("target/debug/marqdo").resolve())
|
||||
root = Path(tempfile.mkdtemp(prefix="mq-source-audit-"))
|
||||
|
||||
def rpc(method, **params):
|
||||
req = json.dumps({"method": method, "params": params}) + "\n"
|
||||
proc = subprocess.run([binary, "mlsp"], input=req, text=True,
|
||||
capture_output=True, check=True)
|
||||
return json.loads(proc.stdout)
|
||||
|
||||
(root / "source.md").write_text("# rate\n\nrate = 0.13\n")
|
||||
(root / "facts.mq.md").write_text(
|
||||
"---\nsources:\n - source.md#missing-anchor\n"
|
||||
"applicability:\n region: CN\n valid_until: 2099-12-31\n"
|
||||
"---\n\n## rate\n\n*0.13*\n"
|
||||
)
|
||||
first = rpc("artifact.inspect", project=str(root), artifact_id="rate")["result"]
|
||||
handle = rpc("artifact.bind", project=str(root), artifact_id="rate",
|
||||
policy="business")["result"]["handle"]
|
||||
(root / "source.md").write_text("# rate\n\nrate = 0.14\n")
|
||||
second = rpc("artifact.inspect", project=str(root), artifact_id="rate")["result"]
|
||||
print("evidence:", first["verification"]["evidence"])
|
||||
print("source changed:", first["provenance"][-1]["content_digest"] !=
|
||||
second["provenance"][-1]["content_digest"])
|
||||
print("artifact changed:", first["hashes"]["artifact"] !=
|
||||
second["hashes"]["artifact"])
|
||||
print("after edit:", rpc("artifact.execute", handle=handle, inputs={}))
|
||||
(root / "source.md").unlink()
|
||||
print("after removal:", rpc("artifact.execute", handle=handle, inputs={}))
|
||||
```
|
||||
|
||||
本轮观察:`evidence=sourced`、`source changed=True`、`artifact changed=False`;两次 execute 均 `ok=true`、result 为 `0.13`。正确修复后,缺锚点应先阻断相应来源政策;用有效锚点重新绑定后,改/删来源也应拒绝旧句柄或要求重验。不能只修复示例中的缺锚点而遗漏来源内容失效。
|
||||
|
||||
### 6.3 求道旧取元风险
|
||||
|
||||
以下代码在默认 2.1.1 中,第一行输出整个 map,第二行输出 False:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`m` =
|
||||
|
||||
| ok | status |
|
||||
|---|---|
|
||||
| False | denied |
|
||||
|
||||
**old = [ok](m)**
|
||||
**new = access(m, "ok")**
|
||||
> print text=`old`
|
||||
> print text=`new`
|
||||
```
|
||||
|
||||
这是默认语义变化,不是框架需要回退的新语法错误。求道需迁移;框架应提供一致的迁移指导、诊断和版本信息,而不是在 Skill 中继续教授冲突的旧默认。
|
||||
|
||||
## 7. 审计限制与后续文档同步
|
||||
|
||||
本次验证是源码审查、仓库固定测试和临时输入实验;没有执行真实 LLM 的建库质量评估,没有测试线上 Web 上传或真实 PDF/OCR。M01 的“缺少转换链”限定在所审查的主代码区域,不否定外部工具可以接入。M02 的闭包根因仍需按身份、依赖图、摘要计算分层定位。
|
||||
|
||||
完成后应同步当前 Skill、README、测试 README 和路线进度:分别标记语言能力、协议子集、产品已接入、当前测试结果。优先把失败样例转成稳定回归门禁,再扩大“可验证知识”“业务复用”“上传编译”的能力声明。此次文档提交不表示缺口已修复。
|
||||
+1
-1
@@ -1 +1 @@
|
||||
2.1.1
|
||||
2.1.3
|
||||
+83
-15
@@ -64,7 +64,7 @@ One LLM turn via the semantic surface (`ask` / `stream`+`collect`). Returns `{te
|
||||
1. `stream`
|
||||
**evs = > model.stream prompt=`prompt` echo=`echo`**
|
||||
**text = > llm.collect events=`evs`**
|
||||
**tokens = 0**
|
||||
**tokens = None**
|
||||
**err = None**
|
||||
**calls = 1**
|
||||
1. not `text`
|
||||
@@ -81,7 +81,7 @@ One LLM turn via the semantic surface (`ask` / `stream`+`collect`). Returns `{te
|
||||
1. `tokens`
|
||||
**_ = 1**
|
||||
2. *
|
||||
**tokens = 0**
|
||||
**tokens = None**
|
||||
1. `err`
|
||||
**calls = 0**
|
||||
2. `fin` == "error"
|
||||
@@ -183,7 +183,7 @@ Allowlist check, then invoke the runbook `##` via `lib/subtask` (`spawn fn=` →
|
||||
Build a runnable workbook. `skeleton=single` (default): one worker `step`. `skeleton=dual`: research then write agents. On success the parent chooses DONE; runtime `agent_workbook_solidify` freezes the answer.
|
||||
|
||||
**q = > json.quote text=`goal`**
|
||||
**esc = > json.parse text={"h":"---\ntitle: agent workbook\nimport:\n llm: ext/ai/llm.mq.md\n agent: ext/ai/agent.mq.md\n json: lib/json.mq.md\n sys: lib/sys.mq.md\n wb: lib/writeback.mq.md\n subtask: lib/subtask.mq.md\n---\n\n# Goal\n\nParent goal is embedded as JSON in # main.\n\n## Solidify\n\nWhen the child returns a good value, parent DECISION: DONE — runtime agent_workbook_solidify freezes the answer as **return** (do not invent long FIND/REPLACE).\n\n# main\n\n> llm.load_env\n\n","s1":"\u002a\u002a\u0060model\u0060 = > llm.llm\u002a\u002a\n","s2":"\u002a\u002a\u0060tools\u0060 = > table.empty_list\u002a\u002a\n","s3":"\u002a\u002a\u0060worker\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You are a workbook worker. tools=[] means never CALL. Finish the task with a direct final answer; do not invent tools.\u002a\u002a\n","s4":"\u002a\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","s5":"}\u002a\u002a\n","s6":"\u002a\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task\u002a\u002a\n","s7":"\u002a\u002a\u0060out\u0060 = > \u0060worker\u0060.step task=\u0060task\u0060 stream=False\u002a\u002a\n","s7b":"\u002a\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result\u002a\u002a\n","s8":"\u002a\u002a\u0060text\u0060\u002a\u002a\n","d3":"\u002a\u002a\u0060research\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You gather facts for the goal. Be concise. Do not invent tools.\u002a\u002a\n","d3b":"\u002a\u002a\u0060writer\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You write the final answer from research notes. Do not invent tools.\u002a\u002a\n","d4":"\u002a\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","d5":"}\u002a\u002a\n","d6":"\u002a\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task\u002a\u002a\n","d7":"\u002a\u002a\u0060notes\u0060 = > \u0060research\u0060.step task=\u0060task\u0060 stream=False\u002a\u002a\n","d8":"\u002a\u002a\u0060ns\u0060 = > json.stringify value=\u0060notes\u0060\u002a\u002a\n","d9":"\u002a\u002a\u0060wt\u0060 = Write the final answer. Research notes:\u002a\u002a\n","d10":"\u002a\u002a\u0060wt\u0060 = \u0060wt\u0060 + \u0060ns\u0060\u002a\u002a\n","d11":"\u002a\u002a\u0060out\u0060 = > \u0060writer\u0060.step task=\u0060wt\u0060 stream=False\u002a\u002a\n","d11b":"\u002a\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result\u002a\u002a\n","d12":"\u002a\u002a\u0060text\u0060\u002a\u002a\n"}**
|
||||
**esc = > json.parse text={"h":"---\ntitle: agent workbook\nimport:\n llm: ext/ai/llm.mq.md\n agent: ext/ai/agent.mq.md\n json: lib/json.mq.md\n sys: lib/sys.mq.md\n wb: lib/writeback.mq.md\n subtask: lib/subtask.mq.md\n---\n\n# Goal\n\nParent goal is embedded as JSON in # main.\n\n## Solidify\n\nWhen the child returns a good value, parent DECISION: DONE — runtime agent_workbook_solidify freezes the answer as **return** (do not invent long FIND/REPLACE).\n\n# main\n\n> llm.load_env\n\n","s1":"\u002a\u002a\u0060model\u0060 = > llm.create model=\u0060sys.env_get name=\"OPENAI_MODEL\"\u0060 base_url=\u0060sys.env_get name=\"OPENAI_BASE_URL\"\u0060 backend=openai name=workbook\u002a\u002a\n","s2":"\u002a\u002a\u0060tools\u0060 = > table.empty_list\u002a\u002a\n","s3":"\u002a\u002a\u0060worker\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You are a workbook worker. tools=[] means never CALL. Finish the task with a direct final answer; do not invent tools.\u002a\u002a\n","s4":"\u002a\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","s5":"}\u002a\u002a\n","s6":"\u002a\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task\u002a\u002a\n","s7":"\u002a\u002a\u0060out\u0060 = > \u0060worker\u0060.step task=\u0060task\u0060 stream=False\u002a\u002a\n","s7b":"\u002a\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result\u002a\u002a\n","s8":"\u002a\u002a\u0060text\u0060\u002a\u002a\n","d3":"\u002a\u002a\u0060research\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You gather facts for the goal. Be concise. Do not invent tools.\u002a\u002a\n","d3b":"\u002a\u002a\u0060writer\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You write the final answer from research notes. Do not invent tools.\u002a\u002a\n","d4":"\u002a\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","d5":"}\u002a\u002a\n","d6":"\u002a\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task\u002a\u002a\n","d7":"\u002a\u002a\u0060notes\u0060 = > \u0060research\u0060.step task=\u0060task\u0060 stream=False\u002a\u002a\n","d8":"\u002a\u002a\u0060ns\u0060 = > json.stringify value=\u0060notes\u0060\u002a\u002a\n","d9":"\u002a\u002a\u0060wt\u0060 = Write the final answer. Research notes:\u002a\u002a\n","d10":"\u002a\u002a\u0060wt\u0060 = \u0060wt\u0060 + \u0060ns\u0060\u002a\u002a\n","d11":"\u002a\u002a\u0060out\u0060 = > \u0060writer\u0060.step task=\u0060wt\u0060 stream=False\u002a\u002a\n","d11b":"\u002a\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result\u002a\u002a\n","d12":"\u002a\u002a\u0060text\u0060\u002a\u002a\n"}**
|
||||
**h = > json.get value=`esc` key="h"**
|
||||
**s1 = > json.get value=`esc` key="s1"**
|
||||
**s2 = > json.get value=`esc` key="s2"**
|
||||
@@ -849,25 +849,44 @@ Write a scratch tool workbook under `.marqdo/agent-runs/tools/<name>.mq.md`.
|
||||
|
||||
---
|
||||
|
||||
## skill_core_card
|
||||
|
||||
Protected v2.1 Occlusion card always prepended to skill_brief (M05). Must not be truncated by budget.
|
||||
|
||||
**esc = > json.parse text={"card":"## CORE SYNTAX (v2.1 Occlusion)\n1. Print with > print / > 打印 — never use bold markers to print.\n2. Bold markers = return/code; italic markers = statement.\n3. [desc](payload) = occlusion; brackets never execute.\n4. Read with access(coll, key) — never Classic [key](map) index.\n5. Foreach: - [desc](for coll as item). import + one language per file.\n6. # type · ## function · + params · numbered branches · - loops.\n"}**
|
||||
*> json.get value=`esc` key="card"*
|
||||
|
||||
---
|
||||
|
||||
## skill_brief
|
||||
+ `max_chars`=1200
|
||||
+ `depth`=default
|
||||
|
||||
Budgeted marqdo skill text for prompts. `depth=deep` raises the char budget.
|
||||
Budgeted marqdo skill text for prompts. Core Occlusion card is always included; remaining budget truncates the rest. `depth=deep` raises the char budget.
|
||||
|
||||
1. `depth` == deep
|
||||
**budget = 4000**
|
||||
2. *
|
||||
**budget = max_chars**
|
||||
**core = > skill_core_card**
|
||||
**core_len = > len value=`core`**
|
||||
**rest_budget = budget - core_len - 2**
|
||||
1. `rest_budget` < 200
|
||||
**rest_budget = 200**
|
||||
2. *
|
||||
**_ = 1**
|
||||
**skill = > agent_marqdo_skill**
|
||||
**full = > len value=`skill`**
|
||||
**ex = > text_head_lines text=`skill` max_lines=80 max_chars=`budget`**
|
||||
**rest = > text_head_lines text=`skill` max_lines=80 max_chars=`rest_budget`**
|
||||
**esc = > json.parse text={"nl":"\n\n"}**
|
||||
**nl = > json.get value=`esc` key="nl"**
|
||||
**ex = core + nl + rest**
|
||||
**used = > len value=`ex`**
|
||||
1. `used` < `full`
|
||||
**esc = > json.parse text={"a":"\n…[truncated skill_len=","b":" budget_chars=","c":"; emit READ:skill to deepen]"}**
|
||||
**a = > json.get value=`esc` key="a"**
|
||||
**b = > json.get value=`esc` key="b"**
|
||||
**c = > json.get value=`esc` key="c"**
|
||||
1. `used` < `full` + `core_len`
|
||||
**esc2 = > json.parse text={"a":"\n…[truncated skill_len=","b":" budget_chars=","c":"; emit READ:skill to deepen]"}**
|
||||
**a = > json.get value=`esc2` key="a"**
|
||||
**b = > json.get value=`esc2` key="b"**
|
||||
**c = > json.get value=`esc2` key="c"**
|
||||
*ex + a + full + b + budget + c*
|
||||
2. *
|
||||
*ex*
|
||||
@@ -1973,18 +1992,27 @@ O5: mark OKF skill `status: quarantine` and force `llm_free: false`. Regression
|
||||
+ `memory_dir`=.marqdo/agent-memory
|
||||
+ `improve_every`=3
|
||||
+ `promote`=True
|
||||
+ `candidate_only`=False
|
||||
+ `product_gate_ok`=True
|
||||
|
||||
Offline learn gate: when ≥ `improve_every` successful episodes share a task hash, generalize → synthesize → compile → optional OKF promote (`llm_free`). Also attempts Policy Compilation for Adaptive Routing.
|
||||
O2: promote path requires sandbox proof unless `require_proof=false`.
|
||||
M04: `candidate_only=True` or `product_gate_ok=False` forces promote off via eng_publish_gate.
|
||||
|
||||
**gate = > `self`.eng_publish_gate project="." candidate_only=`candidate_only` product_gate_ok=`product_gate_ok`**
|
||||
**may_prom = > json.get value=`gate` key="may_promote"**
|
||||
1. not `may_prom`
|
||||
**promote = False**
|
||||
2. *
|
||||
**_ = 1**
|
||||
**skill_learn = > agent_maybe_learn task=`task` kb_dir=`kb_dir` memory_dir=`memory_dir` improve_every=`improve_every` promote=`promote`**
|
||||
**policy_learn = > agent_maybe_compile_policy memory_dir=`memory_dir` min_evidence=`improve_every`**
|
||||
**sl = > json.get value=`skill_learn` key="learned"**
|
||||
`out` =
|
||||
|
||||
| learned | skill | policy |
|
||||
|---------|-------|--------|
|
||||
| `sl` | `skill_learn` | `policy_learn` |
|
||||
| learned | skill | policy | promote_allowed | gate |
|
||||
|---------|-------|--------|-----------------|------|
|
||||
| `sl` | `skill_learn` | `policy_learn` | `may_prom` | `gate` |
|
||||
|
||||
*out*
|
||||
|
||||
@@ -2128,7 +2156,18 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o
|
||||
1. `efi_st` == "missing_knowledge"
|
||||
**_ = 1**
|
||||
2. `efi_dec` == "REUSE"
|
||||
**_ = 1**
|
||||
**efi_exec = > agent_eng_bind_execute project="." query=`task` policy="pure" candidate_only=False**
|
||||
**efi_ok = > json.get value=`efi_exec` key="ok"**
|
||||
1. `efi_ok`
|
||||
**exec_mode = "efi_bound"**
|
||||
**out = **
|
||||
|
||||
| status | goal | result | summary | efi | reuse_trace |
|
||||
|--------|------|--------|---------|-----|-------------|
|
||||
| ok | `task` | `efi_exec` | EFI REUSE bound+executed | `efi_pf` | `efi_exec` |
|
||||
|
||||
2. *
|
||||
**_ = 1**
|
||||
3. `efi_dec` == "ADAPT"
|
||||
**_ = 1**
|
||||
4. `efi_allow`
|
||||
@@ -2433,13 +2472,42 @@ Hard rule: generate only when `create_allowed` is true (or decision is REUSE/ADA
|
||||
+ `root`="."
|
||||
+ `marqdo_dir`=None
|
||||
|
||||
Alias of `preflight` focused on REUSE / ADAPT / CREATE payload.
|
||||
Alias of `preflight` focused on REUSE / ADAPT / CREATE payload (discovery_only).
|
||||
|
||||
1. `marqdo_dir`
|
||||
*> agent_eng_reuse task=`task` root=`root` marqdo_dir=`marqdo_dir`*
|
||||
2. *
|
||||
*> agent_eng_reuse task=`task` root=`root`*
|
||||
|
||||
---
|
||||
|
||||
## eng_bind_execute
|
||||
+ `project`="."
|
||||
+ `query`
|
||||
+ `policy`="pure"
|
||||
+ `inputs`=None
|
||||
+ `candidate_only`=False
|
||||
|
||||
M04: discover → bind → execute → record. Prefer over treating eng_reuse scores as execution.
|
||||
|
||||
1. `inputs`
|
||||
*> agent_eng_bind_execute project=`project` query=`query` policy=`policy` inputs=`inputs` candidate_only=`candidate_only`*
|
||||
2. *
|
||||
*> agent_eng_bind_execute project=`project` query=`query` policy=`policy` candidate_only=`candidate_only`*
|
||||
|
||||
---
|
||||
|
||||
## eng_publish_gate
|
||||
+ `project`="."
|
||||
+ `artifact_id`=None
|
||||
+ `candidate_only`=False
|
||||
+ `product_gate_ok`=True
|
||||
+ `policy`="business"
|
||||
|
||||
Refuse promote when candidate_only or product/verification gate fails.
|
||||
|
||||
*> agent_eng_publish_gate project=`project` artifact_id=`artifact_id` candidate_only=`candidate_only` product_gate_ok=`product_gate_ok` policy=`policy`*
|
||||
|
||||
## eng_record
|
||||
+ `decision`
|
||||
+ `root`="."
|
||||
|
||||
+30
-15
@@ -156,6 +156,7 @@ Prompt artifact helper: `path=` loads a file; `text=` strips `type: prompt` fron
|
||||
|
||||
Module convenience: create a default handle and return **answer text**. Pass `path=` to load a prompt document, `prompt=` text, or omit both to use the entry `.mq.md` as a prompt artifact (`type: prompt` body via `sys.module_source`).
|
||||
|
||||
**p = `prompt`**
|
||||
1. `path`
|
||||
**p = > prompt_load path=`path`**
|
||||
2. `prompt`
|
||||
@@ -268,20 +269,26 @@ Prefer declaring `model` / `api_key` / `base_url` in frontmatter Binding, then u
|
||||
## ask
|
||||
+ `prompt`=None
|
||||
+ `path`=None
|
||||
+ `messages`=None
|
||||
+ `selection`=None
|
||||
+ `strict_selection`=False
|
||||
|
||||
Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `name`, `tool_calls`). Prefer `[text](result)` for the answer string. Omit `prompt=` / `path=` to use the entry document (`sys.module_source` + `prompt_body`).
|
||||
Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `name`, `tool_calls`). Prefer `[text](result)` for the answer string. Omit `prompt=` / `path=` to use the entry document (`sys.module_source` + `prompt_body`). Pass `messages=` for multi-turn history (M01). `selection=` + `strict_selection=True` freeze request identity without env fallback.
|
||||
|
||||
1. `path`
|
||||
**p = `prompt`**
|
||||
1. `messages`
|
||||
**p = None**
|
||||
2. `path`
|
||||
**p = > prompt_load path=`path`**
|
||||
2. `prompt`
|
||||
3. `prompt`
|
||||
**p = `prompt`**
|
||||
3. *
|
||||
4. *
|
||||
**raw = > sys.module_source**
|
||||
1. not `raw`
|
||||
**p = ""**
|
||||
2. *
|
||||
**p = > prompt_body src=`raw`**
|
||||
**pack = > self.complete_result prompt=`p` stream=False echo=False**
|
||||
**pack = > self.complete_result prompt=`p` messages=`messages` selection=`selection` strict_selection=`strict_selection` stream=False echo=False**
|
||||
**text = > json.get value=`pack` key="text"**
|
||||
**usage = > json.get value=`pack` key="usage"**
|
||||
**finish = > json.get value=`pack` key="finish"**
|
||||
@@ -312,11 +319,16 @@ inside the table is unsafe.
|
||||
**nm = > json.get value=`self` key="name"**
|
||||
1. `usage`
|
||||
**tt = > json.get value=`usage` key="total_tokens"**
|
||||
**ustate = > json.get value=`usage` key="usage_state"**
|
||||
2. *
|
||||
**tt = 0**
|
||||
1. not `tt`
|
||||
**tt = 0**
|
||||
2. *
|
||||
**tt = None**
|
||||
**ustate = "unknown"**
|
||||
1. `ustate` == "unknown"
|
||||
Keep null — never coerce missing usage to zero tokens (M02 / F04).
|
||||
**tt = None**
|
||||
2. not `tt`
|
||||
**tt = None**
|
||||
3. *
|
||||
**_ = 1**
|
||||
1. `err`
|
||||
**calls = 0**
|
||||
@@ -325,9 +337,9 @@ inside the table is unsafe.
|
||||
|
||||
`result` =
|
||||
|
||||
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls | error |
|
||||
|------|-------|--------|---------|-------|------|-----------|--------|------------|-------|
|
||||
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | `calls` | `tt` | `tc` | `err` |
|
||||
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls | error | selection |
|
||||
|------|-------|--------|---------|-------|------|-----------|--------|------------|-------|-----------|
|
||||
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | `calls` | `tt` | `tc` | `err` | `selection` |
|
||||
|
||||
*result*
|
||||
|
||||
@@ -352,13 +364,16 @@ Semantic stream: return the event list (use `llm.collect` to reduce to text). Om
|
||||
*> self.complete prompt=`p` stream=True echo=`echo`*
|
||||
|
||||
## complete_result
|
||||
+ `prompt`
|
||||
+ `prompt`=None
|
||||
+ `messages`=None
|
||||
+ `selection`=None
|
||||
+ `strict_selection`=False
|
||||
+ `stream`=False
|
||||
+ `echo`=False
|
||||
|
||||
Transport pack via `ext/ai/llm/openai` (Ollama uses the same OpenAI-compatible path). Non-stream → `{text,usage,finish}`; stream → `{events}`.
|
||||
Transport pack via `ext/ai/llm/openai` (Ollama uses the same OpenAI-compatible path). Non-stream → `{text,usage,finish}`; stream → `{events}`. Prefer `messages=` for multi-turn; optional `selection=` (ModelSelectionV1) with `strict_selection=True` for request-scoped identity (M01).
|
||||
|
||||
*> openai.chat_completions base_url=[base_url](access(self, "base_url")) api_key=[api_key](access(self, "api_key")) model=[model](access(self, "model")) prompt=`prompt` stream=`stream` echo=`echo` suffix=[suffix](access(self, "suffix")) bearer=[bearer](access(self, "bearer"))*
|
||||
*> openai.chat_completions base_url=[base_url](access(self, "base_url")) api_key=[api_key](access(self, "api_key")) model=[model](access(self, "model")) prompt=`prompt` messages=`messages` selection=`selection` strict_selection=`strict_selection` stream=`stream` echo=`echo` suffix=[suffix](access(self, "suffix")) bearer=[bearer](access(self, "bearer"))*
|
||||
|
||||
## complete
|
||||
+ `prompt`
|
||||
|
||||
+15
-6
@@ -73,7 +73,11 @@ Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
|
||||
+ `base_url`
|
||||
+ `api_key`
|
||||
+ `model`
|
||||
+ `prompt`
|
||||
+ `prompt`=None
|
||||
+ `messages`=None
|
||||
+ `selection`=None
|
||||
+ `strict_selection`=False
|
||||
+ `auth_mode`=None
|
||||
+ `stream`=False
|
||||
+ `echo`=False
|
||||
+ `suffix`=/chat/completions
|
||||
@@ -81,20 +85,25 @@ Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
|
||||
|
||||
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).
|
||||
|
||||
Pass either `messages=` (role/content list) or legacy `prompt=` (single user message). Optional `selection=` is a ModelSelectionV1 snapshot; `strict_selection=True` refuses env fallbacks inside the plugin.
|
||||
|
||||
**p = > plugin.native_path name="llm"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
*> llm_chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` stream=`stream` echo=`echo` suffix=`suffix` bearer=`bearer`*
|
||||
*> llm_chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` messages=`messages` selection=`selection` strict_selection=`strict_selection` auth_mode=`auth_mode` stream=`stream` echo=`echo` suffix=`suffix` bearer=`bearer`*
|
||||
2. *
|
||||
**url = base_url + suffix**
|
||||
**auth = bearer + api_key**
|
||||
**headers = > table.put in=None at="Authorization" value=`auth`**
|
||||
|
||||
`messages` =
|
||||
1. not `messages`
|
||||
`messages` =
|
||||
|
||||
| @ | role | content |
|
||||
|---|------|---------|
|
||||
| 1 | user | `prompt` |
|
||||
| @ | role | content |
|
||||
|---|------|---------|
|
||||
| 1 | user | `prompt` |
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
`req` =
|
||||
|
||||
|
||||
@@ -501,6 +501,175 @@ pub fn eng_reuse(args: &Value) -> Result<Value, String> {
|
||||
Ok(pf)
|
||||
}
|
||||
|
||||
/// M04: discover → inspect → bind → execute → record (actual reuse, not n-gram REUSE).
|
||||
///
|
||||
/// Requires host_query `mlsp`. Returns trace with artifact_id, digests, inputs, result.
|
||||
/// Does **not** promote skills — callers pass `candidate_only=true` to skip learn/promote.
|
||||
pub fn eng_bind_execute(args: &Value) -> Result<Value, String> {
|
||||
let project = args
|
||||
.get("project")
|
||||
.or_else(|| args.get("root"))
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(".");
|
||||
let policy = args
|
||||
.get("policy")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("pure");
|
||||
let inputs = args.get("inputs").cloned().unwrap_or(json!({}));
|
||||
let query = if let Some(q) = args.get("artifact_id").or_else(|| args.get("query")).and_then(|v| v.as_str()) {
|
||||
q.to_string()
|
||||
} else {
|
||||
// Fall back to first bind_target from eng_reuse.
|
||||
let reuse = eng_reuse(args)?;
|
||||
let targets = reuse
|
||||
.get("bind_targets")
|
||||
.and_then(|v| v.as_array())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
targets
|
||||
.first()
|
||||
.and_then(|t| t.get("query").and_then(|q| q.as_str()))
|
||||
.ok_or_else(|| {
|
||||
"eng_bind_execute: no artifact_id/query and eng_reuse returned no bind_targets"
|
||||
.to_string()
|
||||
})?
|
||||
.to_string()
|
||||
};
|
||||
|
||||
let inspect = crate::host_query_json_args(
|
||||
"mlsp",
|
||||
&json!({"method":"artifact.inspect","params":{"project":project,"artifact_id":&query}}),
|
||||
)?;
|
||||
if inspect.get("ok") != Some(&json!(true)) {
|
||||
return Ok(json!({
|
||||
"ok": false,
|
||||
"stage": "inspect",
|
||||
"error": inspect.get("error").cloned().unwrap_or(json!("inspect failed")),
|
||||
"query": query,
|
||||
}));
|
||||
}
|
||||
let artifact_id = inspect["result"]["artifact_id"]
|
||||
.as_str()
|
||||
.unwrap_or(&query)
|
||||
.to_string();
|
||||
|
||||
let bound = crate::host_query_json_args(
|
||||
"mlsp",
|
||||
&json!({"method":"artifact.bind","params":{"project":project,"artifact_id":&artifact_id,"policy":policy}}),
|
||||
)?;
|
||||
if bound.get("ok") != Some(&json!(true)) {
|
||||
return Ok(json!({
|
||||
"ok": false,
|
||||
"stage": "bind",
|
||||
"error": bound.get("error").cloned().unwrap_or(json!("bind failed")),
|
||||
"artifact_id": artifact_id,
|
||||
"discovery_only": false,
|
||||
}));
|
||||
}
|
||||
let handle = bound["result"]["handle"].clone();
|
||||
|
||||
let executed = crate::host_query_json_args(
|
||||
"mlsp",
|
||||
&json!({"method":"artifact.execute","params":{"handle":&handle,"inputs":inputs}}),
|
||||
)?;
|
||||
if executed.get("ok") != Some(&json!(true)) {
|
||||
return Ok(json!({
|
||||
"ok": false,
|
||||
"stage": "execute",
|
||||
"error": executed.get("error").cloned().unwrap_or(json!("execute failed")),
|
||||
"artifact_id": artifact_id,
|
||||
"handle": handle,
|
||||
}));
|
||||
}
|
||||
|
||||
// Record only after successful bind+execute (actual reuse).
|
||||
let _ = eng_record(&json!({
|
||||
"decision": "REUSE",
|
||||
"root": project,
|
||||
"marqdo_dir": args.get("marqdo_dir"),
|
||||
}));
|
||||
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"stage": "executed",
|
||||
"discovery_only": false,
|
||||
"bind_required": false,
|
||||
"actual_reuse": true,
|
||||
"artifact_id": artifact_id,
|
||||
"symbol_id": handle.get("symbol_id"),
|
||||
"digest": handle.get("digest"),
|
||||
"evidence_digest": handle.get("evidence_digest"),
|
||||
"closure_digest": handle.get("closure_digest"),
|
||||
"policy": policy,
|
||||
"inputs": inputs,
|
||||
"result": executed.get("result"),
|
||||
"candidate_only": args.get("candidate_only").and_then(|v| v.as_bool()).unwrap_or(false),
|
||||
"trace": {
|
||||
"artifact_id": artifact_id,
|
||||
"symbol_id": handle.get("symbol_id"),
|
||||
"digest": handle.get("digest"),
|
||||
"inputs": inputs,
|
||||
"stdout": executed["result"]["stdout"],
|
||||
"value": executed["result"]["result"],
|
||||
},
|
||||
}))
|
||||
}
|
||||
|
||||
/// Gate promote/learn: when `candidate_only` or may_bind=false, refuse promotion.
|
||||
pub fn eng_publish_gate(args: &Value) -> Result<Value, String> {
|
||||
let candidate_only = matches!(args.get("candidate_only"), Some(Value::Bool(true)));
|
||||
let product_ok = !matches!(args.get("product_gate_ok"), Some(Value::Bool(false)));
|
||||
let project = args
|
||||
.get("project")
|
||||
.or_else(|| args.get("root"))
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(".");
|
||||
let policy = args
|
||||
.get("policy")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("business");
|
||||
let artifact = args
|
||||
.get("artifact_id")
|
||||
.or_else(|| args.get("query"))
|
||||
.and_then(|v| v.as_str());
|
||||
|
||||
if candidate_only {
|
||||
return Ok(json!({
|
||||
"ok": true,
|
||||
"may_promote": false,
|
||||
"reason": "candidate_only — framework must not promote",
|
||||
}));
|
||||
}
|
||||
if !product_ok {
|
||||
return Ok(json!({
|
||||
"ok": true,
|
||||
"may_promote": false,
|
||||
"reason": "product gate failed — framework must not promote",
|
||||
}));
|
||||
}
|
||||
if let Some(id) = artifact {
|
||||
let adj = crate::host_query_json_args(
|
||||
"mlsp",
|
||||
&json!({"method":"artifact.verify","params":{"project":project,"artifact_id":id,"policy":policy}}),
|
||||
)?;
|
||||
let may_bind = adj
|
||||
.pointer("/result/may_bind")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(false);
|
||||
return Ok(json!({
|
||||
"ok": true,
|
||||
"may_promote": may_bind,
|
||||
"verification": adj.get("result"),
|
||||
"reason": if may_bind { "verification allows bind" } else { "verification denied bind" },
|
||||
}));
|
||||
}
|
||||
Ok(json!({
|
||||
"ok": true,
|
||||
"may_promote": product_ok,
|
||||
"reason": "no artifact_id; deferred to product_gate_ok",
|
||||
}))
|
||||
}
|
||||
|
||||
/// `agent_eng_record` — append reuse metrics under `.marqdo/agent/episodes`.
|
||||
pub fn eng_record(args: &Value) -> Result<Value, String> {
|
||||
let decision = arg_text(args, "decision")?;
|
||||
|
||||
@@ -831,6 +831,8 @@ kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear");
|
||||
kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list");
|
||||
kb_ffi!(agent_eng_preflight, eng::eng_preflight, "agent_eng_preflight");
|
||||
kb_ffi!(agent_eng_reuse, eng::eng_reuse, "agent_eng_reuse");
|
||||
kb_ffi!(agent_eng_bind_execute, eng::eng_bind_execute, "agent_eng_bind_execute");
|
||||
kb_ffi!(agent_eng_publish_gate, eng::eng_publish_gate, "agent_eng_publish_gate");
|
||||
kb_ffi!(agent_eng_record, eng::eng_record, "agent_eng_record");
|
||||
|
||||
#[no_mangle]
|
||||
@@ -900,6 +902,8 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
|
||||
("agent_maybe_compile_policy", "memory_dir,min_evidence", agent_maybe_compile_policy),
|
||||
("agent_eng_preflight", "task", agent_eng_preflight),
|
||||
("agent_eng_reuse", "task", agent_eng_reuse),
|
||||
("agent_eng_bind_execute", "project,query,policy", agent_eng_bind_execute),
|
||||
("agent_eng_publish_gate", "project,artifact_id,candidate_only", agent_eng_publish_gate),
|
||||
("agent_eng_record", "decision", agent_eng_record),
|
||||
("sandbox_open", "", sandbox::sandbox_open),
|
||||
("sandbox_write", "", sandbox::sandbox_write),
|
||||
|
||||
+373
-22
@@ -44,21 +44,40 @@ fn read_limited(mut r: impl Read) -> Result<String, String> {
|
||||
String::from_utf8(buf).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Prefer null over zero when the provider omitted a field (ModelCallUsageV1 / F04).
|
||||
fn token_or_null(v: Option<i64>) -> Value {
|
||||
match v {
|
||||
Some(n) if n >= 0 => json!(n),
|
||||
_ => Value::Null,
|
||||
}
|
||||
}
|
||||
|
||||
fn usage_from(data: &Value) -> Value {
|
||||
let u = data.get("usage").cloned().unwrap_or(Value::Null);
|
||||
let pt = u.get("prompt_tokens").and_then(|v| v.as_i64()).unwrap_or(0);
|
||||
let ct = u
|
||||
.get("completion_tokens")
|
||||
.and_then(|v| v.as_i64())
|
||||
.unwrap_or(0);
|
||||
if u.is_null() || !u.is_object() {
|
||||
return json!({
|
||||
"prompt_tokens": Value::Null,
|
||||
"completion_tokens": Value::Null,
|
||||
"total_tokens": Value::Null,
|
||||
"usage_state": "unknown",
|
||||
"measurement_source": "none",
|
||||
});
|
||||
}
|
||||
let pt = u.get("prompt_tokens").and_then(|v| v.as_i64());
|
||||
let ct = u.get("completion_tokens").and_then(|v| v.as_i64());
|
||||
let tt = u
|
||||
.get("total_tokens")
|
||||
.and_then(|v| v.as_i64())
|
||||
.unwrap_or(pt + ct);
|
||||
.or_else(|| match (pt, ct) {
|
||||
(Some(a), Some(b)) => Some(a + b),
|
||||
_ => None,
|
||||
});
|
||||
json!({
|
||||
"prompt_tokens": pt,
|
||||
"completion_tokens": ct,
|
||||
"total_tokens": tt,
|
||||
"prompt_tokens": token_or_null(pt),
|
||||
"completion_tokens": token_or_null(ct),
|
||||
"total_tokens": token_or_null(tt),
|
||||
"usage_state": "final",
|
||||
"measurement_source": "provider",
|
||||
})
|
||||
}
|
||||
|
||||
@@ -72,10 +91,34 @@ fn tool_calls_from(data: &Value) -> Value {
|
||||
.unwrap_or_else(|| json!([]))
|
||||
}
|
||||
|
||||
fn cancel_requested() -> bool {
|
||||
if std::env::var("MARQDO_CANCEL")
|
||||
.map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
|
||||
.unwrap_or(false)
|
||||
{
|
||||
return true;
|
||||
}
|
||||
if let Ok(tok) = std::env::var("MARQDO_CANCEL_TOKEN") {
|
||||
let path = std::path::Path::new(&tok);
|
||||
if path.is_file() {
|
||||
if let Ok(body) = std::fs::read_to_string(path) {
|
||||
let t = body.trim();
|
||||
return t.is_empty() || t == "1" || t.eq_ignore_ascii_case("cancelled");
|
||||
}
|
||||
return true;
|
||||
}
|
||||
}
|
||||
false
|
||||
}
|
||||
|
||||
fn parse_sse_events(reader: impl BufRead, echo: bool) -> Result<Vec<Value>, String> {
|
||||
let mut events = Vec::new();
|
||||
let mut data_lines: Vec<String> = Vec::new();
|
||||
for line in reader.lines() {
|
||||
if cancel_requested() {
|
||||
events.push(json!({"type": "cancelled", "message": "MARQDO_CANCEL"}));
|
||||
return Ok(events);
|
||||
}
|
||||
let line = line.map_err(|e| e.to_string())?;
|
||||
if echo {
|
||||
eprint!("{line}\n");
|
||||
@@ -107,11 +150,106 @@ fn parse_sse_events(reader: impl BufRead, echo: bool) -> Result<Vec<Value>, Stri
|
||||
Ok(events)
|
||||
}
|
||||
|
||||
fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
let base_url = arg_text(args, "base_url")?;
|
||||
let api_key = arg_text(args, "api_key").unwrap_or("");
|
||||
let model = arg_text(args, "model")?;
|
||||
fn build_messages(args: &Value) -> Result<Value, String> {
|
||||
if let Some(arr) = args.get("messages").and_then(|v| v.as_array()) {
|
||||
if arr.is_empty() {
|
||||
return Err("messages array must not be empty".into());
|
||||
}
|
||||
// Validate minimal role/content shape; reject unsupported part types loudly.
|
||||
for (i, m) in arr.iter().enumerate() {
|
||||
let role = m.get("role").and_then(|r| r.as_str()).unwrap_or("");
|
||||
if role.is_empty() {
|
||||
return Err(format!("llm.unsupported_input: messages[{i}].role missing"));
|
||||
}
|
||||
if let Some(parts) = m.get("content").and_then(|c| c.as_array()) {
|
||||
for (j, p) in parts.iter().enumerate() {
|
||||
let ty = p.get("type").and_then(|t| t.as_str()).unwrap_or("text");
|
||||
if ty != "text" {
|
||||
return Err(format!(
|
||||
"llm.unsupported_input: messages[{i}].content[{j}] type={ty}"
|
||||
));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return Ok(Value::Array(arr.clone()));
|
||||
}
|
||||
let prompt = arg_text(args, "prompt")?;
|
||||
Ok(json!([{"role": "user", "content": prompt}]))
|
||||
}
|
||||
|
||||
fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
if cancel_requested() {
|
||||
return Ok(json!({
|
||||
"text": "",
|
||||
"usage": {
|
||||
"prompt_tokens": Value::Null,
|
||||
"completion_tokens": Value::Null,
|
||||
"total_tokens": Value::Null,
|
||||
"usage_state": "unknown",
|
||||
"measurement_source": "none",
|
||||
},
|
||||
"finish": "cancelled",
|
||||
"error": "cancelled",
|
||||
"tool_calls": [],
|
||||
"transport": "plugin",
|
||||
}));
|
||||
}
|
||||
// Strict selection mode: refuse env fallback when selection.strict is set.
|
||||
let strict = opt_bool(args, "strict_selection", false)
|
||||
|| args
|
||||
.get("selection")
|
||||
.and_then(|s| s.get("strict"))
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(false);
|
||||
let selection = args.get("selection").cloned();
|
||||
if strict {
|
||||
if selection.is_none() {
|
||||
return Err("llm.selection_missing:selection".into());
|
||||
}
|
||||
let sel = selection.as_ref().unwrap();
|
||||
for key in ["selection_id", "provider_id", "model_id", "upstream_model_id"] {
|
||||
if sel
|
||||
.get(key)
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.is_none()
|
||||
{
|
||||
return Err(format!("llm.selection_missing:{key}"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let base_url = match arg_text(args, "base_url") {
|
||||
Ok(u) => u,
|
||||
Err(_) if strict => return Err("llm.selection_missing:base_url".into()),
|
||||
Err(e) => return Err(e),
|
||||
};
|
||||
let auth_mode = opt_text(args, "auth_mode")
|
||||
.or_else(|| {
|
||||
selection
|
||||
.as_ref()
|
||||
.and_then(|s| s.get("auth_mode"))
|
||||
.and_then(|v| v.as_str())
|
||||
})
|
||||
.unwrap_or("api_key");
|
||||
let api_key = if auth_mode == "none" {
|
||||
""
|
||||
} else {
|
||||
arg_text(args, "api_key").unwrap_or("")
|
||||
};
|
||||
if strict && auth_mode != "none" && api_key.is_empty() {
|
||||
return Err("llm.selection_missing:api_key".into());
|
||||
}
|
||||
let model = selection
|
||||
.as_ref()
|
||||
.and_then(|s| s.get("upstream_model_id"))
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string())
|
||||
.or_else(|| arg_text(args, "model").ok().map(|s| s.to_string()))
|
||||
.ok_or_else(|| "missing text `model`".to_string())?;
|
||||
let messages = build_messages(args)?;
|
||||
let stream = opt_bool(args, "stream", false);
|
||||
let echo = opt_bool(args, "echo", false);
|
||||
let suffix = opt_text(args, "suffix").unwrap_or("/chat/completions");
|
||||
@@ -123,11 +261,20 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
}
|
||||
|
||||
let mut req_body = Map::new();
|
||||
req_body.insert("model".into(), Value::String(model.to_string()));
|
||||
req_body.insert(
|
||||
"messages".into(),
|
||||
json!([{"role": "user", "content": prompt}]),
|
||||
);
|
||||
req_body.insert("model".into(), Value::String(model.clone()));
|
||||
req_body.insert("messages".into(), messages);
|
||||
if let Some(params) = selection
|
||||
.as_ref()
|
||||
.and_then(|s| s.get("parameters"))
|
||||
.and_then(|p| p.as_object())
|
||||
{
|
||||
if let Some(max) = params.get("max_output_tokens").and_then(|v| v.as_u64()) {
|
||||
req_body.insert("max_tokens".into(), json!(max));
|
||||
}
|
||||
if let Some(temp) = params.get("temperature") {
|
||||
req_body.insert("temperature".into(), temp.clone());
|
||||
}
|
||||
}
|
||||
if stream {
|
||||
req_body.insert("stream".into(), Value::Bool(true));
|
||||
}
|
||||
@@ -193,11 +340,19 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
if status != 200 {
|
||||
return Ok(json!({
|
||||
"text": "",
|
||||
"usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
|
||||
"usage": {
|
||||
"prompt_tokens": Value::Null,
|
||||
"completion_tokens": Value::Null,
|
||||
"total_tokens": Value::Null,
|
||||
"usage_state": "unknown",
|
||||
"measurement_source": "none",
|
||||
},
|
||||
"finish": "error",
|
||||
"error": format!("HTTP {status}: {text}"),
|
||||
"tool_calls": [],
|
||||
"transport": "plugin",
|
||||
"requested_model": model,
|
||||
"resolved_model": model,
|
||||
}));
|
||||
}
|
||||
let data: Value = serde_json::from_str(&text).map_err(|e| e.to_string())?;
|
||||
@@ -208,9 +363,12 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
.and_then(|c0| c0.get("message"))
|
||||
.cloned()
|
||||
.unwrap_or(json!({}));
|
||||
// Some gateways (reasoning models) return null content + reasoning_content.
|
||||
let content = msg
|
||||
.get("content")
|
||||
.and_then(|v| v.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.or_else(|| msg.get("reasoning_content").and_then(|v| v.as_str()))
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
let fr = data
|
||||
@@ -221,32 +379,62 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("stop")
|
||||
.to_string();
|
||||
let resolved = data
|
||||
.get("model")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(model.as_str())
|
||||
.to_string();
|
||||
Ok(json!({
|
||||
"text": content,
|
||||
"usage": usage_from(&data),
|
||||
"finish": fr,
|
||||
"tool_calls": tool_calls_from(&data),
|
||||
"transport": "plugin",
|
||||
"requested_model": model,
|
||||
"resolved_model": resolved,
|
||||
"selection": selection.as_ref().map(|s| {
|
||||
let mut snap = s.clone();
|
||||
if let Some(obj) = snap.as_object_mut() {
|
||||
obj.remove("api_key");
|
||||
}
|
||||
snap
|
||||
}),
|
||||
}))
|
||||
}
|
||||
Err(ureq::Error::Status(code, r)) => {
|
||||
let text = read_limited(r.into_reader()).unwrap_or_default();
|
||||
Ok(json!({
|
||||
"text": "",
|
||||
"usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
|
||||
"usage": {
|
||||
"prompt_tokens": Value::Null,
|
||||
"completion_tokens": Value::Null,
|
||||
"total_tokens": Value::Null,
|
||||
"usage_state": "unknown",
|
||||
"measurement_source": "none",
|
||||
},
|
||||
"finish": "error",
|
||||
"error": format!("HTTP {code}: {text}"),
|
||||
"tool_calls": [],
|
||||
"transport": "plugin",
|
||||
"requested_model": model,
|
||||
"resolved_model": model,
|
||||
}))
|
||||
}
|
||||
Err(e) => Ok(json!({
|
||||
"text": "",
|
||||
"usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
|
||||
"usage": {
|
||||
"prompt_tokens": Value::Null,
|
||||
"completion_tokens": Value::Null,
|
||||
"total_tokens": Value::Null,
|
||||
"usage_state": "unknown",
|
||||
"measurement_source": "none",
|
||||
},
|
||||
"finish": "error",
|
||||
"error": format!("http POST {url}: {e}"),
|
||||
"tool_calls": [],
|
||||
"transport": "plugin",
|
||||
"requested_model": model,
|
||||
"resolved_model": model,
|
||||
})),
|
||||
}
|
||||
}
|
||||
@@ -274,5 +462,168 @@ unsafe extern "C" fn llm_ping(
|
||||
|
||||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||||
("llm_ping", "", llm_ping),
|
||||
("llm_chat_completions", "base_url,api_key,model,prompt,stream,echo,suffix,bearer", llm_chat_completions),
|
||||
("llm_chat_completions", "base_url,api_key,model,prompt,messages,selection,strict_selection,auth_mode,stream,echo,suffix,bearer", llm_chat_completions),
|
||||
]);
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn f03_messages_preserve_roles_and_reject_image() {
|
||||
let msgs = build_messages(&json!({
|
||||
"messages": [
|
||||
{"role": "system", "content": "rules"},
|
||||
{"role": "user", "content": "你好"},
|
||||
{"role": "assistant", "content": "先前"},
|
||||
{"role": "user", "content": "最新用户"}
|
||||
]
|
||||
}))
|
||||
.unwrap();
|
||||
let arr = msgs.as_array().unwrap();
|
||||
assert_eq!(arr.len(), 4);
|
||||
assert_eq!(arr[3]["role"], "user");
|
||||
assert_eq!(arr[3]["content"], "最新用户");
|
||||
|
||||
let err = build_messages(&json!({
|
||||
"messages": [{"role": "user", "content": [{"type": "image", "url": "x"}]}]
|
||||
}))
|
||||
.unwrap_err();
|
||||
assert!(err.contains("unsupported_input"), "{err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn f01_strict_selection_does_not_invent_env_model() {
|
||||
std::env::remove_var("MARQDO_CANCEL");
|
||||
std::env::remove_var("MARQDO_CANCEL_TOKEN");
|
||||
let err = chat_completions(&json!({
|
||||
"strict_selection": true,
|
||||
"base_url": "http://127.0.0.1:9",
|
||||
"api_key": "k",
|
||||
"prompt": "hi"
|
||||
// missing selection → must fail before any HTTP
|
||||
}))
|
||||
.unwrap_err();
|
||||
assert!(err.contains("selection_missing"), "{err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn f06_cancel_short_circuits_before_http() {
|
||||
// Prefer token file over process-global MARQDO_CANCEL to avoid parallel test races.
|
||||
let tok = std::env::temp_dir().join(format!("llm-cancel-{}", std::process::id()));
|
||||
std::fs::write(&tok, "cancelled").unwrap();
|
||||
std::env::set_var("MARQDO_CANCEL_TOKEN", &tok);
|
||||
let out = chat_completions(&json!({
|
||||
"base_url": "http://127.0.0.1:9",
|
||||
"api_key": "k",
|
||||
"model": "m",
|
||||
"prompt": "hi"
|
||||
}));
|
||||
std::env::remove_var("MARQDO_CANCEL_TOKEN");
|
||||
let _ = std::fs::remove_file(&tok);
|
||||
let out = out.unwrap();
|
||||
assert_eq!(out["finish"], "cancelled");
|
||||
}
|
||||
|
||||
/// F01: two local endpoints receive distinct models/auth — no cross-talk.
|
||||
#[test]
|
||||
fn f01_dual_endpoint_isolation() {
|
||||
use std::io::{Read, Write};
|
||||
use std::net::TcpListener;
|
||||
use std::sync::{Arc, Mutex};
|
||||
use std::thread;
|
||||
|
||||
fn spawn_mock(tag: &'static str, seen: Arc<Mutex<Vec<String>>>) -> String {
|
||||
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
|
||||
let addr = listener.local_addr().unwrap();
|
||||
thread::spawn(move || {
|
||||
if let Ok((mut stream, _)) = listener.accept() {
|
||||
let mut raw = Vec::new();
|
||||
let mut buf = [0u8; 4096];
|
||||
loop {
|
||||
let n = stream.read(&mut buf).unwrap_or(0);
|
||||
if n == 0 {
|
||||
break;
|
||||
}
|
||||
raw.extend_from_slice(&buf[..n]);
|
||||
if let Some(pos) = raw.windows(4).position(|w| w == b"\r\n\r\n") {
|
||||
let header = String::from_utf8_lossy(&raw[..pos]);
|
||||
let cl = header
|
||||
.lines()
|
||||
.find_map(|l| l.strip_prefix("Content-Length:"))
|
||||
.and_then(|v| v.trim().parse::<usize>().ok())
|
||||
.unwrap_or(0);
|
||||
let body_start = pos + 4;
|
||||
while raw.len() < body_start + cl {
|
||||
let n = stream.read(&mut buf).unwrap_or(0);
|
||||
if n == 0 {
|
||||
break;
|
||||
}
|
||||
raw.extend_from_slice(&buf[..n]);
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
let req = String::from_utf8_lossy(&raw).to_string();
|
||||
seen.lock().unwrap().push(format!("{tag}:{req}"));
|
||||
let body = r#"{"choices":[{"message":{"content":"ok"},"finish_reason":"stop"}],"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}"#;
|
||||
let resp = format!(
|
||||
"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
|
||||
body.len(),
|
||||
body
|
||||
);
|
||||
let _ = stream.write_all(resp.as_bytes());
|
||||
}
|
||||
});
|
||||
format!("http://{addr}")
|
||||
}
|
||||
|
||||
let seen_a = Arc::new(Mutex::new(Vec::new()));
|
||||
let seen_b = Arc::new(Mutex::new(Vec::new()));
|
||||
let url_a = spawn_mock("A", seen_a.clone());
|
||||
let url_b = spawn_mock("B", seen_b.clone());
|
||||
|
||||
let out_a = chat_completions(&json!({
|
||||
"base_url": url_a,
|
||||
"api_key": "key-a",
|
||||
"model": "model-a",
|
||||
"auth_mode": "api_key",
|
||||
"messages": [{"role":"user","content":"from-a"}],
|
||||
"selection": {
|
||||
"selection_id": "sel-a",
|
||||
"provider_id": "p-a",
|
||||
"model_id": "m-a",
|
||||
"upstream_model_id": "model-a",
|
||||
"strict": true
|
||||
},
|
||||
"strict_selection": true
|
||||
}))
|
||||
.unwrap();
|
||||
let out_b = chat_completions(&json!({
|
||||
"base_url": url_b,
|
||||
"api_key": "key-b",
|
||||
"model": "model-b",
|
||||
"auth_mode": "api_key",
|
||||
"messages": [{"role":"user","content":"from-b"}],
|
||||
"selection": {
|
||||
"selection_id": "sel-b",
|
||||
"provider_id": "p-b",
|
||||
"model_id": "m-b",
|
||||
"upstream_model_id": "model-b",
|
||||
"strict": true
|
||||
},
|
||||
"strict_selection": true
|
||||
}))
|
||||
.unwrap();
|
||||
|
||||
assert_eq!(out_a["finish"], "stop", "{out_a}");
|
||||
assert_eq!(out_b["finish"], "stop", "{out_b}");
|
||||
let a = seen_a.lock().unwrap().join("\n");
|
||||
let b = seen_b.lock().unwrap().join("\n");
|
||||
assert!(a.contains("model-a"), "A saw wrong model: {a}");
|
||||
assert!(a.contains("key-a") || a.contains("Authorization"), "{a}");
|
||||
assert!(!a.contains("model-b"), "A must not see B's model: {a}");
|
||||
assert!(b.contains("model-b"), "B saw wrong model: {b}");
|
||||
assert!(!b.contains("model-a"), "B must not see A's model: {b}");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
package httpx
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// F06: client-disconnect cancel bridge writes token file + MARQDO_CANCEL for llm plugin.
|
||||
func TestPropagateCancelSignal(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
tok := filepath.Join(dir, "cancel.tok")
|
||||
if err := os.WriteFile(tok, []byte("cancelled"), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
t.Setenv("MARQDO_CANCEL_TOKEN", tok)
|
||||
t.Setenv("MARQDO_CANCEL", "1")
|
||||
|
||||
if os.Getenv("MARQDO_CANCEL") != "1" {
|
||||
t.Fatalf("MARQDO_CANCEL not set")
|
||||
}
|
||||
body, err := os.ReadFile(tok)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(body) != "cancelled" {
|
||||
t.Fatalf("token body=%q", body)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,41 @@
|
||||
package httpx
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestDrainForwardReadsIncrementalLines(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "evt.ndjson")
|
||||
if err := os.WriteFile(path, []byte("{\"type\":\"a\"}\n{\"type\":\"b\"}\n"), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var lines []string
|
||||
off := drainForward(path, 0, func(line string) {
|
||||
lines = append(lines, line)
|
||||
})
|
||||
if len(lines) != 2 {
|
||||
t.Fatalf("got %d lines %#v", len(lines), lines)
|
||||
}
|
||||
if off <= 0 {
|
||||
t.Fatalf("offset=%d", off)
|
||||
}
|
||||
// Append after first drain — second call with offset must only see new line.
|
||||
f, err := os.OpenFile(path, os.O_APPEND|os.O_WRONLY, 0o600)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := f.WriteString("{\"type\":\"c\"}\n"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
_ = f.Close()
|
||||
var more []string
|
||||
off2 := drainForward(path, off, func(line string) {
|
||||
more = append(more, line)
|
||||
})
|
||||
if len(more) != 1 || more[0] != "{\"type\":\"c\"}" {
|
||||
t.Fatalf("incremental got %#v off=%d→%d", more, off, off2)
|
||||
}
|
||||
}
|
||||
@@ -1,11 +1,15 @@
|
||||
package httpx
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"os"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/plugin"
|
||||
)
|
||||
@@ -115,6 +119,15 @@ func (st *state) handleInvoke(w http.ResponseWriter, r *http.Request, route invo
|
||||
}
|
||||
|
||||
args := invokeArgsFromPayload(payload)
|
||||
|
||||
// M02: live SSE — stream host_stream_publish events while CallLibPath runs.
|
||||
// return=sse-live|sse_live uses MARQDO_EVENT_FORWARD NDJSON bridge (request-local).
|
||||
liveSSE := route.ReturnMode == "sse-live" || route.ReturnMode == "sse_live"
|
||||
if liveSSE {
|
||||
st.handleInvokeLiveSSE(w, r, route, args)
|
||||
return
|
||||
}
|
||||
|
||||
value, err := plugin.CallLibPath(route.FnPath, args)
|
||||
if err != nil {
|
||||
code := http.StatusInternalServerError
|
||||
@@ -176,3 +189,160 @@ func (st *state) handleInvoke(w http.ResponseWriter, r *http.Request, route invo
|
||||
writeJSON(w, code, body)
|
||||
}
|
||||
}
|
||||
|
||||
// handleInvokeLiveSSE streams RuntimeEvent-shaped lines while the lib call runs.
|
||||
// Client disconnect sets MARQDO_CANCEL + cancel token file so the llm plugin can stop.
|
||||
func (st *state) handleInvokeLiveSSE(w http.ResponseWriter, r *http.Request, route invokeRoute, args map[string]any) {
|
||||
dir := os.TempDir()
|
||||
fwd, err := os.CreateTemp(dir, "mq-evt-*.ndjson")
|
||||
if err != nil {
|
||||
jsonErr(w, http.StatusInternalServerError, fmt.Sprintf("event forward: %v", err))
|
||||
return
|
||||
}
|
||||
fwdPath := fwd.Name()
|
||||
_ = fwd.Close()
|
||||
defer os.Remove(fwdPath)
|
||||
|
||||
prev := os.Getenv("MARQDO_EVENT_FORWARD")
|
||||
_ = os.Setenv("MARQDO_EVENT_FORWARD", fwdPath)
|
||||
cancelFile, cancelErr := os.CreateTemp(dir, "mq-cancel-*.tok")
|
||||
cancelPath := ""
|
||||
if cancelErr == nil {
|
||||
cancelPath = cancelFile.Name()
|
||||
_ = cancelFile.Close()
|
||||
_ = os.Setenv("MARQDO_CANCEL_TOKEN", cancelPath)
|
||||
}
|
||||
defer func() {
|
||||
if prev == "" {
|
||||
_ = os.Unsetenv("MARQDO_EVENT_FORWARD")
|
||||
} else {
|
||||
_ = os.Setenv("MARQDO_EVENT_FORWARD", prev)
|
||||
}
|
||||
_ = os.Unsetenv("MARQDO_CANCEL_TOKEN")
|
||||
_ = os.Unsetenv("MARQDO_CANCEL")
|
||||
if cancelPath != "" {
|
||||
_ = os.Remove(cancelPath)
|
||||
}
|
||||
}()
|
||||
|
||||
w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
|
||||
w.Header().Set("Cache-Control", "no-cache")
|
||||
w.Header().Set("Connection", "keep-alive")
|
||||
w.Header().Set("X-Accel-Buffering", "no")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
flusher, _ := w.(http.Flusher)
|
||||
writeEvent := func(payload any) {
|
||||
b, err := json.Marshal(payload)
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
_, _ = io.WriteString(w, "data: "+string(b)+"\n\n")
|
||||
if flusher != nil {
|
||||
flusher.Flush()
|
||||
}
|
||||
}
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1",
|
||||
"schema_version": 1,
|
||||
"type": "run.started",
|
||||
"payload": map[string]any{"fn": route.FnPath, "bridge": "sse-live"},
|
||||
})
|
||||
|
||||
type callResult struct {
|
||||
value any
|
||||
err error
|
||||
}
|
||||
done := make(chan callResult, 1)
|
||||
go func() {
|
||||
v, e := plugin.CallLibPath(route.FnPath, args)
|
||||
done <- callResult{value: v, err: e}
|
||||
}()
|
||||
|
||||
var mu sync.Mutex
|
||||
offset := int64(0)
|
||||
seq := uint64(1)
|
||||
poll := time.NewTicker(25 * time.Millisecond)
|
||||
defer poll.Stop()
|
||||
|
||||
ctx := r.Context()
|
||||
for {
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
// Propagate cancel to in-flight LLM/plugin via token file + env.
|
||||
_ = os.Setenv("MARQDO_CANCEL", "1")
|
||||
if cancelPath != "" {
|
||||
_ = os.WriteFile(cancelPath, []byte("cancelled"), 0o600)
|
||||
}
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.interrupted",
|
||||
"payload": map[string]any{"reason": "client_disconnect", "cancel_propagated": cancelPath != ""},
|
||||
})
|
||||
return
|
||||
case res := <-done:
|
||||
// Drain remaining forward lines once.
|
||||
mu.Lock()
|
||||
offset = drainForward(fwdPath, offset, func(line string) {
|
||||
seq++
|
||||
var obj any
|
||||
if json.Unmarshal([]byte(line), &obj) == nil {
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1", "schema_version": 1,
|
||||
"seq": seq, "type": "message.delta", "payload": obj,
|
||||
})
|
||||
}
|
||||
})
|
||||
mu.Unlock()
|
||||
if res.err != nil {
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.failed",
|
||||
"payload": map[string]any{"error": res.err.Error()},
|
||||
})
|
||||
} else {
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.completed",
|
||||
"payload": map[string]any{"result": res.value},
|
||||
})
|
||||
}
|
||||
_, _ = io.WriteString(w, "data: [DONE]\n\n")
|
||||
if flusher != nil {
|
||||
flusher.Flush()
|
||||
}
|
||||
return
|
||||
case <-poll.C:
|
||||
mu.Lock()
|
||||
offset = drainForward(fwdPath, offset, func(line string) {
|
||||
seq++
|
||||
var obj any
|
||||
if json.Unmarshal([]byte(line), &obj) == nil {
|
||||
writeEvent(map[string]any{
|
||||
"schema": "RuntimeEventV1", "schema_version": 1,
|
||||
"seq": seq, "type": "message.delta", "payload": obj,
|
||||
})
|
||||
}
|
||||
})
|
||||
mu.Unlock()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func drainForward(path string, offset int64, onLine func(string)) int64 {
|
||||
f, err := os.Open(path)
|
||||
if err != nil {
|
||||
return offset
|
||||
}
|
||||
defer f.Close()
|
||||
if _, err := f.Seek(offset, io.SeekStart); err != nil {
|
||||
return offset
|
||||
}
|
||||
sc := bufio.NewScanner(f)
|
||||
sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
|
||||
for sc.Scan() {
|
||||
line := strings.TrimSpace(sc.Text())
|
||||
offset += int64(len(sc.Bytes()) + 1)
|
||||
if line == "" {
|
||||
continue
|
||||
}
|
||||
onLine(line)
|
||||
}
|
||||
return offset
|
||||
}
|
||||
@@ -81,7 +81,16 @@ func (st *state) handleUpload(w http.ResponseWriter, r *http.Request, routePath
|
||||
_, hadCookie := session.IDFromCookie(r.Header.Get("Cookie"))
|
||||
sid, _, setCookie := resolveSession(r)
|
||||
|
||||
if err := r.ParseMultipartForm(32 << 20); err != nil {
|
||||
// M01: hard-limit request body before multipart parse (32MiB was only in-memory
|
||||
// form budget, not a request total). Cap at configured MaxBytes + 1MiB overhead.
|
||||
maxBody := int64(cfg.MaxBytes)
|
||||
if maxBody <= 0 {
|
||||
maxBody = 32 << 20
|
||||
}
|
||||
overhead := int64(1 << 20)
|
||||
r.Body = http.MaxBytesReader(w, r.Body, maxBody+overhead)
|
||||
|
||||
if err := r.ParseMultipartForm(maxBody + overhead); err != nil {
|
||||
jsonErr(w, http.StatusBadRequest, fmt.Sprintf("multipart: %v", err))
|
||||
return
|
||||
}
|
||||
@@ -109,11 +118,20 @@ func (st *state) handleUpload(w http.ResponseWriter, r *http.Request, routePath
|
||||
return
|
||||
}
|
||||
defer f.Close()
|
||||
b, err := io.ReadAll(f)
|
||||
// Stream-capped read: never buffer more than MaxBytes.
|
||||
lim := maxBody
|
||||
if lim <= 0 {
|
||||
lim = 32 << 20
|
||||
}
|
||||
b, err := io.ReadAll(io.LimitReader(f, lim+1))
|
||||
if err != nil {
|
||||
jsonErr(w, http.StatusBadRequest, fmt.Sprintf("read file: %v", err))
|
||||
return
|
||||
}
|
||||
if int64(len(b)) > lim {
|
||||
jsonErr(w, http.StatusRequestEntityTooLarge, "file exceeds max_bytes")
|
||||
return
|
||||
}
|
||||
fileBytes = b
|
||||
} else {
|
||||
// Fallback: walk File map keys.
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
package httpx
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"mime/multipart"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestHandleUploadRejectsOversizedBeforeFullBuffer(t *testing.T) {
|
||||
st := &state{
|
||||
uploadRoutes: map[string]any{
|
||||
"/upload": map[string]any{
|
||||
"field": "file",
|
||||
"storage_url": "memory://t",
|
||||
"prefix": "u",
|
||||
"max_bytes": float64(64),
|
||||
},
|
||||
},
|
||||
}
|
||||
cfg := parseUploadRoute(st.uploadRoutes["/upload"])
|
||||
var body bytes.Buffer
|
||||
w := multipart.NewWriter(&body)
|
||||
part, err := w.CreateFormFile("file", "big.txt")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := part.Write([]byte(strings.Repeat("x", 200))); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
_ = w.Close()
|
||||
|
||||
req := httptest.NewRequest(http.MethodPost, "/upload", &body)
|
||||
req.Header.Set("Content-Type", w.FormDataContentType())
|
||||
rr := httptest.NewRecorder()
|
||||
st.handleUpload(rr, req, "/upload", cfg)
|
||||
if rr.Code == http.StatusOK {
|
||||
t.Fatalf("expected reject for oversized upload, got %d body=%s", rr.Code, rr.Body.String())
|
||||
}
|
||||
if rr.Code != http.StatusRequestEntityTooLarge && rr.Code != http.StatusBadRequest {
|
||||
t.Fatalf("expected 413 or 400, got %d body=%s", rr.Code, rr.Body.String())
|
||||
}
|
||||
}
|
||||
+36
-55
@@ -14,68 +14,49 @@ description: >-
|
||||
|
||||
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): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
<!-- CORE_SYNTAX_V2.1: must stay at the top so skill_brief budgets never truncate it -->
|
||||
|
||||
**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/*`.
|
||||
## CORE SYNTAX (v2.1 Occlusion — mandatory)
|
||||
|
||||
**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.
|
||||
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
|
||||
|
||||
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
|
||||
2. **`**…**` = code / return expression.** `*…*` = statement (bind / expr). Closing markers touch the last token (no trailing space).
|
||||
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
|
||||
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
|
||||
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
|
||||
6. **Import / call:** frontmatter `import:` / `导入:`; call `lib.member`. One language (EN or ZH) per file.
|
||||
7. **Control flow:** `#` object/type, `##`+ function, `+` params, `1.`/`2.` branches, `-` loops, `N. *` else. No invented `if`/`for`/`def`/`return` keywords.
|
||||
8. **Prose vs code:** blank line separates comment paragraphs from executable lines.
|
||||
9. **GFM tables** for data; prefer `table.put` over `json.set` chains. `ext/**` never calls `host_*`.
|
||||
10. Body narrative `[描述](target)` is lazy (NarrativeRef) — reading does not execute side effects.
|
||||
|
||||
| Marker | Meaning (v2.1) |
|
||||
|--------|----------------|
|
||||
| `#` / `##`+ | Object/type · function/method |
|
||||
| `*…*` | Statement |
|
||||
| `**…**` | Return / code expression |
|
||||
| `[描述](payload)` | Occlusion step (payload executes) |
|
||||
| `access(c, k)` | Collection read |
|
||||
| `> fn …` | Call |
|
||||
| GFM table | Collection literal |
|
||||
|
||||
Canonical: `doc/design/core-surface.md`, `doc/design/document-native-development-guide.md`. Deeper tables: [reference.md](reference.md). Patterns: [examples.md](examples.md). Authoring craft: [marqdo-dev](../marqdo-dev/SKILL.md). Release: [marqdo-release](../marqdo-release/SKILL.md).
|
||||
|
||||
Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md).
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
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. Read collections with **`[key](map)`**, not footnote indexes for new code. In `markup: occlusion` files read with **`access(map, key)`** — there `[x](y)` is occlusion, not index. **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.
|
||||
1. Obey **CORE SYNTAX** above — Occlusion is default; do not emit Classic index links.
|
||||
2. **Identifiers:** params `` + `name` ``; inside `*…*` / `**…**` bare ids are variables. Quote text literals. Standalone `>` calls: backticks where bare would be text.
|
||||
3. **Structure lines** (`#` `>` `+` `-` `|`) are not wrapped in italics.
|
||||
4. **Paths:** bare `/` in expressions is division; in call args / table cells unspaced `a/b` is path text. Ratios as text need quotes (`"1/5"`).
|
||||
5. End side-effect-only helpers with `*None*` / `*空*` / `**` / `****` when the outer function continues. Lone `---` is a thematic break, not function end.
|
||||
6. **`ext/**` never calls `host_*`.** Prefer tables over `json.set` / `json.append`.
|
||||
7. **One language per file.** Sandbox trial before promoting Agent-generated trees.
|
||||
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
|
||||
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
|
||||
| `##` … `######` | **Function / method** (nesting by heading depth). |
|
||||
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter nested `import:` / `导入:` map | Import file (`bind: path.mq.md`) or short name (`bind: lib.member`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | 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) |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
|
||||
## Occlusion syntax (v2.1 default)
|
||||
|
||||
**Default:** unmarked sources and `markup: occlusion` / `标记: 遮蔽` treat `[x](y)` as **occlusion** (description wraps payload), not classic index. Explicit Classic / `--legacy-markup` is a transition path only — do not teach `[键](集合)` as the default. Prefer `access(集合, 键)` for reads.
|
||||
|
||||
Executable-knowledge author baseline (six tasks, offline gate): [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md). Design goals ≠ shipped knowledge reuse; see [`doc/design/document-native-development-guide.md`](../../doc/design/document-native-development-guide.md).
|
||||
|
||||
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
|
||||
- `[顾客留存率](0.42)` · `[总价](access(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
|
||||
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
|
||||
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
|
||||
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
|
||||
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
# Classic markup migration card (not default)
|
||||
|
||||
Use this card **only** when editing files that declare `markup: classic` / `标记: 经典`, or when the CLI is run with `--legacy-markup`. New documents must use Occlusion (see SKILL.md CORE SYNTAX).
|
||||
|
||||
| Classic (legacy) | Occlusion / current |
|
||||
|---|---|
|
||||
| `[key](map)` index read | `access(map, "key")` / `取(map, "key")` |
|
||||
| `- [item](coll)` foreach by index form | `- [描述](遍历 coll 为 item)` |
|
||||
| Teach `**…**` as “the return of print” | Print with `> print`; `**…**` is return/code expression |
|
||||
| Default link = index | Default `[描述](payload)` = occlusion; `[]` never executes |
|
||||
|
||||
Do not place Classic rules in the front of the default Skill pack. After migration, remove `markup: classic` and verify with `marqdo run` / `marqdo check`.
|
||||
@@ -0,0 +1,299 @@
|
||||
//! Document extraction protocol (M01): DocumentSource → ExtractedDocument.
|
||||
//!
|
||||
//! Format parsers live here / in extensions — language core does not OCR.
|
||||
//! First slice: plain text and Markdown. PDF/DOCX plug in later via the same shape.
|
||||
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use sha2::{Digest, Sha256};
|
||||
use serde_json::{json, Value};
|
||||
|
||||
pub const EXTRACTOR_VERSION: &str = "marqdo-document-extract/1";
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct DocumentSource {
|
||||
pub path: std::path::PathBuf,
|
||||
pub format_hint: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ExtractedSegment {
|
||||
pub id: String,
|
||||
pub kind: String,
|
||||
pub text: String,
|
||||
pub locator: String,
|
||||
pub confidence: f64,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ExtractedDocument {
|
||||
pub source_uri: String,
|
||||
pub source_digest: String,
|
||||
pub format: String,
|
||||
pub extractor_version: String,
|
||||
pub text: String,
|
||||
pub segments: Vec<ExtractedSegment>,
|
||||
pub missing: Vec<String>,
|
||||
pub diagnostics: Vec<String>,
|
||||
pub status: String,
|
||||
}
|
||||
|
||||
impl ExtractedDocument {
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"schema_version": 1,
|
||||
"source_uri": self.source_uri,
|
||||
"source_digest": self.source_digest,
|
||||
"format": self.format,
|
||||
"extractor_version": self.extractor_version,
|
||||
"status": self.status,
|
||||
"text": self.text,
|
||||
"segments": self.segments.iter().map(|s| json!({
|
||||
"id": s.id,
|
||||
"kind": s.kind,
|
||||
"text": s.text,
|
||||
"locator": s.locator,
|
||||
"confidence": s.confidence,
|
||||
})).collect::<Vec<_>>(),
|
||||
"missing": self.missing,
|
||||
"diagnostics": self.diagnostics,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Extract text/Markdown from a file. Uploaded `.mq.md` is treated as untrusted
|
||||
/// source text and is never executed here.
|
||||
pub fn extract_document(source: &DocumentSource) -> ExtractedDocument {
|
||||
let path = &source.path;
|
||||
let uri = path.to_string_lossy().replace('\\', "/");
|
||||
let ext = path
|
||||
.extension()
|
||||
.and_then(|e| e.to_str())
|
||||
.unwrap_or("")
|
||||
.to_ascii_lowercase();
|
||||
let name = path
|
||||
.file_name()
|
||||
.and_then(|n| n.to_str())
|
||||
.unwrap_or("")
|
||||
.to_ascii_lowercase();
|
||||
|
||||
let format = source
|
||||
.format_hint
|
||||
.clone()
|
||||
.unwrap_or_else(|| {
|
||||
if name.ends_with(".mq.md") || ext == "md" {
|
||||
"markdown".into()
|
||||
} else if matches!(ext.as_str(), "txt" | "text") {
|
||||
"text".into()
|
||||
} else if matches!(ext.as_str(), "pdf" | "docx") {
|
||||
ext.clone()
|
||||
} else {
|
||||
"unknown".into()
|
||||
}
|
||||
});
|
||||
|
||||
if matches!(
|
||||
format.as_str(),
|
||||
"pdf" | "docx" | "ocr" | "png" | "jpg" | "jpeg" | "webp" | "tiff"
|
||||
) || matches!(ext.as_str(), "pdf" | "docx" | "png" | "jpg" | "jpeg" | "webp" | "tiff")
|
||||
{
|
||||
let kind = if matches!(format.as_str(), "ocr")
|
||||
|| matches!(ext.as_str(), "png" | "jpg" | "jpeg" | "webp" | "tiff")
|
||||
{
|
||||
"ocr/image".to_string()
|
||||
} else {
|
||||
format.clone()
|
||||
};
|
||||
return ExtractedDocument {
|
||||
source_uri: uri,
|
||||
source_digest: String::new(),
|
||||
format,
|
||||
extractor_version: EXTRACTOR_VERSION.into(),
|
||||
text: String::new(),
|
||||
segments: vec![],
|
||||
missing: vec!["full_document".into()],
|
||||
diagnostics: vec![format!(
|
||||
"format `{kind}` requires an external extractor plugin (not in core); incomplete extraction is explicit failure"
|
||||
)],
|
||||
status: "failed".into(),
|
||||
};
|
||||
}
|
||||
|
||||
let bytes = match fs::read(path) {
|
||||
Ok(b) => b,
|
||||
Err(e) => {
|
||||
return ExtractedDocument {
|
||||
source_uri: uri,
|
||||
source_digest: String::new(),
|
||||
format,
|
||||
extractor_version: EXTRACTOR_VERSION.into(),
|
||||
text: String::new(),
|
||||
segments: vec![],
|
||||
missing: vec!["full_document".into()],
|
||||
diagnostics: vec![format!("read error: {e}")],
|
||||
status: "failed".into(),
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
if bytes.is_empty() {
|
||||
return ExtractedDocument {
|
||||
source_uri: uri,
|
||||
source_digest: digest_bytes(&bytes),
|
||||
format,
|
||||
extractor_version: EXTRACTOR_VERSION.into(),
|
||||
text: String::new(),
|
||||
segments: vec![],
|
||||
missing: vec!["content".into()],
|
||||
diagnostics: vec!["empty document".into()],
|
||||
status: "failed".into(),
|
||||
};
|
||||
}
|
||||
|
||||
// Resource limit: refuse to fully buffer huge uploads as text (M01).
|
||||
const MAX_EXTRACT_BYTES: usize = 8 << 20;
|
||||
if bytes.len() > MAX_EXTRACT_BYTES {
|
||||
let head = &bytes[..MAX_EXTRACT_BYTES];
|
||||
let lossy = String::from_utf8_lossy(head).into_owned();
|
||||
let mut doc = extract_markdown_or_text(&uri, &digest_bytes(&bytes), &format, &lossy);
|
||||
doc.missing.push("tail_beyond_limit".into());
|
||||
doc.diagnostics.push(format!(
|
||||
"document truncated at {MAX_EXTRACT_BYTES} bytes (got {}); extraction is partial",
|
||||
bytes.len()
|
||||
));
|
||||
doc.status = "partial".into();
|
||||
return doc;
|
||||
}
|
||||
|
||||
let text = match String::from_utf8(bytes.clone()) {
|
||||
Ok(t) => t,
|
||||
Err(e) => {
|
||||
let lossy = String::from_utf8_lossy(&bytes).into_owned();
|
||||
let mut doc = extract_markdown_or_text(&uri, &digest_bytes(&bytes), &format, &lossy);
|
||||
doc.diagnostics
|
||||
.push(format!("invalid utf-8 ({e}); decoded lossy"));
|
||||
doc.status = if doc.text.is_empty() {
|
||||
"failed".into()
|
||||
} else {
|
||||
"partial".into()
|
||||
};
|
||||
return doc;
|
||||
}
|
||||
};
|
||||
|
||||
extract_markdown_or_text(&uri, &digest_bytes(&bytes), &format, &text)
|
||||
}
|
||||
|
||||
fn extract_markdown_or_text(
|
||||
uri: &str,
|
||||
digest: &str,
|
||||
format: &str,
|
||||
text: &str,
|
||||
) -> ExtractedDocument {
|
||||
let mut segments = Vec::new();
|
||||
let mut n = 0u32;
|
||||
let mut byte_off = 0usize;
|
||||
for (i, line) in text.lines().enumerate() {
|
||||
let line_no = i + 1;
|
||||
let line_bytes = line.len();
|
||||
// M05: stable fragment locator with 1-based line + UTF-8 byte offset.
|
||||
let loc = |kind: &str| format!("{kind}:L{line_no}:B{byte_off}");
|
||||
if let Some(rest) = line.trim().strip_prefix('#') {
|
||||
n += 1;
|
||||
let heading = rest.trim_start_matches('#').trim();
|
||||
segments.push(ExtractedSegment {
|
||||
id: format!("seg-{n}"),
|
||||
kind: "heading".into(),
|
||||
text: heading.to_string(),
|
||||
locator: loc("heading"),
|
||||
confidence: 1.0,
|
||||
});
|
||||
} else if line.trim().starts_with('|') {
|
||||
n += 1;
|
||||
segments.push(ExtractedSegment {
|
||||
id: format!("seg-{n}"),
|
||||
kind: "table_row".into(),
|
||||
text: line.to_string(),
|
||||
locator: loc("table_row"),
|
||||
confidence: 0.9,
|
||||
});
|
||||
} else if !line.trim().is_empty() {
|
||||
n += 1;
|
||||
segments.push(ExtractedSegment {
|
||||
id: format!("seg-{n}"),
|
||||
kind: "paragraph".into(),
|
||||
text: line.to_string(),
|
||||
locator: loc("paragraph"),
|
||||
confidence: 1.0,
|
||||
});
|
||||
}
|
||||
// +1 for '\n' when present in original (lines() strips it).
|
||||
byte_off += line_bytes + 1;
|
||||
}
|
||||
ExtractedDocument {
|
||||
source_uri: uri.to_string(),
|
||||
source_digest: digest.to_string(),
|
||||
format: format.to_string(),
|
||||
extractor_version: EXTRACTOR_VERSION.into(),
|
||||
text: text.to_string(),
|
||||
segments,
|
||||
missing: vec![],
|
||||
diagnostics: vec![],
|
||||
status: "ok".into(),
|
||||
}
|
||||
}
|
||||
|
||||
fn digest_bytes(bytes: &[u8]) -> String {
|
||||
let mut h = Sha256::new();
|
||||
h.update(bytes);
|
||||
format!("sha256:{:x}", h.finalize())
|
||||
}
|
||||
|
||||
/// Convenience for tests / CLI: extract if path exists.
|
||||
pub fn extract_path(path: &Path) -> ExtractedDocument {
|
||||
extract_document(&DocumentSource {
|
||||
path: path.to_path_buf(),
|
||||
format_hint: None,
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::io::Write;
|
||||
|
||||
#[test]
|
||||
fn extracts_markdown_headings() {
|
||||
let dir = std::env::temp_dir().join(format!("mq-extract-{}", std::process::id()));
|
||||
let _ = fs::create_dir_all(&dir);
|
||||
let path = dir.join("note.md");
|
||||
let mut f = fs::File::create(&path).unwrap();
|
||||
writeln!(f, "# rate\n\nhello").unwrap();
|
||||
let doc = extract_path(&path);
|
||||
assert_eq!(doc.status, "ok");
|
||||
assert!(doc.segments.iter().any(|s| s.kind == "heading" && s.text == "rate"));
|
||||
let _ = fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn pdf_reports_missing_extractor() {
|
||||
let doc = extract_document(&DocumentSource {
|
||||
path: Path::new("x.pdf").into(),
|
||||
format_hint: Some("pdf".into()),
|
||||
});
|
||||
assert_eq!(doc.status, "failed");
|
||||
assert!(!doc.diagnostics.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ocr_image_reports_missing_extractor() {
|
||||
let doc = extract_document(&DocumentSource {
|
||||
path: Path::new("scan.png").into(),
|
||||
format_hint: Some("ocr".into()),
|
||||
});
|
||||
assert_eq!(doc.status, "failed");
|
||||
assert!(doc.missing.contains(&"full_document".into()));
|
||||
assert!(doc.diagnostics.iter().any(|d| d.contains("ocr") || d.contains("extractor")));
|
||||
}
|
||||
}
|
||||
@@ -460,6 +460,24 @@ unsafe extern "C" fn host_query(
|
||||
let cap = crate::run_file_capture(&p, &opts).map_err(|e| e.to_string())?;
|
||||
value_to_json(&cap.value)
|
||||
})(),
|
||||
// M04: plugins may drive MLSP artifact.bind/execute without inventing a second protocol.
|
||||
"mlsp" => (|| {
|
||||
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!("mlsp args: {e}"))?;
|
||||
let method = args
|
||||
.get("method")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "mlsp requires `method`".to_string())?;
|
||||
let params = args.get("params").cloned().unwrap_or(serde_json::json!({}));
|
||||
let line = serde_json::json!({"method": method, "params": params}).to_string();
|
||||
let resp = crate::mlsp::handle_line(&line);
|
||||
serde_json::from_str(&resp).map_err(|e| format!("mlsp response: {e}"))
|
||||
})(),
|
||||
other => Err(format!("host_query: unknown `{other}`")),
|
||||
};
|
||||
|
||||
|
||||
@@ -331,6 +331,7 @@ fn spawn_file(
|
||||
));
|
||||
let _ = std::fs::write(&events_path, "");
|
||||
cmd.env("MARQDO_EVENT_FORWARD", &events_path);
|
||||
apply_run_selection_env(&mut cmd);
|
||||
|
||||
let mut child = cmd
|
||||
.spawn()
|
||||
@@ -693,3 +694,75 @@ fn require<'a>(bound: &'a HashMap<String, Value>, key: &str) -> Result<&'a Value
|
||||
.get(key)
|
||||
.ok_or_else(|| format!("host call missing `{key}`"))
|
||||
}
|
||||
|
||||
/// Propagate run/selection identity when parent has them (api_key stays via process inheritance).
|
||||
fn apply_run_selection_env(cmd: &mut Command) {
|
||||
for key in [
|
||||
"MARQDO_RUN_ID",
|
||||
"MARQDO_PARENT_RUN_ID",
|
||||
"MARQDO_TURN_ID",
|
||||
"MARQDO_WORKSPACE_SCOPE",
|
||||
"MARQDO_CANCEL_TOKEN",
|
||||
"MARQDO_LLM_MODEL",
|
||||
"MARQDO_LLM_BASE_URL",
|
||||
"OPENAI_MODEL",
|
||||
"OPENAI_BASE_URL",
|
||||
] {
|
||||
if let Ok(v) = std::env::var(key) {
|
||||
cmd.env(key, v);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::collections::HashMap;
|
||||
use std::process::Command;
|
||||
|
||||
#[test]
|
||||
fn f02_apply_run_selection_env_forwards_parent_identity() {
|
||||
std::env::set_var("MARQDO_RUN_ID", "run-parent");
|
||||
std::env::set_var("OPENAI_MODEL", "child-model");
|
||||
std::env::set_var("OPENAI_BASE_URL", "http://127.0.0.1:7010");
|
||||
// Must never require writing secrets into child env map for selection.
|
||||
std::env::remove_var("OPENAI_API_KEY");
|
||||
|
||||
let mut cmd = Command::new("true");
|
||||
apply_run_selection_env(&mut cmd);
|
||||
// Command doesn't expose env for inspection portably; re-check via helper contract:
|
||||
let keys: HashMap<&str, String> = [
|
||||
"MARQDO_RUN_ID",
|
||||
"OPENAI_MODEL",
|
||||
"OPENAI_BASE_URL",
|
||||
]
|
||||
.into_iter()
|
||||
.filter_map(|k| std::env::var(k).ok().map(|v| (k, v)))
|
||||
.collect();
|
||||
assert_eq!(keys.get("MARQDO_RUN_ID").map(String::as_str), Some("run-parent"));
|
||||
assert_eq!(keys.get("OPENAI_MODEL").map(String::as_str), Some("child-model"));
|
||||
assert_eq!(
|
||||
keys.get("OPENAI_BASE_URL").map(String::as_str),
|
||||
Some("http://127.0.0.1:7010")
|
||||
);
|
||||
|
||||
std::env::remove_var("MARQDO_RUN_ID");
|
||||
std::env::remove_var("OPENAI_MODEL");
|
||||
std::env::remove_var("OPENAI_BASE_URL");
|
||||
let _ = cmd; // ensure apply didn't panic
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn f02_agent_skeleton_has_no_llm_llm() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let agent = std::fs::read_to_string(root.join("ext/ai/agent.mq.md")).unwrap();
|
||||
assert!(
|
||||
!agent.contains("llm.llm"),
|
||||
"render_workbook_skeleton must not hardcode llm.llm"
|
||||
);
|
||||
assert!(
|
||||
agent.contains("llm.create") && agent.contains("OPENAI_MODEL"),
|
||||
"skeleton should create model from env selection"
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -37,6 +37,7 @@ pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
|
||||
};
|
||||
let graph = extract_graph(&extract_opts)?;
|
||||
write_projections(&opts.out_dir, &graph)?;
|
||||
write_publish_manifest(&opts.out_dir, &semantic, &graph)?;
|
||||
eprintln!(
|
||||
"marqdo knowledge: {} module(s), {} symbol(s), {} capability(ies), {} knowledge → {} (semantic graph/; retrieval ekc/)",
|
||||
graph.modules.len(),
|
||||
@@ -48,6 +49,52 @@ pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
|
||||
Ok(graph)
|
||||
}
|
||||
|
||||
/// M06: associate semantic generation, retrieval generation, and source digests.
|
||||
fn write_publish_manifest(
|
||||
out_dir: &Path,
|
||||
semantic: &crate::sema::Compilation,
|
||||
graph: &KnowledgeGraph,
|
||||
) -> Result<()> {
|
||||
let current = fs::read_to_string(out_dir.join("CURRENT")).unwrap_or_default();
|
||||
let generation = current.trim().to_string();
|
||||
let source_digest = {
|
||||
use sha2::{Digest, Sha256};
|
||||
let mut h = Sha256::new();
|
||||
for a in &semantic.semantics.artifacts {
|
||||
h.update(a.hashes.artifact.0.as_bytes());
|
||||
}
|
||||
format!("sha256:{:x}", h.finalize())
|
||||
};
|
||||
let evidence_digest = {
|
||||
use sha2::{Digest, Sha256};
|
||||
let mut h = Sha256::new();
|
||||
for a in &semantic.semantics.artifacts {
|
||||
h.update(a.hashes.evidence.0.as_bytes());
|
||||
}
|
||||
format!("sha256:{:x}", h.finalize())
|
||||
};
|
||||
let manifest = json!({
|
||||
"schema_version": 1,
|
||||
"kind": "publish_manifest",
|
||||
"semantic_generation": generation,
|
||||
"retrieval": {
|
||||
"ekc_graph": "ekc/graph",
|
||||
"modules": graph.modules.len(),
|
||||
"symbols": graph.symbols.len(),
|
||||
"capabilities": graph.capabilities.len(),
|
||||
"knowledge": graph.knowledge.len(),
|
||||
},
|
||||
"source_digest": source_digest,
|
||||
"evidence_digest": evidence_digest,
|
||||
"excluded_dirs": crate::project::EXCLUDED_DIRS,
|
||||
"project_id": semantic.semantics.project_id,
|
||||
});
|
||||
let path = out_dir.join("publish_manifest.json");
|
||||
fs::write(&path, serde_json::to_string_pretty(&manifest)?)
|
||||
.with_context(|| format!("write {}", path.display()))?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Directory for the legacy EKC retrieval projection (not execution authority).
|
||||
pub fn ekc_graph_dir(out_dir: &Path) -> std::path::PathBuf {
|
||||
out_dir.join("ekc").join("graph")
|
||||
|
||||
@@ -164,13 +164,7 @@ fn collect_mq_md(
|
||||
let p = entry.path();
|
||||
if p.is_dir() {
|
||||
let name = p.file_name().and_then(|s| s.to_str()).unwrap_or("");
|
||||
if name == "target"
|
||||
|| name == ".git"
|
||||
|| name == "node_modules"
|
||||
|| name == "docker"
|
||||
|| name == "data"
|
||||
|| name == ".cursor"
|
||||
{
|
||||
if crate::project::is_excluded_dir_name(name) {
|
||||
continue;
|
||||
}
|
||||
if let Ok(canon) = p.canonicalize() {
|
||||
@@ -210,13 +204,7 @@ fn walk_knowledge_md(
|
||||
let p = entry.path();
|
||||
if p.is_dir() {
|
||||
let name = p.file_name().and_then(|s| s.to_str()).unwrap_or("");
|
||||
if name == "target"
|
||||
|| name == ".git"
|
||||
|| name == ".marqdo"
|
||||
|| name == "docker"
|
||||
|| name == "data"
|
||||
|| name == ".cursor"
|
||||
{
|
||||
if crate::project::is_excluded_dir_name(name) {
|
||||
continue;
|
||||
}
|
||||
if let Ok(canon) = p.canonicalize() {
|
||||
|
||||
@@ -21,6 +21,7 @@ pub mod check;
|
||||
pub mod contract;
|
||||
pub mod debug;
|
||||
pub mod diagnostics;
|
||||
pub mod document_extract;
|
||||
pub mod embedded_lib;
|
||||
#[cfg(feature = "cli")]
|
||||
pub mod ext_cli;
|
||||
@@ -36,6 +37,7 @@ pub mod lex;
|
||||
pub mod linalg_ops;
|
||||
pub mod load;
|
||||
pub mod mlsp;
|
||||
pub mod workbench;
|
||||
pub mod parse;
|
||||
pub mod project;
|
||||
pub mod repair;
|
||||
|
||||
+163
-7
@@ -323,6 +323,10 @@ enum Commands {
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Exit non-zero when conflicts found (CI gate; default remains report-only)
|
||||
#[arg(long)]
|
||||
fail: bool,
|
||||
},
|
||||
/// List stale / deprecated / superseded knowledge
|
||||
Stale {
|
||||
@@ -334,6 +338,10 @@ enum Commands {
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Exit non-zero when stale items found (CI gate; default remains report-only)
|
||||
#[arg(long)]
|
||||
fail: bool,
|
||||
},
|
||||
/// Detect duplicate capabilities via symbol fingerprints
|
||||
Duplicate {
|
||||
@@ -353,7 +361,7 @@ enum Commands {
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
},
|
||||
/// Verify code ↔ knowledge consistency
|
||||
/// Verify code ↔ knowledge consistency (EKC structural; exit 1 only on errors)
|
||||
Verify {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
@@ -363,6 +371,10 @@ enum Commands {
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Also fail on warnings (does not change default success-when-no-errors)
|
||||
#[arg(long)]
|
||||
fail_on_warning: bool,
|
||||
},
|
||||
/// Official extension installer (`list` / `add` / `remove`)
|
||||
Ext {
|
||||
@@ -415,6 +427,18 @@ enum KnowledgeAction {
|
||||
#[arg(value_name = "SYMBOL_OR_PATH")]
|
||||
query: String,
|
||||
},
|
||||
/// Machine adjudication of semantic artifacts (M03): may_bind / may_publish
|
||||
Adjudicate {
|
||||
/// Artifact id, symbol id, or display name (omit to report all functions)
|
||||
#[arg(value_name = "ARTIFACT")]
|
||||
artifact: Option<String>,
|
||||
/// Policy: pure | business | static
|
||||
#[arg(long, default_value = "business")]
|
||||
policy: String,
|
||||
/// Exit 1 when any reported artifact has may_bind=false
|
||||
#[arg(long)]
|
||||
fail: bool,
|
||||
},
|
||||
/// Run engineering preflight for a task
|
||||
Preflight {
|
||||
#[arg(value_name = "TASK")]
|
||||
@@ -505,6 +529,23 @@ enum ViewAction {
|
||||
#[arg(short = 'o', long = "out", required = true)]
|
||||
out: PathBuf,
|
||||
},
|
||||
/// Read-only DocumentViewV1 (never executes). JSON to stdout or `--out`.
|
||||
Document {
|
||||
/// Project root (defaults to cwd / CLI path)
|
||||
#[arg(long)]
|
||||
project: Option<PathBuf>,
|
||||
|
||||
/// Document path relative to project
|
||||
#[arg(long)]
|
||||
document: String,
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
|
||||
/// Optional HTML wrapper for browser inspection (embed fragment only)
|
||||
#[arg(long, value_name = "FILE")]
|
||||
out: Option<PathBuf>,
|
||||
},
|
||||
}
|
||||
|
||||
fn main() -> ExitCode {
|
||||
@@ -1081,6 +1122,56 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
})?;
|
||||
Ok(0)
|
||||
}
|
||||
Some(ViewAction::Document {
|
||||
project,
|
||||
document,
|
||||
json,
|
||||
out,
|
||||
}) => {
|
||||
let project = project
|
||||
.or(path)
|
||||
.unwrap_or_else(|| PathBuf::from("."));
|
||||
let req = marqdo::workbench::DocumentViewRequest {
|
||||
project,
|
||||
document,
|
||||
revision: None,
|
||||
generation: None,
|
||||
node_id: None,
|
||||
include: vec![
|
||||
"fragment".into(),
|
||||
"outline".into(),
|
||||
"nodes".into(),
|
||||
"refs".into(),
|
||||
"diagnostics".into(),
|
||||
],
|
||||
};
|
||||
let view = marqdo::workbench::build_document_view(&req).map_err(|e| {
|
||||
anyhow::anyhow!("{}", e)
|
||||
})?;
|
||||
if let Some(out_path) = out {
|
||||
let fragment = view
|
||||
.pointer("/render/fragment")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("");
|
||||
let title = view
|
||||
.pointer("/document/title")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("DocumentView");
|
||||
let html = format!(
|
||||
"<!doctype html><html><head><meta charset=\"utf-8\"/><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"/><title>{title}</title><style>:root{{--mq-bg:#f7f5f0;--mq-text:#1a1a1a;--mq-muted:#5c5c5c;--mq-border:#d0cbc2;--mq-accent:#0b5fff;--mq-font-body:\"Iowan Old Style\",\"Palatino Linotype\",Palatino,serif;--mq-font-code:ui-monospace,Consolas,monospace}}body{{margin:0;background:var(--mq-bg);color:var(--mq-text);font:16px/1.75 var(--mq-font-body)}}.wrap{{max-width:46rem;margin:0 auto;padding:1.5rem}} .mq-document a{{color:var(--mq-accent)}}</style></head><body><div class=\"wrap\">{fragment}</div></body></html>"
|
||||
);
|
||||
std::fs::write(&out_path, html)?;
|
||||
if json {
|
||||
println!("{}", serde_json::to_string_pretty(&view)?);
|
||||
} else {
|
||||
println!("wrote {}", out_path.display());
|
||||
}
|
||||
} else {
|
||||
println!("{}", serde_json::to_string_pretty(&view)?);
|
||||
}
|
||||
let _ = json;
|
||||
Ok(0)
|
||||
}
|
||||
None => {
|
||||
serve(ViewOptions {
|
||||
path: path.unwrap_or_else(|| PathBuf::from(".")),
|
||||
@@ -1324,6 +1415,51 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
1
|
||||
})
|
||||
}
|
||||
KnowledgeAction::Adjudicate {
|
||||
artifact,
|
||||
policy,
|
||||
fail,
|
||||
} => {
|
||||
let semantic_root = if path.is_file() {
|
||||
path.parent()
|
||||
.unwrap_or_else(|| std::path::Path::new("."))
|
||||
.to_path_buf()
|
||||
} else {
|
||||
path.clone()
|
||||
};
|
||||
let report = marqdo::mlsp::adjudicate_project(
|
||||
&semantic_root,
|
||||
artifact.as_deref(),
|
||||
&policy,
|
||||
)
|
||||
.map_err(|e| anyhow::anyhow!("{}", e))?;
|
||||
if json {
|
||||
println!("{report}");
|
||||
} else {
|
||||
println!(
|
||||
"knowledge adjudicate policy={} may_bind_all={} count={}",
|
||||
policy,
|
||||
report["may_bind_all"],
|
||||
report["count"]
|
||||
);
|
||||
for item in report["reports"].as_array().into_iter().flatten() {
|
||||
println!(
|
||||
" {} evidence={} may_bind={} may_publish={}",
|
||||
item["artifact_id"].as_str().unwrap_or(""),
|
||||
item["verification"]["evidence"].as_str().unwrap_or(""),
|
||||
item["may_bind"],
|
||||
item["may_publish"]
|
||||
);
|
||||
}
|
||||
}
|
||||
Ok(
|
||||
if fail && report["may_bind_all"].as_bool() != Some(true) {
|
||||
1
|
||||
} else {
|
||||
0
|
||||
},
|
||||
)
|
||||
}
|
||||
KnowledgeAction::Preflight {
|
||||
task,
|
||||
min_candidates,
|
||||
@@ -1462,7 +1598,12 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Conflicts { path, out, json } => {
|
||||
Commands::Conflicts {
|
||||
path,
|
||||
out,
|
||||
json,
|
||||
fail,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let items = find_conflicts(&graph);
|
||||
@@ -1471,9 +1612,14 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
} else {
|
||||
print!("{}", format_conflicts_text(&items));
|
||||
}
|
||||
Ok(0)
|
||||
Ok(if fail && !items.is_empty() { 1 } else { 0 })
|
||||
}
|
||||
Commands::Stale { path, out, json } => {
|
||||
Commands::Stale {
|
||||
path,
|
||||
out,
|
||||
json,
|
||||
fail,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let items = find_stale(&graph, &path);
|
||||
@@ -1482,7 +1628,7 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
} else {
|
||||
print!("{}", format_stale_text(&items));
|
||||
}
|
||||
Ok(0)
|
||||
Ok(if fail && !items.is_empty() { 1 } else { 0 })
|
||||
}
|
||||
Commands::Duplicate {
|
||||
path,
|
||||
@@ -1517,7 +1663,12 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
Ok(0)
|
||||
}
|
||||
}
|
||||
Commands::Verify { path, out, json } => {
|
||||
Commands::Verify {
|
||||
path,
|
||||
out,
|
||||
json,
|
||||
fail_on_warning,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let issues = verify(&graph);
|
||||
@@ -1527,7 +1678,12 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
print!("{}", format_verify_text(&issues));
|
||||
}
|
||||
let errors = issues.iter().filter(|i| i.severity == "error").count();
|
||||
Ok(if errors > 0 { 1 } else { 0 })
|
||||
let warnings = issues.iter().filter(|i| i.severity == "warning").count();
|
||||
Ok(if errors > 0 || (fail_on_warning && warnings > 0) {
|
||||
1
|
||||
} else {
|
||||
0
|
||||
})
|
||||
}
|
||||
Commands::Ext { action } => {
|
||||
match action {
|
||||
|
||||
+427
-18
@@ -64,19 +64,38 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
|
||||
Some("artifact.impact") => artifact_impact(¶ms),
|
||||
Some("artifact.bind") => artifact_bind(¶ms),
|
||||
Some("artifact.execute") => artifact_execute(¶ms),
|
||||
Some("artifact.reuse_execute") => artifact_reuse_execute(¶ms),
|
||||
Some("document.extract") => document_extract(¶ms),
|
||||
Some("artifact.patch") => artifact_patch(¶ms),
|
||||
Some("artifact.extract_pure") => artifact_extract_pure(¶ms),
|
||||
// Workbench M00–M04: capability probe + read-only view + locator.
|
||||
Some("capabilities") => Ok(crate::workbench::probe_capabilities(¶ms)),
|
||||
#[cfg(feature = "view")]
|
||||
Some("view.document") => view_document(¶ms),
|
||||
#[cfg(not(feature = "view"))]
|
||||
Some("view.document") => Err(err(
|
||||
"mlsp.unsupported",
|
||||
"view.document requires the view feature",
|
||||
)),
|
||||
Some("view.reference_resolve") => crate::workbench::resolve_reference(¶ms),
|
||||
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
|
||||
Some("labels.search") => labels_search(¶ms),
|
||||
// `<TAB>` M6: one-shot session summary (T1 staleness seen/fixed).
|
||||
Some("session.summary") => session_summary(),
|
||||
other => Err(err(
|
||||
"mlsp.unknown_method",
|
||||
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.patch / artifact.extract_pure"),
|
||||
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.reuse_execute / artifact.patch / artifact.extract_pure / document.extract / capabilities / view.document / view.reference_resolve"),
|
||||
)),
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(feature = "view")]
|
||||
fn view_document(params: &Value) -> Result<Value, Value> {
|
||||
let req = crate::workbench::DocumentViewRequest::from_params(params)
|
||||
.map_err(|e| err("mlsp.bad_request", e))?;
|
||||
crate::workbench::build_document_view(&req)
|
||||
}
|
||||
|
||||
fn artifact_extract_pure(params: &Value) -> Result<Value, Value> {
|
||||
let name = params
|
||||
.get("name")
|
||||
@@ -129,6 +148,22 @@ fn artifact_query<'a>(project: &'a crate::sema::SemanticProject, query: &str) ->
|
||||
}).collect()
|
||||
}
|
||||
|
||||
fn document_extract(params: &Value) -> Result<Value, Value> {
|
||||
let path = params
|
||||
.get("path")
|
||||
.and_then(Value::as_str)
|
||||
.ok_or_else(|| err("mlsp.bad_request", "document.extract 需要 path"))?;
|
||||
let hint = params
|
||||
.get("format")
|
||||
.and_then(Value::as_str)
|
||||
.map(|s| s.to_string());
|
||||
let doc = crate::document_extract::extract_document(&crate::document_extract::DocumentSource {
|
||||
path: PathBuf::from(path),
|
||||
format_hint: hint,
|
||||
});
|
||||
Ok(doc.to_json())
|
||||
}
|
||||
|
||||
fn artifact_find(params: &Value) -> Result<Value, Value> {
|
||||
let compilation = semantic_project(params)?;
|
||||
let query = params.get("query").and_then(Value::as_str).unwrap_or("").to_ascii_lowercase();
|
||||
@@ -154,7 +189,100 @@ fn artifact_inspect(params: &Value) -> Result<Value, Value> {
|
||||
let candidates = artifact_query(&compilation.semantics, query);
|
||||
if candidates.is_empty() { return Err(err("artifact.unresolved", format!("没有制品 `{query}`"))); }
|
||||
if candidates.len() != 1 { return Err(json!({"code":"artifact.ambiguous","message":format!("制品 `{query}` 不唯一"),"candidates":candidates.iter().map(|a|&a.artifact_id.0).collect::<Vec<_>>() })); }
|
||||
Ok(crate::sema::artifact_json(candidates[0]))
|
||||
let artifact = candidates[0];
|
||||
// Version contract: expected source/generation mismatch must not silently return current.
|
||||
check_artifact_version_params(params, &compilation, artifact)?;
|
||||
Ok(crate::sema::artifact_json(artifact))
|
||||
}
|
||||
|
||||
/// Reject inspect when caller pinned an expected source revision or generation that
|
||||
/// does not match the current project snapshot (`artifact.version_mismatch`).
|
||||
fn check_artifact_version_params(
|
||||
params: &Value,
|
||||
compilation: &crate::sema::Compilation,
|
||||
artifact: &crate::sema::SemanticArtifact,
|
||||
) -> Result<(), Value> {
|
||||
let expected_rev = params
|
||||
.get("expected_source_revision")
|
||||
.and_then(Value::as_str)
|
||||
.filter(|s| !s.is_empty());
|
||||
if let Some(expected) = expected_rev {
|
||||
let project_root = params
|
||||
.get("project")
|
||||
.or_else(|| params.get("path"))
|
||||
.and_then(Value::as_str)
|
||||
.map(PathBuf::from)
|
||||
.unwrap_or_else(|| PathBuf::from("."));
|
||||
let root = if project_root.is_file() {
|
||||
project_root
|
||||
.parent()
|
||||
.unwrap_or_else(|| Path::new("."))
|
||||
.to_path_buf()
|
||||
} else {
|
||||
project_root
|
||||
};
|
||||
let abs = root.join(&artifact.source.file);
|
||||
match std::fs::read(&abs) {
|
||||
Ok(raw) => {
|
||||
use sha2::{Digest, Sha256};
|
||||
let actual = format!("sha256:{:x}", Sha256::digest(&raw));
|
||||
if actual != expected {
|
||||
return Err(json!({
|
||||
"code": "artifact.version_mismatch",
|
||||
"message": format!(
|
||||
"expected source_revision {expected}, actual {actual}; refusing silent downgrade"
|
||||
),
|
||||
"expected_source_revision": expected,
|
||||
"actual_source_revision": actual,
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
}));
|
||||
}
|
||||
}
|
||||
Err(e) => {
|
||||
return Err(json!({
|
||||
"code": "artifact.version_mismatch",
|
||||
"message": format!(
|
||||
"cannot verify source_revision for {}: {e}; refusing silent downgrade",
|
||||
artifact.source.file
|
||||
),
|
||||
"expected_source_revision": expected,
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
}));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let expected_gen = params
|
||||
.get("expected_generation")
|
||||
.or_else(|| params.get("generation_id"))
|
||||
.and_then(Value::as_str)
|
||||
.filter(|s| !s.is_empty());
|
||||
if let Some(expected) = expected_gen {
|
||||
let actual = semantic_generation_id(&compilation.semantics);
|
||||
if actual != expected {
|
||||
return Err(json!({
|
||||
"code": "artifact.version_mismatch",
|
||||
"message": format!(
|
||||
"expected generation {expected}, current projection is {actual}; refusing silent downgrade"
|
||||
),
|
||||
"expected_generation": expected,
|
||||
"actual_generation": actual,
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
}));
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Semantic generation token matching KnowledgePresentation / DocumentView.
|
||||
fn semantic_generation_id(project: &crate::sema::SemanticProject) -> String {
|
||||
use sha2::{Digest, Sha256};
|
||||
let mut gh = Sha256::new();
|
||||
gh.update(project.project_id.as_bytes());
|
||||
for a in &project.artifacts {
|
||||
gh.update(a.hashes.artifact.0.as_bytes());
|
||||
}
|
||||
format!("{:x}", gh.finalize())[..16].to_string()
|
||||
}
|
||||
|
||||
fn link_resolve(params: &Value) -> Result<Value, Value> {
|
||||
@@ -173,10 +301,216 @@ fn artifact_verify(params: &Value) -> Result<Value, Value> {
|
||||
let candidates = artifact_query(&compilation.semantics, query);
|
||||
if candidates.len() != 1 { return Err(err(if candidates.is_empty() { "artifact.unresolved" } else { "artifact.ambiguous" }, format!("无法唯一验证 `{query}`"))); }
|
||||
let artifact = candidates[0];
|
||||
let mut record = crate::sema::artifact_json(artifact)["verification"].clone();
|
||||
record["policy"] = params.get("policy").cloned().unwrap_or_else(|| json!("static"));
|
||||
record["artifact_id"] = json!(artifact.artifact_id.0);
|
||||
Ok(record)
|
||||
let policy = params.get("policy").and_then(Value::as_str).unwrap_or("static");
|
||||
Ok(build_verification_report(artifact, policy))
|
||||
}
|
||||
|
||||
/// CLI / product machine adjudication over semantic artifacts (M03).
|
||||
pub fn adjudicate_project(project: &std::path::Path, artifact: Option<&str>, policy: &str) -> Result<Value, Value> {
|
||||
let compilation = semantic_project(&json!({"project": project}))?;
|
||||
let targets: Vec<&crate::sema::SemanticArtifact> = if let Some(q) = artifact {
|
||||
let c = artifact_query(&compilation.semantics, q);
|
||||
if c.is_empty() {
|
||||
return Err(err("artifact.unresolved", format!("没有制品 `{q}`")));
|
||||
}
|
||||
c
|
||||
} else {
|
||||
compilation
|
||||
.semantics
|
||||
.artifacts
|
||||
.iter()
|
||||
.filter(|a| a.kind == "function")
|
||||
.collect()
|
||||
};
|
||||
let reports: Vec<Value> = targets
|
||||
.iter()
|
||||
.map(|a| build_verification_report(a, policy))
|
||||
.collect();
|
||||
let any_denied = reports.iter().any(|r| r["may_bind"] == false);
|
||||
Ok(json!({
|
||||
"schema_version": 1,
|
||||
"policy": policy,
|
||||
"count": reports.len(),
|
||||
"may_bind_all": !any_denied,
|
||||
"reports": reports,
|
||||
}))
|
||||
}
|
||||
|
||||
/// Known bind/verify policies (M03). Unknown strings are rejected.
|
||||
fn parse_policy(policy: &str) -> Result<&str, Value> {
|
||||
match policy {
|
||||
"pure" | "business" | "static" => Ok(policy),
|
||||
other => Err(json!({
|
||||
"code": "artifact.unknown_policy",
|
||||
"message": format!("未知政策 `{other}`;允许 pure / business / static"),
|
||||
"policy": other,
|
||||
})),
|
||||
}
|
||||
}
|
||||
|
||||
fn evidence_allows_business(status: &str) -> bool {
|
||||
matches!(status, "sourced" | "verified")
|
||||
}
|
||||
|
||||
fn build_verification_report(artifact: &crate::sema::SemanticArtifact, policy: &str) -> Value {
|
||||
let policy = match parse_policy(policy) {
|
||||
Ok(p) => p,
|
||||
Err(e) => {
|
||||
return json!({
|
||||
"schema_version": 1,
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
"policy": policy,
|
||||
"checks": {},
|
||||
"blockers": [e],
|
||||
"may_bind": false,
|
||||
"may_publish": false,
|
||||
"verification": crate::sema::artifact_json(artifact)["verification"].clone(),
|
||||
});
|
||||
}
|
||||
};
|
||||
let region_status = if artifact.applicability.contains("region=") {
|
||||
"declared"
|
||||
} else {
|
||||
"unknown"
|
||||
};
|
||||
let checks = json!({
|
||||
"parse": {"status": artifact.verification.parse, "detail": "static_project_compile"},
|
||||
"resolve": {"status": artifact.verification.resolve, "detail": "symbol_bound"},
|
||||
"contract": {"status": artifact.verification.contract, "detail": "not_executed_by_verify"},
|
||||
"execution": {"status": artifact.verification.execution, "detail": "not_run"},
|
||||
"tests": {"status": artifact.verification.tests, "detail": "no_test_runner_invoked"},
|
||||
"evidence": {"status": artifact.verification.evidence, "detail": "compile_time_provenance"},
|
||||
"domain": {"status": artifact.verification.domain, "detail": "unreviewed"},
|
||||
"region": {"status": region_status, "detail": "input_domain_not_checked"},
|
||||
"input_domain": {"status": "unknown", "detail": "not_checked_by_static_verify"},
|
||||
});
|
||||
let mut blockers = Vec::new();
|
||||
// Never upgrade tests/execution to passed without a runner (M03).
|
||||
if matches!(
|
||||
artifact.verification.tests.as_str(),
|
||||
"passed" | "verified"
|
||||
) && artifact
|
||||
.verification
|
||||
.methods
|
||||
.iter()
|
||||
.all(|m| m == "static_project_compile")
|
||||
{
|
||||
blockers.push(json!({
|
||||
"code": "artifact.tests_unproven",
|
||||
"check": "tests",
|
||||
"status": artifact.verification.tests,
|
||||
"detail": "static compile must not claim tests passed",
|
||||
}));
|
||||
}
|
||||
if policy == "business" && !evidence_allows_business(&artifact.verification.evidence) {
|
||||
blockers.push(json!({
|
||||
"code": "artifact.evidence_denied",
|
||||
"check": "evidence",
|
||||
"status": artifact.verification.evidence,
|
||||
}));
|
||||
}
|
||||
if policy == "pure"
|
||||
&& artifact
|
||||
.effects
|
||||
.values()
|
||||
.iter()
|
||||
.any(|e| e != "pure")
|
||||
{
|
||||
blockers.push(json!({
|
||||
"code": "artifact.effect_denied",
|
||||
"check": "effects",
|
||||
"effects": artifact.effects.values(),
|
||||
}));
|
||||
}
|
||||
let may_bind = blockers.is_empty()
|
||||
&& match policy {
|
||||
"business" => evidence_allows_business(&artifact.verification.evidence),
|
||||
"pure" => artifact.effects.values().iter().all(|e| e == "pure"),
|
||||
_ => true,
|
||||
};
|
||||
// Publish requires stronger evidence than bind; static verify never claims tests passed.
|
||||
let may_publish = may_bind
|
||||
&& artifact.verification.tests != "unknown"
|
||||
&& artifact.verification.tests != "not_run"
|
||||
&& artifact.verification.execution != "not_run"
|
||||
&& !matches!(
|
||||
artifact.verification.evidence.as_str(),
|
||||
"unverified" | "missing_source" | "anchor_missing" | "expired" | "invalid_date"
|
||||
);
|
||||
json!({
|
||||
"schema_version": 1,
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
"symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
|
||||
"digest": artifact.hashes.artifact.0,
|
||||
"evidence_digest": artifact.hashes.evidence.0,
|
||||
"closure_digest": artifact.hashes.closure.0,
|
||||
"policy": policy,
|
||||
"checks": checks,
|
||||
"blockers": blockers,
|
||||
"may_bind": may_bind,
|
||||
"may_publish": may_publish,
|
||||
"verification": {
|
||||
"parse": artifact.verification.parse,
|
||||
"resolve": artifact.verification.resolve,
|
||||
"contract": artifact.verification.contract,
|
||||
"execution": artifact.verification.execution,
|
||||
"tests": artifact.verification.tests,
|
||||
"evidence": artifact.verification.evidence,
|
||||
"domain": artifact.verification.domain,
|
||||
"methods": artifact.verification.methods,
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
/// M04: bind then execute in one call (actual reuse, not discovery scores).
|
||||
fn artifact_reuse_execute(params: &Value) -> Result<Value, Value> {
|
||||
let project = params
|
||||
.get("project")
|
||||
.or_else(|| params.get("path"))
|
||||
.cloned()
|
||||
.ok_or_else(|| err("mlsp.bad_request", "artifact.reuse_execute 需要 project"))?;
|
||||
let query = params
|
||||
.get("artifact_id")
|
||||
.or_else(|| params.get("symbol_id"))
|
||||
.or_else(|| params.get("query"))
|
||||
.and_then(Value::as_str)
|
||||
.ok_or_else(|| err("mlsp.bad_request", "artifact.reuse_execute 需要 artifact_id"))?;
|
||||
let policy = params.get("policy").and_then(Value::as_str).unwrap_or("pure");
|
||||
let inputs = params.get("inputs").cloned().unwrap_or(json!({}));
|
||||
let bound = artifact_bind(&json!({
|
||||
"project": project,
|
||||
"artifact_id": query,
|
||||
"policy": policy,
|
||||
"expected_digest": params.get("expected_digest"),
|
||||
}))?;
|
||||
let handle = bound
|
||||
.get("handle")
|
||||
.cloned()
|
||||
.ok_or_else(|| err("artifact.bind_failed", "bind 未返回 handle"))?;
|
||||
let executed = artifact_execute(&json!({
|
||||
"handle": handle,
|
||||
"inputs": inputs,
|
||||
"allow_effects": params.get("allow_effects"),
|
||||
}))?;
|
||||
Ok(json!({
|
||||
"schema_version": 1,
|
||||
"actual_reuse": true,
|
||||
"discovery_only": false,
|
||||
"artifact_id": executed.get("artifact_id"),
|
||||
"symbol_id": executed.get("symbol_id"),
|
||||
"digest": executed.get("digest"),
|
||||
"result": executed.get("result"),
|
||||
"stdout": executed.get("stdout"),
|
||||
"effects": executed.get("effects"),
|
||||
"trace": {
|
||||
"artifact_id": executed.get("artifact_id"),
|
||||
"symbol_id": executed.get("symbol_id"),
|
||||
"digest": executed.get("digest"),
|
||||
"inputs": inputs,
|
||||
"value": executed.get("result"),
|
||||
"stdout": executed.get("stdout"),
|
||||
},
|
||||
}))
|
||||
}
|
||||
|
||||
fn artifact_impact(params: &Value) -> Result<Value, Value> {
|
||||
@@ -197,10 +531,12 @@ fn artifact_bind(params: &Value) -> Result<Value, Value> {
|
||||
if expected.is_some() && expected != Some(artifact.hashes.artifact.0.as_str()) {
|
||||
return Err(json!({"code":"artifact.digest_mismatch","message":"目标摘要已变化,拒绝绑定","expected":expected,"actual":artifact.hashes.artifact.0}));
|
||||
}
|
||||
let policy = params
|
||||
.get("policy")
|
||||
.and_then(Value::as_str)
|
||||
.unwrap_or("pure");
|
||||
let policy = parse_policy(
|
||||
params
|
||||
.get("policy")
|
||||
.and_then(Value::as_str)
|
||||
.unwrap_or("pure"),
|
||||
)?;
|
||||
let effects = artifact.effects.values();
|
||||
if policy == "pure"
|
||||
&& effects.iter().any(|effect| effect != "pure")
|
||||
@@ -212,15 +548,10 @@ fn artifact_bind(params: &Value) -> Result<Value, Value> {
|
||||
"effects": effects,
|
||||
}));
|
||||
}
|
||||
if policy == "business"
|
||||
&& !matches!(
|
||||
artifact.verification.evidence.as_str(),
|
||||
"sourced" | "verified"
|
||||
)
|
||||
{
|
||||
if policy == "business" && !evidence_allows_business(&artifact.verification.evidence) {
|
||||
return Err(json!({
|
||||
"code": "artifact.evidence_denied",
|
||||
"message": "business 策略要求来源已关联;当前证据状态不足",
|
||||
"message": "business 策略要求来源已关联且锚点有效、未过期;当前证据状态不足",
|
||||
"policy": policy,
|
||||
"evidence": artifact.verification.evidence,
|
||||
}));
|
||||
@@ -230,14 +561,38 @@ fn artifact_bind(params: &Value) -> Result<Value, Value> {
|
||||
.as_ref()
|
||||
.map(|id| id.as_str().to_string())
|
||||
.unwrap_or_else(|| artifact.artifact_id.0.clone());
|
||||
let valid_until = artifact
|
||||
.applicability
|
||||
.split(';')
|
||||
.find_map(|part| {
|
||||
part.trim()
|
||||
.strip_prefix("valid_until=")
|
||||
.map(|s| s.trim().to_string())
|
||||
});
|
||||
let provenance_digests: Vec<Value> = artifact
|
||||
.provenance
|
||||
.iter()
|
||||
.filter(|p| p.relation == "supports")
|
||||
.map(|p| {
|
||||
json!({
|
||||
"uri": p.uri,
|
||||
"locator": p.locator,
|
||||
"content_digest": p.content_digest.as_ref().map(|d| &d.0),
|
||||
})
|
||||
})
|
||||
.collect();
|
||||
Ok(json!({"schema_version":1,"handle":{
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
"symbol_id": symbol_id,
|
||||
"digest": artifact.hashes.artifact.0,
|
||||
"closure_digest": artifact.hashes.closure.0,
|
||||
"evidence_digest": artifact.hashes.evidence.0,
|
||||
"project": compilation.semantics.root,
|
||||
"policy": policy,
|
||||
"effects": effects,
|
||||
"evidence": artifact.verification.evidence,
|
||||
"valid_until": valid_until,
|
||||
"provenance": provenance_digests,
|
||||
"source": {"file": artifact.source.file, "line": artifact.source.line},
|
||||
}}))
|
||||
}
|
||||
@@ -389,7 +744,27 @@ fn artifact_execute(params: &Value) -> Result<Value, Value> {
|
||||
let candidates = artifact_query(&compilation.semantics, artifact_id);
|
||||
if candidates.len() != 1 { return Err(err("artifact.stale_handle", "制品不再可唯一解析;请重新 bind")); }
|
||||
let artifact = candidates[0];
|
||||
if artifact.hashes.artifact.0 != digest { return Err(json!({"code":"artifact.stale_handle","message":"源码或契约已改变;拒绝执行过期 handle","expected":digest,"actual":artifact.hashes.artifact.0})); }
|
||||
if artifact.hashes.artifact.0 != digest { return Err(json!({"code":"artifact.stale_handle","message":"源码、契约或来源证据已改变;拒绝执行过期 handle","expected":digest,"actual":artifact.hashes.artifact.0})); }
|
||||
if let Some(bound_closure) = handle.get("closure_digest").and_then(Value::as_str) {
|
||||
if bound_closure != artifact.hashes.closure.0 {
|
||||
return Err(json!({
|
||||
"code": "artifact.stale_handle",
|
||||
"message": "依赖闭包已改变;拒绝执行过期 handle",
|
||||
"expected": bound_closure,
|
||||
"actual": artifact.hashes.closure.0,
|
||||
}));
|
||||
}
|
||||
}
|
||||
if let Some(bound_evidence) = handle.get("evidence_digest").and_then(Value::as_str) {
|
||||
if bound_evidence != artifact.hashes.evidence.0 {
|
||||
return Err(json!({
|
||||
"code": "artifact.stale_handle",
|
||||
"message": "来源证据摘要已改变;拒绝执行过期 handle",
|
||||
"expected": bound_evidence,
|
||||
"actual": artifact.hashes.evidence.0,
|
||||
}));
|
||||
}
|
||||
}
|
||||
if let Some(bound_symbol) = handle.get("symbol_id").and_then(Value::as_str) {
|
||||
let current = artifact
|
||||
.symbol_id
|
||||
@@ -405,6 +780,40 @@ fn artifact_execute(params: &Value) -> Result<Value, Value> {
|
||||
}));
|
||||
}
|
||||
}
|
||||
// Re-check policy at execute time (M02) — do not trust bind-time evidence string alone.
|
||||
let policy = handle.get("policy").and_then(Value::as_str).unwrap_or("pure");
|
||||
let _ = parse_policy(policy)?;
|
||||
if policy == "business" && !evidence_allows_business(&artifact.verification.evidence) {
|
||||
return Err(json!({
|
||||
"code": "artifact.evidence_denied",
|
||||
"message": "business 句柄在执行时证据状态不足(来源缺失、锚点失效或已过期)",
|
||||
"policy": policy,
|
||||
"evidence": artifact.verification.evidence,
|
||||
}));
|
||||
}
|
||||
if policy == "pure"
|
||||
&& artifact
|
||||
.effects
|
||||
.values()
|
||||
.iter()
|
||||
.any(|effect| effect != "pure")
|
||||
{
|
||||
return Err(json!({
|
||||
"code": "artifact.effect_denied",
|
||||
"message": "pure 句柄在执行时出现非纯效应",
|
||||
"policy": policy,
|
||||
"effects": artifact.effects.values(),
|
||||
}));
|
||||
}
|
||||
if let Some(until) = handle.get("valid_until").and_then(Value::as_str) {
|
||||
if crate::sema::provenance::valid_until_expired(until) {
|
||||
return Err(json!({
|
||||
"code": "artifact.expired",
|
||||
"message": "句柄适用期已过",
|
||||
"valid_until": until,
|
||||
}));
|
||||
}
|
||||
}
|
||||
if artifact.kind != "function" || artifact.callable.as_deref() == Some("instance_method") { return Err(err("artifact.not_executable", "只有非实例函数制品可由 artifact.execute 直接执行")); }
|
||||
let allowed: Vec<&str> = params.get("allow_effects").and_then(Value::as_array).map(|items| items.iter().filter_map(Value::as_str).collect()).unwrap_or_default();
|
||||
let denied: Vec<String> = artifact.effects.values().into_iter().filter(|effect| effect != "pure" && !allowed.contains(&effect.as_str())).collect();
|
||||
|
||||
+12
-1
@@ -72,15 +72,26 @@ impl ProjectRoot {
|
||||
}
|
||||
}
|
||||
|
||||
const EXCLUDED_DIRS: &[&str] = &[
|
||||
/// Shared with EKC extract (M06): authored sources never include corpus/runtime bags.
|
||||
pub const EXCLUDED_DIRS: &[&str] = &[
|
||||
".git",
|
||||
".marqdo",
|
||||
"target",
|
||||
"node_modules",
|
||||
".cursor",
|
||||
".agents",
|
||||
"data",
|
||||
"docker",
|
||||
"drafts",
|
||||
"candidates",
|
||||
"corpus",
|
||||
];
|
||||
|
||||
/// True when a directory basename is outside the authored source scan.
|
||||
pub fn is_excluded_dir_name(name: &str) -> bool {
|
||||
EXCLUDED_DIRS.iter().any(|excluded| name == *excluded)
|
||||
}
|
||||
|
||||
/// Soft limits so discovery fails with a clear diagnosis instead of hanging (G12).
|
||||
pub const MAX_SOURCE_DEPTH: u32 = 32;
|
||||
pub const MAX_SOURCE_FILE_BYTES: u64 = 2 * 1024 * 1024;
|
||||
|
||||
+133
-25
@@ -572,9 +572,17 @@ fn artifact_for_function(
|
||||
content_digest: Some(implementation.clone()),
|
||||
relation: "defines".into(),
|
||||
}];
|
||||
let resolved = super::provenance::resolve_provenance(path, module_prov);
|
||||
provenance.extend(resolved.refs);
|
||||
let evidence = digest(contract_summary(&contract));
|
||||
let fn_sources = super::provenance::sources_for_function(module_prov, &function.name);
|
||||
let mut fn_prov = module_prov.clone();
|
||||
fn_prov.sources = fn_sources;
|
||||
let resolved = super::provenance::resolve_provenance_sources(path, &fn_prov, &fn_prov.sources);
|
||||
provenance.extend(resolved.refs.clone());
|
||||
// M02: evidence digest includes contract + canonical provenance (URI/locator/content/applicability).
|
||||
let evidence = digest(format!(
|
||||
"{}|{}",
|
||||
contract_summary(&contract),
|
||||
resolved.evidence_record
|
||||
));
|
||||
let kind = match symbol.kind {
|
||||
SymbolKind::Type => "type",
|
||||
SymbolKind::Function => "function",
|
||||
@@ -1012,39 +1020,139 @@ fn direct_effects(calls: &[(usize, CallExpr, u32)]) -> EffectSet {
|
||||
|
||||
/// Propagate callee effects along local `dependencies` edges until fixpoint.
|
||||
/// Empty effect sets become `pure` only after closure (no unknown remains).
|
||||
/// Fixpoint closure digest: own artifact hash + sorted dependency closure hashes (G08).
|
||||
///
|
||||
/// Deterministic SCC closure digests (M02/G08):
|
||||
/// - Member seed = sorted `(artifact_id, interface, implementation)` within the SCC
|
||||
/// - External = sorted closures of dependencies outside the SCC
|
||||
/// - All members of an SCC share one closure digest
|
||||
fn close_closure_digests(artifacts: &mut [SemanticArtifact]) {
|
||||
let n = artifacts.len();
|
||||
if n == 0 {
|
||||
return;
|
||||
}
|
||||
let index: BTreeMap<String, usize> = artifacts
|
||||
.iter()
|
||||
.enumerate()
|
||||
.map(|(i, a)| (a.artifact_id.0.clone(), i))
|
||||
.collect();
|
||||
for _ in 0..n.saturating_add(1) {
|
||||
let mut changed = false;
|
||||
let snap: Vec<String> = artifacts
|
||||
.iter()
|
||||
.map(|a| a.hashes.closure.0.clone())
|
||||
.collect();
|
||||
for artifact in artifacts.iter_mut() {
|
||||
let mut parts = vec![artifact.hashes.artifact.0.clone()];
|
||||
for dep in &artifact.dependencies {
|
||||
if let Some(&i) = index.get(&dep.0) {
|
||||
parts.push(snap[i].clone());
|
||||
} else {
|
||||
parts.push(dep.0.clone());
|
||||
|
||||
// Tarjan SCC
|
||||
let mut stack: Vec<usize> = Vec::new();
|
||||
let mut on_stack = vec![false; n];
|
||||
let mut indices = vec![-1i32; n];
|
||||
let mut lowlink = vec![0i32; n];
|
||||
let mut index_counter = 0i32;
|
||||
let mut sccs: Vec<Vec<usize>> = Vec::new();
|
||||
|
||||
fn strongconnect(
|
||||
v: usize,
|
||||
artifacts: &[SemanticArtifact],
|
||||
index_map: &BTreeMap<String, usize>,
|
||||
stack: &mut Vec<usize>,
|
||||
on_stack: &mut [bool],
|
||||
indices: &mut [i32],
|
||||
lowlink: &mut [i32],
|
||||
index_counter: &mut i32,
|
||||
sccs: &mut Vec<Vec<usize>>,
|
||||
) {
|
||||
indices[v] = *index_counter;
|
||||
lowlink[v] = *index_counter;
|
||||
*index_counter += 1;
|
||||
stack.push(v);
|
||||
on_stack[v] = true;
|
||||
for dep in &artifacts[v].dependencies {
|
||||
if let Some(&w) = index_map.get(&dep.0) {
|
||||
if indices[w] < 0 {
|
||||
strongconnect(
|
||||
w,
|
||||
artifacts,
|
||||
index_map,
|
||||
stack,
|
||||
on_stack,
|
||||
indices,
|
||||
lowlink,
|
||||
index_counter,
|
||||
sccs,
|
||||
);
|
||||
lowlink[v] = lowlink[v].min(lowlink[w]);
|
||||
} else if on_stack[w] {
|
||||
lowlink[v] = lowlink[v].min(indices[w]);
|
||||
}
|
||||
}
|
||||
parts.sort();
|
||||
parts.dedup();
|
||||
let next = digest(parts.join("|"));
|
||||
if next.0 != artifact.hashes.closure.0 {
|
||||
artifact.hashes.closure = next;
|
||||
changed = true;
|
||||
}
|
||||
if lowlink[v] == indices[v] {
|
||||
let mut scc = Vec::new();
|
||||
loop {
|
||||
let w = stack.pop().expect("tarjan stack");
|
||||
on_stack[w] = false;
|
||||
scc.push(w);
|
||||
if w == v {
|
||||
break;
|
||||
}
|
||||
}
|
||||
scc.sort_unstable();
|
||||
sccs.push(scc);
|
||||
}
|
||||
}
|
||||
|
||||
for v in 0..n {
|
||||
if indices[v] < 0 {
|
||||
strongconnect(
|
||||
v,
|
||||
artifacts,
|
||||
&index,
|
||||
&mut stack,
|
||||
&mut on_stack,
|
||||
&mut indices,
|
||||
&mut lowlink,
|
||||
&mut index_counter,
|
||||
&mut sccs,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// sccs are in reverse topological order (callees before callers for DAGs).
|
||||
let mut scc_of = vec![0usize; n];
|
||||
for (si, scc) in sccs.iter().enumerate() {
|
||||
for &v in scc {
|
||||
scc_of[v] = si;
|
||||
}
|
||||
}
|
||||
let mut closure_done = vec![false; n];
|
||||
for scc in &sccs {
|
||||
let mut member_parts = Vec::new();
|
||||
for &v in scc {
|
||||
let a = &artifacts[v];
|
||||
member_parts.push(format!(
|
||||
"{}|{}|{}",
|
||||
a.artifact_id.0, a.hashes.interface.0, a.hashes.implementation.0
|
||||
));
|
||||
}
|
||||
member_parts.sort();
|
||||
member_parts.dedup();
|
||||
let mut external = Vec::new();
|
||||
for &v in scc {
|
||||
for dep in &artifacts[v].dependencies {
|
||||
if let Some(&w) = index.get(&dep.0) {
|
||||
if scc_of[w] != scc_of[v] && closure_done[w] {
|
||||
external.push(artifacts[w].hashes.closure.0.clone());
|
||||
} else if scc_of[w] != scc_of[v] {
|
||||
// External not yet closed — use artifact hash as stable seed.
|
||||
external.push(artifacts[w].hashes.artifact.0.clone());
|
||||
}
|
||||
} else {
|
||||
external.push(dep.0.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
if !changed {
|
||||
break;
|
||||
external.sort();
|
||||
external.dedup();
|
||||
let mut parts = member_parts;
|
||||
parts.extend(external);
|
||||
let scc_digest = digest(parts.join("|"));
|
||||
for &v in scc {
|
||||
artifacts[v].hashes.closure = scc_digest.clone();
|
||||
closure_done[v] = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+69
-10
@@ -111,7 +111,8 @@ pub fn check_links_lock(out_dir: &Path, project: &SemanticProject) -> Result<Loc
|
||||
}
|
||||
|
||||
/// Static reverse dependency closure. Queries can be an artifact/symbol URI,
|
||||
/// a declaration suffix, or a project-relative source filename.
|
||||
/// a declaration suffix, a project-relative source filename, or a corpus
|
||||
/// provenance URI (`supports` relation — M02).
|
||||
pub fn impact(project: &SemanticProject, query: &str) -> Value {
|
||||
let mut seeds = BTreeSet::new();
|
||||
for artifact in &project.artifacts {
|
||||
@@ -125,6 +126,15 @@ pub fn impact(project: &SemanticProject, query: &str) -> Value {
|
||||
.and_then(|s| s.to_str())
|
||||
.is_some_and(|stem| stem == query || query.ends_with(stem))
|
||||
|| artifact.artifact_id.0.ends_with(query)
|
||||
|| artifact.provenance.iter().any(|p| {
|
||||
p.relation == "supports"
|
||||
&& (p.uri == query
|
||||
|| p.uri.ends_with(query)
|
||||
|| query.ends_with(&p.uri)
|
||||
|| p.locator
|
||||
.as_ref()
|
||||
.is_some_and(|loc| format!("{}#{}", p.uri, loc) == query))
|
||||
})
|
||||
{
|
||||
seeds.insert(artifact.artifact_id.0.clone());
|
||||
}
|
||||
@@ -137,6 +147,22 @@ pub fn impact(project: &SemanticProject, query: &str) -> Value {
|
||||
.or_default()
|
||||
.push(artifact.artifact_id.0.clone());
|
||||
}
|
||||
// Corpus URI → citing artifact (provenance supports edges).
|
||||
for prov in &artifact.provenance {
|
||||
if prov.relation != "supports" {
|
||||
continue;
|
||||
}
|
||||
reverse
|
||||
.entry(prov.uri.clone())
|
||||
.or_default()
|
||||
.push(artifact.artifact_id.0.clone());
|
||||
if let Some(loc) = &prov.locator {
|
||||
reverse
|
||||
.entry(format!("{}#{}", prov.uri, loc))
|
||||
.or_default()
|
||||
.push(artifact.artifact_id.0.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
// NarrativeRef edges: step → symbol; impact includes the step's owning artifact.
|
||||
for step in &project.steps {
|
||||
@@ -157,21 +183,54 @@ pub fn impact(project: &SemanticProject, query: &str) -> Value {
|
||||
.push(owner.clone());
|
||||
}
|
||||
}
|
||||
// Also seed reverse walk from corpus URI keys when query matches them.
|
||||
if reverse.contains_key(query) {
|
||||
seeds.insert(query.to_string());
|
||||
}
|
||||
let mut queue: VecDeque<String> = seeds.iter().cloned().collect();
|
||||
let mut affected = BTreeSet::new();
|
||||
while let Some(current) = queue.pop_front() {
|
||||
if !affected.insert(current.clone()) { continue; }
|
||||
if !affected.insert(current.clone()) {
|
||||
continue;
|
||||
}
|
||||
if let Some(users) = reverse.get(¤t) {
|
||||
for user in users { queue.push_back(user.clone()); }
|
||||
for user in users {
|
||||
queue.push_back(user.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
let entries = affected.iter().filter_map(|id| project.artifacts.iter().find(|a| &a.artifact_id.0 == id)).map(|artifact| json!({
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
"symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
|
||||
"display_name": artifact.display_name,
|
||||
"kind": artifact.kind,
|
||||
"source": {"file": artifact.source.file, "line": artifact.source.line},
|
||||
})).collect::<Vec<_>>();
|
||||
// Drop pure corpus URI keys that are not artifacts from the affected set display.
|
||||
let entries = affected
|
||||
.iter()
|
||||
.filter_map(|id| project.artifacts.iter().find(|a| &a.artifact_id.0 == id))
|
||||
.map(|artifact| {
|
||||
let classes = {
|
||||
let mut c = Vec::new();
|
||||
if !artifact.hashes.interface.0.is_empty() {
|
||||
c.push("interface");
|
||||
}
|
||||
if !artifact.hashes.implementation.0.is_empty() {
|
||||
c.push("implementation");
|
||||
}
|
||||
if !artifact.hashes.evidence.0.is_empty() {
|
||||
c.push("evidence");
|
||||
}
|
||||
if !artifact.dependencies.is_empty() {
|
||||
c.push("dependency");
|
||||
}
|
||||
c
|
||||
};
|
||||
json!({
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
"symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
|
||||
"display_name": artifact.display_name,
|
||||
"kind": artifact.kind,
|
||||
"source": {"file": artifact.source.file, "line": artifact.source.line},
|
||||
"hash_classes": classes,
|
||||
"evidence": artifact.verification.evidence,
|
||||
})
|
||||
})
|
||||
.collect::<Vec<_>>();
|
||||
json!({"schema_version":SCHEMA_VERSION,"query":query,"resolved":!seeds.is_empty(),"seeds":seeds,"affected":entries})
|
||||
}
|
||||
|
||||
|
||||
+277
-16
@@ -1,4 +1,4 @@
|
||||
//! Optional source / applicability facts from module frontmatter (G05).
|
||||
//! Optional source / applicability facts from module frontmatter (G05 / M02).
|
||||
//!
|
||||
//! Authors declare `sources:` and optional `applicability:` / `valid_until` in
|
||||
//! frontmatter. Absence means a pure tool may still run but must stay
|
||||
@@ -11,12 +11,19 @@ use sha2::{Digest as _, Sha256};
|
||||
|
||||
use super::ir::{Digest, SourceRef};
|
||||
|
||||
/// Provenance extractor / verifier identity hashed into evidence digests.
|
||||
pub const PROVENANCE_EXTRACTOR_VERSION: &str = "marqdo-provenance/1";
|
||||
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct ModuleProvenance {
|
||||
/// Relative corpus paths, optional `#anchor`.
|
||||
pub sources: Vec<String>,
|
||||
pub valid_until: Option<String>,
|
||||
pub region: Option<String>,
|
||||
/// True when author wrote `sources: [...]` inline (ignored by parser — M07).
|
||||
pub inline_sources_ignored: bool,
|
||||
/// Optional per-function source overrides (M07): `function_sources: { name: [uri…] }`.
|
||||
pub function_sources: std::collections::BTreeMap<String, Vec<String>>,
|
||||
}
|
||||
|
||||
/// Scan YAML-ish frontmatter for sources / applicability (no full YAML parser).
|
||||
@@ -28,6 +35,8 @@ pub fn parse_module_provenance(source: &str) -> ModuleProvenance {
|
||||
let mut out = ModuleProvenance::default();
|
||||
let mut in_sources = false;
|
||||
let mut in_applicability = false;
|
||||
let mut in_function_sources = false;
|
||||
let mut current_fn: Option<String> = None;
|
||||
for line in lines {
|
||||
let t = line.trim_end();
|
||||
if t.trim() == "---" {
|
||||
@@ -40,21 +49,59 @@ pub fn parse_module_provenance(source: &str) -> ModuleProvenance {
|
||||
if !line.starts_with(' ') && !line.starts_with('\t') {
|
||||
in_sources = false;
|
||||
in_applicability = false;
|
||||
in_function_sources = false;
|
||||
current_fn = None;
|
||||
}
|
||||
if trimmed == "sources:" || trimmed.starts_with("sources:") {
|
||||
in_sources = true;
|
||||
in_applicability = false;
|
||||
in_function_sources = false;
|
||||
if let Some(rest) = trimmed.strip_prefix("sources:") {
|
||||
let rest = rest.trim();
|
||||
if !rest.is_empty() && rest != "|" {
|
||||
// inline list not used; ignore
|
||||
// inline list is not parsed — flag for diagnosis (M07).
|
||||
out.inline_sources_ignored = true;
|
||||
}
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if trimmed == "function_sources:" || trimmed.starts_with("function_sources:") {
|
||||
in_function_sources = true;
|
||||
in_sources = false;
|
||||
in_applicability = false;
|
||||
current_fn = None;
|
||||
continue;
|
||||
}
|
||||
if trimmed == "applicability:" || trimmed.starts_with("applicability:") {
|
||||
in_applicability = true;
|
||||
in_sources = false;
|
||||
in_function_sources = false;
|
||||
continue;
|
||||
}
|
||||
if in_function_sources {
|
||||
// Indent levels: ` name:` then ` - uri`
|
||||
let indent = line.len() - line.trim_start().len();
|
||||
if trimmed.ends_with(':') && !trimmed.starts_with('-') {
|
||||
let name = trimmed.trim_end_matches(':').trim().to_string();
|
||||
if !name.is_empty() {
|
||||
current_fn = Some(name.clone());
|
||||
out.function_sources.entry(name).or_default();
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if let Some(item) = trimmed.strip_prefix("- ") {
|
||||
let path = item.trim().trim_matches('"').to_string();
|
||||
if let Some(name) = ¤t_fn {
|
||||
if !path.is_empty() {
|
||||
out.function_sources
|
||||
.entry(name.clone())
|
||||
.or_default()
|
||||
.push(path);
|
||||
}
|
||||
} else if indent >= 2 && !path.is_empty() {
|
||||
// ignore orphan list items
|
||||
}
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if in_sources {
|
||||
@@ -77,26 +124,56 @@ pub fn parse_module_provenance(source: &str) -> ModuleProvenance {
|
||||
out
|
||||
}
|
||||
|
||||
/// Sources applicable to a named function: function_sources override, else module sources.
|
||||
pub fn sources_for_function(prov: &ModuleProvenance, function_name: &str) -> Vec<String> {
|
||||
if let Some(list) = prov.function_sources.get(function_name) {
|
||||
if !list.is_empty() {
|
||||
return list.clone();
|
||||
}
|
||||
}
|
||||
prov.sources.clone()
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum ProvenanceDiag {
|
||||
Missing { path: String },
|
||||
AnchorMissing { path: String, locator: String },
|
||||
ReadError { path: String, message: String },
|
||||
Expired { valid_until: String },
|
||||
InvalidDate { valid_until: String },
|
||||
InlineSourcesIgnored,
|
||||
}
|
||||
|
||||
impl ProvenanceDiag {
|
||||
pub fn code(&self) -> &'static str {
|
||||
match self {
|
||||
Self::Missing { .. } => "source.missing",
|
||||
Self::AnchorMissing { .. } => "source.anchor_missing",
|
||||
Self::ReadError { .. } => "source.read_error",
|
||||
Self::Expired { .. } => "source.expired",
|
||||
Self::InvalidDate { .. } => "source.invalid_date",
|
||||
Self::InlineSourcesIgnored => "source.inline_ignored",
|
||||
}
|
||||
}
|
||||
|
||||
pub fn message(&self) -> String {
|
||||
match self {
|
||||
Self::Missing { path } => format!("来源文件缺失:`{path}`"),
|
||||
Self::AnchorMissing { path, locator } => {
|
||||
format!("来源锚点不存在:`{path}` 中找不到 `#{}`", locator)
|
||||
}
|
||||
Self::ReadError { path, message } => {
|
||||
format!("来源文件无法读取:`{path}`({message})")
|
||||
}
|
||||
Self::Expired { valid_until } => {
|
||||
format!("来源适用期已过(valid_until={valid_until})")
|
||||
}
|
||||
Self::InvalidDate { valid_until } => {
|
||||
format!("适用期日期格式无效(期望 YYYY-MM-DD):`{valid_until}`")
|
||||
}
|
||||
Self::InlineSourcesIgnored => {
|
||||
"sources 行内列表被忽略;请改用 YAML block list(`- path#anchor`)".into()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -106,21 +183,35 @@ pub struct ProvenanceResolution {
|
||||
pub applicability: String,
|
||||
pub evidence_status: String,
|
||||
pub diagnostics: Vec<ProvenanceDiag>,
|
||||
/// Canonical record hashed into `hashes.evidence` (M02).
|
||||
pub evidence_record: String,
|
||||
}
|
||||
|
||||
/// Resolve corpus paths relative to the module file; never mark verified here.
|
||||
pub fn resolve_provenance(
|
||||
module_path: &Path,
|
||||
prov: &ModuleProvenance,
|
||||
) -> ProvenanceResolution {
|
||||
resolve_provenance_sources(module_path, prov, &prov.sources)
|
||||
}
|
||||
|
||||
/// Resolve an explicit source list (module or per-function).
|
||||
pub fn resolve_provenance_sources(
|
||||
module_path: &Path,
|
||||
prov: &ModuleProvenance,
|
||||
sources: &[String],
|
||||
) -> ProvenanceResolution {
|
||||
let mut refs = Vec::new();
|
||||
let mut diagnostics = Vec::new();
|
||||
if prov.inline_sources_ignored {
|
||||
diagnostics.push(ProvenanceDiag::InlineSourcesIgnored);
|
||||
}
|
||||
let base = module_path
|
||||
.parent()
|
||||
.map(|p| p.to_path_buf())
|
||||
.unwrap_or_else(|| PathBuf::from("."));
|
||||
|
||||
for raw in &prov.sources {
|
||||
for raw in sources {
|
||||
let (path_part, locator) = match raw.split_once('#') {
|
||||
Some((p, a)) => (p.trim(), Some(a.trim().to_string())),
|
||||
None => (raw.as_str(), None),
|
||||
@@ -138,22 +229,56 @@ pub fn resolve_provenance(
|
||||
});
|
||||
continue;
|
||||
}
|
||||
let content = fs::read(&resolved).unwrap_or_default();
|
||||
let content = match fs::read(&resolved) {
|
||||
Ok(bytes) => bytes,
|
||||
Err(e) => {
|
||||
diagnostics.push(ProvenanceDiag::ReadError {
|
||||
path: path_part.to_string(),
|
||||
message: e.to_string(),
|
||||
});
|
||||
refs.push(SourceRef {
|
||||
uri: path_part.to_string(),
|
||||
locator,
|
||||
content_digest: None,
|
||||
relation: "supports".into(),
|
||||
});
|
||||
continue;
|
||||
}
|
||||
};
|
||||
let mut hash = Sha256::new();
|
||||
hash.update(&content);
|
||||
let content_digest = Digest(format!("sha256:{:x}", hash.finalize()));
|
||||
if let Some(loc) = locator.as_ref() {
|
||||
let text = String::from_utf8_lossy(&content);
|
||||
if !anchor_exists(&text, loc) {
|
||||
diagnostics.push(ProvenanceDiag::AnchorMissing {
|
||||
path: path_part.to_string(),
|
||||
locator: loc.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
refs.push(SourceRef {
|
||||
uri: path_part.to_string(),
|
||||
locator,
|
||||
content_digest: Some(Digest(format!("sha256:{:x}", hash.finalize()))),
|
||||
content_digest: Some(content_digest),
|
||||
relation: "supports".into(),
|
||||
});
|
||||
}
|
||||
|
||||
if let Some(until) = &prov.valid_until {
|
||||
if is_expired(until) {
|
||||
diagnostics.push(ProvenanceDiag::Expired {
|
||||
valid_until: until.clone(),
|
||||
});
|
||||
match validate_date(until) {
|
||||
DateCheck::Ok => {
|
||||
if is_expired(until) {
|
||||
diagnostics.push(ProvenanceDiag::Expired {
|
||||
valid_until: until.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
DateCheck::Invalid => {
|
||||
diagnostics.push(ProvenanceDiag::InvalidDate {
|
||||
valid_until: until.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -177,45 +302,168 @@ pub fn resolve_provenance(
|
||||
}
|
||||
};
|
||||
|
||||
let evidence_status = if diagnostics.iter().any(|d| matches!(d, ProvenanceDiag::Missing { .. }))
|
||||
let evidence_status = if diagnostics
|
||||
.iter()
|
||||
.any(|d| matches!(d, ProvenanceDiag::Missing { .. } | ProvenanceDiag::ReadError { .. }))
|
||||
{
|
||||
"missing_source".into()
|
||||
} else if diagnostics
|
||||
.iter()
|
||||
.any(|d| matches!(d, ProvenanceDiag::AnchorMissing { .. }))
|
||||
{
|
||||
"anchor_missing".into()
|
||||
} else if diagnostics
|
||||
.iter()
|
||||
.any(|d| matches!(d, ProvenanceDiag::Expired { .. }))
|
||||
{
|
||||
"expired".into()
|
||||
} else if prov.sources.is_empty() {
|
||||
} else if diagnostics
|
||||
.iter()
|
||||
.any(|d| matches!(d, ProvenanceDiag::InvalidDate { .. }))
|
||||
{
|
||||
"invalid_date".into()
|
||||
} else if sources.is_empty() {
|
||||
"unverified".into()
|
||||
} else {
|
||||
// Corpus present and in date — still not domain-verified by compile alone.
|
||||
"sourced".into()
|
||||
};
|
||||
|
||||
let prov_for_record = ModuleProvenance {
|
||||
sources: sources.to_vec(),
|
||||
valid_until: prov.valid_until.clone(),
|
||||
region: prov.region.clone(),
|
||||
inline_sources_ignored: prov.inline_sources_ignored,
|
||||
function_sources: Default::default(),
|
||||
};
|
||||
let evidence_record = evidence_canonical_record(&prov_for_record, &refs);
|
||||
|
||||
ProvenanceResolution {
|
||||
refs,
|
||||
applicability,
|
||||
evidence_status,
|
||||
diagnostics,
|
||||
evidence_record,
|
||||
}
|
||||
}
|
||||
|
||||
/// Canonical evidence inputs: extractor version, applicability, sorted source facts.
|
||||
pub fn evidence_canonical_record(prov: &ModuleProvenance, refs: &[SourceRef]) -> String {
|
||||
let mut parts = vec![
|
||||
format!("extractor={PROVENANCE_EXTRACTOR_VERSION}"),
|
||||
format!("region={}", prov.region.as_deref().unwrap_or("")),
|
||||
format!("valid_until={}", prov.valid_until.as_deref().unwrap_or("")),
|
||||
];
|
||||
let mut source_parts: Vec<String> = refs
|
||||
.iter()
|
||||
.filter(|r| r.relation == "supports")
|
||||
.map(|r| {
|
||||
format!(
|
||||
"{}#{}@{}",
|
||||
r.uri,
|
||||
r.locator.as_deref().unwrap_or(""),
|
||||
r.content_digest
|
||||
.as_ref()
|
||||
.map(|d| d.0.as_str())
|
||||
.unwrap_or("none")
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
source_parts.sort();
|
||||
parts.extend(source_parts);
|
||||
parts.join("|")
|
||||
}
|
||||
|
||||
/// Whether a Markdown heading / id matches the `#locator` fragment.
|
||||
pub fn anchor_exists(content: &str, locator: &str) -> bool {
|
||||
let loc = locator.trim().trim_start_matches('#').trim();
|
||||
if loc.is_empty() {
|
||||
return true;
|
||||
}
|
||||
for line in content.lines() {
|
||||
let t = line.trim();
|
||||
if let Some(rest) = t.strip_prefix('#') {
|
||||
let heading = rest.trim_start_matches('#').trim();
|
||||
let heading = heading
|
||||
.split('{')
|
||||
.next()
|
||||
.unwrap_or(heading)
|
||||
.trim();
|
||||
if heading == loc || slugify_heading(heading) == loc {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
if t.contains(&format!("id=\"{loc}\""))
|
||||
|| t.contains(&format!("id='{loc}'"))
|
||||
|| t.contains(&format!("{{#{loc}}}"))
|
||||
{
|
||||
return true;
|
||||
}
|
||||
}
|
||||
false
|
||||
}
|
||||
|
||||
fn slugify_heading(heading: &str) -> String {
|
||||
let mut out = String::new();
|
||||
for ch in heading.chars() {
|
||||
if ch.is_ascii_alphanumeric() {
|
||||
out.push(ch.to_ascii_lowercase());
|
||||
} else if ch == ' ' || ch == '-' || ch == '_' {
|
||||
if !out.ends_with('-') {
|
||||
out.push('-');
|
||||
}
|
||||
} else if !ch.is_ascii() {
|
||||
// Keep non-ASCII letters (common in ZH docs) without lowercasing rules.
|
||||
out.push(ch);
|
||||
}
|
||||
}
|
||||
out.trim_matches('-').to_string()
|
||||
}
|
||||
|
||||
enum DateCheck {
|
||||
Ok,
|
||||
Invalid,
|
||||
}
|
||||
|
||||
fn validate_date(valid_until: &str) -> DateCheck {
|
||||
let parts: Vec<&str> = valid_until.split('-').collect();
|
||||
if parts.len() != 3 {
|
||||
return DateCheck::Invalid;
|
||||
}
|
||||
let Ok(y) = parts[0].parse::<i32>() else {
|
||||
return DateCheck::Invalid;
|
||||
};
|
||||
let Ok(m) = parts[1].parse::<u32>() else {
|
||||
return DateCheck::Invalid;
|
||||
};
|
||||
let Ok(d) = parts[2].parse::<u32>() else {
|
||||
return DateCheck::Invalid;
|
||||
};
|
||||
if !(1..=12).contains(&m) || !(1..=31).contains(&d) || y < 1970 {
|
||||
return DateCheck::Invalid;
|
||||
}
|
||||
if parts[0].len() != 4 || parts[1].len() != 2 || parts[2].len() != 2 {
|
||||
return DateCheck::Invalid;
|
||||
}
|
||||
DateCheck::Ok
|
||||
}
|
||||
|
||||
fn is_expired(valid_until: &str) -> bool {
|
||||
// Expect YYYY-MM-DD; compare lexicographically to today's UTC date.
|
||||
let today = chrono_today();
|
||||
!valid_until.is_empty() && valid_until < today.as_str()
|
||||
}
|
||||
|
||||
/// Public recheck for handle.execute (M02).
|
||||
pub fn valid_until_expired(valid_until: &str) -> bool {
|
||||
matches!(validate_date(valid_until), DateCheck::Ok) && is_expired(valid_until)
|
||||
}
|
||||
|
||||
fn chrono_today() -> String {
|
||||
// Avoid new dependency: use system local date via `date` is bad; use
|
||||
// SystemTime → rough days since epoch is fragile. Prefer `time` crate if
|
||||
// present, else format via `js_sys` — check Cargo.toml.
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
let secs = SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.unwrap_or_default()
|
||||
.as_secs() as i64;
|
||||
// UTC civil date from days since epoch (proleptic Gregorian).
|
||||
let days = secs.div_euclid(86_400);
|
||||
let (y, m, d) = civil_from_days(days);
|
||||
format!("{y:04}-{m:02}-{d:02}")
|
||||
@@ -248,4 +496,17 @@ mod tests {
|
||||
assert_eq!(p.region.as_deref(), Some("CN"));
|
||||
assert_eq!(p.valid_until.as_deref(), Some("2099-12-31"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn anchor_matches_heading() {
|
||||
assert!(anchor_exists("# rate\n\nrate = 0.13\n", "rate"));
|
||||
assert!(!anchor_exists("# rate\n\nrate = 0.13\n", "missing-anchor"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invalid_date_rejected() {
|
||||
assert!(matches!(validate_date("2099-12-31"), DateCheck::Ok));
|
||||
assert!(matches!(validate_date("not-a-date"), DateCheck::Invalid));
|
||||
assert!(matches!(validate_date("2099-13-01"), DateCheck::Invalid));
|
||||
}
|
||||
}
|
||||
@@ -632,9 +632,10 @@ fn taken_arms_by_branch_line(annots: &[ViewAnnot]) -> HashMap<u32, usize> {
|
||||
|
||||
fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String {
|
||||
let mut s = format!(
|
||||
r#"<div class="doc-fun" id="fn-{line}" data-fn="{name}" data-fn-path="{name}" data-line="{line}">
|
||||
r##"<div class="doc-fun" id="fn-{line}" data-fn="{name}" data-fn-path="{name}" data-line="{line}">
|
||||
<div class="doc-fun-bar">
|
||||
<h3 class="doc-fun-title">{name}</h3>"#,
|
||||
<h3 class="doc-fun-title">{name}</h3>
|
||||
<a class="knowledge-explain" href="#knowledge-{name}" data-node="{name}">说明</a>"##,
|
||||
line = fun.span.line,
|
||||
name = escape(&fun.name),
|
||||
);
|
||||
|
||||
+74
-10
@@ -58,6 +58,17 @@ fn stylesheet() -> &'static str {
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
html { scroll-behavior: smooth; }
|
||||
[id] { scroll-margin-top: 4.5rem; }
|
||||
.knowledge-block summary { cursor: pointer; font-weight: 600; }
|
||||
.knowledge-hint { color: var(--muted); font-size: 0.85em; margin: 0.25rem 0 0.5rem; }
|
||||
.knowledge-error .err { color: #8b1a1a; }
|
||||
@media print {
|
||||
.topbar, .stdin-form, .stream-panel, .exec-clear, #notebook-bar, nav { display: none !important; }
|
||||
.knowledge-block, .source-block { display: block; }
|
||||
}
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
html { scroll-behavior: auto; }
|
||||
}
|
||||
body {
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
@@ -2150,6 +2161,14 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
scrollIfPinned();
|
||||
}}
|
||||
if (thinkingEl && (answerNode && answerNode.data)) thinkingEl.open = false;
|
||||
// V2: reject stale result packets when page_token mismatches (source changed).
|
||||
var pageTok = window.MARQDO_VIEW_PAGE_TOKEN || "";
|
||||
var pktTok = (typeof ev.page_token === "string") ? ev.page_token : "";
|
||||
var acceptPacket = !pktTok || !pageTok || pktTok === pageTok;
|
||||
if (!acceptPacket) {{
|
||||
if (status) status.textContent = "stale result ignored";
|
||||
return;
|
||||
}}
|
||||
if (typeof ev.bindings_html === "string") {{
|
||||
var vp = document.getElementById("vars-panel");
|
||||
if (vp) {{
|
||||
@@ -2161,10 +2180,38 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
if (typeof ev.structure_html === "string" && ev.structure_html) {{
|
||||
var structEl = document.getElementById("structure");
|
||||
if (structEl) {{
|
||||
// Preserve call/loop frame selection across SSE structure swap.
|
||||
var savedCall = {{}};
|
||||
structEl.querySelectorAll("select.call-picker").forEach(function(sel) {{
|
||||
if (sel.id) savedCall[sel.id] = sel.value;
|
||||
}});
|
||||
var savedLoop = {{}};
|
||||
structEl.querySelectorAll("select.loop-picker").forEach(function(sel) {{
|
||||
if (sel.id) savedLoop[sel.id] = sel.value;
|
||||
}});
|
||||
var focusId = (document.activeElement && document.activeElement.id) || "";
|
||||
structEl.innerHTML = ev.structure_html;
|
||||
initAnnotLeaders();
|
||||
initCallPickers();
|
||||
initLoopPickers();
|
||||
Object.keys(savedCall).forEach(function(id) {{
|
||||
var el = document.getElementById(id);
|
||||
if (el && savedCall[id]) {{
|
||||
el.value = savedCall[id];
|
||||
el.dispatchEvent(new Event("change", {{ bubbles: true }}));
|
||||
}}
|
||||
}});
|
||||
Object.keys(savedLoop).forEach(function(id) {{
|
||||
var el = document.getElementById(id);
|
||||
if (el && savedLoop[id]) {{
|
||||
el.value = savedLoop[id];
|
||||
el.dispatchEvent(new Event("change", {{ bubbles: true }}));
|
||||
}}
|
||||
}});
|
||||
if (focusId) {{
|
||||
var fe = document.getElementById(focusId);
|
||||
if (fe && fe.focus) try {{ fe.focus(); }} catch (e) {{}}
|
||||
}}
|
||||
}}
|
||||
}}
|
||||
if (typeof ev.trace_json === "string" && ev.trace_json) {{
|
||||
@@ -4153,11 +4200,12 @@ pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkM
|
||||
}
|
||||
}
|
||||
};
|
||||
let title = Path::new(rel)
|
||||
let fallback_title = Path::new(rel)
|
||||
.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or(rel)
|
||||
.trim_end_matches(".mq.md");
|
||||
let title = crate::view::title_from_source(&vm.source, fallback_title);
|
||||
let plots_html = if vm.plots.is_empty() {
|
||||
String::new()
|
||||
} else {
|
||||
@@ -4224,43 +4272,59 @@ pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkM
|
||||
window.MARQDO_VIEW_LIVE = {live};
|
||||
window.MARQDO_FILE_PATH = {path_js};
|
||||
window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
window.MARQDO_VIEW_PAGE_TOKEN = {page_token_js};
|
||||
</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>
|
||||
{notebook}
|
||||
{knowledge}
|
||||
<section class="block structure-block">
|
||||
<h2>Structure</h2>
|
||||
<section class="block structure-block" id="structure">
|
||||
<h2>文档</h2>
|
||||
{structure_block}
|
||||
</section>
|
||||
{knowledge}
|
||||
<section class="block exec-block" id="exec-block">
|
||||
<h2>Execution {exec_clear}</h2>
|
||||
<h2>运行与结果 {exec_clear}</h2>
|
||||
{stdin_panel}
|
||||
{stream_panel}
|
||||
{plan_card}
|
||||
<div class="out {status}" id="exec-main">{out}</div>
|
||||
{plots}
|
||||
</section>
|
||||
<section class="block source-block">
|
||||
<h2>Source</h2>
|
||||
<details class="block source-block">
|
||||
<summary>完整源码</summary>
|
||||
<pre class="source">{source}</pre>
|
||||
</section>
|
||||
</details>
|
||||
"#,
|
||||
live = live_flag,
|
||||
path_js = escape_js_string(rel),
|
||||
auto_stream = if vm.auto_stream { "true" } else { "false" },
|
||||
page_token_js = escape_js_string(&vm.page_token),
|
||||
trace = if trace_safe.is_empty() {
|
||||
"{}"
|
||||
} else {
|
||||
trace_safe.as_str()
|
||||
},
|
||||
title = escape(title),
|
||||
title = escape(&title),
|
||||
status = status,
|
||||
status_label = status_label,
|
||||
rel = escape(rel),
|
||||
notebook = notebook,
|
||||
knowledge = if vm.knowledge_html.is_empty() { String::new() } else { format!("<section class=\"block knowledge-block\"><h2>Executable knowledge</h2>{}</section>", vm.knowledge_html) },
|
||||
knowledge = {
|
||||
if !vm.knowledge_error.is_empty() {
|
||||
format!(
|
||||
"<section class=\"block knowledge-block knowledge-error\"><h2>知识关系</h2><p class=\"err\">{}</p></section>",
|
||||
escape(&vm.knowledge_error)
|
||||
)
|
||||
} else if vm.knowledge_html.is_empty() {
|
||||
String::new()
|
||||
} else {
|
||||
format!(
|
||||
"<details class=\"block knowledge-block\"><summary>可执行知识(辅助)</summary>{}</details>",
|
||||
vm.knowledge_html
|
||||
)
|
||||
}
|
||||
},
|
||||
exec_clear = exec_clear,
|
||||
structure_block = structure_block,
|
||||
stdin_panel = stdin_panel,
|
||||
|
||||
@@ -0,0 +1,213 @@
|
||||
//! V1 KnowledgePresentation model — structured facts shared by body, outline, and detail.
|
||||
//!
|
||||
//! Semantic facts come from SemanticProject; this module does not invent verification.
|
||||
|
||||
use crate::sema::{SemanticArtifact, SemanticProject};
|
||||
use serde_json::{json, Value};
|
||||
use sha2::{Digest, Sha256};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct KnowledgeNode {
|
||||
pub node_id: String,
|
||||
pub artifact_id: Option<String>,
|
||||
pub display_name: String,
|
||||
pub kind: String,
|
||||
pub source_file: String,
|
||||
pub source_line: u32,
|
||||
pub signature: Option<String>,
|
||||
pub effects: Vec<String>,
|
||||
pub evidence: String,
|
||||
pub dependencies: Vec<String>,
|
||||
pub artifact_digest: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct KnowledgePresentation {
|
||||
pub document_id: String,
|
||||
pub title: String,
|
||||
pub source_digest: String,
|
||||
/// V2: semantic generation / run matching token (empty when not compiled under CURRENT).
|
||||
pub semantic_generation: String,
|
||||
/// V2: page token for SSE stale-packet rejection (digest of document facts).
|
||||
pub page_token: String,
|
||||
pub execution_state: String,
|
||||
pub nodes: Vec<KnowledgeNode>,
|
||||
pub diagnostics: Vec<String>,
|
||||
}
|
||||
|
||||
impl KnowledgePresentation {
|
||||
pub fn from_project(project: &SemanticProject, rel: &str, title: &str) -> Self {
|
||||
let mut nodes = Vec::new();
|
||||
for artifact in &project.artifacts {
|
||||
if artifact.source.file != rel {
|
||||
continue;
|
||||
}
|
||||
if artifact.kind == "module" {
|
||||
continue;
|
||||
}
|
||||
nodes.push(node_from_artifact(artifact));
|
||||
}
|
||||
let mut hasher_parts: Vec<&str> = project
|
||||
.artifacts
|
||||
.iter()
|
||||
.filter(|a| a.source.file == rel)
|
||||
.map(|a| a.hashes.artifact.0.as_str())
|
||||
.collect();
|
||||
hasher_parts.sort();
|
||||
let mut h = Sha256::new();
|
||||
h.update(project.project_id.as_bytes());
|
||||
h.update(rel.as_bytes());
|
||||
for part in &hasher_parts {
|
||||
h.update(part.as_bytes());
|
||||
}
|
||||
let digest_hex = format!("{:x}", h.finalize());
|
||||
let source_digest = format!("sha256:{digest_hex}");
|
||||
// page_token is filled by caller from raw source so SSE can match without recompile.
|
||||
let page_token = String::new();
|
||||
let semantic_generation = {
|
||||
let mut gh = Sha256::new();
|
||||
gh.update(project.project_id.as_bytes());
|
||||
for a in &project.artifacts {
|
||||
gh.update(a.hashes.artifact.0.as_bytes());
|
||||
}
|
||||
format!("{:x}", gh.finalize())[..16].to_string()
|
||||
};
|
||||
let mut diagnostics = Vec::new();
|
||||
for n in &nodes {
|
||||
if n.evidence == "sourced" {
|
||||
// Never imply sourced == verified (V2).
|
||||
diagnostics.push(format!(
|
||||
"{}: 已关联来源,内容尚未核验",
|
||||
n.display_name
|
||||
));
|
||||
}
|
||||
}
|
||||
Self {
|
||||
document_id: rel.to_string(),
|
||||
title: title.to_string(),
|
||||
source_digest,
|
||||
semantic_generation,
|
||||
page_token,
|
||||
execution_state: "not_run".into(),
|
||||
nodes,
|
||||
diagnostics,
|
||||
}
|
||||
}
|
||||
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"schema_version": 1,
|
||||
"document_id": self.document_id,
|
||||
"title": self.title,
|
||||
"source_digest": self.source_digest,
|
||||
"semantic_generation": self.semantic_generation,
|
||||
"page_token": self.page_token,
|
||||
"execution_state": self.execution_state,
|
||||
"nodes": self.nodes.iter().map(|n| json!({
|
||||
"node_id": n.node_id,
|
||||
"artifact_id": n.artifact_id,
|
||||
"display_name": n.display_name,
|
||||
"kind": n.kind,
|
||||
"source": {"file": n.source_file, "line": n.source_line},
|
||||
"signature": n.signature,
|
||||
"effects": n.effects,
|
||||
"evidence": n.evidence,
|
||||
"dependencies": n.dependencies,
|
||||
"artifact_digest": n.artifact_digest,
|
||||
"verified_claim": false,
|
||||
})).collect::<Vec<_>>(),
|
||||
"local_deps": self.nodes.iter().flat_map(|n| {
|
||||
n.dependencies.iter().map(|d| json!({
|
||||
"from": n.node_id,
|
||||
"to": d,
|
||||
})).collect::<Vec<_>>()
|
||||
}).collect::<Vec<_>>(),
|
||||
"diagnostics": self.diagnostics,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Live View SSE: whether a result packet may update the document structure.
|
||||
///
|
||||
/// Legacy packets without a token are accepted so older live-view clients keep
|
||||
/// working. **Embedded DocumentView clients must use [`sse_accepts_packet_strict`]
|
||||
/// instead** — missing/empty tokens and mismatches are rejected there.
|
||||
pub fn sse_accepts_packet(page_token: &str, packet_token: Option<&str>) -> bool {
|
||||
match packet_token {
|
||||
None | Some("") => true, // legacy packets without token still apply
|
||||
Some(_tok) if page_token.is_empty() => true,
|
||||
Some(tok) => tok == page_token,
|
||||
}
|
||||
}
|
||||
|
||||
/// Strict SSE / embed gate: reject missing, empty, or mismatched page tokens.
|
||||
///
|
||||
/// Use this for DocumentView / qdagent embed hosts. Do not inherit the live-view
|
||||
/// leniency of [`sse_accepts_packet`].
|
||||
pub fn sse_accepts_packet_strict(page_token: &str, packet_token: Option<&str>) -> bool {
|
||||
match packet_token {
|
||||
None | Some("") => false,
|
||||
Some(_tok) if page_token.is_empty() => false,
|
||||
Some(tok) => tok == page_token,
|
||||
}
|
||||
}
|
||||
|
||||
/// Stable page token from raw source bytes (used by SSE run path).
|
||||
pub fn page_token_from_source(rel: &str, source: &str) -> String {
|
||||
let mut h = Sha256::new();
|
||||
h.update(rel.as_bytes());
|
||||
h.update(source.as_bytes());
|
||||
let hex = format!("{:x}", h.finalize());
|
||||
hex[..hex.len().min(32)].to_string()
|
||||
}
|
||||
|
||||
fn node_from_artifact(artifact: &SemanticArtifact) -> KnowledgeNode {
|
||||
let signature = artifact.signature.as_ref().map(|sig| {
|
||||
let params = sig
|
||||
.params
|
||||
.iter()
|
||||
.map(|p| format!("{}:{}", p.name, p.ty))
|
||||
.collect::<Vec<_>>()
|
||||
.join(", ");
|
||||
format!("({params}) → {}", sig.returns)
|
||||
});
|
||||
KnowledgeNode {
|
||||
node_id: artifact
|
||||
.symbol_id
|
||||
.as_ref()
|
||||
.map(|id| id.as_str().to_string())
|
||||
.unwrap_or_else(|| artifact.artifact_id.0.clone()),
|
||||
artifact_id: Some(artifact.artifact_id.0.clone()),
|
||||
display_name: artifact.display_name.clone(),
|
||||
kind: artifact.kind.clone(),
|
||||
source_file: artifact.source.file.clone(),
|
||||
source_line: artifact.source.line,
|
||||
signature,
|
||||
effects: artifact.effects.values(),
|
||||
evidence: artifact.verification.evidence.clone(),
|
||||
dependencies: artifact.dependencies.iter().map(|d| d.0.clone()).collect(),
|
||||
artifact_digest: artifact.hashes.artifact.0.clone(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Pull `title:` from YAML frontmatter without a full YAML parser.
|
||||
pub fn title_from_source(source: &str, fallback: &str) -> String {
|
||||
let mut lines = source.lines();
|
||||
if lines.next().map(|l| l.trim_end()) != Some("---") {
|
||||
return fallback.to_string();
|
||||
}
|
||||
for line in lines {
|
||||
let t = line.trim_end();
|
||||
if t.trim() == "---" {
|
||||
break;
|
||||
}
|
||||
let trimmed = t.trim();
|
||||
if let Some(rest) = trimmed.strip_prefix("title:") {
|
||||
let title = rest.trim().trim_matches('"').trim_matches('\'').to_string();
|
||||
if !title.is_empty() {
|
||||
return title;
|
||||
}
|
||||
}
|
||||
}
|
||||
fallback.to_string()
|
||||
}
|
||||
+106
-28
@@ -6,13 +6,23 @@ mod debug_api;
|
||||
mod debug_page;
|
||||
mod document;
|
||||
mod html;
|
||||
mod knowledge_present;
|
||||
mod notebook_api;
|
||||
mod output;
|
||||
mod render;
|
||||
|
||||
pub use knowledge_present::{
|
||||
page_token_from_source, sse_accepts_packet, sse_accepts_packet_strict, title_from_source,
|
||||
KnowledgePresentation,
|
||||
};
|
||||
|
||||
/// Surface rendering of an expression (labels/diagnostics reuse). `<TAB>` M6
|
||||
pub use render::expr_display;
|
||||
|
||||
/// Read-model HTML helpers for embedded DocumentView (M03) — never execute.
|
||||
pub use document::render_module_document;
|
||||
pub use render::render_knowledge_html;
|
||||
|
||||
pub use output::{write_capture, write_static, CaptureOptions, OutputOptions};
|
||||
|
||||
use std::fs;
|
||||
@@ -32,7 +42,7 @@ 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_knowledge_html, render_module_structure_with_annots, render_right_rail, uses_stream_panel, FileViewModel,
|
||||
render_module_structure_with_annots, render_right_rail, uses_stream_panel, FileViewModel,
|
||||
};
|
||||
use crate::{run_file_capture, RunOptions};
|
||||
|
||||
@@ -383,6 +393,18 @@ pub(crate) fn build_file_view(
|
||||
rel: &str,
|
||||
stdin_lines: &[String],
|
||||
live: bool,
|
||||
) -> Result<FileViewModel> {
|
||||
build_file_view_with_exec(root, abs, rel, stdin_lines, live, true)
|
||||
}
|
||||
|
||||
/// Like [`build_file_view`], but `execute=false` skips `run_file_capture` entirely (V0 / `--no-exec`).
|
||||
pub(crate) fn build_file_view_with_exec(
|
||||
root: &ViewRoot,
|
||||
abs: &Path,
|
||||
rel: &str,
|
||||
stdin_lines: &[String],
|
||||
live: bool,
|
||||
execute: bool,
|
||||
) -> Result<FileViewModel> {
|
||||
let mut source = fs::read_to_string(abs).with_context(|| format!("read {}", abs.display()))?;
|
||||
// Structure shows this file only — do not merge imported lib bodies into the tree.
|
||||
@@ -423,34 +445,43 @@ pub(crate) fn build_file_view(
|
||||
// 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(),
|
||||
String::new(),
|
||||
true,
|
||||
Vec::new(),
|
||||
String::new(),
|
||||
)
|
||||
} else {
|
||||
match run_file_capture(abs, &opts) {
|
||||
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) => (
|
||||
let (stdout, stderr, ok, plots, mut bindings_html) =
|
||||
if !execute {
|
||||
(
|
||||
String::new(),
|
||||
tidy_user_error(&format!("{e:#}"), abs, rel),
|
||||
false,
|
||||
"execution skipped (--no-exec)".into(),
|
||||
true,
|
||||
Vec::new(),
|
||||
String::from(r#"<p class="vars-skipped">skipped</p>"#),
|
||||
)
|
||||
} else if awaiting_input || auto_stream {
|
||||
(
|
||||
String::new(),
|
||||
String::new(),
|
||||
true,
|
||||
Vec::new(),
|
||||
String::new(),
|
||||
),
|
||||
}
|
||||
};
|
||||
)
|
||||
} else {
|
||||
match run_file_capture(abs, &opts) {
|
||||
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),
|
||||
false,
|
||||
Vec::new(),
|
||||
String::new(),
|
||||
),
|
||||
}
|
||||
};
|
||||
// Re-read after run so writeback slots / workbook edits show in Structure.
|
||||
if !awaiting_input && !auto_stream {
|
||||
if execute && !awaiting_input && !auto_stream {
|
||||
if let Ok(next) = fs::read_to_string(abs) {
|
||||
source = next;
|
||||
}
|
||||
@@ -480,9 +511,52 @@ pub(crate) fn build_file_view(
|
||||
};
|
||||
// Analysis is intentionally independent from capture/run. If a document
|
||||
// has side effects, its facts remain visible while its values stay absent.
|
||||
let knowledge_html = crate::sema::compile_project(&crate::sema::CompileOptions {
|
||||
project_root: root.root.clone(), entry: Some(abs.to_path_buf()), lock_mode: crate::sema::LockMode::Off,
|
||||
}).map(|compilation| render_knowledge_html(&compilation.semantics, rel)).unwrap_or_default();
|
||||
let title_guess = crate::view::title_from_source(&source, rel);
|
||||
let (knowledge_html, knowledge_error, page_token) =
|
||||
match crate::sema::compile_project(&crate::sema::CompileOptions {
|
||||
project_root: root.root.clone(),
|
||||
entry: Some(abs.to_path_buf()),
|
||||
lock_mode: crate::sema::LockMode::Off,
|
||||
}) {
|
||||
Ok(compilation) => {
|
||||
let html = render_knowledge_html(&compilation.semantics, rel);
|
||||
// V1: also materialize structured presentation (JSON available to page scripts).
|
||||
let mut presentation = crate::view::KnowledgePresentation::from_project(
|
||||
&compilation.semantics,
|
||||
rel,
|
||||
&title_guess,
|
||||
);
|
||||
presentation.page_token = crate::view::page_token_from_source(rel, &source);
|
||||
let json = presentation.to_json().to_string();
|
||||
let with_model = if html.is_empty() {
|
||||
format!(
|
||||
r#"<script type="application/json" id="mq-knowledge-presentation">{json}</script>"#,
|
||||
json = json.replace("</", "<\\/")
|
||||
)
|
||||
} else {
|
||||
format!(
|
||||
r#"{html}<script type="application/json" id="mq-knowledge-presentation">{json}</script>"#,
|
||||
html = html,
|
||||
json = json.replace("</", "<\\/")
|
||||
)
|
||||
};
|
||||
(
|
||||
with_model,
|
||||
String::new(),
|
||||
presentation.page_token.clone(),
|
||||
)
|
||||
}
|
||||
Err(e) => (
|
||||
String::new(),
|
||||
format!("知识关系暂不可用:{}", tidy_user_error(&format!("{e:#}"), abs, rel)),
|
||||
crate::view::page_token_from_source(rel, &source),
|
||||
),
|
||||
};
|
||||
let page_token = if page_token.is_empty() {
|
||||
crate::view::page_token_from_source(rel, &source)
|
||||
} else {
|
||||
page_token
|
||||
};
|
||||
Ok(FileViewModel {
|
||||
rel_path: rel.to_string(),
|
||||
source,
|
||||
@@ -500,6 +574,8 @@ pub(crate) fn build_file_view(
|
||||
bindings_html: std::mem::take(&mut bindings_html),
|
||||
trace_json,
|
||||
knowledge_html,
|
||||
knowledge_error,
|
||||
page_token,
|
||||
})
|
||||
}
|
||||
|
||||
@@ -752,6 +828,7 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> {
|
||||
}
|
||||
Err(_) => (String::new(), String::new()),
|
||||
};
|
||||
let page_token = crate::view::page_token_from_source(&rel_clone, &source_now);
|
||||
let done = serde_json::json!({
|
||||
"type": "done",
|
||||
"run_id": run_id,
|
||||
@@ -761,6 +838,7 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> {
|
||||
"bindings_html": bindings_html,
|
||||
"structure_html": structure_html,
|
||||
"trace_json": trace_json,
|
||||
"page_token": page_token,
|
||||
});
|
||||
crate::host::event_bus::EventBus::global().publish_json(&done.to_string());
|
||||
}
|
||||
|
||||
+3
-21
@@ -11,7 +11,7 @@ use crate::host::foreign_doc::DocumentSession;
|
||||
use crate::host::json::json_to_value;
|
||||
use crate::value::Value;
|
||||
use crate::view::html::{escape, page_file, page_index, LinkMode};
|
||||
use crate::view::{build_file_view, build_root, ViewRoot};
|
||||
use crate::view::{build_file_view, build_file_view_with_exec, build_root, ViewRoot};
|
||||
|
||||
pub struct OutputOptions {
|
||||
pub path: PathBuf,
|
||||
@@ -280,26 +280,8 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
|
||||
for rel_pb in &root.files {
|
||||
let rel = rel_pb.to_string_lossy().replace('\\', "/");
|
||||
let abs = resolve_abs(&root, &rel)?;
|
||||
let mut vm = build_file_view(&root, &abs, &rel, &[], false)?;
|
||||
if opts.no_exec {
|
||||
vm.stdout.clear();
|
||||
vm.stderr = "execution skipped (--no-exec)".into();
|
||||
vm.ok = true;
|
||||
vm.plots.clear();
|
||||
vm.bindings_html = String::from(r#"<p class="vars-skipped">skipped</p>"#);
|
||||
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,
|
||||
&[],
|
||||
);
|
||||
}
|
||||
}
|
||||
// V0: apply --no-exec before any capture run (do not execute then clear).
|
||||
let vm = build_file_view_with_exec(&root, &abs, &rel, &[], false, !opts.no_exec)?;
|
||||
let links = LinkMode::Static {
|
||||
from: Some(rel.clone()),
|
||||
};
|
||||
|
||||
+47
-6
@@ -44,23 +44,38 @@ pub struct FileViewModel {
|
||||
/// SVG plots from math lib (embedded in Execution).
|
||||
pub plots: Vec<String>,
|
||||
/// HTML for Variables panel (entry bindings after run).
|
||||
#[allow(dead_code)]
|
||||
pub bindings_html: String,
|
||||
/// ViewExecutionReport JSON for AI / call-picker (empty if no run).
|
||||
pub trace_json: String,
|
||||
/// Static semantic facts; generated without evaluating the document.
|
||||
pub knowledge_html: String,
|
||||
/// Visible when semantic analysis fails (V0); empty when analysis succeeded or was skipped.
|
||||
pub knowledge_error: String,
|
||||
/// V2: page token for SSE stale-packet rejection (empty when unknown).
|
||||
pub page_token: String,
|
||||
}
|
||||
|
||||
/// A compact, textual (not colour-only) explanation of executable knowledge.
|
||||
/// View deliberately compiles semantics without running the target, so a page
|
||||
/// can show binding/effect/verification facts even in `--no-exec` exports.
|
||||
///
|
||||
/// V0: skip module/type container cards by default; rename lock digest accurately.
|
||||
pub fn render_knowledge_html(project: &crate::sema::SemanticProject, rel: &str) -> String {
|
||||
let artifacts: Vec<_> = project.artifacts.iter().filter(|artifact| artifact.source.file == rel).collect();
|
||||
let artifacts: Vec<_> = project
|
||||
.artifacts
|
||||
.iter()
|
||||
.filter(|artifact| {
|
||||
artifact.source.file == rel && artifact.kind != "module" && artifact.kind != "type"
|
||||
})
|
||||
.collect();
|
||||
let steps: Vec<_> = project.steps.iter().filter(|step| step.source.file == rel).collect();
|
||||
if artifacts.is_empty() && steps.is_empty() { return String::new(); }
|
||||
if artifacts.is_empty() && steps.is_empty() {
|
||||
return String::new();
|
||||
}
|
||||
let mut out = String::from(r#"<div class="knowledge-panel" aria-label="Executable knowledge">"#);
|
||||
if !steps.is_empty() {
|
||||
out.push_str(r#"<article class="knowledge-card knowledge-steps"><h3>Steps</h3><ol class="knowledge-step-list">"#);
|
||||
out.push_str(r#"<article class="knowledge-card knowledge-steps"><h3>文档中的步骤</h3><p class="knowledge-hint">结构步骤(非实际执行时序)</p><ol class="knowledge-step-list">"#);
|
||||
for step in &steps {
|
||||
let label = project
|
||||
.refs
|
||||
@@ -93,12 +108,38 @@ pub fn render_knowledge_html(project: &crate::sema::SemanticProject, rel: &str)
|
||||
let signature = artifact.signature.as_ref().map(|sig| {
|
||||
let params = sig.params.iter().map(|param| format!("{}: {}{}", param.name, param.ty, if param.required { "" } else { "?" })).collect::<Vec<_>>().join(", ");
|
||||
format!("({params}) → {}", sig.returns)
|
||||
}).unwrap_or_else(|| "module/type declaration".into());
|
||||
}).unwrap_or_else(|| "declaration".into());
|
||||
let effects = artifact.effects.values().join(", ");
|
||||
let deps = if artifact.dependencies.is_empty() { "none".to_string() } else { artifact.dependencies.iter().map(|id| id.0.as_str()).collect::<Vec<_>>().join(", ") };
|
||||
// Short digest for display; full value in title for copy.
|
||||
let digest = &artifact.hashes.artifact.0;
|
||||
let digest_short = if digest.len() > 20 {
|
||||
format!("{}…", &digest[..20])
|
||||
} else {
|
||||
digest.clone()
|
||||
};
|
||||
let evidence_note = match artifact.verification.evidence.as_str() {
|
||||
"sourced" => "已关联来源,内容尚未核验",
|
||||
"verified" => "证据已核验",
|
||||
"unverified" => "尚无来源记录",
|
||||
other => other,
|
||||
};
|
||||
out.push_str(&format!(
|
||||
r#"<article class="knowledge-card"><h3>{}</h3><dl><dt>Target</dt><dd><code>{}</code></dd><dt>Kind</dt><dd>{}{}</dd><dt>Signature</dt><dd><code>{}</code></dd><dt>Effects</dt><dd>{}</dd><dt>Verification</dt><dd>parse: {}; resolve: {}; contract: {}; tests: {}; evidence: {}</dd><dt>Lock digest</dt><dd><code>{}</code></dd><dt>Depends on</dt><dd><code>{}</code></dd><dt>Execution</dt><dd>Not executed by knowledge preview.</dd></dl></article>"#,
|
||||
escape(&artifact.display_name), escape(target), escape(&artifact.kind), artifact.callable.as_ref().map(|callable| format!(" ({})", escape(callable))).unwrap_or_default(), escape(&signature), escape(&effects), escape(&artifact.verification.parse), escape(&artifact.verification.resolve), escape(&artifact.verification.contract), escape(&artifact.verification.tests), escape(&artifact.verification.evidence), escape(&artifact.hashes.artifact.0), escape(&deps),
|
||||
r#"<article class="knowledge-card" id="knowledge-{name}"><h3>{name} <span class="ks-kind">{kind}</span></h3><dl><dt>Target</dt><dd><code>{target}</code></dd><dt>Signature</dt><dd><code>{sig}</code></dd><dt>Effects</dt><dd>{effects}</dd><dt>Verification</dt><dd>parse: {parse}; resolve: {resolve}; contract: {contract}; tests: {tests}; evidence: {evidence}({evidence_note})</dd><dt>制品摘要</dt><dd><code title="{digest}">{digest_short}</code> <span class="knowledge-hint">(未检查锁定状态)</span></dd><dt>Depends on</dt><dd><code>{deps}</code></dd><dt>Execution</dt><dd>尚无该知识的运行记录(知识预览不执行)。</dd></dl></article>"#,
|
||||
name = escape(&artifact.display_name),
|
||||
kind = escape(&artifact.kind),
|
||||
target = escape(target),
|
||||
sig = escape(&signature),
|
||||
effects = escape(&effects),
|
||||
parse = escape(&artifact.verification.parse),
|
||||
resolve = escape(&artifact.verification.resolve),
|
||||
contract = escape(&artifact.verification.contract),
|
||||
tests = escape(&artifact.verification.tests),
|
||||
evidence = escape(&artifact.verification.evidence),
|
||||
evidence_note = escape(evidence_note),
|
||||
digest = escape(digest),
|
||||
digest_short = escape(&digest_short),
|
||||
deps = escape(&deps),
|
||||
));
|
||||
}
|
||||
out.push_str("</div>");
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
//! Project snapshot analysis cache (M05 / F14): keyed by project_root + source digests.
|
||||
//! Concurrent same-snapshot requests coalesce: waiters reuse the leader's result.
|
||||
|
||||
use sha2::{Digest, Sha256};
|
||||
use std::collections::HashMap;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
use std::sync::{Condvar, Mutex, OnceLock};
|
||||
use std::time::Instant;
|
||||
|
||||
#[derive(Clone)]
|
||||
struct CacheEntry {
|
||||
digest_key: String,
|
||||
#[allow(dead_code)]
|
||||
compiled_at: Instant,
|
||||
}
|
||||
|
||||
struct CacheState {
|
||||
entries: HashMap<String, CacheEntry>,
|
||||
/// project_key → refcount of leaders currently analyzing.
|
||||
inflight: HashMap<String, usize>,
|
||||
}
|
||||
|
||||
fn cache() -> &'static (Mutex<CacheState>, Condvar) {
|
||||
static C: OnceLock<(Mutex<CacheState>, Condvar)> = OnceLock::new();
|
||||
C.get_or_init(|| {
|
||||
(
|
||||
Mutex::new(CacheState {
|
||||
entries: HashMap::new(),
|
||||
inflight: HashMap::new(),
|
||||
}),
|
||||
Condvar::new(),
|
||||
)
|
||||
})
|
||||
}
|
||||
|
||||
static HITS: AtomicU64 = AtomicU64::new(0);
|
||||
static MISSES: AtomicU64 = AtomicU64::new(0);
|
||||
static MERGES: AtomicU64 = AtomicU64::new(0);
|
||||
|
||||
pub fn project_source_digest(project_root: &Path) -> String {
|
||||
let mut h = Sha256::new();
|
||||
h.update(project_root.to_string_lossy().as_bytes());
|
||||
let mut paths: Vec<PathBuf> = Vec::new();
|
||||
if let Ok(rd) = std::fs::read_dir(project_root) {
|
||||
for ent in rd.flatten().take(200) {
|
||||
let p = ent.path();
|
||||
if p.extension().and_then(|e| e.to_str()) == Some("md")
|
||||
|| p
|
||||
.file_name()
|
||||
.and_then(|n| n.to_str())
|
||||
.map(|n| n.ends_with(".mq.md"))
|
||||
.unwrap_or(false)
|
||||
{
|
||||
paths.push(p);
|
||||
}
|
||||
}
|
||||
}
|
||||
paths.sort();
|
||||
for p in paths {
|
||||
h.update(p.to_string_lossy().as_bytes());
|
||||
if let Ok(bytes) = std::fs::read(&p) {
|
||||
h.update(&bytes);
|
||||
}
|
||||
}
|
||||
format!("{:x}", h.finalize())
|
||||
}
|
||||
|
||||
fn project_key(project_root: &Path) -> String {
|
||||
project_root
|
||||
.canonicalize()
|
||||
.unwrap_or_else(|_| project_root.to_path_buf())
|
||||
.to_string_lossy()
|
||||
.to_string()
|
||||
}
|
||||
|
||||
/// Ticket for a leader analysis; must call [`finish_analysis`] (or drop via finish).
|
||||
pub struct AnalysisTicket {
|
||||
key: String,
|
||||
digest: String,
|
||||
/// true ⇒ this caller is the leader and must run compile then finish.
|
||||
pub is_leader: bool,
|
||||
}
|
||||
|
||||
/// Begin analysis: cache hit / wait for in-flight leader / become leader.
|
||||
pub fn begin_analysis(project_root: &Path) -> AnalysisTicket {
|
||||
let key = project_key(project_root);
|
||||
let digest = project_source_digest(project_root);
|
||||
let (lock, cv) = cache();
|
||||
let mut g = lock.lock().unwrap();
|
||||
loop {
|
||||
if let Some(e) = g.entries.get(&key) {
|
||||
if e.digest_key == digest {
|
||||
HITS.fetch_add(1, Ordering::Relaxed);
|
||||
return AnalysisTicket {
|
||||
key,
|
||||
digest,
|
||||
is_leader: false,
|
||||
};
|
||||
}
|
||||
}
|
||||
if g.inflight.contains_key(&key) {
|
||||
MERGES.fetch_add(1, Ordering::Relaxed);
|
||||
g = cv.wait(g).unwrap();
|
||||
continue;
|
||||
}
|
||||
*g.inflight.entry(key.clone()).or_insert(0) += 1;
|
||||
MISSES.fetch_add(1, Ordering::Relaxed);
|
||||
return AnalysisTicket {
|
||||
key,
|
||||
digest,
|
||||
is_leader: true,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
pub fn finish_analysis(ticket: AnalysisTicket) {
|
||||
if !ticket.is_leader {
|
||||
return;
|
||||
}
|
||||
let (lock, cv) = cache();
|
||||
let mut g = lock.lock().unwrap();
|
||||
g.entries.insert(
|
||||
ticket.key.clone(),
|
||||
CacheEntry {
|
||||
digest_key: ticket.digest,
|
||||
compiled_at: Instant::now(),
|
||||
},
|
||||
);
|
||||
if let Some(n) = g.inflight.get_mut(&ticket.key) {
|
||||
*n = n.saturating_sub(1);
|
||||
if *n == 0 {
|
||||
g.inflight.remove(&ticket.key);
|
||||
}
|
||||
}
|
||||
cv.notify_all();
|
||||
}
|
||||
|
||||
/// Compatibility: note without holding across compile (prefer begin/finish).
|
||||
pub fn note_analysis(project_root: &Path) -> bool {
|
||||
let t = begin_analysis(project_root);
|
||||
let hit = !t.is_leader;
|
||||
finish_analysis(t);
|
||||
hit
|
||||
}
|
||||
|
||||
pub fn cache_keys_isolated(a: &Path, b: &Path) -> bool {
|
||||
project_key(a) != project_key(b)
|
||||
}
|
||||
|
||||
pub fn cache_stats() -> (u64, u64, u64) {
|
||||
(
|
||||
HITS.load(Ordering::Relaxed),
|
||||
MISSES.load(Ordering::Relaxed),
|
||||
MERGES.load(Ordering::Relaxed),
|
||||
)
|
||||
}
|
||||
|
||||
pub fn reset_cache_for_tests() {
|
||||
let (lock, cv) = cache();
|
||||
let mut g = lock.lock().unwrap();
|
||||
g.entries.clear();
|
||||
g.inflight.clear();
|
||||
HITS.store(0, Ordering::Relaxed);
|
||||
MISSES.store(0, Ordering::Relaxed);
|
||||
MERGES.store(0, Ordering::Relaxed);
|
||||
cv.notify_all();
|
||||
}
|
||||
@@ -0,0 +1,213 @@
|
||||
//! MLSP `capabilities` — probe loaded plugins and declared features (M00 / F16).
|
||||
//! Feature integers must reflect *implemented and testable* behavior only.
|
||||
|
||||
use serde_json::{json, Value};
|
||||
use std::path::PathBuf;
|
||||
use std::sync::atomic::{AtomicBool, Ordering};
|
||||
|
||||
/// Host/tests may force stream/cancel off for honesty / F16 mismatch cases.
|
||||
static FORCE_STREAM_OFF: AtomicBool = AtomicBool::new(false);
|
||||
static FORCE_CANCEL_OFF: AtomicBool = AtomicBool::new(false);
|
||||
|
||||
pub fn set_event_stream_ready(ready: bool) {
|
||||
FORCE_STREAM_OFF.store(!ready, Ordering::Relaxed);
|
||||
}
|
||||
|
||||
pub fn set_cancel_ready(ready: bool) {
|
||||
FORCE_CANCEL_OFF.store(!ready, Ordering::Relaxed);
|
||||
}
|
||||
|
||||
/// Build the capabilities document. Does not call providers or execute project code.
|
||||
pub fn probe_capabilities(params: &Value) -> Value {
|
||||
let runtime_version = env!("CARGO_PKG_VERSION").to_string();
|
||||
let mut adapters = vec![json!({
|
||||
"id": "openai-compatible",
|
||||
"available": true,
|
||||
"notes": "HTTP chat completions; messages[] preferred over single prompt"
|
||||
})];
|
||||
adapters.push(json!({
|
||||
"id": "ollama-compatible",
|
||||
"available": true,
|
||||
"notes": "OpenAI-compatible path; not a distinct native protocol"
|
||||
}));
|
||||
adapters.push(json!({
|
||||
"id": "anthropic-native",
|
||||
"available": false,
|
||||
"notes": "not verified in this release"
|
||||
}));
|
||||
adapters.push(json!({
|
||||
"id": "gemini-native",
|
||||
"available": false,
|
||||
"notes": "not verified in this release"
|
||||
}));
|
||||
|
||||
let extract_formats = vec![
|
||||
json!({"format": "text", "available": true}),
|
||||
json!({"format": "markdown", "available": true}),
|
||||
json!({"format": "pdf", "available": false}),
|
||||
json!({"format": "docx", "available": false}),
|
||||
json!({"format": "ocr", "available": false}),
|
||||
];
|
||||
|
||||
let loaded_plugins = probe_loaded_plugins(params);
|
||||
|
||||
let llm_loaded = loaded_plugins.iter().any(|p| {
|
||||
p.get("name").and_then(|n| n.as_str()) == Some("llm")
|
||||
&& p.get("available").and_then(|a| a.as_bool()) == Some(true)
|
||||
});
|
||||
|
||||
let stream_off = FORCE_STREAM_OFF.load(Ordering::Relaxed)
|
||||
|| params
|
||||
.get("force_stream_off")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(false);
|
||||
let cancel_off = FORCE_CANCEL_OFF.load(Ordering::Relaxed)
|
||||
|| params
|
||||
.get("force_cancel_off")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(false);
|
||||
|
||||
let mut features = serde_json::Map::new();
|
||||
features.insert(
|
||||
"llm.explicit_selection".into(),
|
||||
json!(if llm_loaded { 1 } else { 0 }),
|
||||
);
|
||||
features.insert(
|
||||
"llm.call_usage".into(),
|
||||
json!(if llm_loaded { 1 } else { 0 }),
|
||||
);
|
||||
features.insert(
|
||||
"llm.messages".into(),
|
||||
json!(if llm_loaded { 1 } else { 0 }),
|
||||
);
|
||||
// M02 implemented: event_sink + web sse-live + MARQDO_CANCEL in llm plugin.
|
||||
features.insert(
|
||||
"runtime.event_stream".into(),
|
||||
json!(if stream_off { 0 } else { 1 }),
|
||||
);
|
||||
features.insert(
|
||||
"runtime.cancel".into(),
|
||||
json!(if cancel_off { 0 } else { 1 }),
|
||||
);
|
||||
#[cfg(feature = "view")]
|
||||
{
|
||||
features.insert("view.document".into(), json!(1));
|
||||
features.insert("view.reference_resolve".into(), json!(1));
|
||||
}
|
||||
#[cfg(not(feature = "view"))]
|
||||
{
|
||||
features.insert("view.document".into(), json!(0));
|
||||
features.insert("view.reference_resolve".into(), json!(0));
|
||||
}
|
||||
|
||||
json!({
|
||||
"schema_version": 1,
|
||||
"runtime_version": runtime_version,
|
||||
"features": features,
|
||||
"adapters": adapters,
|
||||
"extract_formats": extract_formats,
|
||||
"loaded_plugins": loaded_plugins,
|
||||
"contracts": [
|
||||
"ModelSelectionV1",
|
||||
"ModelCallUsageV1",
|
||||
"RuntimeEventV1",
|
||||
"DocumentViewV1",
|
||||
"KnowledgeLocatorV1"
|
||||
]
|
||||
})
|
||||
}
|
||||
|
||||
fn probe_loaded_plugins(params: &Value) -> Vec<Value> {
|
||||
let mut out = Vec::new();
|
||||
let candidates = [
|
||||
("llm", "MARQDO_LLM_PLUGIN", plugin_name("llm")),
|
||||
("agent", "MARQDO_AGENT_PLUGIN", plugin_name("agent")),
|
||||
("web", "MARQDO_WEB_PLUGIN", plugin_name("web")),
|
||||
];
|
||||
let ext_hint = params
|
||||
.get("ext_root")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(PathBuf::from)
|
||||
.or_else(|| std::env::var_os("MARQDO_EXT").map(PathBuf::from));
|
||||
|
||||
let force_unloaded = params
|
||||
.get("force_unloaded")
|
||||
.and_then(|v| v.as_bool())
|
||||
.unwrap_or(false);
|
||||
|
||||
for (name, env_key, filename) in candidates {
|
||||
if force_unloaded {
|
||||
out.push(json!({
|
||||
"name": name,
|
||||
"available": false,
|
||||
"path": Value::Null,
|
||||
"capabilities": [],
|
||||
}));
|
||||
continue;
|
||||
}
|
||||
let mut path: Option<PathBuf> = std::env::var_os(env_key).map(PathBuf::from);
|
||||
if path.as_ref().map(|p| !p.is_file()).unwrap_or(true) {
|
||||
let debug = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("target")
|
||||
.join("debug")
|
||||
.join(&filename);
|
||||
if debug.is_file() {
|
||||
path = Some(debug);
|
||||
}
|
||||
}
|
||||
if path.as_ref().map(|p| !p.is_file()).unwrap_or(true) {
|
||||
if let Some(ext) = &ext_hint {
|
||||
let native = ext.join("native").join(&filename);
|
||||
if native.is_file() {
|
||||
path = Some(native);
|
||||
}
|
||||
}
|
||||
}
|
||||
let available = path.as_ref().map(|p| p.is_file()).unwrap_or(false);
|
||||
let mut caps = Vec::new();
|
||||
if name == "llm" && available {
|
||||
caps.push("call_usage_v1");
|
||||
caps.push("messages_v1");
|
||||
caps.push("explicit_selection_v1");
|
||||
caps.push("cancel_v1");
|
||||
}
|
||||
if name == "agent" && available {
|
||||
caps.push("eng_bind_execute");
|
||||
caps.push("publish_gate");
|
||||
}
|
||||
out.push(json!({
|
||||
"name": name,
|
||||
"available": available,
|
||||
"path": path.map(|p| p.to_string_lossy().to_string()),
|
||||
"capabilities": caps,
|
||||
}));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn plugin_name(stem: &str) -> String {
|
||||
if cfg!(windows) {
|
||||
format!("{stem}.dll")
|
||||
} else if cfg!(target_os = "macos") {
|
||||
format!("lib{stem}.dylib")
|
||||
} else {
|
||||
format!("lib{stem}.so")
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn force_off_and_unloaded_honest() {
|
||||
let caps = probe_capabilities(&json!({
|
||||
"force_unloaded": true,
|
||||
"force_stream_off": true,
|
||||
"force_cancel_off": true,
|
||||
}));
|
||||
assert_eq!(caps["features"]["runtime.event_stream"], 0);
|
||||
assert_eq!(caps["features"]["runtime.cancel"], 0);
|
||||
assert_eq!(caps["features"]["llm.messages"], 0);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,489 @@
|
||||
//! DocumentViewV1 — read-only embedded view (M03). Never executes the document.
|
||||
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde_json::{json, Value};
|
||||
use sha2::{Digest, Sha256};
|
||||
|
||||
use crate::view::{render_knowledge_html, render_module_document, KnowledgePresentation};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct DocumentViewRequest {
|
||||
pub project: PathBuf,
|
||||
pub document: String,
|
||||
pub revision: Option<String>,
|
||||
pub generation: Option<String>,
|
||||
pub node_id: Option<String>,
|
||||
pub include: Vec<String>,
|
||||
}
|
||||
|
||||
impl DocumentViewRequest {
|
||||
pub fn from_params(params: &Value) -> Result<Self, String> {
|
||||
let project = params
|
||||
.get("project")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "view.document requires params.project".to_string())?;
|
||||
let document = params
|
||||
.get("document")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| "view.document requires params.document".to_string())?;
|
||||
let mode = params
|
||||
.get("mode")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("read");
|
||||
if mode != "read" {
|
||||
return Err(format!("view.document unsupported mode={mode}; only read"));
|
||||
}
|
||||
let include = match params.get("include") {
|
||||
Some(Value::Array(a)) => a
|
||||
.iter()
|
||||
.filter_map(|v| v.as_str().map(|s| s.to_string()))
|
||||
.collect(),
|
||||
_ => vec![
|
||||
"fragment".into(),
|
||||
"outline".into(),
|
||||
"nodes".into(),
|
||||
"refs".into(),
|
||||
"diagnostics".into(),
|
||||
],
|
||||
};
|
||||
Ok(Self {
|
||||
project: PathBuf::from(project),
|
||||
document: document.to_string(),
|
||||
revision: params
|
||||
.get("revision")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
generation: params
|
||||
.get("generation")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
node_id: params
|
||||
.get("node_id")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
include,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Pure read path: compile_project (no plugin load / no eval) + fragment render.
|
||||
/// Must never call `build_file_view` with execute=true.
|
||||
pub fn build_document_view(req: &DocumentViewRequest) -> Result<Value, Value> {
|
||||
let project_root = canonicalize_project(&req.project)?;
|
||||
let abs = resolve_under(&project_root, &req.document)?;
|
||||
let raw = fs::read(&abs).map_err(|e| {
|
||||
err(
|
||||
"view.document_read_failed",
|
||||
format!("cannot read {}: {e}", abs.display()),
|
||||
)
|
||||
})?;
|
||||
let source_revision = format!("sha256:{:x}", Sha256::digest(&raw));
|
||||
if let Some(expected) = &req.revision {
|
||||
if expected != &source_revision && !expected.is_empty() {
|
||||
return Err(err(
|
||||
"view.revision_mismatch",
|
||||
format!("requested {expected} but file is {source_revision}; refusing silent downgrade"),
|
||||
));
|
||||
}
|
||||
}
|
||||
let source = String::from_utf8_lossy(&raw).into_owned();
|
||||
let title = title_from_source(&source, &req.document);
|
||||
|
||||
// Semantic projection — compile_project does not load plugins / evaluate.
|
||||
// Hold analysis lock across compile so concurrent same-snapshot reads coalesce (F14).
|
||||
let ticket = crate::workbench::analysis_cache::begin_analysis(&project_root);
|
||||
let options = crate::sema::CompileOptions::for_path(&project_root)
|
||||
.map_err(|e| err("view.compile_failed", format!("{e:#}")))?;
|
||||
let compilation = match crate::sema::compile_project(&options) {
|
||||
Ok(c) => {
|
||||
crate::workbench::analysis_cache::finish_analysis(ticket);
|
||||
c
|
||||
}
|
||||
Err(e) => {
|
||||
crate::workbench::analysis_cache::finish_analysis(ticket);
|
||||
return Err(err("view.compile_failed", format!("{e:#}")));
|
||||
}
|
||||
};
|
||||
|
||||
let rel = req.document.replace('\\', "/");
|
||||
let mut presentation = KnowledgePresentation::from_project(&compilation.semantics, &rel, &title);
|
||||
presentation.page_token = {
|
||||
let mut h = Sha256::new();
|
||||
h.update(raw.as_slice());
|
||||
h.update(presentation.semantic_generation.as_bytes());
|
||||
format!("{:x}", h.finalize())
|
||||
};
|
||||
|
||||
if let Some(gen) = &req.generation {
|
||||
if !gen.is_empty() && gen != &presentation.semantic_generation {
|
||||
return Err(err(
|
||||
"view.generation_mismatch",
|
||||
format!(
|
||||
"requested generation {gen} but projection is {}; refusing silent downgrade",
|
||||
presentation.semantic_generation
|
||||
),
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
let wants = |k: &str| req.include.iter().any(|x| x == k);
|
||||
|
||||
let heading_outline = outline_from_headings(&source, &presentation);
|
||||
|
||||
// Prefer document surface HTML when parseable; fall back to knowledge HTML.
|
||||
// Never call build_file_view (that path executes).
|
||||
let fragment = if wants("fragment") {
|
||||
let raw_html = match crate::load::parse_source_auto(&source) {
|
||||
Ok(module) => render_module_document(&module, &source, &[]),
|
||||
Err(_) => render_knowledge_html(&compilation.semantics, &rel),
|
||||
};
|
||||
wrap_fragment(&inject_mq_node_attrs(&raw_html, &heading_outline, &presentation))
|
||||
} else {
|
||||
String::new()
|
||||
};
|
||||
|
||||
let outline = if wants("outline") {
|
||||
if heading_outline.is_empty() {
|
||||
outline_from_presentation(&presentation)
|
||||
} else {
|
||||
json!(heading_outline)
|
||||
}
|
||||
} else {
|
||||
json!([])
|
||||
};
|
||||
let nodes = if wants("nodes") {
|
||||
nodes_from_presentation_and_steps(
|
||||
&presentation,
|
||||
&compilation.semantics,
|
||||
&rel,
|
||||
&req.node_id,
|
||||
)
|
||||
} else {
|
||||
json!([])
|
||||
};
|
||||
let refs = if wants("refs") {
|
||||
refs_from_project(&compilation.semantics, &rel)
|
||||
} else {
|
||||
json!([])
|
||||
};
|
||||
|
||||
let mut diag_msgs: Vec<String> = presentation.diagnostics.clone();
|
||||
for d in &compilation.diagnostics {
|
||||
diag_msgs.push(d.message.clone());
|
||||
}
|
||||
let diagnostics = if wants("diagnostics") {
|
||||
json!(diag_msgs)
|
||||
} else {
|
||||
json!([])
|
||||
};
|
||||
|
||||
let completeness = if diag_msgs.is_empty() {
|
||||
"complete"
|
||||
} else {
|
||||
"partial"
|
||||
};
|
||||
|
||||
let snapshot = crate::workbench::snapshot::build_snapshot_manifest(
|
||||
&project_root,
|
||||
&rel,
|
||||
&raw,
|
||||
&compilation.semantics,
|
||||
"1",
|
||||
);
|
||||
|
||||
Ok(json!({
|
||||
"schema": "DocumentViewV1",
|
||||
"schema_version": 1,
|
||||
"document": {
|
||||
"id": rel,
|
||||
"title": title,
|
||||
"source_revision": source_revision,
|
||||
"semantic_digest": presentation.source_digest,
|
||||
"generation_id": if presentation.semantic_generation.is_empty() {
|
||||
Value::Null
|
||||
} else {
|
||||
json!(presentation.semantic_generation)
|
||||
},
|
||||
"presentation_token": presentation.page_token,
|
||||
},
|
||||
"execution": {"state": "not_run", "run_id": Value::Null},
|
||||
"render": {
|
||||
"format": "sanitized_html",
|
||||
"fragment": fragment,
|
||||
"renderer_version": "1"
|
||||
},
|
||||
"outline": outline,
|
||||
"nodes": nodes,
|
||||
"refs": refs,
|
||||
"diagnostics": diagnostics,
|
||||
"completeness": completeness,
|
||||
"snapshot": snapshot,
|
||||
"capabilities": {"read_only": true, "has_semantics": true, "executed": false}
|
||||
}))
|
||||
}
|
||||
|
||||
fn wrap_fragment(inner: &str) -> String {
|
||||
// No html/body, no scripts, namespaced for host theming.
|
||||
let sanitized = strip_script_tags(inner);
|
||||
format!("<article class=\"mq-document\">{sanitized}</article>")
|
||||
}
|
||||
|
||||
/// Remove `<script…>` blocks (case-insensitive) so embed fragments stay non-executable.
|
||||
fn strip_script_tags(html: &str) -> String {
|
||||
let lower = html.to_ascii_lowercase();
|
||||
let mut out = String::with_capacity(html.len());
|
||||
let mut i = 0usize;
|
||||
while i < html.len() {
|
||||
if lower[i..].starts_with("<script") {
|
||||
let after_open = lower[i..]
|
||||
.find('>')
|
||||
.map(|p| i + p + 1)
|
||||
.unwrap_or(html.len());
|
||||
if let Some(rel) = lower[after_open..].find("</script") {
|
||||
let close_at = after_open + rel;
|
||||
let end = lower[close_at..]
|
||||
.find('>')
|
||||
.map(|p| close_at + p + 1)
|
||||
.unwrap_or(html.len());
|
||||
i = end;
|
||||
} else {
|
||||
// Truncate from the dangerous open tag onward.
|
||||
break;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
// Advance one UTF-8 char so multi-byte text stays intact.
|
||||
let ch = html[i..].chars().next().unwrap();
|
||||
out.push(ch);
|
||||
i += ch.len_utf8();
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn title_from_source(source: &str, fallback: &str) -> String {
|
||||
for line in source.lines().take(40) {
|
||||
let t = line.trim();
|
||||
if let Some(rest) = t.strip_prefix("# ") {
|
||||
return rest.trim().to_string();
|
||||
}
|
||||
if let Some(rest) = t.strip_prefix("title:") {
|
||||
return rest.trim().trim_matches('"').to_string();
|
||||
}
|
||||
}
|
||||
Path::new(fallback)
|
||||
.file_stem()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or(fallback)
|
||||
.to_string()
|
||||
}
|
||||
|
||||
/// Outline entries from Markdown / Marqdo `#` headings; prefer matching node ids.
|
||||
fn outline_from_headings(source: &str, p: &KnowledgePresentation) -> Vec<Value> {
|
||||
let mut items = Vec::new();
|
||||
let mut order = 0usize;
|
||||
for (idx, line) in source.lines().enumerate() {
|
||||
let line_no = (idx + 1) as u32;
|
||||
let trimmed = line.trim_start();
|
||||
if !trimmed.starts_with('#') {
|
||||
continue;
|
||||
}
|
||||
let hashes = trimmed.chars().take_while(|c| *c == '#').count();
|
||||
if hashes == 0 || hashes > 6 {
|
||||
continue;
|
||||
}
|
||||
// `# Title`, `## Section`, or Marqdo `#main` / `##greet` (no space).
|
||||
let after = &trimmed[hashes..];
|
||||
let label = after.trim();
|
||||
if label.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let matched = p.nodes.iter().find(|n| {
|
||||
n.source_line == line_no
|
||||
|| n.display_name == label
|
||||
|| n.node_id == label
|
||||
|| n.artifact_id.as_deref() == Some(label)
|
||||
});
|
||||
let id = matched
|
||||
.map(|n| n.node_id.clone())
|
||||
.unwrap_or_else(|| format!("heading:{line_no}"));
|
||||
let artifact_id = matched.and_then(|n| n.artifact_id.clone());
|
||||
items.push(json!({
|
||||
"id": id,
|
||||
"parent_id": Value::Null,
|
||||
"kind": "heading",
|
||||
"label": label,
|
||||
"order": order,
|
||||
"source_span": {"line": line_no},
|
||||
"artifact_id": artifact_id,
|
||||
}));
|
||||
order += 1;
|
||||
}
|
||||
items
|
||||
}
|
||||
|
||||
/// Stamp `data-mq-node` onto elements that already carry `data-line` matching a node/outline id.
|
||||
fn inject_mq_node_attrs(html: &str, outline: &[Value], p: &KnowledgePresentation) -> String {
|
||||
let mut out = html.to_string();
|
||||
let mut bindings: Vec<(u32, String)> = Vec::new();
|
||||
for n in &p.nodes {
|
||||
bindings.push((n.source_line, n.node_id.clone()));
|
||||
}
|
||||
for item in outline {
|
||||
if let (Some(line), Some(id)) = (
|
||||
item.pointer("/source_span/line").and_then(|v| v.as_u64()),
|
||||
item.get("id").and_then(|v| v.as_str()),
|
||||
) {
|
||||
bindings.push((line as u32, id.to_string()));
|
||||
}
|
||||
}
|
||||
bindings.sort_by_key(|(line, _)| *line);
|
||||
bindings.dedup_by_key(|(line, _)| *line);
|
||||
for (line, id) in bindings {
|
||||
let needle = format!("data-line=\"{line}\"");
|
||||
let attr = format!("data-line=\"{line}\" data-mq-node=\"{}\"", html_attr_escape(&id));
|
||||
if out.contains(&needle) && !out.contains(&format!("data-mq-node=\"{}\"", html_attr_escape(&id))) {
|
||||
out = out.replacen(&needle, &attr, 1);
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn html_attr_escape(s: &str) -> String {
|
||||
s.replace('&', "&")
|
||||
.replace('"', """)
|
||||
.replace('<', "<")
|
||||
}
|
||||
|
||||
fn outline_from_presentation(p: &KnowledgePresentation) -> Value {
|
||||
json!(p
|
||||
.nodes
|
||||
.iter()
|
||||
.enumerate()
|
||||
.map(|(i, n)| json!({
|
||||
"id": n.node_id,
|
||||
"parent_id": Value::Null,
|
||||
"kind": "heading",
|
||||
"label": n.display_name,
|
||||
"order": i,
|
||||
"artifact_id": n.artifact_id,
|
||||
}))
|
||||
.collect::<Vec<_>>())
|
||||
}
|
||||
|
||||
fn nodes_from_presentation_and_steps(
|
||||
p: &KnowledgePresentation,
|
||||
project: &crate::sema::SemanticProject,
|
||||
rel: &str,
|
||||
filter: &Option<String>,
|
||||
) -> Value {
|
||||
let mut out = Vec::new();
|
||||
for n in &p.nodes {
|
||||
if filter
|
||||
.as_ref()
|
||||
.map(|f| &n.node_id == f || n.artifact_id.as_ref() == Some(f))
|
||||
.unwrap_or(true)
|
||||
{
|
||||
out.push(json!({
|
||||
"id": n.node_id,
|
||||
"parent_id": Value::Null,
|
||||
"kind": n.kind,
|
||||
"label": n.display_name,
|
||||
"order": n.source_line,
|
||||
"source_span": {"file": n.source_file, "line": n.source_line},
|
||||
"artifact_id": n.artifact_id,
|
||||
"ref_ids": [],
|
||||
"children": [],
|
||||
"evidence": n.evidence,
|
||||
"effects": n.effects,
|
||||
"dependencies": n.dependencies,
|
||||
"signature": n.signature,
|
||||
}));
|
||||
}
|
||||
}
|
||||
// F09: project KnowledgeStep kinds (observe/derive/call/iterate/…) into the read model.
|
||||
for step in &project.steps {
|
||||
if step.source.file != rel {
|
||||
continue;
|
||||
}
|
||||
let id = step.id.0.clone();
|
||||
if filter
|
||||
.as_ref()
|
||||
.map(|f| &id == f || &step.reference == f)
|
||||
.unwrap_or(true)
|
||||
{
|
||||
out.push(json!({
|
||||
"id": id,
|
||||
"parent_id": Value::Null,
|
||||
"kind": step.kind,
|
||||
"label": step.reference,
|
||||
"order": step.source.line,
|
||||
"source_span": {
|
||||
"file": step.source.file,
|
||||
"line": step.source.line,
|
||||
"end_line": step.source.end_line
|
||||
},
|
||||
"artifact_id": Value::Null,
|
||||
"ref_ids": step.calls.iter().map(|c| c.as_str()).collect::<Vec<_>>(),
|
||||
"children": [],
|
||||
"evidence": "unverified",
|
||||
"effects": step.effects.values(),
|
||||
}));
|
||||
}
|
||||
}
|
||||
json!(out)
|
||||
}
|
||||
|
||||
fn refs_from_project(project: &crate::sema::SemanticProject, rel: &str) -> Value {
|
||||
let mut refs = Vec::new();
|
||||
for a in &project.artifacts {
|
||||
if a.source.file != rel {
|
||||
continue;
|
||||
}
|
||||
for dep in &a.dependencies {
|
||||
refs.push(json!({
|
||||
"id": format!("ref:{}:{}", a.artifact_id.0, dep.0),
|
||||
"from_artifact_id": a.artifact_id.0,
|
||||
"to": dep.0,
|
||||
"relation": "depends_on",
|
||||
}));
|
||||
}
|
||||
}
|
||||
json!(refs)
|
||||
}
|
||||
|
||||
fn canonicalize_project(p: &Path) -> Result<PathBuf, Value> {
|
||||
let root = if p.is_file() {
|
||||
p.parent().unwrap_or_else(|| Path::new(".")).to_path_buf()
|
||||
} else {
|
||||
p.to_path_buf()
|
||||
};
|
||||
root.canonicalize().map_err(|e| {
|
||||
err(
|
||||
"view.project_invalid",
|
||||
format!("project {}: {e}", root.display()),
|
||||
)
|
||||
})
|
||||
}
|
||||
|
||||
fn resolve_under(root: &Path, rel: &str) -> Result<PathBuf, Value> {
|
||||
let joined = root.join(rel);
|
||||
let canon = joined.canonicalize().map_err(|e| {
|
||||
err(
|
||||
"view.document_not_found",
|
||||
format!("{}: {e}", joined.display()),
|
||||
)
|
||||
})?;
|
||||
if !canon.starts_with(root) {
|
||||
return Err(err(
|
||||
"view.path_escape",
|
||||
"document path escapes project root",
|
||||
));
|
||||
}
|
||||
Ok(canon)
|
||||
}
|
||||
|
||||
fn err(code: &str, message: impl Into<String>) -> Value {
|
||||
json!({"code": code, "message": message.into()})
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
//! Request-local RuntimeEventV1 sink (M02). Avoids process-global event mix-up.
|
||||
|
||||
use serde_json::{json, Value};
|
||||
use std::fs::OpenOptions;
|
||||
use std::io::Write;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
use std::sync::{Mutex, OnceLock};
|
||||
|
||||
static SEQ: AtomicU64 = AtomicU64::new(0);
|
||||
|
||||
fn sink_path() -> &'static Mutex<Option<PathBuf>> {
|
||||
static SINK: OnceLock<Mutex<Option<PathBuf>>> = OnceLock::new();
|
||||
SINK.get_or_init(|| Mutex::new(None))
|
||||
}
|
||||
|
||||
/// Bind this process/request to an NDJSON event file (also used by web sse-live).
|
||||
pub fn bind_event_sink(path: impl AsRef<Path>) {
|
||||
if let Ok(mut g) = sink_path().lock() {
|
||||
*g = Some(path.as_ref().to_path_buf());
|
||||
}
|
||||
crate::workbench::capabilities::set_event_stream_ready(true);
|
||||
}
|
||||
|
||||
pub fn clear_event_sink() {
|
||||
if let Ok(mut g) = sink_path().lock() {
|
||||
*g = None;
|
||||
}
|
||||
}
|
||||
|
||||
pub fn emit_event(run_id: &str, event_type: &str, payload: Value) -> Value {
|
||||
let seq = SEQ.fetch_add(1, Ordering::Relaxed);
|
||||
let event_id = format!("evt-{run_id}-{seq}");
|
||||
let ev = crate::workbench::usage::runtime_event(&event_id, seq, run_id, event_type, payload);
|
||||
if let Ok(g) = sink_path().lock() {
|
||||
if let Some(path) = g.as_ref() {
|
||||
if let Ok(mut f) = OpenOptions::new().create(true).append(true).open(path) {
|
||||
let _ = writeln!(f, "{}", ev);
|
||||
}
|
||||
}
|
||||
}
|
||||
// Also honor MARQDO_EVENT_FORWARD for subtask/web bridge.
|
||||
if let Ok(fwd) = std::env::var("MARQDO_EVENT_FORWARD") {
|
||||
if !fwd.is_empty() {
|
||||
if let Ok(mut f) = OpenOptions::new().create(true).append(true).open(&fwd) {
|
||||
let _ = writeln!(f, "{}", ev);
|
||||
}
|
||||
}
|
||||
}
|
||||
ev
|
||||
}
|
||||
|
||||
pub fn emit_message_delta(run_id: &str, text: &str) -> Value {
|
||||
emit_event(
|
||||
run_id,
|
||||
"message.delta",
|
||||
json!({"text": text, "format": "plain"}),
|
||||
)
|
||||
}
|
||||
@@ -0,0 +1,304 @@
|
||||
//! KnowledgeLocatorV1 + view.reference_resolve (M04).
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct KnowledgeLocator {
|
||||
pub project_id: String,
|
||||
pub document_id: String,
|
||||
pub source_revision: Option<String>,
|
||||
pub generation_id: Option<String>,
|
||||
pub artifact_id: Option<String>,
|
||||
pub node_id: Option<String>,
|
||||
pub source_ref_id: Option<String>,
|
||||
pub span: Option<Value>,
|
||||
pub relation: String,
|
||||
}
|
||||
|
||||
impl KnowledgeLocator {
|
||||
pub fn from_params(params: &Value) -> Result<Self, String> {
|
||||
let loc = params.get("locator").unwrap_or(params);
|
||||
Ok(Self {
|
||||
project_id: loc
|
||||
.get("project_id")
|
||||
.or_else(|| params.get("project"))
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string(),
|
||||
document_id: loc
|
||||
.get("document_id")
|
||||
.or_else(|| params.get("document"))
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string(),
|
||||
source_revision: loc
|
||||
.get("source_revision")
|
||||
.or_else(|| loc.get("revision"))
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
generation_id: loc
|
||||
.get("generation_id")
|
||||
.or_else(|| loc.get("generation"))
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
artifact_id: loc
|
||||
.get("artifact_id")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
node_id: loc
|
||||
.get("node_id")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
source_ref_id: loc
|
||||
.get("source_ref_id")
|
||||
.or_else(|| loc.get("ref_id"))
|
||||
.and_then(|v| v.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
span: loc.get("span").cloned(),
|
||||
relation: loc
|
||||
.get("relation")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("cites")
|
||||
.to_string(),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"project_id": self.project_id,
|
||||
"document_id": self.document_id,
|
||||
"source_revision": self.source_revision,
|
||||
"generation_id": self.generation_id,
|
||||
"artifact_id": self.artifact_id,
|
||||
"node_id": self.node_id,
|
||||
"source_ref_id": self.source_ref_id,
|
||||
"span": self.span,
|
||||
"relation": self.relation,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Resolve a locator or current-document ref_id against a project snapshot.
|
||||
/// Never silently falls back to "latest" when expected revision/generation mismatch.
|
||||
pub fn resolve_reference(params: &Value) -> Result<Value, Value> {
|
||||
let locator = KnowledgeLocator::from_params(params).map_err(|e| {
|
||||
json!({"code": "locator.bad_request", "message": e})
|
||||
})?;
|
||||
if locator.project_id.is_empty() {
|
||||
return Err(json!({
|
||||
"code": "locator.bad_request",
|
||||
"message": "project_id/project required"
|
||||
}));
|
||||
}
|
||||
let root = PathBuf::from(&locator.project_id);
|
||||
let root = root.canonicalize().map_err(|e| {
|
||||
json!({"code": "locator.project_invalid", "message": format!("{e}")})
|
||||
})?;
|
||||
|
||||
let options = crate::sema::CompileOptions::for_path(&root).map_err(|e| {
|
||||
json!({"code": "locator.compile_failed", "message": format!("{e:#}")})
|
||||
})?;
|
||||
let compilation = crate::sema::compile_project(&options).map_err(|e| {
|
||||
json!({"code": "locator.compile_failed", "message": format!("{e:#}")})
|
||||
})?;
|
||||
|
||||
// Generation mismatch → version_unavailable / stale (no silent current).
|
||||
if let Some(expected_gen) = &locator.generation_id {
|
||||
if !expected_gen.is_empty() {
|
||||
let current_gen = semantic_generation(&compilation.semantics);
|
||||
if ¤t_gen != expected_gen {
|
||||
return Ok(crate::workbench::snapshot::version_unavailable_result(
|
||||
&locator.to_json(),
|
||||
&format!(
|
||||
"expected generation {expected_gen}, current projection is {current_gen}; refusing silent downgrade (no retained snapshot)"
|
||||
),
|
||||
expected_gen,
|
||||
Some(¤t_gen),
|
||||
));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Source revision check when document is known.
|
||||
if let (Some(expected_rev), true) = (
|
||||
&locator.source_revision,
|
||||
!locator.document_id.is_empty(),
|
||||
) {
|
||||
if !expected_rev.is_empty() {
|
||||
let abs = resolve_under(&root, &locator.document_id)?;
|
||||
let raw = std::fs::read(&abs).map_err(|e| {
|
||||
json!({"code": "locator.source_unreadable", "message": format!("{e}")})
|
||||
})?;
|
||||
use sha2::{Digest, Sha256};
|
||||
let actual = format!("sha256:{:x}", Sha256::digest(&raw));
|
||||
if &actual != expected_rev {
|
||||
return Ok(json!({
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "stale",
|
||||
"precision": "document",
|
||||
"locator": locator.to_json(),
|
||||
"target": {
|
||||
"document_id": locator.document_id,
|
||||
"source_revision": actual,
|
||||
"note": "source changed since citation"
|
||||
},
|
||||
"candidates": [],
|
||||
"diagnostics": [{
|
||||
"code": "source_revision_mismatch",
|
||||
"message": format!("expected {expected_rev}, actual {actual}")
|
||||
}],
|
||||
"label": "该来源已变化"
|
||||
}));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let query = locator
|
||||
.artifact_id
|
||||
.clone()
|
||||
.or_else(|| locator.node_id.clone())
|
||||
.or_else(|| locator.source_ref_id.clone());
|
||||
|
||||
let Some(q) = query else {
|
||||
if locator.document_id.is_empty() {
|
||||
return Ok(json!({
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "unresolved",
|
||||
"precision": "none",
|
||||
"locator": locator.to_json(),
|
||||
"target": Value::Null,
|
||||
"candidates": [],
|
||||
"diagnostics": [{"code": "missing_target", "message": "no artifact/node/ref id"}],
|
||||
"label": "无法定位该知识"
|
||||
}));
|
||||
}
|
||||
return Ok(json!({
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "resolved",
|
||||
"precision": "document",
|
||||
"locator": locator.to_json(),
|
||||
"target": {
|
||||
"document_id": locator.document_id,
|
||||
"relation": locator.relation,
|
||||
},
|
||||
"candidates": [],
|
||||
"diagnostics": [],
|
||||
"label": locator.document_id,
|
||||
}));
|
||||
};
|
||||
|
||||
let mut matches: Vec<&crate::sema::SemanticArtifact> = compilation
|
||||
.semantics
|
||||
.artifacts
|
||||
.iter()
|
||||
.filter(|a| {
|
||||
a.artifact_id.0 == q
|
||||
|| a.display_name == q
|
||||
|| a.symbol_id
|
||||
.as_ref()
|
||||
.map(|s| s.as_str() == q)
|
||||
.unwrap_or(false)
|
||||
})
|
||||
.collect();
|
||||
|
||||
if !locator.document_id.is_empty() {
|
||||
let scoped: Vec<_> = matches
|
||||
.iter()
|
||||
.copied()
|
||||
.filter(|a| a.source.file == locator.document_id)
|
||||
.collect();
|
||||
if !scoped.is_empty() {
|
||||
matches = scoped;
|
||||
}
|
||||
}
|
||||
|
||||
match matches.len() {
|
||||
0 => Ok(json!({
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "unresolved",
|
||||
"precision": "none",
|
||||
"locator": locator.to_json(),
|
||||
"target": Value::Null,
|
||||
"candidates": [],
|
||||
"diagnostics": [{"code": "not_found", "message": format!("no artifact matching {q}")}],
|
||||
"label": "尚未定位到具体知识"
|
||||
})),
|
||||
1 => {
|
||||
let a = matches[0];
|
||||
Ok(json!({
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "resolved",
|
||||
"precision": "artifact",
|
||||
"locator": locator.to_json(),
|
||||
"target": {
|
||||
"artifact_id": a.artifact_id.0,
|
||||
"display_name": a.display_name,
|
||||
"document_id": a.source.file,
|
||||
"span": {"line": a.source.line, "end_line": a.source.end_line},
|
||||
"evidence": a.verification.evidence,
|
||||
"relation": locator.relation,
|
||||
},
|
||||
"candidates": [],
|
||||
"diagnostics": [],
|
||||
"label": a.display_name,
|
||||
}))
|
||||
}
|
||||
_ => {
|
||||
let candidates: Vec<Value> = matches
|
||||
.iter()
|
||||
.map(|a| {
|
||||
json!({
|
||||
"artifact_id": a.artifact_id.0,
|
||||
"display_name": a.display_name,
|
||||
"document_id": a.source.file,
|
||||
"line": a.source.line,
|
||||
})
|
||||
})
|
||||
.collect();
|
||||
Ok(json!({
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "ambiguous",
|
||||
"precision": "none",
|
||||
"locator": locator.to_json(),
|
||||
"target": Value::Null,
|
||||
"candidates": candidates,
|
||||
"diagnostics": [{"code": "ambiguous", "message": format!("{} candidates for {q}", matches.len())}],
|
||||
"label": "存在多个候选"
|
||||
}))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn semantic_generation(project: &crate::sema::SemanticProject) -> String {
|
||||
use sha2::{Digest, Sha256};
|
||||
let mut gh = Sha256::new();
|
||||
gh.update(project.project_id.as_bytes());
|
||||
for a in &project.artifacts {
|
||||
gh.update(a.hashes.artifact.0.as_bytes());
|
||||
}
|
||||
format!("{:x}", gh.finalize())[..16].to_string()
|
||||
}
|
||||
|
||||
fn resolve_under(root: &Path, rel: &str) -> Result<PathBuf, Value> {
|
||||
let joined = root.join(rel);
|
||||
let canon = joined.canonicalize().map_err(|e| {
|
||||
json!({"code": "locator.document_not_found", "message": format!("{}: {e}", joined.display())})
|
||||
})?;
|
||||
if !canon.starts_with(root) {
|
||||
return Err(json!({
|
||||
"code": "locator.path_escape",
|
||||
"message": "document path escapes project root"
|
||||
}));
|
||||
}
|
||||
Ok(canon)
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
//! Workbench runtime contracts (M00–M05): schemas, capabilities, DocumentView,
|
||||
//! KnowledgeLocator, ModelSelection / ModelCallUsage / RuntimeEvent / RunContext.
|
||||
//!
|
||||
//! Spec: `doc/design/qdagent-workbench-runtime-and-view-2026-10-25.md`.
|
||||
//! These are v1 contracts distinct from KnowledgePresentation `schema_version:1`.
|
||||
|
||||
pub mod analysis_cache;
|
||||
pub mod capabilities;
|
||||
#[cfg(feature = "view")]
|
||||
pub mod document_view;
|
||||
pub mod event_sink;
|
||||
pub mod locator;
|
||||
pub mod run_context;
|
||||
pub mod selection;
|
||||
pub mod snapshot;
|
||||
pub mod usage;
|
||||
|
||||
pub use analysis_cache::{
|
||||
begin_analysis, cache_keys_isolated, cache_stats, finish_analysis, note_analysis,
|
||||
project_source_digest, reset_cache_for_tests, AnalysisTicket,
|
||||
};
|
||||
pub use capabilities::probe_capabilities;
|
||||
#[cfg(feature = "view")]
|
||||
pub use document_view::{build_document_view, DocumentViewRequest};
|
||||
pub use event_sink::{bind_event_sink, clear_event_sink, emit_event, emit_message_delta};
|
||||
pub use locator::{resolve_reference, KnowledgeLocator};
|
||||
pub use run_context::{cancel_requested, RunContext};
|
||||
pub use selection::{parse_model_selection, ModelSelection};
|
||||
pub use snapshot::{build_snapshot_manifest, version_unavailable_result};
|
||||
pub use usage::{
|
||||
model_call_usage_from_provider, model_call_usage_from_provider_rev, replace_usage_if_newer,
|
||||
runtime_event, token_or_null,
|
||||
};
|
||||
@@ -0,0 +1,148 @@
|
||||
//! RunContextV1 — request-local run identity for selection / usage / cancel (M01).
|
||||
|
||||
use serde_json::{json, Map, Value};
|
||||
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct RunContext {
|
||||
pub run_id: String,
|
||||
pub parent_run_id: Option<String>,
|
||||
pub turn_id: Option<String>,
|
||||
pub workspace_scope: Option<String>,
|
||||
pub selection_context: Map<String, Value>,
|
||||
pub usage_sink: Option<String>,
|
||||
pub event_sink: Option<String>,
|
||||
pub cancellation_token: Option<String>,
|
||||
}
|
||||
|
||||
impl RunContext {
|
||||
pub fn from_value(v: &Value) -> Result<Self, String> {
|
||||
let run_id = v
|
||||
.get("run_id")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.ok_or_else(|| "run_context.missing:run_id".to_string())?
|
||||
.to_string();
|
||||
Ok(Self {
|
||||
run_id,
|
||||
parent_run_id: v
|
||||
.get("parent_run_id")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string()),
|
||||
turn_id: v
|
||||
.get("turn_id")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string()),
|
||||
workspace_scope: v
|
||||
.get("workspace_scope")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string()),
|
||||
selection_context: v
|
||||
.get("selection_context")
|
||||
.and_then(|x| x.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default(),
|
||||
usage_sink: v
|
||||
.get("usage_sink")
|
||||
.and_then(|x| x.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
event_sink: v
|
||||
.get("event_sink")
|
||||
.and_then(|x| x.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
cancellation_token: v
|
||||
.get("cancellation_token")
|
||||
.and_then(|x| x.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"schema": "RunContextV1",
|
||||
"schema_version": 1,
|
||||
"run_id": self.run_id,
|
||||
"parent_run_id": self.parent_run_id,
|
||||
"turn_id": self.turn_id,
|
||||
"workspace_scope": self.workspace_scope,
|
||||
"selection_context": self.selection_context,
|
||||
"usage_sink": self.usage_sink,
|
||||
"event_sink": self.event_sink,
|
||||
"cancellation_token": self.cancellation_token,
|
||||
})
|
||||
}
|
||||
|
||||
/// Child inherits selection/event/cancel; new run_id linked to parent.
|
||||
pub fn spawn_child(&self, child_run_id: &str) -> Self {
|
||||
Self {
|
||||
run_id: child_run_id.to_string(),
|
||||
parent_run_id: Some(self.run_id.clone()),
|
||||
turn_id: self.turn_id.clone(),
|
||||
workspace_scope: self.workspace_scope.clone(),
|
||||
selection_context: self.selection_context.clone(),
|
||||
usage_sink: self.usage_sink.clone(),
|
||||
event_sink: self.event_sink.clone(),
|
||||
cancellation_token: self.cancellation_token.clone(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Env vars for subtask injection (never includes api_key).
|
||||
pub fn selection_env(&self) -> Vec<(String, String)> {
|
||||
let mut out = Vec::new();
|
||||
out.push(("MARQDO_RUN_ID".into(), self.run_id.clone()));
|
||||
if let Some(p) = &self.parent_run_id {
|
||||
out.push(("MARQDO_PARENT_RUN_ID".into(), p.clone()));
|
||||
}
|
||||
if let Some(t) = &self.turn_id {
|
||||
out.push(("MARQDO_TURN_ID".into(), t.clone()));
|
||||
}
|
||||
if let Some(w) = &self.workspace_scope {
|
||||
out.push(("MARQDO_WORKSPACE_SCOPE".into(), w.clone()));
|
||||
}
|
||||
if let Some(tok) = &self.cancellation_token {
|
||||
out.push(("MARQDO_CANCEL_TOKEN".into(), tok.clone()));
|
||||
}
|
||||
if let Some(sink) = &self.event_sink {
|
||||
out.push(("MARQDO_EVENT_FORWARD".into(), sink.clone()));
|
||||
}
|
||||
if let Some(model) = self
|
||||
.selection_context
|
||||
.get("upstream_model_id")
|
||||
.or_else(|| self.selection_context.get("model"))
|
||||
.and_then(|v| v.as_str())
|
||||
{
|
||||
out.push(("MARQDO_LLM_MODEL".into(), model.to_string()));
|
||||
out.push(("OPENAI_MODEL".into(), model.to_string()));
|
||||
}
|
||||
if let Some(base) = self
|
||||
.selection_context
|
||||
.get("base_url")
|
||||
.and_then(|v| v.as_str())
|
||||
{
|
||||
out.push(("MARQDO_LLM_BASE_URL".into(), base.to_string()));
|
||||
out.push(("OPENAI_BASE_URL".into(), base.to_string()));
|
||||
}
|
||||
out
|
||||
}
|
||||
}
|
||||
|
||||
/// Check whether a cancel token file/env indicates cancellation.
|
||||
pub fn cancel_requested(token: Option<&str>) -> bool {
|
||||
let Some(tok) = token.filter(|s| !s.is_empty()) else {
|
||||
return false;
|
||||
};
|
||||
// Token may be a path: presence of file or contents "1"/"cancelled" means stop.
|
||||
let path = std::path::Path::new(tok);
|
||||
if path.is_file() {
|
||||
if let Ok(body) = std::fs::read_to_string(path) {
|
||||
let t = body.trim();
|
||||
return t.is_empty() || t == "1" || t.eq_ignore_ascii_case("cancelled");
|
||||
}
|
||||
return true;
|
||||
}
|
||||
std::env::var("MARQDO_CANCEL")
|
||||
.map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
|
||||
.unwrap_or(false)
|
||||
}
|
||||
@@ -0,0 +1,147 @@
|
||||
//! ModelSelectionV1 — request-level model identity (M01).
|
||||
|
||||
use serde_json::{json, Map, Value};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ModelSelection {
|
||||
pub schema_version: u64,
|
||||
pub selection_id: String,
|
||||
pub provider_id: String,
|
||||
pub model_id: String,
|
||||
pub provider_revision: Option<u64>,
|
||||
pub model_revision: Option<u64>,
|
||||
pub adapter: String,
|
||||
pub endpoint_ref: Option<String>,
|
||||
pub credential_ref: Option<String>,
|
||||
pub credential_version: Option<u64>,
|
||||
pub upstream_model_id: String,
|
||||
pub parameters: Map<String, Value>,
|
||||
pub fallback_policy: String,
|
||||
pub auth_mode: String,
|
||||
/// Resolved call-local endpoint (never serialize API keys into events).
|
||||
pub base_url: Option<String>,
|
||||
/// Call-local credential material — must not appear in public snapshots.
|
||||
pub api_key: Option<String>,
|
||||
}
|
||||
|
||||
impl ModelSelection {
|
||||
pub fn public_snapshot(&self) -> Value {
|
||||
json!({
|
||||
"schema": "ModelSelectionV1",
|
||||
"schema_version": self.schema_version,
|
||||
"selection_id": self.selection_id,
|
||||
"provider_id": self.provider_id,
|
||||
"model_id": self.model_id,
|
||||
"provider_revision": self.provider_revision,
|
||||
"model_revision": self.model_revision,
|
||||
"adapter": self.adapter,
|
||||
"endpoint_ref": self.endpoint_ref,
|
||||
"credential_ref": self.credential_ref,
|
||||
"credential_version": self.credential_version,
|
||||
"upstream_model_id": self.upstream_model_id,
|
||||
"parameters": self.parameters,
|
||||
"fallback_policy": self.fallback_policy,
|
||||
"auth_mode": self.auth_mode,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse selection. In `strict` mode, missing required fields error (no env fallback).
|
||||
pub fn parse_model_selection(v: &Value, strict: bool) -> Result<ModelSelection, String> {
|
||||
let schema_version = v
|
||||
.get("schema_version")
|
||||
.and_then(|x| x.as_u64())
|
||||
.unwrap_or(1);
|
||||
if schema_version != 1 {
|
||||
return Err(format!("unsupported ModelSelection schema_version={schema_version}"));
|
||||
}
|
||||
let require = |key: &str| -> Result<String, String> {
|
||||
match v.get(key).and_then(|x| x.as_str()).filter(|s| !s.is_empty()) {
|
||||
Some(s) => Ok(s.to_string()),
|
||||
None if strict => Err(format!("llm.selection_missing:{key}")),
|
||||
None => Ok(String::new()),
|
||||
}
|
||||
};
|
||||
let selection_id = require("selection_id")?;
|
||||
let provider_id = require("provider_id")?;
|
||||
let model_id = require("model_id")?;
|
||||
let adapter = v
|
||||
.get("adapter")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("openai-compatible")
|
||||
.to_string();
|
||||
let upstream = v
|
||||
.get("upstream_model_id")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string())
|
||||
.or_else(|| {
|
||||
if model_id.is_empty() {
|
||||
None
|
||||
} else {
|
||||
Some(model_id.clone())
|
||||
}
|
||||
});
|
||||
let upstream_model_id = match upstream {
|
||||
Some(u) => u,
|
||||
None if strict => return Err("llm.selection_missing:upstream_model_id".into()),
|
||||
None => String::new(),
|
||||
};
|
||||
let auth_mode = v
|
||||
.get("auth_mode")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("api_key")
|
||||
.to_string();
|
||||
let fallback_policy = v
|
||||
.get("fallback_policy")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("disabled")
|
||||
.to_string();
|
||||
let parameters = v
|
||||
.get("parameters")
|
||||
.and_then(|x| x.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let base_url = v
|
||||
.get("base_url")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.map(|s| s.to_string());
|
||||
let api_key = v
|
||||
.get("api_key")
|
||||
.and_then(|x| x.as_str())
|
||||
.map(|s| s.to_string());
|
||||
if strict && auth_mode != "none" && api_key.as_ref().map(|s| s.is_empty()).unwrap_or(true) {
|
||||
// credential_ref may be resolved by host; allow missing api_key if credential_ref present
|
||||
if v.get("credential_ref").and_then(|x| x.as_str()).is_none() && base_url.is_some() {
|
||||
return Err("llm.selection_missing:api_key_or_credential_ref".into());
|
||||
}
|
||||
}
|
||||
if strict && selection_id.is_empty() {
|
||||
return Err("llm.selection_missing:selection_id".into());
|
||||
}
|
||||
Ok(ModelSelection {
|
||||
schema_version,
|
||||
selection_id,
|
||||
provider_id,
|
||||
model_id,
|
||||
provider_revision: v.get("provider_revision").and_then(|x| x.as_u64()),
|
||||
model_revision: v.get("model_revision").and_then(|x| x.as_u64()),
|
||||
adapter,
|
||||
endpoint_ref: v
|
||||
.get("endpoint_ref")
|
||||
.and_then(|x| x.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
credential_ref: v
|
||||
.get("credential_ref")
|
||||
.and_then(|x| x.as_str())
|
||||
.map(|s| s.to_string()),
|
||||
credential_version: v.get("credential_version").and_then(|x| x.as_u64()),
|
||||
upstream_model_id,
|
||||
parameters,
|
||||
fallback_policy,
|
||||
auth_mode,
|
||||
base_url,
|
||||
api_key,
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,90 @@
|
||||
//! Snapshot manifest for apps to retain historical evidence (M04).
|
||||
//! Framework does not store history; missing snapshot → version_unavailable.
|
||||
|
||||
use serde_json::{json, Value};
|
||||
use sha2::{Digest, Sha256};
|
||||
use std::path::Path;
|
||||
|
||||
/// Build a retainable snapshot manifest for the current projection.
|
||||
pub fn build_snapshot_manifest(
|
||||
project_root: &Path,
|
||||
document_rel: &str,
|
||||
source_bytes: &[u8],
|
||||
project: &crate::sema::SemanticProject,
|
||||
renderer_version: &str,
|
||||
) -> Value {
|
||||
let source_revision = format!("sha256:{:x}", Sha256::digest(source_bytes));
|
||||
let mut dep_revs = Vec::new();
|
||||
for a in &project.artifacts {
|
||||
if a.source.file == document_rel {
|
||||
continue;
|
||||
}
|
||||
dep_revs.push(json!({
|
||||
"document_id": a.source.file,
|
||||
"artifact_id": a.artifact_id.0,
|
||||
"artifact_hash": a.hashes.artifact.0,
|
||||
}));
|
||||
}
|
||||
let mut artifact_hashes = Vec::new();
|
||||
for a in &project.artifacts {
|
||||
if a.source.file == document_rel {
|
||||
artifact_hashes.push(json!({
|
||||
"artifact_id": a.artifact_id.0,
|
||||
"hash": a.hashes.artifact.0,
|
||||
}));
|
||||
}
|
||||
}
|
||||
let mut gh = Sha256::new();
|
||||
gh.update(project.project_id.as_bytes());
|
||||
for a in &project.artifacts {
|
||||
gh.update(a.hashes.artifact.0.as_bytes());
|
||||
}
|
||||
let generation_id = format!("{:x}", gh.finalize())[..16].to_string();
|
||||
|
||||
json!({
|
||||
"schema": "SnapshotManifestV1",
|
||||
"schema_version": 1,
|
||||
"project_id": project_root.display().to_string(),
|
||||
"document_id": document_rel,
|
||||
"source_revision": source_revision,
|
||||
"generation_id": generation_id,
|
||||
"dependency_revisions": dep_revs,
|
||||
"artifact_hashes": artifact_hashes,
|
||||
"renderer_version": renderer_version,
|
||||
"contract_schema": "DocumentViewV1",
|
||||
"retention": {
|
||||
"owner": "application",
|
||||
"note": "framework does not retain historical bodies; missing snapshot → version_unavailable"
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/// When an expected revision/generation is requested but no app-provided snapshot
|
||||
/// resolver is present, return the honest unavailable contract.
|
||||
pub fn version_unavailable_result(
|
||||
locator: &Value,
|
||||
reason: &str,
|
||||
expected: &str,
|
||||
actual: Option<&str>,
|
||||
) -> Value {
|
||||
json!({
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "version_unavailable",
|
||||
"precision": "none",
|
||||
"locator": locator,
|
||||
"target": Value::Null,
|
||||
"candidates": [],
|
||||
"diagnostics": [{
|
||||
"code": "snapshot_not_retained",
|
||||
"message": reason,
|
||||
"expected": expected,
|
||||
"actual": actual,
|
||||
}],
|
||||
"label": "引用版本不可用",
|
||||
"snapshot": {
|
||||
"available": false,
|
||||
"owner": "application"
|
||||
}
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,174 @@
|
||||
//! ModelCallUsageV1 — null ≠ 0; measurement_source honesty (M02 / F04).
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
/// Prefer null over zero when the provider omitted a field.
|
||||
pub fn token_or_null(v: Option<i64>) -> Value {
|
||||
match v {
|
||||
Some(n) if n >= 0 => json!(n),
|
||||
_ => Value::Null,
|
||||
}
|
||||
}
|
||||
|
||||
/// Build ModelCallUsageV1 from an OpenAI-shaped `usage` object (or Null).
|
||||
pub fn model_call_usage_from_provider(
|
||||
call_id: &str,
|
||||
attempt_id: &str,
|
||||
run_id: &str,
|
||||
selection: &Value,
|
||||
provider_usage: &Value,
|
||||
status: &str,
|
||||
) -> Value {
|
||||
model_call_usage_from_provider_rev(call_id, attempt_id, run_id, selection, provider_usage, status, 1)
|
||||
}
|
||||
|
||||
/// Same as [`model_call_usage_from_provider`] with an explicit revision (F05).
|
||||
pub fn model_call_usage_from_provider_rev(
|
||||
call_id: &str,
|
||||
attempt_id: &str,
|
||||
run_id: &str,
|
||||
selection: &Value,
|
||||
provider_usage: &Value,
|
||||
status: &str,
|
||||
revision: u64,
|
||||
) -> Value {
|
||||
let has_usage = provider_usage.is_object();
|
||||
let input = provider_usage
|
||||
.get("prompt_tokens")
|
||||
.or_else(|| provider_usage.get("input_tokens"))
|
||||
.and_then(|v| v.as_i64());
|
||||
let output = provider_usage
|
||||
.get("completion_tokens")
|
||||
.or_else(|| provider_usage.get("output_tokens"))
|
||||
.and_then(|v| v.as_i64());
|
||||
let total = provider_usage
|
||||
.get("total_tokens")
|
||||
.and_then(|v| v.as_i64())
|
||||
.or_else(|| match (input, output) {
|
||||
(Some(a), Some(b)) => Some(a + b),
|
||||
_ => None,
|
||||
});
|
||||
let cached = provider_usage
|
||||
.get("cached_input_tokens")
|
||||
.or_else(|| {
|
||||
provider_usage
|
||||
.get("prompt_tokens_details")
|
||||
.and_then(|d| d.get("cached_tokens"))
|
||||
})
|
||||
.and_then(|v| v.as_i64());
|
||||
let reasoning = provider_usage
|
||||
.get("reasoning_output_tokens")
|
||||
.or_else(|| {
|
||||
provider_usage
|
||||
.get("completion_tokens_details")
|
||||
.and_then(|d| d.get("reasoning_tokens"))
|
||||
})
|
||||
.and_then(|v| v.as_i64());
|
||||
|
||||
let (usage_state, measurement_source) = if !has_usage {
|
||||
("unknown", "none")
|
||||
} else if input.is_none() && output.is_none() && total.is_none() {
|
||||
("unknown", "none")
|
||||
} else {
|
||||
("final", "provider")
|
||||
};
|
||||
|
||||
let mut diagnostics = Vec::new();
|
||||
if let (Some(t), Some(i), Some(o)) = (total, input, output) {
|
||||
if t != i + o && cached.is_none() {
|
||||
diagnostics.push(json!({
|
||||
"code": "usage.inconsistent",
|
||||
"message": format!("total_tokens={t} != input+output={}", i + o)
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
json!({
|
||||
"schema": "ModelCallUsageV1",
|
||||
"schema_version": 1,
|
||||
"call_id": call_id,
|
||||
"attempt_id": attempt_id,
|
||||
"parent_call_id": Value::Null,
|
||||
"run_id": run_id,
|
||||
"turn_id": selection.get("turn_id").cloned().unwrap_or(Value::Null),
|
||||
"workspace_scope": selection.get("workspace_scope").cloned().unwrap_or(Value::Null),
|
||||
"purpose": selection.get("purpose").cloned().unwrap_or(json!("answer")),
|
||||
"selection_id": selection.get("selection_id").cloned().unwrap_or(Value::Null),
|
||||
"provider_id": selection.get("provider_id").cloned().unwrap_or(Value::Null),
|
||||
"model_id": selection.get("model_id").cloned().unwrap_or(Value::Null),
|
||||
"requested_model": selection.get("upstream_model_id").cloned()
|
||||
.or_else(|| selection.get("model").cloned())
|
||||
.unwrap_or(Value::Null),
|
||||
"resolved_model": selection.get("resolved_model").cloned()
|
||||
.or_else(|| selection.get("upstream_model_id").cloned())
|
||||
.unwrap_or(Value::Null),
|
||||
"status": status,
|
||||
"usage_state": usage_state,
|
||||
"measurement_source": measurement_source,
|
||||
"input_tokens": token_or_null(input),
|
||||
"output_tokens": token_or_null(output),
|
||||
"total_tokens": token_or_null(total),
|
||||
"cached_input_tokens": token_or_null(cached),
|
||||
"reasoning_output_tokens": token_or_null(reasoning),
|
||||
"revision": revision.max(1),
|
||||
"provider_request_id": provider_usage.get("provider_request_id").cloned().unwrap_or(Value::Null),
|
||||
"diagnostics": diagnostics,
|
||||
// Legacy fields kept but marked — apps must not treat token_cost as money.
|
||||
"legacy": {
|
||||
"tokens": token_or_null(total),
|
||||
"token_cost": token_or_null(total),
|
||||
"deprecated": true,
|
||||
"unit": "tokens"
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/// Replace prior usage for the same (call_id, attempt_id) when revision is newer (F05).
|
||||
/// Returns the winning snapshot; does not sum cumulative stream counters.
|
||||
pub fn replace_usage_if_newer(prior: &Value, next: &Value) -> Value {
|
||||
let same_call = prior.get("call_id") == next.get("call_id")
|
||||
&& prior.get("attempt_id") == next.get("attempt_id");
|
||||
if !same_call {
|
||||
return next.clone();
|
||||
}
|
||||
let pr = prior.get("revision").and_then(|v| v.as_u64()).unwrap_or(0);
|
||||
let nr = next.get("revision").and_then(|v| v.as_u64()).unwrap_or(0);
|
||||
if nr >= pr {
|
||||
next.clone()
|
||||
} else {
|
||||
prior.clone()
|
||||
}
|
||||
}
|
||||
|
||||
/// RuntimeEventV1 envelope helper.
|
||||
pub fn runtime_event(
|
||||
event_id: &str,
|
||||
seq: u64,
|
||||
run_id: &str,
|
||||
event_type: &str,
|
||||
payload: Value,
|
||||
) -> Value {
|
||||
json!({
|
||||
"schema": "RuntimeEventV1",
|
||||
"schema_version": 1,
|
||||
"event_id": event_id,
|
||||
"seq": seq,
|
||||
"run_id": run_id,
|
||||
"parent_run_id": Value::Null,
|
||||
"turn_id": Value::Null,
|
||||
"workspace_scope": Value::Null,
|
||||
"timestamp": chrono_like_now(),
|
||||
"type": event_type,
|
||||
"payload": payload
|
||||
})
|
||||
}
|
||||
|
||||
fn chrono_like_now() -> String {
|
||||
// Avoid new chrono dep: RFC3339-ish from system time.
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
let secs = SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.map(|d| d.as_secs())
|
||||
.unwrap_or(0);
|
||||
format!("{secs}")
|
||||
}
|
||||
@@ -5,6 +5,64 @@
|
||||
|
||||
use std::process::Command;
|
||||
|
||||
/// Build `libagent` once per test process and prefer it over a stale `~/.marqdo/ext`.
|
||||
/// Same contract as `tests/gold.rs::ensure_agent_plugin_built` — EK gate must not
|
||||
/// depend on a manually copied `ext/native/libagent.so`.
|
||||
fn ensure_agent_plugin_built() {
|
||||
use std::sync::Once;
|
||||
static ONCE: Once = Once::new();
|
||||
ONCE.call_once(|| {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let status = Command::new("cargo")
|
||||
.args(["build", "-p", "marqdo_plugin_agent"])
|
||||
.current_dir(&root)
|
||||
.status()
|
||||
.expect("build marqdo_plugin_agent");
|
||||
assert!(status.success(), "failed to build marqdo_plugin_agent");
|
||||
let lib = if cfg!(windows) {
|
||||
root.join("target").join("debug").join("agent.dll")
|
||||
} else if cfg!(target_os = "macos") {
|
||||
root.join("target").join("debug").join("libagent.dylib")
|
||||
} else {
|
||||
root.join("target").join("debug").join("libagent.so")
|
||||
};
|
||||
let release = if cfg!(windows) {
|
||||
root.join("target").join("release").join("agent.dll")
|
||||
} else if cfg!(target_os = "macos") {
|
||||
root.join("target").join("release").join("libagent.dylib")
|
||||
} else {
|
||||
root.join("target").join("release").join("libagent.so")
|
||||
};
|
||||
let chosen = if lib.is_file() {
|
||||
if release.is_file() {
|
||||
let lib_m = std::fs::metadata(&lib).and_then(|m| m.modified()).ok();
|
||||
let rel_m = std::fs::metadata(&release).and_then(|m| m.modified()).ok();
|
||||
match (lib_m, rel_m) {
|
||||
(Some(l), Some(r)) if r > l => release,
|
||||
_ => lib,
|
||||
}
|
||||
} else {
|
||||
lib
|
||||
}
|
||||
} else {
|
||||
release
|
||||
};
|
||||
assert!(
|
||||
chosen.is_file(),
|
||||
"missing agent plugin at {}",
|
||||
chosen.display()
|
||||
);
|
||||
// SAFETY: single-threaded Once; children inherit for the rest of the test process.
|
||||
std::env::set_var("MARQDO_AGENT_PLUGIN", &chosen);
|
||||
if std::env::var_os("MARQDO_EXT").is_none() {
|
||||
let ext = root.join("ext");
|
||||
if ext.join("ai").join("agent.mq.md").is_file() {
|
||||
std::env::set_var("MARQDO_EXT", &ext);
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
fn run_backend(path: &str, backend: &str) -> (i32, String, String) {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let out = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
@@ -302,9 +360,74 @@ fn s1_view_lists_steps_with_source_anchors() {
|
||||
|| html.contains("data-step-kind=\"iterate\""),
|
||||
"expected classified step kinds in view HTML"
|
||||
);
|
||||
// V0: document body must appear before the knowledge auxiliary panel in main content
|
||||
// (ignore stylesheet class mentions that appear earlier in <style>).
|
||||
let main = html.split("<main").nth(1).unwrap_or(&html);
|
||||
let struct_pos = main
|
||||
.find("id=\"structure\"")
|
||||
.or_else(|| main.find("structure-block"))
|
||||
.expect("structure in main");
|
||||
let know_pos = main
|
||||
.find("block knowledge-block")
|
||||
.or_else(|| main.find("knowledge-block\">"))
|
||||
.unwrap_or(main.len());
|
||||
assert!(
|
||||
struct_pos < know_pos,
|
||||
"V0: document Structure must precede knowledge panel in <main>"
|
||||
);
|
||||
assert!(
|
||||
!html.contains("Lock digest"),
|
||||
"V0: must not mislabel artifact hash as Lock digest"
|
||||
);
|
||||
let _ = std::fs::remove_dir_all(&out_dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn v0_no_exec_does_not_run_side_effects() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-noexec-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
let marker = dir.join("SIDE_EFFECT.txt");
|
||||
let src = format!(
|
||||
"---\nmarkup: occlusion\n---\n\n# main\n\n> fs.write_text path=\"{}\" text=ran\n> print text=ok\n",
|
||||
marker.display().to_string().replace('\\', "/")
|
||||
);
|
||||
std::fs::write(dir.join("main.mq.md"), src).unwrap();
|
||||
let out_dir = dir.join("out");
|
||||
let status = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"view",
|
||||
"output",
|
||||
"--out",
|
||||
out_dir.to_str().unwrap(),
|
||||
"--no-exec",
|
||||
dir.join("main.mq.md").to_str().unwrap(),
|
||||
])
|
||||
.current_dir(&root)
|
||||
.output()
|
||||
.expect("view no-exec");
|
||||
assert_eq!(
|
||||
status.status.code(),
|
||||
Some(0),
|
||||
"stderr={}",
|
||||
String::from_utf8_lossy(&status.stderr)
|
||||
);
|
||||
assert!(
|
||||
!marker.exists(),
|
||||
"V0: --no-exec must not execute side effects (found {})",
|
||||
marker.display()
|
||||
);
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn s1_g03_step_kinds_not_all_call() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
@@ -542,17 +665,29 @@ fn s5_closure_digest_moves_with_dependency() {
|
||||
"stderr={}",
|
||||
String::from_utf8_lossy(&status.stderr)
|
||||
);
|
||||
// Select the caller by dependency edge (not display_name alone — module also named "main").
|
||||
let mut main_closure = None;
|
||||
let mut main_impl = None;
|
||||
let mut main_id = None;
|
||||
for ent in std::fs::read_dir(out1.join("artifacts")).unwrap().flatten() {
|
||||
let v: serde_json::Value =
|
||||
serde_json::from_str(&std::fs::read_to_string(ent.path()).unwrap()).unwrap();
|
||||
if v["display_name"] == "main" {
|
||||
let deps = v["dependencies"].as_array().cloned().unwrap_or_default();
|
||||
let calls_rate = deps.iter().any(|d| {
|
||||
d.as_str()
|
||||
.is_some_and(|s| s.contains("/function/rate") || s.ends_with("rate"))
|
||||
});
|
||||
if v["display_name"] == "main" && v["kind"] != "module" && calls_rate {
|
||||
main_closure = v["hashes"]["closure"].as_str().map(str::to_string);
|
||||
main_impl = v["hashes"]["implementation"].as_str().map(str::to_string);
|
||||
main_id = v["artifact_id"].as_str().map(str::to_string);
|
||||
}
|
||||
}
|
||||
assert!(main_closure.is_some(), "main closure missing in {}", out1.display());
|
||||
assert!(
|
||||
main_closure.is_some(),
|
||||
"caller (type/function main with rate dep) closure missing in {}",
|
||||
out1.display()
|
||||
);
|
||||
std::fs::write(
|
||||
dir.join("dep.mq.md"),
|
||||
"---\nmarkup: occlusion\n---\n\n## rate\n\n*0.14*\n",
|
||||
@@ -571,10 +706,11 @@ fn s5_closure_digest_moves_with_dependency() {
|
||||
);
|
||||
let mut main_closure2 = None;
|
||||
let mut main_impl2 = None;
|
||||
let want_id = main_id.as_deref().unwrap();
|
||||
for ent in std::fs::read_dir(out2.join("artifacts")).unwrap().flatten() {
|
||||
let v: serde_json::Value =
|
||||
serde_json::from_str(&std::fs::read_to_string(ent.path()).unwrap()).unwrap();
|
||||
if v["display_name"] == "main" {
|
||||
if v["artifact_id"].as_str() == Some(want_id) {
|
||||
main_closure2 = v["hashes"]["closure"].as_str().map(str::to_string);
|
||||
main_impl2 = v["hashes"]["implementation"].as_str().map(str::to_string);
|
||||
}
|
||||
@@ -1071,3 +1207,756 @@ fn s2_g07_eng_reuse_requires_bind_before_execute() {
|
||||
"REUSE must expose bind_targets for MLSP bind: {v}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m02_source_change_invalidates_business_handle() {
|
||||
// M02: missing anchor blocks business bind; valid source then edit/delete rejects execute.
|
||||
use marqdo::mlsp::handle_line;
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-m02-src-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
std::fs::write(dir.join("source.md"), "# rate\n\nrate = 0.13\n").unwrap();
|
||||
std::fs::write(
|
||||
dir.join("facts.mq.md"),
|
||||
"---\nmarkup: occlusion\nsources:\n - source.md#missing-anchor\napplicability:\n region: CN\n valid_until: 2099-12-31\n---\n\n## rate\n\n*0.13*\n",
|
||||
)
|
||||
.unwrap();
|
||||
let found: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.find","params":{"project":&dir,"query":"rate","kind":"function"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let id = found["result"]["candidates"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.find(|c| c["kind"] == "function")
|
||||
.unwrap()["artifact_id"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.to_string();
|
||||
let inspect: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.inspect","params":{"project":&dir,"artifact_id":&id}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
inspect["result"]["verification"]["evidence"], "anchor_missing",
|
||||
"missing anchor must not be sourced: {inspect}"
|
||||
);
|
||||
let denied: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.bind","params":{"project":&dir,"artifact_id":&id,"policy":"business"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(denied["ok"], false, "business bind must reject anchor_missing: {denied}");
|
||||
|
||||
// Repair anchor and bind.
|
||||
std::fs::write(
|
||||
dir.join("facts.mq.md"),
|
||||
"---\nmarkup: occlusion\nsources:\n - source.md#rate\napplicability:\n region: CN\n valid_until: 2099-12-31\n---\n\n## rate\n\n*0.13*\n",
|
||||
)
|
||||
.unwrap();
|
||||
let inspect2: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.inspect","params":{"project":&dir,"artifact_id":&id}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
inspect2["result"]["verification"]["evidence"], "sourced",
|
||||
"{inspect2}"
|
||||
);
|
||||
let evidence1 = inspect2["result"]["hashes"]["evidence"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.to_string();
|
||||
let bound: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.bind","params":{"project":&dir,"artifact_id":&id,"policy":"business"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(bound["ok"], true, "business bind with valid anchor: {bound}");
|
||||
let handle = bound["result"]["handle"].clone();
|
||||
assert!(handle["evidence_digest"].as_str().is_some());
|
||||
assert!(handle["closure_digest"].as_str().is_some());
|
||||
|
||||
// Edit source content → evidence digest moves → stale handle.
|
||||
std::fs::write(dir.join("source.md"), "# rate\n\nrate = 0.14\n").unwrap();
|
||||
let inspect3: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.inspect","params":{"project":&dir,"artifact_id":&id}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let evidence2 = inspect3["result"]["hashes"]["evidence"].as_str().unwrap();
|
||||
assert_ne!(
|
||||
evidence1, evidence2,
|
||||
"source content change must move evidence digest"
|
||||
);
|
||||
let after_edit: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.execute","params":{"handle":&handle,"inputs":{}}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
after_edit["ok"], false,
|
||||
"old business handle must fail after source edit: {after_edit}"
|
||||
);
|
||||
|
||||
// Remove source → evidence denied / stale.
|
||||
let _ = std::fs::remove_file(dir.join("source.md"));
|
||||
let after_rm: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.execute","params":{"handle":&handle,"inputs":{}}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
after_rm["ok"], false,
|
||||
"old business handle must fail after source removal: {after_rm}"
|
||||
);
|
||||
|
||||
// Unknown policy rejected.
|
||||
let bad_pol: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.bind","params":{"project":&dir,"artifact_id":&id,"policy":"trust-me"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(bad_pol["ok"], false, "unknown policy must be rejected: {bad_pol}");
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m01_document_extract_markdown() {
|
||||
use marqdo::mlsp::handle_line;
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/12-tax-source/corpus.md");
|
||||
let out: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"document.extract","params":{"path":root}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(out["ok"], true, "{out}");
|
||||
assert_eq!(out["result"]["status"], "ok");
|
||||
assert!(
|
||||
out["result"]["segments"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.any(|s| s["kind"] == "heading"),
|
||||
"expected heading segments: {out}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m06_publish_manifest_written() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let out = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-manifest-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&out);
|
||||
let status = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"knowledge",
|
||||
"tests/executable_knowledge/baseline/02-extract",
|
||||
"-o",
|
||||
out.to_str().unwrap(),
|
||||
])
|
||||
.current_dir(&root)
|
||||
.output()
|
||||
.unwrap();
|
||||
assert_eq!(status.status.code(), Some(0));
|
||||
let manifest: serde_json::Value = serde_json::from_str(
|
||||
&std::fs::read_to_string(out.join("publish_manifest.json")).unwrap(),
|
||||
)
|
||||
.unwrap();
|
||||
assert_eq!(manifest["kind"], "publish_manifest");
|
||||
assert!(manifest["semantic_generation"].as_str().is_some());
|
||||
assert!(
|
||||
manifest["excluded_dirs"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.any(|d| d == "data"),
|
||||
"excluded_dirs must include data: {manifest}"
|
||||
);
|
||||
let _ = std::fs::remove_dir_all(&out);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m05_skill_front_has_occlusion_core_not_classic_index() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let skill = std::fs::read_to_string(root.join("skills/marqdo/SKILL.md")).unwrap();
|
||||
// Skip YAML frontmatter; skill_brief budgets apply to body text.
|
||||
let body = skill
|
||||
.split_once("\n---\n")
|
||||
.map(|(_, rest)| rest)
|
||||
.unwrap_or(skill.as_str());
|
||||
let head: String = body.chars().take(1200).collect();
|
||||
assert!(
|
||||
head.contains("CORE SYNTAX") && head.contains("access(coll, key)"),
|
||||
"first 1200 body chars must include Occlusion core: {}",
|
||||
&head[..head.len().min(200)]
|
||||
);
|
||||
assert!(
|
||||
!head.contains("get with `[key](coll)`")
|
||||
&& !head.contains("Bold `**…**` is **return value only**"),
|
||||
"first 1200 body chars must not teach Classic index / bold-as-print: {head}"
|
||||
);
|
||||
assert!(
|
||||
root.join("skills/marqdo/migration-classic.md").is_file(),
|
||||
"Classic rules must live in migration-classic.md"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m02_impact_includes_provenance_corpus_uri() {
|
||||
use marqdo::mlsp::handle_line;
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/12-tax-source");
|
||||
let impact: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.impact","params":{"project":&root,"path":"corpus.md"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(impact["ok"], true, "{impact}");
|
||||
let affected = impact["result"]["affected"].as_array().unwrap();
|
||||
assert!(
|
||||
!affected.is_empty(),
|
||||
"corpus.md provenance must seed impact: {impact}"
|
||||
);
|
||||
assert!(
|
||||
affected.iter().any(|a| a["kind"] == "function"),
|
||||
"impact should reach citing functions: {impact}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m03_verify_unknown_policy_and_may_publish_gate() {
|
||||
use marqdo::mlsp::handle_line;
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let found: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.find","params":{"project":&root,"query":"商品小计","kind":"function"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let id = found["result"]["candidates"][0]["artifact_id"].as_str().unwrap();
|
||||
let bad: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.verify","params":{"project":&root,"artifact_id":id,"policy":"trust-me"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(bad["ok"], true, "{bad}");
|
||||
assert_eq!(bad["result"]["may_bind"], false, "unknown policy must deny bind: {bad}");
|
||||
assert_eq!(bad["result"]["may_publish"], false);
|
||||
let okv: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.verify","params":{"project":&root,"artifact_id":id,"policy":"pure"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(okv["result"]["may_bind"], true, "{okv}");
|
||||
assert_eq!(
|
||||
okv["result"]["may_publish"], false,
|
||||
"static verify must not allow publish without tests/execution: {okv}"
|
||||
);
|
||||
assert_eq!(okv["result"]["checks"]["tests"]["status"], "unknown");
|
||||
assert_eq!(okv["result"]["checks"]["input_domain"]["status"], "unknown");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m04_reuse_execute_is_actual_reuse_not_discovery() {
|
||||
use marqdo::mlsp::handle_line;
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let found: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.find","params":{"project":&root,"query":"商品小计","kind":"function"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let id = found["result"]["candidates"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.find(|c| c["kind"] == "function")
|
||||
.unwrap()["artifact_id"]
|
||||
.as_str()
|
||||
.unwrap();
|
||||
let out: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({
|
||||
"method":"artifact.reuse_execute",
|
||||
"params":{"project":&root,"artifact_id":id,"policy":"pure","inputs":{"数量":2,"单价":30}}
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(out["ok"], true, "{out}");
|
||||
assert_eq!(out["result"]["actual_reuse"], true);
|
||||
assert_eq!(out["result"]["discovery_only"], false);
|
||||
assert_eq!(out["result"]["result"], 60);
|
||||
assert!(out["result"]["trace"]["digest"].as_str().is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m07_function_sources_override_module_sources() {
|
||||
use marqdo::mlsp::handle_line;
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-fnsrc-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
std::fs::write(dir.join("a.md"), "# alpha\n\nA\n").unwrap();
|
||||
std::fs::write(dir.join("b.md"), "# beta\n\nB\n").unwrap();
|
||||
std::fs::write(
|
||||
dir.join("facts.mq.md"),
|
||||
"---\nmarkup: occlusion\nsources:\n - a.md#alpha\nfunction_sources:\n rate:\n - b.md#beta\napplicability:\n valid_until: 2099-12-31\n---\n\n## rate\n\n*0.13*\n\n## other\n\n*1*\n",
|
||||
)
|
||||
.unwrap();
|
||||
let found: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.find","params":{"project":&dir,"query":"rate","kind":"function"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let id = found["result"]["candidates"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.find(|c| c["kind"] == "function" && c["display_name"] == "rate")
|
||||
.unwrap()["artifact_id"]
|
||||
.as_str()
|
||||
.unwrap();
|
||||
let rate: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.inspect","params":{"project":&dir,"artifact_id":id}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(rate["ok"], true, "{rate}");
|
||||
let prov = rate["result"]["provenance"].as_array().unwrap();
|
||||
assert!(
|
||||
prov.iter()
|
||||
.any(|p| p["relation"] == "supports" && p["uri"] == "b.md"),
|
||||
"rate must use function_sources b.md: {rate}"
|
||||
);
|
||||
assert!(
|
||||
!prov
|
||||
.iter()
|
||||
.any(|p| p["relation"] == "supports" && p["uri"] == "a.md"),
|
||||
"rate must not inherit module a.md when overridden: {rate}"
|
||||
);
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m08_story_build_reuse_invalidate_repair() {
|
||||
// Full story: bind → execute → source edit invalidates → rebind succeeds.
|
||||
use marqdo::mlsp::handle_line;
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-story-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
std::fs::write(dir.join("source.md"), "# rate\n\nv=0.13\n").unwrap();
|
||||
std::fs::write(
|
||||
dir.join("facts.mq.md"),
|
||||
"---\nmarkup: occlusion\nsources:\n - source.md#rate\napplicability:\n region: CN\n valid_until: 2099-12-31\n---\n\n## rate\n\n*0.13*\n",
|
||||
)
|
||||
.unwrap();
|
||||
let found: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.find","params":{"project":&dir,"query":"rate","kind":"function"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let id = found["result"]["candidates"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.find(|c| c["kind"] == "function")
|
||||
.unwrap()["artifact_id"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.to_string();
|
||||
let first: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({
|
||||
"method":"artifact.reuse_execute",
|
||||
"params":{"project":&dir,"artifact_id":&id,"policy":"business","inputs":{}}
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(first["ok"], true, "first reuse: {first}");
|
||||
assert_eq!(first["result"]["result"], 0.13);
|
||||
let handle = {
|
||||
let bound: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.bind","params":{"project":&dir,"artifact_id":&id,"policy":"business"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
bound["result"]["handle"].clone()
|
||||
};
|
||||
std::fs::write(dir.join("source.md"), "# rate\n\nv=0.14\n").unwrap();
|
||||
let stale: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.execute","params":{"handle":handle,"inputs":{}}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(stale["ok"], false, "stale after source edit: {stale}");
|
||||
let repaired: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({
|
||||
"method":"artifact.reuse_execute",
|
||||
"params":{"project":&dir,"artifact_id":&id,"policy":"business","inputs":{}}
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(repaired["ok"], true, "rebind after repair: {repaired}");
|
||||
assert_eq!(repaired["result"]["result"], 0.13);
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m05_skill_core_card_has_access_not_classic_index() {
|
||||
// skill_core_card text is embedded in ext/ai; SKILL body already gated by m05_*.
|
||||
// Also assert migration card and CORE SYNTAX marker remain the release contract.
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let agent = std::fs::read_to_string(root.join("ext/ai/agent.mq.md")).unwrap();
|
||||
assert!(
|
||||
agent.contains("## skill_core_card") && agent.contains("access(coll, key)"),
|
||||
"skill_core_card must teach access()"
|
||||
);
|
||||
assert!(
|
||||
!agent.contains("never **bold** to print") || agent.contains("never use bold markers"),
|
||||
"core card must not rely on conflicting bold-as-print Classic wording"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn v1_view_exports_knowledge_presentation_and_explain_links() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let out_dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-v1-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&out_dir);
|
||||
let status = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"view",
|
||||
"output",
|
||||
"--out",
|
||||
out_dir.to_str().unwrap(),
|
||||
"--no-exec",
|
||||
"tests/executable_knowledge/baseline/02-extract/main.mq.md",
|
||||
])
|
||||
.current_dir(&root)
|
||||
.output()
|
||||
.unwrap();
|
||||
assert_eq!(status.status.code(), Some(0));
|
||||
let mut html = String::new();
|
||||
fn walk(dir: &std::path::Path, acc: &mut String) {
|
||||
let Ok(rd) = std::fs::read_dir(dir) else {
|
||||
return;
|
||||
};
|
||||
for ent in rd.flatten() {
|
||||
let p = ent.path();
|
||||
if p.is_dir() {
|
||||
walk(&p, acc);
|
||||
} else if p.extension().and_then(|e| e.to_str()) == Some("html") {
|
||||
if let Ok(s) = std::fs::read_to_string(&p) {
|
||||
if s.contains("mq-knowledge-presentation") || s.contains("knowledge-explain") {
|
||||
*acc = s;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
walk(&out_dir, &mut html);
|
||||
assert!(
|
||||
html.contains("mq-knowledge-presentation"),
|
||||
"V1 must embed KnowledgePresentation JSON"
|
||||
);
|
||||
assert!(
|
||||
html.contains("knowledge-explain") || html.contains("id=\"knowledge-"),
|
||||
"V1 must expose explain / knowledge anchors: {}",
|
||||
&html[..html.len().min(400)]
|
||||
);
|
||||
assert!(
|
||||
!html.contains("\"verified_claim\":true"),
|
||||
"must not claim verified without evidence runner"
|
||||
);
|
||||
let _ = std::fs::remove_dir_all(&out_dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn v2_sse_accepts_packet_rejects_stale_token() {
|
||||
assert!(marqdo::view::sse_accepts_packet("abc", None));
|
||||
assert!(marqdo::view::sse_accepts_packet("abc", Some("")));
|
||||
assert!(marqdo::view::sse_accepts_packet("abc", Some("abc")));
|
||||
assert!(!marqdo::view::sse_accepts_packet("abc", Some("zzz")));
|
||||
// Embed clients must use strict: missing/empty/mismatch all reject.
|
||||
assert!(!marqdo::view::sse_accepts_packet_strict("abc", None));
|
||||
assert!(!marqdo::view::sse_accepts_packet_strict("abc", Some("")));
|
||||
assert!(!marqdo::view::sse_accepts_packet_strict("", Some("abc")));
|
||||
assert!(!marqdo::view::sse_accepts_packet_strict("abc", Some("zzz")));
|
||||
assert!(marqdo::view::sse_accepts_packet_strict("abc", Some("abc")));
|
||||
assert_eq!(
|
||||
marqdo::view::page_token_from_source("a.mq.md", "x"),
|
||||
marqdo::view::page_token_from_source("a.mq.md", "x")
|
||||
);
|
||||
assert_ne!(
|
||||
marqdo::view::page_token_from_source("a.mq.md", "x"),
|
||||
marqdo::view::page_token_from_source("a.mq.md", "y")
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn v2_view_embeds_page_token_and_semantic_generation() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let out_dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-v2-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&out_dir);
|
||||
let status = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"view",
|
||||
"output",
|
||||
"--out",
|
||||
out_dir.to_str().unwrap(),
|
||||
"--no-exec",
|
||||
"tests/executable_knowledge/baseline/12-tax-source/main.mq.md",
|
||||
])
|
||||
.current_dir(&root)
|
||||
.output()
|
||||
.unwrap();
|
||||
assert_eq!(status.status.code(), Some(0), "{}", String::from_utf8_lossy(&status.stderr));
|
||||
let mut html = String::new();
|
||||
fn walk(dir: &std::path::Path, acc: &mut String) {
|
||||
let Ok(rd) = std::fs::read_dir(dir) else {
|
||||
return;
|
||||
};
|
||||
for ent in rd.flatten() {
|
||||
let p = ent.path();
|
||||
if p.is_dir() {
|
||||
walk(&p, acc);
|
||||
} else if p.extension().and_then(|e| e.to_str()) == Some("html") {
|
||||
if let Ok(s) = std::fs::read_to_string(&p) {
|
||||
if s.contains("mq-knowledge-presentation") {
|
||||
*acc = s;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
walk(&out_dir, &mut html);
|
||||
assert!(html.contains("MARQDO_VIEW_PAGE_TOKEN"), "page token global");
|
||||
assert!(html.contains("\"semantic_generation\""), "presentation generation");
|
||||
assert!(html.contains("\"page_token\""), "presentation page_token");
|
||||
assert!(html.contains("\"local_deps\""), "local deps edges");
|
||||
assert!(
|
||||
html.contains("已关联来源") || html.contains("尚未核验"),
|
||||
"sourced must not look verified"
|
||||
);
|
||||
assert!(
|
||||
html.contains("stale result ignored") || html.contains("page_token"),
|
||||
"SSE stale reject path present in page script"
|
||||
);
|
||||
let _ = std::fs::remove_dir_all(&out_dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn v3_corpus_1000_compile_smoke() {
|
||||
// Scale gate: 1000 tiny units compile under a fixed wall budget (no per-unit dual-backend).
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-corpus1000-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
for i in 0..1000u32 {
|
||||
let n = i + 1;
|
||||
let src = format!(
|
||||
"---\nmarkup: occlusion\ntitle: unit-{n}\n---\n\n# main\n\n**v = [翻倍]({n} * 2)**\n*v*\n"
|
||||
);
|
||||
std::fs::write(dir.join(format!("u{n:04}.mq.md")), src).unwrap();
|
||||
}
|
||||
let out = dir.join(".marqdo-out");
|
||||
let start = std::time::Instant::now();
|
||||
let status = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args(["knowledge", dir.to_str().unwrap(), "-o", out.to_str().unwrap()])
|
||||
.current_dir(&root)
|
||||
.output()
|
||||
.unwrap();
|
||||
let elapsed = start.elapsed();
|
||||
assert_eq!(
|
||||
status.status.code(),
|
||||
Some(0),
|
||||
"stderr={}",
|
||||
String::from_utf8_lossy(&status.stderr)
|
||||
);
|
||||
assert!(out.join("CURRENT").is_file());
|
||||
assert!(
|
||||
out.join("publish_manifest.json").is_file() || out.join("CURRENT").is_file(),
|
||||
"generation published"
|
||||
);
|
||||
// Soft budget: 1000 units should finish offline compile in under 3 minutes on CI.
|
||||
assert!(
|
||||
elapsed.as_secs() < 180,
|
||||
"1000-unit knowledge compile took {:?}",
|
||||
elapsed
|
||||
);
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn v3_view_css_has_responsive_and_print_and_nojs_structure() {
|
||||
let cssish = std::fs::read_to_string(
|
||||
std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("src/view/html.rs"),
|
||||
)
|
||||
.unwrap();
|
||||
assert!(cssish.contains("@media print"));
|
||||
assert!(cssish.contains("@media (max-width: 640px)") || cssish.contains("max-width: 760px"));
|
||||
assert!(cssish.contains("prefers-color-scheme") || cssish.contains("--muted"));
|
||||
// no-JS: structure/knowledge/source blocks remain in static HTML (not JS-only).
|
||||
assert!(cssish.contains("structure-block"));
|
||||
assert!(cssish.contains("knowledge-block"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m01_extract_pdf_and_ocr_fail_explicitly() {
|
||||
use marqdo::mlsp::handle_line;
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"marqdo-ek-extract-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_nanos()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
let pdf = dir.join("x.pdf");
|
||||
std::fs::write(&pdf, b"%PDF-1.4 fake").unwrap();
|
||||
let png = dir.join("scan.png");
|
||||
std::fs::write(&png, b"\x89PNG").unwrap();
|
||||
for (path, expect_fmt) in [(&pdf, "pdf"), (&png, "png")] {
|
||||
let out: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"document.extract","params":{"path": path}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(out["ok"], true, "{out}");
|
||||
assert_eq!(out["result"]["status"], "failed", "{expect_fmt}: {out}");
|
||||
assert!(
|
||||
out["result"]["missing"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.any(|m| m == "full_document"),
|
||||
"{expect_fmt}: {out}"
|
||||
);
|
||||
}
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn f1_publish_gate_chain_via_verify_may_publish() {
|
||||
// Framework-side gate: static verify never may_publish; reuse_execute is actual reuse.
|
||||
use marqdo::mlsp::handle_line;
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let found: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.find","params":{"project":&root,"query":"商品小计","kind":"function"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
let id = found["result"]["candidates"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.find(|c| c["kind"] == "function")
|
||||
.unwrap()["artifact_id"]
|
||||
.as_str()
|
||||
.unwrap();
|
||||
let reused: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({
|
||||
"method":"artifact.reuse_execute",
|
||||
"params":{"project":&root,"artifact_id":id,"policy":"pure","inputs":{"数量":2,"单价":30}}
|
||||
})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(reused["ok"], true, "{reused}");
|
||||
assert_eq!(reused["result"]["actual_reuse"], true);
|
||||
let verify: serde_json::Value = serde_json::from_str(&handle_line(
|
||||
&serde_json::json!({"method":"artifact.verify","params":{"project":&root,"artifact_id":id,"policy":"pure"}})
|
||||
.to_string(),
|
||||
))
|
||||
.unwrap();
|
||||
assert_eq!(verify["ok"], true, "{verify}");
|
||||
assert_eq!(
|
||||
verify["result"]["may_publish"], false,
|
||||
"must not promote from static verify alone: {verify}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn f1_agent_eng_bind_gate_mq_offline() {
|
||||
ensure_agent_plugin_built();
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let out = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"run",
|
||||
"tests/ext/agent-eng-bind-gate.mq.md",
|
||||
"--backend",
|
||||
"tree",
|
||||
])
|
||||
.current_dir(&root)
|
||||
.env(
|
||||
"MARQDO_AGENT_PLUGIN",
|
||||
std::env::var_os("MARQDO_AGENT_PLUGIN").expect("MARQDO_AGENT_PLUGIN set by ensure"),
|
||||
)
|
||||
.output()
|
||||
.unwrap();
|
||||
let stdout = String::from_utf8_lossy(&out.stdout);
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert_eq!(
|
||||
out.status.code(),
|
||||
Some(0),
|
||||
"stdout={stdout}\nstderr={stderr}"
|
||||
);
|
||||
assert!(stdout.contains("agent-eng-bind-gate-ok"), "{stdout}");
|
||||
assert!(stdout.contains("actual-reuse-ok"), "{stdout}");
|
||||
assert!(stdout.contains("candidate-only-blocks-promote"), "{stdout}");
|
||||
}
|
||||
@@ -52,6 +52,15 @@
|
||||
| S4 书店 | **done** | `13-bookstore` + `examples/executable-knowledge` 发票链 |
|
||||
| S5/G04·G08 | **done** | 整代 `CURRENT`;锁 classes+closure;impact |
|
||||
| S6 CI / 语料 / 冒烟 | **done** | CI;100 单元;CLI smoke;扫描上限 |
|
||||
| F0/M02 证据·闭包·句柄 | **done** | evidence 含来源摘要;锚点诊断;business handle 改/删来源失效;SCC closure;`m02_*` |
|
||||
| F0/M03 验证裁决 | **done(子集)** | `artifact.verify` 结构化 may_bind;policy 枚举;`knowledge adjudicate` |
|
||||
| F0/M05 语法 Skill | **done** | CORE SYNTAX 置顶;`migration-classic.md`;`skill_core_card` |
|
||||
| View V0–V1 | **done** | 正文优先;no-exec 不执行;制品摘要;`KnowledgePresentation`;frontmatter title;说明锚点 |
|
||||
| View V2 | **done(子集)** | `page_token`/`semantic_generation`;SSE 过期包拒绝;帧选择保留;`local_deps`;sourced≠verified |
|
||||
| View V3 | **done(子集)** | print/响应式 CSS;100 单元确定性;1000 单元 compile smoke;无 JS 结构块仍在静态 HTML |
|
||||
| F1/M04 bind 闭环 | **done** | `artifact.reuse_execute` 实际复用;`agent_eng_bind_execute` + `publish_gate`(candidate_only / product gate);`tests/ext/agent-eng-bind-gate.mq.md` |
|
||||
| F2/M06–M07 | **done(子集)** | 统一 `EXCLUDED_DIRS`;`publish_manifest.json`;`function_sources`;story 失效/修复 |
|
||||
| F3/M01 提取 | **done(子集)** | `document.extract` text/Markdown;PDF/DOCX/OCR 显式失败;超限截断 partial;上传 `max_bytes` |
|
||||
|
||||
## 与后续切片的关系
|
||||
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
# 2026 年标准增值税率
|
||||
# 标准税率
|
||||
|
||||
演示用政策原文。标准税率为 13%。
|
||||
演示用政策原文。2026 年标准增值税率为 13%。
|
||||
@@ -1,3 +1,3 @@
|
||||
# 2026 年标准增值税率
|
||||
# 标准税率
|
||||
|
||||
演示用政策原文。标准税率为 13%。
|
||||
演示用政策原文(已过期样例)。标准税率为 13%。
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: F1 eng_bind_execute + publish_gate (no LLM)
|
||||
description: >-
|
||||
Deterministic fake-model substitute: bind+execute existing knowledge with
|
||||
actual_reuse trace; candidate_only / product_gate_ok=false refuse promote.
|
||||
Offline — no network / no LLM.
|
||||
import:
|
||||
fs: lib/fs.mq.md
|
||||
json: lib/json.mq.md
|
||||
plugin: lib/plugin.mq.md
|
||||
sys: lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=no-agent-plugin
|
||||
> sys.exit code=1
|
||||
|
||||
**root = "tests/executable_knowledge/baseline/02-extract"**
|
||||
`inputs` = > json.parse text={"数量":2,"单价":30}
|
||||
|
||||
**exec = > agent_eng_bind_execute project=`root` query="商品小计" policy="pure" inputs=`inputs` candidate_only=True**
|
||||
**ok = > json.get value=`exec` key="ok"**
|
||||
1. `ok`
|
||||
> print text=bind-execute-ok
|
||||
2. *
|
||||
> print text=bind-execute-FAIL
|
||||
> print text=`exec`
|
||||
> sys.exit code=1
|
||||
|
||||
**reuse = > json.get value=`exec` key="actual_reuse"**
|
||||
1. `reuse`
|
||||
> print text=actual-reuse-ok
|
||||
2. *
|
||||
> print text=actual-reuse-MISSING
|
||||
> sys.exit code=1
|
||||
|
||||
**gate1 = > agent_eng_publish_gate project=`root` artifact_id="商品小计" candidate_only=True product_gate_ok=True**
|
||||
**promote1 = > json.get value=`gate1` key="may_promote"**
|
||||
1. `promote1` == False
|
||||
> print text=candidate-only-blocks-promote
|
||||
2. *
|
||||
> print text=candidate-only-FAIL
|
||||
> print text=`gate1`
|
||||
> sys.exit code=1
|
||||
|
||||
**gate2 = > agent_eng_publish_gate project=`root` artifact_id="商品小计" candidate_only=False product_gate_ok=False**
|
||||
**promote2 = > json.get value=`gate2` key="may_promote"**
|
||||
1. `promote2` == False
|
||||
> print text=product-gate-blocks-promote
|
||||
2. *
|
||||
> print text=product-gate-FAIL
|
||||
> print text=`gate2`
|
||||
> sys.exit code=1
|
||||
|
||||
> print text=agent-eng-bind-gate-ok
|
||||
*"agent-eng-bind-gate-ok"*
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: workbench F02 agent selection (mock upstream)
|
||||
description: >-
|
||||
Explicit llm.create selection must drive agent.step; process env default model
|
||||
must not win. Upstream URL/key/model come from env set by the Rust harness.
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
sys: lib/sys.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**base = > sys.env_get name="OPENAI_BASE_URL"**
|
||||
**key = > sys.env_get name="OPENAI_API_KEY"**
|
||||
**mdl = > sys.env_get name="OPENAI_MODEL"**
|
||||
1. not `base`
|
||||
> print text=missing-OPENAI_BASE_URL
|
||||
> sys.exit code=2
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `key`
|
||||
> print text=missing-OPENAI_API_KEY
|
||||
> sys.exit code=2
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `mdl`
|
||||
> print text=missing-OPENAI_MODEL
|
||||
> sys.exit code=2
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
Poison ambient default — selection on the handle must still win at the plugin.
|
||||
> sys.env_set name="OPENAI_MODEL" value="env-poison-model"
|
||||
|
||||
**model = > llm.create model=`mdl` base_url=`base` api_key=`key` backend="openai-compatible" name=f02-agent**
|
||||
|
||||
`tools` =
|
||||
|
||||
| 工具 |
|
||||
|------|
|
||||
|
||||
**ag = > agent.agent model=`model` tools=`tools` standing="F02 selection probe; answer with one word only"**
|
||||
**step = > `ag`.step task="Reply with exactly one English word pong" writeback=False max_reads=1**
|
||||
**st = > json.get value=`step` key="status"**
|
||||
**ans = > json.get value=`step` key="result"**
|
||||
1. not `ans`
|
||||
**ans = > json.get value=`step` key="answer"**
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `ans`
|
||||
**ans = > json.get value=`step` key="text"**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
> print text=`st`
|
||||
> print text=`ans`
|
||||
|
||||
**dir = ".marqdo/workbench-f02-resume"**
|
||||
**saved = > agent.resume_save id="f02-sel" goal="pong" status="running" round=1 resume_dir=`dir`**
|
||||
**ok = > json.get value=`saved` key="ok"**
|
||||
1. `ok`
|
||||
> print text=resume-save-ok
|
||||
2. *
|
||||
> print text=resume-save-fail
|
||||
> print text=`saved`
|
||||
> sys.exit code=1
|
||||
|
||||
**loaded = > agent.resume id="f02-sel" resume_dir=`dir`**
|
||||
**found = > json.get value=`loaded` key="found"**
|
||||
1. `found`
|
||||
> print text=resume-load-ok
|
||||
2. *
|
||||
> print text=resume-load-fail
|
||||
> print text=`loaded`
|
||||
> sys.exit code=1
|
||||
|
||||
> agent.resume_clear id="f02-sel" resume_dir=`dir`
|
||||
> print text=f02-agent-selection-ok
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: workbench M01 live selection (USTC-compatible)
|
||||
description: Explicit ModelSelection via llm.create; no llm.llm. Credentials from process env only.
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
sys: lib/sys.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**base = > sys.env_get name="OPENAI_BASE_URL"**
|
||||
**key = > sys.env_get name="OPENAI_API_KEY"**
|
||||
**mdl = > sys.env_get name="OPENAI_MODEL"**
|
||||
1. not `base`
|
||||
> print text=missing-OPENAI_BASE_URL
|
||||
> sys.exit code=2
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `key`
|
||||
> print text=missing-OPENAI_API_KEY
|
||||
> sys.exit code=2
|
||||
2. *
|
||||
**_ = 1**
|
||||
1. not `mdl`
|
||||
**mdl = "qwen3.8-chat"**
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
**model = > llm.create model=`mdl` base_url=`base` api_key=`key` backend="openai-compatible" name=workbench-live**
|
||||
|
||||
**q = "Reply with exactly one English word pong"**
|
||||
**reply = > model.ask prompt=`q`**
|
||||
**text = > json.get value=`reply` key="text"**
|
||||
**usage = > json.get value=`reply` key="usage"**
|
||||
**pt = > json.get value=`usage` key="prompt_tokens"**
|
||||
|
||||
> print text=`text`
|
||||
1. `pt`
|
||||
> print text=usage-present
|
||||
2. *
|
||||
> print text=usage-unknown
|
||||
@@ -0,0 +1,20 @@
|
||||
{
|
||||
"schema": "DocumentViewV1",
|
||||
"schema_version": 1,
|
||||
"document": {
|
||||
"id": "knowledge/example.mq.md",
|
||||
"title": "知识标题",
|
||||
"source_revision": "sha256:requested-source",
|
||||
"semantic_digest": "sha256:semantic-facts",
|
||||
"generation_id": null,
|
||||
"presentation_token": "opaque-token"
|
||||
},
|
||||
"execution": {"state": "not_run", "run_id": null},
|
||||
"render": {"format": "sanitized_html", "fragment": "<article class=\"mq-document\"></article>", "renderer_version": "1"},
|
||||
"outline": [],
|
||||
"nodes": [],
|
||||
"refs": [],
|
||||
"diagnostics": [{"code": "partial", "message": "missing dependency"}],
|
||||
"completeness": "partial",
|
||||
"capabilities": {"read_only": true, "has_semantics": true, "executed": false}
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"ok": false,
|
||||
"error": {
|
||||
"code": "view.document_unsupported_format",
|
||||
"message": "binary formats require extract adapter",
|
||||
"retryable": false
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: F08 side-effect probe
|
||||
status: draft
|
||||
---
|
||||
|
||||
# F08
|
||||
|
||||
This document would write a marker if executed. View must never run it.
|
||||
|
||||
## mark
|
||||
|
||||
> file.write path=".workbench-f08-marker" text="executed"
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "stale",
|
||||
"precision": "document",
|
||||
"locator": {
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"project_id": "/authorized/project",
|
||||
"document_id": "knowledge/example.mq.md",
|
||||
"source_revision": "sha256:old",
|
||||
"artifact_id": "mq://project/example/function",
|
||||
"relation": "cites"
|
||||
},
|
||||
"target": null,
|
||||
"candidates": [],
|
||||
"diagnostics": [{"code": "source_revision_mismatch", "message": "expected sha256:old, actual sha256:new"}],
|
||||
"label": "该来源已变化"
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"resolution": "version_unavailable",
|
||||
"precision": "none",
|
||||
"locator": {
|
||||
"schema": "KnowledgeLocatorV1",
|
||||
"schema_version": 1,
|
||||
"project_id": "/authorized/project",
|
||||
"document_id": "knowledge/example.mq.md",
|
||||
"generation_id": "generation-missing",
|
||||
"artifact_id": "mq://project/example/function",
|
||||
"relation": "cites"
|
||||
},
|
||||
"target": null,
|
||||
"candidates": [],
|
||||
"diagnostics": [{"code": "generation_unavailable", "message": "snapshot not retained"}],
|
||||
"label": "引用版本不可用"
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"schema": "ModelCallUsageV1",
|
||||
"schema_version": 1,
|
||||
"call_id": "call-2",
|
||||
"attempt_id": "attempt-1",
|
||||
"parent_call_id": null,
|
||||
"run_id": "run-1",
|
||||
"turn_id": "turn-1",
|
||||
"workspace_scope": "ws-1",
|
||||
"purpose": "answer",
|
||||
"selection_id": "sel-1",
|
||||
"provider_id": "provider-1",
|
||||
"model_id": "model-2",
|
||||
"requested_model": "example-model",
|
||||
"resolved_model": "example-model",
|
||||
"status": "cancelled",
|
||||
"usage_state": "partial",
|
||||
"measurement_source": "provider",
|
||||
"input_tokens": 100,
|
||||
"output_tokens": 12,
|
||||
"total_tokens": 112,
|
||||
"cached_input_tokens": null,
|
||||
"reasoning_output_tokens": null,
|
||||
"revision": 2,
|
||||
"diagnostics": []
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"schema": "ModelCallUsageV1",
|
||||
"schema_version": 1,
|
||||
"call_id": "call-1",
|
||||
"attempt_id": "attempt-1",
|
||||
"parent_call_id": null,
|
||||
"run_id": "run-1",
|
||||
"turn_id": "turn-1",
|
||||
"workspace_scope": "ws-1",
|
||||
"purpose": "answer",
|
||||
"selection_id": "sel-1",
|
||||
"provider_id": "provider-1",
|
||||
"model_id": "model-2",
|
||||
"requested_model": "example-model",
|
||||
"resolved_model": "example-model",
|
||||
"status": "succeeded",
|
||||
"usage_state": "unknown",
|
||||
"measurement_source": "none",
|
||||
"input_tokens": null,
|
||||
"output_tokens": null,
|
||||
"total_tokens": null,
|
||||
"cached_input_tokens": null,
|
||||
"reasoning_output_tokens": null,
|
||||
"revision": 1,
|
||||
"diagnostics": []
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"schema": "ModelSelectionV1",
|
||||
"schema_version": 1,
|
||||
"error": {
|
||||
"code": "llm.selection_missing",
|
||||
"message": "selection_id required in strict mode",
|
||||
"retryable": false
|
||||
},
|
||||
"partial": {
|
||||
"model_id": "model-2"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"schema": "ModelSelectionV1",
|
||||
"schema_version": 1,
|
||||
"selection_id": "sel-1",
|
||||
"provider_id": "provider-1",
|
||||
"model_id": "model-2",
|
||||
"provider_revision": 3,
|
||||
"model_revision": 5,
|
||||
"adapter": "openai-compatible",
|
||||
"endpoint_ref": "endpoint-local-1",
|
||||
"credential_ref": "credential-local-1",
|
||||
"credential_version": 2,
|
||||
"upstream_model_id": "example-model",
|
||||
"parameters": {"max_output_tokens": 2048},
|
||||
"fallback_policy": "disabled",
|
||||
"auth_mode": "api_key"
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"schema": "RuntimeEventV1",
|
||||
"schema_version": 1,
|
||||
"event_id": "evt-9",
|
||||
"seq": 9,
|
||||
"run_id": "run-1",
|
||||
"parent_run_id": null,
|
||||
"turn_id": "turn-1",
|
||||
"workspace_scope": "ws-1",
|
||||
"timestamp": "2026-10-25T01:00:04Z",
|
||||
"type": "run.cancelled",
|
||||
"payload": {"reason": "user_stop", "usage_state": "partial"}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "marqdo://contracts/DocumentViewV1",
|
||||
"title": "DocumentViewV1",
|
||||
"type": "object",
|
||||
"required": ["schema", "schema_version", "document", "execution", "completeness"],
|
||||
"properties": {
|
||||
"schema": { "const": "DocumentViewV1" },
|
||||
"schema_version": { "const": 1 },
|
||||
"document": {
|
||||
"type": "object",
|
||||
"required": ["id", "source_revision"],
|
||||
"properties": {
|
||||
"id": { "type": "string" },
|
||||
"title": { "type": "string" },
|
||||
"source_revision": { "type": "string" },
|
||||
"semantic_digest": { "type": "string" },
|
||||
"generation_id": { "type": ["string", "null"] },
|
||||
"presentation_token": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"execution": {
|
||||
"type": "object",
|
||||
"required": ["state"],
|
||||
"properties": {
|
||||
"state": { "const": "not_run" },
|
||||
"run_id": { "type": ["string", "null"] }
|
||||
}
|
||||
},
|
||||
"completeness": { "enum": ["complete", "partial"] },
|
||||
"render": { "type": "object" },
|
||||
"outline": { "type": "array" },
|
||||
"nodes": { "type": "array" },
|
||||
"refs": { "type": "array" },
|
||||
"diagnostics": { "type": "array" }
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "marqdo://contracts/KnowledgeLocatorV1",
|
||||
"title": "KnowledgeLocatorV1",
|
||||
"type": "object",
|
||||
"required": ["schema_version", "project_id", "document_id"],
|
||||
"properties": {
|
||||
"schema": { "const": "KnowledgeLocatorV1" },
|
||||
"schema_version": { "const": 1 },
|
||||
"project_id": { "type": "string" },
|
||||
"document_id": { "type": "string" },
|
||||
"source_revision": { "type": ["string", "null"] },
|
||||
"generation_id": { "type": ["string", "null"] },
|
||||
"artifact_id": { "type": ["string", "null"] },
|
||||
"node_id": { "type": ["string", "null"] },
|
||||
"relation": { "type": "string" },
|
||||
"resolution": {
|
||||
"enum": [
|
||||
"resolved",
|
||||
"stale",
|
||||
"unresolved",
|
||||
"ambiguous",
|
||||
"version_unavailable",
|
||||
"unsupported"
|
||||
]
|
||||
}
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "marqdo://contracts/ModelCallUsageV1",
|
||||
"title": "ModelCallUsageV1",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"schema_version",
|
||||
"call_id",
|
||||
"attempt_id",
|
||||
"run_id",
|
||||
"status",
|
||||
"usage_state",
|
||||
"measurement_source"
|
||||
],
|
||||
"properties": {
|
||||
"schema": { "const": "ModelCallUsageV1" },
|
||||
"schema_version": { "const": 1 },
|
||||
"call_id": { "type": "string", "minLength": 1 },
|
||||
"attempt_id": { "type": "string", "minLength": 1 },
|
||||
"run_id": { "type": "string", "minLength": 1 },
|
||||
"status": {
|
||||
"enum": ["started", "succeeded", "failed", "cancelled", "interrupted"]
|
||||
},
|
||||
"usage_state": { "enum": ["pending", "partial", "final", "unknown"] },
|
||||
"measurement_source": { "enum": ["provider", "estimated", "none"] },
|
||||
"input_tokens": { "type": ["integer", "null"], "minimum": 0 },
|
||||
"output_tokens": { "type": ["integer", "null"], "minimum": 0 },
|
||||
"total_tokens": { "type": ["integer", "null"], "minimum": 0 },
|
||||
"revision": { "type": "integer", "minimum": 1 }
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "marqdo://contracts/ModelSelectionV1",
|
||||
"title": "ModelSelectionV1",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"schema_version",
|
||||
"selection_id",
|
||||
"provider_id",
|
||||
"model_id",
|
||||
"adapter",
|
||||
"upstream_model_id"
|
||||
],
|
||||
"properties": {
|
||||
"schema": { "const": "ModelSelectionV1" },
|
||||
"schema_version": { "const": 1 },
|
||||
"selection_id": { "type": "string", "minLength": 1 },
|
||||
"provider_id": { "type": "string", "minLength": 1 },
|
||||
"model_id": { "type": "string", "minLength": 1 },
|
||||
"adapter": { "type": "string" },
|
||||
"upstream_model_id": { "type": "string", "minLength": 1 },
|
||||
"provider_revision": { "type": ["integer", "null"] },
|
||||
"model_revision": { "type": ["integer", "null"] },
|
||||
"endpoint_ref": { "type": ["string", "null"] },
|
||||
"credential_ref": { "type": ["string", "null"] },
|
||||
"credential_version": { "type": ["integer", "null"] },
|
||||
"parameters": { "type": "object" },
|
||||
"fallback_policy": { "type": "string" },
|
||||
"auth_mode": { "type": "string" }
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "marqdo://contracts/RuntimeEventV1",
|
||||
"title": "RuntimeEventV1",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"schema_version",
|
||||
"event_id",
|
||||
"seq",
|
||||
"run_id",
|
||||
"type",
|
||||
"payload"
|
||||
],
|
||||
"properties": {
|
||||
"schema": { "const": "RuntimeEventV1" },
|
||||
"schema_version": { "const": 1 },
|
||||
"event_id": { "type": "string", "minLength": 1 },
|
||||
"seq": { "type": "integer", "minimum": 0 },
|
||||
"run_id": { "type": "string", "minLength": 1 },
|
||||
"type": { "type": "string", "minLength": 1 },
|
||||
"payload": { "type": "object" },
|
||||
"timestamp": { "type": "string" }
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
@@ -0,0 +1,815 @@
|
||||
//! Workbench M00–M06 contract gate (offline).
|
||||
//! Spec: doc/design/qdagent-workbench-runtime-and-view-2026-10-25.md
|
||||
|
||||
use serde_json::Value;
|
||||
use std::path::PathBuf;
|
||||
|
||||
fn fixture(name: &str) -> Value {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join("tests/workbench/fixtures").join(name);
|
||||
let raw = std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
|
||||
serde_json::from_str(&raw).expect("fixture json")
|
||||
}
|
||||
|
||||
fn schema(name: &str) -> Value {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join("tests/workbench/schemas").join(name);
|
||||
let raw = std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
|
||||
serde_json::from_str(&raw).expect("schema json")
|
||||
}
|
||||
|
||||
/// Lightweight required-field check against our JSON Schema documents (no jsonschema crate).
|
||||
fn assert_required(instance: &Value, schema_doc: &Value, label: &str) {
|
||||
let required = schema_doc["required"].as_array().expect("schema.required");
|
||||
for key in required {
|
||||
let k = key.as_str().unwrap();
|
||||
assert!(
|
||||
instance.get(k).is_some(),
|
||||
"{label}: missing required field {k} in {instance}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
fn mlsp(method: &str, params: Value) -> Value {
|
||||
let req = serde_json::json!({"id": 1, "method": method, "params": params});
|
||||
let line = marqdo::mlsp::handle_line(&req.to_string());
|
||||
serde_json::from_str(&line).expect("mlsp response json")
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m00_fixtures_consume_and_capabilities() {
|
||||
let sel = fixture("model_selection_ok.json");
|
||||
assert_required(&sel, &schema("ModelSelectionV1.schema.json"), "selection");
|
||||
assert_eq!(sel["schema"], "ModelSelectionV1");
|
||||
let parsed = marqdo::workbench::parse_model_selection(&sel, true).expect("strict ok");
|
||||
assert_eq!(parsed.selection_id, "sel-1");
|
||||
let snap = parsed.public_snapshot();
|
||||
assert!(snap.get("api_key").is_none());
|
||||
|
||||
let usage = fixture("model_call_usage_unknown.json");
|
||||
assert_required(&usage, &schema("ModelCallUsageV1.schema.json"), "usage");
|
||||
assert!(usage["input_tokens"].is_null());
|
||||
assert_ne!(usage["input_tokens"], 0);
|
||||
assert_eq!(usage["usage_state"], "unknown");
|
||||
|
||||
let cancelled = fixture("model_call_usage_cancelled.json");
|
||||
assert_eq!(cancelled["status"], "cancelled");
|
||||
assert_eq!(cancelled["usage_state"], "partial");
|
||||
|
||||
let doc = fixture("document_view_partial.json");
|
||||
assert_required(&doc, &schema("DocumentViewV1.schema.json"), "document_view");
|
||||
assert_eq!(doc["execution"]["state"], "not_run");
|
||||
|
||||
let stale = fixture("locator_stale.json");
|
||||
assert_eq!(stale["resolution"], "stale");
|
||||
let loc = &stale["locator"];
|
||||
assert_required(loc, &schema("KnowledgeLocatorV1.schema.json"), "locator");
|
||||
|
||||
let unavail = fixture("locator_version_unavailable.json");
|
||||
assert_eq!(unavail["resolution"], "version_unavailable");
|
||||
|
||||
let ev = fixture("runtime_event_cancelled.json");
|
||||
assert_required(&ev, &schema("RuntimeEventV1.schema.json"), "runtime_event");
|
||||
assert_eq!(ev["type"], "run.cancelled");
|
||||
|
||||
let _ = fixture("model_selection_error.json");
|
||||
let _ = fixture("document_view_unsupported.json");
|
||||
|
||||
let caps = mlsp("capabilities", serde_json::json!({}));
|
||||
assert_eq!(caps["ok"], true, "{caps}");
|
||||
let features = &caps["result"]["features"];
|
||||
assert_eq!(features["view.document"], 1);
|
||||
assert_eq!(features["view.reference_resolve"], 1);
|
||||
assert!(caps["result"]["contracts"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.any(|c| c.as_str() == Some("DocumentViewV1")));
|
||||
|
||||
// F16 honesty: unloaded plugins + forced-off stream/cancel → 0
|
||||
let down = mlsp(
|
||||
"capabilities",
|
||||
serde_json::json!({
|
||||
"force_unloaded": true,
|
||||
"force_stream_off": true,
|
||||
"force_cancel_off": true
|
||||
}),
|
||||
);
|
||||
assert_eq!(down["result"]["features"]["llm.messages"], 0);
|
||||
assert_eq!(down["result"]["features"]["runtime.event_stream"], 0);
|
||||
assert_eq!(down["result"]["features"]["runtime.cancel"], 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m00_strict_selection_rejects_missing() {
|
||||
let bad = serde_json::json!({"schema_version": 1, "model_id": "x"});
|
||||
let err = marqdo::workbench::parse_model_selection(&bad, true).unwrap_err();
|
||||
assert!(err.contains("selection_missing"), "{err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m02_usage_null_not_zero() {
|
||||
let usage = marqdo::workbench::model_call_usage_from_provider(
|
||||
"c1",
|
||||
"a1",
|
||||
"r1",
|
||||
&serde_json::json!({"selection_id": "s", "provider_id": "p", "model_id": "m"}),
|
||||
&serde_json::Value::Null,
|
||||
"succeeded",
|
||||
);
|
||||
assert!(usage["input_tokens"].is_null());
|
||||
assert_eq!(usage["measurement_source"], "none");
|
||||
assert_eq!(usage["usage_state"], "unknown");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m03_view_document_no_exec() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let resp = mlsp(
|
||||
"view.document",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"document": "main.mq.md",
|
||||
"mode": "read",
|
||||
"include": ["fragment", "outline", "nodes", "diagnostics"]
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
let doc = &resp["result"];
|
||||
assert_eq!(doc["schema"], "DocumentViewV1");
|
||||
assert_eq!(doc["execution"]["state"], "not_run");
|
||||
assert_eq!(doc["capabilities"]["read_only"], true);
|
||||
assert_eq!(doc["capabilities"]["executed"], false);
|
||||
let fragment = doc["render"]["fragment"].as_str().unwrap_or("");
|
||||
assert!(fragment.contains("mq-document"), "{fragment}");
|
||||
assert!(!fragment.contains("<script"), "must not embed scripts");
|
||||
let outline = doc["outline"].as_array().unwrap();
|
||||
assert!(
|
||||
outline.iter().any(|o| o["kind"] == "heading"),
|
||||
"expected heading outline from # lines: {outline:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m03_view_document_revision_mismatch_refuses_downgrade() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let resp = mlsp(
|
||||
"view.document",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"document": "main.mq.md",
|
||||
"revision": "sha256:deadbeef",
|
||||
"mode": "read"
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], false, "{resp}");
|
||||
assert_eq!(resp["error"]["code"], "view.revision_mismatch");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m04_reference_resolve_unresolved() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let resp = mlsp(
|
||||
"view.reference_resolve",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"project_id": root.to_string_lossy(),
|
||||
"document_id": "main.mq.md",
|
||||
"artifact_id": "does-not-exist-xyz"
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
assert_eq!(resp["result"]["resolution"], "unresolved");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m04_generation_mismatch_version_unavailable() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let resp = mlsp(
|
||||
"view.reference_resolve",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"project_id": root.to_string_lossy(),
|
||||
"document_id": "main.mq.md",
|
||||
"generation_id": "not-a-real-generation",
|
||||
"artifact_id": "商品小计"
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
assert_eq!(resp["result"]["resolution"], "version_unavailable");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m04_source_revision_mismatch_stale() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let resp = mlsp(
|
||||
"view.reference_resolve",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"project_id": root.to_string_lossy(),
|
||||
"document_id": "main.mq.md",
|
||||
"source_revision": "sha256:deadbeef",
|
||||
"artifact_id": "商品小计"
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
assert_eq!(resp["result"]["resolution"], "stale");
|
||||
assert_eq!(
|
||||
resp["result"]["diagnostics"][0]["code"],
|
||||
"source_revision_mismatch"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m04_artifact_inspect_version_mismatch() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let ok = mlsp(
|
||||
"artifact.inspect",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"artifact_id": "商品小计"
|
||||
}),
|
||||
);
|
||||
assert_eq!(ok["ok"], true, "{ok}");
|
||||
let bad_rev = mlsp(
|
||||
"artifact.inspect",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"artifact_id": "商品小计",
|
||||
"expected_source_revision": "sha256:deadbeef"
|
||||
}),
|
||||
);
|
||||
assert_eq!(bad_rev["ok"], false, "{bad_rev}");
|
||||
assert_eq!(bad_rev["error"]["code"], "artifact.version_mismatch");
|
||||
let bad_gen = mlsp(
|
||||
"artifact.inspect",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"artifact_id": "商品小计",
|
||||
"expected_generation": "not-a-real-generation"
|
||||
}),
|
||||
);
|
||||
assert_eq!(bad_gen["ok"], false, "{bad_gen}");
|
||||
assert_eq!(bad_gen["error"]["code"], "artifact.version_mismatch");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m05_extract_segment_byte_locator() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join("tests/executable_knowledge/baseline/02-extract/main.mq.md");
|
||||
let doc = marqdo::document_extract::extract_path(&path);
|
||||
assert!(doc.status == "ok" || doc.status == "partial", "{:?}", doc.status);
|
||||
assert!(
|
||||
doc.segments.iter().any(|s| s.locator.contains(":B")),
|
||||
"expected byte offset in locator: {:?}",
|
||||
doc.segments
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m06_capabilities_lists_adapters_honestly() {
|
||||
let caps = mlsp("capabilities", serde_json::json!({}));
|
||||
let adapters = caps["result"]["adapters"].as_array().unwrap();
|
||||
let native = adapters
|
||||
.iter()
|
||||
.find(|a| a["id"] == "anthropic-native")
|
||||
.unwrap();
|
||||
assert_eq!(native["available"], false);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m01_run_context_spawn_child_inherits_selection() {
|
||||
let parent = marqdo::workbench::RunContext::from_value(&serde_json::json!({
|
||||
"run_id": "run-parent",
|
||||
"turn_id": "turn-1",
|
||||
"workspace_scope": "ws-a",
|
||||
"selection_context": {
|
||||
"selection_id": "sel-1",
|
||||
"upstream_model_id": "model-a",
|
||||
"base_url": "http://127.0.0.1:9"
|
||||
},
|
||||
"cancellation_token": "/tmp/mq-cancel-test"
|
||||
}))
|
||||
.unwrap();
|
||||
let child = parent.spawn_child("run-child");
|
||||
assert_eq!(child.parent_run_id.as_deref(), Some("run-parent"));
|
||||
assert_eq!(child.selection_context["upstream_model_id"], "model-a");
|
||||
let env = child.selection_env();
|
||||
assert!(env.iter().any(|(k, v)| k == "OPENAI_MODEL" && v == "model-a"));
|
||||
assert!(env.iter().any(|(k, _)| k == "MARQDO_CANCEL_TOKEN"));
|
||||
// Public JSON must not invent api_key.
|
||||
assert!(child.to_json().get("api_key").is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m01_f01_parallel_selections_do_not_cross() {
|
||||
let a = marqdo::workbench::RunContext::from_value(&serde_json::json!({
|
||||
"run_id": "run-a",
|
||||
"selection_context": {
|
||||
"upstream_model_id": "model-a",
|
||||
"base_url": "http://127.0.0.1:7001"
|
||||
}
|
||||
}))
|
||||
.unwrap();
|
||||
let b = marqdo::workbench::RunContext::from_value(&serde_json::json!({
|
||||
"run_id": "run-b",
|
||||
"selection_context": {
|
||||
"upstream_model_id": "model-b",
|
||||
"base_url": "http://127.0.0.1:7002"
|
||||
}
|
||||
}))
|
||||
.unwrap();
|
||||
let ea = a.selection_env();
|
||||
let eb = b.selection_env();
|
||||
let model_a = ea.iter().find(|(k, _)| k == "OPENAI_MODEL").map(|(_, v)| v.as_str());
|
||||
let model_b = eb.iter().find(|(k, _)| k == "OPENAI_MODEL").map(|(_, v)| v.as_str());
|
||||
let base_a = ea.iter().find(|(k, _)| k == "OPENAI_BASE_URL").map(|(_, v)| v.as_str());
|
||||
let base_b = eb.iter().find(|(k, _)| k == "OPENAI_BASE_URL").map(|(_, v)| v.as_str());
|
||||
assert_eq!(model_a, Some("model-a"));
|
||||
assert_eq!(model_b, Some("model-b"));
|
||||
assert_ne!(base_a, base_b);
|
||||
assert_ne!(a.run_id, b.run_id);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m02_usage_revision_and_cancel_token() {
|
||||
let u1 = marqdo::workbench::model_call_usage_from_provider(
|
||||
"c1",
|
||||
"a1",
|
||||
"r1",
|
||||
&serde_json::json!({"selection_id": "s"}),
|
||||
&serde_json::json!({"prompt_tokens": 10, "completion_tokens": 2, "total_tokens": 12}),
|
||||
"succeeded",
|
||||
);
|
||||
assert_eq!(u1["usage_state"], "final");
|
||||
assert_eq!(u1["input_tokens"], 10);
|
||||
assert_eq!(u1["revision"], 1);
|
||||
|
||||
let dir = std::env::temp_dir().join(format!("mq-cancel-{}", std::process::id()));
|
||||
let _ = std::fs::remove_file(&dir);
|
||||
std::fs::write(&dir, "cancelled").unwrap();
|
||||
assert!(marqdo::workbench::cancel_requested(Some(dir.to_str().unwrap())));
|
||||
let _ = std::fs::remove_file(&dir);
|
||||
assert!(!marqdo::workbench::cancel_requested(Some("/no/such/cancel/token")));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m02_f05_usage_revision_replaces_same_attempt_not_sum() {
|
||||
let sel = serde_json::json!({"selection_id": "s"});
|
||||
let partial = marqdo::workbench::model_call_usage_from_provider_rev(
|
||||
"c1",
|
||||
"a1",
|
||||
"r1",
|
||||
&sel,
|
||||
&serde_json::json!({"prompt_tokens": 10, "completion_tokens": 1, "total_tokens": 11}),
|
||||
"started",
|
||||
1,
|
||||
);
|
||||
let final_u = marqdo::workbench::model_call_usage_from_provider_rev(
|
||||
"c1",
|
||||
"a1",
|
||||
"r1",
|
||||
&sel,
|
||||
&serde_json::json!({"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}),
|
||||
"succeeded",
|
||||
2,
|
||||
);
|
||||
let won = marqdo::workbench::replace_usage_if_newer(&partial, &final_u);
|
||||
assert_eq!(won["revision"], 2);
|
||||
assert_eq!(won["total_tokens"], 15);
|
||||
// Older revision must not overwrite.
|
||||
let kept = marqdo::workbench::replace_usage_if_newer(&final_u, &partial);
|
||||
assert_eq!(kept["revision"], 2);
|
||||
assert_eq!(kept["total_tokens"], 15);
|
||||
// New attempt is a distinct identity (caller must not merge).
|
||||
let retry = marqdo::workbench::model_call_usage_from_provider_rev(
|
||||
"c1",
|
||||
"a2",
|
||||
"r1",
|
||||
&sel,
|
||||
&serde_json::json!({"prompt_tokens": 3, "completion_tokens": 1, "total_tokens": 4}),
|
||||
"succeeded",
|
||||
1,
|
||||
);
|
||||
assert_ne!(retry["attempt_id"], final_u["attempt_id"]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m02_f07_cancel_does_not_undo_external_write() {
|
||||
let marker = std::env::temp_dir().join(format!("mq-f07-{}", std::process::id()));
|
||||
std::fs::write(&marker, "already-written").unwrap();
|
||||
let tok = std::env::temp_dir().join(format!("mq-f07-cancel-{}", std::process::id()));
|
||||
std::fs::write(&tok, "cancelled").unwrap();
|
||||
assert!(marqdo::workbench::cancel_requested(Some(tok.to_str().unwrap())));
|
||||
// Cancel must not claim or perform undo of prior external writes.
|
||||
assert_eq!(
|
||||
std::fs::read_to_string(&marker).unwrap(),
|
||||
"already-written"
|
||||
);
|
||||
let _ = std::fs::remove_file(&marker);
|
||||
let _ = std::fs::remove_file(&tok);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m02_event_sink_emits_runtime_event() {
|
||||
let path = std::env::temp_dir().join(format!("mq-evt-{}.ndjson", std::process::id()));
|
||||
let _ = std::fs::remove_file(&path);
|
||||
marqdo::workbench::bind_event_sink(&path);
|
||||
let ev = marqdo::workbench::emit_message_delta("run-evt", "hello");
|
||||
assert_eq!(ev["schema"], "RuntimeEventV1");
|
||||
assert_eq!(ev["type"], "message.delta");
|
||||
marqdo::workbench::clear_event_sink();
|
||||
let body = std::fs::read_to_string(&path).unwrap_or_default();
|
||||
assert!(body.contains("message.delta"), "{body}");
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m03_view_document_path_escape_rejected() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let resp = mlsp(
|
||||
"view.document",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"document": "../Cargo.toml",
|
||||
"mode": "read"
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], false, "{resp}");
|
||||
let code = resp["error"]["code"].as_str().unwrap_or("");
|
||||
assert!(
|
||||
code.contains("path") || code.contains("not_found") || code.contains("escape"),
|
||||
"{resp}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m05_project_cache_isolation_f14() {
|
||||
marqdo::workbench::reset_cache_for_tests();
|
||||
let a = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let b = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/01-inline");
|
||||
assert!(
|
||||
marqdo::workbench::analysis_cache::cache_keys_isolated(&a, &b),
|
||||
"distinct project roots must not share cache keys"
|
||||
);
|
||||
let _ = marqdo::workbench::analysis_cache::note_analysis(&a);
|
||||
let hit = marqdo::workbench::analysis_cache::note_analysis(&a);
|
||||
assert!(hit, "second analysis of same snapshot should hit cache");
|
||||
let _ = marqdo::workbench::analysis_cache::note_analysis(&b);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m05_f14_concurrent_100_same_snapshot() {
|
||||
use std::sync::{Arc, Barrier};
|
||||
use std::thread;
|
||||
|
||||
marqdo::workbench::reset_cache_for_tests();
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let root_s = root.to_string_lossy().to_string();
|
||||
let n = 100usize;
|
||||
let barrier = Arc::new(Barrier::new(n));
|
||||
let mut handles = Vec::with_capacity(n);
|
||||
for _ in 0..n {
|
||||
let barrier = Arc::clone(&barrier);
|
||||
let root_s = root_s.clone();
|
||||
handles.push(thread::spawn(move || {
|
||||
barrier.wait();
|
||||
let resp = mlsp(
|
||||
"view.document",
|
||||
serde_json::json!({
|
||||
"project": root_s,
|
||||
"document": "main.mq.md",
|
||||
"mode": "read",
|
||||
"include": ["fragment"]
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
resp["result"]["document"]["source_revision"]
|
||||
.as_str()
|
||||
.unwrap_or("")
|
||||
.to_string()
|
||||
}));
|
||||
}
|
||||
let mut revs = Vec::new();
|
||||
for h in handles {
|
||||
revs.push(h.join().expect("thread"));
|
||||
}
|
||||
assert!(revs.iter().all(|r| r == &revs[0]), "all reads same revision");
|
||||
assert!(revs[0].starts_with("sha256:"));
|
||||
let (hits, misses, merges) = marqdo::workbench::cache_stats();
|
||||
// At least one miss (leader) and either merges (coalesce) or subsequent hits.
|
||||
assert!(misses >= 1, "hits={hits} misses={misses} merges={merges}");
|
||||
assert!(
|
||||
merges > 0 || hits > 0,
|
||||
"expected coalesce or reuse: hits={hits} misses={misses} merges={merges}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m04_snapshot_manifest_on_document_view() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let resp = mlsp(
|
||||
"view.document",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"document": "main.mq.md",
|
||||
"mode": "read",
|
||||
"include": ["fragment"]
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
let snap = &resp["result"]["snapshot"];
|
||||
assert_eq!(snap["schema"], "SnapshotManifestV1");
|
||||
assert_eq!(snap["retention"]["owner"], "application");
|
||||
assert!(snap["source_revision"].as_str().unwrap().starts_with("sha256:"));
|
||||
assert_eq!(
|
||||
snap["source_revision"],
|
||||
resp["result"]["document"]["source_revision"]
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m01_f02_run_context_three_level_inherit() {
|
||||
let root = marqdo::workbench::RunContext::from_value(&serde_json::json!({
|
||||
"run_id": "run-root",
|
||||
"turn_id": "turn-1",
|
||||
"workspace_scope": "ws-1",
|
||||
"selection_context": {
|
||||
"selection_id": "sel-1",
|
||||
"upstream_model_id": "model-fixed",
|
||||
"base_url": "http://127.0.0.1:7700"
|
||||
},
|
||||
"cancellation_token": "/tmp/mq-cancel-f02"
|
||||
}))
|
||||
.unwrap();
|
||||
let child = root.spawn_child("run-child");
|
||||
let grand = child.spawn_child("run-grand");
|
||||
assert_eq!(grand.parent_run_id.as_deref(), Some("run-child"));
|
||||
assert_eq!(
|
||||
grand.selection_context["upstream_model_id"],
|
||||
"model-fixed"
|
||||
);
|
||||
assert_eq!(grand.turn_id.as_deref(), Some("turn-1"));
|
||||
assert_eq!(
|
||||
grand.cancellation_token.as_deref(),
|
||||
Some("/tmp/mq-cancel-f02")
|
||||
);
|
||||
let env = grand.selection_env();
|
||||
assert!(env.iter().any(|(k, v)| k == "OPENAI_MODEL" && v == "model-fixed"));
|
||||
// Root selection must not be mutated by descendants.
|
||||
assert_eq!(root.selection_context["upstream_model_id"], "model-fixed");
|
||||
assert_eq!(root.run_id, "run-root");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m03_f08_side_effect_marker_not_created_by_view() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/workbench/fixtures");
|
||||
let marker = root.join(".workbench-f08-marker");
|
||||
let _ = std::fs::remove_file(&marker);
|
||||
let resp = mlsp(
|
||||
"view.document",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"document": "f08_write_side_effect.mq.md",
|
||||
"mode": "read",
|
||||
"include": ["fragment", "diagnostics"]
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
assert_eq!(resp["result"]["execution"]["state"], "not_run");
|
||||
assert!(
|
||||
!marker.exists(),
|
||||
"view.document must not execute file.write side effects"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m03_f09_step_kinds_baseline_projects_nodes() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/07-step-kinds");
|
||||
let resp = mlsp(
|
||||
"view.document",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"document": "main.mq.md",
|
||||
"mode": "read",
|
||||
"include": ["outline", "nodes", "fragment"]
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
let outline = resp["result"]["outline"].as_array().unwrap();
|
||||
assert!(
|
||||
outline.iter().any(|o| o["kind"] == "heading"),
|
||||
"expected heading outline: {outline:?}"
|
||||
);
|
||||
let nodes = resp["result"]["nodes"].as_array().unwrap();
|
||||
assert!(nodes.len() >= 2, "expected artifact+step nodes: {nodes:?}");
|
||||
let kinds: std::collections::HashSet<&str> = nodes
|
||||
.iter()
|
||||
.filter_map(|n| n["kind"].as_str())
|
||||
.collect();
|
||||
assert!(
|
||||
kinds.iter().any(|k| matches!(
|
||||
*k,
|
||||
"observe" | "derive" | "call" | "iterate" | "narrate" | "type" | "function"
|
||||
)),
|
||||
"expected step/artifact kinds in read model: {kinds:?}"
|
||||
);
|
||||
// Evidence statuses must not be silently upgraded to verified by the read path.
|
||||
for n in nodes {
|
||||
if let Some(ev) = n.get("evidence").and_then(|v| v.as_str()) {
|
||||
assert_ne!(ev, "verified", "read path must not invent verified: {n}");
|
||||
}
|
||||
}
|
||||
let fragment = resp["result"]["render"]["fragment"].as_str().unwrap_or("");
|
||||
assert!(fragment.contains("mq-document"));
|
||||
assert!(!fragment.contains("<script"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m03_f09_outline_nodes_chinese_and_static_a11y_subset() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/02-extract");
|
||||
let resp = mlsp(
|
||||
"view.document",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"document": "main.mq.md",
|
||||
"mode": "read",
|
||||
"include": ["fragment", "outline", "nodes", "refs"]
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
let doc = &resp["result"];
|
||||
let outline = doc["outline"].as_array().unwrap();
|
||||
assert!(outline.iter().any(|o| o["kind"] == "heading"));
|
||||
let nodes = doc["nodes"].as_array().unwrap();
|
||||
assert!(!nodes.is_empty(), "expected semantic nodes");
|
||||
// Chinese / CJK labels should round-trip in outline or nodes when present in source.
|
||||
let blob = format!("{outline:?}{nodes:?}");
|
||||
assert!(
|
||||
blob.chars().any(|c| c >= '\u{4e00}'),
|
||||
"expected CJK in outline/nodes for 02-extract: {blob}"
|
||||
);
|
||||
let fragment = doc["render"]["fragment"].as_str().unwrap_or("");
|
||||
// F12 static HTML subset (full browser → qdagent): semantic article, no script, mq namespace.
|
||||
assert!(fragment.starts_with("<article") || fragment.contains("mq-document"));
|
||||
assert!(!fragment.contains("<script"));
|
||||
assert!(!fragment.contains("javascript:"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn m04_f11_ambiguous_same_name() {
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests/executable_knowledge/baseline/08-same-name");
|
||||
assert!(root.is_dir(), "missing 08-same-name fixture");
|
||||
// a.mq.md and b.mq.md both define 商品小计 — omit document_id so both stay in scope.
|
||||
let resp = mlsp(
|
||||
"view.reference_resolve",
|
||||
serde_json::json!({
|
||||
"project": root.to_string_lossy(),
|
||||
"project_id": root.to_string_lossy(),
|
||||
"artifact_id": "商品小计"
|
||||
}),
|
||||
);
|
||||
assert_eq!(resp["ok"], true, "{resp}");
|
||||
assert_eq!(resp["result"]["resolution"], "ambiguous", "{resp}");
|
||||
let cands = resp["result"]["candidates"].as_array().unwrap();
|
||||
assert!(cands.len() >= 2, "{resp}");
|
||||
}
|
||||
|
||||
/// F02: agent.step + resume with explicit llm.create selection against a local mock.
|
||||
/// Env poison model must not appear in the upstream request body.
|
||||
#[test]
|
||||
fn m01_f02_agent_step_selection_and_resume() {
|
||||
use std::io::{Read, Write};
|
||||
use std::net::TcpListener;
|
||||
use std::process::Command;
|
||||
use std::sync::{Arc, Mutex};
|
||||
use std::thread;
|
||||
|
||||
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let ext = root.join("ext");
|
||||
|
||||
let status = Command::new("cargo")
|
||||
.args(["build", "-p", "marqdo_plugin_llm", "-p", "marqdo_plugin_agent", "--locked"])
|
||||
.current_dir(&root)
|
||||
.status()
|
||||
.expect("build plugins");
|
||||
assert!(status.success(), "plugin build failed");
|
||||
|
||||
let llm_so = root.join("target/debug/libllm.so");
|
||||
let agent_so = root.join("target/debug/libagent.so");
|
||||
assert!(llm_so.is_file(), "missing {llm_so:?}");
|
||||
assert!(agent_so.is_file(), "missing {agent_so:?}");
|
||||
|
||||
let seen = Arc::new(Mutex::new(Vec::new()));
|
||||
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
|
||||
let addr = listener.local_addr().unwrap();
|
||||
let seen_bg = seen.clone();
|
||||
thread::spawn(move || {
|
||||
// Agent may deepen once (READ) then answer — accept a few requests.
|
||||
for _ in 0..4 {
|
||||
let Ok((mut stream, _)) = listener.accept() else {
|
||||
break;
|
||||
};
|
||||
let mut raw = Vec::new();
|
||||
let mut buf = [0u8; 4096];
|
||||
loop {
|
||||
let n = stream.read(&mut buf).unwrap_or(0);
|
||||
if n == 0 {
|
||||
break;
|
||||
}
|
||||
raw.extend_from_slice(&buf[..n]);
|
||||
if let Some(pos) = raw.windows(4).position(|w| w == b"\r\n\r\n") {
|
||||
let header = String::from_utf8_lossy(&raw[..pos]);
|
||||
let cl = header
|
||||
.lines()
|
||||
.find_map(|l| l.strip_prefix("Content-Length:"))
|
||||
.and_then(|v| v.trim().parse::<usize>().ok())
|
||||
.unwrap_or(0);
|
||||
let body_start = pos + 4;
|
||||
while raw.len() < body_start + cl {
|
||||
let n = stream.read(&mut buf).unwrap_or(0);
|
||||
if n == 0 {
|
||||
break;
|
||||
}
|
||||
raw.extend_from_slice(&buf[..n]);
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
let req = String::from_utf8_lossy(&raw).to_string();
|
||||
seen_bg.lock().unwrap().push(req);
|
||||
let body = r#"{"choices":[{"message":{"content":"pong"},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1,"total_tokens":4}}"#;
|
||||
let resp = format!(
|
||||
"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
|
||||
body.len(),
|
||||
body
|
||||
);
|
||||
let _ = stream.write_all(resp.as_bytes());
|
||||
}
|
||||
});
|
||||
|
||||
let base = format!("http://{addr}/v1");
|
||||
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args(["run", "tests/ext/workbench-agent-selection.mq.md"])
|
||||
.current_dir(&root)
|
||||
.env("MARQDO_EXT", &ext)
|
||||
.env("MARQDO_LLM_PLUGIN", &llm_so)
|
||||
.env("MARQDO_AGENT_PLUGIN", &agent_so)
|
||||
.env("OPENAI_BASE_URL", &base)
|
||||
.env("OPENAI_API_KEY", "f02-key")
|
||||
.env("OPENAI_MODEL", "f02-selected-model")
|
||||
.output()
|
||||
.expect("run workbench-agent-selection");
|
||||
let stdout = String::from_utf8_lossy(&output.stdout);
|
||||
let stderr = String::from_utf8_lossy(&output.stderr);
|
||||
assert_eq!(
|
||||
output.status.code().unwrap_or(1),
|
||||
0,
|
||||
"stderr={stderr}\nstdout={stdout}"
|
||||
);
|
||||
assert!(
|
||||
stdout.contains("f02-agent-selection-ok"),
|
||||
"stdout={stdout}"
|
||||
);
|
||||
assert!(stdout.contains("resume-save-ok") && stdout.contains("resume-load-ok"));
|
||||
|
||||
let captured = seen.lock().unwrap().join("\n");
|
||||
assert!(
|
||||
!captured.is_empty(),
|
||||
"mock received no HTTP; stdout={stdout}"
|
||||
);
|
||||
// Body may embed the .mq.md source (which mentions the poison string in prose).
|
||||
// Assert the OpenAI `model` field itself — not a raw substring of the whole HTTP dump.
|
||||
let model_field = captured
|
||||
.split("\r\n\r\n")
|
||||
.nth(1)
|
||||
.unwrap_or("")
|
||||
.lines()
|
||||
.next()
|
||||
.unwrap_or("");
|
||||
let body: Value = serde_json::from_str(model_field).unwrap_or_else(|_| {
|
||||
// Some captures concatenate multiple HTTP messages; take last `{...}` blob.
|
||||
let start = captured.rfind('{').expect("json body");
|
||||
serde_json::from_str(&captured[start..]).expect("parse chat body")
|
||||
});
|
||||
assert_eq!(
|
||||
body["model"].as_str(),
|
||||
Some("f02-selected-model"),
|
||||
"upstream model field: {body}"
|
||||
);
|
||||
assert_ne!(body["model"].as_str(), Some("env-poison-model"));
|
||||
}
|
||||
@@ -0,0 +1,140 @@
|
||||
//! Live workbench gates — skipped unless OPENAI_API_KEY is set (never commit secrets).
|
||||
|
||||
use std::process::Command;
|
||||
|
||||
fn live_key() -> Option<String> {
|
||||
for k in ["OPENAI_API_KEY", "MARQDO_LLM_API_KEY"] {
|
||||
if let Ok(v) = std::env::var(k) {
|
||||
let t = v.trim();
|
||||
if !t.is_empty() && t != "sk-test" {
|
||||
return Some(t.to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn repo_ext() -> std::path::PathBuf {
|
||||
std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("ext")
|
||||
}
|
||||
|
||||
fn ensure_llm_plugin() {
|
||||
let status = Command::new("cargo")
|
||||
.args(["build", "-p", "marqdo_plugin_llm", "--locked"])
|
||||
.current_dir(env!("CARGO_MANIFEST_DIR"))
|
||||
.status()
|
||||
.expect("build llm plugin");
|
||||
assert!(status.success());
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let so = root.join("target/debug/libllm.so");
|
||||
if so.is_file() {
|
||||
std::env::set_var("MARQDO_LLM_PLUGIN", &so);
|
||||
}
|
||||
// Prefer in-tree ext/ over ~/.marqdo/ext (search roots list user install first).
|
||||
std::env::set_var("MARQDO_EXT", repo_ext());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn live_selection_ask_pong() {
|
||||
let Some(_key) = live_key() else {
|
||||
eprintln!("skip live_selection_ask_pong: no API key");
|
||||
return;
|
||||
};
|
||||
ensure_llm_plugin();
|
||||
if std::env::var_os("OPENAI_BASE_URL").is_none() {
|
||||
eprintln!("skip: set OPENAI_BASE_URL (e.g. https://api.llm.ustc.edu.cn/v1)");
|
||||
return;
|
||||
}
|
||||
if std::env::var_os("OPENAI_MODEL").is_none() {
|
||||
std::env::set_var("OPENAI_MODEL", "qwen3.8-chat");
|
||||
}
|
||||
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args(["run", "tests/ext/workbench-selection-live.mq.md"])
|
||||
.current_dir(env!("CARGO_MANIFEST_DIR"))
|
||||
.env("MARQDO_EXT", repo_ext())
|
||||
.env("MARQDO_LLM_PLUGIN", std::env::var_os("MARQDO_LLM_PLUGIN").unwrap_or_default())
|
||||
.output()
|
||||
.expect("run workbench-selection-live");
|
||||
let code = output.status.code().unwrap_or(1);
|
||||
let stdout = String::from_utf8_lossy(&output.stdout);
|
||||
let stderr = String::from_utf8_lossy(&output.stderr);
|
||||
assert_eq!(code, 0, "stderr={stderr}\nstdout={stdout}");
|
||||
let lower = stdout.to_lowercase();
|
||||
assert!(lower.contains("pong"), "expected pong, got {stdout:?}");
|
||||
assert!(
|
||||
stdout.contains("usage-present") || stdout.contains("usage-unknown"),
|
||||
"expected usage line, got {stdout:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn live_dual_model_isolation_via_plugin() {
|
||||
let Some(key) = live_key() else {
|
||||
eprintln!("skip live_dual_model_isolation_via_plugin: no API key");
|
||||
return;
|
||||
};
|
||||
let base = match std::env::var("OPENAI_BASE_URL") {
|
||||
Ok(v) if !v.trim().is_empty() => v,
|
||||
_ => {
|
||||
eprintln!("skip: OPENAI_BASE_URL required");
|
||||
return;
|
||||
}
|
||||
};
|
||||
ensure_llm_plugin();
|
||||
// Two sequential asks with different model ids — both must succeed without env clobber.
|
||||
for model in ["qwen3.8-chat", "deepseek-flash"] {
|
||||
std::env::set_var("OPENAI_MODEL", model);
|
||||
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args(["run", "tests/ext/workbench-selection-live.mq.md"])
|
||||
.current_dir(env!("CARGO_MANIFEST_DIR"))
|
||||
.env("OPENAI_API_KEY", &key)
|
||||
.env("OPENAI_BASE_URL", &base)
|
||||
.env("OPENAI_MODEL", model)
|
||||
.env("MARQDO_EXT", repo_ext())
|
||||
.env(
|
||||
"MARQDO_LLM_PLUGIN",
|
||||
std::env::var_os("MARQDO_LLM_PLUGIN").unwrap_or_default(),
|
||||
)
|
||||
.output()
|
||||
.expect("run");
|
||||
let stdout = String::from_utf8_lossy(&output.stdout);
|
||||
let stderr = String::from_utf8_lossy(&output.stderr);
|
||||
assert_eq!(
|
||||
output.status.code().unwrap_or(1),
|
||||
0,
|
||||
"model={model} stderr={stderr} stdout={stdout}"
|
||||
);
|
||||
assert!(
|
||||
stdout.to_lowercase().contains("pong"),
|
||||
"model={model} stdout={stdout}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn cli_view_document_writes_embed_html() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let out = root.join("target/workbench-docview.html");
|
||||
let _ = std::fs::remove_file(&out);
|
||||
let status = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"view",
|
||||
"document",
|
||||
"--project",
|
||||
root.join("tests/executable_knowledge/baseline/02-extract")
|
||||
.to_str()
|
||||
.unwrap(),
|
||||
"--document",
|
||||
"main.mq.md",
|
||||
"--out",
|
||||
out.to_str().unwrap(),
|
||||
])
|
||||
.current_dir(&root)
|
||||
.status()
|
||||
.expect("view document");
|
||||
assert!(status.success());
|
||||
let html = std::fs::read_to_string(&out).expect("read html");
|
||||
assert!(html.contains("mq-document"));
|
||||
assert!(!html.contains("<script"));
|
||||
assert!(html.contains("execution") || html.contains("mq-document"));
|
||||
}
|
||||
Reference in new issue
Block a user