@qingflow-tech/qingflow-cli 1.1.61-beta.4 → 1.1.61-beta.6

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.61-beta.4
+npm install @qingflow-tech/qingflow-cli@1.1.61-beta.6
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.4 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.6 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -62,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.61-beta.4 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.6 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.61-beta.4",
+  "version": "1.1.61-beta.6",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.61b4"
+version = "1.1.61b6"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -70,6 +70,7 @@ qingflow_mcp = [
   "py.typed",
   "builder_facade/schemas/app_form/**/*.json",
   "builder_facade/schemas/views/**/*.json",
+  "builder_facade/schemas/portals/**/*.json",
 ]
 
 [tool.pytest.ini_options]

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

@@ -233,5 +233,5 @@ CLI 对外推荐使用 **`group_by` + `metric(s)`**；旧的 **`dimension_field_
 
 - [SKILL.md](../SKILL.md)  
 - [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)  
-- [QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)（**`chart_ref`**）  
+- [builder/70-portal.md](./builder/70-portal.md)（门户声明式主链与 **`chart` / `chart_ref`** 用法）  
 - [QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)（成员侧 **`kind`** 与搭建 **`type`** 对照理解业务）

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

@@ -1,263 +1,11 @@
-# Builder 门户创建与变更 SOP：`qingflow builder portal`
+# Builder Portal Workflow
 
-搭建侧稳定入口：**`qingflow builder portal`**：`list` / `get` / **`apply`** / **`delete`**（与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同，见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**）。
-
-实现要点来自 CLI 打包内的 `builder_facade/models.py`（`PortalApplyRequest`、`PortalSectionPatch`）、`builder_facade/service.py`（`portal_apply` / `portal_delete`）、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**：**新建**（`--no-publish`）、**`--publish` 更新**（网关 **503** 恢复后已重试成功）、**五类区块可稳定落库**；**`filter`（`type:6`）经 CLI 直传未落库** 见 **§3.4 / §8**。另已对测试包 **`1414907`** 实跑 **`portal delete`**：临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
-
-> **权限**：**更新**需 **`edit_portal`**；**新建**按后端 `DashCtrl.createDash` 链路只预检目标包 **`add_app`**，不额外要求包 **`edit_app`**。失败时参见主技能与 **ADMIN** 速查。
-
-> **契约**：`qingflow --json builder contract --tool-name portal_apply`；删除契约：`qingflow --json builder contract --tool-name portal_delete`
-
----
-
-## 1. 读：`list` → `get`
+旧文已并入 [builder/70-portal.md](./builder/70-portal.md)。门户创建/更新走声明式主链（版本化 `--file` 声明 + 离线 validate + 唯一 apply 入口）：
 
 ```bash
