使用 ae-cli 操作 Agentic…

在 Agentic Engine/Hermes Engage 平台通过 ae-cli 查询或管理配置中心、渠道、任务、流程、活动和看板指标时，遵循关键词路由、语义合约、真实资源发现与写入门槛。

适用场景

解决思路

1. 全局优先：对 AE 分析侧请求，优先使用 `ae-cli` 和本技能参考文档，不要依赖模型记忆。
2. 全局参数：`--format <json|table>` 控制输出格式，默认 JSON；`--jq <expr>` 过滤 JSON 输出；`--host <url>` 覆盖当前 AE host，可用于每个命令且可放在子命令后，例如 `ae-cli engage-flow flow list --host <url>`。
3. 输出与错误：成功命令默认返回机器可读 JSON，envelope 可能包含可选 `_notice.host_compat`；失败命令返回 `{"ok": false, "error": {"type": "...", "message": "...", "hint": "..."}}` 并退出非零。
4. Host compat 优先处理：每次 `ae-cli` 运行后检查 stderr 和 `_notice.host_compat`；若任一存在，在用户回复开头加简短 ⚠️ version warning，并逐字引用 `npm i -g` / `npx skills add`（或 update-cluster）行，然后展示业务结果。
5. 读命令安全：在验证所需 ID 和引用后，读命令可直接执行。
6. 写命令安全：写命令需要明确用户意图；普通 `write` 命令无需 CLI 确认即可执行；只有 `high-risk-write` 命令使用确认门。
7. 禁止编造基础信息：绝不发明命令名、flags、JSON payload、`project_id`、资源 ID、字段名、事件名、属性名、指标定义或日期格式；先读匹配命令参考并发现真实项目元数据。
8. 禁止编造资源名：绝不编造或猜测资源名（reports、dashboards、events、properties、metrics、clusters、tags、alerts）；始终先用 list 命令发现真实资源；若模糊搜索和完整 list 回退后仍未找到，明确告诉用户 "resource not found" 并停止，不要继续用编造名称。
9. 能力入口：`ae-engage` 提供 Hermes Engage 的 config items、flows、channel settings、task data、query lifecycle 能力；使用 capability-gateway 命令 `ae-cli engage-flow|engage-task|engage-setting|engage-scene|engage-query <resource> <action>`；低频报告使用 L3 references。
10. 典型用例：查询和管理 channels、config channels、approvers、whitelists；查询项目 channel touch-limit 或 fatigue-control 规则；查询任务列表、任务详情、实验报告、指标报告；查询 config items 和 strategies，复制 templates，管理策略状态；查询 flow 列表、节点 schema、flow 报告，保存和管理 flows。
11. 关键词路由：当用户提到产品术语（包括常见中文 UI 标签）时，先打开列出的 reference，不要猜命令或 ID。
12. Config center 路由：产品含义为 Engage scene management / config center overview；CLI 域 `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`。
13. Scene config 路由：与 config center 相同；config item 下的 params、groups、metrics、channels、strategies、templates；CLI 域 `engage-scene`；主参考 `references/scene-config-item.md`；参数/分组/指标参考 `scene-config-param.md`、`scene-config-group.md`、`scene-preset-metric.md`、`scene-config-metric.md`。
14. Config item 路由：config center 中的单个 config item；CLI 域 `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`。
15. Push channel 路由：项目级消息推送渠道（Webhook、FCM、APNS 等）；CLI 域 `engage-setting`；主参考 `references/channel-list.md`；相关参考 `channel-detail.md`、`add-channel.md`、`update-channel-status.md`、`delete-channel.md`、`channel-update-config.md`、`channel-test-send.md`、`channel_touch_limits_list.md`；注意 Webhook 与 Client 不同：`url` = HTTP vs scene key；自定义参数 `user:` vs `user:`/`client:`。
16. Config channel 路由：配置中心 Webhook/client 配置渠道（不同于 push channels）；CLI 域 `engage-scene`；主参考 `references/scene-config-channel.md`；相关参考 `channel-mgmt.md`（create/enable-disable/copy/delete 工作流）；`config.customsParamList` 中用户参数要求 `columnName` 带 `user:` 前缀（例如 `user:#account_id`）；先用 ae-analysis `analysis-meta property list/get` 预检名称。
17. Operation strategy 路由：config item 下的 ops/delivery strategies；CLI 域 `engage-scene`；主参考 `references/scene-strategy.md`；自定义受众参考 `references/scene-strategy-audience.md`（语义 `definitionRequest`，Analysis condition shape）；不要传 `targetClusterQp`/`qp`；预检 props（缺失则停止并 list）；模板参考 `scene-template.md`。
18. Operation task 路由：Hermes push/engagement tasks（list、save、lifecycle、reports）；CLI 域 `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`。
19. Operation activity 路由：campaign activity 管理及按 activity、topic 或 standalone task 的投放趋势；CLI 域 `engage-activity`；主参考 `references/activity-activity.md`；相关参考 `activity-data-detail.md`、`activity-topic.md`、`activity-task.md`、`activity-approval.md`。
20. Template 路由：config item 下的 strategy templates；CLI 域 `engage-scene`；主参考 `references/scene-template.md`；相关参考 `scene-config-param.md`（template fields 引用 `paramId`）；在 strategy create 前先通过 `template update` 再 `template update-status` 启用。
21. 易混淆区分：Push channel 使用 `ae-cli engage-setting channel …`（Hermes push channel settings）；Config channel 使用 `ae-cli engage-scene config-channel …`（config-center channels；见 `channel-mgmt.md`）。
22. 易混淆边界：Flow / Task canvas nodes 使用来自 push channels 的 `channelId`；config items 绑定来自 config channels 的 `channel_id`。
23. 参数约定：简单参数用普通 flags，例如 `--project-id`、`--task-id`、`--flow-uuid`。
24. 参数约定：数组参数用 JSON flags，例如 `--strategy-uuid-list '["id1","id2"]'`。
25. 参数约定：对象参数用 named JSON flags，例如 `--req '{...}'`、`--flow-list '[...]'`。
26. 参数约定：可选全局参数与其它域相同，例如 `--host`、`--mcp-url`、`--dry-run`。
27. 命名边界：CLI flags 用 kebab-case；外层 Capability input 和所有 Capability response keys 用 snake_case。
28. 命名边界：通过 `--req` 或 `--payload` 传入的嵌套业务 DTO 保留文档原生 camelCase 字段；不要机械地把这些嵌套 DTO key 转成 snake_case。
29. 语义合约：audience、event、trigger、completion、metric definitions 是封闭合约；CLI 在本地拒绝 malformed 或 unknown semantic fields；`--validate` 应用相同精确 Hermes capability schema 但不写入。
30. 响应读取：成功迁移的命令在 `data` 下返回业务 payload；选择字段前读匹配 reference 的 Response shape。
31. JSON 参数示例：`--provider-list '["webhook","fcm"]'`；`--strategy-uuid-list '["strategy_a","strategy_b"]'`；`--flow-id-list '["flow_1","flow_2"]'`；`--req '{"pageNum":1,"pageSize":20}'`。
32. setting：查询 channel list：`ae-cli engage-setting channel list --project-id 1`。
33. setting：按 provider 过滤 channel：`ae-cli engage-setting channel list --project-id 1 --provider-list '["webhook","fcm"]'`。
34. setting：查询 config channels（config center channel management，使用 `engage-scene`，不要用 legacy `+config_channel_*`）：`ae-cli engage-scene config-channel list --project-id 1 --channel-type 0`。
35. setting：查询项目 channel touch-limit 规则：`ae-cli engage-setting channel-touch-limits list --project-id <project_id>`。
36. setting：更新 channel config / reach-funnel 设置：`ae-cli engage-setting channel update-config --project-id <project_id> --channel-id <channel_id> --enable-touch-event 1`。
37. setting：向 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"}]'`。
38. setting：批量更新/切换/保存 channel touch-limit（fatigue-control）规则：`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`。
39. setting：从项目移除 approver：`ae-cli engage-setting approval-approver delete --project-id <project_id> --approver <open_id> --yes`。
40. setting：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"]'`。
41. setting：push-language 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>`。
42. setting：client-param create/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>`。
43. setting：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`。
44. setting：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>'`。
45. setting：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`。
46. task：查询任务列表：`ae-cli engage-task task list --project-id 1 --req '{"pageNum":1,"pageSize":20}'`。
47. task：在组合最终 req 前构建 save_task 指南：`ae-cli engage-task task build-save-guide --project-id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'`。
48. task：保存任务草稿（req.taskId 省略时创建）：`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":[]}}}'`。
49. task：查询任务详情：`ae-cli engage-task task get --project-id 1 --task-id task_123`。
50. task：将已保存草稿提交审批：`ae-cli engage-task task submit-approval --project-id 1 --task-id task_123`。
51. task：通过 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`。
52. task：L3 任务报告在调用前读 `references/task-data-overview.md`、`references/task-data-detail.md`、`references/task-metric-detail.md` 或 `references/task-experiment-report.md`。
53. task：使用 `engage-task indicator-user` 前读 `references/task-indicator-user.md`；其 grouping、indicator、summary/detail、metric、experiment、timezone flags 有条件兼容规则。
54. config：查询 config item 列表：`ae-cli engage-scene config-item list --project-id 1`。
55. config：查询 strategy 列表：`ae-cli engage-scene strategy list --project-id 1 --config-id cfg_123`。
56. config：L3 config 报告在调用前读 `references/config-item-trigger-report.md`、`references/config-item-analysis-report.md` 或 `references/config-item-strategy-comparison.md`。
57. flow：查询 flow 列表：`ae-cli engage-flow flow list --project-id 1`。
58. flow：查询 flow 详情：`ae-cli engage-flow flow get --project-id 1 --flow-uuid flow_uuid_123`。
59. flow：查询 flow operation records 和 application logs：`ae-cli engage-flow operation-log query --project-id 1 --flow-id flow_id_123`。
60. flow：查询 flow versions 和 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`。
61. flow：查询 node schema：`ae-cli engage-flow node-config schema --project-id 1 --node-type message_push`；更新 flow metric：`ae-cli engage-flow metric update --project-id 1 --flow-id flow_id_123 --metric-map '<metric_map_json>'`。
62. flow：查询或导出 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`。
63. flow：User-detail `run` 命令用于 bounded inline rows，接受 `--request-id`、`--limit`、`--timeout-seconds`；metric-detail `run` 返回 report object。
64. flow：Export 命令接受 `--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` 取消运行中的 async work。
65. flow：对 flow report/user-detail 命令，在组合非平凡输入前读匹配 reference：flow canvas custom metric configuration 读 `references/flow-metric-update.md`；metric-detail report object 或 flattened report export 读 `references/flow-metric-detail-report.md`；process-level metric segment 背后的 users 读 `references/flow-metric-user.md`；node-level data segment 背后的 users 读 `references/flow-node-user.md`；node-level metric segment 背后的 users 读 `references/flow-node-metric-user.md`。
66. scene：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`。
67. scene：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`。
68. scene：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`。
69. scene：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>'`。
70. scene：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`。
71. scene：config-channel list/get/create/update/update-status/delete/query-log：`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>`。
72. scene：config-channel 用户参数先通过 `ae-analysis property list/get` 验证每个 `customsParamList` 的 `columnName`，然后使用 `user:<prop_name>`；strategy custom audience 读 `scene-strategy-audience.md`，使用语义 `definitionRequest`；strategy predict 用于预估人数；workflows 读 `references/channel-mgmt.md`，schema 读 `references/scene-config-channel.md`。
73. scene：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"]'`。
74. scene：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`。
75. activity：生成任何 activity topic 或 standalone-task payload 前，遵循 Hermes activity UI 暴露的子集。
76. activity：`triggerType` 必须为 `0`（schedule single）或 `1`（schedule repeat）；activity tasks 不支持 manual（`2`）或 triggered（`3`-`6`）任务类型。
77. activity：不要配置 A/B 或 horse-race experiments；省略 `expConfig` 或仅用 `{"enableExp":false}`，并提供恰好一个 non-experiment `groupContentList` group。
78. activity：standalone activity tasks 必须使用 `triggerTimeStrategy: "fixed_time_zone"` 和父 activity 的 `tzOffset`；schedule times 必须位于 activity period 内。
79. activity：topic root 支持 audience types `1`（custom）和 `2`（existing cluster），不支持 `3`（all users）；standalone activity task 可使用 `1`、`2` 或 `3`。
80. activity：topic tasks 从 topic 继承 schedule、timezone、channel、frequency limits、channel touch limits、whitelist 和 experiment settings；它们只能添加 inclusion-only custom `definitionRequest`；绝不生成 task-level `clusterKey`、trigger rules 或 shared-setting overrides。
81. activity：`topic get` 可能返回 canonical task marker `targetClusterType=1`；若存在，更新时保留；但绝不使用其他 task-level 值。
82. activity：先解析父 activity 并确认其可编辑（`mappingStatus` 为 `0`、`2` 或 `5`）；topics、tasks、languages 的限制是项目配置值，不要硬编码默认值。
83. activity：`approval submit` 和 `approval approve` 会验证每个已持久化的 activity task；approval 不会规范化不支持的任务数据；遇到 `ACTIVITY_TASK_COMPATIBILITY_VIOLATION` 时，按需取消/撤回 approval，修正或重建每个被报告的任务，然后重新提交。
84. activity：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>`。
85. activity：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>`。
86. activity：topic create/update/remove-task/delete/get/copy：`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>]`；topicClusterKey vs task clusterKey 和 triggerType 说明见 `references/activity-topic.md`。
87. activity：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`。
88. activity：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>]`。
89. workbench：workbench 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`。
90. workbench：每个用户每个项目最多配置 4 个 metric cards；slots 是按用户的；`update`/`delete` 只影响调用者自己的 slots；第一次 `list` 自动初始化 4 个默认 slots。
91. flow save：当用户想“创建 flow / 生成 flow canvas / 保存 flow”时，不要把 `engage-flow flow save` 当作普通单命令；必须遵循下述工作流。
92. flow save：首先确认用户意图足够具体；至少需要 business scenario、target users、touchpoint 或 delivery method、是否需要 branching 及 branching conditions。
93. flow save：不要从自然语言直接跳到 `--req`；必须先组织稳定的 intermediate intent structure，再映射到最终 `req`。
94. flow save：用语义 `targetDefinitionRequest` 和 `triggerDefinition` 对象构建条件相关节点；通过 Analysis metadata 解析真实 event 和 property names；不要仅为了获得 persisted QP 而创建 intermediate cluster。
95. flow save：在构建 `message_push`、`wechat_push`、`webhook_push` 等 touchpoint nodes 前，必须调用 `ae-cli engage-setting channel list --project-id <projectId>`。
96. flow save：`engage-flow flow save` 是基于 operation 的（protocol v2）；`--req` 对象必须携带 `operation` 为 `build`、`preview` 或 `commit`；不要用旧 `nodeList` / `edgeList` 字段名；使用 `nodes` / `edges` 且 `operation=build`；legacy `nodeList`/`edgeList` payload 或缺失 `operation` 会被拒绝并报 `Unsupported save_flow operation: null`。
97. flow save：按生命周期执行 `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。
98. flow save：`nodes[].config` / `edges[].config` 可以是 JSON object 或 JSON string；custom audience nodes 和 branches 使用语义 `targetDefinitionRequest`；Hermes 会将其编译为节点存储的执行格式；绝不发送 `targetClusterQp`；每个 audience `event` 和 `behavior_sequence` 必须包含自己的 `time_range`；Flow entry dates 不会替代该 range；只使用通过 Flow editor 当前 project、timezone 和 user-entity metadata scope 解析出的 properties。
99. flow save：在 preview/commit 前自检：恰好一个 entry node；至少一个 `exit_flow`；`edge.source` 和 `edge.target` 都引用有效 nodes；任何 branch node 的 `sourceBranchId` 已在上游 node `config` 中声明；整个 graph 是 DAG 且无 cycles。
100. flow save：明确禁止：不要发明 `channelId`；用户未提供足够信息时不要填入 branching logic；不要把 business-semantic nodes 直接作为最终 `nodes` 提交；不要使用 legacy `nodeList` / `edgeList`，也不要省略 `operation`。
101. flow save：推荐顺序：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）。
102. flow save：更详细生成规则先查阅 `references/save-flow.md`、`references/flow-node-config-schema.md`、`references/validate-flow-node-config.md`。
103. dry-run 调试：`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 '{...}'`；`ae-cli --dry-run engage-flow flow list --project-id 1`。
104. references：更详细的单命令指导位于业务导向的 `references/` 目录；使用前按命令域查阅匹配文件，例如 channel、task、flow、scene、activity、workbench、query、report 等 reference。
105. 命令组：setting 包含 `channel-touch-limits list/batch-update/toggle/save`、`channel update-config/test-send/list/get/create/update-status/delete`、`approval-approver add/list/delete`、`whitelist list/add/update/delete/verify`、`push-language get/set`、`client-param create/update/delete/list`、`config-table upload/save/list/query-data/update-data/delete`、`preset-event list/update`、`common-metric list/get/create/update/delete`（通过 `engage-setting`），以及 L3 `engage-setting.query.cancel`。
106. 命令组：task 包含 `operation-log query`、`push-record query`、`user-detail export`、`indicator-user sql/run/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}`。
107. 命令组：query 包含 `run inspect`、`artifact download`、`query cancel`（通过 `engage-query`），capability ID `engage-query.query.cancel`。
108. 命令组：config 的 legacy config MCP 命令已迁移到 `scene` L2 group 和下面三个 L3 report capabilities。
109. 命令组：scene 包含 config-item、config-param、config-group、preset-metric、config-metric、config-channel、strategy、template 各命令（通过 `engage-scene`），以及 L3 `engage-scene.report.{config-item-trigger,config-item-analysis,strategy-comparison}`。
110. 命令组：activity 包含 activity、approval、topic、activity-type、task 各命令（通过 `engage-activity`）。
111. 命令组：workbench 包含 `workbench list/add/update/delete`（通过 `engage-workbench`）。
112. 命令组：flow 包含 `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/export`、`metric-user run/export`、`node-user run/export`、`node-metric-user run/export`（通过 `engage-flow`），以及 L3 `engage-flow.report.{node-overview,process,node-detail,ab-split-node}`。
113. 日期格式：接受日期参数的命令通常使用 `yyyy-MM-dd`，例如 `--start_time 2026-04-01`。
114. 写操作提醒：高风险删除命令（`risk: high-risk-write`）执行前需要明确用户授权；普通写命令（`risk: write`）不需要。
115. 写操作风险列表：Channels 中 `engage-setting channel create`（write）、`engage-setting channel delete`（high-risk-write）、`engage-setting channel update-status`（write）。
116. 写操作风险列表：Config channels 中 `engage-scene config-channel create|update|update-status`（write）、`engage-scene config-channel delete`（high-risk-write）。
117. 写操作风险列表：Strategies 和 config items 中 `engage-scene config-item delete`（high-risk-write）、`engage-scene template copy` 和 `engage-scene strategy manage`（write）。
118. 写操作风险列表：Flows 中 `engage-flow flow update-remark`（write）、`engage-flow flow save`（write）、`engage-flow flow modify-base-info`（write）、`engage-flow flow manage`（write）、`engage-flow flow delete`（high-risk-write）。
119. 写操作风险列表：Tasks 中 `engage-task task save`（write）、`engage-task task submit-approval`（write）、`engage-task task manage`（write）。
120. 任务草稿创建或更新工作流：1）`ae-cli engage-setting channel list --project-id <projectId>`；2）`ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'`。
121. 任务草稿工作流：自定义受众把 Analysis semantic contract 作为 `targetConfig.definitionRequest` 传入。
122. 任务草稿工作流：事件触发任务使用语义 `triggerConfig.triggerDefinition`，并始终在其 primary A rule 上包含 `periodTimeSymbol`（`TS01`、`TS02`、`TS03` 或 `TS04`）。
123. 任务草稿工作流：使用语义 `completionIndicatorDef.completionIndicators[].eventDefinition`；从 `ae-analysis` user-cluster / audience models 构建 shape。
124. 任务草稿工作流：已有 cluster 受众（`targetClusterType=2`）使用 `analysis user-cluster get`。
125. 任务草稿工作流：事件触发任务把 `channelType`、`triggerType`、`eventTriggerType` 传给 `build-save-guide`，然后使用其 type-specific semantic event shape。
126. 任务草稿工作流：accumulated events 是 aggregate conditions；continuous events 使用 count/eq 且 value 至少 2；ordered events 使用 sequence-step envelopes；every-completion events 使用 count/eq/1。
127. 任务草稿工作流：completion target 和 experiment main-goal event filters 不得使用 metadata `select_type` 为 `datetime` 的 properties；绝不构造 persisted QP fields。
128. 任务草稿工作流：按 delivery side 选择 audience：server-side channels 允许 custom（`1`）或 existing（`2`），拒绝 all users（`3`）；`client_push`（`channelType=3`）允许 custom（`1`）或 all users（`3`），拒绝 existing（`2`）；不要仅从 `triggerType` 推断 audience support。
129. 任务草稿工作流：3）`ae-cli engage-task task save --project-id <projectId> --req '{...}'`；4）`ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>`。
130. `engage-task task build-save-guide` 是只读 helper；返回 scenario-specific required fields、channel content schema、unsupported combinations、examples 和给 `save_task` 的 handoff template。
131. 当 `enableExp=true` 时，capability `engage-task.task.build-save-guide` 会丰富 handoff，使 `groupContentList` 关联字段（`expGroupName`/`expGroupType`/`percentageInExperiment`/`order`）与 `expConfig.expGroupList` 保持一致；只替换 `contentList[].content`。
132. capability `engage-task.task.save` 会用 `TASK_EXPERIMENT_GROUP_CONTENT_INVALID` 拒绝错位的 experiment content。
133. `engage-task task save` 创建或更新任务配置；不提交审批、不开始发送、不触发任务执行。
134. `engage-task task save`：若省略 `req.taskId` 则创建新草稿；若存在 `req.taskId` 则更新已有 draft 或 paused task；update mode 用 `invalid_status` 拒绝 running/ended tasks；省略字段在验证前继承自现有任务（支持 partial rename/update）。
135. `engage-task task submit-approval --task-id` 是 `task save` 后推荐的 approval path；它提交已持久化草稿，无需 Agent 重建内部 `trigger_rule`；legacy `--request` 模式仍兼容；必须恰好提供 `--task-id` 或 `--request` 之一。
136. 受众创建不是固定 preflight 步骤；自定义任务受众使用语义 `targetConfig.definitionRequest`；`task get` 返回与 `definition_request` 相同的 contract。
137. `clientConfig.clientQp` 是服务端生成的，必须在 Capability requests 中省略；partial updates 会保留现有服务端状态；不要手工组装 raw QP。
138. 对于 `behavior_sequence`，省略第二步 `relative_to_first` 或设为 `false`；仅在第 3 步或更晚且窗口从第 1 步度量时保留 `true`。

适用边界 · 注意事项

• 没有安装或无法使用 `ae-cli`、没有 Agentic Engine/Hermes Engage 平台访问权限时，不适用。
• 请求不涉及 Engage 配置中心、渠道、任务、流程、活动、模板或看板指标，且不需要 AE 平台元数据/语义合约时，不适用。
• 无法确认 `project_id`、资源 ID、真实 event/property/metric 名称且不能先通过 list/metadata 查询发现时，不适用。