@josephyan/qingflow-app-builder-mcp 0.2.0-beta.10 → 0.2.0-beta.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,13 +3,13 @@
3
3
  Install:
4
4
 
5
5
  ```bash
6
- npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.10
6
+ npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.11
7
7
  ```
8
8
 
9
9
  Run:
10
10
 
11
11
  ```bash
12
- npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.10 qingflow-app-builder-mcp
12
+ npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.11 qingflow-app-builder-mcp
13
13
  ```
14
14
 
15
15
  Environment:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@josephyan/qingflow-app-builder-mcp",
3
- "version": "0.2.0-beta.10",
3
+ "version": "0.2.0-beta.11",
4
4
  "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "qingflow-mcp"
7
- version = "0.2.0b10"
7
+ version = "0.2.0b11"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -19,9 +19,9 @@ Pick the smallest tool layer that can finish the task.
19
19
 
20
20
  - Authentication and workspace: `auth_*`, `workspace_*`
21
21
  - File upload: `file_upload_local`
22
- - Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
22
+ - Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
23
23
  - Resource plan: `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, `app_views_plan`
24
- - Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`
24
+ - Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`, `role_create`
25
25
  - Publish and verify: `app_publish_verify`
26
26
 
27
27
  Note:
@@ -34,12 +34,16 @@ Note:
34
34
  - For flow presets, map natural language to canonical values before calling MCP:
35
35
  - “默认审批/基础审批/普通审批” -> `basic_approval`
36
36
  - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
37
+ - For workflow assignees, prefer roles over explicit members:
38
+ - use `role_search` first
39
+ - use `member_search` only when the user explicitly names members or no stable role exists
40
+ - use `role_create` when the business owner wants a reusable directory role instead of hard-coded members
37
41
  - On any `VALIDATION_ERROR`, inspect `suggested_next_call` first and prefer reusing the MCP-normalized arguments over re-guessing from the original natural language.
38
42
 
39
43
  Default policy:
40
44
 
41
45
  - Creating or updating one app inside an existing package: resolve the package/app, read compact state, plan patches on the server, then apply schema/layout/flow/views patches explicitly.
42
- - Do not create a new package unless the user explicitly asks for package separation.
46
+ - If package creation looks necessary or beneficial, ask the user to confirm before calling `package_create`.
43
47
 
44
48
  ## Standard Operating Order
45
49
 
@@ -51,7 +55,7 @@ Before any business tool:
51
55
 
52
56
  For builder work:
53
57
 
54
- 1. If the user explicitly wants a new package, create it first with `package_create`. Otherwise resolve the target package with `package_resolve`; if resolution is ambiguous or you need a read-only fallback, use `package_list`.
58
+ 1. Resolve the target package with `package_resolve`; if resolution is ambiguous or you need a read-only fallback, use `package_list`. If you believe a new package should be created, ask the user to confirm before calling `package_create`.
55
59
  2. Resolve the target app with `app_resolve` if the request is an update.
56
60
  3. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`.
57
61
  4. Use `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, or `app_views_plan` before any non-trivial write.
@@ -59,7 +63,7 @@ For builder work:
59
63
  6. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
60
64
  7. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default.
61
65
  8. Use `app_flow_apply` after schema exists. It publishes by default.
62
- 9. Use `app_views_apply` when the user wants explicit list/card/board views. It publishes by default.
66
+ 9. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default.
63
67
  10. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
64
68
  11. If a write fails with `APP_EDIT_LOCKED`, stop normal writes. Only use `app_release_edit_lock_if_mine` when the failed result shows the lock owner is the current logged-in user.
65
69
 
@@ -74,10 +78,16 @@ For flow work, keep the order strict:
74
78
 
75
79
  1. `app_read_fields`
76
80
  2. `app_read_flow_summary`
77
- 3. Start from a canonical preset when possible
78
- 4. Use patch-style edits to that skeleton instead of freehand full-graph generation
79
- 5. `app_flow_plan`
80
- 6. `app_flow_apply`
81
+ 3. `role_search` or `member_search` if assignees need to come from the directory
82
+ 4. `role_create` if the user wants a reusable role and no suitable role exists yet
83
+ 5. Start from a canonical preset when possible
84
+ 6. Use patch-style edits to that skeleton instead of freehand full-graph generation
85
+ 7. Declare approver/fill/copy assignees explicitly:
86
+ - prefer `assignees.role_names`
87
+ - support `assignees.member_names` / `assignees.member_emails` / `assignees.member_uids`
88
+ 8. When a node must edit specific fields, declare `permissions.editable_fields`
89
+ 9. `app_flow_plan`
90
+ 10. `app_flow_apply`
81
91
 
82
92
  In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
83
93
 
@@ -97,6 +107,12 @@ For additive work on existing systems:
97
107
  - For flexible workflow requests, split the work into two steps:
98
108
  1. create a base skeleton with a preset
99
109
  2. apply explicit business-specific changes as patchable nodes/transitions
110
+ - Approval, fill, and copy nodes must declare at least one assignee. Treat this as a hard requirement, not an optional detail.
111
+ - For workflow nodes, use the canonical public shape:
112
+ - `assignees.role_names`
113
+ - `assignees.member_names`
114
+ - `permissions.editable_fields`
115
+ - Do not guess role ids or member ids. Resolve them from the directory first.
100
116
  - `app_schema_apply` does not treat package attachment as success criteria; if package ownership matters, verify `tag_ids_after` and call `package_attach_app` explicitly.
101
117
  - `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
