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

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.10
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.12
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.10 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.12 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.12",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b10"
+version = "0.2.0b12"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-builder/SKILL.md

@@ -19,9 +19,9 @@ Pick the smallest tool layer that can finish the task.
 
 - Authentication and workspace: `auth_*`, `workspace_*`
 - File upload: `file_upload_local`
-- 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`
+- 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`
 - Resource plan: `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, `app_views_plan`
-- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`
+- 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`
 - Publish and verify: `app_publish_verify`
 
 Note:
@@ -34,12 +34,17 @@ Note:
 - For flow presets, map natural language to canonical values before calling MCP:
   - “默认审批/基础审批/普通审批” -> `basic_approval`
   - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
+- For first-time flow or view work in a session, read `builder_tool_contract` before planning so keys, aliases, presets, and minimal examples come from MCP instead of memory.
+- For workflow assignees, prefer roles over explicit members:
+  - use `role_search` first
+  - use `member_search` only when the user explicitly names members or no stable role exists
+  - use `role_create` when the business owner wants a reusable directory role instead of hard-coded members
 - On any `VALIDATION_ERROR`, inspect `suggested_next_call` first and prefer reusing the MCP-normalized arguments over re-guessing from the original natural language.
 
 Default policy:
 
 - 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.
-- Do not create a new package unless the user explicitly asks for package separation.
+- If package creation looks necessary or beneficial, ask the user to confirm before calling `package_create`.
 
 ## Standard Operating Order
 
@@ -51,7 +56,7 @@ Before any business tool:
 
 For builder work:
 
-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`.
+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`.
 2. Resolve the target app with `app_resolve` if the request is an update.
 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`.
 4. Use `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, or `app_views_plan` before any non-trivial write.
@@ -59,25 +64,35 @@ For builder work:
 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`.
 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.
 8. Use `app_flow_apply` after schema exists. It publishes by default.
-9. Use `app_views_apply` when the user wants explicit list/card/board views. It publishes by default.
+9. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default.
 10. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
 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.
 
 For view work, keep the order strict:
 
-1. `app_read_fields`
-2. `app_read_views_summary`
-3. `app_views_plan`
-4. `app_views_apply`
+1. `builder_tool_contract`
+2. `app_read_fields`
+3. `app_read_views_summary`
+4. `app_views_plan`
+5. `app_views_apply`
+6. `app_read_views_summary` again whenever `app_views_apply` returns `failed` or `partial_success`
 
 For flow work, keep the order strict:
 
-1. `app_read_fields`
-2. `app_read_flow_summary`
-3. Start from a canonical preset when possible
-4. Use patch-style edits to that skeleton instead of freehand full-graph generation
-5. `app_flow_plan`
-6. `app_flow_apply`
+1. `builder_tool_contract`
+2. `app_read_fields`
+3. `app_read_flow_summary`
+4. `role_search` or `member_search` if assignees need to come from the directory
+5. `role_create` if the user wants a reusable role and no suitable role exists yet
+6. Start from a canonical preset when possible
+7. Use patch-style edits to that skeleton instead of freehand full-graph generation
+8. Declare approver/fill/copy assignees explicitly:
+   - prefer `assignees.role_names`
+   - support `assignees.member_names` / `assignees.member_emails` / `assignees.member_uids`
+9. When a node must edit specific fields, declare `permissions.editable_fields`
+10. `app_flow_plan`
+11. `app_flow_apply`
+12. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
 
 In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
 
@@ -97,6 +112,14 @@ For additive work on existing systems:
 - For flexible workflow requests, split the work into two steps:
   1. create a base skeleton with a preset
   2. apply explicit business-specific changes as patchable nodes/transitions
