docs: clarify lark doc warning prevention

[fangshuyu-768]

Summary

Clarify the lark-doc skill guidance for warning-prone DocxXML creation and update flows identified in the warning audit. The change focuses on preventing invalid or ambiguous inputs before they reach the CLI or service.

Changes

• Document mandatory XML text escaping, supported-tag alternatives, callout/list/table constraints, image-source handling, and safe Mermaid label syntax.
• Require a single title source and explain str_replace uniqueness/no-op behavior plus block-ID lifecycle rules.
• Clarify permission-error handling without treating wiki URLs or dry-run success as proof of write access.

Test Plan

• make fmt-check
• go vet ./...
• go mod tidy produces no changes
• golangci-lint ... --new-from-rev=origin/main reports 0 issues
• Relevant lark-doc and CLI packages pass in the full race run
• Full make unit-test completes cleanly in this local environment; unrelated tests that create temporary Git repositories intermittently fail during t.TempDir cleanup with .git: directory not empty

Related Issues

• Warning audit: https://bytedance.larkoffice.com/docx/PtjSdwpK0oMLoVxiTq2cYkuunPd

Summary by CodeRabbit

• Documentation
  • Clarified guidance for write failures due to missing edit permissions (4030004_no_document_permission), including when to stop retrying and how to request or relocate content for editing.
  • Updated +create guidance for authoritative --title usage when XML already includes <title>, and reinforced title-source checks.
  • Expanded +update guidance: XML escaping rules, block ID lifecycle constraints, str_replace edge cases, and interpreting result/warnings (including zero updated blocks).
  • Refined lark-doc-whiteboard responsibilities and added a concrete Mermaid example with stricter validation/quoting rules.
  • Strengthened lark-doc-xml formatting rules: escaping, supported tags, <callout> boundaries, list and ordering behavior, and image/link requirements with clearer examples.

[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: af62facb-ebb9-4cfc-86d2-ee3ace9d4d6c

📥 Commits

Reviewing files that changed from the base of the PR and between 5b81f94 and cbaeaa3.

📒 Files selected for processing (2)

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

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

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

---

📝 Walkthrough

Walkthrough

Changes

Lark-doc guidance updates

Layer / File(s)	Summary
Permission failure guidance skills/lark-doc/SKILL.md	Documents ACL diagnosis and remediation for 4030004_no_document_permission, including avoiding retries and permission probes.
Create title contract skills/lark-doc/references/lark-doc-create.md	Requires a single title source and distinguishes --title from XML <title>.
Update write and result guidance skills/lark-doc/references/lark-doc-update.md	Adds XML escaping, current block ID validation, replacement matching, no-op handling, and result interpretation rules.
XML and whiteboard content rules skills/lark-doc/references/lark-doc-xml.md, skills/lark-doc/references/lark-doc-whiteboard.md	Clarifies XML escaping, nesting, lists, image URLs, complete examples, Mermaid syntax, label quoting, and validation.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• larksuite/cli#1474: Updates related document title-source guidance.
• larksuite/cli#1466: Covers related Block ID lifecycle guidance.
• larksuite/cli#1701: Updates related Mermaid and whiteboard responsibility guidance.

Suggested reviewers: sunpeiyang996

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately reflects the documentation-focused warning-prevention changes.
Description check	✅ Passed	The description follows the template and includes summary, changes, test plan, and related issues with enough detail.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs-lark-doc-warning-guidance

---

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.}

[coderabbitai]

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-update.md`:
- Around line 204-209: Revise the general warning guidance in the “结果判读” section
so agents inspect each warning before assuming any document mutation occurred.
Preserve the specific no-op handling for 1011_no_document_changes and clarify
that success or partial_success with warnings may represent either completed
writes or no changes, depending on the warning.

In `@skills/lark-doc/references/lark-doc-whiteboard.md`:
- Around line 41-49: 明确调整白板内容职责说明：仅对 SVG、复杂图表和现有白板更新强制委派；允许主代理直接插入简单 Mermaid
内容。同步检查相关职责表与 Mermaid 插入说明，消除两者冲突，并保留 Mermaid 语法验证要求。

🪄 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: aaedebda-5ef1-416b-85d1-3cd4bc98ae00

📥 Commits

Reviewing files that changed from the base of the PR and between 80323bb and 0aeb54f.

📒 Files selected for processing (5)

• skills/lark-doc/SKILL.md
• skills/lark-doc/references/lark-doc-create.md
• skills/lark-doc/references/lark-doc-update.md
• skills/lark-doc/references/lark-doc-whiteboard.md
• skills/lark-doc/references/lark-doc-xml.md

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@cbaeaa3b6f928431fb930859d08075dd4d271634

🧩 Skill update

npx skills add larksuite/cli#codex/docs-lark-doc-warning-guidance -y -g