102
118
  - `relation` and `subtable` must be explicit; do not infer them from vague natural language.
@@ -131,6 +147,9 @@ For additive work on existing systems:
131
147
  - Plan layout patch: `app_layout_plan`
132
148
  - Plan workflow patch: `app_flow_plan`
133
149
  - Plan view patch: `app_views_plan`
150
+ - Search members for workflow assignees: `member_search`
151
+ - Search roles for workflow assignees: `role_search`
152
+ - Create reusable workflow role: `role_create`
134
153
  - Add/update/remove fields: `app_schema_apply`
135
154
  - Merge or replace layout: `app_layout_apply`
136
155
  - Replace workflow: `app_flow_apply`
@@ -148,5 +167,6 @@ Detailed playbooks:
148
167
  - Update fields only: [references/update-schema.md](references/update-schema.md)
149
168
  - Update layout only: [references/update-layout.md](references/update-layout.md)
150
169
  - Update workflow only: [references/update-flow.md](references/update-flow.md)
170
+ - Workflow assignees and node permissions: [references/flow-actors-and-permissions.md](references/flow-actors-and-permissions.md)
151
171
  - Update views only: [references/update-views.md](references/update-views.md)
152
172
  - Standard end-to-end builder sequences: [references/solution-playbooks.md](references/solution-playbooks.md)
@@ -2,7 +2,7 @@
2
2
 
3
3
  Use this when the user wants one new app inside an existing package.
4
4
 
5
- If the user explicitly wants a brand new package first, call `package_create` before this sequence.
5
+ If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, call `package_create` before this sequence.
6
6
 
7
7
  ## Minimal sequence
8
8
 
@@ -15,7 +15,7 @@ If the user explicitly wants a brand new package first, call `package_create` be
15
15
 
16
16
  ## Example
17
17
 
18
- Create a new package only when the user asked for package separation:
18
+ Create a new package only after the user confirms package creation:
19
19
 
20
20
  ```json
21
21
  {
@@ -43,7 +43,7 @@ Builder behavior in prod:
43
43
  - always identify the target package or app set before changing anything
44
44
  - default to `preflight` or `plan` before any `apply`
45
45
  - additive requirements should modify the existing package with ordinary tools by default
46
- - do not create a new package unless the user explicitly wants package separation
46
+ - if creating a new package seems necessary in prod, ask the user to confirm package creation first
47
47
  - do not seed mock data unless the user explicitly approves it for production
48
48
  - verify is mandatory after writes
49
49
 
@@ -0,0 +1,124 @@
1
+ # Flow Actors And Permissions
2
+
3
+ Use this when the workflow needs real assignees or node-level editable field permissions.
4
+
5
+ ## Canonical policy
6
+
7
+ - Approval, fill, and copy nodes must declare at least one assignee.
8
+ - Prefer roles over explicit members.
9
+ - Resolve directory actors before calling `app_flow_plan` or `app_flow_apply`.
10
+ - Use canonical keys only:
11
+ - `assignees.role_names`
12
+ - `assignees.role_ids`
13
+ - `assignees.member_names`
14
+ - `assignees.member_emails`
15
+ - `assignees.member_uids`
16
+ - `permissions.editable_fields`
17
+
18
+ ## Recommended order
19
+
20
+ 1. `app_read_fields`
21
+ 2. `app_read_flow_summary`
22
+ 3. `role_search`
23
+ 4. `member_search` when the user explicitly names people
24
+ 5. `role_create` when no reusable role exists and the user wants role-based routing
25
+ 6. `app_flow_plan`
26
+ 7. `app_flow_apply`
27
+
28
+ ## Examples
29
+
30
+ ### Route an approval node to a reusable role
31
+
32
+ ```json
33
+ {
34
+ "tool_name": "app_flow_plan",
35
+ "arguments": {
36
+ "profile": "default",
37
+ "app_key": "APP_123",
38
+ "preset": "basic_approval",
39
+ "nodes": [
40
+ {
41
+ "id": "approve_1",
42
+ "type": "approve",
43
+ "name": "部门审批",
44
+ "assignees": {
45
+ "role_names": ["项目经理"]
46
+ }
47
+ }
48
+ ]
49
+ }
50
+ }
51
+ ```
52
+
53
+ ### Route to explicit members when the user names people
54
+
55
+ ```json
56
+ {
57
+ "tool_name": "app_flow_plan",
58
+ "arguments": {
59
+ "profile": "default",
60
+ "app_key": "APP_123",
61
+ "preset": "basic_approval",
62
+ "nodes": [
63
+ {
64
+ "id": "approve_1",
65
+ "type": "approve",
66
+ "name": "部门审批",
67
+ "assignees": {
68
+ "member_names": ["严琪东", "张三"]
69
+ }
70
+ }
71
+ ]
72
+ }
73
+ }
74
+ ```
75
+
76
+ ### Let one node edit selected fields only
77
+
78
+ ```json
79
+ {
80
+ "tool_name": "app_flow_apply",
81
+ "arguments": {
82
+ "profile": "default",
83
+ "app_key": "APP_123",
84
+ "mode": "replace",
85
+ "publish": true,
86
+ "nodes": [
87
+ {"id": "start", "type": "start", "name": "发起"},
88
+ {
89
+ "id": "approve_1",
90
+ "type": "approve",
91
+ "name": "部门审批",
92
+ "assignees": {
93
+ "role_names": ["项目经理"]
94
+ },
95
+ "permissions": {
96
+ "editable_fields": ["状态", "审批意见", "项目负责人"]
97
+ }
98
+ },
99
+ {"id": "end", "type": "end", "name": "结束"}
100
+ ],
101
+ "transitions": [
102
+ {"from": "start", "to": "approve_1"},
103
+ {"from": "approve_1", "to": "end"}
104
+ ]
105
+ }
106
+ }
107
+ ```
108
+
109
+ ## Common recovery
110
+
111
+ ### `ROLE_NOT_FOUND` / `AMBIGUOUS_ROLE`
112
+
113
+ - retry with `role_search`
114
+ - if the business wants a reusable route and no exact role exists, create one with `role_create`
115
+
116
+ ### `MEMBER_NOT_FOUND` / `AMBIGUOUS_MEMBER`
117
+
118
+ - retry with `member_search`
119
+ - do not guess user ids
120
+
121
+ ### `UNKNOWN_FLOW_FIELD`
122
+
123
+ - reread fields with `app_read_fields`
124
+ - only pass real current field names to `permissions.editable_fields`
@@ -28,6 +28,10 @@
28
28
  ## Workflow dependencies
29
29
 
30
30
  - Approval-style flows usually require an explicit status field
31
+ - Approval, fill, and copy nodes also require at least one assignee
32
+ - Prefer roles over explicit members unless the user explicitly names people
33
+ - Resolve assignees with `role_search` / `member_search` before flow apply
34
+ - Use `permissions.editable_fields` for node-level editable field permissions; do not guess field ids
31
35
  - If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
32
36
  - Do not switch to hidden `solution_*` tools from public builder flows
33
37
 
@@ -30,10 +30,13 @@ Prefer `mode=merge`. Use `mode=replace` only when every field placement is inten
30
30
 
31
31
  1. `app_read_fields`
32
32
  2. `app_read_flow_summary`
33
- 3. `app_flow_plan`
34
- 4. `app_flow_apply`
33
+ 3. `role_search` or `member_search`
34
+ 4. `role_create` if the business wants a reusable role and no good exact role exists
35
+ 5. `app_flow_plan`
36
+ 6. `app_flow_apply`
35
37
 
36
38
  If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
39
+ If it reports `FLOW_ASSIGNEE_REQUIRED`, resolve roles or members first and retry with canonical `assignees.*`.
37
40
 
38
41
  ## Add or update views
39
42
 
@@ -10,9 +10,12 @@ Use `plan` before `apply` unless the patch is trivial and already normalized.
10
10
 
11
11
  ## Resolve
12
12
 
13
- - `package_create`: create a new package only when the user explicitly asked for one; exact-name duplicates return `noop=true`
13
+ - `package_create`: create a new package only after the user confirms package creation; exact-name duplicates return `noop=true`
14
14
  - `package_resolve`: exact package lookup by name
15
15
  - `package_list`: read-only fallback when package resolution is ambiguous
16
+ - `member_search`: resolve named people from the directory
17
+ - `role_search`: resolve reusable roles from the directory
18
+ - `role_create`: create a reusable role when the business owner wants role-based routing
16
19
  - `app_resolve`: locate an existing app by `app_key` or `app_name`
17
20
 
18
21
  ## Summary reads
@@ -59,7 +62,7 @@ These execute normalized patches and publish by default unless `publish=false`.
59
62
  - Tidy layout:
60
63
  `app_read_layout_summary -> app_layout_plan -> app_layout_apply`
61
64
  - Add workflow:
62
- `app_read_fields -> app_read_flow_summary -> app_flow_plan -> app_flow_apply`
65
+ `app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply`
63
66
  - Add views:
64
67
  `app_read_fields -> app_read_views_summary -> app_views_plan -> app_views_apply`
65
68
 
@@ -67,7 +70,9 @@ These execute normalized patches and publish by default unless `publish=false`.
67
70
 
68
71
  - Do not handcraft raw Qingflow schema payloads
69
72
  - Do not rely on internal `solution_*` tools in public builder flows
70
- - Do not create a new package unless the user explicitly asks for package separation
73
+ - Do not create a new package without first asking the user to confirm package creation
71
74
  - Do not skip summary reads before flow or view work
72
75
  - Do not emit `column_names`; always use `columns`
73
76
  - Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
77
+ - Do not omit assignees on approval/fill/copy nodes
78
+ - Do not guess role ids, member ids, or editable field ids; resolve names first
@@ -6,9 +6,12 @@ Use this when the app already exists and the task is only about workflow.
6
6
 
7
7
  1. `app_read_fields`
8
8
  2. `app_read_flow_summary`
9
- 3. start from a canonical preset when possible
10
- 4. `app_flow_plan`
11
- 5. `app_flow_apply`
9
+ 3. `role_search` or `member_search`
10
+ 4. `role_create` if the user wants a reusable directory role and no good role exists
11
+ 5. start from a canonical preset when possible
12
+ 6. patch the skeleton instead of freehanding a full graph
13
+ 7. `app_flow_plan`
14
+ 8. `app_flow_apply`
12
15
 
13
16
  If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
14
17
 
@@ -19,7 +22,7 @@ Canonical preset mapping:
19
22
  - “默认审批/基础审批/普通审批” -> `basic_approval`
20
23
  - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
21
24
 
22
- Plan a simple approval flow:
25
+ Plan a simple approval flow with a role assignee and node-level editable fields:
23
26
 
24
27
  ```json
