@qingflow-tech/qingflow-cli 1.1.61-beta.7 → 1.1.61-beta.9

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.
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-beta.7
10
+ npm install @qingflow-tech/qingflow-cli@1.1.61-beta.9
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-beta.7 qingflow
24
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.9 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-beta.7 qingflow-skills install --agent codex --scope user --copy
65
+ npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.9 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-beta.7",
3
+ "version": "1.1.61-beta.9",
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.61b7"
7
+ version = "1.1.61b9"
8
8
  description = "User-authenticated MCP server for Qingflow"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -12,7 +12,7 @@ description: |
12
12
 
13
13
  > **Skill 版本**:`qingflow-skills-2026.10.09.01`。CLI 实际版本与安装路径以 `qingflow --json version` 为准。
14
14
 
15
- 本 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` 为准。
16
16
 
17
17
  首次解析 `data query/get` 响应前,阅读 [data 响应结构与解析](./reference/data/README.md#响应结构与解析),按同次响应中的 schema 与记录结构读取目标字段。
18
18
 
@@ -53,9 +53,16 @@ description: |
53
53
  | [reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md) | **可选**:全角色「一次可复制」分项模板;默认执行技能**不必**打开 |
54
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
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。
62
+
56
63
  ## CLI 执行与 JSON 落盘
57
64
 
58
- 1. 已知业务目标时直接执行目标命令,不固定前置 `auth whoami`、`workspace get` 或 `workspace select`。只有业务命令明确返回未登录、会话失效或工作区错误后,才恢复上下文并重试原命令。
65
+ 1. 确认可用工具后,已知业务目标时直接执行目标命令,不固定前置 `auth whoami`、`workspace get` 或 `workspace select`。只有已获准的业务命令明确返回未登录、会话失效或工作区错误后,才按本轮身份与交互约束恢复上下文;未获准的操作不进行认证恢复。写请求是否可重试仍以下述执行结果约束为准。
59
66
  2. 自动化始终使用 `--json`。`data query/get`、task 查询、record 日志/附件上下文、import 与 builder 大响应必须写入本地文件,禁止把整段 JSON 或 CSV 打到上下文。
60
67
  3. `where`、`sort`、`columns`、`items`、`fields` 等结构化参数写入独立 JSON 文件,再通过 `--*-file` 传入。工具已暴露参数 schema 时直接使用;只有命令缺失或参数被拒绝时才读取对应 `--help`。
61
68
  4. 多任务或目录可能变化时使用绝对路径;单线程本地执行至少先固定 `pwd`。解析时只读取目标字段,不要 `cat` 大文件。
@@ -5,7 +5,7 @@
5
5
  ```bash
6
6
  qingflow --json builder portal get --dash-key DASH_KEY --schema-kind complete > portal.json # 更新前先读
7
7
  qingflow --json builder portal validate --file portal.json # 零后端离线校验
8
- qingflow builder portal apply --file portal.json --schema-version v1alpha1 [--dash-key DASH_KEY] [--no-publish]
8
+ qingflow builder portal apply --file portal.json --schema-version v1alpha1 [--dash-key DASH_KEY]
9
9
  ```
10
10
 
11
11
  契约与九类组件专项 Schema:`qingflow --json builder portal schema --schema-kind complete|<类型>`。
@@ -24,7 +24,7 @@ portal list/get if updating -> verify apps/views and read chart lists only when
24
24
  - Read the contract itself: `qingflow --json builder portal schema --schema-kind summary|complete|<component>`; every component type (`chart|view|grid|filter|text|link|carousel|task|favourite`) has a self-contained schema — fetch it before guessing config keys.
25
25
  - `builder portal get` defaults to `--schema-kind summary` and returns a canonical `declaration` (the round-trip anchor for replay tooling). Use `--schema-kind raw` for the legacy normalized response and `--schema-kind complete` for the full declaration.
26
26
  - Offline validation: `qingflow --json builder portal validate --file decl.json` (accepts `-` for stdin; zero backend calls). Fix issues before applying.
27
- - Apply main form: `qingflow builder portal apply --file decl.json --schema-version v1alpha1 [--no-publish]`. Legacy patch parameters (`--sections-file`, `--visibility-file`, ...) still work in a compatibility window but emit a deprecation notice; do not use them in new automations. `--payload-file` (raw DTO passthrough) is legacy-only.
27
+ - Apply main form: `qingflow builder portal apply --file decl.json --schema-version v1alpha1` (apply always publishes automatically; there is no draft-only mode). Legacy patch parameters (`--sections-file`, `--visibility-file`, ...) still work in a compatibility window but emit a deprecation notice; do not use them in new automations. `--payload-file` (raw DTO passthrough) is legacy-only.
28
28
 
29
29
  ## Demo files
30
30
 
@@ -79,7 +79,7 @@ Recommended standard workbench skeleton:
79
79
 
80
80
  ## Update existing portal
81
81
 
82
- - Prefer the declaration-file form: `builder portal apply --file decl.json --schema-version v1alpha1 --dash-key K --no-publish` (the file may omit `dash_key` and pass it via `--dash-key`; do not send `package_id` for updates).
82
+ - Prefer the declaration-file form: `builder portal apply --file decl.json --schema-version v1alpha1 --dash-key K` (the file may omit `dash_key` and pass it via `--dash-key`; do not send `package_id` for updates; apply publishes automatically).
83
83
  - Read the current declaration first with `builder portal get --dash-key K --schema-kind complete`, edit it, `builder portal validate --file`, then apply. `sections` is full-replace semantics.
84
84
  - `patch_sections[]` (via `--patch-sections-file`, compatibility window) remains for targeted section changes when a full declaration round-trip is not practical.
85
85
  - `patch_sections[]` selectors may use `order`, `chart_ref.chart_id`, `chart_ref.chart_key`, or `view_ref.view_key`; chart sections read back from portal often only include `chart_id`, so patching by `chart_id` is valid and does not require `app_key`.
@@ -90,7 +90,7 @@ Recommended standard workbench skeleton:
90
90
 
91
91
  搭建侧稳定入口:**`qingflow builder portal`**:`list` / `get` / **`apply`** / **`delete`**(与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同,见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](../core/QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**)。
92
92
 
93
- 实现要点来自 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` 声明式写入受控支持(rules 非空,历史「不落库」实测为空规则读面不可见,见 §3.4)**。另已对测试包 **`1414907`** 实跑 **`portal delete`**:临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
93
+ 实现要点来自 CLI 打包内的 `builder_facade/models.py`(`PortalApplyRequest`、`PortalSectionPatch`)、`builder_facade/service.py`(`portal_apply` / `portal_delete`)、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**:**新建**、**更新**(网关 **503** 恢复后已重试成功;历史记录中的 `--publish/--no-publish` flag 已移除,apply 一律发布)、**五类区块可稳定落库**;**`filter` 声明式写入受控支持(rules 非空,历史「不落库」实测为空规则读面不可见,见 §3.4)**。另已对测试包 **`1414907`** 实跑 **`portal delete`**:临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
94
94
 
