Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
82c8d78fd3 | ||
|
|
58791fc7d9 | ||
|
|
1730f26fc7 | ||
|
|
4018e9928a | ||
|
|
628e3b6e5d | ||
|
|
5c6c612edd | ||
|
|
41587f319e | ||
|
|
298fbd51ea | ||
|
|
265dfdbcc4 | ||
|
|
42a43f5ffd | ||
|
|
037a963547 | ||
|
|
a32638e935 | ||
|
|
43eebe5671 | ||
|
|
e833dc05e2 | ||
|
|
11bb7ef277 | ||
|
|
6bd90bb2d0 | ||
|
|
4683f2e067 | ||
|
|
5912164039 | ||
|
|
303c06f773 | ||
|
|
a1086fd6c3 | ||
|
|
6ffe5ceb19 | ||
|
|
6b568aff3d | ||
|
|
16f26d7d60 | ||
|
|
b8265a92aa | ||
|
|
9af929971c | ||
|
|
2c4fa4bb05 | ||
|
|
3cabe53da2 | ||
|
|
58e13ee6d3 | ||
|
|
1b11fe063a | ||
|
|
b792f44556 | ||
|
|
9ea5bebfc3 | ||
|
|
c7c329341b | ||
|
|
8cf5288481 | ||
|
|
69c4e74872 | ||
|
|
af0bda2e40 | ||
|
|
090b026547 | ||
|
|
03396afd02 | ||
|
|
663a8ba2c0 | ||
|
|
dc853fb580 | ||
|
|
0b80ff8e50 | ||
|
|
b8a4ddd38f | ||
|
|
352bc0d2c5 | ||
|
|
8a6d09d582 | ||
|
|
dcd3d329d4 | ||
|
|
0e1bfb3359 | ||
|
|
e9ae7ff1ae | ||
|
|
ecbdd18303 | ||
|
|
bedd53e212 | ||
|
|
7674ebb869 | ||
|
|
434be9fd52 | ||
|
|
ae97891266 | ||
|
|
aea86746e7 | ||
|
|
c773503938 | ||
|
|
939e23ee88 | ||
|
|
687c168014 | ||
|
|
eac9b45263 | ||
|
|
74b298e80d | ||
|
|
fc7097bae4 | ||
|
|
b624084745 | ||
|
|
0bbe735c3c | ||
|
|
92de46aca4 | ||
|
|
8bbe017a5e | ||
|
|
1a13989230 | ||
|
|
5ad1a07f5c | ||
|
|
bcfc763ba4 | ||
|
|
bf76e069ee | ||
|
|
9015de26e5 | ||
|
|
8c24d96626 | ||
|
|
4a2f5bf226 | ||
|
|
86e921e959 | ||
|
|
b196a44685 | ||
|
|
c8ed5bffb7 | ||
|
|
fb135ae2f8 | ||
|
|
69fcdd6227 | ||
|
|
deac53d0f5 | ||
|
|
932403237a | ||
|
|
a14a6e221d | ||
|
|
8b0ea9ed7a | ||
|
|
6ae0d39e5a | ||
|
|
307c8efa81 | ||
|
|
34b0911218 | ||
|
|
4488a3cb70 | ||
|
|
9dbcc728b6 | ||
|
|
0405a60d68 | ||
|
|
409b8df2cb | ||
|
|
6bba0be6d2 | ||
|
|
1c90312c02 | ||
|
|
fd0cfcb566 | ||
|
|
6dd0ce47b1 | ||
|
|
1a94cc8490 | ||
|
|
11417c42e0 | ||
|
|
13012cac0e | ||
|
|
5a0f4ed747 | ||
|
|
05b8edc186 | ||
|
|
8926f7bed6 | ||
|
|
18b0c655f7 | ||
|
|
924885969f | ||
|
|
619271b8eb | ||
|
|
719b7a8d82 | ||
|
|
dfe99a10b4 | ||
|
|
fac68e85ea | ||
|
|
639b0ebcd1 | ||
|
|
2c4dac005c | ||
|
|
0ac661eef2 | ||
|
|
1dd74578b5 | ||
|
|
14114993c4 | ||
|
|
e80c944c40 | ||
|
|
30cd5a0833 | ||
|
|
e2068c2051 | ||
|
|
9cda80ee7d | ||
|
|
eae4815fc7 | ||
|
|
3260494e5c | ||
|
|
3330a0fc66 | ||
|
|
42a1a46383 | ||
|
|
b6629e5450 | ||
|
|
ecd7d5e433 | ||
|
|
aeb5a2a43d | ||
|
|
f2d651e063 | ||
|
|
b020b9d218 | ||
|
|
33a14d272c | ||
|
|
6ed70fd8b8 | ||
|
|
115d1f6c0b | ||
|
|
7dc5e56850 | ||
|
|
514caa55ae | ||
|
|
74908ebf04 | ||
|
|
0f852593bc | ||
|
|
34e2fb4f74 | ||
|
|
0e407b2bd3 | ||
|
|
e5e532d83f | ||
|
|
064522a338 | ||
|
|
c85f1a2829 | ||
|
|
a7266185b2 | ||
|
|
4d7c0bea1b | ||
|
|
53758ebd1c | ||
|
|
dff0b700ae | ||
|
|
4da07c1b26 | ||
|
|
78922102e4 | ||
|
|
064bae2c65 | ||
|
|
92b91ffc81 | ||
|
|
ab6648ae0e | ||
|
|
5acf026e0c | ||
|
|
8dcd69412f | ||
|
|
2a13e52981 | ||
|
|
9b269f6447 | ||
|
|
15362cb048 | ||
|
|
05d48f68a4 | ||
|
|
e4387259ba | ||
|
|
518f8e386b | ||
|
|
9da12c9093 | ||
|
|
e0d34669e0 | ||
|
|
0ba4d3d2d7 | ||
|
|
ad3ebf243a | ||
|
|
142d30ce08 | ||
|
|
4757b82edd | ||
|
|
bff2f53e52 | ||
|
|
fb28eee62f | ||
|
|
01468ad976 | ||
|
|
f3791d11b4 | ||
|
|
7fef690167 | ||
|
|
024cdee82a | ||
|
|
f666eaaf40 | ||
|
|
e6f05c7748 | ||
|
|
81f9ea0072 | ||
|
|
dbf3f3a14b | ||
|
|
654e89d98c | ||
|
|
be20629496 | ||
|
|
3223295841 | ||
|
|
beb5bdbe8c | ||
|
|
b8cb022018 | ||
|
|
b9e331cb31 | ||
|
|
476c2b607b | ||
|
|
d99b275336 | ||
|
|
1415aee08f | ||
|
|
0f2c12b636 | ||
|
|
9873df7099 | ||
|
|
3001ed7ba5 | ||
|
|
050d71927f | ||
|
|
7859170aec | ||
|
|
e32ff8f6b3 | ||
|
|
c21a28c3bc | ||
|
|
1e61dca9d8 | ||
|
|
ba675a4767 | ||
|
|
bfd468d5e3 | ||
|
|
8353ba38fe | ||
|
|
b43a08b2e2 | ||
|
|
1908bf1a53 | ||
|
|
c44ea38ae2 | ||
|
|
d489f7c088 | ||
|
|
a993cfd76a | ||
|
|
d5f826a8c8 | ||
|
|
0f72173d08 | ||
|
|
a707758d47 | ||
|
|
63bcb882a6 | ||
|
|
1bb16dd6db | ||
|
|
58ec2172d6 | ||
|
|
66926e9e0a | ||
|
|
dcf4c05663 | ||
|
|
f47a1e143a | ||
|
|
9cf98a98b5 | ||
|
|
f99d552d87 | ||
|
|
7d49c358c1 | ||
|
|
a32c0cd78f | ||
|
|
0a8f76d9b4 | ||
|
|
4e2419b598 | ||
|
|
f6374d1593 | ||
|
|
9ede4bc63d | ||
|
|
3ae8f2c843 | ||
|
|
e9c1a8a730 | ||
|
|
5554b1642c | ||
|
|
fe15603a91 | ||
|
|
1418742655 | ||
|
|
ed31a2b31d | ||
|
|
56ab52356f | ||
|
|
2e425c3010 |
No files matched your search
@@ -38,7 +38,7 @@ A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data
|
||||
|
||||
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
|
||||
|
||||
### 2. Good patterns
|
||||
### 2. Good patterns (copy these — not `json.set`)
|
||||
|
||||
**Wire / steps / commands** — `@` record table:
|
||||
|
||||
@@ -60,7 +60,53 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
|
||||
| `wire` | `set_text` |
|
||||
```
|
||||
|
||||
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
|
||||
**Agent / LLM result map** — one readable row, not a `json.parse` + `json.set` chain:
|
||||
|
||||
```markdown
|
||||
`out` =
|
||||
|
||||
| status | task | result | llm_calls | tokens |
|
||||
|--------|------|--------|-----------|--------|
|
||||
| ok | `task` | `reply` | `llm_calls` | `tokens` |
|
||||
|
||||
*out*
|
||||
```
|
||||
|
||||
**Soft error pack** (transport / gate failure) — still a table humans can skim:
|
||||
|
||||
```markdown
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
**Optional / conditional key** — sparse `table.put` after the static table (one dynamic key only):
|
||||
|
||||
```markdown
|
||||
`out` =
|
||||
|
||||
| status | task |
|
||||
|--------|------|
|
||||
| error | `task` |
|
||||
|
||||
1. `err`
|
||||
**out = > table.put in=`out` at="error" value=`err`**
|
||||
2. *
|
||||
**_ = 1**
|
||||
```
|
||||
|
||||
**Empty list / empty map** — prefer stdlib seeds over `json.parse text=[]` / `{}`:
|
||||
|
||||
```markdown
|
||||
**empty_tc = > table.empty_list**
|
||||
**empty_map = > table.empty_map**
|
||||
```
|
||||
|
||||
**Single dynamic key from scratch** — one `table.put` (or a helper), not a json chain:
|
||||
|
||||
```markdown
|
||||
**`set_text` = table.put in=None at="#log" value=msg**
|
||||
@@ -73,14 +119,20 @@ Better still — call a named helper:
|
||||
**browser.set_text sel="#log" text=msg**
|
||||
```
|
||||
|
||||
### 3. Bad pattern (do not write)
|
||||
**When `json.*` is OK:** `json.parse` / `json.stringify` / `json.quote` on **wire text**; `json.get` to read an opaque map. Never use `json.set` / `json.append` to *build* author-facing structures.
|
||||
|
||||
### 3. Bad pattern (do not write — and do not copy from old `ext/ai`)
|
||||
|
||||
```markdown
|
||||
**`ret` = json.set map=None key="set_text" value=…**
|
||||
**`ret` = json.set map=ret key="canvas" value=…**
|
||||
**`cmds` = json.append list=cmds item=c0**
|
||||
**`out` = json.parse text={"status":"ok"}**
|
||||
**`out` = json.set map=out key="task" value=task**
|
||||
```
|
||||
|
||||
Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compliance. Refactor the call site to tables / `table.put` instead of extending the glue.
|
||||
|
||||
## Writing application `.mq.md`
|
||||
|
||||
1. Frontmatter: title + imports (`table`, domain libs). **Do not import `json` unless parsing strings.**
|
||||
@@ -92,7 +144,7 @@ Better still — call a named helper:
|
||||
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
|
||||
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
|
||||
|
||||
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
|
||||
Browser client programs: prefer nested `import:` with `browser: lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
|
||||
|
||||
## Developing libraries (`lib/*`, `ext/*`)
|
||||
|
||||
@@ -134,7 +186,7 @@ When editing a file full of `json.set`:
|
||||
1. Turn static structures into GFM tables.
|
||||
2. Replace repeated effect shapes with `browser.*` / `web.text_patch` / `web.dom_patch`.
|
||||
3. Leave at most sparse `table.put` for dynamic keys.
|
||||
4. Drop `import json:…` if unused.
|
||||
4. Drop unused `json:` (or other) entries under nested `import:`.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
+85
-175
@@ -4,121 +4,76 @@ description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
|
||||
building dynamic sites with ext/web, quantum circuits with ext/quantum,
|
||||
formula-first linear algebra with ext/linalg, or when the user mentions
|
||||
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
|
||||
or linalg/线性代数 extension.
|
||||
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
|
||||
sites with ext/web, quantum circuits with ext/quantum, or when the user
|
||||
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
|
||||
quantum/量子 extension.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
<!-- 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, **ext → R2+GitHub**, **CLI → Ubuntu PPA**): use [marqdo-release](../marqdo-release/SKILL.md) — detect versions, **ask for SemVer + mode (`full` / `cli` / `ext`)**, then follow that playbook. Ext-only releases are allowed. If sudo/GPG/PPA steps need the user, print the exact commands.
|
||||
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. **`**…**` = statement** (assign / call / expression). `*…*` = return. Closing markers touch the last token (no trailing space).
|
||||
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
|
||||
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
|
||||
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
|
||||
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 (assign / call / expression) |
|
||||
| `*…*` | Return |
|
||||
| `[描述](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. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
|
||||
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
|
||||
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
|
||||
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
|
||||
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
|
||||
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
|
||||
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
|
||||
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.
|
||||
|
||||
## 记不住语法细节?查 MLSP(AI 必读)
|
||||
|
||||
**不必背 Marqdo 语法细节**——语法可查、程序可验、修复有界。写码前后走**查询式**工作流:
|
||||
## Call one function
|
||||
|
||||
```bash
|
||||
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":2,"method":"locate","params":{"path":"a.mq.md","symbol":"加一"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":3,"method":"validate","params":{"path":"a.mq.md"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":4,"method":"schema","params":{"path":"a.mq.md","unit":"加一"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_mismatch","doc_anchor":"a.mq.md#L9-L15"}}' | marqdo mlsp
|
||||
```markdown
|
||||
# 计算器
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
```
|
||||
|
||||
| method | 何时用 |
|
||||
|--------|--------|
|
||||
| `syntax` | 不确定某个语法怎么写(关键字/别名 → 构造卡片:「返回」「表」「调用」「循环」…) |
|
||||
| `locate` | 找符号定义位置 + 契约;或反查构造卡片 |
|
||||
| `validate` | 提交前校验(结构化诊断数组;`ok:false` 就修) |
|
||||
| `schema` | 查单元契约(形参/返回/字段) |
|
||||
| `repair_targets` | 拿错误的**有界**修复靶点:只改锚点范围内行,越界必弃权(abstain) |
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
行分隔 JSON:每行请求 `{"id","method","params"}` → 每行响应 `{"id","ok","result"|"error"}`。
|
||||
语法唯一事实来源 = `doc/design/core-surface.md`(CI 守卫同步);卡片带 `manual` 指回文档行。
|
||||
所有错误诊断都是结构化 JSON:`code` / `severity` / `span` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`。
|
||||
|
||||
### 渐进式契约(可选标注;schema 就长在文档表里)
|
||||
|
||||
契约是**未绑定文档表**(绑定表是数据,永远不是契约)。三种形状、严格位置:
|
||||
|
||||
| 形状(须含 `类型` 列) | 允许位置 | 附着 |
|
||||
|--------------------------|----------|------|
|
||||
| `参数`/`类型`/`说明` 表 + `返回`/`类型`/`说明` 表 | 函数体首个可执行行之前 | 函数 |
|
||||
| `字段`/`类型`/`可空`/`说明` 表 | 紧邻 `` `名` = `` 绑定之前 | 集合(变量) |
|
||||
| `字段`/`类型`/`可空`/`说明` 表 | 对象(`#`)体首成员之前 | 对象类型 |
|
||||
|
||||
````text
|
||||
## 加一
|
||||
|
||||
对于输入变量`n`,期望是数字。
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| n | number | 输入值 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | number | 加一结果 |
|
||||
|
||||
*n+1*
|
||||
````
|
||||
|
||||
- 类型词汇:`text` / `number` / `bool` / `list` / `map` / `any` / `#` 对象名(拼错 ⇒ `contract.unknown_type` + 最近建议)。
|
||||
- 契约表**永不执行**、不污染升参推断;无契约文件行为逐字节不变(动态默认,零摩擦)。
|
||||
- 运行时只在四个边界校验:调用实参 / 字段访问 `[键](集合)` / 表绑定 / 返回。
|
||||
- `marqdo check [FILE] [--json]` 静态互查:契约行 vs 升参推断形参**双向**漂移(错行=Error;新升参未覆盖=Warning)、未知类型、错位契约;有 Error 非零退出。
|
||||
- 契约诊断带 `doc_anchor` + `doc_quote`(表原文)——修复只照锚点局部改。
|
||||
|
||||
## Markup → meaning (v0.3)
|
||||
|
||||
| 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) |
|
||||
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
|
||||
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
|
||||
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
|
||||
| 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`.
|
||||
prints `5`. The same command works on any `.mq.md`; the file does not need a special skill name.
|
||||
|
||||
## Minimal program
|
||||
|
||||
@@ -169,7 +124,7 @@ Chinese builtins (same functions, no import):
|
||||
```
|
||||
|
||||
```markdown
|
||||
**n = 0**
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -181,18 +136,19 @@ Chinese builtins (same functions, no import):
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
Imports use nested YAML `import:` (`导入:` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
import text:lib/text.mq.md
|
||||
import clock:lib/time.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
clock: lib/time.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**xs = > text.str_split s="a,b,c" sep=","**
|
||||
**xs = > text.split value="a,b,c" sep=","**
|
||||
> print text=`xs`
|
||||
**t = > clock.now_unix**
|
||||
```
|
||||
@@ -201,7 +157,7 @@ import clock:lib/time.mq.md
|
||||
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). **`ext/llm`** — intelligence primitive (`ask` / `stream` / `collect`; `complete` is compat); **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
@@ -217,60 +173,23 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
|
||||
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
|
||||
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
|
||||
4. **Skill Compilation (v2)** — successful runs become `.mq.md` episodes; after enough evidence, `maybe_learn` compiles an executable skill (`llm_free`). Prefer `## run` over bare `## plan` when you want learning.
|
||||
5. **Adaptive Routing (P4)** — router is abstract (`marqdo` / `small-llm` / `llm` / `auto`); `jev` is a compat alias of `small-llm`. Decision via `router_model` (any llm handle). Policy Compilation writes `policies/router.mq.md`.
|
||||
|
||||
APIs: `# agent` / `# 智能体` → `## run` / `## route` / `## step` / `## plan` (+ `resolve` / `record_episode` / `maybe_learn` / `compile` / `compile_policy` / `metrics`). Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
|
||||
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`).
|
||||
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) · v2: [doc/next/003.md](../../doc/next/003.md) · P4: [doc/next/004.md](../../doc/next/004.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/) · [agent-sandbox-okf](../../examples/agent-sandbox-okf/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · optimize O1–O5: [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
|
||||
**Sandbox (O1):** `import sandbox:ext/ai/sandbox.mq.md` · `agent.trial` / `智能体.试跑` · `run`/`step` take `sandbox=` / `沙盒=` (default `False`). Profile caps are tables via `sandbox.profile`. Gold: `tests/ext/agent-sandbox-optin.mq.md`.
|
||||
|
||||
## Official extension: `ext/web` (Document / Endpoint / Resource)
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin: `scripts/build-web-plugin.sh` / `marqdo ext add web`.
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifact.md](../../doc/design/ext-web-artifact.md).
|
||||
|
||||
**Constitution (ADR 0007 — do not degrade):**
|
||||
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
|
||||
|
||||
1. **Document / Endpoint / Resource** — `.mq.md` with `type: web|endpoint` (ZH `类型: 网页|端点`) is the site surface; not a Flask-style class pile.
|
||||
2. **Code is documentation** — the file is docs + route + handler.
|
||||
3. **Table = data** — View schema only `|type|slot|value|attrs|style|`. No `compose_*` dialects, no `json.set` glue.
|
||||
4. **Facade only** — `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect`. DB → `ext/data`; auth → `ext/security`; ws/http → `ext/net`.
|
||||
5. **No author `ensure_plugin` / `host_*`**; import web = capability (plugin auto-load).
|
||||
6. **Declared vs system routes**; `web.inspect` lists both. No silent user routes.
|
||||
|
||||
Import **one language** per file:
|
||||
|
||||
- EN: `import web:ext/web/web.mq.md` (+ `import data:ext/data/db.mq.md` as needed)
|
||||
- EN: `import web:ext/web/web.mq.md`
|
||||
- ZH: `导入 网页:ext/web/网页.mq.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: web
|
||||
route: /
|
||||
title: Hello
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# Hello
|
||||
|
||||
Executable document as a page.
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: endpoint
|
||||
method: POST
|
||||
path: /api/ping
|
||||
response: json
|
||||
---
|
||||
|
||||
*{"ok": true}*
|
||||
```
|
||||
|
||||
Site entry may `# main` → `web.serve root="."`. Client WASM: `ext/web/client.mq.md` / `lib/browser` — no author JS.
|
||||
|
||||
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · ADR [0007](../../doc/adr/0007-web-document-endpoint.md) · rule: `.cursor/rules/web-artifact-no-degrade.mdc` · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
|
||||
Web patterns: [examples.md](examples.md) · API index: [reference.md](reference.md).
|
||||
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
|
||||
## Official extension: `ext/quantum` (circuits + Q7/Q8)
|
||||
|
||||
@@ -290,35 +209,29 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
|
||||
|
||||
```markdown
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="probs" theme="light"*
|
||||
**_ = > `qc`.draw kind="circuit" theme="dark"**
|
||||
**_ = > `qc`.draw kind="probs" theme="light"**
|
||||
```
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
|
||||
## Official extension: `ext/linalg` (formula-first LA)
|
||||
## Foreign kernels (v1.5.0)
|
||||
|
||||
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
|
||||
`lib/foreign` is now a full foreign-kernel surface, not only `run`:
|
||||
|
||||
- EN: `import la:ext/linalg/linalg.mq.md`
|
||||
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
|
||||
|
||||
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
|
||||
|
||||
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
|
||||
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
|
||||
- `session_open` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`. JSON integers outside \(\pm(2^{53}-1)\) are refused (`json: integer outside V_safe`); use a decimal string + host `BigInt` for wider ints (`doc/design/v-safe-json.md`).
|
||||
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
|
||||
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. **查再写**:不确定语法就 `marqdo mlsp`(`syntax` / `locate`)——不必背语法细节。
|
||||
2. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
3. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
4. 可选:给函数/集合写**渐进式契约**(上节三种表格形状;写全或不写,别写一半)。
|
||||
5. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
6. On errors:结构化诊断(含 `doc_anchor` / `suggestion`)→ `repair_targets` 取有界靶点,**只改锚点范围内**的行。
|
||||
7. 提交前:`marqdo check path/to/file.mq.md`(或 `mlsp validate`)清到零 Error。
|
||||
8. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
4. On `path:line:col: message`, fix that span; re-run until exit 0.
|
||||
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
|
||||
## Anti-patterns (common model mistakes)
|
||||
|
||||
@@ -328,8 +241,8 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `**a = 1**` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (italic is return, and bare text args) | `**xs = > text.split value="a,b" sep=","**` — statement; quote text literals |
|
||||
| Forgetting empty return after nested `##` helper when outer continues | Add `*None*` / `**` / `****` (not `---`) |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
@@ -339,8 +252,7 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
|
||||
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
|
||||
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
|
||||
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
|
||||
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
|
||||
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
|
||||
|
||||
@@ -357,5 +269,3 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
- [ ] Browser client: `lib/browser` + tables when returning effects
|
||||
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
- [ ] 语法拿不准的地方已查 MLSP(`syntax`/`locate`),而不是凭记忆发明
|
||||
- [ ] 契约(如有)与升参一致:`marqdo check` 零 Error
|
||||
@@ -141,7 +141,8 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
|
||||
|
||||
```markdown
|
||||
---
|
||||
import browser:lib/browser.mq.md
|
||||
import:
|
||||
browser: lib/browser.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -162,12 +163,64 @@ import browser:lib/browser.mq.md
|
||||
|
||||
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
|
||||
|
||||
## 6e. Agent / LLM result maps — GFM first (positive)
|
||||
|
||||
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
## step_ok
|
||||
+ `task`
|
||||
+ `reply`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | result |
|
||||
|--------|------|--------|
|
||||
| ok | `task` | `reply` |
|
||||
|
||||
*out*
|
||||
|
||||
## step_err
|
||||
+ `task`
|
||||
+ `err`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | error |
|
||||
|--------|------|-------|
|
||||
| error | `task` | `err` |
|
||||
|
||||
*out*
|
||||
|
||||
## soft_http_pack
|
||||
+ `msg`
|
||||
+ `usage0`
|
||||
|
||||
**empty_tc = > table.empty_list**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: split demo
|
||||
import text:lib/text.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -180,8 +233,9 @@ import text:lib/text.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import re:lib/re.mq.md
|
||||
import enc:lib/encoding.mq.md
|
||||
import:
|
||||
re: lib/re.mq.md
|
||||
enc: lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -196,8 +250,9 @@ import enc:lib/encoding.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import log:lib/log.mq.md
|
||||
import uuid:lib/uuid.mq.md
|
||||
import:
|
||||
log: lib/log.mq.md
|
||||
uuid: lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -228,7 +283,8 @@ After a blank line, code runs:
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
import math:lib/math.mq.md
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -276,7 +332,8 @@ See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` const
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/agent.mq.md
|
||||
import:
|
||||
agent: ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -328,8 +385,9 @@ if x > 0:
|
||||
```markdown
|
||||
---
|
||||
title: hello-site
|
||||
import web:ext/web/web.mq.md
|
||||
import db:db/index.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
db: db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -366,7 +424,8 @@ import db:db/index.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -395,7 +454,8 @@ import quantum:ext/quantum/quantum.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -122,7 +122,8 @@ Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -141,7 +142,8 @@ Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only
|
||||
|
||||
```markdown
|
||||
---
|
||||
import foreign:lib/foreign.mq.md
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
name: executable-knowledge
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
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: Isolated execute MR-01 (dual 60s SSE + short reads)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
bash scripts/build-web-plugin.sh
|
||||
cargo test --test isolated_execute_mr01 --locked -- --nocapture
|
||||
timeout-minutes: 5
|
||||
- name: no ignored tests counted as success
|
||||
run: |
|
||||
if grep -n '#\[ignore\]' tests/executable_knowledge.rs; then
|
||||
echo "executable_knowledge must not use #[ignore] as success evidence" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "ok: no #[ignore] in executable_knowledge gate"
|
||||
@@ -126,14 +126,50 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v2.2.2**:\(V_{\mathsf{safe}}\) JSON 整数——外联/`json` 拒绝域外整数,禁止静默扭曲;宽整数用十进制字符串
|
||||
- **v2.2.2**: \(V_{\mathsf{safe}}\) JSON integers — foreign/`json` refuse OOD ints (no silent distortion); wide ints via decimal strings
|
||||
- **v2.2.2 ext**:扩展包同步 2.2.2 / Ext pack 2.2.2
|
||||
- **v2.2.1**:view / 静态导出——修复 occlusion 与中等宽度下大纲侧栏掉到正文下方
|
||||
- **v2.2.1**: view / static export — fix outline rail nested under document (occlusion + mid-width layout)
|
||||
- **v2.2.1 ext**:扩展包同步 2.2.1 / Ext pack 2.2.1
|
||||
- **v2.2.0**:函数级调用 `marqdo call`——同一份 .mq.md 就是文档、知识和工具;Tree/Bytecode 执行被点名的函数;外部调用默认只跑纯函数
|
||||
- **v2.2.0**: `marqdo call` runs one function in any .mq.md — the file is the document, the knowledge and the tool; Tree and Bytecode execute that function; external calls stay pure
|
||||
- **v2.2.0 ext**:扩展包同步 2.2.0 / Ext pack 2.2.0
|
||||
- **v2.1.5**:Agent 可靠工作台——ResourceView / ToolSpec / CheckpointV2 / EffectLedger · EKC ir.json 暖机 · Web 短读槽隔离
|
||||
- **v2.1.5**: Agent reliability workbench — ResourceView / ToolSpec / CheckpointV2 / EffectLedger, EKC ir.json warm-load, web short/read lane isolation
|
||||
- **v2.1.5 ext**:扩展包同步 2.1.5 / Ext pack 2.1.5
|
||||
- **v2.1.4**:默认隔离 HTTP execute(ADR 0009)——worker 池 / `--call-lib-path` · `/_runtime/*` · MR-01 双流金样例 · `runtime.isolated_execution=1`
|
||||
- **v2.1.4**: Default isolated HTTP execute (ADR 0009) — worker pool / `--call-lib-path`, `/_runtime/*`, MR-01 dual-stream gold, `runtime.isolated_execution=1`
|
||||
- **v2.1.3**:知识工作台运行时——ModelSelection/RunContext/usage · view document 只读嵌入 · LLM selection/messages/cancel · agent selection e2e
|
||||
- **v2.1.3**: Workbench runtime — ModelSelection/RunContext/usage, view document read-only embed, LLM selection/messages/cancel, agent selection e2e
|
||||
- **v2.1.1**:可执行知识主链——BoundCall · NarrativeRef · 来源/适用期 · patch/extract · 整代 CURRENT + closure · 发票示例 113
|
||||
- **v2.1.1**: Executable-knowledge spine — BoundCall, NarrativeRef, sources, patch/extract, generation CURRENT + closure, invoice example 113
|
||||
- **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
|
||||
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
|
||||
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
|
||||
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
|
||||
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
|
||||
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
|
||||
- **v1.4.6**:裸自增升参——首次粗体赋值左值即声明;`n = n + 1` 无反引号也是必选形参
|
||||
- **v1.4.6**: Bare self-increment is a required parameter — first bold assignment LHS is a declaration
|
||||
- **v1.4.5**:Streamable HTTP MCP + web invoke Bearer/401 · openai/agent json.get 硬化
|
||||
- **v1.4.5**: Streamable HTTP MCP + web invoke Bearer/401; openai/agent json.get hardening
|
||||
- **v1.4.2**:Agent/LLM 优化 O1–O5——sandbox trial · promote proof · step_route/EFI/cost · lint · quarantine
|
||||
- **v1.4.2**: Agent/LLM optimize O1–O5 — sandbox trial, promote proof, step_route/EFI/cost, lint, quarantine
|
||||
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
|
||||
- **v1.4.1**: View annot leaders — SVG mid→mid (mark bottom-center → chip top-center), frame chip id unify, L→R density
|
||||
- **v1.4.0**:叙述统一——`% marqdo: var=` · 臂/循环体叙述 · foreach 中英糖 · 图片自写回 · view 推断形参
|
||||
- **v1.4.0**: Prose-unified control flow — formula meta bind, arm/loop narrative, foreach sugar, image writeback, inferred-param view
|
||||
- **v1.3.3**:view 文档面 Structure——叙述保真 · 标记面 · 调用/循环帧 · `#mq-view-trace` · 静态站同源
|
||||
- **v1.3.3**: Browse document-surface Structure — narration, markers, call/loop frames, `#mq-view-trace`, static site parity
|
||||
- **v1.3.0**:Engineering Knowledge Compiler——L0–L4 · `reuse`/`find`/`duplicate` · Agent preflight(REUSE→ADAPT→CREATE)
|
||||
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
|
||||
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
|
||||
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
|
||||
- **v1.1.1**:AI 栈收口——llm `ask`/`stream`/`collect` · Metadata Binding · Skill Compilation + Adaptive Routing · MCP 客户端 + resume · 可选 `plugins/llm`
|
||||
- **v1.1.1**: AI stack — llm ask/stream/collect, Metadata Binding, Skill Compilation + Adaptive Routing, MCP client + resume, optional plugins/llm
|
||||
- **v1.0.7**:WS/网络边界加固;`url_encode` `%20`
|
||||
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com)
|
||||
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-ai-optimize](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/ext-ai-optimize.md)
|
||||
|
||||
### Downloads
|
||||
|
||||
|
||||
+17
@@ -71,6 +71,16 @@ plugins/*/tmp/
|
||||
/examples/linalg-*/**/*.svg
|
||||
/examples/linalg-*/*.svg
|
||||
/examples/linalg-*.svg
|
||||
# oa2026 showcase: SVGs beside the examples ARE tracked; root-level ones are
|
||||
# run artifacts (draw/plot write to cwd when the example is run from root)
|
||||
/bell-*.svg
|
||||
/calculus-*.svg
|
||||
|
||||
# Plot SVGs emitted beside tests / notebooks when demos run
|
||||
/tests/**/*-plot-*.svg
|
||||
|
||||
# PLDI / thesis harness scratch must never land in this tree
|
||||
.lx*-tmp/
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
@@ -87,3 +97,10 @@ tests/ext/:memory:
|
||||
|
||||
# local secrets
|
||||
.env
|
||||
|
||||
# sandbox gold leftovers
|
||||
tests/ext/_sbx_cow/
|
||||
|
||||
tests/ext/_sbx_*/
|
||||
examples/**/_example_sbx/
|
||||
.secrets/
|
||||
+682
@@ -8,6 +8,688 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v2.2.2 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**\(V_{\mathsf{safe}}\) JSON 整数契约落地**:外联 / `json.parse` / `json.stringify` / `session_set` 等共用映射对齐 Lean ForeignJSON——`|n| > 2^{53}-1` 的 JSON 整数显式拒绝(错误前缀 `json: integer outside V_safe`),禁止 Node 路径静默扭曲;宽整数仍用十进制字符串 + 对端 `BigInt`。CLI · wasm · ext **2.2.2**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——宿主 JSON 契约与测试,不改 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`doc/design/v-safe-json.md`**:宿主 ↔ Lean \(V_{\mathsf{safe}}\) 契约锁定(`MAX_SAFE`、encode/decode refuse、嵌套、float 为宿主扩展)。
|
||||
- **回归**:`tests/lib/json-vsafe-*`、`foreign-vsafe-*`、`foreign-session-vsafe-refuse`(含算术后越界 refuse)。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`src/host/json.rs`**:对域外整数与 `u64 > i64::MAX` 显式失败;不再经 `f64`/`Text` 静默降级。
|
||||
- **`doc/design/foreign-kernel.md`**:Int→number 仅当 `|n| ≤ 2^{53}-1`;宽整数走 string 桥。
|
||||
|
||||
### Changed
|
||||
|
||||
- 外联 JSON 桥与 `lib/json` 行为:OOD 整数从「可能静默失真」改为「诊断失败」。
|
||||
|
||||
## v2.2.1 — 2026-10-30
|
||||
|
||||
### Highlights
|
||||
|
||||
**view / 静态导出大纲侧栏修复**:带遮蔽(occlusion)语句的文档页里,Functions / Variables 右侧栏会掉到正文下面;中等窗口宽度下也会被错误叠成单列。CLI · wasm · ext **2.2.1**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——布局与 HTML 闭合修复,不改 Markdown 标记。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`marqdo view` / `view output`**:occlusion 行提前返回时未关闭 `.doc-block`,把 `#outline-rail` 嵌进 `document-surface`,侧栏排到文档下方;现已闭合并保留标注带。
|
||||
- **view 壳 CSS**:大纲折叠改为按主栏 `@container mq-panel` 宽度(32rem),不再用视口 `960px` 媒体查询把右侧栏压到正文下;极窄时大纲上移到文档上方。
|
||||
|
||||
## v2.2.0 — 2026-10-30
|
||||
|
||||
### Highlights
|
||||
|
||||
**函数级调用 `marqdo call`**:同一份 `.mq.md` 已经是文档、知识和程序。这一版补上从外部调用其中某个函数的入口。人继续读这一页;开发者、测试和 Agent 用同一条命令传入参数并执行。知识复用、把函数当工具、逐个函数做测试、改完再跑,都是这一入口的用法,不是另一套 Skill 系统。CLI · wasm · ext **2.2.0**。
|
||||
|
||||
```bash
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
# 5
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
|
||||
```
|
||||
|
||||
**作用**:最小可执行单位从「整份文件」扩展到「文件里的一个函数」。不必为了试一个函数再写 `# main`、打印和包装程序。
|
||||
|
||||
**价值**:说明和实现仍在同一页。Agent 读函数旁边的叙述,定位函数,传入参数,得到可检查的结果。正式发布和权限仍走已有的项目验证;`call` 默认不开放写文件、进程、网络和插件。
|
||||
|
||||
说明页:[public/features/22-函数调用.mq.md](public/features/22-函数调用.mq.md) · [public/features/22-call.mq.md](public/features/22-call.mq.md)
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——新增的是 CLI 入口,不新增 Markdown 标记。`**…**` 仍是语句,`*…*` 仍是返回。
|
||||
|
||||
### Added
|
||||
|
||||
- **`marqdo call <文件.mq.md> <函数> [名字=值 ...]`**:加载该文件及其 import,按显示路径、SymbolId 或唯一短名定位函数,用现有签名和契约绑定参数,再用现有运行时执行。
|
||||
- **`--json`**:成功 `{"ok":true,"result":...}`,失败 `{"ok":false,"error":...}`,错误带诊断 `code`。`--backend tree|bytecode` 与 `marqdo run` 相同;指定函数时两个后端都不会改去跑 `# main`。
|
||||
- **默认纯函数**:效应含写入、网络、进程或插件时,执行前返回 `artifact.effect_denied`,副作用不会发生。
|
||||
- **参照文档** `examples/calculator.mq.md`,以及用户说明页 `public/features/22-*`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 官方语法说明与 Agent 语法卡的标记极性与解析器对齐:粗体是语句,斜体是返回。同步测试会实际运行说明里的调用示例。
|
||||
- Bytecode 的 `marqdo run --call-lib-path` 执行被点名的导入函数,不再忽略该参数去跑入口。
|
||||
- 隔离运行时冒烟测试补上 `InvokeContext.fs_root`,`--tests` 可以编过。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.2.0**。扩展包版本号对齐;这一版的新能力在 CLI。
|
||||
|
||||
## v2.1.5 — 2026-10-27
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent 可靠工作台 + EKC 热路径**:ResourceView(JSON/CSV/PDF/image `blob_ref`、locator 页/行)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制面与 execute 槽隔离。CLI · wasm · ext **2.1.5**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.5 && cargo build --release
|
||||
marqdo ext add web # CDN / Releases → 2.1.5
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台协议与 Agent 运行时合同,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **ResourceView v1**:有界 JSON/CSV 渲染;PDF/image `blob_ref`;`locator.page` / 行定位;CSV `text` 供 TablePreview。
|
||||
- **Agent 合同**:ToolSpec 注册与 authorize-before-call;CheckpointV2 原子 resume;AgentErrorV1;输出通道;ContextPackV2;EffectLedger(含 mutating `run_tool` 水印)。
|
||||
- **Workbench fixtures/schemas**:`tests/workbench_contracts` 协议金样例。
|
||||
- **EKC `ir.json` 快照**:`marqdo knowledge` 写入 `.marqdo/ekc/graph/ir.json`;查询命令暖机热加载,免全量重编译。
|
||||
- **`--refresh`**:`knowledge preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify` 可强制重编译。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **工程预检热路径**:`knowledge preflight`(及 find/reuse 等)默认不再每次 `ensure_compiled` 全量 compile,修复聊天「工程预检」墙钟过长。
|
||||
- **Web 槽隔离**:`short`/`read`/`control` 不再填满 execute 槽;disconnect≠cancel。
|
||||
- **CSV ResourceView**:去掉尾部空行伪影。
|
||||
|
||||
### Changed
|
||||
|
||||
- 查询类 knowledge CLI:**缺投影才 compile**;CI / 源变更请先 `marqdo knowledge` 或 `--refresh`。
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.5**。
|
||||
|
||||
## v2.1.4 — 2026-10-26
|
||||
|
||||
### Highlights
|
||||
|
||||
**默认隔离 HTTP execute(ADR 0009)**:`class=execute` / `sse-live` / `stream:true` 经 Supervisor worker 池(`marqdo run --call-lib-path`),父进程不再 `CallLibPath` 占 `INVOKE_LOCK`;短读 / 未声明非流式仍 `legacy_serial`(ADR 0008)。`/_runtime/*` 控制面;`runtime.isolated_execution=1`;MR-01 双 60s 假 SSE + 短读金样例。CLI · wasm · ext **2.1.4**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.4 && cargo build --release
|
||||
marqdo ext add web # CDN / Releases → 2.1.4
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——隔离运行时与 Web execute 路径,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **默认隔离 execute(ADR 0009)**:HTTP `execute` / `sse-live` / `stream:true` 经 Supervisor worker 池(`marqdo run --call-lib-path`),父进程不再 `CallLibPath` 占 `INVOKE_LOCK`;可选 route `class`;`/_runtime/*` 控制面;`runtime.isolated_execution=1`。
|
||||
- **MR-01 金样例**:`tests/isolated_execute_mr01.rs` + `tests/ext/isolated-execute-site/`(双 60s 假 SSE + 短读并行;槽满拒绝);接入 `executable-knowledge` workflow。
|
||||
- **Worker CLI**:`marqdo run --call-lib-path` / `--fs-root` / `--args-json` / `--emit-result`;host `runtime` admit/dispatch/cancel/events。
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
- **compile 1000 门禁**:executable-knowledge / workbench 路径恢复与能力探测诚实(isolated 默认开启)。
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.4**。
|
||||
|
||||
## 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
|
||||
|
||||
**遮蔽语法(Occlusion)落地**:`[描述](实现)` —— 方括号是给人读的描述(**永不执行**),圆括号是**唯一执行体**。配套 `()` 内调用、`access` 取元、`遍历` 遮蔽循环、`labels` 两级检索与债务棘轮、`migrate labels` 迁移;`view` 把描述渲染为正文、实现渲染为代码片、空载荷给「桩」徽章。全仓 **80 个语料文件 / 256 处取元 / 23 处循环** 已迁移(M7),语义零漂移。
|
||||
|
||||
```bash
|
||||
git checkout v2.0.0 && cargo build --release
|
||||
marqdo ext add web # CDN → 2.0.0
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)—— 遮蔽是既有 `[键](集合)` 与 `- [项](集合)` 形状在 `markup: occlusion` 文件中的**第二种读法**,默认 `classic` 语义不变;`access` 是宿主函数(id 212),不是新标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **M2 遮蔽语法**:`[描述](实现)`;`[]` 为自由文本、永不执行,`()` 为唯一执行体;支持嵌套;空载荷 `()` 值为 `None`(桩)。frontmatter `markup: occlusion` 按文件启用,`MARQDO_MARKUP=occlusion` 可作进程默认。
|
||||
- **M1 `()` 内调用**:`加(1)` / `加(1, 2)` / `加(加(1 2), 10)` / `加一 号(31)`(callee 可含空格,解决 D8)/ `txt.str_trim(" x ")`;`)` 是参数终止符,逗号可选,支持嵌套;括号形参数按表达式解析,空格形(`> f k=v`)仍按文本。
|
||||
- **M3 `access` 与遮蔽循环**:新增宿主函数 `access(集合, 键)`(别名 `取` / `取值`),与旧取元逐字等价;`- [描述](遍历 集合 为 变量)` 遮蔽循环,接受 `遍历`/`for` 与 `为`/`as`/`in`。
|
||||
- **M2.5 / M4 遮蔽诊断**:`label.missing`(空描述,error)、`label.empty_payload`(空载荷,warning)、`label.ref_dangling`(描述里的反引号实体不可解析,error);由 `marqdo check` 一并输出。
|
||||
- **M5 隐式遮蔽**:`marqdo check --implicit-labels` 把 `>` 调用上方的叙述当作描述(默认关闭,不改变既有输出)。
|
||||
- **M6 T1 会话内陈旧检测**:MLSP `repair_apply` 前后对照 payload 并返回变更的遮蔽点;新增 `session.summary` 会话末一次性汇总。
|
||||
- **M7 迁移与版本门**:frontmatter `markup:` 按文件切换解析模式(同进程可混载 classic / occlusion,imports 亦然);`marqdo migrate labels`(多路径、`--write`、`--json`)把 `[键](集合)` 改写为 `[键](access(集合, "键"))`、`- [项](集合)` 改写为遍历形。
|
||||
- **M8 债务棘轮与呈现**:`marqdo labels --baseline FILE` 记欠据、`--fail-on-increase` 只许降不许升;`view` 浏览 / 卡片 / 静态导出一致呈现遮蔽:描述为正文、实现为代码片、空载荷「桩」徽章。
|
||||
- **M9 两级词表检索**:`marqdo labels`(默认 `pending` 口径 / `--grep` 自定义词 / `--group` / `--also-builtin` / `--count` / `--json`,支持多路径);MLSP `labels.search`;兼容文档写法 `labels pending` / `labels search`。
|
||||
- **M10 工程化落点**:`ext/ai` 提示词加入「接不了就申报」;README「工程习惯」;空载荷一律 warning。
|
||||
- **示例与教程**:`examples/syntax-tour` 一页跑通全部现行语法;`examples/oa2026-showcase`;`doc/tutorial/15-常见陷阱.md`(D1–D10 实测)。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **D9 未闭合引号**:不再静默吞掉后续行——分类层与解析层双层修复,直接报错并给出原始行。
|
||||
- **`加(31)`**:曾被解析成 `unknown function 加(31`(末个位置实参吞掉 `)`)。
|
||||
- **view 解析模式回归**:带 `markup: occlusion` 的文档在 `view` 结构区报 `expected ')' after link-index collection`;新增 `load::parse_source_auto` 统一五处解析点。
|
||||
|
||||
### Changed
|
||||
|
||||
- **HostFn 单表**:五张分派表合一为 `HOST_FN_TABLE`(`src/host/dispatch.rs` **−404 行**),203 项逐字节一致,行为零变化。
|
||||
- **插件 ABI 共享 crate**:新增 `marqdo-plugin-sdk`,5 个原生插件共用同一份 ABI 前言;**ABI 不变**(`include/marqdo_abi.h` / 符号与布局不变)。
|
||||
- **精简**:删除归档的 Rust web 插件 `plugins/web-rust-archive/`(14,235 行,非 workspace 成员,已由 Go `libweb` 取代);删除无调用点死代码,收拢 `as_text` 18 处重复、catalog 助手与 view 路由 34 臂,AST 遍历器合流。
|
||||
- **语料迁移(M7)**:`public/` `ext/` `tests/` `examples/` `doc/` 等语料加 `markup: occlusion`,改写 **80 个语料文件 / 256 处取元 / 23 处循环**;新增 `tests/ratchet` 锁定标签债务。
|
||||
- **文档**:遮蔽语法总纲 + M0–M10 变更记录、标签新鲜度 / 修复回路、函数作为值 6 篇评估、代码体量审计;`doc/design/code-volume-audit.md` 记 53k 行构成。
|
||||
|
||||
## v2.1.0 — 2026-10-23
|
||||
|
||||
### Highlights
|
||||
|
||||
**文件级可执行知识语义**:标准库、扩展库、示例与公开文档全部采用显式 `markup: occlusion`;`[描述](实现)` 成为默认链接语义,`access` 与 `遍历` 承担原有取元与循环职责。迁移工具可离线证明语法形状等价,Tree 与 Bytecode 均完成全量回归。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.0 && cargo build --release
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
**核心表面 Δ**:默认链接语义从 Classic 切换到 Occlusion。未迁移的旧 `[键](集合)` 仅可用 `markup: classic` 或一个版本周期内的 `marqdo run --legacy-markup` / `check --legacy-markup` 执行。
|
||||
|
||||
### Added
|
||||
|
||||
- **文件级新语义迁移**:`marqdo migrate labels --mark` 可把整个库/目录迁移到显式 `markup: occlusion`,即使文件没有旧式索引也不再依赖进程默认值。迁移验证为语法级、无导入解析依赖,并在写入前比较 Classic 与 Occlusion AST 形状。
|
||||
- **显式过渡入口**:`marqdo run --legacy-markup` 与 `marqdo check --legacy-markup` 可在一个版本周期内审阅未迁移的旧文件;环境变量不再改变语法。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 标准库、扩展库、示例、公开文档与可解析测试夹具迁移为文件级 Occlusion;旧的 `[键](集合)` 和 `- [项](集合)` 分别改为 `access` 与 `遍历`。
|
||||
|
||||
### Changed
|
||||
|
||||
- 未标注源码默认采用 Occlusion。Classic 仅能通过明确的 frontmatter 或 `--legacy-markup` 进入,避免同一文档因进程配置而静默改变含义。
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### 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
|
||||
|
||||
**可执行知识主链落地(S0–S6)**:BoundCall 双后端共享解析、正文 NarrativeRef、来源/适用期、digest 保护补丁与纯表达式提取、整代 `CURRENT` 投影与闭包摘要;订单发票示例双后端输出 `113`;离线门禁含 100 单元语料与 CLI 冒烟。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.1 && cargo build --release
|
||||
marqdo ext add web
|
||||
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md
|
||||
```
|
||||
|
||||
**核心表面 Δ**:**无增删关键词**——同模块 `Type.member` 纳入 BoundCall;语义投影新增 `bound_calls` / `dynamic_calls` / `hashes.closure` / NarrativeRef 步骤;不改变默认 Occlusion 链接读法。
|
||||
|
||||
### Added
|
||||
|
||||
- **BoundCall / DynamicCall**:`sema::bind::resolve_for_exec`;Tree 与 Bytecode 静态路径对齐;`bound_calls.json` / `dynamic_calls.json`;同模块定义树路径绑定。
|
||||
- **NarrativeRef**:注释行 Markdown 链接 → `narrate` / `navigation` 步骤;围栏与行内代码不计步骤。
|
||||
- **来源与适用性**:frontmatter `sources` / `valid_until` → `evidence=sourced|expired|missing_source`;`artifact.bind policy=business`。
|
||||
- **局部编辑与提取**:MLSP `artifact.patch`(digest + wording 回滚);`artifact.extract_pure` 纯表达式预览。
|
||||
- **整代与闭包**:`generations/<id>/` + `CURRENT`;`hashes.closure` 随依赖变化;锁报告 `classes`。
|
||||
- **门禁**:`tests/executable_knowledge`(含 100 单元);CI `.github/workflows/executable-knowledge.yml`;项目扫描 depth/size/count 上限。
|
||||
- **示例**:`examples/executable-knowledge` 发票含税链可运行;负知识文档。
|
||||
|
||||
### Fixed
|
||||
|
||||
- Bytecode 裸名解析不再跨 import scope 误连同名函数;同模块 `Type.member` 写入 path_index 供兄弟调用。
|
||||
|
||||
### Changed
|
||||
|
||||
- Agent / reuse 发现结果标记 `discovery_only` + `bind_required` / `bind_targets`,不可把打分结果直接当可执行目标。
|
||||
|
||||
## v1.5.2 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**外联 v3 P0/P1**:session eval 支持 raw stdin(Python/Node 持久内核);每 cell 独立 stdin 与 Interrupt;plan generation/add/remove/value API;snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获实时快照;显式 Persist 按钮。CLI · wasm · ext **1.5.2**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.2 && cargo build --release
|
||||
marqdo ext add web # CDN → 1.5.2
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v3 扩展 `lib/foreign` 库 API;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **raw stdin + 每 cell 输入**:session eval 支持 raw stdin;`foreign.session inputs=` 每 cell 独立 stdin;view 增加每卡 stdin 字段与 Interrupt 按钮。
|
||||
- **plan API**:plan generation/add/remove/value;运行时 plan 更新与 generation。
|
||||
- **snapshot**:snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获 live 快照用于静态导出。
|
||||
- **显式 Persist**:Persist 按钮 + `/api/session/cell/persist`。
|
||||
- **嵌套 plan 边界**:显式 persist 与嵌套 plan 边界;foreign 拒绝嵌套 view plans。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`session_list` arity**:保持空 arity。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.5.2**。
|
||||
|
||||
## v1.5.1 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 静态/动态统一 + 外联值传递**:静态导出与 live view 共用同一套 `foreign_doc` 执行路径;构建时实际运行代码单元并注入 stdout;`foreign.session` 可把 Marqdo 值传入多内核会话;cell stdin 支持 live/static/持久内核三种模式。CLI · wasm · ext **1.5.1**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.1 && cargo build --release
|
||||
marqdo ext add web # CDN → 1.5.1
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——view 执行路径统一 + 外联值传递;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **外联值传递**:`foreign.session kernels= cells=` 可把 Marqdo 值传入多内核 view 会话;`view` 只消费 `会话` 绑定,不再识别 `内核表` / `会话表` 保留名。
|
||||
- **Cell stdin**:view 增加 `Cell stdin / input` 输入框;Run/Step/Run All 都会传给外联 cells;无状态 cell 使用 raw stdin,持久内核使用 `marqdo_input`;静态导出使用 frontmatter `stdin` 作为构建时输入。
|
||||
- **静态导出真实执行**:构建时实际执行代码单元并把 stdout/stderr 注入代码卡;静态示例通过代码 fallback 或 frontmatter `stdin` 提供输入。
|
||||
- **可运行外联写回示例**:新增 `examples/foreign-writeback/index.mq.md`,用 `foreign.run` + `writeback.record` 将结果写入 `.mq.md` 的 keyed 槽位。
|
||||
- **写回块分组与主题**:view 对写回块按目标分组并统一主题样式。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **code 卡控制恢复**:恢复每个代码卡的内核切换下拉与 Clean 按钮;Clean 清除单个 cell 输出/记录,不重启内核。
|
||||
- **导入函数返回锚定**:导入函数的返回值锚定在调用位置。
|
||||
- **静态导出自包含**:静态示例不再依赖空 stdin 或外部内核状态。
|
||||
- **Execution 输出清除**:view 清除 Execution 输出从 view 表面。
|
||||
- **文档表不再变 call chips**:view 不再把文档表转为 call chips。
|
||||
- **写回表标签**:写回表标签保持为行内代码。
|
||||
|
||||
### Changed
|
||||
|
||||
- **静态/动态统一执行路径**:static 与 live cells 使用同一 `foreign_doc` `run_all` 路径;移除 `In []` / `Out []` 与 Notebook 品牌。
|
||||
- **静态按钮行为**:静态页面执行按钮点击显示"静态页面无法真实执行",不伪造成功。
|
||||
- **低层会话评估可见**:文档展示低层 session evaluation 为代码围栏。
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.5.1**。
|
||||
|
||||
## v1.5.0 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**外联 v2 / 文档原生 Notebook**:`lib/foreign` 从“运行一段代码”升级为完整外联内核:结构化 `invoke` 记录、JSON 进出的 `call` / `call_many`、并行扇出、Python/Node 持久内核、显式状态桥,以及用绑定表声明的 Notebook 单元。`view` 增加 cell 单步、Run All、内核切换、journal、状态面板、浅/深主题与可调高度代码区;高对比度 token 修复了代码和 STRUCTURE 文字与背景区分度不足的问题。CLI · wasm · ext **1.5.0**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.0 && cargo build --release
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v2 只扩展 `lib/foreign` 的库 API;Notebook 的 `内核表` / `会话表` 是既有绑定表;没有新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-view-cells` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
|
||||
- **`lib/foreign` F0/F1**:`invoke` 结构化记录(`ok`/`code`/`stdout`/`stderr`/`ms`/`timed_out`/`truncated`/`result`);`run`/`run_lang` 新增 `env`/`cwd`/`timeout`/`args`/`max_output`;15 个语言预设;`probe`/`register`/`unset`/`load_config`;`.marqdo/foreign.toml`。
|
||||
- **`lib/foreign` F2**:JSON 进 / JSON 出 `call`;并行 `run_many` / `call_many`(有序、单项隔离、并发上限);`invoke` 的 `input` / `output` / `result` / `result_error`。
|
||||
- **`lib/foreign` F3/F3.5**:Python / Node 持久会话 `session_open` / `session_eval` / `session_close` / `session_list`;状态桥 `session_set` / `session_get` / `session_names`;会话超时即杀、崩溃隔离、drop 清理。
|
||||
- **Notebook D1/D2**:`内核表` / `会话表` 文档原生语法;`DocumentSession`(cell index / 命名内核 / journal / value store);view Notebook 工具栏(Run All / Restart & Run All / Step / State / Journal / Reload)、状态徽标、内核下拉、Push/Pull 状态表单;`POST /api/session/*`。
|
||||
- **Notebook D3**:`reload` 重新解析并保留内核,源码变更的 cell 标为 `dirty`;Journal/Reload/Debug 按钮;Debug 打开同一 view 服务的语句级单步页(`/debug` + `/api/debug/*`);状态桥 Push/Pull。
|
||||
- **安全与健壮性**:所有外联入口检查 `exec` 能力;有界 stdout/stderr 读取与截断标记;stdin 写线程;Unix 进程组 / Windows `taskkill /T` 超时清理;shell-like argv 切分。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **view 文档表面与标注 chip**:把旧 view 的 `--ink` / `--fill` / `--line` 等 token 映射到当前主题,修复 STRUCTURE 中 `main`、`内核表 =`、函数名和 annot-chip 深色文字/白色卡片与暗色背景不一致的问题。
|
||||
- **view 代码对比度**:移除会互相覆盖的 highlight.js 深/浅两套外链样式,改用内置高对比 token 变量;深色代码正文 `#f0f0f0` on `#1e1e1e`(14.6:1),浅色 `#24292f` on `#f6f8fa`(13.8:1);关键词/字符串/注释均使用可读的对比色。
|
||||
- **view 反向代理兼容**:Notebook / Debug 的 API 与 Debug URL 改为相对路径,可在 `/marqdo-view/...` 路径前缀下工作,便于 Docker 内通过 DSH 同源预览。
|
||||
- **分支内共同局部变量**:if/else 各臂都赋值的局部变量不再被误提升为必选形参;修复 `# llm` 构造器无端要求 `key`,恢复 agent/llm/ext 全量测试。新增 `branch_else_common_local_is_not_a_param` 回归测试。
|
||||
- **外联临时脚本路径**:入口目录为相对路径时,脚本参数现在使用绝对路径,避免 `tests/lib/tests/lib/...` 双拼接。
|
||||
- **外联失败可观测**:解释器不存在时进入 `invoke` 记录,`run` 仍报错;view 显示 stderr / exit / ms。
|
||||
|
||||
### Changed
|
||||
|
||||
- **Notebook view 视觉重做**:采用 VS Code Dark 的扁平色板与 Jupyter 的 cell 组织:单一深色底、明确 surface/border 层级、`In [n]` / `Out [ ]` 提示、顶部 cell 工具栏、无渐变/无重阴影、暗色代码区与一致的字号/间距;保留并统一原始左侧文件导航、右侧 Functions/Variables 栏与 Execution/Source 区块;支持深色/浅色主题切换(localStorage 记忆)与代码区、输出区纵向拖拽调整高度。
|
||||
- **`langs`** 现在返回「预设 ∪ 注册 ∪ 配置」的已知语言(原集合是子集)。
|
||||
- 大输出从 `Err` 改为「截断 + `truncated=true`」;`subtask` 外联输出同步采用该语义。
|
||||
|
||||
## v1.4.6 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**裸自增升参**:粗体首次赋值的左值按设计 §8.2 视为声明。`**n = n + 1**` 在没有反引号提及时也会把 `n` 升成必选形参;缺参报 `missing argument for parameter`,不再是函数体内的 `undefined variable`。纯局部赋值(`**score = 1**`)与循环变量不升参。CLI · wasm **1.4.6**(扩展包仍为 **1.4.5**)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.6 && cargo build --release
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——升参与 §8.2 对齐(赋值左值声明);不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **升参**:`merge_inferred_params` 纳入首次粗体赋值左值。右值在绑定前读取同名(`n = n + 1`)时,该名成为必选推断形参。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm SemVer **1.4.6**。扩展包保持 **1.4.5**。
|
||||
|
||||
## v1.4.5 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**Streamable HTTP MCP + web `/v1` 鉴权硬化**:`agent_mcp_serve` 支持 `transport=http`(MCP Streamable HTTP 2025-03-26);web invoke 注入 `Authorization` / `X-Api-Key`,`ok=false`+`unauthorized` → HTTP 401;`ext/ai` openai/agent 字段访问改 `json.get`,消除 footnote 硬崩。CLI · Ext · wasm **1.4.5**。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.5 && cargo build --release
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
# HTTP MCP:
|
||||
# QDAGENT_MCP_TRANSPORT=http marqdo run cli/求道-mcp.mq.md
|
||||
marqdo ext add agent # CDN → 1.4.5
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**新增** MCP Streamable HTTP 传输(`transport=http|streamable-http`);web invoke 契约扩展(header 注入 · 401);**无** MQ 关键词 / 表几何变更。
|
||||
|
||||
### Added
|
||||
|
||||
- **`agent_mcp_serve` Streamable HTTP**:`transport=http` · `host`/`port`/`path`;POST JSON-RPC + 可选 GET SSE;`Mcp-Session-Id`。facade:`ext/ai/agent` `## serve`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **web invoke**:`Authorization` / `X-Api-Key` 注入 payload;`jsonWrapInvokeValue` 对 `unauthorized` 返回 401;`{sse}` 自动 event-stream。
|
||||
- **`ext/ai/llm/openai` · `agent` · `llm`**:字段访问改 `json.get` / `at`,避免 `[field](x)` 在非 map 上硬崩。
|
||||
- **explore workbook**:子任务 `stream=False`(网关 SSE 524 更稳)。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / Ext / wasm SemVer **1.4.5**。
|
||||
- 设计:[doc/design/ext-web-artifact.md](doc/design/ext-web-artifact.md)(sse / bearer)。
|
||||
|
||||
## v1.4.4 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**LLM 传输软失败 + `ext/ai` 表优先重构**:上游连接拒绝/超时/HTTP≠200 时,Runtime 返回结构化 `finish|status=error`(不再硬中断 VM);`agent` / `智能体` / `llm/openai` 去掉 `json.set`/`json.append` 袋胶水。含 CLI host · `plugins/llm` · Ext pack **1.4.4**。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.4 && cargo build --release
|
||||
cargo build --release -p marqdo_plugin_llm
|
||||
marqdo run tests/ext/agent-llm-transport-soft.mq.md
|
||||
marqdo ext add agent # CDN → 1.4.4
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——HTTP 宿主软失败契约 + Extension 风格重构;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **LLM / Agent 传输软失败**:`host_http_post` / SSE · `plugins/llm` · `ext/ai/llm/openai` 结构化 `finish=error`;`agent.step` / `plan` / `run` 收成 `status=error`。金样 `tests/ext/agent-llm-transport-soft.mq.md`。说明:[doc/research/agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)。
|
||||
- **`agent.run`**:`cache == "soft-hit"` 引号比较(裸 `soft-hit` 曾被解析为减法)。
|
||||
|
||||
### Changed
|
||||
|
||||
- **`ext/ai` 去 json 胶水**:结果 map / 事件用 GFM 表 + `table.put` / `table.append` / `table.empty_*`。SKILL 正面示例:`.cursor/skills/marqdo-dev` §2 · `marqdo/examples.md` §6e。
|
||||
- CLI / Ext / wasm SemVer **1.4.4**。
|
||||
|
||||
## Ext pack v1.4.3 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent cold EFI / resolve 硬崩修复(CLI 仍为 v1.4.2)**:qdagent 接通 `agent.run` 时空 OKF 触发 `unknown function preflight` 与 `missing map key llm_free`。本包修复 `ext/ai/agent` facade 与 `agent` native;金样 `tests/ext/agent-run-cold-efi.mq.md`。说明:[`doc/research/agent-run-efi-resolve-bugs-2026-10.md`](doc/research/agent-run-efi-resolve-bugs-2026-10.md)。
|
||||
|
||||
```bash
|
||||
marqdo ext add agent # CDN latest → 1.4.3
|
||||
# 或:MARQDO_EXT_VERSION=1.4.3 marqdo ext add agent
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime 契约修补。
|
||||
|
||||
### Fixed
|
||||
- **`agent.run`**:`efi=True` 改为 `` `self`.preflight ``(不再裸调全局 `preflight`)。
|
||||
- **`agent_resolve` miss**:返回字段对齐命中路径,含 `llm_free: false`;facade 对 `llm_free` / route 字段改用 `json.get`。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.4.3**(`ext/VERSION`);与 CLI **v1.4.2** 可独立安装。
|
||||
|
||||
## v1.4.2 — 2026-10-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent/LLM 优化 O1–O5**:`ext/ai/sandbox` CoW 试跑接入 `agent.trial` / `run sandbox=`(默认关);promote 强制 sandbox proof;步骤路由 `step_route` + EFI preflight + `usage`/`token_cost`;风格 lint 与 `sandbox.report`;技能 `quarantine` 与离线 standing/policy 优化脚本。表优先、少 json 胶水。路线:[ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.2 && cargo build --release
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
marqdo run tests/ext/agent-sandbox-optin.mq.md
|
||||
marqdo run examples/agent-sandbox-okf/index.mq.md
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add agent # CDN latest → 1.4.2
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Extension / Agent Runtime**(`ext/ai` 沙盒与晋升闸门),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **`ext/ai/sandbox`**:CoW 工作区(`open` / `run` / `diff` / `commit` / `discard` / `inspect` / `profile` / `report`);经 `plugins/agent` `sandbox_*` → `host_query`;默认拒 `plugin`/`exec`/`net`。
|
||||
- **O1**:`agent.trial` · `run`/`step` `sandbox=` · 中文 `试跑`/`沙盒=` · 示例 `examples/agent-sandbox-okf/` · 金样 `agent-sandbox-optin`。
|
||||
- **O2**:`agent_kb_promote` 默认 sandbox proof;OKF `applies_when`/`fixtures`/`sandbox_profile`/`proof`;harness Skill Lift。
|
||||
- **O3**:`agent.step_route` · `ext/ai/policies/step-route.mq.md` · `run efi=`(缺工程知识时软放行)· 结果 `usage`/`token_cost`。
|
||||
- **O4**:`scripts/mq-style-lint.sh` · `sandbox.report` markdown 审阅面。
|
||||
- **O5**:`agent_kb_quarantine` / `agent.quarantine` · `scripts/optimize-standing-policy.sh`。
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.2**。
|
||||
- Skill:强制表/链接取元、禁同文件混 EN/ZH、点名 sandbox 试跑习惯。
|
||||
|
||||
## v1.4.1 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 叙述标注连线**:Browse / `view output` 中 underline→chip 改为 SVG 正交连线(描述底边中点 → 轨道 → 短竖线 → 值顶边中点);同跨度多帧 chip 共用 annot id;可见 chip 按锚点 L→R;帧切换后重算密度。设计:[view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.1 && cargo build --release
|
||||
marqdo view public/00-welcome.mq.md --no-open
|
||||
marqdo view output public -o /tmp/mq-public
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.4.1
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 标注几何与帧 chip 对齐),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- 设计缺口文档 [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md):叙述 fence 卡、帧感知 chip 密度、L-leader 几何约定。
|
||||
|
||||
### Fixed
|
||||
- view L-leader:id 与 mark 错配、chip 逆序交叉、border 无色变黑碎段、横线穿过 chip 文字;现为 mid→mid SVG path。
|
||||
- 叙述 fence / 代码卡单层渲染;静态页隐藏 Run;主文函数引用 call chip + leader。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.1**。
|
||||
|
||||
## v1.4.0 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**叙述统一 + 公式 meta + 图片自写回**:块公式 `% marqdo: var=`;分支/循环体与函数体同权叙述;foreach 中英糖;自写回图片 ``(扩展名校验)与 view/静态站同源标记;view 展示推断形参实值;欢迎页迁到 v0.3 叙述面。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.0 && cargo build --release
|
||||
marqdo run tests/markup-v03/formula-meta-var.mq.md
|
||||
marqdo run tests/markup-v03/foreach-narrative.mq.md
|
||||
marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.4.0
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。Language 层在既有 `formula` / `branch-list` / `loop-list` 上扩展语义(块公式 TeX 注释绑定、臂/循环体叙述、foreach 糖);Runtime:自写回图片形态 + view 推断形参展示。设计:[fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)。
|
||||
|
||||
### Added
|
||||
- **块公式 meta 绑定**:`$$` 内 `% marqdo: var=<ident>`(剥离后解析;可无空 RHS);金样 `tests/markup-v03/formula-meta-var.mq.md`。
|
||||
- **控制流叙述统一**:臂/循环体 `parse_indented_body` 与函数体同权;分支条件行支持叙述前缀与行内 `**…**`;foreach 糖 `- 对…的每一项…` / `- for each … in …`。
|
||||
- **图片自写回**:路径/URL 且扩展名合法 → ``;文本仍 HTML 注释;view / `view output` 同源样式卡与 `<img>`。
|
||||
- **view 推断形参实值**:Browse 展示 body-inferred 参数绑定值;欢迎页 EN/ZH 迁 v0.3 叙述。
|
||||
|
||||
### Fixed
|
||||
- `ext/net/url.encode`:经 `lib/net` 包装,不再直接 `host_*`(金样 `ext_mq_md_never_calls_host`)。
|
||||
- PPA 源包:`ppa-build-source.sh` 本地 `.orig` 已在 build-area 时跳过重复 `cp`。
|
||||
- view:嵌套调用欢迎页与公式/代码卡渲染清理。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.0**;词法评论段遇有序分支臂 / 循环头 / 图片自写回标记时断开,避免吞掉控制流行。
|
||||
|
||||
## v1.3.3 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 文档面 Structure**:Browse 保真叙述与标记面(变量/语句/返回无源码定界符);表/循环/分支结构块;语句后绑定值、分支命中臂、函数多调用与循环迭代下拉(默认末帧);`#mq-view-trace` AI JSON。静态 `marqdo view output` 与 live view **同源渲染**(含用户站 `public/` → gh-pages)。
|
||||
|
||||
```bash
|
||||
git checkout v1.3.3 && cargo build --release
|
||||
marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
marqdo view output public -o public
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.3.3
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 文档面 + 帧选择),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **Browse Structure 文档面**(`src/view/document.rs` · `annot.rs`):叙述保真、标记面、GFM 表 / `doc-loop` / `doc-branch`、CSS L-leader 标注带。
|
||||
- **StmtEvent / CallFrame / LoopFrame** 静默轨迹:post-stmt 绑定、分支 `call_id`、循环 `分 = 分数表[i] · value`;调用/迭代 picker(源码常显,只滤 chip)。
|
||||
- **`ViewExecutionReport`** JSON(`#mq-view-trace` · `/api/view-trace` · SSE `trace_json`)。
|
||||
- 设计:[view-document-annotations.md](doc/design/view-document-annotations.md) · [view-execution-trace.md](doc/design/view-execution-trace.md) · [view-frame-selection.md](doc/design/view-frame-selection.md);样例 `tests/view/document-annot-demo.mq.md`。
|
||||
|
||||
### Fixed
|
||||
- 多调用分支 taken 混叠;调用切换误藏未执行臂源码;循环头重复 chip。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.3.3**;静态导出与 live view 共用 `build_file_view` → 文档面。
|
||||
|
||||
## Ext pack v1.3.2 — 2026-10-13
|
||||
|
||||
### Highlights
|
||||
|
||||
**Trailing slash 路由修复(CLI 仍为 v1.3.0)**:Go `ServeMux` 精确匹配导致 `/post/foo/`(带尾部斜杠)落入 404。新增 `withStripTrailingSlash` 中间件作为最外层 handler wrapper,所有下游中间件(RBAC、Tenant、路由)均看到规范化路径。覆盖静态路由、动态路由、根路径、查询参数保留。
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.3.2
|
||||
# 或:MARQDO_EXT_VERSION=1.3.2 marqdo ext add web
|
||||
```
|
||||
|
||||
### Fixed
|
||||
|
||||
- **web**: `/post/foo/` trailing slash now routes the same as `/post/foo` (dynamic and static routes). Root `/` unchanged. Query strings preserved after normalization.
|
||||
|
||||
## Ext pack v1.3.1 — 2026-10-08
|
||||
|
||||
### Highlights
|
||||
|
||||
**OIDC 路径型 `redirect_uri`(CLI 仍为 v1.3.0)**:`redirect_uri=/oidc/callback` 按请求 Host / `X-Forwarded-*` 拼绝对回调,写入会话供 token 交换;可选 `redirect_origins` allowlist。apex / www 多域名无需写死单一绝对 URI。
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.3.1
|
||||
# 或:MARQDO_EXT_VERSION=1.3.1 marqdo ext add web
|
||||
```
|
||||
|
||||
### Added
|
||||
- **路径型 redirect_uri**:绝对 URL 行为不变;路径模式解析 public origin,session 键 `oidc_redirect_uri`。
|
||||
- **`redirect_origins` / `回调来源`**:逗号分隔 origin allowlist(路径模式)。
|
||||
- **ABI**:`web_app_oidc` 透传 `redirect_origins`;`ext/security/oidc.attach` 文档同步。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.3.1**(`ext/VERSION`);与 CLI **v1.3.0** 可独立安装。
|
||||
|
||||
## v1.3.0 — 2026-09-28
|
||||
|
||||
### Highlights
|
||||
|
||||
**Engineering Knowledge Compiler(EKC)**:把仓库投影为 AI 可查询的工程知识系统——L0–L4 Catalog、Capability / Decision / Constraint / Failure、知识图、Reuse Preflight(REUSE→ADAPT→CREATE)与 Context Pack。本版 CLI 与扩展包 **同步为 1.3.0**。
|
||||
|
||||
- **杀手命令**:`marqdo reuse "task"` / `find` / `duplicate` / `impact` / `conflicts` / `stale` / `verify` / `knowledge`
|
||||
- **Agent**:`agent.preflight` · `agent_eng_*`;`plan … eng_preflight=True` 在造轮子前强制 EFI
|
||||
- **投影**:`.marqdo/catalog|knowledge|graph|agent/` + `engineering.yaml`;`catalog` 默认挂钩 EKC
|
||||
- **示例 / 金样**:`examples/engineering-knowledge/` · `tests/engineering/` · `tests/ext/eng-preflight.mq.md`
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
|
||||
git checkout v1.3.0 && cargo build --release
|
||||
marqdo knowledge . -o .marqdo
|
||||
marqdo reuse "resolve configuration"
|
||||
marqdo ext add agent
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(知识编译器 + CLI + agent 插件),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **`src/knowledge/` EKC**:L0–L4 IR、指纹、能力推导、图边、compile、find/reuse/preflight、impact/lifecycle/duplicate、metrics、policy、learn。
|
||||
- **CLI**:`knowledge` · `find` · `reuse` · `impact` · `conflicts` · `stale` · `duplicate` · `verify`;`catalog`/`sync` 默认编译 EKC(`--no-knowledge` 可关)。
|
||||
- **Agent**:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`;`ext/ai` `## preflight` + `plan eng_preflight`。
|
||||
- **规范**:`doc/design/engineering-knowledge.md`;提案叙事 `doc/next/008.md`(已实现标注)。
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
- **OKF type 注册表**扩展 Capability/Decision/Constraint/Failure/Context Pack/Policy 等([okf.md](doc/design/okf.md))。
|
||||
- **核心表面 Δ**:**无增删**。
|
||||
|
||||
## v1.2.0 — 2026-09-28
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+29
-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 = "1.1.1"
|
||||
version = "2.2.2"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -589,6 +589,7 @@ dependencies = [
|
||||
"predicates",
|
||||
"pulldown-cmark",
|
||||
"regex",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"sha1",
|
||||
"sha2",
|
||||
@@ -601,9 +602,16 @@ dependencies = [
|
||||
"zip",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-plugin-sdk"
|
||||
version = "2.0.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.1.1"
|
||||
version = "2.2.2"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -614,6 +622,7 @@ name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
@@ -621,6 +630,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
@@ -628,6 +638,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_linalg"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
@@ -637,6 +648,7 @@ name = "marqdo_plugin_llm"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"idna_adapter",
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
@@ -646,6 +658,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_quantum"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"marqdo-plugin-sdk",
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
@@ -1278,9 +1291,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",
|
||||
@@ -1291,9 +1304,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",
|
||||
@@ -1301,22 +1314,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",
|
||||
]
|
||||
|
||||
+6
-4
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.2.0"
|
||||
version = "2.2.2"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -19,7 +19,7 @@ cli = ["dep:clap"]
|
||||
view = ["dep:tiny_http"]
|
||||
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
|
||||
plugin-host = ["dep:libloading"]
|
||||
exec-host = []
|
||||
exec-host = ["dep:libc"]
|
||||
fs-host = []
|
||||
tty = ["dep:libc"]
|
||||
wasm-core = []
|
||||
@@ -29,6 +29,7 @@ anyhow = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"], optional = true }
|
||||
pulldown-cmark = "0.12"
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = { version = "0.12", optional = true }
|
||||
@@ -62,9 +63,10 @@ members = [
|
||||
"plugins/quantum",
|
||||
"plugins/linalg",
|
||||
"crates/marqdo-wasm",
|
||||
"crates/marqdo-plugin-sdk",
|
||||
]
|
||||
# Official web plugin is Go (`plugins/web/`); Rust sources kept as
|
||||
# `plugins/web-rust-archive/` for reference (not a workspace member).
|
||||
# Official web plugin is Go (`plugins/web/`). The legacy Rust web plugin was
|
||||
# deleted from the tree (see CHANGELOG); git history keeps it if ever needed.
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
# Marqdo
|
||||
# Marqdo
|
||||
|
||||
**代码即文档。文档即知识库。知识即可执行。**
|
||||
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
|
||||
|
||||
v2.2.0 起,`marqdo call` 可以直接调用这份文件里的一个函数。读的是同一页说明,跑的是同一个实现。知识因此可以当工具用,测试也不必再包一层 `# main`。
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
**链接语法**:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -29,15 +31,97 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| 真正的核心优势 | 说明 |
|
||||
|------|------|
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **函数即工具**<br>`marqdo call` | 最小可执行单位是文件中的函数,不只是整份文件。人阅读函数旁边的叙述;开发者、测试和 Agent 用 `marqdo call 文件 函数 名字=值` 执行它。知识复用、工具调用、函数级测试和局部改进是同一入口的四种用法。 |
|
||||
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
|
||||
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元 `[键](集合)` 也是 Markdown 链接形。这是 literate programming 的下一步。 |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
|
||||
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`print` 只是副作用函数;分支与循环长在 Markdown 结构上(`1.` `2.` 递增 = 分支,`-` = 循环),不是所有列表都被粗暴当成 if。 |
|
||||
| **AI 的可靠上下文与长期记忆** | 一个 `.mq.md` 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的**世界模型**——比 RAG 更接近 Executable RAG。 |
|
||||
| **链接即调用**<br>Link as Call | 文档里的 `[描述](类.函数)` 不是装饰,是跨文档类调用;编译器解析类/函数并返回 **LinkInfo**,`view` 显示调用点,EKC 建边,`links.lock` 可选复现。**v2.1 已实现可执行知识基础设施**。 |
|
||||
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
|
||||
|
||||
---
|
||||
|
||||
## 链接语法:链接即调用(v2.1 设计声明)
|
||||
|
||||
> **这是 v2.1 的可执行知识模型。**
|
||||
> `[]()` 不新增语法:`[]` 是 Markdown 链接的描述;`()` 是**已有代码**,与 `**代码**` 同权。
|
||||
> `#` 是类,`##` 是函数;`类.函数` 是**类调用**。
|
||||
> 链接只是给这次调用一个名字;`view` 显示调用信息,编译器返回 **LinkInfo**,EKC 建边。
|
||||
|
||||
### 两文档,一次类调用
|
||||
|
||||
知识文档 `libai.mq.md`:
|
||||
|
||||
```markdown
|
||||
# 李白
|
||||
|
||||
这个文档存储了李白的信息。
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
- `# 李白` = 类;
|
||||
- `## 李白的出生年份` = 函数;
|
||||
- `*701*` = 返回值。
|
||||
|
||||
调用文档 `main.mq.md`:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`——**类 `李白` 调用函数 `李白的出生年份`**。
|
||||
不需要 `print`:`view` 模式天然显示 `()` 的调用信息(类、函数、签名、值)。
|
||||
要终端输出,就把同一段代码放进代码链接并加 `print`:
|
||||
|
||||
```markdown
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出:`701`。
|
||||
|
||||
### 四条语义
|
||||
|
||||
1. **`[]` 永不执行**:描述只给人读、给检索/诊断/展示用。
|
||||
2. **`()` 与 `**代码**` 同权**:同一套 parser/evaluator;`类.函数` 是类调用,`obj.函数` 是实例调用。
|
||||
3. **`#` 是类,`##` 是函数**:不使用 `self`/`自` 的函数是**类函数**,可直接 `类.函数` 调用;使用 `self`/`自` 的是**实例函数**。
|
||||
4. **链接 = 描述 + 调用**:`view` 显示调用点;编译器返回 `LinkInfo`;EKC 建边;`links.lock` 可选复现。
|
||||
|
||||
### 现状与目标
|
||||
|
||||
| 能力 | v2.0.0 | v2.1 |
|
||||
|------|-------------|-----------|
|
||||
| 本地表达式链接(遮蔽) | ✅ `markup: occlusion` | ✅ |
|
||||
| `()` 与 `**代码**` 同权 | ✅ 表达式/调用 | ✅ |
|
||||
| 类调用 `类.函数` | ❌ 需先构造实例 | ✅ 直接调用 |
|
||||
| 跨文档类索引 | ❌ 需 `import` + 实例 | ✅ 项目类索引 |
|
||||
| 正文链接 `view` 信息 | ❌ | ✅ 目标/签名/值 |
|
||||
| LinkInfo / check | ❌(`check` 只查契约) | ✅ `link.*` |
|
||||
| 链接图边(EKC) | ❌ | ✅ `calls` / `references` |
|
||||
| `links.lock` 可复现 | ❌ | ✅ 可选 |
|
||||
|
||||
### 知识分层:本体 → 知识个体 → 调用面
|
||||
|
||||
| 层 | 写法 | 语义 |
|
||||
|----|------|------|
|
||||
| L1 本体 | `# 诗人` + 字段/类型表 | 类/模式 |
|
||||
| L2 知识个体 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` | 单体知识类(不是运行时实例) |
|
||||
| L3 调用面 | `[出生年份](李白.出生年份)` | 类调用/链接 |
|
||||
|
||||
> `# 李白 = > 诗人` 语法上是继承/特化,语义上是「李白是诗人」的知识个体;
|
||||
> 运行时实例仍是 `> 诗人` / `> 李白`。详见 [knowledge-layers.md](doc/design/knowledge-layers.md)。
|
||||
|
||||
兼容迁移示例见 [examples/link-syntax/main.compat.mq.md](examples/link-syntax/main.compat.mq.md)。
|
||||
|
||||
设计宪法:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 链接示例:[examples/link-syntax/](examples/link-syntax/) · 知识分层示例:[examples/knowledge-layers/](examples/knowledge-layers/) · 证据复核:[occlusion-vs-executable-knowledge-2026-10.md](doc/research/occlusion-vs-executable-knowledge-2026-10.md)
|
||||
|
||||
---
|
||||
|
||||
## 愿景与期许
|
||||
|
||||
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
|
||||
@@ -45,7 +129,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
1. **AI 可验证语言**:`LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序`。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
|
||||
2. **Marqdo Schema / Language Server for AI**:机器可读的语言 Schema(`get_syntax` / `validate` / `repair` …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
|
||||
3. **程序即 AI 长期记忆**:`.mq.md` 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
|
||||
4. **可执行知识图**:`.mq.md` 之间的 Markdown 链接天然长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
|
||||
4. **链接即调用 / 可执行知识图**:`[描述](类.函数)` 既是文档链接,也是类/函数调用;编译器解析目标、校验签名、返回 LinkInfo;`view` 显示调用点;`.mq.md` 之间的链接长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
|
||||
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
|
||||
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
|
||||
|
||||
@@ -64,24 +148,30 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.3)
|
||||
## 语法速览
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
|
||||
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
|
||||
| `[描述](表达式)` | **链接(本地)**:描述 + 代码;`()` 与 `**…**` 同权(默认语义) |
|
||||
| `[描述](类.函数)` | **链接(跨文档/类调用)**:描述 + 已有类函数调用;可解析、可执行(v2.1 目标) |
|
||||
| `[描述](url)` | 普通 Markdown 导航链接(惰性,不执行) |
|
||||
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
|
||||
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `#` | **类 / 类型**(知识命名空间;`# main` = 入口) |
|
||||
| `##` … | **函数**(类下函数;使用 `self`/`自` 时为实例方法) |
|
||||
| `类.函数` | **类调用**(不使用 `self` 的函数;v2.1 目标) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
|
||||
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
|
||||
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](遍历 集合 为 项) ``) |
|
||||
| 表格 | 集合(几何即类型,见下);取元使用 `access(集合, "键")` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
|
||||
|
||||
> `[键](集合)` / `- [项](集合)` 是旧取元/循环形;迁移后使用 `access(集合, "键")` 与 `- [描述](遍历 集合 为 项)`。旧形只在显式 `markup: classic` 或 `--legacy-markup` 过渡入口中保留,见 [link-syntax.md](doc/design/link-syntax.md)。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
@@ -116,6 +206,51 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 工程习惯:允许申报未完成,但不允许假装完成
|
||||
|
||||
Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。这样文档整体仍能跑,
|
||||
而欠账是可见、可数、可结算的(而不是假装完成):
|
||||
|
||||
```markdown
|
||||
## 检索资料
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | list | 命中列表(当前未接) |
|
||||
|
||||
[按关键词检索,接口未接,待开发](None)
|
||||
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**目标**(唯一执行)。这条语法叫**链接语法**:
|
||||
目标是本地表达式时,就是**遮蔽**(把代码折叠在括号里);目标是 `类.函数` 时,就是**跨文档类调用**。
|
||||
v2.1 实现了文件级链接语义与可执行知识投影(见 [link-syntax.md](doc/design/link-syntax.md))。
|
||||
|
||||
**四条约定**
|
||||
|
||||
1. **桩必须能跑**:不得报错,否则整篇文档被阻断。
|
||||
2. **桩必须写明返回值**:写 `None` 也比空着好;空 `()` 会报 `label.empty_payload`(warning)。
|
||||
3. **申报用词有范例**:内置词表(`待开发` `未实现` `开发中` `模拟` `桩` `示例` `实验` `废弃` …)
|
||||
是**推荐用词与默认检索集**,不是语法——写别的说法同样合法。
|
||||
4. **接不了就申报,别声称完成**:这条已写进 `ext/ai` 的 agent 提示词。
|
||||
|
||||
**盘点与门禁**
|
||||
|
||||
```bash
|
||||
marqdo labels --count # 内置口径:还有多少未完成
|
||||
marqdo labels --grep "接口未联调,联调中" --count # 用你自己的说法
|
||||
marqdo labels --grep 联调 --also-builtin --count # 自定义 + 内置一起数
|
||||
marqdo labels --count --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
|
||||
|
||||
设计依据:[link-syntax.md](doc/design/link-syntax.md) · [occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
|
||||
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
|
||||
|
||||
---
|
||||
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
@@ -123,6 +258,13 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
|
||||
# Engineering Knowledge Compiler(L0–L4 能力目录 / 复用门闩)
|
||||
marqdo knowledge [PATH] -o OUT_DIR
|
||||
marqdo find "authentication"
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo duplicate [--fail]
|
||||
marqdo verify
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
@@ -130,7 +272,7 @@ marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。产物示例:`catalog.yaml`、`engineering.yaml`、`catalog/capabilities/`、`graph/graph.json`。设计见 [engineering-knowledge.md](doc/design/engineering-knowledge.md) · [catalog-cli.md](doc/design/catalog-cli.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
|
||||
智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):[agent-frameworks-and-marqdo.md](doc/research/agent-frameworks-and-marqdo.md) · 优化路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
|
||||
|
||||
@@ -142,23 +284,45 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.2.0)
|
||||
## 现状(v2.2.2)
|
||||
|
||||
- **\(V_{\mathsf{safe}}\) JSON 整数(v2.2.2)**:外联与 `lib/json` 拒绝 `|n| > 2^{53}-1` 的 JSON 整数(对齐 Lean ForeignJSON);宽整数用十进制字符串 + Node `BigInt`。扩展包同步 **2.2.2**
|
||||
- **view 大纲侧栏(v2.2.1)**:修复 occlusion 文档与中等宽度下 Functions / Variables 掉到正文下方的问题;静态 `view output` 同源。
|
||||
- **函数级调用(v2.2.0)**:`marqdo call <文件.mq.md> <函数> 名字=值`。同一份文档给人读,也按函数执行;Tree 与 Bytecode 都跑被点名的函数,不回退到 `# main`。默认只执行纯函数。`--json` 给 Agent 读取结果或诊断。说明与价值见 [22-函数调用](public/features/22-函数调用.mq.md)。示例:`marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3` → `5`。扩展包同步 **2.2.1**
|
||||
- **Agent 可靠工作台(v2.1.5)**:ResourceView(JSON/CSV/PDF/image)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制与 execute 槽隔离;扩展包同步 **2.1.5**
|
||||
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例
|
||||
- **知识工作台运行时(v2.1.3)**:ModelSelection / RunContext / usage null≠0 · `view document` 只读嵌入 · LLM selection/messages/cancel · agent.step selection e2e · live smoke(设计 Partial:原生适配器 unavailable)
|
||||
|
||||
- **可执行知识生产链(v2.1.2)**:证据/闭包失效 · `verify`/`adjudicate` · `reuse_execute` / `eng_bind_execute`+`publish_gate` · `document.extract` · View `KnowledgePresentation`+SSE `page_token` · 上传限流 · 门禁 45 项(100/1000 单元)
|
||||
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113`
|
||||
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock)
|
||||
- **外联 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**
|
||||
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
|
||||
- **Streamable HTTP MCP + web invoke 鉴权(v1.4.5)**:`agent_mcp_serve transport=http` · Bearer/`X-Api-Key` 注入 · `unauthorized`→401 · openai/agent `json.get` 硬化
|
||||
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
|
||||
- **Ext pack 1.4.3**:修复 `agent.run` cold EFI(`` `self`.preflight `` + miss resolve `llm_free`);已并入 **≥1.4.4** · [agent-run-efi-resolve-bugs-2026-10.md](doc/research/agent-run-efi-resolve-bugs-2026-10.md)
|
||||
- **Agent/LLM 优化 O1–O5(v1.4.2)**:`ext/ai/sandbox` CoW · `agent.trial` / `sandbox=` · promote sandbox proof · `step_route` / EFI / cost · style lint · quarantine · [ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)
|
||||
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
|
||||
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)
|
||||
- **view 文档面(v1.3.3)**:Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI `#mq-view-trace` · 静态 `view output` / gh-pages 同源 · [view-document-annotations.md](doc/design/view-document-annotations.md)
|
||||
- **Engineering Knowledge(v1.3.0)**:EKC L0–L4 · `marqdo knowledge|find|reuse|duplicate|verify|…` · Agent `preflight` / REUSE→ADAPT→CREATE · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
- **Web Artifact(v1.2.0 · ADR 0007)**:Document/Endpoint 一等公民(`type: web|endpoint`)· facade `page`/`route`/`serve`/`render`/`inspect`/`use` · Resource 拆到 `ext/data`/`security`/`net` · 统一 View 表 · 破坏性移除 `compose_*`/`configure`
|
||||
- **AI 栈(v1.1.1)**:`ext/ai/llm` 语义 `ask`/`stream`/`collect` · Artifact Metadata Binding(`${env|arg|sys|secret}`)· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 `plugins/llm` Transport ABI
|
||||
- **AI 原生闭环(v1.1.0)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
|
||||
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
|
||||
- **`marqdo view`**:文档浏览器(**文档面** Structure + 标注 / 调用·循环帧 + 函数大纲/搜索 + Execution + Variables 浮窗;`view output` 同构)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页(默认挂钩 EKC)
|
||||
- **`marqdo knowledge` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`**:Engineering Knowledge Compiler([engineering-knowledge.md](doc/design/engineering-knowledge.md))
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
|
||||
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
|
||||
- **`web`**:**Artifact 模型(ADR [0007](doc/adr/0007-web-document-endpoint.md))** — `type: web|endpoint` Document/Endpoint;facade `page`/`route`/`serve`/`render`/`inspect`/`use`;Resource 在 `ext/data` · `ext/security` · `ext/net`;设计 [ext-web-artifact.md](doc/design/ext-web-artifact.md);原生 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md));示例 [marqdo-blog](examples/marqdo-blog/) · [web-client-site](examples/web-client-site/) · [anlian-mq](examples/anlian-mq/)
|
||||
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
|
||||
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
|
||||
- **`agent`**:A1–A4 + **MCP Server/Client stdio** + Skill Compilation + Adaptive Routing + resume;宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`agent`**:A1–A4 + **MCP Server/Client**(stdio + **Streamable HTTP**)+ Skill Compilation + Adaptive Routing + resume + **Engineering preflight**(`agent.preflight` / `eng_preflight`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
- **`llm`**:语义 `ask`/`stream`/`collect`(OpenAI/Ollama;可选原生 `plugins/llm`)
|
||||
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg,llm}`(`web` 为 Go;其余为 Rust)
|
||||
@@ -167,7 +331,7 @@ marqdo catalog public -o .marqdo
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v1.2.0)
|
||||
### 如何使用最新 Marqdo(v2.2.2)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -182,14 +346,16 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.2.0 # 或留在 main
|
||||
git checkout v2.2.2 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
marqdo version --check
|
||||
|
||||
# 2) 跑解释器 / 文档站 / catalog
|
||||
# 2) 跑整个文件,或只调用其中一个函数
|
||||
marqdo run tests/structure/hello.mq.md
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
|
||||
marqdo run tests/structure/hello.mq.md --backend bytecode
|
||||
marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
@@ -221,7 +387,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.2.0
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.2.2
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
[package]
|
||||
name = "marqdo-plugin-sdk"
|
||||
version = "2.0.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,195 @@
|
||||
//! Shared ABI plumbing for Marqdo native plugins (`<TAB>` slimming).
|
||||
//!
|
||||
//! Every plugin used to copy the same `MarqdoHostApi` struct, the alloc/free
|
||||
//! statics, `host_strdup`, `set_out`/`set_err`, `parse_args` and `reply`
|
||||
//! (about 140 lines each × 5 crates). This crate holds the single copy; the
|
||||
//! `marqdo_plugin!` macro emits the `#[no_mangle]` exports each `.so` needs.
|
||||
//!
|
||||
//! The ABI itself is unchanged: `include/marqdo_abi.h` and the host loader
|
||||
//! (`src/host/plugin.rs`) still see exactly the same symbols and layout.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
|
||||
pub use serde_json::{json, Value};
|
||||
|
||||
/// Highest ABI version this SDK speaks.
|
||||
pub const ABI_VERSION: u32 = 2;
|
||||
|
||||
pub type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
pub type HostQueryFn = unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
pub host_query: Option<HostQueryFn>,
|
||||
}
|
||||
|
||||
pub static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
pub static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
pub static mut HOST_QUERY: Option<HostQueryFn> = None;
|
||||
pub static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
|
||||
|
||||
/// Duplicate `s` into host-allocated memory (the host frees it).
|
||||
pub unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
pub fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
pub fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse the JSON args object handed to a plugin entry point.
|
||||
pub fn parse_args(args_json: *const c_char) -> Result<Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
if s.trim().is_empty() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Write a plugin result (or error) back through the ABI pointers.
|
||||
pub fn reply(out_json: *mut *mut c_char, err_msg: *mut *mut c_char, r: Result<Value, String>) -> c_int {
|
||||
match r {
|
||||
Ok(v) => {
|
||||
set_out(out_json, &v.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &e);
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Ask the host for a builtin with no arguments (`host_query`).
|
||||
pub fn host_query_json(name: &str) -> Result<Value, String> {
|
||||
host_query_json_with(name, &json!({}))
|
||||
}
|
||||
|
||||
/// Ask the host for a builtin, passing `args` as its argument object.
|
||||
pub fn host_query_json_with(name: &str, args: &Value) -> Result<Value, String> {
|
||||
let q = unsafe { HOST_QUERY }.ok_or("host_query unavailable")?;
|
||||
let n = CString::new(name).map_err(|e| e.to_string())?;
|
||||
let a = CString::new(args.to_string()).map_err(|e| e.to_string())?;
|
||||
let mut out: *mut c_char = ptr::null_mut();
|
||||
let mut err: *mut c_char = ptr::null_mut();
|
||||
let rc = unsafe { q(HOST_USERDATA, n.as_ptr(), a.as_ptr(), &mut out, &mut err) };
|
||||
if rc != 0 {
|
||||
return Err(take_host_string(err).unwrap_or_else(|| "host_query failed".into()));
|
||||
}
|
||||
let text = take_host_string(out).ok_or("host_query returned nothing")?;
|
||||
serde_json::from_str(&text).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Copy a host-allocated C string into a Rust `String` and free the original.
|
||||
pub fn take_host_string(p: *mut c_char) -> Option<String> {
|
||||
if p.is_null() {
|
||||
return None;
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(p) }
|
||||
.to_string_lossy()
|
||||
.into_owned();
|
||||
if let Some(free) = unsafe { HOST_FREE } {
|
||||
unsafe { free(p as *mut c_void) };
|
||||
}
|
||||
Some(s)
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, f: PluginFn) -> c_int {
|
||||
let Some(reg) = host.register_fn else {
|
||||
return 1;
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { reg(host.userdata, n.as_ptr(), p.as_ptr(), f) }
|
||||
}
|
||||
|
||||
/// Store the host callbacks and register every entry point.
|
||||
pub unsafe fn init_plugin(host: *const MarqdoHostApi, regs: &[(&str, &str, PluginFn)]) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
HOST_QUERY = host.host_query;
|
||||
HOST_USERDATA = host.userdata;
|
||||
for (name, params, f) in regs {
|
||||
if register(host, name, params, *f) != 0 {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
/// Emit the four `#[no_mangle]` exports every plugin `.so` must provide,
|
||||
/// wiring `marqdo_plugin_init` to the given registration table.
|
||||
#[macro_export]
|
||||
macro_rules! marqdo_plugin {
|
||||
($version:expr, [ $( ($name:expr, $params:expr, $f:expr) ),* $(,)? ]) => {
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
$version
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(
|
||||
host: *const $crate::MarqdoHostApi,
|
||||
) -> i32 {
|
||||
$crate::init_plugin(host, &[ $( ($name, $params, $f as $crate::PluginFn) ),* ])
|
||||
}
|
||||
};
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.2.0"
|
||||
version = "2.2.2"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
@@ -12,4 +12,4 @@ crate-type = ["cdylib", "rlib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
|
||||
serde_json = "1"
|
||||
serde_json = "1"
|
||||
Vendored
+176
@@ -1,3 +1,179 @@
|
||||
marqdo (2.2.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.2: V_safe JSON integer contract on foreign/json bridge —
|
||||
refuse integers outside +/- (2^53-1); wide ints via decimal string.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Sat, 01 Nov 2026 09:45:00 +0800
|
||||
|
||||
marqdo (2.2.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.1: fix view/static-export outline rail under document
|
||||
(occlusion doc-block close + panel container query layout).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 11:45:00 +0800
|
||||
|
||||
marqdo (2.2.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.0: marqdo call runs one named function in any .mq.md.
|
||||
The same file stays the document, the knowledge and the program.
|
||||
Tree and bytecode both execute that function. External calls stay
|
||||
pure: write, process, network and plugin stay off by default.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 09:20:00 +0800
|
||||
|
||||
marqdo (2.1.5-1ppa2) noble; urgency=medium
|
||||
|
||||
* Rebuild 2.1.5 against Launchpad (previous 1ppa1 failed with no build log).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 09:35:49 +0000
|
||||
|
||||
marqdo (2.1.5-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.5: agent reliability workbench — ResourceView / ToolSpec /
|
||||
CheckpointV2 / EffectLedger; EKC ir.json warm-load; web short/read lanes.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 07:39:08 +0000
|
||||
|
||||
marqdo (2.1.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.4: default isolated HTTP execute (ADR 0009) — Supervisor
|
||||
worker pool for execute/sse-live/stream, /_runtime/* control plane,
|
||||
MR-01 dual 60s SSE gold sample, runtime.isolated_execution=1.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 26 Oct 2026 10:00:00 +0000
|
||||
|
||||
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,
|
||||
sources/applicability, generation CURRENT + closure digests).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 15:40:00 +0000
|
||||
|
||||
marqdo (2.1.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.0: file-scoped Occlusion is the default syntax; migrated
|
||||
standard/extension libraries and executable-knowledge projections.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 12:00:00 +0000
|
||||
|
||||
marqdo (2.0.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
|
||||
bracketed label is inert prose and the parenthesized payload is the
|
||||
only executed part. Adds paren-call arguments, access() element
|
||||
access, occlusion loops, marqdo labels (two-tier search + debt
|
||||
ratchet), marqdo migrate labels, and label.missing / empty_payload /
|
||||
ref_dangling diagnostics; view renders labels as prose, payloads as
|
||||
code, stubs with a badge. 80 corpus files migrated.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 22 Oct 2026 16:30:00 +0800
|
||||
|
||||
marqdo (1.5.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.2: Foreign v3 P0/P1 — raw stdin with per-cell inputs and
|
||||
interrupt, plan generation/add/remove/value API, snapshot
|
||||
export/import/replay, view capture for static export, explicit Persist
|
||||
button, nested plan boundary.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 15:00:00 +0800
|
||||
|
||||
marqdo (1.5.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.1: View static/live execution path unified; foreign value
|
||||
passing into multi-kernel sessions; cell stdin for live/static/persistent
|
||||
kernels; build-time execution with stdout injection in static exports;
|
||||
runnable foreign writeback example; writeback block grouping.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 22:00:00 +0800
|
||||
|
||||
marqdo (1.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
|
||||
parallel fan-out, persistent Python/Node kernels, explicit state
|
||||
bridge) and document-native notebooks in view; high-contrast
|
||||
light/dark view themes, resizable code/output panes, OKF/EKC and
|
||||
Python examples on the user site. Fixes branch-local variables
|
||||
leaking into required constructor parameters.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 03:30:00 +0800
|
||||
|
||||
marqdo (1.4.6-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.6: Promote a bare self-increment to a required parameter.
|
||||
The first bold assignment LHS is a declaration (design §8.2); a missing
|
||||
argument reports missing argument for parameter, not undefined variable.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 23:56:00 +0800
|
||||
|
||||
marqdo (1.4.5-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.5: Streamable HTTP MCP (agent_mcp_serve transport=http);
|
||||
web invoke Bearer/X-Api-Key inject + unauthorized→401; openai/agent
|
||||
field access via json.get (no footnote hard-fail).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 17:40:00 +0800
|
||||
|
||||
marqdo (1.4.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.4: Soft LLM transport errors (structured status=error);
|
||||
ext/ai table-first refactor (no json.set glue).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 14:40:00 +0800
|
||||
|
||||
marqdo (1.4.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.2: Agent/LLM optimize O1–O5 — sandbox trial opt-in,
|
||||
promote sandbox proof, step_route/EFI/cost, style lint, quarantine.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 11:51:05 +0800
|
||||
|
||||
marqdo (1.4.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.1: View annot leaders — SVG mid-to-mid (mark bottom-center
|
||||
to chip top-center), unify frame chip ids, L-to-R chip density.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 15 Oct 2026 20:40:00 +0800
|
||||
|
||||
marqdo (1.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.0: Prose-unified control flow — block formula % marqdo: var=,
|
||||
arm/loop narrative + foreach sugar, image writeback ,
|
||||
view inferred-param values; welcome pages on v0.3 prose surface.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 15:53:00 +0800
|
||||
|
||||
marqdo (1.3.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.3.3: Browse document-surface Structure — narration-preserving
|
||||
markers, branch/loop frame pickers, ViewExecutionReport JSON; static
|
||||
view output / gh-pages share the same render path as live view.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 13:20:00 +0800
|
||||
|
||||
marqdo (1.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.3.0: Engineering Knowledge Compiler (EKC) — L0–L4 catalog,
|
||||
marqdo knowledge/find/reuse/duplicate/verify, Agent preflight
|
||||
(REUSE→ADAPT→CREATE), graph + context packs.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 16:50:00 +0800
|
||||
|
||||
marqdo (1.2.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.2.0: Web Artifact rewrite (ADR 0007) — Document/Endpoint/Resource,
|
||||
|
||||
+49
-4
@@ -13,10 +13,25 @@
|
||||
|
||||
## 当前文档
|
||||
|
||||
> **可执行知识下一阶段的阅读顺序**:[原始意图 009](next/009.md) → [文档原生开发指导](design/document-native-development-guide.md)(作者体验、语法审查结论、AI 工作协议)→ [详细开发规范](next/Marqdo_Executable_Knowledge_Development.md)(目标语义与工程约束)→ [缺口与交付路线](roadmap/executable-knowledge-gaps-2026-10-23.md)(现状证据、S0–S6)。指导文档修订作者负担、场景政策和交付次序;不得把所有内部治理字段变成作者必填项。与之冲突的早期设计只作历史参考,设计目标不等于已实现能力。
|
||||
>
|
||||
> **可执行知识门禁**:[tests/executable_knowledge/](../tests/executable_knowledge/README.md) — S0–S2 BoundCall / 效应 / MLSP bind,以及后续 NarrativeRef、来源与整代投影子集;`cargo test --test executable_knowledge --locked`(CI:`.github/workflows/executable-knowledge.yml`)。`status: design` / 预期失败与已实现分开报告。
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
|
||||
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
|
||||
| [roadmap/agent-reliability-crossrepo-2026-10-27.md](roadmap/agent-reliability-crossrepo-2026-10-27.md) | **Proposed:跨仓 Agent 可靠性开发计划**;M-A0–M-A6 ∥ Q-A0–Q-A7 排期、依赖图、F01–F20 映射、MA-T*/QA-* 验收与第一刀切片;协议真源仍见下方设计文档 |
|
||||
| [design/agent-reliability-tools-resources-2026-10-27.md](design/agent-reliability-tools-resources-2026-10-27.md) | **Proposed:智能体能力补足**;基于 `16f26d7`,增量设计错误恢复、检查点/效应账本、结构化工具、输出通道、上下文与只读资源视图;含跨仓边界、阶段计划和故障验收 |
|
||||
| [research/agent-capabilities-2026-10-27.md](research/agent-capabilities-2026-10-27.md) | **官方能力调研与源码复核**;OpenAI/Claude/Gemini/LangGraph/Deep Agents/MCP,求道当前问题 F01–F20;区分现有能力、设计推导与待实测项 |
|
||||
| [design/isolated-web-runtime-development-2026-10-26.md](design/isolated-web-runtime-development-2026-10-26.md) | **隔离执行与响应式 Web 运行时**:进程池、控制/读取分离、取消、事件恢复、发布一致性;实现见 `src/runtime/` |
|
||||
| [adr/0009-isolated-web-runtime.md](adr/0009-isolated-web-runtime.md) | **ADR 0009**:隔离 Web 运行时决策;金样例通过后替代 ADR 0008 的并行性结论 |
|
||||
| [跨库缺陷复核(2026-10-26)](../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) | **最新源码与测试证据**:实际 HTTP 路由、知识发布/阅读断点、旧缺陷处置及 1000 单元编译性能失败;需同级 qdagent checkout |
|
||||
| [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 映射**:不再代表现行默认链接语义 |
|
||||
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 设计背景**:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断;链接语义以 v2.1 规范和测试为准 |
|
||||
| [adr/0005-prose-unified-markup.md](adr/0005-prose-unified-markup.md) | **Proposed:采纳 mapping v0.3** |
|
||||
| [roadmap/markup-v0.3.md](roadmap/markup-v0.3.md) | **Markup v0.3 实现路线(M0–M5)** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
@@ -25,6 +40,7 @@
|
||||
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
|
||||
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单(早期方向) |
|
||||
| [design/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
|
||||
| [design/engineering-knowledge.md](design/engineering-knowledge.md) | **Engineering Knowledge Compiler(EKC)**:L0–L4、reuse、EFI |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
|
||||
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
|
||||
@@ -47,7 +63,13 @@
|
||||
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
|
||||
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— v1 已落地** |
|
||||
| [design/foreign-kernel.md](design/foreign-kernel.md) | **外联内核:持久内核 / JSON 桥 / 状态桥 / 安全** |
|
||||
| [design/notebook-session.md](design/notebook-session.md) | **文档会话:cell / kernel / step / journal / 状态面板** |
|
||||
| [design/notebook-syntax.md](design/notebook-syntax.md) | **文档原生 notebook 语法:内核表 / 会话表** |
|
||||
| [research/foreign-notebook-decisions.md](research/foreign-notebook-decisions.md) | **外联 / notebook 决策记录(逐问逐答)** |
|
||||
| [roadmap/foreign-v2.md](roadmap/foreign-v2.md) | **外联内核 v2 路线(F0–F4)** |
|
||||
| [roadmap/notebook-session.md](roadmap/notebook-session.md) | **文档会话路线(D0–D5)** |
|
||||
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
|
||||
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
|
||||
@@ -89,10 +111,33 @@
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
|
||||
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
|
||||
| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
|
||||
| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) |
|
||||
| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 |
|
||||
| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
|
||||
| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **Accepted**:Agent/LLM 优化 O1–O5 locked |
|
||||
| [roadmap/ext-ai-optimize.md](roadmap/ext-ai-optimize.md) | **O1–O5 实现路线**(沙盒接入→证明晋升→路由/成本→lint→隔离) |
|
||||
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
|
||||
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
|
||||
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
|
||||
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
|
||||
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
|
||||
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
|
||||
| [roadmap/executable-knowledge-gaps-2026-10-23.md](roadmap/executable-knowledge-gaps-2026-10-23.md) | **v2.1 现状与规划缺口审计(方向修订)**:保留 G01–G12 代码证据,以可读步骤、确定执行、早期 AI 复用和局部修改重排 S0–S6,严格治理按场景增加 |
|
||||
| [../tests/executable_knowledge/README.md](../tests/executable_knowledge/README.md) | **S0 作者基线门禁**:六类任务语料、作者成本计数、预期失败与 Bytecode 同名误连缺陷指纹 |
|
||||
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
|
||||
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
|
||||
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
|
||||
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
|
||||
| [design/warning-fatigue-control.md](design/warning-fatigue-control.md) | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
|
||||
| [design/staleness-providers.md](design/staleness-providers.md) | 变更检测不依赖 git:T0/T1 零依赖 + T2/T3 可选 provider |
|
||||
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
|
||||
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
|
||||
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
|
||||
| [research/occlusion-vs-executable-knowledge-2026-10.md](research/occlusion-vs-executable-knowledge-2026-10.md) | **遮蔽 vs 可执行知识复核**:v2.0.0 的 `[]()` 只做了呈现层 · 两文档例子实测不可执行 · `check`/`labels`/图边工程漂移证据 · 原始设计=类-函数调用(见 link-syntax) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
# ADR 0008:Web 热路径单解释器串行化(设计缺陷与缓解)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted**(缺陷已记录;缓解已落地;真并行见 [ADR 0009](0009-isolated-web-runtime.md)) |
|
||||
| Date | 2026-10-26 |
|
||||
| Related | [web-invoke-serialization.md](../design/web-invoke-serialization.md) · [ADR 0009](0009-isolated-web-runtime.md) · ADR [0004](0004-web-plugin-go.md) · ADR [0007](0007-web-document-endpoint.md) · [ext-abi.md](../design/ext-abi.md) · [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Go `plugins/web` 的 HTTP 服务是**多 goroutine** 的:每个请求可并发进入 `handleInvoke` / `handleInvokeLiveSSE`。
|
||||
- 每个 Endpoint 最终经 C ABI `host_query("call_lib_path", …)` 回到 Rust 宿主,在**同一个** `HostContext`(Marqdo 解释器状态)上执行作者 `.mq.md`。
|
||||
- `HostContext` **不是** `Sync`:共享可变会话、库装载、写回、事件总线等状态不能安全地被多线程同时求值。
|
||||
- 因此宿主用进程级 `INVOKE_LOCK`(`src/host/plugin.rs`)串行化所有来自 worker 线程的 `call_lib_path`。
|
||||
|
||||
### 常见误解
|
||||
|
||||
> 「web 都是单线程的吗?不能多线程吗?」
|
||||
|
||||
| 层 | 并发模型 |
|
||||
|----|----------|
|
||||
| Go HTTP / SSE flush / 取消 | **多线程(多 goroutine)** |
|
||||
| Marqdo 解释器 `call_lib_path` | **单飞(一把全局锁)** |
|
||||
| 浏览器 UI | 与后端锁无关;但若短 API 同步阻塞等待锁,会表现为「整页卡死」 |
|
||||
|
||||
**缺陷不在「HTTP 单线程」,而在「多 HTTP 工作线程共享一个非 Sync 解释器」。**
|
||||
真并行需要多解释器实例(或可共享的隔离运行时),不是去掉 Go 侧并发。
|
||||
|
||||
### 事故形态(已观测)
|
||||
|
||||
长对话(`return=sse-live` / `stream:true`)在 `CallLibPath` 期间一直持有 `INVOKE_LOCK`。并发的短路由(如 `/v1/models`、设置页探测)在旧实现里对锁 **无限期** `lock()`,HTTP 挂起 → 前端 `fetch` 无超时 → 页面无响应。重启进程可恢复,但属于运维掩盖,不是正确错误处理。
|
||||
|
||||
## Decision
|
||||
|
||||
1. **承认并文档化**本限制为宿主架构缺陷(单 `HostContext` + 全局 `INVOKE_LOCK`),不得再被表述为「web 插件只能单线程」。
|
||||
2. **缓解(已实现,非根治)**:
|
||||
- `call_lib_path` 从 worker 进入时用 **限时 try-lock**(默认 `MARQDO_INVOKE_WAIT_MS=1500`),超时返回错误串 `interpreter busy: …`。
|
||||
- Go `handleInvoke` 将含 `interpreter busy` 的错误映射为 **HTTP 503**,并设 `Retry-After: 2`。
|
||||
- **禁止**在 SSE 期间把进程级 `MARQDO_INVOKE_WAIT_MS` 拉长:那会让并发短请求重新卡死。
|
||||
- 长 SSE 在启动时用同一短预算争锁;一旦拿到则持有至调用结束(对话本来就要跑完)。
|
||||
3. **客户端契约**:短 API 必须有超时与 503 文案;不得假设「任意时刻都能同步进入解释器」。
|
||||
4. **根治(未决,另案)**:解释器池 / per-request isolate / 可 `Send` 的会话切片。未落地前,产品行为以本 ADR 的 503 语义为准。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 对话进行中,设置/模型列表等短请求约 1.5s 内失败并可读,UI 不再无限挂起。
|
||||
- 缺陷有名有姓,后续多解释器工作不会被「修好了」的假象挡住。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- 同一进程仍无法真正并行跑两个 Marqdo Endpoint 体;第二个长 SSE 也会在短预算后失败。
|
||||
- 极短窗口内,短请求若正好撞上锁交接,可能偶发 503(可重试)。
|
||||
- `MARQDO_INVOKE_WAIT_MS` 是进程环境变量;误设过大仍会复现卡顿。
|
||||
|
||||
### Neutral
|
||||
|
||||
- Go 多 goroutine、SSE 桥(`MARQDO_EVENT_FORWARD`)、取消令牌(`MARQDO_CANCEL_TOKEN`)保持不变。
|
||||
- 不改变 Document / Endpoint 作者面(ADR 0007);只约束宿主与 web 插件错误语义。
|
||||
|
||||
## Implementation pointers
|
||||
|
||||
| 位置 | 职责 |
|
||||
|------|------|
|
||||
| `src/host/plugin.rs` → `acquire_invoke_lock` | 限时争锁;失败 `set_err("interpreter busy…")` |
|
||||
| `plugins/web/.../routes_invoke.go` → `handleInvoke` | `interpreter busy` → 503 + `Retry-After` |
|
||||
| 设计长文 | [web-invoke-serialization.md](../design/web-invoke-serialization.md) |
|
||||
@@ -0,0 +1,33 @@
|
||||
# ADR 0009: Isolated Web Runtime (worker process pool)
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**;HTTP **execute** 路径正式替代 [ADR 0008](0008-web-invoke-serialization.md) 的并行性结论。`legacy_serial`(未声明且非流式)仍引用 0008 单飞 / 父进程 `CallLibPath`。 |
|
||||
| 日期 | 2026-10-26(修订 2026-10-27:disconnect≠cancel;control/read/short 无父锁) |
|
||||
| 设计 | [isolated-web-runtime-development-2026-10-26.md](../design/isolated-web-runtime-development-2026-10-26.md) |
|
||||
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝;disconnect-keeps-running;control-under-dual-execute) |
|
||||
|
||||
## 背景
|
||||
|
||||
ADR 0008 确认:Go HTTP 多线程,但所有 Endpoint 共享一把解释器锁与进程级 SSE 桥环境变量。1500ms busy → 503 只是缓解,不是并行。
|
||||
|
||||
## 决策
|
||||
|
||||
1. **首选架构**:预热的一次性 Marqdo worker 进程池;每个租约独占一个进程与 HostContext。
|
||||
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` / body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);**禁止**父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。声明的 `short`/`read`/`control` 走父进程短路径(execute 已离进程,父锁通常空闲);未声明非流式 → `legacy_serial`。
|
||||
3. **控制/读取分离**:`/_runtime/*`(cancel、events、task get)不进入解释器锁。短读勿挤占 execute worker 槽(池默认 2);产品 cancel 优先 `/_runtime`。
|
||||
4. **订阅 ≠ 取消**:`sse-live` 观察者 `ctx.Done()` 默认**只结束订阅**,不 `runtime.cancel`;后台仍 reap worker 以释放槽。仅显式 header `X-Marqdo-Cancel-On-Disconnect: 1` 才 disconnect=cancel。同步 `waitIsolatedJSON` 可保留 disconnect 取消。重连:`GET /_runtime/tasks/{id}/events` + `Last-Event-ID` / `after_seq`。
|
||||
5. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
|
||||
6. **能力探测**:`runtime.isolated_execution=1`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane=1`(短读不与 execute 抢父锁)。
|
||||
7. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
|
||||
|
||||
## 后果
|
||||
|
||||
- Execute / live SSE 不再抢进程级 SSE 桥;双流可并行(MR-01)。
|
||||
- 短读走父进程:在 dual execute 下通常仍 200(父锁空闲);勿把 short/read/control 塞进 2 槽 execute 池。
|
||||
- Legacy 未声明非流式路径仍可走父进程锁(ADR 0008)。
|
||||
- 产品(qdagent)`turn_events` / Last-Event-ID / cancel CAS 接线由 qdagent 验收;框架侧 disconnect≠cancel 与 `/_runtime` 无锁控制面已落地。
|
||||
|
||||
## 验收(摘要)
|
||||
|
||||
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`、`runtime.read_lane=1`。观察者断连后任务仍跑完并可经 `/_runtime` 重放。其余见设计文档 §12。
|
||||
@@ -0,0 +1,348 @@
|
||||
# Marqdo 智能体能力补足:恢复、工具、上下文与资源视图
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed**;本次交付设计,不代表以下新接口已实现 |
|
||||
| 日期 / 基线 | 2026-10-27(Asia/Shanghai);Marqdo `16f26d7` / 2.1.4;qdagent `68b757e` |
|
||||
| 调研与现状 | [官方资料与源码证据 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品配套 | [qdagent 智能体能力与预览设计](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 继承 | [ext/agent](ext-agent.md)、[隔离 Web 运行时](isolated-web-runtime-development-2026-10-26.md)、[工作台合同](qdagent-workbench-runtime-and-view-2026-10-25.md) |
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;让工具可发现、可验证、可审计;让结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位,不把框架改成第二套产品聊天服务。
|
||||
|
||||
现有 `src/runtime/` 已实现隔离进程、任务/事件与控制通道,本设计在其上补 Agent 步骤语义。现有 `ext/ai/agent.mq.md` 已有 step/plan/run、CALL/READ、观察压缩,继续扩展。框架不持有求道“笔记”业务表、中文按钮、默认回答字数或具体供应商账户。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | 错误分类、预算、检查点、工具效应、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | 结果分通道、输出预算、角色消息、finish reason | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD 行为 |
|
||||
| 资源 | ResourceRef、只读内容/派生预览、定位、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览组件和布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
APP[qdagent 产品策略与授权] --> RUN[ext/ai/agent step / plan / run]
|
||||
RUN --> CTX[ContextPack 与预算]
|
||||
RUN --> LLM[LLM Adapter]
|
||||
RUN --> DISPATCH[Tool Dispatcher]
|
||||
DISPATCH --> LOCAL[受控 Marqdo 函数]
|
||||
DISPATCH --> MCP[MCP Client]
|
||||
DISPATCH --> RES[资源读取 / 转换]
|
||||
RUN --> REC[Checkpoint / Effect Ledger]
|
||||
REC --> RT[既有 runtime task store / event log]
|
||||
RUN --> OUTPUT[answer / artifact / progress / diagnostic]
|
||||
RES --> VIEW[DocumentView / ResourceView]
|
||||
OUTPUT --> APP
|
||||
VIEW --> APP
|
||||
```
|
||||
|
||||
## 2. 现状与增量
|
||||
|
||||
| 已有能力 | 本轮不能误判为缺失 | 要补的具体语义 |
|
||||
|---|---|---|
|
||||
| runtime.task_control_v2/event_replay/read_lane | 不再新建一套队列与 SSE 框架 | Agent 步骤恢复与传输重放的边界 |
|
||||
| resume_save/load | 不再新建平行 checkpoint 命名空间 | 原子提交、版本摘要、作用域、效应关联 |
|
||||
| CALL、ARGS、READ、plan patch | 不废弃文档式编排 | 类型化 schema、校验错误、有限修复、稳定 call_id |
|
||||
| MCP stdio client | 不从零重写连接器 | timeout/cancel、resource、远程 transport 的能力探测 |
|
||||
| DocumentViewV1 / Locator | 不另写 `.mq.md` 解析器 | 普通资源类型、明确 renderer、历史与相对资源处理 |
|
||||
| LLM messages/usage | 不把 provider 行为交给产品猜测 | 输出预算、原生工具适配探测、角色边界与分通道 |
|
||||
|
||||
新模块路径及协议名以下均是**建议落点**。首批开发先固化 schema 与 fixture,再开放 feature bit;不得只更新 capabilities 把未实现能力标真。
|
||||
|
||||
## 3. 错误和恢复合同
|
||||
|
||||
### 3.1 ErrorV1
|
||||
|
||||
现有字符串错误保留兼容适配,新工具与 Agent 结果返回:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentErrorV1",
|
||||
"code": "tool.timeout",
|
||||
"category": "transient",
|
||||
"stage": "tool",
|
||||
"message": "读取资源超时",
|
||||
"retryable": true,
|
||||
"retry_after_ms": 1200,
|
||||
"effect_state": "none",
|
||||
"recovery_action": "retry_step",
|
||||
"call_id": "call_01",
|
||||
"details_ref": "resource:diagnostic_01"
|
||||
}
|
||||
```
|
||||
|
||||
`retryable` 仅是候选信息,最终动作由可信策略结合效应、截止时间、预算、取消状态决定。远端工具声称 readOnly/idempotent 不构成授权依据。凭证和原始堆栈不进入公开 message。
|
||||
|
||||
| 错误类别 / 例子 | 框架动作 | 不允许的动作 |
|
||||
|---|---|---|
|
||||
| transient:429、部分 5xx、连接失败 | 只在安全步骤重试,遵守 Retry-After | 无限重试、复用同一流片段直接追加 |
|
||||
| invalid_arguments:schema 不匹配 | 把字段级错误作为 observation,最多 1 次参数修复 | 启动工具后才校验;静默丢弃字段 |
|
||||
| validation_failed:编译/文档校验 | 保留候选与诊断,局部修复后重新验证 | 将未验证草稿标为成功 |
|
||||
| context_overflow | 压缩可重建上下文,保留任务/限制/未决效应 | 丢失最新用户指令、授权或版本 |
|
||||
| auth / forbidden | 直接 needs_input/blocked,交应用处理 | 换身份、扩大范围或匿名绕过 |
|
||||
| conflict / stale_revision | 重新读取版本并重新规划 | 覆盖用户修改、对写操作盲重试 |
|
||||
| capability_unavailable | 返回可行替代操作清单 | 假称已搜索、已渲染或已执行 |
|
||||
| policy_denied | 显式拒绝该动作 | 把限制当工具错误让模型规避 |
|
||||
| budget_exhausted | 保存状态与已完成结果,返回 partial | 自动增预算或伪造 completed |
|
||||
| unknown_effect / worker_crash | 对账、查询外部状态,不能判断则 needs_reconciliation | 重跑整个工作簿 |
|
||||
| cancelled | 停止新调用、保留可读产物、传播取消 | 在后台悄悄修复或恢复 |
|
||||
|
||||
初始建议:传输最多 2 次重试(总 3 次尝试),指数退避基准 0.5/1 秒并加 jitter;有 Retry-After 时使用服务端建议并受总 deadline 限制。参数修复最多 1 次,内容修复最多 2 次。预算由应用传入,框架只提供默认上限与执行机制。所有重试、修复和摘要模型调用计入同一成本账本。
|
||||
|
||||
错误指纹 `hash(tool_id, normalized_arguments, error_code, relevant_revision)` 连续出现 2 次且没有新证据时中止该策略,允许一次有依据的替代路径;不能通过改写错误文本绕过循环检测。
|
||||
|
||||
### 3.2 四类“恢复”必须分开
|
||||
|
||||
1. **续订事件**:客户端从 cursor 重放和订阅同一个 task,不发起新推理。
|
||||
2. **重试步骤**:相同逻辑 operation、同幂等键;新 invocation attempt,复用成功的前序结果。
|
||||
3. **恢复工作流**:从兼容 checkpoint 建立新 runtime task / attempt,关联 `resumed_from`,不把旧终态改回 running。
|
||||
4. **重新生成答案**:新的输出版本;已有成功工具结果可复用,用户明确重新执行才重新产生效应。
|
||||
|
||||
当前 TaskState 把 interrupted/needs_reconciliation 视为终态,沿用此约定。新增 `AgentRun` 逻辑关联只管理目标和 attempt 链;调度权仍在原 runtime。恢复请求带 `expected_revision`、checkpoint digest 与幂等键,相同请求返回同一新 attempt,冲突返回 409 对应的框架错误。
|
||||
|
||||
执行失败不必丢掉有用内容:`outcome.status = succeeded | partial | failed | needs_input | cancelled`,伴随 `answer_ref/artifacts/error/recovery_options`。HTTP 调用成功与 Agent 业务 succeeded 不再混为同一字段。
|
||||
|
||||
## 4. 检查点与工具效应
|
||||
|
||||
### 4.1 CheckpointV2
|
||||
|
||||
在 `plugins/agent/src/resume.rs` 扩展已有实现,统一根目录由宿主提供,客户端不能传任意绝对路径。保留 legacy load,但旧 checkpoint 无效应信息时默认 `manual_review`,不能自动重做写操作。
|
||||
|
||||
| 字段组 | 内容 |
|
||||
|---|---|
|
||||
| 身份 | schema、checkpoint_id、logical_run_id、task_id、attempt_id、step_id、parent_checkpoint_id |
|
||||
| 作用域 | principal_ref、workspace_id、session_id、授权 scope digest |
|
||||
| 输入 | task revision、workbook revision/hash、输入资源 revisions、knowledge generation |
|
||||
| 运行配置 | ModelSnapshot public ref、tool registry digest、policy revision、runtime compatibility |
|
||||
| 进度 | completed_steps、pending_operation、observation refs、context summary ref |
|
||||
| 约束 | 剩余 token/tool/time/cost 预算、deadline、cancel epoch |
|
||||
| 一致性 | effect ledger watermark、event seq、manifest digest、committed_at |
|
||||
|
||||
写入协议:写唯一临时文件→flush/fsync→原子 rename→提交 checkpoint 指针;持久化配置下目录 fsync 按平台支持实现。所有引用 blob 在指针提交前落盘。损坏记录报 `checkpoint.corrupt` 并尝试上一个完整版本,不能读取半个 JSON 当无历史。
|
||||
|
||||
恢复前校验身份/授权、源版本、工具 schema 与模型兼容性。权限撤销立即生效;checkpoint 不是永久授权。源文件改变返回 `checkpoint.input_changed`,重新计划受影响步骤,不能偷偷使用最新文件继续旧验证结果。
|
||||
|
||||
### 4.2 Effect ledger
|
||||
|
||||
```text
|
||||
prepared → started → committed
|
||||
↘ failed_no_effect
|
||||
↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
|
||||
```
|
||||
|
||||
每个 operation 持久记录 `operation_id/idempotency_key/args_digest/resource_scope/expected_revision/effect_class/result_ref`。幂等键作用域是 principal + workspace + logical_run + step + operation,不用随机 attempt ID 替换稳定 operation key。对同 key 不同 payload 拒绝。
|
||||
|
||||
读工具可重试;确定幂等写由服务端去重;可补偿写仅在补偿明确安全时执行;未知写先查询 receipt/版本。对外部系统不能承诺通用 exactly-once。关键 crash 窗口是“远端已成功、本地尚未记账”,必须返回 unknown 并对账。
|
||||
|
||||
本地文件使用 expected revision + staging + atomic replace;变更提交后检查点失败也靠 operation receipt 恢复。`tool.completed` 必须在结果与 receipt 可读取后提交,再对外发事件。事件发送失败不回滚已发生的业务效应。
|
||||
|
||||
不要复制 runtime 事件存储:Agent ledger 与 artifact manifest 是步骤事实,现有 runtime event log 是传输/调度事实;以 ID 关联,采用可重建投影与 outbox。跨 DB/文件不能声称一个事务完成,使用 manifest 提交点和恢复扫描补齐索引。
|
||||
|
||||
## 5. 结构化工具与调度
|
||||
|
||||
### 5.1 ToolSpecV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ToolSpecV1",
|
||||
"id": "workspace.read",
|
||||
"version": "1",
|
||||
"description": "读取授权资源的指定行范围",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"resource_id": {"type": "string"},
|
||||
"revision": {"type": "string"},
|
||||
"start_line": {"type": "integer", "minimum": 1},
|
||||
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
|
||||
},
|
||||
"required": ["resource_id"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"output_schema_ref": "ResourceReadV1",
|
||||
"effect": "read",
|
||||
"scopes": ["workspace:read"],
|
||||
"timeout_ms": 10000,
|
||||
"max_result_bytes": 65536,
|
||||
"idempotency": "safe",
|
||||
"concurrency_group": "resource-read",
|
||||
"availability": "ready"
|
||||
}
|
||||
```
|
||||
|
||||
定义由宿主/可信模块注册;用户认证、scope 与资源根由宿主注入,不接受模型提供 principal 或任意 root。`read`、`write`、`execute`、`external_write` 是策略分类,不是靠工具命名推断。
|
||||
|
||||
ToolCallV1:`call_id/tool_id/tool_version/arguments/operation_id/parent_span_id`。ToolResultV1:`ok/status/summary/structured_content/resources/citations/error/usage/truncated/next_cursor/effect_receipt_ref`。超限结果先写 artifact,再返回摘要和范围读取句柄;不把几十 MB 文本送进 prompt。
|
||||
|
||||
### 5.2 一条执行通道
|
||||
|
||||
```text
|
||||
发现 → 加载 schema → schema 校验 → 授权与范围解析 → 预算/取消检查
|
||||
→ 幂等查询 → 执行 → 结果 schema/大小校验 → receipt/结果提交 → 事件 → observation
|
||||
```
|
||||
|
||||
provider 原生 function call 与文档 `CALL:name + ARGS:{...}` 都归一到该通道。保留旧白名单适配,已有 `.mq.md ##` 可根据形参推导初始 schema,再允许显式描述收紧。转换不允许调用未暴露的框架内部函数。禁止对模型参数使用 eval/任意代码反序列化。
|
||||
|
||||
`tools.search` 返回已授权且当前可用的工具摘要;`tools.describe` 按 ID 返回完整 schema。核心 5–8 个工具可常驻,其余按需加载;此数量是产品起始配置,不写死框架。每次真正调用仍重新检查授权;搜索索引可列 unavailable 原因供诊断,但不能让未授权工具名字泄露私有连接信息。
|
||||
|
||||
初始支持 JSON Schema 的明确子集并公开能力;不支持的 schema 拒绝注册,不静默放宽。原生工具能力、并行工具调用、图片输入、结构化输出分别探测;纯文本兼容 provider 继续走 CALL,但并发和可靠性承诺按测试能力开放。
|
||||
|
||||
### 5.3 并发、MCP 与程序化执行
|
||||
|
||||
独立只读调用可并发,默认最多 4 个;修改同一资源的调用串行且用 revision CAS。依赖链、审批与取消检查保持顺序。一个并发调用失败不丢弃其他已成功结果。
|
||||
|
||||
MCP 扩展现有 client:先完善 timeout/cancel、错误映射、工具分页与 schema、resource read/link,再按 capability 增加远程 Streamable HTTP 与连接认证。stdio 不应允许模型选择任意宿主可执行文件。连接元数据归应用,凭证通过 secret handle 注入 worker,工具输出和 trace 不记录密钥。
|
||||
|
||||
工具 annotations 只是提示,可信策略确定真实效应。外部结果全部为数据,不能提升为 standing/system。MCP resource URI 转成宿主授权 ResourceRef,不允许前端直接请求任意 file:// 或内部网地址。
|
||||
|
||||
程序化工具编排和子 Agent 为后续切片:在沙箱中仅暴露注册 dispatcher,逐次执行同样的授权、预算和效应日志;禁止通过一段脚本绕过逐工具控制。子任务继承更小权限和共享总预算,不默认开放写同一资源。
|
||||
|
||||
## 6. 输出通道与上下文
|
||||
|
||||
### 6.1 AgentOutputV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentOutputV1",
|
||||
"status": "succeeded",
|
||||
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
|
||||
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
|
||||
"citations": [],
|
||||
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
|
||||
"finish_reason": "completed",
|
||||
"recovery_options": []
|
||||
}
|
||||
```
|
||||
|
||||
这是结果传输协议,不要求模型每次逐字生成这张 JSON。文档式编排仍可产出 `.mq.md`,框架把稳定产物、摘要与事件归一化。普通文本回答可没有 artifact 和 validation;未运行的内容标 `not_applicable/not_run`,不能填 passed。
|
||||
|
||||
channel 至少区分 `answer/artifact/progress/diagnostic`。只有 answer delta 可追加到聊天正文;工作簿 token 和工具日志进入其他通道。进度是可观察动作摘要,不要求或泄露模型内部思维链。
|
||||
|
||||
应用传 `ResponsePolicy`:detail level、目标长度、最大输出 tokens、是否允许 artifact、用户显式需求。框架负责 budget 和 finish_reason,中文字符数与最终文案由应用决定。达到 token 上限返回 `length_limited` 和完整/不完整标记,不能裁剪 JSON/代码后假装成功。
|
||||
|
||||
优先从已验证产物结构投影摘要。必要时增加一次受预算控制的摘要模型调用;摘要不得新增未经证据支持的结论。修复成功后 accepted candidate、结果正文、artifact revision 与 verification digest 必须全部一致。
|
||||
|
||||
### 6.2 ContextPackV2
|
||||
|
||||
按优先级组装:可信运行规则→最新用户目标/约束→用户选中资源范围→未决操作/成功步骤摘要→检索证据→近期对话→可回读历史。保持角色结构,不把用户/工具文本简单拼进系统指令。
|
||||
|
||||
每个 item 携带 `origin/trust/resource_ref/revision/token_estimate/priority`。预算初值建议保留模型窗口 20% 给输出与协议开销;上下文使用达到可用预算 70% 时触发整理,具体比例配置化。优先剔除可重读的完整工具输出,保留摘要、引用和失败恢复锚点。
|
||||
|
||||
Compaction 必须保留:目标、用户限制、当前计划、已完成步骤、待决写入、授权范围、输入版本、已接受产物与引用、余量。summary 绑定其 source event range 和 digest,不能当成新的已验证知识。工具输入过时须重读,不能依赖压缩摘要执行写入。
|
||||
|
||||
已有 EKC/agent memory 继续提供知识发现和复用。长期用户记忆的创建/修改/删除政策归 qdagent;网页中的指令不能自动变成长期偏好。
|
||||
|
||||
## 7. 统一资源与只读视图
|
||||
|
||||
### 7.1 ResourceRefV1 / ResourceViewV1
|
||||
|
||||
ResourceRef 统一携带 `resource_id/workspace_id/kind/media_type/revision/digest/title/size/origin/locator`;opaque ID 由宿主映射,不将浏览器 path 直接当文件权限。revision 是内容版本,generation 是知识发布代,两者不混用。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ResourceViewV1",
|
||||
"resource": {
|
||||
"resource_id": "res_01", "workspace_id": "ws_01", "kind": "file",
|
||||
"revision": "sha256:example", "media_type": "text/markdown", "title": "设计说明"
|
||||
},
|
||||
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
|
||||
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
|
||||
"outline": [],
|
||||
"locators": [],
|
||||
"completeness": "complete",
|
||||
"no_exec": true,
|
||||
"diagnostics": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
```
|
||||
|
||||
继续把 `.mq.md` 交 `view.document`,ResourceView 只包装/扩展,不能另解释一套 Marqdo 语义。普通 `.md/.txt/代码/JSON/CSV` 走媒体类型处理,避免全仓语义编译。浏览器组件由 qdagent 实现,框架只提供可读内容、受控片段或短期授权 blob 引用。
|
||||
|
||||
`fragment`、`text`、`blob_ref` 是互斥载荷,按严格 format enum 解码。未知格式返回 unsupported,不能用 `format.includes('html')` 猜测 HTML。为空与加载失败必须有独立状态。
|
||||
|
||||
### 7.2 格式矩阵
|
||||
|
||||
| 格式 | 框架提供 | 前端消费 | 未具备能力时 |
|
||||
|---|---|---|---|
|
||||
| `.mq.md` | 静态 DocumentView、outline、节点/引用 | 正文、语义链接、源码切换 | 只读源码 + 明确诊断,不执行 |
|
||||
| Markdown / 笔记正文 | 共享静态 Markdown→受控结构/HTML、相对资源引用 | 标题、列表、表格、代码、链接 | 纯文本 |
|
||||
| 文本/代码 | 分页行片段、编码信息、行定位 | 行号与语法高亮 | 编码提示/下载 |
|
||||
| JSON / CSV | 有界解析、路径/行列定位、分页 | 树/表/源码 | 原始文本,标格式错误 |
|
||||
| 图片 | 授权 blob、尺寸/元信息 | 缩放/旋转/替代文本 | 下载,不暗示已做 OCR |
|
||||
| PDF | blob、页元信息,可选提取插件 | PDF.js 页渲染与定位 | 文件卡;提取不可用不阻止支持的视觉预览 |
|
||||
| DOCX/XLSX/PPTX | 受限转换插件,可选 PDF/HTML 派生物 | 按派生格式预览 | 未安装转换器,保留下载 |
|
||||
| HTML/SVG | 默认源码;允许时经严格清洗或受限派生物 | 隔离预览 | 不以内联可执行页面显示 |
|
||||
| 未知二进制/压缩包 | 元数据 | 下载卡 | 不自动解压/执行 |
|
||||
|
||||
提取、预览、执行各有独立 capability。办公转换、OCR 使用受限 worker,禁宏与网络、限制时间/内存/页数/解压膨胀比;结果绑定原件 digest、转换器版本和参数。首期不承诺保真编辑。
|
||||
|
||||
### 7.3 安全、定位、缓存
|
||||
|
||||
所有读取先校验宿主授予的 workspace/resource scope,canonicalize 并处理 symlink 逃逸;读取句柄与校验对象一致,防路径检查后替换。读取原件的身份权限不可被缓存绕过。
|
||||
|
||||
预览绝不调用 `run/verify` 或有执行副作用的 view 路径;正文中的 Marqdo 调用链接只展示语义与导航,执行需单独工具调用与授权。远程图片、相对链接、资源 URL 经受控解析;下载入口不允许任意内网 fetch。
|
||||
|
||||
HTML 清洗在框架产出侧和浏览器插入侧都有明确边界;用成熟 allowlist 实现而非正则。禁止 script/event handler、危险 URI、任意 style/form/嵌入对象。前端配 CSP;对需要交互的产物另建无权限 sandbox,不复用文档渲染器。
|
||||
|
||||
缓存 key:workspace + resource ID + revision + renderer version + render options + policy version;命中前重新授权。历史 revision 不存在就返回 `version_unavailable`,不能默默展示当前版。locator 支持 node/span/line/page/cell,失效时标 stale 并提供用户主动查看最新版的操作。
|
||||
|
||||
建议首期限制:文本片段 256 KiB、代码单次 500 行、CSV 单次 200 行;更大内容分页,完整文件保留。数值需压测校准,不作为现有系统性能声明。
|
||||
|
||||
## 8. 事件、可观测性与能力协商
|
||||
|
||||
复用 RuntimeEventV2 的 task/run/attempt/seq/event_id。拟增加事件类型:`agent.step.started/completed`、`tool.started/completed/failed`、`recovery.scheduled/exhausted`、`checkpoint.committed`、`artifact.updated`、`answer.delta/committed`、`context.compacted`。现有 `message.delta` 由兼容适配映射 answer channel,不能同时重复消费两套事件。
|
||||
|
||||
终态提交包含 accepted output manifest、last_seq、result digest;断流客户端能通过快照补齐最终答案。stream delta 是预览,最终 committed revision 是权威。统计每次尝试的 usage,摘要和修复调用分别标 purpose;未知计量保持 unknown。
|
||||
|
||||
拟新增 capability:`agent.error_v1`、`agent.checkpoint_v2`、`agent.tool_schema_v1`、`agent.output_channels_v1`、`agent.context_pack_v2`、`resource.view_v1`,以及各 media renderer 的独立版本/可用状态。保持现有 probe,新增字段向后兼容;未知 feature 当不可用。
|
||||
|
||||
trace 记录因果 ID、耗时、错误类别、参数摘要、资源版本和 effect receipt。正文与密钥按配置脱敏,不默认把用户全文件复制进日志。输出中不包含模型私有推理;可审计的是实际动作与结果。
|
||||
|
||||
## 9. 分阶段实现与文件落点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 依赖 / 退出条件 |
|
||||
|---|---|---|---|
|
||||
| M-A0 | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | 上述协议、旧适配、状态映射 | 先冻结跨仓字段,未知字段/版本可降级 |
|
||||
| M-A1 | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、新 recovery/effects 支撑模块 | 分类错误、有界修复、accepted candidate、原子检查点 | M-A0;故障注入不重复写、旧记录不冒险自动恢复 |
|
||||
| M-A2 | `plugins/agent/src/lib.rs`、`mcp_client.rs`、新 tool registry/dispatcher | schema 工具、调用统一、分页与结果资源 | M-A0;未授权调用为 0,失败结果结构正确 |
|
||||
| M-A3 | `src/workbench/document_view.rs`、新 resource_view、媒体适配模块 | ResourceRef/View、普通格式静态阅读、no-exec | M-A0;资源定位与安全语料通过 |
|
||||
| M-A4 | `ext/ai/agent.mq.md`、`plugins/llm/src/lib.rs`、`src/workbench/run_context.rs` | 输出分通道、预算、ContextPackV2 | M-A1/2;原生和纯文本 provider fixture 都可用 |
|
||||
| M-A5 | `src/runtime/` 的既有存储/事件适配、MCP 与转换插件 | 恢复对账、PDF/Office 插件、远程 MCP | M-A1/2/3;持久模式 crash/restart 通过 |
|
||||
| M-A6 | plan/subtask/sandbox 扩展 | 程序化工具、有界委派与可选浏览器 | 后置;须证明任务收益和预算/效应可控 |
|
||||
|
||||
先交 M-A0 与 qdagent P0 的静态阅读/错误结果修复;不要让完整 checkpoint v2 阻塞笔记预览。M-A1 可先上只读重试,写恢复待 ledger 通过再开放。新特性默认关闭直到对应合同实测通过,旧路径继续可读。
|
||||
|
||||
## 10. 验收与评测
|
||||
|
||||
所有目标是 proposed gate,尚未实测。基础机制用确定性 fake provider/tool;真实 provider 做少量单独 smoke 并记录费用,不能把随机模型输出作为唯一门禁。
|
||||
|
||||
| 编号 | 故障/任务 | 必须观察到的结果 |
|
||||
|---|---|---|
|
||||
| MA-T01 | 第一次 429、第二次成功 | 尊重退避、计量 2 次、最终只有一个 accepted answer |
|
||||
| MA-T02 | 连续 schema 参数错误 | 一次修复后停止;工具未在无效参数下执行 |
|
||||
| MA-T03 | 工具写成功但 receipt 提交前杀 worker | unknown_effect→查询对账;写计数不增加 |
|
||||
| MA-T04 | checkpoint 写一半杀进程 | 读取上个完整 checkpoint 或明确 corrupt,不产生伪成功 |
|
||||
| MA-T05 | 终态事件丢失、cursor 重放 | 最终快照恢复完整消息,工具执行次数不增加 |
|
||||
| MA-T06 | 恢复请求重复/并发 | 同一幂等键只产生一个恢复 attempt |
|
||||
| MA-T07 | 用户取消与重试定时器竞争 | 取消生效后无新工具调用,旧任务不复活 |
|
||||
| MA-T08 | 执行中资源/权限改变 | stale/conflict/forbidden,不覆盖新版本 |
|
||||
| MA-T09 | 恶意文本伪造 CALL/system | 不跨越工具白名单和授权范围 |
|
||||
| MA-T10 | `.mq.md` 预览含写文件/联网语句 | 哨兵文件/网络计数不变;只读渲染成功或安全降级 |
|
||||
| MA-T11 | 资源格式、超长输出、路径逃逸 | 正确 renderer/分页;越界拒绝;无 HTML 注入 |
|
||||
| MA-T12 | 修复原文 A 得到通过验证的 B | answer/artifact/verification 都绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后继续 | 最新约束、待决效应、资源版本与剩余预算不丢失 |
|
||||
| MA-T14 | 旧 CALL、旧 DocumentView 消费端 | 基础行为可用,能力缺失有明确返回 |
|
||||
|
||||
先运行受影响的 Rust/Go/Marqdo 合同与既有隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标:已缓存 100 KiB 文本视图服务端 p95 < 300 ms、核心工具发现 p95 < 100 ms,基准机器/并发/冷暖缓存必须记录;第三方网络延迟单独列出。
|
||||
|
||||
## 11. 迁移、回滚与未决项
|
||||
|
||||
兼容迁移按“新增协议→双读→新写→验证→逐步移除旧适配”推进。`.mq.md` 源码与旧运行产物不批量重写;旧 resume JSON 可读取但不能自动升级成带副作用保证的检查点。v2 checkpoint/ledger 保留 schema 版本,新老版本不并发写同一运行。
|
||||
|
||||
回滚关闭新工具自动发现、输出通道或转换器时,已提交资源和最终答案仍可读;执行恢复中的任务先 drain/停止接纳,不能切回会盲重做写操作的旧路径。迁移前备份可变索引与 manifest,回滚不删除用户产物。
|
||||
|
||||
实现前验证项:现有 runtime 持久存储可提供的原子提交边界、各平台 fsync/rename 行为、LLM adapter 原生 tool call 流式兼容、转换插件部署体积。协议优先按本文保守语义实现,验证不能满足则 feature 保持不可用,不阻塞已经完成的只读预览切片。
|
||||
@@ -0,0 +1,252 @@
|
||||
# 语义评估:参数能否从上下文推断(含叙述式调用)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留参数来源可见、避免隐藏调用者环境的边界;下文已被否决的 L0 建议不可重新启用。自然语言只连接和解释,不能成为隐式执行触发器;当前指导见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「让函数参数从上下文推断,`对**n=31**执行**加一函数**` 这种写法可能吗」 |
|
||||
| 方法 | 运行时实测 8 组 + 全仓库语料扫描(1322 个函数)+ 源码比对 |
|
||||
| 相邻 | [call-syntax-from-marks.md](call-syntax-from-marks.md)(**接替本文 §3 的设计**)· [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
|
||||
|
||||
> **后续更正**:本文 §3 提出的 L0「叙述式调用」用**未标记的词**(`执行`)触发调用,
|
||||
> 这会破坏「叙述默认安全、只有标记才执行」的底层原则,已被否决。
|
||||
> 在「只执行标记」约束下重新设计的调用语法见
|
||||
> [call-syntax-from-marks.md](call-syntax-from-marks.md)
|
||||
> (含树遍历 vs 字节码 3.8× 实测、叙述顺序导致位置绑定翻转的实验)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论:你的示例其实**不需要**隐式推断
|
||||
|
||||
先把一个关键事实摆出来:**你的例子里 `n=31` 明明写在那儿**。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
对**n=31**执行**加一函数**
|
||||
```
|
||||
|
||||
`n` 的绑定**就写在句子里**,这不是「从上下文推断」,这是**具名实参换了语序**。
|
||||
所以这个写法需要的是**新的叙述式调用语法**,不是新的作用域语义。
|
||||
|
||||
它今天跑出来的结果很能说明问题:**无输出、无报错、退出码 0**。
|
||||
不是参数推断失败,而是 `执行**加一函数**` 里的裸名字**只是被求值然后丢弃**,
|
||||
从来没被当成一次调用。
|
||||
|
||||
三层拆解:
|
||||
|
||||
| 层 | 写法 | 需要什么 | 裁决 |
|
||||
|----|------|---------|------|
|
||||
| **L0 叙述式调用** | `对**n=31**执行**加一函数**` | 只要语法糖(绑定仍在句中) | ✅ **可做,且安全** |
|
||||
| **L1 就近绑定** | 上一行 `**n=31**`,下一行 `执行**加一函数**` | 段落级隐式作用域 | ⚠️ 能做但危险,不建议 |
|
||||
| **L2 真隐式** | 只写 `执行**加一函数**`,n 全靠上下文 | 动态作用域 | ❌ **不建议**,见 §4 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 实测:今天到底发生了什么
|
||||
|
||||
| # | 用例 | 实测 | 说明 |
|
||||
|---|------|------|------|
|
||||
| 1 | 你的示例原样 | **无输出、无报错、exit 0** | 静默 no-op |
|
||||
| 2 | 同样写法 + `> print text=`n`` | `main里的n=31` | **散文行里的 `**n=31**` 真的执行了** |
|
||||
| 3 | 只写 `对`加一函数`执行` | `done`,无报错 | 裸名字只被求值丢弃,**未调用** |
|
||||
| 4 | `**n = 31**` + `> 加一函数`(不传参) | `missing argument for parameter n` | **函数看不见调用者的 `n`** |
|
||||
| 5 | `> 加一函数 n=31` | `32` | 显式写法今天就能做 |
|
||||
| 6 | `# main` 读 frontmatter `税率` | `0.1` ✅ | 入口可见 |
|
||||
| 7 | `## 函数` 读同一个 `税率` | `undefined variable` ❌ | 函数不可见 |
|
||||
| 8 | 浏览器 WASM 入口调用函数 | metadata + `entry_bindings` **都会传** | 见 §5,**与 CLI 不一致** |
|
||||
|
||||
**第 2 与第 3 条合起来是关键**:散文行里的粗体确实会执行,但一个裸函数名在粗体里
|
||||
只是一个**表达式语句**(值算了就丢),不会变成调用。所以「看起来该调用」的句子,
|
||||
实际什么也没做——又是一次静默失败(与 D9 同一类)。
|
||||
|
||||
**第 4 条是语义基石**:Marqdo 现在的作用域是**严格分离**的,
|
||||
函数只能看到自己的形参与局部变量。你想要的 L2,就要拆掉这块基石。
|
||||
|
||||
---
|
||||
|
||||
## 2. 你自己的担心是对的:数据在这里
|
||||
|
||||
你提到「大项目变量名会难以使用」。我把仓库里 `lib/ ext/ examples/ tests/` 全扫了一遍:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 扫描函数数 | **1322** |
|
||||
| 不同形参名 | 819 |
|
||||
| **被 ≥5 个函数共用的形参名** | **130 个** |
|
||||
|
||||
撞车最严重的一批:
|
||||
|
||||
| 形参名 | 用它的函数数 |
|
||||
|--------|-------------|
|
||||
| `path` | **70** |
|
||||
| `value` | 59 |
|
||||
| `text` | 53 |
|
||||
| `id` | 47 |
|
||||
| `list` | 38 |
|
||||
| `内容` | 38 |
|
||||
| `路径` | 35 |
|
||||
| `a` / `b` | 各 32 |
|
||||
|
||||
结论很直接:**如果参数靠上下文推断,那么每次调用一个读 `text` 的函数,
|
||||
它都会去捡当前作用域里的 `text` 是什么**。53 个函数在等这个值——
|
||||
撞车是常态,不是例外。这不是「大项目才有」的问题,中型项目就已经不可控。
|
||||
|
||||
---
|
||||
|
||||
## 3. L0:叙述式调用(推荐做)
|
||||
|
||||
### 3.1 目标写法
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对`n`我们让**n=n+1**之后返回*n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 对 n=31 执行 加一函数**
|
||||
> print text=`结果` # → 32
|
||||
```
|
||||
|
||||
### 3.2 语义映射(零模型改动)
|
||||
|
||||
```
|
||||
对 <绑定子句> 执行 <函数名> ≡ Call { callee: <函数名>, args: [<绑定子句>…] }
|
||||
```
|
||||
|
||||
也就是**纯粹换语序**的语法糖。它与今天的
|
||||
|
||||
```markdown
|
||||
**结果 = > 加一函数 n=31**
|
||||
```
|
||||
|
||||
产出**同一个 `CallExpr`**。因此:
|
||||
|
||||
| 面 | 影响 |
|
||||
|----|------|
|
||||
| 契约校验(T2.1/T2.2) | **不变**(实参照常绑定与校验) |
|
||||
| EKC 指纹 `collect_calls` | **不变**(callee 仍是静态名) |
|
||||
| 字节码 `Op::Call(fid, argc)` | **不变** |
|
||||
| 序列化 / 沙箱 | **不变** |
|
||||
| `view` 渲染 | 需决定回显哪一种语序 |
|
||||
|
||||
这正是它与「一等函数」「动态作用域」的本质区别:**只改写法,不改调用模型。**
|
||||
|
||||
### 3.3 设计细节要定的三件事
|
||||
|
||||
1. **动词**:`执行` 目前**不是**关键字;而 `调用` **已经是**关键字(`src/aliases.rs:39`
|
||||
把 `调用` 映射到内建 `call_fn`)。两个近义词并存会混乱,需要二选一或明确分工。
|
||||
2. **绑定子句的边界**:`对 n=31 执行 …` 里 `n=31` 到 `执行` 之间是参数区;
|
||||
多参数写 `对 n=31 m=2 执行 …`。
|
||||
3. **与散文的冲突**:`对` 起头的行今天是叙述(CJK 开头 = 注释)。
|
||||
要让这行变成代码,得给「叙述里出现 `执行 <函数名>`」一个可判定的规则,
|
||||
否则又是一处「看起来是代码、实际是注释」的静默陷阱。
|
||||
|
||||
---
|
||||
|
||||
## 4. L2:真隐式参数(不建议)
|
||||
|
||||
### 4.1 它到底是什么
|
||||
|
||||
L2 = **动态作用域**(dynamic scoping):被调函数在**调用者的环境**里查找自由变量。
|
||||
历史上被反复试过、也反复放弃:早期 Lisp 改成词法作用域、Shell 的动态作用域被视为坑。
|
||||
|
||||
### 4.2 七条硬伤(每条都是具体后果,不是理论洁癖)
|
||||
|
||||
| # | 问题 | 具体后果 |
|
||||
|---|------|---------|
|
||||
| 1 | **同名捕获** | `加一函数` 调 `记录日志`,两者都读 `text` → 日志函数静默拿到加一的局部值,输出错内容而不报错 |
|
||||
| 2 | **递归自毁** | `n=n+1` 后调自身:内层看到的是**已被改过的** n(还是副本?)——必须新增一套遮蔽规则,而规则本身又会成为新的坑 |
|
||||
| 3 | **无法复用** | 同一函数两次不同入参,只能反复改外部变量并祈祷调用顺序,等于把「参数」退化成全局可变状态 |
|
||||
| 4 | **契约报废** | `call_arg_diag` 在**调用边界**校验实参类型;如果不传实参,就没有校验点。T2.1/T2.2 契约体系直接失效 |
|
||||
| 5 | **指纹/arity 失真** | `collect_calls` 记录被调名,arity 由形参推断;隐式调用在 AST 上看起来是零参调用 → 复用预检、`plan` 能力匹配、查重全都失真 |
|
||||
| 6 | **沙箱与序列化** | `sandbox.run` 以隔离方式执行文档;隐式依赖外部作用域会破坏隔离语义;环境也必须可序列化 |
|
||||
| 7 | **不可审计** | 函数行为依赖看不见的上下文——这就是「全局可变状态」的经典问题,与「文档即程序、可被人读懂」直接冲突 |
|
||||
|
||||
再叠加 §2 的数据(130 个名字被 ≥5 函数共用),第 1 条不是边角情况,而是默认情况。
|
||||
|
||||
### 4.3 但有一个**受限版**值得考虑
|
||||
|
||||
如果你真正想要的是「短脚本读起来顺」,那么下面这个版本是安全的:
|
||||
|
||||
> **常量默认值**:允许函数在**未传入**某形参时,从**文件级常量**取值。
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 报价
|
||||
税率: 0.1
|
||||
---
|
||||
|
||||
## 含税
|
||||
+ `金额`
|
||||
|
||||
*`金额` * (`税率`)* # 税率 未传入 → 取 frontmatter 常量
|
||||
|
||||
# main
|
||||
|
||||
**a = > 含税 金额=100** # 10
|
||||
**b = > 含税 金额=100 税率=0.06** # 6,显式覆盖
|
||||
```
|
||||
|
||||
为什么它安全而 L2 不安全:
|
||||
|
||||
| 维度 | L2 动态作用域 | 常量默认值 |
|
||||
|------|--------------|-----------|
|
||||
| 取值来源 | 调用者的**任意**变量 | 文件顶部**写一次**的常量 |
|
||||
| 静态可判定 | ❌ 取决于运行路径 | ✅ 打开文件就能看到 |
|
||||
| 随调用者变化 | ✅ 会变(最危险) | ❌ 不会 |
|
||||
| 契约 | 失效 | 仍可校验(实参照常声明) |
|
||||
| 序列化/沙箱 | 破坏隔离 | 可序列化(常量是数据) |
|
||||
| 复用 | 破坏 | 不受影响 |
|
||||
|
||||
**关键差别**:常量是**文档的一部分**(frontmatter 就在文件开头,人读得到),
|
||||
而动态作用域的值是**运行路径的一部分**(人读不到)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带发现的真问题:CLI 与 Web 的环境不一致
|
||||
|
||||
实测 §1 第 6/7/8 条时发现:
|
||||
|
||||
| 路径 | 函数可见环境 | 源码 |
|
||||
|------|-------------|------|
|
||||
| `# main`(CLI 运行) | frontmatter metadata ✅ | `src/interp.rs:473` `Env::with_metadata` |
|
||||
| **普通函数调用** | 只有实参 ❌ | `eval_call` 用 `Env::new()` |
|
||||
| **浏览器 WASM 入口** | metadata ✅ + `# main` 的 `entry_bindings` ✅ | `invoke_in_entry`(`src/interp.rs:365`) |
|
||||
|
||||
也就是说:**同一份文档,在浏览器里函数能读到 frontmatter 常量、还能读到 `# main`
|
||||
的绑定;在 CLI 里读不到。** 行为随运行面不同而不同。
|
||||
|
||||
这是一个**真实缺陷**,已记入 [D11](../research/qdagent-refactor-defects-2026-10.md):
|
||||
|
||||
- 对使用者:同一文件在 Web 能跑、在 CLI 报 `undefined variable`,极难排查
|
||||
- 对设计:说明「受控环境通道」其实已经存在(只是没在 CLI 打开),
|
||||
这既是 L2 受限版的现成基础,也是必须先统一的地方
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议
|
||||
|
||||
| 优先级 | 事项 | 性质 |
|
||||
|--------|------|------|
|
||||
| 1 | **先统一 CLI/Web 的函数环境**(D11) | 修缺陷,消除行为分裂 |
|
||||
| 2 | **做 L0 叙述式调用**(`对 X 执行 F`) | 纯语法糖,零模型改动,554 回归可守 |
|
||||
| 3 | 若要「少写参数」,做**常量默认值**(§4.3) | 受控隐式,静态可判定 |
|
||||
| 4 | **不做 L2 动态作用域** | 七条硬伤 + 130 个撞车名 |
|
||||
|
||||
关于「代码即文档」的取向,我的理解是:
|
||||
|
||||
> 文档化的是**写法**(句子怎么读),不是**语义**(值从哪来)。
|
||||
> 让句子更像人话是值得的;让值从看不见的地方来,是把可读性换成不可预测性。
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **L0 是否采纳?** 若采纳,动词用 `执行` 还是复用已有的 `调用`?
|
||||
2. **`对…执行…` 的行如何与散文区分**(§3.3 第 3 点)?这决定它会不会变成新的静默陷阱。
|
||||
3. **常量默认值**(§4.3)要不要做?
|
||||
4. **D11(CLI/Web 环境不一致)** 是否现在就修?我建议先修它,因为它会影响 L0/L2 的所有验证结论。
|
||||
@@ -36,7 +36,8 @@ type: llm
|
||||
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
|
||||
api_key: ${secret.OPENAI_API_KEY!}
|
||||
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
|
||||
import sys:lib/sys.mq.md
|
||||
import:
|
||||
sys: lib/sys.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,302 @@
|
||||
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
|
||||
|
||||
> **2026-10-23 审阅裁决**:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认 `[键](集合)`。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提案 | 「`[]()` 不是两个部分两个含义,而是 `[描述性显示文字](实际执行的简短语句)`」 |
|
||||
| 方法 | 语料实测(索引 506 / 循环 44 / 方括号调用 0)+ 渲染器源码核对 + 设计史对照 |
|
||||
| 相邻 | [label-freshness-and-repair.md](label-freshness-and-repair.md)(后续:纯度落地 + 标签过期检测)· [function-as-naming-philosophy.md](function-as-naming-philosophy.md) · [collection-access-link.md](collection-access-link.md) · [call-syntax-from-marks.md](call-syntax-from-marks.md) |
|
||||
|
||||
> **决策**:用户选择**路线二(纯度)**——`()` 只装机器语句,取元搬进 `()`;
|
||||
> 标签可省略书写但**编译器必须报错**;循环写法不追求统一,`()` 内自洽即可。
|
||||
> 落地细节、普通取元形态,以及**标签过期检测(L1 引用一致性 / L2 指纹台账 / L3 LLM 复核)**
|
||||
> 见 [label-freshness-and-repair.md](label-freshness-and-repair.md)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 先把提案精确化
|
||||
|
||||
你的话可以解析出三种读法,差别很大,必须先分清:
|
||||
|
||||
| 读法 | `[]` 是什么 | `()` 是什么 | 语义是否变 |
|
||||
|------|------------|------------|-----------|
|
||||
| **A 标签化(你的原意,本文主评)** | 这个值的**人话名字**(纯描述) | 算出它的**机器语句** | **变** |
|
||||
| B 命名规范化 | 更好的键名(描述取出的东西) | 仍是集合 | 不变 |
|
||||
| C 内联命名 | 同时引入可引用的名字 | 算出它的语句 | 新增绑定 |
|
||||
|
||||
你说「`[]()` 函数也有了落脚地」「括号里面可以写长一些」,指向的是 **A**:
|
||||
**`[]` 只负责说人话,`()` 负责说准话;两者合起来才是一条完整语句。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么我们会下意识觉得这个写法"美"
|
||||
|
||||
你的直觉不是审美偏好,它对应三个**真实存在**的设计同构:
|
||||
|
||||
### 1.1 超链接:可见文本 ↔ 目标
|
||||
|
||||
`<a>` / `[可见文字](目标地址)` 的全部意义就是**给机器一个目标,给人类一个说法**。
|
||||
这是人类最早、最成功的"双面文本"。
|
||||
|
||||
### 1.2 文学编程的 chunk 名(Knuth)
|
||||
|
||||
Knuth 的 `<<chunk name>>` 就是"可执行片段的人话名字"。
|
||||
而**文学编程的整个出发点,正是你前面说的"代码要像文章"**——这个类比不是巧合。
|
||||
|
||||
### 1.3 Marqdo 自己已经有这个形态
|
||||
|
||||
```markdown
|
||||

|
||||
```
|
||||
|
||||
- `[]` 里是**指令/说明**(`marqdo-out`、可带 key)
|
||||
- `()` 里是**负载**(图片 URL / data URI)
|
||||
|
||||
**语言里已经有一个"方括号说意图、圆括号放负载"的地方。** 你的提案是把这个模式提升为通则。
|
||||
|
||||
### 1.4 一个经验证据:`[]` 在实践里本来就偏"给人看"
|
||||
|
||||
| 用法 | 数量 | 谁读 |
|
||||
|------|------|------|
|
||||
| `[键](集合)` 取元 | 506 | 机器 |
|
||||
| `- [项](集合)` 循环 | 44 | 机器 |
|
||||
| `[函数] 参数` 调用 | **0(可执行)** | — |
|
||||
| `[函数.名] 参数` 用法说明(`lib/*` 的 `Caller:` 行) | **189** | **人** |
|
||||
|
||||
**可执行的方括号调用从未被使用**;`[]` 在文档里出现最多的地方,恰恰是"给人看的用法示例"。
|
||||
这支持你的判断:`[]` 的天性更接近"描述",而不是"标识符"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 提案的三个真实收益(这部分我完全同意,而且比你说的更强)
|
||||
|
||||
### 2.1 收益一:两条规则变一条 —— 这是最大的价值
|
||||
|
||||
现在 `[x](y)` 是**两个部分、两个含义**(键 + 集合)。这导致前几轮那个死结:
|
||||
|
||||
> `[f](args)` 想当调用,但它和 `[k](c)` **同形**;按名字消歧会打断 2 个真实文件。
|
||||
|
||||
你的重读**直接解散了这个死结**:如果 `[x](y)` 一律是"标签 + 语句",
|
||||
那么**根本不存在"取元独占外形"这件事**——取元只是"`()` 恰好是个取值语句"的特例。
|
||||
|
||||
> 这是本提案最硬的结构收益:**它把一条只能容纳一种语义的外形,改造成能容纳任意语句的外形。**
|
||||
> 前几轮我们反复撞墙,是因为一直默认 `()` 只能是集合。你换了默认。
|
||||
|
||||
### 2.2 收益二:嵌套取元终于可读
|
||||
|
||||
现在是:
|
||||
|
||||
```markdown
|
||||
**第一 = [1]([苹果](货架))**
|
||||
```
|
||||
|
||||
两层嵌套,人类读者要在"货架→苹果→第1项"之间跳三次。
|
||||
|
||||
改成标签后:
|
||||
|
||||
```markdown
|
||||
**第一 = [货架里苹果的第一项](…机器语句…)**
|
||||
```
|
||||
|
||||
**人读标签,机器读嵌套。** 你点出的"嵌套难以描述"问题被真正解决了。
|
||||
|
||||
### 2.3 收益三:循环的"来源"可见 —— 但要说清它成立的范围
|
||||
|
||||
你的原话:`- [果](篮子)` 在 Markdown 渲染里看不出"果是从篮子拿的"。
|
||||
|
||||
**这一点需要精确化,因为它决定这块值不值得改**:
|
||||
|
||||
| 阅读场合 | `- [果](篮子)` 的表现 |
|
||||
|---------|---------------------|
|
||||
| 通用 Markdown(GitHub / VSCode 预览 / 编辑器) | 渲染成**名为「果」的链接指向「篮子」**——看不出是遍历,你的批评成立 |
|
||||
| **Marqdo 自己的 `view`** | 已渲染成带 `foreach` 徽章的 `loop-card`(`src/view/render.rs:1354`)——已经看得出 |
|
||||
|
||||
而取元在 `view` 里仍渲染成字面 `[键](集合)`(`render.rs:1502`),和 Markdown 链接同形。
|
||||
|
||||
**结论**:循环的"来源不可见"在**通用 Markdown 阅读器**里成立,而这恰好是大多数人的阅读场合
|
||||
(`marqdo view` 需要额外一步)。所以这条收益真实,但它其实在说另一件事:
|
||||
|
||||
> **Marqdo 的语义正确性,不应该依赖读者是否用了 `marqdo view`。**
|
||||
> 文档的第一载体是 `.mq.md` 本身,它在任何 Markdown 渲染器里都该读得通。
|
||||
|
||||
这比你原本的表述更有力——它把"渲染不好看"升级成"语义不可自解释"。
|
||||
|
||||
### 2.4 附带收益:标签是天然的锚点
|
||||
|
||||
你提到"点击之后跳转到对应位置"。这件事可行性很高,而且价值不小:
|
||||
|
||||
- `view` 已经保留每个语句的 span(`stmt_start`),标签可以让锚点从"行号"升级为"人话定位"
|
||||
- 报错信息可以说「在 **货架里苹果的第一项** 处出错」,而不是 `foo.mq.md:118`
|
||||
- 对 agent 尤其有用:模型用自然语言描述定位,比用行列号稳得多
|
||||
|
||||
---
|
||||
|
||||
## 3. 结构性弱点:`()` 要变成"语句",就必须再发明一套取元
|
||||
|
||||
这是本提案**代价最大、也最容易被忽略**的一点,必须摊开。
|
||||
|
||||
若 `[]` 只是标签,那 `(菜单)` 就只表示"整个菜单",**不再表示取成员**。要取成员,`()` 内需要新语法:
|
||||
|
||||
| 方案 | 形态 | 问题 |
|
||||
|------|------|------|
|
||||
| 点号 | `(菜单.拿铁)` | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形,容易混淆 |
|
||||
| 函数式 | `(取 菜单 拿铁)` | 需要新内建;与自然语言"取"字冲突多 |
|
||||
| 保留方括号 | `([拿铁](菜单))` | **嵌套方括号**,正是标签想消除的东西 |
|
||||
| 英文式 | `(get(菜单, 拿铁))` | 破坏中文叙述风格 |
|
||||
|
||||
**这就是核心张力**:
|
||||
|
||||
> 你想用 `()` 装"任意机器语句",来换取 `[]` 的纯粹描述性;
|
||||
> 但"取值"本身就需要一个语法,而这个语法要么是新的(增规则),
|
||||
> 要么就是旧的 `[k](c)`(则 `[]` 仍然兼任键,两义仍在)。
|
||||
|
||||
换句话说:**收益一(一条规则)能不能兑现,取决于你愿不愿意新增一条取元规则。**
|
||||
这不是否决理由,但必须算进成本——因为 Marqdo 的宪法是「标记即语法,少而精」,
|
||||
**用一条新规则换掉一条旧规则,不必然是净简化**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 描述漂移:我认为不能轻描淡写
|
||||
|
||||
你说「从语言设计上这好像又不是特别重要」。我不同意,理由三条:
|
||||
|
||||
### 4.1 它是"注释"的回归
|
||||
|
||||
Marqdo 用「叙述 + 标记」取代了注释:叙述在外面说意图,标记在里面说事实。
|
||||
而标签是**贴在执行体上的、可说谎的、必须短的文本**——这正是注释的老问题。
|
||||
Marqdo 花了很大力气让"文档即程序",标签会把"文档可能是假的"重新引进来。
|
||||
|
||||
### 4.2 一旦标签成为锚点,漂移就有操作后果
|
||||
|
||||
你在 §2.4 里期望标签用于跳转与定位。那么:
|
||||
|
||||
- 报错说「在 **安全读取** 处失败」,而实际代码是写入 → **错误信息也撒谎**
|
||||
- agent 用标签定位 bug → 被标签误导
|
||||
- 点击跳转跳到一段与描述不符的代码 → 读者信任崩塌
|
||||
|
||||
**标签的可信度必须与它的用途匹配。** 纯装饰可以漂移;一旦用于定位,就必须可校验。
|
||||
|
||||
### 4.3 安全面:标签是 agent 可读的攻击面
|
||||
|
||||
Marqdo 是 agent 框架。标签是**作者可控的自然语言**,而模型天然倾向相信自然语言。
|
||||
「标签写:只读校验;`()` 里:删除文件」这类不一致,从"文档瑕疵"升级为**误导 agent 的通道**。
|
||||
|
||||
**所以我建议把漂移当成一条可检查的不变量,而不是接受它的存在**:
|
||||
|
||||
| 缓释手段 | 说明 | 成本 |
|
||||
|---------|------|------|
|
||||
| ① 标签永不参与绑定 | 纯显示,不进符号表、不进作用域 | 零 |
|
||||
| ② 词重叠校验 | `check` 检查"标签里提到的名字"是否至少有一个出现在 `()` 里;全不重叠 → warn | 低 |
|
||||
| ③ trace 双输出 | 错误/trace 同时给标签与 `()` 原文 | 低 |
|
||||
| ④ 策略不看标签 | 沙箱/权限判定只读 `()` 的语义,绝不读标签 | 设计约束 |
|
||||
|
||||
其中 ② 最划算:它能抓住**最恶劣的一类漂移**(标签说 A,代码做 B),
|
||||
而对"标签写得更细"这种正常情况不误报。
|
||||
|
||||
---
|
||||
|
||||
## 5. 采用风险:可能重演 v0.3 废除的"仪式感"
|
||||
|
||||
v0.3 废除 `+ \`名\`` 形参表的原话理由是:**「仪式感强;函数头像另一套签名语言,与正文脱节」**。
|
||||
|
||||
强制每个访问都配一段人话标签,是**同一类仪式**。两种可预测的退化:
|
||||
|
||||
1. **凑数**:作者写 `[x](…)`、`[价格](…)`——标签退化成变量名,等于没有
|
||||
2. **噪音**:标签越写越长,正文被切碎,扫描性下降
|
||||
|
||||
这不是反对,而是提醒:**标签的价值只在"写得比键更有信息"时成立**。
|
||||
所以设计上应当考虑"**可以省略**",但一旦可省略,`[]` 就又变成可选键 → 歧义回归。
|
||||
|
||||
**这个矛盾必须在设计里正面解决,不能靠自觉。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 迁移面(实测)
|
||||
|
||||
| 受影响的写法 | 数量 | 文件 |
|
||||
|------------|------|------|
|
||||
| `[键](集合)` 取元 | **506 处** | 136 个文件 |
|
||||
| `- [项](集合)` 循环 | **44 处** | 24 个文件 |
|
||||
| `[函数] 参数` 可执行调用 | **0** | (189 处是 `lib/*` 的 `Caller:` 说明行,不执行) |
|
||||
|
||||
**危险点**:如果 `[]` 改为"纯标签",那 506 处取元的**含义会变**(`(菜单)` 变成整个菜单),
|
||||
而且是**同形换义**——同一段文本含义变了、还不报错。这是最坏的一类变更(参见 D9)。
|
||||
|
||||
所以若走这条路,**必须硬报错 + 版本门**:旧写法在新版本下直接报
|
||||
「`[键](集合)` 已改为 `[描述](语句)`,请写成 X」。
|
||||
另有一个好消息:**可执行方括号调用量为 0**,所以"把 `[f] args` 收编进新形式"是零迁移成本。
|
||||
|
||||
---
|
||||
|
||||
## 7. 两条落地路线
|
||||
|
||||
### 路线一:双层(推荐,兼容)
|
||||
|
||||
> **规则一句话:`[]` 永远是「这个值的人话名字」;`()` 永远是「怎么算出它」。**
|
||||
|
||||
- **长形(新增)**:`[描述](语句)` —— 承载调用、复杂取元、循环
|
||||
- **短形(现状保留)**:`[键](集合)`、`- [项](集合)` 定义为长形的**缩写**
|
||||
- 文档里显式承认:短形是历史妥协,`[]` 在短形中兼任键
|
||||
|
||||
| 优 | 劣 |
|
||||
|----|----|
|
||||
| 零迁移(506 处不动) | 短形的"两义"仍在(但被定义为可解释的缩写) |
|
||||
| 调用终于有落脚地(且 0 成本收编) | 规则仍是"一条 + 一个特例",不是纯一条 |
|
||||
| 嵌套可读、循环可写清来源 | |
|
||||
| 标签可以逐步引入,不强迫 | |
|
||||
|
||||
### 路线二:纯度(一条规则到底)
|
||||
|
||||
> `()` 只装机器语句,取元必须搬进 `()`。
|
||||
|
||||
必须同时决定:**`()` 内取元用什么形式**(§3 表),然后迁移 506 处 + 版本门。
|
||||
|
||||
| 优 | 劣 |
|
||||
|----|----|
|
||||
| 语义最纯,教学最简 | 需新增取元规则(可能不是净简化) |
|
||||
| `[]` 完全自由,可写很长的描述 | 506 处迁移,同形换义风险 |
|
||||
| 与 Markdown 链接语义完全一致 | 新取元语法与库路径/方法调用需要消歧设计 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 我的评定
|
||||
|
||||
**这是本系列里结构上最强的一个提案**,因为它第一次正面回答了"为什么 `[]()` 一直不肯就范":
|
||||
不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。
|
||||
|
||||
| 维度 | 评分 | 说明 |
|
||||
|------|------|------|
|
||||
| 哲学自洽性 | ★★★★★ | 与超链接、文学编程、`` 三处同构;且"文档自解释"优于"依赖 view 渲染" |
|
||||
| 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 |
|
||||
| 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" |
|
||||
| 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 |
|
||||
| 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 |
|
||||
| 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" |
|
||||
|
||||
**我的建议**:走 **路线一(双层)**,但把"长形"作为**推荐写法**、把文档里的示例全部改成长形,
|
||||
让短形成为"读得懂但不必写"的兼容层。这样:
|
||||
|
||||
- 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源)
|
||||
- 506 处零迁移
|
||||
- 调用终于有家,且成本为零
|
||||
- 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形
|
||||
|
||||
**一条具体建议**:先把 §4 的 ②(词重叠 warn)做出来。
|
||||
它让"标签"从"可能说谎的装饰"变成"**可被机器轻度核验的描述**"——
|
||||
这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。
|
||||
|
||||
---
|
||||
|
||||
## 9. 待你决策
|
||||
|
||||
1. **路线一(双层)还是路线二(纯度)?**
|
||||
2. 若路线二:`()` 内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。
|
||||
3. **标签可否省略?** 若可,省略时算"以 `()` 的文字为标签",还是要额外标记?
|
||||
4. **是否采纳 §4.2 的"词重叠校验"**?我认为它是这套设计能否安全的支点。
|
||||
5. 循环的新写法你倾向哪一种:
|
||||
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
|
||||
- `- [篮子里的果子](篮子 → 果)`
|
||||
- 保留 `- [果](篮子)` 作短形
|
||||
@@ -156,7 +156,8 @@ source: &str (+ optional import map)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 调用实参:具名与位置
|
||||
|
||||
> **2026-10-23 适用范围校正**:本文保留早期调用尾部规则和历史示例,不是 v2.1 全部调用语法。当前已有 `f(args)` 及具名实参;默认紧邻 `](` 是描述包裹 payload,不再是下文所述的 Classic 取元。语法审阅与开发取舍见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),当前行为须由默认模式测试复核。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
|
||||
|
||||
@@ -0,0 +1,289 @@
|
||||
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留显式标记和正文默认安全;性能数值是旧实验,不作为当前基准。持久跨文档接口优先具名参数,但不禁止位置参数;反引号声明与顺序改变可能是接口变化。当前调用与开发方向见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未改代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 前置纠正 | 用户否决上一轮的「叙述式动词」方案:**未标记词承载语义 = 破坏「叙述默认安全」** |
|
||||
| 方法 | 实测 6 组(含双后端性能对比、叙述顺序实验)+ 源码比对 |
|
||||
| 相邻 | [ambient-parameters-evaluation.md](ambient-parameters-evaluation.md) · [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 先接受纠正:错在哪
|
||||
|
||||
我上一轮提的 `对**n=31**执行**加一函数**`,靠**未标记的词「执行」**来触发调用。这确实违背底层原则:
|
||||
|
||||
> **叙述(未标记)= 默认安全,不执行;标记 = 才进编译器。**
|
||||
|
||||
一旦「执行」这种词能改变语义,那么:
|
||||
|
||||
- 作者改一句措辞("执行" → "运行" / "调用" / 换个说法)就可能改变程序行为;
|
||||
- 读者无法只看标记判断哪句是代码——必须逐字读叙述;
|
||||
- 与 D9 同类的静默风险:语义藏在叙述里。
|
||||
|
||||
**所以本文的设计约束是硬的**:
|
||||
|
||||
> **调用的每一个语义成分(被调者、每个实参、绑定关系)必须落在标记内;
|
||||
> 叙述词只能起连接与解释作用,永不改变语义。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 先盘清「标记字母表」
|
||||
|
||||
要设计调用,先得知道手上只有哪些字。
|
||||
|
||||
| 标记 | 现行语义 | 可否参与构成调用 |
|
||||
|------|---------|-----------------|
|
||||
| `**…**` | 执行段(赋值 / 调用 / 表达式) | ✅ 主载体 |
|
||||
| `*…*` | 返回 | ✅ 终止 |
|
||||
| `` `x` `` | 变量引用;首次出现即声明 | ✅ 槽名 |
|
||||
| `` `x` = `` | 叙述中的绑定 | ✅ 槽赋值 |
|
||||
| `**x = …**` | 赋值 | ✅ |
|
||||
| `> …`(行首) | 调用语句 | ✅ 已是调用标记 |
|
||||
| `[callee] args` | 方括号调用(消歧 / 前置修饰) | ✅ 已是调用标记 |
|
||||
| `[k](coll)` | 取元 | ⚠️ 与调用抢外形(已否) |
|
||||
| `- [x](coll)` | 遍历 | — |
|
||||
| `#` / `##` | 对象 / 函数声明 | — |
|
||||
| 表格 | 数据 / 契约 | — |
|
||||
| ```lang | 外联代码 | — |
|
||||
|
||||
**关键观察**:调用载体其实只有三种标记:`> 行`、`**…**`、`[callee]`。
|
||||
而 `[k](coll)` 这个外形已被取元独占(前几轮结论),不能用。
|
||||
|
||||
所以问题收敛为:
|
||||
|
||||
> **在 `**…**` 或 `> …` 内部,用哪些标记把「函数名」和「槽赋值」连起来?**
|
||||
|
||||
---
|
||||
|
||||
## 2. 可读性从哪来(这是设计的核心)
|
||||
|
||||
Marqdo 的叙述与代码是**两层**:叙述解释「为什么」,标记表达「做什么」。
|
||||
所以可读性不是靠把叙述词变成语法,而是靠:
|
||||
|
||||
1. **标记本身足够像自然记号**(`=`, `(`, `)`, `→` 都是跨语言的);
|
||||
2. **叙述与标记紧邻**,人一句一码地读;
|
||||
3. **同一件事只写一遍**(叙述不要复述代码)。
|
||||
|
||||
一句话:
|
||||
|
||||
> **叙述负责「说人话」,标记负责「说准话」;两者相邻即高可读,混在一起即两败。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 三个候选设计
|
||||
|
||||
### 设计 A — 括注具名调用:`**加一函数(n=31)**`
|
||||
|
||||
**读法**:`加一函数(n=31)` —— 与数学/几乎所有语言的函数调用同构。
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对 `n` 让 **n = n + 1**,返回 *n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 加一函数(n=31)**
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ 整段在 `**…**` 内 |
|
||||
| 无歧义 | ✅ 圆括号紧跟名字 = 调用;取元需方括号,不冲突 |
|
||||
| 与叙述结合 | ✅「把 n 设为 31 后**加一函数(n=31)**」 |
|
||||
| 多参数 | ✅ `f(a=1 b=2)` |
|
||||
| 编译器 | ✅ 具名 → 编译期映射到槽下标(见 §4) |
|
||||
| 实现成本 | ⚠️ 需改参数分词器:`)` 作终止符、逗号、嵌套(原型已验 554/0,但 `f(1 2)` 的末参数会吞 `)`) |
|
||||
|
||||
### 设计 B — 箭头槽赋值:`**n=31 → 加一函数**`
|
||||
|
||||
**读法**:「n 设为 31,交给加一函数」——最贴合汉语「先条件、后动作」语序。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**n=31 → 加一函数**
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ `→` 是符号标记,不是词 |
|
||||
| 可读性 | ✅✅ 流水线极顺:`**订单 → 计税 → 汇总**` |
|
||||
| 无歧义 | ⚠️ 需定义优先级;`**x = a=1 → f**` 有歧义,得靠括号 |
|
||||
| 求值结果 | ⚠️ 箭头式天然是语句式;要拿返回值还得包一层 |
|
||||
| 实现成本 | 中:新增运算符 + 优先级 + 与 `=`/`*…*` 的交互 |
|
||||
|
||||
### 设计 C — 现成空格式:`**加一函数 n=31**`(今天就可用)
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ |
|
||||
| 实现成本 | **零**(实测 `**r = 加 1 2**` 已可跑) |
|
||||
| 可读性 | ⚠️ 参数边界靠空格;函数名含空格时不可用(D8) |
|
||||
| 编译器 | ✅ 具名同样可映射槽位 |
|
||||
|
||||
### 三者的取舍
|
||||
|
||||
| | A 括注 | B 箭头 | C 空格 |
|
||||
|---|---|---|---|
|
||||
| 像通用函数调用 | ✅✅ | ⚠️ | ✅ |
|
||||
| 中文语序自然 | ⚠️ | ✅✅ | ✅ |
|
||||
| 参数边界清晰 | ✅✅ | ✅ | ❌(空格切分) |
|
||||
| 链式组合 | ⚠️ | ✅✅ | ❌ |
|
||||
| 改动成本 | 中 | 中高 | **零** |
|
||||
| 与取元冲突 | 无 | 无 | 无 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 「不分实参形参」:编译器视角的真实收益
|
||||
|
||||
你问的是:不再区分实参/形参,是否意味着变量总在某个固定位置、能否减少 IO。
|
||||
这一节用实测回答,结论会有点意外。
|
||||
|
||||
### 4.1 现状:两条执行路径,差异 3.8 倍
|
||||
|
||||
| 路径 | 参数如何绑定 | 200k 次调用(1 个 int 实参) | 2000 次调用(500 元素列表) |
|
||||
|------|-------------|------------------------------|------------------------------|
|
||||
| **树遍历**(默认 `Backend::Tree`) | `Env { HashMap<String, Value> }`,每个实参 `k.clone()` + `v.clone()`(**深拷贝**) | 167 ms | 66 ms |
|
||||
| **字节码**(`--backend bytecode`) | `slots: Vec<Value>`,`pop` 后**按位置移动**入槽(**无克隆、无哈希**) | **44 ms** | **23 ms** |
|
||||
|
||||
源码依据:
|
||||
|
||||
```rust
|
||||
// src/bytecode/vm.rs Op::Call(fid, argc)
|
||||
let mut slots = vec![Value::None; callee.locals.len().max(argc).max(1)];
|
||||
for i in (0..argc).rev() {
|
||||
slots[i] = pop(&mut stack)?; // 移动,不克隆
|
||||
}
|
||||
frames.push(Frame { fn_idx: fid, ip: 0, slots, .. });
|
||||
```
|
||||
|
||||
### 4.2 三个结论
|
||||
|
||||
**结论一:「变量始终在某个位置」已经是字节码的现实。**
|
||||
形参按下标落槽,实参按位置移动入槽。这正是你说的模型——它已经存在。
|
||||
|
||||
**结论二:收益是真的,3.8×。**
|
||||
每次调用 0.83µs → 0.22µs;大实参 33µs → 11.5µs(省掉了深拷贝)。
|
||||
|
||||
**结论三(关键):这与「不分实参形参」的语法无关。**
|
||||
槽位化只需要「编译期知道形参顺序」,而形参顺序今天就有(v0.3 体推断给出确定顺序)。
|
||||
真正的瓶颈是**树遍历解释器用名字哈希 + 深拷贝**,以及**默认后端是 Tree**。
|
||||
|
||||
> **所以:不要用性能去论证语义变更。**
|
||||
> 想省 IO,把默认后端切到字节码、或把树遍历解释器槽位化即可——
|
||||
> 这是一条与语法正交的工程路径,收益确定、风险可控。
|
||||
> 而改语义(动态作用域)换来的性能,等于用正确性买速度。
|
||||
|
||||
### 4.3 但有一个真实的语法—性能耦合点:具名 vs 位置
|
||||
|
||||
这是本节最有价值的发现。**在「形参由体推断」的世界里,形参顺序 = 叙述里首次声明的顺序**
|
||||
(v0.3 §8.2:顺序按升参名字的首次声明事件出现序)。而叙述是可以自由改写的。
|
||||
|
||||
我用两个只差一句话序的文件做了实验:
|
||||
|
||||
```markdown
|
||||
## 减
|
||||
对于`a`和`b`。 ← 叙述顺序 a, b
|
||||
*`a` - `b`*
|
||||
```
|
||||
|
||||
```markdown
|
||||
## 减
|
||||
对于`b`和`a`。 ← 只把叙述顺序改成 b, a
|
||||
*`b` - `a`*
|
||||
```
|
||||
|
||||
| 调用写法 | 叙述 a 在前 | 叙述 b 在前 |
|
||||
|---------|------------|------------|
|
||||
| 具名 `a=10 b=3` | 7 | -7(语义随函数体改变,符合预期) |
|
||||
| **位置 `10 3`** | 7(a=10,b=3) | **7(b=10,a=3)** ← **绑定翻转了** |
|
||||
|
||||
**同一行调用代码 `> 减 10 3`,只因为作者改了前面的叙述语序,实际绑定就变了,而且不报错。**
|
||||
|
||||
这在「实参形参不分」的模型下是致命的:既然只有槽、槽序来自叙述,
|
||||
那么**位置传参等于把程序语义挂在叙述的可改写顺序上**。
|
||||
|
||||
**推论**:调用应当**以具名为准**,位置实参在体推断世界里是脆弱语法。
|
||||
这一点与编译器优化正好同向——具名调用让编译期把 `n` 静态映射到 `slots[0]`,
|
||||
既稳又快(不需要运行期哈希,也不需要猜顺序)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 我的设计建议
|
||||
|
||||
### 5.1 主形态:括注具名调用
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对 `n` 让 **n = n + 1**,返回 *n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 加一函数(n=31)**
|
||||
```
|
||||
|
||||
理由:
|
||||
|
||||
1. **全部语义在标记内**(满足你的核心原则);
|
||||
2. 与通用函数调用同构,零学习成本;
|
||||
3. 具名 → 编译期静态映射槽位(对接字节码已有的 `slots[]`);
|
||||
4. 不碰取元 `[k](coll)`,不碰遍历 `- [x](c)`;
|
||||
5. 参数边界显式,顺带解决函数名含空格的调用难题(D8)。
|
||||
|
||||
### 5.2 位置实参:降级而非禁止
|
||||
|
||||
| 情形 | 建议 |
|
||||
|------|------|
|
||||
| 单参数 | 允许 `f(31)`(无歧义、写法自然) |
|
||||
| 多参数 | **要求具名**;位置仅保留给 `> f 1 2` 这种旧写法,并在 `check` 里 **warn** |
|
||||
| 理由 | §4.3:顺序来自叙述,可被改写而不报错 |
|
||||
|
||||
### 5.3 箭头(设计 B)作为可选补充
|
||||
|
||||
如果后续确实需要「流水线可读性」,再引入 `→`,定位为**语句式组合子**:
|
||||
|
||||
```markdown
|
||||
**订单 → 计税 → 汇总**
|
||||
```
|
||||
|
||||
但它是增量特性,不是本设计的前提。优势是链式,代价是优先级与返回值语义。
|
||||
|
||||
### 5.4 明确不做
|
||||
|
||||
| 方案 | 理由 |
|
||||
|------|------|
|
||||
| 未标记动词触发调用(上轮 L0) | 违背「叙述默认安全」 |
|
||||
| `[f](args)` | 与取元同形,已实测 2 个真实冲突文件 |
|
||||
| 动态作用域(参数从上下文推断) | 七条硬伤 + 130 个撞车形参名 |
|
||||
| 位置实参作为主流 | §4.3 叙述顺序会静默改变绑定 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 优劣总表
|
||||
|
||||
| 设计 | 标记完备 | 可读性 | 无歧义 | 编译器友好 | 改动 | 结论 |
|
||||
|------|---------|--------|--------|-----------|------|------|
|
||||
| **A 括注具名 `f(n=31)`** | ✅ | 高 | ✅ | ✅ 静态槽映射 | 中 | **推荐主形态** |
|
||||
| C 空格式 `f n=31` | ✅ | 中 | ✅ | ✅ | 零 | 今天可用,作兼容 |
|
||||
| B 箭头 `n=31 → f` | ✅ | 最高(流水线) | ⚠️ 优先级 | ✅ | 中高 | 可选增量 |
|
||||
| `[f](args)` | ✅ | 高 | ❌ 撞取元 | — | — | 不做 |
|
||||
| 未标记动词 | ❌ | 高 | ❌ | — | — | 不做 |
|
||||
| 动态作用域 | ✅ | 最高 | ❌ | ❌ 契约/指纹失效 | 高 | 不做 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **主形态选 A(括注具名)吗?** 若选,我按 B 档实现:`f(k=v)` 必通、`f(x)` 单参、多参数求具名。
|
||||
2. **位置实参**:多参时"要求具名 + 旧写法 warn"(§5.2),还是保持现状不动?
|
||||
3. **箭头**现在做还是留作后续?
|
||||
4. **顺带**:默认后端要不要切字节码(实测 3.8×,但需先验证 554 用例在 `--backend bytecode` 下全绿)?这条与语法无关,但可能是最划算的性能改进。
|
||||
|
||||
> 若你同意 A,我下一步会:改分词器(`)` 终止、逗号、嵌套)→ 补金样例 →
|
||||
> 跑双后端 554 回归 → 写变更文档。
|
||||
@@ -23,15 +23,20 @@ YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
# 别名(与早期草案一致)
|
||||
marqdo sync [PATH] -o OUT_DIR
|
||||
# 跳过 Engineering Knowledge 投影(仅旧式 catalog)
|
||||
marqdo catalog [PATH] -o OUT_DIR --no-knowledge
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
|
||||
| `--no-knowledge` | off | 不跑 EKC;默认在 catalog 成功后编译 L0–L4 / graph |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
Engineering Knowledge 命令见 [engineering-knowledge.md](engineering-knowledge.md)(`find` / `reuse` / `duplicate` / …)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物
|
||||
|
||||
@@ -0,0 +1,231 @@
|
||||
# 变更记录:D9 未闭合引号不再静默吞行
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(待合入) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 缺陷 | [D9](../research/qdagent-refactor-defects-2026-10.md) |
|
||||
| 设计 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md) §1 |
|
||||
| 改动文件 | `src/lex/mod.rs` · `src/parse/mod.rs` |
|
||||
| 影响面 | 行分类 + 语句解析(仅影响**畸形**输入) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 修了什么
|
||||
|
||||
**修复前**:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0。
|
||||
|
||||
```bash
|
||||
$ marqdo run u.mq.md
|
||||
$ echo $?
|
||||
0 # 没有输出、没有报错,s 这一行凭空消失
|
||||
```
|
||||
|
||||
**修复后**:解析期报错,退出码非 0。
|
||||
|
||||
```bash
|
||||
$ marqdo run u.mq.md
|
||||
error: u.mq.md: 7:1: unterminated string: this line starts bold code but
|
||||
contains an odd number of `"` -- close the string and the trailing `**`
|
||||
(line: **s = "abc)
|
||||
$ echo $?
|
||||
1
|
||||
```
|
||||
|
||||
(实测记录:报错回显中 `unterminated` 前的空格与行号格式由
|
||||
`Diagnostic` 的 span 渲染决定,与其它语法错一致。)
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因
|
||||
|
||||
问题**不在**解析器——`parse_quoted_string` 里的
|
||||
`bail!("unterminated {quote} string")` 一直都在,措辞也对。
|
||||
问题是这一行**根本到不了解析器**:
|
||||
|
||||
```
|
||||
"**s = \"abc"
|
||||
↓ classify_line
|
||||
↓ 首字符 '*' → is_marqdo_star_line?
|
||||
matching_bold_close() 扫描时遇到 '"' → in_str = true
|
||||
之后再也没有 '"' 来关闭 → 后续所有 '*' 都被当作字符串内容跳过
|
||||
→ 找不到收尾 '**' → 返回 None
|
||||
↓ is_marqdo_star_line = false
|
||||
↓ 落入 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
|
||||
↓ 成为「叙述」,解析器看不到
|
||||
```
|
||||
|
||||
**这是分类层的静默降级,不是解析层的缺陷。**
|
||||
|
||||
它比一般的解析错误更危险,因为:
|
||||
|
||||
| 场景 | 后果 |
|
||||
|------|------|
|
||||
| 手写漏一个引号 | 该行消失 → 别处报 `undefined variable`,排查方向被引偏 |
|
||||
| LLM 生成文档 | 少一段内容,但 `exit 0`、`check` 通过,**文档看起来完整却缺节** |
|
||||
| CI / 文档门禁 | 门禁试跑通过 → 残缺文档被沉淀入库 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 怎么改的
|
||||
|
||||
两层,缺一不可。
|
||||
|
||||
### 3.1 分类层:把畸形行留在 Code 类
|
||||
|
||||
`src/lex/mod.rs`
|
||||
|
||||
```rust
|
||||
if trimmed.starts_with("**") {
|
||||
if trimmed.trim() == "** **" {
|
||||
return true;
|
||||
}
|
||||
if matching_bold_close(trimmed).is_some() {
|
||||
return true;
|
||||
}
|
||||
// D9: 粗体起始但引号永不闭合 → 找不到收尾 `**`
|
||||
// 判为 Comment 会静默丢行;判为 Code 让解析器报错
|
||||
return has_unterminated_string(trimmed);
|
||||
}
|
||||
```
|
||||
|
||||
新增辅助函数:
|
||||
|
||||
```rust
|
||||
pub fn has_unterminated_string(line: &str) -> bool {
|
||||
// 统计未被 \ 转义的双引号个数,奇数即「开了没收」
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 解析层:给出精确报错
|
||||
|
||||
`src/parse/mod.rs`,紧跟既有粗体分支之后:
|
||||
|
||||
```rust
|
||||
// D9: 粗体起始但引号未闭合 —— 走到这里说明没有收尾 `**`,
|
||||
// 通用 "unrecognized statement" 会掩盖真正原因。
|
||||
if trimmed.starts_with("**") && has_unterminated_string(trimmed) {
|
||||
bail!("{span}: unterminated string: ... (line: {trimmed})");
|
||||
}
|
||||
```
|
||||
|
||||
没有这一层,用户会看到 `unrecognized statement: **s = "abc`——
|
||||
能定位到行,但不知道是引号没闭合。
|
||||
|
||||
---
|
||||
|
||||
## 4. 影响面(改前量化过)
|
||||
|
||||
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描,正确跳过 `\` 转义:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| `.mq.md` 文件总数 | 845 |
|
||||
| 含 `**` 起始代码行的文件 | 620 |
|
||||
| **引号计数为奇数的代码行** | **0** |
|
||||
|
||||
**结论:不改变任何现有文件的解析结果。** 这条修复只作用于畸形输入。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
### 5.1 新增单元测试(`src/lex/mod.rs`,4 个)
|
||||
|
||||
| 测试 | 断言 |
|
||||
|------|------|
|
||||
| `unterminated_quote_inside_bold_is_code_not_comment` | 未闭合引号的粗体行 → `Code`(修复前失败,修复后通过) |
|
||||
| `balanced_quote_inside_bold_still_code` | 闭合引号仍是 `Code` |
|
||||
| `prose_with_quotes_stays_comment` | 叙述里提引号 → 仍是 `Comment` |
|
||||
| `prose_bold_emphasis_with_quote_stays_comment` | 叙述里含孤立引号 → 仍是 `Comment` |
|
||||
|
||||
**先写测试确认失败**(TDD):
|
||||
|
||||
```
|
||||
---- lex::tests::unterminated_quote_inside_bold_is_code_not_comment
|
||||
panicked: expected Code (so parser reports the error),
|
||||
got [ClassifiedLine { kind: Comment, text: "**s = \"abc" }]
|
||||
```
|
||||
|
||||
修复后 14/14 通过。
|
||||
|
||||
### 5.2 回归
|
||||
|
||||
| 范围 | 结果 |
|
||||
|------|------|
|
||||
| `cargo test --release --lib` | **237 passed, 0 failed**(基线 233 + 新增 4) |
|
||||
| `cargo test --release --test gold` | 276 passed, 8 failed |
|
||||
| ↑ 上述 8 个失败是否本次引入 | **否**。`git stash` 后基线同样 8 failed |
|
||||
| 8 个失败的原因 | 全部 `ext_web_*`,依赖 Go 插件 `libweb` 构建,本机环境不具备 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 已知边界
|
||||
|
||||
| 情形 | 行为 | 说明 |
|
||||
|------|------|------|
|
||||
| `**s = "a` + 下一行 `b"**` | 报错 | 字符串不跨行,符合现状 |
|
||||
| 单引号 `'...'` 未闭合 | **仍是旧行为**(静默) | 本次只处理双引号;单引号在 Marqdo 里使用频率低,留作后续 |
|
||||
| 叙述行含孤立 `"` | 不受影响 | 判定入口是 `starts_with("**")`,叙述行不进入 |
|
||||
|
||||
> 单引号的情况建议后续按同样思路处理,但需要单独评估
|
||||
> (单引号也用于英文撇号,误判风险高于双引号)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/lex/mod.rs` | `is_marqdo_star_line` 增加未闭合引号分支;新增 `pub fn has_unterminated_string`;新增 4 个测试 |
|
||||
| `src/parse/mod.rs` | import 辅助函数;`parse_simple_stmt` 增加精确报错分支 |
|
||||
| `doc/design/parser-diagnostics-d8-d9.md` | 新增(设计依据 + 影响面 + 方案评判) |
|
||||
| `doc/design/spaced-function-names-d8.md` | 新增(D8 方案评估,待审阅) |
|
||||
| `doc/design/change-d9-unterminated-string.md` | 本文件 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 附:本机测试环境(2026-10-22 装好)
|
||||
|
||||
修复过程中发现本机缺两样东西,导致基线本来就有失败。补环境后全量测试 **554 passed / 0 failed**。
|
||||
|
||||
### 8.1 两个非直觉约束
|
||||
|
||||
| 约束 | 表现 | 解法 |
|
||||
|------|------|------|
|
||||
| `$HOME` 不可写 | zig 报 `error: AccessDenied`(全局缓存无处可写) | `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` 显式指向工作区 |
|
||||
| **`/tmp` 是 noexec tmpfs** | Go 链接报 `running gcc failed: signal: aborted`;zig 链接报 `AccessDenied` | `TMPDIR` 指向可写**且可执行**目录 |
|
||||
|
||||
第二条最隐蔽:`/tmp` 挂载为 `rw,nosuid,nodev,noexec`,构建工具会把产物写到那里再执行,
|
||||
于是「文件能写、却执行不了」。错误信息完全指向不了这一点。
|
||||
|
||||
### 8.2 Go 插件(`libweb.so`)
|
||||
|
||||
`gold` 测试里 8 个 `ext_web_*` 失败全因缺 `libweb.so`:
|
||||
|
||||
```bash
|
||||
source scripts/dev-env.sh # 提供 go 1.25 + gcc shim(zig) + TMPDIR
|
||||
./scripts/build-web-plugin.sh # 产出 plugins/web/build/libweb.so
|
||||
cp plugins/web/build/libweb.so target/release/ target/debug/
|
||||
```
|
||||
|
||||
Go 的 cgo 要 `gcc`,本机没有,用 zig cc 充当:
|
||||
`/workspace/qdagent/.tools/zigcc/bin/gcc`(会过滤 Go 传入的 `-Qunused-arguments`,
|
||||
该参数会让 zig 驱动 abort)。
|
||||
|
||||
### 8.3 一键复用
|
||||
|
||||
新增 `scripts/dev-env.sh`,`source` 后即具备完整工具链:
|
||||
|
||||
```
|
||||
marqdo dev-env: rust=1.81.0 go=go1.25.0 python=3.12.15 cc=zig-glibc2.36
|
||||
```
|
||||
|
||||
### 8.4 环境修复前后的测试对比
|
||||
|
||||
| 阶段 | lib 测试 | gold 测试 |
|
||||
|------|----------|-----------|
|
||||
| 无 python3 | 231 / 2 failed | — |
|
||||
| 加 python3 | 233 / 0 failed | 276 / 8 failed |
|
||||
| 加 go + libweb | — | **284 / 0 failed** |
|
||||
| **全量** | | **554 passed / 0 failed** |
|
||||
@@ -0,0 +1,99 @@
|
||||
# 变更记录:HostFn 五张表合一(`HOST_FN_TABLE` 单一来源)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 4 项 |
|
||||
| 改动 | `src/host/dispatch.rs`:**−404 行**(639 删 / 235 增) |
|
||||
| 行为 | **零变化**(203 项逐字节一致) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原来有五张并行表
|
||||
|
||||
202 个宿主函数的元数据分散在五个手写 match 里:
|
||||
|
||||
| 表 | 行数 | 作用 |
|
||||
|----|------|------|
|
||||
| `from_u16` | ~215 | id → 变体 |
|
||||
| `from_name` | ~215 | 名字/别名 → 变体(**保留**,见 §4) |
|
||||
| `name` | ~210 | 变体 → 规范名 |
|
||||
| `required_params` | ~145 | 变体 → 必填参数 |
|
||||
| `optional_params` | ~90 | 变体 → 可选参数 |
|
||||
|
||||
五张表必须同步维护,而 [code-volume-audit.md](code-volume-audit.md) 记录过
|
||||
`from_name` 接受 `http_get` 而 `name()` 只输出 `host_http_get` 的一类漂移。
|
||||
|
||||
## 2. 现在只有一张
|
||||
|
||||
```rust
|
||||
pub struct HostFnDef {
|
||||
pub id: u16,
|
||||
pub f: HostFn,
|
||||
pub name: &'static str,
|
||||
pub required: &'static [&'static str],
|
||||
pub optional: &'static [&'static str],
|
||||
}
|
||||
|
||||
pub const HOST_FN_TABLE: &[HostFnDef] = &[
|
||||
HostFnDef { id: 1, f: HostFn::ReadText, name: "host_read_text",
|
||||
required: &["path"], optional: &[] },
|
||||
…
|
||||
];
|
||||
```
|
||||
|
||||
四个函数改为查表(`from_u16` 按 id 查,其余按判别值查);
|
||||
`call_host` 保留它那 202 个一行臂——**分派逻辑不动**,只把元数据集中。
|
||||
|
||||
## 3. 怎么保证没改坏
|
||||
|
||||
迁移采用**快照比对**:
|
||||
|
||||
1. 先在旧实现上导出全部 203 项的 `(id, name, required, optional)` 到 TSV
|
||||
2. 合并成表后,用同一段代码再导出一份
|
||||
3. `diff` 两份文件 → **完全一致**
|
||||
|
||||
```
|
||||
$ diff /tmp/host_fns_baseline.tsv /tmp/host_fns_new.tsv && echo IDENTICAL
|
||||
IDENTICAL
|
||||
```
|
||||
|
||||
快照测试是一次性的,比对通过后删除;长期守护交给四个不变量测试:
|
||||
|
||||
| 测试 | 内容 |
|
||||
|------|------|
|
||||
| `every_assigned_id_round_trips` | 每个已分配 id → `as_u16()` 往返(id 空间稀疏是**退役 id**,不复用) |
|
||||
| `every_id_has_a_name_that_round_trips` | `name()` → `from_name()` 回到同一变体 |
|
||||
| `names_are_unique` | 规范名唯一 |
|
||||
| `required_and_optional_params_are_disjoint` | 必填/可选不重叠、`all_params` 无重复 |
|
||||
|
||||
## 4. 为什么 `from_name` 没有并进表
|
||||
|
||||
它是**别名注册表**(`http_get`、`get`、中文别名…),语义与"规范名"不同;
|
||||
并进表会让 `name()` 与 `from_name` 又变成一对映射。
|
||||
现在它保留原样,由上面的往返测试保证不与表漂移。
|
||||
|
||||
## 5. 收益
|
||||
|
||||
| 指标 | 前 | 后 |
|
||||
|------|----|----|
|
||||
| `dispatch.rs` | 2,052 行 | **1,648 行** |
|
||||
| `src/` 合计 | 53,040 | **52,668** |
|
||||
| 需同步维护的表 | 5 | **1** |
|
||||
|
||||
## 6. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `cargo build --release` | 零警告 |
|
||||
| `cargo test --release` | **609 passed / 0 failed** |
|
||||
| 快照 diff | 203 项逐字节一致 |
|
||||
| 四个不变量测试 | 全绿 |
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/host/dispatch.rs` | 新增 `HostFnDef` / `HOST_FN_TABLE`(203 项);`from_u16` / `name` / `required_params` / `optional_params` 改为查表;删除对应四个 match |
|
||||
| `doc/design/change-hostfn-table.md` | 本文件 |
|
||||
@@ -0,0 +1,134 @@
|
||||
# 变更记录:M1 `()` 内调用语法(`)` 终止 / 逗号 / 嵌套 / 空格 callee)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M1([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/parse/expr.rs` |
|
||||
| 影响面 | **共享参数分词器**(所有调用都会经过) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 修了什么
|
||||
|
||||
四件事,一句概括:**`(…)` 现在是一等调用外形**。
|
||||
|
||||
| # | 前 | 后 |
|
||||
|---|----|----|
|
||||
| 1 | `加(31)` 报 `unknown function 加(31` | ✅ 调用,返回 32 |
|
||||
| 2 | 末个位置实参会吞掉 `)` | `)` 是**参数终止符** |
|
||||
| 3 | 只支持空白分隔 | 支持 `,` / `,` 可选分隔 |
|
||||
| 4 | 嵌套 `加(加(1 2), 3)` 不可用 | ✅ 递归解析 |
|
||||
| 5 | `加一 号(31)` 不可用(D8) | ✅ **callee 可含空格** |
|
||||
|
||||
实测(1.5.2 本地构建,tree 与 bytecode 双后端结果一致):
|
||||
|
||||
```
|
||||
空格参=3 加(1 2)
|
||||
逗号=3 加(1, 2)
|
||||
嵌套=13 加(加(1 2), 10)
|
||||
带空格callee=32 加一 号(31) ← 缺陷 D8 的结构性解法
|
||||
库函数=x txt.str_trim(" x ")
|
||||
具名=3 加(a=1, b=2)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 实现要点
|
||||
|
||||
### 2.1 参数扫描:深度感知 + `)` 终止
|
||||
|
||||
`split_first_token` 与 `find_next_arg_boundary` 改为**通用扫描器**:
|
||||
|
||||
- 跟踪 `()` `[]` `{}` 嵌套、`"…"` 字符串、`` `…` `` 反引号
|
||||
- **顶层** `)` / 空白(以及括号形里的 `,`)终止当前 token,且**不吞掉终止符**
|
||||
- 字符串内的逗号不受影响(`拼接("a,b", "c")` 仍是 2 个参数)
|
||||
|
||||
### 2.2 `try_paren_call`:callee = 第一个 `(` 之前的全部文本
|
||||
|
||||
```rust
|
||||
let Some(open) = s.find('(') else { return Ok(None) };
|
||||
let callee_tok = s[..open].trim(); // 允许空格
|
||||
```
|
||||
|
||||
**安全护栏**(否则会误判):
|
||||
|
||||
| callee 里出现 | 判定 |
|
||||
|--------------|------|
|
||||
| `=` | 不是括号调用(那是 `text=a(b)` 具名实参) |
|
||||
| `[` `]` `(` `)` `"` `'` | 不是括号调用(那是 `trim [stdout](…)` 方括号实参) |
|
||||
| 以 `[` `]` `"` `'` 开头 | 不是括号调用 |
|
||||
| 反引号 | **允许**(保留 `` `obj`.方法(…) `` 接收者写法) |
|
||||
|
||||
### 2.3 表达式级 postfix 调用
|
||||
|
||||
`parse_primary` 的裸词分支:**紧跟** `(` 时按调用解析。
|
||||
|
||||
```rust
|
||||
if self.allow_paren_call && self.rest().starts_with('(') { … }
|
||||
```
|
||||
|
||||
要求"紧跟"(不隔空格),使 `加 (1)` 仍是原来的"文本 + 括号"行为。
|
||||
|
||||
### 2.4 方括号形也允许空格 callee
|
||||
|
||||
`is_bracket_callee_inner` 不再拒绝空白:`[加一 号] 31` 可用。
|
||||
(仓库内可执行的方括号调用用量为 0,风险极低。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键设计决策:括号形 vs 空格形的参数**值**语义不同
|
||||
|
||||
这是本里程碑唯一有争议的点,必须写清。
|
||||
|
||||
| 形态 | 参数值 | 例子 |
|
||||
|------|--------|------|
|
||||
| **括号形** `f(…)` | 表达式(**允许** `name(args)` 调用) | `加(加(1 2), 3)` |
|
||||
| **空格形** `> f k=v` | 文本(**不允许**裸 `name(args)` 变成调用) | `source=print(2+2)` 仍是文本 |
|
||||
|
||||
**为什么必须区分**:`source=print(2+2)` 在 Marqdo 里历来是**文本**(未加引号的实参按文本处理)。
|
||||
若不区分,它会变成对 `print` 的调用,`foreign.run_lang` 直接报 `source must be text`
|
||||
—— 这正是本次回归测试抓到的 3 个失败。
|
||||
|
||||
实现:`Parser` 增加 `allow_paren_call` 字段;`parse_call_arg_value_mode(input, prefer_var, allow_call)`
|
||||
统一两种值解析(`allow_call=false` 即旧行为)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元 | 新增 11 个(单参/多参/逗号/具名/空格 callee/零参/库路径/嵌套/引号内逗号/旧写法不回归/方括号形) | ✅ |
|
||||
| 全量 | `cargo test --release` | **565 passed / 0 failed**(基线 554 + 11) |
|
||||
| 双后端 | tree 与 `--backend bytecode` 跑同一文档 | 输出一致 |
|
||||
| 端到端 | `marqdo run` 六个用例 | 输出符合预期 |
|
||||
|
||||
**TDD 过程**:先写 11 个测试 → 10 个失败(红灯确认)→ 实现 → 全绿。
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带移除的死代码
|
||||
|
||||
`end_of_quoted_string`:新扫描器取代其唯一用途后变成 `never used`,删除(编译器警告清零)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界(本里程碑不做)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 逗号仅在括号形生效 | 空格形 `text=a,b` 的逗号仍是文本(兼容) |
|
||||
| `加 (1)`(空格后跟括号) | 不视为调用,保持旧行为 |
|
||||
| 遮蔽语法 `[描述](…)` | M2 才引入,本里程碑不解析 |
|
||||
| 位置实参顺序脆弱性 | 与叙述顺序绑定,M7/M8 再处理(诊断) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/parse/expr.rs` | 参数扫描器重写(`)`/逗号/嵌套);新增 `try_paren_call` + `split_callee` 抽取;表达式级 postfix 调用;`Parser.allow_paren_call`;`parse_call_arg_value_mode` 统一两种值语义;方括号 callee 允许空格;删除 `end_of_quoted_string` |
|
||||
| `doc/design/change-m1-paren-call.md` | 本文件 |
|
||||
@@ -0,0 +1,73 @@
|
||||
# 变更记录:M10 工程化落点(README + agent 提示词)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M10([occlusion-description-and-search.md](occlusion-description-and-search.md) §5) |
|
||||
| 改动文件 | `ext/ai/agent.mq.md`(README 一节已在文档阶段落地) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 改了什么
|
||||
|
||||
把「接不了就申报,别假装完成」写进 **agent 的默认提示词**,两处:
|
||||
|
||||
### 1.1 `how-to-act` 协议段(每轮都会带)
|
||||
|
||||
```
|
||||
Call ONLY names listed under --- tools --- (whitelist). …
|
||||
If a capability cannot truly be wired, do NOT fake it silently and never claim it works:
|
||||
write an occlusion with an explicit status, e.g. [按关键词检索,接口未接,待开发](None).
|
||||
Stubs must run without error and must state their return value (None is acceptable).
|
||||
Before finishing, check your own declarations with labels.search.
|
||||
Tools run via Marqdo subtask (spawn fn / wait).
|
||||
```
|
||||
|
||||
### 1.2 默认 standing(`p`)
|
||||
|
||||
```
|
||||
You are a Marqdo agent. Code is documentation: … not a hidden system prompt.
|
||||
When you cannot wire a capability, declare it in the description (待开发 / 模拟)
|
||||
instead of faking success.
|
||||
```
|
||||
|
||||
**为什么这两处**:standing 定基调(每次对话开头),how-to-act 定动作(每轮)。
|
||||
只写 standing 容易被长上下文冲淡;只写 how-to-act 又缺"为什么要申报"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计要点
|
||||
|
||||
| 要点 | 说明 |
|
||||
|------|------|
|
||||
| 给**范式**而不是规则 | 直接给出可抄的 `[按关键词检索,接口未接,待开发](None)`,模型不必发明措辞 |
|
||||
| 给**返回值**要求 | "必须写清返回什么(None 也行)"——对应 `label.empty_payload` 的 warning |
|
||||
| 给**自查**动作 | `labels.search` 让模型收尾时能自己盘点,而不是靠人提醒 |
|
||||
| 用**英文**写 | 与既有 standing / 协议段语言一致(模型对英文指令更稳) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `marqdo check ext/ai/agent.mq.md`(occlusion 模式) | `contract check OK` |
|
||||
| 提示词文本落入模块 | `grep` 命中 2 处(standing 与 how-to-act 各 1) |
|
||||
| 全量回归 | 587 passed / 0 failed(与 M9 相同,本改动不动逻辑) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界
|
||||
|
||||
- 提示词是**建议**,不是门禁;违反不会被拒绝,但会在描述/诊断里暴露。
|
||||
- `labels.search` 需要 M7 翻转默认后对 classic 文档才有意义;提示词先就位。
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `ext/ai/agent.mq.md` | how-to-act 协议段与默认 standing 各追加申报约定 |
|
||||
| `doc/design/change-m10-engineering-habits.md` | 本文件 |
|
||||
@@ -0,0 +1,126 @@
|
||||
# 变更记录:M2 遮蔽语法 `[描述](实现)`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(模式开关默认仍是 classic) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M2([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/ast.rs` · `src/parse/expr.rs` · `src/parse/mod.rs` · `src/interp.rs` · `src/bytecode/compile.rs` · `src/view/render.rs` · `src/main.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 语法(新节点)+ 两个后端 + 渲染 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增语法
|
||||
|
||||
```markdown
|
||||
[描述](实现)
|
||||
```
|
||||
|
||||
- `[]` = **描述**(自由文本,**永不执行**;仅用于检索、统计、过期校验)
|
||||
- `()` = **实现**(唯一执行体)
|
||||
- `[]` 为空 → `label.missing`(error,M2.5 落诊断)
|
||||
- `()` 为空 → 值为 `None`(空载荷桩,M2.5 落 warning)
|
||||
|
||||
实测(`MARQDO_MARKUP=occlusion`):
|
||||
|
||||
```
|
||||
a=2 [加一之后的值](1 + 1)
|
||||
b=42 [外层]([内层](40 + 2)) ← 嵌套遮蔽
|
||||
c=True [某某功能开发中]() ← 空载荷 → None
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键决策:**模式开关,暂不切换语义**
|
||||
|
||||
`[键](集合)` 与 `[描述](实现)` **外形完全相同**。若 M2 直接改语义,全仓 506 处取元
|
||||
会**静默变成"遮蔽整个集合"** —— 这正是文档里点名的最坏一类变更(同形换义)。
|
||||
|
||||
因此 M2 只**实现能力**,不动默认:
|
||||
|
||||
| 模式 | `MARQDO_MARKUP` | `[a](b)` 的语义 |
|
||||
|------|-----------------|-----------------|
|
||||
| `Classic`(默认) | 未设 / 其他值 | 取元(今天的行为) |
|
||||
| `Occlusion`(纯度) | `occlusion` / `purity` / `1` / `on` | 遮蔽(描述 + 实现) |
|
||||
|
||||
**M7 才迁移语料并翻转默认**,同时对旧形报 `syntax.legacy_index` 硬错误。
|
||||
这样 M2 可独立验证,且不会出现"半迁移的静默错义"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现要点
|
||||
|
||||
### 3.1 AST
|
||||
|
||||
```rust
|
||||
Occluded {
|
||||
label: String,
|
||||
payload: Option<Box<Expr>>, // None = 空载荷桩(值 None)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 解析
|
||||
|
||||
- `Parser` 增加 `markup: Markup` 字段;`parse_expr_markup(input, prefer_var, markup)`
|
||||
供测试/迁移显式指定;CLI 通过 `MARQDO_MARKUP` 设置进程默认。
|
||||
- 描述扫描:读到 `]` 为止;`\]` 转义字面方括号;跨行即报未闭合。
|
||||
- 之后必须紧跟 `(`;`()` 内若无内容 → `payload: None`;否则 `parse_or()` 后要求 `)`。
|
||||
- 嵌套自然成立:payload 是完整表达式,可再含遮蔽。
|
||||
|
||||
### 3.3 求值(两个后端一致)
|
||||
|
||||
| 位置 | 处理 |
|
||||
|------|------|
|
||||
| `interp.rs` `eval_expr` | 有 payload → 求值 payload;无 → `Value::None` |
|
||||
| `bytecode/compile.rs` | 有 payload → 编译 payload;无 → `Op::None_` |
|
||||
| `collect_decl_reads` / `collect_reads_expr` | 递归 payload(描述不产生读引用) |
|
||||
| `view/render.rs` `expr_prec` | 渲染成 `[描述](payload)` / `[描述]()` |
|
||||
|
||||
**描述永不参与求值**——守住铁律 1。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(8) | 值直通 / 空载荷 / 描述含空格与标点 / `\]` 转义 / 嵌套 / classic 仍是取元 / 缺括号报错 | ✅ |
|
||||
| 集成(3) | `MARQDO_MARKUP=occlusion` 跑通三个值;不设该变量时旧取元不变;occlusion 模式下旧形**不再**是取元 | ✅ |
|
||||
| 全量 | `cargo test --release` | **575 passed / 0 failed**(M1 后 565 + 10) |
|
||||
| 双后端 | tree 与 `--backend bytecode` | 一致 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带重构
|
||||
|
||||
- `Markup` 枚举与 `parse_expr_markup` 抽为显式参数,避免测试依赖全局可变状态
|
||||
(全局只由 CLI 入口设置一次)。
|
||||
- `parse::expr` 由 `mod` 改 `pub mod`,供 `main.rs` 设置模式。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 描述不参与作用域/类型 | 写什么都不影响执行 |
|
||||
| 描述里的 `` `实体` `` | M4 才做引用一致性校验 |
|
||||
| 空载荷 warning | M2.5 落诊断(本提交只有语义) |
|
||||
| 跨行描述 | 不支持(v1) |
|
||||
| 旧取元 | 仍可用;M7 迁移后改为硬错误 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/ast.rs` | 新增 `Expr::Occluded { label, payload }` |
|
||||
| `src/parse/expr.rs` | `Markup` 枚举 + 全局默认 + `parse_expr_markup` + `parse_occluded` + `Parser.markup` |
|
||||
| `src/parse/mod.rs` | `pub mod expr`;`collect_reads_expr` 递归 payload |
|
||||
| `src/interp.rs` | 求值 + 读引用收集 |
|
||||
| `src/bytecode/compile.rs` | 编译为 payload(或 `None_`) |
|
||||
| `src/view/render.rs` | 表面渲染 + 输入提示收集 |
|
||||
| `src/main.rs` | `MARQDO_MARKUP` 环境变量 |
|
||||
| `tests/occlusion/value.mq.md` · `tests/occlusion/classic-index.mq.md` · `tests/occlusion.rs` | 新增集成测试 |
|
||||
| `doc/design/change-m2-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,91 @@
|
||||
# 变更记录:M2.5 遮蔽标签诊断(`label.missing` / `label.empty_payload`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M2.5([occlusion-syntax.md](occlusion-syntax.md) §13,诊断规范 §10) |
|
||||
| 改动文件 | **新增 `src/label.rs`** · `src/check.rs` · `src/lib.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | `marqdo check`(新增两类诊断) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 两条诊断
|
||||
|
||||
| code | 级别 | 触发 | 文案要点 |
|
||||
|------|------|------|---------|
|
||||
| `label.missing` | **error** | `[](实现)` 描述为空 | 「给这段实现写一句人话,或改用不带遮蔽的写法」 |
|
||||
| `label.empty_payload` | **warning** | `[描述]()` 载荷为空 | 「这里没有可执行内容」,建议写 `(None)` 或补实现 |
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
$ MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md
|
||||
empty-label.mq.md:3:1: 遮蔽缺少描述:`[](…)` —— 给这段实现写一句人话,或改用不带遮蔽的写法
|
||||
contract check: 1 条诊断(1 error) # exit 1
|
||||
|
||||
$ MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md
|
||||
empty-payload.mq.md:3:1: 空载荷遮蔽:`[某某功能开发中]()` —— 这里没有可执行内容
|
||||
contract check: 1 条诊断(0 error) # exit 0(warning 不影响退出码)
|
||||
```
|
||||
|
||||
JSON 出口(自动继承既有 schema,含 `doc_quote`):
|
||||
|
||||
```json
|
||||
{"code":"label.empty_payload","severity":"warning","span":{"line":3,"col":1},
|
||||
"doc_quote":"某某功能开发中","message":"空载荷遮蔽:…","suggestion":"写清桩的返回值(如 `(None)` 或 `(0)`)…"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 实现
|
||||
|
||||
### 2.1 新增 `src/label.rs`
|
||||
|
||||
- `OcclusionSite { label, has_payload, line, unit }`
|
||||
- `collect(module)`:遍历函数体与嵌套语句/表达式,收集所有遮蔽点
|
||||
(描述只读,**不产生任何读引用**)
|
||||
- `check(module, path)`:产出上面两条诊断
|
||||
|
||||
### 2.2 接入 `check_module`
|
||||
|
||||
```rust
|
||||
walk(module, &module.functions, path, &known, &mut out);
|
||||
out.extend(crate::label::check(module, path)); // M2.5
|
||||
```
|
||||
|
||||
设计上把"标签诊断"独立成模块,M4(引用一致性)与 M9(检索)都往这里加,
|
||||
`check` 只做一行汇总。
|
||||
|
||||
---
|
||||
|
||||
## 3. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3 新) | 空描述 → exit 1 + 文案;空载荷 → exit 0 + 文案;干净样例 → 无诊断 | ✅ |
|
||||
| 全量 | `cargo test --release` | **578 passed / 0 failed**(M2 后 575 + 3) |
|
||||
|
||||
反向验证:三条断言分别验证"会响"与"不会误响"(干净样例必须无输出)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 描述内容不校验 | 写什么都可以;M4 才校验反引号引用 |
|
||||
| 空载荷仅在 occlusion 模式可能出现 | classic 模式下 `()` 空是语法错 |
|
||||
| warning 不影响退出码 | 与既有 `Severity` 语义一致 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | **新增**:遮蔽点收集 + 两类诊断 |
|
||||
| `src/lib.rs` | `pub mod label;` |
|
||||
| `src/check.rs` | `check_module` 追加 label 诊断 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/{empty-label,empty-payload,clean}.mq.md` | 新增 3 个集成测试与样例 |
|
||||
| `doc/design/change-m25-label-diagnostics.md` | 本文件 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# 变更记录:M3 `access` 与遮蔽循环
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M3([occlusion-syntax.md](occlusion-syntax.md) §4 / §13) |
|
||||
| 改动文件 | `src/interp.rs` · `src/ast.rs` · `src/parse/mod.rs` · `src/bytecode/compile.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 新增内建 `access`;`Stmt::ForEach` 增可选标签 |
|
||||
|
||||
---
|
||||
|
||||
## 1. `access(集合, 键)`
|
||||
|
||||
旧取元 `[键](集合)` 的语义是**多态**的:Map 按键、List 按 1-based 下标、缺键报错。
|
||||
纯度路线把取元移进 `()`,因此需要一个与之**完全等价**的调用形式:
|
||||
|
||||
```markdown
|
||||
**a = [取表项](access(`表`, "键"))**
|
||||
**b = [取列表第二项](access(`列`, 2))**
|
||||
```
|
||||
|
||||
- 别名:`取` / `取值` / `access`
|
||||
- 缺键 → `missing map key …`(**与旧取元同一错误**,不静默返回 None)
|
||||
- 用途:M7 迁移把 `[k](c)` 机械改写成 `access(c, k)`,语义零漂移
|
||||
|
||||
实现:`interp.rs` 的 special-callee 分派里直接复用 `builtin_footnote_get`,
|
||||
**不新增平行实现**(避免两套索引语义)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 遮蔽循环
|
||||
|
||||
```markdown
|
||||
- [篮子里的每个果子](遍历 `列` 为 `果`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
- 只在 occlusion 模式识别(classic 模式下 `- [x](c)` 仍是旧 foreach)
|
||||
- 接受 `遍历`/`for` 与 `为`/`as`/`in`
|
||||
- 描述存入 `Stmt::ForEach.label`(`Option<String>`),供 M8 渲染/诊断使用
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
a=值
|
||||
b=二
|
||||
果子=一
|
||||
果子=二
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么先做 M3 再做 M7
|
||||
|
||||
迁移(M7)要把 506 处 `[k](c)` 改写掉,而改写目标必须**先存在且等价**。
|
||||
先有 `access` 与循环新形,迁移才是"机械替换",而不是"边迁移边发明语义"。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(2) | `access` 表/列表 + 循环遍历输出正确;缺键报 `missing map key`(与旧取元一致) | ✅ |
|
||||
| 全量 | `cargo test --release` | **595 passed / 0 failed**(M5 后 593 + 2) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `access` 不做缺省值 | 缺省语义请用 `get(表, 键, 默认)`;两者并存 |
|
||||
| 循环描述暂只存不用 | M8 在 `view` 与诊断里使用 |
|
||||
| 旧 foreach 仍可用 | M7 迁移并加门禁后才变成错误 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/interp.rs` | `access` / `取` / `取值` 分派(复用 `builtin_footnote_get`) |
|
||||
| `src/ast.rs` | `Stmt::ForEach.label: Option<String>` |
|
||||
| `src/parse/mod.rs` | `parse_occluded_foreach`;occlusion 模式下优先识别 |
|
||||
| `src/bytecode/compile.rs` / `src/ast.rs` / `src/interp.rs` | 穷举模式补 `label: _` |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/access-and-loop.mq.md` | 2 个集成测试 |
|
||||
| `doc/design/change-m3-access-and-loop.md` | 本文件 |
|
||||
@@ -0,0 +1,84 @@
|
||||
# 变更记录:M4 L1 引用一致性(`label.ref_dangling`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M4([label-freshness-and-repair.md](label-freshness-and-repair.md) §3.1 / [occlusion-syntax.md](occlusion-syntax.md) §11.1) |
|
||||
| 改动文件 | `src/label.rs` · `tests/occlusion.rs` · `tests/occlusion/ref-*.mq.md` |
|
||||
| 影响面 | `marqdo check`(新增一条 error) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 规则
|
||||
|
||||
> 描述里用反引号写出的名字 = **断言**:它必须能解析
|
||||
> —— 要么 `()` 的实现用到它,要么文档里定义了它,要么它是内置函数。
|
||||
|
||||
```markdown
|
||||
**a = [按 `税率` 计算](100 * 0.1)** # ❌ label.ref_dangling(税率为空悬)
|
||||
**b = [按 `税率` 算](100 * `税率`)** # ✅ 实现里用到
|
||||
**c = [取长度](len("abc"))** # ✅ 内置函数
|
||||
**d = [用 `加` 求和](> 加 1 2))** # ✅ 模块内函数
|
||||
```
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
dangling.mq.md:3:1: 描述引用了不存在的实体:`税率` —— 本段实现没有用到它,模块里也没有定义
|
||||
contract check: 1 条诊断(1 error) # exit 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么只认反引号(可证伪原则)
|
||||
|
||||
| 写法 | 是否检查 | 原因 |
|
||||
|------|---------|------|
|
||||
| `` `税率` `` | ✅ | 显式引用,可证伪 |
|
||||
| 普通汉字"税率" | ❌ | 自然语言无法机械判定,检查必然假阳性 |
|
||||
|
||||
代价:作者不写反引号就得不到保护。这是刻意的——**机器只校验它看得懂的断言**,
|
||||
同时反向抑制"为凑数写废话"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现
|
||||
|
||||
| 环节 | 做法 |
|
||||
|------|------|
|
||||
| 抽取 | `refs(label)`:扫描成对反引号,取内部去空白;未闭合/空串忽略 |
|
||||
| 作用域 | `payload_idents(payload)`(Var / callee / path / receiver / `[k]` 的变量键 / 插值变量)∪ `module_symbols(module)`(函数与子函数、参数、import/use 绑定、frontmatter 键)∪ `HostFn::from_name` |
|
||||
| 诊断 | `label.ref_dangling`,**error**,带 `doc_quote`(描述原文)与可执行建议 |
|
||||
|
||||
`OcclusionSite` 增加 `payload_idents` 字段,在 `collect` 阶段一次算好,`check` 只做集合查找。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(3) | 单引用 / 多引用与散文混排 / 无引用与未闭合反引号不 panic | ✅ |
|
||||
| 集成(2) | 悬空引用 exit 1 + 文案;三类可解析引用(payload 变量 / 内置 / 模块函数)零诊断 | ✅ |
|
||||
| 全量 | `cargo test --release` | **583 passed / 0 failed**(M2.5 后 578 + 5) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界与后续
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只查"能否解析" | 不查"语义是否仍成立"——那是 T1(M6)与人工/LLM 复核的活 |
|
||||
| 不查"能解析但实现没用到" | 该情形在模块级符号时无法区分误报,留待 T1 变更驱动 |
|
||||
| 描述里的反引号不是变量绑定 | 只是断言,不进入任何作用域 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `refs()` · `payload_idents()` · `module_symbols()` · `OcclusionSite.payload_idents` · `check` 增 `label.ref_dangling` · 3 个单测 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/{ref-dangling,ref-ok}.mq.md` | 2 个集成测试 |
|
||||
| `doc/design/change-m4-label-refs.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 变更记录:M5 隐式遮蔽(`>` 调用上方的叙述)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(**默认关闭**,`--implicit-labels` 开启) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M5([occlusion-syntax.md](occlusion-syntax.md) §11.2) |
|
||||
| 改动文件 | `src/label.rs` · `src/check.rs` · `src/main.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | `marqdo check` 新增可选检查(默认不改变输出) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 规则
|
||||
|
||||
> **`>` 调用上方的叙述段**就是它的"描述";段内的反引号实体必须被这次调用用到
|
||||
> (或能解析到模块/内置)。
|
||||
|
||||
```markdown
|
||||
按 `税率` 与 `档位` 计算应缴税额: ← 描述
|
||||
|
||||
> 计税 档位=2 金额=100 ← 实现用到了 `档位`,但没有 `税率`
|
||||
```
|
||||
|
||||
```
|
||||
impl.mq.md:5:1: 调用上方的描述提到 `税率`,但这次调用没有用到它
|
||||
```
|
||||
|
||||
段落边界:紧邻上一行起,遇空行(允许**一个**分隔空行,因为 blockquote 前通常空一行)、
|
||||
标题、代码行(`**`/`>`/`-`/`|`/数字开头)即止。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键决策:**默认关闭**
|
||||
|
||||
这不是洁癖,是实测结论:
|
||||
|
||||
| 阶段 | lib + ext/ai 上的警告数 |
|
||||
|------|------------------------|
|
||||
| 初版(任何反引号都算断言) | **6 条**(全部误报:`` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `exec` ``/`` `net` ``) |
|
||||
| 加"实体名形状"过滤 | 2 条 |
|
||||
| **再加默认关闭** | **0 条** |
|
||||
|
||||
理由:**描述一个调用可以用任意措辞**,这比"遮蔽"松散得多;
|
||||
机械校验必然模糊,默认开启就会制造疲劳(违背 [warning-fatigue-control.md](warning-fatigue-control.md))。
|
||||
所以它和 L1 不同:L1 是"能证明才报",隐式检查是"觉得可疑就报"——后者必须 opt-in。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实体名过滤(降低误报)
|
||||
|
||||
反引号内容必须**像实体名**才算断言:
|
||||
|
||||
```rust
|
||||
首字符:字母 / `_` / 非 ASCII(不能是数字)
|
||||
其余:字母数字 / `_` / `.` / 非 ASCII 且非空白
|
||||
```
|
||||
|
||||
于是 `` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `path=` `` 全部被排除。
|
||||
|
||||
---
|
||||
|
||||
## 4. 用法
|
||||
|
||||
```bash
|
||||
marqdo check 文件.mq.md # 默认:不含隐式检查(零噪音)
|
||||
marqdo check 文件.mq.md --implicit-labels # 开启
|
||||
```
|
||||
|
||||
MLSP 侧留了同义参数位(`validate` 的 `implicit_labels`),M8 一并接。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3) | 默认静默;opt-in 报不一致;opt-in 对一致描述仍静默 | ✅ |
|
||||
| 全量 | `cargo test --release` | **593 passed / 0 failed**(M6 后 590 + 3) |
|
||||
|
||||
**反向验证**:`implicit_labels_off_by_default` 与 `..._stays_quiet_when_consistent`
|
||||
两条都在证明"不乱响"。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只查 `>` 语句调用 | 表达式内调用没有"上方叙述"这回事 |
|
||||
| 只认反引号 + 实体形状 | 普通散文永远不参与 |
|
||||
| 不查 payload 语义 | 只查"提到的实体是否被用到" |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `CallSite` · `call_sites` · `paragraph_above` · `is_entity_ref` · `check_implicit` |
|
||||
| `src/check.rs` | `check_path_opts(path, implicit_labels)`(`check_path` 保持默认关闭) |
|
||||
| `src/main.rs` | `check --implicit-labels` |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/implicit-*.mq.md` | 3 个集成测试 |
|
||||
| `doc/design/change-m5-implicit-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,109 @@
|
||||
# 变更记录:M6 T1 会话内陈旧检测 + 会话末汇总
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M6([t1-session-staleness.md](t1-session-staleness.md) · [staleness-providers.md](staleness-providers.md) T1) |
|
||||
| 改动文件 | `src/label.rs` · `src/mlsp.rs` · `src/view/mod.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | MLSP `repair_apply` 新增可选字段;新增 `session.summary` 方法 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 机制
|
||||
|
||||
`repair_apply` 内部同一作用域里同时有 `source`(改前)与 `new_source`(改后),
|
||||
所以「描述是否还成立」可以**纯内存**判定:
|
||||
|
||||
```
|
||||
stale ⟺ 标签文本未变 ∧ payload 指纹变了
|
||||
```
|
||||
|
||||
配对按 `(标签文本, 出现序号)`,因此**移动代码不会误报**。
|
||||
|
||||
请求:
|
||||
|
||||
```json
|
||||
{"method":"repair_apply","params":{
|
||||
"source":"…","ranges":[[3,3]],
|
||||
"edits":[{"op":"replace","line":3,"text":"**a = [按税率算总价](100 * 0.2)**"}],
|
||||
"check_labels":true}}
|
||||
```
|
||||
|
||||
响应:
|
||||
|
||||
```json
|
||||
{"id":1,"ok":true,"result":{
|
||||
"source":"…","edits_applied":1,
|
||||
"labels":{"newly_seen":1,"stale":[
|
||||
{"label":"按税率算总价","line":3,
|
||||
"code_past":"100 * 0.1","code_now":"100 * 0.2"}]}}}
|
||||
```
|
||||
|
||||
**同一份 `source` / `new_source` 就是"前一状态"**——不需要 git、不需要台账、
|
||||
不需要沙箱里的 exec 权限。这是"agent 回路不需要 VCS"的落地。
|
||||
|
||||
---
|
||||
|
||||
## 2. 会话末汇总(你要求做)
|
||||
|
||||
`session.summary` 返回并**重置**计数:
|
||||
|
||||
```json
|
||||
{"ok":true,"labels_stale_seen":1,"labels_fixed":0,
|
||||
"labels_outstanding":1,"items":["按税率算总价"]}
|
||||
```
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `labels_stale_seen` | 本次会话累计发现过多少条(去重按标签) |
|
||||
| `labels_fixed` | 曾经 outstanding、现在不再 stale 的条数 |
|
||||
| `labels_outstanding` | 仍未处理 |
|
||||
| `items` | 未处理的标签文本(只给文本,不重复诊断细节) |
|
||||
|
||||
设计:客户端在收尾时调用一次即可闭合;**不主动打屏**,不污染协议。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键取舍
|
||||
|
||||
| 取舍 | 理由 |
|
||||
|------|------|
|
||||
| `check_labels` 默认 **false** | 零开销、零噪音;agent 框架在修复回路里显式打开 |
|
||||
| 标签变了 → **不报** | 作者改描述本身就是"已复核"的信号 |
|
||||
| 新标签 → 不报 | 无历史可比 |
|
||||
| 指纹用 `Debug` | **只需进程内一致**;跨版本稳定指纹是 T2/T3 的事 |
|
||||
| payload 渲染用 `view::expr_display` | 让 `code_past/code_now` 是人能读的表面语法,而非 AST 调试串 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3) | 只改 payload → `stale` 含 `code_past`/`code_now`;同时改标签 → `stale: []`;`session.summary` 计数正确 | ✅ |
|
||||
| 全量 | `cargo test --release` | **590 passed / 0 failed**(M10 后 587 + 3) |
|
||||
|
||||
**反向验证**:`t1_silent_when_label_also_changes` 证明"改描述即复核"不会误报。
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只看本次编辑 | 跨会话漂移是 T2/T3 的职责(可选 provider) |
|
||||
| 解析失败则跳过 | 修复后的源码可能语法错误,此时不评测标签,交给 `validate` |
|
||||
| 会话状态是进程级 | 一条 MLSP 连接(一个进程)即一个会话;`session.summary` 后清零 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `StaleItem` · `payload_fingerprint` · `compare` · `SessionSummary`(含 `record`)· `OcclusionSite.payload_fp/payload_src` |
|
||||
| `src/mlsp.rs` | `repair_apply` 的 `check_labels`;`session.summary`;进程级 `SESSION` |
|
||||
| `src/view/mod.rs` | `pub use render::expr_display`(供诊断渲染 payload) |
|
||||
| `tests/occlusion.rs` | 3 个 T1 集成测试 |
|
||||
| `doc/design/change-m6-t1-session.md` | 本文件 |
|
||||
@@ -0,0 +1,127 @@
|
||||
# 变更记录:M7 迁移与版本门(per-file 标记 + `migrate labels` + 全仓迁移)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M7([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | **新增 `src/migrate.rs`** · `src/load.rs` · `src/parse/mod.rs`(expr) · `src/host/dispatch.rs` · **80 个语料文件** · 测试 |
|
||||
| 影响面 | 语法模式按文件切换;全仓 256 处索引 + 23 处循环已迁移 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原计划的问题:同形换义
|
||||
|
||||
原设计想"翻转默认 + 对旧形硬报错"。但 `[键](集合)` 与 `[描述](实现)` **外形完全相同**:
|
||||
|
||||
- 翻转默认 → 506 处取元**静默变成**"遮蔽整个集合",正是文档点名的最坏变更
|
||||
- 硬报错 → 无法实现:解析器拿不到"这是旧写法"的证据(两种读法都合法)
|
||||
|
||||
**结论:模式不能全局翻转,必须按文件声明。**
|
||||
|
||||
## 2. 新方案:per-file `markup:`
|
||||
|
||||
```markdown
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
```
|
||||
|
||||
| 文件 | 解析模式 | `[a](b)` 的含义 |
|
||||
|------|---------|----------------|
|
||||
| 无 `markup:` | classic(进程默认) | 取元 |
|
||||
| `markup: occlusion` | 纯度 | 遮蔽 |
|
||||
|
||||
实现:`load.rs` 先读 frontmatter 取出模式,用 `parse::expr::with_markup(m, …)`
|
||||
(线程局部覆盖,压栈/出栈)包住解析。**同一进程里可以同时加载两种模式的文件**
|
||||
(imports!),且 `MARQDO_MARKUP=occlusion` 仍可作为进程默认。
|
||||
|
||||
好处:迁移是**逐文件、可增量、可回滚**的;不存在"半迁移的静默错义"。
|
||||
|
||||
## 3. 迁移工具 `marqdo migrate labels`
|
||||
|
||||
```bash
|
||||
marqdo migrate labels . # 干跑:列出将改什么
|
||||
marqdo migrate labels . --write # 实际写入
|
||||
marqdo migrate labels . --json # 机器可读
|
||||
```
|
||||
|
||||
### 3.1 改写规则
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| `[键](集合)` | `[键](access(集合, "键"))` |
|
||||
| `` [`名`](集合) `` | `` [名](access(集合, `名`)) `` |
|
||||
| `- [项](集合)` | `- [项](遍历 集合 为 项)` |
|
||||
|
||||
`access` 是新增宿主函数(`host_access`,id 212),语义与旧取元**逐字一致**
|
||||
(Map 按键 / List 1-based / 缺键 `missing map key`)。它进 `HostFn` 是有意的:
|
||||
**两个后端共用同一实现**,不再有特例分支。
|
||||
|
||||
### 3.2 安全模型:改写 → 重解析 → 证明等价 → 才写
|
||||
|
||||
1. 原文件按 classic 解析,得到 AST-A
|
||||
2. 文本改写后,按 occlusion 解析,得到 AST-B
|
||||
3. **反归一化** B:把"标签与键同名 + payload 为 `access(x, k)`"的遮蔽还原成 `Index`
|
||||
4. 比较 `Debug(A)` 与 `Debug(反归一化(B))`(抹掉行号,因为插入了 marker 行)
|
||||
5. 只有相等才写入;否则**原文件一字不动**并报告 `equivalence check failed`
|
||||
|
||||
这条校验是真干活的:它先后抓出 4 类改写 bug(表格散文链接、payload 继承文本模式、
|
||||
链式索引、`[问候] (…)` 与遮蔽混淆),每一类都是**先被拦下、再修工具**,没有污染文件。
|
||||
|
||||
### 3.3 只改代码行
|
||||
|
||||
用词法层的 `LineKind::Code` 限定范围;表格行只改 `**…**` 单元格
|
||||
(散文里的 markdown 链接 `[docs](https://…)` 必须原样保留)。
|
||||
|
||||
### 3.4 由内向外
|
||||
|
||||
链式索引 `[content]([1]([messages](req)))` 必须**最内层先改**,
|
||||
否则外层改写会让内层的位置失效;已迁移的 `[k](access(…))` 有守卫,不会二次改写。
|
||||
|
||||
## 4. 全仓迁移结果
|
||||
|
||||
```
|
||||
migrate labels: 256 index, 23 loop, 80 file written
|
||||
```
|
||||
|
||||
- 覆盖 `lib/ ext/ examples/ public/ cli/ tests/`
|
||||
- **0 文件被等价性检查拒绝**
|
||||
- 迁移后 `cargo test --release` → **604 passed / 0 failed**
|
||||
- 再跑一次迁移 → **幂等**(只剩刻意保留的 classic 测试样例)
|
||||
|
||||
## 5. 顺带修的两处真实语义缺陷
|
||||
|
||||
| 缺陷 | 现象 | 修法 |
|
||||
|------|------|------|
|
||||
| payload 继承外层"文本模式" | `f text=[k](access(c,k))` 里 `access(...)` 不被当调用 → 退化成插值文本 | `()` 内**永远**允许 `callee(args)`(`parse_occluded` 临时置位) |
|
||||
| 遮蔽形状判定过宽 | `[问候] ([格式化] "Bo")` 被误判为遮蔽 | 要求 `]` 后**紧跟** `(`;否则落回方括号调用 |
|
||||
|
||||
## 6. 版本门
|
||||
|
||||
- 旧写法**不再**被硬报错——因为无法与遮蔽区分;真正的门是 **per-file 声明**:
|
||||
没写 `markup: occlusion` 的文件按 classic 解析,行为不变。
|
||||
- 需要"禁止新写旧形"的仓库可用 `migrate labels` 干跑做 CI 门禁(有改动即失败)。
|
||||
|
||||
## 7. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(6) | 静态键 / 动态键 / 嵌套三层 / 已迁移不重写 / 循环 / 非循环 | ✅ |
|
||||
| 集成(3) | 干跑不写盘;写入后**运行输出不变**且幂等;等价失败则文件不动 | ✅ |
|
||||
| 全量 | `cargo test --release` | **604 passed / 0 failed**(M3 后 595 + 9) |
|
||||
| 双后端 | gold 套件含 bytecode 变体 | ✅ |
|
||||
|
||||
## 8. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/migrate.rs` | **新增**:改写器、等价性证明、`migrate_file` / `migrate_path` |
|
||||
| `src/load.rs` | `frontmatter_markup` + `with_markup` 包裹两处 `parse_source` |
|
||||
| `src/parse/expr.rs` | `with_markup` 线程局部覆盖;`()` 内强制允许调用;`occlusion_shape_ahead` 严格判定 |
|
||||
| `src/host/dispatch.rs` | `HostFn::Access`(enum / from_u16 212 / from_name / name / required_params / call_host) |
|
||||
| `src/main.rs` | `migrate labels` 子命令 |
|
||||
| `src/interp.rs` | 移除 access 特例(改用 HostFn,单一实现) |
|
||||
| 80 个语料文件 | 索引与循环迁移 + `markup: occlusion` 标记 |
|
||||
| `tests/migrate.rs` + `src/migrate.rs` 单测 | 9 个测试 |
|
||||
| `doc/design/change-m7-migration.md` | 本文件 |
|
||||
@@ -0,0 +1,81 @@
|
||||
# 变更记录:M8 债务棘轮与呈现
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M8([warning-fatigue-control.md](warning-fatigue-control.md) §4 棘轮 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/main.rs` · `tests/ratchet.rs` |
|
||||
| 影响面 | `labels` 新增 `--baseline` / `--fail-on-increase` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 棘轮规则
|
||||
|
||||
```bash
|
||||
# CI:未完成项只许减少,不许增加
|
||||
marqdo labels . --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
| 情形 | 行为 | 退出码 |
|
||||
|------|------|--------|
|
||||
| 台账不存在 | **建立**(写入当前计数),提示 `已建立 N` | 0 |
|
||||
| 当前 > 台账 | 失败,提示 `未完成项增加了 K` | **1** |
|
||||
| 当前 ≤ 台账 | 通过;若减少则**收紧**台账(`N → M`) | 0 |
|
||||
|
||||
**为什么"减少即收紧"**:否则债务可以先降后升,棘轮形同虚设。
|
||||
收紧后台账记住新的低水位,回退到旧数量同样会失败(测试第 4 步验证)。
|
||||
|
||||
台账格式:
|
||||
|
||||
```json
|
||||
{"count": 1, "words": ["待开发", "未开发", "…"]}
|
||||
```
|
||||
|
||||
记录词集是为了让"口径变了"可被审计——换词集时会看到 `words` 变化。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么用棘轮而不是硬门禁
|
||||
|
||||
| 方案 | 老债 | 新债 | 结论 |
|
||||
|------|------|------|------|
|
||||
| 硬门禁(必须为 0) | 阻塞一切 | 拦住 | 存量债立刻红一片,逼人关检查 |
|
||||
| **棘轮(只拦增量)** | 不阻塞 | 拦住 | ✅ 债务可见且不恶化 |
|
||||
| 无门禁 | 不阻塞 | 不拦 | 债务无声增长 |
|
||||
|
||||
这与 [warning-fatigue-control.md](warning-fatigue-control.md) 的结论一致:
|
||||
**老账不追、新账必拦**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 呈现(已具备)
|
||||
|
||||
| 面 | 表现 |
|
||||
|----|------|
|
||||
| `expr_display` / `view` | 遮蔽渲染为 `[描述](实现)`,桩渲染为 `[描述]()`,实测 `view output` 页面含 `access(` |
|
||||
| `labels` | 人类行 `文件:行 [函数] 描述 ← 命中词`;`--json` 一个数组 |
|
||||
| `check` | `label.*` 三类诊断(missing / empty_payload / ref_dangling) |
|
||||
| MLSP | `labels.search` · `session.summary` |
|
||||
|
||||
**没有做桩徽章**:桩已经是 `[描述]()` 这个显眼形状,再加装饰是噪音;
|
||||
需要计数时用 `labels --count`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(1 个四步用例) | 建账 → 增加失败 → 减少收紧 → 回退再次失败 | ✅ |
|
||||
| 全量 | `cargo test --release` | **605 passed / 0 failed**(M7 后 604 + 1) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/main.rs` | `labels --baseline` / `--fail-on-increase`;建账/收紧/违约逻辑 |
|
||||
| `tests/ratchet.rs` | 四步棘轮用例 |
|
||||
| `doc/design/change-m8-ratchet.md` | 本文件 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# 变更记录:M8 view 遮蔽呈现(+ 修一个真实回归)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [occlusion-syntax.md](occlusion-syntax.md) §13 M8「view 徽章/呈现」 |
|
||||
| 改动 | `src/load.rs` · `src/view/{document,render,html,mod,debug_page}.rs` |
|
||||
| 影响 | 只影响呈现;顺带修了 **view 无法解析遮蔽文件** 的回归 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 先修回归:view 用错解析模式
|
||||
|
||||
`view` 内部多处直接用 `crate::parse::parse_source(source)` 重新解析文件,
|
||||
而 per-file `markup:` 是在 `load` 层生效的(M7)。结果:
|
||||
|
||||
```
|
||||
<div class="structure"><div class="err">parse/load error: expected ')' after link-index collection</div></div>
|
||||
```
|
||||
|
||||
任何带 `markup: occlusion` 的文档在 view 里**结构区直接报错**,只能退化成源码视图。
|
||||
用户看到的"粗体里的 `[描述](实现)` 没渲染"其实是这个错误的表象。
|
||||
|
||||
**修法**:`load::parse_source_auto(source)` —— 先读 frontmatter 的 `markup:`,
|
||||
用 `with_markup` 包住 `parse_source`,view 的五处解析点全部改用它。
|
||||
|
||||
## 2. 遮蔽呈现
|
||||
|
||||
### 2.1 浏览视图(`document.rs`,`/file`)
|
||||
|
||||
```html
|
||||
<div class="doc-line doc-occl" data-line="81">
|
||||
<span class="occl-pre">留存 =</span> <!-- 变量名:灰、等宽 -->
|
||||
<span class="occl-label">客户留存率,模拟数据</span> <!-- 描述:正文 -->
|
||||
<code class="occl-code">0.42</code> <!-- 实现:代码片 -->
|
||||
</div>
|
||||
```
|
||||
|
||||
- 空载荷 → `<span class="occl-stub">桩</span>`(琥珀色徽章,title 说明"未接通或待补返回值")
|
||||
- 前缀里的反引号/`**` 都剥掉(与其它行 `mq-anchor` 的处理一致)
|
||||
- 只在词法上切分,不改语义:解析器早已验证结构,这里只决定怎么画
|
||||
|
||||
### 2.2 卡片视图(`render.rs`,`/debug`)
|
||||
|
||||
按 AST 直接匹配 `Expr::Occluded`(`Assign` / `Expr` / `Return` 三种语句),
|
||||
渲染成 `card occl-card`:徽章「遮蔽」+ 变量名 + 描述 + 代码片/桩徽章。
|
||||
|
||||
### 2.3 样式(`html.rs`)
|
||||
|
||||
```css
|
||||
.doc-occl { display:flex; align-items:baseline; flex-wrap:wrap; gap:.4rem; }
|
||||
.occl-pre { font-family:var(--mono); font-size:.86em; color:var(--muted); }
|
||||
.occl-label { color:var(--ink); }
|
||||
.occl-code { font-family:var(--mono); background:var(--fill); border:1px solid var(--line);
|
||||
border-radius:6px; padding:.02rem .38rem; }
|
||||
.occl-stub { background:rgba(255,159,10,.18); color:#9a5b00; border-radius:999px; }
|
||||
```
|
||||
|
||||
刻意**不加**虚线下划线:容易被读成链接/缩写。描述就是正文,靠代码片的边框与之区分。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| 结构区解析错误 | **消失**(`/file` 页面 0 处 `parse/load error`) |
|
||||
| 七个遮蔽行 | 全部渲染为 `doc-occl`:6 个代码片 + 1 个桩徽章 |
|
||||
| 文本抽取 | `留存 = 客户留存率,模拟数据 [0.42]` / `待接 = 搜索接入,接口未接,待开发 [桩]` |
|
||||
| 单元(4) | 裸赋值 / 粗体赋值 / 空载荷+嵌套 payload / 非遮蔽行不误判 |
|
||||
| 全量 | `cargo test --release` **613 passed / 0 failed**(609 + 4) |
|
||||
|
||||
## 4. 未能做到的:截图
|
||||
|
||||
本机没有任何浏览器(`chromium`/`chrome`/`firefox` 均不存在),
|
||||
`npm i puppeteer` 装上了包但 Chromium 下载被网络阻断(`storage.googleapis.com`
|
||||
TLS 断连,两次重试均失败)。所以无法自动截图比对,改为:
|
||||
DOM 结构断言 + 提供 `/.preview/occlusion.html` 方案对照页由作者目视确认。
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/load.rs` | 新增 `parse_source_auto`(按 frontmatter `markup:` 解析) |
|
||||
| `src/view/mod.rs` | 3 处解析改 `parse_source_auto` |
|
||||
| `src/view/debug_page.rs` | 1 处同上 |
|
||||
| `src/view/document.rs` | `split_occlusion` / `match_delim` / `render_occlusion_line` + 4 个单测 |
|
||||
| `src/view/render.rs` | `occl_card` + 三个 `Expr::Occluded` 语句分支 |
|
||||
| `src/view/html.rs` | `.doc-occl` / `.occl-*` 样式 |
|
||||
| `doc/design/change-m8-view-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,113 @@
|
||||
# 变更记录:M9 两级词表检索(`labels` CLI + MLSP `labels.search`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M9([occlusion-description-and-search.md](occlusion-description-and-search.md) §3 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/label.rs` · `src/main.rs` · `src/mlsp.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 新增 CLI 子命令与 MLSP 方法(**不改语法**) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 两级词表
|
||||
|
||||
| 级 | 在哪 | 作用 |
|
||||
|----|------|------|
|
||||
| **第一级:内置** | `label::BUILTIN_GROUPS`(数据常量) | 默认查询 + LLM 范例 + 跨项目可比 |
|
||||
| **第二级:参数** | `--grep` / `grep` | 替换或并集,项目自己的说法照样能搜 |
|
||||
|
||||
内置六组:`未完成`(待开发/未开发/开发中/未实现/待实现/未接/接口未接/TODO)、
|
||||
`假数据`(模拟/假数据/桩/占位/stub/mock)、`示例`、`实验`、`废弃`、`待校验`。
|
||||
`pending` = `未完成 ∪ 假数据`。
|
||||
|
||||
**词表是数据不是语法**:扩充它不改任何解析规则。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo labels . # 默认:pending 口径(内置两组)
|
||||
marqdo labels . --grep "联调" # 替换为自定义词
|
||||
marqdo labels . --grep "联调" --also-builtin # 自定义 ∪ 内置
|
||||
marqdo labels . --group 示例,实验 # 选内置组
|
||||
marqdo labels . --count # 只给数字(CI/棘轮用)
|
||||
marqdo labels . --json # 一个 JSON 数组
|
||||
```
|
||||
|
||||
输出(人类):
|
||||
|
||||
```
|
||||
a.mq.md:3 [main] 按关键词检索,接口未接,待开发 ← 待开发,未接,接口未接
|
||||
a.mq.md:4 [main] 客户留存率,模拟 ← 模拟
|
||||
label search: 2 命中(1 文件,词=[…])
|
||||
```
|
||||
|
||||
`--json`:
|
||||
|
||||
```json
|
||||
[{"file":"a.mq.md","line":3,"unit":"main","label":"…","words":["待开发"],"has_payload":true}]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. MLSP
|
||||
|
||||
```json
|
||||
{"id":1,"method":"labels.search",
|
||||
"params":{"source":"…"|"path":"…","grep":["联调"],"also_builtin":true}}
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```json
|
||||
{"ok":true,"words":[…],"count":2,"hits":[{"line":3,"unit":"main","label":"…",
|
||||
"words":["待开发"],"has_payload":true}]}
|
||||
```
|
||||
|
||||
语义与 CLI 完全一致(同一份 `label::search`)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 检索语义(v1)
|
||||
|
||||
| 项 | 规则 |
|
||||
|----|------|
|
||||
| 匹配 | **子串**(CJK 无词边界,子串最稳) |
|
||||
| 多词 | OR |
|
||||
| 大小写 | 英文不敏感(`TODO`/`todo` 等价) |
|
||||
| 误判 | 必然存在(`[不属于待开发范围]` 会命中)——只影响计数,输出带描述原文可人工判断 |
|
||||
|
||||
不做否定语法;留作 v1.1 可选项。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(4) | pending 计数=2;`--grep` 替换=1;`--also-builtin` 并集=3;MLSP `labels.search` 返回 hits | ✅ |
|
||||
| 全量 | `cargo test --release` | **587 passed / 0 failed**(M4 后 583 + 4) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只在 occlusion 模式产生命中 | classic 模式下没有 `Expr::Occluded`;M7 翻转默认后自然可用 |
|
||||
| 解析失败的文件跳过 | 那是 `check` 的职责,检索不应因一个坏文件整体失败 |
|
||||
| 不做棘轮 | `--baseline` / `--fail-on-increase` 留给 M8(门禁) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `WordGroup` / `BUILTIN_GROUPS` / `PENDING_GROUPS` / `group_words` / `parse_words` / `matched_words` / `Hit` / `search` |
|
||||
| `src/main.rs` | `labels` 子命令 + `collect_mq_files` 递归扫描 |
|
||||
| `src/mlsp.rs` | `labels.search` 方法 + 分发 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/labels.mq.md` | 4 个集成测试 |
|
||||
| `doc/design/change-m9-label-search.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 变更记录:插件 ABI 共享 crate(`marqdo-plugin-sdk`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 1 项 |
|
||||
| 改动 | **新增 `crates/marqdo-plugin-sdk`** · 5 个插件改为依赖它 |
|
||||
| ABI | **不变**(`include/marqdo_abi.h`、`src/host/plugin.rs` 看到的符号与布局完全一致) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
5 个原生插件各自复制同一套 ABI 前言(约 140 行/个):
|
||||
|
||||
| 复制的内容 | 说明 |
|
||||
|-----------|------|
|
||||
| `type PluginFn` / `HostQueryFn` / `struct MarqdoHostApi` | 布局必须逐字一致,抄错就是 UB |
|
||||
| `static mut HOST_ALLOC/FREE/QUERY/USERDATA` | 同上 |
|
||||
| `host_strdup` / `set_out` / `set_err` / `parse_args` / `reply` | 语义必须一致 |
|
||||
| `register` + `#[no_mangle]` 四导出 | 样板 |
|
||||
|
||||
一共 5 份,任何一份漂移都会在运行期表现为"某插件偶发崩"。
|
||||
|
||||
## 2. 方案
|
||||
|
||||
新增工作区成员 `crates/marqdo-plugin-sdk`,持有唯一一份实现,并提供一个宏生成各 `.so` 必需的导出:
|
||||
|
||||
```rust
|
||||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||||
("llm_ping", "", llm_ping),
|
||||
("llm_chat_completions", "base_url,api_key,...", llm_chat_completions),
|
||||
]);
|
||||
```
|
||||
|
||||
宏展开为 `marqdo_plugin_abi_version` / `marqdo_plugin_shutdown` / `marqdo_plugin_init`,
|
||||
其中 init 调 `init_plugin(host, &[…])`(保存回调 + 逐个注册)。
|
||||
|
||||
`demo` 是 ABI **v1**,宏接受版本参数:`marqdo_plugin!(1, [...])`,语义不变。
|
||||
|
||||
## 3. 安全措施:注册项逐一核对
|
||||
|
||||
迁移时把每个插件的 `register(...)` 调用抽取成表。**第一次抽取漏了 11 项**——
|
||||
正则是 `[a-z_0-9]+`,匹配不到 `mcp_server::agent_mcp_serve`、`sandbox::*` 这类
|
||||
**路径限定**的函数名。编译能过(表少几行),运行时才会 `unknown function`。
|
||||
|
||||
补救:正则允许 `::`,并把新旧两张表逐项比对:
|
||||
|
||||
| 插件 | HEAD 注册项 | 迁移后 | 差异 |
|
||||
|------|------------|--------|------|
|
||||
| agent | 63 | 63 | **0** |
|
||||
| quantum | 41 | 41 | 0 |
|
||||
| linalg | 31 | 31 | 0 |
|
||||
| llm | 2 | 2 | 0 |
|
||||
| demo | 2 | 2 | 0 |
|
||||
|
||||
比对脚本同时校验 `(名称, 参数串, 函数)` 三元组完全一致,不只比数量。
|
||||
|
||||
另外两次由"编译通过但语义已变"暴露的问题:
|
||||
|
||||
| 问题 | 现象 | 处理 |
|
||||
|------|------|------|
|
||||
| `mcp_client` 被误判为死模块 | 我删掉 327 行后发现 `agent_mcp_client` 正注册它 | 恢复模块(教训:先查注册表,再判死) |
|
||||
| 量子插件两个"未使用"函数 | 删除时连带吃掉 `density_from_amps`/`flat_to_nested` | 恢复并加 `#[allow(dead_code)]` 注释 |
|
||||
|
||||
## 4. 收益
|
||||
|
||||
| 插件 | 迁移前 | 迁移后 | 变化 |
|
||||
|------|--------|--------|------|
|
||||
| agent | 1,237 | 929 | −308 |
|
||||
| quantum | 1,045 | 835 | −210 |
|
||||
| linalg | 688 | 524 | −164 |
|
||||
| llm | 405 | 278 | −127 |
|
||||
| demo | 170 | 73 | −97 |
|
||||
| 新增 SDK | — | 232 | +232 |
|
||||
|
||||
净减 **≈ 906 − 232 = 674 行**,且 ABI 前言从 5 份变 1 份。
|
||||
|
||||
## 5. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `cargo build --release`(含 5 个插件) | 零警告 |
|
||||
| `cargo test --release` | **609 passed / 0 failed** |
|
||||
| 金样实跑(量子) | `p00-ok` / `p11-ok` / `ping-ok` |
|
||||
| 注册项三元组比对 | 5 个插件全部 0 差异 |
|
||||
|
||||
## 6. 边界
|
||||
|
||||
- ABI 版本号、`#[no_mangle]` 符号、结构体布局**一律未变**;旧 `.so` 与新宿主仍可互操作。
|
||||
- 插件私有逻辑(HTTP、矩阵、量子态、agent 工具)一行未动。
|
||||
- 后续新增插件只需依赖 SDK + 一行宏调用。
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `crates/marqdo-plugin-sdk/{Cargo.toml,src/lib.rs}` | **新增**:ABI 类型、静态回调、`host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/take_host_string/init_plugin`、`marqdo_plugin!` 宏 |
|
||||
| `Cargo.toml` | workspace 增加 `crates/marqdo-plugin-sdk` |
|
||||
| `plugins/{agent,quantum,linalg,llm,demo}/Cargo.toml` | 增加 SDK 依赖 |
|
||||
| `plugins/*/src/lib.rs` | 删除本地 ABI 前言与四导出,改用宏;注册表改为数组 |
|
||||
| `doc/design/change-plugin-sdk.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 代码体量审计:53k 行里哪些是特性、哪些是冗余
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **实施记录**(精简依据与进度) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 结论 | 冗余已清 ~14.5k 行;**剩余体量主要是特性面**,不是废弃物 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 当前账目
|
||||
|
||||
| 部分 | 行数 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/` | **52,668** | 其中约 **5,200** 是内联测试(`#[cfg(test)]`) |
|
||||
| `plugins/` + `crates/` | **14,700** | 5 个 ABI 插件(含共享 SDK)+ wasm crate |
|
||||
| 合计 Rust | **67,368** | |
|
||||
|
||||
最大的 10 个文件:
|
||||
|
||||
| 行数 | 文件 | 性质 |
|
||||
|------|------|------|
|
||||
| 4,451 | `src/view/html.rs` | 3,861 行是 CSS/HTML 字符串(页面皮肤) |
|
||||
| 2,691 | `src/parse/mod.rs` | 解析器主体 + 412 行内联测试 |
|
||||
| 2,194 | `src/parse/expr.rs` | 表达式解析 + 465 行内联测试 |
|
||||
| 2,063 | `src/host/foreign_doc.rs` | 外部语言内核(python/node 文档执行) |
|
||||
| 1,648 | `src/host/dispatch.rs` | 202 个宿主函数的元数据表(已合一) |
|
||||
| 1,968 | `src/host/foreign.rs` | 外部进程/会话管理 |
|
||||
| 1,925 | `src/interp.rs` | 树遍历求值器 |
|
||||
| 1,913 | `src/view/render.rs` | 渲染 |
|
||||
| 1,309 | `src/formula/mod.rs` | `$$…$$` 公式求值 |
|
||||
| 1,168 | `src/view/annot.rs` | 注解/映射 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 已清除的冗余(14.5k 行)
|
||||
|
||||
| # | 项 | 行数 | 提交 |
|
||||
|---|----|------|------|
|
||||
| 1 | `plugins/web-rust-archive/`(31 文件,非 workspace 成员、默认不构建、被 Go `libweb` 取代) | **14,235** | `13012ca` |
|
||||
| 2 | `as_text` × 18 份复制(两种措辞)→ 一个 `host::as_text` | ~100 | `8b0ea9e` |
|
||||
| 3 | `catalog.rs` 的 4 个助手(与 `knowledge::util` 逐字相同) | ~70 | `8b0ea9e` |
|
||||
| 4 | `view` 路由 34 臂 → 2 张表(`handle` / `handle_debug`) | 99 | `8b0ea9e` |
|
||||
| 5 | 无调用点死代码 ×5(`parse_italic_assign` 等) | ~50 | `a14a6e2` |
|
||||
| 6 | 转义重复:URL 编码器 2 份、`escape_js_string` 2 份(debug 副本漏 U+2028/2029) | ~40 | `9324032` |
|
||||
| 7 | AST 遍历器 3 份 → `ast::walk_stmts` / `ast::stmt_line` | ~50 | `deac53d` |
|
||||
|
||||
**顺带修出的真实缺陷**(不是行数问题,是正确性问题):
|
||||
|
||||
| 缺陷 | 发现方式 |
|
||||
|------|---------|
|
||||
| `Access` 变体只有隐式判别值(重排即错位) | 新加的一致性测试 |
|
||||
| HOST id 空间稀疏——不是 bug,但此前无测试守护 | 同上(测试先报"不连续",核实后改成"稀疏但可还原") |
|
||||
| `escape_js_string` 的 debug 副本漏转义 U+2028/2029(JS 里是换行符) | 对比两份实现 |
|
||||
| `view` 路由分布在两个 handler,只改一个会让 debug 路由全 405 | 改完实测 HTTP |
|
||||
|
||||
---
|
||||
|
||||
## 3. 剩余体量为什么不是"冗余"
|
||||
|
||||
逐项核过,剩下的都是**功能**,删掉就是砍特性:
|
||||
|
||||
| 区域 | 行数 | 为什么保留 |
|
||||
|------|------|-----------|
|
||||
| `view/` 合计 | ~12,000 | live server + notebook UI:路由、渲染、注解、调试面板、执行报告;审计确认是 feature-gated 的一等 CLI 面 |
|
||||
| `host/foreign*` | ~5,100 | 外部语言内核(python/node 持久会话、快照、中断);qdagent 的沙箱执行依赖 |
|
||||
| `parse/` | ~4,900 | 词法/语法主体 + 内联测试 |
|
||||
| `bytecode/` | 1,921 | 第二后端;72 处测试引用(含双后端一致性) |
|
||||
| `knowledge/` | ~4,000 | catalog / EKC / 指纹;`marqdo catalog` 的输出有 golden 测试 |
|
||||
| `formula/` | 1,741 | `$$…$$` 公式;与 `ast::Expr` 是**不同类型**的两套求值器(不可合并) |
|
||||
| `host/dispatch.rs` | 2,052 | 202 个宿主函数的元数据 + 分派;`call_host` 是 202 个一行臂 |
|
||||
| `view/html.rs` | 4,451 | 其中 3,861 是页面皮肤字符串 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 剩余可精简项(已定位,未做)
|
||||
|
||||
| 项 | 结论 |
|
||||
|----|------|
|
||||
| ~~插件 ABI 前言共享 crate~~ | **已完成**:[change-plugin-sdk.md](change-plugin-sdk.md),净减 674 行,注册项 0 差异 |
|
||||
| ~~HostFn 五表合一~~ | **已完成**:[change-hostfn-table.md](change-hostfn-table.md),−404 行,203 项逐字节一致 |
|
||||
| `view/html.rs` 皮肤"重复声明基础 CSS" | **审计判断不成立**:实测基础样式 312 条规则、notebook 128 条,**选择器零重叠**,无重复可删 |
|
||||
| `debug_page.rs` "复刻 shell" | **判断基本不成立**:只在 head/favicon 上有约 10 行相似;它没有 nav/topbar,是独立极简页 |
|
||||
| 内联测试迁到 `tests/` | 不减总量,只让 `src` 变薄;不做 |
|
||||
|
||||
**结论(修正后)**:可机械消除的重复**已经清完**。剩余体量全是特性实现,
|
||||
要再压只能砍功能(例如 `view` 调试面板、`formula` 引擎),不是"找重复"。
|
||||
|
||||
**判断**:这些加起来约 1.3k 行(总量的 2%),收益边际递减;其中插件 SDK 最值得做(消除 5 份漂移),
|
||||
其余属于"可以但不必"。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与设计的关系
|
||||
|
||||
精简的目的不是数字好看,而是**不让冗余掩盖设计**:
|
||||
|
||||
- 已消除的都是**重复实现**(同一逻辑多份 → 必然漂移)
|
||||
- 保留的都是**单一实现的特性能耐**
|
||||
- 每一条删改都跑全量测试:`605 → 609 passed / 0 failed`,编译零警告
|
||||
|
||||
如果后续还要压体量,正确的方向是**砍特性**(例如 `view` 的调试面板、`formula` 引擎),
|
||||
而不是继续在特性内部找"重复"——那已经找完了。
|
||||
@@ -3,22 +3,24 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 日期 | 2026-09-22;2026-10-23 校正 v2.1 默认链接语义 |
|
||||
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
|
||||
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
|
||||
|
||||
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
|
||||
|
||||
> **版本边界**:构造 ID 是历史守卫标识,不是固定不变的语义说明。`link-index` ID 暂保留以匹配注册表,但默认 `[]()` 已是描述包裹 payload;旧索引语义仅属于显式 Classic 兼容路径。未来步骤/知识投影见[文档原生指导](document-native-development-guide.md),不要把目标能力当作当前已实现。核心数量之外,还要审查上下文例外和作者负担。
|
||||
|
||||
## 1. 行构造
|
||||
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
| `narrative` | 无标记文字 | 叙述(不执行) | 段落内延续到空行;普通叙述不触发执行;未来知识引用投影也不改变此权限边界 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
|
||||
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
|
||||
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [说明](遍历 集合 为 项)`;描述不是绑定变量名 | `tests/structure/loop.mq.md` |
|
||||
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
|
||||
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
|
||||
@@ -30,12 +32,12 @@
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
|
||||
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 粗体内代码判别序:赋值 → 调用 → 表达式;不取消调用行、返回等其它显式执行入口 | `tests/markup-v03/multi-bold.mq.md` |
|
||||
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
|
||||
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
|
||||
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
|
||||
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
|
||||
| `link-index` | `[描述](表达式)` | 描述包裹 payload(历史 ID) | 默认 Occlusion;取元可写 `[说明](access(集合, 键))`,不按描述取键;循环载荷见上 | `tests/occlusion/access-and-loop.mq.md` |
|
||||
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;紧邻 `](` 的默认语义为 payload 遮蔽,不是旧索引 | `tests/structure/bracket-call.mq.md` |
|
||||
| `footnote-index` | `集合[^键]` | 兼容取元 | 保留既有能力;新代码优先 `access(...)`,需要解释时包裹描述,不再推荐旧 `[键](集合)` | `tests/structure/footnote-index.mq.md` |
|
||||
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
|
||||
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
|
||||
|
||||
@@ -80,7 +80,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;嵌套 `import:` 映射与其它 YAML 键一并解析 |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
|
||||
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
|
||||
|
||||
@@ -0,0 +1,284 @@
|
||||
# Marqdo 文档原生开发指导:让知识的表达、执行与复用成为同一件事
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | 下一阶段开发指导与规划修订;不表示下述目标接口已经实现 |
|
||||
| 日期 / 审阅基线 | 2026-10-23 / `main`,`7674ebb`;继承缺口审计的 `434be9f` 代码证据 |
|
||||
| 原始意图 | [009](../next/009.md)、[附属设计](../next/Marqdo_Executable_Knowledge_Design.md)、[附属示例](../next/Marqdo_Executable_Knowledge_Example.md) |
|
||||
| 配套实施文件 | [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)、[缺口与交付路线](../roadmap/executable-knowledge-gaps-2026-10-23.md) |
|
||||
| 本轮边界 | 校正开发方向、作者体验、AI 工作协议和验收;不新增语法,不宣称实现新能力 |
|
||||
|
||||
## 1. 审阅结论与规范关系
|
||||
|
||||
Marqdo 的优势不在于给传统程序换一套 Markdown 符号,而在于:**读者解释知识、作者修改知识、程序执行知识、AI 查找并复用知识,能够指向同一份有结构的文档和其中的同一步。** 标题、叙述、表格、链接描述、输入输出、来源及执行行为不应分散在彼此手工同步的系统中。
|
||||
|
||||
现有规划没有放弃这一目标,但工程排序存在偏移:把身份、图、证据、锁、句柄、晋升全部铺完,再验证人和 AI 是否更容易使用。这样可能交付一个功能齐全的制品管理系统,却让文档作者承担另一套注册、声明、审核和配置工作。需要改变交付方法,不必推翻确定性编译、绑定和权限机制。
|
||||
|
||||
本指导规定**为何开发、作者维护什么、怎样证明值得开发**;详细规范规定语义模型与执行约束;路线图规定当前缺口、切片与完成证据。三者不是三套平行设计。遇到冲突,依次采用:`009` 的产品意图 → 本指导对作者负担、场景分级和交付次序的修订 → 详细规范的工程规则 → 附属概念示例。当前代码与测试证明“已实现什么”,不能把代码局限升级为永久语言禁令;原始讨论保留,不据其重新引入已被否决的方案。
|
||||
|
||||
### 1.1 方向修订清单
|
||||
|
||||
| 容易偏移的做法 | 修订后的要求 | 必须保留的技术约束 |
|
||||
|---|---|---|
|
||||
| 先做完整知识治理平台,再给作者使用 | 从一篇可读、可运行、可定位步骤的文档交付,逐层扩展 | 每个已支持路径都有准确的目标和效应边界 |
|
||||
| 为进入知识库再写 YAML、注册表和索引 | 从源码推导;只有不能推导的领域事实才需作者补充 | 生成物有版本,可重建,可检查来源 |
|
||||
| 所有逻辑先封装成可登记函数/类 | 一次性逻辑直接写;需要命名、解释或复用时逐步提取 | 作用域、形参、返回与副作用明确 |
|
||||
| 所有调用先审核、锁定、签发远程凭据 | 本地探索、项目复用、严格业务、远程执行分级 | 精确目标、运行时权限不能被标签或模型绕过 |
|
||||
| AI 只能搜文档、填工具参数 | AI 可以读步骤、组合、选择候选、局部修改、提取和验证 | 模型的选择必须转成显式目标,由编译器校验 |
|
||||
| 为“独特”拒绝普通调用或新增更多标记 | 保留简单 payload;让 Markdown 结构提供程序之外的信息 | 无第二套表达式文法,无裸词隐式执行 |
|
||||
| 核心构造数量不增长就是简单 | 同时检查上下文例外、记忆负担和诊断成本 | 新构造需 ADR;不靠把新规则藏进旧构造绕过审查 |
|
||||
|
||||
### 1.2 四个不能互相替代的完成条件
|
||||
|
||||
1. **读得懂**:不打开生成图,也能从源文件看出目的、关键步骤、参数角色和限制。
|
||||
2. **执行同一件事**:标签表达意图,payload 决定计算;运行 trace 能回到源码步骤,不能执行另一个同名目标。
|
||||
3. **改得动**:人或 AI 能修改一个明确步骤,看到影响与验证结果,不必重写整份文档或同步多份签名。
|
||||
4. **复用得对**:找到已有能力后实际调用它;不满足条件时给出具体拒绝原因,而非用复制源码掩盖失败。
|
||||
|
||||
“更适合 AI”是待验证的产品假设,不是 Markdown 文件后缀自动赋予的性质。正确性和作者成本优先于 token 下降;错误复用更便宜不算优化。
|
||||
|
||||
## 2. 语法审查的保留、修正与暂缓
|
||||
|
||||
以下裁决针对审查结论的适用范围,不重写历史实验记录。旧文档中的原型、性能数值和当时的 `Value`/AST 限制,不能直接当作 v2.1 的规范或测试结果。
|
||||
|
||||
| 审查材料 | 保留的洞见 | 需要修正的外推 / 本轮处置 |
|
||||
|---|---|---|
|
||||
| [函数即命名](function-as-naming-philosophy.md) | 从正文计算出发,命名应降低理解和复用成本;避免无意义包装 | “具名给值缺失”是历史观察,当前有具名参数;替换模型是教学解释,不意味着禁止递归、前向引用或必须文本展开 |
|
||||
| [方括号作为标签](bracket-as-label-evaluation.md) | 描述与 payload 共址;标签帮助解释、检索和拆步骤 | Classic 冲突是迁移历史,不据此恢复默认 `[键](集合)`;不强制每个常量或子表达式都有标签 |
|
||||
| [圆括号与可读调用](paren-call-and-readable-invocation.md) | 调用标记应明确;保留 `f(args)` 的局部可读性 | 原型撤回不代表现有版本缺少该能力;Marqdo 的独特性不依赖消灭熟悉的表达式形式 |
|
||||
| [从标记推导调用](call-syntax-from-marks.md) | 语义成分有明确标记;自然语言是连接与解释,不参与猜测调用 | 持久跨文档接口优先具名实参;短而稳定的位置参数仍合法。推断参数的声明次序变化属于接口变化,不承诺任意润色都无影响 |
|
||||
| [环境参数](ambient-parameters-evaluation.md) | 参数来源应可见,避免调用者隐式环境影响复用 | 文档顶部已否决 L0 裸“执行”触发,正文旧建议不能重新生效;文件级常量也须有明确绑定与依赖,不变成动态作用域 |
|
||||
| [函数作为值](functions-as-values-evaluation.md) | 区分名称数据、一等函数、有限查表;避免无需求增加核心复杂度 | “匿名函数必不能索引”“动态调用必然破坏契约”不是普遍定理。将来可研究稳定节点身份与运行时契约;本轮不引入闭包,也不永久禁止 |
|
||||
| [函数作为表格](function-as-table-semantics.md) | 数据表几何有既定含义;契约表不可另造一份参数声明 | 不把表格全部变成函数,也不把“现有实现不支持”写成“表格不能计算”;有限决策表先评估库方案,只有明确角色和歧义测试后才讨论语言扩展 |
|
||||
| [核心表面](core-surface.md)、[分层](layers.md) | 核心小、标记可解释、构造有测试与准入流程 | 清单中的旧取元/循环说明需随迁移更新;固定数量不等于低认知成本,守卫通过也不证明文档语义正确 |
|
||||
| [链接设计](link-syntax.md)、[告警疲劳](warning-fatigue-control.md) | 单一 payload 文法;标签漂移可提示;默认安静、按需严格 | 标签不是纯粹可丢弃的注释,也不是事实证明;不做每次运行重复的批准仪式,不靠词汇相似度证明描述与代码一致 |
|
||||
|
||||
### 2.1 继续冻结的语法边界
|
||||
|
||||
- 默认 `[]()` 是描述包裹 payload;旧取元只能在显式历史兼容路径下解释。现行取元用 `access(...)` 等已支持形式;循环使用明确遍历载荷。
|
||||
- `[]()` 不等于“仅函数调用”:计算、取元、调用、遍历、叙述引用都需要各自语义角色,不能只收集 call 边就宣称完成知识步骤。
|
||||
- 正文引用与可执行位置有不同调度权限。普通句子不因出现“执行”“发送”或工具名而运行;正文解析成引用也不自动求值。
|
||||
- 不把所有 `#` 解释成某种知识对象,或把继承悄悄变成实例关系。标题的既有语义必须兼容,IR 可区分 Type、Entity、Fact、Function。
|
||||
- 不给同一参数增加正文声明、签名表、工具 schema 三套作者真相。规范签名和工具 schema 是投影;契约表补充类型、约束和说明,不偷偷增加形参。
|
||||
- 可读源文件是硬要求;普通 Markdown 渲染器是否把含空格/嵌套表达式的链接渲染成可点击链接是另一件事。不能承诺全部标准渲染器理解执行语义。
|
||||
|
||||
### 2.2 哪些编辑不能当成“只是改文案”
|
||||
|
||||
不含语义标记的普通叙述润色,应保持执行结果和实现摘要;标签改名应保留 payload 行为,但更新展示/检索内容。反引号声明、首次出现顺序、标题名称/层级、粗斜体、表格几何、契约、来源和适用范围的改变则可能影响程序或知识可信性。编辑器必须展示真实差异,不能统一标为 prose-only。
|
||||
|
||||
标签漂移诊断应说明“描述或实现可能需要复核”,不能自动替作者改写业务意图。自然语言一致性检查可作辅助建议,确定性检查仍需可定位的符号、类型、契约或测试证据。
|
||||
|
||||
## 3. 作者工作流:先写清楚,再获得复用能力
|
||||
|
||||
### 3.1 一次性计算不需要预先建知识模型
|
||||
|
||||
下面是当前默认语法的完整最小程序。无模式开关、无项目注册、无知识 ID、无锁文件。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这是演示订单,单价与数量直接写在计算处。
|
||||
|
||||
**小计 = [两件商品的小计](2 * 30)**
|
||||
> print text=`小计`
|
||||
```
|
||||
|
||||
可读意图和精确计算共址。这个标签值得保留,因为它说明本次计算的业务角色;不要求把 `2`、`30`、乘法分别命名。
|
||||
|
||||
### 3.2 需要解释或复用时才提取命名能力
|
||||
|
||||
```markdown
|
||||
## 商品小计
|
||||
|
||||
根据购买数量`数量`和商品单价`单价`计算小计。
|
||||
|
||||
*[按数量与单价计算](数量 * 单价)*
|
||||
|
||||
# main
|
||||
|
||||
计算同一笔演示订单。
|
||||
|
||||
**小计 = [两件商品的小计](商品小计(数量=2, 单价=30))**
|
||||
> print text=`小计`
|
||||
```
|
||||
|
||||
两个完整程序在本轮本地现有 `target/debug/marqdo` 上分别以 Tree 和 Bytecode 执行,均输出 `60`。这仅验证基础语法,不证明步骤身份、重构工具或 Agent 闭环已经实现;也不是全仓测试报告。可将各块保存为 `.mq.md` 后用 `marqdo run 文件 --backend tree` / `--backend bytecode` 复核。
|
||||
|
||||
**后续工具目标**:从选中表达式提取为标题单元,推导自由变量为参数、保持求值顺序与 effect 次数、生成具名调用,并给出可审阅补丁。反向内联也应保留契约和来源关联;无法证明安全的捕获变量、递归、控制流、动态目标或有副作用表达式,先拒绝自动变换并说明原因,不伪称等价。
|
||||
|
||||
### 3.3 跨文档复用与事实说明分别增长
|
||||
|
||||
当第二篇文档需要这段计算,才提取模块并显式 import;不要为十行单文件强制创建 `corpus/knowledge/apps` 目录树。项目索引按约定发现,明确边界或外部来源时再加入配置。
|
||||
|
||||
当“商品小计”依赖政策、时间、币种等条件,再就地补契约与来源。简单乘法不要求假造现实来源;“某商店当前折扣为九折”则不能仅凭函数返回 `0.9` 声称真实。
|
||||
|
||||
正文可以说明结果为何成立,目标是引用同一能力和同一次受控执行的结果,而非手抄另一份公式。正文引用 AST、结果投影和绑定身份尚需开发;完整业务链使用[目标示例](../next/Marqdo_Executable_Knowledge_Example.md)验收,不把它冒充当前全部可运行的教程。
|
||||
|
||||
### 3.4 维护时看到知识变化,而不只是文件变化
|
||||
|
||||
目标维护流程:修改上游规则 → 显示受影响的计算、正文陈述和消费者 → 执行相关测试 → 展示结果/证据/接口各自变化 → 按使用策略接受更新。普通显示文案变更不应触发全库业务审批;证据过期也不必使无关纯工具全部失效。
|
||||
|
||||
## 4. 人维护语义,编译器维护机械关联
|
||||
|
||||
| 信息 | 作者责任 | 编译器 / 工具责任 |
|
||||
|---|---|---|
|
||||
| 目的与步骤 | 有帮助的标题、叙述、标签;避免空泛重复 | 保留源位置和层级,生成步骤投影,不要求手工节点注册 |
|
||||
| 输入输出 | 一份参数来源和必要契约;领域单位不能靠猜 | 推断规范签名、检查调用、生成 schema 和签名视图 |
|
||||
| 目标与依赖 | 显式 import、可读名称、必要消歧 | 绑定唯一 SymbolId,生成依赖边与闭包;不要求手写 ID |
|
||||
| 效应 | 扩展作者声明宿主能力;业务作者必要时收窄允许范围 | 汇总直接及传递效应;未知不得推断 pure;运行时执行能力上限 |
|
||||
| 事实与来源 | 原始资料、范围、有效期、人工审阅等不可推导信息 | 关联来源、记录验证事件、传播失效;不将文件路径视为事实证明 |
|
||||
| 身份与版本 | 有意移动/更名时确认必要迁移 | 区分身份与内容摘要;报告歧义,不靠猜测维持假稳定 |
|
||||
| view / AI 索引 | 不维护第二份可执行描述 | 同一语义模型投影;显示生成代、验证政策和缺失字段 |
|
||||
|
||||
生成信息不等于免费:首次编译、缓存修复、错误定位都要可理解。失败时应回到源文档中可修改的位置,而不是只报内部 Artifact 字段名。
|
||||
|
||||
稳定身份要诚实:同一次编译内引用和 trace 必须一致;普通文本编辑不应打乱无关节点;复制相似步骤、跨文件移动等无法唯一识别时,要求确认迁移或明确生成新身份。禁止用文本相似度悄悄继承已审核的知识身份。
|
||||
|
||||
## 5. AI 原生工作协议:读步骤、改步骤、验证步骤
|
||||
|
||||
本节是**待实现的协议约束**,不是新增 CLI 命令清单。优先扩展现有 MLSP、view、EKC 和 Agent 工作簿,不另造一套 Agent 框架或知识库。
|
||||
|
||||
### 5.1 发现后的最小上下文包
|
||||
|
||||
一次检索返回可展开的上下文卡,而非强制倾倒整个文件或只给函数 schema:
|
||||
|
||||
1. 标题路径、任务相关叙述、标签和精确源码片段;
|
||||
2. SymbolId/步骤节点、source span、源码摘要、生成代;
|
||||
3. 输入角色、返回、单位、默认值和适用条件;
|
||||
4. 直接依赖、效应、必要来源及分层验证状态;
|
||||
5. 支持该能力的例子/测试,相关失败经验、禁用条件和替代能力;
|
||||
6. 还缺哪些检查、能否在当前 policy 下运行、为何被拒绝。
|
||||
|
||||
来源不可用、字段未推导、上下文被截断都须显式标识。按预算可展开依赖,但不能悄悄省略改变适用性或权限的重要信息。原始资料及标签是内容,不是可以覆盖 Agent 策略的指令。
|
||||
|
||||
### 5.2 复用、适配、新建的分界
|
||||
|
||||
- **REUSE**:AI 可根据任务选候选,提交精确目标与输入;resolver 确认目标、契约、适用性、版本和 effect,执行既有制品。复用不靠“没有生成文件”推断,必须有实际调用 trace。
|
||||
- **ADAPT**:已有能力接近但不适用;说明差异,保留依赖/来源关联,在局部副本或补丁中改变必要部分,再验证。不为了通过测试改写原始来源或放宽全局策略。
|
||||
- **CREATE**:没有合适候选或明确需要新语义;记录检索范围和失败原因,在任务预算及写权限允许时新建。不能把检索服务故障当作“仓库没有能力”。
|
||||
- **ASK / STOP**:缺业务决策、权限或关键证据时报告具体缺口。编译器无法决定的真实意图不交给近似匹配默默补全。
|
||||
|
||||
AI 并非只能发现和解释。它可以提出精确目标、组合已有能力、改进表达、重构及补测试;不能以自然语言自报正确来替代执行验证,也不能把含糊名称传给后端任意选一个目标。
|
||||
|
||||
### 5.3 局部修改的事务边界
|
||||
|
||||
编辑请求至少携带目标文件/节点、期望源码摘要、补丁范围和预期行为变化。应用前检查摘要,源已变化则重新定位和审阅,不覆盖用户改动。应用后重新解析受影响文档,生成语义 diff:参数/返回、目标、effect、控制流、证据与依赖是否改变。
|
||||
|
||||
对“只改措辞”请求,检测到接口或实现改变时停止自动合并;对“改计算”请求,运行相关正负例并展示影响。原始文本、格式与未知 metadata 尽量保留,不通过整篇重生成来完成一行修改。禁止修改生成图伪装修复源码。
|
||||
|
||||
首个试点只支持可确定定位的纯计算步骤与普通函数,不等待通用 AST 编辑器、跨项目事务或完整知识治理。安全拒绝超范围输入也属于验收。
|
||||
|
||||
### 5.4 解释和负知识必须有落点
|
||||
|
||||
解释结果应关联到“哪一步、用了哪个目标、哪些输入、哪份来源、哪次验证”,区分已执行观察和模型推断。运行 trace 可以证明程序路径,不能证明任意自然语言论证正确。
|
||||
|
||||
失败经验需要保存适用范围、触发条件、关联能力、原因与失效时间/版本。例如“此折扣不适用于退款”应在查询定价能力时可见,而不是埋在另一份聊天记录里。先由普通文档与结构化关联承载,不先新增通用推理语言;过期负知识也要撤销,不能永久拦截修复后的能力。
|
||||
|
||||
## 6. 渐进严格:不把治理门槛塞进每一行正文
|
||||
|
||||
下面是目标政策分级,不是当前已有四种 CLI 模式。政策由项目/宿主配置和调用上下文选定,源文档保持同一种语法。
|
||||
|
||||
| 场景 | 必需条件 | 默认不要求 |
|
||||
|---|---|---|
|
||||
| 本地探索、单文件运行 | 明确语法与目标、已有运行时契约、宿主能力限制;如实显示未知状态 | lock、来源、ready 晋升、远程签名句柄 |
|
||||
| 项目内自动复用 | 精确绑定、输入/适用性检查、效应许可、状态满足所选政策、执行 trace | 所有纯工具都有人审证据、每次独立确认 |
|
||||
| 严格业务/可复现任务 | 相关依赖与证据锁定、必要验证新鲜度、受控环境和审计;明确不可重放部分 | 对无关文案变化重审整个项目 |
|
||||
| 远程/多租户/不受信调用方 | 上述相关约束,加可信授权主体、范围、服务端能力上限、撤销/期限与防伪设计 | 把客户端提交的 `allow_effects` 当授权本身 |
|
||||
|
||||
`ready` 是“对某项 policy 和输入/上下文已具备复用条件”,不是永久万能认证。未验证的本地草稿可以被检索、查看和按明确权限试跑;不能冒充满足严格政策的可复用事实。测试通过与事实证实分别报告。
|
||||
|
||||
正文 `check/view static` 不执行外部效应。用户主动打开的纯预览可复用项目或会话已有政策,不要求每个链接弹窗;effectful 运行始终受宿主能力和明确执行上下文控制。锁和摘要是完整性机制,不自动等于远程授权;可信本地引用无需先搭建凭据服务。
|
||||
|
||||
## 7. 交付切片:每片都有文档作者与 AI 能看见的结果
|
||||
|
||||
编号与[缺口路线图 §7](../roadmap/executable-knowledge-gaps-2026-10-23.md#7-依赖顺序与可合并切片)一致;G 编号沿用现状证据,M0–M6 保留为工程能力映射,不再被理解为必须全部串行完成的墙。
|
||||
|
||||
### S0 作者基线与最小语料
|
||||
|
||||
- 选定单文件计算、提取函数、两文档引用、表格取元/遍历、业务政策及拒绝复用六类任务;记录当前写法、输出、诊断和作者重复维护项。
|
||||
- 优先整理 `doc/README`、核心语法卡片、教程与运行示例的版本状态;不要先扩展通用库数量。
|
||||
- 为最小样例建立无网络门禁。100 单元及更大语料逐步增长,不阻塞首个可读文档切片。
|
||||
- 完成证据:别人按当前入口能写出正确默认语法;已实现与预期失败分开报告,不能把待实现测试跳过计为成功。
|
||||
|
||||
### S1 可读步骤与唯一目标
|
||||
|
||||
- 主要落点:`src/parse/`、`src/ast.rs`、`src/sema/`、`src/knowledge/compile.rs`、`src/view/`。
|
||||
- 在最小故事内联合完成 G01/G03:保留 label、payload、上下文和跨度;每类步骤有输入输出与依赖投影;旧 EKC 查询索引不再覆盖语义图。
|
||||
- 普通导航、正文引用、可执行表达式、循环分别处理,正文保持惰性。先确保支持范围内同一引用在源码、view、图中是同一个目标,再扩展覆盖范围。
|
||||
- 完成证据:作者能从渲染步骤返回对应源码;同名目标不误连;计算/取元/循环不是伪造的 call;重复构建可对照;未支持上下文明示。
|
||||
|
||||
### S2 确定执行与早期 AI 复用试点
|
||||
|
||||
- 主要落点:`src/sema/`、`src/interp.rs`、`src/bytecode/`、`src/mlsp.rs` 与现有 Agent 入口。
|
||||
- 完成静态普通函数、显式 import、关联函数的 BoundCall 主链;G02 与 G06 的效应安全下限不可延期。小范围可先用明确纯操作白名单,未知路径必须拒绝纯证明,而非猜 pure。
|
||||
- 实现最小上下文卡与本地绑定引用;以 stub/no-LLM 测试验证协议,然后用现有 Agent 跑相同故事。无需先完成远程鉴权平台或全面来源审核。
|
||||
- 完成证据:同一需求实际调用既有函数,不新增同义实现;两个后端 trace 对上图中目标;改目标、错误输入、未知效应、权限不足不能静默执行。
|
||||
|
||||
### S3 局部编辑、提取与库可读性
|
||||
|
||||
- 主要落点:MLSP 编辑/定位、相关 sema/检查入口、`lib/`、`ext/`、教程与测试。
|
||||
- 按 §5.3 实现受摘要保护的局部修改和语义 diff;实现受限纯表达式提取,或明确标为待实现,不用人工演示冒充工具能力。
|
||||
- 迁移标准库/扩展时删掉重复包装与噪音标签,保留有意义的业务步骤、契约和负例;中英镜像含义一致。兼容旧调用接口,不用增加旧语法解释救迁移遗漏。
|
||||
- 完成证据:同义润色不改执行;改反引号声明能检测签名变化;表达式提取前后结果/effect 次数一致;冲突补丁拒绝;CLI、库、扩展与 view 既有能力继续通过。
|
||||
|
||||
### S4 业务知识的来源与适用性
|
||||
|
||||
- 主要落点:契约、SourceRef/VerificationRecord、验证事件、Agent 候选解释;完成 G05 与 G07 的项目政策部分。
|
||||
- 选定书店案例的币种、数量边界、会员范围与政策有效期;给 schema、拒绝诊断及可运行负例,不泛化为全能业务规则语言。
|
||||
- 同步补齐传递效应与相关负知识;生成契约/状态展示,减少作者重复填写。
|
||||
- 完成证据:同一计算因输入或证据不同而正确通过/拒绝;来源过期不被 `tests=passed` 覆盖;普通纯工具无需虚构 SourceRef。
|
||||
|
||||
### S5 变化传播与严格复用
|
||||
|
||||
- 主要落点:`src/sema/lock.rs`、图/impact、产物提交与消费者;完成 G04/G08 和严格 handle 复核。
|
||||
- 区分身份/接口/实现/证据/闭包,给出可读升级 diff;整代快照保证消费者不会读取混代数据。并发读写一旦开放,该一致性就是前置条件,不能等到此片才承认风险。
|
||||
- 完成证据:修改依赖政策后,下游计算和正文解释进入影响集合;文案变化不误判实现变化;并发编辑或构建崩溃不导致错目标执行;锁不声称重放网络/随机/LLM。
|
||||
|
||||
### S6 生态验收与发布
|
||||
|
||||
- G10/G11 从 S0 起每片执行;S6 汇总兼容矩阵、真实工作流和打包后冒烟,不把测试留到最后。
|
||||
- G12 随实际规模需求推进;远程凭据/多租户是有条件的独立交付。它们不阻塞受信本地试点,也不得被本地通过的测试覆盖为“已安全支持”。
|
||||
- 完成证据:当前默认语法的 lib/ext/CLI/MLSP/view/WASM 等受影响消费者有明确结果;目标示例中的已发布子集实际可运行,未发布部分保留状态;发布声明与证据一一对应。
|
||||
|
||||
## 8. 验证 Marqdo 优势,而不只验证组件存在
|
||||
|
||||
### 8.1 必须收集的产品指标
|
||||
|
||||
| 维度 | 记录方法 | 失败信号 |
|
||||
|---|---|---|
|
||||
| 作者负担 | 完成同一任务所需手写声明、重复字段、配置、跳转和确认次数 | 简单本地算式也必须填写制品清单 |
|
||||
| 阅读与定位 | 给定问题,定位正确步骤/限制的准确率、耗时与上下文量 | 只看 label 会误导,必须打开生成 JSON 才理解源文档 |
|
||||
| 可修改性 | 修改范围、无关 diff、语义变化检测率、冲突覆盖数 | 为改一步而重生成全文件;措辞调整偷偷改变接口 |
|
||||
| 复用质量 | 已有能力发现率、实际调用率、重复实现率、误用率 | 检索命中却重新写代码;正确拒绝算成任务失败而被优化掉 |
|
||||
| 知识可追溯性 | 结果关联目标、步骤、输入、来源和验证的覆盖率 | `tested` 被当作事实正确;解释引用未执行的步骤 |
|
||||
| 总成本 | 正确完成任务的 token、工具调用、轮次、总耗时及编译成本 | 只报模型 tokens,隐藏额外注册/审核/修复成本 |
|
||||
|
||||
### 8.2 对照实验与门槛
|
||||
|
||||
1. 固定任务、可访问能力、输入数据、模型版本、工具能力、预算与超时;比较普通 Markdown+代码/RAG、当前 EKC 和新方案。不能给新方案更多现成实现再声称语法更优。
|
||||
2. 任务包括成功复用、同名冲突、近似但不适用、未知 effect、过期来源、正文不执行、局部修改及库升级。加入自然语言诱导绕过 policy 的负例。
|
||||
3. 先测确定性协议,再测多次 AI 运行,保留种子(支持时)、原始 trace、版本、失败样本与分布;小样本不夸大收益。
|
||||
4. 正确目标、无越权和正文无外部 effect 是硬门槛。原有兼容测试不得降低;效率阈值先测基线再登记,不捏造提升百分比。
|
||||
5. 若作者负担增加或误用率上升,回到交互/语义设计分析原因,不能只用“更多治理更安全”或“模型更便宜”解释过去。
|
||||
|
||||
### 8.3 发布声明分层
|
||||
|
||||
- “支持新语法”需语法、迁移、双后端与库兼容证据,不意味着完整知识复用已经交付。
|
||||
- “本地确定性知识复用”需 S1/S2 支持范围内的端到端与拒绝用例;范围外路径显式不支持,不能回落为模糊执行。
|
||||
- “严格业务知识复用”还需相关 S4/S5 来源、适用性、失效、锁和一致性证据。
|
||||
- “安全远程知识执行”需额外的授权、能力上限、凭据/撤销及隔离测试;本地 JSON handle 不等于远程安全。
|
||||
|
||||
## 9. 每个开发变更必须回答的问题
|
||||
|
||||
提交设计或实现时给出一份短而具体的审阅记录:
|
||||
|
||||
- 用户要读/写/改/复用的知识是什么?附源文档前后对照,不只给内部结构图。
|
||||
- 利用了哪种文档原生信息?若只增加通用框架能力,与主线的必要关系是什么?
|
||||
- 新增了哪些作者必须手工维护的信息?为什么不能从现有语义推导?
|
||||
- 是否改变标记、作用域、求值顺序、形参顺序、表格几何或正文安全?分别有哪些测试?
|
||||
- 人、CLI、view、图和 Agent 是否看到同一目标与状态?失败能否回到源码修复?
|
||||
- AI 的正确复用/局部编辑如何证明?哪些部分仍需模型判断,哪些由编译器决定?
|
||||
- 标准库和扩展是否先迁移?是否保住既有公开接口、输出与 effect?
|
||||
- 这是已实现、受限试点还是设计目标?文档和发布声明是否一致?
|
||||
|
||||
**准入原则**:内部可以使用成熟编译器、数据库和协议技术;外部必须减少知识在“说明、程序、索引、工具描述”之间的重复翻译。独特性由这条链的实际收益体现,不由新符号数量或与其他语言不同的程度体现。
|
||||
@@ -0,0 +1,100 @@
|
||||
# Engineering Knowledge Compiler(EKC)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted(v1 已落地)** |
|
||||
| 日期 | 2026-09-28 |
|
||||
| 提案 | [next/008.md](../next/008.md) |
|
||||
| 相关 | [okf.md](okf.md) · [catalog-cli.md](catalog-cli.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
## 1. 定位
|
||||
|
||||
Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识系统。Source of Truth 仍是 `*.mq.md`;`.marqdo/**` 是 GENERATED 投影。
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► Executable + Catalog L0–L4 + Graph + Context Pack
|
||||
│
|
||||
▼
|
||||
Agent preflight (REUSE → ADAPT → CREATE)
|
||||
```
|
||||
|
||||
**Engineering First Information (EFI)**:生成代码前先获得已有能力、约束、决策、失败经验与推荐复用。
|
||||
|
||||
## 2. 五层 Catalog
|
||||
|
||||
| 层 | 内容 | 落盘 |
|
||||
|----|------|------|
|
||||
| L0 Repository | 语言/规模 | `.marqdo/catalog/repository.mq.md` |
|
||||
| L1 Module | imports/exports/responsibility | `.marqdo/catalog/modules/` |
|
||||
| L2 Symbol | signature/calls/fingerprint | `.marqdo/catalog/symbols/` |
|
||||
| L3 Capability | 工程能做什么 | `.marqdo/catalog/capabilities/` |
|
||||
| L4 Knowledge | Decision/Constraint/Failure/… | `.marqdo/knowledge/{decisions,constraints,…}/` |
|
||||
|
||||
既有 `marqdo catalog` 根级 `catalog.yaml` / `index.md` / `modules/` / `concepts/` **保留**;`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。
|
||||
|
||||
## 3. 知识类型(OKF `type`)
|
||||
|
||||
| type | 含义 |
|
||||
|------|------|
|
||||
| `Capability` / `Function` | 能力与符号投影 |
|
||||
| `Decision` | 为什么这样做 |
|
||||
| `Constraint` | 必须/禁止 |
|
||||
| `Failure` / `AntiPattern` | 负面知识 |
|
||||
| `Pattern` / `Migration` / `Fact` | 模式、迁移、事实 |
|
||||
| `Marqdo Context Pack` | Agent 上下文制品 |
|
||||
| `Marqdo Policy` | 复用决议编译结果 |
|
||||
| `Marqdo Engineering Knowledge` | 总览 / `engineering.yaml` |
|
||||
|
||||
未知 type 优雅降级(可读,不专属逻辑)。
|
||||
|
||||
## 4. 图边
|
||||
|
||||
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
|
||||
|
||||
落盘(G01 分离后):
|
||||
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
|
||||
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json` · **`ir.json`**(完整 IR 快照,供查询热路径)
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认;写投影 + ir.json)
|
||||
marqdo knowledge preflight "task" # 暖机读 ir.json;缺图才 compile
|
||||
marqdo knowledge preflight "task" --refresh # 强制全量重编译后再预检
|
||||
marqdo knowledge record REUSE
|
||||
marqdo knowledge learn --task ... --failure ...
|
||||
marqdo find "authentication" # 同上:缺图才 compile;--refresh 强制
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo impact path/to/file.mq.md
|
||||
marqdo conflicts | stale | duplicate [--fail] | verify
|
||||
```
|
||||
|
||||
统一 `--json`。查询类命令(`preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`)默认 **读已编译投影**;CI 或源变更后应先 `marqdo knowledge` 或加 `--refresh`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
|
||||
## 6. Reuse 协议
|
||||
|
||||
三态:**REUSE → ADAPT → CREATE**(硬顺序)。Reuse budget:`min_candidates` / `allow_create_after`。仅 `create_allowed: true` 时允许盲生成。
|
||||
|
||||
## 7. Context Pack
|
||||
|
||||
`.marqdo/agent/contexts/task-<id>.mq.md`:Task / Existing Capabilities / APIs / Constraints / Decisions / Failures / Recommended / Forbidden。
|
||||
|
||||
## 8. Agent
|
||||
|
||||
- Plugin:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`
|
||||
- Facade:`agent.preflight` · `agent.eng_reuse` · `agent.eng_record`
|
||||
- `agent.plan … eng_preflight=True` 在 agent-kb 之前跑 EFI;缺知识图时 `missing_knowledge` 放行(兼容纯 agent-kb 测试)
|
||||
|
||||
## 9. 指标
|
||||
|
||||
`.marqdo/agent/episodes/reuse_metrics.json`:`reuse_ratio` / `adapt_ratio` / `novel_ratio` / `duplication_rate`。
|
||||
|
||||
## 10. 原则(五条)
|
||||
|
||||
1. Discover before Create
|
||||
2. Reuse before Adapt
|
||||
3. Adapt before Duplicate
|
||||
4. Verify before Promote
|
||||
5. Code changes update knowledge
|
||||
|
||||
**不做**:以向量库为知识模型;embedding 仅可选检索实现,默认关闭。Hybrid = lexical + symbol + capability + graph。
|
||||
@@ -0,0 +1,206 @@
|
||||
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Design Draft · v2.1 语义重构** |
|
||||
| 核心判断 | `[]()` 不是“普通代码”与“知识链接”的分界;每一个 `[]()` 同时是代码、文档和知识图节点。 |
|
||||
| 关联 | [link-syntax.md](link-syntax.md) · [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) |
|
||||
| 示例 | [examples/executable-knowledge/](../../examples/executable-knowledge/) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
> **`[名称](载荷)` 是一个命名的可执行知识步骤:`()` 做原有的任何事,`[]` 说明这一步对人意味着什么;编译器把它们一起编入知识图。**
|
||||
|
||||
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、
|
||||
甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、
|
||||
源位置、输入/输出、依赖和影响范围。
|
||||
|
||||
```text
|
||||
代码投影: eval([名称](载荷)) = eval(载荷)
|
||||
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
|
||||
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
|
||||
```
|
||||
|
||||
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性;
|
||||
三者同源,才是代码即文档、文档即知识、知识即可执行。
|
||||
|
||||
---
|
||||
|
||||
## 1. 统一节点:`Named<T>`
|
||||
|
||||
`[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
|
||||
|
||||
```text
|
||||
Named<T> { label, inner: T, span }
|
||||
```
|
||||
|
||||
`T` 是它出现位置原有的语法节点,绝不另造“知识表达式” parser:
|
||||
|
||||
| 既有位置 | `T` | 示例 | 知识角色 |
|
||||
|---|---|---|---|
|
||||
| 表达式 | `Expr` | `[收件人](at(订单, "收件人"))` | 观测/取值 |
|
||||
| 表达式 | `Expr` | `[含税价](金额 * (1 + 税率))` | 推导 |
|
||||
| 表达式 | `Expr` | `[适用税率](税率.查询(地区, 品类))` | 复用/查询 |
|
||||
| 遍历位置 | `LoopSpec` | `[逐个订单行](遍历 订单.行 为 行)` | 过程/展开 |
|
||||
| 正文位置 | `InlinePayload` | `订单总额为[含税总价](定价.总额(订单))。` | 叙述中的可执行槽 |
|
||||
| URL/路径 | `NavigationLink` | `[税率原文](corpus/tax.md)` | 导航/证据定位 |
|
||||
|
||||
运行时只执行 `inner`;`label` 不进符号表、不改变作用域、不重复计算。与此同时,
|
||||
parse/check/catalog 保留整个 `Named<T>`。所以循环不会被误判成“返回一个事实”,取元也不会
|
||||
被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。
|
||||
|
||||
### 1.1 每个节点都有角色,而不是两套语法
|
||||
|
||||
角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束:
|
||||
|
||||
| role | 如何识别 | `check` 应问什么 |
|
||||
|---|---|---|
|
||||
| `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 |
|
||||
| `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 |
|
||||
| `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 |
|
||||
| `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 |
|
||||
| `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 |
|
||||
| `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 |
|
||||
|
||||
一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖
|
||||
若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。
|
||||
|
||||
---
|
||||
|
||||
## 2. 知识层不是目录隔离,而是同一图的不同投影
|
||||
|
||||
“几层知识”不应把语法和项目切断。它们是同一个 `Named<T>` 图中不同职责的节点;
|
||||
同一份 `.mq.md` 可以同时有多层节点。
|
||||
|
||||
| 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 |
|
||||
|---|---|---|---|
|
||||
| **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? |
|
||||
| **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? |
|
||||
| **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named<Expr>` | 哪个可调用单元给出什么知识? |
|
||||
| **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named<Expr>` / `Named<LoopSpec>` | 如何从已有知识得到新结论/行动? |
|
||||
| **N 叙述知识** | 段落与正文调用槽 | 正文 `Named<InlinePayload>` | 如何把结论说给人或 agent? |
|
||||
|
||||
同一条边可以跨层:`[出生年份](at(人物表, "出生年份"))` 同时是 E 的观测、K 的事实值和
|
||||
可被 N 层引用的节点。`[逐个订单行](遍历...)` 是 D 的过程知识,也为其内部每个推导提供上下文。
|
||||
这正是通用语法本身兼容知识体系的含义。
|
||||
|
||||
### 2.1 `#` / `##` 的位置
|
||||
|
||||
- `#` 给一组知识步骤提供可读命名空间、类型/个体语义和文档边界;
|
||||
- `##` 给可复用步骤提供稳定的公开入口、参数与返回契约;
|
||||
- `[]()` 给入口内部的**每一小步**命名,并将它们暴露给文档、图和工具;
|
||||
- `> 类型` 仍只构造运行时实例;知识个体不等于运行时 map。
|
||||
|
||||
因此 `## 含税总额` 不是黑盒函数:其函数体中的 `[订单行](...)`、`[逐行计税](遍历...)`、
|
||||
`[汇总](sum(...))` 都是可检索、可解释、可追踪的知识步骤。函数是知识单元的边界,
|
||||
`[]()` 是知识单元的内部结构。
|
||||
|
||||
---
|
||||
|
||||
## 3. 大项目的寻址:可读短名与稳定身份同时成立
|
||||
|
||||
全局只靠 `# 李白` 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
|
||||
但这不意味着作者要失去 `李白.出生年份` 的自然语言体验。
|
||||
|
||||
1. 文件的既有 frontmatter `id` 是稳定身份;
|
||||
2. 现有 `import bind:target` 是代码中的规范加载/寻址;
|
||||
3. `#` / `##` 是人可读的路径段;
|
||||
4. 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定 `symbol_id`;歧义必须报错。
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: knowledge.people.li-bai
|
||||
import:
|
||||
li_bai: knowledge/people/li-bai.mq.md
|
||||
---
|
||||
|
||||
# 回答
|
||||
|
||||
**year = [李白的出生年份](li_bai.李白.出生年份)**
|
||||
李白出生于[公元 701 年](李白.出生年份)。
|
||||
```
|
||||
|
||||
第一处是可运行代码,使用显式 import;第二处是正文的发现地址。它们编译后都指向
|
||||
`knowledge.people.li-bai::李白.出生年份`。短地址从来不是“按项目扫描第一个名字”,
|
||||
而是可读的查询,必须由 lock 固化。
|
||||
|
||||
---
|
||||
|
||||
## 4. 每个 `[]()` 产生统一的知识记录
|
||||
|
||||
不要把 LinkInfo 固定成单一的 `target`。任意载荷都可能含有多个读、写、调用和循环依赖:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "逐个订单行",
|
||||
"payload_kind": "loop",
|
||||
"roles": ["iterate"],
|
||||
"source": {"file": "capabilities/order-pricing.mq.md", "line": 22},
|
||||
"inputs": ["订单.行"],
|
||||
"outputs": ["行"],
|
||||
"dependencies": [
|
||||
{"kind": "local_value", "path": "订单.行"},
|
||||
{"kind": "symbol", "id": "capability.order-pricing::订单定价.含税价"}
|
||||
],
|
||||
"effect": "pure",
|
||||
"fingerprint": "sha256:…"
|
||||
}
|
||||
```
|
||||
|
||||
此记录就是统一知识图节点:
|
||||
|
||||
- 本地取元有输入/类型边;
|
||||
- 纯计算有输入/输出/公式边;
|
||||
- 循环有集合、变量绑定和循环体边;
|
||||
- 调用有 `calls`/`uses` 边;
|
||||
- 有来源的事实再增加 `derived_from` 边;
|
||||
- 正文节点有 `narrates` 边,连接它所在句子和计算结果;
|
||||
- 副作用节点有权限/影响目标边,不能被 `view` 或 `verify` 静默执行。
|
||||
|
||||
来源不是每个节点的前提,而是图中的一种边。没有来源的字典取元仍是知识步骤;
|
||||
若它最终支撑对外事实,沿依赖链应能找到来源,否则在“发布/验证事实”时才报证据不足。
|
||||
|
||||
---
|
||||
|
||||
## 5. 闭环:写、跑、看、查、变
|
||||
|
||||
```text
|
||||
作者写 Named<T>
|
||||
│
|
||||
├─ run:擦除 label,按原语义执行
|
||||
├─ view:显示 label,可展开值、输入、步骤和来源
|
||||
└─ check:解析所有依赖,编译统一知识图
|
||||
│
|
||||
catalog / lock / context pack
|
||||
│
|
||||
来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named<T> 与叙述句子
|
||||
│
|
||||
作者或 agent 修复后重新 check/verify
|
||||
```
|
||||
|
||||
### 5.1 命令边界
|
||||
|
||||
| 操作 | 做什么 | 不做什么 |
|
||||
|---|---|---|
|
||||
| `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 |
|
||||
| `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 |
|
||||
| `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 |
|
||||
| `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 |
|
||||
| `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 |
|
||||
|
||||
这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实施顺序
|
||||
|
||||
1. 在表达式、遍历和正文三处统一保留 `Named<T>`;payload 复用各自现有 parser。
|
||||
2. 为任意 `Named<T>` 提取 `inputs`、`outputs`、`dependencies`、`effect`、`roles`;从单 target 演进为依赖集合。
|
||||
3. 让 `#`/`##` 契约为内部步骤提供类型/公开边界;让 frontmatter `id` + import 提供跨文件稳定解析。
|
||||
4. 把现有 EKC 图扩展为步骤图:`observes`、`derives`、`iterates`、`calls`、`acts`、`narrates`、`derived_from`。
|
||||
5. 接入 `check`、`view`、`verify`、`impact` 与 lock;让一次变更能回到具体的 `[]()` 和具体句子。
|
||||
|
||||
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
|
||||
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
|
||||
@@ -61,7 +61,8 @@ Unknown names fail. Queries are only valid during a plugin function call (host s
|
||||
|
||||
```markdown
|
||||
---
|
||||
import plugin:lib/plugin.mq.md
|
||||
import:
|
||||
plugin: lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -159,11 +159,12 @@ REPLACE
|
||||
```markdown
|
||||
---
|
||||
title: agent-run-…
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import subtask:lib/subtask.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
json: lib/json.mq.md
|
||||
writeback: lib/writeback.mq.md
|
||||
subtask: lib/subtask.mq.md
|
||||
---
|
||||
|
||||
# 总目标
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**engineering-knowledge.md**](engineering-knowledge.md)(**EKC / EFI preflight**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
## 0. 为什么要改掉旧方案
|
||||
|
||||
@@ -72,10 +72,11 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
导入 智能体:ext/ai/智能体.mq.md
|
||||
导入 大模型:ext/ai/大模型.mq.md
|
||||
导入 自写回:lib/自写回.mq.md
|
||||
导入 时间:lib/时间.mq.md
|
||||
导入:
|
||||
智能体: ext/ai/智能体.mq.md
|
||||
大模型: ext/ai/大模型.mq.md
|
||||
自写回: lib/自写回.mq.md
|
||||
时间: lib/时间.mq.md
|
||||
---
|
||||
|
||||
## 获取时间
|
||||
@@ -167,8 +168,9 @@ ext/
|
||||
**分层纪律(硬规则,勿破)**:
|
||||
|
||||
1. `ext/**/*.mq.md` **禁止**出现任何 `host_*` / `host_` 调用。
|
||||
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
|
||||
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
|
||||
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …;以及 EKC:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
|
||||
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF / EKC 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
|
||||
4. **Engineering preflight**:`agent.preflight` / `plan … eng_preflight=True` 在 agent-kb 之前解析 REUSE/ADAPT/CREATE(见 [engineering-knowledge.md](engineering-knowledge.md))。缺 `.marqdo` 知识图时返回 `missing_knowledge` 并放行,以兼容纯任务包测试。
|
||||
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
|
||||
|
||||
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
# 方案:智能体 / 大模型优化方向(代码即文档 · OKF · 沙盒)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · O1–O5 locked** |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 调研 | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
|
||||
| 路线 | [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md) |
|
||||
| 相关 | [ext-ai-sandbox.md](ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [okf.md](okf.md) · [engineering-knowledge.md](engineering-knowledge.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) · [ai-stack.md](../roadmap/ai-stack.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 方案立场
|
||||
|
||||
1. **强化差异化**:可执行 `.mq.md` 为权威;OKF 为复用;沙盒为证明;LLM 为探索。
|
||||
2. **不向隐藏 TOOL: 循环 / 向量权威回退。**
|
||||
3. 下列方向均为**可行**;推荐波次见 §3,最终裁剪由你选型。
|
||||
4. **不改** `doc/next/*`;落地时另开 roadmap 切片。
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构愿景(闭环)
|
||||
|
||||
```text
|
||||
目标 / 任务
|
||||
│
|
||||
▼
|
||||
EFI / OKF lookup ──hit──► llm_free / marqdo 执行 ──► writeback
|
||||
│ miss
|
||||
▼
|
||||
small-llm 路由 / 父分解
|
||||
│
|
||||
▼
|
||||
生成或修补 .mq.md(代码即文档风格)
|
||||
│
|
||||
▼
|
||||
sandbox.open → sandbox.run(caps)→ diff
|
||||
│
|
||||
├─ 失败 → writeback error / 隔离,不 promote
|
||||
└─ 成功 → 人审或策略 → commit → solidify / OKF promote
|
||||
│
|
||||
▼
|
||||
下次 REUSE(降本)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 可行方向全集
|
||||
|
||||
每个方向标注:解决的问题(Pn)、依赖、风险、粗粒度成本。
|
||||
|
||||
### A. 沙盒 × Agent 闭环
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **A1** | `step`/`plan` 默认经 sandbox 试跑再写实树 | P1 | 生成落 upper;绿才 `commit` | sandbox | 破坏现有金样默认 | 中 |
|
||||
| **A2** | Promote / solidify 强制 sandbox proof | P1 | OKF 写入前要求 proof fixture 绿 | sandbox+OKF | 过严挡复用 | 中 |
|
||||
| **A3** | Sandbox profile 表(caps 宣告) | P1/P3 | GFM 表声明 net/plugin/fs | sandbox | 表方言膨胀 | 低 |
|
||||
| **A4** | Guest 风格门禁(表优先、禁 json 胶水) | P5 | commit 前 lint / preflight | sandbox+parser | 误杀合法 json.parse | 中 |
|
||||
| **A5** | 会话 diff → view 审阅卡 | P1/P4 | HITL 看 CoW diff | view+sandbox | UI 工时 | 中高 |
|
||||
| **A6** | 多会话并行 CoW(fan-out 实验) | — | 每假设一 session | sandbox | 隔离/合并复杂 | 高 |
|
||||
|
||||
### B. OKF / EKC / 技能层
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **B1** | OKF 技能元数据:适用条件 / fixtures / sandbox_profile | P2 | frontmatter + 目录约定 | okf | 与 catalog 字段冲突 | 中 |
|
||||
| **B2** | Progressive disclosure(索引轻、正文按需 READ) | P2/P6 | 对齐 Anthropic Skills 层级 | agent A3 | 实现重复 | 中 |
|
||||
| **B3** | Skill Lift 评测(有/无技能配对) | P4 | harness 指标 | B1 评测 | 样本少噪声大 | 中 |
|
||||
| **B4** | 失败技能隔离(quarantine)+ 回归用例跟随血缘 | P1 | ForgeAgent 式 | OKF | 状态机复杂 | 中高 |
|
||||
| **B5** | near-match / soft_match 产品化默认开 | P6 | 已有 roadmap | okf-near | 误复用 | 低中 |
|
||||
| **B6** | EKC preflight 默认硬门槛(REUSE→ADAPT→CREATE) | P6 | step 前强制 EFI | EKC | 拖慢探索 | 中 |
|
||||
| **B7** | Capability 包与 `llm_free` 资源双向链接 | P2 | catalog L3↔任务包 | EKC+OKF | 图维护 | 中 |
|
||||
|
||||
### C. 大模型 / 路由 / 成本
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **C1** | 步骤级路由(lookup / patch / sandbox_run / net) | P3 | 扩展 route policy 表 | routing | 策略过拟合 | 中 |
|
||||
| **C2** | 总成本计量(含推理 token 膨胀)写回文档 | P7 | usage→writeback/metrics | llm result | 噪声 | 低中 |
|
||||
| **C3** | 用强模型「反思」优化 standing / policy `.mq.md`(类 GEPA) | P3/P5 | 离线优化环,产物仍是文件 | llm | 需评测集 | 高 |
|
||||
| **C4** | 高频 OKF 技能蒸馏/微调小模型(编译进权重) | — | 长期研究 | 数据+算力 | 运维重;偏离「源码权威」 | 很高 |
|
||||
| **C5** | Named model 绑定任务类型(fast=路由,reasoning=分解) | P3 | 已有 named handles 加深 | llm | 配置漂移 | 低 |
|
||||
| **C6** | Prompt document 强制:无参 ask 必须来自 type:prompt 文件 | P5 | 硬化 005 | llm | 破坏脚本式调用 | 低 |
|
||||
|
||||
### D. 代码即文档(产出质量)
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **D1** | 官方「可读 Marqdo」Skill 强化(表/链接取元/禁混名) | P5 | skills/marqdo 加厚 | skill | 模型仍违规 | 低 |
|
||||
| **D2** | AST/结构 lint:json.set 链、混 EN/ZH API | P5 | `marqdo lint` 或 sandbox 钩子 | parser | 误报 | 中 |
|
||||
| **D3** | 工作簿补丁只允许表驱动 / 命名槽写回 | P5 | 收紧 A0 补丁面 | agent | 表达力下降 | 中 |
|
||||
| **D4** | 示例库:sandbox+OKF+表风格 canonical demos | P4/P5 | examples/ | 文档 | 维护 | 低 |
|
||||
|
||||
### E. 评测与产品化
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **E1** | 完成 Wave B1 harness(constitution / writeback / call_site) | P4 | 已规划 | agent | — | 中 |
|
||||
| **E2** | 指标面板:ReuseRate / ProofRate / TokenCost | P4/P7 | metrics 写回或 catalog | agent | 虚荣指标 | 中 |
|
||||
| **E3** | Live 金样矩阵(sandbox 开/关 × 路由后端) | P4 | CI optional | CI | flaky | 中 |
|
||||
| **E4** | 教程:「只读一份 .mq.md 理解 Agent」 | — | doc/tutorial | 文档 | — | 低 |
|
||||
|
||||
### F. 明确不优先 / 需单独论证
|
||||
|
||||
| ID | 方向 | 理由 |
|
||||
|----|------|------|
|
||||
| **F1** | 第二套 Agent Framework(Python/TS 对象图权威) | 违宪 |
|
||||
| **F2** | 向量库升为记忆权威 | 违宪;可作证据工具 |
|
||||
| **F3** | 默认通用 shell Agent | 与 Marqdo-only 沙盒战略冲突 |
|
||||
| **F4** | 整库 `ext/web` 进默认沙盒 | 已否决 |
|
||||
| **F5** | 人人 microVM 本地默认 | DX 过重;留给 hosted |
|
||||
|
||||
---
|
||||
|
||||
## 3. 执行顺序(O1→O5 locked)
|
||||
|
||||
| 波次 | 方向组合 | 为何先做 |
|
||||
|------|----------|----------|
|
||||
| **O1** | A1 轻量(opt-in `sandbox=True`)+ A3 + D1 + D4 | 立刻接上刚落地的沙盒,风险可控 |
|
||||
| **O2** | A2 + B1 + B3 + E1 | 验证→晋升→可度量 Skill Lift |
|
||||
| **O3** | C1 + C2 + B6 | 降本与 EFI 硬门槛 |
|
||||
| **O4** | A4 + D2 + A5 | 质量门禁与人审 |
|
||||
| **O5** | B4 + C3 | 失败隔离与离线提示优化 |
|
||||
| **O∞** | C4 / A6 | 研究项,单独立项 |
|
||||
|
||||
切片实现见 [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收原则(任一波次)
|
||||
|
||||
- 金样:有/无沙盒、有/无 OKF hit、路由后端切换。
|
||||
- 指标:至少报告 ReuseRate 或 TokenCost 之一相对基线变化。
|
||||
- 文档:`.mq.md` 示例仍可读为 Markdown(表/链接取元,少 json 胶水)。
|
||||
- 红线:不改 `doc/next/*`;ext 不调 `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 落地
|
||||
|
||||
O1–O5 已锁定;实现见 [roadmap/ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。**仍不改** `doc/next/*`。
|
||||
@@ -0,0 +1,104 @@
|
||||
# Official AI sandbox (`ext/ai/sandbox`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted · implementing** |
|
||||
| Date | 2026-10-16 |
|
||||
| Related | [research/ai-agent-sandbox.md](../research/ai-agent-sandbox.md) · [roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [stdlib-writeback.md](stdlib-writeback.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. One-liner
|
||||
|
||||
**Agent-only Marqdo trial runtime:** capability-isomorphic to browser Wasm defaults, CoW workspace until explicit `commit`, author surface under `ext/ai` (not stdlib).
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals / non-goals
|
||||
|
||||
### Goals
|
||||
|
||||
| # | Goal |
|
||||
|---|------|
|
||||
| G1 | Open a CoW session over a workspace root; edits stay in upper until `commit` |
|
||||
| G2 | `run` executes `.mq.md` (or in-memory source) under deny-by-default caps with core `lib/*` usable |
|
||||
| G3 | `diff` / `discard` / `inspect` for review gates |
|
||||
| G4 | Stable `unavailable in sandbox` for plugin.load, exec foreign/subtask path|code|lang, net (default), `ext/web` server APIs |
|
||||
| G5 | Author API in `ext/ai/sandbox` via `plugins/agent` — **no** public `lib/sandbox` |
|
||||
|
||||
### Non-goals (this wave)
|
||||
|
||||
| # | Non-goal |
|
||||
|---|----------|
|
||||
| N1 | Embed wasmtime in CLI |
|
||||
| N2 | True Wasm ABI plugins (linalg/quantum) |
|
||||
| N3 | bwrap / microVM |
|
||||
| N4 | Full `ext/web` listen/DB/WS inside sandbox |
|
||||
| N5 | Symlink-forest workspace isolation |
|
||||
| N6 | Default host-proxy of all native ABI plugins |
|
||||
| N7 | Wire `agent.step`/`plan` through sandbox automatically (later) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Layering
|
||||
|
||||
```text
|
||||
ext/ai/sandbox.mq.md → plugin.load agent → sandbox_* ABI
|
||||
↓ host_query
|
||||
HostContext + CowSession
|
||||
(fs / writeback see upper)
|
||||
```
|
||||
|
||||
| Layer | May call `host_*` | Role |
|
||||
|-------|-------------------|------|
|
||||
| `ext/ai/sandbox` | **No** | Author facade |
|
||||
| `plugins/agent` | via `host_query` only | Register `sandbox_*`; forward to host |
|
||||
| `src/host` | — | CoW session store; fs/writeback intercept; nested `run` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Author API
|
||||
|
||||
EN: `ext/ai/sandbox.mq.md` · ZH: `ext/ai/沙盒.mq.md` (separate files, no mixed names in one module).
|
||||
|
||||
| Method | Params | Result |
|
||||
|--------|--------|--------|
|
||||
| `open` | optional `root=` (default entry dir / cwd) | map `{ id, root }` |
|
||||
| `write` | `id=`, `path=`, `text=` | none |
|
||||
| `read` | `id=`, `path=` | text |
|
||||
| `remove` | `id=`, `path=` | none (whiteout) |
|
||||
| `diff` | `id=` | list of `{ path, kind: write\|remove }` |
|
||||
| `commit` | `id=` | `{ ok, applied }` |
|
||||
| `discard` | `id=` | `{ ok }` |
|
||||
| `run` | `id=`, `path=` **or** `source=` | `{ ok, value, stdout?, error? }` |
|
||||
| `inspect` | `id=` | caps, root, change count, notes |
|
||||
|
||||
Default `run` caps: `fs_write=true` (CoW only), `exec=false`, `net=false`, `plugin=false`.
|
||||
|
||||
---
|
||||
|
||||
## 4. CoW semantics
|
||||
|
||||
- **lower** = real workspace root (read-through).
|
||||
- **upper** = session map path → bytes.
|
||||
- **whiteout** = logical deletes; reads miss; commit unlinks lower.
|
||||
- No symlink-as-isolation; resolve paths under root; reject `..` escape.
|
||||
- Until `commit`, host tree unchanged (verifiable with `git status` / file mtime).
|
||||
|
||||
---
|
||||
|
||||
## 5. Hard bans
|
||||
|
||||
1. No public `lib/sandbox`.
|
||||
2. No symlink forest as the isolation story.
|
||||
3. No silent success when capability missing — diagnose `unavailable in sandbox`.
|
||||
4. `ext/**` must not call `host_*`.
|
||||
5. Do not treat empty `# main` as sandbox completeness.
|
||||
|
||||
---
|
||||
|
||||
## 6. ABI / host_query
|
||||
|
||||
Plugin exports (registered on agent plugin): `sandbox_open`, `sandbox_write`, `sandbox_read`, `sandbox_remove`, `sandbox_diff`, `sandbox_commit`, `sandbox_discard`, `sandbox_run`, `sandbox_inspect`.
|
||||
|
||||
Implementation: each forwards to allowlisted `host_query` names of the same stem (e.g. `sandbox_open`), which mutate the process-local CoW store and (for `run`) invoke nested capture with a sandboxed `HostContext`.
|
||||
@@ -197,7 +197,8 @@
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# 转置反序
|
||||
|
||||
@@ -201,8 +201,9 @@ $$
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -20,7 +20,8 @@ Import:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -101,7 +101,8 @@ marqdo ext add quantum
|
||||
|
||||
```markdown
|
||||
---
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
@@ -341,7 +342,8 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
|
||||
```markdown
|
||||
---
|
||||
title: Bell state
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
@@ -62,8 +62,9 @@ route: /
|
||||
method: GET
|
||||
data_source: posts
|
||||
data_order: -created_at
|
||||
import web:ext/web/web.mq.md
|
||||
import data:ext/data/db.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
data: ext/data/db.mq.md
|
||||
---
|
||||
|
||||
# Marqdo
|
||||
@@ -106,7 +107,8 @@ path: /api/posts
|
||||
request: json
|
||||
response: json
|
||||
auth: member
|
||||
import data:ext/data/db.mq.md
|
||||
import:
|
||||
data: ext/data/db.mq.md
|
||||
---
|
||||
|
||||
**post = > data.db.insert …**
|
||||
@@ -120,8 +122,8 @@ import data:ext/data/db.mq.md
|
||||
| `path` | `路径` | URL |
|
||||
| `method` | `方法` | GET/POST/… |
|
||||
| `request` | `请求` | `json` / `form` / `none` |
|
||||
| `response` | `响应` | `json` / `text` / `html` |
|
||||
| `auth` | `鉴权` | 角色名或 `none` |
|
||||
| `response` | `响应` | `json` / `text` / `html` / `sse`(`text/event-stream`) |
|
||||
| `auth` | `鉴权` | 角色名或 `none`;`bearer` / `api_key` = 不要求 cookie,把 `Authorization` / `X-Api-Key` 注入 payload 由 `# main` 校验 |
|
||||
|
||||
正文在请求时执行;返回值按 `response` 序列化。Result 协议见 §8。
|
||||
|
||||
|
||||
@@ -49,7 +49,8 @@
|
||||
英文:
|
||||
|
||||
```markdown
|
||||
import web:ext/web/web.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
|
||||
# main
|
||||
|
||||
|
||||
@@ -347,7 +347,8 @@ plugins/web/ # Go module(替换原 Rust crate)
|
||||
scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
|
||||
```
|
||||
|
||||
原 Rust 源码:`plugins/web-rust-archive/`(**已移出 Cargo workspace**;参考用,默认不构建)。
|
||||
原 Rust 源码:曾置于 `plugins/web-rust-archive/`(已移出 Cargo workspace,参考用);
|
||||
该目录已于 v1.6 精简时从工作树移除,历史保留在 git 中。
|
||||
|
||||
### 9.2 产物与解析
|
||||
|
||||
|
||||
+16
-14
@@ -128,13 +128,14 @@ myapp/
|
||||
---
|
||||
title: web-site
|
||||
description: Home = page table; main may be inline; class methods assemble.
|
||||
import web:ext/web/web.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
shell: styles/shell.mq.md
|
||||
nav: components/nav.mq.md
|
||||
side: components/side.mq.md
|
||||
foot: components/foot.mq.md
|
||||
articles: db/articles.mq.md
|
||||
db: db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -171,13 +172,14 @@ Main content is not a reusable component, so it is authored here.
|
||||
```markdown
|
||||
---
|
||||
title: 站点
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
shell: styles/shell.mq.md
|
||||
nav: components/nav.mq.md
|
||||
side: components/side.mq.md
|
||||
foot: components/foot.mq.md
|
||||
articles: db/articles.mq.md
|
||||
db: db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# 块公式元数据绑定 · 控制流叙述统一
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | Active |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 块公式 `% marqdo: var=`
|
||||
|
||||
在 `$$…$$` 块内用 **TeX 行注释**声明绑定名(渲染通常不可见;运行时剥离后解析公式体):
|
||||
|
||||
```markdown
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
```
|
||||
|
||||
- 指令:`% marqdo:` + 空白 + `var=<ident>`;未知键 → Error。
|
||||
- 可无前置 `` `f` = ``;若同时写空 RHS 与 `var=`,**同名允许、异名 Error**。
|
||||
- **保留**旧空 RHS + 后随 `$$`。
|
||||
- **不做**:行内 `$% marqdo:…$`;\`\`\` 代码围栏内语言注释 meta(本波)。
|
||||
- 行内公式继续传统绑定:`` `g` = $x+1$ ``(单 `$…$` → `formula`)或 `` `g` = $$x+1$$ ``。
|
||||
|
||||
无名叙述区 `$$` 仍仅展示;可执行区裸块既无空 RHS 又无 `var=` → Error。
|
||||
|
||||
---
|
||||
|
||||
## 2. 臂 / 循环体叙述(与函数体同权)
|
||||
|
||||
`parse_indented_body` 与函数体相同:消费 `` `名` `` / `**代码**` / `*返回*`;纯叙述跳过。
|
||||
斜体返回结束**当前臂或当前循环体**,不结束外层函数。
|
||||
|
||||
---
|
||||
|
||||
## 3. 循环头
|
||||
|
||||
| 面 | 写法 | 说明 |
|
||||
|----|------|------|
|
||||
| **推荐** | `- [项](xs)` / `- [`项`](`xs`)` | 支持嵌套 |
|
||||
| 中文糖 | `- 对`xs`的每一项`项`` | 可选后缀「遍历」 |
|
||||
| 英文糖 | `- for each `item` in `xs`` | 大小写不敏感 `for each` / `in` |
|
||||
|
||||
糖与链接头语义相同,可混用嵌套。
|
||||
|
||||
---
|
||||
|
||||
## 4. 分支条件行叙述
|
||||
|
||||
结构行仍以 `1.` / `2.` 开头。条件提取顺序:
|
||||
|
||||
1. 整段可解析为表达式(现状);
|
||||
2. 行内粗体代码条件 `**`n` > 0**`;
|
||||
3. 剥离「当/若/如果/when/if」与「时/则」后,将「大于/小于/等于…」映射为运算符再解析。
|
||||
|
||||
else:`N. *`(可夹「否则」等叙述,条件位仍为 `*`)。
|
||||
禁止无标记自然语言整句当条件。
|
||||
@@ -0,0 +1,453 @@
|
||||
# 外联内核(Foreign Kernel)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **F0–F3.5 已实现** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime(`src/foreign/` · `src/host/foreign*` · `lib/foreign.mq.md`) |
|
||||
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-syntax.md](notebook-syntax.md) · [notebook-session.md](notebook-session.md) · [stdlib-foreign.md](stdlib-foreign.md) · [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
| 核心表面 Δ | 无 |
|
||||
|
||||
> 外联内核 = 一个长期存活的外部语言进程 + 生命周期 + 类型桥 + 记录。它既能被 `marqdo run` 里的显式调用使用,也能被 view 的 notebook 会话使用。
|
||||
|
||||
---
|
||||
|
||||
## 1. 定位与边界
|
||||
|
||||
### 1.1 负责
|
||||
|
||||
- 解释器发现、注册、配置、探测。
|
||||
- 一次性执行:临时脚本、stdin/stdout/stderr、超时、输出上限。
|
||||
- 持久内核:启动、求值、状态、关闭、列表。
|
||||
- 状态桥:`session_set` / `session_get` / `session_names`。
|
||||
- JSON 值桥:Marqdo `Value` ↔ JSON。
|
||||
- 结构化记录:`ok/code/stdout/stderr/ms/timed_out/truncated/result/error`。
|
||||
- 安全:`exec` 门禁、`cwd` 沙箱、进程组、并发/输出上限。
|
||||
- 视图诊断:代码卡片 Run 的完整结果。
|
||||
|
||||
### 1.2 不负责
|
||||
|
||||
- 文档语法(`内核表` / `会话表`)→ [notebook-syntax.md](notebook-syntax.md)。
|
||||
- 文档会话 / cell 顺序 / journal / view UI → [notebook-session.md](notebook-session.md)。
|
||||
- Foreign → Marqdo 函数回调(v2 不做)。
|
||||
- 依赖安装(pip/npm)。
|
||||
- 远程 / 容器执行。
|
||||
|
||||
### 1.3 与相邻模块的区别
|
||||
|
||||
| 模块 | 生命周期 | 用途 |
|
||||
|---|---|---|
|
||||
| `foreign` | 一次性或持久 | 调外部语言;状态可选 |
|
||||
| `subtask` | 一次性并发 | 后台任务、文件子任务、函数子任务 |
|
||||
| `plugin` | 进程内 | 原生 C ABI 扩展 |
|
||||
| `writeback` | 文档级 | 把输出写回 `.mq.md` |
|
||||
|
||||
`subtask` 不管理持久状态;`foreign` 不管理文档执行顺序。
|
||||
|
||||
---
|
||||
|
||||
## 1.4 实施状态(2026-10-17)
|
||||
|
||||
| 阶段 | 状态 | 关键文件 |
|
||||
|---|---|---|
|
||||
| F0 安全执行 / `invoke` 记录 | ✅ | `src/host/foreign.rs` |
|
||||
| F1 预设 / probe / register / config | ✅ | `src/foreign/registry.rs` · `src/host/foreign.rs` |
|
||||
| F2 JSON 桥 / run_many / call_many | ✅ | `src/host/foreign.rs` |
|
||||
| F3 Python/Node 持久内核 | ✅ | `src/host/foreign_session.rs` |
|
||||
| F3.5 session_set/get/names | ✅ | 同上 |
|
||||
| F4 history / view 打磨 / 发布 | 部分 | — |
|
||||
|
||||
测试:`cargo test --lib foreign`(11+)、`cargo test --test gold lib_foreign`(12,python 条件跳过)、`tests/notebook/shared.mq.md` 手工 view 验证。
|
||||
|
||||
---
|
||||
|
||||
## 2. 语言与内核模型
|
||||
|
||||
### 2.1 语言预设
|
||||
|
||||
| lang | 别名 | 默认命令 | 扩展名 | 版本探测 | 会话 |
|
||||
|---|---|---|---|---|---|
|
||||
| `python` | `python3`, `py` | `python3`(Windows `python`) | `.py` | `--version` | ✅ |
|
||||
| `node` | `javascript`, `js` | `node` | `.js` | `-v` | ✅ |
|
||||
| `deno` | — | `deno run` | `.ts` | `--version` | ❌ |
|
||||
| `bun` | — | `bun` | `.js` | `--version` | ❌ |
|
||||
| `ruby` | — | `ruby` | `.rb` | `--version` | ❌ |
|
||||
| `perl` | — | `perl` | `.pl` | `--version` | ❌ |
|
||||
| `php` | — | `php -r {inline}` | `.php` | `--version` | ❌ |
|
||||
| `lua` | — | `lua` | `.lua` | `-v` | ❌ |
|
||||
| `r` | `rscript` | `Rscript` | `.R` | `--version` | ❌ |
|
||||
| `julia` | — | `julia` | `.jl` | `--version` | ❌ |
|
||||
| `go` | — | `go run {file}` | `.go` | `version` | ❌ |
|
||||
| `bash` | `sh`, `shell` | `bash` | `.sh` | `--version` | ❌ |
|
||||
| `powershell` | `pwsh`, `ps1` | `pwsh`(Windows `powershell`) | `.ps1` | `--version` | ❌ |
|
||||
| `sqlite` | `sqlite3` | `sqlite3` | `.sql` | `--version` | ❌ |
|
||||
| `tsx` | `typescript` | `tsx` | `.ts` | `--version` | ❌ |
|
||||
|
||||
说明:
|
||||
|
||||
- 预设只是默认值;注册 / 配置 / 环境变量整体覆盖。
|
||||
- 会话能力首批只有 Python / Node;其它语言一次性执行。
|
||||
- `php` 用 `{inline}`,围栏里直接写 PHP,不需要 `<?php`。
|
||||
- `deno` 默认不给权限;需要时通过配置追加 `--allow-*`。
|
||||
|
||||
### 2.2 解析优先级
|
||||
|
||||
从高到低:
|
||||
|
||||
1. 调用级 `cmd`(整行 argv,shell-like 切分)+ `args`(追加)。
|
||||
2. 进程内注册:`register` / `set_cmd`。
|
||||
3. 环境变量 `MARQDO_FOREIGN_<LANG>`(整行或 JSON 数组)。
|
||||
4. 项目配置 `.marqdo/foreign.toml` / `MARQDO_FOREIGN_CONFIG`。
|
||||
5. 内置预设。
|
||||
6. 都没有 → 带修复建议的诊断。
|
||||
|
||||
Python 额外发现顺序(在预设层内):
|
||||
|
||||
1. `VIRTUAL_ENV/bin/python`(Windows `Scripts/python.exe`);
|
||||
2. `<cwd>/.venv` / `venv` / `env`;
|
||||
3. 入口目录与 `fs_root` 向上查找;
|
||||
4. PATH 的 `python3` / `python`。
|
||||
|
||||
`MARQDO_FOREIGN_NO_VENV=1` 关闭 venv 探测;显式 `cmd` / `set_cmd` / `MARQDO_FOREIGN_PYTHON` 优先。
|
||||
|
||||
相对路径:配置里的 `cmd` 相对配置目录;注册 / `set_cmd` / 环境变量里的 `cmd` 相对 `cwd`。
|
||||
|
||||
### 2.3 注册与模板
|
||||
|
||||
`register(lang, cmd?, args?, template?, ext?, env?, version_args?)`。
|
||||
|
||||
模板占位符:
|
||||
|
||||
| 占位符 | 展开 |
|
||||
|---|---|
|
||||
| `{file}` | 临时脚本绝对路径 |
|
||||
| `{dir}` | 临时目录 |
|
||||
| `{base}` | 脚本文件名 |
|
||||
| `{inline}` | 源码作为一个 argv;不写临时文件 |
|
||||
| `{lang}` | 语言 id |
|
||||
| `{cwd}` | 实际工作目录 |
|
||||
|
||||
规则:
|
||||
|
||||
- `cmd` 与 `template` 至少一个;都给 → 报错。
|
||||
- `{file}` 与 `{inline}` 不能同时出现。
|
||||
- 都没有时自动追加 `{file}`。
|
||||
- `{inline}` 超过 60 KiB → 报错并建议 `{file}`。
|
||||
- 模板不做 shell 转义;需要 shell 时显式写 `bash -c`,路径由引擎生成(安全字符)。
|
||||
|
||||
配置示例:
|
||||
|
||||
```toml
|
||||
[python]
|
||||
cmd = ".venv/bin/python"
|
||||
args = ["-u"]
|
||||
|
||||
[go]
|
||||
template = ["go", "run", "{file}"]
|
||||
|
||||
[rust]
|
||||
template = ["bash", "-c", "rustc -O {file} -o {dir}/main && {dir}/main"]
|
||||
|
||||
[php]
|
||||
template = ["php", "-r", "{inline}"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 一次性执行
|
||||
|
||||
### 3.1 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|---|---|---|---|
|
||||
| `run` | `运行` | `code`, 可选 `stdin` `env` `cwd` `timeout` `args` `max_output` | stdout 文本(v1 兼容) |
|
||||
| `run_lang` | `按语言运行` | `lang`, `source`, 可选同上 | stdout 文本 |
|
||||
| `invoke` | `执行` | 可选 `code` / `lang`+`source` / `stdin` / `input` / `env` / `cwd` / `timeout` / `args` / `output` / `max_output` / `cmd` / `keep` / `cache` | 记录 map |
|
||||
| `call` | `调用` | 可选 `code` / `lang`+`source` / `input` / `stdin` / `env` / `cwd` / `timeout` / `args` | 解析后的 JSON 值 |
|
||||
| `run_many` | `批量运行` | `runs`, 可选 `concurrency` | 记录列表 |
|
||||
| `call_many` | `批量调用` | `inputs`, 可选 `code` / `lang`+`source` / `cmd` / `env` / `cwd` / `timeout` / `args` / `max_output` / `concurrency` | 结果值列表 |
|
||||
|
||||
### 3.2 记录结构
|
||||
|
||||
`invoke` / `run_many` / `session_eval` 共用:
|
||||
|
||||
| 键 | 类型 | 含义 |
|
||||
|---|---|---|
|
||||
| `ok` | Bool | exit=0 且未超时 |
|
||||
| `code` | Int | 退出码;未启动 / kill → -1 |
|
||||
| `stdout` | Text | 原始 stdout(可能截断) |
|
||||
| `stderr` | Text | 原始 stderr(可能截断) |
|
||||
| `ms` | Int | 墙钟毫秒 |
|
||||
| `lang` | Text | 实际语言 |
|
||||
| `cmd` | Text | 实际 argv |
|
||||
| `timed_out` | Bool | 是否超时 |
|
||||
| `truncated` | Bool | stdout/stderr 是否截断 |
|
||||
| `result` | 任意 / None | 按 `output` 解析 |
|
||||
| `result_error` | Text | json 解析失败原因 |
|
||||
| `error` | Text | 启动 / 超时 / 策略原因 |
|
||||
| `script` | Text | `keep=True` 的脚本路径 |
|
||||
| `cached` | Bool | 缓存命中(P4) |
|
||||
|
||||
`session_eval` 额外:`id`、`alive`。
|
||||
|
||||
### 3.3 输出模式
|
||||
|
||||
| `output=` | `result` |
|
||||
|---|---|
|
||||
| `auto`(默认) | 尝试 JSON;失败 → None |
|
||||
| `text` | None |
|
||||
| `json` | 解析;失败 → `result_error` |
|
||||
| `lines` | 行列表 |
|
||||
| `bytes` | stdout 原始字节的 base64 |
|
||||
|
||||
`call` 固定 JSON:空 stdout → None;非空非法 JSON → 错误。
|
||||
|
||||
### 3.4 失败语义
|
||||
|
||||
- `run` / `call`:执行失败 → `Err`;错误包含语言、argv、退出码、stderr(截 4 KiB)、stdout 头。
|
||||
- `invoke` / `run_many`:执行失败 → 记录;只有参数非法 / 策略拒绝 → `Err`。
|
||||
- 输出过大:截断 + `truncated=true`,不再 OOM / 报错。
|
||||
|
||||
---
|
||||
|
||||
## 4. JSON 状态桥
|
||||
|
||||
### 4.1 值映射
|
||||
|
||||
Canonical integer contract: [`v-safe-json.md`](v-safe-json.md) (Lean \(V_{\mathsf{safe}}\): `|n| ≤ 2^{53}-1`).
|
||||
|
||||
| Marqdo | JSON |
|
||||
|---|---|
|
||||
| None | null |
|
||||
| Bool | bool |
|
||||
| Int | number **仅当** `|n| ≤ 2^{53}-1`;越界 → 显式失败(禁止静默扭曲) |
|
||||
| Num | number(NaN/Inf → null);float 为宿主扩展,∉ mechanized \(V_{\mathsf{safe}}\) |
|
||||
| Text | string(宽整数用十进制字符串过桥,对端 `BigInt` / Python `int`) |
|
||||
| List | array(子树递归;任一越界整数使整体失败) |
|
||||
| Map | object(同上) |
|
||||
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
|
||||
| Code | 源码字符串 |
|
||||
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
|
||||
|
||||
错误前缀:`json: integer outside V_safe (±(2^53-1)): <n>`。
|
||||
|
||||
### 4.2 输入
|
||||
|
||||
- `input=` → JSON;写 stdin;同时提供 `MARQDO_INPUT`(≤8 KiB)与 `MARQDO_INPUT_FILE`(任意大小)。
|
||||
- `stdin=` 文本与 `input=` 互斥。
|
||||
- 都不给 → stdin EOF。
|
||||
- 大输入走文件,避免环境变量大小限制。
|
||||
|
||||
### 4.3 输出
|
||||
|
||||
- `result` 按 `output` 解析。
|
||||
- 原始 stdout/stderr 始终保留(截断到上限)。
|
||||
- `call` 返回解析值;`invoke` 返回记录。
|
||||
|
||||
### 4.4 类型限制
|
||||
|
||||
v2 是**值拷贝**,不是对象引用:
|
||||
|
||||
- Python DataFrame / NumPy / Node 对象 → 需要先 `to_dict` / `to_json` / `JSON.stringify`。
|
||||
- 大对象传输成本高;后续考虑 Arrow / Parquet / 文件句柄。
|
||||
- Secret 不默认进入 JSON;需要 env 显式交付。
|
||||
|
||||
---
|
||||
|
||||
## 5. 持久内核与会话
|
||||
|
||||
### 5.1 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|---|---|---|---|
|
||||
| `session_open` | `会话开启` | `lang`, 可选 `cmd` `env` `cwd` `timeout` | 会话 id(Text) |
|
||||
| `session_eval` | `会话求值` | `id`, 可选 `code` / `source` / `input` / `timeout` | 记录(含 id/alive) |
|
||||
| `session_set` | `会话设值` | `id`, `name`, `value` | None |
|
||||
| `session_get` | `会话取值` | `id`, `name` | JSON 值 / None |
|
||||
| `session_names` | `会话变量` | `id` | 名称列表 |
|
||||
| `session_close` | `会话关闭` | `id` | Bool |
|
||||
| `session_list` | `会话表` | — | map 列表 |
|
||||
|
||||
### 5.2 支持语言
|
||||
|
||||
| 语言 | 方式 |
|
||||
|---|---|
|
||||
| python | `python3 -u -c <bootstrap>` |
|
||||
| node | `node -e <bootstrap>` |
|
||||
| 其它 | 报错:`lang=… has no session bootstrap; use run/invoke` |
|
||||
|
||||
### 5.3 线路协议
|
||||
|
||||
stdin 每行一个 JSON 请求;原始 stdout 每行一个 JSON 响应:
|
||||
|
||||
```json
|
||||
{"id":1,"code":"x = 41","input":null}
|
||||
{"id":2,"code":"x + 1","input":null}
|
||||
```
|
||||
|
||||
```json
|
||||
{"id":1,"ok":true,"stdout":"","stderr":"","result":null,"error":""}
|
||||
{"id":2,"ok":true,"stdout":"","stderr":"","result":42,"error":""}
|
||||
```
|
||||
|
||||
- 同一会话严格串行:等到匹配响应后才发下一条。
|
||||
- 响应单行;JSON 转义换行。
|
||||
- 崩溃 / EOF → `alive=false`,会话移除。
|
||||
- 超时 → kill 会话(状态不可信)。
|
||||
|
||||
### 5.4 Python bootstrap
|
||||
|
||||
- 保留原始 `sys.stdout` 写协议;用户输出用 `redirect_stdout/stderr` 捕获。
|
||||
- `ast.parse`:最后一条是表达式 → 先 exec 前面,再 eval 最后,作为 result。
|
||||
- 异常 → `traceback.format_exc(limit=8)`,`ok=false`;会话继续。
|
||||
- `input` → 全局 `marqdo_input`。
|
||||
- 不可序列化 → `default=str`。
|
||||
|
||||
### 5.5 Node bootstrap
|
||||
|
||||
- 保存原始 `process.stdout.write` 写协议。
|
||||
- eval 期间替换 `console.*` 与 `process.stdout/stderr.write`;结束后恢复。
|
||||
- `vm.runInThisContext` 保留全局状态;`require` 挂到 `globalThis`。
|
||||
- Promise → await;顶层 await 需用户包 `(async()=>{…})()`。
|
||||
- 序列化失败 → `String(result)`。
|
||||
|
||||
### 5.6 状态桥
|
||||
|
||||
- `session_set`:值 → JSON → 请求 `{"set": name, "value": ...}` 或执行一段赋值。
|
||||
- `session_get`:请求 `{"get": name}` → JSON → Marqdo Value。
|
||||
- `session_names`:请求变量名列表。
|
||||
- 与 `session_eval` 同一线路协议;严格串行。
|
||||
- 名称必须是合法标识符;保留名(`marqdo_input` 等)另行文档。
|
||||
|
||||
### 5.7 生命周期
|
||||
|
||||
- id 为 `s1`、`s2`…。
|
||||
- 每会话独立进程、cwd、env。
|
||||
- `HostContext` drop → 全部 kill + wait。
|
||||
- `subtask` 不继承会话。
|
||||
- 不跨文档共享。
|
||||
|
||||
---
|
||||
|
||||
## 6. 环境契约
|
||||
|
||||
| 变量 | 值 |
|
||||
|---|---|
|
||||
| `MARQDO_FOREIGN` | `1` |
|
||||
| `MARQDO_FOREIGN_LANG` | 语言 id |
|
||||
| `MARQDO_FOREIGN_SCRIPT` | 脚本路径(文件模式) |
|
||||
| `MARQDO_FOREIGN_DIR` | 脚本目录 |
|
||||
| `MARQDO_FOREIGN_CWD` | 实际 cwd |
|
||||
| `MARQDO_ENTRY` | 入口 `.mq.md` 路径 |
|
||||
| `MARQDO_ENTRY_DIR` | 入口目录 |
|
||||
| `MARQDO_INPUT` | input JSON(≤8 KiB) |
|
||||
| `MARQDO_INPUT_FILE` | input JSON 文件(任意大小) |
|
||||
|
||||
语言默认:
|
||||
|
||||
- Python:`PYTHONUNBUFFERED=1`、`PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`;`PYTHONPATH` 前插 cwd。
|
||||
- Node:`NODE_PATH` 前插 cwd(可选)。
|
||||
|
||||
`env` 是 map;值 `as_display()`;Secret 取真实值(显式交付)。不主动清空父环境。
|
||||
|
||||
---
|
||||
|
||||
## 7. 临时文件与 cwd
|
||||
|
||||
- 默认 `<cwd>/.marqdo/tmp/foreign-<pid>-<nanos>/`;不可写 → 系统临时目录。
|
||||
- `MARQDO_FOREIGN_TMPDIR` 覆盖。
|
||||
- 脚本 `main.<ext>`;Python 加 utf-8 声明。
|
||||
- 默认 cwd = 入口目录;调用级 cwd 经 `resolve_path` + `fs_root` 校验。
|
||||
- 成功/失败/超时都清理;`keep=True` 保留并回填 `script`。
|
||||
- Node 相对 `require('./x')` 相对脚本目录;需要项目相对路径时用 `MARQDO_FOREIGN_CWD` 或 `{inline}` 模板。
|
||||
|
||||
---
|
||||
|
||||
## 8. 超时、IO、进程组
|
||||
|
||||
- `timeout`:秒,可小数;默认 10s;上限 3600s;`<=0` 报错。
|
||||
- 超时 kill 进程组:
|
||||
- Unix:`process_group(0)` + `kill(-pid, SIGKILL)`;
|
||||
- Windows:`taskkill /PID <pid> /T /F`。
|
||||
- `max_output`:每流默认 1 MiB;范围 1 KiB–64 MiB;保留前 N 字节,余下丢弃并继续排空;`truncated=true`。
|
||||
- stdin 独立写线程,避免双向管道死锁;EPIPE 忽略。
|
||||
- stdout/stderr 两个读线程;UTF-8 lossy。
|
||||
- 记录原始字节(至上限)以支持 `bytes` 输出。
|
||||
|
||||
---
|
||||
|
||||
## 9. 安全
|
||||
|
||||
| 项 | 策略 |
|
||||
|---|---|
|
||||
| 能力门禁 | `run` / `invoke` / `probe` / `session_*` 全部检查 `allow_exec()`;沙箱 → 拒绝 |
|
||||
| shell | 默认不经 shell;模板显式 `bash -c` 才走 |
|
||||
| cwd | `resolve_path` + `fs_root`;越界拒绝 |
|
||||
| 输出 | 有界读取 + 丢弃式排空 |
|
||||
| 时间 | 上限 + 进程组 kill |
|
||||
| 并发 | 默认 4,上限 32 |
|
||||
| 会话 | 每文档独立;关闭/drop 清理;超时即杀 |
|
||||
| Secret | JSON 不默认暴露;env 显式;面板打码 |
|
||||
| wasm | `exec-host` 关闭时全部返回清晰错误;`langs` 返回 [] |
|
||||
|
||||
---
|
||||
|
||||
## 10. 兼容性
|
||||
|
||||
- `run` / `run_lang` / `set_cmd` / `langs` 既有调用可用。
|
||||
- `run` 成功仍返回 stdout(去一个尾换行);非 0 仍报错。
|
||||
- `set_cmd` 增加可选 `args`。
|
||||
- `langs` 扩展为「预设 ∪ 注册 ∪ 配置」;原集合是子集。
|
||||
- `subtask` 的 `spawn code=` / `lang=` 仍返回 stdout 文本。
|
||||
- HostFn id 只追加;字节码参数 < 255。
|
||||
- 无核心表面 Δ。
|
||||
|
||||
---
|
||||
|
||||
## 11. 测试矩阵
|
||||
|
||||
| 测试 | 依赖 | 断言 |
|
||||
|---|---|---|
|
||||
| 既有 `foreign-python` / `run-lang` / `外联-python` | python | 兼容 |
|
||||
| `foreign-invoke` | node | ok/code/stdout/stderr/ms |
|
||||
| `foreign-env-cwd` | node | env/cwd/MARQDO_* |
|
||||
| `foreign-timeout` | node | timed_out, 无遗留进程 |
|
||||
| `foreign-call-json` | node | 嵌套 list/map 往返 |
|
||||
| `foreign-call-many` / `run-many` | node | 顺序/隔离/并发 |
|
||||
| `foreign-session` | node(python 可选) | 跨 eval 状态、异常不杀 |
|
||||
| `foreign-session-set-get` | node | 变量推拉 |
|
||||
| `foreign-session-timeout` | node | alive=false |
|
||||
| `foreign-probe` | node | path/version/ok |
|
||||
| `foreign-register` | node | 模板 `{inline}` |
|
||||
| `foreign-config` | node | `MARQDO_FOREIGN_CONFIG` |
|
||||
| `foreign-caps` | 无 | exec=false 拒绝 |
|
||||
| 单元测试 | 无 | shell 切分/模板/别名/JSON |
|
||||
|
||||
当前环境无 Python:node + bash 为主;python 条件跳过;Windows 用 `python_available()` / `bash_available()` 守卫。
|
||||
|
||||
---
|
||||
|
||||
## 12. 实现落点
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `src/foreign/registry.rs` | 预设/别名/模板/venv/PATH/配置/shell 切分(纯逻辑) |
|
||||
| `src/host/foreign.rs` | Job/Execution/ForeignEnv;run/invoke/call/run_many/call_many;probe/register/unset/langs/load_config |
|
||||
| `src/host/foreign_session.rs` | Python/Node bootstrap;会话生命周期;set/get/names |
|
||||
| `src/host/dispatch.rs` | HostFn 追加 |
|
||||
| `src/aliases.rs` | 参数别名 |
|
||||
| `lib/foreign.mq.md` / `lib/外联.mq.md` | L1 API + 文档 |
|
||||
| `src/view/mod.rs` / `html.rs` / `debug_page.rs` | Run 诊断;后续接文档会话 |
|
||||
| `tests/gold.rs` / `tests/lib/foreign-*.mq.md` | 测试 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 明确不做
|
||||
|
||||
- Foreign line-level step。
|
||||
- Foreign → Marqdo 函数 callback。
|
||||
- 自动镜像变量。
|
||||
- 跨语言共享对象引用。
|
||||
- 全进程快照。
|
||||
- 自动安装依赖。
|
||||
- 浏览器 wasm 外联。
|
||||
@@ -0,0 +1,654 @@
|
||||
# 外联运行时 v3 — 能力缺口与深化设计(Proposed)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed;尚未实现** |
|
||||
| 日期 | 2026-10-18 |
|
||||
| 层 | Runtime(foreign)· Document(`foreign.session`)· View(投影) |
|
||||
| 相关 | [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [stdlib-writeback.md](stdlib-writeback.md) · [view-static-interactive.md](view-static-interactive.md) |
|
||||
| 核心表面 Δ | **无增删**:不新增 Markdown 标记、不新增 notebook CLI |
|
||||
|
||||
> 本文只定义设计,不承诺已实现。当前基线是 v1.5.0 之后的本地工作:`foreign.session` 句柄、多内核、values 初始化、view 控制、静态执行与显式 writeback 已可用;本文处理仍然缺失的能力。
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计约束
|
||||
|
||||
v3 必须继续满足以下约束,否则不进入实现:
|
||||
|
||||
1. **外联库拥有内核与状态**:`foreign` 管理内核、会话、cell 计划、输入、输出、journal 和生命周期。`view` 只消费句柄,不拥有第二套运行时。
|
||||
2. **表与围栏是值**:`内核表`、`单元表`、`输入表`、`值表` 都是普通 Marqdo 值;没有保留表名,没有新增标记。
|
||||
3. **单一执行语义**:`run` 是规范执行;`view` 是同一文档的交互投影;静态导出是同一会话的快照,不另写解释器。
|
||||
4. **没有 Notebook 模式**:没有 `marqdo notebook`,没有 `In/Out`,没有“普通 view / notebook view”两套布局。
|
||||
5. **显式 I/O**:Marqdo 值通过 `values` / `session_set` 传递;程序 stdin 是单独概念,不能伪装成 `marqdo_input`。
|
||||
6. **显式持久化**:默认不改源码;writeback 必须由文档显式调用,或由用户显式选择策略。
|
||||
7. **安全默认值**:执行受 capability 控制;输入/输出有界;不反序列化任意对象;跨文档共享必须显式开启。
|
||||
|
||||
---
|
||||
|
||||
## 2. 基线:现在已经有什么
|
||||
|
||||
| 能力 | 状态 |
|
||||
|---|---|
|
||||
| `foreign.run` / `run_lang` / `invoke` / `probe` | 已实现 |
|
||||
| `foreign.call` / `call_many` / JSON 进出 / 并行 | 已实现 |
|
||||
| `session_open` / `eval` / `set` / `get` / `names` / `close` / `list` | 已实现 |
|
||||
| `foreign.session kernels= cells= values=` | 已实现 |
|
||||
| 多内核 view 会话、cell 顺序、内核归属 | 已实现 |
|
||||
| Marqdo 表通过 `values` 传入多个内核 | 已实现 |
|
||||
| 无 `会话` 时无状态 cells | 已实现 |
|
||||
| view 每 cell 内核选择 / Clean / Run | 已实现 |
|
||||
| 静态导出执行 cells 并嵌入真实输出 | 已实现 |
|
||||
| 静态页 session summary、内核归属、多内核展示 | 已实现 |
|
||||
| 显式 `writeback.record` | 已实现(库能力) |
|
||||
| 静态页按钮的“不可执行”提示 | 已实现 |
|
||||
|
||||
---
|
||||
|
||||
## 2.1 实施状态(2026-10-18)
|
||||
|
||||
| ID | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| G1/G2 | ✅ 已实现 | session eval raw stdin;`foreign.session inputs=`;per-cell UI;Python/Node 测试 |
|
||||
| G5 | ✅ 基本实现 | `session_interrupt` + view Interrupt;Python SIGINT 保留会话;Node 进程可能被终止 |
|
||||
| G4 | ✅ 已实现(API) | add/remove/set-value + generation;view 尚未提供 add/remove UI |
|
||||
| G6 | ✅ 已实现(API) | export/import/replay JSON snapshot;view/CLI 尚未做文件封装 |
|
||||
| G9 | ✅ 已实现(CLI/API 基础) | `view capture` + `view output --snapshot`;source hash 校验 |
|
||||
| G3 | ✅ 边界已实现 | 顶层 plan;嵌套 plan 诊断 |
|
||||
| G10 | ✅ 显式 persist | `/api/session/cell/persist` + view Persist;不自动写源码 |
|
||||
| G7/G8 | 📌 已移出当前目标 | 设计保留,后续版本再开发 |
|
||||
|
||||
## 3. 缺口清单
|
||||
|
||||
| ID | 缺口 | 优先级 | 当前行为 | 目标 |
|
||||
|---|---|---|---|---|
|
||||
| G1 | 持久内核 raw stdin | P0 | 持久内核只有 `marqdo_input` | 程序 stdin 与控制协议分离 |
|
||||
| G2 | 每 cell 独立 stdin | P0 | 页面级 Cell stdin,Run All 共用一个输入 | cell 级输入表 + UI |
|
||||
| G3 | 动态 plan | P2 | 只读顶层 `会话` | 明确边界,或受控动态 |
|
||||
| G4 | 运行时更新 plan | P1 | values 只在打开时初始化 | 显式 session 变更 API |
|
||||
| G5 | kernel interrupt | P0 | 只能等超时/杀进程组 | 可中断当前 eval |
|
||||
| G6 | 状态持久化 / replay | P1 | journal/dirty 只在内存 | 导出/恢复/replay |
|
||||
| G7 | 跨文档内核 | P2 | 每文档独立 | 显式 scope/空间 |
|
||||
| G8 | 非 Python/Node 持久内核 | P3 | Go 等一次性执行 | LangSpec 会话适配器 |
|
||||
| G9 | live → static 输入捕获 | P0 | 静态构建不捕获临时 stdin | 显式 snapshot 捕获 |
|
||||
| G10 | 自动 writeback | P2 | 必须显式调用 | 显式策略下的“运行后写回” |
|
||||
|
||||
---
|
||||
|
||||
## 4. 统一模型
|
||||
|
||||
### 4.1 会话句柄
|
||||
|
||||
`foreign.session` 返回的句柄是一个普通 Marqdo 值,建议稳定形状:
|
||||
|
||||
```text
|
||||
{
|
||||
kind: "foreign-session",
|
||||
id: "<session-id>",
|
||||
document: "<entry-source-hash>",
|
||||
status: "created | ready | running | interrupted | dirty | closed",
|
||||
kernels: [...],
|
||||
cells: [...],
|
||||
inputs: [...],
|
||||
values: [...],
|
||||
generation: 1
|
||||
}
|
||||
```
|
||||
|
||||
`view` 只读这些字段;任何执行操作都通过 `foreign` 的 host API。句柄不是第二套运行时。
|
||||
|
||||
### 4.2 三种输入
|
||||
|
||||
必须严格区分:
|
||||
|
||||
| 输入 | 目标 | 形态 | 当前 |
|
||||
|---|---|---|---|
|
||||
| `values` | 内核变量 | Marqdo 值 → JSON copy | 已实现 |
|
||||
| `input` | `marqdo_input` | JSON 值 | 已实现(低层) |
|
||||
| `stdin` | 程序 stdin | 原始文本/字节 | 仅无状态 cell 有 |
|
||||
|
||||
v3 不允许把 raw stdin 偷偷塞进 `marqdo_input`;两者语义不同。
|
||||
|
||||
### 4.3 每 cell 输入表
|
||||
|
||||
不新增标记,仍然使用普通表:
|
||||
|
||||
```mq.md
|
||||
`单元输入` =
|
||||
| 单元 | stdin | input |
|
||||
|------|-------|-------|
|
||||
| 计算 | hello | {rate: 0.08} |
|
||||
| 复核 | | {check: true} |
|
||||
```
|
||||
|
||||
`foreign.session` 增加可选参数:
|
||||
|
||||
```text
|
||||
foreign.session kernels=... cells=... values=... inputs=`单元输入`
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
- `stdin` 只给该 cell 的程序 stdin;
|
||||
- `input` 只给该 cell 的 `marqdo_input`;
|
||||
- 空值表示不提供;
|
||||
- 输入大小有上限,超限显式报错;
|
||||
- 静态导出使用同一张表,因此 view 与静态快照可以一致。
|
||||
|
||||
### 4.4 执行流水线
|
||||
|
||||
```text
|
||||
evaluate 会话 handle
|
||||
→ open kernels
|
||||
→ apply values
|
||||
→ apply cell inputs
|
||||
→ run cell
|
||||
→ record {stdout, stderr, input_echo, result}
|
||||
→ next cell
|
||||
```
|
||||
|
||||
失败不终止整个 Run All;错误写入 cell record,journal 保留。
|
||||
|
||||
---
|
||||
|
||||
## 5. G1/G2:持久内核 stdin 与每 cell 输入
|
||||
|
||||
### 5.1 问题
|
||||
|
||||
当前持久内核的 worker 用 stdin 传输 JSON 控制协议,因此程序自己的 stdin 不可用;`marqdo_input` 只是 JSON 变量,不是 stdin。
|
||||
|
||||
### 5.2 方案 A(推荐):控制通道与程序 stdin 分离
|
||||
|
||||
- Unix:父进程创建 **socketpair**(或两个 pipe),worker 通过 fd 3/4 读写控制帧;程序 stdin 使用单独的 pipe。
|
||||
- Windows:named pipe 或可继承的匿名 pipe 作为控制通道;程序 stdin 单独 pipe。
|
||||
- worker 协议升级为 `protocol: 2`:
|
||||
- 控制帧:`eval` / `set` / `get` / `interrupt` / `close`
|
||||
- eval 帧可带 `stdin`(UTF-8)或 `stdin_b64`(二进制,后续)
|
||||
- Python worker:每次 eval 前把 `sys.stdin` 替换为 `io.TextIOWrapper`/`StringIO`,eval 后恢复控制通道;用户代码读到的是真正的 stdin。
|
||||
- Node worker:控制 readline 移到控制 pipe;每次 eval 把 `process.stdin` 替换为 `PassThrough`/`Readable`,eval 后恢复。
|
||||
- 超时/中断关闭该次 stdin,不污染下一次 eval。
|
||||
|
||||
### 5.3 方案 B(降级):只支持 `input`
|
||||
|
||||
如果控制通道暂不实现,持久内核只支持 `input`,并显式拒绝 raw stdin:
|
||||
|
||||
```text
|
||||
persistent kernel stdin is unavailable; use input= or stateless cells
|
||||
```
|
||||
|
||||
不能静默把 stdin 变成 `marqdo_input`。
|
||||
|
||||
### 5.4 方案 C:stdin cell 降级为一次性
|
||||
|
||||
持久会话中遇到 raw stdin 时,用一次性进程执行该 cell;明确标记 `state: none`,不假装内核态连续。
|
||||
|
||||
### 5.5 UI 与静态
|
||||
|
||||
- `view`:每个代码卡提供 **Cell stdin** 小输入框,或者页面级输入表;推荐每 cell,因为它们经常不同。
|
||||
- 静态:读取 `inputs` 表;没有输入时显示“requires stdin”说明,而不是 traceback。
|
||||
- Run All 使用每 cell 的输入;不再把一个页面级 stdin 复制给所有 cell。
|
||||
|
||||
### 5.6 验收
|
||||
|
||||
- Python 与 Node 持久内核都能读取真实 stdin;
|
||||
- 同一个 cell 连续 eval 不串输入;
|
||||
- 超时/中断后下一次 eval 仍可读 stdin;
|
||||
- 无状态 cell 行为不变;
|
||||
- 静态快照使用相同输入表,结果与 live 一致(在相同输入下)。
|
||||
|
||||
---
|
||||
|
||||
## 6. G3:动态 plan 的边界
|
||||
|
||||
### 6.1 问题
|
||||
|
||||
`foreign.session` 目前只识别 entry 顶层的 `会话` 绑定。分支、函数、运行时循环中定义的 plan 不会被 view 发现。
|
||||
|
||||
### 6.2 设计决定(建议)
|
||||
|
||||
**v3 不支持任意控制流中的 plan。** 这是有意的语义边界:
|
||||
|
||||
- plan 是文档的声明,不是程序运行时的副作用;
|
||||
- view 不应为了找 plan 而执行 `# main`;
|
||||
- 避免 view 再次长出一套“运行程序再猜计划”的隐式逻辑。
|
||||
|
||||
允许的动态形式:
|
||||
|
||||
- 顶层赋值右侧的纯表达式,包括引入的纯函数;
|
||||
- `foreign.session` 的 tables/values 可以由顶层表函数计算;
|
||||
- 运行时变化通过 G4 的显式 session API 完成。
|
||||
|
||||
**不支持**:
|
||||
|
||||
- `##` 函数内部的 plan;
|
||||
- `if`/`while` 分支里的 plan;
|
||||
- 依赖 `# main` 副作用才能得到的 plan。
|
||||
|
||||
### 6.3 诊断
|
||||
|
||||
如果源码中出现非顶层 `foreign.session`,给出:
|
||||
|
||||
```text
|
||||
foreign.session: plan must be a top-level binding (会话 = > foreign.session ...)
|
||||
```
|
||||
|
||||
而不是静默降级为无状态。
|
||||
|
||||
---
|
||||
|
||||
## 7. G4:运行时更新 plan
|
||||
|
||||
### 7.1 目标
|
||||
|
||||
已打开的 view session 允许用户显式修改 cell 归属、增加/移除 cell、更新内核变量;所有修改都要可追踪。
|
||||
|
||||
### 7.2 API
|
||||
|
||||
```text
|
||||
foreign.session_assign session=<handle> cell="计算" kernel="复核"
|
||||
foreign.session_add_cell session=<handle> cell="新单元" kernel="分析"
|
||||
foreign.session_remove_cell session=<handle> cell="旧单元"
|
||||
foreign.session_set_value session=<handle> kernel="分析" name="rate" value=0.08
|
||||
```
|
||||
|
||||
所有操作:
|
||||
|
||||
- 校验 cell/kernel 语言;
|
||||
- 递增 `generation`;
|
||||
- 写入 journal(kind=plan_change / value_change);
|
||||
- 标记受影响 cell 为 `dirty`;
|
||||
- 失败不改变 handle。
|
||||
|
||||
### 7.3 View
|
||||
|
||||
- 内核下拉复用 `session_assign`;
|
||||
- 增加/删除 cell 放在显式菜单,不做隐式拖拽写入源码;
|
||||
- UI 显示 generation / dirty 状态。
|
||||
|
||||
### 7.4 静态
|
||||
|
||||
静态快照不执行变更;它记录变更后的 plan,或在构建时执行一次并固化。
|
||||
|
||||
---
|
||||
|
||||
## 8. G5:kernel interrupt
|
||||
|
||||
### 8.1 API
|
||||
|
||||
```text
|
||||
foreign.session_interrupt id=<session-id>
|
||||
```
|
||||
|
||||
### 8.2 行为
|
||||
|
||||
- 控制通道发送 `interrupt`;
|
||||
- worker 取消当前 eval,返回 `{ok:false, interrupted:true}`;
|
||||
- 保留已完成的值和 journal;
|
||||
- 状态从 `running` → `interrupted`;
|
||||
- 下一次 eval 可以继续使用内核(除非进程已损坏);
|
||||
- 超时继续作为最后一道防线。
|
||||
|
||||
### 8.3 View
|
||||
|
||||
- 工具栏增加 Interrupt;执行中的 cell 显示 interrupted;
|
||||
- 不自动重跑;
|
||||
- 静态导出没有 interrupt(快照不执行)。
|
||||
|
||||
### 8.4 跨平台
|
||||
|
||||
Unix:进程组信号 + 控制帧;Windows:控制帧 + `taskkill /T` fallback。两者都必须有测试。
|
||||
|
||||
---
|
||||
|
||||
## 9. G6:状态持久化与 replay
|
||||
|
||||
### 9.1 不做的事
|
||||
|
||||
- 不做 Python pickle / Node 堆快照;
|
||||
- 不做任意对象反序列化;
|
||||
- 不把内核内存默认写进 `.mq.md`。
|
||||
|
||||
### 9.2 显式快照
|
||||
|
||||
```text
|
||||
foreign.session_export session=<handle> path=".marqdo/sessions/doc-1.json"
|
||||
foreign.session_import path=".marqdo/sessions/doc-1.json"
|
||||
```
|
||||
|
||||
快照只包含:
|
||||
|
||||
```text
|
||||
{
|
||||
version: 1,
|
||||
document_hash: "...",
|
||||
plan_hash: "...",
|
||||
kernels: [{name, lang, cmd, values: {...}}],
|
||||
cells: [{name, kernel, status, last_ok, last_error}],
|
||||
journal: [...],
|
||||
inputs: [...]
|
||||
}
|
||||
```
|
||||
|
||||
值只允许 JSON 可表达的 Marqdo 值;不可序列化的值显式失败。
|
||||
|
||||
### 9.3 replay
|
||||
|
||||
```text
|
||||
foreign.session_replay path="..." verify=True
|
||||
```
|
||||
|
||||
按 journal 顺序重放 cell + inputs,比较 stdout/status;差异写入 report。replay 不覆盖原 journal,除非显式 `append`。
|
||||
|
||||
### 9.4 存储
|
||||
|
||||
- 默认目录 `.marqdo/sessions/`(gitignore 可选);
|
||||
- 用户可通过 path 放到受控目录;
|
||||
- 不默认提交,不默认写源码。
|
||||
|
||||
---
|
||||
|
||||
## 10. G7:跨文档内核(Deferred / future)
|
||||
|
||||
> **状态:已移出 v3 当前实现目标。** 本节设计保留,作为后续版本(v4 或独立 session-scope 工作)的输入;当前不承诺 API 或兼容性。
|
||||
|
||||
### 10.1 原则
|
||||
|
||||
- 默认每文档独立;
|
||||
- 跨文档必须显式 `scope=` / `space=`;
|
||||
- 不自动按变量名或路径共享。
|
||||
|
||||
### 10.2 API
|
||||
|
||||
```text
|
||||
foreign.session_open lang="python" scope="shared:analytics"
|
||||
foreign.session_list scope="shared:analytics"
|
||||
foreign.session_close id=... scope=...
|
||||
```
|
||||
|
||||
- scope 注册表由 foreign runtime 管理;
|
||||
- 同名冲突报错,不覆盖;
|
||||
- view 只能打开当前文档声明允许的 scope;
|
||||
- 生命周期由 owner/refcount 管理,最后一个引用关闭时清理。
|
||||
|
||||
### 10.3 安全
|
||||
|
||||
- 跨文档共享可能违反文档隔离,必须 capability + 显式配置;
|
||||
- journal 标记 scope;
|
||||
- 静态导出默认不打开跨文档 scope。
|
||||
|
||||
---
|
||||
|
||||
## 11. G8:非 Python/Node 持久内核(Deferred / future)
|
||||
|
||||
> **状态:已移出 v3 当前实现目标。** 本节设计保留,等待目标语言与 worker 适配器确定后再实现;当前不承诺 API。
|
||||
|
||||
### 11.1 模型
|
||||
|
||||
不是所有语言都需要持久内核。`LangSpec` 增加能力标志:
|
||||
|
||||
```text
|
||||
session: none | protocol_v2
|
||||
```
|
||||
|
||||
- `none`:只能 `run` / `invoke` 一次性;
|
||||
- `protocol_v2`:实现控制通道与 eval 协议,可以 `session_open`。
|
||||
|
||||
### 11.2 适配器
|
||||
|
||||
Go 等语言通过一个薄 worker 实现:
|
||||
|
||||
```text
|
||||
control frame: eval {code, stdin, input}
|
||||
result frame: {ok, stdout, stderr, result, error}
|
||||
```
|
||||
|
||||
不允许“看起来像持久内核、实际每次重启”的假实现。
|
||||
|
||||
### 11.3 失败语义
|
||||
|
||||
- `session_open` 对 `session: none` 的语言明确报错;
|
||||
- `foreign.session` 的 plan 只能使用支持 session 的语言;
|
||||
- 静态/无状态仍可使用一次性执行。
|
||||
|
||||
---
|
||||
|
||||
## 12. G9:live → static 输入捕获
|
||||
|
||||
### 12.1 问题
|
||||
|
||||
静态构建在构建环境执行,无法知道用户在 live view 中临时输入的 stdin;同一文档的结果可能不同。
|
||||
|
||||
### 12.2 设计
|
||||
|
||||
增加显式的“捕获快照”:
|
||||
|
||||
```text
|
||||
view → Capture snapshot → .marqdo/snapshots/<doc>.view.json
|
||||
```
|
||||
|
||||
快照内容:
|
||||
|
||||
- document source hash;
|
||||
- session plan(kernels/cells/values);
|
||||
- 每 cell 的 stdin/input;
|
||||
- 每 cell 的 stdout/stderr/status;
|
||||
- journal 摘要、语言/解释器版本;
|
||||
- 捕获时间。
|
||||
|
||||
静态导出:
|
||||
|
||||
```text
|
||||
marqdo view output --snapshot .marqdo/snapshots/doc.view.json
|
||||
```
|
||||
|
||||
优先使用快照中的记录,校验 source hash,不重新执行;若 hash 不匹配,显式失败或 `--execute` 重跑。
|
||||
|
||||
### 12.3 安全/隐私
|
||||
|
||||
- 快照可能包含 secrets;默认不提交、不发布;
|
||||
- 提供 `redact` 字段/正则;
|
||||
- 静态页面只发布脱敏后的快照。
|
||||
|
||||
### 12.4 验收
|
||||
|
||||
- live 中成功的结果可以在静态页面原样显示;
|
||||
- 不捕获内核内存,只捕获输入/输出/状态;
|
||||
- 没有快照时回退到构建时执行,行为明确。
|
||||
|
||||
---
|
||||
|
||||
## 13. G10:自动 writeback
|
||||
|
||||
### 13.1 原则
|
||||
|
||||
**“自动”必须是用户显式选择的策略,不是默认副作用。**
|
||||
|
||||
### 13.2 API
|
||||
|
||||
```text
|
||||
foreign.session persist=`写回策略`
|
||||
```
|
||||
|
||||
策略表:
|
||||
|
||||
```mq.md
|
||||
`写回策略` =
|
||||
| 单元 | key |
|
||||
|------|-----|
|
||||
| 计算 | total |
|
||||
| 复核 | check |
|
||||
```
|
||||
|
||||
或 view 的 **Persist results** 按钮:将当前 cell 结果写到 `writeback.record key=...`。
|
||||
|
||||
### 13.3 语义
|
||||
|
||||
- 默认不写源码;
|
||||
- 显式策略只在 **用户点击 Persist** 或 `marqdo run --writeback` 时执行;
|
||||
- 静态构建默认不写回;`--writeback` 必须显式;
|
||||
- writeback 只支持 JSON 可表达值;
|
||||
- 写入位置/格式仍由 `writeback` 库决定。
|
||||
|
||||
### 13.4 与静态快照的关系
|
||||
|
||||
- 静态快照是只读发布;
|
||||
- writeback 是源码内的活结果;
|
||||
- 两者可以共存,但不能互相隐式触发。
|
||||
|
||||
---
|
||||
|
||||
## 14. API / 端点汇总
|
||||
|
||||
### 14.1 新增 foreign 函数
|
||||
|
||||
```text
|
||||
foreign.session inputs=
|
||||
foreign.session_assign
|
||||
foreign.session_add_cell
|
||||
foreign.session_remove_cell
|
||||
foreign.session_set_value
|
||||
foreign.session_interrupt
|
||||
foreign.session_export
|
||||
foreign.session_import
|
||||
foreign.session_replay
|
||||
foreign.session_open scope=
|
||||
foreign.session_list scope=
|
||||
```
|
||||
|
||||
### 14.2 View API
|
||||
|
||||
```text
|
||||
POST /api/session/cell/run { cell, stdin }
|
||||
POST /api/session/run_all { restart, inputs? }
|
||||
POST /api/session/cell/clear
|
||||
POST /api/session/plan/assign
|
||||
POST /api/session/plan/add
|
||||
POST /api/session/plan/remove
|
||||
POST /api/session/plan/value
|
||||
POST /api/session/interrupt
|
||||
POST /api/session/snapshot/capture
|
||||
```
|
||||
|
||||
所有端点只操作 foreign 句柄;view 不直接读写内核。
|
||||
|
||||
### 14.3 CLI
|
||||
|
||||
```text
|
||||
marqdo view output --snapshot FILE
|
||||
marqdo view output --execute
|
||||
marqdo view output --no-exec
|
||||
marqdo run --writeback
|
||||
```
|
||||
|
||||
不新增 `marqdo notebook`。
|
||||
|
||||
---
|
||||
|
||||
## 15. 语义矩阵
|
||||
|
||||
| 能力 | run | view | static |
|
||||
|---|---|---|---|
|
||||
| `foreign.session` plan | 作为普通值执行 | 消费句柄 | 可执行或快照 |
|
||||
| raw stdin | 支持(一次性/session) | 每 cell | inputs 表/快照 |
|
||||
| interrupt | 无 UI | 可调用 | 不可用 |
|
||||
| state export | 可调用 | 可显式导出 | 不导出或快照 |
|
||||
| cross-doc(deferred) | 设计保留 | 设计保留 | 设计保留 |
|
||||
| writeback | `--writeback` | 显式按钮 | 默认不写 |
|
||||
|
||||
---
|
||||
|
||||
## 16. 实施顺序
|
||||
|
||||
### P0(先做,直接影响真实使用)
|
||||
|
||||
1. **G1/G2 stdin**:控制通道 + 每 cell 输入表 + UI。
|
||||
2. **G5 interrupt**:避免只能等超时。
|
||||
3. **G9 snapshot capture**:解决 live/static 不一致。
|
||||
|
||||
### P1
|
||||
|
||||
4. **G4 runtime plan updates**。
|
||||
5. **G6 export/replay**。
|
||||
|
||||
### P2
|
||||
|
||||
6. **G3 dynamic plan 边界**:按第 6 节,只做顶层纯表达式;任意控制流不承诺。
|
||||
7. **G10 explicit writeback policy**。
|
||||
|
||||
### Deferred(不在当前目标)
|
||||
|
||||
- **G7 cross-document scope**:设计保留,后续版本再开发。
|
||||
- **G8 non-Python/Node persistent adapters**:设计保留,等待目标语言与 worker。
|
||||
|
||||
---
|
||||
|
||||
## 17. 测试设计
|
||||
|
||||
### 单元
|
||||
|
||||
- `stdin` 协议:空输入、大输入、超时、中断、连续 eval;
|
||||
- 每 cell 输入隔离;
|
||||
- 返回值锚定在调用点(已修复的 CallFrame.call_line);
|
||||
- 表格不产生 call chip(已修复);
|
||||
- plan top-level 诊断;
|
||||
- session generation / dirty;
|
||||
- export/import/replay 校验。
|
||||
|
||||
### 集成
|
||||
|
||||
- Python 持久内核读 `sys.stdin`;
|
||||
- Node 持久内核读 `process.stdin`;
|
||||
- view Run All 使用每 cell 输入;
|
||||
- interrupt 后下一次 eval 正常;
|
||||
- static snapshot 与 live 结果一致;
|
||||
- snapshot hash 不匹配显式失败;
|
||||
- cross-doc scope 冲突/清理;
|
||||
- Go 一次性 vs 持久能力诊断;
|
||||
- writeback 只显式写入。
|
||||
|
||||
### 静态
|
||||
|
||||
- 输出无 traceback;
|
||||
- 没有输入时显示说明而非伪造;
|
||||
- 多内核 controls 显示;
|
||||
- writeback slot 单块、暗色主题;
|
||||
- 静态按钮提示。
|
||||
|
||||
---
|
||||
|
||||
## 18. 兼容与迁移
|
||||
|
||||
- 现有 `foreign.session kernels= cells= values=` 保持兼容;
|
||||
- 新 `inputs=` 可选;
|
||||
- `session_open` 旧协议继续可用;v2 控制通道通过 handshake 协商;
|
||||
- 旧页面没有 `inputs` 时仍按空 stdin 执行/显示说明;
|
||||
- 不修改已发布的 v1.5.0 tag;v3 以新版本发布。
|
||||
|
||||
---
|
||||
|
||||
## 19. 需要拍板的决策
|
||||
|
||||
1. **G1**:是否接受控制通道与程序 stdin 分离的协议改造?否则只能保留 `input`,不能宣称 raw stdin。
|
||||
2. **G3**:是否接受“plan 必须是顶层声明”的边界?若不接受,需要定义 view 可安全调用的 plan 入口,风险更高。
|
||||
3. **G6**:状态快照只允许 JSON 值,是否可接受?不做任意对象序列化。
|
||||
4. **G9**:快照文件是否默认放在 `.marqdo/snapshots/` 且不提交?涉及 secrets。
|
||||
5. **G10**:自动 writeback 是否只允许显式按钮/flag,而不是每次运行自动写源码?
|
||||
|
||||
---
|
||||
|
||||
## 20. 当前目标范围
|
||||
|
||||
v3 当前实现目标为:**G1、G2、G3、G4、G5、G6、G9、G10**。
|
||||
|
||||
**G7、G8 已移出当前目标**,但设计文档保留在本文件第 10、11 节,供后续开发;它们不计入 v3 完成条件,也不影响现有 API 的兼容性承诺。
|
||||
|
||||
## 21. 非目标
|
||||
|
||||
- 不新增 Markdown 标记;
|
||||
- 不新增 notebook CLI/模式;
|
||||
- 不把任意内核内存序列化;
|
||||
- 不默认修改 `.mq.md`;
|
||||
- 不自动镜像变量;
|
||||
- 不把 view 变成第二套解释器;
|
||||
- 不把“未实现”伪装成支持。
|
||||
|
||||
@@ -0,0 +1,306 @@
|
||||
# 语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留“正文优先、按需命名”的方向;下文语料统计和“具名给值缺失”等判断属于当时快照。当前已有具名实参;“调用即代入”不规定文本展开实现,也不禁止递归。下一阶段以[文档原生指导 §2–3](document-native-development-guide.md#2-语法审查的保留修正与暂缓)的范围和验收为准,本文不是替换整个函数模型的已批准语法提案。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 哲学层讨论**(不涉及实现,不含语法提案细节) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 命题来源 | 用户:「函数是复用、是对高度凝练内容的提炼加工;正常人不会说『计算 37 的两倍需要抽象一个函数』,而是直接说乘二」 |
|
||||
| 定位 | 本文只谈**语义表示**与**自然语言映射**,不谈编译器与语法糖 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 把你的观察写成三条命题
|
||||
|
||||
**命题一(现象)**:函数是一种**预先抽象**装置——必须在使用之前先把内容提炼并命名,还要声明它需要哪些输入。
|
||||
|
||||
**命题二(对照)**:自然语言是**即席描述**——先把事说清楚,只有在内容确实要反复出现时,才顺手给它一个名字("以上做法,我们称为…"),而且命名之后它可以像普通名词/动词一样被使用。
|
||||
|
||||
**命题三(结论)**:因此「函数」这套仪式与「代码即文档」错位。要解决的不是调用写法,而是**用什么语义表示来承担"复用"这件事**。
|
||||
|
||||
本文的答案先给出来:
|
||||
|
||||
> **Marqdo 需要的不是更好的"函数",而是把「函数」还原成「命名」,把「调用」还原成「代入」。**
|
||||
> 函数 = **一段被命名的正文**;参数 = **那段正文里尚未确定的量**;调用 = **把这些量代入后重述一遍**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 语料给出的证据:Marqdo 的 `##` 其实不是"过程"
|
||||
|
||||
统计 `lib/ ext/ examples/ tests/` 全部 1322 个 `##`:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 函数总数 | 1322 |
|
||||
| **纯返回式**(零可执行语句,只有一个返回表达式) | **765(57.9%)** |
|
||||
| 一行式(可执行行 ≤1 且返回 ≤1) | 935(70.7%) |
|
||||
| 极短(可执行行 ≤2) | 1162(87.9%) |
|
||||
| 较长(可执行行 ≥10) | 62(4.7%) |
|
||||
| 可执行语句数**中位数** | **0** |
|
||||
| 平均 | 2.2 |
|
||||
|
||||
典型代表:`## str_trim`、`## contains`、`## to_upper`——**一个名字包一个表达式**。
|
||||
|
||||
这说明:**人们用 `##` 在做"命名",语法却要求他们按"过程抽象"的仪式来做。**
|
||||
签名(`+ n`)、祈使式调用(`> f 1 2`)、返回值约定(`*…*`)全是过程语言的行头,
|
||||
而实际内容是"给这个式子起个名字"。
|
||||
|
||||
**水土不服不是感受,是可以量化的形式错配。**
|
||||
|
||||
### 1.1 按「语义功能」再分一次类
|
||||
|
||||
把 1322 个函数按内容形态归类(同一函数可能重叠,故按主特征优先):
|
||||
|
||||
| 形态 | 判据 | 数量 | 占比 | 自然语言对应 |
|
||||
|------|------|------|------|-------------|
|
||||
| **纯命名式** | 零语句、零副作用、零分支、零循环,只有一个返回式 | **754** | **57.0%** | 「所谓 X,是指…」 |
|
||||
| **条款式** | 有分支、无副作用 | 103 | 7.8% | 「凡…则…」 |
|
||||
| **遍历式** | 有循环、无副作用 | 26 | 2.0% | 「对每一项…」 |
|
||||
| **命令式** | 含 `print` 等副作用 | **83** | **6.3%** | 「打印…」祈使句 |
|
||||
| 线性计算(其余) | 有语句但无控制流/副作用 | 356 | 26.9% | 「先…再…」 |
|
||||
|
||||
两个结论:
|
||||
|
||||
1. **命名 + 条款 = 64.8%** —— 三分之二的 `##` 落在"定义"与"条款"两种自然语言形态里,
|
||||
而这两种恰好不需要"过程"语义(§4 立场甲、乙)。
|
||||
2. **真正的副作用只有 6.3%** —— 也就是说"命令/祈使"语义只是少数派,
|
||||
完全可以隔离成一小块(§8.1),不必让它污染整体读法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么"抽象"在文档里格外别扭:复用经济学
|
||||
|
||||
抽象不是免费的。它有三项成本:
|
||||
|
||||
| 成本 | 内容 |
|
||||
|------|------|
|
||||
| **定义成本** | 要写一次定义(名字、输入、边界) |
|
||||
| **跳转成本** | 读者看到名字,必须回到定义处才能理解(文档尤其致命:要翻页/滚动) |
|
||||
| **维护成本** | 定义改了,所有使用处语义随之变化 |
|
||||
|
||||
收益只有一项:**同一内容被复用 N 次时省下的重复**。
|
||||
|
||||
于是有:
|
||||
|
||||
> **抽象值得做 ⟺ 复用次数 × 内容复杂度 > 定义成本 + N × 跳转成本**
|
||||
|
||||
在**代码**里,N 往往很大、跳转成本低(IDE 跳转、同屏),所以抽象划算。
|
||||
在**文档**里,N 常常是 **1**,跳转成本高(读者在阅读流里被打断),于是:
|
||||
|
||||
> **文档中大量"函数"是负收益的**——它们只被用一次,却强迫读者回头查定义。
|
||||
|
||||
这解释了为什么你会有"正常人不会这么说话"的直觉:**说话的默认假设是对方不知道你的定义**,
|
||||
所以人话倾向于**就地展开**;而函数默认假设读者愿意跳转。
|
||||
|
||||
---
|
||||
|
||||
## 3. 自然语言里「复用」到底有几种形态
|
||||
|
||||
程序语言只承认其中一种(命名+参数化),这是错配的第二层。
|
||||
|
||||
| 形态 | 自然语言的样子 | 对应的程序装置 | Marqdo 现状 |
|
||||
|------|---------------|---------------|------------|
|
||||
| **重复** | 再说一遍 | 复制粘贴 | ✅ 允许 |
|
||||
| **指称** | 如上所述 / 同前 / 该金额 | 变量、引用 | ✅ `` `名` `` |
|
||||
| **命名** | 所谓 X,是指…;以下称 X | 定义 / 函数 | ✅ `## X` |
|
||||
| **条款** | 凡…则…;若…应… | 条件分支、规则 | ✅ `1. 2. 3.` |
|
||||
| **范例** | 以 37 为例 | 样例/测试 | ⚠️ 仅测试目录 |
|
||||
| **表格/清单** | 见下表;用料如下 | 数据、查表 | ✅ 表格 |
|
||||
|
||||
**关键发现**:命名只是六分之一,但程序语言把它变成了**唯一的复用入口**。
|
||||
而文档写作里,**指称("该金额")与条款("凡…则…")比命名更常用**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 三种候选语义表示(哲学立场)
|
||||
|
||||
要"代替水土不服",必须给出**语义模型**,而不只是换个写法。三个候选:
|
||||
|
||||
### 立场甲:定义—代入(Definition & Substitution)
|
||||
|
||||
**语义**:一段正文被命名 → 成为一个**定义**。使用它 = 把定义里的自由量按**角色**代入,再重述。
|
||||
|
||||
```markdown
|
||||
## 加倍
|
||||
|
||||
把 `x` 乘以二,得 *y*
|
||||
```
|
||||
|
||||
使用(语义读法):**按「加倍」代入 x=37,得 74。**
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅ 「依定义」「按…计算」「所谓…是指…」——学术与说明文的主力 |
|
||||
| 与 Marqdo 契合 | ✅ `##`/`#` 本来就是标题(文档结构),天然是"定义"的载体 |
|
||||
| 参数观 | ✅ 角色(具名),不是位置占位符 |
|
||||
| 复用单位 | ✅ **文本段落本身**(文档即单位,符合"代码即文档") |
|
||||
| 71% 的现有一行式函数 | ✅ 直接就是"命名的表达式",无需过程仪式 |
|
||||
| 缺点 | 定义与使用分离,仍有跳转成本(但可用"就地展开"缓解,见 §5) |
|
||||
|
||||
### 立场乙:条款—援引(Clause & Citation)
|
||||
|
||||
**语义**:条件 → 结论。使用 = 援引条款并给出适用的事实。
|
||||
|
||||
```markdown
|
||||
## 计费规则
|
||||
|
||||
若 `里程` 超过 100 公里,则 `费用` 按 8 折计。
|
||||
```
|
||||
使用(语义读法):**本单里程 120 公里,依「计费规则」,费用按 8 折。**
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅✅ 「凡…则…」是中文说明文/法条/规章的骨架 |
|
||||
| 与 Marqdo 契合 | ✅ `1. 2. 3.` 分支已经就是条款形式 |
|
||||
| 缺点 | 数值计算写成条款别扭("把 37 乘以二"不是条款) |
|
||||
|
||||
### 立场丙:配方—配料(Recipe & Ingredients)
|
||||
|
||||
**语义**:一张用料表 + 一段做法。参数 = 配料表中的行。
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 自然语言对应 | ✅ 菜谱、工艺卡、表单 |
|
||||
| 与 Marqdo 契合 | ✅✅ 表格优先正是 Marqdo 的特色;契约表已是雏形 |
|
||||
| 缺点 | 表达力弱;无法递归、无法组合;"给值"变成填表 |
|
||||
|
||||
### 取舍
|
||||
|
||||
| | 甲 代入 | 乙 条款 | 丙 配料 |
|
||||
|---|---|---|---|
|
||||
| 覆盖"命名表达式"(58% 的现状) | ✅✅ | ⚠️ | ❌ |
|
||||
| 覆盖"条件规则" | ⚠️ | ✅✅ | ❌ |
|
||||
| 覆盖"数值流程" | ✅ | ❌ | ⚠️ |
|
||||
| 可读性 | 高 | 最高 | 最高(但最弱) |
|
||||
| 与 `##` 结构一致 | ✅ | ✅ | ⚠️ 表为主 |
|
||||
|
||||
**推荐:以甲为主,乙作为甲内部的一种段落形态。** 理由见 §6。
|
||||
|
||||
---
|
||||
|
||||
## 5. 「代入」为什么比「调用」更贴自然语言
|
||||
|
||||
这不是文字游戏,三处实质差异:
|
||||
|
||||
| 维度 | 调用(invocation) | 代入(substitution) |
|
||||
|------|-------------------|---------------------|
|
||||
| 读者的心理动作 | "跳过去,看它做什么,再回来" | "把这个式子代进去" |
|
||||
| 输入的意义 | 实参 → 形参(两套名字) | 角色 → 定义里的同一个名字(**一套名字**) |
|
||||
| 结果的意义 | 函数返回了一个值 | 式子变成了具体结果 |
|
||||
| 出现位置 | 必须是独立语句或表达式 | 可以**嵌在叙述里**("加倍后为 74 件") |
|
||||
| 一次性使用 | 仍要付出定义+跳转成本 | 可以**不定义,直接展开**(§5.1) |
|
||||
|
||||
### 5.1 关键:抽象要能被"取消"
|
||||
|
||||
自然语言的强大在于**可省略**:能一句话说清就不起名字。
|
||||
所以语义模型必须允许同一件事有**两种粒度**,并可以随时在两者之间移动:
|
||||
|
||||
| 粒度 | 写法(示意) | 何时用 |
|
||||
|------|-------------|--------|
|
||||
| **就地描述** | 把 37 乘以二,得 74 | 只用一次 |
|
||||
| **命名后代入** | 按「加倍」代入 x=37,得 74 | 复用多次 |
|
||||
|
||||
而且**提升与展开都是作者的编辑动作,不是必须的入口**。
|
||||
这正是"抽象可选"——今天的函数是"必须先抽象",这是错配的第三层。
|
||||
|
||||
### 5.2 与 58% 纯表达式函数的对应
|
||||
|
||||
`## to_upper` 这类函数,用"代入"读就是:
|
||||
|
||||
> 「to_upper 的定义是:把 `s` 变成全大写。」使用:`to_upper` 代入 s="abc" 得 "ABC"。
|
||||
|
||||
它读起来是一个**定义 + 一次代入**,而不是"调用一个过程"。这与它的实际内容(一个表达式)一致。
|
||||
|
||||
---
|
||||
|
||||
## 6. 这套语义如何落到 Marqdo 已有的东西上
|
||||
|
||||
| 自然语言的成分 | Marqdo 已有载体 | 需不需要新东西 |
|
||||
|---------------|----------------|---------------|
|
||||
| 命名(给出定义) | `#` / `##` 标题 | ❌ 已有 |
|
||||
| 正文(定义的内容) | 叙述 + 标记代码 | ❌ 已有 |
|
||||
| 未确定的量(角色) | 体推断出来的形参(v0.3 已有) | ❌ 已有 |
|
||||
| 角色的**具名给值** | (缺失) | ✅ **这是唯一真正缺的一环** |
|
||||
| 结论(得…) | `*…*` 返回 | ❌ 已有 |
|
||||
| 条款(凡…则…) | `1. 2. 3.` 分支 | ❌ 已有 |
|
||||
| 配料表 | GFM 表格 + 契约表 | ❌ 已有 |
|
||||
| 引用(依…) | (缺失) | ⚠️ 与"具名给值"是同一件事 |
|
||||
|
||||
**结论:缺的只有一件事——「具名给值」的形式。**
|
||||
|
||||
也就是说:语义模型(代入)几乎不用改,语法只缺一个"把角色填上"的最小约定。
|
||||
这把问题从"要不要重新设计函数"缩小到"这一个小约定怎么长得最不刺眼"。
|
||||
|
||||
---
|
||||
|
||||
## 7. 不可回避的哲学难题:自然性 vs 可判定性
|
||||
|
||||
自然语言判断"哪些量要代入"靠**语境**(前文、常识、指代)。
|
||||
编译器不能。所以必须有一条**显式约定**,无法省掉。
|
||||
|
||||
三种可能的约定形态(只列哲学性质,不列语法细节):
|
||||
|
||||
| 形态 | 自然的程度 | 可判定的程度 | 风险 |
|
||||
|------|-----------|-------------|------|
|
||||
| **角色必须具名给出** | 中(像"按定义,其中 x=37") | ✅ 完全可判定 | 略啰嗦 |
|
||||
| **靠语序(位置)** | 高 | ✅ 可判定 | ❌ 已实测:叙述顺序一变,绑定就翻转(见 call-syntax-from-marks.md §4.3) |
|
||||
| **靠语境(隐式)** | 最高 | ❌ 不可判定 | ❌ 130 个形参名撞车 |
|
||||
|
||||
**这是整件事的硬边界**:越像人话,越难判定。Marqdo 必须选"具名"这一档——
|
||||
它是**唯一同时可读且可判定**的点。
|
||||
|
||||
而这也解释了为什么"叙述式动词"(`执行`)不可取:它把判定交给了一个**未标记的词**,
|
||||
既没有自然的程度优势,又破坏了"叙述安全"。
|
||||
|
||||
---
|
||||
|
||||
## 8. 三个尚未解决的哲学问题
|
||||
|
||||
这些是真问题,需要后续立场,不宜草率定:
|
||||
|
||||
1. **副作用怎么办?**
|
||||
"把 37 乘以二"是纯代入;"打印 74"呢?打印**改变世界**,不是代入。
|
||||
→ 副作用可能必须停留在"命令"语义(今天的 `> print`),
|
||||
而这会让文档里同时存在"代入"与"命令"两套读法。这是否可接受?
|
||||
|
||||
2. **递归与自引用怎么办?**
|
||||
代入是有限展开;递归是无限展开。若坚持代入选义,递归就不可表达。
|
||||
→ 是否接受"Marqdo 不支持递归"?还是给递归单独一套"过程"语义?
|
||||
|
||||
3. **定义的时序怎么办?**
|
||||
自然语言允许先使用后定义("如上,我们称之为…")。代入语义要求定义先存在。
|
||||
→ 是否允许前向引用(读者先看到 `加倍`,后面才看到定义)?
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话总结与建议
|
||||
|
||||
> **Marqdo 的问题不是"函数不好用",而是"函数是过程语言留给文档的遗产"。**
|
||||
> 文档需要的不是过程,是**命名**;不是**调用**,是**代入**。
|
||||
|
||||
建议的语义立场(待你裁决):
|
||||
|
||||
| 项 | 建议 |
|
||||
|----|------|
|
||||
| 复用单位 | **一段被命名的正文**(而非过程) |
|
||||
| 参数观 | **正文中未确定的量**(角色,具名) |
|
||||
| 调用观 | **代入**(可读作"按…代入…") |
|
||||
| 抽象时机 | **可选提升**:默认就地展开,需要复用时才命名 |
|
||||
| 唯一新增约定 | **具名给值**(形态待定,但必须具名,理由见 §7) |
|
||||
| 保留"命令"语义 | 仅用于副作用(`print` 等),与"代入"分层 |
|
||||
| 条款 | 作为定义的一种段落形态(`凡…则…`),不另设机制 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你裁决
|
||||
|
||||
1. **是否接受"函数→命名 / 调用→代入"这个总重构?**
|
||||
若接受,后续所有语法讨论都在这条轴上做取舍。
|
||||
2. **§8 的三个难题**你的倾向是什么(尤其"是否接受不支持递归")?
|
||||
3. **"具名给值"的最小形态**:你更接受哪一种读感?
|
||||
- `**加倍(x=37)**`(像函数调用)
|
||||
- `按**加倍**,`x`=37`(像句子,但需要判定规则)
|
||||
- 表格给出角色(像配料表)
|
||||
4. 是否需要我把这份哲学立场,反向校验一遍**现有 1322 个函数**——
|
||||
看有多少在"命名表达式"框架下会更自然、多少必须保留"过程"语义?
|
||||
@@ -0,0 +1,337 @@
|
||||
# 语义探析:代码函数能否解释为一张 GFM 表
|
||||
|
||||
> **2026-10-23 审阅裁决**:下文 v1.5.2 实验不替代当前回归。保留现有数据表几何与契约表角色,不重复声明参数;“现有实现不支持函数表”不等于表格不能表达计算。有限决策表和生成式签名视图按真实用例评估,见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「`## 函数名` + `+ 参数` + 函数体,从某种角度能否解释成 GFM 表」 |
|
||||
| 方法 | 11 组运行时实验(1.5.2)+ 5 份设计/路线图文档考古 |
|
||||
| 相邻 | [functions-as-values-evaluation.md](functions-as-values-evaluation.md) · [link-style-call-evaluation.md](link-style-call-evaluation.md) |
|
||||
| 关键前置 | [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [objects.md](objects.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话答案
|
||||
|
||||
**你的命题在 Marqdo 里已经实现了——但它实现的是「关于函数的表」,不是「函数本身」。**
|
||||
|
||||
```
|
||||
## 加一
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| n | number | 输入值 |
|
||||
|
||||
*n+1*
|
||||
```
|
||||
|
||||
这张表**今天就能跑**,是既有特性(契约表,`tests/contracts/ok_contract.mq.md`)。
|
||||
它证明了:函数参数**确实可以**是一张 GFM 表。
|
||||
|
||||
但它只能**描述**参数,不能**声明**参数;它不含函数体,不决定 arity,也不能被调用。
|
||||
一句话划界:
|
||||
|
||||
> **表能描述外延(输入→结果)与签名(元数据),不能描述内涵(怎么算)。**
|
||||
> 而「调用」恰恰是内涵操作。
|
||||
> `[k](集合)` 是**投影已有数据**,`f(x)` 是**计算新数据**——
|
||||
> 只有 f 本身已经是「预先枚举好的表函数」时,两者才重合。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先固定事实:Marqdo 的表格几何(实测)
|
||||
|
||||
讨论前必须先把「表」的语义钉死,否则会建在错觉上。
|
||||
|
||||
| 形状 | 绑定结果 | 实验 |
|
||||
|------|---------|------|
|
||||
| 1 列 N 行 | `List`(列值) | 文档锁定 + 实测 |
|
||||
| ≥2 列 **1 行** | `Map`(表头→标量,即「记录」) | `{"档位":[1,2]}` 反例 → 单行才是记录 |
|
||||
| ≥2 列 **N 行** | `Map`(表头→**列列表**,列向聚合) | 实测 `{"档位":[1,2],"税率":[0.03,0.1]}` |
|
||||
| 首列标头为 `行` / `@` / `row` | `List[Map]`(**行向记录**,显式开启) | [tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 |
|
||||
|
||||
**关键点**:Marqdo 的默认是**列向**。多行多列表不是「一组记录」,
|
||||
而是「一列一个列表」。行向记录是**显式标记**才能开的形态,
|
||||
文档原话:「**不得**与默认列向字典静默混用」。
|
||||
|
||||
这一条直接决定了「行 = 参数」在 Marqdo 里**不是自然形态**:
|
||||
按默认几何,`| 参数 | 类型 |` 两行参数会变成
|
||||
`{"参数":["a","b"], "类型":["number","number"]}` —— 列向。
|
||||
|
||||
---
|
||||
|
||||
## 2. 你的命题已经存在:契约表
|
||||
|
||||
`src/contract.rs:308` 的注释写得很清楚:
|
||||
|
||||
```
|
||||
/// 未绑定文档表(`Expr::Map`)→ 契约块。
|
||||
/// - `None`:非契约形状(普通数据/说明表,原样保留)。
|
||||
/// - `Some(Err)`:契约形状但畸形 —— 必产诊断。
|
||||
/// - `Some(Ok)`:合法契约(`参数`/`返回`/`字段` 三形状之一,须含 `类型` 列)。
|
||||
```
|
||||
|
||||
三条规则(`src/contract.rs:260-334`):
|
||||
|
||||
| 规则 | 实现 |
|
||||
|------|------|
|
||||
| 表头含 `参数`/`形参`/`param`/`arg` → 形参契约 | `PARAM_HEADERS` |
|
||||
| 表头含 `返回`/`return`/`result` → 返回契约 | `RETURN_HEADERS` |
|
||||
| **必须含 `类型` 列**,否则视为普通说明表 | `TYPE_HEADERS` 缺失 → `return None` |
|
||||
|
||||
也就是说:**「函数参数表」不仅可能,而且已经是正式语法**。
|
||||
第一列标头(`参数` / `返回` / `字段`)扮演的正是
|
||||
[tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 里
|
||||
`行`/`@`/`row` 那种**形态标记**的角色:显式声明「这张表是干什么用的」。
|
||||
|
||||
---
|
||||
|
||||
## 3. 但它是「关于参数的表」,不是「参数本身」
|
||||
|
||||
11 组实验里最关键的 6 组(全部实跑):
|
||||
|
||||
| # | 写法 | 实测结果 | 说明 |
|
||||
|---|------|---------|------|
|
||||
| E1 | 参数表列 `n`,函数体不读 `n` | `> f` 无参调用**成功**,`n` 不是形参 | 表不能声明形参 |
|
||||
| E3 | 叙述声明 `n` + 参数表 + 传 `"七"` | `参数 n 期望 number,实际 text(契约校验)` | **表能校验** |
|
||||
| E4 | 叙述声明 `n`,**无表** + 传 `"七"` | `七1` | 无表则不校验 |
|
||||
| E5 | `+ \`n\`` 旧式形参行 + 参数表 + 传 `"七"` | 同 E3,报契约错 | **你的草图形态可用** |
|
||||
| E6 | 表写 2 行(`a`,`b`),体只读 `a` | `too many positional arguments` | **表 ≠ arity** |
|
||||
| E7 | 单列参数表 `\| 参数 \|` + `\| n \|` | `七1`,**契约静默失效** | 1 列 = List,不成契约 |
|
||||
| E8 | 表里重复两行 `n` | 取**首行**类型,无诊断 | 表内重复静默 |
|
||||
| E9 | 表里有 `ghost`(体里没有) | 静默忽略 | 幽灵行静默 |
|
||||
| E10 | 同一张表加 `` `tc` = `` 绑定 | `七1`,契约**消失** | 绑定 → 变数据 |
|
||||
|
||||
**E10 揭示了一条隐含且优雅的规则**:
|
||||
|
||||
> **未绑定的表 = 声明/元数据(契约);绑定的表 = 数据。**
|
||||
|
||||
这正是语言对「表可以是声明吗」给出的既有答案:可以,**但前提是它不是一个值**。
|
||||
一旦你给它起名字(`` `tc` = ``),它就从「关于函数的声明」降级为「一个普通数据值」。
|
||||
|
||||
E6 + E7 + E8 + E9 合起来说明:**表与真实签名之间今天就可能漂移,而且是静默的**
|
||||
(`marqdo check e7.mq.md` 输出「无契约问题」)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 若让表成为「定义」,运行时会发生什么
|
||||
|
||||
把上面的静默漂移从「少个校验」升级成「少个参数」,风险等级完全不同。
|
||||
|
||||
| 风险 | 今天(表=注解) | 若表=定义 |
|
||||
|------|----------------|-----------|
|
||||
| 漏写 `类型` 列 | 契约静默失效(E7) | **参数静默消失**,调用直接错 arity |
|
||||
| 表行数 ≠ 体读取数 | 表多余行被忽略(E6/E9) | **接口由表决定**,体重构后表未改 → 运行期崩 |
|
||||
| 重复行 | 取首行(E8) | **参数重复定义**,行为取决于解析器取舍 |
|
||||
| 表行重排 | 无影响(顺序由声明序决定) | **改变位置参数绑定顺序** → `> f 1 2` 含义变了 |
|
||||
| 加名字绑定 | 变数据(E10) | 语义分叉:什么时候是函数、什么时候是数据? |
|
||||
|
||||
最后一条最致命。**表是「可自由编辑的文档」**:调整行序、增删说明列、
|
||||
甚至把两张表合并,都是正常的写作行为。一旦表的行序决定位置参数绑定,
|
||||
「把 `b` 那行移到 `a` 上面」这个无害的编辑动作就**改变了程序行为**。
|
||||
|
||||
而 Marqdo 的核心承诺是「**文档即程序,且文档可被人阅读与维护**」。
|
||||
让排版顺序携带语义,等于给每张表埋一颗静默的雷。
|
||||
|
||||
对比一下:`[键](集合)` 之所以安全,是因为**键是显式的**,
|
||||
取元不依赖顺序。而位置参数天然依赖顺序——所以**签名不该用表承载顺序**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 为什么链接式调用 `[f](args)` 走不通(第三次论证,这次有史料)
|
||||
|
||||
前两轮已从「与取元同形」论证过。这次找到了设计层的原始决议。
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §1:
|
||||
|
||||
> 心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
|
||||
|
||||
```markdown
|
||||
**价 = [拿铁](菜单)** # 取出的名字 = 拿铁;从哪取 = 菜单
|
||||
```
|
||||
|
||||
§4「非目标」明确排除:点号 map 访问、`在`、箭头取元、`(键)[集合]`。
|
||||
[call-arguments.md](call-arguments.md) §2 同样锁定:
|
||||
|
||||
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
|
||||
|
||||
所以 `[f](x)` **不是「还没决定的语法」,而是已被明确分配给取元**。
|
||||
让它兼作调用,就是把「从哪取」这个心智反转成「调用谁」——两套直觉会打架。
|
||||
|
||||
而且这与 §4 的表问题**同源**:都是「同一个外形要承载两种语义」,
|
||||
只不过一个在值层面(表 vs 函数),一个在语法层面(取元 vs 调用)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史:这条路走过,而且是被**反向**走过的
|
||||
|
||||
这是本轮考古最有价值的发现。四条史料:
|
||||
|
||||
### 6.1 v0.2 要求手写形参表 → v0.3 明确废除
|
||||
|
||||
[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §1 把 v0.2 的做法列为**代价**:
|
||||
|
||||
| v0.2 | 代价 |
|
||||
|------|------|
|
||||
| 形参必须 `` + `名` `` | **仪式感强;函数头像「另一套签名语言」,与正文脱节** |
|
||||
|
||||
§2 P4 直接给出新方针:
|
||||
|
||||
> **P4 — 形参由体推断(Body-inferred params)**
|
||||
> **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容)
|
||||
|
||||
§5 对照表把 `+ 名` 标为「**过渡兼容**:显式形参;**新代码不推荐**」。
|
||||
|
||||
**结论**:Marqdo 的发展方向是**离「声明式签名」越来越远**,转向「叙述即签名」。
|
||||
把参数改写成表,是在这条已经走反了的路上再走一遍。
|
||||
|
||||
### 6.2 「用表声明 schema」是明文非目标
|
||||
|
||||
[objects.md](objects.md) §6 非目标:
|
||||
|
||||
> - 用表格声明字段 schema(**表格仍表示数据集合**;见 tables-maps-footnotes.md)
|
||||
|
||||
路线图里同样列为非目标:
|
||||
|
||||
> 用表声明对象字段 schema(仍见 objects 非目标;**与数据集合分开**)
|
||||
|
||||
**结论**:语言已明确决定「表管数据,不管声明」。契约表是这一原则的**受控例外**——
|
||||
它只提供注解与校验,不提供绑定。
|
||||
|
||||
### 6.3 行向记录必须显式标记,且「不得静默混用」
|
||||
|
||||
[tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) §3.3:
|
||||
|
||||
> **备选语义(不默认):行向记录列表** …… 若未来需要,用显式标记区分,
|
||||
> **不得**与默认列向字典静默混用。
|
||||
|
||||
§3.5 落地了 `行`/`@`/`row` 标记。
|
||||
|
||||
**结论**:凡是「形态会改变语义」的地方,Marqdo 一律要求**显式标记**。
|
||||
「函数签名表」如果真要参与绑定,属于同类形态变化,必须同样显式——
|
||||
而契约表的 `参数`/`返回` 头,正是这个显式标记的现成形态。
|
||||
|
||||
### 6.4 取元曾被反复挑选,最后选定链接形
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §3 记录了迁移史:
|
||||
脚注形 `` 集合[^键] ``(左键右基)→ 链接形 `[键](集合)`(左键右基,更好读)。
|
||||
|
||||
**结论**:`[…](…)` 这块语法是被**反复权衡后定下来的**,不是随手占用。
|
||||
|
||||
---
|
||||
|
||||
## 7. 诚实的收益清单
|
||||
|
||||
不能只讲风险。这条路确实有真收益:
|
||||
|
||||
| 收益 | 现状 | 潜力 |
|
||||
|------|------|------|
|
||||
| **人读** | 契约表已能带类型+说明,比 `+ 名` 可读得多 | 正是 v0.3 批评 `+` 行「仪式感」的解药 |
|
||||
| **调用边界校验** | 已实现(E3) | 可扩展到更多类型(枚举、范围) |
|
||||
| **机器读:tool schema** | ⚠️ 半成品:`tools` 已能写成记录行(`tool_names` 接受含 `name`/`工具` 字段的对象),但 `agent_format_tools` **只渲染名字**(`- name`),说明与参数被丢弃 | 若函数暴露签名,工具可带 schema 与说明,实参可校验 |
|
||||
| **机器读:CLI/表单** | ❌ 无 | 签名即表 → 直接生成命令行参数解析、Web 表单 |
|
||||
| **文档一致性** | ❌ 表与体可静默漂移(E6/E9) | 可做成「漂移即报错」 |
|
||||
|
||||
最后三行是**最有价值的**。最典型的是 tool schema:`tools` 的数据形态**已经允许**每行带说明,
|
||||
但渲染器只取名字——也就是说**能力已经在那儿,只差把签名接上去**。
|
||||
这不需要把表变成定义,只需要让签名**可被投影成表**。
|
||||
|
||||
---
|
||||
|
||||
## 8. 建议:表做声明,不做定义(并补三件事)
|
||||
|
||||
### 8.1 结论
|
||||
|
||||
| 主张 | 裁决 |
|
||||
|------|------|
|
||||
| 函数参数可以用 GFM 表**描述** | ✅ **已经是特性**,继续用 |
|
||||
| 函数参数可以由 GFM 表**声明**(表即真相) | ❌ 不建议:顺序携带语义、静默漂移、与 v0.3 方向相反 |
|
||||
| 函数**本身**(含函数体)= 表 | ❌ 不可行:体是代码不是数据(见 functions-as-values §4.2) |
|
||||
| `[f](args)` 链接式调用 | ❌ 已被明确分配给取元 |
|
||||
|
||||
**保持现有分工**:
|
||||
|
||||
> 未绑定的表 = 声明(契约);绑定的表 = 数据;**函数体与 arity 是唯一真相**。
|
||||
|
||||
### 8.2 该补的三件事(都低成本,且都是「消灭静默」)
|
||||
|
||||
**① 让漂移显式化(最高价值)**
|
||||
|
||||
现状:表写 2 行、体只读 1 个 → 静默忽略(E6/E9);1 列 → 静默失效(E7)。
|
||||
建议 `marqdo check` 增加诊断:
|
||||
|
||||
| 情形 | 现在 | 应改为 |
|
||||
|------|------|--------|
|
||||
| 契约表缺 `类型` 列 | 静默视为普通表 | 若表头含 `参数`/`返回` 则 **warn**:缺 `类型` 列,已按说明表忽略 |
|
||||
| 契约表列数不齐 | 有诊断(`Some(Err)`) | 保持 |
|
||||
| 表里的参数名不在真实 arity 内 | 静默忽略 | **warn**:`ghost` 不是本函数的形参 |
|
||||
| 表头重复参数名 | 取首行 | **warn**:重复声明 |
|
||||
|
||||
这与本轮 D9「未闭合引号静默吞行」是同一类问题——**静默类缺陷**优先修。
|
||||
|
||||
**② 反向生成:签名 → 表(满足「语法很美」)**
|
||||
|
||||
既然表是好的**呈现**,就让工具来生成它,而不是让人手写:
|
||||
|
||||
```
|
||||
marqdo view --signature 文件.mq.md # 从体推断的签名生成契约表草案
|
||||
```
|
||||
|
||||
单一真相仍是函数体,表是**投影**。这样既拿到「签名即表」的可读性,
|
||||
又不引入第二真相。人也可以手写表,`check` 负责校验它与体一致(即 ①)。
|
||||
|
||||
**③ 让签名可供机器消费**
|
||||
|
||||
把 `Function` 的签名(名、参数、类型契约)暴露成结构化数据(如
|
||||
`marqdo knowledge` 的能力条目里带上参数 schema),
|
||||
`ext/ai` 的工具即可从「只渲染名字」升级为「带 schema 与说明的工具」。
|
||||
这是 §7 里最实的收益,且**零语法改动**。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一个可以试的新写法(示例,供你评判)
|
||||
|
||||
如果你想保留「表 + 函数体」的书写快感,最安全的形态是**双写 + 一致性校验**:
|
||||
|
||||
```markdown
|
||||
## 税率
|
||||
+ `档位`
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 档位 | number | 1/2/3 档 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | number | 适用税率 |
|
||||
|
||||
- [行](`税率表`)
|
||||
**hit = [档位](`行`)**
|
||||
1. `hit`
|
||||
...
|
||||
*[税率](`行`)*
|
||||
```
|
||||
|
||||
| 优点 | 缺点 |
|
||||
|------|------|
|
||||
| 人读极好(表 + 正文) | 与真实签名可能漂移(需 ① 的校验兜住) |
|
||||
| 已经是**今天可跑**的语法(E5 验证) | `+ 行` 是 v0.3 标注「新代码不推荐」的旧形态 |
|
||||
| 类型校验已生效(E3) | 表不能替代体推断,参数仍要声明 |
|
||||
|
||||
**要点**:这张表**不是**函数的定义,而是它的**仪表盘**。
|
||||
真正的接口由 `+ 档位`(或叙述声明)决定,表负责类型与说明。
|
||||
只要两者不一致就报错,这套写法就既美又安全。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **裁决**:是否接受「表做声明、不做定义」(§8.1)?
|
||||
2. **优先级**:§8.2 的三件事(① 漂移诊断 / ② 反向生成 / ③ 签名可供机器消费)
|
||||
先做哪个?我建议 ①(消灭静默)→ ③(tool schema 是刚需)→ ②。
|
||||
3. **是否要我把 `+ 行` 加契约表的组合**写成教程样例(§9),
|
||||
并明确标注「`+` 是兼容形态、新代码优先叙述声明」?
|
||||
4. 若你仍想推进「表即签名」,我可以做一次**限定实验**:
|
||||
要求显式标记(如 `| 签名 | 参数 | 类型 |`)+ 与体推断不一致即报错,
|
||||
在小范围金样里验证是否可控。要我做吗?
|
||||
@@ -0,0 +1,471 @@
|
||||
# 方案评估:函数能否作为变量的一种(函数即表)
|
||||
|
||||
> **2026-10-23 审阅裁决**:以下是旧实现约束与方案权衡,不是“匿名函数无法索引”或“动态调用无法检查契约”的普遍结论。一等函数/闭包本轮暂缓而非永久禁止;有限决策表先评估现有库表达,文中建议的新辅助函数不因此成为已实现能力。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 用户:「函数本身可以理解为 `` `函数名` = `` + 参数/函数体表;此时和表格取元有极大相似性」 |
|
||||
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [spaced-function-names-d8.md](spaced-function-names-d8.md) · [function-as-table-semantics.md](function-as-table-semantics.md)(后续:函数与表格的语义考古,11 组实验) |
|
||||
| 影响面 | 值模型 / 调用语义 / 契约 / EKC 指纹 / 字节码 / 序列化 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**你的直觉在数学上是对的,但在语言上要拆成三种强弱不同的主张**:
|
||||
|
||||
| 主张 | 是否已成立 | 代价 |
|
||||
|------|-----------|------|
|
||||
| 弱:函数**名**可当数据传递 | ✅ **今天就能做**(字符串 + `call_fn`),但零参、不可静态检查 | 无 |
|
||||
| 中:函数是**一等值**(可存、可传、可返回) | ❌ 需要新值类型 + 动态 callee | 中高:契约、指纹、字节码、序列化全都要动 |
|
||||
| 强:函数**就是表**(结构性、可遍历、可序列化) | ❌ 需要把代码降格为数据 | **高**:与「代码即文档」的静态可索引性冲突 |
|
||||
|
||||
**建议**:把你草图里真正有价值的那部分(**有限域决策表**)作为一等公民支持——它今天就成立、
|
||||
且极其契合 Marqdo 的表格优先哲学;而「函数即表」的强主张不建议采纳,理由见 §4、§6。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先把「函数是变量」拆开
|
||||
|
||||
这四个概念经常被混为一谈,必须分开,否则讨论会滑。
|
||||
|
||||
### 1.1 外延观(extensional)——函数是「图」
|
||||
|
||||
数学上函数就是一组有序对 $f = \{(a,1),(b,2)\}$,即它的**图像**。
|
||||
按这个观点,函数**确实是一张表**,调用就是**查表**。
|
||||
|
||||
**但这里有一个必须先说清的实测事实**(我最初也想当然写错了):
|
||||
|
||||
GFM **两列表绑定成「列映射」,不是「按首列键控的映射」**:
|
||||
|
||||
```markdown
|
||||
`税率` =
|
||||
|
||||
| 档位 | 税率 |
|
||||
|------|------|
|
||||
| 1 | 0.03 |
|
||||
| 2 | 0.10 |
|
||||
```
|
||||
|
||||
```json
|
||||
{"档位":[1,2],"税率":[0.03,0.1]}
|
||||
```
|
||||
|
||||
所以 `[2](`税率`)` **不是**取税率,而是:
|
||||
|
||||
```
|
||||
error: missing map key `2`
|
||||
```
|
||||
|
||||
真正能「键 → 值」查表的形态是 **Map**(来自 JSON 或库函数),实测两条可用配方:
|
||||
|
||||
**配方 A(推荐,最简)**
|
||||
|
||||
```markdown
|
||||
**税率 = > json.parse text={"1":0.03,"2":0.10}**
|
||||
**t = [2](`税率`)** # → 0.1
|
||||
```
|
||||
|
||||
**配方 B(保留 GFM 表格可读性,但需显式索引)**
|
||||
|
||||
```markdown
|
||||
**ks = [档位](`税率`)** # [1, 2]
|
||||
**vs = [税率](`税率`)** # [0.03, 0.1]
|
||||
**i = > table.index_of list=`ks` item=2** # 1
|
||||
**r = > table.at xs=`vs` i=`i`** # 0.1
|
||||
```
|
||||
|
||||
两条都在 1.5.2 上跑通了。**结论**:外延观的「函数=表」在 Marqdo 里不是
|
||||
`[k](表)` 一句话就能实现,而是「**取到键值对**」这件事本身需要配方。
|
||||
这恰好是一个可补的库缺口(见 §8.1)。
|
||||
|
||||
### 1.2 内涵观(intensional)——函数是「规则」
|
||||
|
||||
`f(x) = x² + 1` 无法写成有限表(定义域无穷)。此时函数是**代码**,调用是**执行**。
|
||||
|
||||
### 1.3 闭包观——函数是「代码 + 环境」
|
||||
|
||||
参数之外还要捕获外部变量。这需要运行时的环境快照。
|
||||
|
||||
### 1.4 名字观——函数是「命名空间里的一条」
|
||||
|
||||
今天 Marqdo 就是这一种:函数存在于 `Module.functions`,按名字解析。
|
||||
|
||||
**你的草图 `|参数|函数体|` 属于哪一种?** 它是**混合体**:行是参数声明(§1.4 的味道),
|
||||
单元格放函数体(§1.2 的味道)。而「和表格取元相似」的直觉来自 §1.1。
|
||||
**三种东西被一句话连起来了**——这正是评估要解开的结。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状实测(全部在 1.5.2 上跑过)
|
||||
|
||||
### 2.1 值模型里没有函数
|
||||
|
||||
`src/value.rs:15` 的 `Value` 枚举:`None / Bool / Int / Num / Text / List / Map / Formula / Code / Secret`。
|
||||
**没有 `Func`。** 函数是 AST 节点(`src/ast.rs:58 Function`),挂在 `Module.functions`(`src/ast.rs:27`)。
|
||||
|
||||
`src/contract.rs:104` 的 `type_of` 同样是十种,穷举无函数。
|
||||
|
||||
### 2.2 调用的 callee 是静态名字,不是表达式
|
||||
|
||||
`src/ast.rs:130 CallExpr { callee: String, path, receiver, args }` ——
|
||||
`callee` 是 **`String`**,不是 `Expr`。所以**语法上无法写出「对计算出来的值发起调用」**。
|
||||
|
||||
运行期 `src/interp.rs:1119 eval_call` 最终走到 `lookup_function`(`src/interp.rs:1774`),
|
||||
按名字在 AST 树里查找。
|
||||
|
||||
### 2.3 对象已经是「表」
|
||||
|
||||
`src/interp.rs:1509 instance_type_name` 要求 method receiver 是**带 `_type` 键的 Map**:
|
||||
|
||||
```
|
||||
error: method receiver needs a map with `_type`
|
||||
```
|
||||
|
||||
也就是说 **Marqdo 里「用户定义的结构」本来就是普通 map + 一个标签**。
|
||||
对象与表之间没有鸿沟——**这与你的直觉一致,而且已经是既成事实**。
|
||||
|
||||
但函数不是。对象是值,函数不是。这个不对称值得注意。
|
||||
|
||||
### 2.4 已存在按名字间接调用:`call_fn`
|
||||
|
||||
`src/interp.rs:1295`:
|
||||
|
||||
```rust
|
||||
"call_fn" => {
|
||||
// name 必须是 text
|
||||
let target = lookup_function(module, fun, name)...;
|
||||
if !target.params.is_empty() {
|
||||
return Err("call_fn: `{name}` must have no parameters");
|
||||
}
|
||||
self.run_function(module, target, Env::new(), &[], false)
|
||||
}
|
||||
```
|
||||
|
||||
这是**今天最接近「函数可传递」的机制**,但有三道硬限制:零参、限当前模块、只在运行期校验。
|
||||
|
||||
### 2.5 六组实验
|
||||
|
||||
| # | 写法 | 结果 | 结论 |
|
||||
|---|------|------|------|
|
||||
| 1 | `**f = > greet**` | `missing argument for parameter who` | `> 名字` 是**调用**语法,**无法引用函数本身** |
|
||||
| 2 | `> call_fn name="hello"`(无参函数) | `world` | 按名字调用可行 |
|
||||
| 3 | `> call_fn name="add"`(有参) | `call_fn: `add` must have no parameters` | 不能传参 |
|
||||
| 4 | 表里存函数名 + `[h](reg)` 取名 + `call_fn` | `dispatch=world` | **动态派发今天就能做**(名字即数据) |
|
||||
| 5 | `> call_fn name="txt.str_trim"` | `unknown function` | **不能跨模块** |
|
||||
| 6 | `> call_fn name="no_such_fn"` | `unknown function` | 拼错只能在**运行期**发现 |
|
||||
|
||||
**实验 4 是关键**:它已经是「函数作为表成员」的可用原型,只是把函数表示成**名字字符串**而不是函数值。
|
||||
|
||||
---
|
||||
|
||||
## 3. 你的类比中成立的部分
|
||||
|
||||
必须明确肯定,否则会低估这个想法。
|
||||
|
||||
### 3.1 「有限域函数 = 表」是完全成立的范式
|
||||
|
||||
这类函数在工程里非常常见,而且用它表达比写代码更清楚:
|
||||
|
||||
| 场景 | 适合表格 | 为什么 |
|
||||
|------|---------|--------|
|
||||
| 税率 / 费率档位 | ✅ | 有限、离散、常改动 |
|
||||
| 状态机转移表 | ✅ | 二维查表一目了然 |
|
||||
| 错误码 → 处理动作 | ✅ | 业务方直接维护 |
|
||||
| 路由分发 | ✅ | 键即路径 |
|
||||
| 配置映射 | ✅ | 本来就是数据 |
|
||||
|
||||
而且 Marqdo 的 `[键](集合)` 取元**在语义上就是函数应用** ——
|
||||
前提是这个集合是 **Map**(键→值):
|
||||
|
||||
```markdown
|
||||
**rate = [2](`税率`)** # 读作:税率(2)
|
||||
```
|
||||
|
||||
只要 `税率` 是 Map,这行**无需任何语言改动**就是一个查表函数。你已经拥有它了。
|
||||
|
||||
唯一的坑是**数据形态要对**:GFM 两列表绑定的是**列映射**(§1.1 实测),
|
||||
`[2](两列表)` 会报 `missing map key`。所以「表 = 函数」成立,
|
||||
但**哪种表**有讲究——这正是 §8.1 要补 `table.by_column` / `table.lookup` 的原因。
|
||||
|
||||
### 3.2 表格对「参数边界」天然友好
|
||||
|
||||
上一轮讨论 `[函数名](参数)` 时,痛点是参数边界(空格切词)。表格完全绕开这个问题:
|
||||
键是**显式**的,不需要切词。
|
||||
|
||||
### 3.3 对象已证明「结构即表」不会损害语言
|
||||
|
||||
§2.3 说明对象本来就是 map。既然对象能这样,把**数据的**函数化交给表格是自洽的。
|
||||
|
||||
---
|
||||
|
||||
## 4. 类比的断裂点
|
||||
|
||||
三个,每一个都是硬约束。
|
||||
|
||||
### 4.1 断裂点一:表格是有限的,函数通常是无限的
|
||||
|
||||
外延观只对**有限定义域**成立。`f(x)=x²+1` 写成表需要无限行。
|
||||
所以「函数即表」只能覆盖**查表能解决的那部分**,不能作为函数的通用表示。
|
||||
|
||||
一旦你承认这一点,「函数即表」就从「函数的定义方式」降级为「一种特殊函数(图表函数)」。
|
||||
这仍然有用,**但不是语言的核心函数机制**。
|
||||
|
||||
### 4.2 断裂点二:函数体是**代码**,不是数据
|
||||
|
||||
你的草图把「函数体」放进单元格。但函数体在 Marqdo 里是 `Vec<Stmt>`(AST),不是 `Value`。
|
||||
要让函数体成为单元格内容,必须先让「代码」成为值——即 `Value::Code` 那种东西。
|
||||
|
||||
而 `Value::Code` 目前**只表示外联语言源码**(```lang 围栏),是交给外部执行器跑的,
|
||||
不是 Marqdo 自己的代码。让 Marqdo 代码变成值 = 引入 `eval`,这会带来:
|
||||
|
||||
- 静态检查失效(代码在运行期才成形,`marqdo check` 看不见)
|
||||
- EKC 指纹失效(§6.2)
|
||||
- 契约失效(§6.1)
|
||||
|
||||
### 4.3 断裂点三:调用不是取元——`[k](x)` 会被语义重载
|
||||
|
||||
这是最要命的一条,**与上一轮 `[函数名](参数)` 的冲突同源**。
|
||||
|
||||
若「函数是表」且「调用 = `[参数](函数表)`」,那么:
|
||||
|
||||
```markdown
|
||||
[a](m) # m 是普通 Map → 取成员 a
|
||||
[参数](f) # f 是「函数表」→ 执行?还是取成员「参数」?
|
||||
```
|
||||
|
||||
**形状完全一致,含义取决于值的类型**。这正是上一轮我们判定「不可靠消歧」的同一类问题,
|
||||
只不过从「语法层歧义」升级成了「类型层重载」。
|
||||
|
||||
Marqdo 的 `[k](coll)` 目前是**唯一且清晰**的取元语义。让它兼职「调用」,
|
||||
会让最常用的读表操作变得需要思考「这个表是不是函数」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 五条设计路径
|
||||
|
||||
### 路径 A — `Value::Func` 闭包(一等函数)
|
||||
|
||||
```rust
|
||||
Value::Func(Rc<FuncVal>) // params + body + captured Env
|
||||
```
|
||||
|
||||
调用点需支持「对表达式求值后再调用」,即 `CallExpr.callee` 从 `String` 变成 `Callee::Name(String) | Callee::Expr(Expr)`。
|
||||
|
||||
**代价**:
|
||||
|
||||
| 面 | 影响 |
|
||||
|----|------|
|
||||
| 契约(T2.1/T2.2) | `call_arg_diag(c, &target.name, …)` 依赖静态 `target: &Function`;动态调用**拿不到**,契约检查只能退化为运行期 |
|
||||
| 字节码 | `Op::Call(fid, argc)` 用**编译期函数 id**(`src/bytecode/compile.rs:709`),动态 callee 需要新指令或回退树遍历 |
|
||||
| EKC 指纹 | `collect_calls` 读 `c.callee`(`src/knowledge/fingerprint.rs:76`),动态调用只剩字面 `call_fn`,**复用/查重能力下降** |
|
||||
| 序列化 | `value_to_json`(`src/host/json.rs:98`)对 `Value` 穷举,函数值必须定义 JSON 语义(丢弃?报错?) |
|
||||
| 沙箱 | 函数值无法跨沙箱边界,`sandbox.run` 的接口要加限制 |
|
||||
| 闭包捕获 | 需要环境快照与生命周期管理;`Env` 目前是每次调用新建(`Env::new()`) |
|
||||
|
||||
**适用于**:确有高阶需求(回调、map/filter、事件处理)。属于**新语言特性**,应走 ADR。
|
||||
|
||||
### 路径 B — 函数即表(你的草图,强主张)
|
||||
|
||||
**代价**:A 的全部,**外加** §4.3 的语义重载,以及:
|
||||
|
||||
- 表可以 `table.put` 被修改 → 函数可变?还是只读?
|
||||
- 表可以遍历 → 遍历函数会看到什么?参数名?函数体 AST?
|
||||
- 表可以 `json.stringify` → 函数体以什么形式序列化?
|
||||
- 宏展开式的能力(代码即数据)会引入**自修改程序**,与「可静态审计」直接冲突
|
||||
|
||||
**结论**:**不建议**。它把 Marqdo 从「可静态索引的文档程序」推向「运行期构造的代码」,
|
||||
是在削弱自己最强的差异点(§6)。
|
||||
|
||||
### 路径 C — 对象可调用(复用 `_type` + 约定方法)
|
||||
|
||||
让 `# 类名` 实例在 `_type` 之外带一个约定的 `## 应用` 方法,`f(x)` 时若 `f` 是 map 且 `_type` 有该方
|
||||
法则走方法调用。
|
||||
|
||||
**优点**:不新增 `Value` 变体;复用既有 method 机制。
|
||||
**缺点**:仍需要「`f(x)` 里 f 是表达式」这一语法能力(同 A 的调用点改造);
|
||||
且引入「有的 map 可调用」的隐式规则,可读性下降。
|
||||
|
||||
### 路径 D — 名字即函数(扩展现有 `call_fn`)
|
||||
|
||||
不引入函数值,而是把**名字**这条路径做完整:
|
||||
|
||||
```markdown
|
||||
> call_fn name="add" args=[1, 2] # 支持传参
|
||||
> call_fn name="txt.str_trim" args=[…] # 跨模块路径
|
||||
> invoke table=`注册表` key="h" args=[…] # 从表里按名派发
|
||||
```
|
||||
|
||||
**优点**:
|
||||
- 零值模型改动 → 契约、字节码、指纹、序列化**全部不动**
|
||||
- 保持「函数永远有名字」→ EKC 能索引,代码可审计
|
||||
- 与实验 4 的现有用法完全兼容(只是补齐能力)
|
||||
|
||||
**缺点**:不是真正的一等函数(不能返回闭包);名字拼错仍要运行期发现
|
||||
(但**可以**加静态检查:`call_fn name="字面量"` 时校验目标存在——见 §8.2)。
|
||||
|
||||
### 路径 E — 决策表作为一等公民(**推荐方向**)
|
||||
|
||||
不叫它「函数即表」,而明确它是什么:**有限域查表函数**。
|
||||
|
||||
```markdown
|
||||
**税率 = > json.parse text={"1":0.03,"2":0.10}** # Map:键 → 值
|
||||
**t = [2](`税率`)** # 今天就能跑 → 0.1
|
||||
```
|
||||
|
||||
**优点**:**零语言改动**,只需文档与库函数支持(例如 `table.lookup` 带默认值,
|
||||
把 §1.1 配方 B 的「列取 + 索引」四步压成一步)。
|
||||
**定位诚实**:它是数据,不是代码;能被 EKC 索引、能序列化、能进沙箱、能被非程序员维护。
|
||||
|
||||
---
|
||||
|
||||
## 6. 对 Marqdo 特有机制的冲击面
|
||||
|
||||
这一节是决策的关键:Marqdo 不是通用语言,它的价值在**可静态索引的工程知识**。
|
||||
|
||||
### 6.1 契约系统(T2.1 / T2.2)
|
||||
|
||||
现有实现把契约挂在 `Function` 上(`src/ast.rs:71`),并在调用点用**静态 target**校验:
|
||||
|
||||
```rust
|
||||
if let Some(c) = &target.contract {
|
||||
if let Some(d) = contract::call_arg_diag(c, &target.name, &bound, …) { … }
|
||||
}
|
||||
```
|
||||
|
||||
动态 callee 拿不到静态 `target`,**契约检查必然退化到运行期**——而契约是 Marqdo
|
||||
「渐进式契约」卖点的核心。
|
||||
|
||||
### 6.2 EKC 指纹与复用
|
||||
|
||||
`collect_calls` 把调用目标名字写进指纹(`src/knowledge/fingerprint.rs:76`)。
|
||||
指纹用于**查重、复用预检、相似任务召回**。动态调用使指纹丢失真实目标,
|
||||
`marqdo duplicate` / `preflight` 的准确率会下降——这直接影响智能体复用飞轮。
|
||||
|
||||
### 6.3 「函数必须有名字」是特性,不是限制
|
||||
|
||||
EKC 按符号名索引(`marqdo knowledge` 输出 `59 modules, 346 symbols`)。
|
||||
匿名函数/表构造的函数**无法被索引**,也就无法被复用、被审计、被智能体发现。
|
||||
|
||||
> 对 Marqdo 而言,**函数有名字**不是妥协,而是「代码即文档」的必然:
|
||||
> 文档里的每一段代码都得有一个可被引用的标题。
|
||||
|
||||
### 6.4 序列化与沙箱
|
||||
|
||||
`value_to_json` 穷举所有 `Value`。函数值需要 JSON 语义;
|
||||
沙箱(CoW + 禁 exec/net/plugin)跨边界传值时,函数**无法表示**。
|
||||
一旦函数成为值,`sandbox.run` 的入参约束必须收紧。
|
||||
|
||||
### 6.5 确定性与可审计
|
||||
|
||||
表格是**静态可读**的:非程序员能改税率表。代码构造的函数则要求读者在脑中执行程序。
|
||||
Marqdo 面向的是「文档作者也能维护」的场景,这一点权重很高。
|
||||
|
||||
---
|
||||
|
||||
## 7. 方案对比
|
||||
|
||||
| 维度 | A 闭包 | B 函数即表 | C 可调用对象 | D 扩展 call_fn | E 决策表 |
|
||||
|------|--------|-----------|-------------|---------------|----------|
|
||||
| 值模型改动 | **需新变体** | 需新变体+代码即值 | 无 | **无** | **无** |
|
||||
| 保持静态可索引 | 部分(匿名不可) | ❌ | ✅ | ✅ | ✅ |
|
||||
| 契约检查 | **退化** | 退化 | 保持 | 保持 | 保持 |
|
||||
| EKC 指纹 | 退化 | 退化 | 保持 | 保持 | 保持 |
|
||||
| 序列化/沙箱 | 需特殊处理 | 需特殊处理 | 保持 | 保持 | 保持 |
|
||||
| 解决参数边界 | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| 支持无限定义域 | ✅ | ❌ | ✅ | ✅ | ❌(本质限制) |
|
||||
| 实现成本 | 高 | 很高 | 中 | **低** | **零** |
|
||||
| 风险 | 中高 | **高** | 中 | 低 | 无 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 建议(分阶段)
|
||||
|
||||
### 8.1 立即可做:决策表(路径 E)
|
||||
|
||||
零语言改动。补三件事即可让它好用:
|
||||
|
||||
1. **补库缺口**:新增 `table.lookup map=`key=`default=`(键→值,缺键返回 default)与
|
||||
`table.by_column rows=`key_col=`value_col=`key=`(把 §1.1 配方 B 的四步压成一步)。
|
||||
**这是当前最实的缺口**——GFM 两列表无法直接键查表,用户会反复手写索引逻辑。
|
||||
2. **文档**:在教程里明确「有限域映射怎么表达」,并给出三种形态的取舍:
|
||||
- 键→值查表 → `json.parse` 的 Map + `[键](map)`
|
||||
- 需要保留表格可读性 → 两列表 + `table.by_column`
|
||||
- 缺键行为 → 用 `table.get` / `default=`,避免缺陷 D5 的 `missing map key` 硬崩
|
||||
3. **命名**:明确它叫「决策表 / 查表」而不是「函数」——避免与 §1.2 的内涵观混淆。
|
||||
|
||||
**价值**:把用户已有的直觉固化成推荐用法,不付任何架构代价。
|
||||
|
||||
### 8.2 短期可做:扩展 `call_fn`(路径 D)
|
||||
|
||||
补齐三件事,都不触及值模型:
|
||||
|
||||
| 补充 | 说明 |
|
||||
|------|------|
|
||||
| `args=` | 允许传参,按目标签名绑定 |
|
||||
| 跨模块路径 | `name="lib.fn"` 走 import 解析 |
|
||||
| 字面量静态校验 | `call_fn name="字面量"` 在 `check` 期就校验目标存在(消灭实验 6 的类错误) |
|
||||
|
||||
**收益**:动态派发能力完整,且完全保留契约/指纹/序列化。
|
||||
|
||||
### 8.3 中期评估:一等函数(路径 A)
|
||||
|
||||
只有当出现**确实无法用名字表达**的需求时才做(例如回调、策略模式、事件处理器)。
|
||||
届时必须写 ADR,并明确回答:
|
||||
|
||||
- 匿名函数如何进入 EKC 索引?(可能需要要求「赋给变量的函数字面量必须有名字」)
|
||||
- 契约在动态调用下如何降级?
|
||||
- 字节码是否引入 `Op::CallValue`?
|
||||
- 函数值的 JSON 语义是什么?
|
||||
|
||||
### 8.4 不建议:路径 B(函数即表,强主张)
|
||||
|
||||
理由汇总:§4.3 语义重载 + §6 全面削弱静态可索引性 + §5 自修改程序风险。
|
||||
|
||||
---
|
||||
|
||||
## 9. 如果你想保留「函数即表」的形态,有一个折中
|
||||
|
||||
把「表」用于**参数与分发**,而不用于函数体:
|
||||
|
||||
```markdown
|
||||
`税率表` =
|
||||
|
||||
| 档位 | 税率 |
|
||||
|------|------|
|
||||
| 1 | 0.03 |
|
||||
| 2 | 0.10 |
|
||||
|
||||
## 税率
|
||||
+ `档位`
|
||||
|
||||
**ks = [档位](`税率表`)**
|
||||
**vs = [税率](`税率表`)**
|
||||
**i = > table.index_of list=`ks` item=`档位`**
|
||||
**r = > table.at xs=`vs` i=`i`**
|
||||
*r*
|
||||
```
|
||||
|
||||
(若 §8.1 的 `table.by_column` 落地,函数体可缩成一行:
|
||||
`**r = > table.by_column rows=`税率表` key_col="档位" value_col="税率" key=`档位`**`。)
|
||||
|
||||
这里:
|
||||
|
||||
- **数据**在表里(可被非程序员维护、可序列化、可进沙箱、可被 EKC 索引)
|
||||
- **逻辑**在命名函数里(可契约、可指纹、可审计)
|
||||
- 调用仍是一等清晰的 `> 税率 档位=2`
|
||||
|
||||
这其实是**最好的分工**:表格承担「知识」,函数承担「行为」。
|
||||
它同时满足你的类比直觉(表驱动)和 Marqdo 的静态可索引性。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **方向**:选 E(决策表,零改动)、D(扩展 call_fn)、还是 A(一等函数,需 ADR)?
|
||||
2. 若倾向 D:`args=` 的参数形式用 `[1, 2]`(列表)还是 `a=1 b=2`(具名)?
|
||||
3. 是否要我把 §9 的「数据在表、逻辑在函数」写成教程规范?
|
||||
4. 是否存在**具体用例**驱动一等函数?(例如某个 ext 需要回调)
|
||||
若有真实用例,评估会完全不同——请给我场景,我按场景重新评估。
|
||||
@@ -0,0 +1,326 @@
|
||||
# 隔离执行与响应式 Web 运行时:详细开发设计
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Verified**(execute 路径);HTTP `execute` / `sse-live` / `stream:true` 默认走 Supervisor worker 池(不再经父进程 `CallLibPath` / `INVOKE_LOCK`);`runtime.isolated_execution=1`;MR-01 金样例 `tests/isolated_execute_mr01.rs`;未声明非流式仍 `legacy_serial`(ADR 0008) |
|
||||
| 基线 | Marqdo `1b11fe0` / 2.1.3;qdagent `64b97e5`;2026-10-26 |
|
||||
| 问题依据 | [单解释器缺陷](web-invoke-serialization.md)、[ADR 0008](../adr/0008-web-invoke-serialization.md)、[本轮跨库复核 R01–R14](../../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) |
|
||||
| 产品配套 | [qdagent 可靠工作台开发设计](../../../qdagent/doc/design/reliable-workbench-development-2026-10-26.md) |
|
||||
| 继承合同 | [工作台 M00–M06](qdagent-workbench-runtime-and-view-2026-10-25.md) 中 ModelSelection、ModelSnapshot、Usage、DocumentView、Locator;保留文档原生作者面 |
|
||||
|
||||
## 1. 目标、边界与不变量
|
||||
|
||||
目标是让用户在长对话、导入和构建过程中持续打开模型列表、读取来源、修改下一轮设置并可靠停止任务。高并发容量按资源预算显式限制;不能让所有请求进入一把解释器锁再超时。
|
||||
|
||||
Marqdo 负责通用执行隔离、资源调度、事件/取消、语义分析和制品校验。qdagent 负责用户/工作区授权、业务状态与发布政策。产品仍通过 `.mq.md` 调用 Marqdo Agent,不增加第二套模型循环或知识编译器。
|
||||
|
||||
必须保持的系统不变量:
|
||||
|
||||
1. 同一个可变 HostContext 同时最多一个求值者;不删除锁、不增加虚假的 `unsafe impl Sync` 来获得并行。
|
||||
2. 一个执行租约只属于一个 run/attempt;凭证、事件、取消、cwd、权限和模型选择不可流入另一请求。
|
||||
3. 控制与读取具有独立容量,不被 LLM 等待占满;停止不需要重新进入正在执行的解释器。
|
||||
4. 事件可以重投,外部副作用不默认重做;不宣称跨网络 exactly-once。
|
||||
5. 已确认终态不能被晚到完成/取消覆盖;取消不回滚已经完成的外部写入。
|
||||
6. 阅读不执行 `.mq.md`,缓存不绕过授权或版本校验;缓存命中必须实际复用结果。
|
||||
7. 正文、依赖、证据和编译代属于同一不可变快照;不会把两个代的结果拼成一次阅读或执行。
|
||||
8. 任何能力开关都以实际探测和测试为依据;新 API/schema 在落地前都属于本文提案。
|
||||
|
||||
## 2. 架构选择
|
||||
|
||||
| 方案 | 优点 | 当前代价 | 本轮选择 |
|
||||
|---|---|---|---|
|
||||
| 继续全局锁,只增加 Go handler | 改动小 | 长任务依然阻塞所有 Endpoint,串扰变量也未消失 | 只保留作兼容模式 |
|
||||
| 同进程多 HostContext | 潜在内存复用较好 | GLOBAL_HOST、插件回调、环境、cwd、事件 sink 生命周期需系统重做 | 后续优化,不是首个交付门槛 |
|
||||
| 独立 Marqdo worker 进程 + 控制/读取通道 | 隔离现有全局状态,可强制回收卡死任务,复用现有语言与 Agent | IPC、进程启动、内存、发布写协调 | **首选实现** |
|
||||
| 引入外部通用队列和新业务 Runtime | 容易扩到集群 | 运维复杂度及第二套编排风险 | 单机阶段不引入 |
|
||||
|
||||
首期采用**预热的一次性执行进程池**:进程可预装运行时和非用户特定模块,分配任务后独占,结束即退出并异步补充。这样不用假设清空部分字段就能安全复用 HostContext。长寿命多租约 worker 只有通过状态泄漏、插件资源与 RSS 回归后才开启。只读分析服务可以长寿命运行,但不得加载有副作用的求值插件。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
UI[浏览器 / CLI / MCP] --> WEB[Go HTTP / 认证入口 / 限流]
|
||||
WEB --> CTRL[任务控制与事件服务]
|
||||
WEB --> SHORT[短业务请求容量]
|
||||
WEB --> READ[只读分析服务]
|
||||
SHORT --> POLICY[qdagent .mq.md 授权与业务规则]
|
||||
POLICY --> CTRL
|
||||
CTRL --> DB[(任务索引 / outbox / 事件日志)]
|
||||
CTRL --> SUP[Rust Supervisor / 有界调度]
|
||||
SUP --> A[Marqdo worker A / 一个租约]
|
||||
SUP --> B[Marqdo worker B / 一个租约]
|
||||
A --> AGENT[既有 Marqdo Agent / LLM / sandbox]
|
||||
B --> AGENT
|
||||
A --> STAGE[每任务暂存目录]
|
||||
B --> STAGE
|
||||
STAGE --> COMMIT[按资源串行提交与 revision CAS]
|
||||
COMMIT --> SNAP[(不可变知识代 / 发布 manifest)]
|
||||
READ --> SNAP
|
||||
A --> CTRL
|
||||
B --> CTRL
|
||||
CTRL --> UI
|
||||
```
|
||||
|
||||
“短业务请求容量”依旧可执行产品 `.mq.md`,但有独立 worker 预算和短 deadline。控制服务只做通用接纳、状态 CAS、取消与日志投递,不把模型选型、知识晋升等业务逻辑搬进 Go。读取服务接收经过授权的资源句柄;不得直接相信浏览器提交的绝对路径。
|
||||
|
||||
## 3. 路由分类与接纳
|
||||
|
||||
### 3.1 执行类别
|
||||
|
||||
在 Endpoint 装配中新增可选 metadata(字段名待 schema 固定):
|
||||
|
||||
| 类别 | 示例 | 资源预算与规则 |
|
||||
|---|---|---|
|
||||
| `control` | 任务查询、事件订阅、取消、health | 不执行用户代码;认证后访问任务存储/租约注册表 |
|
||||
| `read` | view.document、引用解析、已发布模型列表投影 | 只读快照;不写用户源码;可缓存 |
|
||||
| `short` | 保存设置、创建导入、接纳任务 | 无 LLM 长等待;默认 deadline 2s,较慢动作转为任务 |
|
||||
| `execute` | ASK/BUILD/生成/验证 | 有界队列、专属进程、显式任务 deadline |
|
||||
| `commit` | 切换知识代、合并受控文件变更 | 按 workspace/kb 的短临界区;执行前检查 revision |
|
||||
|
||||
旧 Endpoint 未声明时仍走 legacy_serial;不能自动猜测任意函数是纯读。纯度来自静态能力和注册配置,实际写权限仍由宿主限制。文件上传字节传输不占解释器,应先落隔离存储,再进入短接纳路径。
|
||||
|
||||
### 3.2 接纳步骤
|
||||
|
||||
1. HTTP 层解析受限请求,验证身份、格式、速率与连接数量。
|
||||
2. 产品短入口解析 workspace/model/policy;授权版本与模型配置 revision 一并冻结。返回规范化任务请求,不执行 Agent。
|
||||
3. 控制服务在同一数据库事务中登记作用域化 idempotency key、payload hash、task 和 dispatch outbox;重复请求读回已有 task,同键异内容返回 409。
|
||||
4. 提交事务后才返回 202/Location。调度器消费 outbox 分配租约,租约带 attempt/epoch。
|
||||
5. 对同步兼容 API,先完成接纳,再挂接结果;等待客户端超时不等于安全重做。
|
||||
|
||||
队列入库前容量不足返回 429 + Retry-After;服务不可用返回 503;接纳失败不发送 started。控制通道须保留槽位,不能因为数据流连接占满而无法取消。
|
||||
|
||||
## 4. Supervisor、生命周期与调度
|
||||
|
||||
### 4.1 Worker 生命周期
|
||||
|
||||
`starting → ready → leased → running → draining → exited`;启动失败/心跳丢失走 `unhealthy → terminating → exited`。任务状态由控制服务维护,进程状态不能直接当作业务成功。
|
||||
|
||||
- worker 启动握手报告 CLI/ext/native、protocol_version、能力、构建摘要;不匹配不进入 ready。
|
||||
- 预热阶段不读取用户凭证、不挂载工作区写权限。分配租约后挂载当前任务的 capability roots、只读快照和独立 staging。
|
||||
- 每任务具有随机 lease_id、run_id、attempt_id、epoch、绝对 deadline 和资源限制。
|
||||
- Supervisor 持有进程句柄、子进程组、事件通道与取消句柄。worker 不能自行修改其他 worker 状态。
|
||||
- 返回业务结果后仍须 drain 事件/用量并提交最终 checkpoint,控制服务持久化终态后确认 ACK,之后释放租约。
|
||||
- 超时或断连清理不能遗留孤儿子任务;正常优雅退出后再删除临时文件。异常由独立 janitor 按租约过期回收。
|
||||
|
||||
### 4.2 有界、公平与资源预算
|
||||
|
||||
初始验证配置建议 4 vCPU/8 GiB、执行槽 2、短请求槽 1、读取服务 1。具体容量由每类任务的 RSS p95 和 CPU profile 决定,不能把这个数当所有机器的默认。执行槽上限:
|
||||
|
||||
`min(CPU约束, floor((可用内存 - 系统/控制/缓存预留) / worker_RSS_p95))`。
|
||||
|
||||
运行队列按 workspace 轮转,再按 session FIFO;一个 session 默认只允许一个活动 turn,跨 session 可并行。相同知识库的生成可并行,发布只占短提交锁。interactive 优先于后台索引,但后台使用老化提升或最低服务配额,防永久饥饿。
|
||||
|
||||
全局队列初始上限 64、单工作区 16、单会话待处理 4,均可配置;队列超限及时返回,不能悄悄丢任务。显示队列位置或“前方有任务”,没有可靠完成时间估计时不显示虚构倒计时。
|
||||
|
||||
### 4.3 副作用与重试
|
||||
|
||||
任务声明 `read_only / staged_write / external_effect`,由工具权限校验而非模型自报。read_only 可按政策重试;staged_write 丢弃未提交 staging 后重试;external_effect 出现超时/失联时标记 `effect_unknown`,等待核对,不自动重复支付、发信或写入。
|
||||
|
||||
稳定的操作键使用 `task_id + logical_step_id`,attempt_id 只标记传输尝试,不应导致同一外部动作生成新的去重键。工具不支持幂等查询时,只能明确报告不确定。工作簿记录已完成与未知副作用;“已停止”不意味着“全部撤销”。
|
||||
|
||||
## 5. IPC 与请求上下文
|
||||
|
||||
首期使用本机 Unix socket 或匿名管道,采用长度前缀 JSON 控制帧与独立事件通道。协议禁止无上限 JSON/单行日志;控制帧初始上限 1 MiB,大文档通过授权 blob handle 传递。普通 stdout/stderr 仅诊断,不与协议混流。当前 NDJSON 文件桥保留为 legacy fallback。
|
||||
|
||||
新增 `InvokeRequestV2` 示例(提案):
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "InvokeRequestV2",
|
||||
"schema_version": 2,
|
||||
"task_id": "task_01",
|
||||
"run_id": "run_01",
|
||||
"attempt_id": "attempt_01",
|
||||
"lease": {"id": "lease_01", "epoch": 3},
|
||||
"entry": {"module": "agent/qdagent.mq.md", "function": "run"},
|
||||
"args_ref": "blob:sha256:...",
|
||||
"context": {
|
||||
"workspace_id": "ws_01",
|
||||
"snapshot_id": "generation_01",
|
||||
"selection_ref": "model-snapshot_01",
|
||||
"capabilities_ref": "grant_01",
|
||||
"deadline_at": "2026-10-26T08:10:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`grant_01` 是服务端验证的短寿命授权句柄,内容包括 principal、scope、根目录、允许效应、授权 revision、失效时间。worker 不使用浏览器任意传入的 fn/path。权限撤回后,新的工具调用必须重新验证 lease/grant,已开始的外部调用记录撤回时间与实际结果。
|
||||
|
||||
`RunContextV1` 保留原有字段与序列化兼容,内部增补显式 Context 对象;扩展 V2 由能力协商启用。event_sink、usage_sink、cancel_token 使用句柄,不使用外部可控路径。子任务通过 IPC/Command.env 显式继承,禁止父进程 `setenv`/`set_current_dir` 承担请求状态。
|
||||
|
||||
凭证在租约启动时通过受保护 IPC 或继承 FD 注入;不落任务 JSON、argv、日志或通用事件。模型快照可含 credential_ref,不含 api_key。即使选择相同 provider,不同请求的授权也不得合并。
|
||||
|
||||
## 6. 取消协议与状态 CAS
|
||||
|
||||
任务基础状态:`accepted → queued → running → finalizing → succeeded/failed`;queued/running 可进入 `cancel_requested → cancelled`;worker 失联进入 `interrupted`,副作用不明时进入 `needs_reconciliation`。这些是提案,产品可以将 succeeded 映射为 completed。
|
||||
|
||||
取消顺序:
|
||||
|
||||
1. 验证调用者对 task 的权限,CAS 写 cancel_requested、revision 与 requested_at;终态返回原状态,未知 ID 返回 404。
|
||||
2. 向匹配 lease/epoch 的控制通道发送 Cancel;不经任务解释器锁。queued 任务原子移出待派发队列。
|
||||
3. worker 在每次 LLM/工具调用、重试、子任务启动和提交之前检查 token;网络请求使用可中断句柄,不能仅在一行输出结束后才检查。
|
||||
4. 收到 ACK 仍不等于任务停止。等待 worker 报 stopped、落未完成副作用和用量,再 CAS 到 cancelled。
|
||||
5. 默认 2s 协作宽限、额外 3s 进程退出宽限,之后回收进程组。强制退出记 interrupted/needs_reconciliation,不能伪造干净 cancelled。
|
||||
|
||||
完成与取消竞争的线性化点是控制存储的 CAS:终态先提交则 cancel 返回 already_terminal;取消先提交则晚到 result 只可作为证据追加,不能重新变 succeeded。若外部动作已发生但响应晚到,记录 effect outcome,不撤销取消事实。
|
||||
|
||||
兼容文件 token 统一:不存在/空/`0` 为未取消,`1`/`cancelled` 为取消;读取失败返回诊断并按明确策略处理。删除 token 只能发生在持有者退出之后。移除全局 `MARQDO_CANCEL` 对多个任务的隐式作用域。
|
||||
|
||||
## 7. 事件、SSE 与背压
|
||||
|
||||
### 7.1 事件权威
|
||||
|
||||
生产者发出 `(run_id, attempt_id, local_seq)`,控制服务去重、持久化并分配 task 内单调 seq/event_id;客户端游标来自持久化日志,不是 handler 重连后从 1 开始计数。终态事件唯一,usage 可以在终态后以更高 usage revision 补录,但不能再次结束任务。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "RuntimeEventV2",
|
||||
"schema_version": 2,
|
||||
"event_id": "task_01:42",
|
||||
"seq": 42,
|
||||
"task_id": "task_01",
|
||||
"run_id": "run_01",
|
||||
"attempt_id": "attempt_01",
|
||||
"type": "message.delta",
|
||||
"payload": {"message_id": "msg_01", "offset": 24, "text": "结果"}
|
||||
}
|
||||
```
|
||||
|
||||
不要直接破坏 RuntimeEventV1;新增字段/新版本由能力协商确定。普通用户可见 progress 只描述工具、阶段、文件等结构化事实;模型内部 reasoning 不作为完成证据,也不默认写入公开事件。
|
||||
|
||||
### 7.2 App SSE
|
||||
|
||||
新增任务 API 的事件订阅用 `GET /tasks/{id}/events`(最终产品前缀见配套设计),发送 SSE `id`/`event`/`data`;每个 data 是一个完整 JSON。客户端支持 Last-Event-ID、CRLF、多行 data、任意 UTF-8 分块和 EOF 未完成帧。重复事件按 ID 去重;message offset 检查缺口,缺口时恢复快照。
|
||||
|
||||
心跳 15s,客户端空闲探测建议 45s;二者可配置。事件保留建议 24h,最终结果/审计按项目政策更长保留。游标早于保留边界返回 410 `event.cursor_expired` 和快照入口,不能默默从最新开始丢字。
|
||||
|
||||
订阅断开默认只关闭订阅。App 显式停止通过 cancel API,切页/移动网络重连可恢复同一任务。传统同步 OpenAI 调用可保持 disconnect=cancel 的兼容策略,但必须显式区分,不能统一把所有浏览器断流当取消。
|
||||
|
||||
### 7.3 OpenAI 兼容流
|
||||
|
||||
`/v1/chat/completions stream=true` 输出 OpenAI chunk 与 `[DONE]`;App 运行事件由独立入口或协商的协议提供。禁止仅凭任意 JSON body 中 stream=true 将不相关路由自动改为 RuntimeEvent 协议。已发 header 后的错误使用该协议允许的错误帧;发 header 前可用 429/503/401 等正确状态码。
|
||||
|
||||
token delta 与最终完整答复分开:最终事件持有结果引用/摘要和 finish reason,不再次追加整篇正文。无 token 能力的适配器报告 `evented_batch`,界面用阶段状态,不把整包人为拆字伪装成实时。
|
||||
|
||||
### 7.4 背压和旧桥修复
|
||||
|
||||
worker→事件服务与服务→订阅者均有界。建议每订阅者 256 KiB 待发送内存,超出后断开慢消费者并允许按游标重连;事件正文已持久化所以不能静默丢 token。允许合并短时间 delta,必须保留 message offset;usage/终态/错误不丢弃。磁盘压力时停止接纳新任务,已有任务使用保留终态空间并按策略中断,不能无限写事件。
|
||||
|
||||
legacy NDJSON tailer 只消费换行已完整到达的字节;保留残片,offset 按真实消费字节移动。超长行、I/O error、文件旋转显式报协议错误。测试至少分三次写一个 JSON、中文多字节边界、恰好 EOF、超过上限、取消与尾帧竞争。禁止吞掉 Scanner.Err() 继续宣告成功。
|
||||
|
||||
## 8. 只读快照与真正有效的缓存
|
||||
|
||||
### 8.1 快照一致性
|
||||
|
||||
分析服务构建 SnapshotKey:规范化 project identity、允许扫描范围、源文件闭包摘要、依赖/来源/配置摘要、compiler/lib/ext 版本、policy/schema、解析选项。输入由编译器枚举,不另造“前 200 个根目录文件”规则。
|
||||
|
||||
读取一次快照内的正文、语义和来源,完成后复核输入 manifest;文件在分析中发生变化则重试一次或返回 `snapshot.changed`。对不可变发布代直接读其 manifest。mtime/size 只用于快速发现候选变更,不能代替内容摘要;watcher 丢事件后以完整扫描修复。
|
||||
|
||||
### 8.2 缓存结构
|
||||
|
||||
- `AnalysisCache<SnapshotKey, Arc<Compilation>>`:实际编译结果。
|
||||
- `DocumentCache<(SnapshotKey, document_digest, renderer_version, view_options), DocumentView>`:安全 fragment、outline、nodes。
|
||||
- 同 key single-flight 的 follower 等待同一个 Result,不再次 compile。
|
||||
- RAII guard 在 error/panic/cancel 时清除 inflight 并唤醒 waiters;等待者有自己的 deadline。
|
||||
- compile 失败只返回给当前等待者,短暂错误缓存需显式 TTL;不得调用“finish_success”标记失败结果可复用。
|
||||
- LRU 按字节而非条数上限管理;初始预算按部署内存的 10% 且设硬上限,长文档超限不缓存或分页;记录淘汰原因。
|
||||
- 每次读取先授权再查缓存;权限敏感的响应按 scope/policy 分区。全局缓存只共享不含用户秘密且访问已验证的不可变语义数据。
|
||||
|
||||
性能证据必须统计 `compile_invocations`、输入字节、缓存结果命中、leader/follower、wait_ms、evictions;现有 hit counter 不能证明减少编译。
|
||||
|
||||
### 8.3 HTML 与来源定位
|
||||
|
||||
沿用 DocumentViewV1,明确 `render.format=plain_text|sanitized_html`。HTML 通过解析器白名单清洗标签/属性/URL scheme,剥离脚本、事件属性、危险 CSS/嵌入与可执行 SVG;相对资源经受限资源端点解析。纯文本始终转义,不以 `<` 字符判断类型。
|
||||
|
||||
node_id、revision、generation 必须从定位到读取到浏览器滚动完整传递。不存在历史快照返回 version_unavailable;返回当前版是用户显式操作且标明版本变化。no_exec 测试分别验证“无语言副作用”和“浏览器无脚本执行”,二者不能互相替代。
|
||||
|
||||
### 8.4 首次编译的性能改造
|
||||
|
||||
本轮 `v3_corpus_1000_compile_smoke` 在 debug 下 243.012s,超过既有 180s 门禁;缓存不能缩短一个全新项目的第一次编译。先为 `knowledge::compile` 的语义编译、语义落盘、检索 extract、检索落盘、manifest 分别加 span,再细分 `ProjectIndex::build`、源枚举/解析、导入挂接、绑定、效应传播、闭包摘要。记录文件数/总字节、节点/边数、parse 次数与序列化字节量。
|
||||
|
||||
源码中 `sema::compile_project` 在每个文件查找 module path、每个 module 过滤全量 symbols,属于值得测量的重复扫描;未取得 profile 前不将其认定为 243s 的唯一根因。优化候选按证据选择:建立 path→module 与 module→symbols 索引;同一输入快照共享 parsed module;绑定/依赖图用稳定索引;效应传播用 worklist;闭包按 SCC DAG 计算并保留循环依赖语义;减少每制品重复序列化和小文件写入。
|
||||
|
||||
任何优化须保持排序确定性、SymbolId/ArtifactId 与证据摘要规则,禁止通过跳过来源校验、删掉复杂 fixture 或改大超时过关。用 100/1000/10000 单元、无依赖/链/菱形/循环四种图分别测时间与 RSS;给出随 V/E 增长的曲线。release 和 debug 分开;已有 debug 门禁恢复通过只是第一步,§12 的 release 预算仍须独立验收。
|
||||
|
||||
## 9. 写入、发布与数据库边界
|
||||
|
||||
执行 worker 只写任务 staging;需要写工程时通过沙箱产生文件 diff。发布以 kb 资源锁 + expected_generation CAS 提交。锁只覆盖校验当前版本和切换 manifest,不覆盖 LLM、全文编译或网络调用。
|
||||
|
||||
完整发布代先写临时目录、校验摘要、完成必要 fsync,再原子 rename 到不可变 generation 目录;最后在同一文件系统原子替换 CURRENT。源码、编译投影和证据在该 manifest 下对齐。SQLite 中的产品“published”是投影,不参与虚构的文件/数据库跨系统原子事务。通过 publish journal + outbox 恢复:CURRENT 已切换但 DB 未更新时重放;未切换时旧代继续有效。
|
||||
|
||||
project_id 与逻辑文档 ID 不随 staging/generation 的物理目录名变化。manifest 保存稳定 project identity、逻辑相对路径和实际 blob/generation 映射;导入引用按项目规则解析,不能因复制到发布目录而重新生成全部符号身份。框架若尚不能区分逻辑身份与物理根,先补该能力,再启用 generation 目录发布;迁移 fixture 必须断言未修改的知识 ID 和跨文档绑定保持稳定。
|
||||
|
||||
任务表/幂等/CAS/outbox 需要通用事务能力:先审计 `ext/data` 是否支持事务、条件更新、受影响行数、复合唯一键;缺少则在 Marqdo 数据层补齐,不能用 `.mq.md` 的先读后写模拟原子性。SQLite 使用短事务和有界 busy timeout;WAL/连接池是否开启需按现有插件适配测试确认。单主本地盘为首期部署范围,跨主机共享 SQLite/NFS 不在首期承诺内。
|
||||
|
||||
## 10. 临时缓解与迁移
|
||||
|
||||
### 10.1 进程池完成前
|
||||
|
||||
- 保留 1500ms busy 预算和 Retry-After;展示繁忙,而非无限 spinner。
|
||||
- 在接纳任何 SSE 之前取得覆盖整个 bridge 生命周期的 legacy 单飞许可,第二条流在修改环境变量/发送 200 前失败;普通请求不得绕过许可观察被污染的状态。
|
||||
- 断连只标记该任务取消,清理由监督者等待执行结束后负责;无法确认停止时报告 stopping/interrupted。
|
||||
- 上述步骤只降低 R02/R03 风险,仍不算并行 Endpoint。
|
||||
|
||||
### 10.2 功能开关(新增提案)
|
||||
|
||||
`runtime.isolated_execution`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane`。探测返回 feature version 和限制。二进制版本相同不等于所有 native 插件都有该能力。
|
||||
|
||||
先离线 fixture → 本地假模型 → 新 workspace → 只读 ASK → staging BUILD → 真正发布。禁止对有副作用的请求做双执行 shadow;允许 shadow 只读分析并比较摘要。
|
||||
|
||||
回滚先停接新任务、drain 已接纳任务、保留任务/事件和新 schema;不能将活动任务交给不认识 lease 的旧进程。只读当前发布代可以保留,写入能力按版本协商关闭。ADR 0008 仅在并行金样例与回滚演练通过后由新 ADR 正式替代。
|
||||
|
||||
## 11. 开发包与依赖
|
||||
|
||||
下列新模块路径是建议,不代表文件已存在。
|
||||
|
||||
| 包 | 建议落点与改动 | 前置 | 验收 |
|
||||
|---|---|---|---|
|
||||
| M-R0 基线/缓解 | `host/plugin.rs`、`httpx/routes_invoke.go`;固定并发屏障、旧桥许可、取消清理 | 无 | 双流 busy 不改写 A 的桥;断连无提前清理 |
|
||||
| M-R1 请求上下文 | `workbench/run_context.rs`、`host/subtask.rs`、LLM 插件;统一 token 与显式 sink | M-R0 | 父子运行模型/事件/取消不串;空 token 不取消 |
|
||||
| M-R2 Worker/IPC | 新 `runtime/{supervisor,worker,protocol,lease}.rs`;独立进程与握手 | M-R1 | 两任务并行、超时回收、子进程无孤儿 |
|
||||
| M-R3 接纳/控制 | 新 `runtime/{task_store,scheduler,control}.rs` 与 ext/data 事务 primitives | M-R2 | 原子幂等、队列公平、取消与结果 CAS |
|
||||
| M-R4 事件协议 | `workbench/event_sink.rs`、Web stream/IPC、协议适配器 | M-R3 | 断点恢复/去重/半帧/慢消费/磁盘错误 |
|
||||
| M-R5 读服务/缓存 | `analysis_cache.rs`、`document_view.rs`、`locator.rs`、MLSP transport | M-R1,可独立推进 | 100 同 key 真正只编译一次;嵌套变更正确失效 |
|
||||
| M-R5b 首次编译性能 | `knowledge/compile.rs`、`sema/ir.rs`、ProjectIndex;分阶段 profile 与按热点优化 | 基线语义回归 | 现有 1000 单元门禁恢复;release 与规模曲线报告,身份和语义不变 |
|
||||
| M-R6 提交底座 | `knowledge` generation/manifest、publish journal、条件更新 | M-R3 | 崩溃点恢复,旧代不被半发布污染 |
|
||||
| M-R7 整合与发布 | 版本探测、CI、release、文档/ADR | M-R4–R6 + 产品接入 | §12 全部必要门禁与回滚演练 |
|
||||
|
||||
先以本地文件和单机进程解决明确缺陷;不要把集群、远程 worker、复杂 Actor 系统设为第一阶段依赖。
|
||||
|
||||
## 12. 验收、性能预算与可观测性
|
||||
|
||||
### 12.1 正确性矩阵
|
||||
|
||||
| 编号 | 场景 | 必须观察到的结果 |
|
||||
|---|---|---|
|
||||
| MR-01 | A/B 两个 60s 假模型流 + 20 次/s 模型/设置读取 | 两流不混字、不混模型;短请求 200;无 interpreter busy |
|
||||
| MR-02 | B 在 A 运行时接纳失败/断连 | A 事件和取消句柄完全不变 |
|
||||
| MR-03 | 同时取消 A、完成 B;取消重复/晚到 | A 正确停;B 成功;终态不回退;审计只结算一次 |
|
||||
| MR-04 | 帧拆字节、多行、EOF 半帧、重连 | 无丢字/重字;协议错误可见;游标恢复精确 |
|
||||
| MR-05 | 慢消费者、磁盘满、worker 崩溃 | 内存有界;事件不静默丢失;状态可恢复 |
|
||||
| MR-06 | 100 个相同读取并发 | 实际编译一次;后续结果复用;失败 leader 不挂死 follower |
|
||||
| MR-07 | 改子目录依赖、第 201 个文件、配置、来源 | SnapshotKey 改变;缓存失效;旧业务句柄拒绝 |
|
||||
| MR-08 | 上传有写文件/网络代码、HTML 事件属性 | 阅读不求值;浏览器脚本不执行;正文可读 |
|
||||
| MR-09 | 发布每个持久化边界 kill | 仅旧完整代或新完整代可见;DB 投影最终追上 |
|
||||
| MR-10 | 并发幂等请求、取消队列、权限撤回 | 单一 task;同键异内容 409;无越权派发 |
|
||||
| MR-11 | kill 后副作用未知 | 不自动重放,显示 needs_reconciliation |
|
||||
| MR-12 | 降级/升级、混合 CLI/ext/native | 缺能力明确禁用,不报已支持 |
|
||||
|
||||
### 12.2 性能目标(待测验收预算)
|
||||
|
||||
基准机:Linux 4 vCPU/8 GiB SSD;release 构建;1000 个知识单元、文档总量 10 MiB、500 条历史 run;假上游固定 60s、每秒 20 个增量;30s 预热、5min 采样、3 轮,报告 p50/p95/p99、错误率、CPU、RSS、磁盘。另测 10k 单元和 100 MiB 以确定容量上限,不能直接沿用小数据阈值。
|
||||
|
||||
| 指标 | 初始预算 | 说明 |
|
||||
|---|---|---|
|
||||
| 短读/任务接纳 | p95 ≤200ms,p99 ≤500ms | 两个长任务运行时;过载拒绝另统计 |
|
||||
| 取消受理 | p95 ≤200ms | 独立于任务停止耗时 |
|
||||
| 协作取消收敛 | p95 ≤2s | 假上游/可中断工具;不可中断外部动作按不确定处理 |
|
||||
| 已就绪 worker 调度 | p95 ≤100ms | 不含排队、模型首 token 时间 |
|
||||
| 事件到订阅者新增延迟 | p95 ≤100ms | 从已收到 provider delta 计,不承诺上游 TTFT |
|
||||
| 1000 单元首次分析 | p95 ≤2s | 候选目标,超标先剖析,不降低正确性 |
|
||||
| 热 DocumentView | p95 ≤100ms | 真实复用结果;长文档另测分页 |
|
||||
| 慢消费者缓冲 | 每订阅 ≤256 KiB | 总连接数也必须受限 |
|
||||
| 压测结束内存 | 稳态可回收、无持续增长 | 记录每次重复轮次 RSS;不能只看一次峰值 |
|
||||
|
||||
新指标至少有 queue_depth/wait、worker_active/recycle、admission_rejected、cancel_ack/stop、orphan_count、event_lag/replay/duplicate、compile_invocations/cache_result_hit、publish_conflict/recovery。指标标签禁止 task_id、原始路径、prompt 等高基数/敏感值;trace 中可记录脱敏 task/attempt/lease 与构建摘要。
|
||||
|
||||
现有测试继续保留:`cargo test --offline --locked --test workbench_contracts --test executable_knowledge`、LLM 插件单测、Go httpx 测试。新增集成门禁必须启动真实 HTTP→IPC→worker 路径并使用本地假模型;不能以手写 fixture 或写 token 文件代替端到端行为。本轮执行结果统一记录在[跨库复核 §5](../../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md)。
|
||||
@@ -0,0 +1,443 @@
|
||||
# 知识分层:原始语料、可执行知识、调用面
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Design Review · Recommended(v2.1 语法设计评审)** |
|
||||
| 日期 | 2026-10-23 |
|
||||
| 问题 | 「诗人类 → 用李白知识实例化 → `[]()` 调用」的三/四层模型,从**语法设计**上是否自洽? |
|
||||
| 推荐 | **单体知识类(singleton knowledge class)**:`# 诗人` 是类,`# 李白 = > 诗人` 是知识个体;`李白.出生年份` 是类调用;零新语法 |
|
||||
| 关联 | [link-syntax.md](link-syntax.md) · [objects.md](objects.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) · [okf.md](okf.md) |
|
||||
| 示例 | [examples/knowledge-layers/](../../examples/knowledge-layers/) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论先行
|
||||
|
||||
### 0.1 一句话
|
||||
|
||||
> **分层逻辑是自洽的;不自洽的是「实例化」这个词与当前 `#`/`= >` 语法。**
|
||||
> 如果「实例化」指**知识个体**,用 `# 李白 = > 诗人` 编码即可,零新语法;
|
||||
> 如果「实例化」指**运行时对象**,就需要新的可寻址实例声明/注册表,语法成本明显更高。
|
||||
|
||||
### 0.2 三层 / 四层:推荐四层
|
||||
|
||||
| 层 | 名称 | 内容 | 语法载体 |
|
||||
|----|------|------|---------|
|
||||
| **L0** | 原始语料 | 原文、出处、引用、版本 | `.md` / `.mq.md` 叙述 + `来源` 表 |
|
||||
| **L1** | 本体 / 模式 | 类、字段、类型、约束 | `# 诗人` + 字段/类型表 |
|
||||
| **L2** | 可执行知识 | 知识个体、事实、返回值、出处 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` |
|
||||
| **L3** | 调用面 | 链接、类调用、view、LinkInfo、EKC、agent | `[出生年份](李白.出生年份)` |
|
||||
|
||||
三层版可以把 L1/L2 合并为「可执行知识体系」;四层版把**本体**与**个体**分开,正好对应 EKC 的 schema/knowledge 分层。
|
||||
|
||||
### 0.3 核心判断
|
||||
|
||||
| 判断 | 结论 |
|
||||
|------|------|
|
||||
| 原始语料 → 可执行知识 → 调用面,逻辑成立 | ✅ |
|
||||
| 可执行知识能还原/验证回原始语料 | ✅ 需要出处/校验约定,语法上可行 |
|
||||
| `# 诗人` 是类 | ✅ 现有 `#` 语义 |
|
||||
| `# 李白 = > 诗人` 是「实例化」 | ⚠️ **语法上是继承/特化,不是运行时实例化** |
|
||||
| `李白.出生年份` 是类调用 | ✅ 需要类函数 + 项目类索引(v2.1 目标) |
|
||||
| `[]()` 是调用面,不新增语法 | ✅ `[描述](类.函数)` = 描述 + 已有调用 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 你的模型(精确复述)
|
||||
|
||||
1. 有一个**诗人**类(`# 诗人`),定义诗人应该有什么字段/函数;
|
||||
2. 用**李白的知识**把这个类「实例化」:
|
||||
- 李白是诗人;
|
||||
- 李白有姓名、出生年份等事实;
|
||||
3. 通过 `[]()` 链接语法调用这个知识:
|
||||
- `[出生年份](李白.出生年份)`;
|
||||
4. 整个体系分层:
|
||||
- 原始语料;
|
||||
- 改写/抽象后的可执行知识(可还原验证回原始知识);
|
||||
- 智能体回答/思考时的调用面。
|
||||
|
||||
这个模型在**知识架构**上没有问题;问题只在第 2 步的「实例化」如何落到语法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前语法事实
|
||||
|
||||
| 语法 | 当前语义 | 对模型的影响 |
|
||||
|------|---------|-------------|
|
||||
| `# 诗人` | 类/类型;正文是构造体 | ✅ 可做本体 |
|
||||
| `# 李白 = > 诗人` | **继承/子类**;不是实例 | ⚠️ 与「实例化」字面不符 |
|
||||
| `## 李白的出生年份` | 方法;可用 `self`/`自` | ⚠️ 当前是实例方法 |
|
||||
| `> 李白` | 构造实例(map + `_type`) | ✅ 运行时实例 |
|
||||
| `李白.李白的出生年份` | 当前被当变量/实例方法路径 | ❌ 类调用未实现 |
|
||||
| `[描述](...)` | 描述 + 表达式 | ✅ 调用面 |
|
||||
| `import` | 跨文档绑定 | ⚠️ 当前跨文档继承/调用需 import |
|
||||
|
||||
**实测**(`marqdo 2.0.0`):
|
||||
|
||||
- `# 李白 = > 诗人` 在**另一个文档**定义 `# 诗人` 时,未 import 会报 `unknown base type 诗人`;
|
||||
- import 后可以继承,但调用仍需 `> libai.李白` 构造实例,再 `` `li`.李白的出生年份() `` → `701`;
|
||||
- `李白.李白的出生年份` 直接调用报 `undefined variable`;
|
||||
- 跨文档类索引不存在。
|
||||
|
||||
所以「诗人类 → 李白实例 → 链接调用」在**目标模型**上成立,在**当前语法**上只完成了「类 + 继承 + 实例方法」,缺「类调用 + 类索引」。
|
||||
|
||||
---
|
||||
|
||||
## 3. 自洽性检查:逐层
|
||||
|
||||
### 3.1 L0 原始语料
|
||||
|
||||
| 问题 | 结论 |
|
||||
|------|------|
|
||||
| 原始语料是否可执行? | 否;它是出处,不是程序 |
|
||||
| 能否被引用? | ✅ 现有 Markdown 相对链接/`来源` 表 |
|
||||
| 能否保留原文? | ✅ 叙述、引用块、表格 |
|
||||
| 语法负担 | 零:就是现有文档 |
|
||||
|
||||
**要点**:原始语料必须保持「不可执行」的独立身份;一旦把原文改写成代码,就失去了「还原验证」的基准。所以 L0 与 L2 要**物理/逻辑分离**(`corpus/` vs `knowledge/`)。
|
||||
|
||||
### 3.2 L1 本体 / 模式
|
||||
|
||||
```markdown
|
||||
# 诗人
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 姓名 | text | 诗人姓名 |
|
||||
| 出生年份 | number | 公元年份 |
|
||||
```
|
||||
|
||||
| 问题 | 结论 |
|
||||
|------|------|
|
||||
| `# 诗人` 能否表达类? | ✅ `#` 就是类/类型 |
|
||||
| 字段/类型能否表达? | ✅ 现有表格 + 契约表 |
|
||||
| 是否需要新语法? | ❌ 不需要;用字段/类型表的列名约定 |
|
||||
| 是否能被检查? | 需要新增 `knowledge.schema_*` 检查(工具,不是语法) |
|
||||
|
||||
**语法结论**:L1 完全用现有 `#` + 表格;只需要约定「字段表」的列名与语义。
|
||||
|
||||
### 3.3 L2 可执行知识:关键歧义
|
||||
|
||||
「用李白的知识实例化诗人」有两种落法:
|
||||
|
||||
#### A. 单体知识类(推荐)
|
||||
|
||||
```markdown
|
||||
# 李白 = > 诗人
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
- 语法:`# 李白 = > 诗人` = 继承/特化;
|
||||
- 语义:李白是诗人(is-a),并且 `# 李白` 是一个**命名的知识个体**;
|
||||
- 调用:`李白.李白的出生年份` = 类调用(不使用 `self` 的函数);
|
||||
- 地址:`# 李白` 是文档里的稳定类名,可被项目类索引解析;
|
||||
- 运行时:如果需要 map,仍可 `> 李白` 构造实例;
|
||||
- 代价:**术语上不是「实例」**,是「单体类/知识个体」。
|
||||
|
||||
#### B. 运行时实例(不推荐作为 v2.1 语法)
|
||||
|
||||
```markdown
|
||||
# 诗人
|
||||
|
||||
## 李白
|
||||
|
||||
*> 诗人 姓名="李白" 出生年份=701*
|
||||
```
|
||||
|
||||
- 语法:`## 李白` 是函数,返回一个实例 map;
|
||||
- 调用:`李白().出生年份`(函数返回实例,再取方法);
|
||||
- 地址:`李白` 是函数名,不是实体;跨文档要函数索引/缓存;
|
||||
- 代价:每次调用可能新构造实例;没有稳定的知识实体地址;EKC 节点是函数,不是个体;
|
||||
- 需要:实例注册表/导出机制,或函数级索引;这比 A 多一层运行时概念。
|
||||
|
||||
#### C. 显式个体声明(未来可选)
|
||||
|
||||
```markdown
|
||||
# 李白 : 诗人
|
||||
```
|
||||
|
||||
- `:` 明确「李白是诗人个体」;
|
||||
- 语法更贴近本体(instance-of),但**新增一个标记**;
|
||||
- 与 `# Child = > Parent` 形成两种关系,需要决定何时用哪种;
|
||||
- 不建议 v2.1 引入;可作为 v2.2 的候选。
|
||||
|
||||
### 3.4 L3 调用面
|
||||
|
||||
```markdown
|
||||
[出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
| 问题 | 结论 |
|
||||
|------|------|
|
||||
| `[]` 是描述、`()` 是调用? | ✅ 现有语义 |
|
||||
| `()` 与 `**` 同权? | ✅ 同一 parser/evaluator |
|
||||
| 跨文档类名能否解析? | 需要项目类索引(v2.1) |
|
||||
| 正文链接是否执行? | view/check 解析;run 不执行(安全) |
|
||||
| 终端输出? | 代码链接 + `print` |
|
||||
| 编译器能否返回 LinkInfo? | 需要新增(工具,不是语法) |
|
||||
| view 能否显示调用点? | 需要新增(工具,不是语法) |
|
||||
|
||||
**语法结论**:L3 不需要新语法;缺的是**解析器/类索引/视图/编译器输出**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 推荐模型:单体知识类
|
||||
|
||||
### 4.1 定义
|
||||
|
||||
> **单体知识类**:一个 `# 名称 = > 父类` 的类,代表一个知识个体;它的 `##` 函数是该个体的知识字段/事实;它不需要运行时实例即可被 `类.函数` 调用。
|
||||
|
||||
```markdown
|
||||
# 诗人
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 姓名 | text | 诗人姓名 |
|
||||
| 出生年份 | number | 公元年份 |
|
||||
|
||||
# 李白 = > 诗人
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
| 返回 | 类型 | 来源 |
|
||||
|------|------|------|
|
||||
| 701 | number | corpus/libai.md#出生年份 |
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
调用:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出:`701`。
|
||||
|
||||
### 4.2 为什么推荐 A
|
||||
|
||||
| 维度 | A 单体类 | B 运行时实例 |
|
||||
|------|---------|-------------|
|
||||
| 语法新增 | **零** | 需要实例导出/注册/函数索引 |
|
||||
| 地址稳定 | ✅ 类名 | ❌ 函数返回值 |
|
||||
| 跨文档 | ✅ 项目类索引 | ❌ 需要实例注册表 |
|
||||
| EKC 映射 | ✅ 文档/类/函数节点 | ❌ 实例不是文档节点 |
|
||||
| 可还原 | ✅ 类/函数 + 来源表 | ⚠️ 实例是运行时值 |
|
||||
| 可检查 | ✅ 类/函数/契约 | ⚠️ 实例状态难静态检查 |
|
||||
| 术语 | ⚠️ 叫「个体」不叫「实例」 | ✅ 叫实例 |
|
||||
| 多实例 | ⚠️ 每个个体一个类 | ✅ 自然 |
|
||||
|
||||
**结论**:在「文档即知识库」的约束下,A 的语法成本最低、可检查性最好;B 的「实例」语义更纯,但需要新的运行时/注册表,和「零新语法」冲突。
|
||||
|
||||
### 4.3 术语约定
|
||||
|
||||
| 术语 | 含义 | 语法 |
|
||||
|------|------|------|
|
||||
| **类 / 本体** | 诗人的模式 | `# 诗人` |
|
||||
| **知识个体(单体类)** | 李白这个知识实体 | `# 李白 = > 诗人` |
|
||||
| **知识字段 / 事实** | 李白的出生年份 | `## 李白的出生年份` + `*701*` |
|
||||
| **类调用** | 读取知识个体的字段 | `李白.李白的出生年份` |
|
||||
| **运行时实例** | 代码里 `> 李白` 得到的 map | `> 李白` / `_type` |
|
||||
| **知识链接** | 描述 + 类调用 | `[出生年份](李白.李白的出生年份)` |
|
||||
|
||||
> **重要**:语法文档里不要再用「实例化」描述 `# 李白 = > 诗人`;用「知识个体化/单体类」。
|
||||
> 「实例」保留给运行时 `> 诗人` 产生的 map。这样语法、文档、EKC 三者才一致。
|
||||
|
||||
### 4.4 多诗人怎么办
|
||||
|
||||
```markdown
|
||||
# 李白 = > 诗人
|
||||
# 杜甫 = > 诗人
|
||||
# 王维 = > 诗人
|
||||
```
|
||||
|
||||
- 每个个体是一个单体类;项目类索引登记它们;
|
||||
- `李白.出生年份` / `杜甫.出生年份` 分别解析;
|
||||
- 这是「命名个体注册表」,不是运行时实例集合;
|
||||
- 如果个体成千上万,类索引会变大;v2.2 可引入表驱动的个体注册(但不改变调用语法)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 EKC 的映射
|
||||
|
||||
| 层 | EKC 层 | 节点/边 |
|
||||
|----|--------|---------|
|
||||
| L0 原始语料 | Repository / sources | `documented_by` / `derived_from` |
|
||||
| L1 本体 | Capability / Schema | `# 诗人` class 节点 |
|
||||
| L2 知识个体 | Knowledge / Symbol | `# 李白` class 节点 + `##` fact 节点;`specializes` 边 → `诗人` |
|
||||
| L3 调用面 | Symbol / Capability | `[]()` 链接 → `calls` 边;LinkInfo |
|
||||
| L4 Agent | Agent / Context Pack | `find`/`reuse`/`link.resolve` |
|
||||
|
||||
**新增边(建议)**:
|
||||
|
||||
- `specializes`:`# 李白 = > 诗人`(语法上是继承;知识语义上是 is-a);
|
||||
- `derived_from`:fact → 原始语料;
|
||||
- `calls`:调用文档 → `李白.出生年份`;
|
||||
- `has_fact`:`# 李白` → `## 出生年份`。
|
||||
|
||||
EKC 现有 `depends_on`/`uses`/`implements`/`documented_by` 可以复用;`specializes` 建议新增。
|
||||
|
||||
---
|
||||
|
||||
## 6. 还原 / 验证(L2 → L0)
|
||||
|
||||
「可执行知识能还原验证回原始知识」需要三件事:
|
||||
|
||||
### 6.1 出处是数据,不是注释
|
||||
|
||||
```markdown
|
||||
## 李白的出生年份
|
||||
|
||||
| 返回 | 类型 | 来源 |
|
||||
|------|------|------|
|
||||
| 701 | number | corpus/libai.md#出生年份 |
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
- `来源` 列指向原始语料(路径 + 标题/锚点);
|
||||
- 也可以放 frontmatter `sources:`;
|
||||
- `check` 验证来源存在;`verify` 验证值/引文一致(能自动化的部分)。
|
||||
|
||||
### 6.2 可还原的渲染
|
||||
|
||||
- `view` 把 `# 李白` 渲染成「知识文档」:字段 + 值 + 来源;
|
||||
- `catalog` 生成 OKF `Fact` 页,`resource:` 指向 `.mq.md`;
|
||||
- 渲染结果与原始语料可人工/机器对照;
|
||||
- 这不是新语法,是 view/catalog 的输出。
|
||||
|
||||
### 6.3 漂移检查
|
||||
|
||||
| 诊断 | 触发 |
|
||||
|------|------|
|
||||
| `knowledge.source_missing` | 事实没有来源 |
|
||||
| `knowledge.source_dangling` | 来源路径/锚点不存在 |
|
||||
| `knowledge.value_mismatch` | 事实值与来源引文不一致(可自动判断时) |
|
||||
| `knowledge.schema_mismatch` | `# 李白` 字段与 `# 诗人` 不匹配 |
|
||||
| `knowledge.fact_drift` | 原始语料变了,知识未复核 |
|
||||
|
||||
这些是**工具诊断**,不是语法。
|
||||
|
||||
---
|
||||
|
||||
## 7. 调用面:智能体如何使用
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
用户想知道李白的出生年份,我们回答:[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
- `view` 显示:`李白.李白的出生年份` → `701` → 来源 `corpus/libai.md#出生年份`;
|
||||
- `check --json` 返回 LinkInfo(class/function/value/source);
|
||||
- agent 通过 `link.resolve` / `find` 取到值 + 出处,回答时可引用来源;
|
||||
- `run` 加 `print` 才输出;正文链接不执行,保证叙述安全。
|
||||
|
||||
**这就是「调用面」**:不是自然语言猜,而是可解析、可验证、可引用的类调用。
|
||||
|
||||
---
|
||||
|
||||
## 8. 反例与边界
|
||||
|
||||
| 场景 | 用 A 单体类 | 说明 |
|
||||
|------|-----------|------|
|
||||
| 李白、杜甫、王维 | 三个单体类 | 类索引;命名个体 |
|
||||
| 同一诗人的多个版本 | 多个事实/来源,或子个体 | 版本是事实维度,不是实例 |
|
||||
| 需要运行时状态(可变对象) | `> 李白` 构造实例 | 运行时实例仍存在,但与知识个体分离 |
|
||||
| 上千个诗人 | 类索引/表驱动注册 | v2.2 优化;语法不变 |
|
||||
| 需要 `instanceof` | `# 李白 = > 诗人` 的 `specializes` 边 | 知识语义;不是运行时 `_type` |
|
||||
| 需要多继承 | 现有不支持 | 不在本设计范围 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 决策建议
|
||||
|
||||
1. **v2.1 采用 A(单体知识类)**:`# 诗人` + `# 李白 = > 诗人` + `##` 事实 + `[]()` 类调用;零新语法。
|
||||
2. **术语冻结**:`# 李白 = > 诗人` 叫「知识个体/单体类」,不叫「实例」;`> 诗人` 才是运行时实例。
|
||||
3. **补类函数与类索引**:不使用 `self` 的 `##` 是类函数;项目类索引解析跨文档 `李白`。
|
||||
4. **补出处/验证**:`来源` 列或 `sources:`;`check`/`verify`;`view`/`catalog` 可还原。
|
||||
5. **EKC 边**:`specializes` / `derived_from` / `calls` / `has_fact`。
|
||||
6. **保留 B/C 作为未来**:如果真需要运行时实例/个体声明,再评估 `# 李白 : 诗人` 或实例注册表;不在 v2.1 引入。
|
||||
|
||||
### 9.1 备选:frontmatter 个体声明(零语法,但换元数据)
|
||||
|
||||
如果不想把 `= >` 的继承语义借给「个体」,可以用 frontmatter 标记:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: Individual
|
||||
class: 诗人
|
||||
id: libai
|
||||
---
|
||||
|
||||
# 李白
|
||||
|
||||
## 出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
| 维度 | 单体类 A | frontmatter 个体 |
|
||||
|------|----------|------------------|
|
||||
| 可见性 | `# 李白 = > 诗人` 一眼可见 | 类型在 frontmatter,正文只看到 `# 李白` |
|
||||
| 语法 | 现有 `= >` | 现有 frontmatter,无新标记 |
|
||||
| 语义纯度 | 继承/特化 | 明确 individual-of |
|
||||
| EKC | class + specializes | individual + instance_of |
|
||||
| 代价 | 术语「个体」不是「实例」 | 两套 is-a 表达(`= >` 与 `class:`)需要约定 |
|
||||
|
||||
**建议**:v2.1 先用 A(可读、零语法);如果 EKC/本体需要严格区分 class/individual,再启用 frontmatter `type: Individual`,并规定「`= >` 只用于类-类,个体用 frontmatter」。
|
||||
|
||||
---
|
||||
|
||||
## 10. 结论
|
||||
|
||||
> **三层/四层模型自洽;「实例化」是唯一需要修正的词。**
|
||||
> 在 Marqdo 的语法里,`# 李白 = > 诗人` 是**继承/特化**,不是运行时实例;
|
||||
> 把它用作**单体知识类**,就能在不新增语法的情况下得到「李白是诗人、李白有出生年份、`李白.出生年份` 可调用」。
|
||||
> 这正是 EKC 的「文档即知识、知识可执行」:**类是本体的地址,单体类是知识个体的地址,`[]()` 是调用面。**
|
||||
|
||||
---
|
||||
|
||||
## 附录 A:一页对照
|
||||
|
||||
```markdown
|
||||
# L1 本体
|
||||
# 诗人
|
||||
| 字段 | 类型 | 说明 |
|
||||
| 姓名 | text | ... |
|
||||
| 出生年份 | number | ... |
|
||||
|
||||
# L2 知识个体(单体类)
|
||||
# 李白 = > 诗人
|
||||
## 李白的出生年份
|
||||
| 返回 | 类型 | 来源 |
|
||||
| 701 | number | corpus/libai.md#出生年份 |
|
||||
*701*
|
||||
|
||||
# L3 调用面
|
||||
[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
| 层 | 语法 | 语义 |
|
||||
|----|------|------|
|
||||
| L0 | `.md` 原文 + 来源 | 不可执行 |
|
||||
| L1 | `# 诗人` + 字段表 | 类/模式 |
|
||||
| L2 | `# 李白 = > 诗人` + `##` + `*701*` | 知识个体/事实 |
|
||||
| L3 | `[描述](类.函数)` | 类调用/链接 |
|
||||
| 运行时 | `> 诗人` / `> 李白` | map 实例(可选) |
|
||||
|
||||
## 附录 B:与现有文档的关系
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [link-syntax.md](link-syntax.md) | 调用面的语法;本文补知识分层与单体类 |
|
||||
| [objects.md](objects.md) | `#`/`##`/`= >` 的对象模型;本文把 `= >` 用于知识个体 |
|
||||
| [module-namespace.md](module-namespace.md) | 跨文档解析;本文用项目类索引 |
|
||||
| [engineering-knowledge.md](engineering-knowledge.md) | EKC L0–L4;本文映射到四层 |
|
||||
| [okf.md](okf.md) | Fact/Concept/路径即身份;本文的 L2 与 Fact 对应 |
|
||||
@@ -0,0 +1,414 @@
|
||||
# 纯度路线细化 + 标签过期检测:面向可执行知识体系的一致性机制
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**(含语法落地、诊断 schema、分阶段计划) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 决策来源 | 用户:取**纯度**;标签**可省略但编译器须报错**;循环写法不重要;**重点:标签过期与 agent 误导** |
|
||||
| 前置 | [bracket-as-label-evaluation.md](bracket-as-label-evaluation.md) |
|
||||
| 依托设施 | `src/diagnostics.rs`(`doc_anchor`/`doc_quote`/`contract_ref`)· `src/mlsp.rs`(`validate`/`repair_targets`/`repair_apply`)· `src/repair.rs`(有界修复)· `src/knowledge/fingerprint.rs` · `src/knowledge/lifecycle.rs`(已有 `find_stale`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 决策记录与一个推论
|
||||
|
||||
**已定**:
|
||||
|
||||
1. **纯度**:`()` 只装机器语句,`[]` 只装人话;取元搬进 `()`。
|
||||
2. **标签可省略,但编译器报错**:写空方括号是可能的,但那是一个**错误**。
|
||||
3. **循环写法从简**:`[]` 已是描述,`()` 内部只要自洽即可。
|
||||
|
||||
**由此得到一个必须先说清的推论**:
|
||||
|
||||
> **纯度强制两件东西同时存在**:
|
||||
> ① 一个**不带标签**的普通表达式写法(否则每个访问都被迫配一段人话 = 仪式感复辟);
|
||||
> ② 带标签的形式作为一个**可选包装**。
|
||||
|
||||
也就是说 `[标签](表达式)` 不是"唯一的表达式语法",而是"**当你想做断言时才用的包装**"。
|
||||
这一条同时解决了我在上一份文档里担心的"标签凑数"退化:
|
||||
**不想断言,就别用这个形式**——而不是"必须写标签但可以写废话"。
|
||||
|
||||
---
|
||||
|
||||
## 1. 纯度路线下的语法落地
|
||||
|
||||
### 1.1 形式
|
||||
|
||||
```
|
||||
带标签表达式 ::= '[' 人话 ']' '(' 表达式 ')'
|
||||
```
|
||||
|
||||
- `表达式` = **现有 Marqdo 表达式文法**(不新增语言)
|
||||
- `人话` = 任意自然语言,必须是**关于这个值的断言**(§2)
|
||||
- 出现位置:表达式位置、语句位置、循环位置
|
||||
|
||||
### 1.2 关键缺口:普通取元怎么写
|
||||
|
||||
纯度之后 `[键](集合)` 不再是取元,所以必须给出**不带标签的取元写法**。四个候选:
|
||||
|
||||
| 方案 | 写法 | 优 | 劣 |
|
||||
|------|------|----|----|
|
||||
| **A 现有内建** | `[第一项](at value=篮子 index=1)` | 零新语法,今天就能实现 | 啰嗦;`value=`/`index=` 是机器腔 |
|
||||
| **B 后置方括号** | `[第一项](篮子[1])` | 最像通用语言;`篮子[拿铁]` 读起来自然 | `[]` 出现两种角色(前置=人话,后置=索引),视觉易混 |
|
||||
| **C 函数式 + 逗号参数** | `[第一项](at(篮子, 1))` | 与 `加一函数(31)` 统一;顺带解决前几轮想要的 `f(args)` | 需支持逗号分隔实参(要改参数分词器) |
|
||||
| D 点号 | `[拿铁价格](菜单.拿铁)` | 短 | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形 |
|
||||
|
||||
**我的建议**:**C**。
|
||||
|
||||
理由:你前面想要 `f(args)` 这种"人读友好"的调用,而 C 与它**同一个改动**——
|
||||
一次性把 `()` 内的表达式升级为「可带括号实参」的形式,
|
||||
`at(篮子, 1)`、`加一函数(31)`、`get(菜单, 拿铁)` 全部成立,且不新增第二种方括号角色。
|
||||
代价是参数分词器要支持 `)` 终止与逗号(前几轮原型已验证方向可行,全量 554/0 回归)。
|
||||
|
||||
若你希望**零实现风险**,选 A:今天就能用,只是啰嗦,后续可再收窄成 C。
|
||||
|
||||
### 1.3 空标签 = 硬错误
|
||||
|
||||
```markdown
|
||||
[](at(篮子, 1)) # ❌ label.missing
|
||||
```
|
||||
|
||||
诊断:`code: "label.missing"`,`severity: error`,`doc_quote: "[]"`,建议:
|
||||
「给这段语句写一句人话描述,或改用不带标签的普通表达式」。
|
||||
|
||||
**这一条是整套设计的门槛**:它把"标签"从可选装饰变成"用了就得负责"的承诺。
|
||||
也正好落实你说的「可以省略,但编译器应当报错」。
|
||||
|
||||
### 1.4 循环
|
||||
|
||||
你说不重要,那我给最省事、且与纯度一致的一条:
|
||||
|
||||
```markdown
|
||||
- [从篮子取出的每个果子](foreach 篮子 为 果)
|
||||
```
|
||||
|
||||
- `[]` 是描述(人读)
|
||||
- `()` 是机器语句:遍历什么、绑定给谁
|
||||
- 循环变量名从 `[]` **搬进 `()`**——因为 `[]` 不再承担绑定职责
|
||||
|
||||
若嫌 `foreach 篮子 为 果` 太新,可就近用现有词:
|
||||
`- [从篮子取出的每个果子](遍历 篮子 绑定 果)`。
|
||||
**关键是别再让 `[]` 兼任变量名**——否则"描述"与"标识符"又会打架。
|
||||
|
||||
---
|
||||
|
||||
## 2. 标签是什么:**可校验断言的载体**
|
||||
|
||||
标签不是注释。三者区别:
|
||||
|
||||
| | 注释 | 标签 |
|
||||
|---|------|------|
|
||||
| 位置 | 游离于代码之外 | **锚定在 AST 节点上**(有 span,可定位) |
|
||||
| 可核验 | 不能 | **能**(§3) |
|
||||
| 可进修复协议 | 不能 | **能**(随诊断导出给 LLM) |
|
||||
| 变更感知 | 无 | **能**(代码变了会撞上旧断言) |
|
||||
|
||||
一句话:**标签 = 贴在可执行片段上、可被机器复核的断言。**
|
||||
这正是 Marqdo 相对传统"文档 + 注释"的核心增量。
|
||||
|
||||
---
|
||||
|
||||
## 3. 过期检测:三层机制
|
||||
|
||||
你问的核心是:**`()` 改了,怎么让 `[]` 的旧描述"叫起来"。**
|
||||
这需要三种能力,缺一不可,且分属不同层。
|
||||
|
||||
### 3.1 L1 引用一致性(无状态、确定性、零成本)
|
||||
|
||||
**规则**:标签内用反引号写出的名字 = **实体断言**。
|
||||
|
||||
```markdown
|
||||
[按 `税率` 计算总价](...)
|
||||
```
|
||||
|
||||
可核验的断言:
|
||||
|
||||
1. `` `税率` `` 必须**可解析**(在当前作用域/模块里存在)
|
||||
2. 它必须**出现在 `()` 的实际内容中**(或经调用链可达)
|
||||
|
||||
任一条不成立 → `label.stale`(引用已腐烂)。
|
||||
|
||||
**为什么低假阳性**:只有**显式反引号**才算断言,普通汉字不参与判定。
|
||||
这复用了 Marqdo 已有的 `` `名` `` = 实体 的约定,**没有新增记号**。
|
||||
|
||||
**局限(必须承认)**:它只查"引用",查不出"语义"。
|
||||
`税率` 还在,但操作从"乘"改成"除",L1 看不见。
|
||||
|
||||
### 3.2 L2 指纹台账(有状态、能查语义腐烂)
|
||||
|
||||
**做法**:把「标签写下时,它描述的那段代码」记一份指纹。
|
||||
|
||||
`.marqdo/labels.json`(与 EKC 产物同目录,视为**缓存**):
|
||||
|
||||
```json
|
||||
{
|
||||
"按税率计算总价#1": {
|
||||
"code_fingerprint": "9f2a…",
|
||||
"code_quote": "at(税率表, 档位) * 金额",
|
||||
"confirmed_at": "2026-10-22T09:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `code_fingerprint`:复用 `src/knowledge/fingerprint.rs`(已有 `collect_calls` / `ops_hint` / `fingerprint_hash`)
|
||||
→ **调用与运算变了,指纹就变**
|
||||
- `code_quote`:**旧代码的文本快照**——这就是你说的"保留内容用于校验"的对称物:
|
||||
`doc_quote` 保留 `[]`,`code_quote` 保留 `()`,两者一起导出给 LLM 对比
|
||||
- 键 = `规范化标签文本 + 同文本序号`(按标签键而不是按行号,**移动代码不会误报**)
|
||||
|
||||
**命中规则**:
|
||||
|
||||
| 变化 | 判定 |
|
||||
|------|------|
|
||||
| `()` 指纹变 | **stale**:标签描述的代码已变,需复核 |
|
||||
| 标签文本变 | **新断言**:无历史,首次确认即可 |
|
||||
| 两者都没变 | 通过 |
|
||||
|
||||
**局限**:需要状态文件;合并冲突要处理(§8.2)。
|
||||
|
||||
### 3.3 L3 LLM 复核(修复协议闭环)
|
||||
|
||||
诊断被导出时同时携带三方信息:
|
||||
|
||||
- `doc_quote`:`[]` 里的原话
|
||||
- `code_past`:`()` 当时的文本(来自台账)
|
||||
- `code_now`:`()` 现在的文本
|
||||
|
||||
模型据此判定三选一:
|
||||
|
||||
1. **改标签**(代码意图是对的,描述过期了)
|
||||
2. **改代码**(描述是对的,实现跑偏了)
|
||||
3. **确认无害**(改动不影响断言,写回台账 `confirmed`)
|
||||
|
||||
这正好接进**已有的修复回路**(`src/repair.rs`):`validate` → `repair_targets` → 模型行编辑 →
|
||||
`repair_apply`(越界必拒)→ 复验。
|
||||
|
||||
### 3.4 为什么三层都要
|
||||
|
||||
| 层 | 查什么 | 能否查"乘改除" | 需要状态 | 假阳性 |
|
||||
|----|--------|--------------|---------|--------|
|
||||
| L1 | 引用腐烂(改名/删除) | ❌ | 无 | 极低 |
|
||||
| L2 | 语义腐烂(同引用、不同操作) | ✅ | 需台账 | 中(无害改动也报) |
|
||||
| L3 | 谁错了(标签 or 代码) | ✅ | 复用 L2 | 由模型判 |
|
||||
|
||||
**L1 是地基**(确定性、零成本、可先上),**L2 是覆盖**(能查语义),**L3 是裁决**(谁改)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与现有设施的对接(这决定了落地成本)
|
||||
|
||||
### 4.1 诊断字段:**已经齐备,不需要新造**
|
||||
|
||||
`src/diagnostics.rs` 的 `to_json` 已输出:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "…", "severity": "…", "message": "…",
|
||||
"span": {"file":…, "line":…, "col":…},
|
||||
"doc_anchor": …, ← 标签位置
|
||||
"doc_quote": …, ← 标签原文
|
||||
"contract_ref": {"unit":…, "kind":…, "name":…, "declared":…},
|
||||
"suggestion": …
|
||||
}
|
||||
```
|
||||
|
||||
**`contract_ref.declared` 就是"声明"这一侧的先例**:
|
||||
契约诊断说的是「**declared** number,actual text」,
|
||||
标签诊断说的是「**declared(标签里的人话)**,actual(`()` 现在的代码)」——
|
||||
**同一个模式,只是从类型层下沉到散文层。**
|
||||
|
||||
> 这也回答了你的问题:"导出时能否保留 `[]` 的内容用于校验"——
|
||||
> **能,而且字段已经在协议里了**:`doc_quote` 就是它。
|
||||
|
||||
### 4.2 契约诊断是现成的范式
|
||||
|
||||
`src/contract.rs:203` 的 `Contract::diagnostic(...)` 一次性装配
|
||||
`code + severity + suggestion + doc_anchor + doc_quote + contract_ref`。
|
||||
标签诊断可以照抄这套装配,只是 `kind` 从 `"contract"` 换成 `"label"`。
|
||||
|
||||
### 4.3 修复范围:允许"标签行 ∪ 代码行"
|
||||
|
||||
现在 `repair_apply` 的形状是 `ranges: [[起, 止], …]`,**天然支持多个区间**。
|
||||
`label.stale` 只需把两段都放进 ranges:
|
||||
|
||||
| 允许范围 | 原因 |
|
||||
|---------|------|
|
||||
| 标签所在行 | 修法 1:改描述 |
|
||||
| `()` 所在行 | 修法 2:改实现 |
|
||||
|
||||
护栏不变:**越界改动一律拒绝(abstain)**——这正是 `src/repair.rs` 已经强制的语义。
|
||||
|
||||
### 4.4 知识层:`stale` 概念已经存在
|
||||
|
||||
`src/knowledge/lifecycle.rs` 已有 `find_stale` / `stale_json` / `verify`。
|
||||
标签过期可以走**同一条 stale 通道**,进入 EKC/OKF 的
|
||||
`marqdo verify` / `marqdo stale` 报告,成为知识库的健康指标。
|
||||
|
||||
> 这一点很重要:**标签过期 = 知识腐烂**,而 Marqdo 已经有"知识会腐烂"的机制,
|
||||
> 标签只是给它增加了一种新的腐烂类型(文档断言 vs 实现)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 诊断 schema 草案
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "label.stale",
|
||||
"severity": "warning",
|
||||
"message": "标签可能过期:标签提到 `税率`,但当前语句已不再引用它",
|
||||
"span": { "file": "报价.mq.md", "line": 42, "col": 12 },
|
||||
"doc_anchor": { "file": "报价.mq.md", "line": 42, "quote": "按 `税率` 计算总价" },
|
||||
"doc_quote": "按 `税率` 计算总价",
|
||||
"label_ref": {
|
||||
"kind": "label",
|
||||
"text": "按 `税率` 计算总价",
|
||||
"refs": ["税率"],
|
||||
"missing_refs": ["税率"],
|
||||
"code_past": "at(税率表, 档位) * 金额",
|
||||
"code_now": "at(税率表, 档位) / 金额",
|
||||
"fingerprint_past": "9f2a…",
|
||||
"fingerprint_now": "3c71…",
|
||||
"layer": "L2"
|
||||
},
|
||||
"suggestion": "若意图是乘,请还原 `*`;若意图改为除,请把标签改成「按档位折算比例」",
|
||||
"ranges": [[42, 42]]
|
||||
}
|
||||
```
|
||||
|
||||
要点:
|
||||
- 复用 `doc_anchor` / `doc_quote`,**不新造字段名**
|
||||
- `label_ref` 仿 `contract_ref`(`kind: "label"`)
|
||||
- `code_past` / `code_now` 并置 → 模型一眼看出差异
|
||||
- `layer` 标明是 L1 还是 L2 检出(便于分级治理)
|
||||
|
||||
---
|
||||
|
||||
## 6. 工作流
|
||||
|
||||
```
|
||||
作者 / agent 改代码
|
||||
↓
|
||||
marqdo check 或 MLSP validate
|
||||
↓
|
||||
label.stale / label.missing 诊断(带 doc_quote + code_past + code_now)
|
||||
↓
|
||||
MLSP repair_targets(ranges = 标签行 ∪ 代码行)
|
||||
↓
|
||||
LLM 三选一:改标签 / 改代码 / 确认无害
|
||||
↓
|
||||
repair_apply(越界必拒)
|
||||
↓
|
||||
复验 → 通过后写回 .marqdo/labels.json(confirmed_fingerprint 更新)
|
||||
```
|
||||
|
||||
**CI 用法**:
|
||||
- 普通项目:`label.stale` 默认 **warning**(不阻塞)
|
||||
- 知识库项目(OKF/EKC 仓):可配置为 **error**,把"断言必须新鲜"作为门禁
|
||||
|
||||
---
|
||||
|
||||
## 7. 反幻觉:这一步到底解决了什么
|
||||
|
||||
必须把话说准,否则容易过度承诺。
|
||||
|
||||
### 7.1 它解决的**具体一类**
|
||||
|
||||
> **文档断言与实现不一致**(doc–code drift at the claim level)。
|
||||
|
||||
传统文档的失败模式:
|
||||
|
||||
| 失败模式 | 传统文档 | Marqdo(本设计) |
|
||||
|---------|---------|-----------------|
|
||||
| 注释过期 | 无声腐烂 | L1/L2 检出 |
|
||||
| 签名漂移 | 靠类型检查(有) | 契约已有 |
|
||||
| **散文描述与实现不符** | **完全无解** | **本设计**(新能力) |
|
||||
| 知识库引用失效 | 靠人工审阅 | 可机械化 |
|
||||
|
||||
### 7.2 它**不解决**什么
|
||||
|
||||
- 模型凭空编造(幻觉的另一种)
|
||||
- 代码本身写错
|
||||
- 标签写得含糊但"不算错"(L1 查不到,L2 只能报"变了")
|
||||
|
||||
**所以正确的表述是**:
|
||||
> 它把"**文档可信度**"从"靠人自觉"提升到"**可被机械复核 + 可被 LLM 裁决**"。
|
||||
|
||||
### 7.3 为什么这对"可执行知识体系"是决定性的
|
||||
|
||||
一个知识库的价值 = **断言的密度 × 断言的可信度**。
|
||||
传统知识库只能提高密度(多写),无法保证可信度(写完就腐)。
|
||||
Marqdo 若能把"断言→复核"闭环,就第一次让**知识库有了保鲜机制**——
|
||||
这也正好接上 EKC 已有的 `stale` / `verify` 体系。
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险与反对意见(诚实清单)
|
||||
|
||||
### 8.1 误报疲劳(最危险)
|
||||
|
||||
如果 `label.stale` 天天响,用户会在三天内学会忽略它。
|
||||
**对策**:
|
||||
- L1 **只在能证明冲突时报**(引用了不存在的实体 / 引用的实体不在语句里)
|
||||
- L2 **默认只报 warning**,且同一标签同一指纹只报一次(台账记录"已复核")
|
||||
- 诊断里必须给**可执行建议**(改哪一行、改成什么),否则就是噪音
|
||||
|
||||
### 8.2 台账的腐烂与合并冲突
|
||||
|
||||
`.marqdo/labels.json` 是缓存,不是真相。对策:
|
||||
- 语义上**可丢弃**:删掉后重建,最多一次全量确认
|
||||
- 合并冲突策略:**重算优先**(以代码指纹为准,冲突时保留 `confirmed_at` 较新者)
|
||||
- 不放进版本库时(`.gitignore`),退化为"本地提示";放进版本库时,成为团队级门禁
|
||||
|
||||
### 8.3 语义鸿沟
|
||||
|
||||
L1 只能查引用;标签写"算总价"而代码改成了"算单价",若两者都引用 `税率`,L1 沉默。
|
||||
**这是 L2 存在的理由**,也是必须承认的能力边界。
|
||||
|
||||
### 8.4 LLM 修标签可能引入新幻觉
|
||||
|
||||
"用幻觉修幻觉"是真风险。对策:
|
||||
- 护栏:**只允许改标签行或代码行**(`repair_apply` 已强制)
|
||||
- 修改必须**双向可逆**:诊断里给出"过去/现在"两侧,让模型做**判定**而不是**创作**
|
||||
- 知识库仓建议:L2 级修改需人工确认(`--confirm`)
|
||||
|
||||
### 8.5 标签不得参与安全判定
|
||||
|
||||
这是我在上一份文档里提的、也是你关心的"agent 误导"的另一面:
|
||||
**如果沙箱/权限判定读标签,那标签就成了攻击面。**
|
||||
硬约束:**策略、沙箱、工具白名单只读 `()` 的语义,永不读 `[]`。**
|
||||
标签只服务于"人读"与"AI 复核",不服务于"机器授权"。
|
||||
|
||||
### 8.6 成本
|
||||
|
||||
每标签一次指纹计算与比对。可增量:只对**本次变更的文件**做 L2 校验
|
||||
(与 EKC 的增量编译一致)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 分阶段落地
|
||||
|
||||
| 阶段 | 内容 | 依赖 | 风险 |
|
||||
|------|------|------|------|
|
||||
| **P0** | 纯度语法:`[标签](表达式)` + `label.missing` + 普通取元(A 或 C) | 解析器 | 中(506 处迁移) |
|
||||
| **P1** | L1 引用一致性 + `label.stale` 诊断(无状态) | 诊断字段已有 | 低 |
|
||||
| **P2** | 诊断 schema + MLSP ranges 并集 + 修复回路 | `mlsp.rs` / `repair.rs` | 低 |
|
||||
| **P3** | L2 指纹台账 + 增量校验 | `fingerprint.rs` | 中 |
|
||||
| **P4** | L3 LLM 复核 + `confirmed` 写回 + CI 门禁 | P2+P3 | 中 |
|
||||
|
||||
**建议先做 P1**:它零状态、确定性、能立刻抓住"引用了不存在的东西"这类最硬的腐烂,
|
||||
且不依赖纯度迁移——可以在旧语法上先验证"标签断言"这个概念是否好用。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **普通取元选 A(`at value=… index=…`,零新语法)还是 C(`at(篮子, 1)`,需逗号参数)?**
|
||||
2. **L1 的断言规则**:只认标签内的反引号 `` `名` ``,还是也认"与代码标识符同名"的中文词?
|
||||
(只认反引号更准;认中文词更聪明但假阳性高)
|
||||
3. **台账位置**:`.marqdo/labels.json`(默认忽略)还是纳入版本库(团队门禁)?
|
||||
4. **`label.stale` 默认级别**:warning(推荐)还是 error?
|
||||
5. **是否先只做 P1**(在旧语法上验证"标签断言"概念),再决定纯度迁移?
|
||||
|
||||
> 我的建议顺序:**P1 → P2 → P0 → P3 → P4**。
|
||||
> 先在旧语法上把"断言 + 复核 + 修复回路"这条链路跑通(它不依赖纯度),
|
||||
> 再动 506 处迁移——这样即使纯度路线最后要调整,一致性机制也已经沉淀下来了。
|
||||
@@ -0,0 +1,218 @@
|
||||
# 方案评估:Markdown 链接式调用 `[函数名](参数…)`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 已被 [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) 取代** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 用户:「markdown 的链接语义似乎很适合做这种操作」 |
|
||||
| 相邻 | [spaced-function-names-d8.md](spaced-function-names-d8.md)(方括号调用 + 空格) |
|
||||
| 影响面 | **核心解析**:`[key](coll)` 链接索引与调用语法冲突 |
|
||||
|
||||
> **后续更正**:本文的 L1–L4 方案列表把问题当成「表/语义」来讨论,偏离了用户原意。
|
||||
> 用户问的是**调用写法**本身。最新评估(含原型实测 554/0 回归)见
|
||||
> [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md):
|
||||
> 方括号确实不可行(2 个真实冲突文件),但**去掉方括号的 `f(args)` 是空闲语法且可行**。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**语法本身很优雅,但它与既有特性「链接索引 `[key](map)`」正面冲突。**
|
||||
冲突不是「难实现」,而是「同一个写法要表示两种语义」。
|
||||
建议**不要**把它做成调用的主形式;若要引入,只能作为**受限变体**(见 §4)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状事实(实测)
|
||||
|
||||
### 1.1 `[…](…)` 目前是链接索引
|
||||
|
||||
```markdown
|
||||
**m = > json.parse text={"a":1}**
|
||||
**v = [a](m)** # 取 map 的 a 成员
|
||||
> print text=`v` # → 1
|
||||
```
|
||||
|
||||
这是 v0.3 的**正式特性**,文档里写作「集合取元优先 `[键](集合)`」。
|
||||
实现有专门入口 `parse_link_index`,并由 `link_index_shape_ahead` 判定:
|
||||
|
||||
> `[` … `]` 后面紧跟 `(` → **链接索引**
|
||||
|
||||
### 1.2 提议的写法今天会怎样
|
||||
|
||||
```markdown
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
*"hi " + `who`*
|
||||
|
||||
# main
|
||||
|
||||
**r = [greet](alice)**
|
||||
```
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
error: l2.mq.md:12:1: undefined variable `alice`
|
||||
```
|
||||
|
||||
因为它被当作链接索引 `[greet](alice)`:拿 `alice` **当变量名**去查,
|
||||
查不到就报错。也就是说**链接索引已经把这块语法占满了**。
|
||||
|
||||
### 1.3 歧义判定只有一行
|
||||
|
||||
```rust
|
||||
fn link_index_shape_ahead(s: &str) -> bool {
|
||||
// '[' … ']' 后紧跟 '(' → 链接索引
|
||||
}
|
||||
```
|
||||
|
||||
任何 `[X](Y)` 都会走链接索引,没有例外。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么这个提议有吸引力
|
||||
|
||||
先说我认可的部分,避免低估它:
|
||||
|
||||
1. **视觉语义准确**。Markdown 里 `[文本](目标)` 的直觉是「链接一个东西到另一个」。
|
||||
调用 `[greet](alice)` 读作「调用 greet,指向 alice」,对非程序员也直观。
|
||||
2. **参数在括号里,边界清晰**。相比 `> greet alice`(空格切词),
|
||||
`(alice bob)` 的边界是**显式**的 —— 这恰好是 D8「带空格函数名」痛点的天然解药。
|
||||
3. **与 Markdown 完全兼容**。`[a](b)` 是合法链接写法,编辑器不会标红。
|
||||
|
||||
**但**:这些优点必须在「不破坏链接索引」的前提下才能兑现。
|
||||
|
||||
---
|
||||
|
||||
## 3. 冲突分析
|
||||
|
||||
### 3.1 根本矛盾
|
||||
|
||||
| 写法 | 链接索引语义 | 调用语义 | 能否并存 |
|
||||
|------|-------------|---------|---------|
|
||||
| `[a](m)` | 取 `m` 的成员 `a` | 用参数 `m` 调用 `a` | **看内容才知道** |
|
||||
| `[greet](alice)` | 取 `alice` 的成员 `greet` | 用 `alice` 调用 `greet` | 同上 |
|
||||
|
||||
**两者形状完全一致**,区别只在「`greet` 是函数还是键名」「`alice` 是集合还是实参」——
|
||||
这需要**符号表信息**,而语法判定发生在解析期(此时未必知道有哪些函数)。
|
||||
|
||||
### 3.2 用「函数表已知」来消歧能行吗
|
||||
|
||||
理论上:若 `greet` 是已定义函数 → 调用;否则 → 链接索引。
|
||||
|
||||
**问题**:
|
||||
1. **跨模块不可知**:`[lib.greet](x)` 需要 import 结果,词法/语法期拿不到。
|
||||
2. **名字冲突**:如果既有 `greet` 函数,又有 map 里叫 `greet` 的键,语义就靠猜。
|
||||
3. **错误信息会变差**:本意是链接索引但键不存在时,会被误判成调用,
|
||||
报 `unknown function` 而不是 `missing map key` —— 把清晰错误变成误导错误。
|
||||
4. **修改即破坏**:今天所有 `[键](集合)` 写法都要进符号表做一次判定,
|
||||
这是**全量语义变更**,不是增量特性。
|
||||
|
||||
### 3.3 冲突的严重度
|
||||
|
||||
链接索引是 v0.3 **明确推广**的写法(「集合取元优先 `[键](集合)`」),
|
||||
仓库里大量使用。让调用去抢这块语法,等于**用新特性侵蚀既有特性**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 可选的受限方案
|
||||
|
||||
### 方案 L1 — 参数列表必须「非单个标识符」(不可靠,不推荐)
|
||||
|
||||
仅在 `(…)` 内含**分隔符**时判为调用,如 `[greet](alice, bob)`。
|
||||
|
||||
- 优点:`[a](m)` 单参数时保留链接索引语义
|
||||
- **致命缺陷**:`[greet](alice)` 这种最常见的单参数调用无法表达;
|
||||
而 `[greet](a, b)` 又和「链接索引 + 逗号」冲突。**语义随参数个数漂移**,最坏的一类设计。
|
||||
|
||||
### 方案 L2 — 独立标记前缀(可行,但失去「链接感」)
|
||||
|
||||
```markdown
|
||||
> [call]greet(alice) # 或 @greet(alice)
|
||||
```
|
||||
|
||||
- 优点:零歧义
|
||||
- 缺点:前面多了标记,就不再是「Markdown 链接」了,失去了提议的全部吸引力
|
||||
|
||||
### 方案 L3 — 方括号调用 + 括号参数(**推荐**)
|
||||
|
||||
保留既有的方括号调用形式,但允许**参数写在括号里**:
|
||||
|
||||
```markdown
|
||||
> [加一 号](n=1) # 具名参数
|
||||
> [加一 号](1) # 位置参数
|
||||
> [greet](alice bob) # 多参数
|
||||
```
|
||||
|
||||
关键:**`]` 后面跟 `(` 时仍优先判为链接索引**——
|
||||
除非方括号内是「已知的函数名形状」且**调用上下文**成立。
|
||||
|
||||
等等,这与 §3 的矛盾相同。**所以 L3 的真正形态是**:
|
||||
|
||||
```markdown
|
||||
> [加一 号] (n=1) # 方括号与括号之间有空格 → 调用+参数组,不是链接
|
||||
```
|
||||
|
||||
用「`]` 与 `(` 之间是否有空格」消歧:
|
||||
- `[key](coll)`(紧贴)→ 链接索引(**既有语义完全不变**)
|
||||
- `[callee] (args)`(有空格)→ 调用,参数为一组
|
||||
|
||||
- 优点:**零歧义**、**零回归**(紧贴形式完全不动)、保留了「括号包参数」的可读性、
|
||||
顺带解决 D8 的空格函数名
|
||||
- 缺点:视觉上 `] (` 有个空格,略不自然;但 Markdown 渲染不受影响
|
||||
|
||||
### 方案 L4 — 不在语法层做,在文档层说明(保守)
|
||||
|
||||
明确「链接索引是取元,不是调用」,调用一律用 `> callee args` 或 `> [callee] args`。
|
||||
`[函数名](参数)` 留作**不做**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 方案对比
|
||||
|
||||
| 方案 | 歧义 | 回归风险 | 保留「链接感」 | 解决 D8 | 推荐 |
|
||||
|------|------|---------|--------------|---------|------|
|
||||
| L1 参数需含分隔符 | **高**(随参数个数漂移) | 中 | 部分 | 否 | ❌ |
|
||||
| L2 独立前缀 | 无 | 无 | **否** | 是 | 备选 |
|
||||
| **L3 空格消歧** | **无** | **无** | 大部分 | **是** | ✅ |
|
||||
| L4 不做 | 无 | 无 | 否 | 否 | 退路 |
|
||||
| 直接抢 `[x](y)` | **不可解** | **高** | 是 | 是 | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## 6. 我的建议
|
||||
|
||||
1. **不要**把 `[函数名](参数)` 直接定为调用——它和链接索引形状相同,无法可靠消歧。
|
||||
2. 采纳 **L3**:`[callee] (args)`(中间有空格)作为「带括号参数组的调用」,
|
||||
紧贴的 `[key](coll)` 语义**一字不动**。
|
||||
3. 这样同时满足:
|
||||
- 「完全兼容 Markdown」(`[x](y)` 仍是链接语义)
|
||||
- 参数边界显式(括号括起来)
|
||||
- D8 的空格函数名(方括号内允许空格)
|
||||
4. 若你觉得 `] (` 的空格不好看,退一步选 **L2**(`> callee(args)` 这种函数式写法),
|
||||
牺牲链接感换取零歧义。
|
||||
|
||||
---
|
||||
|
||||
## 7. 若采纳 L3 的验证计划
|
||||
|
||||
| 编号 | 用例 | 期望 |
|
||||
|------|------|------|
|
||||
| L3-1 | `[a](m)` 紧贴 | 链接索引,取成员(**不变**) |
|
||||
| L3-2 | `[greet] (alice)` 有空格 | 调用,`alice` 作为位置参数 |
|
||||
| L3-3 | `[加一 号] (n=1)` | 调用带空格名函数,返回 2 |
|
||||
| L3-4 | `[greet] (a b)` | 两个位置参数 |
|
||||
| L3-5 | `[a](m)` 中 `a` 恰好也是函数名 | **仍走链接索引**(紧贴优先) |
|
||||
| L3-6 | `> print text=(礼貌 [问候] x)` | 内嵌方括号不受影响 |
|
||||
| L3-7 | 全量 `cargo test` | 554 全绿 |
|
||||
| L3-8 | 全仓库 `.mq.md` 回归 | 无变化(紧贴形式未动) |
|
||||
|
||||
---
|
||||
|
||||
## 8. 待你决策
|
||||
|
||||
1. **选 L3、L2、还是 L4?**
|
||||
2. 若选 L3:`] (` 的空格你能接受吗?(渲染上无差别,源码里能看见)
|
||||
3. 是否同时支持全角 `【函数名】(参数)`?与 D2 全角冒号问题一致考虑。
|
||||
@@ -0,0 +1,799 @@
|
||||
# 链接语法:命名载荷、类-函数调用与可执行知识
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)** |
|
||||
| 日期 | 2026-10-23 |
|
||||
| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;它为任意既有载荷附上人话名称,并产出 view/compiler/知识图元数据 |
|
||||
| 取代/扩展 | 取代 [occlusion-syntax.md](occlusion-syntax.md) 的「遮蔽」单一框架;把「遮蔽」保留为**显示属性** |
|
||||
| 证据复核 | [occlusion-vs-executable-knowledge-2026-10.md](../research/occlusion-vs-executable-knowledge-2026-10.md) |
|
||||
| 示例 | [examples/link-syntax/](../../examples/link-syntax/) |
|
||||
| 关联 | [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [engineering-knowledge.md](engineering-knowledge.md) · [view.md](view.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 设计声明
|
||||
|
||||
### 0.1 一句话
|
||||
|
||||
> **`[]()` 本身不制作新语法。**
|
||||
> `[]` 是 Markdown 链接的可见文本;`()` 是**已经存在的 Marqdo 代码**,与 `**代码**` 同权。
|
||||
> `#` 是类,`##` 是函数;`类.函数` 就是类调用。
|
||||
> 链接把「一次已有载荷」写进文档,并为它附上一个人话名称;view 显示步骤与依赖,编译器返回链接信息。
|
||||
|
||||
### 0.1.1 还缺的一步:链接是「命名的可执行步骤」
|
||||
|
||||
`()` 可以是任意既有语法:取元、计算、调用、表操作、嵌套表达式或遍历/循环载荷。
|
||||
所以 `[]()` 不能只被定义成“事实主张 + 函数调用”;那会把通用语法割裂在知识体系之外。
|
||||
|
||||
> **`[名称](载荷)` 是命名的可执行步骤:`()` 按原语义执行,`[]` 说明这一步对人意味着什么;编译器把整个步骤写入知识图。**
|
||||
|
||||
它始终同时有三种投影:
|
||||
|
||||
| 投影 | 规则 | 目的 |
|
||||
|------|------|------|
|
||||
| **代码投影** | `execute([label](payload)) = execute(payload)` | 与裸 payload 共用 parser/evaluator,结果、效果和执行代价不变 |
|
||||
| **文档投影** | 保留 `label` 与所在句子/代码块 | 读者先读每一步的意图,必要时再展开实现 |
|
||||
| **知识投影** | 产出 `KnowledgeStep { label, kind, inputs, outputs, dependencies, effect, span }` | 让取元、计算、循环、调用和叙述都可检索、解释、验证和影响分析 |
|
||||
|
||||
`label` 不进符号表、不改变作用域,也不替 `payload` 背书为“事实”;但它绝不是可丢弃的显示文字。
|
||||
它是这段代码的人话接口。`payload` 提供操作,`label` 提供意图,二者共同形成可执行知识步骤。
|
||||
|
||||
例如:
|
||||
|
||||
```markdown
|
||||
**name = [订单收件人](at(订单, "收件人"))**
|
||||
**gross = [含税金额](金额 * (1 + 税率))**
|
||||
- [逐个订单行](遍历 订单.行 为 行)
|
||||
订单总额为[含税总价](定价.订单定价.含税总价(订单))。
|
||||
```
|
||||
|
||||
它们分别是观测、推导、过程和叙述调用;四者使用同一个 `[]()`,在运行时都复用已有载荷语义,
|
||||
但在图中拥有不同的输入/输出/依赖/效果边。只有一条步骤最终支撑对外事实时,才沿其依赖链要求来源;
|
||||
不能要求每一次取元或循环都伪造来源表。
|
||||
|
||||
这才同时实现三件事:
|
||||
|
||||
- **代码即文档**:函数内部的每一步都有可读意图,不是一个黑盒;
|
||||
- **文档即代码**:正文中的命名步骤能解析到实际依赖和可选值;
|
||||
- **知识即可执行**:项目中任意代码步骤都是统一知识图的一部分,来源/规则/函数变化可反查到具体步骤和句子。
|
||||
|
||||
完整的跨文件闭环、稳定寻址和层次投影见
|
||||
[executable-knowledge-system.md](executable-knowledge-system.md)。
|
||||
|
||||
### 0.2 三个「不新增」
|
||||
|
||||
| 不新增 | 说明 |
|
||||
|--------|------|
|
||||
| **不新增链接专用协议前缀 / 别名** | `()` 里就是普通表达式/调用;跨文档代码复用现有 `import bind:target`,正文可用唯一短地址发现 |
|
||||
| **不新增执行开关 / 模式关键字** | 不引入 frontmatter 别名或执行开关;解析靠已有类/函数/文档结构 |
|
||||
| **不新增括号 / 标记** | 不引入 `[[...]]` / `@[...]` / `link:`;`[]()` 仍是 Markdown 链接形 |
|
||||
|
||||
**本文定义四件事**:
|
||||
|
||||
1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用;`label` 如何命名任意既有载荷并形成知识步骤;
|
||||
2. **解析**:`()` 与 `**代码**` 共用 parser/evaluator;跨文档按类索引解析;
|
||||
3. **校验**:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子;
|
||||
4. **呈现**:view 显示调用点与证据;编译器返回 LinkInfo;EKC 建边;lock 可选。
|
||||
|
||||
> **作者不需要学习新标记**:正文链接仍是 `[描述](...)`;`view`/`check` 多了一项「把 payload 解析成类/函数」的能力,而不是要求作者写协议前缀、别名或执行开关。
|
||||
|
||||
### 0.3 原始意图
|
||||
|
||||
第一个可执行文档:
|
||||
|
||||
```markdown
|
||||
# 李白
|
||||
|
||||
这个文档存储了李白的信息。
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
李白出生于*某年*
|
||||
```
|
||||
|
||||
在 Marqdo 里:
|
||||
|
||||
- `# 李白` = **类**;
|
||||
- `## 李白的出生年份` = 该类下的**函数**;
|
||||
- `李白.李白的出生年份` = **类调用这个函数**。
|
||||
|
||||
> 注意:正文「李白出生于*某年*」是**叙述**;函数要可调用,需要显式返回值(`*701*` 或表,见 §2.6)。
|
||||
|
||||
第二个文档:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`。它不需要 `print`:
|
||||
**view 模式天然显示 `()` 的调用信息**。如果要终端输出,加一行 `print` 即可:
|
||||
|
||||
```markdown
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
这不是两套语法,而是同一套语法的两种呈现:
|
||||
|
||||
- `**year = 李白.李白的出生年份**` 是代码;
|
||||
- `[李白的出生年份](李白.李白的出生年份)` 是**带描述的同一段代码**;
|
||||
- `[描述](...)` 唯一新增的是「描述」与「view/compiler 元数据」,不是执行规则。
|
||||
|
||||
### 0.4 当前实现的偏差
|
||||
|
||||
v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
|
||||
| 设计意图 | 当前实现 | 后果 |
|
||||
|----------|---------|------|
|
||||
| `# 李白` 是类 | `# 李白` 是对象/类型 | 可以,但 `##` 被当成实例方法 |
|
||||
| `## 李白的出生年份` 是函数 | `##` 是实例方法,需要 `self`/接收者 | `李白.李白的出生年份` 被拒绝 |
|
||||
| `类.函数` 是类调用 | 必须 `> 李白` 构造实例,再 `obj.函数()` | 多一步实例化,知识不能直接调用 |
|
||||
| 跨文档按类名链接 | 裸类名不解析,必须 `import` + 绑定 | 第二个文档的链接是 `undefined variable` |
|
||||
| 链接是「命名载荷 + 已有语义」 | 被收窄成「遮蔽/本地表达式」 | 取元/循环/调用的步骤图、跨文档链接、view 依赖信息缺失 |
|
||||
|
||||
这正是「功能被阉割」的地方:**不是 `[]()` 不够,而是 `#`/`##` 的调用语义被实现成了实例方法,跨文档类索引没有建立。**
|
||||
|
||||
### 0.5 三个统一
|
||||
|
||||
| 统一 | 链接语法的作用 |
|
||||
|------|---------------|
|
||||
| **代码即文档** | 调用写在文档里;`**` 是代码,`[]()` 是同一段代码 + 人话描述 |
|
||||
| **文档即知识库** | `#` 类是知识命名空间,`##` 函数是知识单元;`类.函数` 是地址 |
|
||||
| **知识即可执行** | 链接解析到类/函数并求值;view 显示调用点;编译器返回 LinkInfo |
|
||||
|
||||
形式化:
|
||||
|
||||
> **`[label](expr) ≡ expr`;`expr` 可以是 `类.函数`。**
|
||||
> 链接不改变求值;它增加 label/上下文所形成的命名步骤,以及 view 呈现、编译器元数据和图关系。
|
||||
|
||||
---
|
||||
|
||||
## 1. 术语
|
||||
|
||||
| 术语 | 定义 |
|
||||
|------|------|
|
||||
| **链接语法** | `[描述](载荷)`;描述在运行时 inert、在知识层是步骤名称;载荷复用所在位置的已有代码/结构语法 |
|
||||
| **描述 / 名称(label)** | `[]` 内自由文本;不参与运行时求值,但用于显示、检索、诊断、LinkInfo、意图漂移校验与新鲜度复核 |
|
||||
| **载荷(payload)** | `()` 内的表达式;与 `**代码**` 同权;唯一执行体 |
|
||||
| **类(class)** | `# 名称`;知识命名空间/类型 |
|
||||
| **函数(function)** | `## 名称`(及更深);类下或模块顶层的可调用单元 |
|
||||
| **类调用(class call)** | `类.函数`;不构造实例,直接调用类函数 |
|
||||
| **实例调用(instance call)** | `对象.函数`;对象是局部变量/实例,函数可使用 `self`/`自` |
|
||||
| **知识链接** | 目标为类/函数的 `[]()`;view 显示目标与值 |
|
||||
| **代码链接** | 出现在 `**...**` / `*...*` / 调用实参/表格单元格里的 `[]()`;参与表达式 |
|
||||
| **正文链接** | 出现在叙述里的 `[]()`;view/check 解析,`run` 不执行(除非加 `print` 或代码链接) |
|
||||
| **LinkInfo** | 编译器返回的命名步骤信息:描述与上下文、源位置、payload 类型、输入/输出、依赖、效果、值/来源/指纹 |
|
||||
| **链接图** | 文档/类/函数/命名步骤为点,读、推导、遍历、调用、效果、叙述、来源为边;EKC/catalog/view 共用 |
|
||||
| **遮蔽** | 链接的显示属性:`()` 的代码在 Markdown 里被折叠,读者只看描述与结果 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 语义
|
||||
|
||||
### 2.1 描述永不执行,载荷唯一执行
|
||||
|
||||
```text
|
||||
[label](expr) ≡ expr
|
||||
```
|
||||
|
||||
- `[]` 不进符号表、不参与运行时求值、不改变作用域;但它进入 LinkInfo,作为命名步骤的人话接口;
|
||||
- `()` 是唯一执行体;空 `()` 值为 `None`;
|
||||
- `label.missing` / `label.empty_payload` 仍是结构诊断;
|
||||
- 链接的**可执行性**来自 `payload` 的原有语法;链接的**知识性**来自 `label`、位置以及编译器提取的输入/输出/依赖/效果。任意载荷都可成为知识步骤,不以是否类调用为前提。
|
||||
|
||||
### 2.2 `#` 是类,`##` 是函数
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `# 名称` | 类/知识命名空间;正文是构造体 |
|
||||
| `## 名称` | 类下的函数;可被 `类.函数` 调用 |
|
||||
| `###` … | 更深层函数/子命名空间 |
|
||||
| 顶层 `## 名称` | 模块级自由函数;可被 `模块.函数` 调用 |
|
||||
|
||||
**函数与实例的关系**:
|
||||
|
||||
- 函数体使用 `self` / `自` → **实例函数**,只能通过实例调用(`obj.函数`);
|
||||
- 函数体不使用 `self` / `自` → **类函数**,可被 `类.函数` 直接调用;
|
||||
- 类函数不执行 `# 类` 的构造体,不产生实例;
|
||||
- 实例函数保留现有 `> 对象.函数` / `obj.函数()` 语义。
|
||||
|
||||
这条规则只用已有语法(`#`、`##`、`self`/`自`、`.`),不新增标记。
|
||||
|
||||
### 2.3 `类.函数` 是类调用
|
||||
|
||||
| 写法 | 语义 |
|
||||
|------|------|
|
||||
| `李白.李白的出生年份` | 类 `李白` 的零参函数 `李白的出生年份`;**隐式调用** |
|
||||
| `李白.问候("世界")` | 类 `李白` 的函数 `问候`,带位置参数 |
|
||||
| `李白.计税(档位=2, 金额=100)` | 具名参数,复用现有实参文法 |
|
||||
| `obj.李白的出生年份()` | 实例调用;`obj` 是局部变量/实例 |
|
||||
| `文档.李白.李白的出生年份` | 文档限定;用于同名类消歧 |
|
||||
|
||||
**隐式调用规则**:当点号路径解析到一个**零参函数**时,路径表达式就是调用,值为函数返回值;
|
||||
带参数时必须写 `(...)`;解析到类名本身(无函数段)时,仍是类型/构造,不隐式调用。
|
||||
|
||||
> 这条规则不是新语法:它只规定「点号路径解析到函数」时的语义。
|
||||
> 它让 `李白.李白的出生年份` 与 `**李白.李白的出生年份**` 同权,也让链接与代码同权。
|
||||
|
||||
### 2.4 跨文档:模块身份优先,类索引只做发现
|
||||
|
||||
链接目标可以跨文档。可运行代码的解析顺序:
|
||||
|
||||
1. **局部变量/对象**:第一段是当前作用域变量 → 实例调用;
|
||||
2. **当前文档类/函数**:`# 类` / `## 函数`;
|
||||
3. **已 import 的模块**:现有 `import bind:target` 绑定;
|
||||
4. **内置/插件**。
|
||||
|
||||
文件 frontmatter 的 `id` + 现有 `import bind:target` 是规范地址;例如
|
||||
`li_bai.李白.出生年份`。项目类索引仍是**编译器/链接器的发现索引**,不是运行时的
|
||||
按名加载机制:
|
||||
|
||||
- 索引 `id`、`# 类` 名、`## 函数` 名、签名、文件位置;
|
||||
- 排除 `# main`;
|
||||
- 正文短地址同名 → `link.ambiguous`;解析成功后 LinkInfo/lock 固化 `id`、文件与指纹;
|
||||
- 索引只在项目根内(`--fs-root`),不访问网络;
|
||||
- 索引可缓存(按文件 mtime)。
|
||||
|
||||
> 正文可以直接写 `李白.出生年份`,由 catalog 唯一发现并 lock;
|
||||
> 代码仍应使用显式 import,避免同名、重命名和加载顺序使大型项目失去可复现性。
|
||||
|
||||
### 2.5 `()` 与 `**代码**` 同权
|
||||
|
||||
| 能力 | `**代码**` | `[描述](载荷)` 的 `()` |
|
||||
|------|-----------|----------------------|
|
||||
| 算术/比较/布尔 | ✅ | ✅ 同一 parser |
|
||||
| 变量/插值 | ✅ | ✅ |
|
||||
| 本地调用 `callee(args)` | ✅ | ✅ |
|
||||
| 类调用 `类.函数` | ✅ | ✅ |
|
||||
| 实例调用 `obj.函数` | ✅ | ✅ |
|
||||
| 表/列/映射 | ✅ | ✅ |
|
||||
| 返回值 | Value | Value(同类型系统) |
|
||||
| 副作用 | 可 | 可(受沙箱限制) |
|
||||
|
||||
**实现约束**:表达式位置的 `[label](payload)` 必须复用 `**代码**` 的表达式入口;遍历位置的
|
||||
`[label](payload)` 必须复用既有 LoopSpec 入口;禁止另造「简化知识表达式」或「知识循环」。
|
||||
|
||||
**代码链接 vs 正文链接**:
|
||||
|
||||
| 上下文 | `[]()` 行为 |
|
||||
|--------|-------------|
|
||||
| `**...**` / `*...*` / 调用实参 / 表格单元格 | 代码链接:求值,参与表达式 |
|
||||
| 正文(叙述) | 正文链接:view/check 解析并显示;`run` 不执行 |
|
||||
| 标题 / frontmatter | 不执行;按普通文本处理 |
|
||||
|
||||
正文链接不执行,是为了保持「叙述默认安全」;它由 view 呈现、由 check 解析。
|
||||
要终端输出,就把同一段代码放进代码链接并加 `print`。
|
||||
|
||||
**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 先按所在位置的既有
|
||||
载荷文法解析,再提取其依赖与角色。URL/相对路径为导航;任意可解析的表达式、调用或遍历
|
||||
都是命名步骤;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。
|
||||
|
||||
### 2.6 输出:值知识必须有值,过程知识必须声明效果
|
||||
|
||||
当一个 `##` 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值:
|
||||
|
||||
```markdown
|
||||
## 李白的出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;值知识要的是返回值/表。只有叙述、没有返回的函数:
|
||||
|
||||
- `run` 得到 `None`;
|
||||
- `check` 报 `link.no_value`(warning/error,视知识链接用途);
|
||||
- view 显示「无返回值」;
|
||||
- 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值,
|
||||
但 LinkInfo 必须记录输入、输出绑定和 `effect`,以便 view、权限检查与影响分析。
|
||||
|
||||
### 2.7 view 显示调用信息
|
||||
|
||||
**代码链接**:
|
||||
|
||||
```text
|
||||
┌─ 链接 ─────────────────────────────┐
|
||||
│ `year` = [李白的出生年份] │
|
||||
│ → 李白.李白的出生年份 │
|
||||
│ class 李白 · function · () -> number │
|
||||
│ value 701 · ok │
|
||||
└────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**正文链接**:
|
||||
|
||||
```text
|
||||
用户想要知道李白的出生年份,我们要告诉用户 701。
|
||||
↑
|
||||
悬浮:李白的出生年份 → 李白.李白的出生年份
|
||||
class 李白 · () -> number · value 701
|
||||
```
|
||||
|
||||
- Structure 模式:显示 label + 目标类/函数 + 状态 + 源位置;
|
||||
- Execution 模式:显示值;
|
||||
- 点击目标:跳到目标文档/类/函数;
|
||||
- 错误:错误 chip + 诊断码 + 修复建议;
|
||||
- 无返回值:显示「无返回值」,不伪造值。
|
||||
|
||||
**这就是「示例不带 print」的原因**:view 显示调用信息;`run` 才需要 `print` 才有终端输出。
|
||||
|
||||
### 2.8 编译器返回 LinkInfo
|
||||
|
||||
每个 `[]()` 产出:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "逐个订单行",
|
||||
"payload_kind": "loop",
|
||||
"roles": ["iterate"],
|
||||
"source": {"file": "pricing.mq.md", "line": 18, "col": 3},
|
||||
"inputs": [{"path": "订单.行", "type": "list<订单行>"}],
|
||||
"outputs": [{"name": "行", "type": "订单行"}],
|
||||
"dependencies": [
|
||||
{"kind": "local_value", "path": "订单.行"},
|
||||
{"kind": "symbol", "id": "capability.pricing::订单定价.含税价"}
|
||||
],
|
||||
"effect": "pure",
|
||||
"value": null,
|
||||
"fingerprint": "sha256:…"
|
||||
}
|
||||
```
|
||||
|
||||
- `payload_kind`:`expr` / `loop` / `inline` / `navigation`;复用所在位置的已有文法;
|
||||
- `roles`:`observe` / `derive` / `reuse` / `iterate` / `act` / `narrate`,由 AST、效果和依赖推导;
|
||||
- `dependencies` 是集合而非单一 target;任意复杂表达式都可同时读表、调用多个知识函数和产生副作用;
|
||||
- `value` 在 `check` 中为 `null`(不执行);在 `view`/`run` 中可填;
|
||||
- `fingerprint` 是 label、payload、依赖解析及契约的指纹;用于意图漂移与 lock 检查。
|
||||
|
||||
### 2.8.1 LinkInfo 是统一知识步骤记录,不只是调用记录
|
||||
|
||||
`LinkInfo` 至少要区分三类状态:
|
||||
|
||||
| 层 | 要回答的问题 | 典型状态 |
|
||||
|------|-------------|----------|
|
||||
| **载荷状态** | `()` 能否按它原有语法解析/执行? | `ok` / `unresolved` / `arg_mismatch` / `type_mismatch` |
|
||||
| **步骤状态** | 输入、输出、依赖和效果能否被提取? | `resolved` / `partial` / `ambiguous` |
|
||||
| **证据状态** | 一个发布事实沿依赖链是否能抵达来源? | `supported` / `needs_review` / `unsupported` |
|
||||
|
||||
三者不能混为一谈:字典取元可以 `ok` 且完全不需要来源;但当它被一个事实函数或
|
||||
正文结论使用时,最终的证据链仍可为 `unsupported`。反过来,来源充足也不能掩盖
|
||||
`link.unresolved` 或副作用越权。
|
||||
|
||||
来源是统一步骤图上的 `derived_from` 边,不是只属于一种“知识链接”的特殊 payload。
|
||||
这不是新增语法,而是让既有 `#`/`##`、表、表达式和 `[]()` 共同产生同一张图。
|
||||
|
||||
### 2.9 链接既是步骤节点,也是图边
|
||||
|
||||
```text
|
||||
定价.订单定价 --contains--> step#逐个订单行
|
||||
step#逐个订单行 --observes--> 订单.行
|
||||
step#逐个订单行 --calls--> 定价.订单定价.含税价
|
||||
定价.订单定价.含税价 --derived_from--> corpus/tax.md#税率
|
||||
```
|
||||
|
||||
- 每个 `[]()` 都保留为步骤节点;`calls` 只是 `observes`/`derives`/`iterates`/`acts`/
|
||||
`narrates` 等边的一种;
|
||||
- EKC `graph.json` 增加 class/function/步骤节点和上述关系边;
|
||||
- `catalog` 模块页显示「链接到/被链接」;
|
||||
- `find`/`impact`/`verify` 沿步骤、调用和来源边遍历;表字段、循环、函数或来源变更时,
|
||||
都可精确找出受影响的代码步骤和句子;
|
||||
- view 的 Structure 面板显示上下游。
|
||||
|
||||
### 2.10 安全
|
||||
|
||||
| 风险 | 规则 |
|
||||
|------|------|
|
||||
| 类名歧义 | `link.ambiguous`;要求 `文档.类.函数` |
|
||||
| 实例函数被类调用 | `link.instance_only`;提示用实例 |
|
||||
| 构造副作用 | 类调用不执行构造体;不会隐式构造实例 |
|
||||
| 函数副作用 | 目标函数可能写文件/发请求;`run`/live view 受沙箱限制;`check` 不执行 |
|
||||
| 循环 | 链接图检测环;运行时深度/步数上限 |
|
||||
| 路径逃逸 | 项目类索引只在根内;`--fs-root` 限制;不访问网络 |
|
||||
| 标签欺骗 | 标签不可信;解析/权限只看 target,不看 label |
|
||||
| view | 静态模式不执行;live 执行需用户操作;错误不吞 |
|
||||
|
||||
### 2.11 可复现(可选,生成物)
|
||||
|
||||
- LinkInfo 带 label、payload、依赖解析、效果与可用来源边的指纹;
|
||||
- `marqdo links lock` 生成 `.marqdo/links.lock.yaml`;
|
||||
- `check --locked` 校验;载荷、依赖、契约或来源边变化 → `link.stale` / `knowledge.needs_review`;
|
||||
- 这是生成物/工具,不是新语法。
|
||||
|
||||
### 2.12 知识分层:类、知识个体、调用面
|
||||
|
||||
链接语法是**调用面**;它上面还有两层知识结构(详见 [knowledge-layers.md](knowledge-layers.md)):
|
||||
|
||||
```markdown
|
||||
# 诗人 # L1 本体:类/模式
|
||||
| 字段 | 类型 | 说明 |
|
||||
| 姓名 | text | ... |
|
||||
| 出生年份 | number | ... |
|
||||
|
||||
# 李白 = > 诗人 # L2 知识个体:单体知识类
|
||||
## 李白的出生年份
|
||||
| 返回 | 类型 | 来源 |
|
||||
| 701 | number | corpus/libai.md#出生年份 |
|
||||
*701*
|
||||
|
||||
# L3 调用面
|
||||
[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
**术语**:
|
||||
|
||||
- `# 李白 = > 诗人` 是**知识个体/单体类**(语法上是继承/特化),不是运行时实例;
|
||||
- `> 李白` 才是运行时实例(map + `_type`);
|
||||
- `李白.李白的出生年份` 是类调用;
|
||||
- `[]()` 是调用面,不新增语法。
|
||||
|
||||
**为什么不在 v2.1 引入运行时实例作为知识实体**:
|
||||
|
||||
- 运行时实例是值,不是文档里的稳定地址;跨文档链接需要实例注册表/导出;
|
||||
- EKC 的节点是文档/类/函数,不是运行时 map;
|
||||
- 单体类已经能表达「李白是诗人,李白有出生年份」,且零新语法。
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前实现 vs 目标
|
||||
|
||||
### 3.1 已具备(v2.0.0)
|
||||
|
||||
| 能力 | 状态 | 证据 |
|
||||
|------|------|------|
|
||||
| `[描述](表达式)` 解析 | ✅ | `Expr::Occluded` / `markup: occlusion` |
|
||||
| `()` 内 `callee(args)` | ✅ | M1;`加一 号(31)` |
|
||||
| 本地表达式透明求值 | ✅ | `interp.rs:1117` |
|
||||
| view 本地链接卡 | ✅ | `render.rs:1227` |
|
||||
| 标签诊断/检索 | ✅ | `label.*` / `marqdo labels` |
|
||||
| 实例调用 | ✅ | `obj.method()` / `> obj.method` |
|
||||
|
||||
### 3.2 缺失(v2.1 目标)
|
||||
|
||||
| 能力 | 状态 | 影响 |
|
||||
|------|------|------|
|
||||
| `类.函数` 类调用 | ❌ | `李白.李白的出生年份` 被当成变量/实例方法 |
|
||||
| 跨文档类索引 | ❌ | 裸类名不解析;必须 import + 实例 |
|
||||
| 统一 `[]()` 分类 | ❌ | 默认 Classic 下 `[]()` 是取元;需 `markup` |
|
||||
| LinkInfo | ❌ | 编译器不返回链接信息 |
|
||||
| view 目标/类/函数/值 | ⚠️ 只有本地卡片 | 没有跨文档目标信息 |
|
||||
| 链接图边(EKC) | ❌ | 知识图不从链接取边 |
|
||||
| 正文链接解析 | ❌ | 第二个文档的链接不解析 |
|
||||
| 类函数契约/返回校验 | ❌ | 无返回值也不报 |
|
||||
|
||||
### 3.3 为什么旧例子失败
|
||||
|
||||
| 层 | 旧例子 | 设计要求 |
|
||||
|----|--------|---------|
|
||||
| 上下文 | 正文普通链接 | 正文链接由 view/check 解析(run 不执行) |
|
||||
| 类索引 | 无 import | 项目类索引解析 `李白` |
|
||||
| 调用 | `李白.李白的出生年份` 被当变量 | 解析为类函数,隐式调用 |
|
||||
| 分派 | `##` 是实例方法 | 不使用 `self` 的函数是类函数 |
|
||||
| 值 | 方法体无返回 | 知识函数必须返回 `701` |
|
||||
| 静态检查 | 不解析 | `check` 报 `link.*` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 编译器 / view / CLI 表面
|
||||
|
||||
### 4.1 `check --json`
|
||||
|
||||
- 解析所有 `[]()`(表达式、遍历、代码与正文),输出带载荷/步骤/证据状态的 LinkInfo 与 `link.*` / `knowledge.*` 诊断;
|
||||
- 不执行目标函数;
|
||||
- `link.ok` 可作 info,不阻断;
|
||||
- `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` 按级别报。
|
||||
|
||||
### 4.2 MLSP
|
||||
|
||||
| method | 作用 |
|
||||
|--------|------|
|
||||
| `link.resolve` | 解析一个链接 → LinkInfo |
|
||||
| `links.list` | 列出文件/项目所有链接 |
|
||||
| `links.graph` | 返回链接图 |
|
||||
| `link.check` | 校验一个链接 |
|
||||
|
||||
AI 闭环:`locate` → `link.resolve` → 构造/修复 → `check` → `view`/`run`。
|
||||
|
||||
### 4.3 `catalog` / EKC
|
||||
|
||||
- `catalog` 增加 `links:` 段与链接图;
|
||||
- EKC `graph.json` 增加 class/function、命名步骤节点与 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates`/`derived_from` 边;
|
||||
- `find`/`impact` 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
|
||||
|
||||
### 4.4 `links` CLI(可选)
|
||||
|
||||
```bash
|
||||
marqdo links list [PATH] --json
|
||||
marqdo links resolve FILE:LINE:COL
|
||||
marqdo links graph [PATH] --json
|
||||
marqdo links lock [PATH] # 可选,生成指纹锁
|
||||
```
|
||||
|
||||
### 4.5 诊断
|
||||
|
||||
| code | 级别 | 触发 | 建议 |
|
||||
|------|------|------|------|
|
||||
| `link.unresolved` | error | 类/函数/文档不存在 | 检查类名/文档名/拼写 |
|
||||
| `link.ambiguous` | error | 同名类/函数 | 用 `文档.类.函数` 限定 |
|
||||
| `link.instance_only` | error | 类调用命中实例函数 | 用实例 `obj.函数`,或去掉 `self` |
|
||||
| `link.no_value` | warning | 知识函数无返回 | 加 `*值*` 或表/契约 |
|
||||
| `link.arg_mismatch` | error | 参数数量/名称不匹配 | 按签名补/删 |
|
||||
| `link.type_mismatch` | error | 返回/参数类型不匹配(可静态判断) | 修契约/转换 |
|
||||
| `link.cycle` | error | 链接图成环 | 拆分事实/减少互引 |
|
||||
| `link.stale` | warning | 目标指纹变化(lock 模式) | 更新 lock 并复核 |
|
||||
| `knowledge.unsupported` | warning | 对外发布的事实/结论沿步骤依赖链没有来源支撑 | 补来源边或将其标明为未验证推导 |
|
||||
| `knowledge.needs_review` | warning | payload、依赖、规则或来源变化,受影响步骤/句子待复核 | 复核步骤与叙述后更新 lock |
|
||||
| `label.missing` | error | 空描述 | 写一句人话 |
|
||||
| `label.empty_payload` | warning | 空载荷 | 写 `None` 或真实目标 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 开发指导
|
||||
|
||||
### 5.1 里程碑
|
||||
|
||||
| 阶段 | 目标 | 交付 |
|
||||
|------|------|------|
|
||||
| **L0** | 统一 `[]()` 节点 | `Bracket { label, payload }`;代码/正文两处解析;不新增语法 |
|
||||
| **L1** | 步骤索引 + 解析 | `Named<T>` 的输入/输出/依赖/效果提取;类/模块解析;`link.*`/`knowledge.*` 诊断 |
|
||||
| **L2** | 类调用运行时 | `类.函数` 隐式调用;参数;实例函数拒绝;双后端 |
|
||||
| **L3** | view | 链接卡;正文链接信息;目标跳转;值/状态/源位置 |
|
||||
| **L4** | 图 + lock | EKC 步骤节点/读写推导遍历调用来源边;catalog;可选 lock/stale |
|
||||
| **L5** | 默认/迁移/文档 | 统一解析替代 `markup` 方言;旧取元迁移;README/示例 |
|
||||
|
||||
**顺序**:L0 → L1 → L2 → L3 → L4 → L5。
|
||||
L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
|
||||
|
||||
### 5.2 文件级改动
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `src/ast.rs` | `Bracket { label, payload }`(可由 `Occluded` 演进);不新增语法节点族 |
|
||||
| `src/parse/expr.rs` | `[]()` 统一解析;payload 复用 `**` 表达式入口;保留 `markup` 兼容 |
|
||||
| `src/parse/mod.rs` | 正文 `[]()` 扫描;行/列定位;表格单元格 |
|
||||
| `src/link.rs`(新增) | 模块/类解析、`Named<T>` 步骤记录、依赖/效果提取、诊断、指纹、图边 |
|
||||
| `src/load.rs` | 项目扫描/类索引缓存;`--fs-root`;循环检测 |
|
||||
| `src/check.rs` | 链接解析集成;`link.*`;`--links/--no-links/--locked` |
|
||||
| `src/interp.rs` | `类.函数` 类调用;隐式零参调用;实例函数拒绝;正文链接不执行 |
|
||||
| `src/bytecode/compile.rs` + `vm.rs` | 类调用编译/执行;双后端一致 |
|
||||
| `src/view/render.rs` | 链接卡;正文链接信息;目标/值/状态/跳转 |
|
||||
| `src/view/document.rs` / `output.rs` | 正文链接扫描/渲染 |
|
||||
| `src/knowledge/graph.rs` | class/function/命名步骤节点;读/推导/遍历/调用/效果/叙述/来源边 |
|
||||
| `src/knowledge/extract.rs` | 类/函数/命名步骤提取;依赖与来源关系 |
|
||||
| `src/catalog.rs` | links 段/图 |
|
||||
| `src/mlsp.rs` | `link.resolve` / `links.list` / `links.graph` |
|
||||
| `src/main.rs` | `links` 子命令;check 选项 |
|
||||
| `README.md` | 链接语法章节(不新增语法) |
|
||||
| `doc/README.md` | 登记本文/示例 |
|
||||
| `examples/link-syntax/` | 用户原始示例 + compat |
|
||||
|
||||
### 5.3 关键实现点
|
||||
|
||||
1. **类函数判定**:扫描函数体是否出现 `self` / `自`;出现 → 实例函数;不出现 → 类函数。
|
||||
2. **隐式调用**:点号路径解析到零参函数时,求值为调用;带参必须 `(...)`;解析到类名不调用。
|
||||
3. **类索引**:只索引 `#`/`##` 名、签名、文件、行;排除 `# main`;同名报歧义。
|
||||
4. **`[]()` 分类**:
|
||||
- payload 是类/函数路径 → 知识链接;
|
||||
- payload 是表达式(运算符/字面量/调用)→ 本地表达式链接;
|
||||
- payload 是单标识符且解析为集合 → 旧取元(兼容;`markup` 模式可强制链接);
|
||||
- 正文 `[]()` → 正文链接(view/check)。
|
||||
5. **正文链接不执行**:`run` 不改行为;`view`/`check` 解析;要输出用代码链接 + `print`。
|
||||
6. **LinkInfo**:check/view/catalog 共用;任意 `[]()` 都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。
|
||||
7. **图**:每个 `[]()` 是步骤节点;按角色建 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates` 边,来源只是其中一种边。
|
||||
8. **安全**:类调用不构造实例;沙箱;根目录;标签不可信。
|
||||
|
||||
**最小改动原则**(证明「不新增语法」):
|
||||
|
||||
| 层 | 现状 | v2.1 改动 |
|
||||
|----|------|-----------|
|
||||
| parser | `[label](payload)` → `Occluded { label, payload }` | **不改 grammar**;可把节点改名为 `Bracket` 便于阅读 |
|
||||
| payload | 已是表达式,`callee(args)` 已支持 | 不改;`类.函数` 是现有 dot path |
|
||||
| AST | `Occluded { label, payload }` | 不新增 `Ref`/`Class` 节点;类/函数用现有 `Function`/`is_object` |
|
||||
| resolver | 无 | **新增**:类索引 + `类.函数` 解析 + `self` 判定 |
|
||||
| interp | 透明求值 payload | **新增**:dot path 解析到类函数时隐式调用 |
|
||||
| view/check | 本地卡片/契约 | **新增**:正文 `[]()` 扫描 + LinkInfo |
|
||||
| 语法 | — | **零新增**:没有协议前缀、别名、执行开关、模式关键字 |
|
||||
|
||||
> 当前 `李白.李白的出生年份` 在 AST 里是 `Var("李白.李白的出生年份")`(v2.0.0 实测报 `undefined variable`)。
|
||||
> **不要依赖 parser 生成新节点**:resolver 按 `.` 拆分这个变量名,先找类 `李白`,再找函数 `李白的出生年份`;
|
||||
> 找到后按类调用求值。若 parser 已生成 `Call { path: ["李白","李白的出生年份"] }`,同样按 path 解析。
|
||||
|
||||
### 5.4 测试
|
||||
|
||||
| 层 | 用例 |
|
||||
|----|------|
|
||||
| 单元 | `类.函数` 解析;零参隐式调用;带参;`self` 判定;同名歧义 |
|
||||
| 集成 | 用户两文档:正文链接 view 显示 701;代码链接 + print 输出 701 |
|
||||
| 诊断 | unresolved / ambiguous / instance_only / no_value / arg/type/cycle |
|
||||
| view | 链接卡/正文链接/目标跳转/错误/无返回值 快照 |
|
||||
| 图 | EKC 观测/推导/遍历/调用/效果/叙述/来源边;catalog;impact |
|
||||
| 双后端 | tree + bytecode 一致 |
|
||||
| 回归 | 现有 605 测试不减;实例调用不变;旧 `markup` 兼容 |
|
||||
| 安全 | 根目录逃逸、循环、副作用、标签注入 |
|
||||
|
||||
### 5.5 迁移
|
||||
|
||||
- `#`/`##` 的实例调用保持;
|
||||
- 不使用 `self` 的现有方法自动获得类调用能力(增量);
|
||||
- `类.函数` 是新增解析,不改变旧调用;
|
||||
- `[]()` 在 `markup: occlusion` 下继续是链接;在 Classic 下按 payload 分类,单标识符/集合仍是旧取元;
|
||||
- 目标:v2.2 移除 `markup` 方言,统一按 payload 分类。
|
||||
|
||||
---
|
||||
|
||||
## 6. 示例
|
||||
|
||||
完整见 [examples/link-syntax/](../../examples/link-syntax/)。
|
||||
|
||||
### 6.1 用户原始示例(目标)
|
||||
|
||||
`libai.mq.md`:
|
||||
|
||||
```markdown
|
||||
# 李白
|
||||
|
||||
这个文档存储了李白的信息。
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
李白的出生年份是公元 701 年。
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
`main.mq.md`:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
- `view`:正文链接显示 `李白.李白的出生年份`、类 `李白`、函数、签名、值 `701`;
|
||||
- `run`:无输出(正文链接不执行);加 `print` 才有终端输出;
|
||||
- `check --json`:LinkInfo(target/class/function/signature/status);
|
||||
- `catalog`:`main.mq.md --calls--> libai.mq.md::李白.李白的出生年份`。
|
||||
|
||||
### 6.2 加 print(终端输出)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出:`701`。
|
||||
|
||||
### 6.3 带参数
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**greeting = [问候](李白.问候("世界"))**
|
||||
> print text=`greeting`
|
||||
```
|
||||
|
||||
### 6.4 当前兼容写法(v2.0.0)
|
||||
|
||||
```markdown
|
||||
---
|
||||
markup: occlusion
|
||||
import:
|
||||
libai: libai.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**li = > libai.李白**
|
||||
**year = [李白的出生年份](li.李白的出生年份())**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出 `701`。这只是**当前实现**的等价写法;v2.1 的目标是去掉 `import`/实例两步。
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收标准
|
||||
|
||||
| # | 验收 | 判定 |
|
||||
|---|------|------|
|
||||
| 1 | 用户原始示例的 `view` 显示 `701` 与调用信息 | view 快照 |
|
||||
| 2 | `**year = [..](李白.李白的出生年份)**` + `print` 输出 701 | run |
|
||||
| 3 | `check --json` 返回 LinkInfo(class/function/signature/status) | link.ok |
|
||||
| 4 | 类名改成不存在 → `link.unresolved` | 反例 |
|
||||
| 5 | 同名类 → `link.ambiguous` | 反例 |
|
||||
| 6 | 实例函数被类调用 → `link.instance_only` | 反例 |
|
||||
| 7 | 无返回值 → `link.no_value` | 反例 |
|
||||
| 8 | EKC 出现 `calls` 边 | graph.json |
|
||||
| 9 | 正文链接 `run` 不执行;`view` 解析 | 行为 |
|
||||
| 10 | 旧 605 测试不减;实例调用不变 | 回归 |
|
||||
| 11 | 表字段、规则或来源变化后,受影响的取元/循环/推导/句子变为 `knowledge.needs_review` | impact 反例 |
|
||||
|
||||
**一句话验收**:
|
||||
|
||||
> **`[李白的出生年份](李白.李白的出生年份)` 不新增任何语法;`view` 能显示它,`check` 能解析它,`run` 加 `print` 能输出 701,`catalog` 能建边。**
|
||||
> 四者缺一,说明 `#`/`##` 的类-函数语义还没补齐。
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险与开放问题
|
||||
|
||||
| 风险 | 说明 | 缓解 |
|
||||
|------|------|------|
|
||||
| 类名歧义 | 多个 `# 李白` | `link.ambiguous`;`文档.类.函数` |
|
||||
| 实例/类判定 | 依赖 `self`/`自` 扫描 | 明确规则;无法判定时 `link.instance_only` |
|
||||
| 构造副作用 | 类调用不应构造实例 | 类调用不执行构造体;实例函数拒绝 |
|
||||
| 无返回值 | 知识函数只有叙述 | `link.no_value`;要求 `*值*`/表 |
|
||||
| 正文链接 | run 不执行 | view/check 解析;print 用代码链接 |
|
||||
| 旧取元歧义 | `[key](collection)` | 单标识符/集合按旧取元;`markup` 兼容;逐步迁移 |
|
||||
| 性能 | 大项目类索引 | 缓存;只索引签名;增量 |
|
||||
| 安全 | 类函数执行副作用 | 沙箱;check 不执行;标签不可信 |
|
||||
| 跨项目 | 类索引只在根内 | 用 import/模块;不引入新语法 |
|
||||
|
||||
**开放问题**:
|
||||
|
||||
1. 类函数是否允许访问类级常量/字段?v1 只允许函数体自包含;v1.1 再定义。
|
||||
2. `# 类` 的构造体与类函数的关系?v1 类调用不构造;实例函数用 `self`。
|
||||
3. 同名类跨文档是否允许?v1 报歧义;用 `文档.类.函数`。
|
||||
4. 正文链接是否要在 `run` 中渲染?v1 不执行;view 显示;v1.1 可加 `--render-links`。
|
||||
5. `[]()` 与旧取元的自动分类是否足够稳定?先保留 `markup` 兼容;v2.2 再移除。
|
||||
6. 是否需要函数作为一等值?v1 不需要;`类.函数` 解析即调用。
|
||||
|
||||
---
|
||||
|
||||
## 9. 结论
|
||||
|
||||
> **`[]()` 不是新语法,它是「命名载荷 + 已有语义」的组合。**
|
||||
> `#` 是类,`##` 是函数,`类.函数` 是类调用;`()` 与 `**` 同权。
|
||||
> 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。
|
||||
|
||||
v2.0.0 把 `##` 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 `[]()` 收窄成了本地遮蔽。
|
||||
v2.1 要补的是**语义**,不是语法:
|
||||
|
||||
1. `#`/`##` → 类/函数;不使用 `self` 的函数是类函数;
|
||||
2. `类.函数` → 类调用;跨文档用项目类索引;
|
||||
3. `[]()` → 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析;
|
||||
4. LinkInfo / view / EKC 的步骤节点与读、推导、遍历、调用、效果、来源边 —— 让代码与文档可查、可看、可验、可建图。
|
||||
|
||||
**一句话**:
|
||||
|
||||
> **不是给 `[]()` 加语法,而是让 `#`/`##` 真正成为类/函数,让 `类.函数` 真正可调用;`[]()` 只是把这次调用写成一句人话。**
|
||||
|
||||
---
|
||||
|
||||
## 附录 A:一页速查
|
||||
|
||||
```markdown
|
||||
# 类
|
||||
## 函数
|
||||
*701*
|
||||
|
||||
# 代码链接(求值)
|
||||
**year = [出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
|
||||
# 正文链接(view/check 解析,run 不执行)
|
||||
李白出生于 [李白的出生年份](李白.李白的出生年份)。
|
||||
|
||||
# 带参类调用
|
||||
**g = [问候](李白.问候("世界"))**
|
||||
```
|
||||
|
||||
| 写法 | 执行 | 用途 |
|
||||
|------|------|------|
|
||||
| `**类.函数**` | ✅ | 普通代码/调用 |
|
||||
| `[描述](类.函数)`(代码内) | ✅ | 带描述的类调用 |
|
||||
| `[描述](类.函数)`(正文) | ❌ run / ✅ view/check | 知识链接 |
|
||||
| `[描述](expr)`(代码内) | ✅ | 本地表达式链接 |
|
||||
| `[描述](url)` | ❌ | 普通导航 |
|
||||
|
||||
## 附录 B:与旧文档的关系
|
||||
|
||||
| 旧文档 | 关系 |
|
||||
|--------|------|
|
||||
| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「命名载荷 + 已有语义」;遮蔽只是显示属性 |
|
||||
| [occlusion-description-and-search.md](occlusion-description-and-search.md) | 标签/桩/检索仍适用;本文把标签归入 LinkInfo |
|
||||
| [change-m7-migration.md](change-m7-migration.md) | 旧取元迁移保留;v2.1 统一按 payload 分类,逐步移除 `markup` |
|
||||
| [objects.md](objects.md) | 扩展:`#` 类是命名空间;`##` 不使用 `self` 时是类函数 |
|
||||
| [module-namespace.md](module-namespace.md) | `import` 仍用于代码模块;链接额外支持项目类索引 |
|
||||
| [engineering-knowledge.md](engineering-knowledge.md) | 链接边接入 EKC 图 |
|
||||
@@ -215,7 +215,9 @@ v0.3:
|
||||
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
|
||||
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
|
||||
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
|
||||
| ` ```lang ` | 外联(不变) |
|
||||
| ` ```lang ` | 外联(不变;绑定仍用 `` `名` = `` + 围栏) |
|
||||
| `$$` 内 `% marqdo: var=名` | 块公式绑定([fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)) |
|
||||
| `- 对`集`的每一项`项`` / `for each` | foreach 叙述糖;推荐 `- [项](集)` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
|
||||
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
|
||||
| 状态 | **Accepted;嵌套 YAML `import:` / `导入:` 映射已锁定** |
|
||||
| 日期 | 2026-08-13 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
@@ -16,9 +16,9 @@
|
||||
|
||||
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
|
||||
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
|
||||
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
|
||||
- 旧 frontmatter 一行式 `import bind:target` 在 YAML 里会变成带空格的键,与正规元信息不兼容。
|
||||
|
||||
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
|
||||
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为嵌套 YAML 映射 `import:\n bind: target`。
|
||||
|
||||
---
|
||||
|
||||
@@ -29,8 +29,8 @@
|
||||
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
|
||||
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
|
||||
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
|
||||
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
|
||||
5. **中英对等**:`import` / `导入`。
|
||||
4. **短名与文件导入同形**:同在 `import:` 映射下写 `fmt: time.format`,废除独立 `use` 关键字。
|
||||
5. **中英对等**:`import:` / `导入:`。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
@@ -54,27 +54,38 @@
|
||||
|
||||
### 3.2 导入句法(frontmatter)
|
||||
|
||||
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
|
||||
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。键为合法 YAML:`import:` / `导入:`,值为嵌套映射。
|
||||
|
||||
```yaml
|
||||
---
|
||||
import:
|
||||
utils: utils.mq.md
|
||||
json: lib/json.mq.md
|
||||
fmt: time.format
|
||||
---
|
||||
```
|
||||
|
||||
| 含义 | 英文 | 中文 |
|
||||
|------|------|------|
|
||||
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
|
||||
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
|
||||
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
|
||||
| 导入文件 | `import:` → `utils: utils.mq.md` | `导入:` → `utils: utils.mq.md` |
|
||||
| 标准库 | `json: lib/json.mq.md` | 同左(或中文库路径) |
|
||||
| 短名(成员) | `fmt: time.format` | `fmt: 时间.格式化` |
|
||||
|
||||
规则:
|
||||
|
||||
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
|
||||
- `:` 右侧 `target`:
|
||||
- **绑定名必填**,为映射键(裸名,无反引号);冒号后须有空格(正规 YAML)。
|
||||
- 映射值 `target`:
|
||||
- 以 `.mq.md` 结尾 → **文件导入**;
|
||||
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
|
||||
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
|
||||
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
|
||||
- 同一文件不得同时出现 `import:` 与 `导入:`。
|
||||
- 旧写法一行式 `import bind:target`、`> ….mq.md`、`> use …` → **硬错误**;可用 `marqdo migrate imports --write` 迁移。
|
||||
|
||||
### 3.3 废除的旧规则
|
||||
|
||||
不再支持:
|
||||
|
||||
- 一行式 `import bind:target` / `导入 bind:target`;
|
||||
- 省略绑定名时用文件名茎作库名;
|
||||
- 导入侧 `as` / `作为`;
|
||||
- 独立关键字 `use` / `使用`。
|
||||
@@ -101,8 +112,9 @@ path_callee ::= ident ('.' ident)+
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -139,8 +151,9 @@ import json:lib/json.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import fmt:time.format
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
fmt: time.format
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -153,10 +166,11 @@ import fmt:time.format
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
writeback: lib/writeback.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -179,13 +193,12 @@ import json:lib/json.mq.md
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
|
||||
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
|
||||
| `import fmt`:time.format
|
||||
| `import time:lib/time.mq.md` | `import:` → `time: lib/time.mq.md` |
|
||||
| `import fmt:time.format` | `import:` → `fmt: time.format` |
|
||||
| 茎名默认库名 | 绑定名始终显式 |
|
||||
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
|
||||
|
||||
不提供旧 `>` 导入过渡开关。
|
||||
不提供旧一行式 / `>` 导入过渡开关;`marqdo migrate imports --write` 可机械迁移。
|
||||
|
||||
---
|
||||
|
||||
@@ -201,20 +214,20 @@ import json:lib/json.mq.md
|
||||
|
||||
## 8. 实现要点
|
||||
|
||||
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
|
||||
1. frontmatter 解析嵌套 `import:` / `导入:` 映射;子项分流文件 / 成员。
|
||||
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
|
||||
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|------|------|
|
||||
| M1+M2 | 点号路径 + 短名 — 已落地 |
|
||||
| **Import 句法** | 统一 `import bind:target` — **本波次** |
|
||||
| **Import 句法** | 嵌套 YAML `import:` — **本波次** |
|
||||
|
||||
---
|
||||
|
||||
## 9. 决议摘要
|
||||
|
||||
1. 导入 = `import bind:target`(`导入` 等价)。
|
||||
1. 导入 = 嵌套 `import:` / `导入:` 映射(`bind: target`)。
|
||||
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
|
||||
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
|
||||
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
|
||||
@@ -0,0 +1,531 @@
|
||||
# 文档会话(View Cells)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime + Document(view 服务端 / 交互单元) |
|
||||
| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
| 核心表面 Δ | 无(读取既有 AST 与表格) |
|
||||
|
||||
> 文档会话是 view 背后的交互单元运行时:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。它不是第二个 CLI 模式——`marqdo view` 是唯一的交互面,`marqdo run` 是规范执行。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **像 Jupyter 一样即时**:点一个 cell 就执行,状态保留。
|
||||
2. **不像 Jupyter 一样隐藏**:执行顺序、内核归属、状态、过期情况都可查。
|
||||
3. **不破坏 Marqdo 程序语义**:`marqdo run` 仍是规范执行;view 会话是交互镜头。
|
||||
4. **Git 友好**:状态/输出不默认写进 `.mq.md`。
|
||||
5. **多语言**:命名内核 + 显式状态桥。
|
||||
6. **可复现**:Run All / journal / dirty / stale / replay。
|
||||
|
||||
---
|
||||
|
||||
## 1.1 实施状态(2026-10-18)
|
||||
|
||||
| 能力 | 状态 | 位置 |
|
||||
|---|---|---|
|
||||
| `foreign.session` 句柄(kernels/cells 表参数) | ✅ | `lib/foreign.mq.md` · `src/host/foreign_doc.rs` |
|
||||
| cell plan 求值 | ✅ 解释器求值 `会话` 绑定;不扫描源码行、不认保留表名 | `src/interp.rs` · `src/host/foreign_doc.rs` |
|
||||
| cell index(绑定名 / 行号 / source hash) | ✅ | 同上 |
|
||||
| 命名内核 + 默认内核 + 语言校验 | ✅ | 同上 |
|
||||
| 同内核共享 / 跨内核隔离 | ✅ | Node 金样例 + 单测 |
|
||||
| `run_cell` / `step` / `run_all(restart)` | ✅ | `DocumentSession` |
|
||||
| `restart_kernel` / `assign_kernel` | ✅ | 同上 |
|
||||
| `kernel/interrupt` | 待做 | — |
|
||||
| 状态桥 `push` / `pull` / `state_list` | ✅ | `DocumentSession` + `foreign_session` |
|
||||
| journal(记录 + API + Journal 按钮) | ✅ | `DocumentSession::journal_json` · view |
|
||||
| view 工具栏 / 状态徽标 / 内核下拉 / 状态表单 | ✅ | `src/view/html.rs` |
|
||||
| `POST /api/session/*` | ✅(含 `reload`) | `src/view/notebook_api.rs` |
|
||||
| cell step | ✅ | 同上 |
|
||||
| Marqdo statement step | ✅(view 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
|
||||
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/host/foreign_doc.rs` |
|
||||
| writeback 集成 | 待做 | `writeback` |
|
||||
| replay / 持久化 | 待做 | — |
|
||||
| Python 会话 | ✅(本机无 python,CI/用户机条件测试) | `src/host/foreign_session.rs` |
|
||||
| Node 会话 | ✅ | 同上 |
|
||||
|
||||
首版刻意不做:把状态写进 `.mq.md`、自动镜像变量、foreign 行级 debug、跨文档共享内核。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两个执行面(不是两个 CLI 模式)
|
||||
|
||||
### 2.1 Program execution(规范)
|
||||
|
||||
- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。
|
||||
- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。
|
||||
- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。
|
||||
- 结果:可复现;是文档的“真理”。
|
||||
|
||||
### 2.2 View cells(交互)
|
||||
|
||||
- 入口:`marqdo view doc.mq.md` → 文档单元(cell)控制。
|
||||
- 执行:按 `会话表`(或自动顺序)逐 cell 执行。
|
||||
- 状态:内核持久;可切换、重启、单步。
|
||||
- 结果:默认临时显示;可显式 writeback。
|
||||
- 不是“真理”:是探索界面;需要复现时用 Run All 或把编排写进 `# main`。
|
||||
|
||||
### 2.3 两者关系
|
||||
|
||||
```text
|
||||
.mq.md
|
||||
/ \
|
||||
Program run View cells
|
||||
(canonical) (interactive)
|
||||
\ /
|
||||
Document Session
|
||||
├── cell index
|
||||
├── kernel registry
|
||||
├── journal
|
||||
└── state panel
|
||||
```
|
||||
|
||||
- 共享 cell index 与 kernel registry。
|
||||
- `run` 不消费视图会话;`view` 只在文档绑定 `会话 = > foreign.session ...` 时提供持久 cell 控制;无 `会话` 时 cells 无状态一次性执行。
|
||||
- 冲突时以 `run` 的程序语义为准;view cells 不改变文档语义。
|
||||
|
||||
---
|
||||
|
||||
## 3. 文档会话模型
|
||||
|
||||
```text
|
||||
DocumentSession
|
||||
├── doc_path / doc_hash
|
||||
├── cells: Vec<Cell>
|
||||
│ ├── id (name / anon@line)
|
||||
│ ├── name (binding)
|
||||
│ ├── lang
|
||||
│ ├── line_start / line_end
|
||||
│ ├── source_hash
|
||||
│ ├── kernel (resolved)
|
||||
│ └── status: never | clean | dirty | stale | error | running
|
||||
├── kernels: KernelRegistry
|
||||
│ ├── name → ForeignSession
|
||||
│ └── default per language
|
||||
├── value_store: HashMap<String, Value> // Marqdo 侧会话值
|
||||
├── journal: Vec<ExecutionRecord>
|
||||
├── created_ms / last_active_ms
|
||||
└── surface: program | view
|
||||
```
|
||||
|
||||
### 3.1 Cell
|
||||
|
||||
- 只有**绑定名**的代码围栏才是 cell:
|
||||
```markdown
|
||||
`加载` =
|
||||
```python
|
||||
...
|
||||
```
|
||||
```
|
||||
- 未绑定围栏仍是叙述,不是 cell。
|
||||
- `id`:优先绑定名;匿名围栏用 `anon@<line>`(不进入会话表)。
|
||||
- 同名 cell 重复 → 诊断;会话表按名字引用。
|
||||
- `source_hash` 用于 dirty 判断。
|
||||
- `line_start/line_end` 用于定位;编辑后重建索引。
|
||||
|
||||
### 3.2 Cell index 构建
|
||||
|
||||
1. 读取/解析文档(现有 `parse_source` / `load_module`)。
|
||||
2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。
|
||||
3. 记录 name、lang、source、span、source hash。
|
||||
4. 通过解释器求值 `会话` 绑定(`foreign.session` 返回的句柄,含简单依赖);不扫描源码行、不认保留表名(见 [notebook-syntax.md](notebook-syntax.md))。
|
||||
5. 解析 kernel 声明与 cell 归属;校验;生成诊断。
|
||||
6. 生成执行顺序:
|
||||
- 有会话表 → 行顺序;
|
||||
- 无 → 文档顺序。
|
||||
7. 未入会话的 cell → 状态 `unlisted`,UI 显示徽标。
|
||||
|
||||
### 3.3 Kernel registry
|
||||
|
||||
- key:`<document_id>:<kernel_name>`。
|
||||
- 默认:`default:python`、`default:node`,按需启动。
|
||||
- 命名:来自 `内核表`,首次执行时启动。
|
||||
- 状态:`idle | starting | ready | busy | dead`。
|
||||
- 同一 kernel 的 cell 严格串行;不同 kernel 可并行。
|
||||
- 重启:kill + 清空状态 + 重新启动;cell 状态变 `never`。
|
||||
- 关闭:kill + 移除。
|
||||
|
||||
### 3.4 Value store(Marqdo 侧会话值)
|
||||
|
||||
- 保存可从 Marqdo 推入内核的值(来自最近一次 Program run 的 bindings,或用户手动输入)。
|
||||
- 也保存从内核取回的值(`session_get` / 状态面板 Pull)。
|
||||
- 不是解释器 Env 的实时镜像;它是会话层的**值缓存**。
|
||||
- 注入解释器:未来通过 `SessionEnv` 或显式变量赋值;v2 不做隐式注入。
|
||||
- 用途:
|
||||
- 状态面板显示;
|
||||
- Push 到内核;
|
||||
- 作为 `session_set` 的值来源;
|
||||
- journal 记录。
|
||||
|
||||
### 3.5 Journal
|
||||
|
||||
每次执行追加一条:
|
||||
|
||||
```json
|
||||
{
|
||||
"seq": 3,
|
||||
"cell": "汇总",
|
||||
"kernel": "分析",
|
||||
"lang": "python",
|
||||
"ok": true,
|
||||
"code": 0,
|
||||
"ms": 42,
|
||||
"source_hash": "…",
|
||||
"stdout_hash": "…",
|
||||
"result_hash": "…",
|
||||
"started_ms": 1760000000000,
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
用途:
|
||||
|
||||
- 执行序号 / 顺序;
|
||||
- dirty/stale 判断;
|
||||
- replay;
|
||||
- 视图显示;
|
||||
- 调试(“为什么这个 cell 有值”)。
|
||||
|
||||
存储:内存 + 可选 `.marqdo/sessions/<doc-hash>.json`(默认 git 忽略)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 执行语义
|
||||
|
||||
### 4.1 操作
|
||||
|
||||
| 操作 | 语义 |
|
||||
|---|---|
|
||||
| **Run cell** | 执行选中的 cell;必要时启动/复用 kernel |
|
||||
| **Run above** | 按会话顺序执行到选中 cell(含) |
|
||||
| **Run all** | 按会话顺序执行全部;可选 `restart` |
|
||||
| **Step next cell** | 执行会话顺序中的下一个未执行/选中 cell |
|
||||
| **Step next statement** | Marqdo 语句级单步(DebugController) |
|
||||
| **Restart kernel** | kill + 重建;cell 状态 `never` |
|
||||
| **Interrupt** | kill 当前 cell 进程组;kernel 标记 dead 或重启 |
|
||||
| **Reset session** | 关闭所有 kernel,清 journal / value store |
|
||||
|
||||
### 4.2 执行一个 cell
|
||||
|
||||
```text
|
||||
resolve cell -> resolve kernel
|
||||
-> ensure kernel ready
|
||||
-> [送入?] 显式 bridge 由文档代码/UI 负责
|
||||
-> foreign.session_eval(kernel, source, input?)
|
||||
-> record -> update cell status
|
||||
-> [取回?] 由文档代码/UI 负责
|
||||
-> journal append
|
||||
-> view update
|
||||
```
|
||||
|
||||
- 默认 cwd = 文档目录;env = kernel env。
|
||||
- 输出:stdout / stderr / result / ms / truncated。
|
||||
- 失败:cell 状态 `error`;journal 记录;不自动重试。
|
||||
- 同一 kernel 串行;UI 禁用并发 Run。
|
||||
|
||||
### 4.3 Step 语义
|
||||
|
||||
| 类型 | 行为 |
|
||||
|---|---|
|
||||
| **Cell step** | 执行下一个会话 cell;状态保留 |
|
||||
| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 |
|
||||
| **Foreign line step** | 不做;未来 DAP |
|
||||
|
||||
- Cell step 是 view cells 的主单步。
|
||||
- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。
|
||||
- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。
|
||||
|
||||
### 4.4 中断
|
||||
|
||||
- `Interrupt`:向当前 kernel 进程组发 SIGINT/SIGKILL;记录 `interrupted`。
|
||||
- 若 kernel 状态不确定 → 标记 dead;建议 restart。
|
||||
- 不允许“中断后继续用同一 kernel”除非确认状态。
|
||||
|
||||
### 4.5 并发
|
||||
|
||||
- 同一 kernel:一次一个 cell。
|
||||
- 不同 kernel:可并行(例如 Python 分析与 Node 前端)。
|
||||
- `Run all` 默认按会话顺序串行;可配置“按 kernel 并行、按依赖串行”(后续)。
|
||||
- 并发上限沿用 foreign(32)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 状态桥(会话层)
|
||||
|
||||
### 5.1 显式 API
|
||||
|
||||
文档代码:
|
||||
|
||||
```markdown
|
||||
把 `数值表` 送进 `分析` 内核:
|
||||
**> foreign.session_set id="分析" name="xs" value=`数值表`**
|
||||
|
||||
从 `分析` 内核取回 `mean`:
|
||||
**`均值` = > foreign.session_get id="分析" name="mean"**
|
||||
```
|
||||
|
||||
### 5.2 状态面板
|
||||
|
||||
- 左侧:Marqdo 侧值(最近 Program run bindings + value store)。
|
||||
- 右侧:每个 kernel 的变量(`session_names` + 按需 `session_get`)。
|
||||
- 操作:
|
||||
- Push:选 Marqdo 值 → kernel 变量;
|
||||
- Pull:选 kernel 变量 → value store / 显示;
|
||||
- Refresh;
|
||||
- 复制名称/值。
|
||||
- Secret 打码;大对象显示摘要(类型/长度/repr 截断)。
|
||||
|
||||
### 5.3 自动镜像
|
||||
|
||||
- v2 不做。
|
||||
- 后续 `mirror`:`mq_` 前缀、白名单、按值拷贝、默认关。
|
||||
- 原因见 [decisions](../research/foreign-notebook-decisions.md) §1-F。
|
||||
|
||||
### 5.4 类型
|
||||
|
||||
- JSON 拷贝;复杂对象需 `to_dict` / JSON。
|
||||
- 大对象:v2 显示摘要;传输用文件/DB。
|
||||
- 未来:Arrow / Parquet / 共享文件句柄。
|
||||
|
||||
---
|
||||
|
||||
## 6. Dirty / Stale / Run All
|
||||
|
||||
### 6.1 定义
|
||||
|
||||
| 状态 | 条件 |
|
||||
|---|---|
|
||||
| `never` | 未执行 |
|
||||
| `clean` | 上次执行成功后源码未变 |
|
||||
| `dirty` | 源码 hash 变了 |
|
||||
| `stale` | 上游 cell 变了(依赖图;v2 先按会话顺序近似) |
|
||||
| `error` | 上次执行失败 |
|
||||
| `running` | 正在执行 |
|
||||
| `unlisted` | 不在会话表 |
|
||||
|
||||
### 6.2 依赖
|
||||
|
||||
- v2:会话表行顺序 + 简单规则:
|
||||
- 若上游 cell 的 source_hash 变了,下游标 `stale`;
|
||||
- 若 kernel 重启,全部 `never`。
|
||||
- v2.1:变量级依赖图(静态分析 + bridge 表),精确 stale。
|
||||
- 不假装 Jupyter 的“隐藏顺序”:顺序就是表/文档顺序。
|
||||
|
||||
### 6.3 Run All
|
||||
|
||||
- 默认:按会话顺序执行;可选 `restart=true`。
|
||||
- 规范执行:**restart + run all**;UI 明确按钮 `Restart & Run All`。
|
||||
- 未重启时:显示“当前 kernel 有历史状态”警告。
|
||||
- 执行后:生成 session summary(ok/fail/耗时/跳过的 cell)。
|
||||
|
||||
### 6.4 Replay
|
||||
|
||||
- 用 journal 的顺序和输入 hash,在新 kernel 上重放;
|
||||
- 比较 stdout/result hash;
|
||||
- 输出 divergence 报告。
|
||||
- v2 可选;至少保留 journal 以便未来实现。
|
||||
|
||||
---
|
||||
|
||||
## 7. 输出与文档
|
||||
|
||||
### 7.1 默认
|
||||
|
||||
- View cells 输出只在 view 中显示;不写 `.mq.md`。
|
||||
- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。
|
||||
- 不写 execution_count 到文档。
|
||||
|
||||
### 7.2 显式 writeback
|
||||
|
||||
- 复用 `lib/writeback` 的 `<!-- marqdo-out … -->`。
|
||||
- cell 输出锚点:cell 名 + 行号;写入位置在围栏之后,或文档末尾的“输出”区。
|
||||
- 可选:
|
||||
- 单 cell 写回;
|
||||
- 全部写回;
|
||||
- 只写回文本/数值,不写复杂对象。
|
||||
- Git 友好:输出是普通 Markdown 注释块;可 diff、可忽略。
|
||||
|
||||
### 7.3 不写回
|
||||
|
||||
- 避免 Jupyter 的 `.ipynb` 输出噪声。
|
||||
- 需要分享结果时,导出 HTML / 静态 view,而不是改源文件。
|
||||
|
||||
---
|
||||
|
||||
## 8. View 交互
|
||||
|
||||
### 8.1 工具栏
|
||||
|
||||
```text
|
||||
[Run All] [Restart & Run All] [Step Cell] [Step Statement]
|
||||
Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
[State] [Journal] [Writeback ▾]
|
||||
```
|
||||
|
||||
### 8.2 每个 code card
|
||||
|
||||
```text
|
||||
`加载` python · kernel 分析 · run #3 · 42ms · clean
|
||||
[Run] [Step] [Kernel ▾] [State] [Copy output]
|
||||
```
|
||||
|
||||
- 状态徽标:`never` / `clean` / `dirty` / `stale` / `error` / `running` / `unlisted`。
|
||||
- 输出区:stdout / stderr / result / 截断提示。
|
||||
- 内核下拉:切换归属;不迁移状态;提示需要重跑。
|
||||
- `Step` = 执行此 cell(cell step)。
|
||||
|
||||
### 8.3 状态面板
|
||||
|
||||
- Marqdo / kernel 分栏。
|
||||
- Push/Pull。
|
||||
- Secret 打码。
|
||||
- 大对象摘要 + 复制 JSON。
|
||||
|
||||
### 8.4 Journal 面板
|
||||
|
||||
- 表格:seq / cell / kernel / ok / ms / 时间 / 错误。
|
||||
- 点击跳转 cell。
|
||||
- 导出 JSON。
|
||||
|
||||
### 8.5 键盘
|
||||
|
||||
- `Ctrl/Cmd + Enter`:Run cell。
|
||||
- `Shift + Enter`:Run cell + 下一个。
|
||||
- `Alt + Enter`:Run cell + 插入?不做。
|
||||
- `F10`:Step statement(与 debug 一致)。
|
||||
- `F5`:Run All。
|
||||
|
||||
---
|
||||
|
||||
## 9. 服务端 API
|
||||
|
||||
所有 API 以文档相对路径 + session id 定位;session 内存驻留,进程退出即失。
|
||||
|
||||
| 方法 | 路径 | 作用 |
|
||||
|---|---|---|
|
||||
| POST | `/api/session/open` | 打开文档会话,返回 cells / kernels / journal |
|
||||
| POST | `/api/session/close` | 关闭会话,kill 所有 kernel |
|
||||
| POST | `/api/session/reload` | 重新解析文档,保留 kernel(标记 dirty) |
|
||||
| POST | `/api/session/cell/run` | 执行指定 cell |
|
||||
| POST | `/api/session/cell/step` | 执行下一个 cell |
|
||||
| POST | `/api/session/run_all` | 按会话顺序执行;`restart` 可选 |
|
||||
| POST | `/api/session/kernel/restart` | 重启指定 kernel |
|
||||
| POST | `/api/session/kernel/interrupt` | 中断当前 cell |
|
||||
| POST | `/api/session/kernel/assign` | 改 cell 的 kernel 归属(会话内) |
|
||||
| POST | `/api/session/state/list` | Marqdo / kernel 变量列表 |
|
||||
| POST | `/api/session/state/push` | Marqdo 值 → kernel |
|
||||
| POST | `/api/session/state/pull` | kernel 变量 → value store |
|
||||
| POST | `/api/debug/*` + `/debug` | Marqdo 语句单步(Debug 按钮,复用 debugger) |
|
||||
| POST | `/api/session/writeback` | 显式写回 cell 输出 |
|
||||
| POST | `/api/session/journal` | 执行日志 |
|
||||
| GET | `/api/session` | 当前会话摘要 |
|
||||
|
||||
响应统一:`{ok, session, ...}`;错误 `{ok:false, error, code?}`。
|
||||
|
||||
---
|
||||
|
||||
## 10. 生命周期与持久化
|
||||
|
||||
- Session key:`<root>/<doc_rel>`;每个文档一个。
|
||||
- 打开:解析、建 cell index、按需启动 kernel。
|
||||
- 空闲超时:默认 30 分钟关闭(可配置)。
|
||||
- 文档关闭 / 服务退出:kill 所有 kernel。
|
||||
- 文件变更:view 刷新时 `reload`;cell hash 变化 → dirty;kernel 保留。
|
||||
- 持久化(可选):
|
||||
- `.marqdo/sessions/<doc-hash>.json`:kernel 名称/语言、cell 归属、journal、value store 摘要;
|
||||
- 默认 git 忽略;
|
||||
- 不持久化进程状态 / 大对象。
|
||||
- 不把 session 状态写进 `.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 11. 安全
|
||||
|
||||
| 项 | 策略 |
|
||||
|---|---|
|
||||
| exec | 所有 kernel 启动/执行检查 `allow_exec`;沙箱拒绝 |
|
||||
| 生命周期 | 每文档;关闭/drop kill;不跨文档 |
|
||||
| cwd | 文档目录 / `fs_root`;越界拒绝 |
|
||||
| 输出 | 有界;截断标记 |
|
||||
| 超时 | cell 级;进程组 kill |
|
||||
| 中断 | 杀进程组;kernel 标记 dead |
|
||||
| Secret | 状态面板打码;JSON 不默认暴露 |
|
||||
| 未信任文档 | 不自动打开会话;必须显式 Run |
|
||||
| 并发 | 同 kernel 串行;不同 kernel 上限 32 |
|
||||
| writeback | 显式;路径沙箱;不自动改文档 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 测试
|
||||
|
||||
### 12.1 服务端
|
||||
|
||||
- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。
|
||||
- 会话解析:foreign.session 句柄/自动模式/重复/未知/语言不匹配。
|
||||
- 会话:open/close/reload;kernel 启动/重启/中断。
|
||||
- cell run:状态机 never→running→clean/error;dirty/stale。
|
||||
- step:cell step 顺序;statement step 与 debug 联动。
|
||||
- state:push/pull/list;Secret 打码;大对象摘要。
|
||||
- journal:顺序、hash、失败。
|
||||
- 并发:同 kernel 串行;不同 kernel 并行。
|
||||
- 安全:exec=false 拒绝;cwd 越界;超时。
|
||||
|
||||
### 12.2 金样例
|
||||
|
||||
- `tests/notebook/kernels.mq.md`:foreign.session 句柄。
|
||||
- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。
|
||||
- `tests/notebook/step.mq.md`:cell step 顺序。
|
||||
- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。
|
||||
- `tests/notebook/invalid-*.mq.md`:诊断。
|
||||
- 依赖:node 为主,python 条件跳过。
|
||||
|
||||
### 12.3 UI
|
||||
|
||||
- 手工冒烟:Run cell / Step / Run All / Restart / State Push/Pull / Journal。
|
||||
- 不引入前端测试框架;用服务端 API + 静态检查。
|
||||
|
||||
---
|
||||
|
||||
## 13. 与 Jupyter 对照
|
||||
|
||||
| 维度 | Jupyter | Document Session |
|
||||
|---|---|---|
|
||||
| 源 | `.ipynb` | `.mq.md` |
|
||||
| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal |
|
||||
| 状态 | 隐藏 kernel | kernel + value store + 状态面板 |
|
||||
| 多语言 | 一文档一 kernel | 命名内核 + 每 cell 归属 |
|
||||
| 单步 | cell | cell + statement |
|
||||
| 复现 | 手动 | Restart & Run All + journal + replay |
|
||||
| Git | 输出/计数噪声 | 源码干净;输出显式 |
|
||||
| 知识 | 无 | OKF / catalog |
|
||||
| 调试 | 语言 pdb | Marqdo 断点 + cell 级;行级后续 |
|
||||
|
||||
---
|
||||
|
||||
## 14. 实现顺序(D 层)
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|---|---|
|
||||
| D0 | 设计/语法/决策文档(本文件) |
|
||||
| D1 | `src/host/foreign_doc.rs`:cell index、foreign.session 句柄、session 结构、诊断 |
|
||||
| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt |
|
||||
| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal |
|
||||
| D4 | statement step 接入;dirty/stale;writeback |
|
||||
| D5 | replay / 持久化 / 并发优化 / 测试补全 |
|
||||
|
||||
依赖 F 层:F3 持久内核、F3.5 状态桥先完成,D2 才能工作。
|
||||
|
||||
---
|
||||
|
||||
## 15. 明确不做(v2)
|
||||
|
||||
- Foreign line-level step。
|
||||
- 自动镜像变量。
|
||||
- 跨文档共享 kernel。
|
||||
- 全进程快照。
|
||||
- 自动执行 cell。
|
||||
- 把 session 状态写进 `.mq.md`。
|
||||
- 前端 SPA 框架重写;沿用现有 HTML/JS。
|
||||
@@ -0,0 +1,305 @@
|
||||
# 文档原生 view cells 语法
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Decided;D1 解析已实现** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Document(读取约定) + Runtime(校验) |
|
||||
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-session.md](notebook-session.md) · [foreign-kernel.md](foreign-kernel.md) · [core-surface.md](core-surface.md) · [layers.md](layers.md) |
|
||||
| 核心表面 Δ | **无**——不新增标记;只用既有 `# main` / 赋值 / 表格 / 反引号 |
|
||||
|
||||
> 目标:让“这段代码在哪个内核里、按什么顺序执行、和谁共享状态”像目录一样可读,而不是像 IDE 配置一样可读。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么不用围栏元数据
|
||||
|
||||
Jupyter 的 cell 元数据、VS Code 的 `kernel=`、YAML 的 `kernels:` 都属于**代码/编辑器思维**:
|
||||
|
||||
- 读者看到的是一行属性,不是一段知识;
|
||||
- 属性藏在围栏 info string 或 JSON 里,Markdown 预览看不见意图;
|
||||
- 一旦加 `kernel=`,它就是 Language 层语法,需要 ADR、core-surface 增行;
|
||||
- 同一个文档的执行计划被拆散到每个围栏,无法一眼总览。
|
||||
|
||||
Marqdo 的选择:
|
||||
|
||||
> **执行计划本身是一张表。表是文档的一部分,人先读表,机器再读表。**
|
||||
|
||||
这不是新语法。GFM 表已经是集合,`` `名` = `` + 表已经是数据绑定;我们只约定两个**数据表的名字**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两个约定数据表
|
||||
|
||||
它们放在 `# main`(或唯一入口对象)的体内,和代码单元并列:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 读取与清洗数据 |
|
||||
| 绘图 | python | | 独立环境 |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 加载 | 分析 | 读取原始数据 |
|
||||
| 清洗 | 分析 | 处理缺失值 |
|
||||
| 汇总 | 分析 | 按城市聚合 |
|
||||
| 绘图 | 绘图 | 输出 SVG |
|
||||
```
|
||||
|
||||
为什么是“绑定的表”,不是 `# 外联内核` 对象:
|
||||
|
||||
- `#` 是对象/函数;把元数据做成顶层对象会把文档拆成多个作用域,code fence 会被困在对象里。
|
||||
- 绑定表是入口体内的**数据**,与 cell 同一作用域;不执行、不改变控制流。
|
||||
- View / 文档会话读取 AST 中的绑定值,不需要执行文档。
|
||||
- 解析器零改动。
|
||||
|
||||
### 2.1 `内核表` / `kernels`
|
||||
|
||||
| 列 | 必填 | 含义 |
|
||||
|---|---|---|
|
||||
| `名称` / `Name` | ✅ | 内核名,供 `会话表` 引用;建议用领域词(分析/绘图/前端) |
|
||||
| `语言` / `Language` | ✅ | 预设 id 或已注册语言:`python` / `node` / … |
|
||||
| `命令` / `Command` | 可选 | 覆盖解释器命令;空白 = 预设 / `set_cmd` / 配置 / 环境变量 |
|
||||
| `说明` / `Notes` | 可选 | 给人读的一句话;不影响执行 |
|
||||
|
||||
规则:
|
||||
|
||||
- 名称在文件内唯一;重复 → 诊断。
|
||||
- 语言不支持会话时,内核仍可声明,但只能执行一次性 cell;`session_*` 报错。
|
||||
- `命令` 只写可执行文件;参数请用 `.marqdo/foreign.toml` 或 `session_open`。
|
||||
- 没有 `内核表`:每种语言自动一个 `default` 内核。
|
||||
- 声明了内核但 `会话表` 没引用:允许,只是没有被使用。
|
||||
|
||||
### 2.2 `会话表` / `session`
|
||||
|
||||
| 列 | 必填 | 含义 |
|
||||
|---|---|---|
|
||||
| `单元` / `Cell` | ✅ | 代码围栏的绑定名(`` `加载` = `` 后面的名字),表格里**不写反引号** |
|
||||
| `内核` / `Kernel` | ✅ | `内核表` 中的名称,或语言 id(`python` / `node`)表示该语言默认内核 |
|
||||
| `说明` / `Notes` | 可选 | 给人读的一句话 |
|
||||
|
||||
规则:
|
||||
|
||||
- **行顺序 = 执行顺序**。这是 `Run All`、`Step`、`Run Above` 的规范顺序。
|
||||
- 只有列出的 cell 参与会话;未列出的代码围栏仍然显示,但标记为“未入会话”,Run All 不执行。
|
||||
- 没有 `会话表`:所有绑定名的代码围栏按**文档出现顺序**自动入会话,每种语言用默认内核。
|
||||
- `单元` 必须对应一个已绑定名的代码围栏;找不到 → 诊断。
|
||||
- 同名 cell 重复出现 → 诊断;建议一个名字只绑一个围栏。
|
||||
- `内核` 未声明且不是语言 id → 诊断,列出已声明内核。
|
||||
- cell 的语言与内核语言不一致 → 诊断;别名等价(`python3`/`py` ↔ `python`)。
|
||||
- 表可以出现在 `# main` 体内任意位置;读者可以从表一眼看到执行计划。
|
||||
|
||||
### 2.3 为什么放在 `# main` 体内
|
||||
|
||||
- `# main` 是入口;cell 绑定与元数据表同一作用域。
|
||||
- `marqdo run` 会正常求值这两个表(得到 `List of Map`),没有副作用。
|
||||
- 文档会话从 AST / 最近一次运行的 bindings 读取它们;不需要新的解析路径。
|
||||
- 如果文档没有 `# main` 而是唯一 `#` 对象,同样适用。
|
||||
|
||||
---
|
||||
|
||||
## 3. 完整示例
|
||||
|
||||
````markdown
|
||||
# main
|
||||
|
||||
这份文档演示一个最小 view cells 文档:两个 Python 单元共享 `分析` 内核,
|
||||
一个绘图单元在隔离的 `绘图` 内核里运行。
|
||||
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 数据读取与聚合 |
|
||||
| 绘图 | python | | 独立绘图环境 |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 加载 | 分析 | 读取原始数据 |
|
||||
| 清洗 | 分析 | 处理缺失值 |
|
||||
| 汇总 | 分析 | 按城市聚合 |
|
||||
| 绘图 | 绘图 | 输出 SVG |
|
||||
|
||||
`加载` =
|
||||
```python
|
||||
import json
|
||||
|
||||
rows = [
|
||||
{"city": "上海", "value": 3},
|
||||
{"city": "北京", "value": 5},
|
||||
]
|
||||
print(json.dumps(rows, ensure_ascii=False))
|
||||
```
|
||||
|
||||
`清洗` =
|
||||
```python
|
||||
rows = [r for r in rows if r["value"] > 0]
|
||||
```
|
||||
|
||||
`汇总` =
|
||||
```python
|
||||
from collections import Counter
|
||||
|
||||
counts = Counter(r["city"] for r in rows)
|
||||
print(dict(counts))
|
||||
```
|
||||
|
||||
`绘图` =
|
||||
```python
|
||||
print("plot-ready")
|
||||
```
|
||||
|
||||
`汇总` 和 `绘图` 分属两个内核;`绘图` 看不到 `rows`。
|
||||
需要共享时,用 Marqdo 显式把值送过去:
|
||||
|
||||
**> foreign.session_set id="绘图" name="rows" value=`rows`**
|
||||
````
|
||||
|
||||
读者即使不运行,也能从 `会话表` 读出:先加载、再清洗、再汇总,最后绘图;前三个共享 `分析`,绘图在 `绘图`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 自动模式(没有表)
|
||||
|
||||
### 4.1 没有任何约定表
|
||||
|
||||
````markdown
|
||||
# main
|
||||
|
||||
`分析` =
|
||||
```python
|
||||
x = 41
|
||||
```
|
||||
|
||||
`结论` =
|
||||
```python
|
||||
print(x + 1)
|
||||
```
|
||||
````
|
||||
|
||||
解释:
|
||||
|
||||
- 两个 cell 都是 `python`;
|
||||
- 自动使用 `default:python` 内核(一个);
|
||||
- 按文档顺序执行;
|
||||
- 共享 `x`。
|
||||
|
||||
现有文档不需要改一行就能在 view 里 cell-by-cell 运行。
|
||||
|
||||
### 4.2 只有内核表
|
||||
|
||||
- 所有 cell 按文档顺序;
|
||||
- 每种语言解析到该语言的 `default` 内核;
|
||||
- 命名内核只有被 `会话表` 引用时才使用。
|
||||
|
||||
### 4.3 只有会话表
|
||||
|
||||
- `内核` 列只能写语言 id;
|
||||
- 每个语言 id 解析到该语言默认内核;
|
||||
- 未列出的 cell 不入会话。
|
||||
|
||||
---
|
||||
|
||||
## 5. 可读性规则(语法评审标准)
|
||||
|
||||
新增/修改任何 cell 表约定,必须满足:
|
||||
|
||||
1. **先读人话**:去掉执行语义后,表格仍像目录/清单。
|
||||
2. **不使用属性串**:不写 `kernel=…`、`class=…`、JSON/YAML 元数据。
|
||||
3. **不隐藏意图**:执行顺序、内核归属必须在一处可见。
|
||||
4. **不引入新标记**:只用 `#` / 表格 / 反引号 / 既有代码面。
|
||||
5. **默认安全**:表格只声明,不自动执行;只有 Run / Step 触发。
|
||||
6. **命名用领域词**:`分析`、`绘图`、`前端`,不用 `k1`、`default`、`stage2`(除非确实是默认)。
|
||||
7. **说明列可选但推荐**:给未来的读者/LLM 一点上下文。
|
||||
8. **错误可读**:诊断要指出“哪个单元、哪个内核、哪一行、怎么修”。
|
||||
9. **中英对称**:中文用中文列名,英文用英文列名;语义一一对应。
|
||||
10. **无表也能跑**:约定表是增强,不是前置条件。
|
||||
|
||||
---
|
||||
|
||||
## 6. 诊断规范
|
||||
|
||||
| 情况 | 诊断(中文示例) | 修复建议 |
|
||||
|---|---|---|
|
||||
| 内核名重复 | `内核表: 内核名「分析」重复(第 12、20 行)` | 改名或合并 |
|
||||
| 会话引用未知内核 | `foreign.session: cell「汇总」引用了未声明的内核「分析」` | 在 kernels 表声明,或改用语言 id |
|
||||
| 会话引用未知单元 | `会话表: 找不到名为「清洗」的代码单元` | 检查 `` `清洗` = `` 绑定 |
|
||||
| 单元重复 | `会话表: 单元「汇总」重复出现` | 每个单元只列一次 |
|
||||
| 语言不匹配 | `会话表: 单元「前端」(node) 不能使用 python 内核「分析」` | 换内核或换语言 |
|
||||
| 未入会话 | (非错误)view 徽标:`未入会话` | 需要时加一行 |
|
||||
| 内核表为空 | `内核表: 至少声明一个内核,或删除该表使用默认内核` | 删除表或补行 |
|
||||
| 会话表为空 | `会话表: 至少列出一个单元,或删除该表使用自动顺序` | 删除表或补行 |
|
||||
|
||||
原则:**不静默忽略**。读者必须知道为什么某个 cell 没跑。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与 program execution 的关系
|
||||
|
||||
- `内核表` / `会话表` 只是传递给 `foreign.session` 的普通表变量,不是保留名。
|
||||
- `marqdo run` 仍然执行 `# main` 的程序语义;这两个表会被求值为普通数据。
|
||||
- `run` 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);`foreign.session` 句柄服务 `view` 的 cells 与一键 Run All。
|
||||
- 两者可以并存:
|
||||
- 文档用表描述“交互时怎么跑”;
|
||||
- `# main` 用显式调用描述“CI 时怎么跑”。
|
||||
- 如果两者冲突,以 `run` 的程序语义为准;cell 表只影响 `view`。
|
||||
|
||||
这样避免把“执行计划”变成第二套程序语义。
|
||||
|
||||
---
|
||||
|
||||
## 8. 状态桥的语法边界
|
||||
|
||||
v2 **不**为状态交换新增表格/注释。原因:
|
||||
|
||||
- “什么时候送、什么时候取、送到哪个内核、赋值给哪个 Marqdo 变量”需要精确语义;
|
||||
- 若做成隐式表格动作,容易产生隐藏状态与顺序歧义;
|
||||
- v2 先用显式 API,把时序讲清楚:
|
||||
```markdown
|
||||
把 `数值表` 送进 `分析` 内核:
|
||||
**> foreign.session_set id="分析" name="xs" value=`数值表`**
|
||||
|
||||
从 `分析` 内核取回 `mean`:
|
||||
**`均值` = > foreign.session_get id="分析" name="mean"**
|
||||
```
|
||||
- view 提供状态面板与 Push/Pull 按钮,减少手写 API 的需要;
|
||||
- 声明式 `共享表` 作为 v2.1 提案,等 session value store 与“每次单元执行前后”的时序稳定后再引入。
|
||||
|
||||
这不是降级:v2 的功能完整(可读可写、可推可拉),只是不用隐式语法承载时序。
|
||||
|
||||
---
|
||||
|
||||
## 9. 未来扩展(不承诺进 v2)
|
||||
|
||||
1. `共享表`:
|
||||
`| 内核变量 | Marqdo 变量 | 方向 | 说明 |`,每次单元执行前送入、后取回。
|
||||
2. 每个 cell 的“运行条件/依赖”列:`依赖` 列声明上游单元。
|
||||
3. 内核别名:`内核表` 的 `名称` 可被 `use` 或短名引用。
|
||||
4. 多文件会话:跨 `.mq.md` 的共享内核(默认仍隔离)。
|
||||
5. 语言特定的“会话能力”列(是否支持持久、是否支持行级调试)。
|
||||
|
||||
任何一项都要先过 §5 的可读性规则与 `core-surface` 检查。
|
||||
|
||||
---
|
||||
|
||||
## 10. 实现落点
|
||||
|
||||
| 逻辑 | 位置 |
|
||||
|---|---|
|
||||
| 识别 `会话` 的 foreign.session 句柄 | `src/host/foreign_doc.rs` |
|
||||
| 读取绑定值 | AST `Stmt::Assign` + `Expr::Table` / `Expr::List`;或最近一次 run 的 bindings |
|
||||
| 校验名称/语言/重复/未入会话 | 同上;错误进入现有 Diagnostic |
|
||||
| cell index(绑定名/行号/语言/source hash) | 解析后的 `Module` 遍历 |
|
||||
| 只读展示 | view Structure:表渲染成普通表格 + 徽标 |
|
||||
| 执行 | Document Session API(见 [notebook-session.md](notebook-session.md)) |
|
||||
|
||||
解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。
|
||||
@@ -0,0 +1,426 @@
|
||||
# 遮蔽描述与两级检索:内置词表做范例,参数做扩展
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 实施中**(与 [occlusion-syntax.md](occlusion-syntax.md) 同步) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 关键决策 | ①`[]` 是自由描述,不执行 ②**两级词表**:内置=范例/默认,参数=扩展 ③空载荷**一律 warning** ④工程化写进 README,提示词同步更新 |
|
||||
| 前置 | [occlusion-syntax.md](occlusion-syntax.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 五条定调
|
||||
|
||||
1. **`[]` 里是纯粹的描述文字,对执行没有任何作用。** 编译器**不解析**,只做**检索**。
|
||||
2. **两级词表**:
|
||||
- **内置词表 = 范例 + 默认检索集**(零配置可用;给 LLM 一个稳定范式)
|
||||
- **参数 = 扩展/覆盖**(`--grep 任意词`,项目自己的说法照样能搜)
|
||||
3. **空载荷一律 warning**:`()` 为空说明"这段遮蔽里没有可执行内容",写 `None` 即消除。
|
||||
4. **强力推荐 LLM 申报**:写不了真接口就"申报",别"假装"。提示词同步更新。
|
||||
5. **工程化实践写进 README**,不另造文档。
|
||||
|
||||
一句话:
|
||||
|
||||
> **描述给人读;内置词给个范式;参数给自由;空着不写会被提醒。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么要允许「假接通」
|
||||
|
||||
模型被要求"接入搜索"时,最省力的是写个返回固定值的函数,然后声称已接通。
|
||||
|
||||
| 处理方式 | 结果 | 问题 |
|
||||
|---------|------|------|
|
||||
| **A 禁止**("不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 |
|
||||
| **B 放任** | 静默假功能 | 文档撒谎,没人知道欠了多少 |
|
||||
| **C 申报**(本方案) | 允许,但写进描述 | 代码照跑;欠据可数、可查 |
|
||||
|
||||
C 的关键:**不改道德要求,改激励**——申报比伪造省力,且申报后代码照样跑。
|
||||
|
||||
---
|
||||
|
||||
## 2. `()` 内部语法定稿
|
||||
|
||||
### 2.1 取元
|
||||
|
||||
| 语义 | 写法 |
|
||||
|------|------|
|
||||
| Map 取成员 | `at(表, 键)` |
|
||||
| List 第 n 项(1-based) | `at(列表, 1)` |
|
||||
| 缺键取默认(不崩) | `get(表, 键, 默认值)` |
|
||||
|
||||
### 2.2 调用
|
||||
|
||||
| 形态 | 写法 |
|
||||
|------|------|
|
||||
| 位置实参 | `加一函数(31)`(逗号可选:`加一函数(31 2)`) |
|
||||
| 具名实参 | `计税(档位=2, 金额=100)` |
|
||||
| **带空格 callee** | `加一 号(31)` → callee = 第一个 `(` 之前的全部文本 |
|
||||
| 库路径 / 方法 | `txt.str_trim(s)` / `obj.方法(x)` |
|
||||
|
||||
实测:`加一 号(31 )` → `32`;`> 加一 号 31` → `unknown function 加一`。
|
||||
**`(` 是明确分隔符**——这是缺陷 D8 的结构性解法。
|
||||
|
||||
### 2.3 循环
|
||||
|
||||
```markdown
|
||||
- [从篮子里取出的每个果子](遍历 篮子 为 果)
|
||||
```
|
||||
|
||||
### 2.4 空载荷:**一律 warning**
|
||||
|
||||
| 写法 | 结果 |
|
||||
|------|------|
|
||||
| `[功能,开发中]()` | ⚠️ `label.empty_payload` |
|
||||
| `[功能,开发中](None)` | ✅ 无警告 |
|
||||
| `[功能,开发中](json.parse text="[]")` | ✅ 无警告 |
|
||||
|
||||
**为什么一律报**:空 `()` 就是"什么都没写"。哪怕桩也该说明返回什么——
|
||||
`None` 也是答案,下游能据此判断。
|
||||
**为什么不会造成存量噪音**:遮蔽语法是新形式,**今天仓库里一处都没有**。
|
||||
|
||||
> 可调旋钮(**非默认**):若实际使用中觉得"已申报的桩也报警"太吵,
|
||||
> 可开启「命中内置词表则降为 hint」。默认关闭——遵守"空载荷必须被看见"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 两级词表
|
||||
|
||||
### 3.1 第一级:内置词表(范式 + 默认检索集)
|
||||
|
||||
**它是什么**:编译器内置的一张**小词表**,用途三个——
|
||||
|
||||
| 用途 | 说明 |
|
||||
|------|------|
|
||||
| **范式** | 给 LLM 一个稳定写法:不知道怎么写状态,就照这个词表写 |
|
||||
| **默认检索集** | `marqdo labels pending` 零配置即可用;跨项目可比 |
|
||||
| **默认豁免集** | 命中这些词的遮蔽默认跳过 stale(见 §6.1) |
|
||||
|
||||
**它不是什么**:**不是语法**。写不写、怎么写都不影响解析与执行。
|
||||
|
||||
### 3.2 内置词表(v1)
|
||||
|
||||
| 组 | 关键词(子串任一命中即算) | 计入 |
|
||||
|----|--------------------------|------|
|
||||
| **未完成** | `待开发` `未开发` `开发中` `未实现` `待实现` `未接` `接口未接` `TODO` | pending |
|
||||
| **假数据** | `模拟` `假数据` `桩` `占位` `stub` `mock` | pending |
|
||||
| **演示** | `示例` `样例` `demo` | demo |
|
||||
| **不稳** | `实验` `试验` `experimental` | experimental |
|
||||
| **将删** | `废弃` `弃用` `deprecated` | deprecated |
|
||||
| **待核** | `待校验` `未验证` `待确认` | unverified |
|
||||
|
||||
- 组间**独立计数**,不合并
|
||||
- `pending` = 未完成 ∪ 假数据(默认口径,最常用)
|
||||
- 词表版本随编译器走;扩词表**不动语法**
|
||||
|
||||
### 3.3 第二级:参数(扩展与覆盖)
|
||||
|
||||
```bash
|
||||
# 默认:内置 pending 集
|
||||
marqdo labels pending
|
||||
|
||||
# 覆盖:只用我给的词
|
||||
marqdo labels search --grep "接口未联调,联调中"
|
||||
|
||||
# 合并:我给的 + 内置
|
||||
marqdo labels search --grep "联调中" --also-builtin
|
||||
```
|
||||
|
||||
| 参数 | 语义 |
|
||||
|------|------|
|
||||
| `--grep A,B` | **替换**为 A、B(子串、OR、英文大小写不敏感) |
|
||||
| `--also-builtin` | 与内置词表**取并集** |
|
||||
| `--group pending,demo` | 用内置的某几组(不带 `--grep` 时) |
|
||||
|
||||
MLSP 对应:
|
||||
|
||||
```json
|
||||
{ "method": "labels.search",
|
||||
"params": { "grep": ["联调中"], "also_builtin": true, "json": true } }
|
||||
```
|
||||
|
||||
### 3.4 为什么保留内置词表
|
||||
|
||||
| 理由 | 说明 |
|
||||
|------|------|
|
||||
| **LLM 有范本** | 模型不必发明措辞,照着写即可,稳定性显著提高 |
|
||||
| **跨项目可比** | 大家用同一套词,"还有多少没做"才有统一含义 |
|
||||
| **零配置可用** | CI 不必先写一份词表才能统计 |
|
||||
| **失败模式可控** | 词不全时用参数补,而不是每个项目各自发明一套 |
|
||||
|
||||
**代价**:内置词表是一种"语义偏见"。缓解方式是**两级**——
|
||||
内置只做默认值,参数永远可覆盖/扩展;且词表不参与语法,写别的措辞完全合法。
|
||||
|
||||
### 3.5 识别规则:纯子串,无位置/分隔符要求
|
||||
|
||||
```rust
|
||||
// 语义示意
|
||||
for (group, words) in TABLE(words_from_params_or_builtin) {
|
||||
if words.iter().any(|w| label_text.contains(w)) { hits.insert(group) }
|
||||
}
|
||||
```
|
||||
|
||||
| 写法 | 命中 |
|
||||
|------|------|
|
||||
| `[某某功能开发中]` | ✅ 无分隔符 |
|
||||
| `[搜索接入,待开发]` | ✅ 逗号 |
|
||||
| `[搜索接入-待开发]` | ✅ 连字符 |
|
||||
| `[【待开发】搜索接入]` | ✅ 括号 |
|
||||
| `[这段还没写完]` | ❌ 无词(合法,不计数) |
|
||||
|
||||
- **识别不到不报错、不提示**——描述自由
|
||||
- **误判必然存在**(`[不属于待开发范围]` 会命中):只影响计数,不影响执行;
|
||||
输出带描述原文,人可判断;否定词窗口留 v1.1 可选
|
||||
|
||||
---
|
||||
|
||||
## 4. 桩的语义
|
||||
|
||||
### 4.1 三条规则
|
||||
|
||||
| # | 规则 | 原因 |
|
||||
|---|------|------|
|
||||
| 1 | **桩必须能跑**(不得报错) | 否则整篇文档被阻断 |
|
||||
| 2 | **桩必须写明返回什么** | 空载荷 → warning;写 `None` 也行,但不能什么都不写 |
|
||||
| 3 | **桩不得被当成已完成** | 描述里申报;检索能查到;`view` 有徽章 |
|
||||
|
||||
### 4.2 桩返回什么
|
||||
|
||||
| 手段 | 写法 |
|
||||
|------|------|
|
||||
| 显式空值 | `[某某功能开发中](None)` |
|
||||
| 常量占位 | `[税率预报,模拟](0.1)` |
|
||||
| 假数据 | `[搜索结果,模拟](json.parse text="[]")` |
|
||||
| **桩 + 契约(推荐)** | 配合返回契约声明类型 → 桩是"有类型的洞" |
|
||||
|
||||
```markdown
|
||||
## 搜索
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | list | 命中列表(当前未接) |
|
||||
|
||||
[按关键词检索,接口未接,模拟](json.parse text="[]")
|
||||
```
|
||||
|
||||
### 4.3 惯例(不强制):桩返回值带 `stub: true`
|
||||
|
||||
```markdown
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 工程化:写进 README,提示词同步更新
|
||||
|
||||
### 5.1 README 增补(`README.md` 新节)
|
||||
|
||||
> **工程习惯:允许申报未完成,但不允许假装完成**
|
||||
>
|
||||
> ```markdown
|
||||
> [按关键词检索,接口未接,待开发](None)
|
||||
> ```
|
||||
>
|
||||
> - 桩必须能跑,并写清返回值(写 `None` 也比空着好)
|
||||
> - 描述是自由文本;内置词表只是推荐用词与默认检索集
|
||||
> - 盘点:`marqdo labels pending`;自定义:`--grep 你的词 --also-builtin`
|
||||
> - 门禁:`--baseline` + `--fail-on-increase`(棘轮:只拦新增,不追旧账)
|
||||
> - LLM:接不了就申报;提示词见 `ext/ai/agent.mq.md`
|
||||
|
||||
### 5.2 提示词更新(`ext/ai/agent.mq.md`)
|
||||
|
||||
| 位置 | 现状 | 增补 |
|
||||
|------|------|------|
|
||||
| `:48` 默认 standing(`You are a Marqdo agent…`) | 只讲"源码是真相" | 追加一句申报约定 |
|
||||
| `:39` how-to-act 协议段 | 只讲 CALL/READ | 追加"未完成必须申报" |
|
||||
|
||||
**建议追加文本**(英文,与现有 standing 一致):
|
||||
|
||||
```text
|
||||
When you cannot truly wire a capability, do not fake it silently and never claim it works.
|
||||
Write it as an occlusion with an explicit status instead:
|
||||
[按关键词检索,接口未接,待开发](None)
|
||||
Stubs must run without error and must state their return value (None is acceptable).
|
||||
Before finishing, check your own declarations with labels.pending.
|
||||
```
|
||||
|
||||
**为什么这条对 LLM 有效**:把"编造"变成"填表"——模型不必判断算不算伪造,
|
||||
只需写出状态词并给一个返回值。
|
||||
|
||||
### 5.3 工具面
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| `labels pending` | 内置词表口径的未完成清单 |
|
||||
| `labels search --grep … [--json/--count/--also-builtin]` | 任意词盘点 |
|
||||
| `labels search … --changed` | 只看本次变更涉及的 |
|
||||
| MLSP `labels.search` | 协议内同上 |
|
||||
|
||||
### 5.4 指标
|
||||
|
||||
| 指标 | 算法 |
|
||||
|------|------|
|
||||
| `pending_count` | `labels pending --count` |
|
||||
| `unlabeled_empty` | `label.empty_payload` warning 数 |
|
||||
| `stub_ratio` | pending / 遮蔽总数 |
|
||||
| `stub_age` | 需 VCS(可选,不进默认路径) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 生命周期
|
||||
|
||||
```
|
||||
① 写桩 [按关键词检索,接口未接,待开发](None)
|
||||
↓
|
||||
② 盘点 labels pending → 列出它
|
||||
↓
|
||||
③ 开发 换成真实 HTTP 调用
|
||||
↓
|
||||
④ 复核 去掉"待开发"字样、改写描述
|
||||
↓
|
||||
⑤ 数字-1 检索结果自动减少
|
||||
```
|
||||
|
||||
### 6.1 stale 豁免(默认用内置集)
|
||||
|
||||
| 情形 | stale 行为 |
|
||||
|------|-----------|
|
||||
| 描述命中**内置 pending 组**(未完成/假数据) | **豁免** |
|
||||
| 命中 `将删`(废弃) | **豁免** |
|
||||
| 命中 `示例` / `实验` / `待核` | 正常报 |
|
||||
| 空载荷 | **豁免**(它就是桩) |
|
||||
| 无命中、有实现 | 正常报 |
|
||||
| `check --stub-words "A,B"` | **覆盖**内置集,用 A,B 判定豁免 |
|
||||
|
||||
理由:桩本来就是"未完成",描述已明说。若桩一被改动就报 stale,
|
||||
12 个桩会变 12 条常驻警告——**正好制造我们要消灭的疲劳**。
|
||||
|
||||
### 6.2 防"做完了忘去掉申报"
|
||||
|
||||
- `labels search --grep … --changed`:本次变更中被改过的桩
|
||||
- 会话末汇总带一行 `pending_touched: 2`(只给数字,不逐条)
|
||||
|
||||
---
|
||||
|
||||
## 7. 与防疲劳机制的协同
|
||||
|
||||
| 机制 | 作用 |
|
||||
|------|------|
|
||||
| 桩豁免 stale(默认内置集) | 12 个桩不会变成 12 条常驻警告 |
|
||||
| 债务用**棘轮**(`--baseline` + `--fail-on-increase`) | 老债不阻塞、新债立刻拦 |
|
||||
| 检索是**按需命令**,不进 `check` 人类输出 | 零噪音 |
|
||||
| 搜不到**不报错** | 描述自由,机器不纠正用词 |
|
||||
| 空载荷 warning 仅作用于新语法 | 不可能产生历史债 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 编译器实现点
|
||||
|
||||
| 位置 | 要做的事 |
|
||||
|------|---------|
|
||||
| `src/parse` | 解析 `[描述](实现)`,**原样保存描述**(不解析、不分类) |
|
||||
| `src/ast.rs` | `Expr::Occluded { label: String, inner: Option<Box<Expr>> }` |
|
||||
| `src/label.rs`(新增) | **内置词表常量** + 描述索引/检索(子串、OR、大小写不敏感)+ L1 引用一致性 + T1 前后对比 |
|
||||
| `src/check.rs` | 三条:`label.missing`(error)、`label.ref_dangling`(error)、`label.empty_payload`(**warning,一律**) |
|
||||
| `src/interp.rs` | 描述**不影响求值**;空载荷 → `None` |
|
||||
| `src/main.rs` | `labels pending/search --grep … [--also-builtin/--json/--count/--changed]`;`check --stub-words …` |
|
||||
| `src/mlsp.rs` | `labels.search`(含 `also_builtin`)、`validate.stub_words`、会话汇总 `pending_touched` |
|
||||
| `src/view/render.rs` | 遮蔽渲染:描述为正文、实现可折叠;桩徽章 |
|
||||
| `README.md` | 新增「工程习惯」一节(§5.1) |
|
||||
| `ext/ai/agent.mq.md` | `:48` standing 与 `:39` 协议段追加申报约定(§5.2) |
|
||||
|
||||
**分层**:内置词表是**数据**(常量表),检索是**纯函数**,语法**零依赖**——
|
||||
扩词表不改语法,改语法不动词表。
|
||||
|
||||
---
|
||||
|
||||
## 9. 示例
|
||||
|
||||
### 9.1 无分隔符申报
|
||||
|
||||
```markdown
|
||||
[某某功能开发中](None)
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo labels pending # 命中(内置「开发中」)
|
||||
```
|
||||
|
||||
### 9.2 假算指标
|
||||
|
||||
```markdown
|
||||
本季度 **[客户留存率,待开发](0.0)**,环比变化 **[留存环比,模拟](0.0)**。
|
||||
```
|
||||
|
||||
### 9.3 假接通外部系统
|
||||
|
||||
```markdown
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
### 9.4 该报 warning 的空载荷
|
||||
|
||||
```markdown
|
||||
[应纳税额]() # ⚠️ label.empty_payload
|
||||
```
|
||||
|
||||
### 9.5 项目自己的说法(参数层)
|
||||
|
||||
```markdown
|
||||
[接口还在联调,先返回空](json.parse text="[]")
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo labels search --grep "联调" --also-builtin # 内置 + 自定义一起数
|
||||
```
|
||||
|
||||
### 9.6 任意措辞(合法、不被自动分类,但可被搜)
|
||||
|
||||
```markdown
|
||||
[这段还没写完](0)
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo labels search --grep 还没写完 # LLM 自己挑的词,照样搜到
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 风险与取舍
|
||||
|
||||
| 风险 | 说明 | 缓解 |
|
||||
|------|------|------|
|
||||
| 子串误判 | `[不属于待开发范围]` 会命中 | 只影响计数;输出带原文;否定词窗口留 v1.1 |
|
||||
| 内置词表是语义偏见 | 规定了"什么算未完成" | **两级**:内置只做默认,参数可覆盖/扩展 |
|
||||
| 空载荷 warning 偏多 | 作者爱留空 | 修法极简(写 `None`);仅影响新语法;可留降级旋钮 |
|
||||
| 桩腐化 | 忘去掉申报 | `--changed` + 会话汇总,不做常驻警告 |
|
||||
| 假功能上生产 | 最坏情况 | `view` 显著标记;CI 可 `--count` 门禁 |
|
||||
| LLM 滥用申报逃避检查 | 把真实现标成待开发 | 申报只增加可见性、不减少检查;豁免 stale 的代价是计入债务 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 已定 vs 待定
|
||||
|
||||
**已定(本文即规范)**
|
||||
|
||||
| 项 | 结论 |
|
||||
|----|------|
|
||||
| 描述性质 | 自由文本,不执行,不参与类型/作用域 |
|
||||
| 词表 | **两级**:内置范例/默认 + 参数扩展 |
|
||||
| 空载荷 | **一律 warning**(写 `None` 消除) |
|
||||
| 检索语义 | 子串 + OR + 英文大小写不敏感 |
|
||||
| stale 豁免 | 默认内置 pending/将删组;`--stub-words` 覆盖 |
|
||||
| 棘轮 | `--baseline` + `--fail-on-increase` |
|
||||
| 工程化落点 | README 一节 + `ext/ai` 提示词两处 |
|
||||
|
||||
**待你点头**
|
||||
|
||||
| # | 问题 | 建议 |
|
||||
|---|------|------|
|
||||
| 1 | 内置词表就 §3.2 这六组 | 是 |
|
||||
| 2 | `pending` = 未完成 ∪ 假数据 | 是 |
|
||||
| 3 | `--grep` 替换、`--also-builtin` 合并 | 是 |
|
||||
| 4 | 空载荷"降级旋钮"先不做 | 是(先按一律 warning 跑一段看噪音) |
|
||||
| 5 | 提示词追加文本按 §5.2 写 | 是 |
|
||||
|
||||
> 点头后即按 M1 → M2 → M4 → M9 → M6 开工;首批金样用 §9 的六个例子。
|
||||
@@ -0,0 +1,624 @@
|
||||
# 遮蔽语法(Occlusion Syntax):`[描述](实现)` 设计与实施总纲
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 实施中**(M0 起,本文档为实施依据) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 决策 | 纯度;标签可省略书写但**编译器报错**;新鲜度校验**不依赖 git**;**会话末做一次性汇总** |
|
||||
| 定位 | 本文把 `[]()` 从「若干语法的集合」重新定义为**一种语法、一个目的:遮蔽** |
|
||||
| 前置 | [bracket-as-label-evaluation.md](bracket-as-label-evaluation.md) · [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) · [staleness-providers.md](staleness-providers.md) · [t1-session-staleness.md](t1-session-staleness.md) |
|
||||
| 增补 | [occlusion-description-and-search.md](occlusion-description-and-search.md) — **两级词表(内置=范例/默认;参数=扩展)**;空载荷一律 warning;桩语义;工程化落点(README + `ext/ai` 提示词);**`()` 内部语法定稿见该文 §2** |
|
||||
|
||||
---
|
||||
|
||||
## 0. 术语(后文一律按此使用)
|
||||
|
||||
| 术语 | 含义 |
|
||||
|------|------|
|
||||
| **遮蔽(occlusion)** | 用一段人话盖住一段实现:读者看人话,机器看实现 |
|
||||
| **描述(label)** | `[]` 里的文本。**不可执行**,只给人读,是可被机器核验的断言 |
|
||||
| **实现(payload)** | `()` 里的表达式。**唯一执行**的部分 |
|
||||
| **显式遮蔽** | `[描述](实现)` —— 描述与实现写在同一处 |
|
||||
| **隐式遮蔽** | 叙述段落 + 紧接的 `>` 调用 —— 描述是上方那段散文 |
|
||||
| **新鲜(fresh)** | 描述与实现仍然相符 |
|
||||
| **过期(stale)** | 实现变了、描述没变 —— 描述可能已不再成立 |
|
||||
|
||||
## 0.1 开发环境前置(实施前必须就绪)
|
||||
|
||||
本机(glibc 2.36、无系统 gcc/go/python3)已验证过的完整环境:
|
||||
|
||||
```bash
|
||||
source scripts/dev-env.sh # rust 1.81 + go 1.25 + python 3.12 + zig(gcc shim, glibc 2.36)
|
||||
./scripts/build-web-plugin.sh # 产出 libweb.so,否则 gold 测试会失败
|
||||
```
|
||||
|
||||
两个非直觉约束(踩过的坑,写进文档免得后人重踩):
|
||||
|
||||
| 约束 | 现象 | 处理 |
|
||||
|------|------|------|
|
||||
| `$HOME` 不可写 | zig 报 `AccessDenied` | `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` 指向工作区 |
|
||||
| **`/tmp` 是 noexec tmpfs** | Go 链接 `signal: aborted`、zig `AccessDenied` | `TMPDIR` 指向可写且**可执行**目录 |
|
||||
|
||||
基线(改动前必须先跑通):`cargo test --release` → **554 passed / 0 failed**;
|
||||
`marqdo check` 对 `lib/` + `ext/ai/`(59 文件)→ **0 warning / 0 error**。
|
||||
任何里程碑都不得让这两个数字变差。
|
||||
|
||||
---
|
||||
|
||||
# Part I · 示例先行
|
||||
|
||||
## 1. 六个示例
|
||||
|
||||
### 1.1 嵌套取值:不可读 → 可读
|
||||
|
||||
**今天**(读者要在三层括号间来回跳):
|
||||
|
||||
```markdown
|
||||
**单价 = [1]([苹果]([水果类](货架)))**
|
||||
```
|
||||
|
||||
**遮蔽之后**:
|
||||
|
||||
```markdown
|
||||
**单价 = [水果类里苹果的第 1 项价格](at(at(at(货架, 水果类), 苹果), 1))**
|
||||
```
|
||||
|
||||
人读方括号,机器读圆括号。**嵌套再深,读者也只看一句人话。**
|
||||
|
||||
### 1.2 长表达式打断叙述
|
||||
|
||||
**今天**:
|
||||
|
||||
```markdown
|
||||
本季度应缴税额为 **金额 * 税率 * (1 - 减免比例) + 附加费**,请注意申报期限。
|
||||
```
|
||||
|
||||
一句话被一串符号劈成两半。
|
||||
|
||||
**遮蔽之后**:
|
||||
|
||||
```markdown
|
||||
本季度应缴税额为 **[应缴税额](金额 * 税率 * (1 - 减免比例) + 附加费)**,请注意申报期限。
|
||||
```
|
||||
|
||||
叙述仍然是句子;复杂算式被折进 `()`。
|
||||
|
||||
### 1.3 抽象层次混杂:把实现藏到读者不需要看的地方
|
||||
|
||||
**今天**(读者被迫读实现细节):
|
||||
|
||||
```markdown
|
||||
价格随会员等级浮动,具体为 **基础价 * 会员折扣[等级](折扣表) * (1 + 旺季系数)**。
|
||||
```
|
||||
|
||||
**遮蔽之后**(论证留在叙述里,算法藏起来):
|
||||
|
||||
```markdown
|
||||
价格随会员等级浮动:**[会员最终价](基础价 * at(折扣表, 等级) * (1 + 旺季系数))**。
|
||||
```
|
||||
|
||||
### 1.4 循环:来源从此可见
|
||||
|
||||
**今天**(渲染成「名为果的链接指向篮子」,看不出是遍历):
|
||||
|
||||
```markdown
|
||||
- [果](篮子)
|
||||
**总重 = 总重 + [重量](果)**
|
||||
```
|
||||
|
||||
**遮蔽之后**:
|
||||
|
||||
```markdown
|
||||
- [从篮子里取出的每个果子](遍历 篮子 为 果)
|
||||
**总重 = 总重 + [重量](at(果, 重量))**
|
||||
```
|
||||
|
||||
「从哪来」写进了人话——**不再依赖读者是否用了 `marqdo view` 才能看懂。**
|
||||
|
||||
### 1.5 带空格的函数名(**已实测验证**)
|
||||
|
||||
**今天**(`>` 调用无法表达,这是缺陷 D8):
|
||||
|
||||
```markdown
|
||||
> 加一 号 31 # ❌ unknown function `加一` —— 空格把名字切断了
|
||||
```
|
||||
|
||||
**遮蔽之后**(`(` 成为明确分隔符,空格不再是切词依据):
|
||||
|
||||
```markdown
|
||||
**结果 = [加一之后的值](加一 号(31))**
|
||||
```
|
||||
|
||||
**实测证据**(1.5.2 原型):
|
||||
|
||||
| 写法 | 结果 |
|
||||
|------|------|
|
||||
| `> 加一 号 31` | ❌ `unknown function 加一` |
|
||||
| `加一 号(31 )`(括号调用) | ✅ **32** |
|
||||
| `问候("世界")` | ✅ `你好 世界` |
|
||||
|
||||
> **因为 `()` 里的 callee 取「第一个 `(` 之前的全部文本」,空格不再有任何歧义。**
|
||||
> 这正是你说的「`()` 内部对带空格的函数名处理方式很多样」——而且它不只是"很多样",
|
||||
> 它是**结构上唯一正确**的处理:用括号做边界,而不是用空白。
|
||||
|
||||
### 1.6 反例:什么时候**不该**遮蔽
|
||||
|
||||
```markdown
|
||||
# 反例:为遮蔽而遮蔽
|
||||
|
||||
**总计 = [总计](a + b)** # ❌ 描述等于代码,白加一层
|
||||
**[价格](price)** # ❌ 描述等于变量名,无信息增量
|
||||
```
|
||||
|
||||
**判据**:如果描述不能比实现**多提供信息**(意图、来源、单位、why),就不要遮蔽。
|
||||
遮蔽的收益是"读者不用读实现",若描述只是把实现读了一遍,收益为零、成本照付。
|
||||
|
||||
---
|
||||
|
||||
## 2. 定义:遮蔽语法
|
||||
|
||||
```markdown
|
||||
[ 描述 ] ( 实现 )
|
||||
└─ 人读 ─┘ └─ 机读 ─┘
|
||||
```
|
||||
|
||||
### 2.1 三条铁律
|
||||
|
||||
| # | 铁律 | 理由 |
|
||||
|---|------|------|
|
||||
| 1 | `[]` **永不执行** | 与「叙述默认安全」一致:只说人话的东西不改变程序行为 |
|
||||
| 2 | `()` **是唯一执行体** | 语义只有一处,读者不必猜两层 |
|
||||
| 3 | **遮蔽必须可校验** | 见 §2.2 |
|
||||
|
||||
### 2.2 核心定理:遮蔽创造信任负债
|
||||
|
||||
> **你把实现藏起来,读者就必须相信描述。**
|
||||
> 所以:**遮蔽 ⇔ 描述成为承重结构 ⇔ 必须可被机器核验。**
|
||||
|
||||
这条定理把「新鲜度校验」从"附加功能"变成"遮蔽的**代价与前提**":
|
||||
|
||||
- 不遮蔽 → 读者能自己核对代码 → 描述过期无伤大雅(顶多是注释旧了)
|
||||
- 遮蔽 → 读者看不见代码 → **描述一旦过期,文档就变成了假的**
|
||||
|
||||
所以平台必须提供:**实现一变,描述立刻被质疑**。
|
||||
这不是锦上添花,是这套语法的**合法性来源**。
|
||||
|
||||
### 2.3 为什么必须是「链接外形」
|
||||
|
||||
| 性质 | 链接(`[]()`) | 其它候选 |
|
||||
|------|--------------|---------|
|
||||
| 文本不可执行、目标可执行 | ✅ 天生分离 | 括号内联(`(...)`)做不到"只读文本" |
|
||||
| 与 Markdown 渲染一致 | ✅ 渲染成超链接,读者熟悉 | 箭头 `→` 是自造符号 |
|
||||
| 可承载任意长文本 | ✅ | 下标 `x[y]` 放不下长描述 |
|
||||
| 可被工具定位/跳转 | ✅ 天然锚点 | 注释块不行 |
|
||||
|
||||
**一句话**:链接是唯一"人类文本与机器目标天然分工"的 Markdown 结构,
|
||||
而 Marqdo 正好需要这个分工。
|
||||
|
||||
---
|
||||
|
||||
# Part II · 应用场景(按**动机**分类,不按语法分类)
|
||||
|
||||
**重要**:遮蔽语法**不是**"循环语法""取元语法""调用语法"。
|
||||
它没有专属用途——它是**一种处理不可读性的手段**。任何表达式都可被遮蔽。
|
||||
|
||||
## 3. 五类遮蔽动机
|
||||
|
||||
| 动机 | 症状 | 遮蔽后得到什么 |
|
||||
|------|------|---------------|
|
||||
| **A 不可读** | 嵌套过深、括号堆叠 | 读者只看一句人话 |
|
||||
| **B 打断叙述** | 长算式把句子劈成两半 | 句子完整,算式退居括号 |
|
||||
| **C 层次混杂** | 论证与实现细节混排 | 论证在上,实现可折叠 |
|
||||
| **D 来源不明** | 看不出数据从哪来(如 `- [果](篮子)`) | 来源写进人话 |
|
||||
| **E 名称受限** | 函数名含空格写不出调用(D8) | `(` 做分隔符,名字自由 |
|
||||
|
||||
> 注意 D 与 E:它们是**遮蔽顺带解决的问题**,不是遮蔽的目的。
|
||||
> 若把它们写成"循环语法 / 调用语法",就会限制这套语法的适用面;
|
||||
> 按动机写,它才能覆盖未来尚未想到的不可读情形。
|
||||
|
||||
## 4. 什么时候不该遮蔽
|
||||
|
||||
| 情形 | 说明 |
|
||||
|------|------|
|
||||
| 描述 = 实现(§1.6) | 无信息增量 |
|
||||
| 只用一次且已足够可读 | 遮蔽会**增加**读者的跳转成本 |
|
||||
| 描述无法具体化 | 笼统的描述不可校验,等于把信任成本转嫁给读者 |
|
||||
| 性能敏感的热路径 | 遮蔽本身不贵,但过度嵌套的表达式不利于后续优化 |
|
||||
|
||||
---
|
||||
|
||||
# Part III · 语法规范
|
||||
|
||||
## 5. 文法
|
||||
|
||||
```
|
||||
遮蔽 ::= '[' 描述 ']' '(' 表达式? ')'
|
||||
描述 ::= 非空自由文本(可含 `实体`、空格、关键词;v1 不跨行)
|
||||
表达式 ::= 现有表达式文法(含 §6 的调用形);**可空** → 值为 None
|
||||
|
||||
带括号的调用 ::= callee '(' 实参列表? ')'
|
||||
callee ::= 非空文本,不含 '('(**允许空格**,见 §6.2)
|
||||
实参列表 ::= 实参 (分隔 实参)*
|
||||
实参 ::= 名 '=' 值 | 值
|
||||
分隔 ::= 空白 | ',' # 逗号可选、容错
|
||||
```
|
||||
|
||||
出现位置:**表达式位置 / 语句位置 / 循环项位置**(三处形态一致)。
|
||||
|
||||
> **空载荷 `()`**:合法(值 `None`),但**一律**报 `label.empty_payload`(warning)——
|
||||
> 修法是显式写 `None` 或一个真实返回值。描述是自由文本,检索由**调用方传词**(子串匹配,无分隔符要求),
|
||||
> 详见 [occlusion-description-and-search.md](occlusion-description-and-search.md) §3–§4。
|
||||
|
||||
## 6. `()` 之内
|
||||
|
||||
### 6.1 表达式文法不变
|
||||
|
||||
`()` 里就是今天 Marqdo 的表达式:算术、比较、调用、变量(`` `名` ``)、字面量。
|
||||
**不引入第二套表达式语言。**
|
||||
|
||||
### 6.2 callee 可以含空格(解决 D8)
|
||||
|
||||
规则:**callee = 第一个 `(` 之前的全部文本**(去首尾空白)。
|
||||
|
||||
```markdown
|
||||
[加一之后的值](加一 号(31)) # callee = "加一 号"
|
||||
[会员最终价](会员价(等级=2 )) # 具名实参
|
||||
```
|
||||
|
||||
依据实测:`加一 号(31 )` → `32`。
|
||||
(当前实现的参数分词器会把 `)` 吞进末个实参,需要 M1 修掉;带尾随空格即可绕过。)
|
||||
|
||||
### 6.3 取元怎么写(纯度要求)
|
||||
|
||||
`[键](集合)` **不再是取元**(见 §9 迁移)。取元改为函数形:
|
||||
|
||||
| 语义 | 写法 |
|
||||
|------|------|
|
||||
| 取 Map 成员 | `at(表, 键)` 或 `get(表, 键)` |
|
||||
| 取 List 第 n 项(1-based) | `at(列表, 1)` |
|
||||
| 缺键不崩 | `get(表, 键, 默认值)` |
|
||||
|
||||
**理由**:与调用同一外形,读者不必区分"这是取元还是调用"——
|
||||
而这正是遮蔽语法要消灭的那种"两套读法"。
|
||||
|
||||
### 6.4 循环
|
||||
|
||||
```markdown
|
||||
- [从篮子里取出的每个果子](遍历 篮子 为 果)
|
||||
```
|
||||
|
||||
- `[]` = 人读描述(来源、单位都可写)
|
||||
- `()` = `遍历 <集合> 为 <变量>`
|
||||
- **变量名从 `[]` 搬进 `()`**:`[]` 不再兼任标识符(否则"描述"与"名字"又打架)
|
||||
|
||||
## 7. 标签规则
|
||||
|
||||
| 规则 | 行为 |
|
||||
|------|------|
|
||||
| 空标签 `[](…)` | **error `label.missing`**(你说的"可省略书写但编译器报错") |
|
||||
| 标签内 `` `实体` `` | 视为**断言**:该实体必须可解析且出现在 `()` 中(§10.1) |
|
||||
| 标签含空格、中文、标点 | 允许 |
|
||||
| 标签含 `]` | 不允许(转义规则见 §11.3) |
|
||||
| 标签跨行 | v1 不支持(跨行标签会让定位困难) |
|
||||
|
||||
## 8. 与既有语法的关系
|
||||
|
||||
| 现有 | 归位 |
|
||||
|------|------|
|
||||
| `> 调用` | **保留**,作为"短形调用";同时纳入隐式遮蔽检查(§10.2) |
|
||||
| `[callee] args` | **保留**为消歧/前置修饰形;仓库实测可执行使用量为 **0**(189 处是 `lib/*` 的 `Caller:` 说明行,不执行) |
|
||||
| `[键](集合)` | **废止**(改为 `at/get`;复用 `[]()` 外形)→ 需版本门 |
|
||||
| `- [项](集合)` | **废止**(改为 `- [描述](遍历 …)`)→ 需版本门 |
|
||||
| `*…*` 返回 | 不变 |
|
||||
|
||||
## 9. 迁移(实测规模)
|
||||
|
||||
| 受影响 | 数量 | 文件 |
|
||||
|--------|------|------|
|
||||
| `[键](集合)` 取元 | **506 处** | 136 |
|
||||
| `- [项](集合)` 循环 | **44 处** | 24 |
|
||||
| 可执行方括号调用 | **0** | — |
|
||||
| `Caller:` 说明行(不执行,无需迁移) | 189 | — |
|
||||
|
||||
**危险点:同形换义。** 迁移后 `[键](集合)` 会变成"遮蔽整个集合",语义静默改变。
|
||||
因此必须:
|
||||
|
||||
1. **硬报错**:purity 模式下遇到旧形 → `syntax.legacy_index`,附迁移示例
|
||||
2. **机械迁移工具**:`marqdo migrate labels --write`
|
||||
3. **临时标签**:工具生成的标签 = 原键名,并标记为 `label.provisional`(**hint**,不报 error)
|
||||
—— 不能让 506 处都变成红错,否则没人能开工
|
||||
|
||||
## 10. 错误信息规范
|
||||
|
||||
| code | 级别 | 触发 | 建议文案 |
|
||||
|------|------|------|---------|
|
||||
| `label.missing` | error | `[](…)` | 「给这段实现写一句人话,或改用不带遮蔽的写法」 |
|
||||
| `label.ref_dangling` | error | 标签引用的实体不存在 | 「`X` 已不存在;改成 `Y` 或删掉该引用」 |
|
||||
| `label.stale` | hint/warning | 实现变了、标签没变 | 「标签说 A,实现现在是 B;二者之一需改」 |
|
||||
| `label.provisional` | hint | 标签 = 原键名 | 「建议把键名改写成读者能懂的一句话」 |
|
||||
| `syntax.legacy_index` | error | 旧 `[键](集合)` | 「取元请写 `at(集合, 键)`;遮蔽请写 `[描述](at(集合, 键))`」 |
|
||||
|
||||
---
|
||||
|
||||
# Part IV · 新鲜度校验
|
||||
|
||||
## 11. 两种遮蔽关系
|
||||
|
||||
| 类型 | 形态 | 描述在哪 |
|
||||
|------|------|---------|
|
||||
| **显式遮蔽** | `[描述](实现)` | `[]` 里 |
|
||||
| **隐式遮蔽** | 叙述段落 + 紧接 `> 调用` | 上方那一段散文 |
|
||||
|
||||
**两者都要查**——这是你明确要求的:"`>` 这种函数调用其实也应该被检查是否存在过期现象"。
|
||||
|
||||
### 11.1 L1:引用一致性(零依赖、确定性)
|
||||
|
||||
**规则**:断言 = 标签内的 `` `实体` ``。
|
||||
|
||||
1. 实体必须可解析(当前作用域/模块存在)
|
||||
2. 实体必须出现在 `()` 的实际内容中(或经调用链可达)
|
||||
|
||||
不满足 → `label.ref_dangling`(error)。
|
||||
|
||||
**为什么低假阳性**:只有**显式反引号**才算断言;纯口语不参与判定。
|
||||
**为什么能落地**:复用 Marqdo 已有的 `` `名` `` = 实体约定,**零新记号**。
|
||||
|
||||
### 11.2 隐式遮蔽:`>` 调用的描述从哪来
|
||||
|
||||
**规则**:取 `>` 行**上方紧邻的叙述段落**(连续非空行,遇空行/标题/代码行即止)作为描述。
|
||||
|
||||
```markdown
|
||||
按 `税率` 与 `档位` 计算应缴税额:
|
||||
|
||||
> 计税 档位=2 金额=100
|
||||
```
|
||||
|
||||
检查:
|
||||
- 段落里 `` `税率` ``、`` `档位` `` 必须**出现在调用实参或 callee 中**,或可解析
|
||||
- 若无叙述段 / 叙述里无反引号 → **不检查**(沉默,零噪音)
|
||||
|
||||
**这条规则的价值**:让**存量代码**(今天所有 `>` 调用)**无需改写**就获得新鲜度保护
|
||||
——只要作者在调用上方写了一句带反引号的说明。
|
||||
|
||||
### 11.3 转义
|
||||
|
||||
| 需求 | 写法 |
|
||||
|------|------|
|
||||
| 标签里要写 `]` | `\]` |
|
||||
| 标签里要写 `` ` ``(字面) | `` \` `` |
|
||||
| 实现里要写 `)` | 由括号配对规则处理(字符串内 `)` 不算) |
|
||||
|
||||
### 11.4 T1:会话内检测(不依赖 git)
|
||||
|
||||
**机制**:`repair_apply` 内部同时持有 before(`source`)与 after(`new_source`),
|
||||
解析两版,比较每个标签的 `()` 指纹:
|
||||
|
||||
> `stale ⟺ 标签文本未变 ∧ () 指纹变了`
|
||||
|
||||
- 按**标签文本**配对(不按行号)→ 移动代码不误报
|
||||
- 标签文本变了 → 视为作者在更新描述,**不报**
|
||||
- 新增/删除标签 → 不报
|
||||
- 指纹只需**进程内一致**(`Expr` 现为 `Debug`,可用 `format!("{:?}")`;或补 `derive(PartialEq)`)
|
||||
|
||||
**为什么这能消灭疲劳**:作用域 = 模型自己的 diff;投递 = 一次;自包含(下轮不重复)。
|
||||
|
||||
### 11.5 会话末一次性汇总(**你要求要做**)
|
||||
|
||||
T1 刻意"不重复",因此需要**闭合**:
|
||||
|
||||
- **会话**定义:MLSP 一条连接的生命周期;CLI 为一次 `marqdo check` 运行
|
||||
- 会话结束时输出**一次**:
|
||||
|
||||
```json
|
||||
{ "session": { "labels_stale_seen": 3, "labels_fixed": 1, "labels_outstanding": 2,
|
||||
"items": ["按 `税率` 计算总价", "篮子里的果子"] } }
|
||||
```
|
||||
|
||||
- 只报**数字 + 标签文本**,不重复诊断详情(详情已在各轮给过)
|
||||
- 若 `outstanding > 0`,可用 `"block"` 模式让客户端不得直接结束任务
|
||||
|
||||
### 11.6 能力自述与降级
|
||||
|
||||
| 环境 | 可用层 | 行为 |
|
||||
|------|--------|------|
|
||||
| CLI + VCS | L1 + T1 + T2 | 可跨会话 |
|
||||
| CLI 无 VCS | L1 + T1 | 仅会话内 |
|
||||
| agent 沙箱(`exec=false`) | L1 + T1 | **不调 git** |
|
||||
| 浏览器 WASM | L1 + T1 | 无持久状态 |
|
||||
| 单文件 / zip | L1 + T1 | — |
|
||||
|
||||
**`labels status` 必须显示当前启用了哪几层**,避免"没报 = 没问题"的误判。
|
||||
|
||||
---
|
||||
|
||||
# Part V · 实施计划
|
||||
|
||||
## 12. 里程碑总览
|
||||
|
||||
| M | 名称 | 产出 | 依赖 | 风险 |
|
||||
|---|------|------|------|------|
|
||||
## 13.1 实施进度
|
||||
|
||||
**全部完成**:M0 · M1 · M2 · M2.5 · M3 · M4 · M5 · M6 · M7 · M8 · M9 · M10
|
||||
(每步含变更文档与测试;全量 605 passed / 0 failed;0 编译警告)。
|
||||
|
||||
| 里程碑 | 变更文档 |
|
||||
|--------|---------|
|
||||
| M1 | [change-m1-paren-call.md](change-m1-paren-call.md) |
|
||||
| M2 | [change-m2-occlusion.md](change-m2-occlusion.md) |
|
||||
| M2.5 | [change-m25-label-diagnostics.md](change-m25-label-diagnostics.md) |
|
||||
| M3 | [change-m3-access-and-loop.md](change-m3-access-and-loop.md) |
|
||||
| M4 | [change-m4-label-refs.md](change-m4-label-refs.md) |
|
||||
| M5 | [change-m5-implicit-occlusion.md](change-m5-implicit-occlusion.md) |
|
||||
| M6 | [change-m6-t1-session.md](change-m6-t1-session.md) |
|
||||
| M7 | [change-m7-migration.md](change-m7-migration.md) |
|
||||
| M8 | [change-m8-ratchet.md](change-m8-ratchet.md) |
|
||||
| M9 | [change-m9-label-search.md](change-m9-label-search.md) |
|
||||
| M10 | [change-m10-engineering-habits.md](change-m10-engineering-habits.md) |
|
||||
|
||||
| **M0** | 语义冻结 | 本文档 Accepted + 术语表进 `doc/design/` | — | 无 |
|
||||
| **M1** | `()` 内调用增强 | `callee(args)`:`)` 终止、逗号、嵌套、**空格 callee** | M0 | 中(分词器共享) |
|
||||
| **M2** | 遮蔽语法 | `[描述](表达式)` + 标签节点 + `label.missing` | M1 | 中 |
|
||||
| **M3** | 普通取元与循环 | `at/get` 落地;`- [描述](遍历 …)` | M2 | 中 |
|
||||
| **M4** | L1 引用一致性 | `label.ref_dangling`(error) | M2 | 低 |
|
||||
| **M5** | 隐式遮蔽检查 | `>` 上方叙述 vs 实参 | M4 | 低 |
|
||||
| **M6** | T1 + 会话汇总 | `repair_apply.check_labels` + 汇总 | M2 | 低 |
|
||||
| **M7** | 迁移与版本门 | `marqdo migrate labels`、`syntax.legacy_index` | M3 | **高** |
|
||||
| **M8** | 呈现与门禁 | `view` 徽章、`labels status/review`、CI | M4–M6 | 低 |
|
||||
| **M9** | 描述检索与桩 | **两级词表**:`labels pending`(内置集)+ `labels search --grep … [--also-builtin]`、MLSP `labels.search`、空载荷 warning | M2 | 低 |
|
||||
| **M10** | 工程化落点 | `README.md` 工程习惯一节 + `ext/ai/agent.mq.md` 提示词(standing 与 how-to-act)追加申报约定 | M9 | 低 |
|
||||
|
||||
**顺序建议**:M0 → M1 → M2 → (M2.5 空载荷/描述) → M4 → **M9** → **M10** → M6 → M5 → M3 → M7 → M8
|
||||
|
||||
理由:**先把"断言 + 复核 + 修复回路"跑通(M2/M4/M6),再动 506 处迁移(M7)**。
|
||||
迁移一旦开始,中间态很痛;而 L1/T1 在旧语法上就能验证。
|
||||
|
||||
---
|
||||
|
||||
## 13. 每个里程碑的详细步骤
|
||||
|
||||
### M0 · 语义冻结
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 改动 | 本文档标记 `Accepted`;`doc/README.md` 登记 |
|
||||
| 要点 | 术语表(§0)作为唯一用词标准;`[]()` 一律称"遮蔽",不称"循环/取元/调用语法" |
|
||||
| 验收 | 团队评审通过;后续文档一律引用本文术语 |
|
||||
|
||||
### M1 · `()` 内调用增强
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `callee(args)` 可用:`)` 作实参终止、可选逗号、嵌套调用、**callee 允许空格** |
|
||||
| 改动文件 | `src/parse/expr.rs`(`parse_call_args` / `split_first_token` / `find_next_arg_boundary` / 新增 `try_paren_call`)、`src/parse/mod.rs`(`looks_like_paren_call` 接入两处调用判定) |
|
||||
| 关键点 | ① `)` 必须是实参终止符(今天会吞进末个实参)② 逗号可容错剥离 ③ 嵌套 `f(g(1))` 需括号深度 ④ `callee = 第一个 '(' 前全部文本`(空格合法) |
|
||||
| 测试 | 新增金样 `tests/structure/paren-call.mq.md`:单参/多参/具名/字符串/嵌套/空格名/库路径/方法 |
|
||||
| 验收 | 上述金样全绿;`cargo test --release` **554 全绿不减**;**双后端**(tree + `--backend bytecode`)均通过 |
|
||||
| 回滚 | 独立提交,可单独 revert(不改既有语义,风险低) |
|
||||
|
||||
### M2 · 遮蔽语法
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `[描述](表达式)` 解析为 `Expr::Occluded { label, inner }` |
|
||||
| 改动文件 | `src/ast.rs`(新增节点 + `PartialEq`)、`src/parse/mod.rs`(表达式/语句/循环三处入口)、`src/interp.rs`(求值时透明传递 inner)、`src/bytecode/compile.rs`+`vm.rs`(编译为 inner,label 只留在调试信息) |
|
||||
| 关键点 | ① 遮蔽对语义**完全透明**(`[d](e)` 的值 = `e` 的值)② label 必须存进 AST(供 L1/T1/诊断定位)③ 空 label → `label.missing` |
|
||||
| 测试 | 金样:三处位置各一例;label 含中文/空格/标点;`label.missing` 反例 |
|
||||
| 验收 | 双后端一致;554 全绿;`marqdo check` 对空标签报 error |
|
||||
| 回滚 | 独立提交;新语法是增量的 |
|
||||
|
||||
### M3 · 普通取元与循环
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `at(表, 键)` / `get(表, 键, 默认)` 可用;`- [描述](遍历 集合 为 变量)` 可用 |
|
||||
| 改动文件 | `src/interp.rs`(`at`/`get` 内建或库函数)、`src/parse/mod.rs`(循环新形)、`lib/table.mq.md`(`get` 带默认值) |
|
||||
| 关键点 | 1-based 与现有 `at value= index=` 保持一致;`get` 缺键返回默认而非崩(修 D5 的痛点) |
|
||||
| 测试 | 金样:Map 取元、List 下标、缺键默认、循环 |
|
||||
| 验收 | 双后端一致;554 全绿 |
|
||||
|
||||
### M4 · L1 引用一致性
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | 标签内 `` `实体` `` 校验:可解析 + 出现在 `()` |
|
||||
| 改动文件 | **新增 `src/label.rs`**(标签模型、引用抽取、校验)、`src/check.rs`(接入)、`src/diagnostics.rs`(复用 `doc_anchor`/`doc_quote`,新增 `label_ref`) |
|
||||
| 关键点 | ① 只认反引号(不猜中文词)→ 低假阳性 ② `doc_anchor` = 标签 span,`doc_quote` = 标签原文 ③ `code` 字段用 `label.ref_dangling` |
|
||||
| 测试 | 单元:抽取/解析/缺失;金样:悬空引用的 error、正常引用的通过 |
|
||||
| 验收 | 554 全绿;对现有仓库跑 `check` 仍为 **0 error**(除非真有悬空) |
|
||||
|
||||
### M5 · 隐式遮蔽(`>` 上方叙述)
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `>` 调用的描述 = 上方紧邻叙述段;其反引号实体须出现在实参/callee |
|
||||
| 改动文件 | `src/label.rs`(段落归属规则)、`src/check.rs` |
|
||||
| 关键点 | ① 段落边界:空行/标题/代码行即止 ② 无反引号则跳过(零噪音) ③ 默认级别 **hint** |
|
||||
| 测试 | 金样:三种(有实体且匹配 / 有实体不匹配 / 无叙述) |
|
||||
| 验收 | 554 全绿;现有仓库不因该规则新增 error |
|
||||
|
||||
### M6 · T1 + 会话汇总
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `repair_apply` 支持 `check_labels`;会话末输出一次性汇总 |
|
||||
| 改动文件 | `src/mlsp.rs`(`repair_apply` 内比 before/after;新增 `session.summary` 方法或响应字段)、`src/label.rs`(标签配对与指纹) |
|
||||
| 关键点 | ① 按标签文本配对 ② 标签变则不报 ③ 指纹进程内一致即可 ④ 会话状态按**连接**保存 |
|
||||
| 测试 | 集成:`repair_apply` 改 `()` 不改 `[]` → 返回 stale;改 `[]` → 不返回;会话末汇总数字正确 |
|
||||
| 验收 | 双后端;554 全绿;**无 VCS 环境下同样工作**(CI 里用临时目录验证) |
|
||||
|
||||
### M7 · 迁移与版本门
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `[键](集合)` / `- [项](集合)` 在 purity 模式下**硬报错**;提供机械迁移 |
|
||||
| 改动文件 | `src/parse/expr.rs`(`link_index_shape_ahead` 改为报 `syntax.legacy_index`)、**新增 `src/migrate.rs`** + `src/main.rs` 子命令 `marqdo migrate labels` |
|
||||
| 关键点 | ① 报错文案必须给"改成什么" ② 迁移生成 `[键](at(集合, 键))`,标 `label.provisional` ③ 一次性完成 506+44 处,避免中间态 ④ 迁移后必须跑全量回归 + 逐文件抽样 `run` |
|
||||
| 测试 | 迁移前快照→迁移→回归对比;抽样 20 个文件 `run` 输出一致 |
|
||||
| 验收 | 554 全绿;`marqdo check` 全仓 0 error;抽样输出无变化 |
|
||||
| 回滚 | **必须整批回滚**(中间态不可用),建议单独分支 |
|
||||
|
||||
### M8 · 呈现与门禁
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 目标 | `view` 显示遮蔽徽章与新鲜度;`labels status/review/confirm`;CI 可 gate |
|
||||
| 改动文件 | `src/view/render.rs`(遮蔽渲染:显示 label,折叠 payload)、`src/main.rs`(`labels` 子命令)、`scripts/ci-*.sh` |
|
||||
| 关键点 | ① `view` 里 label 是正文、payload 可折叠(这正是遮蔽的呈现价值) ② `labels status` 报能力层级与债务数字 |
|
||||
| 验收 | 渲染截图人工评审;`labels status` 在无 VCS 环境正确降级 |
|
||||
|
||||
---
|
||||
|
||||
## 14. 测试计划(贯穿全部里程碑)
|
||||
|
||||
| 层 | 内容 | 门禁 |
|
||||
|----|------|------|
|
||||
| 单元 | 解析/求值/标签抽取/指纹比较 | `cargo test --lib` 全绿 |
|
||||
| 金样 | 新增 `tests/structure/occlusion*.mq.md`、`paren-call*.mq.md` | `tests/gold.rs` 全绿 |
|
||||
| 回归 | 全量 `554`(现基线) | 不得减少 |
|
||||
| 双后端 | tree 与 `--backend bytecode` 各跑一遍 | 结论一致 |
|
||||
| 差异 | 迁移前后同文件 `run` 输出逐字节相同 | 抽样 ≥20 文件 |
|
||||
| 反向 | 故意破坏断言/标签,确认能报 | 每条规则至少一个反例 |
|
||||
| 环境 | 无 git / 沙箱(`exec=false`)/ WASM 构建 | 不崩、不报依赖错 |
|
||||
| 性能 | 1000 标签文件的 `check` 耗时 | 不劣化 >10% |
|
||||
|
||||
**反向验证是硬要求**:每个新检查必须证明"它真的会响",
|
||||
否则就是在写永不触发的代码(本项目已多次遇到"静默通过"的缺陷)。
|
||||
|
||||
---
|
||||
|
||||
## 15. 风险登记
|
||||
|
||||
| 风险 | 概率 | 影响 | 缓解 |
|
||||
|------|------|------|------|
|
||||
| M1 分词器改动波及所有调用 | 中 | 高 | 独立提交 + 554 回归 + 双后端 |
|
||||
| M7 迁移中间态不可用 | 高 | 高 | 整批迁移、单独分支、可整批回滚 |
|
||||
| 遮蔽被滥用(描述=实现) | 高 | 中 | `label.provisional` hint + §1.6 反例进教程 |
|
||||
| 标签自然语言无法核验 | 必然 | 中 | 只认反引号断言(可证伪才检查) |
|
||||
| 误报疲劳 | 中 | **高** | T1 变更驱动 + hint 默认 + 会话末汇总 |
|
||||
| 旧语法语义静默改变 | 中 | **高** | `syntax.legacy_index` 硬报错 |
|
||||
| `Expr` 无 `PartialEq` | 确定 | 低 | 先用 `Debug`;或补 derive |
|
||||
|
||||
---
|
||||
|
||||
# Part VI · 待决策
|
||||
|
||||
| # | 问题 | 建议 |
|
||||
|---|------|------|
|
||||
| 1 | 取元函数名用 `at` 还是 `get`(两者都留?) | 都留:`at` 严格、`get` 带默认 |
|
||||
| 2 | 实参分隔用逗号还是空白 | 两者都接受(逗号可选、容错) |
|
||||
| 3 | 循环新形用 `遍历 集合 为 变量` 还是别的 | 先用它,后续可加别名 |
|
||||
| 4 | `label.stale` 默认级别 | **hint**(会话末汇总再提) |
|
||||
| 5 | M7 迁移是否在本文档同批做 | **否**:M2/M4/M6 先上线并验证,再动迁移 |
|
||||
| 6 | 临时标签(`label.provisional`)是否接受 | **接受**,否则 506 处无法开工 |
|
||||
| 7 | 标签是否允许跨行 | v1 不允许 |
|
||||
| 8 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 |
|
||||
|
||||
---
|
||||
|
||||
## 附:一句话总结
|
||||
|
||||
> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。**
|
||||
> 它用链接的天然分工(人话 / 目标)实现这一点,
|
||||
> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制——
|
||||
> 而 `>` 调用同样在负债之列。
|
||||
+28
-7
@@ -143,13 +143,18 @@ Marqdo 对齐的判断是:
|
||||
|
||||
| `type` | 状态 | 含义 | 主要生产者 |
|
||||
|--------|------|------|------------|
|
||||
| `Marqdo Catalog` | **v0 已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
|
||||
| `Marqdo Module` | **v0 已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
|
||||
| `Marqdo Task` | **规范已定;实现待做** | 一项可匹配的任务意图 | `plan` 晋升 |
|
||||
| `Marqdo Agent Skill` | **规范已定;实现待做** | 指向可执行工作簿的技能 | `plan` 晋升 |
|
||||
| `Marqdo Catalog` | **已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
|
||||
| `Marqdo Module` | **已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
|
||||
| `Marqdo Task` | **已实现** | 一项可匹配的任务意图 | `plan` 晋升 |
|
||||
| `Marqdo Agent Skill` | **已实现** | 指向可执行工作簿的技能 | `plan` 晋升 |
|
||||
| `Capability` / `Function` | **EKC** | 工程能力 / 符号投影 | `marqdo knowledge` |
|
||||
| `Decision` / `Constraint` / `Failure` / `AntiPattern` / `Pattern` / `Migration` / `Fact` | **EKC** | L4 工程知识 | 源 frontmatter + learn |
|
||||
| `Marqdo Context Pack` | **EKC** | Agent EFI 上下文制品 | `reuse` / `preflight` |
|
||||
| `Marqdo Policy` | **EKC** | 复用决议编译 | `marqdo reuse` |
|
||||
| `Marqdo Engineering Knowledge` | **EKC** | 工程知识总览 | `engineering.yaml` / `index.mq.md` |
|
||||
| 其他 | 开放 | 第三方/未来扩展 | — |
|
||||
|
||||
**不**引入 Google OKF 的 `Metric` / BigQuery 表类型作为 Marqdo 核心词汇;需要时可由用户包自行使用,运行时降级。
|
||||
完整 EKC 规范见 [engineering-knowledge.md](engineering-knowledge.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -309,10 +314,15 @@ type: Marqdo Agent Skill
|
||||
title: <短名>
|
||||
sig: <12hex>
|
||||
resource: ../../resources/<slug>.mq.md
|
||||
status: stable | candidate
|
||||
status: stable | candidate | quarantine
|
||||
llm_free: true | false
|
||||
quality: <int>
|
||||
hits: <int>
|
||||
# O2 optional metadata (from workbook frontmatter; see §7.5):
|
||||
applies_when: <text condition or tag>
|
||||
fixtures: <relative .mq.md proof path>
|
||||
sandbox_profile: default | readonly | <name>
|
||||
proof: <relative .mq.md> # alias of fixtures for sandbox gate
|
||||
generated:
|
||||
by: marqdo-agent/plan
|
||||
at: <ISO8601>
|
||||
@@ -326,7 +336,7 @@ verified:
|
||||
Prefer spawning `resource` over re-planning.
|
||||
```
|
||||
|
||||
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。
|
||||
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。**O2:** `agent_kb_promote` 默认要求 sandbox proof(`proof` / `fixtures` / workbook 本身经 `sandbox.run` 成功)才写入;失败返回 `promoted: false` / `reason: sandbox_proof_failed`。传 `require_proof=false` 仅用于明确豁免。
|
||||
|
||||
### 7.3 任务签名 → Concept 路径
|
||||
|
||||
@@ -396,6 +406,17 @@ Prefer spawning `resource` over re-planning.
|
||||
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
|
||||
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
|
||||
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
|
||||
| **证明晋升(O2)** | `applies_when` / `fixtures` / `sandbox_profile` / `proof` 写在技能与 workbook frontmatter;promote 前 `sandbox.run` 绿才 `llm_free` |
|
||||
| **隔离(O5)** | 失败技能 `status: quarantine`;回归 fixture 跟随 slug |
|
||||
|
||||
### 7.5a 技能 frontmatter 约定(O2 B1)
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `applies_when` | 适用条件(短文本 / 标签);路由与 harness 可读 |
|
||||
| `fixtures` | 相对路径:sandbox 证明用 `.mq.md` |
|
||||
| `sandbox_profile` | `default` / `readonly` / 其它 `sandbox.profile` 名 |
|
||||
| `proof` | 与 `fixtures` 同义;promote 优先读 `proof` 再 `fixtures`,否则跑 workbook 自身 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,231 @@
|
||||
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
|
||||
|
||||
> **2026-10-23 审阅裁决**:“原型回退”仅描述当时实验,当前 payload 已支持 `f(args)` 和具名实参。旧 Classic 索引冲突不再决定默认语法;保留熟悉的调用形态与文档原生描述并不矛盾。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),不要把本文备选形式当作已批准的新语法。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「`[函数名](参数1 参数2)` 这种写法有没有可能成立;调用能否更符合人读习惯」 |
|
||||
| 更正 | 本文替代前两轮对用户意图的误读(前两轮在讨论「表 / 函数即值」,不是调用语法) |
|
||||
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [function-as-table-semantics.md](function-as-table-semantics.md) · [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论
|
||||
|
||||
| 问题 | 答案 |
|
||||
|------|------|
|
||||
| `[函数名](参数1 参数2)` 能否成立 | **技术上能,但代价在方括号**:它撞的是取元 `[键](集合)`,而命名空间里确有 2 个真实文件以函数名作键,任何「按名字消歧」都会静默改语义 |
|
||||
| 更人读的调用能否成立 | **能,而且更干净**:`函数名(参数1 参数2)`(**不带方括号**)目前是**完全空闲的语法**,原型实测全量 **554 passed / 0 failed**,零回归 |
|
||||
|
||||
一句话:**想要「参数进括号」这个美感,不需要方括号——去掉方括号反而没有任何冲突。**
|
||||
|
||||
```markdown
|
||||
**税率 = 查询税率(档位=2)** # 具名,读起来像函数调用
|
||||
**合计 = 加(1 2)** # 位置,读起来像数学
|
||||
**名 = txt.str_trim(" x ")** # 库函数同样适用(原型已验证)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状:今天的调用写法盘点(全部实测)
|
||||
|
||||
| 写法 | 位置 | 实测 |
|
||||
|------|------|------|
|
||||
| `> 加 1 2` | 语句 | ✅ 位置参数 |
|
||||
| `> 加 a=1 b=2` | 语句 | ✅ 具名参数 |
|
||||
| `[加] 1 2` | 语句 | ✅ 方括号标记 + 位置参数(用于消歧/前置修饰) |
|
||||
| `**r = > [加] 1 2**` | 粗体赋值 | ✅ 返回 3(方括号调用**已支持空格参数**) |
|
||||
| `**r = 加 1 2**` | 粗体赋值 | ✅ **不带 `>` 也能调用,已可用**(打印 3) |
|
||||
| `**r = > 加 a=1**` | 粗体赋值 | ✅ 显式 `>` 形态 |
|
||||
| `**r = 加(1)**` | 粗体赋值 | ❌ `trailing input in expression: "(1)"` |
|
||||
| `**r = [加](1 2)**` | 粗体赋值 | ❌ `unknown function `[加](1`` |
|
||||
| `> [加](1 2)` | 语句 | ❌ `unknown function `[加](1`` |
|
||||
|
||||
也就是说:**「参数放在括号里」这件事今天完全不存在**。
|
||||
|
||||
---
|
||||
|
||||
## 2. `[函数名](参数)` 为什么碰壁
|
||||
|
||||
### 2.1 方括号 + 圆括号 = 取元,这是**已定的语义**
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §1 写的是心智模型:
|
||||
|
||||
> **方括号 = 取出的名字,圆括号 = 从哪取。**
|
||||
|
||||
```markdown
|
||||
**价 = [拿铁](菜单)** # 从菜单里取出「拿铁」
|
||||
```
|
||||
|
||||
[call-arguments.md](call-arguments.md) §2 进一步锁定:
|
||||
|
||||
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
|
||||
|
||||
所以 `[f](x)` 不是「还没被用的语法」,而是**已经被取元占用**。
|
||||
|
||||
### 2.2 靠「名字是函数还是键」消歧,会真的打断现有代码
|
||||
|
||||
这是本轮新增的硬证据。我把全仓库扫了一遍:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| `.mq.md` 文件 | 851 |
|
||||
| `##` 级函数名 | 2367 |
|
||||
| `[键](…)` 出现次数 | 983 |
|
||||
| **键名与同文件函数名相同的冲突** | **5(去重后 2 个真实文件)** |
|
||||
|
||||
两个真实冲突(不是构造出来的):
|
||||
|
||||
```
|
||||
ext/data/db.mq.md:122 *[count](r)* # 函数名 ## count,同时 r 里有 count 列
|
||||
examples/code-as-docs/index.mq.md:79 价=[单价](行) # 函数名 ## 单价,同时 行 里有 单价 字段
|
||||
```
|
||||
|
||||
**这说明任何「函数名优先」的规则都会改变这两处的行为**:它们本意是取元,却会被解释成调用。
|
||||
反过来「数据优先」则永远无法用 `[f](1)` 调用。**两条路都走不通**——这不是实现难度问题,
|
||||
而是同一外形承载两种语义的固有代价。
|
||||
|
||||
### 2.3 但有一个「无歧义子集」确实存在
|
||||
|
||||
`[f](1 2)` 与 `[f](a=1)` 里的括号内容**不是合法表达式**(实测 `x=1` 报
|
||||
`unknown function`、`1 2` 报 `unknown function`),所以理论上可判为参数列表:
|
||||
|
||||
| 括号内容 | 能否是取元 | 可否判为调用 |
|
||||
|---------|-----------|-------------|
|
||||
| `(1 2)` 多 token | 否(非单一表达式) | ✅ 无歧义 |
|
||||
| `(a=1)` 具名 | 否 | ✅ 无歧义 |
|
||||
| `(1)` 单 token | **能** | ❌ 与 `[1](篮子)` 冲突 |
|
||||
| `(m)` 单变量 | **能** | ❌ 与 `[a](m)` 冲突 |
|
||||
|
||||
于是 `[f](1)`(最常见的单参调用)**永远无法**与取元区分。
|
||||
一个「多参数能用、单参数不能用」的语法,对使用者是最难记的一类。
|
||||
|
||||
---
|
||||
|
||||
## 3. `函数名(参数)`:空闲语法,原型验证通过
|
||||
|
||||
### 3.1 它是空闲的
|
||||
|
||||
实测 `**r = 加(1)**`(原型前)报 `trailing input in expression: "(1)"` ——
|
||||
说明 `名字(` 今天既不表示取元,也不表示任何别的含义。**没有既有语义要保护。**
|
||||
|
||||
### 3.2 原型做了什么
|
||||
|
||||
改了两处(**已回退,仅作验证**):
|
||||
|
||||
1. `src/parse/expr.rs`:新增 `try_paren_call` —— 紧随其后的 `(` 视为参数列表;
|
||||
在 `parse_call_tail` 里优先尝试。
|
||||
2. `src/parse/mod.rs`:粗体赋值与 `>` 两条路径的「像调用」判定加上
|
||||
`looks_like_paren_call`(让单 token 的 `加(1)` 也能进入调用分支)。
|
||||
|
||||
### 3.3 原型实测结果
|
||||
|
||||
| 用例 | 结果 |
|
||||
|------|------|
|
||||
| `加(1)` | ✅ 返回 2(单参) |
|
||||
| `加(1 2 )` | ✅ 返回 3(多参) |
|
||||
| `加("1" "2")` | ✅ 返回 `12`(字符串参数) |
|
||||
| `加(1 2)` | ❌ 末参数把 `)` 吞了 |
|
||||
| `加(a=1 b=2)` | ❌ 具名参数值把 `)` 吞了 |
|
||||
| `加(1, 2)` | ❌ 逗号不是分隔符 |
|
||||
| `加(加(1 2) 3)` | ❌ 嵌套未支持 |
|
||||
| `txt.str_trim(" x ")` | ✅ 返回 `x`(**库函数路径可用**) |
|
||||
| **全量测试** | ✅ **554 passed / 0 failed** |
|
||||
|
||||
**两条关键结论**:
|
||||
|
||||
1. **零回归**:新语法是纯增量,没有破坏任何既有用例(含 4 个 `[k](c)` 取元金样)。
|
||||
2. **真正的落点在参数分词器,不在语法**:`加(1 2)` 失败、`加(1 2 )` 成功,
|
||||
差别只是 `)` 前多一个空格——说明 `parse_call_args` 的分词把 `)` 当成了 token 的一部分。
|
||||
要修就得动 `parse_call_args` / `split_first_token` / `find_next_arg_boundary`,
|
||||
而这个分词器是**所有调用**(含今天在用的 `> f a=1`)共享的。
|
||||
|
||||
这解释了为什么这件事「看起来 10 行、实际一次核心改动」。
|
||||
|
||||
---
|
||||
|
||||
## 4. 人读性对比
|
||||
|
||||
同一个意思,五种写法:
|
||||
|
||||
| 写法 | 读起来 | 现状 |
|
||||
|------|--------|------|
|
||||
| `> 加 1 2` | 「调用加,1 和 2」 | ✅ |
|
||||
| `**合计 = 加 1 2**` | 同上,无 `>` | ✅ |
|
||||
| `**合计 = 加(1 2)**` | 「加(1, 2)」,**像数学/函数调用** | 原型通过 |
|
||||
| `**合计 = 加(a=1 b=2)**` | 「加,a=1、b=2」,自解释 | 原型通过 |
|
||||
| `**[加](1 2)**` | 像链接,但与取元同形 | ❌ 不建议 |
|
||||
|
||||
我的判断:**`f(args)` 是这几种里最符合人读习惯的**,理由有三:
|
||||
|
||||
1. **与数学记号同构**:`税率(2)`、`sin(x)` 是跨语言、跨学科的通用写法,不需要学。
|
||||
2. **参数边界显式**:括号天然划定起止,解决了 `> f a b` 里「参数到哪结束」的模糊
|
||||
(这也是 D8「函数名含空格」难题的天然解药)。
|
||||
3. **不占用 Markdown 的链接语义**:渲染出来是普通文本 `f(1)`,
|
||||
不会像 `[f](1)` 那样在预览里变成超链接。
|
||||
|
||||
---
|
||||
|
||||
## 5. 要走完这条路,需要做什么(评估工作量)
|
||||
|
||||
原型只验证了「方向可行」,要合入还缺这些:
|
||||
|
||||
| # | 事项 | 位置 | 风险 |
|
||||
|---|------|------|------|
|
||||
| 1 | `)` 作为参数终止符 | `parse_call_args` / `split_first_token` / `find_next_arg_boundary` | **中高**:所有调用共享 |
|
||||
| 2 | 逗号分隔 `f(1, 2)` | 同上 | 中:逗号在文本参数里合法(`"a,b"` 已加引号则无碍) |
|
||||
| 3 | 嵌套 `f(g(1) 2)` | `parse_call_args` 递归 | 中:需要括号深度跟踪 |
|
||||
| 4 | 方法 `obj.m(1)` / 库 `lib.fn(1)` | `try_paren_call` 已有基础(库路径实测通过) | 低 |
|
||||
| 5 | 位置/具名混用规则 | 复用 [call-arguments.md](call-arguments.md) §3 | 低 |
|
||||
| 6 | 空参 `f()` | 需定义语义(零参调用) | 低 |
|
||||
| 7 | EKC 指纹 | `collect_calls` 已读 `c.callee`,`CallExpr` 不变 → 自动兼容 | 无 |
|
||||
| 8 | `view` 渲染 | `[callee]` 已有 `bracket_marked` 标记,需决定是否回显括号形式 | 低 |
|
||||
| 9 | `marqdo check` | 需新增「`名字(` 但不是函数」的诊断 | 低 |
|
||||
|
||||
**注意第 7 条**:因为 `f(args)` 最终仍产出 `CallExpr { callee, args }`,
|
||||
EKC 指纹、契约、字节码 `Op::Call(fid, argc)` **全部自动兼容**——
|
||||
这正是它与「一等函数」方案([functions-as-values-evaluation.md](functions-as-values-evaluation.md) §5 路径 A)的本质区别:
|
||||
**它只是换了一种写法,没有改变调用模型。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议
|
||||
|
||||
### 6.1 推荐路线
|
||||
|
||||
1. **不做 `[f](args)`**:与取元同形,且已证明按名消歧会打断 2 个真实文件;
|
||||
而「多参能用、单参不能用」的规则不可教。
|
||||
2. **做 `f(args)`**:空闲语法、零回归、人读性好、不动调用模型。
|
||||
3. 先落**具名**形态 `f(k=v)`(最无争议、自解释),再补位置 `f(1 2)`,最后考虑逗号与嵌套。
|
||||
|
||||
### 6.2 若你想保留方括号的「链接感」
|
||||
|
||||
有一个不碰取元的位置:**语句位置**。
|
||||
|
||||
```markdown
|
||||
> [加](1 2) # 今天报 unknown function;语句位置的 [k](c) 无实际用途
|
||||
```
|
||||
|
||||
`[k](c)` 作为**独立语句**今天只会算出值然后丢弃。全仓库扫描(851 文件):
|
||||
以 `[` 起行且形如 `[k](c)` 的独立行只有 **2 处**,且都是样式示例文件里的
|
||||
普通 Markdown 链接文本(`[海上花开](https://…)`),并非取元代码。
|
||||
所以在**语句调用**里允许 `[f](args)` 几乎无成本,表达式里则不允许。
|
||||
代价是「同一写法在两种位置含义不同」,可教性差;我倾向不做。
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **是否采纳 `f(args)`**(不带方括号)作为新调用写法?
|
||||
2. 若采纳,**先做哪一档**:
|
||||
- A 只做具名 `f(k=v)`(最小、最稳)
|
||||
- B 具名 + 位置 `f(1 2)`(需改分词器,价值最大)
|
||||
- C 再加逗号与嵌套(一次做全)
|
||||
3. **`[f](args)` 是否彻底放弃**(我建议放弃,理由 §2.2);
|
||||
还是只允许在语句位置(§6.2)?
|
||||
4. 是否需要我按 B 档做一次完整实现(含分词器改造 + 金样例 + 变更文档),
|
||||
做完再走 554 回归?
|
||||
|
||||
原型代码已全部回退,工作区干净。等你定档我再动手。
|
||||
@@ -0,0 +1,208 @@
|
||||
# 设计:解析器诊断缺陷修复(D8 / D9)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 / D9 |
|
||||
| 影响面 | **核心解析**(`src/lex/mod.rs` 行分类 + `src/parse/expr.rs` 函数调用) |
|
||||
| 关联 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-vs-comment.md](code-vs-comment.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么这两条要先做调研
|
||||
|
||||
D8 与 D9 都落在**行分类**这一层:它决定一行是「叙述」还是「代码」。
|
||||
改错的代价是**整类文档解析结果变化**,而不是某个函数行为变化。
|
||||
所以本文先量化影响面、列出候选方案并逐条否决,再动手。
|
||||
|
||||
一句话结论:
|
||||
|
||||
- **D9** 的根因是分类层把「引号未闭合的粗体行」降级为叙述,
|
||||
导致解析层精心准备的 `unterminated " string` 报错**永远走不到**。
|
||||
修法是在分类层补一条「粗体起始但闭合搜索失败」的判定,让它进入解析层报错。
|
||||
语料实测 620 个文件 0 处受影响,风险可控。
|
||||
- **D8** 的根因是函数名解析按空格切词,与定义侧不对称。
|
||||
修法是在**定义期**拒绝含空格的函数名(fail fast),
|
||||
而不是在调用期做贪婪匹配(那会改变所有多词行的语义)。
|
||||
|
||||
---
|
||||
|
||||
## 1. D9 — 未闭合引号静默吞行
|
||||
|
||||
### 1.1 现状链路
|
||||
|
||||
```
|
||||
源码行 "**s = \"abc"
|
||||
↓ classify_source → classify_line
|
||||
↓ 首字符 '*' → is_marqdo_star_line?
|
||||
trimmed.starts_with("**") → matching_bold_close(trimmed)
|
||||
→ matching_bold_close_opts(require_eol=true)
|
||||
扫描时遇 '"' → in_str = true
|
||||
之后没有任何 '"' 关闭它 → 后续 '*' 全部被当作字符串内容跳过
|
||||
返回 None(找不到收尾 **)
|
||||
→ is_marqdo_star_line = false
|
||||
↓ classify_line 落到 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
|
||||
↓ 该行成为**叙述**,parser 根本看不到它
|
||||
↓ parse_quoted_string 里 `bail!("unterminated {quote} string")` 不可达
|
||||
```
|
||||
|
||||
**结论**:这不是解析器的 bug,是**分类器的静默降级**。
|
||||
解析层已经把错误信息写好了,却没有人把这一行送到它面前。
|
||||
|
||||
### 1.2 影响(为什么算高严重度)
|
||||
|
||||
| 场景 | 后果 |
|
||||
|------|------|
|
||||
| 手写漏一个引号 | 该行消失;变量未定义 → 在别处报 `undefined variable`,方向被引偏 |
|
||||
| LLM 生成文档 | 少一段内容,但 `exit 0`、`marqdo check` 通过,**文档看起来完整却缺节** |
|
||||
| CI/门禁 | 门禁试跑通过 → 错误文档被沉淀入库 |
|
||||
|
||||
对「文档即程序」而言,这属于最危险的一类:**静默产出错误结果**。
|
||||
|
||||
### 1.3 候选方案与评判
|
||||
|
||||
#### 方案 A:分类层补判定(采纳)
|
||||
|
||||
在 `is_marqdo_star_line` 中,当 `trimmed.starts_with("**")` 且
|
||||
`matching_bold_close` 返回 `None` 时,再判断「这一行是否**像**粗体代码」:
|
||||
|
||||
- 行内含有 `=`(赋值)或 `>` 前导(调用)等强代码信号
|
||||
- 且引号计数为奇数
|
||||
|
||||
满足则**仍判为 Code**,让解析层去报 `unterminated " string`。
|
||||
|
||||
**优点**
|
||||
- 改动局限在分类层,不动解析语义
|
||||
- 复用解析层已有的、措辞准确的报错
|
||||
- 对「正常叙述中含 `**` 强调」零影响(那些行引号是配对的)
|
||||
|
||||
**风险**:叙述里恰好出现 `**…"…` 这种畸形组合会被判成代码 → 报错。
|
||||
但实测语料 0 例,且这种组合本身就是写法错误,报错是**期望行为**。
|
||||
|
||||
#### 方案 B:解析层预扫描(否决)
|
||||
|
||||
在 `parse_classified` 前加一遍全文引号配对检查。
|
||||
|
||||
**否决理由**:引号可以合法地出现在叙述、围栏代码块、行内代码里。
|
||||
全文扫描无法区分上下文,会制造大量假阳性(例如叙述里写「他说 "你好」)。
|
||||
逐行判断需要的是**分类**信息,而这正是方案 A 在做的事。
|
||||
|
||||
#### 方案 C:放宽 `matching_bold_close`,引号未闭合时也认 `**` 收尾(否决)
|
||||
|
||||
**否决理由**:会改变「粗体闭合」的语义。`**s = "a ** b"` 这类行
|
||||
会提前在中间 `**` 处闭合,把字符串拆断,产生更难理解的错误。
|
||||
这是把静默错误换成**更混乱的错误**,不是改进。
|
||||
|
||||
### 1.4 影响面实测
|
||||
|
||||
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| `.mq.md` 文件总数 | 845 |
|
||||
| 含 `**` 起始代码行的文件 | 620 |
|
||||
| **引号计数为奇数的代码行** | **0** |
|
||||
|
||||
扫描时正确跳过了 `\` 转义(`\"` 不算引号开合)。
|
||||
结论:修复不会改变任何现有文件的解析结果。
|
||||
|
||||
### 1.5 验收
|
||||
|
||||
| 用例 | 期望 |
|
||||
|------|------|
|
||||
| `**s = "abc`(未闭合) | 报 `unterminated " string`,退出码非 0 |
|
||||
| `**s = "abc"`(闭合) | 正常运行 |
|
||||
| 跨行 `**s = "a` + `b"**` | 报错(不跨行拼接,符合现状) |
|
||||
| 叙述 `他说 "你好"` | 仍是叙述,不受影响 |
|
||||
| 全量 `cargo test` | 233 全绿 |
|
||||
| 全仓库重跑 `marqdo check` | 无新增错误 |
|
||||
|
||||
---
|
||||
|
||||
## 2. D8 — 函数名含空格:定义成功、调用必崩
|
||||
|
||||
> **⚠️ 本节方案已作废。** 原主张「定义期拒绝空格」违背了「完全兼容 Markdown」:
|
||||
> `## 用户 登录流程` 是合法标题,不该为了可调用而改写。
|
||||
> 现行评估见 [spaced-function-names-d8.md](spaced-function-names-d8.md)(Proposed · 待审阅)。
|
||||
> 本文其余部分(D9)仍然有效。
|
||||
|
||||
### 2.1 现状链路
|
||||
|
||||
```
|
||||
定义侧:## 加一 号 → 标题整体作为函数名 "加一 号"(允许空格)
|
||||
|
||||
调用侧:> 加一 号 n=1
|
||||
↓ 按空白切词
|
||||
token[0] = "加一" → 当作函数名
|
||||
token[1..] = ["号", "n=1"]
|
||||
↓ "号" 无 `=` → 按位置参数/变量插值处理
|
||||
↓ 变量 "号" 不存在 → undefined variable `号`
|
||||
```
|
||||
|
||||
两侧不对称:定义时把整串当名字,调用时只取第一个词。
|
||||
|
||||
### 2.2 候选方案与评判
|
||||
|
||||
#### 方案 A:定义期拒绝空格(**已否决**)
|
||||
|
||||
解析 `## 函数名` 时,若函数名含空白则报错:
|
||||
|
||||
```
|
||||
error: 文件:行: function name may not contain spaces: `加一 号`
|
||||
(write `加一_号`, or quote the call as `> "加一 号"`)
|
||||
```
|
||||
|
||||
**优点**
|
||||
- fail fast:错误在定义处暴露,与调用处报 `undefined variable` 相比指向明确
|
||||
- 不改变任何合法程序的语义
|
||||
- 与「标识符不含空格」的通行约定一致
|
||||
|
||||
**风险**:可能已有文件用了空格函数名且**只定义不调用**(今天能跑)。
|
||||
需先扫描语料确认。
|
||||
|
||||
#### 方案 B:调用侧贪婪匹配已知函数名(否决)
|
||||
|
||||
按「已知函数名的最长前缀」匹配。
|
||||
|
||||
**否决理由**:
|
||||
1. 需要把「所有已定义函数名」带进表达式解析上下文,跨越模块边界后不可判定
|
||||
2. `> print text=hello world` 里 `hello world` 会被尝试拼成函数名,语义歧义
|
||||
3. 改变所有多词行的解析路径,属于核心语义变更,收益远小于风险
|
||||
|
||||
#### 方案 C:只警告不报错(否决)
|
||||
|
||||
**否决理由**:D8 的危害正是「check 通过、运行崩」。继续给警告等于维持现状。
|
||||
|
||||
### 2.3 影响面实测
|
||||
|
||||
统计仓库内**定义侧含空格**的 `##`/`###` 标题(仅可调用的层级):
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 含空格的二级及以下标题 | 4 |
|
||||
| 其中位于源码(非运行时目录)的 | **0** |
|
||||
| 分布 | 全部在 `.marqdo/agent/contexts/*.mq.md` 运行时生成物,且是叙述性标题("Existing Capabilities"),从未被调用 |
|
||||
|
||||
结论:源码中不存在含空格的函数名,加定义期校验不会破坏任何现有模块。
|
||||
运行时生成的 context 文件不受影响——它们不被 import。
|
||||
|
||||
### 2.4 验收
|
||||
|
||||
| 用例 | 期望 |
|
||||
|------|------|
|
||||
| `## 加一 号` | 报 `function name may not contain spaces` |
|
||||
| `## 加一_号` + 调用 | 正常 |
|
||||
| `## 断言干净`(中文连写) | 正常 |
|
||||
| 方法 `### 名字 带空格` | 同样拒绝 |
|
||||
| 全量测试 | 233 全绿 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 实施顺序
|
||||
|
||||
1. D9(分类层,影响面已量化)→ 测试 → 文档
|
||||
2. D8(定义期校验)→ 测试 → 文档
|
||||
3. 两条都做完后跑全仓库回归(`cargo test` + 抽样 `marqdo run`)
|
||||
|
||||
每一步独立提交,便于回滚。
|
||||
@@ -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,216 @@
|
||||
# 方案评估:函数名含空格的调用(D8)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待审阅**(未实施任何代码改动) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 |
|
||||
| 前置 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md)(该文方案 A「禁止空格」**已被否决**,见 §0) |
|
||||
| 影响面 | 核心解析:`src/parse/expr.rs` 调用切词 / `src/lex` 行分类 / 名称解析 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么原方案被否决
|
||||
|
||||
原方案 A 主张「定义期拒绝含空格的函数名」。这是**错的**,理由是我此前忽略的一句话:
|
||||
|
||||
> Marqdo 的立身之本就是**完全兼容 Markdown**。
|
||||
|
||||
`## 用户 登录` 是一个**完全合法的 Markdown 二级标题**。真实文档里这类标题极多:
|
||||
|
||||
```markdown
|
||||
## 用户 登录流程
|
||||
## 第三阶段 数据校验
|
||||
## Appendix A Results
|
||||
```
|
||||
|
||||
如果禁止这些标题当函数名,等于强迫作者为了「能调用」而改写标题措辞——
|
||||
这恰恰把「代码即文档」降级成「代码迁就文档」。作者写的标题首先应当是**他自己想写的标题**。
|
||||
|
||||
**结论:空格必须被支持,问题只在于「怎么把带空格的名字准确传给调用」。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 事实基础(全部实测,1.5.2)
|
||||
|
||||
先固定真实行为,避免方案讨论建立在猜测上。
|
||||
|
||||
### 1.1 定义侧
|
||||
|
||||
| 输入 | 结果 |
|
||||
|------|------|
|
||||
| `## 加一 号` | ✅ 定义成功,函数名**原样**为 `加一 号`(`parse_object_decl` 走 `Ok((raw.to_string(), None))`) |
|
||||
| `## 用户 登录流程` | ✅ 同上 |
|
||||
|
||||
**定义侧完全支持空格**,不需要任何改动。
|
||||
|
||||
### 1.2 调用侧
|
||||
|
||||
| 输入 | 结果 | 原因 |
|
||||
|------|------|------|
|
||||
| `> 加一 号 n=1` | ❌ `undefined variable 号` | `parse_call_tail` 用 `split_whitespace().next()` 只取首词 |
|
||||
| `> [加一_号] n=1` | ✅ 正常(返回 2) | 方括号标记调用**已存在**且工作 |
|
||||
| `> [加一 号] n=1` | ❌ `unknown function [加一` | `is_bracket_callee_inner` 第 1248 行**显式拒绝含空白** |
|
||||
| `` `加一 号` `` 作为表达式 | ❌ `undefined variable 加一 号` | 反引号名走变量解析,找不到函数 |
|
||||
|
||||
### 1.3 关键发现
|
||||
|
||||
> **方括号标记调用(`[callee]`)已经存在且实现完整**,
|
||||
> 挡住带空格名字的是 `is_bracket_callee_inner` 里的**两处**校验,
|
||||
> 而不是一处(首轮评估低估了)。
|
||||
|
||||
这是本次评估最重要的发现:**不需要发明新语法**,只需要让既有机制接受空格。
|
||||
|
||||
### 1.4 可行性实测(已做,未保留改动)
|
||||
|
||||
为回答「放开后运行时到底能不能查到含空格的函数名」,做了受控实验:
|
||||
临时放开两处校验 → 编译 → 跑用例 → **立即回退**(`src/parse/expr.rs` 已恢复原样)。
|
||||
|
||||
| 关卡 | 位置 | 原逻辑 | 放开后 |
|
||||
|------|------|--------|--------|
|
||||
| 1 | `is_bracket_callee_inner` | `t.chars().any(is_whitespace)` → 拒绝 | 删除该检查 |
|
||||
| 2 | 同函数末尾 bare-name 白名单 | `is_alphanumeric() \| '_' \| '.' \| !is_ascii()` | 追加 `\| c == ' '` |
|
||||
|
||||
**实验结果**
|
||||
|
||||
| 用例 | 结果 |
|
||||
|------|------|
|
||||
| `## 加一 号` + `> [加一 号] n=1` | ✅ **返回 `2`**(运行时函数表正确命中含空格名) |
|
||||
| `## 加一_号` + `> [加一_号] n=1`(对照) | ✅ 仍返回 `2`,既有行为不变 |
|
||||
| 全量 `cargo test --lib` | ✅ **237 passed, 0 failed** |
|
||||
|
||||
**结论**:方案 1 技术上完全成立,且**不破坏既有测试**。
|
||||
(237 = 基线 233 + 本轮 D9 新增的 4 个分类测试。)
|
||||
|
||||
> 注意:实验只证明「可行」,未固化。正式实施需要补 §4 的全部 V1–V9 用例,
|
||||
> 特别是 V3–V7 的歧义排除,再决定是否合入。
|
||||
|
||||
---
|
||||
|
||||
## 2. 候选方案
|
||||
|
||||
### 方案 1 — 放开方括号内的空格(推荐)
|
||||
|
||||
**做法**:把 `is_bracket_callee_inner` 的「含空白即拒绝」改为「允许空白,
|
||||
但需与既有歧义守卫共存」;并确认调用链后续不再按空格切词。
|
||||
|
||||
**用法**:
|
||||
|
||||
```markdown
|
||||
## 用户 登录流程
|
||||
+ `账号`
|
||||
|
||||
*"已登录 " + `账号`*
|
||||
|
||||
# main
|
||||
|
||||
> [用户 登录流程] 账号=alice
|
||||
*""
|
||||
```
|
||||
|
||||
**优点**
|
||||
- 不新增语法:`[…]` 标记调用是**既有**的正式特性,只是被一行校验挡住
|
||||
- 向后兼容:所有现有调用(含 `[加一_号]`)行为不变
|
||||
- 与 Markdown 完全兼容:标题怎么写都行,调用时用方括号「引用这个名字」
|
||||
- 语义清晰:方括号本身就是「这里是一个整体名字」的视觉标记
|
||||
- 可推广:方法调用 `[obj.方法 名]`、库函数 `[lib.函数 名]` 一并受益
|
||||
|
||||
**风险与缓解**
|
||||
| 风险 | 缓解 |
|
||||
|------|------|
|
||||
| `[…]` 也被用于链接索引 `[key](map)` | 已有守卫:`]` 后紧跟 `(` 则不是 callee(第 981 行),保持 |
|
||||
| JSON 数组 `[1, 2]` 被误认为 callee | 既有守卫:含 `,` `:` `{` `}` `[` `]` 一律拒绝,保持 |
|
||||
| `print text=(礼貌 [问候] x)` 类内嵌方括号 | 既有守卫:前缀含 `=` `(` `"` `'` `:` 则不当 callee,保持 |
|
||||
| 运行时按下标查函数表,`加一 号` 能否命中 | **需实测验证**(见 §4 验证计划 V1) |
|
||||
|
||||
**工作量**:改 2 处校验 + 补 6–9 个测试 + 更新教程与陷阱手册。**最小可验证改动**。
|
||||
|
||||
---
|
||||
|
||||
### 方案 2 — 调用侧最长前缀匹配(否决)
|
||||
|
||||
**做法**:拿到 `加一 号 n=1` 后,尝试用「已知函数名」做最长前缀匹配。
|
||||
|
||||
**否决理由**
|
||||
1. **上下文不可达**:调用发生在表达式解析阶段,此时只有本模块符号表;
|
||||
跨模块 `lib.函数 名` 需要 import 解析结果,不可在词法期判定。
|
||||
2. **歧义爆炸**:`> print text=hello world` 中,若存在名为 `print text` 的函数,
|
||||
本来正确的调用会突然变成别的函数。所有多词行语义都可能改变。
|
||||
3. 属于**核心语义变更**,收益(省掉方括号)远小于风险。
|
||||
|
||||
---
|
||||
|
||||
### 方案 3 — 主张「标题即函数名,调用用完整标题」(不改代码,只改文档)
|
||||
|
||||
**做法**:明确官方立场——带空格的名字**不自称可调用**,需要调用就请写
|
||||
一个无空格的 `## 别名` 转发,或直接把标题写成无空格形式。
|
||||
|
||||
```markdown
|
||||
## 用户 登录流程 ← 给人读的标题,不被调用
|
||||
|
||||
## 用户登录流程 ← 真正被调用的函数
|
||||
+ `账号`
|
||||
...
|
||||
```
|
||||
|
||||
**优点**:零代码改动;鼓励「标题给人、标识符给机器」的清晰分层。
|
||||
|
||||
**缺点**:与「完全兼容 Markdown」仍有张力——作者得写两遍。
|
||||
|
||||
**适用**:如果审计认为方括号放开会牵连过多,可作为**保守退路**。
|
||||
|
||||
---
|
||||
|
||||
### 方案 4 — 反引号名解析到函数(否决)
|
||||
|
||||
允许 `` `加一 号` `` 在**调用位**解析成函数引用(`> `加一 号` n=1`)。
|
||||
|
||||
**否决理由**:反引号在 Marqdo 中统一表示**变量**引用。让它有时指变量、有时指函数,
|
||||
会让「反引号=变量」这条最基础的约定失效,错误更难排查。
|
||||
|
||||
---
|
||||
|
||||
## 3. 方案对比
|
||||
|
||||
| 维度 | 方案 1 放开方括号 | 方案 2 前缀匹配 | 方案 3 文档立场 | 方案 4 反引号 |
|
||||
|------|------------------|----------------|----------------|--------------|
|
||||
| 兼容 Markdown | ✅ 完全 | ✅ | ⚠️ 需写两遍 | ✅ |
|
||||
| 新增语法 | 无(复用既有) | 无 | 无 | 有歧义 |
|
||||
| 改动范围 | 1 处校验 + 测试 | 核心语义 | 0 代码 | 核心语义 |
|
||||
| 回归风险 | 低 | **高** | 无 | **高** |
|
||||
| 可验证性 | 高(可枚举用例) | 低 | — | 低 |
|
||||
| 推荐 | **首选** | 否决 | 备选 | 否决 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 若采纳方案 1:验证计划
|
||||
|
||||
必须全部通过才可合入。
|
||||
|
||||
| 编号 | 用例 | 期望 |
|
||||
|------|------|------|
|
||||
| V1 ✅| `## 加一 号` + `> [加一 号] n=1` | 返回 `2`(**已实测通过**,见 §1.4) |
|
||||
| V2 | `## 加一_号` + `> [加一_号] n=1` | 返回 `2`(**既有行为不变**) |
|
||||
| V3 | 链接索引 `[k](m)` | 仍解析为索引,不被当 callee |
|
||||
| V4 | `> print text=(礼貌 [问候] x)` | 内嵌方括号不被当 callee |
|
||||
| V5 | 方括号内 JSON `[1, 2]` / `["a"]` | 仍被拒绝为 callee |
|
||||
| V6 | 跨模块 `[lib.函数 名]` | 正确解析到库函数 |
|
||||
| V7 | 方法 `[obj.方法 名]` | 正确解析 receiver |
|
||||
| V8 | 全量 `cargo test` | 233 全绿(+ 新增用例) |
|
||||
| V9 | 全仓库 `.mq.md` 回归 | 无新增解析错误 |
|
||||
|
||||
**V1 是决定性的**:如果运行时函数表以 `加一 号` 为键能正常查到,
|
||||
方案 1 就成立;如果查不到(比如符号表内部也做了归一化),需要再评估。
|
||||
|
||||
---
|
||||
|
||||
## 5. 待你决策的问题
|
||||
|
||||
1. **选哪个方案?** 我倾向 **方案 1**(放开方括号空格):不新增语法、
|
||||
完全兼容 Markdown、改动可控、可验证性强。
|
||||
2. **若选方案 1,调用书写是否需要中文别名?** 例如同时接受 `【加一 号】`(全角方括号),
|
||||
与全角冒号问题(D2)一致。
|
||||
3. **是否要保留方案 3 的文档立场作为补充说明?** 即「标题可自由书写;
|
||||
需要调用时用 `[完整名]` 引用」——这句话本身就很适合写进教程。
|
||||
|
||||
在你确认前,我不会改动 D8 相关代码。
|
||||
@@ -0,0 +1,223 @@
|
||||
# 修订:变更检测不该依赖 git —— 「前一状态」的 provider 分层
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 修订**(取代 [warning-fatigue-control.md](warning-fatigue-control.md) §2 的 M5a) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 触发 | 用户:不是所有开发都用 git,依赖 git 是否是好设计 |
|
||||
| 结论 | **不是好设计**。保住「变更驱动」原则,把「前一状态」抽象为可插拔 provider;核心能力零依赖 |
|
||||
| 前置 | [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 直接回答:不该依赖 git
|
||||
|
||||
三条理由,一条比一条硬:
|
||||
|
||||
### 0.1 环境覆盖不到
|
||||
|
||||
| 环境 | 能调 git 吗 | 依据 |
|
||||
|------|------------|------|
|
||||
| 浏览器 WASM | ❌ | `marqdo-wasm`(wasm32-unknown-unknown),无进程能力 |
|
||||
| **沙箱内执行** | ❌ | `src/host/sandbox_fs.rs`:`allow_exec: false` |
|
||||
| 单文件分发 / zip 工件 | ❌ | 没有 `.git` |
|
||||
| CI 容器(浅克隆/无 VCS) | ⚠️ 常常没有 | 取决于流水线 |
|
||||
| 非 git 用户(hg / svn / fossil / 无) | ❌ 或需另写适配 | — |
|
||||
|
||||
### 0.2 语言不该绑定某个 VCS
|
||||
|
||||
Marqdo 是**语言与运行时**。把"断言是否过期"的判定建立在"某个工具的目录是否存在"上,
|
||||
等于把语言的语义正确性外包给环境。今天 git 是主流,明天不是;语言不能跟着换。
|
||||
|
||||
### 0.3 最要命的:最重要的消费者恰在不能调 git 的地方
|
||||
|
||||
标签过期检测的**最高价值场景**是 agent 修复回路——
|
||||
模型改了代码,Marqdo 提醒它"你改的这处描述可能不成立了"。
|
||||
|
||||
而这个回路:
|
||||
- 常在沙箱里跑(`exec=false`,**调不了 git**)
|
||||
- 编辑目标是内存中的文本(`repair_apply` 的 `source`),不一定落在 git 工作区
|
||||
|
||||
**如果核心机制依赖 git,那它恰好在最需要它的地方失灵。** 这是设计错误的铁证。
|
||||
|
||||
---
|
||||
|
||||
## 1. 但 M5 的原则要保住
|
||||
|
||||
上一份文档的 M5 有两个部分,必须分开看:
|
||||
|
||||
| 部分 | 判定 |
|
||||
|------|------|
|
||||
| **原则**:stale 是"变更报告",不是"扫描报告"(没有新信息就不说话) | ✅ **保留**,这是防疲劳的根 |
|
||||
| **实现**:用 `git diff` 提供"前一状态" | ❌ **降级为可选 provider** |
|
||||
|
||||
也就是说:
|
||||
|
||||
> **判定逻辑只有一份:`stale ⟺ fingerprint(()) 变了 ∧ label 没变`。
|
||||
> 变的只是「前一个 `()` 从哪来」。**
|
||||
|
||||
这一步抽象之后,git 只是**四种来源之一**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 四层能力(provider 分层)
|
||||
|
||||
### T0 — 引用一致性(零依赖,永远可用)
|
||||
|
||||
纯文档分析:标签里的 `` `实体` `` 必须可解析、且出现在 `()` 中。
|
||||
|
||||
- 需要:只读当前文件(甚至只需文本)
|
||||
- 能力:查**引用腐烂**(改名、删除、错引)
|
||||
- 查不了:语义腐烂(`*` 改 `/`)
|
||||
|
||||
### T1 — 会话内前后对照(零依赖,最高性价比)
|
||||
|
||||
**任何"编辑前 + 编辑后"都在手的场合**都能算 stale:
|
||||
|
||||
| 场合 | 前一状态从哪来 |
|
||||
|------|---------------|
|
||||
| `MLSP repair_apply` | 调用方传入的 `source` + `edits` → 前/后两版都在内存里 |
|
||||
| `view`(保存后检查) | 保存前的模块 AST |
|
||||
| 编辑器保存钩子 | 编辑器持有的旧缓冲 |
|
||||
| agent 的 diff | 它自己的编辑集 |
|
||||
|
||||
**关键**:只看「本次会话改了哪些标签的 `()` 且没改 `[]`」。
|
||||
天然变更驱动、天然零台账、天然带 before/after——**而且不需要 git**。
|
||||
|
||||
### T2 — 外部历史源(可选,自动探测)
|
||||
|
||||
`git` / `hg` / `svn` / 任意"能取到上一版文件内容"的适配器。
|
||||
|
||||
- 检测:工作区存在 `.git` / `.hg` 且二进制可用
|
||||
- 用途:**跨会话**漂移(昨天改了代码,今天才检查)
|
||||
- 缺失时:**静默关闭**,不报错、不提示、不产生噪音
|
||||
|
||||
### T3 — 台账(可选,无 VCS 时的持久化)
|
||||
|
||||
`.marqdo/labels.json`:`{标签键 → {code_fingerprint, code_quote, confirmed_at}}`
|
||||
|
||||
- 用途:没有 VCS 的环境(沙箱长期任务、编辑器插件)+ 严格模式的"确认"状态
|
||||
- 语义:**可丢弃缓存**(删了重建,最多一次全量确认)
|
||||
- 已知代价:合并冲突、需要 bootstrap(因此作为 opt-in,不做默认)
|
||||
|
||||
---
|
||||
|
||||
## 3. 环境能力矩阵
|
||||
|
||||
| 环境 | T0 引用 | T1 会话内 | T2 历史源 | T3 台账 |
|
||||
|------|--------|----------|----------|--------|
|
||||
| CLI + git 仓库 | ✅ | ✅ | ✅ | ✅ |
|
||||
| CLI + hg/svn(有适配) | ✅ | ✅ | ✅ | ✅ |
|
||||
| CLI 无 VCS | ✅ | ✅ | ❌ | ✅ |
|
||||
| **agent 沙箱(exec=false)** | ✅ | ✅ | ❌ | ⚠️ CoW 内可写但不持久 |
|
||||
| **浏览器 WASM** | ✅ | ✅ | ❌ | ❌ 无持久 fs |
|
||||
| 单文件 / zip 工件 | ✅ | ✅ | ❌ | ❌ |
|
||||
| 数据库/对象存储里的 `.mq.md` | ✅ | ✅ | ❌ | 由宿主提供 |
|
||||
|
||||
**读法**:矩阵里**没有一行全 ❌**。T0+T1 在所有环境都成立——
|
||||
这两层就足以支撑"agent 改动即时提醒"这个最高价值场景。
|
||||
|
||||
---
|
||||
|
||||
## 4. 各层的能力边界(必须诚实)
|
||||
|
||||
| 层 | 能查 | 查不了 |
|
||||
|----|------|--------|
|
||||
| T0 | 引用了不存在的实体;引用的实体不在语句里 | 语义腐烂(乘改除) |
|
||||
| T1 | **本次会话内**的 `()` 变化 | 跨天/跨机器的漂移 |
|
||||
| T2 | 跨会话、跨机器的漂移(若 VCS 有历史) | 未提交历史之外的变化;跨仓库移动 |
|
||||
| T3 | 持久化的漂移(若台账被维护) | 台账未覆盖的标签;合并后需重算 |
|
||||
|
||||
**组合起来的语义**:
|
||||
- 有 T2 → 严格(能查历史)
|
||||
- 只有 T0+T1 → **会话级严格**(够 agent 用)
|
||||
- 什么都没有(WASM 首次打开) → 只查引用(T0),且**明确告知能力级别**
|
||||
|
||||
---
|
||||
|
||||
## 5. 最关键的一条:agent 回路不需要任何 VCS
|
||||
|
||||
`MLSP repair_apply` 的参数里**已经同时有前后两版**:
|
||||
|
||||
```rust
|
||||
// src/mlsp.rs:repair_apply 收到 source + ranges + edits
|
||||
let source = source_text(params)?;
|
||||
// → 应用 edits 得到 after
|
||||
```
|
||||
|
||||
所以只要给协议补一个字段 `base_code`(或让 `repair_apply` 自己在内部保留 before),
|
||||
Marqdo 就能在**同一次调用内**算出:
|
||||
|
||||
> 哪些标签的 `()` 指纹变了、而 `[]` 没变 → 输出 stale 提示。
|
||||
|
||||
**零外部状态、零依赖、零 git。** 而这正是"模型改了代码别忘了改描述"的场景。
|
||||
|
||||
**具体协议建议**(只需一个可选字段):
|
||||
|
||||
```json
|
||||
{ "method": "repair_apply",
|
||||
"params": { "source": "…", "ranges": [[42,42]], "edits": [...],
|
||||
"check_labels": true } }
|
||||
```
|
||||
|
||||
返回里附:
|
||||
|
||||
```json
|
||||
{ "labels": [{ "stale": 1, "items": [{ "text": "按 `税率` 计算总价",
|
||||
"code_past": "…* 金额", "code_now": "…/ 金额", "span": {...} }] }] }
|
||||
```
|
||||
|
||||
这样 agent 每轮只看到**自己刚弄脏的那几条**,且带前后对照。
|
||||
|
||||
---
|
||||
|
||||
## 6. provider 契约(五条硬规则)
|
||||
|
||||
1. **核心不依赖**:T0/T1 必须在任何环境可用,不得引入 provider 前置条件。
|
||||
2. **缺失即降级**:provider 不可用 → 静默关闭该层能力,**绝不报错、绝不提示**。
|
||||
3. **能力必须自述**:`labels status` 必须显示"当前启用 T0/T1/T2/T3 中的哪些"。
|
||||
——否则用户会误以为"没报 = 没问题",这是比噪音更坏的失败。
|
||||
4. **判定单一定义**:`stale` 的定义只有一处实现;provider 只提供 `prev`,不参与判定。
|
||||
——否则不同环境会给出不同结论,语言就没有统一语义了。
|
||||
5. **不写进文档**:provider 的状态、指纹、抑制**一律不进 `.mq.md`**。
|
||||
文档里只允许有人的语言与代码。
|
||||
|
||||
> 第 3 条是我这次最想强调的:**宁可少报,也不能假装"检查过了"。**
|
||||
|
||||
---
|
||||
|
||||
## 7. 被否决的方案
|
||||
|
||||
| 方案 | 否决理由 |
|
||||
|------|---------|
|
||||
| **强制 git 作为核心** | 环境覆盖不到(§0.1);语言绑定 VCS(§0.2);最关键场景失灵(§0.3) |
|
||||
| 文档内嵌指纹 | 污染文档;作者一改就失效;与"文档即散文"冲突 |
|
||||
| 零宽字符隐藏指纹 | 不可见 = 不可审计;复制粘贴即损坏;工具链噩梦 |
|
||||
| mtime 启发式 | 不可靠(checkout、touch、云同步都会变) |
|
||||
| `# noqa` 抑制 | 已否(污染 + 不可审计 + 会永久化) |
|
||||
| 只做全量扫描 + 静音清单 | 静音清单就是台账,且首次即爆炸 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 对上一份文档的修订
|
||||
|
||||
| 原条目 | 修订后 |
|
||||
|--------|--------|
|
||||
| M5a「git 结构化 diff」为核心机制 | 降级为 **T2 的一个适配器**;核心改为 **T0 + T1** |
|
||||
| 严格模式依赖台账 | 严格模式 = 任意 T2 **或** T3 可用即可;无 provider 时按 T0/T1 运行 |
|
||||
| 验收指标「无变更时输出 = 0」 | 保留,且补一条:**provider 缺失时也必须为 0,并在 `labels status` 里说明** |
|
||||
|
||||
---
|
||||
|
||||
## 9. 待你决策
|
||||
|
||||
1. **接受「T0+T1 为核心,T2/T3 可选」这个分层吗?**
|
||||
2. **T1 是否足够**作为 agent 回路的默认能力?(我认为够——它覆盖了"刚改完"这个主场景)
|
||||
3. **能力自述**要不要做成 `labels status` 的固定输出
|
||||
(含"本次无法检测历史漂移"这类明确提示)?
|
||||
4. **T2 的适配范围**:只做 git,还是留一个通用接口(返回"某文件的上一版文本")由宿主实现?
|
||||
5. **T3 台账**是否推迟到有明确需求再做?(我建议推迟——先把 T0+T1 做扎实)
|
||||
|
||||
> 我的建议:**先只做 T0 + T1**,把「变更驱动 + 零依赖 + 能力自述」这条骨架立住。
|
||||
> 这样无论用户在 git、hg、WASM 还是沙箱里,Marqdo 的标签保鲜都成立,
|
||||
> 只是"能看多远"不同——而这一点会被明确告知,不会假装。
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 状态 | **v1 已落地**;v2 设计见 [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [notebook-syntax.md](notebook-syntax.md) |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) · [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [roadmap/foreign-v2.md](../roadmap/foreign-v2.md) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -35,7 +35,8 @@
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -44,7 +45,8 @@ import text:lib/text.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
导入 文本:lib/文本.mq.md
|
||||
导入:
|
||||
文本: lib/文本.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -34,7 +34,16 @@
|
||||
|
||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
||||
|
||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
||||
**推荐(块内元数据)**:在 `$$` 体内用 TeX 注释声明变量(见 [fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)):
|
||||
|
||||
````markdown
|
||||
$$
|
||||
% marqdo: var=f
|
||||
sin(x) + x
|
||||
$$
|
||||
````
|
||||
|
||||
**兼容**:空 RHS 赋值后跟展示数学块(与 `` `xs` = `` 后跟表格一致):
|
||||
|
||||
````markdown
|
||||
# main
|
||||
@@ -52,13 +61,14 @@ $$
|
||||
也支持:
|
||||
|
||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`(历史面)
|
||||
- 行内:`` `g` = $x+1$ `` 或 `` `g` = $$x+1$$ ``
|
||||
|
||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
||||
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区裸 `$$` 若既无空 RHS 又无 `% marqdo: var=` → 报错。
|
||||
|
||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
||||
**行内 `$…$`:** 传统绑定 `` `名` = $…$ `` → `formula`;**不**使用 `$% marqdo:…$`(会破坏 Markdown/TeX 识别)。
|
||||
|
||||
### 2.3 从文本构造
|
||||
|
||||
|
||||
@@ -17,7 +17,8 @@
|
||||
|
||||
```markdown
|
||||
---
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -8,9 +8,11 @@
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` → `marqdo view`(及静态 `view output`)在对应语句下显示 **output-card**,并在源码面用 **writeback** 样式标出块本身。
|
||||
|
||||
## 存储格式
|
||||
## 存储格式(两种,可并存)
|
||||
|
||||
### 1. HTML 注释(文本 / 结构化输出)
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
@@ -30,11 +32,26 @@ pending
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
### 2. Markdown 图片(生成图 / 审计友好)
|
||||
|
||||
当 `value` **看起来像图片引用**(扩展名 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.svg` / …,或 `data:image/…`)时,`record` **自动**写成:
|
||||
|
||||
```markdown
|
||||

|
||||

|
||||
```
|
||||
|
||||
- 普通 Markdown 预览即可看见图;view / 静态站额外加 writeback 标记与 output-card 中的 `<img>`。
|
||||
- 非图片路径仍走注释块;把非图片硬写成 `` 时扫描会忽略(校验失败)。
|
||||
- `list` / `scan_path` 结果带 `kind`: `comment` | `image`。
|
||||
|
||||
### 共用规则
|
||||
|
||||
- 标记字为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
- 默认在**调用行下方**插入或替换紧邻**无键**块
|
||||
- `at_end=true`:替换文件末尾的**无键**块
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
|
||||
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽;`ensure` 在缺失时写入占位且不覆盖已有正文
|
||||
- `line=` / `行=`:显式锚点行号;主机侧有全局互斥锁
|
||||
|
||||
### 替换跨度与空行
|
||||
|
||||
|
||||
@@ -51,8 +51,9 @@ Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,233 @@
|
||||
# T1 会话内陈旧检测:为什么模型不会收到重复警告
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 机制说明**(M6 落地) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 回答 | 「在不改变的情况下,能让模型免于多次警告疲劳吗?」——**能,而且几乎不用改什么** |
|
||||
| 前置 | [staleness-providers.md](staleness-providers.md) · [warning-fatigue-control.md](warning-fatigue-control.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
> **警告的作用域 = 模型自己刚改的那几行;投递次数 = 一次;附着在造成它的那次编辑的返回里。**
|
||||
|
||||
不是"我们让它少报",而是**同一件事在结构上不可能被报第二次**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 机制为什么成立:前后两版本来就在手里
|
||||
|
||||
看现有 `repair_apply`(`src/mlsp.rs:233`)的实现:
|
||||
|
||||
```rust
|
||||
let source = source_text(params)?; // ← 改动前(before)
|
||||
...
|
||||
match crate::repair::apply_edits(&source, &ranges, &edits) {
|
||||
Ok(new_source) => { // ← 改动后(after)
|
||||
Ok(json!({"source": new_source, "edits_applied": edits.len()}))
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**`source` 和 `new_source` 在同一个函数作用域里同时存在。**
|
||||
所以"比较改动前后"不需要任何外部东西:
|
||||
|
||||
| 需要的东西 | 从哪来 |
|
||||
|-----------|--------|
|
||||
| 改动前的 AST | `parse(source)` |
|
||||
| 改动后的 AST | `parse(new_source)` |
|
||||
| 标签配对 | 两份 AST 里的标签节点(按标签文本 + 序号) |
|
||||
| `()` 是否变了 | 比较两边的 AST 指纹 |
|
||||
| `[]` 是否变了 | 比较标签文本 |
|
||||
|
||||
**零 git、零台账、零缓存文件、零环境依赖。** 这就是"agent 回路根本不需要 VCS"的含义。
|
||||
|
||||
### 1.1 指纹怎么做(T1 只需要「进程内一致」)
|
||||
|
||||
这一点让实现变得很轻:
|
||||
|
||||
- `Expr` 目前 `#[derive(Debug, Clone)]`,**没有 `PartialEq`**(`src/ast.rs:184`)。
|
||||
- 但 T1 只在**同一个进程内**比较前后两版,**不需要跨版本、跨机器稳定的指纹格式**。
|
||||
于是最简做法是:把 `()` 的比较键取为 `format!("{:?}", expr)`——同一次运行内确定即可。
|
||||
- 若想更严谨,可给 `Expr` 及其成员补 `#[derive(PartialEq)]`(纯机械改动;`Literal` 含 `f64`,
|
||||
只可 `PartialEq` 不可 `Eq`),然后直接结构比较,不产生字符串。
|
||||
- 反过来,**T2/T3 才需要稳定指纹**(跨会话要能对上),那时才动用
|
||||
`knowledge/fingerprint.rs` 那套。
|
||||
|
||||
> 也就是说:T1 的实现成本 ≈ "解析两次 + 比较两棵子树",没有版本化指纹的负担。
|
||||
|
||||
---
|
||||
|
||||
## 2. 一次修复轮次的完整时序
|
||||
|
||||
```
|
||||
第 N 轮
|
||||
┌─ validate → 语法/契约诊断(不含标签扫描)
|
||||
├─ repair_targets → 靶点 + 允许范围
|
||||
├─ 模型产出 edits (例如:把 `* 金额` 改成 `/ 金额`)
|
||||
└─ repair_apply(source, ranges, edits)
|
||||
│
|
||||
├─ before = source
|
||||
├─ after = apply_edits(...)
|
||||
├─ 解析两版 → 比较每个标签的 () 指纹
|
||||
└─ 返回:
|
||||
{ "source": after,
|
||||
"edits_applied": 1,
|
||||
"labels": { "stale": [ {标签, code_past, code_now, span} ] } }
|
||||
```
|
||||
|
||||
模型在自己这次编辑的**响应里**看到:
|
||||
|
||||
```json
|
||||
{
|
||||
"labels": {
|
||||
"stale": [{
|
||||
"text": "按 `税率` 计算总价",
|
||||
"code_past": "at(税率表, 档位) * 金额",
|
||||
"code_now": "at(税率表, 档位) / 金额",
|
||||
"span": {"line": 42, "col": 12}
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
它只需要回答一个问题:**"你刚才动了这段实现,描述还成立吗?"**
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么「重复」在结构上消失了
|
||||
|
||||
三个性质,缺一不可:
|
||||
|
||||
| 性质 | 内容 | 效果 |
|
||||
|------|------|------|
|
||||
| **作用域 = 自己的 diff** | 只看这次 `apply` 触及的标签 | 全仓库/全文件的旧债永远不进模型的上下文 |
|
||||
| **投递 = 一次** | 只在造成它的那次响应里出现 | 不会在后续 `validate` 里重复出现 |
|
||||
| **自包含** | 下一轮的 diff 是新的 | 模型不改那处 → 那条标签不再出现 |
|
||||
|
||||
**注意第三条的含义(也是代价)**:模型若忽略了提示,它**不会**在下一轮被再提醒——
|
||||
因为它没碰那处。这是刻意的取舍:**宁可漏一次,也不反复骚扰**。
|
||||
|
||||
> 对比扫描式:一个 20 处标签的文件,5 轮修复里模型可能累计看到上百条重复提示;
|
||||
> T1 下最多看到 **自己这几行涉及的 0–2 条**,且每条只出现一次。
|
||||
|
||||
---
|
||||
|
||||
## 4. 关键重构:它在性质上**不是 warning,而是编辑期诊断**
|
||||
|
||||
这是我认为最重要的一点。
|
||||
|
||||
| | Lint 警告 | 编译器错误 | **T1 stale** |
|
||||
|---|---|---|---|
|
||||
| 出现时机 | 常在后台/每次保存 | 你按下构建那一刻 | **你改完那一刻** |
|
||||
| 数量 | 与存量成正比 | 与你这次写的错成正比 | **与你这次改的成正比** |
|
||||
| 是否重复 | 反复出现 | 不重复(改了就消失) | **不重复** |
|
||||
| 用户态度 | 容易忽略 | 必须处理 | **天然要处理** |
|
||||
|
||||
没有人抱怨"编译器又报语法错了"——因为它是**一次性的、可归因的、改动驱动的**。
|
||||
T1 的 stale 正好落在这个类别里。
|
||||
|
||||
**所以疲劳问题不是靠压制解决的,是靠把 stale 从"lint 类别"搬到"编译错误类别"解决的。**
|
||||
|
||||
---
|
||||
|
||||
## 5. 「不改变」到什么程度
|
||||
|
||||
你的问法是"在不改变的情况下"。精确回答:
|
||||
|
||||
| 项 | 要不要变 |
|
||||
|----|---------|
|
||||
| `.mq.md` 文档内容 | **不变**(不嵌指纹、不加 `noqa`、不加标记) |
|
||||
| 写代码 / 读代码的工作流 | **不变**(还是 validate → repair_targets → 编辑 → repair_apply) |
|
||||
| 项目状态文件 | **不新增**(无台账、无基线、无 `.marqdo/labels.json`) |
|
||||
| 对 VCS 的依赖 | **无**(沙箱 `exec=false`、WASM 无进程,照样可用) |
|
||||
| 环境要求 | **无**(纯内存计算) |
|
||||
| **MLSP 协议** | **加一个可选参数 + 一个响应字段**(这是唯一的改动) |
|
||||
|
||||
唯一的协议改动小到可以忽略:
|
||||
|
||||
```json
|
||||
{ "method": "repair_apply",
|
||||
"params": { "source": "…", "ranges": [[42,42]], "edits": [...],
|
||||
"check_labels": true } }
|
||||
```
|
||||
|
||||
- `check_labels` 缺省 = 不做(**默认零开销、零噪音**)
|
||||
- 客户端(agent 框架)在修复回路里打开它
|
||||
- 返回里多一个 `labels` 字段;无 stale 时为空数组
|
||||
|
||||
---
|
||||
|
||||
## 6. 配对规则(哪些算"同一条标签")
|
||||
|
||||
比较两份 AST 时:
|
||||
|
||||
| 情形 | 判定 |
|
||||
|------|------|
|
||||
| 标签文本未变、`()` 指纹变 | ✅ **stale**(核心场景) |
|
||||
| 标签文本变了 | 不报——作者在更新描述,这就是"确认" |
|
||||
| `()` 与标签都没变 | 不报 |
|
||||
| 新插入的标签 | 不报——新断言无历史 |
|
||||
| 被删掉的标签 | 不报——没有东西可比 |
|
||||
| 标签移动位置(同文件) | 不报——按标签文本配,不按行号 |
|
||||
|
||||
**"按标签文本配对"很关键**:它让"把这段代码挪个位置"不会误报,
|
||||
而"把这段代码的计算改了"一定报警。
|
||||
|
||||
---
|
||||
|
||||
## 7. 模型会不会漏掉?三种兜底
|
||||
|
||||
T1 的代价是"不重复",所以要设计"漏了怎么办":
|
||||
|
||||
| 兜底 | 做法 | 代价 |
|
||||
|------|------|------|
|
||||
| **循环预算** | `labels.stale` 非空时,客户端允许下一轮(现有 `max_attempts: 2` 直接可用) | 无 |
|
||||
| **可选阻塞** | `check_labels: "block"`:apply 成功但返回 `needs_attention: true`,客户端不得结束任务 | 小 |
|
||||
| **会话末汇总** | 最后一轮给一次总数(只一次,不逐条) | 小 |
|
||||
|
||||
**建议默认**:`check_labels: true` + 循环预算。也就是"提示一次,允许一轮修,不强制"。
|
||||
知识库仓可以用 `"block"`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 边界(必须说清)
|
||||
|
||||
| 问题 | T1 能不能 |
|
||||
|------|----------|
|
||||
| 模型刚改完,描述还成立吗 | ✅ 能(核心场景) |
|
||||
| 昨天有人改了代码,今天打开才发现描述过期 | ❌ 不能(`diff` 里没有,那是 T2 的活) |
|
||||
| 从别处复制粘贴一段代码带来的旧标签 | ❌ 不能(无历史) |
|
||||
| 描述写得笼统、无法证伪 | ❌ 不能(L1 也不查) |
|
||||
|
||||
**T1 的定位**:保证"**改动者当场被问一次**"。
|
||||
它不保证"整个仓库始终新鲜"——后者需要 T2/T3,是可选增强,不进默认路径。
|
||||
|
||||
---
|
||||
|
||||
## 9. 与你担心的「疲劳」对照
|
||||
|
||||
| 场景 | 扫描式(每轮全量) | **T1(本机制)** |
|
||||
|------|------------------|-----------------|
|
||||
| 模型一轮看到几条 | 全仓库 N 条 | **0–2 条** |
|
||||
| 5 轮累计 | N × 5 | **≤ 2** |
|
||||
| 同一标签重复 | 每轮重复 | **一次** |
|
||||
| 未修复的旧债 | 每轮都提 | 不再提(等它被改到时再说) |
|
||||
| 模型需要记住"我之前看过" | 需要 | **不需要**(自包含) |
|
||||
| 需要 VCS / 台账 | 常需要 | **不需要** |
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你确认
|
||||
|
||||
1. **接受"T1 = 编辑期诊断,不是 lint 警告"这个定位吗?**(这是整个防疲劳论证的支点)
|
||||
2. `check_labels` 默认值:`false`(零开销)还是 `true`(修复回路默认开)?
|
||||
3. 漏掉的兜底:用**循环预算**(不强制)还是**可选阻塞**(`"block"`)为默认?
|
||||
4. 会话末汇总要不要做?(一次性总数,不逐条)
|
||||
|
||||
> 若你确认,P1 的第一步就很小:给 `repair_apply` 加 `check_labels`,
|
||||
> 在 `apply_edits` 之后解析两版、比较标签指纹,把结果挂在响应里。
|
||||
> 文档零改动、状态零新增、不依赖 git——**第一天就不会有任何存量警告**。
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
||||
| 相关 | [view.md](view.md) · [view-static-interactive.md](view-static-interactive.md)(静态交互 / 公式代码视觉 · Proposal) · 源目录 [`public/`](../../public/) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# \(V_{\mathsf{safe}}\) JSON integer contract (host ↔ Lean)
|
||||
|
||||
Canonical Lean model: `MarqdoThesis/PLDI/proofs/MarqdoProof/MarqdoProof/ForeignJSON.lean`.
|
||||
Host mapper: `src/host/json.rs` (`json_to_value` / `value_to_json`).
|
||||
|
||||
This document freezes **runtime conformance** of the Marqdo JSON bridge to the
|
||||
mechanized \(V_{\mathsf{safe}}\) integer domain. It is **not** a verified
|
||||
compilation of the Rust interpreter.
|
||||
|
||||
## Domain
|
||||
|
||||
```
|
||||
MAX_SAFE = 9007199254740991 # 2^53 - 1
|
||||
```
|
||||
|
||||
\(V_{\mathsf{safe}}\) values (mechanized):
|
||||
|
||||
| JSON | Marqdo |
|
||||
|---|---|
|
||||
| `null` | `None` |
|
||||
| `bool` | `Bool` |
|
||||
| integer with `\|n\| ≤ MAX_SAFE` | `Int` |
|
||||
| `string` | `Text` |
|
||||
| `array` | `List` |
|
||||
| `object` | `Map` |
|
||||
|
||||
**Host extension (not in Lean `SafeVal`):** JSON non-integer numbers → `Value::Num(f64)` (NaN/Inf encode as `null`). Floats are documented host behavior; they are **not** claimed as mechanized \(V_{\mathsf{safe}}\) fidelity.
|
||||
|
||||
## Encode (`value_to_json`)
|
||||
|
||||
- `Value::Int(n)` with `|n| ≤ MAX_SAFE` → JSON number.
|
||||
- `Value::Int(n)` with `|n| > MAX_SAFE` → **refuse** (error).
|
||||
- Nested `List` / `Map`: any child refuse fails the whole tree.
|
||||
- Wide integers that must cross a language boundary: author converts to a
|
||||
**decimal string** (∈ \(V_{\mathsf{safe}}\)); the foreign program may use
|
||||
`BigInt` / Python `int` on that string.
|
||||
|
||||
## Decode (`json_to_value`)
|
||||
|
||||
- JSON integer with `|n| ≤ MAX_SAFE` → `Int`.
|
||||
- JSON integer with `|n| > MAX_SAFE` → **refuse**.
|
||||
- JSON unsigned integer `> i64::MAX` → **refuse** (do **not** coerce via `f64` or `Text`).
|
||||
- Nested array/object: any child refuse fails the whole tree.
|
||||
- Decimal-string encodings of wide integers → `Text` (in domain).
|
||||
|
||||
## Error prefix
|
||||
|
||||
All refuse messages use a fixed prefix for probes and diagnostics:
|
||||
|
||||
```
|
||||
json: integer outside V_safe (±(2^53-1)): <n>
|
||||
```
|
||||
|
||||
## In-domain roundtrip
|
||||
|
||||
`±MAX_SAFE`, bool, null, string, array, and object roundtrips through
|
||||
`encode → decode` must succeed. Integers `MAX_SAFE+1`, `-MAX_SAFE-1`, `2^53`,
|
||||
`2^60`, `2^60+1` (and nested forms) must refuse.
|
||||
|
||||
## Non-claims
|
||||
|
||||
- Not verified Rust ↔ Lean compilation.
|
||||
- Not arbitrary host-object fidelity (DataFrame, functions, heap sharing).
|
||||
- Not automatic BigInt promotion inside Node/Python bootstraps.
|
||||
- Document-level `Value::Int` may still hold i64 values that are OOD for JSON;
|
||||
the gate fires when those values enter JSON encode/decode.
|
||||
@@ -4,14 +4,14 @@
|
||||
|---|---|
|
||||
| 状态 | **v1(独立 debug 页)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [view-document-annotations.md](view-document-annotations.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
|
||||
## 分工
|
||||
|
||||
| 命令 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
||||
| `marqdo view` | 文档浏览器:**叙述保真文档面** Structure + Execution + Source;函数大纲与搜索;跑后引出标注;**无断点**(见 [view-document-annotations.md](view-document-annotations.md)) |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;AST Structure + BP;**仅 live** |
|
||||
|
||||
静态 `gh-pages` / `view output` **不能**真断点。
|
||||
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
# View:文档面与结果引出标注
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [view-prose-annot-gaps.md](view-prose-annot-gaps.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 是叙述与程序的同一载体。`marqdo view` 的 Structure 必须**保真叙述**,并在可执行标记旁展示运行结果。
|
||||
|
||||
旧 Browse Structure 用 AST 卡片重建语句,并用 `emit_comments` 只插入**语句行之前**的注释。当叙述与 `**…**` / `*…*` / `` `名` `` 在同一行时,该行被 Stmt 占用,叙述被丢弃——信息密度接近 debug,不适合文档浏览。
|
||||
|
||||
## 2. 模式分工
|
||||
|
||||
| 命令 | Structure | 叙述 | 结果 |
|
||||
|------|-----------|------|------|
|
||||
| `marqdo view`(Browse) | **文档面** | 保留并为主 | 跑后引出标注(callout + CSS L-leader) |
|
||||
| `marqdo debug` | AST 卡片 + BP gutter | 弱化/可折叠 | Variables / 步进;不做文档 callout |
|
||||
|
||||
断点与逐步执行**仅**在 debug。静态 `view output` 与 live view **共用** Browse 文档面渲染。
|
||||
|
||||
## 3. 视觉语法
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注
|
||||
```
|
||||
|
||||
1. 叙述正文正常排版(Markdown)。
|
||||
2. 可执行片段高亮,并带底部分割线(underline)。
|
||||
3. 段落下方 **annotation band** 放结果 callout。
|
||||
4. **CSS L-leader**(绝对定位小盒 + `border-left` + `border-bottom`)连接锚点与 callout。**不使用 SVG。**
|
||||
5. 拥挤 / 极窄屏 / `prefers-reduced-motion`:取消长横折,改为编号 keyed 列表。
|
||||
|
||||
关联强度(递减):同色 underline + callout 色条 + label → CSS L-leader → keyed 编号。
|
||||
|
||||
对齐 [view.md](view.md) HIG:系统字体、无外链、浅色、克制装饰。
|
||||
|
||||
## 4. 文档面渲染
|
||||
|
||||
实现:`src/view/document.rs`;Browse 入口经 `render_module_structure` 调用。
|
||||
|
||||
| 源内容 | 呈现 |
|
||||
|--------|------|
|
||||
| 纯叙述段 | Markdown HTML;无 `comment` badge / 厚卡片 |
|
||||
| 含 `ProseBit` 的行 | 原文保留;Decl / BoldCode / ItalicReturn 包 `mark.mq-anchor`(字节偏移来自 `scan_prose_line`) |
|
||||
| 整行结构(`#` / `>` / `-` / `1.` / 表) | 表面语法保真(见 [view-markup-surface.md](view-markup-surface.md));整句可作锚点 |
|
||||
| 函数标题 | 轻量 heading + `id="fn-{line}"`(大纲跳转不变) |
|
||||
|
||||
Debug 仍走 `render_module_structure_mode(..., Debug)` 的 AST 卡片路径。
|
||||
|
||||
## 5. ViewAnnot
|
||||
|
||||
跑后(或 `--no-exec` 时为空)组装标注集,嵌入文档面 `data-*` 与 band HTML。
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `id` | 稳定短 id(页内唯一) |
|
||||
| `kind` | `bind` · `return` · `call` · `expr` · `branch` · `loop` · `writeback` |
|
||||
| `anchor_line` | 1-based 源行 |
|
||||
| `anchor_byte_start` / `anchor_byte_end` | 行内字节范围(可选;整行锚点可省略 end) |
|
||||
| `label` | 短标题(名 / return / arm / loop) |
|
||||
| `value` | 截断显示 |
|
||||
| `detail` | 完整文本(inspect) |
|
||||
|
||||
| kind | 数据来源 | 锚点 |
|
||||
|------|----------|------|
|
||||
| `bind` | **StmtEvent post-stmt**(赋值执行后的值);禁止用入口终态回填初始化行 | 该赋值行 |
|
||||
| `return` | 返回事件或入口返回 | ItalicReturn / Return |
|
||||
| `call` / `expr` / `writeback` | writeback 槽、调用摘要 | 语句行或 BoldCode |
|
||||
| `branch` | `ViewTrace`:命中 arm、次数 | 条件 / arm |
|
||||
| `loop` | `ViewTrace`:迭代次数、末次 item | While / ForEach 头 |
|
||||
|
||||
标记面、结构块、多调用帧与 AI JSON 见 [view-execution-trace.md](view-execution-trace.md)。
|
||||
|
||||
`ViewTrace` 由 tree 解释器在 capture 时静默收集,**不**写入 stderr;与 `trace_eval` 调试轨迹分离。Bytecode 后端可暂无 trace(标注降级为 writeback)。
|
||||
|
||||
## 6. 布局与密度
|
||||
|
||||
- 每段默认最多 **4** 个常显 callout;其余 hover / 「show more」。
|
||||
- Leader:按锚点 x 排序 callout,避免交叉;窄屏改为短竖线 + 堆叠。
|
||||
- 客户端:`ResizeObserver` 重算 leader 盒的 `left/top/width/height`。
|
||||
- 静态导出:页载 JS 跑一次布局。
|
||||
|
||||
右侧 **Variables** 仍为全集绑定;callout 为就地摘要,点击可打开同一 inspect。
|
||||
|
||||
## 7. 非目标
|
||||
|
||||
- 不在 view 内做断点 / 单步(见 [view-debug.md](view-debug.md))。
|
||||
- 不新增作者侧标注 DSL / frontmatter 指令。
|
||||
- 不引入外链字体、npm 组件或 SVG leader。
|
||||
- 不把 DB/auth 等塞进 view 壳层。
|
||||
|
||||
## 8. 验收
|
||||
|
||||
1. `inc-prose.mq.md`:叙述「对于输入变量…」完整可见;`n` / `n=n+1` / 返回高亮。
|
||||
2. 跑完后:值经 underline + CSS L-leader 连到下方标注(无 SVG)。
|
||||
3. 分支/循环样例:可见命中 arm 与迭代次数(有 ViewTrace 时)。
|
||||
4. `marqdo debug` 仍为 AST + 断点;叙述不抢主视觉。
|
||||
5. 无外链字体/新依赖;`view output` 可离线打开。
|
||||
|
||||
## 9. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:文档面、ViewAnnot、CSS L-leader、与 debug 分工 |
|
||||
| 2026-10-15 | bind = post-stmt;交叉链 view-execution-trace |
|
||||
@@ -0,0 +1,103 @@
|
||||
# View:执行轨迹与文档面保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [view.md](view.md) · [view-markup-surface.md](view-markup-surface.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`marqdo view` Browse Structure 必须同时做到:
|
||||
|
||||
1. **标记面**:变量名 / 可执行语句 / 返回值按表面渲染(无源码定界符字面量)。
|
||||
2. **结构块**:GFM 表、循环(`-`)、分支(`1.`)有正确 HTML 与缩进。
|
||||
3. **语句后值**:赋值行标注该语句执行后的值,不用入口终态回填。
|
||||
4. **执行臂**:高亮实际走的分支臂。
|
||||
5. **多调用帧**:同函数多次调用可用下拉切换经历。
|
||||
6. **AI 可读**:与 HTML 同源的 `ViewExecutionReport` JSON。
|
||||
|
||||
Debug 仍用 AST 卡片 + 断点;不做文档 callout。
|
||||
|
||||
## 2. 标记面
|
||||
|
||||
| 源标记 | 显示(无定界符) | class |
|
||||
|--------|------------------|-------|
|
||||
| `` `名` `` / `` `名`=默认 `` | `名`(默认次要后缀) | `mq-anchor mq-decl` |
|
||||
| `**…**`(可执行) | 内层文本 | `mq-anchor mq-code` |
|
||||
| `*…*`(返回) | 内层文本 | `mq-anchor mq-return` |
|
||||
|
||||
`data-byte-start/end` 仍为源码字节偏移(供 CSS L-leader)。软强调不进 anchor。
|
||||
|
||||
## 3. 结构块
|
||||
|
||||
| 块 | 呈现 |
|
||||
|----|------|
|
||||
| GFM 表 | `<table class="doc-table">` |
|
||||
| `-` 循环 | `<ul class="doc-loop">`,体按源缩进 `--doc-indent` |
|
||||
| `1.` 分支 | `<ol class="doc-branch">`;命中 `arm-taken`,未走 `arm-miss` |
|
||||
| 公式 / 外联代码 | 现有 formula-card / code-card |
|
||||
| `>` 调用 | 表面高亮,非整行灰 code |
|
||||
|
||||
## 4. StmtEvent / CallFrame
|
||||
|
||||
解释器 capture 时静默采集(非 `trace_eval` stderr):
|
||||
|
||||
```text
|
||||
StmtEvent {
|
||||
line, kind, // assign | return | call | branch | loop | bind_ref
|
||||
name?, value_after?, // post-stmt 或求值结果
|
||||
arm_index?, iter?,
|
||||
call_id // 当前用户函数调用帧
|
||||
}
|
||||
|
||||
CallFrame {
|
||||
call_id, fn_name, fn_line, ordinal,
|
||||
args_brief, // 短摘要供下拉
|
||||
events[] // 或全局 events 用 call_id 过滤
|
||||
}
|
||||
```
|
||||
|
||||
- Assign → 写入后的值挂在**该行**。
|
||||
- 循环内多次写入:UI 默认末次;可带次数。
|
||||
- Branch → taken `arm_index` + 条件摘要。
|
||||
- 进入用户函数分配 `call_id`;`# main` 单帧无下拉。
|
||||
|
||||
## 5. ViewExecutionReport(AI)
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"path": "…",
|
||||
"ok": true,
|
||||
"calls": [{ "call_id": 1, "fn": "等级说明", "ordinal": 1, "args_brief": "等级=及格" }],
|
||||
"events": [{ "line": 24, "kind": "assign", "name": "总分", "value_after": "0", "call_id": 0 }],
|
||||
"bindings_final": { "均分": "73", "等级": "及格" }
|
||||
}
|
||||
```
|
||||
|
||||
产出:页内 `#mq-view-trace` JSON;live `GET /api/view-trace?path=`;SSE `done.trace_json`。
|
||||
|
||||
## 6. UI
|
||||
|
||||
- 函数标题旁 `<select class="call-picker">`(调用数 ≥ 2)。
|
||||
- 循环头旁 `<select class="loop-picker">`(迭代数 ≥ 2);默认最后一轮;摘要 `分 = 分数表[i] · value`。
|
||||
- **源码常显**:切换帧只改 chip / 臂高亮,不 `hidden` 结构节点。详见 [view-frame-selection.md](view-frame-selection.md)。
|
||||
- CSS L-leader(非 SVG);拥挤 keyed 降级。
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. 无字面 `**` / 返回定界 `*` / 变量外层 `` ` ``(Source 除外)。
|
||||
2. 表为真表格;循环/分支有缩进列表;未选中臂源码仍可见。
|
||||
3. `总分 = 0` 标注 `0`,非终态累加。
|
||||
4. 命中臂可视化;多调用下只显示当前帧的 taken。
|
||||
5. 循环可按迭代切换;JSON 含 `loops`;单测覆盖。
|
||||
|
||||
## 8. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:标记面、结构块、StmtEvent、CallFrame、AI 报告 |
|
||||
| 2026-10-15 | 帧选择保真:call_id 分支、LoopFrame、源码常显 |
|
||||
@@ -0,0 +1,123 @@
|
||||
# View:调用帧 / 循环帧选择与结构保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-execution-trace.md](view-execution-trace.md) · [view-document-annotations.md](view-document-annotations.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题(对照实测)
|
||||
|
||||
1. **结构缺失**:切换函数调用下拉时,JS 按 `data-call-id` **隐藏** `.doc-exec`。未在本帧执行的分支臂体(赋值/返回)只有其它帧的 call_id,或仅有执行帧的 id → **未选中臂的源码被藏掉**,看起来像「臂消失 / 代码没渲染」。
|
||||
2. **调用记录混叠**:`Branch` 标注未带 `call_id`;`taken_arms` 按行号只保留最后一次命中。多帧下同一分支同时出现 `arm 1 taken` 与 `arm 2 taken`。
|
||||
3. **循环无帧**:循环只有总次数摘要;无法按迭代查看;`` - [分](分数表) `` 不能展示「当前是集合第几个元素」。
|
||||
|
||||
## 2. 定稿原则
|
||||
|
||||
| 原则 | 含义 |
|
||||
|------|------|
|
||||
| **源码常显** | 表 / 列表 / 分支臂 / 语句源码**永不**因帧选择 `hidden` |
|
||||
| **轨迹随帧** | 标注 chip、臂高亮、变量值随「当前调用帧 / 当前迭代」变化 |
|
||||
| **默认末帧** | 函数默认最后一次调用;循环默认最后一次迭代 |
|
||||
| **一帧一真相** | 同时只展示一个 call_id(函数)或一个 (loop_id, iter)(循环)的轨迹 |
|
||||
|
||||
## 3. 函数调用帧
|
||||
|
||||
### 数据
|
||||
|
||||
`BranchHit` / 相关 `StmtEvent` 必须带 `call_id`。`ViewAnnot` 的 branch/bind/return 同样带 `call_id`。
|
||||
|
||||
### UI
|
||||
|
||||
- 函数标题旁 `<select class="call-picker" data-fn="…" data-scope="fn">`
|
||||
- 选项:`1: 等级=及格` / `2: 等级=优秀`
|
||||
- 默认选中最后一次
|
||||
|
||||
### 客户端(`applyCallFrame`)
|
||||
|
||||
1. 读 `#mq-view-trace` JSON。
|
||||
2. 过滤 `events` where `call_id == selected`。
|
||||
3. **不**设置结构节点 `hidden`。
|
||||
4. 更新该函数作用域内:
|
||||
- `.annot-chip[data-call-id]`:仅显示匹配帧;无 call_id 的结构说明类可保留
|
||||
- `.doc-branch[data-line]`:按该帧的 branch 事件设置 `arm-taken` / `arm-miss`(全部臂仍可见)
|
||||
- 绑定 chip 的 `.annot-value`:用该帧 assign/return 事件刷新(同名同行取末次)
|
||||
|
||||
## 4. 循环迭代帧
|
||||
|
||||
### 数据
|
||||
|
||||
```text
|
||||
LoopFrame {
|
||||
loop_id, line,
|
||||
item_name?, // "分"
|
||||
collection?, // "分数表"
|
||||
iterations: [{ index, item_value, call_id }] // index 0-based
|
||||
}
|
||||
```
|
||||
|
||||
`StmtEvent` 增加可选 `loop_id`;循环体内事件带 `iter`(1-based 或 0-based,JSON 内统一 **0-based index**)。
|
||||
|
||||
### UI
|
||||
|
||||
- 循环头(`- [分](分数表)`)旁:`<select class="loop-picker" data-loop-id="…">`
|
||||
- 选项:`迭代 1: 分=92` … `迭代 4: 分=88`
|
||||
- 默认最后一次
|
||||
- 头旁摘要 chip:`分 = 分数表[3] · 88`(下标 0-based 显示为 `[i]`)
|
||||
|
||||
### 客户端(`applyLoopFrame`)
|
||||
|
||||
1. **只显示当前迭代**:带 `data-iter` 的 chip 仅保留选中项;其余 `hidden` + `is-frame-hidden`(SSR 默认已按末轮预隐藏)。
|
||||
2. 更新头摘要 chip(无 `data-iter`)为当前选项文案。
|
||||
3. 不隐藏循环体源码。
|
||||
|
||||
## 5. 分支臂渲染
|
||||
|
||||
- 所有臂(含 else)**始终**渲染完整头 + 体(含 `*返回*` / 赋值)。
|
||||
- `arm-miss` 仅降低不透明度,**不** `display:none` / `hidden`。
|
||||
- 高亮仅反映**当前帧**的 taken `arm_index`。
|
||||
|
||||
## 6. AI JSON 增量
|
||||
|
||||
`ViewExecutionReport` 增加:
|
||||
|
||||
```json
|
||||
"loops": [{
|
||||
"loop_id": 1,
|
||||
"line": 27,
|
||||
"item": "分",
|
||||
"collection": "分数表",
|
||||
"iters": [{ "index": 0, "value": "92" }, { "index": 3, "value": "88" }]
|
||||
}]
|
||||
```
|
||||
|
||||
`events[].call_id` 必填;循环体内事件带 `loop_id` + `iter`(index)。
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. 未选中分支臂源码始终可见(含返回句)。
|
||||
2. 切换「等级说明」调用:只显示该帧的 arm taken;变量/返回值对应该帧。
|
||||
3. 循环下拉默认最后一轮;`分 = 分数表[3] · 88`;切换迭代后体内累加值变化。
|
||||
4. `#mq-view-trace` 含 `loops` 与带 `call_id` 的 branch 事件。
|
||||
5. `cargo test --lib view::` 全绿。
|
||||
|
||||
## 8. 开发计划(已执行)
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| D0 | 本文档 + `view-execution-trace.md` 交叉引用 | ✅ |
|
||||
| D1 | `BranchHit.call_id`;`LoopFrame` / `LoopIter`;`StmtEvent.loop_id` | ✅ |
|
||||
| D2 | 解释器:foreach/while 推栈;BindRef `分=分数表[i]`;assign 带 iter | ✅ |
|
||||
| D3 | `build_view_annots`:分支带 call_id;LoopFrame 选项;报告 JSON `loops` | ✅ |
|
||||
| D4 | 文档面:源码不贴 `data-call-ids`;call picker `value=call_id`;loop picker;SSR taken=末帧 | ✅ |
|
||||
| D5 | JS:`applyCallFrame` / `applyLoopFrame` — 只滤 chip + 重算 arm,不 hidden 结构 | ✅ |
|
||||
| D6 | 单测:多调用不同臂、loop 末项、HTML 三臂返回 + picker | ✅ |
|
||||
|
||||
## 9. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:源码常显、帧过滤、循环迭代 picker |
|
||||
| 2026-10-15 | 按计划落地 D1–D6 |
|
||||
@@ -0,0 +1,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,145 @@
|
||||
# View:叙述面标注缺口(prose annot gaps)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [view-frame-selection.md](view-frame-selection.md) · [view-execution-trace.md](view-execution-trace.md) |
|
||||
|
||||
> **定位**:对既有文档面设计的**缺口专章**——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何「改了却几乎没变化」
|
||||
|
||||
| 原因 | 说明 |
|
||||
|------|------|
|
||||
| 错二进制 | PATH 上的 `marqdo` 可能仍是旧版(如 1.3.0);改动在源码 / `./target/debug/marqdo`。验收必须用 `cargo build && ./target/debug/marqdo view …` |
|
||||
| Chip 被溢出藏掉 | 同 band 堆多帧 return/print/who;`MAX_VISIBLE_ANNOTS=4` 把当前帧的 `who` 打成 `annot-chip-overflow`(`display:none`);帧切换不重算溢出 |
|
||||
| L-leader 几何错位 | `initAnnotLeaders` 里 `y0=0` 只在 `.annot-band` 顶画短折,**连不到**上方 underline;窄屏或 chip>4 时整段关掉 leaders |
|
||||
| 旧静态快照 | gh-pages / 旧 `view output` 不会自动刷新 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标视觉语法(既有,不新造)
|
||||
|
||||
锚定 [view-document-annotations.md](view-document-annotations.md) §3:
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注 chip
|
||||
```
|
||||
|
||||
- underline:`mark.mq-anchor.mq-{decl|code|return}`
|
||||
- band:段落下方 `.annot-band` → leaders + chips
|
||||
- L-leader:CSS `border-left` + `border-bottom`(禁止 SVG)
|
||||
- 公式/代码:[view-static-interactive.md](view-static-interactive.md) G3 **一层主视觉**;卡下不叠 Bind dump
|
||||
- 帧:[view-frame-selection.md](view-frame-selection.md) **源码常显、只滤 chip**;默认末帧
|
||||
|
||||
---
|
||||
|
||||
## 3. 管线
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
CLI["marqdo view / view output"] --> build["build_file_view"]
|
||||
build --> cap["run_file_capture"]
|
||||
cap --> annot["build_view_annots"]
|
||||
annot --> doc["document::render_module_document"]
|
||||
doc --> page["html.rs page_file"]
|
||||
page --> js["initAnnotLeaders + initCallPickers"]
|
||||
```
|
||||
|
||||
| 步骤 | 位置 |
|
||||
|------|------|
|
||||
| CLI / 导出 | `src/main.rs` · `src/view/mod.rs` · `src/view/output.rs` |
|
||||
| Capture + Call 事件 | `src/interp.rs` |
|
||||
| Annot 组装 | `src/view/annot.rs` `build_view_annots` |
|
||||
| 文档面 HTML | `src/view/document.rs` |
|
||||
| 卡片 chrome | `src/view/render.rs` `render_*_assign_card` |
|
||||
| CSS / leader JS | `src/view/html.rs` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 四条用户问题 → 根因 → 验收
|
||||
|
||||
复现源:`public/00-welcome.mq.md` · `public/00-欢迎.mq.md`
|
||||
对照金样:`tests/view/document-annot-demo.mq.md` · `tests/markup-v03/inc-prose.mq.md`
|
||||
|
||||
### P1 — 叙述与代码同段时信息不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | underline 在,chip / 连线弱或无 |
|
||||
| 根因 | `html.rs` `initAnnotLeaders`:`y0=0` 相对 band;`document.rs` `MAX_VISIBLE_ANNOTS` 把当前帧 chip 溢出;PATH 旧 CLI |
|
||||
| 目标 | 同 `inc-prose`:underline + L-leader(从锚点底到 chip)+ 可见 chip |
|
||||
| 验收 | `./target/debug/marqdo view public/00-welcome.mq.md`:主文 `**greet…**` 与 `## greet` 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
|
||||
|
||||
### P2 — 函数内变量不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `` `who` `` 有浅蓝 underline,无值 chip |
|
||||
| 根因 | bind chip 存在但带 `annot-chip-overflow`;`applyCallFrame` 只 `hidden` 非选中帧,不解除当前帧 overflow |
|
||||
| 目标 | 选中调用帧时常显 `who` · `print` · `return` 各一枚 |
|
||||
| 验收 | 切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
|
||||
|
||||
### P3 — ` ```text ` 渲染不一致
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 变成内联 `text marqdo ext add…`,无卡片 |
|
||||
| 根因 | Comment 围栏若进 `flush_para` → `join(" ")` → pulldown 当 inline code;应走 `render_narrative_fence` |
|
||||
| 目标 | 与 bound python 同 `.code-card` chrome(badge + `pre.code-body`),**无** Run/foot |
|
||||
| 验收 | welcome install 段:`data-lang="text"` + 两行 `marqdo ext add`;无 `<code>text marqdo` |
|
||||
|
||||
### P4 — 函数引用 / 代码卡未渲染
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `**greet who=…**` 无结果;或 `hi` python 只见头/Run、不见源码 |
|
||||
| 根因 | 同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
|
||||
| 目标 | 主文两 greet 各有 call chip(stdout 摘要);`hi` = `render_code_assign_card` head→body→foot;静态藏 Run |
|
||||
| 验收 | 两枚 greet mark 均有非空 `data-annot-id`;`code-body` 含 `hello-from-python`;`MARQDO_VIEW_LIVE=false` 无 Run 按钮 |
|
||||
|
||||
### call_id 语义(写死)
|
||||
|
||||
| 位置 | call_id |
|
||||
|------|---------|
|
||||
| 主文 `**greet…**` 的 call chip | 入口帧(`# main` 的 call);结果为 stdout/返回摘要 |
|
||||
| `## greet` 体内 print / who / return | callee 的 CallFrame id;跟函数标题旁 picker |
|
||||
|
||||
---
|
||||
|
||||
## 5. 修复约定(实现红线)
|
||||
|
||||
1. **帧感知密度**:band 内按选中 `call_id` 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + `layoutAll()`。
|
||||
2. **Leader 容器**:提升到 `.doc-block`(prose + band);`y0` = 锚点底相对 block;按锚点 x 排序再画线。
|
||||
3. **卡片**:只复用 Browse `render_*_assign_card` / `render_narrative_fence` + `html.rs` `.code-*` / `.formula-card`;本波不改 Debug AST 路径(除非回归红)。
|
||||
4. **静态 Run**:`MARQDO_VIEW_LIVE=false` 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
|
||||
5. **非目标**:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收命令
|
||||
|
||||
```bash
|
||||
cargo build -q
|
||||
./target/debug/marqdo version # 须为当前工作树版本
|
||||
./target/debug/marqdo view public/00-welcome.mq.md --no-open
|
||||
./target/debug/marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
cargo test -q --lib view::
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
|
||||
| 2026-10-15 | L-leader 拥挤/消失:同跨度多帧 chip **共用 annot id**;可见 chip 按锚点 x 重排;leader 挂 doc-block |
|
||||
| 2026-10-15 | L-leader 黑线碎段:JS `border*: "1.5px solid"` 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
|
||||
| 2026-10-15 | L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |
|
||||
Loaded 100 of 1022 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user