@thinkingai/ae-cli 6.1.18 → 6.1.20

package/skills/ae-dataops/SKILL.md

@@ -20,6 +20,7 @@ The AE Data Development and Operations domain provides capabilities for data war
 | `dataops_flow` | Flow creation, node deletion, and orchestration | `dataops-flow-create` |
 | `dataops_flow` | Flow execution and monitoring | `dataops-flow-monitor` |
 | `dataops_operations` | Operations instance search, details, and task logs | `dataops-flow-monitor` |
+| `dataops_operations` | Backfill job creation, full draft update, deletion, execution, plans, stop, and rerun | `dataops-backfill` |
 | `dataops_ide` | Data exploration and SQL queries | `dataops-query` |
 | `dataops_integration` | Datasource and data integration | `dataops-integration` |
 
@@ -63,6 +64,7 @@ You must understand the following key concepts before use, otherwise errors are
 |----|--------|-------------|
 | **executeId** | Returned by `dataops_flow +execute_flow` | Early stop handle before the scheduler `flowInstanceId` is available |
 | **flowInstanceId** | Returned by `dataops_operations +search_flow_instances` | Operations perspective instance inspection and stop |
+| **jobId** | Returned by `dataops_operations +create_backfill_job` or `+search_backfill_jobs` | Persistent backfill job detail and lifecycle actions |
 
 ### Environment and Defaults
 
@@ -73,6 +75,8 @@ You must understand the following key concepts before use, otherwise errors are
 | `dataops_operations +get_flow_instance_detail` | Instance detail | Inspect one instance DAG and task statuses |
 | `dataops_operations +get_task_instance_detail` | Task detail/logs | Inspect one task and include logs only when needed |
 | `dataops_operations +stop_flow_instance` | Instance stop | Stop by exactly one of `executeId` or `flowInstanceId` |
+| `dataops_operations +list_backfill_flows` | Backfill source discovery | Returns eligible PROD flows and whether ST is required |
+| `dataops_operations +search_backfill_jobs` | Backfill job search | Filter persistent jobs and obtain `jobId` |
 
 ### Schema Naming Rules
 
