ae-capability

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ae-capability

Use this skill for progressive capability discovery and generic gateway invocation. Prefer a domain-specific curated command when one exists; use

ae-cli capability ...

for discovery and long-tail capabilities.

使用此技能进行渐进式能力发现与通用网关调用。当存在领域专属的定制命令时，优先使用该命令；对于能力发现和长尾能力，使用

ae-cli capability ...

命令。

Decision Order

决策顺序

Use a domain skill and its curated command when it directly covers the task.
Otherwise search the capability catalog.
Inspect the selected capability before constructing input.
Optionally pre-check — pick at most one path from the table below (do not stack validate + dry-run by default).
Execute (
```
capability run
```
/ curated command). Chat confirmation only for delete (
```
high-risk-write
```
).

Never guess a capability ID, input field, enum value, resource ID, or project ID.

CRITICAL — Host compat (do this first): After each

ae-cli

run, check stderr and

_notice.host_compat

. If either is present, open the user reply with a short ⚠️ version warning and quote the
npm i -g
/
npx skills add
(or update-cluster) lines verbatim, then present the business result. Soft tip;

ok: true

can still carry the notice.

当领域技能及其定制命令可直接覆盖任务需求时，优先使用。
否则，搜索能力目录。
在构造输入前查看所选能力的详情。
可选预检查——从下表中选择至多一种方式（默认不要同时执行验证和dry-run）。
执行（
```
capability run
```
/ 定制命令）。仅在执行删除操作（
```
high-risk-write
```
）时需聊天确认。

切勿猜测能力ID、输入字段、枚举值、资源ID或项目ID。

关键——主机兼容性（首先执行此步骤）：每次运行
ae-cli
后，检查stderr和
_notice.host_compat
。若其中任意一项存在，在用户回复开头添加简短的⚠️版本警告，并逐字引用
npm i -g
/
npx skills add
（或update-cluster）命令行，然后展示业务结果。即使

ok: true

也可能包含该通知，需温和提示。

On-demand pre-check (pick one)

按需预检查（选其一）

Motto: validate = fix params; dry-run = confirm ready to run. Hard rule: for the same final input, do not run both validate and dry-run by default.

dry-run

already includes parameter validation.

Situation	What to call	Then
Simple / familiar input (typical `read` , few scalar fields)	Neither — skip pre-check	`run` directly
Complex `qp` / nested `payload` / share maps; still iterating shape	`--validate` / `capability validate` only (may repeat while fixing)	After `valid=true` , `run` directly — skip dry-run unless below applies
Need risk / `output_mode` / `supports_cancel` , or `high-risk-write` delete gate	`--dry-run` / `capability dry-run` only (once on final input)	Then confirm (delete) / `run` . Do not validate first on the same final payload
Rare exception: many validate iterations, then still need delete confirmation	validate while drafting → one dry-run on the final input	Then chat confirm → `run --yes`

Do not treat

validate → dry-run → run

as the normal path. That stack is the rare exception in the last row only.

格言：validate = 修正参数；dry-run = 确认准备就绪 硬性规则：对于同一最终输入，默认不要同时运行validate和dry-run。

dry-run

已包含参数验证。

场景	调用命令	后续操作
简单/熟悉的输入（典型 `read` 操作，少量标量字段）	两者都不选——跳过预检查	直接执行 `run`
复杂 `qp` / 嵌套 `payload` / 共享映射；仍在调整结构	仅使用 `--validate` / `capability validate` （调整过程中可重复执行）	当 `valid=true` 后，直接执行 `run` ——除非符合以下情况，否则跳过dry-run
需要查看风险 / `output_mode` / `supports_cancel` ，或 `high-risk-write` 删除校验	仅使用 `--dry-run` / `capability dry-run` （仅对最终输入执行一次）	然后确认（删除操作）/ 执行 `run` 。请勿对同一最终payload先执行validate
罕见例外：多次validate迭代后仍需删除确认	起草阶段执行validate → 对最终输入执行一次dry-run	然后聊天确认 → 执行 `run --yes`

不要将

validate → dry-run → run

视为常规流程。该流程仅为最后一行所述的罕见例外情况。

Skill references

技能参考

Default: do not create a standalone skill reference for every new capability. Use

search

→

inspect

→ (optional validate or dry-run) →

run

; catalog

description

risk

, and