+- Approval, fill, and copy nodes must declare at least one assignee. Treat this as a hard requirement, not an optional detail.
+- For workflow nodes, use the canonical public shape:
+  - `assignees.role_names`
+  - `assignees.member_names`
+  - `permissions.editable_fields`
+- Reuse `app_flow_plan` output directly when it succeeds. Do not rewrite it into internal keys such as `role_entries` or `editable_que_ids`.
+- Reuse `app_views_plan` output directly when it succeeds. Do not re-expand aliases such as `column_names`.
+- Do not guess role ids or member ids. Resolve them from the directory first.
 - `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.
 - `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
 - `relation` and `subtable` must be explicit; do not infer them from vague natural language.
@@ -109,7 +132,11 @@ For additive work on existing systems:
 - `app_publish_verify` is the publish source of truth.
 - If readback mismatches the UI, compare `request_route` and do not assume the builder hit the same `qf_version` as the browser
 - Treat post-write readback as the source of truth, not just write status codes
+- For views, a top-level `VIEW_APPLY_FAILED` does not prove all requested views failed. Read back the view list and verify which views actually landed.
 - In final user-facing summaries, distinguish clearly between:
+  - contract is visible / canonical shape is known
+  - plan succeeded
+  - apply landed and readback verified it
   - base template/skeleton applied
   - business-specific rules completed
   - remaining gaps or follow-up patches
@@ -131,6 +158,9 @@ For additive work on existing systems:
 - Plan layout patch: `app_layout_plan`
 - Plan workflow patch: `app_flow_plan`
 - Plan view patch: `app_views_plan`
+- Search members for workflow assignees: `member_search`
+- Search roles for workflow assignees: `role_search`
+- Create reusable workflow role: `role_create`
 - Add/update/remove fields: `app_schema_apply`
 - Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
@@ -148,5 +178,6 @@ Detailed playbooks:
 - Update fields only: [references/update-schema.md](references/update-schema.md)
 - Update layout only: [references/update-layout.md](references/update-layout.md)
 - Update workflow only: [references/update-flow.md](references/update-flow.md)
+- Workflow assignees and node permissions: [references/flow-actors-and-permissions.md](references/flow-actors-and-permissions.md)
 - Update views only: [references/update-views.md](references/update-views.md)
 - Standard end-to-end builder sequences: [references/solution-playbooks.md](references/solution-playbooks.md)

package/skills/qingflow-app-builder/references/create-app.md

@@ -2,7 +2,7 @@
 
 Use this when the user wants one new app inside an existing package.
 
-If the user explicitly wants a brand new package first, call `package_create` before this sequence.
+If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, call `package_create` before this sequence.
 
 ## Minimal sequence
 
@@ -15,7 +15,7 @@ If the user explicitly wants a brand new package first, call `package_create` be
 
 ## Example
 
