ae-engage

ae-engage

AE CLI（ae-cli）是 Agentic Engine 数据分析平台的命令行工具，供 AI Agent 和人类用户使用。

能力约定

• 职责：参与渠道、配置、策略、任务草稿／生命周期、流程、活动及其报告／查询生命周期。
• 输入：经过验证的项目／资源标识符和特定操作所需的配置。复用已知的受众／事件／属性定义；仅在所选操作需要时，才发现缺失的前置条件。
• 输出：配置／任务／资源标识符、报告，或带有实际持久化状态的查询／运行状态。保存草稿不会提交审批或开始发送。
• 边界：常规分析、元数据发现和独立受众创建属于不同的能力；它们并非每项参与请求都必须经过的预处理阶段。
• 完成：验证用户请求的参与操作已完成，或报告待处理／受阻的工作。创建草稿、提交审批和发送是彼此独立的操作，各自都需要符合用户意图。

跨技能协作

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

AE CLI 全局规则

AE CLI（ae-cli）是 AE（Agentic Engine）分析平台的命令行工具。对于 AE 分析侧的请求，优先使用 ae-cli 和本技能的参考文档，而不是依赖模型记忆。

全局参数：

参数	说明
--format <json|table>	输出格式。默认为 JSON。
--jq <expr>	JSON 输出的 jq 筛选表达式。
--host <url>	覆盖当前 AE 主机。每条命令均可使用，也可放在子命令之后，例如：ae-cli engage-flow flow list --host <url>。

输出与错误：

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

安全约束：

• 在验证必需的 ID 和引用后，可直接执行读取命令。
• 写入命令需要用户明确授权。普通 write 命令无需 CLI 确认即可执行；只有 high-risk-write 命令会触发确认门槛。
• 切勿臆造命令名称、标志、JSON 载荷、project_id、资源 ID、字段名称、事件名称、属性名称、指标定义或日期格式。请查阅对应的命令参考，并首先发现实际的项目元数据。
• 绝不可编造或猜测资源名称（报告、仪表板、事件、属性、指标、集群、标签、告警）。始终先使用列表命令发现真实资源。如果模糊搜索和完整列表回退后仍未找到资源，请明确告知用户“未找到资源”并停止操作——不要继续使用编造的名称。

概述

ae-engage 软件包提供 Hermes Engage 功能，涵盖配置项、流程、渠道设置、任务数据和查询生命周期。通过 ae-cli engage-flow|engage-task|engage-setting|engage-scene|engage-query <resource> <action> 使用 capability-gateway 命令；低频报告请参阅下方的 L3 参考资料。

典型用例包括：

• 查询和管理渠道、配置渠道、审批人和白名单
• 查询项目渠道触达限制或疲劳控制规则
• 查询任务列表、任务详情、实验报告和指标报告
• 查询配置项和策略、复制模板以及管理策略状态
• 查询流程列表、节点架构和流程报告，以及保存或管理流程

关键词路由

当用户提到下列产品术语（包括常见的中文 UI 标签）时，先打开列出的参考文档——不要猜测命令或 ID。

关键词	产品含义	CLI 域	主要参考文档	相关参考文档
配置中心	Engage 场景管理／配置中心概览	engage-scene	references/scene-config-item.md	scene-config-param.md、scene-config-group.md、scene-preset-metric.md、scene-config-metric.md、scene-config-channel.md、channel-mgmt.md、scene-strategy.md、scene-template.md；L3 报告：config-item-trigger-report.md、config-item-analysis-report.md、config-item-strategy-comparison.md
场景配置	与配置中心相同；配置项下的参数、分组、指标、渠道、策略和模板	engage-scene	references/scene-config-item.md	同上；参数／分组／指标：scene-config-param.md、scene-config-group.md、scene-preset-metric.md、scene-config-metric.md
配置项	配置中心中的单个配置项	engage-scene	references/scene-config-item.md	scene-config-param.md、scene-preset-metric.md、scene-config-metric.md、scene-strategy.md、scene-template.md
推送渠道	项目级消息推送渠道（Webhook、FCM、APNS 等）	engage-setting	references/channel-list.md	channel-detail.md、add-channel.md（Webhook 与 Client 不同：url 分别表示 HTTP 和场景键；自定义参数分别使用 user: 与 user:／client:）、update-channel-status.md、delete-channel.md、channel-update-config.md、channel-test-send.md、channel_touch_limits_list.md
配置渠道	配置中心的 Webhook／客户端配置渠道（与推送渠道不同）	engage-scene	references/scene-config-channel.md	channel-mgmt.md（创建／启用-禁用／复制／删除工作流）。config.customsParamList 中的用户参数必须使用带 user: 前缀的 columnName（例如 user:#account_id）；复用已验证的属性名称，或查找属性查询功能。
运营策略	配置项下的运营／投放策略	engage-scene	references/scene-strategy.md	自定义受众：scene-strategy-audience.md — 使用语义化的 definitionRequest（Analysis 条件结构）；不要传入 targetClusterQp／qp；预检属性（缺失时停止并列出）；模板：scene-template.md
运营任务	Hermes 推送／互动任务（列表、保存、生命周期、报告）	engage-task	references/task-list.md	task-detail.md（获取）、save-task.md、build-task-save-guide.md、task-stats.md、task-delete.md、push-record-query.md、task-user-detail-export.md、task-indicator-user.md、task-data-overview.md、task-data-detail.md、task-metric-detail.md、task-metric-update.md、task-experiment-report.md
运营活动	活动管理，以及按活动、主题或独立任务查看投放趋势	engage-activity	references/activity-activity.md	activity-data-detail.md、activity-topic.md、activity-task.md、activity-approval.md
模板	配置项下的策略模板	engage-scene	references/scene-template.md	scene-config-param.md（模板字段引用 paramId）；创建策略前，先通过 template update 启用模板，再执行 template update-status

