@thinkingai/ae-cli 6.0.39 → 6.0.40

package/dist/{te-engage-F7V55KVW.js → te-engage-QWM4GFS7.js}

@@ -209,6 +209,362 @@ var flowModifyBaseInfo = createEngageFlowCapabilityCommand({
   })
 });
 
+// src/commands/te-engage/semantic-qp-validation.ts
+var OPERATORS = /* @__PURE__ */ new Set([
+  "eq",
+  "neq",
+  "lt",
+  "lte",
+  "gt",
+  "gte",
+  "exists",
+  "not_exists",
+  "between",
+  "contains",
+  "not_contains",
+  "is_true",
+  "is_false",
+  "regex",
+  "not_regex",
+  "relative_current_time",
+  "relative_event_time",
+  "array_contains",
+  "in_cluster",
+  "not_in_cluster"
+]);
+var AUDIENCE_AGGREGATIONS = /* @__PURE__ */ new Set([
+  "count",
+  "active_days",
+  "sum",
+  "avg",
+  "max",
+  "min",
+  "distinct_count"
+]);
+var METRIC_AGGREGATIONS = /* @__PURE__ */ new Set([
+  "total_count",
+  "user_count",
+  "per_user_count",
+  "sum",
+  "avg",
+  "avg_per_user",
+  "max",
+  "min",
+  "distinct_count",
+  "median",
+  "percentile",
+  "variance",
+  "stddev"
+]);
+function validateSemanticAudienceDefinition(value, path) {
+  const definition = object(value, path);
+  rejectUnknown(definition, ["type", "conditions", "include_filter", "exclude_filter"], path);
+  exactString(definition.type, "condition", `${path}.type`);
+  validateGroup(definition.conditions, `${path}.conditions`);
+  optional(definition.include_filter, (item) => validateGroup(item, `${path}.include_filter`));
+  optional(definition.exclude_filter, (item) => validateGroup(item, `${path}.exclude_filter`));
+}
+function validateSemanticEventDefinition(value, path) {
+  const event = object(value, path);
+  rejectUnknown(event, [
+    "type",
+    "event",
+    "operator",
+    "value",
+    "aggregation",
+    "property",
+    "time_range",
+    "filters"
+  ], path);
+  exactString(event.type, "event", `${path}.type`);
+  nonBlankString(event.event, `${path}.event`);
+  optionalEnum(event.operator, OPERATORS, `${path}.operator`);
+  optionalNumber(event.value, `${path}.value`);
+  optionalEnum(event.aggregation, AUDIENCE_AGGREGATIONS, `${path}.aggregation`);
+  optionalString(event.property, `${path}.property`);
+  optional(event.time_range, (item) => validateTimeRange(item, `${path}.time_range`));
+  optional(event.filters, (item) => validateFilterGroup(item, `${path}.filters`));
+}
+function validateSemanticMetricDefinition(value, path) {
+  const metric = object(value, path);
+  if (metric.type === "event") {
+    validateMetricEvent(metric, path, false);
+    return;
+  }
+  if (metric.type === "formula") {
+    rejectUnknown(metric, ["type", "expression", "dependencies", "format"], path);
+    nonBlankString(metric.expression, `${path}.expression`);
+    optionalString(metric.format, `${path}.format`);
+    array(metric.dependencies, `${path}.dependencies`, 1).forEach((dependency, index) => validateMetricEvent(
+      object(dependency, `${path}.dependencies[${index}]`),
+      `${path}.dependencies[${index}]`,
+      true
+    ));
+    return;
+  }
+  invalid(`${path}.type must be event or formula.`);
+}
+function validateEmbeddedSemanticDefinitions(value, path) {
+  walk(value, path);
+}
+function walk(value, path) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => walk(item, `${path}[${index}]`));
+    return;
+  }
+  if (!isObject(value)) return;
+  for (const [key, item] of Object.entries(value)) {
+    const itemPath = `${path}.${key}`;
+    if (item === void 0 || item === null) continue;
+    if (["definitionRequest", "targetDefinitionRequest", "topicDefinitionRequest"].includes(key)) {
+      validateSemanticAudienceDefinition(item, itemPath);
+    } else if (key === "eventDefinition") {
+      validateSemanticEventDefinition(item, itemPath);
+    } else if (key === "triggerDefinition") {
+      validateTriggerDefinition(item, itemPath);
+    } else if (key === "config" && typeof item === "string") {
+      walkJsonString(item, itemPath);
+    } else {
+      walk(item, itemPath);
+    }
+  }
+}
+function validateTriggerDefinition(value, path) {
+  const definition = object(value, path);
+  rejectUnknown(definition, ["rules"], path);
+  array(definition.rules, `${path}.rules`, 1).forEach((ruleValue, ruleIndex) => {
+    const rulePath = `${path}.rules[${ruleIndex}]`;
+    const rule = object(ruleValue, rulePath);
+    array(rule.events, `${rulePath}.events`, 1).forEach((event, eventIndex) => {
+      const eventPath = `${rulePath}.events[${eventIndex}]`;
+      const candidate = object(event, eventPath);
+      if ("eventDefinition" in candidate) {
+        validateSemanticEventDefinition(candidate.eventDefinition, `${eventPath}.eventDefinition`);
+      } else {
+        validateSemanticEventDefinition(candidate, eventPath);
+      }
+    });
+    optional(rule.blackList, (items) => array(items, `${rulePath}.blackList`).forEach((event, index) => validateSemanticEventDefinition(
+      event,
+      `${rulePath}.blackList[${index}]`
+    )));
+  });
+}
+function validateGroup(value, path) {
+  const group = object(value, path);
+  rejectUnknown(group, ["relation", "items"], path);
+  enumValue(group.relation, /* @__PURE__ */ new Set(["and", "or"]), `${path}.relation`);
+  array(group.items, `${path}.items`, 1).forEach((item, index) => validateCondition(item, `${path}.items[${index}]`));
+}
+function validateCondition(value, path) {
+  const condition = object(value, path);
+  switch (condition.type) {
+    case "event":
+      validateSemanticEventDefinition(condition, path);
+      required(condition.time_range, `${path}.time_range`);
+      return;
+    case "user":
+    case "tag":
+    case "cluster":
+      validatePropertyCondition(condition, path);
+      return;
+    case "compound":
+      rejectUnknown(condition, ["type", "group"], path);
+      validateGroup(condition.group, `${path}.group`);
+      return;
+    case "behavior_sequence":
+      validateBehaviorSequence(condition, path);
+      return;
+    default:
+      invalid(`${path}.type is unsupported.`);
+  }
+}
+function validatePropertyCondition(condition, path) {
+  const extended = condition.type === "tag" || condition.type === "cluster";
+  rejectUnknown(condition, [
+    "type",
+    "field",
+    "operator",
+    "values",
+    "time_relative",
+    "time_unit",
+    ...extended ? ["cluster_date_policy", "specified_cluster_date"] : []
+  ], path);
+  validateField(condition.field, `${path}.field`);
+  if (condition.type === "user") enumValue(condition.operator, OPERATORS, `${path}.operator`);
+  else optionalEnum(condition.operator, OPERATORS, `${path}.operator`);
+  optional(condition.values, (item) => array(item, `${path}.values`));
+  optionalString(condition.time_relative, `${path}.time_relative`);
+  optionalString(condition.time_unit, `${path}.time_unit`);
+  optionalString(condition.cluster_date_policy, `${path}.cluster_date_policy`);
+  optionalString(condition.specified_cluster_date, `${path}.specified_cluster_date`);
+}
+function validateBehaviorSequence(condition, path) {
+  rejectUnknown(condition, ["type", "completed", "steps", "time_range", "window"], path);
+  if (typeof condition.completed !== "boolean") invalid(`${path}.completed must be a boolean.`);
+  array(condition.steps, `${path}.steps`, 1).forEach((stepValue, index) => {
+    const stepPath = `${path}.steps[${index}]`;
+    const step = object(stepValue, stepPath);
+    rejectUnknown(step, ["event", "completed", "filters", "relative_to_first", "window"], stepPath);
+    nonBlankString(step.event, `${stepPath}.event`);
+    optionalBoolean(step.completed, `${stepPath}.completed`);
+    optionalBoolean(step.relative_to_first, `${stepPath}.relative_to_first`);
+    if (index === 1 && step.relative_to_first === true) {
+      invalid(`${stepPath}.relative_to_first must be false or omitted for the second step.`);
+    }
+    optional(step.filters, (item) => validateFilterGroup(item, `${stepPath}.filters`));
+    optional(step.window, (item) => validateWindow(item, `${stepPath}.window`));
+  });
+  required(condition.time_range, `${path}.time_range`);
+  validateTimeRange(condition.time_range, `${path}.time_range`);
+  optional(condition.window, (item) => validateWindow(item, `${path}.window`));
+}
+function validateFilterGroup(value, path) {
+  const group = object(value, path);
+  rejectUnknown(group, ["relation", "items"], path);
+  optionalEnum(group.relation, /* @__PURE__ */ new Set(["and", "or"]), `${path}.relation`);
+  array(group.items, `${path}.items`, 1).forEach((filterValue, index) => {
+    const filterPath = `${path}.items[${index}]`;
+    const filter = object(filterValue, filterPath);
+    rejectUnknown(filter, ["field", "operator", "values"], filterPath);
+    validateField(filter.field, `${filterPath}.field`);
+    enumValue(filter.operator, OPERATORS, `${filterPath}.operator`);
+    optional(filter.values, (item) => array(item, `${filterPath}.values`));
+  });
+}
+function validateField(value, path) {
+  if (typeof value === "string") {
+    nonBlankString(value, path);
+    return;
+  }
+  const field = object(value, path);
+  rejectUnknown(field, ["name", "type"], path);
+  nonBlankString(field.name, `${path}.name`);
+  optionalEnum(field.type, /* @__PURE__ */ new Set([
+    "event_property",
+    "user_property",
+    "tag",
+    "cluster"
+  ]), `${path}.type`);
+}
+function validateTimeRange(value, path) {
+  const range = object(value, path);
+  rejectUnknown(range, ["mode", "unit", "value", "start_time", "end_time"], path);
+  if (range.mode === "custom") {
+    nonBlankString(range.start_time, `${path}.start_time`);
+    nonBlankString(range.end_time, `${path}.end_time`);
+    return;
+  }
+  enumValue(range.mode, /* @__PURE__ */ new Set(["recent", "previous"]), `${path}.mode`);
+  optional(range.unit, (unit) => exactString(unit, "day", `${path}.unit`));
+  positiveInteger(range.value, `${path}.value`);
+}
+function validateWindow(value, path) {
+  const window = object(value, path);
+  rejectUnknown(window, ["value", "unit"], path);
+  positiveInteger(window.value, `${path}.value`);
+  nonBlankString(window.unit, `${path}.unit`);
+}
+function validateMetricEvent(metric, path, dependency) {
+  rejectUnknown(metric, [
+    "type",
+    ...dependency ? ["key"] : [],
+    "event",
+    "aggregation",
+    "property",
+    "percentile",
+    "filters",
+    "display_name"
+  ], path);
+  exactString(metric.type, "event", `${path}.type`);
+  if (dependency) nonBlankString(metric.key, `${path}.key`);
+  nonBlankString(metric.event, `${path}.event`);
+  enumValue(metric.aggregation, METRIC_AGGREGATIONS, `${path}.aggregation`);
+  if (!["total_count", "user_count", "per_user_count"].includes(String(metric.aggregation))) {
+    nonBlankString(metric.property, `${path}.property`);
+  }
+  optionalString(metric.property, `${path}.property`);
+  if (metric.aggregation === "percentile") {
+    optionalNumber(metric.percentile, `${path}.percentile`);
+    if (typeof metric.percentile !== "number" || metric.percentile <= 0 || metric.percentile > 100) {
+      invalid(`${path}.percentile must be greater than 0 and at most 100.`);
+    }
+  } else if (metric.percentile !== void 0 && metric.percentile !== null) {
+    invalid(`${path}.percentile is only valid for percentile aggregation.`);
+  }
+  optionalString(metric.display_name, `${path}.display_name`);
+  optional(metric.filters, (item) => validateFilterGroup(item, `${path}.filters`));
+}
+function walkJsonString(value, path) {
+  try {
+    walk(JSON.parse(value), path);
+  } catch (error) {
+    if (error instanceof SyntaxError) invalid(`${path} must contain valid JSON.`);
+    throw error;
+  }
+}
+function object(value, path) {
+  if (!isObject(value)) invalid(`${path} must be a JSON object.`);
+  return value;
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function array(value, path, minLength = 0) {
+  if (!Array.isArray(value) || value.length < minLength) {
+    invalid(`${path} must be an array with at least ${minLength} item(s).`);
+  }
+  return value;
+}
+function rejectUnknown(value, allowed, path) {
+  const supported = new Set(allowed);
+  const unknown = Object.keys(value).find((key) => !supported.has(key));
+  if (unknown) invalid(`Unsupported field ${path}.${unknown}.`);
+}
+function optional(value, validate) {
+  if (value !== void 0 && value !== null) validate(value);
+}
+function required(value, path) {
+  if (value === void 0 || value === null) invalid(`${path} is required.`);
+}
+function nonBlankString(value, path) {
+  if (typeof value !== "string" || value.trim() === "") {
+    invalid(`${path} must be a non-blank string.`);
+  }
+}
+function optionalString(value, path) {
+  optional(value, (item) => nonBlankString(item, path));
+}
+function exactString(value, expected, path) {
+  if (value !== expected) invalid(`${path} must be ${expected}.`);
+}
+function enumValue(value, allowed, path) {
+  if (typeof value !== "string" || !allowed.has(value)) {
+    invalid(`${path} must be one of: ${[...allowed].join(", ")}.`);
+  }
+}
+function optionalEnum(value, allowed, path) {
+  optional(value, (item) => enumValue(item, allowed, path));
+}
+function optionalNumber(value, path) {
+  optional(value, (item) => {
+    if (typeof item !== "number" || !Number.isFinite(item)) invalid(`${path} must be a number.`);
+  });
+}
+function positiveInteger(value, path) {
+  if (!Number.isInteger(value) || value < 1) {
+    invalid(`${path} must be a positive integer.`);
+  }
+}
+function optionalBoolean(value, path) {
+  optional(value, (item) => {
+    if (typeof item !== "boolean") invalid(`${path} must be a boolean.`);
+  });
+}
+function invalid(message) {
+  throw new CliValidationError(message);
+}
+
 // src/commands/te-engage/engage-flow/flow/save.ts
 var allowedOperations = ["build", "preview", "commit"];
 function readRequest(ctx) {
@@ -223,6 +579,7 @@ function readRequest(ctx) {
   if ("sourceFlowUuid" in req) {
     throw new Error("Flag --req.sourceFlowUuid is unsupported; get the source flow and build nodes/edges instead");
   }
+  validateEmbeddedSemanticDefinitions(req, "--req");
   return req;
 }
 var flowSave = createEngageFlowCapabilityCommand({
@@ -1042,6 +1399,12 @@ var presetEventUpdate = createEngageSettingCapabilityCommand({
     { name: "recharge-event-definition", type: "json", required: false, desc: "Semantic recharge event definition." }
   ],
   risk: "write",
+  validate: (ctx) => {
+    for (const name of ["add-event-definition", "active-event-definition", "recharge-event-definition"]) {
+      const definition = ctx.json(name);
+      if (definition !== void 0) validateSemanticEventDefinition(definition, `--${name}`);
+    }
+  },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
     add_event_definition: ctx.json("add-event-definition") || void 0,
@@ -1085,23 +1448,7 @@ var commonMetricGet = createEngageSettingCapabilityCommand({
 // src/commands/te-engage/engage-setting/common-metric/metric-qp-validation.ts
 var VALID_WINDOW_TIME_UNITS = /* @__PURE__ */ new Set(["minute", "hour", "day"]);
 function validateMetricDefinitionFlag(definition) {
-  if (definition === null || typeof definition !== "object" || Array.isArray(definition)) {
-    printError(
-      "validation",
-      "--metric-definition must be a JSON object.",
-      "Pass a semantic event or formula metric definition."
-    );
-    process.exit(1);
-  }
-  const type = definition.type;
-  if (type !== "event" && type !== "formula") {
-    printError(
-      "validation",
-      "--metric-definition.type must be event or formula.",
-      "Do not pass legacy type=0/1 metric_qp."
-    );
-    process.exit(1);
-  }
+  validateSemanticMetricDefinition(definition, "--metric-definition");
 }
 function validateMetricWindowTimeUnitFlag(unit) {
   if (VALID_WINDOW_TIME_UNITS.has(unit)) {
@@ -1587,6 +1934,16 @@ var presetMetricSet = createEngageSceneCapabilityCommand({
     { name: "attend-event-definition", type: "json", required: false, desc: "Semantic attend event definition." }
   ],
   risk: "write",
+  validate: (ctx) => {
+    for (const name of [
+      "impression-event-definition",
+      "click-event-definition",
+      "attend-event-definition"
+    ]) {
+      const definition = ctx.json(name);
+      if (definition !== void 0) validateSemanticEventDefinition(definition, `--${name}`);
+    }
+  },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
     config_id: ctx.str("config-id"),
@@ -1865,9 +2222,13 @@ var strategyCreate = createEngageSceneCapabilityCommand({
     }
   ],
   risk: "write",
+  validate: (ctx) => {
+    const payload = readRequiredJsonObject(ctx, "payload");
+    validateEmbeddedSemanticDefinitions(payload, "--payload");
+  },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
-    payload: ctx.json("payload")
+    payload: readRequiredJsonObject(ctx, "payload")
   })
 });
 
@@ -1964,9 +2325,13 @@ var strategyUpdate = createEngageSceneCapabilityCommand({
     }
   ],
   risk: "write",
+  validate: (ctx) => {
+    const payload = readRequiredJsonObject(ctx, "payload");
+    validateEmbeddedSemanticDefinitions(payload, "--payload");
+  },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
-    payload: ctx.json("payload")
+    payload: readRequiredJsonObject(ctx, "payload")
   })
 });
 
@@ -2022,7 +2387,10 @@ var strategyPredict = createEngageSceneCapabilityCommand({
   ],
   risk: "read",
   validate: (ctx) => {
-    readRequiredJsonObject(ctx, "definition-request");
+    validateSemanticAudienceDefinition(
+      readRequiredJsonObject(ctx, "definition-request"),
+      "--definition-request"
+    );
   },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
@@ -2513,6 +2881,7 @@ var TOPIC_TASK_EXCLUSION_FIELDS = /* @__PURE__ */ new Set([
 ]);
 function validateStandaloneActivityPayload(value) {
   const payload = requireObject(value);
+  validateEmbeddedSemanticDefinitions(payload, "payload");
   validateTriggerType(payload.triggerType, "triggerType");
   validateScheduleFields(payload);
   validateExperiment(payload.expConfig, "expConfig");
@@ -2536,6 +2905,7 @@ function validateStandaloneActivityPayload(value) {
 }
 function validateActivityTopicPayload(value) {
   const payload = requireObject(value);
+  validateEmbeddedSemanticDefinitions(payload, "payload");
   validateTriggerType(payload.triggerType, "triggerType");
   validateScheduleFields(payload);
   validateExperiment(payload.expConfig, "expConfig");
@@ -2610,7 +2980,7 @@ function validateScheduleFields(payload) {
 }
 function validateExperiment(value, field) {
   if (value === void 0 || value === null) return;
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     fail(
       `${field} must be omitted or set to {"enableExp":false}.`,
       "ACTIVITY_EXPERIMENT_UNSUPPORTED",
@@ -2641,7 +3011,7 @@ function validateSingleContentGroup(value, field) {
   }
 }
 function requireObject(value, field = "payload") {
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     fail(
       `${field} must be a JSON object.`,
       "ACTIVITY_PAYLOAD_INVALID",
@@ -2653,7 +3023,7 @@ function requireObject(value, field = "payload") {
 }
 function containsAnyKey(value, keys) {
   if (Array.isArray(value)) return value.some((item) => containsAnyKey(item, keys));
-  if (!isObject(value)) return false;
+  if (!isObject2(value)) return false;
   return Object.entries(value).some(
     ([key, item]) => keys.has(key) && hasValue(item) || containsAnyKey(item, keys)
   );
@@ -2662,10 +3032,10 @@ function hasValue(value) {
   if (value === void 0 || value === null) return false;
   if (typeof value === "string") return value.trim().length > 0;
   if (Array.isArray(value)) return value.length > 0;
-  if (isObject(value)) return Object.keys(value).length > 0;
+  if (isObject2(value)) return Object.keys(value).length > 0;
   return true;
 }
-function isObject(value) {
+function isObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function fail(message, code, field, hint) {
@@ -3522,7 +3892,7 @@ var taskSave = createEngageTaskCapabilityCommand({
   ],
   risk: "write",
   validate: (ctx) => {
-    readRequiredJsonObject(ctx, "req");
+    validateEmbeddedSemanticDefinitions(readRequiredJsonObject(ctx, "req"), "--req");
   },
   buildInput: (ctx) => ({ project_id: ctx.num("project-id"), req: readRequiredJsonObject(ctx, "req") })
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.0.39",
+  "version": "6.0.40",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "verify:metadata-capability": "npx tsx test/metadata-capability-commands.test.mjs",
     "verify:community-capability": "node test/community-capability-routing.test.mjs",
     "verify:community-report": "npx tsx tests/community-report-standard-v5.test.ts && npx tsx tests/community-report-client.test.ts && npx tsx tests/community-report-framework.test.ts && npx tsx tests/community-data-report-command.test.ts && node test/community-data-report-skill.test.mjs",
-    "verify:engage-capability": "tsx test/engage/engage-capability-command.test.mjs && node test/engage/engage-skill-capability.test.mjs",
+    "verify:engage-capability": "tsx test/engage/engage-capability-command.test.mjs && tsx test/engage/semantic-qp-validation.test.mjs && node test/engage/engage-skill-capability.test.mjs",
     "verify:retired-analysis-commands": "node --test test/retired-analysis-commands.test.mjs",
     "verify:analysis-meta-tools": "node scripts/verify-te-meta-tools.mjs",
     "verify:analysis-common-tools": "node scripts/verify-te-common-tools.mjs",

package/skills/ae-engage/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-engage
 version: 1.0.0
-description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, and task management. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task."
+description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, task management, and operation activities. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, operation activity, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task, engage-activity."
 ---
 
 # ae-engage
@@ -56,6 +56,7 @@ When the user mentions a product term below (including common Chinese UI labels)
 | **Config channel** | Config-center Webhook/client config channels (not the same as push channels) | `engage-scene` | `references/scene-config-channel.md` | `channel-mgmt.md` (create/enable-disable/copy/delete workflows). User params in `config.customsParamList` require `columnName` with `user:` prefix (e.g. `user:#account_id`); preflight names with ae-analysis `analysis-meta property list/get`. |
 | **Operation strategy** | Ops/delivery strategies under a config item | `engage-scene` | `references/scene-strategy.md` | Custom audience: [`scene-strategy-audience.md`](references/scene-strategy-audience.md) — semantic `definitionRequest` (Analysis condition shape); do not pass `targetClusterQp`/`qp`; preflight props (stop + list if missing); template: `scene-template.md` |
 | **Operation task** | Hermes push/engagement tasks (list, save, lifecycle, reports) | `engage-task` | `references/task-list.md` | `task-detail.md` (get), `save-task.md`, `build-task-save-guide.md`, `task-stats.md`, `task-delete.md`, `push-record-query.md`, `task-data-overview.md`, `task-data-detail.md`, `task-metric-detail.md`, `task-experiment-report.md` |
+| **Operation activity** | Campaign activity management and delivery trends by activity, topic, or standalone task | `engage-activity` | `references/activity-activity.md` | `activity-data-detail.md`, `activity-topic.md`, `activity-task.md`, `activity-approval.md` |
 | **Template** | Strategy templates under a config item | `engage-scene` | `references/scene-template.md` | `scene-config-param.md` (template fields reference `paramId`); enable via `template update` then `template update-status` before strategy create |
 
 **Easy to confuse:**
@@ -75,6 +76,7 @@ Naming boundary:
 
 - CLI flags use kebab-case; outer Capability input and all Capability response keys use snake_case.
 - Nested business DTOs passed through `--req` or `--payload` keep their documented native camelCase fields. Do not mechanically convert those nested DTO keys to snake_case.
+- Semantic audience, event, trigger, completion, and metric definitions are closed contracts. The CLI rejects malformed or unknown semantic fields locally; `--validate` applies the same precise Hermes capability schema without writing.
 - Successful migrated commands return their business payload under `data`; read the matching reference's Response shape before selecting fields.
 
 ## JSON Parameter Format
@@ -375,6 +377,9 @@ ae-cli engage-setting channel list --project-id <projectId>
 5. `engage-flow flow save` is **operation-based** (protocol v2). The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names — use `nodes` / `edges` with `operation=build`. A legacy `nodeList`/`edgeList` payload (or a missing `operation`) is rejected with `Unsupported save_flow operation: null`.
 6. Run the lifecycle: `build` (returns `data.result.status = ready_to_preview` or `need_input`) → resolve any `data.result.next_slot` → `preview` (re-issues response fields `data.result.draft_version` + `data.result.confirm_token`) → `commit` (maps those values to request fields `draftVersion` + `confirmToken`) → reads the final ID from `data.result.result.flow_uuid`.
 7. `nodes[].config` / `edges[].config` may be a JSON object or a JSON string. Custom audience nodes and branches use semantic `targetDefinitionRequest`; Hermes compiles it to the node's stored execution format.
+   Never send `targetClusterQp`. Each audience `event` and `behavior_sequence` must include
+   its own `time_range`; Flow entry dates do not replace that range. Use only properties that
+   resolve through the Flow editor's current project, timezone, and user-entity metadata scope.
 8. You must self-check before previewing/committing:
    - There is exactly one entry node
    - There is at least one `exit_flow`
@@ -456,6 +461,7 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `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}`)
@@ -533,7 +539,9 @@ For task draft creation or update, use this workflow:
    `channelType`, `triggerType`, and `eventTriggerType` to `build-save-guide`, then use its
    type-specific semantic event shape. Accumulated events are aggregate conditions, continuous
    events use count/eq with a value of at least 2, ordered events use sequence-step envelopes,
-   and every-completion events use count/eq/1. Never construct persisted QP fields.
+   and every-completion events use count/eq/1. Completion target and experiment main-goal event
+   filters must not use properties whose metadata `select_type` is `datetime`. Never construct
+   persisted QP fields.
 4. `ae-cli engage-task task save --project-id <projectId> --req '{...}'`
 5. `ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>`
 
@@ -551,3 +559,5 @@ Audience creation is not a fixed preflight step. For custom task audiences, use
 `definition_request`. `clientConfig.clientQp` is server-authored and must be omitted from
 Capability requests; partial updates preserve existing server state. Do not assemble raw QP
 manually.
+For a `behavior_sequence`, omit second-step `relative_to_first` or set it to `false`; reserve
+`true` for step 3 or later when the window is measured from step 1.

package/skills/ae-engage/references/activity-data-detail.md

@@ -0,0 +1,61 @@
+# engage-activity.activity-data.detail
+
+Query activity delivery trends through the L3 Capability Gateway.
+
+Mapped command:
+
+```bash
+ae-cli capability run engage-activity.activity-data.detail --input '<json>'
+```
+
+## Input
+
+Required fields:
+
+- `project_id`: project that owns the activity.
+- `activity_id`: activity to query.
+- `start_time`: inclusive start date in `yyyy-MM-dd` format.
+- `end_time`: inclusive end date in `yyyy-MM-dd` format.
+
+Optional fields:
+
+- `time_particle_size`: `T1` (day), `T2` (week), `T3` (month), or `T5` (total). Defaults to `T1`.
+- `source`: `activity` or `topic_and_task`. Defaults to `activity`.
+- `topic_id_list`: selected topic IDs.
+- `task_id_list`: selected standalone task IDs.
+- `request_id`: cancelable query ID. A UUID is generated when omitted.
+
+When `source=topic_and_task` and both ID lists are omitted or empty, the capability selects every topic and standalone task in the activity. When either list is provided, only the explicitly selected resources are queried. Selected resources must belong to the activity and project.
+
+## Recent seven-day topic trend
+
+Use an inclusive seven-day range, `T1`, and `topic_and_task`:
+
+```bash
+ae-cli capability run engage-activity.activity-data.detail --input \
+  '{"project_id":1,"activity_id":"act-1","start_time":"2026-07-25","end_time":"2026-07-31","time_particle_size":"T1","source":"topic_and_task","request_id":"<uuid>"}'
+```
+
+The report exposes the existing activity-page indicators:
+
+- `plan`: planned trigger users.
+- `actualTrigger`: actual push users.
+- `trigger`: successful push users.
+
+It does not expose `view` (actual arrival) or `click`. Use the returned header values instead of treating `trigger` as an actual-arrival metric.
+
+## Output
+
+Successful output contains:
+
+- `data.request_id`: the request ID used by the query.
+- `data.result_generate_time`: ISO-8601 generation time.
+- `data.data.x`: summary/date axis.
+- `data.data.headers`: indicator keys.
+- `data.data.total`: activity totals aligned with `headers`.
+- `data.data.values`: topic or standalone-task rows aligned with `x` and `headers`.
+- `data.data.topic_list`: selected source IDs and names using `topic_id` and `topic_name`.
+
+The first `x`/`total` row is the overall summary. For non-total time grains, subsequent rows are the requested date buckets.
+
+Use `engage-setting.query.cancel` with the same `request_id` to cancel a running query.