@qingflow-tech/qingflow-cli 1.0.42 → 1.0.44

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
@@ -3,13 +3,13 @@
3
3
  Install:
4
4
 
5
5
  ```bash
6
- npm install @qingflow-tech/qingflow-cli@1.0.42
6
+ npm install @qingflow-tech/qingflow-cli@1.0.44
7
7
  ```
8
8
 
9
9
  Run:
10
10
 
11
11
  ```bash
12
- npx -y -p @qingflow-tech/qingflow-cli@1.0.42 qingflow
12
+ npx -y -p @qingflow-tech/qingflow-cli@1.0.44 qingflow
13
13
  ```
14
14
 
15
15
  Environment:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qingflow-tech/qingflow-cli",
3
- "version": "1.0.42",
3
+ "version": "1.0.44",
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.0.42"
7
+ version = "1.0.44"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -8,7 +8,7 @@ description: |
8
8
 
9
9
  # Qingflow CLI 使用技能
10
10
 
11
- > **Skill 版本**:`qingflow-skills-2026.06.23.1`(入口文档版本;如需确认 CLI 包版本,使用 `qingflow --version` 或 `qingflow --json version`)。
11
+ > **Skill 版本**:`qingflow-skills-2026.06.24.2`(入口文档版本;CLI 包版本用 `qingflow --version`;需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`)。
12
12
 
13
13
  **硬约束(必读)**:正文各节与文末「命令速查」中的命令**只作子命令形态索引**,不覆盖 JSON 结构、`--*-file` 键名、枚举全集、执行顺序与排障细节。凡工作**偏复杂**(多步串联、大块 payload、导入全链、**Builder 搭建向**(应用/schema/流程/布局/视图/门户/报表/按钮/关联资源的配置与发布、系统列与字段 `type`)、契约型 `apply`、按 schema 组织写入 payload、任务下钻与 `task action` 等),或你判断当前任务与「关联文件」里某篇所描述的内容**需求一致、场景相同或大体同类**,都应**先 Read 对应 `reference/*.md`**,再结合 `qingflow … --help` 与 **[EXPLORATION_REPORT](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。**禁止**仅凭索引、习惯或类比去补参数、臆造字段名或推断服务端行为。**最终统计结论、分析报告、趋势/排名/比例/分布等数据分析,必须转交 `qingflow-record-analysis`,统一走 `record_access -> Python/pandas`。**
14
14
 
@@ -41,7 +41,13 @@ description: |
41
41
 
42
42
  **Builder 删除回读语义**:删除类 apply 要区分 **DELETE 是否已发出** 和 **删除是否已回读确认**。若结果里有 **`delete_executed=true`**,但 **`readback_status=unavailable|still_exists`**,不要盲目重复删除;记录 **`safe_to_retry_delete=false`**,稍后用对应读取工具确认。
43
43
 
44
- **Builder 写后回读语义**:`package apply/update`、`schema apply`、`portal apply` 以及其它 builder apply 若返回 **`status=partial_success`** 且 **`write_executed=true` / `safe_to_retry=false`**,表示写动作已经发出或已成功,后续回读/发布校验可能被 40002、404、超时或元数据延迟阻挡。此时不要把结果解读为“未写入”;下一步是 **`readback_before_retry`**,只报告 **写入已执行,回读待确认**,并按 `verification.readback_unavailable`、`details.*readback_error`、`summary.write_executed` 做最终说明。完整系统 schema apply 的恢复只允许先读包、解析应用、读字段/关联;禁止未经读回就重放整批、拆成单应用重建、创建 V2/测试/随机后缀应用,或把同批 `target_app_ref` 改成未确认的 `target_app_key`。
44
+ **Builder 写后回读语义**:`package apply/update`、`schema apply`、`portal apply`、`charts apply` 以及其它 builder apply 若返回 **`status=partial_success`** 且 **`write_executed=true` / `safe_to_retry=false`**,表示写动作已经发出或已成功,后续回读/发布校验可能被 40002、404、超时或元数据延迟阻挡。此时不要把结果解读为“未写入”;下一步是 **`readback_before_retry`**,只报告 **写入已执行,回读待确认**,并按 `verification.readback_unavailable`、`details.*readback_error`、`details.suggested_retry_payload`、`summary.write_executed` 做最终说明。完整系统 schema apply 的恢复只允许先读包、解析应用、读字段/关联;禁止未经读回就重放整批、拆成单应用重建、创建 V2/测试/随机后缀应用,或把同批 `target_app_ref` 改成未确认的 `target_app_key`。
45
+
46
+ **Builder contract 读取路径**:`qingflow --json builder contract --tool-name ...` 成功时,真实契约固定在 **`$.contract`**;优先读返回的 **`json_paths`**。`allowed_keys` 是 `$.contract.allowed_keys`,`allowed_values` 是 `$.contract.allowed_values`,且 allowed_values 使用 **扁平 dotted key**,例如 `["field.type"]` / `["chart.chart_type"]`,不是嵌套对象。成功响应顶层 `allowed_values` 通常为空,不要从顶层取字段枚举。`builder icon catalog` 的候选固定读 `$.icon_names` / `$.icon_colors`。
47
+
48
+ **Builder apply 输出读取路径**:`package/schema/views/charts/portal` 等 builder apply 成功或 partial 时,优先读返回的 **`json_paths`**;稳定主路径是 `$.summary` 与 `$.resources[]`。资源 ID/key/name 先看 `$.resources[].id/key/name`;写入状态先看 `$.write_executed`、`$.safe_to_retry`、`$.next_action`,再看 `$.summary.write_executed` / `$.summary.safe_to_retry`。旧字段只作兼容或 debug。
49
+
50
+ **0 字节输出**:写入类命令如果目标文件或捕获 stdout 为 0 bytes,不要按成功或失败二选一猜测;标记为 **`write_state_unknown`**,先做对应读回(如 `builder app get` / `portal get` / `record get` / `record list`)再决定是否重试。只要读回显示资源已创建/更新,就按成功路径汇报;读回证明缺失时才重试最小缺失项。在 CLI repo 或测试 harness 中,可用 `python scripts/validate_qingflow_output_files.py --glob 'tmp/*.json'` 扫描 0 bytes / 非 JSON 输出。
45
51
 
46
52
  ---
47
53
 
@@ -180,6 +180,7 @@ qingflow builder schema apply \
180
180
  - 这个模式只负责应用壳与字段;视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
181
181
  - 同批 `relation` 优先用 `target_app_ref` 指向 `client_key`;`target_app` 只适合名称唯一且稳定的同批应用。不要先分别建应用、再为了补 `target_app_key` 做第二轮字段修补。
182
182
  - relation 字段写入后读 `details.relation_readback_matrix[]`:逐项核对 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。若出现 `mismatch/missing`,按 `details.relation_repair_plan[]` 做最小 `update_fields` 修复;它会写明建议 patch 和 `data_impact`,不要删除重建字段。
183
+ - `RELATION_FIELD_LIMIT_RISK` 是 warning:表示多个 relation 字段已写入/读回但后端能力可能不稳定。只要字段已创建且 readback 未 mismatch,不要降级成文本;只有 `MULTIPLE_RELATION_FIELDS_UNSUPPORTED` / 49614 或 relation readback mismatch 时,才按返回的 `recommended_modeling_fallback` 做部分降级并汇报为 partial。
183
184
  - 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时,先按 §3.4 读回,不要直接拆成单应用创建。
184
185
 
185
186
  ### 3.4 多应用 schema apply 超时 / partial / readback 不完整恢复
@@ -207,7 +208,7 @@ qingflow builder schema apply \
207
208
  - 若 readback 证明主应用已存在但部分 relation 缺失,修 relation 前先说明数据影响:是否会清空已有值、是否需要迁移、是否可安全重试。
208
209
  - 如果已有包内已经存在相似应用,先决定“复用/更新/新建缺失应用/询问用户”,不要用相似重名或后缀绕开。
209
210
 
210
- **`visibility` JSON**(`--visibility-file`):与包/应用通用,键见契约 `allowed_values.visibility.*`:
211
+ **`visibility` JSON**(`--visibility-file`):与包/应用通用,键见契约 `$.contract.allowed_values["visibility.*"]`:
211
212
 
212
213
  - **`mode`**:`workspace` | `everyone` | `specific`(`specific` 须 **`selectors`**:`member_uids` / `member_emails` / `member_names` / `dept_ids` / `dept_names` / `role_ids` / `role_names` / `include_sub_departs`)。
213
214
  - **`external_mode`**:`not` | `workspace` | `specific`,与对外可见性独立;**`mode=everyone`** 时行为见契约 **execution_notes**。
@@ -279,6 +280,12 @@ qingflow builder layout apply \
279
280
 
280
281
  ### 5.3 流程:`builder flow apply`
281
282
 
283
+ 流程前置条件:
284
+
285
+ - 审批 / 填写 / 抄送类流程需要一个显式业务状态字段;推荐在 schema 阶段先建 `select` 字段,例如 `状态`、`处理状态`、`审批状态`、`工单状态` 或 `流程阶段`。
286
+ - 不要创建平台流程系统字段:`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。这些只能由平台维护。
287
+ - 如果返回 `FLOW_DEPENDENCY_MISSING`,先执行返回的 `suggested_next_call` 补业务状态字段,再 `builder app get fields` 回读,然后重跑 flow apply;不要跳过流程后报告“流程完成”。
288
+
282
289
  ```bash
283
290
  qingflow builder flow apply \
284
291
  --app-key "<APP_KEY>" \
@@ -295,7 +302,7 @@ qingflow builder flow apply \
295
302
 
296
303
  ## 6. 字段类型:`app_schema_apply` 怎么写
297
304
 
298
- 以下 **`type`** 取值来自契约 **`allowed_values.field.type`**(与 **`field_type_ids`** 对应:2,3,4,5,6,7,8,10,11,12,13,18,20,21,22,25,26 —— **勿手写 id**,用 **字符串 `type`**)。
305
+ 以下 **`type`** 取值来自契约 **`$.contract.allowed_values["field.type"]`**(与 **`field_type_ids`** 对应:2,3,4,5,6,7,8,10,11,12,13,18,20,21,22,25,26 —— **勿手写 id**,用 **字符串 `type`**)。
299
306
 
300
307
  智能体可优先写更自然的字段类型,工具会在写入前归一化;读回仍显示 canonical 类型:
301
308
 
@@ -309,8 +316,8 @@ qingflow builder flow apply \
309
316
  |--------|----------|
310
317
  | **`text`** | **`name`**;可选 **`required`**、**`description`**;无选项。 |
311
318
  | **`long_text`** | 同上。 |
312
- | **`number`** | 同上。 |
313
- | **`amount`** | 同上;金额语义由后端表单类型承载。 |
319
+ | **`number`** | 同上;比例、完成率、评分、数量、时长、百分比等可能出现小数或非货币数值时优先用它。 |
320
+ | **`amount`** | 同上;只用于货币/金额语义,不要把百分比、完成率、成本执行率等业务比例建成 `amount`。 |
314
321
  | **`date`** | 同上。 |
315
322
  | **`datetime`** | 同上。 |
316
323
  | **`member`** | **`name`**、**`required`**;成员选择器,无额外 scope 键(与 **department** 不同)。 |
@@ -332,7 +339,7 @@ qingflow builder flow apply \
332
339
  - 子表子字段不能作为标题或封面;多标题、多封面、非附件封面都会在写入前阻断。
333
340
  - 未显式标记封面时保留/不创建封面;未能形成唯一标题时视为配置错误,不要声称应用已完整创建。
334
341
 
335
- **别名**:契约 **`aliases`** 会把 `field.title` / `field.label` 等映射到 **`name`**,把 `field.type_id` 映射到 **`type`**;契约 **`allowed_values.field.type_aliases`** 会把自然字段类型映射到内部类型。主路径建议写上表自然类型,排障和读回时看 canonical 类型。
342
+ **别名**:契约 **`aliases`** 会把 `field.title` / `field.label` 等映射到 **`name`**,把 `field.type_id` 映射到 **`type`**;契约 **`$.contract.allowed_values["field.type_aliases"]`** 会把自然字段类型映射到内部类型。主路径建议写上表自然类型,排障和读回时看 canonical 类型。
336
343
 
337
344
  **`update_fields` 项**:**`selector`**:`que_id` 或 `field_id` 或 **`name`**;**`set`**:允许子集(**`name` / `required` / `description` / `options` / `department_scope` / … / `subfield_updates`**)。
338
345
 
@@ -372,7 +379,7 @@ qingflow builder flow apply \
372
379
  ### 7.2 布局 / 流程中的「系统行为」
373
380
 
374
381
  - **布局**:仅摆放 **`app_get_fields`** 里出现的 **`name`**;不要把上表系统列名放进 **`rows`** 除非读回确认存在对应可摆放控件。
375
- - **流程**:**`app_flow_apply` 的 `permissions.editable_fields`** 等须引用 **真实业务字段名**(读 `fields`)。
382
+ - **流程**:**`app_flow_apply` 的 `permissions.editable_fields`** 等须引用 **真实业务字段名**(读 `fields`)。流程需要状态时,创建业务字段 `状态` / `处理状态` 等,不创建平台字段 `当前流程状态`。
376
383
 
377
384
  ---
378
385
 
@@ -32,6 +32,7 @@ qingflow --json builder charts apply \
32
32
  - 四个文件参数均可省略,但 **`ChartApplyRequest`** 要求 **至少一项非空**(**upsert** / **patch** / **remove** / **reorder**),否则校验报错。
33
33
  - 各文件均为 **JSON 数组**(与 `load_list_arg` 一致)。
34
34
  - 大 JSON 必须 **落盘**,见主技能 **builder** 行。
35
+ - 完整系统里一次要创建很多报表时,主路径按应用或主题分批提交,推荐每批 **4-8 个 `upsert_charts`**。超过 8 个时 CLI 会在写入前返回 `CHART_UPSERT_BATCH_TOO_LARGE`,并给出 `details.suggested_batch_payloads[]`;直接逐个执行这些 payload,不要提交原始大数组。
35
36
 
36
37
  ---
37
38
 
@@ -52,7 +53,7 @@ qingflow --json builder charts apply \
52
53
  | 键 | 说明 |
53
54
  |----|------|
54
55
  | **`name`** | 必填;新建时即图表名;**更新**时可改名。 |
55
- | **`chart_type`** | 以 `qingflow --json builder contract --tool-name app_charts_apply` 的 `allowed_values.chart.chart_type` 为准;当前公开面已覆盖 QingBI 常用类型,如 **`target` / `indicator` / `summary` / `pie` / `bar` / `columnar` / `line` / `table` / `detail` / `area` / `stacked_area` / `funnel` / `waterfall` / `gauge` / `heatmap` / `histogram` / `treemap` / `radar` / `stacked_bar` / `stacked_column` / `scatter` / `ring` / `rose` / `dualaxes` / `map`** 等;最终仍以 contract 为准。 |
56
+ | **`chart_type`** | 以 `qingflow --json builder contract --tool-name app_charts_apply` 的 `$.contract.allowed_values["chart.chart_type"]` 为准;当前公开面已覆盖 QingBI 常用类型,如 **`target` / `indicator` / `summary` / `pie` / `bar` / `columnar` / `line` / `table` / `detail` / `area` / `stacked_area` / `funnel` / `waterfall` / `gauge` / `heatmap` / `histogram` / `treemap` / `radar` / `stacked_bar` / `stacked_column` / `scatter` / `ring` / `rose` / `dualaxes` / `map`** 等;最终仍以 contract 为准。 |
56
57
  | **`chart_id`** | 可选。**有则按 id 命中更新**;无则 **按 `name` 精确匹配**:0 个 → **创建**;多个 → **歧义报错**(须带 **`chart_id`**)。 |
57
58
  | **`metric`** / **`metrics`** | **主推语义指标写法**:`"count(*)"`、`"sum(金额)"`、`"avg(工时)"`、`"max(评分)"`、`"min(耗时)"`,也支持对象 `{"op":"sum","field":"金额"}`。字段必须来自 **`chart_fields[]`**。 |
58
59
  | **`group_by`** | **主推维度写法**:字段显示名、`field_id` 或 `bi_field_id` 数组,例如 `["使用状态"]`。 |
@@ -184,13 +185,27 @@ CLI 对外推荐使用 **`group_by` + `metric(s)`**;旧的 **`dimension_field_
184
185
  |------|------|
185
186
  | **`chart_results[]`** | 每项 **`status`**: **`created`** / **`updated`** / **`removed`** / **`failed`**。 |
186
187
  | **`verification.charts_verified`** | 新建/更新/排序通过报表清单回读验证;删除通过单个 **`chart_id`** 回读验证。 |
187
- | **`partial_success` / `CHART_APPLY_PARTIAL`** | 部分 **`upsert/remove`** 失败。 |
188
+ | **`partial_success` / `CHART_APPLY_PARTIAL`** | 部分 **`upsert/remove`** 失败。若同时 `write_executed=true` / `write_may_have_succeeded=true`,先读回报表列表,不要整批重试。 |
188
189
  | **`CHART_READBACK_PENDING`** | 变更已提交但列表读回未完成。 |
189
190
  | **`CHART_DELETE_READBACK_PENDING`** | 删除请求已完成,但单个 **`chart_id`** 回读未确认已删除。 |
191
+ | **`CHART_UPSERT_BATCH_TOO_LARGE`** | 一次 upsert 图表数超过 8;CLI 写前阻断,`write_executed=false`,按 `details.suggested_batch_payloads[]` 分批执行。 |
190
192
  | **`chart_results[].readback_status`** | 删除结果专用:**`deleted`** / **`still_exists`** / **`unavailable`**。只要 **`delete_executed=true`**,**`safe_to_retry_delete=false`**,不要直接重复删除。 |
191
193
 
192
194
  常见问题:**重名**须 **`chart_id`**;**`chart_id` 不存在**;报表字段必须来自 **`app get fields.chart_fields`**,**record schema 可见** 或 **普通表单 fields 可见** 不等于 QingBI 可用;系统字段如 **申请人/申请时间/编号** 只有出现在 **`chart_fields`** 时才可用于报表;字段标题重复时用 **`bi_field_id`** 或 **`field_queId`** 精确指定;**子表等**类型是否可做维度/指标以后端为准。
193
195
 
196
+ `CHART_APPLY_PARTIAL` 恢复规则:
197
+
198
+ - 先看 `details.failed_chart_names`、`details.failed_delete_chart_ids` 和 `details.readback_first`。
199
+ - 若 `details.readback_first=true`,先 `builder app get --app-key <APP_KEY> charts` 或 `chart get` 确认哪些报表已经存在/已更新。
200
+ - 只重试 `details.suggested_retry_payload` 里的失败项;不要重放原始 `upsert_charts` 全量数组。
201
+ - 如果失败项已经在读回中存在但配置未确认,按失败项名称或 `chart_id` 做一次最小 patch。
202
+
203
+ `CHART_UPSERT_BATCH_TOO_LARGE` 处理规则:
204
+
205
+ - 这是写前阻断,不是后端失败;`write_executed=false`,可以安全按建议重试。
206
+ - 直接复制执行 `details.suggested_batch_payloads[]`,每次只跑一个 payload。
207
+ - 不要改报表名称、不要拆成单个图表反复试、不要重放原始大数组。
208
+
194
209
  ---
195
210
 
196
211
  ## 7. 示例文件(可复制)
@@ -123,6 +123,9 @@ CLI 将参数与文件内容拼装为服务层载荷,**顶层键**如下:
123
123
  - `filters`:固定筛选,打开视图即生效。
124
124
  - `query_conditions`:只配置前端查询面板可输入哪些字段;用户输入查询值后才生效。
125
125
  - `rows` 是字段布局矩阵,不表示 OR 条件。
126
+ - `rows` 只放前端查询面板支持的字段:文本、长文本、数字、金额、日期/时间、单选/多选、成员、部门、手机号、邮箱、布尔。
127
+ - 不要把 relation、attachment、subtable/subfield、address、Q-Linker 或 code-block 字段放进 `query_conditions`。
128
+ - 需要固定筛选时用 `filters`;需要关联报表/关联视图按当前记录匹配时用 `builder associated-resource apply` 的 `match_mappings`。
126
129
 
127
130
  示例:
128
131
 
@@ -286,6 +289,7 @@ qingflow builder views apply \
286
289
  | 重名视图 / 删错 | **`app get views`**;更新时带 **`view_key`** |
287
290
  | 过滤器未生效疑虑 | 看响应 **`verification.view_filters_verified`**;必要时再 **`app get views`** |
288
291
  | 查询条件未生效疑虑 | 看响应 **`verification.view_query_conditions_verified`**;不要把 `query_conditions` 当 `filters` |
292
+ | 后端 **40038 / Object not exist** | 先读失败项 **`details.per_view_results[].details.field_level_diagnostics`** 与 **`recommended_minimal_retry`**。不要删除字段、不要重建应用;先按最小列重试,再逐步加非关键列/筛选。 |
289
293
  | 按钮/关联资源配置 | 按钮走 **`builder button apply`**;关联视图/报表走 **`builder associated-resource apply`** |
290
294
  | 部分失败 | 读 **`views_diff.failed`** 与契约 **execution_notes** 中 **partial_success** |
291
295
  | 权限/锁 | 同 [交付 SOP](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)(**`publish verify`**、编辑锁) |
@@ -11,8 +11,10 @@ qingflow --json record schema insert --app-key <APP_KEY> > tmp/qingflow_insert_s
11
11
  qingflow --json record insert --app-key <APP_KEY> --items-file tmp/records.json > tmp/qingflow_insert_result.json
12
12
  ```
13
13
 
14
- 不要用 `record schema applicant` 代替 `record_insert_schema_get` 的主路径;新建记录需要 insert-ready schema 里的 `required_fields`、`optional_fields`、`payload_template`、`format_hint` 和 `example_value`。
14
+ 不要用 `record schema applicant` 代替 `record_insert_schema_get` 的主路径;新建记录需要 insert-ready schema 里的 `required_fields`、`optional_fields`、`payload_template`、`format_hint`、`expected_format`、`example_value` 和字段级 `options`。
15
15
 
16
- 成员、部门、关联记录、选项、附件等特殊字段按 `qingflow-record-insert` 的 **Special Field Write Cheatsheet** 写:先读 insert schema;部门/成员不能自造候选;关联记录批量写入优先 `record_id`,自然名称只在唯一匹配时使用;附件先上传再写返回值。
16
+ 成员、部门、关联记录、选项、附件等特殊字段按 `qingflow-record-insert` 的 **Special Field Write Cheatsheet** 写:先读 insert schema;部门/成员不能自造候选;选项值必须来自 schema `options` 的文本或 id;关联记录批量写入优先 `record_id`,自然名称只在唯一匹配时使用;附件先上传再写返回值。
17
+
18
+ 追加样例数据时也必须 schema-first:按 `required_fields` 补齐必填;按 `expected_format/example_value` 选择数值、金额、日期等格式;按 `options` 生成选项值。不要按业务常识自造“正常/已完成/高优先级”等 schema 里不存在的选项。比例、完成率、评分、百分比等字段也按 schema 示例写;如果字段被建成金额/整数类而不接受小数,不要强塞 decimal,改用符合 schema 的整数值,或回到 builder 阶段把字段建模为 `number`。
17
19
 
18
20
  录入数据时不要填写轻流系统字段:`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。这些字段由平台生成;需要确认时在创建成功后读取记录详情,不要把它们写进 `fields` / `items[].fields`。
@@ -45,7 +45,7 @@
45
45
  | `select` / `single_choice` / `dropdown` | `single_select` |
46
46
  | `multi_select` / `multi_choice` / `multiple_choice` / `checkbox` | `multi_select` |
47
47
 
48
- 完整映射以 `builder contract --tool-name app_schema_apply` 的 `allowed_values.field.type_aliases` 为准。
48
+ 完整映射以 `builder contract --tool-name app_schema_apply` 的 `$.contract.allowed_values["field.type_aliases"]` 为准。
49
49
 
50
50
  ---
51
51
 
@@ -0,0 +1,87 @@
1
+ #!/usr/bin/env python3
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import glob
6
+ import json
7
+ import sys
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+
12
+ def main(argv: list[str] | None = None) -> int:
13
+ parser = argparse.ArgumentParser(description="Validate Qingflow CLI output artifact files.")
14
+ parser.add_argument("paths", nargs="*", help="Output files to validate")
15
+ parser.add_argument("--glob", action="append", default=[], dest="glob_patterns", help="Glob pattern for output files")
16
+ parser.add_argument("--allow-invalid-json", action="store_true", help="Only check file existence and non-zero size")
17
+ args = parser.parse_args(argv)
18
+
19
+ paths = _expand_paths(args.paths, args.glob_patterns)
20
+ issues: list[dict[str, Any]] = []
21
+ if not paths:
22
+ issues.append(_issue("NO_FILES", "$", "no output files were provided"))
23
+ for path in paths:
24
+ issues.extend(validate_output_file(path, require_json=not args.allow_invalid_json))
25
+
26
+ payload: dict[str, Any] = {"status": "failed" if issues else "success", "checked_count": len(paths), "issues": issues}
27
+ if issues:
28
+ payload["error_code"] = "QINGFLOW_OUTPUT_ARTIFACTS_INVALID"
29
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
30
+ return 1 if issues else 0
31
+
32
+
33
+ def validate_output_file(path: Path, *, require_json: bool = True) -> list[dict[str, Any]]:
34
+ path_text = str(path)
35
+ if not path.exists():
36
+ return [_issue("OUTPUT_FILE_MISSING", path_text, "output file does not exist")]
37
+ if not path.is_file():
38
+ return [_issue("OUTPUT_PATH_NOT_FILE", path_text, "output path is not a file")]
39
+ try:
40
+ size = path.stat().st_size
41
+ except OSError as exc:
42
+ return [_issue("OUTPUT_FILE_STAT_FAILED", path_text, str(exc))]
43
+ if size == 0:
44
+ return [
45
+ _issue(
46
+ "OUTPUT_FILE_EMPTY",
47
+ path_text,
48
+ "output file is 0 bytes; treat write state as unknown and run readback before retry",
49
+ next_action="readback_before_retry",
50
+ )
51
+ ]
52
+ if not require_json:
53
+ return []
54
+ try:
55
+ json.loads(path.read_text(encoding="utf-8"))
56
+ except OSError as exc:
57
+ return [_issue("OUTPUT_FILE_READ_FAILED", path_text, str(exc))]
58
+ except json.JSONDecodeError as exc:
59
+ return [_issue("OUTPUT_FILE_INVALID_JSON", path_text, exc.msg)]
60
+ return []
61
+
62
+
63
+ def _expand_paths(raw_paths: list[str], patterns: list[str]) -> list[Path]:
64
+ seen: set[str] = set()
65
+ paths: list[Path] = []
66
+ for raw in raw_paths:
67
+ path = Path(raw)
68
+ key = str(path)
69
+ if key not in seen:
70
+ paths.append(path)
71
+ seen.add(key)
72
+ for pattern in patterns:
73
+ for match in sorted(glob.glob(pattern)):
74
+ path = Path(match)
75
+ key = str(path)
76
+ if key not in seen:
77
+ paths.append(path)
78
+ seen.add(key)
79
+ return paths
80
+
81
+
82
+ def _issue(code: str, path: str, message: str, **extra: Any) -> dict[str, Any]:
83
+ return {"code": code, "path": path, "message": message, **extra}
84
+
85
+
86
+ if __name__ == "__main__":
87
+ sys.exit(main())
@@ -7,7 +7,7 @@ metadata:
7
7
 
8
8
  # Qingflow MCP Setup
9
9
 
10
- > **Skill 版本**:`qingflow-skills-2026.06.23.1`(入口文档版本;如需确认 CLI 包版本,使用 `qingflow --version` 或 `qingflow --json version`)。
10
+ > **Skill 版本**:`qingflow-skills-2026.06.24.1`(入口文档版本;如需确认 CLI 包版本,使用 `qingflow --version` 或 `qingflow --json version`)。
11
11
 
12
12
  ## Overview
13
13
 
@@ -101,6 +101,7 @@ from .models import (
101
101
  )
102
102
 
103
103
  BUILDER_PORTAL_LIST_DETAIL_VERIFY_LIMIT = 50
104
+ CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE = 8
104
105
 
105
106
 
106
107
  QUESTION_TYPE_TO_FIELD_TYPE: dict[int, str] = {
@@ -186,6 +187,37 @@ QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES = {
186
187
  FieldType.relation.value,
187
188
  FieldType.subtable.value,
188
189
  }
190
+ QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC = sorted(
191
+ {
192
+ "address",
193
+ "attachment",
194
+ "code_block",
195
+ "q_linker",
196
+ "relation",
197
+ "subtable",
198
+ }
199
+ )
200
+ QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC = sorted(
201
+ {
202
+ "text",
203
+ "long_text",
204
+ "number",
205
+ "amount",
206
+ "date",
207
+ "datetime",
208
+ "single_select",
209
+ "multi_select",
210
+ "phone",
211
+ "email",
212
+ "boolean",
213
+ "member",
214
+ "department",
215
+ }
216
+ )
217
+ QUERY_CONDITION_FIX_HINT = (
218
+ "Remove this field from query_conditions. query_conditions only configures the frontend query panel for supported query fields. "
219
+ "Use filters for fixed saved filters, and use associated-resource match_mappings for current-record relation/report matching."
220
+ )
189
221
 
190
222
  ASSOCIATED_RESOURCE_LIMIT_TYPE_ALL = 1
191
223
  ASSOCIATED_RESOURCE_LIMIT_TYPE_SELECT = 2
@@ -4378,7 +4410,7 @@ class AiBuilderFacade:
4378
4410
  "details": {"edit_version_no": None, "associated_item_ids_by_client_key": client_key_to_id, "readback_failed": False},
4379
4411
  "request_id": None,
4380
4412
  "suggested_next_call": None,
4381
- "noop": True,
4413
+ "noop": False,
4382
4414
  "warnings": [],
4383
4415
  "verification": {"associated_resources_verified": True, "associated_resource_view_configs_verified": True, "readback_loaded": True, "published": False},
4384
4416
  "verified": True,
@@ -7511,7 +7543,12 @@ class AiBuilderFacade:
7511
7543
  "nodes": public_nodes,
7512
7544
  "transitions": transitions,
7513
7545
  },
7514
- details={"missing_dependencies": ["status field"]},
7546
+ details={
7547
+ "missing_dependencies": ["status field"],
7548
+ "fix_hint": "Add an explicit business status select field before applying approval workflows. Do not create platform system fields such as 当前流程状态.",
7549
+ "recommended_field_names": ["状态", "处理状态", "审批状态", "工单状态", "流程阶段"],
7550
+ "forbidden_system_field_names": ["当前流程状态", "当前处理人", "当前处理节点", "流程标题"],
7551
+ },
7515
7552
  missing_fields=["status"],
7516
7553
  suggested_next_call={
7517
7554
  "tool_name": "app_schema_apply",
@@ -7519,7 +7556,7 @@ class AiBuilderFacade:
7519
7556
  "profile": profile,
7520
7557
  "app_key": request.app_key,
7521
7558
  "create_if_missing": False,
7522
- "add_fields": [{"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": True}],
7559
+ "add_fields": [{"name": "状态", "type": "select", "options": ["草稿", "进行中", "已完成"], "required": True}],
7523
7560
  "update_fields": [],
7524
7561
  "remove_fields": [],
7525
7562
  },
@@ -8266,7 +8303,16 @@ class AiBuilderFacade:
8266
8303
  relation_field_count = _count_relation_fields(current_fields)
8267
8304
  relation_limit_verified = relation_field_count <= 1
8268
8305
  relation_warnings = (
8269
- [_warning("RELATION_FIELD_LIMIT_RISK", "multiple relation fields are not a stable backend capability", relation_field_count=relation_field_count)]
8306
+ [
8307
+ _warning(
8308
+ "RELATION_FIELD_LIMIT_RISK",
8309
+ "multiple relation fields were written and verified, but this backend capability can be unstable; do not downgrade to text unless the write fails or relation readback mismatches",
8310
+ severity="warning",
8311
+ relation_field_count=relation_field_count,
8312
+ relation_fields_created=True,
8313
+ do_not_downgrade_to_text_unless_apply_failed=True,
8314
+ )
8315
+ ]
8270
8316
  if not relation_limit_verified
8271
8317
  else []
8272
8318
  )
@@ -8397,6 +8443,8 @@ class AiBuilderFacade:
8397
8443
  "app_key": target.app_key,
8398
8444
  "field_diff": {"added": added, "updated": updated, "removed": removed},
8399
8445
  "relation_field_count": relation_field_count,
8446
+ "relation_fields_created": False,
8447
+ "recommended_modeling_fallback": "Keep the primary relation field as relation; use text/reference summary fields only for secondary cross-object links, and report the downgrade as partial.",
8400
8448
  "transport_error": {
8401
8449
  "http_status": api_error.http_status,
8402
8450
  "backend_code": api_error.backend_code,
@@ -10154,6 +10202,12 @@ class AiBuilderFacade:
10154
10202
  "backend_code": api_error.backend_code,
10155
10203
  "category": api_error.category,
10156
10204
  },
10205
+ **_view_apply_failure_diagnostics(
10206
+ patch=patch,
10207
+ current_fields_by_name=current_fields_by_name,
10208
+ backend_code=api_error.backend_code,
10209
+ operation_phase=operation_phase,
10210
+ ),
10157
10211
  },
10158
10212
  }
10159
10213
  failed_views.append(failure_entry)
@@ -11224,6 +11278,56 @@ class AiBuilderFacade:
11224
11278
  normalized_args["upsert_charts"] = [patch.model_dump(mode="json") for patch in upsert_charts]
11225
11279
  normalized_args["patch_results"] = patch_results
11226
11280
 
11281
+ if len(upsert_charts) > CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE:
11282
+ batching_context = _chart_apply_batching_context(
11283
+ request=request,
11284
+ upsert_charts=upsert_charts,
11285
+ batch_size=CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE,
11286
+ )
11287
+ first_batch = batching_context["suggested_batch_payloads"][0]
11288
+ return finalize({
11289
+ "status": "failed",
11290
+ "error_code": "CHART_UPSERT_BATCH_TOO_LARGE",
11291
+ "recoverable": True,
11292
+ "message": (
11293
+ f"upsert_charts contains {len(upsert_charts)} items; split into batches of "
11294
+ f"{CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE} or fewer before writing"
11295
+ ),
11296
+ "normalized_args": normalized_args,
11297
+ "missing_fields": [],
11298
+ "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
11299
+ "details": batching_context,
11300
+ "request_id": None,
11301
+ "suggested_next_call": {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **first_batch}},
11302
+ "backend_code": None,
11303
+ "http_status": None,
11304
+ "noop": False,
11305
+ "warnings": [
11306
+ _warning(
11307
+ "CHART_UPSERT_BATCH_SIZE_BLOCKED",
11308
+ "large chart upsert batches are blocked before write to avoid timeout and unknown write state",
11309
+ upsert_count=len(upsert_charts),
11310
+ max_upsert_count=CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE,
11311
+ )
11312
+ ],
11313
+ "verification": {
11314
+ "charts_verified": False,
11315
+ "readback_unavailable": False,
11316
+ "readback_before_retry": False,
11317
+ "chart_delete_readback_results": [],
11318
+ "chart_order_verified": True,
11319
+ "chart_list_source": existing_chart_list_source,
11320
+ },
11321
+ "app_key": app_key,
11322
+ "app_name": app_name,
11323
+ "chart_results": [],
11324
+ "verified": False,
11325
+ "write_executed": False,
11326
+ "write_succeeded": False,
11327
+ "safe_to_retry": True,
11328
+ "next_action": "split_upsert_charts_and_retry",
11329
+ })
11330
+
11227
11331
  chart_results: list[dict[str, Any]] = []
11228
11332
  created_ids: list[str] = []
11229
11333
  updated_ids: list[str] = []
@@ -11510,6 +11614,15 @@ class AiBuilderFacade:
11510
11614
  primary_failure = failed_items[0]
11511
11615
  primary_error_code = str(primary_failure.get("error_code") or "").strip()
11512
11616
  primary_message = str(primary_failure.get("message") or "").strip()
11617
+ retry_context = _chart_apply_retry_context(
11618
+ request=request,
11619
+ failed_items=failed_items,
11620
+ created_ids=created_ids,
11621
+ updated_ids=updated_ids,
11622
+ removed_ids=removed_ids,
11623
+ reordered=reordered,
11624
+ write_executed=write_executed,
11625
+ )
11513
11626
  return finalize({
11514
11627
  "status": "partial_success" if successful_changes else "failed",
11515
11628
  "error_code": "CHART_APPLY_PARTIAL" if successful_changes else primary_error_code or "CHART_APPLY_FAILED",
@@ -11520,6 +11633,7 @@ class AiBuilderFacade:
11520
11633
  "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
11521
11634
  "details": {
11522
11635
  "per_chart_results": chart_results,
11636
+ **retry_context,
11523
11637
  **({"readback_error": _transport_error_payload(readback_error)} if readback_error is not None else {}),
11524
11638
  },
11525
11639
  "request_id": failed_items[0].get("request_id") or (readback_error.request_id if readback_error is not None else None),
@@ -11536,6 +11650,7 @@ class AiBuilderFacade:
11536
11650
  "verification": {
11537
11651
  "charts_verified": False if failed_items else verified,
11538
11652
  "readback_unavailable": any_readback_unavailable,
11653
+ "readback_before_retry": bool(write_executed),
11539
11654
  "chart_delete_readback_results": [deepcopy(item) for item in chart_results if item.get("operation") == "delete"],
11540
11655
  "chart_order_verified": False if request.reorder_chart_ids else True,
11541
11656
  "chart_list_source": readback_list_source or existing_chart_list_source,
@@ -11546,6 +11661,7 @@ class AiBuilderFacade:
11546
11661
  "verified": False if failed_items else verified,
11547
11662
  "write_executed": write_executed,
11548
11663
  "write_succeeded": write_succeeded,
11664
+ **({"write_may_have_succeeded": True, "next_action": "readback_before_retry"} if write_executed else {}),
11549
11665
  "safe_to_retry": not write_executed,
11550
11666
  })
11551
11667
  result_verified = verified or noop
@@ -15682,6 +15798,155 @@ def _public_chart_filter_groups_from_qingbi_config(config: dict[str, Any]) -> li
15682
15798
  return groups
15683
15799
 
15684
15800
 
15801
+ def _chart_apply_retry_context(
15802
+ *,
15803
+ request: ChartApplyRequest,
15804
+ failed_items: list[dict[str, Any]],
15805
+ created_ids: list[str],
15806
+ updated_ids: list[str],
15807
+ removed_ids: list[str],
15808
+ reordered: bool,
15809
+ write_executed: bool,
15810
+ ) -> dict[str, Any]:
15811
+ failed_chart_names = [
15812
+ str(item.get("name") or "").strip()
15813
+ for item in failed_items
15814
+ if str(item.get("name") or "").strip()
15815
+ ]
15816
+ failed_delete_ids = [
15817
+ str(item.get("chart_id") or "").strip()
15818
+ for item in failed_items
15819
+ if str(item.get("operation") or "") == "delete" and str(item.get("chart_id") or "").strip()
15820
+ ]
15821
+ reorder_failed = any(str(item.get("operation") or "") == "reorder" for item in failed_items)
15822
+ failed_name_set = set(failed_chart_names)
15823
+ retry_payload: dict[str, Any] = {"app_key": request.app_key}
15824
+ retry_upserts = [
15825
+ patch.model_dump(mode="json", exclude_none=True)
15826
+ for patch in request.upsert_charts
15827
+ if patch.name in failed_name_set
15828
+ ]
15829
+ if retry_upserts:
15830
+ retry_payload["upsert_charts"] = retry_upserts
15831
+ if failed_delete_ids:
15832
+ retry_payload["remove_chart_ids"] = failed_delete_ids
15833
+ if reorder_failed and request.reorder_chart_ids:
15834
+ retry_payload["reorder_chart_ids"] = list(request.reorder_chart_ids)
15835
+ has_retry_payload = any(key in retry_payload for key in ("upsert_charts", "remove_chart_ids", "reorder_chart_ids"))
15836
+ context: dict[str, Any] = {
15837
+ "created_chart_ids": list(created_ids),
15838
+ "updated_chart_ids": list(updated_ids),
15839
+ "removed_chart_ids": list(removed_ids),
15840
+ "failed_chart_names": failed_chart_names,
15841
+ "failed_delete_chart_ids": failed_delete_ids,
15842
+ "readback_first": bool(write_executed),
15843
+ "retry_rule": (
15844
+ "read app charts before retrying; retry only the failed chart payloads if they are still missing or unverified"
15845
+ if write_executed
15846
+ else "fix the failed chart payloads and retry only those items"
15847
+ ),
15848
+ }
15849
+ if has_retry_payload:
15850
+ context["suggested_retry_payload"] = retry_payload
15851
+ return context
15852
+
15853
+
15854
+ def _chart_apply_batching_context(
15855
+ *,
15856
+ request: ChartApplyRequest,
15857
+ upsert_charts: list[ChartUpsertPatch],
15858
+ batch_size: int,
15859
+ ) -> dict[str, Any]:
15860
+ suggested_batch_payloads: list[dict[str, Any]] = []
15861
+ for start in range(0, len(upsert_charts), batch_size):
15862
+ batch = upsert_charts[start : start + batch_size]
15863
+ suggested_batch_payloads.append(
15864
+ {
15865
+ "app_key": request.app_key,
15866
+ "upsert_charts": [patch.model_dump(mode="json", exclude_none=True) for patch in batch],
15867
+ }
15868
+ )
15869
+
15870
+ followup_payload: dict[str, Any] = {"app_key": request.app_key}
15871
+ if request.remove_chart_ids:
15872
+ followup_payload["remove_chart_ids"] = list(request.remove_chart_ids)
15873
+ if request.reorder_chart_ids:
15874
+ followup_payload["reorder_chart_ids"] = list(request.reorder_chart_ids)
15875
+ if len(followup_payload) > 1:
15876
+ suggested_batch_payloads.append(followup_payload)
15877
+
15878
+ return {
15879
+ "upsert_count": len(upsert_charts),
15880
+ "max_upsert_count": batch_size,
15881
+ "write_executed": False,
15882
+ "readback_first": False,
15883
+ "retry_rule": "run suggested_batch_payloads one at a time; do not submit the original large upsert_charts array",
15884
+ "suggested_batch_payloads": suggested_batch_payloads,
15885
+ }
15886
+
15887
+
15888
+ def _view_apply_failure_diagnostics(
15889
+ *,
15890
+ patch: ViewUpsertPatch,
15891
+ current_fields_by_name: dict[str, dict[str, Any]],
15892
+ backend_code: Any,
15893
+ operation_phase: str,
15894
+ ) -> dict[str, Any]:
15895
+ references: list[tuple[str, str]] = []
15896
+
15897
+ def add_reference(name: Any, source: str) -> None:
15898
+ text = str(name or "").strip()
15899
+ if text:
15900
+ references.append((text, source))
15901
+
15902
+ for column in patch.columns:
15903
+ add_reference(column, "columns")
15904
+ add_reference(patch.group_by, "group_by")
15905
+ add_reference(patch.start_field, "start_field")
15906
+ add_reference(patch.end_field, "end_field")
15907
+ add_reference(patch.title_field, "title_field")
15908
+ for rule in patch.filters:
15909
+ add_reference(rule.field_name, "filters")
15910
+
15911
+ seen: set[str] = set()
15912
+ field_entries: list[dict[str, Any]] = []
15913
+ for field_name, source in references:
15914
+ key = f"{field_name}\0{source}"
15915
+ if key in seen:
15916
+ continue
15917
+ seen.add(key)
15918
+ field = current_fields_by_name.get(field_name) or {}
15919
+ field_entries.append(
15920
+ {
15921
+ "field_name": field_name,
15922
+ "source": source,
15923
+ "field_id": field.get("field_id"),
15924
+ "que_id": field.get("que_id"),
15925
+ "field_type": field.get("type"),
15926
+ "que_type": field.get("que_type"),
15927
+ "exists_in_schema": bool(field),
15928
+ }
15929
+ )
15930
+ diagnostics: dict[str, Any] = {
15931
+ "operation_phase": operation_phase,
15932
+ "field_level_diagnostics": field_entries,
15933
+ }
15934
+ if backend_code_value_int(backend_code) == 40038:
15935
+ diagnostics.update(
15936
+ {
15937
+ "suspected_fields": field_entries,
15938
+ "recovery_hint": "Do not delete app fields or recreate the app. First retry the view with the smallest required columns; then add non-critical columns back one by one.",
15939
+ "recommended_minimal_retry": {
15940
+ "name": patch.name,
15941
+ "type": patch.type.value,
15942
+ "columns": [field_entries[0]["field_name"]] if field_entries else [],
15943
+ **({"filters": [rule.model_dump(mode="json", exclude_none=True) for rule in patch.filters]} if patch.filters else {}),
15944
+ },
15945
+ }
15946
+ )
15947
+ return diagnostics
15948
+
15949
+
15685
15950
  def _public_chart_group_by_from_qingbi_config(config: dict[str, Any]) -> list[str]:
15686
15951
  fields: list[dict[str, Any]] = []
15687
15952
  for key in ("selectedDimensions", "xDimensions", "yDimensions", "selectedTime"):
@@ -23737,6 +24002,9 @@ def _resolve_query_condition_field(
23737
24002
  "field": raw,
23738
24003
  "parent_field": subfield_parent.get("name"),
23739
24004
  "message": "subtable subfields cannot be used as view query conditions",
24005
+ "fix_hint": QUERY_CONDITION_FIX_HINT,
24006
+ "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
24007
+ "unsupported_field_types": QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC,
23740
24008
  }
23741
24009
  return {}, {
23742
24010
  "error_code": "QUERY_CONDITION_FIELD_NOT_FOUND",
@@ -23753,6 +24021,9 @@ def _resolve_query_condition_field(
23753
24021
  "field": field.get("name"),
23754
24022
  "field_type": field_type,
23755
24023
  "message": "this field type is not supported by the frontend query condition panel",
24024
+ "fix_hint": QUERY_CONDITION_FIX_HINT,
24025
+ "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
24026
+ "unsupported_field_types": QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC,
23756
24027
  }
23757
24028
  que_id = _coerce_positive_int(field.get("que_id"))
23758
24029
  if que_id is None:
@@ -23762,6 +24033,8 @@ def _resolve_query_condition_field(
23762
24033
  "missing_fields": [],
23763
24034
  "field": field.get("name"),
23764
24035
  "message": "query condition field has no backend queId",
24036
+ "fix_hint": QUERY_CONDITION_FIX_HINT,
24037
+ "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
23765
24038
  }
23766
24039
  return field, None
23767
24040
 
@@ -9,7 +9,7 @@ from ..errors import QingflowApiError, backend_code_value_int, message_looks_lik
9
9
  from ..public_surface import cli_public_tool_spec_from_namespace
10
10
  from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
11
11
  from ..tools.ai_builder_tools import _attach_builder_apply_envelope
12
- from ..version import get_cli_version
12
+ from ..version import get_cli_version, get_cli_version_info
13
13
  from .context import CliContext, build_cli_context
14
14
  from .formatters import emit_json_result, emit_text_result
15
15
  from .commands import register_all_commands
@@ -120,12 +120,11 @@ def run(
120
120
 
121
121
 
122
122
  def _handle_version(_args: argparse.Namespace, _context: CliContext) -> dict[str, Any]:
123
- version = get_cli_version()
123
+ info = get_cli_version_info()
124
124
  return {
125
125
  "ok": True,
126
126
  "status": "success",
127
- "version": version,
128
- "package": "@qingflow-tech/qingflow-cli",
127
+ **info,
129
128
  }
130
129
 
131
130
 
@@ -136,8 +135,7 @@ def _emit_version(*, json_mode: bool, stdout: TextIO) -> int:
136
135
  {
137
136
  "ok": True,
138
137
  "status": "success",
139
- "version": version,
140
- "package": "@qingflow-tech/qingflow-cli",
138
+ **get_cli_version_info(),
141
139
  },
142
140
  stream=stdout,
143
141
  )
@@ -631,15 +631,16 @@ class AiBuilderTools(ToolBase):
631
631
  "allowed_values": {"tool_name": public_tool_names},
632
632
  "details": {"reason_path": "tool_name"},
633
633
  "suggested_next_call": None,
634
- "request_id": None,
635
- "backend_code": None,
636
- "http_status": None,
637
- "noop": False,
638
- "warnings": [],
639
- "verification": {},
640
- "verified": False,
641
- }
634
+ "request_id": None,
635
+ "backend_code": None,
636
+ "http_status": None,
637
+ "noop": False,
638
+ "warnings": [],
639
+ "verification": {},
640
+ "verified": False,
641
+ }
642
642
  contract = _builder_contract_with_apply_output(lookup_name, contract)
643
+ contract_summary = _builder_tool_contract_summary(lookup_name, contract)
643
644
  return {
644
645
  "status": "success",
645
646
  "error_code": None,
@@ -658,6 +659,8 @@ class AiBuilderTools(ToolBase):
658
659
  "verification": {},
659
660
  "verified": True,
660
661
  "tool_name": requested,
662
+ "summary": contract_summary,
663
+ "json_paths": contract_summary["json_paths"],
661
664
  "contract": contract,
662
665
  }
663
666
 
@@ -680,6 +683,12 @@ class AiBuilderTools(ToolBase):
680
683
  "color_count": len(catalog["icon_colors"]),
681
684
  "warnings": [],
682
685
  "verification": {"source": "backend AiBuildConstant ICON_NAMES/ICON_COLORS"},
686
+ "json_paths": {
687
+ "icon_names": "$.icon_names",
688
+ "icon_colors": "$.icon_colors",
689
+ "generic_icon_names": "$.generic_icon_names",
690
+ "common_examples": "$.common_examples",
691
+ },
683
692
  }
684
693
 
685
694
  @tool_cn_name("分组创建")
@@ -3927,11 +3936,58 @@ def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) ->
3927
3936
  "schema_version": BUILDER_APPLY_SCHEMA_VERSION,
3928
3937
  "preferred_ui_fields": ["operation", "summary", "resources"],
3929
3938
  "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "icon_config", "error_code", "message"],
3939
+ "json_paths": _builder_apply_json_paths(),
3930
3940
  "legacy_fields_preserved": True,
3931
3941
  }
3932
3942
  return public
3933
3943
 
3934
3944
 
3945
+ def _builder_tool_contract_summary(tool_name: str, contract: JSONObject) -> JSONObject:
3946
+ allowed_values = contract.get("allowed_values") if isinstance(contract, dict) else {}
3947
+ allowed_values_keys = sorted(str(key) for key in allowed_values) if isinstance(allowed_values, dict) else []
3948
+ return {
3949
+ "tool_name": tool_name,
3950
+ "contract_path": "$.contract",
3951
+ "allowed_keys_path": "$.contract.allowed_keys",
3952
+ "allowed_values_path": "$.contract.allowed_values",
3953
+ "allowed_values_key_style": "flat_dotted_keys",
3954
+ "minimal_example_path": "$.contract.minimal_example",
3955
+ "execution_notes_path": "$.contract.execution_notes",
3956
+ "top_level_allowed_values_usage": "empty on successful contract lookup; use $.contract.allowed_values instead",
3957
+ "allowed_values_keys_sample": allowed_values_keys[:12],
3958
+ "json_paths": {
3959
+ "contract": "$.contract",
3960
+ "allowed_keys": "$.contract.allowed_keys",
3961
+ "allowed_values": "$.contract.allowed_values",
3962
+ "minimal_example": "$.contract.minimal_example",
3963
+ "execution_notes": "$.contract.execution_notes",
3964
+ "aliases": "$.contract.aliases",
3965
+ },
3966
+ }
3967
+
3968
+
3969
+ def _builder_apply_json_paths() -> JSONObject:
3970
+ return {
3971
+ "status": "$.status",
3972
+ "schema_version": "$.schema_version",
3973
+ "operation": "$.operation",
3974
+ "summary": "$.summary",
3975
+ "resources": "$.resources",
3976
+ "warnings": "$.warnings",
3977
+ "verification": "$.verification",
3978
+ "details": "$.details",
3979
+ "write_executed": "$.write_executed",
3980
+ "write_may_have_succeeded": "$.write_may_have_succeeded",
3981
+ "safe_to_retry": "$.safe_to_retry",
3982
+ "next_action": "$.next_action",
3983
+ "summary_write_executed": "$.summary.write_executed",
3984
+ "summary_safe_to_retry": "$.summary.safe_to_retry",
3985
+ "resource_keys": "$.resources[].key",
3986
+ "resource_ids": "$.resources[].id",
3987
+ "resource_statuses": "$.resources[].status",
3988
+ }
3989
+
3990
+
3935
3991
  def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONObject:
3936
3992
  if not isinstance(payload, dict):
3937
3993
  return payload
@@ -3940,6 +3996,7 @@ def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONO
3940
3996
  payload["operation"] = tool_name
3941
3997
  payload["resources"] = resources
3942
3998
  payload["summary"] = _builder_apply_summary(payload, resources)
3999
+ payload["json_paths"] = _builder_apply_json_paths()
3943
4000
  return payload
3944
4001
 
3945
4002
 
@@ -5768,12 +5825,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
5768
5825
  "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
5769
5826
  },
5770
5827
  "dependency_hints": [
5771
- "approval-style workflows require an explicit status field",
5828
+ "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
5772
5829
  "approve/fill/copy nodes require at least one assignee",
5773
5830
  ],
5774
5831
  "execution_notes": [
5775
5832
  "public flow building is intentionally limited to linear workflows",
5776
5833
  "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
5834
+ "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
5777
5835
  ],
5778
5836
  "minimal_example": {
5779
5837
  "profile": "default",
@@ -5808,13 +5866,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
5808
5866
  "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
5809
5867
  },
5810
5868
  "dependency_hints": [
5811
- "approval-style workflows require an explicit status field",
5869
+ "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
5812
5870
  "approve/fill/copy nodes require at least one assignee",
5813
5871
  ],
5814
5872
  "execution_notes": [
5815
5873
  "public flow building is intentionally limited to linear workflows",
5816
5874
  "app_flow_apply is replace-only; do not treat node snippets as partial patches",
5817
5875
  "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
5876
+ "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
5818
5877
  "workflow verification only covers linear node structure in the public tool surface",
5819
5878
  ],
5820
5879
  "minimal_example": {
@@ -5894,7 +5953,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
5894
5953
  "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
5895
5954
  "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
5896
5955
  "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
5897
- "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
5956
+ "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
5957
+ "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
5898
5958
  "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
5899
5959
  "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
5900
5960
  "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
@@ -5945,6 +6005,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
5945
6005
  ],
5946
6006
  "remove_views": [],
5947
6007
  },
6008
+ "query_conditions_field_rules": {
6009
+ "supported_field_types": ["text", "long_text", "number", "amount", "date", "datetime", "single_select", "multi_select", "phone", "email", "boolean", "member", "department"],
6010
+ "unsupported_field_types": ["relation", "attachment", "subtable", "address", "code_block", "q_linker"],
6011
+ "use_instead": {
6012
+ "fixed_filter": "filters",
6013
+ "current_record_related_report_or_view": "app_associated_resources_apply.match_mappings",
6014
+ },
6015
+ },
5948
6016
  "gantt_example": {
5949
6017
  "profile": "default",
5950
6018
  "app_key": "APP_KEY",
@@ -6024,7 +6092,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
6024
6092
  "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
6025
6093
  "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
6026
6094
  "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
6027
- "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
6095
+ "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
6096
+ "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
6028
6097
  "use patch_views for partial parameter replacement on existing views; the public update mode is patch even though the backend save is still a full view payload",
6029
6098
  "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
6030
6099
  "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
@@ -6078,6 +6147,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
6078
6147
  ],
6079
6148
  "remove_views": [],
6080
6149
  },
6150
+ "query_conditions_field_rules": {
6151
+ "supported_field_types": ["text", "long_text", "number", "amount", "date", "datetime", "single_select", "multi_select", "phone", "email", "boolean", "member", "department"],
6152
+ "unsupported_field_types": ["relation", "attachment", "subtable", "address", "code_block", "q_linker"],
6153
+ "use_instead": {
6154
+ "fixed_filter": "filters",
6155
+ "current_record_related_report_or_view": "app_associated_resources_apply.match_mappings",
6156
+ },
6157
+ },
6081
6158
  "gantt_example": {
6082
6159
  "profile": "default",
6083
6160
  "app_key": "APP_KEY",
@@ -1,6 +1,9 @@
1
1
  from __future__ import annotations
2
2
 
3
3
  import json
4
+ import re
5
+ import shutil
6
+ import sys
4
7
  from importlib import metadata
5
8
  from pathlib import Path
6
9
 
@@ -15,7 +18,31 @@ def get_cli_version() -> str:
15
18
  return "0+local"
16
19
 
17
20
 
21
+ def get_cli_version_info() -> dict[str, str | None]:
22
+ package_root = _find_package_root()
23
+ return {
24
+ "version": get_cli_version(),
25
+ "package": _find_package_name(package_root) or "@qingflow-tech/qingflow-cli",
26
+ "executable_path": _resolve_executable_path(),
27
+ "command_path": shutil.which("qingflow"),
28
+ "package_root": str(package_root) if package_root is not None else None,
29
+ "skill_version": _find_skill_version(package_root),
30
+ }
31
+
32
+
18
33
  def _find_package_json_version() -> str | None:
34
+ package_root = _find_package_root()
35
+ if package_root is None:
36
+ return None
37
+ try:
38
+ payload = json.loads((package_root / "package.json").read_text(encoding="utf-8"))
39
+ except (OSError, json.JSONDecodeError):
40
+ return None
41
+ version = str(payload.get("version") or "")
42
+ return version or None
43
+
44
+
45
+ def _find_package_root() -> Path | None:
19
46
  current = Path(__file__).resolve()
20
47
  for parent in current.parents:
21
48
  package_json = parent / "package.json"
@@ -36,5 +63,48 @@ def _find_package_json_version() -> str | None:
36
63
  "@josephyan/qingflow-app-user-mcp",
37
64
  "@josephyan/qingflow-app-builder-mcp",
38
65
  }:
39
- return version
66
+ return parent
67
+ return None
68
+
69
+
70
+ def _find_package_name(package_root: Path | None) -> str | None:
71
+ if package_root is None:
72
+ return None
73
+ try:
74
+ payload = json.loads((package_root / "package.json").read_text(encoding="utf-8"))
75
+ except (OSError, json.JSONDecodeError):
76
+ return None
77
+ name = str(payload.get("name") or "")
78
+ return name or None
79
+
80
+
81
+ def _resolve_executable_path() -> str | None:
82
+ if not sys.argv:
83
+ return None
84
+ raw = str(sys.argv[0] or "").strip()
85
+ if not raw:
86
+ return None
87
+ try:
88
+ return str(Path(raw).resolve())
89
+ except OSError:
90
+ return raw
91
+
92
+
93
+ def _find_skill_version(package_root: Path | None) -> str | None:
94
+ if package_root is None:
95
+ return None
96
+ candidates = [
97
+ package_root / "skills" / "qingflow-cli" / "SKILL.md",
98
+ package_root / "skill" / "qingflow-cli" / "SKILL.md",
99
+ ]
100
+ for skill_file in candidates:
101
+ if not skill_file.exists():
102
+ continue
103
+ try:
104
+ text = skill_file.read_text(encoding="utf-8")
105
+ except OSError:
106
+ continue
107
+ match = re.search(r"Skill\s*版本\**[::]\s*`?([^`\s))]+)", text)
108
+ if match:
109
+ return match.group(1).strip()
40
110
  return None