容易混淆的术语：

• 推送渠道 → ae-cli engage-setting channel …（Hermes 推送渠道设置）
• 配置渠道 → ae-cli engage-scene config-channel …（配置中心渠道；参见 channel-mgmt.md）
• 流程／任务画布节点使用来自推送渠道的 channelId；配置项绑定来自配置渠道的 channel_id

参数约定

• 简单参数使用常规标志，例如 --project-id、--task-id 和 --flow-uuid
• 数组参数使用 JSON 标志，例如 --strategy-uuid-list '["id1","id2"]'
• 对象参数使用带名称的 JSON 标志，例如 --req '{...}' 和 --flow-list '[...]'
• 可选的全局参数与其他领域中的用法相同，例如 --host、--mcp-url 和 --dry-run

命名边界：

• CLI 标志使用 kebab-case；外层 Capability 输入及所有 Capability 响应键均使用 snake_case。
• 通过 --req 或 --payload 传入的嵌套业务 DTO 保留其文档中规定的原生 camelCase 字段。不要机械地将这些嵌套 DTO 键转换为 snake_case。
• 语义受众、事件、触发条件、完成条件和指标定义均为封闭契约。CLI 会在本地拒绝格式错误或未知的语义字段；--validate 使用相同的精确 Hermes Capability 模式进行校验，但不会写入数据。
• 成功迁移的命令会在 data 下返回其业务负载；选择字段前请先查看对应参考文档中的 Response 结构。

JSON 参数格式

常见的 JSON 标志示例：

--provider-list '["webhook","fcm"]'
--strategy-uuid-list '["strategy_a","strategy_b"]'
--flow-id-list '["flow_1","flow_2"]'
--req '{"pageNum":1,"pageSize":20}'

常见场景

1. 设置

# Query the channel list
ae-cli engage-setting channel list --project-id 1

# Filter by provider
ae-cli engage-setting channel list --project-id 1 --provider-list '["webhook","fcm"]'

# Query config channels (config center channel management — use engage-scene, not legacy +config_channel_*)
ae-cli engage-scene config-channel list --project-id 1 --channel-type 0

# Query project channel touch-limit rules
ae-cli engage-setting channel-touch-limits list --project-id <project_id>

# Update a channel's config / reach-funnel settings
ae-cli engage-setting channel update-config --project-id <project_id> --channel-id <channel_id> --enable-touch-event 1

# Send a test message to a channel
ae-cli engage-setting channel test-send --project-id <project_id> --channel-id <channel_id> --push-id <send_id> --content-list '[{"key":"title","value":"hello"}]'

# Batch update / toggle / save channel touch-limit (fatigue-control) rules
ae-cli engage-setting channel-touch-limits batch-update --project-id <project_id> --items '[{"rule_id":"r1","enable":true,"rule_def":"[]"}]'
ae-cli engage-setting channel-touch-limits toggle --project-id <project_id> --rule-id <rule_id> --enable false
ae-cli engage-setting channel-touch-limits save --project-id <project_id> --channel-biz-type <biz_type> --rule-def '[]' --enable true

# Remove an approver from a project
ae-cli engage-setting approval-approver delete --project-id <project_id> --approver <open_id> --yes

# Whitelist add / update / delete / verify
ae-cli engage-setting whitelist add --project-id <project_id> --prop-code <prop_code> --column-name <column_name> --column-type string --whitelist-list '[{"entity_id":"u1","source_value":"v1"}]'
ae-cli engage-setting whitelist update --project-id <project_id> --whitelist-id <id> --note-name <name>
ae-cli engage-setting whitelist delete --project-id <project_id> --whitelist-ids '["wl-1"]' --yes
ae-cli engage-setting whitelist verify --project-id <project_id> --prop-code <prop_code> --column-type string --whitelist-prop-list '["v1"]'

# Push-language (localization) get / set
ae-cli engage-setting push-language get --project-id <project_id>
ae-cli engage-setting push-language set --project-id <project_id> --push-language-column <prop_code>

# Client param update / delete / list
ae-cli engage-setting client-param create --project-id <project_id> --column-name level --column-type varchar --column-desc Level
ae-cli engage-setting client-param update --project-id <project_id> --column-name level --column-desc Level
ae-cli engage-setting client-param delete --project-id <project_id> --column-name level --yes
ae-cli engage-setting client-param list --project-id <project_id>

# Config table upload / save / list / query-data / update-data / delete
ae-cli engage-setting config-table upload --project-id <project_id> --request-id <rid> --file-name data.csv --file-content "$(base64 -i data.csv)"
ae-cli engage-setting config-table save --project-id <project_id> --request-id <rid> --info-name <table_name>
ae-cli engage-setting config-table list --project-id <project_id>
ae-cli engage-setting config-table query-data --project-id <project_id> --info-id <info_id>
ae-cli engage-setting config-table update-data --project-id <project_id> --request-id <rid> --info-name <table_name> --info-id <info_id>
ae-cli engage-setting config-table delete --project-id <project_id> --info-id <info_id> --yes

# Preset event list / update
ae-cli engage-setting preset-event list --project-id <project_id>
ae-cli engage-setting preset-event update --project-id <project_id> --add-event-definition '<semantic_event_json>'

