@thinkingai/ae-cli 6.0.18 → 6.0.22

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

@@ -58,14 +58,14 @@ First, check if `.ae-cli/draft.json` exists and read existing configuration:
 |---|---|---|
 | AE projectId | `meta.project_id` | Has value → confirm; missing → ask |
 | AE web address | `meta.host` | Has value → confirm; missing → ask |
-| **SERVER_URL** | `meta.server_url` | **Must ask**. Data ingestion endpoint — different from web address |
-| **APP_ID** | `meta.app_id` | **Must ask**. Obtained from AE Admin → "Integration Config" |
+| **SERVER_URL** | `meta.server_url` | Has value → confirm; missing → try lookup from project config, then ask if unavailable |
+| **APP_ID** | `meta.app_id` | Has value → confirm; missing → try lookup from accessible project list, then ask if unavailable |
 | SDK integration mode | `meta.sdk_integration_mode` | Has value → use directly |
 | Client SDK type | `meta.client_platforms` (preferred) or `meta.client_sdk_type` | Has value → use directly |
 | Server language | `meta.server_language` | Has value → use directly |
 | User identity system | `meta.user_identity` | Has value → use directly |
 
-**Important**: `project_id` ≠ `APP_ID`, and `host` ≠ `SERVER_URL`. Even if project_id and host are already set, SERVER_URL and APP_ID must still be asked separately.
+**Important**: `project_id` ≠ `APP_ID`, and `host` ≠ `SERVER_URL`. Even if project_id and host are already set, SERVER_URL and APP_ID must still be resolved and confirmed separately. Prefer lookup first; ask the user only when lookup is unavailable or ambiguous.
 
 **Multi-platform support**:
 - If `client_platforms` exists (array): multi-platform scenario — generate code for each platform
@@ -86,14 +86,21 @@ First, check if `.ae-cli/draft.json` exists and read existing configuration:
 - User says `yes` → use draft value
 - User enters new value → update draft.json and use new value
 
-### Required configuration (must confirm each item)
+### Required configuration (must resolve and confirm each item)
 
-**⚠️ Key: SERVER_URL and APP_ID are independent config items. Even if draft.json has project_id and host, you MUST ask. `project_id` ≠ `APP_ID`, `host` ≠ `SERVER_URL`.**
+**⚠️ Key: SERVER_URL and APP_ID are independent config items. Even if draft.json has project_id and host, you MUST resolve and confirm them. `project_id` ≠ `APP_ID`, `host` ≠ `SERVER_URL`.**
 
-1. **SERVER_URL** — Data ingestion endpoint (**different from web URL**; go to AE Admin → "Project Settings" → "Integration Config" → fill in "Public URL")
+1. **APP_ID** — Prefer automatic lookup before asking:
+   - If `meta.project_id` is known, run `ae-cli analysis_common +list_projects` once for the current host.
+   - Find the project whose `projectId` matches `meta.project_id`.
+   - If the matched project has `appId`, ask: **"I found APP_ID `<appId>` for project `<projectId>`. Use it? yes / enter new value"**
+   - If the project is missing, ambiguous, or has no `appId`, ask the user to copy APP_ID from AE Admin → "Project Settings" → "Integration Config".
+2. **SERVER_URL** — Data ingestion endpoint (**different from web URL**; go to AE Admin → "Project Settings" → "Integration Config" → fill in "Public URL")
+   - If `meta.project_id` is known, you may try `ae-cli analysis_meta +get_project_config --project_id <project_id>` once.
+   - Use the returned value only if the response explicitly contains a receiver URL field such as `serverUrl`, `pushUrl`, `push_url`, `receiverUrl`, `publicUrl`, or equivalent ingestion endpoint field.
+   - If a value is found, ask: **"I found SERVER_URL `<url>` for project `<projectId>`. Use it? yes / enter new value"**
    - ⚠️ "Public URL" only shows if previously filled in; if empty, this field won't display
    - Solution: ask ops for the URL, or **skip this step** (use `SERVER_URL` or `PUSH_URL` placeholder in code)
-2. **APP_ID** — Go to AE Admin → "Project Settings" → "Integration Config" → copy "APP_ID"
 
 **host handling** (optional):
 - If you need to fetch plan from AE (no local draft.json) → ask for host
@@ -194,7 +201,7 @@ Ask in order, one item per message:
    - Account ID source: user_account / role_id / none
    - Visitor ID strategy: auto / device_id / custom
 
