@qingflow-tech/qingflow-app-user-mcp 1.0.33 → 1.0.35

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.33
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.35
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.33 qingflow-app-user-mcp
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.35 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

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

@@ -32,6 +32,23 @@ Default modeling rules:
 - Another business object -> a separate app, not a text field
 - Cross-object links -> relation fields, not text fields
 
+## Route First
+
+Before any builder write, classify the request:
+
+- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(apps=[...])` for the app shells and fields. Do not squeeze several business objects into one app.
+- **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
+- **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
+
+For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields may use `target_app_ref` for a client key or `target_app` for another app name. Prefer `target_app_ref` when names may collide.
+
+Builder schema inputs should follow agent-intuitive semantics:
+
+- icons may be `icon/color`, `icon_name/icon_color`, `icon_config`, or `icon: {name, color}`
+- `single_select` / `multi_select` options may be strings or objects such as `{label, value}`; tools normalize to option labels
+- relation fields need a target plus `display_field` and `visible_fields`
+- do not create built-in system fields as form fields: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are platform-generated; only reference supported system fields where a tool explicitly says so, such as button `source_field: "数据ID"`
+
 ## Public Tools You Should Think In
 
 - Package: `package_get`, `package_apply`
@@ -51,7 +68,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
 - Multi-app schema work:
   - use one `app_schema_apply(apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
-  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
+  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`, or `target_app` to point at another `apps[].app_name`
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
   - `can_edit_form` only means schema/form-route capability; it no longer implies app base-info write capability
@@ -68,6 +85,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - dataset BI reports are not created or edited by `app_charts_apply` yet; create them in QingBI first, then attach the existing report with `app_associated_resources_apply` and `report_source="dataset"`
   - it does not attach the report to the Qingflow app associated-resource display; use `app_associated_resources_apply` for that
   - supported `chart_type` values include legacy public aliases `target`, `table` and QingBI types such as `summary`, `columnar`, `area`, `stacked_area`, `funnel`, `waterfall`, `gauge`, `heatmap`, `histogram`, `treemap`, `radar`, `stacked_bar`, `stacked_column`, `scatter`, `ring`, `rose`, `dualaxes`, `map`, and `timeline`
+  - chart `filters` use the unified fixed-filter DSL: `field_name + operator + value/values`; the tool compiles them to QingBI string judge types
   - use `patch_charts` for changing a chart name, visibility, filters, or one config fragment on an existing chart
   - `visibility` is a public capability and should be treated as a base-only permission update
   - do not model chart visibility changes as raw config rewrites
@@ -92,14 +110,15 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - before creating a resource, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`; if it already exists, use `patch_resources` with that `associated_item_id`
   - `client_key` is only a same-call reference for `view_configs[].associated_item_refs`; it is not saved and cannot deduplicate later calls
   - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and existing dataset reports use `report_source="dataset"`
-  - use `match_mappings` for associated view/report filters; dynamic conditions use `source_field`, static conditions use `value`
+  - use `match_mappings` for associated view/report filters; dynamic context matches use `source_field`, static filters use `value`; do not handwrite raw `matchRules`
   - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
 - Views and flows:
   - stay on `app_views_apply` / `app_flow_apply`
   - use `patch_views` for existing-view parameter changes such as `query_conditions`, `filters`, `columns`, or visibility
   - builder view writes use raw `view_key` values from `app_get.views`; `custom:<viewKey>` is a record-data `view_id` form, not a builder `view_key`
+  - do not create platform default/system views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`; they are built in. New views must use business-specific names. To change a built-in view, patch by its existing raw `view_key`
   - use `builder_tool_contract` whenever the minimal legal shape is unclear
-  - keep view `filters` and `query_conditions` separate: `filters` are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
+  - keep view `filters` and `query_conditions` separate: `filters` use `field_name + operator + value/values` and are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
   - new views default the associated report/view display area to visible with `limit_type="all"`; existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched
   - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
 
@@ -107,11 +126,15 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 
 1. Trust the current MCP/session when it is already injected by the runtime; only run auth/workspace recovery after a tool explicitly reports an auth, credential, or workspace error
 2. Confirm whether the task is read-only or write-impacting
-3. Resolve the smallest stable target:
+3. Classify the build scope:
+   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(apps=[...])`
+   - single app -> `app_resolve` / `app_get`, then app-scoped apply tools
+   - record/task/data request -> leave builder and use the matching record/task skill
+4. Resolve the smallest stable target:
    - app-scoped work -> `app_resolve`
    - package-scoped work with known id -> `package_get`
    - portal inventory -> `portal_list`
-4. Read only the smallest config slice needed:
+5. Read only the smallest config slice needed:
    - app map -> `app_get` (default entry; includes compact views, charts, custom buttons, and associated resource pool)
    - fields -> `app_get_fields`
    - layout -> `app_get_layout`
@@ -119,8 +142,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - flow -> `app_get_flow`
    - charts -> `app_get_charts` only when the app_get compact list is not enough
    - portal -> `portal_get`
-5. If the public shape is unclear, call `builder_tool_contract`
-6. Apply the smallest patch tool that fits:
+6. If the public shape is unclear, call `builder_tool_contract`
+7. Apply the smallest patch tool that fits:
    - fields -> `app_schema_apply`
    - layout -> `app_layout_apply`
    - flow -> `app_flow_apply`
@@ -130,7 +153,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - existing charts -> `app_charts_apply.patch_charts`; new/full charts -> `app_charts_apply.upsert_charts`
    - portal -> `portal_apply`
    - package metadata/layout -> `package_apply`
-7. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
+8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
 
 ## Safe Usage Rules
 
@@ -141,6 +164,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Do not use raw `portal_*` writes or raw `qingbi_report_*` writes as the default builder strategy.
 - `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default; `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a draft-only `publish` parameter; `app_charts_apply` is immediate-live without publish.
 - When creating or updating fields, configure the app data title/cover directly in field JSON: `as_data_title: true` is required on exactly one readable top-level title field; `as_data_cover: true` is optional and only valid on one top-level `attachment` field.
+- Do not add platform system fields to `add_fields`; if the user asks for record id, number, applicant, creation/update time, or workflow status, use the built-in data/list/readback fields instead of creating duplicate controls.
 - If the same validation error repeats twice, stop guessing and re-read `builder_tool_contract`.
 - For workflow assignees, prefer `role_search` over explicit members unless the user explicitly wants named members.
 - Public flow building is still intentionally limited to stable linear workflows. If a requirement sounds like branches/conditions, explain the limitation instead of freehanding unsupported graph shapes.

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

@@ -9,6 +9,7 @@ Do not use this playbook when the user is really asking for a system/package wit
 2. create the related apps in one `app_schema_apply(apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
 4. add same-call relation fields with `target_app_ref` when one new app references another new app
+5. choose explicit non-template `icon + color` for each new package/app
 
 Hierarchy reminder:
 
@@ -42,6 +43,8 @@ Use this pattern instead:
 
 ## Example
 
+When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.
+
 Create a new package only after the user confirms package creation:
 
 ```json
@@ -50,7 +53,8 @@ Create a new package only after the user confirms package creation:
   "arguments": {
     "profile": "default",
     "package_name": "研发项目管理",
-    "create_if_missing": true
+    "create_if_missing": true,
+    "icon": {"name": "briefcase", "color": "azure"}
   }
 }
 ```
@@ -76,6 +80,7 @@ Apply schema for a new app:
     "profile": "default",
     "app_name": "客户订单",
     "package_id": 1218950,
+    "icon": {"name": "delivery-box-1", "color": "emerald"},
     "create_if_missing": true,
     "publish": true,
     "add_fields": [
@@ -83,7 +88,7 @@ Apply schema for a new app:
       {"name": "客户名称", "type": "text", "required": true},
       {"name": "订单封面", "type": "attachment", "as_data_cover": true},
       {"name": "订单金额", "type": "amount"},
-      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+      {"name": "状态", "type": "single_select", "options": [{"label": "草稿"}, {"label": "进行中"}, {"label": "已完成"}], "required": true}
     ],
     "update_fields": [],
     "remove_fields": []
@@ -105,6 +110,7 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "customer",
         "app_name": "客户",
+        "icon": {"name": "business-personalcard", "color": "emerald"},
         "add_fields": [
           {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
         ]
@@ -112,6 +118,7 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "order",
         "app_name": "订单",
+        "icon": {"name": "delivery-box-1", "color": "blue"},
         "add_fields": [
           {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
           {

package/skills/qingflow-app-builder/references/match-rules.md

@@ -4,6 +4,12 @@ Use this reference for builder-side field matching rules in custom buttons and a
 
 This is not the same thing as `record_access` analysis filters or normal view `filters`.
 
+Unified public semantics:
+
+- Fixed filters use `field_name + operator + value/values`, for example view `filters` and chart `filters`.
+- Current-record context matches use `target_field + operator + source_field/value`, for example associated resource `match_mappings` and add-data button mappings.
+- Do not handwrite `judgeType`, `judgeValues`, or `matchRules`; the CLI compiles them for the target backend protocol.
+
 ## Where These Rules Apply
 
 - `app_custom_buttons_apply.upsert_buttons[].trigger_add_data_config.field_mappings`
@@ -80,6 +86,15 @@ Use `match_mappings` for associated view/report filters:
 
 Dynamic conditions use `source_field`; static conditions use `value`.
 
+Recommended operators are `eq`, `neq`, `in`, `contains`, `gte`, `lte`, `is_empty`, and `not_empty`; aliases such as `equal`, `equals`, `=`, `!=`, `any_of`, `one_of`, and `empty` are accepted. `field_name` and `field` can be used as aliases for `target_field`. Static single-value filters should use `value`; a single-item `values` array is also accepted.
+
+Examples:
+
+```json
+{"target_field": "客户ID", "operator": "eq", "source_field": "数据ID"}
+{"target_field": "状态", "operator": "eq", "value": "有效"}
+```
+
 For an existing associated resource, put the same filter mapping under `patch_resources[].set`:
 
 ```json

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