# Common metric list / get / create / update / delete
ae-cli engage-setting common-metric list --project-id <project_id>
ae-cli engage-setting common-metric get --project-id <project_id> --metric-name <name>
ae-cli engage-setting common-metric create --project-id <project_id> --metric-type 1 --metric-name <name> --metric-definition '<semantic_metric_json>' --metric-window-num 1 --metric-window-time-unit day --display-name <display>
ae-cli engage-setting common-metric update --project-id <project_id> --metric-type 1 --metric-name <name> --metric-definition '<semantic_metric_json>' --metric-window-num 1 --metric-window-time-unit day --display-name <display>
ae-cli engage-setting common-metric delete --project-id <project_id> --metric-name <name> --yes

2. 任务

# Query the task list
ae-cli engage-task task list --project-id 1 --req '{"pageNum":1,"pageSize":20}'

# Build a save_task guide before composing the final req
ae-cli engage-task task build-save-guide --project-id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'

# Save a task draft (create when req.taskId is omitted)
ae-cli engage-task task save --project-id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'

# Query task details
ae-cli engage-task task get --project-id 1 --task-id task_123

# Submit a saved draft task for approval
ae-cli engage-task task submit-approval --project-id 1 --task-id task_123

# Query task reports through the Hermes inline task-data capabilities
ae-cli engage-task effect query --project-id 1 --task-id task_123 --start-time 2026-04-01 --end-time 2026-04-07 --metric-id-list '["metric_1"]'
ae-cli engage-task data-detail query --project-id 1 --task-id task_123 --detail-type time --start-time 2026-04-01 --end-time 2026-04-07
ae-cli engage-task indicator-user sql --project-id 1 --task-id task_123 --indicator main --start-time 2026-04-01 --end-time 2026-04-07
ae-cli engage-task indicator-user run --project-id 1 --task-id task_123 --indicator secondary --secondary-index 1 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100
ae-cli engage-task indicator-user export --project-id 1 --task-id task_123 --indicator metric --metric-id metric_1 --source metric --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv

对于 L3 任务报告，调用前请阅读 references/task-data-overview.md、references/task-data-detail.md、 references/task-metric-detail.md 或 references/task-experiment-report.md。 使用 engage-task indicator-user 前，请阅读 references/task-indicator-user.md；其中的分组、 指标、摘要/详情、度量、实验和时区标志存在条件兼容规则。

3. 配置

# Query the config item list
ae-cli engage-scene config-item list --project-id 1

# Query the strategy list
ae-cli engage-scene strategy list --project-id 1 --config-id cfg_123

对于 L3 配置报告，调用前请阅读 references/config-item-trigger-report.md、 references/config-item-analysis-report.md 或 references/config-item-strategy-comparison.md。

4. 流程

# Query the flow list
ae-cli engage-flow flow list --project-id 1

# Query flow details
ae-cli engage-flow flow get --project-id 1 --flow-uuid flow_uuid_123

# Query flow operation records and application logs
ae-cli engage-flow operation-log query --project-id 1 --flow-id flow_id_123

# Query flow versions and task push records
ae-cli engage-flow version list --project-id 1 --flow-id flow_id_123
ae-cli engage-flow flow update-remark --project-id 1 --flow-uuid flow_uuid_123 --flow-version-desc "Second version"
ae-cli engage-task operation-log query --project-id 1 --task-id task_id_123
ae-cli engage-task push-record query --project-id 1 --task-id task_id_123 --page-num 1 --page-size 20
ae-cli engage-task user-detail export --project-id 1 --task-id task_id_123 --task-instance-id instance_123 --user-status fail --artifact-format csv
ae-cli engage-task segment-list query --project-id 1 --task-id task_id_123
ae-cli engage-task group list --project-id 1
ae-cli engage-task metric list --project-id 1 --task-id task_id_123
ae-cli engage-task channel-ref stats --project-id 1 --channel-id channel_123
ae-cli engage-task task delete --project-id 1 --task-id task_id_123 --yes
ae-cli engage-task task submit-approval --project-id 1 --task-id task_id_123

# Query the node schema
ae-cli engage-flow node-config schema --project-id 1 --node-type message_push
ae-cli engage-flow metric update --project-id 1 --flow-id flow_id_123 --metric-map '<metric_map_json>'

# Query or export newly exposed flow report surfaces
ae-cli engage-flow report metric-detail run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
ae-cli engage-flow report metric-detail export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600
ae-cli engage-flow metric-user run --project-id 1 --flow-id flow_id_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
ae-cli engage-flow metric-user export --project-id 1 --flow-id flow_id_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600
ae-cli engage-flow node-user run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
ae-cli engage-flow node-user export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600
ae-cli engage-flow node-metric-user run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name metric_setting_id_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
ae-cli engage-flow node-metric-user export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name metric_setting_id_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600

用户详情 run 命令用于有界的内联行，并接受 --request-id、--limit 和 --timeout-seconds；度量详情 run 会返回报告对象。导出命令接受 --request-id、--artifact-format csv|jsonl（默认值为 jsonl）和 --timeout-seconds，然后返回 run_id 和 artifact_id；使用 ae-cli engage-query run inspect --run-id RUN_ID 轮询，再使用 ae-cli engage-query artifact download --run-id RUN_ID --artifact-id ARTIFACT_ID --output ./artifact.jsonl.gz 下载。使用 ae-cli engage-query query cancel --run-id RUN_ID 取消正在运行的异步任务。

对于流程报告/用户详情命令，在编写复杂输入前请阅读对应的参考文档：

