@qingflow-tech/qingflow-cli 1.1.43 → 1.1.44-beta.1

package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md

@@ -1,11 +1,11 @@
 # Builder 应用交付重流程 SOP：分组 → 应用定位 → 读场 → 改场 → 发布校验
 
-本文以 **稳定 CLI**（`qingflow builder` / `qingflow build`）为唯一公开入口。编写前已阅读实现中的 `builder_facade/service.py`、`cli/commands/builder.py`、`ai_builder_tools.py`，并对 **`ead8ims5i401`** 实跑：`app resolve`、`app get fields|layout|flow`、`publish verify`。
+本文是历史低层交付备忘，不是当前表单写入 SOP。稳定 CLI 公开入口仍为 `qingflow builder` / `qingflow build`，但表单字段、分组、布局和设置必须使用 `qingflow --json builder app-form schema/get/validate/apply`，应用删除使用 `qingflow --json builder app delete --app-key APP_KEY`；本文件中的 `app_schema_apply` / `app_layout_apply` / `builder schema apply` / `builder layout apply` 只用于识别旧载荷和迁移，不得直接调用。
 
 > **权限**：应用基础信息（`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>`
+> **契约**：当前表单契约固定通过 `qingflow --json builder app-form schema` 获取；其它公开 `app_*_apply` 仅是 `builder contract --tool-name` 的参数值，**不是可执行 CLI 子命令**。其 **`allowed_keys` / `allowed_values` / `execution_notes` / 示例** 以在线契约为准，命令：
+> `qingflow --json builder contract --tool-name <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 ...`。
 >
@@ -27,8 +27,8 @@
 | 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 …` | **段落 / 行 / 单元格** 摆放字段 |
+| E | **AppForm** | `qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json` -> `qingflow --json builder app-form apply --file DECLARATION.json` | 完整 AppForm：字段、分组、行、设置和应用创建/更新 |
+| F | — | 由 AppForm 的 `body` 一并维护 | 表单段落 / 行 / 单元格随完整声明提交 |
 | 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 …` | 管理应用级关联视图/报表池，并配置视图详情侧边栏展示 |
@@ -41,7 +41,7 @@
 这些不是独立流程，而是读、写、改三个动作的多资源形态：
 
 - **批量读**：读多个应用时优先用 `--app-keys`，例如 `builder app get --app-keys a,b fields`、`builder app get --app-keys a,b views`、`builder button get --app-keys a,b`、`builder associated-resource get --app-keys a,b`、`builder publish verify --app-keys a,b`。读结果同时看成功项和 `errors[]`，不要因单个应用失败否定全批。
-- **批量写**：写多个应用时使用各资源自己的 `--apps-file`，例如 `schema/layout/views/button/associated-resource/charts apply --apps-file ...`。`apps[]` 每项都必须带自己的 `app_key` 或多应用 schema 的 `client_key/app_name`。
+- **批量写**：视图、按钮、关联资源和报表按各自资源契约使用对应的批量文件；应用表单不走 `apps-file`，而是每个应用独立提交完整 AppForm 声明。
 - **局部改**：只改已存在资源的少量参数时用对应 patch 文件；`patch_*` 内只写目标定位字段和 `set/unset`，不要用不完整 `upsert_*` 伪装局部更新。
 
 ---
@@ -102,7 +102,7 @@ qingflow --json builder package get --package-id <package_id>
 
 ---
 
-## 3. 应用定位：`app_resolve` 与 **`app_schema_apply` 创建**
+## 3. 应用定位与 AppForm 创建
 
 ### 3.1 `app_resolve`（CLI）
 
@@ -118,9 +118,11 @@ qingflow --json builder app resolve \
 
 - **勿混用**：`--app-key` 与（`--app-name` 或 `--package-id`）**不能同时出现**；只能二选一模式（见 `builder.py` 校验）。
 
-### 3.2 单应用新建（`app_schema_apply` 创建模式 → CLI `schema apply`）
+### 3.2 单应用新建（历史 `app_schema_apply` 迁移说明）
 
-新建前如不确定图标候选，先读：
+当前新建和更新请使用 `qingflow --json builder app-form schema/get/validate/apply`；下方旧命令仅用于迁移脚本识别，不能执行。
+
+历史脚本可能先读取图标候选；当前 AppForm 新建同样先读取并固定合法图标和颜色：
 
 ```bash
 qingflow --json builder icon catalog
@@ -139,23 +141,27 @@ qingflow builder schema apply \
   ...
 ```
 
