@qingflow-tech/qingflow-cli 1.0.15 → 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 CHANGED
@@ -3,13 +3,13 @@
3
3
  Install:
4
4
 
5
5
  ```bash
6
- npm install @qingflow-tech/qingflow-cli@1.0.15
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.15 qingflow
12
+ npx -y -p @qingflow-tech/qingflow-cli@1.0.17 qingflow
13
13
  ```
14
14
 
15
15
  Environment:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qingflow-tech/qingflow-cli",
3
- "version": "1.0.15",
3
+ "version": "1.0.17",
4
4
  "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "qingflow-mcp"
7
- version = "1.0.15"
7
+ version = "1.0.17"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -26,7 +26,7 @@ description: |
26
26
  | [reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) | **搭建侧·应用交付 SOP**(**创建/改造应用底色**:解析包与应用、读写字段布局流程、一键改 schema·layout·flow、按钮与关联资源、**`publish verify`**):`app_get` 应用地图 → `app_resolve` → `app_read_*` → **`schema`/`layout`/`flow apply`** / **`app_custom_buttons_apply`** / **`app_associated_resources_apply`**;字段 JSON 支持 **`as_data_title` / `as_data_cover`** |
27
27
  | [reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md) | **搭建侧·工作区图标**:`builder icon catalog`;新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color`,CLI 只校验候选,不按业务名自动映射 |
28
28
  | [reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md) | **搭建侧·业务视图 SOP**:`app_get` / `app get fields|views` → **`builder views apply`**;区分 `filters` 与 **`query_conditions`**;关联视图/报表走 **`app_associated_resources_apply`**,按钮走 **`app_custom_buttons_apply`** |
29
- | [reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md) | **搭建侧·门户工作台 SOP**(**工作台/门户页面搭建与发布**):**`portal list/get/apply`**、**`--publish`**;**`filter`** 的 CLI 限制见该文 §3.4;示例 [portal_sections_five_types.example.json](./reference/portal_sections_five_types.example.json);契约 **`builder contract --tool-name portal_apply`** |
29
+ | [reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md) | **搭建侧·门户工作台 SOP**(**工作台/门户页面搭建、发布与删除**):**`portal list/get/apply/delete`**、**`--publish`**;删除结果要区分 `delete_executed` 与 `readback_status`;**`filter`** 的 CLI 限制见该文 §3.4;示例 [portal_sections_five_types.example.json](./reference/portal_sections_five_types.example.json);契约 **`builder contract --tool-name portal_apply` / `portal_delete`** |
30
30
  | [reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md) | **搭建侧·报表 QingBI/BI SOP**(**系统内报表/图表的创建、改配与排序**):**`charts apply`**;应用源报表创建/更新、数据集报表仅关联已有、扩展图表类型与特殊字段映射、**immediate-live** 与 **`publish verify`** 关系见该文;示例 [charts_upsert_minimal.example.json](./reference/charts_upsert_minimal.example.json) 等 |
31
31
  | [reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md) | **搭建侧·字段匹配规则**:按钮新增数据 `field_mappings`、关联视图/报表 `match_mappings`、`数据ID(-17)` / `编号(0)`、类型兼容与 `associated_item_id` 口径。 |
32
32
  | [reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | **新建记录**:默认转交 `qingflow-record-insert`;标准链路 `record_insert_schema_get -> record_insert(items)`,CLI 用 **`record insert --items-file`**;成员/部门/关联优先自然语言输入 |
@@ -113,7 +113,7 @@ qingflow --json auth whoami
113
113
  | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
114
114
  | **task** | `list`、`get`、`log`、`report` |
115
115
  | **import** | `template`、`verify`、`repair`、`start`、`status`(**`verify` / `start` 链依赖本机 `~/.qingflow-mcp` 校验/任务落盘,自动化须开放写权限**) |
116
- | **builder** | **`app get`(summary/app map、fields、layout、views、flow、charts;summary 含 `custom_buttons` / `associated_resources`)**、`contract`;以及 **`schema apply` / `layout apply` / `views apply` / `button apply` / `associated-resource apply` / `flow apply` / `charts apply` / `portal apply` / `publish verify` / `package apply`** 等大 JSON 响应 |
116
+ | **builder** | **`app get`(summary/app map、fields、layout、views、flow、charts;summary 含 `custom_buttons` / `associated_resources`)**、`contract`;以及 **`schema apply` / `layout apply` / `views apply` / `button apply` / `associated-resource apply` / `flow apply` / `charts apply` / `portal apply` / `portal delete` / `publish verify` / `package apply`** 等大 JSON 响应 |
117
117
  | **record** | `list`、`get`、`logs`、`access`、`schema browse`;以及 `schema insert` / `schema update` / `schema import` / `schema code-block` 等大体积 schema 子命令(体量大时同上);**创建前列字段时用 `schema insert` / `record_insert_schema_get` 同上**;**写操作 `insert` / `update` 响应体大时同样建议落盘** |
118
118
 
119
119
 
@@ -201,7 +201,7 @@ qingflow --json record list \
201
201
  > tmp/qingflow_records.json
202
202
  ```