• 流程画布自定义度量配置：references/flow-metric-update.md
• 度量详情报告对象或扁平化报告导出：references/flow-metric-detail-report.md
• 流程级度量分段中的用户：references/flow-metric-user.md
• 节点级数据分段中的用户：references/flow-node-user.md
• 节点级度量分段中的用户：references/flow-node-metric-user.md

5. 场景（场景管理/配置中心）

新增的 capability-gateway 命令组 engage-scene 覆盖配置中心：配置项、参数、分组、预设/关联度量、配置渠道、策略和模板。复杂 DTO 使用 --payload 传入（原生 camelCase JSON）。

# Config item list / get / create / update / delete
ae-cli engage-scene config-item list --project-id <project_id>
ae-cli engage-scene config-item get --project-id <project_id> --config-id <config_id>
ae-cli engage-scene config-item create --project-id <project_id> --config-id <config_id> --config-name <name> --business-type params
ae-cli engage-scene config-item update --project-id <project_id> --config-id <config_id> --config-name <name>
ae-cli engage-scene config-item delete --project-id <project_id> --config-id <config_id> --open-id <open_id> --yes

# Config param list / batch-add / update / batch-delete
ae-cli engage-scene config-param list --project-id <project_id> --config-id <config_id>
ae-cli engage-scene config-param batch-add --project-id <project_id> --config-id <config_id> --params '[{"param_name":"a","param_type":"string"}]'
ae-cli engage-scene config-param update --project-id <project_id> --config-id <config_id> --param-id <param_id> --param-name a
ae-cli engage-scene config-param batch-delete --project-id <project_id> --param-ids '[1,2]' --yes

# Config group list / batch-add / update / batch-delete
ae-cli engage-scene config-group list --project-id <project_id>
ae-cli engage-scene config-group batch-add --project-id <project_id> --group-names '["g1"]'
ae-cli engage-scene config-group update --project-id <project_id> --group-id <group_id> --group-name g2
ae-cli engage-scene config-group batch-delete --project-id <project_id> --group-ids '[1,2]' --yes

# Preset metric get / set
ae-cli engage-scene preset-metric get --project-id <project_id> --config-id <config_id>
ae-cli engage-scene preset-metric set --project-id <project_id> --config-id <config_id> --impression-event-definition '<semantic_event_json>'

# Config metric list / get / batch-add / update-rule / batch-delete
ae-cli engage-scene config-metric list --project-id <project_id> --config-id <config_id>
ae-cli engage-scene config-metric get --project-id <project_id> --metric-id <metric_id>
ae-cli engage-scene config-metric batch-add --project-id <project_id> --config-id <config_id> --ta-metric-ids '[1,2]'
ae-cli engage-scene config-metric update-rule --project-id <project_id> --metric-id <metric_id> --event-list '[{"event_name":"e1","filter":"true"}]'
ae-cli engage-scene config-metric batch-delete --project-id <project_id> --config-id <config_id> --metric-ids '[1,2]' --yes

# Config channel list / get / create / update / update-status / delete / query-log
# User params: reuse or discover verified customsParamList property names; then use user:<prop_name>
# Strategy custom audience: scene-strategy-audience.md — semantic definitionRequest; strategy predict for 预估人数
# Workflows: references/channel-mgmt.md · schema: references/scene-config-channel.md
ae-cli engage-scene config-channel list --project-id <project_id> [--channel-type 0|1]
ae-cli engage-scene config-channel get --project-id <project_id> --channel-id <channel_id>
ae-cli engage-scene config-channel create --project-id <project_id> --channel-name <name> --channel-type 0 --config '<json>'
ae-cli engage-scene config-channel update --project-id <project_id> --channel-id <channel_id> --channel-name <name> [--config '<json>']
ae-cli engage-scene config-channel update-status --project-id <project_id> --channel-id <channel_id> --channel-status 1|2
ae-cli engage-scene config-channel delete --project-id <project_id> --channel-id <channel_id> --yes
ae-cli engage-scene config-channel query-log --project-id <project_id> --channel-id <channel_id>

# Strategy create / update / log / batch-copy
ae-cli engage-scene strategy create --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","strategyName":"s1"}'
ae-cli engage-scene strategy update --project-id <project_id> --payload '{"strategyUuid":"uuid-1"}'
ae-cli engage-scene strategy log --project-id <project_id> --strategy-uuid <uuid>
ae-cli engage-scene strategy predict --project-id <project_id> --definition-request '{"type":"condition","conditions":{...}}' --zone-offset 8 [--strategy-uuid <uuid>]
ae-cli engage-scene strategy batch-copy --project-id <project_id> --config-id <config_id> --strategy-ids '["s1"]'

# Template list / get / create / update / update-status / delete
ae-cli engage-scene template list --project-id <project_id> --config-id <config_id>
ae-cli engage-scene template get --project-id <project_id> --config-id <config_id> --template-id <template_id>
ae-cli engage-scene template create --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","templateName":"t1"}'
ae-cli engage-scene template update --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","config":[]}'
ae-cli engage-scene template update-status --project-id <project_id> --config-id <config_id> --template-id <template_id> --status 1
ae-cli engage-scene template delete --project-id <project_id> --config-id <config_id> --template-id <template_id> --yes

6. 活动（营销活动）

新增的 capability-gateway 命令组 engage-activity 覆盖营销活动：活动、审批工作流、主题、活动类型和独立任务。复杂 DTO 使用 --payload 传入（原生 camelCase JSON）。

活动载荷约束

生成任何活动主题或独立任务载荷之前，必须遵循 Hermes 活动 UI 支持的同一子集：

