@thinkingai/ae-cli 6.0.40 → 6.0.41

package/skills/ae-engage/references/build-task-save-guide.md

@@ -224,6 +224,12 @@ Use it to understand what must appear in:
 - `controlConfig`
 - `expConfig` when experiment mode is enabled
 
+When experiment mode is enabled (`context.enableExp=true` or draft `expConfig.enableExp=true`):
+
+- capability `engage-task.task.build-save-guide` enriches `handoff.reqTemplate.channelConfig.groupContentList`
+  so each entry carries `expGroupName`, `expGroupType`, `percentageInExperiment`, `order`, and `contentList`
+- do not drop those association fields when filling content; they must stay aligned with `expConfig.expGroupList`
+
 ### 4.8 `fieldRules`
 
 This is the most important construction section.
@@ -274,6 +280,10 @@ The guide treats the A rule as a discriminated envelope:
 - `eventTriggerType=2`: at least two ordered steps with `eventDefinition` and `hasDone`
 - `eventTriggerType=3`: client-side count/eq/1 events with `eventTriggerCaliberType`
 
+Every event-triggered task A rule must include `periodTimeSymbol`. Use `TS01` for daily,
+`TS02` for the complete configured period, `TS03` for weekly, or `TS04` for monthly.
+Do not omit this field even when `periodStart` and `periodEnd` are present.
+
 Do not copy the accumulated example and only change `eventTriggerType`. Hermes rejects a final QP
 whose event structure does not match its envelope.
 
@@ -299,6 +309,8 @@ Important fields:
 - `reqTemplate`
   - a scenario-aware grouped request template
   - use it as a starting point, not as unquestioned final truth
+  - for experiment tasks, keep `groupContentList` association fields from the template;
+    only replace `contentList[].content` with real channel content
 - `readyToSubmit`
   - `true` means the current scenario or draft has no blocking placeholders
 - `blockingPlaceholders`

package/skills/ae-engage/references/cancel-query-run.md

@@ -0,0 +1,31 @@
+# Cancel a running Engage query or export
+
+Cancel asynchronous Engage work by the Capability Gateway run ID.
+
+Mapped command:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+Mapped capability: `engage-query.query.cancel`
+
+## Input
+
+| Field | Type | Required | Description |
+|------|------|------|------|
+| `run_id` | string | Yes | Run ID returned by an asynchronous query or export capability |
+| `reason` | string | No | Optional cancellation reason |
+
+## Safety Constraints
+
+This command is a **write operation**. Use only the `run_id` returned by the asynchronous
+query/export lifecycle; a report `request_id` is not accepted.
+
+## Example
+
+```bash
+ae-cli engage-query query cancel \
+  --run-id run_123 \
+  --reason "No longer needed"
+```

package/skills/ae-engage/references/config-item-analysis-report.md

@@ -8,7 +8,20 @@ Required input: `project_id`, `config_id`, `start_time`, `end_time`. Optional in
 `template_id_list`, `strategy_id_list`, `show_time_zone`. `template_id_list` and `strategy_id_list`
 are mutually exclusive.
 
+## Input contract
+
+| Field | JSON type | Required | Rules |
+| --- | --- | --- | --- |
+| `project_id` | integer | Yes | Positive project ID. |
+| `config_id` | string | Yes | Config item ID. |
+| `start_time` | string | Yes | Date in `yyyy-MM-dd` format. |
+| `end_time` | string | Yes | Date in `yyyy-MM-dd` format; must not be earlier than `start_time`. |
+| `request_id` | string | No | Request identifier for continuation or cancellation. |
+| `template_id_list` | array of strings | No | Cannot be used together with `strategy_id_list`. |
+| `strategy_id_list` | array of strings | No | Cannot be used together with `template_id_list`. |
+| `show_time_zone` | number | No | Hour offset from `-12.0` through `14.0`; use `8`, not the string `"8"`. |
+
 ```bash
 ae-cli capability run engage-scene.report.config-item-analysis \
-  --input '{"project_id":1,"config_id":"cfg_123","start_time":"2026-04-01","end_time":"2026-04-07"}'
+  --input '{"project_id":1,"config_id":"cfg_123","start_time":"2026-04-01","end_time":"2026-04-07","show_time_zone":8}'
 ```