25
28
  {
@@ -27,7 +30,20 @@ Plan a simple approval flow:
27
30
  "arguments": {
28
31
  "profile": "default",
29
32
  "app_key": "APP_123",
30
- "preset": "basic_approval"
33
+ "preset": "basic_approval",
34
+ "nodes": [
35
+ {
36
+ "id": "approve_1",
37
+ "type": "approve",
38
+ "name": "部门审批",
39
+ "assignees": {
40
+ "role_names": ["项目经理"]
41
+ },
42
+ "permissions": {
43
+ "editable_fields": ["状态", "审批意见"]
44
+ }
45
+ }
46
+ ]
31
47
  }
32
48
  }
33
49
  ```
@@ -38,31 +54,107 @@ For flexible business requirements, do not jump straight to a full custom graph.
38
54
  2. identify the business-specific changes
39
55
  3. patch nodes/transitions explicitly
40
56
 
41
- Only after that should you use explicit nodes:
57
+ For branch flows, keep the public shape canonical:
58
+
59
+ 1. add a `branch` node
60
+ 2. add one or more `condition` nodes as branch lanes
61
+ 3. put filter rules on the `condition` nodes with `conditions` or `condition_groups`
62
+ 4. use an empty `condition` node as the default branch when needed
63
+
64
+ Canonical branch example:
42
65
 
43
66
  ```json