-5. **SERVER_URL / APP_ID** (skip if already configured)
+5. **APP_ID / SERVER_URL**: resolve them with the lookup-first flow above, confirm any found values with the user, and ask only for values that cannot be found or are rejected by the user.
 
 **Step 4: Merge configuration and proceed to Phase 1**
 
@@ -224,26 +231,31 @@ Without `.ae-cli/draft.json` or `.ae-cli/remote-plan.json`:
 
 **Client platforms** (corresponding to client SDKs):
 
-| plan field | Platform | SDK | Document Path |
-|---|---|---|---|
-| `android` | Android | Android SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android.md` |
-| `ios` | iOS | iOS SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/ios.md` |
-| `openharmony` | OpenHarmony | OpenHarmony SDK | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/openharmony.md` |
-| `javascript` | Web / H5 | JavaScript SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/javascript.md` |
-| `miniprogram` | Mini-program | Mini-program SDK | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/小程序小游戏.md` |
-| `unity` | Unity | Unity SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/unity.md` |
-| `game_engine` | Game Engine | Cocos / Laya / Unreal | See `references/sdk-index.md` |
+| plan field | Platform | SDK |
+|---|---|---|
+| `android` | Android | Android SDK |
+| `ios` | iOS | iOS SDK |
+| `openharmony` | OpenHarmony | OpenHarmony SDK |
+| `javascript` | Web / H5 | JavaScript SDK |
+| `miniprogram` | Mini-program | Mini-program SDK |
+| `unity` | Unity | Unity SDK |
+| `game_engine` | Game Engine | Cocos / Laya / Unreal |
 
 **Server languages** (corresponding to server SDKs):
 
-| plan field | Language | SDK | Document Path |
-|---|---|---|---|
-| `java` | Java | Java SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/java.md` |
-| `python` | Python | Python SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/python.md` |
-| `go` | Go | Go SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/golang.md` |
-| `nodejs` | Node.js | Node SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/nodejs.md` |
-| `php` | PHP | PHP SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/php.md` |
-| `csharp` | C# | C# SDK | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/c.md` |
+| plan field | Language | SDK |
+|---|---|---|
+| `java` | Java | Java SDK |
+| `python` | Python | Python SDK |
+| `go` | Go | Go SDK |
+| `nodejs` | Node.js | Node SDK |
+| `php` | PHP | PHP SDK |
+| `csharp` | C# | C# SDK |
+
+**SDK document paths**:
+- Do not use hard-coded wiki paths from this section.
+- Always read `references/sdk-index.md` first and use the path listed there for the selected SDK.
+- If the path from `references/sdk-index.md` does not exist in the local wiki mirror, search under `~/.ae-cli/wiki/te-docs/raw/` with SDK-specific keywords and use the best matching latest main document.
 
 ---
 
@@ -437,7 +449,7 @@ test -z "$(git status --porcelain)" || echo "uncommitted changes present"
 **Only generate events where `platform === "client"` or `platform === "both"`**
 
 **⚠️ Hard rule: Never guess SDK imports**
-- Before generating, MUST read the corresponding SDK wiki document (see `references/sdk-index.md`)
+- Before generating, MUST read `references/sdk-index.md`, resolve the corresponding SDK wiki main document, verify the path exists, and then read that main document
 - **MUST copy import statements and package names from the wiki main document**, never guess
 - Example: JavaScript SDK npm package is `thinkingdata-browser`, import variable is `ta`
 - If generated code doesn't match wiki docs (e.g. `TDAnalytics`/`te`/`@thinkingdata/web-sdk`), re-read wiki and fix
@@ -460,7 +472,7 @@ test -z "$(git status --porcelain)" || echo "uncommitted changes present"
 - **Always provide LogBus2 official docs link**: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
 
 **⚠️ Hard rule: Never guess SDK imports**
-- Before generating, MUST read the corresponding SDK wiki document (see `references/sdk-index.md`)
+- Before generating, MUST read `references/sdk-index.md`, resolve the corresponding SDK wiki main document, verify the path exists, and then read that main document
 - **MUST copy import statements and package names from the wiki main document**, never guess
 - **Re-read docs before every code generation**, never rely on "remembered" code
 
@@ -478,6 +490,25 @@ test -z "$(git status --porcelain)" || echo "uncommitted changes present"
 
 Show deliverables based on selected output modes:
 