@@ -92,6 +96,8 @@ You must understand the following key concepts before use, otherwise errors are
 Create DEV Flow → Create/Update DEV SQL, Integration, Workflow Instance Check, or Task Instance Check Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
 ```
 
+Backfill lifecycle: Discover eligible PROD flow → Create or fully update DRAFT job → Run explicitly → Search / inspect plans → Stop or rerun the complete job; delete only after target inspection
+
 ### CRON Format (6 fields)
 
 `second minute hour day month weekday` — Note: one more "second" field than standard 5-field format.
@@ -115,6 +121,7 @@ Choose the appropriate scenario skill based on user intent to get complete step-
 | Create flow, add or delete nodes, configure schedule, release | `dataops-flow-create` | create flow, new workflow, configure schedule, add task node, delete task node, release, cron, scheduled execution |
 | View execution status, troubleshoot failures, view logs | `dataops-flow-monitor` | execute flow, running instance, monitor, logs, stop, DAG, troubleshoot |
 | Search operation instances across a space | `dataops-flow-monitor` | operations instance, flow instance search, status statistics, owner statistics |
+| Create or operate a persistent multi-date backfill job | `dataops-backfill` | backfill, fill historical data, base date range, backfill plans, stop backfill, rerun backfill |
 | Create datasource, configure sync solution, execute sync | `dataops-integration` | datasource, sync, integration, field mapping, data ingestion, MySQL, ClickHouse, DatabricksJdbc |
 | Browse metadata, search tables, execute SQL queries | `dataops-query` | query, SQL, data exploration, search tables, view table structure, IDE, catalog, select |
 | Create tables and views | `dataops-table` | create table, table creation, view, data dictionary, table details, DDL |
@@ -155,13 +162,16 @@ Flow orchestration is divided into two scenario skills: **creation and configura
 
 **Lifecycle: DEV configuration and preview → Release to PROD → PROD manual execution and operations troubleshooting**
 
-Detailed creation/configuration commands live in [`references/dataops-flow-create.md`](references/dataops-flow-create.md). Detailed execution, monitoring, operation instance, task log, and stop commands live in [`references/dataops-flow-monitor.md`](references/dataops-flow-monitor.md).
+Detailed creation/configuration commands live in [`references/dataops-flow-create.md`](references/dataops-flow-create.md). Detailed execution, monitoring, operation instance, task log, and stop commands live in [`references/dataops-flow-monitor.md`](references/dataops-flow-monitor.md). Persistent multi-date backfill jobs live in [`references/dataops-backfill.md`](references/dataops-backfill.md).
 
 Key constraints:
 - Create and update tasks in DEV, preview/release before PROD execution.
 - Treat `+delete_task` as high-risk: verify the target with `+get_flow_overview`, preview with `--dry-run`, and use `--yes` only after explicit user confirmation. Deletion affects DEV; release the flow to apply it to PROD.
 - `+execute_flow` always runs PROD; it returns `executeId` for early stop.
 - Prefer `flowInstanceId` from operations search for stable inspection and troubleshooting.
+- A backfill job is persistent and batches multiple base dates; do not emulate it by looping `+execute_flow`.
+- Create and run backfill jobs as separate steps. `+rerun_backfill_job` reruns the complete job, not only failed plans.
+- `+update_backfill_job` replaces a DRAFT job's complete configuration; inspect the job first and do not treat it as a partial patch. Treat `+delete_backfill_job` as high-risk and preview it with `--dry-run` before confirmation.
 - Reference workspace parameters in task SQL as `${paramKey}`.
 
 ---

package/skills/ae-dataops/references/dataops-backfill.md

@@ -0,0 +1,135 @@
+---
+name: dataops-backfill
+version: 1.0.0
+description: "Backfill job lifecycle: discover eligible PROD flows, create or update drafts, delete jobs, run jobs, inspect plans, stop running jobs, and rerun complete jobs."
+metadata:
+  requires:
+    bins: ["ae-cli"]
+---
+
+# DataOps Backfill Jobs
+
+> **Prerequisites:** Read [`ae-dataops/SKILL.md`](../SKILL.md) for authentication, output, and safety rules.
+
+A backfill job is a persistent operations object that runs one PROD task flow for multiple base dates. It is not a single manual flow execution and is not a retry of an existing failed flow instance.
+
+## Lifecycle
+
+### 1. Discover an eligible PROD flow
+
+```bash
+ae-cli dataops_operations +list_backfill_flows --spaceCode "${spaceCode}"
+```
+
+Use only a returned flow whose `completeDataInfo.canRun` is true. When `completeDataInfo.hasSt` is true, pass `--stTime` while creating the job.
+
+### 2. Create a draft
+
+Always pass the backfill date range. For manual selection, also pass `--completeDates`; every selected date must be inside that inclusive range.
+
+```bash
+# Range mode
+ae-cli dataops_operations +create_backfill_job --spaceCode "${spaceCode}" \
+  --jobName "August backfill" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-07"
+
+# Custom-date mode
+ae-cli dataops_operations +create_backfill_job --spaceCode "${spaceCode}" \
+  --jobName "Selected dates" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-07" \
+  --completeDates '["2026-08-01","2026-08-03"]'
+```
+
+Creation returns a `DRAFT` job and does not run it. Defaults are `jobType=TASK_ALL`, `failureStrategy=END`, `parallel=true`, `reverse=false`, `step=1`, and `unit=DAY`. For `TASK_ONLY`, `TASK_PRE`, or `TASK_POST`, also pass `--startNode`.
+
+### 3. Update a draft when needed
+
+Update is a complete replacement, not a partial patch. Inspect the DRAFT job first, then pass `--jobId`, `--jobName`, `--flowCode`, and the complete date and strategy configuration just as for creation. Updating does not run the job.
+
+```bash
+ae-cli dataops_operations +update_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --jobName "Revised August backfill" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-10" \
+  --failureStrategy END --parallel true --reverse false
+```
+
+### 4. Run the draft explicitly
+
+```bash
+ae-cli dataops_operations +run_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+### 5. Search jobs and inspect plans
+
+```bash
+ae-cli dataops_operations +search_backfill_jobs --spaceCode "${spaceCode}" \
+  --status "RUNNING,FAIL,SUCCESS" --pageNum 1 --pageSize 20
+
+ae-cli dataops_operations +get_backfill_job_detail --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Detail returns the job and its plans together. A draft has an empty plan list.
+
+### 6. Stop, rerun, or delete
+
+Stopping affects every unfinished plan in the running job. Inspect the job, preview the request, obtain explicit confirmation, and then pass `--yes`.
+
+```bash
+ae-cli dataops_operations +stop_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+# After explicit confirmation, execute the same target; the CLI prompts before dispatch.
+ae-cli dataops_operations +stop_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Rerun applies to every plan only when the job is `FAIL` or `STOP`. A `SUCCESS` job cannot be rerun. Rerun reuses the same job and does not create a new backfill job. The CLI does not support rerunning only failed plans.
+
+```bash
+ae-cli dataops_operations +rerun_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+ae-cli dataops_operations +rerun_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Deletion is high-risk. The server accepts only supported `DRAFT`, `FAIL`, or `SUCCESS` jobs. Inspect the exact target and preview the scoped request before confirmation; the CLI sends only `spaceCode` and `jobId` and does not pre-query or guess state.
+
+```bash
+ae-cli dataops_operations +delete_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+ae-cli dataops_operations +delete_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+## Command Reference
+
+| Command | Purpose | Flags |
+|---|---|---|
+| `+list_backfill_flows` | List eligible PROD flows | `--spaceCode` |
+| `+create_backfill_job` | Create a draft | `--spaceCode` `--jobName` `--flowCode` `--startDate` `--endDate`; optional in-range `--completeDates`, scope, failure, parallel, order, and ST flags |
+| `+update_backfill_job` | Replace a DRAFT job's complete configuration | `--spaceCode` `--jobId` `--jobName` `--flowCode` and the same complete configuration as create |
+| `+delete_backfill_job` | Delete a supported job | `--spaceCode` `--jobId`; high-risk, requires confirmation or `--yes` |
+| `+run_backfill_job` | Run a draft | `--spaceCode` `--jobId` |
+| `+search_backfill_jobs` | Search jobs | `--spaceCode` plus optional keyword, date, type, status, owner, sort, and paging filters |
+| `+get_backfill_job_detail` | Get job and plans | `--spaceCode` `--jobId` |
+| `+stop_backfill_job` | Stop a running job | `--spaceCode` `--jobId`; high-risk, requires confirmation or `--yes` |
+| `+rerun_backfill_job` | Rerun the complete job | `--spaceCode` `--jobId` |
+
+Statuses are `DRAFT`, `RUNNING`, `STOP`, `FAIL`, `SUCCESS`, and `READY_STOP`. Range units are `DAY`, `WEEK`, and `MONTH`. Custom dates must be a non-empty JSON array of unique `yyyy-MM-dd` strings inside the configured date range.
+
+## Transport Status
+
+Transition status: transitional
+
+Owning module: Gaia operations
+
+Current transport: DataOps CLI REST
+
+Covered tools: `operations_list_backfill_flows`, `operations_create_backfill_job`, `operations_update_backfill_job`, `operations_delete_backfill_job`, `operations_run_backfill_job`, `operations_search_backfill_jobs`, `operations_get_backfill_job_detail`, `operations_stop_backfill_job`, and `operations_rerun_backfill_job`
+
+Gateway target: TBD after the DataOps operations Capability Gateway schema review
+
+Review after: 2026-11-20
+
+Exit condition: Migrate these commands after Gaia exposes equivalent capabilities and the command contract tests pass against the Capability Gateway transport.