inspect

input_schema

are the contract.

Create or keep a standalone reference only when at least one applies: L2 hard bar, easily confused with neighbors,

high-risk-write

delete workflow, or multi-step orchestration. Domain skills may inline one-line summaries in overview matrices (e.g.

analysis_gateway_assets.md

). See

capability-command-admission

§10.

默认规则：无需为每个新能力创建独立的技能参考。使用

search

→

inspect

→（可选验证或dry-run）→

run

流程；目录中的

description

、

risk

和

inspect

返回的

input_schema

即为契约内容。

仅在满足以下至少一项条件时，才创建或保留独立参考：L2硬性要求、易与其他能力混淆、

high-risk-write

删除工作流、或多步骤编排。领域技能可在概览矩阵中嵌入单行摘要（例如

analysis_gateway_assets.md

）。详见

capability-command-admission

第10节。

Commands

命令

bash

undefined

bash

undefined

List company-level summaries, or the capabilities available in one project.

ae-cli capability list --domain <domain> [--project-id <id>]

Search capability IDs and descriptions. All terms must match.

ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]

Read input_schema, risk, auth, output, and dry-run support.

ae-cli capability inspect <capability-id> [--project-id <id>]

Optional — fix params only (gateway /validate). Curated: global --validate.

ae-cli capability validate <capability-id> --input '<json-object>' ae-cli metadata data-table sql-write --project-id 1 ... --validate

Optional — confirm ready to run (gateway /dry-run). Curated: global --dry-run.

ae-cli capability dry-run <capability-id> --input '<json-object>' ae-cli metadata data-table sql-write --project-id 1 ... --dry-run

Execute (after inspect; add at most one pre-check when needed).

ae-cli capability run <capability-id> --input '<json-object>'


`--input` accepts:

- An inline JSON object.
- A JSON file path.
- `@<path>`.
- `-` to read JSON from stdin.

The capability namespace is inferred from `<capability-id>` for `inspect`, `validate`, `dry-run`, and `run`. Use `--domain <domain>` only to override routing. For `list`, `search`, and `inspect`, omit `--project-id` for company License/Feature visibility; pass it to include project membership, project Feature, and user permission filtering.

ae-cli capability run <capability-id> --input '<json-object>'


`--input`支持：

- 内联JSON对象。
- JSON文件路径。
- `@<path>`。
- `-`表示从标准输入读取JSON。

能力命名空间会从`<capability-id>`中自动推断，适用于`inspect`、`validate`、`dry-run`和`run`命令。仅在需要覆盖路由时使用`--domain <domain>`。对于`list`、`search`和`inspect`命令，省略`--project-id`可查看公司级License/Feature权限；传入该参数则会包含项目成员身份、项目Feature和用户权限过滤。

validate vs dry-run

validate与dry-run对比

	`validate` / `--validate`	`dry-run` / `--dry-run`
Purpose	Check input shape while composing complex payloads	Pre-execution confirmation (params + risk/output/cancel)
Does it mutate business data?	No	No
Primary success fields	`valid` , `capability_id` , `normalized_input`	`dry_run` , `capability_id` , `risk` , `output_mode` , `supports_cancel` , `normalized_input`
When to prefer	Iterating nested `payload` / `qp` / multi-field JSON	Final input; need risk/output contract or delete gate
Typical failure focus	Missing/invalid fields, type mismatches, bad `qp` structure	Same param errors, plus readiness signals for actual run
Curated commands	Global `--validate` on gateway-backed curated commands	Global `--dry-run`

Server may still authenticate the caller for both endpoints. Neither executes the capability business handler. Do not combine

--validate

and

--dry-run

on one invocation.

Complex input: prefer --validate
only while assembling

qp

/ nested payload; after

valid=true

, go to

run

. Use dry-run instead of validate when you need the risk/output preview or a delete confirmation gate — not both.

Example (param risk only — no stacked dry-run):

bash

ae-cli metadata data-table sql-write ... --validate   # iterate until valid
ae-cli metadata data-table sql-write ...              # execute ordinary write

Example (delete gate — dry-run only on final input):

bash

ae-cli capability dry-run analysis.folder.delete --input '...'

	`validate` / `--validate`	`dry-run` / `--dry-run`
