@qingflow-tech/qingflow-cli 1.1.61 → 1.1.62-beta.2

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 (97) hide show
  1. package/README.md +3 -3
  2. package/package.json +2 -1
  3. package/pyproject.toml +4 -1
  4. package/skills/qingflow-cli/SKILL.md +112 -3
  5. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +1 -1
  6. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +6 -258
  7. package/skills/qingflow-cli/reference/builder/20-build-complete-system.md +3 -3
  8. package/skills/qingflow-cli/reference/builder/30-schema-fields.md +22 -5
  9. package/skills/qingflow-cli/reference/builder/70-portal.md +111 -36
  10. package/skills/qingflow-cli/reference/builder/README.md +2 -2
  11. package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md +3 -3
  12. package/skills/qingflow-cli/reference/examples/portal/portal_apply_v1alpha1.example.json +100 -0
  13. package/skills/qingflow-cli/reference/examples/portal/portal_sections_all_types.example.json +22 -6
  14. package/src/qingflow_mcp/app_form_compat.py +3 -0
  15. package/src/qingflow_mcp/app_form_validator.py +89 -20
  16. package/src/qingflow_mcp/builder_facade/app_form.py +629 -112
  17. package/src/qingflow_mcp/builder_facade/models.py +213 -15
  18. package/src/qingflow_mcp/builder_facade/portals_schema.py +397 -0
  19. package/src/qingflow_mcp/builder_facade/schemas/app_form/manifest.json +15 -1
  20. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/complete.json +112 -38
  21. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/address.json +31 -8
  22. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_classification.json +146 -0
  23. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_extraction.json +146 -0
  24. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_generation.json +146 -0
  25. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_document_parsing.json +146 -0
  26. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_generation.json +146 -0
  27. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_recognition.json +146 -0
  28. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_machine_translation.json +146 -0
  29. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_text_summary.json +146 -0
  30. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/amount.json +6 -10
  31. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/attachment.json +33 -10
  32. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/code_block.json +6 -10
  33. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/data_relation.json +11 -18
  34. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date.json +4 -8
  35. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date_duration.json +146 -0
  36. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/datetime.json +4 -8
  37. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/department.json +6 -10
  38. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/email.json +4 -8
  39. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/embed_field.json +146 -0
  40. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/image_select.json +146 -0
  41. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/link.json +4 -8
  42. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/location.json +146 -0
  43. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/long_text.json +4 -8
  44. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/member.json +6 -10
  45. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/multi_select.json +4 -8
  46. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/number.json +6 -10
  47. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ocr.json +146 -0
  48. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/phone.json +4 -8
  49. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/q_linker.json +8 -12
  50. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/relation.json +73 -15
  51. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/rich_text.json +146 -0
  52. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_choice.json +4 -8
  53. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_select.json +4 -8
  54. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/subtable.json +90 -29
  55. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/text.json +4 -8
  56. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/formula.json +43 -0
  57. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/summary.json +27 -19
  58. package/src/qingflow_mcp/builder_facade/schemas/portals/manifest.json +59 -0
  59. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/complete.json +1397 -0
  60. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/carousel.json +193 -0
  61. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/chart.json +643 -0
  62. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/favourite.json +203 -0
  63. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/filter.json +331 -0
  64. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/grid.json +265 -0
  65. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/link.json +131 -0
  66. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/task.json +199 -0
  67. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/text.json +123 -0
  68. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/view.json +196 -0
  69. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/summary.json +800 -0
  70. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/complete.json +1 -1
  71. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/display.json +1 -1
  72. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/summary.json +1 -1
  73. package/src/qingflow_mcp/builder_facade/service.py +1367 -92
  74. package/src/qingflow_mcp/cli/commands/builder.py +120 -5
  75. package/src/qingflow_mcp/cli/formatters.py +11 -0
  76. package/src/qingflow_mcp/cli/main.py +90 -2
  77. package/src/qingflow_mcp/cli/permission_gate.py +59 -0
  78. package/src/qingflow_mcp/cloud_context.py +16 -1
  79. package/src/qingflow_mcp/entity_permissions.py +10 -0
  80. package/src/qingflow_mcp/permission_catalog.json +1210 -0
  81. package/src/qingflow_mcp/public_surface.py +69 -8
  82. package/src/qingflow_mcp/response_trim.py +2 -1
  83. package/src/qingflow_mcp/server.py +12 -6
  84. package/src/qingflow_mcp/server_app_builder.py +43 -10
  85. package/src/qingflow_mcp/server_app_user.py +9 -5
  86. package/src/qingflow_mcp/server_cloud.py +43 -7
  87. package/src/qingflow_mcp/session_store.py +14 -1
  88. package/src/qingflow_mcp/solution/compiler/icon_utils.py +73 -0
  89. package/src/qingflow_mcp/solution/executor.py +5 -2
  90. package/src/qingflow_mcp/tool_catalog.py +388 -0
  91. package/src/qingflow_mcp/tool_catalog_i18n.py +184 -0
  92. package/src/qingflow_mcp/tool_policy.py +191 -0
  93. package/src/qingflow_mcp/tools/ai_builder_tools.py +118 -20
  94. package/src/qingflow_mcp/tools/base.py +1 -0
  95. package/src/qingflow_mcp/tools/portal_tools.py +4 -54
  96. package/src/qingflow_mcp/tools/portal_writer.py +59 -0
  97. 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-beta.2
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-beta.2 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-beta.2 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-beta.2",
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",
@@ -16,6 +16,7 @@
16
16
  "pyproject.toml",
