ae-dataops

ae-dataops

跨技能协作

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

**关键——此技能是独立的。**请使用下方的全局 AE CLI 规则；对于 DataOps 侧的任务，无需依赖单独的共享技能。

从用户期望的结果入手，然后只阅读下方匹配的参考资料。这些文件属于此技能，而不是单独安装的技能。请使用已安装命令的 --help 获取准确的标志；如果它与此参考资料不一致，请报告版本不匹配，而不要臆造别名。

---

全局 AE CLI 规则

DataOps 任务请使用 ae-cli 和以下参考信息。在整个工作流中保留明确选择的主机和空间。

全局参数：

参数	说明
--format <json|table>	输出格式。默认为 JSON。
--jq <expr>	在封装前对命令负载运行 jq；使用 .flowInstance.status，而非 .data.flowInstance.status。对默认 CLI JSON 使用外部 jq 时，结果包含 .data。
--host <url>	覆盖当前 AE 主机。所有命令均可使用，也可以放在子命令之后，例如 ae-cli dataops_ide +<command> --host <url>。

输出和错误：

• JSON 结果使用外层字段 ok 和 data；命令错误会在 stderr 中返回 ok:false 及 error.type/message/hint，并以非零状态码退出。请检查两个输出流。
• ok:true 不代表业务已完成。 旧版命令可能会在 data 中返回 REJECTED、FAILED 或 CHECK_FAILED。继续操作前，请检查参考资料中说明的具体结果字段。成功读取失败任务的状态，不等于成功执行该任务。
• 对于异步工作，请保留返回的 ID，并查询同一操作。提交不代表完成；不要因为操作仍在运行就再次提交。请使用带退避机制的有限轮询；等待预算耗尽时，报告 ID 和当前状态，不要声称成功或重新启动工作。
• 对于实际的 _notice.host_compat 或明确的版本兼容性警告，请简要说明，并准确引用提供的升级命令。无关的 stderr 输出不是版本警告。

预览语义：

• 表字段变更以及实体回收／删除使用服务器端语义的 --dry-run；请检查返回的阻塞项和计划变更。
• 其他当前 DataOps 的 --dry-run 实现仅显示本地请求，不会验证服务器权限、连接、SQL 或业务状态。如需查看流程发布差异，请使用 +preview_release_flow。
• 当前 DataOps 命令不支持全局的服务器端检查 --validate。不要将其信息性响应视为验证成功。

安全约束：

• 验证必需的 ID 和引用后，可直接执行读取命令。
• 普通 write 命令无需 --yes 即可执行；仅在用户明确确认后，才对 high-risk-write 命令使用 --yes。
• 复用已提供的可信 ID 和上下文；否则使用对应参考资料查找确切资源。结果被截断时，请细化搜索条件或分页；不完整的列表无法证明资源不存在。只有在目标或重大选择仍不明确时才询问。
• 对于现有资源，绝不臆造 ID、字段或参数值。创建资源时需要提供新名称：使用用户要求的名称或提出一个名称，检查是否冲突；不要将名称不存在误认为阻塞项。
• 仅执行到用户要求的结果为止：保存 DEV 不代表获准发布，发布不代表获准手动运行，回收不代表获准永久删除。不要用范围更广的操作替代不受支持的较窄请求。

DataOps 的领域：dataops_repo、dataops_datatable、dataops_flow、dataops_operations、dataops_ide、dataops_integration

---

核心概念和规则

使用前必须了解以下关键概念，否则很可能会出错。

环境和默认值

场景	默认环境	说明
表创建／字段编辑和工作流定义	DEV	如有需要，请单独发布
dataops_datatable +entity_recycle / +recycle_bin_delete	现有的 DEV 和 PRODUCT 映射	实体生命周期操作；并非等待发布的仅限 DEV 的编辑
手动执行流程、运维和回填	PROD	检查确切的流程／作业／实例
SQL 查询	由 SQL 中发现的表决定	不要仅根据示例查询选择 DEV 或 PROD

职责边界

