@qingflow-tech/qingflow-cli 1.0.16 → 1.0.17
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 +7 -7
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md +3 -2
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md +1 -1
- package/skills/qingflow-cli/reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md +3 -4
- package/src/qingflow_mcp/cli/commands/record.py +2 -0
- package/src/qingflow_mcp/cli/commands/task.py +28 -41
- package/src/qingflow_mcp/server.py +3 -3
- package/src/qingflow_mcp/server_app_user.py +3 -3
- package/src/qingflow_mcp/tools/record_tools.py +7 -2
- package/src/qingflow_mcp/tools/task_context_tools.py +39 -31
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.17
|
|
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.17 qingflow
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
Environment:
|
package/package.json
CHANGED
package/pyproject.toml
CHANGED
|
@@ -201,7 +201,7 @@ qingflow --json record list \
|
|
|
201
201
|
> tmp/qingflow_records.json
|
|
202
202
|
```
|
|
203
203
|
|
|
204
|
-
`record list` 默认最多返回 10
|
|
204
|
+
`record list` 默认最多返回 10 条,适合样本检查和模糊定位;需要更大或更小样本时用 `--page-size <N>`,但最终统计结论仍转 `record_access -> Python/pandas`。若用户只给出模糊文本,使用 `--query` 和可选 `--query-field <FIELD_ID>` 收窄候选,再用 `record get` 读详情。若用户明确要完整日志/审计历史,继续执行 `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> --view-id <VIEW_ID> > tmp/qingflow_record_logs.json`,再读取返回的 `data_logs.local_path` / `workflow_logs.local_path`。
|
|
205
205
|
|
|
206
206
|
**找应用包(Builder 管理面)**:默认直接用 **`builder package list --query <关键词>`**;它调用应用包后端 `/tag`,能看到空包、同名包和包级权限。拿到 `items[].package_id` 后再 `builder package get --package-id <ID>`。`package get` 会优先读 `/tag/{id}/baseInfo`,再尝试增强读取 `/tag/{id}`;若返回 `PACKAGE_DETAIL_READ_DEGRADED`,表示详细配置接口需要包编辑/加应用权限但基础信息已读到,不要当成包读取失败。旧版 CLI 没有该命令时,才看 **[reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) §2.3** 与 **[scripts/builder-package-from-app-list.py](./scripts/builder-package-from-app-list.py)**。
|
|
207
207
|
|
|
@@ -336,11 +336,11 @@ qingflow --json task list \
|
|
|
336
336
|
- 可选 `**--query**`:语义见上节「`--query`」;零条时可能是真无数据,也可能是未触发回退或关键词不匹配。
|
|
337
337
|
- **排序**:当前 `**qingflow task list` CLI 无 `--sort-by` / `--sort-direction`**;勿编造排序类参数。
|
|
338
338
|
2. **从列表下到详情 / 日志 / 报表 / 动作**
|
|
339
|
-
-
|
|
339
|
+
- **唯一默认路径**:列表 JSON 中取 `**task_id`**,使用 `**--task-id**`;它必须来自 `data.items[].task_id`,不是列表序号、record_id 或 workflow_node_id。示例:
|
|
340
340
|
`qingflow --json task get --task-id <TASK_ID> > tmp/qingflow_task_get.json`
|
|
341
|
-
-
|
|
341
|
+
- **不要自行凑三键**:`app_key / record_id / workflow_node_id` 只用于用户已明确提供完整 locator 的排障场景;普通执行不要从其它输出里猜。
|
|
342
342
|
- `**task report`**:除定位参数外 **必须** `--report-id`;支持 `**--page` / `--page-size`** 分页(见速查表)。
|
|
343
|
-
- 与「列表可省略 `--app-key
|
|
343
|
+
- 与「列表可省略 `--app-key`」不同:下钻单条默认必须有 `**task_id**`。
|
|
344
344
|
- `save_only` 可用性优先看当前节点 `editableQueIds`;只有该辅助接口 40002 / 40027 / 404 时才降级使用当前待办详情的 `queAuthSetting`,非权限类错误不要当成“节点不可保存”。
|
|
345
345
|
- 评论提及、退回候选、转交候选等辅助候选接口只有 40002 / 40027 / 404 可视为候选不可用;500 / auth 等非权限错误不要包装成权限边界。
|
|
346
346
|
3. **排查**
|
|
@@ -397,7 +397,7 @@ qingflow auth logout --forget-persisted
|
|
|
397
397
|
| 未登录 / profile 未登录 | **再**走「认证方式」节,重试业务命令 |
|
|
398
398
|
| `record_list requires view_id` | 先 `app get --app-key`,取 `view_id` |
|
|
399
399
|
| JSON 内 `backend_code` / `error_code` | 区分配额、权限与参数错误;普通成员见上节「偏向管理」;非本技能速查表覆盖的报错见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)** |
|
|
400
|
-
| `task get` / `task log` / `task report` / `task action` 报 config |
|
|
400
|
+
| `task get` / `task log` / `task report` / `task action` 报 config | 回到 `task list`,复制 `data.items[].task_id` 后再传 `--task-id`;不要用列表序号、record_id、workflow_node_id 或自行拼三键。详见 **「待办 … SOP」步骤 2** |
|
|
401
401
|
| 成员 + `custom:` 后纯数字视图 | 读数时**跳过**,换 `system:*` 或其它 `custom:*` |
|
|
402
402
|
| `record update` 报 **`apply_id must be positive`** 等而 `get`/`list` 正常 | 常为 **超大 `record_id`(超 JS 安全整数)** 下的 CLI 校验问题;见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)** |
|
|
403
403
|
|
|
@@ -417,10 +417,10 @@ qingflow auth logout --forget-persisted
|
|
|
417
417
|
| **auth** | `auth whoami` · `auth use-credential --base-url "$QINGFLOW_BASE_URL" --credential-stdin --persist` · `auth login …`(见「失败恢复时的认证方式」)· `auth logout --forget-persisted` |
|
|
418
418
|
| **workspace** | `workspace list` · `workspace get --ws-id` · `workspace select`(慎用,可读数前不必;可能 **59004**) |
|
|
419
419
|
| **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
|
-
| **record** | `record schema insert`(新建记录 insert-ready schema,仅 `--app-key`)· **`browse`/`list`/`access`:`--app-key` + `--view-id`(缺一常 CONFIG)** · `record list --query ... [--query-field FIELD_ID]`
|
|
420
|
+
| **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
421
|
| **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
422
|
| **builder** | **搭建/系统化配置**:`builder contract`、`builder icon catalog`、`app resolve`、`app get`(summary / fields / layout / views / flow / charts)、`schema`/`layout`/`flow apply`、`views apply`、`button apply`、`associated-resource apply`、`portal apply`、`portal delete`、`charts apply`、`publish verify`;与普通读数/`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
|
-
| **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
|
|
423
|
+
| **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
424
|
|
|
425
425
|
**高发必败**:旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。
|
|
426
426
|
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
| --- | --- | --- |
|
|
13
13
|
| `app_get`(列应用内可访问视图) | `qingflow --json app get --app-key <APP_KEY>` | 从返回体的 **`data`(若存在)** 内取 `accessible_views[]` |
|
|
14
14
|
| `record_schema_get`,`schema_mode=browse` | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>` | 子命令 **`browse`** 即「浏览视图」表结构 |
|
|
15
|
-
| `record_list` | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID> [--query 文本] [--query-field FIELD_ID]` | 样本浏览 / 模糊定位,默认最多返回 10 条;`query_fields` 是全文搜索字段范围 |
|
|
15
|
+
| `record_list` | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID> [--query 文本] [--query-field FIELD_ID] [--page-size N]` | 样本浏览 / 模糊定位,默认最多返回 10 条;`query_fields` 是全文搜索字段范围 |
|
|
16
16
|
| `record_get` | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 前端详情页首屏上下文:字段、首屏日志、引用、关联资源、图片与文件资产 |
|
|
17
17
|
| `record_logs_get` | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 单条记录全量可见数据日志 + 流程日志;自动分页写本地 JSONL,响应只返回摘要和文件路径 |
|
|
18
18
|
|
|
@@ -69,7 +69,7 @@ qingflow --json record list \
|
|
|
69
69
|
> tmp/qingflow_records.json
|
|
70
70
|
```
|
|
71
71
|
|
|
72
|
-
列表默认最多返回 10 条,行数据常见于 `$.data.items`;每条一般有 `record_id
|
|
72
|
+
列表默认最多返回 10 条,行数据常见于 `$.data.items`;每条一般有 `record_id`(及业务字段键值)。需要调整样本量时加 `--page-size <N>`;它只影响浏览/候选定位样本,不替代分析取数。响应会给出总数/下一步建议;如果是模糊定位,优先看 `lookup.total_count`、`lookup.next_action`。
|
|
73
73
|
|
|
74
74
|
**模糊定位示例**:
|
|
75
75
|
|
|
@@ -78,6 +78,7 @@ qingflow --json record list \
|
|
|
78
78
|
--app-key <APP_KEY> \
|
|
79
79
|
--view-id <VIEW_ID> \
|
|
80
80
|
--query "北京和路元" \
|
|
81
|
+
--page-size 20 \
|
|
81
82
|
--query-field 6299262 \
|
|
82
83
|
> tmp/qingflow_record_lookup.json
|
|
83
84
|
```
|
|
@@ -91,7 +91,7 @@
|
|
|
91
91
|
| 场景 | 一次成功写法 | 必填/注意 |
|
|
92
92
|
| ---- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
93
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>` |
|
|
94
|
+
| 待办详情 | `qingflow --json task get --task-id <TASK_ID>` | `<TASK_ID>` 必须来自 `task list` 的 `data.items[].task_id`;不要使用列表序号、record_id、workflow_node_id 或自行拼三键。 |
|
|
95
95
|
| 流程日志 | `qingflow --json task log --task-id <TASK_ID>` | 需有效 `**task-id`** 或等价组合。 |
|
|
96
96
|
| 关联报表 | `qingflow --json task report --task-id <TASK_ID> --report-id <REPORT_ID>` | `**report-id`** 需有效。 |
|
|
97
97
|
| 执行动作 | `qingflow task action --task-id <TASK_ID> --action <ACTION> ...` | **无 `--dry-run`**;属写操作,慎跑。 |
|
|
@@ -24,9 +24,8 @@
|
|
|
24
24
|
|
|
25
25
|
## 2. 定位方式(二选一,勿混用半截参数)
|
|
26
26
|
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
缺参时 CLI 会直接报 config:**要求 `--task-id`,或三者齐**。
|
|
27
|
+
- **唯一默认路径**:全程使用列表里拿到的 `**task_id`**(字符串十进制;与大雪花 ID 一致时保持 **引号 / JSON 字符串** 习惯,避免其它子系统精度问题)。`task_id` 必须来自 `task_list.data.items[].task_id`,不是列表序号、record_id 或 workflow_node_id。
|
|
28
|
+
- `app_key / record_id / workflow_node_id` 只用于用户已明确提供完整 locator 的排障场景;智能体不要从其它输出里自行拼三键。
|
|
30
29
|
|
|
31
30
|
---
|
|
32
31
|
|
|
@@ -92,7 +91,7 @@ qingflow --json task report \
|
|
|
92
91
|
> tmp/qingflow_task_report.json
|
|
93
92
|
```
|
|
94
93
|
|
|
95
|
-
- 定位方式与 `task get`
|
|
94
|
+
- 定位方式与 `task get` 相同:默认传 `task_list.data.items[].task_id`。
|
|
96
95
|
- 若关联项是 QingBI 报表,详情读取优先走前端同源的 **`/qingbi/charts/data/qflow/{chartId}/detail`**,再按 qflow `asos` 降级;只有 qflow 路由明确不存在/不适用时才退回旧 BI 数据接口。不要把中间 **`CHART_SEE` / 40002** 当成任务关联报表最终不可见。
|
|
97
96
|
|
|
98
97
|
### 3.5 `task_action_execute`(`task action`)
|
|
@@ -110,6 +110,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
|
|
|
110
110
|
list_parser.add_argument("--where-file")
|
|
111
111
|
list_parser.add_argument("--order-by-file")
|
|
112
112
|
list_parser.add_argument("--page", type=int, default=1)
|
|
113
|
+
list_parser.add_argument("--page-size", type=int, default=10)
|
|
113
114
|
list_parser.add_argument("--view-id")
|
|
114
115
|
list_parser.add_argument("--list-type", dest="legacy_list_type", type=int, help=argparse.SUPPRESS)
|
|
115
116
|
list_parser.add_argument("--view-key", dest="legacy_view_key", help=argparse.SUPPRESS)
|
|
@@ -367,6 +368,7 @@ def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
|
|
|
367
368
|
where=load_list_arg(args.where_file, option_name="--where-file"),
|
|
368
369
|
order_by=load_list_arg(args.order_by_file, option_name="--order-by-file"),
|
|
369
370
|
page=args.page,
|
|
371
|
+
page_size=args.page_size,
|
|
370
372
|
view_id=args.view_id,
|
|
371
373
|
)
|
|
372
374
|
|
|
@@ -47,20 +47,14 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
|
|
|
47
47
|
list_parser.add_argument("--page-size", type=int, default=20)
|
|
48
48
|
list_parser.set_defaults(handler=_handle_list, format_hint="task_list")
|
|
49
49
|
|
|
50
|
-
get = task_subparsers.add_parser("get", help="
|
|
51
|
-
get.add_argument("--task-id")
|
|
52
|
-
get.add_argument("--app-key")
|
|
53
|
-
get.add_argument("--record-id")
|
|
54
|
-
get.add_argument("--workflow-node-id", type=int)
|
|
50
|
+
get = task_subparsers.add_parser("get", help="读取待办详情;--task-id 必须来自 task list 的 data.items[].task_id")
|
|
51
|
+
get.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id;不是列表序号")
|
|
55
52
|
get.add_argument("--include-candidates", action=argparse.BooleanOptionalAction, default=True)
|
|
56
53
|
get.add_argument("--include-associated-reports", action=argparse.BooleanOptionalAction, default=True)
|
|
57
|
-
get.set_defaults(handler=_handle_get, format_hint="task_get")
|
|
54
|
+
get.set_defaults(handler=_handle_get, format_hint="task_get", app_key="", record_id="", workflow_node_id=0)
|
|
58
55
|
|
|
59
|
-
action = task_subparsers.add_parser("action", help="
|
|
60
|
-
action.add_argument("--task-id")
|
|
61
|
-
action.add_argument("--app-key")
|
|
62
|
-
action.add_argument("--record-id")
|
|
63
|
-
action.add_argument("--workflow-node-id", type=int)
|
|
56
|
+
action = task_subparsers.add_parser("action", help="执行待办动作;--task-id 必须来自 task list 的 data.items[].task_id")
|
|
57
|
+
action.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id;不是列表序号")
|
|
64
58
|
action.add_argument("--action", help="不传时在交互终端中选择当前待办可执行动作")
|
|
65
59
|
action.add_argument("--payload-file")
|
|
66
60
|
action.add_argument("--fields-file")
|
|
@@ -68,24 +62,27 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
|
|
|
68
62
|
handler=_handle_action,
|
|
69
63
|
format_hint="task_action_execute",
|
|
70
64
|
hide_effective_context_line=True,
|
|
65
|
+
app_key="",
|
|
66
|
+
record_id="",
|
|
67
|
+
workflow_node_id=0,
|
|
71
68
|
)
|
|
72
69
|
|
|
73
|
-
report = task_subparsers.add_parser("report", help="
|
|
74
|
-
report.add_argument("--task-id")
|
|
75
|
-
report.add_argument("--app-key")
|
|
76
|
-
report.add_argument("--record-id")
|
|
77
|
-
report.add_argument("--workflow-node-id", type=int)
|
|
70
|
+
report = task_subparsers.add_parser("report", help="读取待办关联报表详情;--task-id 必须来自 task list 的 data.items[].task_id")
|
|
71
|
+
report.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id;不是列表序号")
|
|
78
72
|
report.add_argument("--report-id", type=int, help="不传时在交互终端中选择关联报表")
|
|
79
73
|
report.add_argument("--page", type=int, default=1)
|
|
80
74
|
report.add_argument("--page-size", type=int, default=20)
|
|
81
|
-
report.set_defaults(
|
|
75
|
+
report.set_defaults(
|
|
76
|
+
handler=_handle_report,
|
|
77
|
+
format_hint="task_associated_report_detail_get",
|
|
78
|
+
app_key="",
|
|
79
|
+
record_id="",
|
|
80
|
+
workflow_node_id=0,
|
|
81
|
+
)
|
|
82
82
|
|
|
83
|
-
log = task_subparsers.add_parser("log", help="
|
|
84
|
-
log.add_argument("--task-id")
|
|
85
|
-
log.
|
|
86
|
-
log.add_argument("--record-id")
|
|
87
|
-
log.add_argument("--workflow-node-id", type=int)
|
|
88
|
-
log.set_defaults(handler=_handle_log, format_hint="")
|
|
83
|
+
log = task_subparsers.add_parser("log", help="读取流程日志;--task-id 必须来自 task list 的 data.items[].task_id")
|
|
84
|
+
log.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id;不是列表序号")
|
|
85
|
+
log.set_defaults(handler=_handle_log, format_hint="", app_key="", record_id="", workflow_node_id=0)
|
|
89
86
|
|
|
90
87
|
|
|
91
88
|
def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
|
|
@@ -243,30 +240,20 @@ def _run_task_workbench_task_loop(args: argparse.Namespace, context: CliContext)
|
|
|
243
240
|
def _resolve_task_locator_or_select(args: argparse.Namespace, context: CliContext, *, tool_name: str) -> dict | None:
|
|
244
241
|
if (args.task_id or "").strip():
|
|
245
242
|
return None
|
|
246
|
-
has_app_key = bool((args.app_key or "").strip())
|
|
247
|
-
has_record_id = bool((args.record_id or "").strip())
|
|
248
|
-
has_workflow_node_id = int(args.workflow_node_id or 0) > 0
|
|
249
|
-
if has_app_key and has_record_id and has_workflow_node_id:
|
|
250
|
-
return None
|
|
251
|
-
if has_app_key or has_record_id or has_workflow_node_id:
|
|
252
|
-
raise_config_error(
|
|
253
|
-
f"{tool_name} requires --task-id, or --app-key together with --record-id and --workflow-node-id",
|
|
254
|
-
fix_hint="Either pass `--task-id TASK_ID`, or provide the full locator triple `--app-key --record-id --workflow-node-id`.",
|
|
255
|
-
)
|
|
256
243
|
|
|
257
244
|
selection = _choose_todo_task_interactively(args, context, tool_name=tool_name)
|
|
258
245
|
if selection.status == "unavailable":
|
|
259
246
|
raise_config_error(
|
|
260
|
-
f"{tool_name} requires --task-id
|
|
247
|
+
f"{tool_name} requires --task-id from task list data.items[].task_id",
|
|
261
248
|
fix_hint=(
|
|
262
249
|
"Retry in an interactive terminal to choose from current todo tasks, "
|
|
263
|
-
"or pass `--task-id
|
|
250
|
+
"or pass `--task-id` from `task list` explicitly."
|
|
264
251
|
),
|
|
265
252
|
)
|
|
266
253
|
if selection.status == "empty":
|
|
267
254
|
raise_config_error(
|
|
268
255
|
selection.message or f"{tool_name} could not open a selector because no current todo tasks are available.",
|
|
269
|
-
fix_hint="Run `task list` to confirm current todo tasks,
|
|
256
|
+
fix_hint="Run `task list` to confirm current todo tasks, then pass the selected `data.items[].task_id`.",
|
|
270
257
|
)
|
|
271
258
|
if selection.status == "cancelled":
|
|
272
259
|
return cancelled_result(selection.message or "已取消")
|
|
@@ -327,7 +314,7 @@ def _choose_todo_task_interactively(
|
|
|
327
314
|
args,
|
|
328
315
|
title=title,
|
|
329
316
|
unavailable_message=(
|
|
330
|
-
f"{tool_name} requires --task-id
|
|
317
|
+
f"{tool_name} requires --task-id from task list data.items[].task_id"
|
|
331
318
|
),
|
|
332
319
|
empty_message=f"{tool_name} could not open a selector because no current todo tasks are available.",
|
|
333
320
|
load_options=load_options,
|
|
@@ -347,7 +334,7 @@ def _resolve_report_id_or_select(args: argparse.Namespace, context: CliContext)
|
|
|
347
334
|
if selection.status == "empty":
|
|
348
335
|
raise_config_error(
|
|
349
336
|
selection.message or "task report could not open a selector because the selected task has no visible associated reports.",
|
|
350
|
-
fix_hint="Run `task get --task-id
|
|
337
|
+
fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect `extras.associated_reports`, or choose another task.",
|
|
351
338
|
)
|
|
352
339
|
if selection.status == "cancelled":
|
|
353
340
|
return cancelled_result(selection.message or "已取消")
|
|
@@ -395,7 +382,7 @@ def _resolve_task_action_or_select(
|
|
|
395
382
|
if selection.status == "empty":
|
|
396
383
|
raise_config_error(
|
|
397
384
|
selection.message or "task action could not open an action selector because no interactive actions are available.",
|
|
398
|
-
fix_hint="Run `task get --task-id
|
|
385
|
+
fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect available_actions, or pass a supported `--action` explicitly.",
|
|
399
386
|
)
|
|
400
387
|
if selection.status == "cancelled":
|
|
401
388
|
return cancelled_result(selection.message or "已取消")
|
|
@@ -476,7 +463,7 @@ def _resolve_action_payload_or_select(
|
|
|
476
463
|
if selection.status == "empty":
|
|
477
464
|
raise_config_error(
|
|
478
465
|
selection.message or "task rollback could not open a selector because no rollback candidates are visible.",
|
|
479
|
-
fix_hint="Run `task get --task-id
|
|
466
|
+
fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect rollback candidates, or choose another action.",
|
|
480
467
|
)
|
|
481
468
|
if selection.status == "cancelled":
|
|
482
469
|
return cancelled_result(selection.message or "已取消")
|
|
@@ -493,7 +480,7 @@ def _resolve_action_payload_or_select(
|
|
|
493
480
|
if selection.status == "empty":
|
|
494
481
|
raise_config_error(
|
|
495
482
|
selection.message or "task transfer could not open a selector because no transfer candidates are visible.",
|
|
496
|
-
fix_hint="Run `task get --task-id
|
|
483
|
+
fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect transfer candidates, or choose another action.",
|
|
497
484
|
)
|
|
498
485
|
if selection.status == "cancelled":
|
|
499
486
|
return cancelled_result(selection.message or "已取消")
|
|
@@ -184,12 +184,12 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
|
|
|
184
184
|
`task_list -> task_get -> task_action_execute`
|
|
185
185
|
|
|
186
186
|
- `task_list` returns task-card summaries keyed by `task_id`.
|
|
187
|
-
-
|
|
188
|
-
- `
|
|
187
|
+
- For detail reads and actions, pass the exact `task_id` from `task_list.data.items[].task_id`.
|
|
188
|
+
- `task_id` is not a row number, list index, record id, or workflow node id.
|
|
189
|
+
- Do not reconstruct task actions from `app_key + record_id + workflow_node_id` unless the user explicitly provides that full locator for troubleshooting.
|
|
189
190
|
- `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
|
|
190
191
|
- Use `task_associated_report_detail_get` for associated view or report details.
|
|
191
192
|
- Use `task_workflow_log_get` for the current task context workflow log page. For full record-level data/workflow logs, first choose an accessible view with `app_get`, then call `record_logs_get(app_key, record_id, view_id)` with that same explicit `view_id`.
|
|
192
|
-
- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
|
|
193
193
|
|
|
194
194
|
## Time Handling
|
|
195
195
|
|
|
@@ -189,12 +189,12 @@ Use export only when the user explicitly asks to export/download/generate an Exc
|
|
|
189
189
|
`task_list -> task_get -> task_action_execute`
|
|
190
190
|
|
|
191
191
|
- `task_list` returns task-card summaries keyed by `task_id`.
|
|
192
|
-
-
|
|
193
|
-
- `
|
|
192
|
+
- For detail reads and actions, pass the exact `task_id` from `task_list.data.items[].task_id`.
|
|
193
|
+
- `task_id` is not a row number, list index, record id, or workflow node id.
|
|
194
|
+
- Do not reconstruct task actions from `app_key + record_id + workflow_node_id` unless the user explicitly provides that full locator for troubleshooting.
|
|
194
195
|
- `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
|
|
195
196
|
- Use `task_associated_report_detail_get` for associated view or report details.
|
|
196
197
|
- Use `task_workflow_log_get` for the current task context workflow log page. For full record-level data/workflow logs, first choose an accessible view with `app_get`, then call `record_logs_get(app_key, record_id, view_id)` with that same explicit `view_id`.
|
|
197
|
-
- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
|
|
198
198
|
- Treat `task_action_execute` as the tool-level action enum surface; the current task's real actions are only the ones listed in `task_get.capabilities.available_actions`.
|
|
199
199
|
- Use `task_action_execute(action="save_only", fields=...)` when the user wants to save editable field changes on the current node without advancing the workflow.
|
|
200
200
|
- `save_only` is exposed only when the backend current-node `editableQueIds` signal returns a non-empty result; MCP no longer infers `save_only` from local schema reconstruction.
|
|
@@ -438,6 +438,7 @@ class RecordTools(ToolBase):
|
|
|
438
438
|
where: list[JSONObject] | None = None,
|
|
439
439
|
order_by: list[JSONObject] | None = None,
|
|
440
440
|
page: int = 1,
|
|
441
|
+
page_size: int = DEFAULT_RECORD_LIST_RETURN_LIMIT,
|
|
441
442
|
view_id: str | None = None,
|
|
442
443
|
output_profile: str = "normal",
|
|
443
444
|
) -> JSONObject:
|
|
@@ -450,6 +451,7 @@ class RecordTools(ToolBase):
|
|
|
450
451
|
where=where or [],
|
|
451
452
|
order_by=order_by or [],
|
|
452
453
|
page=page,
|
|
454
|
+
page_size=page_size,
|
|
453
455
|
view_id=view_id,
|
|
454
456
|
list_type=None,
|
|
455
457
|
view_key=None,
|
|
@@ -1881,6 +1883,7 @@ class RecordTools(ToolBase):
|
|
|
1881
1883
|
order_by: list[JSONObject],
|
|
1882
1884
|
limit: int = DEFAULT_RECORD_LIST_RETURN_LIMIT,
|
|
1883
1885
|
page: int = 1,
|
|
1886
|
+
page_size: int = DEFAULT_RECORD_LIST_RETURN_LIMIT,
|
|
1884
1887
|
view_id: str | None = None,
|
|
1885
1888
|
list_type: int | None = None,
|
|
1886
1889
|
view_key: str | None = None,
|
|
@@ -1899,6 +1902,8 @@ class RecordTools(ToolBase):
|
|
|
1899
1902
|
raise_tool_error(QingflowApiError.config_error("limit must be positive"))
|
|
1900
1903
|
if page <= 0:
|
|
1901
1904
|
raise_tool_error(QingflowApiError.config_error("page must be positive"))
|
|
1905
|
+
if page_size <= 0:
|
|
1906
|
+
raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
|
|
1902
1907
|
if not (
|
|
1903
1908
|
_normalize_optional_text(view_id)
|
|
1904
1909
|
or list_type is not None
|
|
@@ -1971,12 +1976,12 @@ class RecordTools(ToolBase):
|
|
|
1971
1976
|
app_key=app_key,
|
|
1972
1977
|
view_route=view_route,
|
|
1973
1978
|
page_num=page,
|
|
1974
|
-
page_size=
|
|
1979
|
+
page_size=page_size,
|
|
1975
1980
|
query_key=normalized_query,
|
|
1976
1981
|
search_que_ids=resolved_query_fields or None,
|
|
1977
1982
|
match_rules=match_rules,
|
|
1978
1983
|
sort_rules=sort_rules,
|
|
1979
|
-
max_rows=limit,
|
|
1984
|
+
max_rows=min(limit, page_size),
|
|
1980
1985
|
selected_fields=selected_fields,
|
|
1981
1986
|
output_profile="verbose" if normalized_output_profile in {"verbose", "normalized"} else DEFAULT_OUTPUT_PROFILE,
|
|
1982
1987
|
)
|
|
@@ -85,33 +85,37 @@ class TaskContextTools(ToolBase):
|
|
|
85
85
|
page_size=page_size,
|
|
86
86
|
)
|
|
87
87
|
|
|
88
|
-
@mcp.tool(
|
|
88
|
+
@mcp.tool(
|
|
89
|
+
description=(
|
|
90
|
+
"Read one workflow task. Prefer task_id from task_list.data.items[].task_id; "
|
|
91
|
+
"task_id is not a row number, list index, record id, or workflow node id."
|
|
92
|
+
)
|
|
93
|
+
)
|
|
89
94
|
def task_get(
|
|
90
95
|
profile: str = DEFAULT_PROFILE,
|
|
91
96
|
task_id: str = "",
|
|
92
|
-
app_key: str = "",
|
|
93
|
-
record_id: str = "",
|
|
94
|
-
workflow_node_id: int = 0,
|
|
95
97
|
include_candidates: bool = True,
|
|
96
98
|
include_associated_reports: bool = True,
|
|
97
99
|
) -> dict[str, Any]:
|
|
98
100
|
return self.task_get(
|
|
99
101
|
profile=profile,
|
|
100
102
|
task_id=task_id,
|
|
101
|
-
app_key=
|
|
102
|
-
record_id=
|
|
103
|
-
workflow_node_id=
|
|
103
|
+
app_key="",
|
|
104
|
+
record_id="",
|
|
105
|
+
workflow_node_id=0,
|
|
104
106
|
include_candidates=include_candidates,
|
|
105
107
|
include_associated_reports=include_associated_reports,
|
|
106
108
|
)
|
|
107
109
|
|
|
108
|
-
@mcp.tool(
|
|
110
|
+
@mcp.tool(
|
|
111
|
+
description=(
|
|
112
|
+
self._high_risk_tool_description(operation="execute", target="workflow task action")
|
|
113
|
+
+ " Pass task_id from task_list.data.items[].task_id. Do not pass a row number, list index, record id, or workflow node id as task_id."
|
|
114
|
+
)
|
|
115
|
+
)
|
|
109
116
|
def task_action_execute(
|
|
110
117
|
profile: str = DEFAULT_PROFILE,
|
|
111
118
|
task_id: str = "",
|
|
112
|
-
app_key: str = "",
|
|
113
|
-
record_id: str = "",
|
|
114
|
-
workflow_node_id: int = 0,
|
|
115
119
|
action: str = "",
|
|
116
120
|
payload: dict[str, Any] | None = None,
|
|
117
121
|
fields: dict[str, Any] | None = None,
|
|
@@ -119,21 +123,23 @@ class TaskContextTools(ToolBase):
|
|
|
119
123
|
return self.task_action_execute(
|
|
120
124
|
profile=profile,
|
|
121
125
|
task_id=task_id,
|
|
122
|
-
app_key=
|
|
123
|
-
record_id=
|
|
124
|
-
workflow_node_id=
|
|
126
|
+
app_key="",
|
|
127
|
+
record_id="",
|
|
128
|
+
workflow_node_id=0,
|
|
125
129
|
action=action,
|
|
126
130
|
payload=payload or {},
|
|
127
131
|
fields=fields or {},
|
|
128
132
|
)
|
|
129
133
|
|
|
130
|
-
@mcp.tool(
|
|
134
|
+
@mcp.tool(
|
|
135
|
+
description=(
|
|
136
|
+
"Read a task-associated report. Pass task_id from task_list.data.items[].task_id; "
|
|
137
|
+
"task_id is not a row number, list index, record id, or workflow node id."
|
|
138
|
+
)
|
|
139
|
+
)
|
|
131
140
|
def task_associated_report_detail_get(
|
|
132
141
|
profile: str = DEFAULT_PROFILE,
|
|
133
142
|
task_id: str = "",
|
|
134
|
-
app_key: str = "",
|
|
135
|
-
record_id: str = "",
|
|
136
|
-
workflow_node_id: int = 0,
|
|
137
143
|
report_id: int = 0,
|
|
138
144
|
page: int = 1,
|
|
139
145
|
page_size: int = 20,
|
|
@@ -141,28 +147,30 @@ class TaskContextTools(ToolBase):
|
|
|
141
147
|
return self.task_associated_report_detail_get(
|
|
142
148
|
profile=profile,
|
|
143
149
|
task_id=task_id,
|
|
144
|
-
app_key=
|
|
145
|
-
record_id=
|
|
146
|
-
workflow_node_id=
|
|
150
|
+
app_key="",
|
|
151
|
+
record_id="",
|
|
152
|
+
workflow_node_id=0,
|
|
147
153
|
report_id=report_id,
|
|
148
154
|
page=page,
|
|
149
155
|
page_size=page_size,
|
|
150
156
|
)
|
|
151
157
|
|
|
152
|
-
@mcp.tool(
|
|
158
|
+
@mcp.tool(
|
|
159
|
+
description=(
|
|
160
|
+
"Read workflow log for one task context. Pass task_id from task_list.data.items[].task_id; "
|
|
161
|
+
"task_id is not a row number, list index, record id, or workflow node id."
|
|
162
|
+
)
|
|
163
|
+
)
|
|
153
164
|
def task_workflow_log_get(
|
|
154
165
|
profile: str = DEFAULT_PROFILE,
|
|
155
166
|
task_id: str = "",
|
|
156
|
-
app_key: str = "",
|
|
157
|
-
record_id: str = "",
|
|
158
|
-
workflow_node_id: int = 0,
|
|
159
167
|
) -> dict[str, Any]:
|
|
160
168
|
return self.task_workflow_log_get(
|
|
161
169
|
profile=profile,
|
|
162
170
|
task_id=task_id,
|
|
163
|
-
app_key=
|
|
164
|
-
record_id=
|
|
165
|
-
workflow_node_id=
|
|
171
|
+
app_key="",
|
|
172
|
+
record_id="",
|
|
173
|
+
workflow_node_id=0,
|
|
166
174
|
)
|
|
167
175
|
|
|
168
176
|
@tool_cn_name("任务上下文列表")
|
|
@@ -1302,14 +1310,14 @@ class TaskContextTools(ToolBase):
|
|
|
1302
1310
|
searched = ", ".join(incomplete_task_boxes)
|
|
1303
1311
|
raise_tool_error(
|
|
1304
1312
|
QingflowApiError.config_error(
|
|
1305
|
-
f"task_id={task_id_text} resolved to an incomplete task locator in task_box={searched};
|
|
1313
|
+
f"task_id={task_id_text} resolved to an incomplete task locator in task_box={searched}; rerun task_list and pass the exact data.items[].task_id. Do not substitute a row number or rebuild the locator from app_key/record_id/workflow_node_id."
|
|
1306
1314
|
)
|
|
1307
1315
|
)
|
|
1308
1316
|
if inaccessible_task_boxes:
|
|
1309
1317
|
searched = ", ".join(str(item.get("task_box")) for item in inaccessible_task_boxes)
|
|
1310
1318
|
raise_tool_error(
|
|
1311
1319
|
QingflowApiError.config_error(
|
|
1312
|
-
f"task_id={task_id_text} was not found in visible task boxes; some task boxes were not searchable in the current permission context: {searched}",
|
|
1320
|
+
f"task_id={task_id_text} was not found in visible task boxes; some task boxes were not searchable in the current permission context: {searched}. Rerun task_list and use data.items[].task_id; do not substitute a row number or rebuild the locator.",
|
|
1313
1321
|
details={
|
|
1314
1322
|
"task_id": task_id_text,
|
|
1315
1323
|
"searched_task_boxes": list(searched_task_boxes),
|
|
@@ -1319,7 +1327,7 @@ class TaskContextTools(ToolBase):
|
|
|
1319
1327
|
)
|
|
1320
1328
|
raise_tool_error(
|
|
1321
1329
|
QingflowApiError.config_error(
|
|
1322
|
-
f"task_id={task_id_text} was not found in the current visible task boxes (todo, initiated, cc, done)"
|
|
1330
|
+
f"task_id={task_id_text} was not found in the current visible task boxes (todo, initiated, cc, done). Rerun task_list and pass data.items[].task_id; do not use the displayed row number or guess app_key/record_id/workflow_node_id."
|
|
1323
1331
|
)
|
|
1324
1332
|
)
|
|
1325
1333
|
|