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

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.3
 ```
 
 推荐从官网复制这一条一键安装 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.3 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.3 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.3",
   "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.43b3"
 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, use `qingflow --json builder icon catalog` in CLI or `workspace_icon_catalog_get` in MCP only to select its icon and color. `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, select an explicit non-`template` icon candidate, then build a declaration without `appKey` and with `packageId`, `spec.appName`, `spec.icon`, `spec.color`, and complete `spec.body`.
 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
@@ -46,8 +56,8 @@ 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`; use the canonical value shape for the field type, and 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.
 - 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 format only; it is not a dry run and does not read or modify Qingflow. 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
 {
@@ -155,17 +155,17 @@ 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.type` 枚举和字段形状以固定版本的 **`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`。
 > **权限**：包内新建应用按后端 `CreateAppBean` 链路只预检目标包 **AddAppAuth**；已有应用的字段/基础信息变更才走应用自身 **EditAppAuth**。
@@ -232,7 +232,7 @@ 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` 类型详情为准；新声明不要使用这些别名。
 
 ---
 
@@ -278,10 +278,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`、显式 icon/color 和完整 `body` |
 | 多应用系统 | 每个 app 独立走 AppForm；先创建无关系 app，再用已确认 `appKey` 更新关系 | 不使用旧 `apps-file` 批量 schema 路径 |
-| 删除应用 | 显式用户意图 -> `app_delete` | 不通过字段删除 |
+| 删除应用 | 显式用户意图 -> `qingflow --json builder app delete --app-key APP_KEY` | 不通过字段删除 |
 
 ---
 
@@ -289,9 +289,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`**（契约内置形状） | `qingflow --json builder app-form schema --field-type TYPE` 返回的当前 AppForm 类型详情 |
 | 最小新建字段（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

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

@@ -1,10 +1,10 @@
 # Builder 应用交付重流程 SOP：分组 → 应用定位 → 读场 → 改场 → 发布校验
 
-本文是历史低层交付备忘，不是当前表单写入 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` 只用于识别旧载荷和迁移，不得直接调用。
+本文是历史低层交付备忘，不是当前表单写入 SOP。稳定 CLI 公开入口仍为 `qingflow builder` / `qingflow build`，但表单字段、分组、布局和设置必须使用 `qingflow --json builder app-form schema/get/validate/apply`，应用删除使用 `qingflow --json builder app delete --app-key APP_KEY`；本文件中的 `app_schema_apply` / `app_layout_apply` / `builder schema apply` / `builder layout apply` 只用于识别旧载荷和迁移，不得直接调用。
 
 > **权限**：应用基础信息（`app_name` / 图标 / 可见性）、表单、流程、自定义按钮本体、应用级关联资源池走 **应用搭建 / EditAppAuth**；视图更新/删除、按钮的视图位置配置（`view_configs`）和视图内关联资源展示配置走 **视图管理 / ViewManagementAuth**（后端 `beingViewManageStatus`；未开启高级应用权限时等价回落到 DataManageAuth）；**新建视图**额外需要 **DataManageAuth**；报表走 **数据管理 / DataManageAuth**。失败码常见 **40002 / 40161 / 编辑锁** 等，见主技能与 **ADMIN** 速查。
 
-> **契约**：当前表单契约固定通过 `app_form_schema` 获取；其它公开 `app_*_apply` 的 **`allowed_keys` / `allowed_values` / `execution_notes` / 示例** 以在线为准，命令：
+> **契约**：当前表单契约固定通过 `qingflow --json builder app-form schema` 获取；其它公开 `app_*_apply` 仅是 `builder contract --tool-name` 的参数值，**不是可执行 CLI 子命令**。其 **`allowed_keys` / `allowed_values` / `execution_notes` / 示例** 以在线契约为准，命令：
 > `qingflow --json builder contract --tool-name <app_flow_apply|app_views_apply|app_custom_buttons_apply|app_associated_resources_apply|app_publish_verify>`
 >
 > **CLI 文件载荷注意**：契约示例里可能出现 `"profile": "default"`，那是请求上下文示例；使用 CLI 的 `--*-file` 时不要把 `profile` 写进 JSON 文件。需要指定账号上下文时用根级参数：`qingflow --profile default ...`。
