@thinkingai/ae-cli 6.0.24 → 6.0.28

package/skills/ae-engage/references/save-flow.md

@@ -4,9 +4,9 @@ Create, edit, preview, or commit a flow canvas draft.
 
 Mapped command: `ae-cli engage +save_flow --project_id <projectId> --req '<req-json>'`
 
-> **Protocol v2 (current).** `save_flow` is now **operation-based**. The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names — send `nodes` / `edges` instead. Posting a legacy `nodeList`/`edgeList` payload (or omitting `operation`) makes the backend reject the call with `Unsupported save_flow operation: null`.
+> **Protocol v2 (current).** `save_flow` is now **operation-based**. The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names -- send `nodes` / `edges` instead. Posting a legacy `nodeList`/`edgeList` payload (or omitting `operation`) makes the backend reject the call with `Unsupported save_flow operation: null`.
 
-The CLI passes your `--req` straight through to the backend (it only injects `projectId`). So everything in this document is about building the correct `req` object.
+The CLI injects `projectId` and rejects missing/unsupported `operation` values, legacy `nodeList`/`edgeList` fields, and the removed `sourceFlowUuid` clone mode; otherwise it passes your `--req` through to the backend. So everything in this document is about building the correct `req` object.
 
 ---
 
@@ -22,10 +22,11 @@ build  ──► status = ready_to_preview ──► preview ──► commit
 
 You still organize user requirements into an intermediate intent first, then map the intent to `nodes` / `edges`, then run the lifecycle.
 
-- `build`: assemble/edit a draft from `nodes` + `edges` (or `dsl`, or clone). Returns `ready_to_preview` (with `draftId`, `draftVersion`, `confirmToken`, `preview.mainPath`) or `need_input` (one more slot required).
+- `build`: assemble/edit a draft from `nodes` + `edges` (or topology-only `dsl`). Returns `ready_to_preview` (with `draftId`, `draftVersion`, `confirmToken`, `preview.mainPath`) or `need_input` (one more slot required).
 - `preview`: validate the draft; **re-issues** a fresh `draftVersion` + `confirmToken`.
 - `commit`: finalize the draft into a flow version using the **preview** `draftVersion` + `confirmToken`; returns the final `flowUuid`.
 - Always verify with `ae-cli engage +flow_detail --project_id <projectId> --flow_uuid <flowUuid>`.
+- To copy an existing flow, first call `+flow_detail`, convert the returned `nodeList` / `edgeList` into compact `nodes` / `edges`, then call `operation=build` as normal creation input. Do not pass `sourceFlowUuid`.
 
 ---
 
@@ -34,8 +35,9 @@ You still organize user requirements into an intermediate intent first, then map
 1. Identify the flow intent from the user input and produce a unified intent JSON.
 2. Run `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition` to obtain the condition cluster definition schema for assembling condition-related fields later.
 3. Run `ae-cli engage +channel_list --project_id <projectId>` to get the available channels and match real `channelId` values for touchpoint nodes. For `webhook_push`, also run `ae-cli engage +channel_detail` and use `data.config.paramsList` to build `contentList`.
-4. Map the intent JSON to `nodes` and `edges` (compact form, see §7 / §8).
-5. `build` → resolve any `need_input` slot → `preview` → `commit`, then verify with `+flow_detail`.
+4. Query `ae-cli engage +flow_node_config_schema --node_type <type>` before constructing each non-trivial node config, then run `ae-cli engage +validate_flow_node_config --node_type <type> --operation_mode save_flow --config '<config-json-string>'` before placing the config into `nodes` or `nodeConfigs`.
+5. Map the intent JSON to `nodes` and `edges` (compact form, see §7 / §8).
+6. `build` → resolve any `need_input` slot → `preview` → `commit`, then verify with `+flow_detail`.
 
 ---
 
@@ -54,7 +56,6 @@ You still organize user requirements into an intermediate intent first, then map
 | `nodes` | array | build | Compact nodes for structured build (see §7) |
 | `edges` | array | build | Compact edges for structured build (see §8) |
 | `dsl` | string | build | Topology-only: lines `node <id> <type>` and `edge <source> -> <target>` |
-| `sourceFlowUuid` | string | build | Clone an existing flow into a new draft |
 | `flowUuid` | string | build | Draft flow UUID for update-draft mode |
 | `parentFlowUuid` | string | build | Base version flow UUID for new-version mode |
 | `userIntent` | string | build | Natural-language intent (optional) |
@@ -69,6 +70,23 @@ You still organize user requirements into an intermediate intent first, then map
 
 `flowUuid` and `parentFlowUuid` are mutually exclusive; when creating a brand-new draft, provide neither.
 
+### Response Fields
+
+Common response fields include:
+
+| Field | Meaning |
+|---|---|
+| `status` | Draft state, such as `need_input`, `ready_to_preview`, `previewed`, or `committed` |
+| `draftId` / `draftVersion` | Server draft identity and version |
+| `selectedMode` | Server-selected authoring mode, such as structured build, wizard, or draft edit |
+| `confidence` / `reason` | Router confidence and explanation for the selected mode |
+| `nextSlot` | One missing slot to answer when `status=need_input` |
+| `preview` | Human-readable preview; use it for user confirmation |
+| `confirmToken` | Token returned by `preview`; required for `commit` |
+| `warnings` / `errors` | Soft warnings and hard validation failures |
+| `supportedOperations` | Server-advertised `build`, `preview`, and `commit` contract |
+| `result` | Commit result, including the final `flowUuid` when committed |
+
 ### Compact node (`nodes[]`)
 
 | Field | Required | Description |
@@ -86,7 +104,7 @@ You still organize user requirements into an intermediate intent first, then map
 | `source` | Yes | Upstream node ID |
 | `target` | Yes | Downstream node ID |
 | `edgeId` | No | Edge ID, unique within the canvas |
-| `sourceBranchId` | No | Branch ID for edges leaving a split/judge node |
+| `sourceBranchId` | No | Branch ID for edges leaving a split/judge node, or a push action node with two branch outgoing edges |
 | `config` | No | Edge business config as JSON string |
 
 ---