95
95
  > **权限**:**更新**需 **`edit_portal`**;**新建**按后端 `DashCtrl.createDash` 链路只预检目标包 **`add_app`**,不额外要求包 **`edit_app`**。失败时参见主技能与 **ADMIN** 速查。
96
96
 
@@ -123,7 +123,6 @@ qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
123
123
 
124
124
  | 参数 | 说明 |
125
125
  |------|------|
126
- | **`--publish` / `--no-publish`** | 默认 **`--publish`**。仅 **`--no-publish`** 时不会调用发布接口;契约说明 **`publish=false` 不宣称线上已变**。 |
127
126
  | **`--file`**(主形态) | 完整门户声明 JSON 对象(支持 **`-`** stdin);与 patch 参数互斥;声明内可带 **`schema_version`**。 |
128
127
  | **`--schema-version`** | 固定声明契约版本(缺省读文件内 `schema_version`,再缺省 latest)。传入时声明先过 complete schema 离线校验,**`INVALID_SPEC` 不写**。 |
129
128
  | **`--payload-file`**(旧) | 完整门户 JSON 对象透传(兼容窗口);新代码改用 **`--file`**。标准字段写 `dash_name`。 |
@@ -318,7 +317,7 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或 **`chart_re
318
317
 
319
318
  ### 3.5 **`grid` / `text` / `link` / `view`**
320
319
 
321
- - **grid**:**`config`** 并入 **`gridConfig`**;业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`。空 `config` 或空 `items` 只会生成空入口容器,并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
320
+ - **grid**:**`config`** 并入 **`gridConfig`**;业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`——**`linkFormType` 缺省时编译器按 1(数据列表)补齐**(缺失会让前端跳转目标为空、入口无法点击);1=数据列表、2=表单页。空 `config` 或空 `items` 只会生成空入口容器,并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
322
321
  - **text** / **link**:**`text`** / **`url`** 必填。
323
322
  - **view**:**`view_ref`**;**`view_key`** 来自 **`builder app get views`**。
324
323
 
@@ -334,9 +333,9 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或 **`chart_re
334
333
 
335
334
  ---
336
335
 
337
- ## 5. 新建最小例(`--no-publish`)
336
+ ## 5. 新建最小例
338
337
 
339
- 见上文 **§2** 与 **`visibility`** 最小对象;**`sections`** 可先用 **单块 `view`**。成功后拿 **`dash_key`** 再 **更新 / 发布**。
338
+ 见上文 **§2** 与 **`visibility`** 最小对象;**`sections`** 可先用 **单块 `view`**。apply 一律自动发布,成功后拿 **`dash_key`** 直接迭代更新。
340
339
 
341
340
  ---
342
341
 
@@ -361,9 +360,9 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
361
360
 
362
361
  ---
363
362
 
364
- ## 8. **发布**(`--publish`)
363
+ ## 8. **发布**(apply 一律发布)
365
364
 
