@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md

@@ -1,304 +1,58 @@
-# Builder 视图创建与变更 SOP：`qingflow builder views apply`
+# Builder Views Workflow (Legacy Redirect)
 
-稳定命令：**`qingflow builder views apply`**（别名 **`qingflow build views apply`**）。编写前已结合 **builder 契约**与实现要点整理；**最小可用 `upsert` 文件**见 **[views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)**（与门户/报表 **`.example.json`** 同风格）。已对应用 **`ead8ims5i401`** **实跑**该文件。
+This file is kept only for old cross-links. Use the current canonical document instead:
 
-> **权限**：视图**新建**走后端 `createViewgraphConfig`，需要同时满足 **视图管理 / ViewManagementAuth**（`beingViewManageStatus`）和 **数据管理 / DataManageAuth**；视图**更新/删除**只走 **ViewManagementAuth**。未开启高级应用权限时 `beingViewManageStatus` 等价回落到 **DataManageAuth**。失败时常见 **40002 / 40161 / 编辑锁**，参见主技能与 **ADMIN** 速查。
+- [builder/50-views.md](./builder/50-views.md)
 
-> **默认系统视图**：`全部数据`、`我的数据`、`我发起的`、`待办`、`已办`、`抄送` 等由轻流自带，**不要新建同名业务视图**。新建视图必须用业务名，例如 `项目台账视图`、`客户跟进视图`、`逾期任务看板`。如果确实要调整默认系统视图，只能从 `app get views` 取已存在的 raw **`view_key`** 后用 `patch_views` 或带 `view_key` 的 `upsert_views` 更新。
-
-> **契约**（权威键名、枚举、`execution_notes`、示例）：  
-> `qingflow --json builder contract --tool-name app_views_apply`  
-> （`--tool-name` 为契约索引，用于拉取 **`allowed_keys` / 别名 / 示例**。）
-> 契约示例若带 `"profile"`，不要复制到 `--upsert-views-file`；CLI 指定 profile 用根级 `qingflow --profile …`。
-
----
-
-## 1. 推荐操作顺序（读 → 写 → 校验）
-
-| 步骤 | 动作 | CLI |
-|------|------|-----|
-| ① 读应用地图 | 先看 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） | — |
-| ④ 应用视图补丁 | 执行 apply | `qingflow builder views apply …`（写入命令自动 JSON，默认直接 stdout；需要留档时用 `tee`） |
-| ⑤ 涉及关联/按钮 | 用专项 apply，不把它们塞进 view patch | `builder associated-resource apply` / `builder button apply` |
-| ⑥ 需要上线时 | 发布侧校验 | `qingflow builder publish verify --app-key …` |
-
-**说明**：`views apply` 的 **`--publish`** 对应契约里的 **`publish`**；自动化可先 **`--no-publish`**，与 schema/layout 改完再 **`publish verify`** 的节奏一致，见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)** 的发布校验章节。
-
----
-
-## 2. CLI 形态
+Current main path:
 
 ```bash
-qingflow builder views apply \
-  --app-key "<APP_KEY>" \
-  [--publish | --no-publish] \
-  [--upsert-views-file PATH] \
-  [--remove-views-file PATH]
-```
-
-- **`--upsert-views-file`** / **`--remove-views-file`**：各为 **JSON 数组**文件，与实现里 `load_list_arg` 一致；可只传其一或两者兼有。
-- 输出默认直接给 stdout，前端可直接读取；需要留档时用 `qingflow builder views apply … | tee tmp/builder_views_apply.json`。
-
----
-
-## 2.1 参考示例文件（与门户 / 报表同风格）
-
-| 文件 | 用途 |
-|------|------|
-| [views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json) | **新建 table 视图**最小 **`upsert_views` 数组**：`name` + `type` + **`columns`**（字段 **显示名**，须来自 **`builder app get --app-key … fields`**） |
-
-**本仓实测**（`ead8ims5i401`，`--no-publish`）：使用文件内 **`columns`**（`单行文字`、`多行文字`）与视图 **`name`** **`示例表视图_CLI模板`** 可 **`status: success` 创建**。复制到其他应用前务必 **`app get fields`** 替换 **`columns`**；**`name`** 重名时会 **更新** 已有同名视图而非新建（见 **§4**）。
-
----
-
-## 3. 请求体形状（与契约对齐）
-
-CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
-
-| 键 | 说明 |
-|----|------|
-| **`app_key`** | 必填 |
-| **`publish`** | 是否顺带发布语义（与 **`--publish` / `--no-publish`** 一致） |
-| **`upsert_views`** | 补丁对象数组（见 §4～§6） |
-| **`remove_views`** | 删除项数组（见 §7） |
-
-**别名**（契约 `aliases` 节选）：**`fields` / `column_names` → `columns`**；**`view_key` / `viewKey`**；**`tableView`→`table`**、**`kanban`→`board`** 等；**`filter_rules`→`filters`**；**`startField`→`start_field`** 等。
-
----
-
-## 4. 创建 vs 更新（`view_key` 与 `name`）
-
-服务逻辑概要：
-
-- **`remove_views`**：可传 raw **`view_key`** 或视图 **显示名 `name`**；显示名重名则 **`AMBIGUOUS_VIEW`**，须改用 `view_key`。
-- **`upsert_views`**：
-  - 若提供 **`view_key`**：对该视图做 **更新**（含类型变更等，仍受后端约束）。
-  - 未提供 **`view_key`**：若 **`name` 唯一** 匹配已有视图 → **更新**；否则 → **创建**。
-
-响应中的 **`verification.by_view[].status`** 会出现 **`created` / `updated`** 等；**`views_diff`** 汇总创建/更新/失败名单。
-
-**`partial_success`**：部分视图成功、部分失败时整体仍可能带成功信封，务必读 **`failed`** 与 **`execution_notes`**。
-
-**系统默认名禁止新建**：未提供 `view_key` 的 `upsert_views` 不要使用 `全部数据`、`我的数据`、`我发起的`、`待办`、`已办`、`抄送` 这类默认系统视图名。它们不是业务视图模板，而是平台默认对象；新业务视图用具体业务名。
-
----
-
-## 5. `type` 与各类型必填
-
-契约 **`view.type`**：**`table`** | **`card`** | **`board`** | **`gantt`**。
-
-| `type` | 列/字段要点 | 类型专属键 |
-|--------|----------------|------------|
-| **`table`** | **`columns`**（业务字段 **显示名**，须能在 **`app get fields`** 里找到） | — |
-| **`card`** | 同 table | — |
-| **`board`**（看板） | 列；且须 **`group_by`**（分组字段名） | **`group_by`** |
-| **`gantt`** | 列；须 **`start_field`**、**`end_field`**（通常为日期类字段名） | 可选 **`title_field`** |
-
-实现侧校验：对 **table/card**，若声明了 **`columns`**，在 **过滤系统列**后须 **至少保留一个**真实应用字段，否则报错——**不能**只用系统列名凑一列（系统列集合见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) §7.1**）。
-
----
-
-## 6. `filters` / `query_conditions` / `visibility` / `buttons`
-
-### 6.1 `filters`
-
-- 项形状：**`field_name`**、**`operator`**、**`values`**（或契约允许的 **`value`** 别名）。
-- **`operator`**：统一公共语义，推荐 `eq` / `neq` / `in` / `contains` / `gte` / `lte` / `is_empty` / `not_empty`；兼容 `equal` / `equals` / `=` / `!=` / `any_of` / `one_of` / `empty` 等别名（以契约为准）。
-- **`in` 等多值**：传 **列表**；**`value`** 为列表时可作别名。
-- **语义**：固定筛选条件，打开视图即生效。不要把前端查询栏字段写进 `filters`。
-- **内部编译**：视图、按钮显示条件、工作流条件会由 CLI 自动编译成 Qingflow 数字 `judgeType`，智能体不要手写 `judgeType` / `judgeValues`。
-
-示例：
-
-```json
-{"field_name": "状态", "operator": "eq", "value": "进行中"}
+qingflow builder views apply --views-file /abs/path/views.json
 ```
 
