@josephyan/qingflow-app-builder-mcp 1.1.30 → 1.1.33

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

@@ -6,16 +6,17 @@ This playbook follows the current public builder surface, not legacy package hel
 Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
 
 1. read or create the package through `package_get` / `package_apply`
-2. create related apps together with one `app_schema_apply(apps=[...])`
+2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
-4. add relation fields between apps
+4. add same-call relation fields with `target_app_ref` when one new app references another new app; use `target_app_key` only after the target app already exists or readback confirms it
+5. choose explicit non-template `icon + color` for each new package/app
 
 Hierarchy reminder:
 
 - package -> app -> field -> relation
 - another business object is another app, not a text field
 
-If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, create it through `package_apply(create_if_missing=true, package_name=...)`.
+If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, create it through `package_apply(package_name=..., icon=..., color=...)`.
 
 ## Minimal sequence
 
@@ -36,12 +37,25 @@ then do not treat that as one app.
 
 Use this pattern instead:
 
-1. `package_get` or `package_apply(create_if_missing=true, package_name=...)`
-2. for a multi-app system, run one `app_schema_apply` with `apps[]`
+1. `package_get` or `package_apply(package_name=..., icon=..., color=...)`
+2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
 3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
+If that multi-app call times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, do not decide that the create failed. Run `readback_before_retry`: read the package, resolve each intended app by package/name or returned app key, read fields, and retry only verified missing apps or fields. Do not rebuild the same complete system as separate single-app creates, and do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
+
 ## Example
 
+When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.
+
+Field authoring rules:
+
+- Use intuitive field types in drafts: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`.
+- The tool normalizes aliases before writing: `multiline -> long_text`, `select -> single_select`, `checkbox -> multi_select`, `currency -> amount`, `mobile -> phone`. Readback may show canonical types; that is not a failed write.
+- Every new app must have exactly one top-level `as_data_title: true` field. `as_data_cover: true` is optional and only valid on a top-level `attachment`.
+- Select fields must define `options` during schema design. Options may be strings or objects such as `{"label": "进行中"}`; sample data must use those labels or ids.
+- Relation fields must use `target_app_ref` for same-batch apps or `target_app_key` for existing apps, plus object selectors: `display_field: {"name": "..."}` and `visible_fields: [{"name": "..."}]`. Do not write bare strings for display/visible field selectors.
+- Do not impose a one-relation-field-per-app limit. Model the real business links and let backend validation/readback decide.
+
 Create a new package only after the user confirms package creation:
 
 ```json
@@ -50,7 +64,8 @@ Create a new package only after the user confirms package creation:
   "arguments": {
     "profile": "default",
     "package_name": "研发项目管理",
-    "create_if_missing": true
+    "icon": "briefcase",
+    "color": "azure"
   }
 }
 ```
@@ -76,21 +91,16 @@ Apply schema for a new app:
     "profile": "default",
     "app_name": "客户订单",
     "package_id": 1218950,
-    "create_if_missing": true,
+    "icon": "delivery-box-1",
+    "color": "emerald",
     "publish": true,
     "add_fields": [
       {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
       {"name": "客户名称", "type": "text", "required": true},
       {"name": "订单封面", "type": "attachment", "as_data_cover": true},
       {"name": "订单金额", "type": "amount"},
-      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+      {"name": "状态", "type": "select", "options": [{"label": "草稿"}, {"label": "进行中"}, {"label": "已完成"}], "required": true}
     ],
-    "form": {
-      "sections": [
-        {"title": "基础信息", "rows": [["订单编号", "客户名称"], ["状态"]]},
-        {"title": "金额与附件", "rows": [["订单金额"], ["订单封面"]]}
-      ]
-    },
     "update_fields": [],
     "remove_fields": []
   }
@@ -105,24 +115,22 @@ Apply schema for multiple apps in one call:
   "arguments": {
     "profile": "default",
     "package_id": 1218950,
-    "create_if_missing": true,
     "publish": true,
     "apps": [
       {
         "client_key": "customer",
         "app_name": "客户",
-        "icon": "user-group",
-        "color": "blue",
+        "icon": "business-personalcard",
+        "color": "emerald",
         "add_fields": [
           {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
-        ],
-        "form": {"sections": [{"title": "基础信息", "rows": [["客户名称"]]}]}
+        ]
       },
       {
         "client_key": "order",
         "app_name": "订单",
         "icon": "delivery-box-1",
-        "color": "green",
+        "color": "blue",
         "add_fields": [
           {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
           {
@@ -132,8 +140,7 @@ Apply schema for multiple apps in one call:
             "display_field": {"name": "客户名称"},
             "visible_fields": [{"name": "客户名称"}]
           }
-        ],
-        "form": {"sections": [{"title": "基础信息", "rows": [["订单编号", "关联客户"]]}]}
+        ]
       }
     ]
   }
@@ -146,11 +153,11 @@ Data title is required: mark exactly one top-level field with `as_data_title: tr
 
 ### `APP_NOT_FOUND`
 
