@thinkingai/ae-cli 6.1.4 → 6.1.6

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

@@ -33,8 +33,9 @@ description: "Interactive generation of an AE tracking plan and upload. Trigger
 | 用户属性 | User Property | Property on the user profile (persistent state) |
 | 预置属性 | Preset Property | System property prefixed with `#` (`#device_id`, `#time`, etc.) |
 | 自动采集事件 | Auto-track Event | SDK auto-collected events (`ta_app_start`, `ta_page_show`, etc.) |
-| 系统事件 | System Event | Auto-track event tag category |
-| 业务事件 | Business Event | Custom business event tag category |
+| 系统事件 | System Event | event_tag value reserved for SDK auto-track events (`ta_*`). One of two non-module tags (together with 基础事件). |
+| 基础事件 | Basic | event_tag value for account-level lifecycle/progression events (register, login, level_up, create_role, etc.). Not tied to any functional module. |
+| 功能模块 | Functional Module | event_tag value for feature-specific business events; identifies which module the event belongs to (e.g. Battle, Shop, Ads, Payment, Basic) |
 | SDK 集成模式 | SDK Integration Mode | `client_only` / `server_only` / `both` / `none` |
 | 客户端平台 | Client Platform | Android, iOS, Web, Unity, Mini-program, etc. |
 | 服务端语言 | Server Language | Java, Python, Go, Node.js, PHP, etc. |
@@ -54,7 +55,7 @@ description: "Interactive generation of an AE tracking plan and upload. Trigger
 | xlsx 格式契约 | xlsx Format Contract | Column rules for AE-compatible Excel generation |
 | draft.json | draft.json | Internal intermediate representation (JSON) of the tracking plan |
 | display_name | Display Name | Human-readable name in the user's language |
-| event_tag | Event Tag | Category label for grouping events |
+| event_tag | Event Tag | Functional module the event belongs to (e.g. Battle, Shop, Ads, Payment). Auto-track events use "System Event". |
 | snake_case | snake_case | Canonical naming format: `lowercase_with_underscores` |
 
 ## When to Trigger
@@ -88,7 +89,7 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > 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.
 > When uploading the xlsx, pass `--lang <user_lang>` as well; it must match `draft.meta.lang` / the generated xlsx language.
 
-Collect the following **4 items** sequentially, **do NOT ask all at once**:
+Collect the following **5 items** sequentially, **do NOT ask all at once**:
 
 ### Item 1 — Application Scenario
 
@@ -111,8 +112,9 @@ Choose your source material (up to 2):
 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
+5 - Modify existing tracking plan (local AE format xlsx file) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description / Codebase, but NOT with Pre-built template
 
-Reply with number(s), e.g. 1 or 1,4. Select up to 2.
+Reply with number(s), e.g. 1,5 or 4. Select up to 2.
 ```
 
 If in a sandbox environment, ask exactly:
@@ -123,8 +125,9 @@ 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.
 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
 
-Reply with number(s), e.g. 1 or 1,3. Select up to 2.
+Reply with number(s), e.g. 1,4 or 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.
@@ -147,9 +150,11 @@ Based on user selection, determine source material type and record to `meta.sour
 | Description only | `chat` | Construct events in Draft phase based on description |
 | Codebase only | `codebase` | Scan source code, extract events/properties from business logic |
 | Template only | `template` | Provide built-in template selection |
-| Any two-item combo | Join two types with `_` | First as baseline, second as supplement (priority: template → codebase → prd → chat) |
+| Existing plan only | `existing_plan` | Import xlsx as baseline (see "Modify Existing Tracking Plan Flow" below) |
+| Any two-item combo | Join two types with `_` | First as baseline, second as supplement (priority: existing_plan → template → codebase → prd → chat) |
+| Existing plan + Pre-built template | **NOT allowed** | Both provide event baselines; semantic conflict |
 
