larksuite · yballul-bytedance · Apr 10, 2026 · Apr 7, 2026
diff --git a/shortcuts/base/workflow_create.go b/shortcuts/base/workflow_create.go
@@ -19,7 +19,7 @@ var BaseWorkflowCreate = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
-		{Name: "json", Desc: `workflow body JSON, e.g. {"title":"My Workflow","steps":[...]}; or @path/to/file.json for large definitions`, Required: true},
+		{Name: "json", Desc: `workflow body JSON, e.g. {"title":"My Workflow","steps":[...]}`, Required: true},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

diff --git a/shortcuts/base/workflow_update.go b/shortcuts/base/workflow_update.go
@@ -20,7 +20,7 @@ var BaseWorkflowUpdate = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "workflow-id", Desc: "workflow ID (wkf... prefix)", Required: true},
-		{Name: "json", Desc: `workflow body JSON, e.g. {"title":"New Title","steps":[...]}; or @path/to/file.json for large definitions`, Required: true},
+		{Name: "json", Desc: `workflow body JSON, e.g. {"title":"New Title","steps":[...]}`, Required: true},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: lark-base
 version: 1.2.0
-description: "当需要用 lark-cli 操作飞书多维表格（Base）时调用：适用于建表、字段管理、记录读写、视图配置、历史查询，以及角色/表单/仪表盘管理；也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。"
+description: "当需要用 lark-cli 操作飞书多维表格（Base）时调用：适用于建表、字段管理、记录读写、视图配置、历史查询，以及角色/表单/仪表盘管理/工作流；也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -82,19 +82,24 @@ metadata:
 
 ## Workflow 专项规则
 
-1. **执行任何 workflow 命令前，必须先读两份文档：对应的命令文档 + [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)**
-   - `+workflow-create` → 先读 [lark-base-workflow-create.md](references/lark-base-workflow-create.md) + schema
-   - `+workflow-update` → 先读 [lark-base-workflow-update.md](references/lark-base-workflow-update.md) + schema
-   - `+workflow-list` → 先读 [lark-base-workflow-list.md](references/lark-base-workflow-list.md) + schema
-   - `+workflow-get` → 先读 [lark-base-workflow-get.md](references/lark-base-workflow-get.md) + schema
-   - `+workflow-enable` → 先读 [lark-base-workflow-enable.md](references/lark-base-workflow-enable.md) + schema
-   - `+workflow-disable` → 先读 [lark-base-workflow-disable.md](references/lark-base-workflow-disable.md) + schema
-   - schema 中定义了所有 StepType 枚举、步骤结构、Trigger/Action/Branch/Loop 的 data 格式、值引用语法等
-   - 禁止凭自然语言猜测 `type` 值（如把"新增记录"猜成 `CreateTrigger`），必须从 schema 的 StepType 枚举中复制准确的类型名称
-
-2. **创建前确认依赖信息**
-   - 先通过 `+table-list` / `+field-list` 获取真实的表名、字段名
+1. **执行任何 workflow 命令前，必须先读对应的命令文档**
+   - **创建**: 先读 [workflow-create.md](references/lark-base-workflow-create.md)（它会引导你读 schema）
+   - **修改**: 先读 [workflow-update.md](references/lark-base-workflow-update.md) + [workflow-get.md](references/lark-base-workflow-get.md) 获取现有配置
+   - **查询/批量操作**: 先读 [workflow-list.md](references/lark-base-workflow-list.md)（注意场景适用性）
+   - **获取详情**: 先读 [workflow-get.md](references/lark-base-workflow-get.md)，用于获取完整 workflow 定义（含 steps 结构）
+   - **启用**: 先读 [workflow-enable.md](references/lark-base-workflow-enable.md)，启用处于 `disabled` 状态的工作流
+   - **禁用**: 先读 [workflow-disable.md](references/lark-base-workflow-disable.md)，禁用处于 `enabled` 状态的工作流
+2. **禁止凭自然语言猜测 `type` 值**
+   - 必须从 schema 的 StepType 枚举中复制准确的类型名称
+   - 如 `AddRecordTrigger` 不是 `CreateTrigger`
+3. **创建前确认依赖信息**
+   - 通过 `+table-list` / `+field-list` 获取真实的表名、字段名
    - 禁止凭自然语言猜测表名/字段名填入 workflow 配置
+4. **workflow_id 与 table_id 区分**
+   - `workflow_id` 以 `wkf` 开头，从 `+workflow-list` 或 URL 的 `?table=wkf...` 参数获取
+   - `table_id` 以 `tbl` 开头，两者在 URL 的 `?table=` 参数里都会出现，需根据前缀判断
+5. **启用/禁用为写入操作**
+   - `+workflow-enable` / `+workflow-disable` 执行前必须向用户确认 base-token 和 workflow-id
 
 ## Dashboard（仪表盘/数据看板）模块
 **当用户提到 "仪表盘、dashboard、数据看板、图表、可视化、block、组件、添加组件、创建图表" 等仪表盘相关的关键词时，必须阅读** [lark-base-dashboard.md](references/lark-base-dashboard.md) 这个指引文档，了解仪表盘模块的命令和能力后再进行后续操作。

