ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
# 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))}'
|
|
```
|