@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md

@@ -0,0 +1,31 @@
+# Qingflow CLI：删除记录 SOP
+
+删除记录是高风险写操作，默认先定位、再确认目标、再最小删除。
+
+## 主链路
+
+```bash
+qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID> --query "<关键词>"
+qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> --view-id <VIEW_ID>
+qingflow --json record delete --app-key <APP_KEY> --record-id <RECORD_ID> --view-id system:all
+```
+
+批量删除用文件传 record ids：
+
+```bash
+qingflow --json record delete --app-key <APP_KEY> --record-ids-file tmp/delete_record_ids.json --view-id system:all
+```
+
+`tmp/delete_record_ids.json` 是记录 ID 数组：
+
+```json
+["535734615263924225", "535734615263924226"]
+```
+
+## 规则
+
+1. 先用 `record list` 或 `record get` 解析精确 `record_id`，不要用模糊标题直接删。
+2. 高风险或批量删除前，向用户确认记录数量、关键字段和应用名。
+3. `record delete` 必须传可访问的系统 `--view-id system:*`；读取定位时可以使用 custom/system view，删除提交时不要传 `custom:*`、`list_type`，也不要省略系统视图上下文。
+4. 删除后需要验证时，用 `record get` 或 `record list` 读回确认；读回 404/不存在才代表已删除，权限型 40002 只说明当前读回路径不可见。
+5. 批量删除若出现部分成功，按返回的成功/失败项只处理失败 ID，不要重放全批。

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md