203
203
 
204
- `record list` 默认最多返回 10 条,适合样本检查和模糊定位;若用户只给出模糊文本,使用 `--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`。
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
- - **推荐**:列表 JSON 中取 `**task_id`**,使用 `**--task-id**`(`get` / `log` / `report` / `action` 的帮助均写「推荐直接传 `--task-id`」)。示例:
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
- - **备选(与 `--task-id` 二选一,勿混用缺参)**:同时提供 `**--app-key`**、`**--record-id**`、`**--workflow-node-id**`(**三者缺一不可**),否则 CLI 会在执行前报 **config** 类错误。
341
+ - **不要自行凑三键**:`app_key / record_id / workflow_node_id` 只用于用户已明确提供完整 locator 的排障场景;普通执行不要从其它输出里猜。
342
342
  - `**task report`**:除定位参数外 **必须** `--report-id`;支持 `**--page` / `--page-size`** 分页(见速查表)。
343
- - 与「列表可省略 `--app-key`」不同:下钻单条时要么有 `**task_id**`,要么凑齐 **应用 + 记录 + 节点** 三键。
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 | **要么**提供 `--task-id`,**要么**同时具备 `--app-key`、`--record-id`、`--workflow-node-id`(缺一不可);详见 **「待办 … SOP」步骤 2** |
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]` 用于候选定位 · `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` |
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
- | **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`、`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`**:优先 **`--task-id`**,否则 **`--app-key`、`--record-id`、`--workflow-node-id` 须同时具备** · **`report`**:另须必选 **`--report-id`** · **`action`**:**无 `--dry-run`** |
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`/`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
 
@@ -1,12 +1,12 @@
1
1
  # Builder 门户创建与变更 SOP:`qingflow builder portal`
2
2
 
3
- 搭建侧稳定入口:**`qingflow builder portal`**:`list` / `get` / **`apply`**(与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同,见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**)。
3
+ 搭建侧稳定入口:**`qingflow builder portal`**:`list` / `get` / **`apply`** / **`delete`**(与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同,见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**)。
4
4
 
5
- 实现要点来自 CLI 打包内的 `builder_facade/models.py`(`PortalApplyRequest`、`PortalSectionPatch`)、`builder_facade/service.py`(`portal_apply`)、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**:**新建**(`--no-publish`)、**`--publish` 更新**(网关 **503** 恢复后已重试成功)、**五类区块可稳定落库**;**`filter`(`type:6`)经 CLI 直传未落库** 见 **§3.4 / §8**。
5
+ 实现要点来自 CLI 打包内的 `builder_facade/models.py`(`PortalApplyRequest`、`PortalSectionPatch`)、`builder_facade/service.py`(`portal_apply` / `portal_delete`)、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**:**新建**(`--no-publish`)、**`--publish` 更新**(网关 **503** 恢复后已重试成功)、**五类区块可稳定落库**;**`filter`(`type:6`)经 CLI 直传未落库** 见 **§3.4 / §8**。另已对测试包 **`1414907`** 实跑 **`portal delete`**:临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
6
6
 
7
7
  > **权限**:**更新**需 **`edit_portal`**;**新建**按后端 `DashCtrl.createDash` 链路只预检目标包 **`add_app`**,不额外要求包 **`edit_app`**。失败时参见主技能与 **ADMIN** 速查。
8
8
 
9
- > **契约**:`qingflow --json builder contract --tool-name portal_apply`
9
+ > **契约**:`qingflow --json builder contract --tool-name portal_apply`;删除契约:`qingflow --json builder contract --tool-name portal_delete`
10
10
 
11
11
  ---
12
12
 
@@ -155,7 +155,21 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart_ref`**;**view**
155
155
 
156
156
  ---
157
157
 
158
- ## 7. **发布**(`--publish`)
158
+ ## 7. 删除:`delete`
159
+
160
+ ```bash
161
+ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_portal_delete.json
162
+ ```
163
+
164
+ - **只按 `dash_key` 删除一个门户**;先用 `builder portal list/get` 确认目标,不要按名称猜。
165
+ - 返回成功时重点看:**`delete_executed`**、**`readback_status`**、**`safe_to_retry_delete`**、`summary.removed`。
166
+ - **`delete_executed=true` + `readback_status=deleted`**:删除已执行且回读确认不存在。
167
+ - **`delete_executed=true` + `readback_status=unavailable|still_exists`**:DELETE 已发出,但回读不可确认或短时间仍存在;**不要盲目重复删除**,稍后用 `builder portal get/list` 确认。
168
+ - DELETE 本身失败时才按 `status=failed` / `error_code` 处理。
169
+
170
+ ---
171
+
172
+ ## 8. **发布**(`--publish`)
159
173
 
160
174
  - **默认会发布**:未显式 **`--no-publish`** 即 **`publish: true`**;公开入口仍是 **`portal_apply`**,发布动作由工具内部执行并回读 **`being_draft=false`**。
161
175
  - **已发布线索**:成功路径上 **`published: true`**;**`live_result.publishStatus`** 常见 **`2`** 表示已发布(以你环境枚举为准)。
@@ -164,7 +178,7 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart_ref`**;**view**
164
178
 
