@qingflow-tech/qingflow-cli 1.1.61-beta.3 → 1.1.61-beta.5

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.61-beta.3
+npm install @qingflow-tech/qingflow-cli@1.1.61-beta.5
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.3 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.5 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.3 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.5 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.3",
+  "version": "1.1.61-beta.5",
   "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.61b3"
+version = "1.1.61b5"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/SKILL.md

@@ -14,6 +14,8 @@ description: |
 
 本 Skill 负责 CLI 入口、文件约定和业务分流。已知 `app_key` 时直接执行 `data query/get`。只有应用名称时，先用 `qingflow --json app list --query "应用名称"` 查找当前工作区的可见应用，并核对返回项的 `app_name/title`；目标明确且唯一时取其 `app_key` 再查询，否则请用户确认。不要把应用名称直接传给 `--app-key`，也不要为定位名称转向 builder 或切换工作区。字段能力、权限范围与下一步动作以当前工具 schema、data 响应和 `hints` 为准。
 
+首次解析 `data query/get` 响应前，阅读 [data 响应结构与解析](./reference/data/README.md#响应结构与解析)，按同次响应中的 schema 与记录结构读取目标字段。
+
 ## 关联文件
 
 

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`** 不能同时用。 |
@@ -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** | 外链 |
-
-CLI 校验（`PortalSectionPatch`）：**chart** 须 **`chart`** 或兼容旧字段 **`chart_ref`**；**view** 须 **`view_ref`**；**text** 须 **`text`**；**link** 须 **`url`**。**grid** / **filter** 无额外 ref，**`config` 形状由后端接受为准**。
+| `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`**；**carousel/task/favourite** 须各自类型化 config 键。**grid** / **filter** 无额外 ref，**`config` 形状由专项 Schema 与后端接受为准**。
 
 ### 3.3 **`chart`**：一个字段同时支持引用已有图表和内联创建图表
 

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

@@ -10,6 +10,44 @@
 
 参数、JSON 文件形状和可选项必须来自当前工具 schema、当次 `--help` 或响应字段能力，不得从其他命令推测。
 
+## 响应结构与解析
+
+`data query` 的记录位于 `records.items[]`，`data get` 的单条记录位于 `record`。两者的业务值都在各记录的 `fields` 对象中，以十进制 `field_id` 字符串为键；不要从记录顶层按字段 id 取值。
+
+`schema.fields[]` 是字段元数据，包含两种结构：系统字段使用 `key` 与 `kind=system`，对应记录顶层的 `record_id/creator/updated_at`；业务字段使用 `field_id/title/data_type/cardinality`，对应记录的 `fields`。按是否包含 `field_id` 识别业务字段（`field_id=0` 也有效），类型读取 `data_type`。子表的列定义在 `children` 中，各行同样以字段 id 字符串为键。
+
+以下是只保留解析所需字段的 query 响应示例：
+
+```json
+{
+  "schema": {"fields": [
+    {"key": "record_id", "kind": "system"},
+    {"field_id": 0, "title": "编号", "data_type": "number", "cardinality": "one"},
+    {"field_id": 101, "title": "名称", "data_type": "text", "cardinality": "one"}
+  ]},
+  "records": {"items": [
+    {"record_id": "1", "fields": {"0": 0, "101": "示例"}}
+  ]}
+}
+```
+
+JSON 落盘后，先确认记录结构，再按用户目标选择字段；例如只查看首条记录的「名称」：
+
+```python
+field = next(f for f in payload["schema"]["fields"]
+             if "field_id" in f and f["title"] == "名称")
+key = str(field["field_id"])
+for record in payload["records"]["items"][:1]:
+    values = record["fields"]
+    assert isinstance(values, dict), "记录 fields 结构不符合预期"
+    if key in values:
+        print({"record_id": record["record_id"], "title": field["title"], "value": values[key]})
+    else:
+        print({"record_id": record["record_id"], "title": field["title"], "returned": False})
+```
+
+键未返回与值为 `null` 是不同情况；`0` 和 `false` 是有效值，不要用真假判断把它们归为空。结构不符合预期或字段键缺失时，检查同次响应的 schema、`access`、`hints` 与首条记录的结构，必要时对同一记录执行 `data get` 复核；不能把解析失败或未返回字段直接报告为业务数据为空。
+
 ## 字段能力合同
 
 1. 首次操作当前应用时，只通过只读 `data query/get` 请求 `include_schema=true`，读取同一次响应中的 `schema` 与递归 `field_capabilities`；不得用 insert/update 探测能力。

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"
     }
   }
-]
+]

package/src/qingflow_mcp/app_form_validator.py

@@ -28,10 +28,16 @@ _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
     "single_select",
     "multi_select",
     "attachment",
+    # r10 存量实证放行:link(92nl6blfk402)/member(ab9fjvj33001)——后端写链
+    # 无类型白名单,运行时同为字符串写入路径
+    "link",
+    "member",
     "data_relation",
     "subtable",
 }
-_Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}\s]+)\}\}")
+# key 允许含空白(r10 实测存量 key 如「应用包 ID」带空格,\s 排除导致占位符
+# 扫描漏检 → validate 误报「key must appear as {{key}}」)
+_Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}]+)\}\}")
 _FORMULA_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
 #: 公式字段引用正则（#queId_<id>$，支持表格嵌套 <id>.<id>）
 _FORMULA_FIELD_REF_RE = re.compile(r"#queId_([^$]+)\$")
@@ -353,7 +359,15 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
                                         "is_empty and is_not_empty require a literal operand with values: []",
                                     )
                                 )
-                        elif operand.get("kind") == "literal" and not values:
+                        elif (
+                            operand.get("kind") == "literal"
+                            and not values
+                            and operator not in {"subordinate_to", "not_subordinate_to"}
+                        ):
+                            # subordinate 两算子放行空 literal:存量「设置后清空」形态
+                            # (r13 实证 41ce0ad8 六处)——后端写链 checkRelationMatchRules
+                            # 仅校验 dynamic_range(FormSvcImpl:10448),formula 渲染对空
+                            # judgeValueDetails 输出 [](Formula:397),读回解析对称,往返保真
                             errors.append(
                                 (
                                     f"{operand_path}/values",
@@ -386,7 +400,10 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             selected_name = selected[1].get("name") if selected is not None else selector.get("name")
             if not selected_name and selector.get("queId") in fields_by_id:
                 selected_name = fields_by_id[selector["queId"]].get("name")
-            if selected_name and item.get("key") != selected_name:
+            # 两侧 strip:模板引用名提取时已 strip(字段名存量带尾随空格,如
+            # am4oh08v2401「答:Answer 」),严格相等会把「引用名≠当前字段名」的
+            # 存量形态误报为 key 不一致
+            if selected_name and str(item.get("key") or "").strip() != str(selected_name).strip():
                 errors.append((f"{input_path}/key", "json_path key must equal the selected field name"))
 
         if field_type == "q_linker":