@qingflow-tech/qingflow-cli 1.0.10 → 1.0.12

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 (90) hide show
  1. package/README.md +8 -4
  2. package/docs/local-agent-install.md +54 -3
  3. package/entry_point.py +1 -1
  4. package/npm/bin/qingflow-skills.mjs +5 -0
  5. package/npm/bin/qingflow.mjs +7 -2
  6. package/npm/lib/runtime.mjs +304 -13
  7. package/npm/scripts/postinstall.mjs +1 -5
  8. package/package.json +3 -2
  9. package/pyproject.toml +1 -1
  10. package/skills/qingflow-cli/SKILL.md +431 -0
  11. package/skills/qingflow-cli/manifest.yaml +10 -0
  12. package/skills/qingflow-cli/reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md +94 -0
  13. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md +432 -0
  14. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +177 -0
  15. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md +119 -0
  16. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +200 -0
  17. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md +288 -0
  18. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md +40 -0
  19. package/skills/qingflow-cli/reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md +129 -0
  20. package/skills/qingflow-cli/reference/QINGFLOW_CLI_EXPLORATION_REPORT.md +84 -0
  21. package/skills/qingflow-cli/reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md +129 -0
  22. package/skills/qingflow-cli/reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md +196 -0
  23. package/skills/qingflow-cli/reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md +159 -0
  24. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md +14 -0
  25. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md +150 -0
  26. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md +163 -0
  27. package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md +95 -0
  28. package/skills/qingflow-cli/reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md +150 -0
  29. package/skills/qingflow-cli/reference/_batch_schema_complex.json +18 -0
  30. package/skills/qingflow-cli/reference/_batch_schema_scalar.json +17 -0
  31. package/skills/qingflow-cli/reference/charts_remove.example.json +1 -0
  32. package/skills/qingflow-cli/reference/charts_reorder.example.json +1 -0
  33. package/skills/qingflow-cli/reference/charts_upsert_bar.example.json +8 -0
  34. package/skills/qingflow-cli/reference/charts_upsert_dashboard_starter.example.json +37 -0
  35. package/skills/qingflow-cli/reference/charts_upsert_minimal.example.json +13 -0
  36. package/skills/qingflow-cli/reference/portal_sections_all_types.example.json +131 -0
  37. package/skills/qingflow-cli/reference/portal_sections_five_types.example.json +106 -0
  38. package/skills/qingflow-cli/reference/schema_add_fields_minimal.example.json +7 -0
  39. package/skills/qingflow-cli/reference/schema_apply_add_fields_all_types.json +78 -0
  40. package/skills/qingflow-cli/reference/views_upsert_table_minimal.example.json +7 -0
  41. package/skills/qingflow-cli/scripts/builder-package-from-app-list.py +140 -0
  42. package/skills/qingflow-cli/scripts/find-app-by-keyword.py +132 -0
  43. package/skills/qingflow-mcp-setup/SKILL.md +113 -0
  44. package/skills/qingflow-mcp-setup/agents/openai.yaml +4 -0
  45. package/skills/qingflow-mcp-setup/references/claude-desktop.md +34 -0
  46. package/skills/qingflow-mcp-setup/references/environments.md +62 -0
  47. package/skills/qingflow-mcp-setup/references/generic-stdio.md +32 -0
  48. package/skills/qingflow-mcp-setup/scripts/check_local_server.sh +38 -0
  49. package/src/qingflow_mcp/__main__.py +6 -2
  50. package/src/qingflow_mcp/builder_facade/models.py +41 -2
  51. package/src/qingflow_mcp/builder_facade/service.py +2743 -423
  52. package/src/qingflow_mcp/cli/commands/app.py +3 -16
  53. package/src/qingflow_mcp/cli/commands/builder.py +30 -4
  54. package/src/qingflow_mcp/cli/commands/exports.py +2 -2
  55. package/src/qingflow_mcp/cli/commands/imports.py +1 -1
  56. package/src/qingflow_mcp/cli/commands/record.py +54 -11
  57. package/src/qingflow_mcp/cli/context.py +0 -3
  58. package/src/qingflow_mcp/cli/formatters.py +238 -8
  59. package/src/qingflow_mcp/cli/main.py +47 -3
  60. package/src/qingflow_mcp/errors.py +43 -2
  61. package/src/qingflow_mcp/public_surface.py +24 -16
  62. package/src/qingflow_mcp/response_trim.py +119 -12
  63. package/src/qingflow_mcp/server.py +17 -14
  64. package/src/qingflow_mcp/server_app_builder.py +29 -7
  65. package/src/qingflow_mcp/server_app_user.py +23 -24
  66. package/src/qingflow_mcp/solution/compiler/icon_utils.py +294 -0
  67. package/src/qingflow_mcp/solution/executor.py +112 -15
  68. package/src/qingflow_mcp/tools/ai_builder_tools.py +497 -65
  69. package/src/qingflow_mcp/tools/app_tools.py +237 -51
  70. package/src/qingflow_mcp/tools/approval_tools.py +196 -34
  71. package/src/qingflow_mcp/tools/auth_tools.py +92 -16
  72. package/src/qingflow_mcp/tools/code_block_tools.py +296 -39
  73. package/src/qingflow_mcp/tools/custom_button_tools.py +64 -10
  74. package/src/qingflow_mcp/tools/directory_tools.py +236 -72
  75. package/src/qingflow_mcp/tools/export_tools.py +230 -33
  76. package/src/qingflow_mcp/tools/file_tools.py +7 -3
  77. package/src/qingflow_mcp/tools/import_tools.py +293 -40
  78. package/src/qingflow_mcp/tools/navigation_tools.py +91 -12
  79. package/src/qingflow_mcp/tools/package_tools.py +134 -8
  80. package/src/qingflow_mcp/tools/portal_tools.py +39 -3
  81. package/src/qingflow_mcp/tools/qingbi_report_tools.py +116 -7
  82. package/src/qingflow_mcp/tools/record_tools.py +2305 -442
  83. package/src/qingflow_mcp/tools/resource_read_tools.py +191 -39
  84. package/src/qingflow_mcp/tools/role_tools.py +80 -9
  85. package/src/qingflow_mcp/tools/solution_tools.py +57 -15
  86. package/src/qingflow_mcp/tools/task_context_tools.py +569 -119
  87. package/src/qingflow_mcp/tools/task_tools.py +113 -29
  88. package/src/qingflow_mcp/tools/view_tools.py +106 -3
  89. package/src/qingflow_mcp/tools/workflow_tools.py +17 -1
  90. package/src/qingflow_mcp/tools/workspace_tools.py +71 -3
