@josephyan/qingflow-cli 1.1.15 → 1.1.17

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@1.1.15
+npm install @josephyan/qingflow-cli@1.1.17
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@1.1.15 qingflow
+npx -y -p @josephyan/qingflow-cli@1.1.17 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/skills/qingflow-cli/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 # Qingflow CLI 使用技能
 
-> **Skill 版本**：`qingflow-skills-2026.06.26.1`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.28.2`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
 
 **硬约束（必读）**：正文各节与文末「命令速查」中的命令**只作子命令形态索引**，不覆盖 JSON 结构、`--*-file` 键名、枚举全集、执行顺序与排障细节。凡工作**偏复杂**（多步串联、大块 payload、导入全链、**Builder 搭建向**（应用/schema/流程/布局/视图/门户/报表/按钮/关联资源的配置与发布、系统列与字段 `type`）、契约型 `apply`、按 schema 组织写入 payload、任务下钻与 `task action` 等），或你判断当前任务与「关联文件」里某篇所描述的内容**需求一致、场景相同或大体同类**，都应**先 Read 对应 `reference/...` 文档**，再结合 `qingflow … --help` 与 **[EXPLORATION_REPORT](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。**禁止**仅凭索引、习惯或类比去补参数、臆造字段名或推断服务端行为。**CLI 自动化场景只通过 `qingflow` 命令工作**；相关说明已按主题合并为本文档下的 `reference/` 子目录。**最终统计结论、分析报告、趋势/排名/比例/分布**统一走 **[record/analysis](./reference/record/analysis/README.md)** 的 `qingflow record access -> Python/pandas`。
 
@@ -180,7 +180,7 @@ qingflow --json auth whoami
 主链路是先读详情，再直接提交用户要求修改的 key/value。不要把 `record schema update` 当成更新前置步骤：
 
 1. **`record get`** → 拿 **`record_id`、当前值、fields[].title / field_id / kind**；已知前端/自定义视图时必须带同一个 **`--view-id`**。未知时 CLI 会先试默认 `system:all`，权限拒绝后再尝试可访问视图，但智能体仍优先从 `app get.accessible_views` 取 view。
-2. 智能体根据 `record get.fields[]` 和用户要求，组一个只包含待改字段的 JSON 对象（标题 → 值）。
+2. 智能体根据 `record get.fields[]` 和用户要求，组一个只包含待改字段的 JSON 对象（标题 → 值）。字段必须来自当前详情上下文的 `fields[]`；带 `--view-id` 时，视图隐藏的字段不要强写。若用户要求改的字段不在当前 `record get.fields[]`，先换到包含该字段的视图/详情上下文，或用 `record schema update` 做失败诊断。
 3. **`record update`** → **`--record-id` + `--fields-file`**，已知前端视图时同样带 **`--view-id`** 让 CLI 优先走该 view；批量用 **`--items-file`**（**`--dry-run` 仅批量**）。
 4. 只有字段范围不清、候选歧义、或 `record update` 失败时，才用 **`record schema update`** 诊断本条记录的 **`writable_fields / payload_template / available_update_routes`**；已知前端视图时同样带 **`--view-id`**，让诊断优先探测同一个详情页上下文。
 

package/skills/qingflow-cli/reference/builder/20-build-complete-system.md

@@ -11,7 +11,7 @@ Not responsible for: single existing-app record CRUD. Use record documents from
 ## Main chain
 
 ```text
