@thinkingai/ae-cli 6.0.31 → 6.0.32

package/skills/ae-engage/references/scene-config-item.md

@@ -0,0 +1,68 @@
+# engage-scene config-item
+
+> Capability ids: `engage-scene.config-item.{list,create,update}` · Domain: `engage`.
+
+场景管理 / 配置中心 - 配置项管理。
+
+## Commands
+
+```bash
+# List config items of a project
+ae-cli engage-scene config-item list --project-id <project_id>
+
+# Create a config item (business type, group, optional avatar)
+ae-cli engage-scene config-item create \
+  --project-id <project_id> --config-id <config_id> --config-name <name> \
+  --business-type <config_file|params> \
+  [--config-remark <remark>] [--group-id <group_id>] \
+  [--avatar-word '["A"]'] [--file-name icon.png] [--file-content "$(base64 -i icon.png)"]
+
+# Update a config item's basic info and bound channel
+ae-cli engage-scene config-item update \
+  --project-id <project_id> --config-id <config_id> \
+  [--config-name <name>] [--config-remark <remark>] [--business-type <type>] \
+  [--group-id <group_id>] [--channel-id <channel_id>]
+```
+
+## Parameters
+
+### list
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+
+### create
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID (unique within the project). |
+| `--config-name` | Yes | Config item display name (<=80 chars). |
+| `--business-type` | Yes | Business type: `config_file` or `params`. |
+| `--config-remark` | No | Remark (<=200 chars). |
+| `--group-id` | No | Group ID (0 = default group). |
+| `--avatar-word` | No | JSON array of avatar words for the icon. |
+| `--file-name` | No | Avatar file name including extension. |
+| `--file-content` | No | Base64-encoded avatar file content. |
+
+### update
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID to update. |
+| `--config-name` | No | New display name. |
+| `--config-remark` | No | New remark. |
+| `--business-type` | No | New business type. |
+| `--group-id` | No | New group ID. |
+| `--channel-id` | No | Config channel ID to bind. |
+
+## Output
+
+- `list`: `data.items` + `data.total`.
+- `create` / `update`: `data.success` — whether the operation succeeded.
+
+## Decision Rules
+
+- `create` / `update` are `write`; `list` is read. Use `config-item list` (or `engage +config_item_list`) to discover real `config_id`s and group IDs; never invent IDs.

package/skills/ae-engage/references/scene-config-metric.md

@@ -0,0 +1,79 @@
+# engage-scene config-metric
+
+> Capability ids: `engage-scene.config-metric.{list,get,batch-add,update-rule,batch-delete}` · Domain: `engage`.
+
+场景管理 / 配置中心 - 配置项关联指标管理。
+
+## Commands
+
+```bash
+# List related metrics of a config item (optionally include preset metrics)
+ae-cli engage-scene config-metric list --project-id <project_id> --config-id <config_id> [--all-metric]
+
+# Get a related metric's detail
+ae-cli engage-scene config-metric get --project-id <project_id> --metric-id <metric_id>
+
+# Batch-relate TA (event-analysis) metrics to a config item
+ae-cli engage-scene config-metric batch-add --project-id <project_id> --config-id <config_id> --ta-metric-ids '[1,2]'
+
+# Update a config metric's event relation rule
+ae-cli engage-scene config-metric update-rule \
+  --project-id <project_id> --metric-id <metric_id> \
+  --event-list '[{"event_name":"e1","filter":"true"}]'
+
+# Batch-remove related metrics (high-risk)
+ae-cli engage-scene config-metric batch-delete --project-id <project_id> --config-id <config_id> --metric-ids '[1,2]' --yes
+```
+
+## Parameters
+
+### list
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID. |
+| `--all-metric` | No | Include preset metrics as well. |
+
+### get
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--metric-id` | Yes | Config metric primary ID. |
+
+### batch-add
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID. |
+| `--ta-metric-ids` | Yes | JSON array of TA metric IDs. |
+
+### update-rule
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--metric-id` | Yes | Config metric primary ID. |
+| `--event-list` | Yes | JSON array of event rules (`event_name` or `eventName`, plus `filter`). |
+
+### batch-delete
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID. |
+| `--metric-ids` | Yes | JSON array of config metric primary IDs. |
+
+## Output
+
+- `list`: `data.items` + `data.total`.
+- `get`: `data` — metric detail.
+- `batch-add` / `update-rule`: `data.success`.
+- `batch-delete`: `data.success`.
+
+## Decision Rules
+
+- Discover real metric IDs via `list`/`get`; never invent IDs.
+- `batch-delete` is `high-risk-write` and requires `--yes`.