-Expected on create. Continue with `create_if_missing=true`.
+For new apps, submit `app_schema_apply` with `package_id + app_name + icon + color`. For existing apps, resolve and pass the real `app_key`.
 
 ### `CREATE_APP_ROUTE_NOT_FOUND`
 
-The create route did not resolve in the current backend route context. Re-run `workspace_select`, then retry the same `app_schema_apply`.
+The create route did not resolve in the current backend route context. In Wingent Momo runtime, first retry the same `app_schema_apply` after confirming the injected session is still active. Only run `workspace_select` if a business tool explicitly reports a missing or wrong workspace.
 
 ### Hierarchy modeling mistake
 

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

@@ -16,7 +16,7 @@ If the user did not specify an environment, default to `prod`.
 Use test for:
 
 - first application of a new `SolutionSpec`
-- trying `solution_build_all(..., verify=true)`
+- trying builder apply flows end-to-end with readback verification, or `solution_install` when the user is installing an existing packaged solution
 - package initialization and schema evolution experiments
 - mock data creation, with at least `5` records per relevant entity unless the user asks for fewer
 

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

@@ -3,7 +3,7 @@
 ## Auth and workspace
 
 - `auth_*` success does not mean a workspace is selected
-- Re-run `workspace_select` after auth changes or route changes
+- In Wingent Momo runtime, do not run `workspace_select` before builder work. Re-run it only after an explicit auth/route recovery or when a business tool reports the workspace is missing.
 
 ## Package ownership
 
@@ -17,13 +17,14 @@
 - Another app is not a field
 - If the user names multiple forms/modules that relate to each other, create multiple apps and connect them with relation fields
 - Do not use child app names like “项目/需求/任务/缺陷/团队” as plain text fields inside one app
+- For a complete system, the main creation path is one multi-app `app_schema_apply(package_id=..., apps=[...])` with stable `apps[].client_key` values and same-call relation fields using `target_app_ref`
+- Use `target_app_key` only for an app that already exists or has been confirmed by readback
 
-## Publish
+## Auto publish
 
-- Always pass `publish: true` explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` — do not rely on the default
-- Pass `publish: false` on those five tools only when the user explicitly wants to leave changes in draft
-- `app_associated_resources_apply` publishes after at least one write succeeds and does not accept a `publish` parameter
-- `app_charts_apply` is immediate-live and has no publish step
+- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default
+- For those four tools, pass `publish=false` only when the user explicitly wants to leave changes in draft
+- `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept `publish=false`
 - `app_publish_verify` is for explicit final verification, not the default next step after every write
 
 ## BI Reports
@@ -32,18 +33,29 @@
 - Use `app_associated_resources_apply` only when an existing BI report or view needs to appear in the Qingflow app associated-resource area or a specific view.
 - `app_charts_apply` currently creates/updates app-source BI reports only (`dataSourceType=qingflow`); dataset BI reports can only be attached when they already exist.
 - Creating a chart with `app_charts_apply` does not automatically show it in the Qingflow app UI; attach it separately if display is required.
+- Main chart config should use semantic `metric`, `metrics`, `group_by`, and `where`; avoid raw `indicator_field_ids`, `selectedMetrics`, and QingBI filter matrices unless diagnosing or preserving existing raw config.
 - `target` and `table` remain compatibility aliases for QingBI `indicator` and `detail`; use the real QingBI chart type when you need a specific type such as `summary`, `columnar`, `stacked_bar`, `scatter`, or `dualaxes`.
