@qingflow-tech/qingflow-cli 1.1.60 → 1.1.61-beta.1

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.60
+npm install @qingflow-tech/qingflow-cli@1.1.61-beta.1
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.60 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.1 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.60 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.1 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.60",
+  "version": "1.1.61-beta.1",
   "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.60"
+version = "1.1.61b1"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -34,6 +34,7 @@ dependencies = [
   "python-socketio[client]>=5.11,<6.0",
   "referencing>=0.35,<1.0",
   "redis>=5.0,<6.0",
+  "typing-extensions>=4.12,<5.0",
   "uvicorn>=0.30,<1.0",
 ]
 
@@ -41,6 +42,7 @@ dependencies = [
 dev = [
   "pytest>=8.3,<9.0",
   "respx>=0.22,<1.0",
+  "pymysql>=1.2.2",
 ]
 build = [
   "pyinstaller>=6.0,<7.0",

package/skills/qingflow-cli/SKILL.md

@@ -3,16 +3,54 @@ 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 使用技能
 
-> **Skill 版本**：`qingflow-skills-2026.09.22.01`。CLI 实际版本与安装路径以 `qingflow --json version` 为准。
+> **Skill 版本**：`qingflow-skills-2026.10.09.01`。CLI 实际版本与安装路径以 `qingflow --json version` 为准。
 
 本 Skill 负责 CLI 入口、文件约定和业务分流。已知 `app_key` 时直接执行 `data query/get`。只有应用名称时，先用 `qingflow --json app list --query "应用名称"` 查找当前工作区的可见应用，并核对返回项的 `app_name/title`；目标明确且唯一时取其 `app_key` 再查询，否则请用户确认。不要把应用名称直接传给 `--app-key`，也不要为定位名称转向 builder 或切换工作区。字段能力、权限范围与下一步动作以当前工具 schema、data 响应和 `hints` 为准。
 
-需要向用户交付业务页面入口时，遵循 [Qingflow Common](../qingflow-common/SKILL.md) 的链接规则。
-
+## 关联文件
+
+
+| 文件                                                                                               | 说明                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `manifest.yaml`                                                                                  | 技能清单                                                                                                                                                                                                                                                                                  |
+| [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) | **视图**：先读 schema，一次写一个视图对象；查询面板和按钮约束见该文 |
+| [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`；创建自定义按钮前先 `button get --button-text` 查重复用 |
+| [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 <关键词>`                                                                                                                    |
 ## CLI 执行与 JSON 落盘
 
 1. 已知业务目标时直接执行目标命令，不固定前置 `auth whoami`、`workspace get` 或 `workspace select`。只有业务命令明确返回未登录、会话失效或工作区错误后，才恢复上下文并重试原命令。
@@ -50,7 +88,8 @@ echo "$QINGFLOW_CREDENTIAL" | qingflow --profile default auth use-credential \
 | Excel 模板、文件校验、修复、启动导入与状态 | `qingflow import ...` / `record schema import` | [批量导入 SOP](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) |
 | 应用、表单、字段、视图、报表、门户与流程搭建 | `qingflow builder ...` | [Builder 总导航](./reference/builder/README.md) |
 | 完整数据／流程日志 | `qingflow record logs` | [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md) |
-| 附件、图片与详情页上下文 | `qingflow record get` | [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md) |
+| 记录附件与附件图片下载 | `qingflow data get --download-attachments` | [data 附件下载](./reference/data/README.md#附件下载与读取) |
+| 详情页引用、关联资源与首屏日志上下文 | `qingflow record get` | [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md) |
 | 代码块字段执行 | `qingflow record code-block-run` | [代码集成说明](./reference/builder/code-integrations/README.md) |
 | 安装、版本或命令能力确认 | `qingflow --json version` / `qingflow ... --help` | [命令索引](./reference/00-INDEX.md) |
 
@@ -64,6 +103,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`。再写筛选文件：
@@ -137,9 +247,11 @@ qingflow --json data query \
 
 ## record 专项
 
-`record` 用于完整数据／流程日志、附件和图片上下文、代码块字段执行，以及用户指定的 `record` 操作。
+`record` 用于详情页专项上下文、完整数据／流程日志、代码块字段执行，以及用户指定的 `record` 操作。普通记录附件下载使用 `data get --download-attachments`。
+
+`data query/get` 默认只读取附件字段。用户需要下载或读取附件时，保持相同 profile 和工作区，对已定位的同一 `app_key`、`record_id` 执行 `qingflow --json data get --download-attachments`，保留 schema，并使用 `file_assets.items[].local_path`。该入口直接处理存储 Cookie、重定向和数据面链接刷新，无需 view_id 或 record get。不要用 curl、requests 或 urllib 直接请求远端 Qingflow 附件 URL，也不要为下载而读取认证配置或打印 token。
 
-普通应用数据使用 `data`。不得改用 `record list/access/get/insert/update/delete` 绕过 data 返回的权限、字段能力或校验结果。日志与附件操作阅读 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)；`record delete` 提交不要传 `custom:*`、`list_type`，细则见 [record 删除参考](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md)。
+普通应用数据使用 `data`。不得改用 `record list/access/get/insert/update/delete` 绕过 data 返回的权限、字段能力或校验结果。附件下载阅读 [data 附件下载](./reference/data/README.md#附件下载与读取)；完整日志和详情页专项上下文阅读 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。`record delete` 提交不要传 `custom:*`、`list_type`，细则见 [record 删除参考](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md)。
 
 ## 关联入口
 

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

@@ -2,4 +2,4 @@
 
 普通应用数据查询默认使用 `data query/get`。完整流程、JSON 形状、分页与分析边界见 [core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)。
 
-需要完整日志、附件和图片上下文时，使用 [record 专项参考](./record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。
+需要下载或读取附件时，对已定位的同一 `app_key`、`record_id` 执行 `qingflow --json data get --download-attachments`，保留 schema，使用 `file_assets.items[].local_path`。不需要 view_id，不直接请求远端附件 URL。详见 [data 附件下载](./data/README.md#附件下载与读取)；完整日志见 [record 专项参考](./record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。

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

@@ -45,7 +45,7 @@
 
 直接 query/get/insert/update/delete 统一阅读 [data 操作说明](./data/README.md) 并使用对应 data 工具。最终分析使用 `data query --all --output csv`，按真实响应的 `files[].local_path` 读取全部 CSV 分片。
 
-`record_get` 下载本地附件的规则仅适用于用户明确要求旧 CLI 兼容入口的场景。
+用户需要下载或读取附件时，对已定位的同一 `app_key`、`record_id` 执行 `data get --download-attachments`，读取 `file_assets.items[].local_path`，无需 view_id。下载失败看 `file_assets.warnings`，不直接请求远端附件 URL，详见 [附件下载流程](./data/README.md#附件下载与读取)。
 
 ---
 

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

@@ -22,7 +22,7 @@ package apply/get -> AppForm schema/get/apply per app -> app readback -> workflo
 - Do not call the retired `builder schema apply` or `builder layout apply` routes, and do not use their `add_fields`, `apps-file`, or `form-file` payloads as the current path.
 - For relations, create relation-independent apps first, read back their published `appKey`s, then submit complete declarations using the canonical relation shape and known target app keys.
 - One app may contain multiple `relation` fields when the business model needs them.
-- Relation selectors use the AppForm camelCase shape, not bare strings: write `config.displayField: {"name":"产品编码"}` and `config.visibleFields: [{"name":"产品名称"}]`. `config.targetAppKey` must be a target app key confirmed by readback.
+- Relation selectors use the AppForm camelCase shape, not bare strings: write ordered `config.displayFields: [{"field":{"name":"产品编码"},"auth":"visible"}]` (include hidden items) and `config.twoWayBoundField: {"queId":N}` when the binding is two-way (omit for one-way). `config.targetAppKey` must be a target app key confirmed by readback.
 - 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.
@@ -73,7 +73,7 @@ A complete system is not just several created apps. Before reporting completion,
 
 - Package exists, and its `package_id` is known.
 - Every core business object is a separate app with `app_key`, `app_name`, `icon`, `color`, and exactly one readable data title field.
-- Cross-app relation fields are present where the business model needs them; each relation uses a confirmed `targetAppKey` and object selectors in `config.displayField` / `config.visibleFields`.
+- Cross-app relation fields are present where the business model needs them; each relation uses a confirmed `targetAppKey` and object selectors in `config.displayFields[].field` (+ `twoWayBoundField` for two-way bindings).
 - Core apps were created with complete AppForm declarations, so fields and readable form sections/rows were submitted together.
 - Core operating views exist and their `query_conditions` and `action_buttons` are verified; list-row buttons and detail-page buttons are both configured through the view.
 - Each new app has 5 realistic sample records unless the user explicitly skipped sample data.

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -185,7 +185,7 @@ current CLI payload.
 | 负责人、审批人、参与人 | `member` | 不要创建“申请人/提交人”等平台系统字段 |
 | 部门、组织 | `department` | 可按需要补 `config.departmentScope` |
 | 图片、文件、附件 | `attachment` | 只有顶层 `attachment` 可被应用级 `dataCoverField` 选择 |
-| 跨应用业务对象关系 | `relation` | 使用已确认的 `targetAppKey`；`displayField` / `visibleFields` 必须写对象选择器 |
+| 跨应用业务对象关系 | `relation` | 使用已确认的 `targetAppKey`；展示字段写有序 `displayFields[]`（含 `auth`），双向绑定写 `twoWayBoundField`；旧 `displayField`/`visibleFields` 兼容窗口内仍可读 |
 
 禁止创建平台系统字段：`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。需要引用系统字段时，只在工具明确支持的位置引用，例如按钮 `source_field: "数据ID"`。
 
@@ -243,7 +243,7 @@ current CLI payload.
 |--------|----------|-----------------|
 | 标量与选择器 | `name` + `questionType`（+ 业务 `beingRequired` 等） | `questionDescription`、`beingRequired`；数据标题和封面在应用级 `dataTitleField/dataCoverField` 中选择；**`single_select` / `multi_select` 的 `config.options` 是非空字符串数组**，如 `["A", "B"]` |
 | `department` | 同左 | **`config.departmentScope`**：`mode: all \| custom`；`custom` 时 **`departments[]`**（含 `deptId` 等） |
-| `relation` | **`targetAppKey`**；另需 **`displayField`**、**`visibleFields[]`** | **`relationMode`**；目标应用元数据不可读时先读已发布表单，不要猜目标 key |
+| `relation` | **`targetAppKey`**；另需 **`displayFields[]`**（含 `field`+`auth`；可为空列表——空 = 双向绑定未配展示字段的存量形态，round-trip 空↔空稳定；与旧形态不可混用、条目 queId 不可重复） | **`relationMode`**；双向绑定加 **`twoWayBoundField`**（省略 = 单向）；目标应用元数据不可读时先读已发布表单，不要猜目标 key |
 | `subtable` | **`subfields[]` 非空** | 子列递归同父级规则；使用 Schema 返回的 camelCase 子字段配置 |
 | `q_linker` | **`config.qLinkerBinding`**：`inputs`、`request`、**`outputs[]` 每项须含 `targetField`**（能解析到本表单字段） | `request.url` 等须符合**租户/后端远程查询策略**；以字段类型 Schema 返回的配置为准 |
 | `code_block` | **`config.codeBlockBinding`**：`inputs`、`code`、**`outputs[]` + `targetField`**；配置 outputs 时，代码必须显式写 **`qf_output = {...}`**，仅 `return {...}` 不会产生可回写结果，且每个 `outputs[].path` 必须从 `qf_output` 取值 | 以字段类型 Schema 返回的 camelCase 配置为准 |
@@ -265,13 +265,17 @@ current CLI payload.
   "config": {
     "targetAppKey": "PRODUCT_APP_KEY",
     "relationMode": "single",
-    "displayField": {"name": "产品编码"},
-    "visibleFields": [{"name": "产品名称"}, {"name": "产品线"}]
+    "twoWayBoundField": {"name": "产品编码"},
+    "displayFields": [
+      {"field": {"name": "产品编码"}, "auth": "visible"},
+      {"field": {"name": "产品名称"}, "auth": "hidden"},
+      {"field": {"name": "产品线"}, "auth": "visible"}
+    ]
   }
 }
 ```
 
-只在目标应用已经创建并通过 readback 确认后填写 `targetAppKey`。如果返回选择器校验错误，修复 `config.displayField` / `config.visibleFields`，不要重建应用或改 `appKey`。
+只在目标应用已经创建并通过 readback 确认后填写 `targetAppKey`。如果返回选择器校验错误，修复 `config.displayFields[].field` / `config.twoWayBoundField`，不要重建应用或改 `appKey`。旧形态 `displayField`/`visibleFields` 在兼容窗口内仍可读（displayField 同时视为双向绑定目标），新声明一律用 `displayFields`。
 
 引用字段的公式默认值写在 `config.defaultValueFormula`，表达式必须符合固定版本 `relation` 字段详情中的 `FormulaExpression`。不要把后端 `referenceConfig` 字段名或其他 Schema 版本的公式写法直接放进声明。
 

package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md

@@ -201,8 +201,8 @@ qingflow builder schema apply \
 - 如果返回 `MULTI_APP_STATIC_VALIDATION_FAILED`，读取 `details.issues[]` 的 `path/error_code/fix_hint` 修 payload；这是写入前失败，通常可以修正后重试，不需要 readback。
 - 多应用 schema apply 不做事务回滚；如果部分失败，只补失败的 `apps[].row_number`，不要整批重复提交。
 - 这个模式只负责应用壳与字段；视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
-- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayField`、`config.visibleFields`，并使用已确认的真实 app key。
-- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`，不要提交旧 `update_fields` patch。
+- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayFields[]`（含 `auth`）、`config.twoWayBoundField`，并使用已确认的真实 app key。
+- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`，不要提交旧 `update_fields` patch。
 - 一个应用可以包含多个 `relation` 字段；不要因为 relation 数量超过 1 就降级成文本。若真实写入失败或 relation readback mismatch，只按实际错误和 `details.relation_repair_plan[]` 做最小修复。
 - 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时，先按 §3.4 读回，不要直接拆成单应用创建。
 
@@ -349,7 +349,7 @@ qingflow builder flow apply \
 | **`address`** | 地址复合字段。 |
 | **`attachment`** | 附件。 |
 | **`boolean`** | 是否。 |
-| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`。 |
+| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`。 |
 | **`subtable`** | 当前 AppForm 使用 `subfields[]` 及 Schema 返回的 camelCase 配置；旧 `subfield_updates` 只作迁移线索。 |
 | **`q_linker`** | 当前 AppForm 使用 `config.qLinkerBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
 | **`code_block`** | 当前 AppForm 使用 `config.codeBlockBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md

@@ -2,7 +2,7 @@
 
 > **用途**：使用视图无关的 `data query/get` 完成普通应用数据查询、筛选、排序、分页和单条读取。
 > **边界**：本文只给流程与 JSON 形状；操作符、字段类型、权限范围和动态限制以当前 `--help`、`schema`、`field_capabilities`、`access` 与 `hints` 为准。
-> **record 专项**：需要完整日志、附件／图片上下文时，阅读 [record 专项参考](../record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。
+> **附件**：需要下载记录附件时，使用 [data 附件下载](../data/README.md#附件下载与读取)。完整日志和详情页专项上下文见 [record 专项参考](../record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。
 
 ## 推荐顺序
 
@@ -96,7 +96,7 @@ qingflow --json data get --app-key APP_KEY --record-id RECORD_ID \
   > tmp/qingflow_data_get.json
 ```
 
-`data get` 用于普通单条业务数据。若用户需要详情页附件、图片或完整数据／流程日志，切换到 record 专项，不要把它们误写成 data get 的默认合同。
+`data get` 默认只读取业务字段。需要下载或读取附件时，对同一 `app_key`、`record_id` 加 `--download-attachments`，保留 schema，并读取 `file_assets.items[].local_path`；无需 view_id 或 record get。不要用 Python/curl 直接请求远端附件 URL。状态、预算与完整流程见 [附件下载与读取](../data/README.md#附件下载与读取)；完整日志按 record 专项执行。
 
 ## 6. 统计分析
 

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md

@@ -45,7 +45,7 @@
 
 直接 query/get/insert/update/delete 统一阅读 [data 操作说明](../data/README.md) 并使用对应 data 工具。最终分析使用 `data query --all --output csv`，按真实响应的 `files[].local_path` 读取全部 CSV 分片。
 
-`record_get` 下载本地附件的规则仅适用于用户明确要求旧 CLI 兼容入口的场景。
+用户需要下载或读取附件时，对已定位的同一 `app_key`、`record_id` 执行 `data get --download-attachments`，读取 `file_assets.items[].local_path`，无需 view_id。下载失败看 `file_assets.warnings`，不直接请求远端附件 URL，详见 [附件下载流程](../data/README.md#附件下载与读取)。
 
 ---
 

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

@@ -25,8 +25,28 @@
 - 返回后先检查 `write_executed`、`retry_safe`、字段错误和 hints。已执行、部分成功或状态不明时不得重放原请求。
 - data 命令失败时只修正响应明确指出的问题，不得切换其他数据入口绕过权限或校验。
 
+## 附件下载与读取
+
+`data query/get` 默认只返回业务字段，不下载远端附件。需要下载、打开或读取附件时，先定位目标记录，保持相同 profile 和工作区执行：
+
+```bash
+mkdir -p tmp
+qingflow --json data get --app-key APP_KEY --record-id RECORD_ID --download-attachments \
+  > tmp/qingflow_data_files.json
+```
+
+- MCP 等价入口是 `data_get(download_attachments=true)`。下载需要 `include_schema=true`，CLI 不要同时使用 `--no-schema`。
+- 下载仅扫描数据面实际可见且 schema 类型为 attachment 的字段，包括子表附件；附件图片与 `.mp4` 视频都通过 `file_assets` 返回。只读链接、富文本或隐藏字段不会被当作附件下载目标。
+- 从 `file_assets.items[]` 按 `field_id`、`source_path` 和 `file_name` 定位文件；仅当 `access_status=downloaded` 且 `local_path` 非空时使用本地路径。新入口只下载原文件，不做文本提取，视频不需要文本提取也可下载成功。
+- `file_assets.status` 为 `ok/none/partial`。记录读取成功不代表全部附件下载成功；`blocked_private_url`、`download_failed`、`too_large` 或 `skipped_limit` 时读取 `file_assets.warnings`，不要把远端 URL 当作已下载文件。
+- 本次下载最多 50 个文件，单文件 50 MiB、总计 200 MiB；接收过程中达到大小限制即停止，超限文件不落盘。55 秒后不再启动新附件下载，已启动的请求受 HTTP 超时限制。默认目录为 `~/.qingflow-mcp/data-files/<run_id>/`，可用 `QINGFLOW_MCP_DATA_FILES_HOME` 调整。
+- CLI/MCP 沿用旧链路的存储 Cookie 与重定向处理，不额外拦截首次下载地址的 origin；401/403 时最多通过同一数据面 get 刷新一次记录，按字段 ID 和文件名取首个仍可见的匹配附件，允许 URL 变化；不访问旧 record/detail 或 decryptedFileUrl 接口，不需要 view_id/listType。
+- 同一字段内的同名附件取首个匹配项，刷新时不比较 URL 路径或查询参数。
+- 不直接用 curl、requests 或 urllib 请求远端私有附件，也不读取认证配置或打印 token。
+
 ## 任务分流
 
+- 附件下载或读取：按上节使用 `data get --download-attachments` 和返回的本地路径。
 - 批量导入：阅读 [批量导入 SOP](../record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)。
 - 统计分析：阅读 [数据分析说明](../record/analysis/README.md)，使用 `data query --all --output csv` 并读取全部 CSV 分片。
 - 待办和流程动作：阅读 [任务上下文 SOP](../task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)。

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md

@@ -1,6 +1,6 @@
 # Qingflow CLI：record 日志与附件参考
 
-> **适用范围**：任务需要完整数据／流程日志、附件或图片上下文时使用。普通应用数据查询使用 [`data query/get`](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)。
+> **适用范围**：任务需要完整数据／流程日志、详情页引用和关联资源上下文，或用户指定 record 兼容入口时使用。普通应用数据查询使用 [`data query/get`](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)，附件下载使用 [data 附件下载](../data/README.md#附件下载与读取)。
 
 ## record 查询链
 
@@ -14,6 +14,8 @@ app get（解析 accessible_views，选定 VIEW_ID）
 
 ## 命令形状
 
+普通记录附件下载使用 `data get --download-attachments`。以下 record 命令只用于详情页专项上下文或用户明确指定的兼容入口；不要把它们当作 data 权限错误的回退。
+
 ```bash
 qingflow --json app get --app-key APP_KEY > tmp/qingflow_app_get.json
 
@@ -42,6 +44,10 @@ qingflow --json record logs \
 - `record logs`：用于完整可见数据日志和流程日志。响应只读取摘要与 JSONL 文件路径，按需筛选本地文件，不把全文放入上下文。
 - `record list`：只在用户明确指定该命令时用于样本浏览／模糊定位，不用于完整统计结论。
 
+## 附件下载与读取
+
+普通附件下载在 `data get --download-attachments` 中完成，参数、状态与预算见 [data 附件下载](../data/README.md#附件下载与读取)。如果用户明确使用 record 详情页兼容入口，继续使用其返回的本地资产；`extraction.status=unsupported` 不代表下载失败。
+
 ## 边界
 
 - 统计分析仍转 `data query --all --output csv -> Python/pandas`。

package/skills/qingflow-common/SKILL.md

@@ -20,7 +20,7 @@ Do not require both surfaces. If only one is installed, complete the workflow on
 
 - **AppForm** is the versioned declarative definition for an application form: app metadata, fields, sections, layout, settings, and field configuration. The same JSON declaration is used by CLI and Qingflow MCP.
 - **Data** 是既有应用中的普通业务数据。查询、单条读取和直接增删改默认使用视图无关的 data 入口，并以当次 schema、字段能力和访问范围为准。
-- **Record** 用于详情页附件／图片、完整日志、导入、代码块，以及用户明确指定的 record 命令；不要把普通应用数据工作路由到 record。
+- **Record** 用于详情页专项上下文、完整日志、导入、代码块，以及用户明确指定的 record 命令；普通应用数据与记录附件下载使用 data。
 - **Task** is a workflow work item. Prefer task operations for approval, transfer, rollback, and assignee actions.
 - **Builder resource** is package, app, view, chart, portal, navigation, or workflow configuration. It is separate from record data.
 - **Schema version** is part of the public contract. Pin it for one AppForm or workflow operation and do not combine values from different versions.
@@ -32,13 +32,16 @@ Do not require both surfaces. If only one is installed, complete the workflow on
 | Form schema/read/apply/delete | `qingflow --json builder app-form ...` / `builder app delete` | `app_form_schema`, `app_form_get`, `app_form_apply`, `app_delete` |
 | AppForm static validation | `qingflow --json builder app-form validate --file ...` | Performed inside `app_form_apply`; no separate tool |
 | 普通应用数据查询与直接增删改 | `qingflow --json data ...` | Qingflow MCP `data_query/get/insert/update/delete` |
-| 日志、附件、导入、代码块或用户指定的 record 命令 | `qingflow --json record ...` / `import ...` | Qingflow MCP 对应 record/import 专项工具 |
+| 记录附件下载 | `qingflow --json data get --download-attachments` | `data_get(download_attachments=true)` |
+| 日志、详情页专项上下文、导入、代码块或用户指定的 record 命令 | `qingflow --json record ...` / `import ...` | Qingflow MCP 对应 record/import 专项工具 |
 | 待办与流程动作 | `qingflow --json task ...` | Qingflow MCP task tools |
 | 免登录打开网页或指定业务页面 | `qingflow --json auth login-link [--redirect-path PATH]` | `get_login_link` |
 | Package, view, portal, chart, workflow | `qingflow --json builder ...` | Qingflow MCP configuration tools |
 
 The operation names and payload schemas are defined by the public surface. Use the current Schema or tool input schema as the source of truth, not another command's shape or a backend payload.
 
+用户需要下载或读取附件时，先用 data 定位记录，保持相同身份与工作区，对同一 `app_key`、`record_id` 调用 CLI `data get --download-attachments` 或 MCP `data_get(download_attachments=true)`，保留 schema，使用 `file_assets.items[].local_path`。附件图片与视频同样适用；新入口只下载原文件，不做文本提取。以 `access_status=downloaded` 和非空本地路径判断成功，部分失败看 `file_assets.warnings`。无需 view_id 或 record_get，也不要为下载而读取认证配置、打印 token 或用 Python/curl 直接请求远端 URL。
+
 ## Package Boundaries
 
 - `@qingflow-tech/qingflow-cli` packages CLI execution guidance and CLI-supported workflows.

package/src/qingflow_mcp/app_form_compat.py

@@ -10,6 +10,9 @@ from .json_types import JSONObject
 TYPE_ALIASES = {
     "multiline": "long_text",
     "textarea": "long_text",
+    "richtext": "rich_text",
+    "rich-text": "rich_text",
+    "rich_text": "rich_text",
     "radio": "single_choice",
     "boolean": "single_choice",
     "select": "single_select",