-qingflow --json builder portal list > tmp/builder_portal_list.json
-
-qingflow --json builder portal get --dash-key "<DASH_KEY>" > tmp/builder_portal_get.json
-qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
-```
-
-- **`list`** 可能带 **`PORTAL_PERMISSION_READ_UNAVAILABLE`**，**`verified: false`** 仍可能有可用 **`items[]`**。
-- **`get`**：**`--dash-key`** 必填；默认 **`--being-draft`** 为草稿。
-
----
-
-## 2. 写：`apply` 两种模式（互斥）
-
-**不可同时**出现 **`--dash-key`** 与 **`--package-id`**。
-
-| 模式 | 必备参数 | 含义 |
-|------|----------|------|
-| **新建** | **`--package-id`** + **`--dash-name`** | **`--sections-file` 须非空**。 |
-| **更新** | **`--dash-key`** | 不要带 **`package_id`**。 |
-
-| 参数 | 说明 |
-|------|------|
-| **`--publish` / `--no-publish`** | 默认 **`--publish`**。仅 **`--no-publish`** 时不会调用发布接口；契约说明 **`publish=false` 不宣称线上已变**。 |
-| **`--payload-file`** | 完整门户 JSON 对象；**标准字段写 `dash_name`**。新版 CLI 兼容 **`name -> dash_name`**、单页 **`pages[0].components -> sections`**，但 agent 默认不要依赖兼容别名。 |
-| **`--sections-file`** | JSON **数组**；**全量替换**。省略时仅改基础信息，且 **`hide_copyright` / `dash_global_config` / `config`** 不能单独提交（**`PORTAL_SECTIONS_REQUIRED`**）。 |
-| **`--layout-preset`** | 可选：**`auto` / `dashboard_2col` / `dashboard_3col`**。当区块未显式写 **`position`** 时由工具生成大屏布局。 |
-| **`--visibility-file`** | 与 **`--auth-file`** 不能同时用。 |
-| **`--icon`** / **`--color`** | 新建门户必须显式传合法的非 `template` 图标和颜色；候选用 `qingflow --json builder icon catalog`。编辑已有门户时省略则保留现状。 |
-| **`--hide-copyright`** / **`--dash-global-config-file`** / **`--config-file`** | 见契约；部分键 **依赖与 `sections` 同批提交**。 |
-
-**图标规则**：CLI 不按门户名自动猜图标；智能体需要自行选择业务贴合的 `icon + color`。读回结果里的 `icon_config` 可直接用于前端资源卡片展示。
-
----
-
-## 3. `sections[]`：六类组件与回读 `type`
-
-### 3.1 公共键
-
-- **`title`**（必填）、**`source_type`**（必填，小写）、可选 **`position`**（**`pc`/`mobile`** 各 **`x,y,cols,rows`**；省略则由**实现自动排布**）。
-- **`config`**、**`dash_style_config`**：按类型 Optional。默认只写 snake_case 规范键。
-
-### 3.1.0 Payload 字段口径
-
-推荐完整 payload 直接使用 CLI 标准键：
-
-```json
-{
-  "dash_name": "产品研发数据大屏",
-  "package_id": 1414909,
-  "layout_preset": "dashboard_2col",
-  "pages": [
-    {
-      "title": "研发总览",
-      "components": [
-        {
-          "title": "部门分布",
-          "source_type": "chart",
-          "chart_ref": {"app_key": "APP_KEY", "chart_id": "CHART_ID"}
-        }
-      ]
-    }
-  ]
-}
+qingflow --json builder portal get --dash-key DASH_KEY --schema-kind complete > portal.json   # 更新前先读
+qingflow --json builder portal validate --file portal.json                                   # 零后端离线校验
+qingflow builder portal apply --file portal.json --schema-version v1alpha1 [--dash-key DASH_KEY] [--no-publish]
 ```
 
-`name` 只是兼容别名；如果遇到旧版 CLI 报 **`name Extra inputs are not permitted`**，不要反复重试，改成 **`dash_name`** 或升级 CLI。
-
-### 3.1.1 布局硬规则：PC 24 栅格，mobile 6 栅格
-
-**门户 PC 端不是 12 栅格，而是 24 栅格。**如果把两列写成 **`x=0/6, cols=6`**，所有组件只会占左半屏，工具会返回 **`PORTAL_LAYOUT_HALF_WIDTH`**。
-
-推荐：
-
-| 场景 | PC 写法 |
-|------|---------|
-| 不确定布局 | **省略 `position`**，或传 **`--layout-preset auto`** |
-| 两列可视化图表 | **`x=0/12, cols=12`**，图表 **`rows >= 7`** |
-| 三列可视化图表 | **`x=0/8/16, cols=8`**，图表 **`rows >= 7`** |
-| 四个指标卡 | **`x=0/6/12/18, cols=6, rows=5`** |
-| 具体数据视图 / 明细表 | 优先 **`cols=12`** 或 **`cols=24`**，视图 **`rows >= 11`** |
-
-mobile 写法固定按 **6 栅格**：通常 **`x=0, cols=6`**。如果只写了 PC position，CLI 会自动补 mobile position，并返回 **`PORTAL_MOBILE_POSITION_MISSING`** 提醒。
-
-图表卡片过小时会返回 **`PORTAL_CHART_CARD_TOO_SMALL`**；指标卡按 **`pc.cols >= 6, pc.rows >= 5`** 校验，普通可视化图表按 **`pc.cols >= 8, pc.rows >= 7`** 校验。指标区图表建议写 `role: "metric"`；此时必须引用 `target` / `indicator` 图表，否则返回 **`PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH`**，应先用 `app_charts_apply` 创建缺失指标卡再组门户。标准工作台数量也会进入 `layout_diagnostics.standard_template_counts`：指标卡推荐 4-6 个、BI 图表 2-3 个、业务视图 1-2 个，超出或不足会返回 `PORTAL_STANDARD_*_COUNT_OUT_OF_RANGE`。
-
-### 3.1.2 推荐门户模板：业务工作台
-
-默认按 **业务入口 → 核心指标 → BI 可视化 → 业务视图** 搭建。门户首屏应直接呈现可用工作台，不要做营销页、说明页或大面积装饰区。
-
-| 区域 | 推荐组件 | PC 布局 | 要点 |
-|------|----------|---------|------|
-| 顶部业务入口 | **`grid`** + 可选 **待办 `task`** | `grid x=0,y=0,cols=12,rows=4`；待办 `x=12,y=0,cols=12,rows=4` | `grid` 放 2-6 个核心业务入口；待办用于当前用户任务概览。当前公开 `portal apply --sections-file` 暂未支持 `source_type=task`，不要伪造；见下方边界说明。 |
-| 核心指标 | **`chart`** 指标卡 + `role: "metric"` | 4 张：`x=0/6/12/18,y=4,cols=6,rows=5` | 指标卡推荐高度 **5**。24 栅格下单卡最小 `cols=6`，所以一行 4 张最稳；如果要 5 个指标，拆成两行。 |
-| BI 可视化 | **`chart`** 图表 | 3 张：`x=0/8/16,y=9,cols=8,rows=7`；或 2 张：`x=0/12,cols=12,rows=7` | 可视化图表推荐高度 **7**，一行 2-3 个，1-2 行。 |
-| 业务数据视图 | **`view`** | `x=0/12,y=16,cols=12,rows=11`；或单表 `cols=24,rows=11` | 数据视图推荐高度 **11**，一行 1-2 个，1-2 行。只挂业务视图，不要创建或引用默认的 **全部数据 / 我的数据** 当主门户视图。 |
-
-mobile 固定按 **6 栅格** 从上到下堆叠：通常所有组件 `x=0, cols=6`，`y` 按 PC 顺序递增。若顶部同时有 `grid + task`，mobile 建议先业务入口 `y=0,rows=4`，再待办 `y=4,rows=4`，核心指标从 `y=8` 开始；若当前公开 CLI 只能写 `grid`，核心指标可从 `y=4` 开始。
-
-**当前工具边界**：
-
-- 公开 `sections-file` 稳定支持：**`grid` / `chart` / `view` / `text` / `link`**；`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理，不作为主路径。
-- **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状，不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`；只有工具后续显式支持 `task`，或维护者走 raw 门户写入链路时，才使用待办槽位。
-- 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)**。该示例使用当前公开 CLI 可稳定写入的组件，顶部先用一个业务入口 `grid` 占满 24 栅格；如果工具已支持待办组件，再把顶部拆成 `grid cols=12 + task cols=12`。
-- `grid` 必须写 **`config.items[]`**；只写 `gridTitle` / `beingShowTitle` 会生成空入口容器，工具会返回 **`PORTAL_GRID_ITEMS_EMPTY`**。
-
-**待办组件 raw 形状参考**（仅用于工具实现对齐，当前不要作为 `--sections-file` 输入）：
-
-```json
-{
-  "type": 8,
-  "position": {
-    "pc": {"x": 12, "y": 0, "cols": 12, "rows": 4},
-    "mobile": {"x": 0, "y": 4, "cols": 6, "rows": 4}
-  },
-  "taskConfig": {
-    "beingShowTitle": true,
-    "componentTaskTitle": "待办",
-    "beingShowHint": true,
-    "componentTaskHint": "及时处理待办，可以有效提升流程效率",
-    "dashTaskConfigList": [
-      {"type": 1, "title": "all.taskTodo", "beingCheck": true, "ordinal": 0},
-      {"type": 2, "title": "all.taskTimeout", "beingCheck": true, "ordinal": 1},
-      {"type": 3, "title": "all.taskUpcomingTimeout", "beingCheck": true, "ordinal": 2},
-      {"type": 4, "title": "all.taskRemind", "beingCheck": true, "ordinal": 3}
-    ]
-  }
-}
-```
-
-### 3.2 `source_type` ↔ 回读 `components[].type`（搭建侧）
-
-| `source_type` | 回读 `type`（数字） | 搭建侧含义 |
-|---------------|---------------------|------------|
-| **`chart`** | **9** | QingBI 图表块 |
-| **`view`** | **10** | 应用视图块 |
-| **`grid`** | **2** | 九宫格 |
-| **`filter`** | **6** | 筛选条 |
-| **`text`** | **5** | 富文本说明 |
-| **`link`** | **4** | 外链 |
-
-CLI 校验（`PortalSectionPatch`）：**chart** 须 **`chart_ref`**；**view** 须 **`view_ref`**；**text** 须 **`text`**；**link** 须 **`url`**。**grid** / **filter** 无额外 ref，**`config` 形状由后端接受为准**。
-
-### 3.3 **`chart`**：几乎总须 **`builder charts apply` 先建报表**
-
-- `portal` 只做 **`chart_ref` 解析**（`app_key` + **`chart_id`** 优先，否则 **唯一 `chart_name`**）。
-- 若 **`builder app get charts`** 为空，先 **`builder charts apply --app-key … --upsert-file`** 创建（契约 **minimal_example** 如 **`target` + `indicator_field_ids: []`**），从响应 **`chart_results[].chart_id`** 取 id 再写 **`chart_ref`**.
-
-### 3.4 **`filter`**：`config` **整包**即接口里的 **`filterConfig`**
-
-实现：组件为 **`{"type": 6, "filterConfig": deepcopy(section.config)}`**。
-
-- **理论上**与 solution 编译器一致：外层 **`{"filterConfig": [ … ], "graphList": [ … ]}`**；**`graphList`** 常含 **`graphType`**（如 **`CHART`**）、**`graphKey`** 或 **`graphRef`（`entity_id` / `chart_id`）** 等。
-- **本环境 CLI 直写实测（多次 `--publish`）**：在已验证 **chart / view / grid / text / link** 均可落库的前提下，**`source_type: filter` 始终未出现在 `draft_result.components` 中**；尝试过：**空数组**、**仅 `graphList` + QingBI `chart_id`**、**`graphKey` 为门户 `dashChartId`**、**`chart` 排在 **`filter` 前**、**仅 2 块（chart+filter）** 等，回读仍 **只有 chart（`count: 1`）** 或 **五类缺 `type: 6`**。  
-  **结论**：当前宜 **在搭建界面创建筛选条**，再 **`builder portal get` 反抓** 原始 `filterConfig` 形状；或向后端确认 **POST `/dash/{dashKey}`** 对 **`type: 6`** 的必填字段。**自动化不要默认认为 `filter` 已写入。**
-- portal `filter` 组件仍按 raw `filterConfig` 处理，不纳入视图 / 报表 / 关联资源的统一筛选 DSL 主链路。
-
-### 3.5 **`grid` / `text` / `link` / `view`**
-
-- **grid**：**`config`** 并入 **`gridConfig`**；业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`。空 `config` 或空 `items` 只会生成空入口容器，并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
-- **text** / **link**：**`text`** / **`url`** 必填。
-- **view**：**`view_ref`**；**`view_key`** 来自 **`builder app get views`**。
-
----
-
-## 4. 前置数据
-
-| 目的 | 命令 |
-|------|------|
-| **`package_id`** | **`builder app resolve --app-key …`** → **`package_ids`** |
-| **`view_key`** | **`builder app get --app-key … views`** |
-| **`chart_id`** | **`builder app get charts`** 或 **`charts apply` 创建** |
-
----
-
-## 5. 新建最小例（`--no-publish`）
-
-见上文 **§2** 与 **`visibility`** 最小对象；**`sections`** 可先用 **单块 `view`**。成功后拿 **`dash_key`** 再 **更新 / 发布**。
-
----
-
-## 6. 更新与替换语义
-
-- **`--dash-key`** + **`--sections-file`**：**列表即全量**；没写进去的区块会被拿掉。
-- 仅改 **可见性 / 图标 / 分组**：**不传 `--sections-file`**，且不要单独带 **§2** 所列「仅在有 sections 时允许」的键。
-
----
-
-## 7. 删除：`delete`
-
-```bash
-qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_portal_delete.json
-```
-
-- **只按 `dash_key` 删除一个门户**；先用 `builder portal list/get` 确认目标，不要按名称猜。
-- 返回成功时重点看：**`delete_executed`**、**`readback_status`**、**`safe_to_retry_delete`**、`summary.removed`。
-- **`delete_executed=true` + `readback_status=deleted`**：删除已执行且回读确认不存在。
-- **`delete_executed=true` + `readback_status=unavailable|still_exists`**：DELETE 已发出，但回读不可确认或短时间仍存在；**不要盲目重复删除**，稍后用 `builder portal get/list` 确认。
-- DELETE 本身失败时才按 `status=failed` / `error_code` 处理。
-
----
-
-## 8. **发布**（`--publish`）
-
-- **默认会发布**：未显式 **`--no-publish`** 即 **`publish: true`**；公开入口仍是 **`portal_apply`**，发布动作由工具内部执行并回读 **`being_draft=false`**。
-- **已发布线索**：成功路径上 **`published: true`**；**`live_result.publishStatus`** 常见 **`2`** 表示已发布（以你环境枚举为准）。
-- **`partial_success` + `PORTAL_READBACK_PENDING`**：草稿/线上 **组件数量或元数据** 与「本次期望」不一致时会出现；**`PORTAL_*_VERIFICATION_INCOMPLETE`** 警告。应 **`builder portal get --dash-key …`**（草稿与 **`--no-being-draft` 线上**）**肉眼核对**区块是否齐全，而不是仅信 **`verified: true`**。
-- **网关 503**：**与 CLI 无关**；环境恢复后重试 **`portal get` / `portal apply`**。（本轮在网关恢复后 **`portal apply` 已成功**。）
-
----
-
-## 9. 本环境实测摘要
-
-| 步骤 | 命令要点 | 结果 |
-|------|-----------|------|
-| 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、`--no-publish`、单 **view** | **`dash_key`: `ecdcell64s02`** |
-| 补报表 | **`builder charts apply`**，`name: 门户探针_目标图`，**`target`** | **`chart_id`: `mcp_fb104267c5c249ca`** |
-| 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**；**`filter` 仍不落库** → **`partial_success`**，**`components expected 6, got 5`**（与 **§3.4** 一致） |
-| **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合 | **回读恒为 1 块（仅 `type: 9`）** |
-| **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](./portal_sections_five_types.example.json)**（**grid / text / link / view / chart**） | **`status: success`**，**`types: [2,4,5,9,10]`**，**`published: true`** |
-| 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**，**`delete_executed: true`**，**`readback_status: deleted`**，**`summary.removed: 1`** |
-
-**推荐工作台模板示例**：[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)
-
-**含 `filter` 的六类示例（`filter` 是否落库视环境/后端而定）**：[portal_sections_all_types.example.json](./portal_sections_all_types.example.json)
-
----
-
-## 10. 排障
-
-| 现象 | 处理 |
-|------|------|
-| `portal apply accepts exactly one selector mode` | **`dash-key`** vs **`package-id`** 二选一。 |
-| `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件；若多写了 **`filter`** 而回读少一块，见 **§3.4**（**CLI 写 filter 可能整体不生效**）；也可能是 **异步回读**，可再 **`get`** 一次。 |
-| **`published: true` 但 `verified: false`** | 读 **§7**；用 **`get` 草稿+线上**对照。 |
-| **503** | 网关/运维；稍后重试。 |
-| 缺 **chart** | **[QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)**：`builder charts apply`；或换有报表的应用。 |
-| **VISIBILITY_CONFLICT** | 只用 **`--visibility-file`**。 |
-| `delete_executed=true` 但 `readback_status=unavailable|still_exists` | DELETE 已发出，回读未确认；不要重复删除，稍后 `builder portal get/list` 复核。 |
-
----
-
-## 11. 交叉引用
-
-- [SKILL.md](../SKILL.md)
-- [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)
-- [QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)
-- [QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)
-- [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md)
+契约与九类组件专项 Schema：`qingflow --json builder portal schema --schema-kind complete|<类型>`。

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

@@ -218,6 +218,19 @@ current CLI payload.
 | `relation` | 关联记录（**`config.relationMode`**：`single` \| `multiple`） |
 | `data_relation` | 数据关联/引用填充 |
 | `subtable` | 子表（**`subfields[]`**） |
+| `date_duration` | 日期区间(透传型,无特殊配置) |
+| `image_select` | 图片单选(透传型,选项经模板保真) |
+| `location` | 地理位置(透传型) |
+| `ocr` | OCR 识别(透传型) |
+| `embed_field` | 内嵌字段(透传型) |
+| `ai_content_generation` | AI 内容生成(透传型) |
+| `ai_content_extraction` | AI 内容提取(透传型) |
+| `ai_content_classification` | AI 内容分类(透传型) |
+| `ai_machine_translation` | AI 机器翻译(透传型) |
+| `ai_image_recognition` | AI 图像识别(透传型) |
+| `ai_image_generation` | AI 图像生成(透传型) |
+| `ai_document_parsing` | AI 文档解析(透传型) |
+| `ai_text_summary` | AI 文本摘要(透传型) |
 
 历史表单中的后端 `queType=1` 是“描述文字”布局控件，不属于上述新建字段类型。`app-form get` 为了保持完整声明可校验，会将它兼容输出为 `long_text`；`app-form apply` 会根据已有字段模板恢复原始 `queType=1` 和 `queDefaultValue`，所以修改其他字段时不会丢失描述文字。新建可填写多行文本仍使用 `long_text`，不要用它创建描述文字控件。
 

package/skills/qingflow-cli/reference/builder/70-portal.md

@@ -11,13 +11,26 @@ Not responsible for: creating apps or views referenced by the portal. Create or
 ## Main chain
 
 ```text