-### 6.2 `query_conditions`
-
-`query_conditions` 是前端“查询条件/查询栏”配置，和 `filters` 是两套语义：
-
-- `filters`：固定筛选，打开视图即生效。
-- `query_conditions`：只配置前端查询面板可输入哪些字段；用户输入查询值后才生效。
-- `rows` 是字段布局矩阵，不表示 OR 条件。
-- `rows` 只放前端查询面板支持的字段：文本、长文本、数字、金额、日期/时间、单选/多选、成员、部门、手机号、邮箱、布尔。
-- 不要把 relation、attachment、subtable/subfield、address、Q-Linker 或 code-block 字段放进 `query_conditions`。
-- 需要固定筛选时用 `filters`；需要关联报表/关联视图按当前记录匹配时用 `builder associated-resource apply` 的 `match_mappings`。
+Use one top-level `views[]` array. Each item carries its own `app_key` and `operation`.
 
-示例：
+Minimum current shape:
 
 ```json
 {
-  "name": "客户查询视图",
-  "type": "table",
-  "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
-  "filters": [
-    {"field_name": "客户状态", "operator": "eq", "value": "有效"}
-  ],
-  "query_conditions": {
-    "enabled": true,
-    "exact": false,
-    "hide_before_query": false,
-    "rows": [["客户名称", "负责人"], ["创建时间"]]
-  }
-}
-```
-
-读回验证时，不要只看视图是否存在；要看 `verification.view_query_conditions_verified=true`。若返回 query condition mismatch，只能说视图已创建/更新，但查询条件未完全验证。
-
-### 6.3 `visibility`
-
-与包/应用/视图等 **授权形态一致**（契约 **`visibility.mode`**：`workspace` | `everyone` | `specific`；**`external_mode`**：`not` | `workspace` | `specific`；**`selectors` / `external_selectors`** 键集合见契约）。
-
-- **更新已存在视图**：省略 **`visibility`** 可 **保留**当前后端权限。
-- **名称类 selector**：须 **唯一解析**，否则失败（不猜测）。
-
-### 6.4 `buttons`（兼容路径）
-
-新版默认不要通过 `app_views_apply.buttons` 配置自定义按钮。按钮本体、字段映射、默认值和头部/详情/列表位置统一走 **`app_custom_buttons_apply`** / CLI **`builder button apply`**。
-
-- `button_ref` 可以是同次按钮的 `client_key`，也可以是已有 `button_id`。
-- `view_configs[].view_key` 使用 raw `view_key`，不要加 `custom:`。
-- `view_configs[].mode` 默认 `merge`；merge 模式必须带 `buttons`，不要只传 `view_key`。清空绑定用 `mode: "replace"` 或显式 `buttons: []`。
-- 对外入参仍写 `placement=list`；CLI 会映射为后端 `INSIDE` 行内/列表按钮。
-- 按钮显示条件 `button_limit` 使用统一条件写法：`field_name + operator + value/values`。不要手写后端 `judgeType` / `judgeValues`。
-- 权限分界：按钮本体增删改需要 **EditAppAuth**；只要同次包含 `view_configs` 写视图按钮位置，还需要 **ViewManagementAuth**（未开启高级应用权限时回落到 **DataManageAuth**）。
-
-`app_views_apply.buttons` 仅作为旧配置维护兼容：
-
-- **省略**：保留现有按钮配置。
-- **`buttons: []`**：清空旧按钮配置。
-- **非空数组**：对旧按钮配置做全量替换。
-
-### 6.5 关联视图/报表
-
-新版默认不要通过 `app_views_apply.associated_resources` 配置关联资源。应用级关联资源池和视图展示开关统一走 **`app_associated_resources_apply`** / CLI **`builder associated-resource apply`**。
-
-- `builder views apply` **新建视图时默认开启详情页关联查看**：等价于 `asosChartVisible=true`、`limit_type=all`，会展示当前应用级关联资源池里的全部关联视图/报表。
-- **更新已有视图**：未显式传 `associated_resources` 时保留原关联查看状态；需要关闭或改成指定资源时，用 **`builder associated-resource apply --view-configs-file`**，或维护旧配置时显式 patch `associated_resources`。
-- 已有资源的最终口径是 `app_get.associated_resources[].associated_item_id`；它不是 `chart_id`、`chart_key` 或 `view_key`。
-- 新版 CLI 在关联报表时可先传 `chart_id` / `chart_key`，内部会解析为轻流后端需要的 id；创建前先检查是否已有相同 `target_app_key + view_key/chart_key`，已存在时用 `patch_resources`；`client_key` 只在同一次 apply 中可被 `associated_item_refs` 引用，不会持久化。
-- 数据集 BI 报表只能关联已有报表，使用 `report_source: "dataset"`；应用源报表可先用 `builder charts apply` 创建/更新。
-- 关联筛选优先用 `match_mappings`；字段匹配规则见 **[QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./QINGFLOW_CLI_BUILDER_MATCH_RULES.md)**。
-
----
-
-## 7. `remove_views`
-
-- 文件内容为 **JSON 数组**；元素可以是 raw **`view_key`**，也可以是唯一视图显示名。
-- 优先用 **`view_key`** 删除；显示名重名会导致 **`AMBIGUOUS_VIEW`**，需先在 **`app get views`** 里确认。
-- DELETE 发出后，工具会用单个 **`view_key`** 回读验证，而不是再读全量视图列表判断删除结果。
-- 删除结果看 **`verification.by_view[].delete_executed`**、**`readback_status`**、**`safe_to_retry_delete`**：
-  - **`readback_status=deleted`**：删除已验证。
-  - **`readback_status=unavailable`** 或 **`still_exists`**：删除请求已发出但回读未完全确认，**不要盲目重复删除**；稍后用 `builder app get views` 或对应视图详情确认。
-
----
-
-## 8. 契约示例（可复制为文件基底）
-
-**Table + `visibility`（`minimal_example` 节选）**：
-
-```json
-[
-  {
-    "name": "项目台账视图",
-    "type": "table",
-    "columns": ["项目名称"],
-    "visibility": {
-      "mode": "workspace",
-      "selectors": {},
-      "external_mode": "not",
-      "external_selectors": {}
-    }
-  }
-]
-```
-
-**Gantt（`gantt_example` 节选）**：
-
-```json
-[
-  {
-    "name": "项目甘特图",
-    "type": "gantt",
-    "columns": ["项目名称", "开始日期", "结束日期"],
-    "start_field": "开始日期",
-    "end_field": "结束日期",
-    "title_field": "项目名称",
-    "filters": [
-      {
-        "field_name": "状态",
-        "operator": "eq",
-        "value": "进行中"
-      }
-    ]
-  }
-]
-```
-
-**Table + 查询条件（节选）**：
-
-```json
-[
-  {
-    "name": "客户查询视图",
-    "type": "table",
-    "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
-    "query_conditions": {
-      "enabled": true,
-      "exact": false,
-      "hide_before_query": false,
-      "rows": [["客户名称", "负责人"], ["创建时间"]]
+  "views": [
+    {
+      "operation": "upsert",
+      "app_key": "APP_KEY",
+      "name": "订单跟进视图",
+      "type": "table",
+      "columns": ["订单编号", "客户名称", "状态", "负责人"],
+      "filters": [
+        {"field_name": "状态", "operator": "neq", "value": "已关闭"}
+      ],
+      "query_conditions": {
+        "enabled": true,
+        "rows": [["订单编号", "客户名称"], ["状态", "负责人"]]
+      },
+      "action_buttons": [
+        {
+          "text": "行内新建跟进",
+          "action": "add_data",
+          "target_app_key": "TARGET_APP_KEY",
+          "placement": "list",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联订单"}
+          ]
+        },
+        {
+          "text": "详情新建跟进",
+          "action": "add_data",
+          "target_app_key": "TARGET_APP_KEY",
+          "placement": "detail",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联订单"}
+          ]
+        }
+      ]
     }
-  }
-]
-```
-
----
-
-## 9. 实测记录（`ead8ims5i401`，`--no-publish`）
-
-内容与仓库 **[views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)** 一致（或历史探针名 **`CLI探针视图_可删`**）。
-
-**读视图**：
-
-```bash
-qingflow --json builder app get --app-key ead8ims5i401 views
-```
-
-**应用**：
-
-```bash
-qingflow builder views apply \
-  --app-key ead8ims5i401 \
-  --no-publish \
-  --upsert-views-file ./reference/views_upsert_table_minimal.example.json
+  ]
+}
 ```
 
