feat(affordance): support domain skill lists

[liangshuo-1]

Summary

Extend affordance Markdown so a business domain can declare the skills shown on lark-cli <domain> --help independently from command-level skill inheritance. Existing single-skill domain help remains byte-compatible unless a domain opts into the new list.

Changes

• Add a reserved domain-level ## Skills section while preserving > skill: as the canonical command default and ### Skills as command-specific guidance.
• Resolve, remap, order, and availability-gate domain skill references through the existing composed skill tree.
• Preserve the established singular Domain guide output and render a list only when multiple configured skills remain available.
• Add parser, cache-copy, help compatibility, filtering, remap, and external customer-wrapper E2E coverage.
• Document the new affordance authoring contract.

Test Plan

• Unit tests pass (make unit-test, including race detection).
• Manual local verification confirms the lark-cli <domain> <command> flow works as expected.
• Full external plugin/customer-wrapper E2E suite passes (go test -count=1 -timeout=15m ./tests/plugin_e2e/...).
• make build, make vet, make fmt-check, go mod tidy, and make quality-gate pass.
• Diff-scoped golangci-lint and source-contract lint report no issues; license policy check passes.

Related Issues

• None

Summary by CodeRabbit

• New Features

  • Domain help now displays multiple configured skills in a consistent order.
  • Skill references are resolved to their available guides, while unavailable entries are omitted.
  • Domain-level skills can guide navigation without being inherited by individual commands.
  • Help output clearly identifies the canonical domain guide.

• Documentation

  • Added guidance for configuring domain-level and command-level Skills sections.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d84cb4b-e18d-4b09-b7a1-863210c467d0

📥 Commits

Reviewing files that changed from the base of the PR and between 6d6b688 and d39b2d7.

📒 Files selected for processing (8)

• affordance/README.md
• cmd/service/affordance.go
• cmd/service/affordance_test.go
• internal/affordance/affordance.go
• internal/affordance/affordance_test.go
• internal/affordance/mdparse.go
• tests/plugin_e2e/harness.go
• tests/plugin_e2e/skills_test.go

---

📝 Walkthrough

Walkthrough

Domain-level ## Skills entries are now parsed, cached, and exposed through DomainSkills. Domain help resolves and displays configured skills while commands inherit only the canonical skill. Unit and end-to-end tests cover ordering, filtering, remapping, and non-inheritance.

Changes

Domain skill parsing and storage

Layer / File(s)	Summary
Parse and store domain skills internal/affordance/mdparse.go, internal/affordance/affordance.go, internal/affordance/*_test.go, affordance/README.md	The parser collects domain-level skill references. The service affordance stores and returns defensive copies of these references. Documentation describes validation, ordering, and command non-inheritance.
Render resolved domain skills cmd/service/affordance.go, cmd/service/affordance_test.go	Domain help resolves configured skill references, omits unavailable skills, preserves single-guide output, and lists multiple resolved skills in order.
Validate custom affordance flows tests/plugin_e2e/harness.go, tests/plugin_e2e/skills_test.go	The test harness accepts custom affordance content. End-to-end tests verify domain help output and exclusion of domain-only skills from command help.

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

Sequence Diagram(s)

sequenceDiagram
  participant AffordanceParser
  participant serviceAffordance
  participant PrepareDomainHelp
  participant SkillFilesystem
  AffordanceParser->>serviceAffordance: load domain skill references
  PrepareDomainHelp->>serviceAffordance: request DomainSkills
  serviceAffordance-->>PrepareDomainHelp: return configured references
  PrepareDomainHelp->>SkillFilesystem: resolve available references
  SkillFilesystem-->>PrepareDomainHelp: return readable skills
  PrepareDomainHelp->>PrepareDomainHelp: render domain guide or skill list

Loading

Possibly related PRs

• larksuite/cli#2181: Modifies domain help skill and reference rendering in the same service affordance code.
• larksuite/cli#2189: Modifies skill-reference resolution and remapping used by affordance rendering.

Suggested labels: domain/task

Suggested reviewers: zhangjun-bytedance

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 45.45% 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 clearly and concisely identifies the main change: support for domain-level affordance skill lists.
Description check	✅ Passed	The description includes all required sections and clearly explains the scope, changes, testing, 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 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/affordance-domain-skills

---

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#agent/affordance-domain-skills -y -g

[codecov]

Codecov Report

❌ Patch coverage is 95.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.47%. Comparing base (8419534) to head (d39b2d7).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/affordance/affordance.go	78.57%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2291      +/-   ##
==========================================
+ Coverage   76.44%   76.47%   +0.03%     
==========================================
  Files        1013     1013              
  Lines      111932   112079     +147     
==========================================
+ Hits        85561    85707     +146     
+ Misses      19860    19859       -1     
- Partials     6511     6513       +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.