Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
29418e14f2 | ||
|
|
ac0a3fbced | ||
|
|
a29bf6e97b | ||
|
|
69b626e919 | ||
|
|
63d7866d06 | ||
|
|
27a289217f | ||
|
|
1ae2ae0be8 | ||
|
|
fd128abd13 | ||
|
|
8f44f10bc9 | ||
|
|
23fa4284a8 | ||
|
|
c1a4bb47b6 | ||
|
|
0ae5bce70a | ||
|
|
2cb05fd838 | ||
|
|
117a03ca8e | ||
|
|
84317a1607 |
No files matched your search
+13
@@ -0,0 +1,13 @@
|
||||
/target/
|
||||
**/*.rs.bk
|
||||
.idea/
|
||||
.vscode/
|
||||
*.pdb
|
||||
.DS_Store
|
||||
|
||||
# Python spike venv (local)
|
||||
spike/.venv/
|
||||
spike/__pycache__/
|
||||
spike/.pytest_cache/
|
||||
**/__pycache__/
|
||||
*.pyc
|
||||
@@ -1,17 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 360" width="520" height="360" role="img" aria-label="function plot">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
||||
<path d="M 0 0 L 10 5 L 0 10 z" fill="#4b5563"/>
|
||||
</marker>
|
||||
</defs>
|
||||
<style>
|
||||
.grid { stroke: #e5e7eb; stroke-width: 1; }
|
||||
.axis { stroke: #4b5563; stroke-width: 1.5; }
|
||||
.tick { stroke: #4b5563; stroke-width: 1; }
|
||||
.curve { fill: none; stroke: #1f6feb; stroke-width: 2; }
|
||||
.pt { fill: #1f6feb; }
|
||||
.axis-label { font: 12px ui-sans-serif, system-ui, sans-serif; fill: #374151; font-weight: 600; }
|
||||
.tick-label { font: 10px ui-sans-serif, system-ui, sans-serif; fill: #6b7280; }
|
||||
</style>
|
||||
<line x1="36.00" y1="36" x2="36.00" y2="324" class="grid"/><line x1="110.67" y1="36" x2="110.67" y2="324" class="grid"/><line x1="185.33" y1="36" x2="185.33" y2="324" class="grid"/><line x1="260.00" y1="36" x2="260.00" y2="324" class="grid"/><line x1="334.67" y1="36" x2="334.67" y2="324" class="grid"/><line x1="409.33" y1="36" x2="409.33" y2="324" class="grid"/><line x1="484.00" y1="36" x2="484.00" y2="324" class="grid"/><line x1="36" y1="310.91" x2="484" y2="310.91" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="grid"/><line x1="36" y1="194.55" x2="484" y2="194.55" class="grid"/><line x1="36" y1="136.36" x2="484" y2="136.36" class="grid"/><line x1="36" y1="78.18" x2="484" y2="78.18" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="axis" marker-end="url(#arrow)"/><line x1="260.00" y1="324" x2="260.00" y2="36" class="axis" marker-end="url(#arrow)"/><text x="488.00" y="256.73" class="axis-label">x</text><text x="266.00" y="40.00" class="axis-label">y</text><line x1="36.00" y1="248.73" x2="36.00" y2="256.73" class="tick"/><text x="36.00" y="266.73" text-anchor="middle" class="tick-label">-3</text><line x1="110.67" y1="248.73" x2="110.67" y2="256.73" class="tick"/><text x="110.67" y="266.73" text-anchor="middle" class="tick-label">-2</text><line x1="185.33" y1="248.73" x2="185.33" y2="256.73" class="tick"/><text x="185.33" y="266.73" text-anchor="middle" class="tick-label">-1</text><line x1="334.67" y1="248.73" x2="334.67" y2="256.73" class="tick"/><text x="334.67" y="266.73" text-anchor="middle" class="tick-label">1</text><line x1="409.33" y1="248.73" x2="409.33" y2="256.73" class="tick"/><text x="409.33" y="266.73" text-anchor="middle" class="tick-label">2</text><line x1="484.00" y1="248.73" x2="484.00" y2="256.73" class="tick"/><text x="484.00" y="266.73" text-anchor="middle" class="tick-label">3</text><line x1="256.00" y1="310.91" x2="264.00" y2="310.91" class="tick"/><text x="252.00" y="310.91" text-anchor="end" dominant-baseline="middle" class="tick-label">-2</text><line x1="256.00" y1="194.55" x2="264.00" y2="194.55" class="tick"/><text x="252.00" y="194.55" text-anchor="end" dominant-baseline="middle" class="tick-label">2</text><line x1="256.00" y1="136.36" x2="264.00" y2="136.36" class="tick"/><text x="252.00" y="136.36" text-anchor="end" dominant-baseline="middle" class="tick-label">4</text><line x1="256.00" y1="78.18" x2="264.00" y2="78.18" class="tick"/><text x="252.00" y="78.18" text-anchor="end" dominant-baseline="middle" class="tick-label">6</text><text x="252.00" y="266.73" class="tick-label">0</text><path d="M 36.00 49.09 L 38.24 54.30 L 40.48 59.46 L 42.72 64.56 L 44.96 69.62 L 47.20 74.62 L 49.44 79.57 L 51.68 84.46 L 53.92 89.31 L 56.16 94.10 L 58.40 98.84 L 60.64 103.52 L 62.88 108.16 L 65.12 112.74 L 67.36 117.27 L 69.60 121.75 L 71.84 126.17 L 74.08 130.54 L 76.32 134.86 L 78.56 139.13 L 80.80 143.35 L 83.04 147.51 L 85.28 151.62 L 87.52 155.68 L 89.76 159.68 L 92.00 163.64 L 94.24 167.54 L 96.48 171.39 L 98.72 175.18 L 100.96 178.93 L 103.20 182.62 L 105.44 186.26 L 107.68 189.84 L 109.92 193.38 L 112.16 196.86 L 114.40 200.29 L 116.64 203.67 L 118.88 206.99 L 121.12 210.27 L 123.36 213.49 L 125.60 216.65 L 127.84 219.77 L 130.08 222.83 L 132.32 225.84 L 134.56 228.80 L 136.80 231.71 L 139.04 234.56 L 141.28 237.36 L 143.52 240.11 L 145.76 242.81 L 148.00 245.45 L 150.24 248.05 L 152.48 250.59 L 154.72 253.07 L 156.96 255.51 L 159.20 257.89 L 161.44 260.22 L 163.68 262.50 L 165.92 264.72 L 168.16 266.90 L 170.40 269.02 L 172.64 271.09 L 174.88 273.10 L 177.12 275.07 L 179.36 276.98 L 181.60 278.84 L 183.84 280.64 L 186.08 282.40 L 188.32 284.10 L 190.56 285.75 L 192.80 287.35 L 195.04 288.89 L 197.28 290.38 L 199.52 291.82 L 201.76 293.21 L 204.00 294.55 L 206.24 295.83 L 208.48 297.06 L 210.72 298.24 L 212.96 299.36 L 215.20 300.44 L 217.44 301.46 L 219.68 302.43 L 221.92 303.34 L 224.16 304.21 L 226.40 305.02 L 228.64 305.78 L 230.88 306.48 L 233.12 307.14 L 235.36 307.74 L 237.60 308.29 L 239.84 308.79 L 242.08 309.23 L 244.32 309.63 L 246.56 309.97 L 248.80 310.25 L 251.04 310.49 L 253.28 310.67 L 255.52 310.80 L 257.76 310.88 L 260.00 310.91 L 262.24 310.88 L 264.48 310.80 L 266.72 310.67 L 268.96 310.49 L 271.20 310.25 L 273.44 309.97 L 275.68 309.63 L 277.92 309.23 L 280.16 308.79 L 282.40 308.29 L 284.64 307.74 L 286.88 307.14 L 289.12 306.48 L 291.36 305.78 L 293.60 305.02 L 295.84 304.21 L 298.08 303.34 L 300.32 302.43 L 302.56 301.46 L 304.80 300.44 L 307.04 299.36 L 309.28 298.24 L 311.52 297.06 L 313.76 295.83 L 316.00 294.55 L 318.24 293.21 L 320.48 291.82 L 322.72 290.38 L 324.96 288.89 L 327.20 287.35 L 329.44 285.75 L 331.68 284.10 L 333.92 282.40 L 336.16 280.64 L 338.40 278.84 L 340.64 276.98 L 342.88 275.07 L 345.12 273.10 L 347.36 271.09 L 349.60 269.02 L 351.84 266.90 L 354.08 264.72 L 356.32 262.50 L 358.56 260.22 L 360.80 257.89 L 363.04 255.51 L 365.28 253.07 L 367.52 250.59 L 369.76 248.05 L 372.00 245.45 L 374.24 242.81 Line truncated
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 6.4 KiB |
@@ -1,135 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Welcome to Marqdo
|
||||
description: User-docs home — code as documentation (English)
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Hello — and welcome. I built Marqdo so that code is documentation and documentation is code: Markdown markers are the program structure, so what you read is what runs.
|
||||
|
||||
AI systems already favor Markdown-shaped output. That raised a simple question: why keep docs and programs as two separate artifacts? Marqdo is the answer. The `.mq.md` suffix exists so a file stays renderable as Markdown while remaining executable. Richer OKF-style YAML catalogs and even slide decks are on the roadmap; for now this site itself is generated by Marqdo — and that often saves tokens when an AI is writing with you.
|
||||
|
||||
The language is still early: structural markers, English/Chinese builtin aliases (`print` / `打印` …), an importable standard library (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Join in at [GitHub](https://github.com/cflmy/marqdo).
|
||||
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
Want a quick hello? `marqdo run` executes the entry `# main`. Try **greet who="marqdo"**. Names can include spaces: **greet who="marqdo user"**.
|
||||
|
||||
This version also runs one function on its own. `marqdo call` takes the file, the function and named arguments. The page you read is the program that runs. What that is for, and why it matters, is in [features/22-call.mq.md](features/22-call.mq.md).
|
||||
|
||||
Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention.
|
||||
|
||||
Write a math block and bind it with a TeX comment:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it: **_svg = math.plot formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
Foreign lets you embed another language. Use Node Intl for locale-aware currency formatting, a genuine presentation boundary:
|
||||
|
||||
`hi` =
|
||||
```node
|
||||
console.log(new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"}).format(950));
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code.
|
||||
|
||||
One file, three surfaces.
|
||||
|
||||
| Surface | What it is |
|
||||
|---|---|
|
||||
| Document | ordinary Markdown: prose, tables, links and fenced code |
|
||||
| Program | the same markers are executable: assignments, calls, returns |
|
||||
| Knowledge | frontmatter, links and generated catalog entries an agent can query |
|
||||
|
||||
The static site you are reading is generated from these files, so the examples are not screenshots. Run the same source and you get the same page.
|
||||
|
||||
Foreign v2 is a good example. Probe Node, then run the bound fence:
|
||||
|
||||
We first **node = [Check the formatting runtime](foreign.probe(lang="node"))** for the next step.
|
||||
|
||||
1. [ok](access(`node`, "ok"))
|
||||
We first **hello = [Format the native amount](foreign.run(code=`hi`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`hello`)**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="(node not found — install Node to run this cell)")**.
|
||||
|
||||
The same module also supports JSON calls, parallel fan-out, persistent kernels and an explicit state bridge. See [stdlib/foreign.mq.md](stdlib/foreign.mq.md) and the native-first Intl walkthrough in [features/19-foreign-view-cells.mq.md](features/19-foreign-view-cells.mq.md).
|
||||
|
||||
A view document is still a document. Named kernels and a cell order are ordinary bound tables:
|
||||
|
||||
```text
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | node | shared state |
|
||||
| 复核 | node | isolated state |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | write |
|
||||
| 计算指标 | 分析 | read |
|
||||
| 独立复核 | 复核 | validate |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
`marqdo view` consumes the foreign-owned `会话` handle and turns it into Run All, Step, per-cell kernels, a journal and a state panel. Without `会话`, cells are stateless one-shot runs. There is no separate interactive mode or command; `marqdo run` still executes the file as one program.
|
||||
|
||||
Documentation becomes knowledge when it can be discovered, verified and reused. OKF supplies the portable Markdown + YAML shape; EKC projects the repository into catalog layers L0–L4, a graph and an engineering preflight. The source `.mq.md` remains the only authority; generated artifacts are marked and rebuildable.
|
||||
|
||||
| Loop | Question |
|
||||
|---|---|
|
||||
| OKF | How do people and agents share a readable knowledge page? |
|
||||
| EKC | What existing capability, decision, constraint or failure should be reused before creating more? |
|
||||
| Preflight | REUSE → ADAPT → CREATE |
|
||||
|
||||
Read [features/20-okf-ekc.mq.md](features/20-okf-ekc.mq.md) for the concepts and commands.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
|
||||
Installation choices.
|
||||
|
||||
Install the interpreter (CLI) in any of these ways:
|
||||
|
||||
| Way | Notes |
|
||||
|------|------|
|
||||
| Ubuntu PPA | sudo add-apt-repository ppa:cflmy/marqdo then sudo apt install marqdo |
|
||||
| GitHub Releases | Prebuilt Windows / Linux packages from [releases](https://github.com/cflmy/marqdo/releases) |
|
||||
| From source | cargo build --release (needs a local Rust toolchain) |
|
||||
|
||||
Official extensions update independently of the CLI:
|
||||
|
||||
```text
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` tries CDN https://ext.marqdo.com first, then GitHub, then the proxy mirror. See [`features/05-extensions.mq.md`](features/05-extensions.mq.md).
|
||||
|
||||
|
||||
## greet
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| who | any | required | Recipient name inserted into the greeting |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; this function performs the described effects instead of returning business data |
|
||||
|
||||
When we meet a visitor `who`, we **print text="Welcome, `who`!"** and close with*None*.
|
||||
@@ -1,17 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 360" width="520" height="360" role="img" aria-label="function plot">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
||||
<path d="M 0 0 L 10 5 L 0 10 z" fill="#4b5563"/>
|
||||
</marker>
|
||||
</defs>
|
||||
<style>
|
||||
.grid { stroke: #e5e7eb; stroke-width: 1; }
|
||||
.axis { stroke: #4b5563; stroke-width: 1.5; }
|
||||
.tick { stroke: #4b5563; stroke-width: 1; }
|
||||
.curve { fill: none; stroke: #1f6feb; stroke-width: 2; }
|
||||
.pt { fill: #1f6feb; }
|
||||
.axis-label { font: 12px ui-sans-serif, system-ui, sans-serif; fill: #374151; font-weight: 600; }
|
||||
.tick-label { font: 10px ui-sans-serif, system-ui, sans-serif; fill: #6b7280; }
|
||||
</style>
|
||||
<line x1="36.00" y1="36" x2="36.00" y2="324" class="grid"/><line x1="110.67" y1="36" x2="110.67" y2="324" class="grid"/><line x1="185.33" y1="36" x2="185.33" y2="324" class="grid"/><line x1="260.00" y1="36" x2="260.00" y2="324" class="grid"/><line x1="334.67" y1="36" x2="334.67" y2="324" class="grid"/><line x1="409.33" y1="36" x2="409.33" y2="324" class="grid"/><line x1="484.00" y1="36" x2="484.00" y2="324" class="grid"/><line x1="36" y1="310.91" x2="484" y2="310.91" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="grid"/><line x1="36" y1="194.55" x2="484" y2="194.55" class="grid"/><line x1="36" y1="136.36" x2="484" y2="136.36" class="grid"/><line x1="36" y1="78.18" x2="484" y2="78.18" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="axis" marker-end="url(#arrow)"/><line x1="260.00" y1="324" x2="260.00" y2="36" class="axis" marker-end="url(#arrow)"/><text x="488.00" y="256.73" class="axis-label">x</text><text x="266.00" y="40.00" class="axis-label">y</text><line x1="36.00" y1="248.73" x2="36.00" y2="256.73" class="tick"/><text x="36.00" y="266.73" text-anchor="middle" class="tick-label">-3</text><line x1="110.67" y1="248.73" x2="110.67" y2="256.73" class="tick"/><text x="110.67" y="266.73" text-anchor="middle" class="tick-label">-2</text><line x1="185.33" y1="248.73" x2="185.33" y2="256.73" class="tick"/><text x="185.33" y="266.73" text-anchor="middle" class="tick-label">-1</text><line x1="334.67" y1="248.73" x2="334.67" y2="256.73" class="tick"/><text x="334.67" y="266.73" text-anchor="middle" class="tick-label">1</text><line x1="409.33" y1="248.73" x2="409.33" y2="256.73" class="tick"/><text x="409.33" y="266.73" text-anchor="middle" class="tick-label">2</text><line x1="484.00" y1="248.73" x2="484.00" y2="256.73" class="tick"/><text x="484.00" y="266.73" text-anchor="middle" class="tick-label">3</text><line x1="256.00" y1="310.91" x2="264.00" y2="310.91" class="tick"/><text x="252.00" y="310.91" text-anchor="end" dominant-baseline="middle" class="tick-label">-2</text><line x1="256.00" y1="194.55" x2="264.00" y2="194.55" class="tick"/><text x="252.00" y="194.55" text-anchor="end" dominant-baseline="middle" class="tick-label">2</text><line x1="256.00" y1="136.36" x2="264.00" y2="136.36" class="tick"/><text x="252.00" y="136.36" text-anchor="end" dominant-baseline="middle" class="tick-label">4</text><line x1="256.00" y1="78.18" x2="264.00" y2="78.18" class="tick"/><text x="252.00" y="78.18" text-anchor="end" dominant-baseline="middle" class="tick-label">6</text><text x="252.00" y="266.73" class="tick-label">0</text><path d="M 36.00 49.09 L 38.24 54.30 L 40.48 59.46 L 42.72 64.56 L 44.96 69.62 L 47.20 74.62 L 49.44 79.57 L 51.68 84.46 L 53.92 89.31 L 56.16 94.10 L 58.40 98.84 L 60.64 103.52 L 62.88 108.16 L 65.12 112.74 L 67.36 117.27 L 69.60 121.75 L 71.84 126.17 L 74.08 130.54 L 76.32 134.86 L 78.56 139.13 L 80.80 143.35 L 83.04 147.51 L 85.28 151.62 L 87.52 155.68 L 89.76 159.68 L 92.00 163.64 L 94.24 167.54 L 96.48 171.39 L 98.72 175.18 L 100.96 178.93 L 103.20 182.62 L 105.44 186.26 L 107.68 189.84 L 109.92 193.38 L 112.16 196.86 L 114.40 200.29 L 116.64 203.67 L 118.88 206.99 L 121.12 210.27 L 123.36 213.49 L 125.60 216.65 L 127.84 219.77 L 130.08 222.83 L 132.32 225.84 L 134.56 228.80 L 136.80 231.71 L 139.04 234.56 L 141.28 237.36 L 143.52 240.11 L 145.76 242.81 L 148.00 245.45 L 150.24 248.05 L 152.48 250.59 L 154.72 253.07 L 156.96 255.51 L 159.20 257.89 L 161.44 260.22 L 163.68 262.50 L 165.92 264.72 L 168.16 266.90 L 170.40 269.02 L 172.64 271.09 L 174.88 273.10 L 177.12 275.07 L 179.36 276.98 L 181.60 278.84 L 183.84 280.64 L 186.08 282.40 L 188.32 284.10 L 190.56 285.75 L 192.80 287.35 L 195.04 288.89 L 197.28 290.38 L 199.52 291.82 L 201.76 293.21 L 204.00 294.55 L 206.24 295.83 L 208.48 297.06 L 210.72 298.24 L 212.96 299.36 L 215.20 300.44 L 217.44 301.46 L 219.68 302.43 L 221.92 303.34 L 224.16 304.21 L 226.40 305.02 L 228.64 305.78 L 230.88 306.48 L 233.12 307.14 L 235.36 307.74 L 237.60 308.29 L 239.84 308.79 L 242.08 309.23 L 244.32 309.63 L 246.56 309.97 L 248.80 310.25 L 251.04 310.49 L 253.28 310.67 L 255.52 310.80 L 257.76 310.88 L 260.00 310.91 L 262.24 310.88 L 264.48 310.80 L 266.72 310.67 L 268.96 310.49 L 271.20 310.25 L 273.44 309.97 L 275.68 309.63 L 277.92 309.23 L 280.16 308.79 L 282.40 308.29 L 284.64 307.74 L 286.88 307.14 L 289.12 306.48 L 291.36 305.78 L 293.60 305.02 L 295.84 304.21 L 298.08 303.34 L 300.32 302.43 L 302.56 301.46 L 304.80 300.44 L 307.04 299.36 L 309.28 298.24 L 311.52 297.06 L 313.76 295.83 L 316.00 294.55 L 318.24 293.21 L 320.48 291.82 L 322.72 290.38 L 324.96 288.89 L 327.20 287.35 L 329.44 285.75 L 331.68 284.10 L 333.92 282.40 L 336.16 280.64 L 338.40 278.84 L 340.64 276.98 L 342.88 275.07 L 345.12 273.10 L 347.36 271.09 L 349.60 269.02 L 351.84 266.90 L 354.08 264.72 L 356.32 262.50 L 358.56 260.22 L 360.80 257.89 L 363.04 255.51 L 365.28 253.07 L 367.52 250.59 L 369.76 248.05 L 372.00 245.45 L 374.24 242.81 Line truncated
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 6.4 KiB |
-135
@@ -1,135 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 欢迎使用 Marqdo
|
||||
description: 用户文档首页 — 代码即文档(中文版)
|
||||
导入:
|
||||
数学: lib/数学.mq.md
|
||||
外联: lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门「代码即文档,文档即代码」的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
|
||||
AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套?于是有了 marqdo。为了让文件既能当文档渲染又能执行,后缀定为 `.mq.md`。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT;眼下它至少已经是个不错的博客工具——对,这个站点就是 Marqdo 生成的。AI 写 `.mq.md` 时往往更省 token,钱包也会轻松一点。
|
||||
|
||||
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md)(English prose and English builtins).
|
||||
|
||||
想先打个招呼?`marqdo run` 会运行入口 `# main`。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。
|
||||
|
||||
从这一版起,不必为了试用一个函数再包一层入口。`marqdo call` 直接运行文件里的某个函数,参数写在命令上。同一页仍然是给人读的文档。作用和价值写在 [features/22-函数调用.mq.md](features/22-函数调用.mq.md)。
|
||||
|
||||
除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
|
||||
|
||||
比方说,直接写一块公式,并用 TeX 注释标上变量名:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
接着画出来:**_svg = 数学.绘图 formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
外联则允许嵌一段别的语言。把`hi`绑成下面这样即可:
|
||||
|
||||
`hi` =
|
||||
```node
|
||||
console.log(new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"}).format(950));
|
||||
```
|
||||
|
||||
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。
|
||||
|
||||
一份文件,三个面。
|
||||
|
||||
| 面 | 是什么 |
|
||||
|---|---|
|
||||
| 文档 | 普通 Markdown:叙述、表格、链接、围栏代码 |
|
||||
| 程序 | 同一批标记可执行:赋值、调用、返回 |
|
||||
| 知识 | frontmatter、链接与生成的 catalog 条目,Agent 可查询 |
|
||||
|
||||
你正在读的静态站就是由这些文件生成的,所以示例不是截图。运行同一份源,会得到同一页。
|
||||
|
||||
外联 v2 是个好例子。先探测 Node,再运行绑定围栏:
|
||||
|
||||
我们先**node = [检查本地化展示所需的解释器](外联.探测(语言="node"))**,供下一步使用。
|
||||
|
||||
1. [ok](access(`node`, "ok"))
|
||||
我们先**问候 = [通过 Intl 展示原生金额](外联.运行(代码=`hi`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`问候`)**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="(未找到 node — 安装 Node 后可运行此单元)")**。
|
||||
|
||||
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 [stdlib/外联.mq.md](stdlib/外联.mq.md) 与原生分析与 Intl 示例 [features/19-外联视图单元.mq.md](features/19-外联视图单元.mq.md)。
|
||||
|
||||
view 仍然是一篇文档。命名内核与单元顺序就是普通绑定表:
|
||||
|
||||
```text
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | node | 共享状态 |
|
||||
| 复核 | node | 隔离状态 |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 写入 |
|
||||
| 计算指标 | 分析 | 读取 |
|
||||
| 独立复核 | 复核 | 校验 |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
`marqdo view` 消费 foreign 拥有的 `会话` 句柄,变成 Run All、Step、每单元内核、journal 与状态面板。没有 `会话` 时,单元是无状态的一次性运行。没有单独的交互模式或命令;`marqdo run` 仍然把文件当单个程序运行。
|
||||
|
||||
文档能被发现、验证和复用时,才成为知识。OKF 提供可移植的 Markdown + YAML 形态;EKC 把仓库投影成 catalog L0–L4、图与工程 preflight。源 `.mq.md` 始终是唯一权威,生成物有标记、可重建。
|
||||
|
||||
| 循环 | 问题 |
|
||||
|---|---|
|
||||
| OKF | 人和 Agent 如何共享一页可读知识? |
|
||||
| EKC | 创建之前,应该复用哪些已有能力、决策、约束与失败? |
|
||||
| Preflight | REUSE → ADAPT → CREATE |
|
||||
|
||||
概念与命令见 [features/20-OKF与EKC.mq.md](features/20-OKF与EKC.mq.md)。
|
||||
|
||||
最后,再次欢迎你,尽情体验 marqdo 吧!
|
||||
|
||||
安装方式。
|
||||
|
||||
解释器(CLI)任选其一:
|
||||
|
||||
| 方式 | 说明 |
|
||||
|------|------|
|
||||
| Ubuntu PPA | sudo add-apt-repository ppa:cflmy/marqdo 后 sudo apt install marqdo |
|
||||
| GitHub Releases | [releases](https://github.com/cflmy/marqdo/releases) 下载 Windows / Linux 预编译包 |
|
||||
| 源码 | cargo build --release(需本机 Rust) |
|
||||
|
||||
官方扩展与 CLI 可分开更新。安装扩展:
|
||||
|
||||
```text
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` 下载顺序:CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 [`features/05-扩展.mq.md`](features/05-扩展.mq.md)。
|
||||
|
||||
|
||||
## 问候
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 谁 | any | 必填 | 要显示在问候中的称呼 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;本函数通过上述操作产生效果,不返回业务数据。 |
|
||||
|
||||
见到访客`谁`时,我们 **打印 内容="欢迎,`谁`!"**,然后收束为*None*。
|
||||
Generated
+447
@@ -0,0 +1,447 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 3
|
||||
|
||||
[[package]]
|
||||
name = "aho-corasick"
|
||||
version = "1.1.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
|
||||
dependencies = [
|
||||
"memchr",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "anstream"
|
||||
version = "0.6.21"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a"
|
||||
dependencies = [
|
||||
"anstyle",
|
||||
"anstyle-parse",
|
||||
"anstyle-query",
|
||||
"anstyle-wincon",
|
||||
"colorchoice",
|
||||
"is_terminal_polyfill",
|
||||
"utf8parse",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "anstyle"
|
||||
version = "1.0.14"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
|
||||
|
||||
[[package]]
|
||||
name = "anstyle-parse"
|
||||
version = "0.2.7"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2"
|
||||
dependencies = [
|
||||
"utf8parse",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "anstyle-query"
|
||||
version = "1.1.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
|
||||
dependencies = [
|
||||
"windows-sys",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "anstyle-wincon"
|
||||
version = "3.0.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
|
||||
dependencies = [
|
||||
"anstyle",
|
||||
"once_cell_polyfill",
|
||||
"windows-sys",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "anyhow"
|
||||
version = "1.0.104"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
|
||||
|
||||
[[package]]
|
||||
name = "ascii"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d92bec98840b8f03a5ff5413de5293bfcd8bf96467cf5452609f939ec6f5de16"
|
||||
|
||||
[[package]]
|
||||
name = "assert_cmd"
|
||||
version = "2.0.14"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ed72493ac66d5804837f480ab3766c72bdfab91a65e565fc54fa9e42db0073a8"
|
||||
dependencies = [
|
||||
"anstyle",
|
||||
"bstr",
|
||||
"doc-comment",
|
||||
"predicates",
|
||||
"predicates-core",
|
||||
"predicates-tree",
|
||||
"wait-timeout",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "autocfg"
|
||||
version = "1.5.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
|
||||
|
||||
[[package]]
|
||||
name = "bstr"
|
||||
version = "1.13.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1f7dc094d718f2e1c1559ad110e27eeaae14a5465d3d56dd6dbd793079fbd530"
|
||||
dependencies = [
|
||||
"memchr",
|
||||
"regex-automata",
|
||||
"serde_core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "chunked_transfer"
|
||||
version = "1.5.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6e4de3bc4ea267985becf712dc6d9eed8b04c953b3fcfb339ebc87acd9804901"
|
||||
|
||||
[[package]]
|
||||
name = "clap"
|
||||
version = "4.4.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1e578d6ec4194633722ccf9544794b71b1385c3c027efe0c55db226fc880865c"
|
||||
dependencies = [
|
||||
"clap_builder",
|
||||
"clap_derive",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "clap_builder"
|
||||
version = "4.4.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4df4df40ec50c46000231c914968278b1eb05098cf8f1b3a518a95030e71d1c7"
|
||||
dependencies = [
|
||||
"anstream",
|
||||
"anstyle",
|
||||
"clap_lex",
|
||||
"strsim",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "clap_derive"
|
||||
version = "4.4.7"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cf9804afaaf59a91e75b022a30fb7229a7901f60c755489cc61c9b423b836442"
|
||||
dependencies = [
|
||||
"heck",
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "clap_lex"
|
||||
version = "0.6.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "702fc72eb24e5a1e48ce58027a675bc24edd52096d5397d4aea7c6dd9eca0bd1"
|
||||
|
||||
[[package]]
|
||||
name = "colorchoice"
|
||||
version = "1.0.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
|
||||
|
||||
[[package]]
|
||||
name = "difflib"
|
||||
version = "0.4.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
|
||||
|
||||
[[package]]
|
||||
name = "doc-comment"
|
||||
version = "0.3.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9"
|
||||
|
||||
[[package]]
|
||||
name = "float-cmp"
|
||||
version = "0.9.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4"
|
||||
dependencies = [
|
||||
"num-traits",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "heck"
|
||||
version = "0.4.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
|
||||
|
||||
[[package]]
|
||||
name = "httpdate"
|
||||
version = "1.0.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
|
||||
|
||||
[[package]]
|
||||
name = "is_terminal_polyfill"
|
||||
version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
|
||||
|
||||
[[package]]
|
||||
name = "libc"
|
||||
version = "0.2.189"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
|
||||
|
||||
[[package]]
|
||||
name = "log"
|
||||
version = "0.4.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"clap",
|
||||
"predicates",
|
||||
"thiserror",
|
||||
"tiny_http",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "memchr"
|
||||
version = "2.8.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
|
||||
|
||||
[[package]]
|
||||
name = "normalize-line-endings"
|
||||
version = "0.3.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "61807f77802ff30975e01f4f071c8ba10c022052f98b3294119f3e615d13e5be"
|
||||
|
||||
[[package]]
|
||||
name = "num-traits"
|
||||
version = "0.2.19"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
|
||||
dependencies = [
|
||||
"autocfg",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "once_cell_polyfill"
|
||||
version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
||||
|
||||
[[package]]
|
||||
name = "predicates"
|
||||
version = "3.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "68b87bfd4605926cdfefc1c3b5f8fe560e3feca9d5552cf68c466d3d8236c7e8"
|
||||
dependencies = [
|
||||
"anstyle",
|
||||
"difflib",
|
||||
"float-cmp",
|
||||
"normalize-line-endings",
|
||||
"predicates-core",
|
||||
"regex",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "predicates-core"
|
||||
version = "1.0.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cad38746f3166b4031b1a0d39ad9f954dd291e7854fcc0eed52ee41a0b50d144"
|
||||
|
||||
[[package]]
|
||||
name = "predicates-tree"
|
||||
version = "1.0.13"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d0de1b847b39c8131db0467e9df1ff60e6d0562ab8e9a16e568ad0fdb372e2f2"
|
||||
dependencies = [
|
||||
"predicates-core",
|
||||
"termtree",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "proc-macro2"
|
||||
version = "1.0.107"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
|
||||
dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "quote"
|
||||
version = "1.0.47"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "regex"
|
||||
version = "1.13.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
|
||||
dependencies = [
|
||||
"aho-corasick",
|
||||
"memchr",
|
||||
"regex-automata",
|
||||
"regex-syntax",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "regex-automata"
|
||||
version = "0.4.16"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
|
||||
dependencies = [
|
||||
"aho-corasick",
|
||||
"memchr",
|
||||
"regex-syntax",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "regex-syntax"
|
||||
version = "0.8.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
|
||||
|
||||
[[package]]
|
||||
name = "serde_core"
|
||||
version = "1.0.229"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
|
||||
dependencies = [
|
||||
"serde_derive",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_derive"
|
||||
version = "1.0.229"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 3.0.3",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "strsim"
|
||||
version = "0.10.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
|
||||
|
||||
[[package]]
|
||||
name = "syn"
|
||||
version = "2.0.119"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "syn"
|
||||
version = "3.0.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "termtree"
|
||||
version = "0.5.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8f50febec83f5ee1df3015341d8bd429f2d1cc62bcba7ea2076759d315084683"
|
||||
|
||||
[[package]]
|
||||
name = "thiserror"
|
||||
version = "1.0.69"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
|
||||
dependencies = [
|
||||
"thiserror-impl",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "thiserror-impl"
|
||||
version = "1.0.69"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tiny_http"
|
||||
version = "0.12.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "389915df6413a2e74fb181895f933386023c71110878cd0825588928e64cdc82"
|
||||
dependencies = [
|
||||
"ascii",
|
||||
"chunked_transfer",
|
||||
"httpdate",
|
||||
"log",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "unicode-ident"
|
||||
version = "1.0.24"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
|
||||
|
||||
[[package]]
|
||||
name = "utf8parse"
|
||||
version = "0.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
|
||||
|
||||
[[package]]
|
||||
name = "wait-timeout"
|
||||
version = "0.2.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
|
||||
dependencies = [
|
||||
"libc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-link"
|
||||
version = "0.2.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
|
||||
|
||||
[[package]]
|
||||
name = "windows-sys"
|
||||
version = "0.61.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
|
||||
dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.0.1"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
readme = "README.md"
|
||||
repository = "https://github.com/cflmy/marqdo"
|
||||
|
||||
[[bin]]
|
||||
name = "marqdo"
|
||||
path = "src/main.rs"
|
||||
|
||||
[dependencies]
|
||||
anyhow = "1"
|
||||
clap = { version = "=4.4.18", features = ["derive"] }
|
||||
thiserror = "1"
|
||||
tiny_http = "0.12"
|
||||
|
||||
[dev-dependencies]
|
||||
assert_cmd = "=2.0.14"
|
||||
predicates = "=3.1.0"
|
||||
@@ -0,0 +1,201 @@
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
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.
|
||||
@@ -1,34 +1,73 @@
|
||||
# 用户文档(可执行 · 可下载 · 中英双语)
|
||||
# Marqdo
|
||||
|
||||
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
|
||||
**代码即文档。文档即代码。**
|
||||
|
||||
**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
|
||||
Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程序。
|
||||
|
||||
| 路径 | 内容 |
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 示例布局:[examples-and-tests.md](doc/design/examples-and-tests.md) · 浏览:[view.md](doc/design/view.md) · 示例:[examples/](examples/)
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.1)
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
|
||||
| [`structure/`](structure/) | 基本结构 |
|
||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
| [`features/19-foreign-view-cells.mq.md`](features/19-foreign-view-cells.mq.md) / [`19-外联视图单元.mq.md`](features/19-外联视图单元.mq.md) | 外联 v2 完整 Python 示例:probe / JSON call / 并行 / 持久内核 / 状态桥 / view 单元 |
|
||||
| [`features/20-okf-ekc.mq.md`](features/20-okf-ekc.mq.md) / [`20-OKF与EKC.mq.md`](features/20-OKF与EKC.mq.md) | 代码即文档、文档即知识:OKF 形态与 EKC 工程知识编译器 |
|
||||
| [`features/21-persistence.mq.md`](features/21-persistence.mq.md) / [`21-持久化.mq.md`](features/21-持久化.mq.md) | 外联结果持久化:静态快照与 writeback |
|
||||
| [`features/22-call.mq.md`](features/22-call.mq.md) / [`22-函数调用.mq.md`](features/22-函数调用.mq.md) | `marqdo call`:同一份文档按函数执行,知识可以直接当工具 |
|
||||
| 无标记行 | 注释 |
|
||||
| `*…*` | 程序语句 |
|
||||
| `**…**` | **返回值**(架构) |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` / `##` | 函数与作用域 |
|
||||
| `+` / `1.` | 分支(臂头单独 `*` = else) |
|
||||
| `-` | 循环(头下纯名则为形参) |
|
||||
| 表格 | 集合 |
|
||||
| `---` / `***` | 可选:框住分支/循环(不强制) |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent`、`ext/web`、`ext/quantum`、`ext/linalg` — 见 `features/05-*.mq.md`、`06-*.mq.md`、`07-linalg.mq.md` / `07-线性代数.mq.md` 与 `doc/design/ext-*.md`。
|
||||
```markdown
|
||||
# main
|
||||
|
||||
中层标准库(Mid):`08`–`12`(re/encoding · path/fs · hash/secrets · csv/text · list/cli;及对应中文页)。
|
||||
> print text=Hello World!
|
||||
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`。
|
||||
## 加一
|
||||
- n
|
||||
|
||||
开发文档在 [`doc/`](../doc/)。
|
||||
|
||||
## 浏览与生成 HTML
|
||||
|
||||
```bash
|
||||
cargo run -- view public
|
||||
cargo run -- view output public -o public
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
详见 [user-site.md](../doc/design/user-site.md)。
|
||||
---
|
||||
|
||||
## 理念
|
||||
|
||||
1. 叙述默认安全(无标记 = 注释)。
|
||||
2. 返回是架构;打印只是函数。
|
||||
3. 依赖清单由工具生成(OKF 风格),不是手填配置。
|
||||
4. **正经解释器(Rust)**:词法/行分类 → 递归下降语法 → 语义 → 树遍历 → 日后字节码;**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md) 与 [依赖说明](doc/design/dependencies.md)。
|
||||
|
||||
---
|
||||
|
||||
## 现状
|
||||
|
||||
- 映射 v0.1:[markdown-mapping.md](doc/design/markdown-mapping.md)
|
||||
- 解释器路线图:[interpreter.md](doc/roadmap/interpreter.md)
|
||||
- **Phase I(树遍历)已通**:`examples/structure/` 与 `examples/keywords/` 金样例均可 `marqdo run`
|
||||
- **view**:`marqdo view examples` 按 AST 浏览结构与输出
|
||||
- 依赖(Rust,无 Flex/Bison):[dependencies.md](doc/design/dependencies.md)
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
|
||||
```bash
|
||||
cargo run -- run examples/structure/hello.mq.md
|
||||
cargo run -- run examples/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view examples --no-open
|
||||
```
|
||||
|
||||
当前发布:**v0.0.1**(Phase I 树遍历 + `view` + M5 字节码原型)。M5 见 [bytecode.md](doc/design/bytecode.md);errors 见 `examples/errors/`。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 命名
|
||||
|
||||
**Marqdo** = Marq(Markdown)+ do(执行)
|
||||
|
||||
## 许可
|
||||
|
||||
[Apache License 2.0](LICENSE)
|
||||
@@ -0,0 +1,41 @@
|
||||
# Marqdo 开发文档
|
||||
|
||||
本目录存放各阶段设计、选型与路线图。
|
||||
|
||||
## 目录约定
|
||||
|
||||
| 路径 | 用途 |
|
||||
|------|------|
|
||||
| [`research/`](research/) | 外部标准与调研 |
|
||||
| [`design/`](design/) | 语言设计(语法映射等) |
|
||||
| [`adr/`](adr/) | 架构决策记录 |
|
||||
| [`roadmap/`](roadmap/) | 实现路线与里程碑 |
|
||||
|
||||
## 当前文档
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
|
||||
| [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/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
|
||||
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
|
||||
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置 `print` `input`** |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **示例即金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` 源结构浏览器** |
|
||||
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
|
||||
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
|
||||
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
|
||||
| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
|
||||
示例与验收集:[`examples/`](../examples/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
## 写作原则
|
||||
|
||||
1. 先宪法与路线图,再实现。
|
||||
2. 金样例不过 = 未完成。
|
||||
3. 示例统一 `.mq.md`。
|
||||
@@ -0,0 +1,53 @@
|
||||
# ADR 0001:参考实现语言与前端工具
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**(修订:实现语言 = Rust) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 决策者 | chaungming + 协作 |
|
||||
| 相关 | [dependencies.md](../design/dependencies.md) · [interpreter 路线图](../roadmap/interpreter.md) · [spike/REPORT.md](../../spike/REPORT.md) |
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
语法宪法 v0.1 已定;Python Spike 已验证 GFM/行扫描风险。产品目标是正经**解释器**(`marqdo run index.mq.md`),实现语言需兼顾安全与可维护性。
|
||||
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
1. **参考解释器实现语言:Rust(stable)**
|
||||
- 内存安全、单静态二进制、适合长期演进到字节码 VM。
|
||||
- Python Spike **保留为算法原型/对照**,不是运行时依赖。
|
||||
|
||||
2. **词法 / 语法:不使用 Flex、Bison**
|
||||
- **主因是 Marqdo 的 Markdown 语法形态**,不是「因为选了 Rust」。换成 C++ 同样不建议用 Flex/Bison 做整语言前端。
|
||||
- 解释器需要词法·语法**阶段**;采用自研行分类 + GFM 库 + **手写递归下降** → AST。
|
||||
- 详见 [dependencies.md](../design/dependencies.md)。
|
||||
|
||||
3. **架构分期不变**
|
||||
- Phase I:树遍历解释器
|
||||
- Phase II:字节码 + VM
|
||||
- 见 [interpreter.md](../roadmap/interpreter.md)
|
||||
|
||||
4. **Markdown 库**
|
||||
- `pulldown-cmark` 或 `comrak` 二选一(建包前短 Spike 钉死)。
|
||||
|
||||
---
|
||||
|
||||
## 后果
|
||||
|
||||
- 正式代码以 Cargo 工程生长;不把 Flex/Bison/LLVM 列入 v1 依赖。
|
||||
- 金样例仍为 `examples/`;行为与宪法一致。
|
||||
- 此前「Python 作参考实现」的倾向由本修订取代;Spike 结论(行扫描等)仍然有效并迁入 Rust。
|
||||
|
||||
---
|
||||
|
||||
## 否决
|
||||
|
||||
| 方案 | 原因 |
|
||||
|------|------|
|
||||
| Flex + Bison 作主前端 | 与 Markup-as-Syntax / Rust 栈错配;解释器非必需 |
|
||||
| v1 上 LLVM | 产品是解释执行文档,不是机器后端 |
|
||||
| 仅 Python 正则玩具 | 达不到安全与长期目标 |
|
||||
@@ -0,0 +1,89 @@
|
||||
# Marqdo 字节码(M5 原型)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 进行中(原型) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [roadmap/interpreter.md](../roadmap/interpreter.md) · Phase I 树遍历 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在保留树遍历后端(`--backend tree`,默认)的同时,提供栈式字节码 VM(`--backend bytecode`),使**核心金样例** stdout 与树遍历 bit 一致。
|
||||
|
||||
```
|
||||
.mq.md → load/parse → Module AST
|
||||
├─ tree-walk
|
||||
└─ compile → Chunk → VM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 指令集(草案 / 原型已实现子集)
|
||||
|
||||
| Op | 栈效应 | 说明 |
|
||||
|----|--------|------|
|
||||
| `Constant i` | → v | 常量池 |
|
||||
| `True` / `False` / `None` | → b | |
|
||||
| `Pop` | v → | |
|
||||
| `GetLocal i` / `SetLocal i` | | 当前帧槽 |
|
||||
| `GetGlobal i` / `SetGlobal i` | | 名字在常量池(文本) |
|
||||
| `Add` `Sub` `Mul` `Div` `Negate` `Not` | | |
|
||||
| `Equal` `NotEqual` `Greater` `GreaterEqual` `Less` `LessEqual` | | |
|
||||
| `Jump a` / `JumpIfFalse a` / `JumpBack a` | | 相对/绝对跳转(原型用绝对 u16) |
|
||||
| `Print` | v → | 弹出并写 stdout |
|
||||
| `BuildList n` | v… → list | |
|
||||
| `GetIndex` | list, i → v | foreach 用 |
|
||||
| `Call f argc` | args… → ret | 用户函数(按形参序压栈) |
|
||||
| `Return` | | 返回 / 结束帧 |
|
||||
| `Interp n` | parts… → text | n 个交错 Lit/Var 标记后的拼接(简化:编译期展开为常量+拼接) |
|
||||
|
||||
原型实现以 `src/bytecode/` 为准;未列出的 Op 不存在于当前构建。
|
||||
|
||||
---
|
||||
|
||||
## 3. 编译约定
|
||||
|
||||
- 每个 Marqdo `Function` → 一个 `FnChunk`(含 `name`、`params`、`code`、`constants`)。
|
||||
- 模块级 `Program`:函数表 + 入口名(`main` 或唯一无参 level-1)。
|
||||
- 局部变量:函数体内首次赋值/形参分配槽位。
|
||||
- 嵌套 `##`:编入同一 `Program`,按名 `Call`;查找规则对齐树遍历(子树优先,再顶层)。
|
||||
- `and` / `or`:短接跳转。
|
||||
- 分支 / while:`JumpIfFalse` + `Jump` / `JumpBack`。
|
||||
- foreach:`BuildList` 或已有 list 全局/局部 → 索引循环。
|
||||
|
||||
---
|
||||
|
||||
## 4. 覆盖表(M5 原型)
|
||||
|
||||
| 金样例 | tree | bytecode |
|
||||
|--------|------|----------|
|
||||
| `structure/hello` | ✅ | ✅ |
|
||||
| `structure/branch` | ✅ | ✅ |
|
||||
| `structure/loop` | ✅ | ✅ |
|
||||
| `structure/collection` | ✅ | ✅ |
|
||||
| `keywords/print` | ✅ | ✅ |
|
||||
| `keywords/bool-logic` | ✅ | ✅ |
|
||||
| `structure/nested-call` | ✅ | ✅ |
|
||||
| `structure/positional-call` | ✅ | ✅ |
|
||||
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
|
||||
| `examples/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
|
||||
|
||||
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
|
||||
|
||||
---
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo run FILE --backend tree # 默认
|
||||
marqdo run FILE --backend bytecode
|
||||
marqdo run FILE --dump-bytecode # 反汇编后仍可按 backend 执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 非目标(本原型)
|
||||
|
||||
优化、寄存器分配、GC、与树遍历指令级调试对齐、独立 sema IR。
|
||||
@@ -0,0 +1,50 @@
|
||||
# 调用实参:具名与位置
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`>` 调用同时支持:
|
||||
|
||||
| 形式 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
|
||||
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
|
||||
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 文法(调用尾部)
|
||||
|
||||
```
|
||||
call_tail ::= callee arg*
|
||||
arg ::= named | positional
|
||||
named ::= ident '=' value
|
||||
positional ::= value_token
|
||||
```
|
||||
|
||||
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
|
||||
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
|
||||
- 内置 `print` 形参名为 `text`:`> print Hi` 与 `> print text=Hi` 等价。
|
||||
|
||||
---
|
||||
|
||||
## 3. 绑定算法
|
||||
|
||||
1. 收集具名 → 映射;冲突则报错。
|
||||
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
|
||||
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
|
||||
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
|
||||
|
||||
---
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `examples/structure/positional-call.mq.md` 与更新后的 `examples/structure/import/`。
|
||||
@@ -0,0 +1,28 @@
|
||||
# 可执行面与叙述面
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐 |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
|
||||
## 三层
|
||||
|
||||
| 层 | 形态 | 角色 |
|
||||
|----|------|------|
|
||||
| **叙述面** | 无标记行 | 注释;内部标记无语义 |
|
||||
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
|
||||
| **外联面** | ` ```lang ` | 其它语言(FFI) |
|
||||
|
||||
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
|
||||
|
||||
---
|
||||
|
||||
## 语句 vs 返回 vs 输出
|
||||
|
||||
| 标记/形式 | 角色 | 是否架构级 |
|
||||
|-----------|------|------------|
|
||||
| `*…*` | 程序语句 | 是 |
|
||||
| `**…**` | 返回值 | 是 |
|
||||
| `> print …` | 打印副作用 | 否(内置函数) |
|
||||
@@ -0,0 +1,174 @@
|
||||
# Marqdo 实现依赖说明(Rust 参考解释器)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [ADR 0001](../adr/0001-implementation-language.md) · [interpreter 路线图](../roadmap/interpreter.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 要不要 Flex / Bison?
|
||||
|
||||
### 结论:**不需要。** 主因不是「用了 Rust」,而是 **Marqdo 的语法形态 + 解释器并不绑定生成器。**
|
||||
|
||||
把两件事分开:
|
||||
|
||||
| 问题 | 答案 |
|
||||
|------|------|
|
||||
| 因为 Rust 才不用 Flex/Bison? | **否。** Flex/Bison 生成的是 C(也可接 C++)。若实现改成 **C++**,**仍然不建议**用它们做 Marqdo 主前端。 |
|
||||
| 因为是解释器才不用? | **部分相关,但不是全部。** 解释器**需要**词法/语法阶段,但**不规定**必须用 Flex/Bison;手写递归下降是主流。即便将来做「编译到字节码/原生」,Marqdo 也因 Markdown 外壳而不适合整语言 Bison 化。 |
|
||||
| 真正主因 | **Markup-as-Syntax**:源是 GFM 文档结构(标题/列表/强调/表格/行分类),不是 Cminusf 那种纯字符流文法。 |
|
||||
|
||||
| 工具 | 典型用途 | Marqdo 为何不用(与宿主语言无关) |
|
||||
|------|----------|----------------------------------|
|
||||
| **Flex** | 正则 → C 词法分析器 | 「词法」是 **行分类 + Markdown 标记**,不是经典 `id\|num\|op` 字符流 |
|
||||
| **Bison** | Yacc 文法 → C LR 分析器 | 整体语法绑在 **GFM 块结构**上,硬写成单一 Bison 文法别扭且难与预览器对齐 |
|
||||
|
||||
[USTC 编译课 Lab1](https://ustc-compiler-2025.github.io/homepage/) 用 Flex/Bison,是因为对象语言是 **C 式源码的编译器**;换 C++ 写那个编译器也合理。
|
||||
Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这一判断。
|
||||
|
||||
**解释型语言同样需要词法与语法分析**,要的是阶段,不是这两个具体程序。
|
||||
|
||||
---
|
||||
|
||||
## 2. Marqdo 前端应怎样做(替代 Flex/Bison)
|
||||
|
||||
拆成三层,比「一个大 lexer/parser」更贴合宪法:
|
||||
|
||||
```
|
||||
.mq.md 文本
|
||||
│
|
||||
├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行
|
||||
├─② GFM 块/行内(库) 标题、表、强调、列表结构
|
||||
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `> file.mq.md`
|
||||
└─④ Marqdo 语法(自研) 递归下降:Module/Fun/Stmt/Expr → AST
|
||||
└─ 表达式子语言 可手写,或仅对 Expr 用 pest/nom
|
||||
```
|
||||
|
||||
| 阶段 | 做法 | 对应编译学 |
|
||||
|------|------|------------|
|
||||
| ①③ | Rust 手写扫描 | 词法 / 扫描器 |
|
||||
| ② | `pulldown-cmark` 或 `comrak` | 复用 GFM,避免自研表格/强调 |
|
||||
| ④ | **手写递归下降**(推荐主路径) | 语法分析 |
|
||||
| Expr(可选) | `pest`(PEG)或 `nom`(组合子) | 仅迷你表达式,不是整门语言 |
|
||||
|
||||
**不推荐**整门语言上 LALRPOP / rusty_lr / Bison 等价物作为 v1 主前端:Markdown 外壳 + 行语义会让文法极度别扭。若将来有「纯文本 Marqdo 方言」,再另议生成器。
|
||||
|
||||
---
|
||||
|
||||
## 3. 详细依赖清单(Rust)
|
||||
|
||||
### 3.1 工具链(开发机)
|
||||
|
||||
| 依赖 | 用途 | 安装 |
|
||||
|------|------|------|
|
||||
| **Rust**(stable,建议 ≥ 1.75) | 编译实现 | [rustup](https://rustup.rs/):`rustup default stable` |
|
||||
| **Cargo** | 包与构建 | 随 rustup |
|
||||
| **rustfmt / clippy** | 格式与静态检查 | `rustup component add rustfmt clippy` |
|
||||
| **Git** | 版本管理 | 已有 |
|
||||
|
||||
**不要安装:** Flex、Bison、LLVM(v1 解释器不需要)。
|
||||
(日后若做原生后端再开 ADR;与当前解释器无关。)
|
||||
|
||||
### 3.2 Cargo crate(建议写入根 `Cargo.toml` / workspace)
|
||||
|
||||
#### 必选(Phase I 树遍历解释器)
|
||||
|
||||
| Crate | 角色 | 说明 |
|
||||
|-------|------|------|
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **camino** 或标准 `PathBuf` | 路径 |
|
||||
| **indexmap** | 保序 map(模块导出等) |
|
||||
|
||||
#### 测试
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **rust 自带** `#[test]` | 单元测试 |
|
||||
| **insta** 或手写金文件 | examples 期望 stdout 快照(可选) |
|
||||
| **assert_cmd** / **predicates** | CLI 集成测试(可选) |
|
||||
|
||||
#### Phase II(字节码 VM,后加)
|
||||
|
||||
无强制新依赖;VM 以自研为主。可选:
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **num_enum** 等 | opcode 枚举(可选) |
|
||||
|
||||
#### 明确不引入(v1)
|
||||
|
||||
| 东西 | 原因 |
|
||||
|------|------|
|
||||
| flex / bison / lemon | 见 §1 |
|
||||
| lalrpop / rusty_lr 作**整语言**前端 | 与 MD 外壳冲突;递归下降更合适 |
|
||||
| llvm-sys / inkwell | 非解释器 v1 |
|
||||
| 完整 Python 运行时嵌入 | 参考实现已定为 Rust,避免双运行时 |
|
||||
|
||||
### 3.3 表达式子语言(可选增强)
|
||||
|
||||
若手写 Expr 递归下降过痛,**仅**对 `` `a` + 1 == `b` `` 这类表达式引入其一:
|
||||
|
||||
| 选项 | 类型 | 何时用 |
|
||||
|------|------|--------|
|
||||
| **手写递归下降** | 无新依赖 | 默认;与全书一致、错误信息最好控 |
|
||||
| **pest** | PEG 生成器 | 文法清晰、想要 `.pest` 文件时 |
|
||||
| **nom** | 解析组合子 | 要零拷贝/细控时 |
|
||||
|
||||
整文件 `.mq.md` **不要**整份丢给 pest/nom。
|
||||
|
||||
---
|
||||
|
||||
## 4. 仓库布局(与依赖对应)
|
||||
|
||||
```
|
||||
Cargo.toml # workspace 或单包
|
||||
crates/marqdo/ # 或根包 marqdo
|
||||
src/
|
||||
main.rs / lib.rs
|
||||
lex/ # 行分类、Token(自研,无 flex)
|
||||
parse/ # 递归下降(自研,无 bison)
|
||||
ast/
|
||||
sema/
|
||||
interp/ # Phase I
|
||||
bytecode/ # Phase II
|
||||
runtime/
|
||||
tests/
|
||||
examples/ # 金样例(已有)
|
||||
spike/ # Python 风险探测存档(可保留,非运行时依赖)
|
||||
```
|
||||
|
||||
开发命令示例:
|
||||
|
||||
```bash
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run examples/structure/nested-call.mq.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 Python Spike 的关系
|
||||
|
||||
| | Python `spike/` | Rust 参考实现 |
|
||||
|--|-----------------|---------------|
|
||||
| 角色 | 已验证 S1–S5 风险 | **正式**词法/语法/语义/解释器 |
|
||||
| 是否运行时依赖 | 否 | 是 |
|
||||
| 算法可迁移 | 行扫描、`split_front_matter`、导入正则 | 用 Rust 重写同算法 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话对照
|
||||
|
||||
- **需要:** 词法(行分类+标记)、语法(递归下降→AST)、语义、解释器/日后 VM。
|
||||
- **不需要:** Flex、Bison、LLVM(v1)。
|
||||
- **外部库只需:** Rust 工具链 + GFM crate(pulldown-cmark/comrak)+ CLI/错误/测试若干;表达式可选 pest/nom。
|
||||
@@ -0,0 +1,76 @@
|
||||
# 示例与测试布局
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **示例即金样例**:`examples/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view` 也可直接浏览 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目录
|
||||
|
||||
```
|
||||
examples/
|
||||
README.md # 本树说明
|
||||
structure/ # 代码基础结构(Markup 架构)
|
||||
hello.mq.md
|
||||
nested-call.mq.md # 原 index:嵌套函数 + 调用
|
||||
positional-call.mq.md # 位置实参
|
||||
branch.mq.md
|
||||
loop.mq.md
|
||||
collection.mq.md
|
||||
import/
|
||||
main.mq.md # 原 with-import
|
||||
utils.mq.md
|
||||
keywords/ # 关键字与内置名
|
||||
print.mq.md
|
||||
bool-logic.mq.md # True/False/None、and/or/not
|
||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
||||
.gitkeep
|
||||
```
|
||||
|
||||
Rust 集成测试:`tests/gold.rs` 扫描约定路径,比对 stdout。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分类职责
|
||||
|
||||
| 类别 | 测什么 | 不测什么 |
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
未单独建夹、但应覆盖的其它测试(放 `tests/` 单测或日后 `examples/runtime/`):
|
||||
|
||||
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
|
||||
- **CLI**:默认 `index.mq.md`、退出码
|
||||
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
|
||||
- **模块图**:循环导入拒绝
|
||||
|
||||
---
|
||||
|
||||
## 3. 金样例约定
|
||||
|
||||
每个可执行 `.mq.md` 在 `tests/gold.rs`(或旁路 `.out` 文件)登记期望 stdout。
|
||||
`errors/` 内文件登记期望 stderr 子串与非零退出码。
|
||||
|
||||
Frontmatter 可写:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: …
|
||||
expect_stdout: |
|
||||
line1
|
||||
line2
|
||||
---
|
||||
```
|
||||
|
||||
(可选;v0 先以测试代码内嵌期望为主。)
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view` 的关系
|
||||
|
||||
`marqdo view examples` 按上述文件夹生成侧栏索引;`structure` / `keywords` 为一级分组。
|
||||
@@ -0,0 +1,163 @@
|
||||
# 设计草案:机器生成的 YAML 清单(OKF 风格)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
|
||||
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
|
||||
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具自动生成的产物,不是给人填的配置文件。**
|
||||
|
||||
它的角色接近其它语言里由工具维护的**依赖与包元数据**,例如:
|
||||
|
||||
| 生态 | 类比(职责相近,不是语法相同) |
|
||||
|------|--------------------------------|
|
||||
| Rust | `Cargo.toml` / 解析后的依赖图(由源与清单共同推导,工具可改写) |
|
||||
| Python | `requirements.txt`(常由解析/冻结生成) |
|
||||
| Go | `go.mod` + `go.sum`(`go mod tidy` 维护) |
|
||||
|
||||
我们选择 **OKF 的形态**(Markdown + YAML frontmatter 的概念目录)来承载这份生成结果,从而一举两得:
|
||||
|
||||
1. **给编译器 / 包管理**:依赖图、模块身份、导出符号、版本锁定等可查询元数据
|
||||
2. **给本项目文档**:同一份生成物可直接渲染为「项目知识目录」——模块说明、依赖关系、API 索引等**自动生成本项目文档内容**
|
||||
|
||||
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
|
||||
|
||||
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
|
||||
|
||||
---
|
||||
|
||||
## 纠正:它不是什么
|
||||
|
||||
| ❌ 不是 | ✅ 是 |
|
||||
|--------|------|
|
||||
| 人手维护的 `run` / `target` / 路径配置 | 从源码 **推导** 出的依赖与模块元数据 |
|
||||
| 编译器「怎么跑」的 ini/配置替代品 | 解析、链接、文档站共用的 **生成清单** |
|
||||
| 与正文平行的第二套程序描述 | 正文的 **投影**(projection):结构化、可查询、可渲染 |
|
||||
|
||||
执行方式(解释 / 检查 / 编译到某后端)由 **CLI、子命令或工程约定** 决定,不塞进这份 YAML 让人配置。
|
||||
|
||||
---
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
手写 .mq.md 源
|
||||
(叙事 + 类型 + 函数 + 正文中的引用/导入)
|
||||
│
|
||||
▼
|
||||
marqdo 工具链
|
||||
· 解析正文 AST
|
||||
· 收集 import / 链接 / 导出
|
||||
· 解析依赖、锁定版本
|
||||
│
|
||||
├──────────────────────────────┐
|
||||
▼ ▼
|
||||
生成 OKF 风格清单 编译 / 类型检查 / 运行
|
||||
(YAML + 概念 Markdown) (消费清单加速解析)
|
||||
│
|
||||
▼
|
||||
自动生成本项目文档
|
||||
(模块索引、依赖图、API 目录……)
|
||||
```
|
||||
|
||||
- **源 → 清单**:单向派生;清单不得反向成为「唯一写依赖的地方」。
|
||||
- **清单 → 文档**:OKF 包本身即可浏览;也可再生成站点/目录页。
|
||||
- **清单 → 编译**:编译器可读生成结果以跳过重复发现,但语义仍以源为准;清单缺失时应能从源重建。
|
||||
|
||||
---
|
||||
|
||||
## 生成物长什么样(示意)
|
||||
|
||||
工程在构建或 `marqdo sync` 类命令后,可得到类似 OKF bundle 的目录(路径未定):
|
||||
|
||||
```
|
||||
.marqdo/ # 或 docs/catalog/ 等 — 待 ADR
|
||||
index.md # 生成:项目总览
|
||||
modules/
|
||||
cart.md # 生成:每个模块一个概念文档
|
||||
prelude-list.md
|
||||
deps/
|
||||
lock.yaml # 生成:依赖锁定(机器向)
|
||||
```
|
||||
|
||||
单个生成的概念文件可呈 OKF 形:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Module # 生成
|
||||
title: cart
|
||||
description: 购物车:行项目与总额
|
||||
resource: src/cart.mq.md # 指向源文件
|
||||
depends:
|
||||
- prelude/list
|
||||
- math/sum
|
||||
exports: [Line, total]
|
||||
generated:
|
||||
by: "marqdo/0.1"
|
||||
at: 2026-08-04T01:00:00Z
|
||||
---
|
||||
|
||||
# cart
|
||||
|
||||
> 本页由 Marqdo 工具链根据 [`src/cart.mq.md`](../../src/cart.mq.md) **自动生成**,请勿手改。
|
||||
|
||||
## 依赖
|
||||
|
||||
- [prelude/list](../modules/prelude-list.md)
|
||||
- [math/sum](../modules/math-sum.md)
|
||||
|
||||
## 导出
|
||||
|
||||
| 符号 | 种类 |
|
||||
|------|------|
|
||||
| `Line` | type |
|
||||
| `total` | fn |
|
||||
```
|
||||
|
||||
人要改行为或说明 → 改 `src/cart.mq.md`;再生成,文档与依赖清单一起更新。
|
||||
|
||||
---
|
||||
|
||||
## 与「代码即文档」的关系
|
||||
|
||||
Marqdo 有两层「文档」,不要混为一谈:
|
||||
|
||||
| 层 | 谁写 | 是什么 |
|
||||
|----|------|--------|
|
||||
| **源文档** | 人(及协助编写的 Agent) | `.mq.md`:程序本身,打开即读、即可跑 |
|
||||
| **项目目录文档** | 机器 | OKF 风格 YAML/Markdown:从全项目源 **汇总** 的依赖、模块图、索引 |
|
||||
|
||||
前者消灭「实现与说明漂移」;后者消灭「仓库级总览靠手维护 README 目录」——总览从源自动长出,格式还对 Agent / 搜索友好(OKF)。
|
||||
|
||||
---
|
||||
|
||||
## 原则
|
||||
|
||||
1. **源为唯一权威** — 依赖与导出以 `.mq.md` 正文中的语言构造为准;YAML 是提取结果。
|
||||
2. **生成、可复现** — 同一源树 + 同一工具版本 → 同一清单(允许时间戳等字段除外或规范化)。
|
||||
3. **勿手改生成物** — 生成文件应带头注释或 `generated` 字段;CI 可校验「未提交脏生成」或「提交的生成与源一致」。
|
||||
4. **OKF 形、Marqdo 义** — 文件形态对齐 OKF(`type`、链接、目录),词汇服务模块/依赖/导出,而不是照搬 BigQuery 概念类型。
|
||||
5. **清单可删可再生** — 没有清单时,编译器仍须能直接从源工作(可能更慢);清单是缓存与文档面,不是语言语义的一部分。
|
||||
|
||||
---
|
||||
|
||||
## 待决问题(后续 ADR)
|
||||
|
||||
- [ ] 生成物落盘路径(例如 `.marqdo/` vs `docs/catalog/`)及是否提交进 git
|
||||
- [ ] 单文件是否仍写入「生成型 frontmatter」,还是全部集中在工程级 OKF 包
|
||||
- [ ] 与 `Cargo.toml` 式「可手写包身份(name/version)」的边界:是否允许极少量非生成的包清单,与全自动 OKF 目录如何分工
|
||||
- [ ] `marqdo sync` / `marqdo doc` 命令的具体行为
|
||||
- [ ] 是否沿用 OKF v0.2 的 `generated` / `sources` 字段描述溯源
|
||||
|
||||
---
|
||||
|
||||
## 结论
|
||||
|
||||
**YAML(OKF 风格清单)= 机器从 `.mq.md` 自动生成的依赖与项目元数据,并可据此自动生成本项目文档;不是人手填写的配置文件。**
|
||||
人写源,工具写清单与目录文档;编译器与文档站共同消费生成物,语义始终回到源。
|
||||
@@ -0,0 +1,84 @@
|
||||
# Marqdo 关键字与内置名(v0 最小集)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(前期够用) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **英文**;参考 [Python](https://realpython.com/python-keywords/) 但远更少;控制流仍靠 Markdown 标记,不引入 `if`/`while`/`def` |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计原则
|
||||
|
||||
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **英文标识**:内置与字面量用英文,便于工具高亮与国际协作。
|
||||
3. **学 Python 的边界**:Python 3 里 [`print` / `input` 是内置函数,不是关键字](https://realpython.com/python-keywords/);布尔与空值是字面量关键字。Marqdo 同样区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:前期只列执行 examples 所需;要加再进 ADR。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键字(词法保留,不可作变量名)
|
||||
|
||||
| 关键字 | 含义 | 备注 |
|
||||
|--------|------|------|
|
||||
| `True` | 布尔真 | 对齐 Python 大小写 |
|
||||
| `False` | 布尔假 | |
|
||||
| `None` | 空值 | |
|
||||
| `and` | 逻辑与 | 表达式内 |
|
||||
| `or` | 逻辑或 | |
|
||||
| `not` | 逻辑非 | |
|
||||
|
||||
**本期不引入:** `if` `else` `elif` `while` `for` `def` `class` `return` `import` `pass` `break` `continue` `in` `is` `lambda` …
|
||||
(`else` 分支臂仍用臂头单独的 `*` 标记,不是单词 `else`。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 内置函数(可调用名,建议勿遮蔽)
|
||||
|
||||
| 名称 | 作用 | 调用示例 |
|
||||
|------|------|----------|
|
||||
| `print` | 写到 stdout(副作用) | `> print text=Hello` 或 `> print Hello`(位置实参,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `input` | 从 stdin 读一行(返回文本) | `*`name` = > input prompt=Name: *` |
|
||||
|
||||
参数约定(v0):
|
||||
|
||||
- `print`:具名实参 `text`(必填);日后可扩展 `end` 等。
|
||||
- `input`:可选 `prompt`;返回用户输入字符串(不含换行)。
|
||||
|
||||
旧文档中的中文 `print` **废弃**,统一为 `print`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 Markup 调用的关系
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
|
||||
*`n` = 1*
|
||||
|
||||
+ `n` > 0
|
||||
> print text=positive
|
||||
+ *
|
||||
> print text=other
|
||||
```
|
||||
|
||||
- `>` 是**调用标记**(架构)。
|
||||
- `print` 是**被调名字**(内置库)。
|
||||
- 用户自定义 `# print` 会遮蔽内置(实现应警告)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 标识符规则(摘要)
|
||||
|
||||
- 变量:行内 `` `name` ``;`name` 不可为上表关键字。
|
||||
- 函数名:`#` 标题文本;建议 ASCII/英文,中文标题仍允许但内置名保持英文。
|
||||
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and` `or` `not`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 后续可增(未批准)
|
||||
|
||||
`len`、`str`、`int`、`float`、`range`;以及 `break`/`continue`(若循环需要)。增加前开短 ADR。
|
||||
@@ -0,0 +1,211 @@
|
||||
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 取代 | v0 中「`**`=输出、`*`=返回」 |
|
||||
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
|
||||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
|
||||
|
||||
---
|
||||
|
||||
## 1. 哲学
|
||||
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **无标记行 = 叙述注释**(内部任何标记无语义)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 行首判别
|
||||
|
||||
跳过前导空白后:
|
||||
|
||||
| 首字符 | 分类 |
|
||||
|--------|------|
|
||||
| 普通文字 / 空 | **注释** |
|
||||
| 标记字符 | **代码** |
|
||||
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的分割线 `---` / `***`(见 §11)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 映射总表(v0.1)
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `#` … `######` | 函数;层数 = 作用域 |
|
||||
| 函数头下 `-` 纯名 | 形参 |
|
||||
| 体内 `-` | 循环 |
|
||||
| 体内 `+` 或 `1.` | 分支 |
|
||||
| 分支臂头整行恰为 `*` | else |
|
||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
||||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
| 无标记行 | 注释 |
|
||||
| GFM 表格 | 集合 |
|
||||
| ` ```lang ` | 外联异种代码 |
|
||||
| `---` / `***` | **可选**:框住分支/循环块(美化/分组;v0.1 不强制,见 §11) |
|
||||
|
||||
### 输出不是架构
|
||||
|
||||
| 错误(旧) | 正确(v0.1) |
|
||||
|------------|--------------|
|
||||
| `**Hello**` 表示打印 | `> print text=Hello` |
|
||||
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
|
||||
| 输出与返回抢粗体 | 粗体只表示 **返回** |
|
||||
|
||||
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 语句、返回、调用
|
||||
|
||||
### 程序语句(斜体)
|
||||
|
||||
```markdown
|
||||
*`x` = 1*
|
||||
|
||||
*`y` = `x` + 2*
|
||||
```
|
||||
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
|
||||
### 返回值(粗体)
|
||||
|
||||
```markdown
|
||||
# 加一
|
||||
- n
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
### 输出(内置函数 `print`)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
### else 与斜体消歧
|
||||
|
||||
- 分支臂**第一行整行只有一个** `*` → else。
|
||||
- `*中间有内容*` → 程序语句。
|
||||
- `**…**` → 返回(与 else 无关)。
|
||||
|
||||
---
|
||||
|
||||
## 5. Frontmatter 与跨文件
|
||||
|
||||
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
|
||||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 函数、作用域、提升
|
||||
|
||||
规则同 v0。推荐:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
|
||||
## 加问候
|
||||
- 谁
|
||||
|
||||
**你好,`谁`**
|
||||
```
|
||||
|
||||
(需要打印时对返回值再 `> print`,或直接 `> print`。)
|
||||
|
||||
形参 `- 名` → 体内 `` `名` ``。
|
||||
|
||||
---
|
||||
|
||||
## 7. 绑定与比较
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) |
|
||||
| `` `x` == 1 `` | 相等比较 |
|
||||
|
||||
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分支与循环
|
||||
|
||||
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
|
||||
|
||||
```markdown
|
||||
*`x` = 0*
|
||||
|
||||
+ `x` > 0
|
||||
> print text=正数
|
||||
+ `x` < 0
|
||||
> print text=负数
|
||||
+ *
|
||||
> print text=零
|
||||
```
|
||||
|
||||
```markdown
|
||||
- [果](篮子)
|
||||
> print text=今天吃`果`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 集合(表格)
|
||||
|
||||
同 v0。`` `篮子` = `` 后接 GFM 表。
|
||||
|
||||
---
|
||||
|
||||
## 10. 求值入口
|
||||
|
||||
1. 加载 `index.mq.md` + 导入。
|
||||
2. Pass1 收集定义。
|
||||
3. Pass2 执行 `# main`。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
|
||||
|
||||
---
|
||||
|
||||
## 11. 分割线框住分支/循环(可选、非强制)
|
||||
|
||||
允许用 `---` 或 `***` 将分支/循环块视觉框起来,便于阅读:
|
||||
|
||||
```markdown
|
||||
---
|
||||
+ `x` > 0
|
||||
> print text=正
|
||||
+ *
|
||||
> print text=其它
|
||||
---
|
||||
```
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| v0.1 | **不强制**;无框同样合法 |
|
||||
| 语义 | 若使用,框内仍是原列表语义;分割线本身不产生控制流 |
|
||||
| 保留 | 日后若缺「块」类关键语法,可升级分割线为强制块边界 |
|
||||
| 消歧 | 仅文件开头的 `---` 对 = frontmatter;函数体内成对/成段的 `---`/`***` = 可选框 |
|
||||
|
||||
---
|
||||
|
||||
## 12. v0.1 非目标
|
||||
|
||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||||
- 强制分割线框
|
||||
- 用 `*` 作无序列表符
|
||||
|
||||
---
|
||||
|
||||
## 13. 示例索引
|
||||
|
||||
见 [`examples/`](../../examples/)。
|
||||
@@ -0,0 +1,73 @@
|
||||
# 解释器流水线可视调试
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(开发期强制友好) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 参考 | [Crafting Interpreters — Scanning](https://www.craftinginterpreters.com/scanning.html)(先打 token)· [AstPrinter](https://craftinginterpreters.com/representing-code.html) · CLI `--dump-ast` 类实践 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
开发 `marqdo` 时,对任意 `.mq.md` 应能**分阶段看见**中间结果,避免黑盒;正式 `run` 默认安静,仅输出程序 `print` 的内容。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI 开关
|
||||
|
||||
```bash
|
||||
marqdo run FILE [dumps...]
|
||||
marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||||
```
|
||||
|
||||
| 标志 | 阶段 | 输出内容 |
|
||||
|------|------|----------|
|
||||
| `--dump-lines` | 行分类 | 每行:`LINE kind=Comment\|Code\|Blank` + 原文预览 |
|
||||
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
|
||||
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
|
||||
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
|
||||
| `--trace-eval` | 求值 | 进入/离开函数、绑定、分支臂选择、`print` 调用 |
|
||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(见 [bytecode.md](bytecode.md)) |
|
||||
| `--backend tree\|bytecode` | 执行后端 | 默认 `tree`;`bytecode` 走栈式 VM |
|
||||
| `--dump-all` | 以上全部 | 按管道顺序打印,段之间用横幅分隔 |
|
||||
|
||||
格式约定:
|
||||
|
||||
- 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
||||
- 可选 `--dump-format=text|json`(json 后置,text 先做)
|
||||
- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
|
||||
|
||||
---
|
||||
|
||||
## 3. 横幅示例
|
||||
|
||||
```
|
||||
=== marqdo: lines (examples/hello.mq.md) ===
|
||||
1 Blank
|
||||
2 Comment | # Hello World
|
||||
3 Blank
|
||||
4 Comment | 本程序调用...
|
||||
5 Blank
|
||||
6 Code | > print text=Hello World!
|
||||
=== marqdo: end lines ===
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 实现要点
|
||||
|
||||
- dump 逻辑放在 `src/debug/`(或各阶段 `fmt`),**不**与安静求值路径搅在一起。
|
||||
- 每个阶段纯函数:`input → (artifacts, diagnostics)`,CLI 负责打印。
|
||||
- 单测可断言 dump 字符串包含关键行(稳定子集),避免绑死全文格式。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与里程碑
|
||||
|
||||
| 里程碑 | 必须可用的 dump |
|
||||
|--------|-----------------|
|
||||
| M1 | `--dump-lines`(及可选 tokens 雏形) |
|
||||
| M2 | `--dump-ast` |
|
||||
| M3–M4 | `--dump-sema`、`--trace-eval` |
|
||||
| 全程 | `--dump-all` 随阶段增长自动变完整 |
|
||||
@@ -0,0 +1,18 @@
|
||||
# 记录:返回 / 语句 / 输出 / 分割线(决议)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已决议(并入 mapping v0.1 + keywords) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
|
||||
## 决议
|
||||
|
||||
1. **`*…*` = 程序语句**。
|
||||
2. **`**…**` = 返回值**(架构级)。
|
||||
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
|
||||
4. **`---` / `***`**:可选框住分支/循环,不强制。
|
||||
5. **否决**:无标记行 = 默认代码。
|
||||
|
||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)。
|
||||
@@ -0,0 +1,152 @@
|
||||
# 参考实现:技术选型分析(尚未拍板)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **分析中 — 未定案** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 说明 | 对比候选与约束;**不在本文直接开写实现仓库脚手架** |
|
||||
|
||||
上一版曾草率写「就用 TypeScript」——信息不足,已作废为定论。本文只做选型框架与对比,**最终实现语言须单开 ADR 确认后再动工。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 我们在选什么
|
||||
|
||||
参考实现至少包含:
|
||||
|
||||
1. **读入** `.mq.md`(含 frontmatter 混合行)
|
||||
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
|
||||
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
|
||||
4. **两遍**:收集定义 + 导入 → 求值
|
||||
5. **CLI** + **金样例测试**(`examples/`)
|
||||
|
||||
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
|
||||
|
||||
---
|
||||
|
||||
## 2. 选型准则(按权重)
|
||||
|
||||
| 权重 | 准则 | 说明 |
|
||||
|------|------|------|
|
||||
| 高 | GFM 忠实度 | 表格、列表符、强调边界与 GitHub 预览一致,减少「能渲染不能跑 / 能跑不能渲染」 |
|
||||
| 高 | 与宪法同构 | 易于表达「先 mdast/事件流,再 Marqdo AST」 |
|
||||
| 高 | 测试与迭代速度 | 改语法宪法时能快速改测试 |
|
||||
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
|
||||
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
|
||||
| 低 | 极致性能 | v0 样例很小 |
|
||||
| 低 | 浏览器内运行 | 可后置 |
|
||||
|
||||
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
|
||||
|
||||
---
|
||||
|
||||
## 3. 架构共性(与语言无关)
|
||||
|
||||
无论选哪门实现语言,流水线应一致:
|
||||
|
||||
```
|
||||
.mq.md 文本
|
||||
→ 前端:GFM 友好解析(或事件扫描)
|
||||
→ Middle:Marqdo lower(行类、标题树、- / +、表、围栏)
|
||||
→ Marqdo AST
|
||||
→ 语义:导入图、提升、作用域
|
||||
→ 后端:解释器(v0)/日后编译
|
||||
→ 测试:examples → 期望 stdout
|
||||
```
|
||||
|
||||
**前端可复用成熟 GFM 库,也可自研**;Middle/后端必须自研(这是语言本体)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 候选对比
|
||||
|
||||
### A. TypeScript / Node + remark(mdast)
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| remark-gfm 与预览器语义接近;mdast 节点齐全 | 运行时依赖 Node;发行 CLI 需打包 |
|
||||
| 迭代快、Vitest 方便 | 性能与「系统级编译器」形象偏软 |
|
||||
| 与 Markdown 工具链同生态 | 需纪律:避免把业务写进插件泥潭 |
|
||||
|
||||
**适合:** 验证宪法、快速金样例。
|
||||
**不自动等于最终生产编译器。**
|
||||
|
||||
### B. Rust + pulldown-cmark / comrak
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 单静态二进制、性能好、适合日后正式编译器 | GFM 表格/细节与 GitHub 仍可能有差异,要对齐测试 |
|
||||
| 类型与代数数据类型适合 AST | 前期迭代比 TS 慢 |
|
||||
| 无 GC、可嵌入 | MD 生态碎片,选库要论证 |
|
||||
|
||||
**适合:** 中长期「真编译器」或与 TS 原型双轨。
|
||||
**风险:** 首版就上 Rust 可能拖慢语法验证。
|
||||
|
||||
### C. Python + markdown-it-py / mistune
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 原型极快 | 类型与工程化偏弱;双实现时易弃 |
|
||||
| 文本处理友好 | 打包 CLI 体验一般 |
|
||||
|
||||
**适合:** 一次性语法实验。
|
||||
**不推荐**作为唯一长期实现,除非团队强约束。
|
||||
|
||||
### D. Go + goldmark
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 单二进制、部署简单 | 泛型/AST 表达力一般;MD 库选 goldmark 需 GFM 扩展评估 |
|
||||
| 并发与工具链成熟 | 与 MD 研究生态联系弱于 JS |
|
||||
|
||||
**适合:** 工具型 CLI 优先的团队。
|
||||
|
||||
### E. 自研扫描器(任意语言)+ 仅用 GFM 做对照测试
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 完全控制行首判别与 `+`/`-` 语义 | 重复实现表格/强调,易与渲染不一致 |
|
||||
| 可强制「行分类优先于块解析」 | 工作量大 |
|
||||
|
||||
**适合:** 证明「行首判别」与 CommonMark 块结构冲突时的研究分支。
|
||||
可与 A/B 组合:自研 lower,块结构仍喂给现成解析器。
|
||||
|
||||
---
|
||||
|
||||
## 5. 关键技术风险(与选语言正交)
|
||||
|
||||
1. **行首判别 vs 块解析器** — CommonMark 先成块再看内容;Marqdo 先看行类。可能需「行预分类再喂解析器」或「解析后按源位置重分类」。选型时要让候选语言/库能拿到**源行映射**。
|
||||
2. **frontmatter 非纯 YAML** — `>` 导入行是扩展;不能整块丢给严格 YAML 解析器。
|
||||
3. **`+` 与 `-` 列表** — 多数解析器都认,但 lower 必须保留**项目符字符**,不能只得「unordered list」。选库时验证 AST 是否保留 bullet type。
|
||||
4. **`*` else vs `*返回*` vs 强调** — 依赖 inline 解析与「整行恰好一个 `*`」的行级规则并存。
|
||||
|
||||
以上 4 点应作为**选型验收用例**,写进 ADR:用最小样例在候选栈上 Spike,再定案。
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议的决策流程(尚未执行)
|
||||
|
||||
1. **Spike(各 ≤0.5–1 日)**
|
||||
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
|
||||
- 候选 B:Rust + comrak/pulldown — 同上。
|
||||
- (可选)C 或 D 若团队有偏好再做。
|
||||
2. **对照验收用例**(固定):`examples/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
|
||||
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
|
||||
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
|
||||
|
||||
---
|
||||
|
||||
## 7. 当前态度(非正式投票)
|
||||
|
||||
| 阶段 | 倾向(待 Spike 验证) |
|
||||
|------|------------------------|
|
||||
| 语法验证期 | 更可能是 **TypeScript + remark**(快、GFM 近) |
|
||||
| 长期生产编译器 | **开放** Rust / Go,不与验证期绑定 |
|
||||
|
||||
**本文不授权开始实现。** 确认 Spike 计划或直接指定语言后,再写 `adr/0001-implementation-language.md`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 与「无标记 = 注释」的关系
|
||||
|
||||
实现必须先做**行分类**(见 [code-vs-comment.md](code-vs-comment.md)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。
|
||||
@@ -0,0 +1,119 @@
|
||||
# `marqdo view` — 源结构浏览器
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(实现中) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [pipeline-debug.md](pipeline-debug.md) · AST(`src/ast.rs`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 既是文档也是程序。需要一种**可读渲染**,而不仅是纯文本或 `run` 的 stdout:
|
||||
|
||||
- 按语法树展示函数、分支、循环、调用、返回;
|
||||
- 同页展示**执行结果**;
|
||||
- 支持打开**单个文件**或**文件夹**(扫描全部 `.mq.md` + 结构索引)。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | `.mq.md` 文件,或目录(递归扫描 `*.mq.md`) |
|
||||
| `--port` | `7429` | HTTP 端口 |
|
||||
| `--host` | `127.0.0.1` | 仅本地 |
|
||||
| `--no-open` | 关 | 不尝试打开系统浏览器 |
|
||||
|
||||
示例:
|
||||
|
||||
```bash
|
||||
marqdo view examples/structure/hello.mq.md
|
||||
marqdo view examples
|
||||
marqdo view examples/keywords --port 8080
|
||||
```
|
||||
|
||||
启动后打印 `http://127.0.0.1:7429/`,阻塞直至 Ctrl+C。
|
||||
|
||||
---
|
||||
|
||||
## 3. 信息架构
|
||||
|
||||
### 3.1 目录模式
|
||||
|
||||
```
|
||||
┌─────────────┬──────────────────────────────────┐
|
||||
│ 索引 │ 选中文件 / 欢迎页 │
|
||||
│ structure/ │ │
|
||||
│ hello │ [源码结构] [执行结果] [原始文本] │
|
||||
│ branch │ │
|
||||
│ keywords/ │ │
|
||||
└─────────────┴──────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 侧栏:相对 `PATH` 的目录树;只列出 `.mq.md`。
|
||||
- 点击文件:主区切换为该文件的三栏/三节视图。
|
||||
|
||||
### 3.2 单文件模式
|
||||
|
||||
无侧栏列表(或仅当前文件);主区同「选中文件」视图。仍提供「执行」结果。
|
||||
|
||||
---
|
||||
|
||||
## 4. 主区三节
|
||||
|
||||
### 4.1 源码结构(AST 渲染)
|
||||
|
||||
不依赖浏览器 Markdown 猜测语义,而用服务端已解析的 AST:
|
||||
|
||||
| AST 节点 | 视觉 |
|
||||
|----------|------|
|
||||
| `Function` | 卡片:标题层级、形参芯片、子函数嵌套;**中间的注释行仍展示**(来自源行分类,不在 AST 内) |
|
||||
| `Stmt::*` | 绑定 / 返回 / 调用 / 分支 / 循环;表达式用**表面语法**(如 `` `x` > 0 ``),不用 Debug |
|
||||
|
||||
样式:清晰分区,避免「通用仪表盘」堆砌;结构层级一眼可读。
|
||||
|
||||
### 4.2 执行结果
|
||||
|
||||
服务端对该文件跑与 `marqdo run` 相同的管线,**捕获 stdout/stderr** 与退出状态,展示在「输出」区。
|
||||
含 `input` 的程序:view 中标注「需交互,未在 view 执行」或提供只读说明(v0:跳过/失败信息)。
|
||||
|
||||
### 4.3 原始文本
|
||||
|
||||
等宽展示源文件;可选行分类着色(Code / Comment / Blank),与 `--dump-lines` 一致。
|
||||
|
||||
---
|
||||
|
||||
## 5. HTTP API(实现细节)
|
||||
|
||||
| 方法 | 路径 | 含义 |
|
||||
|------|------|------|
|
||||
| `GET` | `/` | 索引 HTML |
|
||||
| `GET` | `/file?path=…` | 单文件页(path 相对根,防 `..` 逃逸) |
|
||||
| `GET` | `/api/tree` | JSON 文件树 |
|
||||
| `GET` | `/api/file?path=…` | JSON:`{ source, ast_html 或 ast_json, stdout, stderr, ok }` |
|
||||
|
||||
v0 可全部服务端渲染 HTML,API 可选。
|
||||
|
||||
安全:根目录锁死为 CLI 给定的 `PATH`(若为文件则其父目录为根、仅一文件);拒绝根外路径。
|
||||
|
||||
---
|
||||
|
||||
## 6. 依赖
|
||||
|
||||
本地同步 HTTP 即可(如 `tiny_http`),无强制前端构建;HTML/CSS/少量 JS 内嵌于 Rust。
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. `marqdo view examples/structure/hello.mq.md` 显示结构 + `Hello World!` 输出。
|
||||
2. `marqdo view examples` 侧栏含 `structure/` 与 `keywords/` 分组。
|
||||
3. 分支/循环样例在结构区可区分臂与循环体。
|
||||
4. 路径逃逸被拒绝。
|
||||
@@ -0,0 +1,86 @@
|
||||
# 开发环境配置(Rust 参考解释器)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | M0 |
|
||||
| 相关 | [dependencies.md](design/dependencies.md) · [interpreter.md](roadmap/interpreter.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 必备软件
|
||||
|
||||
| 软件 | 要求 | 检查 |
|
||||
|------|------|------|
|
||||
| Rust + Cargo | stable,建议 ≥ 1.81(本机验证过 1.81) | `rustc --version` / `cargo --version` |
|
||||
| Git | 任意近期版本 | `git --version` |
|
||||
|
||||
安装 Rust(若尚未安装):
|
||||
|
||||
- 官方:[https://rustup.rs/](https://rustup.rs/)
|
||||
- Windows:下载 `rustup-init.exe`,按提示安装后**重新打开终端**
|
||||
|
||||
本仓库可选 `rust-toolchain.toml`(钉 1.81.0)。若本机无 `rustup`、但已有匹配的 `rustc`/`cargo`,也可直接开发。
|
||||
|
||||
**不需要:** Flex、Bison、LLVM、Node/npm(实现栈为 Rust)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取代码与构建
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cflmy/marqdo.git
|
||||
cd marqdo
|
||||
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run examples/structure/hello.mq.md
|
||||
```
|
||||
|
||||
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
|
||||
|
||||
> 若 `cargo build` 报 `edition2024` / 过新 crate:仓库已对 `clap` 等做兼容钉扎(见 `Cargo.toml`);请使用附带的 `Cargo.lock`,勿盲目 `cargo update` 到最新 major。
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐组件
|
||||
|
||||
```bash
|
||||
rustup component add rustfmt clippy # 若使用 rustup
|
||||
cargo fmt
|
||||
cargo clippy --all-targets
|
||||
```
|
||||
|
||||
代理下拉 crate(可选,与 git 推送类似):
|
||||
|
||||
```bash
|
||||
# Windows PowerShell 示例
|
||||
$env:HTTPS_PROXY="http://127.0.0.1:7897"
|
||||
$env:HTTP_PROXY="http://127.0.0.1:7897"
|
||||
cargo build
|
||||
```
|
||||
|
||||
或配置 `%USERPROFILE%\.cargo\config.toml`:
|
||||
|
||||
```toml
|
||||
[http]
|
||||
proxy = "http://127.0.0.1:7897"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录约定
|
||||
|
||||
| 路径 | 含义 |
|
||||
|------|------|
|
||||
| `src/lex` | 行分类 / 词法(自研) |
|
||||
| `src/parse` | 递归下降语法 |
|
||||
| `src/diagnostics` | 诊断 |
|
||||
| `examples/` | 金样例(宪法) |
|
||||
| `spike/` | 旧 Python 风险探测,非运行时依赖 |
|
||||
| `doc/` | 设计与路线图 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 下一里程碑
|
||||
|
||||
见 [interpreter.md](roadmap/interpreter.md):M1 词法·行分类与最小 AST。
|
||||
@@ -0,0 +1,215 @@
|
||||
# 调研:Google Open Knowledge Format(OKF)与 Marqdo
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 调研笔记 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 对象 | [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
|
||||
| 公告 | [v0.1 介绍](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) · [v0.2 trust signals](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals) |
|
||||
|
||||
---
|
||||
|
||||
## 1. OKF 是什么
|
||||
|
||||
**Open Knowledge Format(开放知识格式)** 是 Google Cloud 于 2026 年 6 月发布的厂商中立开放规范(Apache 2.0)。它把「LLM Wiki」模式形式化为可移植格式:用**目录树中的 Markdown 文件 + YAML frontmatter** 表示组织知识(表结构、指标、API、操作手册等),供人类与 AI Agent 共同阅读、交换与维护。
|
||||
|
||||
一句话定位:
|
||||
|
||||
> 知识应活在**格式**里,而不是专有服务或散落的非结构化文本里。
|
||||
|
||||
### 核心形态
|
||||
|
||||
```
|
||||
bundle/
|
||||
index.md # 可选:目录索引(渐进披露)
|
||||
log.md # 可选:变更历史
|
||||
concepts/.../*.md # 每个概念一个 Markdown 文件
|
||||
```
|
||||
|
||||
每个概念文件:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Metric # 唯一必填
|
||||
title: Monthly Active Users
|
||||
description: ...
|
||||
tags: [product, growth]
|
||||
sources: [...] # v0.2:出处
|
||||
generated: {...} # v0.2:谁生成的
|
||||
verified: {...} # v0.2:谁验证的
|
||||
status: stable # v0.2:生命周期
|
||||
stale_after: 2026-12-01 # v0.2:过期日
|
||||
---
|
||||
|
||||
# 正文(自由 Markdown)
|
||||
|
||||
指标定义为……
|
||||
```
|
||||
|
||||
- **Concept ID** = 相对路径去掉 `.md`
|
||||
- **链接** = 普通 Markdown 链接,形成可遍历关系图
|
||||
- **无中心 schema registry**;未知 `type` 必须被优雅降级处理
|
||||
|
||||
### 设计三原则(官方表述)
|
||||
|
||||
1. **Minimally opinionated** — 只强制互通所需的最小公约;其余留给生产者。
|
||||
2. **Producer / consumer independence** — 写知识的人(或 Agent)与读知识的 Agent/工具解耦;格式即契约。
|
||||
3. **Format, not platform** — 不绑定云、数据库、模型或 Agent 框架;`cat` 能读,`git clone` 能分发。
|
||||
|
||||
### v0.2 新增:五类信任信号
|
||||
|
||||
当知识主要由 Agent **持续生成**时,纯 Markdown 不够。v0.2 把下列问题变成 frontmatter 一等字段:
|
||||
|
||||
| 问题 | 机制 |
|
||||
|------|------|
|
||||
| 从何而来? | `sources`(出处 + 可信度信号,不作统一打分) |
|
||||
| 该信多少? | `generated` / `verified` → 推导 trust tier(未验证 / 机器确认 / 人工审核) |
|
||||
| 是否仍真? | `stale_after`(绝对日期,非相对 TTL) |
|
||||
| 是否现行? | `status`: `draft` → `stable` → `deprecated` |
|
||||
| 数字是否按约定算出? | 概念类型 `Attested Computation`:executor 跑计算出 receipt,**非 LLM** 的 attester 核验 |
|
||||
|
||||
---
|
||||
|
||||
## 2. OKF 与 Marqdo:相邻,但不等同
|
||||
|
||||
| 维度 | OKF | Marqdo |
|
||||
|------|-----|--------|
|
||||
| 本质 | **知识交换格式** | **编程语言** |
|
||||
| 文件角色 | 描述资产与概念的文档 | 可执行程序 = 可渲染文档 |
|
||||
| 机器侧 | 解析 metadata、遍历链接、过滤信任 | 解析、类型检查、求值/编译 |
|
||||
| Markdown 地位 | 载体与呈现层 | **语法表层的一部分**(源即 Markdown) |
|
||||
| 成功标准 | 跨组织互通、Agent 可策展 | 严肃编程能力 + 阅读体验同时成立 |
|
||||
|
||||
OKF 回答:「人和 Agent 如何**共享与信任知识**?」
|
||||
Marqdo 回答:「程序如何**本身就是知识**,且仍能运行?」
|
||||
|
||||
因此借鉴应落在**表示哲学与工程约束**,而不是照搬「知识目录」产品形态。
|
||||
|
||||
---
|
||||
|
||||
## 3. 值得借鉴的设计点
|
||||
|
||||
### 3.1 后缀与生态搭便车 — 已采纳
|
||||
|
||||
OKF 坚持「就是 Markdown」:GitHub 渲染、编辑器预览、静态站、搜索索引零摩擦。
|
||||
|
||||
**Marqdo 对应决策:源文件后缀为 `.mq.md`。**
|
||||
|
||||
- `.md` 确保通用 Markdown 渲染器开箱可用
|
||||
- `.mq` 前缀声明这是 Marqdo 源,而非普通文档
|
||||
- 与 OKF「格式优先于平台」一致:可读性不依赖自研 viewer
|
||||
|
||||
### 3.2 最小强制面(Minimally opinionated)
|
||||
|
||||
OKF 只强制 `type`;其余可选,未知字段保留不拒绝。
|
||||
|
||||
**对 Marqdo 的启发:**
|
||||
|
||||
- 语言的「文档面」与「程序面」之间,划清**硬语法**与**散文**
|
||||
- 第一版语法宜小:标题层级、声明、表达式……先钉死互通/可执行最小集
|
||||
- 扩展用约定或可选 frontmatter,避免一上来造完整注解宇宙
|
||||
|
||||
### 3.3 生成式 YAML / OKF 清单 — 已采纳方向(已修正)
|
||||
|
||||
OKF 用 YAML frontmatter 承载「可查询元数据」。Marqdo **借鉴其形态**,但职责不同:
|
||||
|
||||
**YAML(OKF 风格知识包)由工具从 `.mq.md` 自动生成,不是人手写的配置文件。**
|
||||
|
||||
详见 [`design/generated-yaml-manifest.md`](../design/generated-yaml-manifest.md)。
|
||||
|
||||
| | |
|
||||
|--|--|
|
||||
| 类比 | 其它语言中由工具维护的依赖描述(如 `Cargo.toml` / `requirements.txt` 所承担的那类角色) |
|
||||
| 形态 | OKF:概念目录 + YAML frontmatter + Markdown 正文 |
|
||||
| 用途 | ① 编译器/包管理消费依赖图与导出 ② **自动生成本项目文档**(模块索引、依赖关系等) |
|
||||
| 权威 | 始终是手写 `.mq.md`;清单可删、可重建 |
|
||||
|
||||
```
|
||||
.mq.md 源(人写)
|
||||
→ marqdo 工具链
|
||||
→ 生成 OKF 风格清单(YAML + 概念页)
|
||||
→ 供编译解析,并渲染为项目目录文档
|
||||
```
|
||||
|
||||
执行方式等运行参数不放进该 YAML 当配置;由 CLI / 子命令决定。
|
||||
程序本体(类型、函数)只活在源正文里。
|
||||
|
||||
### 3.4 路径即身份,链接即关系
|
||||
|
||||
Concept ID = 路径;关系 = Markdown 链接;目录 = 渐进披露(`index.md`)。
|
||||
|
||||
**对模块系统的启发:**
|
||||
|
||||
- 文件路径可成为模块身份的一部分(类比 OKF concept ID)
|
||||
- `import` / 交叉引用尽量与 Markdown 链接同构,使「读文档跳转」与「解析依赖」共用一种边
|
||||
- 大型程序按「书的章节」组织目录,而不是扁平包名墙
|
||||
|
||||
### 3.5 生产者 / 消费者分离
|
||||
|
||||
同一 bundle:人手写、Agent 生成、管道导出,均可被另一 Agent 或 UI 消费。
|
||||
|
||||
**对 Marqdo 工具链:**
|
||||
|
||||
- 解析器、渲染器、求值器、LSP 都是**消费者**;源格式是唯一契约
|
||||
- 允许 Agent 协助编写 `.mq.md`,但语言必须对「纯手写」同样友好
|
||||
- 不把语义锁进某一 IDE 或云服务
|
||||
|
||||
### 3.6 信任与 attestation(中长期)
|
||||
|
||||
OKF v0.2 的 Attested Computation:批准的算法 + 确定性核验,防止 Agent「随口报数」。
|
||||
|
||||
**远期可借鉴(非 v0 范围):**
|
||||
|
||||
- 文档中嵌入的「可运行示例」是否经过核验执行?
|
||||
- 渲染出的结果是否带来源与 receipt?
|
||||
- Agent 生成的 Marqdo 模块如何标注 `generated` / `verified`?
|
||||
|
||||
这强化「文档中的数字/行为与真实执行一致」——与 Marqdo「同一份真相」高度同向。
|
||||
|
||||
### 3.7 规范本身的克制
|
||||
|
||||
OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、不加强制规则**。
|
||||
|
||||
**对 Marqdo 文档文化:**
|
||||
|
||||
- ADR 记录否决项
|
||||
- 语法草案保持短小、可验证的 conformance 描述
|
||||
- 版本演进优先加法兼容,避免随意破坏「已是有效程序」的源文件
|
||||
|
||||
---
|
||||
|
||||
## 4. 不应照搬之处
|
||||
|
||||
1. **OKF 不是语言** — 其 body 是自由散文;Marqdo body 必须有严格可执行语义。不能停在「Markdown 知识库」。
|
||||
2. **无中心 type 注册** 适合知识目录;编程语言的类型系统需要更强的一致性与检查规则。
|
||||
3. **`Attested Computation` 的 executor/attester** 面向数据平台查询核验;Marqdo 若引入类似机制,应长在「测试 / 示例求值 / 再现构建」上,而不是 BigQuery 收据模型。
|
||||
4. **保留文件名**(`index.md` / `log.md`)可参考,但是否占用需在模块设计里单独 ADR,避免与源文件约定冲突。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议纳入 Marqdo 设计议程的议题
|
||||
|
||||
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
|
||||
|
||||
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
|
||||
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.md))。
|
||||
3. **正文中的依赖声明语法** — import / 链接如何写出,供工具提取进生成清单。
|
||||
4. **Agent 友好但不 Agent 绑定** — 源格式对 LLM 可写,语义对确定性工具可检。
|
||||
5. **可渲染结果的 attestation(后期)** — 文档内求值结果的可验证性。
|
||||
|
||||
---
|
||||
|
||||
## 6. 参考链接
|
||||
|
||||
- 规范:[okf/SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(v0.2)
|
||||
- 仓库:[GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
|
||||
- 博客:[Introducing OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
|
||||
- 博客:[OKF v0.2 trust signals](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals)
|
||||
|
||||
---
|
||||
|
||||
## 7. 结论
|
||||
|
||||
OKF 证明了一条与 Marqdo 同向的产业判断:**人类可读的 Markdown 可以成为机器与 Agent 的一等交换面**,前提是约定足够小、足够稳,并把信任做成可查询字段而非口头保证。
|
||||
|
||||
Marqdo 比 OKF 多走一步:Markdown 不仅是知识的容器,更是**程序的表面语法**。我们借鉴 OKF 的形态,用作**从源自动生成的依赖清单与项目目录文档**(而非人手配置);同时借鉴「格式而非平台」、路径/链接身份、以及(远期)provenance。语言设计必须单独完成——**可渲染不等于可执行,可执行才是 Marqdo 的终点。**
|
||||
@@ -0,0 +1,178 @@
|
||||
# Marqdo 参考实现:正经解释器路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已采纳方向 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 目标 | `marqdo run path/to/index.mq.md` 得到真实执行结果;非演示玩具 |
|
||||
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) · [ADR 0001](../adr/0001-implementation-language.md) · [USTC 编译课 2025](https://ustc-compiler-2025.github.io/homepage/) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何是解释器,而不是 USTC 式「编译到机器码」
|
||||
|
||||
[USTC《编译原理与技术》2025](https://ustc-compiler-2025.github.io/homepage/) 的实验链是经典**编译器**路径:
|
||||
|
||||
```
|
||||
源码 → 词法(Flex) → 语法(Bison) → AST
|
||||
→ 语义 / Light IR → 优化 → 后端(龙芯汇编等)
|
||||
```
|
||||
|
||||
这条路适合 Cminusf 一类「最终变成机器指令」的语言。Marqdo 的产品形态是:
|
||||
|
||||
- 源即 Markdown 文档,**打开即读、运行即算**;
|
||||
- 首要交付是 **从 `index.mq.md` 得到求值结果**(stdout、返回值、模块图),不是龙芯/ x86 二进制;
|
||||
- 语法表面是 Markup-as-Syntax,前端与传统正则+Bison 不同,但**中后端的编译学知识仍然全部用得上**。
|
||||
|
||||
因此:
|
||||
|
||||
| USTC / 龙书阶段 | Marqdo 解释器中的对应 |
|
||||
|-----------------|------------------------|
|
||||
| 词法分析 | **行分类 + 标记词法**(无标记=注释;`#`/`*`/`**`/`>`/`+`/`-`/表…) |
|
||||
| 语法分析 | **结构解析 → Marqdo AST**(可递归下降;不必上 Bison,除非日后自研纯文本方言) |
|
||||
| 语义分析 | 作用域、提升、导入、形参绑定、类型(可后置) |
|
||||
| 中间代码 | **可选**:先树遍历;第二期再降到**字节码** |
|
||||
| 优化 / 目标代码 | **非 v1 目标**;日后若要可另开「编译后端」ADR |
|
||||
|
||||
**结论:做正经解释器 = 把编译前端做扎实 + 把运行时做完整;不是跳过词法语法,也不是一上来 LLVM。**
|
||||
|
||||
权威地图见 [Crafting Interpreters — A Map of the Territory](https://craftinginterpreters.com/a-map-of-the-territory.html):用户眼里的「解释器」内部往往仍含编译到字节码(如 CPython);树遍历是第一期,字节码 VM 是第二期。
|
||||
|
||||
---
|
||||
|
||||
## 2. 推荐总体架构
|
||||
|
||||
```
|
||||
index.mq.md (+ 导入的 .mq.md)
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 0. 源加载 / 模块图 │ frontmatter `> a.mq.md` → 依赖图
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 1. 词法·行分类 │ 注释行丢弃语义;代码行 → Token 流
|
||||
│ (+ MD 块辅助) │ pulldown-cmark/comrak;+/- 靠行扫描
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 2. 语法分析 │ Token/块 → Marqdo AST
|
||||
│ (递归下降) │ Module / Fun / Stmt / Expr / Branch / Loop …
|
||||
│ │ **不用 Flex/Bison**(见 dependencies.md)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并
|
||||
│ │ 作用域链、形参、未定义名诊断
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 4a. 树遍历解释器 │ ← Phase I(必须先完成,跑通全部 examples)
|
||||
│ 或 │
|
||||
│ 4b. 字节码编译+VM │ ← Phase II(性能与「更像真语言实现」)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
stdout / 返回值 / 退出码
|
||||
```
|
||||
|
||||
Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对齐 **clox(字节码 VM)**(见 [Chunks of Bytecode](https://craftinginterpreters.com/chunks-of-bytecode.html))。这是 Python/Ruby/Lua 主实现走过的正经路径,不是玩具捷径。
|
||||
|
||||
---
|
||||
|
||||
## 3. 各阶段「做满」的标准(反玩具清单)
|
||||
|
||||
### Phase 0 — 工程骨架(正式包,不是 `spike/`)
|
||||
|
||||
- 包名:`marqdo`(`src/marqdo/` 或 `marqdo/`)
|
||||
- CLI:`marqdo run <file.mq.md>`,默认找目录下 `index.mq.md`
|
||||
- 诊断:带文件名、行号、列号
|
||||
- 测试:每个 `examples/*.mq.md` 有期望 stdout(金样例);CI 可跑
|
||||
|
||||
### Phase I — 可运行的语言核心(树遍历)
|
||||
|
||||
必须全部为真实现,禁止「正则特判 hello」:
|
||||
|
||||
1. **词法 / 行分类**:注释与代码严格分离。
|
||||
2. **语法 → AST**:函数、形参、`*` 语句、`**` 返回、`>` 调用、`+` 分支、`-` 循环、表格集合、绑定与 `==`。
|
||||
3. **语义**:提升、嵌套作用域、`##` 私有、frontmatter 导入公有顶层。
|
||||
4. **运行时**:环境、调用栈、值(文/数/表/记录)、内置 `print`。
|
||||
5. **验收**:`examples/structure/*` 与 `examples/keywords/*` 全部 `marqdo run` 通过。
|
||||
|
||||
### Phase II — 字节码 VM(正经化)
|
||||
|
||||
- AST → 线性字节码(栈式 VM 即可,与 clox / [GoAWK 经验](https://benhoyt.com/writings/goawk-compiler-vm/) 同类)
|
||||
- 控制流用跳转指令实现分支/循环
|
||||
- 同一套金样例必须 bit-同结果(回归)
|
||||
- 性能与可调试性(反汇编、栈跟踪)优于 Phase I
|
||||
|
||||
### Phase III — 语言完备(按需)
|
||||
|
||||
- 更完整表达式文法、错误模型、外联围栏 FFI
|
||||
- 生成 OKF 依赖目录
|
||||
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 USTC Lab 的知识复用(学什么、不搬什么)
|
||||
|
||||
| 课程内容(摘要) | Marqdo 用法 |
|
||||
|------------------|-------------|
|
||||
| Lab1 词法/语法/AST | **直接对标** Phase I 前端;工具可自研递归下降,不必 Flex/Bison |
|
||||
| Lab2 IR / 访问者 | Phase II 字节码 ≈ 轻量 IR;访问者可用于 AST→字节码 |
|
||||
| Lab3 后端汇编 | **v1 不做**;解释器 VM 代替机器后端 |
|
||||
| Lab4 优化 | Phase II 之后可选;解释器也可做常量折叠等 |
|
||||
|
||||
教材仍可读:龙书、陈意云《编译原理》、课主页参考书;解释器专项读 **Crafting Interpreters**(免费:[craftinginterpreters.com](https://craftinginterpreters.com/))。
|
||||
|
||||
---
|
||||
|
||||
## 5. 实现语言(本路线图默认)
|
||||
|
||||
**参考解释器:Rust**([ADR 0001](../adr/0001-implementation-language.md))。
|
||||
|
||||
- 词法/语法:**自研 + GFM crate**,不用 Flex/Bison([dependencies.md](../design/dependencies.md))。
|
||||
- Python `spike/` 仅作风险探测与算法草稿。
|
||||
- Phase I 树遍历、Phase II 字节码 VM 均在 Rust 中实现。
|
||||
|
||||
---
|
||||
|
||||
## 6. 目录规划(正式代码,非 spike)
|
||||
|
||||
```
|
||||
Cargo.toml
|
||||
crates/marqdo/ # 或根包
|
||||
src/lex/ parse/ ast/ sema/ interp/ bytecode/ runtime/
|
||||
tests/
|
||||
examples/
|
||||
spike/ # Python 存档,非运行时依赖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 近期里程碑(可执行顺序)
|
||||
|
||||
| 周序 | 交付 | 完成定义 |
|
||||
|------|------|----------|
|
||||
| M0 | 正式包 + CLI 空壳 + 金样例框架 | `marqdo run` 可调用;测试发现「未实现」 | ✅ |
|
||||
| M1 | 词法·行分类 + 最小 AST | 单测覆盖注释/代码行 | ✅ |
|
||||
| M2 | 解析:函数、输出调用、返回 | `hello` + `index` 金样例绿 | ✅ |
|
||||
| M3 | 分支、循环、表格、绑定 | `branch`/`loop`/`collection` 绿 | ✅ |
|
||||
| M4 | 导入与提升 | `with-import` 绿;**宣称 Phase I 达标** | ✅ |
|
||||
| M5 | 字节码设计文档 + 原型 opcode | 核心金样例双后端一致;覆盖表见 [bytecode.md](../design/bytecode.md) | ✅ 原型 |
|
||||
|
||||
**Phase I 完成前,不宣称「语言已实现」。**
|
||||
**仅 hello 特判通过,不算完成。**
|
||||
|
||||
---
|
||||
|
||||
## 8. 成功判据(产品级)
|
||||
|
||||
在仓库根或任意含 `index.mq.md` 的目录:
|
||||
|
||||
```bash
|
||||
marqdo run examples/structure/nested-call.mq.md
|
||||
# 或
|
||||
marqdo run examples/structure/import/main.mq.md
|
||||
```
|
||||
|
||||
输出与金样例一致;错误带位置;新增语法必须加金样例与单测。这才是「一门解释型语言」的最低合格线。
|
||||
@@ -0,0 +1,15 @@
|
||||
# Marqdo examples(金样例)
|
||||
|
||||
本目录即测试夹具,见 [doc/design/examples-and-tests.md](../doc/design/examples-and-tests.md)。
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| [`structure/`](structure/) | 函数、调用、分支、循环、表、导入、位置实参 |
|
||||
| [`keywords/`](keywords/) | `print`、布尔与 `and`/`or`/`not` |
|
||||
| [`errors/`](errors/) | 期望失败(未定义名 / 未知函数 / 实参 / 语法) |
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
marqdo run examples/structure/hello.mq.md
|
||||
marqdo view examples
|
||||
```
|
||||
File renamed without changes.
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: bad arity
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> needs_one
|
||||
|
||||
## needs_one
|
||||
- x
|
||||
|
||||
> print text=`x`
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: unrecognized code line
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
~not-valid-syntax
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: undefined variable
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> print text=`missing`
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: unknown function
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> no_such_fn x=1
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: 布尔与逻辑关键字
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`a` = True*
|
||||
*`b` = False*
|
||||
|
||||
+ `a` and not `b`
|
||||
> print text=ok
|
||||
+ *
|
||||
> print text=fail
|
||||
|
||||
*`probe` = 1*
|
||||
|
||||
+ None
|
||||
> print text=none-truthy
|
||||
+ *
|
||||
> print text=none-falsy
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: 内置 print
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> print text=named form
|
||||
|
||||
> print positional
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 分支示例
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`x` = 0*
|
||||
|
||||
+ `x` > 0
|
||||
> print text=正数
|
||||
+ `x` < 0
|
||||
> print text=负数
|
||||
+ *
|
||||
> print text=零
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: 集合(表格)示例
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
|
||||
- [果](篮子)
|
||||
> print text=`果`
|
||||
@@ -0,0 +1,5 @@
|
||||
# Hello World
|
||||
|
||||
本程序调用内置函数 `print` 打印问候。注释里的 **粗体** 与 *斜体* 都不执行。
|
||||
|
||||
> print text=Hello World!
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 跨文件导入示例
|
||||
> utils.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
导入 `utils.mq.md` 后:用返回值绑定,再输出;并直接调用问候。
|
||||
|
||||
*`y` = > 加一 n=41*
|
||||
|
||||
> print text=`y`
|
||||
|
||||
> 问候 谁=Marqdo
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 工具函数
|
||||
description: 供 frontmatter > 导入;返回用粗体;副作用用输出函数
|
||||
---
|
||||
|
||||
# 加一
|
||||
- n
|
||||
|
||||
**`n` + 1**
|
||||
|
||||
# 问候
|
||||
- 谁
|
||||
|
||||
> print text=你好,`谁`!
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: 循环示例
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
倒数:
|
||||
|
||||
*`n` = 3*
|
||||
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*`n` = `n` - 1*
|
||||
|
||||
遍历篮子:
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
|
||||
- [果](篮子)
|
||||
> print text=今天吃`果`
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Hello World
|
||||
description: Recommended entry — nested fn; print builtin; bold return
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
打印一句问候。`print` 是函数,不是语法架构;粗体只用于返回值。
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=Hello `谁`!
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: 位置实参
|
||||
description: `> fn value` binds by parameter order; named form still works
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
位置实参:
|
||||
|
||||
> 问候 Marqdo
|
||||
|
||||
具名实参(保留):
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=Hello `谁`!
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Phase I — tree-walk interpreter
|
||||
description: Lex · parse · check · tree-walk end to end
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Milestone: Phase I (tree-walk).
|
||||
|
||||
Pipeline: load → line classify → recursive-descent parse → semantic check → tree-walk eval. No Flex/Bison.
|
||||
|
||||
This page runs as a program — documentation is executable:
|
||||
|
||||
We now **[Display this step's result](> print text="Phase I: tree-walk interpreter is live.")**.
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 第一阶段 — 树遍历解释器
|
||||
description: 词法 · 语法 · 语义 · 树遍历已贯通
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
里程碑:第一阶段(树遍历)。
|
||||
|
||||
流水线:加载 → 行分类 → 递归下降语法 → 语义检查 → 树遍历执行。实现不用 Flex/Bison。
|
||||
|
||||
本页本身即可运行,证明「文档即程序」已落地:
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="第一阶段:树遍历解释器已就绪。")**。
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Bytecode backend
|
||||
description: `--backend bytecode` shares semantics with tree-walk
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Milestone: bytecode prototype.
|
||||
|
||||
The same `.mq.md` runs on tree-walk or the bytecode VM:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
Output matches on both backends:
|
||||
|
||||
We now **[Display this step's result](> print text="Bytecode backend: same program, alternate engine.")**.
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 字节码后端
|
||||
description: `--backend bytecode` 与树遍历共用语义
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
里程碑:字节码原型。
|
||||
|
||||
同一套 `.mq.md` 可用树遍历或字节码 VM:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
两种后端输出一致:
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="字节码后端:同一程序,另一引擎。")**。
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: view and the user docs site
|
||||
description: Local browse and static export from the interpreter
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Version 2.6.0 keeps action descriptions in the sentence and moves their implementation to side notes. Empty parentheses explicitly mark missing logic. Multiple actions and returns keep their original prose, while ordinary links remain navigation. On compact screens, native disclosures keep the implementation readable even without JavaScript.
|
||||
|
||||
Executable knowledge now presents inputs, returns, effects, dependencies and separate verification facts. Technical identities and digests stay folded. Source explanations are distinct from captured results; a pure effect summary or linked source is not proof that a program ran or its content was verified.
|
||||
|
||||
The reader introduced in 2.5.1: `marqdo view` and `view output` share a warm paper reader with a new
|
||||
Marqdo logo, serif document text, botanical ornaments, navigation, search and a
|
||||
floating action toolbar. Wide screens place real execution notes in the margins;
|
||||
compact screens keep them below the corresponding paragraph. Click a note to
|
||||
inspect its full captured value. Call and loop frame selectors remain available.
|
||||
|
||||
Static exports embed decorations, KaTeX and math fonts for offline reading. The
|
||||
play button runs the document in live view; static pages retain their captured
|
||||
results and explain how to start a live view. Ordinary document reruns update
|
||||
prose, bindings and notes from the same execution capture.
|
||||
|
||||
Annotations follow the exact source span across calls and loop iterations. Flowing
|
||||
curves and staggered margin notes avoid source text and neighboring connections.
|
||||
The floating toolbar labels its actions: refresh, settings, run, clear and more.
|
||||
|
||||
Local: `marqdo view public`
|
||||
|
||||
Static export: `marqdo view output public -o public`
|
||||
|
||||
Browse Structure keeps narration, highlights executable markers, and attaches
|
||||
run results (values, taken branch arms, call/loop frames). The same render path
|
||||
builds this user docs site; CI publishes to `gh-pages`.
|
||||
|
||||
We now **[Display this step's result](> print text="Docs site: generated by the Marqdo interpreter, not hand-written HTML.")**.
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: view 与用户文档站
|
||||
description: 本地浏览与静态导出由解释器生成
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
版本 2.6.0 将动作说明留在句子里,实际实现引到侧注;空圆括号明确提示待补逻辑。同一句话可以保留多个调用与返回,普通链接仍是导航。窄屏使用原生可展开详情,没有 JavaScript 也能查看实现。
|
||||
|
||||
可执行知识先展示输入、返回、调用边界、依赖和分别列出的验证依据,技术身份与摘要按需展开。源码说明与运行捕获有不同含义;pure、来源关联或构造配置都不能被当作已运行或内容已验证的证据。
|
||||
|
||||
沿用 2.5.1 的阅读底座:`marqdo view` 与 `view output` 共用暖白金色阅读界面,新 Marqdo 标志、
|
||||
衬线正文、花枝装饰、导航搜索与底部悬浮工具栏。宽屏将真实执行结果沿左右页边引出,
|
||||
窄屏将标注放回对应段落下方;点击标注可查看完整捕获值,调用帧和循环轮次仍可切换。
|
||||
|
||||
静态导出内嵌装饰素材、KaTeX 与数学字体,断网也能阅读公式。播放按钮在实时 view 中
|
||||
运行文档;静态页面保留导出结果,并提示如何启动实时 view。普通文档重跑后,正文、
|
||||
变量和执行标注使用同一次执行捕获同步刷新。
|
||||
|
||||
执行标注跨调用帧与循环轮次精确对应源码区间。连续曲线与错落标注会避让正文和相邻连线;
|
||||
底部工具栏显示“刷新、设置、运行、清理、更多”,深浅色配色保持一致。
|
||||
|
||||
本地浏览:`marqdo view public`
|
||||
|
||||
静态导出:`marqdo view output public -o public`
|
||||
|
||||
Browse Structure 保真叙述、高亮可执行标记,并挂载运行结果(变量值、分支命中臂、调用/循环帧)。
|
||||
用户站与 live view 同源渲染;CI 发布到 `gh-pages`。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="文档站:由 Marqdo 解释器生成,不是手写 HTML。")**。
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Objects and methods
|
||||
description: Sharp heading is a type; deeper headings are functions or methods
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
In Marqdo, a single sharp (#) defines an object / type constructor. Double sharp and deeper (## …) define free functions or methods. Constructing an object yields a map handle tagged with _type. Call methods with backtick object, then dot, then method name.
|
||||
|
||||
See doc/design/objects.md. Example gold: tests/structure/object-handle.mq.md. Official ext/llm and ext/agent use this pattern.
|
||||
|
||||
We now **[Display this step's result](> print text="objects-ok")**.
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 对象与方法
|
||||
description: 一级标题是类型;更深标题是函数或方法
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
Marqdo 中,单个井号(#)定义对象 / 类型构造体;二级及以上(## …)定义自由函数或方法。构造得到带 _type 标记的 map 句柄。方法调用形如:反引号对象、点、方法名。
|
||||
|
||||
详见 doc/design/objects.md。金样例:tests/structure/object-handle.mq.md。官方 ext/llm 与 ext/agent 使用同一模式。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="对象就绪")**。
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Official extensions (ext/)
|
||||
description: Optional packages — not stdlib
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
ext/ holds official optional extensions. They are not part of lib/. Resolve via `~/.marqdo/ext`, MARQDO_EXT, ./ext, or ext/ next to the binary.
|
||||
|
||||
Install (v0.2+):
|
||||
|
||||
```text
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
marqdo ext add linalg
|
||||
```
|
||||
|
||||
`ext add` downloads L1 sources and prebuilt natives when available. Order: CDN https://ext.marqdo.com → GitHub Releases → proxy mirror. Pack SemVer is `ext/VERSION` and may differ from the CLI.
|
||||
|
||||
Rebuild natives locally only when developing plugins:
|
||||
|
||||
```text
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
cargo build --release -p marqdo_plugin_quantum
|
||||
cargo build --release -p marqdo_plugin_linalg
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
Packages (not Markdown list markers — those are loops in Marqdo):
|
||||
|
||||
ext/llm — OpenAI-compatible chat. Design: doc/design/ext-llm.md
|
||||
|
||||
ext/agent — agent framework + native plugin. Design: doc/design/ext-agent.md
|
||||
|
||||
ext/web provides Documents/Endpoints, recursive View, document-head and request resources. Decompose layout to Markdown or native-control leaves; data, authentication and transport belong to ext/data, ext/security and ext/net. Follow examples/web-site/index.mq.md and examples/web-net-site/index.mq.md for complete workflows. Browser interaction uses Marqdo clients and the official WASM bridge. Development, builds and real acceptance run through marqdo call in skills/marqdo-dev/index.mq.md; the current author contract starts at ext/web/index.mq.md.
|
||||
|
||||
ext/quantum — circuits, draw, noise, formula matrix custom gates, Q7 density/viz, Q8 themed SVG (`theme=dark|light|bw`). Design: doc/design/ext-quantum.md · doc/design/ext-quantum-viz-style.md
|
||||
|
||||
Installer: marqdo ext list / add / remove — doc/design/ext-cli.md
|
||||
|
||||
Native plugins: lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
|
||||
|
||||
We now **[Display this step's result](> print text="ext-ok")**.
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 官方扩展(ext/)
|
||||
description: 可选包 — 不是标准库
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
ext/ 存放官方可选扩展,不属于 lib/。解析顺序:`~/.marqdo/ext`、MARQDO_EXT、./ext、或可执行文件旁的 ext/。
|
||||
|
||||
安装(v0.2+):
|
||||
|
||||
```text
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
marqdo ext add linalg
|
||||
```
|
||||
|
||||
`ext add` 会下载 L1 与预编译 native(若有)。下载顺序:CDN https://ext.marqdo.com → GitHub Releases → proxy 镜像。扩展包版本见 `ext/VERSION`,可与 CLI 分开发版。
|
||||
|
||||
带原生插件的包若需本地重编:
|
||||
|
||||
```text
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
cargo build --release -p marqdo_plugin_quantum
|
||||
cargo build --release -p marqdo_plugin_linalg
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
扩展包(勿用 Markdown `-` 列表:在 Marqdo 里 `-` 是循环):
|
||||
|
||||
ext/llm(大模型)— OpenAI 兼容聊天。设计:doc/design/ext-llm.md
|
||||
|
||||
ext/agent(智能体)— 智能体框架 + 原生插件。设计:doc/design/ext-agent.md
|
||||
|
||||
ext/web(网页)提供 Document/Endpoint、递归 View、页头和请求资源。布局拆到 Markdown 或原生控件叶子,数据、鉴权与运输分别归 ext/data、ext/security、ext/net。完整实践见 examples/web-site-zh/index.mq.md 与 examples/web-net-site-zh/index.mq.md;浏览器交互通过 Marqdo 客户端及官方 WASM 桥完成。开发、构建和真实验收入口为 skills/marqdo-dev/index.mq.md,操作使用 marqdo call;当前作者契约见 ext/web/网页/索引.mq.md。
|
||||
|
||||
ext/quantum(量子)— 电路、绘图、噪声、公式矩阵自定义门、Q7 密度/高级图、Q8 主题 SVG(`主题=dark|light|bw`)。设计:doc/design/ext-quantum.md · doc/design/ext-quantum-viz-style.md
|
||||
|
||||
安装器:marqdo ext list / add / remove — doc/design/ext-cli.md
|
||||
|
||||
通用原生插件:lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="扩展就绪")**。
|
||||
@@ -1,14 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="152" height="180" viewBox="0 0 152.0 180.0" data-theme="dark" role="img" aria-label="measurement probabilities"><defs>
|
||||
<linearGradient id="mq-bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#0a0e14"/>
|
||||
<stop offset="55%" stop-color="#141c28"/>
|
||||
<stop offset="100%" stop-color="#0a0e14"/>
|
||||
</linearGradient>
|
||||
<filter id="mq-glow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="2.2" result="b"/>
|
||||
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<filter id="mq-soft" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="1.5" stdDeviation="1.8" flood-color="#4c6fff" flood-opacity="0.35"/>
|
||||
</filter>
|
||||
</defs><rect width="152.0" height="180.0" rx="14" fill="url(#mq-bg)"/><line x1="36" y1="144" x2="136" y2="144" stroke="#7d8fa3" stroke-width="1.2"/><line x1="36" y1="24" x2="36" y2="144" stroke="#7d8fa3" stroke-width="1.2"/><text x="8" y="28" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#e8eef6">1</text><text x="8" y="148" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#e8eef6">0</text><rect x="40" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#5b7cfa" stroke="#f0f5ff" stroke-width="1" filter="url(#mq-soft)"/><text x="58" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#e8eef6">000</text><text x="58" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#93a4b8">0.50</text><rect x="88" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#5b7cfa" stroke="#f0f5ff" stroke-width="1" filter="url(#mq-soft)"/><text x="106" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#e8eef6">111</text><text x="106" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#93a4b8">0.50</text></svg>
|
||||
|
Before Width: | Height: | Size: 2.0 KiB |
@@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="196" height="192" viewBox="0 0 196.0 192.0" role="img" aria-label="gate matrix heatmap"><text x="8" y="18" font-family="ui-monospace,Menlo,monospace" font-size="12" fill="#1a1a1a">H matrix</text><text x="8" y="67.6" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">0</text><text x="72" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">0</text><rect x="36" y="28" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="72" y="67.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><rect x="108" y="28" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="144" y="67.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><text x="8" y="139.60000000000002" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">1</text><text x="144" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">1</text><rect x="36" y="100" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="72" y="139.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><rect x="108" y="100" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="144" y="139.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">-0.707</text></svg>
|
||||
|
Before Width: | Height: | Size: 1.6 KiB |
@@ -1,39 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Quantum circuits (ext/quantum)
|
||||
description: Official quantum simulator — tables, gates, Q7 density, Q8 themed SVG
|
||||
import:
|
||||
quantum: ext/quantum/circuit/index.mq.md
|
||||
gate: ext/quantum/gate/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Optional package (not stdlib). Install: `marqdo ext add quantum` (or build `marqdo_plugin_quantum`).
|
||||
|
||||
GHZ (3 qubits): H on q0, then CX 0→1 and 0→2. Ideal |000⟩ / |111⟩ each ≈ 1/2.
|
||||
|
||||
Q7: Bell density, partial trace, Schmidt, `draw kind=hinton` / qsphere — `examples/quantum-entanglement/`.
|
||||
|
||||
Q8: `draw theme="dark"|"light"|"bw"` (default dark lab look) on circuit / probs / bloch. Rebuild plugin then `ext add` so view loads the new native lib.
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
| 3 | CX | 0,2 |
|
||||
|
||||
We first **qc = [Compute qc](quantum.circuit(qubits=3, steps=`steps`))** for the next step.
|
||||
We first **p = [Compute p](> `qc`.probabilities)** for the next step.
|
||||
We first **_ = [Compute _](> `qc`.draw kind="probs" theme="dark")** for the next step.
|
||||
We first **H = [Compute H](gate.gate(name="H"))** for the next step.
|
||||
We first **__ = [Compute __](> `H`.draw kind="matrix")** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text=`p`)**.
|
||||
We now **[Display this step's result](> print text="quantum-feature-ok")**.
|
||||
@@ -1,14 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="152" height="180" viewBox="0 0 152.0 180.0" data-theme="dark" role="img" aria-label="measurement probabilities"><defs>
|
||||
<linearGradient id="mq-bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#0a0e14"/>
|
||||
<stop offset="55%" stop-color="#141c28"/>
|
||||
<stop offset="100%" stop-color="#0a0e14"/>
|
||||
</linearGradient>
|
||||
<filter id="mq-glow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="2.2" result="b"/>
|
||||
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<filter id="mq-soft" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="1.5" stdDeviation="1.8" flood-color="#4c6fff" flood-opacity="0.35"/>
|
||||
</filter>
|
||||
</defs><rect width="152.0" height="180.0" rx="14" fill="url(#mq-bg)"/><line x1="36" y1="144" x2="136" y2="144" stroke="#7d8fa3" stroke-width="1.2"/><line x1="36" y1="24" x2="36" y2="144" stroke="#7d8fa3" stroke-width="1.2"/><text x="8" y="28" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#e8eef6">1</text><text x="8" y="148" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#e8eef6">0</text><rect x="40" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#5b7cfa" stroke="#f0f5ff" stroke-width="1" filter="url(#mq-soft)"/><text x="58" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#e8eef6">000</text><text x="58" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#93a4b8">0.50</text><rect x="88" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#5b7cfa" stroke="#f0f5ff" stroke-width="1" filter="url(#mq-soft)"/><text x="106" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#e8eef6">111</text><text x="106" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#93a4b8">0.50</text></svg>
|
||||
|
Before Width: | Height: | Size: 2.0 KiB |
@@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="196" height="192" viewBox="0 0 196.0 192.0" role="img" aria-label="gate matrix heatmap"><text x="8" y="18" font-family="ui-monospace,Menlo,monospace" font-size="12" fill="#1a1a1a">H matrix</text><text x="8" y="67.6" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">0</text><text x="72" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">0</text><rect x="36" y="28" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="72" y="67.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><rect x="108" y="28" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="144" y="67.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><text x="8" y="139.60000000000002" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">1</text><text x="144" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">1</text><rect x="36" y="100" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="72" y="139.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><rect x="108" y="100" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="144" y="139.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">-0.707</text></svg>
|
||||
|
Before Width: | Height: | Size: 1.6 KiB |
@@ -1,41 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 量子电路(ext/quantum)
|
||||
description: 官方量子模拟 — 表、门、Q7 密度与高级图、Q8 主题 SVG
|
||||
导入:
|
||||
量子: ext/quantum/量子/电路/索引.mq.md
|
||||
门: ext/quantum/量子/门/索引.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
可选扩展(非 stdlib)。安装:`marqdo ext add quantum`(或编译 `marqdo_plugin_quantum`)。
|
||||
|
||||
中文面在同包 `ext/quantum/量子/`(根 skill:`索引.mq.md`),与英文模块树并列、不混排 API。
|
||||
|
||||
GHZ(3 比特):q0 哈达玛,再控非 0→1、0→2。理想 |000⟩ / |111⟩ 各约 1/2。
|
||||
|
||||
Q7:密度 / 部分迹 / Schmidt / `绘图 种类=hinton` 等 — `examples/quantum-entanglement/`。
|
||||
|
||||
Q8:`绘图 主题="dark"|"light"|"bw"`(默认 dark 科技感)作用于电路 / 概率 / 布洛赫。改插件后须再 `ext add`,view 才会加载新 `.so`。
|
||||
|
||||
`步骤` =
|
||||
|
||||
| 步 | 门 | 比特 |
|
||||
|----|----|------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
| 3 | CX | 0,2 |
|
||||
|
||||
我们先**qc = [计算并保存 qc](量子.电路(比特数=3, 步骤=`步骤`))**,供下一步使用。
|
||||
我们先**p = [计算并保存 p](> `qc`.概率)**,供下一步使用。
|
||||
我们先**_ = [计算并保存 _](> `qc`.绘图 种类="probs" 主题="dark")**,供下一步使用。
|
||||
我们先**H = [计算并保存 H](门.门(名="H"))**,供下一步使用。
|
||||
我们先**__ = [计算并保存 __](> `H`.绘图 种类="matrix")**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`p`)**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="量子特性-ok")**。
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: How to write a linear-algebra formula document
|
||||
description: ext/linalg formula-doc — declare, infix, run-implies-correct
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# Formula documents with ext/linalg
|
||||
|
||||
|
||||
Not stdlib. Install: `marqdo ext add linalg` (or build `marqdo_plugin_linalg`).
|
||||
|
||||
*Idea:* if the `.mq.md` runs and the asserted form matches, the identity holds under the library rules. Algebra reads like a lecture; `factorize` / `lstsq` / `draw` stay explicit calculation steps.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Declare symbols in a table, multiply, transpose — `T_ascii` is one-step display (auto-simplify).
|
||||
|
||||
`shapes` =
|
||||
|
||||
| @ | name | rows | cols |
|
||||
|---|------|------|------|
|
||||
| 1 | A | 2 | 3 |
|
||||
| 2 | B | 3 | 2 |
|
||||
|
||||
We first **env = [Compute env](la.declare(table=`shapes`))** for the next step.
|
||||
We first **A = [A](access(`env`, "A"))** for the next step.
|
||||
We first **B = [B](access(`env`, "B"))** for the next step.
|
||||
We first **P = (`A` * `B`)** for the next step.
|
||||
We first **t = [Compute t](> `P`.T_ascii)** for the next step.
|
||||
We now **[Display this step's result](> print text=`t`)**.
|
||||
1. `t` == "B^T*A^T"
|
||||
We now **[Display this step's result](> print text="formula-doc-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="formula-doc-fail")**.
|
||||
|
||||
We now **[Display this step's result](> print text="see-examples-linalg-transpose")**.
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 如何写线性代数公式文档
|
||||
description: ext/linalg 公式文档面 — 声明、中缀、跑通即正确
|
||||
导入:
|
||||
la: ext/linalg/线性代数.mq.md
|
||||
---
|
||||
|
||||
# 用 ext/linalg 写公式文档
|
||||
|
||||
可选扩展(非 stdlib)。安装:`marqdo ext add linalg`(中文 id:`线性代数`)。
|
||||
|
||||
*思想:* `.mq.md` 能跑通且断言的规范形一致,则在库规则下该恒等式成立。代数叙述像讲义;`分解` / `最小二乘` / `绘图` 才是显式计算步骤。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
这里讨论符号表达式的形状,而不是对矩阵中的每个数值做计算。先声明 A 为两行三列、B 为三行两列,乘积才具有合法的二行二列形状;转置时两个因子的顺序交换,得到 B^T*A^T。输出相符只证明本例在库定义的规范化规则下成立,不意味着任意数值近似或未声明符号也会被接受。
|
||||
|
||||
阅读时先看形状表,再看乘法和转置的动作说明。公式库需要对应的原生插件,缺少依赖时应先安装 linalg;不要把插件加载错误当成恒等式不成立。此例不读取或写入业务文件,也不把输出字符串重新执行成代码。需要实际矩阵分解时,沿文件开头的导入路径阅读分解函数的独立契约。
|
||||
|
||||
用表声明符号,再乘与转置 — `转置文本` 一步展示(默认化简)。
|
||||
|
||||
`形状` =
|
||||
|
||||
| @ | 名 | 行 | 列 |
|
||||
|---|----|----|----|
|
||||
| 1 | A | 2 | 3 |
|
||||
| 2 | B | 3 | 2 |
|
||||
|
||||
我们先**环境 = [声明带有行列约束的符号环境](la.声明(表=`形状`))**,供下一步使用。
|
||||
我们先**A = [A](access(`环境`, "A"))**,供下一步使用。
|
||||
我们先**B = [B](access(`环境`, "B"))**,供下一步使用。
|
||||
我们先**P = (`A` * `B`)**,供下一步使用。
|
||||
我们先**t = [取得当前步骤的转置公式或随机令牌](> `P`.转置文本)**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`t`)**。
|
||||
1. `t` == "B^T*A^T"
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="formula-doc-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="formula-doc-fail")**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="see-examples-linalg-transpose")**。
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — regex and encoding
|
||||
description: lib/re + lib/encoding without plugins (Mid M1)
|
||||
import:
|
||||
re: lib/re.mq.md
|
||||
enc: lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# Regex and encoding in lib/
|
||||
|
||||
|
||||
Mid-tier stdlib: everyday primitives stay in `lib/`, not ABI plugins.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **ok = [Compute ok](re.is_match(text="user@example.com", pattern="^[^@]+@[^@]+$"))** for the next step.
|
||||
We first **tok = [Compute tok](enc.base64_encode(text="marqdo"))** for the next step.
|
||||
We first **hex = [Compute hex](enc.hex_encode(text="ok"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`ok`)**.
|
||||
We now **[Display this step's result](> print text=`tok`)**.
|
||||
We now **[Display this step's result](> print text=`hex`)**.
|
||||
1. `ok`
|
||||
We now **[Display this step's result](> print text="mid-m1-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="mid-m1-fail")**.
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 正则与编解码
|
||||
description: lib/正则 + lib/编码,无需插件(中层 M1)
|
||||
导入:
|
||||
正则: lib/正则.mq.md
|
||||
编码: lib/编码.mq.md
|
||||
---
|
||||
|
||||
# 标准库中的正则与编解码
|
||||
|
||||
中层标准库:日常原语进 `lib/`,不必 ABI 插件。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
本例从固定的邮箱样式文本开始:正则只检查是否符合给定模式,并不是邮件地址真实性验证。随后把普通 UTF-8 文本分别编码成 Base64 和十六进制,以展示三种返回值的区别:匹配结果是布尔值,两种编码结果是文本。编码后的文本可以继续传给解码函数,还原原始字节或文字。
|
||||
|
||||
编码不具有保密作用,也不会替调用方校验邮箱能否接收消息。这里没有网络请求、文件读写或插件安装;所有输入都来自正文中的字面值。实际接入用户输入时要保留模式与编码函数的错误诊断,不能用空字符串代替失败。最后的标记只检查本例的匹配分支,不能代替编码往返和非法输入的验收。
|
||||
|
||||
我们先**ok = [检查给定模式是否匹配邮箱样式](正则.匹配(内容="user@example.com", 模式="^[^@]+@[^@]+$"))**,供下一步使用。
|
||||
我们先**tok = [把文本编码为 Base64](编码.基64编码(内容="marqdo"))**,供下一步使用。
|
||||
我们先**hex = [把文本编码为十六进制](编码.十六进制编码(内容="ok"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`ok`)**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`tok`)**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`hex`)**。
|
||||
1. `ok`
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m1-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m1-fail")**。
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Path algebra and isolated native file copying
|
||||
import:
|
||||
path: lib/path.mq.md
|
||||
fs: lib/fs.mq.md
|
||||
---
|
||||
|
||||
This page composes native path and filesystem libraries. Call main with fs.write and a disposable --fs-root; the return contains actual observations for a caller or View.
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | Joined/normalized path text and actual copied content |
|
||||
|
||||
Joining and normalizing transform path text without granting filesystem access. The illustrative out/demo.txt is not an actual write destination. All real IO uses a unique native temporary directory, so this page neither requires a pre-existing out directory nor overwrites a caller's same-named files.
|
||||
|
||||
Grant fs.write and choose a disposable root. Native encoding, path and root checks still apply. Read the copied content before cleaning this run's directory; the returned value should be path-m2. The result contains observations rather than live file paths. An intermediate failure retains its native diagnostic and can leave this run's directory for inspection and caller cleanup.
|
||||
|
||||
The complete flow demonstrates text-only path algebra, actual writing, copying, reading and scoped cleanup. A normalized string is not a filesystem permission, and a printed marker alone would not prove what bytes were copied.
|
||||
|
||||
We **requested = [Join the illustrative output path](path.join(a="out", b="demo.txt"))** and **normalized = [Remove redundant path segments without filesystem IO](path.normalize(path="out/./x/../demo.txt"))** before the file demonstration.
|
||||
For actual IO we **work = [Create a unique directory inside the granted root](fs.temp_dir(prefix="path-demo"))** and **original = [Name this run own source file](path.join(a=`work`, b="demo.txt"))** and **copied = [Name its isolated copy](path.join(a=`work`, b="demo-copy.txt"))**.
|
||||
We **[Write the actual text to copy](fs.write_text(path=`original`, text="path-m2"))** and **[Copy only this run own file](fs.copy_file(src=`original`, dest=`copied`))**.
|
||||
We **copied_text = [Observe the actual copied content](fs.read_text(path=`copied`))** and then **[Clean only this run unique directory](fs.remove_tree(path=`work`))**.
|
||||
|
||||
`observed` =
|
||||
|
||||
| requested | normalized | copied_text |
|
||||
|---|---|---|
|
||||
| `requested` | `normalized` | `copied_text` |
|
||||
|
||||
After the isolated file operation we return *observed*. The temporary files have been removed.
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 路径代数与隔离的原生文件复制
|
||||
import:
|
||||
路径: lib/路径.mq.md
|
||||
文件: lib/文件.mq.md
|
||||
---
|
||||
|
||||
本页直接使用路径库和文件库。调用 main 时授权 fs.write,并将 --fs-root 指向可丢弃的工作目录。函数返回实际观察记录,View 可以显示这些值;无需生成外部脚本。
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | 路径拼接文本、规范化文本与实际复制正文 |
|
||||
|
||||
路径拼接和规范化先处理文本,不隐含文件访问授权。out/demo.txt 只是这个代数示例的输入,不会成为实际写入目的地。真正的文件操作全部放在通过固有库创建的唯一临时目录里,因此不要求已有 out 目录,也不覆盖用户的同名文件。
|
||||
|
||||
调用需要 fs.write,文件库仍会检查授权根目录、编码与路径边界。复制后的正文应为 path-m2。保存这个实际值后清理本轮目录,再返回观察记录;临时路径不会成为可继续使用的持久产物。失败保留原生诊断,中途错误可能留下本轮临时目录供检查,调用方负责识别并清理它。
|
||||
|
||||
本函数既展示无 IO 的路径代数,也展示真实写入、复制、读取和清理。业务中不要根据一个规范化后的字符串就认为已经获得文件权限,更不要把打印成功标记当成已读回复制内容的证明。
|
||||
|
||||
先**requested = [组合演示用的相对路径文本](路径.拼接(甲="out", 乙="demo.txt"))**和**normalized = [消除相对路径中的冗余片段](路径.规范化(路径="out/./x/../demo.txt"))**,核对路径代数本身。
|
||||
为实际读写创建**work = [只使用本轮独有的授权临时目录](文件.临时目录(前缀="路径演示"))**,再准备**original = [在临时目录中命名原文件](路径.拼接(甲=`work`, 乙="demo.txt"))**和**copied = [在同一目录中命名副本](路径.拼接(甲=`work`, 乙="demo-copy.txt"))**。
|
||||
随后**[写入本轮需要复制的正文](文件.写文本(路径=`original`, 内容="path-m2"))**,并**[复制本轮文件而不触及已有用户文件](文件.复制文件(源=`original`, 目标=`copied`))**。
|
||||
读取阶段保存**copied_text = [读取副本的真实正文](文件.读文本(路径=`copied`))**,完成观察后**[清理本轮独有的临时目录](文件.删目录树(路径=`work`))**。
|
||||
|
||||
`observed` =
|
||||
|
||||
| requested | normalized | copied_text |
|
||||
|---|---|---|
|
||||
| `requested` | `normalized` | `copied_text` |
|
||||
|
||||
完成路径处理与隔离读写后,我们返回*observed*,其中保留的是已观察到的值,临时文件已经清理。
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — hash and secrets
|
||||
description: lib/hash + lib/secrets without plugins (Mid M3)
|
||||
import:
|
||||
hash: lib/hash.mq.md
|
||||
sec: lib/secrets.mq.md
|
||||
---
|
||||
|
||||
# Digests and secure tokens
|
||||
|
||||
|
||||
Integrity digests and cryptographic tokens stay in `lib/` — do not use `math.random` for secrets.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **d = [Compute d](hash.sha256(text="marqdo"))** for the next step.
|
||||
We first **t = [Compute t](sec.token_hex(n=8))** for the next step.
|
||||
We first **L = [Compute L](len(`t`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`d`)**.
|
||||
We now **[Display this step's result](> print text=`L`)**.
|
||||
1. `L` == 16
|
||||
We now **[Display this step's result](> print text="mid-m3-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="mid-m3-fail")**.
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 哈希与机密
|
||||
description: lib/哈希 + lib/机密,无需插件(中层 M3)
|
||||
导入:
|
||||
哈希: lib/哈希.mq.md
|
||||
机密: lib/机密.mq.md
|
||||
---
|
||||
|
||||
# 摘要与安全令牌
|
||||
|
||||
完整性摘要与加密令牌进 `lib/` — 勿用 `math.random` 生成令牌。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
摘要和随机令牌解决不同的问题。固定文本的 SHA-256 摘要可用于比对内容是否变化;随机令牌从安全随机源获取字节,再编码为十六进制文本。八个随机字节会显示为十六个十六进制字符,因此这里检查输出长度,不把令牌与某个固定值比较。
|
||||
|
||||
本例不会把令牌写到磁盘或发送到网络。实际产品需要依据用途选择令牌字节数,并在使用后按应用规则保管或撤销;这里的短值只演示参数与编码长度的关系。哈希不提供加密,也不能单靠未认证的摘要证明内容来自谁。随机源失败时应保留诊断,不能改用普通伪随机数或固定文本充当安全令牌。
|
||||
|
||||
我们先**d = [计算固定文本的 SHA-256](哈希.哈希256(内容="marqdo"))**,供下一步使用。
|
||||
我们先**t = [取得当前步骤的转置公式或随机令牌](机密.十六进制令牌(字节数=8))**,供下一步使用。
|
||||
我们先**L = [读取十六进制令牌的字符数](长度(`t`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`d`)**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`L`)**。
|
||||
1. `L` == 16
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m3-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m3-fail")**。
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — csv and text
|
||||
description: lib/csv + thickened lib/text (Mid M4)
|
||||
import:
|
||||
csv: lib/csv.mq.md
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# CSV cleaning with text helpers
|
||||
|
||||
|
||||
Parse a tiny CSV, normalize a field, print — no plugins.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **raw = "name,city\nAda,london\nBob,PARIS\n"** for the next step.
|
||||
We first **rows = [Compute rows](csv.parse(text=`raw`))** for the next step.
|
||||
We first **r0 = [Compute r0](at(value=`rows`, index=0))** for the next step.
|
||||
We first **city = [Compute city](text.to_upper(text=[city](access(`r0`, "city"))))** for the next step.
|
||||
We now **[Display this step's result](> print text=[name](access(`r0`, "name")))**.
|
||||
We now **[Display this step's result](> print text=`city`)**.
|
||||
We first **n = [Compute n](len(`rows`))** for the next step.
|
||||
1. `n` == 2
|
||||
We now **[Display this step's result](> print text="mid-m4-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="mid-m4-fail")**.
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 逗号表与文本
|
||||
description: lib/逗号表 + 加厚 lib/文本(中层 M4)
|
||||
导入:
|
||||
逗号表: lib/逗号表.mq.md
|
||||
文本: lib/文本.mq.md
|
||||
---
|
||||
|
||||
# 用文本助手清洗 CSV
|
||||
|
||||
解析小表、规范化字段、打印 — 无需插件。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
CSV 解析先保留每个单元格的文本语义;下面选择第一条记录,再把城市字段规范为大写,得到 LONDON。姓名字段仍是 Ada,另一条记录仍保留在原集合中。调用文本变换不会自动替换原记录,因此这里只展示规范化值,不宣称整个表已经被清洗。
|
||||
|
||||
这里的 at 使用从零开始的位置,access 则按字段名读取记录;不要把二者的索引规则混用。输入正文直接写在本页,没有文件或进程访问。接入真实文件时先用原生文件库读取文本,再交给同一个解析函数;需要金额等数值运算时必须另外做明确的类型转换,不能根据 CSV 中的数字外观推断类型。两行计数只验证这份固定样本的解析结果。
|
||||
|
||||
我们先**raw = "name,city\nAda,london\nBob,PARIS\n"**,供下一步使用。
|
||||
我们先**rows = [解析或排序当前行记录](逗号表.解析(内容=`raw`))**,供下一步使用。
|
||||
我们先**r0 = [选择列表中的第一条记录](at(value=`rows`, index=0))**,供下一步使用。
|
||||
我们先**city = [将第一条记录的城市改为大写文本](文本.大写(内容=[city](access(`r0`, "city"))))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=[name](access(`r0`, "name")))**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`city`)**。
|
||||
我们先**n = [取得本步骤需要的路径或计数](长度(`rows`))**,供下一步使用。
|
||||
1. `n` == 2
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m4-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m4-fail")**。
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — lists and cli
|
||||
description: table sort/unique/zip + cli.parse (Mid M5)
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
csv: lib/csv.mq.md
|
||||
cli: lib/cli.mq.md
|
||||
---
|
||||
|
||||
# Sort CSV rows and parse flags
|
||||
|
||||
|
||||
Zero plugins: parse CSV, sort by key, parse `--input`.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **raw = "name,score\nbob,2\nalice,10\n"** for the next step.
|
||||
We first **rows = [Compute rows](csv.parse(text=`raw`))** for the next step.
|
||||
We first **rows = [Compute rows](table.sort_by(list=`rows`, key="name"))** for the next step.
|
||||
We first **r0 = [Compute r0](at(value=`rows`, index=0))** for the next step.
|
||||
We now **[Display this step's result](> print text=[name](access(`r0`, "name")))**.
|
||||
|
||||
We first **args = [Compute args](split(value="--input,scores.csv,--pretty", sep=","))** for the next step.
|
||||
We first **flags = [Compute flags](cli.parse(args=`args`))** for the next step.
|
||||
We now **[Display this step's result](> print text=[input](access(`flags`, "input")))**.
|
||||
1. [pretty](access(`flags`, "pretty"))
|
||||
We now **[Display this step's result](> print text="mid-m5-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="mid-m5-fail")**.
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 列表与命令行
|
||||
description: 表排序/去重 + 命令行解析(中层 M5)
|
||||
导入:
|
||||
表: lib/表.mq.md
|
||||
逗号表: lib/逗号表.mq.md
|
||||
命令行: lib/命令行.mq.md
|
||||
---
|
||||
|
||||
# 排序 CSV 并解析参数
|
||||
|
||||
零插件:解析 CSV、按键排序、解析 `--input`。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
这里先按 name 字段对 CSV 记录排序,所以第一条姓名是 alice;score 在本例中仍是文本,尚未参与数值排序。排序函数返回新集合,重新保存 rows 才能让后续取值使用排序结果。随后构造三个命令参数并交给命令行库,读取 input 的文件名以及 pretty 的开关状态。
|
||||
|
||||
参数数组中的元素始终是数据:本例解析 scores.csv 这个名字,不会读取该文件,也不会启动命令解释器。用于真实进程调用时应继续保持逐个参数传递,选项文本要加引号,不要拼成 shell 源码。没有插件、网络和文件授权需求;缺少必须的业务参数时,应由上层根据解析结果决定是否继续,而不是仅看到 pretty 为真就认定所有输入有效。
|
||||
|
||||
我们先**raw = "name,score\nbob,2\nalice,10\n"**,供下一步使用。
|
||||
我们先**rows = [解析或排序当前行记录](逗号表.解析(内容=`raw`))**,供下一步使用。
|
||||
我们先**rows = [解析或排序当前行记录](表.按键排序(list=`rows`, key="name"))**,供下一步使用。
|
||||
我们先**r0 = [选择列表中的第一条记录](at(value=`rows`, index=0))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=[name](access(`r0`, "name")))**。
|
||||
|
||||
我们先**args = [构造逐项传递的命令参数](split(value="--input,scores.csv,--pretty", sep=","))**,供下一步使用。
|
||||
我们先**flags = [解析选项值与布尔开关](命令行.解析(参数=`args`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=[input](access(`flags`, "input")))**。
|
||||
1. [pretty](access(`flags`, "pretty"))
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m5-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m5-fail")**。
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — log and uuid
|
||||
description: Level-filtered logs + UUID v4 (Mid M6)
|
||||
import:
|
||||
log: lib/log.mq.md
|
||||
uuid: lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# Observable scripts without plugins
|
||||
|
||||
|
||||
Default log level is info; raise to debug when you need more. Mint ids with uuid.v4.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We now **[Call log.info](> log.info text="mid-m6-start")**.
|
||||
|
||||
We now **[Call log.debug](> log.debug text="skipped-by-default")**.
|
||||
|
||||
We now **[Call log.set level](> log.set_level level="debug")**.
|
||||
|
||||
We now **[Call log.debug](> log.debug text="now-visible")**.
|
||||
|
||||
We first **id = [Compute id](uuid.v4())** for the next step.
|
||||
We first **n = [Compute n](len(`id`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`n`)**.
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 日志与标识
|
||||
description: 按级别过滤的日志 + UUID 版本4(中层 M6)
|
||||
导入:
|
||||
日志: lib/日志.mq.md
|
||||
标识: lib/标识.mq.md
|
||||
---
|
||||
|
||||
# 无插件的可观测脚本
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;本段完成下述操作,不额外返回业务数据。 |
|
||||
|
||||
默认日志级别为 info;需要细节时再调到 debug。用 标识.版本4 生成 id。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
随后我们**[执行 日志.信息](> 日志.信息 内容="中层-m6-开始")**。
|
||||
|
||||
随后我们**[执行 日志.调试](> 日志.调试 内容="默认会跳过")**。
|
||||
|
||||
随后我们**[执行 日志.设级别](> 日志.设级别 级别="debug")**。
|
||||
|
||||
随后我们**[执行 日志.调试](> 日志.调试 内容="现在可见")**。
|
||||
|
||||
我们先**id = [计算并保存 id](标识.版本4())**,供下一步使用。
|
||||
我们先**n = [计算并保存 n](长度(`id`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`n`)**。
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — datetime and url
|
||||
description: Calendar moments + URL/query parse (Mid2 M7)
|
||||
import:
|
||||
dt: lib/datetime.mq.md
|
||||
url: lib/url.mq.md
|
||||
---
|
||||
|
||||
# Time and addresses without plugins
|
||||
|
||||
|
||||
Moments are maps `{unix, zone, iso}`. Parse HTTPS URLs and round-trip query strings in `lib/url` (segment encoding stays in `net.url_encode`).
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **epoch = [Compute epoch](dt.from_unix(unix=0, zone="Asia/Shanghai"))** for the next step.
|
||||
We now **[Display this step's result](> print text=[iso](access(`epoch`, "iso")))**.
|
||||
|
||||
We first **u = [Compute u](url.parse(text="https://example.com/path?q=1#top"))** for the next step.
|
||||
We now **[Display this step's result](> print text=[host](access(`u`, "host")))**.
|
||||
We now **[Display this step's result](> print text=[query](access(`u`, "query")))**.
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 日期时间与地址
|
||||
description: 日历时刻 + URL/查询串(Mid2 M7)
|
||||
导入:
|
||||
日时: lib/日期时间.mq.md
|
||||
址: lib/地址.mq.md
|
||||
---
|
||||
|
||||
# 无需插件的时间与地址
|
||||
|
||||
时刻是 map `{unix, zone, iso}`。用 `地址` 拆 HTTPS URL 与查询串。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
时间戳零表示同一个时间点;指定 Asia/Shanghai 后,ISO 展示采用该时区的当地时间。改变时区不应改变 unix 字段所代表的瞬间。固定时间戳使本例可以重复验证,不依赖机器当前时钟,也不要求读取时间服务。
|
||||
|
||||
地址解析只拆分给定的 HTTPS 文本,host 应为 example.com,query 保留 q=1。它不会访问服务器、验证网站可用性或把查询字符串当作本地文件名。后续需要查询参数时应使用地址库对应的查询解析能力,并保留转义和重复键的边界。时间与 URL 都返回有明确字段的记录;先按契约读取字段,再决定展示格式,避免把整份记录误当成最终用户需要的单段文本。
|
||||
|
||||
我们先**epoch = [构造固定时区的零时刻](日时.自戳(秒=0, 区="Asia/Shanghai"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=[iso](access(`epoch`, "iso")))**。
|
||||
|
||||
我们先**u = [解析当前日期或 URL 输入](址.解析(内容="https://example.com/path?q=1"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=[host](access(`u`, "host")))**。
|
||||
随后我们**[显示当前步骤的结果](> print text=[query](access(`u`, "query")))**。
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — toml, html, base32
|
||||
description: Config TOML + HTML escape + base32 (Mid2 M8)
|
||||
import:
|
||||
toml: lib/toml.mq.md
|
||||
html: lib/html.mq.md
|
||||
enc: lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# Config and safe text without plugins
|
||||
|
||||
|
||||
Parse a TOML subset for tools, escape HTML before assembly, encode with base32.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **cfg = [Compute cfg](toml.parse(text="app = \"demo\"\n[server]\nport = 8080\n"))** for the next step.
|
||||
We now **[Display this step's result](> print text=[app](access(`cfg`, "app")))**.
|
||||
We first **srv = [server](access(`cfg`, "server"))** for the next step.
|
||||
We now **[Display this step's result](> print text=[port](access(`srv`, "port")))**.
|
||||
|
||||
We first **safe = [Compute safe](html.escape(text="<tag>"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`safe`)**.
|
||||
|
||||
We first **b = [Compute b](enc.base32_encode(text="ok"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`b`)**.
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 配置表、超文本、基32
|
||||
description: TOML 配置 + HTML 转义 + base32(Mid2 M8)
|
||||
导入:
|
||||
配置: lib/配置表.mq.md
|
||||
超: lib/超文本.mq.md
|
||||
编: lib/编码.mq.md
|
||||
---
|
||||
|
||||
# 无需插件的配置与安全字面
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
三个步骤处理三种文本边界:TOML 解析得到 app 字段的记录,HTML 转义把尖括号变成普通可展示文本,Base32 把 UTF-8 输入编码为另一种文本表示。它们彼此独立,不能把配置解析、页面布局和编码混成一个隐藏的字符串处理流程。
|
||||
|
||||
TOML 文本直接来自本页,读取真实配置文件时应先使用原生文件库;本例不会隐式寻找系统配置。HTML 转义适用于普通文本展示,不能代替 URL、脚本或样式上下文各自需要的处理,更不应因此拼接大量业务 HTML。Base32 只改变表示方法,不加密数据。所有结果都可继续传递给其他 Marqdo 函数,当前步骤不创建文件、不发送网络请求,也不需要外联解释器。
|
||||
|
||||
我们先**cfg = [解析显式提供的 TOML 配置](配置.解析(内容="app = \"演示\"\n"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=[app](access(`cfg`, "app")))**。
|
||||
|
||||
我们先**safe = [将尖括号转义为普通展示文本](超.转义(内容="<tag>"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=`safe`)**。
|
||||
|
||||
我们先**b = [把输入文本编码为 Base32](编.基32编码(内容="ok"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=`b`)**。
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Native directory trees, enumeration and file metadata
|
||||
import:
|
||||
fs: lib/fs.mq.md
|
||||
---
|
||||
|
||||
This complete demonstration uses native filesystem tools. Call main with fs.write and a disposable --fs-root. It returns actual metadata and relative paths after cleaning its own temporary directory.
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | Actual byte size, directory entry count and relative paths |
|
||||
|
||||
Create a unique temporary directory, then one child directory and one text file. Every write remains under the granted root, avoiding collisions with a pre-existing demo folder. Paths are built explicitly; no generated reader/writer or foreign process participates.
|
||||
|
||||
The content ok occupies two UTF-8 bytes. File size measures stored bytes rather than text character count. Enumeration returns relative paths for the child directory and file; counting those paths is another distinct observation. The example does not depend on operating-system enumeration order. Sort explicitly if a later workflow requires stable ordering.
|
||||
|
||||
Collect the real metadata and paths before removing this run's unique tree. Returned paths describe an observation, not still-live artifacts. A failure can retain its native diagnostic and this run's directory for caller inspection. Cleanup must stay scoped to the directory created by this invocation.
|
||||
|
||||
We **work = [Create a unique directory inside the granted root](fs.temp_dir(prefix="fs-tree-demo"))** and **child = work + "/sub"** and **note = work + "/readme.txt"**.
|
||||
We **[Create this run own child directory](fs.make_dirs(path=`child`))** and **[Write the exact UTF-8 example content](fs.write_text(path=`note`, text="ok"))**.
|
||||
We **metadata = [Read the actual file metadata](fs.stat(path=`note`))** and **paths = [Enumerate this run directory entries](fs.walk(path=`work`))** and **size = [Retain storage byte size](access(metadata, "size"))** and **entries = [Count the actual enumerated paths](len(`paths`))**.
|
||||
We **[Remove only this run unique directory tree](fs.remove_tree(path=`work`))** after collecting the observations.
|
||||
|
||||
`observed` =
|
||||
|
||||
| size | entries | paths |
|
||||
|---|---|---|
|
||||
| `size` | `entries` | `paths` |
|
||||
|
||||
After observing and cleaning this run we return *observed*.
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 原生目录树、遍历与文件状态
|
||||
import:
|
||||
文件: lib/文件.mq.md
|
||||
---
|
||||
|
||||
使用固有文件库完成整个演示。调用 main 时授予 fs.write,并指定独立的 --fs-root。函数返回实际元数据与相对路径列表,正常结束后清理自己的临时目录。
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | 真实文件字节数、目录条目数与相对路径列表 |
|
||||
|
||||
本轮先创建唯一临时目录,再在其中建立子目录和文本文件,避免固定的演示名称与已有目录冲突。创建和写入都受 --fs-root 约束,目录参数并不授予访问其他位置的权限。所有路径由当前流程明确构造,没有外部脚本代为读取或修改正文。
|
||||
|
||||
内容“好”占三个 UTF-8 字节,size 描述存储大小而不是字符数。遍历结果包含文件和子目录的相对路径,条目数与字符串长度也是不同的量。本例只观察枚举内容,不依赖操作系统给出的顺序;需要稳定排序时应继续组合表库。
|
||||
|
||||
实际观察值保存后删除本轮独有的临时树。返回的路径列表描述已经观察过的内容,不是仍然存在的文件句柄。中途失败保留原生诊断与可能留下的本轮目录,调用方可以检查后清理,不应递归删除与演示无关的用户目录。
|
||||
|
||||
先**work = [创建本轮独有的授权临时目录](文件.临时目录(前缀="文件树演示"))**和**child = work + "/子"**及**note = work + "/说明.txt"**。
|
||||
接着**[递归创建本轮子目录](文件.建目录树(路径=`child`))**,并**[写入一个明确的 UTF-8 字符](文件.写文本(路径=`note`, 内容="好"))**。
|
||||
观察时保存**metadata = [读取真实文件元数据](文件.状态(路径=`note`))**和**paths = [枚举本轮目录里的实际条目](文件.遍历(路径=`work`))**及**size = [保留存储字节数](access(metadata, "size"))**和**entries = [保留遍历条目数](长度(`paths`))**。
|
||||
最后**[只清理本轮独有的目录树](文件.删目录树(路径=`work`))**,再组织实际观察值。
|
||||
|
||||
`observed` =
|
||||
|
||||
| size | entries | paths |
|
||||
|---|---|---|
|
||||
| `size` | `entries` | `paths` |
|
||||
|
||||
完成观察与清理后,我们返回*observed*。
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — stats and log fields
|
||||
description: Thin mean/median/stdev + structured log fields (Mid2 M10)
|
||||
import:
|
||||
stats: lib/stats.mq.md
|
||||
log: lib/log.mq.md
|
||||
---
|
||||
|
||||
# Closing Mid2 sugar
|
||||
|
||||
|
||||
Light statistics and optional `fields=` on log lines — no remote sinks, no dataframes.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
`xs` =
|
||||
|
||||
| |
|
||||
|---|
|
||||
| 10 |
|
||||
| 20 |
|
||||
| 30 |
|
||||
|
||||
We first **m = [Compute m](stats.mean(list=`xs`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`m`)**.
|
||||
|
||||
`fld` =
|
||||
|
||||
| step | status |
|
||||
|------|--------|
|
||||
| done | ok |
|
||||
|
||||
We now **[Call log.info](> log.info text="mid2-m10" fields=`fld`)**.
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 统计与日志字段
|
||||
description: 薄均值/中位数/标准差 + 日志 fields(Mid2 M10)
|
||||
导入:
|
||||
统计: lib/统计.mq.md
|
||||
日志: lib/日志.mq.md
|
||||
---
|
||||
|
||||
# Mid2 收口糖
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
数值列表包含十、二十和三十,平均值应为二十。这里把数据写成一列表格,让读者能直接核对输入,而不是在外部解释器中再构造同一份列表。统计函数不修改原集合;需要中位数、标准差或空集合策略时,应继续阅读统计库对应函数的独立契约。
|
||||
|
||||
结构化日志同时携带消息与步骤、状态字段,用于后续过滤或诊断。日志输出不是函数的业务返回值,也不能作为已经完成某项发布或文件写入的证据。本例没有文件和网络操作;实际日志目的地与权限沿用日志库的运行环境规则。若后续任务依赖统计结果,就应直接传递 m 的数值,而不是重新解析打印文本或把最后一条日志当作成功标志。
|
||||
|
||||
`xs` =
|
||||
|
||||
| |
|
||||
|---|
|
||||
| 10 |
|
||||
| 20 |
|
||||
| 30 |
|
||||
|
||||
我们先**m = [计算列表的算术平均值](统计.均值(列表=`xs`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=`m`)**。
|
||||
|
||||
`fld` =
|
||||
|
||||
| 步骤 | 状态 |
|
||||
|------|------|
|
||||
| 完成 | ok |
|
||||
|
||||
随后我们**[执行 日志.信息](> 日志.信息 内容="mid2-m10" 字段=`fld`)**。
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: AI 原生闭环(契约 + MLSP)
|
||||
description: 渐进式契约、结构化诊断与面向 AI 的 Marqdo 语言服务
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
里程碑(v1.1.0):AI 原生闭环——让 AI 不仅能写 Marqdo,还能验证 Marqdo。
|
||||
|
||||
三件套。核心表面守卫(`doc/design/core-surface.md`)钉住 19 个核心构造,任一侧(清单 / 文档 / 金样)单边改动,CI 必红。渐进式契约是可选的 `参数` / `返回` / `字段` 表,直接嵌在叙述里,四边界校验:调用实参、返回值、表绑定、键访问。MLSP for AI(`marqdo mlsp`)是行分隔 JSON 的语言服务,AI 按需查询语法,而不是背诵整部语法。
|
||||
|
||||
静态契约检查:
|
||||
|
||||
```bash
|
||||
marqdo check tests/contracts/ok_contract.mq.md
|
||||
```
|
||||
|
||||
结构化诊断——错误即数据:
|
||||
|
||||
```bash
|
||||
marqdo run tests/structure/hello.mq.md --json
|
||||
```
|
||||
|
||||
按需查询语法(MLSP):
|
||||
|
||||
```bash
|
||||
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
|
||||
```
|
||||
|
||||
MLSP 方法:`locate`(查符号 / 构造卡片)、`syntax`(戒律原文 + 样例 + 文档锚点)、`validate`(结构化诊断)、`repair_targets`(有界靶点)、`repair_apply`(有界行编辑,越界必拒)、`schema`(单元契约)。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> print text="契约是可选的:不写契约表,文件保持全动态。")**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> print text="诊断自带 code / severity / suggestion / doc_anchor / doc_quote。")**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> print text="MLSP 语法卡片内嵌戒律原文与样例,AI 无需预学语法。")**。
|
||||
|
||||
验证结果见:`doc/roadmap/perf-validation-report-2026-09-23.md`。
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: AI-native loop (contracts + MLSP)
|
||||
description: Progressive contracts, structured diagnostics, and the Marqdo Language Server for AI
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Milestone (v1.1.0): the AI-native loop — so an AI can verify Marqdo, not just write it.
|
||||
|
||||
Three pieces. A core surface guard (`doc/design/core-surface.md`) pins the 19 core constructs, so a single-sided change (list / doc / golden sample) turns CI red. Progressive contracts are optional `参数` / `返回` / `字段` tables embedded in the narrative, checked at four boundaries: call argument, return, table bind, key access. MLSP for AI (`marqdo mlsp`) is a line-delimited JSON language service; the AI queries syntax on demand instead of memorizing the whole grammar.
|
||||
|
||||
Static contract check:
|
||||
|
||||
```bash
|
||||
marqdo check tests/contracts/ok_contract.mq.md
|
||||
```
|
||||
|
||||
Structured diagnostics — errors as data:
|
||||
|
||||
```bash
|
||||
marqdo run tests/structure/hello.mq.md --json
|
||||
```
|
||||
|
||||
Query syntax on demand (MLSP):
|
||||
|
||||
```bash
|
||||
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
|
||||
```
|
||||
|
||||
MLSP methods: `locate` (find a symbol / construct card), `syntax` (rule text + sample + doc anchor), `validate` (structured diagnostics), `repair_targets` (bounded span), `repair_apply` (bounded line edits, out-of-scope refused), `schema` (contract of one unit).
|
||||
|
||||
We now **[Display this step's result](> print text="Contracts are optional: with no contract table, a file stays fully dynamic.")**.
|
||||
|
||||
We now **[Display this step's result](> print text="Diagnostics carry code, severity, suggestion, doc_anchor and doc_quote.")**.
|
||||
|
||||
We now **[Display this step's result](> print text="MLSP syntax cards embed the rule text and a sample, so AI need not pre-learn the grammar.")**.
|
||||
|
||||
See validation results: `doc/roadmap/perf-validation-report-2026-09-23.md`.
|
||||
@@ -1,116 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Native analysis and an explicit Intl formatting boundary
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
table: lib/table.mq.md
|
||||
result: lib/result.mq.md
|
||||
native: ../../examples/foreign-native-report/index.mq.md
|
||||
---
|
||||
|
||||
This page keeps order analysis in Marqdo and uses Node Intl only for locale-aware
|
||||
currency formatting. Read [the actual native report tools](../../examples/foreign-native-report/index.mq.md)
|
||||
for their independently callable input and return contracts. That single module
|
||||
contains grouping, population statistics and the bounded persistent formatter.
|
||||
|
||||
Call this page's main with process.exec for a full workflow, or call analyze_orders
|
||||
in that module with no effects for native analysis alone. View evaluates the same
|
||||
cells with shared state and isolated kernels. No Python interpreter is needed.
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | View-session plan plus the native report and checked localized formatting |
|
||||
|
||||
This complete page uses six ordinary orders: their native total is 950, count
|
||||
is six, and the four regional rows retain count, total, mean and normalized span.
|
||||
The pure analysis is independently callable in the linked module. Formatting is a separate
|
||||
capability with an explicit process.exec grant and an installed Node runtime.
|
||||
The successful return contains report and formatting alongside the view-session
|
||||
plan; it contains no live kernel handle and can be returned by marqdo call.
|
||||
|
||||
The view gets the same native report copied into two named kernels. Its cells
|
||||
perform presentation rather than reimplementing native grouping or arithmetic.
|
||||
Run All first initializes the formatter in the analysis kernel, then a second
|
||||
cell reuses it. The review kernel receives its own report copy and formatter.
|
||||
This demonstrates both shared state and kernel isolation. Running the dependent
|
||||
formatting cell before its initializer should show the real missing-state error.
|
||||
|
||||
Static View export evaluates those same cells and embeds actual stdout.
|
||||
Interactive View retains their kernels for later runs. The low-level formatter
|
||||
used to check the public return is opened and closed separately, so it cannot
|
||||
secretly supply state to the view kernels. No stdin, notebook command, generated
|
||||
file-reader program or package installation is hidden in this example.
|
||||
If Node or formatting fails, the page returns that failure before declaring a
|
||||
ready view. Native-only consumers can still call analyze_orders with no effects.
|
||||
The table cells below are data, while the three bound node fences are explicit
|
||||
foreign code. The distinction is visible without translating a Python workflow
|
||||
into another ad hoc command sequence.
|
||||
|
||||
`orders` =
|
||||
|
||||
| @ | region | amount |
|
||||
|---|---|---|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
We **report = [Perform all analysis in Marqdo](native.analyze_orders(orders=`orders`))** and **formatted = [Use the genuine external formatting boundary](native.format_summary(report=`report`))**.
|
||||
1. not access(`formatted`, "ok")
|
||||
Return *formatted* before declaring an executable view ready.
|
||||
|
||||
`kernels` =
|
||||
|
||||
| @ | 名称 | 语言 |
|
||||
|---|---|---|
|
||||
| 1 | 分析 | node |
|
||||
| 2 | 复核 | node |
|
||||
|
||||
`cells` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|---|---|
|
||||
| 1 | 计算 | 分析 |
|
||||
| 2 | 格式化 | 分析 |
|
||||
| 3 | 复核 | 复核 |
|
||||
|
||||
`initial` =
|
||||
|
||||
| @ | 内核 | 名称 | 值 |
|
||||
|---|---|---|---|
|
||||
| 1 | 分析 | report | `report` |
|
||||
| 2 | 复核 | report | `report` |
|
||||
|
||||
We **会话 = [Declare the view with native values and explicit kernels](foreign.session(kernels=`kernels`, cells=`cells`, values=`initial`))**.
|
||||
|
||||
`计算` =
|
||||
```node
|
||||
var money = new Intl.NumberFormat("en-US", {style:"currency", currency:"CNY"});
|
||||
console.log(JSON.stringify(report));
|
||||
```
|
||||
|
||||
`格式化` =
|
||||
```node
|
||||
console.log(money.format(report.total));
|
||||
console.log(money.format(report.average));
|
||||
```
|
||||
|
||||
`复核` =
|
||||
```node
|
||||
var reviewMoney = new Intl.NumberFormat("en-US", {style:"currency", currency:"CNY"});
|
||||
console.log(JSON.stringify({count:report.count, total:reviewMoney.format(report.total)}));
|
||||
```
|
||||
|
||||
We **formatting = [Retain the checked persistent-kernel result](access(formatted, "value"))**.
|
||||
|
||||
`evidence` =
|
||||
|
||||
| report | formatting |
|
||||
|---|---|
|
||||
| `report` | `formatting` |
|
||||
|
||||
Return *[The executable view plan with native analysis evidence](table.merge(a=`会话`, b=`evidence`))*.
|
||||
@@ -1,97 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 原生分析与明确的 Intl 格式化边界
|
||||
import:
|
||||
外联: lib/外联.mq.md
|
||||
表: lib/table.mq.md
|
||||
例程: ../../examples/foreign-native-report/index.mq.md
|
||||
---
|
||||
|
||||
先用固有能力,外联只补真实的能力缺口。本页复用 [原生报告例程](../../examples/foreign-native-report/index.mq.md),让统计在 Marqdo 中完成,再通过已支持的 Node 持久内核使用 Intl。阅读例程的源码即可找到可以独立调用的参数、返回值与失败约束。
|
||||
|
||||
在仓库根目录调用 marqdo call public/features/19-外联视图单元.mq.md main --effects process.exec --fs-root . --json 可以获得真实报告与视图计划。使用 view 导出同一份源码即可运行下面声明的单元。这里采用函数标题 main,便于作为工具直接调用;不需要 Python 解释器或另一套笔记本入口。
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | 包含 report、formatting 及内核/单元/初始值的视图计划;失败时返回实际 Result |
|
||||
|
||||
格式化结果中的数字会显示为 950.00 与 158.33,货币标志由区域设置决定;原生 report 保留未格式化的数值。
|
||||
|
||||
本页的六笔订单全部由 Marqdo 固有能力处理,得到合计 950、数量六、四个区域的订单数、合计、均值和总体标准化跨度。分组、排序、统计与数值运算都不需要外部脚本;真正交给 Node 的只有 Intl 本地化货币格式。直接调用本页 main 需要 process.exec,Node 应预先安装。成功返回的计划包含 report 原始报告和 formatting 展示结果,调用者可以继续验证具体数值。
|
||||
|
||||
共享例程有独立的参数及返回表,区域键和金额键都由调用者明确指定,因此中文字段不需要重命名成另一套 JSON 拼接语言。本页和英文页共同调用一份原生算法,避免两个版本逐渐出现不同的统计规则。纯数据分析可以直接调用例程的 analyze_orders,不需要任何进程授权;空输入、单元素区域与相同金额的区域也有清楚的定义。金额只是示例数值,展示的两位小数由 Intl 决定,不宣称是金融十进制定点模型。
|
||||
|
||||
视图的分析内核先输出已经算好的报告,并创建本地化格式器;同一内核中的第二个单元继续使用这个格式器。因此 Run All 的顺序是明确的执行依赖,直接先运行格式化单元应展示真实的未初始化状态。复核单元使用另一份内核和自己的格式器,体现状态隔离。两个内核收到的是报告的数据拷贝,谁都不会重新实现一份分组算法,也不会修改 Marqdo 的源订单。
|
||||
|
||||
用于验证工具返回值的低层格式化例程单独创建并关闭了一个持久内核:第一次求值创建格式器,第二次复用状态。它检查每次求值的 ok,遇到可恢复错误时关闭仍存活的内核,再返回真实诊断。用于视图的会话随后才被声明;工具验证的内核不能暗中给视图提供状态。视图的静态导出与交互模式运行同一批单元,输出来自实际执行,不用预写的通过文字冒充结果。
|
||||
|
||||
正文先交代数据来源和边界,再把调用放入相应的句子。下面的订单、内核、单元和初始值都是普通表格;三段绑定的 node 围栏才是明确外联的代码。整个操作不要求向终端输入 JSON,也不生成文件读取器。若解释器不可用或格式化失败,会在创建可用视图之前把失败交给调用者。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 区域 | 金额 |
|
||||
|---|---|---|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
我们先**报告 = [使用固有库完成分组和总体统计](例程.analyze_orders(orders=`订单`, region_key="区域", amount_key="金额"))**,再**格式结果 = [把真正缺失的本地化展示交给 Intl](例程.format_summary(report=`报告`, locale="zh-CN"))**。
|
||||
1. not access(`格式结果`, "ok")
|
||||
返回*格式结果*,保留外联解释器或格式化的真实失败。
|
||||
|
||||
`内核` =
|
||||
|
||||
| @ | 名称 | 语言 |
|
||||
|---|---|---|
|
||||
| 1 | 分析 | node |
|
||||
| 2 | 复核 | node |
|
||||
|
||||
`单元` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|---|---|
|
||||
| 1 | 计算 | 分析 |
|
||||
| 2 | 格式化 | 分析 |
|
||||
| 3 | 复核 | 复核 |
|
||||
|
||||
`初始值` =
|
||||
|
||||
| @ | 内核 | 名称 | 值 |
|
||||
|---|---|---|---|
|
||||
| 1 | 分析 | report | `报告` |
|
||||
| 2 | 复核 | report | `报告` |
|
||||
|
||||
接着**会话 = [用普通表格声明显式的视图会话](外联.会话(内核表=`内核`, 单元表=`单元`, 值表=`初始值`))**,让两份内核获得同一个原生报告的独立 JSON 拷贝。
|
||||
|
||||
`计算` =
|
||||
```node
|
||||
var money = new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"});
|
||||
console.log(JSON.stringify(report));
|
||||
```
|
||||
|
||||
`格式化` =
|
||||
```node
|
||||
console.log(money.format(report.total));
|
||||
console.log(money.format(report.average));
|
||||
```
|
||||
|
||||
`复核` =
|
||||
```node
|
||||
var reviewMoney = new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"});
|
||||
console.log(JSON.stringify({count:report.count, total:reviewMoney.format(report.total)}));
|
||||
```
|
||||
|
||||
我们**展示 = [保留已经检查过的持久格式化结果](access(格式结果, "value"))**,把数据与展示来源一并交给调用者。
|
||||
|
||||
`依据` =
|
||||
|
||||
| report | formatting |
|
||||
|---|---|
|
||||
| `报告` | `展示` |
|
||||
|
||||
所有值准备好后返回*[带原生分析依据的可执行视图计划](表.merge(a=`会话`, b=`依据`))*。
|
||||
@@ -1,140 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 代码即文档,文档即知识 — OKF 与 EKC
|
||||
description: Marqdo 如何以一份可执行源为唯一权威,把它投影成 OKF 风格知识与 Engineering Knowledge Compiler 制品
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
Marqdo 的宪法是「代码即文档,文档即知识库」。`.mq.md` 不是程序截图:它同时是可读源码、可执行单元和知识页。
|
||||
|
||||
这个承诺只有在知识始终从源派生时才成立。OKF 提供可移植知识包的形态;EKC 提供工程化投影。二者都不成为第二份权威。
|
||||
|
||||
---
|
||||
|
||||
OKF 的形,Marqdo 的义。
|
||||
|
||||
OKF(Open Knowledge Format)用 Markdown + YAML frontmatter 表示知识:一页一概念、路径即身份、链接成图、强制面刻意保持很小。Marqdo 借用这个形态,但正文是可执行语法。
|
||||
|
||||
因此概念页可以直接指向证明它的文件:
|
||||
|
||||
```yaml
|
||||
type: Capability
|
||||
title: 持久外联内核
|
||||
description: 向显式声明的本地内核传递原生数据并保留状态
|
||||
resource: public/features/19-外联视图单元.mq.md
|
||||
status: stable
|
||||
verified:
|
||||
by: marqdo-knowledge/verify
|
||||
tags:
|
||||
- foreign
|
||||
- view-cells
|
||||
```
|
||||
|
||||
同一页可以在编辑器里读、从 catalog 链接、被 Agent 查询,也可以直接运行。未知字段保留;未知类型降级为可读正文。概念页不是源文件的复制品。
|
||||
|
||||
---
|
||||
|
||||
哪些是生成的,哪些不是。
|
||||
|
||||
| 层 | 作者 | 职责 |
|
||||
|---|---|---|
|
||||
| 源 | 人或编码 Agent | .mq.md;唯一语义权威 |
|
||||
| 目录包 | marqdo catalog | 模块、符号、能力与图投影 |
|
||||
| 任务知识 | plan 晋升 | 任务、技能与可执行资源包 |
|
||||
| 静态站 | marqdo view output | 人读 HTML,永远不是权威 |
|
||||
|
||||
生成物带 GENERATED 标记,可以删除重建;没有它们源树仍能运行。Catalog 是索引,不是语言特性。
|
||||
|
||||
---
|
||||
|
||||
EKC:Engineering Knowledge Compiler。
|
||||
|
||||
EKC 把仓库投影成工程知识系统,并在 Agent 写新代码前提供 preflight:
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► catalog L0–L4
|
||||
├─ graph
|
||||
├─ context pack
|
||||
└─ Agent preflight
|
||||
```
|
||||
|
||||
| 层 | 知识 | 例子 |
|
||||
|---|---|---|
|
||||
| L0 Repository | 语言、规模、根目录 | 仓库总览 |
|
||||
| L1 Module | imports、exports、职责 | 外联内核模块 |
|
||||
| L2 Symbol | 签名、调用、指纹 | 外部源码中的函数 |
|
||||
| L3 Capability | 工程能做什么 | 运行持久外联内核 |
|
||||
| L4 Knowledge | 决策、约束、失败 | 为什么状态桥必须显式 |
|
||||
|
||||
图记录 implements、uses、depends_on、tested_by、documented_by、constrained_by、decided_by、supersedes、conflicts_with、deprecated_by 等关系。Agent 先沿图发现已有能力,而不是重新造轮子。
|
||||
|
||||
---
|
||||
|
||||
Engineering First Information:先发现,再创建。
|
||||
|
||||
复用协议是硬顺序:
|
||||
|
||||
```text
|
||||
REUSE → ADAPT → CREATE
|
||||
```
|
||||
|
||||
preflight 可以在实现开始前返回已有能力、API、约束、决策与失败经验。知识图缺失时返回明确的 missing_knowledge,而不是静默编造。
|
||||
|
||||
五条原则:
|
||||
|
||||
| # | 原则 |
|
||||
|---|---|
|
||||
| 1 | Discover before Create |
|
||||
| 2 | Reuse before Adapt |
|
||||
| 3 | Adapt before Duplicate |
|
||||
| 4 | Verify before Promote |
|
||||
| 5 | Code changes update knowledge |
|
||||
|
||||
---
|
||||
|
||||
命令。
|
||||
|
||||
```bash
|
||||
# 把仓库投影成 catalog + EKC 制品
|
||||
marqdo catalog .
|
||||
|
||||
# 写代码前先问:已经有了什么?
|
||||
marqdo knowledge preflight "增加一个持久外联内核"
|
||||
marqdo find "外联 会话"
|
||||
marqdo reuse "实现 JSON 并行扇出"
|
||||
|
||||
# 看一次修改会影响什么
|
||||
marqdo impact public/features/19-外联视图单元.mq.md
|
||||
|
||||
# 校验知识投影
|
||||
marqdo knowledge verify
|
||||
```
|
||||
|
||||
`marqdo catalog` 保留人读的 `index.md` 与模块页;EKC 在 `.marqdo/` 下增加 L0–L4。两者都从同一棵源树生成。
|
||||
|
||||
---
|
||||
|
||||
每个声称的能力都必须有可执行资源。
|
||||
|
||||
一个知识页说“这个工程能分析订单”,就必须指向一个真正能跑的 `.mq.md` 资源。这是 OKF 形态的笔记与可执行知识系统的区别。
|
||||
|
||||
外联示例先用 Marqdo 固有能力分析订单,再把本地化展示交给 Node Intl。显式导入指向共享的可调用报表手册,页面本身声明实际的视图内核、原生值与单元。验收仍要检查逐单元的真实结果,不能把一份可序列化计划当作单元已经运行成功的证明。
|
||||
|
||||
---
|
||||
|
||||
继续阅读。
|
||||
|
||||
OKF 设计:[OKF 设计](../../doc/design/okf.md)
|
||||
|
||||
Engineering Knowledge Compiler:[Engineering Knowledge Compiler](../../doc/design/engineering-knowledge.md)
|
||||
|
||||
Catalog CLI:[Catalog CLI](../../doc/design/catalog-cli.md)
|
||||
|
||||
OKF 与 Marqdo 调研:[OKF 与 Marqdo 调研](../../doc/research/okf-and-marqdo.md)
|
||||
|
||||
外联 view 单元示例:[外联 view 单元示例](19-外联视图单元.mq.md)
|
||||
@@ -1,140 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Code as documentation, documentation as knowledge — OKF and EKC
|
||||
description: How Marqdo keeps one executable source of truth while projecting it into OKF-style knowledge and Engineering Knowledge Compiler artifacts
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Marqdo's constitution is code as documentation and documentation as knowledge. A `.mq.md` file is not a screenshot of a program: it is the readable source, the executable unit and the knowledge page at the same time.
|
||||
|
||||
That claim matters only if the knowledge stays derived from the source. OKF gives us the shape of a portable knowledge bundle; EKC gives us the engineering projection. Neither becomes a second source of truth.
|
||||
|
||||
---
|
||||
|
||||
OKF shape, Marqdo meaning.
|
||||
|
||||
OKF (Open Knowledge Format) describes knowledge as Markdown pages with YAML frontmatter: one concept per page, path as identity, links as graph, a deliberately small required surface. Marqdo borrows that shape, but its body is executable.
|
||||
|
||||
A concept page can therefore point at the exact file that proves it:
|
||||
|
||||
```yaml
|
||||
type: Capability
|
||||
title: Persistent foreign kernels
|
||||
description: Run an explicitly declared local kernel with native data
|
||||
resource: public/features/19-foreign-view-cells.mq.md
|
||||
status: stable
|
||||
verified:
|
||||
by: marqdo-knowledge/verify
|
||||
tags:
|
||||
- foreign
|
||||
- view-cells
|
||||
```
|
||||
|
||||
The same page can be opened in an editor, linked from a catalog, queried by an agent, and executed. Unknown fields are preserved; unknown types degrade to readable prose. The page is a concept, not a copy of one.
|
||||
|
||||
---
|
||||
|
||||
What is generated, and what is not.
|
||||
|
||||
| Layer | Author | Role |
|
||||
|---|---|---|
|
||||
| Source | person or coding agent | .mq.md; the only semantic authority |
|
||||
| Catalog | marqdo catalog | module, symbol, capability and graph projection |
|
||||
| Task knowledge | plan promotion | task, skill and executable resource bundle |
|
||||
| Static site | marqdo view output | human-readable HTML, never an authority |
|
||||
|
||||
Generated artifacts are marked GENERATED and can be deleted and rebuilt. The source tree still runs without them. A catalog is an index, not a language feature.
|
||||
|
||||
---
|
||||
|
||||
EKC: the Engineering Knowledge Compiler.
|
||||
|
||||
EKC projects the repository into an engineering knowledge system, then exposes it through a preflight before an agent writes new code:
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► catalog L0–L4
|
||||
├─ graph
|
||||
├─ context pack
|
||||
└─ Agent preflight
|
||||
```
|
||||
|
||||
| Layer | Knowledge | Example |
|
||||
|---|---|---|
|
||||
| L0 Repository | language, size, roots | repository summary |
|
||||
| L1 Module | imports, exports, responsibility | a foreign kernel module |
|
||||
| L2 Symbol | signature, calls, fingerprint | a function in external source code |
|
||||
| L3 Capability | what the project can do | run a persistent foreign kernel |
|
||||
| L4 Knowledge | decisions, constraints, failures | why the bridge is explicit |
|
||||
|
||||
The graph records relations such as implements, uses, depends_on, tested_by, documented_by, constrained_by, decided_by, supersedes, conflicts_with and deprecated_by. That graph is how an agent discovers existing capability before inventing a duplicate.
|
||||
|
||||
---
|
||||
|
||||
Engineering First Information: discover before create.
|
||||
|
||||
The reuse protocol is a hard order:
|
||||
|
||||
```text
|
||||
REUSE → ADAPT → CREATE
|
||||
```
|
||||
|
||||
A preflight can return existing capabilities, APIs, constraints, decisions and failure notes before a new implementation starts. If the knowledge graph is missing, the result is an explicit missing_knowledge state, not a silent fabrication.
|
||||
|
||||
The five principles are:
|
||||
|
||||
| # | Principle |
|
||||
|---|---|
|
||||
| 1 | Discover before Create |
|
||||
| 2 | Reuse before Adapt |
|
||||
| 3 | Adapt before Duplicate |
|
||||
| 4 | Verify before Promote |
|
||||
| 5 | Code changes update knowledge |
|
||||
|
||||
---
|
||||
|
||||
The commands.
|
||||
|
||||
```bash
|
||||
# Project the repository into catalog + EKC artifacts
|
||||
marqdo catalog .
|
||||
|
||||
# Ask what already exists before writing code
|
||||
marqdo knowledge preflight "add a persistent foreign kernel"
|
||||
marqdo find "foreign session"
|
||||
marqdo reuse "implement JSON fan-out"
|
||||
|
||||
# See what a change would touch
|
||||
marqdo impact public/features/19-foreign-view-cells.mq.md
|
||||
|
||||
# Validate the knowledge projection
|
||||
marqdo knowledge verify
|
||||
```
|
||||
|
||||
`marqdo catalog` keeps the human-readable `index.md` and module pages; EKC adds L0–L4 files under `.marqdo/`. Both are generated from the same source tree.
|
||||
|
||||
---
|
||||
|
||||
Every claimed capability has an executable resource.
|
||||
|
||||
A knowledge page that says “this project can analyze orders” must point to a `.mq.md` resource that actually runs. That is the difference between an OKF-shaped note and an executable knowledge system.
|
||||
|
||||
The foreign example computes its order report in native Marqdo and uses Node Intl for locale-aware presentation. Explicit imports point to the shared callable report handbook, while the page declares the actual view kernels, values and cells. Inspect the real per-cell results; a serialized plan alone does not establish that its cells ran successfully.
|
||||
|
||||
---
|
||||
|
||||
Read more.
|
||||
|
||||
OKF design: [OKF design](../../doc/design/okf.md)
|
||||
|
||||
Engineering Knowledge Compiler: [Engineering Knowledge Compiler](../../doc/design/engineering-knowledge.md)
|
||||
|
||||
Catalog CLI: [Catalog CLI](../../doc/design/catalog-cli.md)
|
||||
|
||||
OKF and Marqdo research: [OKF and Marqdo research](../../doc/research/okf-and-marqdo.md)
|
||||
|
||||
Foreign view-cells example: [Foreign view-cells example](19-foreign-view-cells.mq.md)
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Persist an actual formatting result through native writeback
|
||||
import:
|
||||
guide: ../../doc/library-development.mq.md
|
||||
formatter: ../../examples/foreign-native-report/index.mq.md
|
||||
writeback: lib/writeback.mq.md
|
||||
result: lib/result.mq.md
|
||||
---
|
||||
|
||||
The source remains the manual for this file operation. Its callable main computes
|
||||
native data, crosses a genuine formatting boundary, checks the result and records
|
||||
only the successful value. Invoke with process.exec,fs.write and --fs-root .;
|
||||
static View uses the same source and embeds its actual observed output.
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | Result with the actual string recorded in this source's total slot |
|
||||
|
||||
A static View snapshot embeds executed output in HTML. Explicit writeback
|
||||
instead keeps a selected value in this source file's named slot. A caller should
|
||||
choose that file effect deliberately: this main needs process.exec and fs.write,
|
||||
with --fs-root pointing at the repository. Reading the page alone does not write.
|
||||
|
||||
The amount is computed by the native programming guide, then the shared example
|
||||
uses Node Intl only for locale-aware currency formatting. Its persistent kernel
|
||||
is closed before this page receives the result. No Python process, foreign file
|
||||
writer or duplicated arithmetic participates. The exact returned string is then
|
||||
passed to lib/writeback, so the file operation remains a Marqdo capability.
|
||||
|
||||
The total slot below is actual recorded output. Repeated execution replaces that
|
||||
same key rather than appending another slot. An unavailable interpreter or failed
|
||||
formatting returns before the write; native write-policy or IO faults retain
|
||||
their diagnostics. Writeback persists this selected ordinary value, not a live
|
||||
kernel or arbitrary process memory. Review source changes with the repository's
|
||||
normal diff workflow. For published docs use a static snapshot unless a living
|
||||
auditable source result is intended, as it explicitly is in this demonstration.
|
||||
|
||||
We **amount = [Compute the native amount](guide.计算金额(单价=190, 数量=5))**.
|
||||
|
||||
`report` =
|
||||
|
||||
| total | average |
|
||||
|---|---|
|
||||
| `amount` | `amount` |
|
||||
|
||||
We **formatted = [Use only the actual Intl presentation gap](formatter.format_summary(report=`report`))**.
|
||||
1. not access(`formatted`, "ok")
|
||||
Return *formatted* before writing a result slot.
|
||||
We **text = [Select the actual formatter output](access(access(formatted, "value"), "total"))**.
|
||||
We **written = [Persist this actual output through Marqdo's native writeback](writeback.record(value=`text`, key="total"))**.
|
||||
<!-- marqdo-out total
|
||||
CN¥950.00
|
||||
-->
|
||||
|
||||
After the explicit native file operation, return *[The persisted formatted value](result.ok(value=`text`))*.
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 用固有写回保存真实的格式化结果
|
||||
import:
|
||||
指南: ../../doc/library-development.mq.md
|
||||
例程: ../../examples/foreign-native-report/index.mq.md
|
||||
写回: lib/writeback.mq.md
|
||||
结果: lib/result.mq.md
|
||||
---
|
||||
|
||||
调用 main 需要 process.exec,fs.write,并将 --fs-root 指向仓库根目录。这是本页明确声明的文件修改,普通阅读不会写文件。静态 View 与可调用函数使用同一份源码,输出来自实际执行。
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | Result:保存到本页 total 槽位的实际文本 |
|
||||
|
||||
静态快照把执行输出嵌入 HTML;显式写回则把选定结果保存在源码的命名槽位里。本页正是需要后者的活文档示例,调用者应先知道会修改本页,再授予 fs.write。写回后的值可以在普通 Markdown 源码和差异中审阅,不依赖仍存活的外部进程。
|
||||
|
||||
金额由原生开发指南计算,随后共享例程只调用 Node Intl 完成固有库尚未提供的本地化货币展示。例程检查每次求值并关闭其持久内核,调用者得到的已经是普通文本。没有 Python 编排,也没有外部文件写入器;保存动作继续使用 Marqdo 的 writeback。示例的金额为 950,当前区域设置下的文本为 ¥950.00,真实输出会成为下面的 total 槽位内容。
|
||||
|
||||
再次执行替换同一个键,不重复添加槽位。若解释器不可用或格式化失败,在写文件之前就返回真实失败;固有文件策略或 IO 错误也保留诊断。这里持久化的是已经选定的文本,不保存任意内核内存,也不能根据它重建活资源句柄。完成后可用正常的仓库差异审阅流程检查变更,再决定是否随文档提交。
|
||||
|
||||
面向读者的发布页面通常选择静态快照;明确需要在源码中保存最新运行结果的审计文档才使用写回。两者可以共存,但静态导出如果执行了本页,仍会尊重这个显式写回操作。权限不会因为文档外观而被隐式扩张,依赖步骤也不能在失败后继续伪造结果。
|
||||
|
||||
先**金额 = [计算需要展示的原生金额](指南.计算金额(单价=190, 数量=5))**.
|
||||
|
||||
`report` =
|
||||
|
||||
| total | average |
|
||||
|---|---|
|
||||
| `金额` | `金额` |
|
||||
|
||||
再**格式结果 = [只把本地化展示交给 Intl](例程.format_summary(report=`report`, locale="zh-CN"))**。
|
||||
1. not access(`格式结果`, "ok")
|
||||
返回*格式结果*,失败时不进入文件写回。
|
||||
我们**正文 = [读取实际格式化文本](access(access(格式结果, "value"), "total"))**。
|
||||
随后**写入 = [使用固有写回能力保存真实文本](写回.record(value=`正文`, key="total"))**。
|
||||
<!-- marqdo-out total
|
||||
¥950.00
|
||||
-->
|
||||
|
||||
写回完成后返回*[已经保存的格式化文本](结果.ok(value=`正文`))*。
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Call one function: the same document is the tool
|
||||
description: v2.2.0 marqdo call runs a function inside any .mq.md. The explanation, the implementation and the call are one page.
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
v2.2.0 adds one command: `marqdo call`. It adds no Markdown marker and no skill system. An ordinary .mq.md file is already a document, a piece of knowledge and a program. What was missing is a way to call one of its functions from outside.
|
||||
|
||||
The usual command runs the whole file. Functions inside it run only when the entry calls them. Trying one calculation meant writing an entry, a print and a check. The smallest unit you can execute is now a function.
|
||||
|
||||
```text
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
Standard output is 5. `--json` is for programs and agents: success carries the result, failure carries a diagnostic code, and the process exits non-zero. `--backend tree` and `--backend bytecode` both run that function. Another entry in the file is not used as a fallback.
|
||||
|
||||
The second half of this page is itself a calculator. This command calls this page:
|
||||
|
||||
```text
|
||||
marqdo call public/features/22-call.mq.md calculator.add a=2 b=3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
The change is how the file is used.
|
||||
|
||||
A person reads the sentences next to the function and sees what add computes. The compiler reads the same markers and checks parameters and the return. A developer composes the function into another program. A test passes inputs to this function and looks at the output, without a wrapper whose only job is to print. An agent reads what the function is for and runs the implementation that is already there, instead of reading the page and rewriting it.
|
||||
|
||||
Those four uses are one call. Knowledge becomes a tool because knowledge can already run, now at function scope. The file does not need a special name, and it does not need to declare itself a skill.
|
||||
|
||||
---
|
||||
|
||||
The command keeps a boundary.
|
||||
|
||||
An external call defaults to a pure function. Writing files, starting a process, using the network or loading a plugin is refused before the function runs. Pass `--effects plugin` when the tool needs an ABI plugin (for example `ext/quantum`). Session bindings use `--session` and `--toget name` (or trailing `toget name`); later calls may pass `$name`. Nested sub-tools use a dotted path such as `outer.helper`. An instance method needs its receiver; this command does not invent one.
|
||||
|
||||
The function must resolve to exactly one declaration. No match, or one short name that hits two functions, is a structured error. The command does not pick the first hit. Arguments bind through the signature and contract that the function already has. Missing, unknown and ill-typed arguments are diagnostics.
|
||||
|
||||
After editing a function, call it again with the inputs that failed. A passing check is a reason to keep the edit. A test does not prove every input. It gives the edit a check that can be repeated.
|
||||
|
||||
# calculator
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | Object/type namespace for the child functions below; call the intended child directly |
|
||||
|
||||
This is an ordinary Marqdo document.
|
||||
|
||||
It holds a little reusable arithmetic.
|
||||
|
||||
## add
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| a | any | required | Left operand supplied to this calculation |
|
||||
| b | any | required | Right operand supplied to this calculation |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | The value explicitly returned below; conditional returns follow the selected branch |
|
||||
|
||||
Add the numbers `a` and `b`.
|
||||
|
||||
After these steps, return *[result]((`a` + `b`))*.
|
||||
|
||||
## multiply
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| a | any | required | Left operand supplied to this calculation |
|
||||
| b | any | required | Right operand supplied to this calculation |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | The value explicitly returned below; conditional returns follow the selected branch |
|
||||
|
||||
Multiply the numbers `a` and `b`.
|
||||
|
||||
After these steps, return *[result]((`a` * `b`))*.
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 函数级调用:同一份文档成为工具
|
||||
description: v2.2.0 的 marqdo call 让任意 .mq.md 里的函数可以带参数执行。说明、实现和调用是同一页。
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
v2.2.0 增加一条命令:`marqdo call`。它不新增 Markdown 标记,也不另建一套技能系统。一个普通的 .mq.md 本来就是文档、知识和程序。缺的是从外部直接调用其中某个函数。
|
||||
|
||||
以前日常用法是运行整份文件。入口对象跑完,里面的函数要等文件自己去调用。要试验一个计算,往往得再写入口、打印和检查。现在最小可执行单位是函数。
|
||||
|
||||
```text
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
标准输出是 5。`--json` 给程序和 Agent 读:成功时是带结果的对象,失败时是带诊断码的对象,退出码非 0。`--backend tree` 与 `--backend bytecode` 执行同一个函数。文件里即使还有别的入口,也不会改去跑那个入口。
|
||||
|
||||
本页后半本身就是一份计算器。下面这条命令调用的就是这一页:
|
||||
|
||||
```text
|
||||
marqdo call public/features/22-函数调用.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
它解决的是使用方式,不是再写一份说明书。
|
||||
|
||||
人打开这一页,读函数旁边的句子,知道加法在算什么。编译器解析同一批标记,检查参数和返回。开发者把函数嵌进别的程序。测试对这个函数传入输入,看输出是不是期望值,不必为它包一层只用来打印的程序。Agent 读到的是函数的用途,执行的是已经写好的实现,而不是读完说明再临时重写一遍。
|
||||
|
||||
这四件事共用一次调用。知识成为工具,是「知识即可执行」在函数这一层上的结果。文件不需要改名,也不需要声明自己是技能。运行时和工具清单都不会把一页普通文档挡在门外。
|
||||
|
||||
---
|
||||
|
||||
边界也写在命令里。
|
||||
|
||||
外部调用默认只执行纯函数。写文件、起进程、访问网络、加载插件,会在运行前被拒绝,副作用不会发生。要放宽权限,仍走项目里已有的验证,而不是在这条命令上新开一个开关。实例方法需要接收者,不能靠这条命令凭空调用。
|
||||
|
||||
函数名必须能唯一对上。没有这个函数,或同一个短名指向两个函数,都会返回结构化错误,不会擅自挑第一个。参数按函数已有的签名和契约绑定:缺了、多了、类型不对,都是诊断,不是静默猜一个值。
|
||||
|
||||
改一个函数之后,用原来的输入再调用一次。结果对了,这个实现就留下来;不对,就还是原来的实现。测试不能证明所有输入都正确。它让修改有一个可以重复的检查点。
|
||||
|
||||
# 计算器
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 供下述方法复用的对象或类型命名空间;直接调用所需的子函数。 |
|
||||
|
||||
这是一个普通的 Marqdo 文档。
|
||||
|
||||
其中包含一些可以复用的数学计算知识。
|
||||
|
||||
## 加法
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| a | any | 必填 | Left operand supplied to this calculation |
|
||||
| b | any | 必填 | Right operand supplied to this calculation |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 下文显式返回的计算值或结构化结果;分支存在时遵循实际命中的分支。 |
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
完成上述步骤后,返回*[计算结果]((`a` + `b`))*。
|
||||
|
||||
## 乘法
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| a | any | 必填 | Left operand supplied to this calculation |
|
||||
| b | any | 必填 | Right operand supplied to this calculation |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 下文显式返回的计算值或结构化结果;分支存在时遵循实际命中的分支。 |
|
||||
|
||||
计算两个数字`a`和`b`的积。
|
||||
|
||||
完成上述步骤后,返回*[计算结果]((`a` * `b`))*。
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
import:
|
||||
result: ../../lib/result.mq.md
|
||||
title: Prove what a page claims: theorem tables judged by Lean 4
|
||||
description: v2.8.0 marqdo prove compiles theorem tables to Lean 4 and judges them. Offline symbolic execution works without a toolchain and never outruns Lean.
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
v2.8.0 adds one command: `marqdo prove`. A theorem table in a knowledge file is compiled to Lean 4 and judged automatically. The claim stops being prose that a reader agrees with and becomes a statement a proof assistant checks.
|
||||
|
||||
```text
|
||||
marqdo prove examples/approval.mq.md --json
|
||||
```
|
||||
|
||||
The pipeline has six stages: load, lower to an intermediate representation, type the claim, generate a Lean module, judge it, and issue a certificate. Judging has two layers. Offline symbolic execution runs first — path enumeration over the pure fragment, milliseconds, no toolchain required. When a Lean toolchain is available it re-checks the emitted module and upgrades the verdict.
|
||||
|
||||
The status ladder is honest by construction: `proved > checked > unverified > rejected > unproved > error`. Offline `checked` is a decided trace for the explored paths, never a proof; `proved` exists only when Lean says so. Without a toolchain the verdict stays at `checked` or `unverified` and the process exits zero — advisory, not silent. `--require-lean` flips unjudged states into failures for CI.
|
||||
|
||||
A false theorem does not get a shrug. The judge produces a counterexample witness — concrete input values that walk the function down a path where the conclusion fails — and points back at the theorem-table row.
|
||||
|
||||
The boundary that makes this trustworthy is monotonicity: whatever the offline layer claims, Lean must be able to confirm. If the offline verdict says checked and Lean cannot prove it, or a counterexample is proven away, the command fails with `proof.divergence` and exits non-zero. A judger defect fails loudly; a green light is never defended.
|
||||
|
||||
The fragment is deliberately small: pure functions, branch comparisons, call-trace shapes, constructor structure, interval restatements. Loops report `proof.foreach_pending` instead of pretending. Cross-module calls stay opaque until assumption tables arrive. Every simplification is recorded in the design docs, because a proof system that hides its boundaries is marketing, not verification.
|
||||
|
||||
This page runs — the theorems below live in the same file that explains them. `轨迹` is the implicit call trace of the function: the big-amount path must pass through 复核, opaque calls append to it, and inlined `result.ok` constructors do not.
|
||||
|
||||
# 台账
|
||||
|
||||
## 记一笔
|
||||
+ `金额`
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 金额 | int | 记账金额(元) |
|
||||
|
||||
| 定理 | 结论 | 前提 | 策略 |
|
||||
|---|---|---|---|
|
||||
| 大额必经复核 | 包含(轨迹, "复核") | 金额 > 10000 | auto |
|
||||
| 大额单次外呼 | 长度(轨迹) = 1 | 金额 > 10000 | auto |
|
||||
| 必有回执 | 结果.ok = True | | auto |
|
||||
|
||||
1. 当`金额`小于等于10000时
|
||||
**回执 = [直接记账](result.ok(value="记"))**
|
||||
2. *
|
||||
**复核结论 = [转复核](复核(金额=`金额`))**
|
||||
**回执 = [采纳](result.ok(value=`复核结论`))**
|
||||
|
||||
*回执*
|
||||
|
||||
## 复核
|
||||
+ `金额`
|
||||
|
||||
**复核回执 = [复核通过](result.ok(value="复核"))**
|
||||
|
||||
*复核回执*
|
||||
-5071
File diff suppressed because it is too large.
Load diff
@@ -1,28 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Booleans and logic
|
||||
description: True / False / None and and / or / not
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Keywords: `True`, `False`, `None`, and `and` / `or` / `not`.
|
||||
|
||||
We first **a = True** for the next step.
|
||||
We first **b = False** for the next step.
|
||||
|
||||
1. `a` and not `b`
|
||||
We now **[Display this step's result](> print text="ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="fail")**.
|
||||
|
||||
We first **probe = 1** for the next step.
|
||||
|
||||
1. None
|
||||
We now **[Display this step's result](> print text="none-truthy")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="none-falsy")**.
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Built-in input
|
||||
description: Read one line from stdin; optional prompt. Demo via frontmatter stdin.
|
||||
stdin: Ada
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
The input builtin reads one line. For demos and marqdo view / static export, put sample lines in frontmatter (stdin:). CLI can also use a pipe or --stdin-file. Live view can override with the Preset input box.
|
||||
|
||||
We first **name = [Compute name](input(prompt="Name: "))** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text="Hello `name`!")**.
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Built-in print
|
||||
description: Named and positional forms
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
The `print` builtin accepts named or positional arguments:
|
||||
|
||||
We now **[Display this step's result](> print text="named form")**.
|
||||
|
||||
We now **[Display this step's result](> print "positional")**.
|
||||
|
||||
Named args may contain spaces; positional args may not.
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Built-ins len / str / int / type / trim / split / join / at
|
||||
description: Host builtins for strings and tables
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Length and type:
|
||||
|
||||
We first **s = "hello"** for the next step.
|
||||
|
||||
We first **n = [Compute n](len(`s`))** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text=`n`)**.
|
||||
|
||||
We first **ty = [Compute ty](type(`s`))** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text=`ty`)**.
|
||||
|
||||
Trim, split, join, and index:
|
||||
|
||||
We first **t = [Compute t](trim(value=" hi "))** for the next step.
|
||||
|
||||
We first **parts = [Compute parts](split(value="a,b", sep=","))** for the next step.
|
||||
|
||||
We first **mid = [Compute mid](at(value=`parts`, index=0))** for the next step.
|
||||
|
||||
We first **j = [Compute j](join(value=`parts`, sep="-"))** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text=`t`)**.
|
||||
|
||||
We now **[Display this step's result](> print text=`mid`)**.
|
||||
|
||||
We now **[Display this step's result](> print text=`j`)**.
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中英内核双名
|
||||
description: 无需导入:打印、长度、文本、整数 与 print / len / …
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
内核中英别名等价,可混用:
|
||||
|
||||
我们先**s = "你好"**,供下一步使用。
|
||||
|
||||
我们先**n = [计算并保存 n](长度(值=`s`))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`n`)**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> print text="also-english")**。
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 布尔与逻辑
|
||||
description: 真 / 假 / 空 与 且 / 或 / 非
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
关键字:`真`、`假`、`空`,以及 `且` / `或` / `非`。
|
||||
|
||||
我们先**a = True**,供下一步使用。
|
||||
我们先**b = False**,供下一步使用。
|
||||
|
||||
1. `a` 且 非 `b`
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="通过")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="失败")**。
|
||||
|
||||
我们先**probe = 1**,供下一步使用。
|
||||
|
||||
1. 空
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="空为真")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="空为假")**。
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 内置 打印
|
||||
description: 具名与位置两种写法
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
内置 `打印` 接受具名或位置实参:
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="具名写法")**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 "位置写法")**。
|
||||
|
||||
具名实参可以带空格;位置实参不可以。
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 内置 长度 / 文本 / 整数 与 trim 等
|
||||
description: 主机内置;中文别名覆盖常用几个
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
长度与英文 `type`(类型无中文内核别名,见标准库文档):
|
||||
|
||||
我们先**s = "你好"**,供下一步使用。
|
||||
|
||||
我们先**n = [计算并保存 n](长度(值=`s`))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`n`)**。
|
||||
|
||||
我们先**ty = [计算并保存 ty](type(`s`))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`ty`)**。
|
||||
|
||||
去空白、拆分、拼接、按下标(主机名仍为英文):
|
||||
|
||||
我们先**t = [计算并保存 t](trim(value=" 嗨 "))**,供下一步使用。
|
||||
|
||||
我们先**parts = [计算并保存 parts](split(value="甲,乙", sep=","))**,供下一步使用。
|
||||
|
||||
我们先**mid = [计算并保存 mid](at(value=`parts`, index=0))**,供下一步使用。
|
||||
|
||||
我们先**j = [计算并保存 j](join(value=`parts`, sep="-"))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`t`)**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`mid`)**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`j`)**。
|
||||
Loaded 100 of 278 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user