@qingflow-tech/qingflow-cli 1.1.61 → 1.1.62

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 (81) hide show
  1. package/README.md +3 -3
  2. package/package.json +1 -1
  3. package/pyproject.toml +3 -1
  4. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +1 -1
  5. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +6 -258
  6. package/skills/qingflow-cli/reference/builder/20-build-complete-system.md +2 -2
  7. package/skills/qingflow-cli/reference/builder/30-schema-fields.md +22 -5
  8. package/skills/qingflow-cli/reference/builder/70-portal.md +71 -36
  9. package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md +3 -3
  10. package/skills/qingflow-cli/reference/examples/portal/portal_apply_v1alpha1.example.json +100 -0
  11. package/skills/qingflow-cli/reference/examples/portal/portal_sections_all_types.example.json +6 -7
  12. package/src/qingflow_mcp/app_form_compat.py +3 -0
  13. package/src/qingflow_mcp/app_form_validator.py +89 -20
  14. package/src/qingflow_mcp/builder_facade/app_form.py +629 -112
  15. package/src/qingflow_mcp/builder_facade/models.py +197 -15
  16. package/src/qingflow_mcp/builder_facade/portals_schema.py +397 -0
  17. package/src/qingflow_mcp/builder_facade/schemas/app_form/manifest.json +15 -1
  18. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/complete.json +112 -38
  19. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/address.json +31 -8
  20. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_classification.json +146 -0
  21. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_extraction.json +146 -0
  22. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_generation.json +146 -0
  23. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_document_parsing.json +146 -0
  24. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_generation.json +146 -0
  25. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_recognition.json +146 -0
  26. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_machine_translation.json +146 -0
  27. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_text_summary.json +146 -0
  28. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/amount.json +6 -10
  29. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/attachment.json +33 -10
  30. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/code_block.json +6 -10
  31. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/data_relation.json +11 -18
  32. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date.json +4 -8
  33. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date_duration.json +146 -0
  34. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/datetime.json +4 -8
  35. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/department.json +6 -10
  36. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/email.json +4 -8
  37. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/embed_field.json +146 -0
  38. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/image_select.json +146 -0
  39. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/link.json +4 -8
  40. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/location.json +146 -0
  41. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/long_text.json +4 -8
  42. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/member.json +6 -10
  43. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/multi_select.json +4 -8
  44. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/number.json +6 -10
  45. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ocr.json +146 -0
  46. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/phone.json +4 -8
  47. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/q_linker.json +8 -12
  48. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/relation.json +73 -15
  49. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/rich_text.json +146 -0
  50. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_choice.json +4 -8
  51. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_select.json +4 -8
  52. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/subtable.json +90 -29
  53. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/text.json +4 -8
  54. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/formula.json +43 -0
  55. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/summary.json +27 -19
  56. package/src/qingflow_mcp/builder_facade/schemas/portals/manifest.json +59 -0
  57. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/complete.json +1397 -0
  58. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/carousel.json +193 -0
  59. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/chart.json +643 -0
  60. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/favourite.json +203 -0
  61. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/filter.json +249 -0
  62. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/grid.json +265 -0
  63. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/link.json +131 -0
  64. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/task.json +199 -0
  65. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/text.json +123 -0
  66. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/view.json +196 -0
  67. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/summary.json +800 -0
  68. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/complete.json +1 -1
  69. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/display.json +1 -1
  70. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/summary.json +1 -1
  71. package/src/qingflow_mcp/builder_facade/service.py +1359 -92
  72. package/src/qingflow_mcp/cli/commands/builder.py +120 -5
  73. package/src/qingflow_mcp/public_surface.py +2 -0
  74. package/src/qingflow_mcp/server_app_builder.py +34 -5
  75. package/src/qingflow_mcp/session_store.py +14 -1
  76. package/src/qingflow_mcp/solution/compiler/icon_utils.py +73 -0
  77. package/src/qingflow_mcp/solution/executor.py +5 -2
  78. package/src/qingflow_mcp/tools/ai_builder_tools.py +118 -20
  79. package/src/qingflow_mcp/tools/portal_tools.py +4 -54
  80. package/src/qingflow_mcp/tools/portal_writer.py +59 -0
  81. package/src/qingflow_mcp/tools/solution_tools.py +2 -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
