diff --git a/doc/README.md b/doc/README.md index b73180d..d81ef0a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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/)。 diff --git a/doc/research/qdagent-refactor-defects-2026-10.md b/doc/research/qdagent-refactor-defects-2026-10.md index 9bde6ba..4cef4e3 100644 --- a/doc/research/qdagent-refactor-defects-2026-10.md +++ b/doc/research/qdagent-refactor-defects-2026-10.md @@ -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: --- -## 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` 以 `` 开头,未提示缺 `# 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` | diff --git a/doc/tutorial/15-常见陷阱.md b/doc/tutorial/15-常见陷阱.md new file mode 100644 index 0000000..9a11940 --- /dev/null +++ b/doc/tutorial/15-常见陷阱.md @@ -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 实测 | diff --git a/doc/tutorial/README.md b/doc/tutorial/README.md index 161da33..de0e1c4 100644 --- a/doc/tutorial/README.md +++ b/doc/tutorial/README.md @@ -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) | 行首数字、作用域、空格函数名、导入路径等实测坑 | 避开高频错误,提交前自查 | ---