feat(affordance): usage guidance for shortcuts and per-command skills by liangshuo-1 · Pull Request #1793 · larksuite/cli

liangshuo-1 · 2026-07-08T05:40:00Z

What

Extends the affordance overlay (per-command --help guidance authored in affordance/<domain>.md) beyond generated service-API methods to +-prefixed shortcuts, and lets a command point at specific related skills.

Changes

Shortcut affordance: shortcuts now render the same guidance block as methods, from ## +cmd entries. The affordance lookup coordinate is unified in cmdmeta (SetAffordanceRef/AffordanceRef) so method and shortcut help share one path (the two packages can't import each other; cmdmeta is the neutral layer).
PostMount Long preserved: PrepareShortcutHelp composes onto the command's captured base, so a shortcut that sets a hand-authored Long in PostMount (e.g. the docs shortcuts' "agents MUST read the skill / MUST NOT grep local SKILL.md" directive) keeps it — the affordance block is appended below, never clobbered. Re-render is idempotent.
Per-command ### Skills: merges with the domain > skill: default (deduped, domain first). An entry may be a bare skill name or a name/relpath reference (e.g. lark-contact/references/lark-contact-search-user.md) so a command can point at its own reference rather than only re-listing the domain skill. Each is validated against the embedded skill tree and dropped when it doesn't resolve, so help never prints an unopenable skills read pointer.
+ heading resolution: +-prefixed headings key verbatim (no space→dot folding).
Data: guide contact's +search-user / +get-user shortcuts (each points at its own reference).

Tips precedence

A shortcut may carry a Go Tips field and an overlay ### Tips. The overlay wins and replaces the Go tips (not merged) — documented in code and README; keep tips in one place.

Testing

Unit tests: PrepareShortcutHelp (compose/idempotency/PostMount-preservation), related-skill stat gating both directions (existing renders, typo/bad-reference dropped, nil FS suppresses), ### Skills merge/dedup, + heading verbatim.
go build ./..., go vet, and the affected package tests are green on an origin/main base.

Summary by CodeRabbit

New Features
- Enhanced help composition for commands, including clearer risk/affordance sections and conditional “related skills” guidance.
Bug Fixes
- +-prefixed shortcut headings are now matched verbatim.
- Domain default skills merge with command skills using de-duplication; unresolved skills are omitted.
- Example link text in fenced blocks now renders consistently.
- Shortcut Tips overlay replaces (rather than merges) any base tips.
Documentation
- Refined affordance markdown format specification.
- Added docs for +search-user and +get-user.
Tests
- Expanded help and markdown/skills parsing coverage with new cases.

coderabbitai · 2026-07-08T05:40:17Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 67939a6b-7e1b-46fb-8632-0c6b01d33135

📥 Commits

Reviewing files that changed from the base of the PR and between 750c1e5 and d43f41a.

📒 Files selected for processing (12)

affordance/README.md
affordance/contact.md
cmd/root.go
cmd/service/affordance.go
cmd/service/affordance_test.go
internal/affordance/affordance.go
internal/affordance/affordance_test.go
internal/affordance/mdparse.go
internal/cmdmeta/meta.go
internal/meta/affordance.go
shortcuts/common/runner.go
shortcuts/contact/contact_search_user.go

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

shortcuts/common/runner.go
internal/meta/affordance.go
shortcuts/contact/contact_search_user.go

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

cmd/root.go
internal/affordance/affordance.go
internal/affordance/affordance_test.go
internal/cmdmeta/meta.go
internal/affordance/mdparse.go
cmd/service/affordance_test.go
affordance/README.md
cmd/service/affordance.go

📝 Walkthrough

Walkthrough

This PR adds affordance-ref metadata for commands, extends affordance markdown parsing with skills merging and verbatim shortcut headings, updates help rendering to use the new metadata and skill filesystem, and refreshes related affordance and contact documentation.

Changes

Affordance ref, skills merge, and help rendering

Layer / File(s)	Summary
Affordance ref annotations `internal/cmdmeta/meta.go`, `shortcuts/common/runner.go`	Adds annotation keys plus `SetAffordanceRef` and `AffordanceRef` helpers, and writes affordance refs when mounting shortcut commands.
Markdown skills parsing `internal/affordance/mdparse.go`, `internal/affordance/affordance.go`, `internal/affordance/affordance_test.go`, `internal/meta/affordance.go`	Adds `### Skills` support, domain/per-command skill merging and deduping, verbatim `+` heading handling, backtick rendering for example links, and matching tests/comments.
Help composition and wiring `cmd/service/affordance.go`, `cmd/service/affordance_test.go`, `cmd/root.go`	Switches help generation to affordance refs, preserves base help text, gates related skills on the supplied FS, and updates help-generation tests and method-help wiring.
Format and contact docs `affordance/README.md`, `affordance/contact.md`, `shortcuts/contact/contact_search_user.go`	Documents skills rules, shortcut behavior, new contact commands, and the trimmed shortcut tips text.

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