-package apply/get -> schema apply --apps-file -> app readback -> layout -> workflow -> views -> charts -> buttons/resources -> portal -> publish/readback verify
+package apply/get -> schema apply --apps-file -> app readback -> layout -> workflow -> views with action_buttons -> charts -> associated resources / advanced buttons -> portal -> publish/readback verify
 ```
 
 ## Hard rules
@@ -19,8 +19,10 @@ package apply/get -> schema apply --apps-file -> app readback -> layout -> workf
 - Create related apps in one `builder schema apply --apps-file` call when possible.
 - Use the recommended apps-file shape: `{"package_id": 123, "apps": [...]}`.
 - Use `apps[].client_key` and relation `target_app_ref` for same-batch relations.
+- Relation selectors use object shape, not bare strings: write `display_field: {"name":"产品编码"}` and `visible_fields: [{"name":"产品名称"}]`. `target_app_ref` remains the same-batch app alias.
 - If schema apply times out or returns uncertain write state, perform readback before retrying. Do not recreate apps with `V2`, `测试`, or random suffixes.
 - Do not create default views such as `全部数据` or `我的数据`; those are platform defaults.
+- Core business views should consider 1-3 useful business buttons through `views apply.action_buttons`. Do not force buttons onto every view.
 - Portal business-entry grid components must contain real entry items, not empty `config` or `items: []`.
 
 ## Required reads by phase
@@ -32,8 +34,14 @@ package apply/get -> schema apply --apps-file -> app readback -> layout -> workf
 | Workflow | [90-workflow.md](./90-workflow.md) |
 | Views | [50-views.md](./50-views.md) |
 | Charts | [60-charts.md](./60-charts.md) |
-| Associated reports/views and buttons | [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) |
+| Advanced buttons and associated reports/views | [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) |
 | Portal | [70-portal.md](./70-portal.md) |
 | Final status | [99-publish-verify.md](./99-publish-verify.md) |
 
+## Button acceptance
+
+For complete systems, the final report must say whether business buttons were configured, which views they are visible on, and whether `verification.action_buttons_verified` plus `verification.view_button_bindings_verified` passed.
+
+Do not mark the system fully complete when the user asked for operational workflows but all core business views have no buttons and no reason is given. It is acceptable to skip buttons on read-only views, overview views, and charts/portal-only screens.
+
 For a longer example playbook, use [reference/legacy-playbooks/build-complete-system.md](./reference/legacy-playbooks/build-complete-system.md) only as supporting material.

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -104,6 +104,27 @@ Example patch:
 
 别名：契约会把 `title`/`label` 映射到 **`name`** 等；字段类型自然别名见 §1.1。
 
+### 2.1 `relation` 选择器形态
+
+`relation` 的目标应用可以用字符串键，但展示字段选择器必须写对象，不要写裸字符串：
+
+```json
+{
+  "name": "关联产品",
+  "type": "relation",
+  "target_app_ref": "product",
+  "relation_mode": "single",
+  "display_field": {"name": "产品编码"},
+  "visible_fields": [{"name": "产品名称"}, {"name": "产品线"}]
+}
+```
+
+允许的目标应用写法：同批多应用优先 `target_app_ref`，已知真实应用时用 `target_app_key`。如果返回 `display_field` / `visible_fields` 的 Pydantic 错误，通常是把选择器写成了字符串；只修这一段字段 payload，不要重建应用或改 app_key。
+
+### 2.2 工作流状态字段
+
+要启用工作流的应用，字段阶段就创建一个明确的业务状态单选字段，例如 `状态`、`处理状态`、`审批状态`、`工单状态`、`计划状态`、`报工状态`、`单据状态`。领域结果字段不等价于流程状态；例如质量场景的 `检验结论` 只能表达结果，仍建议另建 `处理状态` 用于流程节点、视图和报表。
+
 ---
 
 ## 3. `builder schema apply` 场景矩阵
@@ -138,7 +159,7 @@ Example patch:
 
 **一次性新建多个应用**：用 `builder schema apply --apps-file tmp/apps.json`，其中 `tmp/apps.json` 主写法为 `{ "package_id": 123, "apps": [...] }`，每个 `apps[]` 写顶层 `icon + color`；多应用模式默认按 `app_name` 创建或复用应用。`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用，`apps[].app_name` 可被 `target_app` 引用，工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径，尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景；不要为了拿 `app_key` 先逐个创建再二次补关联字段。
 
-**限制（平台硬性）**：每应用 **至多一个** `relation`；`--app-key` 向已有应用追加时须 **字段名不重复**、且 **不能**在已有 relation 上再增第二个。**`example.com`** 作 `q_linker` URL 易触发 **`46031`**，本清单改用 httpbin。**读回缺 `outputs[].target_field` 的 `q_linker`** 会拖死后续 `schema apply`，须修复或删除该题。
+**限制（平台硬性）**：`--app-key` 向已有应用追加字段时须 **字段名不重复**；`relation` 字段数量不做“每应用只能一个”的智能体侧限制，按后端实际校验和写后读回为准。**`example.com`** 作 `q_linker` URL 易触发 **`46031`**，本清单改用 httpbin。**读回缺 `outputs[].target_field` 的 `q_linker`** 会拖死后续 `schema apply`，须修复或删除该题。
 
 **排障**：`--json`；**`DUPLICATE_FIELD`**；**`MULTIPLE_RELATION_FIELDS_UNSUPPORTED`（49614）**。
 

package/skills/qingflow-cli/reference/builder/50-views.md

@@ -4,14 +4,14 @@ Read this when the task is about table/card/board/gantt views, fixed filters, qu
 
 ## Scope
 
-Responsible for: `builder views apply`, `upsert_views`, `patch_views`, `remove_views`, `columns`, `filters`, `query_conditions`, and view readback.
+Responsible for: `builder views apply`, `upsert_views`, `patch_views`, `remove_views`, `columns`, `filters`, `query_conditions`, `action_buttons`, and view readback.
 
-Not responsible for: creating associated report resources or buttons. Use [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) after the target views/charts exist.
+Not responsible for: creating associated report resources, deleting button bodies, cross-view button reuse maintenance, or complex qRobot/wings button setup. Use [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) for those advanced cases.
 
 ## Main chain
 
 ```text
-app get -> app get fields/views -> views apply -> associated-resource apply when needed -> app get/views readback
+app get -> app get fields/views -> views apply, with action_buttons when the view needs operations -> associated-resource apply when needed -> app get/views readback
 ```
 
 ## Update existing views
