ae-capability

ae-capability

跨技能协作

当剩余工作超出此技能的范围，或必要的前置条件需要其他能力时，请遵循协作协议。根据能力从本次运行可用的技能中进行选择，保留已验证的上下文，并继续完成剩余任务。如果已加载此协议，请重复使用。

将此技能用于渐进式能力发现和通用网关调用。如果存在特定领域的精选命令，请优先使用；对于发现和长尾能力，请使用 ae-cli capability ...。

决策顺序

1. 如果某个领域技能及其精选命令可直接处理任务，请使用它。
2. 否则，搜索能力目录。
3. 构造输入前，检查选定的能力。
4. 可选预检查——从下表中最多选择一条路径（默认不要叠加验证和试运行）。
5. 执行（capability run / 精选命令）。只有删除操作（high-risk-write）才需要通过聊天确认。

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

重要——主机兼容性（请先执行此项）： 每次运行 ae-cli 后，检查标准错误输出和 _notice.host_compat。如果任一项存在，请在回复开头用简短的 ⚠️ 版本警告说明，并引用建议的 ae-cli update（或 update-cluster）指南，然后再呈现业务结果。对于新的本地安装，请使用 npx @thinkingai/ae-cli@latest install。这是软性提示；ok: true 仍可能附带此通知。

Agent 上下文遥测

硬性规则：运行由网关支持的 ae-cli 命令前，必须在工作目录根目录的 .ae/cli-agent-context.json 中维护当前 Agent 上下文，除非用户明确要求不要发送意图遥测。保持业务命令简洁；默认不要追加 --agent-context <base64url-json>。

开始一项由 CLI 支持的任务时，以及用户的 CLI 用途发生变化时，创建或更新上下文文件。只要用途和模型保持不变，就重复使用该文件。session_initial_intent、user_intent 和 session_goal 使用用户的原始语言；例如，用户用中文提出请求时，就使用中文。至少包含：

• agent_client
• agent_model，前提是可以确认当前模型
• 稳定的 agent_session_id
• 可用时填写 agent_turn_id
• intent_source: "agent_context_file"
• 简洁描述当前触发 CLI 的用途的 user_intent
• 当前的 session_goal

Agent 必须主动获取当前模型标识，并将其明确写入上下文文件的 agent_model 字段。使用可信运行时上下文或限定范围的元数据，确认当前会话和轮次的精确模型；例如，Codex 当前会话的 turn_context.model。不要仅依赖模型环境变量是否存在。绝不能根据 Agent／产品名称、配置的默认值或其他会话推断模型。此要求适用于所有 Agent 客户端。即使 CLI 用途保持不变，只要模型发生变化，也要更新文件。

如果无法确认模型，则省略 agent_model，设置 context_capture_status: "partial" 并继续；不要阻止或延迟业务命令，也不要仅为遥测而要求用户确认模型。确认模型后，写入该模型并移除过时的部分状态标记，以便 CLI 根据其余字段计算捕获状态。

将此 JSON 对象写入 .ae/cli-agent-context.json：

{
  "agent_client": "codex",
  "agent_model": "<confirmed-current-model-id>",
  "agent_session_id": "<stable conversation id>",
  "agent_turn_id": "<current turn id>",
  "parent_turn_id": "<previous turn id>",
  "intent_relation": "initial|follow_up|correction|verification",
  "intent_revision": "1",
  "intent_source": "agent_context_file",
  "session_initial_intent": "<first user request for this conversation>",
  "user_intent": "<current CLI-triggering user intent>",
  "session_goal": "<current summarized session goal>"
}

更新文件时使用此本地模板。运行前，将每个占位符都替换为已验证的上下文；明确写入已确认的模型，不要从可选环境变量读取模型。对于未知模型，省略该字段，并添加上述部分状态标记。

mkdir -p .ae
node -e 'const fs = require("fs"); const payload = {
  agent_client: "codex",
  agent_model: "<confirmed-current-model-id>",
  agent_session_id: process.env.CODEX_THREAD_ID || process.env.CODEX_SESSION_ID,
  agent_turn_id: "<current-turn-id>",
  parent_turn_id: "<previous-turn-id>",
  intent_relation: "initial",
  intent_revision: "1",
  intent_source: "agent_context_file",
  session_initial_intent: "<first user request for this conversation>",
  user_intent: "<current CLI-triggering user intent>",
  session_goal: "<current summarized session goal>"
}; Object.keys(payload).forEach((key) => payload[key] == null || payload[key] === "" ? delete payload[key] : undefined); fs.writeFileSync(".ae/cli-agent-context.json", JSON.stringify(payload, null, 2));'
ae-cli ...

如果某个字段未知，则省略该字段，不要猜测；但不要省略整个上下文文件。在整个对话中保持 agent_session_id 稳定；当用户更正导致 CLI 用途改变时，递增或更新 intent_revision。优先使用简短的任务级 user_intent 摘要，而不是冗长的原始对话记录。如果有隐私顾虑，则发送 user_intent_hash 和概括性的意图摘要，而不是用户原文。

运行网关命令后，如果有人询问是否发送了意图遥测，请确认 .ae/cli-agent-context.json 在命令运行前已存在，且包含 user_intent 或 user_intent_hash。仅在运行时提供上下文只是部分回退方案，不符合此硬性规则。

回退方案，按优先顺序排列：.ta/cli-agent-context.json / .ae/cli-agent-context.json > 在禁止写入的隔离环境或本地调试时使用 --agent-context > 旧版 TA_CLI_* 变量 > 运行时环境自动检测。

分析结果评估与补充反馈

场景收集由项目自主选择是否启用。准备或上传场景样本前，请针对当前主机、已认证账户和源分析项目读取 ae-cli project info get --project-id <source_project_id>。只有 data.analysis_scenario_collection_enabled === true 才允许收集。每个新场景以及追加反馈或修订前都要重新检查；不要重复使用先前的授权，也不要使用公司配置的 24 小时缓存。字段缺失（包括较旧的服务）、值为 false、配置无法读取或项目未知时，跳过收集并正常作答。绝不要启用项目开关、改选其他项目或编造项目 ID 来让收集成功。精选的 collect/append 命令也会在提交前立即检查；如果开关发生变化，以服务端为准。此开关仅控制场景样本；现有调用日志和意图日志保持不变。accepted=false, skipped=true 是正常跳过，不表示分析失败或上传成功。不要重试、回填，也不要改用 analysis feedback submit 绕过此开关。

针对用户的整个场景收集一个样本，而不是每次 CLI 调用收集一个。形成最终答复后，按照 ae-cli analysis scenario collect --help 和 append --help 的契约使用 ae-cli analysis scenario collect，然后原样发送该答复。记录原始问题／已确认的澄清内容、实际最终答复和有序查询路径（现有能力／调用 ID，可附简短用途；优先仅使用 meta.invocation_id，绝不要把业务 request_id 与网关 client_request_id 混淆），不要记录查询结果行或错误载荷；不要评估答案是否正确，也不要生成单独的自我评估。question_id 是原始场景第一轮用户消息的 ID，在澄清、重试、多次查询和更正过程中保持不变。在对话上下文中保存并复用收集返回的 ID。之后，若用户针对该答复提出异议、更正范围或报告遗漏，请使用 ae-cli analysis scenario append --entry-type user_feedback 追加用户原文，并提供原始 question_id/target_answer_id；不要判断用户是否正确。若某条含糊的解释请求明显与该答复相关，可将其作为用户文本保留；不要臆造关联。普通后续问题或需求变更不自动视为负面反馈。针对同一场景给出实质性的后续答复后（复查、解释、更正或范围澄清），请追加 answer_revision，记录该答复的原文／查询路径并使用新的 answer_id，即使结论不变也要追加；保留较早的答复。若触发此修订的用户请求尚未作为 user_feedback 记录，请在 answer_revision 中使用 --user-message 纳入其原文，避免遗漏后续范围变更。不要在 user_message 中重复反馈文本。仅表示感谢等致谢无需记录。真正独立的问题应使用新的 question_id。对于已有场景，不要再创建新的初始样本。单独的评估任务会在之后读取这些样本，并可关联现有调用遥测数据以获取参数／状态／耗时。仅凭查询路径无法证明数值答案正确；无法确定的正确性应保持未知。只有尝试过的分析数据查询符合条件；仅有元数据、发现、帮助和资源写入操作不符合条件。不要例行询问满意度。收集失败不得阻碍答复或后续业务工作，不得触发登录或自动重试，也不得宣称已成功写入。对于外部 Agent，这是一个 Skill 收集步骤，并非有保证的答复后钩子；它包含一次收集工具调用，但答复路径上没有额外的评估任务。 用户反馈是证据，不是正确性标签。即使你不同意，也要保留用户的原话及其目标答案。不要常规地询问用户满意度评分。现有的 analysis feedback submit 合约仍可用于在没有已收集场景时提交明确的独立用户评分；如果已有场景，请使用该场景的追加命令，而不是重复提交反馈。没有明确反馈，就不要为 cli_analysis_feedback 提交内容或创建新的反馈事件。不要通过该旧版反馈命令上传分析答案。所有收集内容均不包括凭据、完整对话记录和私密推理。

