Files
marqdo/doc/tutorial/15-常见陷阱.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

9.5 KiB
Executable File
Raw Permalink Blame History

Marqdo 常见陷阱手册

状态 Accepted · 使用向(全部条目在 marqdo 1.5.2 上实测)
日期 2026-10-22
来源 qdagent 重构期间(文档门禁 + 输出契约)逐条踩坑复现
关联 02-基本语法.md · 06-函数.md · 11-模块与导入.md · design/markdown-mapping-v0.3.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. 第一步」这类写法极常见, 凡是整行以数字起头都会被拦:

# 结论

发布年份是 2026 年。          ← 把数字后移
共收录 42 条。                 ← 不要以 42 起行
有三个要点需要说明。            ← 不要写 "3 个要点…" 起行

确需保留行首数字时,包进行内代码或围栏:

`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 未闭合引号 → 静默吞行 ⚠️ 危险

现象

**s = "abc
> print text=hi
*""

输出 hi,没有报错,s 那一行凭空消失。

原因:未闭合的双引号让该行被当作叙述而不是语句。

影响:这类错误不会中断程序,只会让变量「不存在」,随后在别处报 undefined variable,把排查方向引偏。

改法:写完立即 marqdo check,或注意「变量莫名未定义」时先看引号是否配对。


2. 变量作用域

2.1 模块级变量在函数之间不可见

现象

# main

**g = 10**
> show
*""

## show

> print text=`g`
*None*
error: t1.mq.md:13:1: undefined variable `g`

兄弟函数之间同样不可见:

## a

**x = 1**
> b
*None*

## b

> print text=`x`      ← undefined variable `x`
*None*

原因:每个 ## 是独立作用域;# main 与各函数之间不共享变量,只共享参数与返回值。

改法:一切跨函数数据走参数与返回值。

## 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 或某个 ## 里。

改法:

---
title: e
---

**x = 1**          ← 挪走

# main

**x = 1**
> print text=ok
*""

2.3 table.put 不原地修改

现象

**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,且不报错。

改法:接住返回值。

**state = > table.put in=`state` at="ok_n" value=`n2`**

3. 函数

3.1 函数名含空格 → 定义成功,调用必崩 ⚠️ 缺陷

现象

## 加一 号
    + `n`

*`n` + 1*

# main

**r = > 加一 号 n=1**
error: t8.mq.md:13:1: undefined variable `号`

英文同样:

## my func

调用 → undefined variable func。

原因:调用处按空格切分,第一个词当函数名,其余词当位置参数或变量插值。 定义侧允许空格,两侧不对称。

改法:函数名不要含空格。用连字符、下划线或去掉空格:

## 加一_号
## assert-no-main
## my_func

命名建议:中文标识符直接连写(断言干净、门禁沉淀),英文用下划线。

3.2 函数内变量名别和叙述里的裸词撞车

叙述里的裸词一般是安全的(实测 大约 head 的位置。 不报错)。 但在函数名或调用参数位置出现未定义标识符会立刻报 undefined variable。 判断标准同上:会被当成语句/表达式的上下文才插值。


4. 字符串与拼接

4.1 引号内 **、|、# 多数安全,不必恐慌

实测以下全部 ✅:

**s = "a ** b"**
**s = "a | col | b"**
**s = "abc # main def"**
**s = "sum: total items"**

只有引号不配对才会出问题(回到 §1.4)。

4.2 拼装文档正文时,"、*、| 仍建议转义

当你用字符串拼接生成一份 .mq.md(而不是自己写)时,字面量容易提前闭合标记。 稳妥写法是用 Unicode 转义:

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

跨目录才用 ..:

import:
  ctx: ../knowledge/context.mq.md

5.2 库名必须导入,不能用裸名

error: unknown library `json` (import it in frontmatter)
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 的体不会被 ## 截断

# main

> print text=first

## helper

*1*

> print text=last      ← 仍属于 main,会执行
*""

输出 first last。但可读性差,建议 # main 只做编排,函数都放前面。

7.2 1. 2. 3. 是一条 if/elif/else 链

1. `a` > 10
  ...
2. `a` > 5
  ...
3. *
  ...

两段独立的 1. 是两个 if,不是链。嵌套靠缩进。 2. * 是 else 分支。


8. 自查清单

提交前跑一遍:

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 实测