366
- - **默认会发布**:未显式 **`--no-publish`** 即 **`publish: true`**;公开入口仍是 **`portal_apply`**,发布动作由工具内部执行并回读 **`being_draft=false`**。**注意**:对**已发布门户**用 **`--no-publish`** 更新会把发布状态**降回草稿**(草稿写了、线上态被覆盖标记)——需要保留线上态的试写/迭代不要带 **`--no-publish`** 对已发布门户提交,或写完后显式补发布。
365
+ - **不存在「不发布」场景**:`portal apply` 写后**总是自动发布**并回读线上态(`--publish/--no-publish` flag 与声明内 `publish` 字段均已移除;声明里写 `publish: false` 会被明确拒绝)。门户不会停留在草稿-only 状态,也不会出现「apply 成功但工作台导航看不到」的情况。
367
366
  - **已发布线索**:成功路径上 **`published: true`**;**`live_result.publishStatus`** 常见 **`2`** 表示已发布(以你环境枚举为准)。
368
367
  - **`partial_success` + `PORTAL_READBACK_PENDING`**:草稿/线上 **组件数量或元数据** 与「本次期望」不一致时会出现;**`PORTAL_*_VERIFICATION_INCOMPLETE`** 警告。应 **`builder portal get --dash-key …`**(草稿与 **`--no-being-draft` 线上**)**肉眼核对**区块是否齐全,而不是仅信 **`verified: true`**。
369
368
  - **网关 503**:**与 CLI 无关**;环境恢复后重试 **`portal get` / `portal apply`**。(本轮在网关恢复后 **`portal apply` 已成功**。)
@@ -374,10 +373,10 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
374
373
 
375
374
  | 步骤 | 命令要点 | 结果 |
376
375
  |------|-----------|------|
377
- | 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、`--no-publish`、单 **view** | **`dash_key`: `ecdcell64s02`** |
378
- | 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**;当时 filter 组合全部**空 rules** → 读面不可见(**§3.4** 机制,非后端拒绝;现空 rules 已被模型层阻断) |
376
+ | 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、单 **view**(历史记录,当时带 `--no-publish`;该 flag 已移除) | **`dash_key`: `ecdcell64s02`** |
377
+ | 503 后重试 | **`--dash-key ecdcell64s02`** + 含 **filter** 的六类 **`sections-file`**(历史记录) | **`published: true`**;当时 filter 组合全部**空 rules** → 读面不可见(**§3.4** 机制,非后端拒绝;现空 rules 已被模型层阻断) |
379
378
  | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合(历史记录,全部空 rules) | **回读恒为 1 块(仅 `type: 9`)**——空规则读面不可见;含 rules 的声明式写入已由 ws40013 基准验证 |
380
- | **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)**(**grid / text / link / view / chart**) | **`status: success`**,**`types: [2,4,5,9,10]`**,**`published: true`** |
379
+ | **稳定可复现** | **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)**(**grid / text / link / view / chart**) | **`status: success`**,**`types: [2,4,5,9,10]`**,**`published: true`** |
381
380
  | 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**,**`delete_executed: true`**,**`readback_status: deleted`**,**`summary.removed: 1`** |
382
381
 
383
382
  **推荐工作台模板示例**:[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)。正式业务门户优先复制这个文件的行布局。
@@ -2774,6 +2774,14 @@ class PortalApplyRequest(StrictModel):
2774
2774
  payload = dict(value)
2775
2775
  payload.pop("schema_version", None)
2776
2776
  payload.pop("schemaVersion", None)
2777
+ # 不发布场景已移除(负责人决策):apply 一律发布。显式 false 明确拒绝,
2778
+ # true/缺省按键消费走默认行为(publish 字段恒 true,仅保留内部默认)。
2779
+ if payload.get("publish") is False:
2780
+ raise ValueError(
2781
+ "portal apply always publishes; the draft-only (publish=false) scenario has been "
2782
+ "removed — delete the publish field from the declaration"
2783
+ )
2784
+ payload.pop("publish", None)
2777
2785
  # schema 文档声明的别名补全(dashKey/dashName):此前条件判断里出现了 dashName
2778
2786
  # 却从未消费,别名声明撞上 StrictModel 被拒,形成 validate 提示与 apply 行为
2779
2787
  # 不一致的观感(实测反馈失败二)。canonical 键优先;别名始终被消费(与 canonical
@@ -50,7 +50,7 @@
50
50
  "publish": {
51
51
  "type": "boolean",
52
52
  "default": true,
53
- "publishCompleteDescription": "apply 后是否发布(true=写后发布并回读线上态;false=仅落草稿)。这是生命周期动作参数,不属于声明内容,幂等重放时用 false。注意:对已发布门户用 false 更新会把发布状态降回草稿——需要保留线上态时不要用 false 试写。"
53
+ "publishCompleteDescription": "apply 一律自动发布(写后发布并回读线上态),不存在草稿-only 门户。本字段已废弃:显式 false 会被拒绝,true/缺省等同默认行为。"
54
54
  },
55
55
  "icon": {
56
56
  "type": "string",
@@ -1119,7 +1119,7 @@
1119
1119
  "integer",
1120
1120
  "null"
1121
1121
  ],
1122
- "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用)。",
1122
+ "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用):1=数据列表,2=表单页。缺省按 1(数据列表)——缺失时前端跳转目标为空、入口无法点击。",
1123
1123
  "x-backend": "ComponentGridItemInfo.linkFormType"