-**结果摘要**（示例视图名 **`示例表视图_CLI模板`**）：`status: success`，`verification.by_view[0].status: created`，返回 **`view_key`**（如 **`ecdk22v65c02`**），`published: false`。
-
----
-
-## 10. 排障要点
-
-| 现象 | 处理 |
-|------|------|
-| 列校验失败 / 无有效业务列 | **`app get fields`** 核对 **`name`**；避免 `columns` 仅含 **§7.1 系统列** |
-| 重名视图 / 删错 | **`app get views`**；更新时带 **`view_key`** |
-| 过滤器未生效疑虑 | 看响应 **`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`** |
-| 部分失败 | 读 **`views_diff.failed`** 与契约 **execution_notes** 中 **partial_success** |
-| 权限/锁 | 同 [交付 SOP](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)（**`publish verify`**、编辑锁） |
-
----
-
-## 11. 交叉引用
-
-- [views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)（**table** 视图最小 **`upsert`**）
-- [SKILL.md](../SKILL.md)：builder 直接输出、鉴权顺序。
-- [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)：系统列、**`publish verify`**、整体交付阶段。
-- [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md)：CLI 覆盖与 **`view_id` vs `view_key`** 备忘。
+Do not use the old `--app-key + --upsert-views-file / --patch-views-file / --remove-views-file` shape as the normal agent path.