@@ -0,0 +1,176 @@
+# 记录批量导入 SOP：`app_get`（`import_capability`）→ 模板 → 校验 →（可选）本地修复 → 启动 → 状态
+
+本文与 **MCP 工具命名**一致，并映射到 **`qingflow` CLI**。编写前已 **实跑**：`app get`、`record schema import`、`import template`、`import verify`、`import repair`（未授权分支 + 授权分支遇 **合并单元格** 异常）、`import start`、`import status`（**仅** `--import-id`）；环境为当前持久化 CLI 会话、应用 `ead8ims5i401`。
+
+---
+
+## 1. 编排顺序（固定）
+
+| 顺序 | 工具名 | CLI | 说明 |
+|------|--------|-----|------|
+| 1 | `app_get` | `qingflow --json app get --app-key <APP_KEY>` | 读 **`data.import_capability`**，预检是否有导入能力 |
+| （可选） | `record_import_schema_get` | `qingflow --json record schema import --app-key <APP_KEY>` | `schema_scope: import_ready`，列 **`columns`**；能力仍以 **`app get`** 为准 |
+| 2 | `record_import_template_get` | `qingflow [--json] import template --app-key <APP_KEY> [--download-to-path <PATH>]` | 官方模板 URL 或 **本地生成的 applicant 模板**（无数据管理权限或导入权限预检未知时可能 fallback） |
+| 3 | `record_import_verify` | `qingflow [--json] import verify --app-key <APP_KEY> --file-path <*.xlsx\|*.xls>` | 产出 **`verification_id`**；**`can_import`** 为真后才应 **`import start`** |
+| （可选） | `record_import_repair_local` | `qingflow [--json] import repair --verification-id <UUID> --authorized-file-modification …` | **必须** 显式授权；**仅 `.xlsx`**；可重复 **`--repair`** |
+| 4 | `record_import_start` | `qingflow [--json] import start --app-key <APP_KEY> --verification-id <UUID> --being-enter-auditing <true\|false> [--view-key …]` | **会真实发起导入** |
+| 5 | `record_import_status_get` | `qingflow [--json] import status (--app-key \| --import-id \| --process-id-str)` **三者择一** | **不要**同时传多个 selector（例如 **`--import-id` 与 `--app-key` 同时**会被 CLI 拒绝） |
+
+CLI 注册见全局包 **`qingflow_mcp/cli/commands/imports.py`**（`template` / `verify` / `repair` / `start` / `status` → 上述 `ImportTools` 方法）。
+
+---
+
+## 2. `import_capability`（来自 `app get`）
+
+`app get` 在 **`data.import_capability`** 中附带由 `baseInfo` 推导的能力（实现：**`_derive_import_capability`**）：
+
+| 字段 | 含义 |
+|------|------|
+| **`can_import`** | `true` / `false` / `null`（未知） |
+| **`auth_source`** | `apply_auth`（申请人导入开关）、`data_manage_auth`（数据管理）、`none`、`unknown` |
+| **`applicant_import_enabled`** | 与 `dataImportStatus` 对应 |
+| **`data_manage_status`** | 与 `dataManageStatus` 对应 |
+| **`runtime_checks_required`** | 预检后仍可能受 **`user_disabled`**、**`function_demoted`** 等运行态影响 |
+| **`confidence`** | `preflight`（由元数据推出）或 `unknown` |
+
+- **`record_import_schema_get` / `record_import_template_get` / `record_import_verify`**：若 `can_import === false` 且来源非 `unknown`，会直接 **`IMPORT_AUTH_PRECHECK_FAILED`**，不会继续读取导入列、官方模板或进入后端文件校验。
+- **`record_import_template_get`**：当具备申请人导入能力但无数据管理权限时，可能对 **`/app/{appKey}/apply/excelTemplate`** 失败并 **本地生成** applicant 模板（警告 **`IMPORT_TEMPLATE_LOCAL_FALLBACK`**）。
+- 若 **`app get` / `baseInfo`** 权限受限导致 **`import_capability.auth_source: unknown`**，但 applicant 字段 schema 可读，且官方模板接口返回 **40002 / 40027**，`record_import_template_get` 也可能返回 **`status: partial_success`** 并本地生成模板（警告 **`IMPORT_TEMPLATE_LOCAL_FALLBACK_AUTH_UNKNOWN`**）。这只说明“模板准备成功”，**不证明用户有导入权限**；后续仍以 **`record_import_verify` / `record_import_start`** 的 `can_import` 与最终结果为准。
+
+---
+
+## 3. 本地校验仓与运行环境
+
+- **`verification_id`** 由 **`record_import_verify`** 生成，并写入本机 **`~/.qingflow-mcp/import-verifications/<id>.json`**（**`ImportVerificationStore`**）。
+- **`record_import_start` / `repair`** 依赖该目录；**自动化/CI 需允许写此目录**，且 **`verify` → `start` 须在** 同一 profile、可达后端的会话内完成。
+- **`record_import_status_get`** 在仅传 **`--import-id`** 时，会结合本地 **`ImportJobStore`** 与后端 **`GET /app/apply/dataImport/record`** 解析 **`app_key` / `process_id_str`**；与 **`import start`** 返回的 **`import_id`**、**`process_id_str`** 对齐使用。
+
+---
+
+## 4. 命令要点
+
+### 4.0 文件形态、CSV 源数据与字段映射
+
+- 当前 `import verify/start` 主链路面向官方 Excel 模板（`.xlsx` / `.xls`），不是直接把任意 CSV 交给后端。
+- CSV 可以作为源数据或中间表，但必须先映射到官方模板列名，再写入模板副本；不要改模板表头。
+- 字段映射以 `record schema import` / 模板列为准：源列名可以是用户习惯名，目标列名必须是官方模板 header。
+- 关联字段批量导入优先使用稳定 `record_id` 或 schema 明确支持的唯一搜索值；显示名可能重复时不要猜。
+- 成员/部门字段必须使用 schema/candidate 范围内的值；选项字段优先使用模板里的选项文案。
+
+CSV 源数据示例（规划用）：
+
+```csv
+客户名称,关联客户,状态,负责人
+上海示例客户,CUST_RECORD_ID_001,有效,张三
+```
+
+映射到模板后的行语义：
+
+```json
+{
+  "客户名称": "上海示例客户",
+  "关联客户": "CUST_RECORD_ID_001",
+  "状态": "有效",
+  "负责人": "张三"
+}
+```
+
+### 4.1 模板
+
+```bash
+qingflow --json import template --app-key "<APP_KEY>" \
+  --download-to-path tmp/qingflow_import_template.xlsx \
+  > tmp/qingflow_import_template_meta.json
+```
+
+- 关注 **`verification.template_source`**：`official` 或本地 fallback。
+- 若 `verification.import_auth_prechecked: false`，表示模板来自 schema 可读分支但导入权限尚未预检成功；不要把该模板结果当作导入授权结论。
+- **`expected_columns`** 在部分响应负荷中给出；**与校验**一致。
+
+### 4.2 校验
+
+```bash
+qingflow --json import verify --app-key "<APP_KEY>" \
+  --file-path tmp/qingflow_import_template.xlsx \
+  > tmp/qingflow_import_verify.json
+```
+
+- 始终解析 **`verification_id`**；仅 **`can_import: true`** 时进入后端 multipart **`/upload/verification`**。
+- **标准输出**上 OpenPyXL 可能对某些 xlsx 打出 **`UserWarning`**（**出现在 JSON 前**）。 jq/直解 **`json.load` 失败时，从首个 `{` 起截取再解析**。
+
+### 4.3 本地修复（可选）
+
+```bash
+qingflow --json import repair \
+  --verification-id "<VERIFICATION_UUID>" \
+  --authorized-file-modification \
+  [--output-path tmp/repaired.xlsx] \
+  [--repair normalize_headers] [--repair trim_trailing_blank_rows] \
+  ... \
+  > tmp/qingflow_import_repair.json
+```
+
+- **未加** `--authorized-file-modification` → **`IMPORT_REPAIR_NOT_AUTHORIZED`**。
+- **`--repair`** 可重复；允许集合（实现 **`SAFE_REPAIRS`**）：
+  **`normalize_headers`**、**`trim_trailing_blank_rows`**、**`normalize_enum_values`**、**`normalize_date_formats`**、**`normalize_number_formats`**、**`normalize_url_cells`**。
+  **省略 `--repair`** 时实现默认对 **全集** 尝试。
+- **仅 `.xlsx`**；**合并单元格表格** 在 **`normalize_headers`** 等路径上可能触发 **`MergedCell` 只读** 类异常（实跑曾遇到）；此时应改模板或跳过 repair、重新导出模板再 **`verify`**。
+
+成功时返回 **`new_verification_id`**，后续 **`start`** 应用 **新 ID**（若 repair 后重新校验通过）。
+
+### 4.4 启动导入
+
+```bash
+qingflow --json import start \
+  --app-key "<APP_KEY>" \
+  --verification-id "<VERIFICATION_UUID>" \
+  --being-enter-auditing false \
+  [--view-key "<VIEW_KEY>"] \
+  > tmp/qingflow_import_start.json
+```
+
+- **`--being-enter-auditing`**：**必填**，布尔字面量：`true` / `false` / `1` / `0` / `yes` / `no` 等（见 argparse `parse_bool_text`）。
+- **会校验**：校验记录仍存在、**`can_import`**、**文件 sha256** 未变、**`schema_fingerprint`** 未变；否则 **`IMPORT_VERIFICATION_STALE`** / **`IMPORT_FILE_CHANGED_AFTER_VERIFY`** / **`IMPORT_SCHEMA_CHANGED_AFTER_VERIFY`**。
+
+### 4.5 状态
+
+**参数规则（CLI）**：**必须且只能** 提供 **`--app-key`**、**`--import-id`**、**`--process-id-str`** 中的 **一个**。
+
+```bash
+# 已知本次 start 返回的 import_id（不要同时加 --app-key）
+qingflow --json import status --import-id "<IMPORT_UUID>" \
+  > tmp/qingflow_import_status.json
+
+# 或只看该应用最近一次导入（仅 --app-key）
+qingflow --json import status --app-key "<APP_KEY>" \
+  > tmp/qingflow_import_status_latest.json
+```
+
+---
+
+## 5. 与 `record schema import` 的关系
+
+- **`record schema import`**：专注 **导入列 / 指纹**（与校验用的 schema bundle 一致思路），**不替代** **`app get` 的 `import_capability`**。
+- 推荐顺序：**`app get`（能力）** →（可选）**`record schema import`（列清单）** → **`import template`** → …
+
+---
+
+## 6. 实测摘要（编写时）
+
+| 步骤 | 结果 |
+|------|------|
+| `app get` | `import_capability.can_import: true`，`auth_source: data_manage_auth` |
+| `record schema import` | `schema_scope: import_ready` |
+| `import template --download-to-path` | 落盘 xlsx 成功 |
+| `import verify` | `can_import: true`，`verification_id` 可用；可能有 **`IMPORT_HEADERS_AUTO_NORMALIZED`** |
+| `import repair --authorized-file-modification` | 特定模板因 **合并单元格** 在 **`normalize_headers`** 崩溃；属 **模板/实现边界** |
+| `import start` | `status: accepted`，返回 **`import_id`**、**`process_id_str`** |
+| `import status --import-id …` | 返回 `app_key`、**`process_id_str`**、**`status`**（后端枚举字符串，如实测 `"3"`） |
+| `import status --import-id … --app-key …` | **CLI 拒绝**：只能选一个 selector |
+
+---
+
+## 7. 交叉引用
+
+- 主技能 [SKILL.md](../../SKILL.md)：**落盘**、导入类权限码 **`IMPORT_*`** 提示。
+- [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](../core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)：管理侧与 **`IMPORT_*`** 失败排查。

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md