1124
1124
  },
1125
1125
  "linkDashKey": {
@@ -112,7 +112,7 @@
112
112
  "integer",
113
113
  "null"
114
114
  ],
115
- "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用)。",
115
+ "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用):1=数据列表,2=表单页。缺省按 1(数据列表)——缺失时前端跳转目标为空、入口无法点击。",
116
116
  "x-backend": "ComponentGridItemInfo.linkFormType"
117
117
  },
118
118
  "linkDashKey": {
@@ -49,7 +49,7 @@
49
49
  "publish": {
50
50
  "type": "boolean",
51
51
  "default": true,
52
- "publishDescription": "apply 后是否发布(true=写后发布并回读线上态;false=仅落草稿)。这是生命周期动作参数,不属于声明内容,幂等重放时用 false。注意:对已发布门户用 false 更新会把发布状态降回草稿——需要保留线上态时不要用 false 试写。",
52
+ "publishDescription": "apply 一律自动发布(写后发布并回读线上态),不存在草稿-only 门户。本字段已废弃:显式 false 会被拒绝,true/缺省等同默认行为。",
53
53
  "x-backend": "(编排层,不落库)"
54
54
  }
55
55
  }
@@ -607,7 +607,7 @@
607
607
  "integer",
608
608
  "null"
609
609
  ],
610
- "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用)。",
610
+ "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用):1=数据列表,2=表单页。缺省按 1(数据列表)——缺失时前端跳转目标为空、入口无法点击。",
611
611
  "x-backend": "ComponentGridItemInfo.linkFormType"
612
612
  },
613
613
  "linkDashKey": {
@@ -15534,6 +15534,7 @@ class AiBuilderFacade:
15534
15534
  suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
15535
15535
  )
15536
15536
  write_executed = False
15537
+ sections_write_completed = False
15537
15538
  draft_readback_error: JSONObject | None = None
15538
15539
  live_readback_error: JSONObject | None = None
15539
15540
  update_payload: dict[str, Any] = {}
@@ -15605,6 +15606,7 @@ class AiBuilderFacade:
15605
15606
  self._portal_writer.update_portal(profile=profile, dash_key=dash_key, payload=update_payload)
15606
15607
  portal_update_ms = _duration_ms(portal_update_started_at)
15607
15608
  write_executed = True
15609
+ sections_write_completed = True
15608
15610
  else:
15609
15611
  portal_component_build_ms = 0
15610
15612
  portal_update_ms = 0
@@ -15653,9 +15655,55 @@ class AiBuilderFacade:
15653
15655
  draft_result = {}
15654
15656
  else:
15655
15657
  portal_draft_readback_ms = _duration_ms(portal_draft_readback_started_at)
15656
- except (QingflowApiError, RuntimeError, ValueError) as error:
15657
- api_error = _coerce_api_error(error) if not isinstance(error, ValueError) else None
15658
+ except Exception as error: # noqa: BLE001 — 任何失败都必须走清壳路径,不允许异常击穿留下半成品
15659
+ api_error = _coerce_api_error(error) if isinstance(error, (QingflowApiError, RuntimeError)) else None
15658
15660
  inline_chart_write_executed = any(bool(item.get("write_executed")) for item in inline_chart_results)
15661
+ # 本次 apply 创建的空壳回收:创建成功但 sections 未写入且无内联图表写入时,
15662
+ # 删除刚建的门户壳,阻断「失败重试 → 0 组件空门户堆积」(实测反馈 3 个空壳)。
15663
+ # 更新语义(dash_key 定位)与已有真实写入的场景不回收。
15664
+ if creating and dash_key and not sections_write_completed and not inline_chart_write_executed:
15665
+ cleanup: dict[str, Any] | None = None
15666
+ try:
15667
+ self.portals.portal_delete(profile=profile, dash_key=dash_key)
15668
+ cleanup = {"status": "deleted", "dash_key": dash_key}
15669
+ except (QingflowApiError, RuntimeError) as cleanup_error:
15670
+ cleanup = {
15671
+ "status": "failed",
15672
+ "dash_key": dash_key,
15673
+ "message": _coerce_api_error(cleanup_error).message,
15674
+ }
15675
+ if cleanup.get("status") == "deleted":
15676
+ return finalize(
15677
+ {
15678
+ "status": "failed",
15679
+ "error_code": "PORTAL_APPLY_FAILED",
15680
+ "recoverable": True,
15681
+ "message": (
15682
+ "portal apply failed before sections were written; the empty portal shell "
15683
+ "created in this call was cleaned up — retry the same declaration safely"
15684
+ ),
15685
+ "normalized_args": normalized_args,
15686
+ "missing_fields": [],
15687
+ "allowed_values": {},
15688
+ "details": {
15689
+ "created_portal_cleanup": cleanup,
15690
+ "write_error": (
15691
+ {"message": api_error.message, "transport_error": _transport_error_payload(api_error)}
15692
+ if api_error is not None
15693
+ else {"message": str(error)}
15694
+ ),
15695
+ **({"inline_chart_results": deepcopy(inline_chart_results)} if inline_chart_results else {}),
15696
+ },
15697
+ "request_id": api_error.request_id if api_error else None,
15698
+ "backend_code": api_error.backend_code if api_error else None,
15699
+ "http_status": None if api_error is None or api_error.http_status == 404 else api_error.http_status,
15700
+ "suggested_next_call": {"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
15701
+ "noop": False,
15702
+ "warnings": [],
15703
+ "verification": {"write_incomplete": True, "created_portal_cleaned_up": True},
15704
+ }
15705
+ )
15706
+ # 清理失败:空壳仍在,带 dash_key 走 partial 语义交人工处理
15659
15707
  if write_executed or inline_chart_write_executed:
15660
15708
  transport_error = _transport_error_payload(api_error) if api_error is not None else None
15661
15709
  warning = _warning(
@@ -16843,6 +16891,22 @@ class AiBuilderFacade:
16843
16891
  },
16844
16892
  )
16845
16893
  )
16894
+ except Exception as error: # noqa: BLE001
16895
+ # 工作线程的任何未预期异常(含并发 session 刷新竞态的
16896
+ # KeyError)都不得击穿整个 portal apply——否则门户壳已创建
16897
+ # 而组件未写入,清理逻辑也无从执行(实测空壳残留路径)。
16898
+ inline_chart_job_results.append(
16899
+ (
16900
+ job,
16901
+ {
16902
+ "status": "failed",
16903
+ "error_code": "PORTAL_INLINE_CHART_APPLY_FAILED",
16904
+ "message": f"{type(error).__name__}: {error}",
16905
+ "write_executed": False,
16906
+ "details": {"unexpected_error": True},
16907
+ },
16908
+ )
16909
+ )
16846
16910
 
16847
16911
  for job, chart_apply in sorted(inline_chart_job_results, key=lambda item: int(item[0].get("section_index") or 0)):
16848
16912
  app_key = str(job["app_key"])
@@ -17034,12 +17098,22 @@ class AiBuilderFacade:
17034
17098
  component = {"type": 10, "position": position_payload, "viewgraphConfig": _compact_dict(view_config)}
17035
17099
  layout_metadata.append({"source_type": section.source_type, "role": section.role})
17036
17100
  elif section.source_type == "grid":
17101
+ # 应用入口跳转页面缺省:声明未给 linkFormType 的 type=1 条目按 1(数据列表)
17102
+ # 补齐——缺失时前端渲染的跳转目标为空、入口无法点击(实测反馈)。其余
17103
+ # 入口类型(2=门户/3=应用包/4=外链)不走该键,显式值一律保留。
17104
+ grid_config_payload = deepcopy(section.config)
17105
+ grid_items = grid_config_payload.get("items") if isinstance(grid_config_payload, dict) else None
17106
+ if isinstance(grid_items, list):
17107
+ for grid_item in grid_items:
17108
+ if isinstance(grid_item, dict) and _coerce_positive_int(grid_item.get("type")) == 1:
17109
+ if _coerce_positive_int(grid_item.get("linkFormType")) is None:
17110
+ grid_item["linkFormType"] = 1
17037
17111
  component = {
17038
17112
  "type": 2,
17039
17113
  "position": position_payload,
17040
17114
  # gridTitle=None(存量空标题)剔除不落库;beingShowTitle 缺省 True、声明 config 内
17041
17115
  # beingShowTitle 键后置覆盖(提取侧 grid config 保留该键,存量 false 保真)。
17042
- "gridConfig": _compact_dict({"gridTitle": section.title, "beingShowTitle": True, **deepcopy(section.config)}),
17116
+ "gridConfig": _compact_dict({"gridTitle": section.title, "beingShowTitle": True, **(grid_config_payload if isinstance(grid_config_payload, dict) else {})}),
17043
17117
  }
17044
17118
  layout_metadata.append({"source_type": section.source_type, "role": section.role})
17045
17119
  elif section.source_type == "filter":
@@ -293,7 +293,6 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
293
293
  portal_apply.add_argument("--dash-key", default="")
294
294
  portal_apply.add_argument("--dash-name", default="")
295
295
  portal_apply.add_argument("--package-id", type=int)
296
- portal_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=None, help="发布开关;--file 声明模式下缺省尊重声明内 publish 字段(再缺省 true),显式传参时覆盖声明值")
297
296
  portal_apply.add_argument("--payload-file", help="兼容:完整门户 payload JSON(裸 DTO 透传);新代码改用 --file")
298
297
  portal_apply.add_argument("--sections-file")
299
298
  portal_apply.add_argument("--layout-preset", default="")
@@ -1470,22 +1469,12 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
1470
1469
  file_declaration.setdefault("package_tag_id", args.package_id)
1471
1470
  if getattr(args, "dash_key", ""):
1472
1471
  file_declaration["dash_key"] = args.dash_key