操作	正确工具	禁止使用
执行 SELECT 查询	dataops_ide	—
创建表／视图或修改表字段	dataops_datatable	dataops_ide
回收或永久删除表／视图	dataops_datatable +entity_recycle / +recycle_bin_delete	dataops_ide

流程生命周期

Create DEV Flow → Configure Parameters/Tasks/Dependencies/Schedule → Preview and Release to PROD when requested → Manual Execution / Operations Troubleshooting when requested

自定义流程参数：在 dataops_flow 中使用 +get_flow_params、+create_flow_param、+update_flow_param 和 +delete_flow_param；请参阅流程参考。写入操作会配置 DEV 定义，并可能停止 DEV 调试执行。修改值、类型、名称或删除参数都需要发布后才能应用于 PROD；如果不重命名，仅更新备注，也会同步更新现有 PROD 参数的备注。

回填生命周期：发现符合条件的 PROD 流程 → 创建或完整更新 DRAFT 作业 → 明确启动 → 搜索／检查计划 → 停止或重新运行完整作业；仅在检查目标后才删除

---

场景路由

用户意图	命令组	参考	完成边界
发现或选择空间	dataops_repo	空间发现	确定目标 spaceCode；复用可信上下文
创建表／视图或修改字段类型／注释	dataops_datatable	表工作流	验证 DEV 状态；仅在用户要求时发布
删除表／视图；检查或清空一个回收站条目	dataops_datatable	实体生命周期	普通删除以回收为止；永久删除需要单独授权
创建／配置流程；添加／更新／删除任务和参数；设置调度或发布	dataops_flow	流程配置	读取并确认所请求的 DEV 或 PROD 定义；不要额外手动运行
执行、检查或停止一次运行；排查失败的工作	dataops_flow、dataops_operations	执行与监控	匹配确切的实例；执行整个流程不等于重试失败节点
填充多个历史业务日期的数据	dataops_operations	回填作业	创建草稿、启动作业和计划完成是不同的结果
创建／测试数据源或配置／运行同步	dataops_integration	数据集成	根据用户请求，验证已保存的配置或确切的运行
设置同步调度并发布，但不立即运行	dataops_integration、dataops_flow	数据集成，然后是流程配置	确认 PROD 节点和调度；不手动执行
浏览架构／表或回答数据问题	dataops_datatable、dataops_ide	查询工作流	读取实际结果并回答问题，而不只是返回下载任务 ID

---

1. 空间发现

dataops_repo 仅提供一个读取命令。在调用需要 spaceCode 的 DataOps 命令之前，使用它来发现有效的 spaceCode。它会返回 createTime、spaceCode 和 spaceDisplayName。

• 如果用户已提供可信的 spaceCode，则复用该值。
• 如果未知 spaceCode，先运行 +list_spaces。
• 如果只返回一个空间，则使用其 spaceCode。
• 如果返回多个空间，且用户意图未明确指定其中一个，则询问用户要使用哪个空间。不要猜测。

# List spaces accessible to the current user
ae-cli dataops_repo +list_spaces

---

2. 数据表和视图管理

详细工作流、命令标志、示例和参数说明见 references/dataops-table.md。

关键约束：

• 从 dataops_datatable +dict_search_tables 开始，发现可见的 DataOps 目录。
• 仅使用 dataops_ide +search_tables 查询原始引擎元数据；仅在已知目录／架构中浏览时使用 dataops_ide +ide_list_tables。
• 使用 dataops_datatable 创建表／视图，而非 dataops_ide；创建操作仅限 DEV。需要发布时使用 +publish_entity。
• 在 DEV 中每次添加、修改或删除一个普通表字段；先预览，绝不修改分区字段，并单独发布到 PROD。
• 普通的“删除表／视图”请求仅表示回收，使用 dataops_datatable +entity_recycle。永久删除是单独的工作流，使用 +recycle_bin_list 和 +recycle_bin_delete；执行任一工作流前都要阅读表参考文档。两种写操作都会影响 DEV 和 PRODUCT，并且需要准确的实体 ID、名称、语义化的 --dry-run，以及在使用 --yes 前明确确认。绝不能自动删除同名的旧回收实体以绕过 RECYCLE_NAME_CONFLICT。
• 确认实际回收后，Agent 可以询问是否要永久删除该实体，并警告此操作不可撤销，且可能删除内部表数据。收到新的明确确认前必须停止。这是 Agent 的回复，不是 CLI 提示或 JSON 字段。预览、FAILED、PARTIAL 或未验证状态都不得触发此提议；应先核对同一实体 ID。
• DDL 遵循 Trino 语法；当前空间的视图 DDL 应保留字面量 ${env} 占位符。

