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
@@ -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