Skip to content

docs: document citation XML syntax #2108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SunPeiYang996 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document citation XML syntax #2108

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion skills/lark-doc/references/lark-doc-xml.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
|-|-|-|
| `<cite type="user">` | @人 | XML 导入时必须显式传入 `user-id`：`<cite type="user" user-id="userID"></cite>` |
| `<cite type="doc">` | @文档 | `<cite type="doc" doc-id="docx_token"></cite>` |
| `<cite type="citation">` | 引文引用 | 一个 `<cite>` 内放入多个 `<a>`，标准写法见「Citation 引用」 |
| `<latex>` | 行内公式 | `<latex>E = mc^2</latex>` |
| `<img>` | 图片（可独立成块或内联） | `<img width="800" height="600" caption="说明" name="图.png" href="http 或 https"/>` |
| `<source>` | 文件附件（可独立成块或内联） | `<source name="报告.pdf"/>` |
Expand Down Expand Up @@ -82,6 +83,29 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
- 代码块必须写成 `<pre lang="xxx" caption="可选说明"><code>代码内容</code></pre>`。
- 不要将代码文本直接放在 `<pre>` 下；应放在内层 `<code>` 中。

## Citation 引用

使用一个 `<cite type="citation">` 包裹多条引用。每个 `<a>` 表示一条引用，必须填写真实 `href`、对应的 `url-type` 和数字序号文本；不要填写 `<cite>` 的 `id`。

```xml
<p>参考资料<cite type="citation">
<a href="https://example.com/article-1" url-type="5">1</a>
<a href="https://example.com/article-2" url-type="5">2</a>
</cite>。</p>
```

URL 查询参数中的 `&` 可以直接写，SDK 会兼容解析；序列化或回读时可能规范化为 `&amp;`。

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '--- locate file ---\n'
fd -a 'lark-doc-xml.md|lark-doc.xml|lark-doc' . | sed 's#^\./##' | head -100

printf '\n--- target excerpt ---\n'
file='skills/lark-doc/references/lark-doc-xml.md'
if [ -f "$file" ]; then
  wc -l "$file"
  sed -n '80,110p' "$file" | cat -n
else
  echo "missing $file"
fi

printf '\n--- nearby URL examples mentioning raw or escaped ampersand ---\n'
rg -n "query|URL|https?:|&amp;|\\?a=1&|b=2|查询参数|序列化|回读" "$file" || true

printf '\n--- all XML files mentioning lark-doc query examples ---\n'
rg -n "a=1&b=2|a=1&amp;b=2|\\?a=1&|\\?a=1&amp;b=2|query|查询参数" -g '*.xml' . | head -200 || true

Repository: larksuite/cli

Length of output: 242

🏁 Script executed:

#!/bin/bash
set -euo pipefail
printf '%s\n' '--- locate file ---'
fd -a 'lark-doc-xml.md|lark-doc.xml|lark-doc' . | sed 's#^\./##' | head -100 || true

printf '%s\n' ''
printf '%s\n' '--- target excerpt ---'
file='skills/lark-doc/references/lark-doc-xml.md'
if [ -f "$file" ]; then
  wc -l "$file"
  sed -n '80,110p' "$file" | cat -n
else
  echo "missing $file"
fi

printf '%s\n' ''
printf '%s\n' '--- nearby URL examples mentioning raw or escaped ampersand ---'
rg -n "query|URL|https?:|&amp;|\\?a=1&|b=2|查询参数|序列化|回读" "$file" || true

printf '%s\n' ''
printf '%s\n' '--- all XML files mentioning lark-doc query examples ---'
rg -n "a=1&b=2|a=1&amp;b=2|\\?a=1&|\\?a=1&amp;b=2|query|查询参数" -g '*.xml' . | head -200 || true

Repository: larksuite/cli

Length of output: 3444

🌐 Web query:

W3C XML ampersand entity character reference in attribute values not well-formed

💡 Result:

In XML, the ampersand character (&) must not appear in its literal form within attribute values [1][2]. According to the W3C XML specification, if an ampersand is needed, it must be escaped using either a predefined entity reference (e.g., &) or a numeric character reference (e.g., &#38;) [1][3][4]. Failing to escape an ampersand in an attribute value is a well-formedness error [1][2]. XML processors are required to report this as a fatal error, rendering the document not well-formed [5][6]. The constraint arises because the XML production for attribute values (AttValue) explicitly excludes the literal ampersand character, allowing it only as part of a reference [7]. This rule ensures that the parser can correctly identify the start and end of entity references and distinguish them from literal text [1][8]. The same requirement applies to the left angle bracket (<), which also cannot appear literally in attribute values [1][7]. Top results: [1], [2], [3], [4]

Citations:

Use the escaped query separator in XML examples.

In XML attribute values, a literal URL & is not well-formed; write query separators as ?a=1&amp;b=2. Put any SDK raw-& parsing support behind a compatibility note.

🤖 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-xml.md` at line 97, Update the XML URL
examples in the lark-doc reference to escape query separators as &amp; (for
example, ?a=1&amp;b=2) so the XML remains well-formed. Move the existing SDK
raw-& parsing behavior into a separate compatibility note rather than presenting
it as the example syntax.

Source: MCP tools


常用 `url-type`：

| 值 | 类型 | 说明 |
|-|-|-|
| `1` | `Doc` | 飞书文档 |
| `5` | `Outlink` / `Web` | 外部网页 |
| `6` | `Minutes` | 飞书妙记 |
| `12` | `Base` | 多维表格 |
| `13` | `Sheet` | 电子表格 |
| `14` | `Excel` | Excel 文件 |

## 用户名写入规则

Expand Down Expand Up @@ -174,7 +198,10 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr

<time expire-time="1775916000000" notify-time="1775912400000" should-notify="false">时间戳毫秒</time>

<cite type="citation"><a href="https://example.com">引文标题</a></cite>
<cite type="citation">
<a href="https://example.com/article-1" url-type="5">1</a>
<a href="https://example.com/article-2" url-type="5">2</a>
</cite>
Comment on lines +201 to +204

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Wrap the inline citation in <p>.

<cite> is documented as an inline component, and the standard example places it inside a paragraph. The complete example currently emits it at the document root, making the canonical example structurally inconsistent.

Proposed fix 
-<cite type="citation">
-  <a href="https://example.com/article-1" url-type="5">1</a>
-  <a href="https://example.com/article-2" url-type="5">2</a>
-</cite>
+<p><cite type="citation">
+  <a href="https://example.com/article-1" url-type="5">1</a>
+  <a href="https://example.com/article-2" url-type="5">2</a>
+</cite></p>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<cite type="citation">
<a href="https://example.com/article-1" url-type="5">1</a>
<a href="https://example.com/article-2" url-type="5">2</a>
</cite>
<p><cite type="citation">
<a href="https://example.com/article-1" url-type="5">1</a>
<a href="https://example.com/article-2" url-type="5">2</a>
</cite></p>
🤖 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-xml.md` around lines 201 - 204, Wrap the
inline citation example in a paragraph element so the cite component is nested
under <p> rather than emitted at the document root. Preserve the existing
citation links and attributes unchanged.

<bookmark name="书签标题" href="https://example.com"></bookmark>

<task task-id="TASK_GUID"></task>
Expand Down
Loading