@josephyan/qingflow-cli 1.0.11 → 1.1.2

package/skills/qingflow-cli/SKILL.md

@@ -0,0 +1,440 @@
+---
+name: qingflow-cli
+description: |
+  【强制】在执行或编排任何 qingflow CLI 命令前必须优先加载本 Skill。
+  指导安装、执行上下文失败恢复、查询与写入；规定 task/record/import/builder 查询落盘；覆盖普通成员读数、字段 kind 与数据形态、任务上下文、批量导入、record access/list/get/insert/update 与管理端边界。
+  Builder SOP 对应「搭建应用与流程」「创建字段与系统列」「改布局视图门户报表」「按钮与关联资源」「发布与校验」等搭建/创建/系统化配置需求，与仅用 record 读写不同；明细见「关联文件」表与文末命令索引。
+---
+
+# Qingflow CLI 使用技能
+
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
+
+**硬约束（必读）**：正文各节与文末「命令速查」中的命令**只作子命令形态索引**，不覆盖 JSON 结构、`--*-file` 键名、枚举全集、执行顺序与排障细节。凡工作**偏复杂**（多步串联、大块 payload、导入全链、**Builder 搭建向**（应用/schema/流程/布局/视图/门户/报表/按钮/关联资源的配置与发布、系统列与字段 `type`）、契约型 `apply`、按 schema 组织写入 payload、任务下钻与 `task action` 等），或你判断当前任务与「关联文件」里某篇所描述的内容**需求一致、场景相同或大体同类**，都应**先 Read 对应 `reference/*.md`**，再结合 `qingflow … --help` 与 **[EXPLORATION_REPORT](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。**禁止**仅凭索引、习惯或类比去补参数、臆造字段名或推断服务端行为。**最终统计结论、分析报告、趋势/排名/比例/分布等数据分析，必须转交 `qingflow-record-analysis`，统一走 `record_access -> Python/pandas`。**
+
+> **CLI**：当前验证包为 `@qingflow-tech/qingflow-cli`（查版本优先用 `qingflow --version`；需要 JSON 时用 `qingflow --json version`）。**搭建/创建/系统配置**：先区分 **完整系统/应用包** 与 **单应用**。完整系统主链路必须走 `builder package apply -> builder schema apply --apps-file`，并用 `apps[].client_key + relation.target_app_ref` 处理同批跨应用关联；单应用才走 `builder schema apply --app-key` 或 `--package-id --app-name --create-if-missing`。完整系统 schema apply 超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时，下一步固定是 **`readback_before_retry`**（`package get` / `app resolve` / `app get fields`），禁止直接拆成单应用重建、用 V2/测试/随机后缀绕过重名或重放整批创建；随后再按 **[APP_DELIVERY](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)** → **[VIEWS](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)** / **[PORTAL](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)** / **[CHARTS](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)** 选读。仅成员读数速通仍可先打开 **[MEMBER_CHEATSHEET](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**。
+
+## 关联文件
+
+
+| 文件                                                                                               | 说明                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `manifest.yaml`                                                                                  | 技能清单                                                                                                                                                                                                                                                                                  |
+| [reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)     | **普通成员**主线：最短路径、`view_id`、与管理命令的差异预期                                                                                                                                                                                                                                                  |
+| [reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md)       | **字段数据类型**：`record schema …` 的 `fields[]`（`field_id`、`title`、`kind`、`options`…）；`record list/get/access` 与写入 payload 的形态对照                                                                                                                                                                    |
+| [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **应用记录获取数据**：`app get`（`accessible_views`）→ `record schema browse` → `record list(query)` 模糊定位 / `record get` 详情页首屏上下文 / `record logs` 全量日志；分析取数转 `record_access`                                                                                                                                                                        |
+| [reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md](./reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md) | **任务(待办已办)上下文 SOP**：`task_list` → `task_get` → `task_workflow_log_get`（`task log`）→ `task_associated_report_detail_get`（`task report`）→ `task_action_execute`（`task action`）；与 MCP 命名对照                                                                                               |
+| [reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) | **批量导入 SOP**：`app_get`（**`import_capability`**）→ `record_import_template_get` → `record_import_verify` →（可选）`record_import_repair_local` → `record_import_start` → `record_import_status_get`；CLI `import` / `record schema import`                                                   |
+| [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`** |
+| [reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md) | **搭建侧·工作区图标**：`builder icon catalog`；新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color`，CLI 只校验候选，不按业务名自动映射 |
+| [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`** |
+| [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_standard_workbench.example.json](./reference/portal_sections_standard_workbench.example.json)，稳定五类示例 [portal_sections_five_types.example.json](./reference/portal_sections_five_types.example.json)；契约 **`builder contract --tool-name portal_apply` / `portal_delete`**                   |
+| [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) 等                                                                             |
+| [reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md) | **搭建侧·字段匹配规则**：按钮新增数据 `field_mappings`、关联视图/报表 `match_mappings`、`数据ID(-17)` / `编号(0)`、类型兼容与 `associated_item_id` 口径。 |
+| [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`**；成员/部门/关联优先自然语言输入 |
+| [reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md) | **更新记录**：主链路是 `record get` → 智能体按 `fields[]` 组 key/value → **`record update`**；`record schema update` 仅用于失败后诊断可写字段/路径                                                                                                                                 |
+| [reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)       | **管理员**：检索、导入等与成员差异（主技能正文不展开）                                                                                                                                                                                                                                                         |
+| [reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)   | CLI 实测与 argparse/服务端对齐备忘                                                                                                                                                                                                                                                              |
+| [reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md) | **可选**：全角色「一次可复制」分项模板；默认执行技能**不必**打开                                                                                                                                                                                                                                                  |
+| [scripts/find-app-by-keyword.py](./scripts/find-app-by-keyword.py)                               | **旧版 CLI 兼容脚本**：当 `app list --query` 不可用时，用 `app list` 本地解析；默认优先使用 `qingflow --json app list --query <关键词>`                                                                                                                                                                          |
+| [scripts/builder-package-from-app-list.py](./scripts/builder-package-from-app-list.py)           | **旧版 CLI 兼容脚本**：当 `builder package list` 不可用时，才从 `app list` 曲线反查 **`package_name` / `resolve-id`**；新版默认直接用 `qingflow --json builder package list --query <关键词>`                                                                                                                    |
+
+**Builder 删除回读语义**：删除类 apply 要区分 **DELETE 是否已发出** 和 **删除是否已回读确认**。若结果里有 **`delete_executed=true`**，但 **`readback_status=unavailable|still_exists`**，不要盲目重复删除；记录 **`safe_to_retry_delete=false`**，稍后用对应读取工具确认。
+
+**Builder 写后回读语义**：`package apply/update`、`schema apply`、`portal apply`、`charts apply` 以及其它 builder apply 若返回 **`status=partial_success`** 且 **`write_executed=true` / `safe_to_retry=false`**，表示写动作已经发出或已成功，后续回读/发布校验可能被 40002、404、超时或元数据延迟阻挡。此时不要把结果解读为“未写入”；下一步是 **`readback_before_retry`**，只报告 **写入已执行，回读待确认**，并按 `verification.readback_unavailable`、`details.*readback_error`、`details.suggested_retry_payload`、`summary.write_executed` 做最终说明。完整系统 schema apply 的恢复只允许先读包、解析应用、读字段/关联；禁止未经读回就重放整批、拆成单应用重建、创建 V2/测试/随机后缀应用，或把同批 `target_app_ref` 改成未确认的 `target_app_key`。
+
+**Builder contract 读取路径**：`qingflow --json builder contract --tool-name ...` 成功时，真实契约固定在 **`$.contract`**；优先读返回的 **`json_paths`**。`allowed_keys` 是 `$.contract.allowed_keys`，`allowed_values` 是 `$.contract.allowed_values`，且 allowed_values 使用 **扁平 dotted key**，例如 `["field.type"]` / `["chart.chart_type"]`，不是嵌套对象。成功响应顶层 `allowed_values` 通常为空，不要从顶层取字段枚举。`builder icon catalog` 的候选固定读 `$.icon_names` / `$.icon_colors`。
+
+**Builder apply 输出读取路径**：`package/schema/views/charts/portal` 等 builder apply 成功或 partial 时，优先读返回的 **`json_paths`**；稳定主路径是 `$.summary` 与 `$.resources[]`。资源 ID/key/name 先看 `$.resources[].id/key/name`；写入状态先看 `$.write_executed`、`$.safe_to_retry`、`$.next_action`，再看 `$.summary.write_executed` / `$.summary.safe_to_retry`。旧字段只作兼容或 debug。
+
+**0 字节输出**：写入类命令如果目标文件或捕获 stdout 为 0 bytes，不要按成功或失败二选一猜测；标记为 **`write_state_unknown`**，先做对应读回（如 `builder app get` / `portal get` / `record get` / `record list`）再决定是否重试。只要读回显示资源已创建/更新，就按成功路径汇报；读回证明缺失时才重试最小缺失项。在 CLI repo 或测试 harness 中，可用 `python scripts/validate_qingflow_output_files.py --glob 'tmp/*.json'` 扫描 0 bytes / 非 JSON 输出。
+
+---
+
+## 安装
+
+> 仅qingflow命令执行后发现不可用再安装，不需要进行校验动作
+
+```bash
+npm install -g @qingflow-tech/qingflow-cli@latest
+```
+
+环境：Node.js v16+、npm、可达轻流 API。
+
+---
+
+## 执行上下文准则（认证仅作失败恢复）
+
+目标是 **少一次无用往返**、**先解决业务**、**再根据失败类型补鉴权**。
+
+1. **不要**在每次任务开头固定执行 `qingflow --json auth whoami`「先验一遍是否登录」。假定 `default` profile **已持久化登录**（或由剧本先完成 `auth use-credential` / `auth login`）。
+2. **优先直接执行业务读/写**（如下文 **落盘规则** 带好重定向）：例如 `app list` → `app get` → `record list`/`task list`。
+3. **仅当**业务命令返回明确 **未登录 / session 无效 / `Profile '…' is not logged in` / 401** 时，再执行：
+  - `qingflow auth use-credential …` 或 `qingflow auth login …`（`--base-url "$QINGFLOW_BASE_URL"`）；成功后再 **重试原业务命令**，而不是先绕一大圈。
+  - 必要时 `qingflow --json auth whoami` **核对**账号与 `selected_ws_id`。
+4. **仅当**业务失败且症状像 **租户/工作区不对**（数据空、明显越权）时，再使用 `workspace list` / `workspace get` / `workspace select`。**读应用内记录不依赖**前置 `workspace get`；且 `workspace select` 在部分环境会遇 **59004**（流币/AI 配额），与「没登录」区分。
+5. 与 **普通成员读数最短路径**（下节）一致：能 2～3 步调通就不要先堆 5～6 步调身份。
+
+**安全**：密码、credential **只走 stdin / 环境变量**，禁止写进命令行历史。
+
+---
+
+## 失败恢复时的认证方式
+
+凡带 `--base-url` 的认证，在环境已配置时 **必须** 使用环境变量 `\`"$QINGFLOW_BASE_URL"\``（勿省略引号以避免空值/word-split），勿写死域名。
+
+### 方式 A：Credential（自动化推荐）
+
+```bash
+echo "$QINGFLOW_CREDENTIAL" | qingflow --profile default auth use-credential \
+  --base-url "$QINGFLOW_BASE_URL" \
+  --credential-stdin \
+  --persist
+```
+
+### 方式 B：交互式登录
+
+```bash
+qingflow auth login \
+  --base-url "$QINGFLOW_BASE_URL" \
+  --email "user@example.com" \
+  --password-stdin \
+  --persist
+```
+
+### 核对会话（排障用，非例行首步）
+
+```bash
+qingflow --json auth whoami
+```
+
+常用参数：`--credential-stdin`、`--password-stdin`、`--persist` / `--forget-persisted`；详见 `qingflow auth --help`。
+
+---
+
+## 输出落盘规则（task / record / import / builder 查询类）
+
+以下 **必须** 将标准输出重定向到文件（如 `tmp/qingflow_*.json`），**禁止**把终端大 JSON 直接交给 LLM；后续用读文件 / 脚本处理。
+
+
+| 子系统        | 必须落盘的子命令                                                                                                                                                            |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **task**   | `list`、`get`、`log`、`report`                                                                                                                                         |
+| **import** | `template`、`verify`、`repair`、`start`、`status`（**`verify` / `start` 链依赖本机 `~/.qingflow-mcp` 校验/任务落盘，自动化须开放写权限**） |
+| **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 响应 |
+| **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` 响应体大时同样建议落盘** |
+
+
+**规则摘要**
+
+- 重定向示例：`qingflow --json record list … > tmp/qingflow_records.json`
+- 线上真实测试、子智能体并行任务、批量 `--*-file` 入参优先使用**绝对路径**，或在命令前固定确认 `pwd`；不要假设子智能体当前目录与主线程一致。
+- `auth`、`workspace`、`app`、`portal`、`view`、**非上述列出的**等，可直接终端查看或按需落盘。
+- 错误在使用 **`--json`** 时多在 **stdout** 的 JSON 信封里；stderr 多为 argparse usage。
+
+---
+
+## 应用记录：获取数据工作流（推荐闭环）
+
+与常见 **编排/API 文档**里的命名对齐时的固定顺序为：
+
+1. **`app_get`**：`qingflow --json app get --app-key <APP_KEY>` → 在 **`data.accessible_views`**（或等价路径）选取 **`view_id`**。
+2. **`record_schema_get`（`schema_mode=browse`）**：`qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>`（CLI 子命令 **`browse`** 即浏览视图表结构）。
+3. **`record_list` / `record_get` / `record_logs_get`**：`record list …` 用于样本浏览或模糊定位候选；`record get --record-id …` 下钻单条前端详情页首屏上下文（字段、首屏日志、引用、图片与文件资产）；只有需要完整审计历史时，再用 `record logs --record-id …` 读取全量数据日志和流程日志 JSONL。
+
+`app get` 里的 `CUSTOM_VIEW_LIST_UNAVAILABLE` 表示自定义视图列表读取被权限或后端限制降级；若 `accessible_views` 中仍有 `system:*`，可继续用该视图读数。若没有任何视图，再回到前端 URL、`app list` 可见应用、或用户提供的 `viewgraphKey` 补充上下文，不要直接断言应用不可读。
+`app get.data.can_create=false` 才表示 applicant/create 路径不可用；创建权限探测遇到 auth / server 等非权限类错误时应直接按失败处理，不要包装成“未知创建权限”或“用户无新建权限”。
+
+**细则、响应解包、`view_id` 雷区与命令模板**见 **[reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**（编写前已对当前 CLI **实跑**校验）。若仅需「最快看一眼有没有行」，可省略 **`schema browse`**，直接走下文「最短路径」。如果用户要任何最终统计结论、分析报告、趋势/排名/比例/分布，切换到 `qingflow-record-analysis`，按 `record_access -> Python/pandas` 执行。
+
+---
+
+## 应用记录：创建记录工作流（申请节点 → 写入）
+
+推荐顺序：
+
+1. **转交 `qingflow-record-insert`**：新建记录默认使用该专项 skill，避免旧的单条 `fields-file` 心智模型。
+2. **`record_insert_schema_get` / CLI `record schema insert`**：先读取 insert-ready schema、`required_fields`、`payload_template`、`format_hint`、`example_value`、联动与运行时必填提示。
+3. **`record insert(items)` / CLI `record insert --items-file`**：单条也是 `items` 数组的一行；成员、部门、关联字段优先写自然语言（如 `"张三"`、`"直销部"`、`"海军军医大学"`），仅在返回 `needs_confirmation` 时再让用户确认候选。
+
+**细则、字段 JSON 结构与排障**见 **[reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**。
+
+---
+
+## 应用记录：更新记录工作流（详情 → 写入）
+
+主链路是先读详情，再直接提交用户要求修改的 key/value。不要把 `record schema update` 当成更新前置步骤：
+
+1. **`record get`** → 拿 **`record_id`、当前值、fields[].title / field_id / kind**；已知前端/自定义视图时必须带同一个 **`--view-id`**。未知时 CLI 会先试默认 `system:all`，权限拒绝后再尝试可访问视图，但智能体仍优先从 `app get.accessible_views` 取 view。
+2. 智能体根据 `record get.fields[]` 和用户要求，组一个只包含待改字段的 JSON 对象（标题 → 值）。
+3. **`record update`** → **`--record-id` + `--fields-file`**，已知前端视图时同样带 **`--view-id`** 让 CLI 优先走该 view；批量用 **`--items-file`**（**`--dry-run` 仅批量**）。
+4. 只有字段范围不清、候选歧义、或 `record update` 失败时，才用 **`record schema update`** 诊断本条记录的 **`writable_fields / payload_template / available_update_routes`**；已知前端视图时同样带 **`--view-id`**，让诊断优先探测同一个详情页上下文。
+
+**更新路径**：`record update` 会自动先尝试数据管理员直改，再 fallback 到前端同源的 custom view 详情编辑路径；如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑，最后会尝试 workflow save-only。成功时只需要读 **`status / update_route / verification_status`**；失败时再读失败原因与路线诊断。不要把中间 route 或辅助 schema/readback 探测的 40002 / 40027 / 404 当作最终失败。
+
+**大号 `record_id`（常见于 Snowflake 类 id）**：若干 CLI 版本在 **`record update` 写入路径**上对 `apply_id` 会做 **JavaScript 安全整数**相关校验，`list`/`get`/`schema update` 仍可能正常而 **更新落库报错**（常为 `apply_id must be positive`）。排障见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。业务统计与最终结论仍必须按 `qingflow-record-analysis` 使用 `record_access -> Python/pandas`。
+
+**命令模板、批量 `items` 形态、与新建相同的写入值约定**（按 **`kind`** 分题型见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**）见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
+
+**成员 / 部门候选排障**：若成员、部门字段返回 `needs_confirmation` 或候选不清，使用 `qingflow record member-candidates` / `qingflow record department-candidates`；它们优先走表单字段候选范围接口（与前端选择器一致）。不要改用通讯录管理类查询去“补候选”，那会把普通成员误带到 ContactAuth 管理权限链路。
+
+**部门名筛选 / 写入**：`record list/access/analyze/insert/update` 遇到部门字段时可直接传部门名或候选对象；CLI 会优先走成员可见的目录搜索解析部门。不要先用通讯录管理接口查询部门 id，否则普通成员容易被 ContactAuth 错误阻挡。
+
+**目录搜索边界**：按关键词找成员/部门应优先使用成员可见搜索（如 `directory_search` 或记录字段候选工具）；部门树遍历、外部联系人完整列表、builder 成员/角色检索、通讯录管理类查询属于配置/管理向能力，普通成员无权时不要当作记录读写失败。若目录工具返回 `CONTACT_DIRECTORY_PERMISSION_DENIED`，只表示 ContactAuth/通讯录管理边界不可读；记录成员/部门字段仍应改用 `record_member_candidates` / `record_department_candidates` 或直接按字段值写入。`builder member search --query` 与 `builder role search --keyword` 都必须传明确关键词，且不要作为记录成员/部门字段候选 fallback。
+
+**导出 / 下载 / Excel**：只有用户明确要文件时才用 `export start/direct`；导出必须显式传 **`--view-id`**，从 `app get.accessible_views` 或前端 URL 取同一个视图，省略会直接报缺少视图上下文。导出字段按前端 read/export scope 解析，不按 record update/write scope；`applicant schema`、`viewList`、`data/listBaseInfo` 等辅助字段源的 40002 只能作为降级信号，不能覆盖同一 `custom:*` view 或 `system:all`/type=8 导出链路。若状态/下载结果带 `EXPORT_HISTORY_UNAVAILABLE`，表示导出历史列表不可读；只要当前进程详情显示 `running/succeeded` 且有文件链接，就按当前进程结果继续处理，不要把历史读取 40002 当作导出失败。
+
+**代码块运行**：`record code-block-run` 主链路是已有记录/任务详情上下文 → 传明确的 `--code-block-field`（优先字段 ID）直接运行；已知前端/custom view 时同样带 **`--view-id`**，让运行优先读取同一个详情页 answers。`record schema code-block` 只用于字段选择不清或需要查看 alias / 绑定回写配置时；若申请表单 schema 无权限，会返回 `CODE_BLOCK_SCHEMA_UNAVAILABLE` 的结构化诊断结果，不代表代码块运行无权限。运行可继续使用详情 answers，绑定回写可能跳过。
+
+---
+
+## 普通成员：读取记录数据「最短路径」（速通）
+
+适用于 **`auth whoami`** 输出的 **`permission_level`** 为普通/基本成员等低权限账号；选应用使用 **`app list`** 或 **`app list --query <关键词>`**。
+
+**调用次数**
+
+- 从零选应用：**3 次** → `app list` → `app get --app-key` → `record list … > 文件`
+- 已知 `APP_KEY`：**2 次** → `app get` → `record list … > 文件`
+
+**写法（占位符替换后即可）**
+
+```bash
+qingflow --json app list
+qingflow --json app get --app-key <APP_KEY>
+# 从 JSON 中取应用对象：若存在顶层 key `data` 则先解包；在 accessible_views 中取 view_id
+
+qingflow --json record list \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_records.json
+```
+
+`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`。
+
+**找应用包（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)**。
+
+**按关键字找应用（成员可用）**：默认直接用 **`app list --query`**，它只读取当前用户可见应用并在本地过滤，响应看 `items[].app_key`、`matched_count`、`unfiltered_count`、`filter_mode`。
+
+```bash
+qingflow --json app list --query '发票'
+# 兼容别名：
+qingflow --json app list --keyword '发票'
+```
+
+若所在环境仍是旧版 CLI、`app list --query` 不存在，再使用本技能目录 **[scripts/find-app-by-keyword.py](./scripts/find-app-by-keyword.py)** 作为兼容 fallback。
+
+### **`view_id` 要点（与成员表一致）**
+
+- **待办 / 已办 / 抄送**：**不要**再把 `record list --view-id system:todo` / `system:done` / `system:cc` 当作 **任务中心**；该类用法已过时。任务箱一律用本节下文 **「待办 … SOP」** 中的 **`task list --task-box …`**。**应用内表格读数**仍可用 `app get` 里其它视图（例如部分环境里 **`system:all`「全部数据」**仍可用于 `record list`，与上述任务箱不是同一概念）。
+- **显式 `view_id` 是前端当前视图语义**：`record list/access/schema browse/logs/export` 传了 `system:all` 就只读「全部数据」链路；若返回 40002 / 40027 / 404 / 500，不要把它自动改成 `system:initiated`、`system:todo` 等其它系统视图。需要换视图时必须重新从 `app get.accessible_views` 或前端 URL 选取。
+- **`--view-id`** 仅从 **`app get`** 的 **`accessible_views`** 选取 **业务 / 自定义视图**（优先 **非「`custom:` 后仅数字」**，如带字母后缀的 `custom:…`）。
+- 若 `app get.warnings` 含 **`CUSTOM_VIEW_LIST_UNAVAILABLE`**，说明 custom view 列表辅助读取不可用；已有 `system:*` 视图仍可继续使用，缺 custom view 本身不等同于应用无权。
+- **禁止**把 `custom:1`、`custom:12` 等纯数字后缀自定义视图当作读数首选：成员侧常见 **`schema browse` / `record list`** 返回 **40038**。
+- 读数前**不必**前置 `workspace get`、`view get`。若仅需列表可先省略 **`record schema browse`**；若要列定义或与 **「获取数据工作流」** 对齐，见 **[reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**。
+
+---
+
+## 偏向「管理 / 高权限」的命令（普通成员常不可用或易失败）
+
+以下为 **能力或数据面更偏管理/配置** 的路径；**普通成员**在未授权时会出现业务错误码（**非**「CLI 坏了」）：
+
+
+| 区域    | 示例                                                | 典型现象（成员）                     |
+| ----- | ------------------------------------------------- | ---------------------------- |
+| 旧应用搜索入口  | 不使用；改用 `app list --query`                                      | `40002` 等                    |
+| 导入    | `record schema import`、`import template`、`import verify`、`import start`… | `IMPORT_AUTH_PRECHECK_FAILED`、`IMPORT_*_UNAUTHORIZED`、无导入权 |
+| 工作区切换 | `workspace select`                                | 可能 **59004**（配额），与未登录区分      |
+
+
+**成员侧只读仍较稳**的示例：`app list` / `app get`、`portal list`。其它管理向子命令参见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+
+---
+
+## 典型工作流示例（含落盘）
+
+### 待办查询
+
+不限定应用时 **不要写死 `--app-key`**，直接落盘列举（详见下节 SOP）：
+
+```bash
+qingflow --json task list --task-box todo --flow-status all --page 1 --page-size 50 \
+  > tmp/qingflow_tasks.json
+```
+
+已知 `APP_KEY` 时再收窄：
+
+```bash
+qingflow --json task list \
+  --task-box todo \
+  --app-key "[APP_KEY]" \
+  --page 1 --page-size 50 \
+  > tmp/qingflow_tasks_app.json
+```
+
+`task get` / `task log` / `task report` 同上，输出 **必须** `> tmp/...json`。
+
+### 待办 / 已办 / 抄送处理 SOP（`task list`）
+
+> **与编排工具名逐步对齐的独立长文**（含 **`task_workflow_log_get` / `task_associated_report_detail_get` / `task_action_execute`** 与 **`task log` / `task report` / `task action`** 对照、实测排障）：**[reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md](./reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)**。
+> **命令形态与参数级写法**见下文 **「命令速查 → 待办 `task`」**；本节约定 **执行顺序** 与 **是否传入 `--app-key`**。
+
+**与前序通路区分**：若以 **待办 / 已办 / 抄送「任务箱」** 为目标，**须**按本节下文 **「待办 / 已办 / 抄送处理 SOP」** 使用 `**task list --task-box …`**； `**record list` + `system:todo`、`system:done`、`system:cc` 等 `view_id` 已过时，不作为推荐**。`record list` 用于 **应用内业务视图**：在 `**app get**` 的 `accessible_views` 中取可用的 `**custom:***` 等 `**--view-id**`，与本节 SOP 勿混为一谈。
+
+`**--task-box` 取值（小写）**
+
+
+| 业务箱      | `--task-box` | 备注                            |
+| -------- | ------------ | ----------------------------- |
+| 待办       | `todo`       | **默认**：省略 `--task-box` 等价于待办箱 |
+| 已办       | `done`       |                               |
+| 抄送       | `cc`         |                               |
+| 我发起的（可选） | `initiated`  | CLI 合法值；按需使用                  |
+
+
+#### `task-box` 与 `flow-status` 的区别（与实现 / 接口对齐）
+
+二者是 **两个独立维度**，在一次 `task list` 里 **同时** 带给后端（`POST /task/dynamic/page` 的 JSON 体字段为 `**type**` 与 `**processStatus**`），不要二选一理解。
+
+- `**--task-box` → `type`（任务箱）**：只看 **哪一类收件箱**——与本账号的关系维度（待办 / 我发起 / 抄送 / 已办）。
+- `**--flow-status` → `processStatus`（流程状态筛选项）**：在 **已选定任务箱内** 再按 **流程进度、时效、是否未读** 等过滤；默认 `**all**`（`processStatus = 1`）表示本维度不减条件。
+
+合法 `**task-box` → type**（小写，`--task-box` 省略时等价 `todo`）：
+
+
+| `--task-box` | `type` | 语义（源码类注释一致） |
+| ------------ | ------ | ----------- |
+| `todo`       | 1      | 待办，需当前用户处理  |
+| `initiated`  | 2      | 我发起的        |
+| `cc`         | 3      | 抄送          |
+| `done`       | 5      | 已办          |
+
+
+合法 `**flow-status` → processStatus`**（CLI 报错信息中的英文关键字与此一致）：
+
+
+| `flow-status` | processStatus | 语义   |
+| ------------- | ------------- | ---- |
+| `all`（默认）     | 1             | 全部   |
+| `in_progress` | 2             | 流程中  |
+| `approved`    | 3             | 已通过  |
+| `rejected`    | 4             | 已拒绝  |
+| `pending_fix` | 5             | 待完善  |
+| `urged`       | 6             | 催办   |
+| `overdue`     | 7             | 超时   |
+| `due_soon`    | 8             | 即将超时 |
+| `unread`      | 9             | 未读   |
+| `ended`       | 10            | 流程结束 |
+
+
+**勿把记录列表的 `list_type`（或过时文档里的 `system:*` 视图口径）与任务中心的 `type` 混为一谈**：`task list --task-box …` 的映射见上表（例如任务中心「已办」为 `type=5`）；**不要**再把旧表单视图侧的编号抄到 `**--task-box`** 或自行拼接请求 `type`。
+
+更深的行为差异与踩坑备忘仍见 **[reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。
+
+#### `--query`（列表检索与回退）
+
+`qingflow task list --help` 中与实现一致：**先走后端待办检索**（请求体中为 `searchKey`）；当 **后端返回零条** 时，公开 `**task_list` 可能对当前页结果做本地匹配**（字段涉及应用名、节点名、`app_key`、`record_id` 等）。若走 JSON/`--json` 信封且触发了该路径，响应中可出现 `**TASK_LIST_QUERY_FALLBACK_APPLIED`** 类提示——**不等于**后端无权限，解析列表前先看 `warnings`。
+
+**标准流程**
+
+1. **列表（必须落盘）**
+  - **未显式掌握 `APP_KEY`**：不要硬编应用；直接执行（按需将 `--task-box` 设为 `todo` / `done` / `cc`）：
+   `qingflow --json task list --task-box <todo|done|cc> --flow-status all --page 1 --page-size 50 > tmp/qingflow_tasks_<箱名>.json`
+   `**--app-key` 整段省略**——与速查表「`task` 列表」一致：`--app-key` 非必须，由后端返回当前会话可见的任务页。
+  - **已知或已从业务收窄到单应用**：在同上命令末尾追加 `--app-key <APP_KEY>`（`APP_KEY` 来自 `**app list` → `app get`**，与普通成员最短路径一致）。
+  - 可选 `**--query**`：语义见上节「`--query`」；零条时可能是真无数据，也可能是未触发回退或关键词不匹配。
+  - **排序**：当前 `**qingflow task list` CLI 无 `--sort-by` / `--sort-direction`**；勿编造排序类参数。
+2. **从列表下到详情 / 日志 / 报表 / 动作**
+  - **唯一默认路径**：列表 JSON 中取 `**task_id`**，使用 `**--task-id**`；它必须来自 `data.items[].task_id`，不是列表序号、record_id 或 workflow_node_id。示例：
+   `qingflow --json task get --task-id <TASK_ID> > tmp/qingflow_task_get.json`
+  - **不要自行凑三键**：`app_key / record_id / workflow_node_id` 只用于用户已明确提供完整 locator 的排障场景；普通执行不要从其它输出里猜。
+  - `**task report`**：除定位参数外 **必须** `--report-id`；支持 `**--page` / `--page-size`** 分页（见速查表）。
+  - 与「列表可省略 `--app-key`」不同：下钻单条默认必须有 `**task_id**`。
+  - `save_only` 可用性优先看当前节点 `editableQueIds`；只有该辅助接口 40002 / 40027 / 404 时才降级使用当前待办详情的 `queAuthSetting`，非权限类错误不要当成“节点不可保存”。
+  - 评论提及、退回候选、转交候选等辅助候选接口只有 40002 / 40027 / 404 可视为候选不可用；500 / auth 等非权限错误不要包装成权限边界。
+3. **排查**
+  - 某一箱 `**items` 为空但 exit 0**：常为真实无数据，可换 `--task-box` 或分页；若在「omit `app_key`」下发散且仍空，再用 `**app list`/`app get`** 确认是否在正确应用与工作区再看是否需补 `--app-key`。
+  - 未登录、权限错误：回到上文 **鉴权行为准则**，先重试业务再补鉴权。
+
+### 记录：表结构、列表、分析取数
+
+多级子命令 **不要** 整体加引号；`record list` / `record access` **运行时必须** `--view-id`（从 `app get` 的 `accessible_views` 取）。最终统计结论、分析报告、趋势/排名/比例/分布必须切换到 `qingflow-record-analysis` 的 `record_access -> Python/pandas`。
+
+```bash
+qingflow --json record schema browse \
+  --app-key "[APP_KEY]" --view-id "[VIEW_ID]" \
+  > tmp/qingflow_schema.json
+
+qingflow --json record list \
+  --app-key "[APP_KEY]" --view-id "[VIEW_ID]" \
+  > tmp/qingflow_records.json
+
+qingflow --json record access \
+  --app-key "[APP_KEY]" --view-id "[VIEW_ID]" \
+  --columns-file tmp/columns.json \
+  --where-file tmp/where.json \
+  > tmp/qingflow_record_access.json
+```
+
+### 危险操作（节选）
+
+
+| 命令                     | 备注                                                                     |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `task action`          | **无 `--dry-run`**，执行即生效                                                |
+| `record delete`        | **无**安全开关                                                              |
+| `record insert/update` | 可用 `--verify-write`；`record update --dry-run` **仅批量**且需 `--items-file` |
+
+
+更多见 **[reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**管理向**（检索/导入等）见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+
+`record delete` 只能使用系统列表语义删除：必须传 `system:*` 的 `--view-id`，不要传 `custom:*`、`list_type`，也不要省略视图上下文。若目标来自 custom view，先用该 view 的 `record list/get` 确认 record_id，再从 `app get.accessible_views` 选择一个可访问的系统视图删除；`RECORD_DELETE_CUSTOM_VIEW_UNSUPPORTED` / `RECORD_DELETE_VIEW_REQUIRED` 是配置边界，不是用户无权。
+
+### 注销
+
+```bash
+qingflow auth logout --forget-persisted
+```
+
+---
+
+## 常见失败与处理
+
+
+| 迹象                                                               | 处理                                                                                                                                      |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| 未登录 / profile 未登录                                                | **再**走「认证方式」节，重试业务命令                                                                                                                    |
+| `record_list requires view_id`                                   | 先 `app get --app-key`，取 `view_id`                                                                                                       |
+| JSON 内 `backend_code` / `error_code`                             | 区分配额、权限与参数错误；普通成员见上节「偏向管理」；非本技能速查表覆盖的报错见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)** |
+| `task get` / `task log` / `task report` / `task action` 报 config | 回到 `task list`，复制 `data.items[].task_id` 后再传 `--task-id`；不要用列表序号、record_id、workflow_node_id 或自行拼三键。详见 **「待办 … SOP」步骤 2**                              |
+| 成员 + `custom:` 后纯数字视图                                            | 读数时**跳过**，换 `system:*` 或其它 `custom:*`                                                                                                   |
+| `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)** |
+
+
+---
+
+## 命令速查（骨架）
+
+**何时须细读引用、勿凭本节推测**：见**文首「硬约束（必读）」**。
+
+> **适用范围**：普通/基本成员在只读或小范围写入里**较高概率可用**的形态；勿照抄旧应用搜索入口、无权的 **`import …`**（易 **40002 / IMPORT_\***）；管理闭环见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+
+**形态**：`qingflow [--profile 名] [--json] …` · 自动化**始终**建议 `--json` · `profile` 是根级执行上下文，若 `builder contract` 示例 JSON 里出现 `"profile": "default"`，不要复制进 CLI 的 `--*-file` 载荷；CLI 要写 `qingflow --profile default ...` · 嵌套子命令（如 `record schema browse`）**勿**整体加引号 · 包版本用 `qingflow --version`；需要结构化输出时用 `qingflow --json version`。
+
+| 分组 | 骨架（细则见上文章节 + 「关联文件」） |
+| ---- | ------------------------------------ |
+| **auth** | `auth whoami` · `auth use-credential --base-url "$QINGFLOW_BASE_URL" --credential-stdin --persist` · `auth login …`（见「失败恢复时的认证方式」）· `auth logout --forget-persisted` |
+| **workspace** | `workspace list` · `workspace get --ws-id` · `workspace select`（慎用，可读数前不必；可能 **59004**） |
+| **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，非权限类后端错误不隐藏） |
+| **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` |
+| **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)** |
+| **builder** | **搭建／系统化配置**：先读 `builder contract`。**完整系统/应用包**：`builder package apply --config-file` → `builder schema apply --apps-file`（主写法为 `{package_id, apps}` 对象；raw apps array / singleton wrapper array 仅兼容；同批 relation 主写 `target_app_ref` 指向 `client_key`，`target_app_key` 只用于已存在/已读回确认的目标）→ layout/views/flow/portal/charts。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先 `readback_before_retry`，不得直接拆单应用重建、重放整批或创建 V2/测试/随机后缀绕过重名。**单应用**：`app resolve/get` → `schema/layout/flow/views apply`。图标主写 `icon/color`；`icon_name/icon_color`、`icon_config`、`icon:{name,color}` 仅兼容/读回。选择字段 `options` 可用字符串数组或 `{label,value}` 对象数组。与普通读数/`record insert` 不是同一路径 → **[APP_DELIVERY](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**、[ICONS](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md)、[VIEWS](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)、[PORTAL](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)、[CHARTS](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md) |
+| **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`** |
+
+**高发必败**：旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。
+
+更多成员策略：**[reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** · 一次性长模板：**[reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** · 对齐说明：**[reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。
+
+---
+
+*技能维护：CLI 升级时以 `qingflow --version`、`qingflow … --help` 与本文 **task-box / flow-status** 对照表为准复核。*

package/skills/qingflow-cli/manifest.yaml

@@ -0,0 +1,10 @@
+identity: qingflow_cli
+type: skill
+description: 「使用 qingflow CLI 的任何命令或自动化脚本前必须先调用本 Skill」。涵盖安装、执行上下文失败恢复、task/record/import/builder 查询落盘规则、普通成员读数速通、record list 模糊定位、record get 详情上下文、record access 分析取数、schema 字段类型（reference）、任务上下文 SOP（reference）、批量导入 SOP（reference）；Builder reference 对准「搭建/创建应用与流程」「多应用一次性新建（schema apply --apps-file / target_app_ref）」「数据标题/封面」「查询条件」「按钮与关联视图/报表」「门户工作台与 QingBI/BI 报表（应用源创建、数据集报表仅关联、扩展图表类型与特殊字段映射）」等系统化配置场景（与普通 record 读写区分）；另有管理端边界；默认不把登录或工作区校验作为业务前置
+tags:
+  - cli
+  - qingflow
+  - task-management
+  - data-analysis
+  - security
+  - validated

package/skills/qingflow-cli/reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md

@@ -0,0 +1,94 @@
+# Qingflow CLI 管理员命令速查表（Skill Reference）
+
+> **适用**：`qingflow --json auth whoami` 中具备 **租户/工作区级管理、应用检索、导入、搭建配置** 等权限的账号（如 **超级管理员、应用管理员** 等，`permission_level` 以服务端为准）。
+> **与普通成员对照**：权限较窄时请用 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**主流程与落盘规则**以 **[SKILL.md](../SKILL.md)** 为准。需要 **全子命令「一次可复制」逐项模板**时可参阅同目录 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)**（任选，默认执行技能不必打开）。
+
+---
+
+## 1. 元与安装
+
+
+| 场景        | 命令                                               | 备注                                  |
+| --------- | ------------------------------------------------ | ----------------------------------- |
+| 查 CLI 包版本 | `qingflow --version`；需要 JSON 用 `qingflow --json version` | 不依赖登录，不需要先查 npm 安装路径 |
+| 帮助        | `qingflow -h`、`qingflow record schema browse -h` | 嵌套子命令勿整体加引号                         |
+
+
+---
+
+## 2. 会话与工作区
+
+
+| 场景            | 命令                                                              |
+| ------------- | --------------------------------------------------------------- |
+| 当前身份与租户       | `qingflow --json auth whoami` → `selected_ws_id`                |
+| 工作区详情         | `qingflow --json workspace get --ws-id <WS_ID>`                 |
+| 枚举工作区         | `qingflow --json workspace list --page 1 --page-size 40`        |
+| **切换租户**（改会话） | `qingflow workspace select --ws-id <WS_ID>`（可能 **59004** 流币/配额） |
+
+
+---
+
+## 3. 应用与门户（管理侧常用）
+
+
+| 场景                     | 命令                                                                 | 管理员说明                              |
+| ---------------------- | ------------------------------------------------------------------ | ---------------------------------- |
+| 列表 / 关键字搜索                     | `qingflow --json app list [--query <词>]`                                         | 通用；`--query` 只过滤当前用户可见应用                                 |
+| 详情（含 accessible_views） | `qingflow --json app get --app-key <APP_KEY>`                      | 正文常在 JSON 的 `**data**` 包裹内         |
+| 门户                     | `qingflow --json portal list`、`portal get --dash-key <DASH_KEY>`   | `dash_key` 多在 `data.items`         |
+
+
+---
+
+## 4. 记录数据
+
+与 **[成员速查](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 及 **[SKILL.md](../SKILL.md)**「命令速查」一致：`record schema browse`、`record list`、`record access` **必须** `--view-id`。查询类遵守 **SKILL 落盘**：`record list`、`get`、`access`、`schema browse` 等。最终统计结论、分析报告、趋势/排名/比例/分布统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**。
+
+---
+
+## 5. 待办
+
+同 SKILL：`task list`、`get`、`log`、`report` 查询输出 **必须落盘**。`task action` **无 `--dry-run`**。
+
+---
+
+## 6. 导入（偏应用管理员）
+
+
+| 步骤     | 命令                                                                           | 备注                                                                |
+| ------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| 模板说明   | `qingflow --json import template --app-key <APP_KEY>`                        | **常需应用管理权限**（成员常为 UNAUTHORIZED）                                   |
+| 校验上传文件 | `qingflow --json import verify --app-key <APP_KEY> --file-path <FILE>`       | 文件须**服务端支持的模板格式**，否则 `**IMPORT_FILE_FORMAT_UNSUPPORTED`**         |
+| 状态     | `qingflow --json import status [--app-key | --import-id | --process-id-str]` | **三选一**；仅 `--app-key` 且无唯一「最新导入」时可能 `**IMPORT_STATUS_AMBIGUOUS`** |
+
+
+链路后续依赖 `verification-id`，见 `qingflow import -h`。
+
+---
+
+## 7. Builder
+
+**只读、管理会话下常见可用**：
+
+
+| 命令                                                           | 必填                                    |
+| ------------------------------------------------------------ | ------------------------------------- |
+| `qingflow --json builder member search --query <关键词>`        | `--query`                             |
+| `qingflow --json builder role search --keyword <关键词>`        | `--keyword`（成员常 `ROLE_SEARCH_FAILED`） |
+| `qingflow --json builder package list [--query <关键词>]`       | 直接读取应用包列表；看 `items[].package_id` |
+| `qingflow --json builder publish verify --app-key <APP_KEY>` | —                                     |
+| `qingflow --json builder package get --package-id <整数>`      | 整数，`package-id` 来自上下文                 |
+
+
+写路径：`role create`、`package apply`、`solution install`、`flow apply`、各类 `*-apply` — **无 universal dry-run**，慎用。
+
+---
+
+## 8. 必败反例
+
+与 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 常见踩雷、**[SKILL.md](../SKILL.md)**「命令速查」末段「必败形态」一致；**逐条 CLI 形态表**另见 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** §9：`record list` 缺 `view-id`、子命令错引号、builder 缺 query/keyword、`import status` 多 selector。
+
+---
+
+*修订：以 `qingflow … -h` 与 **MEMBER**、[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) 对齐。*