-**Follow-up questions** (ask in selection order):
+**Follow-up questions** (ask in follow-up order defined in Multi-Source Combination Rules below):
 - Product doc → if not in a sandbox environment, ask exactly:
   ```text
   What is the product document path?
@@ -176,6 +181,49 @@ Based on user selection, determine source material type and record to `meta.sour
 - 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
+- Modify existing tracking plan → ask **"Please provide the xlsx file path of your existing tracking plan"**, then follow the flow below
+
+**Modify Existing Tracking Plan Flow** (when user selects this option):
+
+1. **Import**: Ask user for the file path, then immediately import:
+   ```bash
+   AE_LANG=<user_lang> ae-cli tracking code import-template --template <path> --out .ae-cli/draft.json
+   ```
+2. **Check result**:
+   - If CLI errors (file not found / parse failure) → report error, ask user to fix the file and retry
+   - If `draft.json` has `events` array empty → 🛑 **Severe: No AE-format sheets found** (missing `#` prefix sheets like `#事件数据`). Tell user the file does not appear to be an AE tracking plan xlsx. User must fix the original file and re-import.
+3. **Content validation** (when events are non-empty):
+   ```bash
+   AE_LANG=<user_lang> ae-cli tracking plan validate --in .ae-cli/draft.json --fix
+   ```
+4. **Handle validation results by severity**:
+   - If validate passes with **no issues at all** → skip to Step 5.
+
+   | 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 |
+   | 🛑 **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**:
+   ```
+   ⚠️ The following content needs to be fixed:
+
+   | # | Issue | Location | Current | Suggested |
+   |---|-------|----------|---------|------------|
+   | 1 | snake_case | event_name | UserLogin | user_login |
+   | 2 | snake_case | prop_name | vipLevel | vip_level |
+   | 3 | invalid type | property "level" | integer | number |
+
+   Apply all suggested fixes? ok / specify per item / skip
+   ```
+   - `ok` → apply all suggested fixes to `draft.json`
+   - `specify per item` → confirm each item one by one
+   - `skip` → keep current values, handle in Refine phase later
+
+   ⚠️ **Never modify the user's original xlsx file.** All changes go into `draft.json`.
+
+5. **Re-validate** after fixes → loop until clean, then continue to the next follow-up question (if combined with another source material), or Item 3 (if existing_plan is the only source).
 
 **Codebase analysis flow** (when source_type includes `codebase`):
 
@@ -196,9 +244,11 @@ After source material is confirmed, **must** process business dimension info bas
 | source_type | Handling |
 |---|---|
 | `template` | Directly display template's inherited business dimensions; skip detailed inference |
+| `existing_plan` | Infer business dimensions from existing plan content (analyze event modules, payment events, currency properties); follow up on missing items; event injection preview |
 | `prd` / `codebase` / `chat` | Infer business dimensions → follow up on missing items → event injection preview |
+| Combo (e.g. `template_prd`) | See detailed rules below — baseline source's method is primary, supplementary source contributes additional context |
 
-**If source_type = template**:
+**If source_type is template or starts with template_** (covers `template`, `template_prd`, `template_codebase`, `template_chat`):
 
 Display template's preset business dimensions:
 
@@ -215,6 +265,27 @@ Confirm using these business dimensions? ok / modify
 
 - User `ok` → proceed to next step
 - User says "modify" → switch to prd/chat flow for user to supplement
+- For combos (e.g. `template_prd`): after confirming template dimensions, also note any supplementary insights from `prd`/`chat` as context for Phase 1.2.
+
+**If source_type includes existing_plan**:
+
+Infer business dimensions from the imported plan content:
+
+1. **Analyze existing events**: Examine `event_tag` values to identify functional modules (e.g. events tagged "Battle" → 战斗 module). Examine event names for payment/ad-related patterns to infer revenue model.
+2. **Inference display**: Format inference results as a summary:
+   ```
+   Business Dimension (inferred from existing plan: <filename>)
+
+   Revenue Model: <inferred from payment/ad events>
+   Core Loop: <inferred from event flow>
+   Functional Entries: <inferred from event_tag values>
+   Currency System: <inferred from currency-related properties>
+
+   Confirm these business dimensions? ok / modify
+   ```
+3. **Follow up missing**: Only ask about items that could not be inferred
+4. **Event injection preview**: Show suggested injected event modules (only add events not already in the plan); user `ok` to proceed
+- For combos (e.g. `existing_plan_prd`): after confirming dimensions from the plan, also note any supplementary insights from `prd`/`chat` as context for Phase 1.2.
 
 **If source_type is prd / codebase / chat**:
 