+- Use `app_get_fields.chart_fields` as the source for dimensions, metrics, and filters. Record schema fields or normal form fields are not enough for chart apply.
+- Use `target` / `indicator` for one metric card; do not use `summary` for a single KPI.
 
-## View actions
+## Custom buttons
 
-- Put business actions directly in the target view's `action_buttons`.
-- For add-data actions, use semantic `target_app_key`, `field_mappings`, and `default_values`.
+- For ordinary view-specific business buttons, use `app_views_apply` with `action_buttons`; do not use legacy `app_views_apply.buttons` unless you are maintaining an old full-replacement patch.
+- Use `app_custom_buttons_apply` for advanced button creation/update/removal and view placement: custom style/icon, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
+- When changing one existing button parameter, use `patch_buttons` with `set/unset`. Do not send a partial `upsert_buttons` object and expect the backend to preserve hidden required fields.
+- `addData` / `add_data` creates a related/downstream Qingflow record; use current-record `field_mappings` only on `detail` or `list`. `link` only opens a URL. `qRobot`/`wings` require user-provided exact config and must not be invented.
+- For add-data buttons, prefer semantic `trigger_add_data_config.target_app_key`, `field_mappings`, and `default_values`.
 - Do not handwrite raw `que_relation` unless you are preserving an existing backend config. If `field_mappings` and `que_relation` are mixed, the tool blocks the write.
 - `field_mappings.source_field` can use source app fields and supported system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`).
 - To fill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`. Use `default_values` only for static constants.
+- Do not put current-record `field_mappings` on a `header` button; `header` has no current row. Use `detail` or `list` for current-record add-data actions.
+- Do not model approval, rejection, close-task, or status transition as a generic `link` button. Use workflow/task behavior, or `qRobot`/`wings` only when the user provides existing automation config.
 - For field type compatibility, read `references/match-rules.md`.
-- Default button placements are `header` and `detail`; these map to the frontend's header and detail button areas.
+- Use `header` for global actions with no current-row context, `detail` for safest current-record actions, and `list` for row/list actions.
+- `view_configs[].buttons` is required in merge mode. Do not send a view config with only `view_key`; it is blocked to avoid no-op writes and accidental publish.
 - Builder view configs use raw `view_key` from `app_get.views[].view_key`; do not prefix it with `custom:`. The `custom:<viewKey>` form is for record-data `view_id`.
+- View button bindings merge by default. Use `view_configs[].mode="replace"` to replace the full set, or pass an explicit empty `buttons: []` when you intend to clear all custom button bindings for that view.
+- Advanced view button bindings can include `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls`, but keep ordinary buttons simple unless the user asks for conditional visibility or print templates.
 - `placement=list` configures row/list buttons. The tool maps it to the backend `INSIDE` button position, not a raw `LIST` config type.
 
 ## Associated resources
@@ -64,11 +76,18 @@
 
 ## Partial update discipline
 
-- Existing views, associated resources, and charts support the same public partial pattern: `patch_*[].set` plus optional `patch_*[].unset`.
+- Existing views use `app_views_apply.views[]` with `operation="patch"` plus `set` and optional `unset`; custom buttons, associated resources, and charts use their `patch_*[].set` plus optional `patch_*[].unset`.
 - The backend may still save a full payload. The MCP/CLI patch path is responsible for reading current config and preserving fields the user did not mention.
-- Do not use `upsert_views`, `upsert_resources`, or `upsert_charts` for a tiny parameter replacement unless you are deliberately providing the full desired target config.
+- Do not use view `operation="upsert"`, `upsert_buttons`, `upsert_resources`, or `upsert_charts` for a tiny parameter replacement unless you are deliberately providing the full desired target config.
 - `app_layout_apply(mode=merge)` is already a safe layout merge path; `mode=replace` is full layout replacement.