-portal list/get if updating -> verify apps/views and read chart lists only when reusing existing charts -> portal apply with sections[].chart -> portal get readback -> publish state
+portal list/get if updating -> verify apps/views and read chart lists only when reusing existing charts
+  -> (offline) builder portal validate --file decl.json
+  -> builder portal apply --file decl.json [--schema-version v1alpha1]
+  -> builder portal get --dash-key K --schema-kind summary|complete (readback) -> publish state
 ```
 
+## Versioned schema and declaration files
+
+- Declarations are versioned: `schema_version` (default `v1alpha1`), `apiVersion: builder.qingflow.com/v1alpha1`. The envelope echoes `schemaVersion` when you pass `--schema-version`.
+- Two document kinds: **summary** = name + layout + component list (five stable component types: `chart/view/grid/text/link`); **complete** = summary superset with global config (`icon/color/hide_copyright/global_config/style_template_id/overall_style`), nine component types (adds `filter/carousel/task/favourite`), component `style_config`, and `visibility` authorization.
+- Read the contract itself: `qingflow --json builder portal schema --schema-kind summary|complete|<component>`; every component type (`chart|view|grid|filter|text|link|carousel|task|favourite`) has a self-contained schema — fetch it before guessing config keys.
+- `builder portal get` defaults to `--schema-kind summary` and returns a canonical `declaration` (the round-trip anchor for replay tooling). Use `--schema-kind raw` for the legacy normalized response and `--schema-kind complete` for the full declaration.
+- Offline validation: `qingflow --json builder portal validate --file decl.json` (accepts `-` for stdin; zero backend calls). Fix issues before applying.
+- Apply main form: `qingflow builder portal apply --file decl.json --schema-version v1alpha1 [--no-publish]`. Legacy patch parameters (`--sections-file`, `--visibility-file`, ...) still work in a compatibility window but emit a deprecation notice; do not use them in new automations. `--payload-file` (raw DTO passthrough) is legacy-only.
+
 ## Demo files
 
 | Scenario | Example |
 |----------|---------|
+| Recommended v1alpha1 declaration (`--file`) | [portal_apply_v1alpha1.example.json](../examples/portal/portal_apply_v1alpha1.example.json) |
 | Recommended business workbench | [portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json) |
 | Stable component capability probe | [portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json) |
 | Raw/experimental all-types probe | [portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json) |
@@ -66,8 +79,9 @@ Recommended standard workbench skeleton:
 
 ## Update existing portal
 
-- Use `--dash-key` for updates and do not send `package_id`.
-- Use `patch_sections[]` for targeted section changes when possible.
+- Prefer the declaration-file form: `builder portal apply --file decl.json --schema-version v1alpha1 --dash-key K --no-publish` (the file may omit `dash_key` and pass it via `--dash-key`; do not send `package_id` for updates).
+- Read the current declaration first with `builder portal get --dash-key K --schema-kind complete`, edit it, `builder portal validate --file`, then apply. `sections` is full-replace semantics.
+- `patch_sections[]` (via `--patch-sections-file`, compatibility window) remains for targeted section changes when a full declaration round-trip is not practical.
 - `patch_sections[]` selectors may use `order`, `chart_ref.chart_id`, `chart_ref.chart_key`, or `view_ref.view_key`; chart sections read back from portal often only include `chart_id`, so patching by `chart_id` is valid and does not require `app_key`.
 - If using a business-entry grid, include real `items`; do not submit an empty entry container.
 - Validate referenced `chart_key`, `chart_id`, `view_key`, or `app_key` before claiming the portal is complete.
@@ -110,7 +124,9 @@ qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
 | 参数 | 说明 |
 |------|------|
 | **`--publish` / `--no-publish`** | 默认 **`--publish`**。仅 **`--no-publish`** 时不会调用发布接口；契约说明 **`publish=false` 不宣称线上已变**。 |
-| **`--payload-file`** | 完整门户 JSON 对象；**标准字段写 `dash_name`**。新版 CLI 兼容 **`name -> dash_name`**、单页 **`pages[0].components -> sections`**，但 agent 默认不要依赖兼容别名。 |
+| **`--file`**（主形态） | 完整门户声明 JSON 对象（支持 **`-`** stdin）；与 patch 参数互斥；声明内可带 **`schema_version`**。 |
+| **`--schema-version`** | 固定声明契约版本（缺省读文件内 `schema_version`，再缺省 latest）。传入时声明先过 complete schema 离线校验，**`INVALID_SPEC` 不写**。 |
+| **`--payload-file`**（旧） | 完整门户 JSON 对象透传（兼容窗口）；新代码改用 **`--file`**。标准字段写 `dash_name`。 |
 | **`--sections-file`** | JSON **数组**；**全量替换**。省略时仅改基础信息，且 **`hide_copyright` / `dash_global_config` / `config`** 不能单独提交（**`PORTAL_SECTIONS_REQUIRED`**）。 |
 | **`--layout-preset`** | 可选：**`auto` / `dashboard_2col` / `dashboard_3col`**。当区块未显式写 **`position`** 时由工具生成大屏布局。 |
 | **`--visibility-file`** | 与 **`--auth-file`** 不能同时用。 |
@@ -125,7 +141,7 @@ qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
 
 ### 3.1 公共键
 
-- **`title`**（必填）、**`source_type`**（必填，小写）、可选 **`position`**（**`pc`/`mobile`** 各 **`x,y,cols,rows`**；省略则由**实现自动排布**）。
+- **`source_type`**（必填，小写）、**`title`**（可选——schema 仅强制 `source_type`；新建组件建议提供标题，存量 filter 组件合法无标题，round-trip 透传不要合成）、可选 **`position`**（嵌套 **`pc`/`mobile`** 各 **`x,y,cols,rows`**；平铺别名 **`pc_x/pc_y/pc_w/pc_h`、`mobile_*`** 也接受，`x/y` 与 `w/h/cols/rows` 混写均认；省略则由**实现自动排布**）。
 - **`config`**、**`dash_style_config`**：按类型 Optional。默认只写 snake_case 规范键。
 
 ### 3.1.0 Payload 字段口径
@@ -198,8 +214,8 @@ mobile 固定按 **6 栅格** 从上到下堆叠：通常所有组件 `x=0, cols
 
 **当前工具边界**：
 