package/skills/ae-engage/SKILL.md

@@ -398,6 +398,8 @@ When the user wants to "create a flow / generate a flow canvas / save a flow", d
 3. Build condition-related nodes with semantic `targetDefinitionRequest` and
    `triggerDefinition` objects. Resolve real event and property names through Analysis metadata;
    do not create an intermediate cluster merely to obtain persisted QP.
+   For `ab_split_flow` indicators, use `indicatorsDef[].eventDefinition`; always provide the
+   aggregate `operator`/`value` and every event-property filter's `operator`/`values`.
 
 4. Before building touchpoint nodes such as `message_push`, `wechat_push`, or `webhook_push`, you must call:
 
@@ -585,6 +587,9 @@ For task draft creation or update, use this workflow:
    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.
+   Select the audience by delivery side: server-side channels allow custom (`1`) or existing (`2`)
+   and reject all users (`3`); `client_push` (`channelType=3`) allows custom (`1`) or all users (`3`)
+   and rejects existing (`2`). Do not infer audience support from `triggerType` alone.
 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>`
 

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

@@ -36,12 +36,16 @@ compounds when reusing `definition_request`; flattening them changes audience se
 For the second sequence step, omit `relative_to_first` or set it to `false`; use `true` only
 from the third step onward when its window must be measured from step 1.
 
-For existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
+For server-side existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
 
 ```bash
 ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<cluster_name>"]'
 ```
 
+Server-side channels allow custom (`1`) or existing (`2`) audiences and reject all users (`3`).
+`client_push` (`channelType=3`) allows custom (`1`) or all users (`3`) and rejects existing (`2`).
+Always pass `channelType` in `context` so the guide can validate this matrix.
+
 4. Build the final grouped `save_task.req`.
 5. Submit with `ae-cli engage-task task save --project-id <projectId> --req '{...}'`.
 

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

@@ -305,9 +305,45 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 #### `ab_split_flow`
 
 ```json