package/skills/ae-engage/references/config-item-strategy-comparison.md

@@ -7,7 +7,17 @@ Mapped command: `ae-cli capability run engage-scene.report.strategy-comparison -
 Required input: `project_id`, `config_id`, `strategy_id_list` with at least two IDs. Optional input:
 `request_id`, `show_time_zone`.
 
+## Input contract
+
+| Field | JSON type | Required | Rules |
+| --- | --- | --- | --- |
+| `project_id` | integer | Yes | Positive project ID. |
+| `config_id` | string | Yes | Config item ID. |
+| `strategy_id_list` | array of strings | Yes | Must contain at least two strategy IDs. |
+| `request_id` | string | No | Request identifier for continuation or cancellation. |
+| `show_time_zone` | number | No | Hour offset from `-12.0` through `14.0`; use `8`, not the string `"8"`. |
+
 ```bash
 ae-cli capability run engage-scene.report.strategy-comparison \
-  --input '{"project_id":1,"config_id":"cfg_123","strategy_id_list":["strategy_a","strategy_b"]}'
+  --input '{"project_id":1,"config_id":"cfg_123","strategy_id_list":["strategy_a","strategy_b"],"show_time_zone":8}'
 ```

package/skills/ae-engage/references/config-item-trigger-report.md

@@ -8,7 +8,21 @@ Required input: `project_id`, `config_id`, `start_time`, `end_time`. Optional in
 `template_id_list`, `strategy_id_list`, `show_time_zone`, `analyze_report_internal_query`.
 `template_id_list` and `strategy_id_list` are mutually exclusive.
 
+## Input contract
+
+| Field | JSON type | Required | Rules |
+| --- | --- | --- | --- |
+| `project_id` | integer | Yes | Positive project ID. |
+| `config_id` | string | Yes | Config item ID. |
+| `start_time` | string | Yes | Date in `yyyy-MM-dd` format. |
+| `end_time` | string | Yes | Date in `yyyy-MM-dd` format; must not be earlier than `start_time`. |
+| `request_id` | string | No | Request identifier for continuation or cancellation. |
+| `template_id_list` | array of strings | No | Cannot be used together with `strategy_id_list`. |
+| `strategy_id_list` | array of strings | No | Cannot be used together with `template_id_list`. |
+| `show_time_zone` | number | No | Hour offset from `-12.0` through `14.0`; use `8`, not the string `"8"`. |
+| `analyze_report_internal_query` | boolean | No | Use `true` or `false`, not a quoted string. |
+
 ```bash
 ae-cli capability run engage-scene.report.config-item-trigger \
