Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
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 | ||
|
|
46a0263d7f | ||
|
|
ff252fd469 | ||
|
|
67bac1bf02 | ||
|
|
33f8b94bb0 | ||
|
|
0ed57b6d54 | ||
|
|
c29d48f38c | ||
|
|
f1e82ce4e5 | ||
|
|
2d412e3bba | ||
|
|
46d78c6e15 | ||
|
|
81a14f9b38 | ||
|
|
88dc6d5a54 | ||
|
|
4a2d89406b | ||
|
|
d8d435fead | ||
|
|
1f8e61f3bf | ||
|
|
a9ee858f53 | ||
|
|
8489d90926 | ||
|
|
5272acaea0 | ||
|
|
cba51238b6 | ||
|
|
5fffb800f9 | ||
|
|
1a729eb9ec | ||
|
|
00c763300e | ||
|
|
224b3d4a66 | ||
|
|
81d26a265a | ||
|
|
5b599125d1 | ||
|
|
18d89d6cf2 | ||
|
|
199b5c532f | ||
|
|
db5f0e830b | ||
|
|
7a449c40b1 | ||
|
|
97fda7aa10 | ||
|
|
a49592a3ba | ||
|
|
ed9ac03c0c | ||
|
|
cb46ad7abe | ||
|
|
586975090b | ||
|
|
544805266b | ||
|
|
f3051fb536 | ||
|
|
86b183e2d7 | ||
|
|
8e23a5395a | ||
|
|
cab609ee91 | ||
|
|
b752cd49b7 | ||
|
|
2c91b5cc7b | ||
|
|
453321c8c2 | ||
|
|
981d754133 | ||
|
|
410f36f719 | ||
|
|
bd06aedb90 | ||
|
|
42ddeb14e7 | ||
|
|
6bd127a313 | ||
|
|
4b7643d833 | ||
|
|
3f96592c99 | ||
|
|
98018fc63b | ||
|
|
aeac4d6d20 | ||
|
|
9e9a80df31 | ||
|
|
5f07b1c3b1 | ||
|
|
bfea2204eb | ||
|
|
fb30cd3db3 | ||
|
|
584cb9ac9d | ||
|
|
428ee141e1 | ||
|
|
ec9718466d | ||
|
|
c5bb08022a | ||
|
|
b710745e88 | ||
|
|
5cf84fe9b7 | ||
|
|
27991a7822 | ||
|
|
d1e2f0ced0 | ||
|
|
e848306187 | ||
|
|
2ee9d7e66d | ||
|
|
e31585842d | ||
|
|
f068b4ab75 | ||
|
|
26e29409a9 | ||
|
|
4923129d10 | ||
|
|
8ab55e2193 | ||
|
|
9bc7ef3b5a | ||
|
|
9431ad835c | ||
|
|
2984d7d4f8 | ||
|
|
6324036e41 |
No files matched your search
@@ -0,0 +1,26 @@
|
||||
---
|
||||
description: Marqdo Web Artifact — no degradation; Document/Endpoint/Resource only
|
||||
globs: ext/web/**,ext/net/**,ext/data/**,ext/security/**,examples/**/*,tests/ext/web*,doc/design/ext-web*,doc/adr/0007*
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Web Artifact — 不允许降级
|
||||
|
||||
Canonical: `doc/adr/0007-web-document-endpoint.md` · `doc/design/ext-web-artifact.md` · `doc/next/007.md` (superseded).
|
||||
|
||||
## Hard bans
|
||||
|
||||
1. **Do not** restore or reintroduce author-facing `compose_main` / `compose_intro` / `compose_*` fragmented table DSLs, god `# page` mutation piles, or `app.configure(...)` junk-drawer APIs.
|
||||
2. **Do not** use `json.set` / `json.append` bag glue for pages, routes, or middleware. Tables = data. View schema is only `|type|slot|value|attrs|style|` (ZH aliases allowed).
|
||||
3. **Do not** call `ensure_plugin` or `host_*` from author programs or from `ext/**` (plugin load is facade/capability only).
|
||||
4. **Do not** register implicit user routes. Declared routes come from Artifact metadata or `web.route`. System routes (`/_part`, `/_form`, …) must appear in `web.inspect`.
|
||||
5. **Do not** invent DSL, nested frontmatter under `##`, or new table dialects when the design is silent — **stop and ask**.
|
||||
6. **Do not** mix EN/ZH API names in one `.mq.md`.
|
||||
7. **Do not** silently delete capabilities. Removals require design text + tests updated in the same change.
|
||||
8. **Do not** put DB/auth/cache/storage/websocket author APIs back into `ext/web/web.mq.md` — they live in `ext/data`, `ext/security`, `ext/net`.
|
||||
|
||||
## Required direction
|
||||
|
||||
- Document (`type: web` / `类型: 网页`), Endpoint (`type: endpoint` / `类型: 端点`), Resource modules.
|
||||
- Facade only: `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect` (ZH mirrors).
|
||||
- Code is documentation: the `.mq.md` is the page/API docs and the implementation.
|
||||
@@ -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: `ext/web` + GFM page/style tables.
|
||||
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`.
|
||||
|
||||
## Developing libraries (`lib/*`, `ext/*`)
|
||||
|
||||
@@ -121,7 +173,9 @@ Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code
|
||||
| Need | Place |
|
||||
|------|--------|
|
||||
| Browser effect maps (WASM client) | `lib/browser.mq.md` |
|
||||
| Site HTML / HTTP / DB | `ext/web` classes + compose from tables |
|
||||
| Site HTML / HTTP | `ext/web` Document/Endpoint + View tables |
|
||||
| DB / cache / storage | `ext/data` |
|
||||
| Auth / OIDC / RBAC | `ext/security` |
|
||||
| List/map primitives | `lib/table.mq.md` |
|
||||
| Parse JSON text | `lib/json.mq.md` only |
|
||||
|
||||
@@ -150,3 +204,18 @@ When editing a file full of `json.set`:
|
||||
- Tables: `doc/design/stdlib-table.md` · `doc/design/table-cell-expressions.md`
|
||||
- Browser effects: `doc/roadmap/browser-wasm-e.md` · `doc/roadmap/browser-wasm-f.md`
|
||||
- Release: [marqdo-release](../marqdo-release/SKILL.md)
|
||||
|
||||
## 渐进式契约 + MLSP(Phase 2/3 落地后的开发戒律)
|
||||
|
||||
- **契约实现**:`src/contract.rs`(类型词汇 / 三形状契约表解析 / 合并 / 四边界校验诊断);
|
||||
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行;
|
||||
绑定表与普通文档表绝不吃 ⇒ 无契约文件零回归)。契约表从 body 移除——元数据永不执行。
|
||||
- **静态互查**:`src/check.rs`(`marqdo check [--json]`)——契约行 vs 升参推断形参双向漂移、
|
||||
未知类型名、错位契约;Error ⇒ 非零退出。
|
||||
- **AI 工具面**:`src/mlsp.rs`(`marqdo mlsp`,行分隔 JSON)——`locate` / `syntax` / `validate` /
|
||||
`repair_targets` / `schema`。语法唯一事实来源 = `parse::CORE_CONSTRUCTS`(CI 守卫与
|
||||
`doc/design/core-surface.md` 同步);MLSP 只加检索别名,**不定义语法**。
|
||||
- **准入戒律**:新特性先过 `doc/design/layers.md` 三层归属(Language 层改动须 ADR + core-surface);
|
||||
新契约形状/类型词汇 = 文档层扩展,进 `src/contract.rs`,不进词法/语法。
|
||||
- **错误出口唯一**:`src/load.rs::label_error` 已示范——装载层/任何新代码都**不许**把
|
||||
`Diagnostic` 拍平成字符串;错误链里必须能 `Diagnostic::find` 找回结构化诊断(AI/MLSP 面)。
|
||||
@@ -1,16 +1,14 @@
|
||||
---
|
||||
name: marqdo-release
|
||||
description: >-
|
||||
Run a full Marqdo product release: detect latest version and ask the user for
|
||||
the next tag, update CHANGELOG/README/skills/public docs, bump Cargo versions,
|
||||
sync VS Code extension on branch vscode-extension when needed, build or
|
||||
trigger install assets (Windows CLI + **required Linux native/CLI zips**,
|
||||
stdlib, ext, public zip, VSIX), push via origin or
|
||||
https://proxy.cflmy.top/github.com/cflmy/marqdo.git, publish GitHub Release
|
||||
with detailed notes, and recover from network failures via that proxy or HK
|
||||
SSH jump (scripts/push-via-hk-jump.py). Use when the user asks to release,
|
||||
cut a version, publish vX.Y.Z, ship a GitHub release, 发版, 发布新版本, or tag
|
||||
marqdo.
|
||||
Run a Marqdo product release: detect latest version and ask the user for the
|
||||
next tag (or confirm mode), update CHANGELOG/README/skills/public docs, bump
|
||||
Cargo and/or ext/VERSION, sync VS Code extension when needed, publish GitHub
|
||||
Release assets, upload extension packs to Cloudflare R2 (ext.marqdo.com) and
|
||||
GitHub, ship Ubuntu CLI via PPA (scripts/ppa-ship.sh), and print manual
|
||||
commands when sudo/GPG/network steps need the user. Use when the user asks to
|
||||
release, cut a version, publish vX.Y.Z, ext-only pack, PPA, 发版, 发布新版本,
|
||||
or tag marqdo.
|
||||
---
|
||||
|
||||
# Marqdo release
|
||||
@@ -19,166 +17,193 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg
|
||||
|
||||
## Hard rules
|
||||
|
||||
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`). Do not proceed until they confirm.
|
||||
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`) and **release mode** if unclear. Do not proceed until they confirm (unless they already stated both in the same message).
|
||||
2. **Never force-push** `main` / tags. **Never** `--no-verify` unless the user explicitly orders it.
|
||||
3. **Never commit `vscode-extension/` on `main`** (gitignored). Extension source lives only on branch **`vscode-extension`**. See `doc/design/vscode-extension-commit.md`.
|
||||
4. **Do not release from a dirty tree** (except intentional release commits you create in this flow).
|
||||
5. **Tag format** is always `vX.Y.Z` matching root `Cargo.toml` `version = "X.Y.Z"`.
|
||||
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for **both** Windows and **Linux** install assets. Local packaging is fallback / verification.
|
||||
7. After network errors: apply [reference.md § Proxy](reference.md). **First try** `https://proxy.cflmy.top/github.com/cflmy/marqdo.git` (this clone’s usual `origin`). Retry; do not silently skip uploads. If the reverse-proxy still drops long pushes, use **HK jump** (`hk.cflmy.de`) via `scripts/push-via-hk-jump.py` — see reference § **Proxy** / **HK SSH jump**.
|
||||
8. **Do not ship a GitHub Release without the Linux extension/native zip.** Job `linux` must attach `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` (and the Linux CLI bundle). Missing Linux packages = release incomplete.
|
||||
5. **Tag format:** CLI/full → `vX.Y.Z` matching root `Cargo.toml`. Ext-only → `ext-vX.Y.Z` matching `ext/VERSION` (Cargo may stay unchanged).
|
||||
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for Windows/Linux install assets. Local packaging is fallback / verification.
|
||||
7. After network errors: apply [reference.md § Proxy](reference.md). **First try** `https://proxy.cflmy.top/github.com/cflmy/marqdo.git`. Retry; do not silently skip uploads. If needed: **HK jump** (`scripts/push-via-hk-jump.py`).
|
||||
8. **Do not ship a full GitHub Release without the Linux extension/native zip** when the mode includes ext packs. Missing Linux packages = incomplete for that mode.
|
||||
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.
|
||||
|
||||
## Defaults (after version is confirmed)
|
||||
## Release modes
|
||||
|
||||
Unless the user overrides, apply these automatically — **do not re-ask**:
|
||||
Ask (or take from user message) which mode:
|
||||
|
||||
| Mode | Bumps | Git tag | GitHub assets | R2 CDN | Ubuntu PPA |
|
||||
|------|-------|---------|---------------|--------|------------|
|
||||
| **full** (default) | `Cargo.toml` + `ext/VERSION` (same SemVer) | `vX.Y.Z` | CLI + ext + native + VSIX + … | yes | yes |
|
||||
| **cli** | `Cargo.toml` only | `vX.Y.Z` | CLI (+ optional attach prior ext) | no (unless user asks) | yes |
|
||||
| **ext** | `ext/VERSION` only | `ext-vX.Y.Z` (or attach to latest CLI release) | ext.zip + native-*.zip | **required** | no |
|
||||
|
||||
Defaults after version+mode confirmed — **do not re-ask**:
|
||||
|
||||
| Setting | Default |
|
||||
|---------|---------|
|
||||
| Sync / bump `vscode-extension` to same `VER` | **yes** |
|
||||
| Push `main`, create annotated tag, push tag immediately (trigger CI) | **yes** |
|
||||
| Release notes language | **中英双语** (Chinese first, then English section, or paired ZH/EN under each heading) |
|
||||
| Skip VSIX | **no** |
|
||||
| Docs-only release | **no** (full asset pipeline via CI) |
|
||||
| Sync / bump `vscode-extension` to same `VER` | **yes** for full/cli; **no** for ext-only |
|
||||
| Push `main`, create annotated tag, push tag (trigger CI) | **yes** for full/cli |
|
||||
| Ext packs → R2 **and** GitHub | **yes** whenever ext ships |
|
||||
| Ubuntu PPA upload after CLI tag | **yes** for full/cli |
|
||||
| Release notes language | **中英双语** |
|
||||
| Deploy gh-pages after release | **no** (only if user asks) |
|
||||
|
||||
Phase 0 asks **only** for the next version (and optional overrides). Example ask:
|
||||
Phase 0 ask example:
|
||||
|
||||
> 当前最新是 **vA.B.C**。请指定下一个版本号(如 `0.3.2`)。其余按默认:同步扩展、立刻打 tag 发布、中英双语说明。
|
||||
> 当前最新 CLI **vA.B.C**,扩展包 **E.F.G**。请指定下一个版本号与模式(`full` / `cli` / `ext`,如 `1.0.3 full`)。
|
||||
|
||||
## Phase 0 — Detect versions (mandatory stop)
|
||||
|
||||
Run in repo root (parallel OK):
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
|
||||
# or: rg / git tag / gh release list — see reference.md
|
||||
```
|
||||
|
||||
Report briefly, then **ask only for the next SemVer** (defaults above). Wait for confirmation. Normalize to `VER=X.Y.Z` and `TAG=vX.Y.Z`.
|
||||
Report briefly, then **ask for SemVer + mode** (unless already given). Normalize `VER` / `TAG`.
|
||||
|
||||
## Phase 1 — Preflight
|
||||
|
||||
Copy and track:
|
||||
|
||||
```
|
||||
Release progress:
|
||||
- [ ] Phase 0: version confirmed by user (TAG=…)
|
||||
- [ ] Phase 0: version + mode confirmed
|
||||
- [ ] Phase 1: preflight green
|
||||
- [ ] Phase 2: docs + version bumps committed
|
||||
- [ ] Phase 3: extension branch (if needed)
|
||||
- [ ] Phase 3: extension branch (full/cli)
|
||||
- [ ] Phase 4: main pushed; tag created & pushed
|
||||
- [ ] Phase 5: CI / assets / release notes verified
|
||||
- [ ] Phase 6: post-release checks
|
||||
- [ ] Phase 5: CI / GitHub assets / notes
|
||||
- [ ] Phase 6: R2 upload (if ext ships)
|
||||
- [ ] Phase 7: Ubuntu PPA (full/cli)
|
||||
- [ ] Phase 8: post-release checks
|
||||
```
|
||||
|
||||
Checks:
|
||||
|
||||
1. `git status` clean or only release WIP you control.
|
||||
2. `git checkout main && git pull --ff-only origin main`.
|
||||
3. Quick gate: `cargo test --test gold structure_hello` (and any release-critical tests the user named). Full gold suite if time allows.
|
||||
4. `CHANGELOG.md` has meaningful **Unreleased** notes; if empty, draft from `git log vLAST..HEAD --oneline` and confirm with user.
|
||||
5. Confirm no secrets in the commit (`*.env`, credentials).
|
||||
Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
|
||||
|
||||
## Phase 2 — Docs & version bumps (main)
|
||||
|
||||
Bump **in lockstep**:
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `Cargo.toml` | `version = "VER"` |
|
||||
| `crates/marqdo-wasm/Cargo.toml` | same `VER` |
|
||||
| `CHANGELOG.md` | Move `## Unreleased` → `## vVER — YYYY-MM-DD`; leave fresh empty `## Unreleased` |
|
||||
| `README.md` | 「现状 / 如何使用最新」version strings, checkout tag, release URL |
|
||||
| `.cursor/skills/marqdo/SKILL.md` | Version-sensitive bullets if any (WASM/web status); keep rules accurate |
|
||||
| `public/**` | User-facing tutorials if features shipped (welcome, features/*, extensions). Prefer small factual updates over rewrites |
|
||||
| `doc/roadmap/*.md` | Mark shipped waves done if this release closes them |
|
||||
| `.github/workflows/release.yml` | Update **Highlights** body template to this release (CI still uses hardcoded blurb—keep in sync) |
|
||||
|
||||
Public HTML: regenerate before packaging / pages deploy:
|
||||
| File | full | cli | ext |
|
||||
|------|------|-----|-----|
|
||||
| `Cargo.toml` + `crates/marqdo-wasm/Cargo.toml` | bump | bump | — |
|
||||
| `ext/VERSION` | bump | — | bump |
|
||||
| `CHANGELOG.md` | `## vVER`(含**核心表面 Δ**,见 `doc/design/layers.md`) | same | `## Ext pack vVER` |
|
||||
| `README.md` / `public/**` install + download table | update | update | update ext notes |
|
||||
| `.cursor/skills/marqdo/SKILL.md` | if surface changed | same | rare |
|
||||
| `.github/workflows/release.yml` Highlights stub | yes | yes | — |
|
||||
|
||||
```bash
|
||||
./scripts/build-public.sh
|
||||
# outputs under public/ (gitignored HTML); used by release zip / gh-pages
|
||||
./scripts/build-public.sh # when public/ sources changed
|
||||
```
|
||||
|
||||
Commit on `main` (HEREDOC message), e.g.:
|
||||
|
||||
```text
|
||||
release: vVER — <one-line highlight>
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
Push `main` (this repo’s `origin` is usually the reverse proxy):
|
||||
Commit + push `main` (proxy origin). On push failure → reference § Proxy; if still blocked, **print** for the user:
|
||||
|
||||
```bash
|
||||
# origin typically: https://proxy.cflmy.top/github.com/cflmy/marqdo.git
|
||||
git push origin main
|
||||
# one-shot if origin still points at github.com:
|
||||
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
|
||||
# or: python3 scripts/push-via-hk-jump.py
|
||||
```
|
||||
|
||||
If that times out: [reference § HK SSH jump](reference.md).
|
||||
## Phase 3 — VS Code / Cursor extension (full/cli only)
|
||||
|
||||
## Phase 3 — VS Code / Cursor extension
|
||||
Default: bump `vscode-extension` package.json to `VER`, compile, push branch `vscode-extension`, return to `main`.
|
||||
|
||||
**Default: always** bump extension to `VER` on branch `vscode-extension` (skip only if user said so).
|
||||
|
||||
1. `git fetch origin vscode-extension`
|
||||
2. Work on `vscode-extension` branch (not main):
|
||||
- Bump `vscode-extension/package.json` `version` to `VER`.
|
||||
- Update `engines` / CLI version hints in extension README if present.
|
||||
- `npm ci && npm run compile`
|
||||
3. Commit & `git push origin vscode-extension`.
|
||||
4. Return to `main`. **Do not** add `vscode-extension/` to main.
|
||||
|
||||
## Phase 4 — Tag & trigger CI
|
||||
## Phase 4 — Tag & trigger CI (full/cli)
|
||||
|
||||
```bash
|
||||
git tag -a "TAG" -m "TAG"
|
||||
git push origin "TAG"
|
||||
git tag -a "vVER" -m "vVER"
|
||||
git push origin "vVER"
|
||||
```
|
||||
|
||||
This runs `.github/workflows/release.yml`:
|
||||
Ext-only:
|
||||
|
||||
- **windows** — CLI exe/zip, stdlib zip, ext zip, source zip, public zip, VSIX, Windows native zip
|
||||
- **linux** (`needs: windows`) — **required** Linux native plugins zip + Linux CLI bundle (`ext/` + `native/*.so`)
|
||||
```bash
|
||||
git tag -a "ext-vVER" -m "ext-vVER"
|
||||
git push origin "ext-vVER"
|
||||
```
|
||||
|
||||
If tag push fails: [reference.md § Proxy](reference.md) (`proxy.cflmy.top` first), retry once; then HK jump.
|
||||
(or build zips locally / via workflow and `gh release upload`).
|
||||
|
||||
## Phase 5 — Release notes & assets
|
||||
If tag push needs the user:
|
||||
|
||||
1. Wait for Actions success: `gh run list --workflow=Release --limit 3` / open the run URL. **Both** `windows` and `linux` jobs must be green.
|
||||
2. Ensure GitHub Release for `TAG` exists with assets (workflow uses `softprops/action-gh-release`).
|
||||
3. Confirm Linux assets exist: `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` and `marqdo-VER-x86_64-unknown-linux-gnu.zip`. If missing, do **not** call the release done — re-run / upload.
|
||||
4. **Rewrite release body** (workflow body is a stub) with **中英双语** — see [reference.md § Notes template](reference.md). `gh release edit TAG --notes-file …`.
|
||||
4. Include: Highlights, Breaking, Install (`ext add`, plugins build), Downloads table, WASM (`marqdo wasm build`), links to CHANGELOG/README, extension branch note.
|
||||
5. Optional Linux local extras (not required if CI green): `marqdo wasm build` smoke; document in notes that wasm is built from source via CLI.
|
||||
```bash
|
||||
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
|
||||
```
|
||||
|
||||
Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script header).
|
||||
## Phase 5 — GitHub Release notes & assets
|
||||
|
||||
## Phase 6 — Post-release
|
||||
1. Wait for Actions (full/cli): both `windows` and `linux` green when ext natives required.
|
||||
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.
|
||||
|
||||
1. `gh release view TAG` — confirm assets + notes.
|
||||
2. `git status` clean; `main` synced.
|
||||
3. Tell user: release URL `https://github.com/cflmy/marqdo/releases/tag/TAG`.
|
||||
4. Optional: `./scripts/deploy-public.ps1` / pages workflow if user wants user-site refresh.
|
||||
5. Open fresh `## Unreleased` already done in Phase 2.
|
||||
## Phase 6 — Extension CDN (R2) — required when ext ships
|
||||
|
||||
```bash
|
||||
# credentials: ~/.marqdo/r2.env (never commit)
|
||||
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
|
||||
curl -fsS https://ext.marqdo.com/latest/VERSION
|
||||
```
|
||||
|
||||
Also ensure the **same** zips are on GitHub (`vVER` or `ext-vVER`). If R2 credentials missing, **tell the user**:
|
||||
|
||||
```bash
|
||||
# put keys in ~/.marqdo/r2.env then:
|
||||
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
|
||||
```
|
||||
|
||||
## Phase 7 — Ubuntu PPA (full/cli)
|
||||
|
||||
Linux CLI for apt users. After `Cargo.toml` is at `VER` and `debian/changelog` has a matching `VER-1ppaN` stanza:
|
||||
|
||||
```bash
|
||||
./scripts/ppa-ship.sh noble
|
||||
```
|
||||
|
||||
Packaging notes / noble Cargo.lock v4: [ubuntu-ppa.md](../../../doc/design/ubuntu-ppa.md).
|
||||
|
||||
**If the agent cannot sudo / sign / dput**, print exactly:
|
||||
|
||||
```bash
|
||||
cd ~/work/marqdo
|
||||
./scripts/ppa-ship.sh noble
|
||||
# or build then upload:
|
||||
./scripts/ppa-build-source.sh noble
|
||||
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
|
||||
```
|
||||
|
||||
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
|
||||
On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `1ppaN`, re-upload. Tell the user the new `dput` command.
|
||||
|
||||
## 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.
|
||||
|
||||
## Extension-only release (mode=ext)
|
||||
|
||||
1. User confirms **ext** SemVer (may differ from CLI).
|
||||
2. Bump `ext/VERSION`; CHANGELOG → `## Ext pack vVER`.
|
||||
3. Build/package `marqdo-VER-ext.zip` + `marqdo-VER-native-*.zip` (CI or local).
|
||||
4. Upload to **R2 and GitHub** (required both).
|
||||
5. Do **not** retag CLI / do **not** PPA unless user also asked for cli.
|
||||
|
||||
## Failure matrix (short)
|
||||
|
||||
| Failure | Action |
|
||||
|---------|--------|
|
||||
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; `required_permissions: ["all"]`; see [reference § Proxy](reference.md) |
|
||||
| GitHub blocked | **`origin` via proxy.cflmy.top** (see below), then HK jump |
|
||||
| Tag exists | Stop; ask user to bump or delete tag (no force on shared tags without explicit order) |
|
||||
| CI red | Fix on main, move tag only if user explicitly allows delete+re-push tag |
|
||||
| VSIX missing | Fetch `vscode-extension`, build locally, `gh release upload TAG dist/*.vsix` |
|
||||
| Linux native/CLI zip missing | Incomplete release — fix `linux` job or `gh release upload`; do not skip |
|
||||
| `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 |
|
||||
| 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` |
|
||||
| Linux native zip missing (full/ext) | Incomplete — fix linux job or upload |
|
||||
|
||||
## Do not
|
||||
|
||||
- Ship without user-confirmed version.
|
||||
- Hardcode release highlights only in Actions YAML and forget CHANGELOG.
|
||||
- Commit `target/`, `dist/`, `*.wasm`, or `public/**/*.html` unless project policy changes.
|
||||
- Ship without user-confirmed version (and mode when ambiguous).
|
||||
- Ship ext packs to only one of R2 / GitHub.
|
||||
- Call a full/cli release done without attempting PPA **or** giving the user the PPA commands.
|
||||
- Commit `target/`, `dist/`, `*.wasm`, `third_party/rust/`, or `public/**/*.html` unless policy changes.
|
||||
- Merge extension tree into `main`.
|
||||
@@ -236,7 +236,25 @@ git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
|
||||
|
||||
Short GETs via the proxy often work; **long `git push` may still time out**. If push hangs or drops, skip Clash retries and go to **HK SSH jump** below.
|
||||
|
||||
`gh` against `api.github.com` may still need a direct path or HK jump (the reverse proxy is for `github.com` git, not always the API).
|
||||
`gh` / Release API can use the same path reverse-proxy:
|
||||
|
||||
| Path prefix | Upstream |
|
||||
|-------------|----------|
|
||||
| `/github.com/` | `https://github.com/` |
|
||||
| `/api.github.com/` | `https://api.github.com/` |
|
||||
| `/uploads.github.com/` | `https://uploads.github.com/` (Release asset POST; OpenResty on HK) |
|
||||
|
||||
```bash
|
||||
# Upload a Release asset through proxy.cflmy.top (Content-Type: application/octet-stream)
|
||||
curl -X POST \
|
||||
-H "Authorization: Bearer $GH_TOKEN" \
|
||||
-H "Accept: application/vnd.github+json" \
|
||||
-H "Content-Type: application/octet-stream" \
|
||||
--data-binary @dist/FILE.zip \
|
||||
"https://proxy.cflmy.top/uploads.github.com/repos/cflmy/marqdo/releases/RELEASE_ID/assets?name=FILE.zip"
|
||||
```
|
||||
|
||||
Do **not** rewrite `Host: uploads.github.com` against `proxy.cflmy.top` without the `/uploads.github.com/` path prefix — that returns 404.
|
||||
|
||||
### Diagnose
|
||||
|
||||
|
||||
@@ -4,18 +4,17 @@ description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
|
||||
building dynamic sites with ext/web, quantum circuits with ext/quantum,
|
||||
formula-first linear algebra with ext/linalg, or when the user mentions
|
||||
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
|
||||
or linalg/线性代数 extension.
|
||||
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
|
||||
sites with ext/web, quantum circuits with ext/quantum, or when the user
|
||||
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
|
||||
quantum/量子 extension.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
|
||||
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
|
||||
|
||||
@@ -24,19 +23,21 @@ Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
|
||||
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
|
||||
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
|
||||
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
|
||||
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
|
||||
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
|
||||
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
|
||||
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
|
||||
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
|
||||
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
|
||||
|
||||
## Markup → meaning (v0.3)
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
@@ -47,14 +48,13 @@ Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
|
||||
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
|
||||
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
|
||||
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
|
||||
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
|
||||
| `- [item](coll)` | Foreach (unchanged) |
|
||||
@@ -103,17 +103,17 @@ Chinese builtins (same functions, no import):
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
**x = 1**
|
||||
**y = x + 2**
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
*n + 1*
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
```markdown
|
||||
**n = 0**
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -136,16 +136,16 @@ import clock:lib/time.mq.md
|
||||
|
||||
# main
|
||||
|
||||
**xs = > text.str_split s="a,b,c" sep=","**
|
||||
*xs = > text.split value="a,b,c" sep=","*
|
||||
> print text=`xs`
|
||||
**t = > clock.now_unix**
|
||||
*t = > clock.now_unix*
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
|
||||
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`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`/`非`.
|
||||
@@ -162,48 +162,22 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
|
||||
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.
|
||||
|
||||
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. 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). 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).
|
||||
|
||||
## Official extension: `ext/web` (dynamic sites)
|
||||
**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`.
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
|
||||
## Official extension: `ext/web` (Document / Endpoint / Resource)
|
||||
|
||||
Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifact.md](../../doc/design/ext-web-artifact.md).
|
||||
|
||||
**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`.
|
||||
|
||||
- EN: `import web:ext/web/web.mq.md`
|
||||
- ZH: `导入 网页:ext/web/网页.mq.md`
|
||||
|
||||
**Hard rules (web):**
|
||||
|
||||
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
|
||||
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
|
||||
- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`.
|
||||
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI (default **Go `libweb`**, build via `scripts/build-web-plugin.sh`).
|
||||
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
|
||||
|
||||
**Typical layout:**
|
||||
|
||||
```text
|
||||
index.mq.md # entry + home page table + listen
|
||||
pages/ # sub-pages
|
||||
components/ # reusable |属性|值|样式| tables
|
||||
styles/ # CSS modules
|
||||
public/ # static + favicon.ico|png|svg
|
||||
db/ # schema + open/init
|
||||
data/ # sqlite runtime (gitignore)
|
||||
```
|
||||
|
||||
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
|
||||
|
||||
**Typical flow:** `db.init` → `page.compose_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)).
|
||||
|
||||
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **表驱动引言** `page.compose_intro` / `页面.引言装配`(属性/值/样式表 → `.main-intro`,避免手写 HTML 字符串);**D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
|
||||
|
||||
Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/) · client: [examples/web-client-site/](../../examples/web-client-site/).
|
||||
|
||||
Web patterns: [examples.md](examples.md) §13 · 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)
|
||||
|
||||
@@ -229,18 +203,15 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
|
||||
## Official extension: `ext/linalg` (formula-first LA)
|
||||
## 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`.
|
||||
- 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
|
||||
|
||||
@@ -264,13 +235,12 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
|
||||
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
|
||||
| `json.set` / `compose_*` page parts | `type: web` Document + View table / `web.render` / `web.serve` |
|
||||
| Import `json` for every browser handler | `import browser:lib/browser.mq.md` + tables ([marqdo-dev](../marqdo-dev/SKILL.md)) |
|
||||
| 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`) |
|
||||
|
||||
|
||||
@@ -162,6 +162,56 @@ import browser:lib/browser.mq.md
|
||||
|
||||
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
|
||||
|
||||
## 6e. Agent / LLM result maps — GFM first (positive)
|
||||
|
||||
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
|
||||
|
||||
```markdown
|
||||
---
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
## step_ok
|
||||
+ `task`
|
||||
+ `reply`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | result |
|
||||
|--------|------|--------|
|
||||
| ok | `task` | `reply` |
|
||||
|
||||
*out*
|
||||
|
||||
## step_err
|
||||
+ `task`
|
||||
+ `err`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | error |
|
||||
|--------|------|-------|
|
||||
| error | `task` | `err` |
|
||||
|
||||
*out*
|
||||
|
||||
## soft_http_pack
|
||||
+ `msg`
|
||||
+ `usage0`
|
||||
|
||||
**empty_tc = > table.empty_list**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
# Ext CDN / R2 (Cloudflare) — copy to ~/.marqdo/r2.env and chmod 600
|
||||
# Never commit real keys. Public downloads: https://ext.marqdo.com
|
||||
|
||||
R2_ACCOUNT_ID=
|
||||
R2_BUCKET=marqdo
|
||||
R2_ENDPOINT=https://<accountid>.r2.cloudflarestorage.com
|
||||
R2_ACCESS_KEY_ID=
|
||||
R2_SECRET_ACCESS_KEY=
|
||||
R2_PUBLIC_BASE=https://ext.marqdo.com
|
||||
@@ -0,0 +1,15 @@
|
||||
## 层归属(必填,见 doc/design/layers.md)
|
||||
|
||||
- [ ] Language(`src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` / 契约)
|
||||
- [ ] Runtime(`lib/` `plugins/` `crates/` catalog / view / debug / builtin)
|
||||
- [ ] Document(`*.mq.md` `skills/` `ext/` `public/` `examples/`)
|
||||
|
||||
## 核心表面(见 doc/design/core-surface.md)
|
||||
|
||||
- [ ] 不涉及核心标记
|
||||
- [ ] 涉及核心标记:ADR 编号 ______;core-surface.md 与 `CORE_CONSTRUCTS` 已同步(CI 守卫)
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 相关验收(机器可验证)全绿
|
||||
- [ ] 全量回归绿(`cargo test` / `go test ./...` 视触及面)
|
||||
@@ -38,7 +38,7 @@ jobs:
|
||||
run: |
|
||||
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
|
||||
cargo build --release
|
||||
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
@@ -87,6 +87,7 @@ jobs:
|
||||
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
|
||||
Copy-Item target/release/llm.dll "$stageNative/native/llm.dll"
|
||||
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
|
||||
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
|
||||
$stage = "dist/stage-bundle"
|
||||
@@ -100,6 +101,7 @@ jobs:
|
||||
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
|
||||
Copy-Item target/release/llm.dll "$stage/ext/native/llm.dll"
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
@@ -124,11 +126,32 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v1.0.2**:表驱动页面引言 `compose_intro` / `引言装配`;web-site Demo 与后台门禁加固
|
||||
- **v1.0.2**: table-bound page intro (`compose_intro`); web-site demo + desk auth polish
|
||||
- **v1.0.1**:修复 Go `libweb` 动态路由 `{param}` 查询代入、详情 Markdown、CSS 数字误报
|
||||
- **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
|
||||
- **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
|
||||
|
||||
@@ -136,7 +159,7 @@ jobs:
|
||||
|-------|----------|
|
||||
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) |
|
||||
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Windows DLL + **Linux .so 必出**) |
|
||||
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`/`llm`(Windows DLL + **Linux .so 必出**) |
|
||||
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` |
|
||||
| `marqdo-*-stdlib.zip` | `lib/` only |
|
||||
| `marqdo-*-ext.zip` | Official `ext/` L1 sources |
|
||||
@@ -181,7 +204,7 @@ jobs:
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cargo build --release
|
||||
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
|
||||
- name: Package Linux native zip + CLI bundle
|
||||
@@ -190,7 +213,7 @@ jobs:
|
||||
VER="${GITHUB_REF_NAME#v}"
|
||||
TARGET="x86_64-unknown-linux-gnu"
|
||||
mkdir -p dist/stage-native/native
|
||||
for lib in libweb.so libagent.so libquantum.so liblinalg.so; do
|
||||
for lib in libweb.so libagent.so libquantum.so liblinalg.so libllm.so; do
|
||||
src="target/release/${lib}"
|
||||
if [[ ! -f "$src" && "$lib" == libweb.so ]]; then
|
||||
src="plugins/web/build/libweb.so"
|
||||
|
||||
+15
-1
@@ -24,7 +24,8 @@
|
||||
.marqdo/
|
||||
**/.marqdo/
|
||||
.marqdo-ext/
|
||||
.env
|
||||
/vendor/
|
||||
/.cargo/config.toml
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
/public/index.html
|
||||
@@ -77,5 +78,18 @@ plugins/*/tmp/
|
||||
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
|
||||
/plugins/web/build/
|
||||
|
||||
# PPA build: bundled Rust toolchain (packed into .orig by ppa-build-source.sh only)
|
||||
/third_party/rust/
|
||||
/third_party/
|
||||
|
||||
# ephemeral sqlite / test artifacts
|
||||
tests/ext/:memory:
|
||||
|
||||
# local secrets
|
||||
.env
|
||||
|
||||
# sandbox gold leftovers
|
||||
tests/ext/_sbx_cow/
|
||||
|
||||
tests/ext/_sbx_*/
|
||||
examples/**/_example_sbx/
|
||||
+627
@@ -8,6 +8,633 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## 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
|
||||
|
||||
**Web Artifact 重写(ADR 0007)**:Document / Endpoint / Resource 一等公民;`type: web|endpoint`(ZH `类型: 网页|端点`);facade `web.page|route|serve|render|inspect|use`;DB/auth/ws 拆到 `ext/data` · `ext/security` · `ext/net`。本版 CLI 与扩展包 **同步为 1.2.0**。
|
||||
|
||||
- **Document**:文件级 Artifact + `data_source` / `data_order` / `data_where`;正文 Markdown → HTML;列表卡片 / 详情文章由 serve 时加载。
|
||||
- **Endpoint**:`# main` 处理器;请求经 `run_artifact` Binding 注入;`response` 序列化 JSON/text/html。
|
||||
- **破坏性**:删除作者面 `compose_*` / `app.configure` / 作者 `ensure_plugin`;旧 web gold 移除,新金样 `ext_web_*`。
|
||||
- **示例**:`examples/marqdo-blog/` Artifact 站(pages/api/db + smoke);`web-client-site` serve 扫描。
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
|
||||
git checkout v1.2.0 && cargo build --release
|
||||
bash scripts/build-web-plugin.sh && marqdo ext add web
|
||||
marqdo run examples/marqdo-blog/serve.mq.md
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——复用 Metadata `type`;装配语义在 ext + plugin。语言标记不变。
|
||||
|
||||
### Added
|
||||
- **Web Artifact 模型(ADR 0007)**:`type: web|endpoint`(ZH `类型: 网页|端点`);核心 `src/artifact/`;`sys.artifact_kind`;无 `# main` 时 Result 摘要。
|
||||
- **`ext/web` facade**:`page` · `route` · `serve` · `render` · `inspect` · `use`;子模块 page/route/dom/client/component。
|
||||
- **`ext/data` · `ext/security` · `ext/net`**:从 monolithic web 拆出 Resource。
|
||||
- **统一 View** `|type|slot|value|attrs|style|` + ABI `web_render_nodes` / `web_serve_root` / `web_inspect` / `web_app_use`。
|
||||
- **规则**:`.cursor/rules/web-artifact-no-degrade.mdc`;设计 `doc/design/ext-web-artifact.md`。
|
||||
|
||||
### Fixed
|
||||
- Document `data_source` / `data_where` now drive list cards and detail articles under `web.serve` (ADR 0007 flat metadata).
|
||||
|
||||
### Changed
|
||||
- **破坏性**:删除作者面 `compose_*` / `app.configure` / 作者 `ensure_plugin`。旧 web gold 已移除;新金样 `web-artifact-*` / `ext_web_*`。
|
||||
- **核心表面 Δ**:**无增删**(复用 Metadata `type`)。
|
||||
- 修订 `ext-web.md` C1;`doc/next/007.md` superseded。
|
||||
|
||||
## v1.1.1 — 2026-09-24
|
||||
|
||||
### Highlights
|
||||
|
||||
**AI 栈收口(agent + llm)**:语义 `ask`/`stream`/`collect`、Artifact Metadata Binding、Skill Compilation + Adaptive Routing、MCP 客户端与 resume 检查点、可选 `plugins/llm` Transport ABI。
|
||||
本版 CLI 与扩展包 **同步为 1.1.1**。
|
||||
|
||||
- **LLM 原语**:`ext/ai/llm` 从 OpenAI HTTP 客户端提升为 `ask`/`stream`/`collect` 智能原语(`complete` 保留兼容);`LLMResult.tool_calls`;可选原生 `llm_chat_completions`(无 `.so` 时回退 `lib/net`)。
|
||||
- **Metadata Binding**:frontmatter `${env|arg|sys|secret}` 加载期解析;Phase 2 将绑定键注入入口 env(正文禁止 `${…}`);`sys.meta` / `--bind`;llm ctor 优先 meta。
|
||||
- **Agent**:Skill Compilation(episode → llm_free skills)+ Adaptive Routing(`marqdo` / `small-llm` / `llm` / `auto`;`jev` 为 `small-llm` 兼容别名);MCP **stdio 客户端**;resume 检查点;零 LLM 金样路径。
|
||||
- **度量与后端**:`model_turn` usage、named handles(fast/reasoning)、`type:prompt` 加载、openai/ollama 分流。
|
||||
|
||||
```bash
|
||||
# Ubuntu PPA / 源码
|
||||
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
|
||||
git checkout v1.1.1 && cargo build --release
|
||||
marqdo ext add llm && marqdo ext add agent
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime**(Metadata Binding、LLM/agent 插件与扩展)变更,不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **`ext/ai/llm` 语义表面**:`ask` / `stream` / `collect`(`complete` 兼容);`LLMResult.tool_calls`(OpenAI-shaped `choices[0].message.tool_calls`);`sys.module_source` + 入口文档 `prompt_body` 离线路径。
|
||||
- **`plugins/llm` Transport ABI**(`llm_chat_completions`):`ext/ai/llm/openai` 优先原生插件,否则 `lib/net` HTTP/SSE。
|
||||
- **Artifact Metadata Binding**:frontmatter `${env|arg|sys|secret}` → `Module.metadata`;Secret 掩码;`sys.meta` / `--bind`;Phase 2 入口 env 注入(正文拒绝 `${…}`;字节码 prologue 同源)。
|
||||
- **Agent Skill Compilation + Adaptive Routing**:episode → `maybe_learn` → llm_free skills;路由后端 `marqdo` / `small-llm` / `llm` / `auto`(`jev` = `small-llm` 兼容别名,不再探测 `MARQDO_JEV`)。
|
||||
- **Agent MCP stdio 客户端**(`agent_mcp_client` / `mcp_connect` / `mcp_client_list` / `mcp_client_call`)+ Python mock 离线金样。
|
||||
- **Agent resume 检查点**(`.marqdo/agent-resume/<id>.json` — save/load/clear/list;`run` 可设 `resume_id=`)。
|
||||
- **AI 栈度量与后端**:`model_turn` usage、named handles(fast/reasoning)、`type:prompt` 加载、openai/ollama 分流、agent-zero-llm 金样。
|
||||
|
||||
### Fixed
|
||||
- **plan force 不再冲掉已有 `resources` workbook**(保留 llm_free 资源;金样 `agent-plan-preserve`)。
|
||||
- **compiled-skill Marqdo 语法**:llm_free await 不再误落到 plan+HTTP。
|
||||
|
||||
### Changed
|
||||
- Adaptive Routing:决策面为 `router_model`(任意 llm handle);`jev` 降为 `small-llm` 文档/兼容别名。
|
||||
|
||||
## v1.1.0 — 2026-09-23
|
||||
|
||||
### Highlights
|
||||
|
||||
**AI 原生闭环三件套落地**:核心表面守卫(问题一)· 渐进式契约(问题二)· MLSP for AI(问题三)。
|
||||
`marqdo check` 静态契约防漂移、`marqdo mlsp` 让 AI **按需查询**语法而非背诵、`run --json` 统一结构化诊断(错误即数据,供 AI 直接消费)。
|
||||
本版 CLI 与扩展包 **同步为 1.1.0**。
|
||||
|
||||
- **核心要小(问题一)**:`doc/design/core-surface.md` 列出 19 个核心构造 + `CORE_CONSTRUCTS` 守卫测试——任一侧(清单/文档/金样)单边改动 CI 必红;三层架构(Core / Runtime / Document)入 `doc/design/layers.md`。
|
||||
- **语义校验(问题二)**:渐进式契约表(`参数`/`返回`/`字段`/集合)嵌入文档叙述;四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);`marqdo check` 静态防漂移(类型 typo / 参数名漂移 / 重复契约必报)。
|
||||
- **AI 可靠反馈 + 不必学语法(问题三)**:`marqdo mlsp`(MLSP,行分隔 JSON over stdio)提供 `locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片机械携带戒律原文 / 样例 / 文档锚点,AI 无需预学语法。修复护栏:有界行编辑、越界必拒(abstain)。
|
||||
- **验证(P4)**:锚点消融 anchor 一轮修复率 **100%**(双模型,plain 85%/90%);契约消融拦截 100% / 误报 0%;防漂移必报 9/9;核心守卫演练 3/3 必红。详见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)。
|
||||
|
||||
```bash
|
||||
# Ubuntu PPA / 源码
|
||||
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
|
||||
git checkout v1.1.0 && cargo build --release
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造(`heading` / `bold-code` / `italic-return` / `param-list` / `call-quote` / `branch-list` / `loop-list` / `table-bind` / `footnote-index` / `link-index` / …)与 v1.0.7 完全一致,未新增标记。本版为 **Runtime 层(契约校验 / MLSP / 诊断 JSON)** 与 **Document 层(core-surface / layers)** 变更,不触碰语言核心。
|
||||
|
||||
### Added
|
||||
- **MLSP(`marqdo mlsp`)**:面向 AI 的语言服务协议(行分隔 JSON over stdio)——`locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片含 `semantics` / `rule` / `sample` / `doc_quote`(自持,机器可读戒律原文)。
|
||||
- **`marqdo check`**:静态契约漂移检查(未知类型词 / 参数名漂移 / 返回越约 / 重复契约表 / 错位契约表)。
|
||||
- **渐进式契约(Progressive contracts)**:文档叙述内嵌契约表(`参数`/`返回`/`字段` + 集合 `字段`),四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);被绑定的 `字段|类型` 表是**数据**、永不误判为契约。
|
||||
- **`marqdo run --json`**:统一结构化诊断(`code` / `severity` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`),错误即数据。
|
||||
- **修复护栏**:`mlsp repair_apply` 有界行编辑——只允许落在 `doc_anchor` 指定范围内的编辑,越界整体拒绝(all-or-nothing / abstain)。
|
||||
- **守卫与文档**:`doc/design/core-surface.md`(19 构造)、`doc/design/layers.md`(三层架构)、`tests/core_surface.rs`(守卫生效验证)。
|
||||
|
||||
### Fixed
|
||||
- **错误链不再扁平化**:`src/load.rs` 以 `label_error` 保留结构化 `Diagnostic`("Error Exit Only" 原则),修复契约类错误被降级为字符串的回归。
|
||||
- **契约 parse 边界**:`interp.rs` 键访问优先给出 `index_diag`(索引/键诊断先于取值),空字段 vs 缺字段语义消歧。
|
||||
|
||||
### Changed
|
||||
- **`.cursor/skills/marqdo`**:由「背诵式压缩操作手册」改为**查询式工作流**——写码前 `mlsp syntax` / `locate`,提交前 `mlsp validate` + `marqdo check`,修复照 `doc_anchor` 局部改。
|
||||
- **契约表一经出现即为完整声明**(新推断的升参未覆盖 ⇒ `contract.param_drift` 警告,不静默)。
|
||||
- 取元**主推** `[键](集合)`(`link-index`);`` `集合`[^键] ``(`footnote-index`)保留兼容。
|
||||
|
||||
### 已知未决(诚实标注)
|
||||
- **P4 实验 (b) 盲测未达标**:「查询式 vs 全文档背诵」四判据未全立(`deepseek-flash`:docs 4/6 vs query 0/3;端点 infra 削样本)。查询机制本身已验证无缺陷,瓶颈在**模型自查纪律**(不知道自己不知道 ⇒ 不查询)——协议改进(写码前强制自检 / 陌生构造强制查询)列入下一阶段。见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md) §3。
|
||||
|
||||
## Unreleased
|
||||
|
||||
## v1.0.7 — 2026-09-22
|
||||
|
||||
### Highlights
|
||||
|
||||
**WS / 网络边界加固**:WebSocket 握手同源校验、broadcast/room 默认需登录(`require_auth`/`需要登录` 可显式关闭)、消息 1 MiB × 256 条上限、空 room 回收;HTTP 响应 8 MiB 在读流时截断;`url_encode` 空格 `%20`。本版 CLI 与扩展包 **同步为 1.0.7**。
|
||||
|
||||
- **安全默认**:浏览器 WS 握手仅同源;有状态 fan-out 端点未登录 401 / 公开直播流显式 `require_auth=False`
|
||||
- **资源上限**:WS 单条 1 MiB、单连接 256 条;HTTP/SSE 8 MiB 读流截断——对端无法借大响应耗尽内存
|
||||
- **测试**:P3 金样对齐 quiet-admin 门禁语义;wasm smoke 以 ESM 加载官方 bridge
|
||||
|
||||
```bash
|
||||
# Ubuntu PPA / 源码
|
||||
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
|
||||
git checkout v1.0.7 && cargo build --release
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
### Fixed
|
||||
- **WS 安全默认**:握手改为同源校验(不再放行任意 Origin);`route_ws` 新增 `require_auth`/`需要登录`,broadcast/room 默认要求登录会话,公开直播流需显式设假,未认证握手 401。
|
||||
- **WS 资源上限**:单条消息 1 MiB、单连接最多收集 256 条回复;传输错误/超时返回 `{ok:false, error}`,不再伪装空成功;空 room 自动回收(防 URL 派生 room 名耗尽内存)。
|
||||
- **HTTP 响应上限**:8 MiB 上限在读流时截断(含错误路径与 SSE 错误路径),上游无法借超大响应耗尽内存。
|
||||
|
||||
### Changed
|
||||
- `net.url_encode`:空格编码为 `%20`(原 `+`),URL 段语义下与字面 `+` 消歧义。
|
||||
- `web`/`网页` 文档同步:`route_ws` 的 `require_auth`/`需要登录` 与 `ws.connect` 的收集上限语义。
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
## Ext pack v1.0.6 — 2026-09-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**ext/web OIDC、表单删除与安静管理台(CLI 仍为 v1.0.3)**:OIDC 登录/登出回首页、表单 `删除` 动作、默认关闭内置 admin/RBAC desk、独立 Redis 会话 URL、Postgres CRUD。安装:
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.0.6
|
||||
```
|
||||
|
||||
### Added
|
||||
- **OIDC**:`auth.oidc` / 网页鉴权 OIDC;登录入口与 `next` 回跳。
|
||||
- **表单删除**:`form` 动作 `删除`/`delete`(通用 CRUD,无站点特判)。
|
||||
- **列表/路由**:请求上下文、列表装配延续;注销默认回 `/` 避免 IdP 再登录环。
|
||||
|
||||
### Fixed
|
||||
- 内置 admin / RBAC desk 默认安静,直至显式 `admin` / `enable_rbac`。
|
||||
- 静态资源缓存与 WASM 启动延迟;会话 CSRF 与 Postgres 方言。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.0.6**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
|
||||
|
||||
## Ext pack v1.0.5 — 2026-09-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**ext/web 请求上下文与表单来源(CLI 仍为 v1.0.3)**:字段 `来源`/`source`(session / route / now)、server-only 盖戳、页面 `列表装配`/`compose_list`;禁止按业务表特判。安装:
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.0.5
|
||||
```
|
||||
|
||||
### Added
|
||||
- **Request context**:表单提交携带 `_mq_params` / `_mq_return`;`ApplySources` 从 session/route/now 写入。
|
||||
- **字段来源列**:`client`(默认)/ `session.username` / `route.NAME` / `now`;非 client 不渲染且覆盖客户端伪造。
|
||||
- **列表装配**:`compose_list` / `列表装配`(副绑定 + 条件/排序/插槽),详情页可同页渲染子列表。
|
||||
- 设计文:[ext-web-request-context.md](doc/design/ext-web-request-context.md);金样 `ext_web_form_source_live`。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.0.5**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
|
||||
- 移除评论表名特判(`enrichCommentSubmit`)。
|
||||
|
||||
## Ext pack v1.0.4 — 2026-09-17
|
||||
|
||||
### Highlights
|
||||
|
||||
**ext/web 能力面扩展(CLI 仍为 v1.0.3)**:可配置 RBAC、租户作用域、WS `on_message`/presence、原生 SPA 内存路由、协同记事本 MVP。安装:
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.0.4
|
||||
```
|
||||
|
||||
### Added
|
||||
- **RBAC**:五表(`web_permissions` / `web_roles` / `web_role_permissions` / `web_users` / `web_user_roles`);`app.enable_rbac`、`app.gate permissions=`、`rbac.can`、注册页、`/_rbac/*` 管理 API/desk。
|
||||
- **Tenant**:`app.tenant`(path/header/subdomain)+ `tenant_scope` 自动过滤/盖戳。
|
||||
- **WebSocket G-WS2**:`route_ws` 支持 `on_message` 钩子、动态 room、`presence` 通道。
|
||||
- **Native SPA**:内存 `store_set` / `spa_goto` 与全页 WASM SPA 样站。
|
||||
- **Collab MVP**:LWW 文档协议(`DOC\t`)双端协同记事本样站。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.0.4**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
|
||||
|
||||
## v1.0.3 — 2026-09-17
|
||||
|
||||
### Highlights
|
||||
|
||||
**分发渠道齐备**:Ubuntu PPA 装 CLI;扩展包走 CDN(`ext.marqdo.com`)与 GitHub;CLI 与扩展可分开发版。本版 CLI 与扩展包 **同步为 1.0.3**。
|
||||
|
||||
**语法**:未绑定的 GFM 表格是可丢弃的集合值,不再报 `unrecognized statement`(文档页可直接写安装表)。
|
||||
|
||||
```bash
|
||||
# Ubuntu
|
||||
sudo add-apt-repository ppa:cflmy/marqdo
|
||||
sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web
|
||||
|
||||
# 或源码 / Releases
|
||||
git checkout v1.0.3 && cargo build --release
|
||||
```
|
||||
|
||||
### Added
|
||||
- Ubuntu PPA packaging: `debian/` + `scripts/ppa-ship.sh` (一键装工具/打包/dput) + `ppa-build-source.sh` + [ubuntu-ppa.md](doc/design/ubuntu-ppa.md).
|
||||
- **Extension CDN** (`https://ext.marqdo.com` / Cloudflare R2):`ext add` 下载顺序改为 CDN → GitHub → proxy;独立包版本见 `ext/VERSION` 与 CDN `latest/VERSION`;上传脚本 `scripts/upload-ext-r2.py`(凭据 `~/.marqdo/r2.env`)。设计见 [ext-cdn.md](doc/design/ext-cdn.md)。
|
||||
- `ext add` 下载:GitHub 失败后自动回退 `https://proxy.cflmy.top/github.com/…`;可用 `MARQDO_EXT_DOWNLOAD_BASE` 指定首选镜像;加长读写超时。
|
||||
- 用户文档(README / `public/00-欢迎` / `features/05-扩展`)标明安装渠道:Ubuntu PPA、GitHub Releases、源码;扩展走 CDN。
|
||||
|
||||
### Fixed
|
||||
- `ext/` 导入默认搜索 `~/.marqdo/ext`(与 `marqdo ext add` 安装根一致),无需再手动 `export MARQDO_EXT`。
|
||||
- PPA/noble:捆绑 `third_party/rust`(现代 cargo)以构建 Cargo.lock v4;修复首次 Launchpad 构建失败(distro cargo 1.75)。
|
||||
- 未绑定的 GFM 表格不再报 `unrecognized statement`:作为集合值求值后丢弃(文档中可写表)。
|
||||
|
||||
### Changed
|
||||
- 允许 **CLI 与扩展包分开发版**:扩展包 SemVer 可与 `Cargo.toml` 不同(`MARQDO_EXT_VERSION` / `ext/VERSION` / CDN latest)。
|
||||
- 发版 skill:支持 `full` / `cli` / `ext`;扩展必传 R2+GitHub;CLI 走 PPA;需用户操作时打印确切命令。
|
||||
|
||||
## v1.0.2 — 2026-09-16
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+12
-2
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "1.0.2"
|
||||
version = "1.5.2"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -603,7 +603,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.0.2"
|
||||
version = "1.5.2"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -632,6 +632,16 @@ dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_llm"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"idna_adapter",
|
||||
"serde_json",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_quantum"
|
||||
version = "0.1.0"
|
||||
|
||||
+5
-3
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.0.2"
|
||||
version = "1.5.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 = []
|
||||
@@ -50,13 +50,15 @@ include_dir = "0.7"
|
||||
libc = { version = "0.2", optional = true }
|
||||
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
# No `wasmbind`: keeps cdylib free of wasm-bindgen imports (raw mq_* ABI).
|
||||
# Custom entropy — no `js`/wasm-bindgen imports (raw mq_* ABI + marqdo-bridge.js).
|
||||
chrono = { version = "0.4", default-features = false, features = ["alloc", "std"] }
|
||||
getrandom = { version = "=0.2.17", default-features = false, features = ["custom"] }
|
||||
|
||||
[workspace]
|
||||
members = [
|
||||
"plugins/demo",
|
||||
"plugins/agent",
|
||||
"plugins/llm",
|
||||
"plugins/quantum",
|
||||
"plugins/linalg",
|
||||
"crates/marqdo-wasm",
|
||||
|
||||
@@ -1,12 +1,53 @@
|
||||
# Marqdo
|
||||
|
||||
**代码即文档。文档即代码。文档即知识库。**
|
||||
**代码即文档。文档即知识库。知识即可执行。**
|
||||
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
|
||||
|
||||
欢迎访问 [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/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)
|
||||
|
||||
---
|
||||
|
||||
## 核心优势:可执行知识(Executable Knowledge)
|
||||
|
||||
> **Knowledge That Can Run —— 知识即可执行。**
|
||||
> Marqdo 不是「用 Markdown 写程序」这么简单:它让一个 `.mq.md` 文档**同时**是文稿、知识与程序——同一份结构,同时服务于人、解释器、工具与 AI。
|
||||
|
||||
```text
|
||||
.mq.md(同一份文件)
|
||||
┌─────────┼─────────┐
|
||||
文稿 知识 程序
|
||||
└─────────┼─────────┘
|
||||
▼
|
||||
Marqdo 运行时
|
||||
▼
|
||||
可执行知识(Executable Knowledge)
|
||||
```
|
||||
|
||||
| 真正的核心优势 | 说明 |
|
||||
|------|------|
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **默认安全,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 的下一步。 |
|
||||
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`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。 |
|
||||
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
|
||||
|
||||
---
|
||||
|
||||
## 愿景与期许
|
||||
|
||||
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
|
||||
|
||||
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)。
|
||||
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
|
||||
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
|
||||
|
||||
---
|
||||
|
||||
@@ -38,7 +79,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
|
||||
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
|
||||
| 表格 | 集合;取元优先 `[键](集合)` |
|
||||
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
|
||||
|
||||
```markdown
|
||||
@@ -58,6 +99,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
对于输入变量`n`,执行**n=n+1**接着返回*n*。
|
||||
```
|
||||
|
||||
**表格几何即类型**:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。详见 [tables-maps-footnotes.md](doc/roadmap/tables-maps-footnotes.md)。
|
||||
|
||||
完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。
|
||||
|
||||
---
|
||||
@@ -68,7 +111,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
6. **语言核心保持小**:Language(标记映射 / AST / 语义 / 类型)、Runtime(stdlib / 插件 ABI / WASM / agent)、Document(知识 + 代码 + UI + AI)三层分明——生态功能不淹没语言身份。
|
||||
|
||||
---
|
||||
|
||||
@@ -79,6 +123,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
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
@@ -86,7 +137,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)。
|
||||
|
||||
@@ -98,34 +149,59 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.0.2)
|
||||
## 现状(v1.5.2)
|
||||
|
||||
- **外联 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`**:W0–W7 + P3 + **W8**;**定制 C0–C4**;**宿主 H1–H2**(`proxy`/`invoke`,见 [ext-hosting.md](doc/roadmap/ext-hosting.md));**表驱动引言**(`compose_intro` / `引言装配`);原生层默认 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md),`scripts/build-web-plugin.sh`);示例 [web-site](examples/web-site/) · [web-site-zh](examples/web-site-zh/) · [marqdo-blog](examples/marqdo-blog/) · [anlian-mq](examples/anlian-mq/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)
|
||||
- **`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 stdio**(`mcp_server`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`llm`**:OpenAI 兼容对话
|
||||
- **`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}`(`web` 为 Go;其余为 Rust)
|
||||
- **原生插件 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)
|
||||
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
|
||||
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
|
||||
- **浏览器 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.0.2)
|
||||
### 如何使用最新 Marqdo(v1.5.2)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
| 方式 | 适用 | 命令 / 链接 |
|
||||
|------|------|-------------|
|
||||
| **Ubuntu PPA** | Ubuntu 24.04+(`noble` 等) | `sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo` |
|
||||
| **GitHub Releases** | Windows / Linux 预编译 zip | https://github.com/cflmy/marqdo/releases |
|
||||
| **源码** | 需本机 Rust | 见下方 `git clone` + `cargo build --release` |
|
||||
|
||||
**安装官方扩展**(与 CLI 可分开发版):`marqdo ext add …` 默认下载顺序为 **CDN** [`https://ext.marqdo.com`](https://ext.marqdo.com) → GitHub Releases → [`proxy.cflmy.top`](https://proxy.cflmy.top) 镜像。
|
||||
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.0.2 # 或留在 main
|
||||
git checkout v1.5.2 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -138,19 +214,24 @@ marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
marqdo catalog public -o .marqdo
|
||||
|
||||
# 3) 安装官方扩展(Release 用户:无需本机 Rust/Go)
|
||||
# 2b) AI 原生闭环(v1.1.0+):契约检查 / 结构化诊断 / MLSP 查询
|
||||
marqdo check tests/contracts/ok_contract.mq.md # 静态契约防漂移
|
||||
marqdo run tests/structure/hello.mq.md --json # 结构化诊断(错误即数据)
|
||||
printf '{"id":1,"method":"syntax","params":{"query":"返回"}}\n' | marqdo mlsp
|
||||
|
||||
# 3) 安装官方扩展(Release / CDN 用户:无需本机 Rust/Go)
|
||||
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
|
||||
marqdo ext add agent # 或:智能体
|
||||
marqdo ext add quantum # 或:量子
|
||||
marqdo ext add linalg # 或:线性代数
|
||||
marqdo ext add llm # 或:大模型(纯 .mq.md)
|
||||
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg}
|
||||
marqdo ext add llm # 或:大模型(.mq.md + 可选 native llm)
|
||||
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg,llm}
|
||||
# bash ./scripts/build-web-plugin.sh # 需 Go + cgo → libweb
|
||||
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
|
||||
|
||||
# 4) 动态站示例(扩展装好后)
|
||||
marqdo run examples/web-site-zh/index.mq.md # 表驱动引言 Demo
|
||||
marqdo run examples/marqdo-blog/index.mq.md
|
||||
marqdo run examples/marqdo-blog/serve.mq.md
|
||||
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
|
||||
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
|
||||
|
||||
@@ -159,7 +240,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.0.2
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.5.2
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
@@ -171,7 +252,7 @@ cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`import …:lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add …` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。
|
||||
**发布包**:GitHub Releases 的单独二进制 **已内置**官方 `lib/`。Ubuntu 用户优先 **PPA** 装 CLI。**扩展库**用 `marqdo ext add …`(CDN → GitHub);设计见 [ext-cdn.md](doc/design/ext-cdn.md) · [ubuntu-ppa.md](doc/design/ubuntu-ppa.md) · [ext-cli.md](doc/design/ext-cli.md)。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md) · 变更 [CHANGELOG.md](CHANGELOG.md)
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.0.2"
|
||||
version = "1.5.2"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
@@ -197,6 +197,20 @@ export function eventArgsFromDom(ev, valueFromSel) {
|
||||
args.fields = fields;
|
||||
}
|
||||
}
|
||||
if (ev && (ev.type === "scroll" || ev.type === "resize")) {
|
||||
try {
|
||||
const doc = typeof document !== "undefined" ? document.documentElement : null;
|
||||
const body = typeof document !== "undefined" ? document.body : null;
|
||||
const scrollTop = (doc && (doc.scrollTop || 0)) || (body && body.scrollTop) || 0;
|
||||
const height = doc ? (doc.scrollHeight - doc.clientHeight) || 1 : 1;
|
||||
const ratio = Math.max(0, Math.min(1, scrollTop / height));
|
||||
args.scroll_top = scrollTop;
|
||||
args.scroll_max = height;
|
||||
args.scroll_ratio = ratio;
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
@@ -721,75 +735,88 @@ function runObserveEffect(exports, spec, onError) {
|
||||
const kind = String(spec.kind || spec.type || "intersect").toLowerCase();
|
||||
const sel = String(spec.sel || "");
|
||||
const thenFn = spec.then;
|
||||
const id = String(spec.id || `obs${++observeSeq}`);
|
||||
const el = qsOne(sel);
|
||||
if (!el || !thenFn) return;
|
||||
const baseId = String(spec.id || `obs${++observeSeq}`);
|
||||
const nodes = qsAll(sel);
|
||||
if (!nodes.length || (!thenFn && !spec.add_class)) return;
|
||||
|
||||
const prev = observeHandles.get(id);
|
||||
if (prev) {
|
||||
try {
|
||||
prev.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
|
||||
const fire = (payload) => {
|
||||
try {
|
||||
const result = call(exports, thenFn, payload);
|
||||
if (!result.ok) {
|
||||
if (onError) onError(result.error);
|
||||
return;
|
||||
nodes.forEach((el, idx) => {
|
||||
const id = nodes.length === 1 ? baseId : `${baseId}_${idx}`;
|
||||
const prev = observeHandles.get(id);
|
||||
if (prev) {
|
||||
try {
|
||||
prev.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
applyEffects(exports, result.value, { onError });
|
||||
} catch (e) {
|
||||
if (onError) onError(String(e));
|
||||
}
|
||||
};
|
||||
|
||||
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
|
||||
const ro = new ResizeObserver((entries) => {
|
||||
const en = entries[0];
|
||||
const cr = en?.contentRect;
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "resize",
|
||||
id,
|
||||
width: cr ? cr.width : 0,
|
||||
height: cr ? cr.height : 0,
|
||||
});
|
||||
});
|
||||
ro.observe(el);
|
||||
observeHandles.set(id, ro);
|
||||
return;
|
||||
}
|
||||
const fire = (payload) => {
|
||||
try {
|
||||
const result = call(exports, thenFn, payload);
|
||||
if (!result.ok) {
|
||||
if (onError) onError(result.error);
|
||||
return;
|
||||
}
|
||||
applyEffects(exports, result.value, { onError });
|
||||
} catch (e) {
|
||||
if (onError) onError(String(e));
|
||||
}
|
||||
};
|
||||
|
||||
if (typeof IntersectionObserver !== "undefined") {
|
||||
const io = new IntersectionObserver(
|
||||
(entries) => {
|
||||
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
|
||||
const ro = new ResizeObserver((entries) => {
|
||||
const en = entries[0];
|
||||
if (!en) return;
|
||||
const cr = en?.contentRect;
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "intersect",
|
||||
kind: "resize",
|
||||
id,
|
||||
intersecting: !!en.isIntersecting,
|
||||
ratio: en.intersectionRatio,
|
||||
width: cr ? cr.width : 0,
|
||||
height: cr ? cr.height : 0,
|
||||
});
|
||||
if (spec.once && en.isIntersecting) {
|
||||
try {
|
||||
io.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
});
|
||||
ro.observe(el);
|
||||
observeHandles.set(id, ro);
|
||||
return;
|
||||
}
|
||||
|
||||
if (typeof IntersectionObserver !== "undefined") {
|
||||
const opts = { threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 };
|
||||
if (spec.rootMargin != null) opts.rootMargin = String(spec.rootMargin);
|
||||
const io = new IntersectionObserver(
|
||||
(entries) => {
|
||||
const en = entries[0];
|
||||
if (!en) return;
|
||||
if (en.isIntersecting && spec.add_class) {
|
||||
for (const c of String(spec.add_class).split(/\s+/).filter(Boolean)) {
|
||||
el.classList.add(c);
|
||||
}
|
||||
}
|
||||
observeHandles.delete(id);
|
||||
}
|
||||
},
|
||||
{ threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 },
|
||||
);
|
||||
io.observe(el);
|
||||
observeHandles.set(id, io);
|
||||
}
|
||||
if (thenFn) {
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "intersect",
|
||||
id,
|
||||
intersecting: !!en.isIntersecting,
|
||||
ratio: en.intersectionRatio,
|
||||
target_id: el.id || "",
|
||||
});
|
||||
}
|
||||
if (spec.once && en.isIntersecting) {
|
||||
try {
|
||||
io.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
observeHandles.delete(id);
|
||||
}
|
||||
},
|
||||
opts,
|
||||
);
|
||||
io.observe(el);
|
||||
observeHandles.set(id, io);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function buildFetchInit(spec) {
|
||||
@@ -921,8 +948,23 @@ function runIntervalEffect(exports, spec, onError) {
|
||||
intervalHandles.set(id, handle);
|
||||
}
|
||||
|
||||
const memoryKV = new Map();
|
||||
|
||||
function storageStore(scope) {
|
||||
if (scope === "cookie") return null;
|
||||
if (scope === "memory" || scope === "mem" || scope === "内存") {
|
||||
return {
|
||||
getItem(key) {
|
||||
return memoryKV.has(key) ? memoryKV.get(key) : null;
|
||||
},
|
||||
setItem(key, value) {
|
||||
memoryKV.set(key, String(value));
|
||||
},
|
||||
removeItem(key) {
|
||||
memoryKV.delete(key);
|
||||
},
|
||||
};
|
||||
}
|
||||
if (typeof localStorage === "undefined") return null;
|
||||
return scope === "session" ? sessionStorage : localStorage;
|
||||
}
|
||||
@@ -1371,12 +1413,24 @@ export async function autoMount(doc) {
|
||||
|
||||
const g = typeof globalThis !== "undefined" ? globalThis : undefined;
|
||||
if (g && g.document) {
|
||||
// Defer WASM boot until after first paint / load so LCP images are not
|
||||
// contending with a ~1.6MB wasm download on the critical path.
|
||||
const start = () => {
|
||||
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
|
||||
const run = () => {
|
||||
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
|
||||
};
|
||||
const schedule = () => {
|
||||
if (typeof g.requestIdleCallback === "function") {
|
||||
g.requestIdleCallback(() => run(), { timeout: 1500 });
|
||||
} else {
|
||||
g.setTimeout(run, 0);
|
||||
}
|
||||
};
|
||||
if (g.document.readyState === "complete") {
|
||||
schedule();
|
||||
} else {
|
||||
g.addEventListener("load", schedule, { once: true });
|
||||
}
|
||||
};
|
||||
if (g.document.readyState === "loading") {
|
||||
g.document.addEventListener("DOMContentLoaded", start);
|
||||
} else {
|
||||
queueMicrotask(start);
|
||||
}
|
||||
start();
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"name": "marqdo-bridge",
|
||||
"private": true,
|
||||
"type": "module"
|
||||
}
|
||||
@@ -185,7 +185,38 @@ fn pack_json(v: &serde_json::Value) -> *mut u8 {
|
||||
ptr::copy_nonoverlapping(len.to_le_bytes().as_ptr(), out, 4);
|
||||
ptr::copy_nonoverlapping(bytes.as_ptr(), out.add(4), bytes.len());
|
||||
}
|
||||
out
|
||||
out
|
||||
}
|
||||
|
||||
/// getrandom `custom` backend for wasm32 — no wasm-bindgen / JS glue imports.
|
||||
/// Preferable to the `js` feature which pulls `__wbindgen_*` and breaks raw mq_* ABI.
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
#[no_mangle]
|
||||
unsafe extern "Rust" fn __getrandom_custom(dest: *mut u8, len: usize) -> u32 {
|
||||
// xorshift64* seeded once; fine for uuid/non-crypto browser host helpers.
|
||||
use std::cell::Cell;
|
||||
thread_local! {
|
||||
static STATE: Cell<u64> = const { Cell::new(0x4d51_5241_4e44_4f21) };
|
||||
}
|
||||
if dest.is_null() || len == 0 {
|
||||
return 0;
|
||||
}
|
||||
let mut s = STATE.with(|c| {
|
||||
let mut v = c.get();
|
||||
if v == 0 {
|
||||
v = 0x4d51_5241_4e44_4f21;
|
||||
}
|
||||
v
|
||||
});
|
||||
let buf = unsafe { std::slice::from_raw_parts_mut(dest, len) };
|
||||
for b in buf.iter_mut() {
|
||||
s ^= s << 13;
|
||||
s ^= s >> 7;
|
||||
s ^= s << 17;
|
||||
*b = (s >> 8) as u8;
|
||||
}
|
||||
STATE.with(|c| c.set(s));
|
||||
0
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
|
||||
Vendored
+22
@@ -0,0 +1,22 @@
|
||||
Marqdo for Ubuntu (PPA)
|
||||
=======================
|
||||
|
||||
This package installs the marqdo CLI (/usr/bin/marqdo).
|
||||
|
||||
Official language extensions are not bundled. After install:
|
||||
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
|
||||
Extension packs download from https://ext.marqdo.com (then GitHub / proxy).
|
||||
|
||||
Install this package from:
|
||||
|
||||
sudo add-apt-repository ppa:cflmy/marqdo
|
||||
sudo apt update
|
||||
sudo apt install marqdo
|
||||
|
||||
Also available: GitHub Releases (Windows/Linux zips) and building from source.
|
||||
|
||||
Documentation: https://github.com/cflmy/marqdo
|
||||
PPA notes: doc/design/ubuntu-ppa.md in the upstream repository.
|
||||
Vendored
+152
@@ -0,0 +1,152 @@
|
||||
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,
|
||||
type:web|endpoint, web.serve/render/inspect, ext/data|security|net split,
|
||||
compose_* author surface removed; marqdo-blog Artifact example.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 11:39:04 +0800
|
||||
|
||||
marqdo (1.1.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.1.1: AI stack closure — llm ask/stream/collect, Metadata Binding,
|
||||
Skill Compilation + Adaptive Routing, MCP stdio client + resume checkpoints,
|
||||
optional plugins/llm Transport ABI (fallback lib/net).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 24 Sep 2026 20:32:00 +0800
|
||||
|
||||
marqdo (1.1.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.1.0: core surface guard + progressive contracts + MLSP for AI.
|
||||
New `marqdo check` (static contract drift) and `marqdo mlsp` (language
|
||||
server for AI: locate/syntax/validate/repair_targets/schema/repair_apply);
|
||||
`run --json` unified structured diagnostics; contract tables
|
||||
(参数/返回/字段/集合) with four validation boundaries; anchored repair
|
||||
guardrails (bounded line edits, out-of-scope refused).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 23 Sep 2026 13:30:00 +0800
|
||||
|
||||
marqdo (1.0.7-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.0.7: WS/net boundary hardening (same-origin handshake,
|
||||
require_auth/需要登录, message caps, empty-room GC); HTTP 8 MiB cap
|
||||
enforced while reading; url_encode space -> %20.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Tue, 22 Sep 2026 15:40:00 +0800
|
||||
|
||||
marqdo (1.0.3-1ppa2) noble; urgency=medium
|
||||
|
||||
* Fix Launchpad build: dh_clean -Xvendor/ so cargo vendor checksums keep
|
||||
Cargo.toml.orig (debian-only; reuse published 1.0.3.orig.tar.xz).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 21:28:00 +0800
|
||||
|
||||
marqdo (1.0.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.0.3: PPA + ext CDN; unbound GFM tables; bundled Rust for noble.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:35:00 +0800
|
||||
|
||||
marqdo (1.0.2-1ppa2) noble; urgency=medium
|
||||
|
||||
* Bundle Rust toolchain in orig (third_party/rust) so noble can build
|
||||
Cargo.lock v4 offline; drop distro cargo/rustc Build-Depends.
|
||||
* Architecture: amd64 (bundled toolchain is x86_64).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:20:00 +0800
|
||||
|
||||
marqdo (1.0.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Initial Ubuntu PPA packaging for Marqdo 1.0.2.
|
||||
* CLI only; extensions via "marqdo ext add" / ext.marqdo.com.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 09:55:00 +0800
|
||||
Vendored
+29
@@ -0,0 +1,29 @@
|
||||
Source: marqdo
|
||||
Section: devel
|
||||
Priority: optional
|
||||
Maintainer: cflmy <pingan@cflmy.cn>
|
||||
Build-Depends:
|
||||
debhelper-compat (= 13),
|
||||
build-essential,
|
||||
pkg-config,
|
||||
libssl-dev,
|
||||
ca-certificates
|
||||
Standards-Version: 4.7.0
|
||||
Homepage: https://github.com/cflmy/marqdo
|
||||
Vcs-Git: https://github.com/cflmy/marqdo.git
|
||||
Vcs-Browser: https://github.com/cflmy/marqdo
|
||||
Rules-Requires-Root: no
|
||||
|
||||
Package: marqdo
|
||||
Architecture: amd64
|
||||
Depends: ${shlibs:Depends}, ${misc:Depends}, ca-certificates
|
||||
Description: Markdown markers as an interpreted programming language
|
||||
Marqdo treats Markdown markers as executable syntax (code / return /
|
||||
control flow). This package installs the marqdo CLI.
|
||||
.
|
||||
Official extensions (web, quantum, …) are installed separately via
|
||||
"marqdo ext add" and download from https://ext.marqdo.com .
|
||||
.
|
||||
Launchpad builds use a bundled Rust toolchain under third_party/rust
|
||||
(Ubuntu noble cargo is too old for Cargo.lock v4). Rebuilds on newer
|
||||
series may use distro rustc if cargo ≥ 1.78.
|
||||
Vendored
+24
@@ -0,0 +1,24 @@
|
||||
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
|
||||
Upstream-Name: marqdo
|
||||
Upstream-Contact: cflmy <pingan@cflmy.cn>
|
||||
Source: https://github.com/cflmy/marqdo
|
||||
|
||||
Files: *
|
||||
Copyright: 2024-2026 cflmy
|
||||
License: Apache-2.0
|
||||
|
||||
License: Apache-2.0
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
.
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
.
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
.
|
||||
On Debian systems, the complete text of the Apache License version 2
|
||||
can be found in "/usr/share/common-licenses/Apache-2.0".
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
#!/usr/bin/make -f
|
||||
|
||||
export DH_VERBOSE = 1
|
||||
# Offline builds on Launchpad: vendored crates + optional bundled Rust toolchain.
|
||||
export CARGO_HOME = $(CURDIR)/debian/cargo_home
|
||||
export CARGO_NET_OFFLINE = true
|
||||
|
||||
# Noble (and older) distro cargo cannot read Cargo.lock v4 / modern crates.
|
||||
# Prefer third_party/rust from the orig tarball when present (see ppa-build-source.sh).
|
||||
BUNDLED_RUST = $(CURDIR)/third_party/rust
|
||||
ifneq ($(wildcard $(BUNDLED_RUST)/bin/cargo),)
|
||||
export PATH := $(BUNDLED_RUST)/bin:$(PATH)
|
||||
endif
|
||||
|
||||
%:
|
||||
dh $@
|
||||
|
||||
override_dh_auto_configure:
|
||||
mkdir -p debian/cargo_home
|
||||
@if [ -x "$(BUNDLED_RUST)/bin/cargo" ]; then \
|
||||
echo "Using bundled Rust: $$($(BUNDLED_RUST)/bin/rustc --version)"; \
|
||||
else \
|
||||
echo "Using system Rust: $$(rustc --version 2>/dev/null || echo missing)"; \
|
||||
fi
|
||||
@if [ -f "$(CURDIR)/.cargo/config.toml" ] || [ -d "$(CURDIR)/vendor" ]; then \
|
||||
echo "Using vendored Cargo dependencies"; \
|
||||
else \
|
||||
echo "WARNING: no vendor/ — online cargo fetch required (not for Launchpad)"; \
|
||||
fi
|
||||
|
||||
override_dh_auto_build:
|
||||
mkdir -p debian/cargo_home
|
||||
@command -v cargo >/dev/null || { echo "error: cargo not found (bundle third_party/rust or install rustc/cargo)" >&2; exit 1; }
|
||||
if [ -d "$(CURDIR)/vendor" ]; then \
|
||||
CARGO_NET_OFFLINE=true cargo build --release --locked --offline \
|
||||
-p marqdo; \
|
||||
else \
|
||||
cargo build --release --locked -p marqdo; \
|
||||
fi
|
||||
|
||||
override_dh_auto_test:
|
||||
@echo "Skipping full test suite on package build (run cargo test in CI)."
|
||||
|
||||
override_dh_auto_install:
|
||||
install -d $(CURDIR)/debian/marqdo/usr/bin
|
||||
install -m 0755 $(CURDIR)/target/release/marqdo \
|
||||
$(CURDIR)/debian/marqdo/usr/bin/marqdo
|
||||
|
||||
# dh_clean deletes *.orig by default; cargo vendor checksums require
|
||||
# vendor/**/Cargo.toml.orig. Exclude the vendored tree from that purge.
|
||||
override_dh_clean:
|
||||
dh_clean -Xvendor/
|
||||
|
||||
override_dh_auto_clean:
|
||||
dh_auto_clean
|
||||
rm -rf debian/cargo_home
|
||||
# keep vendor/ and third_party/rust (part of source package)
|
||||
-cargo clean
|
||||
Vendored
+1
@@ -0,0 +1 @@
|
||||
3.0 (quilt)
|
||||
Vendored
+2
@@ -0,0 +1,2 @@
|
||||
# Ignore temporary files while editing patches
|
||||
extend-diff-ignore = "^vendor/"
|
||||
+17
-2
@@ -25,6 +25,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,12 +48,20 @@
|
||||
| [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 循环)** |
|
||||
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/ext-cdn.md](design/ext-cdn.md) | **扩展 CDN(R2 / ext.marqdo.com)与分开发版** |
|
||||
| [design/ubuntu-ppa.md](design/ubuntu-ppa.md) | **Ubuntu PPA 打包与上传** |
|
||||
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
|
||||
| [design/ext-web-go-rewrite.md](design/ext-web-go-rewrite.md) | **`plugins/web` Go 全量重写**(多语言 ABI · 网页制备完备 · anlian 验收) |
|
||||
| [adr/0004-web-plugin-go.md](adr/0004-web-plugin-go.md) | **Accepted:web 原生插件实现语言为 Go** |
|
||||
@@ -87,10 +96,16 @@
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
|
||||
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
|
||||
| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
|
||||
| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) |
|
||||
| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 |
|
||||
| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
|
||||
| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **Accepted**:Agent/LLM 优化 O1–O5 locked |
|
||||
| [roadmap/ext-ai-optimize.md](roadmap/ext-ai-optimize.md) | **O1–O5 实现路线**(沙盒接入→证明晋升→路由/成本→lint→隔离) |
|
||||
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# ADR 0006:Artifact Metadata Binding(`${…}` 进核心 · Metadata-only)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
| Date | 2026-09-24 |
|
||||
| Related | [binding.md](../design/binding.md) · [core-surface.md](../design/core-surface.md) · [layers.md](../design/layers.md) · [doc/next/006.md](../next/006.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Executable Document 需要声明「依赖哪些外部运行时资源」(模型名、API 密钥、base URL),而不是在 `ext/*` 里各自 `sys.env_get`。
|
||||
- [doc/next/006.md](../next/006.md) 提出 **Marqdo Binding**(`${namespace.name}`)与 Artifact Metadata 统一解析。
|
||||
- [layers.md](../design/layers.md):Language 层变更须 ADR;核心构造计数只许持平或下降;默认进 ext。
|
||||
- 正文插值会与 `$$…$$` 公式面冲突,且会新增内联构造压力。
|
||||
|
||||
## Decision
|
||||
|
||||
1. 采纳 **Artifact Metadata Binding** 为 Language 层能力;正式规范见 [binding.md](../design/binding.md)。
|
||||
2. **`${…}` 仅**在文件头 `---` Metadata 中生效;正文 / 粗体 / 调用 / 表 / 叙述 **永不**写 Binding Expression(否决 [006 §17](../next/006.md))。
|
||||
3. **不**把 Binding 记入 [core-surface.md](../design/core-surface.md) 的 19 构造守卫表——与 `import` 同属 §4「其它语言面」。
|
||||
4. 核心只做声明与解析;扩展(如 `ext/ai/llm`)消费已绑定的 `Module.metadata` / `sys.meta*` / 入口提升变量。
|
||||
5. 第一版 namespace:`env` · `arg` · `sys` · `secret`。`config` / `file` 推迟。
|
||||
6. 加载期一次 resolve → Bound Artifact;`Value::Secret` 遮掩展示;`sys.env_get` 保留为逃逸口。
|
||||
7. **Phase 2**:入口执行前把 metadata 键提升为普通变量(形参/赋值可覆盖);正文用 `` `model` ``,不再 `${env…}`。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 配置成为文档的一部分;LLM / agent / 其它 ext 共用同一套 Binding,避免各写一套 getenv。
|
||||
- 缺失 `!` 在加载期失败,而不是运行到 HTTP 401。
|
||||
- 不膨胀 CORE_CONSTRUCTS;与公式 `$$` 无冲突。
|
||||
- 正文保持普通变量语义,不引入第二套环境变量语法。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- Secret 在 `Text + Secret` 拼接时会揭示明文(供 Authorization);须约束日志面。
|
||||
- metadata 键与业务变量同名时依赖「形参/赋值覆盖」规则,作者需注意命名。
|
||||
|
||||
### Neutral
|
||||
|
||||
- `#` / `##` / `**` / `*` 等核心标记不变;frontmatter `import` 句法不变。
|
||||
@@ -0,0 +1,54 @@
|
||||
# ADR 0007:Web Document / Endpoint / Resource(破坏性 · 代码即文档)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
| Date | 2026-09-28 |
|
||||
| Related | [ext-web-artifact.md](../design/ext-web-artifact.md) · [ext-web.md](../design/ext-web.md) · [binding.md](../design/binding.md) · ADR [0006](0006-artifact-metadata-binding.md) · [layers.md](../design/layers.md) · [doc/next/007.md](../next/007.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- [`ext/web/web.mq.md`](../../ext/web/web.mq.md) 已膨胀为小型 Web Framework(Page God Object、`configure` 垃圾抽屉、碎片 Table DSL、隐式路由),与 Marqdo「代码即文档」冲突。
|
||||
- [doc/next/007.md](../next/007.md) 提出 Document / Endpoint / Resource 三原语与拆分 `ext/web` · `ext/net` · `ext/data` · `ext/security`。
|
||||
- 现行 [ext-web.md](../design/ext-web.md) **C1** 禁止为 web 改核心;Document/Endpoint 装载识别需要 Language/Runtime 参与(复用 Artifact Metadata `type`,**不**新增 CORE_CONSTRUCTS 标记)。
|
||||
- Binding(ADR 0006)已提供文件级 Metadata;`type: prompt` 先例在扩展侧消费 metadata。
|
||||
|
||||
## Decision
|
||||
|
||||
1. **采纳** Document / Endpoint / Resource 为 Web 模型一等公民;正式规范见 [ext-web-artifact.md](../design/ext-web-artifact.md)。
|
||||
2. **修订 ext-web C1**:允许核心在装载期识别 `type: web|endpoint`(及中文 `类型: 网页|端点`)并暴露 artifact 分类;**装配 / HTTP / DB 语义仍在 ext + plugin**。单元格求值、import 句法、CORE_CONSTRUCTS 计数不变。
|
||||
3. **文件级 Artifact only**:不在 `##` 函数体嵌套 `---` frontmatter(与 Binding Phase 1 / 解析器一致)。
|
||||
4. **破坏性重写作者面**:删除 `compose_*` 碎片 DSL、god `# page` 变异堆、`app.configure` 多参数抽屉、作者 `ensure_plugin`;examples 与 `tests/ext/web*` 同步重写。
|
||||
5. **目录定稿**(007 §三十五 + §四十):
|
||||
- `ext/web/` — page · route · component · dom · client · facade
|
||||
- `ext/net/` — http · websocket · url
|
||||
- `ext/data/` — db · cache · storage
|
||||
- `ext/security/` — auth · oidc · rbac
|
||||
6. **统一 View 表**:`| type | slot | value | attrs | style |`;Table = Data,禁止每函数私有方言。
|
||||
7. **declared vs system routes**:用户 route 须声明;`/_part` · `/_form` 等为 system,经 `web.inspect` 可见。
|
||||
8. **import = capability**:`import web:…` 由 facade 自动加载 native plugin;作者程序不写 `ensure_plugin` / `host_*`。
|
||||
9. **Metadata v1 锁定(原 007 未决项)**:
|
||||
- 发现:`web.serve root=` 扫描 `root/**/*.mq.md`,仅注册 `type`/`类型` ∈ {web,网页,endpoint,端点} 的文件;无 type 的库文件忽略。
|
||||
- Data:仅 flat 键 `data_source` · `data_order` · `data_where`(text;where 为 `col=val` 逗号分隔)。嵌套 YAML `data:` 推迟。
|
||||
- Result:`{ok: bool, value: any, error: text|None}`。
|
||||
- Realtime 模块名:`ext/net/websocket.mq.md`(ZH:`实时.mq.md`)。
|
||||
- ZH metadata:`类型`←type,`路由`←route,`方法`←method,`路径`←path,`请求`←request,`响应`←response,`鉴权`←auth,`数据源`←data_source,`排序`←data_order,`条件`←data_where。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- `.mq.md` 同时是文档、路由、实现与鉴权声明。
|
||||
- 与 LLM/Agent Artifact Metadata 统一心智。
|
||||
- 职责边界清晰,可独立演化 data/security/net。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- 破坏性:全部现有 web 作者程序与 smokes 必须改写。
|
||||
- Endpoint 热路径仍经 plugin → `CallLibPath` / 文件装载回调;须保持 ABI 稳定演进。
|
||||
- flat data 键表达力弱于嵌套 YAML;后续另 ADR。
|
||||
|
||||
### Neutral
|
||||
|
||||
- 不新增 Markdown 核心标记;`${…}` 仍仅 Metadata。
|
||||
- Go `plugins/web` 可分波删除死 compose ABI;作者面先断。
|
||||
@@ -0,0 +1,186 @@
|
||||
# Marqdo Binding · Artifact Metadata
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Phase 1 + Phase 2(scope lift)** |
|
||||
| 日期 | 2026-09-24 |
|
||||
| ADR | [0006-artifact-metadata-binding.md](../adr/0006-artifact-metadata-binding.md) |
|
||||
| 讨论稿 | [doc/next/006.md](../next/006.md) |
|
||||
| 实现 | `src/binding/` · `Module.metadata` · entry env lift · `sys.meta` / `sys.meta_get` · `marqdo run --bind` |
|
||||
|
||||
> **边界**:核心负责「声明与解析配置」;扩展负责「解释配置的语义」。
|
||||
> **`${…}` 只出现在文件头 Artifact Metadata**——正文 / 粗体 / 调用 / 表 **永不**写 `${env…}`(否决讨论稿 §17)。正文使用已绑定的普通名字。
|
||||
|
||||
---
|
||||
|
||||
## 1. Artifact Metadata
|
||||
|
||||
文件开头成对 `---` 之间为 **Artifact Metadata**(声明式元信息环境),不是「随便贴的 YAML」。
|
||||
|
||||
```text
|
||||
.mq.md
|
||||
├── Metadata ← Identity / Configuration / Dependencies / Bindings
|
||||
└── Executable Body
|
||||
```
|
||||
|
||||
- `import bind:…` / `导入` 行:模块依赖(既有语义不变)。
|
||||
- 其它 `key: value` 行:元信息;值可为字面量或 **Binding Expression**。
|
||||
- Phase 1 仅支持 **flat** 键(同级 `key: value`);块标量 `>` / `|` 收成 Text。
|
||||
|
||||
例:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: demo
|
||||
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
|
||||
---
|
||||
```
|
||||
|
||||
加载后内部为已绑定的 `Module.metadata`(确定性快照),执行期不再对同一键反复 `getenv`。
|
||||
|
||||
---
|
||||
|
||||
## 2. Binding Expression
|
||||
|
||||
外形:
|
||||
|
||||
```text
|
||||
${expression}
|
||||
```
|
||||
|
||||
### 2.1 路径
|
||||
|
||||
```text
|
||||
${namespace.name}
|
||||
```
|
||||
|
||||
| Namespace | 意义 | Phase 1 |
|
||||
|-----------|------|---------|
|
||||
| `env` | 进程环境变量 | ✅ |
|
||||
| `arg` | CLI / Runtime 绑定(`marqdo run --bind KEY=VALUE`) | ✅ |
|
||||
| `sys` | 系统信息:`cwd` · `platform` | ✅ |
|
||||
| `secret` | 敏感环境变量 → `Value::Secret` | ✅ |
|
||||
| `config` | 配置 Artifact | 推迟 |
|
||||
| `file` | 外部文件内容 | 推迟 |
|
||||
|
||||
### 2.2 默认与必需
|
||||
|
||||
```text
|
||||
${env.OPENAI_MODEL ?? "gpt-4o-mini"}
|
||||
${secret.OPENAI_API_KEY!}
|
||||
```
|
||||
|
||||
- `A ?? B`:A 缺失(未设置 / 空)则用 B。
|
||||
- `A!`:A 必须存在,否则加载失败(`config.required_binding_missing`)。
|
||||
|
||||
### 2.3 类型转换
|
||||
|
||||
```text
|
||||
${int(env.MAX_TOKENS ?? "4096")}
|
||||
${float(env.TEMPERATURE ?? "0.2")}
|
||||
${bool(env.STREAM ?? "false")}
|
||||
```
|
||||
|
||||
### 2.4 独占 value vs 插值
|
||||
|
||||
| 形态 | 语义 |
|
||||
|------|------|
|
||||
| `model: ${env.OPENAI_MODEL}` | **Value binding** — 保留解析后的类型(含 Secret) |
|
||||
| `title: "Hello ${env.USER}"` | **Interpolation** — 结果为 Text |
|
||||
| `model: gpt-4o-mini` | **Literal** — 字面量;**不会**被环境变量静默覆盖 |
|
||||
|
||||
---
|
||||
|
||||
## 3. Resolution Policy
|
||||
|
||||
对每个 metadata 键:
|
||||
|
||||
1. 解析该键的字面量 / Binding / 插值(字面量定稿后不受 env 覆盖)。
|
||||
2. 若 CLI 提供了同名 `--bind KEY=VALUE`,**覆盖**该键的最终值(Text)。
|
||||
3. Binding 内部查找顺序(仅当表达式写出时):`arg` / `env` / `secret` / `sys` 按表达式 namespace;`??` 链从左到右。
|
||||
|
||||
推荐作者意图:
|
||||
|
||||
```text
|
||||
CLI --bind
|
||||
→ Artifact 字面量 / 已写死的 Binding 结果
|
||||
→ Binding 源(env / secret / …)
|
||||
→ ?? 默认
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Secret
|
||||
|
||||
`${secret.NAME}` → `Value::Secret`。
|
||||
|
||||
- `print` / `str` / Display → `<secret>`(不泄露)。
|
||||
- `type` → `secret`。
|
||||
- 与 Text 拼接(如 `bearer + api_key`)时**揭示**明文,供 HTTP Authorization。
|
||||
- 不得进入普通 episode / 错误信息明文(扩展作者责任;核心 Display 已遮掩)。
|
||||
|
||||
---
|
||||
|
||||
## 5. Runtime API
|
||||
|
||||
| API | 语义 |
|
||||
|-----|------|
|
||||
| `sys.meta` / `系统.元信息` | 入口模块已绑定 metadata(map) |
|
||||
| `sys.meta_get` / `系统.取元信息` | `key=` → 值或 `None` |
|
||||
| `marqdo run FILE --bind KEY=VALUE` | 可重复;写入 `arg` 并覆盖同名 metadata 键 |
|
||||
| `sys.env_get` | **保留**逃逸口;新代码优先 Metadata Binding |
|
||||
|
||||
---
|
||||
|
||||
## 6. 错误
|
||||
|
||||
| code | 何时 |
|
||||
|------|------|
|
||||
| `config.required_binding_missing` | `${ns.name!}` 且源缺失 |
|
||||
| `config.unknown_binding_ns` | 未知 namespace |
|
||||
| `config.bad_binding` | 表达式非法 / cast 失败 |
|
||||
|
||||
诊断尽量带 frontmatter 行号。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与扩展的分工
|
||||
|
||||
- **核心**:解析 Metadata、resolve Binding、暴露 `Module.metadata` / `sys.meta*`,并在入口把 metadata **提升为普通变量**。
|
||||
- **`ext/ai/llm`**:构造次序为 **显式实参 → 入口作用域同名变量 / `sys.meta_get` → `sys.env_get` 回退 → 默认**。
|
||||
|
||||
---
|
||||
|
||||
## 8. Phase 2 · Metadata scope lift(Accepted)
|
||||
|
||||
加载期绑定完成后,入口执行(`# main` 或唯一无参顶层对象)前,把 `Module.metadata` 的每个键注入 entry 环境,成为**普通变量**:
|
||||
|
||||
```yaml
|
||||
---
|
||||
model: ${env.ModelName ?? "gpt-4o-mini"}
|
||||
---
|
||||
```
|
||||
|
||||
```marqdo
|
||||
# main
|
||||
|
||||
> print text=`model`
|
||||
```
|
||||
|
||||
### 规则
|
||||
|
||||
1. 注入时机:进入入口函数之前。
|
||||
2. 冲突:形参 / 调用实参 **覆盖** 同名 metadata;程序内赋值亦然。metadata **不**覆盖已存在的绑定。
|
||||
3. `sys.meta` / `sys.meta_get` 仍可用(显式通道)。
|
||||
4. **拒绝** 正文 / 粗体 / 表 / 叙述中的 `${…}`(讨论稿 006 §17 否决)。普通语言也不在语句里 `${ENV}`。
|
||||
|
||||
### 仍推迟(P3+)
|
||||
|
||||
- `config` / `file` namespace
|
||||
- 嵌套 YAML map
|
||||
- 显式 `override:` 糖
|
||||
- 计入 `CORE_CONSTRUCTS`
|
||||
@@ -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,47 @@
|
||||
# 核心表面清单(core-surface)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 守卫 | `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 红。
|
||||
|
||||
## 1. 行构造
|
||||
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `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` |
|
||||
| `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` |
|
||||
| `hr` | 单行 `---` 或 `***` | 叙述分隔 | **不收束函数**(返回才收束) | `tests/markup-v03/module-hr.mq.md` |
|
||||
| `writeback` | `<!-- marqdo-out … -->` | 持久化输出 | 只读回放,不执行 | `tests/lib/writeback-get.mq.md` |
|
||||
|
||||
## 2. 内联标记
|
||||
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.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` |
|
||||
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
|
||||
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
|
||||
|
||||
行级入口只有四个大类:`Blank` / `Comment`(叙述段落,含软强调与行内 `` `名` ``)/ `Writeback` / `Code`(`# * > + - | ~ $` 或数字开头)。本清单第 1 节的行构造是在 `Code`(及 `Comment`/`Writeback`)内部的**语义细分**;第 2 节内联标记由 `src/parse/prose.rs` 行内扫描产出。两层合起来 = 核心表面全集。
|
||||
|
||||
## 4. 范围外(进 Language 层,但不在本守卫)
|
||||
|
||||
frontmatter / Artifact Metadata(元信息)、`import` 行(模块装载)、以及 Metadata 内的 **Binding Expression**(`${ns.name}`,见 [binding.md](binding.md) · [ADR 0006](../adr/0006-artifact-metadata-binding.md))属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,**暂不进本清单守卫**(不增 CORE_CONSTRUCTS 计数)。Phase 2 将已绑定 metadata **提升为入口普通变量**(仍非新标记)。如需一并守卫,走 ADR 扩表。
|
||||
@@ -0,0 +1,97 @@
|
||||
# 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`
|
||||
|
||||
落盘:`.marqdo/graph/graph.json` · `edges.json` · `index.json`。
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认)
|
||||
marqdo knowledge preflight "task"
|
||||
marqdo knowledge record REUSE
|
||||
marqdo knowledge learn --task ... --failure ...
|
||||
marqdo find "authentication"
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo impact path/to/file.mq.md
|
||||
marqdo conflicts | stale | duplicate [--fail] | verify
|
||||
```
|
||||
|
||||
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
|
||||
## 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。
|
||||
+19
-3
@@ -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. 为什么要改掉旧方案
|
||||
|
||||
@@ -167,8 +167,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)。
|
||||
@@ -180,11 +181,26 @@ ext/
|
||||
| 中文 | 英文 | 角色 |
|
||||
|------|------|------|
|
||||
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
|
||||
| `## 运行` | `## run` | **v2 主入口**:Adaptive `route` → execute → record episode → maybe_learn(技能 + 策略) |
|
||||
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
|
||||
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
|
||||
| `## 解析` | `## resolve` | 技能解析:exact → alias → canonical → near |
|
||||
| `## 路由` | `## route` | **P4 Adaptive Routing**:`marqdo` \| `small-llm` \| `llm` \| `auto`(`jev` 为 `small-llm` 兼容别名) |
|
||||
| `## 应用路由` | `## route_apply` | 将小模型/大模型路由回复(`SKILL:<slug>` / `EXPLORE`)落到 kb 技能 |
|
||||
| `## 编译策略` | `## compile_policy` | Policy Compilation → `policies/router.mq.md` |
|
||||
| `## 记录情景` | `## record_episode` | 每次执行沉淀为 `.mq.md` episode(`.marqdo/agent-memory/`) |
|
||||
| `## 尝试学习` | `## maybe_learn` | 情景足够时归纳 → 合成 → 编译技能,并尝试编译策略 |
|
||||
| `## 编译` | `## compile` | 候选技能 → 版本化 `skills/<slug>/vN.mq.md` + 可选 OKF promote |
|
||||
| `## 指标` | `## metrics` | Reasoning amortization(`avg_llm_calls` / `compiled_runs`) |
|
||||
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
|
||||
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
|
||||
|
||||
**Skill Compilation(v2)**:Agent 的记忆不是向量袋,而是可执行 `.mq.md`。路径:`episodes/` → `experiences/` → `candidates/` → `skills/vN.mq.md` → OKF `agent-kb`(`llm_free`)。编译技能正文为合法 Marqdo(`**result = …**` + 斜体返回);金样 `tests/ext/agent-zero-llm.mq.md` 验收 policy+skill 全路径 `execution.llm_calls=0`。`plan` 对已存在的 `resources/<slug>.mq.md` **不覆盖**(`agent-plan-preserve`)。
|
||||
|
||||
**LLM 成本**:`model_turn` 走 `model.ask` / `stream`+`collect`,把 `LLMResult.tokens` 写入 episode / `execution`。
|
||||
|
||||
**Adaptive Routing(P4)**:Router 是抽象能力,backend = `marqdo`(已编译 `policies/router.mq.md`)/ `small-llm`(`router_model` 任意 llm 句柄)/ `llm` / `auto` 级联。`jev` 仅为 `small-llm` 兼容别名,**不进入框架专属设计**。热路径在 **`plugins/agent`**(`route.rs`);**禁止**向 `src/host/` 加领域原语。设计:[doc/next/003.md](../next/003.md) · [doc/next/004.md](../next/004.md)。
|
||||
|
||||
构造参数(v1):
|
||||
|
||||
| 参数 | 说明 |
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
# 方案:智能体 / 大模型优化方向(代码即文档 · OKF · 沙盒)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · O1–O5 locked** |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 调研 | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
|
||||
| 路线 | [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md) |
|
||||
| 相关 | [ext-ai-sandbox.md](ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [okf.md](okf.md) · [engineering-knowledge.md](engineering-knowledge.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) · [ai-stack.md](../roadmap/ai-stack.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 方案立场
|
||||
|
||||
1. **强化差异化**:可执行 `.mq.md` 为权威;OKF 为复用;沙盒为证明;LLM 为探索。
|
||||
2. **不向隐藏 TOOL: 循环 / 向量权威回退。**
|
||||
3. 下列方向均为**可行**;推荐波次见 §3,最终裁剪由你选型。
|
||||
4. **不改** `doc/next/*`;落地时另开 roadmap 切片。
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构愿景(闭环)
|
||||
|
||||
```text
|
||||
目标 / 任务
|
||||
│
|
||||
▼
|
||||
EFI / OKF lookup ──hit──► llm_free / marqdo 执行 ──► writeback
|
||||
│ miss
|
||||
▼
|
||||
small-llm 路由 / 父分解
|
||||
│
|
||||
▼
|
||||
生成或修补 .mq.md(代码即文档风格)
|
||||
│
|
||||
▼
|
||||
sandbox.open → sandbox.run(caps)→ diff
|
||||
│
|
||||
├─ 失败 → writeback error / 隔离,不 promote
|
||||
└─ 成功 → 人审或策略 → commit → solidify / OKF promote
|
||||
│
|
||||
▼
|
||||
下次 REUSE(降本)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 可行方向全集
|
||||
|
||||
每个方向标注:解决的问题(Pn)、依赖、风险、粗粒度成本。
|
||||
|
||||
### A. 沙盒 × Agent 闭环
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **A1** | `step`/`plan` 默认经 sandbox 试跑再写实树 | P1 | 生成落 upper;绿才 `commit` | sandbox | 破坏现有金样默认 | 中 |
|
||||
| **A2** | Promote / solidify 强制 sandbox proof | P1 | OKF 写入前要求 proof fixture 绿 | sandbox+OKF | 过严挡复用 | 中 |
|
||||
| **A3** | Sandbox profile 表(caps 宣告) | P1/P3 | GFM 表声明 net/plugin/fs | sandbox | 表方言膨胀 | 低 |
|
||||
| **A4** | Guest 风格门禁(表优先、禁 json 胶水) | P5 | commit 前 lint / preflight | sandbox+parser | 误杀合法 json.parse | 中 |
|
||||
| **A5** | 会话 diff → view 审阅卡 | P1/P4 | HITL 看 CoW diff | view+sandbox | UI 工时 | 中高 |
|
||||
| **A6** | 多会话并行 CoW(fan-out 实验) | — | 每假设一 session | sandbox | 隔离/合并复杂 | 高 |
|
||||
|
||||
### B. OKF / EKC / 技能层
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **B1** | OKF 技能元数据:适用条件 / fixtures / sandbox_profile | P2 | frontmatter + 目录约定 | okf | 与 catalog 字段冲突 | 中 |
|
||||
| **B2** | Progressive disclosure(索引轻、正文按需 READ) | P2/P6 | 对齐 Anthropic Skills 层级 | agent A3 | 实现重复 | 中 |
|
||||
| **B3** | Skill Lift 评测(有/无技能配对) | P4 | harness 指标 | B1 评测 | 样本少噪声大 | 中 |
|
||||
| **B4** | 失败技能隔离(quarantine)+ 回归用例跟随血缘 | P1 | ForgeAgent 式 | OKF | 状态机复杂 | 中高 |
|
||||
| **B5** | near-match / soft_match 产品化默认开 | P6 | 已有 roadmap | okf-near | 误复用 | 低中 |
|
||||
| **B6** | EKC preflight 默认硬门槛(REUSE→ADAPT→CREATE) | P6 | step 前强制 EFI | EKC | 拖慢探索 | 中 |
|
||||
| **B7** | Capability 包与 `llm_free` 资源双向链接 | P2 | catalog L3↔任务包 | EKC+OKF | 图维护 | 中 |
|
||||
|
||||
### C. 大模型 / 路由 / 成本
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **C1** | 步骤级路由(lookup / patch / sandbox_run / net) | P3 | 扩展 route policy 表 | routing | 策略过拟合 | 中 |
|
||||
| **C2** | 总成本计量(含推理 token 膨胀)写回文档 | P7 | usage→writeback/metrics | llm result | 噪声 | 低中 |
|
||||
| **C3** | 用强模型「反思」优化 standing / policy `.mq.md`(类 GEPA) | P3/P5 | 离线优化环,产物仍是文件 | llm | 需评测集 | 高 |
|
||||
| **C4** | 高频 OKF 技能蒸馏/微调小模型(编译进权重) | — | 长期研究 | 数据+算力 | 运维重;偏离「源码权威」 | 很高 |
|
||||
| **C5** | Named model 绑定任务类型(fast=路由,reasoning=分解) | P3 | 已有 named handles 加深 | llm | 配置漂移 | 低 |
|
||||
| **C6** | Prompt document 强制:无参 ask 必须来自 type:prompt 文件 | P5 | 硬化 005 | llm | 破坏脚本式调用 | 低 |
|
||||
|
||||
### D. 代码即文档(产出质量)
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **D1** | 官方「可读 Marqdo」Skill 强化(表/链接取元/禁混名) | P5 | skills/marqdo 加厚 | skill | 模型仍违规 | 低 |
|
||||
| **D2** | AST/结构 lint:json.set 链、混 EN/ZH API | P5 | `marqdo lint` 或 sandbox 钩子 | parser | 误报 | 中 |
|
||||
| **D3** | 工作簿补丁只允许表驱动 / 命名槽写回 | P5 | 收紧 A0 补丁面 | agent | 表达力下降 | 中 |
|
||||
| **D4** | 示例库:sandbox+OKF+表风格 canonical demos | P4/P5 | examples/ | 文档 | 维护 | 低 |
|
||||
|
||||
### E. 评测与产品化
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **E1** | 完成 Wave B1 harness(constitution / writeback / call_site) | P4 | 已规划 | agent | — | 中 |
|
||||
| **E2** | 指标面板:ReuseRate / ProofRate / TokenCost | P4/P7 | metrics 写回或 catalog | agent | 虚荣指标 | 中 |
|
||||
| **E3** | Live 金样矩阵(sandbox 开/关 × 路由后端) | P4 | CI optional | CI | flaky | 中 |
|
||||
| **E4** | 教程:「只读一份 .mq.md 理解 Agent」 | — | doc/tutorial | 文档 | — | 低 |
|
||||
|
||||
### F. 明确不优先 / 需单独论证
|
||||
|
||||
| ID | 方向 | 理由 |
|
||||
|----|------|------|
|
||||
| **F1** | 第二套 Agent Framework(Python/TS 对象图权威) | 违宪 |
|
||||
| **F2** | 向量库升为记忆权威 | 违宪;可作证据工具 |
|
||||
| **F3** | 默认通用 shell Agent | 与 Marqdo-only 沙盒战略冲突 |
|
||||
| **F4** | 整库 `ext/web` 进默认沙盒 | 已否决 |
|
||||
| **F5** | 人人 microVM 本地默认 | DX 过重;留给 hosted |
|
||||
|
||||
---
|
||||
|
||||
## 3. 执行顺序(O1→O5 locked)
|
||||
|
||||
| 波次 | 方向组合 | 为何先做 |
|
||||
|------|----------|----------|
|
||||
| **O1** | A1 轻量(opt-in `sandbox=True`)+ A3 + D1 + D4 | 立刻接上刚落地的沙盒,风险可控 |
|
||||
| **O2** | A2 + B1 + B3 + E1 | 验证→晋升→可度量 Skill Lift |
|
||||
| **O3** | C1 + C2 + B6 | 降本与 EFI 硬门槛 |
|
||||
| **O4** | A4 + D2 + A5 | 质量门禁与人审 |
|
||||
| **O5** | B4 + C3 | 失败隔离与离线提示优化 |
|
||||
| **O∞** | C4 / A6 | 研究项,单独立项 |
|
||||
|
||||
切片实现见 [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收原则(任一波次)
|
||||
|
||||
- 金样:有/无沙盒、有/无 OKF hit、路由后端切换。
|
||||
- 指标:至少报告 ReuseRate 或 TokenCost 之一相对基线变化。
|
||||
- 文档:`.mq.md` 示例仍可读为 Markdown(表/链接取元,少 json 胶水)。
|
||||
- 红线:不改 `doc/next/*`;ext 不调 `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 落地
|
||||
|
||||
O1–O5 已锁定;实现见 [roadmap/ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。**仍不改** `doc/next/*`。
|
||||
@@ -0,0 +1,104 @@
|
||||
# Official AI sandbox (`ext/ai/sandbox`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted · implementing** |
|
||||
| Date | 2026-10-16 |
|
||||
| Related | [research/ai-agent-sandbox.md](../research/ai-agent-sandbox.md) · [roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [stdlib-writeback.md](stdlib-writeback.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. One-liner
|
||||
|
||||
**Agent-only Marqdo trial runtime:** capability-isomorphic to browser Wasm defaults, CoW workspace until explicit `commit`, author surface under `ext/ai` (not stdlib).
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals / non-goals
|
||||
|
||||
### Goals
|
||||
|
||||
| # | Goal |
|
||||
|---|------|
|
||||
| G1 | Open a CoW session over a workspace root; edits stay in upper until `commit` |
|
||||
| G2 | `run` executes `.mq.md` (or in-memory source) under deny-by-default caps with core `lib/*` usable |
|
||||
| G3 | `diff` / `discard` / `inspect` for review gates |
|
||||
| G4 | Stable `unavailable in sandbox` for plugin.load, exec foreign/subtask path|code|lang, net (default), `ext/web` server APIs |
|
||||
| G5 | Author API in `ext/ai/sandbox` via `plugins/agent` — **no** public `lib/sandbox` |
|
||||
|
||||
### Non-goals (this wave)
|
||||
|
||||
| # | Non-goal |
|
||||
|---|----------|
|
||||
| N1 | Embed wasmtime in CLI |
|
||||
| N2 | True Wasm ABI plugins (linalg/quantum) |
|
||||
| N3 | bwrap / microVM |
|
||||
| N4 | Full `ext/web` listen/DB/WS inside sandbox |
|
||||
| N5 | Symlink-forest workspace isolation |
|
||||
| N6 | Default host-proxy of all native ABI plugins |
|
||||
| N7 | Wire `agent.step`/`plan` through sandbox automatically (later) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Layering
|
||||
|
||||
```text
|
||||
ext/ai/sandbox.mq.md → plugin.load agent → sandbox_* ABI
|
||||
↓ host_query
|
||||
HostContext + CowSession
|
||||
(fs / writeback see upper)
|
||||
```
|
||||
|
||||
| Layer | May call `host_*` | Role |
|
||||
|-------|-------------------|------|
|
||||
| `ext/ai/sandbox` | **No** | Author facade |
|
||||
| `plugins/agent` | via `host_query` only | Register `sandbox_*`; forward to host |
|
||||
| `src/host` | — | CoW session store; fs/writeback intercept; nested `run` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Author API
|
||||
|
||||
EN: `ext/ai/sandbox.mq.md` · ZH: `ext/ai/沙盒.mq.md` (separate files, no mixed names in one module).
|
||||
|
||||
| Method | Params | Result |
|
||||
|--------|--------|--------|
|
||||
| `open` | optional `root=` (default entry dir / cwd) | map `{ id, root }` |
|
||||
| `write` | `id=`, `path=`, `text=` | none |
|
||||
| `read` | `id=`, `path=` | text |
|
||||
| `remove` | `id=`, `path=` | none (whiteout) |
|
||||
| `diff` | `id=` | list of `{ path, kind: write\|remove }` |
|
||||
| `commit` | `id=` | `{ ok, applied }` |
|
||||
| `discard` | `id=` | `{ ok }` |
|
||||
| `run` | `id=`, `path=` **or** `source=` | `{ ok, value, stdout?, error? }` |
|
||||
| `inspect` | `id=` | caps, root, change count, notes |
|
||||
|
||||
Default `run` caps: `fs_write=true` (CoW only), `exec=false`, `net=false`, `plugin=false`.
|
||||
|
||||
---
|
||||
|
||||
## 4. CoW semantics
|
||||
|
||||
- **lower** = real workspace root (read-through).
|
||||
- **upper** = session map path → bytes.
|
||||
- **whiteout** = logical deletes; reads miss; commit unlinks lower.
|
||||
- No symlink-as-isolation; resolve paths under root; reject `..` escape.
|
||||
- Until `commit`, host tree unchanged (verifiable with `git status` / file mtime).
|
||||
|
||||
---
|
||||
|
||||
## 5. Hard bans
|
||||
|
||||
1. No public `lib/sandbox`.
|
||||
2. No symlink forest as the isolation story.
|
||||
3. No silent success when capability missing — diagnose `unavailable in sandbox`.
|
||||
4. `ext/**` must not call `host_*`.
|
||||
5. Do not treat empty `# main` as sandbox completeness.
|
||||
|
||||
---
|
||||
|
||||
## 6. ABI / host_query
|
||||
|
||||
Plugin exports (registered on agent plugin): `sandbox_open`, `sandbox_write`, `sandbox_read`, `sandbox_remove`, `sandbox_diff`, `sandbox_commit`, `sandbox_discard`, `sandbox_run`, `sandbox_inspect`.
|
||||
|
||||
Implementation: each forwards to allowlisted `host_query` names of the same stem (e.g. `sandbox_open`), which mutate the process-local CoW store and (for `run`) invoke nested capture with a sandboxed `HostContext`.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Extension CDN (Cloudflare R2 → https://ext.marqdo.com)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** — download prefer CDN; upload via `scripts/upload-ext-r2.py` |
|
||||
| Date | 2026-09-17 |
|
||||
| Related | [ext-cli.md](ext-cli.md) · [marqdo-release](../../.cursor/skills/marqdo-release/SKILL.md) |
|
||||
|
||||
## Why
|
||||
|
||||
CLI (语法解释器) and official **extension packs** (`ext/` L1 + native plugins) update on different cadences. Users behind unstable GitHub links should get packs from a stable object store first.
|
||||
|
||||
## Public URL layout
|
||||
|
||||
Bucket: `marqdo` · Custom domain: **https://ext.marqdo.com**
|
||||
|
||||
| Key | Meaning |
|
||||
|-----|---------|
|
||||
| `v{VER}/marqdo-{VER}-ext.zip` | L1 sources |
|
||||
| `v{VER}/marqdo-{VER}-native-{triple}.zip` | Prebuilt plugins |
|
||||
| `v{VER}/VERSION` | Pack SemVer echo |
|
||||
| `latest/VERSION` | Recommended pack SemVer (plain text) |
|
||||
| `latest/marqdo-…zip` | Same assets mirrored for convenience |
|
||||
|
||||
`{VER}` is the **extension pack** version (`ext/VERSION`), which **may differ** from CLI `Cargo.toml` version.
|
||||
|
||||
## Client download order (`marqdo ext add`)
|
||||
|
||||
1. `MARQDO_EXT_DOWNLOAD_BASE` (optional override)
|
||||
2. **CDN** `https://ext.marqdo.com/v{VER}/…` (override host with `MARQDO_EXT_CDN`)
|
||||
3. GitHub Releases
|
||||
4. `https://proxy.cflmy.top/github.com/…`
|
||||
|
||||
Pack SemVer resolution (`release_version()`):
|
||||
|
||||
1. `MARQDO_EXT_VERSION`
|
||||
2. CDN `GET …/latest/VERSION` (short timeout)
|
||||
3. Embedded `ext/VERSION` at build time
|
||||
4. CLI `CARGO_PKG_VERSION`
|
||||
|
||||
## Separate ext release (no CLI bump)
|
||||
|
||||
1. Bump `ext/VERSION` (e.g. `1.0.3`) — leave root `Cargo.toml` alone if CLI unchanged.
|
||||
2. Build native zips (CI Linux/Windows jobs or local `scripts/build-web-plugin.sh` + cargo plugins).
|
||||
3. Package `marqdo-{VER}-ext.zip` and `marqdo-{VER}-native-*.zip`.
|
||||
4. Upload **both**:
|
||||
- R2: `python3 scripts/upload-ext-r2.py --version VER --from-dir dist/`
|
||||
- GitHub: attach to a GitHub Release (tag `ext-vVER` **or** reuse latest CLI release assets)
|
||||
5. Confirm `https://ext.marqdo.com/latest/VERSION` and a sample zip URL return 200.
|
||||
|
||||
## Full product release (CLI + ext)
|
||||
|
||||
Keep `ext/VERSION` equal to (or compatible with) CLI SemVer unless documenting a deliberate skew. CI still publishes GitHub assets; **after** CI green, run `upload-ext-r2.py` so CDN is populated (or add a CI step with R2 secrets).
|
||||
|
||||
## Credentials
|
||||
|
||||
| Where | What |
|
||||
|-------|------|
|
||||
| Local | `~/.marqdo/r2.env` (`chmod 600`) — see `.env.r2.example` |
|
||||
| CI (optional) | GitHub Actions secrets: `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_ENDPOINT`, `R2_BUCKET` |
|
||||
|
||||
**Never** commit Account API tokens or S3 secret keys. If a token was pasted into chat, **rotate** it in the Cloudflare dashboard.
|
||||
|
||||
## Object ACL
|
||||
|
||||
Custom domain public reads require the bucket/objects to be publicly readable (R2 public bucket / r2.dev / custom domain). Uploads use S3 API credentials; downloads by `ext add` are anonymous HTTPS GETs.
|
||||
@@ -51,10 +51,16 @@ L1 sources:
|
||||
|
||||
| Variable | Meaning |
|
||||
|----------|---------|
|
||||
| `MARQDO_EXT_VERSION` | Override SemVer used for Release asset names (default: CLI `CARGO_PKG_VERSION`) |
|
||||
| `MARQDO_EXT_VERSION` | Override **extension pack** SemVer (default: CDN `latest/VERSION` → embedded `ext/VERSION` → CLI version) |
|
||||
| `MARQDO_EXT_CDN` | Public CDN base (default `https://ext.marqdo.com`) |
|
||||
| `MARQDO_EXT_NO_DOWNLOAD=1` | Never hit the network (CI / air-gap); local/cargo only |
|
||||
| `MARQDO_EXT_DOWNLOAD_BASE` | Optional extra base tried **before** CDN |
|
||||
| `MARQDO_WEB_PLUGIN` / `MARQDO_AGENT_PLUGIN` / `MARQDO_QUANTUM_PLUGIN` | Explicit native path |
|
||||
|
||||
Download order for each Release asset: `MARQDO_EXT_DOWNLOAD_BASE` → **CDN `ext.marqdo.com`** → `github.com` → **`proxy.cflmy.top`**. Connect timeout 20s; read timeout 10min.
|
||||
|
||||
See [ext-cdn.md](ext-cdn.md) for R2 layout, separate ext releases, and `scripts/upload-ext-r2.py`.
|
||||
|
||||
Windows Release **zip** also ships `ext/` + `ext/native/*.dll` next to `marqdo.exe` so a portable unzip works offline after one download.
|
||||
|
||||
## Source for `add` (developers)
|
||||
|
||||
+74
-51
@@ -2,13 +2,21 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted (v0.1.x) |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
|
||||
| Status | **Accepted · v0.3 semantic**(005:Intelligence Primitive) |
|
||||
| Date | 2026-09-24 |
|
||||
| Related | [objects.md](objects.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) · [ai-stack.md](../roadmap/ai-stack.md) · [doc/next/005.md](../next/005.md) |
|
||||
|
||||
## Scope
|
||||
|
||||
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
|
||||
`ext/ai/llm` is Marqdo’s **intelligence primitive**, not an OpenAI SDK wrapper.
|
||||
|
||||
```text
|
||||
Author surface: ask / stream / collect / create / fast / reasoning / prompt_load
|
||||
Transport: ext/ai/llm/openai.mq.md (+ ollama defaults)
|
||||
Compat: complete / chat
|
||||
```
|
||||
|
||||
Import:
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -16,70 +24,85 @@ import llm:ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
|
||||
|
||||
Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
|
||||
Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` / `done` / `error`); `echo=True` prints thinking (`reasoning_content`) and answer tokens as they arrive. See [agent-streaming.md](../roadmap/agent-streaming.md). Default (`stream=False`) is unchanged (answer string).
|
||||
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `import llm:ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
## Platform prerequisites
|
||||
|
||||
| Capability | Surface |
|
||||
|------------|---------|
|
||||
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
|
||||
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
|
||||
| JSON quote | `lib/json` → `quote` |
|
||||
|
||||
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
|
||||
## Public API
|
||||
|
||||
| English | Chinese | Role |
|
||||
|---------|---------|------|
|
||||
| `## load_env` | `## 加载环境` | Free function: load `.env` |
|
||||
| `## stream_result` | `## 流式结果` | Collapse event list → final text |
|
||||
| `# llm` | `# 大模型` | Object ctor → handle map |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods; optional `stream` / `流式`, `echo` / `打印增量` |
|
||||
| `## load_env` | `## 加载环境` | Load `.env` |
|
||||
| `## create` | `## 创建` | Factory → LLM handle |
|
||||
| `## fast` / `## reasoning` | `## 快速` / `## 推理` | Named handles |
|
||||
| `## prompt_load` / `## prompt` / `## prompt_body` | `## 加载提示` / `## 提示` / `## 提示正文` | Prompt artifacts (`type: prompt` → body) |
|
||||
| `## ask` (module) | `## 提问` | Convenience → **text** (`prompt=` or `path=`) |
|
||||
| `## collect` | `## 收集` | Events → text |
|
||||
| `## stream_result` | `## 流式结果` | Alias of `collect` |
|
||||
| `# llm` | `# 大模型` | Handle ctor (`backend=` openai-compatible \| ollama) |
|
||||
| `## ask` (method) | `## 提问` | → **LLMResult** map |
|
||||
| `## stream` | `## 流式` | → event list |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Compat / transport primitive |
|
||||
|
||||
### Preferred
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/ai/llm.mq.md
|
||||
---
|
||||
**answer = > llm.ask prompt="What is Marqdo?"**
|
||||
*answer*
|
||||
|
||||
# main
|
||||
**model = > llm.create**
|
||||
**result = > `model`.ask prompt=`prompt`**
|
||||
*[text](result)*
|
||||
|
||||
> load_env
|
||||
**fast = > llm.fast**
|
||||
**events = > `fast`.stream prompt=`prompt`**
|
||||
**text = > llm.collect events=`events`**
|
||||
|
||||
*`model` = > llm *
|
||||
*`reply` = > `model`.complete prompt=Say hi in one word *
|
||||
> print text=`reply`
|
||||
|
||||
*`events` = > `model`.complete prompt=Say hi stream=True *
|
||||
- [`ev`](`events`)
|
||||
*`t` = > json.get value=`ev` key=type *
|
||||
1. `t` == "delta"
|
||||
*`chunk` = > json.get value=`ev` key=text *
|
||||
> print text=`chunk`
|
||||
2. *
|
||||
*`_` = 1*
|
||||
**body = > llm.prompt path="fixtures/prompt-marqdo.md"**
|
||||
**body2 = > llm.prompt text=`raw`**
|
||||
```
|
||||
|
||||
Environment (create a **project-local** `.env`; do not commit secrets):
|
||||
### LLMResult
|
||||
|
||||
| Field | Meaning |
|
||||
|-------|---------|
|
||||
| `text` | Answer string |
|
||||
| `model` | Model id |
|
||||
| `finish` | Finish reason (`stop`, …) |
|
||||
| `backend` | e.g. `openai-compatible` / `ollama` |
|
||||
| `usage` | `{prompt_tokens,completion_tokens,total_tokens}` |
|
||||
| `tokens` | Alias of `usage.total_tokens` (agent metrics) |
|
||||
| `name` | Optional handle tag (`fast` / `reasoning`) |
|
||||
| `llm_calls` | `1` per ask |
|
||||
| `tool_calls` | List of OpenAI-shaped tool call objects (empty when none) |
|
||||
|
||||
### Compat
|
||||
|
||||
`complete` / `chat` still return a bare string (or event list when `stream=True`) so `ext/ai/agent` and older runbooks keep working. **New code should use `ask` / `stream` / `collect`.**
|
||||
|
||||
## Environment
|
||||
|
||||
```env
|
||||
OPENAI_API_KEY=sk-...
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
MARQDO_LLM_FAST_MODEL=...
|
||||
MARQDO_LLM_REASONING_MODEL=...
|
||||
OLLAMA_HOST=http://127.0.0.1:11434/v1
|
||||
```
|
||||
|
||||
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
|
||||
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`. Ctor also accepts `api_key=` / `base_url=` / `model=` / `backend=`.
|
||||
|
||||
## Backends
|
||||
|
||||
| `backend=` | Module | Notes |
|
||||
|------------|--------|-------|
|
||||
| `openai-compatible` (default) | `ext/ai/llm/openai.mq.md` | Chat Completions HTTP + SSE |
|
||||
| `ollama` | defaults in ctor + same transport | Key defaults to `ollama`; host from `OLLAMA_HOST` |
|
||||
|
||||
## Tests
|
||||
|
||||
- Import smoke: `tests/ext/llm-import.mq.md`
|
||||
- Offline stream: `tests/ext/llm-stream-offline.mq.md` + `tests/lib/net-openai-sse.mq.md`
|
||||
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
|
||||
- Live agent `## step`: `tests/ext/agent-run-live.mq.md` (DeepSeek; gold: `ext_agent_run_live`)
|
||||
- Agent smoke (real `llm` handle): `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
|
||||
- Live complete: `tests/ext/llm-complete.mq.md` (gold: `ext_llm_complete_live`)
|
||||
|
||||
- `tests/ext/llm-import.mq.md`
|
||||
- `tests/ext/llm-ctor-offline.mq.md`
|
||||
- `tests/ext/llm-ask-offline.mq.md` (create + collect)
|
||||
- `tests/ext/llm-stream-offline.mq.md`
|
||||
- `tests/ext/llm-named-offline.mq.md` (fast/reasoning + prompt_load)
|
||||
- `tests/ext/llm-tool-calls-offline.mq.md` (`tool_calls_from` / Result field)
|
||||
- `tests/ext/llm-meta-offline.mq.md` · `llm-entry-prompt-offline.mq.md`
|
||||
- Live: `llm-complete.mq.md` · `llm-stream-live.mq.md`
|
||||
@@ -0,0 +1,197 @@
|
||||
# 官方扩展:Web Artifact(Document / Endpoint / Resource)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 破坏性(取代 page/app God Object 作者面)** |
|
||||
| 日期 | 2026-09-28 |
|
||||
| ADR | [0007-web-document-endpoint.md](../adr/0007-web-document-endpoint.md) |
|
||||
| 讨论稿 | [doc/next/007.md](../next/007.md)(superseded) |
|
||||
| 安装 | `marqdo ext add web`(`web` / `网页`) |
|
||||
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
> **Document describes the page. Table describes the data. Endpoint describes the interaction. Metadata describes the runtime. Marqdo executes all of them.**
|
||||
|
||||
---
|
||||
|
||||
## 1. 三原语
|
||||
|
||||
| Artifact | Metadata `type` / `类型` | 含义 |
|
||||
|----------|--------------------------|------|
|
||||
| **Document** | `web` / `网页` | Markdown 正文 + View → HTML;`route`/`路由` 注册 declared HTTP |
|
||||
| **Endpoint** | `endpoint` / `端点` | 可执行正文为 handler;`path`+`method` 注册 API |
|
||||
| **Resource** | (绑定/导入) | `ext/data` · `ext/security` · 未来 LLM 等,经 metadata / import 声明 |
|
||||
|
||||
核心装载识别 `type`/`类型`(见 `src/artifact/`);渲染与 listen 在 `ext/web` + `plugins/web`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目录
|
||||
|
||||
```text
|
||||
ext/web/
|
||||
web.mq.md · 网页.mq.md # facade: page route serve render inspect
|
||||
page.mq.md · route.mq.md · component.mq.md · dom.mq.md · client.mq.md
|
||||
ext/net/ http.mq.md · websocket.mq.md · url.mq.md
|
||||
ext/data/ db.mq.md · cache.mq.md · storage.mq.md
|
||||
ext/security/ auth.mq.md · oidc.mq.md · rbac.mq.md
|
||||
```
|
||||
|
||||
作者入口通常:
|
||||
|
||||
```text
|
||||
site/
|
||||
index.mq.md # type: web · route: / · 或 # main → web.serve
|
||||
pages/*.mq.md # type: web
|
||||
api/*.mq.md # type: endpoint
|
||||
data/ # sqlite runtime (gitignore)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Document(`type: web`)
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: web
|
||||
title: Marqdo Blog
|
||||
route: /
|
||||
method: GET
|
||||
data_source: posts
|
||||
data_order: -created_at
|
||||
import web:ext/web/web.mq.md
|
||||
import data:ext/data/db.mq.md
|
||||
---
|
||||
|
||||
# Marqdo
|
||||
|
||||
Welcome to the executable web.
|
||||
```
|
||||
|
||||
| 键 (EN) | 键 (ZH) | 说明 |
|
||||
|---------|---------|------|
|
||||
| `type` | `类型` | `web` / `网页` |
|
||||
| `route` | `路由` | 路径,可含 `{param}` |
|
||||
| `method` | `方法` | 默认 `GET` |
|
||||
| `title` | `标题` | 文档标题 / `<title>` |
|
||||
| `data_source` | `数据源` | 表名 |
|
||||
| `data_order` | `排序` | 如 `-created_at` |
|
||||
| `data_where` | `条件` | `col=val,col2=val2` |
|
||||
|
||||
正文 Markdown 经 `dom` 变为 DOM Artifact,再 `web.render`。可选 View 表:
|
||||
|
||||
```markdown
|
||||
`nodes` =
|
||||
|
||||
| type | slot | value | attrs | style |
|
||||
|------|------|-------|-------|-------|
|
||||
| text | kicker | AI Native | | eyebrow |
|
||||
| title | title | Marqdo | | title |
|
||||
```
|
||||
|
||||
`page.render nodes=` 是**唯一**主装配路径。禁止 `compose_main` / `compose_intro` 等碎片 DSL。
|
||||
|
||||
---
|
||||
|
||||
## 4. Endpoint(`type: endpoint`)
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: endpoint
|
||||
method: POST
|
||||
path: /api/posts
|
||||
request: json
|
||||
response: json
|
||||
auth: member
|
||||
import data:ext/data/db.mq.md
|
||||
---
|
||||
|
||||
**post = > data.db.insert …**
|
||||
|
||||
*post*
|
||||
```
|
||||
|
||||
| 键 (EN) | 键 (ZH) | 说明 |
|
||||
|---------|---------|------|
|
||||
| `type` | `类型` | `endpoint` / `端点` |
|
||||
| `path` | `路径` | URL |
|
||||
| `method` | `方法` | GET/POST/… |
|
||||
| `request` | `请求` | `json` / `form` / `none` |
|
||||
| `response` | `响应` | `json` / `text` / `html` / `sse`(`text/event-stream`) |
|
||||
| `auth` | `鉴权` | 角色名或 `none`;`bearer` / `api_key` = 不要求 cookie,把 `Authorization` / `X-Api-Key` 注入 payload 由 `# main` 校验 |
|
||||
|
||||
正文在请求时执行;返回值按 `response` 序列化。Result 协议见 §8。
|
||||
|
||||
**Handler 约定(锁定)**:Endpoint 文件用 `# main` 作为请求处理器。请求体/query/path 参数经 `run_artifact` 以 Metadata Binding 覆盖注入(与 `--bind` 同源),正文用已提升的普通变量名。无 `# main` 时返回 Artifact Result 摘要(`ok`/`value`/`error`),适合作文档型 ping。
|
||||
|
||||
---
|
||||
|
||||
## 5. Facade API(EN / ZH)
|
||||
|
||||
| EN | ZH | 作用 |
|
||||
|----|-----|------|
|
||||
| `web.page` | `网页.页面` | 从 metadata/正文/nodes 构造 Document 句柄 |
|
||||
| `web.route` | `网页.路由` | 注册 declared Document 或 Endpoint |
|
||||
| `web.serve` | `网页.服务` | `root=` 扫描注册 + listen |
|
||||
| `web.render` | `网页.渲染` | Document → HTML(离线/预览) |
|
||||
| `web.inspect` | `网页.检视` | `{declared, system}` 路由表 |
|
||||
|
||||
Middleware 一等:`web.use` / `route.use`,表驱动;**禁止** `configure(cors, security, …)` 垃圾抽屉。
|
||||
|
||||
---
|
||||
|
||||
## 6. 发现算法(锁定)
|
||||
|
||||
`web.serve root=DIR host=… port=…`:
|
||||
|
||||
1. 递归枚举 `DIR` 下 `*.mq.md`(跳过 `data/`、隐藏目录、`node_modules`)。
|
||||
2. 解析文件头 Metadata;无 `type`/`类型` 或非 web/endpoint → 跳过。
|
||||
3. Document → declared route(缺 `route` 则相对 `root` 的路径映射,`index.mq.md` → `/`)。
|
||||
4. Endpoint → declared path+method(`path`/`路径` 必需)。
|
||||
5. System routes(`/_part/*`、`/_form/*`、静态等)由 runtime 挂载,仅出现在 `inspect.system`。
|
||||
6. 调用 native listen。
|
||||
|
||||
---
|
||||
|
||||
## 7. Table 规则
|
||||
|
||||
- **View**:仅 `|type|slot|value|attrs|style|`(及列名 ZH 别名:`类型|槽|值|属性|样式`)。
|
||||
- **Resource schema**:`|字段|类型|可空|` 等 — 专用且文档化,不是函数私有方言。
|
||||
- **禁止** `|属性|值|样式|` / `|front|back|css|` / `|组件|样式|` 作为页面主装配(已删除)。
|
||||
- Raw HTML/CSS = escape hatch(`dom.raw` / `page.css`),不是默认语言。
|
||||
|
||||
---
|
||||
|
||||
## 8. Result
|
||||
|
||||
所有易失败的 Resource / Endpoint 边界返回 map:
|
||||
|
||||
| 键 | 类型 | 说明 |
|
||||
|----|------|------|
|
||||
| `ok` | bool | 成功 |
|
||||
| `value` | any | 成功载荷 |
|
||||
| `error` | text \| None | 失败信息 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 硬约束(取代旧 C1–C7 作者面)
|
||||
|
||||
| # | 约束 |
|
||||
|---|------|
|
||||
| A1 | Document/Endpoint 由核心识别 `type`;装配在 ext(ADR 0007) |
|
||||
| A2 | 禁止 `json.set` 袋胶水;Table = Data |
|
||||
| A3 | 中英分文件;同文件禁止混 API |
|
||||
| A4 | 禁止作者 `ensure_plugin` / `host_*` |
|
||||
| A5 | 禁止隐式用户 route;system 须 `inspect` 可见 |
|
||||
| A6 | 禁止恢复 `compose_*` / `app.configure` / god page 变异堆 |
|
||||
| A7 | 能力只许迁移/提升;删除须本设计明示 + tests 同步 |
|
||||
| A8 | 设计未锁定处停工提问,禁止自行发明 DSL |
|
||||
|
||||
---
|
||||
|
||||
## 10. 与旧 ext-web.md
|
||||
|
||||
旧「页面表 + compose_* + app.route」作者面 **废止**。历史能力矩阵见 [web-net-capabilities.md](web-net-capabilities.md);迁移后以本文件与 ADR 0007 为准。
|
||||
@@ -0,0 +1,19 @@
|
||||
# Collaborative document MVP
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · MVP (LWW)** |
|
||||
| 日期 | 2026-09-17 |
|
||||
|
||||
## Approach
|
||||
|
||||
Not a full CRDT. Peers sync plain text over `route_ws mode=room` with:
|
||||
|
||||
- Client → server: `DOC\\t<body>`
|
||||
- Server fan-out (existing G-WS1/2)
|
||||
- Apply remote if body ≠ local; `applying` flag suppresses echo
|
||||
- Presence JSON on `room.presence` (`presence=True`)
|
||||
|
||||
## Demo
|
||||
|
||||
`examples/web-collab-doc/` — open two browsers on the same room.
|
||||
@@ -0,0 +1,81 @@
|
||||
# `ext/web` 可配置 RBAC(角色 ⊥ 权限)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 验收 | qdqc:门禁 `desk:access` + 评论权限;`tests/ext/web-rbac-*-smoke.mq.md` |
|
||||
| 状态 | **Accepted · 已落地核心**(gate permissions;`/_rbac/*` 管理台 **opt-in** `管理台=真`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
权限是原子能力(`resource:action`);角色是权限包;用户通过 `user_roles` 获得角色。门禁与业务都问 `can(user, permission)`。管理员可在后台新建角色、勾选权限、赋给用户——**禁止**只靠写死的 `role=admin|user` 字符串作为唯一模型(兼容期仍可读旧 `roles=` gate)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 表结构(SQLite / Postgres 同构)
|
||||
|
||||
| 表 | 列 |
|
||||
|----|-----|
|
||||
| `web_permissions` | `code` PK, `resource`, `action`, `description` |
|
||||
| `web_roles` | `id` PK, `name` UNIQUE, `is_system` INT, `tenant_id` TEXT NULL |
|
||||
| `web_role_permissions` | `role_id`, `permission_code` PK(role_id, permission_code) |
|
||||
| `web_user_roles` | `user_id`, `role_id`, `tenant_id` TEXT NULL, PK(user_id, role_id, tenant_id) |
|
||||
| `web_users` | `id` PK, `username` UNIQUE, `password_hash`, `created_at` |
|
||||
|
||||
命名带 `web_` 前缀,避免与业务表冲突。站点也可映射自定义表名(后期);首版固定。
|
||||
|
||||
---
|
||||
|
||||
## 2. 权限码约定
|
||||
|
||||
形如 `comments:create`、`desk:access`、`roles:manage`。内置种子见 `DefaultCatalog`。`*` 或角色名 `superadmin` / 兼容 `admin`:登录时展开为目录全集。
|
||||
|
||||
---
|
||||
|
||||
## 3. 作者 API
|
||||
|
||||
```markdown
|
||||
**`应用` = > `应用`.权限 确保结构=真 目录=`权限目录`**
|
||||
**`应用` = > `应用`.门禁 路径="/desk" 权限="desk:access" 匹配="prefix" 拒绝="redirect"**
|
||||
**`应用` = > `应用`.鉴权 用户表=`管理员` 注册=真 注册路径="/register" …**
|
||||
```
|
||||
|
||||
| 方法 | ABI | 说明 |
|
||||
|------|-----|------|
|
||||
| `app.rbac` / `启用权限` | `web_app_rbac` | ensure schema;可选 `目录`;`管理台=真` 才挂 `/_rbac/*` |
|
||||
| `app.gate` | `web_app_gate` | 新增 `permissions`/`权限`(CSV);与 `roles` 可并存:有 permissions 时按权限判定 |
|
||||
| `rbac.can` | `web_rbac_can` | `{ok, allowed}` |
|
||||
| `rbac.assign_role` | `web_rbac_assign_role` | 用户←角色 |
|
||||
| `rbac.set_role_permissions` | `web_rbac_set_role_permissions` | 角色←权限列表 |
|
||||
|
||||
防提权:`set_role_permissions` / `assign_role` 在 HTTP 管理面检查操作者 `roles:manage` 且不能授予自身没有的 permission。
|
||||
|
||||
---
|
||||
|
||||
## 4. 运行时
|
||||
|
||||
1. `listen`:若 `auth.rbac=true` 或调用过 `app.rbac`,对 `db` URL `EnsureSchema` + 种子。
|
||||
2. 仅当 `auth.rbac_desk=true`(`启用权限 管理台=真`)时挂载 `/_rbac/*` API 与 desk。
|
||||
3. 登录成功:解析角色 → DB `user_roles` ∪ GFM 角色展开 → session `permissions`(CSV)+ 兼容 `role`。
|
||||
4. `withRBAC`:gate 含 `permissions` 则 `PermissionAllowed`;否则旧 `RoleAllowed`。
|
||||
5. 注册:`POST /register` 写入 `web_users`,默认赋 `member` 角色。
|
||||
|
||||
---
|
||||
|
||||
## 5. qdqc 映射
|
||||
|
||||
| 产品 | 权限码 |
|
||||
|------|--------|
|
||||
| 发评论 | `comments:create` |
|
||||
| 删任意评论 | `comments:delete` |
|
||||
| 进 desk | `desk:access` |
|
||||
| 管角色 | `roles:manage` |
|
||||
|
||||
首个 GFM `admin` 用户登录后视为 `superadmin`(全权限);DB 迁移后绑定 `superadmin` 角色。
|
||||
|
||||
---
|
||||
|
||||
## 6. 非目标(本切片)
|
||||
|
||||
对象级 ACL 全图、ABAC;租户列先可空,多租户波次再启用。
|
||||
@@ -0,0 +1,91 @@
|
||||
# ext/web:请求上下文与表单字段来源
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-09-18 |
|
||||
| 相关 | [ext-web.md](ext-web.md) §5.5 · 对照 Django `request.user` / URL kwargs |
|
||||
| 动机 | 禁止扩展库按业务表名(如 `comments`)特判填字段;身份与路由键属于请求上下文 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 原则
|
||||
|
||||
1. **扩展库提供机制,站点表达领域** — 不得出现 `if table == "comments"`。
|
||||
2. **身份只从 session 来,且服务端盖戳** — 客户端提交的 `author` 等不可信。
|
||||
3. **资源键从路由参数来** — 页面已在 `/post/{slug}` 时,表单继承该页 `params`,不解析 Referer 猜 slug。
|
||||
4. **非 `client` 来源的字段默认不渲染** — 服务端在校验前写入;若 POST 带同名键,一律覆盖丢弃。
|
||||
|
||||
---
|
||||
|
||||
## 1. 请求上下文(Request)
|
||||
|
||||
每次处理 HTTP 请求时,框架逻辑上持有:
|
||||
|
||||
| 键 | 含义 |
|
||||
|----|------|
|
||||
| `user` / `username` | 登录名;访客为空 |
|
||||
| `params` | 动态路由捕获(如 `{slug}`) |
|
||||
| `path` | 请求路径 |
|
||||
| `method` | GET / POST / … |
|
||||
| `query` | URL 查询(可选) |
|
||||
|
||||
与 Django 对应:`request.user`、`request.resolver_match.kwargs`、`request.path`。
|
||||
|
||||
页面渲染时已有 `page.params`(`injectParams`)。表单提交时通过隐藏字段 `_mq_params`(JSON)与 `_mq_return`(回跳路径)把**渲染该表单时的页上下文**带回 POST,避免依赖 Referer。
|
||||
|
||||
---
|
||||
|
||||
## 2. 字段表「来源」列
|
||||
|
||||
字段表增加可选列 `来源` / `source`(缺省 = `client`):
|
||||
|
||||
```markdown
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 | 来源 |
|
||||
|------|------|------|------|------|------|
|
||||
| body | 写下你的想法 | textarea | true | | client |
|
||||
| author | | | true | | session.username |
|
||||
| post_slug | | | true | | route.slug |
|
||||
| created_at | | | false | | now |
|
||||
```
|
||||
|
||||
| 来源值 | 含义 | 渲染 |
|
||||
|--------|------|------|
|
||||
| `client` / 空 | 用户填写 | 正常控件 |
|
||||
| `session.username` / `session.user` / `user` | 当前登录用户名 | 不渲染 |
|
||||
| `route.NAME` / `param.NAME` / `params.NAME` | `params[NAME]` | 不渲染 |
|
||||
| `now` / `utc.now` / `server.now` | UTC `YYYY-MM-DD HH:MM:SS` | 不渲染 |
|
||||
|
||||
`类型=hidden` 仍可显式使用;与 `来源≠client` 叠加时仍不依赖客户端值(服务端覆盖)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 提交管线
|
||||
|
||||
```
|
||||
ParseForm → 去掉来源≠client 的 POST 键
|
||||
→ 按字段来源从 Request 写入
|
||||
→ validate → insert/update
|
||||
→ 回跳:优先 _mq_return(同站路径),否则 form.redirect
|
||||
```
|
||||
|
||||
伪造 `author` / `post_slug` 无效。
|
||||
|
||||
---
|
||||
|
||||
## 4. 页面列表装配(副绑定)
|
||||
|
||||
详情页可附加与主主体**不同查询条件**的列表绑定(如评论):
|
||||
|
||||
```markdown
|
||||
**post = > post.列表装配 主体=`评论卡片` 条件=`评论条件` 排序="-created_at"**
|
||||
```
|
||||
|
||||
条件值同样支持 `{slug}`。渲染在主文章/卡片区之后,无需为子资源单独写 JSON API + 前端过滤。
|
||||
|
||||
---
|
||||
|
||||
## 5. 非目标
|
||||
|
||||
- 不在扩展库内实现「评论」领域类型。
|
||||
- 不把 Referer 解析当作正式 params 来源(仅兼容期可作 `_mq_params` 缺失时的弱回退,金样不依赖)。
|
||||
@@ -0,0 +1,24 @@
|
||||
# Native SPA(Marqdo WASM 全页客户端)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · MVP** |
|
||||
| 日期 | 2026-09-17 |
|
||||
| 相关 | [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · route D/E |
|
||||
|
||||
## 约定
|
||||
|
||||
| 表 | 列 | 用途 |
|
||||
|----|-----|------|
|
||||
| 客户端路由 | `路径` / `面板` / `标题` | 文档化视图;运行时用 `path` + `set_attr(hidden)` 切换 |
|
||||
| 客户端状态 | `browser.store_set` / `store_get` `scope=memory` | 页内状态(列表 JSON、当前 id) |
|
||||
|
||||
作者零业务 JS:`web.client_embed` + `static/client.mq.md` + `lib/browser`。
|
||||
|
||||
## Bridge
|
||||
|
||||
`storage` effect 支持 `scope=memory`(进程内 `Map`),与 `local` / `session` / `cookie` 并列。
|
||||
|
||||
## Demo
|
||||
|
||||
`examples/web-spa-app/` — 列表 → 详情 → 编辑,全客户端路由。
|
||||
@@ -0,0 +1,23 @@
|
||||
# ext/web multi-tenant (path / subdomain / header)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · MVP** |
|
||||
| 日期 | 2026-09-17 |
|
||||
| 相关 | [ext-web-rbac.md](ext-web-rbac.md) · full-ambition plan |
|
||||
|
||||
## Author API
|
||||
|
||||
```markdown
|
||||
**应用 = > `应用`.tenant mode="path" param="t" column="tenant_id" default_scope=False**
|
||||
```
|
||||
|
||||
JSON route table may set `tenant_scope` / `租户作用域` = true so `GET /api/items?t=acme` only returns rows with `tenant_id=acme`.
|
||||
|
||||
## Runtime
|
||||
|
||||
1. `withTenant` resolves id into request context.
|
||||
2. Scoped JSON selects `AND tenant_id=?`; missing tenant → 400.
|
||||
3. `default_scope=True` also stamps form POST bodies.
|
||||
|
||||
Demo: `examples/web-tenant-saas/`.
|
||||
+22
-14
@@ -2,18 +2,21 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · W0–W7 + P3 + W8(站点图标/Head/图片装配)完结**(SQLite/Postgres 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / RBAC / 上传相册 / SEO·RSS·sitemap / **favicon·头资源·图片装配**;Postgres 等见 §9) |
|
||||
| 日期 | 2026-08-11(W8:2026-08-29) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) |
|
||||
| 状态 | **Superseded(作者面)· 历史能力档案** — 现行作者面见 **[ext-web-artifact.md](ext-web-artifact.md)** · ADR [0007](../adr/0007-web-document-endpoint.md) |
|
||||
| 日期 | 2026-08-11(W8:2026-08-29;请求上下文:2026-09-18;Artifact 重构:2026-09-28) |
|
||||
| 相关 | [ext-web-artifact.md](ext-web-artifact.md) · [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) · **[ext-web-request-context.md](ext-web-request-context.md)** |
|
||||
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
|
||||
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
|
||||
| 本文目的 | **历史**类 API 与能力矩阵;新站请勿按本文 `compose_*` / `app.configure` 写作 |
|
||||
|
||||
> **2026-09-28**:作者面迁移到 Document / Endpoint / Resource。C1 已由 ADR 0007 修订。下文保留作迁移对照,**不是**现行推荐 API。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
`ext/web` 用 **GFM 表格 + Marqdo 类方法** 描述动态网站:表仍是字典/列表嵌套;类方法把表装配成可渲染页面。
|
||||
**不改 Marqdo 核心语法**;扩展库存在的理由,正是让「文档即代码」在网站场景下成立。
|
||||
**现行**:`.mq.md` Artifact(`type: web|endpoint`)描述页面与交互;见 [ext-web-artifact.md](ext-web-artifact.md)。
|
||||
|
||||
**历史(废止)**:`ext/web` 曾用 GFM 表格 + `# page`/`# app` 类方法拼装站点。该模型因 God Object / 碎片 DSL / 隐式路由被破坏性替换。
|
||||
|
||||
---
|
||||
|
||||
@@ -41,13 +44,14 @@
|
||||
|
||||
| # | 约束 |
|
||||
|---|------|
|
||||
| C1 | **禁止**为 web 改动 Marqdo 核心:单元格求值、import、点号值读取等保持不变 |
|
||||
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水、手写 part JSON、手写 assemble 袋 |
|
||||
| C3 | 能力以 **`#` 类 + `##` 方法** 暴露;**英文库文件只用英文名,中文库文件只用中文名**(见 [stdlib-i18n.md](stdlib-i18n.md));同一 `.mq.md` 内禁止中英 API 混排 |
|
||||
| C4 | 首页在 **`index.mq.md`**:页面表在此;可复用片段进 `components/`;主体可就地写 |
|
||||
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进。**落实**:原生层 Go 全量重写见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md);作者面 ABI 名保持兼容 |
|
||||
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
|
||||
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
|
||||
| C1 | **修订(ADR 0007)**:核心可识别 Artifact `type: web\|endpoint`(及 ZH);**不**新增 CORE_CONSTRUCTS 标记;单元格求值 / import 句法不变;装配语义仍在 ext + plugin。旧文「禁止为 web 改核心」作废 |
|
||||
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水(现行见 ext-web-artifact A2) |
|
||||
| C3 | 中英分文件;同文件禁止混 API(现行 A3) |
|
||||
| C4 | **废止**「页面表 + compose」心智 → Document Artifact + `pages/` · `api/` |
|
||||
| C5 | 破坏性重写作者面(ADR 0007);原生 Go 演进见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) |
|
||||
| C6 | DB 迁至 **`ext/data`**;CRUD 仍须完整(`select` / `查询`) |
|
||||
| C7 | 表单校验仍须在写库前执行;挂载经 declared Endpoint / system `/_form`(inspect 可见) |
|
||||
| A1–A8 | **现行硬约束**见 [ext-web-artifact.md](ext-web-artifact.md) §9 |
|
||||
|
||||
---
|
||||
|
||||
@@ -247,6 +251,7 @@ import db:db/index.mq.md
|
||||
|------|------|
|
||||
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
|
||||
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=`index`) |
|
||||
| compose_list / 列表装配 | 副绑定(独立 query/order);可选 target 注入引言元素;见 [ext-web-request-context.md](ext-web-request-context.md) |
|
||||
|
||||
**槽位推断:** 由组件导出名决定(`nav`→顶栏,`side`→侧栏,`foot`→底栏;其余→main)。
|
||||
|
||||
@@ -423,6 +428,7 @@ import db:db/index.mq.md
|
||||
| `类型` | 控件/值类型:`text` `textarea` `number` `email` `url` `checkbox` `select` … |
|
||||
| `必填` | 是否必填 |
|
||||
| `默认` | 可选默认值 |
|
||||
| `来源` / `source` | 可选;见 [ext-web-request-context.md](ext-web-request-context.md):`client`(默认)/ `session.username` / `route.NAME` / `now`;非 client 不渲染且服务端盖戳 |
|
||||
|
||||
#### 5.5.2 校验表(作者面)
|
||||
|
||||
@@ -580,7 +586,9 @@ submit → action=insert → db.insert;action=update → db.update
|
||||
## 9. 非本波次(可记入路线图)
|
||||
|
||||
- Postgres / Redis / S3 驱动细节(SQLite 已落地);
|
||||
- 复杂权限与多租户;
|
||||
- ~~复杂权限与多租户~~ → **可配置 RBAC** 见 [ext-web-rbac.md](ext-web-rbac.md);**多租户** 见 [ext-web-tenant.md](ext-web-tenant.md)(path/subdomain/header + `tenant_scope`);
|
||||
- ~~重客户端 SPA~~ → **Native SPA** 见 [ext-web-spa.md](ext-web-spa.md)(WASM + 路由表 + `store_set` memory);
|
||||
- ~~实时协同编辑~~ → **Collab MVP** 见 [ext-web-collab.md](ext-web-collab.md)(WS room LWW 文本 + presence);
|
||||
- 子页路由糖的更多约定(`# 应用.route` 已够用)。
|
||||
|
||||
---
|
||||
|
||||
@@ -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,449 @@
|
||||
# 外联内核(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 值映射
|
||||
|
||||
| Marqdo | JSON |
|
||||
|---|---|
|
||||
| None | null |
|
||||
| Bool | bool |
|
||||
| Int | number |
|
||||
| Num | number(NaN/Inf → null) |
|
||||
| Text | string |
|
||||
| List | array |
|
||||
| Map | object |
|
||||
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
|
||||
| Code | 源码字符串 |
|
||||
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
|
||||
|
||||
### 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,29 @@
|
||||
# 三层归属与准入戒律(layers)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 准入制度(问题一落地)** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 相关 | [core-surface.md](core-surface.md)(核心表面守卫)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.2 |
|
||||
|
||||
> **目的**:语言核心保持小——**Language / Runtime / Document 三层分明,生态功能不淹没语言身份**。本制度是机制不是宣言:违反即 CI 红 / PR 不评审。
|
||||
|
||||
## 1. 三层归属表
|
||||
|
||||
| 层 | 内容 | 仓库位置 |
|
||||
|----|------|----------|
|
||||
| **Language** | 标记映射、词法/行分类、AST、语义、升参、契约检查器、诊断 | `src/lex/` `src/parse/` `src/ast.rs` `src/interp.rs` `src/diagnostics.rs`(及 `contract`/`check`)· 宪法 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [core-surface.md](core-surface.md) |
|
||||
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema / mcp CLI、字节码后端 | `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view/` `src/debug/` `src/builtin.rs` `src/bytecode/` |
|
||||
| **Document** | 知识单元、AI skills、示例、官方扩展、用户站 | `*.mq.md` `skills/` `ext/` `public/` `examples/` `doc/` |
|
||||
|
||||
## 2. 准入戒律
|
||||
|
||||
1. **先填层归属**:任何新特性提案(issue / PR / 设计文档)必须先声明进哪层;未填 = 不评审。
|
||||
2. **Language 层变更 = ADR**:新增核心标记必须有 `doc/adr/` 编号 + 「为什么现有标记不够」+ [core-surface.md](core-surface.md) 增行 + 样例 + `CORE_CONSTRUCTS` 同步(缺任一 → CI 守卫红)。
|
||||
3. **核心计数只许持平或下降**:每个 release 的核心标记计数不得增长;确需增长即触发 Language 层复盘(ADR 里写明不可替代理由)。
|
||||
4. **默认进 ext**:能用扩展、stdlib、插件解决的,一律不进核心。
|
||||
5. **CHANGELOG 单列「核心表面 Δ」**:每个 release 写明增删(无 Δ 写「无」);发版 checklist(`.cursor/skills/marqdo-release/SKILL.md`)含此步。
|
||||
|
||||
## 3. PR 模板
|
||||
|
||||
`.github/PULL_REQUEST_TEMPLATE.md` 含「层归属」必填项与「核心表面」勾选——与本制度一一对应。
|
||||
@@ -211,11 +211,13 @@ v0.3:
|
||||
| 体内 `1.` `2.` … | 分支 |
|
||||
| 体内 `-` | 循环 |
|
||||
| `N. *` | else 臂(此处 `*` 仍是「空条件」标记,**不是**返回值;见 §7.3) |
|
||||
| GFM 表格 | 集合(不变) |
|
||||
| GFM 表格 | 集合;`` `名` = `` 后绑定,或**未绑定**时求值后丢弃(文档中可写表) |
|
||||
| 表达式 `[键](集合)` | **取元**(与 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) |
|
||||
|
||||
@@ -616,3 +618,4 @@ FnDef.params:
|
||||
| 2026-09-13 | 决议空返回(§7.2)与提及性反引号(§4.4);形参改为「升参」与绑定图分离(§8.2) |
|
||||
| 2026-09-14 | §7.2:`---` 不再收束;返回语句结束函数体解析;空返回首选 `*None*` |
|
||||
| 2026-09-14 | 取元主语法改为 `[键](集合)`;脚注取元过渡保留 |
|
||||
| 2026-09-24 | Artifact Metadata Binding(`${…}` Phase 1,仅 frontmatter):见 [binding.md](binding.md) · ADR 0006 |
|
||||
@@ -130,7 +130,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
## 5. Frontmatter 与跨文件
|
||||
|
||||
文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
|
||||
文件头 `---` 对为 **Artifact Metadata**。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。其它 `key: value` 可为字面量或 **Binding**(`${env.NAME}` 等,加载期解析);见 [binding.md](binding.md)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||||
|
||||
|
||||
@@ -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)) |
|
||||
|
||||
解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。
|
||||
+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 自身 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -34,7 +34,16 @@
|
||||
|
||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
||||
|
||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
||||
**推荐(块内元数据)**:在 `$$` 体内用 TeX 注释声明变量(见 [fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)):
|
||||
|
||||
````markdown
|
||||
$$
|
||||
% marqdo: var=f
|
||||
sin(x) + x
|
||||
$$
|
||||
````
|
||||
|
||||
**兼容**:空 RHS 赋值后跟展示数学块(与 `` `xs` = `` 后跟表格一致):
|
||||
|
||||
````markdown
|
||||
# main
|
||||
@@ -52,13 +61,14 @@ $$
|
||||
也支持:
|
||||
|
||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`(历史面)
|
||||
- 行内:`` `g` = $x+1$ `` 或 `` `g` = $$x+1$$ ``
|
||||
|
||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
||||
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区裸 `$$` 若既无空 RHS 又无 `% marqdo: var=` → 报错。
|
||||
|
||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
||||
**行内 `$…$`:** 传统绑定 `` `名` = $…$ `` → `formula`;**不**使用 `$% marqdo:…$`(会破坏 Markdown/TeX 识别)。
|
||||
|
||||
### 2.3 从文本构造
|
||||
|
||||
|
||||
@@ -8,9 +8,11 @@
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` → `marqdo view`(及静态 `view output`)在对应语句下显示 **output-card**,并在源码面用 **writeback** 样式标出块本身。
|
||||
|
||||
## 存储格式
|
||||
## 存储格式(两种,可并存)
|
||||
|
||||
### 1. HTML 注释(文本 / 结构化输出)
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
@@ -30,11 +32,26 @@ pending
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
### 2. Markdown 图片(生成图 / 审计友好)
|
||||
|
||||
当 `value` **看起来像图片引用**(扩展名 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.svg` / …,或 `data:image/…`)时,`record` **自动**写成:
|
||||
|
||||
```markdown
|
||||

|
||||

|
||||
```
|
||||
|
||||
- 普通 Markdown 预览即可看见图;view / 静态站额外加 writeback 标记与 output-card 中的 `<img>`。
|
||||
- 非图片路径仍走注释块;把非图片硬写成 `` 时扫描会忽略(校验失败)。
|
||||
- `list` / `scan_path` 结果带 `kind`: `comment` | `image`。
|
||||
|
||||
### 共用规则
|
||||
|
||||
- 标记字为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
- 默认在**调用行下方**插入或替换紧邻**无键**块
|
||||
- `at_end=true`:替换文件末尾的**无键**块
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
|
||||
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽;`ensure` 在缺失时写入占位且不覆盖已有正文
|
||||
- `line=` / `行=`:显式锚点行号;主机侧有全局互斥锁
|
||||
|
||||
### 替换跨度与空行
|
||||
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# Ubuntu PPA packaging (Marqdo)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** — `ppa:cflmy/marqdo`; noble builds need bundled Rust (Cargo.lock v4) |
|
||||
| Maintainer | cflmy \<pingan@cflmy.cn\> |
|
||||
| GPG | `505943294D04C803` (fingerprint `52A1…C803`) |
|
||||
| PPA | `ppa:cflmy/marqdo` |
|
||||
|
||||
## Goal
|
||||
|
||||
Users install with:
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:cflmy/marqdo
|
||||
sudo apt update
|
||||
sudo apt install marqdo
|
||||
```
|
||||
|
||||
CLI and extension packs stay independent: the `.deb` ships the **interpreter**; `marqdo ext add …` still pulls from **https://ext.marqdo.com** (then GitHub / proxy).
|
||||
|
||||
## Why bundled Rust?
|
||||
|
||||
Ubuntu **noble** ships cargo/rustc **1.75**, which cannot parse **Cargo.lock version 4** (`lock file version 4 requires -Znext-lockfile-bump`). Launchpad builders also have **no network**, so `ppa-build-source.sh` vendors crates **and** installs a modern toolchain into `third_party/rust` inside the `.orig.tar.xz`. `debian/rules` prefers that toolchain over distro cargo.
|
||||
|
||||
## One-time Launchpad setup
|
||||
|
||||
1. Create PPA: https://launchpad.net/~cflmy/+activate-ppa → name e.g. `marqdo`
|
||||
2. OpenPGP key already on Launchpad (done)
|
||||
3. Sign Ubuntu Code of Conduct if Launchpad asks
|
||||
4. Enable the Ubuntu **series** you upload for (e.g. noble) under PPA → Change details
|
||||
5. On the build machine:
|
||||
|
||||
```bash
|
||||
sudo apt install build-essential debhelper devscripts dput lintian \
|
||||
dpkg-dev quilt cargo rustc pkg-config curl xz-utils
|
||||
```
|
||||
|
||||
## Package layout
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `debian/control` | Metadata (amd64; no distro cargo BD) |
|
||||
| `debian/changelog` | Upload revisions (`1ppaN`) |
|
||||
| `debian/rules` | `dh` + bundled/system cargo build |
|
||||
| `scripts/ppa-build-source.sh` | Vendor + bundle Rust + `debuild -S` |
|
||||
| `scripts/ppa-ship.sh` | apt deps + build + `dput` |
|
||||
|
||||
## Versioning
|
||||
|
||||
- Upstream SemVer: `Cargo.toml` / git tag `vX.Y.Z`
|
||||
- Debian revision: `X.Y.Z-1ppaN~SERIES` (SERIES = `noble`, …) — bump `1ppaN` on packaging-only reuploads
|
||||
- **Ext pack** SemVer (`ext/VERSION`) is **not** the deb version
|
||||
|
||||
## One-shot (recommended)
|
||||
|
||||
```bash
|
||||
cd ~/work/marqdo
|
||||
./scripts/ppa-ship.sh noble # tools → debuild -S → dput
|
||||
./scripts/ppa-ship.sh noble -n # build only
|
||||
```
|
||||
|
||||
If automation cannot enter sudo/GPG, tell the user these commands (do not invent alternatives):
|
||||
|
||||
```bash
|
||||
./scripts/ppa-build-source.sh noble
|
||||
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
|
||||
```
|
||||
|
||||
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
|
||||
|
||||
## Failure notes
|
||||
|
||||
| Symptom | Fix |
|
||||
|---------|-----|
|
||||
| `lock file version 4 requires -Znext-lockfile-bump` | Rebuild with current `ppa-build-source.sh` (bundles Rust); bump `1ppaN` |
|
||||
| `failed to calculate checksum of: …/vendor/…/Cargo.toml.orig` | `dh_clean` purged `*.orig`; fixed via `dh_clean -Xvendor/` (+ strip `.orig` only when **creating a new** orig); bump `1ppaN` with **`-sd`** |
|
||||
| `orig.tar.xz already exists … different contents` | Never rewrite an uploaded upstream `.orig`; reuse PPA file (`ppa-build-source.sh` downloads it) and `debuild -S -sd` |
|
||||
| Same version rejected by Launchpad | Bump `debian/changelog` (`1ppa2`, …) |
|
||||
| Wrong series | Enable series on PPA; rebuild with that series name |
|
||||
|
||||
## Out of scope (v1 deb)
|
||||
|
||||
- Shipping `ext/native/*.so` inside the deb (use CDN `ext add`)
|
||||
- WASM / VSIX / non-amd64
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
||||
| 相关 | [view.md](view.md) · [view-static-interactive.md](view-static-interactive.md)(静态交互 / 公式代码视觉 · Proposal) · 源目录 [`public/`](../../public/) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,14 +4,14 @@
|
||||
|---|---|
|
||||
| 状态 | **v1(独立 debug 页)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [view-document-annotations.md](view-document-annotations.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
|
||||
## 分工
|
||||
|
||||
| 命令 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
||||
| `marqdo view` | 文档浏览器:**叙述保真文档面** Structure + Execution + Source;函数大纲与搜索;跑后引出标注;**无断点**(见 [view-document-annotations.md](view-document-annotations.md)) |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;AST Structure + BP;**仅 live** |
|
||||
|
||||
静态 `gh-pages` / `view output` **不能**真断点。
|
||||
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
# View:文档面与结果引出标注
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [view-prose-annot-gaps.md](view-prose-annot-gaps.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 是叙述与程序的同一载体。`marqdo view` 的 Structure 必须**保真叙述**,并在可执行标记旁展示运行结果。
|
||||
|
||||
旧 Browse Structure 用 AST 卡片重建语句,并用 `emit_comments` 只插入**语句行之前**的注释。当叙述与 `**…**` / `*…*` / `` `名` `` 在同一行时,该行被 Stmt 占用,叙述被丢弃——信息密度接近 debug,不适合文档浏览。
|
||||
|
||||
## 2. 模式分工
|
||||
|
||||
| 命令 | Structure | 叙述 | 结果 |
|
||||
|------|-----------|------|------|
|
||||
| `marqdo view`(Browse) | **文档面** | 保留并为主 | 跑后引出标注(callout + CSS L-leader) |
|
||||
| `marqdo debug` | AST 卡片 + BP gutter | 弱化/可折叠 | Variables / 步进;不做文档 callout |
|
||||
|
||||
断点与逐步执行**仅**在 debug。静态 `view output` 与 live view **共用** Browse 文档面渲染。
|
||||
|
||||
## 3. 视觉语法
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注
|
||||
```
|
||||
|
||||
1. 叙述正文正常排版(Markdown)。
|
||||
2. 可执行片段高亮,并带底部分割线(underline)。
|
||||
3. 段落下方 **annotation band** 放结果 callout。
|
||||
4. **CSS L-leader**(绝对定位小盒 + `border-left` + `border-bottom`)连接锚点与 callout。**不使用 SVG。**
|
||||
5. 拥挤 / 极窄屏 / `prefers-reduced-motion`:取消长横折,改为编号 keyed 列表。
|
||||
|
||||
关联强度(递减):同色 underline + callout 色条 + label → CSS L-leader → keyed 编号。
|
||||
|
||||
对齐 [view.md](view.md) HIG:系统字体、无外链、浅色、克制装饰。
|
||||
|
||||
## 4. 文档面渲染
|
||||
|
||||
实现:`src/view/document.rs`;Browse 入口经 `render_module_structure` 调用。
|
||||
|
||||
| 源内容 | 呈现 |
|
||||
|--------|------|
|
||||
| 纯叙述段 | Markdown HTML;无 `comment` badge / 厚卡片 |
|
||||
| 含 `ProseBit` 的行 | 原文保留;Decl / BoldCode / ItalicReturn 包 `mark.mq-anchor`(字节偏移来自 `scan_prose_line`) |
|
||||
| 整行结构(`#` / `>` / `-` / `1.` / 表) | 表面语法保真(见 [view-markup-surface.md](view-markup-surface.md));整句可作锚点 |
|
||||
| 函数标题 | 轻量 heading + `id="fn-{line}"`(大纲跳转不变) |
|
||||
|
||||
Debug 仍走 `render_module_structure_mode(..., Debug)` 的 AST 卡片路径。
|
||||
|
||||
## 5. ViewAnnot
|
||||
|
||||
跑后(或 `--no-exec` 时为空)组装标注集,嵌入文档面 `data-*` 与 band HTML。
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `id` | 稳定短 id(页内唯一) |
|
||||
| `kind` | `bind` · `return` · `call` · `expr` · `branch` · `loop` · `writeback` |
|
||||
| `anchor_line` | 1-based 源行 |
|
||||
| `anchor_byte_start` / `anchor_byte_end` | 行内字节范围(可选;整行锚点可省略 end) |
|
||||
| `label` | 短标题(名 / return / arm / loop) |
|
||||
| `value` | 截断显示 |
|
||||
| `detail` | 完整文本(inspect) |
|
||||
|
||||
| kind | 数据来源 | 锚点 |
|
||||
|------|----------|------|
|
||||
| `bind` | **StmtEvent post-stmt**(赋值执行后的值);禁止用入口终态回填初始化行 | 该赋值行 |
|
||||
| `return` | 返回事件或入口返回 | ItalicReturn / Return |
|
||||
| `call` / `expr` / `writeback` | writeback 槽、调用摘要 | 语句行或 BoldCode |
|
||||
| `branch` | `ViewTrace`:命中 arm、次数 | 条件 / arm |
|
||||
| `loop` | `ViewTrace`:迭代次数、末次 item | While / ForEach 头 |
|
||||
|
||||
标记面、结构块、多调用帧与 AI JSON 见 [view-execution-trace.md](view-execution-trace.md)。
|
||||
|
||||
`ViewTrace` 由 tree 解释器在 capture 时静默收集,**不**写入 stderr;与 `trace_eval` 调试轨迹分离。Bytecode 后端可暂无 trace(标注降级为 writeback)。
|
||||
|
||||
## 6. 布局与密度
|
||||
|
||||
- 每段默认最多 **4** 个常显 callout;其余 hover / 「show more」。
|
||||
- Leader:按锚点 x 排序 callout,避免交叉;窄屏改为短竖线 + 堆叠。
|
||||
- 客户端:`ResizeObserver` 重算 leader 盒的 `left/top/width/height`。
|
||||
- 静态导出:页载 JS 跑一次布局。
|
||||
|
||||
右侧 **Variables** 仍为全集绑定;callout 为就地摘要,点击可打开同一 inspect。
|
||||
|
||||
## 7. 非目标
|
||||
|
||||
- 不在 view 内做断点 / 单步(见 [view-debug.md](view-debug.md))。
|
||||
- 不新增作者侧标注 DSL / frontmatter 指令。
|
||||
- 不引入外链字体、npm 组件或 SVG leader。
|
||||
- 不把 DB/auth 等塞进 view 壳层。
|
||||
|
||||
## 8. 验收
|
||||
|
||||
1. `inc-prose.mq.md`:叙述「对于输入变量…」完整可见;`n` / `n=n+1` / 返回高亮。
|
||||
2. 跑完后:值经 underline + CSS L-leader 连到下方标注(无 SVG)。
|
||||
3. 分支/循环样例:可见命中 arm 与迭代次数(有 ViewTrace 时)。
|
||||
4. `marqdo debug` 仍为 AST + 断点;叙述不抢主视觉。
|
||||
5. 无外链字体/新依赖;`view output` 可离线打开。
|
||||
|
||||
## 9. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:文档面、ViewAnnot、CSS L-leader、与 debug 分工 |
|
||||
| 2026-10-15 | bind = post-stmt;交叉链 view-execution-trace |
|
||||
@@ -0,0 +1,103 @@
|
||||
# View:执行轨迹与文档面保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [view.md](view.md) · [view-markup-surface.md](view-markup-surface.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`marqdo view` Browse Structure 必须同时做到:
|
||||
|
||||
1. **标记面**:变量名 / 可执行语句 / 返回值按表面渲染(无源码定界符字面量)。
|
||||
2. **结构块**:GFM 表、循环(`-`)、分支(`1.`)有正确 HTML 与缩进。
|
||||
3. **语句后值**:赋值行标注该语句执行后的值,不用入口终态回填。
|
||||
4. **执行臂**:高亮实际走的分支臂。
|
||||
5. **多调用帧**:同函数多次调用可用下拉切换经历。
|
||||
6. **AI 可读**:与 HTML 同源的 `ViewExecutionReport` JSON。
|
||||
|
||||
Debug 仍用 AST 卡片 + 断点;不做文档 callout。
|
||||
|
||||
## 2. 标记面
|
||||
|
||||
| 源标记 | 显示(无定界符) | class |
|
||||
|--------|------------------|-------|
|
||||
| `` `名` `` / `` `名`=默认 `` | `名`(默认次要后缀) | `mq-anchor mq-decl` |
|
||||
| `**…**`(可执行) | 内层文本 | `mq-anchor mq-code` |
|
||||
| `*…*`(返回) | 内层文本 | `mq-anchor mq-return` |
|
||||
|
||||
`data-byte-start/end` 仍为源码字节偏移(供 CSS L-leader)。软强调不进 anchor。
|
||||
|
||||
## 3. 结构块
|
||||
|
||||
| 块 | 呈现 |
|
||||
|----|------|
|
||||
| GFM 表 | `<table class="doc-table">` |
|
||||
| `-` 循环 | `<ul class="doc-loop">`,体按源缩进 `--doc-indent` |
|
||||
| `1.` 分支 | `<ol class="doc-branch">`;命中 `arm-taken`,未走 `arm-miss` |
|
||||
| 公式 / 外联代码 | 现有 formula-card / code-card |
|
||||
| `>` 调用 | 表面高亮,非整行灰 code |
|
||||
|
||||
## 4. StmtEvent / CallFrame
|
||||
|
||||
解释器 capture 时静默采集(非 `trace_eval` stderr):
|
||||
|
||||
```text
|
||||
StmtEvent {
|
||||
line, kind, // assign | return | call | branch | loop | bind_ref
|
||||
name?, value_after?, // post-stmt 或求值结果
|
||||
arm_index?, iter?,
|
||||
call_id // 当前用户函数调用帧
|
||||
}
|
||||
|
||||
CallFrame {
|
||||
call_id, fn_name, fn_line, ordinal,
|
||||
args_brief, // 短摘要供下拉
|
||||
events[] // 或全局 events 用 call_id 过滤
|
||||
}
|
||||
```
|
||||
|
||||
- Assign → 写入后的值挂在**该行**。
|
||||
- 循环内多次写入:UI 默认末次;可带次数。
|
||||
- Branch → taken `arm_index` + 条件摘要。
|
||||
- 进入用户函数分配 `call_id`;`# main` 单帧无下拉。
|
||||
|
||||
## 5. ViewExecutionReport(AI)
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"path": "…",
|
||||
"ok": true,
|
||||
"calls": [{ "call_id": 1, "fn": "等级说明", "ordinal": 1, "args_brief": "等级=及格" }],
|
||||
"events": [{ "line": 24, "kind": "assign", "name": "总分", "value_after": "0", "call_id": 0 }],
|
||||
"bindings_final": { "均分": "73", "等级": "及格" }
|
||||
}
|
||||
```
|
||||
|
||||
产出:页内 `#mq-view-trace` JSON;live `GET /api/view-trace?path=`;SSE `done.trace_json`。
|
||||
|
||||
## 6. UI
|
||||
|
||||
- 函数标题旁 `<select class="call-picker">`(调用数 ≥ 2)。
|
||||
- 循环头旁 `<select class="loop-picker">`(迭代数 ≥ 2);默认最后一轮;摘要 `分 = 分数表[i] · value`。
|
||||
- **源码常显**:切换帧只改 chip / 臂高亮,不 `hidden` 结构节点。详见 [view-frame-selection.md](view-frame-selection.md)。
|
||||
- CSS L-leader(非 SVG);拥挤 keyed 降级。
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. 无字面 `**` / 返回定界 `*` / 变量外层 `` ` ``(Source 除外)。
|
||||
2. 表为真表格;循环/分支有缩进列表;未选中臂源码仍可见。
|
||||
3. `总分 = 0` 标注 `0`,非终态累加。
|
||||
4. 命中臂可视化;多调用下只显示当前帧的 taken。
|
||||
5. 循环可按迭代切换;JSON 含 `loops`;单测覆盖。
|
||||
|
||||
## 8. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:标记面、结构块、StmtEvent、CallFrame、AI 报告 |
|
||||
| 2026-10-15 | 帧选择保真:call_id 分支、LoopFrame、源码常显 |
|
||||
@@ -0,0 +1,123 @@
|
||||
# View:调用帧 / 循环帧选择与结构保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-execution-trace.md](view-execution-trace.md) · [view-document-annotations.md](view-document-annotations.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题(对照实测)
|
||||
|
||||
1. **结构缺失**:切换函数调用下拉时,JS 按 `data-call-id` **隐藏** `.doc-exec`。未在本帧执行的分支臂体(赋值/返回)只有其它帧的 call_id,或仅有执行帧的 id → **未选中臂的源码被藏掉**,看起来像「臂消失 / 代码没渲染」。
|
||||
2. **调用记录混叠**:`Branch` 标注未带 `call_id`;`taken_arms` 按行号只保留最后一次命中。多帧下同一分支同时出现 `arm 1 taken` 与 `arm 2 taken`。
|
||||
3. **循环无帧**:循环只有总次数摘要;无法按迭代查看;`` - [分](分数表) `` 不能展示「当前是集合第几个元素」。
|
||||
|
||||
## 2. 定稿原则
|
||||
|
||||
| 原则 | 含义 |
|
||||
|------|------|
|
||||
| **源码常显** | 表 / 列表 / 分支臂 / 语句源码**永不**因帧选择 `hidden` |
|
||||
| **轨迹随帧** | 标注 chip、臂高亮、变量值随「当前调用帧 / 当前迭代」变化 |
|
||||
| **默认末帧** | 函数默认最后一次调用;循环默认最后一次迭代 |
|
||||
| **一帧一真相** | 同时只展示一个 call_id(函数)或一个 (loop_id, iter)(循环)的轨迹 |
|
||||
|
||||
## 3. 函数调用帧
|
||||
|
||||
### 数据
|
||||
|
||||
`BranchHit` / 相关 `StmtEvent` 必须带 `call_id`。`ViewAnnot` 的 branch/bind/return 同样带 `call_id`。
|
||||
|
||||
### UI
|
||||
|
||||
- 函数标题旁 `<select class="call-picker" data-fn="…" data-scope="fn">`
|
||||
- 选项:`1: 等级=及格` / `2: 等级=优秀`
|
||||
- 默认选中最后一次
|
||||
|
||||
### 客户端(`applyCallFrame`)
|
||||
|
||||
1. 读 `#mq-view-trace` JSON。
|
||||
2. 过滤 `events` where `call_id == selected`。
|
||||
3. **不**设置结构节点 `hidden`。
|
||||
4. 更新该函数作用域内:
|
||||
- `.annot-chip[data-call-id]`:仅显示匹配帧;无 call_id 的结构说明类可保留
|
||||
- `.doc-branch[data-line]`:按该帧的 branch 事件设置 `arm-taken` / `arm-miss`(全部臂仍可见)
|
||||
- 绑定 chip 的 `.annot-value`:用该帧 assign/return 事件刷新(同名同行取末次)
|
||||
|
||||
## 4. 循环迭代帧
|
||||
|
||||
### 数据
|
||||
|
||||
```text
|
||||
LoopFrame {
|
||||
loop_id, line,
|
||||
item_name?, // "分"
|
||||
collection?, // "分数表"
|
||||
iterations: [{ index, item_value, call_id }] // index 0-based
|
||||
}
|
||||
```
|
||||
|
||||
`StmtEvent` 增加可选 `loop_id`;循环体内事件带 `iter`(1-based 或 0-based,JSON 内统一 **0-based index**)。
|
||||
|
||||
### UI
|
||||
|
||||
- 循环头(`- [分](分数表)`)旁:`<select class="loop-picker" data-loop-id="…">`
|
||||
- 选项:`迭代 1: 分=92` … `迭代 4: 分=88`
|
||||
- 默认最后一次
|
||||
- 头旁摘要 chip:`分 = 分数表[3] · 88`(下标 0-based 显示为 `[i]`)
|
||||
|
||||
### 客户端(`applyLoopFrame`)
|
||||
|
||||
1. **只显示当前迭代**:带 `data-iter` 的 chip 仅保留选中项;其余 `hidden` + `is-frame-hidden`(SSR 默认已按末轮预隐藏)。
|
||||
2. 更新头摘要 chip(无 `data-iter`)为当前选项文案。
|
||||
3. 不隐藏循环体源码。
|
||||
|
||||
## 5. 分支臂渲染
|
||||
|
||||
- 所有臂(含 else)**始终**渲染完整头 + 体(含 `*返回*` / 赋值)。
|
||||
- `arm-miss` 仅降低不透明度,**不** `display:none` / `hidden`。
|
||||
- 高亮仅反映**当前帧**的 taken `arm_index`。
|
||||
|
||||
## 6. AI JSON 增量
|
||||
|
||||
`ViewExecutionReport` 增加:
|
||||
|
||||
```json
|
||||
"loops": [{
|
||||
"loop_id": 1,
|
||||
"line": 27,
|
||||
"item": "分",
|
||||
"collection": "分数表",
|
||||
"iters": [{ "index": 0, "value": "92" }, { "index": 3, "value": "88" }]
|
||||
}]
|
||||
```
|
||||
|
||||
`events[].call_id` 必填;循环体内事件带 `loop_id` + `iter`(index)。
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. 未选中分支臂源码始终可见(含返回句)。
|
||||
2. 切换「等级说明」调用:只显示该帧的 arm taken;变量/返回值对应该帧。
|
||||
3. 循环下拉默认最后一轮;`分 = 分数表[3] · 88`;切换迭代后体内累加值变化。
|
||||
4. `#mq-view-trace` 含 `loops` 与带 `call_id` 的 branch 事件。
|
||||
5. `cargo test --lib view::` 全绿。
|
||||
|
||||
## 8. 开发计划(已执行)
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| D0 | 本文档 + `view-execution-trace.md` 交叉引用 | ✅ |
|
||||
| D1 | `BranchHit.call_id`;`LoopFrame` / `LoopIter`;`StmtEvent.loop_id` | ✅ |
|
||||
| D2 | 解释器:foreach/while 推栈;BindRef `分=分数表[i]`;assign 带 iter | ✅ |
|
||||
| D3 | `build_view_annots`:分支带 call_id;LoopFrame 选项;报告 JSON `loops` | ✅ |
|
||||
| D4 | 文档面:源码不贴 `data-call-ids`;call picker `value=call_id`;loop picker;SSR taken=末帧 | ✅ |
|
||||
| D5 | JS:`applyCallFrame` / `applyLoopFrame` — 只滤 chip + 重算 arm,不 hidden 结构 | ✅ |
|
||||
| D6 | 单测:多调用不同臂、loop 末项、HTML 三臂返回 + picker | ✅ |
|
||||
|
||||
## 9. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:源码常显、帧过滤、循环迭代 picker |
|
||||
| 2026-10-15 | 按计划落地 D1–D6 |
|
||||
@@ -0,0 +1,145 @@
|
||||
# View:叙述面标注缺口(prose annot gaps)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [view-frame-selection.md](view-frame-selection.md) · [view-execution-trace.md](view-execution-trace.md) |
|
||||
|
||||
> **定位**:对既有文档面设计的**缺口专章**——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何「改了却几乎没变化」
|
||||
|
||||
| 原因 | 说明 |
|
||||
|------|------|
|
||||
| 错二进制 | PATH 上的 `marqdo` 可能仍是旧版(如 1.3.0);改动在源码 / `./target/debug/marqdo`。验收必须用 `cargo build && ./target/debug/marqdo view …` |
|
||||
| Chip 被溢出藏掉 | 同 band 堆多帧 return/print/who;`MAX_VISIBLE_ANNOTS=4` 把当前帧的 `who` 打成 `annot-chip-overflow`(`display:none`);帧切换不重算溢出 |
|
||||
| L-leader 几何错位 | `initAnnotLeaders` 里 `y0=0` 只在 `.annot-band` 顶画短折,**连不到**上方 underline;窄屏或 chip>4 时整段关掉 leaders |
|
||||
| 旧静态快照 | gh-pages / 旧 `view output` 不会自动刷新 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标视觉语法(既有,不新造)
|
||||
|
||||
锚定 [view-document-annotations.md](view-document-annotations.md) §3:
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注 chip
|
||||
```
|
||||
|
||||
- underline:`mark.mq-anchor.mq-{decl|code|return}`
|
||||
- band:段落下方 `.annot-band` → leaders + chips
|
||||
- L-leader:CSS `border-left` + `border-bottom`(禁止 SVG)
|
||||
- 公式/代码:[view-static-interactive.md](view-static-interactive.md) G3 **一层主视觉**;卡下不叠 Bind dump
|
||||
- 帧:[view-frame-selection.md](view-frame-selection.md) **源码常显、只滤 chip**;默认末帧
|
||||
|
||||
---
|
||||
|
||||
## 3. 管线
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
CLI["marqdo view / view output"] --> build["build_file_view"]
|
||||
build --> cap["run_file_capture"]
|
||||
cap --> annot["build_view_annots"]
|
||||
annot --> doc["document::render_module_document"]
|
||||
doc --> page["html.rs page_file"]
|
||||
page --> js["initAnnotLeaders + initCallPickers"]
|
||||
```
|
||||
|
||||
| 步骤 | 位置 |
|
||||
|------|------|
|
||||
| CLI / 导出 | `src/main.rs` · `src/view/mod.rs` · `src/view/output.rs` |
|
||||
| Capture + Call 事件 | `src/interp.rs` |
|
||||
| Annot 组装 | `src/view/annot.rs` `build_view_annots` |
|
||||
| 文档面 HTML | `src/view/document.rs` |
|
||||
| 卡片 chrome | `src/view/render.rs` `render_*_assign_card` |
|
||||
| CSS / leader JS | `src/view/html.rs` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 四条用户问题 → 根因 → 验收
|
||||
|
||||
复现源:`public/00-welcome.mq.md` · `public/00-欢迎.mq.md`
|
||||
对照金样:`tests/view/document-annot-demo.mq.md` · `tests/markup-v03/inc-prose.mq.md`
|
||||
|
||||
### P1 — 叙述与代码同段时信息不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | underline 在,chip / 连线弱或无 |
|
||||
| 根因 | `html.rs` `initAnnotLeaders`:`y0=0` 相对 band;`document.rs` `MAX_VISIBLE_ANNOTS` 把当前帧 chip 溢出;PATH 旧 CLI |
|
||||
| 目标 | 同 `inc-prose`:underline + L-leader(从锚点底到 chip)+ 可见 chip |
|
||||
| 验收 | `./target/debug/marqdo view public/00-welcome.mq.md`:主文 `**greet…**` 与 `## greet` 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
|
||||
|
||||
### P2 — 函数内变量不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `` `who` `` 有浅蓝 underline,无值 chip |
|
||||
| 根因 | bind chip 存在但带 `annot-chip-overflow`;`applyCallFrame` 只 `hidden` 非选中帧,不解除当前帧 overflow |
|
||||
| 目标 | 选中调用帧时常显 `who` · `print` · `return` 各一枚 |
|
||||
| 验收 | 切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
|
||||
|
||||
### P3 — ` ```text ` 渲染不一致
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 变成内联 `text marqdo ext add…`,无卡片 |
|
||||
| 根因 | Comment 围栏若进 `flush_para` → `join(" ")` → pulldown 当 inline code;应走 `render_narrative_fence` |
|
||||
| 目标 | 与 bound python 同 `.code-card` chrome(badge + `pre.code-body`),**无** Run/foot |
|
||||
| 验收 | welcome install 段:`data-lang="text"` + 两行 `marqdo ext add`;无 `<code>text marqdo` |
|
||||
|
||||
### P4 — 函数引用 / 代码卡未渲染
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `**greet who=…**` 无结果;或 `hi` python 只见头/Run、不见源码 |
|
||||
| 根因 | 同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
|
||||
| 目标 | 主文两 greet 各有 call chip(stdout 摘要);`hi` = `render_code_assign_card` head→body→foot;静态藏 Run |
|
||||
| 验收 | 两枚 greet mark 均有非空 `data-annot-id`;`code-body` 含 `hello-from-python`;`MARQDO_VIEW_LIVE=false` 无 Run 按钮 |
|
||||
|
||||
### call_id 语义(写死)
|
||||
|
||||
| 位置 | call_id |
|
||||
|------|---------|
|
||||
| 主文 `**greet…**` 的 call chip | 入口帧(`# main` 的 call);结果为 stdout/返回摘要 |
|
||||
| `## greet` 体内 print / who / return | callee 的 CallFrame id;跟函数标题旁 picker |
|
||||
|
||||
---
|
||||
|
||||
## 5. 修复约定(实现红线)
|
||||
|
||||
1. **帧感知密度**:band 内按选中 `call_id` 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + `layoutAll()`。
|
||||
2. **Leader 容器**:提升到 `.doc-block`(prose + band);`y0` = 锚点底相对 block;按锚点 x 排序再画线。
|
||||
3. **卡片**:只复用 Browse `render_*_assign_card` / `render_narrative_fence` + `html.rs` `.code-*` / `.formula-card`;本波不改 Debug AST 路径(除非回归红)。
|
||||
4. **静态 Run**:`MARQDO_VIEW_LIVE=false` 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
|
||||
5. **非目标**:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收命令
|
||||
|
||||
```bash
|
||||
cargo build -q
|
||||
./target/debug/marqdo version # 须为当前工作树版本
|
||||
./target/debug/marqdo view public/00-welcome.mq.md --no-open
|
||||
./target/debug/marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
cargo test -q --lib view::
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
|
||||
| 2026-10-15 | L-leader 拥挤/消失:同跨度多帧 chip **共用 annot id**;可见 chip 按锚点 x 重排;leader 挂 doc-block |
|
||||
| 2026-10-15 | L-leader 黑线碎段:JS `border*: "1.5px solid"` 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
|
||||
| 2026-10-15 | L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |
|
||||
@@ -0,0 +1,239 @@
|
||||
# View:静态页交互与公式/代码卡视觉
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view.md](view.md) · [user-site.md](user-site.md) · [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [ADR 0002 browser WASM](../adr/0002-browser-marqdo-wasm.md) |
|
||||
|
||||
**已确认(2026-10-15)**
|
||||
|
||||
| 决策 | 选择 |
|
||||
|------|------|
|
||||
| 引擎 | **B**(快照 + S1 帧切换 + 可选懒加载 WASM S2) |
|
||||
| 体验原则 | 静态页与 live view **尽量同构**;控件形态对齐;无服务端时用 WASM/JS 补齐 |
|
||||
| 视觉原则 | **一层主视觉**;一眼能懂;公式/代码不与 Bind chip / 源残留叠床架屋 |
|
||||
| 演示参数条 | **要**(历史实参 select + 可编辑;S1 切帧 / S2 重跑) |
|
||||
| code-card Run | 有 WASM 时可用;否则隐藏(不对齐「假按钮」) |
|
||||
| 公式 Bind chip | **卡内不显示**;Variables 可留终值 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机(对照 `public/00-欢迎.mq.md` / gh-pages)
|
||||
|
||||
静态导出(`marqdo view output` → `gh-pages`)与 live `marqdo view` 已共用**文档面 Structure** 渲染路径,但用户站实测仍有三类落差:
|
||||
|
||||
1. **交互控件缺失 / 偏弱**
|
||||
- 函数「问候」仅有参数 chip「谁」,没有可切换的调用帧下拉(即便源里 `> 问候` 写了两次)。
|
||||
- 参数行 `+ 谁` 在文档面呈声明高亮,读者无法在静态页改「谁」并看到新输出。
|
||||
- 外联 `code-card` 的 Run 在静态模式被禁用(`Run is available in live marqdo view`)。
|
||||
- 静态 stdin 仅在有 preset 时显示只读提示,**不能**再跑。
|
||||
|
||||
2. **无服务端时仍可交互的预期**
|
||||
用户站是纯静态托管:没有 `/api/run`。合理路径是 **页内 JS** 和/或 **嵌入 Marqdo WASM**,在浏览器里重算 Structure 标注、Execution 区,甚至模拟 `input` / 外联(沙箱约束另定)。
|
||||
|
||||
3. **公式 / 代码块视觉凌乱**
|
||||
同一赋值同时出现多层表象,信息重复、线框错位:
|
||||
|
||||
| 层 | 公式 `f = $$…$$` | 外联 `hi = ```python…``` |
|
||||
|----|------------------|---------------------------|
|
||||
| A 卡片 | `formula` badge + KaTeX | `code` badge + 高亮源码 + cmd/Run |
|
||||
| B 标注 chip | `f` → `x^2 - 2` | `hi` → 整段 fence 摘要 |
|
||||
| C 源残留 | 卡片外/旁再露 `$$` 或 ASCII | 卡片下再露 `python print…` 明文 |
|
||||
|
||||
再叠加 CSS L-leader 与卡内边框,首屏显得碎、重复、「坏掉的线」。
|
||||
|
||||
**本文件只定问题与方案;确认前不改代码。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状解剖
|
||||
|
||||
### 2.1 静态 vs live(同一 `page_file`)
|
||||
|
||||
| 能力 | Live | Static(`LinkMode::Static`) |
|
||||
|------|------|------------------------------|
|
||||
| 文档面 Structure + annot | ✅(跑后) | ✅(导出时跑后写入) |
|
||||
| call / loop picker JS | ✅(读 `#mq-view-trace`) | ✅(同源 JS;若轨迹未写入则无控件) |
|
||||
| `/api/run` · Stream | ✅ | ❌ |
|
||||
| stdin 表单 | ✅ 可再跑 | 只读 hint(或无) |
|
||||
| code-card Run | ✅ `POST` 外联 | ❌ 禁用按钮 |
|
||||
| WASM 重算 | ❌(未接) | ❌(未接) |
|
||||
|
||||
结论:**不是「静态另做一套皮肤」**,而是「导出瞬间的快照 + 部分 JS 帧切换」;**没有**浏览器内重执行闭环。
|
||||
|
||||
### 2.2 欢迎页结构(问题复现源)
|
||||
|
||||
```text
|
||||
> 问候 谁=marqdo
|
||||
> 问候 谁=marqdo user
|
||||
## 问候
|
||||
+ `谁`
|
||||
> 打印 内容=欢迎,`谁`!
|
||||
`f` = $$ x^2 - 2 $$
|
||||
`hi` = ```python … ```
|
||||
```
|
||||
|
||||
- 期望:`## 问候` 旁 **调用** 下拉(`1: 谁=marqdo` / `2: 谁=marqdo user`),切换时打印行的绑定/输出随帧变。
|
||||
- 现状风险:若导出时 CallFrame < 2、或 picker 未挂上、或读者期望的是「编辑谁」而非「选历史调用」,都会表现为「没有下拉框」。
|
||||
- 公式/代码:`SpecialAssign` → formula/code **card**,同时又对同名绑定建 **Bind annot**,文档面还可能保留块源视觉 → 三重展示。
|
||||
|
||||
### 2.3 已有红线(方案不得破坏)
|
||||
|
||||
- 代码即文档:`.mq.md` 源可读;不发明第二套嵌套 DSL(见 web-artifact / marqdo-dev)。
|
||||
- Browse ≠ Debug:静态站不做断点。
|
||||
- `public/**/*.html` 不入库;gh-pages 由 CI/`view output` 生成([user-site.md](user-site.md))。
|
||||
- 外链字体禁令仍在 [view.md](view.md);WASM/重型资源须 **可选加载**,默认站可降级为纯快照。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标(验收口径)
|
||||
|
||||
### G1 — 帧与参数交互(静态可读、可拨)
|
||||
|
||||
1. 同函数 ≥2 次调用时,静态页 **必有**「调用」下拉;默认末次;切换只改 chip/臂/相关输出,**源码常显**(同 [view-frame-selection.md](view-frame-selection.md))。
|
||||
2. 导出保证写入完整 `#mq-view-trace`(含 `calls` / `events` / 可选 `loops`)。
|
||||
3. (增强)演示向参数可提供 **受控输入**:默认值来自末次调用或 FM;改参后可触发页内重算(见 §5 引擎选项)。
|
||||
|
||||
### G2 — 无服务端可重算(可选引擎)
|
||||
|
||||
| 档位 | 能力 | 依赖 |
|
||||
|------|------|------|
|
||||
| **S0 快照**(现状加强) | 导出时跑完;帧 picker;只读 Execution | 无 WASM |
|
||||
| **S1 页内重放轨迹** | 不重跑程序,只切换已序列化帧/标注 | JSON only |
|
||||
| **S2 WASM 重跑** | `marqdo_wasm` + bridge:改 stdin/实参后重跑,刷新 Structure/Execution | WASM 包(可 CDN/`public/wasm/`) |
|
||||
| **S3 外联沙箱** | code-card Run:浏览器内 pyodide **或** 明确标「仅 live」 | 可选;默认可关 |
|
||||
|
||||
默认用户站:**S0 + S1 必达**;**S2 为推荐主路径**(与「用 wasm 模拟输出」对齐);S3 单独开关。
|
||||
|
||||
### G3 — 公式 / 代码视觉单层真相
|
||||
|
||||
对「特殊赋值」块约定 **一层主视觉 + 至多一层结果**:
|
||||
|
||||
| 块 | 主视觉 | 允许的结果层 | 禁止 |
|
||||
|----|--------|--------------|------|
|
||||
| 公式 | KaTeX(formula-card 精简) | 无 Bind chip,或仅在 Variables | 再渲一份 `$$` 明文;annot 与卡重复同一 TeX |
|
||||
| 外联代码 | 高亮源码(code-card) | 运行输出区 `code-out`;静态可藏 Run 或接 S2/S3 | annot 再贴整段 fence;卡下重复裸源 |
|
||||
| 普通赋值 | 标记面语句 | Bind chip + L-leader | — |
|
||||
|
||||
Leader:仅连接「主视觉锚点 → 唯一结果 chip」;卡内不用第二套 L 线。
|
||||
|
||||
---
|
||||
|
||||
## 4. 问题清单(成文)
|
||||
|
||||
| ID | 问题 | 严重度 | 根因假设 |
|
||||
|----|------|--------|----------|
|
||||
| P1 | 静态页看不到调用/循环下拉 | 高 | 轨迹未导出完整 / picker 条件(≥2)未满足 / 读者要的是编辑参而非选帧 |
|
||||
| P2 | 不能改参/stdin 再看输出 | 高 | Static 禁用 `/api/run`;无 WASM 闭环 |
|
||||
| P3 | code-card Run 静态无效 | 中 | `initForeignCards` 显式禁用 |
|
||||
| P4 | 公式卡 + chip + `$$` 三重 | 高 | card 与 Bind annot 叠加;块源未完全被 SpecialAssign 吞掉 |
|
||||
| P5 | 代码卡 + chip + 明文三重 | 高 | 同 P4 |
|
||||
| P6 | 卡内/旁碎线、错位 | 中 | leader 锚到错误节点;卡 CSS 与 annot-band 叠层 |
|
||||
| P7 | 静态 stdin 体验差 | 中 | 仅有只读 hint |
|
||||
|
||||
---
|
||||
|
||||
## 5. 解决方案(详案,待选)
|
||||
|
||||
### 5.1 引擎策略(三选一,推荐 **B**)
|
||||
|
||||
| 方案 | 做法 | 优点 | 代价 |
|
||||
|------|------|------|------|
|
||||
| **A. 纯快照 + S1** | 加强导出轨迹与 picker;不引入 WASM | 体积小、离线稳 | 不能改参真重算 |
|
||||
| **B. 快照默认 + 可选 WASM(S0/S1/S2)** | `view output` 仍嵌入跑后 HTML;页脚/侧栏「在浏览器中重跑」懒加载 WASM;改参后 patch Structure/Execution | 对齐用户预期;无 WASM 时仍可读 | 打包/加载体积;宿主能力子集 |
|
||||
| **C. 静态页全面 WASM 首屏** | 打开即 WASM 跑 | 交互最强 | 冷启动慢;gh-pages 带宽;与「文档先可读」冲突 |
|
||||
|
||||
**推荐 B**:文档先可读(S0),帧切换不依赖 WASM(S1),需要改参/演示时再拉 WASM(S2)。
|
||||
|
||||
### 5.2 交互控件(与文档面一致)
|
||||
|
||||
1. **调用 / 循环 picker**(已有组件)
|
||||
- 导出验收:欢迎页「问候」必须出现调用下拉。
|
||||
- 单测:对 `00-欢迎.mq.md` / `document-annot-demo` 断言 HTML 含 `call-picker` 且 options≥2。
|
||||
|
||||
2. **演示参数条(新,窄范围)**
|
||||
- 仅当函数被标记为「可演示」**或**静态页检测到 ≥1 形参且存在 CallFrame 时,在函数标题旁增加:
|
||||
`谁 [ text input | select(历史实参) ] [应用]`
|
||||
- **不**改 `.mq.md` 语法;数据来自 trace 的 `args_brief` / 末次绑定。
|
||||
- 「应用」:S1 仅切换已有帧;S2 调 WASM `run` 后替换 `#structure` / Execution。
|
||||
|
||||
3. **stdin**
|
||||
- 静态:若源含 `input`,渲染与 live 同形的 textarea +「重跑」(S2)或说明「需 WASM」。
|
||||
- 无 input 则不显示。
|
||||
|
||||
### 5.3 公式 / 代码去重(视觉)
|
||||
|
||||
**规则:SpecialAssign 行只走 card,不再为同名同值挂 Bind chip。**
|
||||
|
||||
```text
|
||||
公式赋值行
|
||||
└─ formula-card(badge + 名 + KaTeX)
|
||||
└─ ✗ 不再 render_annot_band(Bind f)
|
||||
└─ ✗ 不再在卡外输出 $$ 源
|
||||
|
||||
外联赋值行
|
||||
└─ code-card(badge + 名 + 高亮体 + 可选 Run)
|
||||
└─ ✗ 不再 Bind chip 贴 fence 全文
|
||||
└─ 运行结果只进 .code-out
|
||||
```
|
||||
|
||||
静态 Run 策略(与 §5.1 对齐):
|
||||
|
||||
- S0:隐藏 Run,或保留禁用并 tooltip「打开 live view / 启用 WASM」。
|
||||
- S2:Run → WASM 宿主 `foreign`(若 WASM 支持)或提示不支持。
|
||||
- S3:可选 Pyodide(默认关)。
|
||||
|
||||
CSS:formula-card / code-card 与 `.annot-band` 垂直节奏统一;禁止对 KaTeX 节点拉 L-leader。
|
||||
|
||||
### 5.4 导出管线
|
||||
|
||||
```text
|
||||
marqdo view output
|
||||
→ build_file_view(跑 + annot + trace_json) // 已有
|
||||
→ page_file(Static)
|
||||
+ 嵌入 #mq-view-trace
|
||||
+ (可选)data-wasm-url / 懒加载脚本
|
||||
+ 公式/代码去重后的 structure_html
|
||||
→ public/ + gh-pages
|
||||
```
|
||||
|
||||
`--no-exec`:文档面无标注;可提示「本页为结构-only」;S2 仍可尝试 WASM 首跑(可选,默认关以免惊喜执行)。
|
||||
|
||||
### 5.5 明确不做(本提案)
|
||||
|
||||
- 静态页断点调试(仍属 `marqdo debug`)。
|
||||
- 在 `public/*.mq.md` 发明新的「交互表」DSL(除非另开设计并获批)。
|
||||
- 默认全站加载 Pyodide。
|
||||
- 提交生成 HTML 进 `main`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 分阶段开发计划(确认后执行)
|
||||
|
||||
| 阶段 | 内容 | 交付 | 依赖确认 |
|
||||
|------|------|------|----------|
|
||||
| **D0** | 本文定稿;选定引擎 **A/B/C**;是否要「演示参数条」 | 状态 → Active | **本次决策** |
|
||||
| **D1** | P4/P5/P6:SpecialAssign 与 Bind 互斥;卡 CSS;去掉重复源 | 欢迎页公式/代码干净;单测 | D0 |
|
||||
| **D2** | P1:导出轨迹验收 + 欢迎页 call-picker 金样;修任何「≥2 调用无下拉」bug | HTML 断言 | D0 |
|
||||
| **D3** | P2/P7 S1 夯实:静态 stdin UI 形态;无 WASM 时文案清晰 | UX | D0 |
|
||||
| **D4** | (若选 B)S2:静态页懒加载 WASM;「应用参数 / 重跑」刷新 Structure+Execution | `public/wasm` 或 CDN 策略;体积预算 | D0=B |
|
||||
| **D5** | P3:code-card 与 S2/S3 策略落地;默认隐藏无效 Run | — | D1+D4 |
|
||||
| **D6** | `build-public` / pages CI 回归;更新 [user-site.md](user-site.md) · [view.md](view.md) 验收条 | gh-pages 抽检欢迎页 | D1–D5 |
|
||||
|
||||
建议默认路径:**D0 选 B → D1 → D2 → D3 → D4 → D5 → D6**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 决策记录
|
||||
|
||||
见文首「已确认」。开发按 §6:D1 → D2 → D3 → D4 → D5 → D6。
|
||||
|
||||
---
|
||||
|
||||
## 8. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:静态交互缺口、公式/代码凌乱、S0–S3 与阶段 D0–D6 |
|
||||
| 2026-10-15 | Active:引擎 B;对齐 live;干净视觉;演示参数条;Run 接 WASM 否则隐藏 |
|
||||
+6
-4
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.0.2 方向) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
|
||||
---
|
||||
|
||||
@@ -77,7 +77,7 @@ OUT_DIR/
|
||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
||||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||||
- 渲染逻辑与实时 `view` **共用**同一路径:`build_file_view` → 文档面 Structure(`document.rs` + annots)→ `page_file`(同一 CSS/JS,含 call/loop picker、`#mq-view-trace`)。禁止第二套皮肤。`--no-exec` 时仍出文档面,但无运行标注。
|
||||
|
||||
示例:
|
||||
|
||||
@@ -90,14 +90,16 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
|
||||
## 4. 信息架构
|
||||
|
||||
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
|
||||
侧栏文件索引 + 主区:**文档面 Structure** · 执行 · 源码。Structure(Browse)为叙述保真文档面:标记面(变量/语句/返回无源码定界符)、表/列表/分支结构保真,跑后结果经 **CSS L-leader** 引出——见 [view-document-annotations.md](view-document-annotations.md) · [view-execution-trace.md](view-execution-trace.md)。**不是** AST 卡片栈(那是 debug)。
|
||||
|
||||
结构旁**右侧栏**(现有 outline 槽)为:
|
||||
|
||||
| 区块 | 内容 |
|
||||
|------|------|
|
||||
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
|
||||
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
|
||||
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板;终态亦可刷新 Structure 内标注。
|
||||
|
||||
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
|
||||
|
||||
@@ -2,16 +2,23 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · W0–W7 + P3 完结**(2026-08-28 复核) |
|
||||
| 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核) |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
| 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈,给出「开发一个完整 Web 项目」所需能力的差距清单与补强路线 |
|
||||
| 状态 | **Historical capability matrix** — 作者面以 **[ext-web-artifact.md](ext-web-artifact.md)** / ADR [0007](../adr/0007-web-document-endpoint.md) 为准(2026-09-28) |
|
||||
| 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核)· 2026-09-28(Artifact 标注) |
|
||||
| 相关 | [ext-web-artifact.md](ext-web-artifact.md) · [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
| 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状;**下文 API 名多为 W0–W7 历史面**(`compose_*` / `configure` 已废止) |
|
||||
|
||||
> **2026-09-28**:作者面迁移到 Document / Endpoint / Resource。
|
||||
> - Document/Endpoint:`type: web|endpoint` + `web.serve` / `web.render` / `web.inspect`
|
||||
> - DB/cache/storage → `ext/data`;auth/oidc/rbac → `ext/security`;ws → `ext/net`
|
||||
> - 统一 View:`|type|slot|value|attrs|style|`;中间件:`web.use`
|
||||
> 本文件保留为**原生能力矩阵**对照,勿再按 `compose_*` / `app.configure` 写作。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**`ext/web` + `plugins/web` 已完成 W0–W7 + P3 路线图**:中间件/JSON API、数据层(连接池/事务/分页/FTS/迁移/外键/审计时间戳)、安全硬化(argon2/CSRF/会话持久化/限速/RBAC)、内容站点标配(SEO/RSS/Markdown/分页 UI)、上传下载/相册/ETag、sitemap/robots/错误页/重定向、WebSocket 广播与访问日志。足以在 Marqdo 上实现博客/CMS/中小型 API 站点;**未内置**的仅剩标签页模板(D6,可用路由+`db.count` 自建)与应用层反垃圾。边界不变:**纯解析进 `lib/net`,HTTP 服务器与领域能力进 `plugins/web` + `ext/web` 作者面**。
|
||||
**能力层(plugins/web)**:中间件/JSON API、数据层、安全、内容站点、上传下载、sitemap、WebSocket 等仍在原生实现中。
|
||||
**作者面(2026-09-28)**:改为 Artifact Metadata + facade;`compose_*` / `configure` **已删除**。边界不变:**纯解析进 `lib/net`,HTTP 服务器进 `plugins/web`,作者 API 进 `ext/web` + `ext/data` + `ext/security` + `ext/net`**。
|
||||
|
||||
**宿主集成下一刀**(同域 LLM SSE 中继、HTTP→用户 `##`、与 MCP Server 协作)不在本 W 表内,见 [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-hosting.md](../roadmap/ext-hosting.md)。
|
||||
|
||||
|
||||
+1373
File diff suppressed because it is too large.
Load diff
+933
@@ -0,0 +1,933 @@
|
||||
这是marqdo的智能体框架,我一直都不满意,我认为marqdo的智能体框架应该更好才对,因为marqdo本身就是一门极好的AI原生语言,针对这个智能体框架,我的构想是,每次执行,智能体都会沉淀mq.md文档,超过三次的调用就会自动总结优化出一份类似与记忆的mq.md文档,把每一步都拆解的非常好,类似与人类的某些学习过程,当完全学习到了一些内容,实际上后续就可以不再每次都聚精会神,而是用一种较低能耗运行,就像是我们沉淀下来的mq.md代码,其中可以使用非常少的大模型思考,或者使用类似Jev的决策模型,或者干脆只使用分支控制,之后调用即可,你觉得呢?
|
||||
|
||||
对,而且我现在觉得你这个构想**很可能比目前的 Agent 框架本身更接近 Marqdo 真正应该成为的东西**。
|
||||
|
||||
我仔细看了你上传的 `ext/ai/agent`。其实你已经无意中铺好了不少基础:现在的 `plan` 已经有 `reuse`、`near_match`、`soft_match`、`promote`、`improve_every=3` 和 `kb_dir=.marqdo/agent-kb`;命中已有 skill 后甚至可以走 `llm_free` 路径。 而且现有逻辑已经会把成功的 workbook promote 到 agent KB。
|
||||
|
||||
**所以我觉得你现在缺的不是“memory”,而是一个更深的概念:Learning → Compilation。**
|
||||
|
||||
---
|
||||
|
||||
# 1. 我会把你想做的东西定义成:Agent 的“认知编译”
|
||||
|
||||
你描述的人类学习过程非常准确:
|
||||
|
||||
```text
|
||||
第一次:
|
||||
仔细思考
|
||||
↓
|
||||
尝试
|
||||
↓
|
||||
犯错
|
||||
↓
|
||||
修正
|
||||
|
||||
第二次:
|
||||
仍然需要思考
|
||||
↓
|
||||
但已经有经验
|
||||
|
||||
第三次:
|
||||
开始形成套路
|
||||
|
||||
多次之后:
|
||||
“我知道怎么做了”
|
||||
↓
|
||||
不再重新思考
|
||||
↓
|
||||
直接执行
|
||||
```
|
||||
|
||||
传统 Agent:
|
||||
|
||||
```text
|
||||
User
|
||||
↓
|
||||
LLM
|
||||
↓
|
||||
Tool
|
||||
↓
|
||||
LLM
|
||||
↓
|
||||
Tool
|
||||
↓
|
||||
LLM
|
||||
```
|
||||
|
||||
每次任务都重新付出推理成本。
|
||||
|
||||
你想让 Marqdo 变成:
|
||||
|
||||
```text
|
||||
新任务
|
||||
│
|
||||
▼
|
||||
是否已经学会?
|
||||
/ \
|
||||
是 否
|
||||
│ │
|
||||
▼ ▼
|
||||
已编译 mq.md LLM 推理
|
||||
│ │
|
||||
▼ ▼
|
||||
低成本执行 执行 + 观察
|
||||
│
|
||||
▼
|
||||
沉淀 mq.md
|
||||
│
|
||||
▼
|
||||
验证 / 优化
|
||||
│
|
||||
▼
|
||||
编译成 Skill
|
||||
```
|
||||
|
||||
我认为这个想法**非常漂亮**。
|
||||
|
||||
---
|
||||
|
||||
# 2. 而且这和 Marqdo 的语言设计天然吻合
|
||||
|
||||
这可能是你整个项目最重要的一次“闭环”。
|
||||
|
||||
你前面定义:
|
||||
|
||||
> `.mq.md` = Markdown + 可执行程序 + 知识。
|
||||
|
||||
现在 Agent 又产生:
|
||||
|
||||
> `.mq.md` = Agent 学会的经验。
|
||||
|
||||
于是:
|
||||
|
||||
```text
|
||||
Agent
|
||||
│
|
||||
│ 学习
|
||||
▼
|
||||
.mq.md
|
||||
│
|
||||
┌───────┼────────┐
|
||||
↓ ↓ ↓
|
||||
知识 策略 程序
|
||||
│ │ │
|
||||
└───────┼────────┘
|
||||
▼
|
||||
Agent Skill
|
||||
│
|
||||
▼
|
||||
低成本执行
|
||||
```
|
||||
|
||||
这就非常有意思了。
|
||||
|
||||
**Agent 的 memory 不再是一段向量 embedding,也不只是聊天历史。**
|
||||
|
||||
它是:
|
||||
|
||||
> **可阅读、可修改、可验证、可执行的知识程序。**
|
||||
|
||||
这才是真正的 **Marqdo-native Agent**。
|
||||
|
||||
---
|
||||
|
||||
# 3. 你现在的 Agent 已经有这个雏形,但还没有真正“学习”
|
||||
|
||||
从你现在的代码看,已经存在:
|
||||
|
||||
```text
|
||||
reuse
|
||||
near_match
|
||||
soft_match
|
||||
promote
|
||||
improve_every = 3
|
||||
llm_free
|
||||
```
|
||||
|
||||
这些机制实际上已经在做:
|
||||
|
||||
> **经验复用。**
|
||||
|
||||
例如当前逻辑会查找已有 KB,如果命中 `llm_free` skill,就可以直接运行 resource,而不是再让父 Agent 做一轮 LLM 推理。
|
||||
|
||||
这是很好的基础。
|
||||
|
||||
但我认为:
|
||||
|
||||
> **Reuse ≠ Learning。**
|
||||
|
||||
现在更像:
|
||||
|
||||
```text
|
||||
成功任务
|
||||
↓
|
||||
保存
|
||||
↓
|
||||
以后查找
|
||||
↓
|
||||
复用
|
||||
```
|
||||
|
||||
而你现在构想的是:
|
||||
|
||||
```text
|
||||
成功任务
|
||||
↓
|
||||
观察多次执行
|
||||
↓
|
||||
抽象共同结构
|
||||
↓
|
||||
去掉偶然信息
|
||||
↓
|
||||
形成一般策略
|
||||
↓
|
||||
验证
|
||||
↓
|
||||
编译
|
||||
↓
|
||||
以后低成本执行
|
||||
```
|
||||
|
||||
这两者差距非常大。
|
||||
|
||||
---
|
||||
|
||||
# 4. 我甚至建议你不要叫它 Memory
|
||||
|
||||
我会给它一个更有 Marqdo 味道的名字:
|
||||
|
||||
## **Skill Compilation**
|
||||
|
||||
或者:
|
||||
|
||||
## **Experience Compilation**
|
||||
|
||||
甚至:
|
||||
|
||||
## **Cognitive Compilation**
|
||||
|
||||
整个过程:
|
||||
|
||||
```text
|
||||
Experience
|
||||
↓
|
||||
Episodic Trace
|
||||
↓
|
||||
Pattern Extraction
|
||||
↓
|
||||
Generalization
|
||||
↓
|
||||
Marqdo Skill
|
||||
↓
|
||||
Validation
|
||||
↓
|
||||
Compiled Skill
|
||||
```
|
||||
|
||||
然后 Agent 不再只是:
|
||||
|
||||
> “记住我以前做过什么。”
|
||||
|
||||
而是:
|
||||
|
||||
> **“把以前的思考编译成以后不需要思考的程序。”**
|
||||
|
||||
我觉得这是一个非常强的概念。
|
||||
|
||||
---
|
||||
|
||||
# 5. 例如真的可以这样工作
|
||||
|
||||
第一次:
|
||||
|
||||
用户:
|
||||
|
||||
> 把这个 CSV 中年龄大于 18 的用户筛出来,并按照年龄排序。
|
||||
|
||||
Agent:
|
||||
|
||||
```text
|
||||
LLM reasoning
|
||||
↓
|
||||
读取 CSV
|
||||
↓
|
||||
分析结构
|
||||
↓
|
||||
过滤
|
||||
↓
|
||||
排序
|
||||
↓
|
||||
输出
|
||||
```
|
||||
|
||||
产生:
|
||||
|
||||
```text
|
||||
.marqdo/agent-runs/xxx.mq.md
|
||||
```
|
||||
|
||||
第二次用户:
|
||||
|
||||
> 把另一个 CSV 中年龄大于 18 的用户筛出来,并按照年龄排序。
|
||||
|
||||
Agent 发现:
|
||||
|
||||
```text
|
||||
intent similarity = 0.94
|
||||
```
|
||||
|
||||
于是:
|
||||
|
||||
```text
|
||||
REUSE
|
||||
```
|
||||
|
||||
直接调用之前的程序。
|
||||
|
||||
---
|
||||
|
||||
第三、第四、第五次:
|
||||
|
||||
Agent 发现:
|
||||
|
||||
```text
|
||||
same structure
|
||||
different file
|
||||
different column names
|
||||
```
|
||||
|
||||
这时候不应该继续保存五个:
|
||||
|
||||
```text
|
||||
task1.mq.md
|
||||
task2.mq.md
|
||||
task3.mq.md
|
||||
task4.mq.md
|
||||
task5.mq.md
|
||||
```
|
||||
|
||||
而应该让 LLM 总结:
|
||||
|
||||
```markdown
|
||||
# Filter and Sort CSV Users
|
||||
|
||||
## Preconditions
|
||||
|
||||
- Input contains user records.
|
||||
- An age field exists.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Read the input table.
|
||||
2. Keep rows where `age > 18`.
|
||||
3. Sort by `age` ascending.
|
||||
|
||||
## Variables
|
||||
|
||||
- `input`
|
||||
- `age_field`
|
||||
- `output`
|
||||
|
||||
## Exceptions
|
||||
|
||||
- Missing age field
|
||||
- Invalid age
|
||||
|
||||
## Examples
|
||||
|
||||
| Input | Output |
|
||||
|---|---|
|
||||
| ... | ... |
|
||||
```
|
||||
|
||||
然后:
|
||||
|
||||
```text
|
||||
skill_status = compiled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 6. 更关键的是:这个 mq.md 可以逐渐“去 LLM 化”
|
||||
|
||||
这是你刚才说的:
|
||||
|
||||
> “其中可以使用非常少的大模型思考,或者使用类似 Jev 的决策模型,或者干脆只使用分支控制。”
|
||||
|
||||
**我非常赞同。**
|
||||
|
||||
我甚至认为这应该成为 Marqdo Agent 的核心架构。
|
||||
|
||||
可以设计成一个:
|
||||
|
||||
# Cognitive Cost Ladder
|
||||
|
||||
```text
|
||||
Level 0
|
||||
Deterministic Marqdo
|
||||
│
|
||||
▼
|
||||
Level 1
|
||||
Rule / Branch
|
||||
│
|
||||
▼
|
||||
Level 2
|
||||
Small decision model
|
||||
│
|
||||
▼
|
||||
Level 3
|
||||
Small LLM
|
||||
│
|
||||
▼
|
||||
Level 4
|
||||
Full LLM reasoning
|
||||
│
|
||||
▼
|
||||
Level 5
|
||||
Multi-agent exploration
|
||||
```
|
||||
|
||||
新问题:
|
||||
|
||||
```text
|
||||
Full LLM
|
||||
↓
|
||||
learn
|
||||
↓
|
||||
Marqdo Skill
|
||||
↓
|
||||
validation
|
||||
↓
|
||||
Level 2/1
|
||||
```
|
||||
|
||||
于是 Agent 会越来越“便宜”。
|
||||
|
||||
---
|
||||
|
||||
# 7. 这甚至给你提供了一个极漂亮的学习曲线
|
||||
|
||||
假设一个任务第一次需要:
|
||||
|
||||
```text
|
||||
8 次 LLM calls
|
||||
```
|
||||
|
||||
第二次:
|
||||
|
||||
```text
|
||||
5 次
|
||||
```
|
||||
|
||||
第三次:
|
||||
|
||||
```text
|
||||
3 次
|
||||
```
|
||||
|
||||
学习完成:
|
||||
|
||||
```text
|
||||
0 次
|
||||
```
|
||||
|
||||
或者:
|
||||
|
||||
```text
|
||||
1 次 small model
|
||||
```
|
||||
|
||||
这时候你就有一个非常漂亮的指标:
|
||||
|
||||
## Reasoning Amortization
|
||||
|
||||
定义:
|
||||
|
||||
$$
|
||||
C_n =
|
||||
\frac{
|
||||
\text{LLM inference cost over first } n \text{ executions}
|
||||
}{n}
|
||||
$$
|
||||
|
||||
随着执行次数增加:
|
||||
|
||||
```text
|
||||
Cost
|
||||
│\
|
||||
│ \
|
||||
│ \
|
||||
│ \
|
||||
│ \____
|
||||
│ ─────────
|
||||
└───────────────────
|
||||
executions
|
||||
```
|
||||
|
||||
**这甚至解决了你之前担心的 Marqdo 性能难以证明的问题。**
|
||||
|
||||
你之前不知道怎么证明:
|
||||
|
||||
> Marqdo 比 Python 更适合 AI。
|
||||
|
||||
但现在你可以研究:
|
||||
|
||||
> **Marqdo Agent 能否把高成本 LLM reasoning 逐渐编译成低成本 executable knowledge?**
|
||||
|
||||
这个是一个非常明确、可测量、而且很有研究价值的问题。
|
||||
|
||||
---
|
||||
|
||||
# 8. 但是这里有一个非常重要的危险
|
||||
|
||||
你说:
|
||||
|
||||
> “超过三次调用就自动总结。”
|
||||
|
||||
我建议:
|
||||
|
||||
**不要真的这么简单。**
|
||||
|
||||
三次可以作为:
|
||||
|
||||
> **触发学习候选**
|
||||
|
||||
但不能作为:
|
||||
|
||||
> **自动认为已经学会。**
|
||||
|
||||
否则会发生:
|
||||
|
||||
```text
|
||||
第一次:特殊情况
|
||||
第二次:特殊情况
|
||||
第三次:特殊情况
|
||||
```
|
||||
|
||||
LLM 总结:
|
||||
|
||||
```text
|
||||
General rule:
|
||||
...
|
||||
```
|
||||
|
||||
然后把偶然性错误“编译”进 Skill。
|
||||
|
||||
这会非常危险。
|
||||
|
||||
---
|
||||
|
||||
# 9. 我建议建立“经验 → 技能”的四阶段
|
||||
|
||||
## Stage 1 — Episode
|
||||
|
||||
每次任务产生:
|
||||
|
||||
```text
|
||||
task
|
||||
context
|
||||
actions
|
||||
tool calls
|
||||
observations
|
||||
errors
|
||||
result
|
||||
cost
|
||||
```
|
||||
|
||||
例如:
|
||||
|
||||
```text
|
||||
episode-001.mq.md
|
||||
episode-002.mq.md
|
||||
episode-003.mq.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage 2 — Candidate Skill
|
||||
|
||||
达到阈值之后:
|
||||
|
||||
```text
|
||||
3+ similar episodes
|
||||
```
|
||||
|
||||
让 LLM 总结:
|
||||
|
||||
```text
|
||||
candidate.mq.md
|
||||
```
|
||||
|
||||
但它还是:
|
||||
|
||||
> **candidate**
|
||||
|
||||
而不是正式 skill。
|
||||
|
||||
---
|
||||
|
||||
## Stage 3 — Verification
|
||||
|
||||
用历史任务重新运行:
|
||||
|
||||
```text
|
||||
episode 1
|
||||
episode 2
|
||||
episode 3
|
||||
```
|
||||
|
||||
测试:
|
||||
|
||||
```text
|
||||
candidate skill
|
||||
```
|
||||
|
||||
如果:
|
||||
|
||||
```text
|
||||
3 / 3 success
|
||||
```
|
||||
|
||||
再加新的 held-out task:
|
||||
|
||||
```text
|
||||
episode 4
|
||||
```
|
||||
|
||||
如果:
|
||||
|
||||
```text
|
||||
4 / 4
|
||||
```
|
||||
|
||||
才提高 confidence。
|
||||
|
||||
---
|
||||
|
||||
## Stage 4 — Compilation
|
||||
|
||||
最后:
|
||||
|
||||
```text
|
||||
candidate
|
||||
↓
|
||||
verified
|
||||
↓
|
||||
compiled
|
||||
```
|
||||
|
||||
此时才允许:
|
||||
|
||||
```text
|
||||
llm_free = true
|
||||
```
|
||||
|
||||
你目前的系统已经有 `llm_free` 命中后直接运行 resource 的机制。
|
||||
|
||||
我认为未来这个 flag **不应该是人工/静态指定的属性,而应该成为学习系统的产物。**
|
||||
|
||||
---
|
||||
|
||||
# 10. 甚至可以让 mq.md 自己记录“学习程度”
|
||||
|
||||
比如:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: skill
|
||||
status: compiled
|
||||
confidence: 0.97
|
||||
evidence: 17
|
||||
success_rate: 0.941
|
||||
llm_free: true
|
||||
created_from: 6c8...
|
||||
last_validated: 2026-09-23
|
||||
avg_reasoning_cost: 0.2
|
||||
---
|
||||
```
|
||||
|
||||
然后正文:
|
||||
|
||||
```markdown
|
||||
# CSV 成人用户筛选
|
||||
|
||||
## Intent
|
||||
|
||||
筛选年龄大于 18 岁的用户。
|
||||
|
||||
## Procedure
|
||||
|
||||
- 读取 CSV
|
||||
- 判断 age
|
||||
- 过滤
|
||||
- 排序
|
||||
|
||||
## Fallback
|
||||
|
||||
如果无法确定 age 字段:
|
||||
|
||||
> ask_llm
|
||||
|
||||
## Verification
|
||||
|
||||
| Case | Result |
|
||||
|---|---|
|
||||
| case-001 | ✓ |
|
||||
| case-002 | ✓ |
|
||||
| case-003 | ✓ |
|
||||
| case-004 | ✓ |
|
||||
```
|
||||
|
||||
注意这个设计里非常重要的一点:
|
||||
|
||||
> **Skill 本身可以包含一个 fallback 到 LLM 的路径。**
|
||||
|
||||
所以不是:
|
||||
|
||||
```text
|
||||
学会 / 不会
|
||||
```
|
||||
|
||||
而是:
|
||||
|
||||
```text
|
||||
确定部分 → deterministic
|
||||
不确定部分 → small model
|
||||
真正未知 → full LLM
|
||||
```
|
||||
|
||||
这就非常接近人类的实际认知过程。
|
||||
|
||||
---
|
||||
|
||||
# 11. 我甚至会把 Agent 的运行模型改成这样
|
||||
|
||||
```text
|
||||
User Task
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Skill Resolver │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────────┼────────────┐
|
||||
▼ ▼ ▼
|
||||
Exact Near Unknown
|
||||
Hit Hit
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
mq.md execute small model Full LLM
|
||||
│ │ │
|
||||
└────────────┼────────────┘
|
||||
▼
|
||||
Result
|
||||
│
|
||||
▼
|
||||
Episode
|
||||
│
|
||||
▼
|
||||
Experience Store
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ │
|
||||
repeated? novel?
|
||||
│
|
||||
▼
|
||||
Skill synthesis
|
||||
│
|
||||
▼
|
||||
Verification
|
||||
│
|
||||
▼
|
||||
Compilation
|
||||
│
|
||||
▼
|
||||
mq.md Skill
|
||||
```
|
||||
|
||||
**这就已经不是普通 Agent framework 了。**
|
||||
|
||||
它是一个:
|
||||
|
||||
> **Self-compiling Agent**
|
||||
|
||||
---
|
||||
|
||||
# 12. 而 Marqdo 在这里有一个其他 Agent framework 很难天然拥有的优势
|
||||
|
||||
因为“学习结果”不是:
|
||||
|
||||
```json
|
||||
{
|
||||
"memory": "..."
|
||||
}
|
||||
```
|
||||
|
||||
也不是:
|
||||
|
||||
```text
|
||||
embedding vector
|
||||
```
|
||||
|
||||
而是:
|
||||
|
||||
```text
|
||||
learned_skill.mq.md
|
||||
```
|
||||
|
||||
这意味着用户可以:
|
||||
|
||||
```text
|
||||
打开
|
||||
阅读
|
||||
修改
|
||||
运行
|
||||
测试
|
||||
分享
|
||||
Git commit
|
||||
diff
|
||||
fork
|
||||
```
|
||||
|
||||
甚至:
|
||||
|
||||
```text
|
||||
Agent A
|
||||
↓
|
||||
learned_skill.mq.md
|
||||
↓
|
||||
Agent B
|
||||
```
|
||||
|
||||
**Agent 的经验第一次成为一种真正可移植的软件 artifact。**
|
||||
|
||||
我认为这是你整个 Marqdo 项目里非常值得深入挖掘的东西。
|
||||
|
||||
---
|
||||
|
||||
# 13. 而且它和你前面说的“Executable Knowledge”完全闭环
|
||||
|
||||
你之前提出:
|
||||
|
||||
```text
|
||||
Executable Document
|
||||
↓
|
||||
Executable Knowledge Base
|
||||
```
|
||||
|
||||
现在再往前一步:
|
||||
|
||||
```text
|
||||
Executable Knowledge
|
||||
↓
|
||||
Agent Experience
|
||||
↓
|
||||
Agent Learning
|
||||
↓
|
||||
Compiled Knowledge
|
||||
↓
|
||||
Executable Skill
|
||||
```
|
||||
|
||||
于是整个 Marqdo 可以形成:
|
||||
|
||||
```text
|
||||
┌───────────────┐
|
||||
│ Human │
|
||||
└───────┬───────┘
|
||||
│
|
||||
▼
|
||||
Natural Task
|
||||
│
|
||||
▼
|
||||
AI Reasoning
|
||||
│
|
||||
▼
|
||||
Executable Work
|
||||
│
|
||||
▼
|
||||
.mq.md
|
||||
│
|
||||
┌───────┴───────┐
|
||||
▼ ▼
|
||||
Knowledge Skill
|
||||
│ │
|
||||
└───────┬───────┘
|
||||
▼
|
||||
Future Agent
|
||||
│
|
||||
▼
|
||||
Less Reasoning
|
||||
│
|
||||
▼
|
||||
More Execution
|
||||
```
|
||||
|
||||
这就是我现在最喜欢 Marqdo 的地方:
|
||||
|
||||
> **Agent 不只是使用知识库;Agent 会把自己的经验沉淀成知识库,然后知识库反过来改变 Agent 的计算方式。**
|
||||
|
||||
这是一个真正的闭环。
|
||||
|
||||
---
|
||||
|
||||
## 最后,我会建议你对现有 Agent 做一个非常明确的架构升级
|
||||
|
||||
你现在已经有:
|
||||
|
||||
```text
|
||||
reuse
|
||||
near_match
|
||||
soft_match
|
||||
promote
|
||||
improve_every=3
|
||||
llm_free
|
||||
```
|
||||
|
||||
所以**完全没必要推倒重来**。
|
||||
|
||||
我会把它演化成:
|
||||
|
||||
```text
|
||||
Current Agent
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ │
|
||||
Execution Experience
|
||||
│ │
|
||||
│ ▼
|
||||
│ Episode Store
|
||||
│ │
|
||||
│ ≥ N similar
|
||||
│ │
|
||||
│ ▼
|
||||
│ Skill Synthesis
|
||||
│ │
|
||||
│ ▼
|
||||
│ Skill Validation
|
||||
│ │
|
||||
│ ▼
|
||||
│ Skill Compilation
|
||||
│ │
|
||||
└─────────────┬───┘
|
||||
▼
|
||||
.mq.md Skill
|
||||
│
|
||||
┌────────┼────────┐
|
||||
▼ ▼ ▼
|
||||
Branch Small LLM Full LLM
|
||||
```
|
||||
|
||||
而且你当前已经有一个非常好的“终点”:**当 child 返回 value 时,可以 deterministic 地 solidify,而不是再次让父 LLM 发明 patch。** 当前代码已经明确这么处理。
|
||||
|
||||
所以我会把你的下一版 Agent 的核心 slogan 直接定成:
|
||||
|
||||
> **Think → Execute → Learn → Compile → Reuse**
|
||||
|
||||
或者更 Marqdo 一点:
|
||||
|
||||
> **Every successful thought can become executable knowledge.**
|
||||
|
||||
这比“Marqdo 有一个 Agent framework”强得多。
|
||||
|
||||
而且这件事**非常适合做你前面说的论文实验**:你甚至可以测一个 Agent 在重复任务上的 **LLM calls / tokens / latency / success rate 随经验次数变化的曲线**,直接验证“推理成本被 mq.md 技能逐渐摊销”的假设。这样 Marqdo 的 Agent、Executable Knowledge 和你之前苦恼的“性能怎么证明”三个问题,反而被同一个实验串起来了。
|
||||
+2626
File diff suppressed because it is too large.
Load diff
+541
@@ -0,0 +1,541 @@
|
||||
有时候可能用户不太好接入Jev,所以阶段4应该要允许用户使用小参数的模型代替,你认为呢?
|
||||
|
||||
我非常赞同,而且我甚至建议**不要把 Jev 作为阶段 4 的必选组件**。
|
||||
|
||||
更准确的设计应该是:
|
||||
|
||||
> **Jev 是一种可选的决策器(Decision Engine),小参数模型是另一种可选实现;Marqdo Agent 本身只规定“需要一个 Router/Policy”,而不规定 Router 必须由什么实现。**
|
||||
|
||||
这样会让整个框架开放很多。
|
||||
|
||||
### 1. 阶段 4 应该改成“Adaptive Routing”
|
||||
|
||||
原来的:
|
||||
|
||||
```text
|
||||
Phase 4
|
||||
↓
|
||||
Jev Router
|
||||
```
|
||||
|
||||
我建议改成:
|
||||
|
||||
```text
|
||||
Phase 4: Adaptive Routing
|
||||
│
|
||||
┌─────────┼─────────┐
|
||||
↓ ↓ ↓
|
||||
Marqdo Rule Jev Small LLM
|
||||
│ │ │
|
||||
└─────────┼─────────┘
|
||||
↓
|
||||
Route Policy
|
||||
```
|
||||
|
||||
甚至还可以允许:
|
||||
|
||||
```text
|
||||
Rule
|
||||
Small Model
|
||||
Jev
|
||||
Full LLM
|
||||
```
|
||||
|
||||
混合使用。
|
||||
|
||||
---
|
||||
|
||||
# 2. 为什么这个设计更合理
|
||||
|
||||
因为用户真正需要的不是:
|
||||
|
||||
> “我要接入 Jev。”
|
||||
|
||||
而是:
|
||||
|
||||
> “我希望 Agent 学会以后,不要每次都调用大模型。”
|
||||
|
||||
这两个概念应该分开。
|
||||
|
||||
所以 Marqdo 只定义接口:
|
||||
|
||||
```text
|
||||
agent.route(task, candidates)
|
||||
```
|
||||
|
||||
至于内部怎么实现,可以是:
|
||||
|
||||
### A. 纯 Marqdo
|
||||
|
||||
```text
|
||||
if task.type == "json":
|
||||
return json-repair
|
||||
|
||||
if task.type == "search":
|
||||
return corpus-search
|
||||
```
|
||||
|
||||
完全不需要模型。
|
||||
|
||||
---
|
||||
|
||||
### B. 小参数模型
|
||||
|
||||
比如用户已经有:
|
||||
|
||||
```text
|
||||
Qwen 0.5B
|
||||
Qwen 1.5B
|
||||
Llama 1B
|
||||
某个本地模型
|
||||
```
|
||||
|
||||
就可以:
|
||||
|
||||
```text
|
||||
task
|
||||
↓
|
||||
small model
|
||||
↓
|
||||
"json-repair"
|
||||
```
|
||||
|
||||
甚至可以让用户直接配置:
|
||||
|
||||
```yaml
|
||||
router:
|
||||
type: llm
|
||||
|
||||
provider: openai-compatible
|
||||
base_url: ...
|
||||
api_key: ...
|
||||
model: ...
|
||||
```
|
||||
|
||||
这和你之前设计 AI 斗蛐蛐时提出的 **OpenAI-compatible URL + Key** 思路其实也很契合。
|
||||
|
||||
---
|
||||
|
||||
### C. Jev
|
||||
|
||||
如果用户安装了 Jev:
|
||||
|
||||
```text
|
||||
task
|
||||
↓
|
||||
Jev
|
||||
↓
|
||||
policy
|
||||
```
|
||||
|
||||
那么就用 Jev。
|
||||
|
||||
---
|
||||
|
||||
### D. 大模型
|
||||
|
||||
甚至最开始没有任何 Router:
|
||||
|
||||
```text
|
||||
task
|
||||
↓
|
||||
large LLM
|
||||
↓
|
||||
decide
|
||||
```
|
||||
|
||||
也是合法的。
|
||||
|
||||
所以:
|
||||
|
||||
> **Router 是抽象能力,不是具体模型。**
|
||||
|
||||
---
|
||||
|
||||
# 3. 更重要的是:Router 本身也可以被学习
|
||||
|
||||
这里我觉得还能进一步提升你的设计。
|
||||
|
||||
一开始:
|
||||
|
||||
```text
|
||||
Task
|
||||
↓
|
||||
Large LLM
|
||||
↓
|
||||
选择 skill
|
||||
```
|
||||
|
||||
系统观察:
|
||||
|
||||
```text
|
||||
task A → json-repair
|
||||
task B → json-repair
|
||||
task C → json-repair
|
||||
task D → corpus-search
|
||||
```
|
||||
|
||||
之后可以自动生成:
|
||||
|
||||
```text
|
||||
router.mq.md
|
||||
```
|
||||
|
||||
例如:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: policy
|
||||
status: compiled
|
||||
---
|
||||
|
||||
## route
|
||||
|
||||
1. `task.type` == "json"
|
||||
*"json-repair"*
|
||||
|
||||
2. `task.type` == "search"
|
||||
*"corpus-search"*
|
||||
|
||||
3. *
|
||||
*"llm"*
|
||||
```
|
||||
|
||||
那么你甚至不需要 Jev。
|
||||
|
||||
**Marqdo 自己的控制流就是 Router。**
|
||||
|
||||
---
|
||||
|
||||
# 4. 所以我会重新设计 Cost Ladder
|
||||
|
||||
之前的:
|
||||
|
||||
```text
|
||||
L0 deterministic
|
||||
L1 rule
|
||||
L2 small model
|
||||
L3 small LLM
|
||||
L4 large LLM
|
||||
L5 exploration
|
||||
```
|
||||
|
||||
我建议改成:
|
||||
|
||||
```text
|
||||
┌────────────────────────┐
|
||||
│ Adaptive Router │
|
||||
└───────────┬────────────┘
|
||||
│
|
||||
┌─────────────────┼─────────────────┐
|
||||
↓ ↓ ↓
|
||||
Deterministic Small Model Large LLM
|
||||
│ │ │
|
||||
↓ ↓ ↓
|
||||
L0/L1 L2/L3 L4
|
||||
│
|
||||
↓
|
||||
Exploration L5
|
||||
```
|
||||
|
||||
这里最关键的是:
|
||||
|
||||
> **L2/L3 不应该规定具体模型。**
|
||||
|
||||
可以是:
|
||||
|
||||
```text
|
||||
Marqdo rules
|
||||
OR
|
||||
Jev
|
||||
OR
|
||||
0.5B model
|
||||
OR
|
||||
1B model
|
||||
OR
|
||||
3B model
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 5. 我甚至建议用户可以配置多个 Router
|
||||
|
||||
例如:
|
||||
|
||||
```yaml
|
||||
router:
|
||||
candidates:
|
||||
|
||||
- name: rules
|
||||
type: marqdo
|
||||
|
||||
- name: local
|
||||
type: llm
|
||||
model: qwen-0.5b
|
||||
|
||||
- name: jev
|
||||
type: jev
|
||||
|
||||
- name: cloud
|
||||
type: llm
|
||||
model: ...
|
||||
```
|
||||
|
||||
然后 Agent 自己选择:
|
||||
|
||||
```text
|
||||
Task
|
||||
↓
|
||||
Router Resolver
|
||||
↓
|
||||
rules?
|
||||
↓
|
||||
confidence insufficient
|
||||
↓
|
||||
small model?
|
||||
↓
|
||||
confidence insufficient
|
||||
↓
|
||||
Jev?
|
||||
↓
|
||||
confidence insufficient
|
||||
↓
|
||||
large LLM
|
||||
```
|
||||
|
||||
这就形成一个**分级决策系统**。
|
||||
|
||||
---
|
||||
|
||||
# 6. 最漂亮的地方:Router 也可以被编译
|
||||
|
||||
最终甚至可以:
|
||||
|
||||
```text
|
||||
第一次:
|
||||
|
||||
LLM
|
||||
↓
|
||||
决定调用 Skill A
|
||||
|
||||
第二次:
|
||||
|
||||
LLM
|
||||
↓
|
||||
决定调用 Skill A
|
||||
|
||||
第三次:
|
||||
|
||||
LLM
|
||||
↓
|
||||
决定调用 Skill A
|
||||
|
||||
Learning
|
||||
↓
|
||||
发现稳定模式
|
||||
|
||||
Compile
|
||||
↓
|
||||
router.mq.md
|
||||
```
|
||||
|
||||
以后:
|
||||
|
||||
```text
|
||||
Task
|
||||
↓
|
||||
router.mq.md
|
||||
↓
|
||||
skill A
|
||||
↓
|
||||
execute
|
||||
```
|
||||
|
||||
**0 LLM。**
|
||||
|
||||
于是整个 Agent 的学习就不只是:
|
||||
|
||||
```text
|
||||
学习如何解决任务
|
||||
```
|
||||
|
||||
而是同时学习:
|
||||
|
||||
```text
|
||||
1. 学习如何解决任务
|
||||
2. 学习什么时候使用什么技能
|
||||
3. 学习什么时候需要大模型
|
||||
```
|
||||
|
||||
这三个层次组合起来,我认为比单纯引入 Jev 更有意思。
|
||||
|
||||
---
|
||||
|
||||
# 7. 最终可以形成三级编译
|
||||
|
||||
我现在反而觉得你的 Agent Framework 可以把整个“学习”定义成三个阶段:
|
||||
|
||||
```text
|
||||
Experience
|
||||
↓
|
||||
Skill Compilation
|
||||
↓
|
||||
Policy Compilation
|
||||
↓
|
||||
Execution Compilation
|
||||
```
|
||||
|
||||
### 第一层:Skill Compilation
|
||||
|
||||
```text
|
||||
LLM experience
|
||||
↓
|
||||
skill.mq.md
|
||||
```
|
||||
|
||||
解决:
|
||||
|
||||
> **怎么做?**
|
||||
|
||||
### 第二层:Policy Compilation
|
||||
|
||||
```text
|
||||
many task → skill mappings
|
||||
↓
|
||||
policy.mq.md
|
||||
```
|
||||
|
||||
解决:
|
||||
|
||||
> **什么时候做什么?**
|
||||
|
||||
### 第三层:Execution Compilation
|
||||
|
||||
```text
|
||||
skill + policy
|
||||
↓
|
||||
pure Marqdo execution
|
||||
```
|
||||
|
||||
解决:
|
||||
|
||||
> **能不能完全不思考直接执行?**
|
||||
|
||||
这时候整个 Agent 就变成:
|
||||
|
||||
```text
|
||||
Large LLM
|
||||
│
|
||||
Exploration
|
||||
↓
|
||||
Experience
|
||||
↓
|
||||
┌───────────────┐
|
||||
│ Skill Compile │
|
||||
└───────┬───────┘
|
||||
↓
|
||||
Skill MQ
|
||||
│
|
||||
┌───────┴───────┐
|
||||
↓ ↓
|
||||
Policy Compile Direct Execute
|
||||
↓
|
||||
Router MQ
|
||||
│
|
||||
↓
|
||||
Skill Selection
|
||||
│
|
||||
↓
|
||||
Execute
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 8. 因此 Phase 4 我建议正式改名
|
||||
|
||||
不要叫:
|
||||
|
||||
> Jev Router
|
||||
|
||||
而叫:
|
||||
|
||||
> **Adaptive Policy / Routing Layer**
|
||||
|
||||
然后提供四种 backend:
|
||||
|
||||
```text
|
||||
router.backend = marqdo
|
||||
router.backend = small-llm
|
||||
router.backend = jev
|
||||
router.backend = llm
|
||||
```
|
||||
|
||||
甚至:
|
||||
|
||||
```text
|
||||
router.backend = auto
|
||||
```
|
||||
|
||||
让 Agent 根据可用环境自动选择。
|
||||
|
||||
---
|
||||
|
||||
## 9. 用户体验也会好很多
|
||||
|
||||
用户第一次安装 Marqdo:
|
||||
|
||||
```text
|
||||
marqdo agent run ...
|
||||
```
|
||||
|
||||
没有 Jev,也没有小模型。
|
||||
|
||||
完全没问题:
|
||||
|
||||
```text
|
||||
→ 使用配置的大模型
|
||||
```
|
||||
|
||||
用户后来配置:
|
||||
|
||||
```yaml
|
||||
router:
|
||||
backend: small-llm
|
||||
provider: openai-compatible
|
||||
model: qwen-0.5b
|
||||
```
|
||||
|
||||
Agent 就自动变成:
|
||||
|
||||
```text
|
||||
大模型:负责复杂推理 / 学习
|
||||
小模型:负责日常路由
|
||||
Marqdo:负责确定性执行
|
||||
```
|
||||
|
||||
如果用户安装 Jev:
|
||||
|
||||
```yaml
|
||||
router:
|
||||
backend: jev
|
||||
```
|
||||
|
||||
则:
|
||||
|
||||
```text
|
||||
Jev:负责路由
|
||||
大模型:负责复杂任务
|
||||
Marqdo:负责执行
|
||||
```
|
||||
|
||||
**用户完全不需要改变 Agent 的上层 API。**
|
||||
|
||||
---
|
||||
|
||||
我认为这个调整非常重要,因为它让 **Marqdo Agent 的核心创新从“依赖某个新模型”变成“模型无关的认知编译架构”**。
|
||||
|
||||
最终可以浓缩成一句话:
|
||||
|
||||
> **大模型负责探索,小模型/Jev 负责决策,Marqdo 负责执行;随着经验积累,探索和决策逐渐被编译成可执行的 `.mq.md`。**
|
||||
|
||||
这其实比“接入 Jev”本身更符合你最开始提出的 **Think → Execute → Learn → Compile → Reuse** 路线。
|
||||
+1173
File diff suppressed because it is too large.
Load diff
+1335
File diff suppressed because it is too large.
Load diff
+2182
File diff suppressed because it is too large.
Load diff
+2818
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,58 @@
|
||||
# 缺陷记录:LLM 传输失败硬中断 Agent Runtime
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-llm-transport-soft.mq.md` |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 发现方 | qdagent(接通 `agent.run` live 路径时) |
|
||||
| 影响面 | `host/net` · `plugins/llm` · `ext/ai/llm` · `ext/ai/llm/openai` · `ext/ai/agent` |
|
||||
| 相关 | [agent-run-efi-resolve-bugs-2026-10.md](agent-run-efi-resolve-bugs-2026-10.md) · [ext-agent.md](../design/ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
上游 LLM **连接拒绝 / 超时 / 非 200** 时,Runtime 曾以 **硬错误** 终止整个 `marqdo run`;产品(qdagent ASK/BUILD)无法落到结构化 `status=error`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 复现
|
||||
|
||||
```bash
|
||||
OPENAI_API_KEY=offline OPENAI_BASE_URL=http://127.0.0.1:9 \
|
||||
marqdo run tests/ext/agent-llm-transport-soft.mq.md
|
||||
# 修复前:exit≠0,error: http POST …
|
||||
# 修复后:exit 0,ask/step/run 均带 finish|status=error + error 文本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因
|
||||
|
||||
| 层 | 行为 |
|
||||
|----|------|
|
||||
| `host_http_post` / SSE | 传输失败 `Err(...)` → VM abort |
|
||||
| `plugins/llm` `llm_chat_completions` | 同上 `Err` |
|
||||
| `ext/ai/llm/openai` | HTTP≠200 → `sys.exit 1` |
|
||||
| `agent.model_turn` / `step` / `plan` | 无软失败臂 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 修复清单
|
||||
|
||||
| # | 改动 | 文件 |
|
||||
|---|------|------|
|
||||
| 1 | 传输失败 → `{status:0, body}` / SSE error event | `src/host/net.rs` |
|
||||
| 2 | 插件返回 `{finish:error, error, …}` 而非 `Err` | `plugins/llm/src/lib.rs` |
|
||||
| 3 | openai 非 200 → 结构化 pack,禁止 `sys.exit` | `ext/ai/llm/openai.mq.md` |
|
||||
| 4 | `llm.ask` 透传 `error` / `finish` | `ext/ai/llm.mq.md` |
|
||||
| 5 | `model_turn` / `step` / `plan` 收成 `status=error` | `ext/ai/agent.mq.md` |
|
||||
| 6 | 金样 | `tests/ext/agent-llm-transport-soft.mq.md` |
|
||||
|
||||
**契约**:Agent Runtime 对 LLM 传输失败必须可捕获;`status=error` + `error` 字符串;进程退出码 0(程序正常返回错误图)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 对 qdagent
|
||||
|
||||
`ensure_llm` 有 key 但上游不可达时,`ask`/`build` 可走既有 `mode=error` 臂写 workbook,不再整 CLI 崩。
|
||||
@@ -0,0 +1,117 @@
|
||||
# 缺陷记录:`agent.run` EFI / resolve 在消费方崩溃(qdagent 复现)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-run-cold-efi.mq.md` |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 发现方 | qdagent(`~/work/qdagent`)接通 Marqdo ≥1.4.2 Agent EFI 全路径时 |
|
||||
| 影响面 | `ext/ai/agent` · `## run` · `plugins/agent` `agent_resolve` |
|
||||
| 相关 | [ext-agent.md](../design/ext-agent.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
`agent.run` 在 **空 OKF / 无 skill 命中** 或 **`efi=True`** 时,会以硬错误退出,而不是降级到 `plan` 探索。
|
||||
这是 **Agent Runtime 契约不完整**,不是 qdagent 业务写错。
|
||||
|
||||
---
|
||||
|
||||
## 1. 复现(qdagent)
|
||||
|
||||
环境:工作区 Marqdo `1.4.2` + `MARQDO_EXT=~/work/marqdo/ext`;qdagent 调用:
|
||||
|
||||
```text
|
||||
助手 = > agent.agent …
|
||||
`助手`.run task=… efi=True # 或 efi=False 后仍进 resolve
|
||||
```
|
||||
|
||||
本仓几乎没有 `.marqdo/agent-kb` 编译 skill。
|
||||
|
||||
### Bug A — `efi=True` → `unknown function preflight`
|
||||
|
||||
**位置**:[`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md) `## run`
|
||||
|
||||
```markdown
|
||||
1. `efi`
|
||||
**efi_pf = preflight task=`task`**
|
||||
```
|
||||
|
||||
同文件其它同对象方法一律写 `` `self`.route `` / `` `self`.resolve ``。
|
||||
裸标识 `preflight` 在导入消费方(如 `cli/求道-构建.mq.md`)里被解析成**全局函数**,找不到 → 硬错。
|
||||
|
||||
**期望**:`` **efi_pf = > `self`.preflight task=`task`** ``(或等价 method call)。
|
||||
|
||||
### Bug B — miss resolve → `missing map key llm_free`
|
||||
|
||||
**位置**:
|
||||
|
||||
1. Plugin:[`plugins/agent/src/memory.rs`](../../plugins/agent/src/memory.rs) `resolve_task`
|
||||
当 `kb_lookup` 返回 null:
|
||||
|
||||
```rust
|
||||
Ok(json!({
|
||||
"mode": "unknown",
|
||||
"skill": null,
|
||||
"resource": null,
|
||||
"confidence": 0.0,
|
||||
// 缺 llm_free
|
||||
}))
|
||||
```
|
||||
|
||||
2. Facade:`## run` 在 resolve 之后:
|
||||
|
||||
```markdown
|
||||
**llm_free = [llm_free](resolved)**
|
||||
```
|
||||
|
||||
脚注式取键在缺键时 **硬失败**,无法落到后面的 `plan` 探索臂。
|
||||
|
||||
**期望**:
|
||||
|
||||
- miss 结果始终带 `"llm_free": false`(与命中路径字段集对齐)
|
||||
- facade 侧对可选键用 `json.get`(缺省 `False`),防御其它调用方
|
||||
|
||||
---
|
||||
|
||||
## 2. 为何金样没拦住
|
||||
|
||||
| 金样 | 为何漏网 |
|
||||
|------|----------|
|
||||
| `tests/ext/agent-zero-llm.mq.md` | 先编译 skill / policy,再 `run`;resolve **命中** |
|
||||
| `tests/ext/eng-preflight.mq.md` | 只测 `agent_eng_preflight`,**不**走 `agent.run efi=` |
|
||||
| 多数 `agent-*-live` | 自带 kb 或 `efi=False` / 不经过 cold miss |
|
||||
|
||||
qdagent 是第一个「冷库 + 产品 EFI + `run`」消费方,因此打穿。
|
||||
|
||||
---
|
||||
|
||||
## 3. 修复清单(本轮)
|
||||
|
||||
| # | 改动 | 文件 |
|
||||
|---|------|------|
|
||||
| 1 | miss resolve 补 `llm_free: false` | `plugins/agent/src/memory.rs` |
|
||||
| 2 | `` `self`.preflight ``;`llm_free`/`mode` 用 `json.get` | `ext/ai/agent.mq.md` |
|
||||
| 3 | 回归金样:冷 kb + `run efi=True` 不崩溃,落到 explore/plan | `tests/ext/agent-run-cold-efi.mq.md` |
|
||||
| 4 | 重建 `marqdo_plugin_agent` 并跑金样 | `cargo build -p marqdo_plugin_agent --release` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 对 qdagent 的含义
|
||||
|
||||
修复后 qdagent 可恢复:
|
||||
|
||||
```text
|
||||
product preflight → latch → agent.run (efi=True|False) / plan
|
||||
```
|
||||
|
||||
而不必长期绕开 `agent.run`。
|
||||
在插件未装入新 so 前,qdagent 侧 EFI latch + `step`/`plan` 仍是合法降级。
|
||||
|
||||
---
|
||||
|
||||
## 5. 非目标
|
||||
|
||||
- 不改 EKC / `agent_eng_preflight` 语义
|
||||
- 不引入第二套 Agent loop
|
||||
- 不把向量检索升为权威真相
|
||||
@@ -0,0 +1,136 @@
|
||||
# 调研:代码即文档 × OKF × 沙盒 下的智能体 / 大模型优化(2026-10)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研 + 问题分析 · 供方案 [ext-ai-optimize.md](../design/ext-ai-optimize.md) 参考** |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [agent-framework-2026-09.md](agent-framework-2026-09.md) · [ai-agent-sandbox.md](ai-agent-sandbox.md) · [okf-and-marqdo.md](okf-and-marqdo.md) |
|
||||
| 本仓能力 | [ext-agent.md](../design/ext-agent.md) · [okf.md](../design/okf.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
|
||||
| 外部抽样 | Anthropic Agent Skills · SoK Agentic Skills (arXiv 2602.20867) · ForgeAgent · ACES / Skill Lift · Switchcraft 路由 · DSPy/GEPA ·「工作流编译进权重」· MalSkillBench |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
业界正把 Agent 优化从「更好的 chat loop」转向 **可验证、可复用、可隔离执行的技能层**;Marqdo 已具备 **可执行 Markdown(代码即文档)+ OKF/EKC 复用 + CoW 沙盒** 三件套,优化目标应是把这三件套焊成闭环:**试跑 → 证据 → 晋升 → 零/少 LLM 复用**,而不是追平 LangChain 功能清单。
|
||||
|
||||
---
|
||||
|
||||
## 1. 调研方法
|
||||
|
||||
| 动作 | 说明 |
|
||||
|------|------|
|
||||
| 扫业界技能层 | Anthropic Skills(渐进披露 `SKILL.md`);SoK Agentic Skills 生命周期;ForgeAgent「能力铸造」;ACES Skill Lift |
|
||||
| 扫成本/路由 | Switchcraft 工具调用路由;DSPy+GEPA 提示优化;工作流编译进小模型权重 |
|
||||
| 扫安全 | MalSkillBench 运行时验证恶意技能;沙盒粒度讨论(per-skill / per-session) |
|
||||
| 对照本仓 | A0–A4 / Wave B 已落地;沙盒 S0–S4 已落地;OKF + EKC + adaptive routing 现状 |
|
||||
|
||||
**不修改** `doc/next/*`(手写真相源);本文件只进 `doc/research/`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 业界态势(与 Marqdo 相关的收敛点)
|
||||
|
||||
### 2.1 技能层取代「纯工具调用叙事」
|
||||
|
||||
| 来源 | 要点 | 对 Marqdo |
|
||||
|------|------|-----------|
|
||||
| Anthropic Agent Skills | 目录 + `SKILL.md`;元数据预载、正文按需;脚本可执行 | 形态近 OKF 任务包,但 Marqdo 技能 **本身可跑** |
|
||||
| SoK Agentic Skills | 发现→练习→蒸馏→存储→组合→评测→更新;代码技能需沙盒 | 生命周期与 OKF promote / sandbox.run 对齐 |
|
||||
| ForgeAgent | 生成能力 → 沙盒证明 → 信任复用;失败进回归隔离 | **验证后晋升** 正是 solidify / `llm_free` 缺的硬闸 |
|
||||
| ACES | 有/无技能配对试验 → Skill Lift | 可作 Marqdo 评测 harness 指标 |
|
||||
|
||||
### 2.2 成本:路由 + 编译 + 小模型
|
||||
|
||||
| 来源 | 要点 | 对 Marqdo |
|
||||
|------|------|-----------|
|
||||
| Switchcraft | 工具调用场景路由到最便宜仍正确的模型;报道大幅降本 | 已有 `marqdo \| small-llm \| llm \| auto`;可加 **工具步/试跑步** 细分 |
|
||||
| DSPy / GEPA | 用反馈改写指令,小模型追上大模型 | 优化对象应是 **`.mq.md` 提示文档 / standing / 路由策略文件**,不是黑盒字符串 |
|
||||
| 工作流编译进权重 | 程序化流程进小模型权重,上下文常数级 | 长期对应「高频 OKF 技能 → 专用小模型」;短期优先 **llm_free 源码路径** |
|
||||
|
||||
### 2.3 安全:技能不可信 + 沙盒必验
|
||||
|
||||
恶意技能基准与 SoK 均强调:**技能说明与代码默认不可信**,须运行时隔离。Marqdo 新沙盒(默认拒 plugin/net/exec)正好是技能晋升前的证明场。
|
||||
|
||||
---
|
||||
|
||||
## 3. Marqdo 已有资产(优化起点)
|
||||
|
||||
| 资产 | 现状 | 优化杠杆 |
|
||||
|------|------|----------|
|
||||
| 代码即文档 | `.mq.md` = 程序 = 提示工作面;GFM 表 / 链接取元 | 减少 json 胶水;让模型「看见」结构 |
|
||||
| 写回 | `marqdo-out` 槽;step 默认写回 | 晋升证据、失败避坑 |
|
||||
| OKF / agent-kb | 命中 / near / promote / solidify / `llm_free` | 复用率、降本主轴 |
|
||||
| EKC / EFI | L0–L4 catalog;preflight REUSE/ADAPT/CREATE | 生成前先查工程知识 |
|
||||
| Adaptive routing | marqdo / small-llm / llm / auto + policy 文件 | 再细分 sandbox 试跑 vs 开放推理 |
|
||||
| Sandbox | CoW + capped `run`;`ext/ai/sandbox` | **试跑闸门**;未 commit 不污染仓库 |
|
||||
| MCP / corpus | 证据工具,`authority=workbook` | 保持不升权威 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 问题分析(差距,不是功能羡慕)
|
||||
|
||||
### P1 — 试跑与晋升未焊死
|
||||
|
||||
沙盒已能 CoW 试跑,但 **`agent.step` / `plan` 默认仍可直接改真实树**;OKF `llm_free` 晋升不强制「沙盒金样绿」。
|
||||
→ 风险:未验证技能进入复用池(业界 ForgeAgent / MalSkillBench 已证明此问题)。
|
||||
|
||||
### P2 — 技能形态双轨
|
||||
|
||||
Anthropic Skills = 文件夹 + 渐进披露;Marqdo = 可执行 `.mq.md` + OKF 类型。
|
||||
→ 机会:用 **OKF frontmatter + 可执行体** 统一,不必引入第二套 SKILL.md 权威;缺的是 **披露层级与验证元数据**(适用条件、fixture、sandbox profile)。
|
||||
|
||||
### P3 — 路由粒度偏粗
|
||||
|
||||
现有路由偏「整任务后端」;未区分:查 OKF / 写补丁 / 沙盒 `run` / 对外 HTTP。
|
||||
→ Switchcraft 启示:按 **步骤类型** 选模型,且「便宜模型推理 token 爆炸」要计入总成本。
|
||||
|
||||
### P4 — 评测未锁差异化
|
||||
|
||||
Wave B1 仍 Active:缺稳定 **Skill Lift / 沙盒证明率 / llm_free 命中率 / 文档可读性** 指标。
|
||||
→ 没有指标,优化会滑回「多调几次模型」。
|
||||
|
||||
### P5 — 代码即文档在 Agent 产出侧仍易腐化
|
||||
|
||||
模型仍可能吐 `json.set` 链、混用 EN/ZH API、跳过表结构。
|
||||
→ 沙盒可跑通语法,但 **风格门禁**(lint / preflight)未默认卡在 commit 前。
|
||||
|
||||
### P6 — 上下文与 EKC 未默认进每步
|
||||
|
||||
EFI / catalog 能力在,但 step 默认上下文仍可能偏源码切片,缺少「先 REUSE」硬门槛。
|
||||
|
||||
### P7 — LLM 表面与 Agent 成本账未统一
|
||||
|
||||
`llm.ask` / `stream` / usage 已有;Agent 侧缺 **按会话/技能的成本仪表盘** 写回文档(可 git 审)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 优化目标函数(建议)
|
||||
|
||||
在固定任务集上最大化:
|
||||
|
||||
\[
|
||||
\begin{align*}
|
||||
& \text{ReuseRate}(\text{OKF hit} + \text{llm\_free}) \\
|
||||
&+ \text{SandboxProofRate}(\text{试跑绿再 commit/promote}) \\
|
||||
&- \lambda_1 \cdot \text{TokenCost} - \lambda_2 \cdot \text{HostMutationsWithoutCommit}
|
||||
\end{align*}
|
||||
\]
|
||||
|
||||
约束:权威真相仍是 `.mq.md`;不引入隐藏 TOOL 主循环;不改 `doc/next/*`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 外部资料索引(抽样)
|
||||
|
||||
| 类型 | 链接 |
|
||||
|------|------|
|
||||
| Skills | [Anthropic engineering: Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) · [Claude Code skills](https://code.claude.com/docs/en/skills) · [agentskills / anthropics/skills](https://github.com/anthropics/skills) |
|
||||
| 论文 | [SoK: Agentic Skills](https://arxiv.org/html/2602.20867) · [Skill Issue (repo SKILL 优化)](https://arxiv.org/html/2609.12742v1) · [ACES Skill Lift](https://arxiv.org/html/2608.20614) · [MalSkillBench](https://arxiv.org/html/2606.07131v3) · [Compiling workflows into weights](https://arxiv.org/html/2605.22502) |
|
||||
| 开源/产品 | [ForgeAgent](https://github.com/Yashasm18/ForgeAgent) · [DSPy GEPA](https://dspy.ai/current/getting-started/gepa-optimization/) · [Switchcraft](https://www.microsoft.com/en-us/research/publication/switchcraft-ai-model-router-for-agentic-tool-calling/) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 结语
|
||||
|
||||
Marqdo 不缺「再一个 Agent SDK」;缺的是把 **文档真相、知识晋升、沙盒证明、模型路由** 收成可度量闭环。下一篇方案文档按问题编号给出可选方向与推荐波次,**不预设唯一银弹**。
|
||||
@@ -0,0 +1,392 @@
|
||||
# 调研:AI 扩展库沙盒设计(执行隔离 × 工作区暂存 × 写回)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 供 `ext/ai/*` 沙盒设计锁定参考**(**2026-10-16 修订**:纳入「AI 只生成 Marqdo」产品约束) |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 范围 | 浏览器 WASM / WASI、OS 进程沙盒、容器 / microVM、CoW 叠加工作区、符号链接暂存方案;对照 Marqdo AI 栈 |
|
||||
| 相关设计 | **[ext-ai-sandbox.md](../design/ext-ai-sandbox.md)** · **[roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md)** · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [adr/0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-modules.md](../design/stdlib-modules.md) |
|
||||
| 姊妹调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) · [ext-ai-optimize.md](../design/ext-ai-optimize.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**在「Agent 只生成 / 只执行 Marqdo(`.mq.md`)」这一产品约束下,Marqdo AI 沙盒应以 Wasm 为主沙盒——且必须是「内核 + `lib/*` + `ext/*`」可运行的完整运行时沙盒,而不是只跑光秃解释器。**
|
||||
|
||||
锁定方向:
|
||||
|
||||
1. **执行隔离 = Marqdo Wasm 运行时(与 ADR 0002 同构)** — deny-by-default 能力导入;**默认不授予** shell / 外联 / `dlopen` 原生插件。AI 产出面收窄到 Markdown 程序后,不必为通用 coding Agent 的「任意二进制」付沙盒税。
|
||||
2. **库完备性是验收线,不是加分项** — 沙盒内须能 `import lib/…` 与受支持的 `ext/…`;缺能力时 **显式失败**,禁止静默空成功(对齐 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5)。
|
||||
3. **工作区突变 = CoW / whiteout / 显式 commit**(应用层 VFS,必要时 overlay)— 「修改短暂不生效 → 确认写回」保留;**禁止以符号链接森林作为隔离边界**。
|
||||
4. **OS 沙盒 / microVM** — 降为 **逃逸舱 / 托管 Profile**:仅当显式启用 foreign、`subtask` 真子进程、或未来多租户托管时使用;**不是** Marqdo-only Agent 的默认主路径。
|
||||
|
||||
初稿曾按「通用 coding Agent 还需 shell」把 Wasm 与 bwrap 并列;在 Marqdo-only 约束下,主结论改为 **Wasm-first + 库完备 + CoW 写回**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 调研方法与边界
|
||||
|
||||
### 1.1 做了什么
|
||||
|
||||
| 动作 | 说明 |
|
||||
|------|------|
|
||||
| 厂商/产品文档 | Anthropic Claude Code sandbox / `@anthropic-ai/sandbox-runtime`;VS Code Copilot agent sandboxing;Docker AI Sandboxes;Turso AgentFS CoW overlay;OpenSandbox isolation sessions;WASI / jco preview2-shim;VS Code for the Web WASM webshell |
|
||||
| 工程对比文 | Northflank / Cosmonic 2026 agent sandbox 指南;gVisor vs Firecracker vs Docker 对比;ContainAI security comparison |
|
||||
| 学术与标准 | USENIX SEC'22 *Provably-Safe Multilingual Software Sandboxing using WebAssembly*;KTH 论文 *Intra-process Fault Isolation Using WebAssembly*(SFI 通信开销);ACM TOSEM *Research on WebAssembly Runtimes: A Survey*(2025);WASI Design Principles(capability / 无 ambient authority) |
|
||||
| 安全案例 | brig 项目挂载 symlink 逃逸(CVSS 8.2);Anthropic sandbox-runtime 对 bwrap bind 跟随 symlink 的修复;Docker Sandbox「direct mount vs clone」威胁说明 |
|
||||
| 对照本仓 | `ext/ai/{llm,agent}`、`lib/writeback`、`lib/subtask`、ADR 0002 浏览器 WASM、`RunOptions.allow_fs_write` 默认关 |
|
||||
|
||||
### 1.2 不做的
|
||||
|
||||
- 不把「发版用的容器镜像」与「Agent 工具沙盒」混为一谈。
|
||||
- 不宣称某一云厂商托管沙盒(E2B / Modal / Daytona)为 Marqdo 默认依赖。
|
||||
- 不修改 `doc/next/*`(手写真相源);本文件只进 `doc/research/`。
|
||||
|
||||
### 1.3 产品约束(修订要点):AI 只生成 Marqdo
|
||||
|
||||
这是相对通用 coding Agent(Claude Code / Codex)的 **结构性好消息**:
|
||||
|
||||
| 通用 Agent | Marqdo AI Agent(本调研采纳) |
|
||||
|------------|------------------------------|
|
||||
| 模型可产出 shell / Python / 任意仓库补丁 | 模型产出面收束为 **`.mq.md`(文档即程序)** |
|
||||
| 沙盒必须兼容「整台开发机能力」 | 沙盒只需跑 **同构 Marqdo 运行时** |
|
||||
| Wasm 往往只能罩住工具子集 | Wasm **可以**成为主执行边界 |
|
||||
| 标准库 = 语言运行时 + OS 工具链 | 标准库 / 扩展 = **`lib/*.mq.md` + `ext/**`(+ 受控宿主能力)** |
|
||||
|
||||
硬规则建议(后续 design 应写死):
|
||||
|
||||
1. Agent 工具表 **不提供** 通用 `bash` / 任意语言 `exec`(除非显式 opt-in 逃逸舱,且另套 OS 沙盒)。
|
||||
2. Agent 改仓库的权威动作是 **写 / 修订 `.mq.md`(含写回块)**,经 CoW 会话再 `commit`。
|
||||
3. 运行 Agent 生成的程序 = 在沙盒里 `run` 该 `.mq.md`,且其 `import` 的 **lib 与 ext 必须可用或显式报不可用**。
|
||||
|
||||
### 1.4 威胁模型(在 Marqdo-only 下收窄)
|
||||
|
||||
| 威胁 | 典型路径 | Marqdo-only 下的权重 |
|
||||
|------|----------|----------------------|
|
||||
| T1 提示注入 | 诱导读密钥、外泄、破坏 `.mq.md` | 仍高 — 靠能力拒绝 + CoW |
|
||||
| T2 工具侧信道 | `subtask`/`foreign` 子进程 | **默认关闭**;opt-in 才升权 |
|
||||
| T3 工作区即时破坏 | 直接写穿源树 | 靠 CoW;commit 闸门 |
|
||||
| T4 挂载逃逸 | symlink / bind 打穿 | 仍相关 — **勿用 symlink 作 W 层** |
|
||||
| T5 网络外泄 | `lib/net` / llm 出站 | 能力开关 + 域名策略 |
|
||||
| T6 Wasm 宿主桥过宽 | `host_fs_*` / 插件桥过宽 | **主威胁** — 桥 = 权限表 |
|
||||
| T7 库残缺假安全 | 沙盒能跑 `# main` 但 `import lib/fs` 怪崩或静默空 | **产品验收威胁** |
|
||||
|
||||
**成功标准:** 失败域止于会话 upper + 已授予能力;真实工作区默认只读直至 commit;**代表性 `lib/*` 与 `ext/*` 金样在沙盒内可跑或得到明确 `unavailable in sandbox` 诊断**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 先拆三个「沙盒放哪里」(Marqdo-only 版)
|
||||
|
||||
业界「Harness / Workspace / Execution」三分法仍成立,但 **Execution 的内容变了**:
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Pattern H — Harness(编排环) │
|
||||
│ ext/ai/agent · parent Plan-and-Move ·(可选)MCP client │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Pattern W — Workspace mutation(.mq.md 真相如何变) │
|
||||
│ CoW upper / whiteout / diff / commit → writeback │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Pattern X — 执行 Agent 产出的 Marqdo 程序 │
|
||||
│ Wasm Marqdo runtime + embedded/packaged lib + sandboxed │
|
||||
│ ext 能力面(非「任意 shell」) │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| Pattern | Marqdo 落点 | 沙盒要解决什么 |
|
||||
|---------|-------------|----------------|
|
||||
| H | `ext/ai/agent` | 编排是否持有过宽宿主权限;模型 I/O 与执行隔离 |
|
||||
| W | `lib/writeback` · 工作簿 | 编辑是否立刻污染仓库;人审/父裁决后落盘 |
|
||||
| X | **Wasm 内 `run` `.mq.md`** | 计算隔离;**lib/ext 能力是否完备且受控** |
|
||||
|
||||
用户提案在 Marqdo-only 下:**Wasm 作 X 主底层是正确方向**;仍须改掉 symlink,并补上 **库完备性** 这一环。
|
||||
|
||||
---
|
||||
|
||||
## 3. 方案谱系(横向对比)
|
||||
|
||||
> **读法(修订后):** 下表仍保留通用 Agent 对照。对 **Marqdo-only** 产品,请以 §0 / §5 / §6 的 Wasm-first 结论为准;本节 A/B 升权,F/G/H 降为逃逸舱或托管。
|
||||
|
||||
评分:● 强 / ◐ 中 / ○ 弱 / — 不适用。维度按「隔离强度」等客观属性;**产品适配**见 §5。
|
||||
|
||||
| 方案 | 隔离强度 | 启动成本 | 任意二进制 | 工作区暂存语义 | 与 Marqdo 契合 | 主要风险 |
|
||||
|------|----------|----------|------------|----------------|----------------|----------|
|
||||
| **A. 浏览器 WASM + 虚拟 FS** | ●(计算)◐(经桥的 FS) | ● | ○ | ◐(需自建 overlay) | ●(已有 ADR 0002) | 宿主桥过宽;无原生 toolchain |
|
||||
| **B. WASI / Component Model(非浏览器亦可)** | ● | ● | ○(仅 WASI 目标) | ●(preopens + 自建 VFS) | ● | 工具链不全则需降级 |
|
||||
| **C. 符号链接映射工作区 + 延迟写回** | ○ | ● | —(本身不是执行沙盒) | ◐(似是而非) | ○ | **symlink 逃逸是已知高危类** |
|
||||
| **D. 应用层 CoW VFS(upper/lower/whiteout)** | ◐(逻辑) | ● | — | ● | ●● | 必须配合 X 层 OS 隔离 |
|
||||
| **E. OS overlayfs / FUSE / AgentFS 式 CoW** | ●(配合命名空间) | ◐ | ●(在沙盒内) | ●● | ● | Linux/macOS 实现分叉;运维 |
|
||||
| **F. bubblewrap / Seatbelt(Anthropic SRT 类)** | ● | ● | ● | ○(默认可写 cwd) | ● | 需另加 CoW 才有「暂不生效」 |
|
||||
| **G. Docker / 硬化容器 / gVisor** | ◐→● | ◐ | ● | ◐(volume 策略) | ◐ | 共享内核或兼容性;重 |
|
||||
| **H. microVM(Firecracker / Kata)** | ●● | ◐ | ● | ◐ | ○(本地 CLI 过重) | KVM/运维;适合多租户托管 |
|
||||
| **I. 纯语言沙盒(RestrictedPython 等)** | ○ | ● | ○ | — | ○ | 对 Agent 工具链几乎无用 |
|
||||
|
||||
### 3.1 A — 浏览器 WASM + 虚拟 FS
|
||||
|
||||
**机制:** Wasm 线性内存 + 校验 + 仅经 import 碰宿主;FS 多为内存树 / OPFS / 经 JS bridge 的映射。Marqdo 已锁定「解释器进 WASM」(ADR 0002),默认 `allow_fs_write=false`。
|
||||
|
||||
**文献支撑:** Wasm 作为 SFI 窄腰(Bosamiya et al., USENIX SEC'22);进程内沙盒跨边界通信可比 IPC 快数量级(KTH Wasm-SFI 论文);WASI 明确 **capability / 无 ambient authority**。
|
||||
|
||||
**优点:** 与「代码即文档」浏览器运行同构;deny-by-default;适合跑 `.mq.md`、公式库、受控插件。
|
||||
**缺点:** 不能原生跑 `cargo test` / `npm` / 任意 shell;安全上限取决于 **bridge 授予了什么**;浏览器场景下「符号链接用户工作区」通常要落到 File System Access API 或服务端中继,**不是** POSIX symlink 语义。
|
||||
|
||||
**判定:** 在 **Marqdo-only** 约束下,作为 **Pattern X 主沙盒** 与浏览器内 Marqdo 的正解;完备性取决于 **lib 嵌入 + ext 能力桥**(§4.1),不取决于 shell。通用「任意二进制 Agent」场景下仍不够——但那不是本产品默认。
|
||||
|
||||
### 3.2 B — WASI / Component Model(CLI 宿主)
|
||||
|
||||
**机制:** preopens 显式挂载;`WASIShim({ sandbox: { preopens, enableNetwork: false } })`(Bytecode Alliance jco);Component imports = 权限表。
|
||||
|
||||
**优点:** 与 Wasm 同族,可在 Node/Wasmtime 跑,不绑浏览器;能力模型清晰。
|
||||
**缺点:** 同 A,任意 Linux 工具链需「宿主机再包一层」或改编译目标。
|
||||
|
||||
**判定:** Marqdo **官方扩展 / 插件中可 Wasm 化的部分**应走这条;与 ADR 0002 一条能力谱。
|
||||
|
||||
### 3.3 C — 符号链接映射工作区(用户设想的核心)
|
||||
|
||||
**设想:** 沙盒根下用 symlink 指向用户文件;写改暂存别处;确认后写回;删除 = 删 symlink。
|
||||
|
||||
**表面吸引力:** 零拷贝读、实现「像」有暂存。
|
||||
|
||||
**为何行业不把它当隔离原语:**
|
||||
|
||||
1. **Bind/mount 跟随 symlink 是经典逃逸。** Anthropic `sandbox-runtime` 明确修复:`allowWrite` 若为指向界外的 symlink,bwrap `--bind` 会把真实目标变成可写(PR #138 类修复)。
|
||||
2. **项目挂载未解析 symlink 可致高危。** Endor Labs 披露 brig「project mount symlink traversal」(CVSS 8.2):Agent 在可写项目内把子目录换成指向 `/etc` 的 symlink,下一轮宿主机按字符串挂载即打穿。
|
||||
3. **「删除 = 删 symlink」语义错误。** 删链接只去掉别名,**不等于**对 lower 层文件的 whiteout;若链接指向真实文件且曾被打开写穿,删除链接也救不回。
|
||||
4. **写穿风险。** 若某路径被解析成真实 inode 且可写,暂存承诺立刻破产。
|
||||
5. **跨平台。** Windows junction/reparse、浏览器虚拟 FS、容器 bind,行为不一致。
|
||||
|
||||
**判定:** **否决作为 Marqdo 默认工作区隔离方案。** 允许在 **只读、已解析、拒绝可写路径上的 symlink 组件** 的前提下作实现细节,但不得当作安全边界叙事。
|
||||
|
||||
### 3.4 D — 应用层 CoW VFS(推荐作 W 层默认)
|
||||
|
||||
**机制:**
|
||||
|
||||
```text
|
||||
lower = 真实工作区(只读打开 / 只读能力)
|
||||
upper = 会话 delta(内存 map / 目录树 / SQLite blob)
|
||||
whiteout = 逻辑删除集合
|
||||
view(path) = upper ?? (!whiteout && lower)
|
||||
commit() = 把 upper/whiteout 应用到 lower(可经人审)
|
||||
discard() = 丢弃会话
|
||||
diff() = 可审变更集
|
||||
```
|
||||
|
||||
与 Turso AgentFS、OpenSandbox `workspace.mode: overlay` 的 **语义同构**,但不强制 FUSE。
|
||||
|
||||
**与 Marqdo 对齐点:**
|
||||
|
||||
| VFS 操作 | Marqdo 真相 |
|
||||
|----------|-------------|
|
||||
| `diff()` | 父 Agent / 人审材料;可进 view |
|
||||
| `commit()` 文本结果 | `writeback.record` / 工作簿补丁 |
|
||||
| `discard()` | 失败回合不污染仓库 |
|
||||
| 只读 lower | 防止 T3 即时破坏 |
|
||||
|
||||
**优点:** 纯用户态、可测、可嵌入 `plugins/agent`;不依赖 root/FUSE;金样可锁。
|
||||
**缺点:** 对 **沙盒内原生工具**(它们走真实 POSIX)不可见,除非再挂 E 或把工具 I/O 也改走 VFS API。
|
||||
|
||||
**判定:** **Pattern W 的默认实现。**
|
||||
|
||||
### 3.5 E — OS CoW overlay(AgentFS / overlayfs / OpenSandbox)
|
||||
|
||||
**机制(AgentFS 公开设计):** lower=宿主只读;upper=SQLite delta;删除=whiteout;Linux 用 FUSE+user/mount ns;macOS 用 NFS+`sandbox-exec`。OpenSandbox 默认 `overlay`,会话结束可丢 upper。
|
||||
|
||||
**优点:** 对 **任意 shell 工具**透明;「改了但宿主机 `git status` 仍干净」体验业界已验证。
|
||||
**缺点:** 平台依赖;FUSE 权限;与应用层 D 双实现成本。
|
||||
|
||||
**判定:** **当 Pattern X 需要真实 shell 且要求暂存对工具透明时**启用(Linux 优先);作为 D 的「native 加速后端」,不是替代 Wasm。
|
||||
|
||||
### 3.6 F — OS 进程沙盒(bwrap / Seatbelt / VS Code Copilot)
|
||||
|
||||
**机制:** Anthropic:文件系统隔离 + **网络隔离(缺一不可)**;Linux bubblewrap + 代理;macOS Seatbelt。VS Code Copilot:同类依赖;路径分 readwrite / readonly / denied;明确「不是 VM,削弱授权即削弱边界」。
|
||||
|
||||
**优点:** 本地编码 Agent 的事实标准;覆盖子进程;启动轻。
|
||||
**缺点:** 默认可写 cwd → **没有**「暂不生效」;必须与 D/E 组合。Symlink 配置路径需解析与拒绝。
|
||||
|
||||
**判定:** **Pattern X(shell/外联/MCP)本地默认。**
|
||||
|
||||
### 3.7 G / H — 容器与 microVM
|
||||
|
||||
**共识:** 裸 Docker 共享内核,不适合作唯一边界应对不可信代码;gVisor 加强 syscall 拦截;Firecracker/Kata 适合多租户与高威胁(~125ms 级启动)。Docker AI Sandboxes 区分 **direct mount(即时写穿)** vs **clone(只读源 + 私有副本)**——后者才接近「确认后写回」。
|
||||
|
||||
**判定:** Marqdo **本地 CLI 默认不强制 microVM**;若未来 `ext` 提供托管执行 / 多租户,再把 H 定为服务端 Profile。G 可作为打包/CI Profile。
|
||||
|
||||
### 3.8 I — 语言级沙盒
|
||||
|
||||
对「Agent 会跑 shell」场景基本无效;仅作极窄解释器内嵌参考。
|
||||
|
||||
---
|
||||
|
||||
## 4. 专门评估:用户提案(修订)
|
||||
|
||||
> 浏览器 WASM 作沙盒底层 + 符号链接用户工作区 + 修改短暂不生效 + 确认后写回 + 删除变删 symlink。
|
||||
> **补充约束:** AI 只生成 Marqdo;沙盒须能用标准库与扩展库。
|
||||
|
||||
| 子命题 | 评价 | 说明 |
|
||||
|--------|------|------|
|
||||
| Wasm 作主执行隔离 | **在 Marqdo-only 下正确** | 与 ADR 0002 同构;不必为 shell 全集付税 |
|
||||
| 沙盒须含 lib + ext | **正确且关键** | 「能跑 `# main`」≠ 好沙盒;见 §4.1 |
|
||||
| 「短暂不生效」 | **正确** | CoW / staging(方案 D,必要时 E) |
|
||||
| 「确认后写回」 | **正确且极契合 Marqdo** | 与 writeback、父裁决、workbook 同一哲学 |
|
||||
| 「symlink 映射工作区」 | **仍错误** | 与是否只用 Marqdo 无关;换 CoW/whiteout |
|
||||
| 「删除 = 删 symlink」 | **仍错误** | 应为 whiteout;commit 时再对 lower 删除 |
|
||||
| 「性能最好且安全性最高」 | **Wasm 主路径下接近成立** | 前提是桥最小权限 + CoW;symlink 仍拉低安全 |
|
||||
|
||||
**修订后的正确表述:**
|
||||
|
||||
> **以 Wasm Marqdo 运行时为主沙盒,打包/嵌入 `lib/*`,经能力桥提供受支持的 `ext/*`;工作区用 lower 只读 + upper/whiteout;人审/父裁决后 commit。符号链接不作隔离原语。shell/外联/原生 dlopen 默认关闭,仅作显式逃逸舱。**
|
||||
|
||||
### 4.1 库完备性:什么叫「标准库和扩展库也能用」
|
||||
|
||||
沙盒若只能跑内置算术、却不能 `import lib/json` 或跑 `ext/ai/llm` 的离线金样,对 Agent 开发几乎无用——模型生成的 `.mq.md` **本来就会依赖 lib/ext**。
|
||||
|
||||
三类库进沙盒的路径不同:
|
||||
|
||||
| 类别 | 今日形态 | 沙盒策略 |
|
||||
|------|----------|----------|
|
||||
| **纯 `.mq.md` 库**(多数 `lib/*`、部分 `ext` 门面) | 源码 import | **嵌入或会话导入图**(已有 `embedded_lib` / import map)— 必须默认可用 |
|
||||
| **需宿主能力的 lib**(`fs` / `net` / `writeback` / `subtask` / `datetime.now`…) | `host_*` | **经能力表桥接**到会话 VFS / 受控 clock / 受控 fetch;默认最小集 |
|
||||
| **原生 ABI 扩展**(`plugins/web`、`plugins/agent`、quantum 等 `.so`) | `plugin.load` + dlopen | 浏览器/Wasm **无 dlopen**(ADR 0002 N2)。沙盒内应:**纯 mq 门面 + Wasm 插件**、或 **宿主代执行且权限计入会话**、或 **显式 `unavailable`** — 禁止假装成功 |
|
||||
|
||||
与 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5 对齐并扩展为 **Agent 沙盒能力矩阵(草案)**:
|
||||
|
||||
| 能力 | 沙盒默认 | 备注 |
|
||||
|------|----------|------|
|
||||
| builtins / 表 / 控制流 / 对象 | ✓ | 内核 |
|
||||
| `lib/math` `json` `table` `text` `collection`… | ✓ | embedded |
|
||||
| `lib/fs` | ✓(仅会话 VFS) | 写进 upper;禁越出 root |
|
||||
| `lib/writeback` | ✓(写会话内 `.mq.md`) | commit 后才进真实树 |
|
||||
| `lib/net` / llm HTTP | 默认关 / 域名白名单 | 与 T5 |
|
||||
| `lib/subtask` `fn=` | ✓(同 Wasm 会话) | |
|
||||
| `lib/subtask` `path=`/`code=`/`lang=` | **默认拒** | 逃逸舱 + OS 沙盒 |
|
||||
| `lib/plugin` + 原生 `.so` | **默认拒** | 改 Wasm 插件或宿主代执行 |
|
||||
| `ext/ai/llm` · `ext/ai/agent`(mq 门面) | ✓(能力允许时) | 网络/密钥另授 |
|
||||
| `ext/web` 服务端 listen/DB | **默认拒或只读 stub** | 完整 axum 不进沙盒;可测「装配/渲染」子集 |
|
||||
| `ext/quantum` / `ext/linalg` | 目标 ✓ | 优先纯逻辑 / Wasm 插件,避免强依赖宿主机 .so |
|
||||
|
||||
**验收金样建议(S 阶段):**
|
||||
一套「沙盒烟囱」:`import` 常用 lib → 写会话文件 → writeback → `diff` → `commit`;再各挑一个 **纯逻辑 ext** 与一个 **需网络的 ext**(后者验证拒绝/白名单)。缺能力必须诊断含 `unavailable in sandbox`(或同等措辞)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 综合评分(面向 Marqdo-only 产品)
|
||||
|
||||
加权(修订):执行隔离契合 Marqdo-only 30%、**lib/ext 完备** 25%、与 writeback 真相 20%、实现成本 15%、跨端(CLI↔浏览器)10%。
|
||||
(「任意 shell 工具完备」不再作为主权重。)
|
||||
|
||||
| 候选架构 | 分(相对) | 备注 |
|
||||
|----------|------------|------|
|
||||
| **A/B Wasm-first + D CoW + 库完备能力表** | **100(推荐)** | 主路径 |
|
||||
| 同上 + 逃逸舱 F(opt-in shell) | 95 | 兼容少数 foreign 需求 |
|
||||
| D + E + F(通用 coding 向) | 75 | 过重;非 Marqdo-only 默认 |
|
||||
| 仅 F(可写 cwd) | 55 | 缺 CoW;且鼓励非 mq 工具 |
|
||||
| 仅 A 但无 CoW、无 lib 嵌入 | 40 | 「半沙盒」 |
|
||||
| 仅 C(symlink) | 20 | 否决 |
|
||||
| 仅 H(人人 microVM) | 50 | 托管可选;本地默认过重 |
|
||||
|
||||
**绝对「最硬」单点**仍可以是 microVM(托管 Profile)。
|
||||
**Marqdo「最合适」:** **Wasm 完整运行时沙盒(内核+lib+受控 ext)+ CoW 工作区 + commit 闸门**。
|
||||
|
||||
---
|
||||
|
||||
## 6. Marqdo 应采用的沙盒设计(推荐锁定草案 · 修订)
|
||||
|
||||
### 6.1 产品形态
|
||||
|
||||
| Profile | 场景 | 执行(X) | 工作区(W) |
|
||||
|---------|------|-----------|------------|
|
||||
| **`mq-sandbox`(默认)** | Agent 生成并试跑 `.mq.md` | **Wasm Marqdo** + embedded `lib/*` + 能力桥 `ext` | 应用层 CoW;commit→真实树 / writeback |
|
||||
| **`browser`** | 页内同构运行 | 同左(ADR 0002) | 内存/OPFS;无 POSIX symlink |
|
||||
| **`escape`(显式)** | foreign / 真子进程 | OS 沙盒包一层 | 仍建议 CoW 可见 |
|
||||
| **`hosted`(可选)** | 多租户 | Wasm 或 microVM | 会话隔离;凭证外置 |
|
||||
|
||||
### 6.2 推荐架构图
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────┐
|
||||
│ ext/ai/agent (Harness) │
|
||||
│ 只产出 / 编排 .mq.md · 人审闸门 │
|
||||
└──────────────────┬───────────────────┘
|
||||
│
|
||||
┌─────────────────────┼─────────────────────┐
|
||||
▼ ▼
|
||||
┌────────────────────┐ ┌────────────────────┐
|
||||
│ Workspace CoW (W) │ │ Marqdo Wasm (X) │
|
||||
│ lower = RO 工作区 │◄── fs/writeback ───│ 同构解释器/VM │
|
||||
│ upper / whiteout │ 能力导入 │ + embedded lib/* │
|
||||
│ diff·commit·discard│ │ + ext 能力面 │
|
||||
└─────────┬──────────┘ │ 默认: 无 shell/so │
|
||||
│ └────────────────────┘
|
||||
▼
|
||||
真实工作区 / <!-- marqdo-out -->
|
||||
(代码即文档真相源)
|
||||
|
||||
(可选)escape: subtask path|code|lang → OS sandbox
|
||||
```
|
||||
|
||||
### 6.3 API 面建议(设计级,非立即实现)
|
||||
|
||||
落点倾向:宿主能力进 `plugins/agent` / Wasm HostContext;作者面经 `ext/ai` 或 `lib`(**禁止** `ext/**` 直调 `host_*`)。
|
||||
|
||||
| 概念 | 语义 |
|
||||
|------|------|
|
||||
| `sandbox.open(root, mode=cow)` | 打开会话;lower 只读 |
|
||||
| `sandbox.read/write/list/remove` | 经 view;remove → whiteout |
|
||||
| `sandbox.diff` / `stat` | 供父 Agent / view |
|
||||
| `sandbox.commit` / `discard` | 闸门;可要求 HITL |
|
||||
| `sandbox.run(source\|path, caps=…)` | **Wasm 跑 Marqdo**;caps 声明 fs/net/llm/… |
|
||||
| `sandbox.caps` / `inspect` | 列出已授能力与 lib/ext 可用性(对齐 `web.inspect` 哲学) |
|
||||
| `sandbox.exec(...)` | **仅 escape Profile**;默认不存在于作者工具表 |
|
||||
|
||||
与现有衔接:
|
||||
|
||||
- `lib/*`:优先 embedded;FS/时间/网络走会话 caps。
|
||||
- `ext/*`:mq 门面可加载;原生插件默认不可用并诊断;长期可 Wasm 化的(linalg/quantum 逻辑)优先进 Wasm。
|
||||
- `lib/writeback`:写入会话内文件;`commit` 时进入真实树。
|
||||
- `lib/subtask`:默认仅 `fn=`;`path`/`code`/`lang` 要 escape。
|
||||
|
||||
### 6.4 硬禁(写入后续 design 时应保留)
|
||||
|
||||
1. **不以 symlink 森林作为隔离或暂存原语。**
|
||||
2. **不以「能跑空 `# main`」宣称沙盒完成** — 必须过 lib/ext 完备金样或显式 unavailable。
|
||||
3. **默认工具表不提供通用 shell / 任意语言 exec。**
|
||||
4. **不默认可写 bind 真实工作区。**
|
||||
5. **宿主桥 = 权限表**:未授能力不得 ambient 成功。
|
||||
6. **不静默降级**:缺 Wasm/能力时不得假装已隔离。
|
||||
7. **`ext/**` 不调 `host_*`**(既有宪法)。
|
||||
|
||||
### 6.5 分阶段落地(建议,非 `doc/next`)
|
||||
|
||||
| 阶段 | 交付 | 验收线索 |
|
||||
|------|------|----------|
|
||||
| S0 | 威胁模型 + 本调研(含 Marqdo-only) | 本文 |
|
||||
| S1 | Wasm `run` + embedded 核心 `lib/*` + 会话 VFS 读 | 常用 lib 金样在沙盒绿 |
|
||||
| S2 | CoW upper/whiteout + diff/commit/discard | 未 commit 时宿主机 `git status` 干净 |
|
||||
| S3 | writeback / 工作簿在会话内可写;commit 对齐 | agent step 金样 |
|
||||
| S4 | caps:net/llm 白名单;`subtask` 非 fn 默认拒 | 诊断字符串稳定 |
|
||||
| S5 | 代表性 ext(纯逻辑 + 需网)沙盒金样 | 完备性验收 |
|
||||
| S6 | (可选)escape OS 沙盒;hosted microVM | 文档标明非默认 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 外部资料索引(抽样)
|
||||
|
||||
| 类型 | 引用 |
|
||||
|------|------|
|
||||
| 产品 | [Anthropic: Claude Code sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) · [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) · [VS Code agent sandboxing](https://code.visualstudio.com/docs/agents/run/agent-sandboxing) · [Docker AI Sandboxes security](https://docs.docker.com/ai/sandboxes/security/) · [Turso AgentFS overlay](https://turso.tech/blog/agentfs-overlay) · [OpenSandbox isolation sessions](https://open-sandbox.ai/guides/isolation-sessions) |
|
||||
| 标准 | [WASI Design Principles](https://github.com/WebAssembly/WASI/blob/main/docs/DesignPrinciples.md) · [jco preview2-shim sandbox](https://github.com/bytecodealliance/jco/blob/main/packages/preview2-shim/README.md) |
|
||||
| 论文 | Bosamiya et al., *Provably-Safe Multilingual Software Sandboxing using WebAssembly*, USENIX Security 2022 · *Intra-process Fault Isolation Using WebAssembly* (KTH) · *Research on WebAssembly Runtimes: A Survey*, ACM TOSEM 2025 |
|
||||
| 综述 | [Cosmonic: Choosing an AI agent sandbox (2026)](https://cosmonic.com/ai-sandbox/choosing-an-agent-sandbox/) · [Northflank: MicroVMs, gVisor & isolation](https://northflank.com/blog/how-to-sandbox-ai-agents) |
|
||||
| 安全案例 | [brig symlink traversal / Endor Labs](https://www.endorlabs.com/learn/project-mount-symlink-traversal-in-brig-how-a-sandbox-reaches-host-directories-it-was-never-given) · Anthropic sandbox-runtime symlink bind 修复 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 结语
|
||||
|
||||
- **产品好消息:** Agent 只生成 Marqdo → **Wasm 主沙盒设计成立**,不必默认扛通用 shell Agent 的复杂度。
|
||||
- **好沙盒的定义:** 不只跑内核,还要 **`lib/*` 可用、`ext/*` 在能力表内可用或显式不可用**;再加 **CoW + commit** 保护仓库真相。
|
||||
- **仍要改掉的:** 符号链接当暂存/隔离;默认开放 foreign/dlopen;「空 main 能跑」就算完工。
|
||||
- **降级为非默认的:** bwrap/microVM — 留给 escape / hosted,而不是 Marqdo-only 主路径。
|
||||
|
||||
不急着实现。下一步若继续收敛,再开 `doc/design/ext-ai-sandbox.md` 把 **能力矩阵 + 库完备金样清单** 锁死即可;**仍不要改 `doc/next/*`**。
|
||||
@@ -0,0 +1,290 @@
|
||||
# 外联内核 · 文档会话 · 决策记录
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Decided(由用户授权代为拍板)** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 范围 | 外联库(`lib/foreign`)· 外联内核 · 文档会话 · view notebook 交互 |
|
||||
| 相关 | [foreign-kernel.md](../design/foreign-kernel.md) · [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [notebook-session.md](../roadmap/notebook-session.md) |
|
||||
| 核心表面 Δ | **无**——不新增 Markdown 标记;只使用既有 `#` / `##` / 表格 / 反引号 |
|
||||
|
||||
> 本文件记录「为什么这样设计」。实现细节分别落在设计文档与路线图中;本文件不重复 API 表。
|
||||
|
||||
---
|
||||
|
||||
## 0. 背景与授权
|
||||
|
||||
用户的核心诉求:
|
||||
|
||||
1. Marqdo 的本质是 **代码即文档、文档即知识库**;`.mq.md` 天生兼容 Markdown / OKF 知识库。
|
||||
2. 外联库的初衷是**对标 Jupyter**:让文档与代码并行有用;但 Jupyter 有 Git 难跟踪、隐藏状态、execution_count 噪声等问题,Marqdo 要解决并超越。
|
||||
3. `view` 模式天然适合这种交互(已有执行按钮、结构视图、writeback、trace)。
|
||||
4. 之前外联库功能太单一;接下来必须支持:
|
||||
- 多个代码块共享外联状态;
|
||||
- 单步执行;
|
||||
- 切换哪些外联内核共享状态;
|
||||
- Marqdo 的状态/变量被外联使用;
|
||||
- 外联的状态/变量被 Marqdo 使用。
|
||||
5. 用户要求:**安全第一、效果最好、功能最强悍、不降级**;充分测试;每份讨论落成详细文档;文档提交并推送后再开发。
|
||||
6. 用户强调:**设计语法不要用代码思维**,语法要天然可读。
|
||||
|
||||
本文档 = 对该授权的决策记录。后续实现若与本文冲突,先改本文并说明理由。
|
||||
|
||||
---
|
||||
|
||||
## 1. 关键结论
|
||||
|
||||
### 结论 A:外联库不是“跑 Python 的函数”,而是多语言内核运行时
|
||||
|
||||
`lib/foreign` 的定位升级为:
|
||||
|
||||
> **文档运行时与外部语言运行时之间的内核/会话层**:启动内核、执行代码单元、持久化状态、双向类型桥、生命周期与安全。
|
||||
|
||||
它不等同于 `subtask`(一次性并发任务),也不等同于 `writeback`(输出持久化)。
|
||||
|
||||
### 结论 B:Jupyter 级体验需要两层,不是一层
|
||||
|
||||
| 层 | 名称 | 责任 |
|
||||
|---|---|---|
|
||||
| **F** | Foreign Kernel Runtime | 内核进程、语言发现/注册、JSON 桥、会话、安全、记录 |
|
||||
| **D** | Document Session | 文档会话、cell index、kernel 分配、单步、状态面板、执行日志、view 交互 |
|
||||
|
||||
上一版 `foreign-v2` 只覆盖 F。共享状态 / 单步 / 切换内核属于 D。两层分开设计、分开验收。
|
||||
|
||||
### 结论 C:Hybrid 执行模型
|
||||
|
||||
- **Program mode(规范模式)**:`marqdo run` / CI / 可复现执行。文档是程序;外联通过显式 `foreign.session_*` / `call` 编排;结果可重复。
|
||||
- **View cells(交互面)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档;不是第二个 CLI 模式。
|
||||
- 两者共享同一个内核运行时与同一套 cell 索引;view cells 是 program execution 的**交互镜头**,不是替代品。
|
||||
|
||||
理由:如果让 cell 执行取代文档程序语义,Marqdo 就退化成 Jupyter;如果只有 Program mode,就失去 Jupyter 的即时反馈。Hybrid 同时保留两者。
|
||||
|
||||
### 结论 D:命名内核;同内核共享,跨内核/跨语言显式传值
|
||||
|
||||
- 一个文档可以有多个命名内核:`py:分析`、`py:绘图`、`js:前端`。
|
||||
- 同一内核的 cell 共享全局状态。
|
||||
- 不同内核(即使同语言)默认隔离。
|
||||
- 不同语言不共享进程内存;只能通过 JSON / 文件 / DB 显式交换。
|
||||
- 默认每个文档、每种语言一个 `default` 内核;命名内核按需开启。
|
||||
- 跨文档默认隔离;全局内核以后再做。
|
||||
|
||||
### 结论 E:三种单步,分阶段实现
|
||||
|
||||
| 单步 | 含义 | 版本 |
|
||||
|---|---|---|
|
||||
| **Cell step** | 执行下一个代码单元,状态保留 | v2 必做 |
|
||||
| **Marqdo statement step** | 逐条执行 Marqdo 语句,查看变量 | v2 复用现有 debugger |
|
||||
| **Foreign line step** | 进入 Python/Node 逐行 | v2 不做;后续接 DAP/pdb/debugpy |
|
||||
|
||||
- 外联 cell 在 statement step 中是原子操作。
|
||||
- “Step into foreign” 是独立项目,不能混入首版。
|
||||
|
||||
### 结论 F:显式状态桥优先,不做隐式自动镜像
|
||||
|
||||
- 默认通过 `session_set` / `session_get` / `call input` / `call result` 交换,JSON 拷贝。
|
||||
- 不默认把 Marqdo 变量自动注入 Python,也不默认把 Python 变量自动写回 Marqdo。
|
||||
- 原因:命名冲突、Secret 泄漏、类型丢失、隐式状态、不可复现、大对象拷贝。
|
||||
- 后续可选 `mirror=True`:只同步 `mq_` 前缀、白名单类型、按值拷贝,且默认关闭。
|
||||
|
||||
### 结论 G:不新增围栏元数据;用文档原生的“内核表 / 会话表”
|
||||
|
||||
- 拒绝 ` ```python kernel=分析 `、`name=`、YAML kernel 配置、魔法注释。
|
||||
- 使用既有绑定表 + GFM 表格(放在 `# main` 体内,与 cell 同作用域):
|
||||
- `内核表` / `kernels`
|
||||
- `会话表` / `session`
|
||||
- 表格是**声明**,不是自动执行;只有 Run / Step 触发。
|
||||
- 解析器不变,核心表面零增长;view/session 读取这两个约定绑定。
|
||||
|
||||
理由:`kernel=` 是 IDE 配置思维,破坏“代码即文档”;绑定表是文档目录/执行计划,人可读、机器可解析,且不把文档拆成多个对象作用域。
|
||||
|
||||
### 结论 H:输出默认临时,writeback 显式;状态不写进 `.mq.md`
|
||||
|
||||
- View cells 的输出默认只在 view 中显示,不修改文档。
|
||||
- 需要持久化时显式 writeback(沿用 `<!-- marqdo-out … -->`),可 Git 跟踪、可忽略。
|
||||
- 执行日志放 `.marqdo/sessions/…`(默认 git 忽略)。
|
||||
- 不把 execution_count / kernel 状态 / base64 输出写进 `.mq.md`。
|
||||
|
||||
### 结论 I:首批会话语言 Python + Node
|
||||
|
||||
- Python:Jupyter 的主场景,优先支持。
|
||||
- Node:v1 已有基础,且当前开发环境可用。
|
||||
- 15 个语言预设继续用于**一次性执行**;R / Julia / Ruby 等的持久会话通过自定义 bootstrap 逐步加入,不阻塞首版。
|
||||
|
||||
### 结论 J:v2 不做“外联回调 Marqdo 函数”
|
||||
|
||||
- 状态/值双向:✅
|
||||
- Marqdo 代码作为源码文本传给外联:✅(外联按自己的语言执行)
|
||||
- 外联代码调用 Marqdo `##` 函数:❌ v2;后续做 callback RPC(控制通道 + 重入 + 死锁处理)。
|
||||
- 原因:重入解释器、线程安全、死锁、安全面都远超首版范围;先把数据/状态桥做稳。
|
||||
|
||||
### 结论 K:安全与测试是一等公民
|
||||
|
||||
- 所有 spawn / probe / session 入口检查 `allow_exec`。
|
||||
- 进程组超时清理;有界 IO;stdin 写线程;输出上限;并发上限。
|
||||
- 每文档生命周期,关闭即 kill;跨文档不共享。
|
||||
- 测试:node + bash 为最小环境主路径;python 条件覆盖;单元测试覆盖切分/模板/JSON;金样例覆盖记录/超时/会话/并行/状态桥。
|
||||
|
||||
---
|
||||
|
||||
## 2. 逐问逐答(保留原始讨论颗粒度)
|
||||
|
||||
### Q1:外联库是做什么的?
|
||||
|
||||
**答**:它是文档的多语言执行总线,负责:
|
||||
|
||||
1. 内核生命周期(启动/重启/中断/关闭/切换);
|
||||
2. cell 执行(源码 → kernel → stdout/stderr/result);
|
||||
3. 状态持久化(同一 kernel 的 cell 共享命名空间);
|
||||
4. 类型桥(Marqdo Value ↔ JSON ↔ 语言对象);
|
||||
5. 环境发现与配置(probe/register/venv/config);
|
||||
6. 记录与安全(耗时、退出码、截断、cap、清理)。
|
||||
|
||||
它不负责:文档语法(Language)、UI 布局(Document)、知识目录(Catalog)。这些由相邻层提供。
|
||||
|
||||
### Q2:是否支持外联库共享状态?
|
||||
|
||||
**答**:支持,但严格分层:
|
||||
|
||||
- 同一 kernel:共享全局变量。
|
||||
- 同一语言不同 kernel:隔离。
|
||||
- 不同语言:不共享内存,只能显式传值。
|
||||
- Marqdo ↔ kernel:显式桥。
|
||||
- 跨文档:默认隔离。
|
||||
|
||||
### Q3:能否单步执行?
|
||||
|
||||
**答**:能,但要定义清楚:
|
||||
|
||||
- cell step:v2 做。
|
||||
- Marqdo statement step:现有 debugger 已有,v2 接入 view。
|
||||
- foreign line step:v2 不做;后续 DAP。
|
||||
|
||||
### Q4:能否切换哪几个外联库共享状态?
|
||||
|
||||
**答**:能,用命名内核:
|
||||
|
||||
- `py:分析` 下所有 cell 共享;
|
||||
- `py:绘图` 隔离;
|
||||
- 每个 cell 有 kernel 归属;
|
||||
- 切换归属不迁移状态,需要重跑;
|
||||
- 跨语言用显式桥。
|
||||
|
||||
### Q5:Marqdo 的代码/状态能否被外联使用?外联的状态/变量能否被 Marqdo 使用?
|
||||
|
||||
**答**:
|
||||
|
||||
- Marqdo 值 → 外联:`session_set` / `call input` / `session_eval input`;JSON 拷贝。
|
||||
- 外联值 → Marqdo:`session_get` / `call` 返回值;赋值。
|
||||
- Marqdo 代码 → 外联:作为源码文本传递;外联按自己的语言执行,不是 Marqdo 语义。
|
||||
- 外联代码 → Marqdo 函数:v2 不做,后续 callback RPC。
|
||||
- 自动镜像:v2 不做,后续可选。
|
||||
|
||||
### Q6:如何超越 Jupyter?
|
||||
|
||||
**答**:不是“功能更多”,而是把 Jupyter 的隐藏面变成显式面:
|
||||
|
||||
| Jupyter | Marqdo |
|
||||
|---|---|
|
||||
| `.ipynb` JSON 混入输出/execution_count | `.mq.md` 源码干净;输出可选 writeback |
|
||||
| 隐藏 kernel 状态 | 内核 + 文档会话 + 状态面板 + journal |
|
||||
| 一个 notebook 一个 kernel | 命名内核 + 每 cell 归属 + 显式桥 |
|
||||
| 只有 cell step | cell step + statement step |
|
||||
| 手动 Run All | restart & run all + dirty/stale + replay |
|
||||
| 无知识目录 | OKF / catalog;cell 是可发现知识单元 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 被拒绝的方案
|
||||
|
||||
| 方案 | 为什么拒绝 |
|
||||
|---|---|
|
||||
| 围栏元数据 ` ```python kernel=分析 ` | Language 层变更;需 ADR;把文档语法变成 IDE 配置;破坏可读性 |
|
||||
| YAML `kernels:` 配置 | 代码思维;与“文档即知识”冲突;表格已能表达 |
|
||||
| 魔法 HTML 注释 `<!-- kernel: 分析 -->` | 不可见、易漂移、读者不可见;违背可读性 |
|
||||
| 自然语言 prose 解析(“把 xs 送给分析内核”) | 非确定性;误触发;违背“叙述默认安全” |
|
||||
| 隐式自动镜像变量 | 命名冲突、Secret 泄漏、类型丢失、不可复现 |
|
||||
| 一个文档一个 kernel | 无法做多语言/隔离实验,正是 Jupyter 的局限 |
|
||||
| 把状态/输出写进 `.mq.md` | Git 噪声;正是要解决的 Jupyter 问题 |
|
||||
| cell 自动执行 | 违背“未标记即叙述/未调用即数据”;破坏安全默认 |
|
||||
| v2 做 foreign→Marqdo callback | 重入/死锁/安全复杂;应先稳定数据桥 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 已锁定的实现边界
|
||||
|
||||
### v2 必做
|
||||
|
||||
- F0 安全执行内核 + `invoke` 记录 + `exec` 门禁 + 有界 IO + 进程组超时。
|
||||
- F1 语言注册/发现:15 预设、`probe`、`register`、`unset`、配置、venv。
|
||||
- F2 JSON 桥:`call` / `run_many` / `output` / `result`。
|
||||
- F3 持久内核:Python / Node `session_open/eval/close/list`。
|
||||
- F3.5 状态桥:`session_set/get/names`。
|
||||
- D1 文档会话服务端:cell index、kernel registry、journal、open/close。
|
||||
- D2 view notebook:内核选择、Run/Step/Run All/Restart、状态面板、dirty/stale。
|
||||
- D3 Marqdo statement step 接入 view。
|
||||
- D4 语法:`内核表` / `会话表` 解析与校验。
|
||||
- D5 测试、文档、catalog、CHANGELOG。
|
||||
|
||||
### v2 不做(明确记录,避免“降级”误解)
|
||||
|
||||
- Foreign line-level step(接 DAP 是后续项目)。
|
||||
- Foreign → Marqdo 函数 callback。
|
||||
- 跨语言共享对象引用 / 共享内存。
|
||||
- 全进程快照(只做变量级 JSON 快照)。
|
||||
- 跨文档全局内核。
|
||||
- 自动安装依赖。
|
||||
- 浏览器 wasm 外联。
|
||||
|
||||
这些不是“砍掉”,而是**独立阶段**;v2 先把内核/会话/桥做稳。
|
||||
|
||||
---
|
||||
|
||||
## 5. 风险与对策
|
||||
|
||||
| 风险 | 对策 |
|
||||
|---|---|
|
||||
| 会话协议脆弱(原生 fd 输出、缓冲) | bootstrap 用原始 stdout;Python `-u`;Node 保存原始 write;超时 kill;文档标注限制 |
|
||||
| 状态桥隐式化导致不可复现 | 默认显式;`mirror` 后续且默认关 |
|
||||
| 多内核进程泄漏 | 每文档生命周期;Drop kill;进程组;session_close;测试 |
|
||||
| 大对象 JSON 拷贝慢 | v2 明确拷贝语义;后续 Arrow/Parquet/文件句柄 |
|
||||
| `内核表` / `会话表` 名称冲突 | 文档声明为保留绑定名;后续可用 frontmatter 指针重命名 |
|
||||
| 表格行/单元不一致 | 明确诊断:未声明内核、重复单元、语言不匹配、未入会话 |
|
||||
| 交互执行顺序混乱 | journal + dirty/stale + Run All canonical + 执行序号 |
|
||||
| 安全(Secret/环境) | Secret 不进 JSON;env 显式交付;状态面板打码;exec cap |
|
||||
| 测试环境无 Python | node/bash 主路径;python 条件测试;协议单测 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 术语表(统一中英文)
|
||||
|
||||
| 中文 | English | 含义 |
|
||||
|---|---|---|
|
||||
| 外联内核 | foreign kernel | 外部语言进程 |
|
||||
| 外联会话 | foreign session | 内核实例 + 命名空间 |
|
||||
| 文档会话 | document session | Marqdo 状态 + 内核注册表 + journal |
|
||||
| 代码单元 | cell | 绑定名的代码围栏 |
|
||||
| 内核归属 | kernel assignment | cell → kernel |
|
||||
| 状态桥 | state bridge | Marqdo 值 ↔ 内核变量 |
|
||||
| 执行日志 | execution journal | 执行顺序/耗时/结果/hash |
|
||||
| 新鲜 | clean | 源码未变且已成功执行 |
|
||||
| 过期 | dirty | 源码变了,结果可能过期 |
|
||||
| 失效 | stale | 上游依赖变了,需要重跑 |
|
||||
| 规范执行 | canonical run | 重启后按会话表顺序 Run All |
|
||||
|
||||
---
|
||||
|
||||
## 7. 决策时间线
|
||||
|
||||
1. 用户提出外联库对标 Jupyter、共享状态、单步、切换、双向使用。
|
||||
2. Agent 阅读 `src/host/foreign.rs`、`src/view`、`src/debug`、`src/host/subtask.rs`、`lib/foreign`、设计文档。
|
||||
3. Agent 回答:需要 F + D 两层;单步分三种;共享分三层;显式桥。
|
||||
4. 用户授权 Agent 拍板:安全、最强、不降级、充分测试、文档先行、提交推送后开发。
|
||||
5. Agent 锁定本文件 §1 的 A–K 结论,进入文档编写与实现。
|
||||
|
||||
---
|
||||
|
||||
## 8. 后续变更流程
|
||||
|
||||
- 任何与本文冲突的实现,先改本文并写明「变更理由 / 影响 / 迁移」。
|
||||
- 新增核心语法(任何新标记)必须走 `doc/adr/` + `core-surface.md`;本文所有语法均为既有标记的组合。
|
||||
- 新增会话语言、跨语言数据平面、callback RPC,各自开独立设计文档,不塞进本文件。
|
||||
@@ -0,0 +1,78 @@
|
||||
# Marqdo AI 栈统一开发方案(llm + agent)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** |
|
||||
| Date | 2026-09-24 |
|
||||
| Source | [doc/next/002–005](../next/) · [ext-llm.md](../design/ext-llm.md) · [ext-agent.md](../design/ext-agent.md) |
|
||||
|
||||
## 1. 一句话
|
||||
|
||||
> **Document → Prompt → LLM → Agent → Skill → Policy → Executable Knowledge**
|
||||
|
||||
大模型负责探索,小模型(`router_model` / 任意 llm 句柄)负责决策,Marqdo 负责执行;经验编译进 `.mq.md` 后推理成本下降。
|
||||
|
||||
## 2. 分层(勿混)
|
||||
|
||||
| 层 | 职责 | 落点 |
|
||||
|----|------|------|
|
||||
| **Intelligence primitive** | `ask` / `stream` / `collect`;结果对象 | `ext/ai/llm` |
|
||||
| **Agent runtime** | `run` / `step` / `plan` / `route` | `ext/ai/agent` |
|
||||
| **Sandbox (trial)** | CoW workspace + capped `run` | `ext/ai/sandbox` · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
| **Memory / compile** | episode → skill → policy | `plugins/agent`(ABI;**不进** `src/host`) |
|
||||
| **Transport** | HTTP / SSE / provider | `ext/ai/llm/openai` · `ollama`;用户不可见 |
|
||||
|
||||
硬规则:`ext/**` 不调 `host_*`;agent/OKF/路由热路径只进 `plugins/agent`。
|
||||
|
||||
## 3. LLM(005)— 已/待
|
||||
|
||||
| 项 | 状态 |
|
||||
|----|------|
|
||||
| 语义 API:`ask` / `stream` / `collect`(`complete` 降为兼容原语) | **done** |
|
||||
| `create` 工厂;handle 带 `backend` | **done** |
|
||||
| LLMResult:`text` / `model` / `finish` / `backend` / `usage` / `tokens` | **done** |
|
||||
| Named models(`llm.fast` / `llm.reasoning`) | **done** |
|
||||
| Prompt document:`prompt` / `prompt_load` + `type: prompt` 正文 | **done**(无参 `ask`/`stream` → `sys.module_source` + `prompt_body`) |
|
||||
| 拆 `ext/ai/llm/openai.mq.md` + `ollama` 后端 | **done** |
|
||||
| tool_calls 完整 Result | **done**(`openai.tool_calls_from` + `LLMResult.tool_calls`;`llm-tool-calls-offline`) |
|
||||
| Transport → 可选 ABI 插件 (`plugins/llm`) | **done** |
|
||||
| Artifact Metadata Binding(`${env.*}` / `secret` · `sys.meta`) | **done**(Phase 1 Metadata-only + Phase 2 scope lift;[binding.md](../design/binding.md)) |
|
||||
|
||||
作者面优先:
|
||||
|
||||
```marqdo
|
||||
**answer = > llm.ask prompt="What is Marqdo?"**
|
||||
**events = > model.stream prompt=`p`**
|
||||
**text = > llm.collect events=`events`**
|
||||
**fast = > llm.fast**
|
||||
**prompt = > llm.prompt path="prompts/task.md"**
|
||||
```
|
||||
|
||||
## 4. Agent(002–004)— 已/待
|
||||
|
||||
| 项 | 状态 |
|
||||
|----|------|
|
||||
| Skill Compilation:episode → maybe_learn → `llm_free` | **done** |
|
||||
| Adaptive Routing:`marqdo` \| `small-llm` \| `llm` \| `auto`(`jev`→`small-llm` 别名) | **done** |
|
||||
| Policy Compilation → `policies/router.mq.md` | **done** |
|
||||
| `run` 串联 route → execute → record → learn | **done** |
|
||||
| Agent 默认走 `model.ask` + Result.usage 记成本 | **done**(`model_turn`) |
|
||||
| Prompt artifact / document-as-prompt | **done**(经 llm `path=` / `prompt`) |
|
||||
| 零 LLM 执行(policy+skill → `llm_calls=0`) | **done** |
|
||||
| `plan` 不覆盖已有 `llm_free` resource | **done** |
|
||||
| 真 MCP client(stdio) / resume checkpoint / 小模型路由请求面 | **done**(live 路由仍可选 skip) |
|
||||
|
||||
## 5. 联调顺序
|
||||
|
||||
1. **LLM Result → Agent metrics** — **done**
|
||||
2. **Named handles** — **done**
|
||||
3. **Prompt document** — **done**(`type: prompt` 剥 frontmatter;无参 `ask`/`stream` 经 `sys.module_source`)
|
||||
4. **Backend split** — **done**
|
||||
5. **Execution compilation** — **done**(`agent-zero-llm` 金样 + harness)
|
||||
6. **Metadata Binding** — **done**(Phase 1 + Phase 2 scope lift;`llm-meta-offline` · `meta-lift`)
|
||||
|
||||
## 6. 验收金样
|
||||
|
||||
- Agent:`tests/ext/agent-v2-learn.mq.md` · `agent-p4-route.mq.md` · `agent-zero-llm.mq.md` · `agent-plan-preserve.mq.md` · `agent-mcp-client.mq.md` · `agent-resume.mq.md` · `agent-small-llm-route.mq.md` · `scripts/agent-harness.sh`
|
||||
- LLM:`tests/ext/llm-ask-offline.mq.md` · `llm-stream-offline.mq.md` · `llm-ctor-offline.mq.md` · `llm-named-offline.mq.md` · `llm-meta-offline.mq.md` · `llm-entry-prompt-offline.mq.md` · `llm-tool-calls-offline.mq.md`
|
||||
- Binding:`tests/structure/meta-binding.mq.md` · `meta-lift.mq.md`
|
||||
@@ -0,0 +1,34 @@
|
||||
# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— 2026-09-23
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 模型 | `deepseek-flash` @ `https://llm.cflmy.cn/v1` |
|
||||
| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |
|
||||
| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |
|
||||
| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |
|
||||
|
||||
## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)
|
||||
|
||||
| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| query | 0/3 | 0/3 | 2/3 | 1/3 | 0.00 | 69771(42478+27293) | 3 |
|
||||
| docs | 3/6 | 4/6 | 2/6 | 0/6 | 0.50 | 57276(33346+23930) | 0 |
|
||||
|
||||
## 逐例
|
||||
|
||||
| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| claims_reserve_settle | query | load-fail | 0 | 是 | 否 | 11987+8177 | 3 | {"error":{"code":"mlsp.parse_error","message":"<memory>: trailing input in expression: \"(claim - deductible, 0)\""},"id":1,"ok":false} \| stderr=error: /tmp/marqdo_blind_1694593_query_claims_reserve_settle.mq.md: trailing input in expression: "(claim - deductible, 0)" |
|
||||
| contract_milestone_pay | query | infra | 0 | 否 | 否 | 3970+4718 | 3 | 非 JSON / 空体: |
|
||||
| vendor_po_gate | query | load-fail | 0 | 是 | 否 | 9552+3686 | 3 | 回复中无程序 \| 开头: QUERY: 条件分支 写法 |
|
||||
| qb_gcd | query | run-fail | 0 | 否 | 是 | 9700+8488 | 3 | \| stderr=error: /tmp/marqdo_blind_1694593_query_qb_gcd.mq.md:26:1: unknown function `gcd(48` |
|
||||
| qb_max_sublist_sum | query | infra | 0 | 否 | 否 | 1253+134 | 3 | 非 JSON / 空体: |
|
||||
| qb_get_factors | query | infra | 0 | 否 | 否 | 6016+2090 | 3 | 非 JSON / 空体: |
|
||||
| claims_reserve_settle | docs | pass | 0 | 否 | 否 | 2699+2987 | 0 | queries=0 |
|
||||
| contract_milestone_pay | docs | pass | 0 | 否 | 否 | 2800+3202 | 0 | queries=0 |
|
||||
| vendor_po_gate | docs | pass | 0 | 否 | 否 | 2690+1264 | 0 | queries=0 |
|
||||
| qb_gcd | docs | pass | 2 | 否 | 否 | 8147+6970 | 0 | queries=0 |
|
||||
| qb_max_sublist_sum | docs | run-fail | 0 | 是 | 否 | 8518+3609 | 0 | \| stderr=error: /tmp/marqdo_blind_1694593_docs_qb_max_sublist_sum.mq.md:3:1: unknown function `[-2,` |
|
||||
| qb_get_factors | docs | run-fail | 0 | 是 | 否 | 8492+5898 | 0 | \| stderr=error: /tmp/marqdo_blind_1694593_docs_qb_get_factors.mq.md:20:1: missing argument for parameter `value` |
|
||||
|
||||
报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。
|
||||
@@ -0,0 +1,34 @@
|
||||
# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— 2026-09-23
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 模型 | `mimo-v2.6-pro` @ `https://llm.cflmy.cn/v1` |
|
||||
| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |
|
||||
| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |
|
||||
| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |
|
||||
|
||||
## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)
|
||||
|
||||
| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| query | 0/1 | 0/1 | 1/1 | 0/1 | 0.00 | 12428(10255+2173) | 5 |
|
||||
| docs | 0/0 | 0/0 | 0/0 | 0/0 | 0.00 | 0(0+0) | 6 |
|
||||
|
||||
## 逐例
|
||||
|
||||
| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| claims_reserve_settle | query | infra | 0 | 否 | 否 | 1424+324 | 3 | 非 JSON / 空体: |
|
||||
| contract_milestone_pay | query | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| vendor_po_gate | query | infra | 0 | 否 | 否 | 1417+213 | 3 | 非 JSON / 空体: |
|
||||
| qb_gcd | query | load-fail | 0 | 是 | 否 | 5011+1265 | 0 | {"error":{"code":"mlsp.parse_error","message":"<memory>: unexpected expression input: \"**y**\""},"id":1,"ok":false} \| stderr=error: /tmp/marqdo_blind_1710203_query_qb_gcd.mq.md: unexpected expression input: "**y**" |
|
||||
| qb_max_sublist_sum | query | infra | 0 | 否 | 否 | 1216+172 | 3 | 非 JSON / 空体: |
|
||||
| qb_get_factors | query | infra | 0 | 否 | 否 | 1187+199 | 3 | 非 JSON / 空体: |
|
||||
| claims_reserve_settle | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| contract_milestone_pay | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| vendor_po_gate | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| qb_gcd | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| qb_max_sublist_sum | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| qb_get_factors | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: {"error":{"message":"upstream connection failed","type":"server_error","param":n… |
|
||||
|
||||
报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。
|
||||
@@ -7,6 +7,7 @@
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.md)** |
|
||||
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
|
||||
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
|
||||
| 后续 | 优化波次 O1–O5 见 [ext-ai-optimize.md](ext-ai-optimize.md)(沙盒证明 · Skill Lift · 路由/成本 · lint · 隔离) |
|
||||
|
||||
---
|
||||
|
||||
@@ -39,6 +40,12 @@
|
||||
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** |
|
||||
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) |
|
||||
| **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** |
|
||||
| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 |
|
||||
| **B1.5** | **Skill Compilation v2(Phase 1–3)**:episode → maybe_learn → compile → `llm_free`;`agent.run` / `resolve` / `metrics`;ABI 在 `plugins/agent`(`memory.rs`);金样 `agent-v2-learn` | **done** |
|
||||
| **B1.6 / P4** | **Adaptive Routing**(原 Jev Router 更名):`route` backends = `marqdo` \| `small-llm` \| `jev?` \| `llm` \| `auto`;Policy Compilation → `policies/router.mq.md`;金样 `agent-p4-route`;设计 [004.md](../next/004.md) | **done** |
|
||||
| **L0** | **LLM semantic surface(005)**:`ask` / `stream` / `collect` / `create`;`complete` 降为兼容;统一方案 [ai-stack.md](ai-stack.md) | **done** |
|
||||
| **B2** | 真 MCP stdio client(`agent_mcp_client` + fixture 仍作离线证据) | **done** |
|
||||
| **B3** | resume checkpoint(`.marqdo/agent-resume/`;HITL view 仍暂缓) | **done**(HITL 暂缓) |
|
||||
| **B4–B5** | stats / 并行;小模型 live 路由金样(无 key skip) | 部分 |
|
||||
| — | LLM named models / prompt-document | **done** |
|
||||
|
||||
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。
|
||||
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。v2 设计:[doc/next/002.md](../next/002.md) · [doc/next/003.md](../next/003.md) · P4:[doc/next/004.md](../next/004.md) · LLM:[doc/next/005.md](../next/005.md)。
|
||||
@@ -0,0 +1,29 @@
|
||||
# Roadmap: Agent/LLM 优化波次 O1–O5
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** |
|
||||
| Date | 2026-10-16 |
|
||||
| Design | [ext-ai-optimize.md](../design/ext-ai-optimize.md) |
|
||||
| Research | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
|
||||
| Prior | [ext-agent-optimize.md](ext-agent-optimize.md) (A0–A4 / Wave B) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
|
||||
## Principles
|
||||
|
||||
1. Executable `.mq.md` remains authority; OKF reuses; sandbox proves; LLM explores.
|
||||
2. No hidden TOOL: loop; no vector-store memory authority; no default shell Agent.
|
||||
3. Do not edit `doc/next/*`.
|
||||
|
||||
## Waves
|
||||
|
||||
| Wave | Scope | Gold / deliverable | Status |
|
||||
|------|-------|--------------------|--------|
|
||||
| **O1** | A1 opt-in `sandbox=` · A3 profile table · D1 skill · D4 example | `agent-sandbox-optin` · `examples/agent-sandbox-okf` | **done** |
|
||||
| **O2** | A2 promote proof · B1 OKF meta · B3/E1 harness Skill Lift | `agent-sandbox-promote` · harness subset | **done** |
|
||||
| **O3** | C1 step route · C2 cost · B6 EFI default | `agent-step-route` · run usage/efi | **done** |
|
||||
| **O4** | A4/D2 lint · A5 diff review report | `scripts/mq-style-lint.sh` · `sandbox.report` | **done** |
|
||||
| **O5** | B4 quarantine · C3 offline policy rewrite | `agent-sandbox-quarantine` · `optimize-standing-policy.sh` | **done** |
|
||||
|
||||
## Non-goals
|
||||
|
||||
F1–F5 · wasmtime CLI embed · default `sandbox=True` without ADR · edit `doc/next/*`
|
||||
@@ -0,0 +1,28 @@
|
||||
# Roadmap: `ext/ai/sandbox` (AI CoW trial runtime)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** |
|
||||
| Date | 2026-10-16 |
|
||||
| Design | [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
|
||||
| Research | [ai-agent-sandbox.md](../research/ai-agent-sandbox.md) |
|
||||
|
||||
## Milestones
|
||||
|
||||
| ID | Deliverable | Done when |
|
||||
|----|-------------|-----------|
|
||||
| S0 | Design + this roadmap + research cross-links | **done** |
|
||||
| S1 | CoW open/write/read/remove/diff/commit/discard | **done** (`sandbox-cow`) |
|
||||
| S2 | `run` + default caps + core lib inside run | **done** (`sandbox-run-lib`) |
|
||||
| S3 | `inspect` + deny plugin.load | **done** (`sandbox-deny`) |
|
||||
| S4 | Polish: ai-stack + CHANGELOG | **done** |
|
||||
|
||||
## Gold samples (target)
|
||||
|
||||
- `tests/ext/sandbox-cow.mq.md`
|
||||
- `tests/ext/sandbox-run-lib.mq.md`
|
||||
- `tests/ext/sandbox-deny.mq.md`
|
||||
|
||||
## Out of scope this wave
|
||||
|
||||
wasmtime CLI embed · Wasm ABI plugins · bwrap/microVM · full web in sandbox · auto-wire agent.step · edit `doc/next/*`
|
||||
@@ -0,0 +1,226 @@
|
||||
# 外联内核 v2 路线图(F0–F4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **F0–F3.5 已落地;F4 进行中** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime |
|
||||
| 相关 | [foreign-kernel.md](../design/foreign-kernel.md) · [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [stdlib-foreign.md](../design/stdlib-foreign.md) · [notebook-session.md](notebook-session.md)(D 层路线) |
|
||||
| 核心表面 Δ | 无 |
|
||||
|
||||
> 本路线图只覆盖 **F:外联内核运行时**。共享状态 / 单步 / 切换内核的文档侧在 [notebook-session.md](notebook-session.md)(D 层)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 现状与目标
|
||||
|
||||
v1:`set_cmd` / `run` / `run_lang` / `langs`;临时文件 + 子进程 + stdout 文本;无状态、无结构化结果、无 exec 门禁、无有界 IO、无进程组清理。
|
||||
|
||||
v2 目标:安全、可发现、结构化、可持久、可并行,并成为 D 层文档会话的可靠底座。
|
||||
|
||||
---
|
||||
|
||||
## 1. 阶段总览
|
||||
|
||||
| 阶段 | 内容 | 估算 | 可独立发版 |
|
||||
|---|---|---|---|
|
||||
| **F0** | 执行内核与安全:Job/Execution、`exec` 门禁、有界 IO、进程组、`invoke` 记录、view 诊断 | 2–3 天 | 是 |
|
||||
| **F1** | 语言注册与发现:registry、15 预设、probe、register/unset、配置、venv | 2–3 天 | 是 |
|
||||
| **F2** | JSON 桥与并行:call/call_many、run_many、output/result | 2–3 天 | 是 |
|
||||
| **F3** | 持久内核:Python/Node session_open/eval/close/list | 3–4 天 | 是 |
|
||||
| **F3.5** | 状态桥:session_set/get/names | 1–2 天 | 是 |
|
||||
| **F4** | 打磨、文档、catalog、CHANGELOG、1.5.0 | 1–2 天 | 1.5.0 |
|
||||
|
||||
D 层(文档会话)从 F3.5 完成后开始;不要把 D 层塞进 F 层。
|
||||
|
||||
---
|
||||
|
||||
## 2. F0 — 执行内核与安全
|
||||
|
||||
### 内容
|
||||
|
||||
- `src/host/foreign.rs` 重构:
|
||||
- `Job`:lang/source/stdin/input/env/cwd/timeout/args/output/max_output/cmd/keep。
|
||||
- `Execution`:stdout/stderr/raw bytes/exit/ms/timed_out/truncated/error。
|
||||
- `ForeignEnv`:cwd/fs_root/specs/caps 快照(供并行)。
|
||||
- `exec` 门禁:`run` / `invoke` / `run_many` / `probe` / `session_*` 统一检查。
|
||||
- 有界 IO:读线程保留前 N 字节、继续排空;`truncated`。
|
||||
- stdin 写线程;EPIPE 忽略。
|
||||
- 超时:进程组 kill(Unix `process_group(0)` + `kill(-pid)`;Windows `taskkill /T /F`)。
|
||||
- shell-like argv 切分(引号/转义)。
|
||||
- `invoke` + 稳定记录。
|
||||
- `run` / `run_lang` 增加 `env` / `cwd` / `timeout` / `args` / `max_output`。
|
||||
- view `/api/foreign-run` 返回完整记录;JS 显示 stderr / exit / ms。
|
||||
- `set_cmd` L1 补 `args`。
|
||||
|
||||
### 验收
|
||||
|
||||
- 既有 `lib_foreign_*` / `lib_subtask_foreign` 绿(python 可用时)。
|
||||
- 新增 node/bash 金样例:非 0 退出、stderr、超时、env/cwd、截断。
|
||||
- `exec=false` 拒绝。
|
||||
- `cargo test` 绿;release build;wasm check。
|
||||
|
||||
### 主要文件
|
||||
|
||||
`src/host/foreign.rs` · `src/host/mod.rs` · `src/host/subtask.rs` · `src/view/mod.rs` · `src/view/html.rs` · `src/view/debug_page.rs` · `Cargo.toml` · `tests/gold.rs` · `tests/lib/foreign-*.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. F1 — 语言注册与发现
|
||||
|
||||
### 内容
|
||||
|
||||
- `src/foreign/registry.rs`(纯逻辑):
|
||||
- 15 预设、别名、扩展名、版本参数、会话能力。
|
||||
- 模板占位符 `{file}` / `{dir}` / `{base}` / `{inline}` / `{lang}` / `{cwd}`。
|
||||
- venv 探测、PATH 查找、shell-like 切分、配置解析。
|
||||
- `HostContext`:
|
||||
- `foreign_specs`、`foreign_config_loaded`。
|
||||
- `probe` 缓存(可选)。
|
||||
- API:`probe` / `langs` / `register` / `unset` / `load_config`。
|
||||
- 配置:`.marqdo/foreign.toml` + `MARQDO_FOREIGN_CONFIG`;优先级见设计。
|
||||
- `MARQDO_FOREIGN_<LANG>` 支持 JSON 数组与引号。
|
||||
- `subtask` 继承注册/配置。
|
||||
|
||||
### 验收
|
||||
|
||||
- `probe` 对 node / bash 给出 path + version;缺失语言 `ok=false` 不 panic。
|
||||
- 配置可把 `python` 指向 venv;模板可跑 `go run`(若本机有 go)。
|
||||
- `langs` 含预设;`unset` 回退预设。
|
||||
- 单元测试:切分、模板、别名、扩展名。
|
||||
|
||||
---
|
||||
|
||||
## 4. F2 — JSON 桥与并行
|
||||
|
||||
### 内容
|
||||
|
||||
- `call` / `call_many`;`invoke` 的 `input` / `output` / `result` / `result_error`。
|
||||
- `Value ↔ JSON` 复用 `host::json`;`bytes` base64。
|
||||
- `run_many` 并行引擎:`ForeignEnv` 快照、线程上限 32、结果同序、单项 panic 隔离。
|
||||
- `call_many` 全跑完再报错(清理所有子进程)。
|
||||
- 文档:Python / Node JSON 样板。
|
||||
|
||||
### 验收
|
||||
|
||||
- `call` 单列表 → map,mean 为 Num;嵌套 list/map 往返。
|
||||
- `run_many` 顺序稳定;单项失败不影响其它项。
|
||||
- 大输入(>8 KiB)走 `MARQDO_INPUT_FILE`。
|
||||
- 并发上限与超时生效。
|
||||
|
||||
---
|
||||
|
||||
## 5. F3 — 持久内核
|
||||
|
||||
### 内容
|
||||
|
||||
- `src/host/foreign_session.rs`:
|
||||
- Python / Node bootstrap(嵌入式常量)。
|
||||
- 启动、reader/writer、严格串行、超时、崩溃、drop 清理。
|
||||
- `session_open` / `session_eval` / `session_close` / `session_list`。
|
||||
- 会话记录:与 invoke 同形 + `id` / `alive`。
|
||||
- 会话环境:cwd / env / cmd;`MARQDO_*`。
|
||||
- `HostContext` 字段(cfg exec-host)+ Drop。
|
||||
|
||||
### 验收
|
||||
|
||||
- Node:`let x=41` → `x+1` → 42;`console.log` 捕获;异常不杀会话。
|
||||
- Python:同(有 python 时)。
|
||||
- 超时 → kill + `alive=false`;close/drop 无遗留进程。
|
||||
- 会话与 `subtask` 边界:不继承。
|
||||
|
||||
---
|
||||
|
||||
## 6. F3.5 — 状态桥
|
||||
|
||||
### 内容
|
||||
|
||||
- `session_set` / `session_get` / `session_names`。
|
||||
- 值:Marqdo → JSON → kernel;kernel → JSON → Marqdo。
|
||||
- 名称校验;Secret 规则;错误可读。
|
||||
- 与 `session_eval` 同一线路,严格串行。
|
||||
- L1 文档 + 金样例。
|
||||
|
||||
### 验收
|
||||
|
||||
- Node:`session_set xs=[1,2,3]`,`session_eval sum(xs)` → 6;`session_get` 取回。
|
||||
- 复杂嵌套 map/list 往返。
|
||||
- 不存在变量 → None + 可读诊断。
|
||||
- 非 JSON 可序列化 → 错误说明。
|
||||
|
||||
---
|
||||
|
||||
## 7. F4 — 打磨与发布
|
||||
|
||||
- `history`(可选)/ `cache`(可选,默认关)。
|
||||
- view 命令记忆 / Ctrl+Enter / 错误分块。
|
||||
- `lib/foreign.mq.md` / `lib/外联.mq.md` 全量。
|
||||
- `public/stdlib/*` 示例。
|
||||
- catalog 重新生成;CHANGELOG;版本 1.5.0。
|
||||
- 性能:空跑、100 次调用、会话 vs 一次性。
|
||||
|
||||
### 验收
|
||||
|
||||
- 新函数全部有中文/英文文档与示例。
|
||||
- `marqdo catalog`、`public/` 构建通过。
|
||||
- 手工 view Run 一个 node 卡片,显示 stdout/stderr/exit/ms。
|
||||
|
||||
---
|
||||
|
||||
## 8. 测试矩阵
|
||||
|
||||
> 当前环境:node / bash / sh / perl 可用,python3 不可用。新金样例以 node + bash 为主;python 用 `python_available()` 条件跳过。
|
||||
|
||||
| 测试 | 依赖 | 断言 |
|
||||
|---|---|---|
|
||||
| 既有 3 个 foreign 用例 | python | 兼容 |
|
||||
| `foreign-invoke` | node | 记录字段 |
|
||||
| `foreign-env-cwd` | node | env/cwd/MARQDO_* |
|
||||
| `foreign-timeout` | node | timed_out |
|
||||
| `foreign-call-json` | node | 类型往返 |
|
||||
| `foreign-call-many` / `run-many` | node | 顺序/隔离 |
|
||||
| `foreign-session` | node | 跨 eval |
|
||||
| `foreign-session-set-get` | node | 状态桥 |
|
||||
| `foreign-session-timeout` | node | alive=false |
|
||||
| `foreign-probe` | node | path/version |
|
||||
| `foreign-register` | node | 模板 |
|
||||
| `foreign-config` | node | 配置 |
|
||||
| `foreign-stdout-stderr` | bash | 成功也有 stderr |
|
||||
| `foreign-caps` | 无 | 拒绝 |
|
||||
| 单元测试 | 无 | 切分/模板/别名/JSON |
|
||||
|
||||
Windows:`python_available` / `bash_available` 守卫;进程组 `taskkill` 分支编译通过。
|
||||
|
||||
---
|
||||
|
||||
## 9. 兼容性
|
||||
|
||||
- `run` / `run_lang` / `set_cmd` / `langs` 兼容;只增可选参数。
|
||||
- `run` 成功仍返回 stdout;非 0 仍报错。
|
||||
- 大输出从“报错”改为“截断 + truncated”(更安全;CHANGELOG 写明)。
|
||||
- `langs` 扩展为预设 ∪ 注册 ∪ 配置。
|
||||
- HostFn id 末尾追加(196+)。
|
||||
- 无核心表面 Δ。
|
||||
|
||||
---
|
||||
|
||||
## 10. 风险
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|---|---|
|
||||
| 会话协议脆弱 | 原始 stdout;`-u`;超时 kill;测试;文档限制 |
|
||||
| 并行进程过多 | 默认 4 / 上限 32;超时;输出上限 |
|
||||
| 配置优先级难记 | 设计文档固定表;`probe` 显示实际 path |
|
||||
| 模板 shell 注入 | 默认不 shell;路径引擎生成;文档警示 |
|
||||
| 大输出截断改变 v1 行为 | CHANGELOG;`truncated` 可检测 |
|
||||
| wasm 编译 | 新字段 cfg 隔离;registry 纯逻辑 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 完成定义
|
||||
|
||||
- F0–F3.5 全部验收。
|
||||
- `cargo test` 绿;release build;wasm check。
|
||||
- 文档/CHANGELOG/catalog 更新。
|
||||
- 提交并推送。
|
||||
- 进入 D 层([notebook-session.md](notebook-session.md))。
|
||||
@@ -0,0 +1,177 @@
|
||||
# 文档会话路线图(D0–D5)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 已落地(首版);D4–D5 待做** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime + Document(view 服务端 / 前端) |
|
||||
| 相关 | [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-kernel.md](../design/foreign-kernel.md) · [foreign-v2.md](foreign-v2.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) |
|
||||
| 核心表面 Δ | 无 |
|
||||
|
||||
> F 层让“外部语言能持久运行”;D 层让“文档里的多个 cell 像 notebook 一样共享状态、单步、切换内核”。两层分开验收。
|
||||
|
||||
---
|
||||
|
||||
## 0. 依赖
|
||||
|
||||
- **F3**:Python / Node 持久内核。
|
||||
- **F3.5**:`session_set/get/names`。
|
||||
- 现有 `DebugController`(Marqdo 语句单步)。
|
||||
- 现有 `writeback` / `annot` / view 结构。
|
||||
|
||||
没有 F3/F3.5,D2 只能做一次性 Run,不是共享状态。
|
||||
|
||||
---
|
||||
|
||||
## 1. 阶段总览
|
||||
|
||||
| 阶段 | 内容 | 估算 |
|
||||
|---|---|---|
|
||||
| **D0** | 设计/语法/决策文档 | 已完成 |
|
||||
| **D1** | `src/notebook/`:cell index、表解析、session 结构、诊断 | 2–3 天 |
|
||||
| **D2** | 服务端 API:open/close/cell run/step/run_all/restart/interrupt | 3–4 天 |
|
||||
| **D3** | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal | 3–4 天 |
|
||||
| **D4** | statement step、dirty/stale、writeback | 2–3 天 |
|
||||
| **D5** | replay、持久化、并发优化、测试补全、发布 | 2–3 天 |
|
||||
|
||||
---
|
||||
|
||||
## 2. D1 — Cell index 与表解析
|
||||
|
||||
### 内容
|
||||
|
||||
- 新模块 `src/notebook/`:
|
||||
- `cell.rs`:从 AST 提取绑定名代码围栏;id/name/lang/line/source hash。
|
||||
- `syntax.rs`:读取 `内核表` / `会话表`;中英列名。
|
||||
- `session.rs`:`DocumentSession` 结构、kernel registry、value store、journal。
|
||||
- `diag.rs`:重复/未知/语言不匹配/未入会话诊断。
|
||||
- 自动模式:无表 → 文档顺序 + 默认内核。
|
||||
- 解析器不改;只遍历 `Module.functions` + `Stmt::Assign { value: Expr::Code }`。
|
||||
- 测试:单元 + `tests/notebook/*.mq.md`。
|
||||
|
||||
### 验收
|
||||
|
||||
- 两个 Python cell + 一个会话表 → cells 顺序、kernel 归属正确。
|
||||
- 无表 → 自动顺序。
|
||||
- 未知内核/未知单元/重复/语言不匹配 → 可读诊断。
|
||||
- 未绑定围栏不进入 cell index。
|
||||
|
||||
---
|
||||
|
||||
## 3. D2 — 服务端 API
|
||||
|
||||
### 内容
|
||||
|
||||
- `src/view/notebook_api.rs`(或 `view/session_api.rs`):
|
||||
- open / close / reload
|
||||
- cell run / step / run_all
|
||||
- kernel restart / interrupt / assign
|
||||
- state list / push / pull
|
||||
- journal
|
||||
- Session 存储:`OnceLock<Mutex<HashMap<String, Arc<DocumentSession>>>>`(类似 debug sessions)。
|
||||
- 每个文档一个 session;key = 相对路径。
|
||||
- 执行线程:cell 执行不阻塞 HTTP;响应返回记录;SSE/EventBus 可选。
|
||||
- 错误统一 JSON。
|
||||
|
||||
### 验收
|
||||
|
||||
- open 返回 cells/kernels/journal。
|
||||
- cell run:never→running→clean/error;状态更新。
|
||||
- step:按会话顺序执行下一个。
|
||||
- run_all:按顺序;restart 选项。
|
||||
- 同 kernel 串行;不同 kernel 可并行。
|
||||
- close/drop kill 所有 kernel。
|
||||
- API 单测/集成测试。
|
||||
|
||||
---
|
||||
|
||||
## 4. D3 — View UI
|
||||
|
||||
### 内容
|
||||
|
||||
- 工具栏:Run All / Restart & Run All / Step Cell / Step Statement / Kernel 状态 / Restart / Interrupt / State / Journal。
|
||||
- Code card:
|
||||
- 状态徽标(never/clean/dirty/stale/error/running/unlisted)
|
||||
- kernel 下拉
|
||||
- Run / Step
|
||||
- 输出区(stdout/stderr/result/truncated)
|
||||
- 执行序号 / 耗时
|
||||
- 状态面板:
|
||||
- Marqdo 值 / kernel 变量分栏
|
||||
- Push / Pull / Refresh
|
||||
- Secret 打码、大对象摘要
|
||||
- Journal 面板:表格 + 跳转 + 导出。
|
||||
- 键盘:Ctrl/Cmd+Enter、Shift+Enter、F5、F10。
|
||||
- 静态导出的 Run 仍隐藏。
|
||||
|
||||
### 验收
|
||||
|
||||
- 手工冒烟:两个 Python cell 共享 `x`;切换 kernel 后隔离;Restart 清状态。
|
||||
- 状态面板 Push/Pull。
|
||||
- 错误 cell 红色徽标 + stderr。
|
||||
- 页面刷新后 session 仍在(服务端内存)。
|
||||
|
||||
---
|
||||
|
||||
## 5. D4 — Statement step / dirty / writeback
|
||||
|
||||
### 内容
|
||||
|
||||
- Statement step:复用 `DebugController`,与 DocumentSession 关联;暂停点显示变量。
|
||||
- dirty:reload 后 source hash 变化。
|
||||
- stale:按会话顺序,上游变更 → 下游 stale(v2 近似)。
|
||||
- writeback:单 cell / 全部;`<!-- marqdo-out -->`;不自动。
|
||||
- 运行历史 / 执行序号。
|
||||
|
||||
### 验收
|
||||
|
||||
- Statement step 在 view 中可用;外联调用原子完成。
|
||||
- 编辑 cell → dirty;Run All 后 clean。
|
||||
- 上游变更 → 下游 stale。
|
||||
- 显式 writeback 写入文档;不自动改文件。
|
||||
|
||||
---
|
||||
|
||||
## 6. D5 — Replay / 持久化 / 发布
|
||||
|
||||
### 内容
|
||||
|
||||
- Journal replay:新 kernel,按 journal 顺序/输入 hash 重放;比较 stdout/result hash;divergence 报告。
|
||||
- 可选持久化 `.marqdo/sessions/<doc-hash>.json`(kernel/cell 归属/journal/value store 摘要;默认 git 忽略)。
|
||||
- 并发优化:不同 kernel 并行;同 kernel 串行。
|
||||
- 测试补全;文档;catalog;CHANGELOG。
|
||||
- 版本:D 层随 1.5.x。
|
||||
|
||||
### 验收
|
||||
|
||||
- Replay 能复现 clean 会话;dirty 输入给出 divergence。
|
||||
- 关闭/重启服务无进程泄漏。
|
||||
- 文档完整;金样例绿。
|
||||
|
||||
---
|
||||
|
||||
## 7. 测试矩阵
|
||||
|
||||
| 测试 | 断言 |
|
||||
|---|---|
|
||||
| `notebook/kernels.mq.md` | 内核表/会话表解析 |
|
||||
| `notebook/auto-session.mq.md` | 无表自动顺序 |
|
||||
| `notebook/shared-state.mq.md` | 同 kernel 共享变量 |
|
||||
| `notebook/isolated-kernels.mq.md` | 不同 kernel 隔离 |
|
||||
| `notebook/step.mq.md` | cell step 顺序 |
|
||||
| `notebook/state-bridge.mq.md` | Marqdo ↔ kernel 推拉 |
|
||||
| `notebook/dirty.mq.md` | 编辑 → dirty/stale |
|
||||
| `notebook/invalid-*.mq.md` | 诊断 |
|
||||
| API 集成 | open/run/step/run_all/restart/interrupt/close |
|
||||
| 安全 | exec=false、cwd 越界、超时、Secret 打码 |
|
||||
|
||||
依赖 node 为主;python 条件跳过。
|
||||
|
||||
---
|
||||
|
||||
## 8. 完成定义
|
||||
|
||||
- D1–D4 验收;D5 可选(replay/持久化)。
|
||||
- 文档会话与 F 层联调通过。
|
||||
- 手工 view 冒烟:共享状态 / 单步 / 切换 / 状态面板 / journal。
|
||||
- 测试绿;文档更新;提交推送。
|
||||
@@ -0,0 +1,118 @@
|
||||
# P4 验证汇总报告 — 2026-09-23
|
||||
|
||||
> 执行 [perf-validation.md](perf-validation.md)(自设计性能验证协议)的结果汇总。
|
||||
> 覆盖 three-problems.md 三大问题的**验证矩阵**(§5.2 a–e)。逐例明细见各实验原始报告(文末索引)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 协议 | [perf-validation.md](perf-validation.md)(实验 (a)–(e)) |
|
||||
| 判据源 | [three-problems.md](three-problems.md) §3.7 / 各问题 §2.4 |
|
||||
| 构建 | marqdo v1.0.7(本仓库工作树;金 20 + 全量回归通过后采样) |
|
||||
| 端点 | `llm.cflmy.cn/v1`(OpenAI 兼容;temperature=0) |
|
||||
| 模型 | 修复实验:`cflmy`、`mimo-v2.6-flash`;盲测:`deepseek-flash`、`mimo-v2.6-pro`(按用户指定) |
|
||||
| 回归 | 全量干净回归(无 API key 基线)**零失败** |
|
||||
|
||||
## 1. 五实验结果与判据对照
|
||||
|
||||
| 实验 | 判据 | 结果 | 判定 |
|
||||
|---|---|---|---|
|
||||
| **(a) 锚点消融**(T3.3,双模型×20例×双臂,三轮) | anchor 臂一轮修复率 ≥ 80%;护栏 0 次越界应用 | cflmy anchor **20/20=100%**(plain 17/20=85%);mimo-v2.6-flash anchor **20/20=100%**(plain 18/20=90%;容错加固中的第二轮 anchor 18/20=90% 亦 ≥80%);越界拒/越界应用 0/0 | ✅ 过 |
|
||||
| **(b) 盲测**(查询式 vs 全文档背诵,6任务×2臂) | 四判据:最终通过率 Q 不劣于 D(允许 −0 例);首轮语法错误率 Q ≤ D;平均修复轮次 Q ≤ D;token ≤ 70% of D(首轮契约诊断率为观测项) | deepseek-flash:docs 4/6 vs query 0/3(3 例端点 infra 剔除);首轮语法错 2/3 vs 2/6;token 69,771 vs 57,276。mimo-v2.6-pro:两跑均端点 infra(12/12、11/12),**不可评估** | ❌ 四判据未全立 ⇒ 按 §3.7 继续改协议 |
|
||||
| **(c) 契约消融**(四边界×三情形) | 带契约错值拦截 = 100%;带契约对值误报 = 0%;无契约路径零回归 | 拦截 4/4=**100%**;误报 0/4=**0%**;无契约 4/4 动态语义保持(含 `missing map key` 基线) | ✅ 过 |
|
||||
| **(d) 防漂移演练**(9 漂移 + 2 负对照) | 故意写错必报 = 100%;对照组误报 = 0% | 必报 9/9=**100%**(`unknown_type`×2、`param_drift`×2、`return_mismatch`、`arg_mismatch`、`unknown_key`、`contract.duplicate`、`contract.unknown_table`);负对照误报 0/2 | ✅ 过 |
|
||||
| **(e) 核心守卫演练**(3 种变异注入) | 单边改动必红;还原必绿 | 3/3 必红(`CORE_CONSTRUCTS` 私增、`core-surface.md` 私增、金样删除);还原全绿 | ✅ 过 |
|
||||
|
||||
**可复制结论(a/c/d/e 全过)**:锚点臂一轮修复率双模型 100%(判据 ≥80%,增量 +15pp/+10pp——易锚定样本近天花板,区分性留难样本扩展);契约系统"只在声明处拦截、零误报、不碰动态路径"成立;契约/实现互查防漂移 100% 必报;核心面单边膨胀被 CI 守卫机械阻断。
|
||||
|
||||
## 2. 实验 (c)(d)(e) 明细
|
||||
|
||||
### (c) 契约消融(tests/contract_ablation.rs,确定性)
|
||||
|
||||
四边界(调用实参 / 返回值 / 表绑定 / 键访问)各测三情形:
|
||||
|
||||
| 情形 | 口径 | 结果 |
|
||||
|---|---|---|
|
||||
| ① 带契约 + 错值 | 必须拦截(`contract.arg_mismatch` / `contract.return_mismatch` / `contract.field_mismatch` / `contract.unknown_key`) | 4/4 |
|
||||
| ② 带契约 + 对值 | 不得报契约错(同路径同形状) | 0/4 误报 |
|
||||
| ③ 无契约 + 错值 | 保持动态语义(不得出现 `contract.*`;走经典动态错误如 `missing map key`) | 4/4 |
|
||||
|
||||
取元一律用主推的 `[]()` 形(`[键](`集合`)`)验证;`集合[^键]` 过渡形保留兼容金样覆盖。
|
||||
|
||||
### (d) 防漂移演练(tests/drift_drill.rs,确定性)
|
||||
|
||||
9 个"故意写错"全部必报:类型词拼错、参数名漂移、升参未覆盖、返回越约、实参越约、未知键、重复契约表、错列表头契约表、运行时值越约。负对照 2 例(被绑定的数据表、纯动态程序)零误报。同时验证"契约表一经出现即为完整声明"(新升参未覆盖 ⇒ `contract.param_drift` warning)被按设计触发。
|
||||
|
||||
### (e) 核心守卫演练(人工变异,tests/core_surface.rs 必红验证)
|
||||
|
||||
| 变异 | 注入点 | 结果 |
|
||||
|---|---|---|
|
||||
| 私增 `ghost-construct` | `src/parse/mod.rs` `CORE_CONSTRUCTS` | 🔴 必红 |
|
||||
| 私增 `ghost-construct` 行 | `doc/design/core-surface.md` | 🔴 必红 |
|
||||
| 删除金样文件 | `tests/markup-v03/soft-emphasis.mq.md` | 🔴 必红 |
|
||||
|
||||
三次还原后 🟢 全绿。CI 守卫强制"清单与文档双改 + 全部金样存在"。
|
||||
|
||||
## 3. 实验 (b) 盲测:详况与诚实结论
|
||||
|
||||
### 协议
|
||||
|
||||
两臂系统提示词同文 = 硬规则 12 条 + 契约表三形状;**唯一变量 = 语法知识获取**:
|
||||
|
||||
- `query` 臂:MLSP 查询通道(`QUERY: <关键字>` ⇒ `mlsp syntax` 卡片,含戒律原文/样例/文档锚点;≤3 次)
|
||||
- `docs` 臂:完整 markup 参考背诵(`tests/blind/docs-bundle.md`,背诵式全语法表 + 中文内建面)
|
||||
|
||||
任务 6 例(`tests/blind/tasks/`):业务 3(保险理赔准备金 / 工程进度款 / 采购付款门槛,均出自律所实测任务集)+ QuixBugs 改写 3(gcd / 最大子段和 / 质因数分解);oracle = stdout 精确匹配(任务书自带期望输出,把推理难度控制掉,失败归因于**语言能力**)。修复回路 ≤2 次(validate 结构化诊断 + stderr 回喂)。
|
||||
|
||||
### deepseek-flash(完成)
|
||||
|
||||
| 臂 | 通过(一轮) | 通过(最终) | 首轮语法错 | 平均修复轮(过例) | token(p+c) | infra 剔除 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| query | 0/3 | 0/3 | 2/3 | – | 69,771(42,478+27,293) | 3/6 |
|
||||
| docs | 3/6 | **4/6** | 2/6 | 0.50 | 57,276(33,346+23,930) | 0/6 |
|
||||
|
||||
- **docs 臂**:业务题 3/3 全部一轮通过(各 ~3k token);`qb_gcd` 修复 2 轮过;`qb_max_sublist_sum`、`qb_get_factors` 暴露真语法滑倒(列表字面量被当调用 `unknown function [-2,`;参数名漂移 `missing argument for parameter value`)。
|
||||
- **query 臂**:查询通道**被积极使用**(5/6 例用满 3 次,多词查询如 `条件分支 写法` 也能正确命中卡片——已单独验证查询匹配无缺陷);但 3 例被端点空体吃掉,其余 3 例败于真语法错(Python 式元组 `(a, b)` ⇒ `trailing input in expression`;Python 式调用 `gcd(48, 18)` ⇒ `unknown function gcd(48`)与 1 例查询后未交程序。
|
||||
|
||||
### mimo-v2.6-pro(两跑均不可评估)
|
||||
|
||||
首跑 **12/12** 全部"非 JSON / 空体"(与 deepseek 并行时段)。三向探针(小提示词×12000/4000、大提示词×12000)证实**网关随机空体**、与 `max_tokens`/提示词体量无稳定关系。加重试(8→12 次、退避 10→15 秒)并**单独**重跑后仍为 **11/12** 端点 infra(含两臂首聊即 `tok=(0,0)` 的空体);唯一执行到的 `qb_gcd` 例暴露真语法错(`**y**` 作语句 ⇒ `unexpected expression input`)。**结论:`mimo-v2.6-pro` 经本网关不可评估**,(b) 判据以 `deepseek-flash` 数据为准。原始报告:[blind-experiment-2026-09-23-mimo-v2.6-pro.md](blind-experiment-2026-09-23-mimo-v2.6-pro.md)。
|
||||
|
||||
### 判据对照(截至 deepseek-flash)
|
||||
|
||||
| 判据(协议 §2.4 原文口径) | 目标 | 实测(deepseek-flash,非 infra 口径) | 判定 |
|
||||
|---|---|---|---|
|
||||
| 最终通过率(≤3 轮)Q 不劣于 D(允许 −0 例) | ≥ D | 0/3 vs 4/6 | ❌ |
|
||||
| 首轮语法错误率 Q ≤ D | ≤ | 2/3 vs 2/6 | ❌ |
|
||||
| 平均修复轮次 Q ≤ D | ≤ | query 臂无通过例,不可比 | ⚠️ |
|
||||
| token 用量 Q ≤ 70% of D | ≤ 40,093 | 69,771(D 的 121.8%) | ❌ |
|
||||
| (观测项)首轮契约诊断率 Q ≤ D | – | 1/3 vs 0/6 | ➖ 观测 |
|
||||
|
||||
**诚实结论:在 deepseek-flash 上,"查询式"没有跑赢"全背诵"**——三项可判量化判据未达,按协议 §3.7 判定:**四判据未全成立 ⇒「AI 不必学语法」本轮未获实证,继续改协议**(不是证伪——infra 吞掉 query 臂一半样本,非 infra n=3)。要点:
|
||||
|
||||
1. **统计力被端点削弱**:query 臂 6 例中 3 例被空体吃掉(协议无从执行),非 infra 样本 n=3;mimo-v2.6-pro 整组不可用。判据是"有方向的强声明",当前证据**不足以支持也未证伪**其普适性,只能定格为"deepseek-flash × 本任务集 × 本协议版本"下的一次未达标观测。
|
||||
2. **失败模式是真发现**:查询臂的败例是**跨语言习惯泄漏**(元组表达式、Python 调用形)——查询卡片能回答"条件分支怎么写",但模型不查询"这里能不能用元组"。说明"AI 不必学语法"的瓶颈不在**查询机制**,而在**模型的自查纪律**(不知道自己不知道)。
|
||||
3. **token 判据方向存疑**:查询式省的是**系统提示词常驻**(背诵包),花的是**多轮往返**。6 例短程序任务里往返开销 > 常驻节省;该判据更适用于**长会话多文件**场景(一次背诵包 × N 轮 vs 每轮均摊查询),本轮任务形态低估了查询式的收益面。
|
||||
4. **docs 臂的 4/6 说明任务集有区分度**(不是全过/全不过的退化测量)。
|
||||
|
||||
## 4. 测量端基础设施记录(方法学附注)
|
||||
|
||||
- **LLM 端点不稳定**是本轮最大的干扰源:随机空体、reasoning 模型 `finish=length` 截断(思考吃满额度、正文为空)。对策:空体重试 5→12 次 + 退避 5→15 秒、截断自适应(`max_tokens` 加倍重试,封顶 32k)、infra 例从判据比率中剔除并单列。
|
||||
- **harness 缺陷两处**(已修,未污染最终数据):查询额度用满后的续篇被当最终回复(⇒ 假"无程序");程序提取失败不进修复回路(⇒ 少给模型一次标准修复机会)。修复后的协议对两臂完全一致。
|
||||
- **模型口径变化留痕**:原定 `cflmy`/`mimo-v2.6-flash` 组合按用户指示弃用,改 `mimo-v2.6-pro`/`deepseek-flash`;修复实验 (a) 的双模型数据仍是原组合(金 20 协议已完成,不重跑)。
|
||||
|
||||
## 5. 材料与复现
|
||||
|
||||
```bash
|
||||
# (a) 锚点消融(需要 API key)
|
||||
cargo test --test repair_experiment -- --ignored --nocapture # anchor/plain 双臂×20例
|
||||
# (b) 盲测(每模型一次;建议单独跑避免并发)
|
||||
OPENAI_MODEL=deepseek-flash MARQDO_EXP_DATE=2026-09-23 cargo test --test blind_experiment -- --ignored --nocapture
|
||||
# (c)(d) 确定性
|
||||
cargo test --test contract_ablation --test drift_drill
|
||||
# (e) 核心守卫(变异注入→必红→还原必绿,按 perf-validation.md §5 手法)
|
||||
cargo test --test core_surface
|
||||
```
|
||||
|
||||
- 任务书 / 背诵包(冻结,勿改):`tests/blind/`
|
||||
- 原始报告:[blind-experiment-2026-09-23-deepseek-flash.md](blind-experiment-2026-09-23-deepseek-flash.md) · [blind-experiment-2026-09-23-mimo-v2.6-pro.md](blind-experiment-2026-09-23-mimo-v2.6-pro.md)(首跑全 infra)· [repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md) · [repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)
|
||||
- 判据协议:[perf-validation.md](perf-validation.md)(版本化于本仓库,实验前冻结)
|
||||
@@ -0,0 +1,125 @@
|
||||
# P4 性能验证设计(实验协议与判据)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · P4 执行依据** |
|
||||
| 日期 | 2026-09-23 |
|
||||
| 授权 | 用户授权**自行设计**本性能验证设计(P4 不再等待外部文档导入;`doc/next/002.md` 与性能验证无关) |
|
||||
| 上位判据 | [three-problems.md](three-problems.md) §5.1 判据矩阵 + §5.2 实验 (a)–(e);「判据矩阵全绿 + 实验数字可复现之前,三大问题一律视为未解决」 |
|
||||
| 工程任务 | [three-problems-plan.md](three-problems-plan.md) Phase 1–3(已完成);本文只负责**验证它们** |
|
||||
|
||||
> **本文定位**:把 three-problems.md §5.2 的五个实验操作化——每个实验给出**材料、协议、指标、判据**,全部机器可执行、数字可复现。实验产物 = 报告 [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。**只认行为与数字,不认宣言。**
|
||||
|
||||
## 0. 总览
|
||||
|
||||
| 实验 | 验证对象 | 判据(全过 = 该问题的实证成立) | 执行方式 | 状态 |
|
||||
|------|----------|-------------------------------|----------|------|
|
||||
| (a) 锚点修复消融 | 问题三 · 可靠反馈 | 一轮修复率 ≥ 80%(anchor 臂),护栏 0 越界 | 模型在环 `tests/repair_experiment.rs` | ✅ 已完成(三轮双模型) |
|
||||
| (b) 盲测 | 问题三 · 不必学语法 | 查询组错误率 ≤ 全文档组;token 显著更少;修复轮次不升 | 模型在环 `tests/blind_experiment.rs` | 见报告 |
|
||||
| (c) 契约消融 | 问题二 · 语义校验 | 拦截率 = 100%;误报率 = 0%;无契约路径零回归 | 确定性 `tests/contract_ablation.rs` | 见报告 |
|
||||
| (d) 防漂移演练 | 问题二 · 契约可信 | 故意写错契约必报率 = 100% | 确定性 `tests/drift_drill.rs` | 见报告 |
|
||||
| (e) 核心守卫演练 | 问题一 · 核心要小 | 三种变异注入各必红 → 还原必绿 | 变异脚本(见 §4) | 见报告 |
|
||||
|
||||
判定口径([three-problems.md](three-problems.md) §5.1):**任何一项判据不成立,对应问题即「未解决」**——不许用文档宣言充数。
|
||||
|
||||
---
|
||||
|
||||
## 1. 实验 (a):锚点修复消融(问题三 · 可靠反馈)
|
||||
|
||||
**假设**:诊断带 `doc_anchor`/`doc_quote`/`suggestion`(锚点诊断)比裸诊断显著提高一轮修复率。
|
||||
|
||||
- **对照**:`anchor` 臂(全量诊断字段)vs `plain` 臂(剥掉 doc_anchor/doc_quote/suggestion)。
|
||||
- **材料**:golden 20 例(10 骨架 × 2 变体:arg/ret/field/key/typo/drift/dup),易锚定错误。
|
||||
- **协议**:`validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮。
|
||||
- **指标**:一轮修复率、最终修复率、平均尝试、越界拒、弃权。
|
||||
- **判据**:anchor 臂一轮修复率 ≥ 80%;护栏 0 次越界应用(越界必拒由 `tests/repair_loop.rs` 硬断言兜底)。
|
||||
- **执行**:`OPENAI_MODEL=… cargo test --test repair_experiment -- --ignored --nocapture`。
|
||||
- **结果**:三轮双模型全过(cflmy anchor 100% / mimo 90%→100%,plain 85%–100%,护栏 0 越界)——
|
||||
详见 [repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md) 与
|
||||
[repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)。**✅ PASS**。
|
||||
- **诚实注记**:样本为易锚定错误(两臂近天花板),锚点增量的区分性证据留待难样本扩展;不影响本判据达标。
|
||||
|
||||
## 2. 实验 (b):盲测——查询式 vs 全文档背诵(问题三 · 超级核心)
|
||||
|
||||
**假设**:「零语法文档 + MLSP 查询」组(Q)成绩**不劣于**「全文档背诵」组(D),且 prompt token 显著更少、修复轮次不升([three-problems.md](three-problems.md) §3.7 最终判据)。
|
||||
|
||||
### 2.1 对照(唯一变量 = 语法知识的获取方式)
|
||||
|
||||
| 臂 | 系统提示词内容 | 语法知识来源 |
|
||||
|----|----------------|--------------|
|
||||
| **Q 查询组** | 硬规则(12 条)+ 契约表三形状 + MLSP 查询通道说明 | 按需 `QUERY: <关键字>`(≤3 次,harness 代答 `mlsp syntax` 卡片) |
|
||||
| **D 全文档组** | 硬规则(12 条)+ 契约表三形状 + **完整 markup 参考**(`tests/blind/docs-bundle.md`:v0.3 全语法表 + 中文内建面) | 上下文预载(背诵) |
|
||||
|
||||
两臂共同点:硬规则与契约表形状**同文**(受控变量,不测契约知识差异);修复回路相同(`mlsp validate` 诊断回喂,≤2 轮);模型 / 温度 / 任务 / 提示词模板相同。
|
||||
|
||||
### 2.2 材料:任务集(6 例,业务 3 + 算法 3)
|
||||
|
||||
| id | 类型 | 任务 | 功能 oracle(stdout 精确匹配) |
|
||||
|----|------|------|-------------------------------|
|
||||
| `claims_reserve_settle` | 业务 | 保险准备金(免赔/共保/分项限额/追偿/地板) | `28000` |
|
||||
| `contract_milestone_pay` | 业务 | 工程里程碑应付款(保留金/逾期罚/变更/税/地板) | `37354` |
|
||||
| `vendor_po_gate` | 业务 | 采购 PO 准付闸(折扣/加急/预算帽/合规费/地板) | `814` |
|
||||
| `qb_gcd` | 算法 | 最大公约数;打印 gcd(48,18) gcd(1071,462) gcd(0,5) gcd(17,5) 各一行 | `6` `21` `5` `1` |
|
||||
| `qb_max_sublist_sum` | 算法 | 最大子段和;三组输入各打印一行 | `6` `6` `-1` |
|
||||
| `qb_get_factors` | 算法 | 质因数分解,因数以 `*` 连接;12 / 13 / 60 各一行 | `2*2*3` `13` `2*2*3*5` |
|
||||
|
||||
业务任务书复用 MarqdoThesis `formal/exp3-bizreq/data/tasks/`(权威规则文本原样进入提示词);算法任务书为 QuixBugs 改写(从「修 bug」改「实现 + 固定输出」,消除参考源码变量)。
|
||||
|
||||
### 2.3 协议(每例)
|
||||
|
||||
1. 提示词 = 任务书 + 「输出完整 `.mq.md` 源码于单个 ```markdown 围栏」;
|
||||
2. **查询阶段**(仅 Q 臂):模型可输出 `QUERY: <关键字>` 行,harness 以 `mlsp syntax` 卡片作答并继续;累计 ≤3 次;
|
||||
3. **执行阶段**:`marqdo run` → stdout == oracle 即通过;失败则回喂 `mlsp validate` 结构化诊断 + stderr,允许 ≤2 次修复;
|
||||
4. 记录每轮 token(API `usage.prompt_tokens + completion_tokens` 累计)。
|
||||
|
||||
### 2.4 指标与判据
|
||||
|
||||
| 指标 | 口径 | 判据 |
|
||||
|------|------|------|
|
||||
| 功能通过率(一轮 / 最终≤3 轮) | stdout 与 oracle 精确匹配 | Q 最终通过率**不劣于** D(允许 −0 例) |
|
||||
| 首轮语法错误率 | 首轮 `validate`/run 出现 parse 类失败的例数占比 | Q ≤ D |
|
||||
| 首轮契约诊断率 | 首轮出现 `contract.*` 诊断的例数占比 | Q ≤ D(观测项) |
|
||||
| 平均修复轮次 | 通过前的修复次数(含首轮生成记 0) | Q ≤ D |
|
||||
| token 用量 | 逐例累计 prompt+completion | Q **显著更少**(≤ 70% of D) |
|
||||
|
||||
**判定**:四条判据全成立 ⇒ 「AI 不必学语法」实证成立;否则按 §3.7「继续改协议」,不得以改进文档充数。
|
||||
- **执行**:`OPENAI_MODEL=… cargo test --test blind_experiment -- --ignored --nocapture`(每模型一轮)。
|
||||
|
||||
## 3. 实验 (c):契约消融(问题二 · 语义校验)
|
||||
|
||||
**假设**:契约只在**有契约处**拦截错误值(P1:无契约 = 全动态),且不误报。
|
||||
|
||||
- **材料**:`tests/contract_ablation.rs` 内联四边界用例(调用实参 / 返回 / 表绑定 / 字段访问)×三形态:
|
||||
① 带契约 + 错值 → **必拦**(`contract.*` 诊断);② 带契约 + 对值 → **零误报**(正常产出);③ 同程序**删契约表** + 错值 → **零契约诊断**(动态语义原样)。
|
||||
- **指标与判据**:
|
||||
- 拦截率 = ①被拦 / ①总数 = **100%**;
|
||||
- 误报率 = ②误报 / ②总数 = **0%**;
|
||||
- 无契约零回归 = ③零 `contract.*` 诊断且输出 = 动态语义基线;且全量 `cargo test` 绿(441+ 既有测试是无契约路径的主回归面)。
|
||||
- **执行**:`cargo test --test contract_ablation`。
|
||||
|
||||
## 4. 实验 (d):防漂移演练(问题二 · 契约可信)
|
||||
|
||||
**假设**:契约写错**必**被机器抓(不静默信任契约)——three-problems.md §2.8「故意写错契约的金样必红」。
|
||||
|
||||
- **材料**:`tests/drift_drill.rs`——故意写错契约的 N 例(类型 typo `nubmer`、未知对象类型、契约参数名 ≠ 升参名 ×2、返回契约明显不符、重复契约表、错位契约表)+ **负对照**(被绑定的 `字段|类型` 数据表 = web_db_migration 式,必须**不**被当契约吃掉)。
|
||||
- **指标与判据**:
|
||||
- 必报率 = 漂移例被诊断(`check` 报错/警告或运行时 `contract.*`)/ 漂移例总数 = **100%**;
|
||||
- 负对照误报 = **0**。
|
||||
- **执行**:`cargo test --test drift_drill`。
|
||||
|
||||
## 5. 实验 (e):核心守卫演练(问题一 · 核心要小)
|
||||
|
||||
**假设**:核心表面任何**单侧**变更(代码/文档/金样不同步)→ CI 必红——three-problems.md §1.5「新增标记不更新清单时 CI 必须红」。
|
||||
|
||||
- **材料**:`tests/core_surface.rs` 守卫 + 三种变异注入(脚本化,`git checkout` 还原):
|
||||
1. `src/parse/mod.rs` `CORE_CONSTRUCTS` 增一行、不改文档 → **必红**;
|
||||
2. `doc/design/core-surface.md` 表增一行、不改代码 → **必红**;
|
||||
3. 金样文件改名(路径失效)→ **必红**。
|
||||
- **指标与判据**:3/3 变异注入后守卫测试红;还原后全绿。**必红率 = 100%**。
|
||||
- **执行**:报告内嵌演练记录(命令 + 测试输出摘录)。
|
||||
|
||||
## 6. 报告与复现
|
||||
|
||||
- 报告:[perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)((a) 引用既有两份实验报告;(b)–(e) 本次产出)。
|
||||
- 复现命令全部写入报告各节;模型在环实验记录模型名与端点,判据数字允许 ±1 例波动(模型非确定性),**判据线本身不放宽**。
|
||||
- 汇总结论回填 [three-problems-plan.md](three-problems-plan.md) 落地记录;§5.1 判据矩阵逐行标注 ✅/❌。
|
||||
@@ -0,0 +1,64 @@
|
||||
# 修复实验(§5.2(a) 锚点消融)—— 2026-09-22
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 模型 | `mimo-v2.6-flash` @ `https://llm.cflmy.cn/v1` |
|
||||
| 样本 | golden 20 例(易锚定错误) |
|
||||
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |
|
||||
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |
|
||||
|
||||
## 汇总(设计目标:一轮修复率 ≥ 80%)
|
||||
|
||||
| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |
|
||||
|---|---|---|---|---|---|
|
||||
| anchor | 20/20(100%) | 20/20(100%) | 1.00 | 0 | 0 |
|
||||
| plain | 18/20(90%) | 19/20(95%) | 1.05 | 0 | 1 |
|
||||
|
||||
## 逐例
|
||||
|
||||
| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |
|
||||
|---|---|---|---|---|---|
|
||||
| arg-num-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-type-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-type-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-type-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-type-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-a | plain | 未修复 | 1 | 0 | 模型弃权/输出不可解析: [{"op":"replace","line":13","text":"*`用户`[^name]*"}] |
|
||||
| key-fix-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-b | plain | 二轮修复 | 2 | 0 | 修复后仍有诊断: {"code":"marqdo.error","contract_ref":null,"doc_anchor":null,"doc_quote":null,"message":"missing map key `phone`","severity":"error","span":{"col":1,"file":"/tmp/marqdo_repair_1666049_plain_key-fix-b.mq.md","line":14},"suggestion":null} |
|
||||
| ret-type-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-b | plain | 一轮修复 | 1 | 0 | |
|
||||
|
||||
## 护栏核对
|
||||
|
||||
- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。
|
||||
@@ -0,0 +1,64 @@
|
||||
# 修复实验(§5.2(a) 锚点消融)—— 2026-09-22
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 模型 | `cflmy` @ `https://llm.cflmy.cn/v1` |
|
||||
| 样本 | golden 20 例(易锚定错误) |
|
||||
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |
|
||||
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |
|
||||
|
||||
## 汇总(设计目标:一轮修复率 ≥ 80%)
|
||||
|
||||
| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |
|
||||
|---|---|---|---|---|---|
|
||||
| anchor | 20/20(100%) | 20/20(100%) | 1.00 | 0 | 0 |
|
||||
| plain | 17/20(85%) | 17/20(85%) | 0.85 | 0 | 0 |
|
||||
|
||||
## 逐例
|
||||
|
||||
| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |
|
||||
|---|---|---|---|---|---|
|
||||
| arg-num-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-a | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
|
||||
| field-nullable-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-b | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
|
||||
| field-type-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-type-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-type-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-type-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-b | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
|
||||
| ret-type-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-b | plain | 一轮修复 | 1 | 0 | |
|
||||
|
||||
## 护栏核对
|
||||
|
||||
- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。
|
||||
@@ -0,0 +1,225 @@
|
||||
# 三大问题落地计划(core 收口 · 渐进式契约 · MLSP)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **本期开发依据 · 执行中** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 设计 | [three-problems.md](three-problems.md)(解决方向与验证设计;判据矩阵 §5.1) |
|
||||
| 范围 | **工程任务 = Phase 1–3**;验证实验(three-problems.md §5.2)协议见 [perf-validation.md](perf-validation.md)(2026-09-23 用户授权自行设计并执行) |
|
||||
| 约定 | 每任务带机器可验证验收;**任务完成 = 验收全绿 + 全量回归绿**;只改宣言不改行为 = 未完成 |
|
||||
|
||||
## 0. 本期范围与依赖
|
||||
|
||||
| 阶段 | 定位 | 本期 |
|
||||
|------|------|------|
|
||||
| **Phase 1** 核心收口 + 诊断地基 | 一切的地基 | ✅ 启动 |
|
||||
| **Phase 2** 渐进式契约层 | 校验层(schema 源头 = 表格/段落) | ✅ 本期主目标 |
|
||||
| **Phase 3** MLSP(AI 语言服务) | **下一步的超级核心**(AI 不必学语法 + 可靠反馈闭环) | ⏭ 下期启动,本期只留接口 |
|
||||
| **Phase 4** 验证实验 | 性能验证(非开发任务) | ❌ 不认领 |
|
||||
|
||||
依赖链(**跳步会倒逼「另造一套错误 / 另写一套 schema」的遮盖式捷径**):
|
||||
|
||||
```text
|
||||
T1.4 Diagnostic ──是──> T2.x 契约诊断的唯一出口
|
||||
T2.x 契约 ───────是──> T3.1 schema 注册表的主数据源
|
||||
T1.1 core-surface ─是─> T3.1 语言面 + T1.3 守卫
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 · 核心收口 + 诊断地基(本期启动)
|
||||
|
||||
### T1.1 核心表面清单
|
||||
|
||||
- **产出**:`doc/design/core-surface.md`
|
||||
- **实现要点**:
|
||||
- 两张表:**行构造**(heading-unit `#`/`##`、call-line `>`、branch-list `1.`、loop-list `-`、param `+ 名`、table、fence、hr、writeback、narrative、blank)与**内联标记**(ident `` `名` ``、bold-code `**…**`、italic-return `*…*`、empty-return、link-index `[键](集合)`、bracket-call `[函数]`、footnote-index `[^键]` 过渡);
|
||||
- 每行含:**id**(英文 kebab,守卫用)、Markdown 外形、语义、**戒律**(边界 + 为什么不能是普通 Markdown)、**金样**(`tests/markup-v03/…` 路径);
|
||||
- 与 [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) §5 / §10 对齐;词法大类(`src/lex/mod.rs` `LineKind`)另列一节说明与构造表的关系。
|
||||
- **验收**:每行金样文件真实存在(T1.3 断言);id 全集 = T1.3 `CORE_CONSTRUCTS` 全集。
|
||||
|
||||
### T1.2 三层归属与准入戒律
|
||||
|
||||
- **产出**:`doc/design/layers.md` + `.github/PULL_REQUEST_TEMPLATE.md`(无则新建)
|
||||
- **实现要点**:
|
||||
- 归属表(含仓库路径):Language = `src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` + 契约检查器;Runtime = `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view` `src/debug` + 未来的 check/schema/mcp;Document = `*.mq.md` `skills/` `ext/` `public/` `examples/`;
|
||||
- 准入戒律:新特性先填层归属;进 Language 必答「为什么现有标记不够」;默认进 ext;核心标记计数每 release 只许持平或下降;
|
||||
- 发布 checklist:CHANGELOG 增「核心表面 Δ」栏(写入 `skills/marqdo-release/SKILL.md` 一步)。
|
||||
- **验收**:PR 模板含「层归属」必填项;layers.md 与 core-surface.md 互相引用闭合。
|
||||
|
||||
### T1.3 核心表面守卫(CI)
|
||||
|
||||
- **产出**:`tests/core_surface.rs` + `src/parse/mod.rs` 增 `pub const CORE_CONSTRUCTS: &[(&str, &str)]`(id、外形;**紧邻分类代码维护**)
|
||||
- **实现要点**:`include_str!` 解析 core-surface.md 表格 id 列 ↔ `CORE_CONSTRUCTS` **双向集合相等**;每行「金样」路径 `Path::exists()` 断言。
|
||||
- **验收(反遮盖核心)**:
|
||||
- 新增 `CORE_CONSTRUCTS` 条目不改文档 → **红**;
|
||||
- 文档加行不改代码 → **红**;
|
||||
- 删除/改名金样文件 → **红**。
|
||||
|
||||
### T1.4 诊断对象扩展(Phase 2/3 的唯一出口)
|
||||
|
||||
- **产出**:`src/diagnostics.rs` 扩展 + `src/main.rs` `run --json`
|
||||
- **实现要点**:
|
||||
- `Diagnostic` 增 `code`(如 `parse.*` / `contract.*` / `runtime.*`)、`severity`、`suggestion`、`doc_anchor`、`doc_quote`、`contract_ref`(Phase 2 起填值);`::new/at` 签名不变(全仓调用零改动),新增 builder 方法;
|
||||
- `serde::Serialize` + `to_json()`;**Display 保持 `path:line:col: message`**(人类输出零回归);
|
||||
- `run --json`:顶层错误路径把 Diagnostic 序列化输出(stderr JSON 行)。
|
||||
- **验收**:现有错误金样文本输出**零变化**;新金样断言 JSON `code`/`span` 非空;`cargo test` 全绿。
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 · 渐进式契约层(本期主目标)
|
||||
|
||||
### T2.1 契约 AST + 提取器
|
||||
|
||||
- **产出**:`src/contract.rs`(`Contract` / `ParamContract` / `FieldContract` + 类型词汇 `text/number/bool/list/map/any/对象名`);`src/parse/`(提取);`src/ast.rs`(挂载,带 span)
|
||||
- **实现要点**:按 [three-problems.md](three-problems.md) §2.3/§2.4——**未绑定文档表** + 列头关键字(`参数/返回/字段/类型/说明`)+ 允许位置(函数体首个可执行行前 / 绑定前 / 对象体首成员前);**被绑定的表永不视为契约表**。
|
||||
- **验收**:三附着面金样 + 「绑定表不吃」反例金样(web_db_migration 式 `字段|类型|可空` 绑定数据表必须原样是数据);未知类型名(`nubmer`)必产诊断。
|
||||
|
||||
### T2.2 四边界运行时校验
|
||||
|
||||
- **产出**:`src/interp.rs` 接入四边界——调用实参 / 字段访问(`[键](集合)`、`.field`)/ 表绑定 / `*…*` 返回
|
||||
- **实现要点**:只在**该边界有契约**时校验(无契约 = 全动态,P1);诊断一律走 T1.4 出口(`code=contract.*`)。
|
||||
- **验收**:有契约 + 错值 → 必产诊断;**无契约路径全量回归零变化**;three-problems.md §5.2(c) 消融材料可产。
|
||||
|
||||
### T2.3 `marqdo check` + `--json`
|
||||
|
||||
- **产出**:`src/check.rs` + `src/main.rs` `Commands::Check`
|
||||
- **实现要点**:静态**按需**校验(只查有契约处);不做全局推导。
|
||||
- **验收**:契约样例工程 `check` 退出码非 0 且 JSON 合协议;干净工程 0 退出零输出。
|
||||
|
||||
### T2.4 锚点诊断
|
||||
|
||||
- **产出**:契约诊断填 `doc_anchor`(契约表行段 `file#Lx-Ly`)+ `doc_quote`(表行原文)
|
||||
- **验收**:金样断言锚点非空且行号回读命中契约表;three-problems.md §5.2(a) 材料就绪。
|
||||
|
||||
### T2.5 契约 vs 实现互查(防漂移)
|
||||
|
||||
- **产出**:check + 运行时提示——契约参数名 ≠ 升参名 / 未知类型 / 返回契约明显不符 → 诊断
|
||||
- **验收**:故意写错契约的金样**必红**(three-problems.md §5.2(d) 材料就绪)。
|
||||
|
||||
### T2.6 运行时内省 `get_schema`(可延后,P3)
|
||||
|
||||
- **产出**:`src/builtin.rs` 内省 builtin(契约是数据,P3)
|
||||
- **验收**:demo 运行中取回自身函数契约并打印。
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 · MLSP(下一步的超级核心;本期只留接口)
|
||||
|
||||
### T3.1 `marqdo schema`(schema 注册表,三来源零手写)
|
||||
|
||||
- **产出**:`src/schema.rs` + `Commands::Schema`——语言面(core-surface 机械转 JSON)+ 函数/类型面(**契约** + stdlib/ext 签名)+ 项目面(`catalog.yaml`)
|
||||
- **验收**:两次生成 byte-identical;stdlib 主函数覆盖率 ≥ 90%。
|
||||
|
||||
### T3.2 `marqdo mcp`(AI 工具面)
|
||||
|
||||
- **产出**:MCP server(参考 `plugins/agent/src/mcp_server.rs`)——`syntax_list` / `syntax_get` / `fn_schema` / `type_schema` / `validate` / `repair` / `run`
|
||||
- **验收**:MCP 客户端冒烟:`fn_schema` → `validate` → `repair` 全链路。
|
||||
|
||||
### T3.3 查询式 AI Skill
|
||||
|
||||
- **产出**:`skills/marqdo/` 改写——十条硬规则 + 查询工作流(construct → validate → 修 → run);细节一律走 `syntax_get` / `fn_schema`
|
||||
- **验收**:skill 体积减半以上;金样全绿。
|
||||
|
||||
### T3.4 修复回路
|
||||
|
||||
- **产出**:repair 规则库 + 语句级 patch(AST span 对齐;预算 N=3;防循环)
|
||||
- **验收**:注入 bug 金样一轮修复率可测(three-problems.md §5.2(a) 执行就绪)。
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 · 验证实验(**协议 = [perf-validation.md](perf-validation.md)**)
|
||||
|
||||
- 2026-09-23 用户授权**自行设计**性能验证设计并执行验证;`doc/next/002.md` 与性能验证无关(此前「待导入」表述已纠正)。
|
||||
- five 实验 (a)–(e) 的**材料由 Phase 1–3 的验收金样直接供给**;协议 / 指标 / 判据见 [perf-validation.md](perf-validation.md) §1–§5;
|
||||
实验产物 = [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。
|
||||
|
||||
---
|
||||
|
||||
## 完成定义
|
||||
|
||||
| 阶段 | 完成定义 |
|
||||
|------|----------|
|
||||
| Phase 1 | T1.1–T1.4 验收全绿 |
|
||||
| Phase 2 | T2.1–T2.5 验收全绿(T2.6 可延后) |
|
||||
| Phase 3 | T3.1–T3.4 验收全绿 |
|
||||
| 三大问题「已解决」 | [three-problems.md](three-problems.md) §5.1 判据矩阵全绿 + 实验数字可复现(Phase 4) |
|
||||
|
||||
## 落地记录
|
||||
|
||||
### Phase 2 · 渐进式契约层(2026-09-22 完成 T2.1–T2.5;T2.6 按计划延后至 Phase 3)
|
||||
|
||||
- **T2.1** `src/contract.rs`(类型词汇/三形状契约表解析/合并/四边界校验诊断)+
|
||||
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行——
|
||||
契约表的单元不会被误升参;契约表从 body 移除,元数据永不执行)。
|
||||
反例守住:**绑定**的 `字段|类型` 数据表(web_db_migration 风格)绝不视为契约。
|
||||
- **T2.2** 四边界全接:调用实参(普通/库路径/方法三条调用路径)、返回、表绑定、字段访问
|
||||
(键存在性**先于**取值,契约诊断优先于 `missing map key`)。列语义按「几何即类型」:标量或全匹配列向量。
|
||||
- **T2.3/T2.5** `marqdo check [FILE] [--json]`:契约行 vs 升参推断形参双向互查
|
||||
(错行 ⇒ Error;新升参未覆盖 ⇒ Warning)、未知类型名(附最近建议)、错位契约;Error ⇒ 非零退出。
|
||||
- **T2.4** 全部契约诊断带 `doc_anchor`(`file.mq.md#L7-L13`)+ `doc_quote`(契约表原文)+
|
||||
`contract_ref`(`declared` = 契约声明摘要);`run --json` / `check --json` 同源输出。
|
||||
- **附带修复(错误出口唯一)**:`src/load.rs` 原来把 parse 错误 `anyhow!("{label}: {e}")` 拍平成字符串,
|
||||
结构化诊断在 import 装载链路丢失;改为 `label_error` 保留 Diagnostic(补文件标签),任何装载层都不许拍平错误。
|
||||
- 验收:`tests/contracts.rs` 12 例(提取 4 + 四边界 4 + check 3 + 正向对照 1)全绿;
|
||||
全量回归零失败(含 262 gold)。
|
||||
- **T2.6(契约导出 `get_schema`)**:按计划延后至 Phase 3 与 MLSP `schema` 一并实现。
|
||||
|
||||
### Phase 3 · MLSP(2026-09-22 完成 T3.1–T3.4 全部工程项 + T2.6)
|
||||
|
||||
- **T3.1** `marqdo mlsp` 子命令:行分隔 JSON over stdio,请求 `{"id","method","params"}` →
|
||||
响应 `{"id","ok","result"|"error"}`(永不 panic,错误也是结构化 JSON)。
|
||||
- **T3.2** 五个 handler 全部实现(`src/mlsp.rs`):
|
||||
`locate`(构造卡片 / 符号定位 + 契约)、`syntax`(关键字/别名 → 卡片;语法唯一事实来源 =
|
||||
`parse::CORE_CONSTRUCTS`,MLSP 只加检索别名不定义语法)、`validate`(parse + 契约 check → 结构化诊断数组)、
|
||||
`repair_targets`(有界修复靶点:`strategy=anchored-local`、`on_violation=abstain`——越界必拒护栏先行)、
|
||||
`schema`(**T2.6 完成**:单元名 → 形参/返回/字段契约 + 升参清单 + 锚点)。
|
||||
- 验收:`tests/mlsp.rs` 7 例全绿(语法问答/未知查询/符号定位/漂移校验/schema 导出/有界修复/结构化错误);
|
||||
stdio 冒烟通过;全量回归零失败。
|
||||
- **T3.4(修复回路)**(2026-09-22 完成工程项)——`src/repair.rs` **机械护栏**(有界行编辑
|
||||
replace/delete/insert:触碰行必须落在靶点范围内,越界 ⇒ 整体拒绝 + 越界清单 + abstain,源零字节不改;
|
||||
表尾追加允许 end+1)+ `mlsp repair_apply` 出口(护栏的 MLSP 面)+ **golden 20 例**
|
||||
(10 骨架 × 2 变体:arg/ret/field/key/typo/drift/dup;金修复经完整修复循环复现——诊断 → 靶点 →
|
||||
行编辑自动推导 → 范围自检(「易锚定」的机器验证)→ 应用 → 复验)+ 护栏负例(越界必拒/部分越界全拒)。
|
||||
**模型实验完成(2026-09-22 · `tests/repair_experiment.rs` · 双模型三轮 @ llm.cflmy.cn)**:
|
||||
§5.2(a) 锚点消融——`anchor` 臂(诊断带 `doc_anchor`/`doc_quote`/`suggestion`)**一轮修复率最高 20/20 = 100%**(目标 ≥80% ✅);
|
||||
`plain` 臂(去锚)85%–100%。三轮汇总:
|
||||
|
||||
| 轮 | 模型 | anchor 一轮 | anchor 最终 | plain 一轮 | plain 最终 | 护栏越界 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1 | `cflmy`(Qwen3.8-Flash-Next) | **20/20(100%)** | 100% | 17/20(85%) | 17/20 | 0 |
|
||||
| 2 | `mimo-v2.6-flash`(容错加固中) | 18/20(90%) | 19/20(95%) | 19/20(95%) | 19/20 | 0 |
|
||||
| 3 | `mimo-v2.6-flash`(容错补齐后) | **20/20(100%)** | 100% | 18/20(90%) | 19/20(95%) | 0 |
|
||||
|
||||
**"≥80% 一轮修复率"三轮双臂全部达标(最低 85%)**;护栏 0 越界(越界必拒/abstain 由确定性测试
|
||||
`tests/repair_loop.rs` 硬断言覆盖)。实验同时是 `validate`→`repair_targets`→`repair_apply` 功能面的真实消费者。
|
||||
**"不稳定"定性为三类测量端问题,均已加固**(与 Marqdo 语义无关):① 网关空体抖动 → curl `--retry` + 5s 退避;
|
||||
② 推理模型 token 预算被 `reasoning_content` 吃光 → `max_tokens` 2000→8000;③ 模型输出格式畸形 → 解析容错
|
||||
(数组/单对象/NDJSON 多对象流/字符串化元素/字符串型行号/围栏/数字后多余引号的确定性修补)。
|
||||
锚点增量观察:易锚定样本两臂都高(天花板效应),cflmy 上 anchor +20pp 明显、mimo 上持平——
|
||||
**锚点价值的区分性验证留 Phase 4**(难样本/信息受限消融)。
|
||||
报告:[repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md)(cflmy)、
|
||||
[repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)(mimo 终测)。
|
||||
- **T3.3(AI Skill 换骨:背语法 → 查 MLSP)**(2026-09-22 完成)——`marqdo` / `marqdo-dev` 两件套改为
|
||||
查询式工作流:写码前 `mlsp syntax/locate`、提交前 `mlsp validate` + `marqdo check`;
|
||||
渐进式契约三种表格形状入语法面;错误修复照 `doc_anchor` 局部改(越界必弃权)。
|
||||
|
||||
## Phase 4 · 验证执行记录(2026-09-23,协议 [perf-validation.md](perf-validation.md))
|
||||
|
||||
- **(a) 锚点修复消融** ✅ PASS——判据「anchor 一轮 ≥80% + 护栏 0 越界」:cflmy anchor 20/20=100%(plain 85%)、
|
||||
mimo-v2.6-flash anchor 20/20=100%(plain 90%),越界拒/越界应用 0/0。易锚定样本近天花板,
|
||||
增量区分性留难样本扩展(协议 §1 诚实注记)。
|
||||
- **(b) 盲测(查询式 vs 全文档背诵)** ❌ 四判据未全立 ⇒ 按 three-problems.md §3.7 **继续改协议**——
|
||||
deepseek-flash:docs 4/6 vs query 0/3(端点 infra 剔除 3/6);首轮语法错 2/3 vs 2/6;token 69,771 vs 57,276。
|
||||
mimo-v2.6-pro 两跑均端点 infra(12/12、11/12,**不可评估**;结果回填 [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md) §3)。
|
||||
**真发现**:查询机制本身无缺陷(多词查询亦正确命中卡片),败例是**跨语言习惯泄漏**(元组表达式/Python 调用形)
|
||||
——模型"不知道自己不知道"而不去查。协议改进主攻方向:**自查触发机制**(validate 前置自检、
|
||||
陌生构造强制查询),而非继续改进卡片。
|
||||
- **(c) 契约消融** ✅ PASS——拦截率 4/4=100%、误报率 0/4=0%、无契约零回归 4/4(四边界:调用实参/返回/表绑定/键访问)。
|
||||
- **(d) 防漂移演练** ✅ PASS——必报率 9/9=100%(9 类故意写错全数诊断)、负对照误报 0/2。
|
||||
- **(e) 核心守卫演练** ✅ PASS——3/3 变异注入必红(清单私增/文档私增/金样删除)、还原必绿。
|
||||
- **判据矩阵回填**:three-problems.md §5.1 逐行标注——问题 1 ✅、问题 2 ✅、**问题 3 ❌(未解决)**。
|
||||
- **测量端记录**:LLM 网关随机空体为最大干扰(重试 5→12 次、退避 5→15 秒、截断自适应 max_tokens);
|
||||
harness 修复两处协议性 bug(查询额度用满误判、提取失败不进修复回路)后采样;
|
||||
模型口径按用户指示由 `cflmy`/`mimo-v2.6-flash` 改 `mimo-v2.6-pro`/`deepseek-flash`(实验 (a) 数据为原组合,不重跑)。
|
||||
- **全量干净回归**(无 API key 基线)零失败。
|
||||
@@ -0,0 +1,393 @@
|
||||
# Marqdo 三大问题:解决方向与验证设计
|
||||
|
||||
——证明「被解决」,而不是「被遮盖」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **设计 · 已导出本期开发任务:[three-problems-plan.md](three-problems-plan.md);验证实验不属于开发任务** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 来源 | [001.md](../next/001.md) 评审讨论提炼的三大问题;用户决议:**问题二走「渐进式契约 / 标注类型」**(拒绝照搬静态类型,也拒绝放弃语义校验);**问题三(AI 可靠反馈 + AI 不必学语法)是下一步的超级核心** |
|
||||
| 相关 | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md)(语法宪法)· [tables-maps-footnotes.md](tables-maps-footnotes.md)(表格几何)· [catalog-cli.md](../design/catalog-cli.md) · [ai-skill.md](../design/ai-skill.md) · [objects.md](../design/objects.md) · [interpreter.md](interpreter.md) |
|
||||
|
||||
> **本文定位:三大问题的解决方向与验证设计。** 给三大问题定义「什么算被解决」(机器可验证判据,见 §5.1)与验证实验(修复率 / 盲测 / 消融 / 防漂移演练,见 §5.2),把「真正解决」与「遮盖过去」区分开。文中的解决步骤(各节 S 表)是**设计方向**;本期开发任务、排期与验收以 [three-problems-plan.md](three-problems-plan.md) 为准。**验证实验(§5.2)协议见 [perf-validation.md](perf-validation.md)**(2026-09-23 用户授权自行设计并执行)。
|
||||
>
|
||||
> **一句话:语言核心收口是地基;渐进式契约是校验层,schema 直接长在表格与说明段落里;AI 语言服务消费这两者形成可靠闭环。** 三个问题必须一起解——契约是 AI 接口的数据源,核心收口是契约语法不膨胀的前提。
|
||||
|
||||
**贯穿戒律(防止「遮盖式解决」):每个阶段的验收必须是机器可验证的行为变化。只产出宣言文档、不改变工具行为的,一律视为未完成。**
|
||||
|
||||
---
|
||||
|
||||
## 0. 问题清单与依赖
|
||||
|
||||
| # | 问题 | 定位 | 一句话方案 |
|
||||
|---|------|------|-----------|
|
||||
| 1 | 语言核心正在被生态功能淹没,identity 不清 | **地基** | 三层归属表 + 准入戒律 + 核心表面守卫(CI 断言) |
|
||||
| 2 | 「静态类型列为非目标」被误读为「不需要语义校验」;但照搬 Java/TS 静态类型会毁掉低摩擦 | **校验层** | **渐进式契约**:schema 写在表格 / 说明段落里;按需契约校验;诊断带文档锚点 |
|
||||
| 3 | AI 反馈不可靠(只有给人看的文本);AI 还在背千行语法文档 | **超级核心** | **Marqdo Language Server for AI(MLSP)**:结构化诊断协议 + 可查询 schema + 修复回路 |
|
||||
|
||||
依赖链:
|
||||
|
||||
```text
|
||||
问题 1(核心收口:契约语法不许越界进核心)
|
||||
└─→ 问题 2(契约层:schema 源头 = 表格 / 说明段落)
|
||||
└─→ 问题 3(schema 注册表 = 契约 + 核心表面 + catalog)
|
||||
└─→ 实证(修复实验 + 消融基准 → README 愿景 6)
|
||||
```
|
||||
|
||||
共享地基先行项:**统一诊断协议(Diagnostic)**——问题 2 的契约校验与问题 3 的 AI 反馈都以它为出口,因此它排在最前(见 §3.3 与 §4)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题一:语言核心必须小
|
||||
|
||||
### 1.1 诊断
|
||||
|
||||
Marqdo 现在同时是:Markdown 语言 + literate programming + 知识库 + catalog + web + WASM + 浏览器 + LLM + agent + MCP + 量子 + 线代 + 插件 ABI。工程上这很酷;语言设计上的危险是:
|
||||
|
||||
> **核心语言的 identity 被生态功能淹没;新功能随手进核心 → 语法面暗中膨胀。**
|
||||
|
||||
真正缺的不是「收敛宣言」,而是**三样机制**:
|
||||
|
||||
1. 一份穷举的**核心表面清单**——现在「什么算核心」没有唯一明文;
|
||||
2. 一张**三层归属表**——新提案无处登记,默认哪儿都塞;
|
||||
3. 一条**越界即可见的守卫**——核心语法暗增长没有任何机器报警。
|
||||
|
||||
### 1.2 目标 / 非目标
|
||||
|
||||
**目标**:Language / Runtime / Document 三层分离;核心标记维持**约 15 个**的封闭集合,生态增长不再增加语言面。
|
||||
|
||||
**非目标**:删掉 web/quantum/agent 等功能(它们不是错,层次混放才是错);重写解释器;给核心加模块可见性等系统编程特性。
|
||||
|
||||
### 1.3 三层归属表(S1 产出物,此处先锁定语义)
|
||||
|
||||
| 层 | 内容 | 仓库位置 |
|
||||
|----|------|----------|
|
||||
| **Language** | 标记映射、词法/行分类、AST、语义、升参、**契约检查器**、诊断 | `src/`(解释器核心)· `doc/design/markdown-mapping-v0.3.md` |
|
||||
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema CLI、MCP | `lib/` · `plugins/` · `crates/` · `src/bin` |
|
||||
| **Document** | 知识单元、skills、示例、public 站、agent 工作流、官方扩展 | `*.mq.md` · `skills/` · `ext/` · `public/` · `examples/` |
|
||||
|
||||
核心表面清单(S1 的枚举基线,来自宪法 §5,逐项进 `core-surface.md`):
|
||||
|
||||
叙述(含 `` `名` `` 声明/引用)· `**…**` 代码 · `*…*` 返回 · 空返回形(`*None*` 等)· `>` 调用 · `#` / `##` 标题单元 · 体内 `1.` 分支 · `-` 循环 · GFM 表格 = 集合 · `[键](集合)` 取元 · `修饰… [函数名]` 方括号调用 · 脚注取元(过渡)· ` ```lang ` 外联 · `---` 叙述分隔 · `` + `名` `` 形参(兼容形)。
|
||||
|
||||
### 1.4 解决方向(设计 · 任务化见 plan)
|
||||
|
||||
| 步 | 动作 | 产出 | 验收(机器可验证) |
|
||||
|----|------|------|--------------------|
|
||||
| S1 | 写 `doc/design/core-surface.md`:穷举核心标记,每个标记一行「戒律」(语义、边界、**为什么不能是普通 Markdown**) | 核心表面唯一清单 | 清单项 ↔ `tests/markup-v03/` 金样逐项有例;缺项即测试红 |
|
||||
| S2 | 写 `doc/design/layers.md`:§1.3 归属表 + **准入戒律**——任何新特性提案必须先填「进哪层」;进 Language 层必须答「为什么现有标记不够」,默认答案是「进 ext」 | 归属与准入制度 | 仓库 PR 模板加「层归属」必填项 |
|
||||
| S3 | 核心表面守卫:Rust 测试断言「词法分类枚举 ↔ core-surface.md 表格」一致(脚本解析 markdown 表格比对枚举名) | `tests/core_surface.rs` | 故意加一个新标记不更新清单 → CI 红 |
|
||||
| S4 | 核心变更强制走 ADR:新增核心标记必须有 `doc/adr/` 编号 + 反例说明;每个 release 的 CHANGELOG 单列「核心表面 Δ」 | ADR 戒律 | 发版 checklist 含「核心表面 Δ」栏 |
|
||||
| S5 | 文档收口:README/doc 目录按三层重排;`doc/design/` 只收 Language 层决策,Runtime 进 `doc/roadmap/`,生态面进各自 ext 文档 | 重排后的文档树 | README 目录树与三层表一一对应 |
|
||||
|
||||
**观测指标**(不是 KPI,是体检):核心标记计数每个 release 只许持平或下降;连续 3 个版本增长即触发 Language 层复盘。
|
||||
|
||||
### 1.5 遮盖 vs 解决
|
||||
|
||||
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|
||||
|--------------------|--------------|------|
|
||||
| 写一篇「语言核心很重要」的宣言 | 清单 + 归属表 + **CI 守卫** | 新增标记不更新清单时 CI 必须红 |
|
||||
| 「以后尽量不加语法」的口头约定 | ADR 强制 + CHANGELOG 核心表面 Δ | 没有 ADR 编号的核心变更不允许合并 |
|
||||
| 把 ext 功能砍掉显得小 | 不砍功能,只**归层** | web/quantum/agent 全部保留且测试通过 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 问题二:渐进式契约 / 标注类型
|
||||
|
||||
### 2.1 分歧点澄清(本方案的立场)
|
||||
|
||||
GPT 一侧强调「AI 可验证语言需要强语义校验」,容易被听成「上静态类型」。**这两件事不一样**:
|
||||
|
||||
> 「放弃全程序静态编译类型」**≠** 「放弃语义检查、字段解析、契约校验」。
|
||||
|
||||
照搬 Java/TS 式静态类型会破坏「自然叙述优先、低摩擦」的体验——Marqdo 会变得笨重,丢掉对业务人员 / agent 即兴脚本的友好性。**目标不是变成静态语言,而是一套附着在文档单元上的可查询契约系统,作为 AI 闭环里的校验层。**
|
||||
|
||||
渐进式契约的四条特征:
|
||||
|
||||
1. **动态默认**——不强制任何标注,保持动态,适合快速原型与 agent 即兴脚本;
|
||||
2. **契约即文档**——schema 可选地写在**表格、文档段落**里,不引入第二套标注语言;
|
||||
3. **按需校验**——不做全局类型推导;在调用边界 / 字段访问时校验「当前值 vs 契约」;
|
||||
4. **诊断即文档链接**——错误不只报类型错,还定位到文档里对应的说明段落,给 AI 的诊断自带文档上下文。
|
||||
|
||||
**独有优势(TS/Python 做不到)**:契约的 schema 源头就是表格与函数说明段落本身——不是额外写一套 JSON Schema。知识、契约、数据、代码在同一份 `.mq.md` 里,**契约即知识**。这是 Knowledge-Code Coherence 的第一个可落地实证:契约说 `int` 实际来了 `text` 时,被机器抓住的不是「文档过期」,而是**知识不一致**。
|
||||
|
||||
### 2.2 设计原则
|
||||
|
||||
| # | 原则 | 含义 |
|
||||
|---|------|------|
|
||||
| P1 | 无契约 = 全动态 | 没写契约的单元行为**一字不变**(零回归是硬验收) |
|
||||
| P2 | 不新增核心标记 | 契约语法全部骑在现有 Markdown 外形上(问题一戒律直接约束本节) |
|
||||
| P3 | 契约是数据 | 契约表本身就是 Marqdo 集合,运行时可内省(`get_schema` 一类的 lib 函数免费获得) |
|
||||
| P4 | 双向防漂移 | 不只「值 vs 契约」,还查「契约 vs 实现」(§2.7-S5) |
|
||||
| P5 | 诊断带锚点 | 凡契约诊断必含:契约表所在文件 + 行段 + 原文引用 |
|
||||
|
||||
### 2.3 契约的三个附着面
|
||||
|
||||
**A. 函数契约** —— `##` 函数体内、首个可执行行之前的**未绑定文档表**:
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
|
||||
加一函数:把输入加一。
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `n` | number | 输入值 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| — | number | n+1 |
|
||||
|
||||
对于输入变量`n`,执行**n=n+1**接着返回*n*。
|
||||
```
|
||||
|
||||
参数仍由 v0.3 升参推断(宪法 §8),契约**不改变**形参机制,只在存在时校验——零摩擦兼容存量代码。
|
||||
|
||||
**B. 集合 / 表格契约** —— 紧邻 `` `名` = `` 绑定之前的未绑定文档表:
|
||||
|
||||
```markdown
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | number | 否 |
|
||||
| name | text | 否 |
|
||||
|
||||
`用户` =
|
||||
|
||||
| 行 | id | name |
|
||||
|----|----|------|
|
||||
| 1 | 1 | 甲 |
|
||||
```
|
||||
|
||||
**C. 对象契约** —— `# 对象` 体内首个成员之前的 `| 字段 | 类型 |` 表;同时被 catalog 提取为条目 schema(见 §3.5 项目面)。
|
||||
|
||||
**先例**:schema 长在表格里今天已经发生——`web_db_migration` 的 `| 字段 | 类型 | 可空 |` 列就是以数据形式传递的 DDL schema。契约系统把这个模式升格为**通用约定**。
|
||||
|
||||
### 2.4 形态选型(为什么是「契约表」)
|
||||
|
||||
| 候选 | 形态 | 判决 |
|
||||
|------|------|------|
|
||||
| **P-A 契约表**(选定) | 列头关键字(`参数`/`返回`/`字段`/`类型`/`说明`)的未绑定文档表 | ✅ 与「GFM 表格即数据」哲学一致;catalog 可提取;人读无负担 |
|
||||
| P-B 叙述内标注 | `` `n`: int `` 写在散文里 | ❌ **否决**:改动行内 `` `名` `` 词法 = 核心标记变更,违反问题一戒律与 P2 |
|
||||
| P-C frontmatter | YAML 声明契约 | ⚠️ 仅作文件级汇总的可选补充(serde_yaml 已在解析元信息);函数粒度不够,不作主形态 |
|
||||
|
||||
**消歧规则(防「契约表」误吃数据表)**:
|
||||
|
||||
1. **被绑定的表永不视为契约表**——`名` = 后的表是数据(宪法 §5:未绑定才「求值后丢弃」,即文档表)。`web_db_migration` 的列头恰好叫 `字段|类型|可空` 但它是绑定数据,不受影响;
|
||||
2. 契约表必须是**未绑定文档表** + 列头命中关键字集,且出现在允许位置(§2.3 A/B/C);
|
||||
3. 同一位置出现多张契约表:参数表与返回表各认各的列头;其余重复 → 诊断(防两份契约打架)。
|
||||
|
||||
### 2.5 类型词汇(刻意做小)
|
||||
|
||||
`text` · `number` · `bool` · `list` · `map` · `any` · 对象名(与 `# 对象` / `_type` 对齐)。
|
||||
|
||||
- 词汇表**只有这一行**;扩展类型词汇 = Language 层变更,走 ADR(问题一 S4)。
|
||||
- 类型名拼错(如 `nubmer`)→ **必须报诊断**(§2.7 验收),否则契约本身成为新的漂移源。
|
||||
|
||||
### 2.6 校验时机(按需四边界,不做全局推导)
|
||||
|
||||
| 边界 | 校验什么 | 时机 |
|
||||
|------|----------|------|
|
||||
| 调用实参 | 实参值 vs 参数契约(类型 + 可选 required) | 运行时调用瞬间;`check` 静态可查处一并查 |
|
||||
| 字段访问 | `[键](集合)` / `obj.field` vs 字段契约(键存在性 + 类型) | 访问瞬间 |
|
||||
| 表绑定 | `` `名` = `` 表的几何/单元格 vs 集合契约 | 绑定瞬间 |
|
||||
| 返回 | `*…*` 值 vs 返回契约 | 返回瞬间 |
|
||||
|
||||
无契约 → 该边界直接跳过(P1)。校验器**不是**编译器:不做跨函数全局推导、不要求全程序一致。
|
||||
|
||||
### 2.7 解决方向(设计 · 任务化见 plan)
|
||||
|
||||
| 步 | 动作 | 产出 | 验收(机器可验证) |
|
||||
|----|------|------|--------------------|
|
||||
| S1 | 契约提取器:按 §2.3/§2.4 规则解析未绑定文档表 → `Contract` 对象,挂入 AST 单元(`Param` 已有 `span`,契约同级带 `span`) | AST + 提取器 | 金样:三附着面各一份提取断言(含「绑定表不吃」反例) |
|
||||
| S2 | 运行时边界校验:§2.6 四边界接入 `Contract` | 运行时校验 | 有契约 + 错值 → **必**产出 §3.3 诊断;无契约金样**全绿零回归** |
|
||||
| S3 | `marqdo check`:静态按需校验(只查有契约处),`--json` 输出诊断 | CLI | 契约样例工程 `check` 退出码非 0 且诊断 JSON 合协议 |
|
||||
| S4 | 诊断锚点:契约错误必带 `doc_anchor` + `doc_quote`(契约表原文行) | 诊断增强 | 金样断言诊断 JSON 里锚点字段非空、行号可回读原文 |
|
||||
| S5 | **契约 vs 实现互查**(P4):契约参数名 ≠ 升参推断名、契约类型名未知、契约返回 vs 语句结构明显不符 → 诊断 | 防漂移检查 | 故意写错契约的金样**必须**红(而不是静默信任契约) |
|
||||
| S6 | 运行时内省:`lib` 提供 `get_schema 单元=…`(P3:契约是数据) | lib 函数 | demo:运行中取回自身函数契约表并打印 |
|
||||
|
||||
### 2.8 遮盖 vs 解决
|
||||
|
||||
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|
||||
|--------------------|--------------|------|
|
||||
| 把「静态类型」继续列为非目标就收工 | 明确「≠ 放弃语义校验」,落**边界校验器** | 运行时行为变化可测(§2.7-S2) |
|
||||
| 照搬 Java/TS 全程序静态类型 | 渐进式:无标注零摩擦,按需四边界 | 无契约金样零回归 |
|
||||
| 另写一套 JSON Schema 文件 | schema = 表格 / 说明段落本身 | 仓库里**不允许**出现手写的第二份 schema;契约只能从 `.mq.md` 提取 |
|
||||
| 契约写了就永远正确 | 契约 vs 升参互查 + 未知类型名必报 | 故意写错契约的金样必红 |
|
||||
| 错误只报 `type mismatch` 文本 | 诊断带文档锚点 + 原文引用 | 金样断言锚点字段 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 问题三(超级核心):AI 可靠反馈 + AI 不必学语法细节
|
||||
|
||||
### 3.1 两个子问题
|
||||
|
||||
**A. 可靠反馈**:今天解释器诊断是给人看的文本(`path:line:col` + message,见 ai-skill「按诊断迭代」)。AI 拿到它要「猜」哪里错、对应文档哪句话、怎么改。GPT 设想的闭环——
|
||||
|
||||
```text
|
||||
LLM → Marqdo → 语义校验 → 结构化 Error → LLM 修复 → 合格程序
|
||||
```
|
||||
|
||||
——的第一块砖就是**结构化诊断**,而且诊断必须自带文档上下文(问题二 §2.1-4 的锚点在这里被 AI 消费)。
|
||||
|
||||
**B. 不必学语法**:今天 `skills/marqdo` 是「面向模型的压缩操作手册」= **背诵式**。正确形态是**查询式**:
|
||||
|
||||
```text
|
||||
AI ── discover ─→ construct ─→ validate ─→ execute ─→ inspect
|
||||
```
|
||||
|
||||
AI 不阅读一千行文档然后猜,而是按需调 `get_syntax("branch")`、`fn_schema("print")`、`validate(program)`。**这才是 Marqdo 与普通 DSL 拉开距离的地方。**
|
||||
|
||||
### 3.2 总形态:Marqdo Language Server for AI(MLSP)
|
||||
|
||||
一套机器可读的语言服务协议。工具面(首版最小集):
|
||||
|
||||
| 工具 | 入参 | 返回 | 数据源 |
|
||||
|------|------|------|--------|
|
||||
| `syntax_list` / `syntax_get` | — / 构造名 | 核心构造表 / 单构造戒律 | core-surface(问题一 S1,机械转 JSON) |
|
||||
| `fn_schema` | 函数名 | 参数/返回契约 + 说明 + 锚点 | 契约(问题二)+ stdlib/ext 签名 |
|
||||
| `type_schema` | 对象名 | 字段契约 + 方法表 | `# 对象` 契约 + catalog |
|
||||
| `validate` | 程序文本/文件 | `Diagnostic[]` | 契约校验器 + 语义检查 |
|
||||
| `repair` | 程序 + 诊断 | 建议 patch(限定行级) | 诊断规则库 |
|
||||
| `run` | 入口 | 结果或结构化错误 | 运行时 |
|
||||
|
||||
交付通道(按序):**`marqdo mcp`**(MCP server,复用 agent ext 的 MCP 经验)→ CLI `--json`(任何宿主可用)→ `skills/marqdo` 改造成「教 AI 查询」(§3.6)。
|
||||
|
||||
### 3.3 先决:统一诊断协议(可靠反馈的地基)
|
||||
|
||||
所有层(解释器、check、契约、插件错误)统一产出:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "contract.arg_mismatch",
|
||||
"severity": "error",
|
||||
"message": "参数 `n` 期望 number,实际 text",
|
||||
"span": { "file": "demo.mq.md", "line": 12, "col": 3, "heading": ["加一"] },
|
||||
"doc_anchor": "demo.mq.md#L4-L7",
|
||||
"doc_quote": "| `n` | number | 输入值 |",
|
||||
"contract_ref": { "unit": "加一", "kind": "param", "name": "n", "declared": "number" },
|
||||
"suggestion": "把实参改为数字;若契约有误,改契约表的类型列"
|
||||
}
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
1. 凡可定位必带 `span`(AST 已有 span,宪法 §10.2);
|
||||
2. 凡契约错误必带 `doc_anchor` + `doc_quote`——**错误直接定位到文档里对应的说明段落**;
|
||||
3. 凡可修复建议必带 `suggestion`(给修复回路的原料);
|
||||
4. 人类文本输出保持现状,`--json` 并行提供——人机同读同写,诊断也一样。
|
||||
|
||||
### 3.4 修复回路(repair loop)
|
||||
|
||||
```text
|
||||
validate(p) → diagnose → patch(p, diag) → validate(p') → … (预算 N=3 轮)
|
||||
```
|
||||
|
||||
- **限定行级 patch**,不允许整文件重写(防止 AI「修复」时破坏叙述);
|
||||
- 尝试预算与重复诊断去重,防循环;
|
||||
- 实验指标:**一轮修复率**(带锚点 vs 不带锚点两组对比)——这是「可靠反馈」的直接证据。
|
||||
|
||||
### 3.5 Schema 注册表(三来源,零手写第二份)
|
||||
|
||||
| 面 | 来源 | 说明 |
|
||||
|----|------|------|
|
||||
| 语言面 | `core-surface.md` 机械转 JSON | 构造戒律原文进 `description` |
|
||||
| 函数 / 类型面 | **契约**(问题二产物)+ stdlib/ext 签名 | schema 源头 = 表格与说明段落(§2.1 独有优势) |
|
||||
| 项目面 | `catalog.yaml`(catalog 自动生成) | 知识单元、链接关系(知识图的边) |
|
||||
|
||||
格式 `marqdo-schema.json`(示意):
|
||||
|
||||
```json
|
||||
{
|
||||
"language": "marqdo",
|
||||
"version": "0.3",
|
||||
"constructs": [{ "name": "branch", "syntax": "1. … 2. … N. *", "rule": "自 1. 递增;重出 1. 开新判断" }],
|
||||
"functions": [{ "name": "加一", "params": [{ "name": "n", "type": "number", "desc": "输入值", "anchor": "#L4" }], "returns": { "type": "number" } }]
|
||||
}
|
||||
```
|
||||
|
||||
命令:`marqdo schema [PATH]`(catalog 的兄弟命令,同样**只生成不手改**)。
|
||||
|
||||
### 3.6 AI Skill:从「背诵」改「查询」
|
||||
|
||||
`skills/marqdo` 改造原则:
|
||||
|
||||
- `SKILL.md` 只留**十条不可违反的硬规则**(叙述默认安全、`**` 代码 `*` 返回、表格几何、命名/双语约定等)+ MLSP 工具用法;
|
||||
- 语法细节、API 明细**一律走 `syntax_get` / `fn_schema`**,不再进上下文;
|
||||
- 工作流改为:construct(凭硬规则写)→ `validate` → 按诊断修 → `run`。
|
||||
|
||||
### 3.7 解决方向(设计 · 任务化见 plan)
|
||||
|
||||
| 步 | 动作 | 验收(机器可验证) |
|
||||
|----|------|--------------------|
|
||||
| S1 | Diagnostic 结构落地(Rust)+ 解释器诊断改造 + `run --json` / `check --json` | 现有错误金样转 JSON 后 `code`/`span` 全非空 |
|
||||
| S2 | 契约诊断接入(消费 §2.7-S4 的锚点) | §2.8 判据全部成立 |
|
||||
| S3 | `marqdo schema` 生成器(三来源汇聚) | 生成物 diff 稳定(两次生成 byte-identical);stdlib 主函数覆盖率 ≥ 90% |
|
||||
| S4 | `marqdo mcp`:暴露 §3.2 工具面 | 用 MCP 客户端冒烟:`fn_schema` → `validate` → `repair` 全链路 |
|
||||
| S5 | `skills/marqdo` 改造为查询式(保留硬规则十条) | skill 体积减半以上;既有 `marqdo run` 金样仍全绿 |
|
||||
| S6 | 修复回路 + 实验执行(实验设计见 §5.2) | 实验报告(进 MarqdoThesis,对接 README 愿景 6) |
|
||||
|
||||
**「解决而不是遮盖」的最终判据(问题三)**:盲测组(零语法文档 + 工具)的成绩**不劣于**全文档背诵组,且 token 显著更少、修复轮次不升——达不到就继续改协议,**不许**用「再写一篇更好的文档」充数。
|
||||
|
||||
### 3.8 遮盖 vs 解决
|
||||
|
||||
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|
||||
|--------------------|--------------|------|
|
||||
| 再写一份更全的 AI 语法文档 | 查询协议 + schema 注册表 | 盲测实验成立 |
|
||||
| 让 AI「多读 reference.md」 | `syntax_get` / `fn_schema` 按需取 | skill 体积减半且成绩不降 |
|
||||
| 报错文本润色一下 | 统一 Diagnostic JSON + 文档锚点 | 诊断金样断言锚点字段 |
|
||||
| 主观感觉「AI 好用了」 | 一轮修复率 / 盲测 / token 三组数字 | 实验报告可复现(MarqdoThesis) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 路线顺序(依赖序 · 排期见 [three-problems-plan.md](three-problems-plan.md))
|
||||
|
||||
> 本表是**依赖顺序**,不是排期表——任务化与本期范围见 [three-problems-plan.md](three-problems-plan.md)。
|
||||
|
||||
| 顺序 | 内容 | 产出 | 依赖 |
|
||||
|------|------|------|------|
|
||||
| **M0 核心收口** | 问题一 S1–S5 | core-surface.md · layers.md · CI 守卫 | — |
|
||||
| **M1 诊断地基** | 问题三 S1(Diagnostic + `--json`) | 统一诊断协议 | M0 |
|
||||
| **M2 契约层** | 问题二 S1–S6 | 提取器 · 四边界校验 · `check` · 锚点 · 防漂移 | M1 |
|
||||
| **M3 AI 语言服务** | 问题三 S2–S5 | schema 生成 · `marqdo mcp` · 查询式 skill · 修复回路 | M2 |
|
||||
| **M4 实证** | 问题三 S6 | 修复实验 + 盲测 + 消融(对接 README 愿景 6) | M3 |
|
||||
|
||||
顺序理由:Diagnostic 先于契约(契约诊断是它的第一个消费者);契约先于 MLSP(契约是 schema 注册表的主数据源)——**任何一个跳步都会倒逼「另写一套 schema / 另造一套错误」的遮盖式捷径**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验证矩阵与实验设计(本文核心)
|
||||
|
||||
### 5.1 判据矩阵:什么算「已解决」
|
||||
|
||||
| 问题 | 解决的定义(机器可验证) | 遮盖式收场(一句话就能写完的,禁止) | 验证手段 | 判定(2026-09-23) |
|
||||
|------|--------------------------|--------------------------------------|----------|--------------------|
|
||||
| 1 核心要小 | 新标记不更新 core-surface → **CI 红** | 「我们重视语言核心」 | CI 守卫演练:故意加标记不更新清单,必须红 | ✅ (e) 3/3 必红→还原必绿 |
|
||||
| 2 语义校验 | 四边界校验器上线;契约写错**必**被机器抓;无契约路径零回归 | 「静态类型是非目标」/照搬 TS 类型/另写 JSON Schema | 契约金样 + 防漂移金样 + 全量回归 | ✅ (c) 拦截 100%/误报 0%/零回归;(d) 必报 9/9 |
|
||||
| 3 AI 反馈 / 语法 | 盲测组错误率 ≤ 全文档组且 token 显著更少;一轮修复率可复现 | 「再写更好的文档」 | §5.2 实验 (a)(b)(d) | ❌ (a) 过(双模型 100%);**(b) 四判据未全立** ⇒ 按 §3.7 继续改协议 |
|
||||
|
||||
> 2026-09-23 实测数字与判据对照:[perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。
|
||||
> 按本矩阵口径:**问题 1、2 实证成立;问题 3 未解决**(查询式盲测未跑赢全背诵——详见报告 §3 的四条要点,
|
||||
> 其中「模型不查自己不知道的语法」是协议改进的主攻方向)。
|
||||
|
||||
### 5.2 实验设计(性能 / 可靠性验证)
|
||||
|
||||
| 实验 | 对照组 | 指标 | 材料 |
|
||||
|------|--------|------|------|
|
||||
| (a) 锚点修复 | 诊断带 `doc_anchor` vs 不带 | 一轮修复率、平均修复轮次 | 注入已知 bug 的金样集 |
|
||||
| (b) 盲测(零语法文档) | 只给 MLSP 工具 vs 给全文档背诵(现 `skills/marqdo`) | 语法错误率、契约违规率、token 消耗 | 任务集(QuixBugs 类 + 业务逻辑类) |
|
||||
| (c) 契约消融 | 契约开 / 关 | 契约拦截率、误报率、无契约路径零回归 | 同上 |
|
||||
| (d) 防漂移演练 | 契约故意写错(类型 typo / 参数名与升参不符) | 必报率 = 100% | 契约金样 |
|
||||
| (e) 核心守卫演练 | 故意加新标记不更新清单 | CI 红 = 必须 | — |
|
||||
|
||||
实验基建:复用 MarqdoThesis `formal/exp1–3` 的 runner / oracle / 容错重试;报告即 README 愿景 6 的「可靠性基准」材料。**判据矩阵全绿 + 实验数字可复现之前,三大问题一律视为未解决**——这是「不遮盖」的最终保险。
|
||||
|
||||
---
|
||||
|
||||
## 6. 未决问题(进 M0/M2 的 ADR 逐条锁定)
|
||||
|
||||
1. 契约表消歧的边界案例:紧邻绑定的未绑定表(注释表)紧贴数据表时的归属规则要不要「隔空行才算分离」?(M2-S1 金样定夺)
|
||||
2. 参数表与返回表合并成单表(首列 `参数`/`返回` 混排)是否更可读?(M2-S1 对比样例后定)
|
||||
3. 对象字段契约:与 [objects.md](../design/objects.md) 「不把表当对象定义语言」的非目标如何划界——契约是**可选校验元数据**,不定义对象布局(对象仍是运行时 map);需 ADR 明文,避免与 [tables-maps-footnotes.md](tables-maps-footnotes.md) 非目标条目互相打架。
|
||||
4. 类型词汇是否收 `对象名` 之外的复合形(如 `list<number>`)?——默认**不收**,需要时走 ADR(P2 + 问题一 S4)。
|
||||
5. `marqdo check` 独立子命令 vs `run --check` 并存?(M2-S3 定,倾向独立 + `run` 默认轻查)
|
||||
6. `repair` 的 patch 边界:行级 patch 的具体格式(unified diff vs 语句级替换)?(M3-S4 定,倾向语句级——与 AST span 对齐)
|
||||
+85
-78
@@ -1,19 +1,22 @@
|
||||
# 第 14 章:网络与 Web 扩展
|
||||
|
||||
Marqdo 的网络能力分两层:**标准库 `lib/net`**(HTTP 客户端、cookie / multipart 解析)与**官方扩展 `ext/web`**(网页应用、数据库、表单、登录鉴权、WebSocket)。分层的依据是「代码即文档」的可读性——基础、通用、低依赖的进标准库;领域性强、依赖重、只在 Web 场景才用的进扩展。
|
||||
> **现行作者面(2026-09-28 · ADR 0007)**:Document / Endpoint / Resource —— 见 [ext-web-artifact.md](../design/ext-web-artifact.md)。
|
||||
> 下文若仍出现 `compose_*` / `app.configure` / `web.db` 同文件混写,视为**历史示例**;DB → `ext/data`,鉴权 → `ext/security`,实时 → `ext/net`。
|
||||
|
||||
Marqdo 的网络能力分两层:**标准库 `lib/net`**(HTTP 客户端、cookie / multipart 解析)与**官方扩展 `ext/web`**(Document/Endpoint facade + 拆分后的 data/security/net)。分层的依据是「代码即文档」。
|
||||
|
||||
## 14.1 概览
|
||||
|
||||
| 能力 | 位置 | 典型函数 |
|
||||
| 能力 | 位置 | 典型 API |
|
||||
|------|------|----------|
|
||||
| HTTP(S) 客户端 | `lib/net` | `http_get` / `http_post` / `http_request` |
|
||||
| Cookie 解析 | `lib/net` | `cookie_parse` |
|
||||
| multipart/form-data 解析 | `lib/net` | `multipart_parse` |
|
||||
| 网页应用 / 路由 / 静态 | `ext/web` | `web.page` / `web.app` |
|
||||
| SQLite 数据库 | `ext/web` | `web.db` |
|
||||
| 表单 | `ext/web` | `web.form` |
|
||||
| 登录鉴权(session) | `ext/web` | `web.auth` / `app.auth` |
|
||||
| WebSocket 客户端 / 端点 | `ext/web` | `web.ws` / `app.route_ws` |
|
||||
| Cookie / multipart | `lib/net` | `cookie_parse` / `multipart_parse` |
|
||||
| Document / Endpoint | `ext/web` | `type: web\|endpoint` · `web.serve` · `web.render` · `web.inspect` |
|
||||
| View 装配 | `ext/web` | `|type|slot|value|attrs|style|` → `web.render` |
|
||||
| 数据库 | `ext/data` | `db` CRUD / txn |
|
||||
| 表单 | `ext/data` | `form` |
|
||||
| 鉴权 / RBAC / OIDC | `ext/security` | `auth` · `rbac` · `oidc` |
|
||||
| WebSocket | `ext/net` | `websocket` |
|
||||
|
||||
```bash
|
||||
# 运行使用 ext/web 的程序前,先安装扩展
|
||||
@@ -67,107 +70,111 @@ import net:lib/net.mq.md
|
||||
> print text=[name](`field`)
|
||||
```
|
||||
|
||||
## 14.3 网页应用(`ext/web`)
|
||||
## 14.3 网页应用(Artifact · ADR 0007)
|
||||
|
||||
`ext/web` 用类 + 方法装配页面。导入 `web:ext/web/web.mq.md`(中文 `网页:ext/web/网页.mq.md`)。
|
||||
站点是一堆 `.mq.md`:**Document**(`type: web`)与 **Endpoint**(`type: endpoint`)。入口调用 `web.serve` 扫描目录并监听。完整设计见 [ext-web-artifact.md](../design/ext-web-artifact.md);示例 [marqdo-blog](../../examples/marqdo-blog/)。
|
||||
|
||||
### 页面、组件、主体
|
||||
### Document 首页
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: web
|
||||
title: 我的站点
|
||||
route: /
|
||||
method: GET
|
||||
data_source: posts
|
||||
data_order: -created_at
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# 我的站点
|
||||
|
||||
欢迎。下方卡片列表由 `data_source` 在服务时从数据库加载。
|
||||
```
|
||||
|
||||
### Endpoint
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: endpoint
|
||||
method: GET
|
||||
path: /api/ping
|
||||
request: none
|
||||
response: json
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`首页` =
|
||||
`out` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`导航` | shell.`顶栏` |
|
||||
| ok | service |
|
||||
|----|---------|
|
||||
| True | demo |
|
||||
|
||||
**page = > web.page title="我的站点" intro="<h1>你好</h1>"**
|
||||
**page = > `page`.compose_components components=`首页`**
|
||||
**html = > `page`.render**
|
||||
*out*
|
||||
```
|
||||
|
||||
### 服务入口
|
||||
|
||||
```markdown
|
||||
---
|
||||
import web:ext/web/web.mq.md
|
||||
import posts:db/posts.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**store = > posts.open url="sqlite:data/site.db"**
|
||||
> web.serve root="." host="127.0.0.1" port=18081 db=`store` static_dir="public"
|
||||
```
|
||||
|
||||
离线预览可用 View 表 + `web.render`:
|
||||
|
||||
```markdown
|
||||
`nodes` =
|
||||
|
||||
| type | slot | value | attrs | style |
|
||||
|------|------|-------|-------|-------|
|
||||
| title | title | Marqdo | | title |
|
||||
|
||||
**html = > web.render nodes=`nodes` title="preview"**
|
||||
> print text=`html`
|
||||
```
|
||||
|
||||
### 应用 + 路由 + 监听
|
||||
### 数据库(`ext/data`)
|
||||
|
||||
```markdown
|
||||
**app = > web.app page=`page` host=127.0.0.1 port=18081**
|
||||
**app = > `app`.route path="/about" page=`关于`**
|
||||
> web_listen app=`app`
|
||||
```
|
||||
---
|
||||
import data:ext/data/db.mq.md
|
||||
---
|
||||
|
||||
`listen` 提供 `/`、路由页、表单端点 `/_form/{id}`、可选静态目录与 `/admin`。
|
||||
# main
|
||||
|
||||
### 数据库(SQLite)
|
||||
|
||||
```markdown
|
||||
**store = > web.db url="sqlite:site.db"**
|
||||
**store = > data.db url="sqlite:site.db"**
|
||||
> `store`.init name=articles fields=`字段表`
|
||||
> `store`.insert table=articles rows=`数据`
|
||||
**rows = > `store`.select table=articles limit=10**
|
||||
- [行](rows)
|
||||
> print text=[title](`行`)
|
||||
```
|
||||
|
||||
## 14.4 登录鉴权(session / cookie)
|
||||
## 14.4 鉴权(`ext/security`)
|
||||
|
||||
给 `/admin*` 加登录门禁:`app.auth` 挂用户表,未登录重定向到 `/admin/login`。
|
||||
HTTP 门禁与登录走 `ext/security`(`auth` / `rbac` / `oidc`),再用 `web.use` 挂中间件表;勿再写 `app.configure`。独立脚本可用:
|
||||
|
||||
```markdown
|
||||
`管理员` =
|
||||
---
|
||||
import rbac:ext/security/rbac.mq.md
|
||||
---
|
||||
|
||||
| 行 | 用户名 | 密码 |
|
||||
|----|--------|------|
|
||||
| 1 | admin | secret |
|
||||
| 2 | 站长 | pw123 |
|
||||
# main
|
||||
|
||||
**app = > web.app page=`page` admin=True**
|
||||
**app = > `app`.auth users=`管理员` session_ttl=3600**
|
||||
> web_listen app=`app`
|
||||
**gate = > rbac.rbac**
|
||||
**r = > `gate`.can permissions="desk:access" needed="desk:access"**
|
||||
> print text=[allowed](`r`)
|
||||
```
|
||||
|
||||
`session_ttl` 是会话有效期(秒),过期后重新登录。
|
||||
## 14.5 WebSocket(`ext/net`)
|
||||
|
||||
**独立鉴权工具** `web.auth`:登录、校验、登出(不依赖页面),返回 `{ok, session_id, username}`:
|
||||
|
||||
```markdown
|
||||
**auth = > web.auth users=`管理员` session_ttl=3600**
|
||||
**login = > `auth`.login username="admin" password="secret"**
|
||||
1. [ok](`login`)
|
||||
> print text=登录成功:[username](`login`)
|
||||
2. *
|
||||
> print text=登录失败
|
||||
|
||||
**sid = [session_id](login)**
|
||||
**check = > `auth`.check session_id=`sid`**
|
||||
> print text=[username](`check`)
|
||||
|
||||
> `auth`.logout session_id=`sid`
|
||||
```
|
||||
|
||||
## 14.5 WebSocket
|
||||
|
||||
`app.route_ws` 注册端点,`web.ws.connect` 单次请求–响应:
|
||||
|
||||
```markdown
|
||||
**app = > `app`.route_ws path="/live" echo=True**
|
||||
> web_listen app=`app`
|
||||
```
|
||||
|
||||
客户端(另开终端):
|
||||
|
||||
```markdown
|
||||
**ws = > web.ws timeout_sec=30**
|
||||
**echo = > `ws`.connect url="ws://127.0.0.1:18081/live" message="hi"**
|
||||
1. [ok](`echo`)
|
||||
> print text=[messages](`echo`)
|
||||
2. *
|
||||
> print text=连接失败:[error](`echo`)
|
||||
```
|
||||
实时能力在 `ext/net`(如 `websocket`),与 Document 站点并列导入,不再挂在 `web.app` 的 junk drawer 上。
|
||||
|
||||
## 14.6 字典操作:用表格与取元,不用 `json.get`/`json.set`
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# agent-sandbox-okf(O1)
|
||||
|
||||
演示 **opt-in 沙盒试跑 + 表风格**(少 json 胶水):`agent.trial` 写入先落 upper,`commit=False` 时宿主不变,成功后再 `commit=True`。
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent
|
||||
export MARQDO_EXT="$PWD/ext"
|
||||
./target/release/marqdo run examples/agent-sandbox-okf/index.mq.md
|
||||
```
|
||||
|
||||
期望:`dry-ok` · `host-clean` · `wet-ok` · `proof-visible` · `profile-default`。
|
||||
|
||||
见 [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md) · 金样 [agent-sandbox-optin.mq.md](../../tests/ext/agent-sandbox-optin.mq.md)。
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: agent-sandbox-okf — trial then commit
|
||||
description: >
|
||||
O1 example: opt-in sandbox trial with GFM-table returns and link-index reads.
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Short demo: write via `agent.trial`, prove the host is clean until commit.
|
||||
|
||||
**had = fs.exists path="_example_sbx"**
|
||||
1. `had`
|
||||
> fs.remove path="_example_sbx"
|
||||
2. *
|
||||
**_ = 0**
|
||||
|
||||
> fs.make_dir path="_example_sbx"
|
||||
|
||||
**dry = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=False**
|
||||
**dry_ok = [ok](dry)**
|
||||
**dry_committed = [committed](dry)**
|
||||
1. `dry_ok`
|
||||
1. not `dry_committed`
|
||||
> print text=dry-ok
|
||||
2. *
|
||||
> print text=dry-bad-commit
|
||||
2. *
|
||||
> print text=dry-fail
|
||||
|
||||
**leaked = fs.exists path="_example_sbx/note.txt"**
|
||||
1. `leaked`
|
||||
> print text=host-leaked
|
||||
2. *
|
||||
> print text=host-clean
|
||||
|
||||
**wet = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=True**
|
||||
**wet_ok = [ok](wet)**
|
||||
**wet_committed = [committed](wet)**
|
||||
1. `wet_ok`
|
||||
1. `wet_committed`
|
||||
> print text=wet-ok
|
||||
2. *
|
||||
> print text=wet-no-commit
|
||||
2. *
|
||||
> print text=wet-fail
|
||||
|
||||
**body = fs.read_text path="_example_sbx/note.txt"**
|
||||
1. `body` == "sandbox-okf"
|
||||
> print text=proof-visible
|
||||
2. *
|
||||
> print text=proof-missing
|
||||
|
||||
**pname = [name]([profile](wet))**
|
||||
1. `pname` == "default"
|
||||
> print text=profile-default
|
||||
2. *
|
||||
> print text=profile-other
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: resolve_config
|
||||
capability: config.resolve
|
||||
status: stable
|
||||
---
|
||||
|
||||
Use when: final normalized configuration is required.
|
||||
|
||||
# config
|
||||
|
||||
## resolve_config
|
||||
+ `path`
|
||||
|
||||
`defaults` =
|
||||
|
||||
| host | port |
|
||||
|------|------|
|
||||
| localhost | 8080 |
|
||||
|
||||
* defaults
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Engineering Knowledge demo
|
||||
description: Tiny project demonstrating Capability Catalog + reuse + decisions.
|
||||
---
|
||||
|
||||
# Engineering Knowledge demo
|
||||
|
||||
This folder is a miniature “large engineering” slice: config resolution already exists.
|
||||
Before generating a new loader, run:
|
||||
|
||||
```bash
|
||||
marqdo knowledge examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
|
||||
marqdo reuse "load and resolve configuration" examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
|
||||
marqdo duplicate examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
|
||||
```
|
||||
|
||||
Expected: **REUSE config.resolve**, not a new `load_configuration`.
|
||||
|
||||
# main
|
||||
|
||||
* "see README via catalog/reuse CLI"
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
type: Decision
|
||||
id: ADR-022
|
||||
title: Cache is not persistence
|
||||
status: accepted
|
||||
applies_to:
|
||||
- config.resolve
|
||||
---
|
||||
|
||||
# Cache is not persistence
|
||||
|
||||
## Decision
|
||||
|
||||
Redis is only used for ephemeral cache.
|
||||
|
||||
## Reason
|
||||
|
||||
The application must remain correct when Redis is unavailable.
|
||||
Loaded 100 of 462 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user