@qingflow-tech/qingflow-cli 1.1.55 → 1.1.57

package/README.md

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

package/skills/qingflow-cli/SKILL.md

@@ -31,7 +31,7 @@ description: |
 | [reference/builder/20-build-complete-system.md](./reference/builder/20-build-complete-system.md) | **完整系统/应用包主入口**：多应用、跨应用 relation、门户闭环 |
 | [reference/builder/30-schema-fields.md](./reference/builder/30-schema-fields.md) | **字段 / schema**：字段类型、直觉别名、数据标题/封面、schema 创建与更新 |
 | [reference/builder/40-layout.md](./reference/builder/40-layout.md) | **布局维护**：仅用于已有应用的分组、`rows` 矩阵、布局修复；新建应用布局写在 `form` 内 |
-| [reference/builder/50-views.md](./reference/builder/50-views.md) | **视图**：表格/卡片/看板/甘特、固定筛选、查询面板、视图 patch |
+| [reference/builder/50-views.md](./reference/builder/50-views.md) | **视图**：先读 schema，一次写一个视图对象；查询面板和按钮约束见该文 |
 | [reference/builder/60-charts.md](./reference/builder/60-charts.md) | **报表 / QingBI**：指标卡、图表、语义聚合、筛选、排序、更新 |
 | [reference/builder/70-portal.md](./reference/builder/70-portal.md) | **门户**：标准工作台、业务入口、指标、图表、视图组件、发布 |
 | [reference/builder/80-buttons-associated-resources.md](./reference/builder/80-buttons-associated-resources.md) | **关联资源 / 非主链路按钮维护**：关联视图/报表、`match_mappings`、上下文传参；按钮配置看视图文档 `action_buttons`；创建自定义按钮前先 `button get --button-text` 查重复用 |

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

@@ -9,7 +9,7 @@
 
 统一语义：
 
-- 固定筛选用 `field_name + operator + value/values`，例如视图 `filters`、报表 `filters`。
+- 报表固定筛选用 `field_name + operator + value/values`。普通视图的 `filters`、`visible_when`、`query_conditions` 不在本文，字段写 `que_id`，见 [50-views.md](./builder/50-views.md)。
 - 当前记录上下文匹配用 `target_field + operator + source_field/value`，例如关联资源 `match_mappings`、新增数据按钮传参。
 - 不要直接写 `judgeType`、`judgeValues`、`matchRules`；CLI 会按目标协议自动编译。
 - 单选 / 多选 / 布尔这类选项值，入参可写选项文本或 option id；视图 / 按钮 / 工作流路径会编译成 Qingflow 需要的 id + details，QingBI 报表路径会编译成 BI 前端需要的文本 `judgeValue`。

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

@@ -1,52 +1,7 @@
-# Builder Views Workflow (Legacy Redirect)
+# Builder Views Workflow
 
-This file is kept only for old cross-links. Use the current canonical document instead:
-
-- [builder/50-views.md](./builder/50-views.md)
-
-Current main path:
+旧文已并入 [builder/50-views.md](./builder/50-views.md)。字段形状读 `builder views schema --schema-kind complete`。一次只提交一个视图对象：
 
 ```bash
-qingflow builder views apply --app-key APP_KEY --view-file /abs/path/view.json
+qingflow builder views apply --app-key APP_KEY --schema-version v1alpha1 --view-file /abs/path/view.json
 ```
-
-Use `--app-key APP_KEY --view-file /abs/path/view.json`. The file contains one direct view object.
-
-Minimum current shape:
-
-```json
-{
-      "name": "订单跟进视图",
-      "type": "table",
-      "columns": ["订单编号", "客户名称", "状态", "负责人"],
-      "filters": [
-        {"field_name": "状态", "operator": "neq", "value": "已关闭"}
-      ],
-      "query_conditions": {
-        "enabled": true,
-        "rows": [["订单编号", "客户名称"], ["状态", "负责人"]]
-      },
-      "action_buttons": [
-        {
-          "text": "行内新建跟进",
-          "action": "add_data",
-          "target_app_key": "TARGET_APP_KEY",
-          "placement": "list",
-          "field_mappings": [
-            {"source_field": "数据ID", "target_field": "关联订单"}
-          ]
-        },
-        {
-          "text": "详情新建跟进",
-          "action": "add_data",
-          "target_app_key": "TARGET_APP_KEY",
-          "placement": "detail",
-          "field_mappings": [
-            {"source_field": "数据ID", "target_field": "关联订单"}
-          ]
-        }
-      ]
-}
-```
-
-Each `builder views apply` call handles one operation on one view: pass one `--view-file`, one-item `patch_views`, or one-item `remove_views`; do not combine these operation modes.

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

@@ -55,7 +55,7 @@
 | --- | --- |
 | `builder app get` | 应用地图；轻量返回字段摘要、视图、图表、自定义按钮、关联资源池 |
 | `builder app-form schema/get/validate/apply` | 当前表单/字段/布局/应用设置入口；固定 AppForm schema 版本，完整声明写入并保留现有 IDs；旧 `builder schema apply` / `builder layout apply` 仅为已移除的内部兼容适配器 |
-| `builder views apply` | 业务视图；固定筛选写 `filters`，前端查询栏写 `query_conditions` |
+| `builder views apply` | 业务视图。字段形状读 `views schema`；一次一个视图对象。数据权限默认 `custom + all`，自定义范围才写 `filters`；查询栏写 `query_conditions` 的 queId |
 | `builder button apply` | 自定义按钮默认路径；新增数据按钮用 `field_mappings/default_values`，绑定位置用 `header/detail/list` |
 | `builder associated-resource apply` | 应用级关联视图/报表池 + 视图展示配置；报表来源用 `report_source`，不让智能体填写后端 raw source |
 | `builder charts apply` | QingBI 报表配置；报表变更 immediate-live，不等同于应用发布 |

package/skills/qingflow-cli/reference/builder/50-views.md

@@ -1,541 +1,56 @@
 # Builder Views
 
-Read this when the task is about table/card/board/gantt/hierarchy/calendar views, fixed filters, query panels, view sorting, view data permissions, associated report/view display on a view, or repairing existing views.
+视图字段形状以 `builder views schema` 为准。本文只保留调用顺序和 schema 没有替你做的交付约束。不要再找 `view_create`、`--views-file` 或批量 `views[]`。
 
-## Scope
-
-Responsible for: `builder views apply --app-key APP_KEY --view-file PATH` (the **only** creation entry), one view declaration, `columns`, `filters`, `query_conditions`, `action_buttons`, and view readback.
-
-Not responsible for: creating associated report resources or maintaining custom button bodies outside the view design. New business views must include `query_conditions`; ordinary business shortcut buttons are required and are declared only through `action_buttons` on the target view.
-
-## Main chain
+## 调用顺序
 
 ```text
-app get -> app get fields/views -> views schema -> prepare one view -> views validate -> views apply -> app get/views readback
+app get fields/views -> views schema --schema-kind complete -> 写一个视图对象 -> views validate -> views apply -> 按 verification 回读
 ```
 
