@qingflow-tech/qingflow-cli 1.0.43 → 1.1.0

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.
Files changed (28) hide show
  1. package/README.md +2 -2
  2. package/npm/bin/qingflow.mjs +32 -1
  3. package/npm/lib/runtime.mjs +43 -2
  4. package/package.json +1 -1
  5. package/pyproject.toml +1 -1
  6. package/skills/qingflow-cli/SKILL.md +8 -2
  7. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md +13 -6
  8. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +17 -2
  9. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md +4 -0
  10. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md +4 -2
  11. package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md +1 -1
  12. package/skills/qingflow-cli/scripts/validate_qingflow_output_files.py +87 -0
  13. package/skills/qingflow-mcp-setup/SKILL.md +1 -1
  14. package/src/qingflow_mcp/__init__.py +1 -1
  15. package/src/qingflow_mcp/builder_facade/models.py +0 -39
  16. package/src/qingflow_mcp/builder_facade/service.py +532 -859
  17. package/src/qingflow_mcp/builder_facade/workflow_spec.py +111 -0
  18. package/src/qingflow_mcp/cli/commands/builder.py +44 -12
  19. package/src/qingflow_mcp/cli/main.py +4 -6
  20. package/src/qingflow_mcp/public_surface.py +2 -0
  21. package/src/qingflow_mcp/server_app_builder.py +16 -8
  22. package/src/qingflow_mcp/solution/compiler/__init__.py +1 -3
  23. package/src/qingflow_mcp/solution/executor.py +3 -133
  24. package/src/qingflow_mcp/tools/ai_builder_tools.py +177 -241
  25. package/src/qingflow_mcp/tools/solution_tools.py +30 -2
  26. package/src/qingflow_mcp/tools/workflow_tools.py +3 -31
  27. package/src/qingflow_mcp/version.py +71 -1
  28. package/src/qingflow_mcp/solution/compiler/workflow_compiler.py +0 -173
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.43
6
+ npm install @qingflow-tech/qingflow-cli@1.1.0
7
7
  ```
8
8
 
9
9
  Run:
10
10
 
11
11
  ```bash
12
- npx -y -p @qingflow-tech/qingflow-cli@1.0.43 qingflow
12
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.0 qingflow
13
13
  ```
14
14
 
15
15
  Environment:
@@ -1,6 +1,37 @@
1
1
  #!/usr/bin/env node
2
- import { spawnServer, getPackageRoot, runSkillsCli } from "../lib/runtime.mjs";
2
+ import fs from "node:fs";
3
+ import path from "node:path";
4
+ import { fileURLToPath, pathToFileURL } from "node:url";
3
5
 
6
+ const PKG_BY_BIN = {
7
+ qingflow: "qingflow-cli",
8
+ "qingflow-app-user-mcp": "qingflow-app-user-mcp",
9
+ "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
10
+ };
11
+
12
+ function resolvePackageModule(metaUrl, ...segments) {
13
+ const scriptPath = fileURLToPath(metaUrl);
14
+ const scriptDir = path.dirname(scriptPath);
15
+ const direct = path.join(scriptDir, ...segments);
16
+ if (fs.existsSync(direct)) {
17
+ return pathToFileURL(direct).href;
18
+ }
19
+ if (path.basename(scriptDir) === ".bin") {
20
+ const binName = path.basename(scriptPath);
21
+ const pkgName = PKG_BY_BIN[binName];
22
+ if (!pkgName) {
23
+ throw new Error(`Unknown qingflow command: ${binName}`);
24
+ }
25
+ const scope = process.env.QINGFLOW_NPM_SCOPE || "@qingflow-tech";
26
+ const fromBin = path.join(scriptDir, "..", scope, pkgName, "npm", ...segments);
27
+ if (fs.existsSync(fromBin)) {
28
+ return pathToFileURL(fromBin).href;
29
+ }
30
+ }
31
+ throw new Error(`Cannot locate ${segments.join("/")} from ${scriptPath}`);
32
+ }
33
+
34
+ const { getPackageRoot, spawnServer, runSkillsCli } = await import(resolvePackageModule(import.meta.url, "lib", "runtime.mjs"));
4
35
  const packageRoot = getPackageRoot(import.meta.url);
5
36
  const args = process.argv.slice(2);
6
37
  if (args[0] === "skills") {
@@ -5,6 +5,12 @@ import { fileURLToPath } from "node:url";
5
5
 
6
6
  const WINDOWS = process.platform === "win32";
7
7
 
8
+ const PKG_BY_BIN = {
9
+ qingflow: "qingflow-cli",
10
+ "qingflow-app-user-mcp": "qingflow-app-user-mcp",
11
+ "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
12
+ };
13
+
8
14
  function runChecked(command, args, options = {}) {
9
15
  const result = spawnSync(command, args, {
10
16
  encoding: "utf8",
@@ -28,7 +34,18 @@ function commandWorks(command, args) {
28
34
  }
29
35
 
30
36
  export function getPackageRoot(metaUrl) {
31
- return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
37
+ const scriptPath = fileURLToPath(metaUrl);
38
+ const scriptDir = path.dirname(scriptPath);
39
+ if (path.basename(scriptDir) === ".bin") {
40
+ const binName = path.basename(scriptPath);
41
+ const pkgName = PKG_BY_BIN[binName];
42
+ if (!pkgName) {
43
+ throw new Error(`Unknown qingflow command: ${binName}`);
44
+ }
45
+ const scope = process.env.QINGFLOW_NPM_SCOPE || "@qingflow-tech";
46
+ return path.join(scriptDir, "..", scope, pkgName);
47
+ }
48
+ return path.resolve(scriptDir, "..", "..");
32
49
  }
33
50
 
34
51
  export function getCodexHome() {
@@ -480,6 +497,17 @@ function getVenvPip(packageRoot) {
480
497
  : path.join(getVenvDir(packageRoot), "bin", "pip");
481
498
  }
482
499
 
500
+ function findOfflineProjectWheel(findLinksDir) {
501
+ const wheels = fs
502
+ .readdirSync(findLinksDir)
503
+ .filter((name) => /^qingflow_mcp-.*\.whl$/i.test(name))
504
+ .sort();
505
+ if (wheels.length === 0) {
506
+ throw new Error(`Offline install expected a qingflow_mcp wheel in ${findLinksDir}`);
507
+ }
508
+ return path.join(findLinksDir, wheels[wheels.length - 1]);
509
+ }
510
+
483
511
  export function findPython() {
484
512
  const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
485
513
  const candidates = preferred
@@ -528,7 +556,20 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
528
556
  }
529
557
 
530
558
  const pip = getVenvPip(packageRoot);
531
- runChecked(pip, ["install", "--disable-pip-version-check", "."], { cwd: packageRoot });
559
+ const pipArgs = ["install", "--disable-pip-version-check"];
560
+ const offlineFindLinks = process.env.QINGFLOW_MCP_PIP_FIND_LINKS?.trim();
561
+ if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1") {
562
+ pipArgs.push("--no-index");
563
+ }
564
+ if (offlineFindLinks) {
565
+ pipArgs.push("--find-links", offlineFindLinks);
566
+ }
567
+ if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1" && offlineFindLinks) {
568
+ pipArgs.push(findOfflineProjectWheel(offlineFindLinks));
569
+ } else {
570
+ pipArgs.push(".");
571
+ }
572
+ runChecked(pip, pipArgs, { cwd: packageRoot });
532
573
 
533
574
  fs.writeFileSync(
534
575
  stampPath,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qingflow-tech/qingflow-cli",
3
- "version": "1.0.43",
3
+ "version": "1.1.0",
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.43"
7
+ version = "1.1.0"
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.24.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.24.1`(入口文档版本;如需确认 CLI 包版本,使用 `qingflow --version` 或 `qingflow --json version`)。
10
+ > **Skill 版本**:`qingflow-skills-2026.06.24.2`(入口文档版本;如需确认 CLI 包版本,使用 `qingflow --version` 或 `qingflow --json version`)。
11
11
 