-- `portal_apply` without `sections` is base-info-only. Supplying `sections` replaces the portal sections list.
+- `portal_apply` without `sections` is base-info-only. Supplying `sections` replaces the portal sections list; use `patch_sections[]` for one-section updates.
+- PC portal layout is 24-column. Group components by the same `y`: all components in that row must have the same `rows`, and their `cols` should sum to 24 unless the user explicitly wants blank space.
+- Standard workbench heights: metric cards `rows=5`, BI charts `rows=7`, data views `rows=11`.
+- Business-entry `grid` sections must include real `config.items[]`; an empty grid container is not a valid business entrance.
+- Build portals only after referenced apps, raw `view_key`s, and chart ids/keys are known by readback. Intended names are not enough.
+- Use standard order: business entry -> metric cards -> BI charts -> concrete data views.
+- Do not use platform default views such as `全部数据` / `我的数据` as the main portal views.
+- Do not use portal `source_type: "filter"` as the normal automation path; it is raw/unstable and not part of the unified filter DSL.
 - `app_flow_apply` is intentionally replace-only for the public linear workflow graph.
 
 ## Workflow dependencies
@@ -85,15 +104,22 @@
 ## Retry discipline
 
 - If a write returns `partial_success`, read back before retrying
+- If multi-app schema apply times out, returns `write_executed=true`, returns `safe_to_retry=false`, or has incomplete readback, treat it as `write_may_have_succeeded`; the next action is `readback_before_retry`
+- `readback_before_retry` means read package/app/fields first, classify which intended apps and relation fields actually exist, and retry only the verified missing slice
 - Do not repeat create steps after `app_key` already exists
+- Do not split a complete-system schema create into single-app rebuilds until readback proves exactly what is missing
+- Do not bypass duplicate/conflict states by inventing `V2`, `测试`, timestamp, or random-suffix app names in a real business package
 - 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 `builder_tool_contract`, read the returned `json_paths` first. Successful contract data is under `$.contract`; `allowed_values` uses flat dotted keys such as `["field.type"]`, not nested objects. Do not read successful field enums from top-level `allowed_values`.
+- For `workspace_icon_catalog_get`, read icon candidates from `$.icon_names` and colors from `$.icon_colors`.
+- For builder apply responses, read returned `json_paths` first. Stable fields are `$.summary` and `$.resources[]`; use `resources[].id/key/name` before legacy top-level fields.
 - For layout `VALIDATION_ERROR`, also inspect `section_allowed_keys`, `section_aliases`, and `minimal_section_example`. If the same layout-shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_apply)`.
 - 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_get_views` and `app_views_apply` should all be read and written in that shape.