-Create a new package only when the user asked for package separation:
+Create a new package only after the user confirms package creation:
 
 ```json
 {

package/skills/qingflow-app-builder/references/environments.md

@@ -43,7 +43,7 @@ Builder behavior in prod:
 - always identify the target package or app set before changing anything
 - default to `preflight` or `plan` before any `apply`
 - additive requirements should modify the existing package with ordinary tools by default
-- do not create a new package unless the user explicitly wants package separation
+- if creating a new package seems necessary in prod, ask the user to confirm package creation first
 - do not seed mock data unless the user explicitly approves it for production
 - verify is mandatory after writes
 

package/skills/qingflow-app-builder/references/flow-actors-and-permissions.md

@@ -0,0 +1,124 @@
+# Flow Actors And Permissions
+
+Use this when the workflow needs real assignees or node-level editable field permissions.
+
+## Canonical policy
+
+- Approval, fill, and copy nodes must declare at least one assignee.
+- Prefer roles over explicit members.
+- Resolve directory actors before calling `app_flow_plan` or `app_flow_apply`.
+- Use canonical keys only:
+  - `assignees.role_names`
+  - `assignees.role_ids`
+  - `assignees.member_names`
+  - `assignees.member_emails`
+  - `assignees.member_uids`
+  - `permissions.editable_fields`
+
+## Recommended order
+
+1. `app_read_fields`
+2. `app_read_flow_summary`
+3. `role_search`
+4. `member_search` when the user explicitly names people
+5. `role_create` when no reusable role exists and the user wants role-based routing
+6. `app_flow_plan`
+7. `app_flow_apply`
+
+## Examples
+
+### Route an approval node to a reusable role
+
+```json
+{
+  "tool_name": "app_flow_plan",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "preset": "basic_approval",
+    "nodes": [
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {
+          "role_names": ["项目经理"]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Route to explicit members when the user names people
+
+```json
+{
+  "tool_name": "app_flow_plan",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "preset": "basic_approval",
+    "nodes": [
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {
+          "member_names": ["严琪东", "张三"]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Let one node edit selected fields only
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "mode": "replace",
+    "publish": true,
+    "nodes": [
+      {"id": "start", "type": "start", "name": "发起"},
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {
+          "role_names": ["项目经理"]
+        },
+        "permissions": {
+          "editable_fields": ["状态", "审批意见", "项目负责人"]
+        }
+      },
+      {"id": "end", "type": "end", "name": "结束"}
+    ],
+    "transitions": [
+      {"from": "start", "to": "approve_1"},
+      {"from": "approve_1", "to": "end"}
+    ]
+  }
+}
+```
+
+## Common recovery
+
+### `ROLE_NOT_FOUND` / `AMBIGUOUS_ROLE`
+
+- retry with `role_search`
+- if the business wants a reusable route and no exact role exists, create one with `role_create`
+
+### `MEMBER_NOT_FOUND` / `AMBIGUOUS_MEMBER`
+
+- retry with `member_search`
+- do not guess user ids
+
+### `UNKNOWN_FLOW_FIELD`
+
+- reread fields with `app_read_fields`
+- only pass real current field names to `permissions.editable_fields`

package/skills/qingflow-app-builder/references/gotchas.md

@@ -28,6 +28,10 @@
 ## Workflow dependencies
 
 - Approval-style flows usually require an explicit status field
+- Approval, fill, and copy nodes also require at least one assignee
+- Prefer roles over explicit members unless the user explicitly names people
+- Resolve assignees with `role_search` / `member_search` before flow apply
+- Use `permissions.editable_fields` for node-level editable field permissions; do not guess field ids
 - If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
 - Do not switch to hidden `solution_*` tools from public builder flows
 
@@ -37,6 +41,10 @@
 - Do not repeat create steps after `app_key` already exists
 - For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
 - For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
+- For flow work, do not replay internal keys from old logs or plan outputs. Public builder calls should stay on:
+  - `assignees.role_ids` / `assignees.member_uids` / `assignees.member_emails`
+  - `permissions.editable_fields`
+- For view work, treat `columns` as the only canonical public key. `app_read_views_summary` and `app_views_plan/apply` should all be read and written in that shape.
 - If a view or flow write fails, report the smallest next action:
   - wrong key -> switch to canonical key
   - unsupported preset -> switch to allowed canonical preset

package/skills/qingflow-app-builder/references/solution-playbooks.md

@@ -30,10 +30,13 @@ Prefer `mode=merge`. Use `mode=replace` only when every field placement is inten
 
 1. `app_read_fields`
 2. `app_read_flow_summary`
-3. `app_flow_plan`
-4. `app_flow_apply`
+3. `role_search` or `member_search`
+4. `role_create` if the business wants a reusable role and no good exact role exists
+5. `app_flow_plan`
+6. `app_flow_apply`
 
 If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
+If it reports `FLOW_ASSIGNEE_REQUIRED`, resolve roles or members first and retry with canonical `assignees.*`.
 
 ## Add or update views
 

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -10,9 +10,12 @@ Use `plan` before `apply` unless the patch is trivial and already normalized.
 
 ## Resolve
 
-- `package_create`: create a new package only when the user explicitly asked for one; exact-name duplicates return `noop=true`
+- `package_create`: create a new package only after the user confirms package creation; exact-name duplicates return `noop=true`
 - `package_resolve`: exact package lookup by name
 - `package_list`: read-only fallback when package resolution is ambiguous
+- `member_search`: resolve named people from the directory
+- `role_search`: resolve reusable roles from the directory
+- `role_create`: create a reusable role when the business owner wants role-based routing
 - `app_resolve`: locate an existing app by `app_key` or `app_name`
 
 ## Summary reads
@@ -59,15 +62,18 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Tidy layout:
   `app_read_layout_summary -> app_layout_plan -> app_layout_apply`
 - Add workflow:
-  `app_read_fields -> app_read_flow_summary -> app_flow_plan -> app_flow_apply`
+  `builder_tool_contract -> app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply -> app_read_flow_summary`
 - Add views:
-  `app_read_fields -> app_read_views_summary -> app_views_plan -> app_views_apply`
+  `builder_tool_contract -> app_read_fields -> app_read_views_summary -> app_views_plan -> app_views_apply -> app_read_views_summary`
 
 ## Avoid
 
 - Do not handcraft raw Qingflow schema payloads
 - Do not rely on internal `solution_*` tools in public builder flows
-- Do not create a new package unless the user explicitly asks for package separation
+- Do not create a new package without first asking the user to confirm package creation
 - Do not skip summary reads before flow or view work
 - Do not emit `column_names`; always use `columns`
+- Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
 - Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
+- Do not omit assignees on approval/fill/copy nodes
+- Do not guess role ids, member ids, or editable field ids; resolve names first

package/skills/qingflow-app-builder/references/update-flow.md

@@ -4,11 +4,16 @@ Use this when the app already exists and the task is only about workflow.
 
 ## Minimal sequence
 
-1. `app_read_fields`
-2. `app_read_flow_summary`
-3. start from a canonical preset when possible
-4. `app_flow_plan`
-5. `app_flow_apply`
+1. `builder_tool_contract(tool_name="app_flow_plan")`
+2. `app_read_fields`
+3. `app_read_flow_summary`
+4. `role_search` or `member_search`
+5. `role_create` if the user wants a reusable directory role and no good role exists
+6. start from a canonical preset when possible
+7. patch the skeleton instead of freehanding a full graph
+8. `app_flow_plan`
+9. `app_flow_apply`
+10. `app_read_flow_summary` when apply returns `partial_success` or the user asked for verification
 
 If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
 
@@ -19,7 +24,7 @@ Canonical preset mapping:
 - “默认审批/基础审批/普通审批” -> `basic_approval`
 - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
 
-Plan a simple approval flow:
+Plan a simple approval flow with a role assignee and node-level editable fields:
 
 ```json
 {
@@ -27,7 +32,20 @@ Plan a simple approval flow:
   "arguments": {
     "profile": "default",
     "app_key": "APP_123",
-    "preset": "basic_approval"
+    "preset": "basic_approval",
+    "nodes": [
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {
+          "role_names": ["项目经理"]
+        },
+        "permissions": {
+          "editable_fields": ["状态", "审批意见"]
+        }
+      }
+    ]
   }
 }
 ```
@@ -38,39 +56,133 @@ For flexible business requirements, do not jump straight to a full custom graph.
 2. identify the business-specific changes
 3. patch nodes/transitions explicitly
 
-Only after that should you use explicit nodes:
+For branch flows, keep the public shape canonical:
+
+1. add a `branch` node
+2. add one or more `condition` nodes as branch lanes
+3. put filter rules on the `condition` nodes with `conditions` or `condition_groups`
+4. use an empty `condition` node as the default branch when needed
+
+Canonical branch example:
 
 ```json
 {
-  "tool_name": "app_flow_apply",
+  "tool_name": "app_flow_plan",
   "arguments": {
     "profile": "default",
     "app_key": "APP_123",
     "mode": "replace",
-    "publish": true,
     "nodes": [
       {"id": "start", "type": "start", "name": "发起"},
-      {"id": "approve_1", "type": "approve", "name": "审批"},
+      {"id": "route", "type": "branch", "name": "金额分支"},
+      {
+        "id": "high_amount",
+        "type": "condition",
+        "name": "金额大于等于一万",
+        "conditions": [
+          {"field_name": "预计金额", "operator": "gte", "value": 10000}
+        ]
+      },
+      {
+        "id": "approve_finance",
+        "type": "approve",
+        "name": "财务审批",
+        "assignees": {"role_names": ["财务负责人"]}
+      },
+      {"id": "default_lane", "type": "condition", "name": "其他情况"},
+      {
+        "id": "approve_manager",
+        "type": "approve",
+        "name": "部门审批",
+        "assignees": {"role_names": ["项目经理"]}
+      },
       {"id": "end", "type": "end", "name": "结束"}
     ],
     "transitions": [
-      {"from": "start", "to": "approve_1"},
-      {"from": "approve_1", "to": "end"}
+      {"from": "start", "to": "route"},
+      {"from": "route", "to": "high_amount"},
+      {"from": "high_amount", "to": "approve_finance"},
+      {"from": "route", "to": "default_lane"},
+      {"from": "default_lane", "to": "approve_manager"},
+      {"from": "approve_finance", "to": "end"},
+      {"from": "approve_manager", "to": "end"}
     ]
   }
 }
 ```
 
+Only after that should you use explicit nodes:
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+        "profile": "default",
+        "app_key": "APP_123",
+        "mode": "replace",
+        "publish": true,
+        "nodes": [
+          {"id": "start", "type": "start", "name": "发起"},
+          {
+            "id": "approve_1",
+            "type": "approve",
+            "name": "部门审批",
+            "assignees": {
+              "role_names": ["项目经理"]
+            },
+            "permissions": {
+              "editable_fields": ["状态", "审批意见"]
+            }
+          },
+          {"id": "end", "type": "end", "name": "结束"}
+        ],
+        "transitions": [
+          {"from": "start", "to": "approve_1"},
+          {"from": "approve_1", "to": "end"}
+        ]
+      }
+}
+```
+
+After `app_flow_plan` succeeds, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
+
 ## Common failures
 
+### `FLOW_ASSIGNEE_REQUIRED`
+
+Approval, fill, and copy nodes must declare at least one assignee.
+
+Preferred fix order:
+
+1. `role_search`
+2. `member_search` only if the user explicitly named members
+3. `role_create` if the business needs a reusable role
+4. retry `app_flow_plan` or `app_flow_apply` with canonical `assignees.*`
+
 ### `FLOW_DEPENDENCY_MISSING`
 
 The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
 
+Preferred recovery:
+
+1. use the returned `suggested_next_call`
+2. apply the minimal schema patch
+3. rerun `app_read_fields`
+4. rerun `app_flow_plan`
+
 ### `INVALID_FLOW_EDGE`
 
 One or more transitions reference unknown nodes or create an invalid graph.
 
+### `UNKNOWN_FLOW_FIELD`
+
+The workflow referenced a field name that does not exist, often in:
+
+- `permissions.editable_fields`
+- branch `conditions`
+
+Call `app_read_fields` and retry with the exact field names returned by the app.
+
 ### `STATUS_FIELD_REQUIRED`
 
 The app has no explicit status field recognized by the internal workflow compiler. Add one with `app_schema_apply`, then retry.
@@ -87,11 +199,22 @@ Do not keep guessing preset names or node shapes. First:
 2. reuse `canonical_arguments` if present
 3. check `allowed_values`
 4. retry with canonical preset or canonical node types
+5. for workflow actors and permissions, always convert to:
+   - `assignees.role_names`
+   - `assignees.member_names`
+   - `permissions.editable_fields`
+
+Do not copy internal keys from old plan outputs or logs, including:
+
+- `role_entries`
+- `editable_que_ids`
 
 ## Notes
 
 - `mode=replace` is the only supported flow apply mode
 - `app_flow_apply` publishes by default
+- Prefer roles over explicit members unless the user explicitly asks for named members
+- `basic_approval` and `basic_fill_then_approve` are skeletons, not complete business workflows
 - Report results precisely:
   - “基础流程骨架已创建” when only the preset landed
   - “业务定制规则已补齐” only after the patch phase is complete