+### Attachment upload
+
+After all `.ae-cli/output/` files are generated, upload every generated output file to the Agent attachment library so the user can download them from the file/attachment management entry.
+
+Use the existing attachment command:
+
+```bash
+ae-cli agent +add-attachment --yes --files '<json-array-of-generated-output-files>'
+```
+
+Upload list rules:
+- Include all generated snippet files under `.ae-cli/output/`.
+- Include generated server config files such as `.ae-cli/output/daemon.json` and LogBus README files.
+- Include `.ae-cli/output/README.md`.
+- Include generated debug scripts if the user selected the debug option.
+- Do not upload files inserted directly into the user's project; only upload generated output artifacts.
+
+If upload succeeds, include the attachment upload result in the final response and tell the user the files are available from the file/attachment management entry. If upload fails because Agent attachment credentials are unavailable, keep the local `.ae-cli/output/` files and tell the user the upload did not complete.
+
 ### All snippets
 
 ```
@@ -496,6 +527,8 @@ Standalone:
 - .ae-cli/output/te-debug.java (validation script)
 
 README: .ae-cli/output/README.md (usage instructions)
+
+Attachment upload: uploaded generated output files to the file/attachment management entry
 ```
 
 ### Mixed (some insert + some snippet)
@@ -514,6 +547,8 @@ LogBus2 official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logb
 
 Standalone:
 - .ae-cli/output/te-debug.java (validation script)
+
+Attachment upload: uploaded generated output files to the file/attachment management entry
 ```
 
 ### Markdown code snippet display
@@ -623,7 +658,9 @@ All output mode rules are in `references/*.md`. This SKILL.md only handles phase
 - `~/.ae-cli/wiki/te-docs/synthesis/` — LLM-synthesized overview documents
 
 **Document reading order during code generation**:
-1. Read `references/sdk-index.md` to find the SDK's wiki document path
-2. Read wiki main doc (initialization, basic API)
-3. Read wiki advanced guide (LoggerConsumer, user properties, etc.)
-4. Check advanced guide sub-documents if needed
+1. Read `references/sdk-index.md` to find the selected SDK's main document and advanced guide paths.
+2. Verify the main document path exists in the local wiki mirror before reading it.
+3. If the indexed path is missing, search under `~/.ae-cli/wiki/te-docs/raw/` with SDK-specific keywords such as SDK name, platform name, language name, and `main doc`; choose the latest main document, not historical/versioned documents.
+4. Read the wiki main doc first (initialization, imports, package names, basic API).
+5. Read the advanced guide only after the main doc (LoggerConsumer, user properties, auto-track, preset properties, etc.).
+6. Check advanced guide sub-documents if needed.

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

@@ -4,9 +4,10 @@
 
 ## Deliverables
 
-Two outputs:
+Three outputs:
 1. **Markdown response**: code snippets grouped by platform (for reading)
 2. **Code files**: `.ae-cli/output/<platform>-sdk.<ext>` (for copy-paste use)
+3. **Attachment library upload**: generated files uploaded with `ae-cli agent +add-attachment` so the user can download them from the file/attachment management entry
 
 ---
 
@@ -230,6 +231,26 @@ AE Debug mode requires the device ID to be added in AE Admin before data can be
 
 ---
 
+## Attachment Library Upload
+
+After all snippet output files are written, upload generated output artifacts to the Agent attachment library:
+
+```bash
+ae-cli agent +add-attachment --yes --files '<json-array-of-generated-output-files>'
+```
+
+Upload list must include:
+- Every generated platform snippet file under `.ae-cli/output/`
+- `.ae-cli/output/README.md`
+- Server-side config files, including `.ae-cli/output/daemon.json` and related README files
+- Generated debug scripts, if any
+
+Only upload generated output artifacts. Do not upload files inserted directly into the user's project.
+
+If upload succeeds, report that the files are available from the file/attachment management entry. If upload fails because Agent attachment credentials are unavailable, preserve the local output files and report the upload failure separately.
+
+---
+
 ## Generation Workflow
 
 ### ⚠️ Mandatory Pre-checks (do not skip)
@@ -302,6 +323,10 @@ After generation, perform language style checks on each output file:
 1. Additionally generate `daemon.json` for server-side
 2. **Must always provide LogBus2 official documentation link**
 
+#### Step 5: Upload Generated Artifacts
+
+Upload all generated `.ae-cli/output/` artifacts to the Agent attachment library using `ae-cli agent +add-attachment --yes --files '<json-array>'`.
+
 ---
 
 ## Code Style

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.