@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.
- package/README.md +2 -2
- package/npm/bin/qingflow.mjs +32 -1
- package/npm/lib/runtime.mjs +43 -2
- package/package.json +1 -1
- package/pyproject.toml +1 -1
- package/skills/qingflow-cli/SKILL.md +8 -2
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md +13 -6
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +17 -2
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md +4 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md +4 -2
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md +1 -1
- package/skills/qingflow-cli/scripts/validate_qingflow_output_files.py +87 -0
- package/skills/qingflow-mcp-setup/SKILL.md +1 -1
- package/src/qingflow_mcp/__init__.py +1 -1
- package/src/qingflow_mcp/builder_facade/models.py +0 -39
- package/src/qingflow_mcp/builder_facade/service.py +532 -859
- package/src/qingflow_mcp/builder_facade/workflow_spec.py +111 -0
- package/src/qingflow_mcp/cli/commands/builder.py +44 -12
- package/src/qingflow_mcp/cli/main.py +4 -6
- package/src/qingflow_mcp/public_surface.py +2 -0
- package/src/qingflow_mcp/server_app_builder.py +16 -8
- package/src/qingflow_mcp/solution/compiler/__init__.py +1 -3
- package/src/qingflow_mcp/solution/executor.py +3 -133
- package/src/qingflow_mcp/tools/ai_builder_tools.py +177 -241
- package/src/qingflow_mcp/tools/solution_tools.py +30 -2
- package/src/qingflow_mcp/tools/workflow_tools.py +3 -31
- package/src/qingflow_mcp/version.py +71 -1
- 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
|
|
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
|
|
12
|
+
npx -y -p @qingflow-tech/qingflow-cli@1.1.0 qingflow
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
Environment:
|
package/npm/bin/qingflow.mjs
CHANGED
|
@@ -1,6 +1,37 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import
|
|
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") {
|
package/npm/lib/runtime.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
package/pyproject.toml
CHANGED
|
@@ -8,7 +8,7 @@ description: |
|
|
|
8
8
|
|
|
9
9
|
# Qingflow CLI 使用技能
|
|
10
10
|
|
|
11
|
-
> **Skill 版本**:`qingflow-skills-2026.06.24.
|
|
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`):与包/应用通用,键见契约
|
|
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`** 取值来自契约
|
|
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`**;契约
|
|
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` 的
|
|
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`
|
|
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
|
|
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`。
|
package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md
CHANGED
|
@@ -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` 的
|
|
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.
|
|
10
|
+
> **Skill 版本**:`qingflow-skills-2026.06.24.2`(入口文档版本;如需确认 CLI 包版本,使用 `qingflow --version` 或 `qingflow --json version`)。
|
|
11
11
|
|
|
12
12
|
## Overview
|
|
13
13
|
|
|
@@ -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)
|