10
+ npm install @qingflow-tech/qingflow-cli@1.1.62
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 qingflow
24
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.62 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 qingflow-skills install --agent codex --scope user --copy
65
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.62 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",
3
+ "version": "1.1.62",
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.61"
7
+ version = "1.1.62"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -42,6 +42,7 @@ dependencies = [
42
42
  dev = [
43
43
  "pytest>=8.3,<9.0",
44
44
  "respx>=0.22,<1.0",
45
+ "pymysql>=1.2.2",
45
46
  ]
46
47
  build = [
47
48
  "pyinstaller>=6.0,<7.0",
@@ -69,6 +70,7 @@ qingflow_mcp = [
69
70
  "py.typed",
70
71
  "builder_facade/schemas/app_form/**/*.json",
71
72
  "builder_facade/schemas/views/**/*.json",
73
+ "builder_facade/schemas/portals/**/*.json",
72
74
  ]
73
75
 
74
76
  [tool.pytest.ini_options]
@@ -233,5 +233,5 @@ CLI 对外推荐使用 **`group_by` + `metric(s)`**;旧的 **`dimension_field_
233
233
 
234
234
  - [SKILL.md](../SKILL.md)
235
235
  - [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)
236
- - [QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)(**`chart_ref`**)
236
+ - [builder/70-portal.md](./builder/70-portal.md)(门户声明式主链与 **`chart` / `chart_ref`** 用法)
237
237
  - [QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)(成员侧 **`kind`** 与搭建 **`type`** 对照理解业务)
@@ -1,263 +1,11 @@
1
- # Builder 门户创建与变更 SOP:`qingflow builder portal`
1
+ # Builder Portal Workflow
2
2
 
3
- 搭建侧稳定入口:**`qingflow builder portal`**:`list` / `get` / **`apply`** / **`delete`**(与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同,见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**)。
4
-
5
- 实现要点来自 CLI 打包内的 `builder_facade/models.py`(`PortalApplyRequest`、`PortalSectionPatch`)、`builder_facade/service.py`(`portal_apply` / `portal_delete`)、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**:**新建**(`--no-publish`)、**`--publish` 更新**(网关 **503** 恢复后已重试成功)、**五类区块可稳定落库**;**`filter`(`type:6`)经 CLI 直传未落库** 见 **§3.4 / §8**。另已对测试包 **`1414907`** 实跑 **`portal delete`**:临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
6
-
7
- > **权限**:**更新**需 **`edit_portal`**;**新建**按后端 `DashCtrl.createDash` 链路只预检目标包 **`add_app`**,不额外要求包 **`edit_app`**。失败时参见主技能与 **ADMIN** 速查。
8
-
9
- > **契约**:`qingflow --json builder contract --tool-name portal_apply`;删除契约:`qingflow --json builder contract --tool-name portal_delete`
10
-
11
- ---
12
-
13
- ## 1. 读:`list` → `get`
3
+ 旧文已并入 [builder/70-portal.md](./builder/70-portal.md)。门户创建/更新走声明式主链(版本化 `--file` 声明 + 离线 validate + 唯一 apply 入口):
14
4
 
15
5
  ```bash
16
- qingflow --json builder portal list > tmp/builder_portal_list.json
17
-
18
- qingflow --json builder portal get --dash-key "<DASH_KEY>" > tmp/builder_portal_get.json
19
- qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
20
- ```
21
-
22
- - **`list`** 可能带 **`PORTAL_PERMISSION_READ_UNAVAILABLE`**,**`verified: false`** 仍可能有可用 **`items[]`**。
23
- - **`get`**:**`--dash-key`** 必填;默认 **`--being-draft`** 为草稿。
24
-
25
- ---
26
-
27
- ## 2. 写:`apply` 两种模式(互斥)
28
-
29
- **不可同时**出现 **`--dash-key`** 与 **`--package-id`**。
30
-
31
- | 模式 | 必备参数 | 含义 |
32
- |------|----------|------|
33
- | **新建** | **`--package-id`** + **`--dash-name`** | **`--sections-file` 须非空**。 |
34
- | **更新** | **`--dash-key`** | 不要带 **`package_id`**。 |
35
-
36
- | 参数 | 说明 |
37
- |------|------|
38
- | **`--publish` / `--no-publish`** | 默认 **`--publish`**。仅 **`--no-publish`** 时不会调用发布接口;契约说明 **`publish=false` 不宣称线上已变**。 |
39
- | **`--payload-file`** | 完整门户 JSON 对象;**标准字段写 `dash_name`**。新版 CLI 兼容 **`name -> dash_name`**、单页 **`pages[0].components -> sections`**,但 agent 默认不要依赖兼容别名。 |
40
- | **`--sections-file`** | JSON **数组**;**全量替换**。省略时仅改基础信息,且 **`hide_copyright` / `dash_global_config` / `config`** 不能单独提交(**`PORTAL_SECTIONS_REQUIRED`**)。 |
41
- | **`--layout-preset`** | 可选:**`auto` / `dashboard_2col` / `dashboard_3col`**。当区块未显式写 **`position`** 时由工具生成大屏布局。 |
42
- | **`--visibility-file`** | 与 **`--auth-file`** 不能同时用。 |
43
- | **`--icon`** / **`--color`** | 新建门户必须显式传合法的非 `template` 图标和颜色;候选用 `qingflow --json builder icon catalog`。编辑已有门户时省略则保留现状。 |
44
- | **`--hide-copyright`** / **`--dash-global-config-file`** / **`--config-file`** | 见契约;部分键 **依赖与 `sections` 同批提交**。 |
45
-
46
- **图标规则**:CLI 不按门户名自动猜图标;智能体需要自行选择业务贴合的 `icon + color`。读回结果里的 `icon_config` 可直接用于前端资源卡片展示。
47
-
48
- ---
49
-
50
- ## 3. `sections[]`:六类组件与回读 `type`
51
-
52
- ### 3.1 公共键
53
-
54
- - **`title`**(必填)、**`source_type`**(必填,小写)、可选 **`position`**(**`pc`/`mobile`** 各 **`x,y,cols,rows`**;省略则由**实现自动排布**)。
55
- - **`config`**、**`dash_style_config`**:按类型 Optional。默认只写 snake_case 规范键。
56
-
57
- ### 3.1.0 Payload 字段口径
58
-
59
- 推荐完整 payload 直接使用 CLI 标准键:
60
-
61
- ```json
62
- {
63
- "dash_name": "产品研发数据大屏",
64
- "package_id": 1414909,
65
- "layout_preset": "dashboard_2col",
66
- "pages": [
67
- {
68
- "title": "研发总览",
69
- "components": [
70
- {
71
- "title": "部门分布",
72
- "source_type": "chart",
73
- "chart_ref": {"app_key": "APP_KEY", "chart_id": "CHART_ID"}
74
- }
75
- ]
76
- }
77
- ]
78
- }
6
+ qingflow --json builder portal get --dash-key DASH_KEY --schema-kind complete > portal.json # 更新前先读
7
+ qingflow --json builder portal validate --file portal.json # 零后端离线校验
8
+ qingflow builder portal apply --file portal.json --schema-version v1alpha1 [--dash-key DASH_KEY]
79
9
  ```
80
10
 
81
- `name` 只是兼容别名;如果遇到旧版 CLI 报 **`name Extra inputs are not permitted`**,不要反复重试,改成 **`dash_name`** 或升级 CLI。
82
-
83
- ### 3.1.1 布局硬规则:PC 24 栅格,mobile 6 栅格
84
-
85
- **门户 PC 端不是 12 栅格,而是 24 栅格。**如果把两列写成 **`x=0/6, cols=6`**,所有组件只会占左半屏,工具会返回 **`PORTAL_LAYOUT_HALF_WIDTH`**。
86
-
87
- 推荐:
88
-
89
- | 场景 | PC 写法 |
90
- |------|---------|
91
- | 不确定布局 | **省略 `position`**,或传 **`--layout-preset auto`** |
92
- | 两列可视化图表 | **`x=0/12, cols=12`**,图表 **`rows >= 7`** |
93
- | 三列可视化图表 | **`x=0/8/16, cols=8`**,图表 **`rows >= 7`** |
94
- | 四个指标卡 | **`x=0/6/12/18, cols=6, rows=5`** |
95
- | 具体数据视图 / 明细表 | 优先 **`cols=12`** 或 **`cols=24`**,视图 **`rows >= 11`** |
96
-
97
- mobile 写法固定按 **6 栅格**:通常 **`x=0, cols=6`**。如果只写了 PC position,CLI 会自动补 mobile position,并返回 **`PORTAL_MOBILE_POSITION_MISSING`** 提醒。
98
-
99
- 图表卡片过小时会返回 **`PORTAL_CHART_CARD_TOO_SMALL`**;指标卡按 **`pc.cols >= 6, pc.rows >= 5`** 校验,普通可视化图表按 **`pc.cols >= 8, pc.rows >= 7`** 校验。指标区图表建议写 `role: "metric"`;此时必须引用 `target` / `indicator` 图表,否则返回 **`PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH`**,应先用 `app_charts_apply` 创建缺失指标卡再组门户。标准工作台数量也会进入 `layout_diagnostics.standard_template_counts`:指标卡推荐 4-6 个、BI 图表 2-3 个、业务视图 1-2 个,超出或不足会返回 `PORTAL_STANDARD_*_COUNT_OUT_OF_RANGE`。
100
-
101
- ### 3.1.2 推荐门户模板:业务工作台
102
-
103
- 默认按 **业务入口 → 核心指标 → BI 可视化 → 业务视图** 搭建。门户首屏应直接呈现可用工作台,不要做营销页、说明页或大面积装饰区。
104
-
105
- | 区域 | 推荐组件 | PC 布局 | 要点 |
106
- |------|----------|---------|------|
107
- | 顶部业务入口 | **`grid`** + 可选 **待办 `task`** | `grid x=0,y=0,cols=12,rows=4`;待办 `x=12,y=0,cols=12,rows=4` | `grid` 放 2-6 个核心业务入口;待办用于当前用户任务概览。当前公开 `portal apply --sections-file` 暂未支持 `source_type=task`,不要伪造;见下方边界说明。 |
108
- | 核心指标 | **`chart`** 指标卡 + `role: "metric"` | 4 张:`x=0/6/12/18,y=4,cols=6,rows=5` | 指标卡推荐高度 **5**。24 栅格下单卡最小 `cols=6`,所以一行 4 张最稳;如果要 5 个指标,拆成两行。 |
109
- | BI 可视化 | **`chart`** 图表 | 3 张:`x=0/8/16,y=9,cols=8,rows=7`;或 2 张:`x=0/12,cols=12,rows=7` | 可视化图表推荐高度 **7**,一行 2-3 个,1-2 行。 |
110
- | 业务数据视图 | **`view`** | `x=0/12,y=16,cols=12,rows=11`;或单表 `cols=24,rows=11` | 数据视图推荐高度 **11**,一行 1-2 个,1-2 行。只挂业务视图,不要创建或引用默认的 **全部数据 / 我的数据** 当主门户视图。 |
111
-
112
- mobile 固定按 **6 栅格** 从上到下堆叠:通常所有组件 `x=0, cols=6`,`y` 按 PC 顺序递增。若顶部同时有 `grid + task`,mobile 建议先业务入口 `y=0,rows=4`,再待办 `y=4,rows=4`,核心指标从 `y=8` 开始;若当前公开 CLI 只能写 `grid`,核心指标可从 `y=4` 开始。
113
-
114
- **当前工具边界**:
115
-
116
- - 公开 `sections-file` 稳定支持:**`grid` / `chart` / `view` / `text` / `link`**;`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理,不作为主路径。
117
- - **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状,不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`;只有工具后续显式支持 `task`,或维护者走 raw 门户写入链路时,才使用待办槽位。
118
- - 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)**。该示例使用当前公开 CLI 可稳定写入的组件,顶部先用一个业务入口 `grid` 占满 24 栅格;如果工具已支持待办组件,再把顶部拆成 `grid cols=12 + task cols=12`。
119
- - `grid` 必须写 **`config.items[]`**;只写 `gridTitle` / `beingShowTitle` 会生成空入口容器,工具会返回 **`PORTAL_GRID_ITEMS_EMPTY`**。
120
-
121
- **待办组件 raw 形状参考**(仅用于工具实现对齐,当前不要作为 `--sections-file` 输入):
122
-
123
- ```json
124
- {
125
- "type": 8,
126
- "position": {
127
- "pc": {"x": 12, "y": 0, "cols": 12, "rows": 4},
128
- "mobile": {"x": 0, "y": 4, "cols": 6, "rows": 4}
129
- },
130
- "taskConfig": {
131
- "beingShowTitle": true,
132
- "componentTaskTitle": "待办",
133
- "beingShowHint": true,
134
- "componentTaskHint": "及时处理待办,可以有效提升流程效率",
135
- "dashTaskConfigList": [
136
- {"type": 1, "title": "all.taskTodo", "beingCheck": true, "ordinal": 0},
137
- {"type": 2, "title": "all.taskTimeout", "beingCheck": true, "ordinal": 1},
138
- {"type": 3, "title": "all.taskUpcomingTimeout", "beingCheck": true, "ordinal": 2},
139
- {"type": 4, "title": "all.taskRemind", "beingCheck": true, "ordinal": 3}
140
- ]
141
- }
142
- }
143
- ```
144
-
145
- ### 3.2 `source_type` ↔ 回读 `components[].type`(搭建侧)
146
-
147
- | `source_type` | 回读 `type`(数字) | 搭建侧含义 |
148
- |---------------|---------------------|------------|
149
- | **`chart`** | **9** | QingBI 图表块 |
150
- | **`view`** | **10** | 应用视图块 |
151
- | **`grid`** | **2** | 九宫格 |
152
- | **`filter`** | **6** | 筛选条 |
153
- | **`text`** | **5** | 富文本说明 |
154
- | **`link`** | **4** | 外链 |
155
-
156
- CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart_ref`**;**view** 须 **`view_ref`**;**text** 须 **`text`**;**link** 须 **`url`**。**grid** / **filter** 无额外 ref,**`config` 形状由后端接受为准**。
157
-
158
- ### 3.3 **`chart`**:几乎总须 **`builder charts apply` 先建报表**
159
-
160
- - `portal` 只做 **`chart_ref` 解析**(`app_key` + **`chart_id`** 优先,否则 **唯一 `chart_name`**)。
161
- - 若 **`builder app get charts`** 为空,先 **`builder charts apply --app-key … --upsert-file`** 创建(契约 **minimal_example** 如 **`target` + `indicator_field_ids: []`**),从响应 **`chart_results[].chart_id`** 取 id 再写 **`chart_ref`**.
162
-
163
- ### 3.4 **`filter`**:`config` **整包**即接口里的 **`filterConfig`**
164
-
165
- 实现:组件为 **`{"type": 6, "filterConfig": deepcopy(section.config)}`**。
166
-
167
- - **理论上**与 solution 编译器一致:外层 **`{"filterConfig": [ … ], "graphList": [ … ]}`**;**`graphList`** 常含 **`graphType`**(如 **`CHART`**)、**`graphKey`** 或 **`graphRef`(`entity_id` / `chart_id`)** 等。
168
- - **本环境 CLI 直写实测(多次 `--publish`)**:在已验证 **chart / view / grid / text / link** 均可落库的前提下,**`source_type: filter` 始终未出现在 `draft_result.components` 中**;尝试过:**空数组**、**仅 `graphList` + QingBI `chart_id`**、**`graphKey` 为门户 `dashChartId`**、**`chart` 排在 **`filter` 前**、**仅 2 块(chart+filter)** 等,回读仍 **只有 chart(`count: 1`)** 或 **五类缺 `type: 6`**。
169
- **结论**:当前宜 **在搭建界面创建筛选条**,再 **`builder portal get` 反抓** 原始 `filterConfig` 形状;或向后端确认 **POST `/dash/{dashKey}`** 对 **`type: 6`** 的必填字段。**自动化不要默认认为 `filter` 已写入。**
170
- - portal `filter` 组件仍按 raw `filterConfig` 处理,不纳入视图 / 报表 / 关联资源的统一筛选 DSL 主链路。
171
-
172
- ### 3.5 **`grid` / `text` / `link` / `view`**
173
-
174
- - **grid**:**`config`** 并入 **`gridConfig`**;业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`。空 `config` 或空 `items` 只会生成空入口容器,并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
175
- - **text** / **link**:**`text`** / **`url`** 必填。
176
- - **view**:**`view_ref`**;**`view_key`** 来自 **`builder app get views`**。
177
-
178
- ---
179
-
180
- ## 4. 前置数据
181
-
182
- | 目的 | 命令 |
183
- |------|------|
184
- | **`package_id`** | **`builder app resolve --app-key …`** → **`package_ids`** |
185
- | **`view_key`** | **`builder app get --app-key … views`** |
186
- | **`chart_id`** | **`builder app get charts`** 或 **`charts apply` 创建** |
187
-
188
- ---
189
-
190
- ## 5. 新建最小例(`--no-publish`)
191
-
192
- 见上文 **§2** 与 **`visibility`** 最小对象;**`sections`** 可先用 **单块 `view`**。成功后拿 **`dash_key`** 再 **更新 / 发布**。
193
-
194
- ---
195
-
196
- ## 6. 更新与替换语义
197
-
198
- - **`--dash-key`** + **`--sections-file`**:**列表即全量**;没写进去的区块会被拿掉。
199
- - 仅改 **可见性 / 图标 / 分组**:**不传 `--sections-file`**,且不要单独带 **§2** 所列「仅在有 sections 时允许」的键。
200
-
201
- ---
202
-
203
- ## 7. 删除:`delete`
204
-
205
- ```bash
206
- qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_portal_delete.json
207
- ```
208
-
209
- - **只按 `dash_key` 删除一个门户**;先用 `builder portal list/get` 确认目标,不要按名称猜。
210
- - 返回成功时重点看:**`delete_executed`**、**`readback_status`**、**`safe_to_retry_delete`**、`summary.removed`。
211
- - **`delete_executed=true` + `readback_status=deleted`**:删除已执行且回读确认不存在。
212
- - **`delete_executed=true` + `readback_status=unavailable|still_exists`**:DELETE 已发出,但回读不可确认或短时间仍存在;**不要盲目重复删除**,稍后用 `builder portal get/list` 确认。
213
- - DELETE 本身失败时才按 `status=failed` / `error_code` 处理。
214
-
215
- ---
216
-
217
- ## 8. **发布**(`--publish`)
218
-
219
- - **默认会发布**:未显式 **`--no-publish`** 即 **`publish: true`**;公开入口仍是 **`portal_apply`**,发布动作由工具内部执行并回读 **`being_draft=false`**。
220
- - **已发布线索**:成功路径上 **`published: true`**;**`live_result.publishStatus`** 常见 **`2`** 表示已发布(以你环境枚举为准)。
221
- - **`partial_success` + `PORTAL_READBACK_PENDING`**:草稿/线上 **组件数量或元数据** 与「本次期望」不一致时会出现;**`PORTAL_*_VERIFICATION_INCOMPLETE`** 警告。应 **`builder portal get --dash-key …`**(草稿与 **`--no-being-draft` 线上**)**肉眼核对**区块是否齐全,而不是仅信 **`verified: true`**。
222
- - **网关 503**:**与 CLI 无关**;环境恢复后重试 **`portal get` / `portal apply`**。(本轮在网关恢复后 **`portal apply` 已成功**。)
223
-
224
- ---
225
-
226
- ## 9. 本环境实测摘要
227
-
228
- | 步骤 | 命令要点 | 结果 |
229
- |------|-----------|------|
230
- | 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、`--no-publish`、单 **view** | **`dash_key`: `ecdcell64s02`** |
231
- | 补报表 | **`builder charts apply`**,`name: 门户探针_目标图`,**`target`** | **`chart_id`: `mcp_fb104267c5c249ca`** |
232
- | 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**;**`filter` 仍不落库** → **`partial_success`**,**`components expected 6, got 5`**(与 **§3.4** 一致) |
233
- | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合 | **回读恒为 1 块(仅 `type: 9`)** |
234
- | **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](./portal_sections_five_types.example.json)**(**grid / text / link / view / chart**) | **`status: success`**,**`types: [2,4,5,9,10]`**,**`published: true`** |
235
- | 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**,**`delete_executed: true`**,**`readback_status: deleted`**,**`summary.removed: 1`** |
236
-
237
- **推荐工作台模板示例**:[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)
238
-
239
- **含 `filter` 的六类示例(`filter` 是否落库视环境/后端而定)**:[portal_sections_all_types.example.json](./portal_sections_all_types.example.json)
240
-
241
- ---
242
-
243
- ## 10. 排障
244
-
245
- | 现象 | 处理 |
246
- |------|------|
247
- | `portal apply accepts exactly one selector mode` | **`dash-key`** vs **`package-id`** 二选一。 |
248
- | `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件;若多写了 **`filter`** 而回读少一块,见 **§3.4**(**CLI 写 filter 可能整体不生效**);也可能是 **异步回读**,可再 **`get`** 一次。 |
249
- | **`published: true` 但 `verified: false`** | 读 **§7**;用 **`get` 草稿+线上**对照。 |
250
- | **503** | 网关/运维;稍后重试。 |
251
- | 缺 **chart** | **[QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)**:`builder charts apply`;或换有报表的应用。 |
252
- | **VISIBILITY_CONFLICT** | 只用 **`--visibility-file`**。 |
253
- | `delete_executed=true` 但 `readback_status=unavailable|still_exists` | DELETE 已发出,回读未确认;不要重复删除,稍后 `builder portal get/list` 复核。 |
254
-
255
- ---
256
-
257
- ## 11. 交叉引用
258
-
259
- - [SKILL.md](../SKILL.md)
260
- - [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)
261
- - [QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)
262
- - [QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)
263
- - [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md)
11
+ 契约与九类组件专项 Schema:`qingflow --json builder portal schema --schema-kind complete|<类型>`。
@@ -22,7 +22,7 @@ package apply/get -> AppForm schema/get/apply per app -> app readback -> workflo
22
22
  - 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.
23
23
  - 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.
24
24
  - One app may contain multiple `relation` fields when the business model needs them.
25
- - 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.
25
+ - 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.
26
26
  - 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.
27
27
  - 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.
28
28
  - 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,
73
73
 
74
74
  - Package exists, and its `package_id` is known.
75
75
  - Every core business object is a separate app with `app_key`, `app_name`, `icon`, `color`, and exactly one readable data title field.
76
- - 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`.
76
+ - 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).
77
77
  - Core apps were created with complete AppForm declarations, so fields and readable form sections/rows were submitted together.
78
78
  - 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.
79
79
  - Each new app has 5 realistic sample records unless the user explicitly skipped sample data.
@@ -185,7 +185,7 @@ current CLI payload.
185
185
  | 负责人、审批人、参与人 | `member` | 不要创建“申请人/提交人”等平台系统字段 |
186
186
  | 部门、组织 | `department` | 可按需要补 `config.departmentScope` |
187
187
  | 图片、文件、附件 | `attachment` | 只有顶层 `attachment` 可被应用级 `dataCoverField` 选择 |
188
- | 跨应用业务对象关系 | `relation` | 使用已确认的 `targetAppKey`;`displayField` / `visibleFields` 必须写对象选择器 |
188
+ | 跨应用业务对象关系 | `relation` | 使用已确认的 `targetAppKey`;展示字段写有序 `displayFields[]`(含 `auth`),双向绑定写 `twoWayBoundField`;旧 `displayField`/`visibleFields` 兼容窗口内仍可读 |
189
189
 
190
190
  禁止创建平台系统字段:`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。需要引用系统字段时,只在工具明确支持的位置引用,例如按钮 `source_field: "数据ID"`。
191
191
 
@@ -218,6 +218,19 @@ current CLI payload.
218
218
  | `relation` | 关联记录(**`config.relationMode`**:`single` \| `multiple`) |
219
219
  | `data_relation` | 数据关联/引用填充 |
220
220
  | `subtable` | 子表(**`subfields[]`**) |
221
+ | `date_duration` | 日期区间(透传型,无特殊配置) |
222
+ | `image_select` | 图片单选(透传型,选项经模板保真) |
223
+ | `location` | 地理位置(透传型) |
224
+ | `ocr` | OCR 识别(透传型) |
225
+ | `embed_field` | 内嵌字段(透传型) |
226
+ | `ai_content_generation` | AI 内容生成(透传型) |
227
+ | `ai_content_extraction` | AI 内容提取(透传型) |
228
+ | `ai_content_classification` | AI 内容分类(透传型) |
229
+ | `ai_machine_translation` | AI 机器翻译(透传型) |
230
+ | `ai_image_recognition` | AI 图像识别(透传型) |
231
+ | `ai_image_generation` | AI 图像生成(透传型) |
232
+ | `ai_document_parsing` | AI 文档解析(透传型) |
233
+ | `ai_text_summary` | AI 文本摘要(透传型) |
221
234
 
222
235
  历史表单中的后端 `queType=1` 是“描述文字”布局控件,不属于上述新建字段类型。`app-form get` 为了保持完整声明可校验,会将它兼容输出为 `long_text`;`app-form apply` 会根据已有字段模板恢复原始 `queType=1` 和 `queDefaultValue`,所以修改其他字段时不会丢失描述文字。新建可填写多行文本仍使用 `long_text`,不要用它创建描述文字控件。
223
236
 
@@ -243,7 +256,7 @@ current CLI payload.
243
256
  |--------|----------|-----------------|
244
257
  | 标量与选择器 | `name` + `questionType`(+ 业务 `beingRequired` 等) | `questionDescription`、`beingRequired`;数据标题和封面在应用级 `dataTitleField/dataCoverField` 中选择;**`single_select` / `multi_select` 的 `config.options` 是非空字符串数组**,如 `["A", "B"]` |
245
258
  | `department` | 同左 | **`config.departmentScope`**:`mode: all \| custom`;`custom` 时 **`departments[]`**(含 `deptId` 等) |
246
- | `relation` | **`targetAppKey`**;另需 **`displayField`**、**`visibleFields[]`** | **`relationMode`**;目标应用元数据不可读时先读已发布表单,不要猜目标 key |
259
+ | `relation` | **`targetAppKey`**;另需 **`displayFields[]`**(含 `field`+`auth`;可为空列表——空 = 双向绑定未配展示字段的存量形态,round-trip 空↔空稳定;与旧形态不可混用、条目 queId 不可重复) | **`relationMode`**;双向绑定加 **`twoWayBoundField`**(省略 = 单向);目标应用元数据不可读时先读已发布表单,不要猜目标 key |
247
260
  | `subtable` | **`subfields[]` 非空** | 子列递归同父级规则;使用 Schema 返回的 camelCase 子字段配置 |
248
261
  | `q_linker` | **`config.qLinkerBinding`**:`inputs`、`request`、**`outputs[]` 每项须含 `targetField`**(能解析到本表单字段) | `request.url` 等须符合**租户/后端远程查询策略**;以字段类型 Schema 返回的配置为准 |
249
262
  | `code_block` | **`config.codeBlockBinding`**:`inputs`、`code`、**`outputs[]` + `targetField`**;配置 outputs 时,代码必须显式写 **`qf_output = {...}`**,仅 `return {...}` 不会产生可回写结果,且每个 `outputs[].path` 必须从 `qf_output` 取值 | 以字段类型 Schema 返回的 camelCase 配置为准 |
@@ -265,13 +278,17 @@ current CLI payload.
265
278
  "config": {
266
279
  "targetAppKey": "PRODUCT_APP_KEY",
267
280
  "relationMode": "single",
268
- "displayField": {"name": "产品编码"},
269
- "visibleFields": [{"name": "产品名称"}, {"name": "产品线"}]
281
+ "twoWayBoundField": {"name": "产品编码"},
282
+ "displayFields": [
283
+ {"field": {"name": "产品编码"}, "auth": "visible"},
284
+ {"field": {"name": "产品名称"}, "auth": "hidden"},
285
+ {"field": {"name": "产品线"}, "auth": "visible"}
286
+ ]
270
287
  }
271
288
  }
272
289
  ```
273
290
 
274
- 只在目标应用已经创建并通过 readback 确认后填写 `targetAppKey`。如果返回选择器校验错误,修复 `config.displayField` / `config.visibleFields`,不要重建应用或改 `appKey`。
291
+ 只在目标应用已经创建并通过 readback 确认后填写 `targetAppKey`。如果返回选择器校验错误,修复 `config.displayFields[].field` / `config.twoWayBoundField`,不要重建应用或改 `appKey`。旧形态 `displayField`/`visibleFields` 在兼容窗口内仍可读(displayField 同时视为双向绑定目标),新声明一律用 `displayFields`。
275
292
 
276
293
  引用字段的公式默认值写在 `config.defaultValueFormula`,表达式必须符合固定版本 `relation` 字段详情中的 `FormulaExpression`。不要把后端 `referenceConfig` 字段名或其他 Schema 版本的公式写法直接放进声明。
277
294