@@ -42,12 +42,12 @@ app get -> app get fields/views -> views apply -> associated-resource apply when
 |------|------|-----|
 | ① 读应用地图 | 先看 compact views/charts/buttons/associated resources | `qingflow --json builder app get --app-key <APP_KEY>` |
 | ② 读字段/视图 | 确认 **`columns`** / `query_conditions` 可用字段、核对 **`view_key`** | `qingflow --json builder app get --app-key <APP_KEY> fields` / `qingflow --json builder app get --app-key <APP_KEY> views` |
-| ③ 准备补丁 JSON | 写入 **`upsert_views` / `remove_views`** 数组文件（见 §3） | — |
+| ③ 准备补丁 JSON | 写入 **`upsert_views` / `patch_views` / `remove_views`** 数组文件（见 §3） | — |
 | ④ 应用视图补丁 | 执行 apply | `qingflow builder views apply …`（写入命令自动 JSON，默认直接 stdout；需要留档时用 `tee`） |
-| ⑤ 涉及关联/按钮 | 用专项 apply，不把它们塞进 view patch | `builder associated-resource apply` / `builder button apply` |
+| ⑤ 涉及按钮/关联 | 常规业务按钮随视图写 `action_buttons`；关联资源和高级按钮维护走专项 apply | `builder associated-resource apply` / `builder button apply` |
 | ⑥ 需要上线时 | 发布侧校验 | `qingflow builder publish verify --app-key …` |
 
-**说明**：`views apply` 的 **`--publish`** 对应契约里的 **`publish`**；自动化可先 **`--no-publish`**，与 schema/layout 改完再 **`publish verify`** 的节奏一致，见 **[99-publish-verify.md](./99-publish-verify.md)**。
+**说明**：`views apply` 的 **`--publish`** 对应契约里的 **`publish`**；不含 `action_buttons` 时自动化可先 **`--no-publish`**，与 schema/layout 改完再 **`publish verify`**。包含 `action_buttons` 时必须 `publish=true`，因为底层按钮写入会自动发布。
 
 ---
 
@@ -58,10 +58,11 @@ qingflow builder views apply \
   --app-key "<APP_KEY>" \
   [--publish | --no-publish] \
   [--upsert-views-file PATH] \