-{ "branchList": [ { "branchId": "<branchId>", "branchName": "Control Group", "branchType": 1, "order": 1, "percentageInExperiment": 34 }, { "branchId": "<branchId>", "branchName": "Experiment Group A", "branchType": 2, "order": 2, "percentageInExperiment": 33 } ], "indicatorsDef": [], "activateIndicatorsDef": null }
+{
+  "branchList": [
+    { "branchId": "control", "branchName": "Control Group", "branchType": 1, "order": 1, "percentageInExperiment": 50 },
+    { "branchId": "experiment_a", "branchName": "Experiment Group A", "branchType": 2, "order": 2, "percentageInExperiment": 50 }
+  ],
+  "indicatorsDef": [
+    {
+      "indicatorsUuid": "metric_1",
+      "name": "Maximum payment amount",
+      "desc": "",
+      "completionIndicatorType": 0,
+      "touch_cycle_num": 1,
+      "touch_cycle_num_unit": "day",
+      "eventDefinition": {
+        "type": "event",
+        "event": "payment",
+        "aggregation": "max",
+        "property": "pay_amount",
+        "operator": "gt",
+        "value": 0,
+        "filters": {
+          "relation": "and",
+          "items": [
+            { "field": "gold", "operator": "gt", "values": [20] }
+          ]
+        }
+      }
+    }
+  ],
+  "activateIndicatorsDef": null
+}
 ```
 
+Use `eventDefinition` for new Capability requests. Its top-level `operator` compares the aggregate
+result with `value`; each `filters.items[].operator` compares an event property with its `values`.
+Both comparison levels are explicit and must not be omitted. Do not construct persisted fields such
+as `event`, `taPropQuota`, `uceCalcuSymbol`, `num`, `filts`, or `calcuSymbol`; Hermes compiles them.
+Legacy `event` remains accepted temporarily for older clients, but never send both fields.
+
 #### `event_judge`
 
 ```json

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

