@qingflow-tech/qingflow-cli 1.1.61-beta.2 → 1.1.61-beta.4

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 (5) hide show
  1. package/README.md +3 -3
  2. package/package.json +1 -1
  3. package/pyproject.toml +1 -1
  4. package/skills/qingflow-cli/SKILL.md +8 -13
  5. package/skills/qingflow-cli/reference/data/README.md +38 -0
package/README.md CHANGED
@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
7
7
  ## 安装
8
8
 
9
9
  ```bash
10
- npm install @qingflow-tech/qingflow-cli@1.1.61-beta.2
10
+ npm install @qingflow-tech/qingflow-cli@1.1.61-beta.4
11
11
  ```
12
12
 
13
13
  推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
21
21
  ## 运行
22
22
 
23
23
  ```bash
24
- npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.2 qingflow
24
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.4 qingflow
25
25
  ```
26
26
 
27
27
  全局安装后可以直接运行：
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
62
62
  如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
63
63
 
64
64
  ```bash
65
- npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.2 qingflow-skills install --agent codex --scope user --copy
65
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.4 qingflow-skills install --agent codex --scope user --copy
66
66
  ```
67
67
 
68
68
  `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qingflow-tech/qingflow-cli",
3
- "version": "1.1.61-beta.2",
3
+ "version": "1.1.61-beta.4",
4
4
  "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "qingflow-mcp"
7
- version = "1.1.61b2"
7
+ version = "1.1.61b4"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
package/skills/qingflow-cli/SKILL.md CHANGED
@@ -14,6 +14,8 @@ description: |
14
14
 
15
15
  本 Skill 负责 CLI 入口、文件约定和业务分流。已知 `app_key` 时直接执行 `data query/get`。只有应用名称时，先用 `qingflow --json app list --query "应用名称"` 查找当前工作区的可见应用，并核对返回项的 `app_name/title`；目标明确且唯一时取其 `app_key` 再查询，否则请用户确认。不要把应用名称直接传给 `--app-key`，也不要为定位名称转向 builder 或切换工作区。字段能力、权限范围与下一步动作以当前工具 schema、data 响应和 `hints` 为准。
16
16
 
17
+ 首次解析 `data query/get` 响应前，阅读 [data 响应结构与解析](./reference/data/README.md#响应结构与解析)，按同次响应中的 schema 与记录结构读取目标字段。
18
+
17
19
  ## 关联文件
18
20
 
19
21
 
@@ -23,7 +25,7 @@ description: |
23
25
  | [reference/00-INDEX.md](./reference/00-INDEX.md) | **总导航**：按用户目标选择 record / task / builder 文档；复杂任务先读 |
24
26
  | [reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md) | **普通成员**主线：最短路径、`view_id`、与管理命令的差异预期 |
25
27
  | [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 的形态对照 |
26
- | [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` |
28
+ | [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **普通应用数据读取**：`data query` 获取记录和 schema → 按需 `data get` 读取单条；附件下载见 [data 操作说明](./reference/data/README.md) |
27
29
  | [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` 作为主定位参数 |
28
30
  | [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` |
29
31
  | [reference/builder/README.md](./reference/builder/README.md) | **Builder 总导航**：完整系统、单应用、字段、布局、视图、报表、门户、按钮/关联资源、流程、发布校验 |
@@ -40,7 +42,7 @@ description: |
40
42
  | [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) |
41
43
  | [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` 仅用于失败后诊断可写字段/路径 |
42
44
  | [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` |
43
- | [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布统一走 `record access -> Python/pandas` |
45
+ | [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布统一走 `data query --all --output csv -> Python/pandas` |
44
46
  | [reference/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) | **底层交付参考**：历史完整 SOP、权限、系统列和工具细节；不是主入口 |
45
47
  | [reference/builder/reference/workspace-icons.md](./reference/builder/reference/workspace-icons.md) | **图标参考**：`builder icon catalog`；新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color` |
46
48
  | [reference/builder/reference/match-rules.md](./reference/builder/reference/match-rules.md) | **统一筛选 / 条件写法**：`filters`、`visible_when`、QingBI 图表筛选、工作流条件、`match_mappings`、`field_mappings` 的 `operator/value` 规则 |
@@ -129,18 +131,11 @@ qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
129
131
 
130
132
  ---
131
133
 
132
- ## 应用记录：获取数据工作流（推荐闭环）
133
-
134
- 与常见 **编排/API 文档**里的命名对齐时的固定顺序为：
135
-
136
- 1. **`app_get`**：`qingflow --json app get --app-key <APP_KEY>` → 在 **`data.accessible_views`**（或等价路径）选取 **`view_id`**。
137
- 2. **`record_schema_get`（`schema_mode=browse`）**：`qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>`（CLI 子命令 **`browse`** 即浏览视图表结构）。
138
- 3. **`record_list` / `record_get` / `record_logs_get`**：`record list …` 用于样本浏览或模糊定位候选；`record get --record-id …` 下钻单条前端详情页首屏上下文（字段、首屏日志、引用、图片与文件资产）；只有需要完整审计历史时，再用 `record logs --record-id …` 读取全量数据日志和流程日志 JSONL。
134
+ ## 应用数据：查询与读取（默认路径）
139
135
 
140
- `app get` 里的 `CUSTOM_VIEW_LIST_UNAVAILABLE` 表示自定义视图列表读取被权限或后端限制降级；若 `accessible_views` 中仍有 `system:*`，可继续用该视图读数。若没有任何视图，再回到前端 URL、`app list` 可见应用、或用户提供的 `viewgraphKey` 补充上下文，不要直接断言应用不可读。
141
- `app get.data.can_create=false` 才表示 applicant/create 路径不可用；创建权限探测遇到 auth / server 等非权限类错误时应直接按失败处理，不要包装成“未知创建权限”或“用户无新建权限”。
136
+ 已知 `app_key` 时直接执行 `qingflow --json data query --app-key <APP_KEY>`；首次查询保留默认 schema，根据响应中的 `field_capabilities` 和 `hints` 决定筛选、分页或停止。定位到 `record_id` 后，按需执行 `qingflow --json data get --app-key <APP_KEY> --record-id <RECORD_ID>`；下载附件时加 `--download-attachments`。
142
137
 
143
- **细则、响应解包、`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`。
138
+ 参数与附件处理见 [data 操作说明](./reference/data/README.md)。详情页引用、关联资源和完整日志见 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)；最终统计结论按 [数据分析说明](./reference/record/analysis/README.md) 使用 `data query --all --output csv`。
144
139
 
145
140
  ---
146
141
 
@@ -167,7 +162,7 @@ qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
167
162
 
168
163
  **更新路径**：`record update` 会自动先尝试数据管理员直改，再 fallback 到前端同源的 custom view 详情编辑路径；如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑，最后会尝试 workflow save-only。成功时只需要读 **`status / update_route / verification_status`**；失败时再读失败原因与路线诊断。不要把中间 route 或辅助 schema/readback 探测的 40002 / 40027 / 404 当作最终失败。
169
164
 
170
- **大号 `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`。
165
+ **大号 `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)** 使用 `data query --all --output csv -> Python/pandas`。
171
166
 
172
167
  **命令模板、批量 `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)**。
173
168
 
package/skills/qingflow-cli/reference/data/README.md CHANGED
@@ -10,6 +10,44 @@
10
10
 
11
11
  参数、JSON 文件形状和可选项必须来自当前工具 schema、当次 `--help` 或响应字段能力，不得从其他命令推测。
12
12
 
13
+ ## 响应结构与解析
14
+
15
+ `data query` 的记录位于 `records.items[]`，`data get` 的单条记录位于 `record`。两者的业务值都在各记录的 `fields` 对象中，以十进制 `field_id` 字符串为键；不要从记录顶层按字段 id 取值。
16
+
17
+ `schema.fields[]` 是字段元数据，包含两种结构：系统字段使用 `key` 与 `kind=system`，对应记录顶层的 `record_id/creator/updated_at`；业务字段使用 `field_id/title/data_type/cardinality`，对应记录的 `fields`。按是否包含 `field_id` 识别业务字段（`field_id=0` 也有效），类型读取 `data_type`。子表的列定义在 `children` 中，各行同样以字段 id 字符串为键。
18
+
19
+ 以下是只保留解析所需字段的 query 响应示例：
20
+
21
+ ```json
22
+ {
23
+ "schema": {"fields": [
24
+ {"key": "record_id", "kind": "system"},
25
+ {"field_id": 0, "title": "编号", "data_type": "number", "cardinality": "one"},
26
+ {"field_id": 101, "title": "名称", "data_type": "text", "cardinality": "one"}
27
+ ]},
28
+ "records": {"items": [
29
+ {"record_id": "1", "fields": {"0": 0, "101": "示例"}}
30
+ ]}
31
+ }
32
+ ```
33
+
34
+ JSON 落盘后，先确认记录结构，再按用户目标选择字段；例如只查看首条记录的「名称」：
35
+
36
+ ```python
37
+ field = next(f for f in payload["schema"]["fields"]
38
+ if "field_id" in f and f["title"] == "名称")
39
+ key = str(field["field_id"])
40
+ for record in payload["records"]["items"][:1]:
41
+ values = record["fields"]
42
+ assert isinstance(values, dict), "记录 fields 结构不符合预期"
43
+ if key in values:
44
+ print({"record_id": record["record_id"], "title": field["title"], "value": values[key]})
45
+ else:
46
+ print({"record_id": record["record_id"], "title": field["title"], "returned": False})
47
+ ```
48
+
49
+ 键未返回与值为 `null` 是不同情况；`0` 和 `false` 是有效值，不要用真假判断把它们归为空。结构不符合预期或字段键缺失时，检查同次响应的 schema、`access`、`hints` 与首条记录的结构，必要时对同一记录执行 `data get` 复核；不能把解析失败或未返回字段直接报告为业务数据为空。
50
+
13
51
  ## 字段能力合同
14
52
 
15
53
  1. 首次操作当前应用时，只通过只读 `data query/get` 请求 `include_schema=true`，读取同一次响应中的 `schema` 与递归 `field_capabilities`；不得用 insert/update 探测能力。