diff --git a/skills/lark-base/references/lark-base-workflow-create.md b/skills/lark-base/references/lark-base-workflow-create.md
@@ -4,26 +4,39 @@
 
 在 Base 中创建一个新的自动化工作流。新建后状态为 `disabled`，需调用 `+workflow-enable` 才能启用。
 
+## ⚠️ 执行前必读
+
+创建工作流前请按顺序完成：
+
+1. **先读本文档**，了解 `--json` 参数格式和 `client_token` 的必填要求
+2. **阅读 [workflow-guide.md](lark-base-workflow-guide.md)**，获取 Loop、IfElseBranch、SwitchBranch 等**完整示例**
+3. **参考 [workflow-schema.md](lark-base-workflow-schema.md)**，查询具体字段定义
+4. **不需要先调用 `+workflow-list`**，创建操作不依赖现有工作流列表
+5. **按需调用 `+table-list` 和 `+field-list`** 获取表名和字段名（只在需要时调用）
+6. **若遇到单多选字段，可调用`+field-get`命令**来获取选项详情
+7. **调用命令时，请将 body 数据直接通过 --json 传入，禁止创建任何的临时文件，即禁止使用 --json @filename**
+
+**常见错误**:
+- ❌ 缺少 `client_token` → 报错: `client token is empty`
+- ❌ 猜测 StepType → 报错: `unknown step type 'CreateTrigger'`（应该是 `AddRecordTrigger`）
+- ❌ 字段引用路径错误 → 报错: `prompt references an unknown reference`
+
+> 💡 **提示**: 复杂场景（循环、分支、多步骤组合）的完整示例请直接阅读 [workflow-guide.md](lark-base-workflow-guide.md)，本文档只包含基础用法。
+
 ## 推荐命令
 
 ```bash
-# 内联 JSON（简单工作流）
 lark-cli base +workflow-create \
   --base-token BascXxxxxx \
-  --json '{"client_token":"1700000000","title":"新订单自动通知","steps":[{"id":"trigger_1","type":"AddRecordTrigger","title":"监控新订单","next":"action_1","data":{"table_name":"订单表","watched_field_name":"订单号"}},{"id":"action_1","type":"LarkMessageAction","title":"发送通知","next":null,"data":{"receiver":[{"value_type":"user","value":"ou_xxxx"}],"send_to_everyone":false,"title":[{"value_type":"text","value":"新订单提醒"}],"content":[{"value_type":"text","value":"收到新订单"}],"btn_list":[]}}]}'
-
-# 从文件读取（推荐用于复杂工作流）
-lark-cli base +workflow-create \
-  --base-token BascXxxxxx \
-  --json @workflow.json
+  --json '{"client_token":"1704067200","title":"新订单自动通知","steps":[{"id":"trigger_1","type":"AddRecordTrigger","title":"监控新订单","next":"action_1","data":{"table_name":"订单表","watched_field_name":"订单号"}},{"id":"action_1","type":"LarkMessageAction","title":"发送通知","next":null,"data":{"receiver":[{"value_type":"user","value":{"id":"ou_xxxx"}}],"send_to_everyone":false,"title":[{"value_type":"text","value":"新订单提醒"}],"content":[{"value_type":"text","value":"收到新订单"}],"btn_list":[]}}]}'
 ```
 
 ## 参数
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--base-token <token>` | 是 | 多维表格 Base Token（`Basc` 开头） |
-| `--json <body>` | 是 | 工作流 body JSON，包含 `title` 和/或 `steps`；支持 `@path/to/file.json` 从文件读取 |
+| `--json <body>` | 是 | 工作流 body JSON，包含 `title` 和 `steps` |
 
 ## 如何从链接中提取参数
 
@@ -82,12 +95,12 @@ POST /open-apis/base/v3/bases/:base_token/workflows
       "title": "发送通知",
       "next": null,
       "data": {
-        "receiver": [{ "value_type": "user", "value": "ou_xxxx" }],
+        "receiver": [{ "value_type": "user", "value": {"id": "ou_xxxx"} }],
         "send_to_everyone": false,
         "title": [{ "value_type": "text", "value": "新订单提醒" }],
         "content": [
           { "value_type": "text", "value": "收到新订单，客户：" },
-          { "value_type": "ref", "value": { "path": "$.trigger_1.客户名称" } }
+          { "value_type": "ref", "value": "$.trigger_1.fldCustomerName" }
         ],
         "btn_list": []
       }
@@ -117,7 +130,7 @@ POST /open-apis/base/v3/bases/:base_token/workflows
 {
   "ok": true,
   "data": {
-    "workflow_id": "wkfxxxxxx",
+    "workflow_id": "wkfosaYTS1V6rhjF",
     "title": "新订单自动通知",
     "status": "disabled",
     "steps": [...],
@@ -135,16 +148,25 @@ POST /open-apis/base/v3/bases/:base_token/workflows
 > 这是**写入操作** — 执行前必须向用户确认。
 
 1. 与用户确认 `--base-token` 和工作流定义（`--json` 内容）
-2. 对于复杂工作流，建议先将 JSON 写入文件，再用 `@file.json` 传入
-3. 执行命令，报告返回的 `workflow_id`（`wkf` 开头）
-4. 提示用户：新建工作流初始状态为 `disabled`，需调用 `+workflow-enable --workflow-id <返回的 workflow_id>` 才会生效
+2. 执行命令，报告返回的 `workflow_id`（`wkf` 开头）
+3. 提示用户：新建工作流初始状态为 `disabled`，需调用 `+workflow-enable --workflow-id <返回的 workflow_id>` 才会生效
 
 ## 坑点
 
-- ⚠️ **client_token 必传**：缺失会返回 `[code=800004006] client token is empty`，这不是权限问题，是 JSON body 缺字段。每次请求传唯一值即可（如 `"$(date +%s)"`）
+> ⚠️ **【重要】client_token 必传**：缺失会返回 `[code=800004006] client token is empty`，这**不是权限问题**，是 **JSON body 缺字段**。每次请求传唯一值即可（如 `"$(date +%s)"` 或 `"1743078000"`）
+
 - ⚠️ **新建后默认禁用**：`status` 固定返回 `disabled`，需要额外调用 `+workflow-enable` 才能让工作流生效；不要误报"创建成功即启用"
 - ⚠️ **steps 中 id 字段必须唯一**：每个步骤的 `id` 由调用方指定，且在工作流内必须唯一；`next` 和 `children.links[].to` 引用的 ID 必须在同一 steps 数组中存在，否则服务端返回 `[2200] Internal Error`
-- ⚠️ **@file 路径限制**：`--json @workflow.json` 会读取文件内容，复杂 workflow 强烈建议用文件而不是命令行内联。CLI 强制要求相对路径（如 `@./workflow.json`），绝对路径（包括 `/tmp/xxx` 和 `/Users/.../xxx`）会被拒绝
+- ⚠️ **字段类型校验**：设置字段值时，`value_type` 必须与字段实际类型匹配：
+   - **select 类型字段**（单选/多选/流程）：必须用 `option`，不能用 `text`
+     ```json
+     // ✅ 正确
+     { "field_name": "大区", "value": [{"value_type": "option", "value": {"name": "华东"}}] }
+     // ❌ 错误 - 会报错 valueType 'text' not allowed for fieldType '3'
+     { "field_name": "大区", "value": [{"value_type": "text", "value": "华东"}] }
+     ```
+   - **SetRecordTrigger 的 field_watch_info** 同样受此限制，select 类型字段的 value 必须用 `option`
+     常见 action 输出：`FindRecordAction` → `$.step_id.recordNum`（记录数）、`$.step_id.fieldRecords`（查找到的记录列表）；`AddRecordAction` → `$.step_id.recordId`
 - ⚠️ **权限不足**：如遇 `permission denied`，先确认当前身份（bot 或 user）是否对该 Base 有编辑权限，再检查 scope 是否已开通。参考 [lark-shared](../../lark-shared/SKILL.md) 中的权限不足处理流程
 - ⚠️ **user_id_type**：涉及用户的 `value_type: "user"` 的 value 字段传 OpenID，服务端会根据 `user_id_type`（默认 `open_id`）解析；如需传 `user_id` 格式需在 body 里显式声明 `"user_id_type": "user_id"`
 

diff --git a/skills/lark-base/references/lark-base-workflow-get.md b/skills/lark-base/references/lark-base-workflow-get.md
@@ -1,7 +1,7 @@
 # base +workflow-get
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-> **必读参考：** 获取到的 `steps` 列表的具体节点结构和各触发器/动作组件的完整配置项，请参见 [`lark-base-workflow-schema.md`](lark-base-workflow-schema.md)。
+> 💡 **按需查阅：** 如需深入理解返回的 `steps` 节点结构，可参考 [workflow-schema.md](lark-base-workflow-schema.md)。简单统计（如节点数量）无需阅读 schema。
 
 获取一个 workflow 的完整定义，包括标题、状态、所有步骤（steps）及其配置。