docs(tutorial): 新增《常见陷阱手册》,并补 D8–D10、按实测收敛 D3
把 qdagent 重构期间踩到的坑整理成**使用向**手册 doc/tutorial/15-常见陷阱.md (417 行,全部条目在 1.5.2 逐条实测,含现象/原因/改法三段式与提交前自查清单)。 手册要点: - §1 写文档:行首数字必报错(2026 年 / 42 条 / 3 个要点 都中招); 行首 + 报错;未闭合引号静默吞行(最危险) - §2 变量作用域:模块级变量在 # main 与各 ## 之间不可见; 顶层不许裸语句;table.put 不原地修改 - §3 函数:函数名含空格时定义成功但调用必崩 - §4 字符串:引号内 ** / | / # 实为安全,只有引号不配对才出事 - §5 导入:相对路径以当前文件为基准;标准库必须带库名前缀 - §6 易记错的函数签名(txt.contains 的 sub、table.put 的 in/at/value …) - §7 结构:# main 体不被 ## 截断;1./2./3. 是 if/elif/else 链 - §8 自查清单(marqdo check + run 双跑) 同步修正缺陷实录 research/qdagent-refactor-defects-2026-10.md: - D3 收敛:实测证明 - / > / | / [ 在叙述区**安全**,只有行首数字与 + 会被当语句;判据是「该行能否被解析成完整语句」 - 新增 D8 函数名含空格:定义成功、调用必崩,check 却通过(不对称) - 新增 D9 未闭合引号静默吞行,退出码 0(静默类最危险) - 新增 D10 table.put 非原地,累积计数静默失效 - 同步复现清单与变更记录 索引:tutorial/README 增第 15 章;doc/README 增手册与缺陷实录两行。 手册内所有代码示例均实测跑通(含参数传递修法、if 链、标准库前缀)。
This commit is contained in:
1 parent
f2d651e063
commit
aeb5a2a43d
4 files changed
+546
-14
No files matched your search
@@ -105,6 +105,8 @@
|
||||
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
|
||||
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
@@ -21,11 +21,14 @@ qdagent 重构把「智能体输出与沉淀笔记必须是可运行 `.mq.md`」
|
||||
|----|------|--------|------|
|
||||
| D1 | `sandbox.profile` 仅回显,不改变实际能力 | **高** | Open(安全语义) |
|
||||
| D2 | `CALL:`/`调用:` 全角冒号无法解析,但提示文案推荐它 | **高** | Open(协议契约) |
|
||||
| D3 | 叙述行行首执行标记导致「看似正常的中文文档」解析失败 | 中 | Open(可用性) |
|
||||
| D3 | 行首数字 / `+` 使叙述行被当语句,中文文档解析失败 | 中 | Open(可用性) |
|
||||
| D4 | `sandbox.run source=` 的报错丢失文件上下文 | 中 | Open(诊断) |
|
||||
| D5 | 成员式取元 `[key](map)` 在键缺失时硬崩 | 中 | Open(健壮性) |
|
||||
| D6 | 未绑定 GFM 表不可迭代,但报错不指向根因 | 低 | Open(诊断) |
|
||||
| D7 | 沙箱内 `subtask spawn path=` 静默不可用(设计如此,需文档明示) | 低 | Documented |
|
||||
| D8 | 函数名含空格:定义成功、调用必崩 | **高** | Open(不对称) |
|
||||
| D9 | 未闭合引号静默吞行,退出码 0 | **高** | Open(静默) |
|
||||
| D10 | `table.put` 非原地修改,累积状态静默失效 | 中 | Open(文档) |
|
||||
|
||||
---
|
||||
|
||||
@@ -121,20 +124,26 @@ When calling an allowed tool, reply with exactly one line: CALL:<name>
|
||||
|
||||
---
|
||||
|
||||
## D3 — 叙述行行首执行标记导致中文文档解析失败
|
||||
## D3 — 行首数字 / `+` 导致中文文档解析失败
|
||||
|
||||
### 现象
|
||||
|
||||
按 v0.3 语法,非标记行是叙述(注释)。但**行首**出现执行标记时,该行会被真当语句执行:
|
||||
按 v0.3 语法,非标记行是叙述(注释)。但某些行首字符会让该行被当成语句。
|
||||
|
||||
| 行首 | 被解析成 | 报错 |
|
||||
|------|----------|------|
|
||||
| 数字 `9 号是数字。` | 语句 | `unrecognized statement` |
|
||||
| `-` | 循环 | `foreach needs a list or map` |
|
||||
| `>` | 调用 | `unknown function` |
|
||||
| `\|` | GFM 表 | 上下文错误 / `footnote index needs list or map` |
|
||||
| 裸 `[{"a":1}]` | 表达式 | `trailing input in expression` |
|
||||
| `**` / `*` | 代码 / 返回 | 标记未闭合 |
|
||||
**实测修正(1.5.2,逐条跑过)**——不是所有标记都出问题:
|
||||
|
||||
| 行首 | 叙述区实测 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `9 号是数字。` | ❌ `unrecognized statement` | 数字字面量是真语句 |
|
||||
| `42` / `2026 年发布。` | ❌ `unrecognized statement` | 同上 |
|
||||
| `+ 加号` | ❌ `unrecognized statement` | `+` 是前导符语法 |
|
||||
| `- 列表项` | ✅ 安全 | 不构成有效 foreach → 跳过 |
|
||||
| `> 引用` | ✅ 安全 | 无对应函数时不当调用 |
|
||||
| `\| a \| b \|` | ✅ 安全 | 未绑定表不算语句 |
|
||||
| `[{"a":1}]` | ✅ 安全 | 无归属的链接索引 → 跳过 |
|
||||
|
||||
判据是**该行能否被解析成一条完整语句**:能则执行,不能则当叙述跳过。
|
||||
所以在函数体内上下文成立时,`- [`x`](`xs`)` 仍是真循环。
|
||||
|
||||
实测(qdagent 门禁):
|
||||
|
||||
@@ -147,13 +156,17 @@ gate.门禁 text="...\n# 结论\n\n9 号是数字。\n\n# main\n..."
|
||||
### 影响
|
||||
|
||||
对**人类作者**这是设计取舍(执行标记优先于叙述,符合「标记即语法」)。
|
||||
但对**LLM 生成的中文文档**是高频陷阱:中文写「3 个要点」、`- 列表`、
|
||||
`1. 步骤` 都是默认表达习惯,一旦出现在叙述区,整篇文档解析失败。
|
||||
但对**LLM 生成的中文文档**是高频陷阱:中文写「2026 年」「42 条」「3 个要点」
|
||||
都是默认表达习惯,一旦出现在叙述区,整篇文档解析失败。
|
||||
|
||||
这是「文档即可运行」与「文档可读」之间的真实张力。
|
||||
qdagent 的应对是**在提示词里逐条禁止**并**门禁机械校验**(见
|
||||
`doc/design/09-document-contract-and-docgate.md`),但根源在语言层面。
|
||||
|
||||
补充(实测发现的更隐蔽问题):**未闭合引号会静默吞行**,不报错,
|
||||
只在别处表现为 `undefined variable`。见使用手册
|
||||
[`tutorial/15-常见陷阱.md`](../tutorial/15-常见陷阱.md) §1.4。
|
||||
|
||||
### 建议
|
||||
|
||||
不改语义(执行标记优先是 v0.3 的基石),但增强可诊断性:
|
||||
@@ -259,6 +272,102 @@ qdagent 的修法是改用 `table.get map= key=` 取可选键,但这是每个
|
||||
|
||||
---
|
||||
|
||||
## D8 — 函数名含空格:定义成功,调用必崩
|
||||
|
||||
### 现象
|
||||
|
||||
```markdown
|
||||
## 加一 号
|
||||
+ `n`
|
||||
|
||||
*`n` + 1*
|
||||
|
||||
# main
|
||||
|
||||
**r = > 加一 号 n=1**
|
||||
```
|
||||
|
||||
```
|
||||
error: t8.mq.md:13:1: undefined variable `号`
|
||||
```
|
||||
|
||||
英文同理:`## my func` 调用时报 `undefined variable func`。
|
||||
|
||||
### 根因
|
||||
|
||||
定义侧(`##` 标题)接受空格;调用侧按空格切词,
|
||||
第一个词当函数名,其余当位置参数或**变量插值**。两侧不对称。
|
||||
|
||||
### 影响
|
||||
|
||||
这是**静默不对称**:`marqdo check` 通过(`无契约问题`),
|
||||
只有真跑才崩,且报错指向「未定义变量」而非「函数名非法」,
|
||||
排查方向被引偏。中文标识符天然爱加空格(`断言无 main`、`加一 号`),
|
||||
LLM 生成代码时尤其容易命中。
|
||||
|
||||
### 建议
|
||||
|
||||
二选一:
|
||||
|
||||
1. **定义侧拒绝空格**——`##` 名字含空格时报
|
||||
`function name may not contain spaces`,定义期即失败。
|
||||
2. **调用侧贪婪匹配**——按已知函数名最长前缀匹配,允许空格名(改动大,不推荐)。
|
||||
|
||||
倾向方案 1:与「标识符不含空格」的通行约定一致,成本最低。
|
||||
|
||||
---
|
||||
|
||||
## D9 — 未闭合双引号静默吞行,无任何报错
|
||||
|
||||
### 现象
|
||||
|
||||
```markdown
|
||||
**s = "abc
|
||||
> print text=hi
|
||||
*""
|
||||
```
|
||||
|
||||
输出 `hi`,退出码 0,**没有报错**,`s` 那一行凭空消失。
|
||||
|
||||
### 根因
|
||||
|
||||
未闭合引号使该行无法解析为语句,于是被当作**叙述**跳过。
|
||||
叙述与「解析失败的语句」没有区分。
|
||||
|
||||
### 影响
|
||||
|
||||
- 变量「莫名未定义」,后续在别处报 `undefined variable`,根因被掩盖。
|
||||
- 生成的文档会少一节内容却不报错——对「文档即程序」而言这是**最危险**的一类:
|
||||
文档看起来完整、能跑、退出码 0,但少了一段。
|
||||
|
||||
### 建议
|
||||
|
||||
未闭合引号应在解析期报错:
|
||||
`unterminated string literal at line N`。
|
||||
若担心破坏「叙述自由」,至少让 `marqdo check` 检出
|
||||
「以 `**` 开头但不以 `**` 结尾」的行并 warn。
|
||||
|
||||
---
|
||||
|
||||
## D10 — 取元 `[key](map)` 与非原地 `table.put` 的认知负担
|
||||
|
||||
已在 [D5](#d5--成员式取元-keymap-在键缺失时硬崩) 记录取元硬崩。
|
||||
补充**协同陷阱**:`table.put` **不原地修改**,返回新 map:
|
||||
|
||||
```markdown
|
||||
**m = > json.parse text={"n":0}**
|
||||
**r = > table.put in=`m` at="n" value=1**
|
||||
```
|
||||
|
||||
`m` 仍是 `{"n":0}`,`r` 才是 `{"n":1}`。
|
||||
于是「靠 `> table.put in=`state` ...` 累积计数」**不生效且无报错**——
|
||||
计数器永远是 0,自检看起来「全部通过」。
|
||||
|
||||
建议:在 `lib/table` 的 `put` 文档里用一句话强调「返回新表」,
|
||||
并考虑提供 `put!` 或 `set!` 的就地版本以匹配直觉。
|
||||
|
||||
---
|
||||
|
||||
## 附录:本次开发中确认正常的项
|
||||
|
||||
避免误报,以下行为经实测**符合文档**,不在缺陷之列:
|
||||
@@ -281,10 +390,13 @@ qdagent 的修法是改用 `table.get map= key=` 取可选键,但这是每个
|
||||
|----|------|--------|
|
||||
| D1 | `sb.open root="." profile="readonly"` + `sb.inspect` | `profile.name` 回显 `default`,`fs_write:true` |
|
||||
| D2 | 模型输出 `调用:tool_find`(全角) | 无工具结果、无报错 |
|
||||
| D3 | 文档叙述区写 `9 号是数字。` | `unrecognized statement` / 门禁 `narration_marker` |
|
||||
| D3 | 文档叙述区写 `9 号是数字。` 或 `+ 加号` | `unrecognized statement` / 门禁 `narration_marker` |
|
||||
| D4 | `sb.run id= source="> print text=x"` | `error` 以 `<memory>` 开头,未提示缺 `# main` |
|
||||
| D5 | `[error](r)`,`r` 为成功返回 | `missing map key 'error'` |
|
||||
| D6 | 未绑定 GFM 表后 `- [x](表)` | `foreach needs a list or map` |
|
||||
| D8 | `## my func` + `> my func n=1` | `undefined variable func`(check 却通过) |
|
||||
| D9 | `**s = "abc` 不闭合 | 静默吞行,退出码 0 |
|
||||
| D10 | `> table.put in=`m` at=…` 后读 `m` | 原表未变;计数永远是 0 |
|
||||
|
||||
---
|
||||
|
||||
@@ -293,3 +405,4 @@ qdagent 的修法是改用 `table.get map= key=` 取可选键,但这是每个
|
||||
| 日期 | 变更 |
|
||||
|------|------|
|
||||
| 2026-10-22 | 首次记录 D1–D7(qdagent 文档门禁开发期) |
|
||||
| 2026-10-22 | 补 D8–D10;D3 按逐条实测收敛(`-` / `>` / `\|` / `[` 实为安全,只数字与 `+` 报错);配套使用手册 `tutorial/15-常见陷阱.md` |
|
||||
@@ -0,0 +1,416 @@
|
||||
# Marqdo 常见陷阱手册
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 使用向**(全部条目在 `marqdo 1.5.2` 上实测) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 来源 | qdagent 重构期间(文档门禁 + 输出契约)逐条踩坑复现 |
|
||||
| 关联 | [02-基本语法.md](02-基本语法.md) · [06-函数.md](06-函数.md) · [11-模块与导入.md](11-模块与导入.md) · [design/markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) |
|
||||
| 缺陷来源 | [research/qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 怎么用这份文档
|
||||
|
||||
不是语言教程,而是**避坑清单**。每条都给出:
|
||||
|
||||
- **现象**:你会看到什么(报错原文)
|
||||
- **原因**:为什么这样
|
||||
- **改法**:可直接抄的写法
|
||||
|
||||
全部结论来自实测,不是推测。文中「✅ 安全」表示实测通过,不要靠猜。
|
||||
|
||||
---
|
||||
|
||||
## 1. 写文档(最常见的一类)
|
||||
|
||||
Marqdo 是「文档即程序」,所以**文档写得像正常中文**恰恰是最容易出错的地方。
|
||||
门禁类工具(如 qdagent 的 `execution/docgate`)主要就是在防这些。
|
||||
|
||||
### 1.1 行首数字 → 一定报错 ⚠️ 最高频
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: a.mq.md:7:1: unrecognized statement: 2026 年发布。
|
||||
error: b.mq.md:7:1: unrecognized statement: 42
|
||||
error: c.mq.md:7:1: unrecognized statement: 9 号是数字。
|
||||
```
|
||||
|
||||
**原因**
|
||||
|
||||
行首是数字时,该行被当成**语句**去解析(数字是字面量表达式),而非叙述。
|
||||
|
||||
**改法**
|
||||
|
||||
以文字开头即可。中文里「2026 年」「42 个」「3 个要点」「1. 第一步」这类写法极常见,
|
||||
凡是整行以数字起头都会被拦:
|
||||
|
||||
```markdown
|
||||
# 结论
|
||||
|
||||
发布年份是 2026 年。 ← 把数字后移
|
||||
共收录 42 条。 ← 不要以 42 起行
|
||||
有三个要点需要说明。 ← 不要写 "3 个要点…" 起行
|
||||
```
|
||||
|
||||
确需保留行首数字时,包进行内代码或围栏:
|
||||
|
||||
```markdown
|
||||
`2026` 是发布年份。
|
||||
|
||||
````markdown
|
||||
42
|
||||
````
|
||||
|
||||
### 1.2 行首 `+` → 报错
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: tmm.mq.md:7:1: unrecognized statement: + 加号
|
||||
```
|
||||
|
||||
**原因**:`+` 是形参声明与列表语法的前导符。
|
||||
|
||||
**改法**:叙述区不要用 `+ ` 起行做列表;需要列表用 `- `(见下条)。
|
||||
|
||||
### 1.3 `-` / `>` / `|` / `[` 起行:**多数情况安全**
|
||||
|
||||
这一条要纠正一个常见误解。实测:
|
||||
|
||||
| 行首 | 叙述区 | 说明 |
|
||||
|------|--------|------|
|
||||
| `- 列表项` | ✅ 安全 | 不构成有效 foreach → 跳过 |
|
||||
| `> 引用` | ✅ 安全 | 无对应函数时不当调用 |
|
||||
| `\| a \| b \|` | ✅ 安全 | 未绑定表不算语句 |
|
||||
| `[{"a":1}]` | ✅ 安全 | 无归属的链接索引 → 跳过 |
|
||||
| `9 号是数字。` | ❌ 报错 | 数字字面量是真语句 |
|
||||
| `+ 加号` | ❌ 报错 | 前导符是真语法 |
|
||||
|
||||
但**在函数体内且上下文成立时**它们会真的执行(例如 `- [`x`](`xs`)` 是真循环)。
|
||||
判断标准:**能不能被解析成一条完整语句**。能,就执行;不能,就当叙述跳过。
|
||||
|
||||
### 1.4 未闭合引号 → 静默吞行 ⚠️ 危险
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
**s = "abc
|
||||
> print text=hi
|
||||
*""
|
||||
```
|
||||
|
||||
输出 `hi`,**没有报错**,`s` 那一行凭空消失。
|
||||
|
||||
**原因**:未闭合的双引号让该行被当作叙述而不是语句。
|
||||
|
||||
**影响**:这类错误不会中断程序,只会让变量「不存在」,随后在别处报
|
||||
`undefined variable`,把排查方向引偏。
|
||||
|
||||
**改法**:写完立即 `marqdo check`,或注意「变量莫名未定义」时先看引号是否配对。
|
||||
|
||||
---
|
||||
|
||||
## 2. 变量作用域
|
||||
|
||||
### 2.1 模块级变量在函数之间**不可见**
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**g = 10**
|
||||
> show
|
||||
*""
|
||||
|
||||
## show
|
||||
|
||||
> print text=`g`
|
||||
*None*
|
||||
```
|
||||
|
||||
```
|
||||
error: t1.mq.md:13:1: undefined variable `g`
|
||||
```
|
||||
|
||||
兄弟函数之间同样不可见:
|
||||
|
||||
```markdown
|
||||
## a
|
||||
|
||||
**x = 1**
|
||||
> b
|
||||
*None*
|
||||
|
||||
## b
|
||||
|
||||
> print text=`x` ← undefined variable `x`
|
||||
*None*
|
||||
```
|
||||
|
||||
**原因**:每个 `##` 是独立作用域;`# main` 与各函数之间**不共享变量**,只共享参数与返回值。
|
||||
|
||||
**改法**:一切跨函数数据走**参数与返回值**。
|
||||
|
||||
```markdown
|
||||
## show
|
||||
+ `g`
|
||||
|
||||
> print text=`g`
|
||||
*None*
|
||||
|
||||
# main
|
||||
|
||||
**g = 10**
|
||||
> show g=`g`
|
||||
*""
|
||||
```
|
||||
|
||||
### 2.2 顶层不许有裸语句
|
||||
|
||||
**现象**
|
||||
|
||||
```
|
||||
error: e.mq.md: 5:1: expected heading (`#` object or `##` function), got: **x = 1**
|
||||
```
|
||||
|
||||
**原因**:文件顶层只能是 frontmatter、叙述、`#` 对象、`##` 函数。
|
||||
语句必须放进 `# main` 或某个 `##` 里。
|
||||
|
||||
**改法**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: e
|
||||
---
|
||||
|
||||
**x = 1** ← 挪走
|
||||
|
||||
# main
|
||||
|
||||
**x = 1**
|
||||
> print text=ok
|
||||
*""
|
||||
```
|
||||
|
||||
### 2.3 `table.put` **不**原地修改
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
**m = > json.parse text={"n":0}**
|
||||
**r = > table.put in=`m` at="n" value=1**
|
||||
```
|
||||
|
||||
之后 `m` 仍是 `{"n":0}`,`r` 才是 `{"n":1}`。
|
||||
|
||||
**影响**:想靠 `> table.put in=`state` ...` 累积状态**不会生效**,
|
||||
计数永远是 0,且不报错。
|
||||
|
||||
**改法**:接住返回值。
|
||||
|
||||
```markdown
|
||||
**state = > table.put in=`state` at="ok_n" value=`n2`**
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 函数
|
||||
|
||||
### 3.1 函数名含空格 → 定义成功,**调用必崩** ⚠️ 缺陷
|
||||
|
||||
**现象**
|
||||
|
||||
```markdown
|
||||
## 加一 号
|
||||
+ `n`
|
||||
|
||||
*`n` + 1*
|
||||
|
||||
# main
|
||||
|
||||
**r = > 加一 号 n=1**
|
||||
```
|
||||
|
||||
```
|
||||
error: t8.mq.md:13:1: undefined variable `号`
|
||||
```
|
||||
|
||||
英文同样:
|
||||
|
||||
```markdown
|
||||
## my func
|
||||
```
|
||||
调用 → `undefined variable func`。
|
||||
|
||||
**原因**:调用处按空格切分,第一个词当函数名,其余词当位置参数或变量插值。
|
||||
定义侧允许空格,**两侧不对称**。
|
||||
|
||||
**改法**:函数名**不要含空格**。用连字符、下划线或去掉空格:
|
||||
|
||||
```markdown
|
||||
## 加一_号
|
||||
## assert-no-main
|
||||
## my_func
|
||||
```
|
||||
|
||||
命名建议:中文标识符直接连写(`断言干净`、`门禁沉淀`),英文用下划线。
|
||||
|
||||
### 3.2 函数内变量名别和叙述里的裸词撞车
|
||||
|
||||
叙述里的裸词一般是安全的(实测 `大约 head 的位置。` 不报错)。
|
||||
但**在函数名或调用参数位置**出现未定义标识符会立刻报 `undefined variable`。
|
||||
判断标准同上:会被当成语句/表达式的上下文才插值。
|
||||
|
||||
---
|
||||
|
||||
## 4. 字符串与拼接
|
||||
|
||||
### 4.1 引号内 `**`、`|`、`#` 多数安全,不必恐慌
|
||||
|
||||
实测以下全部 ✅:
|
||||
|
||||
```markdown
|
||||
**s = "a ** b"**
|
||||
**s = "a | col | b"**
|
||||
**s = "abc # main def"**
|
||||
**s = "sum: total items"**
|
||||
```
|
||||
|
||||
只有**引号不配对**才会出问题(回到 §1.4)。
|
||||
|
||||
### 4.2 拼装文档正文时,`"`、`*`、`|` 仍建议转义
|
||||
|
||||
当你用字符串拼接**生成一份 `.mq.md`**(而不是自己写)时,字面量容易提前闭合标记。
|
||||
稳妥写法是用 Unicode 转义:
|
||||
|
||||
```markdown
|
||||
**qt = "\u{22}"**
|
||||
**star = "\u{2a}"**
|
||||
**pipe = "\u{7c}"**
|
||||
**nl = "\n"**
|
||||
|
||||
**doc = "---" + `nl` + "title: x" + `nl` + "---" + `nl` + `nl` + "# main" + `nl` + `nl`**
|
||||
**doc = `doc` + "> print text=" + `qt` + "hi" + `qt` + `nl` + `star` + "None" + `star` + `nl`**
|
||||
```
|
||||
|
||||
### 4.3 heredoc 写含 `\n` 的 `.mq.md` 会自毁
|
||||
|
||||
用 `cat <<'EOF'` 写文件时,若内容本身包含反斜杠转义序列,shell 虽不展开,
|
||||
但若中间出现 `EOF` 相邻的变体或内容被后续 `sed`/脚本改写,极易截断。
|
||||
**建议**:生成 .mq.md 用脚本(Python/Node)或编辑器,别用长 heredoc。
|
||||
|
||||
---
|
||||
|
||||
## 5. 导入
|
||||
|
||||
### 5.1 相对路径以**当前文件**为基准
|
||||
|
||||
`execution/a.mq.md` 里导入同目录的 `b.mq.md`,写 `import b:b.mq.md`。
|
||||
写 `import b:execution/b.mq.md` 或 `../execution/b.mq.md` 都可能失败:
|
||||
|
||||
```
|
||||
error: cannot resolve import `../execution/docgate.mq.md` from
|
||||
```
|
||||
|
||||
**跨目录**才用 `..`:
|
||||
|
||||
```markdown
|
||||
import ctx:../knowledge/context.mq.md
|
||||
```
|
||||
|
||||
### 5.2 库名必须导入,不能用裸名
|
||||
|
||||
```
|
||||
error: unknown library `json` (import it in frontmatter)
|
||||
```
|
||||
|
||||
```markdown
|
||||
import json:lib/json.mq.md
|
||||
```
|
||||
|
||||
标准库函数要**带库名前缀**:`json.parse`、`txt.contains`、`table.put`。
|
||||
裸 `str_split`、`contains` 会报 `unknown function`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 常见函数签名(易记错)
|
||||
|
||||
| 函数 | 参数名 | 备注 |
|
||||
|------|--------|------|
|
||||
| `txt.contains` | `text`, `sub` | 是 `sub` 不是 `part` |
|
||||
| `table.put` | `in`, `at`, `value` | 返回新表,见 §2.3 |
|
||||
| `table.get` | `map`, `key` | 取可选键,键缺失不崩 |
|
||||
| `json.get` | `value`, `key` | 同上 |
|
||||
| `split` | `value`, `sep` | 内置,无库名前缀 |
|
||||
| `sys.env_get` | `name` | |
|
||||
|
||||
**取元 `[key](map)` 是断言式**:键缺失直接 `missing map key 'error'`。
|
||||
取「可能不存在」的键一律用 `table.get` / `json.get`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 结构
|
||||
|
||||
### 7.1 `# main` 的体不会被 `##` 截断
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=first
|
||||
|
||||
## helper
|
||||
|
||||
*1*
|
||||
|
||||
> print text=last ← 仍属于 main,会执行
|
||||
*""
|
||||
```
|
||||
|
||||
输出 `first` `last`。**但可读性差**,建议 `# main` 只做编排,函数都放前面。
|
||||
|
||||
### 7.2 `1.` `2.` `3.` 是一条 if/elif/else 链
|
||||
|
||||
```markdown
|
||||
1. `a` > 10
|
||||
...
|
||||
2. `a` > 5
|
||||
...
|
||||
3. *
|
||||
...
|
||||
```
|
||||
|
||||
两段独立的 `1.` 是**两个** if,不是链。嵌套靠缩进。
|
||||
`2. *` 是 else 分支。
|
||||
|
||||
---
|
||||
|
||||
## 8. 自查清单
|
||||
|
||||
提交前跑一遍:
|
||||
|
||||
```bash
|
||||
marqdo check 你的文件.mq.md # 契约/语法检查
|
||||
marqdo run 你的文件.mq.md # 真跑,退出码 0 才算过
|
||||
```
|
||||
|
||||
逐项确认:
|
||||
|
||||
- [ ] 叙述区没有以**数字**或 `+` 起头的行
|
||||
- [ ] 所有双引号成对
|
||||
- [ ] 函数名不含空格
|
||||
- [ ] 没有依赖「函数间共享变量」
|
||||
- [ ] `table.put` 的返回值都接住了
|
||||
- [ ] import 路径以当前文件为基准
|
||||
- [ ] 可选键用 `table.get` / `json.get`,不用 `[key](map)`
|
||||
- [ ] 文件有 `# main`,且 `# main` 无副作用
|
||||
|
||||
---
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 日期 | 变更 |
|
||||
|------|------|
|
||||
| 2026-10-22 | 首次发布;全部条目在 1.5.2 实测 |
|
||||
@@ -51,6 +51,7 @@
|
||||
| [第 12 章:标准库](./12-标准库.md) | 内置函数、`lib/` 模块 | 直接使用官方能力 |
|
||||
| [第 13 章:命令行工具](./13-命令行工具.md) | `run` / `view` / `debug` / `catalog` | 运行、浏览、调试、发布 |
|
||||
| [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) | `lib/net`、`ext/web`、鉴权、WebSocket | 构建 HTTP 客户端与网页应用 |
|
||||
| [第 15 章:常见陷阱](./15-常见陷阱.md) | 行首数字、作用域、空格函数名、导入路径等实测坑 | 避开高频错误,提交前自查 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user