package/skills/ae-engage/references/scene-config-param.md

@@ -0,0 +1,72 @@
+# engage-scene config-param
+
+> Capability ids: `engage-scene.config-param.{list,batch-add,update,batch-delete}` · Domain: `engage`.
+
+场景管理 / 配置中心 - 配置项参数管理。
+
+## Commands
+
+```bash
+# List params of a config item
+ae-cli engage-scene config-param list --project-id <project_id> --config-id <config_id>
+
+# Batch-add params to a config item
+ae-cli engage-scene config-param batch-add \
+  --project-id <project_id> --config-id <config_id> \
+  --params '[{"param_name":"title","param_display_name":"标题","param_type":"STRING","param_sub_type":"SHORT_TEXT","is_required":1}]'
+
+# Update a param
+ae-cli engage-scene config-param update \
+  --project-id <project_id> --config-id <config_id> --param-id <param_id> \
+  [--param-name <name>] [--param-display-name <name>] [--param-type <type>] \
+  [--param-sub-type <sub>] [--table-id <table_id>] [--param-placeholder <ph>] \
+  [--is-required 1] [--default-value <value>]
+
+# Batch-delete params (high-risk)
+ae-cli engage-scene config-param batch-delete --project-id <project_id> --param-ids '[1,2]' --yes
+```
+
+## Parameters
+
+### list
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID. |
+
+### batch-add
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID. |
+| `--params` | Yes | JSON array of params (`param_name`, `param_display_name`, `param_type`, `param_sub_type`, `table_id`, `param_placeholder`, `is_required`, `default_value`). `param_type` must be uppercase enum: `STRING`, `NUM`, `DATE`, `DATE_TIME`, `BOOLEAN`, `OBJ`, `SINGLE_SELECT`, `ARRAY`, `JSON`. For `STRING`/`ARRAY`, `param_sub_type` is required (e.g. `SHORT_TEXT`, `LONG_TEXT`, `NUM`). For `SINGLE_SELECT`, `table_id` is required. **`param_display_name` must be unique within the config item** — duplicate display names return `INVALID_CAPABILITY_REQUEST`. |
+
+### update
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID. |
+| `--param-id` | Yes | Param ID to update. |
+| others | No | See flag descriptions above. |
+
+### batch-delete
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--param-ids` | Yes | JSON array of param IDs. |
+
+## Output
+
+- `list`: `data.items` + `data.total`.
+- `batch-add` / `update`: `data.success`.
+- `batch-delete`: `data.success_num` + `data.fail_list` (looped single deletes; non-atomic).
+
+## Decision Rules
+
+- Use `list` to discover real `param_id`s before update/delete; never invent IDs.
+- `param_type` is case-sensitive; lowercase values like `"string"` are rejected with `PARAM_TYPE_INVALID`.
+- `batch-delete` is `high-risk-write` and requires `--yes`.

package/skills/ae-engage/references/scene-preset-metric.md

@@ -0,0 +1,45 @@
+# engage-scene preset-metric
+
+> Capability ids: `engage-scene.preset-metric.{get,set}` · Domain: `engage`.
+
+场景管理 / 配置中心 - 配置项预置指标（曝光/点击/参与）QP 配置。
+
+## Commands
+
+```bash
+# Get preset metric QP config of a config item
+ae-cli engage-scene preset-metric get --project-id <project_id> --config-id <config_id>
+
+# Set preset metric QP config
+ae-cli engage-scene preset-metric set \
+  --project-id <project_id> --config-id <config_id> \
+  [--impression-event-qp '<qp json>'] [--click-event-qp '<qp json>'] [--attend-event-qp '<qp json>']
+```
+
+## Parameters
+
+### get
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID. |
+
+### set
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--config-id` | Yes | Config item ID. |
+| `--impression-event-qp` | No | Impression event QP JSON string. |
+| `--click-event-qp` | No | Click event QP JSON string. |
+| `--attend-event-qp` | No | Attend event QP JSON string. |
+
+## Output
+
+- `get`: `data` — preset metric QP config.
+- `set`: `data.success` — whether the operation succeeded.
+
+## Decision Rules
+
+- `get` is read; `set` is `write`.

package/skills/ae-engage/references/scene-strategy.md