+上面的 `builder schema apply` 示例是 retired 命令，当前 CLI parser 不接受；这里只保留参数形状供迁移脚本定位。
+
 - **`--icon` / `--color`**：取值以 `builder contract --tool-name app_schema_apply` / 当前 CLI 契约候选为准；不要自造 `sales-*`、`crm-*` 等业务语义 key。契约未返回候选值时省略该参数，不要猜测写入。
 
 - **单应用创建模式要件**（与契约一致）：**`package_id` + `app_name`**（或 CLI 的 app-title 映射到 app_name）。
 - **图标必填**：创建应用必须显式传合法的 **`icon + color`**；不要用 `template`。CLI 只校验候选，不根据应用名称自动猜图标。多应用批量创建时，每个新应用应使用不同 `icon`。
-- **数据标题必填**：最终表单必须有且仅有一个顶层可读字段标记 `as_data_title: true`；数据封面可选，必须是顶层 `attachment` 字段标记 `as_data_cover: true`。
+- **数据标题必填**：旧载荷使用 `as_data_title` / `as_data_cover`；当前 AppForm 对应 `dataTitle` / `dataCover`，并要求最终表单只有一个顶层标题字段。
 - **编辑模式**：**仅** **`--app-key`**（可选改名 `--app-name`），**不要**与 `package_id` 混用。
 
-### 3.3 多应用一次性新建（完整系统/应用包主链路）
+### 3.3 多应用一次性新建（历史 multi-app 迁移说明）
 
-当用户要一次创建多个业务对象（例如花名册 + 工时表 + 项目表），或这些应用之间有互相引用关系时，不要循环调用多次 `builder schema apply`。完整系统新建的主链路就是 multi-app `apps-file`，不是“先批量试一下、慢了就拆单应用”的可选优化。用一个 `apps.json`：
+本节下方的 `--apps-file` 示例是旧 CLI 载荷，仅用于识别/迁移历史脚本；当前完整系统应逐个创建 AppForm，记录返回的 `appKey` 后再绑定关系。
+
+旧版本允许用一个 `apps-file` 同批创建多个业务对象。当前版本不再公开该入口；完整系统应先分别创建无关系 AppForm，记录每个返回的 `appKey`，再用完整 AppForm 声明补充关系字段。以下内容只用于识别和迁移旧脚本：
 
 ```bash
 qingflow builder schema apply \
   --apps-file tmp/apps.json
 ```
 
