@bluevs/ttcli 0.0.1 → 0.0.2

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@bluevs/ttcli",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "TikTok CLI - designed for AI Agent and developers",
   "bin": {
     "ttcli": "scripts/run.js"
   },
-  "scripts": {},
+  "scripts": {
+    "postinstall": "node -e \"console.log('\\n📦 ttcli installed. To install the openclaw skill, run:\\n  bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh\\n')\""
+  },
   "optionalDependencies": {
-    "@bluevs/ttcli-darwin-arm64": "0.0.1",
-    "@bluevs/ttcli-darwin-x64": "0.0.1",
-    "@bluevs/ttcli-linux-arm64": "0.0.1",
-    "@bluevs/ttcli-linux-x64": "0.0.1",
-    "@bluevs/ttcli-win32-arm64": "0.0.1",
-    "@bluevs/ttcli-win32-x64": "0.0.1"
+    "@bluevs/ttcli-darwin-arm64": "0.0.2",
+    "@bluevs/ttcli-darwin-x64": "0.0.2",
+    "@bluevs/ttcli-linux-arm64": "0.0.2",
+    "@bluevs/ttcli-linux-x64": "0.0.2",
+    "@bluevs/ttcli-win32-arm64": "0.0.2",
+    "@bluevs/ttcli-win32-x64": "0.0.2"
   },
   "engines": {
     "node": ">=16"
@@ -23,6 +25,7 @@
   },
   "license": "MIT",
   "files": [
-    "scripts/run.js"
+    "scripts/run.js",
+    "skills/"
   ]
 }

