@thinkingai/ae-cli 6.0.20 → 6.0.22

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

@@ -1,181 +1,64 @@
-# AE Plan Query API (captured 2026-04-15)
+# AE Plan Query Capability API
 
-## Endpoint
+This reference is for `ae-cli` maintainers. Skill users should call CLI commands, not backend APIs.
 
-- **Method**: GET
-- **URL**: `https://web-ta-demo.thinkingdata.cn/v1/ta/bury/manage/program/query?@t={timestamp}&projectId={projectId}`
-- **Auth**: header `authorization: bearer {token}` — token value read from `localStorage['ACCESS_TOKEN']` (JSON-encoded string) on the AE web app, also cached in `~/.ae-cli/tokens.json`
-- **Additional required headers**:
-  - `x-requested-with: XMLHttpRequest`
-  - `accept: application/json`
-- **Request body**: none (GET)
+The code-generation skill reads the current tracking plan through the capability gateway. The CLI
+must not call the legacy common-service tracking-program URL directly.
 
-### URL parameters
+## Authentication
 
-| Param | Required | Notes |
-|---|---|---|
-| `@t` | yes (de-facto) | Unix timestamp ms — cache-buster; the server likely accepts any value |
-| `projectId` | yes | AE project ID, e.g. `1603` |
+- Header: `cli-token: <token>`
+- Do not send `authorization: bearer ...`.
+- Do not read `ACCESS_TOKEN` from browser localStorage.
 
----
+## Query Capability
 
-## Response shape (truncated to 2 events / 2 props each)
+- Capability: `track.program.query`
+- Method: `POST`
+- URL: `/api/cli/analysis/v1/capabilities/track.program.query/execute`
+- Input:
+
+```json
+{ "project_id": 1603 }
+```
+
+## Response Shape
+
+The gateway response keeps the standard AE envelope:
 
 ```json
 {
   "return_code": 0,
-  "return_message": "ok",
+  "return_message": "success",
   "showStackMessage": null,
   "data": {
     "projectId": 1603,
-    "createTime": "2026-04-15 15:45:17",
-
-    "events": [
-      {
-        "eventName": "admin_skill_review",
-        "displayName": "管理员审核",
-        "eventDesc": "管理员通过/驳回/归档 skill",
-        "eventTag": "admin",
-        "creator": "周津",
-        "createTime": "2026-04-15 15:45:17",
-        "lastUpdateAuth": "周津",
-        "lastUpdateTime": "2026-04-15 15:45:17",
-        "hasReported": false,
-        "props": ["review_action", "review_reason", "skill_id", "skill_name"],
-        "propInfosOnEvent": [
-          { "name": "review_action", "hasReported": false },
-          { "name": "review_reason", "hasReported": false }
-        ]
-      },
-      {
-        "eventName": "page_view",
-        "displayName": "页面浏览",
-        "eventDesc": "任意页面打开",
-        "eventTag": "common",
-        "creator": "周津",
-        "createTime": "2026-04-15 15:45:17",
-        "lastUpdateAuth": "周津",
-        "lastUpdateTime": "2026-04-15 15:45:17",
-        "hasReported": false
-        // props / propInfosOnEvent absent when event has no bound properties
-      }
-    ],
-
-    "eventProps": [
-      {
-        "name": "login_method",
-        "displayName": "登录方式",
-        "type": "string",
-        "desc": "feishu_sso",
-        "creator": "周津",
-        "createTime": "2026-04-15 15:45:17",
-        "lastUpdateAuth": "周津",
-        "lastUpdateTime": "2026-04-15 15:45:17"
-        // NOTE: no hasReported field on eventProps items
-      },
-      {
-        "name": "session_duration_ms",
-        "displayName": "会话时长毫秒",
-        "type": "number",
-        "desc": "登出时本次会话累计时长",
-        "creator": "周津",
-        "createTime": "2026-04-15 15:45:17",
-        "lastUpdateAuth": "周津",
-        "lastUpdateTime": "2026-04-15 15:45:17"
-      }
-    ],
-
-    "commonEventProps": [
-      {
-        "name": "is_embed",
-        "displayName": "是否嵌入模式",
-        "type": "bool",
-        "desc": "是否在 CRM iframe 嵌入中访问",
-        "creator": "周津",
-        "createTime": "2026-04-15 15:45:17",
-        "lastUpdateAuth": "周津",
-        "lastUpdateTime": "2026-04-15 15:45:17",
-        "hasReported": false
-      },
-      {
-        "name": "page_name",
-        "displayName": "页面名称",
-        "type": "string",
-        "desc": "当前页面标识，如 home/submit/detail/admin",
-        "creator": "周津",
-        "createTime": "2026-04-15 15:45:17",
-        "lastUpdateAuth": "周津",
-        "lastUpdateTime": "2026-04-15 15:45:17",
-        "hasReported": false
-      }
-    ],
-
-    "userProps": [
-      {
-        "name": "admin_review_count",
-        "displayName": "审核处理数",
-        "type": "number",
-        "desc": "管理员累计审核的 skill 数",
-        "updateType": "user_add",
-        "updateTypeName": "user_add",
-        "propTag": "",
-        "creator": "周津",
-        "createTime": "2026-04-15 15:45:17",
-        "lastUpdateAuth": "周津",
-        "lastUpdateTime": "2026-04-15 15:45:17",
-        "hasReported": false
-      }
-    ]
+    "events": [],
+    "eventProps": [],
+    "commonEventProps": [],
+    "userProps": []
   }
 }
 ```
 
