@josephyan/qingflow-cli 1.1.4 → 1.1.6

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_ADMIN_CHEATSHEET.md → core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md}

@@ -1,7 +1,7 @@
 # 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)**（任选，默认执行技能不必打开）。
+> **与普通成员对照**：权限较窄时请用 **[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)**（任选，默认执行技能不必打开）。
 
 ---
 
@@ -43,7 +43,7 @@
 
 ## 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`**。
+与 **[成员速查](./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` 等。最终统计结论、分析报告、趋势/排名/比例/分布统一使用 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**。
 
 ---
 
@@ -87,7 +87,7 @@
 
 ## 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_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。
 
 ---
 

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md → core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md}

@@ -1,8 +1,8 @@
 # Qingflow CLI：获取数据工作流（应用记录）
 
 > **用途**：使用当前 CLI 会话，从「选定应用」到「读懂列含义 + 样本/模糊定位 / 单条详情」的**推荐闭环**；下表 **左列**可与常见 **编排/内部接口**命名对照，**右列**仅为本 CLI 命令。
-> **新版口径**：`record_list` 不是批量分析入口，而是样本浏览和模糊定位入口；`record_get` 是前端详情页首屏上下文入口；全量日志用 `record logs`；分析取数统一转 `qingflow-record-analysis` 的 `record_access -> Python/pandas`。
-> **关联**：权限、`view_id` 选取雷区、成员最短路径速查见 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**字段 `kind` / 数据类型**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录**见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；**更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**；主技能规则见 **[../SKILL.md](../SKILL.md)**。
+> **新版口径**：`record_list` 不是批量分析入口，而是样本浏览和模糊定位入口；`record_get` 是前端详情页首屏上下文入口；全量日志用 `record logs`；分析取数统一转 [record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`。
+> **关联**：权限、`view_id` 选取雷区、成员最短路径速查见 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**字段 `kind` / 数据类型**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录**见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；**更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；最终统计结论统一使用 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**；主技能规则见 **[../SKILL.md](../../SKILL.md)**。
 
 ---
 
@@ -30,10 +30,10 @@ app get（解析 accessible_views，选定 VIEW_ID）
   → （可选）record logs（需要完整审计日志时再拉全量日志 JSONL）
 ```
 
-- **仅当你只需要「快速确认有无数据」**时，可以省略 `schema browse`，直接 `app get` → `record list`（与成员速查表「最短路径」一致）。  
-- **当你需要稳定映射列名、写过滤条件或对接自动化**时，应按上表**显式**走 `schema browse`，避免对着 `list` 里中文列名猜字段定义。  
+- **仅当你只需要「快速确认有无数据」**时，可以省略 `schema browse`，直接 `app get` → `record list`（与成员速查表「最短路径」一致）。
+- **当你需要稳定映射列名、写过滤条件或对接自动化**时，应按上表**显式**走 `schema browse`，避免对着 `list` 里中文列名猜字段定义。
 - **当用户只给出模糊信息定位单条数据**时，走 `record schema browse` 确认可搜索字段，再用 `record list --query ... --query-field ...` 返回候选；只有候选明确后才 `record get`。
-- **需要分组/聚合统计、最终统计结论、分析报告、趋势/排名/比例/分布**时，必须切换到 **`qingflow-record-analysis`**，按 `app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python/pandas -> final answer` 执行。
+- **需要分组/聚合统计、最终统计结论、分析报告、趋势/排名/比例/分布**时，必须按 **[record/analysis](../record/analysis/README.md)** 执行 `app get -> record schema browse -> record access -> Python/pandas -> final answer`。
 
 ---
 
@@ -122,7 +122,7 @@ qingflow --json record logs \
 
 ## `view_id` 选取（成员侧必读摘要）
 
-- **`system:all` 等业务系统视图**：实跑可用于 `schema browse` + `record list`（具体以租户配置为准）。显式传入的 `view_id` 必须按前端当前视图忠实执行；`system:all` 报 40002 / 40027 / 404 / 500 时，不要自动换成 `system:initiated`、`system:todo` 等其它系统视图，除非用户或前端 URL / `app get.accessible_views` 重新指定了那个视图。  
+- **`system:all` 等业务系统视图**：实跑可用于 `schema browse` + `record list`（具体以租户配置为准）。显式传入的 `view_id` 必须按前端当前视图忠实执行；`system:all` 报 40002 / 40027 / 404 / 500 时，不要自动换成 `system:initiated`、`system:todo` 等其它系统视图，除非用户或前端 URL / `app get.accessible_views` 重新指定了那个视图。
 - **`CUSTOM_VIEW_LIST_UNAVAILABLE`**：只说明 `app get` 没能列出 custom view；若已有 `system:*` 可用，不要把它当作应用或记录读取失败。
 - **`custom:` 后仅数字**（如 `custom:1`）：成员侧常见 **`schema browse` / `list` / `access` 均 40038**，应**跳过**，改选 **`custom:` 带字母后缀**或其它可用视图（详见成员速查表「先有通路、再要有数据」）。
 - **待办 / 已办 / 抄送「任务箱」**：不要用旧文档里的 `system:todo` 等视图充当任务中心；应使用 **`task list --task-box …`**（见主技能 **待办 SOP**）。

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_EXPLORATION_REPORT.md → core/QINGFLOW_CLI_EXPLORATION_REPORT.md}

@@ -1,6 +1,6 @@
 # Qingflow CLI 当前版本审计备忘
 
-> 本文件只记录当前 CLI 与 skill 主路径容易混淆的事实。它不是执行 SOP；具体任务仍按 [SKILL.md](../SKILL.md) 与对应专题 reference 执行。CLI 升级后优先重新跑 `qingflow ... --help` 复核。
+> 本文件只记录当前 CLI 与 skill 主路径容易混淆的事实。它不是执行 SOP；具体任务仍按 [SKILL.md](../../SKILL.md) 与对应专题 reference 执行。CLI 升级后优先重新跑 `qingflow ... --help` 复核。
 
 ---
 
@@ -10,7 +10,7 @@
 - `builder` 与 `build` 等价；默认写法仍推荐 `builder`。
 - `record schema`：公开主路径为 `browse`、`insert`、`update`、`import`、`code-block`；`applicant` 仅为兼容保留入口，不作为推荐链路。
 - `record` 公开执行入口：`list`、`access`、`get`、`logs`、`insert`、`update`、`delete`、`code-block-run`。
-- 最终统计结论统一由 `qingflow-record-analysis` 走 `record_access -> Python/pandas`，不要寻找或使用其它聚合捷径。
+- 最终统计结论统一按 [record/analysis](../record/analysis/README.md) 走 `record access -> Python/pandas`，不要寻找或使用其它聚合捷径。
 
 ---
 

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_FIELD_DATA_TYPES.md → core/QINGFLOW_CLI_FIELD_DATA_TYPES.md}

@@ -1,8 +1,8 @@
 # Qingflow CLI：字段数据类型（Schema / 列表 / 写入）
 
 > **用途**：说明 **`record schema …`** 的 **`fields[]`**、**`record list` / `record get` / `record access`** 行内值、以及 **insert/update 写入 payload** 的常见对应关系；并单独说明 **选项联动、关联记录、引用填充、公式/系统题、AI 与受限类型** 等在 CLI 下的表现与处置。
-> **依据**：当前 CLI 在 **`--json`** 下会对 **schema** 响应做 **裁剪**：通常只保留本节列出的键；**`kind`** 由内部写入类别归并而来（见下表）。**`que_type` 等若未出现在输出中**，以 **`kind` + 实跑预检** 为准。  
-> **关联**：写入值细节与成员/部门见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** **`app_schema_apply` 的 `type`（与本文 `kind` 命名体系不同）**见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**；主技能 **[../SKILL.md](../SKILL.md)**。
+> **依据**：当前 CLI 在 **`--json`** 下会对 **schema** 响应做 **裁剪**：通常只保留本节列出的键；**`kind`** 由内部写入类别归并而来（见下表）。**`que_type` 等若未出现在输出中**，以 **`kind` + 实跑预检** 为准。
+> **关联**：写入值细节与成员/部门见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** **`app_schema_apply` 的 `type`（与本文 `kind` 命名体系不同）**见 **[30-schema-fields.md](../builder/30-schema-fields.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
 
 ---
 
@@ -36,14 +36,14 @@
 | **`department`** | `department_list` | 部门名或 id 形态 | 优先自然语言字符串，如 `"直销部"`；`needs_confirmation` 时按候选改显式对象/id |
 | **`relation`** | `relation_record`（**§3.2**） | 常为关联展示字段或 `apply_id` 相关信息 | **`apply_id`**、可解析对象或自然语言；多匹配会返回 `needs_confirmation`，需选候选后重试 |
 | **`attachment`** | `attachment_list` | URL、文件名或结构化附件对象 | **`{"value"或"url", "name"?}`**；常需 **`builder file upload-local` 先上传** |
-| **`address`** | `address_parts`（**对外 `kind` 常被映射进 `scalar`**，以实跑为准） | 对象或分段地址 | **省/市/区/detail 对象** 或 **有序片段数组**（见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**） |
+| **`address`** | `address_parts`（**对外 `kind` 常被映射进 `scalar`**，以实跑为准） | 对象或分段地址 | **省/市/区/detail 对象** 或 **有序片段数组**（见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**） |
 | **`subtable`** | `subtable_rows` | **行数组**；行内键为子列 title | **行数组**；行内 **`title → 值`**；更新行可带 **`row_id`/`__row_id__`**（见实现） |
 | **`unsupported`** | `unsupported_direct_write`（**§3.4、§3.5**） | 只读/仅流程内填写等 | **勿直接写入**；预检会 `UNSUPPORTED_WRITE` / 类似 blockers |
 
 说明：
 
-- **单选/多选**在对外 `kind` 上 **同是 `select`**；以 **`options` 是否存在 + 业务语义** 区分；多选写入用 **数组**。  
-- **`scalar`** 是 **桶类型**：文本、数字、金额、日期、布尔等在对外展示上常同为 `scalar`，**具体校验以后端与预检为准**。  
+- **单选/多选**在对外 `kind` 上 **同是 `select`**；以 **`options` 是否存在 + 业务语义** 区分；多选写入用 **数组**。
+- **`scalar`** 是 **桶类型**：文本、数字、金额、日期、布尔等在对外展示上常同为 `scalar`，**具体校验以后端与预检为准**。
 - **`field_id=0`** 等系统列可能为 **`system`+只读**；不要写入 insert/update payload（见创建文档「系统维护字段」）。
 
 ---
@@ -60,10 +60,10 @@
 | **多选** | 内部题类型常为 **12、15**；对外仍为 **`kind=select`**（与单选 **同名 kind**） | **列表/详情**：常为 **字符串数组** 或可解析的多值结构。写入：传 **JSON 数组**（每个元素对应一个选项值） |
 | **区分单多选** | 精简 schema **仅有 `kind`+`options`** | 以 **表单配置 / 同一 `title` 在别处的表现 / 写入预检** 为准；**唯一写入层面**的硬规则是：**多选必须按数组传** |
 
-**选项联动（控制显隐、必填等）**  
+**选项联动（控制显隐、必填等）**
 
-- 实现上来自 **题目关系 + 选项上的联动题 id**（如其它题因当前选项而被激活）。  
-- **`record schema browse` 的 `--json`**：精简 `fields[]` 可能不展示完整 `linkage` / 联动明细；新建记录以 `qingflow-record-insert` 的 `record_insert_schema_get`（CLI `record schema insert`）为准，不要用兼容保留的 applicant schema 入口替代。
+- 实现上来自 **题目关系 + 选项上的联动题 id**（如其它题因当前选项而被激活）。
+- **`record schema browse` 的 `--json`**：精简 `fields[]` 可能不展示完整 `linkage` / 联动明细；新建记录以 [record/insert](../record/insert/README.md) 的 `record schema insert` 为准，不要用兼容保留的 applicant schema 入口替代。
 - **写入时**：若更新返回提示 **上游未选、联动未激活、字段尚未显示**，应 **先写或改 payload 里处于上游的选项（或其它驱动题）**，再写下游；必要时用 **`record schema update --record-id …`** 诊断当前记录下 **`required_fields` / `optional_fields` / `payload_template`**。
 
 ### 3.2 关联字段（关联记录）
@@ -119,9 +119,9 @@
 ## 5. 读者操作建议
 
 1. **按场景取上下文**：只读/定位视图列用 `record schema browse --view-id …`；新建用 `record schema insert --app-key …`；更新用 `record get --record-id …` 先读当前记录详情，再用 `record update` 写入；`record schema update --record-id …` 只在失败、字段歧义或显式诊断时使用。
-2. **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布必须走 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**。
-3. **看 `kind` + `options` / `row_fields` / `target_app_key`**，并对照 **§3 特殊字段** 判断是否存在联动、引用或只读带出。  
-4. **选项联动 / 引用带出**：先写 **驱动题**，再写 **被带出的题**；只读带出列 **不要强写**。  
+2. **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布必须走 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**。
+3. **看 `kind` + `options` / `row_fields` / `target_app_key`**，并对照 **§3 特殊字段** 判断是否存在联动、引用或只读带出。
+4. **选项联动 / 引用带出**：先写 **驱动题**，再写 **被带出的题**；只读带出列 **不要强写**。
 5. **写入前缩小 payload**；insert 默认用 `record insert --items-file`，单条也是 `items` 数组一行。根据 **`status` / `blockers` / `field_errors` / `failed_fields` / `created_record_ids`** 迭代（`--json` 在 stdout）。
 
 ---

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_MEMBER_CHEATSHEET.md → core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md}

@@ -1,14 +1,14 @@
 # Qingflow CLI 普通成员命令速查表
 
 > **适用对象**：当前会话为 **普通/基本成员**（`permission_level` 非租户/应用管理员、`import_capability` 常为无导入权等）。Wingent Momo runtime 下不要先跑 `auth whoami`；只有业务失败、账号不确定或排障时才核对身份。
-> **与主技能关系**：请以 **[SKILL.md](../SKILL.md)**（本目录上一级）的规则与命令速查表为准。**本表**：成员侧最短读数与高概率通路；**租户/管理员向差异**请参阅同目录 **[QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+> **与主技能关系**：请以 **[SKILL.md](../../SKILL.md)**（本目录上一级）的规则与命令速查表为准。**本表**：成员侧最短读数与高概率通路；**租户/管理员向差异**请参阅同目录 **[QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
 > **可选补充**：同一目录 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** 收录 **全体角色通用**的子命令逐项模板（与本文分工：本文偏「成员能跑通的策略」，ONE_SHOT 偏「参数逐项闭合示例」）。
 
 > **实证**：以下结论以会话内 `qingflow …` 为准；换账号/环境请以 `qingflow … -h` 与必要的身份核对结果为准。
 
 **统一习惯**
 
-- **只读拉取表单记录的最短链路**：见本节 **「最短路径：普通成员只读记录数据」**（可省略 `schema browse`）。**需先拉浏览视图表结构**时见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**；**字段 `kind` / 数据形态**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录默认批量 JSON 链路**请用 **`qingflow-record-insert`**（`record_insert_schema_get -> record_insert(items)`，CLI 为 `record insert --items-file`，成员/部门/关联优先自然语言）；**浏览视图下更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
+- **只读拉取表单记录的最短链路**：见本节 **「最短路径：普通成员只读记录数据」**（可省略 `schema browse`）。**需先拉浏览视图表结构**时见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；最终统计结论统一使用 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**；**字段 `kind` / 数据形态**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录默认批量 JSON 链路**见 **[record/insert](../record/insert/README.md)**（CLI 为 `record insert --items-file`，成员/部门/关联优先自然语言）；**浏览视图下更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
 - 避免无必要地先绕 `workspace`、`view get`。
 - 加 `--json`，便于区分 **CONFIG_ERROR**（少参）与 **backend**（权限/业务）。
 - `app get` / `portal list` 等业务体常在 `**{ "data": { ... } }`** 里：取 `accessible_views`、`items` 前先 unwrap `data`。
@@ -145,7 +145,7 @@ qingflow --json record list \
 
 ## 5. 扩展链路（含 workspace / schema）
 
-若你还要 **核对当前工作区** 或 **先看 browse 字段**，在 **§「最短路径」** 之外可增加（顺序仍建议 **先最短再扩展**）。注意：最终统计结论、分析报告、趋势/排名/比例/分布必须使用 `qingflow-record-analysis` 的 `record_access -> Python/pandas`：
+若你还要 **核对当前工作区** 或 **先看 browse 字段**，在 **§「最短路径」** 之外可增加（顺序仍建议 **先最短再扩展**）。注意：最终统计结论、分析报告、趋势/排名/比例/分布必须使用 [record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`：
 
 ```bash
 qingflow --json auth whoami  # 仅业务失败、账号不确定或需要写清当前租户上下文时
@@ -170,7 +170,7 @@ qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>
 
 | 文档                                                                               | 用途                                                                             |
 | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| [SKILL.md](../SKILL.md)                                                          | **主文档**：认证、落盘规则、正文「命令速查」与高危操作节选。                                                                     |
+| [SKILL.md](../../SKILL.md)                                                          | **主文档**：认证、落盘规则、正文「命令速查」与高危操作节选。                                                                     |
 | [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)        | **导入 / `builder role search` 等**管理向差异与成员侧失败对照。                                                        |
 | [QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)     | 可选：全角色通用；各节「一次可复制」命令块与附录必败清单。                                                                     |
 

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md → core/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md}

@@ -2,7 +2,7 @@
 
 > **面向普通/基本成员账号时**：更易踩 **应用搜索/import/角色检索** 等权限类失败，请先读 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**（策略与最短读数路径）；**管理向差异**参阅 **[QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
 
-> **本文档目的**：按**场景**给出**形态正确、参数闭合**时的命令模板，便于复制后替换占位符即跑，减少「缺参 / 引号 / 根级选项」类返工。  
+> **本文档目的**：按**场景**给出**形态正确、参数闭合**时的命令模板，便于复制后替换占位符即跑，减少「缺参 / 引号 / 根级选项」类返工。
 > **不是**「任何账号、任何租户、任何时刻都 100% HTTP 200」——若遇 `59004`（流币/AI 配额）、401、或目标资源不存在，仍可能失败；那种情况属于**环境与权限**，不是本表要解决的「命令写对一次成」问题。
 
 **统一建议**
@@ -73,11 +73,11 @@
 
 | 场景                      | 一次成功写法                                                                                    | 必填/注意                                                         |
 | ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| Insert schema              | `qingflow --json record schema insert --app-key <APP_KEY>`                             | 新建记录默认走 `qingflow-record-insert`；CLI 用 insert-ready schema + `record insert --items-file`。 |
+| Insert schema              | `qingflow --json record schema insert --app-key <APP_KEY>`                             | 新建记录默认走 [record/insert](../record/insert/README.md)；CLI 用 insert-ready schema + `record insert --items-file`。 |
 | Import / code-block schema | `qingflow --json record schema import --app-key <APP_KEY>` / `qingflow --json record schema code-block --app-key <APP_KEY>` | 仅在导入或代码块任务明确需要时使用。 |
 | Schema：browse（浏览态字段）    | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>`            | **必须 `--view-id`**；不要用引号包住 `record schema browse` 整段。         |
 | 列表/候选定位（运行时强校验）           | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>` | **必须 `--view-id`**；默认最多返回 10 条，适合样本/模糊定位；可加 `--query` / `--query-field`。 |
-| 分析取数                    | `qingflow --json record access --app-key <APP_KEY> --view-id <VIEW_ID> --columns-file columns.json --where-file where.json` | 最终统计结论统一使用 `qingflow-record-analysis` 的 `record_access -> Python/pandas`。 |
+| 分析取数                    | `qingflow --json record access --app-key <APP_KEY> --view-id <VIEW_ID> --columns-file columns.json --where-file where.json` | 最终统计结论统一使用 [record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`。 |
 | 单条读取                    | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID>`                  | **必须** `--record-id`；返回前端详情页首屏上下文、引用、图片/文件资产。 |
 | 全量记录日志                | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 仅在需要完整审计/日志历史时使用；全量数据日志和流程日志写本地 JSONL。 |
 
@@ -156,4 +156,4 @@
 
 ---
 
-*文档生成说明：与 **[../SKILL.md](../SKILL.md)**、[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) 对齐；若 CLI 版本升级，请以 `qingflow … -h` 为准做小步修订。*
+*文档生成说明：与 **[../SKILL.md](../../SKILL.md)**、[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) 对齐；若 CLI 版本升级，请以 `qingflow … -h` 为准做小步修订。*

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md → record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md}

@@ -2,7 +2,7 @@
 
 ---
 
-**创建记录 SOP 见 skill：`qingflow-record-insert`。**
+**创建记录详细规则见**：[record/insert/README.md](./insert/README.md)。
 
 CLI 对应主路径：
 
@@ -11,9 +11,9 @@ qingflow --json record schema insert --app-key <APP_KEY> > tmp/qingflow_insert_s
 qingflow --json record insert --app-key <APP_KEY> --items-file tmp/records.json > tmp/qingflow_insert_result.json
 ```
 
-不要用 `record schema applicant` 代替 `record_insert_schema_get` 的主路径；新建记录需要 insert-ready schema 里的 `required_fields`、`optional_fields`、`payload_template`、`format_hint`、`expected_format`、`example_value` 和字段级 `options`。
+不要用 `record schema applicant` 代替 `record schema insert` 的主路径；新建记录需要 insert-ready schema 里的 `required_fields`、`optional_fields`、`payload_template`、`format_hint`、`expected_format`、`example_value` 和字段级 `options`。
 
-成员、部门、关联记录、选项、附件等特殊字段按 `qingflow-record-insert` 的 **Special Field Write Cheatsheet** 写：先读 insert schema；部门/成员不能自造候选；选项值必须来自 schema `options` 的文本或 id；关联记录批量写入优先 `record_id`，自然名称只在唯一匹配时使用；附件先上传再写返回值。
+成员、部门、关联记录、选项、附件等特殊字段按 [record/insert/README.md](./insert/README.md) 写：先读 insert schema；部门/成员不能自造候选；选项值必须来自 schema `options` 的文本或 id；关联记录批量写入优先 `record_id`，自然名称只在唯一匹配时使用；附件先上传再写返回值。
 
 追加样例数据时也必须 schema-first：按 `required_fields` 补齐必填；按 `expected_format/example_value` 选择数值、金额、日期等格式；按 `options` 生成选项值。不要按业务常识自造“正常/已完成/高优先级”等 schema 里不存在的选项。比例、完成率、评分、百分比等字段也按 schema 示例写；如果字段被建成金额/整数类而不接受小数，不要强塞 decimal，改用符合 schema 的整数值，或回到 builder 阶段把字段建模为 `number`。
 

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/{QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md → record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md}

@@ -111,8 +111,8 @@ qingflow --json import repair \
 ```
 
 - **未加** `--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`** 可重复；允许集合（实现 **`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`**。
 
@@ -172,5 +172,5 @@ qingflow --json import status --app-key "<APP_KEY>" \
 
 ## 7. 交叉引用
 
-- 主技能 [SKILL.md](../SKILL.md)：**落盘**、导入类权限码 **`IMPORT_*`** 提示。
-- [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)：管理侧与 **`IMPORT_*`** 失败排查。
+- 主技能 [SKILL.md](../../SKILL.md)：**落盘**、导入类权限码 **`IMPORT_*`** 提示。
+- [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](../core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)：管理侧与 **`IMPORT_*`** 失败排查。

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md → record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md}

@@ -1,7 +1,7 @@
 # Qingflow CLI：更新记录工作流（详情后直接写入）
 
 > **用途**：使用当前 CLI 会话读取目标记录详情后，用 **`record update`** 直接提交差异字段。主链路是 `record get -> record update`；字段范围不清、候选歧义或失败排查时，才追加 **`record schema update`**。
-> **关联**：只读列表/详情见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**字段 `kind` 与写入值总表**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**；**成员 / 部门等** 的细颗粒写入见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；主技能 **[../SKILL.md](../SKILL.md)**。
+> **关联**：只读列表/详情见 **[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)**。
 
 ---
 
@@ -25,8 +25,8 @@ record get（得到 RECORD_ID、当前值、fields[].title/field_id/kind；已
   → 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` 已经会返回单条详情所需字段信息。  
+**何时先 `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 被拒绝，不一定表示用户对记录完全无编辑能力。
@@ -111,10 +111,10 @@ qingflow --json record schema update \
 
 ## 批量模式（`--items-file`）
 
-- **不可**与 **`--record-id` / `--fields-file`** 同时使用。  
+- **不可**与 **`--record-id` / `--fields-file`** 同时使用。
 - `items` 为 **数组**，每项为对象，至少包含：
   - **`record_id`**：正整数（字符串或可解析数字均可，以 CLI 校验为准）
-  - **`fields`**：与单条相同的「标题 → 值」map  
+  - **`fields`**：与单条相同的「标题 → 值」map
 
 示例：
 
@@ -139,8 +139,8 @@ qingflow --json record schema update \
 
 ## 安全与落盘
 
-- **`record update` 为写操作**；仅在授权环境、**必要时**对测试应用演练。  
-- **`list` / `get` / `schema browse` / `schema update` / 更新结果** 体大量时按主技能 **落盘规则** 重定向。  
+- **`record update` 为写操作**；仅在授权环境、**必要时**对测试应用演练。
+- **`list` / `get` / `schema browse` / `schema update` / 更新结果** 体大量时按主技能 **落盘规则** 重定向。
 - 主技能 **危险操作** 中对 `record update --dry-run`（批量）的说明仍适用。
 
 ---

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