-- 公开 `sections-file` 稳定支持：**`grid` / `chart` / `view` / `text` / `link`**；`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理，不作为主路径。
-- **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状，不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`；只有工具后续显式支持 `task`，或维护者走 raw 门户写入链路时，才使用待办槽位。
+- 声明式（`--file` / complete 档）支持**九类组件**：**`grid` / `chart` / `view` / `text` / `link`**（summary 档稳定面）+ **`carousel` / `task` / `favourite`**（complete 档，配置键见专项 Schema）+ **`filter`**（complete 档受控承载，仍按 **§3.4** raw 边界处理，不作为主路径）。
+- **`task`（一个门户最多 1 个）与 `favourite`（一个门户最多 1 个）** 已进入 v1alpha1 complete 声明面（`task`/`favourite` 类型化 config 键），不要再按后端 raw 形状（`taskConfig`/`favouriteConfig`）手拼；声明形态见 `qingflow --json builder portal schema --schema-kind task|favourite`。旧文档中的「task/favorite 不在公开合约里」已过时。
 - 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)**。这是唯一推荐复制的业务工作台布局模板：每一行 `cols_sum=24`，同行 `rows` 一致，下一行 `y` 连续。顶部先用一个业务入口 `grid` 占满 24 栅格；如果工具已支持待办组件，再把顶部拆成 `grid cols=12 + task cols=12`。
 - **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)** 和 **[portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json)** 仅用于组件能力探针，不作为业务门户布局模板；搭建正式门户时不要从这些探针推导布局。
 - `grid` 必须写 **`config.items[]`**；只写 `gridTitle` / `beingShowTitle` 会生成空入口容器，工具会返回 **`PORTAL_GRID_ITEMS_EMPTY`**。
