@amaster.ai/pi-lark 0.1.5 → 0.1.7

package/skills/lark-drive/references/lark-drive-workflow-topic-move-collector.md

@@ -0,0 +1,202 @@
+# 主题资料收集工作流
+
+Workflow id: `topic_move_collector`
+
+Risk / Structure: `R2-R3` / `S3`
+
+本文档实现已注册的主题资料收集 workflow。执行前必须先阅读 [`lark-drive-workflow.md`](lark-drive-workflow.md) 和 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)，并遵循共享执行协议、Artifact Contract、Workflow Loading、认证和写入确认规则。
+
+本文档负责定义本 workflow 的全局约束、状态机和渐进加载关系。具体阶段规则放在配套文档中，只有进入对应状态时才加载。
+
+配套文档只是本 workflow 的引用文件，不是独立 skill。不要把用户请求直接路由到某个配套文档。
+
+## 必读上下文
+
+执行本 workflow 前，必须先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)，用于处理身份、认证、权限和写操作确认规则。
+
+按阶段渐进加载其他 skill / 引用文档：
+
+- 目标是 Wiki 或个人文档库：[`../../lark-wiki/SKILL.md`](../../lark-wiki/SKILL.md)
+- 需要读取文档内容：[`../../lark-doc/SKILL.md`](../../lark-doc/SKILL.md) 和 [`../../lark-doc/references/lark-doc-fetch.md`](../../lark-doc/references/lark-doc-fetch.md)
+- 需要验证 Sheet 内容：[`../../lark-sheets/SKILL.md`](../../lark-sheets/SKILL.md)
+- 需要 Drive 搜索：[`lark-drive-search.md`](lark-drive-search.md)
+- 需要资源解析：[`lark-drive-inspect.md`](lark-drive-inspect.md)
+
+## 适用范围
+
+本 workflow 用于根据用户给出的主题、关键词或内容线索，在云空间 / 云盘 / Wiki / 电子表格等 Workspace 资源中查找相关资料，并在用户确认后统一移动到指定 Drive 文件夹或 Wiki 节点下。
+
+适用触发语包括：
+
+- "帮我找到和某主题相关的文档并放到这个文件夹"
+- "把所有关于某项目的资料收集到知识库节点下"
+- "找出包含某内容的资料，确认后移动到新建目录"
+- "按这个关键词搜索我负责的资料，把相关资料归档"
+
+默认搜索范围是当前用户 owner / 负责的 Workspace 资源，即 `owner_scope=mine`。只有用户明确要求“不限 owner”“包括共享给我的”“所有我能看到的文档”或“全量搜索”时，才使用 `owner_scope=all_visible` 进入扩展召回模式。
+
+不要求用户先限定文件夹或知识库范围。只有用户明确指定范围时，才使用 `--folder-tokens`、`--space-ids` 或其他显式限制。
+
+## 非目标
+
+默认不生成：
+
+- 长篇研究报告
+- 内容总结文档
+- Sheet 清单或统计看板
+- 自动权限治理报告
+
+默认禁止执行：
+
+- 未确认前创建文件夹或 Wiki 节点
+- 未确认前移动资源
+- 删除资源、重命名资源或修改公开权限
+- 自动批量申请权限
+- 把无权限或无法验证的资源加入移动计划
+- 把移动权限未知或不具备移动资格的资源加入移动计划
+
+如果用户明确要求把结果写入 Sheet / Doc，切到对应专项能力；本 workflow 的默认产物是移动后的资源归档结果。
+
+## Agent 执行约束
+
+触发本 workflow 后，agent 必须：
+
+1. 按“执行状态机”的顺序执行。
+2. 维护“运行时状态”中的字段。
+3. 执行某个状态前，先读取本文档 `## 渐进加载关系` 表格中该状态对应的文档。
+4. 用户可见说明、字段说明和 UI 文案使用中文。
+5. 状态名、字段名、枚举值、命令名保留英文稳定标识。
+6. 将 `CONFIRM_CONTEXT` 和 `CONFIRM_EXECUTION` 作为强用户确认门：前者确认主题、目标位置、身份、搜索范围、可选限制和目标解析结果后才能搜索；后者确认创建目标和移动资源后才能写入。
+7. 进入 `EXECUTE` 前，不得创建目标文件夹 / 节点，也不得移动资源。
+8. 必须展示每个相关性分组中的资源名称；低置信分组可以折叠，但必须可查看。
+9. 默认只移动 `high` 相关资源；`medium` 资源必须由用户显式选择。
+10. 即使用户可见列表分页展示，也必须维护完整内部状态。
+11. `RESOURCE_RESOLVE` 和 `CONTENT_VERIFY` 是两个独立的强制阶段，不得合并；不得用搜索结果、标题或摘要直接替代 `CONTENT_VERIFY`，也不得从 `RESOURCE_RESOLVE` 直接进入 `RELEVANCE_CLASSIFY`。
+12. 触发后锁定 `workflow_id=topic_move_collector`；执行期间不得自动切换到其他 workflow。
+13. 如果认为需要切换 workflow，必须停止并向用户说明原因，等待用户确认。
+14. `RESOURCE_RESOLVE` 是移动资格门禁；只有确认 `move_permission_state=movable` 且 `target_write_state=confirmed` 的资源才能进入默认移动链路。
+
+## 用户展示 UI 规则
+
+所有用户可见 UI 都必须包含：
+
+1. 已经完成的关键结果。
+2. 下一步会做什么，以及是否会产生写操作。
+3. 如果 `wait_for_user=true`，明确告诉用户可以选择的动作。
+4. 如果无需用户操作，明确说明将继续执行，避免用户误以为流程停住。
+
+典型动作包括：确认继续、修改主题 / 目标 / 限制、展开更多结果、调整相关性分组、选择中相关资源、确认执行、取消执行。
+
+## 职责边界
+
+| 文件 | 负责 | 不负责 |
+|------|------|--------------|
+| `lark-drive-workflow-topic-move-collector.md` | 触发规则、全局约束、状态机、渐进加载关系、命令族白名单 | 具体阶段规则、UI 模板、执行细节 |
+| `lark-drive-workflow-topic-move-collector-setup.md` | `PARSE_INPUT`、`RESOLVE_TARGET`、`CONFIRM_CONTEXT`、`TargetLocation` | 搜索执行、相关性分类、写操作 |
+| `lark-drive-workflow-topic-move-collector-recall.md` | `SEARCH_RECALL`、`RECALL_ENHANCE`、搜索 query 策略、去重、`CandidateItem` | 资源 token 解析、内容验证、写操作 |
+| `lark-drive-workflow-topic-move-collector-resolve-verify.md` | `RESOURCE_RESOLVE`、`CONTENT_VERIFY`、权限矩阵、`ResourceItem` | 相关性分类、移动计划、写操作 |
+| `lark-drive-workflow-topic-move-collector-review-plan.md` | `RELEVANCE_CLASSIFY`、`PLAN_MOVE`、`MovePlanItem`、展示分组 | 资源解析、内容验证、写操作执行、恢复 |
+| `lark-drive-workflow-topic-move-collector-execute.md` | `CONFIRM_EXECUTION`、`EXECUTE`、`VERIFY`、`RESTORE`、`RollbackSnapshotItem`、执行日志 | 搜索、分类和计划 schema |
+
+## 运行时状态
+
+本 workflow 扩展共享 Artifact Contract。agent 在一次 workflow 运行中必须维护以下专项内部字段：
+
+| 字段 | 说明 |
+|-------|------|
+| `current_state` | 当前状态机节点。 |
+| `topic` | 用户确认后的主题、关键词、同义词和排除词。 |
+| `target_location` | 目标位置解析结果，见 setup 文件的 `TargetLocation`。 |
+| `identity` | 执行身份；默认优先 `--as user`。 |
+| `owner_scope` | 搜索 owner 范围；默认 `mine`，仅搜索当前用户 owner / 负责的资源；用户明确要求扩展时才为 `all_visible`。 |
+| `constraints` | 用户显式确认的类型、时间、创建人、范围等限制。 |
+| `allow_cross_container_move` | 是否允许跨 Drive / Wiki 容器移动；默认允许，但必须展示给用户确认。 |
+| `recall_query_states` | 每个基础 / 增强 query 的分页状态、累计页数、`next_page_token`、`has_more`、完成或阻塞状态。 |
+| `candidate_items` | 搜索召回结果，包含 query 证据和去重信息。 |
+| `resource_items` | 解析后的标准资源列表。 |
+| `content_verify_completed` | 内容验证阶段完成标记；`resource_items` 新建或变化时重置为 `false`，只有全部资源都有验证状态或跳过原因后才设为 `true`。 |
+| `relevance_groups` | 高相关、中相关、低相关、无权限、无移动权限、移动权限未知、无法验证、不可移动分组。 |
+| `move_plan_items` | 经用户选择后生成的完整移动计划，包含稳定资源关联、不可变命令参数、权限快照和恢复输入。 |
+| `execution_journal` | 写操作日志，用于验证和恢复。 |
+| `rollback_snapshot` | 写操作前位置快照，仅用于失败恢复或用户要求恢复。 |
+| `display_page_state` | 用户可见列表的分页、筛选和展开状态。 |
+
+## 执行状态机
+
+| 状态 | Protocol Step | 进入条件 | agent 必须执行 | 用户可见输出 | `wait_for_user` | 下一状态 |
+|-------|---------------|-----------------|---------------|--------------------|---------------|------------|
+| `PARSE_INPUT` | `route` / `scope` | workflow 被触发 | 加载 setup 文档；解析主题、目标、身份和限制 | 澄清问题或解析摘要 | 必填字段缺失时为 `true` | `RESOLVE_TARGET` |
+| `RESOLVE_TARGET` | `scope` | 主题和目标已获得 | 解析已有目标，或解析待创建目标；按解析状态分流 | 目标解析结果或 blocker | 非 `resolved` 时为 `true` | `resolved` 时进入 `CONFIRM_CONTEXT`；否则保持本状态 |
+| `CONFIRM_CONTEXT` | `scope` | `target_resolve_status=resolved` | 展示主题、目标、身份、限制和跨容器设置 | 搜索前确认 UI | `true` | `SEARCH_RECALL` |
+| `SEARCH_RECALL` | `read` | 用户确认上下文 | 用原始关键词、默认 owner 范围和显式限制执行基础召回；按每批最多 5 页自动续批 | 搜索进度 / 基础统计 | 阻塞时为 `true` | 所有基础 query 完成后进入 `RECALL_ENHANCE` |
+| `RECALL_ENHANCE` | `read` | 所有基础 query 已完成 | 执行覆盖增强 query，按每批最多 5 页自动续批并合并结果 | 增强召回摘要 | 阻塞时为 `true` | 所有增强 query 完成后进入 `RESOURCE_RESOLVE` |
+| `RESOURCE_RESOLVE` | `read` | 候选列表已准备 | 解析 token、类型、父级位置、owner 和移动资格 | 解析进度 / 阻塞摘要 | 阻塞时为 `true` | `CONTENT_VERIFY` |
+| `CONTENT_VERIFY` | `read` | 资源列表已准备 | 对支持的资源做有界内容读取，并为其余资源写入跳过原因 | 验证进度 / 验证摘要 | 阻塞时为 `true` | `RELEVANCE_CLASSIFY` |
+| `RELEVANCE_CLASSIFY` | `assess` | 证据已准备 | 按相关性和可执行性分组 | 分组结果列表 | `false` | `PLAN_MOVE` |
+| `PLAN_MOVE` | `assess` / `plan` | 分组完成 | 基于默认规则和用户可选项生成移动计划 | 草案计划和选择项 | `true` | `CONFIRM_EXECUTION` |
+| `CONFIRM_EXECUTION` | `confirm` | 用户要求执行 | 展示创建、移动、跳过项和风险 | 写操作确认 UI | `true` | `EXECUTE` 或 `PLAN_MOVE` 或 `DONE` |
+| `EXECUTE` | `execute` | 用户明确确认写操作 | 需要时先创建目标，再移动确认资源 | 执行进度 | 阻塞时为 `true` | `VERIFY` 或 `RESTORE` |
+| `VERIFY` | `verify` | 执行完成 | 验证目标位置下的移动结果 | 验证结果 | 提供恢复选项时为 `true` | `DONE` 或 `RESTORE` |
+| `RESTORE` | `recovery confirm` / `recovery execute` | 用户要求恢复 | 仅基于快照和日志恢复 | 恢复确认 / 结果 | 写操作前为 `true` | `VERIFY` 或 `DONE` |
+| `DONE` | `done` | 无后续操作 | 停止 | 最终回复 | `false` | 结束 |
+
+### 状态跳转硬约束
+
+1. `RESOLVE_TARGET` 只有在 `target_resolve_status=resolved` 时才能进入 `CONFIRM_CONTEXT`；`ambiguous`、`unsupported` 或 `permission_denied` 必须保持在 `RESOLVE_TARGET` 并等待用户选择、更换目标或结束。
+2. `SEARCH_RECALL` 只有在全部基础 query 的 `has_more=false` 时才能进入 `RECALL_ENHANCE`；单批达到 5 页但仍有更多结果时必须自动续批，不得提前跳转。
+3. `RECALL_ENHANCE` 只有在全部增强 query 的 `has_more=false` 时才能进入 `RESOURCE_RESOLVE`；不得直接进入 `RELEVANCE_CLASSIFY` 或 `PLAN_MOVE`。
+4. `RESOURCE_RESOLVE` 必须为每个 `CandidateItem` 生成对应的 `ResourceItem`，或生成明确的解析失败 / 权限受限状态。
+5. `RESOURCE_RESOLVE` 必须为每个 `ResourceItem` 写入 `move_permission_state` 和 `move_permission_basis`；完成后将 `content_verify_completed=false`，下一状态只能是 `CONTENT_VERIFY`。
+6. 禁止从 `RESOURCE_RESOLVE` 直接进入 `RELEVANCE_CLASSIFY`。即使没有任何资源可以读取正文，也必须进入 `CONTENT_VERIFY`，为每项写入验证状态或跳过原因并输出验证摘要。
+7. `CONTENT_VERIFY` 必须为每个 `ResourceItem` 写入内容证据、搜索证据复用说明，或不可验证原因；移动权限未知或无移动权限的资源可以只写入跳过验证原因。
+8. 只有当 `resource_items` 已准备、每项都有验证状态或跳过原因，且 `content_verify_completed=true` 时，才能进入 `RELEVANCE_CLASSIFY`。
+9. 用户调整相关性分组后，必须回到 `RELEVANCE_CLASSIFY` 输出调整后的分组结果，再进入 `PLAN_MOVE` 重新生成计划。
+
+### Workflow 切换门禁
+
+只有以下情况允许考虑切换 workflow：
+
+1. 用户明确说不再做主题资料收集，改为整理整个目录结构或生成盘点方案。
+2. 当前 workflow 明确无法覆盖用户的新目标。
+3. 用户要求的是目录结构治理，而不是查找主题相关资料并移动。
+
+即使满足以上条件，也不得自动切换；必须先向用户说明原因并等待确认。
+
+## 渐进加载关系
+
+| 状态 | 必读文档 |
+|-------|---------------|
+| `PARSE_INPUT` / `RESOLVE_TARGET` / `CONFIRM_CONTEXT` | [`lark-drive-workflow-topic-move-collector-setup.md`](lark-drive-workflow-topic-move-collector-setup.md) |
+| `SEARCH_RECALL` / `RECALL_ENHANCE` | [`lark-drive-workflow-topic-move-collector-recall.md`](lark-drive-workflow-topic-move-collector-recall.md) |
+| `RESOURCE_RESOLVE` / `CONTENT_VERIFY` | [`lark-drive-workflow-topic-move-collector-resolve-verify.md`](lark-drive-workflow-topic-move-collector-resolve-verify.md) |
+| `RELEVANCE_CLASSIFY` / `PLAN_MOVE` | [`lark-drive-workflow-topic-move-collector-review-plan.md`](lark-drive-workflow-topic-move-collector-review-plan.md) |
+| `CONFIRM_EXECUTION` / `EXECUTE` / `VERIFY` / `RESTORE` | [`lark-drive-workflow-topic-move-collector-execute.md`](lark-drive-workflow-topic-move-collector-execute.md) |
+
+## 命令映射
+
+| 状态 | 允许的命令族 | 用途 |
+|-------|--------------------------|---------|
+| `RESOLVE_TARGET` | `drive +inspect`、`wiki +node-get`、`wiki +space-list`、仅用于查找文件夹候选的 `drive +search` | 解析目标位置 |
+| `SEARCH_RECALL` / `RECALL_ENHANCE` | `drive +search` | 搜索召回和覆盖增强 |
+| `RESOURCE_RESOLVE` | `drive +inspect`、`wiki +node-get`、`drive metas batch_query`、必要时 `drive permission.members auth` | 解析标准 token、owner、权限信号和移动资格 |
+| `CONTENT_VERIFY` | `docs +fetch`、`sheets +read`、`sheets +find`、必要时 `drive +preview` | 验证内容证据 |
+| `EXECUTE` | `drive +create-folder`、`wiki +node-create`、`drive +move`、`wiki +move`、`wiki +move-to-drive`、`drive +task_result` | 执行已确认写操作 |
+| `VERIFY` | `drive files list`、`wiki +node-list`、`wiki +node-get`、`drive +inspect`、`drive +task_result` | 验证执行结果 |
+| `RESTORE` | `drive +move`、`wiki +move`、`drive +delete`、`wiki +node-delete`、`drive +task_result` | 恢复已确认资源并清理本次新建目标 |
+
+## 引用文档
+
+- [输入与目标确认](lark-drive-workflow-topic-move-collector-setup.md)
+- [召回](lark-drive-workflow-topic-move-collector-recall.md)
+- [资源解析与内容验证](lark-drive-workflow-topic-move-collector-resolve-verify.md)
+- [审核与计划](lark-drive-workflow-topic-move-collector-review-plan.md)
+- [执行](lark-drive-workflow-topic-move-collector-execute.md)
+- [lark-drive-search](lark-drive-search.md)
+- [lark-drive-inspect](lark-drive-inspect.md)
+- [lark-drive-move](lark-drive-move.md)
+- [lark-drive-create-folder](lark-drive-create-folder.md)
+- [lark-drive-delete](lark-drive-delete.md)
+- [lark-wiki-move](../../lark-wiki/references/lark-wiki-move.md)
+- [lark-wiki-move-to-drive](../../lark-wiki/references/lark-wiki-move-to-drive.md)
+- [lark-wiki-node-create](../../lark-wiki/references/lark-wiki-node-create.md)
+- [lark-wiki-node-delete](../../lark-wiki/references/lark-wiki-node-delete.md)

package/skills/lark-drive/references/lark-drive-workflow.md

@@ -97,7 +97,7 @@ Structure Level：
 2. Entry file 超过约 300 行时，优先拆 `commands`、`outputs` 或 `artifacts` reference。
 3. 只有执行、验证、恢复或 rollback 状态链复杂到影响可读性时，才升级到 `S3` phase files。
 4. 垂直业务包优先作为已有 workflow 的 recipe / policy / template，不默认新增独立 workflow。
-5. 已有样板：`permission_governance` 是 `R2/S2`；已发布的独立 `knowledge_organize` 是 `R2-R3/S3`，当前不作为本总框架 registry entry。
+5. 已有样板：`permission_governance` 是 `R2/S2`；`knowledge_organize` 和 `topic_move_collector` 是 `R2-R3/S3`。
 
 ## 加载与拆分边界
 
@@ -108,9 +108,11 @@ Structure Level：
 
 ## Workflow Registry
 
-| Workflow | Status | Risk | Structure | Entry File | Trigger |
-|----------|--------|------|-----------|------------|---------|
+| Workflow | Status | Risk | Structure | Entry File | Trigger                                                         |
+|----------|--------|------|-----------|------------|-----------------------------------------------------------------|
 | `permission_governance` | Registered | `R2` | `S2` | [`lark-drive-workflow-permission-governance.md`](lark-drive-workflow-permission-governance.md) | 权限审计、公开链接/外部访问、复制/下载/评论/分享设置、权限申请、owner 转移 / 批量 owner 转移、密级标签调整 |
+| `knowledge_organize` | Registered | `R2-R3` | `S3` | [`lark-drive-workflow-knowledge-organize.md`](lark-drive-workflow-knowledge-organize.md) | 整理云盘 / 文件夹 / 文档库 / 知识库、盘点目录结构、归类资源、生成整理方案，并在用户确认后创建目录或移动资源      |
+| `topic_move_collector` | Registered | `R2-R3` | `S3` | [`lark-drive-workflow-topic-move-collector.md`](lark-drive-workflow-topic-move-collector.md) | 按主题、关键词或内容线索跨容器搜索资料，验证相关性和移动资格，并在用户确认后归档到 Drive 文件夹或 Wiki 节点    |
 
 ## Workflow Loading
 

package/skills/lark-event/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-event
 version: 1.0.0
-description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM messages/reactions/chat changes, Task updates, VC meeting started/joined/ended, Minutes generated, Whiteboard updated, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses."
+description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM messages/reactions/chat changes, Approval status changes, Task updates, VC meeting started/joined/ended, Minutes generated, Whiteboard updated, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses."
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -147,6 +147,8 @@ Lark-defined semantic tags (**not** JSON Schema's standard `format`). Common val
 
 | Topic      | Reference                                                                    | Coverage |
 |------------|------------------------------------------------------------------------------|---|
+| Application | [`references/lark-event-application.md`](references/lark-event-application.md) | Catalog of Application EventKeys, including `application.bot.menu_v6` for custom bot menu push events + flattened `event_key` / operator fields + jq recipe |
+| Approval   | [`references/lark-event-approval.md`](references/lark-event-approval.md)     | Catalog of 2 Approval EventKeys (`approval.instance.status_changed_v4`, `approval.task.status_changed_v4`) + optional/multi `subscription_type` pre-registration + user-auth subscription lifecycle + flat output field reference |
 | IM         | [`references/lark-event-im.md`](references/lark-event-im.md)                 | Catalog of 12 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender); for `card.action.trigger` see also [`../lark-im/references/lark-im-card-action-reply.md`](../lark-im/references/lark-im-card-action-reply.md) |
 | Task       | [`references/lark-event-task.md`](references/lark-event-task.md)             | Catalog of 1 Task EventKey (`task.task.update_user_access_v2`) + Native V2 envelope shape + task commit types + user/bot subscription notes |
 | VC         | [`references/lark-event-vc.md`](references/lark-event-vc.md)                 | Catalog of 4 VC EventKeys (`vc.meeting.participant_meeting_started_v1`, `vc.meeting.participant_meeting_joined_v1`, `vc.meeting.participant_meeting_ended_v1`, `vc.note.generated_v1`) + field reference + source type semantics (meeting only) |

package/skills/lark-event/references/lark-event-application.md

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

package/skills/lark-event/references/lark-event-approval.md

@@ -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}'
+```

package/skills/lark-im/SKILL.md

@@ -41,13 +41,14 @@ Chat (oc_xxx)
 - `--as bot` means **bot identity** and uses `tenant_access_token`. Calls run as the app bot, so behavior depends on the bot's membership, app visibility, availability range, and bot-specific scopes.
 - If an IM API says it supports both `user` and `bot`, the token type changes who the operator is. The same API can succeed with one identity and fail with the other because owner/admin status, chat membership, tenant boundary, or app availability are checked against the current caller.
 
-### Sender Name Resolution with Bot Identity
+### Sender Name Resolution
 
-When using bot identity (`--as bot`) to fetch messages (e.g. `+chat-messages-list`, `+threads-messages-list`, `+messages-mget`), sender names may not be resolved (shown as open_id instead of display name). This happens when the bot cannot access the user's contact info.
+When fetching messages (`+chat-messages-list`, `+threads-messages-list`, `+messages-mget`, `+messages-search`), the CLI shows a display name for both user and bot senders:
 
-**Root cause**: The bot's app visibility settings do not include the message sender, so the contact API returns no name.
+- **Server-provided name**: the read APIs return `sender_name` (plus the full-i18n `sender_i18n_names` map) on each message `sender`; the CLI surfaces it as the sender's `name` for users and bots alike. No name lookup and no extra permission are needed — **no contact scope** and no `application:bot.basic_info:read`.
+- **Fallback to id**: when the server does not provide a name, the sender is shown by its id and the command still exits 0. There is no contact-directory fallback.
 
-**Solution**: Check the app's visibility settings in the Lark Developer Console — ensure the app's visible range covers the users whose names need to be resolved. Alternatively, use `--as user` to fetch messages with user identity, which typically has broader contact access.
+The raw `sender_name` is not duplicated in output (its value is in `name`); the full `sender_i18n_names` map (all locales) is preserved for consumers that need a specific language, alongside an optional `open_bot_id` (`ou_`) for bot senders aligned with the message-receive event channel. System messages (`msg_type: system`) have no sender name — that is normal, not an error.
 
 ### Default message enrichment (reactions / update_time)
 
@@ -116,7 +117,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination |
 | [`+flag-create`](references/lark-im-flag-create.md) | Create a bookmark on a message; user-only; defaults to message-layer flag; use --flag-type feed for feed-layer flag (item_type auto-detected from chat mode) |
 | [`+flag-cancel`](references/lark-im-flag-cancel.md) | Cancel (remove) a bookmark. When no --flag-type is given, best-effort double-cancel: removes message layer and (when chat_type is determinable) feed layer |
-| [`+flag-list`](references/lark-im-flag-list.md) | List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-pagination |
+| [`+flag-list`](references/lark-im-flag-list.md) | List bookmarks; user-only; auto-enriches feed-type thread entries with message content; `--page-all` is capped by `--page-limit` (default 20, max 1000), and `has_more=true` means the result is incomplete |
 | [`+feed-shortcut-create`](references/lark-im-feed-shortcut-create.md) | Add chats to the user's feed shortcuts; user-only; oc_xxx chat IDs only; batch up to 10 per call; `--head`/`--tail` controls insertion order; partial failures return an `ok:false` ledger |
 | [`+feed-shortcut-remove`](references/lark-im-feed-shortcut-remove.md) | Remove chats from the user's feed shortcuts; user-only; batch up to 10 per call; removing an absent shortcut is idempotent success; real per-item failures return an `ok:false` ledger |
 | [`+feed-shortcut-list`](references/lark-im-feed-shortcut-list.md) | List one page of the user's feed shortcuts; user-only; omit `--page-token` for the first page; default output enriches CHAT entries under `detail`; pass `--no-detail` to skip the extra lookup and `im:chat:read` scope |

package/skills/lark-im/references/card/card-2.0-schema.md

@@ -29,7 +29,7 @@ Card 2.0 组件按**容器 / 展示 / 交互**三类，均通过 `tag` 字段声
     "title":    { "tag": "plain_text", "content": "卡片标题" },
     "subtitle": { "tag": "plain_text", "content": "副标题：一句上下文（时间/来源/状态）" },
     "template": "blue",
-    "icon": { "tag": "standard_icon", "token": "notice_colorful" },
+    "icon": { "tag": "standard_icon", "token": "lark-logo_colorful" },
     "text_tag_list": [
       { "tag": "text_tag", "text": { "tag": "plain_text", "content": "状态标签" }, "color": "blue" }
     ]

package/skills/lark-im/references/card/lark-im-card-style.md

@@ -105,12 +105,12 @@
 "header": {
   "title": { "tag": "plain_text", "content": "卡片标题" },
   "template": "blue",
-  "icon": { "tag": "standard_icon", "token": "mail_colorful" }
+  "icon": { "tag": "standard_icon", "token": "calendar_colorful" }
 }
 ```
 
-- `token` 从 `resource/icons.md` 按场景选取；彩色图标用 `*_colorful` 后缀，单色用普通名称。
-- 常用速查：通知 `notice_colorful`、告警 `warning_colorful`、审批 `approve_colorful`、日历 `calendar_colorful`、数据 `chart_colorful`、任务 `todo_colorful`、AI `myai_colorful`。
+- `token` 必须从 `resource/icons.md` 的精确枚举中选择；禁止根据名称规律自行拼接 token。没有合适的 token 时省略 icon。
+- 场景速查：日历 `calendar_colorful`、待办 `todo_colorful`、投票 `vote_colorful`、妙记 `file-lark-minutes_colorful`、多维表格 `wiki-bitable_colorful`、表单 `file-form_colorful`、社区 `larkcommunity_colorful`、招聘 `hirelogo_colorful`、飞书品牌 `lark-logo_colorful`、Meego `meego_colorful`、AI `myai_colorful`、aPaaS `apaas_colorful`、审批 `approval_colorful`、通用 AI `ai-common_colorful`。
 
 ### 1. 配色纪律（服务 P6 语义一致）
 
@@ -212,7 +212,7 @@ header 有三层能力，**尽量用满**（至少用 `title` + `icon`；`subtit
   "title":    { "tag": "plain_text", "content": "发版审批" },
   "subtitle": { "tag": "plain_text", "content": "2026-06-25 · 后端服务" },
   "template": "blue",
-  "icon": { "tag": "standard_icon", "token": "approve_colorful" },
+  "icon": { "tag": "standard_icon", "token": "approval_colorful" },
   "text_tag_list": [
     { "tag": "text_tag", "text": { "tag": "plain_text", "content": "待审批" }, "color": "yellow" }
   ]

package/skills/lark-im/references/card/resource/icons.md

@@ -34,5 +34,19 @@
 | 通知/铃铛 | `bell_outlined` | 定位 | `pin_outlined` |
 | 附件 | `attachment_outlined` | 审批 | `approval_outlined` |
 
+## 彩色图标（精确 token）
+
+彩色图标必须从下表按**完整字符串**选择，禁止根据名称规律自行拼接。彩色 token 自带颜色，不要再推导其他后缀或变体。
+
+| 含义 | token | 含义 | token |
+|---|---|---|---|
+| 日历 | `calendar_colorful` | 待办 | `todo_colorful` |
+| 投票 | `vote_colorful` | 飞书妙记 | `file-lark-minutes_colorful` |
+| 多维表格 | `wiki-bitable_colorful` | 表单 | `file-form_colorful` |
+| 飞书社区 | `larkcommunity_colorful` | 招聘 | `hirelogo_colorful` |
+| 飞书品牌 | `lark-logo_colorful` | Meego | `meego_colorful` |
+| AI | `myai_colorful` | aPaaS | `apaas_colorful` |
+| 审批 | `approval_colorful` | 通用 AI | `ai-common_colorful` |
+
 > token 必须与官方完全一致，否则图标不渲染。上表为常用项，全量（数百个，分系统/商务/沟通/用户/媒体/文档等类目）以官方图标库为准：
 > https://open.larkoffice.com/document/feishu-cards/enumerations-for-icons

package/skills/lark-im/references/lark-im-flag-list.md

@@ -6,9 +6,9 @@ This skill maps to shortcut: `lark-cli im +flag-list`. Underlying API: `GET /ope
 
 ## Sorting Rules (Important)
 
-The API returns data sorted by `update_time` in **ascending order**, meaning **oldest first, newest last**. When `has_more=true`, you cannot simply take the first page's items as the latest flags — you must paginate through all pages and take the last item on the last page as the newest.
+The API returns data sorted by `update_time` in **ascending order**, meaning **oldest first, newest last**. When `has_more=true`, continue pagination until `has_more=false`; only then is the last item in the merged result authoritative as the newest flag. If pagination stops while `has_more=true`, the last item is only the newest observed flag.
 
-Recommended: use `--page-all` for auto-pagination to get the complete list, then use `-q '.data.flag_items[-1]'` to get the latest item.
+`--page-all` enables automatic pagination but is still capped by `--page-limit`. The default cap is 20 pages; **20 is not the hard maximum**. Set `--page-limit` between 1 and 1000 when a larger scan is required. A response with `has_more=true` is incomplete, even when `flag_items` is empty; increase the limit or resume from the returned `page_token` before reporting an authoritative latest item or count.
 
 ## Commands
 
@@ -19,7 +19,7 @@ lark-cli im +flag-list --as user
 # Manual pagination with custom page size
 lark-cli im +flag-list --as user --page-size 30 --page-token <page_token>
 
-# Auto-paginate to get all flags (recommended)
+# Auto-paginate, capped at the default 20 pages
 lark-cli im +flag-list --as user --page-all
 
 # Auto-paginate + get the latest flag
@@ -31,8 +31,8 @@ lark-cli im +flag-list --as user --page-all -q '.data.flag_items[].item_id'
 # Disable auto-enrichment of message content (enabled by default)
 lark-cli im +flag-list --as user --page-all --enrich-feed-thread=false
 
-# Limit max pages (default 20, max 1000)
-lark-cli im +flag-list --as user --page-all --page-limit 10
+# Use the largest supported page limit for a broader scan
+lark-cli im +flag-list --as user --page-all --page-limit 1000
 ```
 
 ## Parameters
@@ -41,8 +41,8 @@ lark-cli im +flag-list --as user --page-all --page-limit 10
 |------|------|------|
 | `--page-size <n>` | 50 | Range 1-50 (server max is 50) |
 | `--page-token <token>` | empty | Pagination token from previous page; empty string must still be provided |
-| `--page-all` | false | Auto-paginate to fetch all pages and merge results |
-| `--page-limit <n>` | 20 | Max pages in `--page-all` mode (max 1000) |
+| `--page-all` | false | Auto-paginate and merge results, capped by `--page-limit` |
+| `--page-limit <n>` | 20 | Max pages in `--page-all` mode; configurable range 1-1000 (20 is only the default) |
 | `--enrich-feed-thread` | true | Auto-enrich feed-layer thread entries with message content (calls `im.messages.mget`) |
 | `--as user` | Required | Currently only supports user identity |
 
@@ -62,6 +62,7 @@ Note: `(thread, feed)` / `(msg_thread, feed)` entries are automatically enriched
 
 ## Limitations
 
+- **Auto-pagination is bounded**: `--page-all` fetches at most 20 pages by default. If the response still has `has_more=true`, the result is incomplete; increase `--page-limit` up to 1000 or resume with `page_token`. Never interpret `flag_items: []` as an authoritative zero while more pages remain. Historical `delete_flag_items` may occupy early pages and push active flags to later pages.
 - **delete_flag_items are not enriched**: Message content is only fetched for active flags (`flag_items`), not canceled flags (`delete_flag_items`). If you need message content for a canceled flag, query the message separately using `+messages-mget --message-ids <item_id>`.
 
 ## Response Example (Sanitized)

package/skills/lark-im/references/lark-im-messages-reply.md

@@ -188,7 +188,7 @@ lark-cli im +messages-reply --message-id om_xxx --msg-type interactive --content
 | `--video-cover <path\|url\|key>` | **Required with `--video`** | Cwd-relative local cover image path, URL, or `image_key` (`img_xxx`)                                                                                                                          |
 | `--audio <path\|url\|key>` | One content option | Voice-message audio key, URL, or cwd-relative local path. Local paths and URLs must be Opus (`.opus` or Ogg Opus `.ogg`) |
 | `--reply-in-thread` | No | Reply inside the thread. The reply appears in the target message's thread instead of the main chat stream                                                                                     |
-| `--idempotency-key <key>` | No | Idempotency key; the same key sends only one reply within 1 hour                                                                                                                              |
+| `--idempotency-key <key>` | No | Idempotency key, max 50 characters; the same key sends only one reply within 1 hour                                                                                                          |
 | `--as <identity>` | No | Identity type: `bot` or `user` (default `bot`)                                                                                                                                                |
 | `--dry-run` | No | Print the request only, do not execute it                                                                                                                                                     |
 

package/skills/lark-im/references/lark-im-messages-send.md

@@ -191,7 +191,7 @@ lark-cli im +messages-send --chat-id oc_xxx --msg-type interactive --content '<c
 | `--video-cover <path\|url\|key>` | **Required with `--video`** | Cwd-relative local cover image path, URL, or `image_key` (`img_xxx`). Local paths and URLs are uploaded automatically                                                                         |
 | `--audio <path\|url\|key>` | One content option | Voice-message audio key, URL, or cwd-relative local path. Local paths and URLs must be Opus (`.opus` or Ogg Opus `.ogg`) |
 | `--msg-type <type>` | No | Message type (default `text`). If you use `--text` / `--markdown` / media flags, the effective type is inferred automatically. Explicitly setting a conflicting `--msg-type` fails validation |
-| `--idempotency-key <key>` | No | Idempotency key; the same key sends only one message within 1 hour                                                                                                                            |
+| `--idempotency-key <key>` | No | Idempotency key, max 50 characters; the same key sends only one message within 1 hour                                                                                                        |
 | `--as <identity>` | No | Identity type: `bot` or `user` (default `bot`)                                                                                                                                                |
 | `--dry-run` | No | Print the request only, do not execute it                                                                                                                                                     |