用途	构造复杂payload时检查输入结构	执行前确认（参数+风险/输出/可取消性）
是否修改业务数据？	否	否
核心成功字段	`valid` , `capability_id` , `normalized_input`	`dry_run` , `capability_id` , `risk` , `output_mode` , `supports_cancel` , `normalized_input`
优先使用场景	调整嵌套 `payload` / `qp` / 多字段JSON时	最终输入；需要查看风险/输出契约或删除校验时
典型失败关注点	缺失/无效字段、类型不匹配、 `qp` 结构错误	相同的参数错误，加上实际运行的就绪信号
定制命令支持	基于网关的定制命令支持全局 `--validate`	全局 `--dry-run`

服务器可能仍会对两个端点的调用者进行身份验证。两者均不会执行能力的业务处理逻辑。请勿在一次调用中同时使用

--validate

和

--dry-run

。

复杂输入：组装
qp
/ 嵌套payload时优先仅使用
--validate
；当

valid=true

后，直接执行

run

。当需要查看风险/输出预览或删除确认校验时，使用dry-run替代validate——不要同时使用两者。

示例（仅参数风险检查——不叠加dry-run）：

bash

ae-cli metadata data-table sql-write ... --validate   # 迭代直至验证通过
ae-cli metadata data-table sql-write ...              # 执行常规写入操作

示例（删除校验——仅对最终执行dry-run）：

bash

ae-cli capability dry-run analysis.folder.delete --input '...'

stop, ask user, then:

暂停，询问用户，然后执行：

ae-cli capability run analysis.folder.delete --input '...' --yes

undefined

ae-cli capability run analysis.folder.delete --input '...' --yes

undefined

Risk Levels (aligned with lark-cli)

风险等级（与lark-cli对齐）

`risk`	Meaning	Chat confirmation before `run` ?	CLI `[y/N]` without `--yes` ?
`read`	Query / list / inspect	No	No
`write`	Create, update, share, and other ordinary writes	No	No
`high-risk-write`	Delete or remove resources	Yes	Yes

Legacy values such as

create

update

, or

delete