-- For existing view parameter changes, prefer `patch_views`. Example: to change only query-panel fields, set only `query_conditions`; the tool will preserve columns, filters, date config, card fields, buttons, and other backend-required fields.
+- For existing view parameter changes, prefer `views[]` with `operation="patch"`. Example: to change only query-panel fields, set only `query_conditions`; the tool will preserve columns, filters, date config, card fields, buttons, and other backend-required fields.
 - For layout work, treat `title + rows` as the only canonical public section shape. `fields`, `field_ids`, and `columns` may appear in legacy/internal shapes, but they are not the preferred public write shape.
 - A created view is not enough to claim a filter succeeded. When `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, treat the view as present but the filter as unverified.
 - If duplicate view names exist, do not retry by name. Read the exact `view_key` and target that one.

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

@@ -1,118 +1,229 @@
-# Builder Match Rules
+# Builder 统一筛选 / 条件写法
 
-Use this reference for builder-side field matching rules in view actions and associated view/report filters.
+本文适用于 Builder 侧所有给智能体公开的筛选和条件入口：
 
-This is not the same thing as `record_access` analysis filters or normal view `filters`.
+- 视图固定筛选：`builder views apply` 的 `filters`
+- 视图动作按钮显示条件：`action_buttons[].visible_when`
+- QingBI 图表筛选：`builder charts apply` 或 `portal apply sections[].chart.filters`
+- 关联视图 / 关联报表匹配：`builder associated-resource apply` 的 `match_mappings`
+- 新增下游记录传参：`field_mappings` / `default_values`
 
-## Where These Rules Apply
+它不是 `record_access` 分析筛选 DSL。数据分析仍走 `record access` 的 `where` 规则。
+流程条件属于 WorkflowSpec 路径：先读 `app_flow_get_schema` / `app_get_flow`，再按读回结构修改；不要把 raw workflow `autoJudges/judgeType` 混入视图、报表、关联资源的公共筛选 DSL。
 
-- `app_views_apply.views[].action_buttons[].field_mappings`
-- `app_views_apply.patch_views[].set.action_buttons[].field_mappings`
-- `app_associated_resources_apply.upsert_resources[].match_mappings`
-- `app_associated_resources_apply.patch_resources[].set.match_mappings`
+公开写法按场景选择，智能体不要混用。**operator 语义完全一致，区别只在字段名键**：
 
-Prefer semantic mappings. Do not handwrite raw `que_relation` or `match_rules` unless you are preserving an existing backend config.
+- **固定筛选**：`field_name + operator + value/values`
+- **关联资源上下文匹配**：`target_field + operator + source_field/value`
+- **新增数据传参**：`source_field + target_field`；静态默认值写 `default_values`
 
-## System Fields
+不要直接写 `judgeType`、`judgeValues`、`matchRules`、`beforeAggregationFilterMatrix`。CLI 会按目标协议自动编译，并在读回时还原为业务语义。
 
-System fields can participate in mappings:
+最短判断：
 
-- `数据ID`, `row_record_id`, `apply_id`, `_id` -> `field_id=-17`
-  This is the current record's real apply/record ID.
-- `编号`, `数据编号`, `record_number` -> `field_id=0`
-  This is the frontend-visible record number. It may be custom formatted and is not the same as `数据ID`.
+| 你想表达 | 写法 | 示例 |
+| --- | --- | --- |
+| 当前视图/图表只显示某类数据 | `filters` | `{"field_name":"状态","operator":"eq","value":"进行中"}` |
+| 关联报表/关联视图只显示“当前记录相关”的数据 | `match_mappings` + `source_field` | `{"target_field":"关联客户","operator":"eq","source_field":"数据ID"}` |
+| 关联报表/关联视图再加一个固定条件 | `match_mappings` + `value/values` | `{"target_field":"状态","operator":"eq","value":"有效"}` |
+| 从当前记录创建下游记录并带值 | `field_mappings` | `{"source_field":"数据ID","target_field":"关联工单"}` |
 
-Explicit selectors such as `{"field_id": -17}` and `{"field_id": 0}` are allowed and remove ambiguity.
+---
 
-## View Actions
+## 1. `operator` / `value` 统一规则
 
-Use `field_mappings` for dynamic values copied from the current source record:
+| `operator` | 含义 | `value/values` |
+| --- | --- | --- |
+| `eq` | 等于 | 单值用 `value` |
+| `neq` | 不等于 | 单值用 `value` |
+| `in` | 任一匹配 | 多值用 `values` |
+| `contains` | 包含 / 模糊包含 | 单值用 `value` |
+| `gte` | 大于等于 | 单值用 `value` |
+| `lte` | 小于等于 | 单值用 `value` |
+| `is_empty` | 为空 | 不写 `value/values` |
+| `not_empty` | 不为空 | 不写 `value/values` |
+
+`operator` 省略时按 `eq` 处理，但主示例必须显式写 `operator`。`value` 是单值主写法；`values` 是多值主写法。CLI 兼容 `value` 传数组、`values` 传单个标量，但不要把兼容形态当主示例。
+
+兼容别名：`equal`、`equals`、`=`、`==`、`!=`、`not_equal`、`any_of`、`one_of`、`include`、`like`、`empty`、`is null`、`not empty`、`not null`。主示例只写上表 canonical operator。
+
+### 1.1 不同字段类型的值写法
+
+默认优先写业务可读值，但要区分字段类型。选项字段（单选/多选/是否）在视图筛选、QingBI 筛选、关联资源静态筛选中均支持选项文本或 option id，CLI 会按目标协议自动转成 id 或文本。成员、部门、关联记录这类实体字段在固定筛选里优先写唯一 id 或 `{id,value}`；只有新增数据默认值、record 写入、候选解析类路径才先写名称，解析失败后再按候选改成 id。
+
+| 字段类型 | 推荐值写法 | 示例 |
+| --- | --- | --- |
+| 文本 / 长文本 / 手机 / 邮箱 | 字符串；模糊匹配用 `contains` | `{"field_name":"客户名称","operator":"contains","value":"上海"}` |
+| 数字 / 金额 | JSON 数字；范围用 `gte` / `lte` | `{"field_name":"金额","operator":"gte","value":10000}` |
+| 日期 / 日期时间 | 字符串；优先 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss` | `{"field_name":"计划日期","operator":"lte","value":"2026-06-30"}` |
+| 单选 | 选项文本或 option id；优先写文本；对象可写 `{id,value}` / `{optId,optValue}` | `{"field_name":"状态","operator":"eq","value":"进行中"}` 或 `{"field_name":"状态","operator":"eq","value":"160712876"}` |
+| 多选 | 多值用 `values`；每一项可写选项文本、option id 或选项对象 | `{"field_name":"标签","operator":"in","values":["重点","续约"]}` |
+| 布尔 / 是否 | 按字段实际选项文本写，通常是 `是` / `否` | `{"field_name":"是否逾期","operator":"eq","value":"是"}` |
+| 成员 / 部门 | 固定筛选写唯一 id 或 `{id,value}`；候选解析类写入路径可先写名称 | `{"field_name":"负责人","operator":"eq","value":{"id":123,"value":"沈嘉慧"}}` |
+| 关联记录 / relation | 固定筛选写目标记录真实 `record_id/apply_id`；当前记录跨应用匹配用 `source_field:"数据ID"` | `{"field_name":"关联客户","operator":"eq","value":"535734615263924225"}` |
+| 引用 / 数据填充字段 | 按读回展示类型写值；若本质来自选项字段，仍优先写展示文本 | `{"field_name":"客户等级","operator":"eq","value":"A"}` |
+
+字段值选择原则：
+
+- 选项字段：优先写选项文本，例如 `"正常"`；如果文本不唯一或来自读回，也可写 option id，例如 `"160712876"`。
+- 成员/部门：固定筛选优先写 id 或 `{id,value}`；record 写入、默认值等候选解析路径可先写名称，若返回 `needs_confirmation` 再按候选改成 id。
+- 关联/relation：固定筛选写目标记录真实 `record_id/apply_id`；跨应用当前记录匹配写 `source_field:"数据ID"`，不要写前端编号。
+- 引用/数据填充字段：按前端展示的业务值写；如果引用来源是选项字段，仍优先写选项文本。
+- 读回口径：`builder view/chart/associated-resource get` 优先返回业务文本和 canonical `operator`，不把后端数字 `judgeType`、option id、`matchRules` 作为智能体主输出。raw `config` 只用于诊断。
+
+空值判断示例：
 
 ```json
-{
-  "target_app_key": "WORKLOG_APP",
-  "field_mappings": [
-    {"source_field": "数据ID", "target_field": "关联员工"},
-    {"source_field": "员工名称", "target_field": "员工姓名"}
-  ],
-  "default_values": {
-    "状态": "待提交"
-  }
-}
+{"field_name": "完工日期", "operator": "is_empty"}
 ```
 