-  --input '{"project_id":1,"config_id":"cfg_123","start_time":"2026-04-01","end_time":"2026-04-07"}'
+  --input '{"project_id":1,"config_id":"cfg_123","start_time":"2026-04-01","end_time":"2026-04-07","show_time_zone":8}'
 ```

package/skills/ae-engage/references/flow-metric-detail-report.md

@@ -0,0 +1,134 @@
+# Flow metric-detail report
+
+Use this reference when the user asks for a flow node metric-detail report, or wants to export the detailed metric table behind a node on the flow canvas.
+
+Mapped CLI commands:
+
+- `ae-cli engage-flow report metric-detail run`
+- `ae-cli engage-flow report metric-detail export`
+
+Mapped capabilities:
+
+- `engage-flow.report.metric-detail.run`
+- `engage-flow.report.metric-detail.export`
+
+## Choose the command
+
+- Use `run` for quick inline inspection. It returns the original Hermes report object under `report`.
+- Use `export` when the user needs a downloadable, flattened artifact.
+- Use `--report-mode node` or omit it for normal nodes.
+- Use `--report-mode ab` for AB split node metric details.
+
+Do not use the older generic capability form unless the structured command is unavailable.
+
+## Required input
+
+- `--project-id`
+- one of `--flow-id` or `--flow-uuid`
+- `--node-uuid`
+- `--start-time yyyy-MM-dd`
+- `--end-time yyyy-MM-dd`
+
+## Optional input
+
+- `--report-mode node|ab` (default: `node`)
+- `--branch-id`
+- `--indicator-name` for normal node metric selection
+- `--indicators-uuid` for AB metric selection
+- `--data-dim-type uv|pv`
+- `--push-language-code`
+- `--show-time-zone`
+- `--request-id`
+- `--timeout-seconds`
+- `run` only: `--limit` is accepted for command consistency, but metric-detail reports are not row-limited by Hermes
+- `export` only: `--artifact-format csv|jsonl` (default: `jsonl`)
+
+## Parameter guidance
+
+- Prefer `flow_uuid` when the user is talking about a specific flow version; prefer `flow_id` when they mean the current logical flow.
+- `node_uuid` must be the canvas node UUID, not the node type.
+- Dates are inclusive report dates and must be in `yyyy-MM-dd`.
+- For AB mode, pass the AB node UUID and usually `--indicators-uuid`; `--branch-id` is optional and only use it when the selected report cell is branch-specific.
+- If both `flow-id` and `flow-uuid` are supplied, Hermes checks they match.
+
+## Examples
+
+Inline normal node metric detail:
+
+```bash
+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 \
+  --timeout-seconds 120
+```
+
+Export normal node metric detail as CSV:
+
+```bash
+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
+```
+
+Inline AB node metric detail:
+
+```bash
+ae-cli engage-flow report metric-detail run \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid ab_node_uuid_123 \
+  --report-mode ab \
+  --indicators-uuid indicator_uuid_123 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07
+```
+
+## Export lifecycle
+
+`export` returns `run_id` and `artifact_id`. Poll and download with:
+
+```bash
+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 ./flow-metric-detail.csv.gz
+```
+
+Downloaded artifacts are gzip-compressed; keep the `.gz` suffix. Cancel running async work with:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+## Output rows
+
+Normal node export rows:
+
+- `time`
+- `indicator`
+- `value_index`
+- `value`
+
+AB node export rows:
+
+- `time`
+- `branch_id`
+- `branch_name`
+- `indicator`
+- `value`
+- `total`
+
+## Common mistakes
+
+- Do not pass `report-mode ab` for a normal node; Hermes will call the AB report backend.
+- Do not use `indicator_name` and `indicators_uuid` interchangeably: normal node uses `indicator_name`, AB mode usually uses `indicators_uuid`.
+- Do not save a gzip artifact as `.csv` or `.jsonl`; use `.csv.gz` or `.jsonl.gz`.

package/skills/ae-engage/references/flow-metric-update.md

@@ -0,0 +1,77 @@
+# Flow metric update
+
+Use this reference when the user asks to configure, replace, or save effect metric settings for a flow canvas.
+
+Mapped CLI command:
+
+- `ae-cli engage-flow metric update`
+
+Mapped capability:
+
+- `engage-flow.metric.update`
+
+## Safety
+
+This is a write command. Only run it when the user explicitly asks to change a flow's metric configuration. Use `--dry-run` first when the final `metric_map` was assembled by an agent.
+
+The backend uses a clean-and-insert update model: omitted existing metric settings may be deleted. Treat `metric_map` as the complete desired metric configuration for the flow, not a partial patch.
+
+## Required input
+
+- `--project-id`
+- `--flow-id`
+- `--metric-map '<metric_map_json>'`
+
+## Parameter guidance
+
+- `flow_id` is the logical flow ID used by the flow canvas APIs.
+- `metric_map` is a JSON object keyed by metric target-user group. Valid first-level keys are exactly:
+  - `trigger`
+  - `view`
+  - `click`
+  - `ab_test`
+- Preserve first-level group keys exactly. Do not convert `ab_test` to `abTest`.
+- Each group value is an array of Hermes metric DTO objects.
+- Use DTO field names from `HermesMetricReqDTO`: `metricSettingId`, `metricType`, `metricName`, `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, `displayName`, `orderId`, `note`, and `metricParams`.
+- The CLI boundary accepts snake_case nested DTO fields too, but prefer the native camelCase names above in examples and generated payloads.
+- For existing bindings, include `metricSettingId` so Hermes updates that binding instead of treating it as a new binding.
+- For preset metrics, use `metricType: 1` and a real `metricName` discovered from `engage-setting common-metric list/get`.
+- For custom metrics, use `metricType: 2` plus a complete `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, and `displayName`; Hermes creates the custom metric name.
+- Do not invent metric names, event names, property names, QP structures, or metric-setting IDs. Read the existing flow detail and available metric definitions first, then update the complete desired metric map.
+
+## Examples
+
+Dry-run updating an existing binding:
+
+```bash
+ae-cli --dry-run engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"trigger":[{"metricSettingId":"setting_1","metricType":1,"metricName":"purchase_count","displayName":"Purchase count","orderId":1}]}'
+```
+
+Apply the same update:
+
+```bash
+ae-cli engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"trigger":[{"metricSettingId":"setting_1","metricType":1,"metricName":"purchase_count","displayName":"Purchase count","orderId":1}]}'
+```
+
+Add a custom metric to the `view` group:
+
+```bash
+ae-cli engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"view":[{"metricType":2,"metricQp":"{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}","metricWindowNum":1,"metricWindowTimeUnit":"day","displayName":"Purchase after view","orderId":1}]}'
+```
+
+## Common mistakes
+
+- Do not pass `flow_uuid`; this command requires `flow_id`.
+- Do not pass `metricId`; `HermesMetricReqDTO` has no `metricId` field. Use `metricSettingId` for an existing binding or `metricName` for a preset metric.
+- Do not use arbitrary first-level keys such as `custom`, `ACTION`, or `channel`; use only `trigger`, `view`, `click`, or `ab_test`.
+- Do not submit only the group you want to change unless deleting omitted groups is intended.
+- Do not use this command to query report data. For report metric details, use `references/flow-metric-detail-report.md`.

package/skills/ae-engage/references/flow-metric-user.md

@@ -0,0 +1,118 @@
+# Flow metric-user
+
+Use this reference when the user asks for users behind a process-level flow metric segment, such as a cell in the flow process report.
+
+Mapped CLI commands:
+
+- `ae-cli engage-flow metric-user run`
+- `ae-cli engage-flow metric-user export`
+
+Mapped capabilities:
+
+- `engage-flow.metric-user.run`
+- `engage-flow.metric-user.export`
+
+Hermes SQL source: `FlowReportDataService#buildClusterUserSql`.
+
+## Choose the command
+
+- Use `run` for a bounded inline preview of matched users.
+- Use `export` for the full user-detail artifact.
+- This command does not require `--node-uuid`; use `node-user` or `node-metric-user` for node-level cells.
+
+## Required input
+
+- `--project-id`
+- one of `--flow-id` or `--flow-uuid`
+- either `--cluster-def '<cluster_def_json>'` or all of `--indicator-name`, `--start-time`, and `--end-time`
+
+## Optional input
+
+- `--branch-id`
+- `--request-id`
+- `--data-view-type` (default: `2`)
+- `--is-summary`
+- `--push-language-code`
+- `--user-time-zone`
+- `--show-time-zone`
+- `run` only: `--limit`
+- `export` only: `--artifact-format csv|jsonl` (default: `jsonl`)
+- `--timeout-seconds`
+
+Only pass fields listed above. Hermes rejects extra top-level fields for this capability.
+
+## Segment selector contract
+
+Prefer the explicit report fields. Set `--indicator-name` to the metric key returned by the process report and reuse the report date range. Hermes builds the internal cluster definition.
+
+`--cluster-def` remains available for compatibility. When used, it must come from the selected report segment; do not invent or hand-minify partial JSON.
+
+Required keys:
+
+- `indicatorName`
+- `dataViewType`
+- `isSummary`
+
+Date keys depend on `isSummary`:
+
+- `isSummary=true`: require `filterStartDate` and `filterEndDate`
+- `isSummary=false`: require `startDate` and `endDate`
+
+Dates must use `yyyy-MM-dd`, and start must be earlier than or equal to end.
+
+## Examples
+
+Inline preview:
+
+```bash
+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
+```
+
+Export all matched users:
+
+```bash
+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
+```
+
+## Export lifecycle
+
+`export` returns `run_id` and `artifact_id`. Poll and download with:
+
+```bash
+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 ./flow-metric-users.csv.gz
+```
+
+Downloaded artifacts are gzip-compressed; keep the `.gz` suffix. Cancel running async work with:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+## Output shape
+
+- `run` returns `rows`, `total`, and `column_meta`.
+- `export` writes one row per matched user. The primary column is usually `#user_id`.
+
+## Common mistakes
+
+- Do not pass `--node-uuid` unless the process-level report segment actually needs branch/node context; for normal node cells use `node-user`.
+- Use `--data-view-type`, not the report-only `--data-dim-type`, when selecting users without `--cluster-def`.
+- If `cluster_def` is missing the date pair implied by `isSummary`, Hermes rejects it before SQL execution.

