@qingflow-tech/qingflow-cli 1.0.11 → 1.0.13

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 (89) hide show
  1. package/README.md +8 -4
  2. package/docs/local-agent-install.md +54 -3
  3. package/entry_point.py +1 -1
  4. package/npm/bin/qingflow-skills.mjs +5 -0
  5. package/npm/bin/qingflow.mjs +7 -2
  6. package/npm/lib/runtime.mjs +304 -13
  7. package/npm/scripts/postinstall.mjs +1 -5
  8. package/package.json +3 -2
  9. package/pyproject.toml +1 -1
  10. package/skills/qingflow-cli/SKILL.md +431 -0
  11. package/skills/qingflow-cli/manifest.yaml +10 -0
  12. package/skills/qingflow-cli/reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md +94 -0
  13. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md +432 -0
  14. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +177 -0
  15. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md +121 -0
  16. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +200 -0
  17. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md +288 -0
  18. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md +40 -0
  19. package/skills/qingflow-cli/reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md +129 -0
  20. package/skills/qingflow-cli/reference/QINGFLOW_CLI_EXPLORATION_REPORT.md +84 -0
  21. package/skills/qingflow-cli/reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md +129 -0
  22. package/skills/qingflow-cli/reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md +196 -0
  23. package/skills/qingflow-cli/reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md +159 -0
  24. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md +14 -0
  25. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md +150 -0
  26. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md +163 -0
  27. package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md +95 -0
  28. package/skills/qingflow-cli/reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md +150 -0
  29. package/skills/qingflow-cli/reference/_batch_schema_complex.json +18 -0
  30. package/skills/qingflow-cli/reference/_batch_schema_scalar.json +17 -0
  31. package/skills/qingflow-cli/reference/charts_remove.example.json +1 -0
  32. package/skills/qingflow-cli/reference/charts_reorder.example.json +1 -0
  33. package/skills/qingflow-cli/reference/charts_upsert_bar.example.json +8 -0
  34. package/skills/qingflow-cli/reference/charts_upsert_dashboard_starter.example.json +37 -0
  35. package/skills/qingflow-cli/reference/charts_upsert_minimal.example.json +13 -0
  36. package/skills/qingflow-cli/reference/portal_sections_all_types.example.json +131 -0
  37. package/skills/qingflow-cli/reference/portal_sections_five_types.example.json +106 -0
  38. package/skills/qingflow-cli/reference/schema_add_fields_minimal.example.json +7 -0
  39. package/skills/qingflow-cli/reference/schema_apply_add_fields_all_types.json +78 -0
  40. package/skills/qingflow-cli/reference/views_upsert_table_minimal.example.json +7 -0
  41. package/skills/qingflow-cli/scripts/builder-package-from-app-list.py +140 -0
  42. package/skills/qingflow-cli/scripts/find-app-by-keyword.py +132 -0
  43. package/skills/qingflow-mcp-setup/SKILL.md +113 -0
  44. package/skills/qingflow-mcp-setup/agents/openai.yaml +4 -0
  45. package/skills/qingflow-mcp-setup/references/claude-desktop.md +34 -0
  46. package/skills/qingflow-mcp-setup/references/environments.md +62 -0
  47. package/skills/qingflow-mcp-setup/references/generic-stdio.md +32 -0
  48. package/skills/qingflow-mcp-setup/scripts/check_local_server.sh +38 -0
  49. package/src/qingflow_mcp/__main__.py +6 -2
  50. package/src/qingflow_mcp/builder_facade/models.py +11 -0
  51. package/src/qingflow_mcp/builder_facade/service.py +1488 -288
  52. package/src/qingflow_mcp/cli/commands/builder.py +2 -2
  53. package/src/qingflow_mcp/cli/commands/exports.py +2 -2
  54. package/src/qingflow_mcp/cli/commands/imports.py +1 -1
  55. package/src/qingflow_mcp/cli/commands/record.py +91 -19
  56. package/src/qingflow_mcp/cli/context.py +0 -3
  57. package/src/qingflow_mcp/cli/formatters.py +206 -7
  58. package/src/qingflow_mcp/cli/main.py +47 -3
  59. package/src/qingflow_mcp/errors.py +43 -2
  60. package/src/qingflow_mcp/public_surface.py +21 -15
  61. package/src/qingflow_mcp/response_trim.py +74 -13
  62. package/src/qingflow_mcp/server.py +11 -9
  63. package/src/qingflow_mcp/server_app_builder.py +3 -2
  64. package/src/qingflow_mcp/server_app_user.py +19 -13
  65. package/src/qingflow_mcp/session_store.py +11 -7
  66. package/src/qingflow_mcp/solution/executor.py +112 -15
  67. package/src/qingflow_mcp/tools/ai_builder_tools.py +36 -11
  68. package/src/qingflow_mcp/tools/app_tools.py +184 -43
  69. package/src/qingflow_mcp/tools/approval_tools.py +196 -34
  70. package/src/qingflow_mcp/tools/auth_tools.py +92 -16
  71. package/src/qingflow_mcp/tools/code_block_tools.py +298 -40
  72. package/src/qingflow_mcp/tools/custom_button_tools.py +64 -10
  73. package/src/qingflow_mcp/tools/directory_tools.py +236 -72
  74. package/src/qingflow_mcp/tools/export_tools.py +244 -34
  75. package/src/qingflow_mcp/tools/file_tools.py +7 -3
  76. package/src/qingflow_mcp/tools/import_tools.py +336 -49
  77. package/src/qingflow_mcp/tools/navigation_tools.py +91 -12
  78. package/src/qingflow_mcp/tools/package_tools.py +118 -6
  79. package/src/qingflow_mcp/tools/portal_tools.py +39 -3
  80. package/src/qingflow_mcp/tools/qingbi_report_tools.py +116 -7
  81. package/src/qingflow_mcp/tools/record_tools.py +1067 -349
  82. package/src/qingflow_mcp/tools/resource_read_tools.py +188 -39
  83. package/src/qingflow_mcp/tools/role_tools.py +80 -9
  84. package/src/qingflow_mcp/tools/solution_tools.py +57 -15
  85. package/src/qingflow_mcp/tools/task_context_tools.py +569 -119
  86. package/src/qingflow_mcp/tools/task_tools.py +113 -29
  87. package/src/qingflow_mcp/tools/view_tools.py +106 -3
  88. package/src/qingflow_mcp/tools/workflow_tools.py +17 -1
  89. package/src/qingflow_mcp/tools/workspace_tools.py +71 -3