are normalized to this three-tier model (

delete

→

high-risk-write

;

create

update

→

write

`risk`	含义	执行 `run` 前需聊天确认？	无 `--yes` 时CLI是否提示 `[y/N]` ？
`read`	查询/列表/查看	否	否
`write`	创建、更新、共享及其他常规写入操作	否	否
`high-risk-write`	删除或移除资源	是	是

旧版值如

create

、

update

或

delete

会被标准化为三级模型（

delete

→

high-risk-write

；

create

update

→

write

）。

Safety

安全规范

```
list
```
,
```
search
```
,
```
inspect
```
,
```
validate
```
, and
```
dry-run
```
never execute business mutations.
Curated gateway commands:
```
--validate
```
→
```
/validate
```
;
```
--dry-run
```
→
```
/dry-run
```
; do not combine them.
Do not stack validate + dry-run on the same final input by default (efficiency).
```
capability run
```
inspects metadata before execution when
```
--yes
```
is absent.
Only
```
high-risk-write
```
requires chat confirmation before
```
capability run ... --yes
```
.
```
read
```
and ordinary
```
write
```
may run after inspect; add validate or dry-run only when the on-demand table says so.
Use
```
--yes
```
on delete runs only after the user explicitly authorizes execution in chat.
Global
```
--dry-run
```
on
```
capability run
```
/ curated commands calls the gateway dry-run endpoint instead of execute.
Global
```
--validate
```
on
```
capability run
```
/ curated commands calls the gateway validate endpoint instead of execute.

```
list
```
、
```
search
```
、
```
inspect
```
、
```
validate
```
和
```
dry-run
```
永远不会执行业务变更操作。
基于网关的定制命令：
```
--validate
```
调用
```
/validate
```
端点；
```
--dry-run
```
调用
```
/dry-run
```
端点；请勿同时使用两者。
默认情况下，不要对同一最终输入同时执行validate和dry-run（提升效率）。
当未使用
```
--yes
```
时，
```
capability run
```
会在执行前检查元数据。
仅
```
high-risk-write
```
操作需要在执行
```
capability run ... --yes
```
前进行聊天确认。
```
read
```
和常规
```
write
```
操作可在查看后直接执行；仅在按需表格所述场景下，添加validate或dry-run。
仅在用户在聊天中明确授权后，才在删除操作中使用
```
--yes
```
。
在
```
capability run
```
/ 定制命令中使用全局
```
--dry-run
```
会调用网关的dry-run端点而非执行端点。
在
```
capability run
```
/ 定制命令中使用全局
```
--validate
```
会调用网关的validate端点而非执行端点。

High-Risk Confirmation Workflow (Agent)

高风险确认工作流（Agent）

Applies only when

inspect

shows

risk=high-risk-write

User intent (for example "delete this space") is not execution authorization. Do not pass

--yes

just because the user stated the desired action.

```
capability inspect
```
. For complex delete input only, you may iterate with
```
validate
```
while drafting; for the final payload use dry-run
once (skip a redundant validate on that same final JSON — dry-run already validates params).
Stop in the same turn. Do not call
```
capability run
```
in the same turn as dry-run.
Summarize in chat: capability ID,
```
project_id
```
, key input fields, and
```
risk=high-risk-write
```
.
Ask the user to confirm execution. Prefer
```
AskUserQuestion
```
when that tool is available; otherwise ask in plain text and wait for the user's next message.
Only after the user replies with explicit authorization (for example
```
confirm
```
,
```
execute
```
, or
```
yes
```
) run
```
capability run ... --yes
```
with the same input as dry-run.

For

risk=write

: no chat confirmation gate. Prefer direct

run

after inspect; use

--validate

alone when the payload is complex and you are fixing shape; use

--dry-run

alone only if you need the risk/output preview — not validate then dry-run as a habit.

Never pass

--yes

on the first delete attempt. CLI terminal

[y/N]

prompts do not work in Agent Bash; chat confirmation is the real gate for

high-risk-write

仅当

inspect

risk=high-risk-write

时适用。

用户意图（例如"删除此空间"）不代表执行授权。不要仅因为用户表述了期望操作就添加

--yes

。

执行
```
capability inspect
```
。仅针对复杂删除输入，可在起草阶段通过
```
validate
```
进行迭代；对于最终payload，仅执行一次
```
dry-run
```
（无需对同一最终JSON重复执行validate——dry-run已包含参数验证）。
在当前交互中暂停。不要在执行dry-run的同一交互中调用
```
capability run
```
。
在聊天中总结：能力ID、
```
project_id
```
、关键输入字段及
```
risk=high-risk-write
```
。
请求用户确认执行。若
```
AskUserQuestion
```
工具可用，优先使用该工具；否则用明文询问并等待用户的下一条消息。
仅在用户回复明确授权（例如
```
confirm
```
、
```
execute
```
或
```
yes
```
）后，使用与dry-run相同的输入执行
```
capability run ... --yes
```
。

对于

risk=write

操作：无需聊天确认校验。查看后优先直接执行

run

；当payload复杂且需调整结构时，仅使用

--validate

；仅在需要查看风险/输出预览时使用

--dry-run

——不要养成先validate再dry-run的习惯。

首次尝试删除操作时切勿添加

--yes

。CLI终端的

[y/N]

提示在Agent Bash中无法生效，聊天确认是

high-risk-write

操作的实际校验关卡。

Output

输出

```
list
```
returns
```
{ domain, count, capabilities }
```
.

search

returns

{ domain, query, count, capabilities }

```
inspect
```
,
```
validate
```
,
```
dry-run
```
, and
```
run
```
return gateway data in the standard ae-cli envelope.

```
list
```
返回
```
{ domain, count, capabilities }
```
。

search

{ domain, query, count, capabilities }

。

```
inspect
```
、
```
validate
```
、
```
dry-run
```
和
```
run
```
返回标准ae-cli封装格式的网关数据。

Examples

示例

bash

ae-cli capability search "dashboard list" --domain analysis
ae-cli capability inspect analysis.dashboard.list
ae-cli capability validate metadata.data_table.sql_write --input input.json
ae-cli capability dry-run analysis.folder.delete --input '{"project_id":1,"folder_ids":[1001]}'
ae-cli capability run analysis.dashboard.list --input input.json

bash

ae-cli capability search "dashboard list" --domain analysis
ae-cli capability inspect analysis.dashboard.list
ae-cli capability validate metadata.data_table.sql_write --input input.json
ae-cli capability dry-run analysis.folder.delete --input '{"project_id":1,"folder_ids":[1001]}'
ae-cli capability run analysis.dashboard.list --input input.json