@@ -224,7 +295,7 @@ Confirm using these business dimensions? ok / modify
 
 Platform validation: Use `business-dimension-mapping.md` Chapter 5 decision rules to check if injected events' platform assignments are reasonable.
 
-**Template matching** (prd / codebase / chat scenarios, optional):
+**Template matching** (prd / codebase / chat scenarios, optional; **NOT applicable to existing_plan or template scenarios**):
 
 After business dimension confirmation, auto-detect matching templates based on app type:
 ```bash
@@ -233,6 +304,51 @@ AE_LANG=<user_lang> ae-cli tracking plan list-templates --json
 
 Show matching templates to user for confirmation. Confirmed templates serve as baseline and participate in Phase 1 event merging.
 
+### Multi-Source Combination Rules (when user selects 2 source materials)
+
+**Follow-up Order** (Phase 0 questioning sequence):
+
+Do **not** follow user's selection order. Instead, use this order:
+
+```
+existing_plan（blocking validation, always first）→ codebase/prd（user's selection order）→ chat → template
+```
+
+Rationale:
+- `existing_plan` must go first — import + validate may require the user to fix their file; processing it early avoids wasted context
+- `codebase` / `prd` — directly reflect actual business requirements, prioritized over generic descriptions and templates
+- `chat` — conversational description, supplements business context
+- `template` — generic industry template, least specific to the user's business
+
+Source material processing happens primarily in Phase 1.2 (Merge Source Materials). The one exception is `existing_plan`: it is imported and validated in Phase 0 because user-provided files may need fixing before proceeding. All other sources are processed in Phase 1.2 per their standard flow.
+
+Merge priority (Phase 1.2): `existing_plan → template → codebase → prd → chat → autotrack`
+Earlier sources take precedence — same-name events keep the earlier version, later sources only add new events or merge `prop_names` without overwriting.
+
+**Business Dimension Inference (combined scenarios)**:
+
+Use the baseline source's inference method as primary. Supplementary sources (especially prd/chat) may contribute additional information — present a merged view for user confirmation.
+
+**Valid Combinations**:
+
+> The "Baseline" column identifies which source has higher merge priority (see Phase 1.2 merge order), which may differ from the user's selection order. Follow-up questioning uses the fixed order in "Multi-Source Combination Rules" above, not the user's selection order.
+
+| Baseline | Supplementary | Phase 0 for supplementary |
+|---|---|---|
+| existing_plan | codebase | Collect path + quick tech stack detection |
+| existing_plan | prd | Collect path |
+| existing_plan | chat | Collect description; participates in dimension inference |
+| template | codebase | Collect path + quick tech stack detection; template matching/import deferred to Phase 1.2 |
+| template | prd | Collect path; template matching/import deferred to Phase 1.2 |
+| template | chat | Collect description |
+| codebase | prd | Collect path |
+| codebase | chat | Collect description |
+| prd | chat | Collect description |
+| codebase | template | Same as template+codebase row above (template is baseline per merge priority) |
+| prd | template | Same as template+prd row above (template is baseline per merge priority) |
+
+**Forbidden**: `existing_plan + template` (both provide event baselines; semantic conflict).
+
 **Record business dimension info to `meta.business_dimension`**:
 ```json
 "business_dimension": {
@@ -493,8 +609,11 @@ Draft
 
 ### 1.2 Merge Source Materials
 
-Priority from low to high: **template → codebase → prd → chat → autotrack**
+Merge order: **existing_plan → template → codebase → prd → chat → autotrack**
 
+Earlier sources take precedence — same-name events keep the earlier version, later sources only add new events or merge `prop_names` without overwriting.
+
+- **existing_plan**: Already imported and validated in Phase 0 (see "Modify Existing Tracking Plan Flow"). Events are in draft.json as the baseline; each item marked `source: "existing_plan"`. Higher-priority sources supplement with new events only; same-name events keep the existing_plan version.
 - **template**: User-selected industry template (see "Template Lookup Convention" below) as baseline; each item marked `source: "template"`
   - Templates are resolved by ae-cli from the ae-cli package root and user template directory
   - Import command: `AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json`
@@ -657,6 +776,8 @@ AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae
 
 **Note**: Display names can be the same across different property pools (e.g. `vip_level` can be both an event property and a user property).
 
+> **Relationship to Phase 0 existing_plan validation**: The underlying rule engine is the same, but Phase 0 uses **interactive 3-tier** (Minor/Medium/Severe) because the user is present to confirm each fix. Phase 1.6 uses **batch 2-tier** (auto-fixable / manual-fix-needed) because it runs as part of the automated draft generation. Rules that are "Medium (needs confirmation)" in Phase 0 appear as "❌ Manual fix needed" here — the same rule, just without the interactive prompt.
+
 ### 1.7 Show Summary
 
 Display to user via markdown table: event count / event property pool size / super property count / user property count; show deliverable paths.

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

@@ -10,20 +10,20 @@
 
 ## 一、Revenue Model → Required Events
 
-| 收入模型 | 注入事件 | 事件显示名 | platform | 必带属性 |
-|---|---|---|---|---|
-| `IAA` | `ad_show` | 广告展示 | client | `ad_type`、`ad_placement`、`is_filled` |
-| `IAA` | `ad_click` | 广告点击 | client | `ad_type`、`ad_placement`、`ad_network` |
-| `IAA` | `ad_reward_get` | 激励广告奖励领取 | client | `ad_type`、`ad_placement`、`reward_type`、`reward_amount` |
-| `IAP` | `payment` | 支付成功 | server | `order_id`、`pay_amount`、`currency_type`、`payment_name`、`payment_type` |
-| `IAP` | `payment_fail` | 支付失败 | server | `order_id`、`fail_reason`、`payment_name` |
-| `mixed` | 同 IAA + IAP 所有事件 | | | |
-| `subscription` | `subscription_start` | 订阅开始 | server | `subscription_id`、`plan_name`、`start_time` |
-| `subscription` | `subscription_renew` | 订阅续费 | server | `subscription_id`、`renew_amount`、`currency_type` |
-| `subscription` | `subscription_cancel` | 订阅取消 | server | `subscription_id`、`cancel_time`、`cancel_reason` |
-| `commission` | `order_create` | 订单创建 | server | `order_id`、`order_amount`、`commission_rate` |
-| `commission` | `order_paid` | 订单支付 | server | `order_id`、`pay_amount`、`commission_amount` |
-| `commission` | `commission_settled` | 佣金结算 | server | `settlement_id`、`commission_amount`、`settle_time` |
+| 收入模型 | 注入事件 | 事件显示名 | event_tag | platform | 必带属性 |
+|---|---|---|---|---|---|
+| `IAA` | `ad_show` | 广告展示 | 广告 | client | `ad_type`、`ad_placement`、`is_filled` |
+| `IAA` | `ad_click` | 广告点击 | 广告 | client | `ad_type`、`ad_placement`、`ad_network` |
+| `IAA` | `ad_reward_get` | 激励广告奖励领取 | 广告 | client | `ad_type`、`ad_placement`、`reward_type`、`reward_amount` |
+| `IAP` | `payment` | 支付成功 | 支付 | server | `order_id`、`pay_amount`、`currency_type`、`payment_name`、`payment_type` |
+| `IAP` | `payment_fail` | 支付失败 | 支付 | server | `order_id`、`fail_reason`、`payment_name` |
+| `mixed` | 同 IAA + IAP 所有事件 | | | | |
+| `subscription` | `subscription_start` | 订阅开始 | 订阅 | server | `subscription_id`、`plan_name`、`start_time` |
+| `subscription` | `subscription_renew` | 订阅续费 | 订阅 | server | `subscription_id`、`renew_amount`、`currency_type` |
+| `subscription` | `subscription_cancel` | 订阅取消 | 订阅 | server | `subscription_id`、`cancel_time`、`cancel_reason` |
+| `commission` | `order_create` | 订单创建 | 交易 | server | `order_id`、`order_amount`、`commission_rate` |
+| `commission` | `order_paid` | 订单支付 | 交易 | server | `order_id`、`pay_amount`、`commission_amount` |
+| `commission` | `commission_settled` | 佣金结算 | 交易 | server | `settlement_id`、`commission_amount`、`settle_time` |
 
 ---
 
@@ -52,17 +52,19 @@
 **解析结果**：
 
 ```
-节点1: 刷关卡 → stage_start / stage_complete / stage_fail
-节点2: 获得金币 → token_get (token_type=gold, source=关卡)
-节点3: 抽卡 → gacha_draw (pool_type, draw_count)
-节点4: 获取角色 → hero_get (hero_id, hero_star)
+节点1: 刷关卡 → stage_start / stage_complete / stage_fail  [event_tag: 关卡/Stage]
+节点2: 获得金币 → token_get (token_type=gold, source=关卡)  [event_tag: 资源/Resource]
+节点3: 抽卡 → gacha_draw (pool_type, draw_count)  [event_tag: 抽卡/Gacha]
+节点4: 获取角色 → hero_get (hero_id, hero_star)  [event_tag: 养成/Growth]
 ```
 
 ---
 
 ## 三、功能入口 → 模块事件组
 
-| 功能入口 | 事件名 | 显示名 | platform | 典型属性 |
+> 第一列"模块"即该事件的 `event_tag` 值。注入时翻译为用户语言。
+
+| 模块 (event_tag) | 事件名 | 显示名 | platform | 典型属性 |
 |---|---|---|---|---|
 | 关卡 | `stage_start` | 关卡开始 | client | `stage_id`、`stage_type`、`difficulty` |
 | 关卡 | `stage_complete` | 关卡完成 | server | `stage_id`、`star_rating`、`score` |
@@ -200,26 +202,36 @@
 
 > 根据应用类型/游戏品类，自动注入对应模块的事件组。
 > 品类由 Phase 0 的 `meta.scenario` 或用户描述推断。
+>
+> **event_tag 规则**：本表中每行的"模块"列即该事件的 `event_tag` 值。注入时需翻译为用户语言。
+> 例如 战斗→`Battle`, 养成→`Growth`, 抽卡→`Gacha`, 资源→`Resource`, 广告→`Ads`, 支付→`Payment`。
 
-### 8.1 游戏类 — 通用基础模块（所有游戏必选）
+### 8.0 通用基础模块（所有品类适用）
+
+> 以下事件不属于任何具体功能模块（关卡/商城/抽卡等），统一使用 `基础事件`（Basic）标签。
+> 区别于 `系统事件`（System Event，SDK 自动采集的 `ta_*` 事件）。
 
 **用户生命周期**：
 
-| 事件名 | 显示名 | platform | 必带属性 |
-|---|---|---|---|
-| `new_device` | 设备激活 | client | `channel` |
-| `register` | 用户注册 | server | `register_type` |
-| `login` | 用户登录 | both | `account_id` |
-| `logout` | 用户登出 | both | `session_duration` |
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 基础事件 | `new_device` | 设备激活 | client | `channel` |
+| 基础事件 | `register` | 用户注册 | server | `register_type` |
+| 基础事件 | `login` | 用户登录 | both | `account_id` |
+| 基础事件 | `logout` | 用户登出 | both | `session_duration` |
 
 **成长模块**：
 
-| 事件名 | 显示名 | platform | 必带属性 |
-|---|---|---|---|
-| `create_role` | 创建角色 | server | `role_id`、`role_name`、`server_id` |
-| `guide_complete` | 完成新手引导 | client | `guide_id`、`guide_step` |
-| `level_up` | 升级 | server | `level`、`level_before` |
-| `vip_levelup` | VIP升级 | server | `vip_level` |
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 基础事件 | `create_role` | 创建角色 | server | `role_id`、`role_name`、`server_id` |
+| 基础事件 | `guide_complete` | 完成新手引导 | client | `guide_id`、`guide_step` |
+| 基础事件 | `level_up` | 升级 | server | `level`、`level_before` |
+| 基础事件 | `vip_levelup` | VIP升级 | server | `vip_level` |
+
+### 8.1 游戏类 — 通用基础模块（所有游戏必选）
+
+> 以下为游戏品类通用的基础事件，所有游戏品类均应包含。详见 8.0 通用基础模块。
 
 ### 8.2 游戏类 — 按品类
 
@@ -422,4 +434,57 @@
 
 - 必须有 ≥2 个自定义属性
 - 必须标注事件标签（模块归属）和采集端
-- 命名符合 snake_case
+- 命名符合 snake_case
+
+---
+
+## 附录：event_tag 多语言对照表
+
+> 生成 event_tag 时，根据用户语言从本表选取对应翻译。
+> 代码层（`src/xlsx/write.ts` 的 `CANONICAL_TAG`）也同步维护此表，用于 xlsx 输出时按业务重要性排序。
+
+| 中文 | English | 日本語 | 한국어 |
+|---|---|---|---|
+| 基础事件 | Basic | 基本イベント | 기본 이벤트 |
+| 系统事件 | System Event | システムイベント | 시스템 이벤트 |
+| 战斗 | Battle | 戦闘 | 전투 |
+| 关卡 | Stage | ステージ | 스테이지 |
+| 副本 | Dungeon | ダンジョン | 던전 |
+| 抽卡 | Gacha | ガチャ | 가챠 |
+| 养成 | Growth | 育成 | 육성 |
+| 资源 | Resource | リソース | 리소스 |
+| 广告 | Ads | 広告 | 광고 |
+| 支付 | Payment | 支払い | 결제 |
+| 订阅 | Subscription | サブスクリプション | 구독 |
+| 商城 | Shop | ショップ | 상점 |
+| 任务 | Quest | クエスト | 퀘스트 |
+| 成就 | Achievement | 実績 | 업적 |
+| 签到 | Check-in | チェックイン | 출석체크 |
+| 排行榜 | Leaderboard | ランキング | 리더보드 |
+| 公会 | Guild | ギルド | 길드 |
+| 社交 | Social | ソーシャル | 소셜 |
+| 建筑 | Building | 建築 | 건설 |
+| 联盟 | Alliance | 同盟 | 연맹 |
+| 装备 | Equipment | 装備 | 장비 |
+| 交易 | Trade | トレード | 거래 |
+| 复活 | Revive | 復活 | 부활 |
+| Slots | Slots | スロット | 슬롯 |
+| 抽奖 | Lottery | 抽選 | 추첨 |
+| 奖励 | Reward | 報酬 | 보상 |
+| 提现 | Withdraw | 引き出し | 출금 |
+| 发现 | Discovery | 発見 | 발견 |
+| 商品 | Product | 商品 | 상품 |
+| 订单 | Order | 注文 | 주문 |
+| 售后 | After-sales | アフターサービス | A/S |
+| 内容 | Content | コンテンツ | 콘텐츠 |
+| 互动 | Interaction | インタラクション | 인터랙션 |
+| 关系 | Relationship | 関係 | 관계 |
+| 直播 | Live | ライブ | 라이브 |
+| 引导 | Onboarding | オンボーディング | 온보딩 |
+| 课程 | Course | コース | 코스 |
+| 报名 | Enrollment | 申し込み | 신청 |
+| 测验 | Quiz | クイズ | 퀴즈 |
+| 创作 | Creation | 創作 | 창작 |
+| 素材 | Material | 素材 | 소재 |
+| 导出 | Export | エクスポート | 내보내기 |
+| 内容播放 | Playback | 再生 | 재생 |

package/skills/ae-generate-tracking-plan/references/xlsx-schema.md

@@ -95,20 +95,22 @@ A-E 在 writer 里用 `mergeCells` 合并。
 
 ## 类型枚举
 
-### PropType（xlsx 中文值 ↔ canonical）
-
-| canonical（draft.json） | xlsx 写入值 | xlsx 读取可接受值（含行业 alias） |
-|---|---|---|
-| `string` | `文本` | `文本` / `字符串` |
-| `number` | `数值` | `数值` |
-| `bool` | `布尔` | `布尔` |
-| `datetime` | `时间` | `时间` |
-| `object` | `对象` | `对象` |
-| `array_row` | `对象组` | `对象组` |
-| `array_string` | `列表` | `列表` |
-
-Writer 方向统一用第二列（官方中文正式名），不输出 alias。
-Reader 方向对 alias / 未知值做 fallback 并打 stderr warning。
+### PropType（canonical ↔ 各语言显示值）
+
+> Writer 按 `draft.meta.lang` 输出对应语言列的值。
+
+| canonical（draft.json） | zh | en | ja | ko | 读取额外兼容（alias） |
+|---|---|---|---|---|---|
+| `string` | `文本` | `String` | `ストリング` | `String` | `字符串` / `string` / `文字列` / `テキスト` / `텍스트` / `문자열` |
+| `number` | `数值` | `Number` | `数値` | `Number` | `number` / `숫자` |
+| `bool` | `布尔` | `Boolean` | `ブール値` | `Boolean` | `boolean` / `Bool` / `ブール` / `부울` |
+| `datetime` | `时间` | `Date` | `時間` | `Date` | `datetime` / `DateTime` / `Time` / `日時` / `날짜시간` / `time` |
+| `object` | `对象` | `Row` | `オブジェクト` | `Row` | `object` / `Object` |
+| `array_row` | `对象组` | `Array Row` | `オブジェクトグループ` | `Array Row` | `object[]` / `Object Array` / `オブジェクト配列` / `object_array` / `객체 배열` |
+| `array_string` | `列表` | `List` | `リスト` | `List` | `string[]` / `String Array` / `配列` / `string_array` / `리스트` |
+
+> 旧值兼容（2026-07-15 前生成的 xlsx）：`en` 旧值 `string`/`number`/`boolean`/`datetime`/`object`/`object[]`/`string[]`，
+> `ja` 旧值 `オブジェクト配列`/`配列`，`ko` 旧值 `time`/`object_array`/`string_array` 在 reader 中仍可识别。
 
 ### UpdateType（用户属性 `更新方式`）
 

package/skills/ae-kb/SKILL.md

@@ -19,8 +19,9 @@ ae-cli kb +<command> [options]
 - Prefer `--dry-run` before destructive or broad writes when the user has not already validated the target.
 - Do not invent knowledge base names, scopes, source display names, or JSON payloads. Ask the user or query known context when values are missing.
 - JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.
-- Successful commands return JSON by default. Use `--format table` only when a table is easier for a human to scan.
+- Successful commands return JSON by default. Use `--format table` only when a table is easier for a human to scan. Envelope may include optional `_notice.host_compat`.
 - `--host <url>` overrides the active AE host. It is available on every command and may be placed after the subcommand, e.g. `ae-cli kb +<command> --host <url>`.
+- **CRITICAL — Host compat (do this first):** After each `ae-cli` run, check stderr and `_notice.host_compat`. If either is present, open the user reply with a short ⚠️ version warning and **quote the `npm i -g` / `npx skills add` (or update-cluster) lines verbatim**, then present the business result. Soft tip; `ok: true` can still carry the notice.
 - For external-agent retrieval, prefer the deterministic flow `+index` -> `+grep` -> `+read`: inspect navigation, locate candidate pages, then open the exact page or line window. Use `+ask` only when the user wants an LLM-synthesized answer and accepts token consumption.
 
 ## Commands
@@ -124,15 +125,17 @@ ae-cli kb +status --name engineering-handbook
 
 ### Query Knowledge
 
-Use `+query` with a natural-language question and a JSON array of source refs.
+Use `+query` with a natural-language question. Optionally scope to specific knowledge bases or tune result count and locale.
 
 ```bash
 ae-cli kb +query \
   --query "How do we release a dashboard?" \
-  --sources '[{"scope":"company","name":"engineering-handbook"}]'
+  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
+  --top-k 10 \
+  --locale zh
 ```
 
-`--sources` entries require:
+When `--sources` is provided, each entry requires:
 
 - `scope`: knowledge base scope such as `personal` or `company`.
 - `name`: knowledge base name.
@@ -233,11 +236,13 @@ ae-cli kb +remove --name engineering-handbook
 ### `+query`
 
 ```bash
-ae-cli kb +query --query "<question>" --sources '[{"scope":"company","name":"kb-name"}]'
+ae-cli kb +query --query "<question>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--top-k 10] [--locale zh|en|ja|ko]
 ```
 
 - `--query`, alias `-q`: required natural-language question.
-- `--sources`: required JSON array of knowledge base refs.
+- `--sources`: optional JSON array of knowledge base refs. Omit to search all accessible knowledge bases.
+- `--top-k`: optional max number of hits, 1-50, default 10.
+- `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
 
 ### `+ask`
 

package/skills/ae-metadata/SKILL.md

@@ -21,8 +21,9 @@ Parallel to **`ae-analysis`** (MCP `analysis_meta` for metadata lists/governance
 | `--dry-run` | Optional: confirm ready to run (`/dry-run`). Alone for risk/output preview. Do not stack with `--validate`. |
 
 Output and errors:
-- Success: JSON envelope (default).
+- Success: JSON envelope (default). May include optional `_notice.host_compat`.
 - Failure: `{ "ok": false, "error": { "type", "message", "hint" } }`, non-zero exit.
+- **CRITICAL — Host compat (do this first):** After each `ae-cli` run, check stderr and `_notice.host_compat`. If either is present, open the user reply with a short ⚠️ version warning and **quote the `npm i -g` / `npx skills add` (or update-cluster) lines verbatim**, then present the business result. Soft tip; `ok: true` can still carry the notice.
 
 Safety:
 - Read-only commands can run directly after IDs/names are verified.

package/skills/ae-team/SKILL.md

@@ -25,8 +25,9 @@ Global parameters:
 | `--dry-run` | Show request details without executing. |
 
 Output and errors:
-- Successful commands return machine-readable JSON by default.
+- Successful commands return machine-readable JSON by default. Envelope may include optional `_notice.host_compat`.
 - Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
+- **CRITICAL — Host compat (do this first):** If stderr or `_notice.host_compat` has a version warning, open the user reply with ⚠️ and **quote `npm i -g` / `npx skills add` (or update-cluster) lines verbatim**, then list projects/results. Never omit when summarizing. Soft tip; `ok: true` may still include the notice.
 
 Safety constraints:
 - Read commands (`+list`, `+list-templates`, `+list-projects`, `+run-result`, `+run-artifacts`, `+ai-generate`) can execute directly once required IDs are known.

package/dist/chunk-NOO24N7W.js

@@ -1,11 +0,0 @@
-// src/core/errors.ts
-var PermissionError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "PermissionError";
-  }
-};
-
-export {
-  PermissionError
-};