@@ -0,0 +1,167 @@
+# Qingflow CLI：更新记录工作流（详情后直接写入）
+
+> **用途**：使用当前 CLI 会话读取目标记录详情后，用 **`record update`** 直接提交差异字段。主链路是 `record get -> record update`；字段范围不清、候选歧义或失败排查时，才追加 **`record schema update`**。
+> **关联**：只读列表/详情见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**字段 `kind` 与写入值总表**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；最终统计结论统一使用 **[record/analysis](./analysis/README.md) 的 `record access -> Python/pandas`**；**成员 / 部门等** 的细颗粒写入见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
+
+---
+
+## 习惯概念名 → CLI
+
+| 概念名 | CLI |
+| --- | --- |
+| `app_get`（含 `accessible_views`） | `qingflow --json app get --app-key <APP_KEY>` |
+| `record_schema_get`，`schema_mode=browse`，带 `view_id` | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>` |
+| `record_get` | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` |
+| `record_update`（单条） | `qingflow --json record update --app-key <APP_KEY> --record-id <RECORD_ID> --fields-file <FIELDS.json> [--view-id <VIEW_ID>]` |
+| `record_update`（批量） | `qingflow --json record update --app-key <APP_KEY> --items-file <ITEMS.json> [--view-id <VIEW_ID>] [--dry-run]`（见下文） |
+
+---
+
+## 推荐顺序
+
+```text
+record get（得到 RECORD_ID、当前值、fields[].title/field_id/kind；已知前端视图时带 view_id）
+  → 智能体按用户要求组 fields key/value
+  → record update --fields-file [--view-id]（只提交需要改的题；大 JSON 落盘）
+```
+
+**何时先 `app get` / `record list`**：不知道 `view_id` 或 `record_id` 时，先用 `app get` 选视图，再用 `record list` 定位候选。已知 `record_id` 但已知前端/custom view 时，直接 `record get --view-id <VIEW_ID>`。
+**何时追加 `record schema browse`**：只在需要提前看视图表头或搜索字段时使用；`record get` 已经会返回单条详情所需字段信息。
+**何时追加 `record schema update`**：该命令 **必须 `record_id`**，返回 **`writable_fields` / `payload_template` / `available_update_routes` / `recommended_update_route`**，只用于排查「能改什么」和「会走哪条更新路径」。已知前端/custom view 时同样带 `--view-id`，让诊断优先探测同一个详情页上下文；字段明确时不要把它当必经步骤。
+
+**更新路径自动选择**：`record update --view-id <VIEW_ID>` 会优先用这个 view 做字段解析和 custom view 写入候选；未传时自动探测可读 route。写入时仍会先尝试 **数据管理员直改**，若后端返回权限拒绝，再 fallback 到 **前端同源 custom view 详情编辑路径**；如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑，最后会尝试 **workflow save-only**。成功时响应中的 **`update_route`** 是最终成功路径；失败时再查看失败原因与路线诊断。若诊断里有 `40002`，只代表某条 route 被拒绝，不一定表示用户对记录完全无编辑能力。
+
+---
+
+## 命令模板
+
+**1）读取详情**
+
+```bash
+qingflow --json record get \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_record_get.json
+```
+
+已知用户前端所在视图时传同一个 `--view-id`；未知时 CLI 默认先尝试 `system:all/type=8`，若该详情 route 被权限/不可见类错误拒绝，会继续尝试可访问视图。读取 `fields[]` 中的标题、`field_id`、`kind` 与当前值来组更新 payload。
+
+`record_get` 的 `unavailable_context[]` 是辅助上下文提示：`detail_schema` / `audit_info` / 首屏日志等 40002 不等于记录详情读取失败。只要顶层 `status=ok` 且 `fields[]` 中已有目标字段，就按这些字段组 `record update` 的 key/value；只有顶层失败才按失败原因排查。
+
+`record update` 的字段集合应是当前 `record get.fields[]` 的子集。带 `--view-id` 时，当前前端详情/视图隐藏的字段不要强写；字段不在 `fields[]` 中时，先切到包含该字段的视图/详情上下文，或用 `record schema update` 诊断可写字段和失败路径。`FIELD_NOT_FOUND` 通常表示当前更新上下文没有这个题，不等于整条记录不可编辑。
+
+**2）如果缺 `record_id`，先定位候选**
+
+```bash
+qingflow --json record list \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_records.json
+# 或
+qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> \
+  > tmp/qingflow_record_get.json
+```
+
+**3）单条更新**
+
+```bash
+qingflow --json record update \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --fields-file tmp/qingflow_patch_fields.json \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_update_result.json
+```
+
+`--view-id` 可省略；已知用户来自某个 `custom:...` 前端详情页时建议传入，CLI 会优先尝试该 view，失败后再按自动路径 fallback。
+
+**4）（仅排障）本条记录的更新诊断**
+
+```bash
+qingflow --json record schema update \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_schema_update.json
+```
+
+**`tmp/qingflow_patch_fields.json`**：JSON **对象**，键为 **题目标题**（优先来自 `record get.fields[]`），**只放需要修改的键**；值类型与 **新建** 相同（成员、部门、附件等见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**）。实现要求 **`fields` 为「按标题索引的 map」**（与 `record insert` 一致）。
+
+不要把 schema 中见过但当前 `record get.fields[]` 没出现的隐藏字段直接放进 `fields-file`。这会让智能体把视图上下文问题误判成权限或字段不存在问题。
+
+**特殊字段值**：
+
+- **成员字段 `kind=member`**：先传自然语言字符串，如 `{"客户成功":"周颖"}`。若返回 `status="needs_confirmation"`，说明尚未写入；从 `confirmation_requests[].candidates[]` 选一项，改传显式对象，如 `{"客户成功":{"uid":1048599,"name":"沈嘉慧Seth","email":"shenjiahui@exiao.tech"}}`。
+- **部门字段 `kind=department`**：先传部门名，如 `{"负责部门":"客户成功部"}`；歧义时同样按候选对象/id 重试。
+- **关联字段 `kind=relation`**：传唯一可解析的自然语言、或 `{"apply_id":"..."}`；多匹配时按候选记录重试，不要猜 `apply_id`。
+- **选项字段 `kind=select`**：单选传一个选项字符串；多选传字符串数组。
+- **引用/公式/自动填充/只读/系统字段**：不要强写目标字段；改写上游驱动字段，或把 blocker 原因反馈给用户。
+
+`needs_confirmation` 的语义是 **`write_executed=false`，等待确认候选**；不要把它当成功，也不要把它当最终权限失败。只有用明确候选对象重试并成功后，才报告写入完成。
+
+**`--verify-write` / `--no-verify-write`**：见 `qingflow record update -h`；默认倾向 **保留校验**。
+
+更新后优先查看：
+
+- **`update_route.route_type`**：`admin_direct`、`view_edit` 或 `task_save_only`。
+- **`tried_routes[]`**：只在失败或 verbose 诊断时需要看；成功时不要把中间路径失败当最终结果。
+- **`write_executed`**：是否已经发出写请求；为 `true` 时不要盲目整单重试。
+- **`verification_status`**：读回校验是否通过。
+
+**`record_id` 与写入（排查前置）**：若后端 **`record_id` 超出 JavaScript `Number.MAX_SAFE_INTEGER`（约为 `9007199254740991`）**：在旧 1.0.x 或同类实现分支上，**`record list` / `record get` / `record schema update` 常仍可正常**，而 **`record update` 的实际落库**可能在 **`apply_id` 二次校验**处失败——stdout 常表现为 **`apply_id must be positive`**，根本原因多为 **「整数超过 JS 安全范围」**。**批量 `--dry-run`** 仍可用于覆盖 **预检**流程。处理方式见 **「排查摘要」**末行。
+
+---
+
+## 批量模式（`--items-file`）
+
+- **不可**与 **`--record-id` / `--fields-file`** 同时使用。
+- `items` 为 **数组**，每项为对象，至少包含：
+  - **`record_id`**：正整数（字符串或可解析数字均可，以 CLI 校验为准）
+  - **`fields`**：与单条相同的「标题 → 值」map
+
+示例：
+
+```json
+[
+  { "record_id": "518257794791628802", "fields": { "客户名称": "新名称" } },
+  { "record_id": "518257794791628803", "fields": { "备注": "批量第 2 条" } }
+]
+```
+
+- **`--dry-run`**：**仅批量模式**支持（单条模式需走 `items-file` 才能 dry-run）；用于预检。详见 `qingflow record update -h` 与 CLI 报错指引。
+- 批量输出优先读顶层语义，不需要再钻进 `data.summary`：
+  - `mode="batch"`、`dry_run`
+  - `total`、`succeeded`、`failed`、`needs_confirmation`
+  - `updated_record_ids`
+  - `write_executed`、`safe_to_retry`、`verification_status`
+  - `items[].row_number / record_id / status / failed_fields / confirmation_requests`
+- `dry_run=true` 时 `write_executed=false`、`safe_to_retry=true`，只能说明预检通过；真正写入仍需去掉 `--dry-run` 再执行。
+- `write_executed=true` 后不要盲目整批重试；根据 `items[].row_number` 和 `updated_record_ids` 判断是否只补失败行。
+
+---
+
+## 安全与落盘
+
+- **`record update` 为写操作**；仅在授权环境、**必要时**对测试应用演练。
+- **`list` / `get` / `schema browse` / `schema update` / 更新结果** 体大量时按主技能 **落盘规则** 重定向。
+- 主技能 **危险操作** 中对 `record update --dry-run`（批量）的说明仍适用。
+
+---
+
+## 排查摘要
+
+| 现象 | 处理 |
+| --- | --- |
+| 缺 `record_id` | 先用 **`record list`**（同一 `view_id`）或 **`record get`**。 |
+| 不知道字段标题或当前值 | 先查 **`record get`** 的 `fields[]`。 |
+| 不知道能改哪些题 / 路径失败 | 再查 **`record schema update`** 的 `writable_fields` / `payload_template` / 路径诊断；它不是主链路前置步骤。 |
+| 配置类报错 | 单条更新必须 **`--record-id` + `--fields-file`**；批量必须 **`--items-file`**，且勿混用单条参数。 |
+| `needs_confirmation` | 尚未写入；从 `confirmation_requests[].candidates[]` 选明确对象/id 后重试，再读回确认。 |
+| `40002` | 先看 **`tried_routes`**：如果 `admin_direct` 拒绝但 `view_edit` 或 `task_save_only` 成功，说明某条具体通道不可用但仍有可写路径；如果所有 route 都拒绝，再按权限问题处理。 |
+| 成员/部门格式错误 | 与 **创建记录** 文档同一套结构；必要时用 **`record member-candidates` / `record department-candidates`** 走字段候选范围。不要改用 `builder member search` 做记录字段候选。 |
+| **`apply_id must be positive`**，或内部报错含 **`exceeds JavaScript's safe integer range`**（单条 **`record update`** 或批量 **非 dry-run**） | **`record_id` 典型超出 JavaScript 安全整数上限**（`Number.MAX_SAFE_INTEGER`，约为 `9007199254740991`）：读链路与 **`schema update`、批量 `--dry-run`** 可走通；**写入**须在 **新版本 CLI** 重做或向维护方确认。短期仅用 **更小 id 的授权测试应用/记录**演练。 |
+
+---
+
+*维护：复核 `qingflow record schema update -h`、`record update -h`；`view_id` 与成员策略以当前 CLI help 与同目录成员速查表为准。*

