feat: migrate application and IM guidance to affordance

[liangshuo-1]

Summary

Migrate Application and IM command-selection guidance from legacy Go Tips into structured affordance overlays, so AI agents see source-backed examples, decision guidance, and safety prerequisites directly in leaf help and schema output. Runtime permission and recovery guidance remains owned by typed CLI errors instead of being duplicated in static help.

Changes

• Add affordance entries for all 4 Application shortcuts, all 21 IM shortcuts, and 12 raw IM methods with copyable examples verified against the current lark-im skill sources.
• Move the remaining Application examples and IM chat-member operational tips out of Go Tips, with contract tests that prevent guidance from drifting back into mixed sources.
• Preserve identity and safety intent: dual-identity examples stay neutral, user-only examples are explicit, outbound actions require confirmed target/content/identity, and destructive operations retain confirmation boundaries.
• Pin im images create's structured user-and-bot access-token contract without changing the IM skills, and make the reactions batch-query example a valid first-page request without a placeholder page token.
• Add source-trace, relationship, help-rendering, required-flag, identity, and recovery regression coverage.

Test Plan

• Unit tests pass (make unit-test)
• Manual local verification confirms the lark-cli <domain> <command> flow works as expected
• go vet ./...
• go mod tidy leaves go.mod and go.sum unchanged
• Clean-clone gofmt -l . produces no output
• Clean-clone golangci-lint reports 0 issues against the latest main
• make quality-gate QUALITY_GATE_CHANGED_FROM=origin/main passes (two existing bounded-list warnings only)
• 37/37 leaf help pages render the audited example exactly; 57/57 meaningful bot/user dry-run variants pass
• Application and IM dry-run E2E suites pass
• Five help-only agent evaluations complete 62/62 positive dry-run attempts and recover from wrong identity, malformed JSON, and missing confirmation

No live API writes were performed; this change affects help/affordance guidance and its contracts.

Review Notes

The fetched metadata description for im images create still says bot-only even though its structured accessTokens, schema, flags, and user dry-run all support both user and bot. This mismatch is pre-existing in the generated metadata source, is not introduced by this PR, and should be corrected there separately rather than by editing lark-im or duplicating recovery text in affordance.

Related Issues

• None

Summary by CodeRabbit

• New Features
  • Added CLI guidance for listing, creating, updating, and deleting application slash commands.
  • Added a comprehensive IM skill guide covering chats, messages, threads, media, reactions, bookmarks, and feed shortcuts.
• Bug Fixes
  • Improved slash-command creation conflict messaging, including safer guidance for intentional reruns.
• Documentation
  • Centralized usage guidance and examples in dedicated documentation.
• Tests
  • Added validation for command guidance, safety rules, identity handling, and documentation consistency.

[coderabbitai]

📝 Walkthrough

Walkthrough

This change moves application and IM shortcut guidance from Go Tips fields into affordance documents. It adds slash-command and IM documentation, migration tests, affordance audits, safety checks, identity validation, and updated access-token metadata expectations.

Changes

Affordance Guidance Migration

Layer / File(s)	Summary
Application slash-command affordances affordance/application.md, internal/affordance/application_source_test.go, shortcuts/application/*	Documents slash-command lifecycle operations. Tests validate examples, collision handling, deletion confirmation, update routing, and removal of duplicated runtime guidance.
IM affordance content and shortcut migration affordance/im.md, shortcuts/im/*	Adds chat, message, bookmark, feed, media, and reaction guidance. Migration tests validate examples, flags, identities, and required arguments.
IM affordance audit and identity metadata internal/affordance/im_source_test.go, internal/schema/assembler_test.go	Audits IM command coverage, source references, prerequisites, recovery guidance, image-upload identity behavior, and user/tenant access-token metadata.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• larksuite/cli#2151: Both changes migrate shortcut guidance to affordance metadata and cover application deletion safeguards.

Suggested labels: domain/ccm

Suggested reviewers: fangshuyu-768

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the migration of Application and IM guidance to affordance definitions.
Description check	✅ Passed	The description includes the required summary, changes, test plan, and related issues sections with detailed verification results.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/affordance-migration

---

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.01%. Comparing base (bdb1964) to head (98917d2).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2199      +/-   ##
==========================================
+ Coverage   76.00%   76.01%   +0.01%     
==========================================
  Files         966      966              
  Lines      102541   102541              
==========================================
+ Hits        77933    77947      +14     
+ Misses      18704    18691      -13     
+ Partials     5904     5903       -1     

☔ 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: 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 `@internal/affordance/application_source_test.go`:
- Around line 7-17: Replace the os-based filesystem access in
internal/affordance/application_source_test.go lines 7-17 with the appropriate
internal/vfs-backed source setup used by TestApplicationAffordanceExamples;
update internal/affordance/im_source_test.go lines 7-8 similarly, replacing both
os.DirFS and os.ReadFile with internal/vfs APIs while preserving the existing
test behavior.

🪄 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: 0a60ab57-ad21-4144-acc2-33ac5f20abd3

📥 Commits

Reviewing files that changed from the base of the PR and between bdb1964 and 98917d2.

📒 Files selected for processing (13)

• affordance/application.md
• affordance/im.md
• internal/affordance/application_source_test.go
• internal/affordance/im_source_test.go
• internal/schema/assembler_test.go
• shortcuts/application/affordance_migration_test.go
• shortcuts/application/slash_command_create.go
• shortcuts/application/slash_command_create_test.go
• shortcuts/application/slash_command_delete.go
• shortcuts/application/slash_command_list.go
• shortcuts/application/slash_command_update.go
• shortcuts/im/affordance_migration_test.go
• shortcuts/im/im_chat_members_list.go

💤 Files with no reviewable changes (4)

• shortcuts/application/slash_command_update.go
• shortcuts/application/slash_command_delete.go
• shortcuts/application/slash_command_list.go
• shortcuts/im/im_chat_members_list.go

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#feat/affordance-migration -y -g