• triggerType 必须为 0（单次定时）或 1（重复定时）。活动任务不支持手动（2）或触发式（3-6）任务类型。
• 不得配置 A/B 或赛马实验。省略 expConfig，或仅使用 {"enableExp":false}，并且恰好提供一个非实验性的 groupContentList 组。
• 独立活动任务必须使用 triggerTimeStrategy: "fixed_time_zone" 和父活动的 tzOffset。定时时间必须位于活动期间内。
• 主题根节点支持受众类型 1（自定义）和 2（已有群组），不支持 3（所有用户）。独立活动任务可以使用 1、2 或 3。
• 主题任务继承主题的定时安排、时区、渠道、频率限制、渠道触达限制、白名单和实验设置。它们只能添加仅包含用户的自定义 definitionRequest；绝不得生成任务级 clusterKey、触发规则或共享设置覆盖项。topic get 可能会返回规范任务标记 targetClusterType=1；如果存在，更新时请保留，但绝不得使用其他任务级值。
• 先解析父活动，并确认其可编辑（mappingStatus 为 0、2 或 5）。主题、任务和语言的限制值属于项目配置；不得硬编码默认值。
• approval submit 和 approval approve 会验证每个已持久化的活动任务。审批不会规范化不受支持的任务数据。遇到 ACTIVITY_TASK_COMPATIBILITY_VIOLATION 时，按需取消／撤回审批，修正或重新创建每个报告的问题任务，然后重新提交。

# Activity create / update / delete / list / get / pause / end / stats / info-list
ae-cli engage-activity activity create --project-id <project_id> --payload '{"activityName":"a1","activityType":"other_type","tzOffset":8,"periodType":0}'
ae-cli engage-activity activity update --project-id <project_id> --payload '{"activityId":"act-1","activityName":"a1","activityType":"other_type","tzOffset":8,"periodType":0}'
ae-cli engage-activity activity delete --project-id <project_id> --activity-id <activity_id> --yes
ae-cli engage-activity activity list --project-id <project_id> --page 1 --page-size 20
ae-cli engage-activity activity get --project-id <project_id> --activity-id <activity_id>
ae-cli engage-activity activity pause --project-id <project_id> --activity-id <activity_id>
ae-cli engage-activity activity end --project-id <project_id> --activity-id <activity_id>
ae-cli engage-activity activity stats --project-id <project_id>
ae-cli engage-activity activity info-list --project-id <project_id> --activity-id <activity_id>

# Approval submit / approve / reject / cancel
ae-cli engage-activity approval submit --project-id <project_id> --activity-id <activity_id> [--reason <reason>]
ae-cli engage-activity approval approve --project-id <project_id> --activity-id <activity_id>
ae-cli engage-activity approval reject --project-id <project_id> --activity-id <activity_id> --reason <reason>
ae-cli engage-activity approval cancel --project-id <project_id> --activity-id <activity_id>

# Topic create / update / remove-task / delete / get / copy
# See references/activity-topic.md for topicClusterKey vs task clusterKey and triggerType notes.
ae-cli engage-activity topic create --project-id <project_id> --payload '{"activityId":"act-1","topicName":"t1","targetClusterType":2,"topicClusterKey":"<cluster>","channelType":1,"channelId":"c1","triggerType":0,"triggerTime":"2026-12-31 12:00","enableChannelTouchLimits":false,"frequencyLimits":"{}","tasks":[...]}'
ae-cli engage-activity topic update --project-id <project_id> --payload '{"topicId":"topic-1", ...}'
ae-cli engage-activity topic remove-task --project-id <project_id> --task-id <task_id> --yes
ae-cli engage-activity topic delete --project-id <project_id> --topic-id <topic_id> --yes
ae-cli engage-activity topic get --project-id <project_id> --topic-id <topic_id>
ae-cli engage-activity topic copy --project-id <project_id> --topic-id <topic_id> [--new-name <name>]

# Activity type list / batch-add / update / batch-delete
ae-cli engage-activity activity-type list --project-id <project_id>
ae-cli engage-activity activity-type batch-add --project-id <project_id> --type-names '["t1","t2"]'
ae-cli engage-activity activity-type update --project-id <project_id> --id <type_id> --type-name t3
ae-cli engage-activity activity-type batch-delete --project-id <project_id> --ids '["id1","id2"]' --yes

# Standalone task get / create / update / copy
ae-cli engage-activity task get --project-id <project_id> --task-id <task_id>
ae-cli engage-activity task create --project-id <project_id> --payload '{"taskName":"t1","activityId":"act-1", ...}'
ae-cli engage-activity task update --project-id <project_id> --payload '{"taskId":"task-1", ...}'
ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [--new-name <name>]

7. 工作台

新的能力网关命令组 engage-workbench 涵盖工作台指标槽位：每位用户每个项目最多可配置 4 张指标卡片。槽位按用户区分；update／delete 只会影响调用者自己的槽位。首次执行 list 时会自动初始化 4 个默认槽位。

# Workbench slot list / add / update / delete
ae-cli engage-workbench workbench list --project-id <project_id>
ae-cli engage-workbench workbench add --project-id <project_id> --metric-type <metric_type> --date-type <date_type> --order-id 1
ae-cli engage-workbench workbench update --project-id <project_id> --slot-id <slot_id> --metric-type <metric_type> --date-type <date_type> --order-id 1
ae-cli engage-workbench workbench delete --project-id <project_id> --slot-id <slot_id> --yes

engage-flow flow save 的关键约束

