ae-metadata

ae-metadata

CLI 域 metadata 路由到分析能力网关（/api/cli/analysis/v1/...），使用身份验证标头 cli-token。

此技能用于由网关支持的数据表和属性维度表操作。

能力约定

• 职责：通过以下命令管理数据表和维度表绑定。
• 输入：已验证的项目、表／属性标识符及特定操作所需的参数；本地 CSV 工作流需要有效的已上传输入文件标识符和用途。
• 输出：表／绑定操作结果、资源标识符，或下载运行／产物状态。已提交的异步下载尚未生成完成的文件。
• 边界：本地输入文件上传、事件／属性详情与发现、指标 CRUD、虚拟元数据、批量元数据、项目配置和追踪计划属于其他能力。
• 完成条件：已验证所请求的表或绑定结果，或已报告待处理／受阻工作及其剩余要求。

跨技能协作

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

全局 AE CLI 规则

参数	描述
--format <json|table>	输出格式。默认为 JSON。
--jq <expr>	对 JSON 输出应用 jq 过滤器。
--host <url>	覆盖当前 AE 主机，例如：ae-cli metadata data-table list --host <url> ...。
--validate	可选：仅修正参数（/validate）。在迭代复杂 qp / 负载时单独使用，然后再运行。不要与 --dry-run 叠加使用。
--dry-run	可选：确认已准备好运行（/dry-run）。单独使用以预览风险和输出。不要与 --validate 叠加使用。

输出和错误：

• 成功：JSON 封装（默认）。可能包含可选的 _notice.host_compat。
• 失败：{ "ok": false, "error": { "type", "message", "hint" } }，退出码非零。
• 重要提示 — 主机兼容性（首先执行此操作）： 每次运行 ae-cli 后，检查 stderr 和 _notice.host_compat。如果任一处存在兼容性提示，请在回复开头用简短的 ⚠️ 版本警告说明，并逐字引用 npm i -g / npx skills add（或 update-cluster）命令行，然后再呈现业务结果。这只是提示；即使 ok: true，也可能附带此提示。

安全：

• 验证 ID / 名称后，可直接运行只读命令。
• 普通写入（data-table *-write、property-bindings-update、维度表绑定 / 创建）无需 --yes 即可执行。删除命令属于 high-risk-write：先 dry-run、总结影响、等待明确确认，然后使用 --yes 执行。
• 运行任何命令之前，先阅读对应的 references/<name>.md（文件名为将命令中的空格替换为下划线，例如 metadata data-table list → metadata_data_table_list.md）。
• 不要臆造 project_id、事件 / 属性名称、input_file_id 或 data_table_id。复用已验证的名称，或查找元数据查询能力；通过 metadata data-table list 查找数据表 ID。
• metadata data-table download 是异步资源命令：直接调用会提交任务，--wait 会等待，而 --output <file> 会等待后以原子方式写入文件。通过 analysis run wait 恢复；本地中断不会取消远程运行。
• 成员的自然日配额会计入每次符合使用统计条件的 Gateway 能力 execute 调用（用户可识别且已启用统计），包括仅查询元数据、预览、写入表 / 绑定、导出资源，以及会提交任务的下载。是否计入与数据库引擎或业务用途无关。缓存命中、重复调用、复用的运行，以及 execute 内发生的失败都会计入，包括架构错误、权限拒绝和未知能力 ID。Gateway 能力发现（list / inspect）、validate / dry-run，以及独立的运行状态 / 资源下载 HTTP 端点不计入；通过能力执行进行的分页和取消则会计入。遇到 QUERY_DAILY_LIMIT_EXCEEDED（HTTP 429）时，请等待配额重置或联系管理员；QUERY_QUOTA_UNAVAILABLE 会明确报错。不要切换身份以绕过这些错误。省略下载的 --timeout-seconds 以使用服务器默认值；检查所选能力以了解当前策略。

适用场景

用户需要以下操作时使用此技能：

• 列出 / 获取 / 创建 / 更新 / 删除 / 下载元数据数据表
• 上传本地文件时，先通过具有所需用途的可用上传能力获取输入文件标识符，然后继续表操作。
• 将现有数据表绑定到属性，或创建 CSV 维度表并绑定

对于范围之外的工作，请通过协作协议发现可用能力。

命令格式

ae-cli metadata <resource> <action> [options]
ae-cli metadata property <dimension-table-action> [options]

• 命令和标志使用短横线分隔格式：data-table、dimension-table、--project-id、--data-table-id。
• Gateway input 正文字段仍使用下划线分隔格式（project_id、event_name 等）；ae-cli 会自动映射标志。

PROJECT_ID_GATE

在一次对话中复用已验证的项目上下文；否则，查找项目查询能力以解析 project_id。仅当返回的项目确实存在歧义时才询问用户。

Commands (10)

User command	Capability id	Reference
metadata data-table list	metadata.data_table.list	metadata_data_table_list.md
metadata data-table get	metadata.data_table.get	metadata_data_table_get.md
metadata data-table csv-write	metadata.data_table.csv_write	metadata_data_table_csv_write.md
metadata data-table sql-write	metadata.data_table.sql_write	metadata_data_table_sql_write.md
metadata data-table csv-delete	metadata.data_table.csv_delete	metadata_data_table_csv_delete.md
metadata data-table sql-delete	metadata.data_table.sql_delete	metadata_data_table_sql_delete.md
metadata data-table download	metadata.data_table.download	metadata_data_table_download.md
metadata data-table property-bindings-update	metadata.data_table.property_bindings_update	metadata_data_table_property_bindings_update.md
metadata property bind-existing-dimension-table	metadata.property.bind_existing_dimension_table	metadata_property_dimension_table_bind_existing.md
metadata property create-and-bind-csv-dimension-table	metadata.property.create_and_bind_csv_dimension_table	metadata_property_dimension_table_create_and_bind_csv.md

Quick Verification

ae-cli metadata --help
ae-cli metadata data-table list --help
ae-cli metadata data-table list --project-id 1 --dry-run
ae-cli analysis input-file purpose list --project-id 1