----
-
-## Field mapping to Draft
-
-The planned `normalize()` function assumes `data.event_properties[]`, `data.common_event_properties[]`, `data.user_properties[]`. **Reality differs** — see caveats below.
-
-| AE response field | Draft field (src/plan/types.ts) | Notes |
-|---|---|---|
-| `data.events[].eventName` | `events[].event_name` | camelCase → snake_case |
-| `data.events[].displayName` | `events[].display_name` | camelCase → snake_case |
-| `data.events[].eventDesc` | `events[].event_desc` | camelCase → snake_case |
-| `data.events[].eventTag` | `events[].event_tag` | camelCase → snake_case |
-| `data.events[].props[]` | `events[].properties[]` | array of property name strings |
-| `data.events[].propInfosOnEvent[]` | `events[].property_infos[]` | array of `{name, hasReported}` |
-| `data.eventProps[].name` | `event_properties[].name` | key rename: `eventProps` → `event_properties` |
-| `data.eventProps[].type` | `event_properties[].type` | same |
-| `data.eventProps[].displayName` | `event_properties[].display_name` | camelCase → snake_case |
-| `data.eventProps[].desc` | `event_properties[].description` | key rename |
-| `data.commonEventProps[].name` | `common_event_properties[].name` | key rename: `commonEventProps` → `common_event_properties` |
-| `data.userProps[].name` | `user_properties[].name` | key rename: `userProps` → `user_properties` |
-| `data.userProps[].updateType` | `user_properties[].update_type` | user property specific |
-| `data.userProps[].propTag` | `user_properties[].prop_tag` | user property specific |
-| `return_code` | — | top-level; `0` = success |
-| `return_message` | — | top-level; `"ok"` on success |
-
----
-
-## Caveats
-
-1. **Key naming is camelCase throughout** — all field names in the response use camelCase (`eventName`, `displayName`, `eventProps`, etc.). The draft plan assumed snake_case keys like `event_name`. `normalize()` must do a full camelCase → snake_case conversion, or map fields explicitly.
-
-2. **Array key name mismatches vs plan assumption**:
-   - Response uses `eventProps` (not `event_properties`)
-   - Response uses `commonEventProps` (not `common_event_properties`)
-   - Response uses `userProps` (not `user_properties`)
-
-3. **`eventProps` are global, not scoped per event** — all event properties live in one flat `data.eventProps[]` array. Per-event bindings are in `data.events[].props` (name strings) and `data.events[].propInfosOnEvent` (`{name, hasReported}` objects). Events with no bound properties omit both `props` and `propInfosOnEvent` fields entirely.
-
-4. **`hasReported` field inconsistency** — `commonEventProps` and `userProps` items include `hasReported`; `eventProps` items do NOT include this field.
-
-5. **`@t` cache-buster** — the `@t` query param is a Unix timestamp in milliseconds. It appears to be required (the page always sends it) but likely just busts CDN/proxy caching. Use `Date.now()` when constructing requests.
-
-6. **No pagination observed** — the single request returns all 17 events, 21 event props, 6 common props, 9 user props in one shot. No pagination headers or page/limit params were observed.
-
-7. **`userProps[].updateType` and `updateTypeName`** — both fields are present on user properties (e.g., `"user_add"`). The xlsx schema's `更新方式` column maps to this.
-
-8. **`propTag`** — present on `userProps` items (maps to xlsx `属性标签` column), absent on event/common props.
-
-9. **`eventProps` lack `hasReported`** — unlike events and common/user props, individual event property definitions in `eventProps[]` do not carry `hasReported`. The flag does appear inside `propInfosOnEvent[]` on the event object itself.
+The CLI normalizes the capability output before converting it to the tracking draft shape.
+
+## Field Mapping to Draft
+
+| AE response field | Draft field |
+|---|---|
+| `data.events[].eventName` | `events[].event_name` |
+| `data.events[].displayName` | `events[].display_name` |
+| `data.events[].eventDesc` | `events[].event_desc` |
+| `data.events[].eventTag` | `events[].event_tag` |
+| `data.events[].props[]` | `events[].properties[]` |
+| `data.events[].propInfosOnEvent[]` | `events[].property_infos[]` |
+| `data.eventProps[].name` | `event_properties[].name` |
+| `data.eventProps[].displayName` | `event_properties[].display_name` |
+| `data.eventProps[].desc` | `event_properties[].description` |
+| `data.commonEventProps[].name` | `common_event_properties[].name` |
+| `data.userProps[].name` | `user_properties[].name` |
+| `data.userProps[].updateType` | `user_properties[].update_type` |
+| `data.userProps[].propTag` | `user_properties[].prop_tag` |
+
+Empty projects may return a success envelope without `data`; treat that as an empty plan.

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