@@ -245,6 +245,12 @@ Use the guide to decide which audience shape applies:
 - `targetClusterType=2`: existing cluster, requires `clusterKey`
 - `targetClusterType=3`: all users, forbids `definitionRequest` and `clusterKey`
 
+Audience availability depends on delivery side:
+
+- Server-side channels support `targetClusterType=1` (custom) and `2` (existing), but not `3` (all users).
+- `client_push` (`channelType=3`) supports `targetClusterType=1` (custom) and `3` (all users), but not `2` (existing).
+- Determine the delivery side from the selected real channel; do not infer audience support from `triggerType` alone.
+
 For a custom audience, pass the semantic definition directly. Do not create an intermediate
 cluster or copy persisted QP.
 

package/skills/ae-experiment/SKILL.md

@@ -33,10 +33,14 @@ Naming and response boundary:
   `targeting.definition_request`. Never generate or submit `targetConfig`.
 - Metric QP is semantic at the CLI boundary: write `metricDefinition`; read
   `metric_definition`. Never generate or submit `metricConfig`, `calcType`, or `Axxx` codes.
+- Event-property comparisons belong in `metricDefinition.filters`, using
+  `{relation,items:[{field,operator,values}]}`. Never put comparison fields directly on
+  `metricDefinition`, and never submit raw `filts`, `calcuSymbol`, or `ftv` fields.
 - For metric aggregations `sum` / `avg` / `max` / `distinct_count`, `metricDefinition.property`
   is **required** and must be a concrete available event property from Analysis metadata.
   Never create property aggregations without `property` (for example `metric_avg_no_property_*`).
-- Event-count aggregations `total_count` / `user_count` / `active_days` omit `property`.
+- Preset event aggregations `total_count` / `user_count` / `active_days` omit `property`.
+- Experiment metric creation does not support `avg_per_user` / `A105`.
 - Resolve event and property names with Analysis metadata before saving semantic definitions.
 - Lists return `data.items` and `data.total`; detail commands return `data.item`.
 - Readiness returns `data.readiness`; reports return `data.report`; save guides return `data.guide`; save dry-run validation returns `data.validation`; writes return `data.result`.
@@ -72,7 +76,7 @@ If an experiment save returns `error_code: METRIC_NOT_FOUND`, list metrics for t
 ```bash
 ae-cli experiment experiment get --project-id 1 --exp-id exp_123
 ae-cli experiment experiment save --project-id 1 --req '{"expName":"Demo"}' --dry-run
-ae-cli experiment metric save --project-id 1 --req '{"metricId":"login_users","metricName":"Login users","createType":"event","goalDirection":"up","metricDesc":"Users who logged in","metricDefinition":{"type":"event","event":"login","aggregation":"user_count"}}' --dry-run
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_gold_sum","metricName":"Payment gold sum","createType":"event","goalDirection":"up","metricDesc":"Gold sum for payments above 10","metricDefinition":{"type":"event","event":"payment","aggregation":"sum","property":"gold","filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}}' --dry-run
 ae-cli experiment report metric-trend --project-id 1 --exp-id exp_123 --metric-id metric_1 --start-time 2026-07-01 --end-time 2026-07-07
 ```
 

package/skills/ae-experiment/references/save_metric.md