@@ -0,0 +1,47 @@
+# engage-scene strategy
+
+> Capability ids: `engage-scene.strategy.{create,update,log,batch-copy}` · Domain: `engage`.
+
+场景管理 / 配置中心 - 配置项策略管理。create/update 使用 `--payload` 直传后端 DTO（原生 camelCase 结构），`project_id` 会注入 payload。
+
+## Commands
+
+```bash
+# Create a config strategy (draft)
+ae-cli engage-scene strategy create --project-id <project_id> \
+  --payload '{"configId":"cfg-1","templateId":"tpl-1","strategyName":"s1", ...}'
+
+# Update a config strategy
+ae-cli engage-scene strategy update --project-id <project_id> \
+  --payload '{"strategyUuid":"uuid-1","strategyName":"s2", ...}'
+
+# Query a strategy's log
+ae-cli engage-scene strategy log --project-id <project_id> --strategy-uuid <uuid>
+
+# Batch-copy strategies
+ae-cli engage-scene strategy batch-copy --project-id <project_id> --config-id <config_id> \
+  --strategy-ids '["s1","s2"]' [--op-mode batch]
+```
+
+## Parameters
+
+| Command | Required flags | Notes |
+|---|---|---|
+| create | `--project-id`, `--payload` | payload = `ConfigStrategyAddDTO`. |
+| update | `--project-id`, `--payload` | payload = `ConfigStrategyModifyDTO` (`strategyUuid` + fields). |
+| log | `--project-id`, `--strategy-uuid` | read. |
+| batch-copy | `--project-id`, `--config-id`, `--strategy-ids` | `--op-mode` optional (default `batch`). |
+
+## Output
+
+- `create`: `data.strategy_uuid`.
+- `update`: `data.success`.
+- `log`: `data.log`.
+- `batch-copy`: `data.result`.
+
+## Decision Rules
+
+- Discover real strategy UUIDs / config IDs first; never invent IDs.
+- **`create` requires an enabled template** on the same config item. Enable workflow: `config-param batch-add` → `template create` → `template update` (non-empty `config[]` with real `paramId`) → `template update-status --status 1`. Otherwise `create` returns `TEMPLATE_ENABLE`.
+- `create` output field is `data.strategy_uuid` (not `strategy_id`).
+- Save-and-submit and strategy test-send are not exposed via `engage-scene` CLI; use legacy `engage +manage_strategy` or the product UI.

package/skills/ae-engage/references/scene-template.md

@@ -0,0 +1,71 @@
+# engage-scene template
+
+> Capability ids: `engage-scene.template.{list,get,create,update,update-status,delete}` · Domain: `engage`.
+
+场景管理 / 配置中心 - 配置项模板管理。create/update 使用 `--payload` 直传后端 DTO（原生 camelCase 结构），`project_id` 会注入 payload。
+
+## Commands
+
+```bash
+# List templates of a config item
+ae-cli engage-scene template list --project-id <project_id> --config-id <config_id>
+
+# Get a template's detail
+ae-cli engage-scene template get --project-id <project_id> --config-id <config_id> --template-id <template_id>
+
+# Create a template
+ae-cli engage-scene template create --project-id <project_id> \
+  --payload '{"configId":"cfg-1","templateId":"tpl-1","templateName":"t1","remark":""}'
+
+# Update a template (bind config-item params into template.config — required before enable)
+ae-cli engage-scene template update --project-id <project_id> \
+  --payload '{
+    "configId":"cfg-1",
+    "templateId":"tpl-1",
+    "templateName":"t1",
+    "config":[{
+      "paramId":48,
+      "paramName":"title",
+      "paramDisplayName":"标题",
+      "paramType":"STRING",
+      "paramSubType":"SHORT_TEXT",
+      "isRequired":1,
+      "defaultValue":"hello"
+    }]
+  }'
+
+# Enable / disable a template (only after config[] is non-empty)
+ae-cli engage-scene template update-status \
+  --project-id <project_id> --config-id <config_id> --template-id <template_id> --status <1|0>
+
+# Delete a template (high-risk)
+ae-cli engage-scene template delete --project-id <project_id> --config-id <config_id> --template-id <template_id> --yes
+```
+
+## Parameters
+
+| Command | Required flags | Notes |
+|---|---|---|
+| list | `--project-id`, `--config-id` | read. |
+| get | `--project-id`, `--config-id`, `--template-id` | read. |
+| create | `--project-id`, `--payload` | payload = `ConfigTemplateAddDTO`. |
+| update | `--project-id`, `--payload` | payload = `ConfigTemplateModifyDTO`. |
+| update-status | `--project-id`, `--config-id`, `--template-id`, `--status` | status 1 enable / 0 disable. |
+| delete | `--project-id`, `--config-id`, `--template-id` | high-risk. |
+
+`template update-status --validate` and `--dry-run` perform the same read-only business preflight as execution. They reject incomplete template fields, missing dependency configuration, unsupported status transitions, and status values other than `0` or `1` before any template state is changed.
+
+## Output
+
+- `list`: `data.items` + `data.total`.
+- `get`: `data.template`.
+- `create` / `update` / `update-status` / `delete`: `data.success`.
+
+## Decision Rules
+
+- `delete` is `high-risk-write`; requires `--yes` and does not support dry-run.
+- Discover real template IDs with `list`/`get` first; never invent IDs.
+- **`create` requires `templateId` in payload** (unique within config item, <=80 chars), not only `templateName`.
+- **Enable workflow:** (1) `config-param batch-add` on the config item → (2) `template create` → (3) **`template update` with non-empty `config[]`** referencing real `paramId` values from `config-param list` → (4) `template update-status --status 1`. Skipping step 3 returns `TEMPLATE_FIELDS_INCOMPLETE`.
+- Enabling a template is a prerequisite for `strategy create` on the same config (`TEMPLATE_ENABLE` if template disabled).
+- Template test-send is not exposed via `engage-scene` CLI; use the product UI.