44
67
  {
45
- "tool_name": "app_flow_apply",
68
+ "tool_name": "app_flow_plan",
46
69
  "arguments": {
47
70
  "profile": "default",
48
71
  "app_key": "APP_123",
49
72
  "mode": "replace",
50
- "publish": true,
51
73
  "nodes": [
52
74
  {"id": "start", "type": "start", "name": "发起"},
53
- {"id": "approve_1", "type": "approve", "name": "审批"},
75
+ {"id": "route", "type": "branch", "name": "金额分支"},
76
+ {
77
+ "id": "high_amount",
78
+ "type": "condition",
79
+ "name": "金额大于等于一万",
80
+ "conditions": [
81
+ {"field_name": "预计金额", "operator": "gte", "value": 10000}
82
+ ]
83
+ },
84
+ {
85
+ "id": "approve_finance",
86
+ "type": "approve",
87
+ "name": "财务审批",
88
+ "assignees": {"role_names": ["财务负责人"]}
89
+ },
90
+ {"id": "default_lane", "type": "condition", "name": "其他情况"},
91
+ {
92
+ "id": "approve_manager",
93
+ "type": "approve",
94
+ "name": "部门审批",
95
+ "assignees": {"role_names": ["项目经理"]}
96
+ },
54
97
  {"id": "end", "type": "end", "name": "结束"}
55
98
  ],
56
99
  "transitions": [
57
- {"from": "start", "to": "approve_1"},
58
- {"from": "approve_1", "to": "end"}
100
+ {"from": "start", "to": "route"},
101
+ {"from": "route", "to": "high_amount"},
102
+ {"from": "high_amount", "to": "approve_finance"},
103
+ {"from": "route", "to": "default_lane"},
104
+ {"from": "default_lane", "to": "approve_manager"},
105
+ {"from": "approve_finance", "to": "end"},
106
+ {"from": "approve_manager", "to": "end"}
59
107
  ]
60
108
  }
61
109
  }
62
110
  ```
63
111
 
112
+ Only after that should you use explicit nodes:
113
+
114
+ ```json
115
+ {
116
+ "tool_name": "app_flow_apply",
117
+ "arguments": {
118
+ "profile": "default",
119
+ "app_key": "APP_123",
120
+ "mode": "replace",
121
+ "publish": true,
122
+ "nodes": [
123
+ {"id": "start", "type": "start", "name": "发起"},
124
+ {
125
+ "id": "approve_1",
126
+ "type": "approve",
127
+ "name": "部门审批",
128
+ "assignees": {
129
+ "role_names": ["项目经理"]
130
+ },
131
+ "permissions": {
132
+ "editable_fields": ["状态", "审批意见"]
133
+ }
134
+ },
135
+ {"id": "end", "type": "end", "name": "结束"}
136
+ ],
137
+ "transitions": [
138
+ {"from": "start", "to": "approve_1"},
139
+ {"from": "approve_1", "to": "end"}
140
+ ]
141
+ }
142
+ }
143
+ ```
144
+
64
145
  ## Common failures
65
146
 
147
+ ### `FLOW_ASSIGNEE_REQUIRED`
148
+
149
+ Approval, fill, and copy nodes must declare at least one assignee.
150
+
151
+ Preferred fix order:
152
+
153
+ 1. `role_search`
154
+ 2. `member_search` only if the user explicitly named members
155
+ 3. `role_create` if the business needs a reusable role
156
+ 4. retry `app_flow_plan` or `app_flow_apply` with canonical `assignees.*`
157
+
66
158
  ### `FLOW_DEPENDENCY_MISSING`
67
159
 
68
160
  The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
@@ -71,6 +163,15 @@ The workflow depends on fields that do not exist yet, usually `status`. Fix sche
71
163
 
72
164
  One or more transitions reference unknown nodes or create an invalid graph.
73
165
 
166
+ ### `UNKNOWN_FLOW_FIELD`
167
+
168
+ The workflow referenced a field name that does not exist, often in:
169
+
170
+ - `permissions.editable_fields`
171
+ - branch `conditions`
172
+
173
+ Call `app_read_fields` and retry with the exact field names returned by the app.
174
+
74
175
  ### `STATUS_FIELD_REQUIRED`
75
176
 
76
177
  The app has no explicit status field recognized by the internal workflow compiler. Add one with `app_schema_apply`, then retry.
@@ -87,11 +188,17 @@ Do not keep guessing preset names or node shapes. First:
87
188
  2. reuse `canonical_arguments` if present
88
189
  3. check `allowed_values`
89
190
  4. retry with canonical preset or canonical node types
191
+ 5. for workflow actors and permissions, always convert to:
192
+ - `assignees.role_names`
193
+ - `assignees.member_names`
194
+ - `permissions.editable_fields`
90
195
 
91
196
  ## Notes
92
197
 
93
198
  - `mode=replace` is the only supported flow apply mode
94
199
  - `app_flow_apply` publishes by default
200
+ - Prefer roles over explicit members unless the user explicitly asks for named members
201
+ - `basic_approval` and `basic_fill_then_approve` are skeletons, not complete business workflows
95
202
  - Report results precisely:
96
203
  - “基础流程骨架已创建” when only the preset landed
97
204
  - “业务定制规则已补齐” only after the patch phase is complete
@@ -1,6 +1,6 @@
1
1
  # Update Views
2
2
 
3
- Use this when the task is only about list, card, or board views.
3
+ Use this when the task is only about table, card, board, or gantt views.
4
4
 
5
5
  ## Minimal sequence
6
6
 
@@ -18,6 +18,8 @@ Canonical rules before any example:
18
18
  - Always use `columns`
19
19
  - Do not emit `column_names`
20
20
  - Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
21
+ - Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
22
+ - For gantt, use `start_field`, `end_field`, and optionally `title_field`
21
23
 
22
24
  Plan a default table view:
23
25
 
@@ -81,6 +83,36 @@ Board example:
81
83
  }
82
84
  ```
