npm - @qingflow-tech/qingflow-cli - Versions diffs - 1.1.2 → 1.1.34 - Mend

@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (103) hide show

package/README.md CHANGED Viewed

@@ -3,13 +3,13 @@
 Install:
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.2
+npm install @qingflow-tech/qingflow-cli@1.1.34
 ```
 Run:
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.2 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.34 qingflow
 ```
 Environment:

package/docs/local-agent-install.md CHANGED Viewed

@@ -84,6 +84,7 @@ npm run pack:npm
 ```bash
 dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
+dist/npm/qingflow-cli-<version>.tgz
 dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
 dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 ```
@@ -91,11 +92,20 @@ dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 然后在目标机器安装：
 ```bash
+npx -y -p /absolute/path/to/dist/npm/qingflow-cli-<version>.tgz qingflow-cli install --package /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
 npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
 npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
 npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 ```
+线上官网入口对应：
+```bash
+npx qingflow-cli@latest install
+```
+安装器只安装真实 CLI 包 `@qingflow-tech/qingflow-cli`。它会先检查 Node.js、npm 和 Python 3.11+；如果 `npm install -g` 因本机全局目录权限失败，安装器会自动 fallback 到用户目录（macOS/Linux 为 `~/.local`，Windows 为当前用户 AppData npm 目录），但不会修改 shell 配置文件；PATH 缺失时会打印需要执行的 shell / PowerShell 命令。排障可加 `--verbose`；如需禁止 fallback 可加 `--no-fallback`。
 安装时会自动：
 1. 创建 `.npm-python/`

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.2",
+  "version": "1.1.34",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml CHANGED Viewed

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "qingflow-mcp"
-version = "1.1.2"
+version = "1.1.34"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/SKILL.md CHANGED Viewed

@@ -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 按智能体任务路径组织：完整系统、单应用、字段、已有应用布局维护、视图、报表、门户、关联资源、流程、发布校验；完整系统创建用 apps[].form 一次声明字段、relation 和布局；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读/批量写/局部改作为资源文档内的写法变体；明细见「关联文件」表与文末命令索引。
 ---
 # 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.07.01.04`（入口文档版本；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 --json version` 返回的 `package / version / command_path / executable_path / package_root / skill_version` 为准；不要从安装文档或全局 npm 目录猜版本。人工快速查看可用 `qingflow --version`。**复杂任务先读 [reference/00-INDEX.md](./reference/00-INDEX.md)**。**搭建/创建/系统配置**：先区分 **完整系统/应用包** 与 **单应用**。完整系统主链路必须走 `builder package apply -> builder schema apply --apps-file`，每个应用只用 `apps[].form` 同时声明字段、表单分组和行布局，并用 `apps[].client_key + relation.target_app_ref` 处理同批跨应用关联；不要拆成逐个应用创建、真实 `target_app_key` 回填、`add_fields` 追加或单独 `layout apply`。单应用新建走 `builder schema apply --package-id --app-name --form-file`，已有应用才走 `--app-key` 的维护路径。门户需要新报表时在 portal section 写 `chart`，不要把报表创建拆成完整系统主步骤。完整系统 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` 矩阵、布局修复；新建应用布局写在 `form` 内 |