package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md

@@ -1,107 +1,16 @@
-# `app_schema_apply` / `builder schema apply`：字段类型与场景总表
+# Schema Apply Field Types And Scenarios
 
-> **口径**：`field.type` 枚举以 **`qingflow --json builder contract --tool-name app_schema_apply`**（及包内 `PublicFieldType`）为准；**形状校验**以 `qingflow_mcp` 的 **`FieldPatch`**（`builder_facade/models.py`）与 **`app_schema_apply` 编排**（`builder_facade/service.py`）为准。  
-> **CLI**：`qingflow [--profile NAME] builder schema apply [--app-key APP_KEY | 创建模式… | --apps-file 多应用对象] [--publish|--no-publish] [--add-fields-file …] [--update-fields-file …] [--remove-fields-file …]`；**`qingflow` 未在 PATH 时**可用 `npx @qingflow-tech/qingflow-cli` 前缀，并把 `--profile` 放在 `builder` 之前。
-> **新建应用主规则**：`add_fields[]` 里必须有且仅有一个顶层字段标记 `as_data_title: true`；数据封面可选，只能在顶层 `attachment` 字段标记 `as_data_cover: true`。
-> **权限**：包内新建应用按后端 `CreateAppBean` 链路只预检目标包 **AddAppAuth**；已有应用的字段/基础信息变更才走应用自身 **EditAppAuth**。
+This legacy entry is kept only as a compatibility pointer.
 