-## 版本与 schema（views v1alpha1）
-
-视图声明是**版本化契约**（`apiVersion: builder.qingflow.com/v1alpha1`）。`builder views apply` 是视图创建的**唯一入口**（旧命令式 `view_create` 已删除；不要再寻找或使用任何“直接创建视图”的命令/工具）。
-
-- **两级 schema**：**summary**（最简版：类型/名称/数据展示内容 + `data_permission` 数据权限形状）与 **complete**（完整版：visibility 可见性授权、`filters`、`sort`、`query_conditions`、`action_buttons`/`buttons`、`associated_resources`、`card`/`gantt`/`hierarchy`/`calendar` 类型专属配置、`display`/`record`/`share`）。字段级定义逐字段带 `x-backend` 后端映射。
-- **读 schema**：`qingflow --json builder views schema` 默认返回 `v1alpha1/summary.json`；需要完整可写配置时显式传 `--schema-kind complete`。MCP 对应 `app_views_schema`。
-- **Schema-first 写入**：先用 `builder views schema --schema-version VERSION --schema-kind complete` 读取完整 schema；将相同版本显式传给 `validate --schema-version VERSION` 和 `apply --schema-version VERSION`。`validate` 也可从声明信封读取 `schema_version`，但推荐显式传版本；apply 的版本校验必须用 `--schema-version`。`validate` 接受一个直接视图声明对象，不接受 `upsert_view` 包装或批量 envelope。
-- **说明字段**：视图 Schema 使用语义化的 `*Description` 自定义 key（如 `dataPermissionDescription`）承载说明，加载和引用展开时原样保留；读取说明的工具应识别这些 key。标准校验器忽略这些自定义字段，仍按 `type`、`enum`、`required` 等关键字校验；`default` 是标准注解，不会自动填值。`*Description` 不是提交视图声明时的业务字段。
-- **离线校验**：`qingflow --json builder views validate --file PATH`（`-` 支持 stdin），不访问后端；返回 `ok`/`issues[]`（带 JSON pointer path）。
-- **读 canonical 声明**：`qingflow --json builder views get --app-key APP --schema-version VERSION --schema-kind summary`，返回指定版本的 summary 声明数组（字段名反解）；完整可写配置用 `--schema-kind complete` 并检查 `config_read_errors[].gaps`。
-- **完整声明的提取边界**：`views get --schema-kind complete` 优先读取 `buttonConfigVO` 中的完整按钮绑定。公式过滤、无法解析的过滤规则或按钮 ID 会使该视图返回 `VIEW_NOT_EXTRACTABLE`（见 `details.config_read_errors[].gaps`），不会生成删减后的可写声明。修改这类视图的其他属性应使用局部 patch。更新现有视图时，已配置的系统字段原样保留，不补默认值、不重算序号；读接口生成的未配置占位对象不会写回，不会因此新增系统字段配置。
-- **版本协商**：apply 显式传 `--schema-version v1alpha1` 时启用版本化校验：非法声明返回 `INVALID_SPEC` 且**不写**；响应信封回显 `schemaVersion`。apply 不传时行为与旧版一致（别名宽容，零破坏）。
-- **公开视图类型**：summary 与 complete 均支持 `table`、`card`、`board`、`gantt`、`hierarchy`、`calendar`。层级视图须提供 `hierarchy: {title_que_id, children_que_id}`；日历视图须提供 `calendar: {title_que_id, date_que_id}`，可选 `color_que_id`。日历 `date_que_id` 可引用表单日期字段，也可用系统字段 `2`（申请时间）或 `3`（更新时间）。
-- **complete 档配置速览**：`data_permission` 默认 `{type: custom, scope: all}`。`type=config` 跟随应用成员授权，忽略 `scope` 与 `filters`；`type=custom` 才使用 `scope`，其中 `scope=custom` 的规则写 `filters`。`sort`（`[{que_id, ascending}]`，空数组=恢复默认排序）；`hierarchy`（可选 `root_filter`）；`card`/`gantt`/`calendar`/`display`/`record`/`share` 配置组。
-
-## Update existing views
-
-- Prefer `--patch-views-file` for small changes to an existing view.
-- Use raw `view_key` from `app_get.views[].view_key`; do not use record-data `custom:<view_key>` prefixes.
-- Do not send a partial `--view-file` object to update a complex existing view; use `--patch-views-file` with `set`.
-- Verify filters, query conditions, and associated resources separately before reporting success.
-
-## Detailed contract notes
-
-稳定命令：**`qingflow builder views apply --app-key APP_KEY --view-file PATH`**（别名 **`qingflow build views apply`**）。`--view-file` 是一个直接的 JSON 对象，只声明一个新建或完整更新的视图。
-
-> **权限**：视图**新建**走后端 `createViewgraphConfig`，需要同时满足 **视图管理 / ViewManagementAuth**（`beingViewManageStatus`）和 **数据管理 / DataManageAuth**；视图**更新/删除**只走 **ViewManagementAuth**。未开启高级应用权限时 `beingViewManageStatus` 等价回落到 **DataManageAuth**。失败时常见 **40002 / 40161 / 编辑锁**，参见主技能与 **ADMIN** 速查。
-
-> **默认系统视图**：`全部数据`、`我的数据`、`我发起的`、`待办`、`已办`、`抄送` 等由轻流自带，**不要新建同名业务视图**。新建视图必须用业务名，例如 `项目台账视图`、`客户跟进视图`、`逾期任务看板`。如果确实要调整默认系统视图，只能从 `app get views` 取已存在的 raw **`view_key`** 后通过 `--patch-views-file` 更新。
-
-> **契约**（权威键名、枚举、`execution_notes`、示例）：
-> `qingflow --json builder contract --tool-name app_views_apply`
-> （`--tool-name` 为契约索引，用于拉取 **`allowed_keys` / 别名 / 示例**。）
-> 契约示例若带 `"profile"` 或 `"app_key"`，不要复制到 `--view-file`；CLI 分别用根级 `qingflow --profile …` 和 `--app-key` 指定。
-
----
-
-## 1. 推荐操作顺序（读 → 写 → 校验）
-
-| 步骤 | 动作 | CLI |
-|------|------|-----|
-| ① 读应用地图 | 先看 compact views/charts/buttons/associated resources | `qingflow --json builder app get --app-key <APP_KEY>` |
-| ② 读字段/视图 | 确认 **`columns`** / `query_conditions.rows` 可用字段、核对 **`view_key`** | `qingflow --json builder app get --app-key <APP_KEY> fields` / `qingflow --json builder app get --app-key <APP_KEY> views` |
-| ③ 读取 schema | 固定版本；按需求读取 summary 或 complete | `qingflow --json builder views schema --schema-version v1alpha1 --schema-kind complete` |
-| ④ 准备并校验声明 | 新建或完整更新写一个视图对象；先离线校验；局部修改写单项 patch | `qingflow --json builder views validate --file PATH --schema-version v1alpha1` |
-| ⑤ 应用视图操作 | 将同一版本传给 apply；一次只提交一个视图操作 | `qingflow builder views apply --app-key … --view-file PATH --schema-version v1alpha1` |
-| ⑥ 配置查询面板和快捷按钮 | 新建业务视图必须写 `query_conditions` 和 `action_buttons`，按钮同时覆盖 `list` 和 `detail` 位置 | `builder views apply` |
-| ⑦ 需要上线时 | 发布侧校验 | `qingflow builder publish verify --app-key …` |
-
-**说明**：`views apply` 的 **`--publish`** 对应契约里的 **`publish`**；新建业务视图必须包含 `query_conditions` 和 `action_buttons` 并使用 `publish=true`，因为底层按钮写入会自动发布。只有删除、纯维护补丁、或用户明确要求的只读/归档视图，才允许不带按钮；只读/归档视图仍应配置 `query_conditions`。
-
----
-
-## 2. CLI 形态
-
 ```bash
-qingflow builder views apply \
-  --app-key APP_KEY \
-  --view-file PATH \
-  [--publish | --no-publish]
-```
-
-- **`--view-file`**：单个 JSON 对象，用于新建或完整更新一个视图；命令每次只接受一个。
-- **`--patch-views-file`**：JSON 数组，用于已有视图的局部更新；每次最多传一项，包含 `view_key` 或唯一 `name`，以及 `set`/`unset`。
-- **`--remove-views-file`**：JSON 数组，用于删除一个视图；每次最多传一个 raw `view_key` 或唯一名称。
-- 每次调用只能选择一种写入模式：`--view-file`、`--patch-views-file`、`--remove-views-file` 三者不能混用；每次只处理一个应用中的一个视图操作。
-- **不支持批量创建**：不要传 `upsert_views`、`views`、`apps` 等批量声明，也不要在 patch/remove 文件中放多项；多个视图须逐个调用 `builder views apply`，每次单独读回确认。
-- **`--app-key`**：每次视图写入必须指定一个应用；CLI 不提供跨应用或同次多视图写入。
-- 输出默认直接给 stdout，前端可直接读取；需要留档时用 `qingflow builder views apply … | tee tmp/builder_views_apply.json`。
-
----
-
-## 2.1 参考示例文件（与门户 / 报表同风格）
-
-| 文件 | 用途 |
-|------|------|
-| [views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json) | 单视图表格示例，可直接作为 `--view-file` |
-| [views_apply_v1alpha1.example.json](../examples/views/views_apply_v1alpha1.example.json) | 版本化单视图字段示例；作为 `--view-file` 使用时加 `--schema-version v1alpha1` |
-
-复制到具体应用前替换 **`columns`**；应用由命令的 **`--app-key`** 指定。**`name`** 重名时会更新已有同名视图而非新建（见 **§4**）。
-
----
-
-## 3. 请求体形状（与契约对齐）
-
-CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
-
-| 键 | 说明 |
-|----|------|
-| **`app_key`** | 命令的必填参数，定位单个应用 |
-| **`upsert_view`** | 来自 `--view-file` 的一个对象；创建用 `name`，完整更新优先带 raw `view_key` |
-| **`upsert_view.query_conditions`** | 新建业务视图必填；配置前端查询面板字段布局 |
-| **`patch_views`** | 来自 `--patch-views-file` 的数组；每次最多一项，使用 `view_key`/`name` 和 `set`/`unset` |
-| **`remove_views`** | 来自 `--remove-views-file` 的数组；每次最多一项，使用 raw `view_key` 或唯一名称 |
-
-**别名**（契约 `aliases` 节选）：**`fields` / `column_names` → `columns`**；**`view_key` / `viewKey`**；**`tableView`→`table`**、**`kanban`→`board`** 等；**`filter_rules`→`filters`**；**`startField`→`start_field`** 等。
-
----
-
-## 4. 创建 vs 更新（`view_key` 与 `name`）
-
-服务逻辑概要：
-
-- **`remove_views`**：优先传 raw **`view_key`**；也可传唯一视图显示名 `name`，显示名重名则 **`AMBIGUOUS_VIEW`**。
-- **`upsert_view`**：
-  - 若提供 **`view_key`**：对该视图做 **更新**（含类型变更等，仍受后端约束）。
-  - 未提供 **`view_key`**：若 **`name` 唯一** 匹配已有视图 → **更新**；否则 → **创建**。
-- **`patch_views`**：对已有视图做局部参数替换；必须有 `view_key` 或唯一 `name`，并写 `set` / `unset`。
-
-响应中的 **`verification.view.status`** 会出现 **`created` / `updated`** 等；**`view_result`** 给出本次唯一视图操作结果，**`views_diff`** 仅保留兼容摘要。
-
-**`partial_success`**：单个视图写入已执行，但读回或附属配置校验未完全通过；务必读 **`view_result`**、**`warnings`** 与 **`verification`**。
-
-**系统默认名禁止新建**：未提供 `view_key` 的 `upsert` 不要使用 `全部数据`、`我的数据`、`我发起的`、`待办`、`已办`、`抄送` 这类默认系统视图名。它们不是业务视图模板，而是平台默认对象；新业务视图用具体业务名。
-
----
-
-## 5. `type` 与各类型必填
-
-契约 **`view.type`**：**`table`** | **`card`** | **`board`** | **`gantt`** | **`hierarchy`** | **`calendar`**。
-
-| `type` | 列/字段要点 | 类型专属键 |
-|--------|----------------|------------|
-| **`table`** | **`columns`**（业务字段 **queId**，或已有系统字段 **queId**） | — |
-| **`card`** | 同 table | — |
-| **`board`**（看板） | 列；且须 **`group_by`**（分组字段名） | **`group_by`** |
-| **`gantt`** | 列；须 **`start_field`**、**`end_field`**（通常为日期类字段名） | 可选 **`title_field`** |
-| **`hierarchy`** | 层级标题字段和父子关系字段 | `hierarchy.title_que_id`、`hierarchy.children_que_id`；可选 `hierarchy.root_filter` |
-| **`calendar`** | 标题字段和日期字段 | `calendar.title_que_id`、`calendar.date_que_id`；可选 `calendar.color_que_id` |
-
-实现侧校验：对 **table/card**，`columns` 至少包含一列；已知系统字段在读取已有视图时原样透传，不要求出现在表单业务字段索引中。未知系统字段仍会报告覆盖缺口。
-
----
-
-## 6. `filters` / `query_conditions` / `visibility` / `action_buttons`
-
-### 6.0 条件/匹配一眼决策表
-
-先按目标场景选入口。所有入口都接受智能体友好的字段名/操作符语义，但底层编译路径不同。
-
-| 目标场景 | 写到哪里 | 推荐写法 | 不要这样做 |
-| --- | --- | --- | --- |
-| 视图自定义数据范围 | `data_permission` + `filters` | `{"type":"custom","scope":"custom"}`，规则写 `filters` | 不要只写 `filters`；`type=config` 或 `scope` 为 all/oneself/dept/subordinate 时 `filters` 不生效 |
-| 前端查询面板显示哪些字段 | `query_conditions.rows` | `[["客户名称", "负责人"], ["创建时间"]]` | 不要写筛选值；不要把它当 OR 条件 |
-| 按钮显示条件 | `action_buttons[].visible_when` | `{"que_id":101,"operator":"eq","value":"已完工"}` | 不要手写后端判断符 |
-| 当前记录创建下游记录时传值 | `field_mappings` | `{"source_field":"数据ID","target_field":"关联工单"}` | 不要放在 `header` 按钮；`header` 没有当前记录上下文 |
-| 关联视图/关联报表按当前记录过滤 | `associated-resource apply.match_mappings` | `{"target_field":"关联客户","operator":"eq","source_field":"数据ID"}` | 不要用 `filters` 或 `query_conditions` 代替 |
-| 关联视图/关联报表静态筛选 | `match_mappings` | `{"target_field":"状态","operator":"eq","value":"有效"}` | 不要混用 raw `match_rules` |
-
-短规则：**数据权限默认 `custom + all`；自定义范围才写 `filters`（且 `type=custom`、`scope=custom`）；查询栏用 `query_conditions`；当前记录匹配用 `match_mappings`；当前记录传参用 `field_mappings`。**
-
-### 6.1 `filters`
-
-- 项形状：**`que_id`**、**`operator`**、**`values`**（或契约允许的 **`value`** 别名）。
-- **`operator`**：统一公共语义，推荐 `eq` / `neq` / `in` / `contains` / `gte` / `lte` / `is_empty` / `not_empty`；兼容 `equal` / `equals` / `=` / `!=` / `any_of` / `one_of` / `empty` 等别名（以契约为准）。
-- **`in` 等多值**：传 **列表**；**`value`** 为列表时可作别名。
-- **`value` 按字段类型写**：文本/数字/日期直接写业务值；单选/多选/是否优先写选项文本，也支持 option id；成员/部门/关联记录固定筛选优先写唯一 id 或 `{id,value}`。完整规则见 **[reference/match-rules.md](./reference/match-rules.md)**。
-- **语义**：`filters` 是 `data_permission.type=custom` 且 `scope=custom` 时的数据范围，不是叠在 `config` 或预设范围上的第二层筛选。不要把前端查询栏字段写进 `filters`。
-- **写入 / 读回语义**：智能体始终写 `que_id + operator + value/values`；CLI 内部自动转换目标协议，读回也会还原成 `operator/value` 语义。不要手写或解释后端判断符。
-
-示例：
-
-```json
-{"que_id": 101, "operator": "eq", "value": "进行中"}
-```
-
-### 6.2 `query_conditions`
-
-`query_conditions` 是前端“查询条件/查询栏”配置，和 `filters` 是两套语义。新建业务视图必须配置 `query_conditions`，不要交付没有查询面板的业务视图。
-
-- `filters`：仅 `type=custom` 且 `scope=custom` 时作为视图数据范围。默认权限是 `custom + all`，此时不要写 `filters`。
-- `query_conditions`：只配置前端查询面板可输入哪些字段；用户输入查询值后才生效。
-- `rows` 是字段布局矩阵，不表示 OR 条件。
-- `rows` 只放前端查询面板支持的字段：文本、长文本、数字、金额、日期/时间、单选/多选、成员、部门、手机号、邮箱、布尔。
-- 不要把 relation、attachment、subtable/subfield、address、Q-Linker 或 code-block 字段放进 `query_conditions`。
-- 需要自定义数据范围时，写 `data_permission.type=custom`、`scope=custom` 和 `filters`；需要关联报表/关联视图按当前记录匹配时用 `builder associated-resource apply` 的 `match_mappings`。
-- 每个新建业务视图至少配置 2-4 个查询字段；优先选择标题/编号、状态、负责人、日期等高频检索字段。
-
-示例：
-
-```json
-{
-  "name": "客户查询视图",
-  "type": "table",
-  "columns": [101, 102, 103, 104],
-  "filters": [
-    {"que_id": 103, "operator": "eq", "value": "有效"}
-  ],
-  "query_conditions": {
-    "enabled": true,
-    "exact": false,
-    "hide_before_query": false,
-    "rows": [["客户名称", "负责人"], ["创建时间"]]
-  },
-  "action_buttons": [
-    {
-      "text": "行内创建跟进",
-      "action": "add_data",
-      "target_app_key": "FOLLOWUP_APP_KEY",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联客户"}
-      ],
-      "default_values": {"跟进状态": "待跟进"},
-      "placement": "list"
-    },
-    {
-      "text": "详情创建跟进",
-      "action": "add_data",
-      "target_app_key": "FOLLOWUP_APP_KEY",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联客户"}
-      ],
-      "default_values": {"跟进状态": "待跟进"},
-      "placement": "detail"
-    }
-  ]
-}
-```
-
-读回验证时，不要只看视图是否存在；要看 `verification.view_query_conditions_verified=true`。若返回 query condition mismatch，只能说视图已创建/更新，但查询条件未完全验证。
-
-### 6.3 `visibility`
-
-与包/应用/视图等 **授权形态一致**（契约 **`visibility.mode`**：`workspace` | `everyone` | `specific`；**`external_mode`**：`not` | `workspace` | `specific`；**`selectors` / `external_selectors`** 键集合见契约）。
-
-- **更新已存在视图**：省略 **`visibility`** 可 **保留**当前后端权限。
-- **名称类 selector**：须 **唯一解析**，否则失败（不猜测）。
-
-### 6.4 `action_buttons`（主路径）
-
-设计业务视图时，必须同时声明这个视图上的快捷按钮。常规按钮写在视图对象的 `action_buttons` 里，不要先建视图再单独找按钮工具补。新建核心业务视图必须至少包含一个 `placement: "list"` 按钮和一个 `placement: "detail"` 按钮；`header` 按钮可按需增加，但不能替代列表和详情按钮。
-
-创建视图时：
-
-```json
-{
-  "name": "生产工单执行视图",
-  "type": "table",
-  "columns": ["工单编号", "产品", "状态", "负责人"],
-  "filters": [
-    {"que_id": 101, "operator": "in", "values": ["生产中", "已完工"]}
-  ],
-  "query_conditions": {
-    "enabled": true,
-    "exact": false,
-    "hide_before_query": false,
-    "rows": [["工单编号", "状态"], ["负责人"]]
-  },
-  "action_buttons": [
-    {
-      "text": "行内创建质检单",
-      "action": "add_data",
-      "target_app_key": "QUALITY_APP",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联工单"}
-      ],
-      "default_values": {"处理状态": "待处理"},
-      "placement": "list",
-      "visible_when": [
-        {"que_id": 101, "operator": "eq", "value": "已完工"}
-      ]
-    },
-    {
-      "text": "详情创建返工单",
-      "action": "add_data",
-      "target_app_key": "REWORK_APP",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联工单"}
-      ],
-      "default_values": {"返工状态": "待处理"},
-      "placement": "detail"
-    }
-  ]
-}
-```
-
-局部补按钮时：
-
-```json
-{
-  "view_key": "RAW_VIEW_KEY",
-  "set": {
-    "action_buttons": [
-      {
-        "text": "行内创建验收单",
-        "action": "add_data",
-        "target_app_key": "ARRIVAL_APP",
-        "field_mappings": [
-          {"source_field": "数据ID", "target_field": "关联工单"}
-        ],
-        "default_values": {"状态": "待验收"},
-        "placement": "list"
-      },
-      {
-        "text": "详情创建验收单",
-        "action": "add_data",
-        "target_app_key": "ARRIVAL_APP",
-        "field_mappings": [
-          {"source_field": "数据ID", "target_field": "关联工单"}
-        ],
-        "default_values": {"状态": "待验收"},
-        "placement": "detail"
-      }
-    ],
-    "action_buttons_mode": "merge"
-  }
-}
-```
-
-规则：
-
-- `action_buttons_mode` 默认 `merge`：新增/更新声明按钮并绑定到该视图，不清空已有按钮。
-- `replace`：替换该视图上的自定义按钮绑定；`action_buttons: []` + `action_buttons_mode: "replace"` 可清空视图按钮绑定，但不删除按钮本体。
-- 新建核心业务视图时 `query_conditions` 和 `action_buttons` 都不能为空，并且按钮必须同时配置 `placement: "list"` 和 `placement: "detail"`。不要交付缺少查询面板或缺少列表/详情按钮的核心操作视图。
-- `publish=false` + `action_buttons` 会被阻断为 `VIEW_ACTION_BUTTONS_REQUIRE_PUBLISH`。
-- 视图内按钮写智能体语义：`action: "add_data"` 或 `action: "link"`。不要手写底层触发名。
-- 响应里同时看 `verification.views_verified`、`verification.action_buttons_verified`、`verification.view_button_bindings_verified`。
-- 按钮失败但视图成功时是 `partial_success`；先按 `suggested_next_call` 用 `patch_views` 重试失败视图。 如果回读里目标视图已有 `CUSTOM` 按钮、文本/位置/触发类型正确，不要重建视图或重复创建按钮。
-
-`default_values` 是写入**目标应用新增表单**的静态默认值，必须按目标应用 schema 写：
-
-- 写按钮前先确认 **`target_app_key` 对应应用**的字段与选项；优先用 `builder app get --app-key TARGET_APP fields` 看字段名/选项，必要时用 `record schema insert --app-key TARGET_APP` 看 insert-ready 写入格式。
-- 单选/多选字段的默认值必须来自目标字段 `options` 的**原始文本或 option id**；不要用业务近义词。例如 schema 选项是 `每月`、`中`，就不要写 `月检`、`普通`。
-- 成员/部门/关联字段默认值按 record insert 的写法处理；不确定候选或目标记录时，先只写 `field_mappings`，不要编造 `default_values`。
-- `field_mappings[].target_field` 和 `default_values` 的 key 都是**目标应用字段名**，不是当前视图字段名。
-- CLI 会在按钮写入前校验默认值；非法值会返回 `CUSTOM_BUTTON_DEFAULT_VALUE_UNSUPPORTED`。这时视图可能已经创建成功，只需要用 `patch_views` + raw `view_key` 修正 `action_buttons.default_values`，不要重建视图或应用。
-
-正确示例：
-
-```json
-"default_values": {
-  "巡检周期": "每月",
-  "优先级": "中",
-  "隐患等级": "中"
-}
-```
-
-按钮一眼决策表：先按**用户真实意图**选，不要先从按钮枚举反推业务。
-
-| 用户真实意图 | 视图内 `action` | 推荐位置 | 必需配置 | 禁止误用 |
-| --- | --- | --- | --- | --- |
-| 从当前记录生成下游/关联记录，例如工单生成质检、订单生成到货、客户生成跟进 | `add_data` | `detail` 和 `list` 都要配置 | `target_app_key` + `field_mappings`，通常 `source_field: "数据ID"` 指向目标应用的关联/引用字段；`default_values` 必须按目标应用 schema/options 写 | 目标应用或关联字段不清楚时不要猜；不要放在 `header` 后又引用当前记录字段；不要编造选项近义词 |
-| 创建不依赖当前行的独立记录或全局入口 | `add_data` | `header` | `target_app_key`；不要写当前记录 `source_field` | 不要假装有当前记录上下文 |
-| 打开 SOP、外部系统、帮助文档、固定页面 | `link` | `header` 或 `detail` | `url` | 不要用它代替新增数据、审批、状态流转或数据写回 |
-| 审批、通过、驳回、状态流转、关闭任务 | 默认不配普通按钮 | 先判断工作流/任务动作/已有自动化 | 用户明确要求普通按钮且能落到 `add_data` / `link` 时才配置 | 不要用 `link`、空按钮或伪 URL 假装完成 |
-
-核心判断：**要把当前记录的数据带到另一个应用，就用 `add_data`；只打开页面就用 `link`；审批/状态流转不是普通按钮。**
-
-按钮位置选择：
-
-| `placement` | 前端位置 | 适合场景 | 注意事项 |
-| --- | --- | --- | --- |
-| `header` | 视图顶部 | 全局入口，不依赖当前行：打开说明、创建独立记录、批量入口 | 不能依赖当前记录的 `source_field` |
-| `list` | 列表/行内 | 对当前行记录操作：从工单创建质检、从客户创建跟进 | 必须确认当前记录上下文可用于 `field_mappings` |
-| `detail` | 记录详情页 | 当前记录上下文操作：创建子记录、查看外部详情、补充材料 | 最稳妥的上下文按钮位置 |
-
-不同视图类型：
-
-- `table`：必须配置 `list` 和 `detail` 快捷按钮，是最适合放业务按钮的视图。
-- `board`：必须配置状态相关的 `list` 和 `detail` 快捷按钮，并配 `visible_when`，例如只在“待验收”显示“创建验收单”。
-- `card`：必须配置 `detail`，并在卡片行操作明确时配置 `list`；核心操作视图不要只给 `header`。
-- `gantt`：不适合作为唯一核心操作视图；需要快捷按钮时同时提供配套 table/board 视图，在该操作视图中配置 `list` 和 `detail`。
-
-### 6.4.1 绑定已有自定义按钮（`buttons`，查重优先）
-
-视图声明里的 `buttons[]` 只做绑定（引用应用级自定义按钮的 `button_id`），不会创建按钮本体。绑定前必须查重，不要重复创建同名按钮：
-
-1. **查询**：`qingflow --json builder button get --app-key APP --button-text 按钮文案`（MCP `app_get_buttons` 传 `button_text`），按文案精确匹配。
-2. **有则复用**：唯一命中 → 取返回的 `button_id` 直接写进 `buttons[]`；同名多个 → 用 `button_id` 精确指定（避免歧义）。
-3. **没有再创建**：`builder button apply` 创建（其自身也按文案去重），拿到 `button_id` 后回到视图声明绑定。
-
-按钮本体维护（样式/跨视图复用/删除本体）见 [80-buttons-associated-resources.md](./80-buttons-associated-resources.md)。
-
-### 6.5 关联视图/报表
-
-新版默认不要通过 `app_views_apply.associated_resources` 配置关联资源。应用级关联资源池和视图展示开关统一走 **`app_associated_resources_apply`** / CLI **`builder associated-resource apply`**。
-
-- `builder views apply` **新建视图时默认开启详情页关联查看**：等价于 `asosChartVisible=true`、`limit_type=all`，会展示当前应用级关联资源池里的全部关联视图/报表。
-- **更新已有视图**：未显式传 `associated_resources` 时保留原关联查看状态；需要关闭或改成指定资源时，用 **`builder associated-resource apply --view-configs-file`**，或维护旧配置时显式 patch `associated_resources`。
-- 已有资源的最终口径是 `app_get.associated_resources[].associated_item_id`；它不是 `chart_id`、`chart_key` 或 `view_key`。
-- 新版 CLI 在关联报表时可先传 `chart_id` / `chart_key`，内部会解析为轻流后端需要的 id；创建前先检查是否已有相同 `target_app_key + view_key/chart_key`，已存在时用 `patch_resources`；`client_key` 只在同一次 apply 中可被 `associated_item_refs` 引用，不会持久化。
-- 数据集 BI 报表只能关联已有报表，使用 `report_source: "dataset"`；应用源报表可先用 `builder charts apply` 创建/更新。
-- 关联筛选优先用 `match_mappings`；字段类型、`operator`、`value/values` 和跨应用当前记录匹配规则见 **[reference/match-rules.md](./reference/match-rules.md)**。
-
----
-
-## 7. 删除视图
-
-- 主路径使用 `--remove-views-file`；元素是 raw **`view_key`** 或唯一视图显示名，应用通过 `--app-key` 指定。
-- 优先用 **`view_key`** 删除；显示名重名会导致 **`AMBIGUOUS_VIEW`**，需先在 **`app get views`** 里确认。
-- DELETE 发出后，工具会用单个 **`view_key`** 回读验证，而不是再读全量视图列表判断删除结果。
-- 删除结果看 **`verification.view.delete_executed`**、**`readback_status`**、**`safe_to_retry_delete`**：
-  - **`readback_status=deleted`**：删除已验证。
-  - **`readback_status=unavailable`** 或 **`still_exists`**：删除请求已发出但回读未完全确认，**不要盲目重复删除**；稍后用 `builder app get views` 或对应视图详情确认。
-
----
-
-## 8. 契约示例（可复制为文件基底）
-
-**Table + `visibility`（`minimal_example` 节选）**：
-
-```json
-{
-  "name": "项目台账视图",
-  "type": "table",
-  "columns": [101],
-  "visibility": {
-    "mode": "workspace",
-    "selectors": {},
-    "external_mode": "not",
-    "external_selectors": {}
-  }
-}
-```
-
-**Gantt（`gantt_example` 节选）**：
-
-```json
-{
-  "name": "项目甘特图",
-  "type": "gantt",
-  "columns": [101, 102, 103],
-  "start_que_id": 102,
-  "end_que_id": 103,
-  "title_que_id": 101,
-  "filters": [
-    {
-      "que_id": 101,
-      "operator": "eq",
-      "value": "进行中"
-    }
-  ]
-}
-```
-
-**Table + 筛选 + 查询条件 + 快捷按钮（单条 `--view-file`）**：
-
-```json
-{
-  "name": "客户查询视图",
-  "type": "table",
-  "columns": [101, 102, 103, 104],
-  "filters": [
-    {"que_id": 103, "operator": "eq", "value": "有效"}
-  ],
-  "query_conditions": {
-    "enabled": true,
-    "exact": false,
-    "hide_before_query": false,
-    "rows": [["客户名称", "负责人"], ["创建时间"]]
-  },
-  "action_buttons": [
-    {
-      "text": "行内创建跟进",
-      "action": "add_data",
-      "target_app_key": "FOLLOWUP_APP_KEY",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联客户"}
-      ],
-      "default_values": {"跟进状态": "待跟进"},
-      "placement": "list"
-    },
-    {
-      "text": "详情创建跟进",
-      "action": "add_data",
-      "target_app_key": "FOLLOWUP_APP_KEY",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联客户"}
-      ],
-      "default_values": {"跟进状态": "待跟进"},
-      "placement": "detail"
-    }
-  ]
-}
+qingflow --json builder views schema --schema-version v1alpha1 --schema-kind complete
+qingflow --json builder views validate --schema-version v1alpha1 --file view.json
+qingflow builder views apply --app-key APP_KEY --schema-version v1alpha1 --view-file view.json --publish
 ```
 
