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

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.43-beta.2
+npm install @qingflow-tech/qingflow-cli@1.1.43-beta.4
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.43-beta.2 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.43-beta.4 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -40,9 +40,15 @@ qingflow
 
 ## Bundled skills: 内置 Skills
 
+- `skills/qingflow-common`
 - `skills/qingflow-cli`
 - `skills/qingflow-app-form`
-- `skills/qingflow-mcp-setup`
+
+## Skill 分层
+
+该包通过 `qingflow-common` 提供公共概念和路由，并由 `qingflow-cli` 提供命令、JSON 文件和 CLI 专属静态校验说明。
+
+CLI 和 MCP 可以覆盖同一业务流程，但它们只是在调用方式上不同：公共 Skill 定义业务对象、声明契约和路由；领域 Skill 只描述当前包可执行的命令或 MCP 工具。统一 MCP 中的记录操作和系统搭建是任务路由，不是独立 MCP 服务。不要假定安装一个包就能调用另一个包的入口。
 
 ## Skills 安装
 
@@ -56,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-beta.2 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.43-beta.4 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。
@@ -64,5 +70,5 @@ npx -y -p @qingflow-tech/qingflow-cli@1.1.43-beta.2 qingflow-skills install --ag
 ## 排障
 
 - 如果 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-beta.2",
+  "version": "1.1.43-beta.4",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,6 @@
     "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.43b2"
+version = "1.1.43b4"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -48,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]

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

@@ -1,20 +1,30 @@
 ---
 name: qingflow-app-form
-description: Create, edit, validate, publish, verify, and recover Qingflow application forms through the versioned declarative AppForm surface after MCP authentication. Use for app form fields, sections, layout, form settings, attachments, serial numbers, relations, Q-Linker, code blocks, package attachment, or explicit app deletion. Do not use draft form reads for record operations or other published-schema consumers.
+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
 
-Use `app_form_schema`, `app_form_get`, `app_form_apply`, and explicit `app_delete` for AppForm work. Before creating an app, use `workspace_icon_catalog_get` only to select its icon and color. `app_publish_verify` is retained only for explicit final cross-resource verification; AppForm recovery never depends on it.
+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. Call `app_form_schema()` and pin its `schemaVersion` and `apiVersion` for the entire operation.
-2. Call `app_form_schema(schema_version=PINNED, field_type=TYPE)` for every canonical field type used, including subtable child types.
-3. For an update, call `app_form_get(app_key=..., schema_version=PINNED, being_draft=true)`. Preserve every field, row, section, and subfield that should remain. For a create, call `workspace_icon_catalog_get` or `qingflow --json builder icon catalog`, select an explicit non-`template` candidate, then build a declaration without `appKey` and with `packageId`, `spec.appName`, `spec.icon`, `spec.color`, and complete `spec.body`.
+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. 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`.
 4. 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.
-5. Save the declaration as JSON, then run `qingflow --json builder app-form validate --schema-version PINNED --file DECLARATION.json` before every apply. Fix every reported pointer and rerun until `status=success`. YAML is not accepted.
-6. Call `app_form_apply(spec=DECLARATION)`. 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.
+5. 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.
+6. 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.
 7. 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
@@ -26,7 +36,7 @@ Use `app_form_schema`, `app_form_get`, `app_form_apply`, and explicit `app_delet
 ## Identity And Deletion
 
 - `sectionId` is a positive decimal string. `queId`, `attachId`, and `aliasId` are positive integers.
