@qingflow-tech/qingflow-cli 1.1.61-beta.8 → 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.8
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.8 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.8 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.8",
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.61b8"
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`。 |
@@ -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)。正式业务门户优先复制这个文件的行布局。
@@ -15655,8 +15655,8 @@ class AiBuilderFacade:
15655
15655
  draft_result = {}
15656
15656
  else:
15657
15657
  portal_draft_readback_ms = _duration_ms(portal_draft_readback_started_at)
15658
- except (QingflowApiError, RuntimeError, ValueError) as error:
15659
- 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
15660
15660
  inline_chart_write_executed = any(bool(item.get("write_executed")) for item in inline_chart_results)
15661
15661
  # 本次 apply 创建的空壳回收:创建成功但 sections 未写入且无内联图表写入时,
15662
15662
  # 删除刚建的门户壳,阻断「失败重试 → 0 组件空门户堆积」(实测反馈 3 个空壳)。
@@ -16891,6 +16891,22 @@ class AiBuilderFacade:
16891
16891
  },
16892
16892
  )
16893
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
+ )
16894
16910
 
16895
16911
  for job, chart_apply in sorted(inline_chart_job_results, key=lambda item: int(item[0].get("section_index") or 0)):
16896
16912
  app_key = str(job["app_key"])
@@ -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, ...]:
@@ -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."),