----
+- `--view-file`：一个视图对象，新建或完整更新。一次一个应用、一个操作。
+- `--patch-views-file`：已有视图的局部更新。JSON 数组最多一项，含 raw `view_key` 或唯一 `name`，以及 `set` / `unset`。
+- `--remove-views-file`：删除。数组最多一项，优先 raw `view_key`。
+- 三种文件不能混用。不要传 `views`、`upsert_views`、`upsert_view` 包装或多项数组。多个视图逐次调用。
+- `app_key`、`profile` 写在命令上，不要写进视图对象。
+- 读已有声明：`builder views get --app-key APP --schema-version v1alpha1 --schema-kind complete`。出现 `VIEW_NOT_EXTRACTABLE` 时改用 patch，不要拿残缺声明覆盖。
+- MCP：`app_views_schema`，然后 `app_views_apply` 的 `upsert_view`（一个对象）、`patch_views`（最多一项）或 `remove_views`（最多一项）。
 
-## 9. 实测记录（`ead8ims5i401`，`--publish`）
+字段、枚举、`data_permission`、各视图类型必填项都在 schema 的 `*Description` 里。`columns`、`filters`、`query_conditions.rows`、标题和时间字段写整数 queId。业务字段中文名不会解析。已知系统字段可以用 queId 或公开名，例如 `2` / `提交时间`、`0` / `编号`、`-17` / `数据ID`。
 
