feat: add drive list comments shortcut

[wittam-01]

Summary

Add drive +list-comments as the preferred shortcut for listing document comments. The shortcut accepts URLs or token/type inputs, unwraps Wiki tokens to the underlying document token/type, and exposes explicit filters for solved status, comment scope, pagination, reactions, and docx relation data.

Changes

• Add drive +list-comments with URL parsing, Wiki node resolution, typed validation, dry-run orchestration, and structured output.
• Add unit coverage for input parsing, parameter mapping, docx execution, Wiki-to-docx execution, and registry inclusion.
• Add dry-run E2E coverage for docx defaults and Wiki token orchestration.
• Update lark-drive skills to prefer drive +list-comments, document URL-first usage, Wiki support, --solved-status, --comment-scope, and non-docx --need-relation behavior.
• Extend the opt-in comment workflow to list back a created comment when live file-comment E2E is enabled.

Test Plan

• Focused unit tests pass:
  go test ./shortcuts/drive -run 'Test(ResolveDriveListCommentsInput|BuildDriveListCommentsParams|DriveListCommentsExecuteDocx|DriveListCommentsExecuteWikiResolvesToDocx|ShortcutsIncludesExpectedCommands)$'
• Dry-run E2E passes:
  go test -count=1 ./tests/cli_e2e/drive -run 'TestDriveListCommentsDryRun'
• Manual live verification confirms the lark-cli drive +list-comments flow works as expected.
  Test report and retained test data: https://bytedance.larkoffice.com/wiki/ChV2wyAwdiIXfPkyMKncn4idnnf

Related Issues

• None

Summary by CodeRabbit

• New Features
  • Added drive +list-comments to list document comments using --url or --token (with wiki auto-resolution), including pagination and filters for solved status and comment scope.
  • Added --need-relation to return DOCX-specific comment location/relationship details (non-DOCX types ignore it).
• Tests
  • Added unit + CLI e2e coverage for validation, parameter generation, DOCX vs wiki flows, and --dry-run request plans.
• Documentation
  • Updated Drive comments guides and added a dedicated “list comments” reference, including default behaviors and --need-relation limitations.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds the drive +list-comments shortcut for listing Drive comments from URLs or tokens, resolving wiki inputs, applying filters and pagination, returning normalized output, and documenting and testing the command. Drive delete verification also gains retry handling for retryable failures.

Changes

Drive list-comments shortcut

