需要发现或调用 ae-cli 能力网关中的长尾能力时：按…

在 ae-cli 能力网关中，用通用命令发现、检查并调用没有 curated 命令覆盖的长尾能力，并在复杂输入或高风险删除前只选一种预检路径。

适用场景

解决思路

1. 优先使用领域技能及其 curated command 直接覆盖任务；只有在没有对应 curated command 时，才用 `ae-cli capability ...` 做能力发现和长尾能力调用。
2. 按决策顺序执行：先使用领域技能及其 curated command；否则搜索 capability catalog；选定后先 inspect；然后按需选择至多一种预检；最后执行 `capability run` 或 curated command，只有删除类 `high-risk-write` 才需聊天确认。
3. 绝不猜测 capability ID、输入字段、枚举值、资源 ID 或 project ID。
4. 每次运行 `ae-cli` 后检查 stderr 和 `_notice.host_compat`；若出现任一项，在回复开头加简短 ⚠️ 版本警告，并逐字引用 `npm i -g` / `npx skills add`（或 update-cluster）行，然后展示业务结果；注意 `ok: true` 仍可能携带该提示。
5. 按需预检只选一种：牢记 `validate = 修参数`，`dry-run = 确认可运行`；同一最终输入默认不要同时运行 validate 和 dry-run；`dry-run` 已包含参数校验。
6. 简单/熟悉的输入（典型 `read`、少量标量字段）：跳过预检，直接 `run`。
7. 复杂 `qp` / 嵌套 `payload` / share maps，且仍在迭代结构：只用 `--validate` / `capability validate`，可反复修正；`valid=true` 后直接 `run`，除非需要 risk/output 或删除门禁才用 dry-run。
8. 需要 risk / `output_mode` / `supports_cancel`，或 `high-risk-write` 删除门禁：只在最终输入上用一次 `--dry-run` / `capability dry-run`；随后删除则确认，否则 `run`；不要先对同一最终 payload 做 validate。
9. 罕见例外：多次 validate 迭代后仍需删除确认：起草时 validate → 对最终输入做一次 dry-run → 聊天确认 → `run --yes`。
10. 不要将 `validate → dry-run → run` 当作常规路径；该叠加仅限上一条例外。
11. 默认不要为每个新能力创建独立技能引用；使用 `search` → `inspect` →（可选 validate 或 dry-run）→ `run`，并以目录 `description`、`risk`、`inspect` 的 `input_schema` 作为契约。
12. 仅在满足至少一条时创建或保留独立引用：L2 硬门槛、易与邻近能力混淆、`high-risk-write` 删除工作流、或多步编排；领域技能可在概览矩阵中内联一行摘要，例如 `analysis_gateway_assets.md`；参见 `capability-command-admission` §10。
13. 列出公司级摘要或某项目可用能力：`ae-cli capability list --domain <domain> [--project-id <id>]`。
14. 搜索 capability ID 和描述（所有词都必须匹配）：`ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]`。
15. 读取 `input_schema`、`risk`、`auth`、`output` 和 dry-run 支持信息：`ae-cli capability inspect <capability-id> [--project-id <id>]`。
16. 可选 validate（仅修参数，调用 gateway `/validate`；curated 命令用全局 `--validate`）：`ae-cli capability validate <capability-id> --input '<json-object>'`；例如 `ae-cli metadata data-table sql-write --project-id 1 ... --validate`。
17. 可选 dry-run（确认可运行，调用 gateway `/dry-run`；curated 命令用全局 `--dry-run`）：`ae-cli capability dry-run <capability-id> --input '<json-object>'`；例如 `ae-cli metadata data-table sql-write --project-id 1 ... --dry-run`。
18. 执行能力（inspect 后；需要时最多加一种预检）：`ae-cli capability run <capability-id> --input '<json-object>'`。
19. `--input` 可接受：内联 JSON 对象、JSON 文件路径、`@<path>`、或 `-` 从 stdin 读取 JSON。
20. 对 `inspect`、`validate`、`dry-run`、`run`，从 `<capability-id>` 推断 capability namespace；仅在需要覆盖路由时使用 `--domain <domain>`。
21. 对 `list`、`search`、`inspect`，省略 `--project-id` 以获得公司 License/Feature 可见性；传入则包含项目成员资格、项目 Feature 和用户权限过滤。
22. validate 与 dry-run 区别：validate 用于组装复杂 payload 时检查输入形状；dry-run 用于执行前确认（参数 + risk/output/cancel）；两者都不改业务数据。
23. validate 主要成功字段：`valid`、`capability_id`、`normalized_input`；dry-run 主要成功字段：`dry_run`、`capability_id`、`risk`、`output_mode`、`supports_cancel`、`normalized_input`。
24. validate 优先用于迭代嵌套 `payload` / `qp` / 多字段 JSON；dry-run 优先用于最终输入、需要 risk/output 契约或删除门禁。
25. validate 典型失败关注缺失/无效字段、类型不匹配、`qp` 结构错误；dry-run 关注相同参数错误以及实际运行的 readiness 信号。
26. curated 命令上使用全局 `--validate` / `--dry-run`；不要在一次调用中组合 `--validate` 和 `--dry-run`。
27. 复杂输入：组装 `qp` / 嵌套 payload 时优先只用 `--validate`；`valid=true` 后去 `run`；需要 risk/output 预览或删除确认门禁时改用 dry-run，不要两者都用。
28. 风险分级：`read` = 查询/列表/检查，运行前不需要聊天确认，无 `--yes` 时 CLI 也不需要 `[y/N]`；`write` = 创建、更新、分享等普通写入，运行前不需要聊天确认，无 `--yes` 时 CLI 也不需要 `[y/N]`；`high-risk-write` = 删除或移除资源，运行前需要聊天确认，无 `--yes` 时 CLI 需要 `[y/N]`。
29. 旧值规范化：`delete` → `high-risk-write`；`create` / `update` → `write`。
30. 安全规则：`list`、`search`、`inspect`、`validate`、`dry-run` 从不执行业务写操作。
31. curated gateway 命令中：`--validate` 调 `/validate`；`--dry-run` 调 `/dry-run`；不要组合它们。
32. 默认不要在同一最终输入上叠加 validate + dry-run（效率原因）。
33. 无 `--yes` 时，`capability run` 在执行前会 inspect 元数据。
34. 只有 `high-risk-write` 需要在 `capability run ... --yes` 前进行聊天确认。
35. `read` 和普通 `write` 可以在 inspect 后运行；仅当按需表说明时才加 validate 或 dry-run。
36. 仅当用户在聊天中明确授权执行后，删除运行才使用 `--yes`。
37. `capability run` / curated 命令上的全局 `--dry-run` 会调用 gateway dry-run 端点而不是执行。
38. `capability run` / curated 命令上的全局 `--validate` 会调用 gateway validate 端点而不是执行。
39. 仅当 `inspect` 显示 `risk=high-risk-write` 时应用高风险确认工作流；用户意图（如“删除这个空间”）不是执行授权；不要仅因用户说出目标动作就传 `--yes`。
40. 高风险删除步骤 1：`capability inspect`；仅复杂删除输入可在起草时用 `validate` 迭代；最终 payload 用一次 `dry-run`（不要在同一最终 JSON 上重复 validate，因 dry-run 已校验参数）。
41. 高风险删除步骤 2：在同一轮停止，不要在 dry-run 的同一轮调用 `capability run`。
42. 高风险删除步骤 3：在聊天中总结 capability ID、`project_id`、关键输入字段和 `risk=high-risk-write`。
43. 高风险删除步骤 4：请求用户确认执行；有 `AskUserQuestion` 工具时优先使用，否则用纯文本询问并等待用户下一条消息。
44. 高风险删除步骤 5：仅在用户回复明确授权（例如 `confirm`、`execute`、`yes`）后，用与 dry-run 相同的输入运行 `capability run ... --yes`。
45. 对 `risk=write`：没有聊天确认门禁；inspect 后优先直接 `run`；复杂 payload 修形状时单独用 `--validate`；仅在需要 risk/output 预览时单独用 `--dry-run`；不要养成 validate 后 dry-run 的习惯。
46. 第一次删除尝试绝不传 `--yes`；CLI 终端 `[y/N]` 提示在 Agent Bash 中不工作；聊天确认才是 `high-risk-write` 的真正门禁。
47. 输出形状：`list` 返回 `{ domain, count, capabilities }`；`search` 返回 `{ domain, query, count, capabilities }`；`inspect`、`validate`、`dry-run`、`run` 返回标准 ae-cli envelope 中的 gateway 数据。
48. 示例命令：`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`。

适用边界 · 注意事项

• 已有领域技能或 curated command 直接覆盖任务时，不要走本通用发现/调用流程。
• 没有安装或无法运行 `ae-cli`、无法访问 capability gateway，或缺少对应项目/权限时，不适用。
• 不要把同一最终输入的 `validate` 和 `dry-run` 同时执行，也不要把 `validate → dry-run → run` 当作默认路径。