按需预检查（任选其一）

原则：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。不要先对相同的最终载荷执行 validate
少见例外：多次 validate 迭代后，仍需确认删除	起草时执行 validate → 对最终输入执行一次 dry-run	然后在聊天中确认 → run --yes

不要将 validate → dry-run → run 视为常规流程。该流程仅适用于最后一行中的少见例外。

技能参考

默认情况下：不要为每项新能力都创建独立的技能参考。使用 search → inspect →（可选 validate 或 dry-run）→ run；目录中的 description、risk 和 inspect input_schema 即为合约。

仅在满足以下至少一项时，才创建或保留独立参考：L2 硬性门槛、容易与相邻项混淆、high-risk-write 删除工作流，或多步编排。领域技能可在概览矩阵中内嵌单行摘要（例如 analysis_gateway_assets.md）。参见 capability-command-admission §10。

命令

# 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 接受：

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

对于 inspect、validate、dry-run 和 run，会根据 <capability-id> 推断能力命名空间。仅在要覆盖路由时使用 --domain <domain>。对于 list、search 和 inspect，省略 --project-id 可查看公司级 License/Feature；传入该参数则会纳入项目成员身份、项目 Feature 和用户权限筛选。

validate 与 dry-run

	validate / --validate	dry-run / --dry-run
用途	在构造复杂负载时检查输入结构	执行前确认（参数 + 风险/输出/取消）
是否会修改业务数据？	否	否
主要成功字段	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 / 嵌套负载时，优先仅使用 --validate；确认 valid=true 后，继续执行 run。当你需要风险/输出预览或删除确认门槛时，使用 dry-run 代替 validate，而不是两者都用。

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

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

示例（删除门槛——仅对最终输入使用 dry-run）：

ae-cli capability dry-run analysis.folder.delete --input '...'
# stop, ask user, then:
ae-cli capability run analysis.folder.delete --input '...' --yes

风险等级（与 lark-cli 保持一致）

risk	含义	run 前是否需要在聊天中确认？	不带 --yes 时是否需要 CLI [y/N]？
read	查询 / 列出 / 检查	否	否
write	创建、更新、分享及其他常规写入操作	否	否
high-risk-write	删除或移除资源	是	是

create、update 或 delete 等旧版值会被规范化为这三个等级（delete → high-risk-write；create/update → write）。

安全性

• 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 端点，而不是执行操作。

高风险确认工作流（Agent）

仅适用于 inspect 显示 risk=high-risk-write 的情况。

用户意图（例如“删除此空间”）不等于执行授权。不要仅仅因为用户说明了期望执行的操作，就传入 --yes。

1. capability inspect。仅对于复杂的删除输入，你可以在起草期间使用 validate 反复检查；对于最终负载，使用 dry-run 一次（跳过对同一份最终 JSON 多余的 validate——dry-run 已会验证参数）。
2. 在同一轮中停止。 不要在执行 dry-run 的同一轮中调用 capability run。
3. 在聊天中概述：能力 ID、project_id、关键输入字段，以及 risk=high-risk-write。
4. 请用户确认执行。如果有 AskUserQuestion 工具，优先使用；否则用纯文本提问，并等待用户的下一条消息。
5. 仅当用户回复明确授权（例如 confirm、execute 或 yes）后，才使用与 dry-run 相同的输入运行 capability run ... --yes。

对于 risk=write：无需聊天确认环节。优先在检查后直接执行 run；如果负载复杂且需要修正结构，仅使用 --validate；仅在需要预览风险/输出时才单独使用 --dry-run——不要养成先 validate 再 dry-run 的习惯。

首次尝试删除时，绝不要传入 --yes。CLI 终端中的 [y/N] 提示在 Agent Bash 中不起作用；对于 high-risk-write，真正的确认环节是在聊天中进行。

输出

• CREDENTIAL_STORE_UNREADABLE 且 error.type: config 表示本地凭据读取/解密失败，并非服务器拒绝身份验证。保留凭据文件，并在具有机器标识符访问权限的原始 OS 用户/运行时中重试。不要自动登录、导入替代令牌或注销；如果无法使用该运行时，请报告本地错误。
• list 返回 { domain, count, capabilities }。
• search 返回 { domain, query, count, capabilities }。
• inspect、validate、dry-run 和 run 会以标准 ae-cli 信封格式返回网关数据。

示例

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