Layer / File(s)	Summary
Shortcut contract and execution flow shortcuts/drive/drive_list_comments.go	Defines DriveListComments with validation, dry-run, execution, normalized output, and wiki orchestration.
Input resolution and request construction shortcuts/drive/drive_list_comments.go	Parses URL/token inputs, normalizes types, resolves wiki targets, and builds conditional comments API parameters.
Unit validation and execution coverage shortcuts/drive/drive_list_comments_test.go	Tests input parsing, validation, parameter construction, direct DOCX execution, and wiki-to-DOCX execution.
Shortcut registration and CLI coverage shortcuts/drive/shortcuts.go, shortcuts/drive/shortcuts_test.go, tests/cli_e2e/drive/*	Registers the shortcut and adds registry, dry-run, workflow, and coverage validation.
Drive delete retry coverage tests/cli_e2e/drive/helpers.go, tests/cli_e2e/drive/helpers_test.go	Retries Drive delete verification on retryable results and tests simulated contention and empty metadata responses.
Command usage documentation skills/lark-drive/SKILL.md, skills/lark-drive/references/*	Documents inputs, filters, pagination, dry-run behavior, wiki resolution, and DOCX-only relation fields.

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

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant DriveListComments
  participant WikiAPI
  participant DriveCommentsAPI
  CLI->>DriveListComments: Execute with URL or token
  DriveListComments->>WikiAPI: Resolve wiki target when needed
  WikiAPI-->>DriveListComments: Return underlying token and type
  DriveListComments->>DriveCommentsAPI: List comments with filters
  DriveCommentsAPI-->>DriveListComments: Return comments and pagination
  DriveListComments-->>CLI: Emit normalized output

Loading

Possibly related PRs

• larksuite/cli#470: Updates the Drive shortcut registry and expected command list.
• larksuite/cli#609: Updates Drive comment-listing guidance around unresolved and solved comments.

Suggested labels: size/XL, domain/ccm

Suggested reviewers: liangshuo-1, SunPeiYang996

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% 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
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding the Drive list-comments shortcut.
Description check	✅ Passed	The description matches the required template and includes summary, changes, test plan, and related issues.
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 feat/drive-list-comments-shortcut

---

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

❌ Patch coverage is 68.75000% with 60 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.57%. Comparing base (1ab8530) to head (9274025).

Files with missing lines	Patch %	Lines
shortcuts/drive/drive_list_comments.go	68.58%	47 Missing and 13 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1845      +/-   ##
==========================================
- Coverage   74.58%   74.57%   -0.02%     
==========================================
  Files         863      864       +1     
  Lines       90123    90315     +192     
==========================================
+ Hits        67220    67352     +132     
- Misses      17696    17743      +47     
- Partials     5207     5220      +13     

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#feat/drive-list-comments-shortcut -y -g

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

shortcuts/drive/drive_list_comments_test.go (1)

128-142: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider adding dedicated tests for validateDriveListCommentsSpec error paths.

The validation function covers four error paths (invalid page-size, invalid solved-status, invalid comment-scope, invalid user-id-type), but none are directly tested. While the happy paths are indirectly covered through the execution tests, the error paths have no coverage. Adding a small table-driven test would ensure these validations don't regress.

🤖 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 `@shortcuts/drive/drive_list_comments_test.go` around lines 128 - 142, The
current tests cover the happy path for buildDriveListCommentsParams, but
validateDriveListCommentsSpec error branches are untested. Add a small
table-driven test that calls validateDriveListCommentsSpec directly and asserts
errors for the four invalid cases: page-size, solved-status, comment-scope, and
user-id-type. Keep it close to the existing drive list comments tests so the new
coverage is easy to find alongside buildDriveListCommentsParams.

Source: Coding guidelines

🤖 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 `@shortcuts/drive/drive_list_comments_test.go`:
- Around line 75-79: The error assertions in TestResolveDriveListCommentsInput
only check the message substring, but the validation paths in
resolveDriveListCommentsInput return typed errs.NewValidationError values.
Update the test to use errors.As against *errs.ValidationError and assert the
expected Category, SubtypeInvalidArgument, Param, and that the cause is
preserved, while keeping the existing message check if needed. Add the required
errors and github.com/larksuite/cli/errs imports so the test validates typed
metadata instead of relying on strings.Contains alone.

In `@skills/lark-drive/references/lark-drive-comments-guide.md`:
- Around line 68-69: Update the `drive +list-comments` guidance in the comments
guide to make it clear that “all comments” only applies when `--solved-status
all` is passed; otherwise the shortcut defaults to unresolved comments. Adjust
the wording in the `+list-comments` description so it does not imply
full-history counting, sorting, or “latest/last N” retrieval by default, while
keeping the distinction from the raw `drive file.comments list` command.

---

Nitpick comments:
In `@shortcuts/drive/drive_list_comments_test.go`:
- Around line 128-142: The current tests cover the happy path for
buildDriveListCommentsParams, but validateDriveListCommentsSpec error branches
are untested. Add a small table-driven test that calls
validateDriveListCommentsSpec directly and asserts errors for the four invalid
cases: page-size, solved-status, comment-scope, and user-id-type. Keep it close
to the existing drive list comments tests so the new coverage is easy to find
alongside buildDriveListCommentsParams.

🪄 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: 38db4354-78e2-42d6-96ee-fc8be4e9bc11

📥 Commits

Reviewing files that changed from the base of the PR and between b1205b6 and 5fbabc7.

📒 Files selected for processing (11)

• shortcuts/drive/drive_list_comments.go
• shortcuts/drive/drive_list_comments_test.go
• shortcuts/drive/shortcuts.go
• shortcuts/drive/shortcuts_test.go
• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-comment-location.md
• skills/lark-drive/references/lark-drive-comments-guide.md
• skills/lark-drive/references/lark-drive-list-comments.md
• tests/cli_e2e/drive/coverage.md
• tests/cli_e2e/drive/drive_add_comment_workflow_test.go
• tests/cli_e2e/drive/drive_list_comments_dryrun_test.go

[coderabbitai]

Actionable comments posted: 1

🤖 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-drive/SKILL.md`:
- Around line 84-91: The 评论能力入口 section only documents URL and file_token
inputs; update it to document the exact raw token/type invocation supported by
+list-comments. Clarify that raw Wiki tokens require the Wiki type and differ
from the underlying file token, while preserving the existing URL
auto-resolution guidance.

🪄 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: b6cf4de2-9464-456f-a48d-9fbb86e570da

📥 Commits

Reviewing files that changed from the base of the PR and between bbaaeff and 35d130c.

📒 Files selected for processing (13)

• shortcuts/drive/drive_list_comments.go
• shortcuts/drive/drive_list_comments_test.go
• shortcuts/drive/shortcuts.go
• shortcuts/drive/shortcuts_test.go
• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-comment-location.md
• skills/lark-drive/references/lark-drive-comments-guide.md
• skills/lark-drive/references/lark-drive-list-comments.md
• tests/cli_e2e/drive/coverage.md
• tests/cli_e2e/drive/drive_add_comment_workflow_test.go
• tests/cli_e2e/drive/drive_list_comments_dryrun_test.go
• tests/cli_e2e/drive/helpers.go
• tests/cli_e2e/drive/helpers_test.go

✅ Files skipped from review due to trivial changes (3)

• shortcuts/drive/shortcuts.go
• tests/cli_e2e/drive/coverage.md
• skills/lark-drive/references/lark-drive-comment-location.md

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

• skills/lark-drive/references/lark-drive-list-comments.md
• tests/cli_e2e/drive/drive_add_comment_workflow_test.go
• shortcuts/drive/shortcuts_test.go
• skills/lark-drive/references/lark-drive-comments-guide.md
• tests/cli_e2e/drive/drive_list_comments_dryrun_test.go
• shortcuts/drive/drive_list_comments_test.go
• shortcuts/drive/drive_list_comments.go