- 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。
9.5 KiB
Executable File
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 实测 |