-`apps.json` 主写法是对象形态 `{ "package_id": 123, "apps": [...] }`，多应用模式按 `app_name` 直接提交创建，不在工具内查重或按名称复用。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`、`target_app_ref/target_app` 无法解析都会以 `MULTI_APP_STATIC_VALIDATION_FAILED` 返回，不会先创建半成品应用。若后端返回重名/冲突，或写入结果不确定，先读回应用包和字段，再决定复用、补齐缺失资源或询问用户：
+`apps.json` 中的 `package_id`、`client_key`、`app_name`、`add_fields` 和 `target_app_ref` 都是旧 snake_case 载荷键，不得改作当前 AppForm 示例：
 
 ```json
 {
@@ -195,8 +201,8 @@ qingflow builder schema apply \
 - 如果返回 `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`，不要删除重建字段。
+- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayField`、`config.visibleFields`，并使用已确认的真实 app key。
+- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`，不要提交旧 `update_fields` patch。
 - 一个应用可以包含多个 `relation` 字段；不要因为 relation 数量超过 1 就降级成文本。若真实写入失败或 relation readback mismatch，只按实际错误和 `details.relation_repair_plan[]` 做最小修复。
 - 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时，先按 §3.4 读回，不要直接拆成单应用创建。
 
@@ -221,7 +227,7 @@ qingflow builder schema apply \
 重试/修复限制：
 
 - 继续使用原始 `app_name` 与业务命名。重名冲突表示需要读回/更新/询问用户，不是创建 `V2` 的理由。
-- 同批仍未创建的应用之间继续用 `client_key + target_app_ref`。只有目标应用已通过 readback 确认存在时，才可在后续修复里改用 `target_app_key`。
+- 迁移到当前 AppForm 后，不再继续补发 `client_key + target_app_ref`；先确认每个实际 `appKey`，再提交完整声明和 `config.targetAppKey`。
 - 若 readback 证明主应用已存在但部分 relation 缺失，修 relation 前先说明数据影响：是否会清空已有值、是否需要迁移、是否可安全重试。
 - 如果已有包内已经存在相似应用，先决定“复用/更新/新建缺失应用/询问用户”，不要用相似重名或后缀绕开。
 
@@ -251,11 +257,13 @@ qingflow --json builder app get --app-key "<APP_KEY>" flow
 
 ---
 
-## 5. 改场三口：`app_schema_apply` / `app_layout_apply` / `app_flow_apply`（CLI）
+## 5. 改场三口（历史 schema/layout 迁移说明 + 当前 flow）
+
+`app_schema_apply` / `app_layout_apply` 已从公开 MCP/CLI surface 移除。下方 schema/layout 命令只用于迁移旧脚本；当前表单和布局必须使用 `qingflow --json builder app-form schema/get/validate/apply`。
 
-### 5.1 字段：`builder schema apply`
+### 5.1 历史字段载荷：`builder schema apply`（仅迁移识别）
 
-**一键可复制「仅新增字段」示例**（**`add_fields` 数组文件**）：[schema_add_fields_minimal.example.json](../../examples/schema/schema_add_fields_minimal.example.json)
+以下示例是 retired `add_fields` 载荷，不能执行；当前字段新增请回到 AppForm 完整声明。
 
 ```bash
 qingflow builder schema apply \
@@ -266,7 +274,7 @@ qingflow builder schema apply \
 （路径以 `qingflow-cli/` 技能根目录为基准；执行时可解析为该技能目录下的实际文件。）
 
 - **`name`** 须为当前应用内 **唯一** 的控件显示名；若报重名，改 **`示例搭建_CLI单行`** 后再执行。
-- 本文件对应契约 **`app_schema_apply`** 中 **`add_fields`** 的 **最小 `text`** 项；更多 **`type`** 见 **§6**；完整创建应用：单应用见 **§3.2**（**`package_id` + `app_name`**，直接提交创建），多应用/跨应用引用见 **§3.3**（**`--apps-file` + `client_key` / `target_app_ref`**，直接提交创建）。
+- 本文件只记录旧 `app_schema_apply` 的 `add_fields` 形状，供迁移脚本识别；当前新建和字段维护均回到完整 AppForm 声明。
 
 ```bash
 qingflow builder schema apply \
@@ -278,11 +286,11 @@ qingflow builder schema apply \
 ```
 
 - **`--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}`。
+- **文件体形状**：旧契约的顶层 **`add_fields` / `update_fields` / `remove_fields`** 数组；当前 CLI 不接受该形状。
+- **标题/封面**：旧字段标记 `as_data_title` / `as_data_cover` 迁移为 AppForm 的 `dataTitle` / `dataCover`。
 - **本仓实测**（`ead8ims5i401`，`--no-publish`，`name` 改为未存在过的 **`CLI搭建探针字段_可删`**）：`field_diff.added` 成功；同一 **`name`** 不可重复添加，后续请改用 **[schema_add_fields_minimal.example.json](../../examples/schema/schema_add_fields_minimal.example.json)** 内模板名或自改唯一名。
 
-### 5.2 布局：`builder layout apply`
+### 5.2 历史布局载荷：`builder layout apply`（仅迁移识别，不可执行）
 
 ```bash
 qingflow builder layout apply \
@@ -292,14 +300,14 @@ qingflow builder layout apply \
   --sections-file tmp/sections.json
 ```
 
-- **`mode`**：`merge`（默认）或 `replace`。
+- **`mode`**：旧载荷中的 `merge`（默认）或 `replace`；当前 AppForm 不使用该局部模式，必须提交完整 `spec.body`。
 - **`sections` JSON**：数组，元素形状见契约 **`minimal_example`**：`type: paragraph`、`paragraph_id`、`title`、`rows: [[列标题…], …]`，单元格值为 **字段显示名 `name`**（与 `app_get_fields` 一致）。
 
 ### 5.3 流程：`builder flow apply`
 
 流程前置条件：
 
-- 审批 / 填写 / 抄送类流程需要一个显式业务状态字段；推荐在 schema 阶段先建 `select` 字段，例如 `状态`、`处理状态`、`审批状态`、`工单状态` 或 `流程阶段`。
+- 审批 / 填写 / 抄送类流程需要一个显式业务状态字段；当前 AppForm 应在 schema 阶段先建 `single_select` 字段并设置 `config.options`，例如 `状态`、`处理状态`、`审批状态`、`工单状态` 或 `流程阶段`。历史 schema adapter 里的 `select` 仅用于迁移识别。
 - 不要创建平台流程系统字段：`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。这些只能由平台维护。
 - 如果返回 `FLOW_DEPENDENCY_MISSING`，先执行返回的 `suggested_next_call` 补业务状态字段，再 `builder app get fields` 回读，然后重跑 flow apply；不要跳过流程后报告“流程完成”。
 