----
+Use the current builder schema document instead:
 
-## 1. 全部 `field.type`（19 种）
+- [builder/30-schema-fields.md](./builder/30-schema-fields.md)
 
-与契约一致时，搭建侧 **`add_fields[]` / `update_fields[]`** 可用类型为：
+Current main rules:
 
-| `type` | 说明（搭建语义） |
-|--------|------------------|
-| `text` | 单行文本 |
-| `long_text` | 多行文本 |
-| `number` | 数字 |
-| `amount` | 金额 |
-| `date` | 日期 |
-| `datetime` | 日期时间 |
-| `member` | 成员 |
-| `department` | 部门（可带 `department_scope`） |
-| `single_select` | 单选 |
-| `multi_select` | 多选 |
-| `phone` | 电话 |
-| `email` | 邮箱 |
-| `address` | 地址 |
-| `attachment` | 附件 |
-| `boolean` | 是否 |
-| `q_linker` | 远程查询 / 数据获取（**`q_linker_binding`**） |
-| `code_block` | 代码块（**`code_block_binding`** + 编译后的 `code_block_config`） |
-| `relation` | 关联记录（**`relation_mode`**：`single` \| `multiple`） |
-| `subtable` | 子表（**`subfields[]`**） |
-
-**`relation_mode`**：仅 **`relation`** 使用，取值为 **`single`** 或 **`multiple`**（多关联字段能力受 **`verification.relation_field_limit_verified`** 等约束，见交付文 §6）。
-
-### 1.1 智能体友好字段类型别名
-
-主路径可以写更符合直觉的字段类型；工具写入前自动归一化，读回和排障时仍使用 canonical 类型：
-
-| 智能体写法 | canonical 类型 |
-|------------|----------------|
-| `multiline` / `multiline_text` / `textarea` | `long_text` |
-| `select` / `single_choice` / `dropdown` | `single_select` |
-| `multi_select` / `multi_choice` / `multiple_choice` / `checkbox` | `multi_select` |
-
-完整映射以 `builder contract --tool-name app_schema_apply` 的 `$.contract.allowed_values["field.type_aliases"]` 为准。
-
----
-
-## 2. 按类型的必填 / 常用可选（写意图）
-
-| `type` | 通常必填 | 常见可选 / 约束 |
-|--------|----------|-----------------|
-| 标量与选择器 | `name` + `type`（+ 业务 `required` 等） | `description`、`required`；新建应用时其中一个顶层可读字段须 `as_data_title: true`；**`single_select` / `multi_select` 的 `options` 可用字符串数组或对象数组**，如 `["A", "B"]` 或 `[{"label":"A","value":"a"}]`，工具会归一化为选项文案 |
-| `department` | 同左 | **`department_scope`**：`mode: all \| custom`；`custom` 时 **`departments[]`**（含 `dept_id` 等） |
-| `relation` | **`target_app_key`**、**`display_field`**、**`visible_fields[]`** | **`relation_mode`**；目标应用元数据不可读时可多写 **`name`** 降级 |
-| `subtable` | **`subfields[]` 非空** | 子列递归同父级规则；更新已存在子列优先契约 **`subfield_updates`** |
-| `q_linker` | **`q_linker_binding`**：`inputs`、`request`、**`outputs[]` 每项须含 `target_field`**（能解析到本表单字段） | `request.url` 等须符合**租户/后端远程查询策略**；读回 JSON 可能**缺** `outputs[].target_field`，会导致本地再编译失败（见 §5） |
-| `code_block` | **`code_block_binding`**：`inputs`、`code`、**`outputs[]` + `target_field`**；代码体须能被规范识别 **`qf_output` 赋值** | **`auto_trigger`**、按钮文案；勿与 **`code_block_config.code_content`** 与 **`binding.code`** 冲突 |
-
-别名：契约会把 `title`/`label` 映射到 **`name`** 等；字段类型自然别名见 §1.1。
-
----
-
-## 3. `builder schema apply` 场景矩阵
-
-| 场景 | 必备 CLI 参数 | 说明 |
-|------|----------------|------|
-| 编辑已有应用 | `--app-key`；可选 `--no-publish` | **不要**与 `--package-id`、`--create-if-missing` 同用 |
-| 包内新建应用 | `--package-id`、`--app-name`（或 title 映射）、**`--create-if-missing`**；初始 `add-fields-file` 至少包含一个 `as_data_title: true` 字段 | 创建后可得到新 **`app_key`**（以响应为准） |
-| 多应用一次性新建 | `--package-id`、**`--create-if-missing`**、`--apps-file` | 应用包/系统里有 2 个以上应用，或同批应用之间有 `relation` 时使用；`--apps-file` 主写法为 `{package_id, apps}` 对象，raw apps array / singleton wrapper array 仅兼容；`apps[].client_key` 可被 `target_app_ref` 引用，`apps[].app_name` 可被 `target_app` 引用 |
-| 仅增字段 | `--add-fields-file`（JSON 数组） | 与 **`update_fields`/`remove_fields`** 可同次组合（以契约为准） |
-| 改字段 | `--update-fields-file` | 每项 **`selector`**（`name`/`que_id`/`field_id`）+ **`set`** |
-| 删字段 | `--remove-fields-file` | 每项至少 **`name`/`que_id`/`field_id`** 之一 |
-| 可见性（新建/部分元数据） | `--visibility-file` | `mode` / `external_mode` / `selectors` 见交付文 §3.2 |
-| 发布 | 默认或 `--publish`；探针常用 **`--no-publish`** | 与 **`app_publish_verify`** 配合 |
-
----
-
-## 4. 仓库示例文件（单一完整清单）
-
-| 内容 | 位置 |
-|------|------|
-| **19 种 `type` + `code_block` + `q_linker` + 1 个 `relation`（一次 `add_fields`）** | [schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json)（首字段已标记 `as_data_title`，附件字段已标记 `as_data_cover`；`relation.target_app_key` 须指向含「单行文字」「多行文字」的目标应用，默认 `ead8ims5i401`） |
-| **`q_linker_example` / `code_block_example`**（契约内置形状） | `ai_builder_tools.py` 中 `app_schema_apply` 合约 |
-| 最小新建字段（1 个 text 标题字段） | [schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json) |
-| 历史 scalar / complex 批测（可选） | [_batch_schema_scalar.json](./_batch_schema_scalar.json)、[_batch_schema_complex.json](./_batch_schema_complex.json) |
-
----
-
-## 5. 实跑结论
-
-**一次性新建应用**：`--package-id` + `--app-name` + `--create-if-missing` + [schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json) 是当前推荐示例；它已包含唯一数据标题和可选数据封面（`q_linker` 使用 `https://httpbin.org/get`，`relation` 指向可读模板应用 `ead8ims5i401`）。
-
-**一次性新建多个应用**：用 `builder schema apply --package-id <TAG_ID> --create-if-missing --apps-file tmp/apps.json`，其中 `tmp/apps.json` 主写法为 `{ "package_id": 123, "apps": [...] }`，每个 `apps[]` 写顶层 `icon + color`；`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`，须修复或删除该题。
-
-**排障**：`--json`；**`DUPLICATE_FIELD`**；**`MULTIPLE_RELATION_FIELDS_UNSUPPORTED`（49614）**。
-
-## 6. 交叉引用
-
-- 交付主流程（读场 / 改场 / 发布）：[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) **§6**（类型速查与 `relation`/`q_linker`/`code_block` 要点）。  
-- 记录读写 `kind`（与搭建 `type` 不同系）：[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)。  
-- 主技能：[../SKILL.md](../SKILL.md)。
+- New single-app creation uses `builder schema apply --package-id --app-name --form-file`.
+- New complete-system creation uses `builder schema apply --apps-file` with the single shape `{"package_id": 123, "apps": [...]}`.
+- New apps use `form` to express fields and form rows together.
+- Do not use `--create-if-missing`.
+- Do not impose a one-relation-field-per-app limit; create the relation fields the business model needs and rely on backend validation plus readback.
+- All field-type capability probes live under [examples/schema](./examples/schema/); probes are not business delivery templates.