package/skills/qingflow-cli/reference/record/analysis/README.md

@@ -0,0 +1,130 @@
+# Qingflow CLI Record Analysis
+
+Use this section for final statistical conclusions: counts, distributions, ratios, averages, rankings, trends, comparisons, and analysis reports.
+
+Default path, every time:
+
+```text
+app get -> record schema browse(view_id=...) -> record access -> Python/pandas -> final answer
+```
+
+Use the CLI entry:
+
+```bash
+qingflow record --help
+qingflow record access --help
+qingflow record access --app-key APP_KEY --view-id VIEW_ID --columns-file columns.json --where-file where.json --order-by-file order_by.json --json
+```
+
+The CLI command is under the `record` command group, so the discovery path is: first inspect `qingflow record --help`, then inspect `qingflow record access --help`.
+
+## Hard Rules
+
+- Never start analysis from `record_list`, export, QingBI, or guessed field ids.
+- Never conclude `record_access` is unavailable just because it is not visible as a top-level MCP tool; check the CLI path `qingflow record access`.
+- Never call `record access` before `record schema browse`.
+- Use only field ids returned by `record schema browse`.
+- If `app_get.accessible_views[].analysis_supported=false`, do not use that view for `record_access`.
+- Prefer an explicit time range or business filter. If the user gives none and the table may be large, ask for scope or use a clearly provided month/quarter/year.
+- Read every CSV shard in `record_access.files[].local_path` with Python. Do not print raw CSV or load raw rows into model context.
+- Before final analysis, run a field-quality profile in pandas: row count, null rate, distinct count, and period coverage for candidate grouping fields.
+- Do not use a high-missing field as the main conclusion dimension. If a candidate dimension is sparse, downgrade it to an `已填写样本观察` and choose a cleaner semantic fallback when available.
+- Full final conclusions require `record_access.complete=true` and `record_access.safe_for_final_conclusion=true`.
+- `record_list` is only for sample inspection after the aggregate result is understood.
+- `record_get` is only for single-record detail verification, logs, references, images, or readable attachments. Read images from `media_assets.items[].local_path`; read documents/tables from `file_assets.items[].local_path` and `extraction.text_path`.
+- `record_export_direct` is only for explicit export/download/Excel requests.
+- `chart_get` / QingBI is only for user-provided report URLs or chart ids.
+
+## Tool Selection
+
+| Need | Tool |
+|---|---|
+| Batch analysis, statistics, comparison, report | `record access -> Python` |
+| Browse a few example rows | `record_list` |
+| Inspect one record, logs, references, images, attachments | `record_get` |
+| User asks to export/download/Excel | `record_export_direct` |
+| User gives report URL or chart id | `chart_get` |
+| Todo/workflow task actions | `reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md` |
+
+## Standard Procedure
+
+1. Run `app get` and choose a table-style `view_id` from `accessible_views`.
+2. Run `record schema browse --app-key APP_KEY --view-id VIEW_ID`.
+3. Decide metric intent before fetching data: `count`, `sum`, `avg`, `distinct_count`, ratio, ranking, trend, or comparison.
+4. Choose minimal `record_access.columns`, plus `where` and `order_by`.
+5. Run `qingflow record access`.
+6. Read all returned CSV files in Python; use `fields[]` only when field-id metadata is needed.
+7. Run field-quality checks for all candidate dimensions.
+8. Compute results in pandas.
+9. Report numbers with scope, field choices, field-quality caveats, completeness, and business assumptions.
+
+Use field-id DSLs only:
+
+```json
+{
+  "app_key": "APP_KEY",
+  "view_id": "system:all",
+  "columns": [{ "field_id": 2 }, { "field_id": 18 }],
+  "where": [{ "field_id": 2, "op": "between", "value": ["2026-05-01", "2026-05-31"] }],
+  "order_by": [{ "field_id": 2, "direction": "asc" }]
+}
+```
+
+Never pass `page`, `page_size`, `limit`, `max_rows`, `timeout`, or `profile` to `record_access`.
+
+CSV columns are already readable and field-id anchored, for example `项目状态__field_343283094`. Do not expect separate `schema.json` or `README.md` files.
+
+For CLI use, write JSON argument files instead of embedding large JSON in shell text:
+
+```bash
+qingflow record access \
+  --app-key APP_KEY \
+  --view-id system:all \
+  --columns-file columns.json \
+  --where-file where.json \
+  --order-by-file order_by.json \
+  --json
+```
+
+## Status Handling
+
+Read `record_access.status` before reading files or writing conclusions.
+
+- `status=success`, `complete=true`, `safe_for_final_conclusion=true`: full-scope answer is allowed.
+- `status=needs_scope`: no CSV was written. Ask for a time/business range or retry with a user-provided period using `scope.suggested_time_fields`.
+- `status=partial`: read returned files only as a subset. Do not give a full-population conclusion.
+- `complete=false`, `truncated=true`, or `safe_for_final_conclusion=false`: answer as `初步观察` or ask for a narrower scope.
+
+## Business Context
+
+If the question mentions department, team, region, owner group, stage, product line, or a named business scope, check whether aliases or child scopes matter before concluding. Use explicit mappings provided by the user or local context; otherwise ask a short clarification.
+
+Example: if `烈焰组` and `飓风组` are sub-departments of `北斗部门`, apply that mapping in Python and state it in the answer.
+
+## Output Shape
+
+Default to:
+
+1. `结论`
+2. `关键数据`
+3. `口径与范围`
+4. `可信度 / 限制`
+
+Concrete numbers are mandatory. Ratios require both numerator and denominator. Trends require a time field and explicit date range. Rankings must come from a sorted pandas result.
+If a requested dimension has poor quality, say so explicitly and provide the nearest reliable fallback dimension, for example platform or product instead of a mostly empty module field.
+
+## References
+
+Load only what is needed:
+
+- Data access status machine: [references/data-access-playbook.md](./data-access-playbook.md)
+- Python/pandas templates: [references/pandas-recipes.md](./pandas-recipes.md)
+- Analysis patterns: [references/analysis-patterns.md](./analysis-patterns.md)
+- Business mappings and scope: [references/business-context.md](./business-context.md)
+- Confidence and final wording: [references/confidence-reporting.md](./confidence-reporting.md)
+- Common mistakes: [references/analysis-gotchas.md](./analysis-gotchas.md)
+- Report templates: [references/report-format.md](./report-format.md)
+
+## Feedback Escalation
+
+If the desired analysis cannot be completed because of missing capability, unsupported data shape, or an awkward workflow after reasonable attempts, summarize the exact gap and ask whether to submit product feedback. Only after explicit user confirmation, call `feedback_submit`.

