docs: add base workflow quick guide

shortcuts/base/base_shortcuts_test.go

@@ -607,7 +607,9 @@ func TestBaseWorkflowHelpGuidesAgents(t *testing.T) {
 				"workflow-id must start with wkf",
 				"steps may be an empty array",
 				"Use +workflow-get before +workflow-update",
-				"lark-base-workflow-schema.md",
+				"lark-base-workflow-quick.md",
+				"title checks",
+				"preserve-returned-step updates do not need it",
 			},
 		},
 		{
@@ -619,9 +621,9 @@ func TestBaseWorkflowHelpGuidesAgents(t *testing.T) {
 				"New workflows are created disabled",
 				"+table-list and +field-list",
 				"Step ids must be unique",
-				"lark-base-workflow-guide.md as the entry guide",
-				"lark-base-workflow-schema.md as the steps JSON SSOT",
-				"do not invent steps[].type/data/next/children from natural language",
+				"lark-base-workflow-quick.md first",
+				"only for needed step details",
+				"Do not invent steps[].type/data/next/children from natural language",
 			},
 		},
 		{
@@ -634,7 +636,8 @@ func TestBaseWorkflowHelpGuidesAgents(t *testing.T) {
 				"keep title/status/steps fields",
 				"workflow-id must start with wkf",
 				"Updating does not enable or disable",
-				"do not invent steps[].type/data/next/children from natural language",
+				"lark-base-workflow-quick.md first",
+				"Do not invent steps[].type/data/next/children from natural language",
 			},
 		},
 		{

shortcuts/base/workflow_create.go

@@ -19,15 +19,16 @@ 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; read lark-base-workflow-guide.md and lark-base-workflow-schema.md before constructing steps", Required: true},
+		{Name: "json", Desc: "workflow body JSON; read lark-base-workflow-quick.md first, then guide/schema only for needed step details", Required: true},
 	},
 	Tips: []string{
 		"lark-cli base +workflow-create --base-token <base_token> --json @workflow.json",
 		"client_token is required and should be unique per create request.",
 		"New workflows are created disabled; call +workflow-enable after creation when the user wants it active.",
 		"Before constructing steps, use +table-list and +field-list to confirm real table and field names.",
 		"Step ids must be unique, and every next/children link must reference an existing step id.",
-		"Use lark-base-workflow-guide.md as the entry guide and lark-base-workflow-schema.md as the steps JSON SSOT; do not invent steps[].type/data/next/children from natural language.",
+		"Use lark-base-workflow-quick.md first; read lark-base-workflow-guide.md or lark-base-workflow-schema.md only for needed step details.",
+		"Do not invent steps[].type/data/next/children from natural language.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

shortcuts/base/workflow_get.go

@@ -26,7 +26,7 @@ var BaseWorkflowGet = common.Shortcut{
 		"workflow-id must start with wkf; use +workflow-list if the ID is unknown.",
 		"steps may be an empty array; that is valid for an unconfigured workflow.",
 		"Use +workflow-get before +workflow-update, then edit the returned definition and keep fields you do not intend to change.",
-		"Read lark-base-workflow-schema.md when interpreting or reusing returned steps.",
+		"Use lark-base-workflow-quick.md to decide whether the full workflow schema is needed; title checks and preserve-returned-step updates do not need it.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

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; read lark-base-workflow-guide.md and lark-base-workflow-schema.md before replacing steps", Required: true},
+		{Name: "json", Desc: "workflow body JSON; read lark-base-workflow-quick.md first, then guide/schema only for needed step details", Required: true},
 	},
 	Tips: []string{
 		"lark-cli base +workflow-update --base-token <base_token> --workflow-id <workflow_id> --json @workflow.json",
@@ -29,7 +29,8 @@ var BaseWorkflowUpdate = common.Shortcut{
 		"workflow-id must start with wkf; do not pass a tbl table ID.",
 		"Step ids must be unique, and every next/children link must reference an existing step id.",
 		"Updating does not enable or disable a workflow; call +workflow-enable or +workflow-disable separately.",
-		"Use lark-base-workflow-guide.md as the entry guide and lark-base-workflow-schema.md as the steps JSON SSOT; do not invent steps[].type/data/next/children from natural language.",
+		"Use lark-base-workflow-quick.md first; read lark-base-workflow-guide.md or lark-base-workflow-schema.md only for needed step details.",
+		"Do not invent steps[].type/data/next/children from natural language.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

skills/lark-base/SKILL.md

@@ -65,7 +65,7 @@ metadata:
 | 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md) |
 | 其他表单管理 | `+form-list/get/detail/create/update/delete` / `+form-questions-list/delete` | `+form-detail` 读 [lark-base-form-detail.md](references/lark-base-form-detail.md)；删除前确认目标表单 |
 | 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 [lark-base-dashboard.md](references/lark-base-dashboard.md)；组件 `data_config` 读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)；读取图表计算结果用 `+dashboard-block-get-data` |
-| Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；list/get/enable/disable 只处理 workflow ID 与启停状态 |
+| Workflow | `+workflow-*` | 创建/更新先读 [lark-base-workflow-quick.md](references/lark-base-workflow-quick.md)；只查、启停、改标题并保留返回的 status/steps、或复用 `+workflow-get` 返回 steps 时不要读完整 schema；启停只用 `+workflow-enable/disable`；新增未知 step、分支、循环、引用或错误恢复再按需读 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md) |
 | 高级权限与角色 | `+advperm-*` / `+role-*` | 角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；角色 create/update 或解读完整配置再读权限 JSON SSOT [role-config.md](references/role-config.md)；系统角色不可删除；关闭高级权限会影响自定义角色 |
 
 ## Base 心智模型
