Problem
The Lark-flavored Markdown documentation in skills/lark-doc/references/lark-doc-create.md lists which characters need escaping, but never explains when escaping is needed:
- Line 123 (通用规则):
需要显示特殊字符时使用反斜杠转义：* ~ $ [ ] < > { } | ^`
- Line 645 (最佳实践): `转义字符：特殊字符用 \ 转义：* ~ ``
The formatting syntax (**bold**, *italic*, ~~strikethrough~~, etc.) is documented separately in the 富文本格式 section (line 216), but there is no connection between the two — the doc never states that escaping is only needed when a character would be interpreted as formatting syntax.
Impact
AI Agents interpret the escape rule as "always escape these characters", leading to over-escaping:
final_trajectory → final\_trajectoryversion~1.0 → version\~1.05 * 3 → 5 \* 3
The Lark Markdown parser does not consume the extra \, so it renders literally as \_, \~, \* in the document.
Suggestion
Tie the escape rules to the formatting syntax, so agents understand escaping is only needed when a character would trigger formatting (e.g., *text* triggers italic, but a lone * in 5 * 3 does not).
Problem
The Lark-flavored Markdown documentation in
skills/lark-doc/references/lark-doc-create.mdlists which characters need escaping, but never explains when escaping is needed:需要显示特殊字符时使用反斜杠转义：* ~$ [ ] < > { } | ^`The formatting syntax (
**bold**,*italic*,~~strikethrough~~, etc.) is documented separately in the 富文本格式 section (line 216), but there is no connection between the two — the doc never states that escaping is only needed when a character would be interpreted as formatting syntax.Impact
AI Agents interpret the escape rule as "always escape these characters", leading to over-escaping:
final_trajectory→final\_trajectoryversion~1.0→version\~1.05 * 3→5 \* 3The Lark Markdown parser does not consume the extra
\, so it renders literally as\_,\~,\*in the document.Suggestion
Tie the escape rules to the formatting syntax, so agents understand escaping is only needed when a character would trigger formatting (e.g.,
*text*triggers italic, but a lone*in5 * 3does not).