12
12
  ## Overview
13
13
 
@@ -5,7 +5,7 @@ from pathlib import Path
5
5
 
6
6
  __all__ = ["__version__"]
7
7
 
8
- _FALLBACK_VERSION = "0.2.0b1017"
8
+ _FALLBACK_VERSION = "0.2.0b1099"
9
9
 
10
10
 
11
11
  def _resolve_local_pyproject_version() -> str | None:
@@ -203,10 +203,6 @@ class LayoutPreset(str, Enum):
203
203
  single_section = "single_section"
204
204
 
205
205
 
206
- class FlowPreset(str, Enum):
207
- basic_approval = "basic_approval"
208
- basic_fill_then_approve = "basic_fill_then_approve"
209
-
210
206
 
211
207
  class ViewsPreset(str, Enum):
212
208
  default_table = "default_table"
@@ -2342,7 +2338,6 @@ AppReadSummaryResponse = AppGetResponse
2342
2338
  AppFieldsReadResponse = AppGetFieldsResponse
2343
2339
  AppLayoutReadResponse = AppGetLayoutResponse
2344
2340
  AppViewsReadResponse = AppGetViewsResponse
2345
- AppFlowReadResponse = AppGetFlowResponse
2346
2341
  AppChartsReadResponse = AppGetChartsResponse
2347
2342
 
2348
2343
 
@@ -2432,40 +2427,6 @@ class LayoutPlanRequest(StrictModel):
2432
2427
  return payload
2433
2428
 
2434
2429
 
2435
- class FlowPlanRequest(StrictModel):
2436
- app_key: str
2437
- mode: str = "replace"
2438
- nodes: list[FlowNodePatch] = Field(default_factory=list)
2439
- transitions: list[FlowTransitionPatch] = Field(default_factory=list)
2440
- preset: FlowPreset | None = None
2441
-
2442
- @model_validator(mode="before")
2443
- @classmethod
2444
- def normalize_mode_alias(cls, value: Any) -> Any:
2445
- if not isinstance(value, dict):
2446
- return value
2447
- payload = dict(value)
2448
- if str(payload.get("mode") or "").strip().lower() == "overwrite":
2449
- payload["mode"] = "replace"
2450
- raw_preset = payload.get("preset")
2451
- if raw_preset is None and isinstance(payload.get("base_preset"), str):
2452
- raw_preset = payload["base_preset"]
2453
- payload["preset"] = raw_preset
2454
- if isinstance(raw_preset, str):
2455
- normalized_preset = raw_preset.strip().lower()
2456
- preset_aliases = {
2457
- "default_approval": FlowPreset.basic_approval.value,
2458
- "approval": FlowPreset.basic_approval.value,
2459
- "basic approval": FlowPreset.basic_approval.value,
2460
- "default_fill_then_approve": FlowPreset.basic_fill_then_approve.value,
2461
- "default-fill-then-approve": FlowPreset.basic_fill_then_approve.value,
2462
- "fill_then_approve": FlowPreset.basic_fill_then_approve.value,
2463
- }
2464
- if normalized_preset in preset_aliases:
2465
- payload["preset"] = preset_aliases[normalized_preset]
2466
- return payload
2467
-
2468
-
2469
2430
  class ViewsPlanRequest(StrictModel):
2470
2431
  app_key: str
2471
2432
  upsert_views: list[ViewUpsertPatch] = Field(default_factory=list)