-内容与仓库 **[views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json)** 一致（或历史探针名 **`CLI探针视图_可删`**）。
+## 交付约束
 
-**读视图**：
-
-```bash
-qingflow --json builder app get --app-key ead8ims5i401 views
-```
-
-**应用**：
-
-```bash
-qingflow builder views apply \
-  --app-key ead8ims5i401 \
-  --publish \
-  --view-file ./view.json
-```
+- 新建业务视图写 `query_conditions`（至少 2–4 个查询字段）和 `action_buttons`，并且 `publish=true`。`publish=false` 带按钮会返回 `VIEW_ACTION_BUTTONS_REQUIRE_PUBLISH`。只读或归档视图可以没有按钮，仍应有查询面板。
+- `action_buttons` 至少各有一个 `placement: "list"` 和 `"detail"`。`header` 没有当前行上下文，不能写当前记录的 `field_mappings`。
+- 当前记录带到另一个应用用 `action: "add_data"`（`target_app_key` + `field_mappings`，通常 `source_field: "数据ID"`）。只打开页面用 `action: "link"` 加 `url`。审批、状态流转、关闭任务走流程，不要用普通按钮假装。
+- `default_values` 的 key 和 `field_mappings[].target_field` 是目标应用字段。选项必须是目标字段的原文或 option id。不确定就不要编造；`CUSTOM_BUTTON_DEFAULT_VALUE_UNSUPPORTED` 时用 patch 改默认值，不要重建视图。
+- `action_buttons_mode` 默认 `merge`。`replace` 加空数组只清绑定，不删按钮本体。已有按钮先 `builder button get --button-text`，唯一命中后用 `buttons[]` 的 `button_id` 绑定。
+- 写出 `data_permission` 时 `type` 和 `scope` 都必填，优先 `{"type":"custom","scope":"all"}`。整段省略时创建路径才用这个默认。`filters` 只在 `type=custom` 且 `scope=custom` 时是数据范围。不要把 `filters` 叠在 `config` 或预设范围上，也不要把它当查询栏。
+- 写出 `visibility` 时 `mode` 必填。`mode=specific` 必须带 `selectors`（各列表不单独必填，空对象表示尚未配置成员）。`mode=everyone` 时 `external_mode` 必须是 `workspace`。`external_mode=specific` 必须带 `external_selectors`。整段省略时创建路径按工作区可见。
+- 查询栏不要放 relation、attachment、subtable、address、Q-Linker、code-block。
+- 不要新建名为 `全部数据`、`我的数据`、`我发起的`、`待办`、`已办`、`抄送` 的视图。要改它们，先读 raw `view_key` 再 patch。`view_key` 不要加 `custom:` 前缀。
+- 未带 `view_key` 时，唯一同名视图会被更新，重名返回 `AMBIGUOUS_VIEW`。局部修改用 patch，不要用只含少数字段的完整对象去覆盖。
+- 新建视图默认打开详情页关联查看（全部应用级关联资源）。改展示范围、匹配规则用 `builder associated-resource apply`，不要把关联筛选写进 `filters` 或 `query_conditions`。
+- 新建要同时满足视图管理和数据管理权限。更新和删除只要视图管理。常见失败 `40002` / `40161` / 编辑锁。
 