-- A declaration with `appKey` updates and must not contain `spec.icon` or `spec.color`. A declaration without `appKey` always creates a new app and must include `packageId`, `spec.appName`, `spec.icon`, and `spec.color`.
+- 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`.
@@ -46,8 +56,10 @@ Use `app_form_schema`, `app_form_get`, `app_form_apply`, and explicit `app_delet
 
 - 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`; use the canonical value shape for the field type, and use `null` to clear a default. These properties also apply to subtable fields. Omit them when no default is intended.
+- 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. 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 apply when the validation command fails. The command validates format only; it is not a dry run and does not read or modify Qingflow.
-- Delete an application only after explicit user intent by calling `app_delete(app_key=...)`.
+- 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-cli/SKILL.md

@@ -11,9 +11,11 @@ description: |
 
 > **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)**。**搭建/创建/系统配置**：先区分 **完整系统/应用包** 与 **单应用**。应用表单、字段、分组、行布局和应用设置统一走 sibling `qingflow-app-form` Skill 的 versioned AppForm：CLI 对应 `builder app-form schema/get/validate/apply`，写入使用完整声明文件；不要调用已移除的 `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)**。
+> **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)**。
 
 ## 关联文件
 
@@ -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 app-form schema/get/validate/apply --file`（固定版本、完整声明、记录返回的 `appKey`）→ 视图（按钮随视图 `action_buttons` 写）→ 门户（缺报表时写 `chart`）→ 发布/回读。旧 `schema apply` / `layout apply` 不在当前 CLI parser 中。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先读取 AppForm draft/published，再恢复，不得重复创建或创建 V2/测试/随机后缀绕过重名。**单应用**：新建和更新均走 AppForm Skill，再按需求配置流程/视图。更新动作归入对应资源文档：AppForm [qingflow-app-form](../qingflow-app-form/SKILL.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/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)**；**搭建侧** AppForm 的 `type`（与本文 `kind` 命名体系不同）见 **[builder/30-schema-fields.md](./builder/30-schema-fields.md)** 和 sibling **[qingflow-app-form Skill](../../qingflow-app-form/SKILL.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,7 +8,7 @@ Use the current builder schema document instead:
 
 Current main rules:
 
-- New app creation and updates use the sibling `qingflow-app-form` Skill: pin `app_form_schema`, build a complete declaration, validate it with `builder app-form validate --file`, then apply with `builder app-form apply --file`.
+- 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.

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

@@ -14,13 +14,13 @@ Not responsible for: multi-app relation modeling or a portal across several apps
 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`. Create or edit the app form through the sibling `qingflow-app-form` Skill; the CLI equivalent is `builder app-form schema/get/validate/apply`.
+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, form sections, layout, and app creation | [qingflow-app-form Skill](../../../qingflow-app-form/SKILL.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 |
 |----------|---------|
-| 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 `qingflow-app-form` Skill for current declarations) |
+| 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) |
 

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

@@ -16,7 +16,7 @@ package apply/get -> AppForm schema/get/apply per app -> app readback -> workflo
 
 ## Hard rules
 
-- Create each app through the sibling `qingflow-app-form` Skill. Record every returned `appKey` before creating dependent relation declarations.
+- 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`.
 - 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.

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -4,29 +4,29 @@ Read this when the task is about app creation fields, schema updates, field type
 
 ## Scope
 
-Responsible for: field modeling notes, AppForm field types, data title/cover, relation field shape, and routing form writes to the sibling `qingflow-app-form` Skill.
+Responsible for: field modeling notes, AppForm field types, data title/cover, relation field shape, and the CLI form write sequence.
 
 Not responsible for: record data operations. Form layout is part of the AppForm `spec.body`; do not use a separate schema/layout write path.
 
 ## Main chain
 
 ```text
-app/package resolve -> app_form_schema/get/validate/apply -> app get fields/layout readback -> publish/readback verify
+app/package resolve -> builder app-form schema -> draft get for updates -> validate declaration -> apply declaration -> app get fields/layout readback -> publish/readback verify
 ```
 
-For every app, use the sibling `qingflow-app-form` Skill with a pinned schema version and a complete declaration. The old `builder schema apply`, `--apps-file`, `--form-file`, and `add_fields/update_fields/remove_fields` routes are retired compatibility adapters, not current public commands.
+For every app, run `qingflow --json builder app-form schema` and pin the returned schema version. For an update, read `qingflow --json builder app-form get --app-key APP_KEY --being-draft`; validate the complete declaration 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`. The old `builder schema apply`, `--apps-file`, `--form-file`, and `add_fields/update_fields/remove_fields` routes are retired compatibility adapters, not current public commands.
 
 ## Demo files
 
 | Scenario | Example |
 |----------|---------|