package/skills/qingflow-cli/reference/builder/10-build-single-app.md

@@ -0,0 +1,57 @@
+# Build Single App
+
+Read this when the user asks to create or complete exactly one Qingflow app.
+
+## Scope
+
+Responsible for: package/app resolution, form schema, workflow only when requested or clearly needed, business views, sample data, and final verification.
+
+Not responsible for: multi-app relation modeling or a portal across several apps. Use [20-build-complete-system.md](./20-build-complete-system.md) when the user asks for a system, package, multiple modules, or cross-app relations.
+
+## Main chain
+
+```text
+package/app resolve -> schema apply with form -> workflow if requested/needed -> views with query_conditions/action_buttons -> insert 5 sample records -> publish/readback verify
+```
+
+If a new package is needed, create it with `builder package apply --config-file`. Package JSON should contain only `package_name + icon + color`.
+
+## Required reads by phase
+
+| Phase | Read |
+|-------|------|
+| Fields and app creation | [30-schema-fields.md](./30-schema-fields.md) |
+| Workflow | [90-workflow.md](./90-workflow.md) only when the user asks for approval, fill/copy, reminders, process routing, or task handling |
+| Views | [50-views.md](./50-views.md) |
+| Sample data | [../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) |
+| Final status | [99-publish-verify.md](./99-publish-verify.md) |
+
+## Demo files
+
+Use the examples as file bases, then replace placeholder app/package ids and business field names:
+
+| Resource | Example |
+|----------|---------|
+| Single app form schema | [schema_single_app_form_standard.example.json](../examples/schema/schema_single_app_form_standard.example.json) |
+| Business views | [views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json) |
+| Workflow, when needed | [workflow/README.md](./workflow/README.md) |
+
+## Completion standard
+
+- Exactly one top-level data title field exists.
+- Common business fields use canonical or supported intuitive aliases from [30-schema-fields.md](./30-schema-fields.md).
+- App creation uses `form` so fields and form sections/rows are submitted together.
+- New business views use business names, not default names such as `全部数据` or `我的数据`.
+- New business views must include `query_conditions` so users can search/filter from the frontend query panel.
+- New business views must include shortcut buttons through `action_buttons`; every core operating view configures both `placement: "list"` and `placement: "detail"` buttons.
+- Unless the user explicitly says not to create sample data, insert 5 realistic records after schema/views are ready.
+- Workflow may be skipped when no approval/fill/copy/reminder/process-routing requirement exists; mention that it was not requested instead of inventing a flow.
+- When workflow is configured, use `builder flow schema` + `builder flow get` first, then `builder flow apply --spec-file` for a full flow or `--patch-nodes-file` for a targeted update.
+- If a write returns `partial_success`, `write_executed=true`, `safe_to_retry=false`, timeout, or readback 40002, read back before retrying the write.
+
+## Stop or switch conditions
+
+- If the user names multiple business objects, modules, or cross-app relations, switch to [20-build-complete-system.md](./20-build-complete-system.md).
+- If an existing app with the same or very similar name appears and the user did not explicitly say update, extend, or create new, stop and ask which target to use.
+- If readback shows the requested app already has some resources, patch the verified gaps instead of recreating the app.
+- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names in a real business package.

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

