@qingflow-tech/qingflow-cli 1.1.57 → 1.1.58

package/skills/qingflow-cli/SKILL.md

@@ -2,7 +2,6 @@
 name: qingflow-cli
 description: |
   【强制】在执行或编排任何 qingflow CLI 命令前必须优先加载本 Skill。
-  Qingflow CLI 主入口：规定命令执行与 JSON 落盘方式，并把普通应用数据默认路由到 data；task、builder、import、日志、附件和代码块按专项参考执行。
   Qingflow CLI 包以本 Skill 作为 CLI 主入口；record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。
   指导安装、执行上下文失败恢复、查询与写入；规定 task/record/import/builder 查询落盘；覆盖普通成员读数、字段 kind 与数据形态、任务上下文、批量导入、record access/list/get/insert/update/delete 与管理端边界。
   Builder SOP 按智能体任务路径组织：完整系统、单应用、AppForm、视图、报表、门户、关联资源、流程、发布校验；表单字段、分组、布局和应用设置统一使用 versioned AppForm；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读/批量写/局部改依各资源契约执行；视图 apply 每次仅处理一个视图的一种操作，不支持批量创建或混合操作；明细见「关联文件」表与文末命令索引。
@@ -10,9 +9,13 @@ description: |
 
 # Qingflow CLI 使用技能
 
-> **Skill 版本**：`qingflow-skills-2026.09.22.01`。CLI 实际版本与安装路径以 `qingflow --json version` 为准。
+> **Skill 版本**：`qingflow-skills-2026.07.01.04`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
 
