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

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.43
+npm install @qingflow-tech/qingflow-cli@1.1.44-beta.2
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.43 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.44-beta.2 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -38,10 +38,17 @@ qingflow
 
 首次安装时会自动初始化本地 Python 运行环境，随后提供 `qingflow` 命令行入口。
 
-## 内置 Skills
+## Bundled skills: 内置 Skills
 
+- `skills/qingflow-common`
 - `skills/qingflow-cli`
-- `skills/qingflow-mcp-setup`
+- `skills/qingflow-app-form`
+
+## Skill 分层
+
+该包通过 `qingflow-common` 提供公共概念和路由，并由 `qingflow-cli` 提供命令、JSON 文件和 CLI 专属静态校验说明。
+
+CLI 和 MCP 可以覆盖同一业务流程，但它们只是在调用方式上不同：公共 Skill 定义业务对象、声明契约和路由；领域 Skill 只描述当前包可执行的命令或 MCP 工具。统一 MCP 中的记录操作和系统搭建是任务路由，不是独立 MCP 服务。不要假定安装一个包就能调用另一个包的入口。
 
 ## Skills 安装
 
@@ -55,7 +62,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.43 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.44-beta.2 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。
@@ -63,5 +70,5 @@ npx -y -p @qingflow-tech/qingflow-cli@1.1.43 qingflow-skills install --agent cod
 ## 排障
 
 - 如果 npm 全局目录没有权限，推荐使用 `npx qingflow-cli@latest install`，安装器会自动 fallback 到用户目录。
-- 如果本地 MCP 客户端报 `Transport closed`，优先删除安装目录里的 `.npm-python` 后重新安装，并确认 CLI/user/builder 包版本一致。
+- 如果本地 MCP 客户端报 `Transport closed`，优先删除安装目录里的 `.npm-python` 后重新安装，并确认 CLI/MCP 包版本一致。
 - stdio MCP 入口不会在启动瞬间重建 Python 运行时，避免安装日志写入 stdout 破坏 MCP 握手。

package/entry_point.py

@@ -7,7 +7,7 @@ src_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
 if src_path not in sys.path:
     sys.path.insert(0, src_path)
 
-from qingflow_mcp.server_app_user import main
+from qingflow_mcp.server import main
 
 if __name__ == "__main__":
     main()

package/npm/bin/qingflow.mjs