17
17
  "entry_point.py",
18
18
  "src/qingflow_mcp/**/*.py",
19
+ "src/qingflow_mcp/permission_catalog.json",
19
20
  "src/qingflow_mcp/builder_facade/schemas/**/*.json",
20
21
  "src/qingflow_mcp/py.typed",
21
22
  "qingflow",
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.62b2"
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",
@@ -66,9 +67,11 @@ where = ["src"]
66
67
 
67
68
  [tool.setuptools.package-data]
68
69
  qingflow_mcp = [
70
+ "permission_catalog.json",
69
71
  "py.typed",
70
72
  "builder_facade/schemas/app_form/**/*.json",
71
73
  "builder_facade/schemas/views/**/*.json",
74
+ "builder_facade/schemas/portals/**/*.json",
72
75
  ]
73
76
 
74
77
  [tool.pytest.ini_options]
@@ -3,21 +3,66 @@ name: qingflow-cli
3
3
  description: |
4
4
  【强制】在执行或编排任何 qingflow CLI 命令前必须优先加载本 Skill。
5
5
  Qingflow CLI 主入口:规定命令执行与 JSON 落盘方式,并把普通应用数据默认路由到 data;task、builder、import、日志、附件和代码块按专项参考执行。
6
+ Qingflow CLI 包以本 Skill 作为 CLI 主入口;record/app-builder/task/workflow 等相关说明按场景组织在 reference 子目录。
7
+ 指导安装、执行上下文失败恢复、查询与写入;规定 task/record/import/builder 查询落盘;覆盖普通成员读数、字段 kind 与数据形态、任务上下文、批量导入、record access/list/get/insert/update/delete 与管理端边界。
8
+ Builder SOP 按智能体任务路径组织:完整系统、单应用、AppForm、视图、报表、门户、关联资源、流程、发布校验;表单字段、分组、布局和应用设置统一使用 versioned AppForm;按钮随视图 action_buttons 声明;更新动作并入对应资源文档,批量读/批量写/局部改依各资源契约执行;视图 apply 每次仅处理一个视图的一种操作,不支持批量创建或混合操作;明细见「关联文件」表与文末命令索引。
6
9
  ---
7
10
 
8
11
  # Qingflow CLI 使用技能
9
12
 
10
13
  > **Skill 版本**:`qingflow-skills-2026.10.09.01`。CLI 实际版本与安装路径以 `qingflow --json version` 为准。
11
14
 
12
- 本 Skill 负责 CLI 入口、文件约定和业务分流。已知 `app_key` 时直接执行 `data query/get`。只有应用名称时,先用 `qingflow --json app list --query "应用名称"` 查找当前工作区的可见应用,并核对返回项的 `app_name/title`;目标明确且唯一时取其 `app_key` 再查询,否则请用户确认。不要把应用名称直接传给 `--app-key`,也不要为定位名称转向 builder 或切换工作区。字段能力、权限范围与下一步动作以当前工具 schema、data 响应和 `hints` 为准。
15
+ 本 Skill 负责 CLI 入口、文件约定和业务分流。确认可用工具后,已知 `app_key` 时直接执行 `data query/get`。只有应用名称时,先用 `qingflow --json app list --query "应用名称"` 查找当前工作区的可见应用,并核对返回项的 `app_name/title`;目标明确且唯一时取其 `app_key` 再查询,否则请用户确认。不要把应用名称直接传给 `--app-key`,也不要为定位名称转向 builder 或切换工作区。字段能力、权限范围与下一步动作以当前工具 schema、data 响应和 `hints` 为准。
13
16
 