+  [--patch-views-file PATH] \
   [--remove-views-file PATH]
 ```
 
-- **`--upsert-views-file`** / **`--remove-views-file`**：各为 **JSON 数组**文件，与实现里 `load_list_arg` 一致；可只传其一或两者兼有。
+- **`--upsert-views-file`** / **`--patch-views-file`** / **`--remove-views-file`**：各为 **JSON 数组**文件，与实现里 `load_list_arg` 一致；可只传其中之一或组合传入。
 - 输出默认直接给 stdout，前端可直接读取；需要留档时用 `qingflow builder views apply … | tee tmp/builder_views_apply.json`。
 
 ---
@@ -85,6 +86,7 @@ CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
 | **`app_key`** | 必填 |
 | **`publish`** | 是否顺带发布语义（与 **`--publish` / `--no-publish`** 一致） |
 | **`upsert_views`** | 补丁对象数组（见 §4～§6） |
+| **`patch_views`** | 局部修改对象数组；常用于只补 `query_conditions`、`visibility` 或 `action_buttons` |
 | **`remove_views`** | 删除项数组（见 §7） |
 
 **别名**（契约 `aliases` 节选）：**`fields` / `column_names` → `columns`**；**`view_key` / `viewKey`**；**`tableView`→`table`**、**`kanban`→`board`** 等；**`filter_rules`→`filters`**；**`startField`→`start_field`** 等。
@@ -123,7 +125,7 @@ CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
 
 ---
 
-## 6. `filters` / `query_conditions` / `visibility` / `buttons`
+## 6. `filters` / `query_conditions` / `visibility` / `action_buttons`
 
 ### 6.1 `filters`
 
@@ -178,9 +180,78 @@ CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
 - **更新已存在视图**：省略 **`visibility`** 可 **保留**当前后端权限。
 - **名称类 selector**：须 **唯一解析**，否则失败（不猜测）。
 
-### 6.4 `buttons`（兼容路径）
+### 6.4 `action_buttons`（主路径）
 
-新版默认不要通过 `app_views_apply.buttons` 配置自定义按钮。按钮本体、字段映射、默认值和头部/详情/列表位置统一走 **`app_custom_buttons_apply`** / CLI **`builder button apply`**。
+设计业务视图时，同时声明这个视图上需要的业务操作按钮。常规按钮优先写在视图对象里，不要先建视图再单独找按钮工具补。
+
+创建视图时：
+
+```json
+{
+  "name": "生产工单执行视图",
+  "type": "table",
+  "columns": ["工单编号", "产品", "状态", "负责人"],
+  "action_buttons": [
+    {
+      "text": "开始生产",
+      "action": "link",
+      "url": "https://example.com/start",
+      "placement": "list",
+      "visible_when": [
+        {"field_name": "状态", "operator": "eq", "value": "待排产"}
+      ]
+    }
+  ]
+}
+```
+
+局部补按钮时：
+
+```json
+{
+  "view_key": "RAW_VIEW_KEY",
+  "set": {
+    "action_buttons": [
+      {
+        "text": "创建验收单",
+        "action": "add_data",
+        "target_app_key": "ARRIVAL_APP",
+        "field_mappings": [
+          {"source_field": "数据ID", "target_field": "关联工单"}
+        ],
+        "default_values": {"状态": "待验收"},
+        "placement": "detail"
+      }
+    ],
+    "action_buttons_mode": "merge"
+  }
+}
+```
+
+规则：
+
+- `action_buttons_mode` 默认 `merge`：新增/更新声明按钮并绑定到该视图，不清空已有按钮。
+- `replace`：替换该视图上的自定义按钮绑定；`action_buttons: []` + `action_buttons_mode: "replace"` 可清空视图按钮绑定，但不删除按钮本体。
+- `publish=false` + `action_buttons` 会被阻断为 `VIEW_ACTION_BUTTONS_REQUIRE_PUBLISH`。
+- 响应里同时看 `verification.views_verified`、`verification.action_buttons_verified`、`verification.view_button_bindings_verified`。
+- 按钮失败但视图成功时是 `partial_success`；按 `suggested_next_call` 重试，只重放失败视图的 `patch_views[].set.action_buttons`，不要重建视图。
+
+按钮类型：
+
+- `add_data`：从当前记录创建关联子记录，适合“创建验收单”“发起付款申请”“新增跟进记录”。
+- `link`：跳转外部系统、文档、帮助页。
+- `qRobot` / `wings`：仅在用户明确要求并提供配置时使用，不自动编造。
+
+不同视图的建议：
+
+- `table`：`header` 放全局入口，`list` 放行操作，`detail` 放当前记录上下文操作。
+- `board`：适合状态流转类按钮，必须配 `visible_when`。
+- `card`：优先 `detail`，谨慎使用 `list`。
+- `gantt`：默认只放 `header` / `detail`，不主推行内按钮。
+
+### 6.5 `buttons`（兼容路径）
+
+默认不要通过 `app_views_apply.buttons` 配置自定义按钮。该字段是旧视图按钮配置的全量替换兼容入口，不是智能体主写法。高级维护、删除按钮本体、跨视图批量重排、复杂 qRobot/wings 配置走 **`app_custom_buttons_apply`** / CLI **`builder button apply`**。
 
 - `button_ref` 可以是同次按钮的 `client_key`，也可以是已有 `button_id`。
 - `view_configs[].view_key` 使用 raw `view_key`，不要加 `custom:`。
@@ -195,7 +266,7 @@ CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
 - **`buttons: []`**：清空旧按钮配置。
 - **非空数组**：对旧按钮配置做全量替换。
 
-### 6.5 关联视图/报表
+### 6.6 关联视图/报表
 
 新版默认不要通过 `app_views_apply.associated_resources` 配置关联资源。应用级关联资源池和视图展示开关统一走 **`app_associated_resources_apply`** / CLI **`builder associated-resource apply`**。
 
@@ -313,7 +384,7 @@ qingflow builder views apply \
 | 过滤器未生效疑虑 | 看响应 **`verification.view_filters_verified`**；必要时再 **`app get views`** |
 | 查询条件未生效疑虑 | 看响应 **`verification.view_query_conditions_verified`**；不要把 `query_conditions` 当 `filters` |
 | 后端 **40038 / Object not exist** | 先读失败项 **`details.per_view_results[].details.field_level_diagnostics`** 与 **`recommended_minimal_retry`**。不要删除字段、不要重建应用；先按最小列重试，再逐步加非关键列/筛选。 |
-| 按钮/关联资源配置 | 按钮走 **`builder button apply`**；关联视图/报表走 **`builder associated-resource apply`** |
+| 按钮/关联资源配置 | 常规业务按钮随视图写 **`action_buttons`**；高级按钮维护走 **`builder button apply`**；关联视图/报表走 **`builder associated-resource apply`** |
 | 部分失败 | 读 **`views_diff.failed`** 与契约 **execution_notes** 中 **partial_success** |
 | 权限/锁 | 同 [publish verify](./99-publish-verify.md) 与 [app delivery reference](./reference/app-delivery-sop.md) |
 

package/skills/qingflow-cli/reference/builder/70-portal.md

@@ -122,6 +122,17 @@ mobile 写法固定按 **6 栅格**：通常 **`x=0, cols=6`**。如果只写了
 
 图表卡片过小时会返回 **`PORTAL_CHART_CARD_TOO_SMALL`**；指标卡按 **`pc.cols >= 6, pc.rows >= 5`** 校验，普通可视化图表按 **`pc.cols >= 8, pc.rows >= 7`** 校验。指标区图表建议写 `role: "metric"`；此时必须引用 `target` / `indicator` 图表，否则返回 **`PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH`**，应先用 `app_charts_apply` 创建缺失指标卡再组门户。标准工作台数量也会进入 `layout_diagnostics.standard_template_counts`：指标卡推荐 4-6 个、BI 图表 2-3 个、业务视图 1-2 个，超出或不足会返回 `PORTAL_STANDARD_*_COUNT_OUT_OF_RANGE`。
 
+#### 行布局数学规则（必须自检）
+
+显式写 `position.pc` 时，先按相同 `y` 把组件分成行，再逐行校验：
+
+- 同一行内所有组件 **`rows` 必须一致**；不要让 `rows=5` 的指标卡和 `rows=7` 的图表同处一个 `y`。
+- 同一行内组件按 `x` 从小到大排列，**`cols` 总和默认必须等于 24**；除非用户明确要求留白，否则不要出现 `cols_sum=6/8/12` 的短行。
+- 同一行内不要横向重叠：前一块的 `x + cols` 应等于后一块的 `x`。
+- 下一行 `y` 必须等于上一行 `y + max(rows)`；不要产生竖向重叠或无意义空洞。
+- 不允许孤立短行，例如单独一个 `x=0,y=9,cols=6,rows=5` 的指标卡。若只有一个组件占一行，应写 `cols=24`，或重排到完整行中。
+- 在提交 `portal apply` 前，按 `y -> cols_sum/rows/titles` 自检一次；`portal apply` 当前可能不会阻断所有视觉错位，智能体不能仅依赖 `safe_for_display=true`。
+
 ### 3.1.2 推荐门户模板：业务工作台
 
 默认按 **业务入口 → 核心指标 → BI 可视化 → 业务视图** 搭建。门户首屏应直接呈现可用工作台，不要做营销页、说明页或大面积装饰区。
@@ -129,7 +140,7 @@ mobile 写法固定按 **6 栅格**：通常 **`x=0, cols=6`**。如果只写了
 | 区域 | 推荐组件 | PC 布局 | 要点 |
 |------|----------|---------|------|
 | 顶部业务入口 | **`grid`** + 可选 **待办 `task`** | `grid x=0,y=0,cols=12,rows=4`；待办 `x=12,y=0,cols=12,rows=4` | `grid` 放 2-6 个核心业务入口；待办用于当前用户任务概览。当前公开 `portal apply --sections-file` 暂未支持 `source_type=task`，不要伪造；见下方边界说明。 |
-| 核心指标 | **`chart`** 指标卡 + `role: "metric"` | 4 张：`x=0/6/12/18,y=4,cols=6,rows=5` | 指标卡推荐高度 **5**。24 栅格下单卡最小 `cols=6`，所以一行 4 张最稳；如果要 5 个指标，拆成两行。 |
+| 核心指标 | **`chart`** 指标卡 + `role: "metric"` | 4 张：`x=0/6/12/18,y=4,cols=6,rows=5` | 指标卡推荐高度 **5**。24 栅格下单卡最小 `cols=6`，所以一行 4 张最稳。若业务给出 5 个指标，默认精选 4 个核心指标；确需展示 5 个时，补齐成平衡行（如扩展到 6 个，2 行 x 3 张，`cols=8,rows=5`），不要写 4+1 的孤立短行。 |
 | BI 可视化 | **`chart`** 图表 | 3 张：`x=0/8/16,y=9,cols=8,rows=7`；或 2 张：`x=0/12,cols=12,rows=7` | 可视化图表推荐高度 **7**，一行 2-3 个，1-2 行。 |
 | 业务数据视图 | **`view`** | `x=0/12,y=16,cols=12,rows=11`；或单表 `cols=24,rows=11` | 数据视图推荐高度 **11**，一行 1-2 个，1-2 行。只挂业务视图，不要创建或引用默认的 **全部数据 / 我的数据** 当主门户视图。 |
 
@@ -139,7 +150,8 @@ mobile 固定按 **6 栅格** 从上到下堆叠：通常所有组件 `x=0, cols
 
 - 公开 `sections-file` 稳定支持：**`grid` / `chart` / `view` / `text` / `link`**；`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理，不作为主路径。
 - **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状，不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`；只有工具后续显式支持 `task`，或维护者走 raw 门户写入链路时，才使用待办槽位。