-| AppForm declaration shape | [qingflow-app-form Skill](../../../qingflow-app-form/SKILL.md) |
+| AppForm declaration shape and CLI sequence | This document: [Create app with AppForm](#create-app-with-appform) and [AppForm scenario matrix](#3-appform-场景矩阵) |
 | Historical schema capability probe (not the current 21-type manifest) | [schema_apply_add_fields_all_types.json](../examples/schema/schema_apply_add_fields_all_types.json) |
 | Historical existing-app field capability probe | [schema_apply_add_fields_all_types.json](../examples/schema/schema_apply_add_fields_all_types.json) |
 
 ## Create app with AppForm
 
-The current creation shape is a complete AppForm declaration: `spec.body` contains fields, sections, rows, and settings. Pin `app_form_schema`, preserve IDs from `app_form_get(being_draft=true)`, validate, and apply through the sibling Skill. Do not call the retired schema/layout CLI adapters.
+The current creation shape is a complete AppForm declaration: `spec.body` contains fields, sections, rows, and settings. Pin the version with `qingflow --json builder app-form schema`. For updates, preserve IDs from `qingflow --json builder app-form get --app-key APP_KEY --being-draft`; validate and apply through the CLI commands above. Do not call the retired schema/layout CLI adapters.
 
 ```json
 {
@@ -34,15 +34,14 @@ The current creation shape is a complete AppForm declaration: `spec.body` contai
   "packageId": 123456,
   "spec": {
     "appName": "生产工单",
-    "icon": "clipboard-check",
-    "color": "green",
+    "dataTitleField": {"name": "工单编号"},
     "body": [
       {
         "kind": "section",
         "title": "基础信息",
         "rows": [
           {"fields": [
-            {"name": "工单编号", "type": "text", "dataTitle": true},
+            {"name": "工单编号", "type": "text"},
             {"name": "产品", "type": "text"},
             {"name": "状态", "type": "single_select", "config": {"options": ["待排产", "生产中", "已完工"]}}
           ]},
@@ -155,19 +154,19 @@ The following is retained only to recognize a historical `apps-file` payload. It
 
 - Re-read the published and draft AppForm before updating; preserve every field and ID that should remain.
 - Use complete AppForm target state for additions, edits, layout changes, and removals; never replay a partial field patch.
-- Use `app_form_validate` before every apply and follow AppForm recovery rules for uncertain write state.
+- Run `qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json` before every apply and follow AppForm recovery rules for uncertain write state.
 
 Current updates must be complete AppForm declarations. Start from
-`app_form_get(being_draft=true)`, keep the existing `appKey`/IDs, change the
+`qingflow --json builder app-form get --app-key APP_KEY --being-draft`, keep the existing `appKey`/IDs, change the
 desired `spec.body`, validate the complete declaration, and apply it. The old
 `add_fields`/`update_fields`/`remove_fields` patch shape is retired and is not a
 current CLI payload.
 
 ## Field type reference
 
-> **口径**：`field.type` 枚举和字段形状以固定版本的 **`qingflow --json builder app-form schema`** / `app_form_schema()` 返回结果为准；每个 canonical 类型还可用 `--field-type TYPE` 获取细节。不要从已退休的 `app_schema_apply` contract 推断当前 AppForm payload。
+> **口径**：`field.questionType` 枚举和字段形状以固定版本的 **`qingflow --json builder app-form schema`** 返回结果为准；每个 canonical 类型还可用 `--field-type TYPE` 获取细节。不要从已退休的 `app_schema_apply` contract 推断当前 AppForm payload。
 > **CLI**：表单写入使用 `qingflow [--profile NAME] --json builder app-form schema/get/validate/apply`；`validate/apply` 接受 `--file`，`get` 接受 `--app-key`。旧 `builder schema apply` 及 `builder layout apply` 不在当前 parser 的公开命令集合中。
-> **新建应用主规则**：`spec.body` 里必须有且仅有一个顶层字段标记 `dataTitle: true`；数据封面可选，只能在顶层 `attachment` 字段标记 `dataCover: true`。
+> **新建应用主规则**：`spec.body` 非空时必须用 `spec.dataTitleField` 唯一选择一个顶层字段作为数据标题；数据封面可选，只能用 `spec.dataCoverField` 选择顶层 `attachment` 字段。
 > **权限**：包内新建应用按后端 `CreateAppBean` 链路只预检目标包 **AddAppAuth**；已有应用的字段/基础信息变更才走应用自身 **EditAppAuth**。
 
 ## 0. 字段建模一眼决策表
@@ -176,7 +175,7 @@ current CLI payload.
 
 | 业务语义 | 推荐写法 | 注意 |
 | --- | --- | --- |
-| 名称、标题、编号、短文本 | `text` | 新建应用必须且只能有一个顶层可读字段标记 `dataTitle: true` |
+| 名称、标题、编号、短文本 | `text` | 非空表单必须通过应用级 `dataTitleField` 唯一选择一个顶层字段 |
 | 说明、备注、描述、长文本 | `long_text` | 多行文本 |
 | 状态、类型、等级、阶段、是否枚举 | `single_select` | 必须在 `config.options` 定义非空字符串数组 |
 | 标签、多选项、多个类别 | `multi_select` | 必须在 `config.options` 定义非空字符串数组 |
@@ -185,7 +184,7 @@ current CLI payload.
 | 日期、计划日、截止日 | `date` | 同时需要时分秒才用 `datetime` |
 | 负责人、审批人、参与人 | `member` | 不要创建“申请人/提交人”等平台系统字段 |
 | 部门、组织 | `department` | 可按需要补 `config.departmentScope` |
-| 图片、文件、附件 | `attachment` | 只有顶层 `attachment` 可标记 `dataCover: true` |
+| 图片、文件、附件 | `attachment` | 只有顶层 `attachment` 可被应用级 `dataCoverField` 选择 |
 | 跨应用业务对象关系 | `relation` | 使用已确认的 `targetAppKey`；`displayField` / `visibleFields` 必须写对象选择器 |
 
 禁止创建平台系统字段：`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。需要引用系统字段时，只在工具明确支持的位置引用，例如按钮 `source_field: "数据ID"`。
@@ -196,7 +195,7 @@ current CLI payload.
 
 固定 AppForm Schema 中可用的字段类型为：
 
-| `type` | 说明（搭建语义） |
+| `questionType` | 说明（搭建语义） |
 |--------|------------------|
 | `text` | 单行文本 |
 | `long_text` | 多行文本 |
@@ -232,20 +231,20 @@ current CLI payload.
 | `select` / `single_choice` / `dropdown` | `single_select` |
 | `multi_select` / `multi_choice` / `multiple_choice` / `checkbox` | `multi_select` |
 
-`boolean`、`multiline`、`select`、`checkbox` 等仅是兼容输入，归一化结果以 pinned `app_form_schema` 的类型详情为准；新声明不要使用这些别名。
+`boolean`、`multiline`、`select`、`checkbox` 等仅是兼容输入，归一化结果以固定版本的 `qingflow --json builder app-form schema --field-type TYPE` 类型详情为准；新声明不要使用这些别名。
 
 ---
 
 ## 2. 按类型的必填 / 常用可选（写意图）
 
-| `type` | 通常必填 | 常见可选 / 约束 |
+| `questionType` | 通常必填 | 常见可选 / 约束 |
 |--------|----------|-----------------|
-| 标量与选择器 | `name` + `type`（+ 业务 `required` 等） | `description`、`required`；新建应用时其中一个顶层可读字段须 `dataTitle: true`；**`single_select` / `multi_select` 的 `config.options` 是非空字符串数组**，如 `["A", "B"]` |
+| 标量与选择器 | `name` + `questionType`（+ 业务 `beingRequired` 等） | `questionDescription`、`beingRequired`；数据标题和封面在应用级 `dataTitleField/dataCoverField` 中选择；**`single_select` / `multi_select` 的 `config.options` 是非空字符串数组**，如 `["A", "B"]` |
 | `department` | 同左 | **`config.departmentScope`**：`mode: all \| custom`；`custom` 时 **`departments[]`**（含 `deptId` 等） |
 | `relation` | **`targetAppKey`**；另需 **`displayField`**、**`visibleFields[]`** | **`relationMode`**；目标应用元数据不可读时先读已发布表单，不要猜目标 key |
 | `subtable` | **`subfields[]` 非空** | 子列递归同父级规则；使用 Schema 返回的 camelCase 子字段配置 |
 | `q_linker` | **`config.qLinkerBinding`**：`inputs`、`request`、**`outputs[]` 每项须含 `targetField`**（能解析到本表单字段） | `request.url` 等须符合**租户/后端远程查询策略**；以字段类型 Schema 返回的配置为准 |
-| `code_block` | **`config.codeBlockBinding`**：`inputs`、`code`、**`outputs[]` + `targetField`**；代码体须能被规范识别 **`qf_output` 赋值** | 以字段类型 Schema 返回的 camelCase 配置为准 |
+| `code_block` | **`config.codeBlockBinding`**：`inputs`、`code`、**`outputs[]` + `targetField`**；配置 outputs 时，代码必须显式写 **`qf_output = {...}`**，仅 `return {...}` 不会产生可回写结果，且每个 `outputs[].path` 必须从 `qf_output` 取值 | 以字段类型 Schema 返回的 camelCase 配置为准 |
 
 别名：契约会把 `title`/`label` 映射到 **`name`** 等；字段类型自然别名见 §1.1。
 
@@ -268,6 +267,8 @@ current CLI payload.
 
 只在目标应用已经创建并通过 readback 确认后填写 `targetAppKey`。如果返回选择器校验错误，修复 `config.displayField` / `config.visibleFields`，不要重建应用或改 `appKey`。
 
+引用字段的公式默认值写在 `config.defaultValueFormula`，表达式必须符合固定版本 `relation` 字段详情中的 `FormulaExpression`。不要把后端 `referenceConfig` 字段名或其他 Schema 版本的公式写法直接放进声明。
+
 ### 2.2 工作流状态字段
 
 要启用工作流的应用，字段阶段就创建一个明确的业务状态单选字段，例如 `状态`、`处理状态`、`审批状态`、`工单状态`、`计划状态`、`报工状态`、`单据状态`。领域结果字段不等价于流程状态；例如质量场景的 `检验结论` 只能表达结果，仍建议另建 `处理状态` 用于流程节点、视图和报表。
@@ -278,10 +279,10 @@ current CLI payload.
 
 | 场景 | 当前入口 | 说明 |
 |------|----------------|------|
-| 编辑已有应用 | `app_form_get(being_draft=true)` -> `app_form_validate` -> `app_form_apply` | 保留完整 `body` 和现有 IDs；不要提交部分字段 patch |
-| 包内新建应用 | `app_form_schema` -> declaration without `appKey` -> `app_form_validate` -> `app_form_apply` | 须含 `packageId`、`spec.appName`、显式 icon/color 和完整 `body` |
+| 编辑已有应用 | `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` | 保留完整 `body` 和现有 IDs；不要提交部分字段 patch |
+| 包内新建应用 | `qingflow --json builder app-form schema` -> declaration without `appKey` -> `qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json` -> `qingflow --json builder app-form apply --file DECLARATION.json` | 须含 `packageId`、`spec.appName` 和完整 `body`;图标与颜色按应用名生成 |
 | 多应用系统 | 每个 app 独立走 AppForm；先创建无关系 app，再用已确认 `appKey` 更新关系 | 不使用旧 `apps-file` 批量 schema 路径 |
-| 删除应用 | 显式用户意图 -> `app_delete` | 不通过字段删除 |
+| 删除应用 | 显式用户意图 -> `qingflow --json builder app delete --app-key APP_KEY` | 不通过字段删除 |
 
 ---
 
@@ -289,9 +290,9 @@ current CLI payload.
 
 | 内容 | 位置 |
 |------|------|
-| **当前完整系统主示例** | [qingflow-app-form Skill](../../../qingflow-app-form/SKILL.md) |
+| **当前完整系统主入口** | [20-build-complete-system.md](./20-build-complete-system.md) |
 | **历史字段类型能力探针（不是新建主模板）** | [schema_apply_add_fields_all_types.json](../examples/schema/schema_apply_add_fields_all_types.json)（仅用于旧字段能力覆盖测试；当前新建和更新统一使用上文 AppForm） |
-| **`q_linker` / `code_block`**（契约内置形状） | `app_form_schema(field_type=...)` 返回的当前 AppForm 类型详情 |
+| **`q_linker` / `code_block` / relation 公式**（契约内置形状） | `qingflow --json builder app-form schema --schema-version VERSION --field-type TYPE` 返回的固定版本字段详情 |
 | 最小新建字段（1 个 text 标题字段） | [schema_add_fields_minimal.example.json](../examples/schema/schema_add_fields_minimal.example.json) |
 | 历史 scalar / complex 批测（可选） | [_batch_schema_scalar.json](../examples/schema/_batch_schema_scalar.json)、[_batch_schema_complex.json](../examples/schema/_batch_schema_complex.json) |
 

package/skills/qingflow-cli/reference/builder/40-layout.md

@@ -8,17 +8,17 @@ Responsible for: AppForm section titles, `rows` matrix, and existing-app layout
 
 Not responsible for: creating new apps, adding fields, or complete-system app creation. New apps must put layout directly in `spec.body` through [30-schema-fields.md](./30-schema-fields.md).
 
-Do not read this as a standalone CLI write path. For new or existing apps, edit the complete canonical AppForm `body` through the sibling `qingflow-app-form` Skill.
+Do not read this as a standalone CLI write path. For new or existing apps, edit the complete canonical AppForm `body` through the CLI AppForm sequence in [30-schema-fields.md](./30-schema-fields.md).
 
 ## Main chain
 
 ```text
-app_form_get(being_draft=true) -> edit spec.body sections/rows -> app_form_validate -> app_form_apply -> readback on recovery
+qingflow --json builder app-form get --app-key APP_KEY --being-draft -> edit spec.body sections/rows -> qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json -> qingflow --json builder app-form apply --file DECLARATION.json -> readback on recovery
 ```
 
 ## Demo file
 
-Use [layout_sections_full.example.json](../examples/layout/layout_sections_full.example.json) only as a historical layout probe. For current work, start from `app_form_get(being_draft=true)` and preserve the complete canonical declaration.
+Use [layout_sections_full.example.json](../examples/layout/layout_sections_full.example.json) only as a historical layout probe. For current work, start from `qingflow --json builder app-form get --app-key APP_KEY --being-draft` and preserve the complete canonical declaration.
 
 ## Canonical shape
 
@@ -64,7 +64,7 @@ Short rule: **form layout rows arrange fields; portal rows arrange components. D
 ## Update existing layout
 
 - Preserve the complete current AppForm body unless intentionally removing fields or sections.
-- Re-read `app_form_get(being_draft=true)` before writing; every field in rows must be retained with its canonical ID.
+- Re-read `qingflow --json builder app-form get --app-key APP_KEY --being-draft` before writing; every field in rows must be retained with its canonical ID.
 - If apply returns `partial_success` or layout validation details, read the draft and published forms before retrying.
 - There is no current batch layout CLI; update each app's complete AppForm independently.
 
@@ -75,4 +75,4 @@ Short rule: **form layout rows arrange fields; portal rows arrange components. D
 | `UNKNOWN_LAYOUT_FIELD` | Re-read the pinned AppForm Schema and draft; correct the field pointer. |
 | `DUPLICATE_LAYOUT_FIELD` | Keep each field in only one row in the complete AppForm body. |
 | `INCOMPLETE_LAYOUT` | Rebuild the complete body from the latest draft; do not submit a partial patch. |
-| repeated shape errors | Re-read `app_form_schema` for the pinned version and validate before apply. |
+| repeated shape errors | Re-run `qingflow --json builder app-form schema --schema-version VERSION` and validate before apply. |

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

@@ -1,6 +1,6 @@
 # Builder Index
 
-This directory is for Qingflow system-building work through `qingflow builder ...`. Form fields, form layout, form settings, and application deletion are owned by the sibling `qingflow-app-form` Skill.
+This directory is for Qingflow system-building work through `qingflow builder ...`. Form fields, form layout, form settings, and application deletion use the direct CLI commands documented in [30-schema-fields.md](./30-schema-fields.md).
 
 ## Choose the main path
 
@@ -28,7 +28,7 @@ package -> AppForm per app -> workflow if requested/needed -> views -> portal wi
 
 Rules:
 
-- Complete systems create apps through the sibling `qingflow-app-form` Skill, one complete declaration per app, and retain each returned `appKey`.
+- Complete systems create apps with `builder app-form schema`, `validate --schema-version VERSION --file DECLARATION.json`, and `apply --file DECLARATION.json`, one complete declaration per app, and retain each returned `appKey`.
 - Pin the AppForm schema version and preserve every existing field, section, row, and ID on updates.
 - Create relation-independent apps first; use confirmed target `appKey`s in later complete AppForm declarations.
 - The CLI commands for form work are `builder app-form schema`, `builder app-form get`, `builder app-form validate`, and `builder app-form apply --file`.
@@ -47,7 +47,7 @@ Rules:
 | [10-build-single-app.md](./10-build-single-app.md) | One-app delivery order and completion standard |
 | [20-build-complete-system.md](./20-build-complete-system.md) | Multi-app package delivery order and relation strategy |
 | [30-schema-fields.md](./30-schema-fields.md) | Field modeling notes and AppForm pointer |
-| [40-layout.md](./40-layout.md) | Retired layout-patch pointer; use the AppForm Skill for form layout |
+| [40-layout.md](./40-layout.md) | Retired layout-patch pointer; use the direct AppForm CLI sequence for form layout |
 | [50-views.md](./50-views.md) | Table/card/board/gantt views, filters, query panel, view patches, ordinary view action buttons |
 | [60-charts.md](./60-charts.md) | Standalone QingBI chart maintenance; portal dashboards normally use section `chart` for missing reports |
 | [70-portal.md](./70-portal.md) | Portal apply/delete, standard workbench layout, component config, section `chart` |

package/skills/qingflow-cli/reference/builder/code-integrations/README.md

@@ -55,7 +55,7 @@ For code block or Q-Linker work, use this order:
    - `qingflow builder app resolve`
    - `qingflow builder app get fields`
 2. Confirm the target field set already exists.
-3. Switch to the sibling `qingflow-app-form` Skill, preserve the complete declaration, validate it, and call `builder app-form apply --file`.
+3. Read the AppForm schema and the update draft, preserve the complete declaration, run `qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json`, then run `qingflow --json builder app-form apply --file DECLARATION.json`.
 4. Read the published AppForm again and verify:
    - field type
    - alias config