@qingflow-tech/qingflow-cli 1.1.62-beta.1 → 1.1.63

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
7
7
  ## 安装
8
8
 
9
9
  ```bash
10
- npm install @qingflow-tech/qingflow-cli@1.1.62-beta.1
10
+ npm install @qingflow-tech/qingflow-cli@1.1.63
11
11
  ```
12
12
 
13
13
  推荐从官网复制这一条一键安装 Qingflow CLI:
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
21
21
  ## 运行
22
22
 
23
23
  ```bash
24
- npx -y -p @qingflow-tech/qingflow-cli@1.1.62-beta.1 qingflow
24
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.63 qingflow
25
25
  ```
26
26
 
27
27
  全局安装后可以直接运行:
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
62
62
  如果你通过一次性 `npx -p` 执行 skills 安装,建议加 `--copy`,避免 symlink 指向 npm 临时执行缓存:
63
63
 
64
64
  ```bash
65
- npx -y -p @qingflow-tech/qingflow-cli@1.1.62-beta.1 qingflow-skills install --agent codex --scope user --copy
65
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.63 qingflow-skills install --agent codex --scope user --copy
66
66
  ```
67
67
 
68
68
  `qingflow-skills install` 默认使用 symlink,且遇到同名 skill 不会覆盖;只有显式传入 `--force` 才会替换。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qingflow-tech/qingflow-cli",
3
- "version": "1.1.62-beta.1",
3
+ "version": "1.1.63",
4
4
  "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "qingflow-mcp"
7
- version = "1.1.62b1"
7
+ version = "1.1.63"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -3,9 +3,6 @@ name: qingflow-cli
3
3
  description: |
4
4
  【强制】在执行或编排任何 qingflow CLI 命令前必须优先加载本 Skill。
5
5
  Qingflow CLI 主入口:规定命令执行与 JSON 落盘方式,并把普通应用数据默认路由到 data;task、builder、import、日志、附件和代码块按专项参考执行。
6
- Qingflow CLI 包以本 Skill 作为 CLI 主入口;record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。
7
- 指导安装、执行上下文失败恢复、查询与写入;规定 task/record/import/builder 查询落盘;覆盖普通成员读数、字段 kind 与数据形态、任务上下文、批量导入、record access/list/get/insert/update/delete 与管理端边界。
8
- Builder SOP 按智能体任务路径组织:完整系统、单应用、AppForm、视图、报表、门户、关联资源、流程、发布校验;表单字段、分组、布局和应用设置统一使用 versioned AppForm;按钮随视图 action_buttons 声明;更新动作并入对应资源文档,批量读/批量写/局部改依各资源契约执行;视图 apply 每次仅处理一个视图的一种操作,不支持批量创建或混合操作;明细见「关联文件」表与文末命令索引。
9
6
  ---
10
7
 
11
8
  # Qingflow CLI 使用技能
@@ -16,43 +13,7 @@ description: |
16
13
 
