docs(doc): clarify formula rendering

[Alpha-Girl]

Summary

Clarify formula authoring in the lark-doc Skill so agents do not write Markdown/LaTeX delimiters as literal text when docs +create or docs +update uses the default XML format.

The root cause is that native <latex>...</latex> support was only mentioned in the XML component table, while the format-dependent conversion rule was not prominent. This change makes the XML and Markdown paths explicit and adds a post-write verification step.

Changes

• Add a formula-routing rule to skills/lark-doc/SKILL.md.
• Document XML conversion from $...$, $$...$$, \(...\), and \[...\] to native <latex> nodes.
• Add inline and standalone formula examples, XML escaping guidance, and relative @file input guidance.
• Clarify Markdown formula syntax and recommend XML fetch verification after writes.

Test Plan

• Unit tests pass — not run; this is a documentation-only Skill change.
• node scripts/skill-format-check/index.js
• git diff --check
• Manual live-tenant verification of the lark-cli docs +create/+update flow — not run; requires Feishu/Lark tenant access.

Related Issues

• Closes docs(lark-doc): clarify formula rendering for XML document writes #2042

Summary by CodeRabbit

• Documentation
  • Added guidance for writing and exporting Markdown content, including mathematical formulas, escaping, images, and unsupported block types.
  • Documented XML formula syntax using <latex>...</latex>, including escaping and validation requirements.
  • Added quick-decision guidance for selecting the appropriate formula format and safely passing formula content.

[coderabbitai]

📝 Walkthrough

Walkthrough

本次变更完善 lark-doc 的公式处理文档，区分 XML 与 Markdown 语法，并补充转义、Shell 传参、图片、非原生 Markdown 块及写入后验证规则。

Changes

公式与文档格式规范

Layer / File(s)	Summary
格式相关公式规则 skills/lark-doc/SKILL.md, skills/lark-doc/references/lark-doc-xml.md, skills/lark-doc/references/lark-doc-md.md	明确 XML 使用 <latex>...</latex>，Markdown 使用 $...$，补充公式转义限制、Shell-safe 文件传入方式及写入后回读验证。
Markdown 内容与传参说明 skills/lark-doc/references/lark-doc-md.md	新增 Markdown 转义、Shell 传参、图片语法、非原生块类型和 XML 参考入口说明。

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• larksuite/cli#312：同样调整 lark-doc 中 Markdown 转义与反斜杠规则。
• larksuite/cli#1508：同样更新 SKILL.md 的任务路径和文档读取规则。
• larksuite/cli#2002：同样补充 XML 特殊字符与转义规范。

Suggested reviewers: liangshuo-1

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main documentation change about formula rendering.
Description check	✅ Passed	The description follows the template and includes summary, changes, test plan, and related issue details.
Linked Issues check	✅ Passed	The changes address #2042 by clarifying XML vs Markdown formula handling, examples, escaping, @file guidance, and verification.
Out of Scope Changes check	✅ Passed	The modifications stay within the documented lark-doc formula-rendering guidance and do not introduce unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Copilot]

Pull request overview

This PR updates the lark-doc Skill documentation to prevent agents from writing Markdown/LaTeX delimiters as literal text when using the default XML document format, and to make formula authoring/verification rules explicit for both XML and Markdown modes.

Changes:

• Adds a high-level “formula routing” rule to the Skill’s quick-decision section to distinguish XML (<latex>...</latex>) vs Markdown ($...$) behavior.
• Adds an XML formula section explaining <latex> usage, escaping requirements, and a post-write docs +fetch --doc-format xml --detail full verification step.
• Adds a Markdown formula section with inline/standalone examples, escaping guidance for literal $, and @file guidance for shell safety.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
skills/lark-doc/SKILL.md	Adds a top-level decision rule for formula handling across XML vs Markdown paths.
skills/lark-doc/references/lark-doc-xml.md	Documents XML-specific formula syntax using <latex> and recommends post-write verification.
skills/lark-doc/references/lark-doc-md.md	Documents Markdown formula syntax and recommends verification via XML fetch after writes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

skills/lark-doc/references/lark-doc-md.md (1)

32-33: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Correct the expected output for escaped * and _.

Markdown uses the backslash only in the input; rendering removes it. The examples currently show 3 \* 5 = 15 and foo\_bar\_baz as outputs, which teaches users that the escape remains visible.

Proposed correction

-| `*` | 斜体 / 加粗 | `\*` | `3 \* 5 = 15` → 3 \* 5 = 15 |
+| `*` | 斜体 / 加粗 | `\*` | `3 \* 5 = 15` → 3 * 5 = 15 |
-| `_` | 斜体 / 加粗 | `\_` | `foo\_bar\_baz` → foo\_bar\_baz |
+| `_` | 斜体 / 加粗 | `\_` | `foo\_bar\_baz` → foo_bar_baz |

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-doc/references/lark-doc-md.md` around lines 32 - 33, Update the
expected-output examples in the escaping table for `*` and `_`: retain the
backslashes only in the input column, and show rendered outputs as `3 * 5 = 15`
and `foo_bar_baz` without escape characters.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@skills/lark-doc/references/lark-doc-md.md`:
- Around line 32-33: Update the expected-output examples in the escaping table
for `*` and `_`: retain the backslashes only in the input column, and show
rendered outputs as `3 * 5 = 15` and `foo_bar_baz` without escape characters.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0f9c3a4e-a846-41d2-8533-3a63ed38f193

📥 Commits

Reviewing files that changed from the base of the PR and between 5a54bc0 and cc9d98c.

📒 Files selected for processing (3)

• skills/lark-doc/SKILL.md
• skills/lark-doc/references/lark-doc-md.md
• skills/lark-doc/references/lark-doc-xml.md

[SunPeiYang996]

Thanks for the contribution and for documenting this edge case.

The issue is valid, but it appears to be a very low-probability edge case. We do not want to keep patching the Skill for every boundary scenario: doing so would make the Skill unnecessarily large and increase maintenance and model-reading costs.

For now, we will not merge this PR and will close it. If we keep a reminder, please reduce the change to a single sentence:

Markdown syntax is not supported in XML mode; we plan to improve this in the next release.

We can revisit the documentation when XML mode supports Markdown syntax at the product level. Thanks for understanding.