1473
- # publish 三态对齐 MCP(声明值优先、显式 flag 最高):声明内 publish 弹出后由 flag 解析——
1474
- # flag 未传时尊重声明值(含幂等重放的 publish:false),声明也未写时才缺省 true。
1475
- flag_publish = getattr(args, "publish", None)
1476
- declaration_publish = file_declaration.pop("publish", None)
1477
- effective_publish = (
1478
- bool(flag_publish)
1479
- if flag_publish is not None
1480
- else (bool(declaration_publish) if declaration_publish is not None else True)
1481
- )
1482
1472
  file_schema_version = str(file_declaration.pop("schema_version", None) or file_declaration.pop("schemaVersion", None) or "").strip() or None
1483
1473
  effective_schema_version = getattr(args, "schema_version", None) or file_schema_version
1484
1474
  return context.builder.portal_apply(
1485
1475
  profile=args.profile,
1486
1476
  payload=file_declaration,
1487
1477
  schema_version=effective_schema_version,
1488
- publish=effective_publish,
1489
1478
  )
1490
1479
  # deprecation 提示仅在实际使用 patch 参数时打印(review §5 噪声收敛):
1491
1480
  # 纯 flag 调用(--dash-key/--publish/--schema-version/--package-id 定位或发布
@@ -1539,7 +1528,6 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
1539
1528
  dash_key=args.dash_key,
1540
1529
  dash_name=args.dash_name,
1541
1530
  package_id=args.package_id,
1542
- publish=bool(args.publish if args.publish is not None else True),
1543
1531
  sections=sections,
1544
1532
  layout_preset=args.layout_preset,
1545
1533
  visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
@@ -72,6 +72,16 @@ def _format_failed_result(result: dict[str, Any]) -> str:
72
72
  return "\n".join(lines) + "\n"
73
73
 
74
74
 
75
+ def _format_tool_permissions(result: dict[str, Any]) -> str:
76
+ lines = [f"策略状态:{result['mode']}"]
77
+ for key, label in (("allowed_tools", "允许工具"), ("denied_tools", "禁止工具"), ("exempt_tools", "豁免工具")):
78
+ lines.append(f"{label}:")
79
+ for row in result[key]:
80
+ commands = " / ".join("qingflow " + " ".join(item["route"]) for item in row["entrypoints"])
81
+ lines.append(f"- {row['id']}:{row['description']}({commands})")
82
+ return "\n".join(lines) + "\n"
83
+
84
+
75
85
  def _format_generic(result: dict[str, Any]) -> str:
76
86
  lines: list[str] = []
77
87
  title = _first_present(result, "status", "message")
@@ -1727,6 +1737,7 @@ def _format_login_link(result: dict[str, Any]) -> str:
1727
1737
 
1728
1738
 