@@ -21,9 +21,13 @@ See [`save_build_guide.md`](save_build_guide.md) / [`save_validate.md`](save_val
 - Supply metric QP as `req.metricDefinition`.
 - Never submit internal `metricConfig`, `calcType`, or an `Axxx` calculation code.
 - Experiment metrics currently accept event definitions only.
+- Event-property comparisons belong in `metricDefinition.filters`. Each item uses
+  `field`, `operator`, and `values`; do not place `operator` or `value` directly on
+  `metricDefinition`.
 - Supported aggregations:
-  - Event-count (no property): `total_count`, `user_count`, `active_days`
+  - Preset event metrics (omit `property`): `total_count`, `user_count`, `active_days`
   - Property-based (**`property` REQUIRED**): `sum`, `avg`, `max`, `distinct_count`
+- `avg_per_user` (`A105`) is not supported for experiment metric creation.
 
 ### Property rule (mandatory)
 
@@ -38,6 +42,12 @@ When `aggregation` is `sum`, `avg`, `max`, or `distinct_count`:
 
 When `aggregation` is `total_count`, `user_count`, or `active_days`, omit `property`.
 
+### Preset event metric example (no property)
+
+```bash
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_users","metricName":"Payment users","createType":"event","goalDirection":"up","metricDesc":"Users who triggered payment","metricDefinition":{"type":"event","event":"payment","aggregation":"user_count"}}'
+```
+
 ### Correct example (avg with property)
 
 ```bash
@@ -51,7 +61,11 @@ ae-cli experiment metric save --project-id 1 --req '{
     "type":"event",
     "event":"payment",
     "aggregation":"avg",
-    "property":"amount"
+    "property":"amount",
+    "filters":{
+      "relation":"and",
+      "items":[{"field":"amount","operator":"gt","values":[10]}]
+    }
   }
 }'
 ```
@@ -69,11 +83,9 @@ ae-cli experiment metric save --project-id 1 --req '{
 }
 ```
 
-### Event-count example (no property)
+Filters use the semantic `filters` tree with `relation=and|or` and items containing
+`field`, `operator`, and `values`. For the frontend example `gold > 10`, use:
 
-```bash
-ae-cli experiment metric save --project-id 1 --req '{"metricId":"purchase_users","metricName":"Purchase users","createType":"event","goalDirection":"up","metricDesc":"Unique purchasers","metricDefinition":{"type":"event","event":"purchase","aggregation":"user_count"}}'
+```json
+{"filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}
 ```
-
-Filters use the semantic `filters` tree with `relation=and|or` and items containing
-`field`, `operator`, and `values`.

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

@@ -79,7 +79,7 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > CLI messages, and auto-track/i18n-owned labels must come from `src/tracking/i18n` via `AE_LANG=<user_lang>` and `draft.meta.lang`.
 > When a localized label is needed, inspect `src/tracking/i18n` and use the existing resource key/value; do not invent translations from the model.
 > If template business text needs localization and the CLI/i18n resources do not provide it, preserve the imported text and ask the user before rewriting business semantics.
-> Only identifier fields like `event_name`, `prop_name` remain in English snake_case (canonical format).
+> Only identifier fields like `event_name`, `prop_name` remain in English. Property names are `snake_case`; event names are lowercase by default, uppercase only when the user asks to preserve it.
 > This skill only cares about command behavior, not internal implementation.
 
 ---
@@ -111,7 +111,7 @@ 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) — 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/xlsx/pptx/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
@@ -126,7 +126,7 @@ If in a sandbox environment, ask exactly:
 ```text
 Choose your source material (up to 2):
 
-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.
+1 - Product document (sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/xlsx/pptx/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
 4 - Modify existing tracking plan (sandbox workspace path) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description, but NOT with Pre-built template
@@ -142,7 +142,7 @@ User can multi-select (max 2). Interpret numbers by the **visible list shown to
 
 Canonical source material options (non-sandbox numbering):
 
-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)
+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/xlsx/pptx/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)
@@ -210,7 +210,7 @@ Based on user selection, determine source material type and record to `meta.sour
    | Severity | Examples | Handling | User Action |
    |---|---|---|---|
    | 🔧 **Minor** (auto-fixable) | `display_name` duplicate, `array_row` sub-property inconsistency, event name duplicate | `--fix` auto-fixes, writes to `draft.json`. Inform user of what was fixed. | None (informed) |