@@ -0,0 +1,129 @@
1
+ # Qingflow CLI:获取数据工作流(应用记录)
2
+
3
+ > **用途**:使用当前 CLI 会话,从「选定应用」到「读懂列含义 + 样本/模糊定位 / 单条详情」的**推荐闭环**;下表 **左列**可与常见 **编排/内部接口**命名对照,**右列**仅为本 CLI 命令。
4
+ > **新版口径**:`record_list` 不是批量分析入口,而是样本浏览和模糊定位入口;`record_get` 是前端详情页首屏上下文入口;全量日志用 `record logs`;分析取数统一转 `qingflow-record-analysis` 的 `record_access -> Python/pandas`。
5
+ > **关联**:权限、`view_id` 选取雷区、成员最短路径速查见 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**;**字段 `kind` / 数据类型**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**;**新建记录**见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**;**更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**;最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**;主技能规则见 **[../SKILL.md](../SKILL.md)**。
6
+
7
+ ---
8
+
9
+ ## 概念步骤 → CLI 映射
10
+
11
+ | 习惯概念名(编排/文档) | CLI 等价命令 | 必填要点 |
12
+ | --- | --- | --- |
13
+ | `app_get`(列应用内可访问视图) | `qingflow --json app get --app-key <APP_KEY>` | 从返回体的 **`data`(若存在)** 内取 `accessible_views[]` |
14
+ | `record_schema_get`,`schema_mode=browse` | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>` | 子命令 **`browse`** 即「浏览视图」表结构 |
15
+ | `record_list` | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID> [--query 文本] [--query-field FIELD_ID]` | 样本浏览 / 模糊定位,默认最多返回 10 条;`query_fields` 是全文搜索字段范围 |
16
+ | `record_get` | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 前端详情页首屏上下文:字段、首屏日志、引用、关联资源、图片与文件资产 |
17
+ | `record_logs_get` | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 单条记录全量可见数据日志 + 流程日志;自动分页写本地 JSONL,响应只返回摘要和文件路径 |
18
+
19
+ **补充**:若尚未持有 `APP_KEY`,先做 `qingflow --json app list [--query <关键词>]`,在 `items[].app_key` 里选应用;带 `--query` 时读取 `matched_count` / `unfiltered_count` 判断是否命中。
20
+
21
+ ---
22
+
23
+ ## 推荐执行顺序
24
+
25
+ ```text
26
+ app get(解析 accessible_views,选定 VIEW_ID)
27
+ → record schema browse(对齐字段 id/类型/展示名;也是 list/access/get 的视图字段口径)
28
+ → record list(样本浏览或 query 模糊定位候选)
29
+ → (可选)record get(对单条 record_id 拉详情页首屏上下文)
30
+ → (可选)record logs(需要完整审计日志时再拉全量日志 JSONL)
31
+ ```
32
+
33
+ - **仅当你只需要「快速确认有无数据」**时,可以省略 `schema browse`,直接 `app get` → `record list`(与成员速查表「最短路径」一致)。
34
+ - **当你需要稳定映射列名、写过滤条件或对接自动化**时,应按上表**显式**走 `schema browse`,避免对着 `list` 里中文列名猜字段定义。
35
+ - **当用户只给出模糊信息定位单条数据**时,走 `record schema browse` 确认可搜索字段,再用 `record list --query ... --query-field ...` 返回候选;只有候选明确后才 `record get`。
36
+ - **需要分组/聚合统计、最终统计结论、分析报告、趋势/排名/比例/分布**时,必须切换到 **`qingflow-record-analysis`**,按 `app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python/pandas -> final answer` 执行。
37
+
38
+ ---
39
+
40
+ ## 命令模板(占位符替换即可)
41
+
42
+ **1)应用与视图**
43
+
44
+ ```bash
45
+ qingflow --json app get --app-key <APP_KEY> > tmp/qingflow_app_get.json
46
+ ```
47
+
48
+ 从 `tmp/qingflow_app_get.json` 解析:`$.data.accessible_views`(无 `data` 时再试顶层 `accessible_views`)。每个元素含 `view_id`、`name`、`kind` 等。
49
+
50
+ 若响应 `warnings[]` 含 `CUSTOM_VIEW_LIST_UNAVAILABLE`,表示 custom view 列表读取被权限或后端限制降级;这不是应用整体不可读。优先使用已返回的 `system:*` 视图继续 `schema browse` / `record list`,或从前端 URL 的 `viewgraphKey` 补充明确 `view_id`。
51
+
52
+ **2)浏览视图表结构(= `record_schema_get` browse)**
53
+
54
+ ```bash
55
+ qingflow --json record schema browse \
56
+ --app-key <APP_KEY> \
57
+ --view-id <VIEW_ID> \
58
+ > tmp/qingflow_schema_browse.json
59
+ ```
60
+
61
+ 实跑样例响应顶层键包含:`status`、`app_key`、`schema_scope`、`fields`、`suggested_dimensions` 等(**以实际 JSON 为准**)。
62
+
63
+ **3)记录列表**
64
+
65
+ ```bash
66
+ qingflow --json record list \
67
+ --app-key <APP_KEY> \
68
+ --view-id <VIEW_ID> \
69
+ > tmp/qingflow_records.json
70
+ ```
71
+
72
+ 列表默认最多返回 10 条,行数据常见于 `$.data.items`;每条一般有 `record_id`(及业务字段键值)。响应会给出总数/下一步建议;如果是模糊定位,优先看 `lookup.total_count`、`lookup.next_action`。
73
+
74
+ **模糊定位示例**:
75
+
76
+ ```bash
77
+ qingflow --json record list \
78
+ --app-key <APP_KEY> \
79
+ --view-id <VIEW_ID> \
80
+ --query "北京和路元" \
81
+ --query-field 6299262 \
82
+ > tmp/qingflow_record_lookup.json
83
+ ```
84
+
85
+ `--query-field` 对应 `record_browse_schema_get.fields[].field_id`,表示后端全文搜索范围;它不是输出列控制。
86
+
87
+ **4)单条记录详情**
88
+
89
+ ```bash
90
+ qingflow --json record get \
91
+ --app-key <APP_KEY> \
92
+ --record-id <RECORD_ID> \
93
+ --view-id <VIEW_ID> \
94
+ > tmp/qingflow_record_get.json
95
+ ```
96
+
97
+ 已知前端视图时必须传同一个 `--view-id`;未知时 CLI 会先试默认详情 route,再在权限/不可见类错误下尝试可访问视图。`record_get` 现在返回详情页首屏上下文,重点看:`fields[]`、`references[]`、`data_logs`、`workflow_logs`、`associated_resources`、`media_assets`、`file_assets`、`semantic_context`。其中 `data_logs` / `workflow_logs` 只表示详情页首屏日志,不是全量审计历史。若 `unavailable_context[]` 中出现 `detail_schema`、`audit_info`、`data_logs`、`workflow_logs` 等,只说明这些辅助详情上下文读取受限;只要顶层 `status=ok` 且 `fields[]` 有目标字段,就不要把辅助 40002 当作记录不可读。图片读 `media_assets.items[].local_path`;文档/表格/PDF 等附件读 `file_assets.items[].local_path` 和 `file_assets.items[].extraction.text_path`。**不要直接访问远端 Qingflow 附件 URL**。
98
+
99
+ **5)全量日志(仅在用户明确需要完整审计/日志历史时)**
100
+
101
+ ```bash
102
+ qingflow --json record logs \
103
+ --app-key <APP_KEY> \
104
+ --record-id <RECORD_ID> \
105
+ --view-id <VIEW_ID> \
106
+ > tmp/qingflow_record_logs.json
107
+ ```
108
+
109
+ 响应重点看:`data_logs.local_path`、`workflow_logs.local_path`、`items_count`、`pages_fetched`、`complete`、`context_integrity.safe_for_full_log_conclusion`。完整日志在本地 JSONL 文件中,默认目录为 `~/.qingflow-mcp/record-logs/<run_id>/`;不要把 JSONL 全文直接塞进上下文,按需用脚本读取、筛选或汇总。
110
+
111
+ ---
112
+
113
+ ## `view_id` 选取(成员侧必读摘要)
114
+
115
+ - **`system:all` 等业务系统视图**:实跑可用于 `schema browse` + `record list`(具体以租户配置为准)。显式传入的 `view_id` 必须按前端当前视图忠实执行;`system:all` 报 40002 / 40027 / 404 / 500 时,不要自动换成 `system:initiated`、`system:todo` 等其它系统视图,除非用户或前端 URL / `app get.accessible_views` 重新指定了那个视图。
116
+ - **`CUSTOM_VIEW_LIST_UNAVAILABLE`**:只说明 `app get` 没能列出 custom view;若已有 `system:*` 可用,不要把它当作应用或记录读取失败。
117
+ - **`custom:` 后仅数字**(如 `custom:1`):成员侧常见 **`schema browse` / `list` / `access` 均 40038**,应**跳过**,改选 **`custom:` 带字母后缀**或其它可用视图(详见成员速查表「先有通路、再要有数据」)。
118
+ - **待办 / 已办 / 抄送「任务箱」**:不要用旧文档里的 `system:todo` 等视图充当任务中心;应使用 **`task list --task-box …`**(见主技能 **待办 SOP**)。
119
+
120
+ ---
121
+
122
+ ## 落盘与解析
123
+
124
+ - `schema browse`、`record list`、`record get`、`record logs` 体量大时,**必须**重定向到文件,勿将整段 JSON 直接塞进 LLM 上下文(规则见主技能「输出落盘规则」)。`record_get` 下载的本地图片/文件路径可以再交给图片理解、文档解析或 Python 读取;`record logs` 的全量日志读 `*.jsonl` 文件。
125
+ - 解析前**先 unwrap `data`**:多数业务成功响应为 `{ "data": { ... } }`,与 `schema browse` 部分字段在顶层的形态可能不同,以每次响应为准。
126
+
127
+ ---
128
+
129
+ *维护:CLI 升级后请用 `qingflow record schema browse -h`、`qingflow record list -h`、`qingflow record get -h`、`qingflow record logs -h` 复核选项名;概念名 `record_schema_get` / `schema_mode=browse` 在 CLI 中固定对应子命令 `record schema browse`。*
@@ -0,0 +1,84 @@
1
+ # Qingflow CLI 当前版本审计备忘
2
+
3
+ > 本文件只记录当前 CLI 与 skill 主路径容易混淆的事实。它不是执行 SOP;具体任务仍按 [SKILL.md](../SKILL.md) 与对应专题 reference 执行。CLI 升级后优先重新跑 `qingflow ... --help` 复核。
4
+
5
+ ---
6
+
7
+ ## 1. 当前能力树摘要
8
+
9
+ - 顶层:`qingflow {auth|workspace|app|portal|view|chart|record|import|export|task|builder|build} ...`
10
+ - `builder` 与 `build` 等价;默认写法仍推荐 `builder`。
11
+ - `record schema`:公开主路径为 `browse`、`insert`、`update`、`import`、`code-block`;`applicant` 仅为兼容保留入口,不作为推荐链路。
12
+ - `record` 公开执行入口:`list`、`access`、`get`、`logs`、`insert`、`update`、`delete`、`code-block-run`。
13
+ - 最终统计结论统一由 `qingflow-record-analysis` 走 `record_access -> Python/pandas`,不要寻找或使用其它聚合捷径。
14
+
15
+ ---
16
+
17
+ ## 2. 不要被 `--help` 方括号误导
18
+
19
+ 部分参数在 argparse 帮助中看起来可选,但运行时由工具层或后端强制要求:
20
+
21
+ | 命令 | 实际要求 |
22
+ | --- | --- |
23
+ | `app list` | 可选 `--query` / `--keyword`,只在当前用户可见应用中本地过滤 |
24
+ | `builder package list` | 可选 `--query`,直接读取 Builder 应用包 `/tag` 列表并本地过滤 |
25
+ | `record schema browse` | 必须 `--app-key` + `--view-id` |
26
+ | `record list` | 必须 `--app-key`;业务记录读取应显式给 `--view-id` |
27
+ | `record access` | 必须 `--app-key` + `--view-id` |
28
+ | `builder member search` | 必须 `--query` |
29
+ | `builder role search` | 必须 `--keyword` |
30
+
31
+ 自动化里读取命令优先使用根级 JSON 形态:`qingflow --json ...`;builder 写入/apply 命令默认只输出 JSON,不需要额外选择格式。builder apply 响应统一优先读 `operation + summary + resources[]`,其中 `resources[].id/key/name/ids/parent` 是 UI/智能体展示资源的稳定入口;旧字段只作兼容和排障。不要依赖根级 `qingflow --version`,查包版本优先用 `npm ls -g @qingflow-tech/qingflow-cli` 或当前安装路径(如 `which qingflow`)。
32
+
33
+ ---
34
+
35
+ ## 3. Record 当前口径
36
+
37
+ | 入口 | 当前定位 |
38
+ | --- | --- |
39
+ | `record list` | 样本浏览 / 模糊定位候选;默认最多返回 10 条,返回 `data.pagination.total_count`,带 `--query` 时看 `lookup.total_count` 与 `lookup.next_action` |
40
+ | `record access` | 默认分析取数入口;自动分页写本地 CSV;不暴露 `page/page_size/limit/max_rows/profile` |
41
+ | `record get` | 前端详情页首屏上下文;字段、引用、首屏数据日志、首屏流程日志、关联资源、`media_assets`、`file_assets` |
42
+ | `record logs` | 单条记录全量可见数据日志 + 流程日志;自动分页写本地 JSONL,响应给路径和完整性 |
43
+ | `record insert` | 批量 `items` JSON;单条也是 `items` 数组一行;CLI 用 `--items-file` |
44
+ | `record update` | 单条 `--record-id + --fields-file` 或批量 `--items-file`;不要混用 |
45
+
46
+ `record_get` 下载到本地的图片读 `media_assets.items[].local_path`;文档、表格、PDF 等读 `file_assets.items[].local_path` 与 `extraction.text_path`。不要直接访问远端 Qingflow 附件 URL。
47
+
48
+ ---
49
+
50
+ ## 4. Builder 当前口径
51
+
52
+ | 入口 | 当前定位 |
53
+ | --- | --- |
54
+ | `builder app get` | 应用地图;轻量返回字段摘要、视图、图表、自定义按钮、关联资源池 |
55
+ | `builder schema apply` | 字段/新建应用;多应用应用包用 `--apps-file`,同批 `relation` 用 `target_app_ref`;新建应用必须有且仅有一个 `as_data_title: true`;封面用顶层 `attachment` 字段 `as_data_cover: true` |
56
+ | `builder views apply` | 业务视图;固定筛选写 `filters`,前端查询栏写 `query_conditions` |
57
+ | `builder button apply` | 自定义按钮默认路径;新增数据按钮用 `field_mappings/default_values`,绑定位置用 `header/detail/list` |
58
+ | `builder associated-resource apply` | 应用级关联视图/报表池 + 视图展示配置;报表来源用 `report_source`,不让智能体填写后端 raw source |
59
+ | `builder charts apply` | QingBI 报表配置;报表变更 immediate-live,不等同于应用发布 |
60
+ | `builder publish verify` | 发布后核验应用状态 |
61
+
62
+ 按钮和关联资源 apply 有成功写入时会自动发布;没有成功写入、全阻断或全失败时不应额外发布。
63
+
64
+ ---
65
+
66
+ ## 5. ID 口径
67
+
68
+ | 名称 | 用途 |
69
+ | --- | --- |
70
+ | `view_id` | 用户态记录读取,形如 `system:all` 或 `custom:<viewKey>`;来自 `app get.accessible_views` |
71
+ | `view_key` | Builder 视图配置;用于 `builder view get`、`builder views apply`、按钮/关联资源视图配置 |
72
+ | `chart_id` / `chart_key` | 报表本体 ID/key;不可直接当作视图关联资源 ID |
73
+ | `associated_item_id` | 应用级关联资源项 ID,即后端 `form_asos_chart.id`;视图展示关联资源时必须用它 |
74
+
75
+ 普通成员读数时,`custom:` 后仅数字的视图(如 `custom:1`、`custom:12`)常见 40038,应跳过并换 `system:all` 或其它表格类 `custom:*`。
76
+
77
+ ---
78
+
79
+ ## 6. 错误判断
80
+
81
+ - `59004` 多与额度/流币/AI 配额相关,不等同于未登录。
82
+ - `40002` 常是成员权限不足,尤其是角色检索、部分管理向操作;按关键词找应用优先用 `app list --query`。
83
+ - `record list/access requires view_id` 不是数据为空,是缺少视图上下文。
84
+ - 大 JSON 记录/任务查询仍建议落盘到 `tmp/...json` 后再读,不要直接塞入模型上下文;builder 写入/apply 工具默认直接 stdout,前端展示时优先解析 `resources[]`,需要留档时使用 `tee`。builder 读取命令仍显式加 `--json`。
@@ -0,0 +1,129 @@
1
+ # Qingflow CLI:字段数据类型(Schema / 列表 / 写入)
2
+
3
+ > **用途**:说明 **`record schema …`** 的 **`fields[]`**、**`record list` / `record get` / `record access`** 行内值、以及 **insert/update 写入 payload** 的常见对应关系;并单独说明 **选项联动、关联记录、引用填充、公式/系统题、AI 与受限类型** 等在 CLI 下的表现与处置。
4
+ > **依据**:当前 CLI 在 **`--json`** 下会对 **schema** 响应做 **裁剪**:通常只保留本节列出的键;**`kind`** 由内部写入类别归并而来(见下表)。**`que_type` 等若未出现在输出中**,以 **`kind` + 实跑预检** 为准。
5
+ > **关联**:写入值细节与成员/部门见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**;更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**;只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**;**搭建侧** **`app_schema_apply` 的 `type`(与本文 `kind` 命名体系不同)**见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**;主技能 **[../SKILL.md](../SKILL.md)**。
6
+
7
+ ---
8
+
9
+ ## 1. `fields[]` 通用结构(`--json` 精简后)
10
+
11
+ | 字段 | 含义 |
12
+ |------|------|
13
+ | **`field_id`** | 内部题 id(数字);**`record_access.columns` / `where-file` / `order-by-file` 等 DSL** 常以此引用列。 |
14
+ | **`title`** | 题目标题;insert/update 的 `fields` map 键通常与之一致。 |
15
+ | **`kind`** | 见 **§2 `kind` 枚举**;决定读写时值的形态。 |
16
+ | **`options`** | 可选;**`kind=select`** 时常为允许选项的字符串列表。 |
17
+ | **`target_app_key`** | 可选;**`kind=relation`** 时关联目标应用。 |
18
+ | **`searchable_fields`** | 可选;**`kind=relation`** 时在关联侧可用来检索的字段说明。 |
19
+ | **`row_fields`** | 可选;**`kind=subtable`** 时子表列的子 schema(递归同类结构)。 |
20
+ | **`required`** | 部分场景(如 **`record schema update`** 拆出的 `required_fields` / `optional_fields`)出现。 |
21
+ | **`template`** | 少数响应里与 **`payload_template`** 联动出现,供生成初稿。 |
22
+
23
+ **browse 与 detail**:`browse` 产出视图表头的精简 **`fields[]`**;`record get` 产出当前记录详情字段。一般 **不含** 完整 **`que_type`/`writable`** 元数据。更新主链路先用 **`record get`** 的字段信息组 payload,再执行 **`record update`**;只有更新失败、字段歧义或需要诊断可写范围时,再结合 **`record schema update`**(按记录)或写入返回判断。
24
+
25
+ ---
26
+
27
+ ## 2. `kind` 枚举(CLI 对外)
28
+
29
+ 内部写入类别经归并后形成下表 **`kind`**(与 `qingflow` 当前实现一致;升级后请以 **`record schema … --json` 实跑** 为准):
30
+
31
+ | CLI `kind` | 维护侧常见内部类别(参考) | 在 `record list` / `record get` / `record access` 中(常见) | insert/update 写入值 |
32
+ |------------|-----------------------------------|--------------------------------------------|----------------------------------|
33
+ | **`scalar`** | `scalar_text`、`boolean_label`、`date_string` 及未映射类型默认归此 | 多为 **字符串或数字** JSON 标量;布尔/日期常以 **展示字符串** 出现;**地址**题在精简里常仍归 **scalar**,写入时按 **地址对象/分段**(见创建记录文档) | **字符串 / 数字 / 布尔** 等;具体以后端预检为准 |
34
+ | **`select`** | `single_select`、`multi_select` 合并为同一 kind(**§3.1**) | **单选**:与选项同文案的字符串;**多选**:字符串数组或实现可识别的列表 | **单选**:**`options` 中某一元素的字符串**(或实现接受的选项对象);**多选**:**数组** |
35
+ | **`member`** | `member_list` | 常为人类可读名;或对象(含 id、邮箱等,随租户配置) | 优先自然语言字符串,如 `"张三"`;`needs_confirmation` 时按候选改显式对象,如 `{"uid":1048599,"name":"沈嘉慧Seth","email":"..."}` |
36
+ | **`department`** | `department_list` | 部门名或 id 形态 | 优先自然语言字符串,如 `"直销部"`;`needs_confirmation` 时按候选改显式对象/id |
37
+ | **`relation`** | `relation_record`(**§3.2**) | 常为关联展示字段或 `apply_id` 相关信息 | **`apply_id`**、可解析对象或自然语言;多匹配会返回 `needs_confirmation`,需选候选后重试 |
38
+ | **`attachment`** | `attachment_list` | URL、文件名或结构化附件对象 | **`{"value"或"url", "name"?}`**;常需 **`builder file upload-local` 先上传** |
39
+ | **`address`** | `address_parts`(**对外 `kind` 常被映射进 `scalar`**,以实跑为准) | 对象或分段地址 | **省/市/区/detail 对象** 或 **有序片段数组**(见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**) |
40
+ | **`subtable`** | `subtable_rows` | **行数组**;行内键为子列 title | **行数组**;行内 **`title → 值`**;更新行可带 **`row_id`/`__row_id__`**(见实现) |
41
+ | **`unsupported`** | `unsupported_direct_write`(**§3.4、§3.5**) | 只读/仅流程内填写等 | **勿直接写入**;预检会 `UNSUPPORTED_WRITE` / 类似 blockers |
42
+
43
+ 说明:
44
+
45
+ - **单选/多选**在对外 `kind` 上 **同是 `select`**;以 **`options` 是否存在 + 业务语义** 区分;多选写入用 **数组**。
46
+ - **`scalar`** 是 **桶类型**:文本、数字、金额、日期、布尔等在对外展示上常同为 `scalar`,**具体校验以后端与预检为准**。
47
+ - **`field_id=0`** 等系统列可能为 **`system`+只读**;不要写入 insert/update payload(见创建文档「系统维护字段」)。
48
+
49
+ ---
50
+
51
+ ## 3. 特殊字段详解(选项联动、关联、引用、受限类型)
52
+
53
+ 本节对应轻流里常见的 **「选项」「选项联动」「关联记录」「引用/数据联动」** 等;CLI 侧大多仍落在 **`kind=select` / `relation` / `scalar` + 只读** 等组合上,需结合 **预检** 理解。
54
+
55
+ ### 3.1 选项字段(单选 / 多选)
56
+
57
+ | 概念 | CLI 表现 | 读写注意 |
58
+ |------|----------|----------|
59
+ | **单选** | 内部题类型常为 **10、11**;对外 **`kind=select`**,多带 **`options` 字符串列表** | **列表/详情**:常为与选项 **完全一致** 的展示文案。写入:传 **`options` 中某项字符串**(或预检接受的选项对象) |
60
+ | **多选** | 内部题类型常为 **12、15**;对外仍为 **`kind=select`**(与单选 **同名 kind**) | **列表/详情**:常为 **字符串数组** 或可解析的多值结构。写入:传 **JSON 数组**(每个元素对应一个选项值) |
61
+ | **区分单多选** | 精简 schema **仅有 `kind`+`options`** | 以 **表单配置 / 同一 `title` 在别处的表现 / 写入预检** 为准;**唯一写入层面**的硬规则是:**多选必须按数组传** |
62
+
63
+ **选项联动(控制显隐、必填等)**
64
+
65
+ - 实现上来自 **题目关系 + 选项上的联动题 id**(如其它题因当前选项而被激活)。
66
+ - **`record schema browse` 的 `--json`**:精简 `fields[]` 可能不展示完整 `linkage` / 联动明细;新建记录以 `qingflow-record-insert` 的 `record_insert_schema_get`(CLI `record schema insert`)为准,不要用兼容保留的 applicant schema 入口替代。
67
+ - **写入时**:若更新返回提示 **上游未选、联动未激活、字段尚未显示**,应 **先写或改 payload 里处于上游的选项(或其它驱动题)**,再写下游;必要时用 **`record schema update --record-id …`** 诊断当前记录下 **`required_fields` / `optional_fields` / `payload_template`**。
68
+
69
+ ### 3.2 关联字段(关联记录)
70
+
71
+ | 概念 | CLI 表现 | 读写注意 |
72
+ |------|----------|----------|
73
+ | **关联记录** | 内部题类型 **25**;对外 **`kind=relation`** | Schema 常含 **`target_app_key`**,以及可选 **`searchable_fields`**(在 **被关联应用** 侧参与检索的字段线索) |
74
+ | **列表/详情** | 多为 **展示用字符串** 或结构化片段(以租户配置为准) | 不要猜测 `apply_id`;从 **关联列表 / 人工指定 / 预检返回的候选** 取得 |
75
+ | **写入 payload** | 「选中一条被关联记录」 | 优先传可被唯一解析的自然语言(如客户名/项目名)或 `{"apply_id":"..."}`;**多匹配** 时易出现 **待确认候选** 或 **阻断**(按返回 `confirmation_requests` / `blockers` 处理) |
76
+
77
+ **`needs_confirmation`**:表示工具没有写入(`write_executed=false`),只是返回候选。成员、部门、关联字段都可能触发;应从 `confirmation_requests[].candidates[]` 选一个候选对象/id 重试,成功后再报告最终结果。
78
+
79
+ ### 3.3 「引用」与数据填充(非独立 `kind`)
80
+
81
+ 产品里的 **「引用」** 常指:**本题由其它题(选项、关联、成员等)通过规则自动带出**,对应表单元数据中的 **引用/填充配置**。
82
+
83
+ | 现象 | 建议 |
84
+ |------|------|
85
+ | 目标列 **只读** 或预检判定 **只能通过上游带出** | **不要**在 payload 里强行赋值;改 **上游题**(选项、关联、`relation`、`member` 等),让服务端重算 |
86
+ | 目标列 **`kind` 仍是 `scalar` / `select`** | **「引用」不是单独对外 `kind`**;是否可手填以 **`writable` / 预检 / `record schema update`** 为准 |
87
+ | 需要联动说明 | 非精简 schema 中可能出现 **`linkage`** 类结构(如引用链角色);**当前 CLI `--json` 精简常去掉 `linkage`**,以 **实跑预检错误信息** 与 **表单设计** 为准 |
88
+
89
+ **公式、默认值**:若题目由 **公式或默认规则** 计算,常与 **只读 / 系统题** 同类处理,以 **`UNSUPPORTED_WRITE`、`READONLY_OR_SYSTEM_FIELD`** 等预检结果为准。
90
+
91
+ ### 3.4 受限或禁止直写的类型(实现约定)
92
+
93
+ 下列为 **当前 CLI 写入规范化实现** 中的典型 **`unsupported_direct_write`**(对外 **`kind=unsupported`**),**不要依赖 CLI 直接构造复杂载荷**:
94
+
95
+ | 内部 `que_type`(维护参考) | 含义(简述) |
96
+ |-----------------------------|--------------|
97
+ | **14** | **时间区间** 等:需要后端原生结构,CLI 侧不承诺拼装正确 |
98
+ | **34** | **图像识别**(运行时 AI) |
99
+ | **35** | **AI 生图**(运行时 AI) |
100
+ | **36** | **文档解析**(运行时 AI) |
101
+
102
+ **处置**:改在 **轻流界面 / 流程节点** 中产生这些值;或缩小 payload 仅写 **不受支持的题之外** 的字段。
103
+
104
+ ### 3.5 其它 layout / 展示类
105
+
106
+ 内部 **24** 等为 **布局/说明** 类题,通常 **不出现在可写字段** 中;若误入 payload,以预检 **`unsupported`** / **`readonly`** 为准剔除即可。
107
+
108
+ ---
109
+
110
+ ## 4. 与 `field_id` / 列选择
111
+
112
+
113
+ - **`record list --column`**:参数为 **数字列 id**,用于样本/候选列表展示列,须与 **`fields[].field_id`** 一致。
114
+ - **`record get`**:默认读取前端详情页首屏上下文;不要把 `--column` 当成详情字段投影主路径,单条字段、首屏日志、引用、图片/文件资产以 `record_get` 的结构化上下文为准。若用户要完整数据日志/流程日志历史,用 `record logs`。
115
+ - **标题重复**:同一 `title` 可能对应多个 `field_id`(极少见);列表 DSL 应用 **`field_id`** 消歧。
116
+
117
+ ---
118
+
119
+ ## 5. 读者操作建议
120
+
121
+ 1. **按场景取上下文**:只读/定位视图列用 `record schema browse --view-id …`;新建用 `record schema insert --app-key …`;更新用 `record get --record-id …` 先读当前记录详情,再用 `record update` 写入;`record schema update --record-id …` 只在失败、字段歧义或显式诊断时使用。
122
+ 2. **数据分析**:最终统计结论、分析报告、趋势/排名/比例/分布必须走 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**。
123
+ 3. **看 `kind` + `options` / `row_fields` / `target_app_key`**,并对照 **§3 特殊字段** 判断是否存在联动、引用或只读带出。
124
+ 4. **选项联动 / 引用带出**:先写 **驱动题**,再写 **被带出的题**;只读带出列 **不要强写**。
125
+ 5. **写入前缩小 payload**;insert 默认用 `record insert --items-file`,单条也是 `items` 数组一行。根据 **`status` / `blockers` / `field_errors` / `failed_fields` / `created_record_ids`** 迭代(`--json` 在 stdout)。
126
+
127
+ ---
128
+
129
+ *维护:`kind` 集合与精简字段以当前 CLI 的 `record schema … --json` 实跑为准;内部 `que_type` 枚举随轻流版本变化,文档只稳定描述对外 **`kind`** 桶。*
@@ -0,0 +1,196 @@
1
+ # Qingflow CLI 普通成员命令速查表
2
+
3
+ > **适用对象**:当前会话为 **普通/基本成员**(`permission_level` 非租户/应用管理员、`import_capability` 常为无导入权等)。Wingent Momo runtime 下不要先跑 `auth whoami`;只有业务失败、账号不确定或排障时才核对身份。
4
+ > **与主技能关系**:请以 **[SKILL.md](../SKILL.md)**(本目录上一级)的规则与命令速查表为准。**本表**:成员侧最短读数与高概率通路;**租户/管理员向差异**请参阅同目录 **[QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
5
+ > **可选补充**:同一目录 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** 收录 **全体角色通用**的子命令逐项模板(与本文分工:本文偏「成员能跑通的策略」,ONE_SHOT 偏「参数逐项闭合示例」)。
6
+
7
+ > **实证**:以下结论以会话内 `qingflow …` 为准;换账号/环境请以 `qingflow … -h` 与必要的身份核对结果为准。
8
+
9
+ **统一习惯**
10
+
11
+ - **只读拉取表单记录的最短链路**:见本节 **「最短路径:普通成员只读记录数据」**(可省略 `schema browse`)。**需先拉浏览视图表结构**时见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**;最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**;**字段 `kind` / 数据形态**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**;**新建记录默认批量 JSON 链路**请用 **`qingflow-record-insert`**(`record_insert_schema_get -> record_insert(items)`,CLI 为 `record insert --items-file`,成员/部门/关联优先自然语言);**浏览视图下更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
12
+ - 避免无必要地先绕 `workspace`、`view get`。
13
+ - 加 `--json`,便于区分 **CONFIG_ERROR**(少参)与 **backend**(权限/业务)。
14
+ - `app get` / `portal list` 等业务体常在 `**{ "data": { ... } }`** 里:取 `accessible_views`、`items` 前先 unwrap `data`。
15
+
16
+ ---
17
+
18
+ ## 最短路径:普通成员「只读记录数据」
19
+
20
+ > **目标**:直接使用当前 CLI 会话,用**最少 RPC、无多余子命令**,走到 `**record list` 成功返回样本/候选 JSON**;找应用用 `**app list [--query 关键词]`**,在读数前**不必**调用 `auth whoami` / `workspace get` / `view get` / `record schema browse`(除非你另需结构、query field 或排障)。
21
+
22
+ ### 调用次数
23
+
24
+
25
+ | 前置 | 命令数 | 说明 |
26
+ | ------------ | ------ | ---------------------------------------- |
27
+ | 从零选应用 | **3** | `app list` → `app get` → `record list` |
28
+ | 已知 `APP_KEY` | **2** | `app get` → `record list` |
29
+ | 排障 | **+1** | 业务命令明确提示会话不可用、账号不确定时,再追加 `auth whoami` |
30
+
31
+
32
+ ### 固定写法(复制后只换占位符)
33
+
34
+ ```bash
35
+ qingflow --json app list
36
+ # 如果用户只给应用关键词:
37
+ qingflow --json app list --query <关键词>
38
+ # 在 items 中取 app_key → APP_KEY
39
+
40
+ qingflow --json app get --app-key <APP_KEY>
41
+ # 从返回 JSON 中取出应用对象(若存在顶层 .data 则先用 .data);在 accessible_views 里选 view_id,见下文「先有通路、再要有数据」
42
+
43
+ qingflow --json record list \
44
+ --app-key <APP_KEY> \
45
+ --view-id <VIEW_ID>
46
+ ```
47
+
48
+ 大 JSON 按规范 **重定向落盘**(`> tmp/qingflow_records.json`)。
49
+
50
+ ### 先有通路、再要有数据
51
+
52
+
53
+ | 关注点 | 说明 |
54
+ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
55
+ | **连通性优先** | 从 `app get.accessible_views` 选择表格类业务视图,优先 `system:all` 或明确可读的 `custom:*`。`record list` 默认最多 10 条,只用于样本/候选。 |
56
+ | **不一定有明细行** | 业务视图可能因视图筛选为空;`items` 为空不等于 CLI 坏了。若目标是任务中心待办/已办/抄送,应换 `task list --task-box …`。 |
57
+ | **读不到数据时** | 在同一应用的 `accessible_views` 里切换其它表格类视图,跳过 **纯数字后缀** `custom:*`;不要用 `system:todo/done/cc` 当业务记录入口。 |
58
+
59
+
60
+ **普通成员不要使用「自定义 + 纯数字 id」去读数:** 形如 `**custom:1`、`custom:2`、`custom:12`**(`custom:` 后**仅数字**)。此类在实测中 `**record schema browse` / `list` / `access` 一致 40038**(`Object not exist`),**不可用其作为换源备选**——应直接跳过并在 **其它视图 id** 上取样。
61
+
62
+ ### 为何不再多调这些
63
+
64
+
65
+ | 不先调 | 原因 |
66
+ | ---------------------------------- | -------------------------------------------------------- |
67
+ | `workspace get` / `workspace list` | 读应用记录**不依赖**;徒增一次往返,且 list 在部分环境受 **59004** 等影响。 |
68
+ | `view get` | `**record list` 不前置要求**;读后仍要看 `app get` 给的 `view_id` 才稳。 |
69
+ | `record schema browse` | 只读「有哪些列」才需要;纯拉数据 **list 足够**。 |
70
+
71
+
72
+ ---
73
+
74
+ ## 1. 优先使用(成员场景下实测高概率 exit 0)
75
+
76
+
77
+ | 场景 | 命令 | 说明 |
78
+ | ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
79
+ | CLI 版本 | `npm ls -g @qingflow-tech/qingflow-cli` 或 `which qingflow` | 勿用根级 `qingflow --version`。 |
80
+ | 帮助 | `qingflow -h`、`qingflow record schema browse -h` | 嵌套子命令勿整体加引号。 |
81
+ | 身份与租户 | `qingflow --json auth whoami` | 用 `selected_ws_id` / `selectedWsId` 当作当前工作区。 |
82
+ | 工作区只读 | `qingflow --json workspace get --ws-id <WS_ID>` | `WS_ID` 与 whoami 一致最稳。 |
83
+ | 工作区枚举 | `qingflow --json workspace list --page 1 --page-size 40` | 若遇 59004(流币等),仍可依赖 whoami + `workspace get`。 |
84
+ | 应用发现 | `qingflow --json app list [--query <关键词>]` | 成员通常可看「有权限的应用」列表;`--query` 只在可见应用中本地过滤。 |
85
+ | 应用详情 | `qingflow --json app get --app-key <APP_KEY>` | 从 `data.accessible_views`(或顶层兼容结构)取 `**view_id`**;同源可取 `**package_id` / `package**`,供 `builder package get`。 |
86
+ | 用户侧视图只读 | `qingflow --json view get --view-id <VIEW_ID>` | 用于补充视图配置,不是 `record list` 前置;业务记录读取仍以 `app get.accessible_views` 中的可读表格类视图为准;解析 app 只看同源 view/form 与可见应用树,不走旧应用搜索。 |
87
+ | 门户 | `qingflow --json portal list`、`qingflow --json portal get --dash-key <DASH_KEY>` | `items` 常在 `data.items` 中取 `dash_key`。 |
88
+ | Record 元数据(多只需 app-key) | `qingflow --json record schema insert --app-key <APP_KEY>` 等 | 新建记录用 `insert` schema;`import` / `code-block` 仅在对应专项场景使用;`applicant` 仅兼容保留,不作为推荐入口。 |
89
+ | Record 带视图 | 见下节 **「view-id 选取」** | `browse` / `list` / `access` 必须 `--view-id`。 |
90
+ | 待办列表 | `qingflow --json task list --app-key <APP_KEY> --page 1 --page-size 50` | 无待办时也可能 **0 条但 exit 0**;`task get` / `task log` / `task report` 需有效 `**task_id`**(及必要的 `report_id`),**无待办则无 id 可测**(非 CLI 错误)。 |
91
+ | Builder(只读且成员常可用) | `qingflow --json builder member search --query <关键词>` | `**--query` 必填**(服务端)。 |
92
+ | Builder 发布自检 | `qingflow builder publish verify --app-key <APP_KEY>` | builder 校验命令自动 JSON,相对安全。 |
93
+ | 应用包读取 | `qingflow --json builder package get --package-id <整数>` | `**package_id` 必须以 `app get`(等)返回为准**;偶发占位 id 在某环境可读**不可依赖**,换应用/包即可能失败。 |
94
+
95
+
96
+ ---
97
+
98
+ ## 2. `view-id` 选取(成员必读)
99
+
100
+ `app get` 返回的 `accessible_views` **顺序上第一个**未必有数据读权限:**部分** `custom:*` 在基本成员下对 `schema browse` / `record list` 会返回 `**backend_code=40038`(如 `Object not exist`)**;**另有部分** `custom:*`(例如名称「我的数据」类)可与系统视图一样 **exit 0**,须按 **具体 `view_id`** 判断(见下「按视图探测」)。待办/已办/抄送属于任务中心语义,不再作为业务记录读取首选。
101
+
102
+ **特例(务必区分):** `**custom:` 后仅为数字**(`custom:1`、`custom:12` 等)在普通成员会话下 **不适合作为读数备选**(三命令实测 **一致 40038**);可读业务数据时请加用 **非纯数字后缀的 `custom:…`**(如 `custom:ebdl…`)或 `**system:*` / 本节策略**切换,勿与「部分 custom 不可用」泛泛混为一谈。
103
+
104
+ 建议策略:
105
+
106
+ 1. 优先选择 `system:all` 或名称明确的表格类 `custom:*` 业务视图来确认 `record list` 能通;若 `items` 为空,先判断当前视图筛选是否导致为空,再换其它表格类视图。若某个显式 `view_id` 返回权限或服务端错误,不要在同一次调用里把它自动改成其它系统视图;需要换视图时重新从 `app get.accessible_views` 或前端 URL 选。
107
+ 2. `**custom:` 后仅数字**的 id(如 `**custom:1`、`custom:12`**):**普通成员不可用其读数**,与策略 1 并行时**直接跳过**,不要在「换视图」时误选。
108
+ 3. `view get` 只用于补充视图配置/导出能力,不是 `record list` 的前置条件;拉数以 `app get.accessible_views` 选出的 `view_id` 为准。
109
+
110
+ **按视图探测**:对同一 `app_key` 下 `**custom:<纯数字>` 之外**的 `view_id` 按需跑 `**record schema browse` / `list`** 筛通路。实测:`custom:1/2/12` 均 **40038**;`custom:ebdl…`「我的数据」可用;系统视图可用。
111
+
112
+ ---
113
+
114
+ ## 3. 成员常见「命令写对仍失败」(不要当 CLI 坏了)
115
+
116
+
117
+ | 命令/场景 | 典型现象 | 含义(成员) |
118
+ | -------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
119
+ | 旧应用搜索入口 | `backend_code=40002` | 工作区级搜索常无权限;改用 `**app list --query`** 或 `**app list`** 选应用。 |
120
+ | `import template` / `import verify` | `IMPORT_TEMPLATE_UNAUTHORIZED`、`IMPORT_AUTH_PRECHECK_FAILED` | 非应用导入管理员。 |
121
+ | `import status` 仅 `--app-key` | `IMPORT_STATUS_AMBIGUOUS` | 无最新唯一导入记录或无权解析。 |
122
+ | `builder role search` | `ROLE_SEARCH_FAILED` / `backend_code=40002` | 搭建侧角色检索对成员常关闭。 |
123
+ | `chart get` 随意 id | `network` / 报表类错误 | 需**真实且有权**的 `chart-id`(从应用/门户配置取)。 |
124
+ | `**custom:1`、`custom:2`…(冒号后仅数字)** 上读数 | 基本成员 **不可用**上述 id 作主数据源;实测 **browse/list/access→40038**(见上文) | **不要**把它们当作「换一个 custom 试试」;应换同一应用下其它表格类业务视图,如 `system:all` 或 `custom:` 后缀含字母等(如 ebdl…)的视图;任务箱请走 `task list --task-box` |
125
+ | 某非标 `custom:*` 上 `record …` | `40038` / `Object not exist`(exit 4) | 该成员对该视图无权限;换**同一应用**下其它 `**view_id`**(见上文排除规则)。 |
126
+ | `record get` | 需 list 里出现 `record_id` | 若当前视图下列表无数据,则**无 id 可测**(与权限无关时的空结果)。 |
127
+ | `workspace select` | `59004` | 流币/AI 配额与操作类型相关,与其他失败区分。 |
128
+ | 本会话未展开 | `auth login` / `use-credential`、写操作 | 与角色无关的**命令形态**见通用表;成员仍可能因业务策略无法写。 |
129
+
130
+
131
+ ---
132
+
133
+ ## 4. 仍建议避免的写法(与通用表一致)
134
+
135
+
136
+ | 错误 | 原因 |
137
+ | ------------------------------------------------------------- | ------------------------------------------------------------- |
138
+ | `qingflow --version` | 根解析器无此参数。 |
139
+ | `record list` 无 `--view-id` | `CONFIG_ERROR` / `requires view_id`。 |
140
+ | **用 `custom:1`、`custom:12`** 等(`custom:` 后**仅数字**)作普通成员的主读数视图 | 实测 **browse/list/access 一律 40038**,与业务空数据不同,**换源时请跳过**该类 id。 |
141
+ | `builder member search` 无 `--query` | `MEMBER_QUERY_REQUIRED`。 |
142
+ | `builder role search` 无 `--keyword` | `ROLE_QUERY_REQUIRED`(有参数也可能因权限仍失败)。 |
143
+
144
+
145
+ ---
146
+
147
+ ## 5. 扩展链路(含 workspace / schema)
148
+
149
+ 若你还要 **核对当前工作区** 或 **先看 browse 字段**,在 **§「最短路径」** 之外可增加(顺序仍建议 **先最短再扩展**)。注意:最终统计结论、分析报告、趋势/排名/比例/分布必须使用 `qingflow-record-analysis` 的 `record_access -> Python/pandas`:
150
+
151
+ ```bash
152
+ qingflow --json auth whoami # 仅业务失败、账号不确定或需要写清当前租户上下文时
153
+ # 记下 selected_ws_id → WS_ID
154
+
155
+ qingflow --json workspace get --ws-id <WS_ID> # 仅当需要写清「当前租户上下文」时
156
+
157
+ qingflow --json app list
158
+ qingflow --json app get --app-key <APP_KEY>
159
+ # accessible_views:优先表格类业务视图;若无业务行再换其它 view(勿用 custom:+纯数字,见前文)
160
+
161
+ qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID> # 需要字段结构时
162
+ qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>
163
+ ```
164
+
165
+ 大数据请按团队规范 **重定向落盘**。
166
+
167
+ ---
168
+
169
+ ## 6. 与其它文档的关系
170
+
171
+
172
+ | 文档 | 用途 |
173
+ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
174
+ | [SKILL.md](../SKILL.md) | **主文档**:认证、落盘规则、正文「命令速查」与高危操作节选。 |
175
+ | [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md) | **导入 / `builder role search` 等**管理向差异与成员侧失败对照。 |
176
+ | [QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md) | 可选:全角色通用;各节「一次可复制」命令块与附录必败清单。 |
177
+
178
+
179
+ ---
180
+
181
+ *修订时请同步:若服务端权限枚举或 CLI 改名,以 `qingflow … -h` 与实测为准。*
182
+
183
+ ---
184
+
185
+ ## 7. 验证清单(维护者)
186
+
187
+ 以下结论来自 **基本成员** 会话与 help/实测归纳;配额、权限与数据为空等属环境差异:**换账号时请自行复验**。
188
+
189
+
190
+ | 主张 | 说明 |
191
+ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
192
+ | §1 表内多数「高概率 exit 0」命令 | 在典型成员会话下过 help/试跑对齐;仍以当前 CLI 与服务端为准。 |
193
+ | `custom:*` 与 `system:*` 在 browse/list/access 上差异 | 同上;`custom:+纯数字` 读数常 40038 已在上文单列。 |
194
+ | `workspace select` 可能 59004 | 流币等配额与其它失败区分;非每次必现。 |
195
+ | **§「最短路径」**(app list→get→record list;优先表格类业务视图;空数据则换其它可读表格视图;**勿用 `custom:<仅数字>`**) | 不包含多余 `workspace get`/`schema browse`,除非另行需要。 |
196
+ | 本文未逐条自动化验证的项 | `task get`/`log`/`report`(缺 id)、`chart get`(缺真实 id)、**写路径** `record insert` 等 — 按通用表与业务策略,需有数据/权限时再测 |