当用户想要“创建工作流／生成工作流画布／保存工作流”时，不要将 engage-flow flow save 视为普通的单条命令。必须遵循以下工作流。

必需的工作流

1. 首先确认用户意图是否足够明确。至少需要了解：

   • 业务场景
   • 目标用户
   • 触点或交付方式
   • 是否需要分支，以及分支条件

2. 不要直接从自然语言跳到 --req。必须先整理出稳定的中间意图结构，再将其映射到最终的 req。

3. 使用语义化的 targetDefinitionRequest 和 triggerDefinition 对象构建条件相关节点。通过 Analysis 元数据解析实际的事件和属性名称； 不要仅仅为了获取持久化 QP 而创建中间集群。

4. 在构建 message_push、wechat_push 或 webhook_push 等触点节点之前，必须调用：

ae-cli engage-setting channel list --project-id <projectId>

5. engage-flow flow save 是基于操作的（协议 v2）。--req 对象必须携带值为 build、preview 或 commit 的 operation。不要使用旧的 nodeList / edgeList 字段名；应使用 nodes / edges 并设置 operation=build。旧版 nodeList/edgeList 负载（或缺少 operation）会被拒绝，并返回 Unsupported save_flow operation: null。
6. 按生命周期执行：build（返回 data.result.status = ready_to_preview 或 need_input）→ 解析任何 data.result.next_slot → preview（重新签发响应字段 data.result.draft_version + data.result.confirm_token）→ commit（将这些值映射到请求字段 draftVersion + confirmToken）→ 从 data.result.result.flow_uuid 读取最终 ID。
7. nodes[].config / edges[].config 可以是 JSON 对象或 JSON 字符串。自定义受众节点和分支使用语义化的 targetDefinitionRequest；Hermes 会将其编译为节点存储的执行格式。 切勿发送 targetClusterQp。每个受众的 event 和 behavior_sequence 都必须包含 各自的 time_range；Flow 的入口日期不能替代该范围。只能使用能够通过 Flow 编辑器当前项目、时区和用户实体元数据范围解析的属性。
8. 在预览/提交前，必须自行检查：
   • 恰好有一个入口节点
   • 至少有一个 exit_flow
   • edge.source 和 edge.target 都引用有效节点
   • 任何分支节点的 sourceBranchId 都已在上游节点的 config 中声明
   • 整个图是 DAG，且不包含循环

明确禁止

• 不要编造 channelId
• 用户未提供足够信息时，不要填写分支逻辑
• 不要将业务语义节点直接作为最终的 nodes 提交
• 不要使用旧版 nodeList / edgeList，也不要省略 operation

推荐顺序

User request
-> Organize intent
-> analysis user-cluster create/get
-> engage-setting channel list --project-id <projectId>
-> Build nodes / edges
-> Self-check
-> engage-flow flow save operation=build -> (need_input?) -> preview -> commit
-> engage-flow flow get (verify)

如需了解更详细的生成规则，请先查阅以下参考资料：

• references/save-flow.md
• references/flow-node-config-schema.md
• references/validate-flow-node-config.md

试运行调试

ae-cli --dry-run engage-setting channel list --project-id 1
ae-cli --dry-run engage-task task list --project-id 1 --req '{"pageNum":1,"pageSize":20}'
ae-cli --dry-run engage-task task build-save-guide --project-id 1 --req '{}'
ae-cli --dry-run engage-task task save --project-id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'
ae-cli --dry-run engage-flow flow list --project-id 1

参考资料

references/ 目录中提供了面向业务的单命令详细指南：