-**结果摘要**（示例视图名 **`示例业务操作视图_CLI模板`**）：`status: success`，`verification.view.status: created`，返回 **`view_key`**（如 **`ecdk22v65c02`**），并验证 `query_conditions` 与 `action_buttons`。
+## 回读
 
----
+成功看 `verification.view.status`（`created` / `updated`）。不要只凭视图存在就说筛选、查询或按钮已生效：
 
-## 10. 排障要点
+- 筛选：`view_filters_verified`
+- 查询：`view_query_conditions_verified`
+- 按钮：`action_buttons_verified` 与 `view_button_bindings_verified`
 
-| 现象 | 处理 |
-|------|------|
-| 列校验失败 / 无有效业务列 | **`app get fields`** 核对 **`name`**；避免 `columns` 仅含 **§7.1 系统列** |
-| 响应含 **`STALE_FIELD_REFERENCE`** / **`STALE_OPTION_REFERENCE`** 警告 | 声明引用了表单中已删除的字段/选项(后端保存视图本就原样透传);apply 已照写并在 `warnings` 留痕,重放/迁移场景属预期,人工整理时再清理死引用 |
-| 系统字段作标题/时间轴 | `title_que_id`/甘特 `start_que_id` 等可直接用系统字段 id(如 2=提交时间),与 `columns` 系统列同规则 |
-| 重名视图 / 删错 | **`app get views`**；更新时带 **`view_key`** |
-| 过滤器未生效疑虑 | 看响应 **`verification.view_filters_verified`**；必要时再 **`app get views`** |
-| 查询条件未生效疑虑 | 看响应 **`verification.view_query_conditions_verified`**；不要把 `query_conditions` 当 `filters` |
-| 后端 **40038 / Object not exist** | 先读失败项 **`details.view_result.details.field_level_diagnostics`** 与 **`recommended_minimal_retry`**。不要删除字段、不要重建应用；先按最小列重试，再逐步加非关键列/筛选。 |
-| 按钮/关联资源配置 | 常规业务按钮随视图写 **`action_buttons`**；关联视图/报表走 **`builder associated-resource apply`** |
-| 部分失败 | 读 **`views_diff.failed`** 与契约 **execution_notes** 中 **partial_success** |
-| 权限/锁 | 同 [publish verify](./99-publish-verify.md) 与 [app delivery reference](./reference/app-delivery-sop.md) |
+`partial_success` 表示视图可能已写入，附属校验未过。按 `suggested_next_call` 对同一 `view_key` 做 patch。回读里按钮文案、位置、触发类型已经正确时，不要再建一次。
 
