Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
24959a0ba8 | ||
|
|
afbb9f191c | ||
|
|
8db699191e | ||
|
|
e5580d9640 | ||
|
|
9ce2ae1037 | ||
|
|
166b01c86b | ||
|
|
87cfe05095 | ||
|
|
b37387e6da | ||
|
|
895752a1fd | ||
|
|
38c07d9a0e | ||
|
|
a7a5554c0f | ||
|
|
343504c7a8 | ||
|
|
3d9fa0da96 | ||
|
|
bb8960c5eb | ||
|
|
9331af78e2 | ||
|
|
73bf574a55 | ||
|
|
4fae71342d | ||
|
|
63d60e3ba1 | ||
|
|
44d2928c06 | ||
|
|
fa832268b3 | ||
|
|
9576188a2e | ||
|
|
528a1f0dbc | ||
|
|
a11b347659 | ||
|
|
8e437e2cd3 | ||
|
|
23229a6ac9 | ||
|
|
58b65215a1 | ||
|
|
92c3f80055 | ||
|
|
8a66f803cb | ||
|
|
3ce59a4da8 | ||
|
|
90688741c5 | ||
|
|
70b88b3767 | ||
|
|
f859e6eeea | ||
|
|
6705e2e6b7 | ||
|
|
6e8a62928b | ||
|
|
398a0b7222 | ||
|
|
e8f1a3e126 | ||
|
|
8ea56cbe30 | ||
|
|
8085d06124 | ||
|
|
6f929dc2da | ||
|
|
dd22180269 | ||
|
|
cc48bf6d05 | ||
|
|
19f986953a | ||
|
|
770dee5199 | ||
|
|
f6612813e3 | ||
|
|
643ea06340 | ||
|
|
0cd64a7450 | ||
|
|
981faac022 | ||
|
|
f818834ec1 | ||
|
|
8d47507d15 | ||
|
|
1e1f05c087 | ||
|
|
06e61efc51 | ||
|
|
2dfa0b2a5b | ||
|
|
629ad8ed39 | ||
|
|
ee677478be | ||
|
|
edbf241d99 | ||
|
|
add6a7d32c | ||
|
|
c64ec99115 | ||
|
|
60a3b84a84 | ||
|
|
02a4f2d20d | ||
|
|
88490e3092 | ||
|
|
9031c106a1 | ||
|
|
633436e40f | ||
|
|
cf73fcf1ef | ||
|
|
e48fd5b0f4 | ||
|
|
b2f97e72c3 | ||
|
|
c7c0f66d1f | ||
|
|
d5ab9daebb | ||
|
|
5795236d1f | ||
|
|
e8d6dc92fc | ||
|
|
afe31cb2a8 | ||
|
|
905a67df32 | ||
|
|
f63b7ef48d | ||
|
|
393558ca97 | ||
|
|
0d9bd99fc0 | ||
|
|
a0c779e022 | ||
|
|
a82b6fdde1 | ||
|
|
3613ed7c4e | ||
|
|
9564dff777 | ||
|
|
f56deffefe | ||
|
|
bdedf3ecd8 | ||
|
|
b0ee958fcf | ||
|
|
e64f6b23b4 | ||
|
|
eed4f05ea4 | ||
|
|
d88ed274ed | ||
|
|
7fdd97f675 | ||
|
|
c299efe589 | ||
|
|
b3867c46db | ||
|
|
1a39a53d93 | ||
|
|
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 | ||
|
|
3cabe53da2 | ||
|
|
58e13ee6d3 | ||
|
|
1b11fe063a | ||
|
|
b792f44556 | ||
|
|
9ea5bebfc3 | ||
|
|
c7c329341b | ||
|
|
8cf5288481 | ||
|
|
69c4e74872 | ||
|
|
af0bda2e40 | ||
|
|
090b026547 | ||
|
|
03396afd02 | ||
|
|
663a8ba2c0 | ||
|
|
dc853fb580 | ||
|
|
0b80ff8e50 | ||
|
|
b8a4ddd38f | ||
|
|
352bc0d2c5 | ||
|
|
8a6d09d582 | ||
|
|
dcd3d329d4 | ||
|
|
0e1bfb3359 | ||
|
|
e9ae7ff1ae | ||
|
|
ecbdd18303 | ||
|
|
bedd53e212 | ||
|
|
7674ebb869 | ||
|
|
434be9fd52 | ||
|
|
ae97891266 | ||
|
|
aea86746e7 | ||
|
|
c773503938 | ||
|
|
939e23ee88 | ||
|
|
687c168014 | ||
|
|
eac9b45263 | ||
|
|
74b298e80d | ||
|
|
fc7097bae4 | ||
|
|
b624084745 | ||
|
|
0bbe735c3c | ||
|
|
92de46aca4 | ||
|
|
8bbe017a5e | ||
|
|
1a13989230 | ||
|
|
5ad1a07f5c | ||
|
|
bcfc763ba4 |
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 `import browser:lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
|
||||
|
||||
## Developing libraries (`lib/*`, `ext/*`)
|
||||
|
||||
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 `import json:…` if unused.
|
||||
|
||||
## 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,209 +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.
|
||||
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.
|
||||
|
||||
## 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): both `windows` and `linux` green when ext natives required.
|
||||
2. Rewrite release body 中英双语 — [reference.md § Notes](reference.md).
|
||||
3. Confirm Linux `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` when mode ships ext.
|
||||
|
||||
## Phase 6 — Extension CDN (R2) — required when ext ships
|
||||
|
||||
```bash
|
||||
# credentials: ~/.marqdo/r2.env (never commit)
|
||||
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
|
||||
curl -fsS https://ext.marqdo.com/latest/VERSION
|
||||
```
|
||||
|
||||
Also ensure the **same** zips are on GitHub (`vVER` or `ext-vVER`). If R2 credentials missing, **tell the user**:
|
||||
|
||||
```bash
|
||||
# put keys in ~/.marqdo/r2.env then:
|
||||
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
|
||||
```
|
||||
|
||||
## Phase 7 — Ubuntu PPA (full/cli)
|
||||
|
||||
Linux CLI for apt users. After `Cargo.toml` is at `VER` and `debian/changelog` has a matching `VER-1ppaN` stanza:
|
||||
|
||||
```bash
|
||||
./scripts/ppa-ship.sh noble
|
||||
```
|
||||
|
||||
Packaging notes / noble Cargo.lock v4: [ubuntu-ppa.md](../../../doc/design/ubuntu-ppa.md).
|
||||
|
||||
**If the agent cannot sudo / sign / dput**, print exactly:
|
||||
|
||||
```bash
|
||||
cd ~/work/marqdo
|
||||
./scripts/ppa-ship.sh noble
|
||||
# or build then upload:
|
||||
./scripts/ppa-build-source.sh noble
|
||||
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
|
||||
```
|
||||
|
||||
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
|
||||
On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `1ppaN`, re-upload. Tell the user the new `dput` command.
|
||||
|
||||
## Phase 8 — Post-release
|
||||
|
||||
1. `gh release view TAG` — assets + notes.
|
||||
2. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
|
||||
3. PPA build green (if cli shipped).
|
||||
4. Tell user URLs: GitHub release, CDN, PPA install one-liner.
|
||||
5. Optional gh-pages only if asked.
|
||||
|
||||
## Extension-only release (mode=ext)
|
||||
|
||||
1. User confirms **ext** SemVer (may differ from CLI).
|
||||
2. Bump `ext/VERSION`; CHANGELOG → `## Ext pack vVER`.
|
||||
3. Build/package `marqdo-VER-ext.zip` + `marqdo-VER-native-*.zip` (CI or local).
|
||||
4. Upload to **R2 and GitHub** (required both).
|
||||
5. Do **not** retag CLI / do **not** PPA unless user also asked for cli.
|
||||
|
||||
## Failure matrix (short)
|
||||
|
||||
| Failure | Action |
|
||||
|---------|--------|
|
||||
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; see [reference § Proxy](reference.md) |
|
||||
| GitHub blocked | proxy.cflmy.top, then HK jump; **print commands** if agent cannot push |
|
||||
| Tag exists | Stop; ask user |
|
||||
| CI red | Fix on main; retag only if user allows |
|
||||
| R2 upload fails | Print `upload-ext-r2.py` command; do not skip silently |
|
||||
| PPA / sudo / GPG | Print `./scripts/ppa-ship.sh noble` (or `dput …`); do not skip silently |
|
||||
| Launchpad `Cargo.lock` v4 / old cargo | Ensure bundled `third_party/rust` via current `ppa-build-source.sh`; bump `1ppaN` |
|
||||
| Linux native zip missing (full/ext) | Incomplete — fix linux job or upload |
|
||||
|
||||
## Do not
|
||||
|
||||
- Ship without user-confirmed version (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,397 +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).
|
||||
|
||||
### 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,270 +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 -->
|
||||
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
## CORE SYNTAX
|
||||
|
||||
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
|
||||
|
||||
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
|
||||
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. In `markup: occlusion` files read with **`access(map, key)`** — there `[x](y)` is occlusion, not index. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
|
||||
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
|
||||
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
|
||||
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
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.
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
|
||||
| `##` … `######` | **Function / method** (nesting by heading depth). |
|
||||
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
|
||||
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
|
||||
| `- [item](coll)` | Foreach (unchanged) |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
|---|---|
|
||||
| `**…**` | Statement (assign / call / expression) |
|
||||
| `*…*` | Return |
|
||||
| `[intent](payload)` | Readable intent with executable payload |
|
||||
| `access(c, k)` | Collection read |
|
||||
| `- [intent](for items as item)` | Explicit traversal |
|
||||
| `1.` / `2.` | Branches; numbered * is else |
|
||||
| GFM table | Data: one column list, one row record, @ row records |
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
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.
|
||||
|
||||
## Occlusion syntax (v2.0.0)
|
||||
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.
|
||||
|
||||
A file with frontmatter `markup: occlusion` (or `标记: 遮蔽`) reads `[x](y)` as **occlusion**, not index — in that file only (`MARQDO_MARKUP=occlusion` sets the process default; classic files are unchanged).
|
||||
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.
|
||||
|
||||
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
|
||||
- `[顾客留存率](0.42)` · `[总价](at(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
|
||||
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
|
||||
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
|
||||
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
|
||||
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
|
||||
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 `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
import text:lib/text.mq.md
|
||||
import 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,469 +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
|
||||
import 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
|
||||
import 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
|
||||
import 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,204 +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,50 @@
|
||||
name: executable-knowledge
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Build agent + llm plugins (EK / workbench gates)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_agent --locked
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
- name: Native agent choice and bounded recovery unit tests
|
||||
run: cargo test -p marqdo_plugin_agent --locked
|
||||
- name: Check short AI flow documents
|
||||
run: |
|
||||
cargo run --locked -- check ext/ai/flow.mq.md
|
||||
cargo run --locked -- check ext/ai/recovery.mq.md
|
||||
cargo run --locked -- check ext/ai/context.mq.md
|
||||
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
|
||||
cargo run --locked -- check ext/ai/workflow.mq.md
|
||||
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
|
||||
- name: Native AI flow interpreter smoke (offline)
|
||||
env:
|
||||
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
|
||||
run: |
|
||||
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
|
||||
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
|
||||
- name: Workbench contracts (M00–M06 / F-subset)
|
||||
run: cargo test --test workbench_contracts --locked
|
||||
- name: Offline executable-knowledge gate
|
||||
run: cargo test --test executable_knowledge --locked
|
||||
- name: Isolated execute MR-01 (dual 60s SSE + short reads)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
bash scripts/build-web-plugin.sh
|
||||
cargo test --test isolated_execute_mr01 --locked -- --nocapture
|
||||
timeout-minutes: 5
|
||||
- name: no ignored tests counted as success
|
||||
run: |
|
||||
if grep -n '#\[ignore\]' tests/executable_knowledge.rs; then
|
||||
echo "executable_knowledge must not use #[ignore] as success evidence" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "ok: no #[ignore] in executable_knowledge gate"
|
||||
@@ -0,0 +1,80 @@
|
||||
# Independent extension sources and native libraries; no CLI/PPA publication.
|
||||
name: Extension Release
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: Extension version to validate
|
||||
required: true
|
||||
type: string
|
||||
push:
|
||||
branches:
|
||||
- codex/ext-release-validation
|
||||
tags:
|
||||
- "ext-v*"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
windows:
|
||||
runs-on: windows-latest
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
GITHUB_REF_NAME_OVERRIDE: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || format('ext-v{0}', inputs.version || '2.8.1') }}
|
||||
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: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
GITHUB_REF_NAME="$GITHUB_REF_NAME_OVERRIDE" ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json
|
||||
- name: Attach source and Windows native packs without replacement
|
||||
if: startsWith(github.ref, 'refs/tags/ext-v')
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
./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 }}
|
||||
GITHUB_REF_NAME_OVERRIDE: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || format('ext-v{0}', inputs.version || '2.8.1') }}
|
||||
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: GITHUB_REF_NAME="$GITHUB_REF_NAME_OVERRIDE" target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json
|
||||
- name: Attach Linux native pack without replacement
|
||||
if: startsWith(github.ref, 'refs/tags/ext-v')
|
||||
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,40 @@
|
||||
name: native-ai-flow
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- feat/native-ai-flow-recovery-20261118
|
||||
pull_request:
|
||||
paths:
|
||||
- 'plugins/agent/**'
|
||||
- 'ext/ai/flow.mq.md'
|
||||
- 'ext/ai/context.mq.md'
|
||||
- 'ext/ai/recovery.mq.md'
|
||||
- 'ext/ai/workflow.mq.md'
|
||||
- 'tests/ext/ai-native-*.mq.md'
|
||||
- '.github/workflows/native-ai-flow.yml'
|
||||
|
||||
jobs:
|
||||
agent:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Build the agent plugin
|
||||
run: cargo build -p marqdo_plugin_agent --locked
|
||||
- name: Run native agent and workflow tests
|
||||
run: cargo test -p marqdo_plugin_agent --locked
|
||||
- name: Check the public Marqdo ABI libraries
|
||||
run: |
|
||||
cargo run --locked -- check ext/ai/flow.mq.md
|
||||
cargo run --locked -- check ext/ai/context.mq.md
|
||||
cargo run --locked -- check ext/ai/recovery.mq.md
|
||||
cargo run --locked -- check ext/ai/workflow.mq.md
|
||||
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
|
||||
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
|
||||
- name: Exercise offline integration through Marqdo
|
||||
env:
|
||||
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
|
||||
run: |
|
||||
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
|
||||
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
|
||||
@@ -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
|
||||
@@ -0,0 +1,115 @@
|
||||
# 判定流水线(marqdo prove)
|
||||
#
|
||||
# 验证「SKILL 编排文档 → Lean 4 → 自动证明」全链路:
|
||||
# 1. 构建内置 Lean 底座(MarqdoProof.lean)。
|
||||
# 2. 跑判定矩阵(tests/prove_lean.rs):真定理 proved、假定理 unproved、
|
||||
# 证书缓存命中跳判定、--require-lean 退出码。
|
||||
# 3. CI 硬性要求(MARQDO_PROOF_REQUIRE_LEAN=1):没有工具链即失败,
|
||||
# 不允许悄悄降级成 unverified。
|
||||
#
|
||||
# 说明:仓库不强制贡献者装 Lean——本工作流在装有 elan 的 runner 上运行;
|
||||
# 本地无 Lean 时判定状态为 unverified(advisory,不阻塞)。
|
||||
name: proof
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "src/prove/**"
|
||||
- "doc/verification/skill-proof/**"
|
||||
- "lib/**"
|
||||
- "tests/prove*.rs"
|
||||
- ".github/workflows/proof.yml"
|
||||
pull_request:
|
||||
paths:
|
||||
- "src/prove/**"
|
||||
- "doc/verification/skill-proof/**"
|
||||
- "lib/**"
|
||||
- "tests/prove*.rs"
|
||||
- ".github/workflows/proof.yml"
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
proof:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust (1.81)
|
||||
run: |
|
||||
rustup toolchain install 1.81.0 --profile minimal
|
||||
rustup default 1.81.0
|
||||
|
||||
# leanprover/lean-action@v1 已移除 lean4-version;本仓库运行时只需 lean 二进制
|
||||
# (底座内嵌、不经 lake)。用 elan 钉 v4.35.0,与 doc/verification/skill-proof/lean-toolchain 一致。
|
||||
- name: Install Lean 4.35.0 (elan)
|
||||
run: |
|
||||
curl -sSf https://elan.lean-lang.org/elan-init.sh | sh -s -- -y --default-toolchain leanprover/lean4:v4.35.0
|
||||
echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
|
||||
"$HOME/.elan/bin/lean" --version
|
||||
|
||||
- name: Verify embedded proof library
|
||||
run: |
|
||||
chmod +x scripts/check-proof-library.sh
|
||||
scripts/check-proof-library.sh
|
||||
|
||||
- name: Build
|
||||
run: cargo build --locked
|
||||
|
||||
- name: Judgment matrix (real Lean; CI requires toolchain)
|
||||
env:
|
||||
MARQDO_PROOF_REQUIRE_LEAN: "1"
|
||||
run: cargo test --locked --test prove_lean
|
||||
|
||||
- name: Rest of prove suite (no toolchain assumptions)
|
||||
run: cargo test --locked --test prove
|
||||
|
||||
- name: Corpus monotonicity — offline_checked ⊆ lean_proved (40 fixtures)
|
||||
env:
|
||||
MARQDO_PROOF_REQUIRE_LEAN: "1"
|
||||
run: cargo test --locked --test prove_corpus
|
||||
|
||||
- name: T4 differential consistency — interpreter == Lean
|
||||
env:
|
||||
MARQDO_PROOF_REQUIRE_LEAN: "1"
|
||||
run: cargo test --locked --test conformance
|
||||
|
||||
- name: Full sweep — divergence guard bites on injected fault
|
||||
env:
|
||||
MARQDO_PROOF_REQUIRE_LEAN: "1"
|
||||
run: |
|
||||
# A3:注入分歧必须显式失败(error[proof.divergence],退 1)——
|
||||
# 护栏失灵(静默落绿)比单点失败严重得多。
|
||||
set -e
|
||||
tmp=$(mktemp -d)
|
||||
cat > "$tmp/审批.mq.md" <<'FIXTURE'
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
# 台账
|
||||
|
||||
## 记录
|
||||
+ `金额`
|
||||
|
||||
| 定理 | 结论 | 策略 |
|
||||
|---|---|---|
|
||||
| 记过即记 | 长度(轨迹) = 1 | auto |
|
||||
|
||||
**结果 = [登记](result.ok(value=`金额`))**
|
||||
|
||||
*结果*
|
||||
FIXTURE
|
||||
set +e
|
||||
out=$(cargo run --locked -- prove "$tmp/审批.mq.md" --fault-inject offline-claim --json 2>/dev/null)
|
||||
code=$?
|
||||
echo "$out" | head -c 400
|
||||
if [ "$code" -ne 1 ]; then
|
||||
echo "::error::注入分歧未被拦截(exit=$code)——单调性护栏失灵"
|
||||
exit 1
|
||||
fi
|
||||
echo "$out" | grep -q "proof.divergence" || {
|
||||
echo "::error::未出现 proof.divergence 诊断"
|
||||
exit 1
|
||||
}
|
||||
echo "divergence guard OK"
|
||||
@@ -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,67 +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.0.0**:遮蔽语法——`[描述](实现)` 描述不执行 · `()` 内调用 · `access` 取元 · 遮蔽循环 · `labels` / `migrate labels` · view 桩徽章
|
||||
- **v2.0.0**: Occlusion syntax — `[label](payload)` inert prose, paren calls, `access`, occlusion loops, `labels` / `migrate labels`, view stub badges
|
||||
- **v2.0.0 ext**:扩展包同步 2.0.0 / Ext pack 2.0.0
|
||||
- **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 }}
|
||||
@@ -184,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
|
||||
@@ -207,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
|
||||
@@ -215,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"
|
||||
@@ -243,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 }}
|
||||
@@ -1,5 +1,7 @@
|
||||
/target/
|
||||
/dist/
|
||||
# Plugin unit tests use package-relative scratch checkpoints.
|
||||
/plugins/agent/target/
|
||||
|
||||
# Copied by gold harness for ABI plugins
|
||||
/tests/lib/demo.dll
|
||||
@@ -42,11 +44,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 +59,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 +76,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/
|
||||
@@ -103,3 +105,23 @@ 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
|
||||
@@ -1,5 +1,399 @@
|
||||
# Changelog
|
||||
|
||||
## Unreleased
|
||||
|
||||
## Ext pack v2.8.1 — 2026-11-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**AI native durable workflow(CLI 仍为 v2.8.0)**:`ext/ai` 以插件侧步骤机交付持久化
|
||||
工作流(`workflow`/`flow`/`context`/`recovery`),含有界模型选择、作用域上下文、
|
||||
只读失败恢复、`inspect`/`list` 与可隔离 `resume_dir`。Windows 打包使用 `path.join`
|
||||
根路径与 `System32\tar.exe`。详见 [双语发布说明](doc/releases/ext-2.8.1.md)。
|
||||
|
||||
```bash
|
||||
marqdo ext add agent # CDN latest → 2.8.1
|
||||
# 或:MARQDO_EXT_VERSION=2.8.1 marqdo ext add agent
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime。
|
||||
|
||||
### Added
|
||||
|
||||
- `ext/ai/workflow`:`open/next/commit/cancel/tick/retry_*`,以及只读 `inspect`/`list`
|
||||
与各操作的 host-relative `resume_dir`。
|
||||
- `ext/ai/flow` · `context` · `recovery`:ask/choose、作用域打包、CheckpointV2 恢复面。
|
||||
- Agent ABI:`agent_workflow_*`、`agent_choice_parse`、`agent_context_scope`、
|
||||
`agent_input_*`、`agent_parallel_report`。
|
||||
- Offline fixtures:`tests/ext/ai-native-flow.mq.md`、`tests/ext/ai-native-workflow.mq.md`;
|
||||
CI:`.github/workflows/native-ai-flow.yml`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- `flow.choose` no longer leaks a branch-local `parsed` value into the function
|
||||
contract; the repaired-choice path is fully scoped.
|
||||
- CI builds the agent cdylib and runs offline integration without the removed
|
||||
`run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead.
|
||||
- Atomic checkpoint/effect temp names no longer collide under parallel writes;
|
||||
resume tests no longer race on process-wide cwd.
|
||||
- Windows `extension-release`:engineering root 使用 `path.join` / cwd 回退;
|
||||
ZIP 显式调用 `System32\tar.exe`(bsdtar);`packs.ci` 授予 `fs.read`。
|
||||
|
||||
### Changed
|
||||
|
||||
- 扩展包 SemVer **2.8.1**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。
|
||||
- 分支已合并 v2.8.0 依赖锁后的 AI 工作流增量,不再从 2.7.1 基线分叉。
|
||||
|
||||
## v2.8.0 — 2026-11-17
|
||||
|
||||
`marqdo prove` 正式发布:定理表 → Lean 4 证明 → 自动判定。离线符号执行(F1–F5)无工具链可用,`checked` 永远弱于 `proved`;单调性护栏让判定器缺陷显式失败;假定理给出反例见证;证书缓存与目录模式面向智能体批量出证。
|
||||
|
||||
`marqdo prove` ships: theorem tables compile to Lean 4 and are judged automatically. Offline symbolic execution works without a toolchain, monotonicity guardrails fail loudly on judger defects, fake theorems get counterexample witnesses, and certificate caching plus directory mode support agent-scale proving.
|
||||
|
||||
详见 [双语发布说明](doc/releases/v2.8.0.md)。
|
||||
|
||||
## 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
|
||||
|
||||
**默认隔离 HTTP execute(ADR 0009)**:`class=execute` / `sse-live` / `stream:true` 经 Supervisor worker 池(`marqdo run --call-lib-path`),父进程不再 `CallLibPath` 占 `INVOKE_LOCK`;短读 / 未声明非流式仍 `legacy_serial`(ADR 0008)。`/_runtime/*` 控制面;`runtime.isolated_execution=1`;MR-01 双 60s 假 SSE + 短读金样例。CLI · wasm · ext **2.1.4**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.4 && cargo build --release
|
||||
marqdo ext add web # CDN / Releases → 2.1.4
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——隔离运行时与 Web execute 路径,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **默认隔离 execute(ADR 0009)**:HTTP `execute` / `sse-live` / `stream:true` 经 Supervisor worker 池(`marqdo run --call-lib-path`),父进程不再 `CallLibPath` 占 `INVOKE_LOCK`;可选 route `class`;`/_runtime/*` 控制面;`runtime.isolated_execution=1`。
|
||||
- **MR-01 金样例**:`tests/isolated_execute_mr01.rs` + `tests/ext/isolated-execute-site/`(双 60s 假 SSE + 短读并行;槽满拒绝);接入 `executable-knowledge` workflow。
|
||||
- **Worker CLI**:`marqdo run --call-lib-path` / `--fs-root` / `--args-json` / `--emit-result`;host `runtime` admit/dispatch/cancel/events。
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
- **compile 1000 门禁**:executable-knowledge / workbench 路径恢复与能力探测诚实(isolated 默认开启)。
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.4**。
|
||||
|
||||
## v2.1.3 — 2026-10-25
|
||||
|
||||
### Highlights
|
||||
|
||||
**知识工作台运行时合同(M00–M06)**:`ModelSelectionV1` / `RunContextV1` / `ModelCallUsageV1` / `DocumentViewV1` / locator / snapshot;严格 selection;usage null≠0;`view document` 只读嵌入;LLM messages + cancel;agent.step selection 继承假模型 e2e;USTC 兼容 live smoke(env 注入)。CLI · wasm · ext **2.1.3**。设计证据仍为 Partial(原生适配器 unavailable;完整宿主 F12 留给应用)。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.3 && cargo build --release
|
||||
marqdo ext add llm # CDN / Releases → 2.1.3
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台合同与 View/LLM/Agent 扩展面,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **Workbench M00–M06**:capabilities / selection / RunContext / usage / DocumentView / locator / SnapshotManifest;`tests/workbench_contracts`(含 F02 agent.step+resume、F14 并发);`marqdo view document --out` 只读 HTML 嵌入。
|
||||
- **LLM**:`messages=` / `selection=` / `strict_selection`;cancel token;reasoning_content 回退;双端点隔离门禁。
|
||||
- **Live**:`tests/workbench_live`(`OPENAI_*` env only;`MARQDO_EXT` 指向仓内 `ext/`)。
|
||||
- **Agent skeleton**:子工作簿禁 `llm.llm`,从 env selection `llm.create`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`llm.ask` 升参**:hoist `p` 避免缺参 `missing argument for parameter p`;避免 `~/.marqdo/ext` 陈旧包遮蔽仓内 `ext/`(测试强制 `MARQDO_EXT`)。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.3**。
|
||||
|
||||
## v2.0.0 — 2026-10-22
|
||||
|
||||
### Highlights
|
||||
@@ -41,6 +435,32 @@ marqdo ext add web # CDN → 2.0.0
|
||||
- **语料迁移(M7)**:`public/` `ext/` `tests/` `examples/` `doc/` 等语料加 `markup: occlusion`,改写 **80 个语料文件 / 256 处取元 / 23 处循环**;新增 `tests/ratchet` 锁定标签债务。
|
||||
- **文档**:遮蔽语法总纲 + M0–M10 变更记录、标签新鲜度 / 修复回路、函数作为值 6 篇评估、代码体量审计;`doc/design/code-volume-audit.md` 记 53k 行构成。
|
||||
|
||||
## v2.1.0 — 2026-10-23
|
||||
|
||||
### Highlights
|
||||
|
||||
**文件级可执行知识语义**:标准库、扩展库、示例与公开文档全部采用显式 `markup: occlusion`;`[描述](实现)` 成为默认链接语义,`access` 与 `遍历` 承担原有取元与循环职责。迁移工具可离线证明语法形状等价,Tree 与 Bytecode 均完成全量回归。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.0 && cargo build --release
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
**核心表面 Δ**:默认链接语义从 Classic 切换到 Occlusion。未迁移的旧 `[键](集合)` 仅可用 `markup: classic` 或一个版本周期内的 `marqdo run --legacy-markup` / `check --legacy-markup` 执行。
|
||||
|
||||
### Added
|
||||
|
||||
- **文件级新语义迁移**:`marqdo migrate labels --mark` 可把整个库/目录迁移到显式 `markup: occlusion`,即使文件没有旧式索引也不再依赖进程默认值。迁移验证为语法级、无导入解析依赖,并在写入前比较 Classic 与 Occlusion AST 形状。
|
||||
- **显式过渡入口**:`marqdo run --legacy-markup` 与 `marqdo check --legacy-markup` 可在一个版本周期内审阅未迁移的旧文件;环境变量不再改变语法。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 标准库、扩展库、示例、公开文档与可解析测试夹具迁移为文件级 Occlusion;旧的 `[键](集合)` 和 `- [项](集合)` 分别改为 `access` 与 `遍历`。
|
||||
|
||||
### Changed
|
||||
|
||||
- 未标注源码默认采用 Occlusion。Classic 仅能通过明确的 frontmatter 或 `--legacy-markup` 进入,避免同一文档因进程配置而静默改变含义。
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
@@ -49,6 +469,73 @@ marqdo ext add web # CDN → 2.0.0
|
||||
|
||||
### Changed
|
||||
|
||||
## v2.1.2 — 2026-10-24
|
||||
|
||||
### Highlights
|
||||
|
||||
**可执行知识生产消费链 + View 阅读体验发版门槛**:证据摘要进闭包/句柄;`artifact.verify` / `knowledge adjudicate` 结构化裁决;`artifact.reuse_execute` 与 `agent_eng_bind_execute` / `publish_gate` 实际复用(非 n-gram);`document.extract` 文本/Markdown + PDF/OCR 显式失败;View `KnowledgePresentation`、说明锚点、SSE `page_token` 过期包拒绝;上传 `max_bytes`;门禁 45 项(含 100/1000 单元)。CLI · wasm · ext **2.1.2**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.2 && cargo build --release
|
||||
marqdo ext add web
|
||||
cargo test --offline --locked --test executable_knowledge
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删关键词**——语义/MLSP/View/Agent 宿主扩展;不改变默认 Occlusion 链接读法与表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **证据与闭包(F0/M02)**:来源 digests 进入 artifact/evidence/closure;business handle 改/删来源失效;锚点/可读性诊断。
|
||||
- **验证裁决(F0/M03)**:`artifact.verify` 结构化 `may_bind` / `may_publish`;policy 枚举;`knowledge adjudicate`;CLI `--fail`。
|
||||
- **语法 Skill(F0/M05)**:CORE SYNTAX 置顶;`migration-classic.md`;`skill_core_card` 与预算截断防护。
|
||||
- **绑定执行(F1/M04)**:`artifact.reuse_execute`;`agent_eng_bind_execute` + `eng_publish_gate`(`candidate_only` / product gate);host_query `mlsp`;`tests/ext/agent-eng-bind-gate.mq.md`。
|
||||
- **发布与来源(F2/M06–M07)**:统一 `EXCLUDED_DIRS`;`publish_manifest.json`;`function_sources` 函数级来源覆盖。
|
||||
- **文档提取(F3/M01)**:`document.extract` DocumentSource→ExtractedDocument;PDF/DOCX/OCR 显式 `failed`;超限截断 `partial`;Web 上传 `MaxBytesReader` / `LimitReader`。
|
||||
- **View V0–V3(子集)**:正文优先;no-exec;`KnowledgePresentation`(`semantic_generation` / `page_token` / `local_deps`);SSE 过期包拒绝与帧选择保留;print/响应式;1000 单元 compile smoke。
|
||||
- **故事门禁(M08)**:建库→复用→来源变更失效→修复重绑。
|
||||
|
||||
### Fixed
|
||||
|
||||
- View 说明链接 raw-string 截断;skill_brief / CORE SYNTAX 预算不被冲突旧规则吃掉。
|
||||
- 上传体积限制在 multipart 解析前生效(不再只靠内存 form 预算)。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.2**。
|
||||
- `tests/executable_knowledge` 门禁扩至 45 项;README 切片进度表与发版子集对齐。
|
||||
|
||||
## v2.1.1 — 2026-10-23
|
||||
|
||||
### Highlights
|
||||
|
||||
**可执行知识主链落地(S0–S6)**:BoundCall 双后端共享解析、正文 NarrativeRef、来源/适用期、digest 保护补丁与纯表达式提取、整代 `CURRENT` 投影与闭包摘要;订单发票示例双后端输出 `113`;离线门禁含 100 单元语料与 CLI 冒烟。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.1 && cargo build --release
|
||||
marqdo ext add web
|
||||
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md
|
||||
```
|
||||
|
||||
**核心表面 Δ**:**无增删关键词**——同模块 `Type.member` 纳入 BoundCall;语义投影新增 `bound_calls` / `dynamic_calls` / `hashes.closure` / NarrativeRef 步骤;不改变默认 Occlusion 链接读法。
|
||||
|
||||
### Added
|
||||
|
||||
- **BoundCall / DynamicCall**:`sema::bind::resolve_for_exec`;Tree 与 Bytecode 静态路径对齐;`bound_calls.json` / `dynamic_calls.json`;同模块定义树路径绑定。
|
||||
- **NarrativeRef**:注释行 Markdown 链接 → `narrate` / `navigation` 步骤;围栏与行内代码不计步骤。
|
||||
- **来源与适用性**:frontmatter `sources` / `valid_until` → `evidence=sourced|expired|missing_source`;`artifact.bind policy=business`。
|
||||
- **局部编辑与提取**:MLSP `artifact.patch`(digest + wording 回滚);`artifact.extract_pure` 纯表达式预览。
|
||||
- **整代与闭包**:`generations/<id>/` + `CURRENT`;`hashes.closure` 随依赖变化;锁报告 `classes`。
|
||||
- **门禁**:`tests/executable_knowledge`(含 100 单元);CI `.github/workflows/executable-knowledge.yml`;项目扫描 depth/size/count 上限。
|
||||
- **示例**:`examples/executable-knowledge` 发票含税链可运行;负知识文档。
|
||||
|
||||
### Fixed
|
||||
|
||||
- Bytecode 裸名解析不再跨 import scope 误连同名函数;同模块 `Type.member` 写入 path_index 供兄弟调用。
|
||||
|
||||
### Changed
|
||||
|
||||
- Agent / reuse 发现结果标记 `discovery_only` + `bind_required` / `bind_targets`,不可把打分结果直接当可执行目标。
|
||||
|
||||
## v1.5.2 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
@@ -755,6 +1242,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 = 4
|
||||
version = 3
|
||||
|
||||
[[package]]
|
||||
name = "adler2"
|
||||
@@ -143,9 +143,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "bumpalo"
|
||||
version = "3.20.3"
|
||||
version = "3.20.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
|
||||
checksum = "87a0cf66fd1eb2fb7b822cb78370d82303750809bc6ba855f3f58e517d3238db"
|
||||
|
||||
[[package]]
|
||||
name = "byteorder"
|
||||
@@ -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"
|
||||
@@ -264,9 +285,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "crossbeam-utils"
|
||||
version = "0.8.21"
|
||||
version = "0.8.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
|
||||
checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
|
||||
|
||||
[[package]]
|
||||
name = "crypto-common"
|
||||
@@ -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"
|
||||
@@ -539,9 +582,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
||||
|
||||
[[package]]
|
||||
name = "js-sys"
|
||||
version = "0.3.104"
|
||||
version = "0.3.107"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
|
||||
checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"futures-util",
|
||||
@@ -572,11 +615,12 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "2.0.0"
|
||||
version = "2.8.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"chrono",
|
||||
"chrono-tz",
|
||||
"clap",
|
||||
"futures-util",
|
||||
"getrandom",
|
||||
@@ -589,6 +633,7 @@ dependencies = [
|
||||
"predicates",
|
||||
"pulldown-cmark",
|
||||
"regex",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"sha1",
|
||||
"sha2",
|
||||
@@ -596,6 +641,7 @@ dependencies = [
|
||||
"tiny_http",
|
||||
"tokio",
|
||||
"tokio-tungstenite",
|
||||
"toml",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
"zip",
|
||||
@@ -610,7 +656,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.0.0"
|
||||
version = "2.8.0"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -622,6 +668,7 @@ version = "0.1.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"marqdo-plugin-sdk",
|
||||
"pulldown-cmark",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
@@ -633,6 +680,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"
|
||||
@@ -726,12 +790,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"
|
||||
@@ -970,6 +1081,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"
|
||||
@@ -1004,6 +1124,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"
|
||||
@@ -1151,6 +1277,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"
|
||||
@@ -1290,12 +1457,11 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen"
|
||||
version = "0.2.127"
|
||||
version = "0.2.130"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
|
||||
checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"once_cell",
|
||||
"rustversion",
|
||||
"wasm-bindgen-macro",
|
||||
"wasm-bindgen-shared",
|
||||
@@ -1303,9 +1469,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro"
|
||||
version = "0.2.127"
|
||||
version = "0.2.130"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
|
||||
checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9"
|
||||
dependencies = [
|
||||
"quote",
|
||||
"wasm-bindgen-macro-support",
|
||||
@@ -1313,22 +1479,22 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro-support"
|
||||
version = "0.2.127"
|
||||
version = "0.2.130"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
|
||||
checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a"
|
||||
dependencies = [
|
||||
"bumpalo",
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
"syn 3.0.3",
|
||||
"wasm-bindgen-shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-shared"
|
||||
version = "0.2.127"
|
||||
version = "0.2.130"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
|
||||
checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e"
|
||||
dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
@@ -1492,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.0.0"
|
||||
version = "2.8.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -12,6 +12,12 @@ name = "marqdo"
|
||||
path = "src/main.rs"
|
||||
required-features = ["cli"]
|
||||
|
||||
# Lean 判定集成测试(独立目标:缓存/判定/退出码矩阵,见 tests/prove_lean.rs)。
|
||||
[[test]]
|
||||
name = "prove_lean"
|
||||
path = "tests/prove_lean.rs"
|
||||
required-features = ["cli"]
|
||||
|
||||
[features]
|
||||
default = ["native"]
|
||||
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
|
||||
@@ -29,7 +35,8 @@ anyhow = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"], optional = true }
|
||||
pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = { version = "1", features = ["float_roundtrip"] }
|
||||
thiserror = "1"
|
||||
tiny_http = { version = "0.12", optional = true }
|
||||
sha2 = { version = "=0.10.9", default-features = false }
|
||||
@@ -48,6 +55,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).
|
||||
@@ -57,6 +66,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,139 @@
|
||||
# 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/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.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.1](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.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 · 语言、设计与执行系统
|
||||
|
||||
标准库单文件本身就是手册:直接阅读[文件库](lib/文件.mq.md)、[集合库](lib/表.mq.md)等源码,按函数标题下的参数表、返回契约和动作说明调用;[工程实践](examples/stdlib-handbook/索引.mq.md)演示文件整理、CSV 汇总与文档维护。
|
||||
开发标准库和拓展库请直接阅读[可执行库开发指南](doc/library-development.mq.md):契约表、叙述式实现、遮蔽调用与多文件工程组织均有可运行示范。
|
||||
|
||||
当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。
|
||||
|
||||
独立拓展包 **2.8.1**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.1.md)。
|
||||
|
||||
CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available.
|
||||
|
||||
Ext pack **2.8.1** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`.
|
||||
|
||||
## 核心优势:可执行知识(Executable Knowledge)
|
||||
|
||||
> **Knowledge That Can Run —— 知识即可执行。**
|
||||
@@ -29,15 +153,97 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| 真正的核心优势 | 说明 |
|
||||
|------|------|
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **函数即工具**<br>`marqdo call` | 最小可执行单位是文件中的函数,不只是整份文件。人阅读函数旁边的叙述;开发者、测试和 Agent 用 `marqdo call 文件 函数 名字=值` 执行它。知识复用、工具调用、函数级测试和局部改进是同一入口的四种用法。 |
|
||||
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
|
||||
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元 `[键](集合)` 也是 Markdown 链接形。这是 literate programming 的下一步。 |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
|
||||
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`print` 只是副作用函数;分支与循环长在 Markdown 结构上(`1.` `2.` 递增 = 分支,`-` = 循环),不是所有列表都被粗暴当成 if。 |
|
||||
| **AI 的可靠上下文与长期记忆** | 一个 `.mq.md` 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的**世界模型**——比 RAG 更接近 Executable RAG。 |
|
||||
| **链接即调用**<br>Link as Call | 文档里的 `[描述](类.函数)` 不是装饰,是跨文档类调用;编译器解析类/函数并返回 **LinkInfo**,`view` 显示调用点,EKC 建边,`links.lock` 可选复现。**v2.1 已实现可执行知识基础设施**。 |
|
||||
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
|
||||
|
||||
---
|
||||
|
||||
## 链接语法:链接即调用(v2.1 设计声明)
|
||||
|
||||
> **这是 v2.1 的可执行知识模型。**
|
||||
> `[]()` 不新增语法:`[]` 是 Markdown 链接的描述;`()` 是**已有代码**,与 `**代码**` 同权。
|
||||
> `#` 是类,`##` 是函数;`类.函数` 是**类调用**。
|
||||
> 链接只是给这次调用一个名字;`view` 显示调用信息,编译器返回 **LinkInfo**,EKC 建边。
|
||||
|
||||
### 两文档,一次类调用
|
||||
|
||||
知识文档 `libai.mq.md`:
|
||||
|
||||
```markdown
|
||||
# 李白
|
||||
|
||||
这个文档存储了李白的信息。
|
||||
|
||||
## 李白的出生年份
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
- `# 李白` = 类;
|
||||
- `## 李白的出生年份` = 函数;
|
||||
- `*701*` = 返回值。
|
||||
|
||||
调用文档 `main.mq.md`:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
|
||||
```
|
||||
|
||||
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`——**类 `李白` 调用函数 `李白的出生年份`**。
|
||||
不需要 `print`:`view` 模式天然显示 `()` 的调用信息(类、函数、签名、值)。
|
||||
要终端输出,就把同一段代码放进代码链接并加 `print`:
|
||||
|
||||
```markdown
|
||||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||||
> print text=`year`
|
||||
```
|
||||
|
||||
输出:`701`。
|
||||
|
||||
### 四条语义
|
||||
|
||||
1. **`[]` 永不执行**:描述只给人读、给检索/诊断/展示用。
|
||||
2. **`()` 与 `**代码**` 同权**:同一套 parser/evaluator;`类.函数` 是类调用,`obj.函数` 是实例调用。
|
||||
3. **`#` 是类,`##` 是函数**:不使用 `self`/`自` 的函数是**类函数**,可直接 `类.函数` 调用;使用 `self`/`自` 的是**实例函数**。
|
||||
4. **链接 = 描述 + 调用**:`view` 显示调用点;编译器返回 `LinkInfo`;EKC 建边;`links.lock` 可选复现。
|
||||
|
||||
### 现状与目标
|
||||
|
||||
| 能力 | v2.0.0 | v2.1 |
|
||||
|------|-------------|-----------|
|
||||
| 本地表达式链接(遮蔽) | ✅ `markup: occlusion` | ✅ |
|
||||
| `()` 与 `**代码**` 同权 | ✅ 表达式/调用 | ✅ |
|
||||
| 类调用 `类.函数` | ❌ 需先构造实例 | ✅ 直接调用 |
|
||||
| 跨文档类索引 | ❌ 需 `import` + 实例 | ✅ 项目类索引 |
|
||||
| 正文链接 `view` 信息 | ❌ | ✅ 目标/签名/值 |
|
||||
| LinkInfo / check | ❌(`check` 只查契约) | ✅ `link.*` |
|
||||
| 链接图边(EKC) | ❌ | ✅ `calls` / `references` |
|
||||
| `links.lock` 可复现 | ❌ | ✅ 可选 |
|
||||
|
||||
### 知识分层:本体 → 知识个体 → 调用面
|
||||
|
||||
| 层 | 写法 | 语义 |
|
||||
|----|------|------|
|
||||
| L1 本体 | `# 诗人` + 字段/类型表 | 类/模式 |
|
||||
| L2 知识个体 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` | 单体知识类(不是运行时实例) |
|
||||
| L3 调用面 | `[出生年份](李白.出生年份)` | 类调用/链接 |
|
||||
|
||||
> `# 李白 = > 诗人` 语法上是继承/特化,语义上是「李白是诗人」的知识个体;
|
||||
> 运行时实例仍是 `> 诗人` / `> 李白`。详见 [knowledge-layers.md](doc/design/knowledge-layers.md)。
|
||||
|
||||
兼容迁移示例见 [examples/link-syntax/main.compat.mq.md](examples/link-syntax/main.compat.mq.md)。
|
||||
|
||||
设计宪法:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 链接示例:[examples/link-syntax/](examples/link-syntax/) · 知识分层示例:[examples/knowledge-layers/](examples/knowledge-layers/) · 证据复核:[occlusion-vs-executable-knowledge-2026-10.md](doc/research/occlusion-vs-executable-knowledge-2026-10.md)
|
||||
|
||||
---
|
||||
|
||||
## 愿景与期许
|
||||
|
||||
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
|
||||
@@ -45,8 +251,9 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
1. **AI 可验证语言**:`LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序`。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
|
||||
2. **Marqdo Schema / Language Server for AI**:机器可读的语言 Schema(`get_syntax` / `validate` / `repair` …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
|
||||
3. **程序即 AI 长期记忆**:`.mq.md` 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
|
||||
4. **可执行知识图**:`.mq.md` 之间的 Markdown 链接天然长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
|
||||
4. **链接即调用 / 可执行知识图**:`[描述](类.函数)` 既是文档链接,也是类/函数调用;编译器解析目标、校验签名、返回 LinkInfo;`view` 显示调用点;`.mq.md` 之间的链接长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
|
||||
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
|
||||
6. **知识可证明**:知识文件内的定理表 → Lean 4 定理 → 自动判定(`marqdo prove`);离线符号执行与 Lean 单调一致,分歧显式报错——Trusted Knowledge,判定器缺陷优先于任何绿灯。
|
||||
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
|
||||
|
||||
---
|
||||
@@ -64,24 +271,30 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.3)
|
||||
## 语法速览
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
|
||||
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
|
||||
| `[描述](表达式)` | **链接(本地)**:描述 + 代码;`()` 与 `**…**` 同权(默认语义) |
|
||||
| `[描述](类.函数)` | **链接(跨文档/类调用)**:描述 + 已有类函数调用;可解析、可执行(v2.1 目标) |
|
||||
| `[描述](url)` | 普通 Markdown 导航链接(惰性,不执行) |
|
||||
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
|
||||
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `#` | **类 / 类型**(知识命名空间;`# main` = 入口) |
|
||||
| `##` … | **函数**(类下函数;使用 `self`/`自` 时为实例方法) |
|
||||
| `类.函数` | **类调用**(不使用 `self` 的函数;v2.1 目标) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
|
||||
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
|
||||
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](遍历 集合 为 项) ``) |
|
||||
| 表格 | 集合(几何即类型,见下);取元使用 `access(集合, "键")` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
|
||||
|
||||
> `[键](集合)` / `- [项](集合)` 是旧取元/循环形;迁移后使用 `access(集合, "键")` 与 `- [描述](遍历 集合 为 项)`。旧形只在显式 `markup: classic` 或 `--legacy-markup` 过渡入口中保留,见 [link-syntax.md](doc/design/link-syntax.md)。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
@@ -133,8 +346,9 @@ Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**实现**(唯一执行)。这条语法叫**遮蔽**:
|
||||
把不可读或未完成的实现藏到括号里,人读描述、机器读代码。
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**目标**(唯一执行)。这条语法叫**链接语法**:
|
||||
目标是本地表达式时,就是**遮蔽**(把代码折叠在括号里);目标是 `类.函数` 时,就是**跨文档类调用**。
|
||||
v2.1 实现了文件级链接语义与可执行知识投影(见 [link-syntax.md](doc/design/link-syntax.md))。
|
||||
|
||||
**四条约定**
|
||||
|
||||
@@ -147,15 +361,15 @@ Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。
|
||||
**盘点与门禁**
|
||||
|
||||
```bash
|
||||
marqdo labels pending # 内置口径:还有多少未完成
|
||||
marqdo labels search --grep "接口未联调,联调中" # 用你自己的说法
|
||||
marqdo labels search --grep 联调 --also-builtin # 自定义 + 内置一起数
|
||||
marqdo labels pending --count --baseline .marqdo/pending.json --fail-on-increase
|
||||
marqdo labels --count # 内置口径:还有多少未完成
|
||||
marqdo labels --grep "接口未联调,联调中" --count # 用你自己的说法
|
||||
marqdo labels --grep 联调 --also-builtin --count # 自定义 + 内置一起数
|
||||
marqdo labels --count --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
|
||||
|
||||
设计依据:[occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
|
||||
设计依据:[link-syntax.md](doc/design/link-syntax.md) · [occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
|
||||
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
|
||||
|
||||
---
|
||||
@@ -193,9 +407,29 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v2.0.0)
|
||||
## 现状(v2.7.0)
|
||||
|
||||
- **遮蔽语法(v2.0.0)**:`[描述](实现)` 描述不执行 · `()` 内调用(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 遮蔽循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels` · 诊断 `label.missing` / `empty_payload` / `ref_dangling` · view 描述正文 + 代码片 + 桩徽章 · 扩展包同步 **2.0.0**
|
||||
- **实际工程与可执行 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)
|
||||
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
|
||||
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
|
||||
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
|
||||
@@ -219,7 +453,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)
|
||||
@@ -228,10 +462,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.0.0)
|
||||
### 如何使用最新 Marqdo(v2.7.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -246,14 +480,16 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v2.0.0 # 或留在 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
|
||||
@@ -277,15 +513,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.0.0
|
||||
# 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.0.0"
|
||||
version = "2.8.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
@@ -12,4 +12,4 @@ crate-type = ["cdylib", "rlib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
|
||||
serde_json = "1"
|
||||
serde_json = "1"
|
||||
@@ -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,140 @@
|
||||
marqdo (2.8.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Release 2.8.0; see the reviewed upstream CHANGELOG.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Wed, 18 Nov 2026 10:24:08 +0800
|
||||
|
||||
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
|
||||
worker pool for execute/sse-live/stream, /_runtime/* control plane,
|
||||
MR-01 dual 60s SSE gold sample, runtime.isolated_execution=1.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 26 Oct 2026 10:00:00 +0000
|
||||
|
||||
marqdo (2.1.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.3: workbench M00–M06 runtime contracts (ModelSelection,
|
||||
RunContext, DocumentView, usage null≠0, LLM selection/cancel,
|
||||
agent.step selection e2e, view document CLI, live smoke).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 25 Oct 2026 15:20:00 +0000
|
||||
|
||||
marqdo (2.1.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.2: executable-knowledge F0–F3 + View V0–V3 release bar
|
||||
(evidence/closure, verify gates, bind/reuse_execute, document.extract,
|
||||
KnowledgePresentation, SSE page_token, upload max_bytes).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sat, 24 Oct 2026 14:50:00 +0000
|
||||
|
||||
marqdo (2.1.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.1: executable-knowledge spine (BoundCall, NarrativeRef,
|
||||
sources/applicability, generation CURRENT + closure digests).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 15:40:00 +0000
|
||||
|
||||
marqdo (2.1.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.0: file-scoped Occlusion is the default syntax; migrated
|
||||
standard/extension libraries and executable-knowledge projections.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 12:00:00 +0000
|
||||
|
||||
marqdo (2.0.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
|
||||
|
||||
@@ -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.
|
||||
@@ -13,10 +13,29 @@
|
||||
|
||||
## 当前文档
|
||||
|
||||
> **可执行知识下一阶段的阅读顺序**:[原始意图 009](next/009.md) → [文档原生开发指导](design/document-native-development-guide.md)(作者体验、语法审查结论、AI 工作协议)→ [详细开发规范](next/Marqdo_Executable_Knowledge_Development.md)(目标语义与工程约束)→ [缺口与交付路线](roadmap/executable-knowledge-gaps-2026-10-23.md)(现状证据、S0–S6)。指导文档修订作者负担、场景政策和交付次序;不得把所有内部治理字段变成作者必填项。与之冲突的早期设计只作历史参考,设计目标不等于已实现能力。
|
||||
>
|
||||
> **可执行知识门禁**:[tests/executable_knowledge/](../tests/executable_knowledge/README.md) — S0–S2 BoundCall / 效应 / MLSP bind,以及后续 NarrativeRef、来源与整代投影子集;`cargo test --test executable_knowledge --locked`(CI:`.github/workflows/executable-knowledge.yml`)。`status: design` / 预期失败与已实现分开报告。
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
|
||||
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
|
||||
| [design/prove-cli.md](design/prove-cli.md) | **Proposed:`marqdo prove` 设计**;SKILL 控制平面 → Lean 4、函数级定理表与语言习惯审查、离线判定片段、`proved`/`checked` 诚实性契约、无公理 TCB |
|
||||
| [roadmap/prove.md](roadmap/prove.md) | **Proposed:`marqdo prove` 实施路线**;P0–P3 周计划、8 类测试矩阵(单调性/一致性/不执行/子集/定理表/CLI/缓存/编码)、CI 与验收证据 |
|
||||
| [adr/0010-skill-proof-boundary.md](adr/0010-skill-proof-boundary.md) | **ADR 0010**:定理表作为契约表第四角色、可证子集封闭、Lean 为唯一 `proved` 来源、顾问式不强制 |
|
||||
| [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 默认链接/循环说明与构造守卫;不是全部实现状态清单 |
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **历史 v0.2 映射**:不再代表现行默认链接语义 |
|
||||
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 设计背景**:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断;链接语义以 v2.1 规范和测试为准 |
|
||||
| [adr/0005-prose-unified-markup.md](adr/0005-prose-unified-markup.md) | **Proposed:采纳 mapping v0.3** |
|
||||
| [roadmap/markup-v0.3.md](roadmap/markup-v0.3.md) | **Markup v0.3 实现路线(M0–M5)** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
@@ -33,6 +52,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/网络/数学/外联/插件** |
|
||||
@@ -63,7 +83,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、布局…) |
|
||||
@@ -106,6 +126,13 @@
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
|
||||
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
|
||||
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
|
||||
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
|
||||
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
|
||||
| [roadmap/executable-knowledge-gaps-2026-10-23.md](roadmap/executable-knowledge-gaps-2026-10-23.md) | **v2.1 现状与规划缺口审计(方向修订)**:保留 G01–G12 代码证据,以可读步骤、确定执行、早期 AI 复用和局部修改重排 S0–S6,严格治理按场景增加 |
|
||||
| [../tests/executable_knowledge/README.md](../tests/executable_knowledge/README.md) | **S0 作者基线门禁**:六类任务语料、作者成本计数、预期失败与 Bytecode 同名误连缺陷指纹 |
|
||||
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
|
||||
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
|
||||
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
|
||||
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
|
||||
@@ -114,6 +141,7 @@
|
||||
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
|
||||
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
|
||||
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
|
||||
| [research/occlusion-vs-executable-knowledge-2026-10.md](research/occlusion-vs-executable-knowledge-2026-10.md) | **遮蔽 vs 可执行知识复核**:v2.0.0 的 `[]()` 只做了呈现层 · 两文档例子实测不可执行 · `check`/`labels`/图边工程漂移证据 · 原始设计=类-函数调用(见 link-syntax) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# ADR 0004:网络拓展库原生实现改为 Go
|
||||
|
||||
历史说明(2026-11-10):下文业务站点仅记录当时决策背景,相关工程已移出本仓库;当前验收使用维护中的完整站点、网络站点及隔离测试,见 [当前工作流](../design/ext-web-go-rewrite.md#8-独立工作流与隔离验收)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
# ADR 0008:Web 热路径单解释器串行化(设计缺陷与缓解)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted**(缺陷已记录;缓解已落地;真并行见 [ADR 0009](0009-isolated-web-runtime.md)) |
|
||||
| Date | 2026-10-26 |
|
||||
| Related | [web-invoke-serialization.md](../design/web-invoke-serialization.md) · [ADR 0009](0009-isolated-web-runtime.md) · ADR [0004](0004-web-plugin-go.md) · ADR [0007](0007-web-document-endpoint.md) · [ext-abi.md](../design/ext-abi.md) · [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Go `plugins/web` 的 HTTP 服务是**多 goroutine** 的:每个请求可并发进入 `handleInvoke` / `handleInvokeLiveSSE`。
|
||||
- 每个 Endpoint 最终经 C ABI `host_query("call_lib_path", …)` 回到 Rust 宿主,在**同一个** `HostContext`(Marqdo 解释器状态)上执行作者 `.mq.md`。
|
||||
- `HostContext` **不是** `Sync`:共享可变会话、库装载、写回、事件总线等状态不能安全地被多线程同时求值。
|
||||
- 因此宿主用进程级 `INVOKE_LOCK`(`src/host/plugin.rs`)串行化所有来自 worker 线程的 `call_lib_path`。
|
||||
|
||||
### 常见误解
|
||||
|
||||
> 「web 都是单线程的吗?不能多线程吗?」
|
||||
|
||||
| 层 | 并发模型 |
|
||||
|----|----------|
|
||||
| Go HTTP / SSE flush / 取消 | **多线程(多 goroutine)** |
|
||||
| Marqdo 解释器 `call_lib_path` | **单飞(一把全局锁)** |
|
||||
| 浏览器 UI | 与后端锁无关;但若短 API 同步阻塞等待锁,会表现为「整页卡死」 |
|
||||
|
||||
**缺陷不在「HTTP 单线程」,而在「多 HTTP 工作线程共享一个非 Sync 解释器」。**
|
||||
真并行需要多解释器实例(或可共享的隔离运行时),不是去掉 Go 侧并发。
|
||||
|
||||
### 事故形态(已观测)
|
||||
|
||||
长对话(`return=sse-live` / `stream:true`)在 `CallLibPath` 期间一直持有 `INVOKE_LOCK`。并发的短路由(如 `/v1/models`、设置页探测)在旧实现里对锁 **无限期** `lock()`,HTTP 挂起 → 前端 `fetch` 无超时 → 页面无响应。重启进程可恢复,但属于运维掩盖,不是正确错误处理。
|
||||
|
||||
## Decision
|
||||
|
||||
1. **承认并文档化**本限制为宿主架构缺陷(单 `HostContext` + 全局 `INVOKE_LOCK`),不得再被表述为「web 插件只能单线程」。
|
||||
2. **缓解(已实现,非根治)**:
|
||||
- `call_lib_path` 从 worker 进入时用 **限时 try-lock**(默认 `MARQDO_INVOKE_WAIT_MS=1500`),超时返回错误串 `interpreter busy: …`。
|
||||
- Go `handleInvoke` 将含 `interpreter busy` 的错误映射为 **HTTP 503**,并设 `Retry-After: 2`。
|
||||
- **禁止**在 SSE 期间把进程级 `MARQDO_INVOKE_WAIT_MS` 拉长:那会让并发短请求重新卡死。
|
||||
- 长 SSE 在启动时用同一短预算争锁;一旦拿到则持有至调用结束(对话本来就要跑完)。
|
||||
3. **客户端契约**:短 API 必须有超时与 503 文案;不得假设「任意时刻都能同步进入解释器」。
|
||||
4. **根治(未决,另案)**:解释器池 / per-request isolate / 可 `Send` 的会话切片。未落地前,产品行为以本 ADR 的 503 语义为准。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 对话进行中,设置/模型列表等短请求约 1.5s 内失败并可读,UI 不再无限挂起。
|
||||
- 缺陷有名有姓,后续多解释器工作不会被「修好了」的假象挡住。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- 同一进程仍无法真正并行跑两个 Marqdo Endpoint 体;第二个长 SSE 也会在短预算后失败。
|
||||
- 极短窗口内,短请求若正好撞上锁交接,可能偶发 503(可重试)。
|
||||
- `MARQDO_INVOKE_WAIT_MS` 是进程环境变量;误设过大仍会复现卡顿。
|
||||
|
||||
### Neutral
|
||||
|
||||
- Go 多 goroutine、SSE 桥(`MARQDO_EVENT_FORWARD`)、取消令牌(`MARQDO_CANCEL_TOKEN`)保持不变。
|
||||
- 不改变 Document / Endpoint 作者面(ADR 0007);只约束宿主与 web 插件错误语义。
|
||||
|
||||
## Implementation pointers
|
||||
|
||||
| 位置 | 职责 |
|
||||
|------|------|
|
||||
| `src/host/plugin.rs` → `acquire_invoke_lock` | 限时争锁;失败 `set_err("interpreter busy…")` |
|
||||
| `plugins/web/.../routes_invoke.go` → `handleInvoke` | `interpreter busy` → 503 + `Retry-After` |
|
||||
| 设计长文 | [web-invoke-serialization.md](../design/web-invoke-serialization.md) |
|
||||
@@ -0,0 +1,33 @@
|
||||
# ADR 0009: Isolated Web Runtime (worker process pool)
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**;HTTP **execute** 路径正式替代 [ADR 0008](0008-web-invoke-serialization.md) 的并行性结论。`legacy_serial`(未声明且非流式)仍引用 0008 单飞 / 父进程 `CallLibPath`。 |
|
||||
| 日期 | 2026-10-26(修订 2026-10-27:disconnect≠cancel;control/read/short 无父锁) |
|
||||
| 设计 | [isolated-web-runtime-development-2026-10-26.md](../design/isolated-web-runtime-development-2026-10-26.md) |
|
||||
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝;disconnect-keeps-running;control-under-dual-execute) |
|
||||
|
||||
## 背景
|
||||
|
||||
ADR 0008 确认:Go HTTP 多线程,但所有 Endpoint 共享一把解释器锁与进程级 SSE 桥环境变量。1500ms busy → 503 只是缓解,不是并行。
|
||||
|
||||
## 决策
|
||||
|
||||
1. **首选架构**:预热的一次性 Marqdo worker 进程池;每个租约独占一个进程与 HostContext。
|
||||
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` / body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);**禁止**父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。声明的 `short`/`read`/`control` 走父进程短路径(execute 已离进程,父锁通常空闲);未声明非流式 → `legacy_serial`。
|
||||
3. **控制/读取分离**:`/_runtime/*`(cancel、events、task get)不进入解释器锁。短读勿挤占 execute worker 槽(池默认 2);产品 cancel 优先 `/_runtime`。
|
||||
4. **订阅 ≠ 取消**:`sse-live` 观察者 `ctx.Done()` 默认**只结束订阅**,不 `runtime.cancel`;后台仍 reap worker 以释放槽。仅显式 header `X-Marqdo-Cancel-On-Disconnect: 1` 才 disconnect=cancel。同步 `waitIsolatedJSON` 可保留 disconnect 取消。重连:`GET /_runtime/tasks/{id}/events` + `Last-Event-ID` / `after_seq`。
|
||||
5. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
|
||||
6. **能力探测**:`runtime.isolated_execution=1`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane=1`(短读不与 execute 抢父锁)。
|
||||
7. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
|
||||
|
||||
## 后果
|
||||
|
||||
- Execute / live SSE 不再抢进程级 SSE 桥;双流可并行(MR-01)。
|
||||
- 短读走父进程:在 dual execute 下通常仍 200(父锁空闲);勿把 short/read/control 塞进 2 槽 execute 池。
|
||||
- Legacy 未声明非流式路径仍可走父进程锁(ADR 0008)。
|
||||
- 产品(qdagent)`turn_events` / Last-Event-ID / cancel CAS 接线由 qdagent 验收;框架侧 disconnect≠cancel 与 `/_runtime` 无锁控制面已落地。
|
||||
|
||||
## 验收(摘要)
|
||||
|
||||
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`、`runtime.read_lane=1`。观察者断连后任务仍跑完并可经 `/_runtime` 重放。其余见设计文档 §12。
|
||||
@@ -0,0 +1,79 @@
|
||||
# ADR 0010: SKILL 证明边界:定理表、可证子集与顾问式判定
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Accepted(决策已定)**;实现未开始,路线见 [roadmap/prove.md](../roadmap/prove.md) |
|
||||
| 日期 | 2026-11-13 |
|
||||
| 设计 | [design/prove-cli.md](../design/prove-cli.md) |
|
||||
| 相关 | [core-surface.md](../design/core-surface.md)(不新增标记)· [layers.md](../design/layers.md)(Language 层扩表角色)· [contract.rs](../../src/contract.rs)(既有契约表提取)· [replay-policy](../../verification/replay-policy/README.md)(Lean 伴随判定先例) |
|
||||
|
||||
## 背景
|
||||
|
||||
Agent 改写 SKILL 后,人需要逐行确认"分支是否绕开审核、失败是否被吞掉"。这类**控制平面**性质适合形式化:编排是带条件的有限 DAG,没有死循环、没有指针。同时,把整个 Marqdo 当通用语言编译到 Lean 会立刻撞上字符串/JSON/浮点/IO 的语义鸿沟,收益被稀释。
|
||||
|
||||
项目已有一条 Lean 纪律:`verification/replay-policy` 用 Lean 做唯一判定,Rust 不保留第二份实现,缺伴随进程时失败关闭。本 ADR 决定把同样的纪律用于 SKILL 编排,但**降级为顾问式**:证明用于减少审核量,不作为发布门禁。
|
||||
|
||||
## 决策
|
||||
|
||||
1. **定理是契约表的第四种角色**,不是新标记。
|
||||
函数体首条可执行语句之前可放一张「定理表」(`定理 | 结论 | 前提 | 策略`),与 `参数`/`返回`/`字段` 表同槽位;解析期提取进 `Function.claims`,从 body 移除,不参与运行。核心标记计数不变,`CORE_CONSTRUCTS` 不增行;`layers.md` 的 Language 清单补记该角色。
|
||||
|
||||
2. **可证子集显式封闭**:无 `while`、无递归、无动态派发(插件、变量函数名、`code` 值调用)。越界函数被跳过(`rejected`),不降级成不透明块。外部操作是 `Env := Op → Val` 参数,不是公理;后置条件只能来自 `假设` 表并成为定理前提。
|
||||
|
||||
3. **Lean 是唯一能产生 `proved` 的判定器**。离线判定只到 `checked`,且被限制在一个极小的片段(路径枚举、轨迹、字面结果、命题组合、单变量区间),凡是离线判定为真的定理都必须同时生成 Lean 脚本。运行期若 Lean 可用则复核;离线 `checked` 而 Lean 未关闭视为内部错误(`proof.divergence`),以 Lean 为准并退出非零。
|
||||
|
||||
4. **顾问式,不强制**。默认退出码只对"作者写下的定理未被关闭"(`unproved`)与工具错误非零;缺工具链、`rejected`、`unverified` 默认 0。需要严格覆盖的调用方显式传 `--require-lean`。规范与技能手册**推荐**在发布 SKILL 前运行,但不设为门禁。
|
||||
|
||||
5. **`prove` 不执行被证程序**。只读源码、写缓存与 `--emit` 目录;这一点由测试夹具(带 `fs.write` 的函数)守住。
|
||||
|
||||
## 备选与取舍
|
||||
|
||||
| 备选 | 否决理由 |
|
||||
|---|---|
|
||||
| frontmatter `proof:` 块 | 丢函数作用域与行级锚点;多函数文件无法分派;诊断指不回具体行 |
|
||||
| `# 证明` 标题 | `#` 是对象、`##` 是函数;新增"标题=命题"破坏"标题即可调用单元"的既有习惯,还会进命名空间 |
|
||||
| ` ```proof ` 围栏 | 代码围栏必须跟在空赋值后,为写定理先造死变量,比表更别扭;且会被当作可执行值 |
|
||||
| 普通注释承载定理 | 注释不参与语义,无法可靠区分说明与定理,拿不到行锚点 |
|
||||
| 旁挂 `.proof.md` | 把真理拆成两份,违背"文档与代码同一份"的项目前提 |
|
||||
| 细化类型(refinement types) | 语义增量过大,且与既有契约表形成两份作者真相 |
|
||||
| 强制门禁(proved 才能发布) | 与"降低审核难度"的目标冲突;无 Lean 的团队会绕过工具 |
|
||||
|
||||
## 后果
|
||||
|
||||
**正面**
|
||||
|
||||
- 作者在一个地方写清"这条编排保证什么",机器可判定、行号可定位;
|
||||
- 定理表与契约表同一提取路径,`check` / `view` / `catalog` 可逐步接入,不产生第二套声明;
|
||||
- 外部依赖以假设形式显式化,证书是本项目一贯的"可复核证据";
|
||||
- 不新增核心标记,守卫测试与文档计数不膨胀。
|
||||
|
||||
**负面 / 代价**
|
||||
|
||||
- 新增一个语言层语义角色与一个 CLI 命令,需要 ADR + 测试 + 文档(本 ADR 即准入材料);
|
||||
- 离线判定器是新代码,必须长期用 Lean 语料护栏,防止"过度自信";
|
||||
- 作者可能误以为定理会在运行时生效——需要文档、`view` 与 `check` 三处反复澄清;
|
||||
- `proved` 容易被读成"整份 SKILL 安全"——README 必须写死"只对陈述负责"。
|
||||
|
||||
## 语义增量清单
|
||||
|
||||
| 新增 | 是否进运行时 | 说明 |
|
||||
|---|---|---|
|
||||
| `Function.claims` | 否 | 与 `Function.contract` 同类的声明元数据 |
|
||||
| `结果` / `轨迹` 与 `包含` / `长度` / `下标` | 否 | 仅定理作用域;与普通表达式作用域隔离 |
|
||||
| `check --proof` | 否 | 静态校验,默认关 |
|
||||
|
||||
不新增:求值规则、作用域规则、调用约定、核心标记、类型系统扩展。同名遮蔽(参数或局部变量叫 `结果`/`轨迹`)一律报 `proof.name_shadow`,不做隐式优先。
|
||||
|
||||
## 验收(摘要)
|
||||
|
||||
- 核心表面:`cargo test --test core_surface` 不变红;`CORE_CONSTRUCTS` 计数不变。
|
||||
- 单调性:语料中每条离线 `checked` 的定理,Lean 均 `proved`;分歧为 0。
|
||||
- 不执行:带 `fs.write` 的夹具在 `prove` 后无副作用。
|
||||
- 确定性:同输入两次 `emit` 字节一致。
|
||||
- 诚实性:文本、JSON、证书三处对 `checked`/`proved` 的措辞一致。
|
||||
|
||||
## 未决(不阻塞实现)
|
||||
|
||||
- `假设` 表是否需要扩展列(`来源`、`责任方`)。
|
||||
- `--all` 的聚合粒度(按文件/按函数)。
|
||||
- 证书是否需要签名,以及签名由谁持有。
|
||||
@@ -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,7 @@
|
||||
# 语义评估:参数能否从上下文推断(含叙述式调用)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留参数来源可见、避免隐藏调用者环境的边界;下文已被否决的 L0 建议不可重新启用。自然语言只连接和解释,不能成为隐式执行触发器;当前指导见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
|
||||
|
||||
@@ -36,7 +36,8 @@ type: llm
|
||||
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
|
||||
api_key: ${secret.OPENAI_API_KEY!}
|
||||
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
|
||||
import sys:lib/sys.mq.md
|
||||
import:
|
||||
sys: lib/sys.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
|
||||
|
||||
> **2026-10-23 审阅裁决**:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认 `[键](集合)`。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.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 演示包含这些交互。
|
||||
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **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`。
|
||||
@@ -156,7 +159,8 @@ source: &str (+ optional import map)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -209,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`。
|
||||
|
||||
---
|
||||
|
||||
@@ -250,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/`)。
|
||||
|
||||
---
|
||||
|
||||
@@ -260,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` |
|
||||
|
||||
---
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 调用实参:具名与位置
|
||||
|
||||
> **2026-10-23 适用范围校正**:本文保留早期调用尾部规则和历史示例,不是 v2.1 全部调用语法。当前已有 `f(args)` 及具名实参;默认紧邻 `](` 是描述包裹 payload,不再是下文所述的 Classic 取元。语法审阅与开发取舍见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),当前行为须由默认模式测试复核。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留显式标记和正文默认安全;性能数值是旧实验,不作为当前基准。持久跨文档接口优先具名参数,但不禁止位置参数;反引号声明与顺序改变可能是接口变化。当前调用与开发方向见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未改代码) |
|
||||
|
||||
@@ -3,22 +3,24 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 日期 | 2026-09-22;2026-10-23 校正 v2.1 默认链接语义 |
|
||||
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
|
||||
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
|
||||
|
||||
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
|
||||
|
||||
> **版本边界**:构造 ID 是历史守卫标识,不是固定不变的语义说明。`link-index` ID 暂保留以匹配注册表,但默认 `[]()` 已是描述包裹 payload;旧索引语义仅属于显式 Classic 兼容路径。未来步骤/知识投影见[文档原生指导](document-native-development-guide.md),不要把目标能力当作当前已实现。核心数量之外,还要审查上下文例外和作者负担。
|
||||
|
||||
## 1. 行构造
|
||||
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
| `narrative` | 无标记文字 | 叙述(不执行) | 段落内延续到空行;普通叙述不触发执行;未来知识引用投影也不改变此权限边界 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
|
||||
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
|
||||
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [说明](遍历 集合 为 项)`;描述不是绑定变量名 | `tests/structure/loop.mq.md` |
|
||||
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
|
||||
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
|
||||
@@ -30,12 +32,12 @@
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
|
||||
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 粗体内代码判别序:赋值 → 调用 → 表达式;不取消调用行、返回等其它显式执行入口 | `tests/markup-v03/multi-bold.mq.md` |
|
||||
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
|
||||
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
|
||||
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
|
||||
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
|
||||
| `link-index` | `[描述](表达式)` | 描述包裹 payload(历史 ID) | 默认 Occlusion;取元可写 `[说明](access(集合, 键))`,不按描述取键;循环载荷见上 | `tests/occlusion/access-and-loop.mq.md` |
|
||||
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;紧邻 `](` 的默认语义为 payload 遮蔽,不是旧索引 | `tests/structure/bracket-call.mq.md` |
|
||||
| `footnote-index` | `集合[^键]` | 兼容取元 | 保留既有能力;新代码优先 `access(...)`,需要解释时包裹描述,不再推荐旧 `[键](集合)` | `tests/structure/footnote-index.mq.md` |
|
||||
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
|
||||
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
|
||||
|
||||
@@ -80,7 +80,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;嵌套 `import:` 映射与其它 YAML 键一并解析 |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
|
||||
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
|
||||
|
||||
@@ -0,0 +1,284 @@
|
||||
# Marqdo 文档原生开发指导:让知识的表达、执行与复用成为同一件事
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | 下一阶段开发指导与规划修订;不表示下述目标接口已经实现 |
|
||||
| 日期 / 审阅基线 | 2026-10-23 / `main`,`7674ebb`;继承缺口审计的 `434be9f` 代码证据 |
|
||||
| 原始意图 | [009](../next/009.md)、[附属设计](../next/Marqdo_Executable_Knowledge_Design.md)、[附属示例](../next/Marqdo_Executable_Knowledge_Example.md) |
|
||||
| 配套实施文件 | [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)、[缺口与交付路线](../roadmap/executable-knowledge-gaps-2026-10-23.md) |
|
||||
| 本轮边界 | 校正开发方向、作者体验、AI 工作协议和验收;不新增语法,不宣称实现新能力 |
|
||||
|
||||
## 1. 审阅结论与规范关系
|
||||
|
||||
Marqdo 的优势不在于给传统程序换一套 Markdown 符号,而在于:**读者解释知识、作者修改知识、程序执行知识、AI 查找并复用知识,能够指向同一份有结构的文档和其中的同一步。** 标题、叙述、表格、链接描述、输入输出、来源及执行行为不应分散在彼此手工同步的系统中。
|
||||
|
||||
现有规划没有放弃这一目标,但工程排序存在偏移:把身份、图、证据、锁、句柄、晋升全部铺完,再验证人和 AI 是否更容易使用。这样可能交付一个功能齐全的制品管理系统,却让文档作者承担另一套注册、声明、审核和配置工作。需要改变交付方法,不必推翻确定性编译、绑定和权限机制。
|
||||
|
||||
本指导规定**为何开发、作者维护什么、怎样证明值得开发**;详细规范规定语义模型与执行约束;路线图规定当前缺口、切片与完成证据。三者不是三套平行设计。遇到冲突,依次采用:`009` 的产品意图 → 本指导对作者负担、场景分级和交付次序的修订 → 详细规范的工程规则 → 附属概念示例。当前代码与测试证明“已实现什么”,不能把代码局限升级为永久语言禁令;原始讨论保留,不据其重新引入已被否决的方案。
|
||||
|
||||
### 1.1 方向修订清单
|
||||
|
||||
| 容易偏移的做法 | 修订后的要求 | 必须保留的技术约束 |
|
||||
|---|---|---|
|
||||
| 先做完整知识治理平台,再给作者使用 | 从一篇可读、可运行、可定位步骤的文档交付,逐层扩展 | 每个已支持路径都有准确的目标和效应边界 |
|
||||
| 为进入知识库再写 YAML、注册表和索引 | 从源码推导;只有不能推导的领域事实才需作者补充 | 生成物有版本,可重建,可检查来源 |
|
||||
| 所有逻辑先封装成可登记函数/类 | 一次性逻辑直接写;需要命名、解释或复用时逐步提取 | 作用域、形参、返回与副作用明确 |
|
||||
| 所有调用先审核、锁定、签发远程凭据 | 本地探索、项目复用、严格业务、远程执行分级 | 精确目标、运行时权限不能被标签或模型绕过 |
|
||||
| AI 只能搜文档、填工具参数 | AI 可以读步骤、组合、选择候选、局部修改、提取和验证 | 模型的选择必须转成显式目标,由编译器校验 |
|
||||
| 为“独特”拒绝普通调用或新增更多标记 | 保留简单 payload;让 Markdown 结构提供程序之外的信息 | 无第二套表达式文法,无裸词隐式执行 |
|
||||
| 核心构造数量不增长就是简单 | 同时检查上下文例外、记忆负担和诊断成本 | 新构造需 ADR;不靠把新规则藏进旧构造绕过审查 |
|
||||
|
||||
### 1.2 四个不能互相替代的完成条件
|
||||
|
||||
1. **读得懂**:不打开生成图,也能从源文件看出目的、关键步骤、参数角色和限制。
|
||||
2. **执行同一件事**:标签表达意图,payload 决定计算;运行 trace 能回到源码步骤,不能执行另一个同名目标。
|
||||
3. **改得动**:人或 AI 能修改一个明确步骤,看到影响与验证结果,不必重写整份文档或同步多份签名。
|
||||
4. **复用得对**:找到已有能力后实际调用它;不满足条件时给出具体拒绝原因,而非用复制源码掩盖失败。
|
||||
|
||||
“更适合 AI”是待验证的产品假设,不是 Markdown 文件后缀自动赋予的性质。正确性和作者成本优先于 token 下降;错误复用更便宜不算优化。
|
||||
|
||||
## 2. 语法审查的保留、修正与暂缓
|
||||
|
||||
以下裁决针对审查结论的适用范围,不重写历史实验记录。旧文档中的原型、性能数值和当时的 `Value`/AST 限制,不能直接当作 v2.1 的规范或测试结果。
|
||||
|
||||
| 审查材料 | 保留的洞见 | 需要修正的外推 / 本轮处置 |
|
||||
|---|---|---|
|
||||
| [函数即命名](function-as-naming-philosophy.md) | 从正文计算出发,命名应降低理解和复用成本;避免无意义包装 | “具名给值缺失”是历史观察,当前有具名参数;替换模型是教学解释,不意味着禁止递归、前向引用或必须文本展开 |
|
||||
| [方括号作为标签](bracket-as-label-evaluation.md) | 描述与 payload 共址;标签帮助解释、检索和拆步骤 | Classic 冲突是迁移历史,不据此恢复默认 `[键](集合)`;不强制每个常量或子表达式都有标签 |
|
||||
| [圆括号与可读调用](paren-call-and-readable-invocation.md) | 调用标记应明确;保留 `f(args)` 的局部可读性 | 原型撤回不代表现有版本缺少该能力;Marqdo 的独特性不依赖消灭熟悉的表达式形式 |
|
||||
| [从标记推导调用](call-syntax-from-marks.md) | 语义成分有明确标记;自然语言是连接与解释,不参与猜测调用 | 持久跨文档接口优先具名实参;短而稳定的位置参数仍合法。推断参数的声明次序变化属于接口变化,不承诺任意润色都无影响 |
|
||||
| [环境参数](ambient-parameters-evaluation.md) | 参数来源应可见,避免调用者隐式环境影响复用 | 文档顶部已否决 L0 裸“执行”触发,正文旧建议不能重新生效;文件级常量也须有明确绑定与依赖,不变成动态作用域 |
|
||||
| [函数作为值](functions-as-values-evaluation.md) | 区分名称数据、一等函数、有限查表;避免无需求增加核心复杂度 | “匿名函数必不能索引”“动态调用必然破坏契约”不是普遍定理。将来可研究稳定节点身份与运行时契约;本轮不引入闭包,也不永久禁止 |
|
||||
| [函数作为表格](function-as-table-semantics.md) | 数据表几何有既定含义;契约表不可另造一份参数声明 | 不把表格全部变成函数,也不把“现有实现不支持”写成“表格不能计算”;有限决策表先评估库方案,只有明确角色和歧义测试后才讨论语言扩展 |
|
||||
| [核心表面](core-surface.md)、[分层](layers.md) | 核心小、标记可解释、构造有测试与准入流程 | 清单中的旧取元/循环说明需随迁移更新;固定数量不等于低认知成本,守卫通过也不证明文档语义正确 |
|
||||
| [链接设计](link-syntax.md)、[告警疲劳](warning-fatigue-control.md) | 单一 payload 文法;标签漂移可提示;默认安静、按需严格 | 标签不是纯粹可丢弃的注释,也不是事实证明;不做每次运行重复的批准仪式,不靠词汇相似度证明描述与代码一致 |
|
||||
|
||||
### 2.1 继续冻结的语法边界
|
||||
|
||||
- 默认 `[]()` 是描述包裹 payload;旧取元只能在显式历史兼容路径下解释。现行取元用 `access(...)` 等已支持形式;循环使用明确遍历载荷。
|
||||
- `[]()` 不等于“仅函数调用”:计算、取元、调用、遍历、叙述引用都需要各自语义角色,不能只收集 call 边就宣称完成知识步骤。
|
||||
- 正文引用与可执行位置有不同调度权限。普通句子不因出现“执行”“发送”或工具名而运行;正文解析成引用也不自动求值。
|
||||
- 不把所有 `#` 解释成某种知识对象,或把继承悄悄变成实例关系。标题的既有语义必须兼容,IR 可区分 Type、Entity、Fact、Function。
|
||||
- 不给同一参数增加正文声明、签名表、工具 schema 三套作者真相。规范签名和工具 schema 是投影;契约表补充类型、约束和说明,不偷偷增加形参。
|
||||
- 可读源文件是硬要求;普通 Markdown 渲染器是否把含空格/嵌套表达式的链接渲染成可点击链接是另一件事。不能承诺全部标准渲染器理解执行语义。
|
||||
|
||||
### 2.2 哪些编辑不能当成“只是改文案”
|
||||
|
||||
不含语义标记的普通叙述润色,应保持执行结果和实现摘要;标签改名应保留 payload 行为,但更新展示/检索内容。反引号声明、首次出现顺序、标题名称/层级、粗斜体、表格几何、契约、来源和适用范围的改变则可能影响程序或知识可信性。编辑器必须展示真实差异,不能统一标为 prose-only。
|
||||
|
||||
标签漂移诊断应说明“描述或实现可能需要复核”,不能自动替作者改写业务意图。自然语言一致性检查可作辅助建议,确定性检查仍需可定位的符号、类型、契约或测试证据。
|
||||
|
||||
## 3. 作者工作流:先写清楚,再获得复用能力
|
||||
|
||||
### 3.1 一次性计算不需要预先建知识模型
|
||||
|
||||
下面是当前默认语法的完整最小程序。无模式开关、无项目注册、无知识 ID、无锁文件。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这是演示订单,单价与数量直接写在计算处。
|
||||
|
||||
**小计 = [两件商品的小计](2 * 30)**
|
||||
> print text=`小计`
|
||||
```
|
||||
|
||||
可读意图和精确计算共址。这个标签值得保留,因为它说明本次计算的业务角色;不要求把 `2`、`30`、乘法分别命名。
|
||||
|
||||
### 3.2 需要解释或复用时才提取命名能力
|
||||
|
||||
```markdown
|
||||
## 商品小计
|
||||
|
||||
根据购买数量`数量`和商品单价`单价`计算小计。
|
||||
|
||||
*[按数量与单价计算](数量 * 单价)*
|
||||
|
||||
# main
|
||||
|
||||
计算同一笔演示订单。
|
||||
|
||||
**小计 = [两件商品的小计](商品小计(数量=2, 单价=30))**
|
||||
> print text=`小计`
|
||||
```
|
||||
|
||||
两个完整程序在本轮本地现有 `target/debug/marqdo` 上分别以 Tree 和 Bytecode 执行,均输出 `60`。这仅验证基础语法,不证明步骤身份、重构工具或 Agent 闭环已经实现;也不是全仓测试报告。可将各块保存为 `.mq.md` 后用 `marqdo run 文件 --backend tree` / `--backend bytecode` 复核。
|
||||
|
||||
**后续工具目标**:从选中表达式提取为标题单元,推导自由变量为参数、保持求值顺序与 effect 次数、生成具名调用,并给出可审阅补丁。反向内联也应保留契约和来源关联;无法证明安全的捕获变量、递归、控制流、动态目标或有副作用表达式,先拒绝自动变换并说明原因,不伪称等价。
|
||||
|
||||
### 3.3 跨文档复用与事实说明分别增长
|
||||
|
||||
当第二篇文档需要这段计算,才提取模块并显式 import;不要为十行单文件强制创建 `corpus/knowledge/apps` 目录树。项目索引按约定发现,明确边界或外部来源时再加入配置。
|
||||
|
||||
当“商品小计”依赖政策、时间、币种等条件,再就地补契约与来源。简单乘法不要求假造现实来源;“某商店当前折扣为九折”则不能仅凭函数返回 `0.9` 声称真实。
|
||||
|
||||
正文可以说明结果为何成立,目标是引用同一能力和同一次受控执行的结果,而非手抄另一份公式。正文引用 AST、结果投影和绑定身份尚需开发;完整业务链使用[目标示例](../next/Marqdo_Executable_Knowledge_Example.md)验收,不把它冒充当前全部可运行的教程。
|
||||
|
||||
### 3.4 维护时看到知识变化,而不只是文件变化
|
||||
|
||||
目标维护流程:修改上游规则 → 显示受影响的计算、正文陈述和消费者 → 执行相关测试 → 展示结果/证据/接口各自变化 → 按使用策略接受更新。普通显示文案变更不应触发全库业务审批;证据过期也不必使无关纯工具全部失效。
|
||||
|
||||
## 4. 人维护语义,编译器维护机械关联
|
||||
|
||||
| 信息 | 作者责任 | 编译器 / 工具责任 |
|
||||
|---|---|---|
|
||||
| 目的与步骤 | 有帮助的标题、叙述、标签;避免空泛重复 | 保留源位置和层级,生成步骤投影,不要求手工节点注册 |
|
||||
| 输入输出 | 一份参数来源和必要契约;领域单位不能靠猜 | 推断规范签名、检查调用、生成 schema 和签名视图 |
|
||||
| 目标与依赖 | 显式 import、可读名称、必要消歧 | 绑定唯一 SymbolId,生成依赖边与闭包;不要求手写 ID |
|
||||
| 效应 | 扩展作者声明宿主能力;业务作者必要时收窄允许范围 | 汇总直接及传递效应;未知不得推断 pure;运行时执行能力上限 |
|
||||
| 事实与来源 | 原始资料、范围、有效期、人工审阅等不可推导信息 | 关联来源、记录验证事件、传播失效;不将文件路径视为事实证明 |
|
||||
| 身份与版本 | 有意移动/更名时确认必要迁移 | 区分身份与内容摘要;报告歧义,不靠猜测维持假稳定 |
|
||||
| view / AI 索引 | 不维护第二份可执行描述 | 同一语义模型投影;显示生成代、验证政策和缺失字段 |
|
||||
|
||||
生成信息不等于免费:首次编译、缓存修复、错误定位都要可理解。失败时应回到源文档中可修改的位置,而不是只报内部 Artifact 字段名。
|
||||
|
||||
稳定身份要诚实:同一次编译内引用和 trace 必须一致;普通文本编辑不应打乱无关节点;复制相似步骤、跨文件移动等无法唯一识别时,要求确认迁移或明确生成新身份。禁止用文本相似度悄悄继承已审核的知识身份。
|
||||
|
||||
## 5. AI 原生工作协议:读步骤、改步骤、验证步骤
|
||||
|
||||
本节是**待实现的协议约束**,不是新增 CLI 命令清单。优先扩展现有 MLSP、view、EKC 和 Agent 工作簿,不另造一套 Agent 框架或知识库。
|
||||
|
||||
### 5.1 发现后的最小上下文包
|
||||
|
||||
一次检索返回可展开的上下文卡,而非强制倾倒整个文件或只给函数 schema:
|
||||
|
||||
1. 标题路径、任务相关叙述、标签和精确源码片段;
|
||||
2. SymbolId/步骤节点、source span、源码摘要、生成代;
|
||||
3. 输入角色、返回、单位、默认值和适用条件;
|
||||
4. 直接依赖、效应、必要来源及分层验证状态;
|
||||
5. 支持该能力的例子/测试,相关失败经验、禁用条件和替代能力;
|
||||
6. 还缺哪些检查、能否在当前 policy 下运行、为何被拒绝。
|
||||
|
||||
来源不可用、字段未推导、上下文被截断都须显式标识。按预算可展开依赖,但不能悄悄省略改变适用性或权限的重要信息。原始资料及标签是内容,不是可以覆盖 Agent 策略的指令。
|
||||
|
||||
### 5.2 复用、适配、新建的分界
|
||||
|
||||
- **REUSE**:AI 可根据任务选候选,提交精确目标与输入;resolver 确认目标、契约、适用性、版本和 effect,执行既有制品。复用不靠“没有生成文件”推断,必须有实际调用 trace。
|
||||
- **ADAPT**:已有能力接近但不适用;说明差异,保留依赖/来源关联,在局部副本或补丁中改变必要部分,再验证。不为了通过测试改写原始来源或放宽全局策略。
|
||||
- **CREATE**:没有合适候选或明确需要新语义;记录检索范围和失败原因,在任务预算及写权限允许时新建。不能把检索服务故障当作“仓库没有能力”。
|
||||
- **ASK / STOP**:缺业务决策、权限或关键证据时报告具体缺口。编译器无法决定的真实意图不交给近似匹配默默补全。
|
||||
|
||||
AI 并非只能发现和解释。它可以提出精确目标、组合已有能力、改进表达、重构及补测试;不能以自然语言自报正确来替代执行验证,也不能把含糊名称传给后端任意选一个目标。
|
||||
|
||||
### 5.3 局部修改的事务边界
|
||||
|
||||
编辑请求至少携带目标文件/节点、期望源码摘要、补丁范围和预期行为变化。应用前检查摘要,源已变化则重新定位和审阅,不覆盖用户改动。应用后重新解析受影响文档,生成语义 diff:参数/返回、目标、effect、控制流、证据与依赖是否改变。
|
||||
|
||||
对“只改措辞”请求,检测到接口或实现改变时停止自动合并;对“改计算”请求,运行相关正负例并展示影响。原始文本、格式与未知 metadata 尽量保留,不通过整篇重生成来完成一行修改。禁止修改生成图伪装修复源码。
|
||||
|
||||
首个试点只支持可确定定位的纯计算步骤与普通函数,不等待通用 AST 编辑器、跨项目事务或完整知识治理。安全拒绝超范围输入也属于验收。
|
||||
|
||||
### 5.4 解释和负知识必须有落点
|
||||
|
||||
解释结果应关联到“哪一步、用了哪个目标、哪些输入、哪份来源、哪次验证”,区分已执行观察和模型推断。运行 trace 可以证明程序路径,不能证明任意自然语言论证正确。
|
||||
|
||||
失败经验需要保存适用范围、触发条件、关联能力、原因与失效时间/版本。例如“此折扣不适用于退款”应在查询定价能力时可见,而不是埋在另一份聊天记录里。先由普通文档与结构化关联承载,不先新增通用推理语言;过期负知识也要撤销,不能永久拦截修复后的能力。
|
||||
|
||||
## 6. 渐进严格:不把治理门槛塞进每一行正文
|
||||
|
||||
下面是目标政策分级,不是当前已有四种 CLI 模式。政策由项目/宿主配置和调用上下文选定,源文档保持同一种语法。
|
||||
|
||||
| 场景 | 必需条件 | 默认不要求 |
|
||||
|---|---|---|
|
||||
| 本地探索、单文件运行 | 明确语法与目标、已有运行时契约、宿主能力限制;如实显示未知状态 | lock、来源、ready 晋升、远程签名句柄 |
|
||||
| 项目内自动复用 | 精确绑定、输入/适用性检查、效应许可、状态满足所选政策、执行 trace | 所有纯工具都有人审证据、每次独立确认 |
|
||||
| 严格业务/可复现任务 | 相关依赖与证据锁定、必要验证新鲜度、受控环境和审计;明确不可重放部分 | 对无关文案变化重审整个项目 |
|
||||
| 远程/多租户/不受信调用方 | 上述相关约束,加可信授权主体、范围、服务端能力上限、撤销/期限与防伪设计 | 把客户端提交的 `allow_effects` 当授权本身 |
|
||||
|
||||
`ready` 是“对某项 policy 和输入/上下文已具备复用条件”,不是永久万能认证。未验证的本地草稿可以被检索、查看和按明确权限试跑;不能冒充满足严格政策的可复用事实。测试通过与事实证实分别报告。
|
||||
|
||||
正文 `check/view static` 不执行外部效应。用户主动打开的纯预览可复用项目或会话已有政策,不要求每个链接弹窗;effectful 运行始终受宿主能力和明确执行上下文控制。锁和摘要是完整性机制,不自动等于远程授权;可信本地引用无需先搭建凭据服务。
|
||||
|
||||
## 7. 交付切片:每片都有文档作者与 AI 能看见的结果
|
||||
|
||||
编号与[缺口路线图 §7](../roadmap/executable-knowledge-gaps-2026-10-23.md#7-依赖顺序与可合并切片)一致;G 编号沿用现状证据,M0–M6 保留为工程能力映射,不再被理解为必须全部串行完成的墙。
|
||||
|
||||
### S0 作者基线与最小语料
|
||||
|
||||
- 选定单文件计算、提取函数、两文档引用、表格取元/遍历、业务政策及拒绝复用六类任务;记录当前写法、输出、诊断和作者重复维护项。
|
||||
- 优先整理 `doc/README`、核心语法卡片、教程与运行示例的版本状态;不要先扩展通用库数量。
|
||||
- 为最小样例建立无网络门禁。100 单元及更大语料逐步增长,不阻塞首个可读文档切片。
|
||||
- 完成证据:别人按当前入口能写出正确默认语法;已实现与预期失败分开报告,不能把待实现测试跳过计为成功。
|
||||
|
||||
### S1 可读步骤与唯一目标
|
||||
|
||||
- 主要落点:`src/parse/`、`src/ast.rs`、`src/sema/`、`src/knowledge/compile.rs`、`src/view/`。
|
||||
- 在最小故事内联合完成 G01/G03:保留 label、payload、上下文和跨度;每类步骤有输入输出与依赖投影;旧 EKC 查询索引不再覆盖语义图。
|
||||
- 普通导航、正文引用、可执行表达式、循环分别处理,正文保持惰性。先确保支持范围内同一引用在源码、view、图中是同一个目标,再扩展覆盖范围。
|
||||
- 完成证据:作者能从渲染步骤返回对应源码;同名目标不误连;计算/取元/循环不是伪造的 call;重复构建可对照;未支持上下文明示。
|
||||
|
||||
### S2 确定执行与早期 AI 复用试点
|
||||
|
||||
- 主要落点:`src/sema/`、`src/interp.rs`、`src/bytecode/`、`src/mlsp.rs` 与现有 Agent 入口。
|
||||
- 完成静态普通函数、显式 import、关联函数的 BoundCall 主链;G02 与 G06 的效应安全下限不可延期。小范围可先用明确纯操作白名单,未知路径必须拒绝纯证明,而非猜 pure。
|
||||
- 实现最小上下文卡与本地绑定引用;以 stub/no-LLM 测试验证协议,然后用现有 Agent 跑相同故事。无需先完成远程鉴权平台或全面来源审核。
|
||||
- 完成证据:同一需求实际调用既有函数,不新增同义实现;两个后端 trace 对上图中目标;改目标、错误输入、未知效应、权限不足不能静默执行。
|
||||
|
||||
### S3 局部编辑、提取与库可读性
|
||||
|
||||
- 主要落点:MLSP 编辑/定位、相关 sema/检查入口、`lib/`、`ext/`、教程与测试。
|
||||
- 按 §5.3 实现受摘要保护的局部修改和语义 diff;实现受限纯表达式提取,或明确标为待实现,不用人工演示冒充工具能力。
|
||||
- 迁移标准库/扩展时删掉重复包装与噪音标签,保留有意义的业务步骤、契约和负例;中英镜像含义一致。兼容旧调用接口,不用增加旧语法解释救迁移遗漏。
|
||||
- 完成证据:同义润色不改执行;改反引号声明能检测签名变化;表达式提取前后结果/effect 次数一致;冲突补丁拒绝;CLI、库、扩展与 view 既有能力继续通过。
|
||||
|
||||
### S4 业务知识的来源与适用性
|
||||
|
||||
- 主要落点:契约、SourceRef/VerificationRecord、验证事件、Agent 候选解释;完成 G05 与 G07 的项目政策部分。
|
||||
- 选定书店案例的币种、数量边界、会员范围与政策有效期;给 schema、拒绝诊断及可运行负例,不泛化为全能业务规则语言。
|
||||
- 同步补齐传递效应与相关负知识;生成契约/状态展示,减少作者重复填写。
|
||||
- 完成证据:同一计算因输入或证据不同而正确通过/拒绝;来源过期不被 `tests=passed` 覆盖;普通纯工具无需虚构 SourceRef。
|
||||
|
||||
### S5 变化传播与严格复用
|
||||
|
||||
- 主要落点:`src/sema/lock.rs`、图/impact、产物提交与消费者;完成 G04/G08 和严格 handle 复核。
|
||||
- 区分身份/接口/实现/证据/闭包,给出可读升级 diff;整代快照保证消费者不会读取混代数据。并发读写一旦开放,该一致性就是前置条件,不能等到此片才承认风险。
|
||||
- 完成证据:修改依赖政策后,下游计算和正文解释进入影响集合;文案变化不误判实现变化;并发编辑或构建崩溃不导致错目标执行;锁不声称重放网络/随机/LLM。
|
||||
|
||||
### S6 生态验收与发布
|
||||
|
||||
- G10/G11 从 S0 起每片执行;S6 汇总兼容矩阵、真实工作流和打包后冒烟,不把测试留到最后。
|
||||
- G12 随实际规模需求推进;远程凭据/多租户是有条件的独立交付。它们不阻塞受信本地试点,也不得被本地通过的测试覆盖为“已安全支持”。
|
||||
- 完成证据:当前默认语法的 lib/ext/CLI/MLSP/view/WASM 等受影响消费者有明确结果;目标示例中的已发布子集实际可运行,未发布部分保留状态;发布声明与证据一一对应。
|
||||
|
||||
## 8. 验证 Marqdo 优势,而不只验证组件存在
|
||||
|
||||
### 8.1 必须收集的产品指标
|
||||
|
||||
| 维度 | 记录方法 | 失败信号 |
|
||||
|---|---|---|
|
||||
| 作者负担 | 完成同一任务所需手写声明、重复字段、配置、跳转和确认次数 | 简单本地算式也必须填写制品清单 |
|
||||
| 阅读与定位 | 给定问题,定位正确步骤/限制的准确率、耗时与上下文量 | 只看 label 会误导,必须打开生成 JSON 才理解源文档 |
|
||||
| 可修改性 | 修改范围、无关 diff、语义变化检测率、冲突覆盖数 | 为改一步而重生成全文件;措辞调整偷偷改变接口 |
|
||||
| 复用质量 | 已有能力发现率、实际调用率、重复实现率、误用率 | 检索命中却重新写代码;正确拒绝算成任务失败而被优化掉 |
|
||||
| 知识可追溯性 | 结果关联目标、步骤、输入、来源和验证的覆盖率 | `tested` 被当作事实正确;解释引用未执行的步骤 |
|
||||
| 总成本 | 正确完成任务的 token、工具调用、轮次、总耗时及编译成本 | 只报模型 tokens,隐藏额外注册/审核/修复成本 |
|
||||
|
||||
### 8.2 对照实验与门槛
|
||||
|
||||
1. 固定任务、可访问能力、输入数据、模型版本、工具能力、预算与超时;比较普通 Markdown+代码/RAG、当前 EKC 和新方案。不能给新方案更多现成实现再声称语法更优。
|
||||
2. 任务包括成功复用、同名冲突、近似但不适用、未知 effect、过期来源、正文不执行、局部修改及库升级。加入自然语言诱导绕过 policy 的负例。
|
||||
3. 先测确定性协议,再测多次 AI 运行,保留种子(支持时)、原始 trace、版本、失败样本与分布;小样本不夸大收益。
|
||||
4. 正确目标、无越权和正文无外部 effect 是硬门槛。原有兼容测试不得降低;效率阈值先测基线再登记,不捏造提升百分比。
|
||||
5. 若作者负担增加或误用率上升,回到交互/语义设计分析原因,不能只用“更多治理更安全”或“模型更便宜”解释过去。
|
||||
|
||||
### 8.3 发布声明分层
|
||||
|
||||
- “支持新语法”需语法、迁移、双后端与库兼容证据,不意味着完整知识复用已经交付。
|
||||
- “本地确定性知识复用”需 S1/S2 支持范围内的端到端与拒绝用例;范围外路径显式不支持,不能回落为模糊执行。
|
||||
- “严格业务知识复用”还需相关 S4/S5 来源、适用性、失效、锁和一致性证据。
|
||||
- “安全远程知识执行”需额外的授权、能力上限、凭据/撤销及隔离测试;本地 JSON handle 不等于远程安全。
|
||||
|
||||
## 9. 每个开发变更必须回答的问题
|
||||
|
||||
提交设计或实现时给出一份短而具体的审阅记录:
|
||||
|
||||
- 用户要读/写/改/复用的知识是什么?附源文档前后对照,不只给内部结构图。
|
||||
- 利用了哪种文档原生信息?若只增加通用框架能力,与主线的必要关系是什么?
|
||||
- 新增了哪些作者必须手工维护的信息?为什么不能从现有语义推导?
|
||||
- 是否改变标记、作用域、求值顺序、形参顺序、表格几何或正文安全?分别有哪些测试?
|
||||
- 人、CLI、view、图和 Agent 是否看到同一目标与状态?失败能否回到源码修复?
|
||||
- AI 的正确复用/局部编辑如何证明?哪些部分仍需模型判断,哪些由编译器决定?
|
||||
- 标准库和扩展是否先迁移?是否保住既有公开接口、输出与 effect?
|
||||
- 这是已实现、受限试点还是设计目标?文档和发布声明是否一致?
|
||||
|
||||
**准入原则**:内部可以使用成熟编译器、数据库和协议技术;外部必须减少知识在“说明、程序、索引、工具描述”之间的重复翻译。独特性由这条链的实际收益体现,不由新符号数量或与其他语言不同的程度体现。
|
||||