@@ -217,36 +235,47 @@ Inside action nodes: `channel_name` → real `channelId`; `content` → `content
 2. Any `branchId` later referenced by `edge.sourceBranchId` must be declared in that node's `config` first.
 3. Every path must eventually end at `exit_flow`.
 4. `config` may be a JSON object or a JSON string. (`targetClusterQp` inside it is usually a `JSON.stringify`'d string — see §9.)
+5. The backend normalizes some compatible input forms before validation: leading apostrophes on field names are stripped, property names are matched case-insensitively when unambiguous, `enableChannelTouchLimits` booleans become `1`/`0`, `targetClusterQp` relation strings `"0"`/`"1"` become numeric values inside the JSON string, and `clusterPredictCount: null` becomes `0`.
 
 ### 7.2 Common Node Types
 
 `single_trigger`, `repeat_trigger`, `event_trigger`, `event_split_flow`, `feature_split_flow`, `ab_split_flow`, `event_judge`, `feature_judge`, `message_push`, `wechat_push`, `webhook_push`, `time_control`, `exit_flow`.
 
+Before writing any config below, call `+flow_node_config_schema` for the exact node type. The backend schema is the source of truth for required fields, defaults, allowed enum values, submit-time requirements, and examples.
+
 ### 7.3 Common `config` Templates
 
+#### `single_trigger`
+
+```json
+{ "targetUserType": 2, "triggerTime": "<YYYY-MM-DD HH:mm>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "targetClusterName": "<existing clusterName>" }
+```
+
+For custom users, use `targetUserType=1` and fill `targetClusterQp` with the QP JSON string returned by the cluster QP workflow. For existing clusters (`targetUserType=2`), fill `targetClusterName` from a real current-project cluster list queried with the flow `tzOffset`; do not fill `targetClusterQp`. `clusterPredictCount` defaults to `0` and `clusterPredictTime` defaults to `""` when omitted.
+
 #### `repeat_trigger`
 
 ```json
-{ "targetUserType": 1, "startDate": "<YYYY-MM-DD>", "endDate": "<YYYY-MM-DD>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "crontab": "0 00 09 * * ?", "entryControlLimits": { "enableMultEntry": false, "disableConcurrentEntry": false }, "targetClusterName": null, "clusterPredictCount": null, "clusterPredictTime": "<YYYY-MM-DD HH:mm:ss>", "targetClusterQp": "<JSON.stringify(qp)>" }
+{ "targetUserType": 1, "startDate": "<YYYY-MM-DD>", "endDate": "<YYYY-MM-DD>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "crontab": "0 00 09 * * ?", "entryControlLimits": { "enableMultEntry": false, "disableConcurrentEntry": false }, "targetClusterName": null, "targetClusterQp": "<JSON.stringify(qp)>" }
 ```
 
-`entry.segment` → `targetClusterQp`; `entry.schedule` → `crontab` (common default `0 00 09 * * ?`).
+`entry.segment` → `targetClusterQp`; `entry.schedule` → `crontab` (common default `0 00 09 * * ?`). `clusterPredictCount` defaults to `0` and `clusterPredictTime` defaults to `""` when omitted. For existing clusters (`targetUserType=2`), fill `targetClusterName` from a real current-project cluster list queried with the flow `tzOffset`; do not fill `targetClusterQp`.
 
 #### `event_trigger`
 
 ```json
-{ "triggerType": 3, "targetUserType": 1, "realtime": 0, "clusterRefresh": 12, "clusterRefreshTime": null, "startDate": "<YYYY-MM-DD HH:mm>", "endDate": "<YYYY-MM-DD HH:mm>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "clusterPredictCount": null, "clusterPredictTime": "<YYYY-MM-DD HH:mm:ss>", "triggerRule": [ { "periodStart": "<startDate>", "periodEnd": "<endDate>", "periodTimeSymbol": "TS02", "dayStartTime": null, "startDay": null, "eventTriggerType": 0, "zoneoffset": 8, "events": [] } ], "entryControlLimits": { "enableMultEntry": false, "disableConcurrentEntry": false }, "targetClusterQp": "<JSON.stringify(qp) or null>" }
+{ "triggerType": 3, "targetUserType": 1, "startDate": "<YYYY-MM-DD HH:mm>", "endDate": "<YYYY-MM-DD HH:mm>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "triggerRule": [ { "periodStart": "<startDate>", "periodEnd": "<endDate>", "periodTimeSymbol": "TS02", "eventTriggerType": 0, "events": [] } ], "entryControlLimits": { "enableMultEntry": false, "disableConcurrentEntry": false }, "targetClusterQp": "<JSON.stringify(qp) or null>" }
 ```
 
-`entry.trigger_event` → `triggerRule[0].events`; generate `targetClusterQp` only when `entry.segment` exists.
+`entry.trigger_event` → `triggerRule[0].events`; generate `targetClusterQp` only when `entry.segment` exists. `triggerType` supports `3`, `4`, and `5`; `targetUserType=2` existing cluster is not supported for `event_trigger`; use `1` custom or `3` all users. For non-branch trigger rules, use `periodStart` / `periodEnd` / `periodTimeSymbol`. `realtime`, `clusterRefresh`, `clusterRefreshTime`, `clusterPredictTime`, and `triggerRule[].zoneoffset` can be omitted and are defaulted by the backend.
 
 #### `event_split_flow`
 
 ```json
-{ "splitFlowType": 1, "branchList": [ { "branchId": "<branchId>", "branchName": "<label>", "branchType": 1, "triggerRule": [ { "delayTimeSymbol": "<minute|hour|day>", "delayTime": "<number>", "eventTriggerType": "<0 or -1>", "zoneoffset": 8, "events": [] } ] } ] }
+{ "splitFlowType": 1, "branchList": [ { "branchId": "<branchId>", "branchName": "<label>", "branchType": 1, "targetClusterType": 3, "triggerRule": [ { "delayTimeSymbol": "<minute|hour|day>", "delayTime": "<number>", "eventTriggerType": "<0|-1|1|2>", "events": [] } ] } ] }
 ```
 
-`time_limit` → `delayTimeSymbol` + `delayTime`; `0` = happened, `-1` = not happened. Fallback branch keeps only `{ "branchId": "<branchId>", "branchType": 2 }`.
+`time_limit` → `delayTimeSymbol` + `delayTime`; `0` = happened, `-1` = not happened. For `branchType=1`, fill `targetClusterType`; use `3` for all users. If `targetClusterType` is not `3`, fill `clusterKey`. `occasionKeys` is optional, but each item must contain at least four colon-separated parts. Fallback branch keeps only `{ "branchId": "<branchId>", "branchType": 2 }` and must omit `triggerRule`.
 
 #### `feature_split_flow`
 
@@ -265,10 +294,10 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 #### `event_judge`
 
 ```json
-{ "transferType": 1, "meetBranchId": "<meetBranchId>", "notMeetBranchId": "<notMeetBranchId>", "triggerRule": [ { "delayTimeSymbol": "<minute|hour|day>", "delayTime": "<number>", "eventTriggerType": 0, "zoneoffset": 8, "events": [] } ] }
+{ "transferType": 1, "meetBranchId": "<meetBranchId>", "notMeetBranchId": "<notMeetBranchId>", "triggerRule": [ { "periodStart": "<YYYY-MM-DD HH:mm>", "periodEnd": "<YYYY-MM-DD HH:mm>", "periodTimeSymbol": "TS02", "eventTriggerType": 0, "events": [] } ] }
 ```
 
-`wait_time` → `delayTimeSymbol` + `delayTime` (default `30 minute` if unspecified).
+`event_judge` is a non-branch flow task. Use `periodStart`, `periodEnd`, and `periodTimeSymbol` in the A segment; use `delayTime` / `delayTimeSymbol` only for a B segment when the schema/example requires it. `eventTriggerType` supports `0`, `1`, and `2`.
 
 #### `feature_judge`
 
@@ -279,10 +308,10 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 #### `message_push` / `webhook_push`
 
 ```json
-{ "channelId": "<matched channelId>", "channelType": "<matched channelType>", "enableChannelTouchLimits": false, "isOccasionUp": false, "contentList": [ { "pushLanguageCode": "default", "content": [] } ], "processType": 1 }
+{ "channelId": "<matched channelId>", "channelType": "<matched channelType>", "contentList": [ { "pushLanguageCode": "default", "content": [] } ] }
 ```
 
-`channel_name` → real `channelId`; `content` → the param that best matches body text. When the param `type = TEXT`, also add `{ "config": "[{\"type\":\"paragraph\",\"children\":[{\"text\":\"<same as value>\"}]}]" }`. First `contentList` entry must use `"pushLanguageCode": "default"`; generate extra languages per `languages`.
+`channel_name` → real `channelId`; `content` → the param that best matches body text. `processType` defaults to `1`, `enableChannelTouchLimits` defaults to `0`, and `isOccasionUp` defaults to `false`. `enableChannelTouchLimits` may be supplied as a boolean for compatibility, but `normalizedConfigObject` will convert it to `1` or `0`. When the param `type = TEXT`, also add `{ "config": "[{\"type\":\"paragraph\",\"children\":[{\"text\":\"<same as value>\"}]}]" }`. `contentList[].content` should be a JSON array; validation also accepts a JSON-stringified array for compatibility. When the param `type = OBJ_ARRAY`, `value` must be a JSON array, and the item must copy the complete child field definition from `query_channel_detail data.config.paramsList[].objArray`. First `contentList` entry must use `"pushLanguageCode": "default"`; generate extra languages per `languages`.
 
 #### `wechat_push`
 
@@ -296,6 +325,8 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 { "controlType": 1, "timeUnit": "<minute|hour|day>", "timeUnitNum": "<number>" }
 ```
 
+`controlType=1` requires `timeUnit` + `timeUnitNum`; `2` requires `timePointStr`; `3` requires `rollTimeDayNum` + `timePointStr`; `4` requires `fixedDay` + `timePointStr`; `5` requires `relativeMonthLastDayNum` + `timePointStr`.
+
 `30 minutes` → `minute`+`30`; `2 hours` → `hour`+`2`; `1 day` → `day`+`1`.
 
 #### `exit_flow`
@@ -325,14 +356,17 @@ Minimum usable `config`: `{}`.
 | `single_trigger` / `repeat_trigger` / `event_trigger` | 1 | do not provide |
 | `event_split_flow` / `feature_split_flow` / `ab_split_flow` | one per branch | the corresponding `branchList[].branchId` |
 | `event_judge` / `feature_judge` | 2 | `meetBranchId` and `notMeetBranchId` |
-| `message_push` / `wechat_push` / `webhook_push` / `time_control` | 1 | do not provide |
+| `message_push` / `wechat_push` / `webhook_push` | 1 or 2 | omit for 1 outgoing edge; for 2 outgoing edges, use the node config's `meetBranchId` and `notMeetBranchId` |
+| `time_control` | 1 | do not provide |
 | `exit_flow` | 0 | do not provide |
 
 ### 8.4 Rules
 
 1. `source` / `target` must reference existing `node.id` values.
-2. Only edges leaving split/judge nodes carry `sourceBranchId`, and it must be a `branchId` already declared in the upstream node `config`.
-3. The graph must be a DAG (no cycles).
+2. Edges leaving split/judge nodes carry `sourceBranchId`. Push action nodes (`message_push`, `wechat_push`, `webhook_push`) may also carry `sourceBranchId` when they have exactly two outgoing edges.
+3. For push action nodes with one outgoing edge, omit `meetBranchId` / `notMeetBranchId`; if present, the backend ignores them.
+4. For push action nodes with two outgoing edges, set both `config.meetBranchId` and `config.notMeetBranchId`, and make the two `edge.sourceBranchId` values match them.
+5. The graph must be a DAG (no cycles).
 
 ---
 
@@ -436,7 +470,7 @@ ae-cli engage +save_flow --project_id 1 --req '{
   "flowDesc": "New user welcome flow",
   "groupId": 0, "tzOffset": 8, "versionType": 1,
   "nodes": [
-    { "id": "n1", "type": "single_trigger", "name": "Enter", "config": {} },
+    { "id": "n1", "type": "single_trigger", "name": "Enter", "config": { "targetUserType": 2, "triggerTime": "2026-03-31 19:00", "flowEndDate": "2026-04-04 18:00", "targetClusterName": "cohort_20260331_182643" } },
     { "id": "n2", "type": "exit_flow", "name": "End", "config": {} }
   ],
   "edges": [ { "source": "n1", "target": "n2" } ]
@@ -483,6 +517,7 @@ Output the complete `req` JSON for debugging plus a clear failure reason.
 | Symptom | Cause | Fix |
 |---|---|---|
 | `Unsupported save_flow operation: null` | Legacy `nodeList`/`edgeList` payload, or `operation` missing | Put `operation` = `build`/`preview`/`commit` in `req`, use `nodes`/`edges` |
+| `Flag --req.sourceFlowUuid is no longer supported` | Removed clone mode from an older protocol | Call `+flow_detail`, convert detail `nodeList`/`edgeList` into compact `nodes`/`edges`, then create with `operation=build` |
 | operation rejected (`SAVE`/`DRAFT`/`SUBMIT`/`mode`/`action`…) | Wrong field or wrong enum | `operation` is at `req.operation`; enum is only `build`/`preview`/`commit` |
 | `invalid_qp_relation: QP relation must be number 0 or 1` | `relation` sent as string | Use integer `0`/`1` |
 | `invalid_qp_leaf: QP property leaf must contain columnType/columnDesc` | userCondition leaf missing fields | Add `columnType` + `columnDesc` |
@@ -499,16 +534,17 @@ Output the complete `req` JSON for debugging plus a clear failure reason.
 ## 13. Most Common Mistakes
 
 1. **Legacy `nodeList`/`edgeList`** — use `nodes`/`edges` with `operation=build`.
-2. **Time units must be lowercase** — `day`, `hour`, `minute`, `week`, `month` (not `DAY`/`HOUR`).
-3. **Do not invent `channelId`** — get it from `ae-cli engage +channel_list`.
-4. **Define branch IDs before referencing them** — `edge.sourceBranchId` must already exist in the upstream node `config`.
-5. **`targetClusterQp` is usually a string** — `JSON.stringify` the QP object.
-6. **TEXT rich-text `config` must also be a string** — not an object.
-7. **`commit` uses preview's token/version** — not build's.
-8. **Do not merge branches again when `splitFlowType = 2`**.
+2. **Removed clone mode** — do not pass `sourceFlowUuid`; copy flows via `+flow_detail` and a fresh `operation=build` request.
+3. **Time units must be lowercase** — `day`, `hour`, `minute`, `week`, `month` (not `DAY`/`HOUR`).
+4. **Do not invent `channelId`** — get it from `ae-cli engage +channel_list`.
+5. **Define branch IDs before referencing them** — `edge.sourceBranchId` must already exist in the upstream node `config`; for two-edge push action nodes, use `meetBranchId` and `notMeetBranchId`.
+6. **`targetClusterQp` is usually a string** — `JSON.stringify` the QP object.
+7. **TEXT rich-text `config` must also be a string** — not an object.
+8. **`commit` uses preview's token/version** — not build's.
+9. **Do not merge branches again when `splitFlowType = 2`**.
 
 ---
 
 ## 14. One-Sentence Summary
 
-Drive `+save_flow` as a state machine — `build` (`nodes`/`edges`, not `nodeList`/`edgeList`) → resolve any `need_input` slots → `preview` (take its fresh `draftVersion` + `confirmToken`) → `commit` → verify with `+flow_detail`; keep QP `relation` integer, fill `columnType`/`columnDesc` on userCondition leaves and `quotaDesc`/`quota`/`analysisParams` on `taPropQuota`, and ensure touchpoint channels are enabled before referencing them.
+Drive `+save_flow` as a state machine — `build` (`nodes`/`edges`, not `nodeList`/`edgeList` or `sourceFlowUuid`) → resolve any `need_input` slots → `preview` (take its fresh `draftVersion` + `confirmToken`) → `commit` → verify with `+flow_detail`; keep QP `relation` integer, fill `columnType`/`columnDesc` on userCondition leaves and `quotaDesc`/`quota`/`analysisParams` on `taPropQuota`, and ensure touchpoint channels are enabled before referencing them.

package/skills/ae-engage/references/validate-flow-node-config.md

@@ -1,7 +1,7 @@
 # ae-engage +validate_flow_node_config
 
 
-Validate a single node configuration before saving a flow.
+Validate and normalize a single node configuration before placing it into a `save_flow` request.
 
 Mapped command: `ae-cli engage +validate_flow_node_config`
 
@@ -9,15 +9,38 @@ Mapped command: `ae-cli engage +validate_flow_node_config`
 
 | Flag | Type | Required | Description |
 |------|------|------|------|
-| `--node_type` | string | Yes | node type |
-| `--config` | string | Yes | node config JSON string |
-| `--operation_mode` | string | Yes | validation mode |
+| `--node_type` | string | Yes | Flow node type |
+| `--config` | string | Yes | Node config JSON object encoded as a string |
+| `--operation_mode` | string | Yes | Validation mode |
+
+## When To Use
+
+Use this after `+flow_node_config_schema` and before passing a config into `+save_flow`.
+
+The command validates one node config only; it does not validate the full canvas topology. It returns:
+
+- `valid`: whether the candidate config passed validation
+- `normalizedConfigObject`: backend-normalized config with defaulted fields
+- `errors`: hard validation failures to fix before calling `+save_flow`
+- `warnings`: issues that depend on live channel/template/config data
+
+Use `--operation_mode save_flow` for the current exposed MCP protocol. Use `save_submit_flow` only when you intentionally want stricter submit-time checks.
+
+Important current rules:
+
+- `event_trigger` / `event_judge` A segment: use `periodStart`, `periodEnd`, `periodTimeSymbol`; do not use branch-style `delayTime`.
+- `event_split_flow` branch segment: use `delayTime`, `delayTimeSymbol`, `targetClusterType`; omit `triggerRule` on default branches.
+- `event_trigger targetUserType=2` is invalid.
+- Push `OBJ_ARRAY.value` must be a JSON array, not a stringified array.
+- Push `contentList[].content` should be a JSON array, but a JSON-stringified array is accepted for compatibility.
+- Compatible inputs are normalized before validation: apostrophe-prefixed field aliases, case-insensitive property aliases, `enableChannelTouchLimits` booleans, string `"0"`/`"1"` QP relations inside `targetClusterQp`, and `clusterPredictCount: null`.
+- Missing defaults such as `clusterPredictCount`, `clusterPredictTime`, `processType`, and `zoneoffset` may be filled in `normalizedConfigObject`.
 
 ## Enum Notes
 
 ### `--node_type`
 
-Common node types include:
+Schema-backed node types include:
 
 - `single_trigger`
 - `repeat_trigger`
@@ -27,15 +50,10 @@ Common node types include:
 - `message_push`
 - `wechat_push`
 - `webhook_push`
-- `config_push`
-- `tag`
 - `time_control`
 - `feature_split_flow`
 - `event_split_flow`
-- `trigger_prop_split_flow`
-- `percent_split_flow`
 - `ab_split_flow`
-- `race_split_flow`
 - `exit_flow`
 
 ### `--operation_mode`

package/skills/ae-generate-tracking-code/SKILL.md

@@ -97,7 +97,8 @@ First, check if `.ae-cli/draft.json` exists and read existing configuration:
    - If the project is missing, ambiguous, or has no `appId`, ask the user to copy APP_ID from AE Admin → "Project Settings" → "Integration Config".
 2. **SERVER_URL** — Data ingestion endpoint (**different from web URL**; go to AE Admin → "Project Settings" → "Integration Config" → fill in "Public URL")
    - If `meta.project_id` is known, you may try `ae-cli analysis_meta +get_project_config --project_id <project_id>` once.
-   - Use the returned value only if the response explicitly contains a receiver URL field such as `serverUrl`, `pushUrl`, `push_url`, `receiverUrl`, `publicUrl`, or equivalent ingestion endpoint field.
+   - Use the returned value only if the response explicitly contains a receiver URL field such as `serverUrl`, `pushUrl`, `push_url`, `receiverUrl`, `publicUrl`, `publicReceiverAddress`, `privateReceiverAddress`, or equivalent ingestion endpoint field.
+   - If both `publicReceiverAddress` and `privateReceiverAddress` are present, prefer `publicReceiverAddress` as `SERVER_URL` for generated snippets unless the user explicitly needs an internal/private-network receiver.
    - If a value is found, ask: **"I found SERVER_URL `<url>` for project `<projectId>`. Use it? yes / enter new value"**
    - ⚠️ "Public URL" only shows if previously filled in; if empty, this field won't display
    - Solution: ask ops for the URL, or **skip this step** (use `SERVER_URL` or `PUSH_URL` placeholder in code)
@@ -507,6 +508,20 @@ Upload list rules:
 - Include generated debug scripts if the user selected the debug option.
 - Do not upload files inserted directly into the user's project; only upload generated output artifacts.
 
+### Attachment upload compatibility
+
+The Agent attachment backend accepts a limited document MIME set. Code/config artifacts such as `.java`, `.kt`, `.swift`, `.m`, `.ets`, `.cs`, `.py`, `.go`, `.ts`, `.js`, `.php`, and `.json` may be rejected if uploaded directly.
+
+Before running `ae-cli agent +add-attachment`, prepare the upload list as follows:
+- Keep every original generated file unchanged under `.ae-cli/output/`.
+- For each generated text artifact whose extension may be unsupported by the attachment backend, create an upload-only sibling copy by appending `.txt` to the filename.
+  - Example: `.ae-cli/output/java-sdk.java` → `.ae-cli/output/java-sdk.java.txt`
+  - Example: `.ae-cli/output/daemon.json` → `.ae-cli/output/daemon.json.txt`
+- The `.txt` copy must have identical content to the original file. Do not wrap it in markdown fences, do not add headers, and do not change line endings intentionally.
+- Upload the `.txt` compatibility copies instead of the unsupported originals.
+- Keep `.md`, `.txt`, and `.csv` artifacts in the upload list as-is.
+- In the final response, list the original deliverable paths first, then mention any `.txt` compatibility copies used only for attachment upload.
+
 If upload succeeds, include the attachment upload result in the final response and tell the user the files are available from the file/attachment management entry. If upload fails because Agent attachment credentials are unavailable, keep the local `.ae-cli/output/` files and tell the user the upload did not complete.
 
 ### All snippets

package/skills/ae-generate-tracking-code/references/snippet-delivery.md

@@ -247,6 +247,22 @@ Upload list must include:
 
 Only upload generated output artifacts. Do not upload files inserted directly into the user's project.
 
+### Upload Compatibility for Code and Config Files
+
+The attachment upload endpoint accepts a limited document MIME set. Many generated tracking artifacts are valid text files but have extensions that may be rejected by the backend when uploaded directly, including `.java`, `.kt`, `.swift`, `.m`, `.ets`, `.cs`, `.py`, `.go`, `.ts`, `.js`, `.php`, and `.json`.
+
+Before calling `ae-cli agent +add-attachment`, build an upload-safe file list:
+
+1. Keep the original generated files unchanged in `.ae-cli/output/`.
+2. For each unsupported text artifact, create a sibling upload-only copy with `.txt` appended to the original filename.
+   - `.ae-cli/output/android-sdk-java.java` → `.ae-cli/output/android-sdk-java.java.txt`
+   - `.ae-cli/output/daemon.json` → `.ae-cli/output/daemon.json.txt`
+3. Copy the content exactly. Do not add markdown fences, comments, titles, or any extra bytes beyond the original text content.
+4. Upload the `.txt` compatibility copies instead of the unsupported originals.
+5. Upload already-supported text artifacts such as `.md`, `.txt`, and `.csv` directly.
+
+The final deliverable list should still point users to the original generated files. Mention the `.txt` files only as attachment-upload compatibility copies.
+
 If upload succeeds, report that the files are available from the file/attachment management entry. If upload fails because Agent attachment credentials are unavailable, preserve the local output files and report the upload failure separately.
 
 ---
@@ -325,7 +341,7 @@ After generation, perform language style checks on each output file:
 
 #### Step 5: Upload Generated Artifacts
 
-Upload all generated `.ae-cli/output/` artifacts to the Agent attachment library using `ae-cli agent +add-attachment --yes --files '<json-array>'`.
+Prepare upload compatibility copies for unsupported code/config extensions, then upload the safe file list to the Agent attachment library using `ae-cli agent +add-attachment --yes --files '<json-array>'`.
 
 ---
 

package/skills/ae-generate-tracking-plan/SKILL.md

@@ -82,7 +82,7 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > Determine `<user_lang>` from user's input language: Chinese→`zh`, English→`en`, Japanese→`ja`, Korean→`ko`. Other languages default to `en`.
 > All subsequent CLI commands must be prefixed with `AE_LANG=<user_lang>` to ensure CLI output and generated xlsx headers match the user's language.
 
-Collect the following **5 items** sequentially, **do NOT ask all at once**:
+Collect the following **4 items** sequentially, **do NOT ask all at once**:
 
 ### Item 1 — Application Scenario
 
@@ -94,14 +94,14 @@ After user responds, record to `meta.scenario` and generate `meta.plan_name`.
 
 Before asking, decide whether the current runtime is an agent sandbox. The agent may judge this from runtime context such as sandbox-provisioned `cli-token.json`, restricted filesystem access, or absence of the user's local files. Do not ask the user just to decide sandbox visibility.
 
-Product document and Codebase are local-material options. **Hide both options in sandbox environments**. When options are hidden, renumber the visible list contiguously from 1; never show skipped numbers.
+Product document is available in sandbox environments **only for files that are readable inside the sandbox workspace**, including files the user attaches/uploads into the conversation workspace. It cannot read arbitrary local paths outside the sandbox unless those files are mounted or attached. Codebase is a local-material option and must be hidden in sandbox environments unless the codebase is already present in the readable workspace. When options are hidden, renumber the visible list contiguously from 1; never show skipped numbers.
 
 If **not** in a sandbox environment, ask exactly:
 
 ```text
 Choose your source material (up to 2):
 
-1 - Product document (local path, image file, or folder; hidden in sandbox) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+1 - Product document (local path, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
 2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
 3 - Codebase (local project path; hidden in sandbox) — Analyze source code to extract events and properties
 4 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
@@ -114,22 +114,24 @@ If in a sandbox environment, ask exactly:
 ```text
 Choose your source material (up to 2):
 
-1 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
-2 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
+1 - Product document (sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp). You can attach/upload relevant files here.
+2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
+3 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
 
-Reply with number(s), e.g. 1 or 1,2. Select up to 2.
+Reply with number(s), e.g. 1 or 1,3. Select up to 2.
 ```
 
 Do not rewrite this source material list as unnumbered bullets, cards, or prose. The user must be able to reply with the visible numbers.
+When translating this prompt, preserve the numeric prefixes and line breaks exactly. Every visible option MUST be on its own line and MUST begin with `1 -`, `2 -`, `3 -`, etc. Never place two numbered options in the same paragraph or visual line. If a Markdown renderer may collapse soft line breaks, use Markdown hard line breaks (two trailing spaces before newline) rather than blank lines. Translation may change only the option text, not the numbering prefix or one-option-per-line structure.
 
 User can multi-select (max 2). Interpret numbers by the **visible list shown to the user**, not by the non-sandbox canonical list.
 
-Canonical source material options:
+Canonical source material options (non-sandbox numbering):
 
-- **Product document** (local path, image file, or folder; hidden in sandbox) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
-- **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
-- **Codebase** (local project path; hidden in sandbox) — Analyze source code to extract events and properties
-- **Pre-built template** (built-in industry and game genre templates) — Select a built-in template (run `AE_LANG=<user_lang> ae-cli tracking plan list-templates --json` to see available templates)
+1. **Product document** ****(****local path, sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+2. **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
+3. **Codebase** (local project path; hidden in sandbox) — Analyze source code to extract events and properties
+4. **Pre-built template** (built-in industry and game genre templates) — Select a built-in template (run `AE_LANG=<user_lang> ae-cli tracking plan list-templates --json` to see available templates)
 
 Based on user selection, determine source material type and record to `meta.source_type`:
 
@@ -142,7 +144,29 @@ Based on user selection, determine source material type and record to `meta.sour
 | Any two-item combo | Join two types with `_` | First as baseline, second as supplement (priority: template → codebase → prd → chat) |
 
 **Follow-up questions** (ask in selection order):
-- Product doc → ask **"What is the product document path? You can provide one or more paths, separated by commas or newlines (local paths, URLs, image files, or folders)"**
+- Product doc → if not in a sandbox environment, ask exactly:
+  ```text
+  What is the product document path?
+
+  You can provide one or more items, separated by commas or newlines:
+  1. Local file path
+  2. URL
+  3. Image file path
+  4. Folder path
+  ```
+- Product doc → if in a sandbox environment, ask exactly:
+  ```text
+  What is the product document path?
+
+  You can provide one or more items, separated by commas or newlines:
+  1. Sandbox workspace path
+  2. Uploaded attachment path
+  3. URL
+  4. Image file path
+  5. Folder path
+
+  You can also attach/upload relevant files here, and I will read them from the sandbox workspace if available.
+  ```
 - Detailed description → If too vague, follow up on core features, user behaviors, business flows, monetization
 - Codebase → ask **"What is the project directory path?"**, then scan source to extract business logic
 - Pre-built template → display matching templates for user confirmation

package/dist/chunk-OCQPQYHZ.js

@@ -1,105 +0,0 @@
-import {
-  getToken,
-  load,
-  loadCliToken,
-  save
-} from "./chunk-PFJFZVCK.js";
-import {
-  getActiveHost,
-  getFallbackCliToken,
-  listHosts,
-  logger,
-  safeJsonParse
-} from "./chunk-65DKFJZB.js";
-
-// src/core/cli-token.ts
-var CLI_TOKEN_GENERATE_PATH = "/v1/ta/cli/token/generate";
-var _cliTokenCache = /* @__PURE__ */ new Map();
-async function generateCliToken(hostUrl) {
-  const accessToken = await getToken(hostUrl);
-  const base = hostUrl.replace(/\/+$/, "");
-  const url = `${base}${CLI_TOKEN_GENERATE_PATH}`;
-  const resp = await fetch(url, {
-    method: "GET",
-    headers: {
-      "Authorization": `bearer ${accessToken}`
-    }
-  });
-  if (!resp.ok) {
-    throw new Error(`CLI token generate HTTP error: ${resp.status} ${resp.statusText}`);
-  }
-  const data = safeJsonParse(await resp.text());
-  if (data.return_code !== 0) {
-    throw new Error(`CLI token generate error: ${data.return_message || "unknown"} (code: ${data.return_code})`);
-  }
-  const cliToken = data.data?.userSecret;
-  if (!cliToken) {
-    throw new Error("CLI token generate error: empty userSecret in response");
-  }
-  return cliToken;
-}
-function persistCliTokenIfPossible(hostUrl, cliToken) {
-  const existing = load(hostUrl);
-  if (!existing) {
-    logger.info(`cli-token: no secure-store session for ${hostUrl}, keeping token in-process only`);
-    return;
-  }
-  save(hostUrl, { ...existing, cliToken });
-}
-function clearPersistedCliToken(hostUrl) {
-  const existing = load(hostUrl);
-  if (existing?.cliToken) {
-    save(hostUrl, { ...existing, cliToken: void 0 });
-  }
-}
-async function getCliToken(hostOverride) {
-  const hostUrl = hostOverride || getActiveHost();
-  const cached = _cliTokenCache.get(hostUrl);
-  if (cached) {
-    return cached;
-  }
-  const storedToken = loadCliToken(hostUrl);
-  if (storedToken) {
-    _cliTokenCache.set(hostUrl, storedToken);
-    logger.info(`Using persisted CLI token (secure-store) for ${hostUrl}`);
-    return storedToken;
-  }
-  const fallbackToken = getFallbackCliToken(hostUrl);
-  if (fallbackToken) {
-    _cliTokenCache.set(hostUrl, fallbackToken);
-    logger.info(`Using sandbox-provisioned CLI token (fallback file) for ${hostUrl}`);
-    return fallbackToken;
-  }
-  return mintCliToken(hostUrl);
-}
-async function mintCliToken(hostUrl) {
-  logger.info(`Generating CLI token for ${hostUrl}`);
-  const cliToken = await generateCliToken(hostUrl);
-  _cliTokenCache.set(hostUrl, cliToken);
-  persistCliTokenIfPossible(hostUrl, cliToken);
-  logger.info(`CLI token generated, cached, and persisted for ${hostUrl}`);
-  return cliToken;
-}
-function clearCliToken(hostUrl) {
-  if (hostUrl) {
-    _cliTokenCache.delete(hostUrl);
-    clearPersistedCliToken(hostUrl);
-    return;
-  }
-  _cliTokenCache.clear();
-  for (const { url } of listHosts()) {
-    clearPersistedCliToken(url);
-  }
-}
-function setCliTokenManual(token, hostUrl) {
-  _cliTokenCache.set(hostUrl, token);
-  persistCliTokenIfPossible(hostUrl, token);
-  logger.info(`CLI token set for ${hostUrl}`);
-}
-
-export {
-  getCliToken,
-  mintCliToken,
-  clearCliToken,
-  setCliTokenManual
-};

package/dist/cli-token-OZXHC3U2.js

@@ -1,14 +0,0 @@
-import {
-  clearCliToken,
-  getCliToken,
-  mintCliToken,
-  setCliTokenManual
-} from "./chunk-OCQPQYHZ.js";
-import "./chunk-PFJFZVCK.js";
-import "./chunk-65DKFJZB.js";
-export {
-  clearCliToken,
-  getCliToken,
-  mintCliToken,
-  setCliTokenManual
-};