14
17
  首次解析 `data query/get` 响应前,阅读 [data 响应结构与解析](./reference/data/README.md#响应结构与解析),按同次响应中的 schema 与记录结构读取目标字段。
15
18
 
16
- 需要向用户交付业务页面入口时,遵循 [Qingflow Common](../qingflow-common/SKILL.md) 的链接规则。
19
+ ## 关联文件
20
+
21
+
22
+ | 文件 | 说明 |
23
+ | ------------------------------------------------------------------------------------------------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
24
+ | `manifest.yaml` | 技能清单 |
25
+ | [reference/00-INDEX.md](./reference/00-INDEX.md) | **总导航**:按用户目标选择 record / task / builder 文档;复杂任务先读 |
26
+ | [reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md) | **普通成员**主线:最短路径、`view_id`、与管理命令的差异预期 |
27
+ | [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 的形态对照 |
28
+ | [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **普通应用数据读取**:`data query` 获取记录和 schema → 按需 `data get` 读取单条;附件下载见 [data 操作说明](./reference/data/README.md) |
29
+ | [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` 作为主定位参数 |
30
+ | [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` |
31
+ | [reference/builder/README.md](./reference/builder/README.md) | **Builder 总导航**:完整系统、单应用、字段、布局、视图、报表、门户、按钮/关联资源、流程、发布校验 |
32
+ | [reference/builder/10-build-single-app.md](./reference/builder/10-build-single-app.md) | **单应用搭建主入口**:一个应用端到端交付顺序 |
33
+ | [reference/builder/20-build-complete-system.md](./reference/builder/20-build-complete-system.md) | **完整系统/应用包主入口**:多应用、跨应用 relation、门户闭环 |
34
+ | [reference/builder/30-schema-fields.md](./reference/builder/30-schema-fields.md) | **字段 / schema**:字段类型、直觉别名、数据标题/封面、schema 创建与更新 |
35
+ | [reference/builder/40-layout.md](./reference/builder/40-layout.md) | **布局维护**:仅用于已有应用的分组、`rows` 矩阵、布局修复;新建应用布局写在 `form` 内 |
36
+ | [reference/builder/50-views.md](./reference/builder/50-views.md) | **视图**:先读 schema,一次写一个视图对象;查询面板和按钮约束见该文 |
37
+ | [reference/builder/60-charts.md](./reference/builder/60-charts.md) | **报表 / QingBI**:指标卡、图表、语义聚合、筛选、排序、更新 |
38
+ | [reference/builder/70-portal.md](./reference/builder/70-portal.md) | **门户**:标准工作台、业务入口、指标、图表、视图组件、发布 |
39
+ | [reference/builder/80-buttons-associated-resources.md](./reference/builder/80-buttons-associated-resources.md) | **关联资源 / 非主链路按钮维护**:关联视图/报表、`match_mappings`、上下文传参;按钮配置看视图文档 `action_buttons`;创建自定义按钮前先 `button get --button-text` 查重复用 |
40
+ | [reference/builder/90-workflow.md](./reference/builder/90-workflow.md) | **流程**:WorkflowSpec、`patch_nodes`、角色/成员、流程回读 |
41
+ | [reference/builder/99-publish-verify.md](./reference/builder/99-publish-verify.md) | **发布与回读**:`publish verify`、partial/readback 处理、最终汇报口径 |
42
+ | [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) |
43
+ | [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` 仅用于失败后诊断可写字段/路径 |
44
+ | [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` |
45
+ | [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**:最终统计结论、分析报告、趋势/排名/比例/分布统一走 `data query --all --output csv -> Python/pandas` |
46
+ | [reference/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) | **底层交付参考**:历史完整 SOP、权限、系统列和工具细节;不是主入口 |
47
+ | [reference/builder/reference/workspace-icons.md](./reference/builder/reference/workspace-icons.md) | **图标参考**:`builder icon catalog`;新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color` |
48
+ | [reference/builder/reference/match-rules.md](./reference/builder/reference/match-rules.md) | **统一筛选 / 条件写法**:`filters`、`visible_when`、QingBI 图表筛选、工作流条件、`match_mappings`、`field_mappings` 的 `operator/value` 规则 |
49
+ | [reference/builder/workflow/README.md](./reference/builder/workflow/README.md) | **工作流搭建**:已有应用的流程建模、节点配置、`builder flow apply` 与 `patch_nodes` |
50
+ | [reference/builder/code-integrations/README.md](./reference/builder/code-integrations/README.md) | **代码块 / Q-Linker 配置**:字段别名、绑定、输入字段插入和配置排障 |
51
+ | [reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md) | **管理员**:检索、导入等与成员差异(主技能正文不展开) |
52
+ | [reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md) | CLI 实测与 argparse/服务端对齐备忘 |
53
+ | [reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md) | **可选**:全角色「一次可复制」分项模板;默认执行技能**不必**打开 |
54
+ | [scripts/find-app-by-keyword.py](./scripts/find-app-by-keyword.py) | **旧版 CLI 兼容脚本**:当 `app list --query` 不可用时,用 `app list` 本地解析;默认优先使用 `qingflow --json app list --query <关键词>` |
55
+ | [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 <关键词>` |
56
+
57
+ ## 工具使用指引
58
+
59
+ 需要确认本轮可用工具时,执行 `qingflow --json tools permissions`。根据 `allowed_tools`、`exempt_tools` 选择符合目标的工具,不执行 `denied_tools` 中的操作;`entrypoints` 给出对应 CLI 命令路径。结果可落盘,只读取当前需要的项。
60
+
61
+ 已有有效授权信息时直接复用,不在每条命令或每轮任务前重复查询。检查未成功时不开展业务操作,按本轮交付约定处理;仅分析已有资料时无需使用 CLI。
17
62
 
18
63
  ## CLI 执行与 JSON 落盘
19
64
 
20
- 1. 已知业务目标时直接执行目标命令,不固定前置 `auth whoami`、`workspace get` 或 `workspace select`。只有业务命令明确返回未登录、会话失效或工作区错误后,才恢复上下文并重试原命令。
65
+ 1. 确认可用工具后,已知业务目标时直接执行目标命令,不固定前置 `auth whoami`、`workspace get` 或 `workspace select`。只有已获准的业务命令明确返回未登录、会话失效或工作区错误后,才按本轮身份与交互约束恢复上下文;未获准的操作不进行认证恢复。写请求是否可重试仍以下述执行结果约束为准。
21
66
  2. 自动化始终使用 `--json`。`data query/get`、task 查询、record 日志/附件上下文、import 与 builder 大响应必须写入本地文件,禁止把整段 JSON 或 CSV 打到上下文。
22
67
  3. `where`、`sort`、`columns`、`items`、`fields` 等结构化参数写入独立 JSON 文件,再通过 `--*-file` 传入。工具已暴露参数 schema 时直接使用;只有命令缺失或参数被拒绝时才读取对应 `--help`。
23
68
  4. 多任务或目录可能变化时使用绝对路径;单线程本地执行至少先固定 `pwd`。解析时只读取目标字段,不要 `cat` 大文件。
@@ -67,6 +112,70 @@ echo "$QINGFLOW_CREDENTIAL" | qingflow --profile default auth use-credential \
67
112
  qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
68
113
  ```
69
114
 
115
+ 常用参数:`--credential-stdin`、`--password-stdin`、`--persist` / `--forget-persisted`;详见 `qingflow auth --help`。
116
+
117
+ ---
118
+
119
+ ## 输出落盘规则(task / record / import / builder 查询类)
120
+
121
+ 以下 **必须** 将标准输出重定向到文件(如 `tmp/qingflow_*.json`),**禁止**把终端大 JSON 直接交给 LLM;后续用读文件 / 脚本处理。
122
+
123
+
124
+ | 子系统 | 必须落盘的子命令 |
125
+ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
126
+ | **task** | `list`、`get`、`log`、`report` |
127
+ | **import** | `template`、`verify`、`repair`、`start`、`status`(**`verify` / `start` 链依赖本机 `~/.qingflow-mcp` 校验/任务落盘,自动化须开放写权限**) |
128
+ | **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 响应 |
129
+ | **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` 响应体大时同样建议落盘** |
130
+
131
+
132
+ **规则摘要**
133
+
134
+ - 重定向示例:`qingflow --json record list … > tmp/qingflow_records.json`
135
+ - 线上真实测试、子智能体并行任务、批量 `--*-file` 入参优先使用**绝对路径**,或在命令前固定确认 `pwd`;不要假设子智能体当前目录与主线程一致。
136
+ - `auth`、`workspace`、`app`、`portal`、`view`、**非上述列出的**等,可直接终端查看或按需落盘。
137
+ - 错误在使用 **`--json`** 时多在 **stdout** 的 JSON 信封里;stderr 多为 argparse usage。
138
+
139
+ ---
140
+
141
+ ## 应用数据:查询与读取(默认路径)
142
+
143
+ 已知 `app_key` 时直接执行 `qingflow --json data query --app-key <APP_KEY>`;首次查询保留默认 schema,根据响应中的 `field_capabilities` 和 `hints` 决定筛选、分页或停止。定位到 `record_id` 后,按需执行 `qingflow --json data get --app-key <APP_KEY> --record-id <RECORD_ID>`;下载附件时加 `--download-attachments`。
144
+
145
+ 参数与附件处理见 [data 操作说明](./reference/data/README.md)。详情页引用、关联资源和完整日志见 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md);最终统计结论按 [数据分析说明](./reference/record/analysis/README.md) 使用 `data query --all --output csv`。
146
+
147
+ ---
148
+
149
+ ## 应用记录:创建记录工作流(申请节点 → 写入)
150
+
151
+ 推荐顺序:
152
+
153
+ 1. **`record schema insert`**:先读取 insert-ready schema、`required_fields`、`payload_template`、`format_hint`、`example_value`、联动与运行时必填提示。
154
+ 2. **`record insert --items-file`**:单条也是 `items` 数组的一行;成员、部门、关联字段优先写自然语言(如 `"张三"`、`"直销部"`、`"海军军医大学"`),仅在返回 `needs_confirmation` 时再让用户确认候选。
155
+ 3. **写后读回**:单条重要数据用 `record get`,批量样本用 `record list` 或业务视图校验;`partial_success` 只重试失败行,不重放全批。
156
+
157
+ **细则、字段 JSON 结构与排障**见 **[reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**。
158
+
159
+ ---
160
+
161
+ ## 应用记录:更新记录工作流(详情 → 写入)
162
+
163
+ 主链路是先读详情,再直接提交用户要求修改的 key/value。不要把 `record schema update` 当成更新前置步骤:
164
+
165
+ 1. **`record get`** → 拿 **`record_id`、当前值、fields[].title / field_id / kind**;已知前端/自定义视图时必须带同一个 **`--view-id`**。未知时 CLI 会先试默认 `system:all`,权限拒绝后再尝试可访问视图,但智能体仍优先从 `app get.accessible_views` 取 view。
166
+ 2. 智能体根据 `record get.fields[]` 和用户要求,组一个只包含待改字段的 JSON 对象(标题 → 值)。字段必须来自当前详情上下文的 `fields[]`;带 `--view-id` 时,视图隐藏的字段不要强写。若用户要求改的字段不在当前 `record get.fields[]`,先换到包含该字段的视图/详情上下文,或用 `record schema update` 做失败诊断。
167
+ 3. **`record update`** → **`--record-id` + `--fields-file`**,已知前端视图时同样带 **`--view-id`** 让 CLI 优先走该 view;批量用 **`--items-file`**(**`--dry-run` 仅批量**)。
168
+ 4. 只有字段范围不清、候选歧义、或 `record update` 失败时,才用 **`record schema update`** 诊断本条记录的 **`writable_fields / payload_template / available_update_routes`**;已知前端视图时同样带 **`--view-id`**,让诊断优先探测同一个详情页上下文。
169
+
170
+ **更新路径**:`record update` 会自动先尝试数据管理员直改,再 fallback 到前端同源的 custom view 详情编辑路径;如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑,最后会尝试 workflow save-only。成功时只需要读 **`status / update_route / verification_status`**;失败时再读失败原因与路线诊断。不要把中间 route 或辅助 schema/readback 探测的 40002 / 40027 / 404 当作最终失败。
171
+
172
+ **大号 `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)** 使用 `data query --all --output csv -> Python/pandas`。
173
+
174
+ **命令模板、批量 `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)**。
175
+
176
+ **成员 / 部门候选排障**:若成员、部门字段返回 `needs_confirmation` 或候选不清,使用 `qingflow record member-candidates` / `qingflow record department-candidates`;它们优先走表单字段候选范围接口(与前端选择器一致)。不要改用通讯录管理类查询去“补候选”,那会把普通成员误带到 ContactAuth 管理权限链路。
177
+
178
+ **部门名筛选 / 写入**:`record list/access/analyze/insert/update` 遇到部门字段时可直接传部门名或候选对象;CLI 会优先走成员可见的目录搜索解析部门。不要先用通讯录管理接口查询部门 id,否则普通成员容易被 ContactAuth 错误阻挡。
70
179
  ### 字段筛选
71
180
 
72
181
  先运行一次不带 `columns` 的 query,从返回的 `schema` 与递归 `field_capabilities` 准确定位 `field_id`,并确认该字段暴露的 `filter_operators` 与 `value_shape`。再写筛选文件:
@@ -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|<类型>`。
@@ -1,6 +1,6 @@
1
1
  # Build Complete System
2
2
 
3
- Read this when the user asks for a complete business system, app package, multiple modules, or related apps.
3
+ Call `qingflow-system-builder` before building a complete business system, app package, multiple modules, or related apps. Use the command order below only after that skill is loaded.
4
4
 
5
5
  ## Scope
6
6
 
@@ -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