----
+删除看 `verification.view.delete_executed` 和 `readback_status`。`unavailable` 或 `still_exists` 时不要立刻重删，改用 `app get views` 确认。
 
-## 11. 交叉引用
+`STALE_FIELD_REFERENCE` 表示声明引用了已删除字段，保存会原样透传。`40038` 时读 `field_level_diagnostics`，按最小列重试，不要删字段或重建应用。
 
-- [views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json)（单视图示例，可直接作为 `--view-file` 使用）
-- [SKILL.md](../../SKILL.md)：builder 直接输出、鉴权顺序。
-- [99-publish-verify.md](./99-publish-verify.md)：发布与回读。
-- [reference/app-delivery-sop.md](./reference/app-delivery-sop.md)：系统列与历史交付细节。
-- [QINGFLOW_CLI_EXPLORATION_REPORT.md](../core/QINGFLOW_CLI_EXPLORATION_REPORT.md)：CLI 覆盖与 **`view_id` vs `view_key`** 备忘。
+示例对象见 [views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json)。操作符和跨应用匹配见 [reference/match-rules.md](./reference/match-rules.md)。按钮本体维护见 [80-buttons-associated-resources.md](./80-buttons-associated-resources.md)。

package/skills/qingflow-cli/reference/builder/80-buttons-associated-resources.md

@@ -28,7 +28,7 @@ app get -> app get views/charts/buttons/associated resources -> apply button or
 - Use this standalone button tool for advanced cases: deleting button bodies, reusing the same button across many views, bulk reordering bindings, changing style independently, or configuring qRobot/wings when the user provides exact config.
 - Use `upsert_buttons` for create/update and `patch_buttons` for small changes.
 - Use `view_configs` only after reading target raw `view_key`.
