@qingflow-tech/qingflow-cli 1.0.40 → 1.0.41
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/package.json +1 -1
- package/pyproject.toml +1 -1
- package/skills/qingflow-cli/SKILL.md +5 -3
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md +2 -2
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md +44 -7
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +52 -17
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +4 -3
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md +9 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_EXPLORATION_REPORT.md +1 -1
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md +1 -2
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md +2 -2
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md +2 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md +26 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md +13 -1
- package/skills/qingflow-cli/reference/charts_upsert_bar.example.json +2 -2
- package/skills/qingflow-cli/reference/charts_upsert_dashboard_starter.example.json +5 -5
- package/skills/qingflow-cli/reference/charts_upsert_minimal.example.json +1 -1
- package/skills/qingflow-cli/reference/portal_sections_five_types.example.json +21 -1
- package/skills/qingflow-cli/reference/portal_sections_standard_workbench.example.json +4 -0
- package/skills/qingflow-mcp-setup/SKILL.md +2 -0
- package/src/qingflow_mcp/builder_facade/models.py +183 -0
- package/src/qingflow_mcp/builder_facade/service.py +722 -74
- package/src/qingflow_mcp/cli/formatters.py +1 -0
- package/src/qingflow_mcp/cli/main.py +2 -0
- package/src/qingflow_mcp/response_trim.py +1 -0
- package/src/qingflow_mcp/tools/ai_builder_tools.py +388 -17
- package/src/qingflow_mcp/tools/record_tools.py +28 -2
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.0.41
|
|
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.0.41 qingflow
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
Environment:
|
package/package.json
CHANGED
package/pyproject.toml
CHANGED
|
@@ -8,9 +8,11 @@ description: |
|
|
|
8
8
|
|
|
9
9
|
# Qingflow CLI 使用技能
|
|
10
10
|
|
|
11
|
+
> **Skill 版本**:`qingflow-skills-2026.06.23.1`(入口文档版本;如需确认 CLI 包版本,使用 `qingflow --version` 或 `qingflow --json version`)。
|
|
12
|
+
|
|
11
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`。**
|
|
12
14
|
|
|
13
|
-
> **CLI**:当前验证包为 `@qingflow-tech/qingflow-cli`(查版本优先用 `qingflow --version`;需要 JSON 时用 `qingflow --json version`)。**搭建/创建/系统配置**:先区分 **完整系统/应用包** 与
|
|
15
|
+
> **CLI**:当前验证包为 `@qingflow-tech/qingflow-cli`(查版本优先用 `qingflow --version`;需要 JSON 时用 `qingflow --json version`)。**搭建/创建/系统配置**:先区分 **完整系统/应用包** 与 **单应用**。完整系统主链路必须走 `builder package apply -> builder schema apply --apps-file`,并用 `apps[].client_key + relation.target_app_ref` 处理同批跨应用关联;单应用才走 `builder schema apply --app-key` 或 `--package-id --app-name --create-if-missing`。完整系统 schema apply 超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时,下一步固定是 **`readback_before_retry`**(`package get` / `app resolve` / `app get fields`),禁止直接拆成单应用重建、用 V2/测试/随机后缀绕过重名或重放整批创建;随后再按 **[APP_DELIVERY](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)** → **[VIEWS](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)** / **[PORTAL](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)** / **[CHARTS](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)** 选读。仅成员读数速通仍可先打开 **[MEMBER_CHEATSHEET](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**。
|
|
14
16
|
|
|
15
17
|
## 关联文件
|
|
16
18
|
|
|
@@ -39,7 +41,7 @@ description: |
|
|
|
39
41
|
|
|
40
42
|
**Builder 删除回读语义**:删除类 apply 要区分 **DELETE 是否已发出** 和 **删除是否已回读确认**。若结果里有 **`delete_executed=true`**,但 **`readback_status=unavailable|still_exists`**,不要盲目重复删除;记录 **`safe_to_retry_delete=false`**,稍后用对应读取工具确认。
|
|
41
43
|
|
|
42
|
-
**Builder 写后回读语义**:`package apply/update`、`portal apply` 以及其它 builder apply 若返回 **`status=partial_success`** 且 **`write_executed=true` / `safe_to_retry=false`**,表示写动作已经发出或已成功,后续回读/发布校验可能被 40002、404
|
|
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`。
|
|
43
45
|
|
|
44
46
|
---
|
|
45
47
|
|
|
@@ -419,7 +421,7 @@ qingflow auth logout --forget-persisted
|
|
|
419
421
|
| **app / portal / view / chart** | `app list [--query 关键词]` → **`app get --app-key`**(`accessible_views` / `view_id`、`import_capability`)· `builder package list [--query 关键词]` → `builder package get --package-id` · `portal list` · `portal get --dash-key` · `view get --view-id`(只读视图元信息;`baseInfo` 或 `viewConfig` 只有 40002 / 40027 / 404 这类权限/缺失边界可用另一侧降级,非权限类后端错误不隐藏;解析 app 仅依赖同源 view/form 与可见应用树,不回退旧应用搜索)· `chart get --chart-id`(图表 `baseInfo` / 数据 / 配置分阶段读取;单个辅助阶段 40002 / 40027 / 404 只作为 warning,非权限类后端错误不隐藏) |
|
|
420
422
|
| **record** | `record schema insert`(新建记录 insert-ready schema,仅 `--app-key`)· **`browse`/`list`/`access`:`--app-key` + `--view-id`(缺一常 CONFIG)** · `record list --query ... [--query-field FIELD_ID] [--page-size N]` 用于候选定位/样本浏览 · `record get --record-id` 读详情页首屏上下文 · `record logs --record-id` 读完整数据/流程日志 JSONL · `record insert --items-file`(单条也是 items 一行)· `schema update --record-id [--view-id]` / **`update`**(单条 `--fields-file` **或** 批量 `--items-file`/`--dry-run`,二者勿混)· `export start/direct --view-id` 仅用于明确导出文件 · **`delete`/大 schema**:先 **[FIELD_DATA_TYPES](./reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md)** / **[RECORD_CREATE](./reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)** / **[RECORD_UPDATE](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**,再 `-h` |
|
|
421
423
|
| **import** | `record schema import?` · `import template` → `verify` → `repair?` → `start`(**`being-enter-auditing` 必填**)→ `status`(**三者 selector 只选一**);导入权限预检的 `baseInfo` 只有 40002 / 40027 / 404 可降级为 unknown,非权限错误不能当成无导入权或继续执行;**链路与本机目录**只靠本节不够 → **[RECORD_IMPORT](./reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)** |
|
|
422
|
-
| **builder** | **搭建/系统化配置**:先读 `builder contract`。**完整系统/应用包**:`builder package apply --config-file` → `builder schema apply --apps-file`(主写法为 `{package_id, apps}` 对象;raw apps array / singleton wrapper array 仅兼容;同批 relation
|
|
424
|
+
| **builder** | **搭建/系统化配置**:先读 `builder contract`。**完整系统/应用包**:`builder package apply --config-file` → `builder schema apply --apps-file`(主写法为 `{package_id, apps}` 对象;raw apps array / singleton wrapper array 仅兼容;同批 relation 主写 `target_app_ref` 指向 `client_key`,`target_app_key` 只用于已存在/已读回确认的目标)→ layout/views/flow/portal/charts。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先 `readback_before_retry`,不得直接拆单应用重建、重放整批或创建 V2/测试/随机后缀绕过重名。**单应用**:`app resolve/get` → `schema/layout/flow/views apply`。图标主写 `icon/color`;`icon_name/icon_color`、`icon_config`、`icon:{name,color}` 仅兼容/读回。选择字段 `options` 可用字符串数组或 `{label,value}` 对象数组。与普通读数/`record insert` 不是同一路径 → **[APP_DELIVERY](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**、[ICONS](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md)、[VIEWS](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)、[PORTAL](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)、[CHARTS](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md) |
|
|
423
425
|
| **task**(须落盘见上文) | `task list [--task-box][--flow-status][--app-key][--query] --page --page-size`(**枚举、`--query`、与 `record` 视图口径勿混**:见上文 SOP · **[TASK_CONTEXT](./reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)**)· **`get`/`log`/`report`/`action`**:默认只传 `task list` 返回的 **`data.items[].task_id`**;`report` 另须必选 **`--report-id`**;`action` **无 `--dry-run`** |
|
|
424
426
|
|
|
425
427
|
**高发必败**:旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
| 场景 | 命令 | 备注 |
|
|
12
12
|
| --------- | ------------------------------------------------ | ----------------------------------- |
|
|
13
|
-
| 查 CLI 包版本 | `
|
|
13
|
+
| 查 CLI 包版本 | `qingflow --version`;需要 JSON 用 `qingflow --json version` | 不依赖登录,不需要先查 npm 安装路径 |
|
|
14
14
|
| 帮助 | `qingflow -h`、`qingflow record schema browse -h` | 嵌套子命令勿整体加引号 |
|
|
15
15
|
|
|
16
16
|
|
|
@@ -87,7 +87,7 @@
|
|
|
87
87
|
|
|
88
88
|
## 8. 必败反例
|
|
89
89
|
|
|
90
|
-
与 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 常见踩雷、**[SKILL.md](../SKILL.md)**「命令速查」末段「必败形态」一致;**逐条 CLI 形态表**另见 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** §9
|
|
90
|
+
与 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 常见踩雷、**[SKILL.md](../SKILL.md)**「命令速查」末段「必败形态」一致;**逐条 CLI 形态表**另见 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** §9:`record list` 缺 `view-id`、子命令错引号、builder 缺 query/keyword、`import status` 多 selector。
|
|
91
91
|
|
|
92
92
|
---
|
|
93
93
|
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
>
|
|
12
12
|
> **输出口径**:builder 读取命令仍显式加 `--json`;builder 写入/apply 命令默认直接输出 JSON 到 stdout,写入/apply 示例不再额外加 `--json`。如果需要留档,用 `| tee tmp/builder_*.json`,不要用 `>` 吞掉前端可捕获的 stdout。写入结果优先读统一 envelope:`operation` 表示本次动作,`summary` 表示总数/成功失败/发布校验,`resources[]` 表示资源卡片;每个资源统一有 `resource_type`、`operation`、`status`、`id`、`key`、`name`、`ids`、`parent`、`error_code`、`message`。旧字段如 `field_diff`、`views_diff`、`chart_results` 只作兼容和排障。
|
|
13
13
|
>
|
|
14
|
-
> **写后回读**:若 builder 写入结果为 `status=partial_success`,但同时有 `write_executed=true` / `safe_to_retry=false
|
|
14
|
+
> **写后回读**:若 builder 写入结果为 `status=partial_success`,但同时有 `write_executed=true` / `safe_to_retry=false`,表示写动作已执行或可能已执行,问题在最终回读、发布校验或元数据确认。`package apply/update`、`schema apply`、`portal apply` 常见这种形态:`verification.readback_unavailable=true`、`details.*readback_error.backend_code=40002`、命令超时或响应只包含 partial/readback 不完整,都不等于写失败;下一步固定是 **`readback_before_retry`**,最终对用户应说明“写入已执行,回读待确认”,不要重复提交同一写动作。
|
|
15
15
|
> 旧的 solution/build 编排同样遵循该语义:包挂载、门户更新或门户发布之后,若只剩回读 40002,会以 `partial_success` 和 artifacts 中的 `readback_status=unavailable` 表达,不应盲目重放写动作。
|
|
16
16
|
|
|
17
17
|
---
|
|
@@ -127,9 +127,9 @@ qingflow builder schema apply \
|
|
|
127
127
|
- **数据标题必填**:最终表单必须有且仅有一个顶层可读字段标记 `as_data_title: true`;数据封面可选,必须是顶层 `attachment` 字段标记 `as_data_cover: true`。
|
|
128
128
|
- **编辑模式**:**仅** **`--app-key`**(可选改名 `--app-name`),**不要**与 `package_id` / `create_if_missing` 混用。
|
|
129
129
|
|
|
130
|
-
### 3.3
|
|
130
|
+
### 3.3 多应用一次性新建(完整系统/应用包主链路)
|
|
131
131
|
|
|
132
|
-
当用户要一次创建多个业务对象(例如花名册 + 工时表 + 项目表),或这些应用之间有互相引用关系时,不要循环调用多次 `builder schema apply
|
|
132
|
+
当用户要一次创建多个业务对象(例如花名册 + 工时表 + 项目表),或这些应用之间有互相引用关系时,不要循环调用多次 `builder schema apply`。完整系统新建的主链路就是 multi-app `apps-file`,不是“先批量试一下、慢了就拆单应用”的可选优化。用一个 `apps.json`:
|
|
133
133
|
|
|
134
134
|
```bash
|
|
135
135
|
qingflow builder schema apply \
|
|
@@ -138,7 +138,7 @@ qingflow builder schema apply \
|
|
|
138
138
|
--apps-file tmp/apps.json
|
|
139
139
|
```
|
|
140
140
|
|
|
141
|
-
`apps.json` 主写法是对象形态 `{ "package_id": 123, "apps": [...] }`。CLI 兼容 raw apps array 和 singleton wrapper array,但不作为智能体主示例;不要把多个 `{package_id, apps}` wrapper 放进数组里。每个 `apps[]` 是一个应用 schema 配置,写自己的 `client_key`、`app_name`、`icon`、`color`、`add_fields
|
|
141
|
+
`apps.json` 主写法是对象形态 `{ "package_id": 123, "apps": [...] }`。CLI 兼容 raw apps array 和 singleton wrapper array,但不作为智能体主示例;不要把多个 `{package_id, apps}` wrapper 放进数组里。每个 `apps[]` 是一个应用 schema 配置,写自己的 `client_key`、`app_name`、`icon`、`color`、`add_fields`;同批应用之间的关联字段主写 **`target_app_ref`** 指向另一个应用的 `client_key`。只有目标应用已经存在或已被读回确认时,才使用真实 `target_app_key`;不要因为同批创建时还不知道真实 `app_key` 就放弃 `target_app_ref`。写入前 CLI 会先做静态预校验,`client_key/app_name` 重复、缺少 `as_data_title`、未开 `create_if_missing`、`target_app_ref/target_app` 无法解析都会以 `MULTI_APP_STATIC_VALIDATION_FAILED` 返回,不会先创建半成品应用:
|
|
142
142
|
|
|
143
143
|
```json
|
|
144
144
|
{
|
|
@@ -175,9 +175,37 @@ qingflow builder schema apply \
|
|
|
175
175
|
|
|
176
176
|
- 返回里看 `mode=multi_app`、`apps[].app_key`、`created_app_keys` 和 `apps[].status`。
|
|
177
177
|
- 如果 CLI 看到 `[{ "package_id": 123, "apps": [...] }]`,会自动展开并返回 `APPS_FILE_WRAPPER_ARRAY_UNWRAPPED` warning;这是兼容路径,后续仍应改回对象形态。
|
|
178
|
+
- 如果返回 `MULTI_APP_STATIC_VALIDATION_FAILED`,读取 `details.issues[]` 的 `path/error_code/fix_hint` 修 payload;这是写入前失败,通常可以修正后重试,不需要 readback。
|
|
178
179
|
- 多应用 schema apply 不做事务回滚;如果部分失败,只补失败的 `apps[].row_number`,不要整批重复提交。
|
|
179
180
|
- 这个模式只负责应用壳与字段;视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
|
|
180
|
-
- 同批 `relation` 优先用 `target_app_ref` 指向 `client_key
|
|
181
|
+
- 同批 `relation` 优先用 `target_app_ref` 指向 `client_key`;`target_app` 只适合名称唯一且稳定的同批应用。不要先分别建应用、再为了补 `target_app_key` 做第二轮字段修补。
|
|
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
|
+
- 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时,先按 §3.4 读回,不要直接拆成单应用创建。
|
|
184
|
+
|
|
185
|
+
### 3.4 多应用 schema apply 超时 / partial / readback 不完整恢复
|
|
186
|
+
|
|
187
|
+
触发条件:shell/MCP 超时、响应被截断、`status=partial_success`、`write_executed=true`、`safe_to_retry=false`、`verification.readback_unavailable=true`、`created_app_keys` 不完整,或只拿到部分 `apps[].status`。
|
|
188
|
+
|
|
189
|
+
统一判定:
|
|
190
|
+
|
|
191
|
+
- 这不是“创建失败”的证据,而是 **`write_may_have_succeeded`**。
|
|
192
|
+
- 下一步固定为 **`next_action: readback_before_retry`**。
|
|
193
|
+
- 在 readback 完成前,不得重放整份 `apps-file`,不得把完整系统拆成多次单应用重建,不得创建 `V2` / `测试` / 随机后缀应用绕过重名。
|
|
194
|
+
|
|
195
|
+
读回顺序:
|
|
196
|
+
|
|
197
|
+
1. 已知 `package_id` 时先 `qingflow --json builder package get --package-id <TAG_ID>`,确认包仍可读、包内已有应用摘要。
|
|
198
|
+
2. 对每个计划内 `apps[].app_name`,用 `builder app resolve --app-name <NAME> --package-id <TAG_ID>` 定位;若响应已经给出 `apps[].app_key` / `created_app_keys`,优先用这些 key。
|
|
199
|
+
3. 对已定位应用执行 `builder app get --app-key <APP_KEY> fields`,核对标题字段、关键业务字段、relation 字段的 `target_app_key` / 显示字段。
|
|
200
|
+
4. 形成矩阵:`created_and_verified`、`created_but_readback_incomplete`、`missing`、`field_or_relation_missing`、`failed_with_error`。
|
|
201
|
+
5. 只有读回证明某个应用确实不存在或某个字段确实缺失时,才做最小修复:补缺失 app 行、补缺失字段或修 relation;不要重跑已经存在的应用。
|
|
202
|
+
|
|
203
|
+
重试/修复限制:
|
|
204
|
+
|
|
205
|
+
- 继续使用原始 `app_name` 与业务命名。重名冲突表示需要读回/更新/询问用户,不是创建 `V2` 的理由。
|
|
206
|
+
- 同批仍未创建的应用之间继续用 `client_key + target_app_ref`。只有目标应用已通过 readback 确认存在时,才可在后续修复里改用 `target_app_key`。
|
|
207
|
+
- 若 readback 证明主应用已存在但部分 relation 缺失,修 relation 前先说明数据影响:是否会清空已有值、是否需要迁移、是否可安全重试。
|
|
208
|
+
- 如果已有包内已经存在相似应用,先决定“复用/更新/新建缺失应用/询问用户”,不要用相似重名或后缀绕开。
|
|
181
209
|
|
|
182
210
|
**`visibility` JSON**(`--visibility-file`):与包/应用通用,键见契约 `allowed_values.visibility.*`:
|
|
183
211
|
|
|
@@ -269,6 +297,14 @@ qingflow builder flow apply \
|
|
|
269
297
|
|
|
270
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`**)。
|
|
271
299
|
|
|
300
|
+
智能体可优先写更自然的字段类型,工具会在写入前归一化;读回仍显示 canonical 类型:
|
|
301
|
+
|
|
302
|
+
| 智能体写法 | 内部类型 |
|
|
303
|
+
|------------|----------|
|
|
304
|
+
| `multiline` / `multiline_text` / `textarea` | `long_text` |
|
|
305
|
+
| `select` / `single_choice` / `dropdown` | `single_select` |
|
|
306
|
+
| `multi_select` / `multi_choice` / `multiple_choice` / `checkbox` | `multi_select` |
|
|
307
|
+
|
|
272
308
|
| `type` | 设置要点 |
|
|
273
309
|
|--------|----------|
|
|
274
310
|
| **`text`** | **`name`**;可选 **`required`**、**`description`**;无选项。 |
|
|
@@ -284,7 +320,7 @@ qingflow builder flow apply \
|
|
|
284
320
|
| **`address`** | 地址复合字段。 |
|
|
285
321
|
| **`attachment`** | 附件。 |
|
|
286
322
|
| **`boolean`** | 是否。 |
|
|
287
|
-
| **`relation`** | **`target_app_key
|
|
323
|
+
| **`relation`** | 单应用/已存在目标用 **`target_app_key`**;同批 multi-app 新建用 **`target_app_ref`** 指向目标 `apps[].client_key`。**`relation_mode`**:`single` \| `multiple`(**`multiple` 有风险**:多读 **`verification.relation_field_limit_verified` / MULTIPLE_RELATION_FIELDS_UNSUPPORTED**);**必须** **`display_field`** 与 **`visible_fields[]`**(**`name`** 指向目标应用字段);元数据不可查时可显式 **`display_field.name` / `visible_fields[].name`** 降级;写后读 **`details.relation_readback_matrix[]`**,不一致时按 **`details.relation_repair_plan[]`** 最小修复。 |
|
|
288
324
|
| **`subtable`** | **`subfields[]`**,子项与父级同类递归;更新已存在子列优先契约推荐的 **`update_fields[].set.subfield_updates`**(只允许 **name / required / description / 嵌套 subfield_updates**),**`set.subfields` 全量替换** 风险更高。 |
|
|
289
325
|
| **`q_linker`** | **`q_linker_binding`**:`inputs`、`request`(URL/method/headers…)、**`outputs[]`**(`alias` / `path` / **`target_field.name`**);**`target_field.type`** 限定为契约 **allowed_values** 子集。 |
|
|
290
326
|
| **`code_block`** | **`code_block_binding`**:`inputs`(**`field.name` → `var`**)、**`code`**、**`auto_trigger`**、按钮文案;**`outputs[]`** 指向 **`target_field`**;**必须** 可静态识别 **`qf_output =` 赋值**(禁止仅 `const/let qf_output`,实现会规范化);**不执行代码**,只写配置。 |
|
|
@@ -296,7 +332,7 @@ qingflow builder flow apply \
|
|
|
296
332
|
- 子表子字段不能作为标题或封面;多标题、多封面、非附件封面都会在写入前阻断。
|
|
297
333
|
- 未显式标记封面时保留/不创建封面;未能形成唯一标题时视为配置错误,不要声称应用已完整创建。
|
|
298
334
|
|
|
299
|
-
**别名**:契约 **`aliases`** 会把 `field.title` / `field.label` 等映射到 **`name`**,把 `field.type_id` 映射到 **`type`**
|
|
335
|
+
**别名**:契约 **`aliases`** 会把 `field.title` / `field.label` 等映射到 **`name`**,把 `field.type_id` 映射到 **`type`**;契约 **`allowed_values.field.type_aliases`** 会把自然字段类型映射到内部类型。主路径建议写上表自然类型,排障和读回时看 canonical 类型。
|
|
300
336
|
|
|
301
337
|
**`update_fields` 项**:**`selector`**:`que_id` 或 `field_id` 或 **`name`**;**`set`**:允许子集(**`name` / `required` / `description` / `options` / `department_scope` / … / `subfield_updates`**)。
|
|
302
338
|
|
|
@@ -426,6 +462,7 @@ qingflow builder publish verify \
|
|
|
426
462
|
## 9. 输出与排障
|
|
427
463
|
|
|
428
464
|
- **builder 写入/apply 工具默认直接输出 JSON 到 stdout**,便于前端捕获;builder 读取命令仍显式加 `--json`。需要同时留档时使用 `| tee tmp/builder_*.json`,不要用 `>` 吞掉 stdout。
|
|
465
|
+
- **schema apply 超时 / partial / write_executed 后**:先 `readback_before_retry`。尤其是完整系统 multi-app 创建,慢响应常见但可能已经落库;不要直接重放整批、拆单应用重建或用后缀应用绕过冲突。
|
|
429
466
|
- **446 / 49614**:多看契约 **execution_notes**(如 **多选关联限制**)。
|
|
430
467
|
- **40161 / 元数据不可读**:**relation / q_linker / code_block** 按上文 **显式 name / binding** 路径降级。
|
|
431
468
|
|
|
@@ -40,7 +40,7 @@ qingflow --json builder charts apply \
|
|
|
40
40
|
| 步骤 | 动作 | CLI |
|
|
41
41
|
|------|------|-----|
|
|
42
42
|
| ① 解析应用 | 确认 **`app_key`** | **`builder app resolve --app-key …`** |
|
|
43
|
-
| ② 读报表字段 | 取 **`chart_fields[]`** 中的
|
|
43
|
+
| ② 读报表字段 | 取 **`chart_fields[]`** 中的 **显示名**、**`field_id`**(如 **`field_数字`**)或 **`bi_field_id`**,供 `group_by` / `metric` / `where` 用;可直接复制 **`chart_fields[].chart_apply_examples`** 作为 apply 片段 | **`builder app get --app-key … fields`** |
|
|
44
44
|
| ③ 读现有报表 | 已有 **`chart_id`**、重名风险 | 先看 **`builder app get --app-key …`** 的 compact `charts`;不足时再用 **`builder app get --app-key … charts`** |
|
|
45
45
|
| ④ 应用变更 | upsert / remove / reorder | **`builder charts apply …`** |
|
|
46
46
|
| ⑤ 再读列表 | 确认顺序与条目 | 再次 **`builder app get --app-key …`**;需要完整报表清单时再下钻 `builder app get charts` |
|
|
@@ -54,18 +54,19 @@ qingflow --json builder charts apply \
|
|
|
54
54
|
| **`name`** | 必填;新建时即图表名;**更新**时可改名。 |
|
|
55
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
56
|
| **`chart_id`** | 可选。**有则按 id 命中更新**;无则 **按 `name` 精确匹配**:0 个 → **创建**;多个 → **歧义报错**(须带 **`chart_id`**)。 |
|
|
57
|
-
| **`
|
|
58
|
-
| **`
|
|
59
|
-
| **`filters`** | 统一固定筛选写法:**`field_name`**(可用 **`chart_fields[].title`** / **`field_id`** / **`bi_field_id
|
|
57
|
+
| **`metric`** / **`metrics`** | **主推语义指标写法**:`"count(*)"`、`"sum(金额)"`、`"avg(工时)"`、`"max(评分)"`、`"min(耗时)"`,也支持对象 `{"op":"sum","field":"金额"}`。字段必须来自 **`chart_fields[]`**。 |
|
|
58
|
+
| **`group_by`** | **主推维度写法**:字段显示名、`field_id` 或 `bi_field_id` 数组,例如 `["使用状态"]`。 |
|
|
59
|
+
| **`where`** / **`filters`** | 统一固定筛选写法:**`field`/`field_name`**(可用 **`chart_fields[].title`** / **`field_id`** / **`bi_field_id`**)+ **`op`/`operator`** + **`value`/`values`** → 写入配置 **`beforeAggregationFilterMatrix`**。 |
|
|
60
|
+
| **`dimension_field_ids`** / **`indicator_field_ids`** | 兼容/高级写法;旧 payload 可继续用,但智能体主路径优先写 `group_by` + `metric(s)`。 |
|
|
60
61
|
| **`visibility`** | 可选;编译为 QingBI **`visibleAuth`**;**仅更新 visibility** 时不重算其它授权结构(见契约)。**更新**时 **省略** 可保留原可见性。 |
|
|
61
|
-
| **`config`** | 透传高级键:`aggregate`、`beforeAggregationFilterMatrix`、`afterAggregationFilterMatrix`、`chartStyleConfigs`、`displayLimitConfig`、`rawDataConfigDTO`、`query_condition_field_ids` 等;未列键会 **merge 进根**(实现 **`_build_public_chart_config_payload
|
|
62
|
+
| **`config`** | 透传高级键:`aggregate`、`beforeAggregationFilterMatrix`、`afterAggregationFilterMatrix`、`chartStyleConfigs`、`displayLimitConfig`、`rawDataConfigDTO`、`query_condition_field_ids` 等;未列键会 **merge 进根**(实现 **`_build_public_chart_config_payload`**)。主路径不要手写 `selectedMetrics` / `xMetrics` / `leftMetrics`。 |
|
|
62
63
|
| **`question_config`** / **`user_config`** | 可选;分别 POST **`/chart/{id}/question/config`** 与 **`/user/config`**。 |
|
|
63
64
|
|
|
64
|
-
**配置是否重算**:若已存在图表且本次 **未显式**改 **`dimension_field_ids` / `indicator_field_ids` / `filters` / `config`**(Pydantic **`model_fields_set`**),实现可 **跳过** **`qingbi_report_update_config`**;**新建**总会写配置。
|
|
65
|
+
**配置是否重算**:若已存在图表且本次 **未显式**改 **`metric(s)` / `group_by` / `where` / `dimension_field_ids` / `indicator_field_ids` / `filters` / `config`**(Pydantic **`model_fields_set`**),实现可 **跳过** **`qingbi_report_update_config`**;**新建**总会写配置。
|
|
65
66
|
|
|
66
67
|
**报表筛选 operator**:推荐使用 `eq` / `neq` / `in` / `contains` / `gte` / `lte` / `is_empty` / `not_empty`;兼容 `equal` / `equals` / `=` / `!=` / `any_of` / `one_of` / `empty` 等别名。CLI 会自动转成 QingBI 字符串判断符(如 `equal`、`anyMatch`、`isNull`)和 BI 前端需要的 `judgeValue` 文本值;单选/多选筛选入参可传选项文本或 option id,CLI 会按 QingBI 路径转成文本。智能体不要手写 `judgeType`、`judgeValue`、`beforeAggregationFilterMatrix`。
|
|
67
68
|
|
|
68
|
-
**读回语义**:`builder chart get` / `chart_get` 会返回语义化 `filters
|
|
69
|
+
**读回语义**:`builder chart get` / `chart_get` 会返回语义化 `group_by`、`metrics`、`filters`;`config.*` 仅作为 raw 诊断,不作为智能体更新主输入。
|
|
69
70
|
|
|
70
71
|
示例:
|
|
71
72
|
|
|
@@ -73,17 +74,51 @@ qingflow --json builder charts apply \
|
|
|
73
74
|
{"field_name": "使用状态", "operator": "eq", "value": "正常"}
|
|
74
75
|
```
|
|
75
76
|
|
|
76
|
-
### 3.1
|
|
77
|
+
### 3.1 推荐语义写法
|
|
77
78
|
|
|
78
|
-
|
|
79
|
+
指标卡:
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{"name": "正常设备数", "chart_type": "target", "metric": "count(*)", "where": [{"field": "使用状态", "op": "eq", "value": "正常"}]}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
字段聚合:
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{"name": "维修费用总额", "chart_type": "target", "metric": "sum(维修费用)"}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
分组图表:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{"name": "设备状态分布", "chart_type": "bar", "group_by": ["使用状态"], "metric": "count(*)"}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
双轴图:
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{"name": "预算执行对比", "chart_type": "dualaxes", "group_by": ["月份"], "left_metric": "sum(预算金额)", "right_metric": "sum(实际金额)"}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
字段发现返回的 `chart_fields[].chart_apply_examples` 会给出同样语义的可复制片段:
|
|
104
|
+
|
|
105
|
+
- `count_by_field`:按该字段分组计数,适合 bar/columnar/pie 类分布图。
|
|
106
|
+
- `filtered_count`:按该字段固定筛选后计数,适合 target/indicator 指标卡。
|
|
107
|
+
- `sum_metric`:仅数值字段提供,适合金额/数量/工时等合计指标卡。
|
|
108
|
+
|
|
109
|
+
拿到片段后只改 `name`、`chart_type` 和筛选值即可,不要改写成 `indicator_field_ids` / `config.aggregate` / `selectedMetrics`。
|
|
110
|
+
|
|
111
|
+
### 3.2 BI 类型与后端字段映射
|
|
112
|
+
|
|
113
|
+
CLI 对外推荐使用 **`group_by` + `metric(s)`**;旧的 **`dimension_field_ids`** 和 **`indicator_field_ids`** 仍兼容。字段来源必须是 **`app_get_fields.chart_fields`** 的 QingBI datasource 字段。部分 QingBI 类型后端字段槽位不同,CLI 会自动转换:
|
|
79
114
|
|
|
80
115
|
| `chart_type` | 后端要求 | CLI 处理 |
|
|
81
116
|
|--------------|----------|----------|
|
|
82
|
-
| **`summary`** | `xDimensions` / `yDimensions` + `selectedMetrics` | `
|
|
83
|
-
| **`scatter`** | `selectedDimensions` + 单个 `xMetrics` + 单个 `yMetrics` | `
|
|
84
|
-
| **`dualaxes`** | `selectedDimensions` + `leftMetrics` / `rightMetrics` | `
|
|
85
|
-
| **`gauge`** | 无维度,且必须有两个不重复指标 |
|
|
86
|
-
| **`histogram`** | 最多 1 个维度,且必须 1 个普通数值指标 | 不能省略指标,不能使用默认 **`数据总量`** / count
|
|
117
|
+
| **`summary`** | `xDimensions` / `yDimensions` + `selectedMetrics` | `rows` 写入 `xDimensions`,`columns` 写入 `yDimensions`,`metrics` 写入 `selectedMetrics`。 |
|
|
118
|
+
| **`scatter`** | `selectedDimensions` + 单个 `xMetrics` + 单个 `yMetrics` | `x_metric` / `y_metric` 分别写入 X/Y;也兼容 `metrics` 前两个。 |
|
|
119
|
+
| **`dualaxes`** | `selectedDimensions` + `leftMetrics` / `rightMetrics` | `left_metric` / `right_metric` 分别写入左/右轴;也兼容 `metrics` 前两个。 |
|
|
120
|
+
| **`gauge`** | 无维度,且必须有两个不重复指标 | `value_metric` / `target_metric` 为主;只给一个真实指标时,第二指标自动补 **`数据总量`**。 |
|
|
121
|
+
| **`histogram`** | 最多 1 个维度,且必须 1 个普通数值指标 | 不能省略指标,不能使用默认 **`数据总量`** / count,不能使用文本字段或聚合公式字段;推荐 `metric: "sum(数值字段)"` 或 `metric: "avg(数值字段)"`。 |
|
|
87
122
|
| **`heatmap`** | 2 个维度 + 1 个指标 | 不满足时 CLI 会提前返回 `diagnostics`,不要等后端裸 810xx。 |
|
|
88
123
|
| **`waterfall` / `map`** | 1 个维度 + 1 个指标 | `map` 的维度应选位置/地区含义字段。 |
|
|
89
124
|
| **`treemap`** | 1-2 个维度 + 1 个指标 | 维度过少/过多都会被前置校验。 |
|
|
@@ -96,7 +131,7 @@ CLI 对外仍推荐使用通用字段:**`dimension_field_ids`** 和 **`indicat
|
|
|
96
131
|
- **`81005`** 通常会翻译为 `CHART_FIELD_ID_REPEAT`,代表某个维度/指标槽位里出现重复 `fieldId`。
|
|
97
132
|
- `diagnostics.next_action` 是下一步修复建议;不要只把裸后端码返回给用户。
|
|
98
133
|
|
|
99
|
-
### 3.
|
|
134
|
+
### 3.3 应用源报表 vs 数据集报表
|
|
100
135
|
|
|
101
136
|
- **应用源 BI 报表**:使用 `builder charts apply` 创建/更新,配置里保持 `dataSourceType=qingflow`。
|
|
102
137
|
- **数据集 BI 报表**:当前 CLI 不创建、不编辑;只能在已有报表基础上,用 `builder associated-resource apply` 关联到应用,传 `report_source: "dataset"`。
|
|
@@ -104,7 +139,7 @@ CLI 对外仍推荐使用通用字段:**`dimension_field_ids`** 和 **`indicat
|
|
|
104
139
|
|
|
105
140
|
---
|
|
106
141
|
|
|
107
|
-
## 3.
|
|
142
|
+
## 3.4 已有报表局部更新:`patch_charts`
|
|
108
143
|
|
|
109
144
|
`patch_charts` 用于已有报表的小参数替换,工具会读当前 base/config、合并 `set/unset`,再按后端要求保存整份配置。
|
|
110
145
|
|
|
@@ -171,7 +206,7 @@ CLI 对外仍推荐使用通用字段:**`dimension_field_ids`** 和 **`indicat
|
|
|
171
206
|
|
|
172
207
|
| 操作 | 载荷要点 | 结果 |
|
|
173
208
|
|------|-----------|------|
|
|
174
|
-
| 新建 **bar** | **`
|
|
209
|
+
| 新建 **bar** | **`group_by`: [`状态`]**,**`metric`: `sum(金额)`** | **`chart_id`: `mcp_3a35981aff4f4f57`**,`status: created`,**`verified: true`** |
|
|
175
210
|
| **更新** | 同上 id,**`name`** 改为 **`CLI图表探针_柱状_已改名`**,补 **`visibility`** workspace | **`status: updated`**,**`verified: true`** |
|
|
176
211
|
| **reorder** | **`[mcp_3a35981aff4f4f57, mcp_fb104267c5c249ca]`** | **`success`**,**`chart_order_verified: true`** |
|
|
177
212
|
|
|
@@ -96,7 +96,7 @@ qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
|
|
|
96
96
|
|
|
97
97
|
mobile 写法固定按 **6 栅格**:通常 **`x=0, cols=6`**。如果只写了 PC position,CLI 会自动补 mobile position,并返回 **`PORTAL_MOBILE_POSITION_MISSING`** 提醒。
|
|
98
98
|
|
|
99
|
-
图表卡片过小时会返回 **`PORTAL_CHART_CARD_TOO_SMALL`**;指标卡按 **`pc.cols >= 6, pc.rows >= 5`** 校验,普通可视化图表按 **`pc.cols >= 8, pc.rows >= 7`**
|
|
99
|
+
图表卡片过小时会返回 **`PORTAL_CHART_CARD_TOO_SMALL`**;指标卡按 **`pc.cols >= 6, pc.rows >= 5`** 校验,普通可视化图表按 **`pc.cols >= 8, pc.rows >= 7`** 校验。指标区图表建议写 `role: "metric"`;此时必须引用 `target` / `indicator` 图表,否则返回 **`PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH`**,应先用 `app_charts_apply` 创建缺失指标卡再组门户。标准工作台数量也会进入 `layout_diagnostics.standard_template_counts`:指标卡推荐 4-6 个、BI 图表 2-3 个、业务视图 1-2 个,超出或不足会返回 `PORTAL_STANDARD_*_COUNT_OUT_OF_RANGE`。
|
|
100
100
|
|
|
101
101
|
### 3.1.2 推荐门户模板:业务工作台
|
|
102
102
|
|
|
@@ -105,7 +105,7 @@ mobile 写法固定按 **6 栅格**:通常 **`x=0, cols=6`**。如果只写了
|
|
|
105
105
|
| 区域 | 推荐组件 | PC 布局 | 要点 |
|
|
106
106
|
|------|----------|---------|------|
|
|
107
107
|
| 顶部业务入口 | **`grid`** + 可选 **待办 `task`** | `grid x=0,y=0,cols=12,rows=4`;待办 `x=12,y=0,cols=12,rows=4` | `grid` 放 2-6 个核心业务入口;待办用于当前用户任务概览。当前公开 `portal apply --sections-file` 暂未支持 `source_type=task`,不要伪造;见下方边界说明。 |
|
|
108
|
-
| 核心指标 | **`chart`** 指标卡 | 4 张:`x=0/6/12/18,y=4,cols=6,rows=5` | 指标卡推荐高度 **5**。24 栅格下单卡最小 `cols=6`,所以一行 4 张最稳;如果要 5 个指标,拆成两行。 |
|
|
108
|
+
| 核心指标 | **`chart`** 指标卡 + `role: "metric"` | 4 张:`x=0/6/12/18,y=4,cols=6,rows=5` | 指标卡推荐高度 **5**。24 栅格下单卡最小 `cols=6`,所以一行 4 张最稳;如果要 5 个指标,拆成两行。 |
|
|
109
109
|
| BI 可视化 | **`chart`** 图表 | 3 张:`x=0/8/16,y=9,cols=8,rows=7`;或 2 张:`x=0/12,cols=12,rows=7` | 可视化图表推荐高度 **7**,一行 2-3 个,1-2 行。 |
|
|
110
110
|
| 业务数据视图 | **`view`** | `x=0/12,y=16,cols=12,rows=11`;或单表 `cols=24,rows=11` | 数据视图推荐高度 **11**,一行 1-2 个,1-2 行。只挂业务视图,不要创建或引用默认的 **全部数据 / 我的数据** 当主门户视图。 |
|
|
111
111
|
|
|
@@ -116,6 +116,7 @@ mobile 固定按 **6 栅格** 从上到下堆叠:通常所有组件 `x=0, cols
|
|
|
116
116
|
- 公开 `sections-file` 稳定支持:**`grid` / `chart` / `view` / `text` / `link`**;`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理,不作为主路径。
|
|
117
117
|
- **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状,不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`;只有工具后续显式支持 `task`,或维护者走 raw 门户写入链路时,才使用待办槽位。
|
|
118
118
|
- 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)**。该示例使用当前公开 CLI 可稳定写入的组件,顶部先用一个业务入口 `grid` 占满 24 栅格;如果工具已支持待办组件,再把顶部拆成 `grid cols=12 + task cols=12`。
|
|
119
|
+
- `grid` 必须写 **`config.items[]`**;只写 `gridTitle` / `beingShowTitle` 会生成空入口容器,工具会返回 **`PORTAL_GRID_ITEMS_EMPTY`**。
|
|
119
120
|
|
|
120
121
|
**待办组件 raw 形状参考**(仅用于工具实现对齐,当前不要作为 `--sections-file` 输入):
|
|
121
122
|
|
|
@@ -170,7 +171,7 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart_ref`**;**view**
|
|
|
170
171
|
|
|
171
172
|
### 3.5 **`grid` / `text` / `link` / `view`**
|
|
172
173
|
|
|
173
|
-
- **grid**:**`config`** 并入 **`
|
|
174
|
+
- **grid**:**`config`** 并入 **`gridConfig`**;业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`。空 `config` 或空 `items` 只会生成空入口容器,并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
|
|
174
175
|
- **text** / **link**:**`text`** / **`url`** 必填。
|
|
175
176
|
- **view**:**`view_ref`**;**`view_key`** 来自 **`builder app get views`**。
|
|
176
177
|
|
|
@@ -71,6 +71,15 @@ qingflow --json record list \
|
|
|
71
71
|
|
|
72
72
|
列表默认最多返回 10 条,行数据常见于 `$.data.items`;每条一般有 `record_id`(及业务字段键值)。需要调整样本量时加 `--page-size <N>`;它只影响浏览/候选定位样本,不替代分析取数。响应会给出总数/下一步建议;如果是模糊定位,优先看 `lookup.total_count`、`lookup.next_action`。
|
|
73
73
|
|
|
74
|
+
`record_list.data.items[]` 是**字段平铺行对象**,不是 `fields[]` 数组。定位候选或做名称到记录 ID 映射时直接读字段标题键:
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
rows = payload["data"]["items"]
|
|
78
|
+
name_to_record_id = {row["客户名称"]: row["record_id"] for row in rows}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
只有 `record_get` 详情使用 `fields[]` 来表示字段列表。
|
|
82
|
+
|
|
74
83
|
**模糊定位示例**:
|
|
75
84
|
|
|
76
85
|
```bash
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
| `builder member search` | 必须 `--query` |
|
|
29
29
|
| `builder role search` | 必须 `--keyword` |
|
|
30
30
|
|
|
31
|
-
自动化里读取命令优先使用根级 JSON 形态:`qingflow --json ...`;builder 写入/apply 命令默认只输出 JSON,不需要额外选择格式。builder apply 响应统一优先读 `operation + summary + resources[]`,其中 `resources[].id/key/name/ids/parent` 是 UI
|
|
31
|
+
自动化里读取命令优先使用根级 JSON 形态:`qingflow --json ...`;builder 写入/apply 命令默认只输出 JSON,不需要额外选择格式。builder apply 响应统一优先读 `operation + summary + resources[]`,其中 `resources[].id/key/name/ids/parent` 是 UI/智能体展示资源的稳定入口;旧字段只作兼容和排障。查 CLI 包版本直接用 `qingflow --version`;需要结构化输出时用 `qingflow --json version`。
|
|
32
32
|
|
|
33
33
|
---
|
|
34
34
|
|
|
@@ -76,7 +76,7 @@ qingflow --json record list \
|
|
|
76
76
|
|
|
77
77
|
| 场景 | 命令 | 说明 |
|
|
78
78
|
| ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
79
|
-
| CLI 版本 | `
|
|
79
|
+
| CLI 版本 | `qingflow --version`;需要 JSON 用 `qingflow --json version` | 不依赖登录,不需要先查 npm 安装路径。 |
|
|
80
80
|
| 帮助 | `qingflow -h`、`qingflow record schema browse -h` | 嵌套子命令勿整体加引号。 |
|
|
81
81
|
| 身份与租户 | `qingflow --json auth whoami` | 用 `selected_ws_id` / `selectedWsId` 当作当前工作区。 |
|
|
82
82
|
| 工作区只读 | `qingflow --json workspace get --ws-id <WS_ID>` | `WS_ID` 与 whoami 一致最稳。 |
|
|
@@ -135,7 +135,6 @@ qingflow --json record list \
|
|
|
135
135
|
|
|
136
136
|
| 错误 | 原因 |
|
|
137
137
|
| ------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
138
|
-
| `qingflow --version` | 根解析器无此参数。 |
|
|
139
138
|
| `record list` 无 `--view-id` | `CONFIG_ERROR` / `requires view_id`。 |
|
|
140
139
|
| **用 `custom:1`、`custom:12`** 等(`custom:` 后**仅数字**)作普通成员的主读数视图 | 实测 **browse/list/access 一律 40038**,与业务空数据不同,**换源时请跳过**该类 id。 |
|
|
141
140
|
| `builder member search` 无 `--query` | `MEMBER_QUERY_REQUIRED`。 |
|
|
@@ -18,7 +18,8 @@
|
|
|
18
18
|
|
|
19
19
|
| 场景 | 一次成功写法 | 说明 |
|
|
20
20
|
| --------- | -------------------------------------------------------- | -------------------------------------------- |
|
|
21
|
-
| 查 CLI 包版本 | `
|
|
21
|
+
| 查 CLI 包版本 | `qingflow --version` | 不依赖登录;只输出版本号。 |
|
|
22
|
+
| 查 CLI 包版本(JSON) | `qingflow --json version` | 不依赖登录;返回 `version` 与 `package`。 |
|
|
22
23
|
| 看顶层能力 | `qingflow -h` | 确认子命令集合。 |
|
|
23
24
|
| 看某子命令帮助 | `qingflow <子命令> -h` 或 `qingflow record schema browse -h` | 嵌套子命令**不要**整体加引号。 |
|
|
24
25
|
|
|
@@ -134,7 +135,6 @@
|
|
|
134
135
|
|
|
135
136
|
| 错误写法 | 原因 |
|
|
136
137
|
| --------------------------------------------------- | ----------------------------------------------- |
|
|
137
|
-
| `qingflow --version` | 根级无 `--version`。 |
|
|
138
138
|
| `qingflow record list --app-key xxx`(无 `--view-id`) | 运行时常报错:`requires view_id`。 |
|
|
139
139
|
| `"qingflow record schema browse" --app-key ...` | 子命令被整体加引号,解析器不认。 |
|
|
140
140
|
| `builder member search`(无 `--query`) | 常见:`MEMBER_QUERY_REQUIRED` / query is required。 |
|
|
@@ -13,4 +13,6 @@ qingflow --json record insert --app-key <APP_KEY> --items-file tmp/records.json
|
|
|
13
13
|
|
|
14
14
|
不要用 `record schema applicant` 代替 `record_insert_schema_get` 的主路径;新建记录需要 insert-ready schema 里的 `required_fields`、`optional_fields`、`payload_template`、`format_hint` 和 `example_value`。
|
|
15
15
|
|
|
16
|
+
成员、部门、关联记录、选项、附件等特殊字段按 `qingflow-record-insert` 的 **Special Field Write Cheatsheet** 写:先读 insert schema;部门/成员不能自造候选;关联记录批量写入优先 `record_id`,自然名称只在唯一匹配时使用;附件先上传再写返回值。
|
|
17
|
+
|
|
16
18
|
录入数据时不要填写轻流系统字段:`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。这些字段由平台生成;需要确认时在创建成功后读取记录详情,不要把它们写进 `fields` / `items[].fields`。
|
|
@@ -49,6 +49,32 @@ CLI 注册见全局包 **`qingflow_mcp/cli/commands/imports.py`**(`template` /
|
|
|
49
49
|
|
|
50
50
|
## 4. 命令要点
|
|
51
51
|
|
|
52
|
+
### 4.0 文件形态、CSV 源数据与字段映射
|
|
53
|
+
|
|
54
|
+
- 当前 `import verify/start` 主链路面向官方 Excel 模板(`.xlsx` / `.xls`),不是直接把任意 CSV 交给后端。
|
|
55
|
+
- CSV 可以作为源数据或中间表,但必须先映射到官方模板列名,再写入模板副本;不要改模板表头。
|
|
56
|
+
- 字段映射以 `record schema import` / 模板列为准:源列名可以是用户习惯名,目标列名必须是官方模板 header。
|
|
57
|
+
- 关联字段批量导入优先使用稳定 `record_id` 或 schema 明确支持的唯一搜索值;显示名可能重复时不要猜。
|
|
58
|
+
- 成员/部门字段必须使用 schema/candidate 范围内的值;选项字段优先使用模板里的选项文案。
|
|
59
|
+
|
|
60
|
+
CSV 源数据示例(规划用):
|
|
61
|
+
|
|
62
|
+
```csv
|
|
63
|
+
客户名称,关联客户,状态,负责人
|
|
64
|
+
上海示例客户,CUST_RECORD_ID_001,有效,张三
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
映射到模板后的行语义:
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"客户名称": "上海示例客户",
|
|
72
|
+
"关联客户": "CUST_RECORD_ID_001",
|
|
73
|
+
"状态": "有效",
|
|
74
|
+
"负责人": "张三"
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
52
78
|
### 4.1 模板
|
|
53
79
|
|
|
54
80
|
```bash
|
package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md
CHANGED
|
@@ -35,6 +35,18 @@
|
|
|
35
35
|
|
|
36
36
|
**`relation_mode`**:仅 **`relation`** 使用,取值为 **`single`** 或 **`multiple`**(多关联字段能力受 **`verification.relation_field_limit_verified`** 等约束,见交付文 §6)。
|
|
37
37
|
|
|
38
|
+
### 1.1 智能体友好字段类型别名
|
|
39
|
+
|
|
40
|
+
主路径可以写更符合直觉的字段类型;工具写入前自动归一化,读回和排障时仍使用 canonical 类型:
|
|
41
|
+
|
|
42
|
+
| 智能体写法 | canonical 类型 |
|
|
43
|
+
|------------|----------------|
|
|
44
|
+
| `multiline` / `multiline_text` / `textarea` | `long_text` |
|
|
45
|
+
| `select` / `single_choice` / `dropdown` | `single_select` |
|
|
46
|
+
| `multi_select` / `multi_choice` / `multiple_choice` / `checkbox` | `multi_select` |
|
|
47
|
+
|
|
48
|
+
完整映射以 `builder contract --tool-name app_schema_apply` 的 `allowed_values.field.type_aliases` 为准。
|
|
49
|
+
|
|
38
50
|
---
|
|
39
51
|
|
|
40
52
|
## 2. 按类型的必填 / 常用可选(写意图)
|
|
@@ -48,7 +60,7 @@
|
|
|
48
60
|
| `q_linker` | **`q_linker_binding`**:`inputs`、`request`、**`outputs[]` 每项须含 `target_field`**(能解析到本表单字段) | `request.url` 等须符合**租户/后端远程查询策略**;读回 JSON 可能**缺** `outputs[].target_field`,会导致本地再编译失败(见 §5) |
|
|
49
61
|
| `code_block` | **`code_block_binding`**:`inputs`、`code`、**`outputs[]` + `target_field`**;代码体须能被规范识别 **`qf_output` 赋值** | **`auto_trigger`**、按钮文案;勿与 **`code_block_config.code_content`** 与 **`binding.code`** 冲突 |
|
|
50
62
|
|
|
51
|
-
别名:契约会把 `title`/`label` 映射到 **`name`**
|
|
63
|
+
别名:契约会把 `title`/`label` 映射到 **`name`** 等;字段类型自然别名见 §1.1。
|
|
52
64
|
|
|
53
65
|
---
|
|
54
66
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
{
|
|
3
3
|
"name": "数据总量",
|
|
4
4
|
"chart_type": "target",
|
|
5
|
-
"
|
|
5
|
+
"metric": "count(*)",
|
|
6
6
|
"visibility": {
|
|
7
7
|
"mode": "workspace",
|
|
8
8
|
"selectors": {},
|
|
@@ -13,8 +13,8 @@
|
|
|
13
13
|
{
|
|
14
14
|
"name": "按状态分布",
|
|
15
15
|
"chart_type": "bar",
|
|
16
|
-
"
|
|
17
|
-
"
|
|
16
|
+
"group_by": ["REPLACE_WITH_STATUS_FIELD_NAME"],
|
|
17
|
+
"metric": "count(*)",
|
|
18
18
|
"visibility": {
|
|
19
19
|
"mode": "workspace",
|
|
20
20
|
"selectors": {},
|
|
@@ -25,8 +25,8 @@
|
|
|
25
25
|
{
|
|
26
26
|
"name": "按时间趋势",
|
|
27
27
|
"chart_type": "line",
|
|
28
|
-
"
|
|
29
|
-
"
|
|
28
|
+
"group_by": ["REPLACE_WITH_DATE_FIELD_NAME"],
|
|
29
|
+
"metric": "count(*)",
|
|
30
30
|
"visibility": {
|
|
31
31
|
"mode": "workspace",
|
|
32
32
|
"selectors": {},
|
|
@@ -37,7 +37,27 @@
|
|
|
37
37
|
},
|
|
38
38
|
"config": {
|
|
39
39
|
"gridTitle": "业务入口",
|
|
40
|
-
"beingShowTitle": true
|
|
40
|
+
"beingShowTitle": true,
|
|
41
|
+
"items": [
|
|
42
|
+
{
|
|
43
|
+
"type": 1,
|
|
44
|
+
"jumpMode": 1,
|
|
45
|
+
"linkAppKey": "APP_KEY_MAIN",
|
|
46
|
+
"linkFormType": 1,
|
|
47
|
+
"title": "核心业务",
|
|
48
|
+
"customTitle": "核心业务",
|
|
49
|
+
"beingCustomTitle": false
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
"type": 1,
|
|
53
|
+
"jumpMode": 1,
|
|
54
|
+
"linkAppKey": "APP_KEY_TASK",
|
|
55
|
+
"linkFormType": 1,
|
|
56
|
+
"title": "待处理业务",
|
|
57
|
+
"customTitle": "待处理业务",
|
|
58
|
+
"beingCustomTitle": false
|
|
59
|
+
}
|
|
60
|
+
]
|
|
41
61
|
}
|
|
42
62
|
},
|
|
43
63
|
{
|