@@ -19,6 +19,12 @@ Before picking tools, decide which layer the request targets:
 
 If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
 
+Use this split consistently:
+
+- Complete system/package: `package_apply` first, then one `app_schema_apply(apps=[...])`.
+- Single app: `app_resolve/app_get` first, then app-scoped apply tools.
+- Record/task/data operation: leave builder and use record/task skills.
+
 ## Resolve
 
 - `package_get`: read one known package by `package_id`; it reads package `baseInfo` first and may warn `PACKAGE_DETAIL_READ_DEGRADED` when the richer detail endpoint needs package edit/add-app permission. Treat that warning as degraded detail, not as package-read failure.
@@ -48,8 +54,8 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `app_flow_apply`: replace workflow
 - `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; new views default associated report/view display to visible with `limit_type="all"`
 - `app_custom_buttons_apply`: use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; configure add-data field mappings/default values; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field.
-- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call.
-- `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; supports `target/table` aliases plus QingBI chart types such as `summary`, `columnar`, `area`, `funnel`, `radar`, `scatter`, `dualaxes`, and `map`; charts are immediate-live and do not publish; use `chart_id` when names are not unique
+- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` with `target_field + operator + source_field/value` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call.
+- `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `filters` with `field_name + operator + value/values`; the tool compiles them to QingBI string judge types. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; supports `target/table` aliases plus QingBI chart types such as `summary`, `columnar`, `area`, `funnel`, `radar`, `scatter`, `dualaxes`, and `map`; charts are immediate-live and do not publish; use `chart_id` when names are not unique
 - `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; create mode only prechecks package add_app, matching backend portal creation; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics
 
 For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_buttons: [{"button_id": 1001, "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
@@ -65,7 +71,7 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Create a brand new package, then create one app in it:
   `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`; use `apps[].client_key` plus `target_app_ref`, or `target_app` when referencing by app name
 - Update fields on an existing app:
   `app_resolve -> app_get_fields -> app_schema_apply`
 - Tidy layout:
@@ -97,3 +103,4 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Do not omit assignees on approval/fill/copy nodes
 - Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
 - Do not guess role ids, member ids, or editable field ids; resolve names first
+- Do not force agent-authored schema into backend-internal names when public aliases exist: icons may use `icon_config` / `icon:{name,color}`, options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.

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

@@ -10,6 +10,8 @@ Use this when the app already exists and the task is only about fields.
 
 ## Example
 
+Do not add platform system fields as form controls: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are generated by Qingflow; use readback/list fields when you need them.
+
 Read current fields first:
 
 ```json
@@ -70,3 +72,4 @@ Treat it as uncertain write state. Read back with `app_get_fields` before retryi
 - `checkbox -> multi_select`
 - `as_data_title: true` marks the app data title; the final form must have exactly one top-level data title field
 - `as_data_cover: true` marks the app data cover; the cover is optional and must be a top-level `attachment` field
+- `数据ID`, `编号`, applicant/creation/update time, and workflow status fields are system-generated and must not appear in `add_fields`

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