-- 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)**。该示例使用当前公开 CLI 可稳定写入的组件，顶部先用一个业务入口 `grid` 占满 24 栅格；如果工具已支持待办组件，再把顶部拆成 `grid cols=12 + task cols=12`。
+- 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)**。这是唯一推荐复制的业务工作台布局模板：每一行 `cols_sum=24`，同行 `rows` 一致，下一行 `y` 连续。顶部先用一个业务入口 `grid` 占满 24 栅格；如果工具已支持待办组件，再把顶部拆成 `grid cols=12 + task cols=12`。
+- **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)** 和 **[portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json)** 仅用于组件能力探针，不作为业务门户布局模板；搭建正式门户时不要从这些探针推导布局。
 - `grid` 必须写 **`config.items[]`**；只写 `gridTitle` / `beingShowTitle` 会生成空入口容器，工具会返回 **`PORTAL_GRID_ITEMS_EMPTY`**。
 
 **待办组件 raw 形状参考**（仅用于工具实现对齐，当前不要作为 `--sections-file` 输入）：
@@ -258,9 +270,9 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
 | **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)**（**grid / text / link / view / chart**） | **`status: success`**，**`types: [2,4,5,9,10]`**，**`published: true`** |
 | 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**，**`delete_executed: true`**，**`readback_status: deleted`**，**`summary.removed: 1`** |
 