---

3. 流程编排

流程参考文档涵盖创建和配置、执行和监控以及回填作业。

生命周期：DEV 配置 → 请求发布 → 请求执行或故障排查。到达用户设定的边界时停止。

详细的创建／配置命令见 references/dataops-flow-create.md。详细的执行、监控、操作实例、任务日志和停止命令见 references/dataops-flow-monitor.md。持久化的多日期回填作业见 references/dataops-backfill.md。

关键约束：

• 在 DEV 中创建和更新任务；在 PROD 执行前先预览／发布。
• 使用 +get_flow_overview 查看自定义 flowParams 和每个任务的 dag.tasks[].taskParams；默认使用 DEV，也支持 PROD，且两者都需要 dwWorkflowEdit。定义会保留表达式文本和从代码解析出的引用，其中 source/value 字段为 null 或省略。
• 查看实例详情需要 dwOMInstanceView；使用 --includeLog true 检查 flowInstance.instanceParamMap 或任务 log.params 中的历史值。
• 将 +delete_task 视为高风险操作：使用 +get_flow_overview 验证目标，使用 --dry-run 预览，并且仅在用户明确确认后使用 --yes。删除会影响 DEV；发布流程后才会应用到 PROD。
• +execute_flow 始终在 PROD 运行；它会返回用于提前停止的 executeId。
• 优先使用操作搜索结果中的 flowInstanceId，以便稳定地检查和排查问题。
• 回填作业会持久化并批处理多个基准日期；不要通过循环调用 +execute_flow 来模拟。
• 使用 +create_backfill_job 创建草稿，并将运行作为单独步骤。+rerun_backfill_job 会重新运行整个作业，而非仅运行失败的计划。
• +update_backfill_job 会替换 DRAFT 作业的完整配置；先检查作业，不要将其视为部分补丁。将 +delete_backfill_job 视为高风险操作，并在确认前使用 --dry-run 预览。
• 在任务 SQL 中使用 ${paramKey} 引用流程或工作区参数。发布前检查概览中的参数来源。

4. IDE SQL 查询

详细的元数据浏览、SQL 查询、异步下载和取消工作流见 references/dataops-query.md。

关键限制：

• IDE 仅支持查询；创建/修改表以及回收/删除实体，请使用 dataops_datatable。
• 除非需要原始引擎元数据或架构浏览，否则优先使用 dataops_datatable +dict_search_tables 查找表。
• 只能提交一条只读 SQL 查询。它会创建一个受平台限制的下载任务；行数据不会直接返回，结果也不是无限制或完整导出。

---

5. 数据集成

详细的数据源、元数据浏览、同步方案、执行和监控工作流见 references/dataops-integration.md。

关键限制：

• 根据参考模板生成 sourceConfig、sinkConfig、channelConfig 和 fieldsMapping；不要自行编造键。
• MySQL Source 读取分区使用 sourceConfig.splitColumn；fieldsMapping.shardingKey 是列元数据，不得用于分区。
• +save_sync_solution 不是部分补丁。当前的 +get_sync_detail --withParams true 返回摘要和已用参数，而非完整的可编辑配置。不要据此重建缺失设置；请参阅集成参考中的更新边界。为兼容而接受 syncName，但会忽略它。
• 预设仓库同步使用 te_etl@TASK_ENGINE_TRINO；服务端根据选定的空间提供网关路由。不要将示例中的公司或空间 ID 复制到配置中。
• 停止正在运行的同步之前，请使用 +list_sync_runs 获取 taskId。

---

参考文档

有关命令标志和用法的详细信息，请参阅 references/ 目录中的命令文档。