@@ -0,0 +1,84 @@
+# Build Complete System
+
+Read this when the user asks for a complete business system, app package, multiple modules, or related apps.
+
+## Scope
+
+Responsible for: package creation/reuse decision, all app form schemas, cross-app relation fields, shared view/portal conventions, workflow where requested, and final verification.
+
+Not responsible for: single existing-app record CRUD. Use record documents from [../00-INDEX.md](../00-INDEX.md) for data work.
+
+## Main chain
+
+```text
+package apply/get -> schema apply --apps-file with apps[].form -> app readback -> workflow if requested/needed -> views with query_conditions/action_buttons -> insert 5 sample records per app -> portal with inline chart -> publish/readback verify
+```
+
+## Hard rules
+
+- Create related apps in one `builder schema apply --apps-file` call when possible.
+- New package config uses `package_name + icon + color`.
+- Use exactly one recommended apps-file shape: `{"package_id": 123, "apps": [...]}`.
+- Define each new app through `apps[].form`: form sections contain `rows`, rows contain field objects. This is both schema and form layout intent.
+- Do not use `add_fields` for new complete-system apps. Do not create a separate top-level `layout` object. Do not call `builder layout apply` after creation just to place the fields.
+- Use `apps[].client_key` and relation `target_app_ref` for same-batch relations. Do not create apps first just to get real `app_key`s, and do not use placeholder `target_app_key`s.
+- One app may contain multiple `relation` fields when the business model needs them.
+- 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.
+- If a same/similar package or app set already exists and the user did not say whether to extend, repair, replace, or create new, stop and ask. Do not start probing with new names.
+- If readback shows part of the requested system already exists, list existing apps/fields/views/charts/portal, identify gaps, and patch only the missing or incorrect slices.
+- Do not create default views such as `全部数据` or `我的数据`; those are platform defaults.
+- New business views must include `query_conditions`; do not create business views that only define columns, filters, and buttons but lack a frontend query panel.
+- New business views must include shortcut buttons through `action_buttons`; every core operating view must configure both `placement: "list"` and `placement: "detail"` buttons. Do not create core operating views that only contain columns and filters.
+- Build workflow only when the user asks for approval, fill/copy, reminders, process routing, task handling, or the business process clearly depends on it. Do not invent workflows just to make the system look complete.
+- When workflow is needed, use the complete flow chain: `builder flow schema`, `builder flow get`, then `builder flow apply --spec-file` for a full WorkflowSpec or `--patch-nodes-file` for targeted edits.
+- For portal charts, use one section `chart` field: write `{"chart_id":"..."}` to reuse an existing QingBI chart, or `{"app_key":"...","name":"...","chart_type":"...",...}` to create/update the needed chart inline.
+- Portal business-entry grid components must contain real entry items, not empty `config` or `items: []`.
+- Unless the user explicitly says not to create sample data, insert 5 realistic records for every new app after schema/views are ready and before final chart/portal verification.
+
+## Required reads by phase
+
+| Phase | Read |
+|-------|------|
+| App package and schema | [30-schema-fields.md](./30-schema-fields.md) |
+| Workflow | [90-workflow.md](./90-workflow.md) only when workflow is requested or clearly required |
+| Views | [50-views.md](./50-views.md) |
+| Sample data | [../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) |
+| Portal | [70-portal.md](./70-portal.md) |
+| Final status | [99-publish-verify.md](./99-publish-verify.md) |
+
+## Demo files
+
+Use these examples as file bases, then replace placeholder package/app/view keys and business field names:
+
+| Resource | Example |
+|----------|---------|
+| Multi-app schema, same-batch relations, and form layout | [schema_multi_app_form_relation_layout.example.json](../examples/schema/schema_multi_app_form_relation_layout.example.json) |
+| Business views with filters, query panel, and view-bound buttons | [views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json) |
+| Standard portal with inline QingBI charts and business views | [portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json) |
+| Workflow, when needed | [workflow/README.md](./workflow/README.md) |
+
+Schema command:
+
+```bash
+qingflow --json builder schema apply --apps-file /abs/path/apps.json > tmp/schema_apply_system.json
+```
+
+If the write returns timeout or partial success, first read back the package/apps/fields. Do not split the same payload into single-app retries unless readback proves only a specific app slice is missing.
+
+## Completion standard
+
+A complete system is not just several created apps. Before reporting completion, verify these items from readback:
+
+- Package exists, and its `package_id` is known.
+- Every core business object is a separate app with `app_key`, `app_name`, `icon`, `color`, and exactly one readable data title field.
+- Cross-app relation fields are present where the business model needs them; same-batch relations used `target_app_ref` during creation.
+- Core apps were created with `apps[].form`, so fields and readable form sections/rows were submitted together.
+- Core operating views exist and their `query_conditions` and `action_buttons` are verified; list-row buttons and detail-page buttons are both configured through the view.
+- Each new app has 5 realistic sample records unless the user explicitly skipped sample data.
+- Portal exists only after referenced apps and raw `view_key`s are known; chart sections use `chart` either with a verified `chart_id` or an inline QingBI chart definition; business-entry grids have non-empty `config.items[]`.
+- Workflow is verified only when requested or clearly required; otherwise report it as not requested/not configured.
+- Configured workflows are verified by `builder flow get` readback against the intended WorkflowSpec or `patch_nodes` change.
+- Final status follows [99-publish-verify.md](./99-publish-verify.md): distinguish completed, unverified, frontend visible, and needs follow-up.
+
+If workflow was not requested and not clearly required, report it as “not requested / not configured”, not as a missing resource.