@qingflow-tech/qingflow-cli 1.0.11 → 1.0.12
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 +8 -4
- package/docs/local-agent-install.md +54 -3
- package/entry_point.py +1 -1
- package/npm/bin/qingflow-skills.mjs +5 -0
- package/npm/bin/qingflow.mjs +7 -2
- package/npm/lib/runtime.mjs +304 -13
- package/npm/scripts/postinstall.mjs +1 -5
- package/package.json +3 -2
- package/pyproject.toml +1 -1
- package/skills/qingflow-cli/SKILL.md +431 -0
- package/skills/qingflow-cli/manifest.yaml +10 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md +94 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md +432 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +177 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md +119 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +200 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md +288 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md +40 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md +129 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_EXPLORATION_REPORT.md +84 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md +129 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md +196 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md +159 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md +14 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md +150 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md +163 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md +95 -0
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md +150 -0
- package/skills/qingflow-cli/reference/_batch_schema_complex.json +18 -0
- package/skills/qingflow-cli/reference/_batch_schema_scalar.json +17 -0
- package/skills/qingflow-cli/reference/charts_remove.example.json +1 -0
- package/skills/qingflow-cli/reference/charts_reorder.example.json +1 -0
- package/skills/qingflow-cli/reference/charts_upsert_bar.example.json +8 -0
- package/skills/qingflow-cli/reference/charts_upsert_dashboard_starter.example.json +37 -0
- package/skills/qingflow-cli/reference/charts_upsert_minimal.example.json +13 -0
- package/skills/qingflow-cli/reference/portal_sections_all_types.example.json +131 -0
- package/skills/qingflow-cli/reference/portal_sections_five_types.example.json +106 -0
- package/skills/qingflow-cli/reference/schema_add_fields_minimal.example.json +7 -0
- package/skills/qingflow-cli/reference/schema_apply_add_fields_all_types.json +78 -0
- package/skills/qingflow-cli/reference/views_upsert_table_minimal.example.json +7 -0
- package/skills/qingflow-cli/scripts/builder-package-from-app-list.py +140 -0
- package/skills/qingflow-cli/scripts/find-app-by-keyword.py +132 -0
- package/skills/qingflow-mcp-setup/SKILL.md +113 -0
- package/skills/qingflow-mcp-setup/agents/openai.yaml +4 -0
- package/skills/qingflow-mcp-setup/references/claude-desktop.md +34 -0
- package/skills/qingflow-mcp-setup/references/environments.md +62 -0
- package/skills/qingflow-mcp-setup/references/generic-stdio.md +32 -0
- package/skills/qingflow-mcp-setup/scripts/check_local_server.sh +38 -0
- package/src/qingflow_mcp/__main__.py +6 -2
- package/src/qingflow_mcp/builder_facade/service.py +1488 -288
- package/src/qingflow_mcp/cli/commands/builder.py +2 -2
- package/src/qingflow_mcp/cli/commands/exports.py +2 -2
- package/src/qingflow_mcp/cli/commands/imports.py +1 -1
- package/src/qingflow_mcp/cli/commands/record.py +39 -11
- package/src/qingflow_mcp/cli/context.py +0 -3
- package/src/qingflow_mcp/cli/formatters.py +206 -7
- package/src/qingflow_mcp/cli/main.py +47 -3
- package/src/qingflow_mcp/errors.py +43 -2
- package/src/qingflow_mcp/public_surface.py +21 -15
- package/src/qingflow_mcp/response_trim.py +68 -13
- package/src/qingflow_mcp/server.py +11 -9
- package/src/qingflow_mcp/server_app_builder.py +3 -2
- package/src/qingflow_mcp/server_app_user.py +15 -13
- package/src/qingflow_mcp/solution/executor.py +112 -15
- package/src/qingflow_mcp/tools/ai_builder_tools.py +36 -11
- package/src/qingflow_mcp/tools/app_tools.py +184 -43
- package/src/qingflow_mcp/tools/approval_tools.py +196 -34
- package/src/qingflow_mcp/tools/auth_tools.py +92 -16
- package/src/qingflow_mcp/tools/code_block_tools.py +296 -39
- package/src/qingflow_mcp/tools/custom_button_tools.py +64 -10
- package/src/qingflow_mcp/tools/directory_tools.py +236 -72
- package/src/qingflow_mcp/tools/export_tools.py +230 -33
- package/src/qingflow_mcp/tools/file_tools.py +7 -3
- package/src/qingflow_mcp/tools/import_tools.py +293 -40
- package/src/qingflow_mcp/tools/navigation_tools.py +91 -12
- package/src/qingflow_mcp/tools/package_tools.py +118 -6
- package/src/qingflow_mcp/tools/portal_tools.py +39 -3
- package/src/qingflow_mcp/tools/qingbi_report_tools.py +116 -7
- package/src/qingflow_mcp/tools/record_tools.py +1042 -338
- package/src/qingflow_mcp/tools/resource_read_tools.py +188 -39
- package/src/qingflow_mcp/tools/role_tools.py +80 -9
- package/src/qingflow_mcp/tools/solution_tools.py +57 -15
- package/src/qingflow_mcp/tools/task_context_tools.py +569 -119
- package/src/qingflow_mcp/tools/task_tools.py +113 -29
- package/src/qingflow_mcp/tools/view_tools.py +106 -3
- package/src/qingflow_mcp/tools/workflow_tools.py +17 -1
- package/src/qingflow_mcp/tools/workspace_tools.py +71 -3
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# Qingflow CLI 各场景「一次即可跑通」命令速查表
|
|
2
|
+
|
|
3
|
+
> **面向普通/基本成员账号时**:更易踩 **应用搜索/import/角色检索** 等权限类失败,请先读 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**(策略与最短读数路径);**管理向差异**参阅 **[QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
|
|
4
|
+
|
|
5
|
+
> **本文档目的**:按**场景**给出**形态正确、参数闭合**时的命令模板,便于复制后替换占位符即跑,减少「缺参 / 引号 / 根级选项」类返工。
|
|
6
|
+
> **不是**「任何账号、任何租户、任何时刻都 100% HTTP 200」——若遇 `59004`(流币/AI 配额)、401、或目标资源不存在,仍可能失败;那种情况属于**环境与权限**,不是本表要解决的「命令写对一次成」问题。
|
|
7
|
+
|
|
8
|
+
**统一建议**
|
|
9
|
+
|
|
10
|
+
- 自动化读取命令优先加 `**--json`**;builder 写入/apply 命令默认只输出 JSON,不需要额外选择格式;展示写入结果时优先读 `operation + summary + resources[]`,不要按不同工具分别解析旧字段。
|
|
11
|
+
- 需要稳定 profile 时加 `**--profile default`**(或与你的会话一致的名字)。
|
|
12
|
+
- `task` / `record` 的大 JSON 查询类输出,按团队规范**落盘**(例如 `> tmp/qingflow_*.json`),本表为简洁只写核心参数。
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. 元:版本与帮助(不依赖登录)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
| 场景 | 一次成功写法 | 说明 |
|
|
20
|
+
| --------- | -------------------------------------------------------- | -------------------------------------------- |
|
|
21
|
+
| 查 CLI 包版本 | `npm ls -g @qingflow-tech/qingflow-cli` 或 `which qingflow` | **勿用** `qingflow --version`:根解析器无该 flag,会失败。 |
|
|
22
|
+
| 看顶层能力 | `qingflow -h` | 确认子命令集合。 |
|
|
23
|
+
| 看某子命令帮助 | `qingflow <子命令> -h` 或 `qingflow record schema browse -h` | 嵌套子命令**不要**整体加引号。 |
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 2. 会话恢复(仅业务命令失败后使用)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
| 场景 | 一次成功写法 | 必填/注意 |
|
|
32
|
+
| ------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
33
|
+
| 查看当前会话 | `qingflow --json auth whoami` | 仅在业务命令提示会话不可用、账号不确定或需要排障时使用;不要作为每个任务的首步。 |
|
|
34
|
+
| Credential 登录(自动化) | `echo "$QINGFLOW_CREDENTIAL" | qingflow --profile default auth use-credential --base-url "$QINGFLOW_BASE_URL" --credential-stdin --persist` |
|
|
35
|
+
| 安全退出 | `qingflow auth logout --forget-persisted` | 需要清本机持久化凭证时用。 |
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 3. 工作区(只读优先,避免误切租户)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
| 场景 | 一次成功写法 | 必填/注意 |
|
|
44
|
+
| ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
45
|
+
| 当前会话工作区详情 | `qingflow --json workspace get --ws-id <WS_ID>` | `**<WS_ID>`** 与 `auth whoami` 中选中租户一致最稳;**不依赖**先 `workspace list`(list 在部分环境会因配额等失败)。 |
|
|
46
|
+
| 枚举工作区(可选) | `qingflow --json workspace list --page 1 --page-size 40` | 可能因配额等失败;失败时仍以 **whoami + workspace get** 为基准。 |
|
|
47
|
+
| 切换工作区(会改会话) | `qingflow workspace select --ws-id <WS_ID>` | **必填** `--ws-id`;可能触发 **59004**;自动化探针若不想改租户应**不调用**。 |
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 4. 应用与门户/视图/报表(只读)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
| 场景 | 一次成功写法 | 必填/注意 |
|
|
56
|
+
| ------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
57
|
+
| 列出应用 | `qingflow --json app list` | 通常仅需有效会话。 |
|
|
58
|
+
| 成员侧按关键字找应用 | `qingflow --json app list --query <关键词>` | 只读取当前用户可见应用并本地过滤;看 `matched_count` / `unfiltered_count` / `items[].app_key`。 |
|
|
59
|
+
| 应用详情(含可访问视图) | `qingflow --json app get --app-key <APP_KEY>` | **必填** `--app-key`;后续 **view-id** 多从返回的 `accessible_views` 等字段选取。 |
|
|
60
|
+
| 门户列表 | `qingflow --json portal list` | 一般只读。 |
|
|
61
|
+
| 单个门户 | `qingflow --json portal get --dash-key <DASH_KEY>` | **必填** `--dash-key`。 |
|
|
62
|
+
| 用户侧视图 | `qingflow --json view get --view-id <VIEW_ID>` | **必填** `--view-id`(与用户态 id 一致,勿与 builder 的 `view-key` 混用)。 |
|
|
63
|
+
| 用户侧图表 | `qingflow --json chart get --chart-id <CHART_ID>` | **必填** `**chart-id` 合法且有权访问**。 |
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 5. 记录:`record`(区分「仅需 app-key」与「必须 view-id」)
|
|
69
|
+
|
|
70
|
+
下面「一次成功」指 **CLI 不会因缺参报错**;服务端仍可能因权限返回错误 JSON。
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
| 场景 | 一次成功写法 | 必填/注意 |
|
|
74
|
+
| ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
75
|
+
| Insert schema | `qingflow --json record schema insert --app-key <APP_KEY>` | 新建记录默认走 `qingflow-record-insert`;CLI 用 insert-ready schema + `record insert --items-file`。 |
|
|
76
|
+
| Import / code-block schema | `qingflow --json record schema import --app-key <APP_KEY>` / `qingflow --json record schema code-block --app-key <APP_KEY>` | 仅在导入或代码块任务明确需要时使用。 |
|
|
77
|
+
| Schema:browse(浏览态字段) | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>` | **必须 `--view-id`**;不要用引号包住 `record schema browse` 整段。 |
|
|
78
|
+
| 列表/候选定位(运行时强校验) | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>` | **必须 `--view-id`**;默认最多返回 10 条,适合样本/模糊定位;可加 `--query` / `--query-field`。 |
|
|
79
|
+
| 分析取数 | `qingflow --json record access --app-key <APP_KEY> --view-id <VIEW_ID> --columns-file columns.json --where-file where.json` | 最终统计结论统一使用 `qingflow-record-analysis` 的 `record_access -> Python/pandas`。 |
|
|
80
|
+
| 单条读取 | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID>` | **必须** `--record-id`;返回前端详情页首屏上下文、引用、图片/文件资产。 |
|
|
81
|
+
| 全量记录日志 | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 仅在需要完整审计/日志历史时使用;全量数据日志和流程日志写本地 JSONL。 |
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
**高风险写操作**(本表不保「业务上你希望的一次成功」,只列形态):`record insert/update/delete`、`record code-block-run`(可能写回)需按 `-h` 逐项带齐文件类参数与安全开关。
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 6. 待办 `task`(查询类建议落盘)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
| 场景 | 一次成功写法 | 必填/注意 |
|
|
92
|
+
| ---- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
93
|
+
| 待办列表 | `qingflow --json task list --task-box todo --flow-status all --page 1 --page-size 50` | 不限定应用时不要硬塞 `--app-key`;已知应用后再追加 `--app-key <APP_KEY>` 收窄。 |
|
|
94
|
+
| 待办详情 | `qingflow --json task get --task-id <TASK_ID>` | **或** 使用帮助中 `**--app-key` + `--record-id` (+ `--workflow-node-id`)** 组合推断(二选一链路,勿混用漏参)。 |
|
|
95
|
+
| 流程日志 | `qingflow --json task log --task-id <TASK_ID>` | 需有效 `**task-id`** 或等价组合。 |
|
|
96
|
+
| 关联报表 | `qingflow --json task report --task-id <TASK_ID> --report-id <REPORT_ID>` | `**report-id`** 需有效。 |
|
|
97
|
+
| 执行动作 | `qingflow task action --task-id <TASK_ID> --action <ACTION> ...` | **无 `--dry-run`**;属写操作,慎跑。 |
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 7. 导入 `import`(链式;单步「一次成」条件)
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
| 场景 | 一次成功写法 | 必填/注意 |
|
|
106
|
+
| ------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
107
|
+
| 拉模板说明等 | `qingflow --json import template --app-key <APP_KEY>` | 常需应用管理类权限。 |
|
|
108
|
+
| 校验文件 | `qingflow --json import verify --app-key <APP_KEY> --file-path <LOCAL_FILE>` | **必须** `--file-path`,且文件须为服务端**支持的导入模板格式**;随意占位文件可能被 `IMPORT_FILE_FORMAT_UNSUPPORTED`。 |
|
|
109
|
+
| 导入状态查询 | `qingflow --json import status --app-key <APP_KEY>` | **仅能三选一**:`--process-id-str` / `--import-id` / `**--app-key`**(独自表示读该应用**最新导入**);混搭多个选择器易被拒。**仅 `--app-key` 且无唯一「最新导入」时**可出现 `IMPORT_STATUS_AMBIGUOUS`(与是否管理员无关,属数据状态)。 |
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
更后序的 `repair` / `start` 依赖前置返回的 `**verification-id`** 等,按 `import -h` 逐级带参。
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 8. Builder(只列「必填闭合即过 CLI」的常用只读)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
| 场景 | 一次成功写法 | 必填/注意 |
|
|
120
|
+
| ----- | ------------------------------------------------------------ | --------------------------------- |
|
|
121
|
+
| 成员搜索 | `qingflow --json builder member search --query <关键词>` | `**--query` 服务端必填**(帮助里可能看起来像可选)。 |
|
|
122
|
+
| 角色搜索 | `qingflow --json builder role search --keyword <关键词>` | `**--keyword` 必填**。 |
|
|
123
|
+
| 应用包列表 | `qingflow --json builder package list --query <关键词>` | 直接走 `/tag`;返回 `items[].package_id/package_name/permissions`。 |
|
|
124
|
+
| 应用包读取 | `qingflow --json builder package get --package-id <整数>` | `**package-id` 须为整数**。 |
|
|
125
|
+
| 发布自检 | `qingflow builder publish verify --app-key <APP_KEY>` | builder 写入/校验类命令自动 JSON。 |
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
`builder * apply` / `role create` / `package apply` / `solution install` 等为写路径,成功与否强依赖配置文件与租户策略,**不放入「默认一次必成」表**。
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## 9. 必败反例(避免浪费时间)
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
| 错误写法 | 原因 |
|
|
136
|
+
| --------------------------------------------------- | ----------------------------------------------- |
|
|
137
|
+
| `qingflow --version` | 根级无 `--version`。 |
|
|
138
|
+
| `qingflow record list --app-key xxx`(无 `--view-id`) | 运行时常报错:`requires view_id`。 |
|
|
139
|
+
| `"qingflow record schema browse" --app-key ...` | 子命令被整体加引号,解析器不认。 |
|
|
140
|
+
| `builder member search`(无 `--query`) | 常见:`MEMBER_QUERY_REQUIRED` / query is required。 |
|
|
141
|
+
| `builder role search`(无 `--keyword`) | 常见:`ROLE_QUERY_REQUIRED`。 |
|
|
142
|
+
| `import status` 同时丢多个互斥 selector | 见上文「三选一」。 |
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 10. 最小业务链路示例(Wingent Momo runtime 下不做登录前置)
|
|
148
|
+
|
|
149
|
+
在满足账号权限的前提下:
|
|
150
|
+
|
|
151
|
+
1. `qingflow --json app list [--query <关键词>]` → 选一个 `**app_key`**
|
|
152
|
+
2. `qingflow --json app get --app-key <APP_KEY>` → 选一个 `**view_id`**
|
|
153
|
+
3. `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>`
|
|
154
|
+
|
|
155
|
+
若要落盘再给第 3 步加 `> tmp/qingflow_records.json`。只有业务命令明确返回会话不可用、账号不确定或工作区异常时,才回到第 2 节做会话恢复。
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
*文档生成说明:与 **[../SKILL.md](../SKILL.md)**、[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) 对齐;若 CLI 版本升级,请以 `qingflow … -h` 为准做小步修订。*
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Qingflow CLI:创建记录 SOP(申请节点)
|
|
2
|
+
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
**创建记录 SOP 见 skill:`qingflow-record-insert`。**
|
|
6
|
+
|
|
7
|
+
CLI 对应主路径:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
qingflow --json record schema insert --app-key <APP_KEY> > tmp/qingflow_insert_schema.json
|
|
11
|
+
qingflow --json record insert --app-key <APP_KEY> --items-file tmp/records.json > tmp/qingflow_insert_result.json
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
不要用 `record schema applicant` 代替 `record_insert_schema_get` 的主路径;新建记录需要 insert-ready schema 里的 `required_fields`、`optional_fields`、`payload_template`、`format_hint` 和 `example_value`。
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# 记录批量导入 SOP:`app_get`(`import_capability`)→ 模板 → 校验 →(可选)本地修复 → 启动 → 状态
|
|
2
|
+
|
|
3
|
+
本文与 **MCP 工具命名**一致,并映射到 **`qingflow` CLI**。编写前已 **实跑**:`app get`、`record schema import`、`import template`、`import verify`、`import repair`(未授权分支 + 授权分支遇 **合并单元格** 异常)、`import start`、`import status`(**仅** `--import-id`);环境为当前持久化 CLI 会话、应用 `ead8ims5i401`。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. 编排顺序(固定)
|
|
8
|
+
|
|
9
|
+
| 顺序 | 工具名 | CLI | 说明 |
|
|
10
|
+
|------|--------|-----|------|
|
|
11
|
+
| 1 | `app_get` | `qingflow --json app get --app-key <APP_KEY>` | 读 **`data.import_capability`**,预检是否有导入能力 |
|
|
12
|
+
| (可选) | `record_import_schema_get` | `qingflow --json record schema import --app-key <APP_KEY>` | `schema_scope: import_ready`,列 **`columns`**;能力仍以 **`app get`** 为准 |
|
|
13
|
+
| 2 | `record_import_template_get` | `qingflow [--json] import template --app-key <APP_KEY> [--download-to-path <PATH>]` | 官方模板 URL 或 **本地生成的 applicant 模板**(无数据管理权限或导入权限预检未知时可能 fallback) |
|
|
14
|
+
| 3 | `record_import_verify` | `qingflow [--json] import verify --app-key <APP_KEY> --file-path <*.xlsx\|*.xls>` | 产出 **`verification_id`**;**`can_import`** 为真后才应 **`import start`** |
|
|
15
|
+
| (可选) | `record_import_repair_local` | `qingflow [--json] import repair --verification-id <UUID> --authorized-file-modification …` | **必须** 显式授权;**仅 `.xlsx`**;可重复 **`--repair`** |
|
|
16
|
+
| 4 | `record_import_start` | `qingflow [--json] import start --app-key <APP_KEY> --verification-id <UUID> --being-enter-auditing <true\|false> [--view-key …]` | **会真实发起导入** |
|
|
17
|
+
| 5 | `record_import_status_get` | `qingflow [--json] import status (--app-key \| --import-id \| --process-id-str)` **三者择一** | **不要**同时传多个 selector(例如 **`--import-id` 与 `--app-key` 同时**会被 CLI 拒绝) |
|
|
18
|
+
|
|
19
|
+
CLI 注册见全局包 **`qingflow_mcp/cli/commands/imports.py`**(`template` / `verify` / `repair` / `start` / `status` → 上述 `ImportTools` 方法)。
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 2. `import_capability`(来自 `app get`)
|
|
24
|
+
|
|
25
|
+
`app get` 在 **`data.import_capability`** 中附带由 `baseInfo` 推导的能力(实现:**`_derive_import_capability`**):
|
|
26
|
+
|
|
27
|
+
| 字段 | 含义 |
|
|
28
|
+
|------|------|
|
|
29
|
+
| **`can_import`** | `true` / `false` / `null`(未知) |
|
|
30
|
+
| **`auth_source`** | `apply_auth`(申请人导入开关)、`data_manage_auth`(数据管理)、`none`、`unknown` |
|
|
31
|
+
| **`applicant_import_enabled`** | 与 `dataImportStatus` 对应 |
|
|
32
|
+
| **`data_manage_status`** | 与 `dataManageStatus` 对应 |
|
|
33
|
+
| **`runtime_checks_required`** | 预检后仍可能受 **`user_disabled`**、**`function_demoted`** 等运行态影响 |
|
|
34
|
+
| **`confidence`** | `preflight`(由元数据推出)或 `unknown` |
|
|
35
|
+
|
|
36
|
+
- **`record_import_schema_get` / `record_import_template_get` / `record_import_verify`**:若 `can_import === false` 且来源非 `unknown`,会直接 **`IMPORT_AUTH_PRECHECK_FAILED`**,不会继续读取导入列、官方模板或进入后端文件校验。
|
|
37
|
+
- **`record_import_template_get`**:当具备申请人导入能力但无数据管理权限时,可能对 **`/app/{appKey}/apply/excelTemplate`** 失败并 **本地生成** applicant 模板(警告 **`IMPORT_TEMPLATE_LOCAL_FALLBACK`**)。
|
|
38
|
+
- 若 **`app get` / `baseInfo`** 权限受限导致 **`import_capability.auth_source: unknown`**,但 applicant 字段 schema 可读,且官方模板接口返回 **40002 / 40027**,`record_import_template_get` 也可能返回 **`status: partial_success`** 并本地生成模板(警告 **`IMPORT_TEMPLATE_LOCAL_FALLBACK_AUTH_UNKNOWN`**)。这只说明“模板准备成功”,**不证明用户有导入权限**;后续仍以 **`record_import_verify` / `record_import_start`** 的 `can_import` 与最终结果为准。
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 3. 本地校验仓与运行环境
|
|
43
|
+
|
|
44
|
+
- **`verification_id`** 由 **`record_import_verify`** 生成,并写入本机 **`~/.qingflow-mcp/import-verifications/<id>.json`**(**`ImportVerificationStore`**)。
|
|
45
|
+
- **`record_import_start` / `repair`** 依赖该目录;**自动化/CI 需允许写此目录**,且 **`verify` → `start` 须在** 同一 profile、可达后端的会话内完成。
|
|
46
|
+
- **`record_import_status_get`** 在仅传 **`--import-id`** 时,会结合本地 **`ImportJobStore`** 与后端 **`GET /app/apply/dataImport/record`** 解析 **`app_key` / `process_id_str`**;与 **`import start`** 返回的 **`import_id`**、**`process_id_str`** 对齐使用。
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 4. 命令要点
|
|
51
|
+
|
|
52
|
+
### 4.1 模板
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
qingflow --json import template --app-key "<APP_KEY>" \
|
|
56
|
+
--download-to-path tmp/qingflow_import_template.xlsx \
|
|
57
|
+
> tmp/qingflow_import_template_meta.json
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- 关注 **`verification.template_source`**:`official` 或本地 fallback。
|
|
61
|
+
- 若 `verification.import_auth_prechecked: false`,表示模板来自 schema 可读分支但导入权限尚未预检成功;不要把该模板结果当作导入授权结论。
|
|
62
|
+
- **`expected_columns`** 在部分响应负荷中给出;**与校验**一致。
|
|
63
|
+
|
|
64
|
+
### 4.2 校验
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
qingflow --json import verify --app-key "<APP_KEY>" \
|
|
68
|
+
--file-path tmp/qingflow_import_template.xlsx \
|
|
69
|
+
> tmp/qingflow_import_verify.json
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
- 始终解析 **`verification_id`**;仅 **`can_import: true`** 时进入后端 multipart **`/upload/verification`**。
|
|
73
|
+
- **标准输出**上 OpenPyXL 可能对某些 xlsx 打出 **`UserWarning`**(**出现在 JSON 前**)。 jq/直解 **`json.load` 失败时,从首个 `{` 起截取再解析**。
|
|
74
|
+
|
|
75
|
+
### 4.3 本地修复(可选)
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
qingflow --json import repair \
|
|
79
|
+
--verification-id "<VERIFICATION_UUID>" \
|
|
80
|
+
--authorized-file-modification \
|
|
81
|
+
[--output-path tmp/repaired.xlsx] \
|
|
82
|
+
[--repair normalize_headers] [--repair trim_trailing_blank_rows] \
|
|
83
|
+
... \
|
|
84
|
+
> tmp/qingflow_import_repair.json
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- **未加** `--authorized-file-modification` → **`IMPORT_REPAIR_NOT_AUTHORIZED`**。
|
|
88
|
+
- **`--repair`** 可重复;允许集合(实现 **`SAFE_REPAIRS`**):
|
|
89
|
+
**`normalize_headers`**、**`trim_trailing_blank_rows`**、**`normalize_enum_values`**、**`normalize_date_formats`**、**`normalize_number_formats`**、**`normalize_url_cells`**。
|
|
90
|
+
**省略 `--repair`** 时实现默认对 **全集** 尝试。
|
|
91
|
+
- **仅 `.xlsx`**;**合并单元格表格** 在 **`normalize_headers`** 等路径上可能触发 **`MergedCell` 只读** 类异常(实跑曾遇到);此时应改模板或跳过 repair、重新导出模板再 **`verify`**。
|
|
92
|
+
|
|
93
|
+
成功时返回 **`new_verification_id`**,后续 **`start`** 应用 **新 ID**(若 repair 后重新校验通过)。
|
|
94
|
+
|
|
95
|
+
### 4.4 启动导入
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
qingflow --json import start \
|
|
99
|
+
--app-key "<APP_KEY>" \
|
|
100
|
+
--verification-id "<VERIFICATION_UUID>" \
|
|
101
|
+
--being-enter-auditing false \
|
|
102
|
+
[--view-key "<VIEW_KEY>"] \
|
|
103
|
+
> tmp/qingflow_import_start.json
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
- **`--being-enter-auditing`**:**必填**,布尔字面量:`true` / `false` / `1` / `0` / `yes` / `no` 等(见 argparse `parse_bool_text`)。
|
|
107
|
+
- **会校验**:校验记录仍存在、**`can_import`**、**文件 sha256** 未变、**`schema_fingerprint`** 未变;否则 **`IMPORT_VERIFICATION_STALE`** / **`IMPORT_FILE_CHANGED_AFTER_VERIFY`** / **`IMPORT_SCHEMA_CHANGED_AFTER_VERIFY`**。
|
|
108
|
+
|
|
109
|
+
### 4.5 状态
|
|
110
|
+
|
|
111
|
+
**参数规则(CLI)**:**必须且只能** 提供 **`--app-key`**、**`--import-id`**、**`--process-id-str`** 中的 **一个**。
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# 已知本次 start 返回的 import_id(不要同时加 --app-key)
|
|
115
|
+
qingflow --json import status --import-id "<IMPORT_UUID>" \
|
|
116
|
+
> tmp/qingflow_import_status.json
|
|
117
|
+
|
|
118
|
+
# 或只看该应用最近一次导入(仅 --app-key)
|
|
119
|
+
qingflow --json import status --app-key "<APP_KEY>" \
|
|
120
|
+
> tmp/qingflow_import_status_latest.json
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 5. 与 `record schema import` 的关系
|
|
126
|
+
|
|
127
|
+
- **`record schema import`**:专注 **导入列 / 指纹**(与校验用的 schema bundle 一致思路),**不替代** **`app get` 的 `import_capability`**。
|
|
128
|
+
- 推荐顺序:**`app get`(能力)** →(可选)**`record schema import`(列清单)** → **`import template`** → …
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## 6. 实测摘要(编写时)
|
|
133
|
+
|
|
134
|
+
| 步骤 | 结果 |
|
|
135
|
+
|------|------|
|
|
136
|
+
| `app get` | `import_capability.can_import: true`,`auth_source: data_manage_auth` |
|
|
137
|
+
| `record schema import` | `schema_scope: import_ready` |
|
|
138
|
+
| `import template --download-to-path` | 落盘 xlsx 成功 |
|
|
139
|
+
| `import verify` | `can_import: true`,`verification_id` 可用;可能有 **`IMPORT_HEADERS_AUTO_NORMALIZED`** |
|
|
140
|
+
| `import repair --authorized-file-modification` | 特定模板因 **合并单元格** 在 **`normalize_headers`** 崩溃;属 **模板/实现边界** |
|
|
141
|
+
| `import start` | `status: accepted`,返回 **`import_id`**、**`process_id_str`** |
|
|
142
|
+
| `import status --import-id …` | 返回 `app_key`、**`process_id_str`**、**`status`**(后端枚举字符串,如实测 `"3"`) |
|
|
143
|
+
| `import status --import-id … --app-key …` | **CLI 拒绝**:只能选一个 selector |
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 7. 交叉引用
|
|
148
|
+
|
|
149
|
+
- 主技能 [SKILL.md](../SKILL.md):**落盘**、导入类权限码 **`IMPORT_*`** 提示。
|
|
150
|
+
- [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md):管理侧与 **`IMPORT_*`** 失败排查。
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# Qingflow CLI:更新记录工作流(详情后直接写入)
|
|
2
|
+
|
|
3
|
+
> **用途**:使用当前 CLI 会话读取目标记录详情后,用 **`record update`** 直接提交差异字段。主链路是 `record get -> record update`;字段范围不清、候选歧义或失败排查时,才追加 **`record schema update`**。
|
|
4
|
+
> **关联**:只读列表/详情见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**;**字段 `kind` 与写入值总表**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**;最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**;**成员 / 部门等** 的细颗粒写入见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**;主技能 **[../SKILL.md](../SKILL.md)**。
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 习惯概念名 → CLI
|
|
9
|
+
|
|
10
|
+
| 概念名 | CLI |
|
|
11
|
+
| --- | --- |
|
|
12
|
+
| `app_get`(含 `accessible_views`) | `qingflow --json app get --app-key <APP_KEY>` |
|
|
13
|
+
| `record_schema_get`,`schema_mode=browse`,带 `view_id` | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>` |
|
|
14
|
+
| `record_get` | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` |
|
|
15
|
+
| `record_update`(单条) | `qingflow --json record update --app-key <APP_KEY> --record-id <RECORD_ID> --fields-file <FIELDS.json> [--view-id <VIEW_ID>]` |
|
|
16
|
+
| `record_update`(批量) | `qingflow --json record update --app-key <APP_KEY> --items-file <ITEMS.json> [--view-id <VIEW_ID>] [--dry-run]`(见下文) |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 推荐顺序
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
record get(得到 RECORD_ID、当前值、fields[].title/field_id/kind;已知前端视图时带 view_id)
|
|
24
|
+
→ 智能体按用户要求组 fields key/value
|
|
25
|
+
→ record update --fields-file [--view-id](只提交需要改的题;大 JSON 落盘)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**何时先 `app get` / `record list`**:不知道 `view_id` 或 `record_id` 时,先用 `app get` 选视图,再用 `record list` 定位候选。已知 `record_id` 但已知前端/custom view 时,直接 `record get --view-id <VIEW_ID>`。
|
|
29
|
+
**何时追加 `record schema browse`**:只在需要提前看视图表头或搜索字段时使用;`record get` 已经会返回单条详情所需字段信息。
|
|
30
|
+
**何时追加 `record schema update`**:该命令 **必须 `record_id`**,返回 **`writable_fields` / `payload_template` / `available_update_routes` / `recommended_update_route`**,只用于排查「能改什么」和「会走哪条更新路径」。已知前端/custom view 时同样带 `--view-id`,让诊断优先探测同一个详情页上下文;字段明确时不要把它当必经步骤。
|
|
31
|
+
|
|
32
|
+
**更新路径自动选择**:`record update --view-id <VIEW_ID>` 会优先用这个 view 做字段解析和 custom view 写入候选;未传时自动探测可读 route。写入时仍会先尝试 **数据管理员直改**,若后端返回权限拒绝,再 fallback 到 **前端同源 custom view 详情编辑路径**;如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑,最后会尝试 **workflow save-only**。成功时响应中的 **`update_route`** 是最终成功路径;失败时再查看失败原因与路线诊断。若诊断里有 `40002`,只代表某条 route 被拒绝,不一定表示用户对记录完全无编辑能力。
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 命令模板
|
|
37
|
+
|
|
38
|
+
**1)读取详情**
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
qingflow --json record get \
|
|
42
|
+
--app-key <APP_KEY> \
|
|
43
|
+
--record-id <RECORD_ID> \
|
|
44
|
+
--view-id <VIEW_ID> \
|
|
45
|
+
> tmp/qingflow_record_get.json
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
已知用户前端所在视图时传同一个 `--view-id`;未知时 CLI 默认先尝试 `system:all/type=8`,若该详情 route 被权限/不可见类错误拒绝,会继续尝试可访问视图。读取 `fields[]` 中的标题、`field_id`、`kind` 与当前值来组更新 payload。
|
|
49
|
+
|
|
50
|
+
`record_get` 的 `unavailable_context[]` 是辅助上下文提示:`detail_schema` / `audit_info` / 首屏日志等 40002 不等于记录详情读取失败。只要顶层 `status=ok` 且 `fields[]` 中已有目标字段,就按这些字段组 `record update` 的 key/value;只有顶层失败才按失败原因排查。
|
|
51
|
+
|
|
52
|
+
**2)如果缺 `record_id`,先定位候选**
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
qingflow --json record list \
|
|
56
|
+
--app-key <APP_KEY> \
|
|
57
|
+
--view-id <VIEW_ID> \
|
|
58
|
+
> tmp/qingflow_records.json
|
|
59
|
+
# 或
|
|
60
|
+
qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> \
|
|
61
|
+
> tmp/qingflow_record_get.json
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**3)单条更新**
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
qingflow --json record update \
|
|
68
|
+
--app-key <APP_KEY> \
|
|
69
|
+
--record-id <RECORD_ID> \
|
|
70
|
+
--fields-file tmp/qingflow_patch_fields.json \
|
|
71
|
+
--view-id <VIEW_ID> \
|
|
72
|
+
> tmp/qingflow_update_result.json
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`--view-id` 可省略;已知用户来自某个 `custom:...` 前端详情页时建议传入,CLI 会优先尝试该 view,失败后再按自动路径 fallback。
|
|
76
|
+
|
|
77
|
+
**4)(仅排障)本条记录的更新诊断**
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
qingflow --json record schema update \
|
|
81
|
+
--app-key <APP_KEY> \
|
|
82
|
+
--record-id <RECORD_ID> \
|
|
83
|
+
--view-id <VIEW_ID> \
|
|
84
|
+
> tmp/qingflow_schema_update.json
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
**`tmp/qingflow_patch_fields.json`**:JSON **对象**,键为 **题目标题**(优先来自 `record get.fields[]`),**只放需要修改的键**;值类型与 **新建** 相同(成员、部门、附件等见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**)。实现要求 **`fields` 为「按标题索引的 map」**(与 `record insert` 一致)。
|
|
88
|
+
|
|
89
|
+
**特殊字段值**:
|
|
90
|
+
|
|
91
|
+
- **成员字段 `kind=member`**:先传自然语言字符串,如 `{"客户成功":"周颖"}`。若返回 `status="needs_confirmation"`,说明尚未写入;从 `confirmation_requests[].candidates[]` 选一项,改传显式对象,如 `{"客户成功":{"uid":1048599,"name":"沈嘉慧Seth","email":"shenjiahui@exiao.tech"}}`。
|
|
92
|
+
- **部门字段 `kind=department`**:先传部门名,如 `{"负责部门":"客户成功部"}`;歧义时同样按候选对象/id 重试。
|
|
93
|
+
- **关联字段 `kind=relation`**:传唯一可解析的自然语言、或 `{"apply_id":"..."}`;多匹配时按候选记录重试,不要猜 `apply_id`。
|
|
94
|
+
- **选项字段 `kind=select`**:单选传一个选项字符串;多选传字符串数组。
|
|
95
|
+
- **引用/公式/自动填充/只读/系统字段**:不要强写目标字段;改写上游驱动字段,或把 blocker 原因反馈给用户。
|
|
96
|
+
|
|
97
|
+
`needs_confirmation` 的语义是 **`write_executed=false`,等待确认候选**;不要把它当成功,也不要把它当最终权限失败。只有用明确候选对象重试并成功后,才报告写入完成。
|
|
98
|
+
|
|
99
|
+
**`--verify-write` / `--no-verify-write`**:见 `qingflow record update -h`;默认倾向 **保留校验**。
|
|
100
|
+
|
|
101
|
+
更新后优先查看:
|
|
102
|
+
|
|
103
|
+
- **`update_route.route_type`**:`admin_direct`、`view_edit` 或 `task_save_only`。
|
|
104
|
+
- **`tried_routes[]`**:只在失败或 verbose 诊断时需要看;成功时不要把中间路径失败当最终结果。
|
|
105
|
+
- **`write_executed`**:是否已经发出写请求;为 `true` 时不要盲目整单重试。
|
|
106
|
+
- **`verification_status`**:读回校验是否通过。
|
|
107
|
+
|
|
108
|
+
**`record_id` 与写入(排查前置)**:若后端 **`record_id` 超出 JavaScript `Number.MAX_SAFE_INTEGER`(约为 `9007199254740991`)**:在旧 1.0.x 或同类实现分支上,**`record list` / `record get` / `record schema update` 常仍可正常**,而 **`record update` 的实际落库**可能在 **`apply_id` 二次校验**处失败——stdout 常表现为 **`apply_id must be positive`**,根本原因多为 **「整数超过 JS 安全范围」**。**批量 `--dry-run`** 仍可用于覆盖 **预检**流程。处理方式见 **「排查摘要」**末行。
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## 批量模式(`--items-file`)
|
|
113
|
+
|
|
114
|
+
- **不可**与 **`--record-id` / `--fields-file`** 同时使用。
|
|
115
|
+
- `items` 为 **数组**,每项为对象,至少包含:
|
|
116
|
+
- **`record_id`**:正整数(字符串或可解析数字均可,以 CLI 校验为准)
|
|
117
|
+
- **`fields`**:与单条相同的「标题 → 值」map
|
|
118
|
+
|
|
119
|
+
示例:
|
|
120
|
+
|
|
121
|
+
```json
|
|
122
|
+
[
|
|
123
|
+
{ "record_id": "518257794791628802", "fields": { "客户名称": "新名称" } },
|
|
124
|
+
{ "record_id": "518257794791628803", "fields": { "备注": "批量第 2 条" } }
|
|
125
|
+
]
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
- **`--dry-run`**:**仅批量模式**支持(单条模式需走 `items-file` 才能 dry-run);用于预检。详见 `qingflow record update -h` 与 CLI 报错指引。
|
|
129
|
+
- 批量输出优先读顶层语义,不需要再钻进 `data.summary`:
|
|
130
|
+
- `mode="batch"`、`dry_run`
|
|
131
|
+
- `total`、`succeeded`、`failed`、`needs_confirmation`
|
|
132
|
+
- `updated_record_ids`
|
|
133
|
+
- `write_executed`、`safe_to_retry`、`verification_status`
|
|
134
|
+
- `items[].row_number / record_id / status / failed_fields / confirmation_requests`
|
|
135
|
+
- `dry_run=true` 时 `write_executed=false`、`safe_to_retry=true`,只能说明预检通过;真正写入仍需去掉 `--dry-run` 再执行。
|
|
136
|
+
- `write_executed=true` 后不要盲目整批重试;根据 `items[].row_number` 和 `updated_record_ids` 判断是否只补失败行。
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## 安全与落盘
|
|
141
|
+
|
|
142
|
+
- **`record update` 为写操作**;仅在授权环境、**必要时**对测试应用演练。
|
|
143
|
+
- **`list` / `get` / `schema browse` / `schema update` / 更新结果** 体大量时按主技能 **落盘规则** 重定向。
|
|
144
|
+
- 主技能 **危险操作** 中对 `record update --dry-run`(批量)的说明仍适用。
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## 排查摘要
|
|
149
|
+
|
|
150
|
+
| 现象 | 处理 |
|
|
151
|
+
| --- | --- |
|
|
152
|
+
| 缺 `record_id` | 先用 **`record list`**(同一 `view_id`)或 **`record get`**。 |
|
|
153
|
+
| 不知道字段标题或当前值 | 先查 **`record get`** 的 `fields[]`。 |
|
|
154
|
+
| 不知道能改哪些题 / 路径失败 | 再查 **`record schema update`** 的 `writable_fields` / `payload_template` / 路径诊断;它不是主链路前置步骤。 |
|
|
155
|
+
| 配置类报错 | 单条更新必须 **`--record-id` + `--fields-file`**;批量必须 **`--items-file`**,且勿混用单条参数。 |
|
|
156
|
+
| `needs_confirmation` | 尚未写入;从 `confirmation_requests[].candidates[]` 选明确对象/id 后重试,再读回确认。 |
|
|
157
|
+
| `40002` | 先看 **`tried_routes`**:如果 `admin_direct` 拒绝但 `view_edit` 或 `task_save_only` 成功,说明某条具体通道不可用但仍有可写路径;如果所有 route 都拒绝,再按权限问题处理。 |
|
|
158
|
+
| 成员/部门格式错误 | 与 **创建记录** 文档同一套结构;必要时用 **`record member-candidates` / `record department-candidates`** 走字段候选范围。不要改用 `builder member search` 做记录字段候选。 |
|
|
159
|
+
| **`apply_id must be positive`**,或内部报错含 **`exceeds JavaScript's safe integer range`**(单条 **`record update`** 或批量 **非 dry-run**) | **`record_id` 典型超出 JavaScript 安全整数上限**(`Number.MAX_SAFE_INTEGER`,约为 `9007199254740991`):读链路与 **`schema update`、批量 `--dry-run`** 可走通;**写入**须在 **新版本 CLI** 重做或向维护方确认。短期仅用 **更小 id 的授权测试应用/记录**演练。 |
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
*维护:复核 `qingflow record schema update -h`、`record update -h`;`view_id` 与成员策略以当前 CLI help 与同目录成员速查表为准。*
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# `app_schema_apply` / `builder schema apply`:字段类型与场景总表
|
|
2
|
+
|
|
3
|
+
> **口径**:`field.type` 枚举以 **`qingflow --json builder contract --tool-name app_schema_apply`**(及包内 `PublicFieldType`)为准;**形状校验**以 `qingflow_mcp` 的 **`FieldPatch`**(`builder_facade/models.py`)与 **`app_schema_apply` 编排**(`builder_facade/service.py`)为准。
|
|
4
|
+
> **CLI**:`qingflow [--profile NAME] builder schema apply [--app-key APP_KEY | 创建模式… | --apps-file 多应用数组] [--publish|--no-publish] [--add-fields-file …] [--update-fields-file …] [--remove-fields-file …]`;**`qingflow` 未在 PATH 时**可用 `npx @qingflow-tech/qingflow-cli` 前缀,并把 `--profile` 放在 `builder` 之前。
|
|
5
|
+
> **新建应用主规则**:`add_fields[]` 里必须有且仅有一个顶层字段标记 `as_data_title: true`;数据封面可选,只能在顶层 `attachment` 字段标记 `as_data_cover: true`。
|
|
6
|
+
> **权限**:包内新建应用按后端 `CreateAppBean` 链路只预检目标包 **AddAppAuth**;已有应用的字段/基础信息变更才走应用自身 **EditAppAuth**。
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. 全部 `field.type`(19 种)
|
|
11
|
+
|
|
12
|
+
与契约一致时,搭建侧 **`add_fields[]` / `update_fields[]`** 可用类型为:
|
|
13
|
+
|
|
14
|
+
| `type` | 说明(搭建语义) |
|
|
15
|
+
|--------|------------------|
|
|
16
|
+
| `text` | 单行文本 |
|
|
17
|
+
| `long_text` | 多行文本 |
|
|
18
|
+
| `number` | 数字 |
|
|
19
|
+
| `amount` | 金额 |
|
|
20
|
+
| `date` | 日期 |
|
|
21
|
+
| `datetime` | 日期时间 |
|
|
22
|
+
| `member` | 成员 |
|
|
23
|
+
| `department` | 部门(可带 `department_scope`) |
|
|
24
|
+
| `single_select` | 单选 |
|
|
25
|
+
| `multi_select` | 多选 |
|
|
26
|
+
| `phone` | 电话 |
|
|
27
|
+
| `email` | 邮箱 |
|
|
28
|
+
| `address` | 地址 |
|
|
29
|
+
| `attachment` | 附件 |
|
|
30
|
+
| `boolean` | 是否 |
|
|
31
|
+
| `q_linker` | 远程查询 / 数据获取(**`q_linker_binding`**) |
|
|
32
|
+
| `code_block` | 代码块(**`code_block_binding`** + 编译后的 `code_block_config`) |
|
|
33
|
+
| `relation` | 关联记录(**`relation_mode`**:`single` \| `multiple`) |
|
|
34
|
+
| `subtable` | 子表(**`subfields[]`**) |
|
|
35
|
+
|
|
36
|
+
**`relation_mode`**:仅 **`relation`** 使用,取值为 **`single`** 或 **`multiple`**(多关联字段能力受 **`verification.relation_field_limit_verified`** 等约束,见交付文 §6)。
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 2. 按类型的必填 / 常用可选(写意图)
|
|
41
|
+
|
|
42
|
+
| `type` | 通常必填 | 常见可选 / 约束 |
|
|
43
|
+
|--------|----------|-----------------|
|
|
44
|
+
| 标量与选择器 | `name` + `type`(+ 业务 `required` 等) | `description`、`required`;新建应用时其中一个顶层可读字段须 `as_data_title: true`;**`single_select` / `multi_select` 的 `options` 必须是字符串数组**,如 `["A", "B"]`,不要写对象数组或 `label/value` |
|
|
45
|
+
| `department` | 同左 | **`department_scope`**:`mode: all \| custom`;`custom` 时 **`departments[]`**(含 `dept_id` 等) |
|
|
46
|
+
| `relation` | **`target_app_key`**、**`display_field`**、**`visible_fields[]`** | **`relation_mode`**;目标应用元数据不可读时可多写 **`name`** 降级 |
|
|
47
|
+
| `subtable` | **`subfields[]` 非空** | 子列递归同父级规则;更新已存在子列优先契约 **`subfield_updates`** |
|
|
48
|
+
| `q_linker` | **`q_linker_binding`**:`inputs`、`request`、**`outputs[]` 每项须含 `target_field`**(能解析到本表单字段) | `request.url` 等须符合**租户/后端远程查询策略**;读回 JSON 可能**缺** `outputs[].target_field`,会导致本地再编译失败(见 §5) |
|
|
49
|
+
| `code_block` | **`code_block_binding`**:`inputs`、`code`、**`outputs[]` + `target_field`**;代码体须能被规范识别 **`qf_output` 赋值** | **`auto_trigger`**、按钮文案;勿与 **`code_block_config.code_content`** 与 **`binding.code`** 冲突 |
|
|
50
|
+
|
|
51
|
+
别名:契约会把 `title`/`label` 映射到 **`name`** 等;建议直接用规范键。
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 3. `builder schema apply` 场景矩阵
|
|
56
|
+
|
|
57
|
+
| 场景 | 必备 CLI 参数 | 说明 |
|
|
58
|
+
|------|----------------|------|
|
|
59
|
+
| 编辑已有应用 | `--app-key`;可选 `--no-publish` | **不要**与 `--package-id`、`--create-if-missing` 同用 |
|
|
60
|
+
| 包内新建应用 | `--package-id`、`--app-name`(或 title 映射)、**`--create-if-missing`**;初始 `add-fields-file` 至少包含一个 `as_data_title: true` 字段 | 创建后可得到新 **`app_key`**(以响应为准) |
|
|
61
|
+
| 多应用一次性新建 | `--package-id`、**`--create-if-missing`**、`--apps-file` | 应用包/系统里有 2 个以上应用,或同批应用之间有 `relation` 时使用;`apps[].client_key` 可被 `target_app_ref` 引用 |
|
|
62
|
+
| 仅增字段 | `--add-fields-file`(JSON 数组) | 与 **`update_fields`/`remove_fields`** 可同次组合(以契约为准) |
|
|
63
|
+
| 改字段 | `--update-fields-file` | 每项 **`selector`**(`name`/`que_id`/`field_id`)+ **`set`** |
|
|
64
|
+
| 删字段 | `--remove-fields-file` | 每项至少 **`name`/`que_id`/`field_id`** 之一 |
|
|
65
|
+
| 可见性(新建/部分元数据) | `--visibility-file` | `mode` / `external_mode` / `selectors` 见交付文 §3.2 |
|
|
66
|
+
| 发布 | 默认或 `--publish`;探针常用 **`--no-publish`** | 与 **`app_publish_verify`** 配合 |
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 4. 仓库示例文件(单一完整清单)
|
|
71
|
+
|
|
72
|
+
| 内容 | 位置 |
|
|
73
|
+
|------|------|
|
|
74
|
+
| **19 种 `type` + `code_block` + `q_linker` + 1 个 `relation`(一次 `add_fields`)** | [schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json)(首字段已标记 `as_data_title`,附件字段已标记 `as_data_cover`;`relation.target_app_key` 须指向含「单行文字」「多行文字」的目标应用,默认 `ead8ims5i401`) |
|
|
75
|
+
| **`q_linker_example` / `code_block_example`**(契约内置形状) | `ai_builder_tools.py` 中 `app_schema_apply` 合约 |
|
|
76
|
+
| 最小新建字段(1 个 text 标题字段) | [schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json) |
|
|
77
|
+
| 历史 scalar / complex 批测(可选) | [_batch_schema_scalar.json](./_batch_schema_scalar.json)、[_batch_schema_complex.json](./_batch_schema_complex.json) |
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 5. 实跑结论
|
|
82
|
+
|
|
83
|
+
**一次性新建应用**:`--package-id` + `--app-name` + `--create-if-missing` + [schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json) 是当前推荐示例;它已包含唯一数据标题和可选数据封面(`q_linker` 使用 `https://httpbin.org/get`,`relation` 指向可读模板应用 `ead8ims5i401`)。
|
|
84
|
+
|
|
85
|
+
**一次性新建多个应用**:用 `builder schema apply --package-id <TAG_ID> --create-if-missing --apps-file tmp/apps.json`;`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用,工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径,尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景;不要为了拿 `app_key` 先逐个创建再二次补关联字段。
|
|
86
|
+
|
|
87
|
+
**限制(平台硬性)**:每应用 **至多一个** `relation`;`--app-key` 向已有应用追加时须 **字段名不重复**、且 **不能**在已有 relation 上再增第二个。**`example.com`** 作 `q_linker` URL 易触发 **`46031`**,本清单改用 httpbin。**读回缺 `outputs[].target_field` 的 `q_linker`** 会拖死后续 `schema apply`,须修复或删除该题。
|
|
88
|
+
|
|
89
|
+
**排障**:`--json`;**`DUPLICATE_FIELD`**;**`MULTIPLE_RELATION_FIELDS_UNSUPPORTED`(49614)**。
|
|
90
|
+
|
|
91
|
+
## 6. 交叉引用
|
|
92
|
+
|
|
93
|
+
- 交付主流程(读场 / 改场 / 发布):[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) **§6**(类型速查与 `relation`/`q_linker`/`code_block` 要点)。
|
|
94
|
+
- 记录读写 `kind`(与搭建 `type` 不同系):[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)。
|
|
95
|
+
- 主技能:[../SKILL.md](../SKILL.md)。
|