@@ -28,16 +28,18 @@ Canonical rules before any example:
 - Always use `columns`
 - Do not emit `column_names`
 - Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
-- Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
+- Use `filters` with the unified fixed-filter DSL: `field_name`, `operator`, `value`/`values`; do not write raw `judgeType` / `judgeValues`
 - Use `query_conditions` for the frontend query panel. Do not put query-panel fields into `filters`.
+- Do not create views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`. These are built-in default/system views. New views must use business-specific names such as `订单台账视图`, `客户跟进视图`, or `逾期任务看板`.
+- To change a built-in default/system view, first read the existing raw `view_key` from `app_get.views` or `app_get_views`, then use `patch_views` or a full `upsert_views` item with that `view_key`.
 - New views created by `app_views_apply` default the frontend associated report/view area to visible with `limit_type="all"`. Existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched.
-- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
+- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` with `target_field + operator + source_field/value` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
 - For gantt, use `start_field`, `end_field`, and optionally `title_field`
 - If `app_get.views` or `app_get_views` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
 - Builder view writes always use the raw `view_key` from `app_get.views[].view_key`, such as `emsrao25rs02`. Do not pass `custom:emsrao25rs02`; that prefixed form is only for record-data `view_id`.
 - For an existing view, prefer `patch_views` for parameter replacement. Do not send a partial `upsert_views` object such as only `name/type/query_conditions`; backend view saves require other type-specific fields, and the patch path preserves them for you.
 
-Apply a default table view:
+Apply a business table view:
 
 ```json
 {
@@ -48,7 +50,7 @@ Apply a default table view:
     "publish": true,
     "upsert_views": [
       {
-        "name": "全部订单",
+        "name": "订单台账视图",
         "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
         "type": "table",
         "columns": ["订单编号", "客户名称", "订单金额", "状态"]

package/skills/qingflow-record-insert/SKILL.md

@@ -79,6 +79,7 @@ Without `record_id` / `workflow_node_id` / `fields-file`, the result is a static
 16. If post-write detail context matters, read `record_get.fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs and do not expect legacy flat record shapes
 17. Treat nested schema shape as guidance, not a brittle contract; do not hard-code transient implementation details like optional nested `field_id` shape when composing inserts
 18. For `partial_success`, read `created_record_ids`, then repair only the failed `items[].row_number` using `failed_fields`; never retry the whole batch after any row has `write_executed=true`
+19. Do not put Qingflow system fields in `fields`: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are generated by the platform and can be read after creation, not manually inserted.
 
 ## Field Notes
 
@@ -120,6 +121,7 @@ qingflow --json record insert --app-key APP_KEY --items-file records.json
 
 - Do not skip `record_insert_schema_get`
 - Do not invent missing required fields
+- Do not fill platform system fields such as `数据ID`, `编号`, `申请人`, `创建时间`, or `更新时间`
 - Do not flatten subtable leaf fields to the top level
 - Do not pre-query or silently guess member / department / relation ids when a natural string is enough
 - Do not retry a whole batch after `created_record_ids` is non-empty

package/skills/qingflow-task-ops/SKILL.md

@@ -62,7 +62,7 @@ Use one of these two modes:
    2. Discover the exact target with `task_list`
    3. If the target or action requirements are ambiguous, read `task_get`; otherwise go straight to `task_action_execute`
    4. Execute through `task_action_execute`
-   5. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, executed action, and any warnings
+   5. After actions, report whether it succeeded, the `task_id`, the executed action, the final route/status, and any warnings
 
 ## Task-Center Rules
 
@@ -111,7 +111,7 @@ Use one of these two modes:
 - Do not execute `task_action_execute` until the user explicitly confirms the chosen action
 - Exception: if the user has already explicitly authorized a concrete action on exact targets, you may execute directly after exact target resolution
 - Avoid actions on ambiguous tasks or records
-- Summarize the final action and the exact `app_key / record_id / workflow_node_id`
+- Summarize the final action by `task_id`; include `app_key`, `record_id`, or `workflow_node_id` only as read-only context when the tool returns them, not as the action locator
 - `reject` requires `payload.audit_feedback`
 - For approve/reject, trust the current task detail or an explicit frontend-provided `formId`; app baseInfo is only a fallback. A baseInfo `40002` is not final task-action denial when `formId` is already known.
 - `save_only` requires non-empty `fields` and is only available when the backend exposes editable fields for the current node

package/src/qingflow_mcp/builder_facade/models.py

@@ -1259,11 +1259,30 @@ class CustomButtonFieldMappingPatch(StrictModel):
 
 
 class FieldMatchMappingPatch(StrictModel):
-    target_field: Any = Field(validation_alias=AliasChoices("target_field", "targetField", "target", "field"))
+    target_field: Any = Field(
+        validation_alias=AliasChoices("target_field", "targetField", "target", "field", "field_name", "fieldName")
+    )
     source_field: Any | None = Field(default=None, validation_alias=AliasChoices("source_field", "sourceField", "source"))
     value: Any | None = Field(default=None, validation_alias=AliasChoices("value", "static_value", "staticValue"))
     operator: str = Field(default="eq", validation_alias=AliasChoices("operator", "op", "judge_type", "judgeType"))
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_semantic_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        has_static_value = any(key in payload for key in ("value", "static_value", "staticValue"))
+        if "values" in payload:
+            values = payload.pop("values")
+            if has_static_value:
+                return payload
+            if isinstance(values, list) and len(values) == 1:
+                payload["value"] = values[0]
+            else:
+                payload["value"] = values
+        return payload
+
     @model_validator(mode="after")
     def validate_shape(self) -> "FieldMatchMappingPatch":
         has_source = self.source_field is not None and str(self.source_field).strip() != ""
@@ -2292,6 +2311,8 @@ def _normalize_field_payload(value: Any) -> Any:
     payload = dict(value)
     if "fields" in payload and "subfields" not in payload:
         payload["subfields"] = payload.pop("fields")
+    if "options" in payload:
+        payload["options"] = _normalize_field_options(payload.get("options"))
     raw_type = payload.get("type")
     if isinstance(raw_type, int):
         normalized_from_id = FIELD_TYPE_ID_ALIASES.get(raw_type)
@@ -2324,6 +2345,34 @@ def _normalize_field_payload(value: Any) -> Any:
     return payload
 
 
