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

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`，但表单字段、分组、布局、设置和删除必须改用 sibling `qingflow-app-form` Skill 的 `app_form_schema/get/validate/apply/app_delete`；本文件中的 `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>`
+> **契约**：当前表单契约固定通过 `app_form_schema` 获取；其它公开 `app_*_apply` 的 **`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 | **`app_form_apply`** | `qingflow --json builder app-form validate/apply --file …` | 完整 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` 迁移说明）
 
-新建前如不确定图标候选，先读：
+当前新建和更新请使用 sibling `qingflow-app-form` Skill；下方旧命令仅用于迁移脚本识别，不能执行。
+
+历史脚本可能先读取图标候选；当前 AppForm 新建同样先按 sibling Skill 读取并固定合法图标和颜色：
 
 ```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-app-form` Skill。
 
-### 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 配置和必填项以 pinned `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` 命名体系不同）见 **[30-schema-fields.md](../builder/30-schema-fields.md)** 和 sibling **[qingflow-app-form Skill](../../../qingflow-app-form/SKILL.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 the `qingflow-app-form` Skill 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-mcp-setup/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow MCP Setup
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.07.01.04`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Overview
 

package/src/qingflow_mcp/app_form_compat.py

@@ -47,7 +47,12 @@ def normalize_app_form_declaration(payload: JSONObject) -> tuple[JSONObject, lis
         if canonical_type != raw_type and raw_type == "boolean":
             warnings.append({"code": "LEGACY_BOOLEAN_NORMALIZED", "path": f"{path}/type"})
 
-        for old, new in (("as_data_title", "dataTitle"), ("as_data_cover", "dataCover")):
+        for old, new in (
+            ("as_data_title", "dataTitle"),
+            ("as_data_cover", "dataCover"),
+            ("default_type", "defaultType"),
+            ("default_value", "defaultValue"),
+        ):
             if old not in field:
                 continue
             if new in field: