docs(lark-doc): clarify when escape is needed to prevent agent over-escaping

[meijing0114]

Problem

Fixes #155

The escape rules in lark-doc-create.md list which characters can be escaped but never explain when escaping is actually needed. AI agents interpret this as "always escape these characters", producing garbled output:

• final_trajectory → final\_trajectory
• version~1.0 → version\~1.0
• 5 * 3 → 5 \* 3

The Lark Markdown parser doesn't consume the extra \, so it renders literally as \_, \~, \*.

Fix

Two changes in skills/lark-doc/references/lark-doc-create.md:

1. 通用规则 (line 122): Reworded to clarify escaping is only needed when a character would trigger formatting syntax. Added concrete examples of when to escape vs not.

2. 最佳实践 (line 647): Synced the same clarification — escape only when formatting would be triggered.

Examples added

Context	Escape needed?	Why
\*text\*	✅ Yes	*...* triggers italic
5 * 3	❌ No	Lone * doesn't trigger formatting
final_trajectory	❌ No	_ inside a word doesn't trigger italic
version~1.0	❌ No	Lone ~ doesn't trigger strikethrough

Summary by CodeRabbit

• Documentation
  • Updated Lark-flavored Markdown escaping guidance: changed from universal escaping to conditional escaping based on whether a character triggers formatting.
  • Added explicit examples clarifying when asterisks, tildes, underscores, and other characters need escaping versus when they can remain unescaped.
  • Aligned the best-practices section with the new conditional-escaping rules.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e3c0f306-b6df-475f-9901-0d6a348adf11

📥 Commits

Reviewing files that changed from the base of the PR and between d1a364c and 0c54e2b.

📒 Files selected for processing (1)

• skills/lark-doc/references/lark-doc-create.md

🚧 Files skipped from review as they are similar to previous changes (1)

• skills/lark-doc/references/lark-doc-create.md

---

📝 Walkthrough

Walkthrough

Updated Lark-flavored Markdown escaping guidance: escaping is required only when a special character would trigger Lark formatting, not unconditionally. Enumerated escapable characters and clarified when *, ~, underscores, and others need backslashes, with examples to avoid over-escaping.

Changes

Cohort / File(s)	Summary
Lark Markdown Escape Documentation skills/lark-doc/references/lark-doc-create.md	Replaced blanket "always escape these characters" guidance with conditional rules: list of escapable characters plus context on when to escape (only when they would activate formatting). Clarified handling for *, ~, _, and similar cases and adjusted best-practice examples to prevent over-escaping by agents.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Suggested labels

documentation

Suggested reviewers

• fangshuyu-768
• haidaodashushu

Poem

🐰 I hopped through docs to make things right,
Escape when formatting gives a bite,
version~1.0 now hops free,
final_trajectory bounds with glee,
Clear text, no extra fright. 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: clarifying when escape characters are needed in Lark Markdown documentation to prevent agents from over-escaping.
Description check	✅ Passed	The PR description covers the problem (issue #155), the fix (two documentation sections updated with conditional escaping rules), and includes a helpful examples table. It aligns with the expected template structure.
Linked Issues check	✅ Passed	The PR directly addresses issue #155 by updating documentation to clarify that escaping is only needed when characters trigger formatting syntax, with concrete examples provided for both required and non-required escaping scenarios.
Out of Scope Changes check	✅ Passed	All changes are scoped to the Lark Markdown documentation file and directly address the stated objective of clarifying escape rules to prevent agent over-escaping.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR updates the escaping documentation in skills/lark-doc/references/lark-doc-create.md to prevent AI agents from over-escaping characters. The previous wording implied every listed special character always needed a backslash, causing agents to emit final\_trajectory, version\~1.0, and 5 \* 3 — strings that the Lark Markdown parser renders literally with the backslash. The fix rewrites the 通用规则 and 最佳实践 sections to clarify that escaping is only necessary when a character would actually trigger Markdown formatting syntax, and adds concrete before/after examples.

Key changes:

• 通用規則 (line 123): Replaces the flat character list with a conditional rule plus "needs escape / no escape needed" examples for *, ~, and _.
• 最佳实践 (line 647): Aligns with the same conditional phrasing; removes the misleadingly absolute \* \~ \` shorthand.
• Incidentally fixes the embedded-backtick rendering bug flagged in the previous review thread by using ` for the backtick character in the escapable-character list.

Confidence Score: 5/5

Documentation-only change that is safe to merge; it correctly narrows a misleading absolute rule to a context-dependent one.

Both changed sections are documentation text with no code logic. The rewording is accurate, the examples are correct, and the embedded-backtick rendering issue raised in the previous review thread has been fixed as a side effect. No new ambiguities are introduced.

No files require special attention.

Important Files Changed

Filename	Overview
skills/lark-doc/references/lark-doc-create.md	Rewrites two sections to clarify that backslash escaping is only required when a special character would actually trigger Markdown formatting syntax; adds concrete "escape / no-escape" examples and fixes the embedded-backtick rendering bug from the previous review thread.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Special character encountered
e.g. * ~ ` $ _ etc.] --> B{Would it trigger
Markdown formatting
if left unescaped?}
    B -- Yes --> C[Escape with backslash
e.g. \*text\* to prevent italic]
    B -- No --> D[Leave as-is — no backslash needed]

    C --> E["✅ Correct: \*不是斜体\*
✅ Correct: \~\~不是删除线\~\~"]
    D --> F["✅ Correct: 5 * 3
✅ Correct: final_trajectory
✅ Correct: version~1.0"]

Loading

_{Reviews (2): Last reviewed commit: "fix(lark-doc): use individual code spans..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@skills/lark-doc/references/lark-doc-create.md`:
- Line 123: The inline code span listing escape characters
("转义：仅当特殊字符会触发格式化语法时才需要反斜杠转义。支持转义的字符：`* ~ ` $ [ ] < > { } | ^`") is malformed
and triggers MD038; rewrite the list so each character is its own code span
(e.g., `*`, `~`, `` ` ``, `$`, `[` , `]`, `<`, `>`, `{`, `}`, `|`, `^`) or use a
double-backtick fenced span for the literal backtick (`` ` ``), ensuring no
internal spaces break the code spans and the backtick character is properly
escaped/rendered.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 79e6ddb2-c6ea-4f05-ade0-f8f02d08b1c7

📥 Commits

Reviewing files that changed from the base of the PR and between 112dd5f and d1a364c.

📒 Files selected for processing (1)

• skills/lark-doc/references/lark-doc-create.md

[CLAassistant]

All committers have signed the CLA.