@@ -92,14 +92,44 @@ After user responds, record to `meta.scenario` and generate `meta.plan_name`.
 
 ### Item 2 — Source Material + Business Dimension (combined)
 
-Ask: **"Choose your source material (up to 2):"**
+Before asking, decide whether the current runtime is an agent sandbox. The agent may judge this from runtime context such as sandbox-provisioned `cli-token.json`, restricted filesystem access, or absence of the user's local files. Do not ask the user just to decide sandbox visibility.
 
-User can multi-select (max 2):
+Product document and Codebase are local-material options. **Hide both options in sandbox environments**. When options are hidden, renumber the visible list contiguously from 1; never show skipped numbers.
 
-1. **Product document** (local path, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
-2. **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
-3. **Codebase** (local project path) — 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` to see available templates)
+If **not** in a sandbox environment, ask exactly:
+
+```text
+Choose your source material (up to 2):
+
+1 - Product document (local path, image file, or folder; hidden in sandbox) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+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
+
+Reply with number(s), e.g. 1 or 1,4. Select up to 2.
+```
+
+If in a sandbox environment, ask exactly:
+
+```text
+Choose your source material (up to 2):
+
+1 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
+2 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
+
+Reply with number(s), e.g. 1 or 1,2. 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.
+
+User can multi-select (max 2). Interpret numbers by the **visible list shown to the user**, not by the non-sandbox canonical list.
+
+Canonical source material options:
+
+- **Product document** (local path, image file, or folder; hidden in sandbox) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+- **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
+- **Codebase** (local project path; hidden in sandbox) — Analyze source code to extract events and properties
+- **Pre-built template** (built-in industry and game genre templates) — Select a built-in template (run `AE_LANG=<user_lang> ae-cli tracking plan list-templates --json` to see available templates)
 
 Based on user selection, determine source material type and record to `meta.source_type`:
 
@@ -168,7 +198,7 @@ Platform validation: Use `business-dimension-mapping.md` Chapter 5 decision rule
 
 After business dimension confirmation, auto-detect matching templates based on app type:
 ```bash
-AE_LANG=<user_lang> ae-cli tracking plan list-templates
+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.
@@ -189,6 +219,8 @@ Show matching templates to user for confirmation. Confirmed templates serve as b
 
 Ask: **"What is your client platform? (multi-select OK, e.g. Android + iOS) Will you integrate a server-side SDK?"**
 
+After asking this Item 3 question, **stop and wait for the user's answer**. Do not display Item 4 in the same response.
+
 > **Language filter**: The following SDKs have Chinese-only documentation and are **visible to Chinese users only**: `Mini-program`, `Mini-game`, `OpenHarmony`, `LayaAir`, `Egret`, `Cocos2d-Lua`. Do not show these to non-Chinese users.
 
 **Client integration** (multi-select OK):
@@ -270,6 +302,14 @@ Record to `client_platform_languages`:
 
 `none` mode: Suitable for historical data import, batch data sync, third-party system integration, etc. Refine phase does not inject SDK auto-track events.
 
+**Item 3 confirmation gate**:
+
+After the user answers Item 3, normalize the SDK configuration and ask only the missing follow-up questions (for Android/iOS programming language or `Other` server language).
+
+Then summarize the normalized SDK config and ask: **"Confirm this SDK integration config? Reply ok to continue to Item 4, or describe changes."**
+
+Do not display Item 4 or ask identity questions until the user explicitly confirms this SDK integration config.
+
 ### Item 4 — User Identity System (visitor ID + account ID combined)
 
 Ask: **"What is the visitor ID generation strategy?"**
@@ -426,8 +466,8 @@ Draft
 Priority from low to high: **template → codebase → prd → chat → autotrack**
 
 - **template**: User-selected industry template (see "Template Lookup Convention" below) as baseline; each item marked `source: "template"`
-  - Templates prefer `.md` distilled files (`tracking-plan-template/*.md`), fall back to `.xlsx`
-  - Import command: `AE_LANG=<user_lang> ae-cli tracking code import-template --template <path> --out .ae-cli/draft.json`
+  - 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`
   - ⚠️ **Must validate immediately after template import** (see Phase 1.6); template content may not be fully correct
   - ⚠️ **Template content is in Chinese; must translate after import**: Read draft.json, translate `display_name`, `event_desc`, `event_tag`, and property `display_name`/`desc` to user's language, then write back. Only `event_name`, property `name`, `type` identifiers remain as-is.
   - ⚠️ **event_tag also needs translation**: `业务事件`→user's language (e.g. EN: `Business Event`), `系统事件`→user's language (e.g. EN: `System Event`; autotrack events are handled automatically by CLI, no need to re-translate)
@@ -601,21 +641,23 @@ Next: Phase 2 — Refine to confirm the plan.
 Run the following command to dynamically discover available templates:
 
 ```bash
-AE_LANG=<user_lang> ae-cli tracking plan list-templates
+AE_LANG=<user_lang> ae-cli tracking plan list-templates --json
 ```
 
 **Language rules**: Template file names are in Chinese. When displaying to users, **must translate to user's current language**; **do NOT** include the original Chinese name (e.g. show only "Card Game v1", not "Card Game (卡牌游戏) v1").
 
+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.
+
 Search directories in order:
 
-1. `./tracking-plan-template/` — Project root (development)
-2. `~/.ae-cli/templates/` — `ae-cli tracking` CLI user directory after installation (future default)
+1. `<ae-cli package root>/tracking-plan-template/` — bundled templates
+2. `~/.ae-cli/templates/` — user-provided template directory
 
 Each template prefers `.md` distilled file (if same-name `.md` exists, return md path; otherwise return xlsx path).
-Auto-detect format on import:
+Display translated template names to the user, but keep the original `name` from the JSON result for import. Auto-detect format on import:
 
 ```bash
-AE_LANG=<user_lang> ae-cli tracking code import-template --template <path> --out .ae-cli/draft.json
+AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json
 ```
 
 ---
@@ -633,13 +675,22 @@ In order, one conversation round per segment:
 Per-segment flow:
 
 1. Display corresponding section of current draft
-2. Ask **"Does this look correct? `ok` to proceed to next segment, or describe what to change"**
+2. Ask a segment-specific confirmation question. Always include the current segment number, current segment key, and next segment key:
+   ```text
+   Segment <n>/5 <segment_key> confirmed? Reply ok to continue to Segment <n+1>/5 <next_segment_key>, or describe changes.
+   ```
+   For Segment 5:
+   ```text
+   Segment 5/5 props confirmed? Reply ok to archive the plan and continue to Phase 3, or describe changes.
+   ```
 3. User gives natural language instructions → update `.ae-cli/draft.json` → re-run:
    ```bash
    AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx
    ```
 4. User `ok` → proceed to next segment
 
+`ok` is a refine state-machine input, not a repeated-message error. If the user replies `ok` multiple times in a row, advance exactly one segment per `ok` in order. Before each confirmation prompt, print the new segment heading first, so consecutive confirmations do not look like the same question repeated.
+
 User may say **"Go back to segment N"** at any time to jump to any segment (N = 1-5).
 
 ---
@@ -849,33 +900,59 @@ At the start of Phase 3, tell user:
 ```
 ## Phase 3 — Upload Preparation
 Next steps:
-1. AE web address
-2. Login to AE to get token
+1. Check active AE host and login status
+2. Login to AE to get token if needed
 3. AE project ID
 ```
 
-### 3.1 Get AE Web Address
+### 3.1 Check Active AE Host and Login Status
 
-❌ **Do NOT provide unconfirmed example URLs here.** Simply ask the user directly.
+Do not ask for the AE web address first. ae-cli stores an active AE host, and auth commands can use it directly.
 
-Ask user: **"What is the AE web address?"**
+First check current auth/host status:
 
-After user responds, save to `.ae-cli/draft.json` `meta.host` field.
+```bash
+ae-cli auth status
+```
+
+If an active host is configured, save that host to `.ae-cli/draft.json` `meta.host`. If `auth status` reports `authenticated: true`, skip login and continue to project ID.
+
+Only if ae-cli reports no active host / no AE host configured, ask the user:
+
+**"What is the AE web address?"**
+
+After user responds, configure it and save the same value to `.ae-cli/draft.json` `meta.host`:
+
+```bash
+ae-cli config set-host <host>
+```
+
+If `auth status` reports unauthenticated, use the agent split-flow. Do **not** run blocking `ae-cli auth login` directly from an AI agent.
 
-Guide getting and saving token based on AE web address:
+Step 1 — request an authorization URL and return control to the user:
 
 ```bash
-ae-cli auth login --host <host>
+ae-cli auth login --no-wait
+```
+
+Show the returned `verification_url` to the user and ask them to complete authorization. Keep the returned `device_code` for the next step.
+
+Step 2 — after the user says authorization is complete, finish login:
+
+```bash
+ae-cli auth login --device-code <device_code>
 ae-cli auth status
 ```
 
+Do not retry with `ae-cli auth login --host <host>` unless the previous command explicitly failed because no active host was configured. In that case, configure the host first, then restart the split-flow with `--no-wait`.
+
 Common error tips and self-recovery:
 
 | Error | Cause | What to Tell the User |
 |---|---|---|
-| `Chrome JS-from-AppleEvents disabled` | Chrome disabled AppleScript JS execution | Chrome menu View → Developer → Allow JavaScript from Apple Events, then retry |
-| `not_mac` | Not macOS | Manually set `export AE_TOKEN=<uuid>` (get from DevTools → Application → Local Storage → `ACCESS_TOKEN`, strip quotes) |
-| `NO_TAB_FOUND` | Not logged into AE in Chrome | Open and login to TE in Chrome first, then retry |
+| `Device authorize request failed` | The agent runtime cannot reach the authorization service | Report that no device code was created and include the exact error |
+| `not_mac` | A legacy browser-token flow was attempted | Retry the split-flow device-code login; do not ask the user for browser tokens |
+| `NO_TAB_FOUND` | A legacy browser-token flow was attempted | Retry the split-flow device-code login; do not ask the user to open Chrome |
 
 Token cached for 20 hours; same host avoids re-auth.
 
@@ -901,9 +978,11 @@ Checking project's existing plan...
 Before uploading, check if the project already has a tracking plan:
 
 ```bash
-AE_LANG=<user_lang> ae-cli tracking plan fetch --project <projectId> --host <host> > .ae-cli/existing-plan.json
+AE_LANG=<user_lang> ae-cli tracking plan fetch --project <projectId> > .ae-cli/existing-plan.json
 ```
 
+Do not add `--host` here unless the user explicitly provides a reachable override for this command. In agent sandboxes, ae-cli can resolve the request host from the sandbox-provisioned `cli-token.json`; passing a stale Kubernetes internal host can bypass that fallback.
+
 **Result assessment**:
 - File empty or command error `404` → project has no plan; upload directly
 - File has content → project has an existing plan; show summary + **conflict detection**
@@ -1008,12 +1087,10 @@ 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)
 
-If CLI returns exit code 13 (language mismatch), the AE project language differs from xlsx language. Do NOT silently retry; must prompt user:
-> "AE project language is {aeLang}, but current xlsx is {xlsxLang}. Switch AE language?"
-
-After user confirms, re-upload with `--switch-lang`:
+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:
 ```bash
-AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --switch-lang [--replace]
+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 [--replace]
 ```
 
 On successful upload, prompt user to verify in AE Admin. **Provide the full URL** (tracking plan page URL format: `https://<host>/#/data/plan`).

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

@@ -1,23 +1,22 @@
-# AE Backend API (internal reference)
+# AE Tracking Capability API (internal reference)
 
-> **Terminology**: 认证 = authentication | Token = bearer token from localStorage `ACCESS_TOKEN` | 端点 = endpoint | 抓包 = traffic capture | 埋点方案 = tracking plan | 上传 = upload | 删除 = delete | 查询 = query/fetch
+> **Terminology**: authentication = CLI token | capability = gateway-registered operation | tracking plan = program | upload = save xlsx | delete = clear program | query/fetch = read program
 
-> This file is the implementation basis for `src/client.ts`, maintained for internal contributors.
+> This file is the implementation basis for `src/core/tracking-client.ts`, maintained for internal contributors.
 > **Skill body should not reference this document** — skill users interact via CLI commands and do not need to know underlying endpoints.
 > xlsx format contract is in `xlsx-schema.md`, not here.
 
-Capture environment: `https://web-ta-demo.thinkingdata.cn`. If endpoints change, re-run the
-chrome-devtools capture flow from `docs/superpowers/plans/2026-04-15-ae-tracking-skill.md` Task 3.
+The AE CLI must call common-service through capability gateway URLs under `/api/cli/`.
+The legacy common-service endpoints are wrapped server-side by these capabilities and must not be
+called directly from `ae-cli`.
 
-## 认证
+## Authentication
 
-### Token
-- localStorage key：`ACCESS_TOKEN`
-- 存储形态：**JSON 编码字符串**（带双引号），使用前须 `replace(/^["']|["']$/g, '')`
+All capability requests use the CLI token chain:
 
-### 两种传 token 方式（按端点区分）
-- **GET/JSON 类接口**：Header `authorization: bearer <token>`（全小写）
-- **Excel 上传接口**：**form field `access_token`**，裸 UUID，**不用** Authorization header
+- Header: `cli-token: <token>`
+- Do not send `authorization: bearer ...`.
+- Do not send `access_token` form fields.
 
 ## 响应统一包装
 
@@ -25,16 +24,22 @@ chrome-devtools capture flow from `docs/superpowers/plans/2026-04-15-ae-tracking
 { "return_code": 0, "return_message": "success", "showStackMessage": false, "data": ... }
 ```
 - `return_code === 0` 为成功；非 0 抛错，取 `return_message`
-- 某些端点（如 `excel-save` / 空项目 `query`）成功时无 `data`
+- Empty project query may return no `data`.
 
-## 端点
+## Capabilities
 
-### 1. GET `/v1/ta/bury/manage/program/query`
+### 1. `track.program.query`
 
 获取项目唯一的埋点方案。
 
-- Query：`projectId` 必填 number
-- Header：`authorization: bearer <token>`
+- Method: `POST`
+- URL: `/api/cli/analysis/v1/capabilities/track.program.query/execute`
+- Input:
+
+```json
+{ "project_id": 1603 }
+```
+
 - Response `data` 结构（事件池 / 事件属性池 / 公共属性 / 用户属性）：
 
 ```jsonc
@@ -55,21 +60,46 @@ chrome-devtools capture flow from `docs/superpowers/plans/2026-04-15-ae-tracking
 
 空项目：`data` 不存在，直接 `{ return_code: 0, return_message: "success" }`。
 
-### 2. GET `/v1/ta/bury/manage/program/delete?projectId=<id>`
+### 2. `track.program.delete`
 
 一次清空整个项目的方案（事件 / 事件属性 / 公共属性 / 用户属性）。
 
-### 3. POST `/v1/ta/bury/manage/program/excel-save`
+- Method: `POST`
+- URL: `/api/cli/analysis/v1/capabilities/track.program.delete/execute`
+- Input:
+
+```json
+{ "project_id": 1603 }
+```
+
+### 3. `track.program.excel_save`
 
 批量上传 xlsx。
 
-- Content-Type：`multipart/form-data`
-- Form fields（全必填）：
-  - `file` — xlsx 二进制
-  - `projectId` — 文本
-  - `access_token` — 文本，裸 UUID
-- **无** Authorization header
-- Response：`{ return_code: 0, return_message: "success" }`（无 data）
+Upload is a two-step capability-gateway flow:
+
+1. Upload the xlsx as an input file.
+
+   - Method: `POST`
+   - URL: `/api/cli/analysis/v1/input-files`
+   - Content-Type: `multipart/form-data`
+   - Form fields:
+     - `project_id`
+     - `purpose`: `track.program.xlsx`
+     - `file`: xlsx binary
+   - Response includes `input_file_id`.
+
+2. Execute the save capability.
+
+   - Method: `POST`
+   - URL: `/api/cli/analysis/v1/capabilities/track.program.excel_save/execute`
+   - Input:
+
+```json
+{ "project_id": 1603, "input_file_id": "..." }
+```
+
+- Response: `{ return_code: 0, return_message: "success" }` on success.
 
 **合并语义**：对事件走 **merge-by-name**（同名不覆盖、新名新增）。若要完全替换，
 必须先调 `delete` 端点清空再上传。
@@ -96,5 +126,5 @@ chrome-devtools capture flow from `docs/superpowers/plans/2026-04-15-ae-tracking
 
 ## v2（暂未实现）
 
-- UI「逐个添加」通向单事件 CRUD 接口（`POST /v1/ta/bury/manage/event/*` 族），v1 走 excel-save 统一入口
+- UI「逐个添加」通向单事件 CRUD 接口，v1 走 `track.program.excel_save` 统一入口
 - 列项目、校验错误响应等见 plan 文档的"未抓端点"清单