17
14
  首次解析 `data query/get` 响应前,阅读 [data 响应结构与解析](./reference/data/README.md#响应结构与解析),按同次响应中的 schema 与记录结构读取目标字段。
18
15
 
19
- ## 关联文件
20
-
21
-
22
- | 文件 | 说明 |
23
- | ------------------------------------------------------------------------------------------------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
24
- | `manifest.yaml` | 技能清单 |
25
- | [reference/00-INDEX.md](./reference/00-INDEX.md) | **总导航**:按用户目标选择 record / task / builder 文档;复杂任务先读 |
26
- | [reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md) | **普通成员**主线:最短路径、`view_id`、与管理命令的差异预期 |
27
- | [reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md) | **字段数据类型**:`record schema …` 的 `fields[]`(`field_id`、`title`、`kind`、`options`…);`record list/get/access` 与写入 payload 的形态对照 |
28
- | [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **普通应用数据读取**:`data query` 获取记录和 schema → 按需 `data get` 读取单条;附件下载见 [data 操作说明](./reference/data/README.md) |
29
- | [reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md) | **任务(待办已办)上下文 SOP**:`task list` → `task get` → `task log` → `task report` → `task action`;只把 `task_id` 作为主定位参数 |
30
- | [reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) | **批量导入 SOP**:`app_get`(**`import_capability`**)→ `record_import_template_get` → `record_import_verify` →(可选)`record_import_repair_local` → `record_import_start` → `record_import_status_get`;CLI `import` / `record schema import` |
31
- | [reference/builder/README.md](./reference/builder/README.md) | **Builder 总导航**:完整系统、单应用、字段、布局、视图、报表、门户、按钮/关联资源、流程、发布校验 |
32
- | [reference/builder/10-build-single-app.md](./reference/builder/10-build-single-app.md) | **单应用搭建主入口**:一个应用端到端交付顺序 |
33
- | [reference/builder/20-build-complete-system.md](./reference/builder/20-build-complete-system.md) | **完整系统/应用包主入口**:多应用、跨应用 relation、门户闭环 |
34
- | [reference/builder/30-schema-fields.md](./reference/builder/30-schema-fields.md) | **字段 / schema**:字段类型、直觉别名、数据标题/封面、schema 创建与更新 |
35
- | [reference/builder/40-layout.md](./reference/builder/40-layout.md) | **布局维护**:仅用于已有应用的分组、`rows` 矩阵、布局修复;新建应用布局写在 `form` 内 |
36
- | [reference/builder/50-views.md](./reference/builder/50-views.md) | **视图**:先读 schema,一次写一个视图对象;查询面板和按钮约束见该文 |
37
- | [reference/builder/60-charts.md](./reference/builder/60-charts.md) | **报表 / QingBI**:指标卡、图表、语义聚合、筛选、排序、更新 |
38
- | [reference/builder/70-portal.md](./reference/builder/70-portal.md) | **门户**:标准工作台、业务入口、指标、图表、视图组件、发布 |
39
- | [reference/builder/80-buttons-associated-resources.md](./reference/builder/80-buttons-associated-resources.md) | **关联资源 / 非主链路按钮维护**:关联视图/报表、`match_mappings`、上下文传参;按钮配置看视图文档 `action_buttons`;创建自定义按钮前先 `button get --button-text` 查重复用 |
40
- | [reference/builder/90-workflow.md](./reference/builder/90-workflow.md) | **流程**:WorkflowSpec、`patch_nodes`、角色/成员、流程回读 |
41
- | [reference/builder/99-publish-verify.md](./reference/builder/99-publish-verify.md) | **发布与回读**:`publish verify`、partial/readback 处理、最终汇报口径 |
42
- | [reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | **新建记录**:`record schema insert -> record insert --items-file`;成员/部门/关联优先自然语言输入;细节见 [record/insert](./reference/record/insert/README.md) |
43
- | [reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md) | **更新记录**:主链路是 `record get` → 智能体按 `fields[]` 组 key/value → **`record update`**;`record schema update` 仅用于失败后诊断可写字段/路径 |
44
- | [reference/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md) | **删除记录**:`record list/get` 精确定位 → `record delete --app-key --record-id --view-id system:*`;批量用 `--record-ids-file` |
45
- | [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**:最终统计结论、分析报告、趋势/排名/比例/分布统一走 `data query --all --output csv -> Python/pandas` |
46
- | [reference/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) | **底层交付参考**:历史完整 SOP、权限、系统列和工具细节;不是主入口 |
47
- | [reference/builder/reference/workspace-icons.md](./reference/builder/reference/workspace-icons.md) | **图标参考**:`builder icon catalog`;新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color` |
48
- | [reference/builder/reference/match-rules.md](./reference/builder/reference/match-rules.md) | **统一筛选 / 条件写法**:`filters`、`visible_when`、QingBI 图表筛选、工作流条件、`match_mappings`、`field_mappings` 的 `operator/value` 规则 |
49
- | [reference/builder/workflow/README.md](./reference/builder/workflow/README.md) | **工作流搭建**:已有应用的流程建模、节点配置、`builder flow apply` 与 `patch_nodes` |
50
- | [reference/builder/code-integrations/README.md](./reference/builder/code-integrations/README.md) | **代码块 / Q-Linker 配置**:字段别名、绑定、输入字段插入和配置排障 |
51
- | [reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md) | **管理员**:检索、导入等与成员差异(主技能正文不展开) |
52
- | [reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md) | CLI 实测与 argparse/服务端对齐备忘 |
53
- | [reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md) | **可选**:全角色「一次可复制」分项模板;默认执行技能**不必**打开 |
54
- | [scripts/find-app-by-keyword.py](./scripts/find-app-by-keyword.py) | **旧版 CLI 兼容脚本**:当 `app list --query` 不可用时,用 `app list` 本地解析;默认优先使用 `qingflow --json app list --query <关键词>` |
55
- | [scripts/builder-package-from-app-list.py](./scripts/builder-package-from-app-list.py) | **旧版 CLI 兼容脚本**:当 `builder package list` 不可用时,才从 `app list` 曲线反查 **`package_name` / `resolve-id`**;新版默认直接用 `qingflow --json builder package list --query <关键词>` |
16
+ 需要向用户交付业务页面入口时,遵循 [Qingflow Common](../qingflow-common/SKILL.md) 的链接规则。
56
17
 
57
18
  ## 工具使用指引
58
19
 
@@ -112,70 +73,6 @@ echo "$QINGFLOW_CREDENTIAL" | qingflow --profile default auth use-credential \
112
73
  qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
113
74
  ```
114
75
 
115
- 常用参数:`--credential-stdin`、`--password-stdin`、`--persist` / `--forget-persisted`;详见 `qingflow auth --help`。
116
-
117
- ---
118
-
119
- ## 输出落盘规则(task / record / import / builder 查询类)
120
-
121
- 以下 **必须** 将标准输出重定向到文件(如 `tmp/qingflow_*.json`),**禁止**把终端大 JSON 直接交给 LLM;后续用读文件 / 脚本处理。
122
-
123
-
124
- | 子系统 | 必须落盘的子命令 |
125
- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
126
- | **task** | `list`、`get`、`log`、`report` |
127
- | **import** | `template`、`verify`、`repair`、`start`、`status`(**`verify` / `start` 链依赖本机 `~/.qingflow-mcp` 校验/任务落盘,自动化须开放写权限**) |
128
- | **builder** | **`app get`(summary/app map、fields、layout、views、flow、charts;summary 含 `custom_buttons` / `associated_resources`)**、`contract`、`app-form schema/get/validate/apply`;以及 **`views schema/get/validate/apply` / `button apply` / `associated-resource apply` / `flow apply` / `charts apply` / `portal apply` / `portal delete` / `publish verify` / `package apply`** 等大 JSON 响应 |
129
- | **record** | `list`、`get`、`logs`、`access`、`schema browse`;以及 `schema insert` / `schema update` / `schema import` / `schema code-block` 等大体积 schema 子命令(体量大时同上);**创建前列字段时用 `schema insert` / `record_insert_schema_get` 同上**;**写操作 `insert` / `update` 响应体大时同样建议落盘** |
130
-
131
-
132
- **规则摘要**
133
-
134
- - 重定向示例:`qingflow --json record list … > tmp/qingflow_records.json`
135
- - 线上真实测试、子智能体并行任务、批量 `--*-file` 入参优先使用**绝对路径**,或在命令前固定确认 `pwd`;不要假设子智能体当前目录与主线程一致。
136
- - `auth`、`workspace`、`app`、`portal`、`view`、**非上述列出的**等,可直接终端查看或按需落盘。
137
- - 错误在使用 **`--json`** 时多在 **stdout** 的 JSON 信封里;stderr 多为 argparse usage。
138
-
139
- ---
140
-
141
- ## 应用数据:查询与读取(默认路径)
142
-
143
- 已知 `app_key` 时直接执行 `qingflow --json data query --app-key <APP_KEY>`;首次查询保留默认 schema,根据响应中的 `field_capabilities` 和 `hints` 决定筛选、分页或停止。定位到 `record_id` 后,按需执行 `qingflow --json data get --app-key <APP_KEY> --record-id <RECORD_ID>`;下载附件时加 `--download-attachments`。
144
-
145
- 参数与附件处理见 [data 操作说明](./reference/data/README.md)。详情页引用、关联资源和完整日志见 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md);最终统计结论按 [数据分析说明](./reference/record/analysis/README.md) 使用 `data query --all --output csv`。
146
-
147
- ---
148
-
149
- ## 应用记录:创建记录工作流(申请节点 → 写入)
150
-
151
- 推荐顺序:
152
-
153
- 1. **`record schema insert`**:先读取 insert-ready schema、`required_fields`、`payload_template`、`format_hint`、`example_value`、联动与运行时必填提示。
154
- 2. **`record insert --items-file`**:单条也是 `items` 数组的一行;成员、部门、关联字段优先写自然语言(如 `"张三"`、`"直销部"`、`"海军军医大学"`),仅在返回 `needs_confirmation` 时再让用户确认候选。
155
- 3. **写后读回**:单条重要数据用 `record get`,批量样本用 `record list` 或业务视图校验;`partial_success` 只重试失败行,不重放全批。
156
-
157
- **细则、字段 JSON 结构与排障**见 **[reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**。
158
-
159
- ---
160
-
161
- ## 应用记录:更新记录工作流(详情 → 写入)
162
-
163
- 主链路是先读详情,再直接提交用户要求修改的 key/value。不要把 `record schema update` 当成更新前置步骤:
164
-
165
- 1. **`record get`** → 拿 **`record_id`、当前值、fields[].title / field_id / kind**;已知前端/自定义视图时必须带同一个 **`--view-id`**。未知时 CLI 会先试默认 `system:all`,权限拒绝后再尝试可访问视图,但智能体仍优先从 `app get.accessible_views` 取 view。
166
- 2. 智能体根据 `record get.fields[]` 和用户要求,组一个只包含待改字段的 JSON 对象(标题 → 值)。字段必须来自当前详情上下文的 `fields[]`;带 `--view-id` 时,视图隐藏的字段不要强写。若用户要求改的字段不在当前 `record get.fields[]`,先换到包含该字段的视图/详情上下文,或用 `record schema update` 做失败诊断。
167
- 3. **`record update`** → **`--record-id` + `--fields-file`**,已知前端视图时同样带 **`--view-id`** 让 CLI 优先走该 view;批量用 **`--items-file`**(**`--dry-run` 仅批量**)。
168
- 4. 只有字段范围不清、候选歧义、或 `record update` 失败时,才用 **`record schema update`** 诊断本条记录的 **`writable_fields / payload_template / available_update_routes`**;已知前端视图时同样带 **`--view-id`**,让诊断优先探测同一个详情页上下文。
169
-
170
- **更新路径**:`record update` 会自动先尝试数据管理员直改,再 fallback 到前端同源的 custom view 详情编辑路径;如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑,最后会尝试 workflow save-only。成功时只需要读 **`status / update_route / verification_status`**;失败时再读失败原因与路线诊断。不要把中间 route 或辅助 schema/readback 探测的 40002 / 40027 / 404 当作最终失败。
171
-
172
- **大号 `record_id`(常见于 Snowflake 类 id)**:若干 CLI 版本在 **`record update` 写入路径**上对 `apply_id` 会做 **JavaScript 安全整数**相关校验,`list`/`get`/`schema update` 仍可能正常而 **更新落库报错**(常为 `apply_id must be positive`)。排障见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。业务统计与最终结论仍必须按 **[record/analysis](./reference/record/analysis/README.md)** 使用 `data query --all --output csv -> Python/pandas`。
173
-
174
- **命令模板、批量 `items` 形态、与新建相同的写入值约定**(按 **`kind`** 分题型见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**)见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
175
-
176
- **成员 / 部门候选排障**:若成员、部门字段返回 `needs_confirmation` 或候选不清,使用 `qingflow record member-candidates` / `qingflow record department-candidates`;它们优先走表单字段候选范围接口(与前端选择器一致)。不要改用通讯录管理类查询去“补候选”,那会把普通成员误带到 ContactAuth 管理权限链路。
177
-
178
- **部门名筛选 / 写入**:`record list/access/analyze/insert/update` 遇到部门字段时可直接传部门名或候选对象;CLI 会优先走成员可见的目录搜索解析部门。不要先用通讯录管理接口查询部门 id,否则普通成员容易被 ContactAuth 错误阻挡。
179
76
  ### 字段筛选
180
77
 
181
78
  先运行一次不带 `columns` 的 query,从返回的 `schema` 与递归 `field_capabilities` 准确定位 `field_id`,并确认该字段暴露的 `filter_operators` 与 `value_shape`。再写筛选文件:
@@ -63,7 +63,7 @@ Before `portal apply`, verify this short list:
63
63
  | Standard heights | Metric cards `rows=5`; BI charts `rows=7`; data views `rows=11`. Do not mix different heights in one row. |
64
64
  | Standard order | Business entry -> metrics -> BI charts -> data views. Do not put data views before metrics/charts in a dashboard-style portal. |
65
65
  | Default/system views | Do not use `全部数据` / `我的数据` as the main business portal views. Use concrete business views. |
66
- | Filter component | `config.rules` must contain at least one rule group (empty-rules filters are written but invisible in readback; blocked at validation). Item keys are backend persistence keys: filterGroupName/filterGroupConfig/filterItemName/dftJudgeType/dftJudgeValue/filterCondition — never `que`/`judge` (silently dropped, blocked at validation), see §3.4. |
66
+ | Filter component | `config.rules` must contain at least one rule group (empty-rules filters are written but invisible in readback; blocked at validation). Rule keys: filterGroupName/filterGroupConfig/filterItemName/que/judge, see §3.4. |
67
67
  | Readback | After apply, run `portal get` and compare section count, refs, and positions before claiming frontend visibility. |
68
68
 
69
69
  Inline QingBI chart creation uses one chart job per section and runs with an internal concurrency limit of 10. If two sections declare the same `app_key + name + chart_type` with identical config, CLI creates/updates once and reuses the chart id. If their config differs, CLI rejects the portal write as a duplicate inline chart conflict.
@@ -293,38 +293,19 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或 **`chart_re
293
293
 
294
294
  ### 3.4 **`filter`**:声明式筛选条(支持,**rules 必须非空**)
295
295
 
296
- 声明形态:**`config.rules`**(筛选规则组,至少 1 组)编译为后端 `ComponentFilter.filterConfig`;可选 **`config.graphs`** 一般省略——后端按 `filterCondition` 聚合派生 `graphList`。规则键集为**后端持久化键受控透传**:组键 `filterGroupName`(组名)/`filterGroupConfig`(筛选项列表);**筛选项键必须是后端持久化键**:`filterItemName` + `dftJudgeType` + `dftJudgeValue` + `filterCondition[]`;代理键 `filterGroupId`/`filterItemId` 为后端自增位移键,声明里不要携带。
297
-
298
- **不要写 `que{queId}`/`judge{judgeType,judgeValues}` 声明键**(历史文档形态):后端写链的 `FilterGroupConfig` DTO 不识别这两个键,写入即被**静默丢弃**——落库只剩 `filterItemName`,回读表现为每项 `dftJudgeType: null、filterCondition: []`,前端筛选条件渲染为**空**(实测:apply 成功、回读组件存在但绑定全丢)。该形态现已被模型层阻断(apply/validate 共同路径显式报错)。
299
-
300
- 字段绑定写在 `filterCondition[]`:每个条目把筛选项绑定到一张目标图表(`graphType: "CHART"`)或视图(`graphType: "VIEW"`),作用于 N 张图表就写 N 条:
296
+ 声明形态:**`config.graphs`**(受筛选作用的图表引用)+ **`config.rules`**(筛选规则组,至少 1 组),编译为后端 `ComponentFilter`(`graphList` + `filterConfig`)。规则键集:`filterGroupName`(组名)/`filterGroupConfig`(筛选项:`filterItemName` + `que{queId}` + `judge{judgeType,judgeValues}`);代理键 `filterGroupId`/`filterItemId` 为后端自增位移键,声明里不要携带。
301
297
 
302
298
  ```json
303
299
  {
304
300
  "source_type": "filter",
305
- "position": {"pc": {"x": 0, "y": 0, "cols": 24, "rows": 3}, "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 3}},
301
+ "position": {"pc": {"x": 0, "y": 0, "cols": 24, "rows": 3}},
306
302
  "config": {
303
+ "graphs": [{"chart_key": "CHART_KEY_1001"}],
307
304
  "rules": [
308
305
  {
309
306
  "filterGroupName": "区域",
310
307
  "filterGroupConfig": [
311
- {
312
- "filterItemName": "城市",
313
- "dftJudgeType": 2,
314
- "dftJudgeValue": [],
315
- "filterCondition": [
316
- {
317
- "queId": 123456,
318
- "queType": 2,
319
- "queTitle": "城市",
320
- "queOriginType": 2,
321
- "chartKey": "CHART_KEY_1001",
322
- "biFieldId": "APP_KEY_1:123456",
323
- "chartName": "故障类型分布",
324
- "graphType": "CHART"
325
- }
326
- ]
327
- }
308
+ {"filterItemName": "城市", "que": {"queId": 123456}, "judge": {"judgeType": 3, "judgeValues": ["上海"]}}
328
309
  ]
329
310
  }
330
311
  ]
@@ -332,27 +313,7 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或 **`chart_re
332
313
  }
333
314
  ```
334
315
 
335
- `filterCondition[]` 条目键(后端持久化键,实测落库形态):
336
-
337
- | 键 | 来源 |
338
- |----|------|
339
- | `queId` | 目标应用字段 queId(`builder app get --app-key … fields`) |
340
- | `queType` | 字段类型编码:text=2、long_text=3、date/datetime=4、member=5、email=6、phone=7、number/amount=8、boolean=10、single_select=11、multi_select=12、attachment=13、subtable=18、q_linker=20、address=21、department=22、relation=25、code_block=26 |
341
- | `queTitle` | 字段显示名 |
342
- | `queOriginType` | 一般同 `queType` |
343
- | `chartKey` | 目标图表 key(门户回读 `chart_ref.chart_id` / QingBI 图表 id);绑定视图时为视图 `viewgraph_key` |
344
- | `biFieldId` | `"<app_key>:<queId>"` |
345
- | `chartName` | 目标图表显示名 |
346
- | `graphType` | `CHART`(图表)/`VIEW`(视图) |
347
-
348
- 要点:
349
-
350
- - `dftJudgeType: 2` 是「包含」(文本筛选项实测可用);`dftJudgeValue` 是默认筛选值,不希望预过滤就写 `[]`。
351
- - 同一筛选项绑定多应用图表时,按各应用真实字段分别写条件条目;字段必须真实存在于目标图表所属应用,否则绑定不生效。
352
- - 回读校验必须核对**每项 `filterCondition` 非空、`dftJudgeType` 有值**——只核对组件存在/组名存在会漏检绑定丢失(实测教训)。
353
- - 回读的 `graphs` 可能按 filterCondition 条数展开重复——是派生数据,不是真实重复。
354
-
355
- **关键边界(旧实测记录的真相)**:`rules` 为空的 filter **会被模型层直接拒绝**——后端读面按筛选组(dash_filter_group 行)反查筛选组件,空规则的组件行虽写入但读面枚举不到,表现为「apply 成功、回读缺 type:6」。历史上「filter 不落库」的实测记录(命令式 raw 直传时代、全部空规则组合)即此机制,不是后端拒绝 type:6。存量筛选组件合法无标题(提取产物不带 `title`,不要合成);round-trip 重放已验证(ws40013 基准 337 个 filter 组件一致率 100%——该基准验证的是后端键回读→重放路径,从未覆盖 que/judge 首写路径,后者实测被后端静默丢弃)。专项 Schema:`qingflow --json builder portal schema --schema-kind filter`。
316
+ **关键边界(旧实测记录的真相)**:`rules` 为空的 filter **会被模型层直接拒绝**——后端读面按筛选组(dash_filter_group 行)反查筛选组件,空规则的组件行虽写入但读面枚举不到,表现为「apply 成功、回读缺 type:6」。历史上「filter 不落库」的实测记录(命令式 raw 直传时代、全部空规则组合)即此机制,不是后端拒绝 type:6。存量筛选组件合法无标题(提取产物不带 `title`,不要合成);round-trip 重放已验证(ws40013 基准 337 个 filter 组件一致率 100%)。专项 Schema:`qingflow --json builder portal schema --schema-kind filter`。
356
317
 
357
318
  ### 3.5 **`grid` / `text` / `link` / `view`**
358
319
 
@@ -430,7 +391,6 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
430
391
  |------|------|
431
392
  | `portal apply accepts exactly one selector mode` | **`dash-key`** vs **`package-id`** 二选一。 |
432
393
  | `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件;`filter` 回读缺失多为 **空 rules**(模型层已阻断,检查报错)或 **异步回读**(可再 **`get`** 一次);含规则的 filter 写入正常(见 **§3.4**)。 |
433
- | **前端筛选条件为空 / 回读筛选项只剩 `filterItemName`** | 筛选项缺 `filterCondition[]` 绑定,或误用了 `que`/`judge` 声明键(模型层已阻断)。按 **§3.4** 用后端持久化键(`filterItemName` + `dftJudgeType` + `dftJudgeValue` + `filterCondition[]`)重建,并回读核对 `filterCondition` 非空。 |
434
394
  | **`published: true` 但 `verified: false`** | 读 **§7**;用 **`get` 草稿+线上**对照。 |
435
395
  | **503** | 网关/运维;稍后重试。 |
436
396
  | 缺 **chart** | 在对应 portal section 写 **`chart`**;或换用已有报表的 **`chart: {"chart_id": "..."}`** / 兼容旧 **`chart_ref`**。 |
@@ -17,30 +17,13 @@
17
17
  }
18
18
  },
19
19
  "config": {
20
- "rules": [
20
+ "graphs": [
21
21
  {
22
- "filterGroupName": "区域",
23
- "filterGroupConfig": [
24
- {
25
- "filterItemName": "城市",
26
- "dftJudgeType": 2,
27
- "dftJudgeValue": [],
28
- "filterCondition": [
29
- {
30
- "queId": 123456,
31
- "queType": 2,
32
- "queTitle": "城市",
33
- "queOriginType": 2,
34
- "chartKey": "REPLACE_WITH_QINGBI_CHART_ID",
35
- "biFieldId": "REPLACE_WITH_APP_KEY:123456",
36
- "chartName": "REPLACE_WITH_CHART_NAME",
37
- "graphType": "CHART"
38
- }
39
- ]
40
- }
41
- ]
22
+ "chart_key": "REPLACE_WITH_QINGBI_CHART_ID",
23
+ "chart_name": "可选_图表显示名"
42
24
  }
43
- ]
25
+ ],
26
+ "rules": []
44
27
  }
45
28
  },
46
29
  {
@@ -2736,22 +2736,6 @@ class PortalSectionPatch(StrictModel):
2736
2736
  "filter section requires config.rules with at least one rule group; "
2737
2737
  "an empty-rules filter is written but invisible in portal get readback"
2738
2738
  )
2739
- # 筛选项的后端持久化键是 dftJudgeType/dftJudgeValue/filterCondition;历史
2740
- # 文档的声明键 que/judge 不被后端 FilterGroupConfig DTO 识别,静默丢弃后
2741
- # 落库只剩 filterItemName——前端筛选条件渲染为空(实测首建全空真身)。
2742
- # 同在模型咽喉阻断,把静默丢键变成显式报错。
2743
- for group in rule_groups:
2744
- if not isinstance(group, dict):
2745
- continue
2746
- for item in group.get("filterGroupConfig") or []:
2747
- if isinstance(item, dict) and ("que" in item or "judge" in item):
2748
- raise ValueError(
2749
- "filter rule items must use backend persistence keys "
2750
- "(filterItemName/dftJudgeType/dftJudgeValue/filterCondition); "
2751
- "the declaration keys 'que'/'judge' are silently dropped by the "
2752
- "backend and leave the frontend filter condition empty "
2753
- "(see 70-portal.md section 3.4)"
2754
- )
2755
2739
  return self
2756
2740
 
2757
2741
 
@@ -944,7 +944,7 @@
944
944
  "FilterConfig": {
945
945
  "type": "object",
946
946
  "additionalProperties": false,
947
- "filterConfigShapeDescription": "筛选组件配置(受控键集)。graphs 为受影响的图表引用(可省略,后端按 filterCondition 派生);rules 为筛选规则组,项键为后端持久化键 filterGroupName/filterGroupConfig/filterItemName/dftJudgeType/dftJudgeValue/filterCondition 系(受控透传;代理键 filterGroupId/filterItemId 剔除;声明键 que/judge 会被后端静默丢弃致筛选条件为空,模型层已阻断)。rules 必须至少 1 组——后端读面按筛选组反查筛选组件,空规则的 filter 写入后读面不可见(模型层已阻断)。",
947
+ "filterConfigShapeDescription": "筛选组件配置(受控键集)。graphs 为受影响的图表引用;rules 为筛选规则组,键集 filterGroupName/filterGroupConfig/filterItemName/que/judge 系(受控透传,dataset 实测形态定稿;代理键 filterGroupId/filterItemId 剔除)。rules 必须至少 1 组——后端读面按筛选组反查筛选组件,空规则的 filter 写入后读面不可见(模型层已阻断)。",
948
948
  "properties": {
949
949
  "graphs": {
950
950
  "type": "array",
@@ -965,7 +965,7 @@
965
965
  },
966
966
  "rules": {
967
967
  "type": "array",
968
- "filterRulesDescription": "筛选规则组(至少 1 组;空规则组件读面不可见)。组键 filterGroupName(必填)/filterGroupConfig(筛选项后端持久化键:filterItemName/dftJudgeType/dftJudgeValue/filterCondition[],详见专项 Schema --schema-kind filter)。",
968
+ "filterRulesDescription": "筛选规则组(至少 1 组;空规则组件读面不可见)。组键 filterGroupName(必填)/filterGroupConfig(筛选项:filterItemName/que{queId}/judge{judgeType,judgeValues})。",
969
969
  "x-backend": "ComponentFilter.filterConfig(List<FilterConfig>)"
970
970
  }
971
971
  }
@@ -59,11 +59,11 @@
59
59
  "required": [
60
60
  "rules"
61
61
  ],
62
- "filterConfigShapeDescription": "筛选组件配置。rules 必须非空——后端读面(DashSvcImpl#getComponentFilter)按筛选组(dash_filter_group 行)反查筛选组件,空规则的 filter 组件行虽会写入但读面枚举不到,表现为「apply 成功、回读缺该组件」。规则键集为后端持久化键受控透传(filterGroupName/filterGroupConfig/filterItemName/dftJudgeType/dftJudgeValue/filterCondition 系);声明键 que/judge 会被后端写链静默丢弃(落库只剩 filterItemName,前端筛选条件为空),模型层已阻断。",
62
+ "filterConfigShapeDescription": "筛选组件配置。rules 必须非空——后端读面(DashSvcImpl#getComponentFilter)按筛选组(dash_filter_group 行)反查筛选组件,空规则的 filter 组件行虽会写入但读面枚举不到,表现为「apply 成功、回读缺该组件」;规则键集为受控透传(filterGroupName/filterGroupConfig/filterItemName/que/judge 系,以 ws40013 dataset 实测形态定稿)。",
63
63
  "properties": {
64
64
  "graphs": {
65
65
  "type": "array",
66
- "filterGraphsShapeDescription": "受筛选作用的图表引用(可省略:后端按 filterCondition 聚合派生 graphList,回读的 graphs 可能按绑定条数展开,非真实重复)。",
66
+ "filterGraphsShapeDescription": "筛选作用的图表引用(为空表示作用于全部图表)。",
67
67
  "items": {
68
68
  "$ref": "#/$defs/FilterGraphRef"
69
69
  },
@@ -72,7 +72,7 @@
72
72
  "rules": {
73
73
  "type": "array",
74
74
  "minItems": 1,
75
- "filterRulesShapeDescription": "筛选规则组(至少 1 组)。组键:filterGroupName(组名,必填)、filterGroupConfig(组内筛选项列表);项键为后端持久化键:filterItemName、dftJudgeType、dftJudgeValue、filterCondition[](字段绑定)。代理键 filterGroupId/filterItemId 为后端自增位移键,读写两侧均剔除,不要携带;声明键 que/judge 会被后端静默丢弃,模型层已阻断。",
75
+ "filterRulesShapeDescription": "筛选规则组(至少 1 组)。组键:filterGroupName(组名,必填)、filterGroupConfig(组内筛选项列表);项键:filterItemName、que{queId}(绑定字段)、judge{judgeType,judgeValues}(默认条件)。代理键 filterGroupId/filterItemId 为后端自增位移键,读写两侧均剔除,不要携带。",
76
76
  "items": {
77
77
  "$ref": "#/$defs/FilterRuleGroup"
78
78
  },
@@ -136,97 +136,22 @@
136
136
  "required": [
137
137
  "filterItemName"
138
138
  ],
139
- "filterRuleItemShapeDescription": "单个筛选项,必须用后端持久化键:filterItemName + dftJudgeType/dftJudgeValue(默认条件) + filterCondition[](字段绑定,每条绑定一张目标图表/视图)。历史文档的声明键 que{queId}/judge{judgeType,judgeValues} 不被后端 FilterGroupConfig DTO 识别,写入即被静默丢弃——落库只剩 filterItemName,前端筛选条件渲染为空;模型层已阻断,不要携带。",
139
+ "filterRuleItemShapeDescription": "单个筛选项(绑定一个字段)。que/judge 为后端受控透传形态;条件表达式(关联图表/字段)键集以 dataset 实测形态为准。",
140
140
  "properties": {
141
141
  "filterItemName": {
142
142
  "type": "string",
143
143
  "filterRuleItemNameShapeDescription": "筛选项名称。",
144
144
  "x-backend": "FilterGroupConfig.filterItemName"
145
145
  },
146
- "dftJudgeType": {
147
- "type": [
148
- "integer",
149
- "null"
150
- ],
151
- "dftJudgeTypeShapeDescription": "默认判断符;2=包含(文本筛选项实测可用)。",
152
- "x-backend": "FilterGroupConfig.dftJudgeType"
153
- },
154
- "dftJudgeValue": {
155
- "type": "array",
156
- "dftJudgeValueShapeDescription": "默认筛选值列表;不希望预过滤写 []。",
157
- "x-backend": "FilterGroupConfig.dftJudgeValue"
158
- },
159
- "filterCondition": {
160
- "type": "array",
161
- "filterConditionListShapeDescription": "字段绑定列表:每个条目把筛选项绑定到一张目标图表(graphType=CHART)或视图(graphType=VIEW);作用于 N 张图表就写 N 条。",
162
- "items": {
163
- "$ref": "#/$defs/FilterCondition"
164
- },
165
- "x-backend": "FilterGroupConfig.filterCondition"
166
- },
167
- "filterType": {
168
- "type": [
169
- "string",
170
- "integer",
171
- "null"
172
- ],
173
- "filterTypeShapeDescription": "筛选展示类型(后端键,可空;缺省 null 实测可正常落库)。",
174
- "x-backend": "FilterGroupConfig.filterType"
175
- }
176
- }
177
- },
178
- "FilterCondition": {
179
- "type": "object",
180
- "required": [
181
- "queId",
182
- "chartKey"
183
- ],
184
- "filterConditionShapeDescription": "筛选项与一张目标图表/视图的字段绑定(后端持久化键,实测落库形态)。",
185
- "properties": {
186
- "queId": {
187
- "type": "integer",
188
- "conditionQueIdShapeDescription": "目标应用字段 queId(builder app get fields 读取)。",
189
- "x-backend": "FilterCondition.queId"
190
- },
191
- "queType": {
192
- "type": "integer",
193
- "conditionQueTypeShapeDescription": "字段类型编码:text=2、long_text=3、date/datetime=4、member=5、email=6、phone=7、number/amount=8、boolean=10、single_select=11、multi_select=12、attachment=13、subtable=18、q_linker=20、address=21、department=22、relation=25、code_block=26。",
194
- "x-backend": "FilterCondition.queType"
195
- },
196
- "queTitle": {
197
- "type": "string",
198
- "conditionQueTitleShapeDescription": "字段显示名。",
199
- "x-backend": "FilterCondition.queTitle"
200
- },
201
- "queOriginType": {
202
- "type": "integer",
203
- "conditionQueOriginTypeShapeDescription": "来源字段类型,一般同 queType。",
204
- "x-backend": "FilterCondition.queOriginType"
205
- },
206
- "chartKey": {
207
- "type": "string",
208
- "conditionChartKeyShapeDescription": "目标图表 key(门户回读 chart_ref.chart_id / QingBI 图表 bi id);绑定视图时为视图 viewgraph_key。",
209
- "x-backend": "FilterCondition.chartKey"
210
- },
211
- "biFieldId": {
212
- "type": "string",
213
- "conditionBiFieldIdShapeDescription": "BI 字段 ID,格式 \"<app_key>:<queId>\"。",
214
- "x-backend": "FilterCondition.biFieldId"
215
- },
216
- "chartName": {
217
- "type": "string",
218
- "conditionChartNameShapeDescription": "目标图表显示名。",
219
- "x-backend": "FilterCondition.chartName"
220
- },
221
- "graphType": {
222
- "type": "string",
223
- "conditionGraphTypeShapeDescription": "绑定目标类型:CHART(图表)/VIEW(视图)。",
224
- "x-backend": "FilterCondition.graphType"
146
+ "que": {
147
+ "type": "object",
148
+ "filterRuleItemQueShapeDescription": "绑定的字段引用(queId 为字段唯一键)。",
149
+ "x-backend": "FilterGroupConfig.que(Question)"
225
150
  },
226
- "dateType": {
227
- "type": "integer",
228
- "conditionDateTypeShapeDescription": "date/datetime 字段补充键(date=0/datetime=1)。",
229
- "x-backend": "FilterCondition.dateType"
151
+ "judge": {
152
+ "type": "object",
153
+ "filterRuleItemJudgeShapeDescription": "默认筛选条件:judgeType(比较符)+judgeValues(比较值列表)。",
154
+ "x-backend": "FilterGroupConfig.dftJudgeType/dftJudgeValue"
230
155
  }
231
156
  }
232
157
  },
@@ -291,36 +216,29 @@
291
216
  }
292
217
  },
293
218
  "config": {
219
+ "graphs": [
220
+ {
221
+ "chart_key": "CHART_KEY_1001"
222
+ },
223
+ {
224
+ "chart_name": "故障类型分布"
225
+ }
226
+ ],
294
227
  "rules": [
295
228
  {
296
229
  "filterGroupName": "区域",
297
230
  "filterGroupConfig": [
298
231
  {
299
232
  "filterItemName": "城市",
300
- "dftJudgeType": 2,
301
- "dftJudgeValue": [],
302
- "filterCondition": [
303
- {
304
- "queId": 123456,
305
- "queType": 2,
306
- "queTitle": "城市",
307
- "queOriginType": 2,
308
- "chartKey": "CHART_KEY_1001",
309
- "biFieldId": "APP_KEY_1:123456",
310
- "chartName": "故障类型分布",
311
- "graphType": "CHART"
312
- },
313
- {
314
- "queId": 123456,
315
- "queType": 2,
316
- "queTitle": "城市",
317
- "queOriginType": 2,
318
- "chartKey": "CHART_KEY_1002",
319
- "biFieldId": "APP_KEY_1:123456",
320
- "chartName": "区域销量分布",
321
- "graphType": "CHART"
322
- }
323
- ]
233
+ "que": {
234
+ "queId": 123456
235
+ },
236
+ "judge": {
237
+ "judgeType": 3,
238
+ "judgeValues": [
239
+ "上海"
240
+ ]
241
+ }
324
242
  }
325
243
  ]
326
244
  }
@@ -31194,14 +31194,6 @@ def _build_view_update_payload(
31194
31194
  payload["viewgraphType"] = "calendarView"
31195
31195
  payload["beingShowTitleQue"] = True
31196
31196
  payload.pop("groupQueId", None)
31197
- elif normalized_type == "hierarchy":
31198
- payload["viewgraphType"] = "hierarchyView"
31199
- payload["beingShowTitleQue"] = True
31200
- payload.pop("groupQueId", None)
31201
- elif normalized_type == "calendar":
31202
- payload["viewgraphType"] = "calendarView"
31203
- payload["beingShowTitleQue"] = True
31204
- payload.pop("groupQueId", None)
31205
31197
  return _hydrate_view_backend_payload(
31206
31198
  payload=payload,
31207
31199
  view_type=normalized_type,
@@ -51,9 +51,8 @@ COMMON_ERROR_DROP_TOP = {
51
51
 
52
52
  SUCCESS_POLICY_BY_TOOL: dict[str, TransformFn] = {}
53
53
 
54
- #: 这些校验命令的产出契约明确包含 ok 字段(供阶段 2 SKILL.md 引用),
54
+ #: 这两个校验命令的产出契约明确包含 ok 字段(供阶段 2 SKILL.md 引用),
55
55
  #: 需在 success 裁剪时保留 ok(默认 COMMON_SUCCESS_DROP_TOP 会丢弃 ok)。
56
- #: `builder:app_views_validate`(views 声明式校验)同属校验类工具,ok 同样进产出契约。
57
56
  _KEEP_OK_TOOLS = {
58
57
  "builder:app_form_validate_formula",
59
58
  "builder:app_form_validate_code_block",