docs: document citation XML syntax - #2108
Conversation
github-actions
Bot
added
domain/ccm
📝 WalkthroughWalkthroughChangesCitation documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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.
Inline comments:
In `@skills/lark-doc/references/lark-doc-xml.md`:
- Around line 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.
- Line 97: Update the XML URL examples in the lark-doc reference to escape query
separators as & (for example, ?a=1&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.
🪄 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 Plus
Run ID: 849805aa-d593-41d4-b771-741537e61792
📒 Files selected for processing (1)
skills/lark-doc/references/lark-doc-xml.md
| </cite>。</p> | ||
| ``` | ||
|
|
||
| URL 查询参数中的 `&` 可以直接写，SDK 会兼容解析；序列化或回读时可能规范化为 `&`。 |
There was a problem hiding this comment.
🎯 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?:|&|\\?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&b=2|\\?a=1&|\\?a=1&b=2|query|查询参数" -g '*.xml' . | head -200 || trueRepository: 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?:|&|\\?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&b=2|\\?a=1&|\\?a=1&b=2|query|查询参数" -g '*.xml' . | head -200 || trueRepository: 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., &) [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:
- 1: https://www.w3.org/TR/xml/
- 2: https://www.w3.org/TR/xml11/
- 3: https://www.w3.org/TR/REC-xml/
- 4: https://stackoverflow.com/questions/14500800/how-can-i-include-an-ampersand-character-in-an-xml-document
- 5: https://www.w3.org/TR/2008/PER-xml-20080205/
- 6: https://www.w3.org/TR/2000/REC-xml-20001006.html
- 7: https://stackoverflow.com/questions/64547696/finding-the-xml-element-attribute-with-the-max-value-causes-parse-error
- 8: https://www.w3.org/XML/Datamodel.html
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&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 & (for
example, ?a=1&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
| <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> |
There was a problem hiding this comment.
🎯 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.
| <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.
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@866721f799167923e0609dac7c56497ae8591141🧩 Skill updatenpx skills add SunPeiYang996/cli#sun/docs-citation-syntax -y -g |
1 participant
Summary
Document the canonical DocxXML citation syntax so agents can author stable multi-reference citations with explicit URL metadata.
Changes
cite type="citation"to the inline component reference.href,url-type, and numeric labels.url-typevalues used for docs, web links, Minutes, Base, Sheets, and Excel.&in URL query parameters is accepted by the SDK and may be normalized to&on serialization or fetch.Test Plan
node scripts/skill-format-check/index.jsxmllint --nooutfor the multi-reference citation examplegit diff --checkRelated Issues
Summary by CodeRabbit