package/skills/ttcli/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: ttcli
+description: 直接调用 TikTok Marketing API（access token 鉴权，不经 VH 平台/项目层）。当用户提供原生 TikTok access_token + advertiser_id、要直连 TikTok 创建或查询 Smart+ campaign/adgroup/ad、或查 identity/app/region 等元数据时使用。注意：用户走 VH 项目流程（po_xxxx + account_id）的 TikTok 创编应改走 vhcli tiktok。
+---
+
+# TikTok CLI (`ttcli`)
+
+`ttcli` wraps TikTok Marketing API (`business-api.tiktok.com`) as a CLI optimized for AI agents. JSON output by default; the `--human` flag exists for project-owner debugging only — agents should never pass it.
+
+This skill is intentionally short. Always treat `ttcli -h` and `ttcli <subcommand> -h` as the primary reference for flags.
+
+## ttcli vs vhcli tiktok — 选哪一个
+
+openclaw 同时装了两个 TikTok 广告工具，触发条件不同：
+
+| 用户提供的上下文 | 用 |
+|---|---|
+| 原生 `access_token` + `advertiser_id`（用户从 TikTok Marketing 后台直接复制的）| **ttcli** |
+| `po_xxxx` 项目 ID、提到 VH 平台、`customer_project_id` / `account_id` | **vhcli tiktok** |
+| 想直连 TikTok 调试原生 API 行为 / 看真实错误码 | **ttcli** |
+| 想要 VH 的项目级审计、审批、异步任务 | **vhcli tiktok** |
+
+**鉴权材料是关键判断点**——access_token 直接给的走 ttcli，从 VH project 拿的走 vhcli。如果用户没说清楚，**先问**他要给你哪种 token，不要猜。
+
+
+## Installation
+
+```bash
+# 1) 装 CLI
+npm install -g @bluevs/ttcli
+
+# 2) 把 skill 同步到 openclaw workspace（一次即可；自动检测版本变化）
+bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh
+```
+
+`install-skill.sh` 会：
+- 检测 `ttcli` 是否在 PATH，没有就 `npm install -g @bluevs/ttcli`
+- 把 `SKILL.md` 拷到 `${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}/skills/ttcli/SKILL.md`
+- 用 `.installed_version` 文件追踪版本，相同则跳过
+- 若本机同时存在 `~/.claude/skills/`（开发机），顺手同步一份
+
+升级 ttcli：重跑 `npm install -g @bluevs/ttcli` 然后再跑一次 `install-skill.sh`，会自动检测到版本变化并替换 SKILL.md。
+
+## Trigger
+
+Use when the user wants to:
+- Create / list TikTok Smart+ campaigns or adgroups
+- Look up `app_id`, `location_id`, or other targeting metadata
+- Set or inspect TikTok API credentials
+
+## Network: requires HTTPS_PROXY in mainland China
+
+`business-api.tiktok.com` is unreachable from mainland China without a proxy. Go's default HTTP transport honors `HTTPS_PROXY`, so:
+
+```
+HTTPS_PROXY=http://127.0.0.1:7897 ttcli ...
+```
+
+If you see `context deadline exceeded` or `dial: connection refused`, check this first.
+
+## Output: JSON by default
+
+`ttcli` writes pretty-printed JSON to stdout. Pipe to `jq` / `python -m json.tool` to extract fields. There is no `--json` flag — JSON is the default. stderr carries logs and prompts (`auto-generated request_id: ...`, `saved credentials to ...`); never mix it into stdout consumers.
+
+## Discovery before write
+
+Before creating a campaign or adgroup, gather the IDs you'll reference:
+
+```
+ttcli auth show                       # confirm credentials loaded + their source
+ttcli app list                        # → app_id
+ttcli smart-plus campaign list        # → existing campaign_id (or you'll create one)
+ttcli tool region \
+  --placements=PLACEMENT_TIKTOK \
+  --objective-type=APP_PROMOTION \
+  --level-range=TO_COUNTRY            # → location_id for targeting_spec.location_ids
+```
+
+`tool region` accepts `--language=zh-CN` (or any of 78 supported codes) for localized region names — useful when surfacing options to the user.
+
+## Write safety: ALWAYS dry-run first
+
+`smart-plus campaign create` and `smart-plus adgroup create` create real entities in the TikTok account that persist until deleted. Run with `--dry-run` first, inspect the merged body, only then re-run without it.
+
+Default `operation_status` per command:
+- `campaign create` → TikTok's default `ENABLE`. Pass `--operation-status=DISABLE` for safe testing.
+- `adgroup create` → ttcli forces `DISABLE` (overriding TikTok's `ENABLE`). Do NOT set `--operation-status=ENABLE` unless the user explicitly asks.
+
+A `DISABLE` campaign or adgroup creates the entity but does not run / spend.
+
+## Two write patterns
+
+These two endpoints differ in scale; they use different CLI styles.
+
+### `smart-plus campaign create` — flag-driven
+
+Roughly 25 fields, all exposed as flags:
+
+```
+ttcli smart-plus campaign create \
+  --objective-type=APP_PROMOTION \
+  --app-promotion-type=APP_INSTALL \
+  --campaign-name="my_test" \
+  --budget=20 \
+  --operation-status=DISABLE \
+  --dry-run
+```
+
+See `ttcli smart-plus campaign create --help` for the full flag list (objective_type / sales_destination / catalog / budget_mode / RTA etc.).
+
+### `smart-plus adgroup create` — JSON body + essential flag overrides
+
+80+ fields with nested `targeting_spec`, multiple nested arrays. Body is the source of truth; flags override only 5 essential keys.
+
+```
+ttcli smart-plus adgroup create \
+  --body-from-file=adgroup.json \    # OR --body=- to read from stdin / pipe
+  --campaign-id=<id> \
+  --dry-run
+```
+
+Body sources (mutually exclusive):
+- `--body='{...}'` — inline JSON literal
+- `--body=-` — read from stdin
+- `--body-from-file=PATH` — read from file
+
+The 5 essential flags that override matching body keys:
+- `--advertiser-id` (global), `--campaign-id`, `--request-id`, `--operation-status`, `--dry-run`
+
+Do NOT try to flag fields like `adgroup_name`, `bid_price`, `targeting_spec` — they belong in the body. The CLI will not expose flags for them.
+
+Minimal Android APP_INSTALL adgroup body (use as a template):
+
+```json
+{
+  "adgroup_name": "...",
+  "app_id": "...",
+  "promotion_type": "APP_ANDROID",
+  "optimization_goal": "INSTALL",
+  "bid_type": "BID_TYPE_NO_BID",
+  "billing_event": "OCPM",
+  "schedule_type": "SCHEDULE_START_END",
+  "schedule_start_time": "YYYY-MM-DD HH:MM:SS",
+  "schedule_end_time": "YYYY-MM-DD HH:MM:SS",
+  "targeting_optimization_mode": "AUTOMATIC",
+  "targeting_spec": {
+    "location_ids": ["..."],
+    "spc_audience_age": "OVER_EIGHTEEN",
+    "operating_systems": ["ANDROID"]
+  }
+}
+```
+
+11 unconditionally-required fields are validated client-side: `advertiser_id`, `request_id`, `campaign_id`, `adgroup_name`, `promotion_type`, `optimization_goal`, `bid_type`, `billing_event`, `schedule_type`, `schedule_start_time`, `targeting_spec`. The first three are usually injected from flags.
+
+## MINI_GAME (TikTok Minis) — verified configuration
+
+Creating MINI_GAME adgroups has many undocumented or scattered constraints. The combination below was end-to-end verified. Use as the starting template; do not relax fields without a specific reason.
+
+**Campaign must be CBO=off + INFINITE**:
+
+```
+ttcli smart-plus campaign create \
+  --objective-type=APP_PROMOTION \
+  --app-promotion-type=MINIS \
+  --campaign-name="..." \
+  --budget-optimize-on=false \
+  --budget-mode=BUDGET_MODE_INFINITE \
+  --operation-status=DISABLE
+```
+
+**Adgroup body** (MINI_GAME with VALUE/ROAS optimization):
+
+```json
+{
+  "adgroup_name": "...",
+  "minis_id": "<minis-id>",
+  "promotion_type": "MINI_GAME",
+  "placement_type": "PLACEMENT_TYPE_NORMAL",
+  "placements": ["PLACEMENT_TIKTOK"],
+  "budget_mode": "BUDGET_MODE_DYNAMIC_DAILY_BUDGET",
+  "budget": 50,
+  "schedule_type": "SCHEDULE_FROM_NOW",
+  "schedule_start_time": "YYYY-MM-DD HH:MM:SS",
+  "schedule_end_time": "YYYY-MM-DD HH:MM:SS",
+  "optimization_goal": "VALUE",
+  "optimization_event": "AD_REVENUE_VALUE",
+  "billing_event": "OCPM",
+  "bid_type": "BID_TYPE_NO_BID",
+  "deep_bid_type": "VO_MIN_ROAS",
+  "roas_bid": 1,
+  "vbo_window": "ZERO_DAY",
+  "click_attribution_window": "THIRTY_DAYS",
+  "view_attribution_window": "OFF",
+  "engaged_view_attribution_window": "OFF",
+  "targeting_optimization_mode": "AUTOMATIC",
+  "targeting_spec": {
+    "age_groups": ["AGE_18_24","AGE_25_34","AGE_35_44","AGE_45_54","AGE_55_100"],
+    "gender": "GENDER_UNLIMITED",
+    "location_ids": ["6252001"],
+    "spc_audience_age": "OVER_EIGHTEEN"
+  }
+}
+```
+
+**MINI_GAME-specific constraints discovered through trial**:
+
+| Constraint | Symptom if violated |
+|---|---|
+| `optimization_goal` MUST be `VALUE` (not INSTALL/CLICK/IN_APP_EVENT) | `40002 Invalid optimization goal. Please change your goal or promotion type.` |
+| `optimization_event` for VALUE goal: `AD_REVENUE_VALUE` (TikTok normalizes to `IMPRESSION_LEVEL_AD_REVENUE`) | `40002 Invalid event` |
+| `deep_bid_type` MUST be `VO_MIN_ROAS` for VALUE | implicit failure |
+| `roas_bid` REQUIRED when `VO_MIN_ROAS` (range 0.01–1000) | implicit failure |
+| `vbo_window` REQUIRED for VO_MIN_ROAS, `ZERO_DAY` or `SEVEN_DAYS` | implicit failure |
+| `placement_type` MUST be `PLACEMENT_TYPE_NORMAL` (not AUTOMATIC) | `40002 placement_type only supports 'PLACEMENT_TYPE_NORMAL'.` |
+| `placements` MUST contain `PLACEMENT_TIKTOK` (Minis only run on TikTok) | will fail validation |
+| `click_attribution_window` MUST be `THIRTY_DAYS` (only valid value for MINI_GAME) | implicit failure |
+| `budget_mode` MUST be `BUDGET_MODE_DYNAMIC_DAILY_BUDGET` (not INFINITE) when using `VO_MIN_ROAS` | `40002 This ad does not support infinite budget mode.` |
+| Campaign-level CBO must be off if you set adgroup-level `budget_mode` | `40002 Something went wrong. Contact support.` (opaque; pure trial-and-error) |
+| `app_id` MUST NOT be set; use `minis_id` instead | `40002 The app(app_id: ...) info does not exist` |
+
+**Failure mode: opaque "Allowlist not enabled"**
+
+Some MINI_GAME features (VO_MIN_ROAS, vbo_window=ZERO_DAY, BID_TYPE_NO_BID for max delivery) are whitelist-gated for new advertisers. The error message just says `Allowlist not enabled` without specifying which field. If you hit this, ask the user to:
+1. Confirm in TikTok Ads Manager that an existing MINI_GAME adgroup with similar settings runs successfully on this advertiser.
+2. If not: contact TikTok sales rep to enable the relevant whitelist.
+
+**MINI_APP (short drama) variant**
+
+If `promotion_type=MINI_APP` (short drama series, not games), some fields differ. Doc gives `THIRTY_TWO_DAYS` and `ONE_HUNDRED_EIGHTY_DAYS` `click_attribution_window` for MINI_APP+`ACTIVE_PAY` — these constraints are MINI_APP-specific. Reuse the MINI_GAME template above and adjust if user wants short drama promotion.
+
+## Ad creation (`smart-plus ad create`)
+
+Creates one or more ads under an adgroup. The endpoint has no `request_id` field — no idempotency design at this level.
+
+**Body sources** (same pattern as adgroup): `--body=...` / `--body=-` / `--body-from-file=PATH`.
+
+**Essential flag overrides**:
+- `--advertiser-id` (global), `--adgroup-id`, `--operation-status` (defaults to DISABLE), `--dry-run`
+
+**Required body fields**: `creative_list` (non-empty array). `advertiser_id` and `adgroup_id` typically injected from flags.
+
+**TikTok placement → MUST use Spark Ads**
+
+Per the doc: "对于现有广告账号，当广告组的投放广告位为自动版位或手动广告位且包含 TikTok 时，已不再支持使用自定义身份创建非 Spark Ads。" Translation: non-Spark Ads no longer allowed on TikTok placement. Since MINI_GAME / MINI_APP / most adgroups use `PLACEMENT_TIKTOK`, you MUST use Spark Ads:
+
+```json
+{
+  "creative_list": [
+    {
+      "creative_info": {
+        "ad_format": "SINGLE_VIDEO",
+        "tiktok_item_id": "<existing TikTok video post ID>",
+        "identity_type": "TT_USER",
+        "identity_id": "<advertiser identity>"
+      }
+    }
+  ],
+  "landing_page_url_list": [{"landing_page_url": "..."}]
+}
+```
+
+**Helper APIs needed (NOT yet wrapped by ttcli — block real ad creation)**:
+
+| Need | Endpoint | ttcli command |
+|---|---|---|
+| List identities under advertiser | `/identity/get/` | `ttcli identity list` (filter by `--identity-type`) |
+| `tiktok_item_id` (Spark Ads) | `/tt_video/info/` | `ttcli tt-video info --auth-code=...` |
+| List posts under an identity | `/identity/video/get/` | `ttcli identity video list --identity-id=... --identity-type=...` |
+| Verify `identity_id` | `/identity/info/` | `ttcli identity info --identity-id=... --identity-type=...` |
+| Upload video → `video_id` | `/file/video/ad/upload/` | ⏳ not yet wrapped (rare; non-Spark only) |
+| Upload image → `web_uri` | `/file/image/ad/upload/` | ⏳ not yet wrapped |
+| Music → `music_id` | (separate music API) | ⏳ not yet wrapped |
+
+Without the upload helpers you cannot do non-Spark ads, but for any TikTok-placement ad (which is everything MINI_GAME / MINI_APP / most APP_PROMOTION) Spark Ads is mandatory anyway, and the Spark Ads pipeline is fully discoverable via `tt-video info` or `identity video list`.
+
+## Spark Ads discovery flow
+
+For MINI_GAME or any TikTok-placement ad creation:
+
+1. **List identities under the advertiser** (no auth_code needed if you already have managed identities):
+   ```
+   ttcli --human identity list --identity-type=BC_AUTH_TT
+   ```
+   Pick one with `available_status=AVAILABLE`. The `identity_id` and `identity_type` go into the ad body.
+2. **Or, get an auth_code from a creator**: TikTok app → 帖子 → 三点菜单 → 广告设置 → 开启"广告授权" → 选择授权时长 → 复制授权码
+3. **Resolve auth_code to `item_id` + `identity_id`**:
+   ```
+   ttcli tt-video info --auth-code='AUTH_CODE_FROM_STEP_2'
+   ```
+   Returns `item_info.item_id` (→ `creative_info.tiktok_item_id`) and `user_info.identity_id` + `user_info.identity_type`.
+4. **List videos under a known identity** (skip step 2-3 if the identity already has authorized posts):
+   ```
+   ttcli identity video list --identity-id=... --identity-type=TT_USER
+   ```
+   Returned `item_id` values used directly as `tiktok_item_id`.
+5. **Optionally verify identity health** before submitting:
+   ```
+   ttcli identity info --identity-id=... --identity-type=...
+   ```
+   Confirm `available_status=AVAILABLE` and `is_gpppa=false` (GPPPA accounts can't run Spark Ads).
+
+Note: TikTok identity-list pagination requires `identity_type` to be set — without a type filter, `page_info` is null in the response.
+
+## Idempotency: reuse request_id on retry
+
+Without `--request-id`, ttcli generates one from `time.Now().UnixNano()` and logs it to stderr:
+
+```
+auto-generated request_id: 1780447951510460000 (use --request-id=... to retry idempotently)
+```
+
+If a write fails (network, timeout) and you want to retry without creating a duplicate, capture and pass that same `request_id`. TikTok dedupes on this field — a second submission with the same ID returns the original result, not a new entity.
+
+## Errors
+
+ttcli errors carry TikTok's `code`, `message`, and `request_id` (the API request ID, distinct from the idempotency one):
+
+```
+Error: tiktok api error: code=40105 message="Access token is incorrect or has been revoked." request_id=20260602185506...
+```
+
+Common codes:
+- `40105` → access token invalid or revoked. Tell the user to refresh.
+- `40001` → token has no permission for the advertiser_id in use. Likely `TIKTOK_ADVERTISER_ID` doesn't match what the token was authorized for.
+
+The CLI does NOT validate enum values, type correctness, or conditional-required fields. It only checks that unconditionally required fields are present. TikTok is the source of truth for everything else — surface its error messages directly.
+
+## Credentials
+
+Priority: `--flag` > env var > config file (`~/.config/ttcli/credentials.json`, mode 0600).
+
+| Field | Flag | Env |
+|---|---|---|
+| Access token | `--token` | `TIKTOK_ACCESS_TOKEN` |
+| Advertiser ID | `--advertiser-id` | `TIKTOK_ADVERTISER_ID` |
+| Base URL | `--base-url` | `TIKTOK_BASE_URL` |
+
+Persist for the local user with:
+
+```
+ttcli auth set --token=... --advertiser-id=...
+```
+
+`auth show` reports each value and where it came from (`flag` / `env:VAR` / `file` / `default` / `unset`); useful when a write fails with `40001` and you suspect the wrong advertiser is being used.
+
+## Standard end-to-end flow
+
+1. `ttcli auth show` — confirm credentials
+2. `ttcli app list` → pick `app_id`
+3. `ttcli tool region --placements=... --objective-type=...` → pick `location_id`
+4. `ttcli smart-plus campaign create --dry-run ...` → review body
+5. `ttcli smart-plus campaign create ...` → capture `campaign_id` from JSON response
+6. Build adgroup body JSON (heredoc / temp file)
+7. `ttcli smart-plus adgroup create --dry-run --body-from-file=... --campaign-id=...` → review merged body
+8. Same command without `--dry-run` → adgroup created in `DISABLE` state by default

package/skills/ttcli/scripts/install-skill.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# install-skill.sh — ttcli + skill 双向依赖检测与安装
+#
+# 入口场景：
+#   A) 已装 skill，确保 ttcli CLI 可用（缺则自动 npm install）
+#   B) 已装 ttcli CLI，确保 skill 同步到 openclaw workspace
+#   开发期奖励：若本机存在 ~/.claude/skills/，也同步一份方便 Claude Code 调试
+#
+# 用法:
+#   bash <path>/install-skill.sh
+#
+# 调用点：
+#   - 开发期 release.command 末尾（从仓库源同步）
+#   - 服务器 npm install 后手动跑（从 npm pkg 同步）
+#     bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh
+
+set -euo pipefail
+
+# 源目录：脚本所在目录的父目录就是 skill 目录（含 SKILL.md）
+SOURCE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SKILL_FILE="$SOURCE_DIR/SKILL.md"
+
+if [ ! -f "$SKILL_FILE" ]; then
+  echo "❌ SKILL.md not found at $SKILL_FILE"
+  exit 1
+fi
+
+# Target：openclaw workspace
+WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
+WORKSPACE_SKILL_DIR="$WORKSPACE/skills/ttcli"
+
+# npm 包路径（用于 CLI 缺失时反查）
+NPM_ROOT="$(npm root -g 2>/dev/null || echo '')"
+PKG_DIR="${NPM_ROOT:+$NPM_ROOT/@bluevs/ttcli}"
+
+# 版本来源：尽量从 npm 包 package.json 读；本地 release 时退化为 SKILL.md mtime
+get_version() {
+  if [ -n "$PKG_DIR" ] && [ -f "$PKG_DIR/package.json" ]; then
+    node -p "require('$PKG_DIR/package.json').version" 2>/dev/null && return
+  fi
+  # 本地 release 模式：用 SKILL.md 的 mtime 当版本戳
+  date -r "$SKILL_FILE" "+local-%Y%m%d-%H%M%S" 2>/dev/null || echo "local-unknown"
+}
+
+# ============================================================
+# 方向 A：确保 ttcli CLI 可用
+# ============================================================
+check_cli() {
+  if command -v ttcli &>/dev/null; then
+    echo "✅ ttcli CLI ready ($(ttcli --help 2>&1 | head -1 || echo 'ok'))"
+    return 0
+  fi
+  echo "⚠️  ttcli CLI 未安装，尝试 npm install -g @bluevs/ttcli ..."
+  if npm install -g @bluevs/ttcli 2>&1 | tail -3; then
+    if command -v ttcli &>/dev/null; then
+      echo "✅ ttcli CLI 安装成功"
+      NPM_ROOT="$(npm root -g 2>/dev/null || echo '')"
+      PKG_DIR="${NPM_ROOT:+$NPM_ROOT/@bluevs/ttcli}"
+      return 0
+    fi
+  fi
+  echo "❌ npm install 失败。请手动: npm install -g @bluevs/ttcli"
+  return 1
+}
+
+# ============================================================
+# 方向 B：把 skill 同步到 target
+# ============================================================
+sync_to() {
+  local target_dir="$1"
+  local label="$2"
+  local version_file="$target_dir/.installed_version"
+
+  local source_version="$(get_version)"
+
+  if [ -f "$version_file" ]; then
+    local installed_version="$(cat "$version_file")"
+    if [ "$installed_version" = "$source_version" ]; then
+      echo "✅ $label skill 已是 ${source_version}，跳过"
+      return 0
+    fi
+    echo "🔄 $label skill: $installed_version → $source_version"
+  else
+    echo "📦 $label skill 首次安装 ($source_version)"
+  fi
+
+  mkdir -p "$target_dir"
+  cp -f "$SKILL_FILE" "$target_dir/SKILL.md"
+
+  # 未来 docs/ 目录加进来时自动 sync（当前可能无）
+  if [ -d "$SOURCE_DIR/docs" ]; then
+    mkdir -p "$target_dir/docs"
+    cp -f "$SOURCE_DIR/docs/"*.md "$target_dir/docs/" 2>/dev/null || true
+  fi
+
+  echo "$source_version" > "$version_file"
+  echo "✅ $label → $target_dir/SKILL.md"
+}
+
+# ============================================================
+# 主流程
+# ============================================================
+echo "=== ttcli skill 安装 ==="
+echo "  source: $SOURCE_DIR"
+echo ""
+
+check_cli || exit 1
+echo ""
+
+# 主 target: openclaw workspace（永远 sync）
+sync_to "$WORKSPACE_SKILL_DIR" "openclaw"
+
+# 副 target: 本机 Claude Code（开发期才有）
+if [ -d "$HOME/.claude/skills" ]; then
+  echo ""
+  sync_to "$HOME/.claude/skills/ttcli" "claude-code (dev)"
+fi
+
+echo ""
+echo "=== 完成 ==="