-Use `default_values` only for static constants. Do not use `default_values` as the preferred way to pass the current record.
+读回示例：
+
+```json
+{"field_name":"使用状态","operator":"eq","value":"正常"}
+{"target_field":"状态","operator":"in","values":["有效","待提交"]}
+```
+
+---
+
+## 2. 当前记录上下文匹配
 
-For an existing view, patch the view's action list through `patch_views[].set.action_buttons`:
+优先使用语义化映射，不手写后端 raw `que_relation` / `match_rules`。
+
+心智模型：**同一个 operator，同一套 value 规则；只是当前记录匹配要把 `field_name` 改成 `target_field`，并用 `source_field` 表示当前记录字段。**
+
+- 固定筛选当前资源自己的数据：`field_name + operator + value/values`
+- 用当前记录过滤另一个资源：`target_field + operator + source_field`
+- 给另一个资源加静态筛选：`target_field + operator + value/values`
+- 从当前记录创建下游记录时传值：`source_field + target_field`，不写 `operator`
+
+`operator` 和 `value/values` 的含义与 §1 完全一致。`operator` 省略时默认为 `eq`，但为了可读性，主配置仍推荐显式写出。
+不要把跨应用“当前记录匹配”写成 `filters`：`filters` 只筛当前视图/报表自己的数据；`match_mappings` 才表示“拿当前记录的某个字段去匹配另一个资源”。
+
+### 2.1 新增数据按钮
 
 ```json
-{
-  "view_key": "VIEW_KEY",
-  "set": {
-    "action_buttons": [
-      {
-        "text": "新建工时",
-        "action": "add_data",
-        "target_app_key": "WORKLOG_APP",
-        "field_mappings": [
-          {"source_field": "数据ID", "target_field": "关联员工"}
-        ],
-        "default_values": {
-          "状态": "待提交"
-        }
+[
+  {
+    "client_key": "add_worklog",
+    "button_text": "快捷添加工时",
+    "trigger_action": "addData",
+    "trigger_add_data_config": {
+      "target_app_key": "WORKLOG_APP",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联员工"},
+        {"source_field": "员工名称", "target_field": "员工姓名"}
+      ],
+      "default_values": {
+        "状态": "待提交"
       }
+    }
+  }
+]
+```
+
+`field_mappings` 表示从当前记录动态带值，不需要 `operator`；`default_values` 只表示静态默认值。
+
+### 2.2 关联视图 / 报表
+
+跨应用关联必须显式传 `target_app_key`。若关联的是当前应用自己的视图或报表，可以省略 `target_app_key`，CLI 会默认使用命令里的 `--app-key`。
+
+```json
+[
+  {
+    "client_key": "employee_worklogs",
+    "graph_type": "view",
+    "target_app_key": "WORKLOG_APP",
+    "view_key": "WORKLOG_VIEW",
+    "match_mappings": [
+      {"target_field": "关联员工", "source_field": "数据ID"},
+      {"target_field": "状态", "value": "待提交"}
     ]
   }
-}
+]
 ```
 