package/skills/ae-engage/references/{ops-delete.md → task-delete.md}

@@ -1,11 +1,11 @@
-# engage-task ops delete
+# engage-task task delete
 
 Delete an engagement task. High-risk write; requires `--yes` to skip confirmation.
 
-> Capability id: `engage-task.ops.delete` · Domain: `engage`.
+> Capability id: `engage-task.task.delete` · Domain: `engage`.
 
 ```bash
-ae-cli engage-task ops delete --project-id <project-id> --task-id <task-id> --yes
+ae-cli engage-task task delete --project-id <project-id> --task-id <task-id> --yes
 ```
 
 ## Parameters

package/skills/ae-engage/references/whitelist.md

@@ -0,0 +1,72 @@
+# engage-setting whitelist
+
+> Capability ids: `engage-setting.whitelist.{add,update,delete,verify}` · Domain: `engage`.
+
+## Commands
+
+```bash
+# Add whitelist entries
+ae-cli engage-setting whitelist add \
+  --project-id <project_id> --prop-code <prop_code> --column-name <column_name> \
+  --column-type <column_type> \
+  --whitelist-list '[{"entity_id":"u1","source_value":"v1","note_name":"n"}]'
+
+# Update a whitelist entry's note name
+ae-cli engage-setting whitelist update --project-id <project_id> --whitelist-id <id> --note-name <name>
+
+# Delete whitelist entries (high-risk)
+ae-cli engage-setting whitelist delete --project-id <project_id> --whitelist-ids '["wl-1","wl-2"]' --yes
+
+# Verify property values against the whitelist
+ae-cli engage-setting whitelist verify \
+  --project-id <project_id> --prop-code <prop_code> --column-type <column_type> \
+  --whitelist-prop-list '["v1","v2"]'
+```
+
+## Parameters
+
+### add
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--prop-code` | Yes | Associated user property code. |
+| `--column-name` | Yes | Associated user property field name. |
+| `--column-type` | Yes | Associated user property field type. |
+| `--whitelist-list` | Yes | JSON array of entries (`entity_id`, `source_value`, `note_name`). |
+
+### update
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--whitelist-id` | Yes | Whitelist entry ID to modify. |
+| `--note-name` | No | New note name. |
+
+### delete
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--whitelist-ids` | Yes | JSON array of whitelist entry IDs. |
+
+### verify
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--prop-code` | Yes | Associated user property code. |
+| `--column-type` | Yes | Associated user property field type. |
+| `--whitelist-prop-list` | Yes | JSON array of property values to verify. |
+
+## Output
+
+- `add`: `data.success_num` — number of entries successfully added.
+- `update` / `delete`: `data.success` — whether the operation succeeded.
+- `verify`: `data.items` (verified entries with `entity_id`, `source_value`, `note_name`, `fail_msg`) and `data.total`.
+
+## Decision Rules
+
+- Use these commands when the user asks to add / edit / delete / verify project whitelist entries.
+- Discover existing whitelist IDs with `ae-cli engage +whitelist_list --project_id <project_id>` first; never invent IDs.
+- `delete` is `high-risk-write` and requires `--yes` (or interactive confirmation).