@@ -314,9 +322,9 @@ qingflow builder flow apply \
 
 ---
 
-## 6. 字段类型：`app_schema_apply` 怎么写
+## 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`**）。
+以下内容只帮助迁移旧载荷；当前字段类型、camelCase 配置和必填项以固定版本的 `qingflow --json builder app-form schema` 返回结果为准。
 
 智能体可优先写更自然的字段类型，工具会在写入前归一化；读回仍显示 canonical 类型：
 
@@ -335,31 +343,30 @@ qingflow builder flow apply \
 | **`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`**。 |
+| **`department`** | 旧载荷使用 **`department_scope`**；当前 AppForm 使用 `config.departmentScope`，具体形状以 pinned schema 为准。 |
+| **`single_select`** / **`multi_select`** | 当前 AppForm 使用 `config.options` 字符串数组；对象数组和裸 `options` 仅属于旧兼容载荷。 |
 | **`phone`** / **`email`** | 标准校验类字段，**`name` + required**。 |
 | **`address`** | 地址复合字段。 |
 | **`attachment`** | 附件。 |
 | **`boolean`** | 是否。 |
-| **`relation`** | 单应用/已存在目标用 **`target_app_key`**；同批 multi-app 新建用 **`target_app_ref`** 指向目标 `apps[].client_key`。一个应用可以包含多个 `relation` 字段。**`relation_mode`**：`single` \| `multiple`；**必须** **`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`，实现会规范化）；**不执行代码**，只写配置。 |
+| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`。 |
+| **`subtable`** | 当前 AppForm 使用 `subfields[]` 及 Schema 返回的 camelCase 配置；旧 `subfield_updates` 只作迁移线索。 |
+| **`q_linker`** | 当前 AppForm 使用 `config.qLinkerBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
+| **`code_block`** | 当前 AppForm 使用 `config.codeBlockBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
 
 ### 6.1 数据标题与数据封面
 
-- `as_data_title: true`：配置应用数据标题。最终表单必须有且仅有一个顶层可读标题字段；推荐文本、编号、名称类字段。
-- `as_data_cover: true`：配置应用数据封面。可选，且只能用于一个顶层 `attachment` 字段。
+- 旧载荷的 `as_data_title` / `as_data_cover` 分别迁移为 AppForm 字段的 `dataTitle` / `dataCover`。最终表单必须有且仅有一个顶层可读标题字段；封面只能用于一个顶层 `attachment` 字段。
 - 子表子字段不能作为标题或封面；多标题、多封面、非附件封面都会在写入前阻断。
 - 未显式标记封面时保留/不创建封面；未能形成唯一标题时视为配置错误，不要声称应用已完整创建。
 
-**别名**：契约 **`aliases`** 会把 `field.title` / `field.label` 等映射到 **`name`**，把 `field.type_id` 映射到 **`type`**；契约 **`$.contract.allowed_values["field.type_aliases"]`** 会把自然字段类型映射到内部类型。主路径建议写上表自然类型，排障和读回时看 canonical 类型。
+**迁移提示**：旧契约中的 `aliases`、`field.type_id` 和 snake_case 配置不能替代当前 AppForm Schema。主路径以 pinned schema 的 camelCase 字段和类型详情为准。
 
 **`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` 场景矩阵、探针结论**：见 **[30-schema-fields.md](../30-schema-fields.md)**。**19 种搭建 `type` 单文件 `add_fields` 字段能力探针（不是正式新建应用主模板）**：[schema_apply_add_fields_all_types.json](../../examples/schema/schema_apply_add_fields_all_types.json)。
+**当前 21 种字段类型与 canonical 形状**：见 **[30-schema-fields.md](../30-schema-fields.md)**，以 pinned AppForm Schema 为准。下面的 `add_fields` 文件只是历史字段能力探针，不是正式新建应用主模板：[schema_apply_add_fields_all_types.json](../../examples/schema/schema_apply_add_fields_all_types.json)。
 
 ---
 
@@ -501,7 +508,7 @@ qingflow builder publish verify \
 ## 10. 交叉引用
 
 - **最小 `add_fields` 示例**：[schema_add_fields_minimal.example.json](../../examples/schema/schema_add_fields_minimal.example.json)
-- **19 种搭建 type 一次性 `add_fields`**：[schema_apply_add_fields_all_types.json](../../examples/schema/schema_apply_add_fields_all_types.json)
+- **历史字段 type 一次性 `add_fields` 探针（非当前主路径）**：[schema_apply_add_fields_all_types.json](../../examples/schema/schema_apply_add_fields_all_types.json)
 - **类型与场景总表**：[30-schema-fields.md](../30-schema-fields.md)
 - [SKILL.md](../../../SKILL.md)：`builder` 命令边界、**ADMIN** 指向。
 - [QINGFLOW_CLI_FIELD_DATA_TYPES.md](../../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)：成员侧 **记录读写** 的 `kind` / 值形态（与 **搭建 `type`** 名称不同系，但可对照理解业务）。

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

@@ -52,7 +52,7 @@
 | 入口 | 当前定位 |
 | --- | --- |
 | `builder app get` | 应用地图；轻量返回字段摘要、视图、图表、自定义按钮、关联资源池 |
-| `builder schema apply` | 字段/新建应用；多应用应用包用 `--apps-file`，同批 `relation` 用 `target_app_ref`；新建应用必须有且仅有一个 `as_data_title: true`；封面用顶层 `attachment` 字段 `as_data_cover: true` |
+| `builder app-form schema/get/validate/apply` | 当前表单/字段/布局/应用设置入口；固定 AppForm schema 版本，完整声明写入并保留现有 IDs；旧 `builder schema apply` / `builder layout apply` 仅为已移除的内部兼容适配器 |
 | `builder views apply` | 业务视图；固定筛选写 `filters`，前端查询栏写 `query_conditions` |
 | `builder button apply` | 自定义按钮默认路径；新增数据按钮用 `field_mappings/default_values`，绑定位置用 `header/detail/list` |
 | `builder associated-resource apply` | 应用级关联视图/报表池 + 视图展示配置；报表来源用 `report_source`，不让智能体填写后端 raw source |

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

@@ -2,7 +2,7 @@
 
 > **用途**：说明 **`record schema …`** 的 **`fields[]`**、**`record list` / `record get` / `record access`** 行内值、以及 **insert/update 写入 payload** 的常见对应关系；并单独说明 **选项联动、关联记录、引用填充、公式/系统题、AI 与受限类型** 等在 CLI 下的表现与处置。
 > **依据**：当前 CLI 在 **`--json`** 下会对 **schema** 响应做 **裁剪**：通常只保留本节列出的键；**`kind`** 由内部写入类别归并而来（见下表）。**`que_type` 等若未出现在输出中**，以 **`kind` + 实跑预检** 为准。
-> **关联**：写入值细节与成员/部门见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** **`app_schema_apply` 的 `type`（与本文 `kind` 命名体系不同）**见 **[30-schema-fields.md](../builder/30-schema-fields.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
+> **关联**：写入值细节与成员/部门见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** AppForm 的 `type`（与本文 `kind` 命名体系不同）及其 CLI 命令见 **[30-schema-fields.md](../builder/30-schema-fields.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
 
 ---
 

package/skills/qingflow-cli/reference/examples/README.md

@@ -4,9 +4,9 @@ Use these files as copyable bases after reading the matching resource document.
 
 | Resource | Main example | Notes |
 |----------|--------------|-------|
-| Single app schema | [schema/schema_single_app_form_standard.example.json](./schema/schema_single_app_form_standard.example.json) | `--form-file` shape; fields and form rows together. |
-| Multi-app schema | [schema/schema_multi_app_form_relation_layout.example.json](./schema/schema_multi_app_form_relation_layout.example.json) | `--apps-file` shape; same-batch relation and layout. |
-| Existing-app layout | [layout/layout_sections_full.example.json](./layout/layout_sections_full.example.json) | Existing-app maintenance only. New apps use `form`. |
+| Historical single-app schema probe | [schema/schema_single_app_form_standard.example.json](./schema/schema_single_app_form_standard.example.json) | Retired `--form-file` shape; use `builder app-form schema/get/validate/apply` for current declarations. |
+| Historical multi-app schema probe | [schema/schema_multi_app_form_relation_layout.example.json](./schema/schema_multi_app_form_relation_layout.example.json) | Retired `--apps-file` shape; current systems create independent AppForms and then bind confirmed app keys. |
+| Existing-app layout probe | [layout/layout_sections_full.example.json](./layout/layout_sections_full.example.json) | Historical layout-patch shape; current new and existing forms use the complete AppForm `spec.body`. |
 | Views | [views/views_upsert_table_minimal.example.json](./views/views_upsert_table_minimal.example.json), [views/views_batch_full.example.json](./views/views_batch_full.example.json) | `views[]` shape with filters, query panel, view-bound buttons, batch upsert/patch/remove. |
 | Charts | [charts/charts_upsert_dashboard_starter.example.json](./charts/charts_upsert_dashboard_starter.example.json) | Standalone chart apply; portal usually creates missing charts inline. |
 | Portal | [portal/portal_sections_standard_workbench.example.json](./portal/portal_sections_standard_workbench.example.json) | Standard workbench with inline QingBI charts and data views. |

package/skills/qingflow-common/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: qingflow-common
+description: Route Qingflow work through the shared public concepts and choose the matching CLI or MCP package. Use when comparing Qingflow CLI and MCP capabilities, selecting an execution surface, or handing work between record, task, form, workflow, and builder skills.
+---
+
+# Qingflow Common Concepts
+
+Treat CLI and MCP as two invocation surfaces for the same Qingflow public contract. Choose the surface that is installed in the current runtime, then keep the same business workflow and declaration shape unless that operation is explicitly surface-specific.
+
+## Choose A Surface
+
+| Available runtime | Use | Best fit |
+| --- | --- | --- |
+| Terminal, script, CI, or a local file workflow | Qingflow CLI | Repeatable commands and JSON files |
+| Agent has `qingflow-mcp` tools | Qingflow MCP | Records, tasks, packages, forms, views, workflows, portals, and builder configuration |
+
+Do not require both surfaces. If only one is installed, complete the workflow on that surface. Do not expose a CLI-only command as an MCP tool, or vice versa.
+
+## Shared Concepts
+
+- **AppForm** is the versioned declarative definition for an application form: app metadata, fields, sections, layout, settings, and field configuration. The same JSON declaration is used by CLI and Qingflow MCP.
+- **Record** is runtime data written to an existing app. Use the record schema before an insert, update, import, or analysis workflow.
+- **Task** is a workflow work item. Prefer task operations for approval, transfer, rollback, and assignee actions.
+- **Builder resource** is package, app, view, chart, portal, navigation, or workflow configuration. It is separate from record data.
+- **Schema version** is part of the public contract. Pin it for one AppForm or workflow operation and do not combine values from different versions.
+
+## Invocation Mapping
+
+| Business operation | CLI | MCP |
+| --- | --- | --- |
+| Form schema/read/apply/delete | `qingflow --json builder app-form ...` / `builder app delete` | `app_form_schema`, `app_form_get`, `app_form_apply`, `app_delete` |
+| AppForm static validation | `qingflow --json builder app-form validate --file ...` | Performed inside `app_form_apply`; no separate tool |
+| Record and task work | `qingflow --json record ...` / `task ...` | Qingflow MCP record and task tools |
+| Package, view, portal, chart, workflow | `qingflow --json builder ...` | Qingflow MCP configuration tools |
+
+The operation names and payload schemas are defined by the public surface. Use the current Schema or tool input schema as the source of truth, not a legacy command name or backend payload.
+
+## Package Boundaries
+
+- `@qingflow-tech/qingflow-cli` packages CLI execution guidance and CLI-supported workflows.
+- `@qingflow-tech/qingflow-mcp` packages every MCP Skill and exposes one unified MCP service. Record operations and system configuration are task routes in this service, not package or server choices.
+
+Each package includes this common Skill. The CLI package installs its CLI guidance; the MCP package installs every MCP domain Skill. The source of every packaged Skill is `qingflow-support/mcp-server/skills/`.
+
+## Route Next
+
+Use the installed package's relevant domain Skill. In the unified MCP package, select the Skill by the requested work, not by an assumed user or builder server role. Do not link to or invoke a domain Skill that the current package did not install.

package/skills/qingflow-common/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow Common Concepts"
+  short_description: "Route Qingflow work across CLI and MCP"
+  default_prompt: "Use $qingflow-common to choose the correct Qingflow CLI or MCP workflow."

package/src/qingflow_mcp/__main__.py

@@ -1,9 +1,8 @@
 """Entry point for running qingflow_mcp as a module.
 
-Default to the curated user-facing MCP surface. Split package and console
-entrypoints can still start the builder server explicitly.
+Start the unified Qingflow MCP surface.
 """
-from qingflow_mcp.server_app_user import main
+from qingflow_mcp.server import main
 
 if __name__ == "__main__":
     main()

package/src/qingflow_mcp/app_form_compat.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from .builder_facade.app_form_schema import AppFormContractError
+from .json_types import JSONObject
+
+
+TYPE_ALIASES = {
+    "multiline": "long_text",
+    "textarea": "long_text",
+    "radio": "single_choice",
+    "boolean": "single_choice",
+    "select": "single_select",
+    "dropdown": "single_select",
+    "checkbox": "multi_select",
+    "multi_choice": "multi_select",
+    "url": "link",
+    "hyperlink": "link",
+    "reference": "relation",
+    "quote": "relation",
+}
+FIELD_CONFIG_ALIASES = {
+    "options": "options",
+    "department_scope": "departmentScope",
+    "target_app_key": "targetAppKey",
+    "relation_mode": "relationMode",
+    "display_field": "displayField",
+    "visible_fields": "visibleFields",
+    "q_linker_binding": "qLinkerBinding",
+    "code_block_binding": "codeBlockBinding",
+}
+
+
+def normalize_app_form_declaration(payload: JSONObject) -> tuple[JSONObject, list[JSONObject]]:
+    """Normalize supported v1alpha1 compatibility aliases before Schema validation."""
+    result = deepcopy(payload)
+    warnings: list[JSONObject] = []
+
+    def visit(field: JSONObject, path: str) -> None:
+        raw_type = str(field.get("questionType") or field.get("type") or "").strip()
+        canonical_type = TYPE_ALIASES.get(raw_type, raw_type)
+        if canonical_type:
+            field["questionType"] = canonical_type
+        if "type" in field:
+            if "questionType" in field and str(field.get("type") or "").strip() != raw_type:
+                raise AppFormContractError("INVALID_SPEC", "conflicting aliases: type and questionType", path=path)
+            field.pop("type", None)
+        if canonical_type != raw_type and raw_type == "boolean":
+            warnings.append({"code": "LEGACY_BOOLEAN_NORMALIZED", "path": f"{path}/type"})
+
+        for old, new in (
+            ("required", "beingRequired"),
+            ("description", "questionDescription"),
+            ("default_type", "defaultType"),
+            ("default_value", "defaultValue"),
+            ("question_description", "questionDescription"),
+            ("question_type", "questionType"),
+            ("being_required", "beingRequired"),
+        ):
+            if old not in field:
+                continue
+            if new in field:
+                raise AppFormContractError("INVALID_SPEC", f"conflicting aliases: {old} and {new}", path=path)
+            field[new] = field.pop(old)
+
+        config = field.get("config")
+        if config is None:
+            config = {}
+        if not isinstance(config, dict):
+            return
+        for old, new in FIELD_CONFIG_ALIASES.items():
+            if old not in field:
+                continue
+            if new in config:
+                raise AppFormContractError("INVALID_SPEC", f"conflicting aliases: {old} and config.{new}", path=path)
+            config[new] = field.pop(old)
+        if raw_type == "boolean" and "options" not in config:
+            config["options"] = ["是", "否"]
+        if config:
+            field["config"] = config
+
+        if "fields" in field:
+            if "subfields" in field:
+                raise AppFormContractError("INVALID_SPEC", "conflicting aliases: fields and subfields", path=path)
+            field["subfields"] = field.pop("fields")
+        children = field.get("subfields")
+        for index, child in enumerate(children if isinstance(children, list) else []):
+            if isinstance(child, dict):
+                visit(child, f"{path}/subfields/{index}")
+
+    spec = result.get("spec")
+    for block_index, block in enumerate(spec.get("body") or [] if isinstance(spec, dict) else []):
+        if not isinstance(block, dict):
+            continue
+        rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+        for row_index, row in enumerate(rows):
+            if not isinstance(row, dict):
+                continue
+            for field_index, field in enumerate(row.get("fields") or []):
+                if isinstance(field, dict):
+                    visit(field, f"/spec/body/{block_index}/rows/{row_index}/fields/{field_index}")
+    return result, warnings