-## Associated Resources
+动态条件用 `source_field`；静态条件用 `value/values`。如果一个条件写了 `source_field`，就不要再写 `value/values`。
+
+`field_name` / `field` 可作为 `target_field` 别名；静态单值写 `value`，多值写 `values`，空值类 operator 不写值。
 
-Use `match_mappings` for associated view/report filters:
+跨应用 relation 最常见写法是把当前记录的数据 ID 匹配到目标应用的引用字段：
 
 ```json
-{
-  "graph_type": "view",
-  "target_app_key": "WORKLOG_APP",
-  "view_key": "WORKLOG_VIEW",
-  "match_mappings": [
-    {"target_field": "关联员工", "source_field": "数据ID"},
-    {"target_field": "状态", "value": "待提交"}
-  ]
-}
+{"target_field": "关联客户", "operator": "eq", "source_field": "数据ID"}
 ```
 
-Dynamic conditions use `source_field`; static conditions use `value`.
+这里 `target_field` 是被关联资源所在应用里的字段，`source_field` 是当前详情页这条记录里的字段。不要把它写成视图/报表 `filters`，也不要手写 `matchRules`。
 
-For an existing associated resource, put the same filter mapping under `patch_resources[].set`:
+如果 `target_field` 是目标应用中的引用 / relation 字段，最稳妥的当前记录匹配值是 `source_field: "数据ID"`，因为它表示当前记录真实 `record_id/apply_id`。不要用前端可见 `编号` 代替，除非目标字段本身就是文本/编号字段。
+
+示例：
 
 ```json
-{
-  "associated_item_id": 3497587,
-  "set": {
-    "match_mappings": [
-      {"target_field": "关联员工", "source_field": "数据ID"}
-    ]
-  }
-}
+{"target_field": "客户ID", "operator": "eq", "source_field": "数据ID"}
+{"target_field": "状态", "operator": "eq", "value": "有效"}
+{"target_field": "状态", "operator": "in", "values": ["有效", "待提交"]}
+{"target_field": "归档说明", "operator": "is_empty"}
+```
+
+---
+
+## 3. 系统字段
+
+系统字段可以参与匹配：
+
+| 写法 | field_id | 含义 |
+| --- | --- | --- |
+| `数据ID` / `row_record_id` / `apply_id` / `_id` | `-17` | 当前记录真实 record/apply ID |
+| `编号` / `数据编号` / `record_number` | `0` | 前端可见数据编号，可能是自定义编号 |
+
+也可以显式写：
+
+```json
+{"source_field": {"field_id": -17}, "target_field": "关联员工"}
+```
+
+注意：`数据ID` 和 `编号` 不是同一个东西。要把当前记录填入目标引用字段时，用 `数据ID`。
+
+---
+
+## 4. 类型兼容规则
+
+| 目标 / 源字段类型 | 可匹配对象 |
+| --- | --- |
+| 引用字段 | 同目标应用的引用字段，或当前源应用记录的 `数据ID(-17)` |
+| `数据ID(-17)` | 指向当前源应用的目标引用字段；也可匹配 ID 兼容的文本/数字字段 |
+| `编号(0)` | 文本、长文本、数字、金额、编号类字段 |
+| 成员字段 | 成员字段 |
+| 部门字段 | 部门字段 |
+| 单选 / 多选 / 布尔 | 选项类字段或静态选项值 |
+| 日期 / 日期时间 | 日期类字段互通 |
+| 文本 / 长文本 / 电话 / 邮箱 | 文本类字段互通 |
+| 数字 / 金额 | 数值类字段互通 |
+
+附件、子表、代码块、Q-Linker、地址字段默认不作为匹配字段。
+
+---
+
+## 5. 常见错误处理
+
+| 错误场景 | 下一步 |
+| --- | --- |
+| 字段不存在 | 重新 `builder app get --app-key APP_KEY fields` / `builder app get --app-key APP_KEY`，用准确字段标题或 `field_id` |
+| 类型不兼容 | 按上表换兼容的源字段 / 目标字段 |
+| 引用来源不一致 | 目标引用字段指向了别的应用；换成指向当前源应用的引用字段 |
+| 同时传 semantic 与 raw | 同一项里只能二选一：`field_mappings/match_mappings` 或 raw `que_relation/match_rules` |
+
+---
+
+## 6. 关联资源 ID 口径
+
+`associated_item_id` 是应用级关联资源池里的 `form_asos_chart.id`，最终口径来自：
+
+```bash
+qingflow --json builder app get --app-key APP_KEY
 ```
 
