feat：移除了弹窗，服务器添加sls
This commit is contained in:
@ -0,0 +1,38 @@
|
||||
# Lark Application Events
|
||||
|
||||
This page covers Application-domain EventKeys supported by `lark-cli event`.
|
||||
|
||||
## `application.bot.menu_v6`
|
||||
|
||||
Triggered when a user clicks a custom bot menu item whose response action is configured as a push event.
|
||||
|
||||
Listen as the bot identity:
|
||||
|
||||
```bash
|
||||
lark-cli event consume application.bot.menu_v6 --as bot
|
||||
```
|
||||
|
||||
Filter a specific menu event key:
|
||||
|
||||
```bash
|
||||
lark-cli event consume application.bot.menu_v6 --as bot --jq 'select(.event_key == "start_eval")'
|
||||
```
|
||||
|
||||
Output is flattened at the top level:
|
||||
|
||||
| Field | Meaning |
|
||||
|---|---|
|
||||
| `type` | Event type, always `application.bot.menu_v6` |
|
||||
| `event_id` | Globally unique event ID from the event header |
|
||||
| `timestamp` | Event delivery time, preferring `header.create_time` |
|
||||
| `app_id` | App ID from the event header |
|
||||
| `tenant_key` | Tenant key from the event header |
|
||||
| `event_key` | Developer-defined menu event key, for example `start_eval` |
|
||||
| `menu_timestamp` | Menu click timestamp from the event body |
|
||||
| `operator_id` | Operator open_id alias |
|
||||
| `operator_open_id` | Operator open_id |
|
||||
| `operator_union_id` | Operator union_id |
|
||||
| `operator_user_id` | Operator user_id |
|
||||
| `operator_name` | Operator display name |
|
||||
|
||||
This EventKey has no `--param`; use `--jq` to filter by `event_key` or operator fields.
|
||||
170
.claude/skills/lark-event/references/lark-event-approval.md
Normal file
170
.claude/skills/lark-event/references/lark-event-approval.md
Normal file
@ -0,0 +1,170 @@
|
||||
# Approval Events
|
||||
|
||||
> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
|
||||
|
||||
## Key catalog (2)
|
||||
|
||||
| EventKey | Purpose |
|
||||
|---|---|
|
||||
| `approval.instance.status_changed_v4` | An approval instance status changed |
|
||||
| `approval.task.status_changed_v4` | An approval task status changed |
|
||||
|
||||
Both keys use a **Custom schema**. The raw Lark schema 2.0 envelope is flattened: event metadata is exposed as `type`, `event_id`, and `timestamp`, while approval business fields are exposed at the top level.
|
||||
|
||||
Both keys carry a **PreConsume hook** that subscribes the current authorized user through the Approval subscription APIs before listening. The consumer intentionally does **not** unsubscribe on exit; the server-side Approval subscription relation remains until it is canceled outside `event consume`. These keys require `--as user`.
|
||||
|
||||
## Listener and subscription selection
|
||||
|
||||
At the raw CLI level, each `event consume` process accepts exactly one EventKey. `approval.instance.status_changed_v4` and `approval.task.status_changed_v4` have different output shapes, so listening to both still means two processes.
|
||||
|
||||
For Approval only, `subscription_type` is an optional setup param used by PreConsume to register server-side Approval subscription relations before the local listener starts. It is **not** an output field, a local event filter, or a local subscription identity. The pushed event does not say which subscription relation caused delivery, and one business event can match both relations; deduplicate with `event_id` when needed.
|
||||
|
||||
`subscription_type` may be omitted, a single value, a comma-separated list, or a JSON string array:
|
||||
|
||||
```bash
|
||||
# Omitted: register both INVOLVED_APPROVAL and MANAGED_APPROVAL for this EventKey
|
||||
lark-cli event consume approval.instance.status_changed_v4 --as user
|
||||
|
||||
# Single relation
|
||||
lark-cli event consume approval.instance.status_changed_v4 \
|
||||
-p subscription_type=INVOLVED_APPROVAL \
|
||||
--as user
|
||||
|
||||
# Explicit multi-relation registration for one local consumer
|
||||
lark-cli event consume approval.task.status_changed_v4 \
|
||||
-p subscription_type=INVOLVED_APPROVAL,MANAGED_APPROVAL \
|
||||
--as user
|
||||
|
||||
# JSON array form; quote it for the shell
|
||||
lark-cli event consume approval.task.status_changed_v4 \
|
||||
-p 'subscription_type=["INVOLVED_APPROVAL","MANAGED_APPROVAL"]' \
|
||||
--as user
|
||||
```
|
||||
|
||||
| Value | Meaning |
|
||||
|---|---|
|
||||
| `INVOLVED_APPROVAL` | Receive events where the current user is the approval requester or approver |
|
||||
| `MANAGED_APPROVAL` | Receive events under approval definitions managed by the current user |
|
||||
|
||||
User-intent inference:
|
||||
|
||||
| User intent | EventKey(s) | `subscription_type` |
|
||||
|---|---|---|
|
||||
| Mentions approval instances, approval forms, approval order/status, or "instance status" | `approval.instance.status_changed_v4` | infer from relation words below |
|
||||
| Mentions approval tasks, approval todo items, approver operations, or "task status" | `approval.task.status_changed_v4` | infer from relation words below |
|
||||
| Says "approval status changes/events" without saying task vs instance | both EventKeys | infer from relation words below |
|
||||
| Says "my approvals", "approvals involving me", "I requested/approved", "待我审批", "我发起/我参与" | requested EventKey(s) | `INVOLVED_APPROVAL` |
|
||||
| Says "approvals I manage", "managed definitions", "definitions managed by me", "我管理的审批定义" | requested EventKey(s) | `MANAGED_APPROVAL` |
|
||||
| Explicitly asks for both involved and managed, or says "all approval subscriptions" | requested EventKey(s), or both if EventKey is also ambiguous | omit `subscription_type`, or pass both values in one `-p` |
|
||||
| Relation is ambiguous and the user wants broad coverage | requested EventKey(s), or both if EventKey is also ambiguous | omit `subscription_type` so PreConsume registers both |
|
||||
|
||||
If the user's wording omits the relation and broad listening is acceptable, omit `subscription_type`. Ask only when registering both relations would be materially harmful.
|
||||
|
||||
## Scopes & auth
|
||||
|
||||
| EventKey | Scope | Auth |
|
||||
|---|---|---|
|
||||
| `approval.instance.status_changed_v4` | `approval:instance:read` | user |
|
||||
| `approval.task.status_changed_v4` | `approval:task:read` | user |
|
||||
|
||||
## Subscription behavior
|
||||
|
||||
Startup calls the endpoint for the selected EventKey:
|
||||
|
||||
```text
|
||||
POST /open-apis/approval/v4/instances/subscription
|
||||
POST /open-apis/approval/v4/tasks/subscription
|
||||
```
|
||||
|
||||
For each resolved `subscription_type`, PreConsume sends one request body:
|
||||
|
||||
```json
|
||||
{"subscription_type":"INVOLVED_APPROVAL"}
|
||||
```
|
||||
|
||||
If `subscription_type` is omitted, PreConsume sends two registration requests for that EventKey: one with `INVOLVED_APPROVAL`, then one with `MANAGED_APPROVAL`. If listening to both instance and task events, run two consumers; each consumer may omit `subscription_type` to register both relations for its own EventKey.
|
||||
|
||||
Do not start two consumers for the same Approval EventKey merely to split `INVOLVED_APPROVAL` and `MANAGED_APPROVAL`. The server push and flattened output are keyed by EventKey and cannot be distinguished by subscription relation.
|
||||
|
||||
Shutdown behavior:
|
||||
|
||||
`event consume` does not call the Approval unsubscribe APIs when it exits. This applies to graceful exit, Ctrl+C / SIGTERM, stdin EOF, `--timeout`, and `--max-events`.
|
||||
|
||||
To stop future delivery for a user, cancel the Approval subscription relation outside this consumer. The unsubscribe APIs are separate operations and are not called by `event consume`.
|
||||
|
||||
## Output fields
|
||||
|
||||
Common fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `type` | string | Event type |
|
||||
| `event_id` | string | Globally unique event ID; use for deduplication |
|
||||
| `timestamp` | string (timestamp_ms) | Event delivery time in milliseconds, taken from `header.create_time` |
|
||||
|
||||
Instance event fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `approval_code` | string | Approval definition code; not a subscription dimension |
|
||||
| `instance_code` | string | Approval instance code |
|
||||
| `external_id` | string | Third-party approval instance id, when present |
|
||||
| `status` | string enum | `PENDING`, `APPROVED`, `REJECTED`, `CANCELED`, `DELETED`, `REVERTED`, `OVERTIME_CLOSE`, `OVERTIME_RECOVER` |
|
||||
| `operate_time` | string (timestamp_ms) | Status change time |
|
||||
| `start_user` | object | Instance starter user IDs, omitted when unavailable |
|
||||
| `start_user.open_id` | string (open_id) | Instance starter open_id, when present |
|
||||
| `start_user.union_id` | string (union_id) | Instance starter union_id, when present |
|
||||
| `start_user.user_id` | string (user_id) | Instance starter tenant user_id, when present |
|
||||
|
||||
Task event fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `approval_code` | string | Approval definition code; not a subscription dimension |
|
||||
| `instance_code` | string | Approval instance code |
|
||||
| `task_id` | string | Approval task id |
|
||||
| `external_id` | string | Third-party approval external id, when present |
|
||||
| `task_external_id` | string | Third-party task external id, when emitted |
|
||||
| `assigned_user` | object | Task assignee or operator user IDs, omitted for automatic flows without an operator |
|
||||
| `assigned_user.open_id` | string (open_id) | Task assignee or operator open_id, when present |
|
||||
| `assigned_user.union_id` | string (union_id) | Task assignee or operator union_id, when present |
|
||||
| `assigned_user.user_id` | string (user_id) | Task assignee or operator tenant user_id, when present |
|
||||
| `status` | string enum | `REVERTED`, `PENDING`, `APPROVED`, `REJECTED`, `TRANSFERRED`, `ROLLBACK`, `DONE`, `OVERTIME_CLOSE`, `OVERTIME_RECOVER` |
|
||||
| `operate_time` | string (timestamp_ms) | Status change time |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Stream approval instance updates broadly; registers both involved and managed relations
|
||||
lark-cli event consume approval.instance.status_changed_v4 \
|
||||
--as user
|
||||
|
||||
# Stream approval instance updates only for approvals involving the current user
|
||||
lark-cli event consume approval.instance.status_changed_v4 \
|
||||
-p subscription_type=INVOLVED_APPROVAL \
|
||||
--as user
|
||||
|
||||
# Stream approval task updates for definitions managed by the current user
|
||||
lark-cli event consume approval.task.status_changed_v4 \
|
||||
-p subscription_type=MANAGED_APPROVAL \
|
||||
--as user
|
||||
|
||||
# Broad approval status listening:
|
||||
# run both EventKeys as separate processes; omit subscription_type so each registers both relations.
|
||||
lark-cli event consume approval.instance.status_changed_v4 \
|
||||
--as user > approval-instance.ndjson &
|
||||
lark-cli event consume approval.task.status_changed_v4 \
|
||||
--as user > approval-task.ndjson &
|
||||
wait
|
||||
|
||||
# Listen to both involved and managed task subscriptions with one local consumer.
|
||||
lark-cli event consume approval.task.status_changed_v4 \
|
||||
-p subscription_type=INVOLVED_APPROVAL,MANAGED_APPROVAL \
|
||||
--as user > approval-task.ndjson
|
||||
|
||||
# Project a compact approval-task record
|
||||
lark-cli event consume approval.task.status_changed_v4 \
|
||||
-p subscription_type=INVOLVED_APPROVAL \
|
||||
--as user \
|
||||
--jq '{event_id, task_id, status, at: .operate_time}'
|
||||
```
|
||||
87
.claude/skills/lark-event/references/lark-event-im.md
Normal file
87
.claude/skills/lark-event/references/lark-event-im.md
Normal file
@ -0,0 +1,87 @@
|
||||
# IM Events
|
||||
|
||||
> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
|
||||
>
|
||||
> **Heads-up for AI agents**: this key's `.content` is **NOT** the raw OAPI payload shape your training data may suggest. `lark-cli` runs a Process hook (`convertlib`) that flattens the V2 envelope and **pre-renders** `.content` to human-readable text for `text` / `post` / `image` / `file` / `audio` / etc. Only `interactive` (cards) keeps the raw JSON string. Don't blindly `fromjson`.
|
||||
|
||||
## Key catalog (12)
|
||||
|
||||
| EventKey | Purpose |
|
||||
|---|---|
|
||||
| `im.message.receive_v1` | Receive IM messages |
|
||||
| `im.message.message_read_v1` | User read a bot's **p2p** message (group messages don't fire this) |
|
||||
| `im.message.reaction.created_v1` | Reaction added to a message |
|
||||
| `im.message.reaction.deleted_v1` | Reaction removed from a message |
|
||||
| `im.chat.updated_v1` | Chat settings changed (owner, avatar, name, permissions, etc.) |
|
||||
| `im.chat.disbanded_v1` | Chat disbanded |
|
||||
| `im.chat.member.bot.added_v1` | Bot added to a chat |
|
||||
| `im.chat.member.bot.deleted_v1` | Bot removed from a chat |
|
||||
| `im.chat.member.user.added_v1` | User joined a chat (including topic chats) |
|
||||
| `im.chat.member.user.deleted_v1` | User left voluntarily **or** was removed |
|
||||
| `im.chat.member.user.withdrawn_v1` | Pending chat invite withdrawn (inviter canceled; user never actually joined) |
|
||||
| `card.action.trigger` | Interactive card callback — button click, form submit, dropdown, etc. → see [`lark-im-card-action-reply.md`](../../lark-im/references/lark-im-card-action-reply.md) |
|
||||
|
||||
> **Shape**: All 12 events have a V2-enveloped raw payload. `lark-cli` flattens two of them — `im.message.receive_v1` and `card.action.trigger` — so their consumed output is flat (fields at `.xxx`). The other 10 are passed through as-is; use `.event.xxx` to access their fields.
|
||||
|
||||
## Gotchas (`im.message.receive_v1`)
|
||||
|
||||
**sender_id is open_id only**: the event payload carries no display name. Call the contact API separately if you need the sender's name.
|
||||
|
||||
**`.content` shape depends on `message_type`** (this key uses a flat Custom schema; see [`events/im/message_receive.go`](../../../events/im/message_receive.go)):
|
||||
|
||||
| message_type | `.content` shape | How to read |
|
||||
|---|---|---|
|
||||
| `text` / `post` / `image` / `file` / `audio` / `sticker` / `share_chat` / `share_user` / `media` / `system` | Human-readable text (convertlib-processed; `@mentions` resolved to display names) | Use `.content` directly |
|
||||
| `interactive` (card) | Raw card JSON string (structured actions can't be losslessly flattened) | `.content \| fromjson` to get the card object |
|
||||
|
||||
**Do not blindly `fromjson`** — for non-interactive messages it fails with `jq: fromjson cannot be applied to "hello"` because `.content` isn't JSON-encoded.
|
||||
|
||||
```bash
|
||||
# text: .content is plain text — no fromjson needed
|
||||
lark-cli event consume im.message.receive_v1 --as bot \
|
||||
--jq 'select(.message_type=="text") | .content'
|
||||
|
||||
# interactive: .content is a JSON string — fromjson to parse
|
||||
lark-cli event consume im.message.receive_v1 --as bot \
|
||||
--jq 'select(.message_type=="interactive") | .content | fromjson'
|
||||
```
|
||||
|
||||
## On-demand filter recipes
|
||||
|
||||
> **Default = no `--jq`.** Run `lark-cli event consume im.message.receive_v1 --as bot` to see every message. The recipes below are only for cases where the user has asked to narrow the stream.
|
||||
|
||||
### 1. Filter by chat type (p2p vs group)
|
||||
|
||||
`chat_type` is an enum with values `p2p` / `group`.
|
||||
|
||||
```bash
|
||||
# p2p only (direct messages)
|
||||
lark-cli event consume im.message.receive_v1 --as bot \
|
||||
--jq 'select(.chat_type=="p2p") | {from: .sender_id, msg: .content}'
|
||||
|
||||
# group only
|
||||
lark-cli event consume im.message.receive_v1 --as bot \
|
||||
--jq 'select(.chat_type=="group") | {chat: .chat_id, from: .sender_id, msg: .content}'
|
||||
```
|
||||
|
||||
### 2. Filter by message type
|
||||
|
||||
```bash
|
||||
# text only — content is plain human-readable text
|
||||
lark-cli event consume im.message.receive_v1 --as bot \
|
||||
--jq 'select(.message_type=="text") | .content'
|
||||
|
||||
# interactive (card) only — parse the card body
|
||||
lark-cli event consume im.message.receive_v1 --as bot \
|
||||
--jq 'select(.message_type=="interactive") | .content | fromjson'
|
||||
```
|
||||
|
||||
### 3. Filter by sender (only one user's messages)
|
||||
|
||||
```bash
|
||||
# example: only messages from the given open_id
|
||||
lark-cli event consume im.message.receive_v1 --as bot\
|
||||
--jq 'select(.sender_id=="ou_xxxxxxxxxxxxxxxxxxxxxxxxxx") | {msg_id: .message_id, text: .content}'
|
||||
```
|
||||
|
||||
Get your own open_id via `lark-cli contact +get-user --as user`; other users' via `lark-cli contact +search-user`.
|
||||
54
.claude/skills/lark-event/references/lark-event-minutes.md
Normal file
54
.claude/skills/lark-event/references/lark-event-minutes.md
Normal file
@ -0,0 +1,54 @@
|
||||
# Minutes Events
|
||||
|
||||
> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
|
||||
|
||||
## Key catalog (1)
|
||||
|
||||
| EventKey | Purpose |
|
||||
|---|---|
|
||||
| `minutes.minute.generated_v1` | A minute (妙记) has been generated |
|
||||
|
||||
This key uses a **Custom schema** (flat output at `.xxx`) and carries a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer.
|
||||
|
||||
## Scopes & auth
|
||||
|
||||
| EventKey | Scope | Auth |
|
||||
|---|---|---|
|
||||
| `minutes.minute.generated_v1` | `minutes:minutes.basic:read` | user |
|
||||
|
||||
Requires `--as user`.
|
||||
|
||||
## `minutes.minute.generated_v1`
|
||||
|
||||
### Output fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `type` | string | Event type; always `minutes.minute.generated_v1` |
|
||||
| `event_id` | string | Globally unique event ID; safe for deduplication |
|
||||
| `timestamp` | string (timestamp_ms) | Event delivery time (ms timestamp string) |
|
||||
| `minute_token` | string | Minute token |
|
||||
| `title` | string | Minute title (enriched via detail API) |
|
||||
| `minute_source` | object | Minute source metadata; only present when the source is a meeting |
|
||||
| `minute_source.source_type` | string | Source type; only present when the source is a meeting (value: `meeting`) |
|
||||
| `minute_source.source_entity_id` | string | Source entity ID (meeting ID); only present when the source is a meeting |
|
||||
|
||||
### Enrichment & degradation
|
||||
|
||||
The Process hook calls `GET /open-apis/minutes/v1/minutes/{minute_token}` to enrich `title`. If the detail API fails, this field is left empty — the base fields (`type`, `event_id`, `timestamp`, `minute_token`, `minute_source`) are always present.
|
||||
|
||||
`minute_source` is populated from the event payload directly (not the detail API), so it survives enrichment failures. Note: `minute_source` is only present when the minute originates from a meeting; for other sources (e.g. recording, local upload) this field is absent.
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
lark-cli event consume minutes.minute.generated_v1 --as user
|
||||
|
||||
# Project title and token only (skip events where enrichment failed)
|
||||
lark-cli event consume minutes.minute.generated_v1 --as user \
|
||||
--jq 'select(.title != "") | {minute_token, title}'
|
||||
|
||||
# Filter by source type
|
||||
lark-cli event consume minutes.minute.generated_v1 --as user \
|
||||
--jq 'select(.minute_source.source_type == "meeting") | {minute_token, title}'
|
||||
```
|
||||
78
.claude/skills/lark-event/references/lark-event-task.md
Normal file
78
.claude/skills/lark-event/references/lark-event-task.md
Normal file
@ -0,0 +1,78 @@
|
||||
# Task Events
|
||||
|
||||
> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
|
||||
|
||||
## Key catalog (1)
|
||||
|
||||
| EventKey | Purpose |
|
||||
|---|---|
|
||||
| `task.task.update_user_access_v2` | A visible task has been created, deleted, or updated |
|
||||
|
||||
This key uses a **Native schema** (V2 envelope; output rooted at `.event`) and carries a **PreConsume hook** that calls the Task event subscription API before listening.
|
||||
|
||||
## Scopes & auth
|
||||
|
||||
| EventKey | Scope | Auth |
|
||||
|---|---|---|
|
||||
| `task.task.update_user_access_v2` | `task:task:read` | user, bot |
|
||||
|
||||
Supports `--as user` or `--as bot`.
|
||||
|
||||
- `--as user`: receive task updates visible to the current user through authorship, assignment, following, or other access.
|
||||
- `--as bot`: receive task updates for tasks the application is responsible for.
|
||||
|
||||
## `task.task.update_user_access_v2`
|
||||
|
||||
### Subscription behavior
|
||||
|
||||
On startup, `event consume` calls:
|
||||
|
||||
```text
|
||||
POST /open-apis/task/v2/task_v2/task_subscription?user_id_type=open_id
|
||||
```
|
||||
|
||||
The Task subscription API has no matching unsubscribe endpoint in the current CLI metadata, so graceful exit has no cleanup call for this EventKey. Re-running the consumer repeats the subscribe call for the selected identity.
|
||||
|
||||
This EventKey is single-consumer per local bus subscription: start one `event consume task.task.update_user_access_v2` process for a given app/profile/identity at a time.
|
||||
|
||||
### Output fields (V2 envelope; root path `.event`)
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `.header.event_id` | string | Globally unique event ID; safe for deduplication |
|
||||
| `.header.create_time` | string (timestamp_ms) | Event creation time in milliseconds |
|
||||
| `.event.event_types[]` | string enum | Task commit types included in this event |
|
||||
| `.event.task_guid` | string (kind=task_guid) | Task GUID that changed |
|
||||
|
||||
Commit types:
|
||||
|
||||
```text
|
||||
task_assignees_update
|
||||
task_completed_update
|
||||
task_create
|
||||
task_deleted
|
||||
task_desc_update
|
||||
task_followers_update
|
||||
task_reminders_update
|
||||
task_start_due_update
|
||||
task_summary_update
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
# Stream task update events for the current user
|
||||
lark-cli event consume task.task.update_user_access_v2 --as user
|
||||
|
||||
# Sample one event for payload inspection
|
||||
lark-cli event consume task.task.update_user_access_v2 \
|
||||
--as user --max-events 1 --timeout 2m
|
||||
|
||||
# Project to a compact task-update record
|
||||
lark-cli event consume task.task.update_user_access_v2 \
|
||||
--as user \
|
||||
--jq '{event_id: .header.event_id, task_guid: .event.task_guid, event_types: .event.event_types, timestamp: .header.create_time}'
|
||||
|
||||
# Consume as the app identity
|
||||
lark-cli event consume task.task.update_user_access_v2 --as bot
|
||||
```
|
||||
106
.claude/skills/lark-event/references/lark-event-vc.md
Normal file
106
.claude/skills/lark-event/references/lark-event-vc.md
Normal file
@ -0,0 +1,106 @@
|
||||
# VC Events
|
||||
|
||||
> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
|
||||
|
||||
## Key catalog (4)
|
||||
|
||||
| EventKey | Purpose |
|
||||
|---|---|
|
||||
| `vc.meeting.participant_meeting_started_v1` | A meeting the current user participates in has started |
|
||||
| `vc.meeting.participant_meeting_joined_v1` | The current user has joined a meeting |
|
||||
| `vc.meeting.participant_meeting_ended_v1` | A meeting the current user participates in has ended |
|
||||
| `vc.note.generated_v1` | A note has been generated (meeting, recording, upload, etc.) |
|
||||
|
||||
All four keys use a **Custom schema** (flat output) and carry a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer. All require `--as user`.
|
||||
|
||||
## Scopes & auth
|
||||
|
||||
| EventKey | Scope | Auth |
|
||||
|---|---|---|
|
||||
| `vc.meeting.participant_meeting_started_v1` | `vc:meeting.meetingevent:read` | user |
|
||||
| `vc.meeting.participant_meeting_joined_v1` | `vc:meeting.meetingevent:read` | user |
|
||||
| `vc.meeting.participant_meeting_ended_v1` | `vc:meeting.meetingevent:read` | user |
|
||||
| `vc.note.generated_v1` | `vc:note:read` | user |
|
||||
|
||||
---
|
||||
|
||||
## Meeting participant events
|
||||
|
||||
Covered keys:
|
||||
|
||||
- `vc.meeting.participant_meeting_started_v1`
|
||||
- `vc.meeting.participant_meeting_joined_v1`
|
||||
- `vc.meeting.participant_meeting_ended_v1`
|
||||
|
||||
### Output fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `type` | string | Event type; one of the covered meeting participant EventKeys |
|
||||
| `event_id` | string | Globally unique event ID; safe for deduplication |
|
||||
| `timestamp` | string (timestamp_ms) | Event delivery time (ms timestamp string) |
|
||||
| `meeting_id` | string | Meeting ID |
|
||||
| `topic` | string | Meeting topic |
|
||||
| `meeting_no` | string | Meeting number |
|
||||
| `start_time` | string | Meeting start time in RFC3339, converted to the local timezone |
|
||||
| `calendar_event_id` | string | Calendar event ID associated with the meeting |
|
||||
| `end_time` | string | Meeting end time in RFC3339, converted to the local timezone; only present for `vc.meeting.participant_meeting_ended_v1` |
|
||||
|
||||
### Gotchas
|
||||
|
||||
- `start_time` / `end_time` are **not** the raw unix-seconds from OAPI — the Process hook converts them to local-timezone RFC3339. If the raw value is empty or non-numeric, the field is left empty. `end_time` is emitted only for `vc.meeting.participant_meeting_ended_v1`.
|
||||
- No detail API call is made; all fields come from the event payload itself.
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
lark-cli event consume vc.meeting.participant_meeting_started_v1 --as user
|
||||
lark-cli event consume vc.meeting.participant_meeting_joined_v1 --as user
|
||||
lark-cli event consume vc.meeting.participant_meeting_ended_v1 --as user
|
||||
|
||||
# Project meeting topic and end time only
|
||||
lark-cli event consume vc.meeting.participant_meeting_ended_v1 --as user \
|
||||
--jq '{meeting: .meeting_id, topic: .topic, ended: .end_time}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `vc.note.generated_v1`
|
||||
|
||||
Fires when a note is generated — not just from meetings, but also from realtime recordings and local file uploads.
|
||||
|
||||
### Output fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `type` | string | Event type; always `vc.note.generated_v1` |
|
||||
| `event_id` | string | Globally unique event ID; safe for deduplication |
|
||||
| `timestamp` | string (timestamp_ms) | Event delivery time (ms timestamp string) |
|
||||
| `note_id` | string | Note ID |
|
||||
| `note_token` | string | Note document token; may be empty if detail is not yet available |
|
||||
| `verbatim_token` | string | Verbatim document token; may be empty if detail is not yet available |
|
||||
| `note_source` | object | Source metadata; only present when source is a meeting |
|
||||
| `note_source.source_type` | string | Source type; only present when source is a meeting (value: `meeting`) |
|
||||
| `note_source.source_entity_id` | string | Source entity ID (meeting ID); only present when source is a meeting |
|
||||
|
||||
### Source type semantics
|
||||
|
||||
| `source_type` | Trigger |
|
||||
|---|---|
|
||||
| `meeting` | Note generated from a meeting |
|
||||
|
||||
`note_source` (and its sub-fields) are only populated when `source_type` is `meeting`. For other sources the field is absent.
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
lark-cli event consume vc.note.generated_v1 --as user
|
||||
|
||||
# Only notes with enriched tokens, skip incomplete ones
|
||||
lark-cli event consume vc.note.generated_v1 --as user \
|
||||
--jq 'select(.note_token != "") | {note_id, note_token, verbatim_token}'
|
||||
|
||||
# Filter to meeting-sourced notes only
|
||||
lark-cli event consume vc.note.generated_v1 --as user \
|
||||
--jq 'select(.note_source.source_type == "meeting") | {note_id, meeting_id: .note_source.source_entity_id}'
|
||||
```
|
||||
@ -0,0 +1,67 @@
|
||||
# Whiteboard Events
|
||||
|
||||
> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
|
||||
|
||||
## Key catalog (1)
|
||||
|
||||
| EventKey | Purpose |
|
||||
|---|---|
|
||||
| `board.whiteboard.updated_v1` | A whiteboard has been edited |
|
||||
|
||||
This key uses a **Native schema** (V2 envelope; output rooted at `.event`) and carries a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer.
|
||||
|
||||
## Scopes & auth
|
||||
|
||||
| EventKey | Scope | Auth |
|
||||
|---|---|---|
|
||||
| `board.whiteboard.updated_v1` | `board:whiteboard:node:read` | user, bot |
|
||||
|
||||
Supports `--as user` or `--as bot`. The caller must have **manage** access to the target whiteboard, otherwise the subscribe OAPI returns 403 and `event consume` exits with an auth error before listening.
|
||||
|
||||
## `board.whiteboard.updated_v1`
|
||||
|
||||
### Per-whiteboard subscription
|
||||
|
||||
Unlike global event keys (e.g. minutes / im), this key subscribes **per whiteboard**: `event consume` calls `POST /open-apis/board/v1/whiteboards/{whiteboard_id}/subscribe` on startup with the `whiteboard_id` you pass via `-p`. **Required parameter**: `-p whiteboard_id=<whiteboard_token>`. Missing this param fails param validation up-front with `required param "whiteboard_id" missing for EventKey board.whiteboard.updated_v1` before any subscription happens.
|
||||
|
||||
Whiteboard token can be obtained via the docs OAPI [list document blocks](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/list): the block whose `block_type=43` is a whiteboard, and `block.token` is the whiteboard token.
|
||||
|
||||
### Output fields (V2 envelope; root path `.event`)
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `.event.whiteboard_id` | string (kind=whiteboard_id) | Whiteboard token |
|
||||
| `.event.operator_ids[].open_id` | string (kind=open_id) | Editor's open_id (`ou_` prefix) |
|
||||
| `.event.operator_ids[].union_id` | string (kind=union_id) | Editor's union_id |
|
||||
| `.event.operator_ids[].user_id` | string (kind=user_id) | Editor's user_id (only present when the caller's app has the user_id-related contact scope granted by the OAPI side) |
|
||||
|
||||
`operator_ids` is an array — multi-user collaborative editing within one tick collapses into a single event with multiple entries.
|
||||
|
||||
### Subscription lifecycle
|
||||
|
||||
| Phase | Behavior |
|
||||
|---|---|
|
||||
| Startup | `event consume` calls `subscribe` OAPI; on success stderr emits `[event] consuming as ...`, `[event] running pre-consume setup...`, `[event] listening for events (key=board.whiteboard.updated_v1)...`, then the AI-facing ready marker `[event] ready event_key=board.whiteboard.updated_v1` |
|
||||
| Running | Edits to the whiteboard stream as NDJSON to stdout |
|
||||
| Graceful exit (Ctrl+C / SIGTERM / `--max-events` / `--timeout` / stdin EOF) | `event consume` calls `unsubscribe` OAPI |
|
||||
| `kill -9` | **Skips unsubscribe → server-side subscription leaks**, may cause `subscription already exists` or duplicate delivery on next consume. See SKILL.md "Never `kill -9`". |
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
# Stream every edit on whiteboard <token> until Ctrl+C
|
||||
lark-cli event consume board.whiteboard.updated_v1 \
|
||||
-p whiteboard_id=<whiteboard_token> \
|
||||
--as user
|
||||
|
||||
# Sample one event for payload inspection
|
||||
lark-cli event consume board.whiteboard.updated_v1 \
|
||||
-p whiteboard_id=<whiteboard_token> \
|
||||
--as user --max-events 1 --timeout 2m
|
||||
|
||||
# Project to "edit summary": who edited which whiteboard
|
||||
lark-cli event consume board.whiteboard.updated_v1 \
|
||||
-p whiteboard_id=<whiteboard_token> \
|
||||
--as user \
|
||||
--jq '{whiteboard: .event.whiteboard_id, editors: (.event.operator_ids | map(.open_id))}'
|
||||
```
|
||||
Reference in New Issue
Block a user