@@ -230,16 +246,21 @@ mobile 固定按 **6 栅格** 从上到下堆叠：通常所有组件 `x=0, cols
 
 ### 3.2 `source_type` ↔ 回读 `components[].type`（搭建侧）
 
-| `source_type` | 回读 `type`（数字） | 搭建侧含义 |
-|---------------|---------------------|------------|
-| **`chart`** | **9** | QingBI 图表块 |
-| **`view`** | **10** | 应用视图块 |
-| **`grid`** | **2** | 九宫格 |
-| **`filter`** | **6** | 筛选条 |
-| **`text`** | **5** | 富文本说明 |
-| **`link`** | **4** | 外链 |
+| `source_type` | 回读 `type`（数字） | 搭建侧含义 | 声明档 |
+|---------------|---------------------|------------|----------|
+| **`chart`** | **9** | QingBI 图表块 | summary |
+| **`view`** | **10** | 应用视图块 | summary |
+| **`grid`** | **2** | 九宫格 | summary |
+| **`text`** | **5** | 富文本说明 | summary |
+| **`link`** | **4** | 外链 | summary |
+| **`filter`** | **6** | 筛选条 | complete（raw/unstable） |
+| **`carousel`** | **3** | 轮播（数据源应用 + 标题/图片/链接字段） | complete |
+| **`task`** | **8** | 待办（一个门户最多 1 个） | complete |
+| **`favourite`** | **7** | 收藏（一个门户最多 1 个） | complete |
+
+每类组件的详细配置键经专项 Schema 获取：`qingflow --json builder portal schema --schema-kind <类型>`（如 `--schema-kind carousel`、`--schema-kind task`）。`carousel` 的 `title_field/image_field/link_field` 填字段显示名（CLI 编译为 queId）；`task.tasks[].task_type` 取值 1=我的待办 2=已超时 3=即将超时 4=催办 5=我发起的 6=抄送我的 7=草稿箱 8=我的已办 9=待完善；`favourite.items[]` 用 `item_type`(1=应用 2=门户)+`link_key` 锚定目标。
 
-CLI 校验（`PortalSectionPatch`）：**chart** 须 **`chart`** 或兼容旧字段 **`chart_ref`**；**view** 须 **`view_ref`**；**text** 须 **`text`**；**link** 须 **`url`**。**grid** / **filter** 无额外 ref，**`config` 形状由后端接受为准**。
+CLI 校验（`PortalSectionPatch`）：**chart** 须 **`chart`** 或 **`chart_ref`**；**view** 须 **`view_ref`**；**text** 须 **`text`**；**link** 须 **`url`**；**carousel/task/favourite** 须各自类型化 config 键。**grid** / **filter** 无额外 ref，**`config` 形状由专项 Schema 与后端接受为准**。
 
 ### 3.3 **`chart`**：一个字段同时支持引用已有图表和内联创建图表
 
@@ -327,7 +348,7 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
 
 ## 8. **发布**（`--publish`）
 
-- **默认会发布**：未显式 **`--no-publish`** 即 **`publish: true`**；公开入口仍是 **`portal_apply`**，发布动作由工具内部执行并回读 **`being_draft=false`**。
+- **默认会发布**：未显式 **`--no-publish`** 即 **`publish: true`**；公开入口仍是 **`portal_apply`**，发布动作由工具内部执行并回读 **`being_draft=false`**。**注意**：对**已发布门户**用 **`--no-publish`** 更新会把发布状态**降回草稿**（草稿写了、线上态被覆盖标记）——需要保留线上态的试写/迭代不要带 **`--no-publish`** 对已发布门户提交，或写完后显式补发布。
 - **已发布线索**：成功路径上 **`published: true`**；**`live_result.publishStatus`** 常见 **`2`** 表示已发布（以你环境枚举为准）。
 - **`partial_success` + `PORTAL_READBACK_PENDING`**：草稿/线上 **组件数量或元数据** 与「本次期望」不一致时会出现；**`PORTAL_*_VERIFICATION_INCOMPLETE`** 警告。应 **`builder portal get --dash-key …`**（草稿与 **`--no-being-draft` 线上**）**肉眼核对**区块是否齐全，而不是仅信 **`verified: true`**。
 - **网关 503**：**与 CLI 无关**；环境恢复后重试 **`portal get` / `portal apply`**。（本轮在网关恢复后 **`portal apply` 已成功**。）

package/skills/qingflow-cli/reference/examples/portal/portal_apply_v1alpha1.example.json

@@ -0,0 +1,100 @@
+{
+  "schema_version": "v1alpha1",
+  "name": "业务工作台",
+  "package_tag_id": 2030703,
+  "icon": "view-grid",
+  "color": "#2468F2",
+  "hide_copyright": false,
+  "global_config": {
+    "auto_refresh": false,
+    "interval": 60,
+    "export": true
+  },
+  "visibility": {
+    "mode": "workspace",
+    "external_mode": "not"
+  },
+  "layout_preset": "auto",
+  "sections": [
+    {
+      "title": "业务入口",
+      "source_type": "grid",
+      "position": {
+        "pc": { "x": 0, "y": 0, "cols": 24, "rows": 4 }
+      },
+      "config": {
+        "gridTitle": "业务入口",
+        "beingShowTitle": true,
+        "items": [
+          { "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY_DEVICE", "linkFormType": 1, "title": "设备台账" },
+          { "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY_WORKORDER", "linkFormType": 1, "title": "工单管理" }
+        ]
+      }
+    },
+    {
+      "title": "设备总数",
+      "source_type": "chart",
+      "role": "metric",
+      "position": {
+        "pc": { "x": 0, "y": 4, "cols": 6, "rows": 5 }
+      },
+      "chart": {
+        "app_key": "APP_KEY_DEVICE",
+        "name": "设备总数",
+        "chart_type": "target",
+        "metric": "count(*)"
+      }
+    },
+    {
+      "title": "异常设备数",
+      "source_type": "chart",
+      "role": "metric",
+      "position": {
+        "pc": { "x": 6, "y": 4, "cols": 6, "rows": 5 }
+      },
+      "chart": {
+        "app_key": "APP_KEY_DEVICE",
+        "name": "异常设备数",
+        "chart_type": "target",
+        "metric": "count(*)",
+        "filters": [
+          { "field_name": "状态", "operator": "eq", "values": ["异常"] }
+        ]
+      }
+    },
+    {
+      "title": "工单趋势",
+      "source_type": "chart",
+      "position": {
+        "pc": { "x": 0, "y": 9, "cols": 12, "rows": 7 }
+      },
+      "chart": {
+        "app_key": "APP_KEY_WORKORDER",
+        "name": "工单趋势",
+        "chart_type": "line",
+        "metric": "count(*)",
+        "group_by": ["创建日期"]
+      }
+    },
+    {
+      "title": "工单类型分布",
+      "source_type": "chart",
+      "position": {
+        "pc": { "x": 12, "y": 9, "cols": 12, "rows": 7 }
+      },
+      "chart_ref": { "app_key": "APP_KEY_WORKORDER", "chart_name": "工单类型分布" }
+    },
+    {
+      "title": "异常设备明细",
+      "source_type": "view",
+      "position": {
+        "pc": { "x": 0, "y": 16, "cols": 24, "rows": 11 }
+      },
+      "view_ref": {
+        "app_key": "APP_KEY_DEVICE",
+        "view_key": "VIEW_KEY_ABNORMAL_DEVICES"
+      },
+      "view_display": { "show_title": true }
+    }
+  ]
+}

package/skills/qingflow-cli/reference/examples/portal/portal_sections_all_types.example.json

@@ -17,14 +17,13 @@
       }
     },
     "config": {
-      "filterConfig": [],
-      "graphList": [
+      "graphs": [
         {
-          "graphType": "CHART",
-          "graphKey": "REPLACE_WITH_QINGBI_CHART_ID",
-          "graphName": "可选_图表显示名"
+          "chart_key": "REPLACE_WITH_QINGBI_CHART_ID",
+          "chart_name": "可选_图表显示名"
         }
-      ]
+      ],
+      "rules": []
     }
   },
   {
@@ -142,4 +141,4 @@
       "chart_id": "YOUR_CHART_ID"
     }
   }
-]
+]