-   | ⚠️ **Medium** (needs confirmation) | snake_case violation, property name duplicate, invalid property type, nested property parent is not a composite type | List each issue with current value → suggested fix. User confirms item by item before writing to `draft.json`. | Confirm each fix |
+   | ⚠️ **Medium** (needs confirmation) | property name snake_case violation, property name duplicate, invalid property type, nested property parent is not a composite type | List each issue with current value → suggested fix. User confirms item by item before writing to `draft.json`. | Confirm each fix |
    | 🛑 **Severe** | File cannot be parsed, or events array is empty after import | Reject. Tell user the specific issue. User fixes **original file** and re-imports. | Fix original file |
 
    **Medium issue confirmation format**:
@@ -219,7 +219,7 @@ Based on user selection, determine source material type and record to `meta.sour
 
    | # | Issue | Location | Current | Suggested |
    |---|-------|----------|---------|------------|
-   | 1 | snake_case | event_name | UserLogin | user_login |
+   | 1 | snake_case | event_name | UserLogin | user_login (keep UserLogin only if the user asked to preserve case) |
    | 2 | snake_case | prop_name | vipLevel | vip_level |
    | 3 | invalid type | property "level" | integer | number |
 
@@ -242,7 +242,7 @@ Based on user selection, determine source material type and record to `meta.sour
    - **Events**: Player interaction actions (click/swipe/trigger), scene transitions, game state changes (start/pause/end), business flow nodes (purchase/upgrade/unlock)
    - **Event Properties**: Action parameters (bullet type/enemy level/item ID), state values (score/HP/coins), context (level ID/difficulty/mode)
    - **User Properties**: Persistent state (level/experience/VIP/cumulative spend)