+def _normalize_field_options(value: Any) -> Any:
+    if not isinstance(value, list):
+        return value
+    normalized: list[str] = []
+    for item in value:
+        if isinstance(item, str):
+            normalized.append(item)
+            continue
+        if isinstance(item, (int, float, bool)):
+            normalized.append(str(item))
+            continue
+        if isinstance(item, dict):
+            label = (
+                item.get("label")
+                or item.get("name")
+                or item.get("title")
+                or item.get("value")
+                or item.get("text")
+                or item.get("optValue")
+                or item.get("optName")
+            )
+            if label is not None:
+                normalized.append(str(label))
+                continue
+        normalized.append(str(item))
+    return normalized
+
+
 def _slugify_title(title: str) -> str:
     normalized = "".join(ch.lower() if ch.isalnum() else "_" for ch in str(title or ""))
     collapsed = "_".join(part for part in normalized.split("_") if part)

package/src/qingflow_mcp/builder_facade/service.py

@@ -15049,14 +15049,14 @@ def _build_public_chart_filter_matrix(
         return []
     group: list[dict[str, Any]] = []
     judge_map = {
-        ViewFilterOperator.eq.value: 0,
-        ViewFilterOperator.neq.value: 1,
-        ViewFilterOperator.gte.value: 5,
-        ViewFilterOperator.lte.value: 7,
-        ViewFilterOperator.in_.value: 9,
-        ViewFilterOperator.contains.value: 19,
-        ViewFilterOperator.is_empty.value: 15,
-        ViewFilterOperator.not_empty.value: 16,
+        ViewFilterOperator.eq.value: "equal",
+        ViewFilterOperator.neq.value: "unequal",
+        ViewFilterOperator.gte.value: "greaterOrEqual",
+        ViewFilterOperator.lte.value: "lessOrEqual",
+        ViewFilterOperator.in_.value: "anyMatch",
+        ViewFilterOperator.contains.value: "include",
+        ViewFilterOperator.is_empty.value: "isNull",
+        ViewFilterOperator.not_empty.value: "notNull",
     }
     for rule in rules:
         qingbi_field = _resolve_qingbi_chart_field(
@@ -15074,7 +15074,7 @@ def _build_public_chart_filter_matrix(
                 "fieldId": field_id,
                 "fieldName": qingbi_field.get("fieldName") or form_field.get("name") or field_id,
                 "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(form_field.get("type") or "")),
-                "judgeType": judge_map.get(operator, 0),
+                "judgeType": judge_map.get(operator, "equal"),
                 "judgeValues": values,
                 "matchType": 1,
             }

package/src/qingflow_mcp/cli/commands/builder.py

@@ -4,6 +4,7 @@ import argparse
 
 from ..context import CliContext
 from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
+from ..json_io import load_json_value
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -476,26 +477,30 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
-    apps = load_list_arg(args.apps_file, option_name="--apps-file")
+    apps_payload = _load_apps_file_arg(args.apps_file)
+    apps = apps_payload["apps"]
+    package_id = args.package_id
+    if package_id is None and apps_payload.get("package_id") is not None:
+        package_id = int(apps_payload["package_id"])
     if args.apps_file:
         if not apps:
             raise_config_error(
                 "schema apply multi-app mode requires a non-empty --apps-file.",
-                fix_hint="Pass a JSON array with at least one app item.",
+                fix_hint="Pass a JSON array, or a JSON object like {\"package_id\":1001,\"apps\":[...]} with at least one app item.",
             )
         if args.app_key or args.app_name or args.app_title or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
             raise_config_error(
                 "schema apply multi-app mode accepts --package-id/--create-if-missing plus --apps-file only.",
                 fix_hint="Use `--apps-file` for batch mode, or remove `--apps-file` and use the single-app arguments.",
             )
-        if args.package_id is None:
+        if package_id is None:
             raise_config_error(
                 "schema apply multi-app mode requires --package-id.",
-                fix_hint="Pass `--package-id` and app names inside --apps-file.",
+                fix_hint="Pass `--package-id`, or put `package_id` at the top level of --apps-file. `package_name` alone does not create the package here; run `builder package apply` first.",
             )
         return context.builder.app_schema_apply(
             profile=args.profile,
-            package_id=args.package_id,
+            package_id=package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
             create_if_missing=bool(args.create_if_missing),
             publish=bool(args.publish),
@@ -537,6 +542,29 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _load_apps_file_arg(path: str | None) -> dict[str, object]:
+    if not path:
+        return {"apps": []}
+    payload = load_json_value(path, option_name="--apps-file")
+    if isinstance(payload, list):
+        return {"apps": payload}
+    if isinstance(payload, dict):
+        apps = payload.get("apps")
+        if not isinstance(apps, list):
+            raise_config_error(
+                "--apps-file JSON object requires an apps array.",
+                fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw JSON array.",
+            )
+        result: dict[str, object] = {"apps": apps}
+        if payload.get("package_id") is not None:
+            result["package_id"] = payload.get("package_id")
+        return result
+    raise_config_error(
+        "--apps-file must be a JSON array or an object containing apps.",
+        fix_hint="Use [{...}] or {\"package_id\":1001,\"apps\":[...]}",
+    )
+
+
 def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_layout_apply(
         profile=args.profile,

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -146,8 +146,11 @@ class AiBuilderTools(ToolBase):
             package_id: int | None = None,
             package_name: str | None = None,
             create_if_missing: bool = False,
-            icon: str | None = None,
+            icon: str | JSONObject | None = None,
             color: str | None = None,
+            icon_name: str | None = None,
+            icon_color: str | None = None,
+            icon_config: JSONObject | None = None,
             visibility: JSONObject | None = None,
             items: list[dict] | None = None,
             allow_detach: bool = False,
@@ -159,6 +162,9 @@ class AiBuilderTools(ToolBase):
                 create_if_missing=create_if_missing,
                 icon=icon,
                 color=color,
+                icon_name=icon_name,
+                icon_color=icon_color,
+                icon_config=icon_config,
                 visibility=visibility,
                 items=items or None,
                 allow_detach=allow_detach,
@@ -364,8 +370,11 @@ class AiBuilderTools(ToolBase):
             package_id: int | None = None,
             app_name: str = "",
             app_title: str = "",
-            icon: str = "",
+            icon: str | JSONObject = "",
             color: str = "",
+            icon_name: str | None = None,
+            icon_color: str | None = None,
+            icon_config: JSONObject | None = None,
             visibility: JSONObject | None = None,
             create_if_missing: bool = False,
             publish: bool = True,
@@ -423,6 +432,9 @@ class AiBuilderTools(ToolBase):
                 app_title=app_title,
                 icon=icon,
                 color=color,
+                icon_name=icon_name,
+                icon_color=icon_color,
+                icon_config=icon_config,
                 visibility=visibility,
                 create_if_missing=create_if_missing,
                 publish=publish,
@@ -733,13 +745,23 @@ class AiBuilderTools(ToolBase):
         package_id: int | None = None,
         package_name: str | None = None,
         create_if_missing: bool = False,
-        icon: str | None = None,
+        icon: str | JSONObject | None = None,
         color: str | None = None,
+        icon_name: str | None = None,
+        icon_color: str | None = None,
+        icon_config: JSONObject | None = None,
         visibility: JSONObject | None = None,
         items: list[dict] | None = None,
         allow_detach: bool = False,
     ) -> JSONObject:
         """执行分组与包相关逻辑。"""
+        icon, color = _normalize_builder_icon_args(
+            icon=icon,
+            color=color,
+            icon_name=icon_name,
+            icon_color=icon_color,
+            icon_config=icon_config,
+        )
         visibility_patch = None
         if visibility is not None:
             try:
@@ -1459,6 +1481,22 @@ class AiBuilderTools(ToolBase):
         remove_fields: list[JSONObject],
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        system_field_failure = _reserved_system_field_name_failure(
+            tool_name="app_schema_plan",
+            profile=profile,
+            app_key=app_key,
+            package_id=package_id,
+            app_name=app_name,
+            icon=icon,
+            color=color,
+            visibility=visibility,
+            create_if_missing=create_if_missing,
+            add_fields=add_fields,
+            update_fields=update_fields,
+            remove_fields=remove_fields,
+        )
+        if system_field_failure is not None:
+            return system_field_failure
         try:
             request = SchemaPlanRequest.model_validate(
                 {
@@ -1609,6 +1647,15 @@ class AiBuilderTools(ToolBase):
         preset: str | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        reserved_failure = _reserved_system_view_name_failure(
+            tool_name="app_views_plan",
+            profile=profile,
+            app_key=app_key,
+            upsert_views=upsert_views,
+            remove_views=remove_views,
+        )
+        if reserved_failure is not None:
+            return reserved_failure
         try:
             request = ViewsPlanRequest.model_validate(
                 {
@@ -1650,8 +1697,11 @@ class AiBuilderTools(ToolBase):
         package_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
-        icon: str = "",
+        icon: str | JSONObject = "",
         color: str = "",
+        icon_name: str | None = None,
+        icon_color: str | None = None,
+        icon_config: JSONObject | None = None,
         visibility: JSONObject | None = None,
         create_if_missing: bool = False,
         publish: bool = True,
@@ -1661,7 +1711,15 @@ class AiBuilderTools(ToolBase):
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        icon, color = _normalize_builder_icon_args(
+            icon=icon,
+            color=color,
+            icon_name=icon_name,
+            icon_color=icon_color,
+            icon_config=icon_config,
+        )
         if apps:
+            apps = [_normalize_schema_app_item(item) if isinstance(item, dict) else item for item in apps]
             result = self._app_schema_apply_multi(
                 profile=profile,
                 package_id=package_id,
@@ -1725,6 +1783,17 @@ class AiBuilderTools(ToolBase):
         }
         if visibility is not None:
             normalized_args["visibility"] = deepcopy(visibility)
+        system_field_failure = _reserved_system_field_name_failure_for_apps(
+            tool_name="app_schema_apply",
+            profile=profile,
+            package_id=package_id,
+            visibility=visibility,
+            create_if_missing=create_if_missing,
+            publish=publish,
+            apps=apps,
+        )
+        if system_field_failure is not None:
+            return system_field_failure
         if package_id is None:
             return _config_failure(
                 tool_name="app_schema_apply",
@@ -1801,6 +1870,7 @@ class AiBuilderTools(ToolBase):
             )
 
         client_key_to_app_key: dict[str, str] = {}
+        app_name_to_app_key: dict[str, str] = {}
         created_app_keys: list[str] = []
         results: list[JSONObject] = []
         any_write_executed = False
@@ -1864,11 +1934,14 @@ class AiBuilderTools(ToolBase):
                 created_app_keys.append(resolved_key)
             if client_key:
                 client_key_to_app_key[client_key] = resolved_key
+            resolved_name = str(public_shell.get("app_name_after") or public_shell.get("app_name") or app_name or "").strip()
+            if resolved_name:
+                app_name_to_app_key[resolved_name] = resolved_key
             results.append({
                 "index": index,
                 "row_number": index + 1,
                 "client_key": client_key or None,
-                "app_name": str(public_shell.get("app_name_after") or public_shell.get("app_name") or app_name or "").strip() or None,
+                "app_name": resolved_name or None,
                 "app_key": resolved_key,
                 "status": "shell_ready",
                 "created": bool(public_shell.get("created")),
@@ -1888,7 +1961,7 @@ class AiBuilderTools(ToolBase):
             item = deepcopy(raw_item)
             app_key = str(existing.get("app_key") or "").strip()
             try:
-                compiled_item = _compile_multi_app_schema_item_refs(item, client_key_to_app_key)
+                compiled_item = _compile_multi_app_schema_item_refs(item, client_key_to_app_key, app_name_to_app_key)
             except ValueError as error:
                 final_items.append({
                     **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
@@ -2012,6 +2085,23 @@ class AiBuilderTools(ToolBase):
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         effective_app_name = app_name or app_title
+        system_field_failure = _reserved_system_field_name_failure(
+            tool_name="app_schema_apply",
+            profile=profile,
+            app_key=app_key,
+            package_id=package_id,
+            app_name=effective_app_name,
+            icon=icon,
+            color=color,
+            visibility=visibility,
+            create_if_missing=create_if_missing,
+            publish=publish,
+            add_fields=add_fields,
+            update_fields=update_fields,
+            remove_fields=remove_fields,
+        )
+        if system_field_failure is not None:
+            return system_field_failure
         icon_failure = _validate_workspace_icon_for_builder(
             tool_name="app_schema_apply",
             icon=icon,
@@ -2343,6 +2433,17 @@ class AiBuilderTools(ToolBase):
         remove_views: list[str],
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
+        reserved_failure = _reserved_system_view_name_failure(
+            tool_name="app_views_apply",
+            profile=profile,
+            app_key=app_key,
+            publish=publish,
+            upsert_views=upsert_views,
+            patch_views=patch_views,
+            remove_views=remove_views,
+        )
+        if reserved_failure is not None:
+            return reserved_failure
         if patch_views:
             try:
                 parsed_views = [ViewUpsertPatch.model_validate(item) for item in (upsert_views or [])]
@@ -2417,7 +2518,7 @@ class AiBuilderTools(ToolBase):
                         "profile": profile,
                         "app_key": str(plan_args.get("app_key") or app_key),
                         "publish": publish,
-                        "upsert_views": plan_args.get("upsert_views") or [{"name": "全部数据", "type": "table", "columns": ["字段A"]}],
+                        "upsert_views": plan_args.get("upsert_views") or [{"name": "业务台账视图", "type": "table", "columns": ["字段A"]}],
                         "remove_views": plan_args.get("remove_views") or [],
                     },
                 },
@@ -2786,8 +2887,58 @@ def _multi_app_item_failure(index: int, item: object, error_code: str, message:
     }
 
 
-def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key: dict[str, str]) -> JSONObject:
+def _normalize_builder_icon_args(
+    *,
+    icon: str | JSONObject | None,
+    color: str | None,
+    icon_name: str | None = None,
+    icon_color: str | None = None,
+    icon_config: JSONObject | None = None,
+) -> tuple[str | None, str | None]:
+    payloads: list[JSONObject] = []
+    if isinstance(icon_config, dict):
+        payloads.append(icon_config)
+    if isinstance(icon, dict):
+        payloads.append(icon)
+
+    normalized_icon = None if isinstance(icon, dict) else icon
+    normalized_color = color
+    for payload in payloads:
+        normalized_icon = normalized_icon or payload.get("icon") or payload.get("icon_name") or payload.get("iconName") or payload.get("name")
+        normalized_color = normalized_color or payload.get("color") or payload.get("icon_color") or payload.get("iconColor")
+    normalized_icon = normalized_icon or icon_name
+    normalized_color = normalized_color or icon_color
+    return (
+        str(normalized_icon).strip() if normalized_icon is not None else None,
+        str(normalized_color).strip() if normalized_color is not None else None,
+    )
+
+
+def _normalize_schema_app_item(item: JSONObject) -> JSONObject:
+    normalized = deepcopy(item)
+    icon, color = _normalize_builder_icon_args(
+        icon=normalized.get("icon"),
+        color=normalized.get("color"),
+        icon_name=normalized.get("icon_name") or normalized.get("iconName"),
+        icon_color=normalized.get("icon_color") or normalized.get("iconColor"),
+        icon_config=normalized.get("icon_config") or normalized.get("iconConfig"),
+    )
+    if icon:
+        normalized["icon"] = icon
+    if color:
+        normalized["color"] = color
+    for key in ("icon_name", "iconName", "icon_color", "iconColor", "icon_config", "iconConfig"):
+        normalized.pop(key, None)
+    return normalized
+
+
+def _compile_multi_app_schema_item_refs(
+    item: JSONObject,
+    client_key_to_app_key: dict[str, str],
+    app_name_to_app_key: dict[str, str] | None = None,
+) -> JSONObject:
     compiled = deepcopy(item)
+    app_name_to_app_key = app_name_to_app_key or {}
 
     def visit(value):
         if isinstance(value, list):
@@ -2807,6 +2958,13 @@ def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key:
             if not target_app_key:
                 raise ValueError(f"target_app_ref '{ref_key}' did not match any apps[].client_key")
             payload["target_app_key"] = target_app_key
+        target_app = payload.pop("target_app", None) or payload.pop("targetApp", None)
+        if target_app is not None and not str(payload.get("target_app_key") or "").strip():
+            target_name = str(target_app or "").strip()
+            target_app_key = app_name_to_app_key.get(target_name)
+            if not target_app_key:
+                raise ValueError(f"target_app '{target_name}' did not match any apps[].app_name in the same call")
+            payload["target_app_key"] = target_app_key
         return payload
 
     return visit(compiled)
@@ -2855,7 +3013,7 @@ def _contains_multi_app_target_ref(value: object) -> bool:
     if not isinstance(value, dict):
         return False
     for key, entry in value.items():
-        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey"}:
+        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey", "target_app", "targetApp"}:
             return True
         if _contains_multi_app_target_ref(entry):
             return True
@@ -2968,6 +3126,197 @@ def _visibility_validation_failure(
     return result
 
 
+_RESERVED_SYSTEM_FIELD_NAMES = {
+    "数据ID",
+    "编号",
+    "申请人",
+    "申请时间",
+    "创建人",
+    "创建时间",
+    "提交人",
+    "提交时间",
+    "更新时间",
+    "更新人",
+    "当前流程状态",
+    "当前处理人",
+    "当前处理节点",
+    "流程标题",
+}
+
+
+def _field_patch_name(item: object) -> str:
+    if not isinstance(item, dict):
+        return ""
+    value = item.get("name")
+    if value is None:
+        value = item.get("title")
+    if value is None:
+        value = item.get("field_name")
+    if value is None:
+        value = item.get("fieldName")
+    return str(value or "").strip()
+
+
+def _reserved_system_field_name_failure(
+    *,
+    tool_name: str,
+    profile: str,
+    app_key: str = "",
+    package_id: int | None = None,
+    app_name: str = "",
+    icon: str | None = None,
+    color: str | None = None,
+    visibility: JSONObject | None = None,
+    create_if_missing: bool = False,
+    publish: bool | None = None,
+    add_fields: list[JSONObject] | None = None,
+    update_fields: list[JSONObject] | None = None,
+    remove_fields: list[JSONObject] | None = None,
+    app_index: int | None = None,
+) -> JSONObject | None:
+    for index, item in enumerate(add_fields or []):
+        name = _field_patch_name(item)
+        if name not in _RESERVED_SYSTEM_FIELD_NAMES:
+            continue
+        suggested_add_fields = [field for field in (add_fields or []) if _field_patch_name(field) not in _RESERVED_SYSTEM_FIELD_NAMES]
+        arguments: JSONObject = {
+            "profile": profile,
+            "app_key": app_key,
+            "package_id": package_id,
+            "app_name": app_name,
+            "icon": icon or "",
+            "color": color or "",
+            "visibility": visibility,
+            "create_if_missing": create_if_missing,
+            "add_fields": suggested_add_fields,
+            "update_fields": update_fields or [],
+            "remove_fields": remove_fields or [],
+        }
+        if publish is not None:
+            arguments["publish"] = publish
+        return _config_failure(
+            tool_name=tool_name,
+            error_code="RESERVED_SYSTEM_FIELD_NAME",
+            message=f"add_fields[{index}].name uses built-in system field name '{name}'",
+            fix_hint="Do not create form fields named 数据ID, 编号, 申请人, 申请时间, 创建人, 创建时间, 提交人, 提交时间, 更新时间, 更新人, 当前流程状态, 当前处理人, 当前处理节点, or 流程标题. These fields are provided by Qingflow. Remove them from add_fields; only reference them where the tool explicitly supports system fields, such as button source_field 数据ID.",
+            details={
+                "reserved_field_names": sorted(_RESERVED_SYSTEM_FIELD_NAMES),
+                "blocked_index": index,
+                "blocked_name": name,
+                "app_index": app_index,
+            },
+            suggested_next_call={"tool_name": tool_name, "arguments": arguments},
+        )
+    return None
+
+
+def _reserved_system_field_name_failure_for_apps(
+    *,
+    tool_name: str,
+    profile: str,
+    package_id: int | None,
+    visibility: JSONObject | None,
+    create_if_missing: bool,
+    publish: bool,
+    apps: list[JSONObject],
+) -> JSONObject | None:
+    for index, item in enumerate(apps or []):
+        if not isinstance(item, dict):
+            continue
+        failure = _reserved_system_field_name_failure(
+            tool_name=tool_name,
+            profile=profile,
+            app_key=str(item.get("app_key") or item.get("appKey") or ""),
+            package_id=package_id,
+            app_name=str(item.get("app_name") or item.get("appName") or ""),
+            icon=str(item.get("icon") or ""),
+            color=str(item.get("color") or ""),
+            visibility=item.get("visibility") if isinstance(item.get("visibility"), dict) else visibility,
+            create_if_missing=create_if_missing,
+            publish=publish,
+            add_fields=list(item.get("add_fields") or item.get("addFields") or []),
+            update_fields=list(item.get("update_fields") or item.get("updateFields") or []),
+            remove_fields=list(item.get("remove_fields") or item.get("removeFields") or []),
+            app_index=index,
+        )
+        if failure is not None:
+            suggested = deepcopy(failure.get("suggested_next_call") or {})
+            arguments = suggested.get("arguments")
+            if isinstance(arguments, dict):
+                fixed_apps = deepcopy(apps)
+                if isinstance(fixed_apps[index], dict):
+                    fixed_apps[index]["add_fields"] = arguments.get("add_fields") or []
+                arguments = {
+                    "profile": profile,
+                    "package_id": package_id,
+                    "visibility": visibility,
+                    "create_if_missing": create_if_missing,
+                    "publish": publish,
+                    "apps": fixed_apps,
+                }
+                failure["suggested_next_call"] = {"tool_name": tool_name, "arguments": arguments}
+            return failure
+    return None
+
+
+_RESERVED_SYSTEM_VIEW_NAMES = {
+    "全部数据",
+    "我的数据",
+    "我发起的",
+    "待办",
+    "已办",
+    "抄送",
+}
+
+
+def _reserved_system_view_name_failure(
+    *,
+    tool_name: str,
+    profile: str,
+    app_key: str,
+    publish: bool | None = None,
+    upsert_views: list[JSONObject] | None = None,
+    patch_views: list[JSONObject] | None = None,
+    remove_views: list[str] | None = None,
+) -> JSONObject | None:
+    for index, item in enumerate(upsert_views or []):
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name") or "").strip()
+        view_key = str(item.get("view_key") or item.get("viewKey") or "").strip()
+        if name in _RESERVED_SYSTEM_VIEW_NAMES and not view_key:
+            suggested: JSONObject = {
+                "tool_name": tool_name,
+                "arguments": {
+                    "profile": profile,
+                    "app_key": app_key,
+                    "upsert_views": [
+                        {
+                            **item,
+                            "name": "业务台账视图",
+                        }
+                    ],
+                    "patch_views": patch_views or [],
+                    "remove_views": remove_views or [],
+                },
+            }
+            if publish is not None:
+                suggested["arguments"]["publish"] = publish
+            return _config_failure(
+                tool_name=tool_name,
+                error_code="RESERVED_SYSTEM_VIEW_NAME",
+                message=f"upsert_views[{index}].name uses built-in system view name '{name}' without view_key",
+                fix_hint="Do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送. Use a business-specific view name for new views; to modify a built-in view, pass its existing raw view_key or use patch_views.",
+                details={
+                    "reserved_view_names": sorted(_RESERVED_SYSTEM_VIEW_NAMES),
+                    "blocked_index": index,
+                    "blocked_name": name,
+                },
+                suggested_next_call=suggested,
+            )
+    return None
+
+
 def _config_failure(
     *,
     tool_name: str,
@@ -2976,6 +3325,7 @@ def _config_failure(
     error_code: str = "CONFIG_ERROR",
     details: JSONObject | None = None,
     allowed_values: JSONObject | None = None,
+    suggested_next_call: JSONObject | None = None,
 ) -> JSONObject:
     contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
     public_allowed_values = deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {}
@@ -2996,7 +3346,7 @@ def _config_failure(
         "missing_fields": [],
         "allowed_values": public_allowed_values,
         "details": public_details,
-        "suggested_next_call": None,
+        "suggested_next_call": suggested_next_call,
         "request_id": None,
         "backend_code": None,
         "http_status": None,
@@ -4054,13 +4404,29 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "package_apply": {
-        "allowed_keys": ["package_id", "package_name", "create_if_missing", "icon", "color", "visibility", "items", "allow_detach"],
+        "allowed_keys": [
+            "package_id",
+            "package_name",
+            "create_if_missing",
+            "icon",
+            "color",
+            "icon_name",
+            "icon_color",
+            "icon_config",
+            "visibility",
+            "items",
+            "allow_detach",
+        ],
         "aliases": {
             "packageId": "package_id",
             "packageName": "package_name",
             "createIfMissing": "create_if_missing",
             "iconName": "icon",
             "iconColor": "color",
+            "icon_config.name": "icon",
+            "icon_config.icon_name": "icon",
+            "icon_config.color": "color",
+            "icon_config.icon_color": "color",
             "allowDetach": "allow_detach",
         },
         "allowed_values": {
@@ -4072,6 +4438,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "create or update package metadata, visibility, grouping, and ordering in one call",
             "creating a package requires explicit icon + color; icon=template is blocked because it is too generic",
+            "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
             "updating a package preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "metadata keys omitted on update are preserved",
@@ -4536,6 +4903,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode may set visibility for the new app; edit mode may update visibility on an existing app",
             "create mode should include explicit non-template icon + color; apply mode enforces this before writing",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
+            "do not add form fields named 数据ID, 编号, 申请人, 申请时间, 创建人, 创建时间, 提交人, 提交时间, 更新时间, 更新人, 当前流程状态, 当前处理人, 当前处理节点, or 流程标题; these are Qingflow built-in system fields, not fields to create",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
@@ -4575,6 +4943,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "app_title",
             "icon",
             "color",
+            "icon_name",
+            "icon_color",
+            "icon_config",
             "visibility",
             "create_if_missing",
             "publish",
@@ -4587,11 +4958,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].app_name",
             "apps[].icon",
             "apps[].color",
+            "apps[].icon_name",
+            "apps[].icon_color",
+            "apps[].icon_config",
             "apps[].visibility",
             "apps[].add_fields",
             "apps[].update_fields",
             "apps[].remove_fields",
             "apps[].add_fields[].target_app_ref",
+            "apps[].add_fields[].target_app",
         ],
         "aliases": {
             "app_title": "app_name",
@@ -4601,8 +4976,16 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].appKey": "apps[].app_key",
             "apps[].appName": "apps[].app_name",
             "apps[].appTitle": "apps[].app_name",
+            "apps[].iconName": "apps[].icon",
+            "apps[].iconColor": "apps[].color",
+            "apps[].icon_config.name": "apps[].icon",
+            "apps[].icon_config.color": "apps[].color",
             "field.targetAppRef": "field.target_app_ref",
             "field.targetAppClientKey": "field.target_app_ref",
+            "field.targetApp": "field.target_app",
+            "field.options[].label": "field.options[]",
+            "field.options[].value": "field.options[]",
+            "field.options[].optValue": "field.options[]",
             "field.title": "field.name",
             "field.label": "field.name",
             "field.fields": "field.subfields",
@@ -4642,12 +5025,16 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
             "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
             "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
+            "multi-app relation fields may also use target_app with another apps[].app_name; prefer target_app_ref/client_key when names may collide",
             "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
             "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
+            "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
             "multi-app create mode requires each new app item to include a distinct non-template icon and a valid color",
+            "single_select and multi_select options accept strings or objects such as {label,value}; builder normalizes them to option labels before writing",
             "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
+            "do not add form fields named 数据ID, 编号, 申请人, 申请时间, 创建人, 创建时间, 提交人, 提交时间, 更新时间, 更新人, 当前流程状态, 当前处理人, 当前处理节点, or 流程标题; these are Qingflow built-in system fields, not fields to create",
             *_VISIBILITY_EXECUTION_NOTES,
             "update_fields is the field-level partial update path; it reads current form schema and preserves untouched field config",
             "multiple relation fields are backend-risky; read verification.relation_field_limit_verified and warnings before declaring the schema stable",
@@ -5047,6 +5434,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
+            "do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送; these are built-in system/default views. Use business-specific names for new views, and pass the existing raw view_key or patch_views when changing a built-in view",
             "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
             "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply only keeps legacy associated_resources input compatible",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
@@ -5055,7 +5443,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "upsert_views": [{"name": "项目台账视图", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
         "query_conditions_example": {
@@ -5176,6 +5564,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use patch_views for partial parameter replacement on existing views; the public update mode is patch even though the backend save is still a full view payload",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
+            "do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送; these are built-in system/default views. Use business-specific names for new views, and pass the existing raw view_key or patch_views when changing a built-in view",
             "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
             "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply keeps legacy associated_resources input compatible but it is no longer the recommended public contract",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
@@ -5185,7 +5574,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_key": "APP_KEY",
             "publish": True,
-            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "upsert_views": [{"name": "项目台账视图", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
         "query_conditions_example": {

package/src/qingflow_mcp/tools/record_tools.py

@@ -75,6 +75,22 @@ MAX_SUMMARY_PREVIEW_COLUMN_LIMIT = 6
 VERIFY_TASK_FALLBACK_PAGE_SIZE = 50
 VERIFY_TASK_FALLBACK_MAX_PAGES = 3
 BACKEND_LIST_SEARCH_FIELD_LIMIT = 10
+RECORD_WRITE_SYSTEM_FIELD_NAMES = {
+    "数据ID",
+    "编号",
+    "申请人",
+    "申请时间",
+    "创建人",
+    "创建时间",
+    "提交人",
+    "提交时间",
+    "更新时间",
+    "更新人",
+    "当前流程状态",
+    "当前处理人",
+    "当前处理节点",
+    "流程标题",
+}
 LOOKUP_RESOLUTION_MIN_SCORE = 0.92
 LOOKUP_RESOLUTION_MIN_MARGIN = 0.08
 LOOKUP_CONFIRMATION_CANDIDATE_LIMIT = 5
@@ -3649,6 +3665,7 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if items is not None:
             normalized_items = self._normalize_public_record_insert_batch_items(fields=fields, items=items)
+            self._reject_record_insert_system_fields([cast(JSONObject, item["fields"]) for item in normalized_items])
             return self._record_insert_public_batch(
                 profile=profile,
                 app_key=app_key,
@@ -3658,15 +3675,35 @@ class RecordTools(ToolBase):
             )
         if fields is not None and not isinstance(fields, dict):
             raise_tool_error(QingflowApiError.config_error("fields must be an object map keyed by field title"))
+        normalized_fields = cast(JSONObject, fields or {})
+        self._reject_record_insert_system_fields([normalized_fields])
         return self._record_insert_public_single(
             profile=profile,
             app_key=app_key,
-            fields=cast(JSONObject, fields or {}),
+            fields=normalized_fields,
             verify_write=verify_write,
             output_profile=normalized_output_profile,
             capture_exceptions=False,
         )
 
+    def _reject_record_insert_system_fields(self, field_maps: list[JSONObject]) -> None:
+        for row_index, field_map in enumerate(field_maps):
+            for field_name in field_map:
+                normalized_name = str(field_name or "").strip()
+                if normalized_name in RECORD_WRITE_SYSTEM_FIELD_NAMES:
+                    raise_tool_error(
+                        QingflowApiError.config_error(
+                            f"record_insert fields must not include built-in system field '{normalized_name}'",
+                            details={
+                                "error_code": "RESERVED_SYSTEM_FIELD_NAME",
+                                "row_number": row_index + 1,
+                                "field_name": normalized_name,
+                                "reserved_field_names": sorted(RECORD_WRITE_SYSTEM_FIELD_NAMES),
+                                "fix_hint": "Remove Qingflow built-in system fields from record_insert payload. They are generated by the platform and can be read after creation, not manually inserted.",
+                            },
+                        )
+                    )
+
     def _record_insert_public_single(
         self,
         *,