feat: add comment-aware document fetch

[SunPeiYang996]

Summary

Add opt-in, AI-friendly visible comment context to docs +fetch while preserving the existing comment-free default and the existing IM Markdown behavior.

Contract

• --comments is effective only for non-outline reads and requires --format json plus --as bot.
• XML anchors use comment-refs="c1 c2"; Markdown uses <comment-ref refs="c1 c2"/>.
• Comment export supports only xml and markdown. im-markdown remains unchanged; an effective --comments --doc-format im-markdown combination is rejected before any API request.
• Local and whole-document discussions live in reference_map.comment and reference_map.document-comment.
• Full fetch returns local plus whole-document comments; partial fetch returns only intersecting local comments; outline performs no comment request.
• Historical revisions mean historical content plus the current visible unresolved comment snapshot projected onto that revision.

Implementation

• Send include_comments only when comments are effective and require the conditional comment-read scope.
• Reject lossy output, user-token, and IM Markdown comment combinations before any API request.
• Preserve precise marker associations in XML and Markdown, including lists and tables.
• Leave the production IM Markdown converter untouched.
• Add unit, mounted dry-run and gated self-contained live workflow coverage with document-before-folder cleanup.

Validation

• Remote build, full unit suite, vet, formatting, dependency tidiness, changed-line lint, script gates, example builds and plugin E2E.
• BOE boe_sun_ai_test real-document matrix: 15 local + 806 whole-document discussions with exact marker/sidecar closure in XML and Markdown.
• IM Markdown without comments is byte-for-byte identical before and after the boundary correction on the real BOE document.
• --comments --doc-format im-markdown returns a typed --doc-format validation error before the request.
• Full integration packages for docs and IM passed. Two unrelated Drive live cleanup cases were blocked by the test app missing drive:drive / space:document:delete; no comment-fetch package failed.
• Full CI, CodeQL, CodeRabbit, and Codecov passed for head 0377b32d (evidence: CI 31239377111, CodeQL 31239322520).

Dependencies and boundaries

• SDK MR: https://code.byted.org/lark/office_ai_sdk/merge_requests/210
• ai_edit MR: https://code.byted.org/ccm-platform/ai_edit/merge_requests/197
• DevFlow: https://devflow.bytedance.net/space/0/task/474859/develop?tabKey=Develop
• No Engine, IDL, generated code or OGW change.
• The SDK reuses Engine's existing revision-aware OpenAPIListBlockByCommentIDs only for comment-ID-to-block association. Comment headers and discussion content come from the comment service (GetCommentByNote and APIBatchGetComment).
• User tokens remain fail-closed until a trusted conditional scope contract exists.

Related Issues

• None

[coderabbitai]

📝 Walkthrough

Walkthrough

Docs fetch now supports opt-in comment retrieval. Validation enforces compatible output, identity, document format, and scope settings. Tests cover request construction and rendered comment references. Documentation describes the new option and response structure.

Changes

Document comment fetching

Layer / File(s)	Summary
Fetch comment control shortcuts/doc/docs_fetch.go, shortcuts/doc/docs_fetch_v2.go	Adds the --comments option, comment-aware request parameters, validation rules, outline suppression, and conditional comment-read scope metadata.
Fetch validation and parameter tests shortcuts/doc/docs_fetch_v2_test.go	Tests output, document format, identity, scope, effective-scope, and runtime flag behavior.
End-to-end comment output tests/cli_e2e/docs/docs_fetch_comments_workflow_test.go, tests/cli_e2e/docs/docs_fetch_dryrun_test.go	Verifies opt-in comment retrieval, scope filtering, XML and Markdown markers, reference sidecars, dry-run payloads, and pre-request validation.
Comment fetch documentation skills/lark-doc/SKILL.md, skills/lark-doc/references/lark-doc-fetch.md	Documents authentication, output requirements, response structures, filtering, authorization, and standalone comment operations.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant DocsFetchV2
  participant DocsAPI
  CLI->>DocsFetchV2: pass --comments
  DocsFetchV2->>DocsFetchV2: validate format, identity, and scope
  DocsFetchV2->>DocsAPI: send include_comments
  DocsAPI-->>DocsFetchV2: return document and comment data
  DocsFetchV2-->>CLI: render document with comment references

Loading

Possibly related PRs

• larksuite/cli#2189: Both changes modify shortcuts/doc/docs_fetch_v2_test.go.

Suggested labels: documentation

Suggested reviewers: evandance

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.76% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding comment-aware document fetching.
Description check	✅ Passed	The description is detailed and covers the change scope, implementation, validation, dependencies, and related issues.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sun/docx-fetch-comments

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.37%. Comparing base (13305ae) to head (0377b32).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2244      +/-   ##
==========================================
- Coverage   76.41%   76.37%   -0.04%     
==========================================
  Files        1010     1011       +1     
  Lines      111104   111301     +197     
==========================================
+ Hits        84895    85002     +107     
- Misses      19737    19815      +78     
- Partials     6472     6484      +12     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[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-fetch.md`:
- Line 117: 更新 lark-doc 的格式说明，删除对未在参数表中列出的 table 格式的引用；若 CLI 实际支持
table，则同步将其加入参数表并确保相关格式校验与文档契约一致。

In `@tests/cli_e2e/docs/docs_fetch_comments_workflow_test.go`:
- Around line 42-46: Register t.Cleanup immediately after creating the document
and folder in the test workflow, using the existing document and folder
identifiers to delete the document first and then the folder. Ensure cleanup
runs whether assertions pass or fail, while preserving the current
comment-creation and verification flow.

🪄 Autofix

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: f2adbc6f-abe1-4dbe-a71a-d273b30d84aa

📥 Commits

Reviewing files that changed from the base of the PR and between 13305ae and 1d4c46a.

📒 Files selected for processing (8)

• shortcuts/doc/docs_fetch.go
• shortcuts/doc/docs_fetch_im_markdown_test.go
• shortcuts/doc/docs_fetch_v2.go
• shortcuts/doc/docs_fetch_v2_test.go
• skills/lark-doc/SKILL.md
• skills/lark-doc/references/lark-doc-fetch.md
• tests/cli_e2e/docs/docs_fetch_comments_workflow_test.go
• tests/cli_e2e/docs/docs_fetch_dryrun_test.go

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#sun/docx-fetch-comments -y -g

[SunPeiYang996]

交付状态更新（本条替代此前摘要中的 IM Markdown 表述）：

• 评论导出仅支持 XML / Markdown；有效的 --comments --doc-format im-markdown 组合会在请求前返回结构化校验错误。
• 生产 IM Markdown 转换器没有改动；不带评论时，新旧二进制对 BOE 真实测试文档的 IM Markdown 输出逐字节一致。
• 当前 head 0377b32d。BOE 实测仍返回 15 条局部评论、806 条全文评论，XML / Markdown 的 marker 与 sidecar 精确闭合。
• 没有修改 Engine、IDL、generated code 或 OGW。SDK 仅复用 Engine 既有 OpenAPIListBlockByCommentIDs 做 revision-aware 锚点关联；评论正文来自评论服务 GetCommentByNote / APIBatchGetComment。
• 完整报告仍在：https://hegqugfrkb.feishu-boe.cn/docx/IccjdLV6SoeXSOxWqsdbZ3bMche（正在同步修正文案与最新 CI 结果）。