@@ -5,8 +5,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const PKG_BY_BIN = {
   qingflow: "qingflow-cli",
-  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
-  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
+  "qingflow-mcp": "qingflow-mcp",
 };
 
 function resolvePackageModule(metaUrl, ...segments) {

package/npm/lib/runtime.mjs

@@ -8,8 +8,7 @@ const MIN_PYTHON_VERSION = [3, 11, 0];
 
 const PKG_BY_BIN = {
   qingflow: "qingflow-cli",
-  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
-  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
+  "qingflow-mcp": "qingflow-mcp",
 };
 
 function runChecked(command, args, options = {}) {
@@ -484,11 +483,8 @@ function getRuntimeProbeModule(commandName) {
   if (commandName === "qingflow") {
     return "qingflow_mcp.cli.main";
   }
-  if (commandName === "qingflow-app-user-mcp") {
-    return "qingflow_mcp.server_app_user";
-  }
-  if (commandName === "qingflow-app-builder-mcp") {
-    return "qingflow_mcp.server_app_builder";
+  if (commandName === "qingflow-mcp") {
+    return "qingflow_mcp.server";
   }
   return "qingflow_mcp";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.43",
+  "version": "1.1.44-beta.2",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",
@@ -16,10 +16,10 @@
     "pyproject.toml",
     "entry_point.py",
     "src/qingflow_mcp/**/*.py",
+    "src/qingflow_mcp/builder_facade/schemas/**/*.json",
     "src/qingflow_mcp/py.typed",
     "qingflow",
     "npm/",
-    "docs/local-agent-install.md",
     "skills/"
   ],
   "engines": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.43"
+version = "1.1.44b2"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
   "mcp>=1.9.4,<2.0.0",
   "httpx>=0.27,<1.0",
+  "jsonschema>=4.23,<5.0",
   "keyring>=25.5,<26.0",
   "openpyxl>=3.1,<4.0",
   "pydantic>=2.8,<3.0",
@@ -47,8 +48,6 @@ build = [
 ]
 
 [project.scripts]
-qingflow-app-user-mcp = "qingflow_mcp.server_app_user:main"
-qingflow-app-builder-mcp = "qingflow_mcp.server_app_builder:main"
 qingflow = "qingflow_mcp.cli.main:main"
 
 [project.urls]
@@ -64,7 +63,7 @@ Issues = "https://github.com/qingflow/qingflow-mcp/issues"
 where = ["src"]
 
 [tool.setuptools.package-data]
-qingflow_mcp = ["py.typed"]
+qingflow_mcp = ["py.typed", "builder_facade/schemas/app_form/**/*.json"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

package/skills/qingflow-app-form/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: qingflow-app-form
+description: Create, edit, validate, publish, verify, and recover Qingflow application forms through the versioned declarative AppForm surface. Use for app form fields, sections, layout, form settings, attachments, serial numbers, relations, Q-Linker, code blocks, package attachment, or explicit app deletion through either Qingflow CLI or Qingflow MCP. Do not use draft form reads for record operations or other published-schema consumers.
+---
+
+# Qingflow App Form
+
+AppForm is one shared declaration contract. Choose one execution surface and use it consistently for the operation; the JSON declaration, schema version, IDs, reconciliation, and recovery rules below are the same.
+
+| Step | Qingflow CLI | Qingflow MCP |
+| --- | --- | --- |
+| Schema | `qingflow --json builder app-form schema` | `app_form_schema` |
+| Read | `qingflow --json builder app-form get` | `app_form_get` |
+| Static validation | `qingflow --json builder app-form validate --file DECLARATION.json` | `app_form_apply` validates internally |
+| Apply | `qingflow --json builder app-form apply --file DECLARATION.json` | `app_form_apply(spec=DECLARATION)` |
+| Delete | `qingflow --json builder app delete --app-key APP_KEY` | `app_delete(app_key=APP_KEY)` |
+
+Before creating an app, let AppForm derive a stable default icon and color from `spec.appName`; do not add visual metadata to the declaration. `app_publish_verify` is retained only for an explicit final cross-resource verification; AppForm recovery never depends on it. For general surface selection, read [$qingflow-common](../qingflow-common/SKILL.md).
+
+## Workflow
+
+1. Read the AppForm Schema and pin its `schemaVersion` and `apiVersion` for the entire operation.
+2. Read the pinned field Schema for every canonical field type used, including subtable child types.
+3. When a field uses `defaultType: 3` or another config accepts a formula, read the pinned formula Schema with CLI `--schema-kind formula` or MCP `schema_kind="formula"`; use its field-reference, operator, and function catalog instead of inventing formula syntax.
+4. For an update, read the draft form with `being_draft=true`. Preserve every field, row, section, and subfield that should remain. For a create, build a declaration without `appKey` and with `packageId`, `spec.appName`, and complete `spec.body`; AppForm derives the icon and color from `spec.appName`.
+5. Keep existing `queId`, `sectionId`, `attachId`, and `aliasId` values from get. Omit them only for new resources. Treat `body`, `subfields`, explicit `attachments`, and custom serial-number `components` as complete target state.
+6. Save the declaration as JSON. In CLI, run `qingflow --json builder app-form validate --schema-version PINNED --file DECLARATION.json` before every apply and fix every reported pointer. In MCP, call apply directly; it performs the same declaration validation internally. YAML is not accepted.
+7. Apply the declaration on the selected surface. Record a newly returned `appKey` immediately. On success, show only `operation`, the non-empty `changes/actions` summary, and warnings. On any non-success result, show the recovery diagnostics, especially deleted/changed field names in `diff/remainingDiff`, and the failed phase.
+8. A successful apply has already read back the draft, verified the complete target, and verified the published form. Do not call get only to verify it again. For any non-success result, follow Recovery; never replay a saved backend payload or edit version.
+
+## Read Source
+
+- Use `being_draft=true` for editing and apply recovery.
+- Use the default published read for inspecting a live form, configuring another app's relation/Q-Linker, inserting or importing records, and every other consumption workflow.
+- Never expose draft-only fields to a published-schema consumer.
+
+## Identity And Deletion
+
+- `sectionId` is a positive decimal string. `queId`, `attachId`, and `aliasId` are positive integers.
+- A declaration with `appKey` updates. A declaration without `appKey` always creates a new app and must include `packageId` and `spec.appName`. Neither form accepts `spec.icon` or `spec.color`.
+- Repeating a create after losing its response can create a duplicate. Once an `appKey` is known, add it to the original declaration and recover as an update.
+- Update `packageId` only when the user wants to ensure that package references the app. It never removes other package references.
+- Removing an existing field from `body` or a child from `subfields` deletes it. Replace a field type in two explicit applies: delete, verify, then add the new type without the old `queId`.
+
+## Recovery
+
+- `EDIT_VERSION_CONFLICT`: read the latest draft, rebuild the complete declaration, validate, and retry once.
+- `APPLY_READBACK_MISMATCH`: read the latest draft, rebuild the complete declaration from that state, validate, and retry once.
+- `APPLY_RESULT_UNKNOWN`: read draft and published forms. Repair from the latest draft; if draft matches but published differs, reapply the same complete target so reconciliation performs publish only.
+- `PUBLISH_FAILED`: display `appPublishStatus` and `publishDetails`; resolve the backend validation or approval problem before retrying.
+- `EDIT_FINISHED_FAILED`: if published equals draft, call `app_release_edit_lock_if_mine`; do not publish again.
+- `RELATION_REBIND_FAILED`: read the draft, preserve returned IDs, and repair only unresolved bindings. Never recreate the app.
+- `PACKAGE_ATTACH_RESULT_UNKNOWN`: retain the same `appKey`, `packageId`, and full spec. Reapplying is safe because package attachment is ensure-present.
+- If an apply without `appKey` returns no `appKey` and reports `APP_CREATE_RESULT_UNKNOWN`, stop. Do not retry or search by name to guess the created app.
+
+## Constraints
+
+- Pin one Schema version; never combine details from different versions or silently upgrade recovery work.
+- Ordinary and section rows contain one to four fields. A section is its own outer block. Subtable columns use only the allowed subfield types returned by the subtable detail Schema.
+- Field declarations may set `defaultType` (`1` static, `2` relation/binding, `3` formula) and `defaultValue`; `defaultValue` is `string | null` because the backend `queDefaultValue` is a string, so numeric literals must be passed as strings. For `defaultType: 3`, query the same version with `--schema-kind formula` or `schema_kind="formula"` before composing the formula. Use `null` to clear a default. These properties also apply to subtable fields. Choice defaults belong in `config.defaultOptions`; address, attachment, subtable, and relation defaults belong in `config.defaultValues`. Omit a default when none is intended.
+- For `code_block`, when `config.codeBlockBinding.outputs` is non-empty, the `code` must explicitly assign `qf_output`, for example `qf_output = { score: input.score };`; `return {...}` alone does not satisfy output writeback, and each output `path` must point under `qf_output`.
+- A relation formula default is `config.defaultValueFormula` and must satisfy the pinned `relation` field Schema's `FormulaExpression`; do not infer its syntax from another version or from backend DTO names.
+- If widths are present, every field in that row must have one and the total must equal 100.
+- Keep declarations at or below 2 MiB and 64 object/array nesting levels. For a Q-Linker `json_path` input, set `key` to the selected field's exact name so get can reconstruct the placeholder losslessly.
+- Do not call CLI apply when the validation command fails. The command validates the local Schema plus declaration-only cross-field rules, including resolvable integration selectors, supported output target types, and globally unique Q-Linker/code-block output targets. It is not a dry run and does not read or modify Qingflow; checks that need current or external app state remain in apply. For MCP, resolve validation errors returned by `app_form_apply` before retrying.
+- Delete an application only after explicit user intent through the selected CLI or MCP delete operation.

package/skills/qingflow-app-form/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow App Form"
+  short_description: "Apply versioned declarative Qingflow app forms"
+  default_prompt: "Use $qingflow-app-form to safely create or update a Qingflow app form."

package/skills/qingflow-cli/SKILL.md

@@ -4,16 +4,18 @@ description: |
   【强制】在执行或编排任何 qingflow CLI 命令前必须优先加载本 Skill。
   Qingflow CLI 包以本 Skill 作为 CLI 主入口；record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。
   指导安装、执行上下文失败恢复、查询与写入；规定 task/record/import/builder 查询落盘；覆盖普通成员读数、字段 kind 与数据形态、任务上下文、批量导入、record access/list/get/insert/update/delete 与管理端边界。
-  Builder SOP 按智能体任务路径组织：完整系统、单应用、字段、已有应用布局维护、视图、报表、门户、关联资源、流程、发布校验；完整系统创建用 apps[].form 一次声明字段、relation 和布局；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读/批量写/局部改作为资源文档内的写法变体；明细见「关联文件」表与文末命令索引。
+  Builder SOP 按智能体任务路径组织：完整系统、单应用、AppForm、视图、报表、门户、关联资源、流程、发布校验；表单字段、分组、布局和应用设置统一使用 versioned AppForm；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读/批量写/局部改作为资源文档内的写法变体；明细见「关联文件」表与文末命令索引。
 ---
 
 # Qingflow CLI 使用技能
 
 > **Skill 版本**：`qingflow-skills-2026.07.01.04`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
 
+Use [$qingflow-common](../qingflow-common/SKILL.md) first when choosing between CLI and MCP. This Skill owns command-line invocation, JSON-file handling, and CLI-only validation; it does not redefine the underlying AppForm, record, task, or builder business contracts.
+
 **硬约束（必读）**：正文各节与文末「命令速查」中的命令**只作子命令形态索引**，不覆盖 JSON 结构、`--*-file` 键名、枚举全集、执行顺序与排障细节。凡工作**偏复杂**（多步串联、大块 payload、导入全链、**Builder 搭建向**（应用/schema/流程/布局/视图/门户/报表/按钮/关联资源的配置与发布、系统列与字段 `type`）、契约型 `apply`、按 schema 组织写入 payload、任务下钻与 `task action` 等），或你判断当前任务与「关联文件」里某篇所描述的内容**需求一致、场景相同或大体同类**，都应**先 Read 对应 `reference/...` 文档**，再结合 `qingflow … --help` 与 **[EXPLORATION_REPORT](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。**禁止**仅凭索引、习惯或类比去补参数、臆造字段名或推断服务端行为。**CLI 自动化场景只通过 `qingflow` 命令工作**；相关说明已按主题合并为本文档下的 `reference/` 子目录。**最终统计结论、分析报告、趋势/排名/比例/分布**统一走 **[record/analysis](./reference/record/analysis/README.md)** 的 `qingflow record access -> Python/pandas`。
 
-> **CLI**：当前实际执行包以 `qingflow --json version` 返回的 `package / version / command_path / executable_path / package_root / skill_version` 为准；不要从安装文档或全局 npm 目录猜版本。人工快速查看可用 `qingflow --version`。**复杂任务先读 [reference/00-INDEX.md](./reference/00-INDEX.md)**。**搭建/创建/系统配置**：先区分 **完整系统/应用包** 与 **单应用**。完整系统主链路必须走 `builder package apply -> builder schema apply --apps-file`，每个应用只用 `apps[].form` 同时声明字段、表单分组和行布局，并用 `apps[].client_key + relation.target_app_ref` 处理同批跨应用关联；不要拆成逐个应用创建、真实 `target_app_key` 回填、`add_fields` 追加或单独 `layout apply`。单应用新建走 `builder schema apply --package-id --app-name --form-file`，已有应用才走 `--app-key` 的维护路径。门户需要新报表时在 portal section 写 `chart`，不要把报表创建拆成完整系统主步骤。完整系统 schema apply 超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时，下一步固定是 **`readback_before_retry`**（`package get` / `app resolve` / `app get fields`），禁止直接拆成单应用重建、用 V2/测试/随机后缀绕过重名或重放整批创建；随后按 **[builder/README.md](./reference/builder/README.md)** 选择单应用、完整系统或具体资源文档。仅成员读数速通仍可先打开 **[MEMBER_CHEATSHEET](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**。
+> **CLI**：当前实际执行包以 `qingflow --json version` 返回的 `package / version / command_path / executable_path / package_root / skill_version` 为准；不要从安装文档或全局 npm 目录猜版本。人工快速查看可用 `qingflow --version`。**复杂任务先读 [reference/00-INDEX.md](./reference/00-INDEX.md)**。**搭建/创建/系统配置**：先区分 **完整系统/应用包** 与 **单应用**。应用表单、字段、分组、行布局和应用设置统一使用 versioned AppForm：先执行 `qingflow --json builder app-form schema` 固定版本；更新前执行 `qingflow --json builder app-form get --app-key APP_KEY --being-draft`；每次写入前执行 `qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json`，再执行 `qingflow --json builder app-form apply --file DECLARATION.json`。不要调用已移除的 `builder schema apply` / `builder layout apply`，也不要把旧 `--apps-file` / `--form-file` 当成当前主路径。完整系统先 `builder package apply`，再逐个 AppForm 创建并记录每个 `appKey`，最后用已确认的 app keys 配置关系、视图、门户和流程。门户需要新报表时在 portal section 写 `chart`，不要把报表创建拆成完整系统主步骤。AppForm apply 超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时，下一步固定是读取 draft/published form 后再恢复，禁止重复创建或用 V2/测试/随机后缀绕过重名；随后按 **[builder/README.md](./reference/builder/README.md)** 选择具体资源文档。仅成员读数速通仍可先打开 **[MEMBER_CHEATSHEET](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**。
 
 ## 关联文件
 
@@ -29,7 +31,7 @@ description: |
 | [reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) | **批量导入 SOP**：`app_get`（**`import_capability`**）→ `record_import_template_get` → `record_import_verify` →（可选）`record_import_repair_local` → `record_import_start` → `record_import_status_get`；CLI `import` / `record schema import`                                                   |
 | [reference/builder/README.md](./reference/builder/README.md) | **Builder 总导航**：完整系统、单应用、字段、布局、视图、报表、门户、按钮/关联资源、流程、发布校验 |
 | [reference/builder/10-build-single-app.md](./reference/builder/10-build-single-app.md) | **单应用搭建主入口**：一个应用端到端交付顺序 |
-| [reference/builder/20-build-complete-system.md](./reference/builder/20-build-complete-system.md) | **完整系统/应用包主入口**：多应用、同批 relation、门户闭环 |
+| [reference/builder/20-build-complete-system.md](./reference/builder/20-build-complete-system.md) | **完整系统/应用包主入口**：多应用、跨应用 relation、门户闭环 |
 | [reference/builder/30-schema-fields.md](./reference/builder/30-schema-fields.md) | **字段 / schema**：字段类型、直觉别名、数据标题/封面、schema 创建与更新 |
 | [reference/builder/40-layout.md](./reference/builder/40-layout.md) | **布局维护**：仅用于已有应用的分组、`rows` 矩阵、布局修复；新建应用布局写在 `form` 内 |
 | [reference/builder/50-views.md](./reference/builder/50-views.md) | **视图**：表格/卡片/看板/甘特、固定筛选、查询面板、视图 patch |
@@ -55,7 +57,7 @@ description: |
 
 **Builder 删除回读语义**：删除类 apply 要区分 **DELETE 是否已发出** 和 **删除是否已回读确认**。若结果里有 **`delete_executed=true`**，但 **`readback_status=unavailable|still_exists`**，不要盲目重复删除；记录 **`safe_to_retry_delete=false`**，稍后用对应读取工具确认。
 
-**Builder 写后回读语义**：`package apply/update`、`schema apply`、`portal apply`、`charts apply` 以及其它 builder apply 若返回 **`status=partial_success`** 且 **`write_executed=true` / `safe_to_retry=false`**，表示写动作已经发出或已成功，后续回读/发布校验可能被 40002、404、超时或元数据延迟阻挡。此时不要把结果解读为“未写入”；下一步是 **`readback_before_retry`**，只报告 **写入已执行，回读待确认**，并按 `verification.readback_unavailable`、`details.*readback_error`、`details.suggested_retry_payload`、`summary.write_executed` 做最终说明。完整系统 schema apply 的恢复只允许先读包、解析应用、读字段/关联；禁止未经读回就重放整批、拆成单应用重建、创建 V2/测试/随机后缀应用，或把同批 `target_app_ref` 改成未确认的 `target_app_key`。
+**Builder 写后回读语义**：`package apply/update`、`app-form apply`、`portal apply`、`charts apply` 以及其它 builder apply 若返回 **`status=partial_success`** 且 **`write_executed=true` / `safe_to_retry=false`**，表示写动作已经发出或已成功，后续回读/发布校验可能被 40002、404、超时或元数据延迟阻挡。此时不要把结果解读为“未写入”；下一步是 **`readback_before_retry`**，AppForm 先读 draft/published form，再只修复确认的差异；最终说明按 `verification.readback_unavailable`、`details.*readback_error`、`summary.write_executed` 组织。禁止未经读回就重放创建、拆成单应用重建、创建 V2/测试/随机后缀应用，或猜测未确认的 `appKey`。
 
 **Builder contract 读取路径**：`qingflow --json builder contract --tool-name ...` 成功时，真实契约固定在 **`$.contract`**；优先读返回的 **`json_paths`**。`allowed_keys` 是 `$.contract.allowed_keys`，`allowed_values` 是 `$.contract.allowed_values`，且 allowed_values 使用 **扁平 dotted key**，例如 `["field.type"]` / `["chart.chart_type"]`，不是嵌套对象。成功响应顶层 `allowed_values` 通常为空，不要从顶层取字段枚举。`builder icon catalog` 的候选固定读 `$.icon_names` / `$.icon_colors`。
 
@@ -135,7 +137,7 @@ qingflow --json auth whoami
 | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **task**   | `list`、`get`、`log`、`report`                                                                                                                                         |
 | **import** | `template`、`verify`、`repair`、`start`、`status`（**`verify` / `start` 链依赖本机 `~/.qingflow-mcp` 校验/任务落盘，自动化须开放写权限**） |
-| **builder** | **`app get`（summary/app map、fields、layout、views、flow、charts；summary 含 `custom_buttons` / `associated_resources`）**、`contract`；以及 **`schema apply` / `layout apply` / `views apply` / `button apply` / `associated-resource apply` / `flow apply` / `charts apply` / `portal apply` / `portal delete` / `publish verify` / `package apply`** 等大 JSON 响应 |
+| **builder** | **`app get`（summary/app map、fields、layout、views、flow、charts；summary 含 `custom_buttons` / `associated_resources`）**、`contract`、`app-form schema/get/validate/apply`；以及 **`views apply` / `button apply` / `associated-resource apply` / `flow apply` / `charts apply` / `portal apply` / `portal delete` / `publish verify` / `package apply`** 等大 JSON 响应 |
 | **record** | `list`、`get`、`logs`、`access`、`schema browse`；以及 `schema insert` / `schema update` / `schema import` / `schema code-block` 等大体积 schema 子命令（体量大时同上）；**创建前列字段时用 `schema insert` / `record_insert_schema_get` 同上**；**写操作 `insert` / `update` 响应体大时同样建议落盘** |
 
 
@@ -442,7 +444,7 @@ qingflow auth logout --forget-persisted
 | **app / portal / view / chart** | `app list [--query 关键词]` → **`app get --app-key`**（`accessible_views` / `view_id`、`import_capability`）· `builder package list [--query 关键词]` → `builder package get --package-id` · `portal list` · `portal get --dash-key` · `view get --view-id`（只读视图元信息；`baseInfo` 或 `viewConfig` 只有 40002 / 40027 / 404 这类权限/缺失边界可用另一侧降级，非权限类后端错误不隐藏；解析 app 仅依赖同源 view/form 与可见应用树，不回退旧应用搜索）· `chart get --chart-id`（图表 `baseInfo` / 数据 / 配置分阶段读取；单个辅助阶段 40002 / 40027 / 404 只作为 warning，非权限类后端错误不隐藏） |
 | **record** | `record schema insert`（新建记录 insert-ready schema，仅 `--app-key`）· **`browse`/`list`/`access`：`--app-key` + `--view-id`（缺一常 CONFIG）** · `record list --query ... [--query-field FIELD_ID] [--page-size N]` 用于候选定位/样本浏览 · `record get --record-id` 读详情页首屏上下文 · `record logs --record-id` 读完整数据/流程日志 JSONL · `record insert --items-file`（单条也是 items 一行）· `schema update --record-id [--view-id]` / **`update`**（单条 `--fields-file` **或** 批量 `--items-file`/`--dry-run`，二者勿混）· `record delete --app-key --record-id --view-id system:*` / `--record-ids-file` · `export start/direct --view-id` 仅用于明确导出文件 · **大 schema**：先 **[FIELD_DATA_TYPES](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)** / **[RECORD_CREATE](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)** / **[RECORD_UPDATE](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)** / **[RECORD_DELETE](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md)**，再 `-h` |
 | **import** | `record schema import?` · `import template` → `verify` → `repair?` → `start`（**`being-enter-auditing` 必填**）→ `status`（**三者 selector 只选一**）；导入权限预检的 `baseInfo` 只有 40002 / 40027 / 404 可降级为 unknown，非权限错误不能当成无导入权或继续执行；**链路与本机目录**只靠本节不够 → **[RECORD_IMPORT](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)** |
-| **builder** | **搭建／系统化配置**：先按 **[INDEX](./reference/00-INDEX.md)** / **[BUILDER](./reference/builder/README.md)** 选主路径，再读 `builder contract`。**完整系统/应用包**：`builder package apply --config-file` → `builder schema apply --apps-file`（唯一主写法 `{package_id, apps}`；每个应用写 `apps[].form`；同批 relation 只写 `target_app_ref` 指向 `client_key`；布局在 `form[].rows` 内，不单独提交）→ 视图（按钮随视图 `action_buttons` 写）→ 门户（缺报表时写 `chart`）→ 发布/回读。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先 `readback_before_retry`，不得直接拆单应用重建、重放整批或创建 V2/测试/随机后缀绕过重名。**单应用**：新建走 `schema apply --form-file`，再按需求配置流程/视图。更新动作归入对应资源文档：字段 [30](./reference/builder/30-schema-fields.md)、布局维护 [40](./reference/builder/40-layout.md)、视图 [50](./reference/builder/50-views.md)、报表 [60](./reference/builder/60-charts.md)、门户 [70](./reference/builder/70-portal.md)、关联资源/非主链路按钮维护 [80](./reference/builder/80-buttons-associated-resources.md)、流程 [90](./reference/builder/90-workflow.md)、发布 [99](./reference/builder/99-publish-verify.md)。 |
+| **builder** | **搭建／系统化配置**：先按 **[INDEX](./reference/00-INDEX.md)** / **[BUILDER](./reference/builder/README.md)** 选主路径，再读 `builder contract`。**完整系统/应用包**：`builder package apply --config-file` → 每个应用依次执行 `builder app-form schema`、更新时 `get --app-key APP_KEY --being-draft`、`validate --schema-version VERSION --file DECLARATION.json`、`apply --file DECLARATION.json`（固定版本、完整声明、记录返回的 `appKey`）→ 视图（按钮随视图 `action_buttons` 写）→ 门户（缺报表时写 `chart`）→ 发布/回读。旧 `schema apply` / `layout apply` 不在当前 CLI parser 中。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先读取 AppForm draft/published，再恢复，不得重复创建或创建 V2/测试/随机后缀绕过重名。**单应用**：新建和更新遵循同一 AppForm CLI 链路，再按需求配置流程/视图。更新动作归入对应资源文档：AppForm [30](./reference/builder/30-schema-fields.md)、视图 [50](./reference/builder/50-views.md)、报表 [60](./reference/builder/60-charts.md)、门户 [70](./reference/builder/70-portal.md)、关联资源/非主链路按钮维护 [80](./reference/builder/80-buttons-associated-resources.md)、流程 [90](./reference/builder/90-workflow.md)、发布 [99](./reference/builder/99-publish-verify.md)。 |
 | **task**（须落盘见上文） | `task list [--task-box][--flow-status][--app-key][--query] --page --page-size`（**枚举、`--query`、与 `record` 视图口径勿混**：见上文 SOP · **[TASK_CONTEXT](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)**）· **`get`/`log`/`report`/`action`**：默认只传 `task list` 返回的 **`data.items[].task_id`**；`report` 另须必选 **`--report-id`**；`action` **无 `--dry-run`** |
 
 **高发必败**：旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。

package/skills/qingflow-cli/manifest.yaml

@@ -1,6 +1,6 @@
 identity: qingflow_cli
 type: skill
-description: 「使用 qingflow CLI 的任何命令或自动化脚本前必须先调用本 Skill」。Qingflow CLI 包以本 Skill 作为 CLI 主入口；record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。涵盖安装、执行上下文失败恢复、task/record/import/builder 查询落盘规则、普通成员读数速通、record list 模糊定位、record get 详情上下文、record access 分析取数、record insert/update/delete/import、schema 字段类型、任务上下文 SOP。Builder reference 按智能体任务路径组织：单应用、完整系统/应用包、字段、已有应用布局维护、视图、报表/QingBI、门户、关联资源、流程、发布校验；完整系统创建主链路是 package apply -> schema apply --apps-file，使用 apps[].form 一次声明字段、relation 和布局；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读、批量写、局部改作为资源内写法变体；默认不把登录或工作区校验作为业务前置
+description: 「使用 qingflow CLI 的任何命令或自动化脚本前必须先调用本 Skill」。Qingflow CLI 包以本 Skill 作为 CLI 主入口；record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。涵盖安装、执行上下文失败恢复、task/record/import/builder 查询落盘规则、普通成员读数速通、record list 模糊定位、record get 详情上下文、record access 分析取数、record insert/update/delete/import、任务上下文 SOP。Builder reference 按智能体任务路径组织：单应用、完整系统/应用包、AppForm、视图、报表/QingBI、门户、关联资源、流程、发布校验；表单字段、布局和应用设置统一使用 versioned AppForm（CLI 为 builder app-form schema/get/validate/apply），不再使用已移除的 schema/layout apply；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读、批量写、局部改作为资源内写法变体；默认不把登录或工作区校验作为业务前置
 tags:
   - cli
   - qingflow

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

@@ -16,14 +16,14 @@ Use the current Qingflow CLI builder documents instead:
 Current complete-system 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
+package apply/get -> AppForm schema/get/validate/apply per app -> 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
 ```
 
 Current rules:
 
-- New complete-system apps use `apps[].form`; do not use `add_fields`.
-- Do not create a separate top-level layout object or call `builder layout apply` after creation just to place fields.
-- Same-batch relations use `client_key + target_app_ref`.
+- New apps use complete, version-pinned AppForm declarations; do not use the retired `apps[].form`, `add_fields`, or `--apps-file` schema adapters.
+- Do not call the retired `builder schema apply` or `builder layout apply` routes.
+- Create relation-independent apps first, then use confirmed target `appKey`s in complete AppForm declarations.
 - Business buttons are declared in view `action_buttons`.
 - Portal charts use the section `chart` field, either an existing `chart_id` or an inline QingBI definition.
 - Historical low-level notes live in [builder/reference/app-delivery-sop.md](./builder/reference/app-delivery-sop.md) and are for debugging only, not route selection.

package/skills/qingflow-cli/reference/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/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](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** **`app_schema_apply` 的 `type`（与本文 `kind` 命名体系不同）**见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**；主技能 **[../SKILL.md](../SKILL.md)**。
+> **关联**：写入值细节与成员/部门见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** AppForm 的 `type`（与本文 `kind` 命名体系不同）及其 CLI 命令见 **[builder/30-schema-fields.md](./builder/30-schema-fields.md)**；主技能 **[../SKILL.md](../SKILL.md)**。
 
 ---
 

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

@@ -8,9 +8,9 @@ Use the current builder schema document instead:
 
 Current main rules:
 
-- 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`.
+- New app creation and updates use the CLI AppForm commands: pin the version with `qingflow --json builder app-form schema`, build a complete declaration, validate it with `qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json`, then apply it with `qingflow --json builder app-form apply --file DECLARATION.json`.
+- For complete systems, create apps independently, retain every returned `appKey`, and add relations only with confirmed target app keys in later complete declarations.
+- New and existing apps use `spec.body` to express fields, sections, rows, and form settings together.
+- Do not use retired `builder schema apply`, `builder layout apply`, `--apps-file`, `--form-file`, or `--create-if-missing` paths.
 - 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

@@ -11,16 +11,16 @@ Not responsible for: multi-app relation modeling or a portal across several apps
 ## 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
+package/app resolve -> AppForm schema/get/validate/apply -> 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`.
+If a new package is needed, create it with `builder package apply --config-file`. Package JSON should contain only `package_name + icon + color`. Create or edit the app form with the CLI sequence in [30-schema-fields.md](./30-schema-fields.md): `builder app-form schema`, then `get --app-key APP_KEY --being-draft` for updates, `validate --schema-version VERSION --file DECLARATION.json`, and `apply --file DECLARATION.json`.
 
 ## Required reads by phase
 
 | Phase | Read |
 |-------|------|
-| Fields and app creation | [30-schema-fields.md](./30-schema-fields.md) |
+| Fields, form sections, layout, 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) |
@@ -32,7 +32,7 @@ Use the examples as file bases, then replace placeholder app/package ids and bus
 
 | Resource | Example |
 |----------|---------|
-| Single app form schema | [schema_single_app_form_standard.example.json](../examples/schema/schema_single_app_form_standard.example.json) |
+| Historical single-app schema probe | [schema_single_app_form_standard.example.json](../examples/schema/schema_single_app_form_standard.example.json) (retired `--form-file` shape; use the AppForm CLI sequence above for current declarations) |
 | 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) |
 
@@ -40,7 +40,7 @@ Use the examples as file bases, then replace placeholder app/package ids and bus
 
 - 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.
+- App creation and form edits use one complete, version-pinned AppForm declaration; preserve existing IDs on updates.
 - 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.

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

@@ -11,20 +11,19 @@ Not responsible for: single existing-app record CRUD. Use record documents from
 ## 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
+package apply/get -> AppForm schema/get/apply per app -> 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.
+- Create each app with `qingflow --json builder app-form schema`, `validate --schema-version VERSION --file DECLARATION.json`, and `apply --file DECLARATION.json`. Record every returned `appKey` before creating dependent relation declarations.
 - 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.
+- Pin one AppForm schema version per app and submit a complete declaration containing fields, sections, rows, and settings.
+- Do not call the retired `builder schema apply` or `builder layout apply` routes, and do not use their `add_fields`, `apps-file`, or `form-file` payloads as the current path.
+- For relations, create relation-independent apps first, read back their published `appKey`s, then submit complete declarations using the canonical relation shape and known target app keys.
 - 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.
+- Relation selectors use the AppForm camelCase shape, not bare strings: write `config.displayField: {"name":"产品编码"}` and `config.visibleFields: [{"name":"产品名称"}]`. `config.targetAppKey` must be a target app key confirmed by readback.
+- If AppForm apply times out or returns uncertain write state, perform draft/published form 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.
@@ -53,18 +52,19 @@ Use these examples as file bases, then replace placeholder package/app/view keys
 
 | 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) |
+| Historical multi-app schema probe (retired; migration reference only) | [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:
+AppForm command:
 
 ```bash
-qingflow --json builder schema apply --apps-file /abs/path/apps.json > tmp/schema_apply_system.json
+qingflow --json builder app-form validate --schema-version <SCHEMA_VERSION> --file /abs/path/app-form.json
+qingflow --json builder app-form apply --file /abs/path/app-form.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.
+If the write returns timeout or partial success, first read back the draft and published AppForm. Do not replay a create or guess an app by name; once an `appKey` is known, recover through a complete update declaration.
 
 ## Completion standard
 
@@ -72,8 +72,8 @@ A complete system is not just several created apps. Before reporting completion,
 
 - 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.
+- Cross-app relation fields are present where the business model needs them; each relation uses a confirmed `targetAppKey` and object selectors in `config.displayField` / `config.visibleFields`.
+- Core apps were created with complete AppForm declarations, 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[]`.