-**推荐工作台模板示例**：[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)
+**推荐工作台模板示例**：[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)。正式业务门户优先复制这个文件的行布局。
 
-**含 `filter` 的六类示例（`filter` 是否落库视环境/后端而定）**：[portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json)
+**组件探针示例**：[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)、[portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json)。它们用于验证组件形状和后端边界，不作为业务门户视觉布局模板；其中 `filter` 是否落库视环境/后端而定。
 
 ---
 

package/skills/qingflow-cli/reference/builder/80-buttons-associated-resources.md

@@ -1,12 +1,12 @@
 # Builder Buttons And Associated Resources
 
-Read this when the task mentions custom buttons, button visibility, add-data button mappings, associated views, associated reports, or current-record context matching.
+Read this when the task mentions advanced custom button maintenance, deleting button bodies, cross-view button reuse, complex qRobot/wings buttons, associated views, associated reports, or current-record context matching.
 
 ## Scope
 
-Responsible for: `builder button apply`, `builder associated-resource apply`, view button placement, associated view/report display config, `match_mappings`, and button add-data mappings.
+Responsible for: `builder button apply`, `builder associated-resource apply`, advanced view button placement maintenance, associated view/report display config, `match_mappings`, and button add-data mappings.
 
-Not responsible for: creating the target views or charts themselves. Create or verify them first through [50-views.md](./50-views.md) and [60-charts.md](./60-charts.md).
+Not responsible for: ordinary business buttons declared while creating or patching a view. For normal cases, write `action_buttons` inside `builder views apply`; see [50-views.md](./50-views.md).
 
 ## Main chain
 
@@ -16,10 +16,63 @@ app get -> app get views/charts/buttons/associated resources -> apply button or
 
 ## Custom buttons
 
+- For normal view-level business actions, prefer `builder views apply` with `action_buttons`.
+- Use this standalone button tool for advanced cases: deleting button bodies, reusing the same button across many views, bulk reordering bindings, changing style independently, or configuring qRobot/wings when the user provides exact config.
 - Use `upsert_buttons` for create/update and `patch_buttons` for small changes.
-- Use `view_configs` only after reading target `view_key`.
+- Use `view_configs` only after reading target raw `view_key`.
 - Use semantic conditions: `field_name + operator + value/values`. Do not handwrite raw `judgeType` or backend match matrices.
 - For add-data button field mappings, use target/source semantics, not raw backend ids, unless a contract explicitly requires ids.
+- If `button apply` returns `CUSTOM_BUTTON_APPLY_PARTIAL` / `VIEW_CUSTOM_BUTTON_READBACK_PENDING` while `custom_buttons_verified=true`, do not recreate the button. Run `builder app get --app-key APP views` and inspect the target view `buttons[]` for `button_type=CUSTOM` plus the expected `button_text` or `button_id`. Only reapply `view_configs` if the view binding is actually absent.
+
+Button actions:
+
+- `addData`: create a related child record from the current record. Use for “创建验收单”, “发起付款申请”, “新增跟进记录”.
+- `link`: jump to an external system, document, or help page.
+- `qRobot` / `wings`: use only when the user explicitly asks and provides configuration; do not invent agent/qRobot settings.
+
+Placement guidance:
+
+- `table`: `header` for global actions, `list` for row actions, `detail` for current-record context actions.
+- `board`: status transition buttons are appropriate; always configure `visible_when`.
+- `card`: prefer `detail`; use `list` cautiously.
+- `gantt`: prefer `header` or `detail`; avoid row/list buttons unless the user explicitly asks.
+
+Standalone example:
+
+```json
+{
+  "upsert_buttons": [
+    {
+      "client_key": "create_acceptance",
+      "button_text": "创建验收单",
+      "style_preset": "primary_blue",
+      "trigger_action": "addData",
+      "trigger_add_data_config": {
+        "target_app_key": "ARRIVAL_APP",
+        "field_mappings": [
+          {"source_field": "数据ID", "target_field": "关联工单"}
+        ],
+        "default_values": {"状态": "待验收"}
+      }
+    }
+  ],
+  "view_configs": [
+    {
+      "view_key": "RAW_VIEW_KEY",
+      "mode": "merge",
+      "buttons": [
+        {
+          "button_ref": "create_acceptance",
+          "placement": "detail",
+          "button_limit": [
+            [{"field_name": "状态", "operator": "eq", "value": "已完工"}]
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
 
 ## Associated views and reports
 

package/skills/qingflow-cli/reference/builder/90-workflow.md

@@ -16,6 +16,7 @@ contract -> app get fields -> app get flow -> member/role lookup -> flow apply -
 
 ## Recommended write path
 
+- Before applying a workflow, verify the app has an explicit business status select field such as `状态`, `处理状态`, `审批状态`, `工单状态`, `计划状态`, `报工状态`, or `单据状态`. Domain result fields are not enough by themselves: for example, `检验结论` should be paired with `处理状态`.
 - For normal agent-authored workflows, use the public path: `--nodes-file` + `--transitions-file`.
 - `--spec-file` is an advanced raw backend WorkflowSpec path. Do not put public node aliases such as `start` / `approve` / `end` into `--spec-file`.
 - Start from a preset when possible: `basic_approval` or `basic_fill_then_approve`.

package/skills/qingflow-cli/reference/builder/99-publish-verify.md

@@ -24,6 +24,7 @@ If a write returns any of these, do not immediately replay the same write:
 - `safe_to_retry=false`
 - readback unavailable
 - backend readback 40002 after a write
+- `VIEW_CUSTOM_BUTTON_READBACK_PENDING` after `custom_buttons_verified=true`
 
 Next action:
 
@@ -33,6 +34,8 @@ package get / app resolve / app get fields|layout|views|charts / portal get / pu
 
 Then patch only the missing or mismatched resources.
 
+For custom button view binding, verify through `builder app get ... views` before retrying: if the target view already shows a `CUSTOM` button with the expected text/id, treat the write as successful with delayed readback, not as a failed button creation.
+
 ## Final report requirements
 
 Always state:

package/skills/qingflow-cli/reference/builder/workflow/README.md

@@ -35,7 +35,7 @@
 在开始任何搭建操作前，按顺序确认以下条件：
 
 1. **应用存在性**：`qingflow --json app get --app-key <APP_KEY>` 成功返回
-2. **字段就绪**：`qingflow --json builder app get --app-key <APP_KEY> fields` 返回字段列表，确认业务建模所需字段（如单选框、成员、部门字段）均已存在
+2. **字段就绪**：`qingflow --json builder app get --app-key <APP_KEY> fields` 返回字段列表，确认业务建模所需字段（如单选框、成员、部门字段）均已存在；流程应用还需要明确的业务状态单选字段（如 `状态`、`处理状态`、`审批状态`、`工单状态`、`计划状态`、`报工状态`、`单据状态`），不要只用 `检验结论` 这类结果字段替代状态字段
 3. **未启用已有流程**（新建场景）：`qingflow --json builder app get --app-key <APP_KEY> flow` 查看 `enabled` 状态，若已有流程则为**更新模式**
 
 **不满足时的处理**：

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md

@@ -43,7 +43,7 @@
 说明：
 
 - **单选/多选**在对外 `kind` 上 **同是 `select`**；以 **`options` 是否存在 + 业务语义** 区分；多选写入用 **数组**。
-- **`scalar`** 是 **桶类型**：文本、数字、金额、日期、布尔等在对外展示上常同为 `scalar`，**具体校验以后端与预检为准**。
+- **`scalar`** 是 **桶类型**：文本、数字、金额、日期、布尔等在对外展示上常同为 `scalar`，**具体校验以后端与预检为准**。数字/金额能否写小数以 insert/update schema 的 `expected_format`、`example_value` 和实际错误为准；不要仅凭字段标题或 builder `number` 推断可写 decimal。
 - **`field_id=0`** 等系统列可能为 **`system`+只读**；不要写入 insert/update payload（见创建文档「系统维护字段」）。
 
 ---

package/skills/qingflow-cli/reference/examples/portal/portal_sections_all_types.example.json

@@ -72,7 +72,7 @@
       "pc": {
         "x": 0,
         "y": 8,
-        "cols": 12,
+        "cols": 24,
         "rows": 2
       },
       "mobile": {
@@ -113,7 +113,7 @@
       "pc": {
         "x": 0,
         "y": 18,
-        "cols": 12,
+        "cols": 24,
         "rows": 6
       },
       "mobile": {

package/skills/qingflow-cli/reference/examples/portal/portal_sections_five_types.example.json

@@ -67,7 +67,7 @@
       "pc": {
         "x": 0,
         "y": 6,
-        "cols": 8,
+        "cols": 24,
         "rows": 6
       },
       "mobile": {
@@ -112,7 +112,7 @@
         "x": 12,
         "y": 12,
         "cols": 12,
-        "rows": 2
+        "rows": 8
       },
       "mobile": {
         "x": 0,

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md

@@ -15,6 +15,6 @@ qingflow --json record insert --app-key <APP_KEY> --items-file tmp/records.json
 
 成员、部门、关联记录、选项、附件等特殊字段按 [record/insert/README.md](./insert/README.md) 写：先读 insert schema；部门/成员不能自造候选；选项值必须来自 schema `options` 的文本或 id；关联记录批量写入优先 `record_id`，自然名称只在唯一匹配时使用；附件先上传再写返回值。
 
-追加样例数据时也必须 schema-first：按 `required_fields` 补齐必填；按 `expected_format/example_value` 选择数值、金额、日期等格式；按 `options` 生成选项值。不要按业务常识自造“正常/已完成/高优先级”等 schema 里不存在的选项。比例、完成率、评分、百分比等字段也按 schema 示例写；如果字段被建成金额/整数类而不接受小数，不要强塞 decimal，改用符合 schema 的整数值，或回到 builder 阶段把字段建模为 `number`。
+追加样例数据时也必须 schema-first：按 `required_fields` 补齐必填；按 `expected_format/example_value` 选择数值、金额、日期等格式；按 `options` 生成选项值。不要按业务常识自造“正常/已完成/高优先级”等 schema 里不存在的选项。比例、完成率、评分、百分比等字段也按 schema 示例写；即使 builder 字段类型看起来是 `number`，写入时仍以 insert schema 的 `expected_format` 为准。若返回 `INVALID_AMOUNT_VALUE`、`requires an integer amount`、或 schema 显示 `allow_decimal=false`，只修失败行，把小数改成整数，或回到 builder 阶段重建为允许小数的字段；不要强塞 decimal，也不要重试整批已成功行。
 
 录入数据时不要填写轻流系统字段：`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。这些字段由平台生成；需要确认时在创建成功后读取记录详情，不要把它们写进 `fields` / `items[].fields`。

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md