+| [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`、上下文传参；按钮配置看视图文档 `action_buttons` |
+| [reference/builder/90-workflow.md](./reference/builder/90-workflow.md) | **流程**：WorkflowSpec、`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、权限、系统列和工具细节；不是主入口 |
+| [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) | **统一筛选 / 条件写法**：`filters`、`visible_when`、QingBI 图表筛选、工作流条件、`match_mappings`、`field_mappings` 的 `operator/value` 规则 |
+| [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 <关键词>`                                                                                                                    |
@@ -56,10 +70,10 @@ description: |
 > 仅qingflow命令执行后发现不可用再安装，不需要进行校验动作
 ```bash
-npm install -g @qingflow-tech/qingflow-cli@latest
+npx qingflow-cli@latest install
 ```
-环境：Node.js v16+、npm、可达轻流 API。
+安装器会安装真实 CLI 包 `@qingflow-tech/qingflow-cli@latest`；会预检 Node.js、npm、Python 3.11+；若全局 npm 目录权限不足，会 fallback 到用户目录（macOS/Linux 为 `~/.local`，Windows 为用户 AppData npm 目录）并提示 PATH 配置，不会自动改 shell 文件。排障可加 `--verbose`。环境：Node.js v16+、npm、Python 3.11+、可达 npm registry / 轻流 API。
 ---
@@ -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)**。
 ---
@@ -166,15 +180,15 @@ qingflow --json auth whoami
 主链路是先读详情，再直接提交用户要求修改的 key/value。不要把 `record schema update` 当成更新前置步骤：
 1. **`record get`** → 拿 **`record_id`、当前值、fields[].title / field_id / kind**；已知前端/自定义视图时必须带同一个 **`--view-id`**。未知时 CLI 会先试默认 `system:all`，权限拒绝后再尝试可访问视图，但智能体仍优先从 `app get.accessible_views` 取 view。
-2. 智能体根据 `record get.fields[]` 和用户要求，组一个只包含待改字段的 JSON 对象（标题 → 值）。
+2. 智能体根据 `record get.fields[]` 和用户要求，组一个只包含待改字段的 JSON 对象（标题 → 值）。字段必须来自当前详情上下文的 `fields[]`；带 `--view-id` 时，视图隐藏的字段不要强写。若用户要求改的字段不在当前 `record get.fields[]`，先换到包含该字段的视图/详情上下文，或用 `record schema update` 做失败诊断。
 3. **`record update`** → **`--record-id` + `--fields-file`**，已知前端视图时同样带 **`--view-id`** 让 CLI 优先走该 view；批量用 **`--items-file`**（**`--dry-run` 仅批量**）。
 4. 只有字段范围不清、候选歧义、或 `record update` 失败时，才用 **`record schema update`** 诊断本条记录的 **`writable_fields / payload_template / available_update_routes`**；已知前端视图时同样带 **`--view-id`**，让诊断优先探测同一个详情页上下文。
 **更新路径**：`record update` 会自动先尝试数据管理员直改，再 fallback 到前端同源的 custom view 详情编辑路径；如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑，最后会尝试 workflow save-only。成功时只需要读 **`status / update_route / verification_status`**；失败时再读失败原因与路线诊断。不要把中间 route 或辅助 schema/readback 探测的 40002 / 40027 / 404 当作最终失败。
-**大号 `record_id`（常见于 Snowflake 类 id）**：若干 CLI 版本在 **`record update` 写入路径**上对 `apply_id` 会做 **JavaScript 安全整数**相关校验，`list`/`get`/`schema update` 仍可能正常而 **更新落库报错**（常为 `apply_id must be positive`）。排障见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。业务统计与最终结论仍必须按 `qingflow-record-analysis` 使用 `record_access -> Python/pandas`。
+**大号 `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}`；每个应用写 `apps[].form`；同批 relation 只写 `target_app_ref` 指向 `client_key`；布局在 `form[].rows` 内，不单独提交）→ 视图（按钮随视图 `action_buttons` 写）→ 门户（缺报表时写 `chart`）→ 发布/回读。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先 `readback_before_retry`，不得直接拆单应用重建、重放整批或创建 V2/测试/随机后缀绕过重名。**单应用**：新建走 `schema apply --form-file`，再按需求配置流程/视图。更新动作归入对应资源文档：字段 [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 CHANGED Viewed

@@ -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、门户、关联资源、流程、发布校验；完整系统创建主链路是 package apply -> schema apply --apps-file，使用 apps[].form 一次声明字段、relation 和布局；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读、批量写、局部改作为资源内写法变体；默认不把登录或工作区校验作为业务前置
 tags:
   - cli
   - qingflow

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

@@ -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) |
+| Associated views/reports and current-record matching | [builder/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.