Possibly related PRs

larksuite/cli#1565: Touches the same help-generation path in cmd/service/affordance.go and the wrapper logic in cmd/root.go.

Suggested labels: feature

Suggested reviewers: MaxHuang22, fangshuyu-768

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: affordance guidance for shortcuts and per-command skills.
Description check	✅ Passed	The description covers the summary, main changes, tips precedence, and testing, with only the related issues section omitted.
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-usage-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

_{Comment @coderabbitai help to get the list of available commands.}

codecov · 2026-07-08T05:45:29Z

Codecov Report

❌ Patch coverage is 69.23077% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.42%. Comparing base (9413e7c) to head (d43f41a).

Files with missing lines	Patch %	Lines
internal/cmdmeta/meta.go	0.00%	15 Missing ⚠️
cmd/service/affordance.go	85.45%	3 Missing and 5 partials ⚠️
cmd/root.go	0.00%	2 Missing and 2 partials ⚠️
internal/affordance/mdparse.go	85.18%	4 Missing ⚠️
internal/affordance/affordance.go	50.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1793   +/-   ##
=======================================
  Coverage   74.42%   74.42%           
=======================================
  Files         860      860           
  Lines       89754    89827   +73     
=======================================
+ Hits        66797    66852   +55     
- Misses      17779    17795   +16     
- Partials     5178     5180    +2

☔ 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 · 2026-07-08T05:46:18Z

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

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

Extend the affordance overlay (per-command --help guidance) beyond generated service-API methods to +-prefixed shortcuts, and let a command point at specific related skills. - shortcuts render the same guidance block as methods, from `## +cmd` entries in affordance/<domain>.md; the lookup coordinate is unified in cmdmeta (SetAffordanceRef/AffordanceRef) so both share one path - PrepareShortcutHelp composes onto the command's captured base, so a shortcut's PostMount-authored Long (e.g. the docs "read the skill" directive) is preserved, not clobbered - a per-command `### Skills` section merges with the domain `> skill:` default (deduped, domain first); an entry may be a bare skill name or a name/relpath reference (lark-contact/references/x.md), validated against the embedded skill tree and dropped when unresolved - +-prefixed headings resolve verbatim (no space->dot folding) - guide contact's +search-user / +get-user shortcuts, dropping the +search-user Go tips now covered by the overlay's examples and lead Tips precedence: a shortcut's overlay `### Tips` replace its Go Tips field.

github-actions Bot added the size/L Large or sensitive change across domains or core paths label Jul 8, 2026

liangshuo-1 force-pushed the feat/affordance-usage-guidance branch from f749710 to 592497b Compare July 8, 2026 06:10

github-actions Bot added the domain/contact PR touches the contact domain label Jul 8, 2026

liangshuo-1 force-pushed the feat/affordance-usage-guidance branch from 592497b to 750c1e5 Compare July 8, 2026 06:14

liangshuo-1 force-pushed the feat/affordance-usage-guidance branch from 750c1e5 to d43f41a Compare July 8, 2026 09:32

MaxHuang22 approved these changes Jul 8, 2026

View reviewed changes

liangshuo-1 merged commit cdd9d34 into main Jul 8, 2026
37 checks passed

liangshuo-1 deleted the feat/affordance-usage-guidance branch July 8, 2026 11:45

This was referenced Jul 8, 2026

chore: release v1.0.67 #1808

Merged

chore: release v1.0.68 #1809

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(affordance): usage guidance for shortcuts and per-command skills#1793

feat(affordance): usage guidance for shortcuts and per-command skills#1793
liangshuo-1 merged 1 commit into
mainfrom
feat/affordance-usage-guidance

liangshuo-1 commented Jul 8, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

codecov Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

liangshuo-1 commented Jul 8, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Changes

Tips precedence

Testing

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

codecov Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 PR Preview Install Guide

🧰 CLI update

🧩 Skill update

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

liangshuo-1 commented Jul 8, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading

codecov Bot commented Jul 8, 2026 •

edited

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading