@amaster.ai/pi-lark 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -61,7 +61,7 @@
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.13"
+    "@amaster.ai/pi-shared": "0.1.15"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-apps/references/lark-apps-local-dev.md

@@ -66,7 +66,7 @@ lark-cli apps +release-get --as user --app-id app_xxx --release-id <上一步返
 
 #### 首次开发（无 app，无代码）
 
-`+create(html)` → `+init` → 加载 [`creative-design`](../creative-design/SKILL.md) skill 在 repo 根目录产出文件 → `git add .` + `git commit` → `git push origin sprint/default` → `+release-create` → `+release-get`。
+`+create(html)` → `+init` → 加载 [`creative-design`](../creative-design/creative-design.md) skill 在 repo 根目录产出文件 → `git add .` + `git commit` → `git push origin sprint/default` → `+release-create` → `+release-get`。
 
 ```bash
 lark-cli apps +create --name "活动页" --app-type html --as user

package/skills/lark-base/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-base
-version: 1.2.21
+version: 1.2.22
 description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。"
 metadata:
   requires:
@@ -209,8 +209,9 @@ Form 依附于 Table，以 Field 作为题目，每次有效提交会创建一
 
 1. **读取 Table 中的表单配置：** 使用 `+form-list` / `+form-get` 读取表单，使用 `+form-questions-list` 读取题目配置；这些命令使用表单所属的 `base_token + table_id`。
 2. **创建或修改 Table 中的表单配置：** 使用 `+form-create` / `+form-update` / `+form-delete` 管理表单；题目由 Table Field 承载，question ID 对应 `field_id`，创建和更新分别读取 [questions create](references/lark-base-form-questions-create.md) / [questions update](references/lark-base-form-questions-update.md)，删除使用 `+form-questions-delete`。
-3. **管理表单分享：** 使用 `+form-share-get` / `+form-share-update` 管理启停、访问范围和匿名/登录要求；更新前先读取现状，每次只修改一个字段，布尔值显式传 `true` 或 `false`。
-4. **填写分享表单并提交：** 对表单分享链接使用 `+url-resolve` 取得 `share_token`，按 [Form detail](references/lark-base-form-detail.md) 执行 `+form-detail` 读取真实题目、必填项和显示条件，再按 [Form submit](references/lark-base-form-submit.md) 构造字段与附件并执行 `+form-submit`。
+3. **调整表单题目显隐和顺序：** Form 在 `visible_fields` 接口中作为 View，`form_id` 传给 `--view-id`。用 `+view-get-visible-fields` 读取当前可见题目，再用 `+view-set-visible-fields` 提交最终需要展示的完整有序题目 ID 列表；省略当前可见题目会隐藏它，加入已有隐藏 Form 成员会重新展示，空列表会隐藏全部题目。目标只能包含已有 Form 成员；仍显示题目的 `visible_rule` 只能引用位于它之前的可见题目。
+4. **管理表单分享：** 使用 `+form-share-get` / `+form-share-update` 管理启停、访问范围和匿名/登录要求；更新前先读取现状，每次只修改一个字段，布尔值显式传 `true` 或 `false`。
+5. **填写分享表单并提交：** 对表单分享链接使用 `+url-resolve` 取得 `share_token`，按 [Form detail](references/lark-base-form-detail.md) 执行 `+form-detail` 读取真实题目、必填项和显示条件，再按 [Form submit](references/lark-base-form-submit.md) 构造字段与附件并执行 `+form-submit`。
 
 表单题目和字段的关系：
 

package/skills/lark-base/references/lark-base-app.md

@@ -23,7 +23,7 @@
 当前 CLI 只支持用 `+workspace-move-in` 把 Base 或 BaseApp 移入 Workspace，不支持从 Workspace 移出或移除资源，也没有 `workspace move-out` / `workspace remove` 命令。这类请求必须先完成只读定位，再说明限制并停止，顺序不可调换：
 
 1. Workspace URL 含 `/base/workspace/<workspace_token>` 时，提取其中的真实 `workspace_token`，不要把完整 URL 当作命令参数。
-2. 在同一轮立即执行 `lark-cli base +workspace-entity-list --workspace-token <workspace_token> --page-size 100 --as user`；若 `has_more=true`，继续分页直到完整。该查询是必要的只读定位步骤，不要把它留成等待用户再次选择的可选项，也不要用 `--help` 代替真实查询。
+2. 在同一轮立即执行 `lark-cli base +workspace-entity-list --workspace-token <workspace_token> --page-size 30 --as user`；若 `has_more=true`，继续分页直到完整。该查询是必要的只读定位步骤，不要把它留成等待用户再次选择的可选项，也不要用 `--help` 代替真实查询。
 3. 用服务端返回的 `entities[].name`、`entity_type`、`token` 和 `url` 忠实判断目标。名称完全匹配时报告真实对象；没有完全匹配时明确说明不存在精确同名实体，并原样列出可能相关的候选。不得自动去掉或补齐前后缀，也不得仅凭名称相似就声称已经定位目标。用户直接给出 token 时仍要忠实报告该 token 对应的实际名称。
 4. 定位结果报告完后，明确说明当前 CLI 无法执行 Workspace 移出/移除，并停止，不要发起任何写请求。用户在任一步骤中取消时立即停止，取消后不再调用工具。
 
@@ -55,7 +55,7 @@ lark-cli base +app-get --app-token <app_token>
   lark-cli base +workspace-entity-list \
     --workspace-token <workspace_token> \
     --type baseapp \
-    --page-size 100
+    --page-size 30
   ```
 
 - 响应中的 `pages` 是页面摘要。

package/skills/lark-base/references/lark-base-dashboard-block-config.md

@@ -224,7 +224,7 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
   - `group_by[].sort.type` 为 `group` 或 `view` 且缺少 `order` 时，自动补 `order:"asc"`；`value` 排序不会自动补方向
 - 本地校验（可通过 `--no-validate` 跳过）
   - `+dashboard-block-create` 默认对 `data_config` 做轻量校验；失败会聚合错误并给出修复建议
-  - `+dashboard-block-update` 不带 `--type`，所以不做按组件类型的强校验，字段由后端验证；但 `number_format` 子字段与 create 一样本地拦截（见下方 number_format 小节）
+  - `+dashboard-block-update` 不带 `--type`，所以不做按组件类型的强校验；但会对可解析的 `filter` 条件做轻量校验，包括 `conjunction`、字段引用、`operator` 和必需的 `value`，并与 create 一样拦截非法 `number_format` 子字段（见下方 number_format 小节）
   - 仅需传入合法 JSON；CLI 不会擅自改写你的业务含义
 
 ## 可复制模板

package/skills/lark-base/references/lark-base-workflow-schema.md

@@ -108,9 +108,8 @@
 | 需求描述 | 触发器 |
 |---------|--------|
 | 新增记录时 | `AddRecordTrigger` |
-| 字段变为特定值时（**仅修改**） | `SetRecordTrigger` |
-| **新增或修改**都触发 | `ChangeRecordTrigger` |
-| 拿不准用哪个 | `ChangeRecordTrigger` |
+| 指定字段发生修改时（仅修改，可限定修改后的值） | `SetRecordTrigger` |
+| 新增或修改记录，且满足配置的筛选条件时 | `ChangeRecordTrigger` |
 
 > ⚠️ `SetRecordTrigger` 仅监听修改，`ChangeRecordTrigger` 同时监听新增 + 修改。
 
@@ -125,6 +124,7 @@
 | `Delay` | 延迟 |
 | `LarkMessageAction` | 发送飞书消息 |
 | `GenerateAiTextAction` | AI 生成文本 |
+| `AIAnalysisAction` | AI 分析 |
 
 > 所有 Action 节点**请勿设置** `children` ，通过 `next` 串联后继。
 
@@ -134,6 +134,7 @@
 |------|------|
 | `IfElseBranch` | 条件分支，`children.links` 含 `if_true` 和 `if_false` |
 | `SwitchBranch` | 多路分支，`children.links` 含多个 `case` |
+| `AIClassificationBranch` | AI 分类分支，`children.links` 含多个 `case` |
 
 ### System 类型
 
@@ -153,7 +154,7 @@
   "table_name": "订单表",
   "watched_field_name": "状态",
   "trigger_control_list": ["pasteUpdate", "automationBatchUpdate"],
-  "condition_list": [] /* AndCondition 数组 */ 
+  "condition_list": [] /* AndCondition 数组 */
 }
 ```
 
@@ -162,7 +163,7 @@
 | `table_name` | 是 | 监控的数据表名 |
 | `watched_field_name` | 是 | 监控的字段名 |
 | `trigger_control_list` | 否 | 触发控制，可选值：`pasteUpdate` / `automationBatchUpdate` / `syncUpdate` / `appendImport` / `openAPIBatchUpdate` |
-| `condition_list` | 否 | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系 |
+| `condition_list` | 否 | 数组中的每个元素表示一个条件组，条件组之间为 OR，组内 conditions 之间必须为 AND |
 
 ### ChangeRecordTrigger
 
@@ -170,15 +171,26 @@
 {
   "table_name": "任务表",
   "trigger_control_list": [],
-  "condition": null
+  "condition_list": [
+    {
+      "conjunction": "and",
+      "conditions": [
+        {
+          "field_name": "预计工时",
+          "operator": "isGreater",
+          "value": [{ "value_type": "number", "value": 0 }]
+        }
+      ]
+    }
+  ]
 }
 ```
 
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `table_name` | 是 | 监控的数据表名 |
+| 字段 | 必填 | 说明                                                                              |
+|------|------|---------------------------------------------------------------------------------|
+| `table_name` | 是 | 监控的数据表名                                                                         |
 | `trigger_control_list` | 否 | 触发控制，可选值：`pasteUpdate` / `automationBatchUpdate` / `syncUpdate` / `appendImport` |
-| `condition_list` | 否 | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系 |
+| `condition_list` | 是 | 不能为空；数组中的每个元素表示一个条件组，条件组之间为 OR，组内 conditions 之间必须为 AND                          |
 
 ### SetRecordTrigger
 
@@ -202,7 +214,7 @@
 | `record_watch_info` | 否  | 记录级过滤条件（修改前值匹配），为空则监听全部 |
 | `field_watch_info` | 是  | 字段级监控条件列表，至少一个 |
 | `trigger_control_list` | 否  | 触发控制，可选值：`pasteUpdate` / `automationBatchUpdate` / `syncUpdate` / `appendImport` |
-| `condition_list` | 否  | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系 |
+| `condition_list` | 否  | 数组中的每个元素表示一个条件组，条件组之间为 OR，组内 conditions 之间必须为 AND |
 
 `FieldWatchItem`：
 
@@ -239,7 +251,7 @@
 {
   "table_name": "项目表",
   "field_name": "截止日期",
-  "offset": 1,
+  "offset": -1,
   "unit": "DAY",
   "hour": 9,
   "minute": 0,
@@ -252,10 +264,10 @@
 | `table_name` | 是 | 数据表名 |
 | `field_name` | 是 | 日期字段名（必须为 `datetime` / `created_at` / `formula` / `lookup` 类型） |
 | `unit` | 是 | 偏移单位：`MINUTE` / `HOUR` / `DAY` / `WEEK` / `MONTH` |
-| `offset` | 是 | 提前/延后的偏移量（正数=提前，负数=延后；范围由 `unit` 决定）：`MINUTE` ∈ {0, 5, 15, 30, -5, -15, -30}；`HOUR` ∈ [-6, -1] ∪ [1, 6]；`DAY` ∈ [-7, 7]；`WEEK` ∈ [-7, -1] ∪ [1, 7]；`MONTH` ∈ [-7, -1] ∪ [1, 7] |
+| `offset` | 是 | 提前/延后的偏移量（触发时间 = 日期字段时间 + `offset` × `unit`，因此负数=提前、正数=延后；范围由 `unit` 决定）：`MINUTE` ∈ {0, 5, 15, 30, -5, -15, -30}；`HOUR` ∈ [-6, -1] ∪ [1, 6]；`DAY` ∈ [-7, 7]；`WEEK` ∈ [-7, -1] ∪ [1, 7]；`MONTH` ∈ [-7, -1] ∪ [1, 7] |
 | `hour` | 是 | 触发小时 (0-23)，默认 9 |
 | `minute` | 是 | 触发分钟 (0-59)，默认 0 |
-| `condition_list` | 否 | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系  | 
+| `condition_list` | 否 | 数组中的每个元素表示一个条件组，条件组之间为 OR，组内 conditions 之间必须为 AND  | 
 
 
 ### ButtonTrigger
@@ -473,6 +485,26 @@
 |------|------|------|
 | `prompt` | 是 | TextRefItem[] 提示词，支持 `text` / `ref` |
 
+### AIAnalysisAction
+
+```json
+{
+  "analysis_task": [
+    { "value_type": "text", "value": "分析昨日订单趋势、异常原因，并给出行动建议" }
+  ],
+  "analysis_table_names": ["订单表", "退款表"],
+  "identity_type": "maker",
+  "output_instruction": "先给结论，再列证据与行动建议"
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `analysis_task` | 是 | TextRefItem[] 分析任务，支持 `text` / `ref` 混排；至少包含一项有效内容 |
+| `analysis_table_names` | 否 | string[] 分析数据范围；为空数组 `[]` 或省略时表示当前 Base 的全部数据表 |
+| `identity_type` | 是 | 数据访问身份：`maker`（固定流程身份） / `triggerPersonal`（流程触发者） |
+| `output_instruction` | 否 | 仅支持纯文本 |
+
 
 ## Branch data 详细结构
 
@@ -552,6 +584,45 @@
 | `name` | string | 分支名称 |
 | `condition` | OrGroup | 分支条件 |
 
+### AIClassificationBranch
+
+`AIClassificationBranch` 用 AI 对 `content` 内容做分类，再通过 `children.links` 中的 `case` 边进入命中的后续步骤。`steps[].data` 使用公开 Agent Data 协议。
+
+```json
+{
+  "classes": [
+    {
+      "name": "Bug",
+      "desc": "功能报错、异常、不可用或结果错误"
+    },
+    {
+      "name": "功能建议",
+      "desc": "希望新增能力或优化现有功能"
+    }
+  ],
+  "content": [
+    { "value_type": "text", "value": "请根据反馈内容判断类型：" },
+    { "value_type": "ref", "value": "$.step_trigger.fldFeedback" }
+  ],
+  "classification_rule": "信息不足时判定为无法匹配。"
+}
+```
+
+| 字段 | 必填 | 说明                                                                   |
+|------|------|----------------------------------------------------------------------|
+| `classes` | 是 | 分类列表，至少 2 项。每项包含 `name` 和 `desc`                                     |
+| `classes[].name` | 是 | 分类名称，需与对应普通 `children.links[].desc` 保持一致                             |
+| `classes[].desc` | 是 | 分类描述，可为空字符串，但字段必须存在                                                  |
+| `content` | 是 | TextRefItem[]，用于分类的内容，支持 `text` / `ref`                              |
+| `classification_rule` | 否 | 全局分类规则纯文本                                                            |
+| `no_match_action` | 否 | 无匹配策略。`classifyToOther`：进入默认分支；`fail`：当前节点失败。省略时使用 `classifyToOther` |
+
+`children.links` 规则：
+- 每个分类命中后要跳到哪个后续步骤，必须写在 children.links 中。
+- 普通分类边使用 `kind: "case"` 和 `label: "branch_1"`、`branch_2` 等稳定标签；`desc` 与 `classes[i].name` 保持一致；`to` 指向该分类的入口 step。
+- `no_match_action: "classifyToOther"` 时必须额外提供一条默认分支边：`{ "kind": "case", "label": "default", "desc": "默认分支", "to": "step_other_action" }`。
+- `no_match_action: "fail"` 时不要提供默认分支边。
+
 
 ## System data 详细结构
 
@@ -788,6 +859,12 @@ HTTPClientAction 的输出取决于 `response_type`：
 |--------|------|----------|
 | （整体出参） | AI 生成的文本内容（不支持下钻，只能引用 `$.{stepId}`） | `$.{stepId}` |
 
+##### AIAnalysisAction（AI 分析）
+
+| pathId | 说明 | 引用示例 |
+|--------|------|----------|
+| `analysisResult` | AI 分析结果字符串 | `$.{stepId}.analysisResult` |
+
 ##### 无输出的操作节点
 
 以下节点不产生任何可引用的输出数据：
@@ -887,6 +964,7 @@ $.{stepId}.{fieldId}.fileToken    → 文件 Token 列表（array<string>，仅
 | SetRecordAction | 动作 | ✅ | 动态（用户配置的字段） |
 | HTTPClientAction | 动作 | ✅ | 动态（取决于用户配置的 HTTP 响应输出） |
 | GenerateAiTextAction | 动作 | ✅ | 静态（单 string） |
+| AIAnalysisAction | 动作 | ✅ | 静态（`analysisResult`） |
 | Delay | 动作 | ❌ | 无输出 |
 | LarkMessageAction | 动作 | ❌ | 无输出 |
 | IfElseBranch | 分支 | ❌ | 无输出 |

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

@@ -57,9 +57,10 @@
 | 新增触发+通知 | AddRecordTrigger → LarkMessageAction | [下方](#示例1-新增记录触发--发送消息) |
 | 按钮点击+调用外部接口+写入日志 | ButtonTrigger → HTTPClientAction → AddRecordAction | [下方](#示例-6-按钮触发--调用外部接口--写入同步日志) |
 | 定时+循环 | TimerTrigger → FindRecordAction → Loop → LarkMessageAction | [下方](#示例2-定时触发--查找记录--循环遍历--发送消息) |
-| 条件判断 | ... → IfElseBranch → 分支处理 | [下方](#示例3-条件分支-ifelsebranch) |
-| 多路分类 | ... → SwitchBranch → 多分支处理 | [下方](#示例4-多路分支-switchbranch) |
-| 复杂组合 | 定时+查找+循环+分支+消息 | [下方](#示例5-组合场景-定时查找循环分支消息) |
+| 条件判断 | ... → IfElseBranch → 分支处理 | [下方](#示例3-条件分支ifelsebranch) |
+| 多路分类 | ... → SwitchBranch → 多分支处理 | [下方](#示例4-多路分支switchbranch) |
+| 复杂组合 | 定时+查找+循环+分支+消息 | [下方](#示例5-组合场景定时查找循环分支消息) |
+| AI 分类 | ... → AIClassificationBranch → 分类后处理 | [下方](#示例7-ai-分类用户反馈自动分流) |
 
 ---
 
@@ -741,6 +742,101 @@
 
 ---
 
+### 示例 7: AI 分类（用户反馈自动分流）
+
+**场景**: 当用户反馈表新增记录时，AI 根据反馈内容分类为 Bug 或功能建议；无法判断时标记为待人工复核。
+
+```json
+{
+  "client_token": "1704067206",
+  "title": "用户反馈自动分流",
+  "steps": [
+    {
+      "id": "step_trigger",
+      "type": "AddRecordTrigger",
+      "title": "新增反馈时触发",
+      "next": "step_ai_classify",
+      "data": {
+        "table_name": "用户反馈表",
+        "watched_field_name": "反馈详情"
+      }
+    },
+    {
+      "id": "step_ai_classify",
+      "type": "AIClassificationBranch",
+      "title": "AI 判断反馈类型",
+      "children": {
+        "links": [
+          { "kind": "case", "to": "step_bug_action", "label": "branch_1", "desc": "Bug" },
+          { "kind": "case", "to": "step_feature_action", "label": "branch_2", "desc": "功能建议" },
+          { "kind": "case", "to": "step_other_action", "label": "default", "desc": "默认分支" }
+        ]
+      },
+      "next": null,
+      "data": {
+        "classes": [
+          {
+            "name": "Bug",
+            "desc": "功能报错、异常、崩溃、无法使用或结果错误"
+          },
+          {
+            "name": "功能建议",
+            "desc": "希望新增能力或改变产品行为"
+          }
+        ],
+        "content": [
+          { "value_type": "ref", "value": "$.step_trigger.fldFeedbackDetail" }
+        ],
+        "classification_rule": "有明确故障现象时优先归入 Bug；同时包含多个诉求时，以最影响用户完成任务的问题为准；信息不足时进入默认分支。"
+      }
+    },
+    {
+      "id": "step_bug_action",
+      "type": "SetRecordAction",
+      "title": "标记为 Bug",
+      "next": null,
+      "data": {
+        "table_name": "用户反馈表",
+        "ref_info": { "step_id": "step_trigger" },
+        "field_values": [
+          { "field_name": "分类", "value": [{ "value_type": "text", "value": "Bug" }] }
+        ]
+      }
+    },
+    {
+      "id": "step_feature_action",
+      "type": "SetRecordAction",
+      "title": "标记为功能建议",
+      "next": null,
+      "data": {
+        "table_name": "用户反馈表",
+        "ref_info": { "step_id": "step_trigger" },
+        "field_values": [
+          { "field_name": "分类", "value": [{ "value_type": "text", "value": "功能建议" }] }
+        ]
+      }
+    },
+    {
+      "id": "step_other_action",
+      "type": "SetRecordAction",
+      "title": "标记为待人工复核",
+      "next": null,
+      "data": {
+        "table_name": "用户反馈表",
+        "ref_info": { "step_id": "step_trigger" },
+        "field_values": [
+          { "field_name": "分类", "value": [{ "value_type": "text", "value": "待人工复核" }] }
+        ]
+      }
+    }
+  ]
+}
+```
+**关键点**:
+- `classes` 按顺序对应 `branch_1`、`branch_2`；`desc` 与分类名一致，`to` 指向已定义的下游 step；
+
+---
+
 ## 构造技巧
 
 ### Loop 构造要点

package/skills/lark-calendar/SKILL.md

@@ -19,7 +19,7 @@ metadata:
 按**日程归属**选身份：
 
 - 查看/管理登录用户本人的日程 → `--as user`（默认，绝大多数场景）。
-- 查看/管理 bot 自己创建/拥有的日程 → `--as bot` 
+- 查看/管理 bot 自己创建/拥有的日程 → `--as bot`
 
 **对话人称映射**：「我」= 登录用户，「你」= 应用（bot）；作为字段取值的人称（参会人、会议 owner 等）不参与身份判定，如「你创建日程，邀请我、会议 owner 为我」→ `--as bot` 创建，登录用户仅作参会人与会议 owner。
 
@@ -35,15 +35,17 @@ lark-cli calendar +agenda --as bot
 | Shortcut | 说明 |
 |----------|------|
 | `+agenda` | 查看日程安排（默认今天） |
-| [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note），日程开过视频会议才会有meeting_id |
+| [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note），日程开过视频会议才会有meeting_id,**注意**: 视频会议链接获取走+get命令 |
 | [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） |
-| [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室 |
-| `+freebusy` | 查询用户主日历的忙闲信息和 RSVP 状态（纯查询场景；预约场景走 `+suggestion`） |
+| [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室；重复性日程/例外必须传 `--apply-to`（详见 [重复性日程操作规范](references/lark-calendar-recurring.md)） |
+| `+delete` | 删除日程；重复性日程/例外必须传 `--apply-to`（详见 [重复性日程操作规范](references/lark-calendar-recurring.md)） |
+| `+freebusy` | 查询主日历的忙闲/RSVP状态/空闲时间段。(**如需预约/推荐时间段**走 `+suggestion`——它综合工作时间、忙碌区间和休息时间推荐。) |
 | [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） |
 | [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） |
 | [`+join-event`](references/lark-calendar-join-event.md) | 凭分享 token 加入日程（分享链接/二维码/分享卡片/RSVP 卡片） |
 | [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 |
 | [`+transfer`](references/lark-calendar-transfer.md) | 把日程组织者转让给另一个用户或机器人；不可逆，需 `--yes` |
+| [`+list-attendees`](references/lark-calendar-list-attendees.md) | 列出日程的参与人和会议室（支持按 `--type` 过滤：user / resource / chat / third_party） |
 
 ### `+get` — 单日程详情
 
@@ -56,6 +58,8 @@ lark-cli calendar +get --calendar-id <calendar_id> --event-id <event_id>
 
 日程描述统一使用 `description` 一个字段，按 **Markdown** 富文本处理。读取日程时 `description` 返回 Markdown 富文本（仅有纯文本描述时返回该纯文本）；创建/更新日程时也通过 `--description` 传入 Markdown。
 
+> `+get` 返回不含参会人和会议室。需要参与人视角（用户 / 会议室 / 群 / 三方邮箱）请调用 [`+list-attendees`](references/lark-calendar-list-attendees.md)。
+
 ### `+search-event` — 按关键词、时间范围和参会人搜索日程
 
 仅返回基础字段（`event_id`/`summary`/`start`/`end` 等），需要详情请走 `+get`。
@@ -69,6 +73,17 @@ lark-cli calendar +get --calendar-id <calendar_id> --event-id <event_id>
 lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1,oc_chat1,omm_room1" --page-token <page_token> --page-size 30
 ```
 
+`--attendee-ids` 的多值语义：**同类型内为 OR（并集）**——只要日程命中列表中的任意一个同类型 ID，就会返回。
+
+- `--attendee-ids "ou_A,ou_B"` = A **或** B 参加的日程（**不是** A 和 B 都参加的）。
+
+### `+delete` — 删除日程
+
+```bash
+# calendar_id不传，默认primary
+lark-cli calendar +delete --calendar-id <calendar_id> --event-id <event_id> --notify=true
+```
+
 ### `+agenda` — 查看近期日程安排
 
 默认查询当天。结果应整理为按日期分组、按开始时间升序的易读时间线。
@@ -83,20 +98,36 @@ lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17 --calendar-id <cal
 - 已取消的日程自动过滤；无日程时直接告知"日程清空"。
 - 时间范围超过 40 天会自动拆分查询并合并结果。
 
-### `+freebusy` — 查询主日历忙闲时段和 RSVP 状态
+### `+freebusy` — 查询主日历忙闲时段 / 事件 / 公共空闲
 
-仅返回忙碌时段起止时间，不含日程标题等隐私信息；其他订阅日历不在范围内。
+`+freebusy` 一个入口承担四种视角：几何计算类（`busy` / `free` / `common_free`）走自动合并；事件维度类（`raw_busy`）保留每条上游日程 + `rsvp_status`。
 
 ```bash
 # start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天
-# user-id 目标用户 open_id（ou_ 前缀）可选；默认当前登录用户，bot 身份必须显式指定
-lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
+# user-id 目标用户 open_id，可重复或用逗号分隔；默认当前登录用户，bot 身份必须显式传至少一个
+# type 视角四选一（默认 busy）：
+#   busy         每个 user 合并后的忙碌区间（找空档、看忙碌时段）
+#   raw_busy     每个 user 的原始日程块 + rsvp_status（数会议、看每个会的 rsvp）
+#   free         每个 user 在时间窗内的空闲区间（可带 --min-duration 过滤）
+#   common_free  所有 user 的共同空闲区间（可带 --min-duration 过滤）
+# min-duration 仅对 free / common_free 生效；Go duration 格式，例如 30m、1h、90m
+
+# 查询忙碌时间段（去重并合并相邻/重叠段）
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-11 --user-id ou_a,ou_b --type busy
+
+# 看别人有几个会、每个会的起止 + rsvp（不合并相邻/重叠段，带rsvp状态）
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-11 --user-id ou_a,ou_b --type raw_busy
+
+# 查询用户空闲时间段
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-11 --user-id ou_a,ou_b --type free
+
+# 多人公共空闲时间段（推荐替代手工合并）
+lark-cli calendar +freebusy --start 2026-03-11T09:00:00+08:00 --end 2026-03-11T18:00:00+08:00 --user-id ou_a,ou_b --type common_free --min-duration 30m
 ```
 
 用法提示：
-- **仅判断是否有空** → `+freebusy`；**需要日程详情** → `+agenda`。
-- 检查多人可用性：分别调用并对比，找共同空闲。
-- 预约/改约场景下，调用规则（参与人过多、含群组、来自 `+suggestion` 等）详见 [schedule-clear-time.md § 查询忙闲](references/lark-calendar-schedule-clear-time.md#2-查询忙闲)。
+- **`+freebusy` 只适用于查询忙碌/空闲时间段这一事实**。如果目标是"给会议**推荐**一个合适的时间段"（单人或多人），必须优先使用 [`+suggestion`](references/lark-calendar-suggestion.md)——它会综合**工作时间段、忙碌时间段、休息时间段**来推荐，`+freebusy` 只回答"哪些区间空着"，不判断该区间是否适合排会。
+- **多人公共空闲**：只想拿"哪些区间共同没被占"→ `--type common_free [--min-duration <dur>]`；想拿"推荐的会议时间段"→ 走 `+suggestion`。
 
 ## 前置条件路由
 
@@ -120,6 +151,9 @@ lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
 - **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
 - **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
 - **日程会议 ID（Meeting ID）**：日程的历史视频会议 ID，在日程上开过视频会议才会有。
+- **日程分享链接 vs 会议链接**：两者是不同事物，不可混用。
+  - 日程分享链接：`https://<domain>/calendar/share?token=<token>`，指向日程本身，用于分享日程详情。**分享日程给某个人、某个群或粘贴到文档中，需要的都是这个日程分享链接（通过 `calendar events share_info` 获取），不是 applink**；禁止自己拼接 applink 或用 applink 代替。
+  - 会议链接：`https://<domain>/j/<number>`，指向视频会议入口；同一重复性日程序列的所有实例共用同一个会议链接。
 
 ## 术语映射
 
@@ -127,18 +161,20 @@ lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
 
 ## 意图路由
 
+**日程与会议的关系**：用户口中的「会议」通常不区分日程和视频会议。定义、三种查询意图（当前/未来/过去）的分流规则见 [日程与视频会议的关系](references/lark-calendar-meeting-relation.md)。
+
 | 用户意图 | 路由到 |
 |----------|--------|
-| 查询过去的会议（"昨天的会议""上周的会"） | [`../lark-meeting/SKILL.md`](../lark-meeting/SKILL.md)（会议数据含即时会议，仅查日程会遗漏） |
-| 今天有哪些会议| 需要合并两部分内容：[`../lark-meeting/SKILL.md`](../lark-meeting/SKILL.md) 中的 `vc +search` 查询今天已结束的会议， `calendar +agenda` 查询进行中或未开始的日程。|
-| 查询日历/日程或未来时间的会议 | 本 skill |
+| 查询过去的会议（"昨天的会议""上周的会"）/今天有哪些会议 / 当前正在开的会议 | 先读 [日程与视频会议的关系](references/lark-calendar-meeting-relation.md) |
+| 未来的会议 / 明天/下周的会议 | 本 skill：视频会议不存在于未来，等价于查日程 |
 | 按关键词搜索日程 | 本 skill（`+search-event`） |
-| 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
-| 把日程分享给某人 / 群 | 本 skill：先 `calendar events share_info` 取**日程分享链接**，再走 [lark-im](../lark-im/SKILL.md) 发送该链接；分享链接不是 applink，不要自己拼接或用 applink 代替 |
+| 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（[`+meeting`](references/lark-calendar-meeting.md)） |
+| 查看日程的参会人 / 会议室（含 `--type resource` 只看会议室） | 本 skill（[`+list-attendees`](references/lark-calendar-list-attendees.md)） |
+| 把日程分享给某人 / 群 / 粘贴到文档 | 本 skill：先 `calendar events share_info` 取**日程分享链接**，再走 [lark-im](../lark-im/SKILL.md) 发送或粘贴该链接；**分享日程给某个人、某个群或粘贴到文档中，需要的都是日程分享链接，不是 applink**，不要自己拼接或用 applink 代替 |
 | 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再进入 [`lark-meeting`](../lark-meeting/SKILL.md)：[`vc +detail`](../lark-meeting/references/lark-vc-detail.md) → [`note +detail`](../lark-meeting/references/lark-note-detail.md) / [`minutes +detail`](../lark-meeting/references/lark-minutes-detail.md) |
 | 预约/改约日程、调整时间、添加/更换会议室、查会议室 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
 | 仅编辑日程字段（标题/描述）或增删参会人（不涉及时间和会议室） | 先定位 `event_id`，再读 [+update](references/lark-calendar-update.md) 执行变更 |
-| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
+| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)；`+update` / `+delete` 均通过 `--apply-to=single|all|this-and-following` 指定范围 |
 | 转让日程组织者（「把这个日程交给 XX」「组织者改成 XX」「这个会转给我」「bot 建完还给我」） | 读 [+transfer](references/lark-calendar-transfer.md)；`--as` 用**当前组织者**身份，`--to-user-id` 传接收人，用户和机器人任意互转 |
 
 ## 任务类型分流
@@ -170,9 +206,6 @@ lark-cli calendar <resource> <method> [flags]
 # 查询用户主日历
 lark-cli calendar calendars primary
 
-# 获取日程详情及 app_link
-lark-cli calendar events get --calendar-id <calendar_id> --event-id <event_id>
-
 # 获取日程分享链接（分享给他人/群前必须先拿到）
 # 返回形如 {{domain}}/calendar/share?token=<token> 的分享链接，不是 applink；直接把该链接发给对方（对方可凭链接中的 token 走 +join-event 加入）
 lark-cli calendar events share_info --calendar-id <calendar_id> --event-id <event_id>
@@ -194,8 +227,8 @@ lark-cli calendar events delete --calendar-id <calendar_id> --event-id <event_id
 ## 常用其他域命令
 
 ```bash
-# 搜索用户，更多参数详见 lark-contact
-lark-cli contact +search-user --query <query> --as user
+# 批量搜索多个用户，更多参数详见 lark-contact
+lark-cli contact +search-user --queries "<q1>,<q2>" --as user
 
 # 搜索群聊，更多参数详见 lark-im
 lark-cli im +chat-search --query <query> --as user

package/skills/lark-calendar/references/lark-calendar-list-attendees.md

@@ -0,0 +1,33 @@
+# calendar +list-attendees
+
+列出单个日程的参与人（用户 / 会议室 / 群 / 三方邮箱）。只读。
+
+## 命令
+
+```bash
+# 查看指定日历（默认primary）下某日程的全部类型参与人和会议室
+lark-cli calendar +list-attendees --calendar-id <calendar_id> --event-id <event_id>
+
+# 只看会议室
+lark-cli calendar +list-attendees --event-id <event_id> --type resource
+
+# 同时看用户与会议室
+lark-cli calendar +list-attendees --event-id <event_id> --type user --type resource
+
+# 分页续拉（由调用方基于 has_more / page_token 决定是否再调一次）
+lark-cli calendar +list-attendees --event-id <event_id> --page-size 100 --page-token <page_token>
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--event-id <id>` | **是** | 目标日程 ID |
+| `--calendar-id <id>` | 否 | 日历 ID，省略则使用主日历（`primary`） |
+| `--type <type>` | 否 | 按 attendee 类型过滤；可重复或逗号分隔。枚举：`user` / `resource` / `chat` / `third_party`。留空返回全部类型|
+| `--page-size <n>` | 否 | 上游分页大小；默认 `20`|
+| `--page-token <token>` | 否 | 上游分页游标，来自上一次返回的 `page_token` |
+
+## 提示
+
+- `type=chat` 的群参与人**不返回 `rsvp_status`**（群本身没有群级 RSVP 状态）。需要群成员的 RSVP 请走原生 OpenAPI。