package/skills/ae-engage/references/flow-node-metric-user.md

@@ -0,0 +1,122 @@
+# Flow node-metric-user
+
+Use this reference when the user asks for users behind a node-level metric segment on the flow canvas.
+
+Mapped CLI commands:
+
+- `ae-cli engage-flow node-metric-user run`
+- `ae-cli engage-flow node-metric-user export`
+
+Mapped capabilities:
+
+- `engage-flow.node-metric-user.run`
+- `engage-flow.node-metric-user.export`
+
+Hermes SQL source: `FlowNodeReportDataService#buildMetricClusterUserSql`.
+
+## Choose the command
+
+- Use `run` for a bounded inline preview of users behind the selected node metric segment.
+- Use `export` for the full user-detail artifact.
+- Use `node-user` for node data segments that are not metric-detail segments.
+- Use `metric-user` for process-level flow metric cells.
+
+## Required input
+
+- `--project-id`
+- one of `--flow-id` or `--flow-uuid`
+- `--node-uuid`
+- either `--cluster-def '<cluster_def_json>'` or all of `--indicator-name`, `--start-time`, and `--end-time`
+
+## Optional input
+
+- `--branch-id`
+- `--request-id`
+- `--data-view-type` (default: `2`)
+- `--is-summary`
+- `--push-language-code`
+- `--user-time-zone`
+- `--show-time-zone`
+- `run` only: `--limit`
+- `export` only: `--artifact-format csv|jsonl` (default: `jsonl`)
+- `--timeout-seconds`
+
+Only pass fields listed above. Hermes rejects extra top-level fields for this capability.
+
+## Segment selector contract
+
+Prefer the explicit report fields. Set `--indicator-name` to the metric key returned by the node metric report and reuse the report date range. Hermes builds the internal cluster definition.
+
+`--cluster-def` remains available for compatibility. When used, it must come from the selected node metric report segment; do not invent it.
+
+Required keys:
+
+- `indicatorName`
+- `dataViewType`
+- `isSummary`
+
+Date keys depend on `isSummary`:
+
+- `isSummary=true`: require `filterStartDate` and `filterEndDate`
+- `isSummary=false`: require `startDate` and `endDate`
+
+Dates must use `yyyy-MM-dd`, and start must be earlier than or equal to end.
+
+## Examples
+
+Inline preview:
+
+```bash
+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
+```
+
+Export all matched users:
+
+```bash
+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
+```
+
+## Export lifecycle
+
+`export` returns `run_id` and `artifact_id`. Poll and download with:
+
+```bash
+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 ./flow-node-metric-users.csv.gz
+```
+
+Downloaded artifacts are gzip-compressed; keep the `.gz` suffix. Cancel running async work with:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+## Output shape
+
+- `run` returns `rows`, `total`, and `column_meta`.
+- `export` writes one row per matched user. The primary column is usually `#user_id`.
+
+## Common mistakes
+
+- `--node-uuid` is required and must be the canvas node UUID.
+- Do not use this for node data cells; use `node-user` so Hermes routes to the non-metric SQL builder.
+- Use `--data-view-type`, not the report-only `--data-dim-type`, when selecting users without `--cluster-def`.