wehub-resource-sync
bf9395e022
CI / license-header (push) Has been skipped
CI / e2e-dry-run (push) Has been skipped
CI / fast-gate (push) Failing after 0s
Test PR Label Logic / test-pr-labels (push) Failing after 1s
Skill Format Check / check-format (push) Failing after 2s
CI / security (push) Failing after 5s
CI / unit-test (push) Has been skipped
CI / lint (push) Has been skipped
CI / script-test (push) Has been skipped
CI / deterministic-gate (push) Has been skipped
CI / coverage (push) Has been skipped
CI / results (push) Has been cancelled
CI / deadcode (push) Has been cancelled
CI / e2e-live (push) Has been cancelled
67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
# Affordance
|
|
|
|
Per-command usage guidance for the CLI, authored as one markdown file per domain
|
|
(`<service>.md`). It is surfaced in `lark-cli <command> --help` and in the
|
|
`schema` output, and read directly at runtime (lazy, cached) — there is no build
|
|
step. Maintain these files alongside `skills/` and `shortcuts/`.
|
|
|
|
## Format
|
|
|
|
A small, fixed markdown subset; each file describes one domain:
|
|
|
|
# <domain> optional `> skill: <name>` applies to every command below
|
|
## <command> the command as typed, minus `lark-cli <domain>`; a
|
|
+-prefixed heading (## +create) targets that shortcut
|
|
<lead paragraph> when to use this command
|
|
### Avoid when when not to use it / which command to use instead
|
|
### Prerequisites what you must have first (e.g. an id, and where it comes from)
|
|
### Tips gotchas and constraints
|
|
### Examples **description** lines, each followed by a fenced command
|
|
### Skills bullet skill names, or name/relpath references
|
|
(lark-contact/references/x.md), to read for usage;
|
|
merged with the domain `> skill:` default (deduped,
|
|
domain first)
|
|
### <other heading> a custom section; flows through verbatim
|
|
|
|
Reference another command with `[[command]]` — it renders as `command` in help.
|
|
Under `Avoid when` it means "use that one instead"; under `Prerequisites`
|
|
("… from [[command]]") it means "get the input there first".
|
|
|
|
Both service-API commands (`## messages get`) and `+`-prefixed shortcuts
|
|
(`## +create`) take entries. A `### Skills` entry is a skill name (validated
|
|
against `<name>/SKILL.md`) or a `name/relpath` reference into that skill
|
|
(validated against the path); help drops any that don't resolve, so a typo shows
|
|
nothing. Point a command at its own reference (e.g. `+search-user` →
|
|
`lark-contact/references/lark-contact-search-user.md`) rather than re-listing the
|
|
domain skill, which the `> skill:` default already covers. When a shortcut also
|
|
sets a hand-authored `Tips` list in Go, the overlay's `### Tips` win — they
|
|
replace the Go tips (not merged), so keep tips in one place.
|
|
|
|
## Example
|
|
|
|
## messages get
|
|
Fetch the full content of a single message by id.
|
|
|
|
### Avoid when
|
|
- Reading several at once → use [[messages batch_get]]
|
|
|
|
### Prerequisites
|
|
- message_id from [[messages list]]
|
|
|
|
### Examples
|
|
|
|
**Fetch one message**
|
|
```bash
|
|
lark-cli mail user_mailbox.messages get --message-id "<id>"
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Write plain prose; the only convention is wrapping command references in `[[ ]]`.
|
|
- Keep it concise and high-signal — don't restate field/flag names, id types, or
|
|
anything the schema and flags already show; the agent infers the rest.
|
|
- Command-form headings resolve to method ids via the registry, so plural resource
|
|
names (`messages`) map to the singular method id (`message`) automatically.
|
|
`+`-prefixed shortcut headings are matched verbatim (no plural/space folding),
|
|
so the heading must equal the shortcut command exactly (`## +history-revert`).
|