• references/channel-list.md（engage-setting.channel.list）
• references/channel-detail.md（engage-setting.channel.get）
• references/add-channel.md（engage-setting.channel.create）
• references/update-channel-status.md（engage-setting.channel.update-status）
• references/delete-channel.md（engage-setting.channel.delete）
• references/channel_touch_limits_list.md（engage-setting.channel-touch-limits.list）
• references/channel-touch-limits-batch-update.md（engage-setting.channel-touch-limits.batch-update）
• references/channel-touch-limits-toggle.md（engage-setting.channel-touch-limits.toggle）
• references/channel-touch-limits-save.md（engage-setting.channel-touch-limits.save）
• references/channel-update-config.md（engage-setting.channel.update-config）
• references/channel-test-send.md（engage-setting.channel.test-send）
• references/approval-approver-delete.md（engage-setting.approval-approver.delete）
• references/add-approver.md / references/approver-list.md（engage-setting.approval-approver.{add,list}）
• references/whitelist-list.md / references/whitelist.md（engage-setting.whitelist.{list,add,update,delete,verify}）
• references/cancel-query-by-request-id.md（engage-setting.query.cancel，L3）
• references/cancel-query-run.md（engage-query.query.cancel）
• references/push-language.md（engage-setting.push-language.{get,set}）
• references/client-param.md（engage-setting.client-param.{create,update,delete,list}）
• references/config-table.md（engage-setting.config-table.{upload,save,list,query-data,update-data,delete}）
• references/preset-event.md（engage-setting.preset-event.{list,update}）
• references/common-metric.md（engage-setting.common-metric.{list,get,create,update,delete}）
• references/scene-config-item.md（engage-scene.config-item.{list,get,create,update,delete}）
• references/scene-config-param.md（engage-scene.config-param.{list,batch-add,update,batch-delete}）
• references/scene-config-group.md（engage-scene.config-group.{list,batch-add,update,batch-delete}）
• references/scene-preset-metric.md（engage-scene.preset-metric.{get,set}）
• references/scene-config-metric.md（engage-scene.config-metric.{list,get,batch-add,update-rule,batch-delete}）
• references/scene-config-channel.md（engage-scene.config-channel.{list,get,create,update,update-status,delete,query-log}）
• references/channel-mgmt.md（配置渠道管理工作流）
• references/scene-strategy.md（engage-scene.strategy.{list,get,create,update,log,predict,batch-copy,manage}）
• references/scene-strategy-audience.md（自定义受众语义 definitionRequest、预检、预测）
• references/scene-template.md（engage-scene.template.{list,get,copy,create,update,update-status,delete}）
• references/config-item-trigger-report.md（engage-scene.report.config-item-trigger，L3）
• references/config-item-analysis-report.md（engage-scene.report.config-item-analysis，L3）
• references/config-item-strategy-comparison.md（engage-scene.report.strategy-comparison，L3）
• references/activity-activity.md（engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}）
• references/activity-data-detail.md（engage-activity.activity-data.detail，L3）
• references/activity-approval.md（engage-activity.approval.{submit,approve,reject,cancel}）
• references/activity-topic.md（engage-activity.topic.{create,update,remove-task,delete,get,copy}）
• references/activity-activity-type.md（engage-activity.activity-type.{list,batch-add,update,batch-delete}）
• references/activity-task.md（engage-activity.task.{get,create,update,copy}）
• references/workbench-workbench.md（engage-workbench.workbench.{list,add,update,delete}）
• references/build-task-save-guide.md
• references/save-task.md
• references/task-list.md
• references/flow-list.md
• references/operation-log-query.md（engage-flow.operation-log.query）
• references/task-operation-log-query.md（engage-task.operation-log.query）
• references/version-list.md（engage-flow.version.list）
• references/flow-update-remark.md（ae-cli engage-flow flow update-remark；能力 engage-flow.version.update-remark）
• references/push-record-query.md（engage-task.push-record.query）
• references/task-user-detail-export.md（engage-task user-detail export；能力 engage-task.user-detail.export）
• references/task-indicator-user.md（engage-task indicator-user {sql,run,export}；能力 engage-task.indicator-user.{sql,run,export}）
• references/segment-list-query.md（engage-task.segment-list.query）
• references/group-list.md（engage-task.group.list）
• references/task-delete.md（engage-task.task.delete）
• references/task-submit-approval.md（engage-task.task.submit-approval）
• references/task-data-detail.md（engage-task data-detail query；能力 engage-task.task-data.detail）
• references/task-metric-detail.md（engage-task effect query；能力 engage-task.task-data.metric-detail）
• references/task-metric-update.md（engage-task metric update；能力 engage-task.metric.update）
• references/flow-metric-update.md（engage-flow metric update；能力 engage-flow.metric.update） 这种拆分的文档结构更便于后续扩展，因为具有更复杂对象输入的命令可以集中放在 references/ 根目录中。

命令组

setting

channel-touch-limits list / channel-touch-limits batch-update / channel-touch-limits toggle / channel-touch-limits save / channel update-config / channel test-send / channel list / channel get / channel create / channel update-status / channel delete / approval-approver add / approval-approver list / approval-approver delete / whitelist list / whitelist add / whitelist update / whitelist delete / whitelist verify / push-language get / push-language set / client-param create / client-param update / client-param delete / client-param list / config-table upload / config-table save / config-table list / config-table query-data / config-table update-data / config-table delete / preset-event list / preset-event update / common-metric list / common-metric get / common-metric create / common-metric update / common-metric delete（通过 engage-setting），以及 L3 能力 engage-setting.query.cancel

task

operation-log query / push-record query / user-detail export / indicator-user sql / indicator-user run / indicator-user export / segment-list * / ops * / metric * / race release / channel-ref stats / group * / task delete / task modify-group / task submit-approval / task get / task list / task stats / task build-save-guide / task save / task manage / effect query / data-detail query（通过 engage-task），以及 L3 能力 engage-task.task-data.{overview,detail,metric-detail,experiment-report}

query

run inspect / artifact download / query cancel（通过 engage-query），能力 ID engage-query.query.cancel

config

旧版 config MCP 命令已迁移至 scene L2 组，以及以下三个 L3 报告能力。

scene

config-item list / config-item get / config-item create / config-item update / config-item delete / config-param list / config-param batch-add / config-param update / config-param batch-delete / config-group list / config-group batch-add / config-group update / config-group batch-delete / preset-metric get / preset-metric set / config-metric list / config-metric get / config-metric batch-add / config-metric update-rule / config-metric batch-delete / config-channel list / config-channel get / config-channel create / config-channel update / config-channel update-status / config-channel delete / config-channel query-log / strategy list / strategy get / strategy create / strategy update / strategy log / strategy batch-copy / strategy manage / template list / template get / template copy / template create / template update / template update-status / template delete（通过 engage-scene），能力 ID engage-scene.config-item.{list,get,create,update,delete}、engage-scene.config-param.{list,batch-add,update,batch-delete}、engage-scene.config-group.{list,batch-add,update,batch-delete}、engage-scene.preset-metric.{get,set}、engage-scene.config-metric.{list,get,batch-add,update-rule,batch-delete}、engage-scene.config-channel.{list,get,create,update,update-status,delete,query-log}、engage-scene.strategy.{list,get,create,update,log,batch-copy,manage}、engage-scene.template.{list,get,copy,create,update,update-status,delete}，以及 L3 能力 engage-scene.report.{config-item-trigger,config-item-analysis,strategy-comparison}

活动