-## Type Compatibility
-
-- Relation fields: match another relation field with the same target app, or match `数据ID(-17)` when the target relation points to the current source app.
-- Record ID `数据ID(-17)`: can match relation fields that point to the current source app, or ID-compatible text/number fields.
-- Record number `编号(0)`: can match text, long text, number, amount, or another record-number field.
-- Member fields: only match member fields.
-- Department fields: only match department fields.
-- Option fields: single select, multi select, and boolean can match option-family fields or static option values.
-- Date fields: date and datetime can match each other.
-- Text fields: text, long text, phone, and email can match each other.
-- Number fields: number and amount can match each other.
-- Attachment, subtable, code block, Q-Linker, and address fields are not default match fields.
-
-## Error Interpretation
-
-- Field not found: re-read `app_get` or `app_get_fields` and retry with an exact title or `field_id`.
-- Type mismatch: choose a compatible source/target pair from the matrix above.
-- Reference source mismatch: the target relation field points to a different app; choose a relation field that points back to the current source app, or match a non-relation field.
-- Mixed raw and semantic modes: use either semantic `field_mappings/match_mappings` or raw `que_relation/match_rules`, never both in the same item.
+或同等 `app_get.associated_resources[].associated_item_id`。
+
+它不是 `chart_id`、`chart_key`、`view_key`。但新版 `builder associated-resource apply` 在部分入口可接受 `chart_id` / `chart_key` / `view_key` 作为 selector，并自动解析成后端需要的 `associated_item_id`；写 view config 或排障时仍以读回的 `associated_item_id` 为准。

package/skills/qingflow-app-builder/references/public-surface-sync.md

@@ -39,14 +39,14 @@ It is not a user-facing product spec. It exists to prevent skill drift.
   - `app_layout_apply`
   - `app_flow_apply`
   - `app_views_apply`
+  - `app_custom_buttons_apply`
   - `app_associated_resources_apply`
   - `app_charts_apply`
   - `portal_apply`
   - `app_publish_verify`
 - `portal_apply` edit mode may omit `sections` for base-info-only updates
 - `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
-- View actions are declared through `app_views_apply` `action_buttons`
-- Existing object parameter replacement should use `patch_views`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
+- Existing view parameter replacement should use `app_views_apply.views[]` with `operation="patch"`; existing buttons, resources, and charts should use `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
 - `app_get.editability` uses:
   - `can_edit_app_base`
   - `can_edit_form`