@qingflow-tech/qingflow-cli 1.1.50-beta.2 → 1.1.50-beta.3

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.50-beta.2
+npm install @qingflow-tech/qingflow-cli@1.1.50-beta.3
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.50-beta.2 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.50-beta.3 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.50-beta.2 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.50-beta.3 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.50-beta.2",
+  "version": "1.1.50-beta.3",
   "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.50b2"
+version = "1.1.50b3"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -32,6 +32,7 @@ dependencies = [
   "pycryptodome>=3.20,<4.0",
   "pypdf>=5.0,<6.0",
   "python-socketio[client]>=5.11,<6.0",
+  "referencing>=0.35,<1.0",
   "redis>=5.0,<6.0",
   "uvicorn>=0.30,<1.0",
 ]
@@ -64,7 +65,11 @@ Issues = "https://github.com/qingflow/qingflow-mcp/issues"
 where = ["src"]
 
 [tool.setuptools.package-data]
-qingflow_mcp = ["py.typed", "builder_facade/schemas/app_form/**/*.json"]
+qingflow_mcp = [
+  "py.typed",
+  "builder_facade/schemas/app_form/**/*.json",
+  "builder_facade/schemas/views/**/*.json",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

package/skills/qingflow-cli/SKILL.md

@@ -3,6 +3,9 @@ name: qingflow-cli
 description: |
   【强制】在执行或编排任何 qingflow CLI 命令前必须优先加载本 Skill。
   Qingflow CLI 主入口：规定命令执行与 JSON 落盘方式，并把普通应用数据默认路由到 data；task、builder、import、日志、附件和代码块按专项参考执行。
+  Qingflow CLI 包以本 Skill 作为 CLI 主入口；record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。
+  指导安装、执行上下文失败恢复、查询与写入；规定 task/record/import/builder 查询落盘；覆盖普通成员读数、字段 kind 与数据形态、任务上下文、批量导入、record access/list/get/insert/update/delete 与管理端边界。
+  Builder SOP 按智能体任务路径组织：完整系统、单应用、AppForm、视图、报表、门户、关联资源、流程、发布校验；表单字段、分组、布局和应用设置统一使用 versioned AppForm；按钮随视图 action_buttons 声明；更新动作并入对应资源文档，批量读/批量写/局部改依各资源契约执行；视图 apply 每次仅处理一个视图的一种操作，不支持批量创建或混合操作；明细见「关联文件」表与文末命令索引。
 ---
 
 # Qingflow CLI 使用技能
@@ -62,6 +65,77 @@ echo "$QINGFLOW_CREDENTIAL" | qingflow --profile default auth use-credential \
 qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
 ```
 
+常用参数：`--credential-stdin`、`--password-stdin`、`--persist` / `--forget-persisted`；详见 `qingflow auth --help`。
+
+---
+
+## 输出落盘规则（task / record / import / builder 查询类）
+
+以下 **必须** 将标准输出重定向到文件（如 `tmp/qingflow_*.json`），**禁止**把终端大 JSON 直接交给 LLM；后续用读文件 / 脚本处理。
+
+
+| 子系统        | 必须落盘的子命令                                                                                                                                                            |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **task**   | `list`、`get`、`log`、`report`                                                                                                                                         |
+| **import** | `template`、`verify`、`repair`、`start`、`status`（**`verify` / `start` 链依赖本机 `~/.qingflow-mcp` 校验/任务落盘，自动化须开放写权限**） |
+| **builder** | **`app get`（summary/app map、fields、layout、views、flow、charts；summary 含 `custom_buttons` / `associated_resources`）**、`contract`、`app-form schema/get/validate/apply`；以及 **`views schema/get/validate/apply` / `button apply` / `associated-resource apply` / `flow apply` / `charts apply` / `portal apply` / `portal delete` / `publish verify` / `package apply`** 等大 JSON 响应 |
+| **record** | `list`、`get`、`logs`、`access`、`schema browse`；以及 `schema insert` / `schema update` / `schema import` / `schema code-block` 等大体积 schema 子命令（体量大时同上）；**创建前列字段时用 `schema insert` / `record_insert_schema_get` 同上**；**写操作 `insert` / `update` 响应体大时同样建议落盘** |
+
+
+**规则摘要**
+
+- 重定向示例：`qingflow --json record list … > tmp/qingflow_records.json`
+- 线上真实测试、子智能体并行任务、批量 `--*-file` 入参优先使用**绝对路径**，或在命令前固定确认 `pwd`；不要假设子智能体当前目录与主线程一致。
+- `auth`、`workspace`、`app`、`portal`、`view`、**非上述列出的**等，可直接终端查看或按需落盘。
+- 错误在使用 **`--json`** 时多在 **stdout** 的 JSON 信封里；stderr 多为 argparse usage。
+
+---
+
+## 应用记录：获取数据工作流（推荐闭环）
+
+与常见 **编排/API 文档**里的命名对齐时的固定顺序为：
+
+1. **`app_get`**：`qingflow --json app get --app-key <APP_KEY>` → 在 **`data.accessible_views`**（或等价路径）选取 **`view_id`**。
+2. **`record_schema_get`（`schema_mode=browse`）**：`qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>`（CLI 子命令 **`browse`** 即浏览视图表结构）。
+3. **`record_list` / `record_get` / `record_logs_get`**：`record list …` 用于样本浏览或模糊定位候选；`record get --record-id …` 下钻单条前端详情页首屏上下文（字段、首屏日志、引用、图片与文件资产）；只有需要完整审计历史时，再用 `record logs --record-id …` 读取全量数据日志和流程日志 JSONL。
+
+`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/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**（编写前已对当前 CLI **实跑**校验）。若仅需「最快看一眼有没有行」，可省略 **`schema browse`**，直接走下文「最短路径」。如果用户要任何最终统计结论、分析报告、趋势/排名/比例/分布，按 **[record/analysis](./reference/record/analysis/README.md)** 执行 `record access -> Python/pandas`。
+
+---
+
+## 应用记录：创建记录工作流（申请节点 → 写入）
+
+推荐顺序：
+
+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/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**。
+
+---
+
+## 应用记录：更新记录工作流（详情 → 写入）
+
+主链路是先读详情，再直接提交用户要求修改的 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 对象（标题 → 值）。字段必须来自当前详情上下文的 `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/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/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 管理权限链路。
+
+**部门名筛选 / 写入**：`record list/access/analyze/insert/update` 遇到部门字段时可直接传部门名或候选对象；CLI 会优先走成员可见的目录搜索解析部门。不要先用通讯录管理接口查询部门 id，否则普通成员容易被 ContactAuth 错误阻挡。
 ### 字段筛选
 
 先运行一次不带 `columns` 的 query，从返回的 `schema` 与递归 `field_capabilities` 准确定位 `field_id`，并确认该字段暴露的 `filter_operators` 与 `value_shape`。再写筛选文件：

package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md

@@ -7,19 +7,15 @@ This file is kept only for old cross-links. Use the current canonical document i
 Current main path:
 
 ```bash
-qingflow builder views apply --views-file /abs/path/views.json
+qingflow builder views apply --app-key APP_KEY --view-file /abs/path/view.json
 ```
 
-Use one top-level `views[]` array. Each item carries its own `app_key` and `operation`.
+Use `--app-key APP_KEY --view-file /abs/path/view.json`. The file contains one direct view object.
 
 Minimum current shape:
 
 ```json
 {
-  "views": [
-    {
-      "operation": "upsert",
-      "app_key": "APP_KEY",
       "name": "订单跟进视图",
       "type": "table",
       "columns": ["订单编号", "客户名称", "状态", "负责人"],
@@ -50,9 +46,7 @@ Minimum current shape:
           ]
         }
       ]
-    }
-  ]
 }
 ```
 
-Do not use the old `--app-key + --upsert-views-file / --patch-views-file / --remove-views-file` shape as the normal agent path.
+Each `builder views apply` call handles one operation on one view: pass one `--view-file`, one-item `patch_views`, or one-item `remove_views`; do not combine these operation modes.

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

@@ -26,6 +26,7 @@ package apply/get -> AppForm schema/get/apply per app -> app readback -> workflo
 - If AppForm apply times out or returns uncertain write state, perform draft/published form readback before retrying. Do not recreate apps with `V2`, `测试`, or random suffixes.
 - If a same/similar package or app set already exists and the user did not say whether to extend, repair, replace, or create new, stop and ask. Do not start probing with new names.
 - If readback shows part of the requested system already exists, list existing apps/fields/views/charts/portal, identify gaps, and patch only the missing or incorrect slices.
+- `builder views apply` is declarative and handles one view operation per call. When a system needs multiple views, submit each view in a separate call; do not send batch view declarations.
 - Do not create default views such as `全部数据` or `我的数据`; those are platform defaults.
 - New business views must include `query_conditions`; do not create business views that only define columns, filters, and buttons but lack a frontend query panel.
 - New business views must include shortcut buttons through `action_buttons`; every core operating view must configure both `placement: "list"` and `placement: "detail"` buttons. Do not create core operating views that only contain columns and filters.