@@ -123,7 +123,7 @@ metadata:
 ## Dashboard / Workflow / Role
 
 - Dashboard 的复杂点是 block 的 `data_config`，不是 list/get/create/delete 命令参数。创建或更新 block 前先读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)，组件必须串行创建；`+dashboard-arrange` 是服务端智能布局，只在用户明确要求重排/美化时执行。`+dashboard-block-get-data` 读取图表最终计算结果，不返回 block 名称、类型、布局或 `data_config`；需要元数据先用 `+dashboard-block-get`。
-- Workflow 的复杂点是 `steps` 结构。创建、更新或解释完整 workflow 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；enable/disable/list 只需确认 workflow ID、当前启停状态和用户意图。
+- Workflow 的复杂点是 `steps` 结构。创建、更新或解释完整 workflow 时先读 [lark-base-workflow-quick.md](references/lark-base-workflow-quick.md)：quick 能判断是否只需 ID/状态、是否可复用 `+workflow-get` 返回结构，以及何时才需要打开完整 guide/schema 的相关小节；enable/disable/list 不读 steps schema。
 - Role 的复杂点是权限 JSON。角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；`+role-create` 只支持自定义角色；`+role-update` 是 delta merge；角色 create/update 或解读完整配置时读权限 JSON SSOT [role-config.md](references/role-config.md)。`+role-delete` 只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
 
 ## 常见恢复
@@ -153,5 +153,5 @@ metadata:
 - [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)：视图筛选 JSON
 - [lark-base-form-detail.md](references/lark-base-form-detail.md) / [lark-base-form-submit.md](references/lark-base-form-submit.md) / [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)：表单详情、提交和复杂 JSON
 - [lark-base-dashboard.md](references/lark-base-dashboard.md) / [dashboard-block-data-config.md](references/dashboard-block-data-config.md) / [lark-base-dashboard-block-get-data.md](references/lark-base-dashboard-block-get-data.md)：仪表盘、组件配置与图表结果协议
-- [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)：workflow 入口与 steps JSON SSOT
+- [lark-base-workflow-quick.md](references/lark-base-workflow-quick.md) / [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)：workflow 高频路径、入口示例与 steps JSON SSOT
 - [lark-base-role-guide.md](references/lark-base-role-guide.md) / [role-config.md](references/role-config.md)：角色入口与权限 JSON SSOT

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

@@ -785,7 +785,7 @@
 | 3 | `At least one of filter info and ref info is required` | SetRecordAction/FindRecordAction 缺少定位条件 | 必须提供 `filter_info` 或 `ref_info` 之一 |
 | 4 | `client token is empty` | 缺少 `client_token` | 每次请求传入唯一值（时间戳或随机字符串） |
 | 5 | `valueType 'text' not allowed for fieldType '3'` | select 类型字段值格式错误 | 改用 `option` 类型 |
