Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6d6f580d24 | ||
|
|
af05f19301 | ||
|
|
3201369470 | ||
|
|
05197378b3 | ||
|
|
f3b3152f07 | ||
|
|
22364f2f1b | ||
|
|
b69a90501d | ||
|
|
7ff881f506 | ||
|
|
9acbe10986 | ||
|
|
81989a26d7 | ||
|
|
cf0ba6dccd | ||
|
|
0de703f86a | ||
|
|
4907f92d84 | ||
|
|
eac6921524 | ||
|
|
c0dc18433b | ||
|
|
7d9af11398 | ||
|
|
d9aef957f7 | ||
|
|
aa0c4d0f55 | ||
|
|
c50c515c4a | ||
|
|
16c44588d5 | ||
|
|
5080136d65 | ||
|
|
cc5277d2b5 | ||
|
|
bb06dad134 | ||
|
|
24dcb97354 | ||
|
|
76aa02846a | ||
|
|
0e389f34ec | ||
|
|
492790e985 | ||
|
|
ca434a8bab | ||
|
|
6195ad1d5d | ||
|
|
a87c2154ff | ||
|
|
8f1010f967 | ||
|
|
e3d9021bb6 | ||
|
|
142ab523d6 | ||
|
|
82c8d78fd3 | ||
|
|
58791fc7d9 | ||
|
|
1730f26fc7 | ||
|
|
4018e9928a | ||
|
|
628e3b6e5d | ||
|
|
5c6c612edd | ||
|
|
41587f319e | ||
|
|
298fbd51ea | ||
|
|
265dfdbcc4 | ||
|
|
42a43f5ffd | ||
|
|
037a963547 | ||
|
|
a32638e935 | ||
|
|
43eebe5671 | ||
|
|
e833dc05e2 | ||
|
|
11bb7ef277 | ||
|
|
6bd90bb2d0 | ||
|
|
4683f2e067 | ||
|
|
5912164039 | ||
|
|
303c06f773 | ||
|
|
a1086fd6c3 | ||
|
|
6ffe5ceb19 | ||
|
|
6b568aff3d | ||
|
|
16f26d7d60 | ||
|
|
b8265a92aa | ||
|
|
9af929971c | ||
|
|
2c4fa4bb05 |
No files matched your search
@@ -1,221 +1,14 @@
|
||||
---
|
||||
name: marqdo-dev
|
||||
description: >-
|
||||
Develop Marqdo programs and libraries the readable way: GFM tables as data,
|
||||
code-as-documentation, table.put over json.set chains, lib/ext authoring.
|
||||
Use when writing or refactoring .mq.md, creating lib/* or ext/*, reviewing
|
||||
Marqdo style, fixing unreadable json glue, or when the user asks how to
|
||||
develop Marqdo / 如何开发 marqdo.
|
||||
description: Write, refactor and verify Marqdo programs, standard libraries and extensions through the executable development handbook. Use native Marqdo file tools and marqdo call; extend capability gaps through plugins or explicit external tools.
|
||||
---
|
||||
|
||||
# Marqdo development (author + library)
|
||||
Read [the executable development entry](../../../skills/marqdo-dev/index.mq.md), then [the programming guide](../../../doc/library-development.mq.md). The same guide governs programs, libraries and executable SKILLs. For installed skills, resolve these paths against the Marqdo source checkout.
|
||||
|
||||
Read this **before** writing or expanding `.mq.md`. Syntax basics stay in [marqdo](../marqdo/SKILL.md); this skill is the **style and library craft** contract.
|
||||
Use `**statement**` to execute and `*return*` to return; write `[intent](actual code)` inside executable positions, and `access(coll, key)` to read collections. The guide provides real examples. Native file tasks live in [files.mq.md](../../../skills/marqdo-dev/files.mq.md): read, write, patch, search, inventory, audit and apply. Do not generate Python or shell programs for ordinary file operations.
|
||||
|
||||
## Non-negotiable: code is documentation
|
||||
Prepare the native engineering plugin with the development entry before using its analysis or process tasks. The repository development binary is `target/debug/marqdo`; installed older binaries may need a bootstrap Cargo build through `lib/sys.mq.md exec`. All subsequent task execution uses `marqdo call`. Keep decisions and sequencing in readable mq.md; use a new extension or a documented foreign tool only for a real capability gap.
|
||||
|
||||
A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data and intent without decoding nested `json.set` / `json.append` chains, the code is wrong.
|
||||
The guide is authoritative for narrative over 50%, immediate parameter/return tables, inline statements and returns, GFM data, index.mq.md organization, recursive Markdown web components, failure evidence and verification. Read each task's contract and grant its actual effects. External processes retain their OS authority. Do not rewrite intentional test fixtures or restore removed compose_* APIs.
|
||||
|
||||
| Prefer | Avoid |
|
||||
|--------|--------|
|
||||
| GFM tables for maps, lists, records, wire, commands | Building the same with `json.set` / `json.append` |
|
||||
| Named library helpers (`web.*`, `browser.*`, `table.*`) | Copy-paste effect-map glue in every handler |
|
||||
| `table.put` for **one** dynamic key | Long `json.set` pipelines |
|
||||
| `json.parse` / `json.stringify` / `json.quote` only | Using `json` as a general dict builder |
|
||||
|
||||
`lib/json` is for **parse / stringify / quote**. Collection edits use **GFM tables** and **`lib/table`** (`doc/design/stdlib-table.md`).
|
||||
|
||||
## How to shape data
|
||||
|
||||
### 1. GFM table geometry (memorize)
|
||||
|
||||
| Shape | Result |
|
||||
|-------|--------|
|
||||
| 1 column | list |
|
||||
| ≥2 columns, **one** data row | map (headers = keys) |
|
||||
| ≥2 columns, **many** rows | map of lists (column-oriented) |
|
||||
| First header `@` / `行` / `row` | **list of maps** (row records) |
|
||||
|
||||
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
|
||||
|
||||
### 2. Good patterns (copy these — not `json.set`)
|
||||
|
||||
**Wire / steps / commands** — `@` record table:
|
||||
|
||||
```markdown
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 |
|
||||
|---|--------|------|------|
|
||||
| 1 | "#bump" | click | bump |
|
||||
```
|
||||
|
||||
**Multi-key return / boot** — map table with variable cells:
|
||||
|
||||
```markdown
|
||||
`boot` =
|
||||
|
||||
| wire | set_text |
|
||||
|------|----------|
|
||||
| `wire` | `set_text` |
|
||||
```
|
||||
|
||||
**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**
|
||||
**table.put in=None at="set_text" value=set_text**
|
||||
```
|
||||
|
||||
Better still — call a named helper:
|
||||
|
||||
```markdown
|
||||
**browser.set_text sel="#log" text=msg**
|
||||
```
|
||||
|
||||
**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.**
|
||||
2. `# main`: state binds, then **tables** for wire/config, return boot map via table or helper.
|
||||
3. `##` handlers: short prose OK; data as tables; return via `browser.*` / `web.*` / one `table.put`.
|
||||
4. Blank line between comment paragraphs and code.
|
||||
5. Run `marqdo run path.mq.md` from repo root.
|
||||
6. **Calls in narrative:** prefer `**结果 = 某函数 名=`x`**` (no `>` on the RHS). Bracket form `礼貌 [问候] "x"` / `**出 = [put] …**` is fine when modifiers help. Use `> …` for standalone step lists. See `examples/code-as-docs/`.
|
||||
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 nested `import:` with `browser: lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
|
||||
|
||||
## Developing libraries (`lib/*`, `ext/*`)
|
||||
|
||||
Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../../doc/roadmap/lib-ext-code-as-docs.md).
|
||||
|
||||
### Goals
|
||||
|
||||
- **Authors** see tables and short calls; **library** may hide `table.put` / host calls.
|
||||
- One concern per helper; name the effect (`set_text`, `canvas`, …), do not expose bag surgery.
|
||||
- EN + ZH pair when shipping user-facing libs (`lib/browser.mq.md` ↔ `lib/浏览器.mq.md`, `ext/web` ↔ `ext/web/网页.mq.md`).
|
||||
- `ext/**` never calls `host_*` — use plugins / public lib only (`doc/design/ext-agent.md`).
|
||||
- Collection get: **`[key](coll)`** (no new footnote indexes). Calls in examples may use `修饰 [fn] …` or classic `>` / bold.
|
||||
|
||||
### Library checklist
|
||||
|
||||
- [ ] Purpose sentence + prose params + one example + short body
|
||||
- [ ] Public examples use **tables + helpers**, not json glue
|
||||
- [ ] Index with `[k](c)`; foreach `- [item](coll)`
|
||||
- [ ] Helpers documented with a one-line purpose above `##`
|
||||
- [ ] Defaults on params; omit `None` fields in merged maps
|
||||
- [ ] No `json.set` chains in new code — use `table.put` / `table.merge` / GFM
|
||||
- [ ] `marqdo run` on a tiny demo under `examples/` or inline smoke
|
||||
|
||||
### Where helpers live
|
||||
|
||||
| Need | Place |
|
||||
|------|--------|
|
||||
| Browser effect maps (WASM client) | `lib/browser.mq.md` |
|
||||
| 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 |
|
||||
|
||||
## Refactoring existing glue
|
||||
|
||||
When editing a file full of `json.set`:
|
||||
|
||||
1. Turn static structures into GFM tables.
|
||||
2. Replace repeated effect shapes with `browser.*` / `web.text_patch` / `web.dom_patch`.
|
||||
3. Leave at most sparse `table.put` for dynamic keys.
|
||||
4. Drop unused `json:` (or other) entries under nested `import:`.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| `json.set` × N to build boot | GFM map table or `browser`/`web` helper |
|
||||
| `json.append` to build command list | `@` record table |
|
||||
| Dummy column to force a 1-key map | `table.put` or helper |
|
||||
| Importing `ext/web` only for `text_patch` in WASM | `lib/browser` (no native plugin) |
|
||||
| Unreadable nested maps as “clever” | Flatten into tables humans can read |
|
||||
|
||||
## Related
|
||||
|
||||
- Syntax: [marqdo/SKILL.md](../marqdo/SKILL.md) · [examples.md](../marqdo/examples.md)
|
||||
- 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 面)。
|
||||
Use the development entry's audit task to discover and review maintained repository sources. Its failed Result retains every finding; write_report=True saves the same evidence under .marqdo/audit. It does not execute inspected source or treat known placeholder warnings as completed logic.
|
||||
@@ -1,215 +1,14 @@
|
||||
---
|
||||
name: marqdo-release
|
||||
description: >-
|
||||
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.
|
||||
description: Prepare, publish and verify a user-authorized Marqdo full, cli or extension release through its executable mq.md handbook. Use for release versioning, immutable tags, matching CI gates, GitHub/R2 parity and Ubuntu PPA publication.
|
||||
---
|
||||
|
||||
# Marqdo release
|
||||
Read [the executable release entry](../../../skills/marqdo-release/index.mq.md) and use its task routing. Version and mode come from the user; an already stated choice remains authorized. Inspection of an old release does not authorize republishing it. Never infer a new version, replace a tag, force-push or bypass hooks.
|
||||
|
||||
Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagging or uploading assets. Details: [reference.md](reference.md).
|
||||
Use `marqdo call` on the actual handbook headings. The repository development binary is `target/debug/marqdo`; prepare its engineering plugin through [the development entry](../../../skills/marqdo-dev/index.mq.md). File reading and authoring use native [file tools](../../../skills/marqdo-dev/files.mq.md). No Python release orchestrator is required. New OS/service capabilities belong at explicit plugin or external-tool boundaries; version decisions, retries and publication order remain readable mq.md.
|
||||
|
||||
## Hard rules
|
||||
The entry preserves full/cli/ext deliverables, separate editor sources, clean-main tagging, bilingual authored notes, exact-commit Release and EK gates, both native platforms, GitHub/R2 identical bytes, VERSION-after-ZIP ordering and Ubuntu source/build/apt evidence. Every applicable obligation must be verified before declaring completion. Default full/cli work includes PPA; gh-pages deployment needs its own instruction.
|
||||
|
||||
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:** 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.
|
||||
12. **GitHub auto-build must be green before declaring a release done.** For full/cli: wait for the tag-triggered **Release** workflow (`windows` + `linux`) **and** the push-triggered **`executable-knowledge`** workflow on the release commit / `main` tip. Release asset zips alone are **not** sufficient — a green Release job with a red EK gate is an incomplete release. Do not skip or reframe a red `executable-knowledge` as “assets already uploaded.”
|
||||
Read-only status and verification are separate from publication. Grant effects stated by each task. Inspect Result.ok before value; use --require-ok when an external automation must stop on a failed Result. Credentials stay in their existing private stores. Interactive sudo/GPG/dput or a failed service request remains incomplete: report the concrete failure and the exact handbook recovery call, preserving local evidence.
|
||||
|
||||
## Release modes
|
||||
|
||||
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** 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 ask example:
|
||||
|
||||
> 当前最新 CLI **vA.B.C**,扩展包 **E.F.G**。请指定下一个版本号与模式(`full` / `cli` / `ext`,如 `1.0.3 full`)。
|
||||
|
||||
## Phase 0 — Detect versions (mandatory stop)
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
|
||||
```
|
||||
|
||||
Report briefly, then **ask for SemVer + mode** (unless already given). Normalize `VER` / `TAG`.
|
||||
|
||||
## Phase 1 — Preflight
|
||||
|
||||
```
|
||||
Release progress:
|
||||
- [ ] Phase 0: version + mode confirmed
|
||||
- [ ] Phase 1: preflight green
|
||||
- [ ] Phase 2: docs + version bumps committed
|
||||
- [ ] Phase 3: extension branch (full/cli)
|
||||
- [ ] Phase 4: main pushed; tag created & pushed
|
||||
- [ ] 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: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
|
||||
Also confirm the latest `main` **`executable-knowledge`** Actions run is green (or that this release commit will be covered after push) — do not proceed to tag if EK is already red on tip without a fix in the same release PR.
|
||||
|
||||
## Phase 2 — Docs & version bumps (main)
|
||||
|
||||
| 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 # when public/ sources changed
|
||||
```
|
||||
|
||||
Commit + push `main` (proxy origin). On push failure → reference § Proxy; if still blocked, **print** for the user:
|
||||
|
||||
```bash
|
||||
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
|
||||
# or: python3 scripts/push-via-hk-jump.py
|
||||
```
|
||||
|
||||
## Phase 3 — VS Code / Cursor extension (full/cli only)
|
||||
|
||||
Default: bump `vscode-extension` package.json to `VER`, compile, push branch `vscode-extension`, return to `main`.
|
||||
|
||||
## Phase 4 — Tag & trigger CI (full/cli)
|
||||
|
||||
```bash
|
||||
git tag -a "vVER" -m "vVER"
|
||||
git push origin "vVER"
|
||||
```
|
||||
|
||||
Ext-only:
|
||||
|
||||
```bash
|
||||
git tag -a "ext-vVER" -m "ext-vVER"
|
||||
git push origin "ext-vVER"
|
||||
```
|
||||
|
||||
(or build zips locally / via workflow and `gh release upload`).
|
||||
|
||||
If tag push needs the user:
|
||||
|
||||
```bash
|
||||
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
|
||||
```
|
||||
|
||||
## Phase 5 — GitHub Release notes & assets
|
||||
|
||||
1. Wait for Actions (full/cli):
|
||||
- Tag **Release** workflow: both `windows` and `linux` green when ext natives required.
|
||||
- Push **`executable-knowledge`** workflow on the release commit / `main`: **must be success**. Poll with `gh run list --workflow=executable-knowledge.yml --branch main` / `gh run watch`. If EK is red → **stop**; fix plugin/harness on `main`, re-run; do **not** declare the release complete from assets alone.
|
||||
2. Rewrite release body 中英双语 — [reference.md § Notes](reference.md).
|
||||
3. Confirm Linux `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` when mode ships ext.
|
||||
|
||||
## 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. Confirm **`executable-knowledge`** and **Release** Actions are both green for this tag/commit; if either is red, say so and do not claim “发版完成”.
|
||||
3. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
|
||||
4. PPA build green (if cli shipped).
|
||||
5. Tell user URLs: GitHub release, CDN, PPA install one-liner.
|
||||
6. Optional gh-pages only if asked.
|
||||
|
||||
## Extension-only release (mode=ext)
|
||||
|
||||
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; 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 (Release assets) | Fix on main; retag only if user allows |
|
||||
| `executable-knowledge` red | Fix agent plugin / test harness (e.g. `ensure_agent_plugin_built`); push `main`; wait for EK green. **Do not** treat uploaded Release zips as a successful release |
|
||||
| R2 upload fails | Print `upload-ext-r2.py` command; do not skip silently |
|
||||
| PPA / sudo / GPG | Print `./scripts/ppa-ship.sh noble` (or `dput …`); do not skip silently |
|
||||
| Launchpad `Cargo.lock` v4 / old cargo | Ensure bundled `third_party/rust` via current `ppa-build-source.sh`; bump `1ppaN` |
|
||||
| Linux native zip missing (full/ext) | Incomplete — fix linux job or upload |
|
||||
|
||||
## Do not
|
||||
|
||||
- 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`.
|
||||
Independent extension releases commit reviewed bilingual notes at doc/releases/ext-X.Y.Z.md before tagging. The [pack handbook](../../../skills/marqdo-release/packs.mq.md) and extension-release.yml run native staging, both platform builds, exact-tag release creation and non-clobbering gh asset upload through marqdo call. An existing upload is inspected rather than replaced. Windows execution remains a CI obligation; a local Linux ZIP cannot prove it.
|
||||
@@ -1,406 +1,3 @@
|
||||
# Marqdo release — reference
|
||||
# Release task reference
|
||||
|
||||
Companion to [SKILL.md](SKILL.md). Use during a release; keep SKILL short.
|
||||
|
||||
## Detect versions (commands)
|
||||
|
||||
```bash
|
||||
# From repo root
|
||||
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
|
||||
# or manually:
|
||||
git fetch --tags origin 2>/dev/null || true
|
||||
echo "Cargo: $(sed -n 's/^version = \"\(.*\)\"/\1/p' Cargo.toml | head -1)"
|
||||
echo "wasm: $(sed -n 's/^version = \"\(.*\)\"/\1/p' crates/marqdo-wasm/Cargo.toml | head -1)"
|
||||
echo "tags: $(git tag -l 'v*' --sort=-v:refname | head -3 | tr '\n' ' ')"
|
||||
gh release list --limit 3 2>/dev/null || true
|
||||
```
|
||||
|
||||
**SemVer guidance for the ask (do not choose for the user):**
|
||||
|
||||
| Kind | When |
|
||||
|------|------|
|
||||
| patch `x.y.(z+1)` | Fixes, docs, no public API / MQ surface break |
|
||||
| minor `x.(y+1).0` | New features (WASM route C, new ext APIs) backward compatible |
|
||||
| major `(x+1).0.0` | Breaking MQ / CLI / plugin ABI |
|
||||
|
||||
## Asset matrix (CI tag `v*`)
|
||||
|
||||
Produced by `.github/workflows/release.yml` on **windows-latest** (`windows` job) and **ubuntu-latest** (`linux` job, **required**, `needs: windows`):
|
||||
|
||||
| Asset | Role | Job |
|
||||
|-------|------|-----|
|
||||
| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) | windows |
|
||||
| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/` + native DLL | windows |
|
||||
| `marqdo-VER-stdlib.zip` | `lib/` only | windows |
|
||||
| `marqdo-VER-ext.zip` | Official `ext/` L1 | windows |
|
||||
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) | windows |
|
||||
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) — **must ship** | linux |
|
||||
| `marqdo-VER-x86_64-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` — **must ship** | linux |
|
||||
| `marqdo-VER-source.zip` | `git archive` of tagged commit | windows |
|
||||
| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) | windows |
|
||||
| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) | windows |
|
||||
|
||||
Not CI-uploaded (document in notes): macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`.
|
||||
|
||||
A release **without** the Linux native zip is incomplete (`marqdo ext add` on Linux cannot download prebuilts).
|
||||
|
||||
## Doc sync checklist (Phase 2 detail)
|
||||
|
||||
### CHANGELOG.md
|
||||
|
||||
1. Ensure `## Unreleased` lists everything shipping.
|
||||
2. Rename to `## vVER — YYYY-MM-DD` (use release day in Asia/Shanghai unless user says otherwise).
|
||||
3. Add a short **Highlights** subsection (install snippet + 3–6 bullets).
|
||||
4. Insert empty:
|
||||
|
||||
```markdown
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
```
|
||||
|
||||
### README.md
|
||||
|
||||
Update every user-visible version pin, typically:
|
||||
|
||||
- Section title `## 现状(vVER)`
|
||||
- `### 如何使用最新 Marqdo(vVER)`
|
||||
- `git checkout vVER`
|
||||
- Release URL `…/releases/tag/vVER`
|
||||
|
||||
Keep install / `ext add` / plugin build instructions accurate for this release.
|
||||
|
||||
### `.cursor/skills/marqdo/SKILL.md`
|
||||
|
||||
- Sync hard rules / feature bullets that this release changes (e.g. WASM, web).
|
||||
- Do **not** dump full CHANGELOG into the skill.
|
||||
- If release-only process changed, point to `.cursor/skills/marqdo-release/`.
|
||||
|
||||
### `public/` (author Markdown sources)
|
||||
|
||||
User tutorials under `public/` (not generated HTML). Update when:
|
||||
|
||||
- New CLI (`marqdo wasm …`, `ext add`, `version`)
|
||||
- New tutorials (browser hello, web client embed)
|
||||
- Version badges / “requires vVER” lines
|
||||
|
||||
Then regenerate HTML for zip/pages:
|
||||
|
||||
```bash
|
||||
./scripts/build-public.sh
|
||||
# Windows: powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
HTML under `public/**/*.html` is typically gitignored — zip still ships from CI `marqdo view output public`.
|
||||
|
||||
### Workflow stub
|
||||
|
||||
Edit `.github/workflows/release.yml` `body:` **Highlights** so the first auto body matches this tag (agent still replaces with full notes via `gh release edit`).
|
||||
|
||||
### Roadmaps / ADRs
|
||||
|
||||
If this release closes a wave: set status Completed in `doc/roadmap/*`; leave ADRs immutable (link from CHANGELOG).
|
||||
|
||||
## Extension checklist (Phase 3 detail)
|
||||
|
||||
Branch policy: `doc/design/vscode-extension-commit.md`.
|
||||
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout vscode-extension
|
||||
# edit vscode-extension/package.json version → VER
|
||||
# npm ci && npm run compile
|
||||
git add vscode-extension/
|
||||
git commit -m "$(cat <<'EOF'
|
||||
vscode-extension: bump to VER for release
|
||||
|
||||
EOF
|
||||
)"
|
||||
git push origin vscode-extension
|
||||
git checkout main
|
||||
```
|
||||
|
||||
Local VSIX only (fallback):
|
||||
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout origin/vscode-extension -- vscode-extension
|
||||
(cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-VER.vsix")
|
||||
# cleanup ignored tree if desired
|
||||
gh release upload "vVER" "dist/marqdo-VER.vsix" --clobber
|
||||
```
|
||||
|
||||
## Defaults (mirror of SKILL)
|
||||
|
||||
| Setting | Default |
|
||||
|---------|---------|
|
||||
| Sync `vscode-extension` to `VER` | yes |
|
||||
| Push main + annotated tag immediately | yes |
|
||||
| Release notes | 中英双语 |
|
||||
| Skip VSIX / docs-only / deploy pages | no |
|
||||
|
||||
Phase 0 asks **only** for the next version unless the user wants overrides.
|
||||
|
||||
## Notes template (中英双语 — default)
|
||||
|
||||
Save as `/tmp/marqdo-vVER-notes.md` then:
|
||||
|
||||
```bash
|
||||
gh release edit "vVER" --notes-file /tmp/marqdo-vVER-notes.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
## Marqdo vVER
|
||||
|
||||
### 亮点 / Highlights
|
||||
|
||||
- **中文** … / **EN** …
|
||||
- …
|
||||
|
||||
### 安装 / Install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout vVER
|
||||
cargo build --release
|
||||
./target/release/marqdo version
|
||||
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
|
||||
# 中文 id:网页 / 智能体 / 量子
|
||||
```
|
||||
|
||||
**浏览器 WASM / Browser WASM**
|
||||
|
||||
```bash
|
||||
marqdo wasm build
|
||||
# → dist/wasm/marqdo_wasm_bg.wasm + marqdo-bridge.js
|
||||
# examples: examples/browser-hello/
|
||||
```
|
||||
|
||||
### 破坏性变更 / Breaking changes
|
||||
|
||||
- 无 / None
|
||||
- …
|
||||
|
||||
### 下载 / Downloads
|
||||
|
||||
| Asset | 内容 / Contents |
|
||||
|-------|-----------------|
|
||||
| `marqdo-*-windows-msvc.exe` | CLI(内置 stdlib) |
|
||||
| `marqdo-*-windows-msvc.zip` | exe + `lib/` + `ext/`(含 native) |
|
||||
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + `.so` |
|
||||
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Win + **Linux 必出**) |
|
||||
| `marqdo-*-stdlib.zip` | 仅 `lib/` |
|
||||
| `marqdo-*-ext.zip` | 官方 `ext/` |
|
||||
| `marqdo-*-source.zip` | 源码快照 |
|
||||
| `marqdo-*.vsix` | VS Code / Cursor 扩展 |
|
||||
| `marqdo-*-public.zip` | 用户文档站 |
|
||||
|
||||
扩展源码分支 / Extension branch: **`vscode-extension`** ([policy](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)).
|
||||
|
||||
### 链接 / Links
|
||||
|
||||
- [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md)
|
||||
- [README](https://github.com/cflmy/marqdo/blob/main/README.md)
|
||||
```
|
||||
|
||||
## Proxy & auth (network recovery)
|
||||
|
||||
Symptoms seen in this project: broken local Clash on `127.0.0.1:7890`, flaky GitHub TLS, `gh` needing token, Cursor agent sandbox with only `lo`.
|
||||
|
||||
### `proxy.cflmy.top` (try this first)
|
||||
|
||||
This machine’s `origin` is typically:
|
||||
|
||||
```
|
||||
https://proxy.cflmy.top/github.com/cflmy/marqdo.git
|
||||
```
|
||||
|
||||
Push / fetch / tag through that remote (HTTPS reverse proxy to GitHub):
|
||||
|
||||
```bash
|
||||
git remote -v # confirm origin uses proxy.cflmy.top
|
||||
git push origin main
|
||||
git push origin vVER
|
||||
git push origin vscode-extension
|
||||
|
||||
# one-shot if origin still points at github.com:
|
||||
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
|
||||
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` / 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
|
||||
|
||||
```bash
|
||||
env | grep -iE 'proxy|PROXY' || true
|
||||
curl -sI --max-time 15 https://github.com | head -5
|
||||
curl -sS --max-time 15 -o /dev/null -w 'proxy=%{http_code}\n' https://proxy.cflmy.top/ || true
|
||||
gh auth status
|
||||
ip -br addr | head -5 # agent may lack enp*; use required_permissions: ["all"]
|
||||
```
|
||||
|
||||
### Fix order
|
||||
|
||||
1. **Unset bad proxy** if connection refused:
|
||||
|
||||
```bash
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
|
||||
# also clear for one git call: git -c http.proxy= -c https.proxy= …
|
||||
```
|
||||
|
||||
2. **Set a working proxy** only if the user provides one (or known working):
|
||||
|
||||
```bash
|
||||
export HTTPS_PROXY=http://HOST:PORT
|
||||
export HTTP_PROXY=http://HOST:PORT
|
||||
```
|
||||
|
||||
3. **Agent Shell**: retry `git push` / `gh` with `required_permissions: ["all"]` (and `full_network` if needed).
|
||||
|
||||
4. **`gh` auth**: if `gh auth status` fails, ask user to `gh auth login` or set `GH_TOKEN` / `GITHUB_TOKEN` for the session — **never commit tokens**. Fallback used in this repo: load password from `git credential fill` (`protocol=https` / `host=github.com`) into `GH_TOKEN` for the session only, then delete the temp env file.
|
||||
|
||||
5. **Git remote**: prefer `https://github.com/cflmy/marqdo.git`; SSH needs keys.
|
||||
|
||||
6. **HK SSH jump (preferred when GitHub is blocked but HK is reachable)** — see next subsection.
|
||||
|
||||
7. **Partial upload**:
|
||||
|
||||
```bash
|
||||
gh release upload "vVER" dist/FILE --clobber
|
||||
```
|
||||
|
||||
8. **Re-run CI** without retagging (if tag already correct):
|
||||
|
||||
```bash
|
||||
gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else fix + new patch tag
|
||||
```
|
||||
|
||||
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
|
||||
|
||||
**Also required before declaring release done:** the push-triggered **`executable-knowledge`** workflow on the release commit / `main` tip must be **success**. Poll with:
|
||||
|
||||
```bash
|
||||
gh run list --workflow=executable-knowledge.yml --branch main --limit 5
|
||||
gh run watch <run-id>
|
||||
```
|
||||
|
||||
A green Release asset job with a red `executable-knowledge` gate is an **incomplete** release — fix the plugin/harness (e.g. `ensure_agent_plugin_built` for agent-dependent EK tests), push `main`, and wait for EK green. Do not skip.
|
||||
|
||||
### HK SSH jump (Paramiko CONNECT)
|
||||
|
||||
**When to use:** local → GitHub fails (timeout / TLS / Clash flaky / reverse-proxy `proxy.cflmy.top` connect drops), but this host can reach an overseas box that has stable GitHub (default `hk.cflmy.de`). Proven path for v0.3.9 push/tag/`gh`.
|
||||
|
||||
**Do not** rely on OpenSSH + `sshpass` here — password auth has hung; use **Paramiko** (`python3-paramiko`).
|
||||
|
||||
**Never** commit the HK root password or tokens. Ask the user for the password (or a key), put it in env / a `600` temp file, scrub after.
|
||||
|
||||
```bash
|
||||
# one-shot password file (example — use the secret the user gave this session)
|
||||
printf '%s' "$HK_PASSWORD_FROM_USER" > /tmp/.hk_ssh_pw && chmod 600 /tmp/.hk_ssh_pw
|
||||
|
||||
export HK_SSH_HOST=hk.cflmy.de # or 83.229.126.119
|
||||
export HK_SSH_USER=root
|
||||
export HK_SSH_PASSWORD_FILE=/tmp/.hk_ssh_pw
|
||||
# optional: HK_JUMP_PORT=18081
|
||||
|
||||
SCRIPT=.cursor/skills/marqdo-release/scripts/push-via-hk-jump.py
|
||||
|
||||
# push / tag / extension (git gets CONNECT proxy + github.com askpass)
|
||||
python3 "$SCRIPT" -- git push origin main
|
||||
python3 "$SCRIPT" -- git push origin vscode-extension
|
||||
python3 "$SCRIPT" -- git push origin vVER
|
||||
|
||||
# gh (sets GH_TOKEN from git credential fill if unset)
|
||||
python3 "$SCRIPT" -- gh release edit vVER --notes-file /tmp/notes.md
|
||||
python3 "$SCRIPT" -- gh run list --workflow=Release --limit 3
|
||||
|
||||
# leave proxy up for manual commands
|
||||
python3 "$SCRIPT" --serve # then: export https_proxy=http://127.0.0.1:18081
|
||||
|
||||
rm -f /tmp/.hk_ssh_pw
|
||||
```
|
||||
|
||||
Script behavior: SSH to HK → local `http://127.0.0.1:$HK_JUMP_PORT` HTTP CONNECT via `direct-tcpip` → run `git`/`gh`/`curl` with that proxy. Git auth uses local `git credential` via `http.extraHeader` (Basic) — **not** `GIT_ASKPASS` (askpass has hung under agent/no TTY). Tokens never go to the jump host disk.
|
||||
|
||||
Optional path reverse-proxy (`https://proxy.cflmy.top/github.com/…` `insteadOf`) may work for short GETs; treat long `git push` failures as a signal to use the HK jump instead of retrying Clash forever.
|
||||
## Local Windows fallback
|
||||
|
||||
```powershell
|
||||
powershell -File ./scripts/release-full.ps1 -Tag vVER -Upload
|
||||
# -SkipVsix / -SkipPublic / -DeployPages as needed
|
||||
```
|
||||
|
||||
Also: `scripts/release-windows.ps1`, `scripts/publish-release.py` if present.
|
||||
|
||||
## Commit message style
|
||||
|
||||
```text
|
||||
release: vVER — <highlight>
|
||||
|
||||
```
|
||||
|
||||
Extension:
|
||||
|
||||
```text
|
||||
vscode-extension: bump to VER for release
|
||||
|
||||
```
|
||||
|
||||
## Pre-tag test suggestions
|
||||
|
||||
Minimum:
|
||||
|
||||
```bash
|
||||
cargo test --test gold structure_hello
|
||||
./target/release/marqdo version # after cargo build --release
|
||||
```
|
||||
|
||||
Stronger (time permitting):
|
||||
|
||||
```bash
|
||||
cargo test --test gold
|
||||
cargo test -p marqdo-wasm -- --nocapture # if wasm tests exist
|
||||
# optional Node: node tests/wasm/smoke.mjs after marqdo wasm build
|
||||
```
|
||||
|
||||
## Ask-user prompt (copy)
|
||||
|
||||
```text
|
||||
版本探测结果:
|
||||
- Cargo.toml: A.B.C
|
||||
- crates/marqdo-wasm: …
|
||||
- 最新 git tag: v…
|
||||
- 最新 GitHub Release: v…
|
||||
- CHANGELOG Unreleased: 有 / 无(摘要:…)
|
||||
|
||||
请指定下一个版本号(例如 0.3.2)。
|
||||
默认(无需确认):同步 vscode-extension 同号、立刻 push tag 发版、发布说明中英双语。
|
||||
若要改默认请一并说明。
|
||||
```
|
||||
Use [the executable release entry](../../../skills/marqdo-release/index.mq.md) and [its maintained task reference](../../../skills/marqdo-release/reference.md). File authoring, mode rules, native service/process boundaries and recovery live with the actual mq.md tasks. Do not reconstruct the former Python or terminal playbook from historical copies.
|
||||
@@ -1,253 +1,62 @@
|
||||
---
|
||||
name: marqdo
|
||||
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, 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.
|
||||
description: Author, run and review readable Marqdo programs, libraries and executable knowledge. Use for .mq.md, marqdo call, Document/Endpoint/Resource web projects and quantum tools; read the executable programming and development handbooks.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
# Marqdo
|
||||
|
||||
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.
|
||||
<!-- CORE_SYNTAX_V2.1: keep this card within the first 1200 body characters -->
|
||||
|
||||
<!-- CORE_SYNTAX_V2.1: must stay at the top so skill_brief budgets never truncate it -->
|
||||
## CORE SYNTAX
|
||||
|
||||
## CORE SYNTAX (v2.1 Occlusion — mandatory)
|
||||
Occlusion is the current default. `**…**` executes a statement; `*…*` returns.
|
||||
Use `[intent](actual code)` in an executable position: the label is prose and
|
||||
only its payload executes. Empty parentheses are a pending None stub.
|
||||
Read collections with `access(coll, key)`. Classic indexing is only for explicit
|
||||
legacy sources and migration. Reading narrative references never runs effects.
|
||||
|
||||
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
|
||||
|
||||
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
|
||||
2. **`**…**` = code / return expression.** `*…*` = statement (bind / expr). Closing markers touch the last token (no trailing space).
|
||||
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
|
||||
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
|
||||
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
|
||||
6. **Import / call:** frontmatter `import:` / `导入:`; call `lib.member`. One language (EN or ZH) per file.
|
||||
7. **Control flow:** `#` object/type, `##`+ function, `+` params, `1.`/`2.` branches, `-` loops, `N. *` else. No invented `if`/`for`/`def`/`return` keywords.
|
||||
8. **Prose vs code:** blank line separates comment paragraphs from executable lines.
|
||||
9. **GFM tables** for data; prefer `table.put` over `json.set` chains. `ext/**` never calls `host_*`.
|
||||
10. Body narrative `[描述](target)` is lazy (NarrativeRef) — reading does not execute side effects.
|
||||
|
||||
| Marker | Meaning (v2.1) |
|
||||
|--------|----------------|
|
||||
| `#` / `##`+ | Object/type · function/method |
|
||||
| `*…*` | Statement |
|
||||
| `**…**` | Return / code expression |
|
||||
| `[描述](payload)` | Occlusion step (payload executes) |
|
||||
| Marker | Meaning |
|
||||
|---|---|
|
||||
| `**…**` | Statement (assign / call / expression) |
|
||||
| `*…*` | Return |
|
||||
| `[intent](payload)` | Readable intent with executable payload |
|
||||
| `access(c, k)` | Collection read |
|
||||
| `> fn …` | Call |
|
||||
| GFM table | Collection literal |
|
||||
| `- [intent](for items as item)` | Explicit traversal |
|
||||
| `1.` / `2.` | Branches; numbered * is else |
|
||||
| GFM table | Data: one column list, one row record, @ row records |
|
||||
|
||||
Canonical: `doc/design/core-surface.md`, `doc/design/document-native-development-guide.md`. Deeper tables: [reference.md](reference.md). Patterns: [examples.md](examples.md). Authoring craft: [marqdo-dev](../marqdo-dev/SKILL.md). Release: [marqdo-release](../marqdo-release/SKILL.md).
|
||||
Read [the executable programming guide](../../../doc/library-development.mq.md)
|
||||
before authoring. Its actual callable examples demonstrate inline computation,
|
||||
structured results, defaults and recoverable native file reads. Use
|
||||
[the development entry](../../../skills/marqdo-dev/index.mq.md) and its file tools for source
|
||||
work, and [the release entry](../../../skills/marqdo-release/index.mq.md) for an authorized
|
||||
release. These mq.md files are the working instructions and tools; do not rebuild
|
||||
a parallel command playbook in SKILL.md.
|
||||
|
||||
Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md).
|
||||
Call the actual file and heading with `marqdo call`. In a source checkout use
|
||||
the built `target/debug/marqdo`; prepare its engineering plugin through the
|
||||
development entry. Large structured inputs use --args-json FILE or stdin;
|
||||
JSON strings stay literal during call-session replay. --require-ok makes failed
|
||||
Results stop external automation while preserving their returned evidence.
|
||||
Read each function's parameter/return tables and effect contract before calling.
|
||||
|
||||
## Hard rules (do not violate)
|
||||
Author programs as readable explanations: useful narrative exceeds half of
|
||||
each callable unit; parameter and return tables immediately follow its heading;
|
||||
inline assignments, actions and returns explain their purpose. Standard libraries
|
||||
remain single-file handbooks. Multi-file projects and extensions use index.mq.md.
|
||||
GFM describes data, public helpers describe operations, and components recursively
|
||||
split web layouts until their content leaves are ordinary Markdown.
|
||||
|
||||
1. Obey **CORE SYNTAX** above — Occlusion is default; do not emit Classic index links.
|
||||
2. **Identifiers:** params `` + `name` ``; inside `*…*` / `**…**` bare ids are variables. Quote text literals. Standalone `>` calls: backticks where bare would be text.
|
||||
3. **Structure lines** (`#` `>` `+` `-` `|`) are not wrapped in italics.
|
||||
4. **Paths:** bare `/` in expressions is division; in call args / table cells unspaced `a/b` is path text. Ratios as text need quotes (`"1/5"`).
|
||||
5. End side-effect-only helpers with `*None*` / `*空*` / `**` / `****` when the outer function continues. Lone `---` is a thematic break, not function end.
|
||||
6. **`ext/**` never calls `host_*`.** Prefer tables over `json.set` / `json.append`.
|
||||
7. **One language per file.** Sandbox trial before promoting Agent-generated trees.
|
||||
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
|
||||
Native Marqdo capabilities handle file reading/writing, tables, parsing, hashing
|
||||
and network reads. Add an extension for a reusable capability gap or call an
|
||||
explicit existing external tool with argument arrays. Keep decisions, retries
|
||||
and the execution flow in mq.md. Do not generate Python or shell programs for
|
||||
already available native operations. OS processes and plugins retain their OS
|
||||
authority; an fs-root does not sandbox their own access.
|
||||
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
Chinese builtins (same functions, no import):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好
|
||||
```
|
||||
|
||||
## Functions, calls, end-body
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
*None*
|
||||
```
|
||||
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped).
|
||||
- In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`).
|
||||
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
```markdown
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
Imports use nested YAML `import:` (`导入:` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
clock: lib/time.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*xs = > text.split value="a,b,c" sep=","*
|
||||
> print text=`xs`
|
||||
*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` (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`/`非`.
|
||||
|
||||
Stdlib map: [reference.md](reference.md).
|
||||
|
||||
## Official extension: `ext/agent` (document-driven)
|
||||
|
||||
Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --release -p marqdo_plugin_agent`.
|
||||
|
||||
**Constitution (do not dilute):**
|
||||
|
||||
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
|
||||
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
|
||||
|
||||
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/) · [agent-sandbox-okf](../../examples/agent-sandbox-okf/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · optimize O1–O5: [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
|
||||
**Sandbox (O1):** `import sandbox:ext/ai/sandbox.mq.md` · `agent.trial` / `智能体.试跑` · `run`/`step` take `sandbox=` / `沙盒=` (default `False`). Profile caps are tables via `sandbox.profile`. Gold: `tests/ext/agent-sandbox-optin.mq.md`.
|
||||
|
||||
## Official extension: `ext/web` (Document / Endpoint / Resource)
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). 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`
|
||||
|
||||
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)
|
||||
|
||||
Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`, then **`marqdo ext add quantum` again** so view loads the new `libquantum.so` (stale plugin = old black/white circuits).
|
||||
|
||||
- EN: `import quantum:ext/quantum/quantum.mq.md`
|
||||
- ZH: `导入 量子:ext/quantum/量子.mq.md`
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program; quote draw string args (`kind="…"`, `theme="…"`).
|
||||
|
||||
**Core:** `# circuit` / `# gate` / `# density` — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`.
|
||||
|
||||
**Q7 linear algebra:** `density`, `partial_trace`, `eig`, `expect` (Pauli string, left=high bit), `purity`, `kron`, `schmidt`, `fidelity`.
|
||||
|
||||
**Draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch`.
|
||||
|
||||
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
|
||||
|
||||
```markdown
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="probs" theme="light"*
|
||||
```
|
||||
|
||||
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/).
|
||||
|
||||
## Foreign kernels (v1.5.0)
|
||||
|
||||
`lib/foreign` is now a full foreign-kernel surface, not only `run`:
|
||||
|
||||
- `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
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
4. On `path:line:col: message`, fix that span; re-run until exit 0.
|
||||
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
|
||||
## Anti-patterns (common model mistakes)
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| `**Hello**` to print | `> print text=Hello` |
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
|
||||
| Forgetting empty return after nested `##` helper when outer continues | Add `*None*` / `**` / `****` (not `---`) |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
|
||||
| `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 |
|
||||
| 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`) |
|
||||
|
||||
## Checklist before finishing
|
||||
|
||||
- [ ] File ends with `.mq.md`
|
||||
- [ ] Print via `print` / `打印`, not bold
|
||||
- [ ] Blank lines separate comment paragraphs from code
|
||||
- [ ] `# main` exists when the file is an entry program
|
||||
- [ ] Nested side-effect helpers ended with `*None*` / `**` / `****` when the outer function continues
|
||||
- [ ] Imports and call names share the same language file
|
||||
- [ ] Data shaped as **GFM tables** (or short helpers) — no `json.set` / `json.append` glue
|
||||
- [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored
|
||||
- [ ] Browser client: `lib/browser` + tables when returning effects
|
||||
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
Use the current [web entry](../../../ext/web/index.mq.md) for Document, Endpoint and
|
||||
Resource artifacts, or [quantum entry](../../../ext/quantum/index.mq.md) for circuit
|
||||
workflows. Do not restore removed compose_* or app.configure APIs. Preserve
|
||||
intentional fixtures and [classic migration context](migration-classic.md).
|
||||
Validate the real calls and error paths; a narrative ratio or uploaded asset
|
||||
alone is never functional evidence.
|
||||
@@ -1,479 +1,3 @@
|
||||
# Marqdo examples (AI)
|
||||
# Marqdo executable examples
|
||||
|
||||
v0.3: `**…**` = code (assign / call); `*…*` = return. Prefer `[key](coll)` over footnote get. Bracket calls: `礼貌 [问候] x`.
|
||||
|
||||
## 1. Hello (English)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
## 2. Hello (Chinese builtins)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
## 3. Function + named call + empty return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
Greeting via a nested function:
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
*None*
|
||||
```
|
||||
|
||||
Or end with a whole-line empty bold return: `**` / `****`. Lone `---` is a thematic break (skipped), not function end.
|
||||
|
||||
## 4. Bindings and return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**a = 2**
|
||||
**b = add_one n=`a`**
|
||||
**打印 内容=`b`**
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
## 5. Branch with else
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**n = 0**
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## 6. Foreach loop
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
|
||||
- [果](篮子)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 6b. Map table + link-index get
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
|
||||
**种 = [苹果](分类)**
|
||||
**打印 内容=`种`**
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
|
||||
**第一 = [1](篮子)**
|
||||
**打印 内容=`第一`**
|
||||
```
|
||||
|
||||
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Prefer `[key](coll)` (lists are 1-based). Legacy `` coll[^key] `` still parses. Foreach on a map walks **keys**.
|
||||
|
||||
Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of maps (marker column excluded):
|
||||
|
||||
```markdown
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
|
||||
**名 = [品名]([1](订单))**
|
||||
```
|
||||
|
||||
## 6c. Bracket-marked call + modifiers
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**打印 内容=(礼貌 [问候] "Marqdo")**
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
|
||||
**出 = `礼貌` + ", " + `谁` + "!"**
|
||||
*出*
|
||||
```
|
||||
|
||||
`礼貌 [问候] …` → `礼貌=True`. `]` immediately followed by `(` is index, not a call.
|
||||
|
||||
## 6d. Browser effects — tables + lib/browser (not json.set)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
browser: lib/browser.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 |
|
||||
|---|--------|------|------|
|
||||
| 1 | "#bump" | click | bump |
|
||||
|
||||
**`wire`**
|
||||
|
||||
## bump
|
||||
**count = count + 1**
|
||||
**label = str count**
|
||||
**> browser.set_text sel="#count" text=label**
|
||||
```
|
||||
|
||||
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
|
||||
|
||||
## 6e. Agent / LLM result maps — GFM first (positive)
|
||||
|
||||
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
## step_ok
|
||||
+ `task`
|
||||
+ `reply`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | result |
|
||||
|--------|------|--------|
|
||||
| ok | `task` | `reply` |
|
||||
|
||||
*out*
|
||||
|
||||
## step_err
|
||||
+ `task`
|
||||
+ `err`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | error |
|
||||
|--------|------|-------|
|
||||
| error | `task` | `err` |
|
||||
|
||||
*out*
|
||||
|
||||
## soft_http_pack
|
||||
+ `msg`
|
||||
+ `usage0`
|
||||
|
||||
**empty_tc = > table.empty_list**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: split demo
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**parts = [text.str_split] s="a,b,c" sep=","**
|
||||
**打印 内容=`parts`**
|
||||
```
|
||||
|
||||
## 7b. Mid M1 — regex + encoding (no plugin)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
re: lib/re.mq.md
|
||||
enc: lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**`ok` = [re.is_match] text="a@b.c" pattern="@"**
|
||||
**`b64` = [enc.base64_encode] text="hi"**
|
||||
**打印 内容=`ok`**
|
||||
**打印 内容=`b64`**
|
||||
```
|
||||
|
||||
## 7c. Mid M6 — log + uuid
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
log: lib/log.mq.md
|
||||
uuid: lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> log.info text="start"
|
||||
> log.set_level level="debug"
|
||||
> log.debug text="detail"
|
||||
**id = [uuid.v4]**
|
||||
**打印 内容=`id`**
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
This whole paragraph is a comment, including lines that look like code:
|
||||
**not_executed = 1**
|
||||
> print text=also still comment
|
||||
|
||||
After a blank line, code runs:
|
||||
|
||||
> print text=this runs
|
||||
```
|
||||
|
||||
## 9. Frontmatter import only
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**t = > num value=3.5**
|
||||
**打印 内容=`t`**
|
||||
```
|
||||
|
||||
## 10. Object handle + method
|
||||
|
||||
See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
|
||||
|
||||
## 10b. Object inheritance
|
||||
|
||||
```markdown
|
||||
# Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
**msg = "Hello, `who`!"**
|
||||
*msg*
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
**msg = "HELLO, `who`!"**
|
||||
*msg*
|
||||
```
|
||||
|
||||
`_type` stays the most specific name (`Loud`). Methods walk the base chain; same-name `##` on the child overrides. **No implicit super** — if the child needs parent fields, call the parent explicitly:
|
||||
|
||||
```markdown
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
**self = > Parent name=`name`**
|
||||
**self = [table.put] in=`self` at="extra" value=1**
|
||||
*self*
|
||||
```
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
agent: ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
**ws = > agent**
|
||||
**n = > `ws`.ensure_layout**
|
||||
**打印 内容=`n`**
|
||||
```
|
||||
|
||||
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
|
||||
|
||||
## 12. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bare bold that is not code-shaped (decorative OK); do not use bold/italic as print
|
||||
**Hello**
|
||||
|
||||
# BAD — Python control keywords
|
||||
if x > 0:
|
||||
print(x)
|
||||
|
||||
# BAD — wrapping a call in italics as if it were a statement
|
||||
*> print text=hi*
|
||||
|
||||
# BAD — old branch syntax (removed)
|
||||
+ `x` > 0
|
||||
|
||||
# GOOD — ordered list arms
|
||||
1. `x` > 0
|
||||
> print text=pos
|
||||
2. *
|
||||
> print text=other
|
||||
|
||||
# GOOD — another independent branch (restart at 1.)
|
||||
1. `y` > 0
|
||||
> print text=y-pos
|
||||
2. *
|
||||
> print text=y-other
|
||||
|
||||
# GOOD — print / return
|
||||
**打印 内容="hi"**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
## 13. Dynamic site (ext/web, minimal)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: hello-site
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
db: db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`shell` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav | |
|
||||
|
||||
`main` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | posts.title | |
|
||||
| body | posts.summary | |
|
||||
|
||||
**store = > db.open**
|
||||
**css = "body{font-family:sans-serif}"**
|
||||
**page = > web.page title="Hello"**
|
||||
**page = > page.compose_components components=`shell`**
|
||||
**page = > page.compose_main main=`main`**
|
||||
**page = > page.css css=`css`**
|
||||
**app = > web.app page=`page` port=8080**
|
||||
**app = > app.static prefix="/static" dir="static"**
|
||||
> listen app=`app`
|
||||
```
|
||||
|
||||
- Import `ext/web/web.mq.md` **or** `ext/web/网页.mq.md` — not both; match API language to the file.
|
||||
- Full blog/CMS patterns: `examples/marqdo-blog/` (routes, SEO, RSS, auth, upload, WS).
|
||||
- Run after `marqdo ext add web` and building `marqdo_plugin_web`.
|
||||
|
||||
## 14. Quantum entanglement lab (ext/quantum Q7/Q8)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
**qc = > quantum.circuit qubits=2 steps=`steps`**
|
||||
**rho = > `qc`.density**
|
||||
**red = > `rho`.partial_trace keep=0**
|
||||
**sch = > `qc`.schmidt cut=1**
|
||||
**_ = > `qc`.draw kind="circuit" theme="dark"**
|
||||
**_ = > `qc`.draw kind="hinton"**
|
||||
**打印 内容=`red`**
|
||||
```
|
||||
|
||||
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
|
||||
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
|
||||
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
|
||||
|
||||
## 15. Linear algebra (ext/linalg)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**`A` = > la.symbol name="A" rows=2 cols=2**
|
||||
**`B` = > la.symbol name="B" rows=2 cols=2**
|
||||
**`C` = `A` + `B`**
|
||||
**`P` = `A` * `B`**
|
||||
```
|
||||
|
||||
Prefer:
|
||||
|
||||
```markdown
|
||||
**`env` = > la.declare table=`shapes`**
|
||||
**`P` = [A](env) * [B](env)**
|
||||
**`t` = > `P`.T_ascii**
|
||||
```
|
||||
|
||||
- Infix `+` / `-` / `*`;`ascii` / `T_ascii` 默认化简(`raw=True` 可关)。
|
||||
- Formula-doc design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
- Examples: `examples/linalg-transpose/`, `examples/linalg-svd/`, `examples/linalg-least-squares/`.
|
||||
Read [the maintained discovery note](../../../skills/marqdo/examples.md) and its actual mq.md source entries. The [programming guide](../../../doc/library-development.mq.md) is authoritative; source examples and real workflow tests stay together rather than being copied into SKILL reference fences.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Classic migration
|
||||
|
||||
Read [the maintained migration context](../../../skills/marqdo/migration-classic.md) and [the executable programming guide](../../../doc/library-development.mq.md). Historical fixtures retain explicit classic markup; new code uses readable occlusion and access(collection, key).
|
||||
@@ -1,206 +1,3 @@
|
||||
# Marqdo reference (AI)
|
||||
# Marqdo executable reference
|
||||
|
||||
Load this when you need stdlib names, CLI, or edge cases. Core rules stay in [SKILL.md](SKILL.md).
|
||||
|
||||
## CLI
|
||||
|
||||
```text
|
||||
marqdo --version
|
||||
marqdo run FILE.mq.md
|
||||
marqdo run FILE.mq.md --backend bytecode
|
||||
marqdo view PATH # docs browser, default port 7429
|
||||
marqdo debug PATH # debugger UI, default port 7430
|
||||
marqdo catalog PATH -o .marqdo
|
||||
marqdo ext list
|
||||
marqdo ext add llm|agent|web|quantum|linalg
|
||||
marqdo ext remove llm|agent|web|quantum|linalg
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.3 surface:** `**…**` = code; `*…*` = return; parameters `` + `name` `` (or prose-inferred); branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) ``; get `` [key](coll) ``; bracket calls `` mod [fn] args ``. See `doc/design/markdown-mapping-v0.3.md`.
|
||||
|
||||
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
|
||||
|
||||
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `import llm:ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
|
||||
|
||||
## Builtins (no import)
|
||||
|
||||
| EN | ZH | Role |
|
||||
|----|----|------|
|
||||
| `print` | `打印` | stdout; arg `text` / `内容` |
|
||||
| `input` | `输入` | one line; arg `prompt` / `提示` |
|
||||
| `len` | `长度` | length; arg `value` / `值` |
|
||||
| `str` | `文本` | to text; arg `value` / `值` |
|
||||
| `int` | `整数` | to int; arg `value` / `值` |
|
||||
|
||||
Keywords (not variable names): `True`/`真`, `False`/`假`, `None`/`空`, `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
## Standard library files
|
||||
|
||||
Import one file; use **that** file’s function names.
|
||||
|
||||
| EN import | ZH import | Typical APIs (EN / ZH) |
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
|
||||
| `lib/re.mq.md` | `lib/正则.mq.md` | Mid:`is_match`/`find`/`replace`/… |
|
||||
| `lib/encoding.mq.md` | `lib/编码.mq.md` | Mid:base64/hex |
|
||||
| `lib/path.mq.md` | `lib/路径.mq.md` | Mid:join/normalize/… |
|
||||
| `lib/hash.mq.md` | `lib/哈希.mq.md` | Mid:sha256/hmac/… |
|
||||
| `lib/secrets.mq.md` | `lib/机密.mq.md` | Mid:token_hex/urlsafe |
|
||||
| `lib/csv.mq.md` | `lib/逗号表.mq.md` | Mid:parse/stringify |
|
||||
| `lib/cli.mq.md` | `lib/命令行.mq.md` | Mid:`parse` flags |
|
||||
| `lib/log.mq.md` | `lib/日志.mq.md` | Mid:level-filtered one-line logs |
|
||||
| `lib/uuid.mq.md` | `lib/标识.mq.md` | Mid:UUID v4 |
|
||||
| `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM client effect helpers(GFM + `set_text`/`canvas`/…;见 marqdo-dev) |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
| `lib/plugin.mq.md` | `lib/插件.mq.md` | load native ABI plugins (`doc/design/ext-abi.md`) |
|
||||
| `lib/time.mq.md` | `lib/时间.mq.md` | time/format |
|
||||
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) helpers (+ optional headers) |
|
||||
| `lib/json.mq.md` | (see design) | **parse / stringify / quote only** — not a dict builder |
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
|
||||
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
|
||||
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | formula MatExpr + factorize/draw — see **ext/linalg** below |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
## ext/web (dynamic sites)
|
||||
|
||||
Install: `marqdo ext add web` (`网页`). Native: `cargo build --release -p marqdo_plugin_web`.
|
||||
|
||||
| EN import | ZH import | Core types |
|
||||
|-----------|-----------|------------|
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | `# page` `# style` `# db` `# form` `# app` `# auth` `# cache` `# storage` |
|
||||
|
||||
| Area | EN methods (representative) | Notes |
|
||||
|------|----------------------------|-------|
|
||||
| Page | `compose_components`, `compose_main`, `render`, `meta`, `paginate` | GFM tables; cells are literal path strings |
|
||||
| DB | `init`, `insert`, `select`, `paginate`, `get`, `update`, `delete`, `migrate`, `fts`, `search`, `count`, `事务`/`txn` | init supports `unique`/`index`/`fk`; auto `created_at`/`updated_at` |
|
||||
| App | `route`, `static`, `configure`, `listen`, `auth`, `gate`, `upload`, `download`, `gallery`, `route_rss`, `redirect`, `error_page`, `sitemap`, `robots` | W0–W7 + P3 complete |
|
||||
| Auth | `login`, `check`, `logout`, `hash_password` | argon2 + CSRF + SQLite sessions; `role` for RBAC |
|
||||
|
||||
Drivers (Postgres / Redis / S3): `db url=postgres://…`, `cache url=memory:`, `storage url=file:…` — see `doc/design/ext-web-drivers.md`.
|
||||
|
||||
Example project: `examples/marqdo-blog/`. Capability matrix: `doc/design/web-net-capabilities.md`.
|
||||
|
||||
## ext/quantum (circuits + Q7/Q8)
|
||||
|
||||
Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`, then re-run `ext add` so view picks up the new `.so`.
|
||||
|
||||
| EN import | ZH import | Core types |
|
||||
|-----------|-----------|------------|
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | `# circuit` `# gate` `# density` |
|
||||
|
||||
| Area | EN APIs | Notes |
|
||||
|------|---------|-------|
|
||||
| Circuit | `h`/`cx`/…, `simulate`, `probabilities`, `run`, `draw`, `noise` | `steps=` GFM table; ≤12 qubits |
|
||||
| Gate | `matrix`, `matches_matrix`, `draw` | named or `matrix=` custom unitary |
|
||||
| Density (Q7) | `purity`, `partial_trace`, `eig`, `expect`, `draw` | ≤6 qubits for dense ρ |
|
||||
| Free (Q7) | `kron`, `schmidt`, `fidelity` | top-level on import bind |
|
||||
| Draw kinds | `circuit\|probs\|bloch\|hinton\|city\|density\|paulivec\|qsphere\|multibloch` | quote `kind="…"` |
|
||||
| Themes (Q8) | `theme="dark"\|"light"\|"bw"` (ZH `主题=`) | default **dark**; circuit/probs/bloch themed; SVG `data-theme` |
|
||||
|
||||
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
|
||||
|
||||
## ext/linalg (formula-first linear algebra)
|
||||
|
||||
Install: `marqdo ext add linalg` (`线性代数`). Native: `cargo build --release -p marqdo_plugin_linalg`, then re-run `ext add`.
|
||||
|
||||
| EN import | ZH import | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | Top-level `symbol`/`mul`/`factorize`/`draw` |
|
||||
|
||||
Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc/design/ext-linalg.md` · formula-doc: `doc/design/ext-linalg-formula-doc.md` · roadmap: `doc/roadmap/ext-linalg.md`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*_svg = > plot formula=`f` var=x min=-3 max=3*
|
||||
```
|
||||
|
||||
Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only `$$` without binding is display, not assignment.
|
||||
|
||||
## Foreign (Python example)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
```
|
||||
|
||||
Lines starting with `` ` `` can be code (binding). Keep a blank line before/after fences per comment rules.
|
||||
|
||||
## Function-end details
|
||||
|
||||
| Form | Effect |
|
||||
|------|--------|
|
||||
| Lone `---` or `***` (≥3 same chars) at function body top level | End function; no return value |
|
||||
| `****` or empty bold | Return `None` and end body |
|
||||
| `**expr**` | Return `expr`; does **not** by itself cut off later sibling statements — still use HR or shallower heading |
|
||||
|
||||
File-leading paired `---` is frontmatter only; body `---` is not frontmatter.
|
||||
|
||||
## Call arguments
|
||||
|
||||
- Named: `> greet who=World`
|
||||
- Positional: `> greet World`
|
||||
- Spaces in values: allowed in named forms as in docs (`who=marqdo user`)
|
||||
- Inline call in statement: `` *`n` = > len value=`s`* ``
|
||||
|
||||
See `doc/design/call-arguments.md`.
|
||||
|
||||
## Identifiers
|
||||
|
||||
- Variables: `` `name` ``
|
||||
- Comparisons: `==` `>` `<` `>=` `<=`
|
||||
- Do not use keyword tokens as names
|
||||
|
||||
## Design docs (repo)
|
||||
|
||||
| Doc | Topic |
|
||||
|-----|--------|
|
||||
| `doc/design/markdown-mapping-v0.3.md` | Syntax constitution (runtime) |
|
||||
| `doc/design/markdown-mapping.md` | Legacy v0.2 notes |
|
||||
| `doc/design/objects.md` | `#` objects / `##` methods |
|
||||
| `doc/design/keywords.md` | Builtins / keywords |
|
||||
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
|
||||
| `doc/design/stdlib-i18n.md` | EN/ZH lib files |
|
||||
| `doc/design/stdlib-modules.md` | L1 modules including plugin |
|
||||
| `doc/design/ext-abi.md` | Native C ABI v1 |
|
||||
| `doc/design/ext-llm.md` | `ext/llm` |
|
||||
| `doc/design/ext-agent.md` | `ext/agent` agent **framework** (layout shipped; LLM orchestration roadmap) |
|
||||
| `doc/design/ext-cli.md` | `marqdo ext list/add/remove` |
|
||||
| `doc/design/ext-web.md` | `ext/web` dynamic sites (author API) |
|
||||
| `doc/design/web-net-capabilities.md` | ext/web capability matrix (W0–W7 + P3) |
|
||||
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
|
||||
| `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG |
|
||||
| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) |
|
||||
| `doc/design/ext-linalg.md` | `ext/linalg` formula MatExpr + factorize/draw |
|
||||
| `doc/design/ext-linalg-formula-doc.md` | 公式文档面:跑通即正确 · 代数/计算两面 |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
Read [the maintained discovery note](../../../skills/marqdo/reference.md) and its actual mq.md source entries. The [programming guide](../../../doc/library-development.mq.md) is authoritative; source examples and real workflow tests stay together rather than being copied into SKILL reference fences.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Multipart protocol examples retain required CRLF bytes in every checkout.
|
||||
examples/web-net-site/components/content/multipart.txt -text whitespace=cr-at-eol
|
||||
examples/web-net-site-zh/components/content/multipart.txt -text whitespace=cr-at-eol
|
||||
@@ -0,0 +1,46 @@
|
||||
name: Build cinematic Markdown-to-execution video
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [docs/markdown-execution-cinematic-v2]
|
||||
paths:
|
||||
- "scripts/render-markdown-execution-promo.py"
|
||||
- ".github/workflows/build-markdown-execution-video.yml"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
video:
|
||||
if: github.ref_name == 'docs/markdown-execution-cinematic-v2'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 25
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: true
|
||||
- name: Prepare fonts, Chrome and Python tools
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y -qq ffmpeg fonts-noto-cjk
|
||||
python -m pip install --quiet pillow numpy markdown-it-py selenium
|
||||
google-chrome --version
|
||||
- name: Render promo video from two original images and Marqdo source
|
||||
run: python scripts/render-markdown-execution-promo.py
|
||||
- name: Check resulting video
|
||||
run: |
|
||||
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4
|
||||
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg
|
||||
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution.srt
|
||||
ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height -of json assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4
|
||||
- name: Commit compiled video, poster and subtitles
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git add assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4 \
|
||||
assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg \
|
||||
assets/marketing/marqdo-2.7.1-markdown-to-execution.srt \
|
||||
assets/marketing/marqdo-procurement-standard-markdown.png
|
||||
git diff --cached --quiet || git commit -m "docs: publish cinematic Markdown-to-execution promotional film"
|
||||
git push origin HEAD:docs/markdown-execution-cinematic-v2
|
||||
@@ -0,0 +1,48 @@
|
||||
name: capture-procurement-marketing-assets
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [docs/executable-skill-showcase-271]
|
||||
paths:
|
||||
- "scripts/capture-procurement-showcase.py"
|
||||
- ".github/workflows/capture-procurement-marketing.yml"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
capture:
|
||||
if: github.ref_name == 'docs/executable-skill-showcase-271'
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: true
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.11"
|
||||
- name: Prepare Chrome, Chinese fonts and Python imaging
|
||||
run: |
|
||||
python -m pip install --quiet pillow selenium
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y -qq fonts-noto-cjk
|
||||
google-chrome --version
|
||||
- name: Download Marqdo v2.7.1 Linux release
|
||||
run: |
|
||||
mkdir -p /tmp/marqdo-marketing-cli
|
||||
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo-marketing.zip
|
||||
unzip -q /tmp/marqdo-marketing.zip -d /tmp/marqdo-marketing-cli
|
||||
BIN="$(find /tmp/marqdo-marketing-cli -type f -name marqdo | head -n 1)"
|
||||
test -n "$BIN"
|
||||
chmod +x "$BIN"
|
||||
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
|
||||
- name: Record real command outputs and capture real View
|
||||
run: python scripts/capture-procurement-showcase.py --cli "$CLI_BIN"
|
||||
- name: Commit reproducible promotional assets
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git add assets/marketing/procurement-cli.gif assets/marketing/procurement-view.png
|
||||
git diff --cached --quiet || git commit -m "docs: capture live procurement CLI GIF and View screenshot"
|
||||
git push origin HEAD:docs/executable-skill-showcase-271
|
||||
@@ -0,0 +1,64 @@
|
||||
# Independent extension sources and native libraries; no CLI/PPA publication.
|
||||
name: Extension Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "ext-v*"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
windows:
|
||||
runs-on: windows-latest
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: "1.23.x"
|
||||
- name: Install cgo toolchain
|
||||
run: choco install mingw -y
|
||||
- name: Build the handbook CLI and native capabilities
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
|
||||
bash scripts/build-web-plugin.sh
|
||||
- name: Build and validate the runner's exact pack bytes
|
||||
shell: pwsh
|
||||
run: ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.write,environment.read --fs-root . --require-ok --json
|
||||
- name: Attach source and Windows native packs without replacement
|
||||
shell: pwsh
|
||||
run: ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
|
||||
|
||||
linux:
|
||||
runs-on: ubuntu-latest
|
||||
needs: windows
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: "1.23.x"
|
||||
- name: Install ZIP and cgo tools
|
||||
run: sudo apt-get update && sudo apt-get install -y zip gcc libc6-dev
|
||||
- name: Build the handbook CLI and native capabilities
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
|
||||
bash scripts/build-web-plugin.sh
|
||||
- name: Build and validate the runner's exact pack bytes
|
||||
run: target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.write,environment.read --fs-root . --require-ok --json
|
||||
- name: Attach Linux native pack without replacement
|
||||
run: target/release/marqdo call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
|
||||
@@ -0,0 +1,28 @@
|
||||
name: procurement-example-smoke
|
||||
on:
|
||||
push:
|
||||
branches: [main, docs/executable-skill-showcase-271]
|
||||
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
|
||||
pull_request:
|
||||
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
|
||||
jobs:
|
||||
smoke:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Fetch released v2.7.1 Linux CLI
|
||||
run: |
|
||||
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo.zip
|
||||
unzip -q /tmp/marqdo.zip -d /tmp
|
||||
BIN="$(find /tmp -type f -name marqdo | head -n 1)"
|
||||
test -n "$BIN"
|
||||
chmod +x "$BIN"
|
||||
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
|
||||
- name: Check and run procurement skill
|
||||
run: |
|
||||
"$CLI_BIN" check examples/procurement/index.mq.md
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 查询余额 已花费=120 --json
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/allowed.json
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/denied.json
|
||||
grep -q '本地模拟' /tmp/allowed.json
|
||||
grep -q '采购金额超过' /tmp/denied.json
|
||||
@@ -0,0 +1,43 @@
|
||||
name: Build Marqdo promotional video
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [docs/promo-video-271]
|
||||
paths:
|
||||
- scripts/make-procurement-promo.py
|
||||
- .github/workflows/promo-video.yml
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build-video:
|
||||
if: github.ref_name == 'docs/promo-video-271'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: true
|
||||
- name: Prepare video environment
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -qq -y ffmpeg fonts-noto-cjk
|
||||
python -m pip install --quiet --disable-pip-version-check pillow numpy
|
||||
ffmpeg -version | head -n 2
|
||||
- name: Compose 32-second Marqdo video
|
||||
run: python scripts/make-procurement-promo.py
|
||||
- name: Verify deliverable
|
||||
run: |
|
||||
test -s assets/marketing/marqdo-2.7.1-promo.mp4
|
||||
test -s assets/marketing/marqdo-2.7.1-poster.jpg
|
||||
test -s assets/marketing/marqdo-2.7.1-promo.srt
|
||||
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 assets/marketing/marqdo-2.7.1-promo.mp4
|
||||
- name: Commit video into promotional branch
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git add assets/marketing/marqdo-2.7.1-promo.mp4 assets/marketing/marqdo-2.7.1-poster.jpg assets/marketing/marqdo-2.7.1-promo.srt
|
||||
git diff --cached --quiet || git commit -m "docs: render Marqdo 2.7.1 promotional video from existing assets"
|
||||
git push origin HEAD:docs/promo-video-271
|
||||
@@ -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 -p marqdo_plugin_llm
|
||||
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
@@ -88,6 +88,7 @@ jobs:
|
||||
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"
|
||||
Copy-Item target/release/engineering.dll "$stageNative/native/engineering.dll"
|
||||
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
|
||||
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
|
||||
$stage = "dist/stage-bundle"
|
||||
@@ -102,6 +103,7 @@ jobs:
|
||||
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"
|
||||
Copy-Item target/release/engineering.dll "$stage/ext/native/engineering.dll"
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
@@ -116,71 +118,18 @@ jobs:
|
||||
echo "VSIX=$vsix" >> $env:GITHUB_ENV
|
||||
echo "SOURCE=$source" >> $env:GITHUB_ENV
|
||||
echo "PUBLIC=$public" >> $env:GITHUB_ENV
|
||||
echo "PUBLISH_EXT=$((Get-Content ext/VERSION -Raw).Trim() -eq $ver)" >> $env:GITHUB_ENV
|
||||
echo "EXT=$extZip" >> $env:GITHUB_ENV
|
||||
echo "NATIVE=$nativeZip" >> $env:GITHUB_ENV
|
||||
|
||||
- name: Upload release assets
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v2.1.4**:默认隔离 HTTP execute(ADR 0009)——worker 池 / `--call-lib-path` · `/_runtime/*` · MR-01 双流金样例 · `runtime.isolated_execution=1`
|
||||
- **v2.1.4**: Default isolated HTTP execute (ADR 0009) — worker pool / `--call-lib-path`, `/_runtime/*`, MR-01 dual-stream gold, `runtime.isolated_execution=1`
|
||||
- **v2.1.4 ext**:扩展包同步 2.1.4 / Ext pack 2.1.4
|
||||
- **v2.1.3**:知识工作台运行时——ModelSelection/RunContext/usage · view document 只读嵌入 · LLM selection/messages/cancel · agent selection e2e
|
||||
- **v2.1.3**: Workbench runtime — ModelSelection/RunContext/usage, view document read-only embed, LLM selection/messages/cancel, agent selection e2e
|
||||
- **v2.1.1**:可执行知识主链——BoundCall · NarrativeRef · 来源/适用期 · patch/extract · 整代 CURRENT + closure · 发票示例 113
|
||||
- **v2.1.1**: Executable-knowledge spine — BoundCall, NarrativeRef, sources, patch/extract, generation CURRENT + closure, invoice example 113
|
||||
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
|
||||
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
|
||||
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
|
||||
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
|
||||
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
|
||||
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
|
||||
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
|
||||
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
|
||||
- **v1.4.6**:裸自增升参——首次粗体赋值左值即声明;`n = n + 1` 无反引号也是必选形参
|
||||
- **v1.4.6**: Bare self-increment is a required parameter — first bold assignment LHS is a declaration
|
||||
- **v1.4.5**:Streamable HTTP MCP + web invoke Bearer/401 · openai/agent json.get 硬化
|
||||
- **v1.4.5**: Streamable HTTP MCP + web invoke Bearer/401; openai/agent json.get hardening
|
||||
- **v1.4.2**:Agent/LLM 优化 O1–O5——sandbox trial · promote proof · step_route/EFI/cost · lint · quarantine
|
||||
- **v1.4.2**: Agent/LLM optimize O1–O5 — sandbox trial, promote proof, step_route/EFI/cost, lint, quarantine
|
||||
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
|
||||
- **v1.4.1**: View annot leaders — SVG mid→mid (mark bottom-center → chip top-center), frame chip id unify, L→R density
|
||||
- **v1.4.0**:叙述统一——`% marqdo: var=` · 臂/循环体叙述 · foreach 中英糖 · 图片自写回 · view 推断形参
|
||||
- **v1.4.0**: Prose-unified control flow — formula meta bind, arm/loop narrative, foreach sugar, image writeback, inferred-param view
|
||||
- **v1.3.3**:view 文档面 Structure——叙述保真 · 标记面 · 调用/循环帧 · `#mq-view-trace` · 静态站同源
|
||||
- **v1.3.3**: Browse document-surface Structure — narration, markers, call/loop frames, `#mq-view-trace`, static site parity
|
||||
- **v1.3.0**:Engineering Knowledge Compiler——L0–L4 · `reuse`/`find`/`duplicate` · Agent preflight(REUSE→ADAPT→CREATE)
|
||||
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
|
||||
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
|
||||
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
|
||||
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
|
||||
- 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
|
||||
|
||||
| Asset | Contents |
|
||||
|-------|----------|
|
||||
| `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`/`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 |
|
||||
| `marqdo-*-source.zip` | Source snapshot (`git archive`) |
|
||||
| `marqdo-*.vsix` | VS Code / Cursor extension |
|
||||
| `marqdo-*-public.zip` | Static user docs site |
|
||||
|
||||
Extension workflow: [vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
|
||||
body_path: doc/releases/${{ github.ref_name }}.md
|
||||
files: |
|
||||
dist/${{ env.EXE }}
|
||||
dist/${{ env.ZIP }}
|
||||
dist/${{ env.STDLIB }}
|
||||
dist/${{ env.EXT }}
|
||||
dist/${{ env.NATIVE }}
|
||||
dist/${{ env.VSIX }}
|
||||
dist/${{ env.SOURCE }}
|
||||
dist/${{ env.PUBLIC }}
|
||||
@@ -188,6 +137,17 @@ jobs:
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Upload independently versioned extension assets
|
||||
if: env.PUBLISH_EXT == 'True'
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
files: |
|
||||
dist/${{ env.EXT }}
|
||||
dist/${{ env.NATIVE }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
linux:
|
||||
runs-on: ubuntu-latest
|
||||
# Wait until Windows has created the GitHub Release, then attach Linux zips
|
||||
@@ -211,7 +171,7 @@ jobs:
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cargo build --release
|
||||
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
|
||||
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
|
||||
- name: Package Linux native zip + CLI bundle
|
||||
@@ -219,8 +179,11 @@ jobs:
|
||||
set -euo pipefail
|
||||
VER="${GITHUB_REF_NAME#v}"
|
||||
TARGET="x86_64-unknown-linux-gnu"
|
||||
if [[ "$(tr -d '[:space:]' < ext/VERSION)" == "$VER" ]]; then
|
||||
echo "PUBLISH_EXT=true" >> "$GITHUB_ENV"
|
||||
fi
|
||||
mkdir -p dist/stage-native/native
|
||||
for lib in libweb.so libagent.so libquantum.so liblinalg.so libllm.so; do
|
||||
for lib in libweb.so libagent.so libquantum.so liblinalg.so libllm.so libengineering.so; do
|
||||
src="target/release/${lib}"
|
||||
if [[ ! -f "$src" && "$lib" == libweb.so ]]; then
|
||||
src="plugins/web/build/libweb.so"
|
||||
@@ -247,8 +210,16 @@ jobs:
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
files: |
|
||||
dist/${{ env.NATIVE }}
|
||||
dist/${{ env.LINUX_ZIP }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Upload independently versioned Linux native pack
|
||||
if: env.PUBLISH_EXT == 'true'
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
files: dist/${{ env.NATIVE }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
@@ -42,11 +42,7 @@ spike/.pytest_cache/
|
||||
*.pyc
|
||||
|
||||
# Built browser WASM (rebuild via crates/marqdo-wasm README)
|
||||
/examples/browser-hello/marqdo_wasm.wasm
|
||||
/examples/browser-hello/pkg/
|
||||
/examples/web-client-site/static/marqdo_wasm.wasm
|
||||
/examples/browser-app/marqdo_wasm.wasm
|
||||
/examples/browser-media/marqdo_wasm.wasm
|
||||
|
||||
# Local sqlite / scratch
|
||||
/data/
|
||||
@@ -61,7 +57,6 @@ plugins/*/tmp/
|
||||
/examples/web-net-site/data/
|
||||
/examples/web-net-site-zh/data/
|
||||
/examples/marqdo-blog/data/
|
||||
/examples/anlian-mq/data/
|
||||
|
||||
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
|
||||
/tests/ext/quantum-*.svg
|
||||
@@ -79,11 +74,16 @@ plugins/*/tmp/
|
||||
# Plot SVGs emitted beside tests / notebooks when demos run
|
||||
/tests/**/*-plot-*.svg
|
||||
|
||||
# Lean Lake build outputs (sources under verification/ stay tracked)
|
||||
**/.lake/
|
||||
|
||||
# PLDI / thesis harness scratch must never land in this tree
|
||||
.lx*-tmp/
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
# Install-root path hints from `marqdo ext add` — never belong in the source tree
|
||||
/ext/*.plugin
|
||||
|
||||
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
|
||||
/plugins/web/build/
|
||||
@@ -104,3 +104,22 @@ tests/ext/_sbx_cow/
|
||||
tests/ext/_sbx_*/
|
||||
examples/**/_example_sbx/
|
||||
.secrets/
|
||||
|
||||
# Generated runtime resources for callable browser handbook examples
|
||||
/examples/web-spa-app/static/marqdo_wasm.wasm
|
||||
/examples/web-spa-app/static/marqdo-bridge.js
|
||||
/examples/web-collab-doc/static/marqdo_wasm.wasm
|
||||
/examples/web-collab-doc/static/marqdo-bridge.js
|
||||
|
||||
# Native browser runtime and compiled theme produced by the network-site handbook.
|
||||
/examples/web-net-site/public/generated/
|
||||
/examples/web-net-site-zh/public/generated/
|
||||
|
||||
# Generated literary-site theme resources (the declarative sources stay tracked).
|
||||
/examples/web-site/public/generated/
|
||||
/examples/web-site-zh/public/generated/
|
||||
|
||||
# Native browser-effects example generated resources.
|
||||
/examples/browser-app/static/marqdo_wasm.wasm
|
||||
/examples/browser-app/static/marqdo-bridge.js
|
||||
/examples/browser-app/static/theme.css
|
||||
@@ -2,12 +2,294 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
## v2.7.1 — 2026-11-11
|
||||
|
||||
CLI 修复发布:View 实际逻辑的手动开合不再被布局重排或运行结果刷新覆盖;函数、链接、列表和记录按内容排版,手机详情整行展示。核心仍为 19 个构造;拓展库保留 2.7.0。
|
||||
|
||||
CLI fix release: implementation disclosures retain mouse/keyboard choices across resize, nested source reading and live replacement. Typed call/link/value details preserve real navigation and read-only inspection. Independent extension packs remain 2.7.0.
|
||||
|
||||
详见 [双语发布说明](doc/releases/v2.7.1.md)。旧静态站点需要用新 CLI 重新导出。
|
||||
|
||||
## v2.7.0 — 2026-11-10
|
||||
|
||||
### Highlights / 亮点
|
||||
|
||||
源码手册进入真实开发与用户站点:原生文件操作、可调用开发/发版流程、递归 View 站点及当前请求资源。CLI、WASM、拓展包与编辑器版本统一为 2.7.0。详见 [完整双语发布说明](doc/releases/v2.7.0.md)。
|
||||
|
||||
Executable source handbooks now drive actual development and user sites: native file operations, callable release tasks, recursive View Documents and current request resources. CLI, WASM, extension packs and editor version are 2.7.0.
|
||||
|
||||
**核心表面 Δ / Core surface Δ**:无增删,仍为 19 个核心构造;沿用既有 Markdown 标记与插件 ABI。
|
||||
|
||||
### Added
|
||||
|
||||
- Native development and release handbooks, bounded engineering plugin boundaries, literal CLI JSON file/stdin arguments and --require-ok failure propagation.
|
||||
- 原生文档表读取与保留正文的修改;纯 head 资源,以及当前请求的数据查询、表单与会话导航资源。
|
||||
- Both-language recursive user sites, source-aware route inspection, retained theme declarations and actual browser acceptance.
|
||||
- Structured nested list/control records in the official bridge, documented in EN/ZH browser libraries and the callable browser-app.
|
||||
|
||||
### Fixed
|
||||
|
||||
- Occlusion receivers, nested and hyphenated-path calls, prose literal defaults and exact CLI argument/session replay semantics.
|
||||
- 授权站点根下的文件/SQLite 定位;嵌套 Document 与 Endpoint 回调上下文;表单重试 CSRF、成功跳转、管理入口与片段选择。
|
||||
- Browser duplicate-item deletion, literal content rendering, Back/Forward history and asynchronous outcome reporting.
|
||||
|
||||
### Changed
|
||||
|
||||
- SKILL discovery delegates to executable handbooks; ordinary file IO and orchestration use Marqdo instead of Python release scripts.
|
||||
- 中英文用户站点保留原始主题、当前文章与管理能力;移除无关的暗恋工程和过时独立浏览器演示,保留底层测试夹具。
|
||||
- Native packs include the engineering plugin. Main excludes editor sources; immutable tags, both-platform builds and independent GitHub/CDN/Ubuntu verification remain release obligations.
|
||||
|
||||
## v2.6.0 — 2026-11-08
|
||||
|
||||
### Highlights / 亮点
|
||||
|
||||
标准库、拓展库与阅读界面共同围绕“源码即手册,文档即 SKILL,函数即工具”完成更新。
|
||||
CLI、WASM、扩展包与 VS Code 扩展统一为 2.6.0。
|
||||
|
||||
- 标准库新增完整文件整理、二进制与分块、集合处理、结构化数据、文档修改、HTTP、子任务与时区能力。
|
||||
- 61 份公开标准库提供 650 个函数,保持单文件自述;多文件拓展库通过 index 组织真实工作流。
|
||||
- Quantum 提供可执行实验与会话句柄;Web 明确从区域树递归拆到 Markdown 叶子的工程方式。
|
||||
- View 正文只呈现动作说明,实际逻辑进入左右侧注,空括号明确提示待补逻辑;知识区按输入输出与依据组织。
|
||||
- Standard libraries add practical file, binary, collection, structured-data, document, HTTP, task and timezone workflows.
|
||||
- Libraries are executable handbooks with contracts, narrative parameters and readable inline operations; View separates action text, implementation and observed results.
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:无增删,仍为 19 个核心构造。新增能力属于 Runtime / Document;
|
||||
行内遮蔽边界与 GFM 转义修复沿用既有标记,不引入另一套语法或 Skill 编译器。
|
||||
|
||||
### Added
|
||||
|
||||
- 文件:查找、行读写、JSON/CSV 读写、二进制字节和分块操作、临时资源、单文件原子写、摘要检查、目录批处理与可选 ZIP。
|
||||
- 集合:范围、枚举、投影、筛选、首项/任一/全部判断、分组汇总、连接、集合运算、模式校验及 key/value 行记录构造。
|
||||
- 数据与工程:Result、完整 TOML、IANA 时区/DST、结构化 HTTP 结果与下载、子任务超时/并发/取消、保留周围叙述的受控文档修改。
|
||||
- 标准库单文件手册、开发指南、真实工程示例,以及数据、安全、网络、线性代数、AI 的工程入口与安装依赖。
|
||||
- Quantum 任务导航、实验与双语门面;Web 递归布局、普通 Markdown 叶子和双语参考站点;call 会话中传递实际资源句柄。
|
||||
- View 核心语法阅读指南、实现侧注、可读知识卡片、最终绑定与调用记录,以及静态/实时/无脚本浏览器验收。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 修复中文智能体单步被说明中的斜体 map 提前返回、事务构造器返回未绑定 self、策略说明标题被误识别为对象等旧问题。
|
||||
- 修复行内遮蔽中标签星号和载荷乘法的结束边界,以及 GFM 单元格的转义竖线。
|
||||
- 修复整句遮蔽只处理首个链接、改写叙述的问题;普通导航与文字字面量不冒充可执行逻辑。
|
||||
- 单文件 View 只分析实际依赖闭包,避免无关同目录模块重名使知识说明整体不可用。
|
||||
- 修复回放策略 wire 命令与 agent smoke 工具注册,保持可执行知识门禁可复现。
|
||||
|
||||
### Changed
|
||||
|
||||
- 标准库和拓展库的参数与返回表紧接标题;移除库源码中的旧加号形参,使用叙述形参与句中赋值、调用、返回。
|
||||
- 每个库单元叙述超过 50%;行内代码和绑定数据表仍计作代码,避免以模板或排版替代说明。
|
||||
- 知识区将身份和摘要折叠为技术详情,分别呈现静态检查、测试、来源与领域审阅;阅读操作不会执行代码。
|
||||
- 既有可用接口、默认值和副作用边界保持兼容。原生专属能力不宣称在 WASM 可用,目录批处理不宣称事务,摘要写入不宣称内核 CAS。
|
||||
|
||||
### Validation
|
||||
|
||||
- 本地全量回归 984 通过、0 失败、2 个原有忽略项;发布提交与打包产物另行复核。
|
||||
- 实际 wasm32 产物通过 ABI、桥接、双语集合与 32 位边界验收。
|
||||
- Chromium 验证七种宽度、实时与静态页面、无脚本回退、源码定位、曲线、帧切换与重新运行。
|
||||
|
||||
## v2.5.1 — 2026-11-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**View 标注连线与工具栏优化 / View annotation and toolbar refinement**:执行标注精确绑定源码行与字节区间;连续 S 形曲线取代水平长线,标注贴近正文错落排布,并避让正文和相邻连线;浮动工具栏增加文字说明。CLI · wasm · ext **2.5.1**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造);无 Markdown 语法或插件 ABI 变更。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 执行标注从实际源码片段引出并连接标注标题,不再从正文边缘引出;多调用帧与循环轮次共用准确的源码区间,避免按类型猜测锚点。
|
||||
- 处理源码换行、重跑、窗口变化与字体加载后的连线定位;保留密集区域和窄屏的文内降级。
|
||||
- 连线连续弯曲、柔和金绿过渡,并为相邻曲线保留间距;宽屏标注更靠近正文,横纵方向错落排布。
|
||||
|
||||
### Changed
|
||||
|
||||
- 底部工具栏显示“刷新、设置、运行、清理、更多”,保留深浅色配色与原有操作行为。
|
||||
- 新增七种屏宽、曲率、连线交叉、两端定位及共享源码帧绑定的浏览器回归。
|
||||
- CLI、WASM、扩展包和 VS Code / Cursor 扩展同步 **2.5.1**;扩展包功能沿用 v2.5.0。
|
||||
|
||||
## v2.5.0 — 2026-11-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**View 文档阅读界面重构 / View reader redesign**:暖白金色排版、新 Marqdo 标志与花枝羽毛素材;宽屏执行信息左右引出,窄屏回到正文下方;导航、搜索与悬浮工具栏;实时 view 与静态导出同源,公式和素材离线可用。CLI · wasm · ext **2.5.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)。本次变更集中于 view 展示与普通文档执行结果刷新;无 Markdown 语法或插件 ABI 变更。
|
||||
|
||||
```bash
|
||||
marqdo view public
|
||||
marqdo view output public -o site
|
||||
```
|
||||
|
||||
### Added
|
||||
|
||||
- 暖白/深色阅读主题、新 Logo、透明花枝与羽毛;顶部导航、正文/函数/文件搜索、阅读设置和悬浮工具栏。
|
||||
- 宽屏执行标注左右排布与避让,点击查看完整捕获值;窄屏、密集段落和打印采用正文内标注。
|
||||
- 内嵌 KaTeX 0.16.22、字体和装饰素材,静态页面断网仍可渲染公式。
|
||||
- 六种屏宽的 live/static 浏览器回归与普通文档重跑结果一致性回归。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 普通文档重跑后,从同一次执行捕获刷新正文、变量与轨迹,避免为更新标注重复执行。
|
||||
- 移除重复的正文 `id="structure"`,确保刷新定位到实际正文;修复搜索框 Escape 关闭与隐藏目录焦点行为。
|
||||
|
||||
### Changed
|
||||
|
||||
- 函数和变量面板按需打开;调用帧与循环轮次选择保留;高级 notebook 操作从工具菜单进入。
|
||||
- CLI、WASM、扩展包和 VS Code / Cursor 扩展同步为 **2.5.0**;扩展包功能沿用 v2.4.0 已发布内容。
|
||||
|
||||
## v2.4.0 — 2026-11-06
|
||||
|
||||
### Highlights
|
||||
|
||||
**Oracle journal 作语言值**:`foreign.oracle_journal` / `foreign.replay_check` 把观测与纯比较暴露为普通 Marqdo 值(非仅 notebook API);handle/code 不得入 journal;`copy` 拒绝 code。Bytecode / frontend / foreign session 模块化与 applications 金样例;`verification/replay-policy` Lean 策略身份。CLI · wasm · ext **2.4.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——变更在 `lib/foreign` 宿主表面与实现结构,不增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`foreign.oracle_journal` / `foreign.replay_check`**:文档级观测列表与纯 journal 比较(`doc/design/oracle-journal-values.md`)。
|
||||
- **回归**:`foreign-oracle-{journal,names,failure}`、`foreign-{,session-}copy-code-refuse`、`tests/oracle_journal.rs`、applications 四场景、`verification/replay-policy`。
|
||||
- **文档**:`oracle-journal-values.md`;frontend-call / foreign-library 方向笔记。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **view notebook API**:`OnceLock` 初始化等待兼容 MSRV **1.81**(不再调用 ≥1.84 的 `wait`)。
|
||||
- JSON `float_roundtrip` 特征,减少外联浮点往返失真。
|
||||
|
||||
### Changed
|
||||
|
||||
- Bytecode compile/VM、foreign_doc/session、sema resolution、notebook interrupt 路径拆模块(行为对齐既有 Strong 契约)。
|
||||
|
||||
## v2.3.0 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**Foreign Strong(session / value / replay)**:会话句柄改为不透明 `handle`(不可 JSON 过桥、禁止 text 伪造);`close` 仿射消费(双 close / use-after-close 故障);`replay_check` 对照 oracle journal(旧 `replay_snapshot` 仅重跑保留);GFM 表行 arity 与列长映射拒绝静默补空;Ω 返回域外整数故障。对齐 PLDI Strong 叙事与 Lean SessionReg / \(V_{\mathsf{safe}}\)。CLI · wasm · ext **2.3.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——破坏面在宿主 foreign/session/JSON 与表解析纪律,不增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`Value::Handle`**:`session_open` 返回句柄;session 操作拒绝 text 伪造。
|
||||
- **`DocumentSession::replay_check`** + API `/api/session/snapshot/replay_check`;snapshot 录音字段 + **`oracle_journal`**(与 execution journal 分名)。
|
||||
- **API** `/api/session/oracle_journal`。
|
||||
- **文档**:`doc/design/foreign-strong-correspondence.md`;`v-safe-json.md` 补 Handle / 列 arity / Ω 门。
|
||||
- **回归**:`foreign-session-{use-before-open,use-after-close,double-close,cold-replay-empty,isolation,handle-no-serialize,result-vsafe-refuse}`;`tests/errors/table-arity.mq.md`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 不等宽 GFM 表不再静默补空单元格;解析报 `table row arity mismatch`。
|
||||
- Py/Node session bootstrap:Ω 结果 OOD 整数不再 `default=str` 偷渡,宿主升级为故障。
|
||||
|
||||
### Changed
|
||||
|
||||
- **`session_close`**:未知 / 已关闭句柄 → 故障(不再返回 `False`)。
|
||||
- **`session_list`**:`id` 字段为 `handle`。
|
||||
- Snapshot export 含 `ok`/`code`/`stdout`/`result`/`source_hash` 与 `oracle_journal`。
|
||||
|
||||
## v2.2.2 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**\(V_{\mathsf{safe}}\) JSON 整数契约落地**:外联 / `json.parse` / `json.stringify` / `session_set` 等共用映射对齐 Lean ForeignJSON——`|n| > 2^{53}-1` 的 JSON 整数显式拒绝(错误前缀 `json: integer outside V_safe`),禁止 Node 路径静默扭曲;宽整数仍用十进制字符串 + 对端 `BigInt`。CLI · wasm · ext **2.2.2**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——宿主 JSON 契约与测试,不改 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`doc/design/v-safe-json.md`**:宿主 ↔ Lean \(V_{\mathsf{safe}}\) 契约锁定(`MAX_SAFE`、encode/decode refuse、嵌套、float 为宿主扩展)。
|
||||
- **回归**:`tests/lib/json-vsafe-*`、`foreign-vsafe-*`、`foreign-session-vsafe-refuse`(含算术后越界 refuse)。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`src/host/json.rs`**:对域外整数与 `u64 > i64::MAX` 显式失败;不再经 `f64`/`Text` 静默降级。
|
||||
- **`doc/design/foreign-kernel.md`**:Int→number 仅当 `|n| ≤ 2^{53}-1`;宽整数走 string 桥。
|
||||
|
||||
### Changed
|
||||
|
||||
- 外联 JSON 桥与 `lib/json` 行为:OOD 整数从「可能静默失真」改为「诊断失败」。
|
||||
|
||||
## v2.2.1 — 2026-10-30
|
||||
|
||||
### Highlights
|
||||
|
||||
**view / 静态导出大纲侧栏修复**:带遮蔽(occlusion)语句的文档页里,Functions / Variables 右侧栏会掉到正文下面;中等窗口宽度下也会被错误叠成单列。CLI · wasm · ext **2.2.1**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——布局与 HTML 闭合修复,不改 Markdown 标记。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`marqdo view` / `view output`**:occlusion 行提前返回时未关闭 `.doc-block`,把 `#outline-rail` 嵌进 `document-surface`,侧栏排到文档下方;现已闭合并保留标注带。
|
||||
- **view 壳 CSS**:大纲折叠改为按主栏 `@container mq-panel` 宽度(32rem),不再用视口 `960px` 媒体查询把右侧栏压到正文下;极窄时大纲上移到文档上方。
|
||||
|
||||
## v2.2.0 — 2026-10-30
|
||||
|
||||
### Highlights
|
||||
|
||||
**函数级调用 `marqdo call`**:同一份 `.mq.md` 已经是文档、知识和程序。这一版补上从外部调用其中某个函数的入口。人继续读这一页;开发者、测试和 Agent 用同一条命令传入参数并执行。知识复用、把函数当工具、逐个函数做测试、改完再跑,都是这一入口的用法,不是另一套 Skill 系统。CLI · wasm · ext **2.2.0**。
|
||||
|
||||
```bash
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
# 5
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
|
||||
```
|
||||
|
||||
**作用**:最小可执行单位从「整份文件」扩展到「文件里的一个函数」。不必为了试一个函数再写 `# main`、打印和包装程序。
|
||||
|
||||
**价值**:说明和实现仍在同一页。Agent 读函数旁边的叙述,定位函数,传入参数,得到可检查的结果。正式发布和权限仍走已有的项目验证;`call` 默认不开放写文件、进程、网络和插件。
|
||||
|
||||
说明页:[public/features/22-函数调用.mq.md](public/features/22-函数调用.mq.md) · [public/features/22-call.mq.md](public/features/22-call.mq.md)
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——新增的是 CLI 入口,不新增 Markdown 标记。`**…**` 仍是语句,`*…*` 仍是返回。
|
||||
|
||||
### Added
|
||||
|
||||
- **`marqdo call <文件.mq.md> <函数> [名字=值 ...]`**:加载该文件及其 import,按显示路径、SymbolId 或唯一短名定位函数,用现有签名和契约绑定参数,再用现有运行时执行。
|
||||
- **`--json`**:成功 `{"ok":true,"result":...}`,失败 `{"ok":false,"error":...}`,错误带诊断 `code`。`--backend tree|bytecode` 与 `marqdo run` 相同;指定函数时两个后端都不会改去跑 `# main`。
|
||||
- **默认纯函数**:效应含写入、网络、进程或插件时,执行前返回 `artifact.effect_denied`,副作用不会发生。
|
||||
- **参照文档** `examples/calculator.mq.md`,以及用户说明页 `public/features/22-*`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 官方语法说明与 Agent 语法卡的标记极性与解析器对齐:粗体是语句,斜体是返回。同步测试会实际运行说明里的调用示例。
|
||||
- Bytecode 的 `marqdo run --call-lib-path` 执行被点名的导入函数,不再忽略该参数去跑入口。
|
||||
- 隔离运行时冒烟测试补上 `InvokeContext.fs_root`,`--tests` 可以编过。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.2.0**。扩展包版本号对齐;这一版的新能力在 CLI。
|
||||
|
||||
## v2.1.5 — 2026-10-27
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent 可靠工作台 + EKC 热路径**:ResourceView(JSON/CSV/PDF/image `blob_ref`、locator 页/行)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制面与 execute 槽隔离。CLI · wasm · ext **2.1.5**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.5 && cargo build --release
|
||||
marqdo ext add web # CDN / Releases → 2.1.5
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台协议与 Agent 运行时合同,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **ResourceView v1**:有界 JSON/CSV 渲染;PDF/image `blob_ref`;`locator.page` / 行定位;CSV `text` 供 TablePreview。
|
||||
- **Agent 合同**:ToolSpec 注册与 authorize-before-call;CheckpointV2 原子 resume;AgentErrorV1;输出通道;ContextPackV2;EffectLedger(含 mutating `run_tool` 水印)。
|
||||
- **Workbench fixtures/schemas**:`tests/workbench_contracts` 协议金样例。
|
||||
- **EKC `ir.json` 快照**:`marqdo knowledge` 写入 `.marqdo/ekc/graph/ir.json`;查询命令暖机热加载,免全量重编译。
|
||||
- **`--refresh`**:`knowledge preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify` 可强制重编译。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **工程预检热路径**:`knowledge preflight`(及 find/reuse 等)默认不再每次 `ensure_compiled` 全量 compile,修复聊天「工程预检」墙钟过长。
|
||||
- **Web 槽隔离**:`short`/`read`/`control` 不再填满 execute 槽;disconnect≠cancel。
|
||||
- **CSV ResourceView**:去掉尾部空行伪影。
|
||||
|
||||
### Changed
|
||||
|
||||
- 查询类 knowledge CLI:**缺投影才 compile**;CI / 源变更请先 `marqdo knowledge` 或 `--refresh`。
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.5**。
|
||||
|
||||
## v2.1.4 — 2026-10-26
|
||||
|
||||
### Highlights
|
||||
@@ -910,6 +1192,8 @@ marqdo run tests/markup-v03/inc-prose.mq.md
|
||||
|
||||
### Highlights
|
||||
|
||||
历史说明(2026-11-10):本节的 anlian-mq 是当时发布内容记录,现已移出仓库,旧启动命令不适用于当前工作树。当前完整站点见 examples/web-site 与 examples/web-site-zh。
|
||||
|
||||
**Go `libweb` 默认落地(W-G0–W-G14)**:官方网页原生插件改为 Go C ABI;CLI / gold / Release 走 `scripts/build-web-plugin.sh`;Rust 源码归档。另附 **anlian-mq** 验收站与表单插槽 / `MARQDO_EXT` 提示修复。
|
||||
|
||||
```bash
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 3
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "adler2"
|
||||
@@ -186,6 +186,27 @@ dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "chrono-tz"
|
||||
version = "0.10.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cd6dd8046d00723a59a2f8c5f295c515b9bb9a331ee4f8f3d4dd49e428acd3b6"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"chrono-tz-build",
|
||||
"phf",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "chrono-tz-build"
|
||||
version = "0.4.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8f10f8c9340e31fc120ff885fcdb54a0b48e474bbd77cab557f0c30a3e569402"
|
||||
dependencies = [
|
||||
"parse-zoneinfo",
|
||||
"phf_codegen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "chunked_transfer"
|
||||
version = "1.5.0"
|
||||
@@ -307,6 +328,12 @@ version = "0.3.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9"
|
||||
|
||||
[[package]]
|
||||
name = "equivalent"
|
||||
version = "1.0.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
|
||||
|
||||
[[package]]
|
||||
name = "find-msvc-tools"
|
||||
version = "0.1.10"
|
||||
@@ -414,6 +441,12 @@ dependencies = [
|
||||
"wasi",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hashbrown"
|
||||
version = "0.15.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
|
||||
|
||||
[[package]]
|
||||
name = "heck"
|
||||
version = "0.4.1"
|
||||
@@ -525,6 +558,16 @@ dependencies = [
|
||||
"quote",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "indexmap"
|
||||
version = "2.7.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8c9c992b02b5b4c94ea26e32fe5bccb7aa7d9f390ab5c1221ff895bc7ea8b652"
|
||||
dependencies = [
|
||||
"equivalent",
|
||||
"hashbrown",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "is_terminal_polyfill"
|
||||
version = "1.70.2"
|
||||
@@ -572,11 +615,12 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "2.1.4"
|
||||
version = "2.7.1"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"chrono",
|
||||
"chrono-tz",
|
||||
"clap",
|
||||
"futures-util",
|
||||
"getrandom",
|
||||
@@ -597,6 +641,7 @@ dependencies = [
|
||||
"tiny_http",
|
||||
"tokio",
|
||||
"tokio-tungstenite",
|
||||
"toml",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
"zip",
|
||||
@@ -611,7 +656,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.1.4"
|
||||
version = "2.7.1"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -634,6 +679,23 @@ dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_engineering"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"base64",
|
||||
"chrono",
|
||||
"flate2",
|
||||
"hmac",
|
||||
"libc",
|
||||
"marqdo",
|
||||
"marqdo-plugin-sdk",
|
||||
"serde_json",
|
||||
"sha2",
|
||||
"ureq",
|
||||
"zip",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_linalg"
|
||||
version = "0.1.0"
|
||||
@@ -727,12 +789,59 @@ version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
||||
|
||||
[[package]]
|
||||
name = "parse-zoneinfo"
|
||||
version = "0.3.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1f2a05b18d44e2957b88f96ba460715e295bc1d7510468a2f3d3b44535d26c24"
|
||||
dependencies = [
|
||||
"regex",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "percent-encoding"
|
||||
version = "2.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
|
||||
|
||||
[[package]]
|
||||
name = "phf"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
|
||||
dependencies = [
|
||||
"phf_shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_codegen"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "aef8048c789fa5e851558d709946d6d79a8ff88c0440c587967f8e94bfb1216a"
|
||||
dependencies = [
|
||||
"phf_generator",
|
||||
"phf_shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_generator"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
|
||||
dependencies = [
|
||||
"phf_shared",
|
||||
"rand",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_shared"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
|
||||
dependencies = [
|
||||
"siphasher",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pin-project-lite"
|
||||
version = "0.2.17"
|
||||
@@ -971,6 +1080,15 @@ dependencies = [
|
||||
"zmij",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_spanned"
|
||||
version = "0.6.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
|
||||
dependencies = [
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "sha1"
|
||||
version = "0.10.6"
|
||||
@@ -1005,6 +1123,12 @@ version = "0.3.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
|
||||
|
||||
[[package]]
|
||||
name = "siphasher"
|
||||
version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256"
|
||||
|
||||
[[package]]
|
||||
name = "slab"
|
||||
version = "0.4.12"
|
||||
@@ -1152,6 +1276,47 @@ dependencies = [
|
||||
"tungstenite",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml"
|
||||
version = "0.8.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
|
||||
dependencies = [
|
||||
"serde",
|
||||
"serde_spanned",
|
||||
"toml_datetime",
|
||||
"toml_edit",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_datetime"
|
||||
version = "0.6.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
|
||||
dependencies = [
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_edit"
|
||||
version = "0.22.27"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
|
||||
dependencies = [
|
||||
"indexmap",
|
||||
"serde",
|
||||
"serde_spanned",
|
||||
"toml_datetime",
|
||||
"toml_write",
|
||||
"winnow",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_write"
|
||||
version = "0.1.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
|
||||
|
||||
[[package]]
|
||||
name = "tungstenite"
|
||||
version = "0.24.0"
|
||||
@@ -1493,6 +1658,15 @@ version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
|
||||
|
||||
[[package]]
|
||||
name = "winnow"
|
||||
version = "0.7.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
|
||||
dependencies = [
|
||||
"memchr",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "zerocopy"
|
||||
version = "0.8.56"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "2.1.4"
|
||||
version = "2.7.1"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -30,7 +30,7 @@ chrono = { version = "0.4", default-features = false, features = ["clock", "std"
|
||||
clap = { version = "=4.4.18", features = ["derive"], optional = true }
|
||||
pulldown-cmark = "0.12"
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
serde_json = { version = "1", features = ["float_roundtrip"] }
|
||||
thiserror = "1"
|
||||
tiny_http = { version = "0.12", optional = true }
|
||||
sha2 = { version = "=0.10.9", default-features = false }
|
||||
@@ -49,6 +49,8 @@ zip = { version = "=0.6.6", default-features = false, features = ["deflate"], op
|
||||
libloading = { version = "=0.8.6", optional = true }
|
||||
include_dir = "0.7"
|
||||
libc = { version = "0.2", optional = true }
|
||||
chrono-tz = "=0.10.0"
|
||||
toml = "=0.8.23"
|
||||
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
# Custom entropy — no `js`/wasm-bindgen imports (raw mq_* ABI + marqdo-bridge.js).
|
||||
@@ -58,6 +60,7 @@ getrandom = { version = "=0.2.17", default-features = false, features = ["custom
|
||||
[workspace]
|
||||
members = [
|
||||
"plugins/demo",
|
||||
"plugins/engineering",
|
||||
"plugins/agent",
|
||||
"plugins/llm",
|
||||
"plugins/quantum",
|
||||
|
||||
@@ -1,15 +1,128 @@
|
||||
# Marqdo
|
||||
# Marqdo — Your SKILL is now a TOOL.
|
||||
|
||||
**代码即文档。文档即知识库。知识即可执行。**
|
||||
<p align="center"><strong>Write it. Inspect it. Call it.</strong></p>
|
||||
<p align="center"><em>让 SKILL 真正成为工具:文档即知识,知识即可执行。</em></p>
|
||||
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
|
||||
<p align="center">
|
||||
<a href="https://github.com/cflmy/marqdo/releases/tag/v2.7.1"><img alt="release" src="https://img.shields.io/badge/release-v2.7.1-DDBA86?style=flat-square"></a>
|
||||
<a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square"></a>
|
||||
<img alt="Rust runtime" src="https://img.shields.io/badge/runtime-Rust-B38E68?style=flat-square">
|
||||
<img alt="Pure by default" src="https://img.shields.io/badge/call-pure_by_default-467C83?style=flat-square">
|
||||
</p>
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
**Marqdo is a Rust-based, document-native runtime for executable AI skills and tools.** Write human-readable prose, GFM tables, parameter contracts, and real functions in one `.mq.md` document. Call a function by its heading, inspect the implementation, and grant side effects explicitly.
|
||||
|
||||
**链接语法**:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
**Not a prompt wrapper.** The document is interpreted as a program by Marqdo; its tool functions are not merely natural-language instructions.
|
||||
|
||||
<p align="center">
|
||||
<a href="#one-markdown-file-three-views-real-execution">56s film</a> ·
|
||||
<a href="#quickstart--one-function-one-command">Quickstart</a> ·
|
||||
<a href="#a-procurement-skill-with-a-600-budget">Procurement demo</a> ·
|
||||
<a href="#explore-the-view">View</a> ·
|
||||
<a href="doc/library-development.mq.md">Guide</a> ·
|
||||
<a href="https://www.marqdo.com/">Website</a> ·
|
||||
<a href="doc/releases/v2.7.1.md">Release notes</a>
|
||||
</p>
|
||||
|
||||
## One Markdown file. Three views. Real execution.
|
||||
|
||||
[](assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4)
|
||||
|
||||
**[▶ Watch the 56-second film](assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4)** · [Bilingual captions](assets/marketing/marqdo-2.7.1-markdown-to-execution.srt) · [Reproducible video source](scripts/render-markdown-execution-promo.py)
|
||||
|
||||
> **The point is not to invent a new document format.** A `.mq.md` file uses Markdown headings, paragraphs and tables. Ordinary Markdown renderers still show a readable document. Marqdo adds explicit execution semantics and a View that can inspect functions, values and their relationships on the same document.
|
||||
|
||||

|
||||
|
||||
<sub>**Concept artwork** showing the design principle: **source → ordinary Markdown rendering → Marqdo View**. Illustrative labels are not a live execution trace. The video includes [a real View screenshot](assets/marketing/user-procurement-view.png), [a standard Markdown rendering](assets/marketing/marqdo-procurement-standard-markdown.png) produced from the actual procurement source, and a business example verified with the 2.7.1 CLI.</sub>
|
||||
|
||||
**One `.mq.md` source, three ways to interact:**
|
||||
|
||||
| Source | Standard Markdown | Marqdo runtime + View |
|
||||
|---|---|---|
|
||||
| Edit the same Markdown text | Read headings, prose and data tables | Inspect the same document's calls, values and effects |
|
||||
| No separate prompt or tool implementation specification needed | Works as ordinary readable documentation | Call named functions with `marqdo call` |
|
||||
|
||||
|
||||
|
||||
## Quickstart — one function, one command
|
||||
|
||||
Install the [2.7.1 CLI release for Windows or Linux](https://github.com/cflmy/marqdo/releases/tag/v2.7.1), then run from this repository's root:
|
||||
|
||||
```bash
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
# => 5
|
||||
```
|
||||
|
||||
The function heading is the callable name. The function's explanation, parameters, return contract, and implementation live **in the same source file**. Use `--json` for machine-readable call results and diagnostics. No LLM key is needed for this quickstart.
|
||||
|
||||
## A procurement skill with a ¥600 budget
|
||||
|
||||
[Read the complete executable procurement document](examples/procurement/index.mq.md) · [How to run and verify the example](examples/procurement/README.md)
|
||||
|
||||
This is a **seven-tool, offline demonstration**. It knows the local supplier directory, queries a static price catalog, checks the budget, and conditionally creates a **simulated** work order. It also documents receipt handling, negotiation and supplier switching as unconnected stubs.
|
||||
|
||||

|
||||
|
||||
<sub>**Real CLI results**, edited into a short animation; the accepted order is explicitly **simulated** and never sent. [Capture workflow](scripts/capture-procurement-showcase.py) · [Passing checks](https://github.com/cflmy/marqdo/actions/runs/43358288563).</sub>
|
||||
|
||||
```bash
|
||||
# 1. Approve suppliers: paused or blacklisted entries are excluded.
|
||||
marqdo call examples/procurement/index.mq.md 查询采购商 "采购商状态='正常'" --json
|
||||
|
||||
# 2. Quote: SUP_JN, 8 ball bearings × ¥36 = ¥288 (sample price).
|
||||
marqdo call examples/procurement/index.mq.md 查询采购商价格 "采购商标识符='SUP_JN'" 数量=8 有效秒数=300 --json
|
||||
|
||||
# 3. Budget: ¥600 - ¥120 = ¥480.
|
||||
marqdo call examples/procurement/index.mq.md 查询余额 已花费=120 --json
|
||||
|
||||
# 4. Recheck supplier, quote, delivery and budget before a local mock order.
|
||||
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json
|
||||
|
||||
# 5. Over budget: ¥600 - ¥360 = ¥240 < ¥288. The mock work order must be denied.
|
||||
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json
|
||||
```
|
||||
|
||||
| Case | Budget check | Expected business result |
|
||||
|---|---|---|
|
||||
| `已花费=120` | ¥480 available ≥ ¥288 | `ok: true`, **local simulation only, not sent** |
|
||||
| `已花费=360` | ¥240 available < ¥288 | `ok: false`, budget denial |
|
||||
| `SUP_YY` | Supplier on blacklist | Excluded from quote / order |
|
||||
|
||||
**Why this matters:** The document doesn't merely tell an agent to obey a limit. The work-order **function itself** calls supplier validation, price lookup, and `查询余额` before returning an order record. Agent instructions and callable business logic can be inspected together.
|
||||
|
||||
> **Important limits:** Price and supplier records are fixtures; `已花费` is caller supplied. No authoritative budget ledger, concurrent reservation, live supplier prices, ERP messaging, real receipt, or payment is implemented. A successful **simulated** order is **not** a real transaction. The demo is a testable starting point, not a financial safety guarantee.
|
||||
|
||||
## Explore the View
|
||||
|
||||
Marqdo 2.7.1 improves the interactive reading experience: implementation details stay open when manually expanded, structured values are presented more clearly, and function/source links are easier to inspect. It **does not introduce new language syntax or APIs**.
|
||||
|
||||
```bash
|
||||
marqdo view examples/procurement --no-open
|
||||
```
|
||||
|
||||

|
||||
|
||||
<sub>**Original View screenshot provided by the project author.** Notice the natural document typography, values in the margins, and curved connections originating from function calls in the prose. [Additional automated View capture](assets/marketing/procurement-view.png) · [Static Markdown rendering](assets/marketing/marqdo-procurement-standard-markdown.png).</sub>
|
||||
|
||||
## One document, multiple uses
|
||||
|
||||
| Prompt-oriented agent skill | Marqdo executable skill |
|
||||
|---|---|
|
||||
| Natural-language tool instructions | Natural-language guidance **and** executable functions |
|
||||
| Description and code often separated | Heading, parameter table, return table and implementation in one `.mq.md` |
|
||||
| Validation may require separate wiring | Named function calls can be checked, executed and tested |
|
||||
| Prompts ask a model to comply | Runtime permissions control **declared** effects of a function call |
|
||||
| Hard to follow implementation through files | View links readable content and implementation details |
|
||||
|
||||
Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior.
|
||||
|
||||
**Resources:** [Release v2.7.1](https://github.com/cflmy/marqdo/releases/tag/v2.7.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/)
|
||||
|
||||
---
|
||||
|
||||
## Deep dive · 语言、设计与执行系统
|
||||
|
||||
## 核心优势:可执行知识(Executable Knowledge)
|
||||
|
||||
> **Knowledge That Can Run —— 知识即可执行。**
|
||||
@@ -29,6 +142,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| 真正的核心优势 | 说明 |
|
||||
|------|------|
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **函数即工具**<br>`marqdo call` | 最小可执行单位是文件中的函数,不只是整份文件。人阅读函数旁边的叙述;开发者、测试和 Agent 用 `marqdo call 文件 函数 名字=值` 执行它。知识复用、工具调用、函数级测试和局部改进是同一入口的四种用法。 |
|
||||
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
|
||||
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
|
||||
@@ -281,10 +395,26 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v2.1.4)
|
||||
## 现状(v2.7.0)
|
||||
|
||||
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例;扩展包同步 **2.1.4**
|
||||
- **实际工程与可执行 SKILL(v2.7.0)**:中英文用户站点使用递归 View、普通 Markdown、当前数据/表单/会话资源并保留原始主题。开发与发版手册通过 `marqdo call` 执行,固有文件能力负责读写,工程插件承接进程、认证与格式边界。旧独立浏览器演示已收敛到实际可运行的工程;详见 [2.7.0 发布说明](doc/releases/v2.7.0.md)。
|
||||
- **标准库与拓展库手册(v2.6.0)**:61 份公开标准库、650 个函数;源码内参数/返回契约、叙述形参、句中遮蔽调用与真实工程。新增文件/字节/集合/Result/文档/HTTP/任务/TOML/时区工作流;多文件拓展库以 index 组织。
|
||||
- **View 可读动作与知识(v2.6.0)**:正文读动作,侧注看实现,运行标注看实际结果;空逻辑明确提示待补。知识说明先看输入、返回、依赖和依据,技术身份按需展开。
|
||||
- **Quantum / Web 工程实践(v2.6.0)**:可执行实验、会话句柄与双语门面;网页先递归拆布局,直到叶子可以直接用 Markdown 表达。CLI · wasm · ext · VS Code 扩展同步 **2.7.0**。
|
||||
|
||||
- **View 连线与工具栏(v2.5.1)**:真实源码锚点、连续 S 形曲线、错落标注与连线避让;底部工具栏增加文字标签。深浅色配色保持一致。CLI · wasm · ext 同步 **2.5.1**。
|
||||
|
||||
- **View 阅读界面(v2.5.0)**:暖白金色主题、新 Logo 与花枝装饰;真实执行信息左右引出、窄屏内联;导航/搜索/阅读设置/工具栏;重跑同步刷新与离线公式。CLI · wasm · ext 同步 **2.5.0**。
|
||||
|
||||
- **Oracle journal 语言值(v2.4.0)**:`foreign.oracle_journal` / `foreign.replay_check` 作普通值;handle/code 拒入 journal;bytecode/frontend 硬化;扩展包同步 **2.4.0**
|
||||
- **Foreign Strong(v2.3.0)**:会话 `handle`(不可过桥)· 仿射 close · `replay_check`/oracle journal · 表 arity refuse · Ω∈\(V_{\mathsf{safe}}\)。扩展包同步 **2.3.0**
|
||||
- **\(V_{\mathsf{safe}}\) JSON 整数(v2.2.2)**:外联与 `lib/json` 拒绝 `|n| > 2^{53}-1` 的 JSON 整数(对齐 Lean ForeignJSON);宽整数用十进制字符串 + Node `BigInt`。
|
||||
- **view 大纲侧栏(v2.2.1)**:修复 occlusion 文档与中等宽度下 Functions / Variables 掉到正文下方的问题;静态 `view output` 同源。
|
||||
- **函数级调用(v2.2.0)**:`marqdo call <文件.mq.md> <函数> 名字=值`。同一份文档给人读,也按函数执行;Tree 与 Bytecode 都跑被点名的函数,不回退到 `# main`。默认只执行纯函数。`--json` 给 Agent 读取结果或诊断。说明与价值见 [22-函数调用](public/features/22-函数调用.mq.md)。示例:`marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3` → `5`。扩展包同步 **2.2.1**
|
||||
- **Agent 可靠工作台(v2.1.5)**:ResourceView(JSON/CSV/PDF/image)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制与 execute 槽隔离;扩展包同步 **2.1.5**
|
||||
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例
|
||||
- **知识工作台运行时(v2.1.3)**:ModelSelection / RunContext / usage null≠0 · `view document` 只读嵌入 · LLM selection/messages/cancel · agent.step selection e2e · live smoke(设计 Partial:原生适配器 unavailable)
|
||||
|
||||
- **可执行知识生产链(v2.1.2)**:证据/闭包失效 · `verify`/`adjudicate` · `reuse_execute` / `eng_bind_execute`+`publish_gate` · `document.extract` · View `KnowledgePresentation`+SSE `page_token` · 上传限流 · 门禁 45 项(100/1000 单元)
|
||||
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113`
|
||||
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock)
|
||||
@@ -311,7 +441,7 @@ marqdo catalog public -o .marqdo
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
|
||||
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
|
||||
- **`web`**:**Artifact 模型(ADR [0007](doc/adr/0007-web-document-endpoint.md))** — `type: web|endpoint` Document/Endpoint;facade `page`/`route`/`serve`/`render`/`inspect`/`use`;Resource 在 `ext/data` · `ext/security` · `ext/net`;设计 [ext-web-artifact.md](doc/design/ext-web-artifact.md);原生 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md));示例 [marqdo-blog](examples/marqdo-blog/) · [web-client-site](examples/web-client-site/) · [anlian-mq](examples/anlian-mq/)
|
||||
- **`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/) · [完整站点](examples/web-site/) · [中文完整站点](examples/web-site-zh/)
|
||||
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
|
||||
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
|
||||
- **`agent`**:A1–A4 + **MCP Server/Client**(stdio + **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)
|
||||
@@ -320,10 +450,10 @@ marqdo catalog public -o .marqdo
|
||||
- **原生插件 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))
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-app](examples/browser-app/) · [web-spa-app](examples/web-spa-app/) · [web-collab-doc](examples/web-collab-doc/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v2.1.4)
|
||||
### 如何使用最新 Marqdo(v2.7.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -338,14 +468,16 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v2.1.4 # 或留在 main
|
||||
git checkout v2.7.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
marqdo version --check
|
||||
|
||||
# 2) 跑解释器 / 文档站 / catalog
|
||||
# 2) 跑整个文件,或只调用其中一个函数
|
||||
marqdo run tests/structure/hello.mq.md
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
|
||||
marqdo run tests/structure/hello.mq.md --backend bytecode
|
||||
marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
@@ -369,15 +501,15 @@ marqdo ext add llm # 或:大模型(.mq.md + 可选 native llm)
|
||||
# 4) 动态站示例(扩展装好后)
|
||||
marqdo run examples/web-site-zh/index.mq.md # 表驱动引言 Demo
|
||||
marqdo run examples/marqdo-blog/serve.mq.md
|
||||
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
|
||||
marqdo call examples/web-site/index.mq.md serve --effects plugin,fs.write,network.write --fs-root examples/web-site --json
|
||||
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
|
||||
|
||||
# 5) 浏览器 WASM(可选)
|
||||
marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
# → dist/wasm/ … 实际工程见 examples/browser-app/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.1.4
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.7.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
|
After Width: | Height: | Size: 132 KiB |
@@ -0,0 +1,35 @@
|
||||
1
|
||||
00:00:00,000 --> 00:00:04,800
|
||||
Your SKILL is now a TOOL.
|
||||
让 Markdown 直接承载可执行语义。
|
||||
|
||||
2
|
||||
00:00:04,800 --> 00:00:11,600
|
||||
源码态:标题、段落、表格都沿用 Markdown。
|
||||
执行逻辑就在文档之中。
|
||||
|
||||
3
|
||||
00:00:11,600 --> 00:00:18,000
|
||||
渲染态:同一份代码也能成为普通 Markdown 文档。
|
||||
|
||||
4
|
||||
00:00:18,000 --> 00:00:25,000
|
||||
源码态、标准 Markdown 渲染态、Marqdo View 态。
|
||||
三种视图,同一份源文件。
|
||||
|
||||
5
|
||||
00:00:25,000 --> 00:00:32,500
|
||||
一份 .mq.md,既可以阅读,也可以编译执行。
|
||||
|
||||
6
|
||||
00:00:32,500 --> 00:00:42,000
|
||||
真实 View 截图:函数调用和值沿着优雅曲线呈现。
|
||||
|
||||
7
|
||||
00:00:42,000 --> 00:00:50,800
|
||||
预算校验不是文字承诺,而是函数执行。
|
||||
模拟订单通过或拒绝,均由运行时返回结果。
|
||||
|
||||
8
|
||||
00:00:50,800 --> 00:00:56,000
|
||||
Marqdo 2.7.1 · github.com/cflmy/marqdo
|
||||
|
After Width: | Height: | Size: 78 KiB |
@@ -0,0 +1,29 @@
|
||||
1
|
||||
00:00:00,000 --> 00:00:03,900
|
||||
Your SKILL is now a TOOL.
|
||||
让 SKILL 真正成为工具。
|
||||
|
||||
2
|
||||
00:00:03,900 --> 00:00:09,000
|
||||
One readable document. Callable business logic.
|
||||
规则、数据、工具在同一份文档里。
|
||||
|
||||
3
|
||||
00:00:09,000 --> 00:00:17,400
|
||||
Five verified CLI calls, from quote to decision.
|
||||
真实 CLI 结果:询价、预算、模拟发单。
|
||||
|
||||
4
|
||||
00:00:17,400 --> 00:00:23,400
|
||||
¥120 spent: mock order. ¥360 spent: rejected.
|
||||
¥120 时模拟通过;¥360 时预算不足。
|
||||
|
||||
5
|
||||
00:00:23,400 --> 00:00:29,000
|
||||
Inspect the actual document in Marqdo View.
|
||||
查看 Marqdo 真实 View 页面。
|
||||
|
||||
6
|
||||
00:00:29,000 --> 00:00:32,000
|
||||
github.com/cflmy/marqdo
|
||||
开源 · Marqdo 2.7.1
|
||||
|
After Width: | Height: | Size: 161 KiB |
|
After Width: | Height: | Size: 139 KiB |
@@ -0,0 +1,42 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1340" height="720" viewBox="0 0 1340 720" role="img" aria-label="Animated illustration of a procurement skill being called, including a budget denial">
|
||||
<defs><linearGradient id="night" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0b1324"/><stop offset="1" stop-color="#1a2335"/></linearGradient></defs>
|
||||
<rect x="0" y="0" width="1340" height="720" rx="0" fill="url(#night)" stroke="none"/>
|
||||
<text x="46" y="52" fill="#f6d39c" font-size="30" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">Marqdo</text>
|
||||
<text x="207" y="50" fill="#9eacc1" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">/ EXECUTABLE SKILLS</text>
|
||||
<rect x="1137" y="25" width="165" height="38" rx="19" fill="#283348" stroke="#4b5b6b"/>
|
||||
<text x="1154" y="50" fill="#d3d9e4" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">2.7.1 · DEMO</text>
|
||||
<text x="46" y="109" fill="#f6f5ee" font-size="37" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">Your SKILL is now a TOOL.</text>
|
||||
<text x="47" y="141" fill="#a8b6c7" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">A human-readable document → callable business logic → structured results</text>
|
||||
<rect x="43" y="168" width="608" height="493" rx="18" fill="#182235" stroke="#38485c"/>
|
||||
<rect x="677" y="168" width="620" height="493" rx="18" fill="#111a2b" stroke="#38485c"/>
|
||||
<rect x="43" y="168" width="608" height="57" rx="18" fill="#263349" stroke="none"/>
|
||||
<rect x="677" y="168" width="620" height="57" rx="18" fill="#263349" stroke="none"/>
|
||||
<text x="65" y="204" fill="#f5dba9" font-size="20" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">index.mq.md</text>
|
||||
<text x="707" y="204" fill="#e5eaf4" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">$ marqdo call ... 向采购商发工单</text>
|
||||
<text x="66" y="266" fill="#faf7f1" font-size="27" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">## 向采购商发工单</text>
|
||||
<text x="66" y="307" fill="#a2b2ca" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">Read the rules. Call the function.</text>
|
||||
<rect x="65" y="328" width="564" height="166" rx="9" fill="#101a2a" stroke="none"/>
|
||||
<text x="86" y="365" fill="#abd6fa" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">报价 = 查询采购商价格(...)</text>
|
||||
<text x="86" y="407" fill="#abd6fa" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">预算 = 查询余额(已花费=...)</text>
|
||||
<text x="86" y="453" fill="#e9ba84" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">1. 剩余额度 < 本单金额 → 拒绝</text>
|
||||
<text x="65" y="552" fill="#d4e0ee" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">One file: prose + contracts + tables</text>
|
||||
<text x="65" y="588" fill="#d4e0ee" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">+ executable functions + result records</text>
|
||||
<text x="706" y="272" fill="#d7deef" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">SUP_JN 数量=8 单价=36</text>
|
||||
<text x="706" y="311" fill="#98aec9" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">最高预算 = ¥600</text>
|
||||
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.04;0.09;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="345" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="374" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">01 SUPPLIER</text><text x="920" y="374" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">SUP_JN · active</text></g>
|
||||
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.19;0.24;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="399" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="428" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">02 QUOTE</text><text x="920" y="428" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">8 × ¥36 = ¥288</text></g>
|
||||
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.35;0.39999999999999997;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="453" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="482" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">03 BALANCE</text><text x="920" y="482" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">¥600 - already spent</text></g>
|
||||
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.53;0.5800000000000001;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="507" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="536" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">04 DECISION</text><text x="920" y="536" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">check requested amount</text></g>
|
||||
<g opacity="0"><animate attributeName="opacity" values="0;0;1;1;0" keyTimes="0;0.62;0.66;0.85;1" dur="13s" repeatCount="indefinite"/>
|
||||
<rect x="704" y="572" width="565" height="68" rx="10" fill="#193a34" stroke="#478a71"/>
|
||||
<text x="718" y="600" fill="#b5ebcb" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">✓ 已花费=120 ¥480 ≥ ¥288</text>
|
||||
<text x="718" y="625" fill="#d9f7e8" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ok: true · 本地模拟,未发送</text>
|
||||
</g>
|
||||
<g opacity="0"><animate attributeName="opacity" values="0;0;0;1;1;0" keyTimes="0;0.78;0.84;0.88;0.95;1" dur="13s" repeatCount="indefinite"/>
|
||||
<rect x="704" y="572" width="565" height="68" rx="10" fill="#42252d" stroke="#a45a67"/>
|
||||
<text x="718" y="600" fill="#f8b1bc" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">✕ 已花费=360 ¥240 < ¥288</text>
|
||||
<text x="718" y="625" fill="#fde7ea" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ok: false · 预算不足,拒绝工单</text>
|
||||
</g>
|
||||
<path d="M 652 430 C 665 429 674 429 688 430" fill="none" stroke="#f0c58c" stroke-width="3"/><circle cx="665" cy="429" r="4" fill="#f0c58c"><animate attributeName="cx" values="656;681;656" dur="2.5s" repeatCount="indefinite"/></circle>
|
||||
<text x="44" y="698" fill="#7e90a7" font-size="14" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ILLUSTRATED EXPECTED FLOW · NOT A TERMINAL CAPTURE · NO REAL PURCHASE</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 7.4 KiB |
@@ -0,0 +1,35 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1340" height="740" viewBox="0 0 1340 740" role="img" aria-label="View-inspired editorial concept for the procurement function, not a real screenshot">
|
||||
<rect x="0" y="0" width="1340" height="740" rx="0" fill="#f8f6f0" stroke="none"/>
|
||||
<rect x="0" y="0" width="1340" height="68" rx="0" fill="#f2ede4" stroke="none"/>
|
||||
<text x="69" y="45" fill="#8d7358" font-size="29" font-family="Georgia,serif" font-weight="600">marqdo</text>
|
||||
<text x="577" y="43" fill="#665d53" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">文档 函数 执行 变量</text>
|
||||
<text x="1030" y="44" fill="#998773" font-size="13" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">VIEW CONCEPT / NOT CAPTURE</text>
|
||||
<line x1="325" y1="113" x2="325" y2="688" stroke="#e0d5c7"/><line x1="1032" y1="113" x2="1032" y2="688" stroke="#e0d5c7"/>
|
||||
<text x="374" y="128" fill="#b0895e" font-size="16" font-family="Georgia,'Noto Serif CJK SC',serif" font-weight="400">采购智能体</text>
|
||||
<text x="372" y="196" fill="#39352d" font-size="37" font-family="'Noto Serif CJK SC',Georgia,serif" font-weight="600">向采购商发工单</text>
|
||||
<text x="374" y="238" fill="#5d5851" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">核对准入、价格、交付与预算之后,生成本地模拟工单。</text>
|
||||
<line x1="374" y1="267" x2="993" y2="267" stroke="#b69b78"/>
|
||||
<text x="375" y="309" fill="#514a41" font-size="21" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">参数</text>
|
||||
<text x="375" y="348" fill="#5b5146" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">采购商标识符</text>
|
||||
<text x="625" y="348" fill="#96754f" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">text</text>
|
||||
<text x="811" y="348" fill="#8e8171" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">必填</text>
|
||||
<line x1="374" y1="365" x2="994" y2="365" stroke="#ded6c9"/>
|
||||
<text x="375" y="392" fill="#5b5146" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">数量 / 单价 / 已花费</text>
|
||||
<text x="625" y="392" fill="#96754f" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">number</text>
|
||||
<text x="811" y="392" fill="#8e8171" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">必填</text>
|
||||
<line x1="374" y1="408" x2="994" y2="408" stroke="#ded6c9"/>
|
||||
<text x="374" y="463" fill="#5e584f" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">发单前,必须再次查询并核对本轮的可用余额。</text>
|
||||
<rect x="373" y="483" width="618" height="48" rx="8" fill="#ebe3d5" stroke="none"/>
|
||||
<text x="391" y="513" fill="#805b35" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">预算 = [重新查询预算](查询余额(...))</text>
|
||||
<text x="374" y="565" fill="#7b5b4b" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">1. 剩余额度 < 本单金额</text>
|
||||
<text x="374" y="612" fill="#a06b5f" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400"> 返回 [预算不足,拒绝模拟工单](...)</text>
|
||||
<text x="375" y="682" fill="#8c8276" font-size="16" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">仅在全部检查通过时产生“本地模拟、未发送”的结果。</text>
|
||||
<path d="M 408 503 C 295 503 278 339 146 339" stroke="#ba9a75" stroke-width="1.7" fill="none"/><circle cx="408" cy="503" r="4.3" fill="#ba9a75"/>
|
||||
<text x="73" y="281" fill="#a78255" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">BUDGET CHECK</text>
|
||||
<text x="73" y="315" fill="#756350" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">已花费 ¥360</text>
|
||||
<text x="73" y="343" fill="#756350" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">剩余额度 ¥240</text>
|
||||
<path d="M 823 602 C 1010 586 1026 396 1122 396" stroke="#b7837e" stroke-width="1.7" fill="none"/><circle cx="823" cy="602" r="4.3" fill="#b7837e"/>
|
||||
<text x="1080" y="319" fill="#a67871" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">REJECTION</text>
|
||||
<text x="1080" y="354" fill="#945e55" font-size="22" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">¥240 < ¥288</text>
|
||||
<text x="1080" y="393" fill="#945e55" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">拒绝工单</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 4.9 KiB |
|
After Width: | Height: | Size: 204 KiB |
|
After Width: | Height: | Size: 1.9 MiB |
|
After Width: | Height: | Size: 523 KiB |
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.1.4"
|
||||
version = "2.7.1"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
@@ -11,7 +11,7 @@ Raw `cdylib` exports — no `wasm-bindgen` CLI required.
|
||||
|
||||
```bash
|
||||
# from repo root (C5 size profile)
|
||||
marqdo wasm build -o examples/browser-hello
|
||||
marqdo call skills/marqdo-dev/index.mq.md build_browser --effects plugin,process.exec,fs.write --fs-root . --json
|
||||
# or:
|
||||
cargo build -p marqdo-wasm --target wasm32-unknown-unknown --profile release-wasm
|
||||
```
|
||||
@@ -19,3 +19,5 @@ cargo build -p marqdo-wasm --target wasm32-unknown-unknown --profile release-was
|
||||
Prints size in KiB; runs `wasm-opt -Oz` when Binaryen is on `PATH`.
|
||||
|
||||
See [doc/design/browser-marqdo-wasm.md](../../doc/design/browser-marqdo-wasm.md).
|
||||
|
||||
Use the maintained [browser-app](../../examples/browser-app/index.mq.md) for a runnable native Document and browser program. The ABI counter fixture lives in tests/wasm/counter.mq.md, with no independent HTML demo host. The former browser-hello and browser-media directories were retired in 2.7.0; their host capabilities remain documented in lib/browser.mq.md.
|
||||
@@ -228,28 +228,52 @@ function applyStyle(el, styleVal) {
|
||||
}
|
||||
|
||||
export function renderListItems(spec) {
|
||||
const tag = String(spec.tag || "li");
|
||||
const rootTag = String(spec.tag || "li");
|
||||
const items = Array.isArray(spec.items) ? spec.items : [];
|
||||
return items
|
||||
.map((it) => {
|
||||
if (it == null) return "";
|
||||
if (typeof it === "string" || typeof it === "number") {
|
||||
return `<${tag}>${escapeHtml(String(it))}</${tag}>`;
|
||||
}
|
||||
if (!isPlainObject(it)) return "";
|
||||
const text = it.text != null ? String(it.text) : it.html != null ? null : "";
|
||||
const cls = it.class != null ? ` class="${escapeAttr(String(it.class))}"` : "";
|
||||
let attrs = "";
|
||||
if (isPlainObject(it.attrs)) {
|
||||
for (const [k, v] of Object.entries(it.attrs)) {
|
||||
if (v === null || v === false) continue;
|
||||
attrs += ` ${escapeAttr(k)}="${escapeAttr(String(v))}"`;
|
||||
let count = 0;
|
||||
const render = (item, fallbackTag, depth) => {
|
||||
if (depth > 32 || ++count > 10000) throw new Error("render_list: structural limit exceeded");
|
||||
if (item == null) return "";
|
||||
if (typeof item !== "string" && typeof item !== "number" && !isPlainObject(item)) return "";
|
||||
const record = isPlainObject(item) ? item : { text: String(item) };
|
||||
const tag = String(record.tag || fallbackTag);
|
||||
if (!/^[a-z][a-z0-9-]*$/i.test(tag) ||
|
||||
/^(script|style|iframe|object|embed|link|meta|base)$/i.test(tag)) {
|
||||
throw new Error("render_list: unsupported element name");
|
||||
}
|
||||
let attrs = record.class != null ? ` class="${escapeAttr(String(record.class))}"` : "";
|
||||
if (isPlainObject(record.attrs)) {
|
||||
for (const [key, value] of Object.entries(record.attrs)) {
|
||||
if (!/^[a-z_:][a-z0-9_.:-]*$/i.test(key) || /^on/i.test(key)) {
|
||||
throw new Error("render_list: invalid attribute name");
|
||||
}
|
||||
if (value === null || value === false) continue;
|
||||
if (!["string", "number", "boolean"].includes(typeof value)) throw new Error("render_list: attributes must be scalar");
|
||||
if (/^(href|src|action|formaction)$/i.test(key) &&
|
||||
/^[\s\u0000-\u0020]*(javascript|vbscript|data)[\s\u0000-\u0020]*:/i.test(String(value))) {
|
||||
throw new Error("render_list: unsupported URL");
|
||||
}
|
||||
attrs += ` ${key}="${escapeAttr(String(value))}"`;
|
||||
}
|
||||
const inner = it.html != null ? String(it.html) : escapeHtml(text ?? "");
|
||||
return `<${tag}${cls}${attrs}>${inner}</${tag}>`;
|
||||
})
|
||||
.join("");
|
||||
}
|
||||
let inner;
|
||||
if (record.children != null) {
|
||||
if (!Array.isArray(record.children) || record.text != null || record.html != null) {
|
||||
throw new Error("render_list: children must be an unambiguous record list");
|
||||
}
|
||||
inner = record.children.map(child => render(child, "span", depth + 1)).join("");
|
||||
} else {
|
||||
// Preserve the existing explicit HTML escape hatch. Ordinary business
|
||||
// values use text/children and never become source or markup.
|
||||
inner = record.html != null ? String(record.html) : escapeHtml(String(record.text ?? ""));
|
||||
}
|
||||
if (/^(input|img|br|hr|area|col|source|wbr)$/i.test(tag)) {
|
||||
if (inner) throw new Error("render_list: void elements cannot have content");
|
||||
return `<${tag}${attrs}>`;
|
||||
}
|
||||
return `<${tag}${attrs}>${inner}</${tag}>`;
|
||||
};
|
||||
return items.map(item => render(item, rootTag, 0)).join("");
|
||||
}
|
||||
|
||||
function escapeHtml(s) {
|
||||
|
||||
@@ -1,3 +1,96 @@
|
||||
marqdo (2.7.1-1ppa2) noble; urgency=medium
|
||||
|
||||
* Release 2.7.1; see the reviewed upstream CHANGELOG.
|
||||
* Stop reapplying the engineering compatibility fix already in upstream.
|
||||
* Include cached orig bytes until publication is confirmed by Launchpad.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Wed, 11 Nov 2026 00:03:29 +0800
|
||||
|
||||
marqdo (2.7.0-1ppa2) noble; urgency=medium
|
||||
|
||||
* Repair engineering plugin compatibility for this 2.7.0 release.
|
||||
* Keep the accepted upstream orig archive; carry the fix as a quilt patch.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Tue, 10 Nov 2026 17:53:03 +0800
|
||||
|
||||
marqdo (2.7.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Release 2.7.0; see the reviewed upstream CHANGELOG.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Tue, 10 Nov 2026 16:40:29 +0800
|
||||
|
||||
marqdo (2.6.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Executable standard/extension handbooks and practical file/data/task tools.
|
||||
* Readable View action notes, knowledge contracts and offline reader support.
|
||||
* Preserve effect, platform and source compatibility boundaries.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sun, 08 Nov 2026 23:01:35 +0800
|
||||
|
||||
marqdo (2.5.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.5.1: exact source anchors, flowing annotation curves,
|
||||
staggered margin notes, connector avoidance and a labeled toolbar.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 13:05:55 +0800
|
||||
|
||||
marqdo (2.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.5.0: redesigned document reader, margin execution annotations,
|
||||
offline math/assets, navigation/search, and consistent live result refresh.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 10:00:00 +0800
|
||||
|
||||
marqdo (2.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.4.0: oracle journal as language values (foreign.oracle_journal /
|
||||
replay_check), bytecode/frontend hardening, MSRV 1.81 OnceLock wait fix.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Fri, 06 Nov 2026 15:15:00 +0800
|
||||
|
||||
marqdo (2.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.3.0: Strong foreign session — opaque Handle, affine close,
|
||||
replay_check vs oracle journal, table arity refuse, Omega V_safe gate.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 01 Nov 2026 14:45:00 +0800
|
||||
|
||||
marqdo (2.2.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.2: V_safe JSON integer contract on foreign/json bridge —
|
||||
refuse integers outside +/- (2^53-1); wide ints via decimal string.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Sat, 01 Nov 2026 09:45:00 +0800
|
||||
|
||||
marqdo (2.2.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.1: fix view/static-export outline rail under document
|
||||
(occlusion doc-block close + panel container query layout).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 11:45:00 +0800
|
||||
|
||||
marqdo (2.2.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.0: marqdo call runs one named function in any .mq.md.
|
||||
The same file stays the document, the knowledge and the program.
|
||||
Tree and bytecode both execute that function. External calls stay
|
||||
pure: write, process, network and plugin stay off by default.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 09:20:00 +0800
|
||||
|
||||
marqdo (2.1.5-1ppa2) noble; urgency=medium
|
||||
|
||||
* Rebuild 2.1.5 against Launchpad (previous 1ppa1 failed with no build log).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 09:35:49 +0000
|
||||
|
||||
marqdo (2.1.5-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.5: agent reliability workbench — ResourceView / ToolSpec /
|
||||
CheckpointV2 / EffectLedger; EKC ir.json warm-load; web short/read lanes.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 07:39:08 +0000
|
||||
|
||||
marqdo (2.1.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.4: default isolated HTTP execute (ADR 0009) — Supervisor
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
Description: Use stable Option map_or in the engineering release boundary
|
||||
Author: Marqdo Maintainers <cflmy@users.noreply.github.com>
|
||||
Forwarded: not-needed
|
||||
Last-Update: 2026-11-10
|
||||
|
||||
diff --git a/plugins/engineering/src/lib.rs b/plugins/engineering/src/lib.rs
|
||||
index 6891f01..f0c5ffc 100644
|
||||
--- a/plugins/engineering/src/lib.rs
|
||||
+++ b/plugins/engineering/src/lib.rs
|
||||
@@ -283,7 +283,7 @@ fn r2_settings(root:&Path)->Result<BTreeMap<String,String>,String> {
|
||||
}
|
||||
}
|
||||
for k in ["R2_ENDPOINT","R2_BUCKET","R2_ACCESS_KEY_ID","R2_SECRET_ACCESS_KEY"] {
|
||||
- if settings.get(k).is_none_or(String::is_empty) {return Err(format!("missing {k}; configure ~/.marqdo/r2.env"));}
|
||||
+ if settings.get(k).map_or(true, String::is_empty) {return Err(format!("missing {k}; configure ~/.marqdo/r2.env"));}
|
||||
}
|
||||
Ok(settings)
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
# engineering-stable-option.patch
|
||||
# The fix is already in upstream 2.7.1.
|
||||
@@ -19,11 +19,15 @@
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [roadmap/agent-reliability-crossrepo-2026-10-27.md](roadmap/agent-reliability-crossrepo-2026-10-27.md) | **Proposed:跨仓 Agent 可靠性开发计划**;M-A0–M-A6 ∥ Q-A0–Q-A7 排期、依赖图、F01–F20 映射、MA-T*/QA-* 验收与第一刀切片;协议真源仍见下方设计文档 |
|
||||
| [design/agent-reliability-tools-resources-2026-10-27.md](design/agent-reliability-tools-resources-2026-10-27.md) | **Proposed:智能体能力补足**;基于 `16f26d7`,增量设计错误恢复、检查点/效应账本、结构化工具、输出通道、上下文与只读资源视图;含跨仓边界、阶段计划和故障验收 |
|
||||
| [research/agent-capabilities-2026-10-27.md](research/agent-capabilities-2026-10-27.md) | **官方能力调研与源码复核**;OpenAI/Claude/Gemini/LangGraph/Deep Agents/MCP,求道当前问题 F01–F20;区分现有能力、设计推导与待实测项 |
|
||||
| [design/isolated-web-runtime-development-2026-10-26.md](design/isolated-web-runtime-development-2026-10-26.md) | **隔离执行与响应式 Web 运行时**:进程池、控制/读取分离、取消、事件恢复、发布一致性;实现见 `src/runtime/` |
|
||||
| [adr/0009-isolated-web-runtime.md](adr/0009-isolated-web-runtime.md) | **ADR 0009**:隔离 Web 运行时决策;金样例通过后替代 ADR 0008 的并行性结论 |
|
||||
| [跨库缺陷复核(2026-10-26)](../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) | **最新源码与测试证据**:实际 HTTP 路由、知识发布/阅读断点、旧缺陷处置及 1000 单元编译性能失败;需同级 qdagent checkout |
|
||||
| [design/qdagent-workbench-runtime-and-view-2026-10-25.md](design/qdagent-workbench-runtime-and-view-2026-10-25.md) | **qdagent 知识工作台框架支持**:M00–M05 合同落地中(`src/workbench/`、MLSP `capabilities` / `view.document` / `view.reference_resolve`、`tests/workbench_contracts.rs`);完整 verified 以切片验收证据为准 |
|
||||
| [design/view-knowledge-reading-experience-2026-10-24.md](design/view-knowledge-reading-experience-2026-10-24.md) | **View 知识阅读体验重设计(建议)**:正文优先、结构导航、就地知识说明、来源与运行状态、响应式线框、实现契约与验收;含当前呈现和 no-exec 反例 |
|
||||
| [design/view-readable-actions.md](design/view-readable-actions.md) | **View 阅读优化实现**:动作留在正文、实际逻辑引到侧注、空逻辑明确标识;语法阅读指南、输入输出与依据卡片、单文件依赖分析及浏览器验收 |
|
||||
| [roadmap/qdagent-knowledge-support-gaps-2026-10-24.md](roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) | **求道知识沉淀与文档编译支撑缺口**:2.1.1 源码复核、来源/依赖失效反例、验证与 Agent 协议、语法提示词、导入底座及跨库分工 |
|
||||
| [design/document-native-development-guide.md](design/document-native-development-guide.md) | **下一阶段开发指导**:语法审查裁决、正文→命名→复用工作流、AI 上下文与局部编辑、渐进严格、作者成本及 S0–S6 验收 |
|
||||
| [design/core-surface.md](design/core-surface.md) | **核心构造清单**:v2.1 默认链接/循环说明与构造守卫;不是全部实现状态清单 |
|
||||
@@ -45,6 +49,7 @@
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
|
||||
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
|
||||
| [design/module-namespace.md](design/module-namespace.md) | **模块命名空间:导入绑定库名、`库.成员` / `use`(M1+M2 已落地)** |
|
||||
| [library-development.mq.md](library-development.mq.md) | **可执行库开发指南**:单文件标准库、多文件拓展库、叙述超过 50%、标题下参数与返回表、句中赋值/返回和遮蔽调用;含真实调用及失败场景 |
|
||||
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
|
||||
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
|
||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
|
||||
@@ -75,7 +80,7 @@
|
||||
| [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 验收) |
|
||||
| [design/ext-web-go-rewrite.md](design/ext-web-go-rewrite.md) | **`plugins/web` Go 全量重写**(多语言 ABI · 网页制备完备 · 独立工作流验收) |
|
||||
| [adr/0004-web-plugin-go.md](adr/0004-web-plugin-go.md) | **Accepted:web 原生插件实现语言为 Go** |
|
||||
| [research/ext-web-customization-limits.md](research/ext-web-customization-limits.md) | **`ext/web` 定制限制踩坑盘点**(路由/壳 CSS/鉴权/样式/部署) |
|
||||
| [design/ext-web-customization/](design/ext-web-customization/) | **对应解决设计**(C0–C4:前缀可让出、shell_css、gate、布局…) |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# ADR 0004:网络拓展库原生实现改为 Go
|
||||
|
||||
历史说明(2026-11-10):下文业务站点仅记录当时决策背景,相关工程已移出本仓库;当前验收使用维护中的完整站点、网络站点及隔离测试,见 [当前工作流](../design/ext-web-go-rewrite.md#8-独立工作流与隔离验收)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**;HTTP **execute** 路径正式替代 [ADR 0008](0008-web-invoke-serialization.md) 的并行性结论。`legacy_serial`(未声明且非流式)仍引用 0008 单飞 / 父进程 `CallLibPath`。 |
|
||||
| 日期 | 2026-10-26 |
|
||||
| 日期 | 2026-10-26(修订 2026-10-27:disconnect≠cancel;control/read/short 无父锁) |
|
||||
| 设计 | [isolated-web-runtime-development-2026-10-26.md](../design/isolated-web-runtime-development-2026-10-26.md) |
|
||||
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝) |
|
||||
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝;disconnect-keeps-running;control-under-dual-execute) |
|
||||
|
||||
## 背景
|
||||
|
||||
@@ -14,18 +14,20 @@ ADR 0008 确认:Go HTTP 多线程,但所有 Endpoint 共享一把解释器
|
||||
## 决策
|
||||
|
||||
1. **首选架构**:预热的一次性 Marqdo worker 进程池;每个租约独占一个进程与 HostContext。
|
||||
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` 或 body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);禁止父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。`short` / `read` / `control` 仍父进程短路径;未声明非流式 → `legacy_serial`。
|
||||
3. **控制/读取分离**:取消与事件订阅不进入任务解释器锁;短业务与长执行有独立容量(execute 槽默认 2)。
|
||||
4. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
|
||||
5. **能力探测**:`runtime.isolated_execution=1`(默认)、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`;`runtime.read_lane` 仍 0。
|
||||
6. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
|
||||
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` / body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);**禁止**父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。声明的 `short`/`read`/`control` 走父进程短路径(execute 已离进程,父锁通常空闲);未声明非流式 → `legacy_serial`。
|
||||
3. **控制/读取分离**:`/_runtime/*`(cancel、events、task get)不进入解释器锁。短读勿挤占 execute worker 槽(池默认 2);产品 cancel 优先 `/_runtime`。
|
||||
4. **订阅 ≠ 取消**:`sse-live` 观察者 `ctx.Done()` 默认**只结束订阅**,不 `runtime.cancel`;后台仍 reap worker 以释放槽。仅显式 header `X-Marqdo-Cancel-On-Disconnect: 1` 才 disconnect=cancel。同步 `waitIsolatedJSON` 可保留 disconnect 取消。重连:`GET /_runtime/tasks/{id}/events` + `Last-Event-ID` / `after_seq`。
|
||||
5. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
|
||||
6. **能力探测**:`runtime.isolated_execution=1`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane=1`(短读不与 execute 抢父锁)。
|
||||
7. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
|
||||
|
||||
## 后果
|
||||
|
||||
- Execute / live SSE 不再抢进程级 SSE 桥;双流可并行(MR-01)。
|
||||
- 短读走父进程:在 dual execute 下通常仍 200(父锁空闲);勿把 short/read/control 塞进 2 槽 execute 池。
|
||||
- Legacy 未声明非流式路径仍可走父进程锁(ADR 0008)。
|
||||
- 产品(qdagent)cancel / Last-Event-ID 接线仍为后续;不阻碍本框架发版。
|
||||
- 产品(qdagent)`turn_events` / Last-Event-ID / cancel CAS 接线由 qdagent 验收;框架侧 disconnect≠cancel 与 `/_runtime` 无锁控制面已落地。
|
||||
|
||||
## 验收(摘要)
|
||||
|
||||
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`。其余见设计文档 §12。
|
||||
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`、`runtime.read_lane=1`。观察者断连后任务仍跑完并可经 `/_runtime` 重放。其余见设计文档 §12。
|
||||
@@ -0,0 +1,348 @@
|
||||
# Marqdo 智能体能力补足:恢复、工具、上下文与资源视图
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed**;本次交付设计,不代表以下新接口已实现 |
|
||||
| 日期 / 基线 | 2026-10-27(Asia/Shanghai);Marqdo `16f26d7` / 2.1.4;qdagent `68b757e` |
|
||||
| 调研与现状 | [官方资料与源码证据 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品配套 | [qdagent 智能体能力与预览设计](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 继承 | [ext/agent](ext-agent.md)、[隔离 Web 运行时](isolated-web-runtime-development-2026-10-26.md)、[工作台合同](qdagent-workbench-runtime-and-view-2026-10-25.md) |
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;让工具可发现、可验证、可审计;让结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位,不把框架改成第二套产品聊天服务。
|
||||
|
||||
现有 `src/runtime/` 已实现隔离进程、任务/事件与控制通道,本设计在其上补 Agent 步骤语义。现有 `ext/ai/agent.mq.md` 已有 step/plan/run、CALL/READ、观察压缩,继续扩展。框架不持有求道“笔记”业务表、中文按钮、默认回答字数或具体供应商账户。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | 错误分类、预算、检查点、工具效应、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | 结果分通道、输出预算、角色消息、finish reason | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD 行为 |
|
||||
| 资源 | ResourceRef、只读内容/派生预览、定位、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览组件和布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
APP[qdagent 产品策略与授权] --> RUN[ext/ai/agent step / plan / run]
|
||||
RUN --> CTX[ContextPack 与预算]
|
||||
RUN --> LLM[LLM Adapter]
|
||||
RUN --> DISPATCH[Tool Dispatcher]
|
||||
DISPATCH --> LOCAL[受控 Marqdo 函数]
|
||||
DISPATCH --> MCP[MCP Client]
|
||||
DISPATCH --> RES[资源读取 / 转换]
|
||||
RUN --> REC[Checkpoint / Effect Ledger]
|
||||
REC --> RT[既有 runtime task store / event log]
|
||||
RUN --> OUTPUT[answer / artifact / progress / diagnostic]
|
||||
RES --> VIEW[DocumentView / ResourceView]
|
||||
OUTPUT --> APP
|
||||
VIEW --> APP
|
||||
```
|
||||
|
||||
## 2. 现状与增量
|
||||
|
||||
| 已有能力 | 本轮不能误判为缺失 | 要补的具体语义 |
|
||||
|---|---|---|
|
||||
| runtime.task_control_v2/event_replay/read_lane | 不再新建一套队列与 SSE 框架 | Agent 步骤恢复与传输重放的边界 |
|
||||
| resume_save/load | 不再新建平行 checkpoint 命名空间 | 原子提交、版本摘要、作用域、效应关联 |
|
||||
| CALL、ARGS、READ、plan patch | 不废弃文档式编排 | 类型化 schema、校验错误、有限修复、稳定 call_id |
|
||||
| MCP stdio client | 不从零重写连接器 | timeout/cancel、resource、远程 transport 的能力探测 |
|
||||
| DocumentViewV1 / Locator | 不另写 `.mq.md` 解析器 | 普通资源类型、明确 renderer、历史与相对资源处理 |
|
||||
| LLM messages/usage | 不把 provider 行为交给产品猜测 | 输出预算、原生工具适配探测、角色边界与分通道 |
|
||||
|
||||
新模块路径及协议名以下均是**建议落点**。首批开发先固化 schema 与 fixture,再开放 feature bit;不得只更新 capabilities 把未实现能力标真。
|
||||
|
||||
## 3. 错误和恢复合同
|
||||
|
||||
### 3.1 ErrorV1
|
||||
|
||||
现有字符串错误保留兼容适配,新工具与 Agent 结果返回:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentErrorV1",
|
||||
"code": "tool.timeout",
|
||||
"category": "transient",
|
||||
"stage": "tool",
|
||||
"message": "读取资源超时",
|
||||
"retryable": true,
|
||||
"retry_after_ms": 1200,
|
||||
"effect_state": "none",
|
||||
"recovery_action": "retry_step",
|
||||
"call_id": "call_01",
|
||||
"details_ref": "resource:diagnostic_01"
|
||||
}
|
||||
```
|
||||
|
||||
`retryable` 仅是候选信息,最终动作由可信策略结合效应、截止时间、预算、取消状态决定。远端工具声称 readOnly/idempotent 不构成授权依据。凭证和原始堆栈不进入公开 message。
|
||||
|
||||
| 错误类别 / 例子 | 框架动作 | 不允许的动作 |
|
||||
|---|---|---|
|
||||
| transient:429、部分 5xx、连接失败 | 只在安全步骤重试,遵守 Retry-After | 无限重试、复用同一流片段直接追加 |
|
||||
| invalid_arguments:schema 不匹配 | 把字段级错误作为 observation,最多 1 次参数修复 | 启动工具后才校验;静默丢弃字段 |
|
||||
| validation_failed:编译/文档校验 | 保留候选与诊断,局部修复后重新验证 | 将未验证草稿标为成功 |
|
||||
| context_overflow | 压缩可重建上下文,保留任务/限制/未决效应 | 丢失最新用户指令、授权或版本 |
|
||||
| auth / forbidden | 直接 needs_input/blocked,交应用处理 | 换身份、扩大范围或匿名绕过 |
|
||||
| conflict / stale_revision | 重新读取版本并重新规划 | 覆盖用户修改、对写操作盲重试 |
|
||||
| capability_unavailable | 返回可行替代操作清单 | 假称已搜索、已渲染或已执行 |
|
||||
| policy_denied | 显式拒绝该动作 | 把限制当工具错误让模型规避 |
|
||||
| budget_exhausted | 保存状态与已完成结果,返回 partial | 自动增预算或伪造 completed |
|
||||
| unknown_effect / worker_crash | 对账、查询外部状态,不能判断则 needs_reconciliation | 重跑整个工作簿 |
|
||||
| cancelled | 停止新调用、保留可读产物、传播取消 | 在后台悄悄修复或恢复 |
|
||||
|
||||
初始建议:传输最多 2 次重试(总 3 次尝试),指数退避基准 0.5/1 秒并加 jitter;有 Retry-After 时使用服务端建议并受总 deadline 限制。参数修复最多 1 次,内容修复最多 2 次。预算由应用传入,框架只提供默认上限与执行机制。所有重试、修复和摘要模型调用计入同一成本账本。
|
||||
|
||||
错误指纹 `hash(tool_id, normalized_arguments, error_code, relevant_revision)` 连续出现 2 次且没有新证据时中止该策略,允许一次有依据的替代路径;不能通过改写错误文本绕过循环检测。
|
||||
|
||||
### 3.2 四类“恢复”必须分开
|
||||
|
||||
1. **续订事件**:客户端从 cursor 重放和订阅同一个 task,不发起新推理。
|
||||
2. **重试步骤**:相同逻辑 operation、同幂等键;新 invocation attempt,复用成功的前序结果。
|
||||
3. **恢复工作流**:从兼容 checkpoint 建立新 runtime task / attempt,关联 `resumed_from`,不把旧终态改回 running。
|
||||
4. **重新生成答案**:新的输出版本;已有成功工具结果可复用,用户明确重新执行才重新产生效应。
|
||||
|
||||
当前 TaskState 把 interrupted/needs_reconciliation 视为终态,沿用此约定。新增 `AgentRun` 逻辑关联只管理目标和 attempt 链;调度权仍在原 runtime。恢复请求带 `expected_revision`、checkpoint digest 与幂等键,相同请求返回同一新 attempt,冲突返回 409 对应的框架错误。
|
||||
|
||||
执行失败不必丢掉有用内容:`outcome.status = succeeded | partial | failed | needs_input | cancelled`,伴随 `answer_ref/artifacts/error/recovery_options`。HTTP 调用成功与 Agent 业务 succeeded 不再混为同一字段。
|
||||
|
||||
## 4. 检查点与工具效应
|
||||
|
||||
### 4.1 CheckpointV2
|
||||
|
||||
在 `plugins/agent/src/resume.rs` 扩展已有实现,统一根目录由宿主提供,客户端不能传任意绝对路径。保留 legacy load,但旧 checkpoint 无效应信息时默认 `manual_review`,不能自动重做写操作。
|
||||
|
||||
| 字段组 | 内容 |
|
||||
|---|---|
|
||||
| 身份 | schema、checkpoint_id、logical_run_id、task_id、attempt_id、step_id、parent_checkpoint_id |
|
||||
| 作用域 | principal_ref、workspace_id、session_id、授权 scope digest |
|
||||
| 输入 | task revision、workbook revision/hash、输入资源 revisions、knowledge generation |
|
||||
| 运行配置 | ModelSnapshot public ref、tool registry digest、policy revision、runtime compatibility |
|
||||
| 进度 | completed_steps、pending_operation、observation refs、context summary ref |
|
||||
| 约束 | 剩余 token/tool/time/cost 预算、deadline、cancel epoch |
|
||||
| 一致性 | effect ledger watermark、event seq、manifest digest、committed_at |
|
||||
|
||||
写入协议:写唯一临时文件→flush/fsync→原子 rename→提交 checkpoint 指针;持久化配置下目录 fsync 按平台支持实现。所有引用 blob 在指针提交前落盘。损坏记录报 `checkpoint.corrupt` 并尝试上一个完整版本,不能读取半个 JSON 当无历史。
|
||||
|
||||
恢复前校验身份/授权、源版本、工具 schema 与模型兼容性。权限撤销立即生效;checkpoint 不是永久授权。源文件改变返回 `checkpoint.input_changed`,重新计划受影响步骤,不能偷偷使用最新文件继续旧验证结果。
|
||||
|
||||
### 4.2 Effect ledger
|
||||
|
||||
```text
|
||||
prepared → started → committed
|
||||
↘ failed_no_effect
|
||||
↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
|
||||
```
|
||||
|
||||
每个 operation 持久记录 `operation_id/idempotency_key/args_digest/resource_scope/expected_revision/effect_class/result_ref`。幂等键作用域是 principal + workspace + logical_run + step + operation,不用随机 attempt ID 替换稳定 operation key。对同 key 不同 payload 拒绝。
|
||||
|
||||
读工具可重试;确定幂等写由服务端去重;可补偿写仅在补偿明确安全时执行;未知写先查询 receipt/版本。对外部系统不能承诺通用 exactly-once。关键 crash 窗口是“远端已成功、本地尚未记账”,必须返回 unknown 并对账。
|
||||
|
||||
本地文件使用 expected revision + staging + atomic replace;变更提交后检查点失败也靠 operation receipt 恢复。`tool.completed` 必须在结果与 receipt 可读取后提交,再对外发事件。事件发送失败不回滚已发生的业务效应。
|
||||
|
||||
不要复制 runtime 事件存储:Agent ledger 与 artifact manifest 是步骤事实,现有 runtime event log 是传输/调度事实;以 ID 关联,采用可重建投影与 outbox。跨 DB/文件不能声称一个事务完成,使用 manifest 提交点和恢复扫描补齐索引。
|
||||
|
||||
## 5. 结构化工具与调度
|
||||
|
||||
### 5.1 ToolSpecV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ToolSpecV1",
|
||||
"id": "workspace.read",
|
||||
"version": "1",
|
||||
"description": "读取授权资源的指定行范围",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"resource_id": {"type": "string"},
|
||||
"revision": {"type": "string"},
|
||||
"start_line": {"type": "integer", "minimum": 1},
|
||||
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
|
||||
},
|
||||
"required": ["resource_id"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"output_schema_ref": "ResourceReadV1",
|
||||
"effect": "read",
|
||||
"scopes": ["workspace:read"],
|
||||
"timeout_ms": 10000,
|
||||
"max_result_bytes": 65536,
|
||||
"idempotency": "safe",
|
||||
"concurrency_group": "resource-read",
|
||||
"availability": "ready"
|
||||
}
|
||||
```
|
||||
|
||||
定义由宿主/可信模块注册;用户认证、scope 与资源根由宿主注入,不接受模型提供 principal 或任意 root。`read`、`write`、`execute`、`external_write` 是策略分类,不是靠工具命名推断。
|
||||
|
||||
ToolCallV1:`call_id/tool_id/tool_version/arguments/operation_id/parent_span_id`。ToolResultV1:`ok/status/summary/structured_content/resources/citations/error/usage/truncated/next_cursor/effect_receipt_ref`。超限结果先写 artifact,再返回摘要和范围读取句柄;不把几十 MB 文本送进 prompt。
|
||||
|
||||
### 5.2 一条执行通道
|
||||
|
||||
```text
|
||||
发现 → 加载 schema → schema 校验 → 授权与范围解析 → 预算/取消检查
|
||||
→ 幂等查询 → 执行 → 结果 schema/大小校验 → receipt/结果提交 → 事件 → observation
|
||||
```
|
||||
|
||||
provider 原生 function call 与文档 `CALL:name + ARGS:{...}` 都归一到该通道。保留旧白名单适配,已有 `.mq.md ##` 可根据形参推导初始 schema,再允许显式描述收紧。转换不允许调用未暴露的框架内部函数。禁止对模型参数使用 eval/任意代码反序列化。
|
||||
|
||||
`tools.search` 返回已授权且当前可用的工具摘要;`tools.describe` 按 ID 返回完整 schema。核心 5–8 个工具可常驻,其余按需加载;此数量是产品起始配置,不写死框架。每次真正调用仍重新检查授权;搜索索引可列 unavailable 原因供诊断,但不能让未授权工具名字泄露私有连接信息。
|
||||
|
||||
初始支持 JSON Schema 的明确子集并公开能力;不支持的 schema 拒绝注册,不静默放宽。原生工具能力、并行工具调用、图片输入、结构化输出分别探测;纯文本兼容 provider 继续走 CALL,但并发和可靠性承诺按测试能力开放。
|
||||
|
||||
### 5.3 并发、MCP 与程序化执行
|
||||
|
||||
独立只读调用可并发,默认最多 4 个;修改同一资源的调用串行且用 revision CAS。依赖链、审批与取消检查保持顺序。一个并发调用失败不丢弃其他已成功结果。
|
||||
|
||||
MCP 扩展现有 client:先完善 timeout/cancel、错误映射、工具分页与 schema、resource read/link,再按 capability 增加远程 Streamable HTTP 与连接认证。stdio 不应允许模型选择任意宿主可执行文件。连接元数据归应用,凭证通过 secret handle 注入 worker,工具输出和 trace 不记录密钥。
|
||||
|
||||
工具 annotations 只是提示,可信策略确定真实效应。外部结果全部为数据,不能提升为 standing/system。MCP resource URI 转成宿主授权 ResourceRef,不允许前端直接请求任意 file:// 或内部网地址。
|
||||
|
||||
程序化工具编排和子 Agent 为后续切片:在沙箱中仅暴露注册 dispatcher,逐次执行同样的授权、预算和效应日志;禁止通过一段脚本绕过逐工具控制。子任务继承更小权限和共享总预算,不默认开放写同一资源。
|
||||
|
||||
## 6. 输出通道与上下文
|
||||
|
||||
### 6.1 AgentOutputV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentOutputV1",
|
||||
"status": "succeeded",
|
||||
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
|
||||
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
|
||||
"citations": [],
|
||||
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
|
||||
"finish_reason": "completed",
|
||||
"recovery_options": []
|
||||
}
|
||||
```
|
||||
|
||||
这是结果传输协议,不要求模型每次逐字生成这张 JSON。文档式编排仍可产出 `.mq.md`,框架把稳定产物、摘要与事件归一化。普通文本回答可没有 artifact 和 validation;未运行的内容标 `not_applicable/not_run`,不能填 passed。
|
||||
|
||||
channel 至少区分 `answer/artifact/progress/diagnostic`。只有 answer delta 可追加到聊天正文;工作簿 token 和工具日志进入其他通道。进度是可观察动作摘要,不要求或泄露模型内部思维链。
|
||||
|
||||
应用传 `ResponsePolicy`:detail level、目标长度、最大输出 tokens、是否允许 artifact、用户显式需求。框架负责 budget 和 finish_reason,中文字符数与最终文案由应用决定。达到 token 上限返回 `length_limited` 和完整/不完整标记,不能裁剪 JSON/代码后假装成功。
|
||||
|
||||
优先从已验证产物结构投影摘要。必要时增加一次受预算控制的摘要模型调用;摘要不得新增未经证据支持的结论。修复成功后 accepted candidate、结果正文、artifact revision 与 verification digest 必须全部一致。
|
||||
|
||||
### 6.2 ContextPackV2
|
||||
|
||||
按优先级组装:可信运行规则→最新用户目标/约束→用户选中资源范围→未决操作/成功步骤摘要→检索证据→近期对话→可回读历史。保持角色结构,不把用户/工具文本简单拼进系统指令。
|
||||
|
||||
每个 item 携带 `origin/trust/resource_ref/revision/token_estimate/priority`。预算初值建议保留模型窗口 20% 给输出与协议开销;上下文使用达到可用预算 70% 时触发整理,具体比例配置化。优先剔除可重读的完整工具输出,保留摘要、引用和失败恢复锚点。
|
||||
|
||||
Compaction 必须保留:目标、用户限制、当前计划、已完成步骤、待决写入、授权范围、输入版本、已接受产物与引用、余量。summary 绑定其 source event range 和 digest,不能当成新的已验证知识。工具输入过时须重读,不能依赖压缩摘要执行写入。
|
||||
|
||||
已有 EKC/agent memory 继续提供知识发现和复用。长期用户记忆的创建/修改/删除政策归 qdagent;网页中的指令不能自动变成长期偏好。
|
||||
|
||||
## 7. 统一资源与只读视图
|
||||
|
||||
### 7.1 ResourceRefV1 / ResourceViewV1
|
||||
|
||||
ResourceRef 统一携带 `resource_id/workspace_id/kind/media_type/revision/digest/title/size/origin/locator`;opaque ID 由宿主映射,不将浏览器 path 直接当文件权限。revision 是内容版本,generation 是知识发布代,两者不混用。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ResourceViewV1",
|
||||
"resource": {
|
||||
"resource_id": "res_01", "workspace_id": "ws_01", "kind": "file",
|
||||
"revision": "sha256:example", "media_type": "text/markdown", "title": "设计说明"
|
||||
},
|
||||
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
|
||||
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
|
||||
"outline": [],
|
||||
"locators": [],
|
||||
"completeness": "complete",
|
||||
"no_exec": true,
|
||||
"diagnostics": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
```
|
||||
|
||||
继续把 `.mq.md` 交 `view.document`,ResourceView 只包装/扩展,不能另解释一套 Marqdo 语义。普通 `.md/.txt/代码/JSON/CSV` 走媒体类型处理,避免全仓语义编译。浏览器组件由 qdagent 实现,框架只提供可读内容、受控片段或短期授权 blob 引用。
|
||||
|
||||
`fragment`、`text`、`blob_ref` 是互斥载荷,按严格 format enum 解码。未知格式返回 unsupported,不能用 `format.includes('html')` 猜测 HTML。为空与加载失败必须有独立状态。
|
||||
|
||||
### 7.2 格式矩阵
|
||||
|
||||
| 格式 | 框架提供 | 前端消费 | 未具备能力时 |
|
||||
|---|---|---|---|
|
||||
| `.mq.md` | 静态 DocumentView、outline、节点/引用 | 正文、语义链接、源码切换 | 只读源码 + 明确诊断,不执行 |
|
||||
| Markdown / 笔记正文 | 共享静态 Markdown→受控结构/HTML、相对资源引用 | 标题、列表、表格、代码、链接 | 纯文本 |
|
||||
| 文本/代码 | 分页行片段、编码信息、行定位 | 行号与语法高亮 | 编码提示/下载 |
|
||||
| JSON / CSV | 有界解析、路径/行列定位、分页 | 树/表/源码 | 原始文本,标格式错误 |
|
||||
| 图片 | 授权 blob、尺寸/元信息 | 缩放/旋转/替代文本 | 下载,不暗示已做 OCR |
|
||||
| PDF | blob、页元信息,可选提取插件 | PDF.js 页渲染与定位 | 文件卡;提取不可用不阻止支持的视觉预览 |
|
||||
| DOCX/XLSX/PPTX | 受限转换插件,可选 PDF/HTML 派生物 | 按派生格式预览 | 未安装转换器,保留下载 |
|
||||
| HTML/SVG | 默认源码;允许时经严格清洗或受限派生物 | 隔离预览 | 不以内联可执行页面显示 |
|
||||
| 未知二进制/压缩包 | 元数据 | 下载卡 | 不自动解压/执行 |
|
||||
|
||||
提取、预览、执行各有独立 capability。办公转换、OCR 使用受限 worker,禁宏与网络、限制时间/内存/页数/解压膨胀比;结果绑定原件 digest、转换器版本和参数。首期不承诺保真编辑。
|
||||
|
||||
### 7.3 安全、定位、缓存
|
||||
|
||||
所有读取先校验宿主授予的 workspace/resource scope,canonicalize 并处理 symlink 逃逸;读取句柄与校验对象一致,防路径检查后替换。读取原件的身份权限不可被缓存绕过。
|
||||
|
||||
预览绝不调用 `run/verify` 或有执行副作用的 view 路径;正文中的 Marqdo 调用链接只展示语义与导航,执行需单独工具调用与授权。远程图片、相对链接、资源 URL 经受控解析;下载入口不允许任意内网 fetch。
|
||||
|
||||
HTML 清洗在框架产出侧和浏览器插入侧都有明确边界;用成熟 allowlist 实现而非正则。禁止 script/event handler、危险 URI、任意 style/form/嵌入对象。前端配 CSP;对需要交互的产物另建无权限 sandbox,不复用文档渲染器。
|
||||
|
||||
缓存 key:workspace + resource ID + revision + renderer version + render options + policy version;命中前重新授权。历史 revision 不存在就返回 `version_unavailable`,不能默默展示当前版。locator 支持 node/span/line/page/cell,失效时标 stale 并提供用户主动查看最新版的操作。
|
||||
|
||||
建议首期限制:文本片段 256 KiB、代码单次 500 行、CSV 单次 200 行;更大内容分页,完整文件保留。数值需压测校准,不作为现有系统性能声明。
|
||||
|
||||
## 8. 事件、可观测性与能力协商
|
||||
|
||||
复用 RuntimeEventV2 的 task/run/attempt/seq/event_id。拟增加事件类型:`agent.step.started/completed`、`tool.started/completed/failed`、`recovery.scheduled/exhausted`、`checkpoint.committed`、`artifact.updated`、`answer.delta/committed`、`context.compacted`。现有 `message.delta` 由兼容适配映射 answer channel,不能同时重复消费两套事件。
|
||||
|
||||
终态提交包含 accepted output manifest、last_seq、result digest;断流客户端能通过快照补齐最终答案。stream delta 是预览,最终 committed revision 是权威。统计每次尝试的 usage,摘要和修复调用分别标 purpose;未知计量保持 unknown。
|
||||
|
||||
拟新增 capability:`agent.error_v1`、`agent.checkpoint_v2`、`agent.tool_schema_v1`、`agent.output_channels_v1`、`agent.context_pack_v2`、`resource.view_v1`,以及各 media renderer 的独立版本/可用状态。保持现有 probe,新增字段向后兼容;未知 feature 当不可用。
|
||||
|
||||
trace 记录因果 ID、耗时、错误类别、参数摘要、资源版本和 effect receipt。正文与密钥按配置脱敏,不默认把用户全文件复制进日志。输出中不包含模型私有推理;可审计的是实际动作与结果。
|
||||
|
||||
## 9. 分阶段实现与文件落点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 依赖 / 退出条件 |
|
||||
|---|---|---|---|
|
||||
| M-A0 | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | 上述协议、旧适配、状态映射 | 先冻结跨仓字段,未知字段/版本可降级 |
|
||||
| M-A1 | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、新 recovery/effects 支撑模块 | 分类错误、有界修复、accepted candidate、原子检查点 | M-A0;故障注入不重复写、旧记录不冒险自动恢复 |
|
||||
| M-A2 | `plugins/agent/src/lib.rs`、`mcp_client.rs`、新 tool registry/dispatcher | schema 工具、调用统一、分页与结果资源 | M-A0;未授权调用为 0,失败结果结构正确 |
|
||||
| M-A3 | `src/workbench/document_view.rs`、新 resource_view、媒体适配模块 | ResourceRef/View、普通格式静态阅读、no-exec | M-A0;资源定位与安全语料通过 |
|
||||
| M-A4 | `ext/ai/agent.mq.md`、`plugins/llm/src/lib.rs`、`src/workbench/run_context.rs` | 输出分通道、预算、ContextPackV2 | M-A1/2;原生和纯文本 provider fixture 都可用 |
|
||||
| M-A5 | `src/runtime/` 的既有存储/事件适配、MCP 与转换插件 | 恢复对账、PDF/Office 插件、远程 MCP | M-A1/2/3;持久模式 crash/restart 通过 |
|
||||
| M-A6 | plan/subtask/sandbox 扩展 | 程序化工具、有界委派与可选浏览器 | 后置;须证明任务收益和预算/效应可控 |
|
||||
|
||||
先交 M-A0 与 qdagent P0 的静态阅读/错误结果修复;不要让完整 checkpoint v2 阻塞笔记预览。M-A1 可先上只读重试,写恢复待 ledger 通过再开放。新特性默认关闭直到对应合同实测通过,旧路径继续可读。
|
||||
|
||||
## 10. 验收与评测
|
||||
|
||||
所有目标是 proposed gate,尚未实测。基础机制用确定性 fake provider/tool;真实 provider 做少量单独 smoke 并记录费用,不能把随机模型输出作为唯一门禁。
|
||||
|
||||
| 编号 | 故障/任务 | 必须观察到的结果 |
|
||||
|---|---|---|
|
||||
| MA-T01 | 第一次 429、第二次成功 | 尊重退避、计量 2 次、最终只有一个 accepted answer |
|
||||
| MA-T02 | 连续 schema 参数错误 | 一次修复后停止;工具未在无效参数下执行 |
|
||||
| MA-T03 | 工具写成功但 receipt 提交前杀 worker | unknown_effect→查询对账;写计数不增加 |
|
||||
| MA-T04 | checkpoint 写一半杀进程 | 读取上个完整 checkpoint 或明确 corrupt,不产生伪成功 |
|
||||
| MA-T05 | 终态事件丢失、cursor 重放 | 最终快照恢复完整消息,工具执行次数不增加 |
|
||||
| MA-T06 | 恢复请求重复/并发 | 同一幂等键只产生一个恢复 attempt |
|
||||
| MA-T07 | 用户取消与重试定时器竞争 | 取消生效后无新工具调用,旧任务不复活 |
|
||||
| MA-T08 | 执行中资源/权限改变 | stale/conflict/forbidden,不覆盖新版本 |
|
||||
| MA-T09 | 恶意文本伪造 CALL/system | 不跨越工具白名单和授权范围 |
|
||||
| MA-T10 | `.mq.md` 预览含写文件/联网语句 | 哨兵文件/网络计数不变;只读渲染成功或安全降级 |
|
||||
| MA-T11 | 资源格式、超长输出、路径逃逸 | 正确 renderer/分页;越界拒绝;无 HTML 注入 |
|
||||
| MA-T12 | 修复原文 A 得到通过验证的 B | answer/artifact/verification 都绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后继续 | 最新约束、待决效应、资源版本与剩余预算不丢失 |
|
||||
| MA-T14 | 旧 CALL、旧 DocumentView 消费端 | 基础行为可用,能力缺失有明确返回 |
|
||||
|
||||
先运行受影响的 Rust/Go/Marqdo 合同与既有隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标:已缓存 100 KiB 文本视图服务端 p95 < 300 ms、核心工具发现 p95 < 100 ms,基准机器/并发/冷暖缓存必须记录;第三方网络延迟单独列出。
|
||||
|
||||
## 11. 迁移、回滚与未决项
|
||||
|
||||
兼容迁移按“新增协议→双读→新写→验证→逐步移除旧适配”推进。`.mq.md` 源码与旧运行产物不批量重写;旧 resume JSON 可读取但不能自动升级成带副作用保证的检查点。v2 checkpoint/ledger 保留 schema 版本,新老版本不并发写同一运行。
|
||||
|
||||
回滚关闭新工具自动发现、输出通道或转换器时,已提交资源和最终答案仍可读;执行恢复中的任务先 drain/停止接纳,不能切回会盲重做写操作的旧路径。迁移前备份可变索引与 manifest,回滚不删除用户产物。
|
||||
|
||||
实现前验证项:现有 runtime 持久存储可提供的原子提交边界、各平台 fsync/rename 行为、LLM adapter 原生 tool call 流式兼容、转换插件部署体积。协议优先按本文保守语义实现,验证不能满足则 feature 保持不可用,不阻塞已经完成的只读预览切片。
|
||||
@@ -1,5 +1,8 @@
|
||||
# 浏览器 Marqdo(WASM 解释器)设计
|
||||
|
||||
> 2.7.0 维护说明:独立的 browser-hello 与 browser-media 演示已删除。下文保留既有能力设计与宿主边界,当前可运行工程使用 browser-app;底层计数器冒烟夹具位于 tests/wasm/counter.mq.md。Canvas、音频等仍是 lib/browser 的宿主能力,不宣称当前 browser-app 演示包含这些交互。
|
||||
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted(设计锁定)** · 实现见路线图 C0–C5 |
|
||||
@@ -124,7 +127,7 @@ source: &str (+ optional import map)
|
||||
| `marqdo`(根) | 核心;feature-gate |
|
||||
| `crates/marqdo-wasm` | `cdylib`:`mq_*` ABI + `js/marqdo-bridge.js` |
|
||||
| `ext/web` 或 `web/browser` | L1:`浏览器.运行` / `交互装配`(C3+) |
|
||||
| `examples/browser-hello/` | 静态页 + wasm 冒烟 |
|
||||
| `examples/browser-app/` | 静态页 + wasm 冒烟 |
|
||||
| `tests/browser/` 或金样脚本 | Node/wasmtime 跑 `run_source` 对齐 |
|
||||
|
||||
发行:`marqdo wasm build`(C2 CLI 糖)或 `wasm-pack build crates/marqdo-wasm`。
|
||||
@@ -210,7 +213,7 @@ L1 `浏览器.交互装配`(ext)可后置;C3 以 bridge + 返回 wire 表
|
||||
|
||||
Bridge:`applyEffects(exports, value)` — 先 DOM,再调度异步;**不**在 WASM 内阻塞。
|
||||
|
||||
示例见 `examples/browser-hello/fetch.mq.md`。
|
||||
示例见 `examples/browser-app/static/app.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
@@ -251,7 +254,7 @@ marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
|
||||
# app.static dir=static
|
||||
```
|
||||
|
||||
业务页再 `boot` 自己的 `.mq.md`(见 `examples/browser-hello/`)。
|
||||
业务页再 `boot` 自己的 `.mq.md`(见 `examples/browser-app/`)。
|
||||
|
||||
---
|
||||
|
||||
@@ -261,7 +264,7 @@ marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
|
||||
|----|------|
|
||||
| 单元 | `run_source("…# main\n> print…")` native 与 wasm 同测 |
|
||||
| 金样子集 | `tests/structure/hello.mq.md` 等无 fs/net/plugin 的样例 |
|
||||
| 浏览器冒烟 | `examples/browser-hello`:按钮点击 → Marqdo 函数 → 改 DOM 文本 |
|
||||
| 浏览器冒烟 | `examples/browser-app`:按钮点击 → Marqdo 函数 → 改 DOM 文本 |
|
||||
| 回归 | CI:`cargo test` native;另 job `wasm-pack build` / `cargo check --target wasm32-unknown-unknown --no-default-features --features wasm-core` |
|
||||
|
||||
---
|
||||
|
||||
@@ -53,22 +53,23 @@ Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识
|
||||
|
||||
落盘(G01 分离后):
|
||||
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
|
||||
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json`
|
||||
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json` · **`ir.json`**(完整 IR 快照,供查询热路径)
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认)
|
||||
marqdo knowledge preflight "task"
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认;写投影 + ir.json)
|
||||
marqdo knowledge preflight "task" # 暖机读 ir.json;缺图才 compile
|
||||
marqdo knowledge preflight "task" --refresh # 强制全量重编译后再预检
|
||||
marqdo knowledge record REUSE
|
||||
marqdo knowledge learn --task ... --failure ...
|
||||
marqdo find "authentication"
|
||||
marqdo find "authentication" # 同上:缺图才 compile;--refresh 强制
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo impact path/to/file.mq.md
|
||||
marqdo conflicts | stale | duplicate [--fail] | verify
|
||||
```
|
||||
|
||||
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
统一 `--json`。查询类命令(`preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`)默认 **读已编译投影**;CI 或源变更后应先 `marqdo knowledge` 或加 `--refresh`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
|
||||
## 6. Reuse 协议
|
||||
|
||||
|
||||
@@ -1,66 +1,41 @@
|
||||
# Extension CDN (Cloudflare R2 → https://ext.marqdo.com)
|
||||
# Extension CDN: native publication and byte parity
|
||||
|
||||
| | |
|
||||
This page describes storage. The executable tasks are in [the release entry](../../skills/marqdo-release/index.mq.md), [assets.mq.md](../../skills/marqdo-release/assets.mq.md) and [asset_io.mq.md](../../skills/marqdo-release/asset_io.mq.md). Read the source contracts before calling them. Version, mode and publication authorization come from the user; inspecting an existing release grants no new remote write.
|
||||
|
||||
## Versioned packs
|
||||
|
||||
Extension versions come from ext/VERSION and can advance independently of the interpreter. An extension release uses its own ext-vX.Y.Z tag and three packs. A full release also includes the CLI, source, WASM and editor deliverables listed in model.mq.md.
|
||||
|
||||
| Object | Meaning |
|
||||
|---|---|
|
||||
| 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) |
|
||||
| vX.Y.Z/marqdo-X.Y.Z-ext.zip | Readable extension sources |
|
||||
| vX.Y.Z/marqdo-X.Y.Z-native-x86_64-pc-windows-msvc.zip | Windows plugins |
|
||||
| vX.Y.Z/marqdo-X.Y.Z-native-x86_64-unknown-linux-gnu.zip | Linux plugins |
|
||||
| vX.Y.Z/VERSION | Version echo for this pack set |
|
||||
| latest/marqdo-X.Y.Z-*.zip | Identical current pack bytes |
|
||||
| latest/VERSION | Recommended current extension version |
|
||||
|
||||
## Why
|
||||
Public reads use https://ext.marqdo.com. [src/ext_cli.rs](../../src/ext_cli.rs) is authoritative for client override variables, version resolution and download fallback order. Ordinary installation does not need storage credentials.
|
||||
|
||||
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.
|
||||
## Callable publication
|
||||
|
||||
## Public URL layout
|
||||
After GitHub contains every required asset, download to dist/release-X.Y.Z. Validation checks names, GitHub size/SHA256, archive CRCs, versions and native capabilities. Source-declared plugins require matching libraries on both native platforms. Independently valid ZIPs cannot hide a missing DLL or shared library.
|
||||
|
||||
Bucket: `marqdo` · Custom domain: **https://ext.marqdo.com**
|
||||
Run from the checkout root with the version already chosen by the user; use the actual full or ext mode:
|
||||
```sh
|
||||
marqdo call skills/marqdo-release/assets.mq.md download 'version="X.Y.Z"' 'mode="ext"' --require-ok --effects plugin,net,fs.write --fs-root . --json
|
||||
marqdo call skills/marqdo-release/assets.mq.md publish 'version="X.Y.Z"' 'mode="ext"' --require-ok --effects plugin,net,fs.write --fs-root . --json
|
||||
marqdo call skills/marqdo-release/index.mq.md finish 'version="X.Y.Z"' 'mode="ext"' --require-ok --effects plugin,net,fs.write --fs-root . --json
|
||||
```
|
||||
|
||||
| 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 |
|
||||
Publication rechecks all three packs and their combined capability matrix before the first PUT. All three versioned ZIPs and three latest ZIPs are written before either VERSION pointer. A failed ZIP stops the sequence. Historical versions are retained.
|
||||
|
||||
`{VER}` is the **extension pack** version (`ext/VERSION`), which **may differ** from CLI `Cargo.toml` version.
|
||||
Finish reads both public pointers and compares downloaded versioned/latest bytes with GitHub SHA256 values. HTTP 200 or one sample URL is insufficient. Edge propagation may leave verification incomplete; repeat observation rather than rebuilding unrelated archives or claiming completion from an upload response.
|
||||
|
||||
## Client download order (`marqdo ext add`)
|
||||
## Explicit boundaries
|
||||
|
||||
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/…`
|
||||
Filesystem operations, hashing, public HTTP downloads, release decisions and upload order are Marqdo code. The engineering extension supplies bounded ZIP inspection and private R2 Signature V4 transport. No Python uploader is part of this path; older standalone scripts remain compatibility utilities.
|
||||
|
||||
Pack SemVer resolution (`release_version()`):
|
||||
The native boundary resolves credentials privately from existing stores or environment. Missing credentials fail explicitly. Never put access keys or secrets in tool parameters, source or reports. A plugin grant has normal OS authority; --fs-root does not sandbox native plugins or child processes.
|
||||
|
||||
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.
|
||||
Isolated loopback tests use fake credentials to verify ZIP-before-VERSION ordering and failure stops. Read-only verification of the published 2.6.0 release has also exercised the actual GitHub/CDN parity path without republishing its assets.
|
||||
@@ -93,8 +93,8 @@ web.plugin # absolute path hint
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **native `quantum`** |
|
||||
| `web` | `web/index.mq.md` + facade/modules + `layout/` · `布局/` + `网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/`(含 `量子/` 中文树), **native `quantum`** |
|
||||
|
||||
## Release assets (native)
|
||||
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# 扩展库:index 即代码 · 文档 · SKILL · tools
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active**(契约卡;完整开发范式见下行) |
|
||||
| 日期 | 2026-11-06 |
|
||||
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
|
||||
| 范式长文 | [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md)(布局、陷阱、验收清单、推广顺序) |
|
||||
| 试点 | `ext/quantum/`;[手册闭环与当前契约位置修正](ext-quantum-handbook.md) |
|
||||
| 相关 | [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [function-as-table-semantics.md](function-as-table-semantics.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
扩展包里**每一份** `.mq.md` 同时是可执行代码、可读 SKILL、以及可 `marqdo call` 的 tools 面;**函数即工具**,`###` 即子工具;禁止第二套 catalog / OpenAPI 真相源。开发新包或迁包时以 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 的验收清单为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 整包统一作者契约(无例外)
|
||||
|
||||
适用于包内全部 `.mq.md`(含 `index`、子依赖、`_capability`、兼容层、中英镜像):
|
||||
|
||||
| 要求 | 含义 |
|
||||
|------|------|
|
||||
| 代码 | 标记可执行;实现可薄委托 ABI / 兄弟模块 |
|
||||
| SKILL | `#` 下写清领域、何时用、**For AI agents → `marqdo call` 本文件** |
|
||||
| tools | `##` / `###` 即工具树;无旁路 schema |
|
||||
| 版式 | **形参契约表紧贴标题下**;**返回契约表也在首条执行语句之前**(当前解析器只在此提取契约) |
|
||||
| 叙述 | 每个函数单元叙述占比 **≥ 50%**;公式与约定写进人话 |
|
||||
| 禁止 | `+` 清单当主表面;ABI 名罗列充文档;「内部文件免检」 |
|
||||
|
||||
形参仍由叙述/体中的 `` `名` `` 推断 arity;`| 参数 | 类型 | 说明 |` 为契约表(见 `tests/contracts/`)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 包布局(quantum 试点)
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
index.mq.md # EN 根 SKILL:无上下文也能照抄 marqdo call
|
||||
circuit/index.mq.md # call 工具 + 作者 # circuit
|
||||
gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/index.mq.md
|
||||
量子/ # ZH 同包(勿再把 量子/ 抬到 ext/ 顶层)
|
||||
索引.mq.md
|
||||
电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
```
|
||||
|
||||
`index` = 总图与编排,必须写明 FILE/FUNCTION/`--effects plugin`;每个子目录的 `index.mq.md` 单独拿到也要能执行。无单独「兼容层」文件。
|
||||
|
||||
---
|
||||
|
||||
## 3. `marqdo call` 与会话
|
||||
|
||||
```text
|
||||
marqdo call <FILE> <FUNCTION> [k=v…]
|
||||
[--json] [--backend tree|bytecode]
|
||||
[--effects none|plugin] # 默认 none
|
||||
[--session <id>]
|
||||
[--toget <name>] # 或尾部 toget <name>
|
||||
```
|
||||
|
||||
- 默认:仅纯函数(今日行为)。
|
||||
- `--effects plugin`:允许 `plugin.call`(及附属的 `output.write`);仍拒绝 fs.write / network / process.exec / llm 等。
|
||||
- `toget` + `--session`:绑定写入 `.marqdo/call-sessions/<id>.json`;参数 `$name` 引用会话值;跨进程 **plugin 句柄经 journal 重放** 重建。
|
||||
- 嵌套子工具:`parent.child`(`###` 路径)。
|
||||
|
||||
值字面量:整数/小数/引号文本/True|False|None;以 `[` / `{` 开头时按 JSON 解析为 List/Map。
|
||||
|
||||
---
|
||||
|
||||
## 4. 叙述 ≥ 50%
|
||||
|
||||
`marqdo check --narrative-ratio`(及 `lib/lint/narrative.mq.md` skill)按函数单元统计叙述字符占比;`ext/quantum/**/*.mq.md` **全量零豁免**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 ADR 0007
|
||||
|
||||
作者程序与业务路径仍不写 `ensure_plugin` / `host_*`;插件经 `_capability` / facade 加载。Agent 用 `--effects plugin` 调用 facade,不把 capability 当日常工具(文件本身仍须达标 skill)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-11-06 | 初稿:012 试点契约、call effects/toget、quantum 模块树 |
|
||||
| 2026-11-06 | quantum 中文树收进 `ext/quantum/量子/`;根 skill 增加「选哪条路」;`ext add` 拒绝装进源码树 |
|
||||
| 2026-11-06 | 链到 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 作为开发范式长文 |
|
||||
@@ -0,0 +1,71 @@
|
||||
# Quantum:从「拆分过的库」到可执行开发手册
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 日期 | 2026-11-08 |
|
||||
| 使用与开发真相源 | [英文根入口](../../ext/quantum/index.mq.md) · [中文根入口](../../ext/quantum/量子/索引.mq.md) |
|
||||
| 回归门禁 | [quantum_handbook.rs](../../tests/quantum_handbook.rs) |
|
||||
| 思想来源 | [next/010](../next/010.md) · [next/011](../next/011.md) · [next/012](../next/012.md) |
|
||||
| 本文定位 | 记录本次修正的原因与边界;日常使用无需先读本文 |
|
||||
|
||||
上一轮把量子库拆成了模块树,也加入了 `call` 与叙述比例,但没有形成「只沿 index 就能使用和开发」的闭环。问题出在验收标准:目录、工具和叙述存在,并不能证明一个陌生开发者能完成实验、理解结果,再正确扩展它。
|
||||
|
||||
## 已确认的缺口
|
||||
|
||||
| 缺口 | 后果 | 本轮修正 |
|
||||
|------|------|----------|
|
||||
| `## For AI agents`、`## Package layout` 等说明标题 | 解析成无业务意义的真实函数,污染工具树 | 说明用自然段,标题保留给工具/对象 |
|
||||
| 裸 `$qc`、缺会话或只有消费者没有生产者 | 照抄命令失效,Rust argv 测试发现不了 shell 展开 | 每页完整实验;引用和文本字面量用 shell 单引号 |
|
||||
| 字符串 `kind="bitflip"` 的双引号被 shell 去掉 | CLI 拒绝未带字面量引号的文本 | 使用 `'kind="bitflip"'`,通过真实 shell 测试 |
|
||||
| 默认值后紧贴英文标点,如容差后的问号 | 标点被叙述扫描器纳入默认值,number 变成 text | 标点与默认值分隔,实跑覆盖省略参数 |
|
||||
| 旋转、自定义门应用、追加、矩阵导出藏在对象方法里 | 命令行只能走很窄的 Bell 演示路径 | 补齐自由工具,保留既有作者对象方法 |
|
||||
| 重复「本方法返回句柄」等通用套话 | 满足比例却没有解释科学语义 | 移除旧填充,加入来源、单位、边界、预期和下一步 |
|
||||
| 缺源码归属与验证方式 | AI 知道怎么调用,却不知道怎么开发 | 各模块写新增配方/原语的修改位置、镜像和既有金样 |
|
||||
|
||||
## 同一个入口承担四个职责
|
||||
|
||||
使用路径是「打开根入口 → 根据科学问题选模块 → 复制完整实验 → 核对独立期望」。每个子入口也能单独冷启动,包括输入生产者、参数、结果形状、何时转到兄弟模块。
|
||||
|
||||
开发路径从最小必要变化开始:新实验组合已有工具;新酉矩阵使用 `gate.custom`;只有真实能力缺口才改原生实现。每个模块给出它负责的 Rust 文件、ABI 导出、中英镜像及应保留的测试。根入口的 `bell_analysis` 是这种开发方式的具体配方。
|
||||
|
||||
`bell_circuit` 返回可继续组合的电路;原有 `bell_phi_plus` / `贝尔态` 保留概率结果;新增 `bell_analysis` / `纠缠分析` 返回整体纯度、约化纯度、ZZ 关联和 Schmidt 数据。相同概率的经典混合不能冒充 Bell 纯态,所以不能只验证 00/11 概率。
|
||||
|
||||
工具入口继续是普通 `.mq.md` 函数。没有添加 Skill 编译器、MCP 包装、额外工具 manifest 或另一套 schema。符号与契约依靠现有解析和 `knowledge inspect`;符合 next/011 的简洁核心。
|
||||
|
||||
## 契约位置必须符合当前解析器
|
||||
|
||||
旧范式要求「返回表放在体末、返回标记前」,但 `src/parse/mod.rs::extract_function_contract` 只在首条可执行语句前提取参数与返回契约。放到 `cap.load` 之后的返回表会成为普通表,无法承担预期校验。
|
||||
|
||||
本轮以实现为准:参数表紧跟标题;返回表也位于首条执行语句之前;意图叙述仍可与后续执行步骤交错。对象构造器和方法同样补齐契约。叙述声明承载默认值,表说明类型和含义,不把 `any` 句柄伪装成新增的领域类型系统。
|
||||
|
||||
`check --narrative-ratio` 仍是最低门槛,但不再充当手册完成的唯一证据。测试同时检查每个可调用单元具有真正提取出的返回契约、参数无漂移,根符号只有三个实际实验工具。
|
||||
|
||||
## 只承诺已有能力
|
||||
|
||||
手册明确以下区别,而不把 next 的愿景写成已经实现的功能:
|
||||
|
||||
- `call`、跨进程 journal 会话、双后端和稳定符号查询已有实现。
|
||||
- 状态向量默认 12 比特、硬上限 16;密度和 Schmidt 最多六比特。
|
||||
- 理想态与概率忽略教学噪声;只有 `run` 采样施噪。
|
||||
- 密度矩阵构造检查形状和厄米性,不认证半正定与归一化。
|
||||
- Schmidt 熵使用自然对数;局部纯度和关联需要结合整体态解释。
|
||||
- `draw_state` / `画态` 补上现有 qsphere、multibloch 能力;高级态图换肤仍是 Q8c 规划。
|
||||
- `call --effects plugin` 允许绘图返回 SVG,但宿主仍禁文件写入;实际落盘走作者程序的 `run`。
|
||||
- 插件 journal 重放可能重复插件效果;会话不是无副作用的永久对象仓库。
|
||||
- 智能体决定持久交互分支和复杂自我改进并非本轮实现。
|
||||
|
||||
## 验证与推广条件
|
||||
|
||||
先构建 `marqdo_plugin_quantum`,再执行:
|
||||
|
||||
```bash
|
||||
cargo test --locked --test quantum_handbook
|
||||
cargo test --locked --test call_cli quantum_
|
||||
cargo test --locked --test gold ext_quantum -- --test-threads=1
|
||||
```
|
||||
|
||||
手册门禁直接提取双语源码中的 `sh` 围栏,经过 bash 执行原命令,逐次检查退出码与 JSON,不抄写另一份命令目录。作者程序也从 `marqdo` 围栏提取执行。两类示例都验证 Tree/Bytecode,并比较独立数学期望与中间结果;会话放在临时目录隔离。
|
||||
|
||||
组合工具另覆盖具名旋转门、矩阵导出、应用、追加和密度矩阵观察。既有 gold 继续覆盖公式、自定义门、噪声、振幅阻尼、作者方法与 SVG。
|
||||
|
||||
向其他扩展推广时,复用的是这些验证问题:陌生人能否独立启动、能否解释结果、能否找到修改归属、示例是否来自源码且持续执行。无需把 Quantum 的具体物理工具或新的模板套到每个库。
|
||||
@@ -88,7 +88,7 @@
|
||||
|
||||
## 4. 作者面 API
|
||||
|
||||
### 4.1 英文(`ext/quantum/quantum.mq.md`)
|
||||
### 4.1 英文(`ext/quantum/circuit/index.mq.md`)
|
||||
|
||||
在既有 `# circuit` / `# gate` 之外增加(或扩展方法):
|
||||
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
| 日期 | 2026-08-12(初版)· 2026-08-28(Q7 · Q8 viz) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
|
||||
| 当前手册 | [根入口](../../ext/quantum/index.mq.md) · [中文入口](../../ext/quantum/量子/索引.mq.md) · [2026-11-08 优化记录](ext-quantum-handbook.md) |
|
||||
| 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 |
|
||||
|
||||
---
|
||||
@@ -72,7 +73,7 @@ math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的
|
||||
|
||||
1. **仅 ABI 插件接入**:`plugins/quantum` → `libquantum.so`;L1 在 `ext/quantum/*.mq.md`。
|
||||
2. **`ext/quantum/**` 禁止 `host_*`**;经 `plugin.native_path` + `plugin.load`(同 web/agent)。
|
||||
3. **中英分文件**:`quantum.mq.md` / `量子.mq.md`,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
|
||||
3. **中英分文件**:同一包 `ext/quantum/` 内英文模块树 + `量子/` 中文树,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
|
||||
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
|
||||
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
|
||||
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
|
||||
@@ -81,17 +82,31 @@ math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的
|
||||
|
||||
## 3. 布局与安装
|
||||
|
||||
Skill / tools 树(012 试点;契约 [ext-index-skill-tools.md](ext-index-skill-tools.md),范式 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md)):
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
quantum.mq.md # 英文类 API
|
||||
量子.mq.md # 中文类 API
|
||||
ext/quantum/ # 一个扩展包(同 web/ai:中英同目录)
|
||||
index.mq.md # EN 根 SKILL
|
||||
circuit/ · gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/index.mq.md
|
||||
量子/ # ZH 根与模块(同等 skill 标准)
|
||||
索引.mq.md
|
||||
电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
plugins/quantum/
|
||||
Cargo.toml
|
||||
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
|
||||
examples/quantum-bell/ # 规范示例(Q3)
|
||||
src/lib.rs # ABI v2
|
||||
examples/quantum-bell/
|
||||
tests/ext/quantum-*.mq.md
|
||||
```
|
||||
|
||||
安装产物(`~/.marqdo/ext` 或 `MARQDO_EXT`,**不是**仓库 `ext/` 源码树):
|
||||
|
||||
```text
|
||||
quantum/...
|
||||
native/libquantum.so
|
||||
quantum.plugin # 绝对路径提示;勿提交
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_quantum
|
||||
marqdo ext add quantum
|
||||
@@ -102,11 +117,11 @@ marqdo ext add quantum
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
quantum: ext/quantum/circuit/index.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
或中文:`导入 量子:ext/quantum/量子.mq.md`。
|
||||
或中文:`导入 量子:ext/quantum/量子/电路/索引.mq.md`(根 skill:`ext/quantum/量子/索引.mq.md`)。
|
||||
|
||||
---
|
||||
|
||||
@@ -152,7 +167,7 @@ $$
|
||||
|
||||
## 5. 作者面 API(锁定草图)
|
||||
|
||||
### 5.1 英文 `ext/quantum/quantum.mq.md`
|
||||
### 5.1 英文 `ext/quantum/circuit/index.mq.md`
|
||||
|
||||
```markdown
|
||||
# gate
|
||||
@@ -199,7 +214,7 @@ $$
|
||||
|
||||
门方法返回**更新后的 circuit 句柄**(与 web `compose_*` 相同:`` `qc` = > `qc`.h qubit=0 *``)。
|
||||
|
||||
### 5.2 中文 `ext/quantum/量子.mq.md`
|
||||
### 5.2 中文 `ext/quantum/量子/`(根 `索引.mq.md`)
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
@@ -343,7 +358,7 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
|
||||
---
|
||||
title: Bell state
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
quantum: ext/quantum/circuit/index.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
@@ -0,0 +1,227 @@
|
||||
# 扩展库开发范式:code = document = skill = tools
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active**(quantum 试点已落地;其它官方扩展按本范式推广) |
|
||||
| 日期 | 2026-11-06 |
|
||||
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
|
||||
| 契约摘要 | [ext-index-skill-tools.md](ext-index-skill-tools.md) |
|
||||
| 试点 | [`ext/quantum/`](../../ext/quantum/)(完成)· [`ext/web/`](../../ext/web/)(迁移中,含[布局范式](ext-web-layout-paradigm.md)) |
|
||||
| 相关 | [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
一份 `.mq.md` **同时是**可执行代码、给人读的文档、给智能体的 SKILL、以及可 `marqdo call` 的 tools 面。
|
||||
**函数即工具**(`##`),**子函数即子工具**(`###`)。禁止旁路 catalog / OpenAPI / MCP 包装成为第二真相源。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么这样设计
|
||||
|
||||
| 传统拆法 | 本范式 |
|
||||
|----------|--------|
|
||||
| README + SDK + tool schema 三套漂移 | 同一文件既可跑又可讲 |
|
||||
| Agent 调 MCP,作者调库 API | 智能体与作者共读同一路径;智能体默认 `marqdo call` |
|
||||
| 扩展 = 功能清单 | 扩展 = 可执行知识包:根 skill 先教会「怎么调」 |
|
||||
|
||||
智能体冷启动时只应:打开根 `index.mq.md` → 按「选哪条路」→ 照抄 `marqdo call`。不必发明第二套 API。
|
||||
|
||||
---
|
||||
|
||||
## 2. 包布局(强制形态)
|
||||
|
||||
一个官方扩展 **一个目录**(与 `web` / `ai` 一致)。中英 **同包分文件**,不要把中文树抬到 `ext/` 顶层变成「第二个包」。
|
||||
|
||||
```text
|
||||
ext/<id>/
|
||||
index.mq.md # EN 根 SKILL(先读)
|
||||
<module>/index.mq.md # 模块:## call 工具 + 可选 # 作者对象
|
||||
_capability/index.mq.md # 仅插件加载(日常勿当业务工具)
|
||||
<中文名>/ # ZH 镜像树(同等标准)
|
||||
索引.mq.md
|
||||
<模块>/索引.mq.md
|
||||
```
|
||||
|
||||
试点现状:
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
index.mq.md · circuit/ · gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/
|
||||
量子/索引.mq.md · 电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
```
|
||||
|
||||
安装后落在 `~/.marqdo/ext`(或 `MARQDO_EXT`),**不是**仓库源码 `ext/`:
|
||||
|
||||
```text
|
||||
~/.marqdo/ext/
|
||||
quantum/...
|
||||
native/libquantum.so
|
||||
quantum.plugin # 路径提示;勿提交源码树
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 根 skill 怎么写
|
||||
|
||||
根 `index.mq.md` / `索引.mq.md` 是冷启动入口,须按顺序包含:
|
||||
|
||||
1. **选哪条路**(表格,勿用 `1.` 列表——在 Marqdo 里 `1.` 是分支语法)
|
||||
- 只要演示结果 → 根上的编排工具(如 `bell_phi_plus` / `贝尔态`)
|
||||
- 要句柄继续 → 贴出分步 `call`(同一 `--session` + `--toget`)
|
||||
- 换语言 → 指向另一语言树,禁止混用 EN/ZH 工具名
|
||||
2. **如何执行任意工具**:固定 CLI 形状、`--effects plugin`、`--json`、`$name`
|
||||
3. **包布局**:每个模块路径 + 一句用途
|
||||
4. **可选一键编排工具**(如贝尔态):无参或极少参,便于验收
|
||||
|
||||
智能体默认路径是 `##` + `marqdo call`。`# circuit` / `# 电路` 等对象是 **作者程序** import 用的,须在根 skill 写明,避免代理误走方法链。
|
||||
|
||||
---
|
||||
|
||||
## 4. 模块文件怎么写
|
||||
|
||||
每个 `index.mq.md` 单独拿到也要能用:
|
||||
|
||||
| 块 | 要求 |
|
||||
|----|------|
|
||||
| 开篇叙述 | 领域是什么、何时打开本文件 |
|
||||
| For AI agents / 给智能体 | 可照抄的 `marqdo call`;缺能力时 **写明下一步打开哪个兄弟模块**(例如 circuit 造线后概率在 simulate) |
|
||||
| `##` 工具 | 形参契约表紧贴标题下;返回契约表也在首条执行语句前(当前解析器边界);叙述 ≥ 50% |
|
||||
| `#` 对象(可选) | 作者链式 API;加载插件走 facade(如 `cap.load` / `能力.加载`),禁止作者面 `host_*` |
|
||||
|
||||
薄实现:工具体调用 ABI(`*> quantum_…*`)或转发兄弟模块即可,真相在叙述与契约表。
|
||||
|
||||
---
|
||||
|
||||
## 5. `marqdo call` 与会话
|
||||
|
||||
```text
|
||||
marqdo call <FILE> <FUNCTION> [k=v…]
|
||||
[--json]
|
||||
[--effects none|plugin] # 默认 none;ABI 扩展必须 plugin
|
||||
[--session <id>]
|
||||
[--toget <name>] # 或尾部 toget <name>
|
||||
```
|
||||
|
||||
| 机制 | 用途 |
|
||||
|------|------|
|
||||
| `--effects plugin` | 允许 `plugin.call`;仍拒 fs/network/process/llm 等 |
|
||||
| `--session` + `--toget` | 跨进程保存返回值;`$name` 引用;plugin 句柄经 journal 重放 |
|
||||
| `parent.child` | 嵌套 `###` 子工具 |
|
||||
|
||||
参数字面量:数字、引号文本、True/False/None、以 `[`/`{` 开头的 JSON、或 `$name`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 叙述 ≥ 50%
|
||||
|
||||
```bash
|
||||
marqdo check --narrative-ratio ext/<id>/path/index.mq.md
|
||||
```
|
||||
|
||||
- 按函数单元计;契约表计为叙述;语言代码围栏计为代码。
|
||||
- 试点包 `ext/quantum/**` **零豁免**(含 `_capability` 与中文树)。
|
||||
- 狗粮 skill:`lib/lint/narrative.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 7. ABI 与 capability
|
||||
|
||||
- 原生能力只经 `plugin.native_path` + `plugin.load`(集中在 `_capability` / `能力`)。
|
||||
- 领域模块在工具开头调用 `cap.load` / `能力.加载`,**不**把 capability 当日常业务工具。
|
||||
- 遵守 ADR 0007:作者程序与 `ext/**` 业务面不写 `host_*` / `ensure_plugin` 垃圾抽屉。
|
||||
|
||||
---
|
||||
|
||||
## 8. 中英与导入
|
||||
|
||||
| 规则 | 做法 |
|
||||
|------|------|
|
||||
| 分文件 | EN 与 ZH 两套树;禁止同一文件混排 API 名 |
|
||||
| 同包 | `ext/<id>/` 内放中文子树,勿 `ext/<中文包名>/` 顶层并列 |
|
||||
| 作者导入 | `import: circuit: ext/quantum/circuit/index.mq.md` → `circuit.circuit` |
|
||||
| 中文导入 | `导入 量子:ext/quantum/量子/电路/索引.mq.md` → `量子.电路` |
|
||||
| 智能体 | 打开对应语言的根 skill,工具名与路径保持同语言 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 安装与源码卫生
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_<id> # 若有原生插件
|
||||
MARQDO_EXT_SOURCE=/path/to/repo/ext \
|
||||
marqdo ext add <id> # 装到 ~/.marqdo/ext
|
||||
```
|
||||
|
||||
| 禁止 | 原因 |
|
||||
|------|------|
|
||||
| `MARQDO_EXT` 指向仓库 `ext/` 再 `ext add` | 同文件 `fs::copy` 会清空源码;并写入 `*.plugin` / `native/` |
|
||||
| 提交 `ext/*.plugin`、`ext/native/` | 安装产物;已 gitignore |
|
||||
|
||||
`marqdo ext add` **拒绝**把安装根设成源码 `ext/`(防再踩坑)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 常见陷阱
|
||||
|
||||
| 陷阱 | 正确做法 |
|
||||
|------|----------|
|
||||
| 正文写 `1. xxx` 当条目 | 用表格或项目符号;`1.` 是分支 |
|
||||
| 漏 `--effects plugin` | 根 skill 与模块 For AI 段反复写明 |
|
||||
| 只发 `circuit` 文件却找 `probabilities` | 在 circuit 的智能体段贴出 simulate 的完整 call |
|
||||
| 智能体去调 `#` 对象方法 | 根 skill「选哪条路」声明默认走 `##` call |
|
||||
| 中英混用 `新建` + `ext/quantum/circuit` | 选定一棵树用到底 |
|
||||
| 用「兼容层」大文件双挂 API | 删除;模块树即唯一面 |
|
||||
|
||||
---
|
||||
|
||||
Quantum 的完整实验、开发路线与源码示例门禁,见 [2026-11-08 手册修正](ext-quantum-handbook.md)。叙述比例是最低门槛,不能替代照抄执行与独立期望验证。
|
||||
|
||||
## 11. 开发验收清单
|
||||
|
||||
新扩展或把旧包迁到本范式时,逐项打勾:
|
||||
|
||||
- [ ] `ext/<id>/index.mq.md`:选哪条路 + call 形状 + 布局 +(可选)一键编排
|
||||
- [ ] 每个模块 `index.mq.md`:For AI agents 可单独照抄;缺能力时指向兄弟模块
|
||||
- [ ] 全部 `.mq.md`:`marqdo check --narrative-ratio` 通过
|
||||
- [ ] 需要 ABI:`_capability` 唯一加载;领域只调 facade
|
||||
- [ ] 中文:同包子树,路径与 ## 名全中文
|
||||
- [ ] `ext_cli` catalog 的 `mq_files` 列全 EN+ZH 源文件
|
||||
- [ ] 金样:`marqdo call` 一键工具 +(若有句柄)分步 `--session`/`--toget`
|
||||
- [ ] 作者 smoke:import 模块后的 `#` 对象链仍绿
|
||||
- [ ] 未把安装产物写进仓库 `ext/`
|
||||
|
||||
---
|
||||
|
||||
## 12. 智能体视角(试点自检)
|
||||
|
||||
任务「制备 Bell 态」时,合格根 skill 应使代理:
|
||||
|
||||
1. 打开 `ext/quantum/index.mq.md`(或中文 `量子/索引.mq.md`)
|
||||
2. 只要结果 → `bell_phi_plus` / `贝尔态`
|
||||
3. 要句柄 → 照抄 circuit→simulate 四条 call,同一 session
|
||||
|
||||
不必阅读 gate/density,不必发明 Python/MCP。
|
||||
|
||||
---
|
||||
|
||||
## 13. 推广顺序(建议)
|
||||
|
||||
1. **已完成试点**:`ext/quantum/`(含 `量子/`)
|
||||
2. **进行中**:`ext/web/` — 根 `index` + `layout` + 模块树 `page|route|…/index.mq.md` + 中文 `网页/`;作者门面 `web.mq.md`/`网页.mq.md` 保持兼容;call 金样与站点示例对齐继续补齐
|
||||
3. **下一优先**:`linalg` 公式面、`ai` agent 面
|
||||
4. **`ext/net` / `ext/data` / `ext/security`**:随 web 站点场景补根 skill,勿把 DB/鉴权 API 塞回 `web` facade
|
||||
|
||||
每迁一包:更新本文件「试点/推广」表与该包 `doc/design/ext-*.md` 布局节,并加 call 金样。
|
||||
**Web 特有**:布局工程必须写进包内 skill(见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md)),不能只放在外部 README。
|
||||
|
||||
---
|
||||
|
||||
## 14. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-11-06 | web:模块树 + `网页/` 镜像 + page session call 金样推进 |
|
||||
| 2026-11-06 | 初版:由 quantum 试点归纳的整包开发范式与验收清单 |
|
||||
@@ -7,7 +7,7 @@
|
||||
| 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) |
|
||||
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md) · [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -33,13 +33,17 @@
|
||||
|
||||
```text
|
||||
ext/web/
|
||||
web.mq.md · 网页.mq.md # facade: page route serve render inspect
|
||||
index.mq.md · 网页.mq.md # 根 skill(智能体先读;含布局铁律)
|
||||
layout/ · 布局/ # 文件划分布局工程 tools
|
||||
web.mq.md # EN 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
|
||||
```
|
||||
|
||||
**布局工程**(反 HTML/CSS 注入):见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md);包内 `ext/web/layout/index.mq.md`。
|
||||
|
||||
作者入口通常:
|
||||
|
||||
```text
|
||||
@@ -77,6 +81,7 @@ Welcome to the executable web.
|
||||
| `type` | `类型` | `web` / `网页` |
|
||||
| `route` | `路由` | 路径,可含 `{param}` |
|
||||
| `method` | `方法` | 默认 `GET` |
|
||||
| `view` | `视图` | 可选 main:启动时执行主程序,返回递归 View 节点;不与自动 data_source 绑定混用 |
|
||||
| `title` | `标题` | 文档标题 / `<title>` |
|
||||
| `data_source` | `数据源` | 表名 |
|
||||
| `data_order` | `排序` | 如 `-created_at` |
|
||||
@@ -93,6 +98,10 @@ Welcome to the executable web.
|
||||
| title | title | Marqdo | | title |
|
||||
```
|
||||
|
||||
2026-11-08:View 已支持 row/column 容器与 markdown 叶子,容器值保持子表;显式 `view: main` Document 通过普通函数装配。
|
||||
|
||||
2026-11-10:同一五列 View 可放置具型 Resource 节点;结构仍只在启动时装配,数据查询、已挂载表单与会话导航在请求期间解析。无新增 frontmatter 或核心标记;见 [请求资源](web-view-resources.md)。普通离线渲染缺少请求上下文时明确报错,不伪造动态内容。完整工程见[布局实践](ext-web-layout-paradigm.md),实现边界见[优化说明](ext-web-handbook.md)。
|
||||
|
||||
`page.render nodes=` 是**唯一**主装配路径。禁止 `compose_main` / `compose_intro` 等碎片 DSL。
|
||||
|
||||
---
|
||||
@@ -191,6 +200,7 @@ Middleware 一等:`web.use` / `route.use`,表驱动;**禁止** `configure(
|
||||
| A6 | 禁止恢复 `compose_*` / `app.configure` / god page 变异堆 |
|
||||
| A7 | 能力只许迁移/提升;删除须本设计明示 + tests 同步 |
|
||||
| A8 | 设计未锁定处停工提问,禁止自行发明 DSL |
|
||||
| A9 | **文件划分布局**:页面拆到简单组件文件为止;默认禁止整页 HTML/CSS 注入(`dom.raw`/`page.css` 仅逃逸舱) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -7,13 +7,15 @@
|
||||
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [web-net-capabilities.md](web-net-capabilities.md) · [ext-web-drivers.md](ext-web-drivers.md) · [web-assets-and-images.md](web-assets-and-images.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md) |
|
||||
| 实现目录 | `plugins/web/`(**Go module**;产物仍为 `libweb.so` / `web.dll` / `libweb.dylib`) |
|
||||
| 作者面 | `ext/web/web.mq.md` · `ext/web/网页.mq.md`(**ABI 名与方法面保持兼容**;非另起一套 API) |
|
||||
| 验收应用 | 工作区 `anlian`(暗恋见君):用 Marqdo 前后端脚本完整重写;**PostgreSQL + Redis 外接** |
|
||||
| 当前验收 | 仓库内独立示例与临时夹具;完整站点、网络站点、浏览器与数据资源分别验证 |
|
||||
|
||||
本文件记录 Go 原生层重写时期的 ABI 与实施背景。2026-11-10 起不再以外部业务工程作为仓库交付项;当前作者规范与可调用入口以 [Web Artifact 设计](ext-web-artifact.md)、[网页手册](../../ext/web/index.mq.md)和[编程规范](../library-development.mq.md)为准。下方旧 compose/类链清单是历史对照,不能当作当前推荐 API。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
用 **Go** 重写官方网络拓展库原生层(`plugins/web`),在 **C ABI v2 全量兼容** 前提下提供「网页制备」所需的全部服务端能力;`ext/web` 继续用 GFM 表 + `#` 类做作者面;应用(含暗恋见君)的前后端脚本全部用 Marqdo 书写。此举同时验证 **多语言 ABI 插件生态**(首个非 Rust 官方插件)。
|
||||
用 **Go** 重写官方网络拓展库原生层(`plugins/web`),在 **C ABI v2 全量兼容** 前提下提供「网页制备」所需的全部服务端能力;`ext/web` 继续用 GFM 表 + `#` 类做作者面;应用的前后端脚本全部用 Marqdo 书写。此举同时验证 **多语言 ABI 插件生态**(首个非 Rust 官方插件)。
|
||||
|
||||
**不是**最小 hello 插件;**不是**在旧 Rust 代码上打补丁(对齐 [ext-web.md](ext-web.md) **C5**)。
|
||||
|
||||
@@ -36,7 +38,7 @@
|
||||
2. **作者面可用**:现有 `ext/web` 示例与 `tests/ext/web-*`(含 live-server)在换 Go `.so` 后通过;无需作者改业务脚本(除非文档标明的 **G 增强**)。
|
||||
3. **网页制备完备**:单站点可完成页面装配、样式/头/图、库表、表单、路由、中间件、鉴权/RBAC、上传下载、SEO/RSS/sitemap、WS、缓存、对象存储、反代、invoke——即 W0–W8 + P3 + C0–C4 + H1/H2 能力面。
|
||||
4. **驱动外接**:`postgres://`、`redis://`、`s3://` 为正式一等能力(与 [ext-web-drivers.md](ext-web-drivers.md) 一致);SQLite / memory / file 仍支持本地与测试。
|
||||
5. **暗恋见君可写完**:用 Marqdo 后端脚本 + 浏览器 WASM 前端脚本重写 anlian 核心模块(见 §8);运行时仅依赖 `marqdo` + `libweb` + **外接 PostgreSQL + Redis**(可选 S3/RustFS)。
|
||||
5. **通用工作流可验证**:使用仓库内独立站点和临时夹具覆盖数据、鉴权、表单与实时能力(见 §8);SQLite 提供本地验收,PostgreSQL、Redis 和对象存储按各自可用环境另行验证。
|
||||
6. **安装路径不变**:`marqdo ext add web`、`plugin.native_path name=web`、`MARQDO_WEB_PLUGIN`、产物文件名 `libweb.so` 等与 [ext-cli.md](ext-cli.md) 兼容。
|
||||
|
||||
### 1.3 非目标
|
||||
@@ -56,7 +58,7 @@
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 应用(anlian / 任意站点) │
|
||||
│ 应用(独立业务站点) │
|
||||
│ · 后端 .mq.md:路由、业务、装配、invoke 处理函数 │
|
||||
│ · 前端 .mq.md:WASM + lib/browser(作者零业务 JS) │
|
||||
└────────────────────────────┬─────────────────────────────────────┘
|
||||
@@ -284,41 +286,36 @@ Where 语义:等值 map、filter 表、OR / IN / BETWEEN、分页 offset/limit
|
||||
|
||||
---
|
||||
|
||||
## 7. G 增强(完备网页制备 + anlian;兼容之上增量)
|
||||
## 7. G 增强(完备网页制备;兼容之上增量)
|
||||
|
||||
> 以下为 **新增能力**,不替代 §5。作者面用新方法/新 configure 键;旧脚本不受影响。
|
||||
|
||||
| ID | 能力 | 动机 | 作者面草案 |
|
||||
|----|------|------|------------|
|
||||
| **G-WS1** | **命名房间** WS:`join`/`leave`/`publish`;组名 ASCII(如 `chat.room.{id}`) | anlian 公聊/私聊 | `app.route_ws` 增 `mode=room` + `room_key`;或 `ws.room_*` ABI |
|
||||
| **G-WS1** | **命名房间** WS:`join`/`leave`/`publish`;组名 ASCII(如 `chat.room.{id}`) | 独立聊天室 | `app.route_ws` 增 `mode=room` + `room_key`;或 `ws.room_*` ABI |
|
||||
| **G-WS2** | 房间消息钩子:先 `invoke`/落库再广播 | 「先写 PG 再推送」 | configure 或 route 表 `on_message=lib.member` |
|
||||
| **G-SESS1** | Session 后端可选 `redis://` | 多进程/多实例 | `web_session_new` url 或 auth 配置 `session=redis://` |
|
||||
| **G-CACHE1** | Redis pub/sub 可选作 WS 扇出后端 | 多进程 WS | `configure ws_backend=redis` |
|
||||
| **G-API1** | Bearer API Key 校验原语(hash+pepper+scopes) | anlian `apikeys` | `web_api_key_check` + `# auth` 或独立小类;**业务 scopes 仍在 .mq.md** |
|
||||
| **G-MAIL0** | (可选后续)SMTP 发送原语 | 邮箱验证码 | 不阻塞首版对等;列入 anlian 二期 |
|
||||
| **G-API1** | Bearer API Key 校验原语(hash+pepper+scopes) | API 密钥资源 | `web_api_key_check` + `# auth` 或独立小类;**业务 scopes 仍在 .mq.md** |
|
||||
| **G-MAIL0** | (可选后续)SMTP 发送原语 | 邮箱验证码 | 不阻塞首版对等;另列后续能力 |
|
||||
|
||||
**明确仍属应用层(不进插件)**:反垃圾策略、草稿定时发布约定、好友关系、专题 `topic_bundles` 静态交互内容(静态挂载 + 前端 Marqdo/既有 JS 资产)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 暗恋见君验收矩阵(检测「能不能写完」)
|
||||
## 8. 独立工作流与隔离验收
|
||||
|
||||
外部依赖(允许):**PostgreSQL**、**Redis**;可选对象存储。
|
||||
仓库交付不依赖某个外部业务工程的源码或个人数据库。各能力保留在原生实现与领域资源中,通过维护中的独立示例验证;移出业务工程不构成删除通用功能的理由。
|
||||
|
||||
| 模块 | Marqdo 后端 | Marqdo 前端 | 插件依赖 | 验收 |
|
||||
|------|-------------|-------------|----------|------|
|
||||
| 站点壳 / 首页 | `# page` + db | 局部刷新可选 WASM | listen、static、cache | 首页可开 |
|
||||
| posts 帖子/评论/板块 | route + form + db | 发帖表单 WASM 可选 | CRUD、CSRF、upload | CRUD+列表详情 |
|
||||
| news | 同上 | 同上 | 同上 | 列表详情 |
|
||||
| accounts | auth + session +(二期 mail) | 登录表单 | argon2、session、gate | 注册登录 |
|
||||
| profiles | db + storage | 头像上传 | storage/upload | 资料页 |
|
||||
| search | db.search 或 PG 查询 + cache | — | db/cache | 关键词搜索 |
|
||||
| chat | route_ws + G-WS1/2 + db | WS 客户端脚本 | Redis + WS rooms | 公聊+私聊实时 |
|
||||
| apikeys | G-API1 + db | 管理页 | — | Bearer 调 API |
|
||||
| webmaster | sitemap/robots | — | 已有 ABI | `/sitemap.xml` |
|
||||
| topics | `app.static` → bundles | 既有静态交互 | static | 专题可访问 |
|
||||
| 工作流 | 当前来源 | 实际核对 |
|
||||
|---|---|---|
|
||||
| 完整动态站点 | examples/web-site、examples/web-site-zh | 原主题规则、摘要与详情、当前记录、表单重试、会话导航及后台门禁 |
|
||||
| 网络资源 | examples/web-net-site、examples/web-net-site-zh | Cookie/multipart、WebSocket 回显、真实表单与后台 |
|
||||
| 客户端状态 | examples/web-spa-app、examples/web-collab-doc | 当前 WASM、历史记录、编辑、多标签实时协作 |
|
||||
| 数据与租户 | tests/example_databases.rs、tests/web_handbook.rs | 独占临时数据库、已有记录保留、租户条件 |
|
||||
| 原生插件 | plugins/web 内部测试 | 独立夹具下验证数据库、会话、运输、资源及渲染边界 |
|
||||
|
||||
**「写完」定义**:上述模块在 Marqdo 仓库或 `anlian` 旁路目录有可运行 `.mq.md` 站点;gold/手工脚本能走通主路径;不依赖 Django/Channels/Daphne/gunicorn。
|
||||
开发与验收由 skills/marqdo-dev/index.mq.md 编排,使用 marqdo call。完整示例的浏览器用例和 HTTP 用例不能替代 Postgres、Redis、OIDC 或外部服务的真实环境证据;未运行的边界仍需明确保留为未验证。
|
||||
|
||||
---
|
||||
|
||||
@@ -400,7 +397,7 @@ scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
|
||||
| **W-G11** | 定制 C2–C4 shell/layout/style/nav | ✅ `web-c2`–`c4` |
|
||||
| **W-G12** | G 增强 WS rooms + Redis session/pubsub + API key 原语 | ✅ 单测 + `web-g12-api-key-smoke` |
|
||||
| **W-G13** | 默认切换 Go `libweb`;归档 Rust;更新发版与 ext CLI | ✅ 离线+live gold(7 个 `*_live`)对 Go 全绿;`ext add`/`gold`/`release` 走 `scripts/build-web-plugin.sh`;Rust 移出 workspace;gold 强制 `MARQDO_WEB_PLUGIN` 避免 `~/.marqdo` 旧 so |
|
||||
| **W-G14** | anlian Marqdo 重写主路径(可分仓或 `examples/anlian-mq/`) | ✅ `examples/anlian-mq/`(本地 SQLite + 粉玻璃主题 + 主路由/登录/片段;外接 PG/Redis 仍为增强路径) |
|
||||
| **W-G14** | 历史业务站点主路径演示 | 历史演示工程已移出仓库;当前独立验收见 §8 |
|
||||
|
||||
每波次:**先补 Go 实现 → 跑对应 gold → 再进入下一波**。禁止跨波次留下「注册了但返回 stub 错误」的 ABI(除 W-G0 明确的未实现探测)。
|
||||
|
||||
@@ -414,7 +411,7 @@ scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
|
||||
| 金样例 | 现有 `tests/ext/web-*.mq.md`;构建脚本产出 `libweb.so` 后跑 |
|
||||
| Live | 现有 `*-live-server.mq.md` + curl |
|
||||
| 回归门禁 | CI:安装 Go → `scripts/build-web-plugin.sh` → `cargo test` 相关 web 项 |
|
||||
| anlian | 独立 smoke:登录、发帖、WS 发言、API key |
|
||||
| 独立站点 | 登录、表单、WebSocket 与 API 使用可控夹具分别验收 |
|
||||
|
||||
---
|
||||
|
||||
@@ -450,6 +447,6 @@ scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
|
||||
1. **全量重写** `plugins/web` 为 Go,**不是**最小闭环。
|
||||
2. **既有网络拓展能力(§5)重写后必须仍可用**;作者面默认兼容。
|
||||
3. **PostgreSQL / Redis 外接** 为一等公民;Marqdo 承担应用前后端脚本。
|
||||
4. **暗恋见君** 为完备性验收,不是缩小插件范围的借口。
|
||||
4. 完备性通过独立工作流和原生测试验证,不以外部业务工程缩小插件能力范围。
|
||||
5. **多语言 ABI 生态** 以本插件为样板(G7)。
|
||||
6. 开发严格按 **§10 波次** 推进;本文件为唯一施工图。
|
||||
@@ -0,0 +1,71 @@
|
||||
# Web:可执行手册与递归布局工程
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 日期 | 2026-11-08 |
|
||||
| 使用与开发入口 | [英文 index](../../ext/web/index.mq.md) · [中文索引](../../ext/web/网页/索引.mq.md) |
|
||||
| 工程规范 | [布局拆分](ext-web-layout-paradigm.md) |
|
||||
| 参考工程 | [英文](../../examples/web-layout-handbook/index.mq.md) · [中文](../../examples/web-layout-handbook-zh/index.mq.md) |
|
||||
| 自动验收 | [源手册与活站点](../../tests/web_handbook.rs) · [浏览器布局](../../tests/web/layout.browser.cjs) |
|
||||
| 思想来源 | [next/010](../next/010.md) · [next/011](../next/011.md) · [next/012](../next/012.md) · [Quantum 优化](ext-quantum-handbook.md) |
|
||||
|
||||
## 原有规范为什么没有落实
|
||||
|
||||
原有 Web skill 已写「拆到简单」,但缺少可沿着文件树复现的工程。原生 `RenderNodes` 仅渲染平面 title/text/link/html;拼接两张表只产生兄弟节点,不会产生双栏。`serve` 又只把 Document 正文当 Markdown,没有执行文档里的组件装配。只加强口头禁止 HTML,无法补上这些实际缺口。
|
||||
|
||||
本轮以一个完整首页检验规范:导航、主体、页脚分开;页脚拆品牌与链接;链接再拆文档与社区。所有末端 content.md 都是普通 Markdown。每个父 index.mq.md 只负责其下一层排列关系。
|
||||
|
||||
## 使用同一份 View 表表示父与叶
|
||||
|
||||
沿用 `type | slot | value | attrs | style`,不新增核心语法、不建立第二套布局方言:
|
||||
|
||||
| 类型 | 值列 | 含义 |
|
||||
|------|------|------|
|
||||
| markdown / 正文 | Markdown 文本 | 内容叶子 |
|
||||
| row / 横排 | 子节点列表 | 响应式分栏 |
|
||||
| column / 纵排 | 子节点列表 | 上下排列 |
|
||||
| nav/header/footer/section/aside | 子节点列表 | 语义区域 |
|
||||
| 既有 title/text/link/html | 兼容原值 | 保留旧节点行为;html 为显式兼容边界 |
|
||||
|
||||
纯 `component.markdown` / `正文` 与 `component.wrap` / `包裹` 构造节点,`layout.stack` / `纵排` 和 `layout.columns` / `分栏` 声明几何。`merge` 接受 @ 记录列表,确定兄弟顺序并保留嵌套值;不再声称它会自动归一化所有列式表或把平面表变成双栏。
|
||||
|
||||
递归渲染保留节点类型,不把子表转成 `map[...]` 字符串。原生渲染器诊断无效子节点、列长不等和过深嵌套。运行时固定的布局样式提供基础响应式几何,样式列继续是类名引用,并非 CSS 编译器。叶子正文经过既有 Markdown 渲染器。
|
||||
|
||||
## 显式 Document 装配
|
||||
|
||||
普通 `type: web` 保留既有 Markdown/数据源路径。需要结构化页面时显式增加 `view: main`(中文 `视图: main`),普通 `# main` 返回 View 节点列表。`serve` 在启动时通过已有 `run_artifact` 回调执行装配,用与离线预览相同的渲染器生成文档,不再套入旧站点的另一份导航/页脚壳。
|
||||
|
||||
这是启动时装配,修改内容后重启;不声称具备自动请求期模板绑定。装配函数不再次调用渲染器或启动服务器。请求期业务仍用 Endpoint。自动 `data_source` 绑定使用普通 Document;与 `view: main` 混用会明确报错,避免静默忽略数据源。
|
||||
|
||||
`web.inspect root=...` / `网页.检视 根=...` 新增离线扫描入口,不启动进程也不执行组件。空应用的新进程无法读取另一个活进程的私有路由;手册不再将此作为活站点检视方法。检视结果加入 `_type: web_inspection`,使不同长度的 declared/system 列表保持对象语义,而不被 JSON 边界当作列式表。
|
||||
|
||||
## 手册与工具一致
|
||||
|
||||
另修复既有元数据型 Endpoint 在 Bytecode 没有函数时误报编译错误的问题:与 Tree 共用声明摘要路径,普通无入口程序仍然拒绝执行。
|
||||
|
||||
全部 Web 模块清理说明性伪函数,参数和返回契约均放在执行前;对象 API 保留。纯 DOM 构造与客户端描述不再无故加载插件。命令示例保护文本引号与会话美元引用。布尔/数字默认值与相邻标点分开,保证真正省略参数时仍符合契约。
|
||||
|
||||
原 `accept_component` 仅根据名称和职责就返回 ok=True,无法代表实际验收。现在返回明确的 checklist 状态,实际验收依据源码职责、渲染结构和运行结果。`site_playbook` 讲流程,`preview_markdown` / `preview_nodes` 给真实预览,不再把增加叙述字数当作完成指标。
|
||||
|
||||
## 验证
|
||||
|
||||
```bash
|
||||
bash scripts/build-web-plugin.sh
|
||||
cargo test --locked --test web_handbook
|
||||
cargo test --locked --test call_cli web_
|
||||
cargo test --locked --test gold ext_web -- --test-threads=1
|
||||
```
|
||||
|
||||
手册门禁直接执行 18 份包内入口的双语 sh 围栏,在 Tree/Bytecode 共执行 80 次命令;同样执行根手册的作者程序。参考工程的双语双后端检查实际预览、启动服务,核对首页与预览相同、关于页仍走普通 Document、API 正常返回 JSON;不把路由声明误当作已经监听。
|
||||
|
||||
浏览器检查可对参考预览或活站点执行,按环境指定现有 Playwright 模块和 Chromium:
|
||||
|
||||
```bash
|
||||
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
|
||||
```
|
||||
|
||||
它测量 1440px 下的外层与内层双栏、390px 下的两层纵向折叠,并检查无横向溢出。无需外部资源或业务 JavaScript。Go 单元测试覆盖递归 Markdown、顺序、带类型列式表、错误形状与 Document 显式执行边界。
|
||||
|
||||
通用数据文档渲染测试已从硬编码个人数据库改为临时目录建表并注入已知数据,使完整 Go 套件无需个人站点状态。
|
||||
|
||||
Web 提交时,全库 Rust 为 436 通过、25 项既有策略/回放失败,基线失败集合相同。后续已单独修复 Rust→Lean 命令缺字段的问题:所有操作发送完整的 op、steps、value,进程错误保留退出码与 stderr。原 25 项失败全部消除,新增诊断回归后库级测试为 462 通过、0 失败。策略判定仍由 Lean 执行。
|
||||
@@ -0,0 +1,65 @@
|
||||
# Web 布局工程:先拆布局,直到 Markdown 叶子
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 状态 | Active,2026-11-08 可执行参考工程与浏览器门禁已落地 |
|
||||
| 包内手册 | [英文根入口](../../ext/web/index.mq.md) · [中文根入口](../../ext/web/网页/索引.mq.md) |
|
||||
| 布局工具 | [layout](../../ext/web/layout/index.mq.md) · [布局](../../ext/web/布局/索引.mq.md) |
|
||||
| 实现与边界 | [Web 手册优化](ext-web-handbook.md) · [Artifact](ext-web-artifact.md) · [ADR 0007](../adr/0007-web-document-endpoint.md) |
|
||||
|
||||
## 先建立区域树,再写内容
|
||||
|
||||
首页先拆成导航、主体、页脚。页脚若有左右两栏,拆成品牌与链接;链接区若还有双栏,再拆成文档与社区。继续按内部独立布局拆分,直到叶子只剩简单 Markdown 可以直接表达的内容。
|
||||
|
||||
```text
|
||||
index.mq.md → components/index.mq.md(纵排)
|
||||
├─ nav/index.mq.md → content.md
|
||||
├─ main/index.mq.md → content.md
|
||||
└─ footer/index.mq.md(分栏)
|
||||
├─ brand/index.mq.md → content.md
|
||||
└─ links/index.mq.md(分栏)
|
||||
├─ docs/index.mq.md → content.md
|
||||
└─ community/index.mq.md → content.md
|
||||
```
|
||||
|
||||
父文件只导入子块、合并兄弟节点并声明一层排列。叶子文件只说明一种内容职责;内容较长时,使用相邻的普通 content.md,避免字符串转义。拆分终点不是行数或文件数量,更不是每句话建一个文件。
|
||||
|
||||
## 何时继续拆、何时停止
|
||||
|
||||
| 观察 | 决定 |
|
||||
|------|------|
|
||||
| 导航、正文、页脚混在一个内容块 | 拆成父级装配和三个职责块 |
|
||||
| 页脚内部仍同时负责品牌与链接排布 | 再拆左右子块 |
|
||||
| 链接子块内部仍包含两个独立栏目 | 继续拆到各栏目 Markdown |
|
||||
| 叶子只包含标题、段落、列表、链接、表格、图片 | 停止;已可用普通 Markdown 表达 |
|
||||
| 父文件含大量正文、HTML 标签、CSS 字符串 | 职责或表达方式仍未收敛,继续拆解 |
|
||||
| 结构已经简单,只为减少行数而再拆 | 不必拆;以可读职责为准 |
|
||||
|
||||
表单、数据源、交互各有自己的领域职责,应调用对应模块,不以“Markdown 不表达交互”为由恢复整页 HTML 壳。只有确实需要兼容宿主能力时,才在隔离边界使用已有 raw/css 接口并说明原因。
|
||||
|
||||
## 同一表结构贯穿所有层
|
||||
|
||||
公共列是 `type | slot | value | attrs | style`,中文可用 `类型 | 槽 | 值 | 属性 | 样式`。使用 @ 记录表产生节点列表。
|
||||
|
||||
- `component.markdown` / `组件.正文`:叶子值为普通 Markdown。
|
||||
- `component.wrap` / `组件.包裹`:值中保留子节点列表,可标记 nav/footer/section 等语义区域。
|
||||
- `layout.stack` / `布局.纵排`:声明上下关系。
|
||||
- `layout.columns` / `布局.分栏`:声明响应式横向栏目。
|
||||
- `merge`:只确定兄弟顺序,不会自动产生双栏,也不提前渲染 HTML。
|
||||
|
||||
原生运行时提供基本布局几何,窄屏自动折叠。style 列引用类名,不承载 CSS 源码,也不会自动定义主题。父块始终保留结构值;先渲染子块再拼 HTML 会丢失这条统一路径。
|
||||
|
||||
## 从文件走到真正页面
|
||||
|
||||
[英文参考工程](../../examples/web-layout-handbook/index.mq.md)与[中文参考工程](../../examples/web-layout-handbook-zh/index.mq.md)实现上面的整个拆分树。先运行 preview.mq.md 检查真实渲染,再进入工程目录运行 serve.mq.md。
|
||||
|
||||
结构化 Document 显式声明 `view: main` / `视图: main`,main 返回节点;服务启动时装配一次。普通 Markdown Document 保留既有行为,Endpoint 单独处理请求期互动。改动结构或叶子内容后重启。自动数据源绑定继续使用普通 Document,避免与启动装配混用。
|
||||
|
||||
验收同时检查源码和产物:叶子只含普通 Markdown,父文件只表达其一层关系;桌面页脚出现真正的两层分栏,手机两层都折叠;关于页、API 仍能工作。规则清单本身不是“已经通过”的证明。
|
||||
|
||||
```bash
|
||||
cargo test --locked --test web_handbook
|
||||
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
|
||||
```
|
||||
|
||||
详细测试方式和当前能力边界见[优化记录](ext-web-handbook.md)。
|
||||
@@ -214,19 +214,23 @@ template = ["php", "-r", "{inline}"]
|
||||
|
||||
### 4.1 值映射
|
||||
|
||||
Canonical integer contract: [`v-safe-json.md`](v-safe-json.md) (Lean \(V_{\mathsf{safe}}\): `|n| ≤ 2^{53}-1`).
|
||||
|
||||
| Marqdo | JSON |
|
||||
|---|---|
|
||||
| None | null |
|
||||
| Bool | bool |
|
||||
| Int | number |
|
||||
| Num | number(NaN/Inf → null) |
|
||||
| Text | string |
|
||||
| List | array |
|
||||
| Map | object |
|
||||
| Int | number **仅当** `|n| ≤ 2^{53}-1`;越界 → 显式失败(禁止静默扭曲) |
|
||||
| Num | number(NaN/Inf → null);float 为宿主扩展,∉ mechanized \(V_{\mathsf{safe}}\) |
|
||||
| Text | string(宽整数用十进制字符串过桥,对端 `BigInt` / Python `int`) |
|
||||
| List | array(子树递归;任一越界整数使整体失败) |
|
||||
| Map | object(同上) |
|
||||
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
|
||||
| Code | 源码字符串 |
|
||||
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
|
||||
|
||||
错误前缀:`json: integer outside V_safe (±(2^53-1)): <n>`。
|
||||
|
||||
### 4.2 输入
|
||||
|
||||
- `input=` → JSON;写 stdin;同时提供 `MARQDO_INPUT`(≤8 KiB)与 `MARQDO_INPUT_FILE`(任意大小)。
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# 外联库论文的研究方向
|
||||
|
||||
作者于 2026-11-05 将论文主线明确为:**叙述本身是程序,外部代码是值**。
|
||||
Marqdo 的外联库用于在这一宿主模型中组合既有语言的计算能力,统一说明、控制流、
|
||||
代码复用、状态与显式数据交换。论文应先解释 Notebook/文学编程中的实际设计问题,
|
||||
再给出解决方案、可核验的收益、形式化依据和应用实验。
|
||||
|
||||
后续实现工作围绕绑定的代码值、参数化调用、持久会话、复制值和文档计划展开。
|
||||
生命周期、值域和重放机制为这个统一设计提供保证;不能将重放检查器重新提升成
|
||||
取代外联库与叙述式编程的论文主题。不得把未测的人因优势或未证明的实现正确性
|
||||
写成既成事实。
|
||||
|
||||
完整方向文件在论文工作区:
|
||||
|
||||
- 方向(当前):`MarqdoThesis/PLDI/design/V7-NARRATIVE-FIRST-DIRECTION-2026-11-05.md`
|
||||
- v6 方向(历史):`MarqdoThesis/PLDI/design/V6-NARRATIVE-FIRST-DIRECTION-2026-11-05.md`
|
||||
- 证据映射:`MarqdoThesis/PLDI/design/V6-EVIDENCE-MAP-2026-11-05.md`
|
||||
- 章节与页预算:`MarqdoThesis/PLDI/design/V6-OUTLINE-2026-11-05.md`
|
||||
|
||||
当前稿位于 `MarqdoThesis/PLDI/paper-v7`;v6 保留,历史 v5 及其证据保留。方向文件取代了
|
||||
此前把论文缩成“外联会话值 + 因果重放”的 N3 路线:重放是支撑机制,不是主线。
|
||||
|
||||
2026-11-05 交付:`MarqdoThesis/PLDI/paper-v7/main.pdf`,正文(含 AI Use)20 页。
|
||||
v6 保留为上一版尝试;更早的 v6 草稿保留在 `paper-v6-draft-2026-11-05/`。
|
||||
@@ -0,0 +1,44 @@
|
||||
# Foreign Strong: Lean ↔ host correspondence
|
||||
|
||||
2026-11-02 补充:`ForeignSource.lean` 对显式局部环境、返回、函数调用/递归、
|
||||
分支和有界 while 的源解释器与独立 effect 编译器证明一般精化,并推出安全
|
||||
观察和旧句柄不可复活。`CheckForeignSource.lean` 消费真实加载后 AST 的显式
|
||||
适配格式,用独立 counter oracle 对照 tree/bytecode 的返回、journal、fault
|
||||
与故障后 n。它已用于发现并修复 tree 的父词法作用域查找缺陷。
|
||||
这是源控制流层的证明与实现 translation validation;Rust parser/adapter、
|
||||
全部 AST 构造、机器数值运算和物理调度的完整 refinement 仍须完成。
|
||||
模型中的 fuel 是分析界限,不能称为真实程序必然终止或有界取消。
|
||||
|
||||
Pinned with PLDI Strong / paper-v5 (sessions as values; three gates).
|
||||
Marqdo **2.3.0** host implements the same objects the Lean development decides.
|
||||
|
||||
| Lean / paper rule | Host surface | Evidence |
|
||||
|---|---|---|
|
||||
| `SessionReg` + `sessionOpen` / `Close` / `sessionEval` | `HostContext.foreign_sessions` + `Value::Handle` | `DocCalc.lean` S1–S6, `requires_live`; `foreign_session.rs` |
|
||||
| `Ω(s, τ, c)` | Persistent kernel + process order | Oracle journal `(cell, source_hash, stdout, result)` |
|
||||
| `SafeVal` / Encode / Decode | `src/host/json.rs` + bootstrap sanitize | `ForeignJSON.lean`; gold `foreign-*-vsafe-*` |
|
||||
| Handle ∉ \(V_{\mathsf{safe}}\) | `value_to_json(Handle) → Err` | `foreign-session-handle-no-serialize.mq.md` |
|
||||
| Closed / Closed-Close | use-after-close / double-close `Err` | gold misuse; `sessionClose_then_eval_none_w` |
|
||||
| Oracle-Domain | Ω OOD integer → host `Err` | `foreign-session-result-vsafe-refuse.mq.md` |
|
||||
| Table arity stuck | Parse refuse unequal GFM; JSON unequal columns | `Surface.lean`; `tests/errors/table-arity.mq.md` |
|
||||
| Snapshot hash match/mismatch | `view/output.rs` `snapshot_page` | unit snapshot hash tests |
|
||||
| **Thm. corr** (`corr_fresh_functional`) | Cold `evaldoc`; step values = Ω | `corr_step_eq_omega`; `corr_doc_fresh_foreign`; foreign-session gold |
|
||||
| `OracleJournal` / `replayCheck` | `oracle_journal` + `DocumentSession::replay_check` | `replayCheck_*`; fate R1–R3 |
|
||||
| `corr_fail_warm_store` / `corr_fail_reordered_plan` | cold vs warm / schedule order | DocCalc witnesses; Table corr-fail |
|
||||
| Dual-backend differential | `tests/gold.rs` tree + bytecode | 308 × 2; foreign session/V_safe subset |
|
||||
|
||||
## Scope (not distance)
|
||||
|
||||
- SafeVal mechanization covers the **integer** fragment; finite floats are admitted by the host under the same refuse-not-coerce bridge policy for non-integers already in SafeVal.
|
||||
- Session discipline is a **dynamic registry** (affine close + borrow-use). Static linear types over OS-killable processes are out of scope by design, not an unfinished host feature.
|
||||
- Correspondence is mechanized for the **closed / fresh-open / functional-Ω** fragment (`corr_fresh_functional`): per-step interactive value = Ω answer, interactive runner = normative runner, `replayCheck` on the journal. Broken hypotheses are `corr_fail_*`. Host discharge is foreign-session gold plus R1–R3, not R1–R3 alone.
|
||||
|
||||
## Reviewer-driven implementation update (2026-11-01)
|
||||
|
||||
The independent live cursor and multisession action-plan simulation are in
|
||||
`DocCalc.runForeignLive_simulation` and `MarqdoProof.ForeignTrace`. The language
|
||||
now exposes oracle observations and pure journal comparison through
|
||||
`foreign.oracle_journal` / `foreign.replay_check`. Strict interactive snapshot
|
||||
replay uses the full oracle history with source identity and per-step input.
|
||||
See `oracle-journal-values.md` for the API and the research experiment manifest
|
||||
under `PLDI/experiments/reviewer-v5/` for exact source hashes and actual runs.
|
||||
@@ -0,0 +1,336 @@
|
||||
# Executable call and integer semantics
|
||||
|
||||
This describes the implementation contract exercised by
|
||||
`src/frontend_elaboration_tests.rs`; it is not a claim of a verified parser.
|
||||
|
||||
All explicit actual arguments evaluate once in authored order, including extra
|
||||
named arguments whose values the callee does not read. Binding then permutes
|
||||
already computed values into parameter slots. Named arguments take precedence
|
||||
over positional filling; duplicate names and excess positional arguments fail.
|
||||
A duplicate-actual binding fault occurs only when its call is reached, after
|
||||
all explicit actuals have evaluated; it cannot reject an unused function at
|
||||
compile time or erase an earlier argument effect.
|
||||
Local calls and imported calls use the same order. Builtins and host primitives
|
||||
must not reorder expression evaluation when selecting their parameter values.
|
||||
|
||||
All supplied parameters are available before defaults. Missing defaults execute
|
||||
in parameter declaration order, once per call, in the target definition's
|
||||
module and lexical scope. A default can see supplied parameters, earlier
|
||||
computed defaults, and an explicitly bound method receiver. It cannot capture
|
||||
the caller's locals. A still omitted later parameter is unbound. Explicit None
|
||||
is a supplied value and never triggers a default. Required-argument validation
|
||||
precedes default execution. Default expressions participate in receiver
|
||||
classification, dependency analysis and transitive effect inference.
|
||||
|
||||
A dynamic method's signature belongs to the resolved receiver and selected
|
||||
method; a different object's same-named method cannot supply its parameter
|
||||
list. Imported definitions retain their module scope. A compiled document's
|
||||
entry is selected only from its own module; an imported `main` is not an entry.
|
||||
|
||||
The bytecode retains argument names and explicit presence bits. Callee
|
||||
prologues evaluate defaults in their own frame. Local slots distinguish an
|
||||
unbound slot from a slot holding None. Local, constant, call-layout and jump
|
||||
indices use container-sized indices rather than unchecked 8/16-bit casts.
|
||||
Scratch slots are reused across sequential calls while pending outer actuals
|
||||
remain live. Scalar constant interning uses a hash table; floating constants
|
||||
are keyed by their exact bits.
|
||||
|
||||
Host integers are signed 64-bit values. Add, subtract, multiply, divide and
|
||||
negation report a language error on overflow in every build profile; division
|
||||
by zero is a separate error. Division truncates toward zero. The negative
|
||||
endpoint has a valid signed literal. Float-to-int conversion rejects nonfinite
|
||||
or out-of-range inputs instead of silently saturating. This local integer
|
||||
domain is distinct from the narrower continuous foreign-copy domain.
|
||||
|
||||
The Lean call-combinator proof preserves complete interaction programs for
|
||||
arbitrary argument evaluators, including failure and reply-dependent requests.
|
||||
The integer model specifies exact arithmetic followed by representability
|
||||
checking. Native documents, independently derived Python expectations, a Lean
|
||||
arithmetic consumer and isolated source mutations validate the implementation
|
||||
links. These do not prove the entire Rust parser, binder, object representation
|
||||
or adapter. The research coverage ledger must keep those obligations explicit.
|
||||
|
||||
## Module identity, entry inputs and source-bound invocation
|
||||
|
||||
Instances retain the existing map representation and safe-copy domain. The
|
||||
reserved `_type_module` field is a list of import binding names, paired with
|
||||
`_type`. Class selection uses that module instance within the active import
|
||||
tree; inherited methods resolve their bases in the defining module. Equal
|
||||
class names in different imports remain distinct. These fields are ordinary,
|
||||
forgeable data, not capabilities or globally portable nominal identities.
|
||||
Round trips through Python/Node preserve these descriptors in the same module
|
||||
context. Opaque session handles remain outside the copy domain.
|
||||
|
||||
Entry metadata is passed to `Vm::run`, never compiled into `main`'s body.
|
||||
Explicit named/recursive invocations of `main` therefore keep their own inputs.
|
||||
Defaults run with the invocation's actual registry; a session-valued default
|
||||
must not be evaluated in a separate interpreter and then injected into a VM.
|
||||
Reads appearing only in explicit/prose defaults participate in input inference
|
||||
and effect analysis. Default failures use the parameter declaration's span.
|
||||
Source-bound APIs preserve the selected declaration's source identity and
|
||||
span, even when two declarations have the same dotted path. Textual path calls
|
||||
retain the existing first-declaration rule. Duplicate parameter names are
|
||||
rejected because they cannot define distinct binding slots.
|
||||
|
||||
Both backends retain parameter, return and local field contracts. Bytecode
|
||||
checks supplied/defaulted inputs before the body, explicit returns before
|
||||
returning, table bindings before writing a local and direct footnote accesses
|
||||
before/after lookup. Unknown fields report the contract error before a generic
|
||||
missing-key error. Entry/raw invocations also check their completed inputs.
|
||||
Contract diagnostics retain the declaration quote and the failure location.
|
||||
|
||||
## Refinement obligations and current evidence
|
||||
|
||||
| Link | Mechanized result or implementation evidence | Remaining obligation |
|
||||
|---|---|---|
|
||||
| Raw Markdown to executable AST | Native explicit/prose defaults, source snapshots, parameter spans, inference and duplicate-parameter diagnostics | Prove the actual Rust classifier/parser and extraction rules; the older abstract grammar is not that proof |
|
||||
| Loaded module tree to flattened declarations | Independent inventories of source digests, module instances, lexical parents, class/method ownership and resolved bases | Connect the actual resolver to the Lean namespace lookup model, including failed/ambiguous resolution |
|
||||
| Effectful actual evaluation to parameter values | `FrontendCalls` proves interaction-program equality for arbitrary expression evaluators; native authored-order/unused-actual/builtin/foreign probes | Prove Rust scratch allocation, every expression case and its stack invariant against that combinator |
|
||||
| Default evaluation and invocation inputs | Native callee-scope, presence, receiver, entry/raw/metadata, inference, error-span and stateful-session cases | A complete default-binding semantics and universal compiler refinement, including errors and host context |
|
||||
| Module-qualified object dispatch | `ModularObjects` proves namespace flattening lookup, resolved-parent dispatch and safe descriptor round trips | Connect every real object constructor, resolver and copied descriptor to the model; justify Rust module-root lifetimes |
|
||||
| Machine integers | `MachineInts` exact signed-64 model, checked boundary implementation, independent Python and Lean consumers | Connect Rust checked arithmetic and every conversion to the mathematical evaluator; floats remain an extension |
|
||||
| Progressive contracts | Four real source boundary failures preserve codes, anchors and failure spans; valid contract execution | Universal contract-preservation theorem and imported declaration/call-site attribution |
|
||||
| Source-bound external calls | Two same-path declarations execute their separately selected source lines on both backends | Full external argument validation, effect-policy and environment-injection refinement |
|
||||
|
||||
The ledger deliberately does not turn a new model lemma, a finite passing
|
||||
corpus, or independent reconstruction into a complete frontend theorem. Those
|
||||
remaining proof links are required to discharge the full frontend objective.
|
||||
|
||||
## Default prologue proof and imported contract attribution (November 4)
|
||||
|
||||
`DefaultPrologue.default_prologue_refines` relates source default binding, which
|
||||
rechecks the current environment for omission, to a guarded block machine with
|
||||
an immutable initial presence mask. It proves whole interaction-program equality
|
||||
for arbitrary effectful evaluators, assuming distinct parameter slots and an
|
||||
initially faithful presence mask. Earlier default stores preserve that invariant
|
||||
for later parameters. The duplicate-slot counterexample issues two requests in
|
||||
the machine versus one in the source, demonstrating why slot uniqueness matters.
|
||||
Explicit None skips and immediate failure stopping are separately checked.
|
||||
This is a model of guard/evaluate/store blocks, not a proof of the Rust emitter,
|
||||
flat instruction stepping, actual expression compilation or parser.
|
||||
|
||||
The generated implementation family crosses all 27 omitted/int/None states for
|
||||
three parameters with all six declaration orders. An independent environment
|
||||
model checks 162 documents and 324 executions, including 34 faults when a default
|
||||
reads a later omitted parameter. Source text is reconstructed independently;
|
||||
expected traces are not derived from either backend. This finite family does
|
||||
not prove arbitrary defaults. Imported argument-contract diagnostics now retain
|
||||
the caller's failure span and source revision while pointing the declaration
|
||||
anchor and suggestion at the actual library. Supplied and defaulted invalid
|
||||
arguments both refuse before entering the callee body.
|
||||
|
||||
## Concrete name and flat-code interfaces
|
||||
|
||||
The compiler now borrows each original declaration and owning module while
|
||||
flattening. Bare-call selection uses the same source `lookup_local` operation
|
||||
as Tree, then maps the selected declaration identity to its flat index. This
|
||||
removes a second, subtly different lookup algorithm: repeated top-level names
|
||||
previously selected the first declaration in Tree but failed compilation in VM.
|
||||
It does not prove the source lookup operation itself.
|
||||
|
||||
`NameSlots` proves reads, writes and the complete named-argument binding fold
|
||||
commute with an injective local-name vector. Unknown names and repeated raw
|
||||
API names are covered; repeated raw names retain last-write semantics. A
|
||||
presence mask computed from initialized slots is faithful by construction.
|
||||
The Rust raw entry and argument binder now derive their mask from the actual
|
||||
initial logical slots. Method receiver aliases are overlaid only for default
|
||||
evaluation, and restored into the body frame after logical argument checks.
|
||||
`ReceiverDefaults` supplies the additional environment reasoning for explicitly
|
||||
declared self/自 parameters; the slot theorem alone does not cover that case.
|
||||
|
||||
Every compiled Program is structurally verified before return, and the VM
|
||||
verifies even publicly constructed/mutated Programs before any instruction.
|
||||
All current opcode variants are handled exhaustively. Checks include operand
|
||||
bounds, parameter/local prefix and injectivity, declaration and inheritance
|
||||
forests, call-layout and function references, spans, reachable stack underflow,
|
||||
branch/loop join heights and absence of leaked stack values on return. Missing
|
||||
variable values remain language faults; this checker does not prohibit them.
|
||||
|
||||
Rust exports the computed per-PC heights alongside the real emitted opcode
|
||||
text. `CheckFlatCertificate.lean` independently decodes that text and applies
|
||||
an executable checker whose soundness is proved in `FlatCertificate`. Accepted
|
||||
certificates preserve heights along every finite path and guarantee a valid
|
||||
fetch with sufficient operands on each reachable PC, including loop prefixes.
|
||||
The independent reader rejects unmodeled opcodes. Rust debug serialization and
|
||||
opcode-to-concrete-VM-step correspondence remain interfaces to justify; a
|
||||
structural certificate does not establish source/bytecode functional equality.
|
||||
|
||||
Neither this ordinary bytecode verification technique nor reuse of a resolver
|
||||
is an originality claim. Complete functional lowering, parser semantics and the
|
||||
Rust implementation correspondence remain open proof obligations.
|
||||
|
||||
## Functional expression checks and receiver views (November 4)
|
||||
|
||||
The emitter now records source-directed expression rules before emission, with
|
||||
child order and exact instruction intervals. The mandatory native verifier
|
||||
checks literal identity (including floating-point bits), local names, unary and
|
||||
binary operators, short-circuit targets, interpolation, collections, indexing
|
||||
and occlusion. Calls delegate staging and selection checks to `bytecode/call.rs`;
|
||||
resolution and dispatch semantics remain explicit boundaries.
|
||||
All seven statement forms have source-directed templates; a separate forest
|
||||
check covers the entire default prologue, statement body and implicit return.
|
||||
These checks detect stack-preserving semantic corruption, including Add to Sub,
|
||||
and refuse it before host effects. A forged source witness remains outside this
|
||||
check's guarantee; the recorder and actual AST correspondence need justification.
|
||||
|
||||
`ExpressionLowering` proves postfix expression compilation preserves complete
|
||||
interaction programs for arbitrary effectful leaves and operator interpretations,
|
||||
including faults and an arbitrary caller stack and continuation. `ShortCircuit`
|
||||
proves the exact absolute-PC AND/OR macros under arbitrary effectful child
|
||||
evaluation. `CheckExpressionLowering.lean` independently reads actual emitted
|
||||
operators, constants and local names, and applies the proved core checker.
|
||||
It counts call, collection, index and interpolation boundaries explicitly.
|
||||
Child inlining, Rust VM stepping, leaf interpretation and source-witness fidelity
|
||||
remain obligations; none of these results is whole-frontend functional refinement.
|
||||
|
||||
`ReceiverDefaults` proves that the source's separately maintained default
|
||||
environment equals the machine's receiver view after every successful prefix.
|
||||
The mask describes logical argument slots, while omitted self/自 defaults may
|
||||
replace the evaluation view. Supplied None remains present. The real receiver
|
||||
is restored before entering the body; argument contracts check both the logical
|
||||
arguments at the call site and the restored frame at the declaration, preserving
|
||||
source identity and diagnostic frames. The theorem composes this view invariant
|
||||
with `DefaultPrologue` for arbitrary effectful defaults and distinct slots.
|
||||
|
||||
Concrete repairs also share scalar/unary semantics across evaluators, stringify
|
||||
every interpolation part, allocate fresh loop temporaries, restrict dynamic
|
||||
calls to their defining module scope, and enforce the existing one-million
|
||||
truthy-iteration limit in VM as well as Tree. Regression evidence records each
|
||||
repair separately from proof claims. These compiler techniques are not new
|
||||
originality claims.
|
||||
|
||||
## Actual call staging and bounded control-flow macros
|
||||
|
||||
Every emitted call now has a separate source obligation captured before actuals
|
||||
are replaced with scratch reads. The checker covers authored actual order,
|
||||
evaluate/store/pop triples, source-local and loop-slot separation, nested-call
|
||||
scratch separation, argument reloads, layouts, builtin selection/defaults, host
|
||||
primitive identity, plugin name/pair ordering, method name/receiver and resolved
|
||||
user target/tag. Every call expression must have exactly one obligation. The
|
||||
reserved source-local prefix is established before any synthetic slots are
|
||||
allocated. Disjoint nested calls may reuse scratch slots after their lifetimes.
|
||||
|
||||
`CallStaging` proves the flat evaluate/save/pop program restores an arbitrary
|
||||
caller stack and has the same effects and failures as authored-order collection.
|
||||
It proves outside slots unchanged and unique staged slots read back the exact
|
||||
actual vector. The dispatch continuation is arbitrary and effectful, so binding,
|
||||
defaults and receiver effects can follow collection without commuting effects.
|
||||
`CheckCallStaging.lean` decodes real stores and reloads, applies the proved stage
|
||||
checker and independently checks the complete selection/dispatch template.
|
||||
Source-expression callback correspondence, name resolution and the semantics of
|
||||
each dispatch continuation remain proof interfaces. Host parameter metadata is
|
||||
an exported registry interface, not an independently verified registry theorem.
|
||||
|
||||
`WhileLowering` proves the condition/JF/check/body/backedge macro preserves the
|
||||
complete interaction program for a bounded loop, including a final false
|
||||
condition, condition/body faults, the truthy-iteration limit and early returns.
|
||||
It relates an increasing native counter to a decreasing model budget and proves
|
||||
admitted increments below one million fit u32. Model machine-step fuel is
|
||||
distinct from this language-visible iteration budget.
|
||||
`CheckStatementLowering.lean` checks actual default prologues, all seven statement
|
||||
templates, forests and implicit returns, including the exact while macro layout.
|
||||
The while theorem uses condition/body callbacks; concrete child inlining and the
|
||||
full Rust state machine are not discharged by checking those layouts. Branches
|
||||
and foreach currently have independent template evidence, not new functional
|
||||
refinement theorems. No ordinary compiler-checking technique is a novelty claim.
|
||||
|
||||
## Loaded executable AST and coherent witness corruption
|
||||
|
||||
`SourceFunction` now captures parameters, defaults, executable bodies and complete
|
||||
contract data directly from the loaded declaration before emission. The native
|
||||
source checker walks that snapshot separately from the rule recorder, checks
|
||||
ordered expression/statement correspondence and complete witness ownership,
|
||||
and accounts for the generated scratch reloads explicitly. It also compares
|
||||
full contracts with structural Rust equality, including types, nullable fields,
|
||||
descriptions, source lines and declaration quotes. Contract presence alone would
|
||||
not detect a Number-to-Any weakening.
|
||||
|
||||
The evidence exports the executable AST separately from the original module and
|
||||
from the compiled snapshot. `CheckSourceWitness.lean` matches declaration
|
||||
identities and applies `SourceWitness`'s proved ordered-tree reconstruction
|
||||
checker. Interpolation parts, index labels, code payloads and formula structure
|
||||
are retained; all formula floats and matrix entries retain their exact bits.
|
||||
The old Debug formula text was insufficient for NaN payload identity. Inert
|
||||
occlusion prose and pre-inference parser metadata are not execution-tree nodes.
|
||||
|
||||
Ten native coordinated-corruption cases change code together with its witness,
|
||||
including operators, constants, variables, assignments, callees, NaN payloads,
|
||||
index keys, interpolation, contract metadata and an orphan expression record.
|
||||
Eight independent source-witness negatives include changing the compiled snapshot
|
||||
as well. A coordinated wrong operator is a positive acceptance control for all
|
||||
four earlier independent consumers and a rejection control for the AST checker.
|
||||
This distinguishes trusted source correspondence from agreement among emitted
|
||||
metadata fields.
|
||||
|
||||
The theorem proves exact correspondence of the supplied executable trees, hence
|
||||
preservation under any interpretation of those trees. The native and JSON AST
|
||||
adapters, normalization helpers and snapshot capture remain trusted interfaces.
|
||||
No theorem here verifies the actual Markdown classifier/parser/inference or
|
||||
connects every concrete Rust operation to the semantic models. A caller who
|
||||
changes both the reference AST and its program has supplied a different
|
||||
translation-validation input; this is not source authentication.
|
||||
|
||||
## Runtime argument-preparation faults
|
||||
|
||||
The expanded AST audit exposed a concrete acceptance mismatch: Tree can execute
|
||||
main while an unused function contains a conflicting bracket modifier, whereas
|
||||
VM compilation previously rejected the entire module. Modifier preparation now
|
||||
lowers its failure to `RejectArgumentExpansion` before actual evaluation. A
|
||||
provided default parameter, including explicit None, skips that fault; reaching
|
||||
it preserves prior output and stops before actual effects or a suffix. The
|
||||
error's message, span, source revision and diagnostic frames match Tree.
|
||||
|
||||
`CallExpr::for_evaluation` normalizes bare aliases before modifier expansion,
|
||||
matching Tree's existing order. The expression checker validates an effect-free
|
||||
fault leaf and the independent decoder handles its actual terminal opcode.
|
||||
The AST adapter explicitly represents that executable fault without children;
|
||||
unexecuted actual expressions are not falsely counted as evaluated code.
|
||||
Two independent fault-opcode/message negatives and a positive AST-identity-only
|
||||
control keep representation checking distinct from instruction interpretation.
|
||||
|
||||
The independent Python oracle now compares JSON values with exact recursive
|
||||
types and requires integer arithmetic inputs to be actual integers. Python's
|
||||
True==1 and 1==1.0 equalities must not erase language-visible value distinctions.
|
||||
Four type-corruption controls are added. These improvements do not discharge
|
||||
other call-error timing, parser, resolver, dispatch or Rust-step proof obligations.
|
||||
|
||||
## Native binding and declaration graph validation
|
||||
|
||||
Builtins, host primitives and plugins retain authored labels in native bytecode.
|
||||
The shared value-independent binding plan selects named parameters before
|
||||
positionals, preserves omitted optional bindings and unknown named extras, and
|
||||
reports duplicate, missing and surplus positional arguments after actual effects.
|
||||
Plugin lookup precedes signature binding. Eighteen reached/unreached error cases
|
||||
check explicit expected output, messages, spans, source revisions and frames.
|
||||
A registered C ABI echo probe checks mixed and extra named arguments. Execution
|
||||
uses the native VM and plugin bridge throughout.
|
||||
|
||||
The source and flat declaration views share ordered resolution. A loaded snapshot
|
||||
captures ordinal declaration paths, levels, child/root counts, imports and ordered
|
||||
use aliases before emission. Verification checks identity, parent/child/root order,
|
||||
module scopes and object/method names, then derives call targets independently of
|
||||
emitted target records. Two-component paths check runtime receiver presence before
|
||||
static fallback; an unbound reserved slot differs from a supplied None. Imports
|
||||
retain priority. Resolution failures are native terminal instructions after actuals.
|
||||
|
||||
`NameResolution` proves first-match, path and lexical commutation under an
|
||||
ordered embedding. Its rank checker proves sufficient depth and connects a
|
||||
well-founded total source policy to flat lookup. Rust uses the same parent-chain
|
||||
policy; parent-view extraction remains a trusted adapter. The finite checkers consume actual AST/flat evidence in
|
||||
`CheckNameResolution.lean`. Nine native corruptions and seven independent graph
|
||||
negatives test this boundary. A coordinated wrong target remains a positive control
|
||||
for the older stack, staging and AST-shape consumers. Ordinary compiler correctness
|
||||
ingredients are not novelty claims. Snapshot/JSON adapters, primitive registries,
|
||||
parent-view extraction and concrete Rust
|
||||
instruction refinement remain explicit obligations; universal frontend verification
|
||||
and overall paper readiness are not established by these results.
|
||||
|
||||
`ArgumentBinding` separately models per-parameter omission permission and proves
|
||||
value substitution preserves selections and faults. A successful index plan has
|
||||
a finite-index witness. `CheckArgumentBinding.lean` checks actual static call
|
||||
plans and an independently enumerated mask/label corpus. User VM calls now use
|
||||
the shared planner with the callee default mask, correcting their surplus-count
|
||||
diagnostic and preserving missing-required-before-default priority. Default
|
||||
evaluation, contracts, dynamic signature selection and concrete Rust/JSON steps
|
||||
remain separate interfaces. The mathematical planner is not a proof of the
|
||||
entire native binding implementation.
|
||||
@@ -1,5 +1,7 @@
|
||||
# 标准库 / 扩展库:代码即文档
|
||||
|
||||
当前可执行开发规范见[库开发指南](../library-development.mq.md),其中的真实函数示范叙述内赋值、遮蔽调用、表格数据与返回。本页保留设计背景与历史波次。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
@@ -10,39 +12,51 @@
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库不写长文;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
|
||||
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库用充分且具体的叙述解释短实现;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
|
||||
|
||||
## 2. 薄库模板(默认)
|
||||
## 2. 单文件标准库模板
|
||||
|
||||
每个导出函数 / 方法尽量按此骨架(中英分文件锁步):
|
||||
标准库通常是一个 `lib/*.mq.md` 文件,源码自身承担使用手册、开发说明与 SKILL。
|
||||
直接阅读、导入或调用此文件,不增加强制 `index.mq.md` 或平行模块手册。
|
||||
多文件拓展库才用 `index.mq.md` 组织模块与开发路线。
|
||||
|
||||
1. **目的句**(一句人话,无标记即可)。
|
||||
2. **叙述形参**:正文里出现 `` `名` `` / `` `名`=默认 ``(推断签名);过渡期可保留 `` + `名` ``。
|
||||
3. **一例**:粗体或 `>` 调用;优先可读表面。
|
||||
4. **实现**:短;取元用 `[键](集合)`,**禁止新增**脚注取元 `` `m`[^k] ``(旧解析仍可用)。
|
||||
每个函数依次提供:标题、参数表(名称、类型、默认值、含义)、返回契约、效应说明、
|
||||
叙述形参、用途与真实调用例子、简短实现。无参数函数直接放返回表。
|
||||
参数和返回契约位于第一条执行语句之前;标准库不再保留旧 `+` 形参清单。
|
||||
|
||||
调用示例(三种等价,试点期任选;新叙述优先括号标记或粗体):
|
||||
叙述形参使用正文中的反引号名称,默认值紧跟等号;表格说明与实际默认值必须一致。
|
||||
例如正文写「输入路径 `path`」,调用时即可提供 path。含标点的文本默认值使用完整引号。
|
||||
不透明类型保留渐进式 any,并说明其产生途径和限制。
|
||||
|
||||
## 3. 可读性与调用规范
|
||||
|
||||
每个函数单元的叙述比例必须超过 50%,同时说明真实用途和边界;不能靠重复套话凑比例。
|
||||
参数和返回契约表属于文档面,绑定的数据表仍须表达真实数据。
|
||||
|
||||
宿主等不透明调用用遮蔽语法表达动作:`[]` 写做什么,`()` 写实际执行代码。
|
||||
返回和赋值仍遵循原有标记;标签不执行,也不替代失败处理。
|
||||
|
||||
```markdown
|
||||
**出 = [put] 入=`表` 键="a" 值=1**
|
||||
## read_text
|
||||
|
||||
**出 = put 入=`表` 键="a" 值=1**
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| path | text | 必填 | 授权根目录内的文件路径 |
|
||||
|
||||
> put 入=`表` 键="a" 值=1
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | text | UTF-8 文本;无效编码或读取失败产生诊断 |
|
||||
|
||||
输入路径 `path`。此操作读取整个文件;大文件应改用分块读取。
|
||||
文件根目录由调用方授权,不能通过传入路径绕过权限。
|
||||
|
||||
读取完成后,我们返回*[读取授权范围内的 UTF-8 文本](> host_read_text path=`path`)*,供调用方继续处理。
|
||||
```
|
||||
|
||||
带布尔开关时可用前置修饰:`严格 [parse] text=`源`` → `严格=True`(形参名与修饰语字面一致;核心不剥「的」等词缀)。
|
||||
|
||||
## 3. 硬约束
|
||||
|
||||
| 要 | 不要 |
|
||||
|----|------|
|
||||
| GFM 表作数据;`table.put` / 具名助手 | `json.set` 链当字典构造器 |
|
||||
| 作者程序用 `[k](c)` 取元;`- [项](集合)` foreach | 新代码写 `` m[^k] `` |
|
||||
| 中英 API 对称(见 [stdlib-i18n.md](stdlib-i18n.md)) | 只改一侧 |
|
||||
| 一例跑通即文档(public/stdlib 或 examples) | 另开第二套「文档站」手写说明 |
|
||||
|
||||
**库函数体内的叙述坑:** 函数体里的链接形 `[k](c)`、以及单独的 `**强调**` 会被当成可执行代码。库内说明用「链接取元 / link-index」等字面描述;可执行示例放在 `public/stdlib` 或 `examples/`,不要写在 `##` 体内当叙述。
|
||||
集合读取使用 access(collection, key),不使用旧链接取元;循环使用显式遍历。
|
||||
用 GFM 表和具名助手表达结构化数据,避免 json.set/json.append 链。
|
||||
说明中的调用示例放在未绑定代码围栏内,不能让示例意外成为函数执行步骤。
|
||||
中英文源码保持语义、默认值与行为一致;检查叙述比例、契约并执行真实示例。
|
||||
|
||||
## 4. 波次
|
||||
|
||||
|
||||
@@ -1,5 +1,35 @@
|
||||
# 文档会话(View Cells)
|
||||
|
||||
## 2026-11-02:并发控制与完整历史 v5
|
||||
|
||||
以下为当前实现;后文保留首版设计与当时的状态表。
|
||||
|
||||
- HTTP `kernel/interrupt` 查找已存在的会话,经独立控制器发送请求,不等待单元执行锁或其他文档的初始化。未打开、尚在初始化的会话返回错误,不启动新内核。已加载文档的源码文件被删除后仍可取消正在执行的单元。
|
||||
- 内核的中断能力绑定其持有的子进程,并在回收前撤销;旧能力不能指向后来启动的内核。引导阶段的取消被暂存,收到 ready 后投递。逻辑取消输入会合并重复信号;投递错误明确返回。Windows 尚无对应的保状态中断实现。
|
||||
- 取消使 Run All 在当前单元结束后停止,返回实际 `ran`、`remaining` 和 `cancelled`;不会继续运行后续单元。内核没有退出时,取消前已发生的状态修改保留。close 撤销 API 会话,重新打开不会激活旧引用。
|
||||
- 完整历史 v5 将并发取消作为所在操作的 `controls` 输入记录:操作起点之后的微秒偏移及各内核的真实接收结果。严格回放按输入重新投递并重新观察回执;操作先结束时撤销剩余定时请求,不能流入下一操作。实际回执或观察不匹配就报告差异。v4 无控制输入的历史仍可检查;v4 中出现 controls 字段会被拒绝。
|
||||
- 严格检查先完成纯验证,再启动回放内核。实际执行中,每次协议请求必须先与预期请求一致;实际回复和每个单元的观察、批次结果也立即比较。首个差异后停止依赖后缀,包括同一个 Run All 内的后续单元。未执行的观察标记 `compared=false`,不冒充已比较的第二个差异。
|
||||
|
||||
快照导出支持可选 `compact:true`。默认仍为完整 JSON;紧凑格式
|
||||
`marqdo.history.dag` v1 对相同子值做自底向上共享,整数使用十进制文本、
|
||||
浮点数保存 IEEE 位模式,保留映射顺序和全部历史字段。导入和严格回放会自动
|
||||
识别格式。SHA-256 校验只检测内容一致性,不提供来源认证。
|
||||
解码要求规范节点、向后引用、全部可达和唯一键,并在展开前检查最多
|
||||
1,000,000 个节点、8,000,000 个展开值、512 MiB 保守展开预算、128 层深度;
|
||||
展开后再次检查安全值域。此格式减少导出字节数,尚未减少录制时内存,也不保证更快。
|
||||
|
||||
实际取消实验覆盖 Unix 上同步 Python/Node 持久会话;不能推导任意外部代码均有界停止。
|
||||
[Python 3.14 信号文档](https://docs.python.org/3.14/library/signal.html#execution-of-python-signal-handlers)
|
||||
说明纯 C 计算可延迟信号处理;
|
||||
[Node 22.22.1 vm 文档](https://nodejs.org/download/release/v22.22.1/docs/api/vm.html#timeout-interactions-with-asynchronous-tasks-and-promises)
|
||||
说明异步任务可能逃出同步求值的中断范围。完整源码 elaboration、控制适配器、
|
||||
真实时钟与信号调度到形式模型的 refinement 仍需完成,不能以这些测试代替。
|
||||
|
||||
相关实现:`foreign_session/control.rs`、`foreign_doc/control.rs`、
|
||||
`foreign_doc/packing.rs`、`foreign_doc/replay.rs` 与 `view/notebook_api.rs`。
|
||||
真实 TCP/HTTP 取消、逐单元副作用屏障和独立快照消费记录位于论文
|
||||
`PLDI/experiments/reviewer-v5/`。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
# Document oracle observations and strict replay
|
||||
|
||||
`foreign.oracle_journal` returns a copy of this evaluation's observations as
|
||||
ordinary `index/channel/value` records. Successful admitted `session_eval`,
|
||||
`session_get`, and document `json.parse` operations append `eval`, `get`, and
|
||||
`decode`, respectively. Set/open/close do not append. An observation is
|
||||
validated recursively before append; handles and code objects cannot enter.
|
||||
Each new HostContext starts with an empty observation list.
|
||||
|
||||
`foreign.replay_check expected=J observed=J2` is a pure comparison, with no
|
||||
foreign execution. It validates contiguous zero-based indices, channel tags
|
||||
and crossing-domain membership. Records compare structurally by field name,
|
||||
independent of field order. The result contains `ok`, the least mismatching
|
||||
`index`, and both records (None for a missing entry). Two empty journals
|
||||
match. Failure to provide a valid journal is an error, not a match.
|
||||
|
||||
The interactive `DocumentSession::replay_check(snapshot)` is a different layer:
|
||||
it executes a recorded trace from fresh state. Version-2 snapshots contain the
|
||||
full chronological oracle trace, recorded stdin per step, its declared count,
|
||||
the plan and source identity. Preflight validates every step before any foreign
|
||||
execution. Every step is compared; none is skipped. Repeated cell executions
|
||||
are distinct observations. Execution timing logs and cell display summaries
|
||||
are not comparison inputs. Matching input values in a supplied snapshot is
|
||||
consistency checking, not cryptographic authentication of the recording.
|
||||
|
||||
Snapshots carry the SHA-256 of the loaded document text. Import checks it
|
||||
before restoring foreign bindings, and preflights all crossing payloads before
|
||||
mutation. Reload retains prior oracle observations with their original source
|
||||
hashes, so a later checker can reject an incompatible trace.
|
||||
|
||||
Lean: DocCalc's independent `runForeignLive` cursor simulates `runForeignAcc`
|
||||
for arbitrary prefixes, observation accumulators and code sequences, including
|
||||
oracle failures. `ForeignTrace` composes the registry's open/eval/close
|
||||
judgments using independent normative and interactive execution control;
|
||||
`trace_simulation`, `trace_correspondence`, and `trace_replay` quantify arbitrary
|
||||
multisession action sequences, also when a run faults. These supplement the
|
||||
existing theorems without removing them.
|
||||
|
||||
Tests: `tests/oracle_journal.rs` runs the public document API on both evaluators;
|
||||
`host::oracle::tests` covers journal equality and length localization;
|
||||
`host::foreign_doc::tests` covers the live trace preflight and actual replay;
|
||||
`host::foreign_session::tests` includes generated two-session model checks and
|
||||
Python/Node boundary and process-failure experiments. The research runner is
|
||||
`MarqdoThesis/PLDI/experiments/reviewer-v5/run.py`.
|
||||
|
||||
## Stateful requests and semantic projection
|
||||
|
||||
`HostContext.foreign_protocol_steps` records internal request attempts and
|
||||
replies, including set values, copied eval input and raw stdin. It is separate
|
||||
from the admitted language journal: rejected inbound responses belong to the
|
||||
protocol evidence, while only admitted values belong to the oracle journal.
|
||||
An input refused before send produces no protocol request. A response refused
|
||||
after execution does not undo kernel effects; the post-state is retained.
|
||||
|
||||
Language observations are recorded at the document API boundary and by live
|
||||
cell evaluation. Low-level get/names used during snapshot export do not append
|
||||
language observations. A successful eval projects to its result. A failed eval
|
||||
projects to a record of stable status, output and diagnostics. Process timing,
|
||||
commands and handles are not semantic values. The exact source path allocated
|
||||
for one-shot execution is alpha-renamed only in diagnostic fields; raw stderr
|
||||
and stdout remain available unchanged, and ordinary paths/error differences
|
||||
are still compared. Live oracle records carry this same projected `value`.
|
||||
|
||||
Python/Node replies mark serialization-domain failure with `domain_error`.
|
||||
Error text is not used to infer this flag. Python refuses non-string object
|
||||
keys; Node sanitizes objects with a null prototype to preserve special keys.
|
||||
The common strict JSON decoder checks duplicate keys before materializing a
|
||||
map, rather than losing them through overwrite.
|
||||
|
||||
`ForeignState.lean` refines the earlier eval-only fragment with opaque kernel
|
||||
state, complete request histories, set/get/eval input/decode, monotonic handle
|
||||
allocation and fault outcomes carrying the admitted prefix. An adaptive
|
||||
Program has continuations on actual observations; its correspondence theorem
|
||||
covers data-dependent next actions, not just a fixed schedule. Mapping actual
|
||||
document elaboration and host bindings to this program is a further proof
|
||||
obligation recorded in the research status file.
|
||||
|
||||
## Complete history, snapshot version 4 (2026-11-02)
|
||||
|
||||
Strict interactive replay now records operations, not just successful cells.
|
||||
Each public execution/mutation boundary records typed arguments, success or
|
||||
failure, admitted observations, cell-oracle records, and stable resulting
|
||||
state. Nested implementation calls are grouped under the user's operation.
|
||||
The history includes set/get, run/step/run-all, restart, reload, plan edits,
|
||||
clear, snapshot inspection and imported values. Failed attempts remain in the
|
||||
history; rejected handles and secrets have only non-capability/redacted tags.
|
||||
Clearing display outputs cannot erase the history's oracle projection.
|
||||
|
||||
The snapshot stores the materialized initial plan and historical reload plans.
|
||||
Entry text is parsed at its original path, retaining relative imports without
|
||||
rewriting the user's document. Initial bindings are reapplied when a kernel is
|
||||
reopened; unchanged reload kernels retain state, whereas changed language or
|
||||
command retires the incompatible process. Loaded source/metadata and cached
|
||||
cell outputs are updated consistently.
|
||||
|
||||
Preflight checks the entire operation stream, all source revisions, plan edits,
|
||||
binding/cursor/generation transitions, and oracle projections before starting
|
||||
any replay kernel. Executing the trace compares each result, admitted value,
|
||||
cell result and stable state. The first mismatch stops its dependent suffix;
|
||||
`executed_actions` and `remaining_actions` make this explicit. `matched` counts
|
||||
admitted observations and `matched_actions` counts operations. No missing
|
||||
record is silently accepted or skipped.
|
||||
|
||||
The HTTP replay-check endpoint performs an isolated comparison and retains an
|
||||
existing warm session. It validates malformed input before starting even a
|
||||
seed kernel; duplicate JSON fields are refused before overwrite. Verification
|
||||
can still run recorded foreign work and its external effects: isolation is of
|
||||
the document session, not a process sandbox. `replay_snapshot` remains the
|
||||
separate legacy cell re-run API and makes no strict-history comparison claim.
|
||||
Older version-2/3 snapshots may be used by legacy restoration/re-run surfaces;
|
||||
they cannot prove a complete action history and strict checking requires v4.
|
||||
|
||||
`ForeignHistory.lean` models explicit command boundaries. A fault terminates
|
||||
its command, a later command receives the actual retained registry, and the
|
||||
history retains all command faults and admitted observations. It proves
|
||||
command-history correspondence, journal membership and no alias resurrection
|
||||
through arbitrary recovery histories. This extends the adaptive Program
|
||||
results; the general source-elaboration refinement is a separate outstanding
|
||||
proof obligation.
|
||||
|
||||
Experiment source inputs are frozen before running, checked again afterward,
|
||||
and archived with their hashes. The current passing bundle is identified by
|
||||
`MarqdoThesis/PLDI/experiments/reviewer-v5/LATEST-PASSING.json`.
|
||||
|
||||
Each operation also retains its internal protocol attempts/replies, including
|
||||
refused inspection results. Those records are compared even when an inspector
|
||||
could not return a value. They are control evidence and do not admit rejected
|
||||
payloads into the language journal. An explicit document session_names request
|
||||
adds its admitted array on the decode channel; internal names/get probes do not.
|
||||
Reload records either a historical source/plan input or its input-read error;
|
||||
replay consumes that captured version input and does not rewrite past files.
|
||||
@@ -0,0 +1,130 @@
|
||||
# 标准库:代码、文档、SKILL 与 tools 同源
|
||||
|
||||
标准库通常是单文件:直接阅读并调用 [fs.mq.md](../../lib/fs.mq.md)、[文件.mq.md](../../lib/文件.mq.md)、[table.mq.md](../../lib/table.mq.md) 或其他任务所需源码。
|
||||
31 个模块族对应 61 份公开标准库单文件;源码本身承担手册与 SKILL,不设强制总入口或模块 index。
|
||||
多文件拓展库的 index 用于组织多文件,标准库沿用其可读性和调用规范。
|
||||
|
||||
## 源码就是手册
|
||||
|
||||
每个函数标题下立即放参数表(名称、类型、默认、含义),随后是返回契约、效应、叙述形参、
|
||||
用途和边界、实际调用例子及短实现。无参数函数直接放返回表。旧 `+` 形参已移除。
|
||||
契约表位于首条执行语句之前;默认值和参数顺序保持兼容。
|
||||
|
||||
叙述比例逐函数超过 50%;既检查比例,也检查真实契约、调用和错误语义。
|
||||
不透明宿主指令使用遮蔽调用,例如 `` *[读取 UTF-8 文本](> host_read_text path=`path`)* ``:
|
||||
方括号说明目的,圆括号执行真实代码;赋值语句同样采用描述标签。
|
||||
标签不替代参数与权限,也不能用空标签或重复模板代替说明。调用与返回自然写入正文;
|
||||
行内表达式仍计作代码,绑定数据表不冒充叙述。125 份库源码的统一验收见
|
||||
[本轮记录](../roadmap/library-authoring-refactor.md),公共标准库当前为 650 个函数。
|
||||
键值行记录可用 table.from_pairs / 表.键值转记录生成具名记录,保留空值和重复键更新语义。
|
||||
|
||||
## 接口事实来自编译器
|
||||
|
||||
现有 call、catalog、MLSP 与编译器读取同一份标准库源码,不额外包装一层目录函数或示例函数。
|
||||
`examples/stdlib_catalog.rs` 使用实际装载、签名和效应结果检查源码中的效应说明;
|
||||
--json 输出接口事实,--write 仅刷新效应说明,不生成第二套手册。
|
||||
人工维护用途、参数含义、失败处理和工程实践。不透明值保留渐进式 any,并说明来源和限制。
|
||||
|
||||
```sh
|
||||
cargo run --example stdlib_catalog -- --json
|
||||
cargo run --example stdlib_catalog -- --check
|
||||
marqdo check lib/文件.mq.md --narrative-ratio
|
||||
cargo test --test stdlib_tasks
|
||||
```
|
||||
|
||||
测试直接读取 61 份公开源码中的实际命令,在 Tree 与 Bytecode 执行 126 次。
|
||||
验证每个函数的参数/返回契约、标题下表格、无旧形参声明以及逐函数叙述比例。
|
||||
|
||||
## 能力与兼容性
|
||||
|
||||
| 任务 | 新的公共入口 | 关键契约 |
|
||||
|---|---|---|
|
||||
| 文件整理 | fs.find/read_lines/write_lines/read_json/write_json/read_csv/write_csv | 明确根目录、格式和资源上限 |
|
||||
| 文件修改 | atomic_write/write_changed/write_checked | 单文件原子替换;摘要检查不是内核 CAS,竞争写入仍需协调 |
|
||||
| 批量文件 | copy_tree/sync_tree/rename_many | 先预检冲突,覆盖需选择;不承诺多文件事务;目录复制面向普通文件,不复制权限、链接与空目录 |
|
||||
| 临时文件 | make_temp/temp_dir | 在授权根目录创建,由调用方明确清理;真实工程演示清理 |
|
||||
| 二进制 | bytes 与 fs.read_bytes/write_bytes/read_chunk/append_bytes/file_hash | 普通 bytes 记录,Base64 跨 CLI/JSON/插件传递,字节偏移从零起 |
|
||||
| 集合 | range/enumerate/pluck/project/where/find/any/all | 不增加回调字符串求值或新的查询方言 |
|
||||
| 表数据 | group_by/aggregate/summarize/join/rename/unique_by/sort_keys | 行记录、分组键和字段含义明确;批量汇总避免作者循环反复复制列表 |
|
||||
| 数据形态 | from_columns/to_columns/cast/try_cast/validate | 不猜测列式表与普通对象;列长、字段及类型错误有明确结果 |
|
||||
| 集合运算 | union/intersection/difference | 返回保序列表,沿用运行时值相等规则 |
|
||||
| 网络 | net.get/request/download/header_values | 超时、响应上限、重复响应头、字节响应;失败下载保留原文件 |
|
||||
| 配置与日期 | toml.parse/stringify、datetime.parse_local/add_calendar | 标准 TOML;内嵌 IANA 规则;夏令时缺口和重叠明确失败或选择 |
|
||||
| 子任务 | wait_timeout/cancel_all/run_many | 文件任务并发上限、超时终止回收、父权限与根目录继承 |
|
||||
| 文档维护 | document.sections/section/tables/links/code_blocks/replace_section/replace_table | 与渲染共用 Markdown 解析器,不执行文档,保留周围源码 |
|
||||
| 归档 | archive.pack/unpack | 可选 ZIP,预检路径、链接、重复项和展开上限,目标必须不存在 |
|
||||
|
||||
旧 remove 保持递归删除行为,公开文档已纠正;新代码用 remove_file/remove_empty_dir。
|
||||
access 与 put 的整数路径从一开始;旧 at/slice/insert/remove_at 等接口从零开始,不能混用。
|
||||
更新返回新集合,原值保留;单次追加仍有复制成本。规模任务使用批量变换,去重使用分桶并保留原相等语义。
|
||||
混合排序采用明确类型顺序,修复数字与文本混排造成非传递比较的问题。
|
||||
大下标在 32/64 位目标上保持一致:取元越界为空,更新越界为诊断,巨大分块大小不会截断成零或导致死循环。
|
||||
|
||||
## 权限与错误
|
||||
|
||||
宿主身份声明效应,编译器沿解析后的依赖传播,不依据 fs、net 等导入别名猜测。
|
||||
函数、BoundCall 和步骤共享最终效应,外部标准库和中英文别名也使用同一逻辑。
|
||||
|
||||
```sh
|
||||
marqdo call lib/fs.mq.md read_text 'path="notes.md"' --effects fs.read --fs-root /absolute/project --json
|
||||
marqdo call lib/fs.mq.md atomic_write 'path="notes.md"' 'text="updated"' --effects fs.write --fs-root /absolute/project --json
|
||||
```
|
||||
|
||||
默认 none 只准纯函数;fs.write 包含读取授权,其余能力仍需明确选择。
|
||||
plugin 保留加载提示所需的既有能力,不增加文件写入、网络或进程执行授权。
|
||||
根目录检查覆盖新文件的最近已存在父路径与符号链接越界。
|
||||
会话保存规范化根目录与可持久化结果;重建会话不重复文件、网络或进程写操作。
|
||||
不可重放写操作缺少快照时明确拒绝,不能为了重建句柄偷偷重做。
|
||||
|
||||
可恢复操作统一返回 `{ok,value,error}`,错误含 code/message/operation,校验错误可附 details。
|
||||
代码来自明确错误标签与 IO 错误种类,不扫描任意路径文本猜类别。Result 不授权操作,也不捕获任意语言错误。
|
||||
CLI 外层 ok 表示调用成功;函数值的 Result.ok 表示操作协议成功;HTTP status、子进程 code 仍需按领域判断。
|
||||
语法、契约与不可恢复运行错误继续使用原有结构化 Diagnostic,保留库来源和调用点。
|
||||
|
||||
## 平台与资源边界
|
||||
|
||||
| 能力 | 原生 | WebAssembly 浏览器目标 | CoW 试运行 |
|
||||
|---|---|---|---|
|
||||
| 集合、文本、JSON/CSV/TOML、字节数据、文档结构、静态时区计算 | 支持 | 纯计算可构建;具体浏览器熵/时钟依赖桥接 | 支持 |
|
||||
| 原生文件与分块 IO | 支持 | 未接入浏览器文件系统时明确不可用 | 文件内容经覆盖层;已有目录枚举/元数据为宿主快照,试运行变更用 sandbox.diff/inspect |
|
||||
| 文件复制、移动、追加与文本补丁 | 支持 | 无原生 FS | 经覆盖层;复制最多 64 MiB,不绕过试运行写入真实文件 |
|
||||
| 目录状态、目录树批处理、归档、流式下载 | 支持 | 原生专属能力不可用 | 未建模的目录/原生任务明确拒绝 |
|
||||
| HTTP、进程、动态插件 | 按构建特性支持 | 原生接口不可用;浏览器使用 browser 效果与桥接 | 依 profile/caps,不以库包装绕过 |
|
||||
| 子任务取消 | 进程可终止并回收 | 不提供原生子进程 | 函数线程仅逻辑取消;有界批处理只接收文件任务 |
|
||||
|
||||
新增有界读取默认 8 MiB、上限 64 MiB;旧 read_text 及其格式组合接口保留整文件读取语义,大文件使用 read_chunk/file_hash;原生文件摘要和下载使用 64 KiB 缓冲区。
|
||||
查找最多十万条目;序列和连接最多一百万结果;文件批处理最多一万任务、六十四并发。
|
||||
HTTP 时限与字节上限由调用方明确设置;不自动重试可能修改远端状态的请求。
|
||||
TOML 日期转换为 ISO 文本;写出不保留注释,None 和非有限数没有支持的表示。
|
||||
IANA 数据随锁定依赖交付,不声称总是最新政策数据。ZIP 不提供完整备份语义。
|
||||
|
||||
## 真实工程与验收
|
||||
|
||||
[标准库工程](../../examples/stdlib-handbook/index.mq.md)和[中文入口](../../examples/stdlib-handbook/索引.mq.md)同时完成:
|
||||
|
||||
1. 扫描 Markdown,保留逐文件读取结果;坏 UTF-8 不阻止其他记录。
|
||||
2. 读取 CSV,转换字段,筛选并批量分组汇总,输出 CSV。
|
||||
3. 精确替换章节,以读取文本的摘要检查来源,保留其他叙述并原子写入。
|
||||
|
||||
`tests/stdlib_tasks.rs` 验证公开文档和双后端,而非只测私有宿主调用。
|
||||
附加测试覆盖 CoW 不落盘、写入快照不重放、超时后继续等待、网络参数预检、重复响应头、
|
||||
失败下载保留目标、ZIP 越界与链接、夏令时、TOML、混合排序和十万项去重。
|
||||
旧诊断测试从编译器 AST 定位库指令,继续严格检查独立调用点;不再因添加文档而依赖固定行号。
|
||||
|
||||
## 构建验证
|
||||
|
||||
原生默认特性、精简 wasm-core 特性、真实 wasm32 交叉编译均已验证。
|
||||
浏览器 ABI 与 `tests/wasm/stdlib.mjs` 在当前 wasm 产物上由 Node 执行,覆盖集合、字节、
|
||||
文档、TOML、IANA/DST、32 位大下标与嵌套路径诊断。Node 验收不是浏览器 DOM 布局验收。
|
||||
|
||||
发行版 rustc 与官方 wasm 标准库的构建元数据不能混用;本次使用同版本匹配的官方组件,
|
||||
校验后在临时目录构建并执行,不依赖修改系统工具链。复现时使用已安装对应 wasm32 标准库的工具链:
|
||||
|
||||
```sh
|
||||
cargo check --no-default-features --features wasm-core
|
||||
cargo build -p marqdo-wasm --target wasm32-unknown-unknown
|
||||
node tests/wasm/smoke.mjs target/wasm32-unknown-unknown/debug/marqdo_wasm.wasm
|
||||
node tests/wasm/stdlib.mjs target/wasm32-unknown-unknown/debug/marqdo_wasm.wasm
|
||||
```
|
||||
单文件结构修正后,全量 970 项测试通过,0 失败,2 个原有忽略项;其中包括 17 项标准库工程测试。
|
||||
完整命令、分轮计数和交叉目标结果见[实施验收记录](../roadmap/stdlib-executable-handbook.md)。
|
||||
@@ -1,5 +1,7 @@
|
||||
# 标准库 L1 模块
|
||||
|
||||
直接阅读并导入标准库单文件,例如 [文件](../../lib/文件.mq.md)和[表](../../lib/表.mq.md)。每个文件自身就是手册,函数标题下给出参数表、返回契约和动作说明;不要求额外 index。模块分层与历史波次见下表,当前规范见[标准库说明](stdlib-handbook.md)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **核心已落地**;**Mid M1–M6 已落地**;**Mid2 规划中** · [stdlib-mid2.md](stdlib-mid2.md) / [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
|
||||
|
||||
@@ -1,85 +1,49 @@
|
||||
# Ubuntu PPA packaging (Marqdo)
|
||||
# Ubuntu PPA: executable packaging and publication
|
||||
|
||||
| | |
|
||||
The maintained entry is [the release handbook](../../skills/marqdo-release/index.mq.md). [ubuntu.mq.md](../../skills/marqdo-release/ubuntu.mq.md) provides publication and observation tasks; [package.mq.md](../../skills/marqdo-release/package.mq.md) owns native metadata and staged file preparation. Their source contracts replace a separate command playbook.
|
||||
|
||||
The PPA is ppa:cflmy/marqdo. Apt installs the interpreter; extensions remain independently installed by marqdo ext add. Upload acceptance alone is incomplete: the exact source must be published, its amd64 build must succeed and apt must expose the same Debian version.
|
||||
|
||||
## Exact version and artifact
|
||||
|
||||
| Value | Meaning |
|
||||
|---|---|
|
||||
| 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` |
|
||||
| X.Y.Z | Cargo package.version and the authorized upstream |
|
||||
| 1ppaN | Reviewed debian/changelog packaging revision |
|
||||
| ~SERIES | Explicit Ubuntu target, normally noble |
|
||||
| marqdo_X.Y.Z-1ppaN~SERIES_source.changes | Exact signed source artifact |
|
||||
| ext/VERSION | Independent extension-pack version |
|
||||
|
||||
## Goal
|
||||
Native upstream and debian_version tasks parse the actual files. The latter retains the reviewed revision, removes its old series suffix and selects the current upstream/target series. A packaging-only reupload needs an explicit changelog revision edit. Upload selects the exact computed filename, never the newest unrelated package from a previous release or another series.
|
||||
|
||||
Users install with:
|
||||
## Callable workflow
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:cflmy/marqdo
|
||||
sudo apt update
|
||||
sudo apt install marqdo
|
||||
Run from the checkout root after the user has authorized this CLI/full release. Replace X.Y.Z with that version:
|
||||
```sh
|
||||
marqdo call skills/marqdo-release/ubuntu.mq.md ship 'version="X.Y.Z"' 'series="noble"' --require-ok --effects plugin,fs.read --fs-root . --json
|
||||
marqdo call skills/marqdo-release/ubuntu.mq.md status 'version="X.Y.Z"' 'series="noble"' --require-ok --effects plugin,net --fs-root . --json
|
||||
marqdo call skills/marqdo-release/index.mq.md finish 'version="X.Y.Z"' 'mode="full"' --require-ok --effects plugin,net,fs.write --fs-root . --json
|
||||
```
|
||||
|
||||
CLI and extension packs stay independent: the `.deb` ships the **interpreter**; `marqdo ext add …` still pulls from **https://ext.marqdo.com** (then GitHub / proxy).
|
||||
Status is observational: inspect complete as well as Result.ok. Finish turns incomplete publication into a failed Result, allowing --require-ok to stop automation while keeping evidence. A green GitHub run does not establish Launchpad completion or apt availability.
|
||||
|
||||
## Why bundled Rust?
|
||||
## Native files and existing tools
|
||||
|
||||
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.
|
||||
Marqdo reads version metadata and writes the staged Cargo configuration, Debian changelog and vendor-checksum repairs. Native filesystem, TOML and JSON functions carry the data. No generated Python reader or writer is used. Vendor repair removes backup entries that Debian cleaning would delete while retaining package digests and ordinary source hashes.
|
||||
|
||||
## One-time Launchpad setup
|
||||
The existing Debian boundary uses Cargo vendor, tar/xz, the configured Rust installation, debuild, GPG and dput. The source archive includes vendored crates and the selected Rust toolchain for an offline build. Its script chooses a fixed default toolchain and exposes the existing override; it does not assume the build host compiler is sufficient.
|
||||
|
||||
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:
|
||||
A new upstream may create an orig archive. Once Launchpad accepts that upstream, reuse the identical bytes and upload only the Debian revision. Never rebuild an accepted orig archive to work around a checksum rejection. A failed stage remains available for inspection.
|
||||
|
||||
```bash
|
||||
sudo apt install build-essential debhelper devscripts dput lintian \
|
||||
dpkg-dev quilt cargo rustc pkg-config curl xz-utils
|
||||
```
|
||||
## Recovery evidence
|
||||
|
||||
## Package layout
|
||||
| Failure | Required action |
|
||||
|---|---|
|
||||
| sudo/GPG interaction unavailable | Complete the same concrete Debian boundary in the user's terminal, keeping version and series |
|
||||
| Complete package version already used | Review and increment the Debian revision before another authorized upload |
|
||||
| orig bytes differ | Retrieve and reuse the previously accepted archive |
|
||||
| Offline vendor checksum failure | Inspect sanitize_vendor evidence and the retained staged tree |
|
||||
| Source accepted, build pending/failed | Inspect the actual Launchpad build |
|
||||
| Build green, apt metadata stale | Repeat apt observation for the exact version |
|
||||
|
||||
| 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
|
||||
Public apt observation reads Packages.gz with native HTTP bytes and the bounded gzip boundary, then inspects actual package records. Isolated fixtures cover metadata selection, configuration writing and vendor-checksum preservation without uploading to a PPA.
|
||||
@@ -0,0 +1,90 @@
|
||||
# \(V_{\mathsf{safe}}\) JSON integer contract (host ↔ Lean)
|
||||
|
||||
Canonical Lean model: `MarqdoThesis/PLDI/proofs/MarqdoProof/MarqdoProof/ForeignJSON.lean`.
|
||||
Host mapper: `src/host/json.rs` (`json_to_value` / `value_to_json`).
|
||||
|
||||
This document freezes **runtime conformance** of the Marqdo JSON bridge to the
|
||||
mechanized \(V_{\mathsf{safe}}\) integer domain. It is **not** a verified
|
||||
compilation of the Rust interpreter.
|
||||
|
||||
## Domain
|
||||
|
||||
```
|
||||
MAX_SAFE = 9007199254740991 # 2^53 - 1
|
||||
```
|
||||
|
||||
\(V_{\mathsf{safe}}\) values (mechanized):
|
||||
|
||||
| JSON | Marqdo |
|
||||
|---|---|
|
||||
| `null` | `None` |
|
||||
| `bool` | `Bool` |
|
||||
| integer with `\|n\| ≤ MAX_SAFE` | `Int` |
|
||||
| `string` | `Text` |
|
||||
| `array` | `List` |
|
||||
| `object` | `Map` |
|
||||
|
||||
**Host extension (not in Lean `SafeVal`):** JSON non-integer numbers → `Value::Num(f64)`. Non-finite numbers (NaN/Inf) are refused on encode and in Python/Node oracle responses, including nested payloads. Floats are documented host behavior; they are **not** claimed as mechanized \(V_{\mathsf{safe}}\) fidelity.
|
||||
|
||||
## Encode (`value_to_json`)
|
||||
|
||||
- `Value::Int(n)` with `|n| ≤ MAX_SAFE` → JSON number.
|
||||
- `Value::Int(n)` with `|n| > MAX_SAFE` → **refuse** (error).
|
||||
- `Value::Handle(_)` → **refuse** (`json: session handle cannot be serialized`).
|
||||
- Column-table `Map` whose fields are all `List` with **unequal lengths** →
|
||||
**refuse** (`json: table column arity mismatch`).
|
||||
- Nested `List` / `Map`: any child refuse fails the whole tree.
|
||||
- GFM table **parse** also refuses unequal row width
|
||||
(`table row arity mismatch`) before a value is built.
|
||||
- Wide integers that must cross a language boundary: author converts to a
|
||||
**decimal string** (∈ \(V_{\mathsf{safe}}\)); the foreign program may use
|
||||
`BigInt` / Python `int` on that string.
|
||||
|
||||
## Foreign oracle (`session_eval` / `session_get`)
|
||||
|
||||
Python/Node session bootstraps sanitize results with the same integer gate
|
||||
before JSON emission. An Ω response containing an OOD integer is a **fault**
|
||||
(host `Err`), not a soft `ok:false` cell record. Stdout text that authors
|
||||
`json.parse` themselves is still gated by host `json_to_value`.
|
||||
|
||||
## Decode (`json_to_value`)
|
||||
|
||||
- JSON integer with `|n| ≤ MAX_SAFE` → `Int`.
|
||||
- JSON integer with `|n| > MAX_SAFE` → **refuse**.
|
||||
- JSON unsigned integer `> i64::MAX` → **refuse** (do **not** coerce via `f64` or `Text`).
|
||||
- Nested array/object: any child refuse fails the whole tree.
|
||||
- Decimal-string encodings of wide integers → `Text` (in domain).
|
||||
|
||||
## Error prefix
|
||||
|
||||
All refuse messages use a fixed prefix for probes and diagnostics:
|
||||
|
||||
```
|
||||
json: integer outside V_safe (±(2^53-1)): <n>
|
||||
```
|
||||
|
||||
## In-domain roundtrip
|
||||
|
||||
`±MAX_SAFE`, bool, null, string, array, and object roundtrips through
|
||||
`encode → decode` must succeed. Integers `MAX_SAFE+1`, `-MAX_SAFE-1`, `2^53`,
|
||||
`2^60`, `2^60+1` (and nested forms) must refuse.
|
||||
|
||||
## Non-claims
|
||||
|
||||
- Not verified Rust ↔ Lean compilation.
|
||||
- Not arbitrary host-object fidelity (DataFrame, functions, heap sharing).
|
||||
- Not automatic BigInt promotion inside Node/Python bootstraps.
|
||||
- Document-level `Value::Int` may still hold i64 values that are OOD for JSON;
|
||||
the gate fires when those values enter JSON encode/decode.
|
||||
|
||||
## Strict request boundary update
|
||||
|
||||
The numeric gate applies to the represented value, including integer-valued
|
||||
floats and exponent notation. `9007199254740992.0` and
|
||||
`9.007199254740992e15` are refused; fractions such as `1.5` remain in the host
|
||||
extension. `serde_json` uses `float_roundtrip` to avoid endpoint decoding loss.
|
||||
The strict text decoder rejects duplicate object keys and unequal column maps
|
||||
before information is lost. One-shot, call_many and persistent input paths
|
||||
use recursive domain admission; code, handle and secret values are not copied
|
||||
implicitly. Auto-detection may leave non-JSON output as text, but valid JSON
|
||||
outside the domain is a refusal, including in batch results.
|
||||
@@ -16,17 +16,22 @@
|
||||
|
||||
| AST / 概念 | View 优先显示 | 备注 |
|
||||
|------------|---------------|------|
|
||||
| `Expr::Index` | `[键](基)` | 嵌套 `[k2]([k1](base))` |
|
||||
| `InterpPart::Index` | 同上嵌套链接形 | 不再默认 `` `base`[^k] `` |
|
||||
| `Expr::Occluded` | 正文只读动作说明,实际实现进入侧注 | 每个片段独立关联,不把整句改成一次赋值 |
|
||||
| 空遮蔽 `()` | 待补充实际逻辑 | 当前空遮蔽返回 None,不伪装成已接通工具 |
|
||||
| `Expr::Index` / `InterpPart::Index` | 保留经典或脚注取元的兼容说明 | 当前作者程序优先用 access 读取集合;默认链接形是遮蔽 |
|
||||
| `CallExpr` + `bracket_marked` / `pre_modifiers` | `修饰 [callee] 实参…` 或 `[callee] 实参…` | 仅经典 `>` 解析时仍显示 `> callee …` |
|
||||
| 赋值 / 返回 | 粗体 / 斜体语义即可 | 不强制还原整句叙述 |
|
||||
| foreach | `- [项](集合)` | 不变 |
|
||||
| 赋值 / 返回 | 保留原叙述句子,在真实执行片段上标明语句或返回 | 普通链接与字面量不冒充执行遮蔽 |
|
||||
| foreach | `- [动作](遍历 集合 为 项)` | 正文显示动作,控制逻辑见侧注;迭代选择器只切换已有运行记录 |
|
||||
|
||||
## 3. 非目标
|
||||
|
||||
- 不把 view 做成第二语法;解析真相仍在 mapping / call-arguments。
|
||||
- 不删除对脚注取元、旧 `>` 调用的兼容显示需求时,可用次要提示,但默认推荐面优先。
|
||||
|
||||
当前阅读器的实现与验收见 [view-readable-actions.md](view-readable-actions.md)。
|
||||
可执行知识先展示输入、返回、调用边界、依赖和各项依据;摘要和机器身份按需展开。
|
||||
源码说明与运行标注分开,展开侧注或知识卡片不会执行代码。
|
||||
|
||||
## 4. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# View:动作留在正文,逻辑留在侧注
|
||||
|
||||
本轮针对阅读界面,不改变语言求值和工具权限。阅读示例为
|
||||
[view-reading.mq.md](../../examples/view-reading.mq.md)。
|
||||
|
||||
遮蔽按真实 AST 识别,随后按源片段保留句子:方括号的动作说明留在正文,圆括号中的
|
||||
实现进入独立侧注。同一句话可以包含多个调用和返回,不再把整行当成一次赋值。
|
||||
文字字面量中的链接、普通 Markdown 导航与 classic 取元不冒充执行遮蔽。
|
||||
空圆括号明确显示“待补充实际逻辑”,并说明当前空遮蔽返回 None。
|
||||
|
||||
宽屏实现侧注与运行标注共用现有的左右避碰及引出线布局,彼此有明确名称区分。
|
||||
实现侧注标记“源码说明 · 不是运行结果”,不带调用帧或迭代帧身份。
|
||||
密集区域、窄屏和无脚本页面使用可原生展开的 details;动作按钮可按需查看完整逻辑。
|
||||
悬停与键盘聚焦关联实际源片段,不触发运行。
|
||||
|
||||
“怎样读这份可执行文档”沿用核心构造注册表,说明参数、赋值、返回、调用、条件、
|
||||
循环、数据表、代码块、公式、写回与兼容标记。公式和外语代码仍使用既有卡片,
|
||||
不新增语法或作者必填的展示配置。
|
||||
|
||||
可执行知识按真实源单元分组。默认先读输入、返回、调用边界、依赖和验证依据,
|
||||
身份、摘要与原始状态收进技术详情。契约说明来自已解析的参数和返回表;缺失时如实说明。
|
||||
语法检查、契约检查、测试、来源和领域审阅分别展示,静态分析不代表实际执行或内容正确。
|
||||
源码结构步骤与实际运行时序分开;内存面板先展示最终绑定与调用记录,再按需展开原始报告。
|
||||
|
||||
函数的说明链接和知识卡片使用当前文档源行定位,避免同名方法共用一个 DOM 身份。
|
||||
单文件阅读只分析它和实际导入的依赖,避免无关同目录模块重名导致知识区整体失败。
|
||||
目录阅读保留项目分析。来源身份及版本匹配沿用现有编译器和页面 token,不另建求值器。
|
||||
|
||||
验收入口:
|
||||
|
||||
```sh
|
||||
cargo test --offline --lib view::
|
||||
cargo test --offline --test view_readability
|
||||
cargo test --offline --test gold view_
|
||||
cargo test --offline --test executable_knowledge
|
||||
marqdo view output examples/view-reading.mq.md --no-exec --out /tmp/marqdo-reading
|
||||
```
|
||||
|
||||
浏览器验收脚本是 [readability.browser.cjs](../../tests/view/readability.browser.cjs),
|
||||
接收真实页面 URL,支持 MARQDO_PLAYWRIGHT_MODULE、MARQDO_CHROMIUM 和 MARQDO_SCREENSHOT_DIR。
|
||||
覆盖七种宽度、侧注边界与碰撞、多动作句子、空逻辑、知识卡片、正文定位和无脚本回退。
|
||||
原有 [reader.browser.cjs](../../tests/view/reader.browser.cjs)继续覆盖曲线、帧选择及实时/静态交互。
|
||||
|
||||
本轮实际验收(2026-11-08):67 项 view 相关单元测试、2 项新增只读导出测试通过;
|
||||
全量回归 984 通过、0 失败、2 个原有忽略项。真实 Chromium 验证静态快照、
|
||||
只读导出和实时页面,覆盖七种宽度、无脚本阅读、曲线与帧切换、源码定位及实时重新运行。
|
||||
GOFLAGS 仅对完整回归命令关闭工作区所有权引起的 Go VCS 盖章失败,不改全局配置。
|
||||
@@ -0,0 +1,64 @@
|
||||
# View botanical reader
|
||||
|
||||
Implemented 2026-11-07 for the shared `marqdo view` and `marqdo view output` shell.
|
||||
|
||||
The default is warm paper, serif document text, olive runtime notes, gold accents,
|
||||
and generated transparent blossom/feather ornaments. The M/book logo is embedded
|
||||
SVG. Navigation and the floating toolbar are code-native SVG icons and CSS.
|
||||
|
||||
`src/view/reader.css` is the final theme layer after notebook component styles;
|
||||
`src/view/reader.js` owns reader navigation, dialogs and annotation geometry.
|
||||
Notebook APIs and controls remain available through More → advanced tools.
|
||||
Welcome files get a larger introduction; ordinary files retain compact titles.
|
||||
|
||||
## Runtime notes
|
||||
|
||||
Annotations keep their existing owner band, stable IDs, source anchor, call frame
|
||||
and loop iteration data. Chips serialize source line and byte spans so another
|
||||
call/iteration frame can find the same source mark without guessing by kind.
|
||||
On viewports wider than 1000px with 180px available on each side, notes use both
|
||||
page margins, varying horizontal reach and vertical offset with collision
|
||||
avoidance. Dense bands that would drift more than 170px retain inline notes.
|
||||
Compact screens, printing, and expanded overflow bands use ordinary document
|
||||
flow. A shared SVG overlay draws continuously curved connections from the actual
|
||||
mark's source-facing lower edge to the annotation title. The default is a full
|
||||
S-curve with restrained gold/olive gradient; candidate sweeps are checked against
|
||||
visible source text and already drawn connections. Tight prose uses two joined
|
||||
curves below the text baseline and through the free margin, with no straight rail.
|
||||
Notes sit closer to the document with varying horizontal/vertical offsets, rather
|
||||
than stretching every connector across the entire page. Wrapped source marks use
|
||||
their actual line fragments. Hover/focus highlights the exact source and connector.
|
||||
Unresolved source anchors retain inline results instead of inventing a connection.
|
||||
Clicking a note shows its full captured detail. No explanatory prose or runtime
|
||||
values are invented.
|
||||
|
||||
Layout updates after window/font/structure resize, frame selection and live DOM
|
||||
replacement. Static HTML includes the same code and embedded assets. All KaTeX
|
||||
scripts, CSS and fonts are bundled for offline math. Optional syntax highlighting
|
||||
retains the previous CDN progressive enhancement; code remains readable offline.
|
||||
|
||||
`api/session/run_document` now returns prose HTML, bindings and trace JSON from
|
||||
its own capture. The reader applies that capture without rerunning the program.
|
||||
Page tokens prevent a changed source from receiving mismatched annotations.
|
||||
|
||||
## Navigation
|
||||
|
||||
Document returns to prose. Functions/Variables move the real existing panels into
|
||||
a modal and restore them on close, preserving their existing event handlers.
|
||||
Memory shows the captured execution report, labeled as a snapshot on exports.
|
||||
Run navigates to the output section. Search finds document, function and file text.
|
||||
The floating toolbar labels its icons 刷新 / 设置 / 运行 / 清理 / 更多.
|
||||
The bottom play button invokes actual live execution; static pages explain how to
|
||||
start a live view. Static clear hides captured output locally; reload restores it.
|
||||
Settings control light/dark theme, text size and annotation visibility. More keeps
|
||||
source, advanced execution controls, file navigation and print within reach.
|
||||
|
||||
## Validation
|
||||
|
||||
Run `cargo test --offline --lib view::` and `cargo test --offline --test gold view_`.
|
||||
The browser regression is `tests/view/reader.browser.cjs <URL>`; it accepts
|
||||
`MARQDO_PLAYWRIGHT_MODULE`, `MARQDO_CHROMIUM`, and optional
|
||||
`MARQDO_SCREENSHOT_DIR`. It blocks HTTPS resources to exercise offline reading,
|
||||
checks seven viewport widths, note bounds/collisions, source/label curve endpoints, visible curvature and non-crossing paths,
|
||||
shared-source frame binding, stable redraw, real panel restoration,
|
||||
search, frame selection, note inspection and live/static run behavior.
|
||||
@@ -0,0 +1,25 @@
|
||||
# View 中的请求资源
|
||||
|
||||
状态:请求资源已实现,后续旧站点迁移继续进行。遵循 ADR 0007;沿用五列 View、普通表值与 Resource,不增加 Markdown 标记或 frontmatter 方言。
|
||||
|
||||
view: main 仍只在启动时执行一次。它返回的结构保留为 View 节点,服务器在每次请求准备会话、路由参数和 CSRF 后渲染。普通 Markdown、控件和布局没有额外业务执行;只有 type=resource 的节点把 value 中的已声明 Resource 交给对应原生处理器。
|
||||
|
||||
Resource 的职责明确分开:data_query 查询当前应用数据库;form_ref 引用显式挂载的表单;view_navigation 根据当前会话筛选导航。document_head 是纯文档资源,只贡献 SEO 与原生资源链接,不需要请求上下文。它们不接受任意页面属性,不恢复 compose_*、页面变异链或 app.configure。结构和文字继续递归拆成组件及 Markdown 叶子。
|
||||
|
||||
启动阶段检查节点和资源契约,不查询数据库、不提交表单。请求渲染失败保留真实诊断。离线纯渲染遇到查询、表单与会话导航时明确要求上下文,不伪造空列表、登录状态或表单提交成功。纯页头资源与普通内容可以直接预览。
|
||||
|
||||
数据查询使用原有数据库资源与条件格式,路由参数来自实际请求。表单通过原有系统路由处理,字段、规则和提交资源保持一致,并传递真实 CSRF 与返回地址。导航的可见性不能替代服务端鉴权。资源绑定和监听仍是独立步骤。
|
||||
|
||||
验收覆盖启动无数据查询、请求间新增数据可见、完整正文与摘要区分、动态路由条件、登录前后导航、表单校验与提交、CSRF、未知资源失败,以及原有静态布局和浏览器用例。
|
||||
|
||||
|
||||
已完成的实际证据:web-net-site 与 web-net-site-zh 使用这些资源完整迁移;web_handbook 在两个启动后端中验证请求期间的数据更新、表单错误重试、工具页与后台鉴权。原生 Go 测试验证结构装配不查询缺失数据库、未知资源失败、路径条件不污染保留定义、CSRF 拒绝与错误重试。browser_handbook.mjs 使用当前 WASM 验证连续回显、Enter 与空输入、实际提交与管理后台、窄屏布局。
|
||||
|
||||
入口与边界:component.resource(中文组件为“请求资源”,保留原“资源”作为脚本/样式引用)、data/view.query、form.reference 与 form.mount、component.navigation。表单挂载可显式保护实际系统提交路径,不能只保护展示页面。服务器回调继承授予的文件根,所选站点根只能收窄该范围;嵌套页面按统一站点根读取共享叶子,Endpoint 同样保留该上下文。
|
||||
|
||||
|
||||
片段沿用 /_part/{slot}:递归选择唯一具名区域,在当前请求上下文中解析其资源;不会把源码当作片段返回。未声明 main 槽时保留整组节点作为 main 的兼容回退,其他未知槽返回 404,重复槽保留歧义诊断。容器遍历与完整渲染共享同一类型表,不进入资源私有数据。
|
||||
|
||||
检视的 registered 范围复用真实监听的注册过程,捕获处理器路径但不执行处理器;不会初始化数据库、重置会话或调用页面。metadata 范围仅扫描文件声明与运行时模板。两者明确区分,不能把目录扫描当成资源绑定已经完成的证据。监听前使用同一注册校验,冲突以诊断返回。系统和声明清单均去重并稳定排序。
|
||||
|
||||
页头资源保留现有五列 View:组件只安放 `_type=document_head` 的具型值,原生渲染在离线和真实页面中收集到 head,不在正文或片段中渲染占位。它只有 meta 与 links 两个领域字段,不接受任意页面属性、HTML 壳或应用配置。元数据沿用 key/value 表与原生 SEO 行为,链接复用普通 Document 的资源表及双语字段。相同链接按完整定义去重,同名元数据冲突在启动前报错。元数据按键稳定输出,保证同一结构的预览与服务一致。URL 只允许站内绝对路径与 http(s),不读取或下载地址。charset、viewport、csrf-token 属于运行时,作者不能重声明。对应手册为 ext/web/head.mq.md 与 ext/web/页头.mq.md。
|
||||
@@ -0,0 +1,274 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Marqdo 编程规范:源码即手册,手册即 SKILL,函数即工具
|
||||
description: 标准库与拓展库的叙述式开发规范,包含可以直接调用的真实示例。
|
||||
import:
|
||||
文件: lib/文件.mq.md
|
||||
---
|
||||
|
||||
库开发指南:让说明、调用和实现长在同一份源码里。
|
||||
|
||||
本文件供人和 AI 编写 Marqdo 程序、标准库、拓展库以及可执行 SKILL 时直接阅读。目标是把库文件交给一个没有读过
|
||||
完整语法手册的模型,它仍能判断何时使用、提供哪些输入、如何调用、如何消费结果,
|
||||
以及遇到失败时怎么办。完成这些任务所需的信息必须在库文件中,不依赖聊天历史、
|
||||
隐藏提示词、另一份签名清单或模型猜测。修改实现所需的最少标记也在本文就地示范。
|
||||
|
||||
这份指南本身可以执行。下方三个函数分别演示句中计算、结构化数据和可恢复文件读取;
|
||||
它们返回真实结果,不返回“已遵守规范”之类的固定通过标志。直接使用的命令为:
|
||||
|
||||
```sh
|
||||
marqdo call doc/library-development.mq.md 计算金额 单价=12 数量=3 --json
|
||||
marqdo call doc/library-development.mq.md 形成订单摘要 '商品="笔记本"' 单价=12 数量=3 --json
|
||||
marqdo call doc/library-development.mq.md 尝试读取正文 '路径="doc/library-development.mq.md"' --effects fs.read --fs-root . --json
|
||||
```
|
||||
|
||||
第一条返回 36,第二条返回商品为笔记本、数量为 3、金额为 36 的记录。
|
||||
第三条返回包含本文源码的成功结果记录。需要读写权限的工具必须给出授权命令及路径基准;
|
||||
纯计算不要求插件、网络或文件授权。读到一个工具时,读者应该能直接复制其真实命令。
|
||||
|
||||
---
|
||||
|
||||
一、先确定文件承担的任务。
|
||||
|
||||
标准库通常是一份 lib/名称.mq.md:这个单文件本身就是手册和 SKILL,直接导入或调用。
|
||||
不要为了文档另造一个 index、目录包装函数或同名模块手册。文件开头写清用途、适用范围、
|
||||
输入来源、权限、运行环境、共享数据形态和一个真实工作流;每个函数再就地说明自己的契约。
|
||||
|
||||
拓展库需要多个文件时,以 index.mq.md 为入口组织工程。入口要说明先读什么、任务在哪个
|
||||
模块、依赖怎样安装或准备、有哪些可运行流程,以及新能力应该加在哪里。
|
||||
子目录有独立职责和多个文件时,也用自己的 index.mq.md 收拢接口与开发路线;
|
||||
叶子只有一个文件时直接使用该文件,不为空目录层级继续增加入口。
|
||||
中文镜像遵守已有命名约定,并说明其与英文模块的对应关系。
|
||||
|
||||
下面只是目录组织示意,不是已经存在、可以直接调用的拓展包:
|
||||
|
||||
```text
|
||||
ext/sample/
|
||||
index.mq.md 任务导航、安装和权限、主流程、公开门面、开发路线
|
||||
core.mq.md 单一职责的纯计算;本文件自身就是手册
|
||||
parse/
|
||||
index.mq.md 解析任务入口,组合本目录的格式能力
|
||||
markdown.mq.md Markdown 叶子能力,保留可独立调用的契约
|
||||
csv.mq.md CSV 叶子能力
|
||||
examples/
|
||||
workflow.mq.md 使用公开 API 的完整业务流程
|
||||
tests/
|
||||
acceptance.mq.md 工程自有的可执行验收场景
|
||||
```
|
||||
|
||||
入口沿用公开能力进行组合,避免复制一份底层实现。索引中的路径和命令必须可用,
|
||||
还要说明输入与产物怎样跨步骤传递,而不只是列文件名。工具 schema、签名和效应由现有
|
||||
编译器、call、catalog、MLSP 从源码投影,不另建一套由作者同步维护的工具协议。
|
||||
本指南也无需安装为另一套 SKILL 包;开发者或 AI 读这份源码即可使用其中的规范与示例。
|
||||
|
||||
---
|
||||
|
||||
二、标题下面立即交代参数与返回。
|
||||
|
||||
普通网页正文、内容叶子与静态文档可以继续使用内容标题;它们没有调用契约,不能为了
|
||||
满足函数格式而插入虚假的参数或返回值表。需要执行任务的 SKILL 应把操作写入 mq.md,
|
||||
SKILL.md 只保留发现入口、适用范围和必要约束,避免两份独立维护的长命令清单。
|
||||
|
||||
每个真正可调用的函数使用函数标题。紧接标题先写参数表,再写返回表;没有参数时直接
|
||||
放返回表。表格必须位于第一条执行语句之前。正文中的普通小节使用说明段和分隔线,
|
||||
不要把“安装说明”“注意事项”等叙述标题误做成空函数。
|
||||
|
||||
参数表逐项写名称、类型、默认值和含义。含义应包含输入来源、数据形态、单位、索引基数、
|
||||
是否允许为空及必要限制,而非“运行时参数”或把参数名复述一次。返回表写实际值的类型、
|
||||
字段和含义,指出是新集合、文件路径、句柄、普通值还是可恢复结果,并说明失败出口。
|
||||
正文进一步解释这些约束的原因与处理方式,不能把关键边界埋到另一个文件才找得到。
|
||||
|
||||
新库用正文中的叙述形参,不保留旧的加号形参清单。参数表提供类型契约和说明,
|
||||
不是另一套参数声明器:名称、顺序和默认值要与正文和实际实现一致。
|
||||
有默认值的形参在正文首次声明时紧跟等号,文本默认值加完整引号;无默认值的输入
|
||||
必须由调用方提供。下面的真实函数展示完整排版,不需要先学另一份模板语法。
|
||||
|
||||
---
|
||||
|
||||
三、先把函数写成能读懂的文章,再让必要部分执行。
|
||||
|
||||
每个函数单元的叙述比例超过 50%,整份文件也保持说明充分。目的、适用条件、步骤之间
|
||||
的因果、数据含义、返回去向和失败处理都属于有用叙述。不要用重复套话、巨型契约表、
|
||||
无关背景或在文件头堆文章来掩盖某个函数仍然难读。短实现也需要说明为什么这样做。
|
||||
|
||||
检查按每个真实函数单元分别计算,契约表与说明文字属于叙述;绑定的数据表与代码围栏
|
||||
属于实现。句中粗体、返回表达式和遮蔽圆括号中的代码仍计入代码,方括号中的动作说明
|
||||
计入叙述。因此把整段代码搬进一句话,并不会把它全部变成说明文字。比例只是最低门槛,
|
||||
还应逐段检查输入来源、分支理由、失败出口与可执行示例。
|
||||
|
||||
尽量让语句成为句子的组成部分。粗体标记执行赋值、调用或表达式;单斜体标记返回。
|
||||
例如,下方计算金额函数在解释金额来源的句子中完成赋值,在交代用途的句子中返回结果。
|
||||
先读句子能够理解意图,展开其中的精确表达式又能看清实际执行的代码。
|
||||
|
||||
使用当前已支持的句中返回写法:`完成上述操作后,我们返回*结果*,供调用方继续使用。`
|
||||
其中“返回”直接引出单斜体。不要把粗体当作返回,也不要假定任意句中出现的单斜体强调
|
||||
都会结束函数。返回立即结束当前函数;同一句后面的文字只能解释,不能安排后续执行动作。
|
||||
讲解标记本身或展示尚不执行的示例时,使用行内代码或未绑定的代码围栏,避免意外执行。
|
||||
|
||||
确实需要单独成块的表格、分支和循环可以保留结构化排版。减少孤立代码的目的在于
|
||||
保留可读因果,而不是把长循环硬塞到一句话里。每个结构块前说明判断或遍历的目的,
|
||||
块内使用清楚的变量名与动作标签,块后说明产物;不要让读者靠追踪临时变量猜流程。
|
||||
|
||||
---
|
||||
|
||||
四、用遮蔽语法把意图和精确实现放在同一处。
|
||||
|
||||
方括号写“要做什么”,圆括号写实际代码。标签应解释领域动作、输入与结果之间的关系,
|
||||
例如“按单价和购买数量计算金额”“在授权根目录读取 UTF-8 正文”,而不是“执行操作”
|
||||
或原样复述宿主函数名。简单算术、取元、库调用和宿主调用都可以按需要使用这种写法。
|
||||
|
||||
下方函数会在叙述中执行赋值,赋值右侧用遮蔽表达式写出动作和实现。返回也可以直接
|
||||
包住一个有说明的表达式;以下围栏只是排版示例,不会在阅读本指南时执行文件操作:
|
||||
|
||||
```markdown
|
||||
读取阶段先**正文 = [读取授权范围内的 UTF-8 文本](文件.读文本(路径=`路径`))**,得到后续使用的内容。
|
||||
读取完成后,我们返回*正文*,供调用方继续处理。
|
||||
```
|
||||
|
||||
如果不需要中间命名,也可以用下面的直接返回替代上面整个过程。二者是两种写法,
|
||||
不是连续执行的两个读取步骤;不要为了叙述或展示再调用一次有副作用的能力。
|
||||
|
||||
```markdown
|
||||
读取阶段直接返回*[读取授权范围内的 UTF-8 文本](文件.读文本(路径=`路径`))*,把内容交给调用方。
|
||||
```
|
||||
|
||||
执行位置很重要:普通正文中的链接样式是叙述引用或导航,单靠写出一个动作标签不会
|
||||
自动执行它。需要执行的表达式应放在赋值、语句、返回等明确的执行位置;
|
||||
不要用一个没有实现的空圆括号假装功能已完成。标签不参与参数求值,也不能证明实现
|
||||
符合描述;修改标签或实现后仍要检查二者是否一致,并执行相关场景。
|
||||
|
||||
---
|
||||
|
||||
五、用表格表达结构,用模块表达职责。
|
||||
|
||||
静态记录、行列表、配置、命令和视图结构优先写成 GFM 表格。一列表达列表,
|
||||
一行多列表达记录;多行多列默认是列式数据,要表达行记录列表时把首列写成 @。
|
||||
调用产生的值先计算并命名,再在单元格中引用,不能假定表格里任意一段函数文本会执行。
|
||||
普通值用列表和记录传递;读取集合使用 access,不能把描述标签误当作集合键。
|
||||
|
||||
命令参数也作为数据写入表格:`"-p"`、`"--offline"` 等文本必须带引号;
|
||||
裸写 `-p` 会被当成表达式而不是命令选项。已计算的路径使用反引号引用变量,
|
||||
不要再拼接整段 shell 源码。需要同时被 call 与 View 使用的过程用普通函数标题,
|
||||
例如 `## main`;`# main` 是对象入口,不能假定两者具有相同的调用语义。
|
||||
整数除法会保留整数语义;计算平均值优先使用统计库的 mean,或明确采用浮点输入,
|
||||
并在非整除样例中验证结果,避免演示数据恰好整除掩盖精度问题。
|
||||
|
||||
不可变更新要保存返回的新值。少量动态键用表库的具名助手;解析与序列化才使用 JSON。
|
||||
不要用长串 json.set/json.append 来拼原本一张表就能读懂的数据,也不要为每个数字或
|
||||
单个字段创建层层转发的空壳函数。只有当一段逻辑需要解释、复用或独立验证时才提取职责。
|
||||
|
||||
网页工程从最小布局拆分开始:首页拆为导航、主体、底部,底部再拆为品牌和链接双栏,
|
||||
链接栏还可拆成文档与社区。一直拆到叶子内部能够用简单 Markdown 表达内容;
|
||||
父模块负责导入、组合与布局,叶子负责内容。使用现有 web 的文档、组件与 View 表能力,
|
||||
让结构与内容保持统一语言,避免大段原生 HTML/CSS、转义字符串和手写业务 JavaScript。
|
||||
|
||||
通用组合优先写在 mq 源码里。仅在 OS、算法或原生 ABI 边界加入小型宿主原语,
|
||||
声明实际效应与资源限制;拓展库通过公开标准库或插件接口使用能力,不直接调用 host_*。
|
||||
中英文镜像保持契约、默认值与行为一致。不要把未来规划写成当前已经可用的接口。
|
||||
|
||||
---
|
||||
|
||||
六、把运行边界和工程验收写在开发者找得到的位置。
|
||||
|
||||
实际开发也使用这些能力:读取、搜索、撰写和原子修订通过固有文件库完成;JSON、表格、
|
||||
散列和网络读取优先组合标准库。不要为已有能力再生成 Python 或 shell 程序。缺少能力时,
|
||||
把可复用的边界补成拓展插件,或者通过明确参数数组外联已有工具;决策、条件和重试仍在
|
||||
mq.md 中表达。开发与发版入口分别位于 skills/marqdo-dev 和 skills/marqdo-release,操作用
|
||||
marqdo call 执行。大段源码通过 --args-json 文件或标准输入传输,保留换行、引号和字面数据。
|
||||
外部自动化可以加 --require-ok,让失败 Result 产生非零退出码,避免继续执行依赖步骤。
|
||||
|
||||
有副作用的能力写明授权、根目录、平台、超时、资源上限以及重试与清理责任。
|
||||
返回可恢复结果时先检查其中的 ok,再读取 value 或 error;CLI 外层的 ok 只说明调用
|
||||
是否完成,不替代函数结果、HTTP 状态或子进程退出码的判断。未知副作用不能声称为纯函数。
|
||||
文件原子替换不等于多文件事务;条件写入也不等于无竞争的内核 CAS。
|
||||
|
||||
文件类示例使用明确的临时根目录,说明产物是否保留、失败是否留下临时文件、由谁清理。
|
||||
需要插件、外部服务或凭据时写明前提,验收优先使用本地可控替身,不把线上写入作为
|
||||
阅读文档的隐含步骤。维护原有库时保留既有调用语义,必要变更要说明迁移路径。
|
||||
|
||||
交付时至少检查四件事:首次读源码能否完成一次真实调用;契约和正文是否一致;
|
||||
叙述是否超过半数且解释了真实行为;正常、边界、错误场景是否返回预期结果。
|
||||
修改源码中的示例时同步执行它们;公共调用面需要兼顾 Tree 和 Bytecode。
|
||||
检查叙述比例是可读性门槛,不是功能正确性的证明,更不能代替业务与失败场景。
|
||||
|
||||
本文件可用以下命令检查。第二条是仓库内的可执行指南验收,覆盖叙述内赋值、
|
||||
默认参数、结构化返回以及可恢复读取;修改库时还应运行该库本身相关的回归。
|
||||
|
||||
```sh
|
||||
marqdo call skills/marqdo-dev/index.mq.md check 'path="doc/library-development.mq.md"' --require-ok --effects plugin --fs-root . --json
|
||||
marqdo call skills/marqdo-dev/index.mq.md test 'targets=["stdlib_tasks"]' 'filter="library_development_guide_examples_match_their_contracts"' --require-ok --effects plugin --fs-root . --json
|
||||
```
|
||||
|
||||
现有能力可直接参考 [文件库](../lib/文件.mq.md)、[表库](../lib/表.mq.md)、
|
||||
[量子工程入口](../ext/quantum/index.mq.md)和[网页工程入口](../ext/web/index.mq.md)。
|
||||
需要了解解析与语义的边界时再阅读[文档原生开发指导](design/document-native-development-guide.md)。
|
||||
以下是真实可调用的单文件示例,也是前面三个命令的实现。
|
||||
|
||||
## 计算金额
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 单价 | number | 必填 | 单件商品的金额;币种由调用方保持一致 |
|
||||
| 数量 | number | 1 | 参与乘法的购买数量;调用方按业务规则校验其范围 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 结果 | number | 单价乘以数量的金额,不含税费、折扣或币种转换 |
|
||||
|
||||
输入单价为`单价`,购买数量`数量`=1,没有指定数量时按一件计算。
|
||||
本示例只演示透明的乘法组合,不暗示商品有效、允许负数交易或具有货币精度保证;
|
||||
需要货币精度时由领域库采用整数最小货币单位,并补充其单位和范围约束。
|
||||
|
||||
为得到这笔购买的基础金额,我们先**结果 = [按单价和购买数量计算金额](单价 * 数量)**,
|
||||
后续说明仍留在同一段落,使读者无需从一条孤立赋值反推它的业务目的。
|
||||
|
||||
完成上述计算后,我们返回*结果*,调用方可以继续计算税费、折扣或生成订单摘要。
|
||||
|
||||
## 形成订单摘要
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 商品 | text | 必填 | 调用方提供的商品显示名称;此函数不查商品库 |
|
||||
| 单价 | number | 必填 | 与数量相乘的单件金额,币种与调用方约定 |
|
||||
| 数量 | number | 1 | 购买数量,默认一件;业务校验由调用方完成 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 摘要 | map | 商品、数量、金额三个字段组成的新记录 |
|
||||
|
||||
本函数接收商品名`商品`、单件金额`单价`以及购买数量`数量`=1,
|
||||
只生成供下一步展示或保存的数据,不会下单、扣款、写文件或访问外部服务。
|
||||
因此调用者可以在纯计算权限下验证完整的数据组合过程。
|
||||
|
||||
我们复用同一文件的计算能力,先**金额 = [计算本次购买的基础金额](计算金额(单价=`单价`, 数量=`数量`))**,
|
||||
避免在订单摘要中再维护一份乘法规则。接着将需要交给调用方的字段直接列成记录,
|
||||
让阅读者能逐项看到商品名称、数量和金额从哪里来,而无需解码字典构造链。
|
||||
|
||||
`摘要` =
|
||||
|
||||
| 商品 | 数量 | 金额 |
|
||||
|---|---|---|
|
||||
| `商品` | `数量` | `金额` |
|
||||
|
||||
表格中的反引号引用已经得到的值,未增加一层隐式求值。字段准备好后,我们返回*摘要*,
|
||||
调用方可以把它交给其他库继续展示或序列化;本函数不会修改传入的值。
|
||||
|
||||
## 尝试读取正文
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 路径 | text | 必填 | 授权文件根目录内的 UTF-8 文件路径;不是相对本指南的导航链接 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 读取结果 | map | ok/value/error 记录;成功的 value 是正文,失败的 error 含 code/message/operation |
|
||||
|
||||
输入文件`路径`由调用者提供,执行时需要 fs.read,路径以 --fs-root 为基准;
|
||||
省略根目录时采用被调用文件的目录。本函数复用文件库的有界读取,不能绕过根目录、
|
||||
编码检查或资源上限。此例不执行读到的代码,也不从正文推断额外的文件访问权限。
|
||||
|
||||
为了让一次读取失败仍能作为数据交给下一步,我们先**读取结果 = [在授权范围读取 UTF-8 正文并保留失败信息](文件.尝试读文本(路径=`路径`))**,
|
||||
由公开文件库统一处理已定义的可恢复失败,而不是在此复制宿主 IO 或假造成功文本。
|
||||
|
||||
读取结束后,我们返回*读取结果*,调用者先检查记录中的 ok,再使用 value 或 error。
|
||||
失败记录只说明这次操作没有成功;它不会捕获任意语言错误,也不会替调用者授予权限。
|
||||
@@ -450,4 +450,127 @@ AI 优先使用既有知识,而非反复解释和重新生成
|
||||
|
||||
如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它?
|
||||
|
||||
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
|
||||
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
|
||||
|
||||
# Marqdo 可执行知识体系:设计规范与完整范例
|
||||
|
||||
我已经基于 Marqdo 当前仓库的语法规范、`[]()` 设计、知识分层、对象模型和 EKC,整理了两份详细文档。
|
||||
|
||||
这次设计保留了你的原始理念:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
核心目标不是让 AI 更容易生成 Marqdo 代码,而是让 AI 尽可能不必重新生成已经存在的知识,转而通过编译器确定性地发现、引用、验证和执行既有知识。
|
||||
|
||||
第一份:完整架构设计规范
|
||||
|
||||
涵盖语义制品、知识引用、编译器架构、解析优先级、效应安全、版本管理、EKC 集成、Agent 复用协议和实施验收。
|
||||
|
||||
阅读设计文档
|
||||
|
||||
第二份:多文件可执行知识范例
|
||||
|
||||
以虚构书店定价为例,从原始政策文档开始,逐步构造知识定义、对象、计算能力、业务入口、AI 问答、知识复用和错误验证。
|
||||
|
||||
阅读完整示例
|
||||
|
||||
两份文档打包
|
||||
|
||||
下载 ZIP
|
||||
|
||||
## 一、这份设计最重要的三个决定
|
||||
|
||||
# Marqdo 可执行知识体系:核心设计纲领
|
||||
|
||||
**核心理念:代码即文档,文档即知识库,知识即可执行。**
|
||||
|
||||
## 1. 知识是可编译的语义制品
|
||||
|
||||
文档经过 Marqdo 编译器处理后,不只产生可执行逻辑,还应产生具有稳定身份、类型、签名、契约、依赖关系、来源和验证状态的语义制品(Semantic Artifact)。
|
||||
|
||||
知识可以表现为事实、函数、能力、约束、数据集或类型。它们无需全部被强制编码为类。
|
||||
|
||||
## 2. `[]()` 是知识使用的统一入口
|
||||
|
||||
`[描述](目标)` 保留 Markdown 的可读性。
|
||||
|
||||
- `[]` 面向人类,描述意图、意义或用途。
|
||||
- `()` 面向编译器,包含既有 Marqdo 表达式或者可解析的知识目标。
|
||||
- 描述不改变执行结果,也不能作为可信性依据。
|
||||
- 编译器负责将目标解析为确定的符号身份,并验证使用条件。
|
||||
|
||||
既支持隐藏不易阅读的代码,也支持引用已经编译的知识。
|
||||
|
||||
## 3. AI 复用知识,而不是重新解释知识
|
||||
|
||||
AI 面对新任务时,应该遵循:
|
||||
|
||||
**Discover → Resolve → Verify → Reuse → Execute → Trace**
|
||||
|
||||
当知识缺失或不适用时,才进入 ADAPT 或 CREATE 流程。
|
||||
|
||||
检索可以模糊,但最终绑定必须确定。验证必须区分程序可执行性、契约符合性和现实事实正确性。
|
||||
|
||||
## 4. 编译器是知识系统的基础
|
||||
|
||||
AST、Semantic IR、符号索引、链接关系和知识验证应当由同一套语义体系产生。
|
||||
|
||||
解释器、字节码 VM、View、EKC 和 Agent 消费统一的编译结果,而不是各自重新解析文档。
|
||||
|
||||
## 5. 最终验收标准
|
||||
|
||||
一个 AI 能够发现现有知识、确定其身份、检查适用条件、直接执行既有能力、引用结果和来源,并在知识发生变化时识别受影响的调用者。
|
||||
|
||||
只有这条链条成立,Marqdo 才真正实现知识的可执行复用。
|
||||
|
||||
## 二、示例将展示什么
|
||||
|
||||
我选择了一个具有明确规则和复用价值的业务案例,而不只是使用“李白出生年份”这样的静态事实。
|
||||
|
||||
用户购买两件单价 60 元的商品,金卡折扣为 90%,满 100 元免运费。
|
||||
|
||||
AI 要处理的业务请求
|
||||
|
||||
> 请计算这笔金卡订单的最终应付款,并解释依据。
|
||||
|
||||
传统路径
|
||||
|
||||
检索政策 → AI 阅读规则 → 重新推导计算 → 生成新代码或答案
|
||||
|
||||
Marqdo 目标路径
|
||||
|
||||
发现定价能力 → 绑定已编译函数 → 检查输入与政策 → 执行 → 引用结果
|
||||
|
||||
目标语法示意(v2.1+,不是 v2.0.0 实测)
|
||||
|
||||
```
|
||||
**应付 = [订单最终应付款](定价.计算应付金额(60, 2, "金卡"))**
|
||||
```
|
||||
|
||||
根据演示政策计算
|
||||
|
||||
# ¥108
|
||||
|
||||
这套例子进一步展示了参数和返回值、类与继承、表格、条件分支、循环、跨文档调用、自然语言遮蔽,以及知识来源改变时的影响分析。
|
||||
|
||||
## 三、与当前版本的兼容边界
|
||||
|
||||
我特别保留了一个重要区分:设计目标不等于当前已经实现的功能。
|
||||
|
||||
根据这次读取的仓库内容,v2.0.0 已支持本地表达式遮蔽、对象、方法、控制流、表格集合、导入以及现有 EKC 基础;但无实例类函数调用、跨文档知识自动解析、完整 LinkInfo 和语义制品绑定仍需要进一步开发。
|
||||
|
||||
因此示例文档明确标注了目标语法和现有兼容写法,没有将尚未验证的代码描述为已经跑通。
|
||||
|
||||
## 四、我的主要架构建议
|
||||
|
||||
我认为接下来的开发不应该从 `[]()` 的外观继续扩展,而应该先实现:
|
||||
|
||||
统一符号索引 → 稳定知识身份 → 引用绑定 → 契约验证 → EKC 复用。
|
||||
|
||||
还有一点值得特别强调:我不赞成为了建立知识系统,再单独实现一个与 Marqdo 解释器并列的“知识编译器”。那样会重新制造你希望消除的表示碎片。
|
||||
|
||||
更合适的架构是让现有 Marqdo 编译管线产出统一的语义中间表示,然后由运行时、View、EKC 和 Agent 各自消费。
|
||||
|
||||
这意味着 Marqdo 的知识体系不是一个外挂的 RAG 框架,而是语言本身的语义能力。
|
||||
|
||||
我认为这才是整个设计中最值得投入资源,也最有可能形成独立研究贡献的部分。
|
||||
@@ -0,0 +1,374 @@
|
||||
请你重新阅读marqdo的官方库,掌握marqdo的最新进度。在我对marqdo项目的仔细审视之下我发现有一点没有闭环,我终于找到了,考虑现在智能体开发最常用的SKILL,这是一个markdown文件写明了智能体该干什么,我想要更推荐一步,因为marqdo使用markdown语法,支持叙述和代码相互混合,这就使得marqdo满足这样一个条件,当分章节的SKILL撰写下来,只要经过调整就能成为一份marqdo代码其中包含若干函数,我打算开发新的CLI命令marqdo > 函数名 函数参数或者marqdo call 函数名 函数参数 此时SKILL的不同章节就变成了不同的函数,智能体就真正的成为了将知识复现的作用,这让代码即文档、文档即知识,知识即可执行推进了一步变成了知识即工具,真正发挥了marqdo的优势,同样这样的执行还以为着智能体能够自行改进SKILL并接受确定的问题后修改而不会出错,这让自我进化的智能体成为了具备理论支撑和清晰边界的可能
|
||||
|
||||
# Marqdo 从“可执行知识”走向“知识即工具”:最新仓库审查与架构建议
|
||||
|
||||
我认为你这次找到了 Marqdo 一个非常重要、而且比单纯增加 `marqdo call` 命令更深层的突破口。
|
||||
|
||||
你实际上提出了一个新的统一关系:
|
||||
|
||||
> SKILL 是人和 AI 都能阅读的操作知识;Marqdo 可以让其中具有确定性执行语义的章节,直接成为可调用的工具。
|
||||
|
||||
这样,Agent 的职责就有机会从“阅读说明、理解步骤、临时生成实现”,转向“定位已有能力、填入参数、执行和验证结果”。
|
||||
|
||||
这与 Marqdo 原来的三句话是连续的,不需要推翻原来的定位:
|
||||
|
||||
代码即文档 → 文档即知识库 → 知识即可执行 → 知识即可作为工具使用。
|
||||
|
||||
不过我建议把“知识即工具”视为可执行知识的对外使用形态,而不是再创造一套与语言、知识库平行的 Skill 运行系统。
|
||||
|
||||
## 一、重新检查仓库后的最新情况
|
||||
|
||||
本次核对的是 [cflmy/marqdo](https://github.com/cflmy/marqdo?utm_source=chatgpt.com) 的 `main` 分支,HEAD 为 `4018e992`,`Cargo.toml` 版本为 2.1.5。最近的 v2.1.5 版本记录日期是 2026 年 10 月 27 日。
|
||||
|
||||
与我们之前讨论 v2.0.0 时相比,项目已经完成了不少与你的构想直接相关的基础建设。
|
||||
|
||||
| 相关能力 | 最新仓库证据 | 判断 |
|
||||
| --------------------- | ---------------------------------------------------------------- | -------- |
|
||||
| 跨文档确定性函数绑定 | `BoundCall`、`SymbolId`,Tree/Bytecode 双后端测试 | 已有核心基础 |
|
||||
| 已编译知识的执行复用 | MLSP `artifact.bind`、`artifact.execute`、`artifact.reuse_execute` | 已有子集 |
|
||||
| Agent 复用已有函数 | `agent_eng_bind_execute`、发布门禁 | 已有子集 |
|
||||
| 指定函数执行 | `marqdo run --call-lib-path`、JSON 参数、隔离 worker | 已有底层入口 |
|
||||
| 智能体工具规范 | `ToolSpecV1`、效应分类、权限检查与恢复设计 | 已有框架基础 |
|
||||
| 章节式 SKILL 自动成为 CLI 工具 | 目前没有独立的 `marqdo call` 或 Skill 编译命令 | 待开发 |
|
||||
| SKILL 自修改、自动测试和受控发布 | 已有局部修改、验证与沙盒组件 | 尚未形成完整闭环 |
|
||||
|
||||
因此,现在不是重新开发一个 Skill 执行器,而是将已存在的 Marqdo 函数、知识制品、工具协议和 Agent 机制统一起来。
|
||||
|
||||
还有一个与你的新构想直接相关的问题值得先修复:
|
||||
|
||||
最新官方 `skills/marqdo/SKILL.md` 的核心语法说明,与仓库中的现行解析器、v0.3 语法规范和可执行测试存在冲突。
|
||||
|
||||
目前解析器与测试使用的是:
|
||||
|
||||
- `**…**`:代码、赋值、调用等语句;
|
||||
- `*…*`:返回值。
|
||||
|
||||
但官方 Skill 顶部却把两者反过来描述。这不是小的文档笔误:如果 Agent 按照错误规则自我修改 Skill,就可能产生与实际运行时不一致的程序。
|
||||
|
||||
这个真实存在的不一致,恰好证明了你所说的闭环为什么重要——SKILL 不能仅靠自然语言说明自己的正确性,它需要由语言编译器和实际测试提供独立验证。
|
||||
|
||||
## 二、你真正提出的是一种新的 Skill 体系
|
||||
|
||||
我建议把它暂时命名为 Executable Skill(可执行技能)。
|
||||
|
||||
它不应被理解为“给 Markdown Skill 增加一点代码”,而应当满足一个更严格的定义:
|
||||
|
||||
> Executable Skill 是一份以 Markdown 为人类可读接口、以 Marqdo 函数为确定性执行单元、以编译后的语义制品为工具身份、能够由 Agent 发现、调用、验证和改进的技能文档。
|
||||
|
||||
传统 Skill 与你的目标之间,存在一个非常重要的区别。
|
||||
|
||||
| 维度 | 普通 Markdown Skill | Marqdo Executable Skill |
|
||||
| ---- | ----------------------- | ----------------------- |
|
||||
| 技能说明 | 自然语言 | 自然语言 |
|
||||
| 操作步骤 | Agent 阅读后自行实施 | 可以绑定已有 Marqdo 函数 |
|
||||
| 函数接口 | 通常需要额外编写工具代码 | 从 `.mq.md` 的函数和契约生成 |
|
||||
| 执行 | 依赖 Agent 选择工具、生成代码或操作软件 | 对已实现的步骤直接执行 |
|
||||
| 输出验证 | 往往需要单独建立 | 可连接编译器、契约和测试 |
|
||||
| 改进 | 编辑说明或脚本 | 编辑同源的知识与实现,验证后发布 |
|
||||
| 可追踪性 | 主要依赖工具日志 | 可关联 SymbolId、源码、版本和执行结果 |
|
||||
|
||||
但不是每个 Skill 章节都应该自动变成可执行函数。
|
||||
|
||||
比如“适用场景”“注意事项”“禁止操作”是知识或约束;“检查订单”“生成报价”“汇总报告”才可能成为可调用能力。编译器应区分文档章节与可执行章节,不能把所有二级标题不加判断地暴露成工具。
|
||||
|
||||
### 这实际上使 Agent 的结构发生变化
|
||||
|
||||
SKILL.md
|
||||
|
||||
目标 · 流程 · 函数 · 契约 · 示例 · 约束
|
||||
|
||||
Marqdo Skill Compiler
|
||||
|
||||
章节解析 · 符号绑定 · 类型检查 · 效应分析
|
||||
|
||||
Knowledge View
|
||||
|
||||
Agent 阅读技能与限制
|
||||
|
||||
Tool Registry
|
||||
|
||||
Agent 调用已编译函数
|
||||
|
||||
Agent:选择、组合、执行、观察与改进
|
||||
|
||||
由语言运行时执行确定性部分,由模型处理非确定性判断
|
||||
|
||||
特别值得注意的是:这不仅是执行接口的统一,还是知识交付接口的统一。
|
||||
|
||||
同一份 Skill 能够投影成可读说明、CLI 函数、Agent Tool Schema、MCP 工具描述,以及知识库中的能力节点。实现这些投影的系统仍是同一个 Marqdo 编译器。
|
||||
|
||||
## 三、CLI 应采用 `marqdo call`,不要采用 `marqdo >`
|
||||
|
||||
你提出了两个命令形式:
|
||||
|
||||
```
|
||||
marqdo > 函数名 函数参数
|
||||
marqdo call 函数名 函数参数
|
||||
```
|
||||
|
||||
我明确建议采用第二种。
|
||||
|
||||
原因是 `>` 在 Bash、PowerShell、CMD 等 Shell 中已经具有输出重定向语义。`marqdo > xxx` 会被 Shell 先行解释,无法可靠地作为传递给 Marqdo 的函数调用语法。
|
||||
|
||||
推荐设计为:
|
||||
|
||||
```
|
||||
# 按函数名调用
|
||||
marqdo call "订单计算.商品小计" \
|
||||
--skill ./skills/order-calculator \
|
||||
--arg 单价=30 \
|
||||
--arg 数量=2
|
||||
|
||||
# 结构化调用,供 Agent 使用
|
||||
marqdo call "订单计算.商品小计" \
|
||||
--skill ./skills/order-calculator \
|
||||
--args-json inputs.json \
|
||||
--output json \
|
||||
--policy pure
|
||||
```
|
||||
|
||||
上述是建议新增的 CLI 接口,不是 v2.1.5 已支持的命令。
|
||||
|
||||
我还建议在 CLI 层保留一个便利别名:`marqdo skill call`。它与 `marqdo call` 进入同一个 dispatcher,不应分别实现两套调用逻辑。
|
||||
|
||||
### 最小必要的 CLI 能力
|
||||
|
||||
| 命令 | 作用 |
|
||||
| ---------------------------- | ----------------------- |
|
||||
| `marqdo skill inspect PATH` | 解析 Skill 文档、章节、可调用函数和依赖 |
|
||||
| `marqdo skill list PATH` | 列出对 Agent 暴露的工具 |
|
||||
| `marqdo skill check PATH` | 检查语法、绑定、签名、效应和工具导出规则 |
|
||||
| `marqdo call TARGET` | 调用指定 Marqdo 函数并返回结果 |
|
||||
| `marqdo skill test PATH` | 执行 Skill 的测试与契约检查 |
|
||||
| `marqdo skill export PATH` | 生成通用工具描述或 MCP 暴露接口 |
|
||||
| `marqdo skill trial PATH` | 对修改后的候选版本进行隔离验证 |
|
||||
| `marqdo skill promote PATH` | 在门禁通过后发布新版本 |
|
||||
| `marqdo skill rollback PATH` | 恢复到指定已接受版本 |
|
||||
|
||||
不过不建议一次性实现这九项命令。最小可用产品只需要 `inspect`、`call`、`check`、`test` 四项,版本发布与改进机制可以随后补齐。
|
||||
|
||||
最重要的技术决策是:
|
||||
|
||||
`marqdo call` 必须调用现有编译器绑定的函数,不得重新用字符串搜索源码、猜测章节位置再执行。
|
||||
|
||||
当前 [src/mlsp.rs](https://github.com/cflmy/marqdo/blob/main/src/mlsp.rs?utm_source=chatgpt.com) 已有 `artifact.bind` 与 `artifact.execute`,能够检查制品指纹、依赖闭包、来源摘要和效应策略。新的 CLI 应复用相同的应用服务和语义校验,而不是通过进程内调用 MLSP JSON 接口制造另一层重复协议。
|
||||
|
||||
还有一个现有实现细节:`marqdo run --call-lib-path` 已支持隔离 worker 通过 JSON 参数调用函数,但当前 `src/lib.rs` 的这个入口只在树遍历分支中处理,Bytecode 分支仍按普通程序入口执行。新的公开 `call` 命令需要补齐这一差异,或者明确在第一版只支持 Tree backend,不能静默忽略所选后端。
|
||||
|
||||
## 四、完整示例:让一份 Skill 同时成为文档、知识和工具
|
||||
|
||||
我建议第一版尽量保持作者体验简单:人只维护一份 Markdown 源文件,编译器自动生成工具描述、函数索引和知识制品。
|
||||
|
||||
例如,我们建立一个订单计算 Skill。
|
||||
|
||||
下面是目标设计示例。其中 `runtime` 和 `tools` 是我建议为 Skill 编译增加的元数据约定,目前不能将这份 `SKILL.md` 直接交给 v2.1.5 的 CLI,期待自动注册工具。
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
name: order-calculator
|
||||
description: 订单价格计算,包括商品小计和含税金额
|
||||
runtime: marqdo
|
||||
tools:
|
||||
- 订单计算.商品小计
|
||||
- 订单计算.含税金额
|
||||
---
|
||||
|
||||
# 订单计算
|
||||
|
||||
这份技能用于计算订单金额。
|
||||
|
||||
所有金额使用同一货币单位。税率使用小数表示,
|
||||
例如 0.10 表示 10%。
|
||||
|
||||
## 商品小计
|
||||
|
||||
给定商品单价`单价`和购买数量`数量`,
|
||||
计算未税商品小计。
|
||||
|
||||
*[商品小计](单价 * 数量)*
|
||||
|
||||
## 含税金额
|
||||
|
||||
给定商品单价`单价`、购买数量`数量`
|
||||
和适用税率`税率`,计算含税金额。
|
||||
|
||||
**小计 = [计算商品小计](订单计算.商品小计(单价=单价, 数量=数量))**
|
||||
|
||||
*[最终含税金额](小计 * (1 + 税率))*
|
||||
|
||||
```
|
||||
|
||||
这里的计算是演示规则。正式业务技能还需要校验数量范围、金额精度、货币单位、税率适用条件与舍入规则;这些不能由函数名字自动推断为正确。
|
||||
|
||||
### 这份 Skill 会产生三种投影
|
||||
|
||||
给人阅读: 它是一份正常的 Markdown 文档。读者能理解每个步骤的目的,以及所需输入和返回值。
|
||||
|
||||
给 Marqdo 编译器: 两个 `##` 单元构成可解析的函数;第二个函数可以确定性地调用第一个函数;符号索引能够记录它们的依赖关系。
|
||||
|
||||
给 Agent 使用: 编译器输出两个工具的结构化描述。Agent 不需要重新生成乘法计算程序,只需选择工具并提供参数。
|
||||
|
||||
例如,编译后的工具描述可以是:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "order-calculator::订单计算.商品小计",
|
||||
"description": "计算未税商品小计",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"单价": {"type": "number"},
|
||||
"数量": {"type": "number"}
|
||||
},
|
||||
"required": ["单价", "数量"]
|
||||
},
|
||||
"output_schema": {
|
||||
"type": "number"
|
||||
},
|
||||
"effect": "pure"
|
||||
}
|
||||
```
|
||||
|
||||
但这个 Schema 必须由明确的类型契约和编译器检查生成。若源文件没有足够的类型信息,应标记为未知或要求补全,不能因为变量参加了乘法就无条件断言它一定是 `number`。
|
||||
|
||||
需要强调:不是 `##` 标题自动等于一个公开工具。 `##` 让章节具备 Marqdo 函数的结构,`tools` 则声明哪些函数允许对外暴露。这样才能避免“安全说明”一类章节被意外注册成工具,也避免内部辅助函数被 Agent 随意调用。
|
||||
|
||||
### 为什么采用显式的 `runtime: marqdo`?
|
||||
|
||||
因为普通 Skill 的 Markdown 本来就可能包含 `**加粗内容**`、编号列表、代码块和二级标题。这些在现有 Marqdo 中可能具有执行语义。
|
||||
|
||||
如果直接把所有 `SKILL.md` 当成 `.mq.md` 执行,很可能发生严重的语义误读。
|
||||
|
||||
所以我建议:
|
||||
|
||||
- 未明确声明 Marqdo 运行时的 `SKILL.md`,仍然是普通 Markdown 文档。
|
||||
- 明确声明 `runtime: marqdo` 的 Skill 才进入 Marqdo 编译流程。
|
||||
- 内嵌示例代码块不应因展示而执行。
|
||||
- 编辑器应对具有执行意义的 Markdown 标记提供可视化提示。
|
||||
- 导出的工具必须经过独立检查和授权。
|
||||
|
||||
未来还可以支持从已有普通 Skill 中自动提取候选函数,但那应当是生成可审阅的转换补丁,而不是默认把自然语言步骤当成已经实现的代码。
|
||||
|
||||
## 五、这次最有价值的部分:自我改进的 Skill
|
||||
|
||||
你提出的第二层意义,我认为甚至比 `marqdo call` 更值得研究。
|
||||
|
||||
传统 Agent 修改一个 Skill 时,常见问题是:它修改了一段说明或脚本,却无法可靠判断其他步骤是否受到影响。
|
||||
|
||||
Marqdo 已经具备一些适合解决这个问题的基础,例如 `SymbolId`、依赖闭包、`artifact.patch`、`artifact.verify` 和知识影响分析。
|
||||
|
||||
但是,不能由此推出“智能体修改 Skill 就不会出错”。
|
||||
|
||||
更精确的目标是:智能体可以提出改进,系统能够判定一组明确、可测试的性质是否被保持,并且只有通过门禁的版本才有资格替换原有 Skill。
|
||||
|
||||
我建议采用以下演化协议:
|
||||
|
||||
已发布 Skill v1
|
||||
|
||||
现有稳定版本与完整依赖
|
||||
|
||||
1\. 发现确定的问题
|
||||
|
||||
失败测试、诊断、复现步骤或用户提出的明确修改要求
|
||||
|
||||
2\. AI 生成局部修改候选
|
||||
|
||||
只修改获准的章节或函数,记录版本与修改意图
|
||||
|
||||
3\. 编译与静态验证
|
||||
|
||||
语法、符号、参数、返回类型、效应、依赖关系
|
||||
|
||||
4\. 隔离测试与回归验证
|
||||
|
||||
目标问题修复、历史行为保持、异常输入、性能与权限边界
|
||||
|
||||
5\. 发布门禁
|
||||
|
||||
仅当策略允许且必要验证通过时晋升新版本;否则保留旧版本
|
||||
|
||||
Skill v2 · 已接受版本
|
||||
|
||||
可追溯、可回滚、后续调用绑定到明确版本
|
||||
|
||||
### 举一个真正的自我改进案例
|
||||
|
||||
原 Skill 中存在:
|
||||
|
||||
```
|
||||
## 商品小计
|
||||
|
||||
商品单价`单价`,购买数量`数量`。
|
||||
|
||||
*[小计](单价 * 数量)*
|
||||
```
|
||||
|
||||
现在发现一个确定的问题:输入 `数量=-1` 时,函数返回负数,但业务要求数量必须大于零。
|
||||
|
||||
Agent 不应该只是把说明修改成“数量必须大于零”。这不会改变执行行为。
|
||||
|
||||
它应当在候选版本中增加可执行的校验逻辑,并补充至少三个测试:
|
||||
|
||||
| 测试 | 输入 | 期望 |
|
||||
| ---- | ----------- | ------------- |
|
||||
| 正常订单 | 单价 30,数量 2 | 返回 60 |
|
||||
| 非法数量 | 单价 30,数量 -1 | 返回结构化参数错误 |
|
||||
| 边界数量 | 单价 30,数量 0 | 根据业务契约决定接受或拒绝 |
|
||||
|
||||
如果 Marqdo 尚不具备合适的语言级错误返回或异常处理方式,这个案例还会暴露一个语言能力缺口:需要一种由 Marqdo 程序自身构造、传递和处理错误的机制,而不是只能依赖 Rust 宿主报错。
|
||||
|
||||
这与此前我们讨论的通用语言能力重构是直接关联的。
|
||||
|
||||
### 自我进化的边界必须比普通代码修改更严格
|
||||
|
||||
我建议把以下约束固定下来:
|
||||
|
||||
1. 修改不能自动扩大权限。 原 Skill 只有纯计算权限,新版本不能因为 Agent 自己添加网络或文件操作就获得这些权限。
|
||||
2. 候选版不能直接覆盖运行中的正式版本。 需要隔离工作区、原子发布和固定引用版本。
|
||||
3. 必须证明目标问题被修复。 不允许通过删除测试、放宽断言或隐藏失败来宣称成功。
|
||||
4. 测试通过不是绝对正确的证明。 未覆盖的业务情况、外部事实和依赖服务仍可能出错。
|
||||
5. 高风险修改需要更严格的发布决策。 尤其是支付、外部写入、删除、凭证和安全策略变更,不能由被修改的 Skill 自己批准。
|
||||
|
||||
最新仓库的 `artifact.patch` 已经提供基于摘要的修改和有限回滚,但它还不是完整的候选版本事务与测试后晋升系统。现有 `HostCaps` 的默认值也允许文件写入、执行、网络和插件,因此新 `call` 的安全默认值应当收紧,不能简单继承普通本地运行的全部宿主权限。
|
||||
|
||||
这就是“有界自我进化”的含义:不保证 Agent 永不犯错,而是让它能够在可验证、可回滚、可限制权限的范围内持续改进。
|
||||
|
||||
## 六、我建议如何安排开发
|
||||
|
||||
| 阶段 | 目标 | 关键验收 |
|
||||
| ---------------- | ---------------------------------------- | ------------------------ |
|
||||
| S0 · Skill 语义一致性 | 修复官方 Skill 与解析器的标记冲突,建立 Skill 语法同步测试 | Skill 记载的每条核心语法都有可运行金样例 |
|
||||
| S1 · 函数调用 CLI | `marqdo call` 调用已绑定的普通函数、类函数和跨文档函数 | JSON 参数正确绑定;错误路径和双后端行为明确 |
|
||||
| S2 · Skill 编译 | 对显式启用的 `SKILL.md` 解析章节和可执行函数 | 自动产生 SymbolId、签名、依赖、导出清单 |
|
||||
| S3 · 知识即工具 | 将公开函数编译为 ToolSpec,并接入现有 Agent dispatcher | Agent 不重新生成实现即可调用并取得结果 |
|
||||
| S4 · Skill 测试 | 增加 `skill check/test`、负例、效应门禁和回归测试 | 未通过验证的 Skill 不得自动发布 |
|
||||
| S5 · Skill 演化 | 实现候选修改、隔离验证、影响分析、版本晋升与回滚 | 修改失败不影响已发布版本,权限不能自行扩大 |
|
||||
|
||||
这里还需要一项对你的研究目标尤其重要的对照实验。
|
||||
|
||||
让相同模型分别使用普通 Markdown Skill、Markdown Skill 加外部脚本工具、以及 Marqdo Executable Skill 完成相同的一组任务。分别测量正确率、模型需要重新生成的代码量、工具调用参数错误、修改后的回归失败率、token 消耗和完成时间。
|
||||
|
||||
只有与“Markdown + 现有工具调用”进行公平对照,才能证明 Marqdo 的优势来自文档、程序与知识的统一,而不只是因为它额外提供了一个执行器。
|
||||
|
||||
## 七、我对这项构想的最终评价
|
||||
|
||||
我认为这次构想具有三个非常值得肯定的性质。
|
||||
|
||||
第一,它有明确的语言基础。`#`、`##`、自然语言叙述、函数参数、`[]()`、契约表和跨文档符号绑定并不是为了 Skill 重新创造的。Skill 可以成为现有语言的一种应用形态。
|
||||
|
||||
第二,它有真实的工程基础。当前 Marqdo 已经具备部分确定性绑定、制品验证、Agent 复用与隔离运行能力。你需要做的是将这些能力收敛到统一的公开接口,而不是重新实现一套 Agent 框架。
|
||||
|
||||
第三,它能够引出一个更有研究价值的问题:自然语言描述的操作知识,如何逐步转化为可调用、可检查、可维护,并可由 Agent 在受限条件下自行改进的程序制品?
|
||||
|
||||
但是,“SKILL 章节即函数”本身还不足以证明新的编程范式。Markdown 章节映射函数,与文学编程、文档驱动工作流及现有工具包装有明显的共同点。
|
||||
|
||||
更有价值的是把三个原本需要单独维护的对象——Skill 说明、函数实现、Agent Tool Schema——统一为一个可编译的源事实,并展示这种统一确实降低了错误、维护成本和重复生成成本。
|
||||
|
||||
我建议为 Marqdo 保留原来的核心理念,并将这一阶段的技术方向明确为:
|
||||
|
||||
> 知识即工具(Knowledge as Tool):将可执行知识直接编译为 Agent 能够发现、调用和验证的工具,并允许智能体在明确的语义、测试和权限边界内持续改进这些知识。
|
||||
|
||||
这可能是 Marqdo 从“AI 可以使用的编程语言”,进一步走向“AI 能够使用并维护的可执行知识体系”的关键一步。
|
||||
|
||||
备注,这里实际上有一点叙述错误,marqdo支持mq.md文件,所以最好针对SKILL也是SKILL.mq.md这样会比较统一。
|
||||
@@ -0,0 +1,249 @@
|
||||
SKILL的名称应该是.mq.md有一点必须提及,SKILL其实命名不一定必须得是SKILL,平常的一个marqdo文件也可以是一份skill这里的设计太复杂了没有抽离出来核心本质,你看对于一个平常的marqdo文件,完全也可以和SKILL一样,这都是没有区别的,所谓的知识即工具作为高度抽象本质就是带参数调用函数,所以你的inspect等等命令其实完全可以对传统的marqdo也生效而不是非要绑定SKILL对吧,而且这样处理还有好处是方面智能体做单元测试,单个函数是否可以带参数直接运行,换句话说,你仔细思考就会发现这些好处是marqdo的设计哲学在增加一点点call自然派生的优势,所以不需要繁复的设计
|
||||
|
||||
你说得对。这次我认为你抓住了真正的核心,而且我的上一版设计确实把一个本来很自然的语言能力复杂化了。
|
||||
|
||||
Marqdo 根本不需要引入一种叫作 Executable Skill 的新概念,也不需要专门建立 Skill 编译器。
|
||||
|
||||
因为在 Marqdo 的设计哲学下:
|
||||
|
||||
> 一个 `.mq.md` 文件本身就是文档、知识与程序。只要允许从外部直接调用其中的函数,它自然也就能够成为 Skill。
|
||||
|
||||
这不是为 Skill 开发一套新系统,而是为 Marqdo 补齐一个非常基础的语言使用入口。
|
||||
|
||||
## 一、真正缺少的只有一件事:函数级执行入口
|
||||
|
||||
Marqdo 当前已经支持函数定义、参数、返回值、模块引用,以及确定性符号绑定。
|
||||
|
||||
但是日常使用时,我们往往仍然站在“运行整个文件”的角度:
|
||||
|
||||
```
|
||||
marqdo run example.mq.md
|
||||
```
|
||||
|
||||
你现在提出的是:
|
||||
|
||||
```
|
||||
marqdo call example.mq.md 函数名 参数
|
||||
```
|
||||
|
||||
这实际上意味着:
|
||||
|
||||
Marqdo 的最小可执行单位,从文件进一步扩展为文件中的任意可调用函数。
|
||||
|
||||
而这一点会自然派生大量优势。
|
||||
|
||||
普通 `.mq.md` 文件
|
||||
|
||||
自然语言叙述 + 函数 + 参数 + 返回值
|
||||
|
||||
marqdo call
|
||||
|
||||
指定函数 + 绑定参数 + 直接执行
|
||||
|
||||
知识复用
|
||||
|
||||
调用已存在的实现
|
||||
|
||||
Agent Skill
|
||||
|
||||
直接暴露函数为工具
|
||||
|
||||
单元测试
|
||||
|
||||
逐个函数验证结果
|
||||
|
||||
自我改进
|
||||
|
||||
修改函数并重新测试
|
||||
|
||||
这里不存在四套实现,只有一个底层能力的四种使用方式。
|
||||
|
||||
## 二、一个普通的 Marqdo 文件就足够了
|
||||
|
||||
比如,文件 `calculator.mq.md`:
|
||||
|
||||
```
|
||||
# 计算器
|
||||
|
||||
这是一个普通的 Marqdo 文档。
|
||||
|
||||
其中包含一些可以复用的数学计算知识。
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
|
||||
## 乘法
|
||||
|
||||
计算两个数字`a`和`b`的积。
|
||||
|
||||
*[计算结果](a * b)*
|
||||
```
|
||||
|
||||
它既是可阅读的文档,也包含两个函数。
|
||||
|
||||
现在只需要支持:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```
|
||||
5
|
||||
```
|
||||
|
||||
再比如:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.乘法 a=4 b=6
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```
|
||||
24
|
||||
```
|
||||
|
||||
以上 `marqdo call` 是拟新增的命令形式;函数示例遵循当前 `*…*` 返回、`[]()` 遮蔽的语义。
|
||||
|
||||
这时候,一个 Agent 只要能够读取这个 `.mq.md` 文档,就可以理解函数的用途;只要能够调用 Marqdo CLI,就能执行其中的能力。
|
||||
|
||||
它根本不需要关心这个文件是不是 Skill,也不需要一份特殊的 `SKILL.md`。
|
||||
|
||||
如果 Agent 把它当成 Skill 阅读和使用,它就是 Skill;如果开发者把它当成程序库调用,它就是程序库;如果研究者把它作为知识库中的一部分,它就是可执行知识。
|
||||
|
||||
文件的身份没有变化,变化的是使用方式。
|
||||
|
||||
## 三、这项能力会自然解决三个问题
|
||||
|
||||
### 1. 让知识成为工具
|
||||
|
||||
传统 Skill:
|
||||
|
||||
Agent 阅读操作说明,决定如何完成任务。
|
||||
|
||||
Marqdo:
|
||||
|
||||
Agent 阅读函数说明,找到适合的函数,传入参数,直接执行。
|
||||
|
||||
这就将原来的:
|
||||
|
||||
知识 → Agent 理解 → 重新实现 → 执行
|
||||
|
||||
缩短为:
|
||||
|
||||
知识 → 函数定位 → 参数调用 → 执行
|
||||
|
||||
但模型仍然需要负责判断应该调用哪个函数、传入哪些参数。确定性的是被调用函数的语言语义,而不是整个 Agent 决策过程。
|
||||
|
||||
### 2. 让单元测试成为语言的天然能力
|
||||
|
||||
我非常赞同你提到的单元测试价值。
|
||||
|
||||
有了 `marqdo call`,可以直接测试:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
# 期望 5
|
||||
|
||||
marqdo call calculator.mq.md 计算器.加法 a=-2 b=3
|
||||
# 期望 1
|
||||
|
||||
marqdo call calculator.mq.md 计算器.乘法 a=0 b=100
|
||||
# 期望 0
|
||||
```
|
||||
|
||||
不必为了测试一个函数,再创建一个 `# main`,再编写调用、打印和结果检查的包装程序。
|
||||
|
||||
未来即使增加 `marqdo test`,底层仍然可以复用同一个函数调用接口。
|
||||
|
||||
### 3. 让 Agent 可以针对知识进行局部改进
|
||||
|
||||
这是你提出的最有意义的延伸。
|
||||
|
||||
假设一个 Agent 发现 `计算器.乘法` 对某类输入存在错误。
|
||||
|
||||
它可以:
|
||||
|
||||
1. 阅读相应函数及其上下文。
|
||||
2. 修改这个 `.mq.md` 文件中的函数实现。
|
||||
3. 直接用 `marqdo call` 传入错误输入验证。
|
||||
4. 再运行该函数的历史测试。
|
||||
5. 如果检查通过,就提交候选修改;否则保留原有实现。
|
||||
|
||||
这使得 Agent 的改进对象不再仅仅是自然语言提示词,而是有明确输入、输出和可执行语义的知识单元。
|
||||
|
||||
当然,测试不能证明函数在所有输入上都正确;正式发布和权限控制仍需要遵循已有的项目验证机制。但不需要为此创造一套 Skill 专属的演化协议。
|
||||
|
||||
## 四、真正的 CLI 设计可以非常简单
|
||||
|
||||
我建议第一阶段只做一个命令:
|
||||
|
||||
```
|
||||
marqdo call <文件> <函数> [具名参数...]
|
||||
```
|
||||
|
||||
比如:
|
||||
|
||||
```
|
||||
marqdo call book.mq.md 订单.计算总价 单价=30 数量=2
|
||||
```
|
||||
|
||||
它只需要完成五件事:
|
||||
|
||||
| 步骤 | 职责 |
|
||||
| -- | -------------------- |
|
||||
| 1 | 加载指定 `.mq.md` 文件及其导入 |
|
||||
| 2 | 解析并唯一定位目标函数 |
|
||||
| 3 | 根据现有函数签名绑定、校验参数 |
|
||||
| 4 | 使用现有运行时执行该函数 |
|
||||
| 5 | 返回函数结果和结构化错误 |
|
||||
|
||||
额外提供一个 `--json` 输出选项就足够方便 Agent 调用。
|
||||
|
||||
如果未来需要 `marqdo inspect`,它也应该针对任何 `.mq.md` 文件,列出其中函数、参数和文档描述,而非限定 Skill。
|
||||
|
||||
此外,当前仓库已经有 `--call-lib-path` 和 `artifact.execute` 的相关基础,因此实现时应尽量复用现有函数定位与执行机制,而不是重复开发解释器。
|
||||
|
||||
唯一值得坚持的边界是:外部调用仍必须经过现有权限检查,不能因为新增了 `call` 就默认允许 Agent 对任意函数执行文件删除、网络写入等操作。
|
||||
|
||||
## 五、我认为你的设计哲学现在更加清晰了
|
||||
|
||||
你原来的理念:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
实际上已经足够完整。
|
||||
|
||||
“知识即工具”不是额外的设计理念,而是“知识即可执行”在函数级调用能力成熟后自然出现的结果。
|
||||
|
||||
进一步看,这件事还有一个很漂亮的对称性:
|
||||
|
||||
| 参与者 | 对同一个 `.mq.md` 的使用方式 |
|
||||
| ---------- | ------------------- |
|
||||
| 人类 | 阅读文档、理解知识 |
|
||||
| 编译器 | 解析并验证函数 |
|
||||
| 开发者 | 调用函数、组合程序 |
|
||||
| Agent | 发现知识、调用工具 |
|
||||
| 测试系统 | 输入参数、检查结果 |
|
||||
| 维护者或 Agent | 修改实现、验证改进 |
|
||||
|
||||
这些角色并没有要求作者维护六份不同的东西。
|
||||
|
||||
同一份文件,同一套语义,同一个函数调用接口。
|
||||
|
||||
这也恰恰是我认为 Marqdo 相比传统“Markdown 文档 + 外部工具”组合最值得证明的优势:知识描述与执行实现共址,而且能够直接由语言工具链消费,避免维护重复的工具包装和操作说明。
|
||||
|
||||
所以,我现在的建议与上一轮不同:
|
||||
|
||||
不要开发 Executable Skill 系统。不要设计 Skill 专属语法。不要引入新的 Skill 注册、编译和执行机制。
|
||||
|
||||
先完成 `marqdo call`,使普通 `.mq.md` 中的可调用函数都能被精确定位、传参执行,并用现有语义系统验证。
|
||||
|
||||
这是一个相对很小的接口变化,却可能自然打通 Marqdo 的编程、知识复用、Agent 工具调用和函数级测试四个场景。
|
||||
|
||||
我认为这才是你所说的:让 Marqdo 自己的设计哲学发挥作用,而不是不断增加外部框架来证明它的价值。
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: 作者对于marqdo的价值认识
|
||||
author: cflmy
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
诚实的说,作者其实一直都很纠结说marqdo是否具有存在的必要,不过在逐渐的开发和了解中,marqdo
|
||||
是有价值的,我此时此刻确信这一点。
|
||||
|
||||
在过去的很长时间中,我一直在思考,marqdo代码即文档,文档即知识库,知识库可执行有什么作用呢?
|
||||
|
||||
## code as document,document as skill,skill is tools
|
||||
|
||||
现在我给出的答案是,code as document,document as skill,skill is tools.
|
||||
|
||||
试想一个.mq.md文件,只需要撰写下来,智能体只需要每次执行:
|
||||
```
|
||||
marqdo call 文件名 函数名 函数参数
|
||||
```
|
||||
就能直接的得到执行结果,之后进行下一步的判断,更近一步,我们甚至可以在函数内写分支,但是让智能体决定走哪一个分支,让skill和tools不再强行分离。
|
||||
|
||||
甚至更近一步
|
||||
|
||||
```
|
||||
marqdo call 文件名 函数名 函数参数 toget 返回值
|
||||
```
|
||||
|
||||
得到返回值,在同一个会话进行多次的操作,之后记录下来,我们以后必定能够复现出来。
|
||||
|
||||
再进一步呢,智能体的输出就是marqdo脚本,只需要单步运行就能够得到结果。
|
||||
|
||||
## ABI插件
|
||||
|
||||
除此之外还有编程语言的特色,ABI插件,在deepseek harness中插件被证明是skill、mcp等的极好
|
||||
接入方式,那么有没有可能marqdo可以实现每一个插件都是通过ABI接入的?
|
||||
|
||||
我想答案似乎是可以的。
|
||||
|
||||
这种情况下拓展库应该怎么设计呢?
|
||||
|
||||
我觉得应该按照模块设计
|
||||
|
||||
index.mq.md
|
||||
依赖1
|
||||
……
|
||||
依赖2
|
||||
……
|
||||
|
||||
其中index.mq.md就是这个拓展库的SKILL文档,AI只需要阅读这个文档就知道该怎么使用这个拓展库。
|
||||
|
||||
甚至更近一步的,index.mq.md本身就是一个可执行的文档,包含拓展库的全部功能。
|
||||
|
||||
## 叙述代码是否足够?
|
||||
|
||||
我想叙述性文字在AI编程中是非常重要的,所以,我在这里提出一个编程规范:
|
||||
|
||||
> 所有的函数叙述性文字必须和实际文字混合且超过50%
|
||||
|
||||
进行**校验**如果通过则**通过**否则**不通过**
|
||||
|
||||
这应该是我写的第一个SKILL即tools吧
|
||||
|
||||
所有的拓展库都要规划成为这样。
|
||||
|
||||
skill即tools有一个绝妙的地方那就是tools是函数,函数本身就对应一个操作,这个操作就是一个工具,所以每个skill都只需要调用本身就可以是tools了,同时marqdo的设计中包含有### 更深层的函数,这就是子工具了
|
||||
@@ -0,0 +1,48 @@
|
||||
# Marqdo 2.7.0
|
||||
|
||||
本次 full 发布把源码手册落到实际开发与用户站点:文件操作、开发检查、构建与发版阶段可通过 marqdo call 执行;站点以递归组件、普通 Markdown 和明确的原生资源表达页面与行为。
|
||||
|
||||
This full release makes executable source handbooks practical for development and user sites. Native file tools and callable development/release tasks replace generated orchestration programs. Recursive View components preserve ordinary Markdown content and explicit runtime resources.
|
||||
|
||||
## 亮点 / Highlights
|
||||
|
||||
- 开发与发版 SKILL 路由到可执行 .mq.md 手册;文件读取、审阅、摘要校验和写入使用固有标准库。工程插件承担有界进程、私密认证、压缩格式和实际编译器检查边界,流程不依赖 Python 编排。
|
||||
- Literal JSON file/stdin CLI arguments preserve quotes, newlines and dollar-prefixed text. --require-ok makes a failed Result stop external automation; saved call sessions retain literal argument semantics.
|
||||
- 中英文网络站点与完整用户站点改为递归 View 布局、Markdown 内容、当前数据查询、表单、真实会话导航与鉴权资源。原有配色、字体、布局、文章详情和管理功能保留。
|
||||
- Pure document_head resources carry SEO and resource links into the actual head. Request-time query/form/navigation resources preserve the existing five-column View schema, source context and explicit effect boundaries. Prepared-app inspection follows the real registrar without executing handlers.
|
||||
- 原生 SQLite 初始化按实际站点授权根定位,保留已有业务记录;嵌套 Document 与 Endpoint 使用一致的站点根。修复表单校验重试中的 CSRF、成功跳转以及嵌套片段选择与路由检查。
|
||||
- The browser bridge supports typed nested list/control records. The maintained browser-app demonstrates duplicate-safe identities, literal text, truthful storage/network feedback, real history and local WebSocket echo with no authored business JavaScript.
|
||||
- 移除与语言仓库无关的暗恋工程及过时的独立浏览器演示;底层 WASM 冒烟夹具与公共回归保留。维护入口收敛到实际可运行的工程。
|
||||
|
||||
## 核心表面与兼容边界 / Core surface and boundaries
|
||||
|
||||
核心构造仍为 19 个,没有新增 Markdown 标记。改动集中在已有标记解析、CLI 参数传送、Runtime / Document 资源及工程工具;原生插件仍具有调用用户的操作系统权限,--fs-root 不把外部进程变成沙箱。显式 raw HTML 兼容出口不等同于不可信内容清理。编译检查与叙述比例检查不能单独证明运行或视觉正确。
|
||||
|
||||
The core surface remains 19 constructs. Native-only filesystem, process and authenticated service capabilities do not become browser WASM capabilities. Atomic file replacement is not a multi-file transaction, and digest preflight is not a kernel compare-and-swap. Deployment credentials remain in private stores.
|
||||
|
||||
## 下载 / Downloads
|
||||
|
||||
| 产物 / Asset | 内容 / Contents |
|
||||
|---|---|
|
||||
| marqdo-2.7.0-x86_64-pc-windows-msvc.exe | Windows CLI,内嵌标准库 / CLI with embedded standard library |
|
||||
| marqdo-2.7.0-x86_64-pc-windows-msvc.zip | Windows CLI、标准库、拓展源码与原生插件 / complete Windows bundle |
|
||||
| marqdo-2.7.0-x86_64-unknown-linux-gnu.zip | Linux CLI、标准库、拓展源码与原生插件 / complete Linux bundle |
|
||||
| marqdo-2.7.0-stdlib.zip | 可读标准库源码 / readable standard-library sources |
|
||||
| marqdo-2.7.0-ext.zip | 官方拓展库源码 / official extension sources |
|
||||
| marqdo-2.7.0-native-x86_64-pc-windows-msvc.zip | Windows web、agent、quantum、linalg、llm、engineering 插件 |
|
||||
| marqdo-2.7.0-native-x86_64-unknown-linux-gnu.zip | Linux web、agent、quantum、linalg、llm、engineering 插件 |
|
||||
| marqdo-2.7.0-source.zip | 本标签的源码快照 / tagged source snapshot |
|
||||
| marqdo-2.7.0.vsix | VS Code / Cursor 扩展,源码独立分支 / separate editor-source branch |
|
||||
| marqdo-2.7.0-public.zip | 由实际 .mq.md 导出的静态用户站点 / exported public documentation |
|
||||
|
||||
## 安装与使用 / Installation and use
|
||||
|
||||
下载对应平台的完整 ZIP,解压后使用其中的 CLI 与 lib/ext。已有 CLI 可通过 marqdo ext add 安装官方拓展;具体调用从标准库单文件或拓展库 index.mq.md 的参数与返回表开始。Linux 用户也可使用项目现有 Ubuntu noble PPA 安装路径;实际 apt 可用性以发布验证结果为准。
|
||||
|
||||
Download and unpack the matching platform bundle. Start from each standard-library source or extension index.mq.md. Development tools live in skills/marqdo-dev/index.mq.md; release tasks live in skills/marqdo-release/index.mq.md. A callable task preserves actual failures and grants only its declared effects. See README for the maintained install routes.
|
||||
|
||||
## 验证 / Validation
|
||||
|
||||
本地全量 Rust 验收为 1031 通过、0 失败、2 个原有模型实验忽略项;Go 网络插件完整测试通过。清理后重跑的 21 项 CLI/发版/WASM 测试以及 7 项真实浏览器用例通过,实际用户文档成功导出 102 页。源码审查单独检查标题下契约与超过一半的叙述;普通测试、人工夹具和历史兼容样例保留既有用途。
|
||||
|
||||
Windows and Linux release builds run in CI for this exact source tag. Final release verification separately checks those jobs, all artifact contents and hashes, GitHub/R2 byte parity and VERSION ordering, and Ubuntu source/build/apt publication. A local Linux test is not evidence of Windows execution or completed package publication. Public documentation export is packaged here; gh-pages deployment is separate.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Marqdo 2.7.1
|
||||
|
||||
本次为 CLI 修复发布,重点修复 View 中“实际逻辑”展开后立即折叠的问题,并完成描述链接的细节排版。官方拓展库继续使用 2.7.0,不发布新的独立拓展包,也不移动 CDN VERSION。
|
||||
|
||||
This CLI release fixes implementation disclosures that collapsed immediately after opening and improves typed details for descriptive links. Official extension packs remain at 2.7.0; no independent extension assets or CDN VERSION update are included.
|
||||
|
||||
## 修复与改进 / Fixes and improvements
|
||||
|
||||
- View 布局只记录自己的自动开合,不再覆盖用户选择;鼠标、键盘、窗口变化、嵌套原始写法及同一文档的运行结果刷新均保留手动状态。
|
||||
- Disclosure choices survive layout, resize and live DOM replacement. Layout-generated toggle events do not become user intent or trigger another reset loop.
|
||||
- 函数调用按函数名、命名参数和嵌套调用排版;本页函数可以定位到定义。链接在正文及侧注中保留跳转,相对 mq.md 链接适配实时和离线页面。
|
||||
- Lists, records and prose have typed presentation with optional original source. Empty payloads remain explicit placeholders; reading details never runs payloads.
|
||||
- 手机详情按整行排列,展开卡片不再撑高相邻卡片。新增可执行阅读示例 examples/view-details.mq.md。
|
||||
|
||||
## 核心表面与范围 / Core surface and scope
|
||||
|
||||
核心构造仍为 19 个,没有新增语法、标准库接口或插件 ABI。变更属于 CLI 内嵌 View 前端、只读渲染与发布产物选择。浏览器不会因查看详情而执行实现或自动抓取链接预览。
|
||||
|
||||
The core surface stays at 19 constructs. Standard-library and extension APIs are unchanged. CLI and WASM manifest versions are 2.7.1; extension source packs stay 2.7.0. The matching VS Code package is built from its separate source branch. This release does not deploy gh-pages.
|
||||
|
||||
## 下载与安装 / Downloads and installation
|
||||
|
||||
| 产物 / Asset | 内容 / Contents |
|
||||
|---|---|
|
||||
| marqdo-2.7.1-x86_64-pc-windows-msvc.exe | Windows CLI,内嵌标准库 / CLI with embedded standard library |
|
||||
| marqdo-2.7.1-x86_64-pc-windows-msvc.zip | Windows CLI 与配套库及原生插件 / complete Windows bundle |
|
||||
| marqdo-2.7.1-x86_64-unknown-linux-gnu.zip | Linux CLI 与配套库及原生插件 / complete Linux bundle |
|
||||
| marqdo-2.7.1-stdlib.zip | 标准库源码,API 未变 / standard-library sources with unchanged APIs |
|
||||
| marqdo-2.7.1-source.zip | 本标签源码 / tagged source snapshot |
|
||||
| marqdo-2.7.1.vsix | 独立编辑器分支构建 / editor extension from its separate branch |
|
||||
| marqdo-2.7.1-public.zip | 使用修复后的 View 导出的用户文档 / public docs exported with the fixed View |
|
||||
|
||||
下载并解压对应平台 ZIP,使用其中的 CLI;独立 Windows EXE 内嵌标准库。Ubuntu noble 用户可使用 ppa:cflmy/marqdo 安装或升级,实际包可用性由发版最终验证单独检查。旧的静态导出需用新 CLI 重新执行 marqdo view output,才能包含修复后的前端。
|
||||
|
||||
Unpack the matching platform bundle, or use the standalone Windows executable. The maintained Ubuntu noble installation route is ppa:cflmy/marqdo. Regenerate older static exports with marqdo view output to include the fixed reader script. A CLI-only release keeps the existing official extension installation version.
|
||||
|
||||
## 验证范围 / Validation
|
||||
|
||||
本地全量 Rust 验收为 1039 通过、0 失败、2 个原有忽略项;用户文档成功导出 102 页。本地验收覆盖真实详情点击、键盘开合、原始写法、反复布局、窗口变化、实时 DOM 替换,以及静态/实时页面、桌面/手机和无脚本阅读。另验证只读导出不会触发逻辑、现有运行标注与连线、文档间跳转和示例函数调用。
|
||||
|
||||
Windows and Linux builds, exact-commit Release/EK jobs, archive contents and hashes, and Ubuntu source/build/apt availability are independent final release gates. Local browser tests do not establish Windows build success, and upload acceptance does not establish apt availability.
|
||||
@@ -0,0 +1,102 @@
|
||||
# 智能体能力调研与求道差距复核(2026-10-27)
|
||||
|
||||
| 项目 | 说明 |
|
||||
|---|---|
|
||||
| 状态 | Research / 设计输入;不是功能交付声明 |
|
||||
| 调研日期 | 2026-10-27,Asia/Shanghai |
|
||||
| 源码基线 | Marqdo `16f26d7d60ce9fbc62feb0e8e83f93951f7b53fe`;qdagent `68b757e02ebfb64833b5262b0c8a683512581e8b` |
|
||||
| 框架设计 | [Agent 恢复、工具与资源协议](../design/agent-reliability-tools-resources-2026-10-27.md) |
|
||||
| 产品设计 | [求道智能体能力与预览体验](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级仓库) |
|
||||
|
||||
## 1. 方法与结论边界
|
||||
|
||||
先以 `git pull --ff-only` 同步两仓,再追踪真实调用链与前端入口;对比公开官方文档,不以营销介绍、工具数量或旧设计中的 done 标签代替实现证据。本次是静态源码复核与官方资料研究,没有启动部署实例,没有调用付费模型,没有进行竞品账号实测。因此,下表“源码确认”仅代表代码路径可见,“设计判断”与“待实测”不能写成已复现或已交付。
|
||||
|
||||
主流能力的共同方向是:可恢复的执行、结构化工具与资源、按需上下文、可追溯结果、独立产物展示。不同产品和模型支持范围不同;这里不是市场占有率调查,也不声称所有智能体都具备全部能力。求道应保留文档原生、EKC、验证后沉淀的定位,吸收机制,不引入第二套 Agent Runtime。
|
||||
|
||||
## 2. 官方资料与可借鉴机制
|
||||
|
||||
以下页面均在调研日实际打开;MCP 特意引用固定 `2025-06-18` 版本,作为兼容基线,不宣称它是最新协议。厂商专有能力必须探测,不能因为端点兼容 `/v1` 就认为全部可用。
|
||||
|
||||
| 编号 | 官方来源 | 已核实内容 | 对求道的设计启示 |
|
||||
|---|---|---|---|
|
||||
| S01 | [OpenAI Agents:集成与可观测性](https://developers.openai.com/api/docs/guides/agents/integrations-observability) | MCP 接入与运行、模型、工具等 tracing | 统一 call/attempt/span 关联;产品只显示阶段摘要,详细事件可展开 |
|
||||
| S02 | [OpenAI:Memory 与 Compaction](https://developers.openai.com/cookbook/examples/agents_sdk/building_reliable_agents_memory_compaction) | 区分当前任务上下文压缩、跨运行记忆、可审阅产物 | 历史不要无限拼接;完整产物不等于聊天全文 |
|
||||
| S03 | [LangGraph Persistence](https://docs.langchain.com/oss/python/langgraph/persistence) | checkpointer 保存 thread 状态,store 支撑跨 thread 数据 | 恢复执行状态和用户长期知识是两种生命周期 |
|
||||
| S04 | [LangGraph Interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) | 恢复时节点代码可能重新执行 | 检查点不能单独保证写操作只执行一次,必须记录效应与幂等键 |
|
||||
| S05 | [Claude Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | 工具定义按需进入模型上下文 | 工具多不代表每轮注入全部定义;检索后再校验权限 |
|
||||
| S06 | [Claude Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | 在执行环境中编排工具、筛选结果 | 大批量只读处理可减少模型往返;后置于基础工具可靠性 |
|
||||
| S07 | [Deep Agents overview](https://docs.langchain.com/oss/python/deepagents/overview) | 文件系统、上下文管理、子任务与可选规划能力 | 规划应按任务启用;简单问答不强制复杂工作流 |
|
||||
| S08 | [Gemini Tools](https://ai.google.dev/gemini-api/docs/tools) | 检索、URL、文件搜索、代码执行等工具面 | 覆盖“找资料—读内容—计算—形成产物”,不能只有工程检索 |
|
||||
| S09 | [Gemini File search](https://ai.google.dev/gemini-api/docs/file-search) | 文件检索与引用信息 | 命中要能定位原文,检索摘要不能代替源文件版本 |
|
||||
| S10 | [MCP Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) | schema、结构化结果、资源链接;annotations 有信任边界 | 工具结果包含短摘要和资源引用;注解不是权限凭证 |
|
||||
| S11 | [MCP Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) | URI 资源、读取和应用决定的上下文注入 | “预览”“加入上下文”“执行”必须是独立动作 |
|
||||
| S12 | [Claude Artifacts](https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them) | 产物在会话旁独立打开,可继续查看与编辑 | 右栏应承载正文;不应只提供离开当前会话的入口 |
|
||||
| S13 | [Mozilla PDF.js](https://mozilla.github.io/pdf.js/) | Web PDF 解析和渲染 | PDF 视觉预览和 OCR/知识提取分开交付 |
|
||||
| S14 | [DOMPurify 官方仓库](https://github.com/cure53/DOMPurify) | DOM 清洗、标签/属性配置;插入前清洗 | 替换前端正则“清洗器”,配合同源资源代理和 CSP |
|
||||
|
||||
上述设计启示是本次推导,相关性能收益、成本下降比例不照搬厂商基准。工程路线不绑定某个最新模型或套餐。
|
||||
|
||||
## 3. 源码事实清单
|
||||
|
||||
下列 qdagent 路径相对该仓库;Marqdo 路径相对本仓库。基线 commit 已固定,后续实现需按符号再定位。
|
||||
|
||||
| 编号 | 当前实现证据 | 结论与限制 |
|
||||
|---|---|---|
|
||||
| F01 | qdagent `agent/qdagent.mq.md::契约提示`、`ask` | ASK 和 BUILD 都要求完整六段式 `.mq.md`,包含 main、验证和元数据;普通回答变长有明确结构性诱因。不能断言这是唯一原因 |
|
||||
| F02 | 同文件 `ask` 的门禁修复分支 | `r2` 送入第二次门禁后,成功分支仍 `result = raw`;可能展示修复前内容,设计必须绑定同一 accepted candidate |
|
||||
| F03 | 同文件 `ask` 返回表 | `gated_error` 路径仍可能保留 `status=ok` 且返回 `ok=True`;必须明确业务失败与输送成功的不同含义 |
|
||||
| F04 | 同文件 `eng_tools` | 默认白名单是 `tool_find/reuse/bind/verify/summarize` 五个工程工具;不是整个框架只有五个工具,也不代表已覆盖网页、笔记、文件编辑 |
|
||||
| F05 | `ext/ai/agent.mq.md` | 有 step/plan/run、READ、CALL、观察压缩、工作簿和恢复接口;应扩展这些原语,不另造循环 |
|
||||
| F06 | `plugins/agent/src/resume.rs::resume_save` | JSON 直接 `fs::write`;现有恢复接口不等于具备原子检查点、工具效应对账及任意步骤自动续跑 |
|
||||
| F07 | `src/runtime/`、`src/workbench/capabilities.rs` | 已有隔离执行、取消、事件回放与读通道;这一轮是 Agent 级恢复补足,不重新规划整个进程池 |
|
||||
| F08 | qdagent `session-store.ts::resumeTurn` | 终态 completed/failed/interrupted 直接返回;已有事件续订,但终态消息补齐与中断后的执行恢复需分别处理 |
|
||||
| F09 | qdagent `DesktopFrame.tsx::RightNotesPanel` | 实际只有“查看全部笔记”导航至 `/notes`,没有侧栏笔记正文 |
|
||||
| F10 | 同文件 `RightFilesPanel`、`WorkspacePage.tsx::openFile` | 文件点击已调 `openTarget`;右栏取首个 workspace,根目录最多 40 个非目录项。不能笼统写“所有按钮都跳转” |
|
||||
| F11 | `DesktopFrame.tsx` 的 reader/rightbar 条件 | `DocumentReader` 与右侧 tab 容器互斥,且使用两套开关/宽度状态;不是统一的资源浏览面板 |
|
||||
| F12 | qdagent `NotesPage.tsx` detail | 剥离 frontmatter 后以 `whiteSpace: pre-wrap` 显示文本;没有 Markdown/Marqdo 正文结构渲染 |
|
||||
| F13 | qdagent `DocumentReader.tsx` | 已有 DocumentView、引用版本传递、请求代数防迟到覆盖;`profile_item` target 未进入读取分支,格式不是通用资源分派 |
|
||||
| F14 | 同文件 `sanitizeHtmlFragment` | 主要靠正则移除 script/事件/javascript URL;不能当作完整 HTML 白名单安全边界。未在本次做漏洞利用实验 |
|
||||
| F15 | `src/workbench/document_view.rs` | 有只读文档视图,注释与实现明确避开执行路径;已解析语义应继续复用 |
|
||||
| F16 | `src/workbench/capabilities.rs` | text/markdown 提取可用,pdf/docx/ocr 标 unavailable;提取能力与浏览器 PDF 预览能力须分别探测 |
|
||||
| F17 | qdagent `lib/web_search.mq.md` | 既有网页搜索桥使用 legacy 脚本和固定 `last_web_search.json`;存在并发覆盖设计风险,不能直接作为新工具通道 |
|
||||
| F18 | `plugins/agent/src/mcp_client.rs` | 已有 stdio connect/list/call/close;不能把本轮描述为“从零添加 MCP”,远程连接和资源能力需另验 |
|
||||
| F19 | qdagent `compose_messages` / `ask` | 对话按角色标记拼成字符串注入 standing;会话语义、上下文预算和外部内容信任层级仍需强化 |
|
||||
| F20 | qdagent `lib/workbench.mq.md::documents_read` | 临时文件名以秒和环境 RANDOM 构造,RANDOM 缺失又退到秒;设计仍需真正唯一临时文件。workspace 缺省 `.` 不应作为新授权资源接口规则 |
|
||||
|
||||
这些是本轮优先级依据。10-26 release notes 所列修复作为已有基础保留,但“Implemented(本仓)”不能替代浏览器、真实 HTTP、进程中断与模型输出的联合验收。
|
||||
|
||||
## 4. 能力覆盖与差距优先级
|
||||
|
||||
| 能力 | 当前基础 | 本轮目标 | 优先级 / 归属 |
|
||||
|---|---|---|---|
|
||||
| 自动纠错 | 一次文档门禁修复、plan patch | 分类错误、有限修复、正确结果替换、可恢复失败 | P0 / 两仓 |
|
||||
| 执行恢复 | 任务隔离、取消、事件回放、JSON checkpoint | 传输续订与执行续跑分离;效应对账 | P0 / Marqdo 原语,qdagent UX |
|
||||
| 回答长度 | 六段式文档、完整历史 | 直接回答、摘要+产物、显式详述三种表达 | P0 / qdagent 策略,Marqdo 输出通道 |
|
||||
| 资源阅读 | DocumentView / Locator | 笔记、工作文件、引用、产物统一入口 | P0 / 两仓 |
|
||||
| 侧栏预览 | 两套状态与导航入口 | 单一右栏,点击即预览,聊天不中断 | P0 / qdagent |
|
||||
| 工具使用 | 五工具默认白名单、MCP/库原语 | schema 注册、按需发现、资源读取/搜索/写入/验证 | P1 / 两仓 |
|
||||
| 联网研究 | legacy 搜索脚本 | search+fetch、来源时间、限量正文、可定位引用 | P1 / 两仓 |
|
||||
| 上下文与记忆 | EFI pack、profile、history | 分层上下文、预算、可编辑记忆、资源 pin | P1 / 两仓 |
|
||||
| 多格式 | 文档视图、文本提取 | text/md/mq/code/json/csv/image;PDF 后续 | P0→P1 / 两仓 |
|
||||
| 长任务与计划 | plan 工作簿 | 里程碑、预算、暂停/继续、产物进度 | P1 / 两仓 |
|
||||
| 多智能体与浏览器 | 不作为当前完成前提 | 有界委派、隔离执行、受控浏览器工具 | P2 / 框架主导 |
|
||||
| 可观测评测 | usage、事件与既有测试 | 工具/恢复指标、实际任务语料、回归门禁 | P0 起持续 / 两仓 |
|
||||
|
||||
## 5. 采用与暂缓的决策
|
||||
|
||||
采用:有界失败恢复;工具结果摘要+资源引用;结构化参数;步骤效应账本;产物与聊天投影分离;资源预览与“加入上下文”分离;用户可检查的引用;按需工具发现。原有源码、知识、工作簿与验证证据仍是权威,衍生视图可重建。
|
||||
|
||||
暂缓:全自动跨站电脑操作、任意外部 MCP 自动信任、默认多智能体协作、所有 Office 格式保真编辑、每次问答都规划/运行代码。它们不能先于当前恢复、工具授权和预览闭环。
|
||||
|
||||
不采用:把长回答直接 substring 截断、把失败原文当最终成功、前端断流即重发任务、把所有文件当 HTML、用网页内容改写 system 指令、把预览等同于执行可执行文档。
|
||||
|
||||
## 6. 必须补做的动态验证
|
||||
|
||||
1. 在真实聊天中验证六段式输出与门禁失败/修复的最终消息和持久产物是否一致。
|
||||
2. 丢弃最后一帧、断网、刷新、worker 崩溃分别注入,确认事件重放不重做工具副作用。
|
||||
3. 使用真实 HTTP 入口验证右栏笔记、嵌套文件、历史引用、跨 workspace 资源;不只调用兄弟辅助函数。
|
||||
4. 用恶意/畸形 HTML、路径与符号链接、过大文件验证预览隔离;no-exec 通过哨兵副作用测试。
|
||||
5. 对无凭证模型、text-only provider、不可用转换器做明确降级;记录版本与环境,禁止以 mock 成功声称上线成功。
|
||||
|
||||
后续设计文档中的时间、轮数、字符数、成功率阈值均为拟定验收目标,需用该语料校准。
|
||||
@@ -1,5 +1,7 @@
|
||||
# 调研:Mid M1–M6 之后标准库还缺什么
|
||||
|
||||
历史调研快照:以下缺口已由 Mid2 和后续标准库闭环分批解决,不能作为当前缺失清单。当前能力请从[标准库源码](../../lib/文件.mq.md)与[验收说明](../design/stdlib-handbook.md)核对。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** |
|
||||
|
||||
@@ -0,0 +1,194 @@
|
||||
# 跨仓 Agent 可靠性开发计划(2026-10-27)
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed / planning**;本文是排期与验收编排,**不是**已实现声明 |
|
||||
| 日期 | 2026-10-27(Asia/Shanghai) |
|
||||
| 基线 | Marqdo `6ffe5ce` / 2.1.4;qdagent `c4c976c`(设计文档基线曾为 `16f26d7` / `68b757e`;排期以当前 HEAD 为准) |
|
||||
| 协议真源 | [智能体能力补足设计](../design/agent-reliability-tools-resources-2026-10-27.md) |
|
||||
| 产品真源 | [qdagent 智能体能力与预览](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 证据 | [官方调研与 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品侧镜像 | [qdagent 开发计划镜像](../../../qdagent/doc/roadmap/agent-capabilities-development-2026-10-27.md) |
|
||||
|
||||
本文只编排依赖、落点、门禁与发布次序。**不发明第二套 Agent Framework**;不修改 `doc/next/`;不把 capability bit 在合同实测前标真。协议字段以设计文档为准,路线图只引用不另造 schema。
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;工具可发现、可验证、可审计;结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | ErrorV1、预算、CheckpointV2、效应账本、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | AgentOutput 分通道、输出预算、ContextPackV2 | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD |
|
||||
| 资源 | ResourceRef/View、只读预览、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
## 2. 现状(不再重做)
|
||||
|
||||
| 已落地基础 | 说明 |
|
||||
|---|---|
|
||||
| Agent A0–A4、O1–O5 | 文档原生 step/plan/run、沙盒与优化波次;扩展 `ext/ai/agent`,不另造循环 |
|
||||
| 隔离 Web 运行时(ADR 0009) | `src/runtime/` Verified;本轮补 Agent 步骤语义,不重建进程池 |
|
||||
| Workbench 合同切片 | DocumentView / Locator / capabilities;Partial,随本轮补 F 矩阵 |
|
||||
| 可执行知识 S0–S6 | 本地确定性子集已门禁;**不重开 S0–S6** |
|
||||
|
||||
本轮增量(设计已锁、代码待做):`AgentErrorV1`、`CheckpointV2` + effect ledger、`ToolSpecV1` 统一调度、`ResourceViewV1`、`AgentOutputV1` 通道、`ContextPackV2`。
|
||||
|
||||
**产品措辞约束**:本地门禁绿 ≠ 远程/多租户安全;≠「知识验证 + Agent 复用闭环」全产品完成。
|
||||
|
||||
## 3. 跨仓依赖与日历顺序
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
MA0[M-A0 contracts] --> QA0[Q-A0 fixtures]
|
||||
MA0 --> MA3[M-A3 ResourceView]
|
||||
MA0 --> MA1[M-A1 Error and Checkpoint]
|
||||
MA0 --> MA2[M-A2 ToolSpec]
|
||||
QA0 --> QA1[Q-A1 answer outcome]
|
||||
QA0 --> QA2[Q-A2 right panel]
|
||||
MA3 --> QA2
|
||||
QA1 --> QA3[Q-A3 recovery UX]
|
||||
MA1 --> QA3
|
||||
MA2 --> QA4[Q-A4 product tools]
|
||||
MA1 --> MA4[M-A4 channels ContextPack]
|
||||
MA2 --> MA4
|
||||
MA4 --> QA4
|
||||
MA3 --> QA5[Q-A5 formats]
|
||||
MA5[M-A5 ledger PDF MCP] --> QA5
|
||||
MA4 --> QA6[Q-A6 plan memory]
|
||||
MA5 --> QA7[Q-A7 connectors]
|
||||
MA6[M-A6 subagents] --> QA7
|
||||
```
|
||||
|
||||
### 3.1 强制顺序原则
|
||||
|
||||
1. 先 **M-A0 ∥ Q-A0** 冻结跨仓字段与缺陷 fixtures。
|
||||
2. 立刻 **Q-A1 + Q-A2 + M-A3(文本/md/mq)**——**不得**被完整 CheckpointV2 阻塞。
|
||||
3. **M-A1** 可先上只读重试 + 原子 checkpoint;**Q-A3** 终态快照可先行,写恢复等 effect ledger。
|
||||
4. 再 **M-A2 ∥ Q-A4** → **M-A4 / Q-A6** → **M-A5 / Q-A5** → **M-A6 / Q-A7**。
|
||||
5. 四类恢复必须分开:事件续订 / 步骤重试 / 工作流 resume(新 attempt + `resumed_from`)/ 答案再生成。
|
||||
|
||||
## 4. 阶段包明细
|
||||
|
||||
### Wave 0 — 合同
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A0** | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | Error/Tool/Resource/Output/Context 协议、旧适配、状态映射;capability **默认 false** | 跨仓字段冻结;未知字段/版本可降级 |
|
||||
| **Q-A0** | 缺陷样例、HTTP 路由清单、answer/resource fixtures;设计入口 | 固化 F01–F20 相关 fixtures;`mock`/`live` 证据区分 | 与 M-A0 字段一致;不把 mock 当 live |
|
||||
|
||||
### Wave 1 — 可见痛点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **Q-A1** | `agent/qdagent.mq.md`、`gateway/openai`、api 映射 | accepted candidate;`outcome` ≠ HTTP `ok`;摘要投影;ASK 不强制六节 | 修复后只展示 B;未通过不标成功(F01/F02/F03) |
|
||||
| **M-A3(首批)** | `src/workbench/document_view.rs`、新 `resource_view`、媒体适配 | ResourceRef/View;md/txt/code/mq 静态阅读;no-exec | 资源定位与安全语料通过(F15) |
|
||||
| **Q-A2** | `DesktopFrame`、panel store、`DocumentReader`、ResourcePanel/Preview | 统一右栏;笔记/文件点击不导航;同 renderer | 所有入口同预览(F09–F14) |
|
||||
|
||||
### Wave 2 — 恢复
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A1** | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、recovery/effects 模块 | ErrorV1、有界修复、accepted candidate 绑定、CheckpointV2 原子写 | 故障注入不重复写;旧记录不冒险自动恢复(F06) |
|
||||
| **Q-A3** | `execution/turns`、session store、`api.ts` | 终态快照补齐、恢复动作、错误卡 | 事件恢复 0 工具调用;写恢复须 ledger(F08) |
|
||||
|
||||
### Wave 3 — 工具与通道
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A2** | `plugins/agent/src/lib.rs`、`mcp_client.rs`、tool registry/dispatcher | ToolSpec/Call/Result;CALL+native 单通道;分页与结果资源 | 未授权调用为 0;失败结果结构正确(F04/F05/F18) |
|
||||
| **M-A4** | `ext/ai/agent.mq.md`、`plugins/llm`、`src/workbench/run_context.rs` | AgentOutput 通道、预算、ContextPackV2 | 原生与纯文本 provider fixture 可用(F01/F19) |
|
||||
| **Q-A4** | `agent/tools/`、工具目录、ContextAttachment | 业务工具;保留旧五工程工具别名 | 找→读→改→验证→预览真实闭环 |
|
||||
| **Q-A6** | 计划折叠、预算 UI、profile 忘记、候选沉淀 | ResponsePolicy UX、记忆边界 | 压缩与恢复不丢用户约束 |
|
||||
|
||||
### Wave 4 — 持久与格式
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A5** | `src/runtime/` 存储/事件适配、MCP 与转换插件 | ledger↔runtime 对账、PDF/Office 插件、远程 MCP | crash/restart 通过;诚实探测(F16–F18) |
|
||||
| **Q-A5** | JSON/CSV/图片/PDF UI、网页来源与页/行引用 | 格式扩展与转换进度 | 缺插件可读降级;PDF 不假称 OCR |
|
||||
| **M-A6 / Q-A7** | plan/subtask/sandbox;MCP 配置与委派 | 程序化工具、有界委派、可选浏览器 | **后置**;须证明收益与预算/效应可控 |
|
||||
|
||||
## 5. F01–F20 → 包映射
|
||||
|
||||
| ID | 摘要 | Marqdo | qdagent | 主要验收 |
|
||||
|---|---|---|---|---|
|
||||
| F01 | ASK/BUILD 强制六节 | M-A4 输出通道 | Q-A1 ResponsePolicy | QA-01、MA-T12 |
|
||||
| F02 | 修复后仍返回 raw | M-A1 accepted 绑定 | Q-A1 | QA-03、MA-T12 |
|
||||
| F03 | `gated_error` 仍 `status=ok` | M-A0/M-A1 ErrorV1 | Q-A1 envelope | QA-04 |
|
||||
| F04 | 默认仅五工程工具 | M-A2 registry | Q-A4 目录 | QA-17 |
|
||||
| F05 | 已有 step/plan/run | **扩展** agent.mq.md | — | 不另造 loop |
|
||||
| F06 | `resume_save` 裸 `fs::write` | M-A1 CheckpointV2 | Q-A3 UX | MA-T03/T04 |
|
||||
| F07 | runtime 已有 | 复用,不重建 | 接线恢复 API | — |
|
||||
| F08 | `resumeTurn` 终态直返 | 事件 vs 再执行分离 | Q-A3 快照补齐 | QA-13、MA-T05 |
|
||||
| F09–F12 | 右栏/笔记预览缺陷 | M-A3 ResourceView | Q-A2 | QA-06–QA-09 |
|
||||
| F13 | DocumentReader 非通用分派 | DocumentView 保留 mq;ResourceView 其它 | 预览分派 | QA-09 |
|
||||
| F14 | 正则 HTML 清洗 | 生产侧 allowlist | DOMPurify + CSP | QA-11、MA-T11 |
|
||||
| F15 | DocumentView no-exec | 保持;ResourceView 禁 run/verify | — | MA-T10 |
|
||||
| F16 | pdf/docx/ocr unavailable | M-A5 插件 + 诚实探测 | Q-A5 | QA-10 |
|
||||
| F17 | legacy web_search 临时文件 | 优先框架 net 工具 | 迁移工具 | QA-17、F20 |
|
||||
| F18 | MCP stdio 已有 | M-A2/5 timeout/cancel/remote | 连接器配置 | MA-T07 |
|
||||
| F19 | 历史字符串 standing | M-A4 ContextPackV2 | compose_messages | QA-19、MA-T13 |
|
||||
| F20 | 弱临时名;workspace `.` | 安全临时文件 + ResourceRef | 资源解析 | QA-08、MA-T11 |
|
||||
|
||||
## 6. 验收与发布
|
||||
|
||||
### 6.1 Marqdo 门禁(MA-T01–T14)
|
||||
|
||||
以设计文档 §10 为准;基础机制用确定性 fake provider/tool;真实 provider 少量单独 smoke 并记费用。摘要:
|
||||
|
||||
| 编号 | 必须观察到 |
|
||||
|---|---|
|
||||
| MA-T01 | 429 后成功:退避、计量、单一 accepted answer |
|
||||
| MA-T02 | schema 连续错:一次修复后停;无效参数不执行工具 |
|
||||
| MA-T03 | 写成功但 receipt 前提杀:unknown_effect→对账;写计数不增 |
|
||||
| MA-T04 | checkpoint 写一半杀进程:完整上一检查点或明确 corrupt |
|
||||
| MA-T05 | 终态事件丢失:快照恢复完整消息;工具次数不增 |
|
||||
| MA-T06 | 重复/并发恢复:同一幂等键一个 attempt |
|
||||
| MA-T07 | 取消 vs 重试:取消后无新工具调用 |
|
||||
| MA-T08 | 权限/版本变更:stale/conflict/forbidden |
|
||||
| MA-T09 | 伪造 CALL/system:不越白名单 |
|
||||
| MA-T10 | `.mq.md` 预览含写/联网:哨兵不变;只读或安全降级 |
|
||||
| MA-T11 | 格式/超长/路径逃逸:正确 renderer;越界拒绝;无注入 |
|
||||
| MA-T12 | 修复 A→B:answer/artifact/verification 均绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后:约束、待决效应、版本、预算不丢 |
|
||||
| MA-T14 | 旧 CALL/DocumentView:基础可用;缺失能力明确返回 |
|
||||
|
||||
先跑受影响的 Rust/Go/Marqdo 合同与隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标(须记录机器/并发/冷暖缓存):已缓存 100 KiB 文本视图服务端 p95 < 300 ms;核心工具发现 p95 < 100 ms。
|
||||
|
||||
### 6.2 qdagent 门禁(QA-01–QA-20)
|
||||
|
||||
以产品设计 §13 为准;路径必须 `serve → api → 权威业务函数 →` 真实前端。零容忍:重复写效应、预览执行副作用、跨 workspace 越权。
|
||||
|
||||
实现时:`python3 scripts/check-contracts.py`、相关 workbench 测试、前端 `npm test` / `npm run build`,再跑 Playwright;无服务时 E2E 须明确 skip/失败原因。
|
||||
|
||||
### 6.3 Feature flags 与灰度
|
||||
|
||||
建议开关:`agent_output_v2`、`resource_panel_v2`、`agent_tools_v1`、`agent_recovery_v2`。启用取决于 runtime capability + 服务端政策,不由前端单独决定。
|
||||
|
||||
灰度:内部单 workspace → 多 workspace → 真 provider/断网 → 默认开启。关闭恢复时必须停止接纳新恢复请求并保留 attempt 状态,**禁止**切回会盲重做写操作的旧路径。
|
||||
|
||||
兼容迁移:新增协议 → 双读 → 新写 → 验证 → 逐步移除旧适配。旧 resume JSON 可读但不能自动升级成带副作用保证的检查点。
|
||||
|
||||
## 7. 伴生轨(登记,不阻塞主线)
|
||||
|
||||
| 轨 | 动作 |
|
||||
|---|---|
|
||||
| 可执行知识 S0–S6 | **不重开**;消费 BoundCall/EKC;话术保持「本地子集」 |
|
||||
| 知识支撑 F0(M02/M03/M05) | **并行伴生**:provenance/closure invalidate、真 verify API、Skill 无冲突 |
|
||||
| Workbench Partial | 随 M-A0/M-A3 补 F 矩阵与 adapters;不重写 M00–M05 |
|
||||
| 语言 next-phase P3 / Wave B1 评测 | **延后** |
|
||||
| Web Document/Endpoint | 遵守 ADR 0007;禁止 compose_/json bag 回退 |
|
||||
|
||||
## 8. 下一步开工(第一刀实现切片)
|
||||
|
||||
确认本路线图入库后,**另开实现回合**(本文件仅文档):
|
||||
|
||||
1. **M-A0 + Q-A0**:合同与 fixtures
|
||||
2. **Q-A1**:raw→accepted、outcome 一致性
|
||||
3. **Q-A3 子集**:终态快照补齐
|
||||
4. **Q-A2 + M-A3 子集**:右栏真实预览(笔记 / md / mq / txt / code)
|
||||
|
||||
发布判据是 MA-T* / QA-* 与真实 HTTP/browser 证据,不是接口返回 200 或代码中出现某符号名。
|
||||
@@ -1,5 +1,8 @@
|
||||
# 路线图:浏览器 Marqdo 路线 F(进阶宿主能力)
|
||||
|
||||
> 2.7.0 维护说明:独立的 browser-hello 与 browser-media 演示已删除。下文保留既有能力设计与宿主边界,当前可运行工程使用 browser-app;底层计数器冒烟夹具位于 tests/wasm/counter.mq.md。Canvas、音频等仍是 lib/browser 的宿主能力,不宣称当前 browser-app 演示包含这些交互。
|
||||
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Completed**(F1–F5;F6 Service Worker 可选未做) |
|
||||
@@ -23,4 +26,4 @@
|
||||
| **F5** | drag/drop wire + `data-drag` / `drop_text` | **done** |
|
||||
| **F6** | Service Worker / 离线缓存 | optional / skipped |
|
||||
|
||||
示例:[examples/browser-media/](../../examples/browser-media/) · 助手:`lib/browser.mq.md`。
|
||||
示例:[examples/browser-app/](../../examples/browser-app/) · 助手:`lib/browser.mq.md`。
|
||||
@@ -1,5 +1,8 @@
|
||||
# 路线图:浏览器 Marqdo(WASM)
|
||||
|
||||
> 2.7.0 维护说明:独立的 browser-hello 与 browser-media 演示已删除。下文保留既有能力设计与宿主边界,当前可运行工程使用 browser-app;底层计数器冒烟夹具位于 tests/wasm/counter.mq.md。Canvas、音频等仍是 lib/browser 的宿主能力,不宣称当前 browser-app 演示包含这些交互。
|
||||
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Completed**(路线 C 首版功能完备;续作见 [browser-wasm-d.md](browser-wasm-d.md)) |
|
||||
@@ -23,7 +26,7 @@
|
||||
| ABI crate | `crates/marqdo-wasm` |
|
||||
| 官方 bridge | `crates/marqdo-wasm/js/marqdo-bridge.js` |
|
||||
| CLI | `marqdo wasm build -o DIR` |
|
||||
| 示例 | `examples/browser-hello/` |
|
||||
| 示例 | `examples/browser-app/` |
|
||||
| 冒烟 | `tests/wasm/smoke.mjs` · `tests/wasm_smoke.rs` |
|
||||
| L1 | `web.client_embed` / `网页.客户端挂载` |
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Q0–Q7 完结 · Q8a/Q8b 完结 · Q8c 待做** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 日期 | 2026-08-28 · 2026-11-08 手册闭环 |
|
||||
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) |
|
||||
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
|
||||
@@ -41,6 +41,8 @@
|
||||
|
||||
---
|
||||
|
||||
2026-11-08:双语 index 已补完整实验、开发路线与真实契约;新增手册源示例的双后端测试。使用与开发从[根入口](../../ext/quantum/index.mq.md)开始,修改动机见[手册优化记录](../design/ext-quantum-handbook.md)。
|
||||
|
||||
## 3. 已收敛的原开放点
|
||||
|
||||
| 原疑问 | 锁定结论(见设计文) |
|
||||
@@ -48,7 +50,7 @@
|
||||
| 并进 math? | **否**,独立 `ext/quantum` |
|
||||
| 电路表 | **要做**(Q3),与方法链等价 |
|
||||
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
|
||||
| 自由函数面 | **不**与对象面并行 |
|
||||
| 自由函数面 | 普通函数供 `call`,对象方法保留作者链;共用既有 ABI,见[手册修正](../design/ext-quantum-handbook.md) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# 库源码叙述式重构验收
|
||||
|
||||
本轮以[可执行开发指南](../library-development.mq.md)为准,覆盖 lib 与 ext 的全部 mq 源码。
|
||||
重构前为 117 个文件、1,258 个函数或对象单元;349 个缺少契约,956 条旧显式形参声明。
|
||||
完成后为 125 个文件、1,273 个单元。其中 61 份公开标准库保持单文件结构,提供 650 个函数;
|
||||
另有 lint 库单元。数据、安全、网络、线性代数和 AI 补齐工程入口,独立多文件职责由 index 组织。
|
||||
原工作区阅读器改动及本轮之前的功能实现保留。
|
||||
|
||||
- [x] 标准库保持单文件,赋值、调用与返回融入叙述,宿主调用有动作说明。
|
||||
- [x] 量子、网页的契约紧接标题,入口与叶子采用同一叙述规范。
|
||||
- [x] 数据、安全、网络、线性代数补齐契约、输入来源、真实工作流与多文件索引。
|
||||
- [x] AI 补齐公开与内部单元的职责说明,解释上下文、路由、工具、工作簿和失败处理。
|
||||
- [x] 所有单元移除旧形参,参数与返回表对应真实接口;不以占位工具或固定通过标志验收。
|
||||
- [x] 逐函数严格检查叙述超过 50%,行内表达式与绑定数据表仍计作代码。
|
||||
- [x] 既有接口与实际行为回归;真实工作流和源码示例在 Tree、Bytecode 执行。
|
||||
- [x] 扩展安装清单包含新入口及其源文件依赖,精简构建、WASM 与全量回归通过。
|
||||
|
||||
源码与工程组织
|
||||
|
||||
标准库不增加强制 index 或平行手册层。每个函数先给参数与返回契约,再说明输入、
|
||||
调用效应、用途、边界与实现。新 table.from_pairs / 表.键值转记录将较宽的具名记录改为
|
||||
可读的 key/value 行表;空列表、空值、重复键更新、键顺序与输入不可变性均有双后端验证。
|
||||
|
||||
拓展库入口解释任务选择、依赖、权限、结果跨步骤传递与开发归属。网页继续采用递归布局:
|
||||
首页拆导航、主体、页脚;页脚与链接的双栏继续拆,直到内部只是单一 Markdown 内容职责。
|
||||
父 index 只负责一层关系,叶子保留普通正文。已有双语参考站点验证真实嵌套、预览、服务与 API。
|
||||
|
||||
AI 中的静态提示、目录与工作簿片段改为普通表格数据,保留原字符、字段顺序和换行;
|
||||
真正的传输 JSON 仍交给 JSON 库解析。复杂函数解释决策顺序、工具授权、上下文预算、
|
||||
事件收集、去重账本和写回责任。中文单步的 sandbox 参数只附加配置行,实际隔离需调用
|
||||
CoW 试跑;工具名解析的半角冒号边界也已如实说明。
|
||||
|
||||
兼容性审核
|
||||
|
||||
[审核器](../../examples/library_audit.rs)使用真实解析器,对比参数顺序、默认值、对象层级、
|
||||
接收者、控制流与计算。遮蔽标签不参与执行;审核只对明确支持的纯常量构造做等价折叠,
|
||||
重复 JSON 键、不安全数值、非常量与未知调用均不会被当作等价常量。折叠规则有独立测试。
|
||||
原始源码快照保留在本次执行环境的临时目录;它不是另一套工具签名或运行时协议。
|
||||
|
||||
对比只有三项旧缺陷修复产生的八条 AST 差异,其余既有单元的参数、默认值与规范化执行结构一致。
|
||||
[精确修复记录](library-authoring-reviewed-fixes.json)保存差异名称、修复前后摘要与原因;
|
||||
审核器只接受摘要完全匹配的记录,新增差异或失效记录都会失败。
|
||||
|
||||
| 旧问题 | 实际修复与验证 |
|
||||
|---|---|
|
||||
| 中文单步说明中的斜体 map 被当作提前返回,实现错误落入构造器 | 说明恢复为文字,单步真正执行;离线模型替身验证上下文调用与最终结果 |
|
||||
| 事务构造器返回未绑定的 self | 用实际 txn 与 url 构造句柄;验证提交、回滚及事务外读取,不额外开启事务 |
|
||||
| 策略说明标题被误认成对象,main 返回未绑定的 routes | 恢复说明与真实 routes 工具,main 调用它;验证 lookup 和默认后端,文件后缀保持文字 |
|
||||
|
||||
执行证据(2026-11-08)
|
||||
|
||||
| 检查 | 结果 |
|
||||
|---|---|
|
||||
| `cargo test --offline --test library_authoring` | 5 项通过;覆盖全部 125 份源码与 1,273 单元、包工作流、旧缺陷、双语记录与安装依赖 |
|
||||
| `cargo test --offline --test stdlib_tasks --test quantum_handbook --test web_handbook` | 18 + 4 + 3 项通过;源码中的真实命令与作者程序在双后端运行 |
|
||||
| `cargo run --offline --quiet --example stdlib_catalog -- --check` | 650 个公开函数,0 条效应说明需要更新 |
|
||||
| AST 原始快照对比及精确修复记录检查 | 8 条已审查修复差异,0 条未解释差异,0 条失效记录 |
|
||||
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets` | 982 通过、0 失败、2 个原有忽略项,包含千文档编译与 312 项金样例 |
|
||||
| `cargo check --offline --no-default-features --features wasm-core` | 通过;保留已有未使用代码告警 |
|
||||
| 版本匹配工具链的实际 wasm32 构建与 Node 验收 | ABI、桥接、标准库、32 位边界、双语记录、转义表格及句中遮蔽计算通过 |
|
||||
| `git diff --check` | 通过 |
|
||||
|
||||
GOFLAGS 仅用于当前命令绕过工作区所有权引起的 Go VCS 盖章问题,不修改全局配置。
|
||||
WASM 使用临时目录中版本匹配的官方工具链;不以本机编译代替真实 wasm 运行。
|
||||
网络和身份提供方示例使用离线数据或本机可控服务;没有把构造配置、清单或演示结果
|
||||
宣称成生产服务已验证。Node 验收不代表重新完成浏览器 DOM 几何验收。
|
||||
@@ -0,0 +1,50 @@
|
||||
[
|
||||
{
|
||||
"after": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
|
||||
"before": "754acb518e0d5f0c5c6f6ae6d48c94a1df69ddbdfff13395114786cbe63edf5e",
|
||||
"difference": "removed ext/ai/policies/step-route.mq.md \"Step class → backend\"",
|
||||
"reason": "修复说明标题被误认成对象、路由表未绑定且 main 返回未定义 routes;真实 routes 工具返回原策略数据,沙盒行文件后缀显式写为文字。双后端验证 lookup 和默认后端。"
|
||||
},
|
||||
{
|
||||
"after": "62bd87e62802aeaefbc635715481451d5eee3b918aefe8db9c816039ef91b04f",
|
||||
"before": "f6c5aecc836c461f7593ffabe9cc2c236a3738a90c49c9c2b5c12a767d97c94c",
|
||||
"difference": "ext/ai/policies/step-route.mq.md \"main\" changed body",
|
||||
"reason": "修复说明标题被误认成对象、路由表未绑定且 main 返回未定义 routes;真实 routes 工具返回原策略数据,沙盒行文件后缀显式写为文字。双后端验证 lookup 和默认后端。"
|
||||
},
|
||||
{
|
||||
"after": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"before": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体\" changed receiver",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "888398739b40074de2e2f93943516541eec872cecc284835968650b3ef72a24d",
|
||||
"before": "a7553f00f8f05c97c2c44299fd2fcd4641c8f5e9acbb6a246874b096a2acdc0a",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体\" changed body",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"before": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体.单步\" changed receiver",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "e3853fac627ca88f1557132aabb6b818ecc805ab53e6feacb3b08c77e503ece4",
|
||||
"before": "aae371909b83bdaec63671897c5581a8ba7f14a5e113bd825fca0576df403e2b",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体.单步\" changed body",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"before": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"difference": "ext/data/db.mq.md \"txn\" changed receiver",
|
||||
"reason": "事务构造器原来返回未绑定的 self;改为保留调用者传入的真实 txn 和 url 句柄,不额外开始事务。双后端验证构造、提交、回滚与事务外读取。"
|
||||
},
|
||||
{
|
||||
"after": "0a51bc7e7fe4577f32aae9a76ea461213c3547ea9e937f280e17b6e8075194c5",
|
||||
"before": "92096850522e76cff3350d582b57ae3124fd400635ad25fd63f208a1994514f0",
|
||||
"difference": "ext/data/db.mq.md \"txn\" changed body",
|
||||
"reason": "事务构造器原来返回未绑定的 self;改为保留调用者传入的真实 txn 和 url 句柄,不额外开始事务。双后端验证构造、提交、回滚与事务外读取。"
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,60 @@
|
||||
# 标准库:可执行手册与通用能力闭环
|
||||
|
||||
目标:代码即文档,文档即 SKILL,SKILL 即 tools。AI 直接阅读任务对应的 `lib/*.mq.md` 单文件,理解输入来源、输出形态、效应、失败处理和可执行示例;保持既有导入兼容。
|
||||
本清单记录真实交付状态,未完成项不能因文档或接口占位而标为完成。
|
||||
|
||||
## 阶段与验收
|
||||
|
||||
- [x] A. 宿主效应作为唯一事实来源;直调、导入别名、中英文和双后端一致。
|
||||
- [x] A. `call` 明确授权文件读写及根目录;会话重放保留权限范围。
|
||||
- [x] A. 明确递归删除、索引基数、不可变更新、结构化可恢复错误契约。
|
||||
- [x] B. 文件筛选、行/JSON/CSV 读写、目录树复制、批量改名/同步及冲突策略。
|
||||
- [x] B. 原子/条件写入、临时目录与清理、路径相对化与扩展名替换。
|
||||
- [x] C. 序列、投影、筛选、分组/聚合、连接、按键去重/多键排序和表形态转换。
|
||||
- [x] C. 字段类型转换与记录校验;避免回调字符串求值及新集合方言。
|
||||
- [x] D. 字节与分块 IO、文件哈希、网络下载、压缩归档及明确资源上限。
|
||||
- [x] D. HTTP 响应头、可配置超时、一致的错误结果;保留既有入口兼容。
|
||||
- [x] E. 子任务超时、并发上限、批量取消与资源回收。
|
||||
- [x] E. 日期完整时区/DST、配置读写边界、规模性能。
|
||||
- [x] F. 文档章节/表格/代码块/链接提取和保留叙述的受控局部修改,复用解析器。
|
||||
- [x] G. 全标准库单文件手册、标题下参数表、叙述形参和遮蔽调用;叙述超过 50%;提供契约与真实示例;不以伪函数或叙述比例代替正确性。
|
||||
- [x] G. 三个端到端工程:文件整理、CSV 数据处理、文档维护;示例直接提取执行。
|
||||
- [x] G. 相关回归、双后端、默认/最小特性构建及平台能力矩阵。
|
||||
|
||||
## 实施约束
|
||||
|
||||
保留工作区已有的 reader 改动。通用组合优先 `.mq.md`,OS/算法边界使用小型宿主原语;
|
||||
不增加第二套 Skill 编译器、字符串 eval 或应用模板语法。递归删除保留旧入口行为,
|
||||
新增清晰的窄接口;每次修改都同时写清兼容性和失败语义。
|
||||
|
||||
## 验证记录
|
||||
|
||||
按用户澄清修正为 31 个模块族、61 份公开标准库单文件;撤除先前误增的 64 份目录与模块手册。648 个公开函数的名称、参数顺序和默认值 AST 与迁移前逐项一致;不再保留旧 + 形参。源码中的实际调用在 Tree 与 Bytecode 共执行 126 次,并检查操作结果。17 项标准库工程测试通过;所有函数的叙述比例均超过 50%。
|
||||
|
||||
先前能力实现的验证记录如下;单文件结构与遮蔽调用修正后的全量复验记录在表后追加。
|
||||
|
||||
| 验证 | 真实结果 |
|
||||
|---|---|
|
||||
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets` | 首次全量 967 通过、0 失败、2 个原有忽略项,包含千文档编译测试 |
|
||||
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets -- --skip v3_corpus_1000_compile_smoke` | 结构修正前回归 968 通过、0 失败、2 个原有忽略项;跳过的千文档测试已在首次全量通过,合计覆盖 969 个不同通过项 |
|
||||
| `cargo check --offline --no-default-features --features wasm-core` | 通过;保留已有未使用代码告警 |
|
||||
| `cargo run --offline --quiet --example stdlib_catalog -- --check` | 0 条源码效应说明需要更新 |
|
||||
| `cargo check/build --offline -p marqdo-wasm --target wasm32-unknown-unknown` | 使用临时目录内版本匹配的官方工具链通过 |
|
||||
| `node tests/wasm/smoke.mjs <wasm产物>` | ABI 与桥接通过 |
|
||||
| `node tests/wasm/stdlib.mjs <wasm产物>` | 集合、字节、文档、TOML、IANA/DST 与 32 位边界通过 |
|
||||
| `git diff --check` | 通过 |
|
||||
|
||||
最终全量回归包含 17 项标准库工程测试。`GOFLAGS` 仅对本次命令关闭工作区所有权导致的 Go VCS 盖章失败,不修改全局 Git 配置。wasm 检查和运行使用同一构建产物,Node 验收不代表浏览器 DOM 布局验收。
|
||||
|
||||
单文件结构与遮蔽调用修正后的复验:
|
||||
|
||||
- `GOFLAGS=-buildvcs=false cargo test --offline --all-targets`:970 通过、0 失败、2 个原有忽略项,包含千文档编译、312 项金样例及 17 项标准库工程测试。
|
||||
- 61 份公开源码包含 63 条真实命令,Tree 与 Bytecode 共执行 126 次;操作返回 Result 时同时检查其 ok。
|
||||
- 648 个函数的名称、参数顺序与默认值 AST 逐项保持一致;每个函数叙述均超过 50%,标题下有完整契约,且不再保留旧形参。
|
||||
- 编译器效应检查:0 条源码效应说明需要更新;--json 直接输出 648 条真实接口记录。
|
||||
- 精简 wasm-core 构建通过;当前源码重新构建的 wasm32 产物通过 ABI、桥接和标准库 Node 运行验证。
|
||||
- `git diff --check` 通过。保留原有 reader 工作区修改。
|
||||
|
||||
删除旧形参后,沿用现有叙述形参推断;修复引号内星号、分号、空格被误作默认值边界的问题,并增加扫描回归测试。宿主调用的遮蔽标签不参与执行,诊断测试继续穿过标签定位真实指令和独立调用点。
|
||||
|
||||
[设计与能力边界](../design/stdlib-handbook.md)记录平台能力矩阵、兼容索引基数、资源上限、CoW 限制、目录复制范围、条件写入并发边界及线程取消语义。这些边界均为明确契约,不以占位实现宣称支持。保留工作区既有 reader 改动。
|
||||
@@ -13,50 +13,58 @@ import:
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
This is an offline knowledge-reuse workflow, not a request to an external model. It loads the agent plugin, promotes the visible workbook for one exact goal and asks the same agent goal again. The expected hit comes from the promoted knowledge base. The dummy key only satisfies model setup; it is not a credential or evidence that a model call succeeded.
|
||||
|
||||
The example uses its own named files under .marqdo and replaces that example knowledge base on rerun. Grant the actual plugin and filesystem effects in a disposable example root. Promotion and execution are separate outcomes: inspect promoted first, then cache, match and the returned result. A hit marker alone does not prove that an unrelated new goal is safe to reuse.
|
||||
|
||||
OKF flywheel offline: promote → plan same goal → `cache=hit` (no live LLM required for the hit path).
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
We first **p = [Compute p](plugin.native_path(name="agent"))** for the next step.
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
We now **[Call plugin.load](> plugin.load path=`p`)**.
|
||||
2. *
|
||||
> print text=no-agent-plugin
|
||||
> sys.exit code=1
|
||||
We now **[Display this step's result](> print text="no-agent-plugin")**.
|
||||
We now **[Call sys.exit](> sys.exit code=1)**.
|
||||
|
||||
> sys.env_set name="OPENAI_API_KEY" value="offline-okf-dummy"
|
||||
**model = > llm.llm**
|
||||
**tools = > json.parse text=[]**
|
||||
**助手 = > agent.agent model=`model` tools=`tools` standing="offline okf flywheel"**
|
||||
We now **[Call sys.env set](> sys.env_set name="OPENAI_API_KEY" value="offline-okf-dummy")**.
|
||||
We first **model = [Compute model](llm.llm())** for the next step.
|
||||
We first **tools = [Compute tools](json.parse(text="[]"))** for the next step.
|
||||
We first **助手 = [Compute 助手](agent.agent(model=`model`, tools=`tools`, standing="offline okf flywheel"))** for the next step.
|
||||
|
||||
**kb = ".marqdo/agent-kb-example-flywheel"**
|
||||
**wb = ".marqdo/agent-runs/example-pong-solid.mq.md"**
|
||||
**goal = "Reply with exactly the word pong and nothing else."**
|
||||
**body = "---\ntitle: okf pong\n---\n\n# main\n\n*msg = \"pong\"*\n\n**msg**\n"**
|
||||
We first **kb = ".marqdo/agent-kb-example-flywheel"** for the next step.
|
||||
We first **wb = ".marqdo/agent-runs/example-pong-solid.mq.md"** for the next step.
|
||||
We first **goal = "Reply with exactly the word pong and nothing else."** for the next step.
|
||||
We first **body = "---\ntitle: okf pong\n---\n\n# main\n\n*msg = \"pong\"*\n\n**msg**\n"** for the next step.
|
||||
|
||||
1. > fs.exists path=`kb`
|
||||
> fs.remove path=`kb`
|
||||
We now **[Call fs.remove](> fs.remove path=`kb`)**.
|
||||
2. *
|
||||
---
|
||||
|
||||
> fs.write_text path=`wb` text=`body`
|
||||
We now **[Call fs.write text](> fs.write_text path=`wb` text=`body`)**.
|
||||
|
||||
**prom = > agent_kb_promote kb_dir=`kb` goal=`goal` workbook=`wb`**
|
||||
**okp = > json.get value=`prom` key="promoted"**
|
||||
We first **prom = [Compute prom](agent_kb_promote(kb_dir=`kb`, goal=`goal`, workbook=`wb`))** for the next step.
|
||||
We first **okp = [Compute okp](json.get(value=`prom`, key="promoted"))** for the next step.
|
||||
1. `okp`
|
||||
> print text=promoted
|
||||
We now **[Display this step's result](> print text="promoted")**.
|
||||
2. *
|
||||
> print text=promote-fail
|
||||
> sys.exit code=1
|
||||
We now **[Display this step's result](> print text="promote-fail")**.
|
||||
We now **[Call sys.exit](> sys.exit code=1)**.
|
||||
|
||||
**out = > `助手`.plan goal=`goal` max_rounds=2 writeback=False kb_dir=`kb` explore_n=0 promote=False**
|
||||
**cache = > json.get value=`out` key="cache"**
|
||||
> print text=`cache`
|
||||
**match = > json.get value=`out` key="match"**
|
||||
> print text=`match`
|
||||
**val = > json.get value=`out` key="result"**
|
||||
> print text=`val`
|
||||
We first **out = [Compute out](> `助手`.plan goal=`goal` max_rounds=2 writeback=False kb_dir=`kb` explore_n=0 promote=False)** for the next step.
|
||||
We first **cache = [Compute cache](json.get(value=`out`, key="cache"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`cache`)**.
|
||||
We first **match = [Compute match](json.get(value=`out`, key="match"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`match`)**.
|
||||
We first **val = [Compute val](json.get(value=`out`, key="result"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`val`)**.
|
||||
|
||||
1. `cache` == "hit"
|
||||
> print text=flywheel-ok
|
||||
We now **[Display this step's result](> print text="flywheel-ok")**.
|
||||
2. *
|
||||
> print text=flywheel-miss
|
||||
> sys.exit code=1
|
||||
We now **[Display this step's result](> print text="flywheel-miss")**.
|
||||
We now **[Call sys.exit](> sys.exit code=1)**.
|
||||
@@ -15,21 +15,33 @@ import:
|
||||
|
||||
## 获取时间
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | The value explicitly returned below; conditional returns follow the selected branch |
|
||||
|
||||
Return today's date string (tool visible in source to the model).
|
||||
|
||||
**u = > time.now_unix**
|
||||
*> time.format unix=`u` pattern="%Y-%m-%d"*
|
||||
We first **u = [Compute u](time.now_unix())** for the next step.
|
||||
After these steps, return *time.format(unix=`u`, pattern="%Y-%m-%d")*.
|
||||
|
||||
# main
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=no-agent-plugin
|
||||
> sys.exit code=1
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
> llm.load_env path="../../.env"
|
||||
This entry first verifies what the agent can read about its own call site. It assembles a step context and checks for the call-site section, source section and the actual time-tool name before considering an optional live step. The tool table points to the real local function; it is not an independently maintained tool description detached from the source.
|
||||
|
||||
Normal demonstration stops at context evidence and does not require a paid model response. AGENT_LIVE and an available key together opt into the separate live branch. Context markers establish prompt content, not the correctness of a future model answer. Keep the tool result and returned status visible when exercising that branch; never replace a missing credential with a fixed successful response.
|
||||
|
||||
We first **p = [Compute p](plugin.native_path(name="agent"))** for the next step.
|
||||
1. `p`
|
||||
We now **[Call plugin.load](> plugin.load path=`p`)**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="no-agent-plugin")**.
|
||||
We now **[Call sys.exit](> sys.exit code=1)**.
|
||||
|
||||
We now **[Call llm.load env](> llm.load_env path="../../.env")**.
|
||||
|
||||
`工具表` =
|
||||
|
||||
@@ -37,55 +49,55 @@ Return today's date string (tool visible in source to the model).
|
||||
|------|
|
||||
| 获取时间 |
|
||||
|
||||
**model = > llm.llm**
|
||||
**助手 = > agent.agent model=`model` tools=`工具表` standing="You are a Marqdo agent. Prefer CALL:获取时间 when the task needs today's date."**
|
||||
We first **model = [Compute model](llm.llm())** for the next step.
|
||||
We first **助手 = [Compute 助手](agent.agent(model=`model`, tools=`工具表`, standing="You are a Marqdo agent. Prefer CALL:获取时间 when the task needs today's date."))** for the next step.
|
||||
|
||||
Assert constitution markers in the assembled prompt (call site before how-to-act):
|
||||
|
||||
**ctx = > agent.build_step_context agent=`助手` task="What is today's date? Use the tool in this runbook."**
|
||||
We first **ctx = [Compute ctx](agent.build_step_context(agent=`助手`, task="What is today's date? Use the tool in this runbook."))** for the next step.
|
||||
|
||||
**parts = > split value=`ctx` sep="--- call site ---"**
|
||||
**n = > len value=`parts`**
|
||||
We first **parts = [Compute parts](split(value=`ctx`, sep="--- call site ---"))** for the next step.
|
||||
We first **n = [Compute n](len(value=`parts`))** for the next step.
|
||||
1. `n` > 1
|
||||
> print text=call-site-ok
|
||||
We now **[Display this step's result](> print text="call-site-ok")**.
|
||||
2. *
|
||||
> print text=call-site-missing
|
||||
> sys.exit code=1
|
||||
We now **[Display this step's result](> print text="call-site-missing")**.
|
||||
We now **[Call sys.exit](> sys.exit code=1)**.
|
||||
|
||||
**parts2 = > split value=`ctx` sep="--- source (.mq.md) ---"**
|
||||
**n2 = > len value=`parts2`**
|
||||
We first **parts2 = [Compute parts2](split(value=`ctx`, sep="--- source (.mq.md) ---"))** for the next step.
|
||||
We first **n2 = [Compute n2](len(value=`parts2`))** for the next step.
|
||||
1. `n2` > 1
|
||||
> print text=source-ok
|
||||
We now **[Display this step's result](> print text="source-ok")**.
|
||||
2. *
|
||||
> print text=source-missing
|
||||
> sys.exit code=1
|
||||
We now **[Display this step's result](> print text="source-missing")**.
|
||||
We now **[Call sys.exit](> sys.exit code=1)**.
|
||||
|
||||
**parts3 = > split value=`ctx` sep="获取时间"**
|
||||
**n3 = > len value=`parts3`**
|
||||
We first **parts3 = [Compute parts3](split(value=`ctx`, sep="获取时间"))** for the next step.
|
||||
We first **n3 = [Compute n3](len(value=`parts3`))** for the next step.
|
||||
1. `n3` > 1
|
||||
> print text=tool-in-source-ok
|
||||
We now **[Display this step's result](> print text="tool-in-source-ok")**.
|
||||
2. *
|
||||
> print text=tool-in-source-missing
|
||||
> sys.exit code=1
|
||||
We now **[Display this step's result](> print text="tool-in-source-missing")**.
|
||||
We now **[Call sys.exit](> sys.exit code=1)**.
|
||||
|
||||
**site = > agent_call_site**
|
||||
**fn = > json.get value=`site` key="function"**
|
||||
> print text=`fn`
|
||||
We first **site = [Compute site](agent_call_site())** for the next step.
|
||||
We first **fn = [Compute fn](json.get(value=`site`, key="function"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`fn`)**.
|
||||
|
||||
Optional live step — set env AGENT_LIVE=1 and put keys in repo-root `.env`:
|
||||
|
||||
**live = > sys.env_get name="AGENT_LIVE"**
|
||||
**key = > sys.env_get name="OPENAI_API_KEY"**
|
||||
We first **live = [Compute live](sys.env_get(name="AGENT_LIVE"))** for the next step.
|
||||
We first **key = [Compute key](sys.env_get(name="OPENAI_API_KEY"))** for the next step.
|
||||
1. `live` == "1"
|
||||
1. `key`
|
||||
**out = > `助手`.step task="请调用获取时间工具,然后只回复日期字符串。" writeback=False**
|
||||
**status = > json.get value=`out` key="status"**
|
||||
> print text=`status`
|
||||
**tool = > json.get value=`out` key="tool"**
|
||||
> print text=`tool`
|
||||
**result = > json.get value=`out` key="result"**
|
||||
> print text=`result`
|
||||
We first **out = [Compute out](> `助手`.step task="请调用获取时间工具,然后只回复日期字符串。" writeback=False)** for the next step.
|
||||
We first **status = [Compute status](json.get(value=`out`, key="status"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`status`)**.
|
||||
We first **tool = [Compute tool](json.get(value=`out`, key="tool"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`tool`)**.
|
||||
We first **result = [Compute result](json.get(value=`out`, key="result"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`result`)**.
|
||||
2. *
|
||||
> print text=live-skipped-no-key
|
||||
We now **[Display this step's result](> print text="live-skipped-no-key")**.
|
||||
2. *
|
||||
> print text=live-skipped
|
||||
We now **[Display this step's result](> print text="live-skipped")**.
|
||||
@@ -10,52 +10,60 @@ import:
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
The two trials intentionally differ only in commit. First inspect a successful dry trial and verify that note.txt has not appeared in the host directory. Then run the committed trial, read the host file and compare its actual content. This separates an observed proposal from an observed filesystem change; neither ok alone nor a proposed path establishes that a commit happened.
|
||||
|
||||
Use a disposable filesystem root: the example replaces its named _example_sbx directory and leaves the committed evidence there for inspection. It does not promise to roll back a committed external effect. Read the returned profile as part of the trial evidence, and keep failures visible rather than manufacturing a success marker when the expected file is absent.
|
||||
|
||||
Short demo: write via `agent.trial`, prove the host is clean until commit.
|
||||
|
||||
**had = fs.exists path="_example_sbx"**
|
||||
We first **had = [Compute had](fs.exists(path="_example_sbx"))** for the next step.
|
||||
1. `had`
|
||||
> fs.remove path="_example_sbx"
|
||||
We now **[Call fs.remove](> fs.remove path="_example_sbx")**.
|
||||
2. *
|
||||
**_ = 0**
|
||||
We first **_ = 0** for the next step.
|
||||
|
||||
> fs.make_dir path="_example_sbx"
|
||||
We now **[Call fs.make dir](> fs.make_dir path="_example_sbx")**.
|
||||
|
||||
**dry = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=False**
|
||||
**dry_ok = [ok](access(dry, "ok"))**
|
||||
**dry_committed = [committed](access(dry, "committed"))**
|
||||
We first **dry = [Compute dry](agent.trial(root="_example_sbx", write_path="note.txt", text="sandbox-okf", commit=False))** for the next step.
|
||||
We first **dry_ok = [ok](access(`dry`, "ok"))** for the next step.
|
||||
We first **dry_committed = [committed](access(`dry`, "committed"))** for the next step.
|
||||
1. `dry_ok`
|
||||
1. not `dry_committed`
|
||||
> print text=dry-ok
|
||||
We now **[Display this step's result](> print text="dry-ok")**.
|
||||
2. *
|
||||
> print text=dry-bad-commit
|
||||
We now **[Display this step's result](> print text="dry-bad-commit")**.
|
||||
2. *
|
||||
> print text=dry-fail
|
||||
We now **[Display this step's result](> print text="dry-fail")**.
|
||||
|
||||
**leaked = fs.exists path="_example_sbx/note.txt"**
|
||||
We first **leaked = [Compute leaked](fs.exists(path="_example_sbx/note.txt"))** for the next step.
|
||||
1. `leaked`
|
||||
> print text=host-leaked
|
||||
We now **[Display this step's result](> print text="host-leaked")**.
|
||||
2. *
|
||||
> print text=host-clean
|
||||
We now **[Display this step's result](> print text="host-clean")**.
|
||||
|
||||
**wet = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=True**
|
||||
**wet_ok = [ok](access(wet, "ok"))**
|
||||
**wet_committed = [committed](access(wet, "committed"))**
|
||||
We first **wet = [Compute wet](agent.trial(root="_example_sbx", write_path="note.txt", text="sandbox-okf", commit=True))** for the next step.
|
||||
We first **wet_ok = [ok](access(`wet`, "ok"))** for the next step.
|
||||
We first **wet_committed = [committed](access(`wet`, "committed"))** for the next step.
|
||||
1. `wet_ok`
|
||||
1. `wet_committed`
|
||||
> print text=wet-ok
|
||||
We now **[Display this step's result](> print text="wet-ok")**.
|
||||
2. *
|
||||
> print text=wet-no-commit
|
||||
We now **[Display this step's result](> print text="wet-no-commit")**.
|
||||
2. *
|
||||
> print text=wet-fail
|
||||
We now **[Display this step's result](> print text="wet-fail")**.
|
||||
|
||||
**body = fs.read_text path="_example_sbx/note.txt"**
|
||||
We first **body = [Compute body](fs.read_text(path="_example_sbx/note.txt"))** for the next step.
|
||||
1. `body` == "sandbox-okf"
|
||||
> print text=proof-visible
|
||||
We now **[Display this step's result](> print text="proof-visible")**.
|
||||
2. *
|
||||
> print text=proof-missing
|
||||
We now **[Display this step's result](> print text="proof-missing")**.
|
||||
|
||||
**pname = [name](access([profile](access(wet, "profile")), "name"))**
|
||||
We first **pname = [name](access([profile](access(`wet`, "profile")), "name"))** for the next step.
|
||||
1. `pname` == "default"
|
||||
> print text=profile-default
|
||||
We now **[Display this step's result](> print text="profile-default")**.
|
||||
2. *
|
||||
> print text=profile-other
|
||||
We now **[Display this step's result](> print text="profile-other")**.
|
||||
@@ -1,45 +0,0 @@
|
||||
# 暗恋见君 · Marqdo 重写
|
||||
|
||||
用 **Marqdo + `ext/web`(Go `libweb`)** 对齐 Django [anlian](../../../anlian/) 的主浏览路径与视觉:原站 CSS/JS、首页四段、列表/详情、发帖门禁、聊天室、专题、搜索入口、API 指南。
|
||||
|
||||
默认 **SQLite**(`data/anlian-mq.db`);生产可换 `postgres://` + Redis。
|
||||
|
||||
## 设计约定
|
||||
|
||||
| 做 | 不做 |
|
||||
|----|------|
|
||||
| GFM 表装配库表/种子/表单/门禁/头资源 | `json.set` 链拼页面 |
|
||||
| 原站 `public/css|js|img` + DOM class 对齐 | 另起一套模板糊弄验收 |
|
||||
| `页面.壳HTML` 挂 Django 级导航/页脚 | 业务写进 Go 插件 |
|
||||
| 缺能力时改 `ext/web` / `libweb` | 在应用层堆不可读胶水 |
|
||||
|
||||
## 路径(对齐原站)
|
||||
|
||||
| 路径 | 能力 |
|
||||
|------|------|
|
||||
| `/` | Hero + 公告 + 新闻时间线 + 论坛板块栏/卡片 |
|
||||
| `/post`、`/post/{slug}` | 帖子列表 / 详情 |
|
||||
| `/news`、`/news/{slug}` | 新闻列表 / 详情 |
|
||||
| `/post/public` | 发帖(需登录) |
|
||||
| `/post/ten`、`/news/five` | 首页 AJAX 片段 |
|
||||
| `/chat`、`/chat/lobby`、`/chat/casual` | 房间列表 + 公聊 WS |
|
||||
| `/topics` | 专题书架 |
|
||||
| `/search` | 搜索入口 |
|
||||
| `/guide/automation-api` | API 指南 |
|
||||
| `/accounts/login` | 粉玻璃登录 |
|
||||
| `/sitemap.xml`、`/robots.txt` | 站长 |
|
||||
|
||||
## 运行
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/.local/go/bin:$PATH"
|
||||
./scripts/build-web-plugin.sh
|
||||
export MARQDO_WEB_PLUGIN=$PWD/plugins/web/build/libweb.so
|
||||
rm -f examples/anlian-mq/data/anlian-mq.db* # 首次或改 schema 后
|
||||
./target/debug/marqdo run examples/anlian-mq/index.mq.md
|
||||
# → http://127.0.0.1:18180/
|
||||
|
||||
bash examples/anlian-mq/smoke.sh
|
||||
```
|
||||
|
||||
默认账号:`admin` / `anlian`。
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/chrome
|
||||
description: 暗恋见君壳层 — head 资源表、导航 HTML、页脚 HTML(对齐 Django base / site_footer)。
|
||||
---
|
||||
|
||||
## 头资源
|
||||
|
||||
首页与浏览页共用的 CSS / JS 链接表(挂到 `页面.头装配`)。路径对齐 `public/` 静态树。
|
||||
|
||||
`头` =
|
||||
|
||||
| 关系 | 地址 | 推迟 |
|
||||
|------|------|------|
|
||||
| stylesheet | "/static/vendor/bootstrap-anlian.min.css" | |
|
||||
| stylesheet | "/static/css/base.css" | |
|
||||
| stylesheet | "/static/css/navbar_search.css" | |
|
||||
| stylesheet | "/static/css/footer.css" | |
|
||||
| stylesheet | "/static/css/icons.css" | |
|
||||
| stylesheet | "/static/css/feed_common.css" | |
|
||||
| stylesheet | "/static/css/feed_list.css" | |
|
||||
| stylesheet | "/static/css/index.css" | |
|
||||
| stylesheet | "/static/css/index/hero.css" | |
|
||||
| stylesheet | "/static/css/index/notice.css" | |
|
||||
| stylesheet | "/static/css/index/home_news_timeline.css" | |
|
||||
| stylesheet | "/static/css/index/home_posts.css" | |
|
||||
| stylesheet | "/static/css/anlian_forms.css" | |
|
||||
| stylesheet | "/static/css/login.css" | |
|
||||
| stylesheet | "/static/css/rich_content.css" | |
|
||||
| stylesheet | "/static/css/detail_reading.css" | |
|
||||
| stylesheet | "/static/css/search.css" | |
|
||||
| stylesheet | "/static/css/chat.css" | |
|
||||
| stylesheet | "/static/css/topic_index.css" | |
|
||||
| script | "/static/vendor/bootstrap.bundle.min.js" | 真 |
|
||||
| script | "/static/js/anlian_partial.js" | 真 |
|
||||
| script | "/static/js/feed_board.js" | 真 |
|
||||
| script | "/static/js/index.js" | 真 |
|
||||
|
||||
*`头`*
|
||||
|
||||
## 导航HTML
|
||||
|
||||
对齐 Django `front/base.html` 顶栏:品牌「暗恋见君论坛」、主导航、搜索、登录/退出(`nav-when-guest` / `nav-when-auth` 由 CSS/JS 切换)。
|
||||
|
||||
**"<nav class=\"navbar navbar-expand-lg navbar-dark bg-dark\"><div class=\"container-fluid navbar-shell\"><div class=\"navbar-start\"><div class=\"navbar-logo\"><img src=\"/static/img/logo.svg\" alt=\"logo\" width=\"30\" height=\"30\" decoding=\"async\"></div><a class=\"navbar-brand\" href=\"/\">暗恋见君论坛</a></div><button class=\"navbar-toggler\" type=\"button\" data-bs-toggle=\"collapse\" data-bs-target=\"#navbarNav\" aria-controls=\"navbarNav\" aria-expanded=\"false\" aria-label=\"Toggle navigation\"><span class=\"navbar-toggler-icon\"></span></button><div class=\"collapse navbar-collapse\" id=\"navbarNav\"><ul class=\"navbar-nav navbar-nav-main\"><li class=\"nav-item\"><a class=\"nav-link\" href=\"/\">首页</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/post\">帖子</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/news\">新闻</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/topics\">专题</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/chat\">聊天</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/post/public\">发帖</a></li></ul><div class=\"navbar-end\"><form class=\"navbar-search d-flex\" action=\"/search\" method=\"get\" role=\"search\"><input class=\"form-control\" type=\"search\" name=\"q\" placeholder=\"搜索帖子、新闻、用户\" aria-label=\"搜索\" maxlength=\"100\" autocomplete=\"off\"><button class=\"btn btn-search-submit\" type=\"submit\">搜索</button></form><ul class=\"navbar-nav navbar-auth\"><li class=\"nav-item nav-when-guest\"><a class=\"nav-link nav-link-auth\" href=\"/accounts/login\">登录</a></li><li class=\"nav-item nav-when-auth\"><a class=\"nav-link nav-link-btn\" href=\"/admin/logout\">退出</a></li></ul></div></div></div></nav>"**
|
||||
|
||||
## 页脚HTML
|
||||
|
||||
对齐 `site_footer`:站点列 + 作者列;标语、版权、API 指南、作者 cflmy。
|
||||
|
||||
**"<footer class=\"site-footer\"><div class=\"site-footer-inner\"><div class=\"footer-col footer-col-site\"><img src=\"/static/img/logo.svg\" alt=\"\" class=\"footer-site-logo\" width=\"40\" height=\"40\" loading=\"lazy\"><p class=\"footer-site-name\">暗恋见君论坛</p><p class=\"footer-site-tagline\">期待人们能够继续相信爱情</p><p class=\"footer-copy\">© 2026 暗恋见君论坛</p><p class=\"footer-meta-sm footer-api-guide\"><a href=\"/guide/automation-api\" class=\"footer-guide-btn\" title=\"面向开发者的 API Key 与自动化对接说明\"><span class=\"anlian-icon anlian-icon--book\" aria-hidden=\"true\"><svg viewBox=\"0 0 24 24\" xmlns=\"http://www.w3.org/2000/svg\" focusable=\"false\" aria-hidden=\"true\"><path d=\"M6 2a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V4a2 2 0 0 0-2-2H6Zm0 2h5v7.5L8.5 10 6 11.5V4Zm7 0h5v16h-5V4Z\"/></svg></span> API 自动化指南</a></p></div><div class=\"footer-col footer-col-author\"><img src=\"/static/img/author_avatar-144.webp\" alt=\"\" class=\"footer-author-avatar\" width=\"72\" height=\"72\" loading=\"lazy\"><div class=\"footer-author-info\"><p class=\"footer-author-name\">cflmy</p><p class=\"footer-author-title\">站长</p></div></div></div></footer>"**
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/feed
|
||||
description: 帖子列表 / 新闻时间线 / 板块栏 HTML 片段(对齐 Django feed 与 home 局部模板)。
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
## 帖子列表HTML
|
||||
+ `行`
|
||||
|
||||
给定帖子行记录列表,输出 `ul.home-posts-list` 标记(首页与列表页共用)。
|
||||
|
||||
**段 = None**
|
||||
- [帖](遍历 行 为 帖)
|
||||
**板 = [board](access(帖, "board"))**
|
||||
**题 = [title](access(帖, "title"))**
|
||||
**链 = [slug](access(帖, "slug"))**
|
||||
**作 = [author](access(帖, "author"))**
|
||||
**评 = [comments_count](access(帖, "comments_count"))**
|
||||
**时 = [created_at](access(帖, "created_at"))**
|
||||
1. not 作
|
||||
**作 = "匿名"**
|
||||
2. *
|
||||
1. not 评
|
||||
**评 = 0**
|
||||
2. *
|
||||
1. not 时
|
||||
**时 = ""**
|
||||
2. *
|
||||
**一项 = "<li><article class=\"home-post-card feed-post-card\"><a href=\"/post/" + 链 + "\" class=\"home-post-card-link feed-post-card-link\"><span class=\"home-post-board feed-post-board\">" + 板 + "</span><div class=\"home-post-body feed-post-body\"><h3 class=\"home-post-title feed-post-title\">" + 题 + "</h3><div class=\"home-post-meta feed-post-meta\"><span class=\"home-post-meta-item feed-post-meta-item\"><span class=\"anlian-icon anlian-icon--user\" aria-hidden=\"true\"></span> " + 作 + "</span><span class=\"home-post-meta-item feed-post-meta-item\"><span class=\"anlian-icon anlian-icon--comment\" aria-hidden=\"true\"></span> " + 评 + "</span><time>" + 时 + "</time></div></div><span class=\"home-post-arrow feed-post-arrow\" aria-hidden=\"true\"><span class=\"anlian-icon anlian-icon--chevron-right\"></span></span></a></article></li>"**
|
||||
**段 = > table.append list=段 item=一项**
|
||||
1. 段
|
||||
**内 = > text.str_join xs=段 sep=""**
|
||||
*"<ul class=\"home-posts-list feed-posts-list\">" + 内 + "</ul>"*
|
||||
2. *
|
||||
*"<ul class=\"home-posts-list feed-posts-list\"><li class=\"home-posts-empty feed-empty\">暂无帖子,<a href=\"/post/public\">去发帖</a></li></ul>"*
|
||||
|
||||
## 新闻时间线HTML
|
||||
+ `行`
|
||||
|
||||
给定新闻行记录列表,输出 `.news-timeline` 标记。
|
||||
|
||||
**段 = None**
|
||||
- [讯](遍历 行 为 讯)
|
||||
**题 = [title](access(讯, "title"))**
|
||||
**链 = [slug](access(讯, "slug"))**
|
||||
**板 = [board](access(讯, "board"))**
|
||||
**时 = [created_at](access(讯, "created_at"))**
|
||||
1. not 板
|
||||
**板 = ""**
|
||||
2. *
|
||||
1. not 时
|
||||
**时 = ""**
|
||||
2. *
|
||||
**一项 = "<li class=\"news-timeline-item\"><span class=\"news-timeline-node\" aria-hidden=\"true\"></span><article class=\"news-timeline-card\"><div class=\"news-timeline-meta\"><time class=\"news-timeline-date\">" + 时 + "</time><span class=\"news-timeline-board\">" + 板 + "</span></div><h3 class=\"news-timeline-title\"><a href=\"/news/" + 链 + "\" class=\"news-timeline-link\">" + 题 + "</a></h3></article></li>"**
|
||||
**段 = > table.append list=段 item=一项**
|
||||
1. 段
|
||||
**内 = > text.str_join xs=段 sep=""**
|
||||
*"<div class=\"news-timeline\"><div class=\"news-timeline-rail\" aria-hidden=\"true\"><span class=\"news-timeline-line\"></span><span class=\"news-timeline-arrow\" aria-hidden=\"true\"><span class=\"anlian-icon anlian-icon--chevron-right news-timeline-arrow-icon--right\"></span><span class=\"anlian-icon anlian-icon--chevron-down news-timeline-arrow-icon--down\"></span></span></div><ol class=\"news-timeline-items\">" + 内 + "</ol></div>"*
|
||||
2. *
|
||||
*"<div class=\"news-timeline\"><div class=\"news-timeline-rail\" aria-hidden=\"true\"><span class=\"news-timeline-line\"></span><span class=\"news-timeline-arrow\" aria-hidden=\"true\"></span></div><ol class=\"news-timeline-items\"><li class=\"news-timeline-item news-timeline-item-empty\"><article class=\"news-timeline-card\"><p class=\"news-timeline-empty\">暂无新闻</p></article></li></ol></div>"*
|
||||
|
||||
## 板块栏HTML
|
||||
+ `板块`
|
||||
+ `前缀`
|
||||
+ `查询键`
|
||||
+ `全部类`
|
||||
|
||||
板块 Tab 栏。`前缀` 如 `/post/ten/`;`查询键` 为 `board_id` 或 `news_board_id`;`全部类` 为 Tab 共用 class(含 js hook)。
|
||||
|
||||
**数据属 = "data-board"**
|
||||
**全标签 = "全部"**
|
||||
1. 查询键 == "news_board_id"
|
||||
**数据属 = "data-news-board"**
|
||||
**全标签 = "所有板块"**
|
||||
2. *
|
||||
|
||||
**段 = None**
|
||||
**全链 = 前缀 + "?" + 查询键 + "=0"**
|
||||
**全项 = "<a href=\"" + 全链 + "\" class=\"" + 全部类 + " active\" " + 数据属 + "=\"0\">" + 全标签 + "</a>"**
|
||||
**段 = > table.append list=段 item=全项**
|
||||
- [板](遍历 板块 为 板)
|
||||
**名 = [name](access(板, "name"))**
|
||||
**号 = [id](access(板, "id"))**
|
||||
**链 = 前缀 + "?" + 查询键 + "=" + 号**
|
||||
**项 = "<a href=\"" + 链 + "\" class=\"" + 全部类 + "\" " + 数据属 + "=\"" + 号 + "\">" + 名 + "</a>"**
|
||||
**段 = > table.append list=段 item=项**
|
||||
1. 查询键 == "news_board_id"
|
||||
**更多 = "<a href=\"/news\" class=\"home-posts-tab home-posts-tab-more\">全部新闻</a>"**
|
||||
**段 = > table.append list=段 item=更多**
|
||||
2. *
|
||||
**内 = > text.str_join xs=段 sep=""**
|
||||
**栏类 = "home-posts-board-bar"**
|
||||
1. 查询键 == "news_board_id"
|
||||
**栏类 = "home-posts-board-bar home-news-board-bar"**
|
||||
2. *
|
||||
*"<div class=\"" + 栏类 + "\" data-feed-board><button type=\"button\" class=\"home-posts-scroll home-posts-scroll-left\" aria-label=\"向左滚动\"><span class=\"anlian-icon anlian-icon--chevron-left\"></span></button><div class=\"home-posts-segment-outer\"><div class=\"home-posts-segment\"><div class=\"home-posts-spotlight\" aria-hidden=\"true\"></div><div class=\"home-posts-tabs-scroll\"><div class=\"home-posts-tabs\" role=\"tablist\">" + 内 + "</div></div></div></div><button type=\"button\" class=\"home-posts-scroll home-posts-scroll-right\" aria-label=\"向右滚动\"><span class=\"anlian-icon anlian-icon--chevron-right\"></span></button></div>"*
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## 页脚
|
||||
|
||||
站点信息与站长链接(毛玻璃底由壳样式绘制)。
|
||||
|
||||
`页脚` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| 暗恋见君 · 期待人们能够继续相信爱情 | / |
|
||||
| 帖子 | /posts |
|
||||
| 新闻 | /news |
|
||||
| 公聊 | /chat |
|
||||
| sitemap | /sitemap.xml |
|
||||
|
||||
*`页脚`*
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/fragments
|
||||
description: AJAX 片段 — /post/ten、/news/five。
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
db: ../db/index.mq.md
|
||||
feed: feed.mq.md
|
||||
---
|
||||
|
||||
## 帖子十
|
||||
+ `board_id`="0"
|
||||
|
||||
**store = > db.打开**
|
||||
**行 = > store.查询 表="posts" 上限=10 排序="-created_at"**
|
||||
*> feed.帖子列表HTML 行=`行`*
|
||||
|
||||
## 新闻五
|
||||
+ `news_board_id`="0"
|
||||
|
||||
**store = > db.打开**
|
||||
**行 = > store.查询 表="news" 上限=5 排序="-created_at"**
|
||||
*> feed.新闻时间线HTML 行=`行`*
|
||||
@@ -1,9 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## 首页引言
|
||||
|
||||
英雄区 HTML(品牌标语 + CTA + 漂浮主图)。样式在 `styles/shell` 的 Hero / 动效表。
|
||||
|
||||
**"<section class=\"hero\" aria-label=\"暗恋见君\"><div class=\"hero-content\"><div class=\"hero-left\"><p class=\"hero-brand\"><img class=\"hero-logo\" src=\"/static/logo.svg\" alt=\"\" width=\"30\" height=\"30\"><span>暗恋<span class=\"hero-pink\">见君</span></span></p><h1 class=\"main-text\">期待人们能够继续相信<span class=\"hero-pink\">爱情</span></h1><p class=\"sub-text\">粉玻璃、呼吸 Logo、漂浮主图——用 Marqdo 表格装配的社区站点,验收「代码即文档」能否撑起真实前端。</p><p class=\"hero-cta\"><a class=\"hero-btn\" href=\"/posts\">浏览帖子</a><a class=\"hero-btn ghost\" href=\"/news\">新闻</a><a class=\"hero-btn ghost\" href=\"/chat\">公聊</a></p></div><div class=\"hero-right\"><img class=\"hero-art\" src=\"/static/bg-hero-640.webp\" alt=\"暗恋见君\"></div></div></section><div class=\"home-feed-head\"><h2>最新帖子</h2><p>来自粉玻璃卡片流</p></div>"**
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/home_body
|
||||
description: 首页主体 HTML — hero + 公告 + 新闻时间线 + 论坛帖子(对齐 Django home.html,无外层导航)。
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
table: lib/table.mq.md
|
||||
text: lib/text.mq.md
|
||||
feed: feed.mq.md
|
||||
---
|
||||
|
||||
## 装配
|
||||
+ `库`
|
||||
|
||||
查询 notices / boards / news_boards / news(5) / posts(10),拼装首页四段 HTML(不含导航与页脚)。调用方传入已打开的 store。
|
||||
|
||||
**公告行 = > 库.查询 表="notices" 上限=20 排序="-created_at"**
|
||||
**板块行 = > 库.查询 表="boards" 上限=50**
|
||||
**新闻板块行 = > 库.查询 表="news_boards" 上限=50**
|
||||
**新闻行 = > 库.查询 表="news" 上限=5 排序="-created_at"**
|
||||
**帖子行 = > 库.查询 表="posts" 上限=10 排序="-created_at"**
|
||||
|
||||
**公告段 = None**
|
||||
- [告](遍历 公告行 为 告)
|
||||
**文 = [content](access(告, "content"))**
|
||||
**时 = [created_at](access(告, "created_at"))**
|
||||
**一项 = "<div class=\"notice-item\"><article class=\"notice-content\">" + 文 + "</article><p class=\"notice-create-time\">" + 时 + "</p></div>"**
|
||||
**公告段 = > table.append list=公告段 item=一项**
|
||||
1. 公告段
|
||||
**公告内 = > text.str_join xs=公告段 sep=""**
|
||||
2. *
|
||||
**公告内 = "<p class=\"text-muted\">暂无公告</p>"**
|
||||
|
||||
**新闻栏 = > feed.板块栏HTML 板块=新闻板块行 前缀="/news/five" 查询键="news_board_id" 全部类="home-posts-tab js-home-news-tab"**
|
||||
**新闻板 = > feed.新闻时间线HTML 行=新闻行**
|
||||
**帖子栏 = > feed.板块栏HTML 板块=板块行 前缀="/post/ten" 查询键="board_id" 全部类="home-posts-tab js-home-post-tab"**
|
||||
**帖子表 = > feed.帖子列表HTML 行=帖子行**
|
||||
|
||||
**段 = None**
|
||||
**英雄 = "<section class=\"hero\"><div class=\"section-wrap\"><header><img src=\"/static/img/logo.svg\" alt=\"logo\" width=\"30\" height=\"30\" decoding=\"async\"><a class=\"head-logo\" href=\"/\"><span>暗恋</span>见君</a></header><div class=\"hero-content\"><div class=\"left\"><h1 class=\"main-text\">期待人们能够继续相信<span style=\"color:#ffd0d0\">爱情</span></h1><h2 class=\"sub-text\">粉玻璃社区 · 匿名与实名同在</h2></div><div class=\"right\"><img src=\"/static/img/bg-hero-640.webp\" alt=\"首页展示图\" width=\"640\" height=\"482\" fetchpriority=\"high\" decoding=\"async\"></div></div><div class=\"social\"></div></div></section>"**
|
||||
**段 = > table.append list=段 item=英雄**
|
||||
**公告区 = "<section class=\"notice\"><div class=\"section-wrap\"><h2 class=\"notice-title\">公告信息</h2><div class=\"notice-content-container\"><div class=\"notice-list\">" + 公告内 + "</div></div></div></section>"**
|
||||
**段 = > table.append list=段 item=公告区**
|
||||
**新闻区 = "<section class=\"news home-news\" id=\"news\"><div class=\"section-wrap home-news-stage\"><h2 class=\"news-title\">新闻动态</h2>" + 新闻栏 + "<div class=\"news-timeline-wrap\"><div id=\"homeNewsPanel\" class=\"news-timeline-panel home-panel-swap\">" + 新闻板 + "</div></div></div></section>"**
|
||||
**段 = > table.append list=段 item=新闻区**
|
||||
**更多 = "<a href=\"/post\" class=\"home-posts-more-link\">查看更多帖子</a>"**
|
||||
**帖子区 = "<section class=\"home-posts\" id=\"post\"><div class=\"section-wrap home-posts-stage\"><h2 class=\"home-posts-title\">论坛交流</h2>" + 帖子栏 + "<div id=\"tenPostContainer\" class=\"home-posts-panel home-panel-swap\">" + 帖子表 + 更多 + "</div></div></section>"**
|
||||
**段 = > table.append list=段 item=帖子区**
|
||||
*> text.str_join xs=段 sep=""*
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## 导航
|
||||
|
||||
顶栏:首页、帖子、新闻、搜索、聊天、发帖(登录后)、后台。
|
||||
|
||||
`导航` =
|
||||
|
||||
| 属性 | 值 | 样式 | 媒体 | 当 |
|
||||
|------|-----|------|------|-----|
|
||||
| 暗恋见君 | / | | | |
|
||||
| 帖子 | /posts | | | |
|
||||
| 新闻 | /news | | | |
|
||||
| 搜索 | /search | | | |
|
||||
| 聊天 | /chat | | | |
|
||||
| 发帖 | /write | | | auth |
|
||||
| 登录 | /admin/login | | | guest |
|
||||
| 后台 | /admin | | | auth |
|
||||
|
||||
*`导航`*
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: components/page
|
||||
description: 用原站 chrome 包一层完整 HTML 引言(bare 布局)。
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
chrome: chrome.mq.md
|
||||
---
|
||||
|
||||
## 包装
|
||||
+ `正文`
|
||||
+ `体类`=""
|
||||
|
||||
导航 + 正文 + 页脚;体类如 `page-home`。
|
||||
|
||||
**顶 = > chrome.导航HTML**
|
||||
**底 = > chrome.页脚HTML**
|
||||
**鉴权脚本 = "<script>(function(){var c=document.cookie.indexOf('marqdo_sid=')>=0;document.querySelectorAll('.nav-when-guest').forEach(function(el){el.style.display=c?'none':'';});document.querySelectorAll('.nav-when-auth').forEach(function(el){el.style.display=c?'':'none';});})();</script>"**
|
||||
**鉴权样式 = "<style>.nav-when-auth{display:none}</style>"**
|
||||
*鉴权样式 + 顶 + "<main class=\"anlian-main " + 体类 + "\">" + 正文 + "</main>" + 底 + 鉴权脚本*
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: db/index
|
||||
description: 打开库、建全表、幂等种子、帖子全文索引。
|
||||
导入:
|
||||
网页: ext/web/网页.mq.md
|
||||
schema: schema.mq.md
|
||||
seed: seed.mq.md
|
||||
---
|
||||
|
||||
## 打开
|
||||
|
||||
打开 sqlite:data/anlian-mq.db,初始化全部表;帖子建 FTS;若 posts 为空则写入种子。返回 store。
|
||||
|
||||
**store = > 网页.数据库 地址="sqlite:data/anlian-mq.db"**
|
||||
**帖子字段 = > schema.posts**
|
||||
**新闻字段 = > schema.news**
|
||||
**板块字段 = > schema.boards**
|
||||
**新闻板块字段 = > schema.news_boards**
|
||||
**公告字段 = > schema.notices**
|
||||
**评论字段 = > schema.comments**
|
||||
**房间字段 = > schema.chat_rooms**
|
||||
**专题字段 = > schema.topics**
|
||||
**密钥字段 = > schema.api_keys**
|
||||
> `store`.初始化 名=posts 字段=`帖子字段`
|
||||
> `store`.初始化 名=news 字段=`新闻字段`
|
||||
> `store`.初始化 名=boards 字段=`板块字段`
|
||||
> `store`.初始化 名=news_boards 字段=`新闻板块字段`
|
||||
> `store`.初始化 名=notices 字段=`公告字段`
|
||||
> `store`.初始化 名=comments 字段=`评论字段`
|
||||
> `store`.初始化 名=chat_rooms 字段=`房间字段`
|
||||
> `store`.初始化 名=topics 字段=`专题字段`
|
||||
> `store`.初始化 名=api_keys 字段=`密钥字段`
|
||||
|
||||
`全文列` =
|
||||
|
||||
| 列 |
|
||||
|----|
|
||||
| title |
|
||||
| summary |
|
||||
| body |
|
||||
|
||||
> `store`.全文 表=posts 列=`全文列` 名=posts_fts
|
||||
|
||||
**已有 = > store.查询 表="posts" 上限=1**
|
||||
1. `已有`
|
||||
*store*
|
||||
2. *
|
||||
**板块 = > seed.boards**
|
||||
**新闻板块 = > seed.news_boards**
|
||||
**帖子 = > seed.posts**
|
||||
**新闻 = > seed.news**
|
||||
**公告 = > seed.notices**
|
||||
**评论 = > seed.comments**
|
||||
**房间 = > seed.chat_rooms**
|
||||
**专题 = > seed.topics**
|
||||
> `store`.插入 表=boards 行=`板块`
|
||||
> `store`.插入 表=news_boards 行=`新闻板块`
|
||||
> `store`.插入 表=posts 行=`帖子`
|
||||
> `store`.插入 表=news 行=`新闻`
|
||||
> `store`.插入 表=notices 行=`公告`
|
||||
> `store`.插入 表=comments 行=`评论`
|
||||
> `store`.插入 表=chat_rooms 行=`房间`
|
||||
> `store`.插入 表=topics 行=`专题`
|
||||
*store*
|
||||
@@ -1,150 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
## posts
|
||||
|
||||
帖子主表。`slug` 用于详情路径;`board` 为板块显示名,`board_id` 关联 `boards`。
|
||||
|
||||
`posts` =
|
||||
|
||||
| 字段 | 类型 | 可空 | 索引 |
|
||||
|------|------|------|------|
|
||||
| id | integer | false | |
|
||||
| title | text | false | |
|
||||
| slug | text | false | 是 |
|
||||
| summary | text | true | |
|
||||
| body | text | true | |
|
||||
| board | text | true | |
|
||||
| board_id | integer | true | |
|
||||
| author | text | true | |
|
||||
| comments_count | integer | true | |
|
||||
| views | integer | true | |
|
||||
| created_at | timestamp | true | |
|
||||
| updated_at | timestamp | true | |
|
||||
|
||||
*`posts`*
|
||||
|
||||
## news
|
||||
|
||||
新闻主表。`board_id` 关联 `news_boards`;`board` 为板块显示名。
|
||||
|
||||
`news` =
|
||||
|
||||
| 字段 | 类型 | 可空 | 索引 |
|
||||
|------|------|------|------|
|
||||
| id | integer | false | |
|
||||
| title | text | false | |
|
||||
| slug | text | false | 是 |
|
||||
| summary | text | true | |
|
||||
| body | text | true | |
|
||||
| board | text | true | |
|
||||
| board_id | integer | true | |
|
||||
| created_at | timestamp | true | |
|
||||
| updated_at | timestamp | true | |
|
||||
|
||||
*`news`*
|
||||
|
||||
## boards
|
||||
|
||||
帖子板块。
|
||||
|
||||
`boards` =
|
||||
|
||||
| 字段 | 类型 | 可空 | 索引 |
|
||||
|------|------|------|------|
|
||||
| id | integer | false | |
|
||||
| name | text | false | |
|
||||
| slug | text | false | 是 |
|
||||
|
||||
*`boards`*
|
||||
|
||||
## news_boards
|
||||
|
||||
新闻板块。
|
||||
|
||||
`news_boards` =
|
||||
|
||||
| 字段 | 类型 | 可空 | 索引 |
|
||||
|------|------|------|------|
|
||||
| id | integer | false | |
|
||||
| name | text | false | |
|
||||
| slug | text | false | 是 |
|
||||
|
||||
*`news_boards`*
|
||||
|
||||
## notices
|
||||
|
||||
首页公告。
|
||||
|
||||
`notices` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| content | text | false |
|
||||
| created_at | timestamp | true |
|
||||
|
||||
*`notices`*
|
||||
|
||||
## comments
|
||||
|
||||
评论(按目标类型 + slug 挂接)。
|
||||
|
||||
`comments` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| target_type | text | false |
|
||||
| target_slug | text | false |
|
||||
| body | text | false |
|
||||
| author | text | true |
|
||||
| created_at | timestamp | true |
|
||||
|
||||
*`comments`*
|
||||
|
||||
## chat_rooms
|
||||
|
||||
公聊房间。
|
||||
|
||||
`chat_rooms` =
|
||||
|
||||
| 字段 | 类型 | 可空 | 索引 |
|
||||
|------|------|------|------|
|
||||
| id | integer | false | |
|
||||
| slug | text | false | 是 |
|
||||
| name | text | false | |
|
||||
| summary | text | true | |
|
||||
|
||||
*`chat_rooms`*
|
||||
|
||||
## topics
|
||||
|
||||
专题占位。
|
||||
|
||||
`topics` =
|
||||
|
||||
| 字段 | 类型 | 可空 | 索引 |
|
||||
|------|------|------|------|
|
||||
| id | integer | false | |
|
||||
| slug | text | false | 是 |
|
||||
| title | text | false | |
|
||||
| summary | text | true | |
|
||||
|
||||
*`topics`*
|
||||
|
||||
## api_keys
|
||||
|
||||
API Key 校验用哈希表(应用层 scopes)。
|
||||
|
||||
`api_keys` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| name | text | false |
|
||||
| hash | text | false |
|
||||
| scopes | text | true |
|
||||
|
||||
*`api_keys`*
|
||||