package/skills/ae-engage/references/workbench-workbench.md

@@ -0,0 +1,48 @@
+# engage-workbench workbench
+
+> Capability ids: `engage-workbench.workbench.{list,add,update,delete}` · Domain: `engage`.
+
+工作台 - 工作台指标卡槽（workbench slot）管理。每个用户在每个项目下最多 4 个指标卡；卡槽按当前登录用户隔离，`update`/`delete` 只能操作本人卡槽。首次 `list` 会自动初始化 4 个默认卡槽。
+
+## Commands
+
+```bash
+# List the current user's workbench metric slots
+ae-cli engage-workbench workbench list --project-id <project_id>
+
+# Add a metric slot (metric + date range + order)
+ae-cli engage-workbench workbench add --project-id <project_id> \
+  --metric-type <metric_type> --date-type <date_type> [--order-id <1-4>]
+
+# Update a slot (own slot only)
+ae-cli engage-workbench workbench update --project-id <project_id> \
+  --slot-id <slot_id> --metric-type <metric_type> --date-type <date_type> [--order-id <1-4>]
+
+# Delete a slot (own slot only, high-risk)
+ae-cli engage-workbench workbench delete --project-id <project_id> --slot-id <slot_id> --yes
+```
+
+## Parameters
+
+| Command | Required flags | Notes |
+|---|---|---|
+| list | `--project-id` / `-p` | read; auto-inits 4 defaults on first access. |
+| add | `--project-id`, `--metric-type`, `--date-type` | write; `--order-id` optional (1-4); max 4 slots. |
+| update | `--project-id`, `--slot-id`, `--metric-type`, `--date-type` | write; own slot only; `--order-id` optional. |
+| delete | `--project-id`, `--slot-id` | high-risk; requires `--yes`; no dry-run; soft-delete. |
+
+- `--metric-type`: `WorkbenchSlotMetricTypeEnum` code (1-12), e.g. 1=PLAN, 2=PUSH_SUCCESS_PERSON, 5=NEW_USER_COUNT.
+- `--date-type`: `WorkbenchSlotDateTypeEnum` code (1-13), e.g. 8=LAST_7_DAYS, 10=LAST_30_DAYS, 11=CURRENT.
+
+## Output
+
+- `list`: `data.slots` (array of slot cards: `slot_id`, `metric_code`, `metric_name`, `date_code`, `date_name`, `value`, `order_id`, `status`, ...).
+- `add` / `update`: `data.slot` (the created/updated slot card).
+- `delete`: `data.success`.
+
+## Decision Rules
+
+- Discover real `slot_id` via `list` first; never invent slot IDs.
+- The same `(metric_type, date_type)` combination cannot be added twice for the same user+project.
+- `add` fails once the user already has 4 slots; remove one with `delete` first.
+- `delete` is `high-risk-write`; it requires `--yes` and does not support dry-run.

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

@@ -9,7 +9,8 @@ description: "Interactive generation of an AE tracking plan and upload. Trigger
 > English input → English reply; Chinese input → Chinese reply; Japanese input → Japanese reply.
 > If uncertain, default to English.
 > This applies to all output: section titles, phase names, template prompts, example text, option lists, etc.
-> **⚠️ CRITICAL: Template localization is CLI-owned. Do NOT manually translate imported template content with the model. Use the `src/tracking` i18n pipeline by setting `AE_LANG=<user_lang>`, writing `draft.meta.lang`, and regenerating through `ae-cli tracking code import-template` / `ae-cli tracking plan draft`.**
+> **⚠️ CRITICAL: Template localization is CLI-owned. Do NOT manually translate imported template content with the model. Use the `src/tracking/i18n` module as the source of truth by setting `AE_LANG=<user_lang>`, writing `draft.meta.lang`, and regenerating through `ae-cli tracking code import-template` / `ae-cli tracking plan draft`.**
+> **Before changing any template-owned localized label, first look up the corresponding translation in `src/tracking/i18n` (for example `resources/xlsx/sheets.ts`, `resources/xlsx/headers.ts`, `resources/xlsx/types.ts`, and `resources/cli/*.json`). If no matching translation exists there, preserve the imported text and ask before rewriting business semantics.**
 > Do NOT copy Chinese text verbatim from this document into English/Japanese replies unless it is an identifier, template name needed for CLI import, or original source material quoted for traceability.
 
 ## Terminology Glossary
