Compare commits
428
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
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 | ||
|
|
bf76e069ee | ||
|
|
9015de26e5 | ||
|
|
8c24d96626 | ||
|
|
4a2f5bf226 | ||
|
|
86e921e959 | ||
|
|
b196a44685 | ||
|
|
c8ed5bffb7 | ||
|
|
fb135ae2f8 | ||
|
|
69fcdd6227 | ||
|
|
deac53d0f5 | ||
|
|
932403237a | ||
|
|
a14a6e221d | ||
|
|
8b0ea9ed7a | ||
|
|
6ae0d39e5a | ||
|
|
307c8efa81 | ||
|
|
34b0911218 | ||
|
|
4488a3cb70 | ||
|
|
9dbcc728b6 | ||
|
|
0405a60d68 | ||
|
|
409b8df2cb | ||
|
|
6bba0be6d2 | ||
|
|
1c90312c02 | ||
|
|
fd0cfcb566 | ||
|
|
6dd0ce47b1 | ||
|
|
1a94cc8490 | ||
|
|
11417c42e0 | ||
|
|
13012cac0e | ||
|
|
5a0f4ed747 | ||
|
|
05b8edc186 | ||
|
|
8926f7bed6 | ||
|
|
18b0c655f7 | ||
|
|
924885969f | ||
|
|
619271b8eb | ||
|
|
719b7a8d82 | ||
|
|
dfe99a10b4 | ||
|
|
fac68e85ea | ||
|
|
639b0ebcd1 | ||
|
|
2c4dac005c | ||
|
|
0ac661eef2 | ||
|
|
1dd74578b5 | ||
|
|
14114993c4 | ||
|
|
e80c944c40 | ||
|
|
30cd5a0833 | ||
|
|
e2068c2051 | ||
|
|
9cda80ee7d | ||
|
|
eae4815fc7 | ||
|
|
3260494e5c | ||
|
|
3330a0fc66 | ||
|
|
42a1a46383 | ||
|
|
b6629e5450 | ||
|
|
ecd7d5e433 | ||
|
|
aeb5a2a43d | ||
|
|
f2d651e063 | ||
|
|
b020b9d218 | ||
|
|
33a14d272c | ||
|
|
6ed70fd8b8 | ||
|
|
115d1f6c0b | ||
|
|
7dc5e56850 | ||
|
|
514caa55ae | ||
|
|
74908ebf04 | ||
|
|
0f852593bc | ||
|
|
34e2fb4f74 | ||
|
|
0e407b2bd3 | ||
|
|
e5e532d83f | ||
|
|
064522a338 | ||
|
|
c85f1a2829 | ||
|
|
a7266185b2 | ||
|
|
4d7c0bea1b | ||
|
|
53758ebd1c | ||
|
|
dff0b700ae | ||
|
|
4da07c1b26 | ||
|
|
78922102e4 | ||
|
|
064bae2c65 | ||
|
|
92b91ffc81 | ||
|
|
ab6648ae0e | ||
|
|
5acf026e0c | ||
|
|
8dcd69412f | ||
|
|
2a13e52981 | ||
|
|
9b269f6447 | ||
|
|
15362cb048 | ||
|
|
05d48f68a4 | ||
|
|
e4387259ba | ||
|
|
518f8e386b | ||
|
|
9da12c9093 | ||
|
|
e0d34669e0 | ||
|
|
0ba4d3d2d7 | ||
|
|
ad3ebf243a | ||
|
|
142d30ce08 | ||
|
|
4757b82edd | ||
|
|
bff2f53e52 | ||
|
|
fb28eee62f | ||
|
|
01468ad976 | ||
|
|
f3791d11b4 | ||
|
|
7fef690167 | ||
|
|
024cdee82a | ||
|
|
f666eaaf40 | ||
|
|
e6f05c7748 | ||
|
|
81f9ea0072 | ||
|
|
dbf3f3a14b | ||
|
|
654e89d98c | ||
|
|
be20629496 | ||
|
|
3223295841 | ||
|
|
beb5bdbe8c | ||
|
|
b8cb022018 | ||
|
|
b9e331cb31 | ||
|
|
476c2b607b | ||
|
|
d99b275336 | ||
|
|
1415aee08f | ||
|
|
0f2c12b636 | ||
|
|
9873df7099 | ||
|
|
3001ed7ba5 | ||
|
|
050d71927f | ||
|
|
7859170aec | ||
|
|
e32ff8f6b3 | ||
|
|
c21a28c3bc | ||
|
|
1e61dca9d8 | ||
|
|
ba675a4767 | ||
|
|
bfd468d5e3 | ||
|
|
8353ba38fe | ||
|
|
b43a08b2e2 | ||
|
|
1908bf1a53 | ||
|
|
c44ea38ae2 | ||
|
|
d489f7c088 | ||
|
|
a993cfd76a | ||
|
|
d5f826a8c8 | ||
|
|
0f72173d08 | ||
|
|
a707758d47 | ||
|
|
63bcb882a6 | ||
|
|
1bb16dd6db | ||
|
|
58ec2172d6 | ||
|
|
66926e9e0a | ||
|
|
dcf4c05663 | ||
|
|
f47a1e143a | ||
|
|
9cf98a98b5 | ||
|
|
f99d552d87 | ||
|
|
7d49c358c1 | ||
|
|
a32c0cd78f | ||
|
|
0a8f76d9b4 | ||
|
|
4e2419b598 | ||
|
|
f6374d1593 | ||
|
|
9ede4bc63d | ||
|
|
3ae8f2c843 | ||
|
|
e9c1a8a730 | ||
|
|
5554b1642c | ||
|
|
fe15603a91 | ||
|
|
1418742655 | ||
|
|
ed31a2b31d | ||
|
|
56ab52356f | ||
|
|
2e425c3010 | ||
|
|
46a0263d7f | ||
|
|
ff252fd469 | ||
|
|
67bac1bf02 | ||
|
|
33f8b94bb0 | ||
|
|
0ed57b6d54 | ||
|
|
c29d48f38c | ||
|
|
f1e82ce4e5 | ||
|
|
2d412e3bba | ||
|
|
46d78c6e15 | ||
|
|
81a14f9b38 | ||
|
|
88dc6d5a54 | ||
|
|
4a2d89406b | ||
|
|
d8d435fead | ||
|
|
1f8e61f3bf | ||
|
|
a9ee858f53 | ||
|
|
8489d90926 | ||
|
|
5272acaea0 | ||
|
|
cba51238b6 | ||
|
|
5fffb800f9 | ||
|
|
1a729eb9ec | ||
|
|
00c763300e | ||
|
|
224b3d4a66 | ||
|
|
81d26a265a | ||
|
|
5b599125d1 | ||
|
|
18d89d6cf2 | ||
|
|
199b5c532f | ||
|
|
db5f0e830b | ||
|
|
7a449c40b1 | ||
|
|
97fda7aa10 | ||
|
|
a49592a3ba | ||
|
|
ed9ac03c0c | ||
|
|
cb46ad7abe | ||
|
|
586975090b | ||
|
|
544805266b | ||
|
|
f3051fb536 | ||
|
|
86b183e2d7 | ||
|
|
8e23a5395a | ||
|
|
cab609ee91 | ||
|
|
b752cd49b7 | ||
|
|
2c91b5cc7b | ||
|
|
453321c8c2 | ||
|
|
981d754133 | ||
|
|
410f36f719 | ||
|
|
bd06aedb90 | ||
|
|
42ddeb14e7 | ||
|
|
6bd127a313 | ||
|
|
4b7643d833 | ||
|
|
3f96592c99 | ||
|
|
98018fc63b | ||
|
|
aeac4d6d20 | ||
|
|
9e9a80df31 | ||
|
|
5f07b1c3b1 | ||
|
|
bfea2204eb | ||
|
|
fb30cd3db3 | ||
|
|
584cb9ac9d | ||
|
|
428ee141e1 | ||
|
|
ec9718466d | ||
|
|
c5bb08022a | ||
|
|
b710745e88 | ||
|
|
5cf84fe9b7 | ||
|
|
27991a7822 | ||
|
|
d1e2f0ced0 | ||
|
|
e848306187 | ||
|
|
2ee9d7e66d | ||
|
|
e31585842d | ||
|
|
f068b4ab75 | ||
|
|
26e29409a9 | ||
|
|
4923129d10 | ||
|
|
8ab55e2193 | ||
|
|
9bc7ef3b5a | ||
|
|
9431ad835c | ||
|
|
2984d7d4f8 | ||
|
|
6324036e41 | ||
|
|
3287799959 | ||
|
|
f95e5d3339 | ||
|
|
52b4bae423 | ||
|
|
037592087c | ||
|
|
3eb8e732ea | ||
|
|
761b92afce | ||
|
|
b5f43ee993 | ||
|
|
76da97f090 | ||
|
|
7554e45f60 | ||
|
|
6994acb91d | ||
|
|
bccfec86ba | ||
|
|
114fd53cd1 | ||
|
|
c8f41164c5 | ||
|
|
6f303ff957 | ||
|
|
95a49697f7 | ||
|
|
8846f5f070 | ||
|
|
4f09e515ee | ||
|
|
551f4ff322 | ||
|
|
d5a9301c7f | ||
|
|
34915e3b16 | ||
|
|
c55aad775e | ||
|
|
ac3f0633cd | ||
|
|
d55567a634 | ||
|
|
abcb141737 | ||
|
|
8d97adc1dc | ||
|
|
5c37d54070 | ||
|
|
fecaacd5be | ||
|
|
53bc3538da | ||
|
|
0e0655b316 | ||
|
|
5058f5ddcf | ||
|
|
4a1c9c48a2 | ||
|
|
5e74ff39f2 | ||
|
|
b5c07385e9 | ||
|
|
bfb10d172b | ||
|
|
00a77181ef | ||
|
|
e13468dc43 | ||
|
|
d3b137c919 | ||
|
|
e292c8a7c7 | ||
|
|
ce195998c1 | ||
|
|
e20cf8b386 | ||
|
|
c4a726397d | ||
|
|
7fab85b389 | ||
|
|
12d2c7be69 | ||
|
|
26955f4f36 | ||
|
|
56df0736fa | ||
|
|
695939ac74 | ||
|
|
4c06851e0e | ||
|
|
23e4bc406e | ||
|
|
fe18c4d1d6 | ||
|
|
e6fdeb0b31 | ||
|
|
5ec4b3c17d | ||
|
|
6e94d0a179 | ||
|
|
4357045904 | ||
|
|
1ef71d7492 | ||
|
|
1fc985db7e | ||
|
|
364428ca1e | ||
|
|
09b549a862 | ||
|
|
2d238a8c36 | ||
|
|
7a0309284a | ||
|
|
fd3f1724e6 | ||
|
|
ca40c698a2 | ||
|
|
fb6254e501 | ||
|
|
cf9d96477b | ||
|
|
493d0ad91a | ||
|
|
a0e88919a6 | ||
|
|
237962c3be | ||
|
|
1637acce6e | ||
|
|
68c4f8c822 | ||
|
|
784d5ec346 | ||
|
|
955834e453 | ||
|
|
435f36b6e9 | ||
|
|
08c48f3acb | ||
|
|
ff1870cedc | ||
|
|
5e51ee1bb2 | ||
|
|
55f1a37b3d | ||
|
|
58dff0a1e9 | ||
|
|
fc543f1ca5 | ||
|
|
2e068e66d4 | ||
|
|
a4c346d4a2 | ||
|
|
fe14d1f7e3 | ||
|
|
f4b39dfe80 | ||
|
|
7d86ed1d9c | ||
|
|
506de65dae | ||
|
|
08384c7540 | ||
|
|
94ae6713aa | ||
|
|
838a2b425a | ||
|
|
1a5ee57a6f | ||
|
|
d539e6b96b | ||
|
|
3ade036d34 | ||
|
|
f3c49e86ae | ||
|
|
b2401b8458 | ||
|
|
51bb8767e3 | ||
|
|
c0fbe9b182 | ||
|
|
01287d9e7e | ||
|
|
70fb2fbfb2 | ||
|
|
b6f116108c | ||
|
|
03aca7cdac | ||
|
|
96da88e168 | ||
|
|
b6cceab218 | ||
|
|
95b16be714 | ||
|
|
d31ad79bc0 | ||
|
|
5745805a5d | ||
|
|
590f7a58fa | ||
|
|
027b19c5db | ||
|
|
7670673a39 | ||
|
|
824b9bf607 | ||
|
|
155183eb30 | ||
|
|
b10a84466b | ||
|
|
0aa0f47a9d | ||
|
|
5f91be7c21 | ||
|
|
e3e2cfa9d1 | ||
|
|
d1b4e62d4d |
No files matched your search
@@ -0,0 +1,26 @@
|
||||
---
|
||||
description: Marqdo Web Artifact — no degradation; Document/Endpoint/Resource only
|
||||
globs: ext/web/**,ext/net/**,ext/data/**,ext/security/**,examples/**/*,tests/ext/web*,doc/design/ext-web*,doc/adr/0007*
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Web Artifact — 不允许降级
|
||||
|
||||
Canonical: `doc/adr/0007-web-document-endpoint.md` · `doc/design/ext-web-artifact.md` · `doc/next/007.md` (superseded).
|
||||
|
||||
## Hard bans
|
||||
|
||||
1. **Do not** restore or reintroduce author-facing `compose_main` / `compose_intro` / `compose_*` fragmented table DSLs, god `# page` mutation piles, or `app.configure(...)` junk-drawer APIs.
|
||||
2. **Do not** use `json.set` / `json.append` bag glue for pages, routes, or middleware. Tables = data. View schema is only `|type|slot|value|attrs|style|` (ZH aliases allowed).
|
||||
3. **Do not** call `ensure_plugin` or `host_*` from author programs or from `ext/**` (plugin load is facade/capability only).
|
||||
4. **Do not** register implicit user routes. Declared routes come from Artifact metadata or `web.route`. System routes (`/_part`, `/_form`, …) must appear in `web.inspect`.
|
||||
5. **Do not** invent DSL, nested frontmatter under `##`, or new table dialects when the design is silent — **stop and ask**.
|
||||
6. **Do not** mix EN/ZH API names in one `.mq.md`.
|
||||
7. **Do not** silently delete capabilities. Removals require design text + tests updated in the same change.
|
||||
8. **Do not** put DB/auth/cache/storage/websocket author APIs back into `ext/web/web.mq.md` — they live in `ext/data`, `ext/security`, `ext/net`.
|
||||
|
||||
## Required direction
|
||||
|
||||
- Document (`type: web` / `类型: 网页`), Endpoint (`type: endpoint` / `类型: 端点`), Resource modules.
|
||||
- Facade only: `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect` (ZH mirrors).
|
||||
- Code is documentation: the `.mq.md` is the page/API docs and the implementation.
|
||||
@@ -1,144 +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
|
||||
|
||||
**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` |
|
||||
```
|
||||
|
||||
**Single dynamic key** — 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**
|
||||
```
|
||||
|
||||
### 3. Bad pattern (do not write)
|
||||
|
||||
```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*
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: `ext/web` + GFM page/style tables.
|
||||
|
||||
## Developing libraries (`lib/*`, `ext/*`)
|
||||
|
||||
### 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`).
|
||||
|
||||
### Library checklist
|
||||
|
||||
- [ ] Public examples use **tables + helpers**, not json glue
|
||||
- [ ] 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 / DB | `ext/web` classes + compose from tables |
|
||||
| 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)
|
||||
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,166 +1,14 @@
|
||||
---
|
||||
name: marqdo-release
|
||||
description: >-
|
||||
Run a full Marqdo product release: detect latest version and ask the user for
|
||||
the next tag, update CHANGELOG/README/skills/public docs, bump Cargo versions,
|
||||
sync VS Code extension on branch vscode-extension when needed, build or
|
||||
trigger install assets (CLI, stdlib, ext, public zip, VSIX, wasm notes), push
|
||||
tag, publish GitHub Release with detailed notes, and recover from network
|
||||
failures via proxy. Use when the user asks to release, cut a version, publish
|
||||
vX.Y.Z, ship a GitHub release, 发版, 发布新版本, 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`). Do not proceed until they confirm.
|
||||
2. **Never force-push** `main` / tags. **Never** `--no-verify` unless the user explicitly orders it.
|
||||
3. **Never commit `vscode-extension/` on `main`** (gitignored). Extension source lives only on branch **`vscode-extension`**. See `doc/design/vscode-extension-commit.md`.
|
||||
4. **Do not release from a dirty tree** (except intentional release commits you create in this flow).
|
||||
5. **Tag format** is always `vX.Y.Z` matching root `Cargo.toml` `version = "X.Y.Z"`.
|
||||
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for Windows CLI + VSIX + zips. Local packaging is fallback / verification.
|
||||
7. After network errors: apply [reference.md § Proxy](reference.md); retry; do not silently skip uploads.
|
||||
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.
|
||||
|
||||
## Defaults (after version is confirmed)
|
||||
|
||||
Unless the user overrides, apply these automatically — **do not re-ask**:
|
||||
|
||||
| Setting | Default |
|
||||
|---------|---------|
|
||||
| Sync / bump `vscode-extension` to same `VER` | **yes** |
|
||||
| Push `main`, create annotated tag, push tag immediately (trigger CI) | **yes** |
|
||||
| Release notes language | **中英双语** (Chinese first, then English section, or paired ZH/EN under each heading) |
|
||||
| Skip VSIX | **no** |
|
||||
| Docs-only release | **no** (full asset pipeline via CI) |
|
||||
| Deploy gh-pages after release | **no** (only if user asks) |
|
||||
|
||||
Phase 0 asks **only** for the next version (and optional overrides). Example ask:
|
||||
|
||||
> 当前最新是 **vA.B.C**。请指定下一个版本号(如 `0.3.2`)。其余按默认:同步扩展、立刻打 tag 发布、中英双语说明。
|
||||
|
||||
## Phase 0 — Detect versions (mandatory stop)
|
||||
|
||||
Run in repo root (parallel OK):
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
|
||||
# or: rg / git tag / gh release list — see reference.md
|
||||
```
|
||||
|
||||
Report briefly, then **ask only for the next SemVer** (defaults above). Wait for confirmation. Normalize to `VER=X.Y.Z` and `TAG=vX.Y.Z`.
|
||||
|
||||
## Phase 1 — Preflight
|
||||
|
||||
Copy and track:
|
||||
|
||||
```
|
||||
Release progress:
|
||||
- [ ] Phase 0: version confirmed by user (TAG=…)
|
||||
- [ ] Phase 1: preflight green
|
||||
- [ ] Phase 2: docs + version bumps committed
|
||||
- [ ] Phase 3: extension branch (if needed)
|
||||
- [ ] Phase 4: main pushed; tag created & pushed
|
||||
- [ ] Phase 5: CI / assets / release notes verified
|
||||
- [ ] Phase 6: post-release checks
|
||||
```
|
||||
|
||||
Checks:
|
||||
|
||||
1. `git status` clean or only release WIP you control.
|
||||
2. `git checkout main && git pull --ff-only origin main`.
|
||||
3. Quick gate: `cargo test --test gold structure_hello` (and any release-critical tests the user named). Full gold suite if time allows.
|
||||
4. `CHANGELOG.md` has meaningful **Unreleased** notes; if empty, draft from `git log vLAST..HEAD --oneline` and confirm with user.
|
||||
5. Confirm no secrets in the commit (`*.env`, credentials).
|
||||
|
||||
## Phase 2 — Docs & version bumps (main)
|
||||
|
||||
Bump **in lockstep**:
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `Cargo.toml` | `version = "VER"` |
|
||||
| `crates/marqdo-wasm/Cargo.toml` | same `VER` |
|
||||
| `CHANGELOG.md` | Move `## Unreleased` → `## vVER — YYYY-MM-DD`; leave fresh empty `## Unreleased` |
|
||||
| `README.md` | 「现状 / 如何使用最新」version strings, checkout tag, release URL |
|
||||
| `.cursor/skills/marqdo/SKILL.md` | Version-sensitive bullets if any (WASM/web status); keep rules accurate |
|
||||
| `public/**` | User-facing tutorials if features shipped (welcome, features/*, extensions). Prefer small factual updates over rewrites |
|
||||
| `doc/roadmap/*.md` | Mark shipped waves done if this release closes them |
|
||||
| `.github/workflows/release.yml` | Update **Highlights** body template to this release (CI still uses hardcoded blurb—keep in sync) |
|
||||
|
||||
Public HTML: regenerate before packaging / pages deploy:
|
||||
|
||||
```bash
|
||||
./scripts/build-public.sh
|
||||
# outputs under public/ (gitignored HTML); used by release zip / gh-pages
|
||||
```
|
||||
|
||||
Commit on `main` (HEREDOC message), e.g.:
|
||||
|
||||
```text
|
||||
release: vVER — <one-line highlight>
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
Push `main`: `git push origin main` (with proxy/`all` perms if needed).
|
||||
|
||||
## Phase 3 — VS Code / Cursor extension
|
||||
|
||||
**Default: always** bump extension to `VER` on branch `vscode-extension` (skip only if user said so).
|
||||
|
||||
1. `git fetch origin vscode-extension`
|
||||
2. Work on `vscode-extension` branch (not main):
|
||||
- Bump `vscode-extension/package.json` `version` to `VER`.
|
||||
- Update `engines` / CLI version hints in extension README if present.
|
||||
- `npm ci && npm run compile`
|
||||
3. Commit & `git push origin vscode-extension`.
|
||||
4. Return to `main`. **Do not** add `vscode-extension/` to main.
|
||||
|
||||
## Phase 4 — Tag & trigger CI
|
||||
|
||||
```bash
|
||||
git tag -a "TAG" -m "TAG"
|
||||
git push origin "TAG"
|
||||
```
|
||||
|
||||
This runs `.github/workflows/release.yml` (Windows): CLI exe/zip, stdlib zip, ext zip, source zip, public zip, VSIX.
|
||||
|
||||
If tag push fails: [reference.md § Proxy](reference.md), retry once; then report.
|
||||
|
||||
## Phase 5 — Release notes & assets
|
||||
|
||||
1. Wait for Actions success: `gh run list --workflow=Release --limit 3` / open the run URL.
|
||||
2. Ensure GitHub Release for `TAG` exists with assets (workflow uses `softprops/action-gh-release`).
|
||||
3. **Rewrite release body** (workflow body is a stub) with **中英双语** — see [reference.md § Notes template](reference.md). `gh release edit TAG --notes-file …`.
|
||||
4. Include: Highlights, Breaking, Install (`ext add`, plugins build), Downloads table, WASM (`marqdo wasm build`), links to CHANGELOG/README, extension branch note.
|
||||
5. Optional Linux local extras (not required if CI green): `marqdo wasm build` smoke; document in notes that wasm is built from source via CLI.
|
||||
|
||||
Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script header).
|
||||
|
||||
## Phase 6 — Post-release
|
||||
|
||||
1. `gh release view TAG` — confirm assets + notes.
|
||||
2. `git status` clean; `main` synced.
|
||||
3. Tell user: release URL `https://github.com/cflmy/marqdo/releases/tag/TAG`.
|
||||
4. Optional: `./scripts/deploy-public.ps1` / pages workflow if user wants user-site refresh.
|
||||
5. Open fresh `## Unreleased` already done in Phase 2.
|
||||
|
||||
## Failure matrix (short)
|
||||
|
||||
| Failure | Action |
|
||||
|---------|--------|
|
||||
| `gh` / git TLS or proxy `7890` refused | Unset bad proxy; use working `HTTP(S)_PROXY` or `required_permissions: ["all"]`; see reference |
|
||||
| Tag exists | Stop; ask user to bump or delete tag (no force on shared tags without explicit order) |
|
||||
| CI red | Fix on main, move tag only if user explicitly allows delete+re-push tag |
|
||||
| VSIX missing | Fetch `vscode-extension`, build locally, `gh release upload TAG dist/*.vsix` |
|
||||
| Partial assets | Re-run workflow or upload missing files only |
|
||||
|
||||
## Do not
|
||||
|
||||
- Ship without user-confirmed version.
|
||||
- Hardcode release highlights only in Actions YAML and forget CHANGELOG.
|
||||
- Commit `target/`, `dist/`, `*.wasm`, or `public/**/*.html` unless project policy changes.
|
||||
- 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,305 +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**:
|
||||
|
||||
| Asset | Role |
|
||||
|-------|------|
|
||||
| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) |
|
||||
| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` |
|
||||
| `marqdo-VER-stdlib.zip` | `lib/` only |
|
||||
| `marqdo-VER-ext.zip` | Official `ext/` L1 |
|
||||
| `marqdo-VER-source.zip` | `git archive` of tagged commit |
|
||||
| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) |
|
||||
| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) |
|
||||
|
||||
Not CI-uploaded (document in notes): Linux/macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`.
|
||||
|
||||
## 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
|
||||
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/` |
|
||||
| `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 proxy on `127.0.0.1:7890`, TLS failures, `gh` needing token, Cursor sandbox blocking git/gh.
|
||||
|
||||
### Diagnose
|
||||
|
||||
```bash
|
||||
env | grep -iE 'proxy|PROXY' || true
|
||||
curl -sI https://github.com | head -5
|
||||
gh auth status
|
||||
```
|
||||
|
||||
### Fix order
|
||||
|
||||
1. **Unset bad proxy** if connection refused:
|
||||
|
||||
```bash
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_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. **Partial upload**:
|
||||
|
||||
```bash
|
||||
gh release upload "vVER" dist/FILE --clobber
|
||||
```
|
||||
|
||||
7. **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).
|
||||
|
||||
## 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.
|
||||
+284
@@ -0,0 +1,284 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Push / run git|gh through an HK SSH jump host (Paramiko HTTP CONNECT).
|
||||
|
||||
When this machine cannot reach GitHub reliably but can SSH to a host that can
|
||||
(e.g. hk.cflmy.de), open a local HTTP CONNECT proxy over Paramiko and run the
|
||||
remaining command with http(s).proxy pointed at it.
|
||||
|
||||
Why Paramiko: OpenSSH/`sshpass` has hung on password auth in this environment;
|
||||
Paramiko password + direct-tcpip works.
|
||||
|
||||
Credentials (never commit):
|
||||
HK_SSH_PASSWORD password string
|
||||
HK_SSH_PASSWORD_FILE file containing password (mode 600 recommended)
|
||||
or SSH key via Paramiko agent/keys if password unset and key works
|
||||
|
||||
Optional env:
|
||||
HK_SSH_HOST default hk.cflmy.de
|
||||
HK_SSH_USER default root
|
||||
HK_JUMP_PORT default 18081 (local CONNECT listen)
|
||||
|
||||
Usage:
|
||||
HK_SSH_PASSWORD_FILE=/tmp/hk.pw \\
|
||||
python3 .cursor/skills/marqdo-release/scripts/push-via-hk-jump.py -- \\
|
||||
git push origin main
|
||||
|
||||
# keep proxy only (Ctrl+C to stop)
|
||||
... push-via-hk-jump.py --serve
|
||||
|
||||
# wrap gh
|
||||
... push-via-hk-jump.py -- gh release view v0.3.9
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import select
|
||||
import socket
|
||||
import socketserver
|
||||
import subprocess
|
||||
import sys
|
||||
import threading
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import paramiko
|
||||
except ImportError as e: # pragma: no cover
|
||||
raise SystemExit(
|
||||
"paramiko required: apt install python3-paramiko (or pip install paramiko)"
|
||||
) from e
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[4]
|
||||
|
||||
|
||||
class _Server(socketserver.ThreadingMixIn, socketserver.TCPServer):
|
||||
allow_reuse_address = True
|
||||
daemon_threads = True
|
||||
|
||||
|
||||
def load_password() -> str | None:
|
||||
path = os.environ.get("HK_SSH_PASSWORD_FILE")
|
||||
if path:
|
||||
return Path(path).read_text(encoding="utf-8").strip()
|
||||
pw = os.environ.get("HK_SSH_PASSWORD")
|
||||
return pw.strip() if pw else None
|
||||
|
||||
|
||||
def connect_hk() -> paramiko.SSHClient:
|
||||
host = os.environ.get("HK_SSH_HOST", "hk.cflmy.de")
|
||||
user = os.environ.get("HK_SSH_USER", "root")
|
||||
pw = load_password()
|
||||
client = paramiko.SSHClient()
|
||||
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
|
||||
kwargs: dict = {
|
||||
"hostname": host,
|
||||
"username": user,
|
||||
"timeout": 20,
|
||||
"auth_timeout": 25,
|
||||
"banner_timeout": 25,
|
||||
}
|
||||
if pw:
|
||||
kwargs.update(password=pw, allow_agent=False, look_for_keys=False)
|
||||
else:
|
||||
kwargs.update(allow_agent=True, look_for_keys=True)
|
||||
print(f"== HK jump {user}@{host} ==", flush=True)
|
||||
client.connect(**kwargs)
|
||||
_, stdout, stderr = client.exec_command(
|
||||
"hostname; curl -sS --max-time 20 -o /dev/null -w gh=%{http_code} https://github.com/; echo"
|
||||
)
|
||||
out = stdout.read().decode()
|
||||
err = stderr.read().decode()
|
||||
print(out, end="" if out.endswith("\n") else "\n", flush=True)
|
||||
if err.strip():
|
||||
print(err, file=sys.stderr, flush=True)
|
||||
return client
|
||||
|
||||
|
||||
def make_proxy(transport: paramiko.Transport, port: int) -> _Server:
|
||||
class Handler(socketserver.StreamRequestHandler):
|
||||
def handle(self) -> None:
|
||||
try:
|
||||
first = self.rfile.readline(65536)
|
||||
if not first:
|
||||
return
|
||||
parts = first.decode("latin1", "replace").split()
|
||||
if len(parts) < 2 or parts[0].upper() != "CONNECT":
|
||||
self.wfile.write(b"HTTP/1.1 405 Method Not Allowed\r\n\r\n")
|
||||
return
|
||||
while True:
|
||||
line = self.rfile.readline(65536)
|
||||
if line in (b"\r\n", b"\n", b""):
|
||||
break
|
||||
host, _, port_s = parts[1].partition(":")
|
||||
chan = transport.open_channel(
|
||||
"direct-tcpip",
|
||||
(host, int(port_s or "443")),
|
||||
self.connection.getpeername(),
|
||||
)
|
||||
self.wfile.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
|
||||
sock = self.connection
|
||||
sock.setblocking(False)
|
||||
chan.setblocking(False)
|
||||
try:
|
||||
while True:
|
||||
r, _, x = select.select([sock, chan], [], [sock, chan], 120)
|
||||
if x:
|
||||
break
|
||||
if sock in r:
|
||||
data = sock.recv(65536)
|
||||
if not data:
|
||||
break
|
||||
chan.sendall(data)
|
||||
if chan in r:
|
||||
data = chan.recv(65536)
|
||||
if not data:
|
||||
break
|
||||
sock.sendall(data)
|
||||
finally:
|
||||
try:
|
||||
chan.close()
|
||||
except Exception:
|
||||
pass
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return _Server(("127.0.0.1", port), Handler)
|
||||
|
||||
|
||||
def github_basic_auth_header() -> str:
|
||||
"""Authorization: Basic … from local git credential store (no askpass; askpass can hang)."""
|
||||
import base64
|
||||
|
||||
out = subprocess.check_output(
|
||||
["git", "credential", "fill"],
|
||||
input=b"protocol=https\nhost=github.com\n\n",
|
||||
).decode()
|
||||
data = dict(line.split("=", 1) for line in out.splitlines() if "=" in line)
|
||||
user = data.get("username") or "x-access-token"
|
||||
password = data.get("password") or ""
|
||||
if not password:
|
||||
raise SystemExit("no github.com credential in git credential store")
|
||||
token = base64.b64encode(f"{user}:{password}".encode()).decode()
|
||||
return f"Authorization: Basic {token}"
|
||||
|
||||
|
||||
def github_token() -> str | None:
|
||||
out = subprocess.check_output(
|
||||
["git", "credential", "fill"],
|
||||
input=b"protocol=https\nhost=github.com\n\n",
|
||||
).decode()
|
||||
data = dict(line.split("=", 1) for line in out.splitlines() if "=" in line)
|
||||
return data.get("password") or None
|
||||
|
||||
|
||||
def run_with_proxy(proxy: str, argv: list[str]) -> int:
|
||||
env = os.environ.copy()
|
||||
for k in (
|
||||
"http_proxy",
|
||||
"https_proxy",
|
||||
"HTTP_PROXY",
|
||||
"HTTPS_PROXY",
|
||||
"ALL_PROXY",
|
||||
"all_proxy",
|
||||
):
|
||||
env.pop(k, None)
|
||||
|
||||
cmd = list(argv)
|
||||
if cmd and cmd[0] == "git":
|
||||
# Prefer http.extraHeader over GIT_ASKPASS (askpass has hung under agent/no TTY).
|
||||
# Do not also set env http_proxy for git — only -c (avoids double-proxy quirks).
|
||||
auth = github_basic_auth_header()
|
||||
cmd = [
|
||||
"git",
|
||||
"-c",
|
||||
f"http.proxy={proxy}",
|
||||
"-c",
|
||||
f"https.proxy={proxy}",
|
||||
"-c",
|
||||
"credential.helper=",
|
||||
"-c",
|
||||
f"http.extraHeader={auth}",
|
||||
"-c",
|
||||
"http.version=HTTP/1.1",
|
||||
"-c",
|
||||
"http.postBuffer=524288000",
|
||||
*cmd[1:],
|
||||
]
|
||||
print(
|
||||
"+",
|
||||
" ".join(
|
||||
c if not str(c).startswith("http.extraHeader=") else "http.extraHeader=<redacted>"
|
||||
for c in cmd
|
||||
),
|
||||
flush=True,
|
||||
)
|
||||
return subprocess.call(cmd, cwd=ROOT, env=env)
|
||||
|
||||
env["http_proxy"] = proxy
|
||||
env["https_proxy"] = proxy
|
||||
env["HTTP_PROXY"] = proxy
|
||||
env["HTTPS_PROXY"] = proxy
|
||||
|
||||
if cmd and cmd[0] == "gh" and not env.get("GH_TOKEN"):
|
||||
tok = github_token()
|
||||
if tok:
|
||||
env["GH_TOKEN"] = tok
|
||||
|
||||
print("+", " ".join(cmd), flush=True)
|
||||
return subprocess.call(cmd, cwd=ROOT, env=env)
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
args = argv[1:]
|
||||
if not args or args[0] in ("-h", "--help"):
|
||||
print(__doc__)
|
||||
return 0 if args else 1
|
||||
|
||||
serve_only = args == ["--serve"]
|
||||
if args[0] == "--":
|
||||
args = args[1:]
|
||||
if not serve_only and not args:
|
||||
print("missing command after --", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
port = int(os.environ.get("HK_JUMP_PORT", "18081"))
|
||||
client = connect_hk()
|
||||
transport = client.get_transport()
|
||||
assert transport is not None
|
||||
server = make_proxy(transport, port)
|
||||
threading.Thread(target=server.serve_forever, daemon=True).start()
|
||||
proxy = f"http://127.0.0.1:{port}"
|
||||
print(f"== CONNECT proxy {proxy} ==", flush=True)
|
||||
# smoke
|
||||
subprocess.call(
|
||||
[
|
||||
"curl",
|
||||
"-sS",
|
||||
"--connect-timeout",
|
||||
"10",
|
||||
"--max-time",
|
||||
"25",
|
||||
"--proxy",
|
||||
proxy,
|
||||
"-o",
|
||||
"/dev/null",
|
||||
"-w",
|
||||
"github=%{http_code}\\n",
|
||||
"https://github.com/",
|
||||
]
|
||||
)
|
||||
|
||||
try:
|
||||
if serve_only:
|
||||
print("serving; Ctrl+C to stop", flush=True)
|
||||
while transport.is_active():
|
||||
time.sleep(5)
|
||||
return 1
|
||||
return run_with_proxy(proxy, args)
|
||||
finally:
|
||||
server.shutdown()
|
||||
client.close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main(sys.argv))
|
||||
+48
-243
@@ -1,257 +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 a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
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.
|
||||
|
||||
|
||||
## 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 `---` / `***` in function body | End function body (no value) |
|
||||
| GFM table after empty RHS bind | Collection (1-col list / ≥2-col map / `@`·`行`·`row` → list of maps); `` `x`[^1] `` / `` `m`[^key] `` |
|
||||
| `` ```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.
|
||||
|
||||
## Minimal program
|
||||
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.
|
||||
|
||||
```markdown
|
||||
# main
|
||||
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.
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
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.
|
||||
|
||||
Chinese builtins (same functions, no import):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好
|
||||
```
|
||||
|
||||
## Functions, calls, end-body
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `---` / `***`.
|
||||
|
||||
## 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: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (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/web` (dynamic sites)
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
|
||||
|
||||
Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
|
||||
|
||||
- EN: `import web:ext/web/web.mq.md`
|
||||
- ZH: `导入 网页:ext/web/网页.mq.md`
|
||||
|
||||
**Hard rules (web):**
|
||||
|
||||
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
|
||||
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
|
||||
- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`.
|
||||
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI.
|
||||
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
|
||||
|
||||
**Typical layout:**
|
||||
|
||||
```text
|
||||
index.mq.md # entry + home page table + listen
|
||||
pages/ # sub-pages
|
||||
components/ # reusable |属性|值|样式| tables
|
||||
styles/ # CSS modules
|
||||
public/ # static + favicon.ico|png|svg
|
||||
db/ # schema + open/init
|
||||
data/ # sqlite runtime (gitignore)
|
||||
```
|
||||
|
||||
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
|
||||
|
||||
**Typical flow:** `db.init` → `page.compose_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)).
|
||||
|
||||
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
|
||||
|
||||
Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/) · client: [examples/web-client-site/](../../examples/web-client-site/).
|
||||
|
||||
Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md).
|
||||
|
||||
## 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/).
|
||||
|
||||
## 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 `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
|
||||
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
|
||||
| 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 functions ended with `---` / `***` / `****` when needed
|
||||
- [ ] 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,328 +1,3 @@
|
||||
# Marqdo examples (AI)
|
||||
# Marqdo executable examples
|
||||
|
||||
## 1. Hello (English)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
## 2. Hello (Chinese builtins)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
## 3. Function + named call + body end
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
Greeting via a nested function:
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## 4. Bindings and return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*a = 2*
|
||||
*b = > add_one n=`a`*
|
||||
> print text=`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 + footnote get
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
|
||||
*种 = 分类[^苹果]*
|
||||
> print text=`种`
|
||||
|
||||
*第一 = 篮子[^1]*
|
||||
```
|
||||
|
||||
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Data cells are expressions (same as call-arg values): bare words, numbers, `` `var` ``, quoted strings; URLs and `gpt-4o-mini` stay text via path/hyphen folding. Footnotes: lists use 1-based digit indices; maps use key text (including digit keys like `[^00]`). 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. 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).
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: split demo
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*parts = > split value=a,b,c sep=,*
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
## 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*
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
## 10. Object handle + method
|
||||
|
||||
See `tests/structure/object-handle.mq.md` and `ext/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 = > json.set map=`self` key=extra value=1*
|
||||
**self**
|
||||
```
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
*ws = > agent*
|
||||
*n = > `ws`.ensure_layout*
|
||||
> print text=`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 — bold is return, not print
|
||||
**Hello**
|
||||
|
||||
# BAD — Python control keywords
|
||||
if x > 0:
|
||||
print(x)
|
||||
|
||||
# BAD — wrapping a call in italics
|
||||
*> 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
|
||||
```
|
||||
|
||||
## 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"*
|
||||
> print text=`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.
|
||||
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,181 +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
|
||||
marqdo ext remove llm|agent|web|quantum
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) `` or `` - [`item`](`coll`) ``; identifiers in backticks (foreach header may omit ticks). See `doc/design/markdown-mapping.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/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` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.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 |
|
||||
|
||||
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`.
|
||||
|
||||
## 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.md` | Syntax constitution |
|
||||
| `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/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,12 @@
|
||||
# Local LLM for Marqdo agent / ext/ai/llm development.
|
||||
# Copy to `.env` in the repo root (gitignored) and fill secrets.
|
||||
# Never commit real keys.
|
||||
|
||||
OPENAI_API_KEY=
|
||||
OPENAI_BASE_URL=https://llm.cflmy.cn/v1
|
||||
OPENAI_MODEL=cflmy
|
||||
|
||||
# Aliases also accepted by ext/ai/llm:
|
||||
# MARQDO_LLM_API_KEY=
|
||||
# MARQDO_LLM_BASE_URL=
|
||||
# MARQDO_LLM_MODEL=
|
||||
@@ -0,0 +1,9 @@
|
||||
# Ext CDN / R2 (Cloudflare) — copy to ~/.marqdo/r2.env and chmod 600
|
||||
# Never commit real keys. Public downloads: https://ext.marqdo.com
|
||||
|
||||
R2_ACCOUNT_ID=
|
||||
R2_BUCKET=marqdo
|
||||
R2_ENDPOINT=https://<accountid>.r2.cloudflarestorage.com
|
||||
R2_ACCESS_KEY_ID=
|
||||
R2_SECRET_ACCESS_KEY=
|
||||
R2_PUBLIC_BASE=https://ext.marqdo.com
|
||||
@@ -0,0 +1,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,15 @@
|
||||
## 层归属(必填,见 doc/design/layers.md)
|
||||
|
||||
- [ ] Language(`src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` / 契约)
|
||||
- [ ] Runtime(`lib/` `plugins/` `crates/` catalog / view / debug / builtin)
|
||||
- [ ] Document(`*.mq.md` `skills/` `ext/` `public/` `examples/`)
|
||||
|
||||
## 核心表面(见 doc/design/core-surface.md)
|
||||
|
||||
- [ ] 不涉及核心标记
|
||||
- [ ] 涉及核心标记:ADR 编号 ______;core-surface.md 与 `CORE_CONSTRUCTS` 已同步(CI 守卫)
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 相关验收(机器可验证)全绿
|
||||
- [ ] 全量回归绿(`cargo test` / `go test ./...` 视触及面)
|
||||
@@ -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,34 @@
|
||||
name: executable-knowledge
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Build agent + llm plugins (EK / workbench gates)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_agent --locked
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
- name: Workbench contracts (M00–M06 / F-subset)
|
||||
run: cargo test --test workbench_contracts --locked
|
||||
- name: Offline executable-knowledge gate
|
||||
run: cargo test --test executable_knowledge --locked
|
||||
- name: Isolated execute MR-01 (dual 60s SSE + short reads)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
bash scripts/build-web-plugin.sh
|
||||
cargo test --test isolated_execute_mr01 --locked -- --nocapture
|
||||
timeout-minutes: 5
|
||||
- name: no ignored tests counted as success
|
||||
run: |
|
||||
if grep -n '#\[ignore\]' tests/executable_knowledge.rs; then
|
||||
echo "executable_knowledge must not use #[ignore] as success evidence" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "ok: no #[ignore] in executable_knowledge gate"
|
||||
@@ -0,0 +1,64 @@
|
||||
# Independent extension sources and native libraries; no CLI/PPA publication.
|
||||
name: Extension Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "ext-v*"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
windows:
|
||||
runs-on: windows-latest
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: "1.23.x"
|
||||
- name: Install cgo toolchain
|
||||
run: choco install mingw -y
|
||||
- name: Build the handbook CLI and native capabilities
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
|
||||
bash scripts/build-web-plugin.sh
|
||||
- name: Build and validate the runner's exact pack bytes
|
||||
shell: pwsh
|
||||
run: ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.write,environment.read --fs-root . --require-ok --json
|
||||
- name: Attach source and Windows native packs without replacement
|
||||
shell: pwsh
|
||||
run: ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
|
||||
|
||||
linux:
|
||||
runs-on: ubuntu-latest
|
||||
needs: windows
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: "1.23.x"
|
||||
- name: Install ZIP and cgo tools
|
||||
run: sudo apt-get update && sudo apt-get install -y zip gcc libc6-dev
|
||||
- name: Build the handbook CLI and native capabilities
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
|
||||
bash scripts/build-web-plugin.sh
|
||||
- name: Build and validate the runner's exact pack bytes
|
||||
run: target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.write,environment.read --fs-root . --require-ok --json
|
||||
- name: Attach Linux native pack without replacement
|
||||
run: target/release/marqdo call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
|
||||
@@ -0,0 +1,28 @@
|
||||
name: procurement-example-smoke
|
||||
on:
|
||||
push:
|
||||
branches: [main, docs/executable-skill-showcase-271]
|
||||
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
|
||||
pull_request:
|
||||
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
|
||||
jobs:
|
||||
smoke:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Fetch released v2.7.1 Linux CLI
|
||||
run: |
|
||||
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo.zip
|
||||
unzip -q /tmp/marqdo.zip -d /tmp
|
||||
BIN="$(find /tmp -type f -name marqdo | head -n 1)"
|
||||
test -n "$BIN"
|
||||
chmod +x "$BIN"
|
||||
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
|
||||
- name: Check and run procurement skill
|
||||
run: |
|
||||
"$CLI_BIN" check examples/procurement/index.mq.md
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 查询余额 已花费=120 --json
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/allowed.json
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/denied.json
|
||||
grep -q '本地模拟' /tmp/allowed.json
|
||||
grep -q '采购金额超过' /tmp/denied.json
|
||||
@@ -0,0 +1,43 @@
|
||||
name: Build Marqdo promotional video
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [docs/promo-video-271]
|
||||
paths:
|
||||
- scripts/make-procurement-promo.py
|
||||
- .github/workflows/promo-video.yml
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build-video:
|
||||
if: github.ref_name == 'docs/promo-video-271'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: true
|
||||
- name: Prepare video environment
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -qq -y ffmpeg fonts-noto-cjk
|
||||
python -m pip install --quiet --disable-pip-version-check pillow numpy
|
||||
ffmpeg -version | head -n 2
|
||||
- name: Compose 32-second Marqdo video
|
||||
run: python scripts/make-procurement-promo.py
|
||||
- name: Verify deliverable
|
||||
run: |
|
||||
test -s assets/marketing/marqdo-2.7.1-promo.mp4
|
||||
test -s assets/marketing/marqdo-2.7.1-poster.jpg
|
||||
test -s assets/marketing/marqdo-2.7.1-promo.srt
|
||||
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 assets/marketing/marqdo-2.7.1-promo.mp4
|
||||
- name: Commit video into promotional branch
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git add assets/marketing/marqdo-2.7.1-promo.mp4 assets/marketing/marqdo-2.7.1-poster.jpg assets/marketing/marqdo-2.7.1-promo.srt
|
||||
git diff --cached --quiet || git commit -m "docs: render Marqdo 2.7.1 promotional video from existing assets"
|
||||
git push origin HEAD:docs/promo-video-271
|
||||
+126
-29
@@ -20,13 +20,26 @@ jobs:
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Go (web plugin)
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: "1.23.x"
|
||||
|
||||
- name: Install Node (VS Code extension)
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Build release
|
||||
run: cargo build --release
|
||||
- name: Install MinGW for cgo (web.dll)
|
||||
run: choco install mingw -y
|
||||
|
||||
- name: Build release CLI + official plugins
|
||||
shell: bash
|
||||
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 -p marqdo_plugin_engineering
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
@@ -55,6 +68,7 @@ jobs:
|
||||
$vsix = "marqdo-$ver.vsix"
|
||||
$public = "marqdo-$ver-public.zip"
|
||||
$extZip = "marqdo-$ver-ext.zip"
|
||||
$nativeZip = "marqdo-$ver-native-$target.zip"
|
||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
||||
git archive --format=zip -o "dist/$source" HEAD
|
||||
./target/release/marqdo view output public -o public
|
||||
@@ -65,11 +79,31 @@ jobs:
|
||||
Copy-Item ext "$stageExt/ext" -Recurse
|
||||
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
|
||||
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
|
||||
# Prebuilt native plugins (no Rust required for `marqdo ext add`)
|
||||
$stageNative = "dist/stage-native"
|
||||
if (Test-Path $stageNative) { Remove-Item $stageNative -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path "$stageNative/native" | Out-Null
|
||||
Copy-Item target/release/web.dll "$stageNative/native/web.dll"
|
||||
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
|
||||
Copy-Item target/release/llm.dll "$stageNative/native/llm.dll"
|
||||
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"
|
||||
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stage | Out-Null
|
||||
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
|
||||
Copy-Item lib "$stage/lib" -Recurse
|
||||
Copy-Item ext "$stage/ext" -Recurse
|
||||
New-Item -ItemType Directory -Force -Path "$stage/ext/native" | Out-Null
|
||||
Copy-Item target/release/web.dll "$stage/ext/native/web.dll"
|
||||
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
|
||||
Copy-Item target/release/llm.dll "$stage/ext/native/llm.dll"
|
||||
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"
|
||||
@@ -84,45 +118,108 @@ 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 — v0.3.3
|
||||
- **浏览器作者零业务 JS(D/E/F)**:bridge 自启;DOM/路由/storage/ws/文件/Canvas/音频/Observer/拖放;`lib/browser` + GFM
|
||||
- **Browser author-zero-JS (routes D/E/F)**: host effects + `lib/browser`; examples `browser-hello` / `browser-app` / `browser-media`
|
||||
- Skill: `marqdo-dev`(代码即文档 / 禁止 json.set 胶水)
|
||||
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
|
||||
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [README](https://github.com/cflmy/marqdo/blob/main/README.md)
|
||||
|
||||
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
|
||||
|
||||
### Downloads
|
||||
|
||||
| Asset | Contents |
|
||||
|-------|----------|
|
||||
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
|
||||
| `marqdo-*-stdlib.zip` | `lib/` only |
|
||||
| `marqdo-*-ext.zip` | Official `ext/` L1 sources (for `MARQDO_EXT_SOURCE` / local `./ext`) |
|
||||
| `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.VSIX }}
|
||||
dist/${{ env.SOURCE }}
|
||||
dist/${{ env.PUBLIC }}
|
||||
fail_on_unmatched_files: true
|
||||
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
|
||||
# (required: native plugins for `marqdo ext add` on Linux + CLI bundle).
|
||||
needs: windows
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Go (web plugin)
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: "1.23.x"
|
||||
|
||||
- name: Install zip + cgo toolchain
|
||||
run: sudo apt-get update && sudo apt-get install -y zip gcc libc6-dev
|
||||
|
||||
- name: Build Linux CLI + official plugins
|
||||
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 -p marqdo_plugin_engineering
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
|
||||
- name: Package Linux native zip + CLI bundle
|
||||
run: |
|
||||
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 libengineering.so; do
|
||||
src="target/release/${lib}"
|
||||
if [[ ! -f "$src" && "$lib" == libweb.so ]]; then
|
||||
src="plugins/web/build/libweb.so"
|
||||
fi
|
||||
test -f "$src" || { echo "missing $src" >&2; exit 1; }
|
||||
cp "$src" "dist/stage-native/native/${lib}"
|
||||
done
|
||||
(cd dist/stage-native && zip -r "../marqdo-${VER}-native-${TARGET}.zip" .)
|
||||
echo "NATIVE=marqdo-${VER}-native-${TARGET}.zip" >> "$GITHUB_ENV"
|
||||
|
||||
stage="dist/stage-linux"
|
||||
rm -rf "$stage"
|
||||
mkdir -p "$stage/ext/native" "$stage/lib"
|
||||
cp target/release/marqdo "$stage/marqdo"
|
||||
chmod +x "$stage/marqdo"
|
||||
cp -a lib/. "$stage/lib/"
|
||||
cp -a ext/. "$stage/ext/"
|
||||
cp dist/stage-native/native/*.so "$stage/ext/native/"
|
||||
linux_zip="marqdo-${VER}-${TARGET}.zip"
|
||||
(cd "$stage" && zip -r "../${linux_zip}" .)
|
||||
echo "LINUX_ZIP=${linux_zip}" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Upload Linux packages
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
files: |
|
||||
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 }}
|
||||
+61
-5
@@ -23,7 +23,9 @@
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
**/.marqdo/
|
||||
.env
|
||||
.marqdo-ext/
|
||||
/vendor/
|
||||
/.cargo/config.toml
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
/public/index.html
|
||||
@@ -40,11 +42,7 @@ spike/.pytest_cache/
|
||||
*.pyc
|
||||
|
||||
# Built browser WASM (rebuild via crates/marqdo-wasm README)
|
||||
/examples/browser-hello/marqdo_wasm.wasm
|
||||
/examples/browser-hello/pkg/
|
||||
/examples/web-client-site/static/marqdo_wasm.wasm
|
||||
/examples/browser-app/marqdo_wasm.wasm
|
||||
/examples/browser-media/marqdo_wasm.wasm
|
||||
|
||||
# Local sqlite / scratch
|
||||
/data/
|
||||
@@ -62,8 +60,66 @@ plugins/*/tmp/
|
||||
|
||||
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
|
||||
/tests/ext/quantum-*.svg
|
||||
/tests/ext/linalg-*.svg
|
||||
/examples/quantum-*/**/*.svg
|
||||
/examples/quantum-*/*.svg
|
||||
/examples/linalg-*/**/*.svg
|
||||
/examples/linalg-*/*.svg
|
||||
/examples/linalg-*.svg
|
||||
# oa2026 showcase: SVGs beside the examples ARE tracked; root-level ones are
|
||||
# run artifacts (draw/plot write to cwd when the example is run from root)
|
||||
/bell-*.svg
|
||||
/calculus-*.svg
|
||||
|
||||
# Plot SVGs emitted beside tests / notebooks when demos run
|
||||
/tests/**/*-plot-*.svg
|
||||
|
||||
# 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/
|
||||
|
||||
# PPA build: bundled Rust toolchain (packed into .orig by ppa-build-source.sh only)
|
||||
/third_party/rust/
|
||||
/third_party/
|
||||
|
||||
# ephemeral sqlite / test artifacts
|
||||
tests/ext/:memory:
|
||||
|
||||
# local secrets
|
||||
.env
|
||||
|
||||
# sandbox gold leftovers
|
||||
tests/ext/_sbx_cow/
|
||||
|
||||
tests/ext/_sbx_*/
|
||||
examples/**/_example_sbx/
|
||||
.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
|
||||
+1358
File diff suppressed because it is too large.
Load diff
Generated
+211
-1068
File diff suppressed because it is too large.
Load diff
+24
-6
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.3.3"
|
||||
version = "2.7.1"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -17,9 +17,9 @@ default = ["native"]
|
||||
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
|
||||
cli = ["dep:clap"]
|
||||
view = ["dep:tiny_http"]
|
||||
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize"]
|
||||
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
|
||||
plugin-host = ["dep:libloading"]
|
||||
exec-host = []
|
||||
exec-host = ["dep:libc"]
|
||||
fs-host = []
|
||||
tty = ["dep:libc"]
|
||||
wasm-core = []
|
||||
@@ -29,29 +29,47 @@ 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 }
|
||||
sha1 = { version = "=0.10.6", default-features = false }
|
||||
md-5 = { version = "=0.10.6", default-features = false }
|
||||
hmac = { version = "=0.12.1", default-features = false }
|
||||
getrandom = { version = "=0.2.17", default-features = false, features = ["std"] }
|
||||
# Mid M1: Unicode regex for lib/re (no backrefs; RE2-like).
|
||||
regex = { version = "=1.13.1", default-features = false, features = ["std", "unicode"] }
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"], optional = true }
|
||||
idna_adapter = { version = "=1.1.0", optional = true }
|
||||
zeroize = { version = "=1.8.1", optional = true }
|
||||
# Extract GitHub Release ext/native zips (`marqdo ext add` without local Rust).
|
||||
zip = { version = "=0.6.6", default-features = false, features = ["deflate"], optional = true }
|
||||
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]
|
||||
# No `wasmbind`: keeps cdylib free of wasm-bindgen imports (raw mq_* ABI).
|
||||
# Custom entropy — no `js`/wasm-bindgen imports (raw mq_* ABI + marqdo-bridge.js).
|
||||
chrono = { version = "0.4", default-features = false, features = ["alloc", "std"] }
|
||||
getrandom = { version = "=0.2.17", default-features = false, features = ["custom"] }
|
||||
|
||||
[workspace]
|
||||
members = [
|
||||
"plugins/demo",
|
||||
"plugins/engineering",
|
||||
"plugins/agent",
|
||||
"plugins/web",
|
||||
"plugins/llm",
|
||||
"plugins/quantum",
|
||||
"plugins/linalg",
|
||||
"crates/marqdo-wasm",
|
||||
"crates/marqdo-plugin-sdk",
|
||||
]
|
||||
# Official web plugin is Go (`plugins/web/`). The legacy Rust web plugin was
|
||||
# deleted from the tree (see CHANGELOG); git history keeps it if ever needed.
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
|
||||
@@ -1,12 +1,226 @@
|
||||
# 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` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
||||
<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) · 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="#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>
|
||||
|
||||

|
||||
|
||||
<sub>Animated walkthrough assembled from **real Marqdo 2.7.1 function-call results**, including the accepted **simulated** order and an over-budget refusal. Curated frames, not a recording of typing or a production transaction. [Reproduce the capture](scripts/capture-procurement-showcase.py) · [CI run](https://github.com/cflmy/marqdo/actions/runs/43358103498).</sub>
|
||||
|
||||
## 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.
|
||||
|
||||
```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>**Actual screenshot** captured in Chromium from a Marqdo **2.7.1** View static export, scrolled to `向采购商发工单`. It shows the real rendered document, not a promotional mockup. [Screenshot generation source](scripts/capture-procurement-showcase.py).</sub>
|
||||
|
||||
## One document, multiple uses
|
||||
|
||||
| Prompt-oriented agent skill | Marqdo executable skill |
|
||||
|---|---|
|
||||
| Natural-language tool instructions | Natural-language guidance **and** executable functions |
|
||||
| Description and code often separated | Heading, parameter table, return table and implementation in one `.mq.md` |
|
||||
| Validation may require separate wiring | Named function calls can be checked, executed and tested |
|
||||
| Prompts ask a model to comply | Runtime permissions control **declared** effects of a function call |
|
||||
| Hard to follow implementation through files | View links readable content and implementation details |
|
||||
|
||||
Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior.
|
||||
|
||||
**Resources:** [Release v2.7.1](https://github.com/cflmy/marqdo/releases/tag/v2.7.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/)
|
||||
|
||||
---
|
||||
|
||||
## Deep dive · 语言、设计与执行系统
|
||||
|
||||
## 核心优势:可执行知识(Executable Knowledge)
|
||||
|
||||
> **Knowledge That Can Run —— 知识即可执行。**
|
||||
> Marqdo 不是「用 Markdown 写程序」这么简单:它让一个 `.mq.md` 文档**同时**是文稿、知识与程序——同一份结构,同时服务于人、解释器、工具与 AI。
|
||||
|
||||
```text
|
||||
.mq.md(同一份文件)
|
||||
┌─────────┼─────────┐
|
||||
文稿 知识 程序
|
||||
└─────────┼─────────┘
|
||||
▼
|
||||
Marqdo 运行时
|
||||
▼
|
||||
可执行知识(Executable Knowledge)
|
||||
```
|
||||
|
||||
| 真正的核心优势 | 说明 |
|
||||
|------|------|
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **函数即工具**<br>`marqdo call` | 最小可执行单位是文件中的函数,不只是整份文件。人阅读函数旁边的叙述;开发者、测试和 Agent 用 `marqdo call 文件 函数 名字=值` 执行它。知识复用、工具调用、函数级测试和局部改进是同一入口的四种用法。 |
|
||||
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
|
||||
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
|
||||
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`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」**:
|
||||
|
||||
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. **链接即调用 / 可执行知识图**:`[描述](类.函数)` 既是文档链接,也是类/函数调用;编译器解析目标、校验签名、返回 LinkInfo;`view` 显示调用点;`.mq.md` 之间的链接长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
|
||||
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
|
||||
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
|
||||
|
||||
---
|
||||
|
||||
@@ -23,23 +237,29 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.2)
|
||||
## 语法速览
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| 无标记行 | 注释(空行分段) |
|
||||
| `*…*` | 程序语句 |
|
||||
| `**…**` | **返回值**(架构) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
|
||||
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
|
||||
| `[描述](表达式)` | **链接(本地)**:描述 + 代码;`()` 与 `**…**` 同权(默认语义) |
|
||||
| `[描述](类.函数)` | **链接(跨文档/类调用)**:描述 + 已有类函数调用;可解析、可执行(v2.1 目标) |
|
||||
| `[描述](url)` | 普通 Markdown 导航链接(惰性,不执行) |
|
||||
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
|
||||
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `#` | **类 / 类型**(知识命名空间;`# main` = 入口) |
|
||||
| `##` … | **函数**(类下函数;使用 `self`/`自` 时为实例方法) |
|
||||
| `类.函数` | **类调用**(不使用 `self` 的函数;v2.1 目标) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
|
||||
| 表格 | 集合 |
|
||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||||
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
|
||||
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](遍历 集合 为 项) ``) |
|
||||
| 表格 | 集合(几何即类型,见下);取元使用 `access(集合, "键")` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
|
||||
|
||||
> `[键](集合)` / `- [项](集合)` 是旧取元/循环形;迁移后使用 `access(集合, "键")` 与 `- [描述](遍历 集合 为 项)`。旧形只在显式 `markup: classic` 或 `--legacy-markup` 过渡入口中保留,见 [link-syntax.md](doc/design/link-syntax.md)。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -47,19 +267,20 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
向`谁`问好。
|
||||
|
||||
---
|
||||
**print text="Hello " + 谁**
|
||||
*None*
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
对于输入变量`n`,执行**n=n+1**接着返回*n*。
|
||||
```
|
||||
|
||||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
||||
**表格几何即类型**:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。详见 [tables-maps-footnotes.md](doc/roadmap/tables-maps-footnotes.md)。
|
||||
|
||||
完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -69,7 +290,53 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
6. **语言核心保持小**:Language(标记映射 / AST / 语义 / 类型)、Runtime(stdlib / 插件 ABI / WASM / agent)、Document(知识 + 代码 + UI + AI)三层分明——生态功能不淹没语言身份。
|
||||
|
||||
---
|
||||
|
||||
## 工程习惯:允许申报未完成,但不允许假装完成
|
||||
|
||||
Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。这样文档整体仍能跑,
|
||||
而欠账是可见、可数、可结算的(而不是假装完成):
|
||||
|
||||
```markdown
|
||||
## 检索资料
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | list | 命中列表(当前未接) |
|
||||
|
||||
[按关键词检索,接口未接,待开发](None)
|
||||
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**目标**(唯一执行)。这条语法叫**链接语法**:
|
||||
目标是本地表达式时,就是**遮蔽**(把代码折叠在括号里);目标是 `类.函数` 时,就是**跨文档类调用**。
|
||||
v2.1 实现了文件级链接语义与可执行知识投影(见 [link-syntax.md](doc/design/link-syntax.md))。
|
||||
|
||||
**四条约定**
|
||||
|
||||
1. **桩必须能跑**:不得报错,否则整篇文档被阻断。
|
||||
2. **桩必须写明返回值**:写 `None` 也比空着好;空 `()` 会报 `label.empty_payload`(warning)。
|
||||
3. **申报用词有范例**:内置词表(`待开发` `未实现` `开发中` `模拟` `桩` `示例` `实验` `废弃` …)
|
||||
是**推荐用词与默认检索集**,不是语法——写别的说法同样合法。
|
||||
4. **接不了就申报,别声称完成**:这条已写进 `ext/ai` 的 agent 提示词。
|
||||
|
||||
**盘点与门禁**
|
||||
|
||||
```bash
|
||||
marqdo labels --count # 内置口径:还有多少未完成
|
||||
marqdo labels --grep "接口未联调,联调中" --count # 用你自己的说法
|
||||
marqdo labels --grep 联调 --also-builtin --count # 自定义 + 内置一起数
|
||||
marqdo labels --count --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
|
||||
|
||||
设计依据:[link-syntax.md](doc/design/link-syntax.md) · [occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
|
||||
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -80,6 +347,13 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
|
||||
# Engineering Knowledge Compiler(L0–L4 能力目录 / 复用门闩)
|
||||
marqdo knowledge [PATH] -o OUT_DIR
|
||||
marqdo find "authentication"
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo duplicate [--fail]
|
||||
marqdo verify
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
@@ -87,7 +361,7 @@ marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。产物示例:`catalog.yaml`、`engineering.yaml`、`catalog/capabilities/`、`graph/graph.json`。设计见 [engineering-knowledge.md](doc/design/engineering-knowledge.md) · [catalog-cli.md](doc/design/catalog-cli.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
|
||||
智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):[agent-frameworks-and-marqdo.md](doc/research/agent-frameworks-and-marqdo.md) · 优化路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
|
||||
|
||||
@@ -99,62 +373,121 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.3.3)
|
||||
## 现状(v2.7.0)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **实际工程与可执行 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**
|
||||
- **Streamable HTTP MCP + web invoke 鉴权(v1.4.5)**:`agent_mcp_serve transport=http` · Bearer/`X-Api-Key` 注入 · `unauthorized`→401 · openai/agent `json.get` 硬化
|
||||
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
|
||||
- **Ext pack 1.4.3**:修复 `agent.run` cold EFI(`` `self`.preflight `` + miss resolve `llm_free`);已并入 **≥1.4.4** · [agent-run-efi-resolve-bugs-2026-10.md](doc/research/agent-run-efi-resolve-bugs-2026-10.md)
|
||||
- **Agent/LLM 优化 O1–O5(v1.4.2)**:`ext/ai/sandbox` CoW · `agent.trial` / `sandbox=` · promote sandbox proof · `step_route` / EFI / cost · style lint · quarantine · [ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)
|
||||
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
|
||||
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)
|
||||
- **view 文档面(v1.3.3)**:Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI `#mq-view-trace` · 静态 `view output` / gh-pages 同源 · [view-document-annotations.md](doc/design/view-document-annotations.md)
|
||||
- **Engineering Knowledge(v1.3.0)**:EKC L0–L4 · `marqdo knowledge|find|reuse|duplicate|verify|…` · Agent `preflight` / REUSE→ADAPT→CREATE · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
- **Web Artifact(v1.2.0 · ADR 0007)**:Document/Endpoint 一等公民(`type: web|endpoint`)· facade `page`/`route`/`serve`/`render`/`inspect`/`use` · Resource 拆到 `ext/data`/`security`/`net` · 统一 View 表 · 破坏性移除 `compose_*`/`configure`
|
||||
- **AI 栈(v1.1.1)**:`ext/ai/llm` 语义 `ask`/`stream`/`collect` · Artifact Metadata Binding(`${env|arg|sys|secret}`)· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 `plugins/llm` Transport ABI
|
||||
- **AI 原生闭环(v1.1.0)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
|
||||
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
|
||||
- **`marqdo view`**:文档浏览器(**文档面** Structure + 标注 / 调用·循环帧 + 函数大纲/搜索 + Execution + Variables 浮窗;`view output` 同构)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页(默认挂钩 EKC)
|
||||
- **`marqdo knowledge` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`**:Engineering Knowledge Compiler([engineering-knowledge.md](doc/design/engineering-knowledge.md))
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
|
||||
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
|
||||
- **`web`**:W0–W7 + P3 + **W8**(favicon / Head 资源 / 图片装配,见 [web-assets-and-images.md](doc/design/web-assets-and-images.md));示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)(反向代理 → 嵌入式 `listen`,非 Daphne/Uvicorn)
|
||||
- **`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/)
|
||||
- **`agent`**:A1–A4(OKF 复用、过程事件、上下文预算、RAG/MCP fixture);下一波缺口 [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`llm`**:OpenAI 兼容对话
|
||||
- **`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)
|
||||
- **`llm`**:语义 `ask`/`stream`/`collect`(OpenAI/Ollama;可选原生 `plugins/llm`)
|
||||
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
|
||||
- **原生插件 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(v0.3.3)
|
||||
### 如何使用最新 Marqdo(v2.7.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
| 方式 | 适用 | 命令 / 链接 |
|
||||
|------|------|-------------|
|
||||
| **Ubuntu PPA** | Ubuntu 24.04+(`noble` 等) | `sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo` |
|
||||
| **GitHub Releases** | Windows / Linux 预编译 zip | https://github.com/cflmy/marqdo/releases |
|
||||
| **源码** | 需本机 Rust | 见下方 `git clone` + `cargo build --release` |
|
||||
|
||||
**安装官方扩展**(与 CLI 可分开发版):`marqdo ext add …` 默认下载顺序为 **CDN** [`https://ext.marqdo.com`](https://ext.marqdo.com) → GitHub Releases → [`proxy.cflmy.top`](https://proxy.cflmy.top) 镜像。
|
||||
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v0.3.3 # 或留在 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
|
||||
marqdo catalog public -o .marqdo
|
||||
|
||||
# 3) 安装官方扩展(需先编原生插件)
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
marqdo ext add web # 或:网页
|
||||
# 2b) AI 原生闭环(v1.1.0+):契约检查 / 结构化诊断 / MLSP 查询
|
||||
marqdo check tests/contracts/ok_contract.mq.md # 静态契约防漂移
|
||||
marqdo run tests/structure/hello.mq.md --json # 结构化诊断(错误即数据)
|
||||
printf '{"id":1,"method":"syntax","params":{"query":"返回"}}\n' | marqdo mlsp
|
||||
|
||||
# 3) 安装官方扩展(Release / CDN 用户:无需本机 Rust/Go)
|
||||
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
|
||||
marqdo ext add agent # 或:智能体
|
||||
marqdo ext add quantum # 或:量子
|
||||
marqdo ext add llm # 或:大模型
|
||||
marqdo ext add linalg # 或:线性代数
|
||||
marqdo ext add llm # 或:大模型(.mq.md + 可选 native llm)
|
||||
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg,llm}
|
||||
# bash ./scripts/build-web-plugin.sh # 需 Go + cgo → libweb
|
||||
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
|
||||
|
||||
# 4) 动态站示例(扩展装好后)
|
||||
marqdo run examples/marqdo-blog/index.mq.md
|
||||
marqdo run examples/web-site-zh/index.mq.md # 表驱动引言 Demo
|
||||
marqdo run examples/marqdo-blog/serve.mq.md
|
||||
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) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v0.3.3
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.7.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
@@ -166,7 +499,7 @@ cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`import …:lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add …` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。
|
||||
**发布包**:GitHub Releases 的单独二进制 **已内置**官方 `lib/`。Ubuntu 用户优先 **PPA** 装 CLI。**扩展库**用 `marqdo ext add …`(CDN → GitHub);设计见 [ext-cdn.md](doc/design/ext-cdn.md) · [ubuntu-ppa.md](doc/design/ubuntu-ppa.md) · [ext-cli.md](doc/design/ext-cli.md)。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md) · 变更 [CHANGELOG.md](CHANGELOG.md)
|
||||
---
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
Binary file not shown.
@@ -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
|
||||
Binary file not shown.
|
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 |
Binary file not shown.
|
After Width: | Height: | Size: 204 KiB |
@@ -0,0 +1,7 @@
|
||||
[package]
|
||||
name = "marqdo-plugin-sdk"
|
||||
version = "2.0.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,195 @@
|
||||
//! Shared ABI plumbing for Marqdo native plugins (`<TAB>` slimming).
|
||||
//!
|
||||
//! Every plugin used to copy the same `MarqdoHostApi` struct, the alloc/free
|
||||
//! statics, `host_strdup`, `set_out`/`set_err`, `parse_args` and `reply`
|
||||
//! (about 140 lines each × 5 crates). This crate holds the single copy; the
|
||||
//! `marqdo_plugin!` macro emits the `#[no_mangle]` exports each `.so` needs.
|
||||
//!
|
||||
//! The ABI itself is unchanged: `include/marqdo_abi.h` and the host loader
|
||||
//! (`src/host/plugin.rs`) still see exactly the same symbols and layout.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
|
||||
pub use serde_json::{json, Value};
|
||||
|
||||
/// Highest ABI version this SDK speaks.
|
||||
pub const ABI_VERSION: u32 = 2;
|
||||
|
||||
pub type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
pub type HostQueryFn = unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
pub host_query: Option<HostQueryFn>,
|
||||
}
|
||||
|
||||
pub static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
pub static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
pub static mut HOST_QUERY: Option<HostQueryFn> = None;
|
||||
pub static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
|
||||
|
||||
/// Duplicate `s` into host-allocated memory (the host frees it).
|
||||
pub unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
pub fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
pub fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse the JSON args object handed to a plugin entry point.
|
||||
pub fn parse_args(args_json: *const c_char) -> Result<Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
if s.trim().is_empty() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Write a plugin result (or error) back through the ABI pointers.
|
||||
pub fn reply(out_json: *mut *mut c_char, err_msg: *mut *mut c_char, r: Result<Value, String>) -> c_int {
|
||||
match r {
|
||||
Ok(v) => {
|
||||
set_out(out_json, &v.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &e);
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Ask the host for a builtin with no arguments (`host_query`).
|
||||
pub fn host_query_json(name: &str) -> Result<Value, String> {
|
||||
host_query_json_with(name, &json!({}))
|
||||
}
|
||||
|
||||
/// Ask the host for a builtin, passing `args` as its argument object.
|
||||
pub fn host_query_json_with(name: &str, args: &Value) -> Result<Value, String> {
|
||||
let q = unsafe { HOST_QUERY }.ok_or("host_query unavailable")?;
|
||||
let n = CString::new(name).map_err(|e| e.to_string())?;
|
||||
let a = CString::new(args.to_string()).map_err(|e| e.to_string())?;
|
||||
let mut out: *mut c_char = ptr::null_mut();
|
||||
let mut err: *mut c_char = ptr::null_mut();
|
||||
let rc = unsafe { q(HOST_USERDATA, n.as_ptr(), a.as_ptr(), &mut out, &mut err) };
|
||||
if rc != 0 {
|
||||
return Err(take_host_string(err).unwrap_or_else(|| "host_query failed".into()));
|
||||
}
|
||||
let text = take_host_string(out).ok_or("host_query returned nothing")?;
|
||||
serde_json::from_str(&text).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
/// Copy a host-allocated C string into a Rust `String` and free the original.
|
||||
pub fn take_host_string(p: *mut c_char) -> Option<String> {
|
||||
if p.is_null() {
|
||||
return None;
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(p) }
|
||||
.to_string_lossy()
|
||||
.into_owned();
|
||||
if let Some(free) = unsafe { HOST_FREE } {
|
||||
unsafe { free(p as *mut c_void) };
|
||||
}
|
||||
Some(s)
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, f: PluginFn) -> c_int {
|
||||
let Some(reg) = host.register_fn else {
|
||||
return 1;
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { reg(host.userdata, n.as_ptr(), p.as_ptr(), f) }
|
||||
}
|
||||
|
||||
/// Store the host callbacks and register every entry point.
|
||||
pub unsafe fn init_plugin(host: *const MarqdoHostApi, regs: &[(&str, &str, PluginFn)]) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
HOST_QUERY = host.host_query;
|
||||
HOST_USERDATA = host.userdata;
|
||||
for (name, params, f) in regs {
|
||||
if register(host, name, params, *f) != 0 {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
/// Emit the four `#[no_mangle]` exports every plugin `.so` must provide,
|
||||
/// wiring `marqdo_plugin_init` to the given registration table.
|
||||
#[macro_export]
|
||||
macro_rules! marqdo_plugin {
|
||||
($version:expr, [ $( ($name:expr, $params:expr, $f:expr) ),* $(,)? ]) => {
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
$version
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(
|
||||
host: *const $crate::MarqdoHostApi,
|
||||
) -> i32 {
|
||||
$crate::init_plugin(host, &[ $( ($name, $params, $f as $crate::PluginFn) ),* ])
|
||||
}
|
||||
};
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "0.3.3"
|
||||
version = "2.7.1"
|
||||
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.
|
||||
@@ -197,6 +197,20 @@ export function eventArgsFromDom(ev, valueFromSel) {
|
||||
args.fields = fields;
|
||||
}
|
||||
}
|
||||
if (ev && (ev.type === "scroll" || ev.type === "resize")) {
|
||||
try {
|
||||
const doc = typeof document !== "undefined" ? document.documentElement : null;
|
||||
const body = typeof document !== "undefined" ? document.body : null;
|
||||
const scrollTop = (doc && (doc.scrollTop || 0)) || (body && body.scrollTop) || 0;
|
||||
const height = doc ? (doc.scrollHeight - doc.clientHeight) || 1 : 1;
|
||||
const ratio = Math.max(0, Math.min(1, scrollTop / height));
|
||||
args.scroll_top = scrollTop;
|
||||
args.scroll_max = height;
|
||||
args.scroll_ratio = ratio;
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
@@ -214,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) {
|
||||
@@ -721,75 +759,88 @@ function runObserveEffect(exports, spec, onError) {
|
||||
const kind = String(spec.kind || spec.type || "intersect").toLowerCase();
|
||||
const sel = String(spec.sel || "");
|
||||
const thenFn = spec.then;
|
||||
const id = String(spec.id || `obs${++observeSeq}`);
|
||||
const el = qsOne(sel);
|
||||
if (!el || !thenFn) return;
|
||||
const baseId = String(spec.id || `obs${++observeSeq}`);
|
||||
const nodes = qsAll(sel);
|
||||
if (!nodes.length || (!thenFn && !spec.add_class)) return;
|
||||
|
||||
const prev = observeHandles.get(id);
|
||||
if (prev) {
|
||||
try {
|
||||
prev.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
|
||||
const fire = (payload) => {
|
||||
try {
|
||||
const result = call(exports, thenFn, payload);
|
||||
if (!result.ok) {
|
||||
if (onError) onError(result.error);
|
||||
return;
|
||||
nodes.forEach((el, idx) => {
|
||||
const id = nodes.length === 1 ? baseId : `${baseId}_${idx}`;
|
||||
const prev = observeHandles.get(id);
|
||||
if (prev) {
|
||||
try {
|
||||
prev.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
applyEffects(exports, result.value, { onError });
|
||||
} catch (e) {
|
||||
if (onError) onError(String(e));
|
||||
}
|
||||
};
|
||||
|
||||
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
|
||||
const ro = new ResizeObserver((entries) => {
|
||||
const en = entries[0];
|
||||
const cr = en?.contentRect;
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "resize",
|
||||
id,
|
||||
width: cr ? cr.width : 0,
|
||||
height: cr ? cr.height : 0,
|
||||
});
|
||||
});
|
||||
ro.observe(el);
|
||||
observeHandles.set(id, ro);
|
||||
return;
|
||||
}
|
||||
const fire = (payload) => {
|
||||
try {
|
||||
const result = call(exports, thenFn, payload);
|
||||
if (!result.ok) {
|
||||
if (onError) onError(result.error);
|
||||
return;
|
||||
}
|
||||
applyEffects(exports, result.value, { onError });
|
||||
} catch (e) {
|
||||
if (onError) onError(String(e));
|
||||
}
|
||||
};
|
||||
|
||||
if (typeof IntersectionObserver !== "undefined") {
|
||||
const io = new IntersectionObserver(
|
||||
(entries) => {
|
||||
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
|
||||
const ro = new ResizeObserver((entries) => {
|
||||
const en = entries[0];
|
||||
if (!en) return;
|
||||
const cr = en?.contentRect;
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "intersect",
|
||||
kind: "resize",
|
||||
id,
|
||||
intersecting: !!en.isIntersecting,
|
||||
ratio: en.intersectionRatio,
|
||||
width: cr ? cr.width : 0,
|
||||
height: cr ? cr.height : 0,
|
||||
});
|
||||
if (spec.once && en.isIntersecting) {
|
||||
try {
|
||||
io.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
});
|
||||
ro.observe(el);
|
||||
observeHandles.set(id, ro);
|
||||
return;
|
||||
}
|
||||
|
||||
if (typeof IntersectionObserver !== "undefined") {
|
||||
const opts = { threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 };
|
||||
if (spec.rootMargin != null) opts.rootMargin = String(spec.rootMargin);
|
||||
const io = new IntersectionObserver(
|
||||
(entries) => {
|
||||
const en = entries[0];
|
||||
if (!en) return;
|
||||
if (en.isIntersecting && spec.add_class) {
|
||||
for (const c of String(spec.add_class).split(/\s+/).filter(Boolean)) {
|
||||
el.classList.add(c);
|
||||
}
|
||||
}
|
||||
observeHandles.delete(id);
|
||||
}
|
||||
},
|
||||
{ threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 },
|
||||
);
|
||||
io.observe(el);
|
||||
observeHandles.set(id, io);
|
||||
}
|
||||
if (thenFn) {
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "intersect",
|
||||
id,
|
||||
intersecting: !!en.isIntersecting,
|
||||
ratio: en.intersectionRatio,
|
||||
target_id: el.id || "",
|
||||
});
|
||||
}
|
||||
if (spec.once && en.isIntersecting) {
|
||||
try {
|
||||
io.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
observeHandles.delete(id);
|
||||
}
|
||||
},
|
||||
opts,
|
||||
);
|
||||
io.observe(el);
|
||||
observeHandles.set(id, io);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function buildFetchInit(spec) {
|
||||
@@ -921,8 +972,23 @@ function runIntervalEffect(exports, spec, onError) {
|
||||
intervalHandles.set(id, handle);
|
||||
}
|
||||
|
||||
const memoryKV = new Map();
|
||||
|
||||
function storageStore(scope) {
|
||||
if (scope === "cookie") return null;
|
||||
if (scope === "memory" || scope === "mem" || scope === "内存") {
|
||||
return {
|
||||
getItem(key) {
|
||||
return memoryKV.has(key) ? memoryKV.get(key) : null;
|
||||
},
|
||||
setItem(key, value) {
|
||||
memoryKV.set(key, String(value));
|
||||
},
|
||||
removeItem(key) {
|
||||
memoryKV.delete(key);
|
||||
},
|
||||
};
|
||||
}
|
||||
if (typeof localStorage === "undefined") return null;
|
||||
return scope === "session" ? sessionStorage : localStorage;
|
||||
}
|
||||
@@ -1371,12 +1437,24 @@ export async function autoMount(doc) {
|
||||
|
||||
const g = typeof globalThis !== "undefined" ? globalThis : undefined;
|
||||
if (g && g.document) {
|
||||
// Defer WASM boot until after first paint / load so LCP images are not
|
||||
// contending with a ~1.6MB wasm download on the critical path.
|
||||
const start = () => {
|
||||
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
|
||||
const run = () => {
|
||||
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
|
||||
};
|
||||
const schedule = () => {
|
||||
if (typeof g.requestIdleCallback === "function") {
|
||||
g.requestIdleCallback(() => run(), { timeout: 1500 });
|
||||
} else {
|
||||
g.setTimeout(run, 0);
|
||||
}
|
||||
};
|
||||
if (g.document.readyState === "complete") {
|
||||
schedule();
|
||||
} else {
|
||||
g.addEventListener("load", schedule, { once: true });
|
||||
}
|
||||
};
|
||||
if (g.document.readyState === "loading") {
|
||||
g.document.addEventListener("DOMContentLoaded", start);
|
||||
} else {
|
||||
queueMicrotask(start);
|
||||
}
|
||||
start();
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"name": "marqdo-bridge",
|
||||
"private": true,
|
||||
"type": "module"
|
||||
}
|
||||
@@ -185,7 +185,38 @@ fn pack_json(v: &serde_json::Value) -> *mut u8 {
|
||||
ptr::copy_nonoverlapping(len.to_le_bytes().as_ptr(), out, 4);
|
||||
ptr::copy_nonoverlapping(bytes.as_ptr(), out.add(4), bytes.len());
|
||||
}
|
||||
out
|
||||
out
|
||||
}
|
||||
|
||||
/// getrandom `custom` backend for wasm32 — no wasm-bindgen / JS glue imports.
|
||||
/// Preferable to the `js` feature which pulls `__wbindgen_*` and breaks raw mq_* ABI.
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
#[no_mangle]
|
||||
unsafe extern "Rust" fn __getrandom_custom(dest: *mut u8, len: usize) -> u32 {
|
||||
// xorshift64* seeded once; fine for uuid/non-crypto browser host helpers.
|
||||
use std::cell::Cell;
|
||||
thread_local! {
|
||||
static STATE: Cell<u64> = const { Cell::new(0x4d51_5241_4e44_4f21) };
|
||||
}
|
||||
if dest.is_null() || len == 0 {
|
||||
return 0;
|
||||
}
|
||||
let mut s = STATE.with(|c| {
|
||||
let mut v = c.get();
|
||||
if v == 0 {
|
||||
v = 0x4d51_5241_4e44_4f21;
|
||||
}
|
||||
v
|
||||
});
|
||||
let buf = unsafe { std::slice::from_raw_parts_mut(dest, len) };
|
||||
for b in buf.iter_mut() {
|
||||
s ^= s << 13;
|
||||
s ^= s >> 7;
|
||||
s ^= s << 17;
|
||||
*b = (s >> 8) as u8;
|
||||
}
|
||||
STATE.with(|c| c.set(s));
|
||||
0
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
|
||||
Vendored
+22
@@ -0,0 +1,22 @@
|
||||
Marqdo for Ubuntu (PPA)
|
||||
=======================
|
||||
|
||||
This package installs the marqdo CLI (/usr/bin/marqdo).
|
||||
|
||||
Official language extensions are not bundled. After install:
|
||||
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
|
||||
Extension packs download from https://ext.marqdo.com (then GitHub / proxy).
|
||||
|
||||
Install this package from:
|
||||
|
||||
sudo add-apt-repository ppa:cflmy/marqdo
|
||||
sudo apt update
|
||||
sudo apt install marqdo
|
||||
|
||||
Also available: GitHub Releases (Windows/Linux zips) and building from source.
|
||||
|
||||
Documentation: https://github.com/cflmy/marqdo
|
||||
PPA notes: doc/design/ubuntu-ppa.md in the upstream repository.
|
||||
Vendored
+295
@@ -0,0 +1,295 @@
|
||||
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
|
||||
bracketed label is inert prose and the parenthesized payload is the
|
||||
only executed part. Adds paren-call arguments, access() element
|
||||
access, occlusion loops, marqdo labels (two-tier search + debt
|
||||
ratchet), marqdo migrate labels, and label.missing / empty_payload /
|
||||
ref_dangling diagnostics; view renders labels as prose, payloads as
|
||||
code, stubs with a badge. 80 corpus files migrated.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 22 Oct 2026 16:30:00 +0800
|
||||
|
||||
marqdo (1.5.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.2: Foreign v3 P0/P1 — raw stdin with per-cell inputs and
|
||||
interrupt, plan generation/add/remove/value API, snapshot
|
||||
export/import/replay, view capture for static export, explicit Persist
|
||||
button, nested plan boundary.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 15:00:00 +0800
|
||||
|
||||
marqdo (1.5.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.1: View static/live execution path unified; foreign value
|
||||
passing into multi-kernel sessions; cell stdin for live/static/persistent
|
||||
kernels; build-time execution with stdout injection in static exports;
|
||||
runnable foreign writeback example; writeback block grouping.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 22:00:00 +0800
|
||||
|
||||
marqdo (1.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
|
||||
parallel fan-out, persistent Python/Node kernels, explicit state
|
||||
bridge) and document-native notebooks in view; high-contrast
|
||||
light/dark view themes, resizable code/output panes, OKF/EKC and
|
||||
Python examples on the user site. Fixes branch-local variables
|
||||
leaking into required constructor parameters.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 03:30:00 +0800
|
||||
|
||||
marqdo (1.4.6-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.6: Promote a bare self-increment to a required parameter.
|
||||
The first bold assignment LHS is a declaration (design §8.2); a missing
|
||||
argument reports missing argument for parameter, not undefined variable.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 23:56:00 +0800
|
||||
|
||||
marqdo (1.4.5-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.5: Streamable HTTP MCP (agent_mcp_serve transport=http);
|
||||
web invoke Bearer/X-Api-Key inject + unauthorized→401; openai/agent
|
||||
field access via json.get (no footnote hard-fail).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 17:40:00 +0800
|
||||
|
||||
marqdo (1.4.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.4: Soft LLM transport errors (structured status=error);
|
||||
ext/ai table-first refactor (no json.set glue).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 14:40:00 +0800
|
||||
|
||||
marqdo (1.4.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.2: Agent/LLM optimize O1–O5 — sandbox trial opt-in,
|
||||
promote sandbox proof, step_route/EFI/cost, style lint, quarantine.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 11:51:05 +0800
|
||||
|
||||
marqdo (1.4.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.1: View annot leaders — SVG mid-to-mid (mark bottom-center
|
||||
to chip top-center), unify frame chip ids, L-to-R chip density.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 15 Oct 2026 20:40:00 +0800
|
||||
|
||||
marqdo (1.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.0: Prose-unified control flow — block formula % marqdo: var=,
|
||||
arm/loop narrative + foreach sugar, image writeback ,
|
||||
view inferred-param values; welcome pages on v0.3 prose surface.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 15:53:00 +0800
|
||||
|
||||
marqdo (1.3.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.3.3: Browse document-surface Structure — narration-preserving
|
||||
markers, branch/loop frame pickers, ViewExecutionReport JSON; static
|
||||
view output / gh-pages share the same render path as live view.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 13:20:00 +0800
|
||||
|
||||
marqdo (1.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.3.0: Engineering Knowledge Compiler (EKC) — L0–L4 catalog,
|
||||
marqdo knowledge/find/reuse/duplicate/verify, Agent preflight
|
||||
(REUSE→ADAPT→CREATE), graph + context packs.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 16:50:00 +0800
|
||||
|
||||
marqdo (1.2.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.2.0: Web Artifact rewrite (ADR 0007) — Document/Endpoint/Resource,
|
||||
type:web|endpoint, web.serve/render/inspect, ext/data|security|net split,
|
||||
compose_* author surface removed; marqdo-blog Artifact example.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 11:39:04 +0800
|
||||
|
||||
marqdo (1.1.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.1.1: AI stack closure — llm ask/stream/collect, Metadata Binding,
|
||||
Skill Compilation + Adaptive Routing, MCP stdio client + resume checkpoints,
|
||||
optional plugins/llm Transport ABI (fallback lib/net).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 24 Sep 2026 20:32:00 +0800
|
||||
|
||||
marqdo (1.1.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.1.0: core surface guard + progressive contracts + MLSP for AI.
|
||||
New `marqdo check` (static contract drift) and `marqdo mlsp` (language
|
||||
server for AI: locate/syntax/validate/repair_targets/schema/repair_apply);
|
||||
`run --json` unified structured diagnostics; contract tables
|
||||
(参数/返回/字段/集合) with four validation boundaries; anchored repair
|
||||
guardrails (bounded line edits, out-of-scope refused).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 23 Sep 2026 13:30:00 +0800
|
||||
|
||||
marqdo (1.0.7-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.0.7: WS/net boundary hardening (same-origin handshake,
|
||||
require_auth/需要登录, message caps, empty-room GC); HTTP 8 MiB cap
|
||||
enforced while reading; url_encode space -> %20.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Tue, 22 Sep 2026 15:40:00 +0800
|
||||
|
||||
marqdo (1.0.3-1ppa2) noble; urgency=medium
|
||||
|
||||
* Fix Launchpad build: dh_clean -Xvendor/ so cargo vendor checksums keep
|
||||
Cargo.toml.orig (debian-only; reuse published 1.0.3.orig.tar.xz).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 21:28:00 +0800
|
||||
|
||||
marqdo (1.0.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.0.3: PPA + ext CDN; unbound GFM tables; bundled Rust for noble.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:35:00 +0800
|
||||
|
||||
marqdo (1.0.2-1ppa2) noble; urgency=medium
|
||||
|
||||
* Bundle Rust toolchain in orig (third_party/rust) so noble can build
|
||||
Cargo.lock v4 offline; drop distro cargo/rustc Build-Depends.
|
||||
* Architecture: amd64 (bundled toolchain is x86_64).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:20:00 +0800
|
||||
|
||||
marqdo (1.0.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Initial Ubuntu PPA packaging for Marqdo 1.0.2.
|
||||
* CLI only; extensions via "marqdo ext add" / ext.marqdo.com.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 09:55:00 +0800
|
||||
Vendored
+29
@@ -0,0 +1,29 @@
|
||||
Source: marqdo
|
||||
Section: devel
|
||||
Priority: optional
|
||||
Maintainer: cflmy <pingan@cflmy.cn>
|
||||
Build-Depends:
|
||||
debhelper-compat (= 13),
|
||||
build-essential,
|
||||
pkg-config,
|
||||
libssl-dev,
|
||||
ca-certificates
|
||||
Standards-Version: 4.7.0
|
||||
Homepage: https://github.com/cflmy/marqdo
|
||||
Vcs-Git: https://github.com/cflmy/marqdo.git
|
||||
Vcs-Browser: https://github.com/cflmy/marqdo
|
||||
Rules-Requires-Root: no
|
||||
|
||||
Package: marqdo
|
||||
Architecture: amd64
|
||||
Depends: ${shlibs:Depends}, ${misc:Depends}, ca-certificates
|
||||
Description: Markdown markers as an interpreted programming language
|
||||
Marqdo treats Markdown markers as executable syntax (code / return /
|
||||
control flow). This package installs the marqdo CLI.
|
||||
.
|
||||
Official extensions (web, quantum, …) are installed separately via
|
||||
"marqdo ext add" and download from https://ext.marqdo.com .
|
||||
.
|
||||
Launchpad builds use a bundled Rust toolchain under third_party/rust
|
||||
(Ubuntu noble cargo is too old for Cargo.lock v4). Rebuilds on newer
|
||||
series may use distro rustc if cargo ≥ 1.78.
|
||||
Vendored
+24
@@ -0,0 +1,24 @@
|
||||
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
|
||||
Upstream-Name: marqdo
|
||||
Upstream-Contact: cflmy <pingan@cflmy.cn>
|
||||
Source: https://github.com/cflmy/marqdo
|
||||
|
||||
Files: *
|
||||
Copyright: 2024-2026 cflmy
|
||||
License: Apache-2.0
|
||||
|
||||
License: Apache-2.0
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
.
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
.
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
.
|
||||
On Debian systems, the complete text of the Apache License version 2
|
||||
can be found in "/usr/share/common-licenses/Apache-2.0".
|
||||
+18
@@ -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)
|
||||
}
|
||||
Vendored
+2
@@ -0,0 +1,2 @@
|
||||
# engineering-stable-option.patch
|
||||
# The fix is already in upstream 2.7.1.
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
#!/usr/bin/make -f
|
||||
|
||||
export DH_VERBOSE = 1
|
||||
# Offline builds on Launchpad: vendored crates + optional bundled Rust toolchain.
|
||||
export CARGO_HOME = $(CURDIR)/debian/cargo_home
|
||||
export CARGO_NET_OFFLINE = true
|
||||
|
||||
# Noble (and older) distro cargo cannot read Cargo.lock v4 / modern crates.
|
||||
# Prefer third_party/rust from the orig tarball when present (see ppa-build-source.sh).
|
||||
BUNDLED_RUST = $(CURDIR)/third_party/rust
|
||||
ifneq ($(wildcard $(BUNDLED_RUST)/bin/cargo),)
|
||||
export PATH := $(BUNDLED_RUST)/bin:$(PATH)
|
||||
endif
|
||||
|
||||
%:
|
||||
dh $@
|
||||
|
||||
override_dh_auto_configure:
|
||||
mkdir -p debian/cargo_home
|
||||
@if [ -x "$(BUNDLED_RUST)/bin/cargo" ]; then \
|
||||
echo "Using bundled Rust: $$($(BUNDLED_RUST)/bin/rustc --version)"; \
|
||||
else \
|
||||
echo "Using system Rust: $$(rustc --version 2>/dev/null || echo missing)"; \
|
||||
fi
|
||||
@if [ -f "$(CURDIR)/.cargo/config.toml" ] || [ -d "$(CURDIR)/vendor" ]; then \
|
||||
echo "Using vendored Cargo dependencies"; \
|
||||
else \
|
||||
echo "WARNING: no vendor/ — online cargo fetch required (not for Launchpad)"; \
|
||||
fi
|
||||
|
||||
override_dh_auto_build:
|
||||
mkdir -p debian/cargo_home
|
||||
@command -v cargo >/dev/null || { echo "error: cargo not found (bundle third_party/rust or install rustc/cargo)" >&2; exit 1; }
|
||||
if [ -d "$(CURDIR)/vendor" ]; then \
|
||||
CARGO_NET_OFFLINE=true cargo build --release --locked --offline \
|
||||
-p marqdo; \
|
||||
else \
|
||||
cargo build --release --locked -p marqdo; \
|
||||
fi
|
||||
|
||||
override_dh_auto_test:
|
||||
@echo "Skipping full test suite on package build (run cargo test in CI)."
|
||||
|
||||
override_dh_auto_install:
|
||||
install -d $(CURDIR)/debian/marqdo/usr/bin
|
||||
install -m 0755 $(CURDIR)/target/release/marqdo \
|
||||
$(CURDIR)/debian/marqdo/usr/bin/marqdo
|
||||
|
||||
# dh_clean deletes *.orig by default; cargo vendor checksums require
|
||||
# vendor/**/Cargo.toml.orig. Exclude the vendored tree from that purge.
|
||||
override_dh_clean:
|
||||
dh_clean -Xvendor/
|
||||
|
||||
override_dh_auto_clean:
|
||||
dh_auto_clean
|
||||
rm -rf debian/cargo_home
|
||||
# keep vendor/ and third_party/rust (part of source package)
|
||||
-cargo clean
|
||||
Vendored
+1
@@ -0,0 +1 @@
|
||||
3.0 (quilt)
|
||||
Vendored
+2
@@ -0,0 +1,2 @@
|
||||
# Ignore temporary files while editing patches
|
||||
extend-diff-ignore = "^vendor/"
|
||||
+75
-4
@@ -13,15 +13,35 @@
|
||||
|
||||
## 当前文档
|
||||
|
||||
> **可执行知识下一阶段的阅读顺序**:[原始意图 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.1 语法宪法** |
|
||||
| [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) | **`#` 对象 / `##` 函数与方法** |
|
||||
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
|
||||
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
|
||||
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
|
||||
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单(早期方向) |
|
||||
| [design/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
|
||||
| [design/engineering-knowledge.md](design/engineering-knowledge.md) | **Engineering Knowledge Compiler(EKC)**:L0–L4、reuse、EFI |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
|
||||
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
|
||||
@@ -29,17 +49,41 @@
|
||||
| [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/网络/数学/外联/插件** |
|
||||
| [design/stdlib-mid.md](design/stdlib-mid.md) | **中层 Mid M1–M6(已落地)** |
|
||||
| [design/stdlib-mid2.md](design/stdlib-mid2.md) | **中层 Mid2:datetime / url / toml / html / fs++** |
|
||||
| [design/stdlib-datetime.md](design/stdlib-datetime.md) | **`lib/datetime`(Mid2 M7)** |
|
||||
| [design/stdlib-url.md](design/stdlib-url.md) | **`lib/url`(Mid2 M7)** |
|
||||
| [design/stdlib-toml.md](design/stdlib-toml.md) | **`lib/toml`(Mid2 M8)** |
|
||||
| [design/stdlib-html.md](design/stdlib-html.md) | **`lib/html`(Mid2 M8)** |
|
||||
| [design/stdlib-fs-mid2.md](design/stdlib-fs-mid2.md) | **`lib/fs` Mid2 M9 加厚** |
|
||||
| [design/stdlib-stats-log.md](design/stdlib-stats-log.md) | **`lib/stats` + log.fields(Mid2 M10)** |
|
||||
| [research/stdlib-gaps-after-mid.md](research/stdlib-gaps-after-mid.md) | **Mid 之后缺口盘点**(对照 Python/Go) |
|
||||
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
|
||||
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— v1 已落地** |
|
||||
| [design/foreign-kernel.md](design/foreign-kernel.md) | **外联内核:持久内核 / JSON 桥 / 状态桥 / 安全** |
|
||||
| [design/notebook-session.md](design/notebook-session.md) | **文档会话:cell / kernel / step / journal / 状态面板** |
|
||||
| [design/notebook-syntax.md](design/notebook-syntax.md) | **文档原生 notebook 语法:内核表 / 会话表** |
|
||||
| [research/foreign-notebook-decisions.md](research/foreign-notebook-decisions.md) | **外联 / notebook 决策记录(逐问逐答)** |
|
||||
| [roadmap/foreign-v2.md](roadmap/foreign-v2.md) | **外联内核 v2 路线(F0–F4)** |
|
||||
| [roadmap/notebook-session.md](roadmap/notebook-session.md) | **文档会话路线(D0–D5)** |
|
||||
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
|
||||
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
|
||||
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/ext-cdn.md](design/ext-cdn.md) | **扩展 CDN(R2 / ext.marqdo.com)与分开发版** |
|
||||
| [design/ubuntu-ppa.md](design/ubuntu-ppa.md) | **Ubuntu PPA 打包与上传** |
|
||||
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
|
||||
| [design/ext-web-go-rewrite.md](design/ext-web-go-rewrite.md) | **`plugins/web` Go 全量重写**(多语言 ABI · 网页制备完备 · 独立工作流验收) |
|
||||
| [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、布局…) |
|
||||
| [design/web-assets-and-images.md](design/web-assets-and-images.md) | **W8:favicon / Head 资源表 / 图片装配**(一次补齐) |
|
||||
| [design/web-asgi-servers-and-marqdo.md](design/web-asgi-servers-and-marqdo.md) | **Daphne/Uvicorn 等 vs Marqdo**:不能直接托管;反代 + axum `listen` |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
@@ -67,8 +111,35 @@
|
||||
| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点**(产品化 / 评测 / MCP / resume) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` 深入优化 A0–A4**(已完成) |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
|
||||
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
|
||||
| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
|
||||
| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) |
|
||||
| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 |
|
||||
| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
|
||||
| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **Accepted**:Agent/LLM 优化 O1–O5 locked |
|
||||
| [roadmap/ext-ai-optimize.md](roadmap/ext-ai-optimize.md) | **O1–O5 实现路线**(沙盒接入→证明晋升→路由/成本→lint→隔离) |
|
||||
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
|
||||
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
|
||||
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
|
||||
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
|
||||
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
|
||||
| [roadmap/executable-knowledge-gaps-2026-10-23.md](roadmap/executable-knowledge-gaps-2026-10-23.md) | **v2.1 现状与规划缺口审计(方向修订)**:保留 G01–G12 代码证据,以可读步骤、确定执行、早期 AI 复用和局部修改重排 S0–S6,严格治理按场景增加 |
|
||||
| [../tests/executable_knowledge/README.md](../tests/executable_knowledge/README.md) | **S0 作者基线门禁**:六类任务语料、作者成本计数、预期失败与 Bytecode 同名误连缺陷指纹 |
|
||||
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
|
||||
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
|
||||
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
|
||||
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
|
||||
| [design/warning-fatigue-control.md](design/warning-fatigue-control.md) | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
|
||||
| [design/staleness-providers.md](design/staleness-providers.md) | 变更检测不依赖 git:T0/T1 零依赖 + T2/T3 可选 provider |
|
||||
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
|
||||
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
|
||||
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
|
||||
| [research/occlusion-vs-executable-knowledge-2026-10.md](research/occlusion-vs-executable-knowledge-2026-10.md) | **遮蔽 vs 可执行知识复核**:v2.0.0 的 `[]()` 只做了呈现层 · 两文档例子实测不可执行 · `check`/`labels`/图边工程漂移证据 · 原始设计=类-函数调用(见 link-syntax) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# ADR 0004:网络拓展库原生实现改为 Go
|
||||
|
||||
历史说明(2026-11-10):下文业务站点仅记录当时决策背景,相关工程已移出本仓库;当前验收使用维护中的完整站点、网络站点及隔离测试,见 [当前工作流](../design/ext-web-go-rewrite.md#8-独立工作流与隔离验收)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
| Date | 2026-09-10 |
|
||||
| Related | [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) · [ext-abi.md](../design/ext-abi.md) · [0001-implementation-language.md](0001-implementation-language.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Marqdo **宿主/解释器**仍为 Rust(ADR 0001 不变)。
|
||||
- 官方插件契约是稳定 **C ABI**(`include/marqdo_abi.h`),不绑定 Rust ABI。
|
||||
- `plugins/web`(Rust/axum)已具备 W0–W8 等能力,但迭代成本高;且需验证多语言插件生态。
|
||||
- 产品目标:网络拓展库支撑完整网页制备,并以暗恋见君(外接 PostgreSQL + Redis)验收;应用层前后端均为 Marqdo 脚本。
|
||||
|
||||
## Decision
|
||||
|
||||
1. **重写** `plugins/web` 为 **Go** 共享库(`-buildmode=c-shared`),产物名仍为 `libweb.so` / `web.dll` / `libweb.dylib`。
|
||||
2. **ABI 全量兼容**(函数名、参数、语义);`ext/web` 作者面默认不动。
|
||||
3. 施工图:[ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md)。禁止在旧 Rust 插件上继续打补丁演进(ext-web C5)。
|
||||
4. 其它官方插件(agent / quantum / linalg)**暂不**强制改语言;Go web 作为多语言样板。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 构建与发版需安装 Go;CI/`marqdo ext add web` 增加 `go build` 回退。
|
||||
- 根 Cargo workspace 不再包含 `plugins/web` Rust crate(切换完成后)。
|
||||
- cgo/共享库生命周期与 `shutdown` 需严格测试。
|
||||
- 金样例 `tests/ext/web-*` 为门禁。
|
||||
@@ -0,0 +1,53 @@
|
||||
# ADR 0005:叙述统一的 Markup 映射(粗体即代码 · 斜体即返回 · 形参体推断)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
| Date | 2026-09-13 |
|
||||
| Related | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [return-hr-and-code-surface.md](../design/return-hr-and-code-surface.md) · [roadmap/markup-v0.3.md](../roadmap/markup-v0.3.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Marqdo 的产品承诺是「代码即文档 / 文档即代码」:`.mq.md` 打开是文章,运行是程序。
|
||||
- v0.2([markdown-mapping.md](../design/markdown-mapping.md))为消歧做了硬隔离:无标记 = 注释;`*…*` = 语句;`**…**` = 返回;调用必须 `>`;形参必须 `` + `名` ``。
|
||||
- 该隔离使叙述与程序**视觉割裂**;且与 AI/Markdown 习惯相反(模型偏好用 `**` 强调「要做的事」)。
|
||||
- 产品方重新审视后,希望合法化如下写法:
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
|
||||
|
||||
# main
|
||||
> 加一函数 37
|
||||
或者可以直接这么调用**加一函数 37**
|
||||
```
|
||||
|
||||
## Decision
|
||||
|
||||
1. 采纳 **Markup 映射 v0.3** 为下一版语言宪法草案,全文见 [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md)。
|
||||
2. **角色对调**:`**…**` = 代码段(含可省略 `>` 的调用);`*…*` = 返回值。
|
||||
3. **叙述中的** `` `名` ``:**首次未赋值 = 声明变量**;未使用不报错;**仅当可执行面读取时升为形参**(见设计 §4.4 · §8.2)。不设「提及性」专用语法。
|
||||
4. **形参默认由函数体/叙述推断**(升参);`` + `名` `` 仅作迁移兼容。
|
||||
5. **`>` 调用面保留**(可选)。
|
||||
6. **空返回**用标记而非关键字:推荐 `---` / `***`;显式 `*None*` / `*无*`;整行 `**`;兼容 `****`(设计 §7.2)。
|
||||
7. **不做 v0.2 双模式兼容**(摸索阶段允许破坏性变更);旧 `.mq.md` 须改写。
|
||||
8. 金样例门禁:`tests/markup-v03/`;存量 suite 随后迁移。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 叙述与代码共用 Markdown 习惯,文档可读性上升。
|
||||
- 更贴合 AI 生成粗体「操作」的偏好,降低错用标记。
|
||||
- 去掉形参表仪式,函数更像「带名字的说明段落」。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- **破坏性**:与 v0.2 金样例、Skill、教程、大量 `lib/`/`ext/` 源码不兼容,必须分波迁移或双模式。
|
||||
- 段内扫描与形参推断增加解析/语义复杂度——空返回与升参规则已在设计 §7.2 / §8.2 钉死;其余 §12 项用金样例收口。
|
||||
- view/catalog/LSP 高亮规则需同步。
|
||||
|
||||
### Neutral
|
||||
|
||||
- `#` / `##` 对象体系、标准库、插件 ABI、关键字最小集不变。
|
||||
- 输出仍是 `print` / `打印`,不是粗体/斜体。
|
||||
@@ -0,0 +1,42 @@
|
||||
# ADR 0006:Artifact Metadata Binding(`${…}` 进核心 · Metadata-only)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
| Date | 2026-09-24 |
|
||||
| Related | [binding.md](../design/binding.md) · [core-surface.md](../design/core-surface.md) · [layers.md](../design/layers.md) · [doc/next/006.md](../next/006.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Executable Document 需要声明「依赖哪些外部运行时资源」(模型名、API 密钥、base URL),而不是在 `ext/*` 里各自 `sys.env_get`。
|
||||
- [doc/next/006.md](../next/006.md) 提出 **Marqdo Binding**(`${namespace.name}`)与 Artifact Metadata 统一解析。
|
||||
- [layers.md](../design/layers.md):Language 层变更须 ADR;核心构造计数只许持平或下降;默认进 ext。
|
||||
- 正文插值会与 `$$…$$` 公式面冲突,且会新增内联构造压力。
|
||||
|
||||
## Decision
|
||||
|
||||
1. 采纳 **Artifact Metadata Binding** 为 Language 层能力;正式规范见 [binding.md](../design/binding.md)。
|
||||
2. **`${…}` 仅**在文件头 `---` Metadata 中生效;正文 / 粗体 / 调用 / 表 / 叙述 **永不**写 Binding Expression(否决 [006 §17](../next/006.md))。
|
||||
3. **不**把 Binding 记入 [core-surface.md](../design/core-surface.md) 的 19 构造守卫表——与 `import` 同属 §4「其它语言面」。
|
||||
4. 核心只做声明与解析;扩展(如 `ext/ai/llm`)消费已绑定的 `Module.metadata` / `sys.meta*` / 入口提升变量。
|
||||
5. 第一版 namespace:`env` · `arg` · `sys` · `secret`。`config` / `file` 推迟。
|
||||
6. 加载期一次 resolve → Bound Artifact;`Value::Secret` 遮掩展示;`sys.env_get` 保留为逃逸口。
|
||||
7. **Phase 2**:入口执行前把 metadata 键提升为普通变量(形参/赋值可覆盖);正文用 `` `model` ``,不再 `${env…}`。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 配置成为文档的一部分;LLM / agent / 其它 ext 共用同一套 Binding,避免各写一套 getenv。
|
||||
- 缺失 `!` 在加载期失败,而不是运行到 HTTP 401。
|
||||
- 不膨胀 CORE_CONSTRUCTS;与公式 `$$` 无冲突。
|
||||
- 正文保持普通变量语义,不引入第二套环境变量语法。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- Secret 在 `Text + Secret` 拼接时会揭示明文(供 Authorization);须约束日志面。
|
||||
- metadata 键与业务变量同名时依赖「形参/赋值覆盖」规则,作者需注意命名。
|
||||
|
||||
### Neutral
|
||||
|
||||
- `#` / `##` / `**` / `*` 等核心标记不变;frontmatter `import` 句法不变。
|
||||
@@ -0,0 +1,54 @@
|
||||
# ADR 0007:Web Document / Endpoint / Resource(破坏性 · 代码即文档)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
| Date | 2026-09-28 |
|
||||
| Related | [ext-web-artifact.md](../design/ext-web-artifact.md) · [ext-web.md](../design/ext-web.md) · [binding.md](../design/binding.md) · ADR [0006](0006-artifact-metadata-binding.md) · [layers.md](../design/layers.md) · [doc/next/007.md](../next/007.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- [`ext/web/web.mq.md`](../../ext/web/web.mq.md) 已膨胀为小型 Web Framework(Page God Object、`configure` 垃圾抽屉、碎片 Table DSL、隐式路由),与 Marqdo「代码即文档」冲突。
|
||||
- [doc/next/007.md](../next/007.md) 提出 Document / Endpoint / Resource 三原语与拆分 `ext/web` · `ext/net` · `ext/data` · `ext/security`。
|
||||
- 现行 [ext-web.md](../design/ext-web.md) **C1** 禁止为 web 改核心;Document/Endpoint 装载识别需要 Language/Runtime 参与(复用 Artifact Metadata `type`,**不**新增 CORE_CONSTRUCTS 标记)。
|
||||
- Binding(ADR 0006)已提供文件级 Metadata;`type: prompt` 先例在扩展侧消费 metadata。
|
||||
|
||||
## Decision
|
||||
|
||||
1. **采纳** Document / Endpoint / Resource 为 Web 模型一等公民;正式规范见 [ext-web-artifact.md](../design/ext-web-artifact.md)。
|
||||
2. **修订 ext-web C1**:允许核心在装载期识别 `type: web|endpoint`(及中文 `类型: 网页|端点`)并暴露 artifact 分类;**装配 / HTTP / DB 语义仍在 ext + plugin**。单元格求值、import 句法、CORE_CONSTRUCTS 计数不变。
|
||||
3. **文件级 Artifact only**:不在 `##` 函数体嵌套 `---` frontmatter(与 Binding Phase 1 / 解析器一致)。
|
||||
4. **破坏性重写作者面**:删除 `compose_*` 碎片 DSL、god `# page` 变异堆、`app.configure` 多参数抽屉、作者 `ensure_plugin`;examples 与 `tests/ext/web*` 同步重写。
|
||||
5. **目录定稿**(007 §三十五 + §四十):
|
||||
- `ext/web/` — page · route · component · dom · client · facade
|
||||
- `ext/net/` — http · websocket · url
|
||||
- `ext/data/` — db · cache · storage
|
||||
- `ext/security/` — auth · oidc · rbac
|
||||
6. **统一 View 表**:`| type | slot | value | attrs | style |`;Table = Data,禁止每函数私有方言。
|
||||
7. **declared vs system routes**:用户 route 须声明;`/_part` · `/_form` 等为 system,经 `web.inspect` 可见。
|
||||
8. **import = capability**:`import web:…` 由 facade 自动加载 native plugin;作者程序不写 `ensure_plugin` / `host_*`。
|
||||
9. **Metadata v1 锁定(原 007 未决项)**:
|
||||
- 发现:`web.serve root=` 扫描 `root/**/*.mq.md`,仅注册 `type`/`类型` ∈ {web,网页,endpoint,端点} 的文件;无 type 的库文件忽略。
|
||||
- Data:仅 flat 键 `data_source` · `data_order` · `data_where`(text;where 为 `col=val` 逗号分隔)。嵌套 YAML `data:` 推迟。
|
||||
- Result:`{ok: bool, value: any, error: text|None}`。
|
||||
- Realtime 模块名:`ext/net/websocket.mq.md`(ZH:`实时.mq.md`)。
|
||||
- ZH metadata:`类型`←type,`路由`←route,`方法`←method,`路径`←path,`请求`←request,`响应`←response,`鉴权`←auth,`数据源`←data_source,`排序`←data_order,`条件`←data_where。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- `.mq.md` 同时是文档、路由、实现与鉴权声明。
|
||||
- 与 LLM/Agent Artifact Metadata 统一心智。
|
||||
- 职责边界清晰,可独立演化 data/security/net。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- 破坏性:全部现有 web 作者程序与 smokes 必须改写。
|
||||
- Endpoint 热路径仍经 plugin → `CallLibPath` / 文件装载回调;须保持 ABI 稳定演进。
|
||||
- flat data 键表达力弱于嵌套 YAML;后续另 ADR。
|
||||
|
||||
### Neutral
|
||||
|
||||
- 不新增 Markdown 核心标记;`${…}` 仍仅 Metadata。
|
||||
- Go `plugins/web` 可分波删除死 compose ABI;作者面先断。
|
||||
@@ -0,0 +1,68 @@
|
||||
# ADR 0008:Web 热路径单解释器串行化(设计缺陷与缓解)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted**(缺陷已记录;缓解已落地;真并行见 [ADR 0009](0009-isolated-web-runtime.md)) |
|
||||
| Date | 2026-10-26 |
|
||||
| Related | [web-invoke-serialization.md](../design/web-invoke-serialization.md) · [ADR 0009](0009-isolated-web-runtime.md) · ADR [0004](0004-web-plugin-go.md) · ADR [0007](0007-web-document-endpoint.md) · [ext-abi.md](../design/ext-abi.md) · [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Go `plugins/web` 的 HTTP 服务是**多 goroutine** 的:每个请求可并发进入 `handleInvoke` / `handleInvokeLiveSSE`。
|
||||
- 每个 Endpoint 最终经 C ABI `host_query("call_lib_path", …)` 回到 Rust 宿主,在**同一个** `HostContext`(Marqdo 解释器状态)上执行作者 `.mq.md`。
|
||||
- `HostContext` **不是** `Sync`:共享可变会话、库装载、写回、事件总线等状态不能安全地被多线程同时求值。
|
||||
- 因此宿主用进程级 `INVOKE_LOCK`(`src/host/plugin.rs`)串行化所有来自 worker 线程的 `call_lib_path`。
|
||||
|
||||
### 常见误解
|
||||
|
||||
> 「web 都是单线程的吗?不能多线程吗?」
|
||||
|
||||
| 层 | 并发模型 |
|
||||
|----|----------|
|
||||
| Go HTTP / SSE flush / 取消 | **多线程(多 goroutine)** |
|
||||
| Marqdo 解释器 `call_lib_path` | **单飞(一把全局锁)** |
|
||||
| 浏览器 UI | 与后端锁无关;但若短 API 同步阻塞等待锁,会表现为「整页卡死」 |
|
||||
|
||||
**缺陷不在「HTTP 单线程」,而在「多 HTTP 工作线程共享一个非 Sync 解释器」。**
|
||||
真并行需要多解释器实例(或可共享的隔离运行时),不是去掉 Go 侧并发。
|
||||
|
||||
### 事故形态(已观测)
|
||||
|
||||
长对话(`return=sse-live` / `stream:true`)在 `CallLibPath` 期间一直持有 `INVOKE_LOCK`。并发的短路由(如 `/v1/models`、设置页探测)在旧实现里对锁 **无限期** `lock()`,HTTP 挂起 → 前端 `fetch` 无超时 → 页面无响应。重启进程可恢复,但属于运维掩盖,不是正确错误处理。
|
||||
|
||||
## Decision
|
||||
|
||||
1. **承认并文档化**本限制为宿主架构缺陷(单 `HostContext` + 全局 `INVOKE_LOCK`),不得再被表述为「web 插件只能单线程」。
|
||||
2. **缓解(已实现,非根治)**:
|
||||
- `call_lib_path` 从 worker 进入时用 **限时 try-lock**(默认 `MARQDO_INVOKE_WAIT_MS=1500`),超时返回错误串 `interpreter busy: …`。
|
||||
- Go `handleInvoke` 将含 `interpreter busy` 的错误映射为 **HTTP 503**,并设 `Retry-After: 2`。
|
||||
- **禁止**在 SSE 期间把进程级 `MARQDO_INVOKE_WAIT_MS` 拉长:那会让并发短请求重新卡死。
|
||||
- 长 SSE 在启动时用同一短预算争锁;一旦拿到则持有至调用结束(对话本来就要跑完)。
|
||||
3. **客户端契约**:短 API 必须有超时与 503 文案;不得假设「任意时刻都能同步进入解释器」。
|
||||
4. **根治(未决,另案)**:解释器池 / per-request isolate / 可 `Send` 的会话切片。未落地前,产品行为以本 ADR 的 503 语义为准。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 对话进行中,设置/模型列表等短请求约 1.5s 内失败并可读,UI 不再无限挂起。
|
||||
- 缺陷有名有姓,后续多解释器工作不会被「修好了」的假象挡住。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- 同一进程仍无法真正并行跑两个 Marqdo Endpoint 体;第二个长 SSE 也会在短预算后失败。
|
||||
- 极短窗口内,短请求若正好撞上锁交接,可能偶发 503(可重试)。
|
||||
- `MARQDO_INVOKE_WAIT_MS` 是进程环境变量;误设过大仍会复现卡顿。
|
||||
|
||||
### Neutral
|
||||
|
||||
- Go 多 goroutine、SSE 桥(`MARQDO_EVENT_FORWARD`)、取消令牌(`MARQDO_CANCEL_TOKEN`)保持不变。
|
||||
- 不改变 Document / Endpoint 作者面(ADR 0007);只约束宿主与 web 插件错误语义。
|
||||
|
||||
## Implementation pointers
|
||||
|
||||
| 位置 | 职责 |
|
||||
|------|------|
|
||||
| `src/host/plugin.rs` → `acquire_invoke_lock` | 限时争锁;失败 `set_err("interpreter busy…")` |
|
||||
| `plugins/web/.../routes_invoke.go` → `handleInvoke` | `interpreter busy` → 503 + `Retry-After` |
|
||||
| 设计长文 | [web-invoke-serialization.md](../design/web-invoke-serialization.md) |
|
||||
@@ -0,0 +1,33 @@
|
||||
# ADR 0009: Isolated Web Runtime (worker process pool)
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**;HTTP **execute** 路径正式替代 [ADR 0008](0008-web-invoke-serialization.md) 的并行性结论。`legacy_serial`(未声明且非流式)仍引用 0008 单飞 / 父进程 `CallLibPath`。 |
|
||||
| 日期 | 2026-10-26(修订 2026-10-27:disconnect≠cancel;control/read/short 无父锁) |
|
||||
| 设计 | [isolated-web-runtime-development-2026-10-26.md](../design/isolated-web-runtime-development-2026-10-26.md) |
|
||||
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝;disconnect-keeps-running;control-under-dual-execute) |
|
||||
|
||||
## 背景
|
||||
|
||||
ADR 0008 确认:Go HTTP 多线程,但所有 Endpoint 共享一把解释器锁与进程级 SSE 桥环境变量。1500ms busy → 503 只是缓解,不是并行。
|
||||
|
||||
## 决策
|
||||
|
||||
1. **首选架构**:预热的一次性 Marqdo worker 进程池;每个租约独占一个进程与 HostContext。
|
||||
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` / body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);**禁止**父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。声明的 `short`/`read`/`control` 走父进程短路径(execute 已离进程,父锁通常空闲);未声明非流式 → `legacy_serial`。
|
||||
3. **控制/读取分离**:`/_runtime/*`(cancel、events、task get)不进入解释器锁。短读勿挤占 execute worker 槽(池默认 2);产品 cancel 优先 `/_runtime`。
|
||||
4. **订阅 ≠ 取消**:`sse-live` 观察者 `ctx.Done()` 默认**只结束订阅**,不 `runtime.cancel`;后台仍 reap worker 以释放槽。仅显式 header `X-Marqdo-Cancel-On-Disconnect: 1` 才 disconnect=cancel。同步 `waitIsolatedJSON` 可保留 disconnect 取消。重连:`GET /_runtime/tasks/{id}/events` + `Last-Event-ID` / `after_seq`。
|
||||
5. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
|
||||
6. **能力探测**:`runtime.isolated_execution=1`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane=1`(短读不与 execute 抢父锁)。
|
||||
7. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
|
||||
|
||||
## 后果
|
||||
|
||||
- Execute / live SSE 不再抢进程级 SSE 桥;双流可并行(MR-01)。
|
||||
- 短读走父进程:在 dual execute 下通常仍 200(父锁空闲);勿把 short/read/control 塞进 2 槽 execute 池。
|
||||
- Legacy 未声明非流式路径仍可走父进程锁(ADR 0008)。
|
||||
- 产品(qdagent)`turn_events` / Last-Event-ID / cancel CAS 接线由 qdagent 验收;框架侧 disconnect≠cancel 与 `/_runtime` 无锁控制面已落地。
|
||||
|
||||
## 验收(摘要)
|
||||
|
||||
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`、`runtime.read_lane=1`。观察者断连后任务仍跑完并可经 `/_runtime` 重放。其余见设计文档 §12。
|
||||
@@ -0,0 +1,348 @@
|
||||
# Marqdo 智能体能力补足:恢复、工具、上下文与资源视图
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed**;本次交付设计,不代表以下新接口已实现 |
|
||||
| 日期 / 基线 | 2026-10-27(Asia/Shanghai);Marqdo `16f26d7` / 2.1.4;qdagent `68b757e` |
|
||||
| 调研与现状 | [官方资料与源码证据 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品配套 | [qdagent 智能体能力与预览设计](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 继承 | [ext/agent](ext-agent.md)、[隔离 Web 运行时](isolated-web-runtime-development-2026-10-26.md)、[工作台合同](qdagent-workbench-runtime-and-view-2026-10-25.md) |
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;让工具可发现、可验证、可审计;让结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位,不把框架改成第二套产品聊天服务。
|
||||
|
||||
现有 `src/runtime/` 已实现隔离进程、任务/事件与控制通道,本设计在其上补 Agent 步骤语义。现有 `ext/ai/agent.mq.md` 已有 step/plan/run、CALL/READ、观察压缩,继续扩展。框架不持有求道“笔记”业务表、中文按钮、默认回答字数或具体供应商账户。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | 错误分类、预算、检查点、工具效应、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | 结果分通道、输出预算、角色消息、finish reason | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD 行为 |
|
||||
| 资源 | ResourceRef、只读内容/派生预览、定位、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览组件和布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
APP[qdagent 产品策略与授权] --> RUN[ext/ai/agent step / plan / run]
|
||||
RUN --> CTX[ContextPack 与预算]
|
||||
RUN --> LLM[LLM Adapter]
|
||||
RUN --> DISPATCH[Tool Dispatcher]
|
||||
DISPATCH --> LOCAL[受控 Marqdo 函数]
|
||||
DISPATCH --> MCP[MCP Client]
|
||||
DISPATCH --> RES[资源读取 / 转换]
|
||||
RUN --> REC[Checkpoint / Effect Ledger]
|
||||
REC --> RT[既有 runtime task store / event log]
|
||||
RUN --> OUTPUT[answer / artifact / progress / diagnostic]
|
||||
RES --> VIEW[DocumentView / ResourceView]
|
||||
OUTPUT --> APP
|
||||
VIEW --> APP
|
||||
```
|
||||
|
||||
## 2. 现状与增量
|
||||
|
||||
| 已有能力 | 本轮不能误判为缺失 | 要补的具体语义 |
|
||||
|---|---|---|
|
||||
| runtime.task_control_v2/event_replay/read_lane | 不再新建一套队列与 SSE 框架 | Agent 步骤恢复与传输重放的边界 |
|
||||
| resume_save/load | 不再新建平行 checkpoint 命名空间 | 原子提交、版本摘要、作用域、效应关联 |
|
||||
| CALL、ARGS、READ、plan patch | 不废弃文档式编排 | 类型化 schema、校验错误、有限修复、稳定 call_id |
|
||||
| MCP stdio client | 不从零重写连接器 | timeout/cancel、resource、远程 transport 的能力探测 |
|
||||
| DocumentViewV1 / Locator | 不另写 `.mq.md` 解析器 | 普通资源类型、明确 renderer、历史与相对资源处理 |
|
||||
| LLM messages/usage | 不把 provider 行为交给产品猜测 | 输出预算、原生工具适配探测、角色边界与分通道 |
|
||||
|
||||
新模块路径及协议名以下均是**建议落点**。首批开发先固化 schema 与 fixture,再开放 feature bit;不得只更新 capabilities 把未实现能力标真。
|
||||
|
||||
## 3. 错误和恢复合同
|
||||
|
||||
### 3.1 ErrorV1
|
||||
|
||||
现有字符串错误保留兼容适配,新工具与 Agent 结果返回:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentErrorV1",
|
||||
"code": "tool.timeout",
|
||||
"category": "transient",
|
||||
"stage": "tool",
|
||||
"message": "读取资源超时",
|
||||
"retryable": true,
|
||||
"retry_after_ms": 1200,
|
||||
"effect_state": "none",
|
||||
"recovery_action": "retry_step",
|
||||
"call_id": "call_01",
|
||||
"details_ref": "resource:diagnostic_01"
|
||||
}
|
||||
```
|
||||
|
||||
`retryable` 仅是候选信息,最终动作由可信策略结合效应、截止时间、预算、取消状态决定。远端工具声称 readOnly/idempotent 不构成授权依据。凭证和原始堆栈不进入公开 message。
|
||||
|
||||
| 错误类别 / 例子 | 框架动作 | 不允许的动作 |
|
||||
|---|---|---|
|
||||
| transient:429、部分 5xx、连接失败 | 只在安全步骤重试,遵守 Retry-After | 无限重试、复用同一流片段直接追加 |
|
||||
| invalid_arguments:schema 不匹配 | 把字段级错误作为 observation,最多 1 次参数修复 | 启动工具后才校验;静默丢弃字段 |
|
||||
| validation_failed:编译/文档校验 | 保留候选与诊断,局部修复后重新验证 | 将未验证草稿标为成功 |
|
||||
| context_overflow | 压缩可重建上下文,保留任务/限制/未决效应 | 丢失最新用户指令、授权或版本 |
|
||||
| auth / forbidden | 直接 needs_input/blocked,交应用处理 | 换身份、扩大范围或匿名绕过 |
|
||||
| conflict / stale_revision | 重新读取版本并重新规划 | 覆盖用户修改、对写操作盲重试 |
|
||||
| capability_unavailable | 返回可行替代操作清单 | 假称已搜索、已渲染或已执行 |
|
||||
| policy_denied | 显式拒绝该动作 | 把限制当工具错误让模型规避 |
|
||||
| budget_exhausted | 保存状态与已完成结果,返回 partial | 自动增预算或伪造 completed |
|
||||
| unknown_effect / worker_crash | 对账、查询外部状态,不能判断则 needs_reconciliation | 重跑整个工作簿 |
|
||||
| cancelled | 停止新调用、保留可读产物、传播取消 | 在后台悄悄修复或恢复 |
|
||||
|
||||
初始建议:传输最多 2 次重试(总 3 次尝试),指数退避基准 0.5/1 秒并加 jitter;有 Retry-After 时使用服务端建议并受总 deadline 限制。参数修复最多 1 次,内容修复最多 2 次。预算由应用传入,框架只提供默认上限与执行机制。所有重试、修复和摘要模型调用计入同一成本账本。
|
||||
|
||||
错误指纹 `hash(tool_id, normalized_arguments, error_code, relevant_revision)` 连续出现 2 次且没有新证据时中止该策略,允许一次有依据的替代路径;不能通过改写错误文本绕过循环检测。
|
||||
|
||||
### 3.2 四类“恢复”必须分开
|
||||
|
||||
1. **续订事件**:客户端从 cursor 重放和订阅同一个 task,不发起新推理。
|
||||
2. **重试步骤**:相同逻辑 operation、同幂等键;新 invocation attempt,复用成功的前序结果。
|
||||
3. **恢复工作流**:从兼容 checkpoint 建立新 runtime task / attempt,关联 `resumed_from`,不把旧终态改回 running。
|
||||
4. **重新生成答案**:新的输出版本;已有成功工具结果可复用,用户明确重新执行才重新产生效应。
|
||||
|
||||
当前 TaskState 把 interrupted/needs_reconciliation 视为终态,沿用此约定。新增 `AgentRun` 逻辑关联只管理目标和 attempt 链;调度权仍在原 runtime。恢复请求带 `expected_revision`、checkpoint digest 与幂等键,相同请求返回同一新 attempt,冲突返回 409 对应的框架错误。
|
||||
|
||||
执行失败不必丢掉有用内容:`outcome.status = succeeded | partial | failed | needs_input | cancelled`,伴随 `answer_ref/artifacts/error/recovery_options`。HTTP 调用成功与 Agent 业务 succeeded 不再混为同一字段。
|
||||
|
||||
## 4. 检查点与工具效应
|
||||
|
||||
### 4.1 CheckpointV2
|
||||
|
||||
在 `plugins/agent/src/resume.rs` 扩展已有实现,统一根目录由宿主提供,客户端不能传任意绝对路径。保留 legacy load,但旧 checkpoint 无效应信息时默认 `manual_review`,不能自动重做写操作。
|
||||
|
||||
| 字段组 | 内容 |
|
||||
|---|---|
|
||||
| 身份 | schema、checkpoint_id、logical_run_id、task_id、attempt_id、step_id、parent_checkpoint_id |
|
||||
| 作用域 | principal_ref、workspace_id、session_id、授权 scope digest |
|
||||
| 输入 | task revision、workbook revision/hash、输入资源 revisions、knowledge generation |
|
||||
| 运行配置 | ModelSnapshot public ref、tool registry digest、policy revision、runtime compatibility |
|
||||
| 进度 | completed_steps、pending_operation、observation refs、context summary ref |
|
||||
| 约束 | 剩余 token/tool/time/cost 预算、deadline、cancel epoch |
|
||||
| 一致性 | effect ledger watermark、event seq、manifest digest、committed_at |
|
||||
|
||||
写入协议:写唯一临时文件→flush/fsync→原子 rename→提交 checkpoint 指针;持久化配置下目录 fsync 按平台支持实现。所有引用 blob 在指针提交前落盘。损坏记录报 `checkpoint.corrupt` 并尝试上一个完整版本,不能读取半个 JSON 当无历史。
|
||||
|
||||
恢复前校验身份/授权、源版本、工具 schema 与模型兼容性。权限撤销立即生效;checkpoint 不是永久授权。源文件改变返回 `checkpoint.input_changed`,重新计划受影响步骤,不能偷偷使用最新文件继续旧验证结果。
|
||||
|
||||
### 4.2 Effect ledger
|
||||
|
||||
```text
|
||||
prepared → started → committed
|
||||
↘ failed_no_effect
|
||||
↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
|
||||
```
|
||||
|
||||
每个 operation 持久记录 `operation_id/idempotency_key/args_digest/resource_scope/expected_revision/effect_class/result_ref`。幂等键作用域是 principal + workspace + logical_run + step + operation,不用随机 attempt ID 替换稳定 operation key。对同 key 不同 payload 拒绝。
|
||||
|
||||
读工具可重试;确定幂等写由服务端去重;可补偿写仅在补偿明确安全时执行;未知写先查询 receipt/版本。对外部系统不能承诺通用 exactly-once。关键 crash 窗口是“远端已成功、本地尚未记账”,必须返回 unknown 并对账。
|
||||
|
||||
本地文件使用 expected revision + staging + atomic replace;变更提交后检查点失败也靠 operation receipt 恢复。`tool.completed` 必须在结果与 receipt 可读取后提交,再对外发事件。事件发送失败不回滚已发生的业务效应。
|
||||
|
||||
不要复制 runtime 事件存储:Agent ledger 与 artifact manifest 是步骤事实,现有 runtime event log 是传输/调度事实;以 ID 关联,采用可重建投影与 outbox。跨 DB/文件不能声称一个事务完成,使用 manifest 提交点和恢复扫描补齐索引。
|
||||
|
||||
## 5. 结构化工具与调度
|
||||
|
||||
### 5.1 ToolSpecV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ToolSpecV1",
|
||||
"id": "workspace.read",
|
||||
"version": "1",
|
||||
"description": "读取授权资源的指定行范围",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"resource_id": {"type": "string"},
|
||||
"revision": {"type": "string"},
|
||||
"start_line": {"type": "integer", "minimum": 1},
|
||||
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
|
||||
},
|
||||
"required": ["resource_id"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"output_schema_ref": "ResourceReadV1",
|
||||
"effect": "read",
|
||||
"scopes": ["workspace:read"],
|
||||
"timeout_ms": 10000,
|
||||
"max_result_bytes": 65536,
|
||||
"idempotency": "safe",
|
||||
"concurrency_group": "resource-read",
|
||||
"availability": "ready"
|
||||
}
|
||||
```
|
||||
|
||||
定义由宿主/可信模块注册;用户认证、scope 与资源根由宿主注入,不接受模型提供 principal 或任意 root。`read`、`write`、`execute`、`external_write` 是策略分类,不是靠工具命名推断。
|
||||
|
||||
ToolCallV1:`call_id/tool_id/tool_version/arguments/operation_id/parent_span_id`。ToolResultV1:`ok/status/summary/structured_content/resources/citations/error/usage/truncated/next_cursor/effect_receipt_ref`。超限结果先写 artifact,再返回摘要和范围读取句柄;不把几十 MB 文本送进 prompt。
|
||||
|
||||
### 5.2 一条执行通道
|
||||
|
||||
```text
|
||||
发现 → 加载 schema → schema 校验 → 授权与范围解析 → 预算/取消检查
|
||||
→ 幂等查询 → 执行 → 结果 schema/大小校验 → receipt/结果提交 → 事件 → observation
|
||||
```
|
||||
|
||||
provider 原生 function call 与文档 `CALL:name + ARGS:{...}` 都归一到该通道。保留旧白名单适配,已有 `.mq.md ##` 可根据形参推导初始 schema,再允许显式描述收紧。转换不允许调用未暴露的框架内部函数。禁止对模型参数使用 eval/任意代码反序列化。
|
||||
|
||||
`tools.search` 返回已授权且当前可用的工具摘要;`tools.describe` 按 ID 返回完整 schema。核心 5–8 个工具可常驻,其余按需加载;此数量是产品起始配置,不写死框架。每次真正调用仍重新检查授权;搜索索引可列 unavailable 原因供诊断,但不能让未授权工具名字泄露私有连接信息。
|
||||
|
||||
初始支持 JSON Schema 的明确子集并公开能力;不支持的 schema 拒绝注册,不静默放宽。原生工具能力、并行工具调用、图片输入、结构化输出分别探测;纯文本兼容 provider 继续走 CALL,但并发和可靠性承诺按测试能力开放。
|
||||
|
||||
### 5.3 并发、MCP 与程序化执行
|
||||
|
||||
独立只读调用可并发,默认最多 4 个;修改同一资源的调用串行且用 revision CAS。依赖链、审批与取消检查保持顺序。一个并发调用失败不丢弃其他已成功结果。
|
||||
|
||||
MCP 扩展现有 client:先完善 timeout/cancel、错误映射、工具分页与 schema、resource read/link,再按 capability 增加远程 Streamable HTTP 与连接认证。stdio 不应允许模型选择任意宿主可执行文件。连接元数据归应用,凭证通过 secret handle 注入 worker,工具输出和 trace 不记录密钥。
|
||||
|
||||
工具 annotations 只是提示,可信策略确定真实效应。外部结果全部为数据,不能提升为 standing/system。MCP resource URI 转成宿主授权 ResourceRef,不允许前端直接请求任意 file:// 或内部网地址。
|
||||
|
||||
程序化工具编排和子 Agent 为后续切片:在沙箱中仅暴露注册 dispatcher,逐次执行同样的授权、预算和效应日志;禁止通过一段脚本绕过逐工具控制。子任务继承更小权限和共享总预算,不默认开放写同一资源。
|
||||
|
||||
## 6. 输出通道与上下文
|
||||
|
||||
### 6.1 AgentOutputV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentOutputV1",
|
||||
"status": "succeeded",
|
||||
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
|
||||
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
|
||||
"citations": [],
|
||||
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
|
||||
"finish_reason": "completed",
|
||||
"recovery_options": []
|
||||
}
|
||||
```
|
||||
|
||||
这是结果传输协议,不要求模型每次逐字生成这张 JSON。文档式编排仍可产出 `.mq.md`,框架把稳定产物、摘要与事件归一化。普通文本回答可没有 artifact 和 validation;未运行的内容标 `not_applicable/not_run`,不能填 passed。
|
||||
|
||||
channel 至少区分 `answer/artifact/progress/diagnostic`。只有 answer delta 可追加到聊天正文;工作簿 token 和工具日志进入其他通道。进度是可观察动作摘要,不要求或泄露模型内部思维链。
|
||||
|
||||
应用传 `ResponsePolicy`:detail level、目标长度、最大输出 tokens、是否允许 artifact、用户显式需求。框架负责 budget 和 finish_reason,中文字符数与最终文案由应用决定。达到 token 上限返回 `length_limited` 和完整/不完整标记,不能裁剪 JSON/代码后假装成功。
|
||||
|
||||
优先从已验证产物结构投影摘要。必要时增加一次受预算控制的摘要模型调用;摘要不得新增未经证据支持的结论。修复成功后 accepted candidate、结果正文、artifact revision 与 verification digest 必须全部一致。
|
||||
|
||||
### 6.2 ContextPackV2
|
||||
|
||||
按优先级组装:可信运行规则→最新用户目标/约束→用户选中资源范围→未决操作/成功步骤摘要→检索证据→近期对话→可回读历史。保持角色结构,不把用户/工具文本简单拼进系统指令。
|
||||
|
||||
每个 item 携带 `origin/trust/resource_ref/revision/token_estimate/priority`。预算初值建议保留模型窗口 20% 给输出与协议开销;上下文使用达到可用预算 70% 时触发整理,具体比例配置化。优先剔除可重读的完整工具输出,保留摘要、引用和失败恢复锚点。
|
||||
|
||||
Compaction 必须保留:目标、用户限制、当前计划、已完成步骤、待决写入、授权范围、输入版本、已接受产物与引用、余量。summary 绑定其 source event range 和 digest,不能当成新的已验证知识。工具输入过时须重读,不能依赖压缩摘要执行写入。
|
||||
|
||||
已有 EKC/agent memory 继续提供知识发现和复用。长期用户记忆的创建/修改/删除政策归 qdagent;网页中的指令不能自动变成长期偏好。
|
||||
|
||||
## 7. 统一资源与只读视图
|
||||
|
||||
### 7.1 ResourceRefV1 / ResourceViewV1
|
||||
|
||||
ResourceRef 统一携带 `resource_id/workspace_id/kind/media_type/revision/digest/title/size/origin/locator`;opaque ID 由宿主映射,不将浏览器 path 直接当文件权限。revision 是内容版本,generation 是知识发布代,两者不混用。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ResourceViewV1",
|
||||
"resource": {
|
||||
"resource_id": "res_01", "workspace_id": "ws_01", "kind": "file",
|
||||
"revision": "sha256:example", "media_type": "text/markdown", "title": "设计说明"
|
||||
},
|
||||
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
|
||||
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
|
||||
"outline": [],
|
||||
"locators": [],
|
||||
"completeness": "complete",
|
||||
"no_exec": true,
|
||||
"diagnostics": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
```
|
||||
|
||||
继续把 `.mq.md` 交 `view.document`,ResourceView 只包装/扩展,不能另解释一套 Marqdo 语义。普通 `.md/.txt/代码/JSON/CSV` 走媒体类型处理,避免全仓语义编译。浏览器组件由 qdagent 实现,框架只提供可读内容、受控片段或短期授权 blob 引用。
|
||||
|
||||
`fragment`、`text`、`blob_ref` 是互斥载荷,按严格 format enum 解码。未知格式返回 unsupported,不能用 `format.includes('html')` 猜测 HTML。为空与加载失败必须有独立状态。
|
||||
|
||||
### 7.2 格式矩阵
|
||||
|
||||
| 格式 | 框架提供 | 前端消费 | 未具备能力时 |
|
||||
|---|---|---|---|
|
||||
| `.mq.md` | 静态 DocumentView、outline、节点/引用 | 正文、语义链接、源码切换 | 只读源码 + 明确诊断,不执行 |
|
||||
| Markdown / 笔记正文 | 共享静态 Markdown→受控结构/HTML、相对资源引用 | 标题、列表、表格、代码、链接 | 纯文本 |
|
||||
| 文本/代码 | 分页行片段、编码信息、行定位 | 行号与语法高亮 | 编码提示/下载 |
|
||||
| JSON / CSV | 有界解析、路径/行列定位、分页 | 树/表/源码 | 原始文本,标格式错误 |
|
||||
| 图片 | 授权 blob、尺寸/元信息 | 缩放/旋转/替代文本 | 下载,不暗示已做 OCR |
|
||||
| PDF | blob、页元信息,可选提取插件 | PDF.js 页渲染与定位 | 文件卡;提取不可用不阻止支持的视觉预览 |
|
||||
| DOCX/XLSX/PPTX | 受限转换插件,可选 PDF/HTML 派生物 | 按派生格式预览 | 未安装转换器,保留下载 |
|
||||
| HTML/SVG | 默认源码;允许时经严格清洗或受限派生物 | 隔离预览 | 不以内联可执行页面显示 |
|
||||
| 未知二进制/压缩包 | 元数据 | 下载卡 | 不自动解压/执行 |
|
||||
|
||||
提取、预览、执行各有独立 capability。办公转换、OCR 使用受限 worker,禁宏与网络、限制时间/内存/页数/解压膨胀比;结果绑定原件 digest、转换器版本和参数。首期不承诺保真编辑。
|
||||
|
||||
### 7.3 安全、定位、缓存
|
||||
|
||||
所有读取先校验宿主授予的 workspace/resource scope,canonicalize 并处理 symlink 逃逸;读取句柄与校验对象一致,防路径检查后替换。读取原件的身份权限不可被缓存绕过。
|
||||
|
||||
预览绝不调用 `run/verify` 或有执行副作用的 view 路径;正文中的 Marqdo 调用链接只展示语义与导航,执行需单独工具调用与授权。远程图片、相对链接、资源 URL 经受控解析;下载入口不允许任意内网 fetch。
|
||||
|
||||
HTML 清洗在框架产出侧和浏览器插入侧都有明确边界;用成熟 allowlist 实现而非正则。禁止 script/event handler、危险 URI、任意 style/form/嵌入对象。前端配 CSP;对需要交互的产物另建无权限 sandbox,不复用文档渲染器。
|
||||
|
||||
缓存 key:workspace + resource ID + revision + renderer version + render options + policy version;命中前重新授权。历史 revision 不存在就返回 `version_unavailable`,不能默默展示当前版。locator 支持 node/span/line/page/cell,失效时标 stale 并提供用户主动查看最新版的操作。
|
||||
|
||||
建议首期限制:文本片段 256 KiB、代码单次 500 行、CSV 单次 200 行;更大内容分页,完整文件保留。数值需压测校准,不作为现有系统性能声明。
|
||||
|
||||
## 8. 事件、可观测性与能力协商
|
||||
|
||||
复用 RuntimeEventV2 的 task/run/attempt/seq/event_id。拟增加事件类型:`agent.step.started/completed`、`tool.started/completed/failed`、`recovery.scheduled/exhausted`、`checkpoint.committed`、`artifact.updated`、`answer.delta/committed`、`context.compacted`。现有 `message.delta` 由兼容适配映射 answer channel,不能同时重复消费两套事件。
|
||||
|
||||
终态提交包含 accepted output manifest、last_seq、result digest;断流客户端能通过快照补齐最终答案。stream delta 是预览,最终 committed revision 是权威。统计每次尝试的 usage,摘要和修复调用分别标 purpose;未知计量保持 unknown。
|
||||
|
||||
拟新增 capability:`agent.error_v1`、`agent.checkpoint_v2`、`agent.tool_schema_v1`、`agent.output_channels_v1`、`agent.context_pack_v2`、`resource.view_v1`,以及各 media renderer 的独立版本/可用状态。保持现有 probe,新增字段向后兼容;未知 feature 当不可用。
|
||||
|
||||
trace 记录因果 ID、耗时、错误类别、参数摘要、资源版本和 effect receipt。正文与密钥按配置脱敏,不默认把用户全文件复制进日志。输出中不包含模型私有推理;可审计的是实际动作与结果。
|
||||
|
||||
## 9. 分阶段实现与文件落点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 依赖 / 退出条件 |
|
||||
|---|---|---|---|
|
||||
| M-A0 | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | 上述协议、旧适配、状态映射 | 先冻结跨仓字段,未知字段/版本可降级 |
|
||||
| M-A1 | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、新 recovery/effects 支撑模块 | 分类错误、有界修复、accepted candidate、原子检查点 | M-A0;故障注入不重复写、旧记录不冒险自动恢复 |
|
||||
| M-A2 | `plugins/agent/src/lib.rs`、`mcp_client.rs`、新 tool registry/dispatcher | schema 工具、调用统一、分页与结果资源 | M-A0;未授权调用为 0,失败结果结构正确 |
|
||||
| M-A3 | `src/workbench/document_view.rs`、新 resource_view、媒体适配模块 | ResourceRef/View、普通格式静态阅读、no-exec | M-A0;资源定位与安全语料通过 |
|
||||
| M-A4 | `ext/ai/agent.mq.md`、`plugins/llm/src/lib.rs`、`src/workbench/run_context.rs` | 输出分通道、预算、ContextPackV2 | M-A1/2;原生和纯文本 provider fixture 都可用 |
|
||||
| M-A5 | `src/runtime/` 的既有存储/事件适配、MCP 与转换插件 | 恢复对账、PDF/Office 插件、远程 MCP | M-A1/2/3;持久模式 crash/restart 通过 |
|
||||
| M-A6 | plan/subtask/sandbox 扩展 | 程序化工具、有界委派与可选浏览器 | 后置;须证明任务收益和预算/效应可控 |
|
||||
|
||||
先交 M-A0 与 qdagent P0 的静态阅读/错误结果修复;不要让完整 checkpoint v2 阻塞笔记预览。M-A1 可先上只读重试,写恢复待 ledger 通过再开放。新特性默认关闭直到对应合同实测通过,旧路径继续可读。
|
||||
|
||||
## 10. 验收与评测
|
||||
|
||||
所有目标是 proposed gate,尚未实测。基础机制用确定性 fake provider/tool;真实 provider 做少量单独 smoke 并记录费用,不能把随机模型输出作为唯一门禁。
|
||||
|
||||
| 编号 | 故障/任务 | 必须观察到的结果 |
|
||||
|---|---|---|
|
||||
| MA-T01 | 第一次 429、第二次成功 | 尊重退避、计量 2 次、最终只有一个 accepted answer |
|
||||
| MA-T02 | 连续 schema 参数错误 | 一次修复后停止;工具未在无效参数下执行 |
|
||||
| MA-T03 | 工具写成功但 receipt 提交前杀 worker | unknown_effect→查询对账;写计数不增加 |
|
||||
| MA-T04 | checkpoint 写一半杀进程 | 读取上个完整 checkpoint 或明确 corrupt,不产生伪成功 |
|
||||
| MA-T05 | 终态事件丢失、cursor 重放 | 最终快照恢复完整消息,工具执行次数不增加 |
|
||||
| MA-T06 | 恢复请求重复/并发 | 同一幂等键只产生一个恢复 attempt |
|
||||
| MA-T07 | 用户取消与重试定时器竞争 | 取消生效后无新工具调用,旧任务不复活 |
|
||||
| MA-T08 | 执行中资源/权限改变 | stale/conflict/forbidden,不覆盖新版本 |
|
||||
| MA-T09 | 恶意文本伪造 CALL/system | 不跨越工具白名单和授权范围 |
|
||||
| MA-T10 | `.mq.md` 预览含写文件/联网语句 | 哨兵文件/网络计数不变;只读渲染成功或安全降级 |
|
||||
| MA-T11 | 资源格式、超长输出、路径逃逸 | 正确 renderer/分页;越界拒绝;无 HTML 注入 |
|
||||
| MA-T12 | 修复原文 A 得到通过验证的 B | answer/artifact/verification 都绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后继续 | 最新约束、待决效应、资源版本与剩余预算不丢失 |
|
||||
| MA-T14 | 旧 CALL、旧 DocumentView 消费端 | 基础行为可用,能力缺失有明确返回 |
|
||||
|
||||
先运行受影响的 Rust/Go/Marqdo 合同与既有隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标:已缓存 100 KiB 文本视图服务端 p95 < 300 ms、核心工具发现 p95 < 100 ms,基准机器/并发/冷暖缓存必须记录;第三方网络延迟单独列出。
|
||||
|
||||
## 11. 迁移、回滚与未决项
|
||||
|
||||
兼容迁移按“新增协议→双读→新写→验证→逐步移除旧适配”推进。`.mq.md` 源码与旧运行产物不批量重写;旧 resume JSON 可读取但不能自动升级成带副作用保证的检查点。v2 checkpoint/ledger 保留 schema 版本,新老版本不并发写同一运行。
|
||||
|
||||
回滚关闭新工具自动发现、输出通道或转换器时,已提交资源和最终答案仍可读;执行恢复中的任务先 drain/停止接纳,不能切回会盲重做写操作的旧路径。迁移前备份可变索引与 manifest,回滚不删除用户产物。
|
||||
|
||||
实现前验证项:现有 runtime 持久存储可提供的原子提交边界、各平台 fsync/rename 行为、LLM adapter 原生 tool call 流式兼容、转换插件部署体积。协议优先按本文保守语义实现,验证不能满足则 feature 保持不可用,不阻塞已经完成的只读预览切片。
|
||||
@@ -0,0 +1,252 @@
|
||||
# 语义评估:参数能否从上下文推断(含叙述式调用)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留参数来源可见、避免隐藏调用者环境的边界;下文已被否决的 L0 建议不可重新启用。自然语言只连接和解释,不能成为隐式执行触发器;当前指导见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「让函数参数从上下文推断,`对**n=31**执行**加一函数**` 这种写法可能吗」 |
|
||||
| 方法 | 运行时实测 8 组 + 全仓库语料扫描(1322 个函数)+ 源码比对 |
|
||||
| 相邻 | [call-syntax-from-marks.md](call-syntax-from-marks.md)(**接替本文 §3 的设计**)· [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
|
||||
|
||||
> **后续更正**:本文 §3 提出的 L0「叙述式调用」用**未标记的词**(`执行`)触发调用,
|
||||
> 这会破坏「叙述默认安全、只有标记才执行」的底层原则,已被否决。
|
||||
> 在「只执行标记」约束下重新设计的调用语法见
|
||||
> [call-syntax-from-marks.md](call-syntax-from-marks.md)
|
||||
> (含树遍历 vs 字节码 3.8× 实测、叙述顺序导致位置绑定翻转的实验)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论:你的示例其实**不需要**隐式推断
|
||||
|
||||
先把一个关键事实摆出来:**你的例子里 `n=31` 明明写在那儿**。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
对**n=31**执行**加一函数**
|
||||
```
|
||||
|
||||
`n` 的绑定**就写在句子里**,这不是「从上下文推断」,这是**具名实参换了语序**。
|
||||
所以这个写法需要的是**新的叙述式调用语法**,不是新的作用域语义。
|
||||
|
||||
它今天跑出来的结果很能说明问题:**无输出、无报错、退出码 0**。
|
||||
不是参数推断失败,而是 `执行**加一函数**` 里的裸名字**只是被求值然后丢弃**,
|
||||
从来没被当成一次调用。
|
||||
|
||||
三层拆解:
|
||||
|
||||
| 层 | 写法 | 需要什么 | 裁决 |
|
||||
|----|------|---------|------|
|
||||
| **L0 叙述式调用** | `对**n=31**执行**加一函数**` | 只要语法糖(绑定仍在句中) | ✅ **可做,且安全** |
|
||||
| **L1 就近绑定** | 上一行 `**n=31**`,下一行 `执行**加一函数**` | 段落级隐式作用域 | ⚠️ 能做但危险,不建议 |
|
||||
| **L2 真隐式** | 只写 `执行**加一函数**`,n 全靠上下文 | 动态作用域 | ❌ **不建议**,见 §4 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 实测:今天到底发生了什么
|
||||
|
||||
| # | 用例 | 实测 | 说明 |
|
||||
|---|------|------|------|
|
||||
| 1 | 你的示例原样 | **无输出、无报错、exit 0** | 静默 no-op |
|
||||
| 2 | 同样写法 + `> print text=`n`` | `main里的n=31` | **散文行里的 `**n=31**` 真的执行了** |
|
||||
| 3 | 只写 `对`加一函数`执行` | `done`,无报错 | 裸名字只被求值丢弃,**未调用** |
|
||||
| 4 | `**n = 31**` + `> 加一函数`(不传参) | `missing argument for parameter n` | **函数看不见调用者的 `n`** |
|
||||
| 5 | `> 加一函数 n=31` | `32` | 显式写法今天就能做 |
|
||||
| 6 | `# main` 读 frontmatter `税率` | `0.1` ✅ | 入口可见 |
|
||||
| 7 | `## 函数` 读同一个 `税率` | `undefined variable` ❌ | 函数不可见 |
|
||||
| 8 | 浏览器 WASM 入口调用函数 | metadata + `entry_bindings` **都会传** | 见 §5,**与 CLI 不一致** |
|
||||
|
||||
**第 2 与第 3 条合起来是关键**:散文行里的粗体确实会执行,但一个裸函数名在粗体里
|
||||
只是一个**表达式语句**(值算了就丢),不会变成调用。所以「看起来该调用」的句子,
|
||||
实际什么也没做——又是一次静默失败(与 D9 同一类)。
|
||||
|
||||
**第 4 条是语义基石**:Marqdo 现在的作用域是**严格分离**的,
|
||||
函数只能看到自己的形参与局部变量。你想要的 L2,就要拆掉这块基石。
|
||||
|
||||
---
|
||||
|
||||
## 2. 你自己的担心是对的:数据在这里
|
||||
|
||||
你提到「大项目变量名会难以使用」。我把仓库里 `lib/ ext/ examples/ tests/` 全扫了一遍:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 扫描函数数 | **1322** |
|
||||
| 不同形参名 | 819 |
|
||||
| **被 ≥5 个函数共用的形参名** | **130 个** |
|
||||
|
||||
撞车最严重的一批:
|
||||
|
||||
| 形参名 | 用它的函数数 |
|
||||
|--------|-------------|
|
||||
| `path` | **70** |
|
||||
| `value` | 59 |
|
||||
| `text` | 53 |
|
||||
| `id` | 47 |
|
||||
| `list` | 38 |
|
||||
| `内容` | 38 |
|
||||
| `路径` | 35 |
|
||||
| `a` / `b` | 各 32 |
|
||||
|
||||
结论很直接:**如果参数靠上下文推断,那么每次调用一个读 `text` 的函数,
|
||||
它都会去捡当前作用域里的 `text` 是什么**。53 个函数在等这个值——
|
||||
撞车是常态,不是例外。这不是「大项目才有」的问题,中型项目就已经不可控。
|
||||
|
||||
---
|
||||
|
||||
## 3. L0:叙述式调用(推荐做)
|
||||
|
||||
### 3.1 目标写法
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对`n`我们让**n=n+1**之后返回*n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 对 n=31 执行 加一函数**
|
||||
> print text=`结果` # → 32
|
||||
```
|
||||
|
||||
### 3.2 语义映射(零模型改动)
|
||||
|
||||
```
|
||||
对 <绑定子句> 执行 <函数名> ≡ Call { callee: <函数名>, args: [<绑定子句>…] }
|
||||
```
|
||||
|
||||
也就是**纯粹换语序**的语法糖。它与今天的
|
||||
|
||||
```markdown
|
||||
**结果 = > 加一函数 n=31**
|
||||
```
|
||||
|
||||
产出**同一个 `CallExpr`**。因此:
|
||||
|
||||
| 面 | 影响 |
|
||||
|----|------|
|
||||
| 契约校验(T2.1/T2.2) | **不变**(实参照常绑定与校验) |
|
||||
| EKC 指纹 `collect_calls` | **不变**(callee 仍是静态名) |
|
||||
| 字节码 `Op::Call(fid, argc)` | **不变** |
|
||||
| 序列化 / 沙箱 | **不变** |
|
||||
| `view` 渲染 | 需决定回显哪一种语序 |
|
||||
|
||||
这正是它与「一等函数」「动态作用域」的本质区别:**只改写法,不改调用模型。**
|
||||
|
||||
### 3.3 设计细节要定的三件事
|
||||
|
||||
1. **动词**:`执行` 目前**不是**关键字;而 `调用` **已经是**关键字(`src/aliases.rs:39`
|
||||
把 `调用` 映射到内建 `call_fn`)。两个近义词并存会混乱,需要二选一或明确分工。
|
||||
2. **绑定子句的边界**:`对 n=31 执行 …` 里 `n=31` 到 `执行` 之间是参数区;
|
||||
多参数写 `对 n=31 m=2 执行 …`。
|
||||
3. **与散文的冲突**:`对` 起头的行今天是叙述(CJK 开头 = 注释)。
|
||||
要让这行变成代码,得给「叙述里出现 `执行 <函数名>`」一个可判定的规则,
|
||||
否则又是一处「看起来是代码、实际是注释」的静默陷阱。
|
||||
|
||||
---
|
||||
|
||||
## 4. L2:真隐式参数(不建议)
|
||||
|
||||
### 4.1 它到底是什么
|
||||
|
||||
L2 = **动态作用域**(dynamic scoping):被调函数在**调用者的环境**里查找自由变量。
|
||||
历史上被反复试过、也反复放弃:早期 Lisp 改成词法作用域、Shell 的动态作用域被视为坑。
|
||||
|
||||
### 4.2 七条硬伤(每条都是具体后果,不是理论洁癖)
|
||||
|
||||
| # | 问题 | 具体后果 |
|
||||
|---|------|---------|
|
||||
| 1 | **同名捕获** | `加一函数` 调 `记录日志`,两者都读 `text` → 日志函数静默拿到加一的局部值,输出错内容而不报错 |
|
||||
| 2 | **递归自毁** | `n=n+1` 后调自身:内层看到的是**已被改过的** n(还是副本?)——必须新增一套遮蔽规则,而规则本身又会成为新的坑 |
|
||||
| 3 | **无法复用** | 同一函数两次不同入参,只能反复改外部变量并祈祷调用顺序,等于把「参数」退化成全局可变状态 |
|
||||
| 4 | **契约报废** | `call_arg_diag` 在**调用边界**校验实参类型;如果不传实参,就没有校验点。T2.1/T2.2 契约体系直接失效 |
|
||||
| 5 | **指纹/arity 失真** | `collect_calls` 记录被调名,arity 由形参推断;隐式调用在 AST 上看起来是零参调用 → 复用预检、`plan` 能力匹配、查重全都失真 |
|
||||
| 6 | **沙箱与序列化** | `sandbox.run` 以隔离方式执行文档;隐式依赖外部作用域会破坏隔离语义;环境也必须可序列化 |
|
||||
| 7 | **不可审计** | 函数行为依赖看不见的上下文——这就是「全局可变状态」的经典问题,与「文档即程序、可被人读懂」直接冲突 |
|
||||
|
||||
再叠加 §2 的数据(130 个名字被 ≥5 函数共用),第 1 条不是边角情况,而是默认情况。
|
||||
|
||||
### 4.3 但有一个**受限版**值得考虑
|
||||
|
||||
如果你真正想要的是「短脚本读起来顺」,那么下面这个版本是安全的:
|
||||
|
||||
> **常量默认值**:允许函数在**未传入**某形参时,从**文件级常量**取值。
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 报价
|
||||
税率: 0.1
|
||||
---
|
||||
|
||||
## 含税
|
||||
+ `金额`
|
||||
|
||||
*`金额` * (`税率`)* # 税率 未传入 → 取 frontmatter 常量
|
||||
|
||||
# main
|
||||
|
||||
**a = > 含税 金额=100** # 10
|
||||
**b = > 含税 金额=100 税率=0.06** # 6,显式覆盖
|
||||
```
|
||||
|
||||
为什么它安全而 L2 不安全:
|
||||
|
||||
| 维度 | L2 动态作用域 | 常量默认值 |
|
||||
|------|--------------|-----------|
|
||||
| 取值来源 | 调用者的**任意**变量 | 文件顶部**写一次**的常量 |
|
||||
| 静态可判定 | ❌ 取决于运行路径 | ✅ 打开文件就能看到 |
|
||||
| 随调用者变化 | ✅ 会变(最危险) | ❌ 不会 |
|
||||
| 契约 | 失效 | 仍可校验(实参照常声明) |
|
||||
| 序列化/沙箱 | 破坏隔离 | 可序列化(常量是数据) |
|
||||
| 复用 | 破坏 | 不受影响 |
|
||||
|
||||
**关键差别**:常量是**文档的一部分**(frontmatter 就在文件开头,人读得到),
|
||||
而动态作用域的值是**运行路径的一部分**(人读不到)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带发现的真问题:CLI 与 Web 的环境不一致
|
||||
|
||||
实测 §1 第 6/7/8 条时发现:
|
||||
|
||||
| 路径 | 函数可见环境 | 源码 |
|
||||
|------|-------------|------|
|
||||
| `# main`(CLI 运行) | frontmatter metadata ✅ | `src/interp.rs:473` `Env::with_metadata` |
|
||||
| **普通函数调用** | 只有实参 ❌ | `eval_call` 用 `Env::new()` |
|
||||
| **浏览器 WASM 入口** | metadata ✅ + `# main` 的 `entry_bindings` ✅ | `invoke_in_entry`(`src/interp.rs:365`) |
|
||||
|
||||
也就是说:**同一份文档,在浏览器里函数能读到 frontmatter 常量、还能读到 `# main`
|
||||
的绑定;在 CLI 里读不到。** 行为随运行面不同而不同。
|
||||
|
||||
这是一个**真实缺陷**,已记入 [D11](../research/qdagent-refactor-defects-2026-10.md):
|
||||
|
||||
- 对使用者:同一文件在 Web 能跑、在 CLI 报 `undefined variable`,极难排查
|
||||
- 对设计:说明「受控环境通道」其实已经存在(只是没在 CLI 打开),
|
||||
这既是 L2 受限版的现成基础,也是必须先统一的地方
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议
|
||||
|
||||
| 优先级 | 事项 | 性质 |
|
||||
|--------|------|------|
|
||||
| 1 | **先统一 CLI/Web 的函数环境**(D11) | 修缺陷,消除行为分裂 |
|
||||
| 2 | **做 L0 叙述式调用**(`对 X 执行 F`) | 纯语法糖,零模型改动,554 回归可守 |
|
||||
| 3 | 若要「少写参数」,做**常量默认值**(§4.3) | 受控隐式,静态可判定 |
|
||||
| 4 | **不做 L2 动态作用域** | 七条硬伤 + 130 个撞车名 |
|
||||
|
||||
关于「代码即文档」的取向,我的理解是:
|
||||
|
||||
> 文档化的是**写法**(句子怎么读),不是**语义**(值从哪来)。
|
||||
> 让句子更像人话是值得的;让值从看不见的地方来,是把可读性换成不可预测性。
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **L0 是否采纳?** 若采纳,动词用 `执行` 还是复用已有的 `调用`?
|
||||
2. **`对…执行…` 的行如何与散文区分**(§3.3 第 3 点)?这决定它会不会变成新的静默陷阱。
|
||||
3. **常量默认值**(§4.3)要不要做?
|
||||
4. **D11(CLI/Web 环境不一致)** 是否现在就修?我建议先修它,因为它会影响 L0/L2 的所有验证结论。
|
||||
@@ -0,0 +1,187 @@
|
||||
# Marqdo Binding · Artifact Metadata
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Phase 1 + Phase 2(scope lift)** |
|
||||
| 日期 | 2026-09-24 |
|
||||
| ADR | [0006-artifact-metadata-binding.md](../adr/0006-artifact-metadata-binding.md) |
|
||||
| 讨论稿 | [doc/next/006.md](../next/006.md) |
|
||||
| 实现 | `src/binding/` · `Module.metadata` · entry env lift · `sys.meta` / `sys.meta_get` · `marqdo run --bind` |
|
||||
|
||||
> **边界**:核心负责「声明与解析配置」;扩展负责「解释配置的语义」。
|
||||
> **`${…}` 只出现在文件头 Artifact Metadata**——正文 / 粗体 / 调用 / 表 **永不**写 `${env…}`(否决讨论稿 §17)。正文使用已绑定的普通名字。
|
||||
|
||||
---
|
||||
|
||||
## 1. Artifact Metadata
|
||||
|
||||
文件开头成对 `---` 之间为 **Artifact Metadata**(声明式元信息环境),不是「随便贴的 YAML」。
|
||||
|
||||
```text
|
||||
.mq.md
|
||||
├── Metadata ← Identity / Configuration / Dependencies / Bindings
|
||||
└── Executable Body
|
||||
```
|
||||
|
||||
- `import bind:…` / `导入` 行:模块依赖(既有语义不变)。
|
||||
- 其它 `key: value` 行:元信息;值可为字面量或 **Binding Expression**。
|
||||
- Phase 1 仅支持 **flat** 键(同级 `key: value`);块标量 `>` / `|` 收成 Text。
|
||||
|
||||
例:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: demo
|
||||
type: llm
|
||||
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
|
||||
api_key: ${secret.OPENAI_API_KEY!}
|
||||
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
|
||||
import:
|
||||
sys: lib/sys.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
加载后内部为已绑定的 `Module.metadata`(确定性快照),执行期不再对同一键反复 `getenv`。
|
||||
|
||||
---
|
||||
|
||||
## 2. Binding Expression
|
||||
|
||||
外形:
|
||||
|
||||
```text
|
||||
${expression}
|
||||
```
|
||||
|
||||
### 2.1 路径
|
||||
|
||||
```text
|
||||
${namespace.name}
|
||||
```
|
||||
|
||||
| Namespace | 意义 | Phase 1 |
|
||||
|-----------|------|---------|
|
||||
| `env` | 进程环境变量 | ✅ |
|
||||
| `arg` | CLI / Runtime 绑定(`marqdo run --bind KEY=VALUE`) | ✅ |
|
||||
| `sys` | 系统信息:`cwd` · `platform` | ✅ |
|
||||
| `secret` | 敏感环境变量 → `Value::Secret` | ✅ |
|
||||
| `config` | 配置 Artifact | 推迟 |
|
||||
| `file` | 外部文件内容 | 推迟 |
|
||||
|
||||
### 2.2 默认与必需
|
||||
|
||||
```text
|
||||
${env.OPENAI_MODEL ?? "gpt-4o-mini"}
|
||||
${secret.OPENAI_API_KEY!}
|
||||
```
|
||||
|
||||
- `A ?? B`:A 缺失(未设置 / 空)则用 B。
|
||||
- `A!`:A 必须存在,否则加载失败(`config.required_binding_missing`)。
|
||||
|
||||
### 2.3 类型转换
|
||||
|
||||
```text
|
||||
${int(env.MAX_TOKENS ?? "4096")}
|
||||
${float(env.TEMPERATURE ?? "0.2")}
|
||||
${bool(env.STREAM ?? "false")}
|
||||
```
|
||||
|
||||
### 2.4 独占 value vs 插值
|
||||
|
||||
| 形态 | 语义 |
|
||||
|------|------|
|
||||
| `model: ${env.OPENAI_MODEL}` | **Value binding** — 保留解析后的类型(含 Secret) |
|
||||
| `title: "Hello ${env.USER}"` | **Interpolation** — 结果为 Text |
|
||||
| `model: gpt-4o-mini` | **Literal** — 字面量;**不会**被环境变量静默覆盖 |
|
||||
|
||||
---
|
||||
|
||||
## 3. Resolution Policy
|
||||
|
||||
对每个 metadata 键:
|
||||
|
||||
1. 解析该键的字面量 / Binding / 插值(字面量定稿后不受 env 覆盖)。
|
||||
2. 若 CLI 提供了同名 `--bind KEY=VALUE`,**覆盖**该键的最终值(Text)。
|
||||
3. Binding 内部查找顺序(仅当表达式写出时):`arg` / `env` / `secret` / `sys` 按表达式 namespace;`??` 链从左到右。
|
||||
|
||||
推荐作者意图:
|
||||
|
||||
```text
|
||||
CLI --bind
|
||||
→ Artifact 字面量 / 已写死的 Binding 结果
|
||||
→ Binding 源(env / secret / …)
|
||||
→ ?? 默认
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Secret
|
||||
|
||||
`${secret.NAME}` → `Value::Secret`。
|
||||
|
||||
- `print` / `str` / Display → `<secret>`(不泄露)。
|
||||
- `type` → `secret`。
|
||||
- 与 Text 拼接(如 `bearer + api_key`)时**揭示**明文,供 HTTP Authorization。
|
||||
- 不得进入普通 episode / 错误信息明文(扩展作者责任;核心 Display 已遮掩)。
|
||||
|
||||
---
|
||||
|
||||
## 5. Runtime API
|
||||
|
||||
| API | 语义 |
|
||||
|-----|------|
|
||||
| `sys.meta` / `系统.元信息` | 入口模块已绑定 metadata(map) |
|
||||
| `sys.meta_get` / `系统.取元信息` | `key=` → 值或 `None` |
|
||||
| `marqdo run FILE --bind KEY=VALUE` | 可重复;写入 `arg` 并覆盖同名 metadata 键 |
|
||||
| `sys.env_get` | **保留**逃逸口;新代码优先 Metadata Binding |
|
||||
|
||||
---
|
||||
|
||||
## 6. 错误
|
||||
|
||||
| code | 何时 |
|
||||
|------|------|
|
||||
| `config.required_binding_missing` | `${ns.name!}` 且源缺失 |
|
||||
| `config.unknown_binding_ns` | 未知 namespace |
|
||||
| `config.bad_binding` | 表达式非法 / cast 失败 |
|
||||
|
||||
诊断尽量带 frontmatter 行号。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与扩展的分工
|
||||
|
||||
- **核心**:解析 Metadata、resolve Binding、暴露 `Module.metadata` / `sys.meta*`,并在入口把 metadata **提升为普通变量**。
|
||||
- **`ext/ai/llm`**:构造次序为 **显式实参 → 入口作用域同名变量 / `sys.meta_get` → `sys.env_get` 回退 → 默认**。
|
||||
|
||||
---
|
||||
|
||||
## 8. Phase 2 · Metadata scope lift(Accepted)
|
||||
|
||||
加载期绑定完成后,入口执行(`# main` 或唯一无参顶层对象)前,把 `Module.metadata` 的每个键注入 entry 环境,成为**普通变量**:
|
||||
|
||||
```yaml
|
||||
---
|
||||
model: ${env.ModelName ?? "gpt-4o-mini"}
|
||||
---
|
||||
```
|
||||
|
||||
```marqdo
|
||||
# main
|
||||
|
||||
> print text=`model`
|
||||
```
|
||||
|
||||
### 规则
|
||||
|
||||
1. 注入时机:进入入口函数之前。
|
||||
2. 冲突:形参 / 调用实参 **覆盖** 同名 metadata;程序内赋值亦然。metadata **不**覆盖已存在的绑定。
|
||||
3. `sys.meta` / `sys.meta_get` 仍可用(显式通道)。
|
||||
4. **拒绝** 正文 / 粗体 / 表 / 叙述中的 `${…}`(讨论稿 006 §17 否决)。普通语言也不在语句里 `${ENV}`。
|
||||
|
||||
### 仍推迟(P3+)
|
||||
|
||||
- `config` / `file` namespace
|
||||
- 嵌套 YAML map
|
||||
- 显式 `override:` 糖
|
||||
- 计入 `CORE_CONSTRUCTS`
|
||||
@@ -0,0 +1,302 @@
|
||||
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
|
||||
|
||||
> **2026-10-23 审阅裁决**:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认 `[键](集合)`。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提案 | 「`[]()` 不是两个部分两个含义,而是 `[描述性显示文字](实际执行的简短语句)`」 |
|
||||
| 方法 | 语料实测(索引 506 / 循环 44 / 方括号调用 0)+ 渲染器源码核对 + 设计史对照 |
|
||||
| 相邻 | [label-freshness-and-repair.md](label-freshness-and-repair.md)(后续:纯度落地 + 标签过期检测)· [function-as-naming-philosophy.md](function-as-naming-philosophy.md) · [collection-access-link.md](collection-access-link.md) · [call-syntax-from-marks.md](call-syntax-from-marks.md) |
|
||||
|
||||
> **决策**:用户选择**路线二(纯度)**——`()` 只装机器语句,取元搬进 `()`;
|
||||
> 标签可省略书写但**编译器必须报错**;循环写法不追求统一,`()` 内自洽即可。
|
||||
> 落地细节、普通取元形态,以及**标签过期检测(L1 引用一致性 / L2 指纹台账 / L3 LLM 复核)**
|
||||
> 见 [label-freshness-and-repair.md](label-freshness-and-repair.md)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 先把提案精确化
|
||||
|
||||
你的话可以解析出三种读法,差别很大,必须先分清:
|
||||
|
||||
| 读法 | `[]` 是什么 | `()` 是什么 | 语义是否变 |
|
||||
|------|------------|------------|-----------|
|
||||
| **A 标签化(你的原意,本文主评)** | 这个值的**人话名字**(纯描述) | 算出它的**机器语句** | **变** |
|
||||
| B 命名规范化 | 更好的键名(描述取出的东西) | 仍是集合 | 不变 |
|
||||
| C 内联命名 | 同时引入可引用的名字 | 算出它的语句 | 新增绑定 |
|
||||
|
||||
你说「`[]()` 函数也有了落脚地」「括号里面可以写长一些」,指向的是 **A**:
|
||||
**`[]` 只负责说人话,`()` 负责说准话;两者合起来才是一条完整语句。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么我们会下意识觉得这个写法"美"
|
||||
|
||||
你的直觉不是审美偏好,它对应三个**真实存在**的设计同构:
|
||||
|
||||
### 1.1 超链接:可见文本 ↔ 目标
|
||||
|
||||
`<a>` / `[可见文字](目标地址)` 的全部意义就是**给机器一个目标,给人类一个说法**。
|
||||
这是人类最早、最成功的"双面文本"。
|
||||
|
||||
### 1.2 文学编程的 chunk 名(Knuth)
|
||||
|
||||
Knuth 的 `<<chunk name>>` 就是"可执行片段的人话名字"。
|
||||
而**文学编程的整个出发点,正是你前面说的"代码要像文章"**——这个类比不是巧合。
|
||||
|
||||
### 1.3 Marqdo 自己已经有这个形态
|
||||
|
||||
```markdown
|
||||

|
||||
```
|
||||
|
||||
- `[]` 里是**指令/说明**(`marqdo-out`、可带 key)
|
||||
- `()` 里是**负载**(图片 URL / data URI)
|
||||
|
||||
**语言里已经有一个"方括号说意图、圆括号放负载"的地方。** 你的提案是把这个模式提升为通则。
|
||||
|
||||
### 1.4 一个经验证据:`[]` 在实践里本来就偏"给人看"
|
||||
|
||||
| 用法 | 数量 | 谁读 |
|
||||
|------|------|------|
|
||||
| `[键](集合)` 取元 | 506 | 机器 |
|
||||
| `- [项](集合)` 循环 | 44 | 机器 |
|
||||
| `[函数] 参数` 调用 | **0(可执行)** | — |
|
||||
| `[函数.名] 参数` 用法说明(`lib/*` 的 `Caller:` 行) | **189** | **人** |
|
||||
|
||||
**可执行的方括号调用从未被使用**;`[]` 在文档里出现最多的地方,恰恰是"给人看的用法示例"。
|
||||
这支持你的判断:`[]` 的天性更接近"描述",而不是"标识符"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 提案的三个真实收益(这部分我完全同意,而且比你说的更强)
|
||||
|
||||
### 2.1 收益一:两条规则变一条 —— 这是最大的价值
|
||||
|
||||
现在 `[x](y)` 是**两个部分、两个含义**(键 + 集合)。这导致前几轮那个死结:
|
||||
|
||||
> `[f](args)` 想当调用,但它和 `[k](c)` **同形**;按名字消歧会打断 2 个真实文件。
|
||||
|
||||
你的重读**直接解散了这个死结**:如果 `[x](y)` 一律是"标签 + 语句",
|
||||
那么**根本不存在"取元独占外形"这件事**——取元只是"`()` 恰好是个取值语句"的特例。
|
||||
|
||||
> 这是本提案最硬的结构收益:**它把一条只能容纳一种语义的外形,改造成能容纳任意语句的外形。**
|
||||
> 前几轮我们反复撞墙,是因为一直默认 `()` 只能是集合。你换了默认。
|
||||
|
||||
### 2.2 收益二:嵌套取元终于可读
|
||||
|
||||
现在是:
|
||||
|
||||
```markdown
|
||||
**第一 = [1]([苹果](货架))**
|
||||
```
|
||||
|
||||
两层嵌套,人类读者要在"货架→苹果→第1项"之间跳三次。
|
||||
|
||||
改成标签后:
|
||||
|
||||
```markdown
|
||||
**第一 = [货架里苹果的第一项](…机器语句…)**
|
||||
```
|
||||
|
||||
**人读标签,机器读嵌套。** 你点出的"嵌套难以描述"问题被真正解决了。
|
||||
|
||||
### 2.3 收益三:循环的"来源"可见 —— 但要说清它成立的范围
|
||||
|
||||
你的原话:`- [果](篮子)` 在 Markdown 渲染里看不出"果是从篮子拿的"。
|
||||
|
||||
**这一点需要精确化,因为它决定这块值不值得改**:
|
||||
|
||||
| 阅读场合 | `- [果](篮子)` 的表现 |
|
||||
|---------|---------------------|
|
||||
| 通用 Markdown(GitHub / VSCode 预览 / 编辑器) | 渲染成**名为「果」的链接指向「篮子」**——看不出是遍历,你的批评成立 |
|
||||
| **Marqdo 自己的 `view`** | 已渲染成带 `foreach` 徽章的 `loop-card`(`src/view/render.rs:1354`)——已经看得出 |
|
||||
|
||||
而取元在 `view` 里仍渲染成字面 `[键](集合)`(`render.rs:1502`),和 Markdown 链接同形。
|
||||
|
||||
**结论**:循环的"来源不可见"在**通用 Markdown 阅读器**里成立,而这恰好是大多数人的阅读场合
|
||||
(`marqdo view` 需要额外一步)。所以这条收益真实,但它其实在说另一件事:
|
||||
|
||||
> **Marqdo 的语义正确性,不应该依赖读者是否用了 `marqdo view`。**
|
||||
> 文档的第一载体是 `.mq.md` 本身,它在任何 Markdown 渲染器里都该读得通。
|
||||
|
||||
这比你原本的表述更有力——它把"渲染不好看"升级成"语义不可自解释"。
|
||||
|
||||
### 2.4 附带收益:标签是天然的锚点
|
||||
|
||||
你提到"点击之后跳转到对应位置"。这件事可行性很高,而且价值不小:
|
||||
|
||||
- `view` 已经保留每个语句的 span(`stmt_start`),标签可以让锚点从"行号"升级为"人话定位"
|
||||
- 报错信息可以说「在 **货架里苹果的第一项** 处出错」,而不是 `foo.mq.md:118`
|
||||
- 对 agent 尤其有用:模型用自然语言描述定位,比用行列号稳得多
|
||||
|
||||
---
|
||||
|
||||
## 3. 结构性弱点:`()` 要变成"语句",就必须再发明一套取元
|
||||
|
||||
这是本提案**代价最大、也最容易被忽略**的一点,必须摊开。
|
||||
|
||||
若 `[]` 只是标签,那 `(菜单)` 就只表示"整个菜单",**不再表示取成员**。要取成员,`()` 内需要新语法:
|
||||
|
||||
| 方案 | 形态 | 问题 |
|
||||
|------|------|------|
|
||||
| 点号 | `(菜单.拿铁)` | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形,容易混淆 |
|
||||
| 函数式 | `(取 菜单 拿铁)` | 需要新内建;与自然语言"取"字冲突多 |
|
||||
| 保留方括号 | `([拿铁](菜单))` | **嵌套方括号**,正是标签想消除的东西 |
|
||||
| 英文式 | `(get(菜单, 拿铁))` | 破坏中文叙述风格 |
|
||||
|
||||
**这就是核心张力**:
|
||||
|
||||
> 你想用 `()` 装"任意机器语句",来换取 `[]` 的纯粹描述性;
|
||||
> 但"取值"本身就需要一个语法,而这个语法要么是新的(增规则),
|
||||
> 要么就是旧的 `[k](c)`(则 `[]` 仍然兼任键,两义仍在)。
|
||||
|
||||
换句话说:**收益一(一条规则)能不能兑现,取决于你愿不愿意新增一条取元规则。**
|
||||
这不是否决理由,但必须算进成本——因为 Marqdo 的宪法是「标记即语法,少而精」,
|
||||
**用一条新规则换掉一条旧规则,不必然是净简化**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 描述漂移:我认为不能轻描淡写
|
||||
|
||||
你说「从语言设计上这好像又不是特别重要」。我不同意,理由三条:
|
||||
|
||||
### 4.1 它是"注释"的回归
|
||||
|
||||
Marqdo 用「叙述 + 标记」取代了注释:叙述在外面说意图,标记在里面说事实。
|
||||
而标签是**贴在执行体上的、可说谎的、必须短的文本**——这正是注释的老问题。
|
||||
Marqdo 花了很大力气让"文档即程序",标签会把"文档可能是假的"重新引进来。
|
||||
|
||||
### 4.2 一旦标签成为锚点,漂移就有操作后果
|
||||
|
||||
你在 §2.4 里期望标签用于跳转与定位。那么:
|
||||
|
||||
- 报错说「在 **安全读取** 处失败」,而实际代码是写入 → **错误信息也撒谎**
|
||||
- agent 用标签定位 bug → 被标签误导
|
||||
- 点击跳转跳到一段与描述不符的代码 → 读者信任崩塌
|
||||
|
||||
**标签的可信度必须与它的用途匹配。** 纯装饰可以漂移;一旦用于定位,就必须可校验。
|
||||
|
||||
### 4.3 安全面:标签是 agent 可读的攻击面
|
||||
|
||||
Marqdo 是 agent 框架。标签是**作者可控的自然语言**,而模型天然倾向相信自然语言。
|
||||
「标签写:只读校验;`()` 里:删除文件」这类不一致,从"文档瑕疵"升级为**误导 agent 的通道**。
|
||||
|
||||
**所以我建议把漂移当成一条可检查的不变量,而不是接受它的存在**:
|
||||
|
||||
| 缓释手段 | 说明 | 成本 |
|
||||
|---------|------|------|
|
||||
| ① 标签永不参与绑定 | 纯显示,不进符号表、不进作用域 | 零 |
|
||||
| ② 词重叠校验 | `check` 检查"标签里提到的名字"是否至少有一个出现在 `()` 里;全不重叠 → warn | 低 |
|
||||
| ③ trace 双输出 | 错误/trace 同时给标签与 `()` 原文 | 低 |
|
||||
| ④ 策略不看标签 | 沙箱/权限判定只读 `()` 的语义,绝不读标签 | 设计约束 |
|
||||
|
||||
其中 ② 最划算:它能抓住**最恶劣的一类漂移**(标签说 A,代码做 B),
|
||||
而对"标签写得更细"这种正常情况不误报。
|
||||
|
||||
---
|
||||
|
||||
## 5. 采用风险:可能重演 v0.3 废除的"仪式感"
|
||||
|
||||
v0.3 废除 `+ \`名\`` 形参表的原话理由是:**「仪式感强;函数头像另一套签名语言,与正文脱节」**。
|
||||
|
||||
强制每个访问都配一段人话标签,是**同一类仪式**。两种可预测的退化:
|
||||
|
||||
1. **凑数**:作者写 `[x](…)`、`[价格](…)`——标签退化成变量名,等于没有
|
||||
2. **噪音**:标签越写越长,正文被切碎,扫描性下降
|
||||
|
||||
这不是反对,而是提醒:**标签的价值只在"写得比键更有信息"时成立**。
|
||||
所以设计上应当考虑"**可以省略**",但一旦可省略,`[]` 就又变成可选键 → 歧义回归。
|
||||
|
||||
**这个矛盾必须在设计里正面解决,不能靠自觉。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 迁移面(实测)
|
||||
|
||||
| 受影响的写法 | 数量 | 文件 |
|
||||
|------------|------|------|
|
||||
| `[键](集合)` 取元 | **506 处** | 136 个文件 |
|
||||
| `- [项](集合)` 循环 | **44 处** | 24 个文件 |
|
||||
| `[函数] 参数` 可执行调用 | **0** | (189 处是 `lib/*` 的 `Caller:` 说明行,不执行) |
|
||||
|
||||
**危险点**:如果 `[]` 改为"纯标签",那 506 处取元的**含义会变**(`(菜单)` 变成整个菜单),
|
||||
而且是**同形换义**——同一段文本含义变了、还不报错。这是最坏的一类变更(参见 D9)。
|
||||
|
||||
所以若走这条路,**必须硬报错 + 版本门**:旧写法在新版本下直接报
|
||||
「`[键](集合)` 已改为 `[描述](语句)`,请写成 X」。
|
||||
另有一个好消息:**可执行方括号调用量为 0**,所以"把 `[f] args` 收编进新形式"是零迁移成本。
|
||||
|
||||
---
|
||||
|
||||
## 7. 两条落地路线
|
||||
|
||||
### 路线一:双层(推荐,兼容)
|
||||
|
||||
> **规则一句话:`[]` 永远是「这个值的人话名字」;`()` 永远是「怎么算出它」。**
|
||||
|
||||
- **长形(新增)**:`[描述](语句)` —— 承载调用、复杂取元、循环
|
||||
- **短形(现状保留)**:`[键](集合)`、`- [项](集合)` 定义为长形的**缩写**
|
||||
- 文档里显式承认:短形是历史妥协,`[]` 在短形中兼任键
|
||||
|
||||
| 优 | 劣 |
|
||||
|----|----|
|
||||
| 零迁移(506 处不动) | 短形的"两义"仍在(但被定义为可解释的缩写) |
|
||||
| 调用终于有落脚地(且 0 成本收编) | 规则仍是"一条 + 一个特例",不是纯一条 |
|
||||
| 嵌套可读、循环可写清来源 | |
|
||||
| 标签可以逐步引入,不强迫 | |
|
||||
|
||||
### 路线二:纯度(一条规则到底)
|
||||
|
||||
> `()` 只装机器语句,取元必须搬进 `()`。
|
||||
|
||||
必须同时决定:**`()` 内取元用什么形式**(§3 表),然后迁移 506 处 + 版本门。
|
||||
|
||||
| 优 | 劣 |
|
||||
|----|----|
|
||||
| 语义最纯,教学最简 | 需新增取元规则(可能不是净简化) |
|
||||
| `[]` 完全自由,可写很长的描述 | 506 处迁移,同形换义风险 |
|
||||
| 与 Markdown 链接语义完全一致 | 新取元语法与库路径/方法调用需要消歧设计 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 我的评定
|
||||
|
||||
**这是本系列里结构上最强的一个提案**,因为它第一次正面回答了"为什么 `[]()` 一直不肯就范":
|
||||
不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。
|
||||
|
||||
| 维度 | 评分 | 说明 |
|
||||
|------|------|------|
|
||||
| 哲学自洽性 | ★★★★★ | 与超链接、文学编程、`` 三处同构;且"文档自解释"优于"依赖 view 渲染" |
|
||||
| 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 |
|
||||
| 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" |
|
||||
| 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 |
|
||||
| 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 |
|
||||
| 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" |
|
||||
|
||||
**我的建议**:走 **路线一(双层)**,但把"长形"作为**推荐写法**、把文档里的示例全部改成长形,
|
||||
让短形成为"读得懂但不必写"的兼容层。这样:
|
||||
|
||||
- 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源)
|
||||
- 506 处零迁移
|
||||
- 调用终于有家,且成本为零
|
||||
- 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形
|
||||
|
||||
**一条具体建议**:先把 §4 的 ②(词重叠 warn)做出来。
|
||||
它让"标签"从"可能说谎的装饰"变成"**可被机器轻度核验的描述**"——
|
||||
这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。
|
||||
|
||||
---
|
||||
|
||||
## 9. 待你决策
|
||||
|
||||
1. **路线一(双层)还是路线二(纯度)?**
|
||||
2. 若路线二:`()` 内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。
|
||||
3. **标签可否省略?** 若可,省略时算"以 `()` 的文字为标签",还是要额外标记?
|
||||
4. **是否采纳 §4.2 的"词重叠校验"**?我认为它是这套设计能否安全的支点。
|
||||
5. 循环的新写法你倾向哪一种:
|
||||
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
|
||||
- `- [篮子里的果子](篮子 → 果)`
|
||||
- 保留 `- [果](篮子)` 作短形
|
||||
@@ -0,0 +1,54 @@
|
||||
# 方括号标记调用与前置修饰语
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 相关 | [call-arguments.md](call-arguments.md) · [collection-access-link.md](collection-access-link.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
无标记时,修饰语+函数名与函数名+实参都是词列,**无法消歧**。消歧标记必须来自 Marqdo 语法,**不能**依赖任一自然语言词法(「的」、形容词位置等)。
|
||||
|
||||
## 2. 形状
|
||||
|
||||
```text
|
||||
修饰语… [函数名] 实参…
|
||||
```
|
||||
|
||||
| 例子 | 含义 |
|
||||
|------|------|
|
||||
| `[问候] marqdo` | 调用 `问候`,位置实参 |
|
||||
| `礼貌 [问候] marqdo` | 另加 `礼貌=True` |
|
||||
| `正式 礼貌 [问候] marqdo` | `正式=True` `礼貌=True` |
|
||||
| `[结账摘要] 品名="拿铁" 杯数=2` | 仅具名实参 |
|
||||
| `[问候] ([格式化] `名字`)` | 嵌套:内层整段用 `()` |
|
||||
|
||||
旧形保留:`> 问候 …`、`**问候 …**`、`礼貌=True` 显式具名。
|
||||
|
||||
## 3. 与取元 / foreach
|
||||
|
||||
| 形状 | 语义 |
|
||||
|------|------|
|
||||
| `[X](Y)`(`]` 后**紧邻** `(`) | 取元 |
|
||||
| `[X]`(`]` 后不是 `(`) | 函数名标记 |
|
||||
| `- [X](Y)` | foreach |
|
||||
|
||||
## 4. 修饰语绑定
|
||||
|
||||
- `[` 前按空白切开;每段为标识(可 `` `名` ``)。
|
||||
- 降为 `Named(名, Bool(true))`,再与 `]` 后实参合并。
|
||||
- 与显式同名具名冲突 → 诊断。
|
||||
- **核心不剥语言词缀**;形参叫 `礼貌` 则写 `礼貌 [问候]`。
|
||||
|
||||
## 5. AST
|
||||
|
||||
`CallExpr.pre_modifiers: Vec<String>`;求值/字节码在绑参前展开。
|
||||
|
||||
## 6. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿并落地 |
|
||||
@@ -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,10 +1,12 @@
|
||||
# 调用实参:具名与位置
|
||||
|
||||
> **2026-10-23 适用范围校正**:本文保留早期调用尾部规则和历史示例,不是 v2.1 全部调用语法。当前已有 `f(args)` 及具名实参;默认紧邻 `](` 是描述包裹 payload,不再是下文所述的 Classic 取元。语法审阅与开发取舍见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),当前行为须由默认模式测试复核。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补) |
|
||||
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -16,20 +18,26 @@
|
||||
|------|------|------|
|
||||
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
|
||||
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
|
||||
| **方括号标记**(增补) | `礼貌 [问候] Marqdo` | `[函数名]` 消歧;`[` 前裸词 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md) |
|
||||
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。前置修饰语与显式同名具名冲突则报错。
|
||||
|
||||
---
|
||||
|
||||
## 2. 文法(调用尾部)
|
||||
|
||||
```
|
||||
call_tail ::= callee arg*
|
||||
call_tail ::= bracket_call | classic_call
|
||||
bracket_call ::= modifier* '[' callee ']' arg*
|
||||
classic_call ::= callee arg*
|
||||
arg ::= named | positional
|
||||
named ::= ident '=' value
|
||||
positional ::= value_token
|
||||
positional ::= value_token | '(' call_tail ')'
|
||||
modifier ::= ident # 展开为 ident=True;核心不剥语言词缀
|
||||
```
|
||||
|
||||
- `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记(见 [collection-access-link.md](collection-access-link.md))。
|
||||
- 嵌套调用:把内层整段放进 `()`,例如 `[问候] ([格式化] "x")`。
|
||||
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
|
||||
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
|
||||
- 实参值中 `` `变量` `` 后**紧跟** `[^…]` 时按**脚注取元**解析(可链式),而非文本:`> print text=苹果单价:`水果价格`[^苹果]`、`> print text=`订单`[^2][^品名]`。
|
||||
@@ -44,13 +52,14 @@ positional ::= value_token
|
||||
|
||||
## 3. 绑定算法
|
||||
|
||||
1. 收集具名 → 映射;冲突则报错。
|
||||
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
|
||||
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
|
||||
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
|
||||
1. 将前置修饰语展开为 `名=True` 具名(与显式具名冲突则报错)。
|
||||
2. 收集具名 → 映射;冲突则报错。
|
||||
3. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
|
||||
4. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
|
||||
5. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
|
||||
|
||||
---
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
|
||||
见 `tests/structure/positional-call.mq.md`、`tests/structure/bracket-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
|
||||
@@ -0,0 +1,289 @@
|
||||
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留显式标记和正文默认安全;性能数值是旧实验,不作为当前基准。持久跨文档接口优先具名参数,但不禁止位置参数;反引号声明与顺序改变可能是接口变化。当前调用与开发方向见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未改代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 前置纠正 | 用户否决上一轮的「叙述式动词」方案:**未标记词承载语义 = 破坏「叙述默认安全」** |
|
||||
| 方法 | 实测 6 组(含双后端性能对比、叙述顺序实验)+ 源码比对 |
|
||||
| 相邻 | [ambient-parameters-evaluation.md](ambient-parameters-evaluation.md) · [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 先接受纠正:错在哪
|
||||
|
||||
我上一轮提的 `对**n=31**执行**加一函数**`,靠**未标记的词「执行」**来触发调用。这确实违背底层原则:
|
||||
|
||||
> **叙述(未标记)= 默认安全,不执行;标记 = 才进编译器。**
|
||||
|
||||
一旦「执行」这种词能改变语义,那么:
|
||||
|
||||
- 作者改一句措辞("执行" → "运行" / "调用" / 换个说法)就可能改变程序行为;
|
||||
- 读者无法只看标记判断哪句是代码——必须逐字读叙述;
|
||||
- 与 D9 同类的静默风险:语义藏在叙述里。
|
||||
|
||||
**所以本文的设计约束是硬的**:
|
||||
|
||||
> **调用的每一个语义成分(被调者、每个实参、绑定关系)必须落在标记内;
|
||||
> 叙述词只能起连接与解释作用,永不改变语义。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 先盘清「标记字母表」
|
||||
|
||||
要设计调用,先得知道手上只有哪些字。
|
||||
|
||||
| 标记 | 现行语义 | 可否参与构成调用 |
|
||||
|------|---------|-----------------|
|
||||
| `**…**` | 执行段(赋值 / 调用 / 表达式) | ✅ 主载体 |
|
||||
| `*…*` | 返回 | ✅ 终止 |
|
||||
| `` `x` `` | 变量引用;首次出现即声明 | ✅ 槽名 |
|
||||
| `` `x` = `` | 叙述中的绑定 | ✅ 槽赋值 |
|
||||
| `**x = …**` | 赋值 | ✅ |
|
||||
| `> …`(行首) | 调用语句 | ✅ 已是调用标记 |
|
||||
| `[callee] args` | 方括号调用(消歧 / 前置修饰) | ✅ 已是调用标记 |
|
||||
| `[k](coll)` | 取元 | ⚠️ 与调用抢外形(已否) |
|
||||
| `- [x](coll)` | 遍历 | — |
|
||||
| `#` / `##` | 对象 / 函数声明 | — |
|
||||
| 表格 | 数据 / 契约 | — |
|
||||
| ```lang | 外联代码 | — |
|
||||
|
||||
**关键观察**:调用载体其实只有三种标记:`> 行`、`**…**`、`[callee]`。
|
||||
而 `[k](coll)` 这个外形已被取元独占(前几轮结论),不能用。
|
||||
|
||||
所以问题收敛为:
|
||||
|
||||
> **在 `**…**` 或 `> …` 内部,用哪些标记把「函数名」和「槽赋值」连起来?**
|
||||
|
||||
---
|
||||
|
||||
## 2. 可读性从哪来(这是设计的核心)
|
||||
|
||||
Marqdo 的叙述与代码是**两层**:叙述解释「为什么」,标记表达「做什么」。
|
||||
所以可读性不是靠把叙述词变成语法,而是靠:
|
||||
|
||||
1. **标记本身足够像自然记号**(`=`, `(`, `)`, `→` 都是跨语言的);
|
||||
2. **叙述与标记紧邻**,人一句一码地读;
|
||||
3. **同一件事只写一遍**(叙述不要复述代码)。
|
||||
|
||||
一句话:
|
||||
|
||||
> **叙述负责「说人话」,标记负责「说准话」;两者相邻即高可读,混在一起即两败。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 三个候选设计
|
||||
|
||||
### 设计 A — 括注具名调用:`**加一函数(n=31)**`
|
||||
|
||||
**读法**:`加一函数(n=31)` —— 与数学/几乎所有语言的函数调用同构。
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对 `n` 让 **n = n + 1**,返回 *n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 加一函数(n=31)**
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ 整段在 `**…**` 内 |
|
||||
| 无歧义 | ✅ 圆括号紧跟名字 = 调用;取元需方括号,不冲突 |
|
||||
| 与叙述结合 | ✅「把 n 设为 31 后**加一函数(n=31)**」 |
|
||||
| 多参数 | ✅ `f(a=1 b=2)` |
|
||||
| 编译器 | ✅ 具名 → 编译期映射到槽下标(见 §4) |
|
||||
| 实现成本 | ⚠️ 需改参数分词器:`)` 作终止符、逗号、嵌套(原型已验 554/0,但 `f(1 2)` 的末参数会吞 `)`) |
|
||||
|
||||
### 设计 B — 箭头槽赋值:`**n=31 → 加一函数**`
|
||||
|
||||
**读法**:「n 设为 31,交给加一函数」——最贴合汉语「先条件、后动作」语序。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**n=31 → 加一函数**
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ `→` 是符号标记,不是词 |
|
||||
| 可读性 | ✅✅ 流水线极顺:`**订单 → 计税 → 汇总**` |
|
||||
| 无歧义 | ⚠️ 需定义优先级;`**x = a=1 → f**` 有歧义,得靠括号 |
|
||||
| 求值结果 | ⚠️ 箭头式天然是语句式;要拿返回值还得包一层 |
|
||||
| 实现成本 | 中:新增运算符 + 优先级 + 与 `=`/`*…*` 的交互 |
|
||||
|
||||
### 设计 C — 现成空格式:`**加一函数 n=31**`(今天就可用)
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 完全由标记构成 | ✅ |
|
||||
| 实现成本 | **零**(实测 `**r = 加 1 2**` 已可跑) |
|
||||
| 可读性 | ⚠️ 参数边界靠空格;函数名含空格时不可用(D8) |
|
||||
| 编译器 | ✅ 具名同样可映射槽位 |
|
||||
|
||||
### 三者的取舍
|
||||
|
||||
| | A 括注 | B 箭头 | C 空格 |
|
||||
|---|---|---|---|
|
||||
| 像通用函数调用 | ✅✅ | ⚠️ | ✅ |
|
||||
| 中文语序自然 | ⚠️ | ✅✅ | ✅ |
|
||||
| 参数边界清晰 | ✅✅ | ✅ | ❌(空格切分) |
|
||||
| 链式组合 | ⚠️ | ✅✅ | ❌ |
|
||||
| 改动成本 | 中 | 中高 | **零** |
|
||||
| 与取元冲突 | 无 | 无 | 无 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 「不分实参形参」:编译器视角的真实收益
|
||||
|
||||
你问的是:不再区分实参/形参,是否意味着变量总在某个固定位置、能否减少 IO。
|
||||
这一节用实测回答,结论会有点意外。
|
||||
|
||||
### 4.1 现状:两条执行路径,差异 3.8 倍
|
||||
|
||||
| 路径 | 参数如何绑定 | 200k 次调用(1 个 int 实参) | 2000 次调用(500 元素列表) |
|
||||
|------|-------------|------------------------------|------------------------------|
|
||||
| **树遍历**(默认 `Backend::Tree`) | `Env { HashMap<String, Value> }`,每个实参 `k.clone()` + `v.clone()`(**深拷贝**) | 167 ms | 66 ms |
|
||||
| **字节码**(`--backend bytecode`) | `slots: Vec<Value>`,`pop` 后**按位置移动**入槽(**无克隆、无哈希**) | **44 ms** | **23 ms** |
|
||||
|
||||
源码依据:
|
||||
|
||||
```rust
|
||||
// src/bytecode/vm.rs Op::Call(fid, argc)
|
||||
let mut slots = vec![Value::None; callee.locals.len().max(argc).max(1)];
|
||||
for i in (0..argc).rev() {
|
||||
slots[i] = pop(&mut stack)?; // 移动,不克隆
|
||||
}
|
||||
frames.push(Frame { fn_idx: fid, ip: 0, slots, .. });
|
||||
```
|
||||
|
||||
### 4.2 三个结论
|
||||
|
||||
**结论一:「变量始终在某个位置」已经是字节码的现实。**
|
||||
形参按下标落槽,实参按位置移动入槽。这正是你说的模型——它已经存在。
|
||||
|
||||
**结论二:收益是真的,3.8×。**
|
||||
每次调用 0.83µs → 0.22µs;大实参 33µs → 11.5µs(省掉了深拷贝)。
|
||||
|
||||
**结论三(关键):这与「不分实参形参」的语法无关。**
|
||||
槽位化只需要「编译期知道形参顺序」,而形参顺序今天就有(v0.3 体推断给出确定顺序)。
|
||||
真正的瓶颈是**树遍历解释器用名字哈希 + 深拷贝**,以及**默认后端是 Tree**。
|
||||
|
||||
> **所以:不要用性能去论证语义变更。**
|
||||
> 想省 IO,把默认后端切到字节码、或把树遍历解释器槽位化即可——
|
||||
> 这是一条与语法正交的工程路径,收益确定、风险可控。
|
||||
> 而改语义(动态作用域)换来的性能,等于用正确性买速度。
|
||||
|
||||
### 4.3 但有一个真实的语法—性能耦合点:具名 vs 位置
|
||||
|
||||
这是本节最有价值的发现。**在「形参由体推断」的世界里,形参顺序 = 叙述里首次声明的顺序**
|
||||
(v0.3 §8.2:顺序按升参名字的首次声明事件出现序)。而叙述是可以自由改写的。
|
||||
|
||||
我用两个只差一句话序的文件做了实验:
|
||||
|
||||
```markdown
|
||||
## 减
|
||||
对于`a`和`b`。 ← 叙述顺序 a, b
|
||||
*`a` - `b`*
|
||||
```
|
||||
|
||||
```markdown
|
||||
## 减
|
||||
对于`b`和`a`。 ← 只把叙述顺序改成 b, a
|
||||
*`b` - `a`*
|
||||
```
|
||||
|
||||
| 调用写法 | 叙述 a 在前 | 叙述 b 在前 |
|
||||
|---------|------------|------------|
|
||||
| 具名 `a=10 b=3` | 7 | -7(语义随函数体改变,符合预期) |
|
||||
| **位置 `10 3`** | 7(a=10,b=3) | **7(b=10,a=3)** ← **绑定翻转了** |
|
||||
|
||||
**同一行调用代码 `> 减 10 3`,只因为作者改了前面的叙述语序,实际绑定就变了,而且不报错。**
|
||||
|
||||
这在「实参形参不分」的模型下是致命的:既然只有槽、槽序来自叙述,
|
||||
那么**位置传参等于把程序语义挂在叙述的可改写顺序上**。
|
||||
|
||||
**推论**:调用应当**以具名为准**,位置实参在体推断世界里是脆弱语法。
|
||||
这一点与编译器优化正好同向——具名调用让编译期把 `n` 静态映射到 `slots[0]`,
|
||||
既稳又快(不需要运行期哈希,也不需要猜顺序)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 我的设计建议
|
||||
|
||||
### 5.1 主形态:括注具名调用
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对 `n` 让 **n = n + 1**,返回 *n*
|
||||
|
||||
# main
|
||||
|
||||
**结果 = 加一函数(n=31)**
|
||||
```
|
||||
|
||||
理由:
|
||||
|
||||
1. **全部语义在标记内**(满足你的核心原则);
|
||||
2. 与通用函数调用同构,零学习成本;
|
||||
3. 具名 → 编译期静态映射槽位(对接字节码已有的 `slots[]`);
|
||||
4. 不碰取元 `[k](coll)`,不碰遍历 `- [x](c)`;
|
||||
5. 参数边界显式,顺带解决函数名含空格的调用难题(D8)。
|
||||
|
||||
### 5.2 位置实参:降级而非禁止
|
||||
|
||||
| 情形 | 建议 |
|
||||
|------|------|
|
||||
| 单参数 | 允许 `f(31)`(无歧义、写法自然) |
|
||||
| 多参数 | **要求具名**;位置仅保留给 `> f 1 2` 这种旧写法,并在 `check` 里 **warn** |
|
||||
| 理由 | §4.3:顺序来自叙述,可被改写而不报错 |
|
||||
|
||||
### 5.3 箭头(设计 B)作为可选补充
|
||||
|
||||
如果后续确实需要「流水线可读性」,再引入 `→`,定位为**语句式组合子**:
|
||||
|
||||
```markdown
|
||||
**订单 → 计税 → 汇总**
|
||||
```
|
||||
|
||||
但它是增量特性,不是本设计的前提。优势是链式,代价是优先级与返回值语义。
|
||||
|
||||
### 5.4 明确不做
|
||||
|
||||
| 方案 | 理由 |
|
||||
|------|------|
|
||||
| 未标记动词触发调用(上轮 L0) | 违背「叙述默认安全」 |
|
||||
| `[f](args)` | 与取元同形,已实测 2 个真实冲突文件 |
|
||||
| 动态作用域(参数从上下文推断) | 七条硬伤 + 130 个撞车形参名 |
|
||||
| 位置实参作为主流 | §4.3 叙述顺序会静默改变绑定 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 优劣总表
|
||||
|
||||
| 设计 | 标记完备 | 可读性 | 无歧义 | 编译器友好 | 改动 | 结论 |
|
||||
|------|---------|--------|--------|-----------|------|------|
|
||||
| **A 括注具名 `f(n=31)`** | ✅ | 高 | ✅ | ✅ 静态槽映射 | 中 | **推荐主形态** |
|
||||
| C 空格式 `f n=31` | ✅ | 中 | ✅ | ✅ | 零 | 今天可用,作兼容 |
|
||||
| B 箭头 `n=31 → f` | ✅ | 最高(流水线) | ⚠️ 优先级 | ✅ | 中高 | 可选增量 |
|
||||
| `[f](args)` | ✅ | 高 | ❌ 撞取元 | — | — | 不做 |
|
||||
| 未标记动词 | ❌ | 高 | ❌ | — | — | 不做 |
|
||||
| 动态作用域 | ✅ | 最高 | ❌ | ❌ 契约/指纹失效 | 高 | 不做 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 待你决策
|
||||
|
||||
1. **主形态选 A(括注具名)吗?** 若选,我按 B 档实现:`f(k=v)` 必通、`f(x)` 单参、多参数求具名。
|
||||
2. **位置实参**:多参时"要求具名 + 旧写法 warn"(§5.2),还是保持现状不动?
|
||||
3. **箭头**现在做还是留作后续?
|
||||
4. **顺带**:默认后端要不要切字节码(实测 3.8×,但需先验证 554 用例在 `--backend bytecode` 下全绿)?这条与语法无关,但可能是最划算的性能改进。
|
||||
|
||||
> 若你同意 A,我下一步会:改分词器(`)` 终止、逗号、嵌套)→ 补金样例 →
|
||||
> 跑双后端 554 回归 → 写变更文档。
|
||||
@@ -23,15 +23,20 @@ YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
# 别名(与早期草案一致)
|
||||
marqdo sync [PATH] -o OUT_DIR
|
||||
# 跳过 Engineering Knowledge 投影(仅旧式 catalog)
|
||||
marqdo catalog [PATH] -o OUT_DIR --no-knowledge
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
|
||||
| `--no-knowledge` | off | 不跑 EKC;默认在 catalog 成功后编译 L0–L4 / graph |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
Engineering Knowledge 命令见 [engineering-knowledge.md](engineering-knowledge.md)(`find` / `reuse` / `duplicate` / …)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物
|
||||
|
||||
@@ -0,0 +1,231 @@
|
||||
# 变更记录:D9 未闭合引号不再静默吞行
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(待合入) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 缺陷 | [D9](../research/qdagent-refactor-defects-2026-10.md) |
|
||||
| 设计 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md) §1 |
|
||||
| 改动文件 | `src/lex/mod.rs` · `src/parse/mod.rs` |
|
||||
| 影响面 | 行分类 + 语句解析(仅影响**畸形**输入) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 修了什么
|
||||
|
||||
**修复前**:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0。
|
||||
|
||||
```bash
|
||||
$ marqdo run u.mq.md
|
||||
$ echo $?
|
||||
0 # 没有输出、没有报错,s 这一行凭空消失
|
||||
```
|
||||
|
||||
**修复后**:解析期报错,退出码非 0。
|
||||
|
||||
```bash
|
||||
$ marqdo run u.mq.md
|
||||
error: u.mq.md: 7:1: unterminated string: this line starts bold code but
|
||||
contains an odd number of `"` -- close the string and the trailing `**`
|
||||
(line: **s = "abc)
|
||||
$ echo $?
|
||||
1
|
||||
```
|
||||
|
||||
(实测记录:报错回显中 `unterminated` 前的空格与行号格式由
|
||||
`Diagnostic` 的 span 渲染决定,与其它语法错一致。)
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因
|
||||
|
||||
问题**不在**解析器——`parse_quoted_string` 里的
|
||||
`bail!("unterminated {quote} string")` 一直都在,措辞也对。
|
||||
问题是这一行**根本到不了解析器**:
|
||||
|
||||
```
|
||||
"**s = \"abc"
|
||||
↓ classify_line
|
||||
↓ 首字符 '*' → is_marqdo_star_line?
|
||||
matching_bold_close() 扫描时遇到 '"' → in_str = true
|
||||
之后再也没有 '"' 来关闭 → 后续所有 '*' 都被当作字符串内容跳过
|
||||
→ 找不到收尾 '**' → 返回 None
|
||||
↓ is_marqdo_star_line = false
|
||||
↓ 落入 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
|
||||
↓ 成为「叙述」,解析器看不到
|
||||
```
|
||||
|
||||
**这是分类层的静默降级,不是解析层的缺陷。**
|
||||
|
||||
它比一般的解析错误更危险,因为:
|
||||
|
||||
| 场景 | 后果 |
|
||||
|------|------|
|
||||
| 手写漏一个引号 | 该行消失 → 别处报 `undefined variable`,排查方向被引偏 |
|
||||
| LLM 生成文档 | 少一段内容,但 `exit 0`、`check` 通过,**文档看起来完整却缺节** |
|
||||
| CI / 文档门禁 | 门禁试跑通过 → 残缺文档被沉淀入库 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 怎么改的
|
||||
|
||||
两层,缺一不可。
|
||||
|
||||
### 3.1 分类层:把畸形行留在 Code 类
|
||||
|
||||
`src/lex/mod.rs`
|
||||
|
||||
```rust
|
||||
if trimmed.starts_with("**") {
|
||||
if trimmed.trim() == "** **" {
|
||||
return true;
|
||||
}
|
||||
if matching_bold_close(trimmed).is_some() {
|
||||
return true;
|
||||
}
|
||||
// D9: 粗体起始但引号永不闭合 → 找不到收尾 `**`
|
||||
// 判为 Comment 会静默丢行;判为 Code 让解析器报错
|
||||
return has_unterminated_string(trimmed);
|
||||
}
|
||||
```
|
||||
|
||||
新增辅助函数:
|
||||
|
||||
```rust
|
||||
pub fn has_unterminated_string(line: &str) -> bool {
|
||||
// 统计未被 \ 转义的双引号个数,奇数即「开了没收」
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 解析层:给出精确报错
|
||||
|
||||
`src/parse/mod.rs`,紧跟既有粗体分支之后:
|
||||
|
||||
```rust
|
||||
// D9: 粗体起始但引号未闭合 —— 走到这里说明没有收尾 `**`,
|
||||
// 通用 "unrecognized statement" 会掩盖真正原因。
|
||||
if trimmed.starts_with("**") && has_unterminated_string(trimmed) {
|
||||
bail!("{span}: unterminated string: ... (line: {trimmed})");
|
||||
}
|
||||
```
|
||||
|
||||
没有这一层,用户会看到 `unrecognized statement: **s = "abc`——
|
||||
能定位到行,但不知道是引号没闭合。
|
||||
|
||||
---
|
||||
|
||||
## 4. 影响面(改前量化过)
|
||||
|
||||
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描,正确跳过 `\` 转义:
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| `.mq.md` 文件总数 | 845 |
|
||||
| 含 `**` 起始代码行的文件 | 620 |
|
||||
| **引号计数为奇数的代码行** | **0** |
|
||||
|
||||
**结论:不改变任何现有文件的解析结果。** 这条修复只作用于畸形输入。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
### 5.1 新增单元测试(`src/lex/mod.rs`,4 个)
|
||||
|
||||
| 测试 | 断言 |
|
||||
|------|------|
|
||||
| `unterminated_quote_inside_bold_is_code_not_comment` | 未闭合引号的粗体行 → `Code`(修复前失败,修复后通过) |
|
||||
| `balanced_quote_inside_bold_still_code` | 闭合引号仍是 `Code` |
|
||||
| `prose_with_quotes_stays_comment` | 叙述里提引号 → 仍是 `Comment` |
|
||||
| `prose_bold_emphasis_with_quote_stays_comment` | 叙述里含孤立引号 → 仍是 `Comment` |
|
||||
|
||||
**先写测试确认失败**(TDD):
|
||||
|
||||
```
|
||||
---- lex::tests::unterminated_quote_inside_bold_is_code_not_comment
|
||||
panicked: expected Code (so parser reports the error),
|
||||
got [ClassifiedLine { kind: Comment, text: "**s = \"abc" }]
|
||||
```
|
||||
|
||||
修复后 14/14 通过。
|
||||
|
||||
### 5.2 回归
|
||||
|
||||
| 范围 | 结果 |
|
||||
|------|------|
|
||||
| `cargo test --release --lib` | **237 passed, 0 failed**(基线 233 + 新增 4) |
|
||||
| `cargo test --release --test gold` | 276 passed, 8 failed |
|
||||
| ↑ 上述 8 个失败是否本次引入 | **否**。`git stash` 后基线同样 8 failed |
|
||||
| 8 个失败的原因 | 全部 `ext_web_*`,依赖 Go 插件 `libweb` 构建,本机环境不具备 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 已知边界
|
||||
|
||||
| 情形 | 行为 | 说明 |
|
||||
|------|------|------|
|
||||
| `**s = "a` + 下一行 `b"**` | 报错 | 字符串不跨行,符合现状 |
|
||||
| 单引号 `'...'` 未闭合 | **仍是旧行为**(静默) | 本次只处理双引号;单引号在 Marqdo 里使用频率低,留作后续 |
|
||||
| 叙述行含孤立 `"` | 不受影响 | 判定入口是 `starts_with("**")`,叙述行不进入 |
|
||||
|
||||
> 单引号的情况建议后续按同样思路处理,但需要单独评估
|
||||
> (单引号也用于英文撇号,误判风险高于双引号)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/lex/mod.rs` | `is_marqdo_star_line` 增加未闭合引号分支;新增 `pub fn has_unterminated_string`;新增 4 个测试 |
|
||||
| `src/parse/mod.rs` | import 辅助函数;`parse_simple_stmt` 增加精确报错分支 |
|
||||
| `doc/design/parser-diagnostics-d8-d9.md` | 新增(设计依据 + 影响面 + 方案评判) |
|
||||
| `doc/design/spaced-function-names-d8.md` | 新增(D8 方案评估,待审阅) |
|
||||
| `doc/design/change-d9-unterminated-string.md` | 本文件 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 附:本机测试环境(2026-10-22 装好)
|
||||
|
||||
修复过程中发现本机缺两样东西,导致基线本来就有失败。补环境后全量测试 **554 passed / 0 failed**。
|
||||
|
||||
### 8.1 两个非直觉约束
|
||||
|
||||
| 约束 | 表现 | 解法 |
|
||||
|------|------|------|
|
||||
| `$HOME` 不可写 | zig 报 `error: AccessDenied`(全局缓存无处可写) | `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` 显式指向工作区 |
|
||||
| **`/tmp` 是 noexec tmpfs** | Go 链接报 `running gcc failed: signal: aborted`;zig 链接报 `AccessDenied` | `TMPDIR` 指向可写**且可执行**目录 |
|
||||
|
||||
第二条最隐蔽:`/tmp` 挂载为 `rw,nosuid,nodev,noexec`,构建工具会把产物写到那里再执行,
|
||||
于是「文件能写、却执行不了」。错误信息完全指向不了这一点。
|
||||
|
||||
### 8.2 Go 插件(`libweb.so`)
|
||||
|
||||
`gold` 测试里 8 个 `ext_web_*` 失败全因缺 `libweb.so`:
|
||||
|
||||
```bash
|
||||
source scripts/dev-env.sh # 提供 go 1.25 + gcc shim(zig) + TMPDIR
|
||||
./scripts/build-web-plugin.sh # 产出 plugins/web/build/libweb.so
|
||||
cp plugins/web/build/libweb.so target/release/ target/debug/
|
||||
```
|
||||
|
||||
Go 的 cgo 要 `gcc`,本机没有,用 zig cc 充当:
|
||||
`/workspace/qdagent/.tools/zigcc/bin/gcc`(会过滤 Go 传入的 `-Qunused-arguments`,
|
||||
该参数会让 zig 驱动 abort)。
|
||||
|
||||
### 8.3 一键复用
|
||||
|
||||
新增 `scripts/dev-env.sh`,`source` 后即具备完整工具链:
|
||||
|
||||
```
|
||||
marqdo dev-env: rust=1.81.0 go=go1.25.0 python=3.12.15 cc=zig-glibc2.36
|
||||
```
|
||||
|
||||
### 8.4 环境修复前后的测试对比
|
||||
|
||||
| 阶段 | lib 测试 | gold 测试 |
|
||||
|------|----------|-----------|
|
||||
| 无 python3 | 231 / 2 failed | — |
|
||||
| 加 python3 | 233 / 0 failed | 276 / 8 failed |
|
||||
| 加 go + libweb | — | **284 / 0 failed** |
|
||||
| **全量** | | **554 passed / 0 failed** |
|
||||
@@ -0,0 +1,99 @@
|
||||
# 变更记录:HostFn 五张表合一(`HOST_FN_TABLE` 单一来源)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 4 项 |
|
||||
| 改动 | `src/host/dispatch.rs`:**−404 行**(639 删 / 235 增) |
|
||||
| 行为 | **零变化**(203 项逐字节一致) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原来有五张并行表
|
||||
|
||||
202 个宿主函数的元数据分散在五个手写 match 里:
|
||||
|
||||
| 表 | 行数 | 作用 |
|
||||
|----|------|------|
|
||||
| `from_u16` | ~215 | id → 变体 |
|
||||
| `from_name` | ~215 | 名字/别名 → 变体(**保留**,见 §4) |
|
||||
| `name` | ~210 | 变体 → 规范名 |
|
||||
| `required_params` | ~145 | 变体 → 必填参数 |
|
||||
| `optional_params` | ~90 | 变体 → 可选参数 |
|
||||
|
||||
五张表必须同步维护,而 [code-volume-audit.md](code-volume-audit.md) 记录过
|
||||
`from_name` 接受 `http_get` 而 `name()` 只输出 `host_http_get` 的一类漂移。
|
||||
|
||||
## 2. 现在只有一张
|
||||
|
||||
```rust
|
||||
pub struct HostFnDef {
|
||||
pub id: u16,
|
||||
pub f: HostFn,
|
||||
pub name: &'static str,
|
||||
pub required: &'static [&'static str],
|
||||
pub optional: &'static [&'static str],
|
||||
}
|
||||
|
||||
pub const HOST_FN_TABLE: &[HostFnDef] = &[
|
||||
HostFnDef { id: 1, f: HostFn::ReadText, name: "host_read_text",
|
||||
required: &["path"], optional: &[] },
|
||||
…
|
||||
];
|
||||
```
|
||||
|
||||
四个函数改为查表(`from_u16` 按 id 查,其余按判别值查);
|
||||
`call_host` 保留它那 202 个一行臂——**分派逻辑不动**,只把元数据集中。
|
||||
|
||||
## 3. 怎么保证没改坏
|
||||
|
||||
迁移采用**快照比对**:
|
||||
|
||||
1. 先在旧实现上导出全部 203 项的 `(id, name, required, optional)` 到 TSV
|
||||
2. 合并成表后,用同一段代码再导出一份
|
||||
3. `diff` 两份文件 → **完全一致**
|
||||
|
||||
```
|
||||
$ diff /tmp/host_fns_baseline.tsv /tmp/host_fns_new.tsv && echo IDENTICAL
|
||||
IDENTICAL
|
||||
```
|
||||
|
||||
快照测试是一次性的,比对通过后删除;长期守护交给四个不变量测试:
|
||||
|
||||
| 测试 | 内容 |
|
||||
|------|------|
|
||||
| `every_assigned_id_round_trips` | 每个已分配 id → `as_u16()` 往返(id 空间稀疏是**退役 id**,不复用) |
|
||||
| `every_id_has_a_name_that_round_trips` | `name()` → `from_name()` 回到同一变体 |
|
||||
| `names_are_unique` | 规范名唯一 |
|
||||
| `required_and_optional_params_are_disjoint` | 必填/可选不重叠、`all_params` 无重复 |
|
||||
|
||||
## 4. 为什么 `from_name` 没有并进表
|
||||
|
||||
它是**别名注册表**(`http_get`、`get`、中文别名…),语义与"规范名"不同;
|
||||
并进表会让 `name()` 与 `from_name` 又变成一对映射。
|
||||
现在它保留原样,由上面的往返测试保证不与表漂移。
|
||||
|
||||
## 5. 收益
|
||||
|
||||
| 指标 | 前 | 后 |
|
||||
|------|----|----|
|
||||
| `dispatch.rs` | 2,052 行 | **1,648 行** |
|
||||
| `src/` 合计 | 53,040 | **52,668** |
|
||||
| 需同步维护的表 | 5 | **1** |
|
||||
|
||||
## 6. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `cargo build --release` | 零警告 |
|
||||
| `cargo test --release` | **609 passed / 0 failed** |
|
||||
| 快照 diff | 203 项逐字节一致 |
|
||||
| 四个不变量测试 | 全绿 |
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/host/dispatch.rs` | 新增 `HostFnDef` / `HOST_FN_TABLE`(203 项);`from_u16` / `name` / `required_params` / `optional_params` 改为查表;删除对应四个 match |
|
||||
| `doc/design/change-hostfn-table.md` | 本文件 |
|
||||
@@ -0,0 +1,134 @@
|
||||
# 变更记录:M1 `()` 内调用语法(`)` 终止 / 逗号 / 嵌套 / 空格 callee)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M1([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/parse/expr.rs` |
|
||||
| 影响面 | **共享参数分词器**(所有调用都会经过) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 修了什么
|
||||
|
||||
四件事,一句概括:**`(…)` 现在是一等调用外形**。
|
||||
|
||||
| # | 前 | 后 |
|
||||
|---|----|----|
|
||||
| 1 | `加(31)` 报 `unknown function 加(31` | ✅ 调用,返回 32 |
|
||||
| 2 | 末个位置实参会吞掉 `)` | `)` 是**参数终止符** |
|
||||
| 3 | 只支持空白分隔 | 支持 `,` / `,` 可选分隔 |
|
||||
| 4 | 嵌套 `加(加(1 2), 3)` 不可用 | ✅ 递归解析 |
|
||||
| 5 | `加一 号(31)` 不可用(D8) | ✅ **callee 可含空格** |
|
||||
|
||||
实测(1.5.2 本地构建,tree 与 bytecode 双后端结果一致):
|
||||
|
||||
```
|
||||
空格参=3 加(1 2)
|
||||
逗号=3 加(1, 2)
|
||||
嵌套=13 加(加(1 2), 10)
|
||||
带空格callee=32 加一 号(31) ← 缺陷 D8 的结构性解法
|
||||
库函数=x txt.str_trim(" x ")
|
||||
具名=3 加(a=1, b=2)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 实现要点
|
||||
|
||||
### 2.1 参数扫描:深度感知 + `)` 终止
|
||||
|
||||
`split_first_token` 与 `find_next_arg_boundary` 改为**通用扫描器**:
|
||||
|
||||
- 跟踪 `()` `[]` `{}` 嵌套、`"…"` 字符串、`` `…` `` 反引号
|
||||
- **顶层** `)` / 空白(以及括号形里的 `,`)终止当前 token,且**不吞掉终止符**
|
||||
- 字符串内的逗号不受影响(`拼接("a,b", "c")` 仍是 2 个参数)
|
||||
|
||||
### 2.2 `try_paren_call`:callee = 第一个 `(` 之前的全部文本
|
||||
|
||||
```rust
|
||||
let Some(open) = s.find('(') else { return Ok(None) };
|
||||
let callee_tok = s[..open].trim(); // 允许空格
|
||||
```
|
||||
|
||||
**安全护栏**(否则会误判):
|
||||
|
||||
| callee 里出现 | 判定 |
|
||||
|--------------|------|
|
||||
| `=` | 不是括号调用(那是 `text=a(b)` 具名实参) |
|
||||
| `[` `]` `(` `)` `"` `'` | 不是括号调用(那是 `trim [stdout](…)` 方括号实参) |
|
||||
| 以 `[` `]` `"` `'` 开头 | 不是括号调用 |
|
||||
| 反引号 | **允许**(保留 `` `obj`.方法(…) `` 接收者写法) |
|
||||
|
||||
### 2.3 表达式级 postfix 调用
|
||||
|
||||
`parse_primary` 的裸词分支:**紧跟** `(` 时按调用解析。
|
||||
|
||||
```rust
|
||||
if self.allow_paren_call && self.rest().starts_with('(') { … }
|
||||
```
|
||||
|
||||
要求"紧跟"(不隔空格),使 `加 (1)` 仍是原来的"文本 + 括号"行为。
|
||||
|
||||
### 2.4 方括号形也允许空格 callee
|
||||
|
||||
`is_bracket_callee_inner` 不再拒绝空白:`[加一 号] 31` 可用。
|
||||
(仓库内可执行的方括号调用用量为 0,风险极低。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键设计决策:括号形 vs 空格形的参数**值**语义不同
|
||||
|
||||
这是本里程碑唯一有争议的点,必须写清。
|
||||
|
||||
| 形态 | 参数值 | 例子 |
|
||||
|------|--------|------|
|
||||
| **括号形** `f(…)` | 表达式(**允许** `name(args)` 调用) | `加(加(1 2), 3)` |
|
||||
| **空格形** `> f k=v` | 文本(**不允许**裸 `name(args)` 变成调用) | `source=print(2+2)` 仍是文本 |
|
||||
|
||||
**为什么必须区分**:`source=print(2+2)` 在 Marqdo 里历来是**文本**(未加引号的实参按文本处理)。
|
||||
若不区分,它会变成对 `print` 的调用,`foreign.run_lang` 直接报 `source must be text`
|
||||
—— 这正是本次回归测试抓到的 3 个失败。
|
||||
|
||||
实现:`Parser` 增加 `allow_paren_call` 字段;`parse_call_arg_value_mode(input, prefer_var, allow_call)`
|
||||
统一两种值解析(`allow_call=false` 即旧行为)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元 | 新增 11 个(单参/多参/逗号/具名/空格 callee/零参/库路径/嵌套/引号内逗号/旧写法不回归/方括号形) | ✅ |
|
||||
| 全量 | `cargo test --release` | **565 passed / 0 failed**(基线 554 + 11) |
|
||||
| 双后端 | tree 与 `--backend bytecode` 跑同一文档 | 输出一致 |
|
||||
| 端到端 | `marqdo run` 六个用例 | 输出符合预期 |
|
||||
|
||||
**TDD 过程**:先写 11 个测试 → 10 个失败(红灯确认)→ 实现 → 全绿。
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带移除的死代码
|
||||
|
||||
`end_of_quoted_string`:新扫描器取代其唯一用途后变成 `never used`,删除(编译器警告清零)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界(本里程碑不做)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 逗号仅在括号形生效 | 空格形 `text=a,b` 的逗号仍是文本(兼容) |
|
||||
| `加 (1)`(空格后跟括号) | 不视为调用,保持旧行为 |
|
||||
| 遮蔽语法 `[描述](…)` | M2 才引入,本里程碑不解析 |
|
||||
| 位置实参顺序脆弱性 | 与叙述顺序绑定,M7/M8 再处理(诊断) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/parse/expr.rs` | 参数扫描器重写(`)`/逗号/嵌套);新增 `try_paren_call` + `split_callee` 抽取;表达式级 postfix 调用;`Parser.allow_paren_call`;`parse_call_arg_value_mode` 统一两种值语义;方括号 callee 允许空格;删除 `end_of_quoted_string` |
|
||||
| `doc/design/change-m1-paren-call.md` | 本文件 |
|
||||
@@ -0,0 +1,73 @@
|
||||
# 变更记录:M10 工程化落点(README + agent 提示词)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M10([occlusion-description-and-search.md](occlusion-description-and-search.md) §5) |
|
||||
| 改动文件 | `ext/ai/agent.mq.md`(README 一节已在文档阶段落地) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 改了什么
|
||||
|
||||
把「接不了就申报,别假装完成」写进 **agent 的默认提示词**,两处:
|
||||
|
||||
### 1.1 `how-to-act` 协议段(每轮都会带)
|
||||
|
||||
```
|
||||
Call ONLY names listed under --- tools --- (whitelist). …
|
||||
If a capability cannot truly be wired, do NOT fake it silently and never claim it works:
|
||||
write an occlusion with an explicit status, e.g. [按关键词检索,接口未接,待开发](None).
|
||||
Stubs must run without error and must state their return value (None is acceptable).
|
||||
Before finishing, check your own declarations with labels.search.
|
||||
Tools run via Marqdo subtask (spawn fn / wait).
|
||||
```
|
||||
|
||||
### 1.2 默认 standing(`p`)
|
||||
|
||||
```
|
||||
You are a Marqdo agent. Code is documentation: … not a hidden system prompt.
|
||||
When you cannot wire a capability, declare it in the description (待开发 / 模拟)
|
||||
instead of faking success.
|
||||
```
|
||||
|
||||
**为什么这两处**:standing 定基调(每次对话开头),how-to-act 定动作(每轮)。
|
||||
只写 standing 容易被长上下文冲淡;只写 how-to-act 又缺"为什么要申报"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计要点
|
||||
|
||||
| 要点 | 说明 |
|
||||
|------|------|
|
||||
| 给**范式**而不是规则 | 直接给出可抄的 `[按关键词检索,接口未接,待开发](None)`,模型不必发明措辞 |
|
||||
| 给**返回值**要求 | "必须写清返回什么(None 也行)"——对应 `label.empty_payload` 的 warning |
|
||||
| 给**自查**动作 | `labels.search` 让模型收尾时能自己盘点,而不是靠人提醒 |
|
||||
| 用**英文**写 | 与既有 standing / 协议段语言一致(模型对英文指令更稳) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `marqdo check ext/ai/agent.mq.md`(occlusion 模式) | `contract check OK` |
|
||||
| 提示词文本落入模块 | `grep` 命中 2 处(standing 与 how-to-act 各 1) |
|
||||
| 全量回归 | 587 passed / 0 failed(与 M9 相同,本改动不动逻辑) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界
|
||||
|
||||
- 提示词是**建议**,不是门禁;违反不会被拒绝,但会在描述/诊断里暴露。
|
||||
- `labels.search` 需要 M7 翻转默认后对 classic 文档才有意义;提示词先就位。
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `ext/ai/agent.mq.md` | how-to-act 协议段与默认 standing 各追加申报约定 |
|
||||
| `doc/design/change-m10-engineering-habits.md` | 本文件 |
|
||||
@@ -0,0 +1,126 @@
|
||||
# 变更记录:M2 遮蔽语法 `[描述](实现)`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(模式开关默认仍是 classic) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M2([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/ast.rs` · `src/parse/expr.rs` · `src/parse/mod.rs` · `src/interp.rs` · `src/bytecode/compile.rs` · `src/view/render.rs` · `src/main.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 语法(新节点)+ 两个后端 + 渲染 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增语法
|
||||
|
||||
```markdown
|
||||
[描述](实现)
|
||||
```
|
||||
|
||||
- `[]` = **描述**(自由文本,**永不执行**;仅用于检索、统计、过期校验)
|
||||
- `()` = **实现**(唯一执行体)
|
||||
- `[]` 为空 → `label.missing`(error,M2.5 落诊断)
|
||||
- `()` 为空 → 值为 `None`(空载荷桩,M2.5 落 warning)
|
||||
|
||||
实测(`MARQDO_MARKUP=occlusion`):
|
||||
|
||||
```
|
||||
a=2 [加一之后的值](1 + 1)
|
||||
b=42 [外层]([内层](40 + 2)) ← 嵌套遮蔽
|
||||
c=True [某某功能开发中]() ← 空载荷 → None
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键决策:**模式开关,暂不切换语义**
|
||||
|
||||
`[键](集合)` 与 `[描述](实现)` **外形完全相同**。若 M2 直接改语义,全仓 506 处取元
|
||||
会**静默变成"遮蔽整个集合"** —— 这正是文档里点名的最坏一类变更(同形换义)。
|
||||
|
||||
因此 M2 只**实现能力**,不动默认:
|
||||
|
||||
| 模式 | `MARQDO_MARKUP` | `[a](b)` 的语义 |
|
||||
|------|-----------------|-----------------|
|
||||
| `Classic`(默认) | 未设 / 其他值 | 取元(今天的行为) |
|
||||
| `Occlusion`(纯度) | `occlusion` / `purity` / `1` / `on` | 遮蔽(描述 + 实现) |
|
||||
|
||||
**M7 才迁移语料并翻转默认**,同时对旧形报 `syntax.legacy_index` 硬错误。
|
||||
这样 M2 可独立验证,且不会出现"半迁移的静默错义"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现要点
|
||||
|
||||
### 3.1 AST
|
||||
|
||||
```rust
|
||||
Occluded {
|
||||
label: String,
|
||||
payload: Option<Box<Expr>>, // None = 空载荷桩(值 None)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 解析
|
||||
|
||||
- `Parser` 增加 `markup: Markup` 字段;`parse_expr_markup(input, prefer_var, markup)`
|
||||
供测试/迁移显式指定;CLI 通过 `MARQDO_MARKUP` 设置进程默认。
|
||||
- 描述扫描:读到 `]` 为止;`\]` 转义字面方括号;跨行即报未闭合。
|
||||
- 之后必须紧跟 `(`;`()` 内若无内容 → `payload: None`;否则 `parse_or()` 后要求 `)`。
|
||||
- 嵌套自然成立:payload 是完整表达式,可再含遮蔽。
|
||||
|
||||
### 3.3 求值(两个后端一致)
|
||||
|
||||
| 位置 | 处理 |
|
||||
|------|------|
|
||||
| `interp.rs` `eval_expr` | 有 payload → 求值 payload;无 → `Value::None` |
|
||||
| `bytecode/compile.rs` | 有 payload → 编译 payload;无 → `Op::None_` |
|
||||
| `collect_decl_reads` / `collect_reads_expr` | 递归 payload(描述不产生读引用) |
|
||||
| `view/render.rs` `expr_prec` | 渲染成 `[描述](payload)` / `[描述]()` |
|
||||
|
||||
**描述永不参与求值**——守住铁律 1。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(8) | 值直通 / 空载荷 / 描述含空格与标点 / `\]` 转义 / 嵌套 / classic 仍是取元 / 缺括号报错 | ✅ |
|
||||
| 集成(3) | `MARQDO_MARKUP=occlusion` 跑通三个值;不设该变量时旧取元不变;occlusion 模式下旧形**不再**是取元 | ✅ |
|
||||
| 全量 | `cargo test --release` | **575 passed / 0 failed**(M1 后 565 + 10) |
|
||||
| 双后端 | tree 与 `--backend bytecode` | 一致 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 顺带重构
|
||||
|
||||
- `Markup` 枚举与 `parse_expr_markup` 抽为显式参数,避免测试依赖全局可变状态
|
||||
(全局只由 CLI 入口设置一次)。
|
||||
- `parse::expr` 由 `mod` 改 `pub mod`,供 `main.rs` 设置模式。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 描述不参与作用域/类型 | 写什么都不影响执行 |
|
||||
| 描述里的 `` `实体` `` | M4 才做引用一致性校验 |
|
||||
| 空载荷 warning | M2.5 落诊断(本提交只有语义) |
|
||||
| 跨行描述 | 不支持(v1) |
|
||||
| 旧取元 | 仍可用;M7 迁移后改为硬错误 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/ast.rs` | 新增 `Expr::Occluded { label, payload }` |
|
||||
| `src/parse/expr.rs` | `Markup` 枚举 + 全局默认 + `parse_expr_markup` + `parse_occluded` + `Parser.markup` |
|
||||
| `src/parse/mod.rs` | `pub mod expr`;`collect_reads_expr` 递归 payload |
|
||||
| `src/interp.rs` | 求值 + 读引用收集 |
|
||||
| `src/bytecode/compile.rs` | 编译为 payload(或 `None_`) |
|
||||
| `src/view/render.rs` | 表面渲染 + 输入提示收集 |
|
||||
| `src/main.rs` | `MARQDO_MARKUP` 环境变量 |
|
||||
| `tests/occlusion/value.mq.md` · `tests/occlusion/classic-index.mq.md` · `tests/occlusion.rs` | 新增集成测试 |
|
||||
| `doc/design/change-m2-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,91 @@
|
||||
# 变更记录:M2.5 遮蔽标签诊断(`label.missing` / `label.empty_payload`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M2.5([occlusion-syntax.md](occlusion-syntax.md) §13,诊断规范 §10) |
|
||||
| 改动文件 | **新增 `src/label.rs`** · `src/check.rs` · `src/lib.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | `marqdo check`(新增两类诊断) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 两条诊断
|
||||
|
||||
| code | 级别 | 触发 | 文案要点 |
|
||||
|------|------|------|---------|
|
||||
| `label.missing` | **error** | `[](实现)` 描述为空 | 「给这段实现写一句人话,或改用不带遮蔽的写法」 |
|
||||
| `label.empty_payload` | **warning** | `[描述]()` 载荷为空 | 「这里没有可执行内容」,建议写 `(None)` 或补实现 |
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
$ MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md
|
||||
empty-label.mq.md:3:1: 遮蔽缺少描述:`[](…)` —— 给这段实现写一句人话,或改用不带遮蔽的写法
|
||||
contract check: 1 条诊断(1 error) # exit 1
|
||||
|
||||
$ MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md
|
||||
empty-payload.mq.md:3:1: 空载荷遮蔽:`[某某功能开发中]()` —— 这里没有可执行内容
|
||||
contract check: 1 条诊断(0 error) # exit 0(warning 不影响退出码)
|
||||
```
|
||||
|
||||
JSON 出口(自动继承既有 schema,含 `doc_quote`):
|
||||
|
||||
```json
|
||||
{"code":"label.empty_payload","severity":"warning","span":{"line":3,"col":1},
|
||||
"doc_quote":"某某功能开发中","message":"空载荷遮蔽:…","suggestion":"写清桩的返回值(如 `(None)` 或 `(0)`)…"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 实现
|
||||
|
||||
### 2.1 新增 `src/label.rs`
|
||||
|
||||
- `OcclusionSite { label, has_payload, line, unit }`
|
||||
- `collect(module)`:遍历函数体与嵌套语句/表达式,收集所有遮蔽点
|
||||
(描述只读,**不产生任何读引用**)
|
||||
- `check(module, path)`:产出上面两条诊断
|
||||
|
||||
### 2.2 接入 `check_module`
|
||||
|
||||
```rust
|
||||
walk(module, &module.functions, path, &known, &mut out);
|
||||
out.extend(crate::label::check(module, path)); // M2.5
|
||||
```
|
||||
|
||||
设计上把"标签诊断"独立成模块,M4(引用一致性)与 M9(检索)都往这里加,
|
||||
`check` 只做一行汇总。
|
||||
|
||||
---
|
||||
|
||||
## 3. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3 新) | 空描述 → exit 1 + 文案;空载荷 → exit 0 + 文案;干净样例 → 无诊断 | ✅ |
|
||||
| 全量 | `cargo test --release` | **578 passed / 0 failed**(M2 后 575 + 3) |
|
||||
|
||||
反向验证:三条断言分别验证"会响"与"不会误响"(干净样例必须无输出)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 描述内容不校验 | 写什么都可以;M4 才校验反引号引用 |
|
||||
| 空载荷仅在 occlusion 模式可能出现 | classic 模式下 `()` 空是语法错 |
|
||||
| warning 不影响退出码 | 与既有 `Severity` 语义一致 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | **新增**:遮蔽点收集 + 两类诊断 |
|
||||
| `src/lib.rs` | `pub mod label;` |
|
||||
| `src/check.rs` | `check_module` 追加 label 诊断 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/{empty-label,empty-payload,clean}.mq.md` | 新增 3 个集成测试与样例 |
|
||||
| `doc/design/change-m25-label-diagnostics.md` | 本文件 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# 变更记录:M3 `access` 与遮蔽循环
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M3([occlusion-syntax.md](occlusion-syntax.md) §4 / §13) |
|
||||
| 改动文件 | `src/interp.rs` · `src/ast.rs` · `src/parse/mod.rs` · `src/bytecode/compile.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 新增内建 `access`;`Stmt::ForEach` 增可选标签 |
|
||||
|
||||
---
|
||||
|
||||
## 1. `access(集合, 键)`
|
||||
|
||||
旧取元 `[键](集合)` 的语义是**多态**的:Map 按键、List 按 1-based 下标、缺键报错。
|
||||
纯度路线把取元移进 `()`,因此需要一个与之**完全等价**的调用形式:
|
||||
|
||||
```markdown
|
||||
**a = [取表项](access(`表`, "键"))**
|
||||
**b = [取列表第二项](access(`列`, 2))**
|
||||
```
|
||||
|
||||
- 别名:`取` / `取值` / `access`
|
||||
- 缺键 → `missing map key …`(**与旧取元同一错误**,不静默返回 None)
|
||||
- 用途:M7 迁移把 `[k](c)` 机械改写成 `access(c, k)`,语义零漂移
|
||||
|
||||
实现:`interp.rs` 的 special-callee 分派里直接复用 `builtin_footnote_get`,
|
||||
**不新增平行实现**(避免两套索引语义)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 遮蔽循环
|
||||
|
||||
```markdown
|
||||
- [篮子里的每个果子](遍历 `列` 为 `果`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
- 只在 occlusion 模式识别(classic 模式下 `- [x](c)` 仍是旧 foreach)
|
||||
- 接受 `遍历`/`for` 与 `为`/`as`/`in`
|
||||
- 描述存入 `Stmt::ForEach.label`(`Option<String>`),供 M8 渲染/诊断使用
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
a=值
|
||||
b=二
|
||||
果子=一
|
||||
果子=二
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么先做 M3 再做 M7
|
||||
|
||||
迁移(M7)要把 506 处 `[k](c)` 改写掉,而改写目标必须**先存在且等价**。
|
||||
先有 `access` 与循环新形,迁移才是"机械替换",而不是"边迁移边发明语义"。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(2) | `access` 表/列表 + 循环遍历输出正确;缺键报 `missing map key`(与旧取元一致) | ✅ |
|
||||
| 全量 | `cargo test --release` | **595 passed / 0 failed**(M5 后 593 + 2) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `access` 不做缺省值 | 缺省语义请用 `get(表, 键, 默认)`;两者并存 |
|
||||
| 循环描述暂只存不用 | M8 在 `view` 与诊断里使用 |
|
||||
| 旧 foreach 仍可用 | M7 迁移并加门禁后才变成错误 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/interp.rs` | `access` / `取` / `取值` 分派(复用 `builtin_footnote_get`) |
|
||||
| `src/ast.rs` | `Stmt::ForEach.label: Option<String>` |
|
||||
| `src/parse/mod.rs` | `parse_occluded_foreach`;occlusion 模式下优先识别 |
|
||||
| `src/bytecode/compile.rs` / `src/ast.rs` / `src/interp.rs` | 穷举模式补 `label: _` |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/access-and-loop.mq.md` | 2 个集成测试 |
|
||||
| `doc/design/change-m3-access-and-loop.md` | 本文件 |
|
||||
@@ -0,0 +1,84 @@
|
||||
# 变更记录:M4 L1 引用一致性(`label.ref_dangling`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M4([label-freshness-and-repair.md](label-freshness-and-repair.md) §3.1 / [occlusion-syntax.md](occlusion-syntax.md) §11.1) |
|
||||
| 改动文件 | `src/label.rs` · `tests/occlusion.rs` · `tests/occlusion/ref-*.mq.md` |
|
||||
| 影响面 | `marqdo check`(新增一条 error) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 规则
|
||||
|
||||
> 描述里用反引号写出的名字 = **断言**:它必须能解析
|
||||
> —— 要么 `()` 的实现用到它,要么文档里定义了它,要么它是内置函数。
|
||||
|
||||
```markdown
|
||||
**a = [按 `税率` 计算](100 * 0.1)** # ❌ label.ref_dangling(税率为空悬)
|
||||
**b = [按 `税率` 算](100 * `税率`)** # ✅ 实现里用到
|
||||
**c = [取长度](len("abc"))** # ✅ 内置函数
|
||||
**d = [用 `加` 求和](> 加 1 2))** # ✅ 模块内函数
|
||||
```
|
||||
|
||||
实测:
|
||||
|
||||
```
|
||||
dangling.mq.md:3:1: 描述引用了不存在的实体:`税率` —— 本段实现没有用到它,模块里也没有定义
|
||||
contract check: 1 条诊断(1 error) # exit 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么只认反引号(可证伪原则)
|
||||
|
||||
| 写法 | 是否检查 | 原因 |
|
||||
|------|---------|------|
|
||||
| `` `税率` `` | ✅ | 显式引用,可证伪 |
|
||||
| 普通汉字"税率" | ❌ | 自然语言无法机械判定,检查必然假阳性 |
|
||||
|
||||
代价:作者不写反引号就得不到保护。这是刻意的——**机器只校验它看得懂的断言**,
|
||||
同时反向抑制"为凑数写废话"。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现
|
||||
|
||||
| 环节 | 做法 |
|
||||
|------|------|
|
||||
| 抽取 | `refs(label)`:扫描成对反引号,取内部去空白;未闭合/空串忽略 |
|
||||
| 作用域 | `payload_idents(payload)`(Var / callee / path / receiver / `[k]` 的变量键 / 插值变量)∪ `module_symbols(module)`(函数与子函数、参数、import/use 绑定、frontmatter 键)∪ `HostFn::from_name` |
|
||||
| 诊断 | `label.ref_dangling`,**error**,带 `doc_quote`(描述原文)与可执行建议 |
|
||||
|
||||
`OcclusionSite` 增加 `payload_idents` 字段,在 `collect` 阶段一次算好,`check` 只做集合查找。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(3) | 单引用 / 多引用与散文混排 / 无引用与未闭合反引号不 panic | ✅ |
|
||||
| 集成(2) | 悬空引用 exit 1 + 文案;三类可解析引用(payload 变量 / 内置 / 模块函数)零诊断 | ✅ |
|
||||
| 全量 | `cargo test --release` | **583 passed / 0 failed**(M2.5 后 578 + 5) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界与后续
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只查"能否解析" | 不查"语义是否仍成立"——那是 T1(M6)与人工/LLM 复核的活 |
|
||||
| 不查"能解析但实现没用到" | 该情形在模块级符号时无法区分误报,留待 T1 变更驱动 |
|
||||
| 描述里的反引号不是变量绑定 | 只是断言,不进入任何作用域 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `refs()` · `payload_idents()` · `module_symbols()` · `OcclusionSite.payload_idents` · `check` 增 `label.ref_dangling` · 3 个单测 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/{ref-dangling,ref-ok}.mq.md` | 2 个集成测试 |
|
||||
| `doc/design/change-m4-label-refs.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 变更记录:M5 隐式遮蔽(`>` 调用上方的叙述)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented**(**默认关闭**,`--implicit-labels` 开启) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M5([occlusion-syntax.md](occlusion-syntax.md) §11.2) |
|
||||
| 改动文件 | `src/label.rs` · `src/check.rs` · `src/main.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | `marqdo check` 新增可选检查(默认不改变输出) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 规则
|
||||
|
||||
> **`>` 调用上方的叙述段**就是它的"描述";段内的反引号实体必须被这次调用用到
|
||||
> (或能解析到模块/内置)。
|
||||
|
||||
```markdown
|
||||
按 `税率` 与 `档位` 计算应缴税额: ← 描述
|
||||
|
||||
> 计税 档位=2 金额=100 ← 实现用到了 `档位`,但没有 `税率`
|
||||
```
|
||||
|
||||
```
|
||||
impl.mq.md:5:1: 调用上方的描述提到 `税率`,但这次调用没有用到它
|
||||
```
|
||||
|
||||
段落边界:紧邻上一行起,遇空行(允许**一个**分隔空行,因为 blockquote 前通常空一行)、
|
||||
标题、代码行(`**`/`>`/`-`/`|`/数字开头)即止。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键决策:**默认关闭**
|
||||
|
||||
这不是洁癖,是实测结论:
|
||||
|
||||
| 阶段 | lib + ext/ai 上的警告数 |
|
||||
|------|------------------------|
|
||||
| 初版(任何反引号都算断言) | **6 条**(全部误报:`` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `exec` ``/`` `net` ``) |
|
||||
| 加"实体名形状"过滤 | 2 条 |
|
||||
| **再加默认关闭** | **0 条** |
|
||||
|
||||
理由:**描述一个调用可以用任意措辞**,这比"遮蔽"松散得多;
|
||||
机械校验必然模糊,默认开启就会制造疲劳(违背 [warning-fatigue-control.md](warning-fatigue-control.md))。
|
||||
所以它和 L1 不同:L1 是"能证明才报",隐式检查是"觉得可疑就报"——后者必须 opt-in。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实体名过滤(降低误报)
|
||||
|
||||
反引号内容必须**像实体名**才算断言:
|
||||
|
||||
```rust
|
||||
首字符:字母 / `_` / 非 ASCII(不能是数字)
|
||||
其余:字母数字 / `_` / `.` / 非 ASCII 且非空白
|
||||
```
|
||||
|
||||
于是 `` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `path=` `` 全部被排除。
|
||||
|
||||
---
|
||||
|
||||
## 4. 用法
|
||||
|
||||
```bash
|
||||
marqdo check 文件.mq.md # 默认:不含隐式检查(零噪音)
|
||||
marqdo check 文件.mq.md --implicit-labels # 开启
|
||||
```
|
||||
|
||||
MLSP 侧留了同义参数位(`validate` 的 `implicit_labels`),M8 一并接。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3) | 默认静默;opt-in 报不一致;opt-in 对一致描述仍静默 | ✅ |
|
||||
| 全量 | `cargo test --release` | **593 passed / 0 failed**(M6 后 590 + 3) |
|
||||
|
||||
**反向验证**:`implicit_labels_off_by_default` 与 `..._stays_quiet_when_consistent`
|
||||
两条都在证明"不乱响"。
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只查 `>` 语句调用 | 表达式内调用没有"上方叙述"这回事 |
|
||||
| 只认反引号 + 实体形状 | 普通散文永远不参与 |
|
||||
| 不查 payload 语义 | 只查"提到的实体是否被用到" |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `CallSite` · `call_sites` · `paragraph_above` · `is_entity_ref` · `check_implicit` |
|
||||
| `src/check.rs` | `check_path_opts(path, implicit_labels)`(`check_path` 保持默认关闭) |
|
||||
| `src/main.rs` | `check --implicit-labels` |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/implicit-*.mq.md` | 3 个集成测试 |
|
||||
| `doc/design/change-m5-implicit-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,109 @@
|
||||
# 变更记录:M6 T1 会话内陈旧检测 + 会话末汇总
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M6([t1-session-staleness.md](t1-session-staleness.md) · [staleness-providers.md](staleness-providers.md) T1) |
|
||||
| 改动文件 | `src/label.rs` · `src/mlsp.rs` · `src/view/mod.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | MLSP `repair_apply` 新增可选字段;新增 `session.summary` 方法 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 机制
|
||||
|
||||
`repair_apply` 内部同一作用域里同时有 `source`(改前)与 `new_source`(改后),
|
||||
所以「描述是否还成立」可以**纯内存**判定:
|
||||
|
||||
```
|
||||
stale ⟺ 标签文本未变 ∧ payload 指纹变了
|
||||
```
|
||||
|
||||
配对按 `(标签文本, 出现序号)`,因此**移动代码不会误报**。
|
||||
|
||||
请求:
|
||||
|
||||
```json
|
||||
{"method":"repair_apply","params":{
|
||||
"source":"…","ranges":[[3,3]],
|
||||
"edits":[{"op":"replace","line":3,"text":"**a = [按税率算总价](100 * 0.2)**"}],
|
||||
"check_labels":true}}
|
||||
```
|
||||
|
||||
响应:
|
||||
|
||||
```json
|
||||
{"id":1,"ok":true,"result":{
|
||||
"source":"…","edits_applied":1,
|
||||
"labels":{"newly_seen":1,"stale":[
|
||||
{"label":"按税率算总价","line":3,
|
||||
"code_past":"100 * 0.1","code_now":"100 * 0.2"}]}}}
|
||||
```
|
||||
|
||||
**同一份 `source` / `new_source` 就是"前一状态"**——不需要 git、不需要台账、
|
||||
不需要沙箱里的 exec 权限。这是"agent 回路不需要 VCS"的落地。
|
||||
|
||||
---
|
||||
|
||||
## 2. 会话末汇总(你要求做)
|
||||
|
||||
`session.summary` 返回并**重置**计数:
|
||||
|
||||
```json
|
||||
{"ok":true,"labels_stale_seen":1,"labels_fixed":0,
|
||||
"labels_outstanding":1,"items":["按税率算总价"]}
|
||||
```
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `labels_stale_seen` | 本次会话累计发现过多少条(去重按标签) |
|
||||
| `labels_fixed` | 曾经 outstanding、现在不再 stale 的条数 |
|
||||
| `labels_outstanding` | 仍未处理 |
|
||||
| `items` | 未处理的标签文本(只给文本,不重复诊断细节) |
|
||||
|
||||
设计:客户端在收尾时调用一次即可闭合;**不主动打屏**,不污染协议。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键取舍
|
||||
|
||||
| 取舍 | 理由 |
|
||||
|------|------|
|
||||
| `check_labels` 默认 **false** | 零开销、零噪音;agent 框架在修复回路里显式打开 |
|
||||
| 标签变了 → **不报** | 作者改描述本身就是"已复核"的信号 |
|
||||
| 新标签 → 不报 | 无历史可比 |
|
||||
| 指纹用 `Debug` | **只需进程内一致**;跨版本稳定指纹是 T2/T3 的事 |
|
||||
| payload 渲染用 `view::expr_display` | 让 `code_past/code_now` 是人能读的表面语法,而非 AST 调试串 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(3) | 只改 payload → `stale` 含 `code_past`/`code_now`;同时改标签 → `stale: []`;`session.summary` 计数正确 | ✅ |
|
||||
| 全量 | `cargo test --release` | **590 passed / 0 failed**(M10 后 587 + 3) |
|
||||
|
||||
**反向验证**:`t1_silent_when_label_also_changes` 证明"改描述即复核"不会误报。
|
||||
|
||||
---
|
||||
|
||||
## 5. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只看本次编辑 | 跨会话漂移是 T2/T3 的职责(可选 provider) |
|
||||
| 解析失败则跳过 | 修复后的源码可能语法错误,此时不评测标签,交给 `validate` |
|
||||
| 会话状态是进程级 | 一条 MLSP 连接(一个进程)即一个会话;`session.summary` 后清零 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `StaleItem` · `payload_fingerprint` · `compare` · `SessionSummary`(含 `record`)· `OcclusionSite.payload_fp/payload_src` |
|
||||
| `src/mlsp.rs` | `repair_apply` 的 `check_labels`;`session.summary`;进程级 `SESSION` |
|
||||
| `src/view/mod.rs` | `pub use render::expr_display`(供诊断渲染 payload) |
|
||||
| `tests/occlusion.rs` | 3 个 T1 集成测试 |
|
||||
| `doc/design/change-m6-t1-session.md` | 本文件 |
|
||||
@@ -0,0 +1,127 @@
|
||||
# 变更记录:M7 迁移与版本门(per-file 标记 + `migrate labels` + 全仓迁移)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M7([occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | **新增 `src/migrate.rs`** · `src/load.rs` · `src/parse/mod.rs`(expr) · `src/host/dispatch.rs` · **80 个语料文件** · 测试 |
|
||||
| 影响面 | 语法模式按文件切换;全仓 256 处索引 + 23 处循环已迁移 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原计划的问题:同形换义
|
||||
|
||||
原设计想"翻转默认 + 对旧形硬报错"。但 `[键](集合)` 与 `[描述](实现)` **外形完全相同**:
|
||||
|
||||
- 翻转默认 → 506 处取元**静默变成**"遮蔽整个集合",正是文档点名的最坏变更
|
||||
- 硬报错 → 无法实现:解析器拿不到"这是旧写法"的证据(两种读法都合法)
|
||||
|
||||
**结论:模式不能全局翻转,必须按文件声明。**
|
||||
|
||||
## 2. 新方案:per-file `markup:`
|
||||
|
||||
```markdown
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
```
|
||||
|
||||
| 文件 | 解析模式 | `[a](b)` 的含义 |
|
||||
|------|---------|----------------|
|
||||
| 无 `markup:` | classic(进程默认) | 取元 |
|
||||
| `markup: occlusion` | 纯度 | 遮蔽 |
|
||||
|
||||
实现:`load.rs` 先读 frontmatter 取出模式,用 `parse::expr::with_markup(m, …)`
|
||||
(线程局部覆盖,压栈/出栈)包住解析。**同一进程里可以同时加载两种模式的文件**
|
||||
(imports!),且 `MARQDO_MARKUP=occlusion` 仍可作为进程默认。
|
||||
|
||||
好处:迁移是**逐文件、可增量、可回滚**的;不存在"半迁移的静默错义"。
|
||||
|
||||
## 3. 迁移工具 `marqdo migrate labels`
|
||||
|
||||
```bash
|
||||
marqdo migrate labels . # 干跑:列出将改什么
|
||||
marqdo migrate labels . --write # 实际写入
|
||||
marqdo migrate labels . --json # 机器可读
|
||||
```
|
||||
|
||||
### 3.1 改写规则
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| `[键](集合)` | `[键](access(集合, "键"))` |
|
||||
| `` [`名`](集合) `` | `` [名](access(集合, `名`)) `` |
|
||||
| `- [项](集合)` | `- [项](遍历 集合 为 项)` |
|
||||
|
||||
`access` 是新增宿主函数(`host_access`,id 212),语义与旧取元**逐字一致**
|
||||
(Map 按键 / List 1-based / 缺键 `missing map key`)。它进 `HostFn` 是有意的:
|
||||
**两个后端共用同一实现**,不再有特例分支。
|
||||
|
||||
### 3.2 安全模型:改写 → 重解析 → 证明等价 → 才写
|
||||
|
||||
1. 原文件按 classic 解析,得到 AST-A
|
||||
2. 文本改写后,按 occlusion 解析,得到 AST-B
|
||||
3. **反归一化** B:把"标签与键同名 + payload 为 `access(x, k)`"的遮蔽还原成 `Index`
|
||||
4. 比较 `Debug(A)` 与 `Debug(反归一化(B))`(抹掉行号,因为插入了 marker 行)
|
||||
5. 只有相等才写入;否则**原文件一字不动**并报告 `equivalence check failed`
|
||||
|
||||
这条校验是真干活的:它先后抓出 4 类改写 bug(表格散文链接、payload 继承文本模式、
|
||||
链式索引、`[问候] (…)` 与遮蔽混淆),每一类都是**先被拦下、再修工具**,没有污染文件。
|
||||
|
||||
### 3.3 只改代码行
|
||||
|
||||
用词法层的 `LineKind::Code` 限定范围;表格行只改 `**…**` 单元格
|
||||
(散文里的 markdown 链接 `[docs](https://…)` 必须原样保留)。
|
||||
|
||||
### 3.4 由内向外
|
||||
|
||||
链式索引 `[content]([1]([messages](req)))` 必须**最内层先改**,
|
||||
否则外层改写会让内层的位置失效;已迁移的 `[k](access(…))` 有守卫,不会二次改写。
|
||||
|
||||
## 4. 全仓迁移结果
|
||||
|
||||
```
|
||||
migrate labels: 256 index, 23 loop, 80 file written
|
||||
```
|
||||
|
||||
- 覆盖 `lib/ ext/ examples/ public/ cli/ tests/`
|
||||
- **0 文件被等价性检查拒绝**
|
||||
- 迁移后 `cargo test --release` → **604 passed / 0 failed**
|
||||
- 再跑一次迁移 → **幂等**(只剩刻意保留的 classic 测试样例)
|
||||
|
||||
## 5. 顺带修的两处真实语义缺陷
|
||||
|
||||
| 缺陷 | 现象 | 修法 |
|
||||
|------|------|------|
|
||||
| payload 继承外层"文本模式" | `f text=[k](access(c,k))` 里 `access(...)` 不被当调用 → 退化成插值文本 | `()` 内**永远**允许 `callee(args)`(`parse_occluded` 临时置位) |
|
||||
| 遮蔽形状判定过宽 | `[问候] ([格式化] "Bo")` 被误判为遮蔽 | 要求 `]` 后**紧跟** `(`;否则落回方括号调用 |
|
||||
|
||||
## 6. 版本门
|
||||
|
||||
- 旧写法**不再**被硬报错——因为无法与遮蔽区分;真正的门是 **per-file 声明**:
|
||||
没写 `markup: occlusion` 的文件按 classic 解析,行为不变。
|
||||
- 需要"禁止新写旧形"的仓库可用 `migrate labels` 干跑做 CI 门禁(有改动即失败)。
|
||||
|
||||
## 7. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 单元(6) | 静态键 / 动态键 / 嵌套三层 / 已迁移不重写 / 循环 / 非循环 | ✅ |
|
||||
| 集成(3) | 干跑不写盘;写入后**运行输出不变**且幂等;等价失败则文件不动 | ✅ |
|
||||
| 全量 | `cargo test --release` | **604 passed / 0 failed**(M3 后 595 + 9) |
|
||||
| 双后端 | gold 套件含 bytecode 变体 | ✅ |
|
||||
|
||||
## 8. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/migrate.rs` | **新增**:改写器、等价性证明、`migrate_file` / `migrate_path` |
|
||||
| `src/load.rs` | `frontmatter_markup` + `with_markup` 包裹两处 `parse_source` |
|
||||
| `src/parse/expr.rs` | `with_markup` 线程局部覆盖;`()` 内强制允许调用;`occlusion_shape_ahead` 严格判定 |
|
||||
| `src/host/dispatch.rs` | `HostFn::Access`(enum / from_u16 212 / from_name / name / required_params / call_host) |
|
||||
| `src/main.rs` | `migrate labels` 子命令 |
|
||||
| `src/interp.rs` | 移除 access 特例(改用 HostFn,单一实现) |
|
||||
| 80 个语料文件 | 索引与循环迁移 + `markup: occlusion` 标记 |
|
||||
| `tests/migrate.rs` + `src/migrate.rs` 单测 | 9 个测试 |
|
||||
| `doc/design/change-m7-migration.md` | 本文件 |
|
||||
@@ -0,0 +1,81 @@
|
||||
# 变更记录:M8 债务棘轮与呈现
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M8([warning-fatigue-control.md](warning-fatigue-control.md) §4 棘轮 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/main.rs` · `tests/ratchet.rs` |
|
||||
| 影响面 | `labels` 新增 `--baseline` / `--fail-on-increase` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 棘轮规则
|
||||
|
||||
```bash
|
||||
# CI:未完成项只许减少,不许增加
|
||||
marqdo labels . --baseline .marqdo/pending.json --fail-on-increase
|
||||
```
|
||||
|
||||
| 情形 | 行为 | 退出码 |
|
||||
|------|------|--------|
|
||||
| 台账不存在 | **建立**(写入当前计数),提示 `已建立 N` | 0 |
|
||||
| 当前 > 台账 | 失败,提示 `未完成项增加了 K` | **1** |
|
||||
| 当前 ≤ 台账 | 通过;若减少则**收紧**台账(`N → M`) | 0 |
|
||||
|
||||
**为什么"减少即收紧"**:否则债务可以先降后升,棘轮形同虚设。
|
||||
收紧后台账记住新的低水位,回退到旧数量同样会失败(测试第 4 步验证)。
|
||||
|
||||
台账格式:
|
||||
|
||||
```json
|
||||
{"count": 1, "words": ["待开发", "未开发", "…"]}
|
||||
```
|
||||
|
||||
记录词集是为了让"口径变了"可被审计——换词集时会看到 `words` 变化。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么用棘轮而不是硬门禁
|
||||
|
||||
| 方案 | 老债 | 新债 | 结论 |
|
||||
|------|------|------|------|
|
||||
| 硬门禁(必须为 0) | 阻塞一切 | 拦住 | 存量债立刻红一片,逼人关检查 |
|
||||
| **棘轮(只拦增量)** | 不阻塞 | 拦住 | ✅ 债务可见且不恶化 |
|
||||
| 无门禁 | 不阻塞 | 不拦 | 债务无声增长 |
|
||||
|
||||
这与 [warning-fatigue-control.md](warning-fatigue-control.md) 的结论一致:
|
||||
**老账不追、新账必拦**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 呈现(已具备)
|
||||
|
||||
| 面 | 表现 |
|
||||
|----|------|
|
||||
| `expr_display` / `view` | 遮蔽渲染为 `[描述](实现)`,桩渲染为 `[描述]()`,实测 `view output` 页面含 `access(` |
|
||||
| `labels` | 人类行 `文件:行 [函数] 描述 ← 命中词`;`--json` 一个数组 |
|
||||
| `check` | `label.*` 三类诊断(missing / empty_payload / ref_dangling) |
|
||||
| MLSP | `labels.search` · `session.summary` |
|
||||
|
||||
**没有做桩徽章**:桩已经是 `[描述]()` 这个显眼形状,再加装饰是噪音;
|
||||
需要计数时用 `labels --count`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(1 个四步用例) | 建账 → 增加失败 → 减少收紧 → 回退再次失败 | ✅ |
|
||||
| 全量 | `cargo test --release` | **605 passed / 0 failed**(M7 后 604 + 1) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/main.rs` | `labels --baseline` / `--fail-on-increase`;建账/收紧/违约逻辑 |
|
||||
| `tests/ratchet.rs` | 四步棘轮用例 |
|
||||
| `doc/design/change-m8-ratchet.md` | 本文件 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# 变更记录:M8 view 遮蔽呈现(+ 修一个真实回归)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [occlusion-syntax.md](occlusion-syntax.md) §13 M8「view 徽章/呈现」 |
|
||||
| 改动 | `src/load.rs` · `src/view/{document,render,html,mod,debug_page}.rs` |
|
||||
| 影响 | 只影响呈现;顺带修了 **view 无法解析遮蔽文件** 的回归 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 先修回归:view 用错解析模式
|
||||
|
||||
`view` 内部多处直接用 `crate::parse::parse_source(source)` 重新解析文件,
|
||||
而 per-file `markup:` 是在 `load` 层生效的(M7)。结果:
|
||||
|
||||
```
|
||||
<div class="structure"><div class="err">parse/load error: expected ')' after link-index collection</div></div>
|
||||
```
|
||||
|
||||
任何带 `markup: occlusion` 的文档在 view 里**结构区直接报错**,只能退化成源码视图。
|
||||
用户看到的"粗体里的 `[描述](实现)` 没渲染"其实是这个错误的表象。
|
||||
|
||||
**修法**:`load::parse_source_auto(source)` —— 先读 frontmatter 的 `markup:`,
|
||||
用 `with_markup` 包住 `parse_source`,view 的五处解析点全部改用它。
|
||||
|
||||
## 2. 遮蔽呈现
|
||||
|
||||
### 2.1 浏览视图(`document.rs`,`/file`)
|
||||
|
||||
```html
|
||||
<div class="doc-line doc-occl" data-line="81">
|
||||
<span class="occl-pre">留存 =</span> <!-- 变量名:灰、等宽 -->
|
||||
<span class="occl-label">客户留存率,模拟数据</span> <!-- 描述:正文 -->
|
||||
<code class="occl-code">0.42</code> <!-- 实现:代码片 -->
|
||||
</div>
|
||||
```
|
||||
|
||||
- 空载荷 → `<span class="occl-stub">桩</span>`(琥珀色徽章,title 说明"未接通或待补返回值")
|
||||
- 前缀里的反引号/`**` 都剥掉(与其它行 `mq-anchor` 的处理一致)
|
||||
- 只在词法上切分,不改语义:解析器早已验证结构,这里只决定怎么画
|
||||
|
||||
### 2.2 卡片视图(`render.rs`,`/debug`)
|
||||
|
||||
按 AST 直接匹配 `Expr::Occluded`(`Assign` / `Expr` / `Return` 三种语句),
|
||||
渲染成 `card occl-card`:徽章「遮蔽」+ 变量名 + 描述 + 代码片/桩徽章。
|
||||
|
||||
### 2.3 样式(`html.rs`)
|
||||
|
||||
```css
|
||||
.doc-occl { display:flex; align-items:baseline; flex-wrap:wrap; gap:.4rem; }
|
||||
.occl-pre { font-family:var(--mono); font-size:.86em; color:var(--muted); }
|
||||
.occl-label { color:var(--ink); }
|
||||
.occl-code { font-family:var(--mono); background:var(--fill); border:1px solid var(--line);
|
||||
border-radius:6px; padding:.02rem .38rem; }
|
||||
.occl-stub { background:rgba(255,159,10,.18); color:#9a5b00; border-radius:999px; }
|
||||
```
|
||||
|
||||
刻意**不加**虚线下划线:容易被读成链接/缩写。描述就是正文,靠代码片的边框与之区分。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| 结构区解析错误 | **消失**(`/file` 页面 0 处 `parse/load error`) |
|
||||
| 七个遮蔽行 | 全部渲染为 `doc-occl`:6 个代码片 + 1 个桩徽章 |
|
||||
| 文本抽取 | `留存 = 客户留存率,模拟数据 [0.42]` / `待接 = 搜索接入,接口未接,待开发 [桩]` |
|
||||
| 单元(4) | 裸赋值 / 粗体赋值 / 空载荷+嵌套 payload / 非遮蔽行不误判 |
|
||||
| 全量 | `cargo test --release` **613 passed / 0 failed**(609 + 4) |
|
||||
|
||||
## 4. 未能做到的:截图
|
||||
|
||||
本机没有任何浏览器(`chromium`/`chrome`/`firefox` 均不存在),
|
||||
`npm i puppeteer` 装上了包但 Chromium 下载被网络阻断(`storage.googleapis.com`
|
||||
TLS 断连,两次重试均失败)。所以无法自动截图比对,改为:
|
||||
DOM 结构断言 + 提供 `/.preview/occlusion.html` 方案对照页由作者目视确认。
|
||||
|
||||
## 5. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/load.rs` | 新增 `parse_source_auto`(按 frontmatter `markup:` 解析) |
|
||||
| `src/view/mod.rs` | 3 处解析改 `parse_source_auto` |
|
||||
| `src/view/debug_page.rs` | 1 处同上 |
|
||||
| `src/view/document.rs` | `split_occlusion` / `match_delim` / `render_occlusion_line` + 4 个单测 |
|
||||
| `src/view/render.rs` | `occl_card` + 三个 `Expr::Occluded` 语句分支 |
|
||||
| `src/view/html.rs` | `.doc-occl` / `.occl-*` 样式 |
|
||||
| `doc/design/change-m8-view-occlusion.md` | 本文件 |
|
||||
@@ -0,0 +1,113 @@
|
||||
# 变更记录:M9 两级词表检索(`labels` CLI + MLSP `labels.search`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 里程碑 | M9([occlusion-description-and-search.md](occlusion-description-and-search.md) §3 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
|
||||
| 改动文件 | `src/label.rs` · `src/main.rs` · `src/mlsp.rs` · `tests/occlusion.rs` |
|
||||
| 影响面 | 新增 CLI 子命令与 MLSP 方法(**不改语法**) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 两级词表
|
||||
|
||||
| 级 | 在哪 | 作用 |
|
||||
|----|------|------|
|
||||
| **第一级:内置** | `label::BUILTIN_GROUPS`(数据常量) | 默认查询 + LLM 范例 + 跨项目可比 |
|
||||
| **第二级:参数** | `--grep` / `grep` | 替换或并集,项目自己的说法照样能搜 |
|
||||
|
||||
内置六组:`未完成`(待开发/未开发/开发中/未实现/待实现/未接/接口未接/TODO)、
|
||||
`假数据`(模拟/假数据/桩/占位/stub/mock)、`示例`、`实验`、`废弃`、`待校验`。
|
||||
`pending` = `未完成 ∪ 假数据`。
|
||||
|
||||
**词表是数据不是语法**:扩充它不改任何解析规则。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo labels . # 默认:pending 口径(内置两组)
|
||||
marqdo labels . --grep "联调" # 替换为自定义词
|
||||
marqdo labels . --grep "联调" --also-builtin # 自定义 ∪ 内置
|
||||
marqdo labels . --group 示例,实验 # 选内置组
|
||||
marqdo labels . --count # 只给数字(CI/棘轮用)
|
||||
marqdo labels . --json # 一个 JSON 数组
|
||||
```
|
||||
|
||||
输出(人类):
|
||||
|
||||
```
|
||||
a.mq.md:3 [main] 按关键词检索,接口未接,待开发 ← 待开发,未接,接口未接
|
||||
a.mq.md:4 [main] 客户留存率,模拟 ← 模拟
|
||||
label search: 2 命中(1 文件,词=[…])
|
||||
```
|
||||
|
||||
`--json`:
|
||||
|
||||
```json
|
||||
[{"file":"a.mq.md","line":3,"unit":"main","label":"…","words":["待开发"],"has_payload":true}]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. MLSP
|
||||
|
||||
```json
|
||||
{"id":1,"method":"labels.search",
|
||||
"params":{"source":"…"|"path":"…","grep":["联调"],"also_builtin":true}}
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```json
|
||||
{"ok":true,"words":[…],"count":2,"hits":[{"line":3,"unit":"main","label":"…",
|
||||
"words":["待开发"],"has_payload":true}]}
|
||||
```
|
||||
|
||||
语义与 CLI 完全一致(同一份 `label::search`)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 检索语义(v1)
|
||||
|
||||
| 项 | 规则 |
|
||||
|----|------|
|
||||
| 匹配 | **子串**(CJK 无词边界,子串最稳) |
|
||||
| 多词 | OR |
|
||||
| 大小写 | 英文不敏感(`TODO`/`todo` 等价) |
|
||||
| 误判 | 必然存在(`[不属于待开发范围]` 会命中)——只影响计数,输出带描述原文可人工判断 |
|
||||
|
||||
不做否定语法;留作 v1.1 可选项。
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 层 | 内容 | 结果 |
|
||||
|----|------|------|
|
||||
| 集成(4) | pending 计数=2;`--grep` 替换=1;`--also-builtin` 并集=3;MLSP `labels.search` 返回 hits | ✅ |
|
||||
| 全量 | `cargo test --release` | **587 passed / 0 failed**(M4 后 583 + 4) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 边界
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 只在 occlusion 模式产生命中 | classic 模式下没有 `Expr::Occluded`;M7 翻转默认后自然可用 |
|
||||
| 解析失败的文件跳过 | 那是 `check` 的职责,检索不应因一个坏文件整体失败 |
|
||||
| 不做棘轮 | `--baseline` / `--fail-on-increase` 留给 M8(门禁) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/label.rs` | `WordGroup` / `BUILTIN_GROUPS` / `PENDING_GROUPS` / `group_words` / `parse_words` / `matched_words` / `Hit` / `search` |
|
||||
| `src/main.rs` | `labels` 子命令 + `collect_mq_files` 递归扫描 |
|
||||
| `src/mlsp.rs` | `labels.search` 方法 + 分发 |
|
||||
| `tests/occlusion.rs` + `tests/occlusion/labels.mq.md` | 4 个集成测试 |
|
||||
| `doc/design/change-m9-label-search.md` | 本文件 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 变更记录:插件 ABI 共享 crate(`marqdo-plugin-sdk`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Implemented** |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 1 项 |
|
||||
| 改动 | **新增 `crates/marqdo-plugin-sdk`** · 5 个插件改为依赖它 |
|
||||
| ABI | **不变**(`include/marqdo_abi.h`、`src/host/plugin.rs` 看到的符号与布局完全一致) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
5 个原生插件各自复制同一套 ABI 前言(约 140 行/个):
|
||||
|
||||
| 复制的内容 | 说明 |
|
||||
|-----------|------|
|
||||
| `type PluginFn` / `HostQueryFn` / `struct MarqdoHostApi` | 布局必须逐字一致,抄错就是 UB |
|
||||
| `static mut HOST_ALLOC/FREE/QUERY/USERDATA` | 同上 |
|
||||
| `host_strdup` / `set_out` / `set_err` / `parse_args` / `reply` | 语义必须一致 |
|
||||
| `register` + `#[no_mangle]` 四导出 | 样板 |
|
||||
|
||||
一共 5 份,任何一份漂移都会在运行期表现为"某插件偶发崩"。
|
||||
|
||||
## 2. 方案
|
||||
|
||||
新增工作区成员 `crates/marqdo-plugin-sdk`,持有唯一一份实现,并提供一个宏生成各 `.so` 必需的导出:
|
||||
|
||||
```rust
|
||||
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
|
||||
("llm_ping", "", llm_ping),
|
||||
("llm_chat_completions", "base_url,api_key,...", llm_chat_completions),
|
||||
]);
|
||||
```
|
||||
|
||||
宏展开为 `marqdo_plugin_abi_version` / `marqdo_plugin_shutdown` / `marqdo_plugin_init`,
|
||||
其中 init 调 `init_plugin(host, &[…])`(保存回调 + 逐个注册)。
|
||||
|
||||
`demo` 是 ABI **v1**,宏接受版本参数:`marqdo_plugin!(1, [...])`,语义不变。
|
||||
|
||||
## 3. 安全措施:注册项逐一核对
|
||||
|
||||
迁移时把每个插件的 `register(...)` 调用抽取成表。**第一次抽取漏了 11 项**——
|
||||
正则是 `[a-z_0-9]+`,匹配不到 `mcp_server::agent_mcp_serve`、`sandbox::*` 这类
|
||||
**路径限定**的函数名。编译能过(表少几行),运行时才会 `unknown function`。
|
||||
|
||||
补救:正则允许 `::`,并把新旧两张表逐项比对:
|
||||
|
||||
| 插件 | HEAD 注册项 | 迁移后 | 差异 |
|
||||
|------|------------|--------|------|
|
||||
| agent | 63 | 63 | **0** |
|
||||
| quantum | 41 | 41 | 0 |
|
||||
| linalg | 31 | 31 | 0 |
|
||||
| llm | 2 | 2 | 0 |
|
||||
| demo | 2 | 2 | 0 |
|
||||
|
||||
比对脚本同时校验 `(名称, 参数串, 函数)` 三元组完全一致,不只比数量。
|
||||
|
||||
另外两次由"编译通过但语义已变"暴露的问题:
|
||||
|
||||
| 问题 | 现象 | 处理 |
|
||||
|------|------|------|
|
||||
| `mcp_client` 被误判为死模块 | 我删掉 327 行后发现 `agent_mcp_client` 正注册它 | 恢复模块(教训:先查注册表,再判死) |
|
||||
| 量子插件两个"未使用"函数 | 删除时连带吃掉 `density_from_amps`/`flat_to_nested` | 恢复并加 `#[allow(dead_code)]` 注释 |
|
||||
|
||||
## 4. 收益
|
||||
|
||||
| 插件 | 迁移前 | 迁移后 | 变化 |
|
||||
|------|--------|--------|------|
|
||||
| agent | 1,237 | 929 | −308 |
|
||||
| quantum | 1,045 | 835 | −210 |
|
||||
| linalg | 688 | 524 | −164 |
|
||||
| llm | 405 | 278 | −127 |
|
||||
| demo | 170 | 73 | −97 |
|
||||
| 新增 SDK | — | 232 | +232 |
|
||||
|
||||
净减 **≈ 906 − 232 = 674 行**,且 ABI 前言从 5 份变 1 份。
|
||||
|
||||
## 5. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
|----|------|
|
||||
| `cargo build --release`(含 5 个插件) | 零警告 |
|
||||
| `cargo test --release` | **609 passed / 0 failed** |
|
||||
| 金样实跑(量子) | `p00-ok` / `p11-ok` / `ping-ok` |
|
||||
| 注册项三元组比对 | 5 个插件全部 0 差异 |
|
||||
|
||||
## 6. 边界
|
||||
|
||||
- ABI 版本号、`#[no_mangle]` 符号、结构体布局**一律未变**;旧 `.so` 与新宿主仍可互操作。
|
||||
- 插件私有逻辑(HTTP、矩阵、量子态、agent 工具)一行未动。
|
||||
- 后续新增插件只需依赖 SDK + 一行宏调用。
|
||||
|
||||
## 7. 变更清单
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `crates/marqdo-plugin-sdk/{Cargo.toml,src/lib.rs}` | **新增**:ABI 类型、静态回调、`host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/take_host_string/init_plugin`、`marqdo_plugin!` 宏 |
|
||||
| `Cargo.toml` | workspace 增加 `crates/marqdo-plugin-sdk` |
|
||||
| `plugins/{agent,quantum,linalg,llm,demo}/Cargo.toml` | 增加 SDK 依赖 |
|
||||
| `plugins/*/src/lib.rs` | 删除本地 ABI 前言与四导出,改用宏;注册表改为数组 |
|
||||
| `doc/design/change-plugin-sdk.md` | 本文件 |
|
||||
@@ -0,0 +1,119 @@
|
||||
# 代码即文档 · 叙述面摩擦(v0.3 实测)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Done** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 触发 | `examples/code-as-docs/index.mq.md` 试跑 |
|
||||
| 宪法 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
|
||||
| 路线 | [code-as-docs-gaps.md](../roadmap/code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 原则
|
||||
|
||||
修复必须同时服务:
|
||||
|
||||
1. **代码即文档**:人读 Markdown 时自然段落、分隔线、强调不应被误伤。
|
||||
2. **适配 LLM 输出**:模型习惯写 `---` 分段、`**加粗强调**`、`0.85` 小数、`` map[^`key`] `` 动态键——运行时应尽量「写出来就能跑」。
|
||||
3. **可执行标记仍清晰**:真正的赋值 / 调用 / 返回不被误判成装饰。
|
||||
|
||||
---
|
||||
|
||||
## 1. 四个问题(实测)
|
||||
|
||||
### G1 — 模块级 `---` 被当成结构错误
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 文件标题段落后写 Markdown 分隔线 `---`,报 `expected heading … got: ---` |
|
||||
| 根因 | 词法上整行 `-`/`*` 为 Code;旧实现把函数体内 `---` 当收束,模块顶却当非法。现统一为叙述跳过 |
|
||||
| 人/LLM 期望 | 任意处 `---` = GFM thematic break = **叙述噪音** |
|
||||
| 决议 | **处处** frame 行 skip;副作用收束用 `*None*` / `**` / `****`(返回即结束函数体解析) |
|
||||
|
||||
### G2 — 叙述里的 `**强调**` / `*斜体强调*` 被当成代码/返回
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 「本文件既是**说明**也是**程序**」→ 粗体 `说明` 不是赋值/调用,解析失败;`*only*` 类英文强调升成返回/`only` 变量 |
|
||||
| 根因 | v0.3 叙述扫描凡 `**…**` / `*…*` 一律可执行([prose.rs](../../src/parse/prose.rs));Skill 曾禁止强调,但与 LLM/Markdown 习惯冲突 |
|
||||
| 人/LLM 期望 | 装饰性强调可出现;**像代码的**粗体/斜体仍执行 |
|
||||
| 决议 | **形状启发式**(见 §2):像代码则执行,否则当作叙述装饰(不产生 Stmt,不升参) |
|
||||
|
||||
### G3 — 小数面量 `0.85` 不可用
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `**x = 0.85**` → `trailing input: ".85"`;`28 * 0.85` 解析错乱;即便进到求值,`*` 仍只接受 int |
|
||||
| 根因 | 表达式主词只吃整数字面量(`Literal` 无 `Num`);运行时已有 `Value::Num`,二元运算未接浮点 |
|
||||
| 人/LLM 期望 | `0.85`、`3.14`、`折扣=0.85` 可写可算 |
|
||||
| 决议 | 解析 `数字.数字` → `Literal::Num`;`*` `/` `+` `-` 及比较在 `Int`/`Num` 间提升(与已有 `cmp_ord` 一致) |
|
||||
|
||||
### G4 — 动态脚注键 `` 菜单[^`名`] ``
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `` 菜单[^`名`] `` → `missing map key ``名`` `(把字面 `` `名` `` 当键,或解析失败) |
|
||||
| 根因 | `[^label]` 的 label 仅为**静态字符串**;AST `Expr::Index { label: String }` 无变量槽 |
|
||||
| 人/LLM 期望 | 表/映射按变量取键:`` `菜单`[^`品名`] `` 或 `菜单[^`品名`]` |
|
||||
| 决议 | 支持 `` [^`ident`] `` → 运行时用变量值作键(文本化后走现有 footnote get);静态 `[^拿铁]` 不变 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 粗体/斜体「像代码」启发式
|
||||
|
||||
### 粗体 `**inner**` → 可执行,当且仅当
|
||||
|
||||
满足任一:
|
||||
|
||||
- 含 `=`(赋值 / 命名参数调用);或
|
||||
- 以 `>` 开头(显式调用);或
|
||||
- 含运算符 / 索引 / 调用形:`+ - * / ( ) [ ]`;或
|
||||
- 空白分词 ≥2 段,且其后段含数字面量、引号串、或 `=`(如 `**加一 37**`、`**print text="hi"**`)
|
||||
|
||||
否则(如 `**说明**`、`**代码即文档**`)→ **装饰,忽略**。
|
||||
|
||||
### 斜体 `*inner*` → 返回,当且仅当
|
||||
|
||||
满足任一:
|
||||
|
||||
- 空 / `None` / `无` / `空` / bool 字面;或
|
||||
- 以 `>` 开头;或
|
||||
- 含 `=` 或运算符 / 索引;或
|
||||
- **整行**仅为 `*…*`(含缩进)——整行返回 `*总额*` / `*n*`;或
|
||||
- 行内且前方紧邻「返回」二字(叙述「接着返回*n*」)
|
||||
|
||||
否则行内简单词(如 `*only*`、`*named*`)→ **装饰,忽略**。
|
||||
|
||||
> 整行 `*n*` 仍是返回;行内「返回*n*。」仍是返回。英文强调词在句中被忽略。
|
||||
|
||||
---
|
||||
|
||||
## 3. 非目标
|
||||
|
||||
- 不恢复 v0.2 双模式
|
||||
- 不引入 `if`/`return` 关键字
|
||||
- 不把任意 `**任意自然语言句子**` 都当代码(必须过 §2)
|
||||
- 动态键第一期只做 `` [^`ident`] ``,不做完整表达式 `[^a+b]`
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收
|
||||
|
||||
| 用例 | 期望 |
|
||||
|------|------|
|
||||
| 顶层段落之间的 `---` | 可解析、可运行 |
|
||||
| 「既是**说明**也是**程序**」 | 可解析;无 Stmt |
|
||||
| `**应付 = 原价 * 0.85**` / `折扣`=0.85 | 数值正确(浮点) |
|
||||
| `` **价 = 菜单[^`名`]** ``(`名` 已绑定) | 取到对应价 |
|
||||
| `examples/code-as-docs/index.mq.md` | 用回浮点折扣与动态键后仍绿 |
|
||||
| 既有 `tests/markup-v03/*` 与 gold | 不回归 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿:四缝 + 启发式 + 验收 |
|
||||
| 2026-09-14 | 落地:G1–G4 实现 + 金样;顶层 Comment 引言 skip |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 代码体量审计:53k 行里哪些是特性、哪些是冗余
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **实施记录**(精简依据与进度) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 结论 | 冗余已清 ~14.5k 行;**剩余体量主要是特性面**,不是废弃物 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 当前账目
|
||||
|
||||
| 部分 | 行数 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/` | **52,668** | 其中约 **5,200** 是内联测试(`#[cfg(test)]`) |
|
||||
| `plugins/` + `crates/` | **14,700** | 5 个 ABI 插件(含共享 SDK)+ wasm crate |
|
||||
| 合计 Rust | **67,368** | |
|
||||
|
||||
最大的 10 个文件:
|
||||
|
||||
| 行数 | 文件 | 性质 |
|
||||
|------|------|------|
|
||||
| 4,451 | `src/view/html.rs` | 3,861 行是 CSS/HTML 字符串(页面皮肤) |
|
||||
| 2,691 | `src/parse/mod.rs` | 解析器主体 + 412 行内联测试 |
|
||||
| 2,194 | `src/parse/expr.rs` | 表达式解析 + 465 行内联测试 |
|
||||
| 2,063 | `src/host/foreign_doc.rs` | 外部语言内核(python/node 文档执行) |
|
||||
| 1,648 | `src/host/dispatch.rs` | 202 个宿主函数的元数据表(已合一) |
|
||||
| 1,968 | `src/host/foreign.rs` | 外部进程/会话管理 |
|
||||
| 1,925 | `src/interp.rs` | 树遍历求值器 |
|
||||
| 1,913 | `src/view/render.rs` | 渲染 |
|
||||
| 1,309 | `src/formula/mod.rs` | `$$…$$` 公式求值 |
|
||||
| 1,168 | `src/view/annot.rs` | 注解/映射 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 已清除的冗余(14.5k 行)
|
||||
|
||||
| # | 项 | 行数 | 提交 |
|
||||
|---|----|------|------|
|
||||
| 1 | `plugins/web-rust-archive/`(31 文件,非 workspace 成员、默认不构建、被 Go `libweb` 取代) | **14,235** | `13012ca` |
|
||||
| 2 | `as_text` × 18 份复制(两种措辞)→ 一个 `host::as_text` | ~100 | `8b0ea9e` |
|
||||
| 3 | `catalog.rs` 的 4 个助手(与 `knowledge::util` 逐字相同) | ~70 | `8b0ea9e` |
|
||||
| 4 | `view` 路由 34 臂 → 2 张表(`handle` / `handle_debug`) | 99 | `8b0ea9e` |
|
||||
| 5 | 无调用点死代码 ×5(`parse_italic_assign` 等) | ~50 | `a14a6e2` |
|
||||
| 6 | 转义重复:URL 编码器 2 份、`escape_js_string` 2 份(debug 副本漏 U+2028/2029) | ~40 | `9324032` |
|
||||
| 7 | AST 遍历器 3 份 → `ast::walk_stmts` / `ast::stmt_line` | ~50 | `deac53d` |
|
||||
|
||||
**顺带修出的真实缺陷**(不是行数问题,是正确性问题):
|
||||
|
||||
| 缺陷 | 发现方式 |
|
||||
|------|---------|
|
||||
| `Access` 变体只有隐式判别值(重排即错位) | 新加的一致性测试 |
|
||||
| HOST id 空间稀疏——不是 bug,但此前无测试守护 | 同上(测试先报"不连续",核实后改成"稀疏但可还原") |
|
||||
| `escape_js_string` 的 debug 副本漏转义 U+2028/2029(JS 里是换行符) | 对比两份实现 |
|
||||
| `view` 路由分布在两个 handler,只改一个会让 debug 路由全 405 | 改完实测 HTTP |
|
||||
|
||||
---
|
||||
|
||||
## 3. 剩余体量为什么不是"冗余"
|
||||
|
||||
逐项核过,剩下的都是**功能**,删掉就是砍特性:
|
||||
|
||||
| 区域 | 行数 | 为什么保留 |
|
||||
|------|------|-----------|
|
||||
| `view/` 合计 | ~12,000 | live server + notebook UI:路由、渲染、注解、调试面板、执行报告;审计确认是 feature-gated 的一等 CLI 面 |
|
||||
| `host/foreign*` | ~5,100 | 外部语言内核(python/node 持久会话、快照、中断);qdagent 的沙箱执行依赖 |
|
||||
| `parse/` | ~4,900 | 词法/语法主体 + 内联测试 |
|
||||
| `bytecode/` | 1,921 | 第二后端;72 处测试引用(含双后端一致性) |
|
||||
| `knowledge/` | ~4,000 | catalog / EKC / 指纹;`marqdo catalog` 的输出有 golden 测试 |
|
||||
| `formula/` | 1,741 | `$$…$$` 公式;与 `ast::Expr` 是**不同类型**的两套求值器(不可合并) |
|
||||
| `host/dispatch.rs` | 2,052 | 202 个宿主函数的元数据 + 分派;`call_host` 是 202 个一行臂 |
|
||||
| `view/html.rs` | 4,451 | 其中 3,861 是页面皮肤字符串 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 剩余可精简项(已定位,未做)
|
||||
|
||||
| 项 | 结论 |
|
||||
|----|------|
|
||||
| ~~插件 ABI 前言共享 crate~~ | **已完成**:[change-plugin-sdk.md](change-plugin-sdk.md),净减 674 行,注册项 0 差异 |
|
||||
| ~~HostFn 五表合一~~ | **已完成**:[change-hostfn-table.md](change-hostfn-table.md),−404 行,203 项逐字节一致 |
|
||||
| `view/html.rs` 皮肤"重复声明基础 CSS" | **审计判断不成立**:实测基础样式 312 条规则、notebook 128 条,**选择器零重叠**,无重复可删 |
|
||||
| `debug_page.rs` "复刻 shell" | **判断基本不成立**:只在 head/favicon 上有约 10 行相似;它没有 nav/topbar,是独立极简页 |
|
||||
| 内联测试迁到 `tests/` | 不减总量,只让 `src` 变薄;不做 |
|
||||
|
||||
**结论(修正后)**:可机械消除的重复**已经清完**。剩余体量全是特性实现,
|
||||
要再压只能砍功能(例如 `view` 调试面板、`formula` 引擎),不是"找重复"。
|
||||
|
||||
**判断**:这些加起来约 1.3k 行(总量的 2%),收益边际递减;其中插件 SDK 最值得做(消除 5 份漂移),
|
||||
其余属于"可以但不必"。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与设计的关系
|
||||
|
||||
精简的目的不是数字好看,而是**不让冗余掩盖设计**:
|
||||
|
||||
- 已消除的都是**重复实现**(同一逻辑多份 → 必然漂移)
|
||||
- 保留的都是**单一实现的特性能耐**
|
||||
- 每一条删改都跑全量测试:`605 → 609 passed / 0 failed`,编译零警告
|
||||
|
||||
如果后续还要压体量,正确的方向是**砍特性**(例如 `view` 的调试面板、`formula` 引擎),
|
||||
而不是继续在特性内部找"重复"——那已经找完了。
|
||||
@@ -2,8 +2,12 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 状态 | 与 mapping **v0.3** 对齐(现行运行时) |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 取代 | 本文曾按 v0.2(`*语句*` / `**返回**`)叙述;旧对照见 [markdown-mapping.md](markdown-mapping.md) |
|
||||
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §4 |
|
||||
|
||||
「Markup」在此仓库 = Marqdo **把 Markdown 标记映射成语法** 的那一层,不是另一个语言。
|
||||
|
||||
---
|
||||
|
||||
@@ -11,19 +15,18 @@
|
||||
|
||||
| 层 | 形态 | 角色 |
|
||||
|----|------|------|
|
||||
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
|
||||
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
|
||||
| **叙述面** | 普通段落 | 注释;行内 `` `名` `` 可声明/引用;装饰性 `**强调**` / `*斜体*` 不执行 |
|
||||
| **Marqdo 可执行面** | 结构标记 + **`**代码**`** + **`*返回*`** | 本语言程序 |
|
||||
| **外联面** | ` ```lang ` | 其它语言(FFI) |
|
||||
|
||||
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
|
||||
输出属于可执行面里的**函数调用**(`> print …` / `**print …**`),见 [keywords.md](keywords.md)。
|
||||
|
||||
### 成段注释
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
|
||||
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
- 段首行:首字符非标记 → 注释段;段内续行一律叙述(即使以 `` ` `` / `-` 开头)。
|
||||
- 段内仍扫描行内可执行位:`` `名` ``、代码形 `**…**`、返回形 `*…*`。
|
||||
- 叙述段与独立结构行(`>` `#`)之间**建议空一行**,否则 `> print` 可能被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
@@ -31,8 +34,8 @@
|
||||
|
||||
| 标记/形式 | 角色 | 是否架构级 |
|
||||
|-----------|------|------------|
|
||||
| `*…*` | 程序语句 | 是 |
|
||||
| `**…**` | 返回值 | 是 |
|
||||
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
|
||||
| `**…**` | 代码(赋值 / 调用 / 表达式语句) | 是 |
|
||||
| `*…*` | 返回值(整行、`返回*n*`、或表达式形) | 是 |
|
||||
| `****` / 整行 `**` / `*None*` | 空返回 + 结束函数体 | 是 |
|
||||
| `> print …` | 打印副作用 | 否(内置函数) |
|
||||
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
|
||||
| 函数体 `---` / `***` | 叙述分隔(跳过,**不**结束函数体) | 否 |
|
||||
@@ -0,0 +1,64 @@
|
||||
# 集合取元:GFM 链接形
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active(运行时)** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 相关 | [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 决议
|
||||
|
||||
表达式取元的**主语法**为 Markdown 链接外形,与 foreach 同构:
|
||||
|
||||
| 角色 | 写法 |
|
||||
|------|------|
|
||||
| **取元(表达式)** | `[键](集合)` |
|
||||
| **遍历(语句)** | `- [项](集合)`(不变) |
|
||||
| **脚注取元(过渡)** | `` 集合[^键] `` 仍解析,新代码勿写 |
|
||||
|
||||
心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
|
||||
|
||||
```markdown
|
||||
**价 = [拿铁](菜单)**
|
||||
**价 = [`名`](菜单)**
|
||||
**第一 = [1](篮子)**
|
||||
|
||||
- [行](今日订单)
|
||||
**名 = [品名](行)**
|
||||
```
|
||||
|
||||
## 2. 细则
|
||||
|
||||
| 写法 | 语义 |
|
||||
|------|------|
|
||||
| `[拿铁](菜单)` | 静态键;`菜单` 为变量(粗体/斜体内) |
|
||||
| `` [`名`](菜单) `` | 动态键(求值 `名` 再作键) |
|
||||
| `[1](篮子)` | List **1-based** 下标(同脚注约定) |
|
||||
| `[1]([苹果](货架))` | 嵌套链式 |
|
||||
|
||||
与 `- [项](集合)` 消歧:仅 **表达式位置** 的 `[…](…)` 为取元;`-` 行头仍为 foreach。
|
||||
|
||||
## 3. 迁移
|
||||
|
||||
`` `菜单`[^拿铁] `` / `菜单[^拿铁]` → `[拿铁](菜单)`(**基与键左右对调**)。
|
||||
|
||||
| 区域 | 约定 |
|
||||
|------|------|
|
||||
| 新代码 / examples / public | **只用**链接形 |
|
||||
| `tests/structure/footnote*` · `interp-footnote*` | 脚注兼容门禁(保留) |
|
||||
| 其余 structure / ext / lib 金样 | 已迁链接形 |
|
||||
|
||||
脚注路径保留至另行决定移除之日;Skill / 教程 / 新示例只用链接形。
|
||||
|
||||
## 4. 非目标
|
||||
|
||||
- 点号 map 访问、`在`、箭头取元、`(键)[集合]`
|
||||
- 循环语法糖(`←` / `in` / 自然语言)
|
||||
|
||||
## 5. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿并落地主语法 |
|
||||
@@ -0,0 +1,49 @@
|
||||
# 核心表面清单(core-surface)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
|
||||
| 日期 | 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` |
|
||||
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
|
||||
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [说明](遍历 集合 为 项)`;描述不是绑定变量名 | `tests/structure/loop.mq.md` |
|
||||
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
|
||||
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
|
||||
| `hr` | 单行 `---` 或 `***` | 叙述分隔 | **不收束函数**(返回才收束) | `tests/markup-v03/module-hr.mq.md` |
|
||||
| `writeback` | `<!-- marqdo-out … -->` | 持久化输出 | 只读回放,不执行 | `tests/lib/writeback-get.mq.md` |
|
||||
|
||||
## 2. 内联标记
|
||||
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 粗体内代码判别序:赋值 → 调用 → 表达式;不取消调用行、返回等其它显式执行入口 | `tests/markup-v03/multi-bold.mq.md` |
|
||||
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
|
||||
| `link-index` | `[描述](表达式)` | 描述包裹 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`)
|
||||
|
||||
行级入口只有四个大类:`Blank` / `Comment`(叙述段落,含软强调与行内 `` `名` ``)/ `Writeback` / `Code`(`# * > + - | ~ $` 或数字开头)。本清单第 1 节的行构造是在 `Code`(及 `Comment`/`Writeback`)内部的**语义细分**;第 2 节内联标记由 `src/parse/prose.rs` 行内扫描产出。两层合起来 = 核心表面全集。
|
||||
|
||||
## 4. 范围外(进 Language 层,但不在本守卫)
|
||||
|
||||
frontmatter / Artifact Metadata(元信息)、`import` 行(模块装载)、以及 Metadata 内的 **Binding Expression**(`${ns.name}`,见 [binding.md](binding.md) · [ADR 0006](../adr/0006-artifact-metadata-binding.md))属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,**暂不进本清单守卫**(不增 CORE_CONSTRUCTS 计数)。Phase 2 将已绑定 metadata **提升为入口普通变量**(仍非新标记)。如需一并守卫,走 ADR 扩表。
|
||||
@@ -80,8 +80,11 @@ 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` |
|
||||
| **getrandom** (=0.2.17) | OS 熵 | Mid M3 `lib/secrets` |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
|
||||
@@ -0,0 +1,284 @@
|
||||
# Marqdo 文档原生开发指导:让知识的表达、执行与复用成为同一件事
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | 下一阶段开发指导与规划修订;不表示下述目标接口已经实现 |
|
||||
| 日期 / 审阅基线 | 2026-10-23 / `main`,`7674ebb`;继承缺口审计的 `434be9f` 代码证据 |
|
||||
| 原始意图 | [009](../next/009.md)、[附属设计](../next/Marqdo_Executable_Knowledge_Design.md)、[附属示例](../next/Marqdo_Executable_Knowledge_Example.md) |
|
||||
| 配套实施文件 | [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)、[缺口与交付路线](../roadmap/executable-knowledge-gaps-2026-10-23.md) |
|
||||
| 本轮边界 | 校正开发方向、作者体验、AI 工作协议和验收;不新增语法,不宣称实现新能力 |
|
||||
|
||||
## 1. 审阅结论与规范关系
|
||||
|
||||
Marqdo 的优势不在于给传统程序换一套 Markdown 符号,而在于:**读者解释知识、作者修改知识、程序执行知识、AI 查找并复用知识,能够指向同一份有结构的文档和其中的同一步。** 标题、叙述、表格、链接描述、输入输出、来源及执行行为不应分散在彼此手工同步的系统中。
|
||||
|
||||
现有规划没有放弃这一目标,但工程排序存在偏移:把身份、图、证据、锁、句柄、晋升全部铺完,再验证人和 AI 是否更容易使用。这样可能交付一个功能齐全的制品管理系统,却让文档作者承担另一套注册、声明、审核和配置工作。需要改变交付方法,不必推翻确定性编译、绑定和权限机制。
|
||||
|
||||
本指导规定**为何开发、作者维护什么、怎样证明值得开发**;详细规范规定语义模型与执行约束;路线图规定当前缺口、切片与完成证据。三者不是三套平行设计。遇到冲突,依次采用:`009` 的产品意图 → 本指导对作者负担、场景分级和交付次序的修订 → 详细规范的工程规则 → 附属概念示例。当前代码与测试证明“已实现什么”,不能把代码局限升级为永久语言禁令;原始讨论保留,不据其重新引入已被否决的方案。
|
||||
|
||||
### 1.1 方向修订清单
|
||||
|
||||
| 容易偏移的做法 | 修订后的要求 | 必须保留的技术约束 |
|
||||
|---|---|---|
|
||||
| 先做完整知识治理平台,再给作者使用 | 从一篇可读、可运行、可定位步骤的文档交付,逐层扩展 | 每个已支持路径都有准确的目标和效应边界 |
|
||||
| 为进入知识库再写 YAML、注册表和索引 | 从源码推导;只有不能推导的领域事实才需作者补充 | 生成物有版本,可重建,可检查来源 |
|
||||
| 所有逻辑先封装成可登记函数/类 | 一次性逻辑直接写;需要命名、解释或复用时逐步提取 | 作用域、形参、返回与副作用明确 |
|
||||
| 所有调用先审核、锁定、签发远程凭据 | 本地探索、项目复用、严格业务、远程执行分级 | 精确目标、运行时权限不能被标签或模型绕过 |
|
||||
| AI 只能搜文档、填工具参数 | AI 可以读步骤、组合、选择候选、局部修改、提取和验证 | 模型的选择必须转成显式目标,由编译器校验 |
|
||||
| 为“独特”拒绝普通调用或新增更多标记 | 保留简单 payload;让 Markdown 结构提供程序之外的信息 | 无第二套表达式文法,无裸词隐式执行 |
|
||||
| 核心构造数量不增长就是简单 | 同时检查上下文例外、记忆负担和诊断成本 | 新构造需 ADR;不靠把新规则藏进旧构造绕过审查 |
|
||||
|
||||
### 1.2 四个不能互相替代的完成条件
|
||||
|
||||
1. **读得懂**:不打开生成图,也能从源文件看出目的、关键步骤、参数角色和限制。
|
||||
2. **执行同一件事**:标签表达意图,payload 决定计算;运行 trace 能回到源码步骤,不能执行另一个同名目标。
|
||||
3. **改得动**:人或 AI 能修改一个明确步骤,看到影响与验证结果,不必重写整份文档或同步多份签名。
|
||||
4. **复用得对**:找到已有能力后实际调用它;不满足条件时给出具体拒绝原因,而非用复制源码掩盖失败。
|
||||
|
||||
“更适合 AI”是待验证的产品假设,不是 Markdown 文件后缀自动赋予的性质。正确性和作者成本优先于 token 下降;错误复用更便宜不算优化。
|
||||
|
||||
## 2. 语法审查的保留、修正与暂缓
|
||||
|
||||
以下裁决针对审查结论的适用范围,不重写历史实验记录。旧文档中的原型、性能数值和当时的 `Value`/AST 限制,不能直接当作 v2.1 的规范或测试结果。
|
||||
|
||||
| 审查材料 | 保留的洞见 | 需要修正的外推 / 本轮处置 |
|
||||
|---|---|---|
|
||||
| [函数即命名](function-as-naming-philosophy.md) | 从正文计算出发,命名应降低理解和复用成本;避免无意义包装 | “具名给值缺失”是历史观察,当前有具名参数;替换模型是教学解释,不意味着禁止递归、前向引用或必须文本展开 |
|
||||
| [方括号作为标签](bracket-as-label-evaluation.md) | 描述与 payload 共址;标签帮助解释、检索和拆步骤 | Classic 冲突是迁移历史,不据此恢复默认 `[键](集合)`;不强制每个常量或子表达式都有标签 |
|
||||
| [圆括号与可读调用](paren-call-and-readable-invocation.md) | 调用标记应明确;保留 `f(args)` 的局部可读性 | 原型撤回不代表现有版本缺少该能力;Marqdo 的独特性不依赖消灭熟悉的表达式形式 |
|
||||
| [从标记推导调用](call-syntax-from-marks.md) | 语义成分有明确标记;自然语言是连接与解释,不参与猜测调用 | 持久跨文档接口优先具名实参;短而稳定的位置参数仍合法。推断参数的声明次序变化属于接口变化,不承诺任意润色都无影响 |
|
||||
| [环境参数](ambient-parameters-evaluation.md) | 参数来源应可见,避免调用者隐式环境影响复用 | 文档顶部已否决 L0 裸“执行”触发,正文旧建议不能重新生效;文件级常量也须有明确绑定与依赖,不变成动态作用域 |
|
||||
| [函数作为值](functions-as-values-evaluation.md) | 区分名称数据、一等函数、有限查表;避免无需求增加核心复杂度 | “匿名函数必不能索引”“动态调用必然破坏契约”不是普遍定理。将来可研究稳定节点身份与运行时契约;本轮不引入闭包,也不永久禁止 |
|
||||
| [函数作为表格](function-as-table-semantics.md) | 数据表几何有既定含义;契约表不可另造一份参数声明 | 不把表格全部变成函数,也不把“现有实现不支持”写成“表格不能计算”;有限决策表先评估库方案,只有明确角色和歧义测试后才讨论语言扩展 |
|
||||
| [核心表面](core-surface.md)、[分层](layers.md) | 核心小、标记可解释、构造有测试与准入流程 | 清单中的旧取元/循环说明需随迁移更新;固定数量不等于低认知成本,守卫通过也不证明文档语义正确 |
|
||||
| [链接设计](link-syntax.md)、[告警疲劳](warning-fatigue-control.md) | 单一 payload 文法;标签漂移可提示;默认安静、按需严格 | 标签不是纯粹可丢弃的注释,也不是事实证明;不做每次运行重复的批准仪式,不靠词汇相似度证明描述与代码一致 |
|
||||
|
||||
### 2.1 继续冻结的语法边界
|
||||
|
||||
- 默认 `[]()` 是描述包裹 payload;旧取元只能在显式历史兼容路径下解释。现行取元用 `access(...)` 等已支持形式;循环使用明确遍历载荷。
|
||||
- `[]()` 不等于“仅函数调用”:计算、取元、调用、遍历、叙述引用都需要各自语义角色,不能只收集 call 边就宣称完成知识步骤。
|
||||
- 正文引用与可执行位置有不同调度权限。普通句子不因出现“执行”“发送”或工具名而运行;正文解析成引用也不自动求值。
|
||||
- 不把所有 `#` 解释成某种知识对象,或把继承悄悄变成实例关系。标题的既有语义必须兼容,IR 可区分 Type、Entity、Fact、Function。
|
||||
- 不给同一参数增加正文声明、签名表、工具 schema 三套作者真相。规范签名和工具 schema 是投影;契约表补充类型、约束和说明,不偷偷增加形参。
|
||||
- 可读源文件是硬要求;普通 Markdown 渲染器是否把含空格/嵌套表达式的链接渲染成可点击链接是另一件事。不能承诺全部标准渲染器理解执行语义。
|
||||
|
||||
### 2.2 哪些编辑不能当成“只是改文案”
|
||||
|
||||
不含语义标记的普通叙述润色,应保持执行结果和实现摘要;标签改名应保留 payload 行为,但更新展示/检索内容。反引号声明、首次出现顺序、标题名称/层级、粗斜体、表格几何、契约、来源和适用范围的改变则可能影响程序或知识可信性。编辑器必须展示真实差异,不能统一标为 prose-only。
|
||||
|
||||
标签漂移诊断应说明“描述或实现可能需要复核”,不能自动替作者改写业务意图。自然语言一致性检查可作辅助建议,确定性检查仍需可定位的符号、类型、契约或测试证据。
|
||||
|
||||
## 3. 作者工作流:先写清楚,再获得复用能力
|
||||
|
||||
### 3.1 一次性计算不需要预先建知识模型
|
||||
|
||||
下面是当前默认语法的完整最小程序。无模式开关、无项目注册、无知识 ID、无锁文件。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这是演示订单,单价与数量直接写在计算处。
|
||||
|
||||
**小计 = [两件商品的小计](2 * 30)**
|
||||
> print text=`小计`
|
||||
```
|
||||
|
||||
可读意图和精确计算共址。这个标签值得保留,因为它说明本次计算的业务角色;不要求把 `2`、`30`、乘法分别命名。
|
||||
|
||||
### 3.2 需要解释或复用时才提取命名能力
|
||||
|
||||
```markdown
|
||||
## 商品小计
|
||||
|
||||
根据购买数量`数量`和商品单价`单价`计算小计。
|
||||
|
||||
*[按数量与单价计算](数量 * 单价)*
|
||||
|
||||
# main
|
||||
|
||||
计算同一笔演示订单。
|
||||
|
||||
**小计 = [两件商品的小计](商品小计(数量=2, 单价=30))**
|
||||
> print text=`小计`
|
||||
```
|
||||
|
||||
两个完整程序在本轮本地现有 `target/debug/marqdo` 上分别以 Tree 和 Bytecode 执行,均输出 `60`。这仅验证基础语法,不证明步骤身份、重构工具或 Agent 闭环已经实现;也不是全仓测试报告。可将各块保存为 `.mq.md` 后用 `marqdo run 文件 --backend tree` / `--backend bytecode` 复核。
|
||||
|
||||
**后续工具目标**:从选中表达式提取为标题单元,推导自由变量为参数、保持求值顺序与 effect 次数、生成具名调用,并给出可审阅补丁。反向内联也应保留契约和来源关联;无法证明安全的捕获变量、递归、控制流、动态目标或有副作用表达式,先拒绝自动变换并说明原因,不伪称等价。
|
||||
|
||||
### 3.3 跨文档复用与事实说明分别增长
|
||||
|
||||
当第二篇文档需要这段计算,才提取模块并显式 import;不要为十行单文件强制创建 `corpus/knowledge/apps` 目录树。项目索引按约定发现,明确边界或外部来源时再加入配置。
|
||||
|
||||
当“商品小计”依赖政策、时间、币种等条件,再就地补契约与来源。简单乘法不要求假造现实来源;“某商店当前折扣为九折”则不能仅凭函数返回 `0.9` 声称真实。
|
||||
|
||||
正文可以说明结果为何成立,目标是引用同一能力和同一次受控执行的结果,而非手抄另一份公式。正文引用 AST、结果投影和绑定身份尚需开发;完整业务链使用[目标示例](../next/Marqdo_Executable_Knowledge_Example.md)验收,不把它冒充当前全部可运行的教程。
|
||||
|
||||
### 3.4 维护时看到知识变化,而不只是文件变化
|
||||
|
||||
目标维护流程:修改上游规则 → 显示受影响的计算、正文陈述和消费者 → 执行相关测试 → 展示结果/证据/接口各自变化 → 按使用策略接受更新。普通显示文案变更不应触发全库业务审批;证据过期也不必使无关纯工具全部失效。
|
||||
|
||||
## 4. 人维护语义,编译器维护机械关联
|
||||
|
||||
| 信息 | 作者责任 | 编译器 / 工具责任 |
|
||||
|---|---|---|
|
||||
| 目的与步骤 | 有帮助的标题、叙述、标签;避免空泛重复 | 保留源位置和层级,生成步骤投影,不要求手工节点注册 |
|
||||
| 输入输出 | 一份参数来源和必要契约;领域单位不能靠猜 | 推断规范签名、检查调用、生成 schema 和签名视图 |
|
||||
| 目标与依赖 | 显式 import、可读名称、必要消歧 | 绑定唯一 SymbolId,生成依赖边与闭包;不要求手写 ID |
|
||||
| 效应 | 扩展作者声明宿主能力;业务作者必要时收窄允许范围 | 汇总直接及传递效应;未知不得推断 pure;运行时执行能力上限 |
|
||||
| 事实与来源 | 原始资料、范围、有效期、人工审阅等不可推导信息 | 关联来源、记录验证事件、传播失效;不将文件路径视为事实证明 |
|
||||
| 身份与版本 | 有意移动/更名时确认必要迁移 | 区分身份与内容摘要;报告歧义,不靠猜测维持假稳定 |
|
||||
| view / AI 索引 | 不维护第二份可执行描述 | 同一语义模型投影;显示生成代、验证政策和缺失字段 |
|
||||
|
||||
生成信息不等于免费:首次编译、缓存修复、错误定位都要可理解。失败时应回到源文档中可修改的位置,而不是只报内部 Artifact 字段名。
|
||||
|
||||
稳定身份要诚实:同一次编译内引用和 trace 必须一致;普通文本编辑不应打乱无关节点;复制相似步骤、跨文件移动等无法唯一识别时,要求确认迁移或明确生成新身份。禁止用文本相似度悄悄继承已审核的知识身份。
|
||||
|
||||
## 5. AI 原生工作协议:读步骤、改步骤、验证步骤
|
||||
|
||||
本节是**待实现的协议约束**,不是新增 CLI 命令清单。优先扩展现有 MLSP、view、EKC 和 Agent 工作簿,不另造一套 Agent 框架或知识库。
|
||||
|
||||
### 5.1 发现后的最小上下文包
|
||||
|
||||
一次检索返回可展开的上下文卡,而非强制倾倒整个文件或只给函数 schema:
|
||||
|
||||
1. 标题路径、任务相关叙述、标签和精确源码片段;
|
||||
2. SymbolId/步骤节点、source span、源码摘要、生成代;
|
||||
3. 输入角色、返回、单位、默认值和适用条件;
|
||||
4. 直接依赖、效应、必要来源及分层验证状态;
|
||||
5. 支持该能力的例子/测试,相关失败经验、禁用条件和替代能力;
|
||||
6. 还缺哪些检查、能否在当前 policy 下运行、为何被拒绝。
|
||||
|
||||
来源不可用、字段未推导、上下文被截断都须显式标识。按预算可展开依赖,但不能悄悄省略改变适用性或权限的重要信息。原始资料及标签是内容,不是可以覆盖 Agent 策略的指令。
|
||||
|
||||
### 5.2 复用、适配、新建的分界
|
||||
|
||||
- **REUSE**:AI 可根据任务选候选,提交精确目标与输入;resolver 确认目标、契约、适用性、版本和 effect,执行既有制品。复用不靠“没有生成文件”推断,必须有实际调用 trace。
|
||||
- **ADAPT**:已有能力接近但不适用;说明差异,保留依赖/来源关联,在局部副本或补丁中改变必要部分,再验证。不为了通过测试改写原始来源或放宽全局策略。
|
||||
- **CREATE**:没有合适候选或明确需要新语义;记录检索范围和失败原因,在任务预算及写权限允许时新建。不能把检索服务故障当作“仓库没有能力”。
|
||||
- **ASK / STOP**:缺业务决策、权限或关键证据时报告具体缺口。编译器无法决定的真实意图不交给近似匹配默默补全。
|
||||
|
||||
AI 并非只能发现和解释。它可以提出精确目标、组合已有能力、改进表达、重构及补测试;不能以自然语言自报正确来替代执行验证,也不能把含糊名称传给后端任意选一个目标。
|
||||
|
||||
### 5.3 局部修改的事务边界
|
||||
|
||||
编辑请求至少携带目标文件/节点、期望源码摘要、补丁范围和预期行为变化。应用前检查摘要,源已变化则重新定位和审阅,不覆盖用户改动。应用后重新解析受影响文档,生成语义 diff:参数/返回、目标、effect、控制流、证据与依赖是否改变。
|
||||
|
||||
对“只改措辞”请求,检测到接口或实现改变时停止自动合并;对“改计算”请求,运行相关正负例并展示影响。原始文本、格式与未知 metadata 尽量保留,不通过整篇重生成来完成一行修改。禁止修改生成图伪装修复源码。
|
||||
|
||||
首个试点只支持可确定定位的纯计算步骤与普通函数,不等待通用 AST 编辑器、跨项目事务或完整知识治理。安全拒绝超范围输入也属于验收。
|
||||
|
||||
### 5.4 解释和负知识必须有落点
|
||||
|
||||
解释结果应关联到“哪一步、用了哪个目标、哪些输入、哪份来源、哪次验证”,区分已执行观察和模型推断。运行 trace 可以证明程序路径,不能证明任意自然语言论证正确。
|
||||
|
||||
失败经验需要保存适用范围、触发条件、关联能力、原因与失效时间/版本。例如“此折扣不适用于退款”应在查询定价能力时可见,而不是埋在另一份聊天记录里。先由普通文档与结构化关联承载,不先新增通用推理语言;过期负知识也要撤销,不能永久拦截修复后的能力。
|
||||
|
||||
## 6. 渐进严格:不把治理门槛塞进每一行正文
|
||||
|
||||
下面是目标政策分级,不是当前已有四种 CLI 模式。政策由项目/宿主配置和调用上下文选定,源文档保持同一种语法。
|
||||
|
||||
| 场景 | 必需条件 | 默认不要求 |
|
||||
|---|---|---|
|
||||
| 本地探索、单文件运行 | 明确语法与目标、已有运行时契约、宿主能力限制;如实显示未知状态 | lock、来源、ready 晋升、远程签名句柄 |
|
||||
| 项目内自动复用 | 精确绑定、输入/适用性检查、效应许可、状态满足所选政策、执行 trace | 所有纯工具都有人审证据、每次独立确认 |
|
||||
| 严格业务/可复现任务 | 相关依赖与证据锁定、必要验证新鲜度、受控环境和审计;明确不可重放部分 | 对无关文案变化重审整个项目 |
|
||||
| 远程/多租户/不受信调用方 | 上述相关约束,加可信授权主体、范围、服务端能力上限、撤销/期限与防伪设计 | 把客户端提交的 `allow_effects` 当授权本身 |
|
||||
|
||||
`ready` 是“对某项 policy 和输入/上下文已具备复用条件”,不是永久万能认证。未验证的本地草稿可以被检索、查看和按明确权限试跑;不能冒充满足严格政策的可复用事实。测试通过与事实证实分别报告。
|
||||
|
||||
正文 `check/view static` 不执行外部效应。用户主动打开的纯预览可复用项目或会话已有政策,不要求每个链接弹窗;effectful 运行始终受宿主能力和明确执行上下文控制。锁和摘要是完整性机制,不自动等于远程授权;可信本地引用无需先搭建凭据服务。
|
||||
|
||||
## 7. 交付切片:每片都有文档作者与 AI 能看见的结果
|
||||
|
||||
编号与[缺口路线图 §7](../roadmap/executable-knowledge-gaps-2026-10-23.md#7-依赖顺序与可合并切片)一致;G 编号沿用现状证据,M0–M6 保留为工程能力映射,不再被理解为必须全部串行完成的墙。
|
||||
|
||||
### S0 作者基线与最小语料
|
||||
|
||||
- 选定单文件计算、提取函数、两文档引用、表格取元/遍历、业务政策及拒绝复用六类任务;记录当前写法、输出、诊断和作者重复维护项。
|
||||
- 优先整理 `doc/README`、核心语法卡片、教程与运行示例的版本状态;不要先扩展通用库数量。
|
||||
- 为最小样例建立无网络门禁。100 单元及更大语料逐步增长,不阻塞首个可读文档切片。
|
||||
- 完成证据:别人按当前入口能写出正确默认语法;已实现与预期失败分开报告,不能把待实现测试跳过计为成功。
|
||||
|
||||
### S1 可读步骤与唯一目标
|
||||
|
||||
- 主要落点:`src/parse/`、`src/ast.rs`、`src/sema/`、`src/knowledge/compile.rs`、`src/view/`。
|
||||
- 在最小故事内联合完成 G01/G03:保留 label、payload、上下文和跨度;每类步骤有输入输出与依赖投影;旧 EKC 查询索引不再覆盖语义图。
|
||||
- 普通导航、正文引用、可执行表达式、循环分别处理,正文保持惰性。先确保支持范围内同一引用在源码、view、图中是同一个目标,再扩展覆盖范围。
|
||||
- 完成证据:作者能从渲染步骤返回对应源码;同名目标不误连;计算/取元/循环不是伪造的 call;重复构建可对照;未支持上下文明示。
|
||||
|
||||
### S2 确定执行与早期 AI 复用试点
|
||||
|
||||
- 主要落点:`src/sema/`、`src/interp.rs`、`src/bytecode/`、`src/mlsp.rs` 与现有 Agent 入口。
|
||||
- 完成静态普通函数、显式 import、关联函数的 BoundCall 主链;G02 与 G06 的效应安全下限不可延期。小范围可先用明确纯操作白名单,未知路径必须拒绝纯证明,而非猜 pure。
|
||||
- 实现最小上下文卡与本地绑定引用;以 stub/no-LLM 测试验证协议,然后用现有 Agent 跑相同故事。无需先完成远程鉴权平台或全面来源审核。
|
||||
- 完成证据:同一需求实际调用既有函数,不新增同义实现;两个后端 trace 对上图中目标;改目标、错误输入、未知效应、权限不足不能静默执行。
|
||||
|
||||
### S3 局部编辑、提取与库可读性
|
||||
|
||||
- 主要落点:MLSP 编辑/定位、相关 sema/检查入口、`lib/`、`ext/`、教程与测试。
|
||||
- 按 §5.3 实现受摘要保护的局部修改和语义 diff;实现受限纯表达式提取,或明确标为待实现,不用人工演示冒充工具能力。
|
||||
- 迁移标准库/扩展时删掉重复包装与噪音标签,保留有意义的业务步骤、契约和负例;中英镜像含义一致。兼容旧调用接口,不用增加旧语法解释救迁移遗漏。
|
||||
- 完成证据:同义润色不改执行;改反引号声明能检测签名变化;表达式提取前后结果/effect 次数一致;冲突补丁拒绝;CLI、库、扩展与 view 既有能力继续通过。
|
||||
|
||||
### S4 业务知识的来源与适用性
|
||||
|
||||
- 主要落点:契约、SourceRef/VerificationRecord、验证事件、Agent 候选解释;完成 G05 与 G07 的项目政策部分。
|
||||
- 选定书店案例的币种、数量边界、会员范围与政策有效期;给 schema、拒绝诊断及可运行负例,不泛化为全能业务规则语言。
|
||||
- 同步补齐传递效应与相关负知识;生成契约/状态展示,减少作者重复填写。
|
||||
- 完成证据:同一计算因输入或证据不同而正确通过/拒绝;来源过期不被 `tests=passed` 覆盖;普通纯工具无需虚构 SourceRef。
|
||||
|
||||
### S5 变化传播与严格复用
|
||||
|
||||
- 主要落点:`src/sema/lock.rs`、图/impact、产物提交与消费者;完成 G04/G08 和严格 handle 复核。
|
||||
- 区分身份/接口/实现/证据/闭包,给出可读升级 diff;整代快照保证消费者不会读取混代数据。并发读写一旦开放,该一致性就是前置条件,不能等到此片才承认风险。
|
||||
- 完成证据:修改依赖政策后,下游计算和正文解释进入影响集合;文案变化不误判实现变化;并发编辑或构建崩溃不导致错目标执行;锁不声称重放网络/随机/LLM。
|
||||
|
||||
### S6 生态验收与发布
|
||||
|
||||
- G10/G11 从 S0 起每片执行;S6 汇总兼容矩阵、真实工作流和打包后冒烟,不把测试留到最后。
|
||||
- G12 随实际规模需求推进;远程凭据/多租户是有条件的独立交付。它们不阻塞受信本地试点,也不得被本地通过的测试覆盖为“已安全支持”。
|
||||
- 完成证据:当前默认语法的 lib/ext/CLI/MLSP/view/WASM 等受影响消费者有明确结果;目标示例中的已发布子集实际可运行,未发布部分保留状态;发布声明与证据一一对应。
|
||||
|
||||
## 8. 验证 Marqdo 优势,而不只验证组件存在
|
||||
|
||||
### 8.1 必须收集的产品指标
|
||||
|
||||
| 维度 | 记录方法 | 失败信号 |
|
||||
|---|---|---|
|
||||
| 作者负担 | 完成同一任务所需手写声明、重复字段、配置、跳转和确认次数 | 简单本地算式也必须填写制品清单 |
|
||||
| 阅读与定位 | 给定问题,定位正确步骤/限制的准确率、耗时与上下文量 | 只看 label 会误导,必须打开生成 JSON 才理解源文档 |
|
||||
| 可修改性 | 修改范围、无关 diff、语义变化检测率、冲突覆盖数 | 为改一步而重生成全文件;措辞调整偷偷改变接口 |
|
||||
| 复用质量 | 已有能力发现率、实际调用率、重复实现率、误用率 | 检索命中却重新写代码;正确拒绝算成任务失败而被优化掉 |
|
||||
| 知识可追溯性 | 结果关联目标、步骤、输入、来源和验证的覆盖率 | `tested` 被当作事实正确;解释引用未执行的步骤 |
|
||||
| 总成本 | 正确完成任务的 token、工具调用、轮次、总耗时及编译成本 | 只报模型 tokens,隐藏额外注册/审核/修复成本 |
|
||||
|
||||
### 8.2 对照实验与门槛
|
||||
|
||||
1. 固定任务、可访问能力、输入数据、模型版本、工具能力、预算与超时;比较普通 Markdown+代码/RAG、当前 EKC 和新方案。不能给新方案更多现成实现再声称语法更优。
|
||||
2. 任务包括成功复用、同名冲突、近似但不适用、未知 effect、过期来源、正文不执行、局部修改及库升级。加入自然语言诱导绕过 policy 的负例。
|
||||
3. 先测确定性协议,再测多次 AI 运行,保留种子(支持时)、原始 trace、版本、失败样本与分布;小样本不夸大收益。
|
||||
4. 正确目标、无越权和正文无外部 effect 是硬门槛。原有兼容测试不得降低;效率阈值先测基线再登记,不捏造提升百分比。
|
||||
5. 若作者负担增加或误用率上升,回到交互/语义设计分析原因,不能只用“更多治理更安全”或“模型更便宜”解释过去。
|
||||
|
||||
### 8.3 发布声明分层
|
||||
|
||||
- “支持新语法”需语法、迁移、双后端与库兼容证据,不意味着完整知识复用已经交付。
|
||||
- “本地确定性知识复用”需 S1/S2 支持范围内的端到端与拒绝用例;范围外路径显式不支持,不能回落为模糊执行。
|
||||
- “严格业务知识复用”还需相关 S4/S5 来源、适用性、失效、锁和一致性证据。
|
||||
- “安全远程知识执行”需额外的授权、能力上限、凭据/撤销及隔离测试;本地 JSON handle 不等于远程安全。
|
||||
|
||||
## 9. 每个开发变更必须回答的问题
|
||||
|
||||
提交设计或实现时给出一份短而具体的审阅记录:
|
||||
|
||||
- 用户要读/写/改/复用的知识是什么?附源文档前后对照,不只给内部结构图。
|
||||
- 利用了哪种文档原生信息?若只增加通用框架能力,与主线的必要关系是什么?
|
||||
- 新增了哪些作者必须手工维护的信息?为什么不能从现有语义推导?
|
||||
- 是否改变标记、作用域、求值顺序、形参顺序、表格几何或正文安全?分别有哪些测试?
|
||||
- 人、CLI、view、图和 Agent 是否看到同一目标与状态?失败能否回到源码修复?
|
||||
- AI 的正确复用/局部编辑如何证明?哪些部分仍需模型判断,哪些由编译器决定?
|
||||
- 标准库和扩展是否先迁移?是否保住既有公开接口、输出与 effect?
|
||||
- 这是已实现、受限试点还是设计目标?文档和发布声明是否一致?
|
||||
|
||||
**准入原则**:内部可以使用成熟编译器、数据库和协议技术;外部必须减少知识在“说明、程序、索引、工具描述”之间的重复翻译。独特性由这条链的实际收益体现,不由新符号数量或与其他语言不同的程度体现。
|
||||
@@ -0,0 +1,100 @@
|
||||
# Engineering Knowledge Compiler(EKC)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted(v1 已落地)** |
|
||||
| 日期 | 2026-09-28 |
|
||||
| 提案 | [next/008.md](../next/008.md) |
|
||||
| 相关 | [okf.md](okf.md) · [catalog-cli.md](catalog-cli.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
## 1. 定位
|
||||
|
||||
Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识系统。Source of Truth 仍是 `*.mq.md`;`.marqdo/**` 是 GENERATED 投影。
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► Executable + Catalog L0–L4 + Graph + Context Pack
|
||||
│
|
||||
▼
|
||||
Agent preflight (REUSE → ADAPT → CREATE)
|
||||
```
|
||||
|
||||
**Engineering First Information (EFI)**:生成代码前先获得已有能力、约束、决策、失败经验与推荐复用。
|
||||
|
||||
## 2. 五层 Catalog
|
||||
|
||||
| 层 | 内容 | 落盘 |
|
||||
|----|------|------|
|
||||
| L0 Repository | 语言/规模 | `.marqdo/catalog/repository.mq.md` |
|
||||
| L1 Module | imports/exports/responsibility | `.marqdo/catalog/modules/` |
|
||||
| L2 Symbol | signature/calls/fingerprint | `.marqdo/catalog/symbols/` |
|
||||
| L3 Capability | 工程能做什么 | `.marqdo/catalog/capabilities/` |
|
||||
| L4 Knowledge | Decision/Constraint/Failure/… | `.marqdo/knowledge/{decisions,constraints,…}/` |
|
||||
|
||||
既有 `marqdo catalog` 根级 `catalog.yaml` / `index.md` / `modules/` / `concepts/` **保留**;`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。
|
||||
|
||||
## 3. 知识类型(OKF `type`)
|
||||
|
||||
| type | 含义 |
|
||||
|------|------|
|
||||
| `Capability` / `Function` | 能力与符号投影 |
|
||||
| `Decision` | 为什么这样做 |
|
||||
| `Constraint` | 必须/禁止 |
|
||||
| `Failure` / `AntiPattern` | 负面知识 |
|
||||
| `Pattern` / `Migration` / `Fact` | 模式、迁移、事实 |
|
||||
| `Marqdo Context Pack` | Agent 上下文制品 |
|
||||
| `Marqdo Policy` | 复用决议编译结果 |
|
||||
| `Marqdo Engineering Knowledge` | 总览 / `engineering.yaml` |
|
||||
|
||||
未知 type 优雅降级(可读,不专属逻辑)。
|
||||
|
||||
## 4. 图边
|
||||
|
||||
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
|
||||
|
||||
落盘(G01 分离后):
|
||||
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
|
||||
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json` · **`ir.json`**(完整 IR 快照,供查询热路径)
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认;写投影 + ir.json)
|
||||
marqdo knowledge preflight "task" # 暖机读 ir.json;缺图才 compile
|
||||
marqdo knowledge preflight "task" --refresh # 强制全量重编译后再预检
|
||||
marqdo knowledge record REUSE
|
||||
marqdo knowledge learn --task ... --failure ...
|
||||
marqdo find "authentication" # 同上:缺图才 compile;--refresh 强制
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo impact path/to/file.mq.md
|
||||
marqdo conflicts | stale | duplicate [--fail] | verify
|
||||
```
|
||||
|
||||
统一 `--json`。查询类命令(`preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`)默认 **读已编译投影**;CI 或源变更后应先 `marqdo knowledge` 或加 `--refresh`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
|
||||
## 6. Reuse 协议
|
||||
|
||||
三态:**REUSE → ADAPT → CREATE**(硬顺序)。Reuse budget:`min_candidates` / `allow_create_after`。仅 `create_allowed: true` 时允许盲生成。
|
||||
|
||||
## 7. Context Pack
|
||||
|
||||
`.marqdo/agent/contexts/task-<id>.mq.md`:Task / Existing Capabilities / APIs / Constraints / Decisions / Failures / Recommended / Forbidden。
|
||||
|
||||
## 8. Agent
|
||||
|
||||
- Plugin:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`
|
||||
- Facade:`agent.preflight` · `agent.eng_reuse` · `agent.eng_record`
|
||||
- `agent.plan … eng_preflight=True` 在 agent-kb 之前跑 EFI;缺知识图时 `missing_knowledge` 放行(兼容纯 agent-kb 测试)
|
||||
|
||||
## 9. 指标
|
||||
|
||||
`.marqdo/agent/episodes/reuse_metrics.json`:`reuse_ratio` / `adapt_ratio` / `novel_ratio` / `duplication_rate`。
|
||||
|
||||
## 10. 原则(五条)
|
||||
|
||||
1. Discover before Create
|
||||
2. Reuse before Adapt
|
||||
3. Adapt before Duplicate
|
||||
4. Verify before Promote
|
||||
5. Code changes update knowledge
|
||||
|
||||
**不做**:以向量库为知识模型;embedding 仅可选检索实现,默认关闭。Hybrid = lexical + symbol + capability + graph。
|
||||
@@ -16,27 +16,17 @@
|
||||
tests/
|
||||
README.md
|
||||
gold.rs # 集成测试入口
|
||||
structure/ # 代码基础结构(Markup 架构)
|
||||
hello.mq.md
|
||||
nested-call.mq.md
|
||||
positional-call.mq.md
|
||||
branch.mq.md
|
||||
loop.mq.md
|
||||
collection.mq.md
|
||||
import/
|
||||
main.mq.md
|
||||
utils.mq.md
|
||||
ns/
|
||||
helpers.mq.md
|
||||
path3.mq.md
|
||||
use.mq.md
|
||||
structure/ # 代码基础结构(Markup 架构 · v0.2)
|
||||
…
|
||||
keywords/ # 关键字与内置名
|
||||
print.mq.md
|
||||
bool-logic.mq.md
|
||||
…
|
||||
markup-v03/ # Markup 映射 v0.3 草案金样例(实现前 ignore)
|
||||
README.md
|
||||
inc-prose.mq.md
|
||||
…
|
||||
ext/
|
||||
agent-run-live.mq.md
|
||||
…
|
||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
||||
ns-instance-method.mq.md
|
||||
…
|
||||
```
|
||||
|
||||
@@ -51,6 +41,7 @@ tests/
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **markup-v03** | v0.3:叙述声明、粗体代码、斜体返回、升参、空返回、双调用面(见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)) | 在 `--markup v0.3` 落地前 `#[ignore]` |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
|
||||
|
||||
@@ -0,0 +1,206 @@
|
||||
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Design Draft · v2.1 语义重构** |
|
||||
| 核心判断 | `[]()` 不是“普通代码”与“知识链接”的分界;每一个 `[]()` 同时是代码、文档和知识图节点。 |
|
||||
| 关联 | [link-syntax.md](link-syntax.md) · [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) |
|
||||
| 示例 | [examples/executable-knowledge/](../../examples/executable-knowledge/) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
> **`[名称](载荷)` 是一个命名的可执行知识步骤:`()` 做原有的任何事,`[]` 说明这一步对人意味着什么;编译器把它们一起编入知识图。**
|
||||
|
||||
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、
|
||||
甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、
|
||||
源位置、输入/输出、依赖和影响范围。
|
||||
|
||||
```text
|
||||
代码投影: eval([名称](载荷)) = eval(载荷)
|
||||
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
|
||||
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
|
||||
```
|
||||
|
||||
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性;
|
||||
三者同源,才是代码即文档、文档即知识、知识即可执行。
|
||||
|
||||
---
|
||||
|
||||
## 1. 统一节点:`Named<T>`
|
||||
|
||||
`[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
|
||||
|
||||
```text
|
||||
Named<T> { label, inner: T, span }
|
||||
```
|
||||
|
||||
`T` 是它出现位置原有的语法节点,绝不另造“知识表达式” parser:
|
||||
|
||||
| 既有位置 | `T` | 示例 | 知识角色 |
|
||||
|---|---|---|---|
|
||||
| 表达式 | `Expr` | `[收件人](at(订单, "收件人"))` | 观测/取值 |
|
||||
| 表达式 | `Expr` | `[含税价](金额 * (1 + 税率))` | 推导 |
|
||||
| 表达式 | `Expr` | `[适用税率](税率.查询(地区, 品类))` | 复用/查询 |
|
||||
| 遍历位置 | `LoopSpec` | `[逐个订单行](遍历 订单.行 为 行)` | 过程/展开 |
|
||||
| 正文位置 | `InlinePayload` | `订单总额为[含税总价](定价.总额(订单))。` | 叙述中的可执行槽 |
|
||||
| URL/路径 | `NavigationLink` | `[税率原文](corpus/tax.md)` | 导航/证据定位 |
|
||||
|
||||
运行时只执行 `inner`;`label` 不进符号表、不改变作用域、不重复计算。与此同时,
|
||||
parse/check/catalog 保留整个 `Named<T>`。所以循环不会被误判成“返回一个事实”,取元也不会
|
||||
被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。
|
||||
|
||||
### 1.1 每个节点都有角色,而不是两套语法
|
||||
|
||||
角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束:
|
||||
|
||||
| role | 如何识别 | `check` 应问什么 |
|
||||
|---|---|---|
|
||||
| `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 |
|
||||
| `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 |
|
||||
| `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 |
|
||||
| `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 |
|
||||
| `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 |
|
||||
| `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 |
|
||||
|
||||
一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖
|
||||
若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。
|
||||
|
||||
---
|
||||
|
||||
## 2. 知识层不是目录隔离,而是同一图的不同投影
|
||||
|
||||
“几层知识”不应把语法和项目切断。它们是同一个 `Named<T>` 图中不同职责的节点;
|
||||
同一份 `.mq.md` 可以同时有多层节点。
|
||||
|
||||
| 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 |
|
||||
|---|---|---|---|
|
||||
| **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? |
|
||||
| **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? |
|
||||
| **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named<Expr>` | 哪个可调用单元给出什么知识? |
|
||||
| **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named<Expr>` / `Named<LoopSpec>` | 如何从已有知识得到新结论/行动? |
|
||||
| **N 叙述知识** | 段落与正文调用槽 | 正文 `Named<InlinePayload>` | 如何把结论说给人或 agent? |
|
||||
|
||||
同一条边可以跨层:`[出生年份](at(人物表, "出生年份"))` 同时是 E 的观测、K 的事实值和
|
||||
可被 N 层引用的节点。`[逐个订单行](遍历...)` 是 D 的过程知识,也为其内部每个推导提供上下文。
|
||||
这正是通用语法本身兼容知识体系的含义。
|
||||
|
||||
### 2.1 `#` / `##` 的位置
|
||||
|
||||
- `#` 给一组知识步骤提供可读命名空间、类型/个体语义和文档边界;
|
||||
- `##` 给可复用步骤提供稳定的公开入口、参数与返回契约;
|
||||
- `[]()` 给入口内部的**每一小步**命名,并将它们暴露给文档、图和工具;
|
||||
- `> 类型` 仍只构造运行时实例;知识个体不等于运行时 map。
|
||||
|
||||
因此 `## 含税总额` 不是黑盒函数:其函数体中的 `[订单行](...)`、`[逐行计税](遍历...)`、
|
||||
`[汇总](sum(...))` 都是可检索、可解释、可追踪的知识步骤。函数是知识单元的边界,
|
||||
`[]()` 是知识单元的内部结构。
|
||||
|
||||
---
|
||||
|
||||
## 3. 大项目的寻址:可读短名与稳定身份同时成立
|
||||
|
||||
全局只靠 `# 李白` 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
|
||||
但这不意味着作者要失去 `李白.出生年份` 的自然语言体验。
|
||||
|
||||
1. 文件的既有 frontmatter `id` 是稳定身份;
|
||||
2. 现有 `import bind:target` 是代码中的规范加载/寻址;
|
||||
3. `#` / `##` 是人可读的路径段;
|
||||
4. 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定 `symbol_id`;歧义必须报错。
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: knowledge.people.li-bai
|
||||
import:
|
||||
li_bai: knowledge/people/li-bai.mq.md
|
||||
---
|
||||
|
||||
# 回答
|
||||
|
||||
**year = [李白的出生年份](li_bai.李白.出生年份)**
|
||||
李白出生于[公元 701 年](李白.出生年份)。
|
||||
```
|
||||
|
||||
第一处是可运行代码,使用显式 import;第二处是正文的发现地址。它们编译后都指向
|
||||
`knowledge.people.li-bai::李白.出生年份`。短地址从来不是“按项目扫描第一个名字”,
|
||||
而是可读的查询,必须由 lock 固化。
|
||||
|
||||
---
|
||||
|
||||
## 4. 每个 `[]()` 产生统一的知识记录
|
||||
|
||||
不要把 LinkInfo 固定成单一的 `target`。任意载荷都可能含有多个读、写、调用和循环依赖:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "逐个订单行",
|
||||
"payload_kind": "loop",
|
||||
"roles": ["iterate"],
|
||||
"source": {"file": "capabilities/order-pricing.mq.md", "line": 22},
|
||||
"inputs": ["订单.行"],
|
||||
"outputs": ["行"],
|
||||
"dependencies": [
|
||||
{"kind": "local_value", "path": "订单.行"},
|
||||
{"kind": "symbol", "id": "capability.order-pricing::订单定价.含税价"}
|
||||
],
|
||||
"effect": "pure",
|
||||
"fingerprint": "sha256:…"
|
||||
}
|
||||
```
|
||||
|
||||
此记录就是统一知识图节点:
|
||||
|
||||
- 本地取元有输入/类型边;
|
||||
- 纯计算有输入/输出/公式边;
|
||||
- 循环有集合、变量绑定和循环体边;
|
||||
- 调用有 `calls`/`uses` 边;
|
||||
- 有来源的事实再增加 `derived_from` 边;
|
||||
- 正文节点有 `narrates` 边,连接它所在句子和计算结果;
|
||||
- 副作用节点有权限/影响目标边,不能被 `view` 或 `verify` 静默执行。
|
||||
|
||||
来源不是每个节点的前提,而是图中的一种边。没有来源的字典取元仍是知识步骤;
|
||||
若它最终支撑对外事实,沿依赖链应能找到来源,否则在“发布/验证事实”时才报证据不足。
|
||||
|
||||
---
|
||||
|
||||
## 5. 闭环:写、跑、看、查、变
|
||||
|
||||
```text
|
||||
作者写 Named<T>
|
||||
│
|
||||
├─ run:擦除 label,按原语义执行
|
||||
├─ view:显示 label,可展开值、输入、步骤和来源
|
||||
└─ check:解析所有依赖,编译统一知识图
|
||||
│
|
||||
catalog / lock / context pack
|
||||
│
|
||||
来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named<T> 与叙述句子
|
||||
│
|
||||
作者或 agent 修复后重新 check/verify
|
||||
```
|
||||
|
||||
### 5.1 命令边界
|
||||
|
||||
| 操作 | 做什么 | 不做什么 |
|
||||
|---|---|---|
|
||||
| `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 |
|
||||
| `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 |
|
||||
| `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 |
|
||||
| `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 |
|
||||
| `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 |
|
||||
|
||||
这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实施顺序
|
||||
|
||||
1. 在表达式、遍历和正文三处统一保留 `Named<T>`;payload 复用各自现有 parser。
|
||||
2. 为任意 `Named<T>` 提取 `inputs`、`outputs`、`dependencies`、`effect`、`roles`;从单 target 演进为依赖集合。
|
||||
3. 让 `#`/`##` 契约为内部步骤提供类型/公开边界;让 frontmatter `id` + import 提供跨文件稳定解析。
|
||||
4. 把现有 EKC 图扩展为步骤图:`observes`、`derives`、`iterates`、`calls`、`acts`、`narrates`、`derived_from`。
|
||||
5. 接入 `check`、`view`、`verify`、`impact` 与 lock;让一次变更能回到具体的 `[]()` 和具体句子。
|
||||
|
||||
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
|
||||
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
|
||||
@@ -61,7 +61,8 @@ Unknown names fail. Queries are only valid during a plugin function call (host s
|
||||
|
||||
```markdown
|
||||
---
|
||||
import plugin:lib/plugin.mq.md
|
||||
import:
|
||||
plugin: lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -85,7 +86,7 @@ cargo build -p marqdo_plugin_agent
|
||||
|
||||
- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
|
||||
- Agent (ABI v2): … **OKF agent-kb** …
|
||||
- Web (ABI v2): HTTP listen + SQLite + page render (`web_listen`, `web_render`, `web_db_*`) — [`plugins/web`](../../plugins/web); used by [`ext/web/web.mq.md`](../../ext/web/web.mq.md). Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
|
||||
- Web (ABI v2): HTTP listen + SQLite/Postgres + page render (`web_listen`, `web_render`, `web_db_*`, …) — [`plugins/web`](../../plugins/web)(**Go 全量重写**,见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) · [ADR 0004](../adr/0004-web-plugin-go.md));作者面 [`ext/web/web.mq.md`](../../ext/web/web.mq.md)。Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
|
||||
|
||||
## Layering
|
||||
|
||||
|
||||
@@ -159,11 +159,12 @@ REPLACE
|
||||
```markdown
|
||||
---
|
||||
title: agent-run-…
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import subtask:lib/subtask.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
json: lib/json.mq.md
|
||||
writeback: lib/writeback.mq.md
|
||||
subtask: lib/subtask.mq.md
|
||||
---
|
||||
|
||||
# 总目标
|
||||
|
||||
+24
-7
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**engineering-knowledge.md**](engineering-knowledge.md)(**EKC / EFI preflight**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
## 0. 为什么要改掉旧方案
|
||||
|
||||
@@ -72,10 +72,11 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
导入 智能体:ext/ai/智能体.mq.md
|
||||
导入 大模型:ext/ai/大模型.mq.md
|
||||
导入 自写回:lib/自写回.mq.md
|
||||
导入 时间:lib/时间.mq.md
|
||||
导入:
|
||||
智能体: ext/ai/智能体.mq.md
|
||||
大模型: ext/ai/大模型.mq.md
|
||||
自写回: lib/自写回.mq.md
|
||||
时间: lib/时间.mq.md
|
||||
---
|
||||
|
||||
## 获取时间
|
||||
@@ -167,8 +168,9 @@ ext/
|
||||
**分层纪律(硬规则,勿破)**:
|
||||
|
||||
1. `ext/**/*.mq.md` **禁止**出现任何 `host_*` / `host_` 调用。
|
||||
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
|
||||
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
|
||||
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …;以及 EKC:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
|
||||
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF / EKC 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
|
||||
4. **Engineering preflight**:`agent.preflight` / `plan … eng_preflight=True` 在 agent-kb 之前解析 REUSE/ADAPT/CREATE(见 [engineering-knowledge.md](engineering-knowledge.md))。缺 `.marqdo` 知识图时返回 `missing_knowledge` 并放行,以兼容纯任务包测试。
|
||||
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
|
||||
|
||||
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
|
||||
@@ -180,11 +182,26 @@ ext/
|
||||
| 中文 | 英文 | 角色 |
|
||||
|------|------|------|
|
||||
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
|
||||
| `## 运行` | `## run` | **v2 主入口**:Adaptive `route` → execute → record episode → maybe_learn(技能 + 策略) |
|
||||
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
|
||||
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
|
||||
| `## 解析` | `## resolve` | 技能解析:exact → alias → canonical → near |
|
||||
| `## 路由` | `## route` | **P4 Adaptive Routing**:`marqdo` \| `small-llm` \| `llm` \| `auto`(`jev` 为 `small-llm` 兼容别名) |
|
||||
| `## 应用路由` | `## route_apply` | 将小模型/大模型路由回复(`SKILL:<slug>` / `EXPLORE`)落到 kb 技能 |
|
||||
| `## 编译策略` | `## compile_policy` | Policy Compilation → `policies/router.mq.md` |
|
||||
| `## 记录情景` | `## record_episode` | 每次执行沉淀为 `.mq.md` episode(`.marqdo/agent-memory/`) |
|
||||
| `## 尝试学习` | `## maybe_learn` | 情景足够时归纳 → 合成 → 编译技能,并尝试编译策略 |
|
||||
| `## 编译` | `## compile` | 候选技能 → 版本化 `skills/<slug>/vN.mq.md` + 可选 OKF promote |
|
||||
| `## 指标` | `## metrics` | Reasoning amortization(`avg_llm_calls` / `compiled_runs`) |
|
||||
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
|
||||
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
|
||||
|
||||
**Skill Compilation(v2)**:Agent 的记忆不是向量袋,而是可执行 `.mq.md`。路径:`episodes/` → `experiences/` → `candidates/` → `skills/vN.mq.md` → OKF `agent-kb`(`llm_free`)。编译技能正文为合法 Marqdo(`**result = …**` + 斜体返回);金样 `tests/ext/agent-zero-llm.mq.md` 验收 policy+skill 全路径 `execution.llm_calls=0`。`plan` 对已存在的 `resources/<slug>.mq.md` **不覆盖**(`agent-plan-preserve`)。
|
||||
|
||||
**LLM 成本**:`model_turn` 走 `model.ask` / `stream`+`collect`,把 `LLMResult.tokens` 写入 episode / `execution`。
|
||||
|
||||
**Adaptive Routing(P4)**:Router 是抽象能力,backend = `marqdo`(已编译 `policies/router.mq.md`)/ `small-llm`(`router_model` 任意 llm 句柄)/ `llm` / `auto` 级联。`jev` 仅为 `small-llm` 兼容别名,**不进入框架专属设计**。热路径在 **`plugins/agent`**(`route.rs`);**禁止**向 `src/host/` 加领域原语。设计:[doc/next/003.md](../next/003.md) · [doc/next/004.md](../next/004.md)。
|
||||
|
||||
构造参数(v1):
|
||||
|
||||
| 参数 | 说明 |
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
# 方案:智能体 / 大模型优化方向(代码即文档 · OKF · 沙盒)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · O1–O5 locked** |
|
||||
| 日期 | 2026-10-16 |
|
||||
| 调研 | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
|
||||
| 路线 | [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md) |
|
||||
| 相关 | [ext-ai-sandbox.md](ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [okf.md](okf.md) · [engineering-knowledge.md](engineering-knowledge.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) · [ai-stack.md](../roadmap/ai-stack.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 方案立场
|
||||
|
||||
1. **强化差异化**:可执行 `.mq.md` 为权威;OKF 为复用;沙盒为证明;LLM 为探索。
|
||||
2. **不向隐藏 TOOL: 循环 / 向量权威回退。**
|
||||
3. 下列方向均为**可行**;推荐波次见 §3,最终裁剪由你选型。
|
||||
4. **不改** `doc/next/*`;落地时另开 roadmap 切片。
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构愿景(闭环)
|
||||
|
||||
```text
|
||||
目标 / 任务
|
||||
│
|
||||
▼
|
||||
EFI / OKF lookup ──hit──► llm_free / marqdo 执行 ──► writeback
|
||||
│ miss
|
||||
▼
|
||||
small-llm 路由 / 父分解
|
||||
│
|
||||
▼
|
||||
生成或修补 .mq.md(代码即文档风格)
|
||||
│
|
||||
▼
|
||||
sandbox.open → sandbox.run(caps)→ diff
|
||||
│
|
||||
├─ 失败 → writeback error / 隔离,不 promote
|
||||
└─ 成功 → 人审或策略 → commit → solidify / OKF promote
|
||||
│
|
||||
▼
|
||||
下次 REUSE(降本)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 可行方向全集
|
||||
|
||||
每个方向标注:解决的问题(Pn)、依赖、风险、粗粒度成本。
|
||||
|
||||
### A. 沙盒 × Agent 闭环
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **A1** | `step`/`plan` 默认经 sandbox 试跑再写实树 | P1 | 生成落 upper;绿才 `commit` | sandbox | 破坏现有金样默认 | 中 |
|
||||
| **A2** | Promote / solidify 强制 sandbox proof | P1 | OKF 写入前要求 proof fixture 绿 | sandbox+OKF | 过严挡复用 | 中 |
|
||||
| **A3** | Sandbox profile 表(caps 宣告) | P1/P3 | GFM 表声明 net/plugin/fs | sandbox | 表方言膨胀 | 低 |
|
||||
| **A4** | Guest 风格门禁(表优先、禁 json 胶水) | P5 | commit 前 lint / preflight | sandbox+parser | 误杀合法 json.parse | 中 |
|
||||
| **A5** | 会话 diff → view 审阅卡 | P1/P4 | HITL 看 CoW diff | view+sandbox | UI 工时 | 中高 |
|
||||
| **A6** | 多会话并行 CoW(fan-out 实验) | — | 每假设一 session | sandbox | 隔离/合并复杂 | 高 |
|
||||
|
||||
### B. OKF / EKC / 技能层
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **B1** | OKF 技能元数据:适用条件 / fixtures / sandbox_profile | P2 | frontmatter + 目录约定 | okf | 与 catalog 字段冲突 | 中 |
|
||||
| **B2** | Progressive disclosure(索引轻、正文按需 READ) | P2/P6 | 对齐 Anthropic Skills 层级 | agent A3 | 实现重复 | 中 |
|
||||
| **B3** | Skill Lift 评测(有/无技能配对) | P4 | harness 指标 | B1 评测 | 样本少噪声大 | 中 |
|
||||
| **B4** | 失败技能隔离(quarantine)+ 回归用例跟随血缘 | P1 | ForgeAgent 式 | OKF | 状态机复杂 | 中高 |
|
||||
| **B5** | near-match / soft_match 产品化默认开 | P6 | 已有 roadmap | okf-near | 误复用 | 低中 |
|
||||
| **B6** | EKC preflight 默认硬门槛(REUSE→ADAPT→CREATE) | P6 | step 前强制 EFI | EKC | 拖慢探索 | 中 |
|
||||
| **B7** | Capability 包与 `llm_free` 资源双向链接 | P2 | catalog L3↔任务包 | EKC+OKF | 图维护 | 中 |
|
||||
|
||||
### C. 大模型 / 路由 / 成本
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **C1** | 步骤级路由(lookup / patch / sandbox_run / net) | P3 | 扩展 route policy 表 | routing | 策略过拟合 | 中 |
|
||||
| **C2** | 总成本计量(含推理 token 膨胀)写回文档 | P7 | usage→writeback/metrics | llm result | 噪声 | 低中 |
|
||||
| **C3** | 用强模型「反思」优化 standing / policy `.mq.md`(类 GEPA) | P3/P5 | 离线优化环,产物仍是文件 | llm | 需评测集 | 高 |
|
||||
| **C4** | 高频 OKF 技能蒸馏/微调小模型(编译进权重) | — | 长期研究 | 数据+算力 | 运维重;偏离「源码权威」 | 很高 |
|
||||
| **C5** | Named model 绑定任务类型(fast=路由,reasoning=分解) | P3 | 已有 named handles 加深 | llm | 配置漂移 | 低 |
|
||||
| **C6** | Prompt document 强制:无参 ask 必须来自 type:prompt 文件 | P5 | 硬化 005 | llm | 破坏脚本式调用 | 低 |
|
||||
|
||||
### D. 代码即文档(产出质量)
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **D1** | 官方「可读 Marqdo」Skill 强化(表/链接取元/禁混名) | P5 | skills/marqdo 加厚 | skill | 模型仍违规 | 低 |
|
||||
| **D2** | AST/结构 lint:json.set 链、混 EN/ZH API | P5 | `marqdo lint` 或 sandbox 钩子 | parser | 误报 | 中 |
|
||||
| **D3** | 工作簿补丁只允许表驱动 / 命名槽写回 | P5 | 收紧 A0 补丁面 | agent | 表达力下降 | 中 |
|
||||
| **D4** | 示例库:sandbox+OKF+表风格 canonical demos | P4/P5 | examples/ | 文档 | 维护 | 低 |
|
||||
|
||||
### E. 评测与产品化
|
||||
|
||||
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|
||||
|----|------|------|--------|------|------|------|
|
||||
| **E1** | 完成 Wave B1 harness(constitution / writeback / call_site) | P4 | 已规划 | agent | — | 中 |
|
||||
| **E2** | 指标面板:ReuseRate / ProofRate / TokenCost | P4/P7 | metrics 写回或 catalog | agent | 虚荣指标 | 中 |
|
||||
| **E3** | Live 金样矩阵(sandbox 开/关 × 路由后端) | P4 | CI optional | CI | flaky | 中 |
|
||||
| **E4** | 教程:「只读一份 .mq.md 理解 Agent」 | — | doc/tutorial | 文档 | — | 低 |
|
||||
|
||||
### F. 明确不优先 / 需单独论证
|
||||
|
||||
| ID | 方向 | 理由 |
|
||||
|----|------|------|
|
||||
| **F1** | 第二套 Agent Framework(Python/TS 对象图权威) | 违宪 |
|
||||
| **F2** | 向量库升为记忆权威 | 违宪;可作证据工具 |
|
||||
| **F3** | 默认通用 shell Agent | 与 Marqdo-only 沙盒战略冲突 |
|
||||
| **F4** | 整库 `ext/web` 进默认沙盒 | 已否决 |
|
||||
| **F5** | 人人 microVM 本地默认 | DX 过重;留给 hosted |
|
||||
|
||||
---
|
||||
|
||||
## 3. 执行顺序(O1→O5 locked)
|
||||
|
||||
| 波次 | 方向组合 | 为何先做 |
|
||||
|------|----------|----------|
|
||||
| **O1** | A1 轻量(opt-in `sandbox=True`)+ A3 + D1 + D4 | 立刻接上刚落地的沙盒,风险可控 |
|
||||
| **O2** | A2 + B1 + B3 + E1 | 验证→晋升→可度量 Skill Lift |
|
||||
| **O3** | C1 + C2 + B6 | 降本与 EFI 硬门槛 |
|
||||
| **O4** | A4 + D2 + A5 | 质量门禁与人审 |
|
||||
| **O5** | B4 + C3 | 失败隔离与离线提示优化 |
|
||||
| **O∞** | C4 / A6 | 研究项,单独立项 |
|
||||
|
||||
切片实现见 [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收原则(任一波次)
|
||||
|
||||
- 金样:有/无沙盒、有/无 OKF hit、路由后端切换。
|
||||
- 指标:至少报告 ReuseRate 或 TokenCost 之一相对基线变化。
|
||||
- 文档:`.mq.md` 示例仍可读为 Markdown(表/链接取元,少 json 胶水)。
|
||||
- 红线:不改 `doc/next/*`;ext 不调 `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 落地
|
||||
|
||||
O1–O5 已锁定;实现见 [roadmap/ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。**仍不改** `doc/next/*`。
|
||||
@@ -0,0 +1,104 @@
|
||||
# Official AI sandbox (`ext/ai/sandbox`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted · implementing** |
|
||||
| Date | 2026-10-16 |
|
||||
| Related | [research/ai-agent-sandbox.md](../research/ai-agent-sandbox.md) · [roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [stdlib-writeback.md](stdlib-writeback.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. One-liner
|
||||
|
||||
**Agent-only Marqdo trial runtime:** capability-isomorphic to browser Wasm defaults, CoW workspace until explicit `commit`, author surface under `ext/ai` (not stdlib).
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals / non-goals
|
||||
|
||||
### Goals
|
||||
|
||||
| # | Goal |
|
||||
|---|------|
|
||||
| G1 | Open a CoW session over a workspace root; edits stay in upper until `commit` |
|
||||
| G2 | `run` executes `.mq.md` (or in-memory source) under deny-by-default caps with core `lib/*` usable |
|
||||
| G3 | `diff` / `discard` / `inspect` for review gates |
|
||||
| G4 | Stable `unavailable in sandbox` for plugin.load, exec foreign/subtask path|code|lang, net (default), `ext/web` server APIs |
|
||||
| G5 | Author API in `ext/ai/sandbox` via `plugins/agent` — **no** public `lib/sandbox` |
|
||||
|
||||
### Non-goals (this wave)
|
||||
|
||||
| # | Non-goal |
|
||||
|---|----------|
|
||||
| N1 | Embed wasmtime in CLI |
|
||||
| N2 | True Wasm ABI plugins (linalg/quantum) |
|
||||
| N3 | bwrap / microVM |
|
||||
| N4 | Full `ext/web` listen/DB/WS inside sandbox |
|
||||
| N5 | Symlink-forest workspace isolation |
|
||||
| N6 | Default host-proxy of all native ABI plugins |
|
||||
| N7 | Wire `agent.step`/`plan` through sandbox automatically (later) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Layering
|
||||
|
||||
```text
|
||||
ext/ai/sandbox.mq.md → plugin.load agent → sandbox_* ABI
|
||||
↓ host_query
|
||||
HostContext + CowSession
|
||||
(fs / writeback see upper)
|
||||
```
|
||||
|
||||
| Layer | May call `host_*` | Role |
|
||||
|-------|-------------------|------|
|
||||
| `ext/ai/sandbox` | **No** | Author facade |
|
||||
| `plugins/agent` | via `host_query` only | Register `sandbox_*`; forward to host |
|
||||
| `src/host` | — | CoW session store; fs/writeback intercept; nested `run` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Author API
|
||||
|
||||
EN: `ext/ai/sandbox.mq.md` · ZH: `ext/ai/沙盒.mq.md` (separate files, no mixed names in one module).
|
||||
|
||||
| Method | Params | Result |
|
||||
|--------|--------|--------|
|
||||
| `open` | optional `root=` (default entry dir / cwd) | map `{ id, root }` |
|
||||
| `write` | `id=`, `path=`, `text=` | none |
|
||||
| `read` | `id=`, `path=` | text |
|
||||
| `remove` | `id=`, `path=` | none (whiteout) |
|
||||
| `diff` | `id=` | list of `{ path, kind: write\|remove }` |
|
||||
| `commit` | `id=` | `{ ok, applied }` |
|
||||
| `discard` | `id=` | `{ ok }` |
|
||||
| `run` | `id=`, `path=` **or** `source=` | `{ ok, value, stdout?, error? }` |
|
||||
| `inspect` | `id=` | caps, root, change count, notes |
|
||||
|
||||
Default `run` caps: `fs_write=true` (CoW only), `exec=false`, `net=false`, `plugin=false`.
|
||||
|
||||
---
|
||||
|
||||
## 4. CoW semantics
|
||||
|
||||
- **lower** = real workspace root (read-through).
|
||||
- **upper** = session map path → bytes.
|
||||
- **whiteout** = logical deletes; reads miss; commit unlinks lower.
|
||||
- No symlink-as-isolation; resolve paths under root; reject `..` escape.
|
||||
- Until `commit`, host tree unchanged (verifiable with `git status` / file mtime).
|
||||
|
||||
---
|
||||
|
||||
## 5. Hard bans
|
||||
|
||||
1. No public `lib/sandbox`.
|
||||
2. No symlink forest as the isolation story.
|
||||
3. No silent success when capability missing — diagnose `unavailable in sandbox`.
|
||||
4. `ext/**` must not call `host_*`.
|
||||
5. Do not treat empty `# main` as sandbox completeness.
|
||||
|
||||
---
|
||||
|
||||
## 6. ABI / host_query
|
||||
|
||||
Plugin exports (registered on agent plugin): `sandbox_open`, `sandbox_write`, `sandbox_read`, `sandbox_remove`, `sandbox_diff`, `sandbox_commit`, `sandbox_discard`, `sandbox_run`, `sandbox_inspect`.
|
||||
|
||||
Implementation: each forwards to allowlisted `host_query` names of the same stem (e.g. `sandbox_open`), which mutate the process-local CoW store and (for `run`) invoke nested capture with a sandboxed `HostContext`.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Extension CDN: native publication and byte parity
|
||||
|
||||
This page describes storage. The executable tasks are in [the release entry](../../skills/marqdo-release/index.mq.md), [assets.mq.md](../../skills/marqdo-release/assets.mq.md) and [asset_io.mq.md](../../skills/marqdo-release/asset_io.mq.md). Read the source contracts before calling them. Version, mode and publication authorization come from the user; inspecting an existing release grants no new remote write.
|
||||
|
||||
## Versioned packs
|
||||
|
||||
Extension versions come from ext/VERSION and can advance independently of the interpreter. An extension release uses its own ext-vX.Y.Z tag and three packs. A full release also includes the CLI, source, WASM and editor deliverables listed in model.mq.md.
|
||||
|
||||
| Object | Meaning |
|
||||
|---|---|
|
||||
| vX.Y.Z/marqdo-X.Y.Z-ext.zip | Readable extension sources |
|
||||
| vX.Y.Z/marqdo-X.Y.Z-native-x86_64-pc-windows-msvc.zip | Windows plugins |
|
||||
| vX.Y.Z/marqdo-X.Y.Z-native-x86_64-unknown-linux-gnu.zip | Linux plugins |
|
||||
| vX.Y.Z/VERSION | Version echo for this pack set |
|
||||
| latest/marqdo-X.Y.Z-*.zip | Identical current pack bytes |
|
||||
| latest/VERSION | Recommended current extension version |
|
||||
|
||||
Public reads use https://ext.marqdo.com. [src/ext_cli.rs](../../src/ext_cli.rs) is authoritative for client override variables, version resolution and download fallback order. Ordinary installation does not need storage credentials.
|
||||
|
||||
## Callable publication
|
||||
|
||||
After GitHub contains every required asset, download to dist/release-X.Y.Z. Validation checks names, GitHub size/SHA256, archive CRCs, versions and native capabilities. Source-declared plugins require matching libraries on both native platforms. Independently valid ZIPs cannot hide a missing DLL or shared library.
|
||||
|
||||
Run from the checkout root with the version already chosen by the user; use the actual full or ext mode:
|
||||
```sh
|
||||
marqdo call skills/marqdo-release/assets.mq.md download 'version="X.Y.Z"' 'mode="ext"' --require-ok --effects plugin,net,fs.write --fs-root . --json
|
||||
marqdo call skills/marqdo-release/assets.mq.md publish 'version="X.Y.Z"' 'mode="ext"' --require-ok --effects plugin,net,fs.write --fs-root . --json
|
||||
marqdo call skills/marqdo-release/index.mq.md finish 'version="X.Y.Z"' 'mode="ext"' --require-ok --effects plugin,net,fs.write --fs-root . --json
|
||||
```
|
||||
|
||||
Publication rechecks all three packs and their combined capability matrix before the first PUT. All three versioned ZIPs and three latest ZIPs are written before either VERSION pointer. A failed ZIP stops the sequence. Historical versions are retained.
|
||||
|
||||
Finish reads both public pointers and compares downloaded versioned/latest bytes with GitHub SHA256 values. HTTP 200 or one sample URL is insufficient. Edge propagation may leave verification incomplete; repeat observation rather than rebuilding unrelated archives or claiming completion from an upload response.
|
||||
|
||||
## Explicit boundaries
|
||||
|
||||
Filesystem operations, hashing, public HTTP downloads, release decisions and upload order are Marqdo code. The engineering extension supplies bounded ZIP inspection and private R2 Signature V4 transport. No Python uploader is part of this path; older standalone scripts remain compatibility utilities.
|
||||
|
||||
The native boundary resolves credentials privately from existing stores or environment. Missing credentials fail explicitly. Never put access keys or secrets in tool parameters, source or reports. A plugin grant has normal OS authority; --fs-root does not sandbox native plugins or child processes.
|
||||
|
||||
Isolated loopback tests use fake credentials to verify ZIP-before-VERSION ordering and failure stops. Read-only verification of the published 2.6.0 release has also exercised the actual GitHub/CDN parity path without republishing its assets.
|
||||
+72
-33
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted (v0.1)** |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) |
|
||||
| Status | **Accepted (v0.3.5 prep)** — prebuilt native download |
|
||||
| Date | 2026-09-04 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [08-ext-deploy-coupling.md](ext-web-customization/08-ext-deploy-coupling.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext remove llm
|
||||
marqdo ext remove agent
|
||||
```
|
||||
|
||||
## Install root
|
||||
@@ -23,57 +23,96 @@ marqdo ext remove agent
|
||||
|
||||
Imports use paths like `import llm:ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
|
||||
|
||||
## Source for `add`
|
||||
## Goal: no local Rust required
|
||||
|
||||
End users who install Marqdo from **GitHub Releases** should run:
|
||||
|
||||
```bash
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
and get both L1 `.mq.md` **and** the matching native plugin (`.dll` / `.so`) **without** `cargo build`.
|
||||
|
||||
### Resolution order (`add` with native crate)
|
||||
|
||||
1. Local artifact (`MARQDO_*_PLUGIN`, `plugins/web/build` for **web**, `target/{debug,release}`, beside `marqdo`, `MARQDO_EXT_SOURCE/native`, …)
|
||||
2. **Download** `marqdo-{VER}-native-{target}.zip` from the GitHub Release for this CLI version → cache under `~/.marqdo/cache/`
|
||||
3. Local rebuild fallback:
|
||||
- **web** → `./scripts/build-web-plugin.sh` (Go c-shared `libweb`; requires Go 1.22+ / cgo)
|
||||
- other plugins → `cargo build -p marqdo_plugin_*` when Rust/`cargo` is available
|
||||
4. Else fail with a clear message pointing at the Release assets
|
||||
|
||||
L1 sources:
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` / repo `./ext` / beside binary
|
||||
2. Else download `marqdo-{VER}-ext.zip` into `~/.marqdo/cache/ext-src-v{VER}/`
|
||||
|
||||
### Env knobs
|
||||
|
||||
| Variable | Meaning |
|
||||
|----------|---------|
|
||||
| `MARQDO_EXT_VERSION` | Override **extension pack** SemVer (default: CDN `latest/VERSION` → embedded `ext/VERSION` → CLI version) |
|
||||
| `MARQDO_EXT_CDN` | Public CDN base (default `https://ext.marqdo.com`) |
|
||||
| `MARQDO_EXT_NO_DOWNLOAD=1` | Never hit the network (CI / air-gap); local/cargo only |
|
||||
| `MARQDO_EXT_DOWNLOAD_BASE` | Optional extra base tried **before** CDN |
|
||||
| `MARQDO_WEB_PLUGIN` / `MARQDO_AGENT_PLUGIN` / `MARQDO_QUANTUM_PLUGIN` | Explicit native path |
|
||||
|
||||
Download order for each Release asset: `MARQDO_EXT_DOWNLOAD_BASE` → **CDN `ext.marqdo.com`** → `github.com` → **`proxy.cflmy.top`**. Connect timeout 20s; read timeout 10min.
|
||||
|
||||
See [ext-cdn.md](ext-cdn.md) for R2 layout, separate ext releases, and `scripts/upload-ext-r2.py`.
|
||||
|
||||
Windows Release **zip** also ships `ext/` + `ext/native/*.dll` next to `marqdo.exe` so a portable unzip works offline after one download.
|
||||
|
||||
## Source for `add` (developers)
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
3. Else Release `marqdo-*-ext.zip` (see above)
|
||||
|
||||
## Layout (`ext/`)
|
||||
|
||||
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
ai/ # llm + agent L1
|
||||
web/
|
||||
quantum/
|
||||
```
|
||||
|
||||
Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum/`), not mixed into `ai/`.
|
||||
Installed tree (`~/.marqdo/ext` or `MARQDO_EXT`):
|
||||
|
||||
```text
|
||||
web/web.mq.md
|
||||
web/网页.mq.md
|
||||
native/libweb.so # or web.dll / libweb.dylib
|
||||
web.plugin # absolute path hint
|
||||
```
|
||||
|
||||
## Catalog
|
||||
|
||||
| Id | Installs under `MARQDO_EXT` |
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
|
||||
| `web` | `web/index.mq.md` + facade/modules + `layout/` · `布局/` + `网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/`(含 `量子/` 中文树), **native `quantum`** |
|
||||
|
||||
`add agent` / `add web` / `add quantum` **先定位原生插件**,再复制 `.mq.md`:
|
||||
## Release assets (native)
|
||||
|
||||
1. 在 `CARGO_TARGET_DIR`、`target/{debug,release}`、源码 `ext` 旁的 `target/`、可执行文件旁等路径查找 `lib{name}.so`(或 `.dll` / `.dylib`)
|
||||
2. 找不到则自动执行 `cargo build -p marqdo_plugin_{name}`,再安装到 `MARQDO_EXT/native/`
|
||||
3. 写入 `{name}.plugin` 绝对路径提示,供 `plugin.native_path` 解析
|
||||
| Asset | Platform |
|
||||
|-------|----------|
|
||||
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Windows x64 (`native/*.dll`) |
|
||||
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Linux x64 (`native/lib*.so`) |
|
||||
|
||||
这样不会出现「只装了 `.mq.md`、运行时报 native plugin not found」的半安装状态。
|
||||
|
||||
```bash
|
||||
# 推荐:在仓库根目录
|
||||
marqdo ext add web
|
||||
# 等价于找到或编好 libweb.so 后拷入 ~/.marqdo/ext/native/
|
||||
```
|
||||
|
||||
Without a prior install, runtime still resolves via `plugin.native_path name=web` (see [ext-abi.md](ext-abi.md)): `MARQDO_WEB_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`.
|
||||
macOS: use local `cargo build` until CI adds Darwin natives (same zip naming pattern reserved).
|
||||
|
||||
## Tests
|
||||
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_cli_add_web` (local build path; set `MARQDO_EXT_NO_DOWNLOAD=1` in sandboxes if needed).
|
||||
|
||||
Unit: `ext_fetch` URL / triple tests.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Third-party registry
|
||||
- Merging into `lib/`
|
||||
- Bundling domain/task helpers in official ext
|
||||
- Merging domain helpers into `lib/`
|
||||
- Guaranteeing plugin **source** ABI stability (author `.mq.md` API is the contract)
|
||||
@@ -0,0 +1,306 @@
|
||||
# 设计:宿主集成缺口补齐(`ext/web` · `ext/ai`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · H1–H4 stdio 已落地**(H4b HTTP 可选) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 缺口盘点 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
|
||||
| 路线图 | [ext-hosting.md](../roadmap/ext-hosting.md) |
|
||||
| 边界 | [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) |
|
||||
| 目标 | 用**扩展库一等 API**关闭 GAP-01–05,取代下游 Python 旁路 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**服务器中继与「请求→`##`」进 `ext/web`;MCP Server 与 corpus 可发现进 `ext/ai`;标准库只保留已有客户端 SSE。** 作者用 GFM 表声明路由/工具,不写 JS、不启第二语言运行时。
|
||||
|
||||
---
|
||||
|
||||
## 1. 分层与禁止项
|
||||
|
||||
| 层 | 职责 | 落点 |
|
||||
|----|------|------|
|
||||
| 作者面 | 声明路径、上游、函数名、工具表 | `ext/web/web.mq.md` · `ext/ai/agent.mq.md`(+ 中文对偶) |
|
||||
| ABI | axum 流式代理、每请求 interp 调用、MCP 传输 | `plugins/web` · `plugins/agent` |
|
||||
| 标准库 | 不变:缓冲客户端 SSE / 解析 | `lib/net`(**不**加中继) |
|
||||
| 核心 host | **禁止**新增 agent/web 领域 `host_*` | 见 Skill 硬规则 9 |
|
||||
|
||||
**禁止:**
|
||||
|
||||
1. 为中继在浏览器手写业务 JS。
|
||||
2. `json=` 继续塞「任意 `##`」语义(保持 DB-only;新能力用独立装配名)。
|
||||
3. MCP Server 把向量库升为权威真相(工具结果可带 `authority=workbook`)。
|
||||
4. 无白名单的「任意文件系统路径 + 任意 `##`」远程触发。
|
||||
|
||||
---
|
||||
|
||||
## 2. GAP-01 · `app.proxy` 流式反向代理
|
||||
|
||||
### 2.1 作者 API
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.proxy path="/v1/chat/completions" upstream=$OPENAI_BASE_URL*
|
||||
*应用 = > `应用`.proxy path="/llm/stream" upstream="https://api.example.com" strip_prefix="/llm" stream=True*
|
||||
```
|
||||
|
||||
或装配表(一次挂多条):
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.configure proxy=`代理表`*
|
||||
|
||||
| path | upstream | stream | strip_prefix | headers_from_env |
|
||||
|------|----------|--------|--------------|------------------|
|
||||
| /proxy/chat | $OPENAI_BASE_URL | True | | OPENAI_API_KEY=Authorization |
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 含义 |
|
||||
|------|------|------|
|
||||
| `path` | 必填 | 浏览器同域路径 |
|
||||
| `upstream` | 必填 | 上游根或完整 URL;支持 `$ENV` |
|
||||
| `stream` | `True` | `True`:响应按上游 `Content-Type` 管道转发(含 `text/event-stream`) |
|
||||
| `strip_prefix` | 空 | 转发前去掉本站前缀 |
|
||||
| `methods` | `POST` | 允许方法 |
|
||||
| `headers_from_env` | 空 | `ENV=Header-Name` 注入(密钥不进前端) |
|
||||
| `timeout_ms` | 插件默认 | 上游超时 |
|
||||
|
||||
中文:`## 代理` / `流式=` / `上游=` / `去前缀=`。
|
||||
|
||||
### 2.2 ABI / 插件行为
|
||||
|
||||
| 步骤 | 行为 |
|
||||
|------|------|
|
||||
| 注册 | `web_app_proxy` 写入 `AppState` 路由表 |
|
||||
| 请求 | 读 body + 过滤危险 hop-by-hop 头;合并 env 注入头 |
|
||||
| 上游 | `reqwest`/`hyper` 流式客户端(插件内,不进核心) |
|
||||
| 响应 | 复制状态码与 `content-type`;`body` 为 stream;SSE 不整段缓冲 |
|
||||
| CORS | 仍走既有 `configure cors=`(同域调用时浏览器不依赖上游 CORS) |
|
||||
|
||||
### 2.3 与 `lib/net.http_post_sse` 关系
|
||||
|
||||
| API | 角色 |
|
||||
|-----|------|
|
||||
| `http_post_sse` | **出站消费者**(CLI/agent 侧收齐 events) |
|
||||
| `app.proxy` | **入站中继**(浏览器 ← Marqdo ← 上游) |
|
||||
|
||||
二者互补,不互相替代。
|
||||
|
||||
### 2.4 验收
|
||||
|
||||
- 金样:mock 上游发两帧 SSE,浏览器侧(或 `curl -N`)收到两帧且中间无全缓冲延迟门槛。
|
||||
- 密钥仅出现在服务端 env 注入头。
|
||||
- 金样名建议:`tests/ext/web-proxy-sse-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. GAP-02 · `app.invoke` / `configure invoke=`(HTTP → `##`)
|
||||
|
||||
### 3.1 作者 API
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.invoke path="/api/沉淀" method=POST fn="run.沉淀"*
|
||||
```
|
||||
|
||||
表形式:
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.configure invoke=`调用表`*
|
||||
|
||||
| path | method | fn | body | return |
|
||||
|------|--------|-----|------|--------|
|
||||
| /api/note | POST | run.写出 | json | json |
|
||||
| /api/search | GET | db.recent | query | json |
|
||||
```
|
||||
|
||||
| 列 / 参数 | 含义 |
|
||||
|-----------|------|
|
||||
| `path` / `method` | HTTP 路由 |
|
||||
| `fn` | `库.成员`(入口模块已 `import`)或 `模块路径##标题`(白名单前缀内) |
|
||||
| `body` | `json` \| `form` \| `query` \| `raw` → 映射到 `##` 形参(同名优先;其余进 `payload` 袋) |
|
||||
| `return` | `json`(默认)\| `text` \| `status` |
|
||||
|
||||
中文:`## 调用` / `函数=` / `正文=` / `返回=`。
|
||||
|
||||
### 3.2 安全默认(锁定)
|
||||
|
||||
1. **仅**解析入口 workbook 已导入的 `bind` 路径,或 `invoke_allow=` 显式前缀列表。
|
||||
2. 单请求超时 + 可选并发上限(防 listen 线程饿死)。
|
||||
3. 默认不启;作者显式 `invoke` / `configure invoke=`。
|
||||
4. 错误:`{ok:false, error}` + HTTP 4xx/5xx;不把内部路径栈默认回传生产模式。
|
||||
|
||||
### 3.3 ABI / 插件行为
|
||||
|
||||
| 步骤 | 行为 |
|
||||
|------|------|
|
||||
| 注册 | `web_app_invoke` 存 `(path, method, FnRef)` |
|
||||
| 命中 | 解析 body → Value 袋;`call_lib_path` / 等价「同步调用已加载模块的 `##`」 |
|
||||
| 返回 | Value → JSON(复用现有 host JSON 通路);侧效(写盘)在同一解释器事务语义内尽最大努力 |
|
||||
|
||||
**不**把 `json=` DB 路由改语义;`invoke` 是平行装配。
|
||||
|
||||
### 3.4 与 compose 期 `call_lib_path` 关系
|
||||
|
||||
| 时机 | API |
|
||||
|------|-----|
|
||||
| 装配页 | 现有 compose / `call_lib_path` |
|
||||
| **每个 HTTP 请求** | 本设计 `invoke` |
|
||||
|
||||
### 3.5 验收
|
||||
|
||||
- `POST` JSON → 用户 `##` 写入临时文件 + 返回 `{ok:true,…}`。
|
||||
- 未导入路径 → 4xx,不执行。
|
||||
- 金样:`tests/ext/web-invoke-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 4. GAP-03 · MCP Server(`ext/ai`)
|
||||
|
||||
### 4.1 作者 API
|
||||
|
||||
```markdown
|
||||
*服务 = > agent.mcp_server name="marqdo-qd"*
|
||||
*服务 = > `服务`.tool name="qd_search" fn="求道.搜索" description="关键词检索"*
|
||||
*服务 = > `服务`.tool name="qd_capture" fn="求道.捕捉"*
|
||||
*服务 = > `服务`.serve transport=stdio*
|
||||
# 或
|
||||
*服务 = > `服务`.serve transport=http host=127.0.0.1 port=7433*
|
||||
```
|
||||
|
||||
工具表:
|
||||
|
||||
| name | fn | description |
|
||||
|------|-----|-------------|
|
||||
| qd_search | 求道.搜索 | … |
|
||||
| qd_list | 求道.列出 | … |
|
||||
|
||||
### 4.2 传输
|
||||
|
||||
| transport | 用途 |
|
||||
|-----------|------|
|
||||
| `stdio` | Cursor / Claude Desktop 拉起 |
|
||||
| `http` | Streamable HTTP(与官方 MCP 演进对齐;首版可先 SSE+POST 子集) |
|
||||
|
||||
### 4.3 与 A4 fixture 客户端关系
|
||||
|
||||
| API | 方向 |
|
||||
|-----|------|
|
||||
| `mcp_list_tools` / `mcp_call` | **出站**(Agent 调外部 MCP;现 fixture) |
|
||||
| `mcp_server` + `serve` | **入站**(外部调 Marqdo) |
|
||||
|
||||
客户端「真 MCP」仍见 agent 缺口文;本设计先交 Server,fixture 可保留测客户端。
|
||||
|
||||
### 4.4 ABI
|
||||
|
||||
- `plugins/agent`:`agent_mcp_server_*`(注册工具、stdio loop、可选 HTTP)。
|
||||
- 工具实现:复用 GAP-02 同款「调用 `##`」内核(可抽共享 `invoke_fn`),避免两套分发。
|
||||
- 返回包装:可含 `authority=workbook`。
|
||||
|
||||
### 4.5 验收
|
||||
|
||||
- 金样:stdio 夹具发 `tools/list` + `tools/call`,断言 JSON-RPC 形结果。
|
||||
- 可选:`tests/ext/agent-mcp-server-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. GAP-04 · 同寿副端口
|
||||
|
||||
### 5.1 关闭策略(优先)
|
||||
|
||||
GAP-01 + GAP-02 挂在**同一** `app.listen` → **不实现副端口**,文档宣布 GAP-04 关闭。
|
||||
|
||||
### 5.2 备选 API(仅当必须隔离)
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.listen host=127.0.0.1 port=18081 also_port=7432 also_routes=`中继表`*
|
||||
```
|
||||
|
||||
`also_routes` 仅允许 `proxy` / `invoke` 已注册子集。实现成本高,**默认不做**。
|
||||
|
||||
---
|
||||
|
||||
## 6. GAP-05 · 跨模块 `db` 与 corpus 可发现
|
||||
|
||||
### 6.1 `db` 句柄(扩展约定 + 运行时)
|
||||
|
||||
**作者约定(立即文档化):**
|
||||
|
||||
1. 跨模块优先传 **`url` 字符串**,调用方 `*store = > web.db url=…*` 再 `select`。
|
||||
2. 若传对象:必须保留 `_type` 为插件注册名(与 `web.db` 构造一致)。
|
||||
|
||||
**运行时修补(H 波次):**
|
||||
|
||||
| 选项 | 做法 | 选用 |
|
||||
|------|------|------|
|
||||
| A | 跨模块返回插件对象时规范 `_type` + 全局方法表查找 | **首选**(一次修好所有插件对象) |
|
||||
| B | `db.open` 只返回 `{url}` 朴素 map,禁止「裸 select」跨文件 | 文档契约;体验较差 |
|
||||
|
||||
金样:模块 A `open` → 返回 → 模块 B `select` 成功。
|
||||
`tests/ext/web-db-cross-module-smoke.mq.md`。
|
||||
|
||||
### 6.2 `corpus_search` 可发现
|
||||
|
||||
```markdown
|
||||
## corpus_search
|
||||
+ `query`
|
||||
+ `root`=".marqdo/agent-kb"
|
||||
|
||||
* > plugin.load name=agent *
|
||||
** > agent_corpus_search query=`query` root=`root` **
|
||||
```
|
||||
|
||||
或在 `# agent` / `## corpus_search` 入口统一 `ensure_plugin`(与现 `agent` 构造对齐),保证 **纯 `marqdo run` + import agent** 即可用。
|
||||
|
||||
**不**把 `agent_corpus_search` 搬进 `src/host/`。
|
||||
|
||||
### 6.3 验收
|
||||
|
||||
- 无显式手工 ABI 名的情况下,`marqdo run` 金样调用 `agent.corpus_search` 成功。
|
||||
- 跨模块 `db.select` 金样绿。
|
||||
|
||||
---
|
||||
|
||||
## 7. 扩展库表面清单(落地时改这些文件)
|
||||
|
||||
| 文件 | 增补 |
|
||||
|------|------|
|
||||
| `ext/web/web.mq.md` · `网页.mq.md` | `## proxy` / `## invoke`;`configure` 增 `proxy`/`invoke` 列 |
|
||||
| `plugins/web/src/http.rs` · `middleware.rs` · 新 `proxy.rs` / `invoke.rs` | 路由注册与流式/调用 |
|
||||
| `ext/ai/agent.mq.md` · `智能体.mq.md` | `# mcp_server` · `## tool` · `## serve`;`corpus_search` ensure_plugin |
|
||||
| `plugins/agent/` | MCP Server 传输 + 共享 invoke |
|
||||
| `tests/ext/web-proxy-sse-smoke.mq.md` 等 | 见上 |
|
||||
| `doc/roadmap/ext-web.md` | 链到 H 波次(不重开 W0–W7) |
|
||||
| `public/` / Skill | 发版时补「同域 LLM 代理 / HTTP 调用 ##」短节 |
|
||||
|
||||
**不**新增 `lib/run` 作为核心依赖:用户业务 `##` 仍在其自己的 `lib/*.mq.md`;Marqdo 只提供 **invoke 管道**。
|
||||
|
||||
---
|
||||
|
||||
## 8. 迁移:下游旁路 → 扩展 API
|
||||
|
||||
| 旁路(下游) | 替换为 |
|
||||
|--------------|--------|
|
||||
| `llm_proxy.py` `/proxy/stream` | `app.proxy` / `configure proxy=` |
|
||||
| `llm_proxy.py` `/store/*` + `marqdo run` | `app.invoke` → 用户 `##` |
|
||||
| `mq_bridge.py` 仅过滤 | 用户 `##` 内 `table`/`re` 过滤,或修复后的 `corpus_search` |
|
||||
| `qdagent_mcp.py` | `agent.mcp_server` + `serve` |
|
||||
| `mq.sh` 双进程 | 单 `marqdo run index.mq.md`(proxy+invoke 同端口) |
|
||||
|
||||
---
|
||||
|
||||
## 9. 开放点(实现前拍板)
|
||||
|
||||
| # | 问题 | 默认倾向 |
|
||||
|---|------|----------|
|
||||
| 1 | `invoke` 的 `fn` 是否允许 `path.mq.md##标题` 字面量 | 允许但必须 `invoke_allow` 前缀 |
|
||||
| 2 | MCP HTTP 首版范围 | stdio 先交;HTTP 跟一波 |
|
||||
| 3 | 代理是否缓冲「非 SSE」大 body | 非流式可限长缓冲;SSE 禁止整段缓冲 |
|
||||
| 4 | GAP-05 选项 A vs B | **A** |
|
||||
|
||||
---
|
||||
|
||||
## 10. 完成定义(整包)
|
||||
|
||||
1. 无 Python 旁路即可:浏览器同域 SSE 对话 + HTTP 触发沉淀 `##` +(可选)MCP stdio 暴露同一批 `##`。
|
||||
2. 金样覆盖 proxy / invoke / cross-db / corpus / mcp-server(stdio)。
|
||||
3. `doc/research/ext-hosting-gaps.md` 各 GAP 标为关闭或降级为「备选副端口不做」。
|
||||
4. 发版说明指向 `ext/web` · `ext/ai` 新作者面,不指向 `scripts/*.py`。
|
||||
@@ -0,0 +1,91 @@
|
||||
# 扩展库:index 即代码 · 文档 · SKILL · tools
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active**(契约卡;完整开发范式见下行) |
|
||||
| 日期 | 2026-11-06 |
|
||||
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
|
||||
| 范式长文 | [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md)(布局、陷阱、验收清单、推广顺序) |
|
||||
| 试点 | `ext/quantum/`;[手册闭环与当前契约位置修正](ext-quantum-handbook.md) |
|
||||
| 相关 | [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [function-as-table-semantics.md](function-as-table-semantics.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
扩展包里**每一份** `.mq.md` 同时是可执行代码、可读 SKILL、以及可 `marqdo call` 的 tools 面;**函数即工具**,`###` 即子工具;禁止第二套 catalog / OpenAPI 真相源。开发新包或迁包时以 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 的验收清单为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 整包统一作者契约(无例外)
|
||||
|
||||
适用于包内全部 `.mq.md`(含 `index`、子依赖、`_capability`、兼容层、中英镜像):
|
||||
|
||||
| 要求 | 含义 |
|
||||
|------|------|
|
||||
| 代码 | 标记可执行;实现可薄委托 ABI / 兄弟模块 |
|
||||
| SKILL | `#` 下写清领域、何时用、**For AI agents → `marqdo call` 本文件** |
|
||||
| tools | `##` / `###` 即工具树;无旁路 schema |
|
||||
| 版式 | **形参契约表紧贴标题下**;**返回契约表也在首条执行语句之前**(当前解析器只在此提取契约) |
|
||||
| 叙述 | 每个函数单元叙述占比 **≥ 50%**;公式与约定写进人话 |
|
||||
| 禁止 | `+` 清单当主表面;ABI 名罗列充文档;「内部文件免检」 |
|
||||
|
||||
形参仍由叙述/体中的 `` `名` `` 推断 arity;`| 参数 | 类型 | 说明 |` 为契约表(见 `tests/contracts/`)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 包布局(quantum 试点)
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
index.mq.md # EN 根 SKILL:无上下文也能照抄 marqdo call
|
||||
circuit/index.mq.md # call 工具 + 作者 # circuit
|
||||
gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/index.mq.md
|
||||
量子/ # ZH 同包(勿再把 量子/ 抬到 ext/ 顶层)
|
||||
索引.mq.md
|
||||
电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
```
|
||||
|
||||
`index` = 总图与编排,必须写明 FILE/FUNCTION/`--effects plugin`;每个子目录的 `index.mq.md` 单独拿到也要能执行。无单独「兼容层」文件。
|
||||
|
||||
---
|
||||
|
||||
## 3. `marqdo call` 与会话
|
||||
|
||||
```text
|
||||
marqdo call <FILE> <FUNCTION> [k=v…]
|
||||
[--json] [--backend tree|bytecode]
|
||||
[--effects none|plugin] # 默认 none
|
||||
[--session <id>]
|
||||
[--toget <name>] # 或尾部 toget <name>
|
||||
```
|
||||
|
||||
- 默认:仅纯函数(今日行为)。
|
||||
- `--effects plugin`:允许 `plugin.call`(及附属的 `output.write`);仍拒绝 fs.write / network / process.exec / llm 等。
|
||||
- `toget` + `--session`:绑定写入 `.marqdo/call-sessions/<id>.json`;参数 `$name` 引用会话值;跨进程 **plugin 句柄经 journal 重放** 重建。
|
||||
- 嵌套子工具:`parent.child`(`###` 路径)。
|
||||
|
||||
值字面量:整数/小数/引号文本/True|False|None;以 `[` / `{` 开头时按 JSON 解析为 List/Map。
|
||||
|
||||
---
|
||||
|
||||
## 4. 叙述 ≥ 50%
|
||||
|
||||
`marqdo check --narrative-ratio`(及 `lib/lint/narrative.mq.md` skill)按函数单元统计叙述字符占比;`ext/quantum/**/*.mq.md` **全量零豁免**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 ADR 0007
|
||||
|
||||
作者程序与业务路径仍不写 `ensure_plugin` / `host_*`;插件经 `_capability` / facade 加载。Agent 用 `--effects plugin` 调用 facade,不把 capability 当日常工具(文件本身仍须达标 skill)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-11-06 | 初稿:012 试点契约、call effects/toget、quantum 模块树 |
|
||||
| 2026-11-06 | quantum 中文树收进 `ext/quantum/量子/`;根 skill 增加「选哪条路」;`ext add` 拒绝装进源码树 |
|
||||
| 2026-11-06 | 链到 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 作为开发范式长文 |
|
||||
@@ -0,0 +1,236 @@
|
||||
# `ext/linalg` — 公式文档面(跑通即正确)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft · 锁定作者面哲学与分期** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 父设计 | [ext-linalg.md](ext-linalg.md) |
|
||||
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| 对照 | [stdlib-math.md](stdlib-math.md)(高中标量公式) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**`.mq.md` 里的线性代数应当读起来像一份可运行的公式讲义**:式子能跑通,就在库承诺的规则与维数下代表正确;`lib/math` 守高中边界,大学符号矩阵与更深层计算由 **`ext/linalg` 正当承担**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 产品哲学
|
||||
|
||||
### 1.1 与 Marqdo 总原则对齐
|
||||
|
||||
| Marqdo | 在线性代数上的含义 |
|
||||
|--------|-------------------|
|
||||
| 代码即文档 | 矩阵代数段落用数学式书写,而不是 API 调用清单 |
|
||||
| 标记即语法 | `$$`、中缀、`# matrix` 方法都是可读标记,不是「库胶水」 |
|
||||
| 跑通可验收 | 金样 / 课堂作业:文件 exit 0 + 断言化简结果 = 式子合法 |
|
||||
|
||||
### 1.2 「跑通即正确」的精确定义
|
||||
|
||||
**不是**「任意高深定理自动证明」。
|
||||
**是**在声明的能力边界内,下列任一成立则文档该段视为正确:
|
||||
|
||||
1. **形状层**:不相容维数的乘加在构造时硬错误(写不出可运行的坏式)。
|
||||
2. **恒等式层**:文档断言的规范形(如 `(AB)^\top → B^\top A^\top`)经规则集得到。
|
||||
3. **数值核对层**(可选):小 `$$` 数值阵 `explicit` 后与手算一致——验算,不是符号证明。
|
||||
|
||||
更高深主题(矩阵微积分、表示、特殊函数矩阵等)通过**扩展同一公式面的规则表**分期加入,而不是另起一套函数库叙事。
|
||||
|
||||
### 1.3 与 `lib/math` 的边界(再次锁定)
|
||||
|
||||
| | `lib/math` | `ext/linalg` |
|
||||
|--|------------|--------------|
|
||||
| 教育边界 | 高中标量公式 | 大学经典线性代数及更深(官方 ext) |
|
||||
| 值类型 | `Value::Formula`(标量 AST) | `_type=matrix` / `矩阵`(MatExpr + 稠密) |
|
||||
| 作者感觉 | `$$sin(x)+x$$` + `diff` / `plot` | `A*B`、`(AB)^T`、分块、分解图 |
|
||||
| 是否「数学库」 | 是(stdlib) | **是数学库的官方扩展**,不是旁路工具箱 |
|
||||
|
||||
把大学 LA 塞进 `lib/math` ❌;在 `ext/linalg` 做大学符号计算乃至更深 ✅。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两面模型:代数面 vs 计算面
|
||||
|
||||
文档里应能一眼分清「推导」与「动手算」。
|
||||
|
||||
### 2.1 代数面(默认;公式文档)
|
||||
|
||||
| 意图 | 写法(目标) | 语义 |
|
||||
|------|--------------|------|
|
||||
| 引入符号阵 | 见 §3 | 惰性 `MatrixSymbol` |
|
||||
| 加减乘 | `` `C` = `A` + `B` `` · `` `P` = `A` * `B` `` | 建树 + 形状检查 |
|
||||
| 转置 / 逆 | `` `At` = > `A`.T `` · `` `Ai` = > `A`.inv `` | 惰性节点 |
|
||||
| 化简 / 展示 | 见 §4(默认化简策略) | 规则不动点 → ASCII / KaTeX |
|
||||
| 分块 / Kronecker | 表或 `block` / `kron`(可保留具名,但结果仍是公式) | 惰性 |
|
||||
|
||||
**读者感受**:像在抄黑板,而不是在调 `la.mul`。
|
||||
|
||||
### 2.2 计算面(显式步骤;可单独成段)
|
||||
|
||||
| 意图 | 写法 | 语义 |
|
||||
|------|------|------|
|
||||
| 稠密求值 | `` `E` = > `A`.explicit `` / `la.explicit` | 展开数值 |
|
||||
| 分解 | `` `f` = > la.factorize matrix=`A` kind="svd" `` | `linalg_factor` |
|
||||
| 求解 / 最小二乘 | `solve` / `lstsq` | 数值解 |
|
||||
| 度量 | `norm` / `cond` / `rank` / `det`(数值路径) | 标量或条件对象 |
|
||||
| 作图 | `draw` / `show` | SVG / 公式卡 |
|
||||
|
||||
**读者感受**:「于是我们计算 / 画出…」——与纯代数叙述分段书写。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标作者语法(公式文档优先)
|
||||
|
||||
### 3.1 已落地(v1 中缀 / 方法)
|
||||
|
||||
```markdown
|
||||
*`A` = > la.symbol name="A" rows=2 cols=2*
|
||||
*`B` = > la.symbol name="B" rows=2 cols=2*
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`s` = > `Pt`.simplify*
|
||||
*`t` = > `s`.ascii*
|
||||
```
|
||||
|
||||
数值 `$$` 矩阵可直接参与 `+` / `*`(经插件吸收为稠密叶)。
|
||||
|
||||
### 3.2 目标形态(文档感更强;分期实现)
|
||||
|
||||
**叙事理想(不必一次做完):**
|
||||
|
||||
```markdown
|
||||
# 正规方程
|
||||
|
||||
令 \(A\) 为 \(m\times n\) 设计矩阵,\(b\) 为观测。
|
||||
|
||||
*`AtA` = > `A`.T * `A`* # 或未来更紧凑的 postfix / 混合写法
|
||||
*`xty` = > `A`.T * `b`*
|
||||
*`xhat` = > `AtA`.solve b=`xty`* # 计算面
|
||||
```
|
||||
|
||||
**符号引入(减少 `la.symbol` 噪音)——候选(F2 选定一种):**
|
||||
|
||||
| 候选 | 例 | 利 | 弊 |
|
||||
|------|----|----|-----|
|
||||
| A. 构造糖 | `` `A` = > la.matrix name=A rows=m cols=n `` | 已有 `# matrix` | 仍是调用 |
|
||||
| B. 维数表 | GFM 表声明符号与形状,一行绑定 | 很「文档」 | 需新约定 |
|
||||
| C. `$$` 符号方言 | `$$A_{m\times n}$$` → MatExpr | 最像讲义 | 解析歧义;勿污染标量 formula |
|
||||
| D. 保持 `symbol` + 短别名 | `` `A` = > la.A rows=m cols=n `` | 实现便宜 | 文档感一般 |
|
||||
|
||||
**锁定倾向:** 短期 **A + 默认化简(F1)**;**F2 采用 B(GFM `@` 表 + `la.declare`)**;受限 C(`$$` 符号方言)仍待评估且不得污染核心 formula。
|
||||
|
||||
### 3.3 明确不做(本波语法)
|
||||
|
||||
- 把符号 MatExpr 塞进核心 `formula::Expr`
|
||||
- 发明与 Markdown 列表冲突的行首 `+` 矩阵语法
|
||||
- 用未定义的 `$$矩阵A$$` 伪方言冒充已实现语义
|
||||
|
||||
---
|
||||
|
||||
## 4. 默认化简与「写出即规范」
|
||||
|
||||
### 4.1 策略
|
||||
|
||||
| 操作 | 是否自动 `simplify` | 理由 |
|
||||
|------|---------------------|------|
|
||||
| `ascii` / `latex` / `show` | **是(F1 done)** | 展示面应接近讲义规范形;`raw=True` 可关 |
|
||||
| 中缀 `+` `*` `-` 的构造结果 | **否** | 保留用户书写结构;需要时再化简 |
|
||||
| `.simplify` | 显式不动点 | 文档断言 / 金样 |
|
||||
| `explicit` 前 | 可选先 simplify(F1.1) | 减少无效稠密路径 |
|
||||
|
||||
### 4.2 验收句式(金样)
|
||||
|
||||
```markdown
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`t` = > `Pt`.ascii* # F1:无需再 .simplify 即得 B^T*A^T
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=ok
|
||||
```
|
||||
|
||||
「跑通 + 断言」= 这段公式文档正确。
|
||||
|
||||
---
|
||||
|
||||
## 5. 正确性分层与错误体验
|
||||
|
||||
| 层 | 失败时 | 作者应看到 |
|
||||
|----|--------|------------|
|
||||
| 形状 | `A*B` 列行不配 | 含双方 shape 的硬错误,指向调用点 |
|
||||
| 规则 | 无法化到文档期望形 | 金样失败;或 `ascii` 仍为未化简形(需补规则) |
|
||||
| 插件未加载 | 中缀矩阵运算 | 提示 `ext add linalg` / `ensure_plugin` |
|
||||
| 超维 | `explicit` / 分解 | 护栏错误,建议保持符号 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 与实现现状的对照
|
||||
|
||||
| 能力 | 状态 |
|
||||
|------|------|
|
||||
| MatExpr 惰性树 + R1–R5 / 分块 / kron | done(L1–L3) |
|
||||
| 稠密 / 分解 / 度量 / draw theme | done(L2–L6) |
|
||||
| 中缀 `+` `-` `*` + `# matrix` 方法 | done(v1) |
|
||||
| `ascii`/`latex`/`show` 默认 simplify | **done(F1)** |
|
||||
| 更少噪音的符号引入 | **done(F2:`declare` + 表)** |
|
||||
| 更紧凑转置 / 混合公式书写 | **done(F3:`T_ascii`)** |
|
||||
| `explicit` 前可选 auto-simplify | **done(F3,默认开)** |
|
||||
| public「如何写公式文档」 | **done(F3)** |
|
||||
| 矩阵微积分等 | L7+ / 规则表扩展 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 分期(公式文档面)
|
||||
|
||||
| 阶段 | 内容 | 出口 |
|
||||
|------|------|------|
|
||||
| **F1** | 展示路径默认 simplify;金样「`.T` + `ascii` → 规范形」;设计本文落地 | **done** |
|
||||
| **F2** | 符号引入降噪(选定 §3.2 候选);更新 examples 使其读起来像讲义 | **done**(`declare` + `linalg-transpose`) |
|
||||
| **F3** | 可选 postfix / 链式糖;`explicit` 前可选 auto-simplify;public 短文「如何写公式文档」 | **done** |
|
||||
| **F4+** | 新规则(伴随、多项式矩阵…);矩阵微积分仅当明确需要 | 规则表可测 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 示例叙事(目标文档骨架)
|
||||
|
||||
````markdown
|
||||
---
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# 转置反序
|
||||
|
||||
*`A` = > la.symbol name="A" rows=2 cols=3*
|
||||
*`B` = > la.symbol name="B" rows=3 cols=2*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
|
||||
叙述:\((AB)^\top = B^\top A^\top\)。
|
||||
|
||||
*`t` = > `Pt`.ascii*
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=identity-ok
|
||||
2. *
|
||||
> print text=identity-fail
|
||||
````
|
||||
|
||||
计算面示例保持 `examples/linalg-least-squares/`(`lstsq` + heatmap),与代数面示例分目录或分章节。
|
||||
|
||||
---
|
||||
|
||||
## 9. 开放问题
|
||||
|
||||
1. **自动 simplify 是否改变 `ascii` 金样**——凡依赖「未化简乘积串」的测试需改期望或改调 `repr_raw`(若提供)。
|
||||
2. **中文 `_type=矩阵` 与展示**——方法链已 retag;view 是否统一显示英文 kind。
|
||||
3. **`$$` 符号方言**——若做,必须经 `from_formula` 扩展,禁止改核心高中 formula 语义。
|
||||
|
||||
---
|
||||
|
||||
## 10. 收束
|
||||
|
||||
`ext/linalg` 的北极星不是「功能最多的矩阵库」,而是:
|
||||
|
||||
> **让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。**
|
||||
@@ -0,0 +1,346 @@
|
||||
# `ext/linalg` — 公式优先的线性代数扩展
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft · L0–L6 + 中缀 v1 · 公式文档面见专文** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| **公式文档面** | [ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)(跑通即正确 · 代数面/计算面) |
|
||||
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [view.md](view.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
|
||||
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**经典线性代数以「矩阵公式」为一等公民**:抽象表达式可化简、可展示、可选求值;稠密数值与分解图走 ABI 插件——**不**并入 `lib/math`,**不**挂在 `ext/quantum` 作者面。
|
||||
|
||||
作者面北极星见 **[ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)**:跑通即正确;代数面像讲义,计算面是显式步骤。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
1. **公式类扩展**:在现有标量 `formula` 之上,引入 **矩阵表达式(MatExpr)**——`MatrixSymbol`、乘加、转置、逆、迹、行列式、分块、Kronecker——默认**不展开**。
|
||||
2. **大规模优化**:形状检查 + 重写规则 + 惰性求值 + 分解对象复用(见 §5)。
|
||||
3. **易于展示**:KaTeX 公式卡、结构 SVG(SVD/QR/消元/特征)、数值热力图;CLI 可断言的 ASCII。
|
||||
4. **文档即实验**:GFM 表声明矩阵 / 步骤;`.mq.md` 可读可跑。
|
||||
|
||||
### 1.2 非目标(首版)
|
||||
|
||||
| 不做 | 原因 |
|
||||
|------|------|
|
||||
| 塞进 `lib/math` | 高中标量范围已锁定;大学 LA 属官方 ext |
|
||||
| 复用 `quantum.*` 作者 API | 领域混淆;量子 Q7 保持量子语义 |
|
||||
| 完整 SymPy / Mathematica | 规则表可控子集即可 |
|
||||
| 稀疏格式 / GPU / 分布式 | 超出文档语言定位 |
|
||||
| 矩阵微积分闭式(Jacobian 积木) | 记入路线图远期 |
|
||||
| 在 `ext/**` 调 `host_*` | 硬约束;数值走插件名 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层架构
|
||||
|
||||
```text
|
||||
作者 .mq.md
|
||||
│ import la:ext/linalg/linalg.mq.md
|
||||
▼
|
||||
L1 官方 ext(GFM + ## 包装,中英分文件)
|
||||
│ plugin.load name=linalg
|
||||
▼
|
||||
plugins/linalg(ABI v2)
|
||||
├── matexpr:符号树构造 / 重写 / latex
|
||||
├── dense:稠密 f64(可选复数)运算与分解
|
||||
└── draw:结构 SVG / heatmap
|
||||
│
|
||||
▼(可选)
|
||||
核心 Value::Formula 仅保留「数值矩阵字面量」现状;
|
||||
符号 MatExpr 以 **map `_type=matrix`(中文构造为 `矩阵`)** 承载,避免撑爆高中 formula AST;遗留标签 `linalg_expr` / `linalg_dense` 仍可解析。
|
||||
```
|
||||
|
||||
### 2.1 为何 MatExpr 不直接塞进 `formula::Expr`
|
||||
|
||||
| 方案 | 利 | 弊 | 决策 |
|
||||
|------|----|----|------|
|
||||
| 扩展 `formula::Expr` | 与 `$$` 一体 | 核心膨胀;高中/大学边界糊 | ❌ |
|
||||
| 插件侧表达式 + L1 对象 | 核心干净;可独立发版 | 需稳定 `_type` 与 latex 桥 | ✅ **采用** |
|
||||
| 仅 list-of-list 数值 | 简单 | 无法公式优化与符号展示 | ❌ 仅作 `explicit` 结果 |
|
||||
|
||||
**既有** `formula::Expr::Matrix`(数值 `$$`)继续服务量子门 / 小例子;`ext/linalg` 通过 `la.matrix` / `la.from_formula` 吸收为稠密叶子。
|
||||
|
||||
### 2.2 与量子的边界
|
||||
|
||||
| | `ext/linalg` | `ext/quantum` Q7 |
|
||||
|--|--------------|------------------|
|
||||
| 域 | 经典实/复矩阵 | 态 / 密度 / Pauli |
|
||||
| Kronecker | 经典 ⊗ | 复合量子系统 |
|
||||
| 图 | SVD/QR/GE/heatmap | hinton/city/qsphere/… |
|
||||
| 复用 | 插件**私有**可共享 Jacobi/SVD 代码 | 作者面 API **分离** |
|
||||
|
||||
---
|
||||
|
||||
## 3. 运行时对象(锁定草案)
|
||||
|
||||
全部经插件构造,L1 返回 **map**(`_type` 稳定,金样可断言):
|
||||
|
||||
| `_type`(英) | 中文标签 | 字段(最小) | 含义 |
|
||||
|---------------|----------|--------------|------|
|
||||
| `linalg_expr` | `线性式` | `repr`(S-expr 或内部 id)、`shape`=`[m,n]` 或符号维、`latex`、`ascii` | 抽象矩阵公式 |
|
||||
| `linalg_dense` | `稠密阵` | `rows`, `cols`, `data`(行主 list[list])、`dtype`=`real`\|`complex` | 显式数值 |
|
||||
| `linalg_factor` | `分解` | `kind`=`lu`\|`qr`\|`svd`\|`eig`\|`chol`,因子字段,`latex`,可选 `svg` | 分解结果 |
|
||||
| `linalg_svg` | — | `kind`, `svg` 文本 | 与 quantum_svg 同构展示约定 |
|
||||
| `linalg_solve` | `求解` | `x`, `residual`, `method` | 线性系 / 最小二乘 |
|
||||
|
||||
形状:`shape` 允许整数或符号维名(字符串 `"n"`);不相容 → 硬错误。
|
||||
|
||||
---
|
||||
|
||||
## 4. 作者面 API(英文 `ext/linalg/linalg.mq.md`)
|
||||
|
||||
中文镜像:`ext/linalg/线性代数.mq.md`(`矩阵` / `化简` / `求值` / `绘图`…)。
|
||||
|
||||
### 4.1 构造
|
||||
|
||||
```markdown
|
||||
# matrix
|
||||
|
||||
## symbol
|
||||
+ `name`
|
||||
+ `rows`
|
||||
+ `cols`
|
||||
# → linalg_expr MatrixSymbol
|
||||
|
||||
## eye / zeros / ones / diag
|
||||
+ …
|
||||
|
||||
## from_list
|
||||
+ `data` # list[list] 或 table
|
||||
|
||||
## from_formula
|
||||
+ `formula` # 吸收 Value::Formula Matrix 字面量
|
||||
|
||||
## block
|
||||
+ `blocks` # 表或嵌套 list of expr
|
||||
```
|
||||
|
||||
文档写法偏好:
|
||||
|
||||
````markdown
|
||||
`A` = > la.symbol name=A rows=n cols=n
|
||||
|
||||
`b` =
|
||||
$$
|
||||
\begin{pmatrix}1\\0\\0\end{pmatrix}
|
||||
$$
|
||||
|
||||
*`b` = > la.from_formula formula=`b` *
|
||||
````
|
||||
|
||||
作者面优先顶层 `la.symbol` / `la.mul`(`la.matrix.symbol` 无接收者会硬错误,见 [module-namespace.md](module-namespace.md) §4.3)。
|
||||
### 4.2 公式代数(返回 `linalg_expr`,惰性)
|
||||
|
||||
| 英文 | 中文 | 语义 |
|
||||
|------|------|------|
|
||||
| `mul` / `add` / `sub` | `乘` / `加` / `减` | 形状检查后建树 |
|
||||
| `transpose` / `T` | `转置` | |
|
||||
| `inv` | `逆` | 符号逆;不立即求数值 |
|
||||
| `pow` | `幂` | 整数幂 |
|
||||
| `trace` / `det` | `迹` / `行列式` | 可得到标量 expr 或数值 |
|
||||
| `kron` | `克罗内克` | **禁止**默认 expand |
|
||||
| `simplify` | `化简` | 应用 §5 规则集 |
|
||||
| `collapse` | `分块化简` | 对标 `block_collapse` |
|
||||
| `latex` / `ascii` | `乳胶` / `文本` | 展示字符串 |
|
||||
| `shape` | `形状` | |
|
||||
|
||||
链式 / 中缀(v1 已落地):
|
||||
|
||||
```markdown
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`s` = > `Pt`.simplify*
|
||||
```
|
||||
|
||||
运行时对双方为 `matrix` / `矩阵` / 数值 `$$` 矩阵 / 遗留 `linalg_expr` 的 `+` `-` `*` 分派到插件;结果保留左操作数 `_type` 以便中英方法链。
|
||||
### 4.3 求值与分解(热路径 → 稠密)
|
||||
|
||||
| 英文 | 说明 |
|
||||
|------|------|
|
||||
| `eval` / `explicit` | 符号树 + 绑定表 → `linalg_dense`;超维硬错误 |
|
||||
| `factorize` | `kind=lu\|qr\|svd\|eig\|chol` → `linalg_factor` |
|
||||
| `solve` | `A`,`b`;或 `factor` + `b` |
|
||||
| `lstsq` | 最小二乘 |
|
||||
| `rank` / `norm` / `cond` | 数值度量 |
|
||||
| `matmul` | 稠密乘(已 explicit 时) |
|
||||
|
||||
维数上限(草案,可配置):
|
||||
|
||||
| 操作 | 默认上限 |
|
||||
|------|----------|
|
||||
| `explicit` 稠密元素总数 | \(n\cdot m \le 10^4\)(如 100×100) |
|
||||
| SVD / eig 方阵边长 | \(\le 64\)(与 quantum 密度同级) |
|
||||
| 结构 SVG(无元素) | 边长示意可达数百(只画框) |
|
||||
| KaTeX 完整数字阵 | \(\le 8\times 8\);更大只出摘要 + 结构图 |
|
||||
|
||||
### 4.4 展示
|
||||
|
||||
| 英文 | `kind` | 说明 |
|
||||
|------|--------|------|
|
||||
| `show` | — | 写入 view:优先 `latex` 公式卡 |
|
||||
| `draw` | `structure` | 形状/分块矩形(drawmatrix 风格) |
|
||||
| `draw` | `heatmap` / `hinton` | 数值幅度 |
|
||||
| `draw` | `svd` / `qr` / `ge` / `eig` | 分解结构图(对标 LAFigureSpecs) |
|
||||
| `draw` | `path`= | 可选落盘 SVG |
|
||||
|
||||
`show` 应对符号式**始终可用**(无需 `eval`)。
|
||||
|
||||
### 4.5 最小可运行示例(设计验收叙事)
|
||||
|
||||
````markdown
|
||||
---
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`A` = > la.symbol name=A rows=3 cols=3 *
|
||||
*`x` = > la.symbol name=x rows=3 cols=1 *
|
||||
*`b` = > la.mul a=`A` b=`x` *
|
||||
|
||||
*`s` = > la.simplify expr=`b` *
|
||||
> la.show expr=`s`
|
||||
|
||||
`M` =
|
||||
$$
|
||||
\begin{bmatrix}2&0\\0&3\end{bmatrix}
|
||||
$$
|
||||
|
||||
*`M` = > la.from_list data=[[2,0],[0,3]] *
|
||||
*`f` = > la.factorize matrix=`M` kind=eig *
|
||||
> la.draw factor=`f` kind=eig path=eig.svg
|
||||
````
|
||||
---
|
||||
|
||||
## 5. 公式重写与「大规模优化」(核心)
|
||||
|
||||
### 5.1 原则
|
||||
|
||||
1. **构造便宜,展开昂贵**——乘加只分配节点。
|
||||
2. **形状是类型系统**——`(m×k)·(k×n)` 合法;否则错误指向调用点。
|
||||
3. **化简是规则不动点**——有限规则表,可测、可文档化。
|
||||
4. **expand 显式开启**——`expand=True` 才对 Kronecker / 多项式矩阵做爆炸性展开。
|
||||
5. **数值路径旁路符号**——已 `explicit` 的叶子用稠密核,不再走规则。
|
||||
|
||||
### 5.2 v1 规则集(最小够用)
|
||||
|
||||
| ID | 规则 | 例 |
|
||||
|----|------|-----|
|
||||
| R1 | 单位元 | `I*A → A`,`A*I → A`,`A+0 → A` |
|
||||
| R2 | 双逆 | `(A^{-1})^{-1} → A` |
|
||||
| R3 | 转置反序 | `(AB)^\top → B^\top A^\top`,`(A^\top)^\top → A` |
|
||||
| R4 | 逆转置 | `(A^{-1})^\top → (A^\top)^{-1}` |
|
||||
| R5 | 结合扁平 | `MatMul` 链扁平化 |
|
||||
| R6 | 分块塌缩 | 对标 `block_collapse`(乘/加在块级分配) |
|
||||
| R7 | Kronecker 结合 | `(A⊗B)⊗C → A⊗B⊗C`;**不**展开成元素 |
|
||||
| R8 | 标量提出 | `c*(A+B) → c*A+c*B`(可选;默认关以免树变宽) |
|
||||
|
||||
### 5.3 数值侧优化
|
||||
|
||||
| 策略 | 说明 |
|
||||
|------|------|
|
||||
| `factorize` 一次 | 多 RHS `solve` 复用 |
|
||||
| 小阵专用核 | 2×2 / 3×3 闭式逆 / det(教学友好、可对照公式) |
|
||||
| 复杂度护栏 | 超限错误信息建议「保持符号 / 降维 / 分块」 |
|
||||
| 禁止静默降精度 | 病态 `cond` 可警告(stderr 或结果字段) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 展示设计(效果)
|
||||
|
||||
### 6.1 通道
|
||||
|
||||
| 通道 | 符号 MatExpr | 稠密 | 分解 |
|
||||
|------|--------------|------|------|
|
||||
| view Structure | KaTeX `latex` 卡 | 小阵 KaTeX;大阵摘要 | 公式 + 可选 SVG |
|
||||
| view Execution plots | — | heatmap SVG | `kind=svd|…` SVG |
|
||||
| CLI `print` | `ascii` | `[[…],…]` 或摘要 | `svd(U,S,V)` 摘要 |
|
||||
| writeback | 可选记录 latex | 可选 | 可选 |
|
||||
|
||||
### 6.2 LaTeX 约定
|
||||
|
||||
- 符号:`A`,`A^{\top}`,`A^{-1}`,`AB`,`A \otimes B`
|
||||
- 数值小阵:`\begin{bmatrix}…\end{bmatrix}`
|
||||
- 分块:`\begin{bmatrix} A & B \\ C & D \end{bmatrix}`
|
||||
- 喂给既有 view:与 `formula-card` / KaTeX 同源路径(L1 `show` → `host_query("record_plot")` 或扩展「record_math」若已有;无则复用 writeback + plot 列表)
|
||||
|
||||
### 6.3 结构 SVG(教学主视觉)
|
||||
|
||||
对标 LAFigureSpecs / drawmatrix,**不**依赖 Matplotlib:
|
||||
|
||||
| `kind` | 画什么 |
|
||||
|--------|--------|
|
||||
| `structure` | 矩形块 + 标签(零块灰色) |
|
||||
| `svd` | \(U\Sigma V^{\top}\) 块布局 + 秩分隔 |
|
||||
| `qr` | 瘦/胖 QR 示意 |
|
||||
| `ge` | 消元后上三角高亮 |
|
||||
| `eig` | \(A=PDP^{-1}\) 或谱列表 + 对角 |
|
||||
| `heatmap` | 单元填色(实数蓝红;复数幅值) |
|
||||
|
||||
主题:`theme=light|dark|bw`(与 quantum Q8 令牌对齐;默认 `light`)。
|
||||
|
||||
---
|
||||
|
||||
## 7. L1 / 插件 / CLI 约定
|
||||
|
||||
1. **`ext/linalg/**` 禁止 `host_*`**;只调 `plugin.*` 注册名(如 `linalg_simplify`)。
|
||||
2. **中英分文件**,CATALOG 双 id:`linalg` / `线性代数`。
|
||||
3. **`marqdo ext add linalg`**:与 web/agent/quantum 相同——优先 Release 预编译 native zip。
|
||||
4. **金样**:离线、确定性;SVG 断言含关键子串或稳定 hash 前缀。
|
||||
5. **依赖**:插件内自研稠密核(或慎重引入单一 crate,如 `nalgebra`——**实现期再议**;设计默认「可自研小维 + 可选 crate」)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分期(摘要;细节见路线图)
|
||||
|
||||
| 阶段 | 交付 |
|
||||
|------|------|
|
||||
| **L0** | CATALOG + ping + L1 `ensure_plugin` |
|
||||
| **L1** | `matrix.symbol` / dense 构造 / `mul`·`T`·`inv` 树 + `simplify` R1–R5 + `latex`/`show` |
|
||||
| **L2** | `explicit` / 小阵运算 / `solve` / `det`·`trace` 数值 |
|
||||
| **L3** | 分块 + `collapse`;Kronecker 惰性 |
|
||||
| **L4** | `factorize` LU/QR/SVD/eig + 结构 SVG |
|
||||
| **L5** | heatmap/hinton;examples + public 文档 + skill 摘要 |
|
||||
| **L6+** | 矩阵微积分 / 更大 BLAS(仅当用户明确要求);复数全路径算子 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收标准(设计级)
|
||||
|
||||
1. 符号式 `(AB)^\top` 经 `simplify` 得 `B^\top A^\top`,**不**产生稠密数据。
|
||||
2. 不相容形状在符号 `mul` 即失败。
|
||||
3. `$$` 数值阵 → `from_formula` → `factorize kind=eig` → view 含 SVG 或 latex。
|
||||
4. Kronecker 默认不 expand;显式 `expand` 受维数护栏。
|
||||
5. 中英 L1 金样各至少一条;`ext add linalg` 路径文档化。
|
||||
6. 与 `ext/quantum` 无作者面符号冲突。
|
||||
|
||||
---
|
||||
|
||||
## 10. 风险与开放问题
|
||||
|
||||
| 项 | 备注 |
|
||||
|----|------|
|
||||
| MatExpr 序列化 | 金样 / write:倾向可打印 S-expr 或稳定 latex+shape,避免不透明指针跨进程 |
|
||||
| 与标量 `formula` 混运算 | v1:标量只作 `c*A` 系数;`det` 结果若符号则另型或降为 `formula` 文本 |
|
||||
| nalgebra 等依赖 | 实现 L2 时评估二进制体积与 ABI 体积 |
|
||||
| record_math vs plot | 若仅 SVG/KaTeX 字符串,可先复用 plot/writeback |
|
||||
|
||||
---
|
||||
|
||||
## 11. 一句话(收束)
|
||||
|
||||
**`ext/linalg` 让线性代数公式保持可优化的表达式,用规则与结构图服务文档阅读,用受控稠密核服务验算——公式优先,数值可选,展示分层。**
|
||||
+76
-52
@@ -2,84 +2,108 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted (v0.1.x) |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
|
||||
| Status | **Accepted · v0.3 semantic**(005:Intelligence Primitive) |
|
||||
| Date | 2026-09-24 |
|
||||
| Related | [objects.md](objects.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) · [ai-stack.md](../roadmap/ai-stack.md) · [doc/next/005.md](../next/005.md) |
|
||||
|
||||
## Scope
|
||||
|
||||
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
|
||||
`ext/ai/llm` is Marqdo’s **intelligence primitive**, not an OpenAI SDK wrapper.
|
||||
|
||||
```text
|
||||
Author surface: ask / stream / collect / create / fast / reasoning / prompt_load
|
||||
Transport: ext/ai/llm/openai.mq.md (+ ollama defaults)
|
||||
Compat: complete / chat
|
||||
```
|
||||
|
||||
Import:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
|
||||
|
||||
Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
|
||||
Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` / `done` / `error`); `echo=True` prints thinking (`reasoning_content`) and answer tokens as they arrive. See [agent-streaming.md](../roadmap/agent-streaming.md). Default (`stream=False`) is unchanged (answer string).
|
||||
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `import llm:ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
## Platform prerequisites
|
||||
|
||||
| Capability | Surface |
|
||||
|------------|---------|
|
||||
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
|
||||
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
|
||||
| JSON quote | `lib/json` → `quote` |
|
||||
|
||||
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
|
||||
## Public API
|
||||
|
||||
| English | Chinese | Role |
|
||||
|---------|---------|------|
|
||||
| `## load_env` | `## 加载环境` | Free function: load `.env` |
|
||||
| `## stream_result` | `## 流式结果` | Collapse event list → final text |
|
||||
| `# llm` | `# 大模型` | Object ctor → handle map |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods; optional `stream` / `流式`, `echo` / `打印增量` |
|
||||
| `## load_env` | `## 加载环境` | Load `.env` |
|
||||
| `## create` | `## 创建` | Factory → LLM handle |
|
||||
| `## fast` / `## reasoning` | `## 快速` / `## 推理` | Named handles |
|
||||
| `## prompt_load` / `## prompt` / `## prompt_body` | `## 加载提示` / `## 提示` / `## 提示正文` | Prompt artifacts (`type: prompt` → body) |
|
||||
| `## ask` (module) | `## 提问` | Convenience → **text** (`prompt=` or `path=`) |
|
||||
| `## collect` | `## 收集` | Events → text |
|
||||
| `## stream_result` | `## 流式结果` | Alias of `collect` |
|
||||
| `# llm` | `# 大模型` | Handle ctor (`backend=` openai-compatible \| ollama) |
|
||||
| `## ask` (method) | `## 提问` | → **LLMResult** map |
|
||||
| `## stream` | `## 流式` | → event list |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Compat / transport primitive |
|
||||
|
||||
### Preferred
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/ai/llm.mq.md
|
||||
---
|
||||
**answer = > llm.ask prompt="What is Marqdo?"**
|
||||
*answer*
|
||||
|
||||
# main
|
||||
**model = > llm.create**
|
||||
**result = > `model`.ask prompt=`prompt`**
|
||||
*[text](result)*
|
||||
|
||||
> load_env
|
||||
**fast = > llm.fast**
|
||||
**events = > `fast`.stream prompt=`prompt`**
|
||||
**text = > llm.collect events=`events`**
|
||||
|
||||
*`model` = > llm *
|
||||
*`reply` = > `model`.complete prompt=Say hi in one word *
|
||||
> print text=`reply`
|
||||
|
||||
*`events` = > `model`.complete prompt=Say hi stream=True *
|
||||
- [`ev`](`events`)
|
||||
*`t` = > json.get value=`ev` key=type *
|
||||
1. `t` == "delta"
|
||||
*`chunk` = > json.get value=`ev` key=text *
|
||||
> print text=`chunk`
|
||||
2. *
|
||||
*`_` = 1*
|
||||
**body = > llm.prompt path="fixtures/prompt-marqdo.md"**
|
||||
**body2 = > llm.prompt text=`raw`**
|
||||
```
|
||||
|
||||
Environment (create a **project-local** `.env`; do not commit secrets):
|
||||
### LLMResult
|
||||
|
||||
| Field | Meaning |
|
||||
|-------|---------|
|
||||
| `text` | Answer string |
|
||||
| `model` | Model id |
|
||||
| `finish` | Finish reason (`stop`, …) |
|
||||
| `backend` | e.g. `openai-compatible` / `ollama` |
|
||||
| `usage` | `{prompt_tokens,completion_tokens,total_tokens}` |
|
||||
| `tokens` | Alias of `usage.total_tokens` (agent metrics) |
|
||||
| `name` | Optional handle tag (`fast` / `reasoning`) |
|
||||
| `llm_calls` | `1` per ask |
|
||||
| `tool_calls` | List of OpenAI-shaped tool call objects (empty when none) |
|
||||
|
||||
### Compat
|
||||
|
||||
`complete` / `chat` still return a bare string (or event list when `stream=True`) so `ext/ai/agent` and older runbooks keep working. **New code should use `ask` / `stream` / `collect`.**
|
||||
|
||||
## Environment
|
||||
|
||||
```env
|
||||
OPENAI_API_KEY=sk-...
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
MARQDO_LLM_FAST_MODEL=...
|
||||
MARQDO_LLM_REASONING_MODEL=...
|
||||
OLLAMA_HOST=http://127.0.0.1:11434/v1
|
||||
```
|
||||
|
||||
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
|
||||
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`. Ctor also accepts `api_key=` / `base_url=` / `model=` / `backend=`.
|
||||
|
||||
## Backends
|
||||
|
||||
| `backend=` | Module | Notes |
|
||||
|------------|--------|-------|
|
||||
| `openai-compatible` (default) | `ext/ai/llm/openai.mq.md` | Chat Completions HTTP + SSE |
|
||||
| `ollama` | defaults in ctor + same transport | Key defaults to `ollama`; host from `OLLAMA_HOST` |
|
||||
|
||||
## Tests
|
||||
|
||||
- Import smoke: `tests/ext/llm-import.mq.md`
|
||||
- Offline stream: `tests/ext/llm-stream-offline.mq.md` + `tests/lib/net-openai-sse.mq.md`
|
||||
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
|
||||
- Live agent `## step`: `tests/ext/agent-run-live.mq.md` (DeepSeek; gold: `ext_agent_run_live`)
|
||||
- Agent smoke (real `llm` handle): `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
|
||||
- Live complete: `tests/ext/llm-complete.mq.md` (gold: `ext_llm_complete_live`)
|
||||
|
||||
- `tests/ext/llm-import.mq.md`
|
||||
- `tests/ext/llm-ctor-offline.mq.md`
|
||||
- `tests/ext/llm-ask-offline.mq.md` (create + collect)
|
||||
- `tests/ext/llm-stream-offline.mq.md`
|
||||
- `tests/ext/llm-named-offline.mq.md` (fast/reasoning + prompt_load)
|
||||
- `tests/ext/llm-tool-calls-offline.mq.md` (`tool_calls_from` / Result field)
|
||||
- `tests/ext/llm-meta-offline.mq.md` · `llm-entry-prompt-offline.mq.md`
|
||||
- Live: `llm-complete.mq.md` · `llm-stream-live.mq.md`
|
||||
Loaded 100 of 1729 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user