diff --git a/shortcuts/base/base_shortcuts_test.go b/shortcuts/base/base_shortcuts_test.go index 9810cd7089..388949dd59 100644 --- a/shortcuts/base/base_shortcuts_test.go +++ b/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", }, }, { diff --git a/shortcuts/base/workflow_create.go b/shortcuts/base/workflow_create.go index 9bf9fe562f..11cb613ae1 100644 --- 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; 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 --json @workflow.json", @@ -27,7 +27,8 @@ var BaseWorkflowCreate = common.Shortcut{ "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")) == "" { diff --git a/shortcuts/base/workflow_get.go b/shortcuts/base/workflow_get.go index 5e5abbb17c..5e6b6c6018 100644 --- a/shortcuts/base/workflow_get.go +++ b/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")) == "" { diff --git a/shortcuts/base/workflow_update.go b/shortcuts/base/workflow_update.go index ea13a3e17a..f58562909c 100644 --- 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; 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 --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")) == "" { diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index 3399146dc9..9339f0b246 100644 --- a/skills/lark-base/SKILL.md +++ b/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 diff --git a/skills/lark-base/references/lark-base-workflow-guide.md b/skills/lark-base/references/lark-base-workflow-guide.md index fb7aa363c2..df9becf67b 100644 --- a/skills/lark-base/references/lark-base-workflow-guide.md +++ b/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 节点无需设置 | diff --git a/skills/lark-base/references/lark-base-workflow-quick.md b/skills/lark-base/references/lark-base-workflow-quick.md new file mode 100644 index 0000000000..3e5057459d --- /dev/null +++ b/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 --as user --format json --jq ''` | 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 ` | Do not read schema just to report title, status, IDs, or that steps are empty. | +| Create a workflow | `+base-block-create --type workflow --name ""` -> `+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. diff --git a/skills/lark-base/references/lark-base-workflow-schema.md b/skills/lark-base/references/lark-base-workflow-schema.md index 916f53f646..825159c2c4 100644 --- a/skills/lark-base/references/lark-base-workflow-schema.md +++ b/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 类型