83
85
 
86
+ Gantt example with filters:
87
+
88
+ ```json
89
+ {
90
+ "tool_name": "app_views_apply",
91
+ "arguments": {
92
+ "profile": "default",
93
+ "app_key": "APP_123",
94
+ "upsert_views": [
95
+ {
96
+ "name": "项目甘特图",
97
+ "type": "gantt",
98
+ "columns": ["项目名称", "开始日期", "结束日期", "状态"],
99
+ "start_field": "开始日期",
100
+ "end_field": "结束日期",
101
+ "title_field": "项目名称",
102
+ "filters": [
103
+ {
104
+ "field_name": "状态",
105
+ "operator": "eq",
106
+ "value": "进行中"
107
+ }
108
+ ]
109
+ }
110
+ ],
111
+ "remove_views": []
112
+ }
113
+ }
114
+ ```
115
+
84
116
  ## Common failures
85
117
 
86
118
  ### `UNKNOWN_VIEW_FIELD`
@@ -89,7 +121,7 @@ At least one `columns` or `group_by` field name does not exist.
89
121
 
90
122
  ### `INVALID_VIEW_TYPE`
91
123
 
92
- Public view types are only `table`, `card`, `board`.
124
+ Public view types are only `table`, `card`, `board`, `gantt`.
93
125
 
94
126
  Map old or intuitive labels before calling the tool:
95
127
 
@@ -97,6 +129,15 @@ Map old or intuitive labels before calling the tool:
97
129
  - `cardView` -> `card`
98
130
  - `kanban` -> `board`
99
131
 
132
+ ### `INVALID_GANTT_CONFIG`
133
+
134
+ Gantt views require at least:
135
+
136
+ - `start_field`
137
+ - `end_field`
138
+
139
+ Also make sure these field names already exist on the app.
140
+
100
141
  ### `VIEW_APPLY_FAILED`
101
142
 
102
143
  The backend rejected the normalized view payload. Re-read fields and inspect `request_id` before retrying.
@@ -111,4 +152,6 @@ Do not repeat `app_views_apply` with guessed keys. First:
111
152
  ## Notes
112
153
 
113
154
  - `fields` is accepted as an alias for `columns`, but skill examples should still use `columns`
155
+ - `column_names` should not appear in skill examples
156
+ - `filters` are ANDed together as one flat condition group
114
157
  - `app_views_apply` publishes by default
@@ -2,4 +2,4 @@ from __future__ import annotations
2
2
 
3
3
  __all__ = ["__version__"]
4
4
 
5
- __version__ = "0.2.0b10"
5
+ __version__ = "0.2.0b11"