Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
a3948dbe0d | ||
|
|
24959a0ba8 | ||
|
|
afbb9f191c | ||
|
|
8db699191e | ||
|
|
e5580d9640 | ||
|
|
9ce2ae1037 | ||
|
|
166b01c86b | ||
|
|
87cfe05095 | ||
|
|
b37387e6da | ||
|
|
895752a1fd | ||
|
|
38c07d9a0e | ||
|
|
a7a5554c0f | ||
|
|
343504c7a8 | ||
|
|
3d9fa0da96 | ||
|
|
bb8960c5eb | ||
|
|
9331af78e2 | ||
|
|
73bf574a55 | ||
|
|
4fae71342d | ||
|
|
63d60e3ba1 | ||
|
|
44d2928c06 | ||
|
|
fa832268b3 | ||
|
|
9576188a2e | ||
|
|
528a1f0dbc | ||
|
|
a11b347659 | ||
|
|
8e437e2cd3 | ||
|
|
23229a6ac9 | ||
|
|
58b65215a1 | ||
|
|
92c3f80055 | ||
|
|
8a66f803cb | ||
|
|
3ce59a4da8 | ||
|
|
90688741c5 | ||
|
|
70b88b3767 | ||
|
|
f859e6eeea | ||
|
|
6705e2e6b7 | ||
|
|
6e8a62928b | ||
|
|
398a0b7222 | ||
|
|
e8f1a3e126 | ||
|
|
8ea56cbe30 | ||
|
|
8085d06124 | ||
|
|
6f929dc2da | ||
|
|
dd22180269 | ||
|
|
cc48bf6d05 | ||
|
|
19f986953a | ||
|
|
770dee5199 | ||
|
|
f6612813e3 | ||
|
|
643ea06340 | ||
|
|
0cd64a7450 | ||
|
|
981faac022 | ||
|
|
f818834ec1 | ||
|
|
8d47507d15 | ||
|
|
1e1f05c087 | ||
|
|
06e61efc51 | ||
|
|
2dfa0b2a5b | ||
|
|
629ad8ed39 | ||
|
|
ee677478be | ||
|
|
edbf241d99 | ||
|
|
add6a7d32c | ||
|
|
c64ec99115 | ||
|
|
60a3b84a84 | ||
|
|
02a4f2d20d | ||
|
|
88490e3092 | ||
|
|
9031c106a1 | ||
|
|
633436e40f | ||
|
|
cf73fcf1ef | ||
|
|
e48fd5b0f4 | ||
|
|
b2f97e72c3 | ||
|
|
c7c0f66d1f | ||
|
|
d5ab9daebb | ||
|
|
5795236d1f | ||
|
|
e8d6dc92fc | ||
|
|
afe31cb2a8 | ||
|
|
905a67df32 | ||
|
|
f63b7ef48d | ||
|
|
393558ca97 | ||
|
|
0d9bd99fc0 | ||
|
|
a0c779e022 | ||
|
|
a82b6fdde1 | ||
|
|
3613ed7c4e | ||
|
|
9564dff777 | ||
|
|
f56deffefe | ||
|
|
bdedf3ecd8 | ||
|
|
b0ee958fcf | ||
|
|
e64f6b23b4 | ||
|
|
eed4f05ea4 | ||
|
|
d88ed274ed | ||
|
|
7fdd97f675 | ||
|
|
c299efe589 | ||
|
|
b3867c46db | ||
|
|
1a39a53d93 | ||
|
|
6d6f580d24 | ||
|
|
af05f19301 | ||
|
|
3201369470 | ||
|
|
05197378b3 | ||
|
|
f3b3152f07 | ||
|
|
22364f2f1b | ||
|
|
b69a90501d | ||
|
|
7ff881f506 | ||
|
|
9acbe10986 | ||
|
|
81989a26d7 | ||
|
|
cf0ba6dccd | ||
|
|
0de703f86a | ||
|
|
4907f92d84 | ||
|
|
eac6921524 | ||
|
|
c0dc18433b | ||
|
|
7d9af11398 | ||
|
|
d9aef957f7 | ||
|
|
aa0c4d0f55 | ||
|
|
c50c515c4a | ||
|
|
16c44588d5 | ||
|
|
5080136d65 | ||
|
|
cc5277d2b5 | ||
|
|
bb06dad134 | ||
|
|
24dcb97354 | ||
|
|
76aa02846a | ||
|
|
0e389f34ec | ||
|
|
492790e985 | ||
|
|
ca434a8bab | ||
|
|
6195ad1d5d | ||
|
|
a87c2154ff | ||
|
|
8f1010f967 | ||
|
|
e3d9021bb6 | ||
|
|
142ab523d6 | ||
|
|
82c8d78fd3 | ||
|
|
58791fc7d9 | ||
|
|
1730f26fc7 | ||
|
|
4018e9928a | ||
|
|
628e3b6e5d | ||
|
|
5c6c612edd | ||
|
|
41587f319e | ||
|
|
298fbd51ea | ||
|
|
265dfdbcc4 | ||
|
|
42a43f5ffd | ||
|
|
037a963547 | ||
|
|
a32638e935 | ||
|
|
43eebe5671 | ||
|
|
e833dc05e2 | ||
|
|
11bb7ef277 | ||
|
|
6bd90bb2d0 | ||
|
|
4683f2e067 | ||
|
|
5912164039 | ||
|
|
303c06f773 | ||
|
|
a1086fd6c3 | ||
|
|
6ffe5ceb19 | ||
|
|
6b568aff3d | ||
|
|
16f26d7d60 | ||
|
|
b8265a92aa | ||
|
|
9af929971c | ||
|
|
2c4fa4bb05 | ||
|
|
3cabe53da2 | ||
|
|
58e13ee6d3 | ||
|
|
1b11fe063a | ||
|
|
b792f44556 | ||
|
|
9ea5bebfc3 | ||
|
|
c7c329341b | ||
|
|
8cf5288481 | ||
|
|
69c4e74872 | ||
|
|
af0bda2e40 | ||
|
|
090b026547 | ||
|
|
03396afd02 | ||
|
|
663a8ba2c0 | ||
|
|
dc853fb580 | ||
|
|
0b80ff8e50 | ||
|
|
b8a4ddd38f | ||
|
|
352bc0d2c5 | ||
|
|
8a6d09d582 | ||
|
|
dcd3d329d4 | ||
|
|
0e1bfb3359 | ||
|
|
e9ae7ff1ae | ||
|
|
ecbdd18303 | ||
|
|
bedd53e212 | ||
|
|
7674ebb869 | ||
|
|
434be9fd52 | ||
|
|
ae97891266 | ||
|
|
aea86746e7 | ||
|
|
c773503938 | ||
|
|
939e23ee88 | ||
|
|
687c168014 | ||
|
|
eac9b45263 | ||
|
|
74b298e80d | ||
|
|
fc7097bae4 | ||
|
|
b624084745 | ||
|
|
0bbe735c3c | ||
|
|
92de46aca4 | ||
|
|
8bbe017a5e | ||
|
|
1a13989230 | ||
|
|
5ad1a07f5c | ||
|
|
bcfc763ba4 | ||
|
|
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.
|
||||
@@ -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))
|
||||
@@ -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,46 @@
|
||||
name: Build cinematic Markdown-to-execution video
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [docs/markdown-execution-cinematic-v2]
|
||||
paths:
|
||||
- "scripts/render-markdown-execution-promo.py"
|
||||
- ".github/workflows/build-markdown-execution-video.yml"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
video:
|
||||
if: github.ref_name == 'docs/markdown-execution-cinematic-v2'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 25
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: true
|
||||
- name: Prepare fonts, Chrome and Python tools
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y -qq ffmpeg fonts-noto-cjk
|
||||
python -m pip install --quiet pillow numpy markdown-it-py selenium
|
||||
google-chrome --version
|
||||
- name: Render promo video from two original images and Marqdo source
|
||||
run: python scripts/render-markdown-execution-promo.py
|
||||
- name: Check resulting video
|
||||
run: |
|
||||
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4
|
||||
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg
|
||||
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution.srt
|
||||
ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height -of json assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4
|
||||
- name: Commit compiled video, poster and subtitles
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git add assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4 \
|
||||
assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg \
|
||||
assets/marketing/marqdo-2.7.1-markdown-to-execution.srt \
|
||||
assets/marketing/marqdo-procurement-standard-markdown.png
|
||||
git diff --cached --quiet || git commit -m "docs: publish cinematic Markdown-to-execution promotional film"
|
||||
git push origin HEAD:docs/markdown-execution-cinematic-v2
|
||||
@@ -0,0 +1,48 @@
|
||||
name: capture-procurement-marketing-assets
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [docs/executable-skill-showcase-271]
|
||||
paths:
|
||||
- "scripts/capture-procurement-showcase.py"
|
||||
- ".github/workflows/capture-procurement-marketing.yml"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
capture:
|
||||
if: github.ref_name == 'docs/executable-skill-showcase-271'
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: true
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.11"
|
||||
- name: Prepare Chrome, Chinese fonts and Python imaging
|
||||
run: |
|
||||
python -m pip install --quiet pillow selenium
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y -qq fonts-noto-cjk
|
||||
google-chrome --version
|
||||
- name: Download Marqdo v2.7.1 Linux release
|
||||
run: |
|
||||
mkdir -p /tmp/marqdo-marketing-cli
|
||||
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo-marketing.zip
|
||||
unzip -q /tmp/marqdo-marketing.zip -d /tmp/marqdo-marketing-cli
|
||||
BIN="$(find /tmp/marqdo-marketing-cli -type f -name marqdo | head -n 1)"
|
||||
test -n "$BIN"
|
||||
chmod +x "$BIN"
|
||||
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
|
||||
- name: Record real command outputs and capture real View
|
||||
run: python scripts/capture-procurement-showcase.py --cli "$CLI_BIN"
|
||||
- name: Commit reproducible promotional assets
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git add assets/marketing/procurement-cli.gif assets/marketing/procurement-view.png
|
||||
git diff --cached --quiet || git commit -m "docs: capture live procurement CLI GIF and View screenshot"
|
||||
git push origin HEAD:docs/executable-skill-showcase-271
|
||||
@@ -0,0 +1,50 @@
|
||||
name: executable-knowledge
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Build agent + llm plugins (EK / workbench gates)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_agent --locked
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
- name: Native agent choice and bounded recovery unit tests
|
||||
run: cargo test -p marqdo_plugin_agent --locked
|
||||
- name: Check short AI flow documents
|
||||
run: |
|
||||
cargo run --locked -- check ext/ai/flow.mq.md
|
||||
cargo run --locked -- check ext/ai/recovery.mq.md
|
||||
cargo run --locked -- check ext/ai/context.mq.md
|
||||
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
|
||||
cargo run --locked -- check ext/ai/workflow.mq.md
|
||||
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
|
||||
- name: Native AI flow interpreter smoke (offline)
|
||||
env:
|
||||
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
|
||||
run: |
|
||||
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
|
||||
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
|
||||
- name: Workbench contracts (M00–M06 / F-subset)
|
||||
run: cargo test --test workbench_contracts --locked
|
||||
- name: Offline executable-knowledge gate
|
||||
run: cargo test --test executable_knowledge --locked
|
||||
- name: Isolated execute MR-01 (dual 60s SSE + short reads)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
bash scripts/build-web-plugin.sh
|
||||
cargo test --test isolated_execute_mr01 --locked -- --nocapture
|
||||
timeout-minutes: 5
|
||||
- name: no ignored tests counted as success
|
||||
run: |
|
||||
if grep -n '#\[ignore\]' tests/executable_knowledge.rs; then
|
||||
echo "executable_knowledge must not use #[ignore] as success evidence" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "ok: no #[ignore] in executable_knowledge gate"
|
||||
@@ -0,0 +1,68 @@
|
||||
# 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: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json
|
||||
- name: Attach source and Windows native packs without replacement
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
|
||||
|
||||
linux:
|
||||
runs-on: ubuntu-latest
|
||||
needs: windows
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
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.read,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,40 @@
|
||||
name: native-ai-flow
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- feat/native-ai-flow-recovery-20261118
|
||||
pull_request:
|
||||
paths:
|
||||
- 'plugins/agent/**'
|
||||
- 'ext/ai/flow.mq.md'
|
||||
- 'ext/ai/context.mq.md'
|
||||
- 'ext/ai/recovery.mq.md'
|
||||
- 'ext/ai/workflow.mq.md'
|
||||
- 'tests/ext/ai-native-*.mq.md'
|
||||
- '.github/workflows/native-ai-flow.yml'
|
||||
|
||||
jobs:
|
||||
agent:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Build the agent plugin
|
||||
run: cargo build -p marqdo_plugin_agent --locked
|
||||
- name: Run native agent and workflow tests
|
||||
run: cargo test -p marqdo_plugin_agent --locked
|
||||
- name: Check the public Marqdo ABI libraries
|
||||
run: |
|
||||
cargo run --locked -- check ext/ai/flow.mq.md
|
||||
cargo run --locked -- check ext/ai/context.mq.md
|
||||
cargo run --locked -- check ext/ai/recovery.mq.md
|
||||
cargo run --locked -- check ext/ai/workflow.mq.md
|
||||
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
|
||||
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
|
||||
- name: Exercise offline integration through Marqdo
|
||||
env:
|
||||
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
|
||||
run: |
|
||||
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
|
||||
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
|
||||
@@ -0,0 +1,28 @@
|
||||
name: procurement-example-smoke
|
||||
on:
|
||||
push:
|
||||
branches: [main, docs/executable-skill-showcase-271]
|
||||
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
|
||||
pull_request:
|
||||
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
|
||||
jobs:
|
||||
smoke:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Fetch released v2.7.1 Linux CLI
|
||||
run: |
|
||||
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo.zip
|
||||
unzip -q /tmp/marqdo.zip -d /tmp
|
||||
BIN="$(find /tmp -type f -name marqdo | head -n 1)"
|
||||
test -n "$BIN"
|
||||
chmod +x "$BIN"
|
||||
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
|
||||
- name: Check and run procurement skill
|
||||
run: |
|
||||
"$CLI_BIN" check examples/procurement/index.mq.md
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 查询余额 已花费=120 --json
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/allowed.json
|
||||
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/denied.json
|
||||
grep -q '本地模拟' /tmp/allowed.json
|
||||
grep -q '采购金额超过' /tmp/denied.json
|
||||
@@ -0,0 +1,43 @@
|
||||
name: Build Marqdo promotional video
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [docs/promo-video-271]
|
||||
paths:
|
||||
- scripts/make-procurement-promo.py
|
||||
- .github/workflows/promo-video.yml
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build-video:
|
||||
if: github.ref_name == 'docs/promo-video-271'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: true
|
||||
- name: Prepare video environment
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -qq -y ffmpeg fonts-noto-cjk
|
||||
python -m pip install --quiet --disable-pip-version-check pillow numpy
|
||||
ffmpeg -version | head -n 2
|
||||
- name: Compose 32-second Marqdo video
|
||||
run: python scripts/make-procurement-promo.py
|
||||
- name: Verify deliverable
|
||||
run: |
|
||||
test -s assets/marketing/marqdo-2.7.1-promo.mp4
|
||||
test -s assets/marketing/marqdo-2.7.1-poster.jpg
|
||||
test -s assets/marketing/marqdo-2.7.1-promo.srt
|
||||
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 assets/marketing/marqdo-2.7.1-promo.mp4
|
||||
- name: Commit video into promotional branch
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git add assets/marketing/marqdo-2.7.1-promo.mp4 assets/marketing/marqdo-2.7.1-poster.jpg assets/marketing/marqdo-2.7.1-promo.srt
|
||||
git diff --cached --quiet || git commit -m "docs: render Marqdo 2.7.1 promotional video from existing assets"
|
||||
git push origin HEAD:docs/promo-video-271
|
||||
@@ -0,0 +1,115 @@
|
||||
# 判定流水线(marqdo prove)
|
||||
#
|
||||
# 验证「SKILL 编排文档 → Lean 4 → 自动证明」全链路:
|
||||
# 1. 构建内置 Lean 底座(MarqdoProof.lean)。
|
||||
# 2. 跑判定矩阵(tests/prove_lean.rs):真定理 proved、假定理 unproved、
|
||||
# 证书缓存命中跳判定、--require-lean 退出码。
|
||||
# 3. CI 硬性要求(MARQDO_PROOF_REQUIRE_LEAN=1):没有工具链即失败,
|
||||
# 不允许悄悄降级成 unverified。
|
||||
#
|
||||
# 说明:仓库不强制贡献者装 Lean——本工作流在装有 elan 的 runner 上运行;
|
||||
# 本地无 Lean 时判定状态为 unverified(advisory,不阻塞)。
|
||||
name: proof
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "src/prove/**"
|
||||
- "doc/verification/skill-proof/**"
|
||||
- "lib/**"
|
||||
- "tests/prove*.rs"
|
||||
- ".github/workflows/proof.yml"
|
||||
pull_request:
|
||||
paths:
|
||||
- "src/prove/**"
|
||||
- "doc/verification/skill-proof/**"
|
||||
- "lib/**"
|
||||
- "tests/prove*.rs"
|
||||
- ".github/workflows/proof.yml"
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
proof:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust (1.81)
|
||||
run: |
|
||||
rustup toolchain install 1.81.0 --profile minimal
|
||||
rustup default 1.81.0
|
||||
|
||||
# leanprover/lean-action@v1 已移除 lean4-version;本仓库运行时只需 lean 二进制
|
||||
# (底座内嵌、不经 lake)。用 elan 钉 v4.35.0,与 doc/verification/skill-proof/lean-toolchain 一致。
|
||||
- name: Install Lean 4.35.0 (elan)
|
||||
run: |
|
||||
curl -sSf https://elan.lean-lang.org/elan-init.sh | sh -s -- -y --default-toolchain leanprover/lean4:v4.35.0
|
||||
echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
|
||||
"$HOME/.elan/bin/lean" --version
|
||||
|
||||
- name: Verify embedded proof library
|
||||
run: |
|
||||
chmod +x scripts/check-proof-library.sh
|
||||
scripts/check-proof-library.sh
|
||||
|
||||
- name: Build
|
||||
run: cargo build --locked
|
||||
|
||||
- name: Judgment matrix (real Lean; CI requires toolchain)
|
||||
env:
|
||||
MARQDO_PROOF_REQUIRE_LEAN: "1"
|
||||
run: cargo test --locked --test prove_lean
|
||||
|
||||
- name: Rest of prove suite (no toolchain assumptions)
|
||||
run: cargo test --locked --test prove
|
||||
|
||||
- name: Corpus monotonicity — offline_checked ⊆ lean_proved (40 fixtures)
|
||||
env:
|
||||
MARQDO_PROOF_REQUIRE_LEAN: "1"
|
||||
run: cargo test --locked --test prove_corpus
|
||||
|
||||
- name: T4 differential consistency — interpreter == Lean
|
||||
env:
|
||||
MARQDO_PROOF_REQUIRE_LEAN: "1"
|
||||
run: cargo test --locked --test conformance
|
||||
|
||||
- name: Full sweep — divergence guard bites on injected fault
|
||||
env:
|
||||
MARQDO_PROOF_REQUIRE_LEAN: "1"
|
||||
run: |
|
||||
# A3:注入分歧必须显式失败(error[proof.divergence],退 1)——
|
||||
# 护栏失灵(静默落绿)比单点失败严重得多。
|
||||
set -e
|
||||
tmp=$(mktemp -d)
|
||||
cat > "$tmp/审批.mq.md" <<'FIXTURE'
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
# 台账
|
||||
|
||||
## 记录
|
||||
+ `金额`
|
||||
|
||||
| 定理 | 结论 | 策略 |
|
||||
|---|---|---|
|
||||
| 记过即记 | 长度(轨迹) = 1 | auto |
|
||||
|
||||
**结果 = [登记](result.ok(value=`金额`))**
|
||||
|
||||
*结果*
|
||||
FIXTURE
|
||||
set +e
|
||||
out=$(cargo run --locked -- prove "$tmp/审批.mq.md" --fault-inject offline-claim --json 2>/dev/null)
|
||||
code=$?
|
||||
echo "$out" | head -c 400
|
||||
if [ "$code" -ne 1 ]; then
|
||||
echo "::error::注入分歧未被拦截(exit=$code)——单调性护栏失灵"
|
||||
exit 1
|
||||
fi
|
||||
echo "$out" | grep -q "proof.divergence" || {
|
||||
echo "::error::未出现 proof.divergence 诊断"
|
||||
exit 1
|
||||
}
|
||||
echo "divergence guard OK"
|
||||
@@ -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 }}
|
||||
@@ -1,5 +1,7 @@
|
||||
/target/
|
||||
/dist/
|
||||
# Plugin unit tests use package-relative scratch checkpoints.
|
||||
/plugins/agent/target/
|
||||
|
||||
# Copied by gold harness for ABI plugins
|
||||
/tests/lib/demo.dll
|
||||
@@ -23,7 +25,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 +44,7 @@ spike/.pytest_cache/
|
||||
*.pyc
|
||||
|
||||
# Built browser WASM (rebuild via crates/marqdo-wasm README)
|
||||
/examples/browser-hello/marqdo_wasm.wasm
|
||||
/examples/browser-hello/pkg/
|
||||
/examples/web-client-site/static/marqdo_wasm.wasm
|
||||
/examples/browser-app/marqdo_wasm.wasm
|
||||
/examples/browser-media/marqdo_wasm.wasm
|
||||
|
||||
# Local sqlite / scratch
|
||||
/data/
|
||||
@@ -62,8 +62,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
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.3.3"
|
||||
version = "2.8.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -12,14 +12,20 @@ name = "marqdo"
|
||||
path = "src/main.rs"
|
||||
required-features = ["cli"]
|
||||
|
||||
# Lean 判定集成测试(独立目标:缓存/判定/退出码矩阵,见 tests/prove_lean.rs)。
|
||||
[[test]]
|
||||
name = "prove_lean"
|
||||
path = "tests/prove_lean.rs"
|
||||
required-features = ["cli"]
|
||||
|
||||
[features]
|
||||
default = ["native"]
|
||||
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
|
||||
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 +35,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,260 @@
|
||||
# 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="#one-markdown-file-three-views-real-execution">56s film</a> ·
|
||||
<a href="#quickstart--one-function-one-command">Quickstart</a> ·
|
||||
<a href="#a-procurement-skill-with-a-600-budget">Procurement demo</a> ·
|
||||
<a href="#explore-the-view">View</a> ·
|
||||
<a href="doc/library-development.mq.md">Guide</a> ·
|
||||
<a href="https://www.marqdo.com/">Website</a> ·
|
||||
<a href="doc/releases/v2.7.1.md">Release notes</a>
|
||||
</p>
|
||||
|
||||
## One Markdown file. Three views. Real execution.
|
||||
|
||||
[](assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4)
|
||||
|
||||
**[▶ Watch the 56-second film](assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4)** · [Bilingual captions](assets/marketing/marqdo-2.7.1-markdown-to-execution.srt) · [Reproducible video source](scripts/render-markdown-execution-promo.py)
|
||||
|
||||
> **The point is not to invent a new document format.** A `.mq.md` file uses Markdown headings, paragraphs and tables. Ordinary Markdown renderers still show a readable document. Marqdo adds explicit execution semantics and a View that can inspect functions, values and their relationships on the same document.
|
||||
|
||||

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

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