activity create / activity update / activity delete / activity list / activity get / activity pause / activity end / activity stats / activity info-list / approval submit / approval approve / approval reject / approval cancel / topic create / topic update / topic remove-task / topic delete / topic get / topic copy / activity-type list / activity-type batch-add / activity-type update / activity-type batch-delete / task get / task create / task update / task copy（通过 engage-activity），能力 ID：engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}、engage-activity.approval.{submit,approve,reject,cancel}、engage-activity.topic.{create,update,remove-task,delete,get,copy}、engage-activity.activity-type.{list,batch-add,update,batch-delete}、engage-activity.task.{get,create,update,copy}

工作台

workbench list / workbench add / workbench update / workbench delete（通过 engage-workbench），能力 ID：engage-workbench.workbench.{list,add,update,delete}

流程

operation-log query / version list / flow update-remark / flow save / node-config schema / flow get / flow list / flow manage / node-config validate / flow delete / flow modify-base-info / metric update / report metric-detail run / report metric-detail export / metric-user run / metric-user export / node-user run / node-user export / node-metric-user run / node-metric-user export（通过 engage-flow），以及 L3 能力 engage-flow.report.{node-overview,process,node-detail,ab-split-node}

日期格式

接受日期参数的命令通常使用 yyyy-MM-dd，例如 --start_time 2026-04-01。

写操作提醒

所有写操作都需要相应的用户意图。高风险删除命令（risk: high-risk-write）还需要在执行前获得明确确认；普通写操作（risk: write）不需要额外确认：

• 渠道：engage-setting channel create（写操作）、engage-setting channel delete（高风险写操作）、engage-setting channel update-status（写操作）
• 配置渠道（配置中心渠道管理）：engage-scene config-channel create|update|update-status（写操作）、engage-scene config-channel delete（高风险写操作）
• 策略和配置项：engage-scene config-item delete（高风险写操作）、engage-scene template copy 和 engage-scene strategy manage（写操作）
• 流程：engage-flow flow update-remark（写操作）、engage-flow flow save（写操作）、engage-flow flow modify-base-info（写操作）、engage-flow flow manage（写操作）、engage-flow flow delete（高风险写操作）
• 任务：engage-task task save（写操作）、engage-task task submit-approval（写操作）、engage-task task manage（写操作）

创建或更新任务草稿时，请使用以下工作流：

1. ae-cli engage-setting channel list --project-id <projectId>
2. ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'
3. 对于自定义受众，将 Analysis 语义契约作为 targetConfig.definitionRequest 传入。对于事件触发型任务，使用语义字段 triggerConfig.triggerDefinition，并且 始终在其主要 A 规则中包含 periodTimeSymbol（TS01、TS02、TS03 或 TS04）。 使用语义字段 completionIndicatorDef.completionIndicators[].eventDefinition。 根据 ae-analysis 的用户分群／受众模型构建结构。对于现有分群受众 （targetClusterType=2），使用 analysis user-cluster get。对于事件触发型任务，将 channelType、triggerType 和 eventTriggerType 传入 build-save-guide，然后使用 与类型对应的语义事件结构。累计事件使用聚合条件，连续事件使用值至少为 2 的 count/eq，有序事件使用序列步骤封装， 每次完成事件使用 count/eq/1。完成目标和实验主目标事件筛选条件不得使用元数据 select_type 为 datetime 的属性。切勿构造持久化的 QP 字段。 根据投放侧选择受众：服务端渠道允许自定义（1）或现有（2）受众，且拒绝全体用户（3）；client_push（channelType=3）允许自定义（1）或全体用户（3）受众，且拒绝现有（2）受众。不要仅根据 triggerType 推断受众支持情况。
4. ae-cli engage-task task save --project-id <projectId> --req '{...}'

对于仅保存草稿的请求，保存并验证草稿后即停止。只有当用户意图中包含单独的审批操作时，才提交审批： ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>。

engage-task task build-save-guide 是只读辅助工具。它会返回特定场景所需的字段、渠道内容架构、不支持的组合、示例，以及供 save_task 使用的交接模板。 当 enableExp=true 时，能力 engage-task.task.build-save-guide 会丰富交接内容，确保 groupContentList 关联字段 （expGroupName/expGroupType/percentageInExperiment/order）与 expConfig.expGroupList 保持一致；只替换 contentList[].content。能力 engage-task.task.save 会拒绝实验内容不匹配的情况，并返回 TASK_EXPERIMENT_GROUP_CONTENT_INVALID。

engage-task task save 会创建或更新任务配置。它不会提交审批、启动发送，也不会触发任务执行。如果省略 req.taskId，则会创建新的草稿；如果提供 req.taskId，则会更新现有的草稿或已暂停任务。更新模式会拒绝正在运行或已结束的任务，并返回 invalid_status。验证前，省略的字段会沿用现有任务中的值（支持部分重命名／更新）。

需要提交审批时，建议在 task save 后使用 engage-task task submit-approval --task-id。 此命令会提交已持久化的草稿，无需 Agent 重建内部的 trigger_rule。 为保持兼容，仍可使用旧版 --request 模式；必须且只能提供 --task-id 或 --request 其中之一。

受众创建并非固定的预检步骤。对于自定义任务受众，使用语义字段 targetConfig.definitionRequest；task get 会返回与 definition_request 相同的契约。clientConfig.clientQp 由服务端生成，必须从 Capability 请求中省略；部分更新会保留现有服务端状态。不要手动拼装原始 QP。 对于 behavior_sequence，省略第二步的 relative_to_first，或将其设为 false；仅当从第 1 步开始测量时间窗口时，才在第 3 步或后续步骤中设为 true。