From d1a364c9297582d1e467baaa36d15715297fac4b Mon Sep 17 00:00:00 2001 From: chen Date: Thu, 2 Apr 2026 17:23:52 +0800 Subject: [PATCH 1/2] docs(lark-doc): clarify when escape is needed to prevent agent over-escaping (#155) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The escape rules listed which characters can be escaped but never explained when escaping is actually needed. AI agents interpreted this as 'always escape these characters', producing garbled output like final\_trajectory, version\~1.0, 5 \* 3. Add context: escaping is only needed when a character would trigger formatting syntax (e.g. *text* → italic). Lone special characters in normal text do not need escaping. Fixes larksuite/cli#155 --- skills/lark-doc/references/lark-doc-create.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/skills/lark-doc/references/lark-doc-create.md b/skills/lark-doc/references/lark-doc-create.md index b26a162f..9be65efc 100644 --- a/skills/lark-doc/references/lark-doc-create.md +++ b/skills/lark-doc/references/lark-doc-create.md @@ -120,7 +120,9 @@ lark-cli docs +create --title "产品需求" --markdown ' { } | ^` +- 转义：仅当特殊字符会触发格式化语法时才需要反斜杠转义。支持转义的字符：`* ~ ` $ [ ] < > { } | ^` + - 需要转义：`\*不是斜体\*`（`*...*` 会触发斜体）、`\~\~不是删除线\~\~` + - 无需转义：`5 * 3`（孤立的 `*` 不触发格式化）、`final_trajectory`（`_` 在单词中间不触发斜体）、`version~1.0`（孤立的 `~` 不触发删除线） --- @@ -642,7 +644,7 @@ $$ ## 最佳实践 - **空行分隔**：不同块类型之间用空行分隔 -- **转义字符**：特殊字符用 `\` 转义：`\*` `\~` `\`` +- **转义字符**：仅在字符会触发格式化时才转义（如 `\*text\*` 防止斜体）。普通上下文中的 `*`、`~`、`_` 等无需转义 - **图片**：使用 URL，系统自动下载上传 - **分栏**：列宽总和必须为 100 - **表格选择**：简单数据用 Markdown，复杂嵌套用 `` From 0c54e2b6ee4a266b559148bc91f3c0b9bc06f7e8 Mon Sep 17 00:00:00 2001 From: chen Date: Thu, 2 Apr 2026 20:15:44 +0800 Subject: [PATCH 2/2] fix(lark-doc): use individual code spans for escape character list Split the single code span containing all escape characters into individual code spans, using double-backtick fencing for the literal backtick character. Fixes MD038 and broken rendering on GitHub. Addresses CodeRabbit review comment on PR #216. --- skills/lark-doc/references/lark-doc-create.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/lark-doc/references/lark-doc-create.md b/skills/lark-doc/references/lark-doc-create.md index 9be65efc..584bd345 100644 --- a/skills/lark-doc/references/lark-doc-create.md +++ b/skills/lark-doc/references/lark-doc-create.md @@ -120,7 +120,7 @@ lark-cli docs +create --title "产品需求" --markdown ' { } | ^` +- 转义：仅当特殊字符会触发格式化语法时才需要反斜杠转义。支持转义的字符：`*`, `~`, `` ` ``, `$`, `[`, `]`, `<`, `>`, `{`, `}`, `|`, `^` - 需要转义：`\*不是斜体\*`（`*...*` 会触发斜体）、`\~\~不是删除线\~\~` - 无需转义：`5 * 3`（孤立的 `*` 不触发格式化）、`final_trajectory`（`_` 在单词中间不触发斜体）、`version~1.0`（孤立的 `~` 不触发删除线）