-- Use semantic conditions from [reference/match-rules.md](./reference/match-rules.md). Fixed filters use `field_name + operator + value/values`; associated-resource context matching uses `target_field + operator + source_field/value`.
+- Use semantic conditions from [reference/match-rules.md](./reference/match-rules.md). View `filters` and `visible_when` use `que_id`; chart filters use `field_name`; associated-resource context matching uses `target_field + operator + source_field/value`.
 - For add-data button field mappings, use target/source semantics, not raw backend ids, unless a contract explicitly requires ids.
 - If `button apply` returns `CUSTOM_BUTTON_APPLY_PARTIAL` / `VIEW_CUSTOM_BUTTON_READBACK_PENDING` while `custom_buttons_verified=true`, do not recreate the button. Run `builder app get --app-key APP views` and inspect the target view `buttons[]` for `button_type=CUSTOM` plus the expected `button_text` or `button_id`. Only reapply `view_configs` if the view binding is actually absent.
 

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

@@ -396,7 +396,7 @@ qingflow builder flow apply \
 **`数据ID`**、**`编号`**、**`申请人`**、**`申请时间`**、**`创建人`**、**`创建时间`**、**`提交人`**、**`提交时间`**、**`更新时间`**、**`更新人`**、**`当前流程状态`**、**`当前处理人`**、**`当前处理节点`**、**`流程标题`**。
 
 - **含义**：这些是平台维护的系统信息，**不要**在 **`add_fields`** 里手工造同名控件来「模拟」，也不要写进 `record insert` 的 `fields` / `items[].fields`。
-- **视图列例外**：`builder views apply` 对部分系统列名会过滤并警告（`ignored_system_columns`）；新建/更新业务视图至少要包含一个真实业务字段。
+- **视图列例外**：已知系统字段可以按 queId 或公开名出现在 `columns`、标题、甘特/日历日期和 `query_conditions` 里，例如 `2` / `提交时间`。不要在 `add_fields` 里再造同名控件。未知系统 id 仍会报告缺口。
 - **与 `app_get_fields` 的关系**：读回 **`fields[]`** 侧重 **表单搭建字段**；**编号 / 申请人** 等可能不会作为普通 `type` 出现在列表中（视应用模板与工作流是否开启），**以读回 JSON 为准**。交付时 **业务字段** 用 **`app_get_fields`**；**系统列** 由平台在 **数据列表 / 视图** 侧展示。
 
 ### 7.2 布局 / 流程中的「系统行为」

package/skills/qingflow-cli/reference/builder/reference/match-rules.md

@@ -2,7 +2,7 @@
 
 本文适用于 Builder 侧所有给智能体公开的筛选和条件入口：
 
-- 视图固定筛选：`builder views apply` 的 `filters`
+- 视图数据范围：`builder views apply` 的 `filters`。只在 `data_permission.type=custom` 且 `scope=custom` 时生效，字段写 `que_id`
 - 视图动作按钮显示条件：`action_buttons[].visible_when`
 - QingBI 图表筛选：`builder charts apply` 或 `portal apply sections[].chart.filters`
 - 关联视图 / 关联报表匹配：`builder associated-resource apply` 的 `match_mappings`
@@ -13,7 +13,8 @@
 
 公开写法按场景选择，智能体不要混用。**operator 语义完全一致，区别只在字段名键**：
 
-- **固定筛选**：`field_name + operator + value/values`
+- **视图数据范围、查询条件和按钮可见条件**：`que_id + operator + value/values`
+- **图表固定筛选**：`field_name + operator + value/values`
 - **关联资源上下文匹配**：`target_field + operator + source_field/value`
 - **新增数据传参**：`source_field + target_field`；静态默认值写 `default_values`
 
@@ -23,7 +24,8 @@
 
 | 你想表达 | 写法 | 示例 |
 | --- | --- | --- |
-| 当前视图/图表只显示某类数据 | `filters` | `{"field_name":"状态","operator":"eq","value":"进行中"}` |
+| 当前视图只显示某类数据 | `filters` | `{"que_id":101,"operator":"eq","value":"进行中"}`，且 `data_permission` 为 `custom` + `custom` |
+| 图表只显示某类数据 | `filters` | `{"field_name":"状态","operator":"eq","value":"进行中"}` |
 | 关联报表/关联视图只显示“当前记录相关”的数据 | `match_mappings` + `source_field` | `{"target_field":"关联客户","operator":"eq","source_field":"数据ID"}` |
 | 关联报表/关联视图再加一个固定条件 | `match_mappings` + `value/values` | `{"target_field":"状态","operator":"eq","value":"有效"}` |
 | 从当前记录创建下游记录并带值 | `field_mappings` | `{"source_field":"数据ID","target_field":"关联工单"}` |
@@ -90,9 +92,10 @@
 
 优先使用语义化映射，不手写后端 raw `que_relation` / `match_rules`。
 
-心智模型：**同一个 operator，同一套 value 规则；只是当前记录匹配要把 `field_name` 改成 `target_field`，并用 `source_field` 表示当前记录字段。**
+心智模型：**同一个 operator，同一套 value 规则；只是当前记录匹配要把字段键改成 `target_field`，并用 `source_field` 表示当前记录字段。**
 
-- 固定筛选当前资源自己的数据：`field_name + operator + value/values`
+- 视图数据范围：`que_id + operator + value/values`，且 `data_permission` 为 `custom` + `custom`
+- 图表固定筛选：`field_name + operator + value/values`
 - 用当前记录过滤另一个资源：`target_field + operator + source_field`
 - 给另一个资源加静态筛选：`target_field + operator + value/values`
 - 从当前记录创建下游记录时传值：`source_field + target_field`，不写 `operator`

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md

@@ -55,7 +55,7 @@
 | --- | --- |
 | `builder app get` | 应用地图；轻量返回字段摘要、视图、图表、自定义按钮、关联资源池 |
 | `builder app-form schema/get/validate/apply` | 当前表单/字段/布局/应用设置入口；固定 AppForm schema 版本，完整声明写入并保留现有 IDs；旧 `builder schema apply` / `builder layout apply` 仅为已移除的内部兼容适配器 |
-| `builder views apply` | 业务视图；固定筛选写 `filters`，前端查询栏写 `query_conditions` |
+| `builder views apply` | 业务视图。字段形状读 `views schema`；一次一个视图对象。数据权限默认 `custom + all`，自定义范围才写 `filters`；查询栏写 `query_conditions` 的 queId |
 | `builder button apply` | 自定义按钮默认路径；新增数据按钮用 `field_mappings/default_values`，绑定位置用 `header/detail/list` |
 | `builder associated-resource apply` | 应用级关联视图/报表池 + 视图展示配置；报表来源用 `report_source`，不让智能体填写后端 raw source |
 | `builder charts apply` | QingBI 报表配置；报表变更 immediate-live，不等同于应用发布 |

package/skills/qingflow-cli/reference/examples/views/views_apply_v1alpha1.example.json

@@ -2,13 +2,13 @@
   "name": "项目台账视图",
   "type": "table",
   "columns": [100, 101, 102, 103],
-  "data_permission": {"type": "custom", "scope": "dept"},
+  "data_permission": {"type": "custom", "scope": "all"},
   "sort": [{"que_id": 100, "ascending": false}],
   "display": {"row_height": "compact", "pin_navigate": true},
   "query_conditions": {
     "enabled": true,
     "exact": false,
     "hide_before_query": false,
-    "rows": [["项目名称", "负责人"], ["创建时间"]]
+    "rows": [[100, 101], [2]]
   }
 }

package/skills/qingflow-cli/reference/examples/views/views_upsert_table_minimal.example.json

@@ -9,7 +9,7 @@
     "enabled": true,
     "exact": false,
     "hide_before_query": false,