package/skills/qingflow-cli/reference/record/analysis/analysis-gotchas.md

@@ -0,0 +1,91 @@
+# Analysis Gotchas
+
+## Do Not Skip Schema
+
+Correct path:
+
+1. `app_get`
+2. `record_browse_schema_get`
+3. `record_access`
+4. Python
+
+`record_browse_schema_get` returns readable fields for the selected view. Missing fields are permission or view-scope boundaries, not invitations to guess hidden ids.
+
+## Do Not Use Export For Analysis
+
+Export tools are for user-requested files. Analysis uses `record_access` because it returns structured completeness and compact field metadata.
+
+## Do Not Treat `record_list` As Full Data
+
+`record_list` is sample/browse only. It can be capped and should not justify:
+
+- average
+- share
+- ranking
+- trend
+- regional distribution
+- "all data" insights
+
+## Do Not Control Paging
+
+`record_access` owns paging internally.
+
+Do not invent:
+
+- `page`
+- `page_size`
+- `limit`
+- `requested_pages`
+- `scan_max_pages`
+- `max_rows`
+- `timeout`
+
+## Do Not Print Raw CSV
+
+Read CSV files with pandas. Summarize computed results, not raw rows.
+
+## Do Not Rename Source Files
+
+CSV columns are directly readable and field-id anchored: `record_id`, `<字段标题>__field_<id>`. Use those columns directly in pandas.
+
+## Do Not Trust Sparse Dimensions
+
+Before final grouping, run a field-quality profile. If the selected field is mostly blank, say so and downgrade the claim.
+
+Rules of thumb:
+
+- Overall blank rate above 40%: not a primary conclusion dimension.
+- Any compared period blank rate above 80%: do not use that field for period comparison.
+- A sparse field can support only `已填写样本观察`.
+
+If the user asks for a semantic field such as `板块`, test nearby candidates like product, platform, module, stage, source, owner, or department before concluding.
+
+## Do Not Hide Incomplete Access
+
+If `needs_scope`, no CSV exists. Ask for a time/business scope.
+
+If `partial`, use only subset wording and avoid full-population claims.
+
+If field meaning is ambiguous, ask the user to confirm from a short list.
+
+## Do Not Guess Metrics
+
+Before fetching data, decide whether the request needs count, sum, average, distinct count, ratio, ranking, trend, or comparison.
+
+## Do Not Call A Ratio Without Denominator
+
+For penetration, conversion, or share:
+
+1. define numerator
+2. define denominator
+3. query compatible source data
+4. compute in Python
+5. report numerator and denominator
+
+## Normalize Relative Dates
+
+Convert relative phrases into exact ranges before `record_access`.
+
+- `今年5月` -> exact May 1 to May 31 in the current year
+- `去年同期` -> same date range in previous year
+- `最近30天` -> exact rolling start/end dates