docs(doc): clarify formula rendering

skills/lark-doc/SKILL.md

@@ -49,6 +49,7 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
 - 用户明确要操作思维笔记时；已有**思维笔记**，走 [思维笔记链路](references/lark-doc-mindnote.md)；新建**思维笔记**，走 [lark-doc-whiteboard](references/lark-doc-whiteboard.md)
 - 拿到 spreadsheet URL/token 后 → 切到 `lark-sheets` 做对象内部操作
 - 用户需要统计文档的**总字数 / 总字符数**（word count / character count）时，先读取 [`lark-doc-word-stat.md`](references/lark-doc-word-stat.md)，并按其中流程调用 [`scripts/doc_word_stat.py`](scripts/doc_word_stat.py)；统计口径以该脚本为准，不要改用其他方式自行计算。
+- 文档包含数学公式时，先按所选格式读取对应公式规则：XML 使用 `<latex>...</latex>`，**禁止**把 `$...$`、`$$...$$`、`\(...\)` 或 `\[...\]` 原样写入 XML；Markdown 才使用 `$...$`。含 `$` 或反斜杠的内容优先通过相对 `@file` 传入，避免 Shell 改写公式。详见 [`lark-doc-xml.md`](references/lark-doc-xml.md#公式) / [`lark-doc-md.md`](references/lark-doc-md.md#数学公式)。
 - 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 reaction" → 切到 `lark-drive` 处理
 - 文档内容中出现嵌入的 `<sheet>`、`<bitable>` 或 `<cite file-type="sheets|bitable">` 标签时 → **必须主动提取 token 并切到对应技能下钻读取内部数据**，不能只呈现标签本身
 

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

@@ -2,6 +2,23 @@
 
 `docs +fetch` / `docs +create` / `docs +update` 使用 `--doc-format markdown` 时适用；fetch 的 `--doc-format im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用，不作为 create/update 写入格式。
 
+## 数学公式
+
+Markdown 模式使用 `$...$` 写公式。不要使用代码反引号包裹公式，否则只会显示源码。
+
+```markdown
+行内公式：$E = mc^2$
+
+独立成段的公式：
+
+$\int_0^1 x^2\,dx = \frac{1}{3}$
+```
+
+- 只有命令显式使用 `--doc-format markdown` 时才依赖 `$...$` 解析；默认 XML 模式应改写为 `<latex>...</latex>`。
+- 字面量美元符号写成 `\$`，例如 `价格 \$100`。
+- 含 `$` 或反斜杠的内容优先保存到当前工作目录下的 `.md` 文件，再使用相对 `--content @formula.md` 传入，避免 Shell 展开或吞掉字符。
+- 写入后用 `docs +fetch --doc-format xml --detail full` 回读目标内容，确认公式已成为 `<latex>...</latex>` 节点。
+
 ## 转义规则
 
 > **⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时**，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。

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

@@ -36,6 +36,28 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 - `align` — `"left"`|`"center"`|`"right"`（适用于 p / h1-h9 / li / checkbox）
 - 有序列表项用 `seq="auto"` 自动编号
 
+## 公式
+
+XML 模式只把 `<latex>...</latex>` 转换为飞书公式节点。Markdown / LaTeX 定界符 `$...$`、`$$...$$`、`\(...\)`、`\[...\]` 在 XML 模式下都是普通文本，原样写入会在文档中显示源码而不是渲染后的公式。
+
+- 行内公式：`<p>质能方程为 <latex>E = mc^2</latex>。</p>`
+- 独立公式：将 `<latex>` 放在单独段落中，例如 `<p><latex>\int_0^1 x^2\,dx = \frac{1}{3}</latex></p>`
+- 只写 LaTeX 表达式本体，不要把 `$`、`$$`、`\(`、`\)`、`\[`、`\]` 包进 `<latex>`。
+- 公式正文仍属于 XML 文本。LaTeX 中的 `&`、`<`、`>` 必须分别写成 `&amp;`、`&lt;`、`&gt;`。
+- 不要把公式放进 `<pre>` 或 `<code>`；代码块只会显示公式源码。
+- 内容含反斜杠时，优先把完整 XML 保存到当前工作目录下的文件，并通过相对路径传入：`--content @formula.xml`。不要使用绝对 `@file` 路径。
+
+常见定界符转换：
+
+| 输入形式 | XML 写法 |
+|-|-|
+| `$E = mc^2$` | `<latex>E = mc^2</latex>` |
+| `$$\sum_{i=1}^{n} i$$` | `<p><latex>\sum_{i=1}^{n} i</latex></p>` |
+| `\(\alpha + \beta\)` | `<latex>\alpha + \beta</latex>` |
+| `\[\frac{a}{b}\]` | `<p><latex>\frac{a}{b}</latex></p>` |
+
+写入后用 `docs +fetch --doc-format xml --detail full` 回读目标内容，确认返回的是 `<latex>...</latex>` 节点，而不是带定界符的普通文本。
+
 # 三、资源块
 
 文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：