@@ -72,6 +73,7 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > property `display_name`, property `desc`, etc.) should be generated in the **user's input language**.
 > For imported templates, do NOT translate those fields manually. Template sheet names, headers, property type display values,
 > 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).
 > This skill only cares about command behavior, not internal implementation.
@@ -498,8 +500,9 @@ Priority from low to high: **template → codebase → prd → chat → autotrac
   - Import command: `AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json`
   - ⚠️ **Must validate immediately after template import** (see Phase 1.6); template content may not be fully correct
   - ⚠️ **Do not manually translate template content after import**: Do NOT read draft.json and model-translate `display_name`, `event_desc`, `event_tag`, or property `display_name`/`desc`. Keep imported business content as produced by the CLI/template reader unless the user explicitly asks for semantic rewriting.
-  - ⚠️ **Use `src/tracking` i18n for localization owned by the CLI**: `AE_LANG=<user_lang>` + `draft.meta.lang` control CLI messages, xlsx sheet names, xlsx headers, property type display values, and auto-track/i18n-owned labels. If these are wrong, regenerate with the intended locale instead of editing labels by hand.
-  - ⚠️ **event_tag is not free-form model translation**: Do not manually map `业务事件`/`系统事件` to another language. Preserve template tags, or rely on `src/tracking` i18n/autotrack generation for system labels when the CLI owns them.
+  - ⚠️ **Use `src/tracking/i18n` for localization owned by the CLI**: `AE_LANG=<user_lang>` + `draft.meta.lang` control CLI messages, xlsx sheet names, xlsx headers, property type display values, and auto-track/i18n-owned labels. If these are wrong, inspect the existing translations under `src/tracking/i18n`, then regenerate with the intended locale instead of editing labels by hand.
+  - ⚠️ **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 path is a folder**: Recursively scan all files in the directory:
@@ -673,7 +676,7 @@ Run the following command to dynamically discover available templates:
 AE_LANG=<user_lang> ae-cli tracking plan list-templates --json
 ```
 
-**Language rules**: Template names and template business content must not be model-translated. Use localized names only when they are returned by the CLI / `src/tracking` i18n resources. If `list-templates --json` only returns the original template `name`, display that name as-is and keep it unchanged for import.
+**Language rules**: Template names and template business content must not be model-translated. Use localized names only when they are returned by the CLI or found in `src/tracking/i18n` resources. If `list-templates --json` only returns the original template `name`, display that name as-is and keep it unchanged for import. Before presenting or modifying any localized template-owned label, look it up in `src/tracking/i18n`; do not invent a translation.
 
 Built-in templates are resolved by ae-cli from the ae-cli package root. User templates are resolved from the ae-cli user template directory. Do **not** manually construct `./tracking-plan-template/...` paths from the user's current workspace.
 
@@ -1116,7 +1119,7 @@ AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae
 - **With `--replace`**: Delete existing project plan first then upload (when user chooses "Replace", or severe conflict switches to replace)
 - **Without `--replace`**: AE merge-by-name merge (no conflicts, or advisory only with user confirmation to append)
 
-Upload language is controlled locally by `AE_LANG`, `--lang`, or `draft.meta.lang`. Do not call AE user language config APIs and do not use `--switch-lang`. If the xlsx language is wrong, regenerate the xlsx with the intended language before uploading:
+Upload commands MUST pass `--lang <user_lang>` explicitly. `--lang` must match the generated xlsx language and `draft.meta.lang`; `AE_LANG` is only used for CLI messages and xlsx regeneration context. Do not call AE user language config APIs and do not use `--switch-lang`. If the xlsx language is wrong, regenerate the xlsx with the intended language before uploading:
 ```bash
 AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx
 AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]

package/skills/ae-generate-tracking-plan/references/te-api.md

@@ -99,7 +99,7 @@ Upload is a two-step capability-gateway flow:
 { "project_id": 1603, "input_file_id": "...", "lang": "zh" }
 ```
 
-- `lang` is optional for backward compatibility, but Agents should pass the generated xlsx language (`zh` / `en` / `ja` / `ko`) so the backend resolves localized sheet names and headers consistently.
+- Agents MUST pass `lang` with the generated xlsx language (`zh` / `en` / `ja` / `ko`) so the backend resolves localized sheet names and headers consistently.
 - Response: `{ return_code: 0, return_message: "success" }` on success.
 
 **合并语义**：对事件走 **merge-by-name**（同名不覆盖、新名新增）。若要完全替换，