@josephyan/qingflow-cli 1.0.11 → 1.1.2

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

@@ -0,0 +1,485 @@
+# Builder 应用交付重流程 SOP：分组 → 应用定位 → 读场 → 改场 → 发布校验
+
+本文对齐 **MCP / AiBuilder** 工具链命名，并给出 **稳定 CLI**（`qingflow builder` / `qingflow build`）等价写法。编写前已 **阅读** `qingflow_mcp` 中 `builder_facade/service.py`、`cli/commands/builder.py`、`ai_builder_tools.py`，并对 **`ead8ims5i401`** **实跑**：`app resolve`、`app get fields|layout|flow`、`publish verify`。
+
+> **权限**：应用基础信息（`app_name` / 图标 / 可见性）、表单、流程、自定义按钮本体、应用级关联资源池走 **应用搭建 / EditAppAuth**；视图更新/删除、按钮的视图位置配置（`view_configs`）和视图内关联资源展示配置走 **视图管理 / ViewManagementAuth**（后端 `beingViewManageStatus`；未开启高级应用权限时等价回落到 DataManageAuth）；**新建视图**额外需要 **DataManageAuth**；报表走 **数据管理 / DataManageAuth**。失败码常见 **40002 / 40161 / 编辑锁** 等，见主技能与 **ADMIN** 速查。
+
+> **契约**：各 `app_*_apply` 的 **`allowed_keys` / `allowed_values` / `execution_notes` / 示例** 以在线为准，命令：
+> `qingflow --json builder contract --tool-name <app_schema_apply|app_layout_apply|app_flow_apply|app_views_apply|app_custom_buttons_apply|app_associated_resources_apply|app_publish_verify>`
+>
+> **CLI 文件载荷注意**：契约示例里可能出现 `"profile": "default"`，那是请求上下文示例；使用 CLI 的 `--*-file` 时不要把 `profile` 写进 JSON 文件。需要指定账号上下文时用根级参数：`qingflow --profile default ...`。
+>
+> **输出口径**：builder 读取命令仍显式加 `--json`；builder 写入/apply 命令默认直接输出 JSON 到 stdout，写入/apply 示例不再额外加 `--json`。如果需要留档，用 `| tee tmp/builder_*.json`，不要用 `>` 吞掉前端可捕获的 stdout。写入结果优先读统一 envelope：`operation` 表示本次动作，`summary` 表示总数/成功失败/发布校验，`resources[]` 表示资源卡片；每个资源统一有 `resource_type`、`operation`、`status`、`id`、`key`、`name`、`ids`、`parent`、`error_code`、`message`。旧字段如 `field_diff`、`views_diff`、`chart_results` 只作兼容和排障。
+>
+> **写后回读**：若 builder 写入结果为 `status=partial_success`，但同时有 `write_executed=true` / `safe_to_retry=false`，表示写动作已执行或可能已执行，问题在最终回读、发布校验或元数据确认。`package apply/update`、`schema apply`、`portal apply` 常见这种形态：`verification.readback_unavailable=true`、`details.*readback_error.backend_code=40002`、命令超时或响应只包含 partial/readback 不完整，都不等于写失败；下一步固定是 **`readback_before_retry`**，最终对用户应说明“写入已执行，回读待确认”，不要重复提交同一写动作。
+> 旧的 solution/build 编排同样遵循该语义：包挂载、门户更新或门户发布之后，若只剩回读 40002，会以 `partial_success` 和 artifacts 中的 `readback_status=unavailable` 表达，不应盲目重放写动作。
+
+---
+
+## 1. 推荐阶段顺序（与工具名对齐）
+
+| 阶段 | MCP / 编排常用名 | 稳定 CLI（有则列出） | 作用 |
+|------|------------------|----------------------|------|
+| A | **`package_list`** | `qingflow --json builder package list [--query <关键词>]` | 列出当前 Builder 权限可见的应用包，返回 **`package_id/package_name`**、包权限和应用数量 |
+| A′ | **`package_resolve`** | 不再作为 CLI 默认入口；用 `package list --query` 后人工/智能体确认 `package_id` | 同名包、空包都以 `package_list` 返回为准 |
+| B | — | `qingflow builder package get --package-id <N>` | 已知 **数字 `package-id`**（即 `tag_id`）时读包详情 / 配置上下文 |
+| C | **`app_resolve`** | `qingflow builder app resolve --app-key …` **或** `--app-name … --package-id …` | 在包内按名解析应用，或按 **`app_key`** 校验存在性 |
+| D | **`app_get` / `app_get_fields`** | `qingflow --json builder app get --app-key <APP_KEY>` / `qingflow --json builder app get --app-key <APP_KEY> fields` | 默认 `app_get` 是应用地图，含字段摘要、视图、图表、自定义按钮和关联资源池；`fields` 只读表单可搭建字段 |
+| D | **`app_read_layout_summary`** | `qingflow --json builder app get --app-key <APP_KEY> layout` | 读 **布局**（段落、`rows` 字段名矩阵、`unplaced_fields`） |
+| D | **`app_read_flow_summary`** | `qingflow --json builder app get --app-key <APP_KEY> flow` | 读 **流程**是否启用、节点摘要（公开面能力有限） |
+| E | **`app_schema_apply`** | `qingflow builder schema apply …` | 增删改 **字段**；单应用新建；多应用/应用包新建用 `--apps-file` |
+| F | **`app_layout_apply`** | `qingflow builder layout apply …` | **段落 / 行 / 单元格** 摆放字段 |
+| G | **`app_flow_apply`** | `qingflow builder flow apply …` | **线性流程** 节点与转移（见契约限制） |
+| G′ | **`app_custom_buttons_apply`** | `qingflow builder button apply …` | 创建/更新/删除自定义按钮，并配置头部/详情/列表位置 |
+| G″ | **`app_associated_resources_apply`** | `qingflow builder associated-resource apply …` | 管理应用级关联视图/报表池，并配置视图详情侧边栏展示 |
+| H | **`app_publish_verify`** | `qingflow builder publish verify --app-key …` | 确认 **已发布**、包挂载、视图等校验位 |
+
+**说明**：**`app_charts_apply`**（CLI **`builder charts apply`**）不在上表骨架内，但同属交付闭环；详见 **[QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)**；**视图**、**门户** 见同目录另文；其余另读 **`builder contract --tool-name …`**。`app_custom_buttons_apply` 与 `app_associated_resources_apply` 有成功写入时会自动发布，不暴露 draft-only `publish` 参数。
+
+---
+
+## 2. 分组阶段：`builder package list` → `builder package get`
+
+默认使用应用包后端列表，不再从 `app list` 曲线推断：
+
+```bash
+qingflow --json builder package list --query "产品研发"
+```
+
+读取返回：
+
+- `items[].package_id`：后续 `package get` / 新建应用挂包要用的数字 ID。
+- `items[].package_name`：展示名；可能重名，不能单独当唯一键。
+- `items[].item_count`：包内应用/门户/分组数量摘要，空包也能显示。
+- `items[].permissions`：当前账号对该包的可操作权限。
+- `matched_count / unfiltered_count / filter_mode`：判断关键词过滤结果。
+
+然后读详情：
+
+```bash
+qingflow --json builder package get --package-id <package_id>
+```
+
+**不要**用 `app list` 代替 `package list`：`app list` 只代表当前用户可见应用，不能代表空包、同名包、包级权限或完整包结构。
+
+### 2.1 仅有 **`app_key`**（无包名场景）
+
+若已知道任意挂载在该包下的应用：**直接**
+`qingflow --json builder app resolve --app-key "<APP_KEY>"` → **`package_ids`**。
+（与 **`publish verify`** 回包里的 **`package_ids_after`** 可交叉核对。）
+
+### 2.2 限制（务必读）
+
+| 情况 | 说明 |
+|------|------|
+| **同名多包** | `package list --query` 可能返回多个同名包；必须用 `package_id/item_count/permissions` 继续确认。 |
+| **无权限** | 后端 40002 会返回 `PACKAGE_LIST_FAILED`；不要自动改用 `app list`，那会改变权限口径。 |
+| **关键词未命中** | 看 `matched_count=0` 和 `unfiltered_count`；必要时去掉 query 获取全包列表。 |
+
+### 2.3 旧版 CLI fallback
+
+如果所在环境仍没有 `qingflow builder package list`，才使用 `scripts/builder-package-from-app-list.py` 从 `app list` 曲线临时解析。该 fallback 不能覆盖空包、同名包和包级权限，只用于旧版 CLI 迁移期。
+
+---
+
+## 3. 应用定位：`app_resolve` 与 **`app_schema_apply` 创建**
+
+### 3.1 `app_resolve`（CLI）
+
+```bash
+# 模式 1：已有 app_key（推荐自动化）
+qingflow --json builder app resolve --app-key "<APP_KEY>"
+
+# 模式 2：包内按应用显示名查找（须同时给 package-id）
+qingflow --json builder app resolve \
+  --app-name "我的应用" \
+  --package-id 2030703
+```
+
+- **勿混用**：`--app-key` 与（`--app-name` 或 `--package-id`）**不能同时出现**；只能二选一模式（见 `builder.py` 校验）。
+
+### 3.2 单应用新建（`app_schema_apply` 创建模式 → CLI `schema apply`）
+
+新建前如不确定图标候选，先读：
+
+```bash
+qingflow --json builder icon catalog
+```
+
+```bash
+qingflow builder schema apply \
+  --package-id <TAG_ID> \
+  --app-name "新应用显示名" \
+  --create-if-missing \
+  --icon <非 template 图标名> \
+  --color <图标颜色> \
+  [--app-title …] \
+  [--visibility-file tmp/visibility.json] \
+  [--publish | --no-publish] \
+  [--add-fields-file tmp/add_fields.json] \
+  ...
+```
+
+- **`--icon` / `--color`**：取值以 `builder contract --tool-name app_schema_apply` / 当前 CLI 契约候选为准；不要自造 `sales-*`、`crm-*` 等业务语义 key。契约未返回候选值时省略该参数，不要猜测写入。
+
+- **创建模式要件**（与契约一致）：**`package_id` + `app_name`（或 CLI 的 app-title 映射到 app_name）+ `create_if_missing`**。
+- **图标必填**：创建应用必须显式传合法的 **`icon + color`**；不要用 `template`。CLI 只校验候选，不根据应用名称自动猜图标。多应用批量创建时，每个新应用应使用不同 `icon`。
+- **数据标题必填**：最终表单必须有且仅有一个顶层可读字段标记 `as_data_title: true`；数据封面可选，必须是顶层 `attachment` 字段标记 `as_data_cover: true`。
+- **编辑模式**：**仅** **`--app-key`**（可选改名 `--app-name`），**不要**与 `package_id` / `create_if_missing` 混用。
+
+### 3.3 多应用一次性新建（完整系统/应用包主链路）
+
+当用户要一次创建多个业务对象（例如花名册 + 工时表 + 项目表），或这些应用之间有互相引用关系时，不要循环调用多次 `builder schema apply`。完整系统新建的主链路就是 multi-app `apps-file`，不是“先批量试一下、慢了就拆单应用”的可选优化。用一个 `apps.json`：
+
+```bash
+qingflow builder schema apply \
+  --package-id <TAG_ID> \
+  --create-if-missing \
+  --apps-file tmp/apps.json
+```
+
+`apps.json` 主写法是对象形态 `{ "package_id": 123, "apps": [...] }`。CLI 兼容 raw apps array 和 singleton wrapper array，但不作为智能体主示例；不要把多个 `{package_id, apps}` wrapper 放进数组里。每个 `apps[]` 是一个应用 schema 配置，写自己的 `client_key`、`app_name`、`icon`、`color`、`add_fields`；同批应用之间的关联字段主写 **`target_app_ref`** 指向另一个应用的 `client_key`。只有目标应用已经存在或已被读回确认时，才使用真实 `target_app_key`；不要因为同批创建时还不知道真实 `app_key` 就放弃 `target_app_ref`。写入前 CLI 会先做静态预校验，`client_key/app_name` 重复、缺少 `as_data_title`、未开 `create_if_missing`、`target_app_ref/target_app` 无法解析都会以 `MULTI_APP_STATIC_VALIDATION_FAILED` 返回，不会先创建半成品应用：
+
+```json
+{
+  "package_id": 123,
+  "apps": [
+    {
+      "client_key": "employee",
+      "app_name": "员工花名册",
+      "icon": "business-personalcard",
+      "color": "emerald",
+      "add_fields": [
+        {"name": "员工名称", "type": "text", "as_data_title": true}
+      ]
+    },
+    {
+      "client_key": "worklog",
+      "app_name": "工时表",
+      "icon": "clock",
+      "color": "blue",
+      "add_fields": [
+        {"name": "工时标题", "type": "text", "as_data_title": true},
+        {
+          "name": "关联员工",
+          "type": "relation",
+          "target_app_ref": "employee",
+          "display_field": {"name": "员工名称"},
+          "visible_fields": [{"name": "员工名称"}]
+        }
+      ]
+    }
+  ]
+}
+```
+
+- 返回里看 `mode=multi_app`、`apps[].app_key`、`created_app_keys` 和 `apps[].status`。
+- 如果 CLI 看到 `[{ "package_id": 123, "apps": [...] }]`，会自动展开并返回 `APPS_FILE_WRAPPER_ARRAY_UNWRAPPED` warning；这是兼容路径，后续仍应改回对象形态。
+- 如果返回 `MULTI_APP_STATIC_VALIDATION_FAILED`，读取 `details.issues[]` 的 `path/error_code/fix_hint` 修 payload；这是写入前失败，通常可以修正后重试，不需要 readback。
+- 多应用 schema apply 不做事务回滚；如果部分失败，只补失败的 `apps[].row_number`，不要整批重复提交。
+- 这个模式只负责应用壳与字段；视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
+- 同批 `relation` 优先用 `target_app_ref` 指向 `client_key`；`target_app` 只适合名称唯一且稳定的同批应用。不要先分别建应用、再为了补 `target_app_key` 做第二轮字段修补。
+- relation 字段写入后读 `details.relation_readback_matrix[]`：逐项核对 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。若出现 `mismatch/missing`，按 `details.relation_repair_plan[]` 做最小 `update_fields` 修复；它会写明建议 patch 和 `data_impact`，不要删除重建字段。
+- `RELATION_FIELD_LIMIT_RISK` 是 warning：表示多个 relation 字段已写入/读回但后端能力可能不稳定。只要字段已创建且 readback 未 mismatch，不要降级成文本；只有 `MULTIPLE_RELATION_FIELDS_UNSUPPORTED` / 49614 或 relation readback mismatch 时，才按返回的 `recommended_modeling_fallback` 做部分降级并汇报为 partial。
+- 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时，先按 §3.4 读回，不要直接拆成单应用创建。
+
+### 3.4 多应用 schema apply 超时 / partial / readback 不完整恢复
+
+触发条件：shell/MCP 超时、响应被截断、`status=partial_success`、`write_executed=true`、`safe_to_retry=false`、`verification.readback_unavailable=true`、`created_app_keys` 不完整，或只拿到部分 `apps[].status`。
+
+统一判定：
+
+- 这不是“创建失败”的证据，而是 **`write_may_have_succeeded`**。
+- 下一步固定为 **`next_action: readback_before_retry`**。
+- 在 readback 完成前，不得重放整份 `apps-file`，不得把完整系统拆成多次单应用重建，不得创建 `V2` / `测试` / 随机后缀应用绕过重名。
+
+读回顺序：
+
+1. 已知 `package_id` 时先 `qingflow --json builder package get --package-id <TAG_ID>`，确认包仍可读、包内已有应用摘要。
+2. 对每个计划内 `apps[].app_name`，用 `builder app resolve --app-name <NAME> --package-id <TAG_ID>` 定位；若响应已经给出 `apps[].app_key` / `created_app_keys`，优先用这些 key。
+3. 对已定位应用执行 `builder app get --app-key <APP_KEY> fields`，核对标题字段、关键业务字段、relation 字段的 `target_app_key` / 显示字段。
+4. 形成矩阵：`created_and_verified`、`created_but_readback_incomplete`、`missing`、`field_or_relation_missing`、`failed_with_error`。
+5. 只有读回证明某个应用确实不存在或某个字段确实缺失时，才做最小修复：补缺失 app 行、补缺失字段或修 relation；不要重跑已经存在的应用。
+
+重试/修复限制：
+
+- 继续使用原始 `app_name` 与业务命名。重名冲突表示需要读回/更新/询问用户，不是创建 `V2` 的理由。
+- 同批仍未创建的应用之间继续用 `client_key + target_app_ref`。只有目标应用已通过 readback 确认存在时，才可在后续修复里改用 `target_app_key`。
+- 若 readback 证明主应用已存在但部分 relation 缺失，修 relation 前先说明数据影响：是否会清空已有值、是否需要迁移、是否可安全重试。
+- 如果已有包内已经存在相似应用，先决定“复用/更新/新建缺失应用/询问用户”，不要用相似重名或后缀绕开。
+
+**`visibility` JSON**（`--visibility-file`）：与包/应用通用，键见契约 `$.contract.allowed_values["visibility.*"]`：
+
+- **`mode`**：`workspace` | `everyone` | `specific`（`specific` 须 **`selectors`**：`member_uids` / `member_emails` / `member_names` / `dept_ids` / `dept_names` / `role_ids` / `role_names` / `include_sub_departs`）。
+- **`external_mode`**：`not` | `workspace` | `specific`，与对外可见性独立；**`mode=everyone`** 时行为见契约 **execution_notes**。
+
+---
+
+## 4. 读场三口：`app_read_*`（CLI `builder app get`）
+
+```bash
+qingflow --json builder app get --app-key "<APP_KEY>"
+qingflow --json builder app get --app-key "<APP_KEY>" fields
+qingflow --json builder app get --app-key "<APP_KEY>" layout
+qingflow --json builder app get --app-key "<APP_KEY>" flow
+# 另有 summary（默认）| views | charts
+```
+
+- **`app get` 默认摘要**：应用地图入口，包含 compact `views`、`charts`、`custom_buttons`、`associated_resources`。需要完整配置时再调用具体 `fields/layout/views/flow/charts` 或 `view get/chart get`。
+- **`fields`**：每项含 **`que_id`**、**`name`**、**`type`**（字符串枚举）、**`required`**、**`section_id`**（含子表 **`subfields`**、关联 **`target_app_key`** 等）。用于 **`update_fields` / `remove_fields` 的 selector**。
+- **`layout`**：**`sections[]`**（`type: paragraph`、`rows: [[字段名, …], …]`）、**`unplaced_fields`**、**`layout_mode_detected`**；可能出现 **`LAYOUT_SUMMARY_UNVERIFIED`** 警告。
+- **`flow`**：**`enabled`**、**`nodes`** 摘要；契约提示 **分支/条件** 在公开工具面受限，验证仅覆盖 **线性** 结构。
+
+**实跑摘录**（`ead8ims5i401`）：`field_count=7`；`layout` 1 个 section、`unplaced_fields` 空；`flow` `enabled=true`、`nodes` 数 1。
+
+---
+
+## 5. 改场三口：`app_schema_apply` / `app_layout_apply` / `app_flow_apply`（CLI）
+
+### 5.1 字段：`builder schema apply`
+
+**一键可复制「仅新增字段」示例**（**`add_fields` 数组文件**）：[schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json)
+
+```bash
+qingflow builder schema apply \
+  --app-key "<APP_KEY>" \
+  --no-publish \
+  --add-fields-file ./reference/schema_add_fields_minimal.example.json
+```
+（路径以 `qingflow-cli/` 技能根目录为基准；执行时可解析为该技能目录下的实际文件。）
+
+- **`name`** 须为当前应用内 **唯一** 的控件显示名；若报重名，改 **`示例搭建_CLI单行`** 后再执行。
+- 本文件对应契约 **`app_schema_apply`** 中 **`add_fields`** 的 **最小 `text`** 项；更多 **`type`** 见 **§6**；完整创建应用：单应用见 **§3.2**（**`package_id` + `app_name` + `create_if_missing`**），多应用/跨应用引用见 **§3.3**（**`--apps-file` + `client_key` / `target_app_ref`**）。
+
+```bash
+qingflow builder schema apply \
+  --app-key "<APP_KEY>" \
+  [--publish | --no-publish] \
+  [--add-fields-file tmp/add.json] \
+  [--update-fields-file tmp/update.json] \
+  [--remove-fields-file tmp/remove.json]
+```
+
+- **`--publish` / `--no-publish`**：默认发布；`--no-publish` 仅草稿/预检语义（见 `server_app_builder` 总述：**schema/layout/views/flow** 的 noop 与发布关系以契约为准）。
+- **文件体形状**：与 **`app_schema_apply`** 契约一致；顶层 **`add_fields` / `update_fields` / `remove_fields`** 数组。
+- **标题/封面**：只在字段 JSON 中直接标记，例如 `{"name":"项目名称","type":"text","required":true,"as_data_title":true}`、`{"name":"项目封面","type":"attachment","as_data_cover":true}`。
+- **本仓实测**（`ead8ims5i401`，`--no-publish`，`name` 改为未存在过的 **`CLI搭建探针字段_可删`**）：`field_diff.added` 成功；同一 **`name`** 不可重复添加，后续请改用 **[schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json)** 内模板名或自改唯一名。
+
+### 5.2 布局：`builder layout apply`
+
+```bash
+qingflow builder layout apply \
+  --app-key "<APP_KEY>" \
+  --mode merge \
+  [--publish | --no-publish] \
+  --sections-file tmp/sections.json
+```
+
+- **`mode`**：`merge`（默认）或 `replace`。
+- **`sections` JSON**：数组，元素形状见契约 **`minimal_example`**：`type: paragraph`、`paragraph_id`、`title`、`rows: [[列标题…], …]`，单元格值为 **字段显示名 `name`**（与 `app_get_fields` 一致）。
+
+### 5.3 流程：`builder flow apply`
+
+流程前置条件：
+
+- 审批 / 填写 / 抄送类流程需要一个显式业务状态字段；推荐在 schema 阶段先建 `select` 字段，例如 `状态`、`处理状态`、`审批状态`、`工单状态` 或 `流程阶段`。
+- 不要创建平台流程系统字段：`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。这些只能由平台维护。
+- 如果返回 `FLOW_DEPENDENCY_MISSING`，先执行返回的 `suggested_next_call` 补业务状态字段，再 `builder app get fields` 回读，然后重跑 flow apply；不要跳过流程后报告“流程完成”。
+
+```bash
+qingflow builder flow apply \
+  --app-key "<APP_KEY>" \
+  --mode replace \
+  [--publish | --no-publish] \
+  --nodes-file tmp/nodes.json \
+  --transitions-file tmp/transitions.json
+```
+
+- **`mode`**：CLI 当前仅 **`replace`**。
+- **限制**（契约 **execution_notes**）：公开面 **有意仅支持线性流程**；**分支 / 条件节点不可用**（后端前端组合不稳定）。
+
+---
+
+## 6. 字段类型：`app_schema_apply` 怎么写
+
+以下 **`type`** 取值来自契约 **`$.contract.allowed_values["field.type"]`**（与 **`field_type_ids`** 对应：2,3,4,5,6,7,8,10,11,12,13,18,20,21,22,25,26 —— **勿手写 id**，用 **字符串 `type`**）。
+
+智能体可优先写更自然的字段类型，工具会在写入前归一化；读回仍显示 canonical 类型：
+
+| 智能体写法 | 内部类型 |
+|------------|----------|
+| `multiline` / `multiline_text` / `textarea` | `long_text` |
+| `select` / `single_choice` / `dropdown` | `single_select` |
+| `multi_select` / `multi_choice` / `multiple_choice` / `checkbox` | `multi_select` |
+
+| `type` | 设置要点 |
+|--------|----------|
+| **`text`** | **`name`**；可选 **`required`**、**`description`**；无选项。 |
+| **`long_text`** | 同上。 |
+| **`number`** | 同上；比例、完成率、评分、数量、时长、百分比等可能出现小数或非货币数值时优先用它。 |
+| **`amount`** | 同上；只用于货币/金额语义，不要把百分比、完成率、成本执行率等业务比例建成 `amount`。 |
+| **`date`** | 同上。 |
+| **`datetime`** | 同上。 |
+| **`member`** | **`name`**、**`required`**；成员选择器，无额外 scope 键（与 **department** 不同）。 |
+| **`department`** | **`department_scope`**：`mode: all \| custom`；**`custom`** 时 **`departments[]`** 须含 **`dept_id`**（可选 **`dept_name`** 辅助）、**`include_sub_departs`**。 |
+| **`single_select`** / **`multi_select`** | **`options` 可用字符串数组**，如 `["A", "B"]`，也可用对象数组如 `[{"label":"A","value":"a"}]`；工具会归一化为选项文案。可选 **`required`**。 |
+| **`phone`** / **`email`** | 标准校验类字段，**`name` + required**。 |
+| **`address`** | 地址复合字段。 |
+| **`attachment`** | 附件。 |
+| **`boolean`** | 是否。 |
+| **`relation`** | 单应用/已存在目标用 **`target_app_key`**；同批 multi-app 新建用 **`target_app_ref`** 指向目标 `apps[].client_key`。**`relation_mode`**：`single` \| `multiple`（**`multiple` 有风险**：多读 **`verification.relation_field_limit_verified` / MULTIPLE_RELATION_FIELDS_UNSUPPORTED**）；**必须** **`display_field`** 与 **`visible_fields[]`**（**`name`** 指向目标应用字段）；元数据不可查时可显式 **`display_field.name` / `visible_fields[].name`** 降级；写后读 **`details.relation_readback_matrix[]`**，不一致时按 **`details.relation_repair_plan[]`** 最小修复。 |
+| **`subtable`** | **`subfields[]`**，子项与父级同类递归；更新已存在子列优先契约推荐的 **`update_fields[].set.subfield_updates`**（只允许 **name / required / description / 嵌套 subfield_updates**），**`set.subfields` 全量替换** 风险更高。 |
+| **`q_linker`** | **`q_linker_binding`**：`inputs`、`request`（URL/method/headers…）、**`outputs[]`**（`alias` / `path` / **`target_field.name`**）；**`target_field.type`** 限定为契约 **allowed_values** 子集。 |
+| **`code_block`** | **`code_block_binding`**：`inputs`（**`field.name` → `var`**）、**`code`**、**`auto_trigger`**、按钮文案；**`outputs[]`** 指向 **`target_field`**；**必须** 可静态识别 **`qf_output =` 赋值**（禁止仅 `const/let qf_output`，实现会规范化）；**不执行代码**，只写配置。 |
+
+### 6.1 数据标题与数据封面
+
+- `as_data_title: true`：配置应用数据标题。最终表单必须有且仅有一个顶层可读标题字段；推荐文本、编号、名称类字段。
+- `as_data_cover: true`：配置应用数据封面。可选，且只能用于一个顶层 `attachment` 字段。
+- 子表子字段不能作为标题或封面；多标题、多封面、非附件封面都会在写入前阻断。
+- 未显式标记封面时保留/不创建封面；未能形成唯一标题时视为配置错误，不要声称应用已完整创建。
+
+**别名**：契约 **`aliases`** 会把 `field.title` / `field.label` 等映射到 **`name`**，把 `field.type_id` 映射到 **`type`**；契约 **`$.contract.allowed_values["field.type_aliases"]`** 会把自然字段类型映射到内部类型。主路径建议写上表自然类型，排障和读回时看 canonical 类型。
+
+**`update_fields` 项**：**`selector`**：`que_id` 或 `field_id` 或 **`name`**；**`set`**：允许子集（**`name` / `required` / `description` / `options` / `department_scope` / … / `subfield_updates`**）。
+
+**`remove_fields` 项**：**`que_id` / `field_id` / `name`** 之一。
+
+**完整类型表、`schema apply` 场景矩阵、探针结论**：见 **[QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md](./QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md)**。**19 种搭建 `type` 单文件 `add_fields`（推荐新建应用一次成功）**：[schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json)。
+
+---
+
+### 6.2 局部参数更新规则（patch vs upsert）
+
+后端很多保存接口仍是整份配置保存，但新版 CLI/MCP 对外提供 **public partial patch**：
+
+- 已有视图：`builder views apply --patch-views-file`
+- 已有按钮：`builder button apply --patch-buttons-file`
+- 已有关联资源：`builder associated-resource apply --patch-resources-file`
+- 已有报表：`builder charts apply --patch-file`
+
+`patch_*` 的语义是：你只写要替换的参数，工具内部读取当前配置、补齐后端必填字段，再整份保存。每个 patch 项直接使用对象真实定位字段 + `set` / 可选 `unset`，不要写字面量 `selector` key。示例：`{"view_key": "VIEW_KEY", "set": {"query_conditions": {...}}}`、`{"button_id": 1001, "set": {"button_text": "新名称"}}`、`{"associated_item_id": 123, "set": {"match_mappings": [...]}}`、`{"chart_id": 456, "set": {"name": "新报表名"}}`。
+
+`upsert_*` 用于创建或提供完整目标配置；不要只给 `name/type/query_conditions` 这类局部片段然后期待后端自动合并。
+
+---
+
+## 7. 系统字段与视图系统列（必读）
+
+### 7.1 平台系统字段 / 视图系统列（不可当普通字段去 `add_fields` / 录入）
+
+平台会自动生成或维护这些系统字段 / 系统列，不要在创建表单时手工造同名控件，也不要在录入数据时写入：
+
+**`数据ID`**、**`编号`**、**`申请人`**、**`申请时间`**、**`创建人`**、**`创建时间`**、**`提交人`**、**`提交时间`**、**`更新时间`**、**`更新人`**、**`当前流程状态`**、**`当前处理人`**、**`当前处理节点`**、**`流程标题`**。
+
+- **含义**：这些是平台维护的系统信息，**不要**在 **`add_fields`** 里手工造同名控件来「模拟」，也不要写进 `record insert` 的 `fields` / `items[].fields`。
+- **视图列例外**：`builder views apply` 对部分系统列名会过滤并警告（`ignored_system_columns`）；新建/更新业务视图至少要包含一个真实业务字段。
+- **与 `app_get_fields` 的关系**：读回 **`fields[]`** 侧重 **表单搭建字段**；**编号 / 申请人** 等可能不会作为普通 `type` 出现在列表中（视应用模板与工作流是否开启），**以读回 JSON 为准**。交付时 **业务字段** 用 **`app_get_fields`**；**系统列** 由平台在 **数据列表 / 视图** 侧展示。
+
+### 7.2 布局 / 流程中的「系统行为」
+
+- **布局**：仅摆放 **`app_get_fields`** 里出现的 **`name`**；不要把上表系统列名放进 **`rows`** 除非读回确认存在对应可摆放控件。
+- **流程**：**`app_flow_apply` 的 `permissions.editable_fields`** 等须引用 **真实业务字段名**（读 `fields`）。流程需要状态时，创建业务字段 `状态` / `处理状态` 等，不创建平台字段 `当前流程状态`。
+
+---
+
+## 8. 按钮与关联资源（新版默认路径）
+
+### 8.1 自定义按钮：`app_custom_buttons_apply`
+
+默认使用 `qingflow builder button apply` 管理按钮本体和视图位置，不再把自定义按钮拆成 `create/update/delete/list/get` 多个公开路径。
+
+```bash
+qingflow builder button apply \
+  --app-key "<APP_KEY>" \
+  --upsert-buttons-file tmp/upsert_buttons.json \
+  --remove-buttons-file tmp/remove_buttons.json \
+  --view-configs-file tmp/button_view_configs.json
+```
+
+新增数据按钮优先用语义化字段映射：
+
+```json
+{
+  "client_key": "add_worklog",
+  "button_text": "快捷添加工时",
+  "trigger_action": "addData",
+  "trigger_add_data_config": {
+    "target_app_key": "WORKLOG_APP",
+    "field_mappings": [
+      {"source_field": "员工名称", "target_field": "员工"}
+    ],
+    "default_values": {"状态": "待提交"}
+  }
+}
+```
+
+- 新增数据按钮只写 `field_mappings/default_values`。
+- `view_configs[].buttons[]` 绑定位置：`header`、`detail`、`list`。对外入参仍写 `placement=list`；CLI 会映射为后端 `INSIDE` 行内/列表按钮。
+- `button_ref` 可以引用同次 `upsert_buttons[].client_key`，也可以引用已有 `button_id`。
+- `view_configs[].view_key` 使用 `builder app get --app-key APP_KEY` 返回的 raw `view_key`，不要加 `custom:`。
+- `view_configs[].mode` 默认 `merge`，merge 模式必须传 `buttons`；清空用 `mode="replace"` 或显式 `buttons: []`。
+- 字段兼容与 `数据ID` / `编号` 规则见 **[QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./QINGFLOW_CLI_BUILDER_MATCH_RULES.md)**。
+- 删除按钮时优先传 **`button_id`**；若用 **`button_text`** 必须能唯一匹配。DELETE 发出后会按单个 **`button_id`** 回读验证，结果看 **`removed[].delete_executed/readback_status/safe_to_retry_delete`**。只要 **`delete_executed=true`**，就不要盲目重复删除；**`readback_status=unavailable|still_exists`** 表示回读待确认。
+- 该工具有成功写入时自动发布；全阻断、全失败或无变化不会额外发布。
+
+### 8.2 关联视图/报表：`app_associated_resources_apply`
+
+默认使用 `qingflow builder associated-resource apply` 管理应用级关联资源池与视图展示配置。
+
+- 权限分层：`upsert_resources` / `patch_resources` / 删除 / 排序应用级关联资源池走 **EditAppAuth**；`view_configs` 修改某个视图里的关联资源展示配置，还需要视图配置侧的 **ViewManagementAuth**（未开启高级应用权限时回落到 **DataManageAuth**）。
+
+```bash
+qingflow builder associated-resource apply \
+  --app-key "<APP_KEY>" \
+  --upsert-resources-file tmp/upsert_resources.json \
+  --view-configs-file tmp/associated_view_configs.json
+```
+
+- Shell 退出码为 0、重定向成功或 `echo OK` 只表示命令执行完，不表示业务成功。必须读取输出 JSON，检查顶层 `status`、`error_code`、`warnings`、`blocking_issues`；`status: failed`、`partial_success`、`ASSOCIATED_RESOURCES_APPLY_BLOCKED` 都不能当作完成。
+- 关联资源要生效必须同时处理两层：应用级资源池（`upsert_resources` / `patch_resources`）和视图详情展示绑定（`view_configs`）。只传 `--upsert-resources-file` 往往只是在资源池准备资源，不会让按钮或视图详情里看到关联资源。
+- `builder views apply` 新建视图会默认打开详情页关联查看（展示全部应用级关联资源）；若只需要默认展示全部资源，创建视图时不用额外写 `view_configs`。需要指定部分资源、关闭展示或配置匹配筛选时，仍必须使用本工具的 `view_configs` / `match_mappings`。
+- `associated_item_id` 是后端 `form_asos_chart.id`，最终来自 `app_get.associated_resources[].associated_item_id`；它不是 `chart_id`、`chart_key` 或 `view_key`。
+- 创建前先检查 `associated_resources` 中是否已有相同 `target_app_key + view_key/chart_key`；已存在时用 `patch_resources`，不要重复 `upsert_resources`。
+- 公开面只写 `graph_type`、`view_key` / `chart_key` 和可选 `report_source`；关联视图内部自动使用后端需要的来源，关联报表默认是 **应用源 BI 报表**，可先用 `builder charts apply` 创建/更新。**数据集 BI 报表只能关联已有报表**，使用 `report_source: "dataset"`，不要用 `builder charts apply` 创建或编辑 dataset 报表。
+- 关联报表时优先传 `chart_id` / `chart_key`；CLI 会解析为轻流后端需要的内部关联 id。视图展示配置里已有资源仍以 `associated_item_id` 为最终口径。
+- 同次创建资源并配置视图时，用 `client_key` + `view_configs[].associated_item_refs`。
+- `client_key` 只用于同一次 apply 内给 `view_configs[].associated_item_refs` 引用，后端不会保存，不能用于后续去重。
+- 每个主应用都要生成自己的 upsert/view-config payload，不要复用其他应用的 tmp JSON；命令中 `--app-key` 只写一次，且必须与 payload 的主应用一致。
+- 成功后必须用 `builder app get --app-key ...` 回读：确认 `associated_resources[].associated_item_id` 已生成，并确认目标视图的详情配置中已绑定对应资源。若只看到资源池有记录、视图详情无绑定，继续补 `view_configs`，不能宣称完成。
+- 关联筛选优先用 `match_mappings`，不要手写 raw `match_rules`；字段兼容规则见 **[QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./QINGFLOW_CLI_BUILDER_MATCH_RULES.md)**。
+- 删除关联资源时传 **`associated_item_id`**，也可传已有资源的 `chart_id/chart_key/view_key` 让工具解析为内部 id。后端暂无确认可用的单项关联资源 GET，所以工具只做一次资源池回读验证；结果看 **`removed[].delete_executed/readback_status/safe_to_retry_delete`**。只要 **`delete_executed=true`**，就不要盲目重复删除；**`readback_status=unavailable|still_exists`** 表示回读待确认。
+- 该工具有成功写入时自动发布；不提供 `--no-publish`。
+
+## 9. `app_publish_verify`（CLI `builder publish verify`）
+
+```bash
+qingflow builder publish verify \
+  --app-key "<APP_KEY>" \
+  [--expected-package-id <TAG_ID>]
+```
+
+- 校验 **已发布**、**视图 OK**、可选 **包一致性**（**`expected_package_id`**）。
+- **编辑锁**：若因 **当前用户持有锁** 失败，契约提示：**`builder app release-edit-lock-if-mine`**（须 **邮箱 / 姓名** 参数）后再重试。
+
+**实跑**（`ead8ims5i401`）：`message: app already published and verified`，`package_ids_after: [2030703]`。
+
+---
+
+## 9. 输出与排障
+
+- **builder 写入/apply 工具默认直接输出 JSON 到 stdout**，便于前端捕获；builder 读取命令仍显式加 `--json`。需要同时留档时使用 `| tee tmp/builder_*.json`，不要用 `>` 吞掉 stdout。
+- **schema apply 超时 / partial / write_executed 后**：先 `readback_before_retry`。尤其是完整系统 multi-app 创建，慢响应常见但可能已经落库；不要直接重放整批、拆单应用重建或用后缀应用绕过冲突。
+- **446 / 49614**：多看契约 **execution_notes**（如 **多选关联限制**）。
+- **40161 / 元数据不可读**：**relation / q_linker / code_block** 按上文 **显式 name / binding** 路径降级。
+
+---
+
+## 10. 交叉引用
+
+- **最小 `add_fields` 示例**：[schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json)
+- **19 种搭建 type 一次性 `add_fields`**：[schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json)
+- **类型与场景总表**：[QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md](./QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md)
+- [SKILL.md](../SKILL.md)：`builder` 命令边界、**ADMIN** 指向。
+- [QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)：成员侧 **记录读写** 的 `kind` / 值形态（与 **搭建 `type`** 名称不同系，但可对照理解业务）。
+- [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)：`package apply`、权限类 **`IMPORT_*` / 40002**。