@thinkingai/ae-cli 1.0.28 → 6.0.16-1

package/skills/ae-generate-tracking-code/references/logbus-config.md

@@ -0,0 +1,200 @@
+# LogBus2 Configuration Generation
+
+> **Terminology**: LogBus2 = log sync tool (Go-based, v2) | LoggerConsumer = writes events to local log files | 日志同步工具 = log sync tool | daemon.json = LogBus2 config file | push_url = TE receiver/data ingestion URL | app_id = AE project APP_ID | file_patterns = glob patterns for log files | unit_remove = file deletion unit (day/hour) | offset_remove = file deletion offset | 重命名 = rename (causes re-upload) | runtime 目录 = runtime directory (stores progress snapshots) | JSON line = JSONL format (one JSON per line)
+
+LogBus2 is AE's official log sync tool, used together with LoggerConsumer (server-side SDK).
+
+**Note: LogBus v1 is deprecated and no longer recommended. Use LogBus2 for all scenarios.**
+
+---
+
+## Architecture
+
+```
+Server code → LoggerConsumer → Local log files
+                                    ↓
+                              LogBus2 process → AE platform
+```
+
+---
+
+## Official Documentation
+
+When generating config files, **must always provide the official documentation link**:
+
+| Document Type | URL |
+|---|---|
+| **LogBus2 User Guide** | https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US |
+
+Download link is in the official doc's "二、Download LogBus2" section.
+
+---
+
+## Trigger Condition
+
+- When server-side chooses `insert` or `snippet`, **generated by default**
+- User does not need to select it separately
+
+---
+
+## Deliverables
+
+### 1. Config File
+
+`.ae-cli/output/daemon.json`:
+
+```json
+{
+  "datasource": [
+    {
+      "type": "file",
+      "file_patterns": [
+        "/data/ta_log/*.log"
+      ],
+      "app_id": "<appId>",
+      "unit_remove": "day",
+      "offset_remove": 7
+    }
+  ],
+  "push_url": "<SERVER_URL>"
+}
+```
+
+**Config item descriptions**:
+
+| Config Item | Description | Required |
+|---|---|---|
+| `file_patterns` | Log file matching path (Glob wildcards), must match LoggerConsumer config | ✔️ |
+| `app_id` | AE project APP_ID | ✔️ |
+| `push_url` | AE receiver URL (must start with http/https) | ✔️ |
+| `unit_remove` | File deletion unit: `day` or `hour` | Optional |
+| `offset_remove` | File deletion offset (paired with unit_remove) | Optional |
+
+### 2. README File
+
+`.ae-cli/output/logbus-README.md`:
+
+```
+# LogBus2 Configuration Guide
+
+## Important
+
+- LogBus v1 is deprecated. Please use **LogBus2**
+- This config file is in JSON format (daemon.json)
+
+## Official Documentation
+
+| Document | Link |
+|---|---|
+| **LogBus2 User Guide** | https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US |
+
+Download link is in the official doc's "二、Download LogBus2" section.
+
+## Prerequisites
+
+1. **Download LogBus2** (matching OS version):
+   - Visit the official docs. Download the appropriate version from "二、Download LogBus2"
+   - Linux-amd64 / Linux-arm64 / Windows / Mac / Docker
+
+2. **Extract and deploy**:
+   ```bash
+   tar -xzf logbus2-linux-amd64.tar.gz
+   cd logbus2
+   ```
+
+3. **Confirm LoggerConsumer log path**:
+   - This config uses: /data/ta_log/*.log
+   - Ensure LoggerConsumer config matches this
+
+4. **Place config file**:
+   ```bash
+   cp daemon.json conf/daemon.json
+   ```
+
+## Start
+
+```bash
+./logbus start
+```
+
+## Common Commands
+
+| Command | Description |
+|---|---|
+| `./logbus start` | Start LogBus2 |
+| `./logbus stop` | Stop LogBus2 |
+| `./logbus restart` | Restart LogBus2 |
+| `./logbus env` | Check config and connectivity |
+| `./logbus progress` | View transfer progress |
+| `./logbus reset` | Reset read records (use with caution) |
+| `./logbus dev` | Validate file format |
+
+## Verification
+
+1. Check running status: `./logbus progress`
+2. Check logs: log files under `./logbus/log/` directory
+3. Open AE Debug page to verify data ingestion
+
+## Config Item Reference
+
+| Config Item | Current Value | Description |
+|---|---|---|
+| push_url | <SERVER_URL> | AE receiver URL |
+| app_id | <appId> | AE project APP_ID |
+| file_patterns | /data/ta_log/*.log | Log file matching pattern |
+
+## Notes
+
+1. **Do not rename uploaded log files**: Renaming is equivalent to creating a new file — causes re-upload
+2. **Do not modify the runtime directory**: This directory stores transfer progress snapshots
+3. **Config uses glob wildcards, not regex**: e.g. `/data/log/*.log`
+```
+
+---
+
+## LoggerConsumer Data Format
+
+LoggerConsumer outputs in JSON line format, automatically parsed by LogBus2:
+
+| LoggerConsumer Field | Description |
+|---|---|
+| `#event_name` | Event name |
+| `#time` | Timestamp (ISO 8601) |
+| `#distinct_id` | Visitor ID |
+| `#account_id` | Account ID |
+| Business properties | Properties from track() call |
+
+---
+
+## Customer Prompt (must display when generating)
+
+After generating the LogBus2 config file, present to the customer:
+
+```
+LogBus2 config file generated: .ae-cli/output/daemon.json
+
+## Official Documentation
+
+| Document | Link |
+|---|---|
+| **LogBus2 User Guide** | https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US |
+
+Download link is in the official doc's "二、Download LogBus2" section.
+
+## Usage Steps
+
+1. Download LogBus2 from the official docs (matching OS version)
+2. Extract and deploy
+3. Copy daemon.json to conf/ directory
+4. Start: ./logbus start
+5. Verify: ./logbus progress
+
+Note: LogBus v1 is deprecated. Please use LogBus2.
+```
+
+---
+
+## Reference Docs
+
+- Official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
+- Wiki: `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/logbus2-user-guide.md` — LogBus2 official doc mirror

package/skills/ae-generate-tracking-code/references/modes.md

@@ -0,0 +1,83 @@
+# Output Mode Architecture
+
+> **Terminology**: 输出方式 = output mode | 插入 = insert (inject into project) | 片段 = snippet (code file delivery) | 产物 = deliverable/output | 端/平台 = platform | 项目路径 = project path (absolute) | LoggerConsumer = writes events to local log files | LogBus2 = log sync tool | 校验脚本 = validation/debug script
+
+## Core Choice (per platform)
+
+| Output Mode | Description | Parameters | Deliverables |
+|---|---|---|---|
+| **insert** | Direct Edit injection into user project | Requires project path (absolute) | Code written to target directory |
+| **snippet** | Markdown print + generate code file | No path needed | `.ae-cli/output/<platform>-sdk.<ext>` |
+
+---
+
+## Server-side Defaults
+
+Server-side always gets the following regardless of `insert` or `snippet`:
+
+| Deliverable | Description |
+|---|---|
+| LoggerConsumer code | Server SDK writes to local log files |
+| `.ae-cli/output/daemon.json` | LogBus2 config (reads logs and uploads to TE) |
+
+**Note: LogBus v1 is deprecated. Use LogBus2 for all scenarios.**
+
+Official docs:
+- User guide: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
+- Download link is in the official doc's "二、Download LogBus2" section
+
+**Architecture**:
+```
+Server code → LoggerConsumer → Local log files
+                                    ↓
+                              LogBus2 process → AE platform
+```
+
+Advantages:
+- Data reliability (local log persistence)
+- Async upload (doesn't block business logic)
+- Batch upload (high network efficiency)
+
+---
+
+## Standalone Options (reserved)
+
+| Option | Description | Deliverable |
+|---|---|---|
+| `datax` | Database batch import | `.ae-cli/output/datax-job.json` + README |
+| `restful` | RESTful API direct upload (HTTP POST) | `.ae-cli/output/restful-client.<ext>` |
+| `debug` | Validation script | `.ae-cli/output/te-debug.<ext>` |
+
+---
+
+## SDK Integration Mode → Platform List
+
+| SDK Integration Mode | Platform List |
+|---|---|
+| `client_only` | Client: [client_sdk_type] (e.g. `['android']`) |
+| `server_only` | Server: [server_language] (e.g. `['java']`) |
+| `both` | Client: [client_sdk_type], Server: [server_language] |
+
+---
+
+## Quick Selection
+
+| Quick Option | Description |
+|---|---|
+| **Generate all as snippets** | All platforms use `snippet`, output all code files at once |
+
+When to use:
+- Not inside the project directory
+- Just want to reference code structure
+- Multi-platform one-shot output
+
+---
+
+## Constraints
+
+- Any `insert` must check `git status` first; refuse if uncommitted changes exist
+- Client code: only generate events where `platform === "client"` or `platform === "both"`
+- Server code: only generate events where `platform === "server"` or `platform === "both"`
+- Server defaults to LoggerConsumer + LogBus2, does NOT default to RESTful
+- **Use LogBus2 only; do not use LogBus v1** (deprecated)
+- When generating LogBus2 config, must always provide official documentation link (user guide + download address)

package/skills/ae-generate-tracking-code/references/restful-call.md

@@ -0,0 +1,36 @@
+# Mode E — RESTful Call
+
+> **Terminology**: 模板 = template | 产物 = deliverable/output | 同构版本 = isomorphic version (same logic, different language) | endpoint = API endpoint URL | 鉴权规则 = authentication rules | Edit 写文件 = Edit to write file (insert mode)
+
+## Template Selection
+By appType → language:
+- node-server → `src/lib/te-track.ts` (axios)
+- python-server → `src/lib/te_track.py` (requests)
+- go-server → `src/lib/te_track.go` (net/http)
+- java-server → `src/main/java/.../TeTrack.java` (OkHttp)
+
+## Deliverable (Node example)
+```ts
+// src/lib/te-track.ts
+import axios from 'axios';
+
+const SERVER_URL = '<SERVER_URL>';
+const APPID = '<appId>';
+
+export async function track(event: string, props: Record<string, unknown>, distinctId: string) {
+  await axios.post(`${SERVER_URL}/sync_json`, {
+    appid: APPID,
+    event,
+    '#time': new Date().toISOString(),
+    '#distinct_id': distinctId,
+    properties: { ...props },
+  }, { headers: { 'Content-Type': 'application/json' } });
+}
+```
+
+Other languages: provide isomorphic versions. Reference `~/.ae-cli/wiki/te-docs/synthesis/restful-api-reference.md`.
+
+## Generation Steps
+1. Select template by appType; confirm endpoint/auth rules from wiki
+2. If CWD is a server project → directly Edit to write file (simplified version of Mode A Stage 3 logic)
+3. Otherwise → deliver as snippet per Mode B

package/skills/ae-generate-tracking-code/references/sdk-index.md

@@ -0,0 +1,128 @@
+# SDK Document Path Index
+
+> **Terminology**: 文档路径索引 = document path index | 主文档 = main document (latest, authoritative) | 历史版本文档 = historical/versioned document (ignore) | 进阶指南 = advanced guide | 预置属性 = preset properties | 自动采集 = auto-track
+
+> This index points to authoritative wiki documents for the skill to reference during code generation.
+> The wiki directory is maintained by `ae-cli tracking wiki` and synced from AE official documentation.
+
+---
+
+## ⚠️ Important: Document Reading Priority
+
+**When generating code, must prioritize reading the "main document". Do NOT read historical/versioned documents!**
+
+| 优先级 | 文档类型 | 说明 |
+|---|---|---|
+| 🔴 **最高** | Main doc (e.g. `android.md`) | Latest SDK guide with correct API |
+| 🟡 中等 | Advanced, Auto-track, Preset Props | Supplementary info |
+| ⚫ **忽略** | Historical docs | Outdated, may use incompatible API |
+
+**Directory naming**:
+- `xxx.md` — latest main doc (read first)
+- `xxx-advanced.md` — supplementary guide
+- `advanced/` — supplementary sub-pages
+
+---
+
+## 客户端 SDK
+
+### 原生移动端
+
+| SDK | Main Doc | Advanced | Auto-track | Preset Props |
+|---|---|---|---|---|
+| Android | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android/android-advanced.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android/android-advanced/automatic-event-tracking.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android/android-advanced/preset-properties.md` |
+| iOS | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/ios.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/ios/ios-advanced.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/ios/ios-advanced/automatic-event-tracking.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/ios/ios-advanced/preset-properties.md` |
+
+### Web / H5
+
+| SDK | Main Doc | Advanced | Auto-track |
+|---|---|---|---|
+| JavaScript | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/javascript.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/javascript/javascript-advanced.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/javascript/javascript-advanced/automatic-event-tracking.md` |
+
+### Mini Program & Mini Game (zh-CN only)
+
+| SDK | Main Doc | Advanced | Auto-track |
+|---|---|---|---|
+| 小程序小游戏 | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/小程序小游戏.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/小程序小游戏/进阶指南.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/小程序小游戏/进阶指南/自动采集.md` |
+
+### Game Engines
+
+| SDK | Version | Main Doc | Advanced | Auto-track |
+|---|---|---|---|---|
+| Unity | v3.x | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/unity.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/unity/unity-advanced.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/unity/unity-advanced/automatic-event-tracking.md` |
+| Unreal | v2.x | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/unreal.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/unreal/unreal-advanced.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/unreal/unreal-advanced/automatic-event-tracking.md` |
+| Cocos2d-x | v2.x | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/cocos2d-x.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/cocos2d-x/cocos2d-x-advanced.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/cocos2d-x/cocos2d-x-advanced/automatic-event-tracking.md` |
+| CocosCreator | v2.x | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/cocoscreator.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/cocoscreator/cocoscreator-advance.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/cocoscreator/cocoscreator-advance/automatic-event-tracking.md` |
+| Cocos2d-Lua (zh-CN) | v2.x | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/cocos2d-lua.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/cocos2d-lua/进阶指南.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/cocos2d-lua/进阶指南/自动采集.md` |
+| LayaAir (zh-CN) | v2.x | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/layaair.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/layaair/进阶指南.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/layaair/进阶指南/自动采集.md` |
+| Egret (zh-CN) | v2.x | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/egret.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/egret/进阶指南.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/egret/进阶指南/自动采集.md` |
+
+**Note**: Unity SDK upgraded from v2.x to v3.x with significant API changes:
+- v2.x API: `ThinkingAnalyticsAPI.Track()`
+- v3.x API: `TDAnalytics.Track()`
+- Main doc `unity.md` = v3.x; historical docs removed from v6.0
+
+### Cross-Platform
+
+| SDK | Main Doc | Advanced |
+|---|---|---|
+| React Native | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/cross-platform/react-native.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/cross-platform/react-native/reactnative-advanced.md` |
+| Flutter | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/cross-platform/flutter.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/cross-platform/flutter/flutter-advanced.md` |
+| uni-app | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/cross-platform/uni-app.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/cross-platform/uni-app/uniapp-advanced.md` |
+| OpenHarmony (zh-CN) | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/openharmony.md` | `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/openharmony/进阶指南.md` |
+
+---
+
+## Server SDK
+
+| Language | Main Doc | Advanced |
+|---|---|---|
+| Java | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/java.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/java/java-advanced.md` |
+| Python | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/python.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/python/python-advanced.md` |
+| Golang | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/golang.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/golang/golang-advanced.md` |
+| Node.js | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/nodejs.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/nodejs/nodejs-advanced.md` |
+| PHP | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/php.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/php/php-advanced.md` |
+| C# | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/c-V2W3wv.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/c/c-advanced-IauKwI.md` |
+| C++ | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/c-Zf9Jwl.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/c/c-advanced-YAilwk.md` |
+| Ruby | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/ruby.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/ruby/ruby-advanced.md` |
+| Lua | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/lua.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/lua/lua-advanced.md` |
+| Erlang | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/erlang.md` | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/erlang/erlang-advanced.md` |
+
+---
+
+## Data Import Tools
+
+| Tool | Doc Path | Description |
+|---|---|---|
+| **LogBus2** | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/logbus2-user-guide.md` | Recommended, paired with LoggerConsumer |
+| DataX Writer | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/ta-datax-writer-plugin-user-guide.md` | Database batch import |
+| RESTful API | `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/restful-api-user-guide.md` | Direct HTTP upload |
+
+**Note: LogBus v1 is deprecated. Use LogBus2 for all scenarios.**
+
+Official docs:
+- Guide: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
+
+---
+
+## Preset Properties & System Fields
+
+| Doc | Path |
+|---|---|
+| Preset Properties & System Fields | `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/preset-properties-and-system-fields.md` |
+| User Identification Rules | `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/user-identification-rules.md` |
+| Data Rules | `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/data-rules.md` |
+
+---
+
+## Synthesized Docs (Overview)
+
+LLM-synthesized overview docs from multiple raw sources:
+
+| Synthesis Doc | Path | Description |
+|---|---|---|
+| Server SDK Overview | `~/.ae-cli/wiki/te-docs/synthesis/server-sdk-overview.md` | Unified architecture of all server SDKs |
+| SDK Selection Guide | `~/.ae-cli/wiki/te-docs/synthesis/sdk-selection.md` | How to choose the right SDK |
+| RESTful API Reference | `~/.ae-cli/wiki/te-docs/synthesis/restful-api-reference.md` | RESTful API summary |
+| JS SDK Cheatsheet | `~/.ae-cli/wiki/te-docs/synthesis/js-sdk-cheatsheet.md` | JavaScript SDK quick reference |
+| Batch Ingestion Comparison | `~/.ae-cli/wiki/te-docs/synthesis/batch-ingest-comparison.md` | LogBus / DataX / Kafka comparison |

package/skills/ae-generate-tracking-code/references/server-sdk-insert.md

@@ -0,0 +1,206 @@
+# Server-side Code Insertion (LoggerConsumer + LogBus2)
+
+> **Terminology**: 服务端 SDK = server-side SDK | 代码插入 = code insertion/injection | LoggerConsumer = writes events to local log files (recommended for production) | LogBus2 = log sync tool that reads local logs and uploads to TE | 架构 = architecture | 异步上报 = async upload | 批量上传 = batch upload | 重试策略 = retry strategy | 公共属性 = super property | 用户属性 = user property | 依赖管理 = dependency management
+
+## Architecture
+
+Server-side SDK uses the recommended LoggerConsumer + LogBus2 architecture:
+
+```
+Server code → LoggerConsumer → Local log files (/data/ta_log/)
+                                    ↓
+                              LogBus2 process → AE platform
+```
+
+**Note: LogBus v1 is deprecated. Use LogBus2 exclusively.**
+
+Official docs:
+- User guide: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
+- Download link is in the official doc's "二、Download LogBus2" section
+
+Advantages:
+- Data reliability (local log persistence, resilient to network fluctuations)
+- Async upload (doesn't block business logic)
+- Batch upload (high network efficiency)
+- Controllable retry (LogBus2 configures retry strategy)
+
+---
+
+## Stage 0: Wiki
+
+1. Read `references/sdk-index.md` to find the server SDK's wiki path
+2. Read wiki main doc (initialization, LoggerConsumer configuration)
+3. Read wiki advanced guide (user properties, batch upload, etc.)
+
+### Stage 0.5: SDK Integration Confirmation (must execute after Stage 0)
+
+Based on the selected SDK, identify the dependency management method (Maven / pip / go get / npm / composer, etc.), then confirm with user:
+
+**Integration methods that require code changes (Maven / pip / go get / npm / composer, etc.)**:
+
+```
+Server-side <language> SDK detected. Dependency config changes needed.
+
+Should I modify the config file directly to add SDK dependencies?
+- yes → Edit the config file (e.g. pom.xml / requirements.txt / go.mod / package.json / composer.json), then proceed to Stage 1
+- no → Reference the docs below to complete SDK integration, then reply yes to continue
+
+Documentation: <wiki doc path>
+```
+
+- User `yes` → Execute Edit on config file, then proceed to Stage 1
+- User `no` → Display doc path, pause and wait for user completion
+
+**Integration methods that don't require code changes (manual JAR download / file placement, etc.)**:
+
+```
+Please reference the docs below to complete SDK integration, then reply yes to continue.
+
+Documentation: <wiki doc path>
+```
+
+Wait for user confirmation, then proceed to Stage 1.
+
+---
+
+## Stage 1: Explore
+
+1. Grep entry points: `src/main.*`, `App.*`, `Application.*` (Java), `main.go` (Go)
+2. Grep existing tracking: `TaAnalytics|TDAnalytics|thinkingdata|// @tracking`
+3. Grep business logic locations: `(createOrder|handlePayment|userRegister)` etc. (based on plan events)
+4. Confirm log directory: recommends `/data/ta_log/` or `/var/log/ae-tracking/`
+
+---
+
+## Stage 2: Insertion Plan (markdown table)
+
+**Platform filtering**:
+- xlsx "Platform" value `服务端` / `server` → `platform: "server"` (server-only collection)
+- xlsx "Platform" value `客户端,服务端` / `client,server` → `platform: "both"` (both platforms)
+- xlsx "Platform" value `客户端` / `client` → `platform: "client"` (client-only, do NOT generate in server)
+- Only insert events where `platform === "server"` or `platform === "both"`
+
+```
+## SDK Initialization (LoggerConsumer)
+- File: <path>:<line>
+- Code: TaAnalytics.init(new LoggerConsumer("/data/ta_log/"))
+
+## Super Properties
+- File: <path>:<line>
+- setSuperProperties({...})
+
+## User Properties
+- File: <path>:<line>
+- user_set / user_setOnce / user_add
+
+## Event Group: <tag>
+- <event_name>: <file>:<symbol> or SKIP (already present)
+- ...
+
+## LogBus2 Configuration
+- File: (outside project) `.ae-cli/output/daemon.json`
+```
+
+After showing, ask user `ok` to enter Stage 3, or "go back to event X to remap".
+
+---
+
+## Stage 3: Batched Edit
+
+### Batch 1: SDK init (LoggerConsumer)
+
+```java
+// Java example
+TaAnalytics.init(new LoggerConsumer("/data/ta_log/")
+    .setRotateMode(LoggerConsumer.RotateMode.DAILY)
+    .setRotateSize(1024 * 1024 * 100)); // 100MB
+```
+
+Insertion point: entry file static block / start of main function
+
+### Batch 2: Super Properties + User Properties
+
+Generate based on `meta.user_identity`:
+- `user_set` / `user_setOnce`: user property upload
+- `login()` call: on user login
+
+### Batch 3..N: Events grouped by event_tag
+
+Insert track calls at corresponding business logic locations for each event.
+
+Each batch: use Edit tool; print file list + added line count after completion, ask `ok / undo`.
+
+---
+
+## Stage 4: LogBus2 Configuration Generation
+
+Additionally generate `.ae-cli/output/daemon.json` (NOT written to user project):
+
+```json
+{
+  "datasource": [
+    {
+      "type": "file",
+      "file_patterns": [
+        "/data/ta_log/*.log"
+      ],
+      "app_id": "<appId>",
+      "unit_remove": "day",
+      "offset_remove": 7
+    }
+  ],
+  "push_url": "<SERVER_URL>"
+}
+```
+
+**Always provide official docs** (for customer download and deployment):
+
+```
+LogBus2 official documentation:
+- User guide: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
+- Download link is in the official doc's "二、Download LogBus2" section
+
+Note: LogBus v1 is deprecated. Please use LogBus2.
+```
+
+---
+
+## Stage 5: Summary
+
+- Print all modified files + newly added events per file
+- Print LogBus2 config file path (daemon.json)
+- **Always provide LogBus2 official documentation link**
+- Guide user to start LogBus2:
+  1. Copy `daemon.json` to LogBus2 `conf/` directory
+  2. Run `./logbus start`
+- Suggest user consider running debug mode for verification
+
+---
+
+## Code Style
+
+- LoggerConsumer singleton: create `src/lib/TeTracking.java` (if not exists)
+- Prefix each track call with `// @tracking <event_name>` comment
+- Log path: `/data/ta_log/` (Linux) or `C:\ta_log\` (Windows)
+- Do NOT add try/catch (LoggerConsumer is fault-tolerant on its own)
+- Event names / property names strictly from plan, do not modify
+
+---
+
+## Pre-check
+
+- `git status --porcelain` not empty → refuse, prompt user to commit/stash first
+
+---
+
+## LoggerConsumer Configuration by Language
+
+| Language | LoggerConsumer Class | Log Format |
+|---|---|---|
+| Java | `LoggerConsumer` | JSON line |
+| Python | `TaLoggerConsumer` | JSON line |
+| Go | `LoggerConsumer` | JSON line |
+| Node.js | `LoggerConsumer` | JSON line |
+| PHP | `TE_LoggerConsumer` | JSON line |
+
+See wiki SDK docs for details.