-本 Skill 负责 CLI 入口、文件约定和业务分流。已知 `app_key` 时直接执行 `data query/get`。只有应用名称时，先用 `qingflow --json app list --query "应用名称"` 查找当前工作区的可见应用，并核对返回项的 `app_name/title`；目标明确且唯一时取其 `app_key` 再查询，否则请用户确认。不要把应用名称直接传给 `--app-key`，也不要为定位名称转向 builder 或切换工作区。字段能力、权限范围与下一步动作以当前工具 schema、data 响应和 `hints` 为准。
+Use [$qingflow-common](../qingflow-common/SKILL.md) first when choosing between CLI and MCP. This Skill owns command-line invocation, JSON-file handling, and CLI-only validation; it does not redefine the underlying AppForm, record, task, or builder business contracts.
+
+**硬约束（必读）**：正文各节与文末「命令速查」中的命令**只作子命令形态索引**，不覆盖 JSON 结构、`--*-file` 键名、枚举全集、执行顺序与排障细节。凡工作**偏复杂**（多步串联、大块 payload、导入全链、**Builder 搭建向**（应用/schema/流程/布局/视图/门户/报表/按钮/关联资源的配置与发布、系统列与字段 `type`）、契约型 `apply`、按 schema 组织写入 payload、任务下钻与 `task action` 等），或你判断当前任务与「关联文件」里某篇所描述的内容**需求一致、场景相同或大体同类**，都应**先 Read 对应 `reference/...` 文档**，再结合 `qingflow … --help` 与 **[EXPLORATION_REPORT](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。**禁止**仅凭索引、习惯或类比去补参数、臆造字段名或推断服务端行为。**CLI 自动化场景只通过 `qingflow` 命令工作**；相关说明已按主题合并为本文档下的 `reference/` 子目录。**最终统计结论、分析报告、趋势/排名/比例/分布**统一走 **[record/analysis](./reference/record/analysis/README.md)** 的 `qingflow record access -> Python/pandas`。
+
+> **CLI**：当前实际执行包以 `qingflow --json version` 返回的 `package / version / command_path / executable_path / package_root / skill_version` 为准；不要从安装文档或全局 npm 目录猜版本。人工快速查看可用 `qingflow --version`。**复杂任务先读 [reference/00-INDEX.md](./reference/00-INDEX.md)**。**搭建/创建/系统配置**：先区分 **完整系统/应用包** 与 **单应用**。应用表单、字段、分组、行布局和应用设置统一使用 versioned AppForm：先执行 `qingflow --json builder app-form schema` 固定版本；更新前执行 `qingflow --json builder app-form get --app-key APP_KEY --being-draft`；每次写入前执行 `qingflow --json builder app-form validate --schema-version VERSION --file DECLARATION.json`，再执行 `qingflow --json builder app-form apply --file DECLARATION.json`。不要调用已移除的 `builder schema apply` / `builder layout apply`，也不要把旧 `--apps-file` / `--form-file` 当成当前主路径。完整系统先 `builder package apply`，再逐个 AppForm 创建并记录每个 `appKey`，最后用已确认的 app keys 配置关系、视图、门户和流程。门户需要新报表时在 portal section 写 `chart`，不要把报表创建拆成完整系统主步骤。AppForm apply 超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时，下一步固定是读取 draft/published form 后再恢复，禁止重复创建或用 V2/测试/随机后缀绕过重名；随后按 **[builder/README.md](./reference/builder/README.md)** 选择具体资源文档。仅成员读数速通仍可先打开 **[MEMBER_CHEATSHEET](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**。
 
 ## 关联文件
 
@@ -51,57 +54,97 @@ description: |
 | [reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/core/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 <关键词>`                                                                                                                    |
-## CLI 执行与 JSON 落盘
 
-1. 已知业务目标时直接执行目标命令，不固定前置 `auth whoami`、`workspace get` 或 `workspace select`。只有业务命令明确返回未登录、会话失效或工作区错误后，才恢复上下文并重试原命令。
-2. 自动化始终使用 `--json`。`data query/get`、task 查询、record 日志/附件上下文、import 与 builder 大响应必须写入本地文件，禁止把整段 JSON 或 CSV 打到上下文。
-3. `where`、`sort`、`columns`、`items`、`fields` 等结构化参数写入独立 JSON 文件，再通过 `--*-file` 传入。工具已暴露参数 schema 时直接使用；只有命令缺失或参数被拒绝时才读取对应 `--help`。
-4. 多任务或目录可能变化时使用绝对路径；单线程本地执行至少先固定 `pwd`。解析时只读取目标字段，不要 `cat` 大文件。
-5. `--json` 模式的业务错误通常也在 stdout JSON 信封中；stderr 主要用于 argparse usage。写命令返回已执行、部分成功或状态不明时，不得重放原请求。
+**Builder 删除回读语义**：删除类 apply 要区分 **DELETE 是否已发出** 和 **删除是否已回读确认**。若结果里有 **`delete_executed=true`**，但 **`readback_status=unavailable|still_exists`**，不要盲目重复删除；记录 **`safe_to_retry_delete=false`**，稍后用对应读取工具确认。
+
+**Builder 写后回读语义**：`package apply/update`、`app-form apply`、`portal apply`、`charts apply` 以及其它 builder apply 若返回 **`status=partial_success`** 且 **`write_executed=true` / `safe_to_retry=false`**，表示写动作已经发出或已成功，后续回读/发布校验可能被 40002、404、超时或元数据延迟阻挡。此时不要把结果解读为“未写入”；下一步是 **`readback_before_retry`**，AppForm 先读 draft/published form，再只修复确认的差异；最终说明按 `verification.readback_unavailable`、`details.*readback_error`、`summary.write_executed` 组织。禁止未经读回就重放创建、拆成单应用重建、创建 V2/测试/随机后缀应用，或猜测未确认的 `appKey`。
+
+**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
-mkdir -p tmp
-qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
-python - <<'PY'
-import json
-payload = json.load(open("tmp/qingflow_data_query.json", encoding="utf-8"))
-records = payload.get("records") or {}
-print({"total": records.get("total"), "has_more": records.get("has_more"), "hints": payload.get("hints")})
-PY
+npx qingflow-cli@latest install
 ```
 
-认证恢复时，credential 或密码只通过 stdin／环境变量传递，不写入命令行历史：
+安装器会安装真实 CLI 包 `@qingflow-tech/qingflow-cli@latest`；会预检 Node.js、npm、Python 3.11+；若全局 npm 目录权限不足，会 fallback 到用户目录（macOS/Linux 为 `~/.local`，Windows 为用户 AppData npm 目录）并提示 PATH 配置，不会自动改 shell 文件。排障可加 `--verbose`。环境：Node.js v16+、npm、Python 3.11+、可达 npm registry / 轻流 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
+  --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
+```
 
-| 用户意图 | 默认入口 | 专项说明 |
-| --- | --- | --- |
-| 普通应用数据查询、单条读取、直接增删改 | `qingflow data query/get/insert/update/delete` | [data 操作说明](./reference/data/README.md) |
-| 简单筛选计数（例如“有几条”） | `data query --where-file`，读取 `records.total` | [data 操作说明](./reference/data/README.md) |
-| 分布、比例、排名、趋势等需要全量样本的分析 | `data query --all --output csv -> Python/pandas` | [数据分析说明](./reference/record/analysis/README.md) |
-| 待办、已办、抄送、审批、转交或退回 | `qingflow task ...` | [任务上下文 SOP](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md) |
-| Excel 模板、文件校验、修复、启动导入与状态 | `qingflow import ...` / `record schema import` | [批量导入 SOP](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) |
-| 应用、表单、字段、视图、报表、门户与流程搭建 | `qingflow builder ...` | [Builder 总导航](./reference/builder/README.md) |
-| 完整数据／流程日志 | `qingflow record logs` | [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md) |
-| 附件、图片与详情页上下文 | `qingflow record get` | [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md) |
-| 代码块字段执行 | `qingflow record code-block-run` | [代码集成说明](./reference/builder/code-integrations/README.md) |
-| 安装、版本或命令能力确认 | `qingflow --json version` / `qingflow ... --help` | [命令索引](./reference/00-INDEX.md) |
+### 交付网页资源链接
 
-## 应用数据最短示例
+创建、修改或安装轻流资源后，最终回复主动提供主要结果的可点击页面入口，无需等待用户再次索要。采用“完成结果 + 查看入口”，文案使用“在轻流中查看应用／应用包／视图”，不默认称为“继续编辑”。
 
-以下示例只说明流程和 JSON 形状，不替代当次 `--help`，也不复制操作符矩阵、权限规则或字段类型表。首次读取默认保留 schema；后续根据响应中的 `schema`、`field_capabilities`、`access` 和 `hints` 决定下一步。
+默认只交付用户请求的主要结果：安装方案默认提供应用包入口；直接创建或修改应用、视图时提供对应入口；用户明确要求多个主要对象时分别提供。使用业务结果中的稳定 `uri`，按 URI 去重，不为全部子资源预签票据。主要对象没有可靠 URI 时说明限制，不猜地址，也不替换为不相关页面。
 
-### 普通查询
+CLI 返回的稳定 `uri` 以 `QINGFLOW_BASE_URL` 为当前环境来源：去除末尾 API 路径后使用同一 HTTP(S) 域名；仅当该变量为空时回退 `https://qingflow.com`。若非空配置非法，保留 URI 不可用诊断，不自行替换或拼接其他环境地址。
+
+部分成功时仅交付已确认成功且可定位的主要结果，保留失败或未验证说明。纯数据问答、中间读取、失败资源和删除操作不自动签发；用户明确要求不提供链接时遵从。用户明确要求查看或打开页面时也使用已确认的路径。
+
+目标浏览器登录态未知时，临近交付取主要结果稳定 `uri` 的完整 pathname 执行，不得丢失应用包、应用或视图层级；视图任务不得退化成应用入口：
 
 ```bash
-qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
+qingflow auth login-link --redirect-path "<主要结果 uri 的完整 pathname>"
+# 自定义视图 pathname 示例：/resources/ws/<WS_ID>/app/<APP_KEY>/view/custom/<VIEW_KEY>
 ```
 
+对每个实际展示的入口分别签发，使用本次返回的完整 URL，不额外追问登录态，不复用已消费链接。只有已有用户确认同一浏览器、网页域名、账号和工作区已登录、没有失效信号的事实，才直接交付稳定 `uri`。CLI 已登录、自动化浏览器已登录或曾经成功签发票据都不能证明目标浏览器已登录。
+
+用户未要求打开时不要提前打开或消费链接；签发失败时说明免登录链接未生成，并提供标注“需登录”的稳定 `uri` 作为备用入口，不重做业务操作。机器结果继续保留稳定 URI，临时登录链接仅用于面向用户交付。
+
 常用参数：`--credential-stdin`、`--password-stdin`、`--persist` / `--forget-persisted`；详见 `qingflow auth --help`。
 
 ---
@@ -173,91 +216,277 @@ qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
 **成员 / 部门候选排障**：若成员、部门字段返回 `needs_confirmation` 或候选不清，使用 `qingflow record member-candidates` / `qingflow record department-candidates`；它们优先走表单字段候选范围接口（与前端选择器一致）。不要改用通讯录管理类查询去“补候选”，那会把普通成员误带到 ContactAuth 管理权限链路。
 
 **部门名筛选 / 写入**：`record list/access/analyze/insert/update` 遇到部门字段时可直接传部门名或候选对象；CLI 会优先走成员可见的目录搜索解析部门。不要先用通讯录管理接口查询部门 id，否则普通成员容易被 ContactAuth 错误阻挡。
-### 字段筛选
 
-先运行一次不带 `columns` 的 query，从返回的 `schema` 与递归 `field_capabilities` 准确定位 `field_id`，并确认该字段暴露的 `filter_operators` 与 `value_shape`。再写筛选文件：
+**目录搜索边界**：按关键词找成员/部门应优先使用成员可见搜索（如 `directory_search` 或记录字段候选工具）；部门树遍历、外部联系人完整列表、builder 成员/角色检索、通讯录管理类查询属于配置/管理向能力，普通成员无权时不要当作记录读写失败。若目录工具返回 `CONTACT_DIRECTORY_PERMISSION_DENIED`，只表示 ContactAuth/通讯录管理边界不可读；记录成员/部门字段仍应改用 `record_member_candidates` / `record_department_candidates` 或直接按字段值写入。`builder member search --query` 与 `builder role search --keyword` 都必须传明确关键词，且不要作为记录成员/部门字段候选 fallback。
 
-```json
-[
-  {"field_id": 101, "op": "eq", "value": "已完成"}
-]
-```
+**导出 / 下载 / 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 data query \
-  --app-key APP_KEY \
-  --where-file tmp/where.json \
-  > tmp/qingflow_data_filtered.json
+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`。
 
-只为 `field_capabilities` 中 `sort_supported=true` 的字段构造排序：
+**找应用包（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/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) §2.3** 与 **[scripts/builder-package-from-app-list.py](./scripts/builder-package-from-app-list.py)**。
 
-```json
-[
-  {"field_id": 102, "direction": "desc"}
-]
-```
+**按关键字找应用（成员可用）**：默认直接用 **`app list --query`**，它只读取当前用户可见应用并在本地过滤，响应看 `items[].app_key`、`matched_count`、`unfiltered_count`、`filter_mode`。
 
 ```bash
-qingflow --json data query \
-  --app-key APP_KEY \
-  --sort-file tmp/sort.json \
-  > tmp/qingflow_data_sorted.json
+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/core/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/core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+
+---
+
+## 典型工作流示例（含落盘）
+
+### 待办查询
 
-先请求第一页，并按响应 `hints` 执行：`RESULT_IS_PARTIAL` 时保持筛选与排序继续下一页，`RESULT_IS_COMPLETE` 时立即停止；不凭总数猜页数。
+不限定应用时 **不要写死 `--app-key`**，直接落盘列举（详见下节 SOP）：
 
 ```bash
-qingflow --json data query --app-key APP_KEY --page 1 --page-size 100 \
-  > tmp/qingflow_data_page_1.json
-qingflow --json data query --app-key APP_KEY --page 2 --page-size 100 \
-  > tmp/qingflow_data_page_2.json
+qingflow --json task list --task-box todo --flow-status all --page 1 --page-size 50 \
+  > tmp/qingflow_tasks.json
 ```
 
-### 单条详情
+已知 `APP_KEY` 时再收窄：
 
 ```bash
-qingflow --json data get --app-key APP_KEY --record-id RECORD_ID \
-  > tmp/qingflow_data_get.json
+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/task/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/core/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` 取）。最终统计结论、分析报告、趋势/排名/比例/分布必须按 **[record/analysis](./reference/record/analysis/README.md)** 使用 `record access -> Python/pandas`。
 
 ```bash
-qingflow --json data query \
-  --app-key APP_KEY \
+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 \
-  --all --output csv \
-  > tmp/qingflow_data_analysis.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/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**管理向**（检索/导入等）见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+
+`record delete` 必须传可访问的系统 `--view-id system:*`；删除前可用 custom/system view 的 `record list/get` 精确定位 record_id，但真正删除提交不要传 `custom:*`、`list_type`，也不要省略系统视图上下文。完整规则见 **[RECORD_DELETE](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md)**。
+
+### 注销
+
+```bash
+qingflow auth logout --forget-persisted
 ```
 
-读取响应中的全部 `files[].local_path`，只在 `complete=true`、`truncated=false`、`safe_for_final_conclusion=true` 时形成完整总体结论；具体分析步骤见 [数据分析说明](./reference/record/analysis/README.md)。
+---
 
-## 写入与专项边界
+## 常见失败与处理
 
-- `data insert/update/delete` 是普通应用数据直接写入入口。写入前用只读 `data query/get` 获取 schema、字段能力与访问范围；删除、覆盖已有值、批量写入或其他不可逆操作必须先确认目标和影响范围。
-- `task`、builder、import 均按路由表进入专项文档；主 Skill 不复制其参数、枚举或完整 SOP。
-- 导出／下载只有用户明确需要文件时才使用，并按对应命令要求提供视图上下文；不要把导出当作普通查询或统计分析默认入口。
-- 查看视图时，`baseInfo` 或 `viewConfig` 只有 40002 / 40027 / 404 这类权限/缺失边界可用另一侧降级，非权限类后端错误不隐藏；完整规则见 Builder 视图文档。
 
-## record 专项
+| 迹象                                                               | 处理                                                                                                                                      |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| 未登录 / profile 未登录                                                | **再**走「认证方式」节，重试业务命令                                                                                                                    |
+| `record_list requires view_id`                                   | 先 `app get --app-key`，取 `view_id`                                                                                                       |
+| JSON 内 `backend_code` / `error_code`                             | 区分配额、权限与参数错误；普通成员见上节「偏向管理」；非本技能速查表覆盖的报错见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/core/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/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)** |
 
-`record` 用于完整数据／流程日志、附件和图片上下文、代码块字段执行，以及用户指定的 `record` 操作。
 
-普通应用数据使用 `data`。不得改用 `record list/access/get/insert/update/delete` 绕过 data 返回的权限、字段能力或校验结果。日志与附件操作阅读 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)；`record delete` 提交不要传 `custom:*`、`list_type`，细则见 [record 删除参考](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md)。
+---
 
-## 关联入口
+## 命令速查（骨架）
 
-- [复杂命令总索引](./reference/00-INDEX.md)
-- [data 操作说明](./reference/data/README.md)
-- [任务上下文 SOP](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)
-- [批量导入 SOP](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)
-- [数据分析说明](./reference/record/analysis/README.md)
-- [Builder 总导航](./reference/builder/README.md)
-- [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)
+**何时须细读引用、勿凭本节推测**：见**文首「硬约束（必读）」**。
+
+> **适用范围**：普通/基本成员在只读或小范围写入里**较高概率可用**的形态；勿照抄旧应用搜索入口、无权的 **`import …`**（易 **40002 / IMPORT_\***）；管理闭环见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/core/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 login-link [--redirect-path PATH]`（临时网页登录链接）· `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`，二者勿混）· `record delete --app-key --record-id --view-id system:*` / `--record-ids-file` · `export start/direct --view-id` 仅用于明确导出文件 · **大 schema**：先 **[FIELD_DATA_TYPES](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)** / **[RECORD_CREATE](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)** / **[RECORD_UPDATE](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)** / **[RECORD_DELETE](./reference/record/QINGFLOW_CLI_RECORD_DELETE_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/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)** |
+| **builder** | **搭建／系统化配置**：先按 **[INDEX](./reference/00-INDEX.md)** / **[BUILDER](./reference/builder/README.md)** 选主路径，再读 `builder contract`。**完整系统/应用包**：`builder package apply --config-file` → 每个应用依次执行 `builder app-form schema`、更新时 `get --app-key APP_KEY --being-draft`、`validate --schema-version VERSION --file DECLARATION.json`、`apply --file DECLARATION.json`（固定版本、完整声明、记录返回的 `appKey`）→ 视图（按钮随视图 `action_buttons` 写）→ 门户（缺报表时写 `chart`）→ 发布/回读。旧 `schema apply` / `layout apply` 不在当前 CLI parser 中。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先读取 AppForm draft/published，再恢复，不得重复创建或创建 V2/测试/随机后缀绕过重名。**单应用**：新建和更新遵循同一 AppForm CLI 链路，再按需求配置流程/视图。更新动作归入对应资源文档：AppForm [30](./reference/builder/30-schema-fields.md)、视图 [50](./reference/builder/50-views.md)、报表 [60](./reference/builder/60-charts.md)、门户 [70](./reference/builder/70-portal.md)、关联资源/非主链路按钮维护 [80](./reference/builder/80-buttons-associated-resources.md)、流程 [90](./reference/builder/90-workflow.md)、发布 [99](./reference/builder/99-publish-verify.md)。**AI 公式/代码块校验**：`builder app-form validate-formula --app-key KEY --formula '<公式>' --test-case <文件路径>`（`--formula` 内联；`--test-case` **只收文件路径或 `-` stdin，不收内联 JSON**）与 `builder app-form validate-code-block --app-key KEY --code <内联文本|@文件路径> --test-case <文件路径>`（本地静态 + 后端真跑，输出 `staticErrors` / `runResult` / `runError`）；两者是公式/代码块生成场景的真实校验命令，校验结论必须来自其真实执行，不得以本地模拟替代。代码内占位符 `qf_field.{字段名$$queId$$}`（**字段名不带引号**，带引号会被 CLI 自动剥离但勿依赖）与 `keyQueId` 均使用**十进制** queId（CLI 真跑前自动编码为运行时形态；错误回显自动还原为十进制，勿逆向编码 id）。test-case values 按类型：文本/电话=字符串、数字=数字字面量、日期=yyyy-MM-dd、附件=URL 字符串数组、单选/下拉/多选=选项文案（CLI 自动译为选项 id）、成员/部门=不可提供（代码判空,覆盖校验豁免）。 |
+| **task**（须落盘见上文） | `task list [--task-box][--flow-status][--app-key][--query] --page --page-size`（**枚举、`--query`、与 `record` 视图口径勿混**：见上文 SOP · **[TASK_CONTEXT](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)**）· **`get`/`log`/`report`/`action`**：默认只传 `task list` 返回的 **`data.items[].task_id`**；`report` 另须必选 **`--report-id`**；`action` **无 `--dry-run`** |
+
+### 临时网页登录链接
+
+按上文“交付网页资源链接”规则，在创建、修改或安装完成后主动为主要结果提供查看入口；用户明确要求进入页面时也适用，纯数据问答不自动调用：
+
+```bash
+qingflow --json auth login-link
+qingflow --profile default --json auth login-link --redirect-path "<主要结果 uri 的完整 pathname>"
+# 自定义视图 pathname 示例：/resources/ws/<WS_ID>/app/<APP_KEY>/view/custom/<VIEW_KEY>
+```
+
+- 默认使用当前会话和已选工作区；缺失时按实际错误恢复，不额外预查或重新登录。pathname 必须保留主要对象的完整层级，视图任务不得改用应用 pathname。
+- `--redirect-path` 可选，仅接受已确认的站内业务路径，可包含 query/hash；不接受外域或认证入口。示例 ID 仅作格式展示，不得照抄或编造实际目标；省略时进入工作区首页。
+- 将返回的 `url` 作为可点击链接交付，不修改或拼造。链接短时有效且仅可使用一次，失效后重新获取，不写入公共文档或日志。
+- 命令不会自动打开浏览器；用户未要求打开时不提前打开或消费链接，明确要求打开时才调用浏览器。
+
+**高发必败**：旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。
+
+更多成员策略：**[reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** · 一次性长模板：**[reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** · 对齐说明：**[reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。
+
+---
 
-维护时用 `qingflow --json version`、`qingflow data --help` 与对应专项 `--help` 复核，不根据历史文档补造参数。
+*技能维护：CLI 升级时以 `qingflow --version`、`qingflow … --help` 与本文 **task-box / flow-status** 对照表为准复核。*

package/skills/qingflow-cli/manifest.yaml

@@ -1,6 +1,6 @@
 identity: qingflow_cli
 type: skill
-description: 「使用 qingflow CLI 的任何命令或自动化脚本前必须先调用本 Skill」。普通应用数据使用 data；日志、附件、导入、代码块和用户明确指定的 record 命令使用对应专项入口；task、builder 与 workflow 通过 reference 子目录分流。默认不把登录或工作区校验作为业务前置。
+description: 「使用 qingflow CLI 的任何命令或自动化脚本前必须先调用本 Skill」。Qingflow CLI 包以本 Skill 作为 CLI 主入口；record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。涵盖安装、执行上下文失败恢复、task/record/import/builder 查询落盘规则、普通成员读数速通、record list 模糊定位、record get 详情上下文、record access 分析取数、record insert/update/delete/import、任务上下文 SOP。Builder reference 按智能体任务路径组织：单应用、完整系统/应用包、AppForm、视图、报表/QingBI、门户、关联资源、流程、发布校验；表单字段、布局和应用设置统一使用 versioned AppForm（CLI 为 builder app-form schema/get/validate/apply），不再使用已移除的 schema/layout apply；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读、批量写、局部改作为资源内写法变体；默认不把登录或工作区校验作为业务前置
 tags:
   - cli
   - qingflow

package/skills/qingflow-cli/reference/00-INDEX.md

@@ -6,10 +6,10 @@ Use this file as the first routing page after `SKILL.md` when the task is not a
 
 | User goal | Read first | Then read |
 |-----------|------------|-----------|
-| Read records, locate one record, inspect schema | [data 操作说明](./data/README.md)：`data query` / `data get` | 当前 `data --help` 与 data schema |
-| Create records | [data 操作说明](./data/README.md)：`data insert` | 当前 `data insert --help` 与 data schema |
-| Update records | [data 操作说明](./data/README.md)：`data get` → `data update` | 当前 `data update --help` 与 data schema |
-| Delete records | [data 操作说明](./data/README.md)：`data query/get` 确认目标 → `data delete` | 当前 `data delete --help` |
+| Read records, locate one record, inspect schema | [core/data retrieval](./core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | [core/field data types](./core/QINGFLOW_CLI_FIELD_DATA_TYPES.md) |
+| Create records | [record/create](./record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | [record/insert details](./record/insert/README.md) |
+| Update records | [record/update](./record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md) | [core/field data types](./core/QINGFLOW_CLI_FIELD_DATA_TYPES.md) |
+| Delete records | [record/delete](./record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md) | - |
 | Import records in bulk | [record/import](./record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) | - |
 | Statistical analysis, ratios, rankings, trends | [record/analysis](./record/analysis/README.md) | [analysis patterns](./record/analysis/analysis-patterns.md) |
 | Task/todo context or task action | [task context](./task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md) | [task ops](./task/ops/README.md) |

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

@@ -43,7 +43,7 @@
 
 ## 4. 记录数据
 
-与 **[成员速查](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 及 **[SKILL.md](../SKILL.md)** 一致：直接数据操作使用 [data 操作说明](./data/README.md)；最终统计结论、分析报告、趋势/排名/比例/分布统一使用 **`data query --all --output csv -> Python/pandas`**。
+与 **[成员速查](./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`**。
 
 ---