165
179
  ---
166
180
 
167
- ## 8. 本环境实测摘要
181
+ ## 9. 本环境实测摘要
168
182
 
169
183
  | 步骤 | 命令要点 | 结果 |
170
184
  |------|-----------|------|
@@ -173,12 +187,13 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart_ref`**;**view**
173
187
  | 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**;**`filter` 仍不落库** → **`partial_success`**,**`components expected 6, got 5`**(与 **§3.4** 一致) |
174
188
  | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合 | **回读恒为 1 块(仅 `type: 9`)** |
175
189
  | **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](./portal_sections_five_types.example.json)**(**grid / text / link / view / chart**) | **`status: success`**,**`types: [2,4,5,9,10]`**,**`published: true`** |
190
+ | 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**,**`delete_executed: true`**,**`readback_status: deleted`**,**`summary.removed: 1`** |
176
191
 
177
192
  **含 `filter` 的六类示例(`filter` 是否落库视环境/后端而定)**:[portal_sections_all_types.example.json](./portal_sections_all_types.example.json)
178
193
 
179
194
  ---
180
195
 
181
- ## 9. 排障
196
+ ## 10. 排障
182
197
 
183
198
  | 现象 | 处理 |
184
199
  |------|------|
@@ -188,10 +203,11 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart_ref`**;**view**
188
203
  | **503** | 网关/运维;稍后重试。 |
189
204
  | 缺 **chart** | **[QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)**:`builder charts apply`;或换有报表的应用。 |
190
205
  | **VISIBILITY_CONFLICT** | 只用 **`--visibility-file`**。 |
206
+ | `delete_executed=true` 但 `readback_status=unavailable|still_exists` | DELETE 已发出,回读未确认;不要重复删除,稍后 `builder portal get/list` 复核。 |
191
207
 
192
208
  ---
193
209
 
194
- ## 10. 交叉引用
210
+ ## 11. 交叉引用
195
211
 
196
212
  - [SKILL.md](../SKILL.md)
197
213
  - [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)
@@ -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`(及业务字段键值)。响应会给出总数/下一步建议;如果是模糊定位,优先看 `lookup.total_count`、`lookup.next_action`。
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>` | **或** 使用帮助中 `**--app-key` + `--record-id` (+ `--workflow-node-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
- - **推荐**:全程使用列表里拿到的 `**task_id`**(字符串十进制;与大雪花 ID 一致时保持 **引号 / JSON 字符串** 习惯,避免其它子系统精度问题)。
28
- - **备选**:无 `task_id` 时,**同时**提供 `--app-key`、`--record-id`、`--workflow-node-id`,缺一不可。
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` 相同(`--task-id` 或 三键)。
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="读取待办详情;推荐直接传 --task-id")
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="读取待办关联报表详情;推荐直接传 --task-id")
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(handler=_handle_report, format_hint="task_associated_report_detail_get")
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="读取流程日志;推荐直接传 --task-id")
84
- log.add_argument("--task-id")
85
- log.add_argument("--app-key")
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, or --app-key together with --record-id and --workflow-node-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 TASK_ID` explicitly."
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, or retry later with `--task-id TASK_ID`.",
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, or --app-key together with --record-id and --workflow-node-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 TASK_ID` to inspect `extras.associated_reports`, or choose another task.",
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 TASK_ID` to inspect available_actions, or pass a supported `--action` explicitly.",
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 TASK_ID` to inspect rollback candidates, or choose another action.",
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 TASK_ID` to inspect transfer candidates, or choose another action.",
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
- - Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
188
- - `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
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
- - Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
193
- - `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
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=DEFAULT_LIST_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=app_key,
102
- record_id=record_id,
103
- workflow_node_id=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(description=self._high_risk_tool_description(operation="execute", target="workflow task action"))
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=app_key,
123
- record_id=record_id,
124
- workflow_node_id=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=app_key,
145
- record_id=record_id,
146
- workflow_node_id=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=app_key,
164
- record_id=record_id,
165
- workflow_node_id=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}; please refresh the task list and retry"
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