@josephyan/qingflow-cli 1.1.3 → 1.1.5

package/skills/qingflow-cli/SKILL.md

@@ -2,17 +2,18 @@
 name: qingflow-cli
 description: |
   【强制】在执行或编排任何 qingflow CLI 命令前必须优先加载本 Skill。
-  指导安装、执行上下文失败恢复、查询与写入；规定 task/record/import/builder 查询落盘；覆盖普通成员读数、字段 kind 与数据形态、任务上下文、批量导入、record access/list/get/insert/update 与管理端边界。
-  Builder SOP 对应「搭建应用与流程」「创建字段与系统列」「改布局视图门户报表」「按钮与关联资源」「发布与校验」等搭建/创建/系统化配置需求，与仅用 record 读写不同；明细见「关联文件」表与文末命令索引。
+  Qingflow CLI 包以本 Skill 作为 CLI 主入口；record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。
+  指导安装、执行上下文失败恢复、查询与写入；规定 task/record/import/builder 查询落盘；覆盖普通成员读数、字段 kind 与数据形态、任务上下文、批量导入、record access/list/get/insert/update/delete 与管理端边界。
+  Builder SOP 按智能体任务路径组织：完整系统、单应用、字段、布局、视图、报表、门户、按钮/关联资源、流程、发布校验；更新动作并入对应资源文档，批量读/批量写/局部改作为资源文档内的写法变体；明细见「关联文件」表与文末命令索引。
 ---
 
 # Qingflow CLI 使用技能
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.26.1`（入口文档版本；CLI 包版本用 `qingflow --version`；需要定位版本漂移时用 `qingflow --json version` 读取 `version/package/command_path/executable_path/package_root/skill_version`）。
 
-**硬约束（必读）**：正文各节与文末「命令速查」中的命令**只作子命令形态索引**，不覆盖 JSON 结构、`--*-file` 键名、枚举全集、执行顺序与排障细节。凡工作**偏复杂**（多步串联、大块 payload、导入全链、**Builder 搭建向**（应用/schema/流程/布局/视图/门户/报表/按钮/关联资源的配置与发布、系统列与字段 `type`）、契约型 `apply`、按 schema 组织写入 payload、任务下钻与 `task action` 等），或你判断当前任务与「关联文件」里某篇所描述的内容**需求一致、场景相同或大体同类**，都应**先 Read 对应 `reference/*.md`**，再结合 `qingflow … --help` 与 **[EXPLORATION_REPORT](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。**禁止**仅凭索引、习惯或类比去补参数、臆造字段名或推断服务端行为。**最终统计结论、分析报告、趋势/排名/比例/分布等数据分析，必须转交 `qingflow-record-analysis`，统一走 `record_access -> Python/pandas`。**
+**硬约束（必读）**：正文各节与文末「命令速查」中的命令**只作子命令形态索引**，不覆盖 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-tech/qingflow-cli`（查版本优先用 `qingflow --version`；需要 JSON 时用 `qingflow --json version`）。**搭建/创建/系统配置**：先区分 **完整系统/应用包** 与 **单应用**。完整系统主链路必须走 `builder package apply -> builder schema apply --apps-file`，并用 `apps[].client_key + relation.target_app_ref` 处理同批跨应用关联；单应用才走 `builder schema apply --app-key` 或 `--package-id --app-name --create-if-missing`。完整系统 schema apply 超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时，下一步固定是 **`readback_before_retry`**（`package get` / `app resolve` / `app get fields`），禁止直接拆成单应用重建、用 V2/测试/随机后缀绕过重名或重放整批创建；随后再按 **[APP_DELIVERY](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)** → **[VIEWS](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)** / **[PORTAL](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)** / **[CHARTS](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)** 选读。仅成员读数速通仍可先打开 **[MEMBER_CHEATSHEET](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**。
+> **CLI**：当前验证包为 `@qingflow-tech/qingflow-cli`（查版本优先用 `qingflow --version`；需要 JSON 时用 `qingflow --json version`）。**复杂任务先读 [reference/00-INDEX.md](./reference/00-INDEX.md)**。**搭建/创建/系统配置**：先区分 **完整系统/应用包** 与 **单应用**。完整系统主链路必须走 `builder package apply -> builder schema apply --apps-file`，并用 `apps[].client_key + relation.target_app_ref` 处理同批跨应用关联；单应用才走 `builder schema apply --app-key` 或 `--package-id --app-name --create-if-missing`。完整系统 schema apply 超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时，下一步固定是 **`readback_before_retry`**（`package get` / `app resolve` / `app get fields`），禁止直接拆成单应用重建、用 V2/测试/随机后缀绕过重名或重放整批创建；随后按 **[builder/README.md](./reference/builder/README.md)** 选择单应用、完整系统或具体资源文档。仅成员读数速通仍可先打开 **[MEMBER_CHEATSHEET](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**。
 
 ## 关联文件
 
@@ -20,22 +21,35 @@ description: |
 | 文件                                                                                               | 说明                                                                                                                                                                                                                                                                                    |
 | ------------------------------------------------------------------------------------------------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `manifest.yaml`                                                                                  | 技能清单                                                                                                                                                                                                                                                                                  |
-| [reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)     | **普通成员**主线：最短路径、`view_id`、与管理命令的差异预期                                                                                                                                                                                                                                                  |
-| [reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md)       | **字段数据类型**：`record schema …` 的 `fields[]`（`field_id`、`title`、`kind`、`options`…）；`record list/get/access` 与写入 payload 的形态对照                                                                                                                                                                    |
-| [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **应用记录获取数据**：`app get`（`accessible_views`）→ `record schema browse` → `record list(query)` 模糊定位 / `record get` 详情页首屏上下文 / `record logs` 全量日志；分析取数转 `record_access`                                                                                                                                                                        |
-| [reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md](./reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md) | **任务(待办已办)上下文 SOP**：`task_list` → `task_get` → `task_workflow_log_get`（`task log`）→ `task_associated_report_detail_get`（`task report`）→ `task_action_execute`（`task action`）；与 MCP 命名对照                                                                                               |
-| [reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) | **批量导入 SOP**：`app_get`（**`import_capability`**）→ `record_import_template_get` → `record_import_verify` →（可选）`record_import_repair_local` → `record_import_start` → `record_import_status_get`；CLI `import` / `record schema import`                                                   |
-| [reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) | **搭建侧·应用交付 SOP**（**创建/改造应用底色**：解析包与应用、读写字段布局流程、一键改 schema·layout·flow、按钮与关联资源、**`publish verify`**）：`app_get` 应用地图 → `app_resolve` → `app_read_*` → **`schema`/`layout`/`flow apply`** / **`app_custom_buttons_apply`** / **`app_associated_resources_apply`**；字段 JSON 支持 **`as_data_title` / `as_data_cover`** |
-| [reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md) | **搭建侧·工作区图标**：`builder icon catalog`；新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color`，CLI 只校验候选，不按业务名自动映射 |
-| [reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md) | **搭建侧·业务视图 SOP**：`app_get` / `app get fields|views` → **`builder views apply`**；区分 `filters` 与 **`query_conditions`**；关联视图/报表走 **`app_associated_resources_apply`**，按钮走 **`app_custom_buttons_apply`** |
-| [reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md) | **搭建侧·门户工作台 SOP**（**工作台/门户页面搭建、发布与删除**）：**`portal list/get/apply/delete`**、**`--publish`**；删除结果要区分 `delete_executed` 与 `readback_status`；**`filter`** 的 CLI 限制见该文 §3.4；推荐模板示例 [portal_sections_standard_workbench.example.json](./reference/portal_sections_standard_workbench.example.json)，稳定五类示例 [portal_sections_five_types.example.json](./reference/portal_sections_five_types.example.json)；契约 **`builder contract --tool-name portal_apply` / `portal_delete`**                   |
-| [reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md) | **搭建侧·报表 QingBI/BI SOP**（**系统内报表/图表的创建、改配与排序**）：**`charts apply`**；应用源报表创建/更新、数据集报表仅关联已有、扩展图表类型与特殊字段映射、**immediate-live** 与 **`publish verify`** 关系见该文；示例 [charts_upsert_minimal.example.json](./reference/charts_upsert_minimal.example.json) 等                                                                             |
-| [reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md) | **搭建侧·字段匹配规则**：按钮新增数据 `field_mappings`、关联视图/报表 `match_mappings`、`数据ID(-17)` / `编号(0)`、类型兼容与 `associated_item_id` 口径。 |
-| [reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | **新建记录**：默认转交 `qingflow-record-insert`；标准链路 `record_insert_schema_get -> record_insert(items)`，CLI 用 **`record insert --items-file`**；成员/部门/关联优先自然语言输入 |
-| [reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md) | **更新记录**：主链路是 `record get` → 智能体按 `fields[]` 组 key/value → **`record update`**；`record schema update` 仅用于失败后诊断可写字段/路径                                                                                                                                 |
-| [reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)       | **管理员**：检索、导入等与成员差异（主技能正文不展开）                                                                                                                                                                                                                                                         |
-| [reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)   | CLI 实测与 argparse/服务端对齐备忘                                                                                                                                                                                                                                                              |
-| [reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md) | **可选**：全角色「一次可复制」分项模板；默认执行技能**不必**打开                                                                                                                                                                                                                                                  |
+| [reference/00-INDEX.md](./reference/00-INDEX.md) | **总导航**：按用户目标选择 record / task / builder 文档；复杂任务先读 |
+| [reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)     | **普通成员**主线：最短路径、`view_id`、与管理命令的差异预期                                                                                                                                                                                                                                                  |
+| [reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)       | **字段数据类型**：`record schema …` 的 `fields[]`（`field_id`、`title`、`kind`、`options`…）；`record list/get/access` 与写入 payload 的形态对照                                                                                                                                                                    |
+| [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **应用记录获取数据**：`app get`（`accessible_views`）→ `record schema browse` → `record list(query)` 模糊定位 / `record get` 详情页首屏上下文 / `record logs` 全量日志；分析取数转 `record_access`                                                                                                                                                                        |
+| [reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md) | **任务(待办已办)上下文 SOP**：`task list` → `task get` → `task log` → `task report` → `task action`；只把 `task_id` 作为主定位参数                                                                                               |
+| [reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) | **批量导入 SOP**：`app_get`（**`import_capability`**）→ `record_import_template_get` → `record_import_verify` →（可选）`record_import_repair_local` → `record_import_start` → `record_import_status_get`；CLI `import` / `record schema import`                                                   |
+| [reference/builder/README.md](./reference/builder/README.md) | **Builder 总导航**：完整系统、单应用、字段、布局、视图、报表、门户、按钮/关联资源、流程、发布校验 |
+| [reference/builder/10-build-single-app.md](./reference/builder/10-build-single-app.md) | **单应用搭建主入口**：一个应用端到端交付顺序 |
+| [reference/builder/20-build-complete-system.md](./reference/builder/20-build-complete-system.md) | **完整系统/应用包主入口**：多应用、同批 relation、门户闭环 |
+| [reference/builder/30-schema-fields.md](./reference/builder/30-schema-fields.md) | **字段 / schema**：字段类型、直觉别名、数据标题/封面、schema 创建与更新 |
+| [reference/builder/40-layout.md](./reference/builder/40-layout.md) | **布局**：分组、`rows` 矩阵、布局创建/更新/批量写 |
+| [reference/builder/50-views.md](./reference/builder/50-views.md) | **视图**：表格/卡片/看板/甘特、固定筛选、查询面板、视图 patch |
+| [reference/builder/60-charts.md](./reference/builder/60-charts.md) | **报表 / QingBI**：指标卡、图表、语义聚合、筛选、排序、更新 |
+| [reference/builder/70-portal.md](./reference/builder/70-portal.md) | **门户**：标准工作台、业务入口、指标、图表、视图组件、发布 |
+| [reference/builder/80-buttons-associated-resources.md](./reference/builder/80-buttons-associated-resources.md) | **按钮与关联资源**：自定义按钮、关联视图/报表、`match_mappings`、上下文传参 |
+| [reference/builder/90-workflow.md](./reference/builder/90-workflow.md) | **流程**：流程预设、`patch_nodes`、角色/成员、流程回读 |
+| [reference/builder/99-publish-verify.md](./reference/builder/99-publish-verify.md) | **发布与回读**：`publish verify`、partial/readback 处理、最终汇报口径 |
+| [reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | **新建记录**：`record schema insert -> record insert --items-file`；成员/部门/关联优先自然语言输入；细节见 [record/insert](./reference/record/insert/README.md) |
+| [reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md) | **更新记录**：主链路是 `record get` → 智能体按 `fields[]` 组 key/value → **`record update`**；`record schema update` 仅用于失败后诊断可写字段/路径                                                                                                                                 |
+| [reference/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md) | **删除记录**：`record list/get` 精确定位 → `record delete --app-key --record-id --view-id system:*`；批量用 `--record-ids-file` |
+| [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布统一走 `record access -> Python/pandas` |
+| [reference/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) | **底层交付参考**：历史完整 SOP、权限、旧 fallback、系统列和工具细节；不是主入口 |
+| [reference/builder/reference/workspace-icons.md](./reference/builder/reference/workspace-icons.md) | **图标参考**：`builder icon catalog`；新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color` |
+| [reference/builder/reference/match-rules.md](./reference/builder/reference/match-rules.md) | **字段匹配规则参考**：按钮新增数据 `field_mappings`、关联视图/报表 `match_mappings`、类型兼容 |
+| [reference/builder/workflow/README.md](./reference/builder/workflow/README.md) | **工作流搭建**：已有应用的流程建模、节点配置、`builder flow apply` 与 `patch_nodes` |
+| [reference/builder/code-integrations/README.md](./reference/builder/code-integrations/README.md) | **代码块 / Q-Linker 配置**：字段别名、绑定、输入字段插入和配置排障 |
+| [reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)       | **管理员**：检索、导入等与成员差异（主技能正文不展开）                                                                                                                                                                                                                                                         |
+| [reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md)   | CLI 实测与 argparse/服务端对齐备忘                                                                                                                                                                                                                                                              |
+| [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 <关键词>`                                                                                                                    |
 
@@ -145,7 +159,7 @@ qingflow --json auth whoami
 `app get` 里的 `CUSTOM_VIEW_LIST_UNAVAILABLE` 表示自定义视图列表读取被权限或后端限制降级；若 `accessible_views` 中仍有 `system:*`，可继续用该视图读数。若没有任何视图，再回到前端 URL、`app list` 可见应用、或用户提供的 `viewgraphKey` 补充上下文，不要直接断言应用不可读。
 `app get.data.can_create=false` 才表示 applicant/create 路径不可用；创建权限探测遇到 auth / server 等非权限类错误时应直接按失败处理，不要包装成“未知创建权限”或“用户无新建权限”。
 
-**细则、响应解包、`view_id` 雷区与命令模板**见 **[reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**（编写前已对当前 CLI **实跑**校验）。若仅需「最快看一眼有没有行」，可省略 **`schema browse`**，直接走下文「最短路径」。如果用户要任何最终统计结论、分析报告、趋势/排名/比例/分布，切换到 `qingflow-record-analysis`，按 `record_access -> Python/pandas` 执行。
+**细则、响应解包、`view_id` 雷区与命令模板**见 **[reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**（编写前已对当前 CLI **实跑**校验）。若仅需「最快看一眼有没有行」，可省略 **`schema browse`**，直接走下文「最短路径」。如果用户要任何最终统计结论、分析报告、趋势/排名/比例/分布，按 **[record/analysis](./reference/record/analysis/README.md)** 执行 `record access -> Python/pandas`。
 
 ---
 
@@ -153,11 +167,11 @@ qingflow --json auth whoami
 
 推荐顺序：
 
-1. **转交 `qingflow-record-insert`**：新建记录默认使用该专项 skill，避免旧的单条 `fields-file` 心智模型。
-2. **`record_insert_schema_get` / CLI `record schema insert`**：先读取 insert-ready schema、`required_fields`、`payload_template`、`format_hint`、`example_value`、联动与运行时必填提示。
-3. **`record insert(items)` / CLI `record insert --items-file`**：单条也是 `items` 数组的一行；成员、部门、关联字段优先写自然语言（如 `"张三"`、`"直销部"`、`"海军军医大学"`），仅在返回 `needs_confirmation` 时再让用户确认候选。
+1. **`record schema insert`**：先读取 insert-ready schema、`required_fields`、`payload_template`、`format_hint`、`example_value`、联动与运行时必填提示。
+2. **`record insert --items-file`**：单条也是 `items` 数组的一行；成员、部门、关联字段优先写自然语言（如 `"张三"`、`"直销部"`、`"海军军医大学"`），仅在返回 `needs_confirmation` 时再让用户确认候选。
+3. **写后读回**：单条重要数据用 `record get`，批量样本用 `record list` 或业务视图校验；`partial_success` 只重试失败行，不重放全批。
 
-**细则、字段 JSON 结构与排障**见 **[reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**。
+**细则、字段 JSON 结构与排障**见 **[reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**。
 
 ---
 
@@ -172,9 +186,9 @@ qingflow --json auth whoami
 
 **更新路径**：`record update` 会自动先尝试数据管理员直改，再 fallback 到前端同源的 custom view 详情编辑路径；如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑，最后会尝试 workflow save-only。成功时只需要读 **`status / update_route / verification_status`**；失败时再读失败原因与路线诊断。不要把中间 route 或辅助 schema/readback 探测的 40002 / 40027 / 404 当作最终失败。
 
-**大号 `record_id`（常见于 Snowflake 类 id）**：若干 CLI 版本在 **`record update` 写入路径**上对 `apply_id` 会做 **JavaScript 安全整数**相关校验，`list`/`get`/`schema update` 仍可能正常而 **更新落库报错**（常为 `apply_id must be positive`）。排障见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。业务统计与最终结论仍必须按 `qingflow-record-analysis` 使用 `record_access -> Python/pandas`。
+**大号 `record_id`（常见于 Snowflake 类 id）**：若干 CLI 版本在 **`record update` 写入路径**上对 `apply_id` 会做 **JavaScript 安全整数**相关校验，`list`/`get`/`schema update` 仍可能正常而 **更新落库报错**（常为 `apply_id must be positive`）。排障见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。业务统计与最终结论仍必须按 **[record/analysis](./reference/record/analysis/README.md)** 使用 `record access -> Python/pandas`。
 
-**命令模板、批量 `items` 形态、与新建相同的写入值约定**（按 **`kind`** 分题型见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**）见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
+**命令模板、批量 `items` 形态、与新建相同的写入值约定**（按 **`kind`** 分题型见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**）见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
 
 **成员 / 部门候选排障**：若成员、部门字段返回 `needs_confirmation` 或候选不清，使用 `qingflow record member-candidates` / `qingflow record department-candidates`；它们优先走表单字段候选范围接口（与前端选择器一致）。不要改用通讯录管理类查询去“补候选”，那会把普通成员误带到 ContactAuth 管理权限链路。
 
@@ -212,7 +226,7 @@ qingflow --json record list \
 
 `record list` 默认最多返回 10 条，适合样本检查和模糊定位；需要更大或更小样本时用 `--page-size <N>`，但最终统计结论仍转 `record_access -> Python/pandas`。若用户只给出模糊文本，使用 `--query` 和可选 `--query-field <FIELD_ID>` 收窄候选，再用 `record get` 读详情。若用户明确要完整日志/审计历史，继续执行 `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> --view-id <VIEW_ID> > tmp/qingflow_record_logs.json`，再读取返回的 `data_logs.local_path` / `workflow_logs.local_path`。
 
-**找应用包（Builder 管理面）**：默认直接用 **`builder package list --query <关键词>`**；它调用应用包后端 `/tag`，能看到空包、同名包和包级权限。拿到 `items[].package_id` 后再 `builder package get --package-id <ID>`。`package get` 会优先读 `/tag/{id}/baseInfo`，再尝试增强读取 `/tag/{id}`；若返回 `PACKAGE_DETAIL_READ_DEGRADED`，表示详细配置接口需要包编辑/加应用权限但基础信息已读到，不要当成包读取失败。旧版 CLI 没有该命令时，才看 **[reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) §2.3** 与 **[scripts/builder-package-from-app-list.py](./scripts/builder-package-from-app-list.py)**。
+**找应用包（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)**。
 
 **按关键字找应用（成员可用）**：默认直接用 **`app list --query`**，它只读取当前用户可见应用并在本地过滤，响应看 `items[].app_key`、`matched_count`、`unfiltered_count`、`filter_mode`。
 
@@ -231,7 +245,7 @@ qingflow --json app list --keyword '发票'
 - **`--view-id`** 仅从 **`app get`** 的 **`accessible_views`** 选取 **业务 / 自定义视图**（优先 **非「`custom:` 后仅数字」**，如带字母后缀的 `custom:…`）。
 - 若 `app get.warnings` 含 **`CUSTOM_VIEW_LIST_UNAVAILABLE`**，说明 custom view 列表辅助读取不可用；已有 `system:*` 视图仍可继续使用，缺 custom view 本身不等同于应用无权。
 - **禁止**把 `custom:1`、`custom:12` 等纯数字后缀自定义视图当作读数首选：成员侧常见 **`schema browse` / `record list`** 返回 **40038**。
-- 读数前**不必**前置 `workspace get`、`view get`。若仅需列表可先省略 **`record schema browse`**；若要列定义或与 **「获取数据工作流」** 对齐，见 **[reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**。
+- 读数前**不必**前置 `workspace get`、`view get`。若仅需列表可先省略 **`record schema browse`**；若要列定义或与 **「获取数据工作流」** 对齐，见 **[reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**。
 
 ---
 
@@ -247,7 +261,7 @@ qingflow --json app list --keyword '发票'
 | 工作区切换 | `workspace select`                                | 可能 **59004**（配额），与未登录区分      |
 
 
-**成员侧只读仍较稳**的示例：`app list` / `app get`、`portal list`。其它管理向子命令参见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+**成员侧只读仍较稳**的示例：`app list` / `app get`、`portal list`。其它管理向子命令参见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
 
 ---
 
@@ -276,7 +290,7 @@ qingflow --json task list \
 
 ### 待办 / 已办 / 抄送处理 SOP（`task list`）
 
-> **与编排工具名逐步对齐的独立长文**（含 **`task_workflow_log_get` / `task_associated_report_detail_get` / `task_action_execute`** 与 **`task log` / `task report` / `task action`** 对照、实测排障）：**[reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md](./reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)**。
+> **与编排工具名逐步对齐的独立长文**（含 **`task_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 勿混为一谈。
@@ -329,7 +343,7 @@ qingflow --json task list \
 
 **勿把记录列表的 `list_type`（或过时文档里的 `system:*` 视图口径）与任务中心的 `type` 混为一谈**：`task list --task-box …` 的映射见上表（例如任务中心「已办」为 `type=5`）；**不要**再把旧表单视图侧的编号抄到 `**--task-box`** 或自行拼接请求 `type`。
 
-更深的行为差异与踩坑备忘仍见 **[reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。
+更深的行为差异与踩坑备忘仍见 **[reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。
 
 #### `--query`（列表检索与回退）
 
@@ -358,7 +372,7 @@ qingflow --json task list \
 
 ### 记录：表结构、列表、分析取数
 
-多级子命令 **不要** 整体加引号；`record list` / `record access` **运行时必须** `--view-id`（从 `app get` 的 `accessible_views` 取）。最终统计结论、分析报告、趋势/排名/比例/分布必须切换到 `qingflow-record-analysis` 的 `record_access -> Python/pandas`。
+多级子命令 **不要** 整体加引号；`record list` / `record access` **运行时必须** `--view-id`（从 `app get` 的 `accessible_views` 取）。最终统计结论、分析报告、趋势/排名/比例/分布必须按 **[record/analysis](./reference/record/analysis/README.md)** 使用 `record access -> Python/pandas`。
 
 ```bash
 qingflow --json record schema browse \
@@ -386,9 +400,9 @@ qingflow --json record access \
 | `record insert/update` | 可用 `--verify-write`；`record update --dry-run` **仅批量**且需 `--items-file` |
 
 
-更多见 **[reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**管理向**（检索/导入等）见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+更多见 **[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` 只能使用系统列表语义删除：必须传 `system:*` 的 `--view-id`，不要传 `custom:*`、`list_type`，也不要省略视图上下文。若目标来自 custom view，先用该 view 的 `record list/get` 确认 record_id，再从 `app get.accessible_views` 选择一个可访问的系统视图删除；`RECORD_DELETE_CUSTOM_VIEW_UNSUPPORTED` / `RECORD_DELETE_VIEW_REQUIRED` 是配置边界，不是用户无权。
+`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)**。
 
 ### 注销
 
@@ -405,10 +419,10 @@ qingflow auth logout --forget-persisted
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | 未登录 / profile 未登录                                                | **再**走「认证方式」节，重试业务命令                                                                                                                    |
 | `record_list requires view_id`                                   | 先 `app get --app-key`，取 `view_id`                                                                                                       |
-| JSON 内 `backend_code` / `error_code`                             | 区分配额、权限与参数错误；普通成员见上节「偏向管理」；非本技能速查表覆盖的报错见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)** |
+| 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/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)** |
+| `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)** |
 
 
 ---
@@ -417,7 +431,7 @@ qingflow auth logout --forget-persisted
 
 **何时须细读引用、勿凭本节推测**：见**文首「硬约束（必读）」**。
 
-> **适用范围**：普通/基本成员在只读或小范围写入里**较高概率可用**的形态；勿照抄旧应用搜索入口、无权的 **`import …`**（易 **40002 / IMPORT_\***）；管理闭环见 **[reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.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`。
 
@@ -426,14 +440,14 @@ qingflow auth logout --forget-persisted
 | **auth** | `auth whoami` · `auth use-credential --base-url "$QINGFLOW_BASE_URL" --credential-stdin --persist` · `auth login …`（见「失败恢复时的认证方式」）· `auth logout --forget-persisted` |
 | **workspace** | `workspace list` · `workspace get --ws-id` · `workspace select`（慎用，可读数前不必；可能 **59004**） |
 | **app / portal / view / chart** | `app list [--query 关键词]` → **`app get --app-key`**（`accessible_views` / `view_id`、`import_capability`）· `builder package list [--query 关键词]` → `builder package get --package-id` · `portal list` · `portal get --dash-key` · `view get --view-id`（只读视图元信息；`baseInfo` 或 `viewConfig` 只有 40002 / 40027 / 404 这类权限/缺失边界可用另一侧降级，非权限类后端错误不隐藏；解析 app 仅依赖同源 view/form 与可见应用树，不回退旧应用搜索）· `chart get --chart-id`（图表 `baseInfo` / 数据 / 配置分阶段读取；单个辅助阶段 40002 / 40027 / 404 只作为 warning，非权限类后端错误不隐藏） |
-| **record** | `record schema insert`（新建记录 insert-ready schema，仅 `--app-key`）· **`browse`/`list`/`access`：`--app-key` + `--view-id`（缺一常 CONFIG）** · `record list --query ... [--query-field FIELD_ID] [--page-size N]` 用于候选定位/样本浏览 · `record get --record-id` 读详情页首屏上下文 · `record logs --record-id` 读完整数据/流程日志 JSONL · `record insert --items-file`（单条也是 items 一行）· `schema update --record-id [--view-id]` / **`update`**（单条 `--fields-file` **或** 批量 `--items-file`/`--dry-run`，二者勿混）· `export start/direct --view-id` 仅用于明确导出文件 · **`delete`/大 schema**：先 **[FIELD_DATA_TYPES](./reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md)** / **[RECORD_CREATE](./reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)** / **[RECORD_UPDATE](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**，再 `-h` |
-| **import** | `record schema import?` · `import template` → `verify` → `repair?` → `start`（**`being-enter-auditing` 必填**）→ `status`（**三者 selector 只选一**）；导入权限预检的 `baseInfo` 只有 40002 / 40027 / 404 可降级为 unknown，非权限错误不能当成无导入权或继续执行；**链路与本机目录**只靠本节不够 → **[RECORD_IMPORT](./reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)** |
-| **builder** | **搭建／系统化配置**：先读 `builder contract`。**完整系统/应用包**：`builder package apply --config-file` → `builder schema apply --apps-file`（主写法为 `{package_id, apps}` 对象；raw apps array / singleton wrapper array 仅兼容；同批 relation 主写 `target_app_ref` 指向 `client_key`，`target_app_key` 只用于已存在/已读回确认的目标）→ layout/views/flow/portal/charts。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先 `readback_before_retry`，不得直接拆单应用重建、重放整批或创建 V2/测试/随机后缀绕过重名。**单应用**：`app resolve/get` → `schema/layout/flow/views apply`。图标主写 `icon/color`；`icon_name/icon_color`、`icon_config`、`icon:{name,color}` 仅兼容/读回。选择字段 `options` 可用字符串数组或 `{label,value}` 对象数组。与普通读数/`record insert` 不是同一路径 → **[APP_DELIVERY](./reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**、[ICONS](./reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md)、[VIEWS](./reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)、[PORTAL](./reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)、[CHARTS](./reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md) |
-| **task**（须落盘见上文） | `task list [--task-box][--flow-status][--app-key][--query] --page --page-size`（**枚举、`--query`、与 `record` 视图口径勿混**：见上文 SOP · **[TASK_CONTEXT](./reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)**）· **`get`/`log`/`report`/`action`**：默认只传 `task list` 返回的 **`data.items[].task_id`**；`report` 另须必选 **`--report-id`**；`action` **无 `--dry-run`** |
+| **record** | `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 schema apply --apps-file`（主写法 `{package_id, apps}`；同批 relation 主写 `target_app_ref` 指向 `client_key`）→ layout/views/flow/charts/buttons/associated resources/portal。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先 `readback_before_retry`，不得直接拆单应用重建、重放整批或创建 V2/测试/随机后缀绕过重名。**单应用**：`app resolve/get` → `schema/layout/flow/views/charts apply`。更新动作归入对应资源文档：字段 [30](./reference/builder/30-schema-fields.md)、布局 [40](./reference/builder/40-layout.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)。 |
+| **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`** |
 
 **高发必败**：旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。
 
-更多成员策略：**[reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** · 一次性长模板：**[reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** · 对齐说明：**[reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/QINGFLOW_CLI_EXPLORATION_REPORT.md)**。
+更多成员策略：**[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)**。
 
 ---
 

package/skills/qingflow-cli/manifest.yaml

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

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

@@ -0,0 +1,35 @@
+# Qingflow CLI Reference Index
+
+Use this file as the first routing page after `SKILL.md` when the task is not a trivial one-command lookup.
+
+## Route by user goal
+
+| User goal | Read first | Then read |
+|-----------|------------|-----------|
+| 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) |
+| Build or modify apps, views, charts, portal, workflow | [builder index](./builder/README.md) | The resource document named there |
+
+## Builder task shortcuts
+
+| Builder task | Main document |
+|--------------|---------------|
+| One app end-to-end | [builder/single app](./builder/10-build-single-app.md) |
+| Multi-app system / app package | [builder/complete system](./builder/20-build-complete-system.md) |
+| Fields, schema, data title/cover | [builder/schema fields](./builder/30-schema-fields.md) |
+| Form layout | [builder/layout](./builder/40-layout.md) |
+| Views and view filters | [builder/views](./builder/50-views.md) |
+| QingBI charts/reports | [builder/charts](./builder/60-charts.md) |
+| Portal/workbench | [builder/portal](./builder/70-portal.md) |
+| Custom buttons and associated views/reports | [builder/buttons and associated resources](./builder/80-buttons-associated-resources.md) |
+| Workflow | [builder/workflow](./builder/90-workflow.md) |
+| Publish and readback verification | [builder/publish verify](./builder/99-publish-verify.md) |
+
+## Reading rule
+
+Pick the document for the target resource first. Do not start from historical playbooks or old MCP skill names. If a task says "update", route by the resource being updated: fields -> schema fields, views -> views, portal -> portal, charts -> charts, workflow -> workflow.

package/skills/qingflow-cli/reference/builder/10-build-single-app.md

@@ -0,0 +1,38 @@
+# Build Single App
+
+Read this when the user asks to create or complete exactly one Qingflow app.
+
+## Scope
+
+Responsible for: package/app resolution, schema fields, layout, workflow, views, charts, buttons/resources if needed, sample data if requested, and final verification.
+
+Not responsible for: multi-app relation modeling or a portal across several apps. Use [20-build-complete-system.md](./20-build-complete-system.md) when the user asks for a system, package, multiple modules, or cross-app relations.
+
+## Main chain
+
+```text
+package/app resolve -> schema -> layout -> workflow -> views -> charts -> buttons/resources -> sample data -> publish/readback verify
+```
+
+## Required reads by phase
+
+| Phase | Read |
+|-------|------|
+| Fields and app creation | [30-schema-fields.md](./30-schema-fields.md) |
+| Layout | [40-layout.md](./40-layout.md) |
+| Workflow | [90-workflow.md](./90-workflow.md) |
+| Views | [50-views.md](./50-views.md) |
+| Charts | [60-charts.md](./60-charts.md) |
+| Buttons or associated resources | [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) |
+| Final status | [99-publish-verify.md](./99-publish-verify.md) |
+
+## Completion standard
+
+- Exactly one top-level data title field exists.
+- Common business fields use canonical or supported intuitive aliases from [30-schema-fields.md](./30-schema-fields.md).
+- Layout places the important fields into readable groups.
+- New business views use business names, not default names such as `全部数据` or `我的数据`.
+- Charts and portal references are only reported complete after readback or the specific apply result verifies them.
+- If a write returns `partial_success`, `write_executed=true`, `safe_to_retry=false`, timeout, or readback 40002, read back before retrying the write.
+
+For a longer example playbook, use [reference/legacy-playbooks/build-single-app.md](./reference/legacy-playbooks/build-single-app.md) only as supporting material.

package/skills/qingflow-cli/reference/builder/20-build-complete-system.md

@@ -0,0 +1,39 @@
+# Build Complete System
+
+Read this when the user asks for a complete business system, app package, multiple modules, or related apps.
+
+## Scope
+
+Responsible for: package creation/reuse decision, all app schemas, cross-app relation fields, shared layout/view/report/portal conventions, workflow where requested, and final verification.
+
+Not responsible for: single existing-app record CRUD. Use record documents from [../00-INDEX.md](../00-INDEX.md) for data work.
+
+## Main chain
+
+```text
+package apply/get -> schema apply --apps-file -> app readback -> layout -> workflow -> views -> charts -> buttons/resources -> portal -> publish/readback verify
+```
+
+## Hard rules
+
+- Create related apps in one `builder schema apply --apps-file` call when possible.
+- Use the recommended apps-file shape: `{"package_id": 123, "apps": [...]}`.
+- Use `apps[].client_key` and relation `target_app_ref` for same-batch relations.
+- If schema apply times out or returns uncertain write state, perform readback before retrying. Do not recreate apps with `V2`, `测试`, or random suffixes.
+- Do not create default views such as `全部数据` or `我的数据`; those are platform defaults.
+- Portal business-entry grid components must contain real entry items, not empty `config` or `items: []`.
+
+## Required reads by phase
+
+| Phase | Read |
+|-------|------|
+| App package and schema | [30-schema-fields.md](./30-schema-fields.md) |
+| Layout | [40-layout.md](./40-layout.md) |
+| Workflow | [90-workflow.md](./90-workflow.md) |
+| Views | [50-views.md](./50-views.md) |
+| Charts | [60-charts.md](./60-charts.md) |
+| Associated reports/views and buttons | [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) |
+| Portal | [70-portal.md](./70-portal.md) |
+| Final status | [99-publish-verify.md](./99-publish-verify.md) |
+
+For a longer example playbook, use [reference/legacy-playbooks/build-complete-system.md](./reference/legacy-playbooks/build-complete-system.md) only as supporting material.

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md → builder/30-schema-fields.md}

@@ -1,6 +1,48 @@
-# `app_schema_apply` / `builder schema apply`：字段类型与场景总表
+# Builder Schema And Fields
 
-> **口径**：`field.type` 枚举以 **`qingflow --json builder contract --tool-name app_schema_apply`**（及包内 `PublicFieldType`）为准；**形状校验**以 `qingflow_mcp` 的 **`FieldPatch`**（`builder_facade/models.py`）与 **`app_schema_apply` 编排**（`builder_facade/service.py`）为准。  
+Read this when the task is about app creation fields, schema updates, field types, data title, data cover, relation fields, or system fields.
+
+## Scope
+
+Responsible for: `builder schema apply`, `add_fields`, `update_fields`, `remove_fields`, app creation through schema apply, field type aliases, data title/cover, and relation field shape.
+
+Not responsible for: form placement. Use [40-layout.md](./40-layout.md) after fields exist.
+
+## Main chain
+
+```text
+app/package resolve -> app get fields -> schema apply -> app get fields readback -> publish/readback verify
+```
+
+For complete systems, use `builder schema apply --apps-file` with `{package_id, apps}` and same-batch `target_app_ref`. For a single existing app, use `--app-key` plus field files.
+
+## Update existing schema
+
+- Re-read fields before updating; selectors may use `name`, `field_id`, or `que_id`.
+- Switch from `add_fields` to `update_fields` when a field already exists.
+- Use `remove_fields` only when deletion is explicitly intended.
+- If apply returns uncertain write state, re-read fields before retrying.
+
+Example patch:
+
+```json
+{
+  "app_key": "APP_KEY",
+  "publish": true,
+  "add_fields": [{"name": "跟进日期", "type": "date"}],
+  "update_fields": [
+    {
+      "selector": {"name": "金额"},
+      "set": {"name": "订单金额", "required": true}
+    }
+  ],
+  "remove_fields": [{"name": "旧字段"}]
+}
+```
+
+## Field type reference
+
+> **口径**：`field.type` 枚举以 **`qingflow --json builder contract --tool-name app_schema_apply`**（及包内 `PublicFieldType`）为准；**形状校验**以 `qingflow_mcp` 的 **`FieldPatch`**（`builder_facade/models.py`）与 **`app_schema_apply` 编排**（`builder_facade/service.py`）为准。
 > **CLI**：`qingflow [--profile NAME] builder schema apply [--app-key APP_KEY | 创建模式… | --apps-file 多应用对象] [--publish|--no-publish] [--add-fields-file …] [--update-fields-file …] [--remove-fields-file …]`；**`qingflow` 未在 PATH 时**可用 `npx @qingflow-tech/qingflow-cli` 前缀，并把 `--profile` 放在 `builder` 之前。
 > **新建应用主规则**：`add_fields[]` 里必须有且仅有一个顶层字段标记 `as_data_title: true`；数据封面可选，只能在顶层 `attachment` 字段标记 `as_data_cover: true`。
 > **权限**：包内新建应用按后端 `CreateAppBean` 链路只预检目标包 **AddAppAuth**；已有应用的字段/基础信息变更才走应用自身 **EditAppAuth**。
@@ -33,7 +75,7 @@
 | `relation` | 关联记录（**`relation_mode`**：`single` \| `multiple`） |
 | `subtable` | 子表（**`subfields[]`**） |
 
-**`relation_mode`**：仅 **`relation`** 使用，取值为 **`single`** 或 **`multiple`**（多关联字段能力受 **`verification.relation_field_limit_verified`** 等约束，见交付文 §6）。
+**`relation_mode`**：仅 **`relation`** 使用，取值为 **`single`** 或 **`multiple`**（多关联字段能力受 **`verification.relation_field_limit_verified`** 等约束，见 [reference/app-delivery-sop.md](./reference/app-delivery-sop.md)）。
 
 ### 1.1 智能体友好字段类型别名
 
@@ -83,16 +125,16 @@
 
 | 内容 | 位置 |
 |------|------|
-| **19 种 `type` + `code_block` + `q_linker` + 1 个 `relation`（一次 `add_fields`）** | [schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json)（首字段已标记 `as_data_title`，附件字段已标记 `as_data_cover`；`relation.target_app_key` 须指向含「单行文字」「多行文字」的目标应用，默认 `ead8ims5i401`） |
+| **19 种 `type` + `code_block` + `q_linker` + 1 个 `relation`（一次 `add_fields`）** | [schema_apply_add_fields_all_types.json](../examples/schema/schema_apply_add_fields_all_types.json)（首字段已标记 `as_data_title`，附件字段已标记 `as_data_cover`；`relation.target_app_key` 须指向含「单行文字」「多行文字」的目标应用，默认 `ead8ims5i401`） |
 | **`q_linker_example` / `code_block_example`**（契约内置形状） | `ai_builder_tools.py` 中 `app_schema_apply` 合约 |
-| 最小新建字段（1 个 text 标题字段） | [schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json) |
-| 历史 scalar / complex 批测（可选） | [_batch_schema_scalar.json](./_batch_schema_scalar.json)、[_batch_schema_complex.json](./_batch_schema_complex.json) |
+| 最小新建字段（1 个 text 标题字段） | [schema_add_fields_minimal.example.json](../examples/schema/schema_add_fields_minimal.example.json) |
+| 历史 scalar / complex 批测（可选） | [_batch_schema_scalar.json](../examples/schema/_batch_schema_scalar.json)、[_batch_schema_complex.json](../examples/schema/_batch_schema_complex.json) |
 
 ---
 
 ## 5. 实跑结论
 
-**一次性新建应用**：`--package-id` + `--app-name` + `--create-if-missing` + [schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json) 是当前推荐示例；它已包含唯一数据标题和可选数据封面（`q_linker` 使用 `https://httpbin.org/get`，`relation` 指向可读模板应用 `ead8ims5i401`）。
+**一次性新建应用**：`--package-id` + `--app-name` + `--create-if-missing` + [schema_apply_add_fields_all_types.json](../examples/schema/schema_apply_add_fields_all_types.json) 是当前推荐示例；它已包含唯一数据标题和可选数据封面（`q_linker` 使用 `https://httpbin.org/get`，`relation` 指向可读模板应用 `ead8ims5i401`）。
 
 **一次性新建多个应用**：用 `builder schema apply --package-id <TAG_ID> --create-if-missing --apps-file tmp/apps.json`，其中 `tmp/apps.json` 主写法为 `{ "package_id": 123, "apps": [...] }`，每个 `apps[]` 写顶层 `icon + color`；`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用，`apps[].app_name` 可被 `target_app` 引用，工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径，尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景；不要为了拿 `app_key` 先逐个创建再二次补关联字段。
 
@@ -102,6 +144,6 @@
 
 ## 6. 交叉引用
 
-- 交付主流程（读场 / 改场 / 发布）：[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) **§6**（类型速查与 `relation`/`q_linker`/`code_block` 要点）。  
-- 记录读写 `kind`（与搭建 `type` 不同系）：[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)。  
-- 主技能：[../SKILL.md](../SKILL.md)。
+- 交付主流程（读场 / 改场 / 发布）：[reference/app-delivery-sop.md](./reference/app-delivery-sop.md)（类型速查与 `relation`/`q_linker`/`code_block` 要点）。
+- 记录读写 `kind`（与搭建 `type` 不同系）：[QINGFLOW_CLI_FIELD_DATA_TYPES.md](../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)。
+- 主技能：[../SKILL.md](../../SKILL.md)。

package/skills/qingflow-cli/reference/builder/40-layout.md

@@ -0,0 +1,52 @@
+# Builder Layout
+
+Read this when the task is about form grouping, row order, field placement, or layout repair.
+
+## Scope
+
+Responsible for: `builder layout apply`, section titles, `rows` matrix, merge/replace mode, layout batch writes.
+
+Not responsible for: adding fields. Add or update fields first through [30-schema-fields.md](./30-schema-fields.md).
+
+## Main chain
+
+```text
+app get fields -> app get layout -> prepare sections -> builder layout apply -> readback when needed
+```
+
+## Public shape
+
+Use section `title + rows`. Do not invent top-level `columns`.
+
+```json
+{
+  "app_key": "APP_KEY",
+  "mode": "merge",
+  "publish": true,
+  "sections": [
+    {
+      "title": "基础信息",
+      "rows": [
+        ["客户名称", "订单金额"],
+        ["状态", "负责人"]
+      ]
+    }
+  ]
+}
+```
+
+## Update existing layout
+
+- Prefer `mode: "merge"` unless intentionally replacing the entire layout.
+- Re-read `app get fields` before writing; every field in `rows` must exist.
+- Re-read `app get layout` when apply returns `partial_success` or layout validation details.
+- Batch layout writes use the resource's `--apps-file`; each `apps[]` item carries its own `app_key` and layout payload.
+
+## Common failures
+
+| Failure | Action |
+|---------|--------|
+| `UNKNOWN_LAYOUT_FIELD` | Re-read fields and remove or correct the missing field name. |
+| `DUPLICATE_LAYOUT_FIELD` | Keep each field in only one row. |
+| `INCOMPLETE_LAYOUT` | Switch to `merge` unless replacing the whole layout intentionally. |
+| repeated shape errors | Read `builder contract --tool-name app_layout_apply`; reuse the canonical section example. |