1729
1739
  _FORMATTERS = {
1740
+ "tool_permissions": _format_tool_permissions,
1730
1741
  "login_link": _format_login_link,
1731
1742
  "auth_whoami": _format_whoami,
1732
1743
  "workspace_list": _format_workspace_list,
@@ -9,6 +9,7 @@ from typing import Any, Callable, TextIO
9
9
  from ..errors import QingflowApiError, backend_code_value_int, message_looks_like_invalid_token
10
10
  from ..public_surface import (
11
11
  NON_TOOL_CLI_HANDLER_ROUTES,
12
+ PUBLIC_TOOL_BY_CLI_ROUTE,
12
13
  cli_public_tool_spec_from_namespace,
13
14
  cli_route_from_namespace,
14
15
  cli_trim_key_from_namespace,
@@ -17,6 +18,7 @@ from ..resource_uri import cli_resource_base_url
17
18
  from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
18
19
  from ..tools.ai_builder_tools import _attach_builder_apply_envelope
19
20
  from ..version import get_cli_version, get_cli_version_info
21
+ from ..tool_catalog import TOOL_DESCRIPTIONS, tool_is_exempt
20
22
  from ..tool_policy import (
21
23
  TOOL_POLICY_ENV,
22
24
  TOOL_POLICY_INVALID,
@@ -52,6 +54,10 @@ def build_parser() -> argparse.ArgumentParser:
52
54
  subparsers = parser.add_subparsers(dest="command", required=True)
53
55
  version_parser = subparsers.add_parser("version", help="输出 Qingflow CLI 版本")
54
56
  version_parser.set_defaults(handler=_handle_version, format_hint="version")
57
+ tools_parser = subparsers.add_parser("tools", help="查看当前 CLI 的工具授权")
58
+ tools_commands = tools_parser.add_subparsers(dest="tools_command", required=True)
59
+ permissions_parser = tools_commands.add_parser("permissions", help="只读查看本轮允许、禁止及豁免工具,不初始化认证")
60
+ permissions_parser.set_defaults(handler=_handle_tools_permissions)
55
61
  register_all_commands(subparsers)
56
62
  return parser
57
63
 
@@ -101,6 +107,16 @@ def run(
101
107
  if handler is None:
102
108
  parser.print_help(out)
103
109
  return 2
110
+ if cli_route_from_namespace(args) == ("tools", "permissions"):
111
+ # 授权自省必须早于业务上下文初始化,非法策略下也能说明拒绝原因。
112
+ result = _handle_tools_permissions(args, None)
113
+ if result["status"] == "failed":
114
+ return _emit_error(result, json_mode=bool(args.json), stdout=out, stderr=err)
115
+ if args.json:
116
+ emit_json_result(result, stream=out)
117
+ else:
118
+ emit_text_result(result, hint="tool_permissions", stream=out)
119
+ return 0
104
120
  violation = _cli_tool_policy_violation(args)
105
121
  if violation is not None:
106
122
  return _emit_error(
@@ -155,6 +171,37 @@ def _cli_tool_policy_violation(args: argparse.Namespace) -> ToolPolicyViolation
155
171
  return parse_tool_policy(os.getenv(TOOL_POLICY_ENV)).violation_for(stable_id)
156
172
 
157
173
 
174
+ def _handle_tools_permissions(_args: argparse.Namespace, _context: CliContext | None) -> dict[str, Any]:
175
+ snapshot = parse_tool_policy(os.getenv(TOOL_POLICY_ENV))
176
+ tools: dict[str, dict[str, Any]] = {}
177
+ # 只报告当前 CLI 实际可达的工具;未知策略 ID 不代表已安装相应能力。
178
+ for route, spec in sorted(PUBLIC_TOOL_BY_CLI_ROUTE.items()):
179
+ row = tools.setdefault(spec.trim_key, {
180
+ "id": spec.trim_key,
181
+ "description": TOOL_DESCRIPTIONS[spec.trim_key],
182
+ "entrypoints": [],
183
+ })
184
+ row["entrypoints"].append({"type": "cli", "route": list(route)})
185
+ result: dict[str, Any] = {
186
+ "status": "success",
187
+ "mode": snapshot.mode,
188
+ "allowed_tools": [],
189
+ "denied_tools": [],
190
+ "exempt_tools": [],
191
+ }
192
+ for stable_id, row in sorted(tools.items()):
193
+ if tool_is_exempt(stable_id):
194
+ group = "exempt_tools"
195
+ elif snapshot.violation_for(stable_id) is None:
196
+ group = "allowed_tools"
197
+ else:
198
+ group = "denied_tools"
199
+ result[group].append(row)
200
+ if snapshot.mode == "invalid":
201
+ result.update(status="failed", error_code=TOOL_POLICY_INVALID, message=snapshot.error)
202
+ return result
203
+
204
+
158
205
  def _handle_version(_args: argparse.Namespace, _context: CliContext) -> dict[str, Any]:
159
206
  info = get_cli_version_info()
160
207
  return {
@@ -210,8 +210,8 @@ PUBLIC_TOOL_BY_CLI_ROUTE.update(
210
210
  }
211
211
  )
212
212
 
213
- # 这些 handler 只负责版本输出或参数迁移提示,不会发起轻流业务请求。
214
- NON_TOOL_CLI_HANDLER_ROUTES = frozenset({("version",), ("record", "schema")})
213
+ # 这些 handler 只负责版本输出、参数迁移或本地授权自省,不会发起轻流业务请求。
214
+ NON_TOOL_CLI_HANDLER_ROUTES = frozenset({("version",), ("record", "schema"), ("tools", "permissions")})
215
215
 
216
216
 
217
217
  def public_tool_specs(domain: str | None = None) -> tuple[PublicToolSpec, ...]:
@@ -637,7 +637,6 @@ def build_builder_server() -> PolicyAwareFastMCP:
637
637
  dash_name: str = "",
638
638
  name: str = "",
639
639
  package_id: int | None = None,
640
- publish: bool = True,
641
640
  sections: list[dict] | None = None,
642
641
  pages: list[dict] | None = None,
643
642
  layout_preset: str = "",
@@ -677,7 +676,6 @@ def build_builder_server() -> PolicyAwareFastMCP:
677
676
  dash_name=dash_name,
678
677
  name=name,
679
678
  package_id=package_id,
680
- publish=publish,
681
679
  sections=sections or [],
682
680
  pages=pages or [],
683
681
  layout_preset=layout_preset,
@@ -2,6 +2,7 @@ from __future__ import annotations
2
2
 
3
3
  import json
4
4
  import os
5
+ import time
5
6
  from collections.abc import Callable
6
7
  from dataclasses import asdict, dataclass
7
8
  from datetime import datetime, timedelta, timezone
@@ -156,7 +157,19 @@ class SessionStore:
156
157
  raw_profile = payload.get("profiles", {}).get(profile)
157
158
  session_profile = SessionProfile.from_dict(raw_profile) if isinstance(raw_profile, dict) else None
158
159
  if profile in self._refreshing_profiles:
159
- return session_profile
160
+ if session_profile is not None:
161
+ return session_profile
162
+ # 并发刷新窗口内读到瞬时缺失:等待刷新完成后重读。不补这一步时,
163
+ # 工作线程(如门户内联图表创建的并发 chart_apply)会在另一线程
164
+ # 刷新 profile 期间拿到 None,调用方(select_workspace/update_route 等)
165
+ # 随即抛 KeyError(profile) 击穿整个 apply(实测「并发 chart 创建因
166
+ # 认证过期失败」的竞态入口)。
167
+ deadline = time.monotonic() + 2.0
168
+ while profile in self._refreshing_profiles and time.monotonic() < deadline:
169
+ time.sleep(0.05)
170
+ payload = self._load_profiles()
171
+ raw_profile = payload.get("profiles", {}).get(profile)
172
+ return SessionProfile.from_dict(raw_profile) if isinstance(raw_profile, dict) else None
160
173
  if self._should_refresh_profile(payload, session_profile) and self._refresh_profile(profile, session_profile):
161
174
  payload = self._load_profiles()
162
175
  raw_profile = payload.get("profiles", {}).get(profile)
@@ -152,6 +152,8 @@ TOOL_DESCRIPTIONS: dict[str, str] = {
152
152
  "builder:portal_delete": "删除门户,沿用原破坏性确认要求。",
153
153
  "builder:portal_get": "读取门户配置。",
154
154
  "builder:portal_list": "列出可访问的门户。",
155
+ "builder:portal_schema": "读取门户声明的版本化 Schema。",
156
+ "builder:portal_validate": "校验门户声明,不执行门户写入。",
155
157
  "builder:role_create": "创建工作区角色。",
156
158
  "builder:role_search": "搜索工作区角色。",
157
159
  "builder:solution_install": "安装完整方案,可创建应用包、应用、字段、视图、流程、图表、门户和角色,并按参数复制业务数据。",
@@ -56,6 +56,8 @@ TOOL_DISPLAY_TEXT: dict[str, tuple[str, str, str]] = {
56
56
  "builder:portal_delete": ("删除门户", "Delete portal", "Delete a portal with existing destructive operation confirmation requirements."),
57
57
  "builder:portal_get": ("读取门户配置", "Read portal configuration", "Read portal configuration."),
58
58
  "builder:portal_list": ("列出门户", "List portals", "List accessible portals."),
59
+ "builder:portal_schema": ("读取门户结构", "Read portal schema", "Read the versioned schema for portal declarations."),
60
+ "builder:portal_validate": ("校验门户声明", "Validate portal declaration", "Validate a portal declaration without writing portal configuration."),
59
61
  "builder:role_create": ("创建工作区角色", "Create workspace role", "Create a workspace role."),
60
62
  "builder:role_search": ("搜索工作区角色", "Search workspace roles", "Search workspace roles."),
61
63
  "builder:solution_install": ("安装完整方案", "Install complete solution", "Install a complete solution; may create application packages, applications, fields, views, workflows, charts, portals, and roles, and copy business data when requested."),
@@ -858,7 +858,6 @@ class AiBuilderTools(ToolBase):
858
858
  dash_name: str = "",
859
859
  name: str = "",
860
860
  package_id: int | None = None,
861
- publish: bool = True,
862
861
  sections: list[JSONObject] | None = None,
863
862
  pages: list[JSONObject] | None = None,
864
863
  layout_preset: str = "",
@@ -900,7 +899,6 @@ class AiBuilderTools(ToolBase):
900
899
  dash_name=dash_name,
901
900
  name=name,
902
901
  package_id=package_id,
903
- publish=publish,
904
902
  sections=sections or [],
905
903
  pages=pages or [],
906
904
  layout_preset=layout_preset,
@@ -4296,7 +4294,6 @@ class AiBuilderTools(ToolBase):
4296
4294
  dash_name: str = "",
4297
4295
  name: str = "",
4298
4296
  package_id: int | None = None,
4299
- publish: bool = True,
4300
4297
  sections: list[JSONObject] | None = None,
4301
4298
  pages: list[JSONObject] | None = None,
4302
4299
  layout_preset: str = "",
@@ -4318,7 +4315,6 @@ class AiBuilderTools(ToolBase):
4318
4315
  if patch_sections is not None:
4319
4316
  normalized_args = {
4320
4317
  "dash_key": dash_key,
4321
- "publish": publish,
4322
4318
  "patch_sections": patch_sections,
4323
4319
  }
4324
4320
  return self._attach_apply_envelope(profile, "portal_apply", _publicize_package_fields(_safe_tool_call(
@@ -4326,7 +4322,6 @@ class AiBuilderTools(ToolBase):
4326
4322
  profile=profile,
4327
4323
  dash_key=dash_key,
4328
4324
  patch_sections=patch_sections,
4329
- publish=publish,
4330
4325
  ),
4331
4326
  error_code="PORTAL_PATCH_FAILED",
4332
4327
  normalized_args=normalized_args,
@@ -4341,8 +4336,6 @@ class AiBuilderTools(ToolBase):
4341
4336
  request_payload["name"] = name
4342
4337
  if package_id is not None:
4343
4338
  request_payload["package_id"] = package_id
4344
- if "publish" not in request_payload or publish is False:
4345
- request_payload["publish"] = publish
4346
4339
  if sections:
4347
4340
  request_payload["sections"] = sections
4348
4341
  if pages:
@@ -4386,7 +4379,6 @@ class AiBuilderTools(ToolBase):
4386
4379
  "profile": profile,
4387
4380
  "dash_name": dash_name or "业务门户",
4388
4381
  "package_id": package_id or 1001,
4389
- "publish": True,
4390
4382
  "layout_preset": "dashboard_2col",
4391
4383
  "sections": [
4392
4384
  {