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:
cflmy committed 2026-10-22 09:46:17 +08:00
1 parent f2d651e063
commit aeb5a2a43d
4 files changed
+546 -14

No files matched your search

+416
View File
@@ -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 实测 |
+1
View File
@@ -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) | 行首数字、作用域、空格函数名、导入路径等实测坑 | 避开高频错误,提交前自查 |
---