-5. Map extracted results to AE naming conventions (`snake_case` event names + `display_name` in user's language)
+5. Map extracted results to AE naming conventions (event names lowercase by default, uppercase only on request; property names `snake_case`; + `display_name` in user's language)
 6. Confirm extracted results with user, supplement missing items
 
 **Business Dimension Confirmation**:
@@ -386,7 +386,7 @@ When the user selects the **Data sample / file profile** option (`source_type =
 3. **Column → property mapping draft**:
    - Identify system columns first: time field, `distinct_id` / `account_id`, event-name column, user-property-name column.
    - Map the remaining columns to event properties / user properties / super properties.
-   - Naming: `snake_case` event/property names + `display_name` + `desc` + `event_tag` (language follows the user's input).
+   - Naming: `snake_case` property names, event names lowercase by default (uppercase only on request) + `display_name` + `desc` + `event_tag` (language follows the user's input).
    - Type inference: CSV columns default to `string`; infer `number` / `bool` / `datetime` / enum from field name + value distribution + business doc/prompt priors. **Uncertain or conflicting columns are marked "to-confirm" and asked only inside the gate** (do not ask column-by-column beforehand).
 4. **Single confirmation gate** (replaces Phase 2, see below).
 5. **Merge with existing plan** (reuse Phase 4.1/4.2 conflict detection).
@@ -656,7 +656,7 @@ Draft
 **Property types** (enum): `string` / `number` / `bool` / `datetime` /
 `object` (single object, with sub-properties) / `array_row` (object array, supports `parent.child` nesting) / `array_string` (string array)
 
-**Naming rules**: Event names / property names must be `snake_case`; use `display_name` field for human-readable names.
+**Naming rules**: Property names must be `snake_case`; event names are lowercase by default, and uppercase is kept only when the user asks to preserve it. Use `display_name` for human-readable names.
 
 ### 1.2 Merge Source Materials
 
@@ -674,9 +674,20 @@ Earlier sources take precedence — same-name events keep the earlier version, l
   - ⚠️ **No model-invented translations for template labels**: When replacing or explaining a localized template-owned label, use the exact value from `src/tracking/i18n` resources. If no corresponding resource exists, preserve the template text and ask the user before changing semantics.
   - ⚠️ **event_tag is not free-form model translation**: Do not manually map `业务事件`/`系统事件` to another language. Preserve template tags, or rely on `src/tracking/i18n` and autotrack generation for system labels when the CLI owns them.
 - **codebase**: Scan project source directory, extract events/properties from business logic; **same-name events merge prop_names without overwriting existing fields**; new items `source: "codebase"`
-- **prd**: Read all user-provided product documents (md / pdf / docx / URL / images), extract events and properties from each file; **same-name events merge prop_names without overwriting existing fields**; image files analyzed via multimodal interpretation of UI elements and interaction flows; all new items `source: "prd"`
+- **prd**: Read all user-provided product documents (md / pdf / docx / xlsx / pptx / URL / images), extract events and properties from each file; **same-name events merge prop_names without overwriting existing fields**; image files analyzed via multimodal interpretation of UI elements and interaction flows; all new items `source: "prd"`
+  - **Read each format with the table below.** Preferred tool first; when it is missing, fall back rather than fail the read.
+    | Format | Read via |
+    |---|---|
+    | md | read directly |
+    | docx | `pandoc -t markdown <file>`; fallback `markitdown <file>` (`pip install markitdown` if missing); last resort `unzip -p <file> word/document.xml` and read the text |
+    | pdf (text) | extract text (native Read or a PDF text extractor) |
+    | pdf (scanned) | render pages to images, then read with vision |
+    | xlsx | read rows/columns with a structure-preserving reader (`openpyxl` / `pandas`, `pip install` if missing); a tracking table's row/column layout carries meaning — do NOT rely on a flattened markdown dump |
+    | pptx | `markitdown <file>` (`pip install markitdown` if missing) |
+    | png/jpg/jpeg/webp | multimodal interpretation, analyze UI elements and interaction flows |
+  - **xlsx is a third source-material path, distinct from the two existing xlsx flows.** A human-readable tracking table (event / property / type rows) is read row-by-row here. An **AE-format tracking-plan xlsx** goes through `import-template`; a **CSV/Excel data sample** goes through the data path (`ae-cli data-integration inspect`). Never route one into another's flow.
   - **prd path is a folder**: Recursively scan all files in the directory:
-    - md/pdf/docx → read text content, extract events/properties
+    - md/pdf/docx/xlsx/pptx → read per the table above, extract events/properties
     - png/jpg/jpeg/webp → multimodal interpretation, analyze UI elements and interaction flows
     - subdirectories → recurse
     - other files → skip
@@ -817,7 +828,8 @@ AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae
 |---|---|---|
 | Display name uniqueness | Within same property pool, `display_name` must not repeat | ✅ Add distinguishing prefix |
 | Object array consistency | Same `array_row` across different events must have identical sub-properties | ✅ Fill missing sub-properties |
-| snake_case | Event/property names must match `^[a-z][a-z0-9_]*$` | ❌ Manual fix needed |
+| Property name snake_case | Property names must match `^[a-z][a-z0-9_]*$` | ❌ Manual fix needed |
+| Event name format | Event names match `^[A-Za-z][A-Za-z0-9_]*$`; lowercase by default, uppercase kept on request | ❌ Manual fix needed |
 | Property name uniqueness | Property names must not repeat | ❌ Manual fix needed |
 | Event name uniqueness | Event names must not repeat | ✅ Remove later duplicates |
 
@@ -1255,7 +1267,7 @@ Continue append (without fixing) / Modify draft / Switch to replace?
 
 #### Conflict Type B: Same-name events (advisory)
 
-AE merge-by-name: Same-name events are not overwritten; new-name events are added.
+AE merge-by-name: Same-name events are not overwritten; new-name events are added. Event names are case-sensitive (`Purchase` ≠ `purchase`) — changing only the case creates a new event, not a rename.
 
 **Detection logic**:
 

package/skills/ae-generate-tracking-plan/references/business-dimension-mapping.md

@@ -434,7 +434,7 @@
 
 - 必须有 ≥2 个自定义属性
 - 必须标注事件标签（模块归属）和采集端
-- 命名符合 snake_case
+- 命名符合 snake_case（事件名默认小写，用户要求保留大写时按用户要求）
 
 ---