@@ -0,0 +1,121 @@
1
+ # Builder 字段匹配规则:按钮传参与关联视图/报表筛选
2
+
3
+ 本文只适用于 **Builder 侧 MatchRule**:
4
+
5
+ - `builder button apply` 的新增数据按钮传参
6
+ - `builder associated-resource apply` 的关联视图 / 关联报表筛选条件
7
+
8
+ 它不是 `record_access` 分析筛选 DSL,也不是普通视图 `filters`。
9
+
10
+ ---
11
+
12
+ ## 1. 默认写法
13
+
14
+ 优先使用语义化映射,不手写后端 raw `que_relation` / `match_rules`。
15
+
16
+ ### 1.1 新增数据按钮
17
+
18
+ ```json
19
+ [
20
+ {
21
+ "client_key": "add_worklog",
22
+ "button_text": "快捷添加工时",
23
+ "trigger_action": "addData",
24
+ "trigger_add_data_config": {
25
+ "target_app_key": "WORKLOG_APP",
26
+ "field_mappings": [
27
+ {"source_field": "数据ID", "target_field": "关联员工"},
28
+ {"source_field": "员工名称", "target_field": "员工姓名"}
29
+ ],
30
+ "default_values": {
31
+ "状态": "待提交"
32
+ }
33
+ }
34
+ }
35
+ ]
36
+ ```
37
+
38
+ `field_mappings` 表示从当前记录动态带值;`default_values` 只表示静态默认值。
39
+
40
+ ### 1.2 关联视图 / 报表
41
+
42
+ 跨应用关联必须显式传 `target_app_key`。若关联的是当前应用自己的视图或报表,可以省略 `target_app_key`,CLI 会默认使用命令里的 `--app-key`。
43
+
44
+ ```json
45
+ [
46
+ {
47
+ "client_key": "employee_worklogs",
48
+ "graph_type": "view",
49
+ "target_app_key": "WORKLOG_APP",
50
+ "view_key": "WORKLOG_VIEW",
51
+ "match_mappings": [
52
+ {"target_field": "关联员工", "source_field": "数据ID"},
53
+ {"target_field": "状态", "value": "待提交"}
54
+ ]
55
+ }
56
+ ]
57
+ ```
58
+
59
+ 动态条件用 `source_field`;静态条件用 `value`。
60
+
61
+ ---
62
+
63
+ ## 2. 系统字段
64
+
65
+ 系统字段可以参与匹配:
66
+
67
+ | 写法 | field_id | 含义 |
68
+ | --- | --- | --- |
69
+ | `数据ID` / `row_record_id` / `apply_id` / `_id` | `-17` | 当前记录真实 record/apply ID |
70
+ | `编号` / `数据编号` / `record_number` | `0` | 前端可见数据编号,可能是自定义编号 |
71
+
72
+ 也可以显式写:
73
+
74
+ ```json
75
+ {"source_field": {"field_id": -17}, "target_field": "关联员工"}
76
+ ```
77
+
78
+ 注意:`数据ID` 和 `编号` 不是同一个东西。要把当前记录填入目标引用字段时,用 `数据ID`。
79
+
80
+ ---
81
+
82
+ ## 3. 类型兼容规则
83
+
84
+ | 目标 / 源字段类型 | 可匹配对象 |
85
+ | --- | --- |
86
+ | 引用字段 | 同目标应用的引用字段,或当前源应用记录的 `数据ID(-17)` |
87
+ | `数据ID(-17)` | 指向当前源应用的目标引用字段;也可匹配 ID 兼容的文本/数字字段 |
88
+ | `编号(0)` | 文本、长文本、数字、金额、编号类字段 |
89
+ | 成员字段 | 成员字段 |
90
+ | 部门字段 | 部门字段 |
91
+ | 单选 / 多选 / 布尔 | 选项类字段或静态选项值 |
92
+ | 日期 / 日期时间 | 日期类字段互通 |
93
+ | 文本 / 长文本 / 电话 / 邮箱 | 文本类字段互通 |
94
+ | 数字 / 金额 | 数值类字段互通 |
95
+
96
+ 附件、子表、代码块、Q-Linker、地址字段默认不作为匹配字段。
97
+
98
+ ---
99
+
100
+ ## 4. 常见错误处理
101
+
102
+ | 错误场景 | 下一步 |
103
+ | --- | --- |
104
+ | 字段不存在 | 重新 `builder app get --app-key APP_KEY fields` / `builder app get --app-key APP_KEY`,用准确字段标题或 `field_id` |
105
+ | 类型不兼容 | 按上表换兼容的源字段 / 目标字段 |
106
+ | 引用来源不一致 | 目标引用字段指向了别的应用;换成指向当前源应用的引用字段 |
107
+ | 同时传 semantic 与 raw | 同一项里只能二选一:`field_mappings/match_mappings` 或 raw `que_relation/match_rules` |
108
+
109
+ ---
110
+
111
+ ## 5. 关联资源 ID 口径
112
+
113
+ `associated_item_id` 是应用级关联资源池里的 `form_asos_chart.id`,最终口径来自:
114
+
115
+ ```bash
116
+ qingflow --json builder app get --app-key APP_KEY
117
+ ```
118
+
119
+ 或同等 `app_get.associated_resources[].associated_item_id`。
120
+
121
+ 它不是 `chart_id`、`chart_key`、`view_key`。但新版 `builder associated-resource apply` 在部分入口可接受 `chart_id` / `chart_key` / `view_key` 作为 selector,并自动解析成后端需要的 `associated_item_id`;写 view config 或排障时仍以读回的 `associated_item_id` 为准。
@@ -0,0 +1,200 @@
1
+ # Builder 门户创建与变更 SOP:`qingflow builder portal`
2
+
3
+ 搭建侧稳定入口:**`qingflow builder portal`**:`list` / `get` / **`apply`**(与根命令 **`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`)、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**:**新建**(`--no-publish`)、**`--publish` 更新**(网关 **503** 恢复后已重试成功)、**五类区块可稳定落库**;**`filter`(`type:6`)经 CLI 直传未落库** 见 **§3.4 / §8**。
6
+
7
+ > **权限**:**更新**需 **`edit_portal`**;**新建**按后端 `DashCtrl.createDash` 链路只预检目标包 **`add_app`**,不额外要求包 **`edit_app`**。失败时参见主技能与 **ADMIN** 速查。
8
+
9
+ > **契约**:`qingflow --json builder contract --tool-name portal_apply`
10
+
11
+ ---
12
+
13
+ ## 1. 读:`list` → `get`
14
+
15
+ ```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
+ }
79
+ ```
80
+
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 >= 6`** |
93
+ | 三列大屏 | **`x=0/8/16, cols=8`**,图表 **`rows >= 6`** |
94
+ | 四个指标卡 | **`x=0/6/12/18, cols=6`**,指标卡可较矮 |
95
+ | 趋势图 / 表格 / 明细视图 | 优先 **`cols=12`** 或 **`cols=24`** |
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 >= 8` 且 `pc.rows >= 6`**。
100
+
101
+ ### 3.2 `source_type` ↔ 回读 `components[].type`(搭建侧)
102
+
103
+ | `source_type` | 回读 `type`(数字) | 搭建侧含义 |
104
+ |---------------|---------------------|------------|
105
+ | **`chart`** | **9** | QingBI 图表块 |
106
+ | **`view`** | **10** | 应用视图块 |
107
+ | **`grid`** | **2** | 九宫格 |
108
+ | **`filter`** | **6** | 筛选条 |
109
+ | **`text`** | **5** | 富文本说明 |
110
+ | **`link`** | **4** | 外链 |
111
+
112
+ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart_ref`**;**view** 须 **`view_ref`**;**text** 须 **`text`**;**link** 须 **`url`**。**grid** / **filter** 无额外 ref,**`config` 形状由后端接受为准**。
113
+
114
+ ### 3.3 **`chart`**:几乎总须 **`builder charts apply` 先建报表**
115
+
116
+ - `portal` 只做 **`chart_ref` 解析**(`app_key` + **`chart_id`** 优先,否则 **唯一 `chart_name`**)。
117
+ - 若 **`builder app get charts`** 为空,先 **`builder charts apply --app-key … --upsert-file`** 创建(契约 **minimal_example** 如 **`target` + `indicator_field_ids: []`**),从响应 **`chart_results[].chart_id`** 取 id 再写 **`chart_ref`**.
118
+
119
+ ### 3.4 **`filter`**:`config` **整包**即接口里的 **`filterConfig`**
120
+
121
+ 实现:组件为 **`{"type": 6, "filterConfig": deepcopy(section.config)}`**。
122
+
123
+ - **理论上**与 solution 编译器一致:外层 **`{"filterConfig": [ … ], "graphList": [ … ]}`**;**`graphList`** 常含 **`graphType`**(如 **`CHART`**)、**`graphKey`** 或 **`graphRef`(`entity_id` / `chart_id`)** 等。
124
+ - **本环境 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`**。
125
+ **结论**:当前宜 **在搭建界面创建筛选条**,再 **`builder portal get` 反抓** 原始 `filterConfig` 形状;或向后端确认 **POST `/dash/{dashKey}`** 对 **`type: 6`** 的必填字段。**自动化不要默认认为 `filter` 已写入。**
126
+
127
+ ### 3.5 **`grid` / `text` / `link` / `view`**
128
+
129
+ - **grid**:**`config`** 并入 **`gridTitle`** 等;**`items`** 等键以后端为准,**空 `config`{}** 可生成空九宫格(已测)。
130
+ - **text** / **link**:**`text`** / **`url`** 必填。
131
+ - **view**:**`view_ref`**;**`view_key`** 来自 **`builder app get views`**。
132
+
133
+ ---
134
+
135
+ ## 4. 前置数据
136
+
137
+ | 目的 | 命令 |
138
+ |------|------|
139
+ | **`package_id`** | **`builder app resolve --app-key …`** → **`package_ids`** |
140
+ | **`view_key`** | **`builder app get --app-key … views`** |
141
+ | **`chart_id`** | **`builder app get charts`** 或 **`charts apply` 创建** |
142
+
143
+ ---
144
+
145
+ ## 5. 新建最小例(`--no-publish`)
146
+
147
+ 见上文 **§2** 与 **`visibility`** 最小对象;**`sections`** 可先用 **单块 `view`**。成功后拿 **`dash_key`** 再 **更新 / 发布**。
148
+
149
+ ---
150
+
151
+ ## 6. 更新与替换语义
152
+
153
+ - **`--dash-key`** + **`--sections-file`**:**列表即全量**;没写进去的区块会被拿掉。
154
+ - 仅改 **可见性 / 图标 / 分组**:**不传 `--sections-file`**,且不要单独带 **§2** 所列「仅在有 sections 时允许」的键。
155
+
156
+ ---
157
+
158
+ ## 7. **发布**(`--publish`)
159
+
160
+ - **默认会发布**:未显式 **`--no-publish`** 即 **`publish: true`**;公开入口仍是 **`portal_apply`**,发布动作由工具内部执行并回读 **`being_draft=false`**。
161
+ - **已发布线索**:成功路径上 **`published: true`**;**`live_result.publishStatus`** 常见 **`2`** 表示已发布(以你环境枚举为准)。
162
+ - **`partial_success` + `PORTAL_READBACK_PENDING`**:草稿/线上 **组件数量或元数据** 与「本次期望」不一致时会出现;**`PORTAL_*_VERIFICATION_INCOMPLETE`** 警告。应 **`builder portal get --dash-key …`**(草稿与 **`--no-being-draft` 线上**)**肉眼核对**区块是否齐全,而不是仅信 **`verified: true`**。
163
+ - **网关 503**:**与 CLI 无关**;环境恢复后重试 **`portal get` / `portal apply`**。(本轮在网关恢复后 **`portal apply` 已成功**。)
164
+
165
+ ---
166
+
167
+ ## 8. 本环境实测摘要
168
+
169
+ | 步骤 | 命令要点 | 结果 |
170
+ |------|-----------|------|
171
+ | 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、`--no-publish`、单 **view** | **`dash_key`: `ecdcell64s02`** |
172
+ | 补报表 | **`builder charts apply`**,`name: 门户探针_目标图`,**`target`** | **`chart_id`: `mcp_fb104267c5c249ca`** |
173
+ | 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**;**`filter` 仍不落库** → **`partial_success`**,**`components expected 6, got 5`**(与 **§3.4** 一致) |
174
+ | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合 | **回读恒为 1 块(仅 `type: 9`)** |
175
+ | **稳定可复现** | **`--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`** |
176
+
177
+ **含 `filter` 的六类示例(`filter` 是否落库视环境/后端而定)**:[portal_sections_all_types.example.json](./portal_sections_all_types.example.json)
178
+
179
+ ---
180
+
181
+ ## 9. 排障
182
+
183
+ | 现象 | 处理 |
184
+ |------|------|
185
+ | `portal apply accepts exactly one selector mode` | **`dash-key`** vs **`package-id`** 二选一。 |
186
+ | `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件;若多写了 **`filter`** 而回读少一块,见 **§3.4**(**CLI 写 filter 可能整体不生效**);也可能是 **异步回读**,可再 **`get`** 一次。 |
187
+ | **`published: true` 但 `verified: false`** | 读 **§7**;用 **`get` 草稿+线上**对照。 |
188
+ | **503** | 网关/运维;稍后重试。 |
189
+ | 缺 **chart** | **[QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)**:`builder charts apply`;或换有报表的应用。 |
190
+ | **VISIBILITY_CONFLICT** | 只用 **`--visibility-file`**。 |
191
+
192
+ ---
193
+
194
+ ## 10. 交叉引用
195
+
196
+ - [SKILL.md](../SKILL.md)
197
+ - [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)
198
+ - [QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)
199
+ - [QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)
200
+ - [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md)
@@ -0,0 +1,288 @@
1
+ # Builder 视图创建与变更 SOP:`qingflow builder views apply`
2
+
3
+ 稳定命令:**`qingflow builder views apply`**(别名 **`qingflow build views apply`**)。编写前已结合 **builder 契约**与实现要点整理;**最小可用 `upsert` 文件**见 **[views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)**(与门户/报表 **`.example.json`** 同风格)。已对应用 **`ead8ims5i401`** **实跑**该文件。
4
+
5
+ > **权限**:视图**新建**走后端 `createViewgraphConfig`,需要同时满足 **视图管理 / ViewManagementAuth**(`beingViewManageStatus`)和 **数据管理 / DataManageAuth**;视图**更新/删除**只走 **ViewManagementAuth**。未开启高级应用权限时 `beingViewManageStatus` 等价回落到 **DataManageAuth**。失败时常见 **40002 / 40161 / 编辑锁**,参见主技能与 **ADMIN** 速查。
6
+
7
+ > **契约**(权威键名、枚举、`execution_notes`、示例):
8
+ > `qingflow --json builder contract --tool-name app_views_apply`
9
+ > (`--tool-name` 为契约索引,用于拉取 **`allowed_keys` / 别名 / 示例**。)
10
+ > 契约示例若带 `"profile"`,不要复制到 `--upsert-views-file`;CLI 指定 profile 用根级 `qingflow --profile …`。
11
+
12
+ ---
13
+
14
+ ## 1. 推荐操作顺序(读 → 写 → 校验)
15
+
16
+ | 步骤 | 动作 | CLI |
17
+ |------|------|-----|
18
+ | ① 读应用地图 | 先看 compact views/charts/buttons/associated resources | `qingflow --json builder app get --app-key <APP_KEY>` |
19
+ | ② 读字段/视图 | 确认 **`columns`** / `query_conditions` 可用字段、核对 **`view_key`** | `qingflow --json builder app get --app-key <APP_KEY> fields` / `qingflow --json builder app get --app-key <APP_KEY> views` |
20
+ | ③ 准备补丁 JSON | 写入 **`upsert_views` / `remove_views`** 数组文件(见 §3) | — |
21
+ | ④ 应用视图补丁 | 执行 apply | `qingflow builder views apply …`(写入命令自动 JSON,默认直接 stdout;需要留档时用 `tee`) |
22
+ | ⑤ 涉及关联/按钮 | 用专项 apply,不把它们塞进 view patch | `builder associated-resource apply` / `builder button apply` |
23
+ | ⑥ 需要上线时 | 发布侧校验 | `qingflow builder publish verify --app-key …` |
24
+
25
+ **说明**:`views apply` 的 **`--publish`** 对应契约里的 **`publish`**;自动化可先 **`--no-publish`**,与 schema/layout 改完再 **`publish verify`** 的节奏一致,见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)** 的发布校验章节。
26
+
27
+ ---
28
+
29
+ ## 2. CLI 形态
30
+
31
+ ```bash
32
+ qingflow builder views apply \
33
+ --app-key "<APP_KEY>" \
34
+ [--publish | --no-publish] \
35
+ [--upsert-views-file PATH] \
36
+ [--remove-views-file PATH]
37
+ ```
38
+
39
+ - **`--upsert-views-file`** / **`--remove-views-file`**:各为 **JSON 数组**文件,与实现里 `load_list_arg` 一致;可只传其一或两者兼有。
40
+ - 输出默认直接给 stdout,前端可直接读取;需要留档时用 `qingflow builder views apply … | tee tmp/builder_views_apply.json`。
41
+
42
+ ---
43
+
44
+ ## 2.1 参考示例文件(与门户 / 报表同风格)
45
+
46
+ | 文件 | 用途 |
47
+ |------|------|
48
+ | [views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json) | **新建 table 视图**最小 **`upsert_views` 数组**:`name` + `type` + **`columns`**(字段 **显示名**,须来自 **`builder app get --app-key … fields`**) |
49
+
50
+ **本仓实测**(`ead8ims5i401`,`--no-publish`):使用文件内 **`columns`**(`单行文字`、`多行文字`)与视图 **`name`** **`示例表视图_CLI模板`** 可 **`status: success` 创建**。复制到其他应用前务必 **`app get fields`** 替换 **`columns`**;**`name`** 重名时会 **更新** 已有同名视图而非新建(见 **§4**)。
51
+
52
+ ---
53
+
54
+ ## 3. 请求体形状(与契约对齐)
55
+
56
+ CLI 将参数与文件内容拼装为服务层载荷,**顶层键**如下:
57
+
58
+ | 键 | 说明 |
59
+ |----|------|
60
+ | **`app_key`** | 必填 |
61
+ | **`publish`** | 是否顺带发布语义(与 **`--publish` / `--no-publish`** 一致) |
62
+ | **`upsert_views`** | 补丁对象数组(见 §4~§6) |
63
+ | **`remove_views`** | 删除项数组(见 §7) |
64
+
65
+ **别名**(契约 `aliases` 节选):**`fields` / `column_names` → `columns`**;**`view_key` / `viewKey`**;**`tableView`→`table`**、**`kanban`→`board`** 等;**`filter_rules`→`filters`**;**`startField`→`start_field`** 等。
66
+
67
+ ---
68
+
69
+ ## 4. 创建 vs 更新(`view_key` 与 `name`)
70
+
71
+ 服务逻辑概要:
72
+
73
+ - **`remove_views`**:可传 raw **`view_key`** 或视图 **显示名 `name`**;显示名重名则 **`AMBIGUOUS_VIEW`**,须改用 `view_key`。
74
+ - **`upsert_views`**:
75
+ - 若提供 **`view_key`**:对该视图做 **更新**(含类型变更等,仍受后端约束)。
76
+ - 未提供 **`view_key`**:若 **`name` 唯一** 匹配已有视图 → **更新**;否则 → **创建**。
77
+
78
+ 响应中的 **`verification.by_view[].status`** 会出现 **`created` / `updated`** 等;**`views_diff`** 汇总创建/更新/失败名单。
79
+
80
+ **`partial_success`**:部分视图成功、部分失败时整体仍可能带成功信封,务必读 **`failed`** 与 **`execution_notes`**。
81
+
82
+ ---
83
+
84
+ ## 5. `type` 与各类型必填
85
+
86
+ 契约 **`view.type`**:**`table`** | **`card`** | **`board`** | **`gantt`**。
87
+
88
+ | `type` | 列/字段要点 | 类型专属键 |
89
+ |--------|----------------|------------|
90
+ | **`table`** | **`columns`**(业务字段 **显示名**,须能在 **`app get fields`** 里找到) | — |
91
+ | **`card`** | 同 table | — |
92
+ | **`board`**(看板) | 列;且须 **`group_by`**(分组字段名) | **`group_by`** |
93
+ | **`gantt`** | 列;须 **`start_field`**、**`end_field`**(通常为日期类字段名) | 可选 **`title_field`** |
94
+
95
+ 实现侧校验:对 **table/card**,若声明了 **`columns`**,在 **过滤系统列**后须 **至少保留一个**真实应用字段,否则报错——**不能**只用系统列名凑一列(系统列集合见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) §7.1**)。
96
+
97
+ ---
98
+
99
+ ## 6. `filters` / `query_conditions` / `visibility` / `buttons`
100
+
101
+ ### 6.1 `filters`
102
+
103
+ - 项形状:**`field_name`**、**`operator`**、**`values`**(或契约允许的 **`value`** 别名)。
104
+ - **`operator`**:`eq` / `neq` / `in` / `contains` / `gte` / `lte` / `is_empty` / `not_empty` 等(以契约为准)。
105
+ - **`in` 等多值**:传 **列表**;**`value`** 为列表时可作别名。
106
+ - **语义**:固定筛选条件,打开视图即生效。不要把前端查询栏字段写进 `filters`。
107
+
108
+ ### 6.2 `query_conditions`
109
+
110
+ `query_conditions` 是前端“查询条件/查询栏”配置,和 `filters` 是两套语义:
111
+
112
+ - `filters`:固定筛选,打开视图即生效。
113
+ - `query_conditions`:只配置前端查询面板可输入哪些字段;用户输入查询值后才生效。
114
+ - `rows` 是字段布局矩阵,不表示 OR 条件。
115
+
116
+ 示例:
117
+
118
+ ```json
119
+ {
120
+ "name": "客户查询视图",
121
+ "type": "table",
122
+ "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
123
+ "filters": [
124
+ {"field_name": "客户状态", "operator": "eq", "value": "有效"}
125
+ ],
126
+ "query_conditions": {
127
+ "enabled": true,
128
+ "exact": false,
129
+ "hide_before_query": false,
130
+ "rows": [["客户名称", "负责人"], ["创建时间"]]
131
+ }
132
+ }
133
+ ```
134
+
135
+ 读回验证时,不要只看视图是否存在;要看 `verification.view_query_conditions_verified=true`。若返回 query condition mismatch,只能说视图已创建/更新,但查询条件未完全验证。
136
+
137
+ ### 6.3 `visibility`
138
+
139
+ 与包/应用/视图等 **授权形态一致**(契约 **`visibility.mode`**:`workspace` | `everyone` | `specific`;**`external_mode`**:`not` | `workspace` | `specific`;**`selectors` / `external_selectors`** 键集合见契约)。
140
+
141
+ - **更新已存在视图**:省略 **`visibility`** 可 **保留**当前后端权限。
142
+ - **名称类 selector**:须 **唯一解析**,否则失败(不猜测)。
143
+
144
+ ### 6.4 `buttons`(兼容路径)
145
+
146
+ 新版默认不要通过 `app_views_apply.buttons` 配置自定义按钮。按钮本体、字段映射、默认值和头部/详情/列表位置统一走 **`app_custom_buttons_apply`** / CLI **`builder button apply`**。
147
+
148
+ - `button_ref` 可以是同次按钮的 `client_key`,也可以是已有 `button_id`。
149
+ - `view_configs[].view_key` 使用 raw `view_key`,不要加 `custom:`。
150
+ - `view_configs[].mode` 默认 `merge`;merge 模式必须带 `buttons`,不要只传 `view_key`。清空绑定用 `mode: "replace"` 或显式 `buttons: []`。
151
+ - 对外入参仍写 `placement=list`;CLI 会映射为后端 `INSIDE` 行内/列表按钮。
152
+ - 权限分界:按钮本体增删改需要 **EditAppAuth**;只要同次包含 `view_configs` 写视图按钮位置,还需要 **ViewManagementAuth**(未开启高级应用权限时回落到 **DataManageAuth**)。
153
+
154
+ `app_views_apply.buttons` 仅作为旧配置维护兼容:
155
+
156
+ - **省略**:保留现有按钮配置。
157
+ - **`buttons: []`**:清空旧按钮配置。
158
+ - **非空数组**:对旧按钮配置做全量替换。
159
+
160
+ ### 6.5 关联视图/报表
161
+
162
+ 新版默认不要通过 `app_views_apply.associated_resources` 配置关联资源。应用级关联资源池和视图展示开关统一走 **`app_associated_resources_apply`** / CLI **`builder associated-resource apply`**。
163
+
164
+ - `builder views apply` **新建视图时默认开启详情页关联查看**:等价于 `asosChartVisible=true`、`limit_type=all`,会展示当前应用级关联资源池里的全部关联视图/报表。
165
+ - **更新已有视图**:未显式传 `associated_resources` 时保留原关联查看状态;需要关闭或改成指定资源时,用 **`builder associated-resource apply --view-configs-file`**,或维护旧配置时显式 patch `associated_resources`。
166
+ - 已有资源的最终口径是 `app_get.associated_resources[].associated_item_id`;它不是 `chart_id`、`chart_key` 或 `view_key`。
167
+ - 新版 CLI 在关联报表时可先传 `chart_id` / `chart_key`,内部会解析为轻流后端需要的 id;创建前先检查是否已有相同 `target_app_key + view_key/chart_key`,已存在时用 `patch_resources`;`client_key` 只在同一次 apply 中可被 `associated_item_refs` 引用,不会持久化。
168
+ - 数据集 BI 报表只能关联已有报表,使用 `report_source: "dataset"`;应用源报表可先用 `builder charts apply` 创建/更新。
169
+ - 关联筛选优先用 `match_mappings`;字段匹配规则见 **[QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./QINGFLOW_CLI_BUILDER_MATCH_RULES.md)**。
170
+
171
+ ---
172
+
173
+ ## 7. `remove_views`
174
+
175
+ - 文件内容为 **JSON 数组**;元素可以是 raw **`view_key`**,也可以是唯一视图显示名。
176
+ - 优先用 **`view_key`** 删除;显示名重名会导致 **`AMBIGUOUS_VIEW`**,需先在 **`app get views`** 里确认。
177
+ - DELETE 发出后,工具会用单个 **`view_key`** 回读验证,而不是再读全量视图列表判断删除结果。
178
+ - 删除结果看 **`verification.by_view[].delete_executed`**、**`readback_status`**、**`safe_to_retry_delete`**:
179
+ - **`readback_status=deleted`**:删除已验证。
180
+ - **`readback_status=unavailable`** 或 **`still_exists`**:删除请求已发出但回读未完全确认,**不要盲目重复删除**;稍后用 `builder app get views` 或对应视图详情确认。
181
+
182
+ ---
183
+
184
+ ## 8. 契约示例(可复制为文件基底)
185
+
186
+ **Table + `visibility`(`minimal_example` 节选)**:
187
+
188
+ ```json
189
+ [
190
+ {
191
+ "name": "全部数据",
192
+ "type": "table",
193
+ "columns": ["项目名称"],
194
+ "visibility": {
195
+ "mode": "workspace",
196
+ "selectors": {},
197
+ "external_mode": "not",
198
+ "external_selectors": {}
199
+ }
200
+ }
201
+ ]
202
+ ```
203
+
204
+ **Gantt(`gantt_example` 节选)**:
205
+
206
+ ```json
207
+ [
208
+ {
209
+ "name": "项目甘特图",
210
+ "type": "gantt",
211
+ "columns": ["项目名称", "开始日期", "结束日期"],
212
+ "start_field": "开始日期",
213
+ "end_field": "结束日期",
214
+ "title_field": "项目名称",
215
+ "filters": [
216
+ {
217
+ "field_name": "状态",
218
+ "operator": "eq",
219
+ "value": "进行中"
220
+ }
221
+ ]
222
+ }
223
+ ]
224
+ ```
225
+
226
+ **Table + 查询条件(节选)**:
227
+
228
+ ```json
229
+ [
230
+ {
231
+ "name": "客户查询视图",
232
+ "type": "table",
233
+ "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
234
+ "query_conditions": {
235
+ "enabled": true,
236
+ "exact": false,
237
+ "hide_before_query": false,
238
+ "rows": [["客户名称", "负责人"], ["创建时间"]]
239
+ }
240
+ }
241
+ ]
242
+ ```
243
+
244
+ ---
245
+
246
+ ## 9. 实测记录(`ead8ims5i401`,`--no-publish`)
247
+
248
+ 内容与仓库 **[views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)** 一致(或历史探针名 **`CLI探针视图_可删`**)。
249
+
250
+ **读视图**:
251
+
252
+ ```bash
253
+ qingflow --json builder app get --app-key ead8ims5i401 views
254
+ ```
255
+
256
+ **应用**:
257
+
258
+ ```bash
259
+ qingflow builder views apply \
260
+ --app-key ead8ims5i401 \
261
+ --no-publish \
262
+ --upsert-views-file ./reference/views_upsert_table_minimal.example.json
263
+ ```
264
+
265
+ **结果摘要**(示例视图名 **`示例表视图_CLI模板`**):`status: success`,`verification.by_view[0].status: created`,返回 **`view_key`**(如 **`ecdk22v65c02`**),`published: false`。
266
+
267
+ ---
268
+
269
+ ## 10. 排障要点
270
+
271
+ | 现象 | 处理 |
272
+ |------|------|
273
+ | 列校验失败 / 无有效业务列 | **`app get fields`** 核对 **`name`**;避免 `columns` 仅含 **§7.1 系统列** |
274
+ | 重名视图 / 删错 | **`app get views`**;更新时带 **`view_key`** |
275
+ | 过滤器未生效疑虑 | 看响应 **`verification.view_filters_verified`**;必要时再 **`app get views`** |
276
+ | 查询条件未生效疑虑 | 看响应 **`verification.view_query_conditions_verified`**;不要把 `query_conditions` 当 `filters` |
277
+ | 按钮/关联资源配置 | 按钮走 **`builder button apply`**;关联视图/报表走 **`builder associated-resource apply`** |
278
+ | 部分失败 | 读 **`views_diff.failed`** 与契约 **execution_notes** 中 **partial_success** |
279
+ | 权限/锁 | 同 [交付 SOP](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)(**`publish verify`**、编辑锁) |
280
+
281
+ ---
282
+
283
+ ## 11. 交叉引用
284
+
285
+ - [views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)(**table** 视图最小 **`upsert`**)
286
+ - [SKILL.md](../SKILL.md):builder 直接输出、鉴权顺序。
287
+ - [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md):系统列、**`publish verify`**、整体交付阶段。
288
+ - [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md):CLI 覆盖与 **`view_id` vs `view_key`** 备忘。
@@ -0,0 +1,40 @@
1
+ # Builder 工作区图标规则
2
+
3
+ 用于应用包、应用、门户的新建与改名改图标场景。
4
+
5
+ ## 默认链路
6
+
7
+ 1. 先读取候选目录:
8
+
9
+ ```bash
10
+ qingflow --json builder icon catalog
11
+ ```
12
+
13
+ 2. 新建应用包、应用、门户时,显式填写 `icon` 和 `color`。
14
+
15
+ 3. 不要使用 `template`;这是通用图标,新建资源会被 CLI 阻断。
16
+
17
+ ## 关键规则
18
+
19
+ - CLI 不会根据业务名称自动猜图标。
20
+ - 智能体必须自己选择业务贴合的 `icon + color`。
21
+ - 创建应用包、应用、门户时缺少 `icon` 或 `color` 会失败。
22
+ - 同批多应用创建时,每个新应用应使用不同 `icon`。
23
+ - 编辑已有资源时,不传 `icon/color` 会保留现状;显式传入时仍会校验合法性。
24
+ - 读取结果里的 `icon_config` 是给 UI/agent 展示用的解构结果,包含 `icon_name`、`icon_color`、`icon_text`、`raw`。
25
+
26
+ ## 示例选择
27
+
28
+ 这些只是候选思路,不是 CLI 默认映射:
29
+
30
+ | 场景 | 可选 icon |
31
+ |---|---|
32
+ | 员工 / 花名册 | `business-personalcard`、`user-group` |
33
+ | 任务 / 待办 | `clipboard-check`、`action-work` |
34
+ | 工时 / 时间 | `clock`、`action-hourglass-full` |
35
+ | 商机 / 增长 | `business-graph`、`business-trend-up` |
36
+ | 订单 / 交付 | `delivery-box-1`、`shopping-bag` |
37
+ | 回款 / 收款 | `money-receipt-2-1`、`money-wallet-1` |
38
+ | 门户 / 数据大屏 | `view-grid`、`chart-square-bar` |
39
+
40
+ 颜色候选以 `builder icon catalog` 返回为准,例如 `emerald`、`blue`、`azure`、`orange`、`red`。