|
||||
|
||||
<sub>**Original View screenshot provided by the project author.** Notice the natural document typography, values in the margins, and curved connections originating from function calls in the prose. [Additional automated View capture](assets/marketing/procurement-view.png) · [Static Markdown rendering](assets/marketing/marqdo-procurement-standard-markdown.png).</sub>
|
||||
|
||||
## One document, multiple uses
|
||||
|
||||
| Prompt-oriented agent skill | Marqdo executable skill |
|
||||
|---|---|
|
||||
| Natural-language tool instructions | Natural-language guidance **and** executable functions |
|
||||
| Description and code often separated | Heading, parameter table, return table and implementation in one `.mq.md` |
|
||||
| Validation may require separate wiring | Named function calls can be checked, executed and tested |
|
||||
| Prompts ask a model to comply | Runtime permissions control **declared** effects of a function call |
|
||||
| Hard to follow implementation through files | View links readable content and implementation details |
|
||||
|
||||
Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior.
|
||||
|
||||
**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.1](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/)
|
||||
|
||||
---
|
||||
|
||||
## Deep dive · 语言、设计与执行系统
|
||||
|
||||
标准库单文件本身就是手册:直接阅读[文件库](lib/文件.mq.md)、[集合库](lib/表.mq.md)等源码,按函数标题下的参数表、返回契约和动作说明调用;[工程实践](examples/stdlib-handbook/索引.mq.md)演示文件整理、CSV 汇总与文档维护。
|
||||
开发标准库和拓展库请直接阅读[可执行库开发指南](doc/library-development.mq.md):契约表、叙述式实现、遮蔽调用与多文件工程组织均有可运行示范。
|
||||
|
||||
当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。
|
||||
|
||||
独立拓展包 **2.8.1**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.1.md)。
|
||||
|
||||
CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available.
|
||||
|
||||
Ext pack **2.8.1** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`.
|
||||
|
||||
## 核心优势:可执行知识(Executable Knowledge)
|
||||
|
||||
> **Knowledge That Can Run —— 知识即可执行。**
|
||||
> 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. **知识可证明**:知识文件内的定理表 → Lean 4 定理 → 自动判定(`marqdo prove`);离线符号执行与 Lean 单调一致,分歧显式报错——Trusted Knowledge,判定器缺陷优先于任何绿灯。
|
||||
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
|
||||
|
||||
---
|
||||
|
||||
@@ -23,23 +271,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 +301,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 +324,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 +381,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 +395,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 +407,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 +533,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)
|
||||
---
|
||||
|
||||
|
After Width: | Height: | Size: 132 KiB |
@@ -0,0 +1,35 @@
|
||||
1
|
||||
00:00:00,000 --> 00:00:04,800
|
||||
Your SKILL is now a TOOL.
|
||||
让 Markdown 直接承载可执行语义。
|
||||
|
||||
2
|
||||
00:00:04,800 --> 00:00:11,600
|
||||
源码态:标题、段落、表格都沿用 Markdown。
|
||||
执行逻辑就在文档之中。
|
||||
|
||||
3
|
||||
00:00:11,600 --> 00:00:18,000
|
||||
渲染态:同一份代码也能成为普通 Markdown 文档。
|
||||
|
||||
4
|
||||
00:00:18,000 --> 00:00:25,000
|
||||
源码态、标准 Markdown 渲染态、Marqdo View 态。
|
||||
三种视图,同一份源文件。
|
||||
|
||||
5
|
||||
00:00:25,000 --> 00:00:32,500
|
||||
一份 .mq.md,既可以阅读,也可以编译执行。
|
||||
|
||||
6
|
||||
00:00:32,500 --> 00:00:42,000
|
||||
真实 View 截图:函数调用和值沿着优雅曲线呈现。
|
||||
|
||||
7
|
||||
00:00:42,000 --> 00:00:50,800
|
||||
预算校验不是文字承诺,而是函数执行。
|
||||
模拟订单通过或拒绝,均由运行时返回结果。
|
||||
|
||||
8
|
||||
00:00:50,800 --> 00:00:56,000
|
||||
Marqdo 2.7.1 · github.com/cflmy/marqdo
|
||||
|
After Width: | Height: | Size: 78 KiB |
@@ -0,0 +1,29 @@
|
||||
1
|
||||
00:00:00,000 --> 00:00:03,900
|
||||
Your SKILL is now a TOOL.
|
||||
让 SKILL 真正成为工具。
|
||||
|
||||
2
|
||||
00:00:03,900 --> 00:00:09,000
|
||||
One readable document. Callable business logic.
|
||||
规则、数据、工具在同一份文档里。
|
||||
|
||||
3
|
||||
00:00:09,000 --> 00:00:17,400
|
||||
Five verified CLI calls, from quote to decision.
|
||||
真实 CLI 结果:询价、预算、模拟发单。
|
||||
|
||||
4
|
||||
00:00:17,400 --> 00:00:23,400
|
||||
¥120 spent: mock order. ¥360 spent: rejected.
|
||||
¥120 时模拟通过;¥360 时预算不足。
|
||||
|
||||
5
|
||||
00:00:23,400 --> 00:00:29,000
|
||||
Inspect the actual document in Marqdo View.
|
||||
查看 Marqdo 真实 View 页面。
|
||||
|
||||
6
|
||||
00:00:29,000 --> 00:00:32,000
|
||||
github.com/cflmy/marqdo
|
||||
开源 · Marqdo 2.7.1
|
||||
|
After Width: | Height: | Size: 161 KiB |
|
After Width: | Height: | Size: 139 KiB |
@@ -0,0 +1,42 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1340" height="720" viewBox="0 0 1340 720" role="img" aria-label="Animated illustration of a procurement skill being called, including a budget denial">
|
||||
<defs><linearGradient id="night" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0b1324"/><stop offset="1" stop-color="#1a2335"/></linearGradient></defs>
|
||||
<rect x="0" y="0" width="1340" height="720" rx="0" fill="url(#night)" stroke="none"/>
|
||||
<text x="46" y="52" fill="#f6d39c" font-size="30" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">Marqdo</text>
|
||||
<text x="207" y="50" fill="#9eacc1" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">/ EXECUTABLE SKILLS</text>
|
||||
<rect x="1137" y="25" width="165" height="38" rx="19" fill="#283348" stroke="#4b5b6b"/>
|
||||
<text x="1154" y="50" fill="#d3d9e4" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">2.7.1 · DEMO</text>
|
||||
<text x="46" y="109" fill="#f6f5ee" font-size="37" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">Your SKILL is now a TOOL.</text>
|
||||
<text x="47" y="141" fill="#a8b6c7" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">A human-readable document → callable business logic → structured results</text>
|
||||
<rect x="43" y="168" width="608" height="493" rx="18" fill="#182235" stroke="#38485c"/>
|
||||
<rect x="677" y="168" width="620" height="493" rx="18" fill="#111a2b" stroke="#38485c"/>
|
||||
<rect x="43" y="168" width="608" height="57" rx="18" fill="#263349" stroke="none"/>
|
||||
<rect x="677" y="168" width="620" height="57" rx="18" fill="#263349" stroke="none"/>
|
||||
<text x="65" y="204" fill="#f5dba9" font-size="20" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">index.mq.md</text>
|
||||
<text x="707" y="204" fill="#e5eaf4" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">$ marqdo call ... 向采购商发工单</text>
|
||||
<text x="66" y="266" fill="#faf7f1" font-size="27" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">## 向采购商发工单</text>
|
||||
<text x="66" y="307" fill="#a2b2ca" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">Read the rules. Call the function.</text>
|
||||
<rect x="65" y="328" width="564" height="166" rx="9" fill="#101a2a" stroke="none"/>
|
||||
<text x="86" y="365" fill="#abd6fa" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">报价 = 查询采购商价格(...)</text>
|
||||
<text x="86" y="407" fill="#abd6fa" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">预算 = 查询余额(已花费=...)</text>
|
||||
<text x="86" y="453" fill="#e9ba84" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">1. 剩余额度 < 本单金额 → 拒绝</text>
|
||||
<text x="65" y="552" fill="#d4e0ee" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">One file: prose + contracts + tables</text>
|
||||
<text x="65" y="588" fill="#d4e0ee" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">+ executable functions + result records</text>
|
||||
<text x="706" y="272" fill="#d7deef" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">SUP_JN 数量=8 单价=36</text>
|
||||
<text x="706" y="311" fill="#98aec9" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">最高预算 = ¥600</text>
|
||||
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.04;0.09;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="345" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="374" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">01 SUPPLIER</text><text x="920" y="374" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">SUP_JN · active</text></g>
|
||||
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.19;0.24;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="399" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="428" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">02 QUOTE</text><text x="920" y="428" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">8 × ¥36 = ¥288</text></g>
|
||||
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.35;0.39999999999999997;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="453" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="482" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">03 BALANCE</text><text x="920" y="482" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">¥600 - already spent</text></g>
|
||||
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.53;0.5800000000000001;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="507" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="536" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">04 DECISION</text><text x="920" y="536" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">check requested amount</text></g>
|
||||
<g opacity="0"><animate attributeName="opacity" values="0;0;1;1;0" keyTimes="0;0.62;0.66;0.85;1" dur="13s" repeatCount="indefinite"/>
|
||||
<rect x="704" y="572" width="565" height="68" rx="10" fill="#193a34" stroke="#478a71"/>
|
||||
<text x="718" y="600" fill="#b5ebcb" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">✓ 已花费=120 ¥480 ≥ ¥288</text>
|
||||
<text x="718" y="625" fill="#d9f7e8" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ok: true · 本地模拟,未发送</text>
|
||||
</g>
|
||||
<g opacity="0"><animate attributeName="opacity" values="0;0;0;1;1;0" keyTimes="0;0.78;0.84;0.88;0.95;1" dur="13s" repeatCount="indefinite"/>
|
||||
<rect x="704" y="572" width="565" height="68" rx="10" fill="#42252d" stroke="#a45a67"/>
|
||||
<text x="718" y="600" fill="#f8b1bc" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">✕ 已花费=360 ¥240 < ¥288</text>
|
||||
<text x="718" y="625" fill="#fde7ea" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ok: false · 预算不足,拒绝工单</text>
|
||||
</g>
|
||||
<path d="M 652 430 C 665 429 674 429 688 430" fill="none" stroke="#f0c58c" stroke-width="3"/><circle cx="665" cy="429" r="4" fill="#f0c58c"><animate attributeName="cx" values="656;681;656" dur="2.5s" repeatCount="indefinite"/></circle>
|
||||
<text x="44" y="698" fill="#7e90a7" font-size="14" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ILLUSTRATED EXPECTED FLOW · NOT A TERMINAL CAPTURE · NO REAL PURCHASE</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 7.4 KiB |
@@ -0,0 +1,35 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1340" height="740" viewBox="0 0 1340 740" role="img" aria-label="View-inspired editorial concept for the procurement function, not a real screenshot">
|
||||
<rect x="0" y="0" width="1340" height="740" rx="0" fill="#f8f6f0" stroke="none"/>
|
||||
<rect x="0" y="0" width="1340" height="68" rx="0" fill="#f2ede4" stroke="none"/>
|
||||
<text x="69" y="45" fill="#8d7358" font-size="29" font-family="Georgia,serif" font-weight="600">marqdo</text>
|
||||
<text x="577" y="43" fill="#665d53" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">文档 函数 执行 变量</text>
|
||||
<text x="1030" y="44" fill="#998773" font-size="13" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">VIEW CONCEPT / NOT CAPTURE</text>
|
||||
<line x1="325" y1="113" x2="325" y2="688" stroke="#e0d5c7"/><line x1="1032" y1="113" x2="1032" y2="688" stroke="#e0d5c7"/>
|
||||
<text x="374" y="128" fill="#b0895e" font-size="16" font-family="Georgia,'Noto Serif CJK SC',serif" font-weight="400">采购智能体</text>
|
||||
<text x="372" y="196" fill="#39352d" font-size="37" font-family="'Noto Serif CJK SC',Georgia,serif" font-weight="600">向采购商发工单</text>
|
||||
<text x="374" y="238" fill="#5d5851" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">核对准入、价格、交付与预算之后,生成本地模拟工单。</text>
|
||||
<line x1="374" y1="267" x2="993" y2="267" stroke="#b69b78"/>
|
||||
<text x="375" y="309" fill="#514a41" font-size="21" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">参数</text>
|
||||
<text x="375" y="348" fill="#5b5146" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">采购商标识符</text>
|
||||
<text x="625" y="348" fill="#96754f" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">text</text>
|
||||
<text x="811" y="348" fill="#8e8171" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">必填</text>
|
||||
<line x1="374" y1="365" x2="994" y2="365" stroke="#ded6c9"/>
|
||||
<text x="375" y="392" fill="#5b5146" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">数量 / 单价 / 已花费</text>
|
||||
<text x="625" y="392" fill="#96754f" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">number</text>
|
||||
<text x="811" y="392" fill="#8e8171" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">必填</text>
|
||||
<line x1="374" y1="408" x2="994" y2="408" stroke="#ded6c9"/>
|
||||
<text x="374" y="463" fill="#5e584f" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">发单前,必须再次查询并核对本轮的可用余额。</text>
|
||||
<rect x="373" y="483" width="618" height="48" rx="8" fill="#ebe3d5" stroke="none"/>
|
||||
<text x="391" y="513" fill="#805b35" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">预算 = [重新查询预算](查询余额(...))</text>
|
||||
<text x="374" y="565" fill="#7b5b4b" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">1. 剩余额度 < 本单金额</text>
|
||||
<text x="374" y="612" fill="#a06b5f" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400"> 返回 [预算不足,拒绝模拟工单](...)</text>
|
||||
<text x="375" y="682" fill="#8c8276" font-size="16" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">仅在全部检查通过时产生“本地模拟、未发送”的结果。</text>
|
||||
<path d="M 408 503 C 295 503 278 339 146 339" stroke="#ba9a75" stroke-width="1.7" fill="none"/><circle cx="408" cy="503" r="4.3" fill="#ba9a75"/>
|
||||
<text x="73" y="281" fill="#a78255" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">BUDGET CHECK</text>
|
||||
<text x="73" y="315" fill="#756350" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">已花费 ¥360</text>
|
||||
<text x="73" y="343" fill="#756350" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">剩余额度 ¥240</text>
|
||||
<path d="M 823 602 C 1010 586 1026 396 1122 396" stroke="#b7837e" stroke-width="1.7" fill="none"/><circle cx="823" cy="602" r="4.3" fill="#b7837e"/>
|
||||
<text x="1080" y="319" fill="#a67871" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">REJECTION</text>
|
||||
<text x="1080" y="354" fill="#945e55" font-size="22" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">¥240 < ¥288</text>
|
||||
<text x="1080" y="393" fill="#945e55" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">拒绝工单</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 4.9 KiB |
|
After Width: | Height: | Size: 204 KiB |
|
After Width: | Height: | Size: 1.9 MiB |
|
After Width: | Height: | Size: 523 KiB |
@@ -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.8.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
@@ -12,4 +12,4 @@ crate-type = ["cdylib", "rlib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
|
||||
serde_json = "1"
|
||||
serde_json = "1"
|
||||
@@ -11,7 +11,7 @@ Raw `cdylib` exports — no `wasm-bindgen` CLI required.
|
||||
|
||||
```bash
|
||||
# from repo root (C5 size profile)
|
||||
marqdo wasm build -o examples/browser-hello
|
||||
marqdo call skills/marqdo-dev/index.mq.md build_browser --effects plugin,process.exec,fs.write --fs-root . --json
|
||||
# or:
|
||||
cargo build -p marqdo-wasm --target wasm32-unknown-unknown --profile release-wasm
|
||||
```
|
||||
@@ -19,3 +19,5 @@ cargo build -p marqdo-wasm --target wasm32-unknown-unknown --profile release-was
|
||||
Prints size in KiB; runs `wasm-opt -Oz` when Binaryen is on `PATH`.
|
||||
|
||||
See [doc/design/browser-marqdo-wasm.md](../../doc/design/browser-marqdo-wasm.md).
|
||||
|
||||
Use the maintained [browser-app](../../examples/browser-app/index.mq.md) for a runnable native Document and browser program. The ABI counter fixture lives in tests/wasm/counter.mq.md, with no independent HTML demo host. The former browser-hello and browser-media directories were retired in 2.7.0; their host capabilities remain documented in lib/browser.mq.md.
|
||||
@@ -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)]
|
||||
|
||||
@@ -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.
|
||||
@@ -0,0 +1,301 @@
|
||||
marqdo (2.8.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Release 2.8.0; see the reviewed upstream CHANGELOG.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Wed, 18 Nov 2026 10:24:08 +0800
|
||||
|
||||
marqdo (2.7.1-1ppa2) noble; urgency=medium
|
||||
|
||||
* Release 2.7.1; see the reviewed upstream CHANGELOG.
|
||||
* Stop reapplying the engineering compatibility fix already in upstream.
|
||||
* Include cached orig bytes until publication is confirmed by Launchpad.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Wed, 11 Nov 2026 00:03:29 +0800
|
||||
|
||||
marqdo (2.7.0-1ppa2) noble; urgency=medium
|
||||
|
||||
* Repair engineering plugin compatibility for this 2.7.0 release.
|
||||
* Keep the accepted upstream orig archive; carry the fix as a quilt patch.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Tue, 10 Nov 2026 17:53:03 +0800
|
||||
|
||||
marqdo (2.7.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Release 2.7.0; see the reviewed upstream CHANGELOG.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Tue, 10 Nov 2026 16:40:29 +0800
|
||||
|
||||
marqdo (2.6.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Executable standard/extension handbooks and practical file/data/task tools.
|
||||
* Readable View action notes, knowledge contracts and offline reader support.
|
||||
* Preserve effect, platform and source compatibility boundaries.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sun, 08 Nov 2026 23:01:35 +0800
|
||||
|
||||
marqdo (2.5.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.5.1: exact source anchors, flowing annotation curves,
|
||||
staggered margin notes, connector avoidance and a labeled toolbar.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 13:05:55 +0800
|
||||
|
||||
marqdo (2.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.5.0: redesigned document reader, margin execution annotations,
|
||||
offline math/assets, navigation/search, and consistent live result refresh.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 10:00:00 +0800
|
||||
|
||||
marqdo (2.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.4.0: oracle journal as language values (foreign.oracle_journal /
|
||||
replay_check), bytecode/frontend hardening, MSRV 1.81 OnceLock wait fix.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Fri, 06 Nov 2026 15:15:00 +0800
|
||||
|
||||
marqdo (2.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.3.0: Strong foreign session — opaque Handle, affine close,
|
||||
replay_check vs oracle journal, table arity refuse, Omega V_safe gate.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 01 Nov 2026 14:45:00 +0800
|
||||
|
||||
marqdo (2.2.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.2: V_safe JSON integer contract on foreign/json bridge —
|
||||
refuse integers outside +/- (2^53-1); wide ints via decimal string.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Sat, 01 Nov 2026 09:45:00 +0800
|
||||
|
||||
marqdo (2.2.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.1: fix view/static-export outline rail under document
|
||||
(occlusion doc-block close + panel container query layout).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 11:45:00 +0800
|
||||
|
||||
marqdo (2.2.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.0: marqdo call runs one named function in any .mq.md.
|
||||
The same file stays the document, the knowledge and the program.
|
||||
Tree and bytecode both execute that function. External calls stay
|
||||
pure: write, process, network and plugin stay off by default.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 09:20:00 +0800
|
||||
|
||||
marqdo (2.1.5-1ppa2) noble; urgency=medium
|
||||
|
||||
* Rebuild 2.1.5 against Launchpad (previous 1ppa1 failed with no build log).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 09:35:49 +0000
|
||||
|
||||
marqdo (2.1.5-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.5: agent reliability workbench — ResourceView / ToolSpec /
|
||||
CheckpointV2 / EffectLedger; EKC ir.json warm-load; web short/read lanes.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 07:39:08 +0000
|
||||
|
||||
marqdo (2.1.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.4: default isolated HTTP execute (ADR 0009) — Supervisor
|
||||
worker pool for execute/sse-live/stream, /_runtime/* control plane,
|
||||
MR-01 dual 60s SSE gold sample, runtime.isolated_execution=1.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 26 Oct 2026 10:00:00 +0000
|
||||
|
||||
marqdo (2.1.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.3: workbench M00–M06 runtime contracts (ModelSelection,
|
||||
RunContext, DocumentView, usage null≠0, LLM selection/cancel,
|
||||
agent.step selection e2e, view document CLI, live smoke).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 25 Oct 2026 15:20:00 +0000
|
||||
|
||||
marqdo (2.1.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.2: executable-knowledge F0–F3 + View V0–V3 release bar
|
||||
(evidence/closure, verify gates, bind/reuse_execute, document.extract,
|
||||
KnowledgePresentation, SSE page_token, upload max_bytes).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sat, 24 Oct 2026 14:50:00 +0000
|
||||
|
||||
marqdo (2.1.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.1: executable-knowledge spine (BoundCall, NarrativeRef,
|
||||
sources/applicability, generation CURRENT + closure digests).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 15:40:00 +0000
|
||||
|
||||
marqdo (2.1.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.0: file-scoped Occlusion is the default syntax; migrated
|
||||
standard/extension libraries and executable-knowledge projections.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 12:00:00 +0000
|
||||
|
||||
marqdo (2.0.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
|
||||
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
|
||||
@@ -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.
|
||||
@@ -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".
|
||||
@@ -0,0 +1,18 @@
|
||||
Description: Use stable Option map_or in the engineering release boundary
|
||||
Author: Marqdo Maintainers <cflmy@users.noreply.github.com>
|
||||
Forwarded: not-needed
|
||||
Last-Update: 2026-11-10
|
||||
|
||||
diff --git a/plugins/engineering/src/lib.rs b/plugins/engineering/src/lib.rs
|
||||
index 6891f01..f0c5ffc 100644
|
||||
--- a/plugins/engineering/src/lib.rs
|
||||
+++ b/plugins/engineering/src/lib.rs
|
||||
@@ -283,7 +283,7 @@ fn r2_settings(root:&Path)->Result<BTreeMap<String,String>,String> {
|
||||
}
|
||||
}
|
||||
for k in ["R2_ENDPOINT","R2_BUCKET","R2_ACCESS_KEY_ID","R2_SECRET_ACCESS_KEY"] {
|
||||
- if settings.get(k).is_none_or(String::is_empty) {return Err(format!("missing {k}; configure ~/.marqdo/r2.env"));}
|
||||
+ if settings.get(k).map_or(true, String::is_empty) {return Err(format!("missing {k}; configure ~/.marqdo/r2.env"));}
|
||||
}
|
||||
Ok(settings)
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
# engineering-stable-option.patch
|
||||
# The fix is already in upstream 2.7.1.
|
||||
@@ -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
|
||||
@@ -0,0 +1 @@
|
||||
3.0 (quilt)
|
||||
@@ -0,0 +1,2 @@
|
||||
# Ignore temporary files while editing patches
|
||||
extend-diff-ignore = "^vendor/"
|
||||
@@ -13,15 +13,38 @@
|
||||
|
||||
## 当前文档
|
||||
|
||||
> **可执行知识下一阶段的阅读顺序**:[原始意图 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 语法宪法** |
|
||||
| [design/prove-cli.md](design/prove-cli.md) | **Proposed:`marqdo prove` 设计**;SKILL 控制平面 → Lean 4、函数级定理表与语言习惯审查、离线判定片段、`proved`/`checked` 诚实性契约、无公理 TCB |
|
||||
| [roadmap/prove.md](roadmap/prove.md) | **Proposed:`marqdo prove` 实施路线**;P0–P3 周计划、8 类测试矩阵(单调性/一致性/不执行/子集/定理表/CLI/缓存/编码)、CI 与验收证据 |
|
||||
| [adr/0010-skill-proof-boundary.md](adr/0010-skill-proof-boundary.md) | **ADR 0010**:定理表作为契约表第四角色、可证子集封闭、Lean 为唯一 `proved` 来源、顾问式不强制 |
|
||||
| [roadmap/agent-reliability-crossrepo-2026-10-27.md](roadmap/agent-reliability-crossrepo-2026-10-27.md) | **Proposed:跨仓 Agent 可靠性开发计划**;M-A0–M-A6 ∥ Q-A0–Q-A7 排期、依赖图、F01–F20 映射、MA-T*/QA-* 验收与第一刀切片;协议真源仍见下方设计文档 |
|
||||
| [design/agent-reliability-tools-resources-2026-10-27.md](design/agent-reliability-tools-resources-2026-10-27.md) | **Proposed:智能体能力补足**;基于 `16f26d7`,增量设计错误恢复、检查点/效应账本、结构化工具、输出通道、上下文与只读资源视图;含跨仓边界、阶段计划和故障验收 |
|
||||
| [research/agent-capabilities-2026-10-27.md](research/agent-capabilities-2026-10-27.md) | **官方能力调研与源码复核**;OpenAI/Claude/Gemini/LangGraph/Deep Agents/MCP,求道当前问题 F01–F20;区分现有能力、设计推导与待实测项 |
|
||||
| [design/isolated-web-runtime-development-2026-10-26.md](design/isolated-web-runtime-development-2026-10-26.md) | **隔离执行与响应式 Web 运行时**:进程池、控制/读取分离、取消、事件恢复、发布一致性;实现见 `src/runtime/` |
|
||||
| [adr/0009-isolated-web-runtime.md](adr/0009-isolated-web-runtime.md) | **ADR 0009**:隔离 Web 运行时决策;金样例通过后替代 ADR 0008 的并行性结论 |
|
||||
| [跨库缺陷复核(2026-10-26)](../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) | **最新源码与测试证据**:实际 HTTP 路由、知识发布/阅读断点、旧缺陷处置及 1000 单元编译性能失败;需同级 qdagent checkout |
|
||||
| [design/qdagent-workbench-runtime-and-view-2026-10-25.md](design/qdagent-workbench-runtime-and-view-2026-10-25.md) | **qdagent 知识工作台框架支持**:M00–M05 合同落地中(`src/workbench/`、MLSP `capabilities` / `view.document` / `view.reference_resolve`、`tests/workbench_contracts.rs`);完整 verified 以切片验收证据为准 |
|
||||
| [design/view-knowledge-reading-experience-2026-10-24.md](design/view-knowledge-reading-experience-2026-10-24.md) | **View 知识阅读体验重设计(建议)**:正文优先、结构导航、就地知识说明、来源与运行状态、响应式线框、实现契约与验收;含当前呈现和 no-exec 反例 |
|
||||
| [design/view-readable-actions.md](design/view-readable-actions.md) | **View 阅读优化实现**:动作留在正文、实际逻辑引到侧注、空逻辑明确标识;语法阅读指南、输入输出与依据卡片、单文件依赖分析及浏览器验收 |
|
||||
| [roadmap/qdagent-knowledge-support-gaps-2026-10-24.md](roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) | **求道知识沉淀与文档编译支撑缺口**:2.1.1 源码复核、来源/依赖失效反例、验证与 Agent 协议、语法提示词、导入底座及跨库分工 |
|
||||
| [design/document-native-development-guide.md](design/document-native-development-guide.md) | **下一阶段开发指导**:语法审查裁决、正文→命名→复用工作流、AI 上下文与局部编辑、渐进严格、作者成本及 S0–S6 验收 |
|
||||
| [design/core-surface.md](design/core-surface.md) | **核心构造清单**:v2.1 默认链接/循环说明与构造守卫;不是全部实现状态清单 |
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **历史 v0.2 映射**:不再代表现行默认链接语义 |
|
||||
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 设计背景**:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断;链接语义以 v2.1 规范和测试为准 |
|
||||
| [adr/0005-prose-unified-markup.md](adr/0005-prose-unified-markup.md) | **Proposed:采纳 mapping v0.3** |
|
||||
| [roadmap/markup-v0.3.md](roadmap/markup-v0.3.md) | **Markup v0.3 实现路线(M0–M5)** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
| [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 +52,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 +114,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,79 @@
|
||||
# ADR 0010: SKILL 证明边界:定理表、可证子集与顾问式判定
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Accepted(决策已定)**;实现未开始,路线见 [roadmap/prove.md](../roadmap/prove.md) |
|
||||
| 日期 | 2026-11-13 |
|
||||
| 设计 | [design/prove-cli.md](../design/prove-cli.md) |
|
||||
| 相关 | [core-surface.md](../design/core-surface.md)(不新增标记)· [layers.md](../design/layers.md)(Language 层扩表角色)· [contract.rs](../../src/contract.rs)(既有契约表提取)· [replay-policy](../../verification/replay-policy/README.md)(Lean 伴随判定先例) |
|
||||
|
||||
## 背景
|
||||
|
||||
Agent 改写 SKILL 后,人需要逐行确认"分支是否绕开审核、失败是否被吞掉"。这类**控制平面**性质适合形式化:编排是带条件的有限 DAG,没有死循环、没有指针。同时,把整个 Marqdo 当通用语言编译到 Lean 会立刻撞上字符串/JSON/浮点/IO 的语义鸿沟,收益被稀释。
|
||||
|
||||
项目已有一条 Lean 纪律:`verification/replay-policy` 用 Lean 做唯一判定,Rust 不保留第二份实现,缺伴随进程时失败关闭。本 ADR 决定把同样的纪律用于 SKILL 编排,但**降级为顾问式**:证明用于减少审核量,不作为发布门禁。
|
||||
|
||||
## 决策
|
||||
|
||||
1. **定理是契约表的第四种角色**,不是新标记。
|
||||
函数体首条可执行语句之前可放一张「定理表」(`定理 | 结论 | 前提 | 策略`),与 `参数`/`返回`/`字段` 表同槽位;解析期提取进 `Function.claims`,从 body 移除,不参与运行。核心标记计数不变,`CORE_CONSTRUCTS` 不增行;`layers.md` 的 Language 清单补记该角色。
|
||||
|
||||
2. **可证子集显式封闭**:无 `while`、无递归、无动态派发(插件、变量函数名、`code` 值调用)。越界函数被跳过(`rejected`),不降级成不透明块。外部操作是 `Env := Op → Val` 参数,不是公理;后置条件只能来自 `假设` 表并成为定理前提。
|
||||
|
||||
3. **Lean 是唯一能产生 `proved` 的判定器**。离线判定只到 `checked`,且被限制在一个极小的片段(路径枚举、轨迹、字面结果、命题组合、单变量区间),凡是离线判定为真的定理都必须同时生成 Lean 脚本。运行期若 Lean 可用则复核;离线 `checked` 而 Lean 未关闭视为内部错误(`proof.divergence`),以 Lean 为准并退出非零。
|
||||
|
||||
4. **顾问式,不强制**。默认退出码只对"作者写下的定理未被关闭"(`unproved`)与工具错误非零;缺工具链、`rejected`、`unverified` 默认 0。需要严格覆盖的调用方显式传 `--require-lean`。规范与技能手册**推荐**在发布 SKILL 前运行,但不设为门禁。
|
||||
|
||||
5. **`prove` 不执行被证程序**。只读源码、写缓存与 `--emit` 目录;这一点由测试夹具(带 `fs.write` 的函数)守住。
|
||||
|
||||
## 备选与取舍
|
||||
|
||||
| 备选 | 否决理由 |
|
||||
|---|---|
|
||||
| frontmatter `proof:` 块 | 丢函数作用域与行级锚点;多函数文件无法分派;诊断指不回具体行 |
|
||||
| `# 证明` 标题 | `#` 是对象、`##` 是函数;新增"标题=命题"破坏"标题即可调用单元"的既有习惯,还会进命名空间 |
|
||||
| ` ```proof ` 围栏 | 代码围栏必须跟在空赋值后,为写定理先造死变量,比表更别扭;且会被当作可执行值 |
|
||||
| 普通注释承载定理 | 注释不参与语义,无法可靠区分说明与定理,拿不到行锚点 |
|
||||
| 旁挂 `.proof.md` | 把真理拆成两份,违背"文档与代码同一份"的项目前提 |
|
||||
| 细化类型(refinement types) | 语义增量过大,且与既有契约表形成两份作者真相 |
|
||||
| 强制门禁(proved 才能发布) | 与"降低审核难度"的目标冲突;无 Lean 的团队会绕过工具 |
|
||||
|
||||
## 后果
|
||||
|
||||
**正面**
|
||||
|
||||
- 作者在一个地方写清"这条编排保证什么",机器可判定、行号可定位;
|
||||
- 定理表与契约表同一提取路径,`check` / `view` / `catalog` 可逐步接入,不产生第二套声明;
|
||||
- 外部依赖以假设形式显式化,证书是本项目一贯的"可复核证据";
|
||||
- 不新增核心标记,守卫测试与文档计数不膨胀。
|
||||
|
||||
**负面 / 代价**
|
||||
|
||||
- 新增一个语言层语义角色与一个 CLI 命令,需要 ADR + 测试 + 文档(本 ADR 即准入材料);
|
||||
- 离线判定器是新代码,必须长期用 Lean 语料护栏,防止"过度自信";
|
||||
- 作者可能误以为定理会在运行时生效——需要文档、`view` 与 `check` 三处反复澄清;
|
||||
- `proved` 容易被读成"整份 SKILL 安全"——README 必须写死"只对陈述负责"。
|
||||
|
||||
## 语义增量清单
|
||||
|
||||
| 新增 | 是否进运行时 | 说明 |
|
||||
|---|---|---|
|
||||
| `Function.claims` | 否 | 与 `Function.contract` 同类的声明元数据 |
|
||||
| `结果` / `轨迹` 与 `包含` / `长度` / `下标` | 否 | 仅定理作用域;与普通表达式作用域隔离 |
|
||||
| `check --proof` | 否 | 静态校验,默认关 |
|
||||
|
||||
不新增:求值规则、作用域规则、调用约定、核心标记、类型系统扩展。同名遮蔽(参数或局部变量叫 `结果`/`轨迹`)一律报 `proof.name_shadow`,不做隐式优先。
|
||||
|
||||
## 验收(摘要)
|
||||
|
||||
- 核心表面:`cargo test --test core_surface` 不变红;`CORE_CONSTRUCTS` 计数不变。
|
||||
- 单调性:语料中每条离线 `checked` 的定理,Lean 均 `proved`;分歧为 0。
|
||||
- 不执行:带 `fs.write` 的夹具在 `prove` 后无副作用。
|
||||
- 确定性:同输入两次 `emit` 字节一致。
|
||||
- 诚实性:文本、JSON、证书三处对 `checked`/`proved` 的措辞一致。
|
||||
|
||||
## 未决(不阻塞实现)
|
||||
|
||||
- `假设` 表是否需要扩展列(`来源`、`责任方`)。
|
||||
- `--all` 的聚合粒度(按文件/按函数)。
|
||||
- 证书是否需要签名,以及签名由谁持有。
|
||||
@@ -0,0 +1,348 @@
|
||||
# Marqdo 智能体能力补足:恢复、工具、上下文与资源视图
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed**;本次交付设计,不代表以下新接口已实现 |
|
||||
| 日期 / 基线 | 2026-10-27(Asia/Shanghai);Marqdo `16f26d7` / 2.1.4;qdagent `68b757e` |
|
||||
| 调研与现状 | [官方资料与源码证据 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品配套 | [qdagent 智能体能力与预览设计](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 继承 | [ext/agent](ext-agent.md)、[隔离 Web 运行时](isolated-web-runtime-development-2026-10-26.md)、[工作台合同](qdagent-workbench-runtime-and-view-2026-10-25.md) |
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;让工具可发现、可验证、可审计;让结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位,不把框架改成第二套产品聊天服务。
|
||||
|
||||
现有 `src/runtime/` 已实现隔离进程、任务/事件与控制通道,本设计在其上补 Agent 步骤语义。现有 `ext/ai/agent.mq.md` 已有 step/plan/run、CALL/READ、观察压缩,继续扩展。框架不持有求道“笔记”业务表、中文按钮、默认回答字数或具体供应商账户。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | 错误分类、预算、检查点、工具效应、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | 结果分通道、输出预算、角色消息、finish reason | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD 行为 |
|
||||
| 资源 | ResourceRef、只读内容/派生预览、定位、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览组件和布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
APP[qdagent 产品策略与授权] --> RUN[ext/ai/agent step / plan / run]
|
||||
RUN --> CTX[ContextPack 与预算]
|
||||
RUN --> LLM[LLM Adapter]
|
||||
RUN --> DISPATCH[Tool Dispatcher]
|
||||
DISPATCH --> LOCAL[受控 Marqdo 函数]
|
||||
DISPATCH --> MCP[MCP Client]
|
||||
DISPATCH --> RES[资源读取 / 转换]
|
||||
RUN --> REC[Checkpoint / Effect Ledger]
|
||||
REC --> RT[既有 runtime task store / event log]
|
||||
RUN --> OUTPUT[answer / artifact / progress / diagnostic]
|
||||
RES --> VIEW[DocumentView / ResourceView]
|
||||
OUTPUT --> APP
|
||||
VIEW --> APP
|
||||
```
|
||||
|
||||
## 2. 现状与增量
|
||||
|
||||
| 已有能力 | 本轮不能误判为缺失 | 要补的具体语义 |
|
||||
|---|---|---|
|
||||
| runtime.task_control_v2/event_replay/read_lane | 不再新建一套队列与 SSE 框架 | Agent 步骤恢复与传输重放的边界 |
|
||||
| resume_save/load | 不再新建平行 checkpoint 命名空间 | 原子提交、版本摘要、作用域、效应关联 |
|
||||
| CALL、ARGS、READ、plan patch | 不废弃文档式编排 | 类型化 schema、校验错误、有限修复、稳定 call_id |
|
||||
| MCP stdio client | 不从零重写连接器 | timeout/cancel、resource、远程 transport 的能力探测 |
|
||||
| DocumentViewV1 / Locator | 不另写 `.mq.md` 解析器 | 普通资源类型、明确 renderer、历史与相对资源处理 |
|
||||
| LLM messages/usage | 不把 provider 行为交给产品猜测 | 输出预算、原生工具适配探测、角色边界与分通道 |
|
||||
|
||||
新模块路径及协议名以下均是**建议落点**。首批开发先固化 schema 与 fixture,再开放 feature bit;不得只更新 capabilities 把未实现能力标真。
|
||||
|
||||
## 3. 错误和恢复合同
|
||||
|
||||
### 3.1 ErrorV1
|
||||
|
||||
现有字符串错误保留兼容适配,新工具与 Agent 结果返回:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentErrorV1",
|
||||
"code": "tool.timeout",
|
||||
"category": "transient",
|
||||
"stage": "tool",
|
||||
"message": "读取资源超时",
|
||||
"retryable": true,
|
||||
"retry_after_ms": 1200,
|
||||
"effect_state": "none",
|
||||
"recovery_action": "retry_step",
|
||||
"call_id": "call_01",
|
||||
"details_ref": "resource:diagnostic_01"
|
||||
}
|
||||
```
|
||||
|
||||
`retryable` 仅是候选信息,最终动作由可信策略结合效应、截止时间、预算、取消状态决定。远端工具声称 readOnly/idempotent 不构成授权依据。凭证和原始堆栈不进入公开 message。
|
||||
|
||||
| 错误类别 / 例子 | 框架动作 | 不允许的动作 |
|
||||
|---|---|---|
|
||||
| transient:429、部分 5xx、连接失败 | 只在安全步骤重试,遵守 Retry-After | 无限重试、复用同一流片段直接追加 |
|
||||
| invalid_arguments:schema 不匹配 | 把字段级错误作为 observation,最多 1 次参数修复 | 启动工具后才校验;静默丢弃字段 |
|
||||
| validation_failed:编译/文档校验 | 保留候选与诊断,局部修复后重新验证 | 将未验证草稿标为成功 |
|
||||
| context_overflow | 压缩可重建上下文,保留任务/限制/未决效应 | 丢失最新用户指令、授权或版本 |
|
||||
| auth / forbidden | 直接 needs_input/blocked,交应用处理 | 换身份、扩大范围或匿名绕过 |
|
||||
| conflict / stale_revision | 重新读取版本并重新规划 | 覆盖用户修改、对写操作盲重试 |
|
||||
| capability_unavailable | 返回可行替代操作清单 | 假称已搜索、已渲染或已执行 |
|
||||
| policy_denied | 显式拒绝该动作 | 把限制当工具错误让模型规避 |
|
||||
| budget_exhausted | 保存状态与已完成结果,返回 partial | 自动增预算或伪造 completed |
|
||||
| unknown_effect / worker_crash | 对账、查询外部状态,不能判断则 needs_reconciliation | 重跑整个工作簿 |
|
||||
| cancelled | 停止新调用、保留可读产物、传播取消 | 在后台悄悄修复或恢复 |
|
||||
|
||||
初始建议:传输最多 2 次重试(总 3 次尝试),指数退避基准 0.5/1 秒并加 jitter;有 Retry-After 时使用服务端建议并受总 deadline 限制。参数修复最多 1 次,内容修复最多 2 次。预算由应用传入,框架只提供默认上限与执行机制。所有重试、修复和摘要模型调用计入同一成本账本。
|
||||
|
||||
错误指纹 `hash(tool_id, normalized_arguments, error_code, relevant_revision)` 连续出现 2 次且没有新证据时中止该策略,允许一次有依据的替代路径;不能通过改写错误文本绕过循环检测。
|
||||
|
||||
### 3.2 四类“恢复”必须分开
|
||||
|
||||
1. **续订事件**:客户端从 cursor 重放和订阅同一个 task,不发起新推理。
|
||||
2. **重试步骤**:相同逻辑 operation、同幂等键;新 invocation attempt,复用成功的前序结果。
|
||||
3. **恢复工作流**:从兼容 checkpoint 建立新 runtime task / attempt,关联 `resumed_from`,不把旧终态改回 running。
|
||||
4. **重新生成答案**:新的输出版本;已有成功工具结果可复用,用户明确重新执行才重新产生效应。
|
||||
|
||||
当前 TaskState 把 interrupted/needs_reconciliation 视为终态,沿用此约定。新增 `AgentRun` 逻辑关联只管理目标和 attempt 链;调度权仍在原 runtime。恢复请求带 `expected_revision`、checkpoint digest 与幂等键,相同请求返回同一新 attempt,冲突返回 409 对应的框架错误。
|
||||
|
||||
执行失败不必丢掉有用内容:`outcome.status = succeeded | partial | failed | needs_input | cancelled`,伴随 `answer_ref/artifacts/error/recovery_options`。HTTP 调用成功与 Agent 业务 succeeded 不再混为同一字段。
|
||||
|
||||
## 4. 检查点与工具效应
|
||||
|
||||
### 4.1 CheckpointV2
|
||||
|
||||
在 `plugins/agent/src/resume.rs` 扩展已有实现,统一根目录由宿主提供,客户端不能传任意绝对路径。保留 legacy load,但旧 checkpoint 无效应信息时默认 `manual_review`,不能自动重做写操作。
|
||||
|
||||
| 字段组 | 内容 |
|
||||
|---|---|
|
||||
| 身份 | schema、checkpoint_id、logical_run_id、task_id、attempt_id、step_id、parent_checkpoint_id |
|
||||
| 作用域 | principal_ref、workspace_id、session_id、授权 scope digest |
|
||||
| 输入 | task revision、workbook revision/hash、输入资源 revisions、knowledge generation |
|
||||
| 运行配置 | ModelSnapshot public ref、tool registry digest、policy revision、runtime compatibility |
|
||||
| 进度 | completed_steps、pending_operation、observation refs、context summary ref |
|
||||
| 约束 | 剩余 token/tool/time/cost 预算、deadline、cancel epoch |
|
||||
| 一致性 | effect ledger watermark、event seq、manifest digest、committed_at |
|
||||
|
||||
写入协议:写唯一临时文件→flush/fsync→原子 rename→提交 checkpoint 指针;持久化配置下目录 fsync 按平台支持实现。所有引用 blob 在指针提交前落盘。损坏记录报 `checkpoint.corrupt` 并尝试上一个完整版本,不能读取半个 JSON 当无历史。
|
||||
|
||||
恢复前校验身份/授权、源版本、工具 schema 与模型兼容性。权限撤销立即生效;checkpoint 不是永久授权。源文件改变返回 `checkpoint.input_changed`,重新计划受影响步骤,不能偷偷使用最新文件继续旧验证结果。
|
||||
|
||||
### 4.2 Effect ledger
|
||||
|
||||
```text
|
||||
prepared → started → committed
|
||||
↘ failed_no_effect
|
||||
↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
|
||||
```
|
||||
|
||||
每个 operation 持久记录 `operation_id/idempotency_key/args_digest/resource_scope/expected_revision/effect_class/result_ref`。幂等键作用域是 principal + workspace + logical_run + step + operation,不用随机 attempt ID 替换稳定 operation key。对同 key 不同 payload 拒绝。
|
||||
|
||||
读工具可重试;确定幂等写由服务端去重;可补偿写仅在补偿明确安全时执行;未知写先查询 receipt/版本。对外部系统不能承诺通用 exactly-once。关键 crash 窗口是“远端已成功、本地尚未记账”,必须返回 unknown 并对账。
|
||||
|
||||
本地文件使用 expected revision + staging + atomic replace;变更提交后检查点失败也靠 operation receipt 恢复。`tool.completed` 必须在结果与 receipt 可读取后提交,再对外发事件。事件发送失败不回滚已发生的业务效应。
|
||||
|
||||
不要复制 runtime 事件存储:Agent ledger 与 artifact manifest 是步骤事实,现有 runtime event log 是传输/调度事实;以 ID 关联,采用可重建投影与 outbox。跨 DB/文件不能声称一个事务完成,使用 manifest 提交点和恢复扫描补齐索引。
|
||||
|
||||
## 5. 结构化工具与调度
|
||||
|
||||
### 5.1 ToolSpecV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ToolSpecV1",
|
||||
"id": "workspace.read",
|
||||
"version": "1",
|
||||
"description": "读取授权资源的指定行范围",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"resource_id": {"type": "string"},
|
||||
"revision": {"type": "string"},
|
||||
"start_line": {"type": "integer", "minimum": 1},
|
||||
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
|
||||
},
|
||||
"required": ["resource_id"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"output_schema_ref": "ResourceReadV1",
|
||||
"effect": "read",
|
||||
"scopes": ["workspace:read"],
|
||||
"timeout_ms": 10000,
|
||||
"max_result_bytes": 65536,
|
||||
"idempotency": "safe",
|
||||
"concurrency_group": "resource-read",
|
||||
"availability": "ready"
|
||||
}
|
||||
```
|
||||
|
||||
定义由宿主/可信模块注册;用户认证、scope 与资源根由宿主注入,不接受模型提供 principal 或任意 root。`read`、`write`、`execute`、`external_write` 是策略分类,不是靠工具命名推断。
|
||||
|
||||
ToolCallV1:`call_id/tool_id/tool_version/arguments/operation_id/parent_span_id`。ToolResultV1:`ok/status/summary/structured_content/resources/citations/error/usage/truncated/next_cursor/effect_receipt_ref`。超限结果先写 artifact,再返回摘要和范围读取句柄;不把几十 MB 文本送进 prompt。
|
||||
|
||||
### 5.2 一条执行通道
|
||||
|
||||
```text
|
||||
发现 → 加载 schema → schema 校验 → 授权与范围解析 → 预算/取消检查
|
||||
→ 幂等查询 → 执行 → 结果 schema/大小校验 → receipt/结果提交 → 事件 → observation
|
||||
```
|
||||
|
||||
provider 原生 function call 与文档 `CALL:name + ARGS:{...}` 都归一到该通道。保留旧白名单适配,已有 `.mq.md ##` 可根据形参推导初始 schema,再允许显式描述收紧。转换不允许调用未暴露的框架内部函数。禁止对模型参数使用 eval/任意代码反序列化。
|
||||
|
||||
`tools.search` 返回已授权且当前可用的工具摘要;`tools.describe` 按 ID 返回完整 schema。核心 5–8 个工具可常驻,其余按需加载;此数量是产品起始配置,不写死框架。每次真正调用仍重新检查授权;搜索索引可列 unavailable 原因供诊断,但不能让未授权工具名字泄露私有连接信息。
|
||||
|
||||
初始支持 JSON Schema 的明确子集并公开能力;不支持的 schema 拒绝注册,不静默放宽。原生工具能力、并行工具调用、图片输入、结构化输出分别探测;纯文本兼容 provider 继续走 CALL,但并发和可靠性承诺按测试能力开放。
|
||||
|
||||
### 5.3 并发、MCP 与程序化执行
|
||||
|
||||
独立只读调用可并发,默认最多 4 个;修改同一资源的调用串行且用 revision CAS。依赖链、审批与取消检查保持顺序。一个并发调用失败不丢弃其他已成功结果。
|
||||
|
||||
MCP 扩展现有 client:先完善 timeout/cancel、错误映射、工具分页与 schema、resource read/link,再按 capability 增加远程 Streamable HTTP 与连接认证。stdio 不应允许模型选择任意宿主可执行文件。连接元数据归应用,凭证通过 secret handle 注入 worker,工具输出和 trace 不记录密钥。
|
||||
|
||||
工具 annotations 只是提示,可信策略确定真实效应。外部结果全部为数据,不能提升为 standing/system。MCP resource URI 转成宿主授权 ResourceRef,不允许前端直接请求任意 file:// 或内部网地址。
|
||||
|
||||
程序化工具编排和子 Agent 为后续切片:在沙箱中仅暴露注册 dispatcher,逐次执行同样的授权、预算和效应日志;禁止通过一段脚本绕过逐工具控制。子任务继承更小权限和共享总预算,不默认开放写同一资源。
|
||||
|
||||
## 6. 输出通道与上下文
|
||||
|
||||
### 6.1 AgentOutputV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentOutputV1",
|
||||
"status": "succeeded",
|
||||
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
|
||||
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
|
||||
"citations": [],
|
||||
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
|
||||
"finish_reason": "completed",
|
||||
"recovery_options": []
|
||||
}
|
||||
```
|
||||
|
||||
这是结果传输协议,不要求模型每次逐字生成这张 JSON。文档式编排仍可产出 `.mq.md`,框架把稳定产物、摘要与事件归一化。普通文本回答可没有 artifact 和 validation;未运行的内容标 `not_applicable/not_run`,不能填 passed。
|
||||
|
||||
channel 至少区分 `answer/artifact/progress/diagnostic`。只有 answer delta 可追加到聊天正文;工作簿 token 和工具日志进入其他通道。进度是可观察动作摘要,不要求或泄露模型内部思维链。
|
||||
|
||||
应用传 `ResponsePolicy`:detail level、目标长度、最大输出 tokens、是否允许 artifact、用户显式需求。框架负责 budget 和 finish_reason,中文字符数与最终文案由应用决定。达到 token 上限返回 `length_limited` 和完整/不完整标记,不能裁剪 JSON/代码后假装成功。
|
||||
|
||||
优先从已验证产物结构投影摘要。必要时增加一次受预算控制的摘要模型调用;摘要不得新增未经证据支持的结论。修复成功后 accepted candidate、结果正文、artifact revision 与 verification digest 必须全部一致。
|
||||
|
||||
### 6.2 ContextPackV2
|
||||
|
||||
按优先级组装:可信运行规则→最新用户目标/约束→用户选中资源范围→未决操作/成功步骤摘要→检索证据→近期对话→可回读历史。保持角色结构,不把用户/工具文本简单拼进系统指令。
|
||||
|
||||
每个 item 携带 `origin/trust/resource_ref/revision/token_estimate/priority`。预算初值建议保留模型窗口 20% 给输出与协议开销;上下文使用达到可用预算 70% 时触发整理,具体比例配置化。优先剔除可重读的完整工具输出,保留摘要、引用和失败恢复锚点。
|
||||
|
||||
Compaction 必须保留:目标、用户限制、当前计划、已完成步骤、待决写入、授权范围、输入版本、已接受产物与引用、余量。summary 绑定其 source event range 和 digest,不能当成新的已验证知识。工具输入过时须重读,不能依赖压缩摘要执行写入。
|
||||
|
||||
已有 EKC/agent memory 继续提供知识发现和复用。长期用户记忆的创建/修改/删除政策归 qdagent;网页中的指令不能自动变成长期偏好。
|
||||
|
||||
## 7. 统一资源与只读视图
|
||||
|
||||
### 7.1 ResourceRefV1 / ResourceViewV1
|
||||
|
||||
ResourceRef 统一携带 `resource_id/workspace_id/kind/media_type/revision/digest/title/size/origin/locator`;opaque ID 由宿主映射,不将浏览器 path 直接当文件权限。revision 是内容版本,generation 是知识发布代,两者不混用。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ResourceViewV1",
|
||||
"resource": {
|
||||
"resource_id": "res_01", "workspace_id": "ws_01", "kind": "file",
|
||||
"revision": "sha256:example", "media_type": "text/markdown", "title": "设计说明"
|
||||
},
|
||||
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
|
||||
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
|
||||
"outline": [],
|
||||
"locators": [],
|
||||
"completeness": "complete",
|
||||
"no_exec": true,
|
||||
"diagnostics": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
```
|
||||
|
||||
继续把 `.mq.md` 交 `view.document`,ResourceView 只包装/扩展,不能另解释一套 Marqdo 语义。普通 `.md/.txt/代码/JSON/CSV` 走媒体类型处理,避免全仓语义编译。浏览器组件由 qdagent 实现,框架只提供可读内容、受控片段或短期授权 blob 引用。
|
||||
|
||||
`fragment`、`text`、`blob_ref` 是互斥载荷,按严格 format enum 解码。未知格式返回 unsupported,不能用 `format.includes('html')` 猜测 HTML。为空与加载失败必须有独立状态。
|
||||
|
||||
### 7.2 格式矩阵
|
||||
|
||||
| 格式 | 框架提供 | 前端消费 | 未具备能力时 |
|
||||
|---|---|---|---|
|
||||
| `.mq.md` | 静态 DocumentView、outline、节点/引用 | 正文、语义链接、源码切换 | 只读源码 + 明确诊断,不执行 |
|
||||
| Markdown / 笔记正文 | 共享静态 Markdown→受控结构/HTML、相对资源引用 | 标题、列表、表格、代码、链接 | 纯文本 |
|
||||
| 文本/代码 | 分页行片段、编码信息、行定位 | 行号与语法高亮 | 编码提示/下载 |
|
||||
| JSON / CSV | 有界解析、路径/行列定位、分页 | 树/表/源码 | 原始文本,标格式错误 |
|
||||
| 图片 | 授权 blob、尺寸/元信息 | 缩放/旋转/替代文本 | 下载,不暗示已做 OCR |
|
||||
| PDF | blob、页元信息,可选提取插件 | PDF.js 页渲染与定位 | 文件卡;提取不可用不阻止支持的视觉预览 |
|
||||
| DOCX/XLSX/PPTX | 受限转换插件,可选 PDF/HTML 派生物 | 按派生格式预览 | 未安装转换器,保留下载 |
|
||||
| HTML/SVG | 默认源码;允许时经严格清洗或受限派生物 | 隔离预览 | 不以内联可执行页面显示 |
|
||||
| 未知二进制/压缩包 | 元数据 | 下载卡 | 不自动解压/执行 |
|
||||
|
||||
提取、预览、执行各有独立 capability。办公转换、OCR 使用受限 worker,禁宏与网络、限制时间/内存/页数/解压膨胀比;结果绑定原件 digest、转换器版本和参数。首期不承诺保真编辑。
|
||||
|
||||
### 7.3 安全、定位、缓存
|
||||
|
||||
所有读取先校验宿主授予的 workspace/resource scope,canonicalize 并处理 symlink 逃逸;读取句柄与校验对象一致,防路径检查后替换。读取原件的身份权限不可被缓存绕过。
|
||||
|
||||
预览绝不调用 `run/verify` 或有执行副作用的 view 路径;正文中的 Marqdo 调用链接只展示语义与导航,执行需单独工具调用与授权。远程图片、相对链接、资源 URL 经受控解析;下载入口不允许任意内网 fetch。
|
||||
|
||||
HTML 清洗在框架产出侧和浏览器插入侧都有明确边界;用成熟 allowlist 实现而非正则。禁止 script/event handler、危险 URI、任意 style/form/嵌入对象。前端配 CSP;对需要交互的产物另建无权限 sandbox,不复用文档渲染器。
|
||||
|
||||
缓存 key:workspace + resource ID + revision + renderer version + render options + policy version;命中前重新授权。历史 revision 不存在就返回 `version_unavailable`,不能默默展示当前版。locator 支持 node/span/line/page/cell,失效时标 stale 并提供用户主动查看最新版的操作。
|
||||
|
||||
建议首期限制:文本片段 256 KiB、代码单次 500 行、CSV 单次 200 行;更大内容分页,完整文件保留。数值需压测校准,不作为现有系统性能声明。
|
||||
|
||||
## 8. 事件、可观测性与能力协商
|
||||
|
||||
复用 RuntimeEventV2 的 task/run/attempt/seq/event_id。拟增加事件类型:`agent.step.started/completed`、`tool.started/completed/failed`、`recovery.scheduled/exhausted`、`checkpoint.committed`、`artifact.updated`、`answer.delta/committed`、`context.compacted`。现有 `message.delta` 由兼容适配映射 answer channel,不能同时重复消费两套事件。
|
||||
|
||||
终态提交包含 accepted output manifest、last_seq、result digest;断流客户端能通过快照补齐最终答案。stream delta 是预览,最终 committed revision 是权威。统计每次尝试的 usage,摘要和修复调用分别标 purpose;未知计量保持 unknown。
|
||||
|
||||
拟新增 capability:`agent.error_v1`、`agent.checkpoint_v2`、`agent.tool_schema_v1`、`agent.output_channels_v1`、`agent.context_pack_v2`、`resource.view_v1`,以及各 media renderer 的独立版本/可用状态。保持现有 probe,新增字段向后兼容;未知 feature 当不可用。
|
||||
|
||||
trace 记录因果 ID、耗时、错误类别、参数摘要、资源版本和 effect receipt。正文与密钥按配置脱敏,不默认把用户全文件复制进日志。输出中不包含模型私有推理;可审计的是实际动作与结果。
|
||||
|
||||
## 9. 分阶段实现与文件落点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 依赖 / 退出条件 |
|
||||
|---|---|---|---|
|
||||
| M-A0 | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | 上述协议、旧适配、状态映射 | 先冻结跨仓字段,未知字段/版本可降级 |
|
||||
| M-A1 | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、新 recovery/effects 支撑模块 | 分类错误、有界修复、accepted candidate、原子检查点 | M-A0;故障注入不重复写、旧记录不冒险自动恢复 |
|
||||
| M-A2 | `plugins/agent/src/lib.rs`、`mcp_client.rs`、新 tool registry/dispatcher | schema 工具、调用统一、分页与结果资源 | M-A0;未授权调用为 0,失败结果结构正确 |
|
||||
| M-A3 | `src/workbench/document_view.rs`、新 resource_view、媒体适配模块 | ResourceRef/View、普通格式静态阅读、no-exec | M-A0;资源定位与安全语料通过 |
|
||||
| M-A4 | `ext/ai/agent.mq.md`、`plugins/llm/src/lib.rs`、`src/workbench/run_context.rs` | 输出分通道、预算、ContextPackV2 | M-A1/2;原生和纯文本 provider fixture 都可用 |
|
||||
| M-A5 | `src/runtime/` 的既有存储/事件适配、MCP 与转换插件 | 恢复对账、PDF/Office 插件、远程 MCP | M-A1/2/3;持久模式 crash/restart 通过 |
|
||||
| M-A6 | plan/subtask/sandbox 扩展 | 程序化工具、有界委派与可选浏览器 | 后置;须证明任务收益和预算/效应可控 |
|
||||
|
||||
先交 M-A0 与 qdagent P0 的静态阅读/错误结果修复;不要让完整 checkpoint v2 阻塞笔记预览。M-A1 可先上只读重试,写恢复待 ledger 通过再开放。新特性默认关闭直到对应合同实测通过,旧路径继续可读。
|
||||
|
||||
## 10. 验收与评测
|
||||
|
||||
所有目标是 proposed gate,尚未实测。基础机制用确定性 fake provider/tool;真实 provider 做少量单独 smoke 并记录费用,不能把随机模型输出作为唯一门禁。
|
||||
|
||||
| 编号 | 故障/任务 | 必须观察到的结果 |
|
||||
|---|---|---|
|
||||
| MA-T01 | 第一次 429、第二次成功 | 尊重退避、计量 2 次、最终只有一个 accepted answer |
|
||||
| MA-T02 | 连续 schema 参数错误 | 一次修复后停止;工具未在无效参数下执行 |
|
||||
| MA-T03 | 工具写成功但 receipt 提交前杀 worker | unknown_effect→查询对账;写计数不增加 |
|
||||
| MA-T04 | checkpoint 写一半杀进程 | 读取上个完整 checkpoint 或明确 corrupt,不产生伪成功 |
|
||||
| MA-T05 | 终态事件丢失、cursor 重放 | 最终快照恢复完整消息,工具执行次数不增加 |
|
||||
| MA-T06 | 恢复请求重复/并发 | 同一幂等键只产生一个恢复 attempt |
|
||||
| MA-T07 | 用户取消与重试定时器竞争 | 取消生效后无新工具调用,旧任务不复活 |
|
||||
| MA-T08 | 执行中资源/权限改变 | stale/conflict/forbidden,不覆盖新版本 |
|
||||
| MA-T09 | 恶意文本伪造 CALL/system | 不跨越工具白名单和授权范围 |
|
||||
| MA-T10 | `.mq.md` 预览含写文件/联网语句 | 哨兵文件/网络计数不变;只读渲染成功或安全降级 |
|
||||
| MA-T11 | 资源格式、超长输出、路径逃逸 | 正确 renderer/分页;越界拒绝;无 HTML 注入 |
|
||||
| MA-T12 | 修复原文 A 得到通过验证的 B | answer/artifact/verification 都绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后继续 | 最新约束、待决效应、资源版本与剩余预算不丢失 |
|
||||
| MA-T14 | 旧 CALL、旧 DocumentView 消费端 | 基础行为可用,能力缺失有明确返回 |
|
||||
|
||||
先运行受影响的 Rust/Go/Marqdo 合同与既有隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标:已缓存 100 KiB 文本视图服务端 p95 < 300 ms、核心工具发现 p95 < 100 ms,基准机器/并发/冷暖缓存必须记录;第三方网络延迟单独列出。
|
||||
|
||||
## 11. 迁移、回滚与未决项
|
||||
|
||||
兼容迁移按“新增协议→双读→新写→验证→逐步移除旧适配”推进。`.mq.md` 源码与旧运行产物不批量重写;旧 resume JSON 可读取但不能自动升级成带副作用保证的检查点。v2 checkpoint/ledger 保留 schema 版本,新老版本不并发写同一运行。
|
||||
|
||||
回滚关闭新工具自动发现、输出通道或转换器时,已提交资源和最终答案仍可读;执行恢复中的任务先 drain/停止接纳,不能切回会盲重做写操作的旧路径。迁移前备份可变索引与 manifest,回滚不删除用户产物。
|
||||
|
||||
实现前验证项:现有 runtime 持久存储可提供的原子提交边界、各平台 fsync/rename 行为、LLM adapter 原生 tool call 流式兼容、转换插件部署体积。协议优先按本文保守语义实现,验证不能满足则 feature 保持不可用,不阻塞已经完成的只读预览切片。
|
||||
@@ -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 扩表。
|
||||