-    "rows": [["主记录编号", "主记录名称"], ["状态", "负责人"]]
+        "rows": [[100, 101], [102, 2]]
   },
   "action_buttons": [
     {

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/complete.json

@@ -311,7 +311,8 @@
     "DataPermission": {
       "type": "object",
       "additionalProperties": false,
-      "dataPermissionDescription": "先选来源 type，再在 type=custom 时选 scope。默认且优先写 custom + all。filters 只在 type=custom 且 scope=custom 时作为数据范围，不会叠在 config 或预设范围上。",
+      "required": ["type", "scope"],
+      "dataPermissionDescription": "写出本对象时 type 与 scope 都必填。优先写 custom + all。整段 data_permission 省略时，创建路径才按 custom + all。filters 只在 type=custom 且 scope=custom 时作为数据范围，不会叠在 config 或预设范围上。",
       "properties": {
         "type": {
           "type": "string",
@@ -320,7 +321,7 @@
             "custom"
           ],
           "default": "custom",
-          "dataPermissionDescription": "数据权限来源，默认 custom。未声明时按 custom + all 创建。config=跟随应用成员授权的数据权限，本视图的 scope 与 filters 不参与查询。custom=使用本视图自己的数据范围(scope)。别名 dataPermissionType(CONFIG/CUSTOM)。",
+          "dataPermissionDescription": "数据权限来源。写出 data_permission 时必填。config=跟随应用成员授权的数据权限，本视图的 scope 与 filters 不参与查询。custom=使用本视图自己的数据范围(scope)。别名 dataPermissionType(CONFIG/CUSTOM)。",
           "x-backend": "dataPermissionType(CONFIG|CUSTOM)"
         },
         "scope": {
@@ -333,7 +334,7 @@
             "custom"
           ],
           "default": "all",
-          "dataScopeDescription": "仅 type=custom 时生效，默认 all。all=不追加数据范围；oneself=仅自己发起；dept=所在部门发起；subordinate=下属发起；custom=用 filters 作为数据范围。type=config 时不要用 scope 选择应用权限，应用授权组的范围写在成员授权上。",
+          "dataScopeDescription": "写出 data_permission 时必填，且只在 type=custom 时生效。all=不追加数据范围；oneself=仅自己发起；dept=所在部门发起；subordinate=下属发起；custom=用 filters 作为数据范围。type=config 时不要用 scope 选择应用权限，应用授权组的范围写在成员授权上。",
           "x-backend": "dataScope(ALL|ONESELF|DEPT|SUBORDINATE|CUSTOM)"
         }
       }
@@ -341,6 +342,34 @@
     "Visibility": {
       "type": "object",
       "additionalProperties": false,
+      "required": ["mode"],
+      "visibilityDescription": "写出 visibility 时 mode 必填。mode=specific 时必须带 selectors；selectors 各列表都不是单独必填，空对象表示指定范围但尚未配置成员。mode=everyone 时 external_mode 必须为 workspace。external_mode=specific 时必须带 external_selectors。整段省略时创建路径按 workspace + external_mode=not。",
+      "allOf": [
+        {
+          "if": {
+            "properties": { "mode": { "const": "specific" } },
+            "required": ["mode"]
+          },
+          "then": { "required": ["selectors"] }
+        },
+        {
+          "if": {
+            "properties": { "mode": { "const": "everyone" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["external_mode"],
+            "properties": { "external_mode": { "const": "workspace" } }
+          }
+        },
+        {
+          "if": {
+            "properties": { "external_mode": { "const": "specific" } },
+            "required": ["external_mode"]
+          },
+          "then": { "required": ["external_selectors"] }
+        }
+      ],
       "properties": {
         "mode": {
           "type": "string",
@@ -373,6 +402,7 @@
     "VisibilitySelectors": {
       "type": "object",
       "additionalProperties": false,
+      "visibilitySelectorsDescription": "成员、部门、角色用不同列表表达，没有任何一个列表单独必填。mode=specific 时本对象本身必填；空对象是合法回读，表示指定范围但尚未配置成员。要真正授权时，至少填一个非空列表。",
       "properties": {
         "member_uids": {
           "type": "array",

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/data-permission.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/details/data-permission.json",
   "title": "Qingflow Views data permission configuration",
-  "dataPermissionDescription": "视图数据权限片段(schema_kind=data-permission)。默认且优先写 data_permission {type: custom, scope: all}。type 选来源，scope 只在 type=custom 时生效；filters 只在 type=custom 且 scope=custom 时作为数据范围。字段直接并入完整视图声明。",
+  "dataPermissionDescription": "视图数据权限片段(schema_kind=data-permission)。写出 data_permission 时 type 与 scope 都必填，优先 {type: custom, scope: all}。整段省略时创建路径才按 custom + all。type 选来源，scope 只在 type=custom 时生效；filters 只在 type=custom 且 scope=custom 时作为数据范围。字段直接并入完整视图声明。",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -36,7 +36,7 @@
       "fieldSchema": "字段类型、默认值等表单侧细节用 app_form_schema 传 schema_kind=field 和 field_type 获取(CLI: builder app-form schema --schema-kind field --field-type TYPE)。"
     }
   },
-  "x-qingflow-apply-semantics": "新建视图默认且应优先写 data_permission type=custom、scope=all。只有要跟随应用成员授权时才用 type=config，此时不要用 scope 表达范围。filters 仅在 type=custom 且 scope=custom 时作为数据范围；省略 filters 表示保留现有规则，空数组表示清空。",
+  "x-qingflow-apply-semantics": "写出 data_permission 时 type 与 scope 都必填，优先 type=custom、scope=all。整段省略时创建路径才按 custom + all。只有要跟随应用成员授权时才用 type=config，此时不要用 scope 表达范围。filters 仅在 type=custom 且 scope=custom 时作为数据范围；省略 filters 表示保留现有规则，空数组表示清空。",
   "x-qingflow-mode-requirements": {
     "default": "未声明 data_permission 时按 custom + all 创建。需要限制行时再改 scope，不要默认改成 config。",
     "config": "跟随应用成员授权的数据权限。视图上的 scope、filters 不参与查询。应用授权组自己可以是全部、自己、部门、下属或自定义公式，那些规则写在成员授权上，不写在视图声明里。",

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/summary.json

@@ -199,7 +199,8 @@
     "DataPermission": {
       "type": "object",
       "additionalProperties": false,
-      "dataPermissionDescription": "先选来源 type，再在 type=custom 时选 scope。默认且优先写 custom + all。filters 只在 type=custom 且 scope=custom 时作为数据范围，不会叠在 config 或预设范围上。",
+      "required": ["type", "scope"],
+      "dataPermissionDescription": "写出本对象时 type 与 scope 都必填。优先写 custom + all。整段 data_permission 省略时，创建路径才按 custom + all。filters 只在 type=custom 且 scope=custom 时作为数据范围，不会叠在 config 或预设范围上。",
       "properties": {
         "type": {
           "type": "string",
@@ -208,7 +209,7 @@
             "custom"
           ],
           "default": "custom",
-          "dataPermissionDescription": "数据权限来源，默认 custom。未声明时按 custom + all 创建。config=跟随应用成员授权的数据权限，本视图的 scope 与 filters 不参与查询。custom=使用本视图自己的数据范围(scope)。别名 dataPermissionType(CONFIG/CUSTOM)。",
+          "dataPermissionDescription": "数据权限来源。写出 data_permission 时必填。config=跟随应用成员授权的数据权限，本视图的 scope 与 filters 不参与查询。custom=使用本视图自己的数据范围(scope)。别名 dataPermissionType(CONFIG/CUSTOM)。",
           "x-backend": "viewgraph.dataPermissionType(CONFIG|CUSTOM)"
         },
         "scope": {
@@ -221,7 +222,7 @@
             "custom"
           ],
           "default": "all",
-          "dataScopeDescription": "仅 type=custom 时生效，默认 all。all=不追加数据范围；oneself=仅自己发起；dept=所在部门发起；subordinate=下属发起；custom=用 filters 作为数据范围(规则在 complete 或 schema_kind=data-permission)。type=config 时不要用 scope 选择应用权限，应用授权组的范围写在成员授权上。dataset-v0 实测分布:all×560 / custom×74 / oneself×71。",
+          "dataScopeDescription": "写出 data_permission 时必填，且只在 type=custom 时生效。all=不追加数据范围；oneself=仅自己发起；dept=所在部门发起；subordinate=下属发起；custom=用 filters 作为数据范围(规则在 complete 或 schema_kind=data-permission)。type=config 时不要用 scope 选择应用权限，应用授权组的范围写在成员授权上。dataset-v0 实测分布:all×560 / custom×74 / oneself×71。",
           "x-backend": "viewgraph.dataScope(ALL|ONESELF|DEPT|SUBORDINATE|CUSTOM)"
         }
       }