-| 6 | `Undefined Step Type` | 使用了不支持的 StepType | 使用 `AddRecordTrigger` 而非 `CreateRecordTrigger` |
+| 6 | `Undefined Step Type` | 使用了不支持的 StepType | 使用 `AddRecordTrigger` 而非 `CreateRecordTrigger`；没有 `DeleteRecordTrigger`，删除事件要用状态/字段变更建模 |
 | 7 | `prompt references an unknown reference from step` | 引用的 stepId 不存在 | 确保引用的 step 在同一 workflow 的 steps 数组中 |
 | 8 | `[2200] Internal Error` | 1. steps[].id 重复 2. next/children.links 引用了不存在的 step | 确保所有 step id 唯一；检查引用关系 |
 | 9 | 工作流结构不完整 | Branch/Loop 节点缺少 `children` | 仅 Branch（IfElseBranch/SwitchBranch）和 Loop 节点需要 `children`，Trigger/Action 节点无需设置 |

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

@@ -0,0 +1,109 @@
+# Workflow quick
+
+Use this as the first stop for Base workflow tasks. It decides the short path first; keep the full guide and schema as the source of truth for new step fields and read only the relevant sections when this quick path is not enough.
+
+## Route
+
+| Task | First commands | When to read more |
+|---|---|---|
+| Find a workflow by name | `+workflow-list --base-token <base> --as user --format json --jq '<filter>'` | Use `+workflow-get` only for the uniquely matched workflow you will inspect or update. |
+| Disable or enable | `+workflow-list` -> `+workflow-disable` / `+workflow-enable` | Do not read the steps schema; state changes do not modify steps. |
+| Inspect title/status/steps | `+workflow-get --workflow-id <wkf>` | Do not read schema just to report title, status, IDs, or that steps are empty. |
+| Create a workflow | `+base-block-create --type workflow --name "<title>"` -> `+workflow-update --workflow-id <wkf>` | Read schema sections only for the step types you need. |
+| Update workflow steps | `+workflow-get` -> edit returned `title/status/steps` -> `+workflow-update` | Full replacement semantics: keep fields you do not intend to change. |
+
+## Create Path
+
+Prefer the stable two-step create path:
+
+```bash
+lark-cli base +base-block-create --base-token <base_token> --as user --type workflow --name "<workflow title>"
+lark-cli base +workflow-update --base-token <base_token> --as user --workflow-id <wkf_id> --json @workflow.json
+```
+
+`+workflow-create` calls the direct workflow create API and may be blocked by platform limits in some tenants. If it returns a limited-method API error, do not retry it; create the workflow block and then update that workflow's definition.
+
+New or newly configured workflows are not automatically enabled by an update. Call `+workflow-enable` only when the user asked for an active workflow or the task clearly requires activation.
+
+## Stay In The Short Path
+
+Do not open the full guide/schema for these tasks:
+
+- list workflows, find a unique workflow ID, enable, disable, or report current status;
+- rename a workflow by changing `title` while preserving returned `status` and `steps`; use `+workflow-enable` or `+workflow-disable` for state changes;
+- update an existing workflow by editing a small part of a `+workflow-get` response and leaving existing step `type`, `data`, `next`, and `children` shapes intact;
+- create an empty named workflow block when the user did not ask to configure trigger/action steps.
+
+Open the full guide/schema only when you must construct a new step data shape, add a step type that is not already present, change branch/loop links, write ref paths, or recover a platform schema error. When reading them locally, search for the heading first and read only that narrow section.
+
+## Unsupported Trigger Boundaries
+
+- There is no native record-deleted trigger in the current workflow step schema. Do not search for or invent `DeleteRecordTrigger`, `DeletedRecordTrigger`, or `RecordDeletedTrigger`.
+- If the user asks for "record deleted" / "删除记录" to trigger a workflow, say the exact delete event is not supported by Base workflow steps. Offer a modelable alternative: set a status such as "离职/已删除" before deletion, clear a marker field, or update a boolean flag, then use `SetRecordTrigger` / `ChangeRecordTrigger`.
+- If the task must be triggered after a physical row is already deleted, stop and report the capability boundary instead of creating a misleading workflow.
+
+## Common Step Data Keys
+
+These keys are enough for common workflow shells. Read the full schema only when a required key below is not enough, a platform error asks for a specific field, or you need branch/loop/ref details.
+
+| Step type | Minimal `data` keys |
+|---|---|
+| `AddRecordTrigger` | `table_name`, `watched_field_name`, optional `trigger_control_list` and `condition_list` |
+| `TimerTrigger` | `rule` (`DAILY` / `WORKDAY` are common), `start_time` as `YYYY-MM-DD HH:mm`, optional `is_never_end` |
+| `SetRecordTrigger` | `table_name`, `field_watch_info: [{ "field_name": "<field>" }]`, optional `trigger_control_list` and `condition_list` |
+| `ChangeRecordTrigger` | `table_name`, optional `trigger_control_list` and `condition_list`; use when add-or-change should trigger |
+| `FindRecordAction` | `table_name`, `field_names`, `should_proceed_when_no_results`, and exactly one of `filter_info` or `ref_info`; read the schema/guide when constructing that locator |
+| `GenerateAiTextAction` | `prompt` as text/ref items; later steps reference the generated text as `$.<stepId>`, not a nested path |
+| `LarkMessageAction` | `receiver`, `send_to_everyone`, `content`, optional `title`, `btn_list` as `[]` when no button is needed |
+| `Delay` | `duration` in minutes, range 1-120 |
+
+## Required Checks
+
+- Extract `base_token` from the `/base/<token>` URL before running Base commands.
+- Use returned names and IDs. Do not guess table names, field names, workflow IDs, group IDs, user IDs, or receiver values.
+- Before constructing `steps`, read the real Base structure you reference: tables via `+table-list`, fields via `+field-list`, existing workflows via `+workflow-list/get`.
+- For workflow updates, `+workflow-update` replaces the full workflow definition. Start from `+workflow-get` for existing workflows and preserve unchanged `title`, `status`, and `steps`.
+- For write operations, keep using `--as user` unless the user explicitly asks for bot identity or permission recovery requires the shared auth flow.
+
+## Step Schema Pointers
+
+Only read the full schema or guide when this quick file does not contain the needed step detail.
+
+| Need | Read |
+|---|---|
+| Record deletion trigger | Do not read more for `DeleteRecordTrigger`; it is not supported. Model with status/field change before deletion, or report unsupported if exact deletion is required. |
+| Common simple flow: record/timer trigger -> message, add/update/find record, delay, or AI text action | Search headings first; read only the exact guide example or schema step data section that is missing |
+| Basic step shape, `next`, `children.links` | `lark-base-workflow-schema.md` -> WorkflowStep / StepChildren |
+| Trigger type selection | `lark-base-workflow-schema.md` -> Trigger types |
+| Message receiver/content | `lark-base-workflow-schema.md` -> LarkMessageAction |
+| AI text generation | `lark-base-workflow-schema.md` -> GenerateAiTextAction |
+| Find records, add records, update records | `lark-base-workflow-schema.md` -> Action data |
+| Timer, workday, reminder timing | `lark-base-workflow-schema.md` -> TimerTrigger / ReminderTrigger |
+| If/else, switch, loop | `lark-base-workflow-guide.md` examples plus schema branch/system sections |
+
+## Minimal Body Shape
+
+```json
+{
+  "title": "workflow title",
+  "status": "disabled",
+  "steps": [
+    {
+      "id": "step_trigger",
+      "type": "AddRecordTrigger",
+      "title": "trigger title",
+      "next": "step_action",
+      "data": {}
+    },
+    {
+      "id": "step_action",
+      "type": "LarkMessageAction",
+      "title": "action title",
+      "next": null,
+      "data": {}
+    }
+  ]
+}
+```
+
+This is only the outer shape. Fill each `data` object from the relevant schema section or an existing `+workflow-get` response; do not invent unsupported fields from natural language.

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

@@ -110,9 +110,11 @@
 | 新增记录时 | `AddRecordTrigger` |
 | 字段变为特定值时（**仅修改**） | `SetRecordTrigger` |
 | **新增或修改**都触发 | `ChangeRecordTrigger` |
+| 记录被物理删除时 | 不支持；不要使用 `DeleteRecordTrigger`，改用删除前状态/字段变更建模 |
 | 拿不准用哪个 | `ChangeRecordTrigger` |
 
 > ⚠️ `SetRecordTrigger` 仅监听修改，`ChangeRecordTrigger` 同时监听新增 + 修改。
+> ⚠️ 当前 StepType 不包含记录删除触发器。需要“删除时通知”时，先把记录标记为离职/待删除/已删除，再用 `SetRecordTrigger` 或 `ChangeRecordTrigger` 监听该字段变化；如果必须监听物理删除事件，则 Base workflow 暂不支持。
 
 ### Action 类型