@@ -49,6 +49,8 @@ qingflow --json record get \
 
 `record_get` 的 `unavailable_context[]` 是辅助上下文提示：`detail_schema` / `audit_info` / 首屏日志等 40002 不等于记录详情读取失败。只要顶层 `status=ok` 且 `fields[]` 中已有目标字段，就按这些字段组 `record update` 的 key/value；只有顶层失败才按失败原因排查。
 
+`record update` 的字段集合应是当前 `record get.fields[]` 的子集。带 `--view-id` 时，当前前端详情/视图隐藏的字段不要强写；字段不在 `fields[]` 中时，先切到包含该字段的视图/详情上下文，或用 `record schema update` 诊断可写字段和失败路径。`FIELD_NOT_FOUND` 通常表示当前更新上下文没有这个题，不等于整条记录不可编辑。
+
 **2）如果缺 `record_id`，先定位候选**
 
 ```bash
@@ -86,6 +88,8 @@ qingflow --json record schema update \
 
 **`tmp/qingflow_patch_fields.json`**：JSON **对象**，键为 **题目标题**（优先来自 `record get.fields[]`），**只放需要修改的键**；值类型与 **新建** 相同（成员、部门、附件等见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**）。实现要求 **`fields` 为「按标题索引的 map」**（与 `record insert` 一致）。
 
+不要把 schema 中见过但当前 `record get.fields[]` 没出现的隐藏字段直接放进 `fields-file`。这会让智能体把视图上下文问题误判成权限或字段不存在问题。
+
 **特殊字段值**：
 
 - **成员字段 `kind=member`**：先传自然语言字符串，如 `{"客户成功":"周颖"}`。若返回 `status="needs_confirmation"`，说明尚未写入；从 `confirmation_requests[].candidates[]` 选一项，改传显式对象，如 `{"客户成功":{"uid":1048599,"name":"沈嘉慧Seth","email":"shenjiahui@exiao.tech"}}`。

package/skills/qingflow-cli/reference/record/insert/README.md

@@ -34,6 +34,7 @@ Default to batch-shaped insert. A single new record is `items` with one row.
 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 `data.normalized_record`
 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. For numeric / amount-like fields, follow insert schema `expected_format` and `example_value`, not the builder field name alone. If the schema or error says decimals are not allowed, retry only the failed row with an integer value.
 
 ## Field Notes
 
@@ -48,6 +49,7 @@ Default to batch-shaped insert. A single new record is `items` with one row.
 - `linkage.role=auto_fill_only` means "normally do not hand-fill this unless the product explicitly requires it"
 - `requires_upload=true` means upload the file first, then write the returned value
 - `failed_fields[].next_action` tells the next repair step for that row
+- `allow_decimal=false` or errors like `requires an integer amount` mean the current write path wants an integer even if the business label says hours, rate, or score
 
 ## CLI Pattern
 
@@ -73,3 +75,4 @@ qingflow record insert --app-key APP_KEY --items-file records.json --json
 - 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
 - Do not bind logic to a transient nested schema serialization detail when the field title and parent table already identify the legal payload shape
+- Do not infer decimal support from the field label or builder type; the insert schema is the write contract

package/skills/qingflow-cli/reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md

@@ -4,6 +4,8 @@
 
 **必须落盘**：`task` 的 `list`、`get`、`log`、`report` 以及 `**task action` 的响应**若体积大，均应 `> tmp/qingflow_*.json`，与主技能 [SKILL.md](../../SKILL.md) 一致。
 
+**输出解包**：`task list/get/log/report` 的主数据通常在 `data` 下，不要求有顶层 `status`。没有顶层 `status` 不代表失败；先检查是否有错误字段，再按 `task list -> data.items[]`、`task get -> data.task / data.available_actions`、`task log -> data.items[]`、`task report -> data` 解包。
+
 ---
 
 ## 1. 编排顺序（固定）