@@ -27,7 +27,7 @@
 | 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_form_apply`** | `qingflow --json builder app-form validate/apply --file …` | 完整 AppForm：字段、分组、行、设置和应用创建/更新 |
+| E | **AppForm** | `qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json` -> `qingflow --json builder app-form apply --file DECLARATION.json` | 完整 AppForm：字段、分组、行、设置和应用创建/更新 |
 | F | — | 由 AppForm 的 `body` 一并维护 | 表单段落 / 行 / 单元格随完整声明提交 |
 | G | **`app_flow_apply`** | `qingflow builder flow apply …` | **线性流程** 节点与转移（见契约限制） |
 | G′（维护） | **`app_custom_buttons_apply`** | `qingflow builder button apply …` | 仅用于用户明确要求维护已有独立按钮：样式/图标、跨视图复用、删除按钮本体或批量重排 |
@@ -120,9 +120,9 @@ qingflow --json builder app resolve \
 
 ### 3.2 单应用新建（历史 `app_schema_apply` 迁移说明）
 
-当前新建和更新请使用 sibling `qingflow-app-form` Skill；下方旧命令仅用于迁移脚本识别，不能执行。
+当前新建和更新请使用 `qingflow --json builder app-form schema/get/validate/apply`；下方旧命令仅用于迁移脚本识别，不能执行。
 
-历史脚本可能先读取图标候选；当前 AppForm 新建同样先按 sibling Skill 读取并固定合法图标和颜色：
+历史脚本可能先读取图标候选；当前 AppForm 新建同样先读取并固定合法图标和颜色：
 
 ```bash
 qingflow --json builder icon catalog
@@ -259,7 +259,7 @@ qingflow --json builder app get --app-key "<APP_KEY>" flow
 
 ## 5. 改场三口（历史 schema/layout 迁移说明 + 当前 flow）
 
-`app_schema_apply` / `app_layout_apply` 已从公开 MCP/CLI surface 移除。下方 schema/layout 命令只用于迁移旧脚本；当前表单和布局必须走 `qingflow-app-form` Skill。
+`app_schema_apply` / `app_layout_apply` 已从公开 MCP/CLI surface 移除。下方 schema/layout 命令只用于迁移旧脚本；当前表单和布局必须使用 `qingflow --json builder app-form schema/get/validate/apply`。
 
 ### 5.1 历史字段载荷：`builder schema apply`（仅迁移识别）
 
@@ -324,7 +324,7 @@ qingflow builder flow apply \
 
 ## 6. 字段类型迁移对照（旧 `app_schema_apply` 载荷）
 
-以下内容只帮助迁移旧载荷；当前字段类型、camelCase 配置和必填项以 pinned `app_form_schema` 为准。
+以下内容只帮助迁移旧载荷；当前字段类型、camelCase 配置和必填项以固定版本的 `qingflow --json builder app-form schema` 返回结果为准。
 
 智能体可优先写更自然的字段类型，工具会在写入前归一化；读回仍显示 canonical 类型：
 

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

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

@@ -4,7 +4,7 @@ Use these files as copyable bases after reading the matching resource document.
 
 | Resource | Main example | Notes |
 |----------|--------------|-------|
-| 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 single-app schema probe | [schema/schema_single_app_form_standard.example.json](./schema/schema_single_app_form_standard.example.json) | Retired `--form-file` shape; use `builder app-form schema/get/validate/apply` for current declarations. |
 | Historical multi-app schema probe | [schema/schema_multi_app_form_relation_layout.example.json](./schema/schema_multi_app_form_relation_layout.example.json) | Retired `--apps-file` shape; current systems create independent AppForms and then bind confirmed app keys. |
 | Existing-app layout probe | [layout/layout_sections_full.example.json](./layout/layout_sections_full.example.json) | Historical layout-patch shape; current new and existing forms use the complete AppForm `spec.body`. |
 | Views | [views/views_upsert_table_minimal.example.json](./views/views_upsert_table_minimal.example.json), [views/views_batch_full.example.json](./views/views_batch_full.example.json) | `views[]` shape with filters, query panel, view-bound buttons, batch upsert/patch/remove. |

package/skills/qingflow-common/SKILL.md

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

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

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