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

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.61-beta.3
+npm install @qingflow-tech/qingflow-cli@1.1.61-beta.4
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.3 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.4 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.3 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.4 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

package/package.json

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

package/pyproject.toml

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

package/skills/qingflow-cli/SKILL.md

@@ -14,6 +14,8 @@ description: |
 
 本 Skill 负责 CLI 入口、文件约定和业务分流。已知 `app_key` 时直接执行 `data query/get`。只有应用名称时，先用 `qingflow --json app list --query "应用名称"` 查找当前工作区的可见应用，并核对返回项的 `app_name/title`；目标明确且唯一时取其 `app_key` 再查询，否则请用户确认。不要把应用名称直接传给 `--app-key`，也不要为定位名称转向 builder 或切换工作区。字段能力、权限范围与下一步动作以当前工具 schema、data 响应和 `hints` 为准。
 
+首次解析 `data query/get` 响应前，阅读 [data 响应结构与解析](./reference/data/README.md#响应结构与解析)，按同次响应中的 schema 与记录结构读取目标字段。
+
 ## 关联文件
 
 

package/skills/qingflow-cli/reference/data/README.md

@@ -10,6 +10,44 @@
 
 参数、JSON 文件形状和可选项必须来自当前工具 schema、当次 `--help` 或响应字段能力，不得从其他命令推测。
 
+## 响应结构与解析
+
+`data query` 的记录位于 `records.items[]`，`data get` 的单条记录位于 `record`。两者的业务值都在各记录的 `fields` 对象中，以十进制 `field_id` 字符串为键；不要从记录顶层按字段 id 取值。
+
+`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 字符串为键。
+
+以下是只保留解析所需字段的 query 响应示例：
+
+```json
+{
+  "schema": {"fields": [
+    {"key": "record_id", "kind": "system"},
+    {"field_id": 0, "title": "编号", "data_type": "number", "cardinality": "one"},
+    {"field_id": 101, "title": "名称", "data_type": "text", "cardinality": "one"}
+  ]},
+  "records": {"items": [
+    {"record_id": "1", "fields": {"0": 0, "101": "示例"}}
+  ]}
+}
+```
+
+JSON 落盘后，先确认记录结构，再按用户目标选择字段；例如只查看首条记录的「名称」：
+
+```python
+field = next(f for f in payload["schema"]["fields"]
+             if "field_id" in f and f["title"] == "名称")
+key = str(field["field_id"])
+for record in payload["records"]["items"][:1]:
+    values = record["fields"]
+    assert isinstance(values, dict), "记录 fields 结构不符合预期"
+    if key in values:
+        print({"record_id": record["record_id"], "title": field["title"], "value": values[key]})
+    else:
+        print({"record_id": record["record_id"], "title": field["title"], "returned": False})
+```
+
+键未返回与值为 `null` 是不同情况；`0` 和 `false` 是有效值，不要用真假判断把它们归为空。结构不符合预期或字段键缺失时，检查同次响应的 schema、`access`、`hints` 与首条记录的结构，必要时对同一记录执行 `data get` 复核；不能把解析失败或未返回字段直接报告为业务数据为空。
+
 ## 字段能力合同
 
 1. 首次操作当前应用时，只通过只读 `data query/get` 请求 `include_schema=true`，读取同一次响应中的 `schema` 与递归 `field_capabilities`；不得用 insert/update 探测能力。