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

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