siluzan-tso-cli 1.1.16 → 1.1.17-beta.2

package/README.md

@@ -43,7 +43,7 @@ HTML 报告模板引用以下 CDN：`cdn.tailwindcss.com`、`cdnjs.cloudflare.co
 在**用户的目标项目根目录**执行（根据用户使用的助手选择 `--ai`）：
 
 ```bash
-npm install -g siluzan-tso-cli
+npm install -g siluzan-tso-cli@beta
 siluzan-tso init --ai cursor         # 写入 Cursor（默认）
 siluzan-tso init --ai cursor,claude  # 同时写入多个平台
 siluzan-tso init --ai all            # 写入所有支持的平台
@@ -51,6 +51,7 @@ siluzan-tso init -d /path/to/skills  # 写入自定义目录
 siluzan-tso init --force             # 强制覆盖已存在文件
 ```
 
+> **注意**：当前为测试版（1.1.17-beta.2），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/dist/index.js

@@ -2791,7 +2791,7 @@ var DEFAULT_API_BASE;
 var init_defaults = __esm({
   "src/config/defaults.ts"() {
     "use strict";
-    DEFAULT_API_BASE = "https://tso-api.siluzan.com";
+    DEFAULT_API_BASE = "https://tso-api-ci.siluzan.com";
   }
 });
 
@@ -5949,7 +5949,7 @@ var init_google_analysis = __esm({
     SECTIONS = [
       {
         name: "overview",
-        description: "\u8D26\u6237\u603B\u89C8 OverviewSectionData",
+        description: "\u8D26\u6237\u603B\u89C8 OverviewSectionData\uFF08\u5B9E\u65F6\uFF0C\u53EF\u67E5\u5F53\u5929\uFF09",
         dateMode: "range",
         path: (id) => `/reporting/media-account/${id}/OverviewSectionData`
       },
@@ -6075,7 +6075,7 @@ var init_google_analysis = __esm({
       },
       {
         name: "campaign-types",
-        description: "\u5E7F\u544A\u7CFB\u5217\u7C7B\u578B\u6C47\u603B campaigns/types-summary",
+        description: "\u5E7F\u544A\u7CFB\u5217\u7C7B\u578B\u6C47\u603B campaigns/types-summary\uFF08\u5B9E\u65F6\uFF0C\u53EF\u67E5\u5F53\u5929\uFF09",
         dateMode: "none",
         path: (id) => `/reporting/media-account/${id}/campaigns/types-summary`
       }

package/dist/skill/SKILL.md

@@ -24,6 +24,8 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
   irm https://unpkg.com/siluzan-tso-cli@latest/dist/skill/scripts/install.ps1 | iex
   ```
 
+Windows 注意：部分 Agent 客户端通过 PowerShell / cmd 代执行命令时存在兼容性问题。若上述命令异常失败，请先安装 [Git for Windows](https://git-scm.com/download/win)，然后在 Git Bash 中执行 macOS / Linux / WSL 的 Bash 安装命令。
+
 参照 `references/setup.md` 完成安装与配置。
 
 ---
@@ -92,6 +94,7 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
 ### 硬规范
 
 - **账户状态 ≠ 广告系列状态**：`stats`/`balance`/`list-accounts` 的 `status` 只表示账户是否可用，系列状态**必须**来自 `ad campaigns`。
+- **数据时效性（实时 vs 每日同步）**：涉及「今天/当天/今日消耗」「实时消耗排行」前，**必须**先看 `references/account-analytics.md` 顶部「数据时效性」表选对接口（`accountsoverview` 系列接口同步昨天数据，不能查今天）。
 - **不确定时读文档**：先读对应 references 或用 `-h` 查看帮助，不要猜参数。
 - **先查账户再操作**：`list-accounts -m [mediaType] -k [mediaCustomerId]`。
 - **使用 `--json-out` 处理数据**：处理顺序：先读 `outlineFile`（schema 描述，扩展名 **`.outline.txt`** 不是 `.json`，**禁止 `require()`**，用 `fs.readFileSync(outlineFile,'utf8')` 取最后一行 TS 式类型字面量即可了解全部字段路径）→ 再让脚本读 `writtenFiles[0]`（真实数据 JSON）做聚合。**outline 通常几百字节、JSON 常见几 MB，先读 outline 能节省 2~3 个数量级的上下文**——尤其多账户多维度场景，直接 `Read` 全量 JSON 几次就把对话窗口塞满了。**禁止**把 outline 当数据、跳过 outline 猜字段、把 outline 内容贴给用户当结论。

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.16",
-  "publishedAt": 1778219223750
+  "version": "1.1.17-beta.2",
+  "publishedAt": 1778231004836
 }

package/dist/skill/references/account-analytics.md

@@ -4,6 +4,27 @@
 
 ---
 
+## 数据时效性（实时 vs 每日同步）—— 选命令前必读
+
+涉及"今天/当天/今日消耗""实时消耗排行"等问题时，**必须**先按此表确认接口口径，否则今天消耗会被误判为 0。
+
+| 命令 / 接口 | 时效性 | 能否查"今天" | 典型用途 |
+|---|---|---|---|
+| `google-analysis --sections overview`（Google 网关 `OverviewSectionData`） | **实时** | ✅ 可查当天 | 当天/今日消耗、当天高消耗账号排行 |
+| `google-analysis --sections campaign-types`（`types-summary`） | **实时** | ✅ 可查当天 | 当天系列类型分布 |
+| `google-analysis` 其他维度（`campaigns` / `keywords` / `devices` / ...） | 实时（受 Google Ads API 同步延迟影响） | 可查当天，但当天可能尚未结算 | 周期分析、报告 |
+| `stats`、`balance-scan` 的近 7 日消耗、`accounts-digest`、`list-accounts` 合并消耗（TSO `accountsoverview`） | **每日同步昨天** | ❌ 查今天会全为 0 | 历史回溯、巡检、余额续航估算（口径为"截至昨天"） |
+| `balance`（`GetMediaAccountInfo`） | 实时 | — | 仅当前余额，不反映消耗 |
+
+**选用规则**：
+
+- 「今天/当天/今日消耗」「实时消耗排行」 → 用 `google-analysis(-batch) --sections overview`，`--start` / `--end` 都设为今天
+- 「最近 N 天消耗 / 周报 / 月报 / 余额续航」 → `stats` / `balance-scan` / `accounts-digest`，默认窗口截至昨天即可
+- **禁止**用 `accountsoverview` 系列接口（`stats` / `balance-scan` / `accounts-digest` / `list-accounts` 合并消耗）判断当天消耗
+- **禁止**给当天高消耗场景加 `--min-spend`：该预筛选同样来自 `accountsoverview`，会把今天有消耗的账号当成 0 给筛掉
+
+---
+
 ## 默认做法（核心工作流）
 
 1. **先确认统计区间**：用户未给明确起止日期时**必须反问**（参见 SKILL.md 时间范围强制反问）。
@@ -63,7 +84,7 @@
 
 ## Google 账户分析：`google-analysis` 命令
 
-> **重要**：`google-analysis` 是统一入口，所有 21 个维度都通过 `--sections` 选取。关键词维度用 `--sections keywords`，**不要**用 `ad keywords` 代替。
+> **重要**：`google-analysis` 是统一入口，所有 21 个维度都通过 `--sections` 选取。关键词维度用 `--sections keywords`，**不要**用 `ad keywords` 代替。涉及「今天/当天」消耗的口径见本文顶部「数据时效性」表。
 
 ```bash
 # 单维度
@@ -100,7 +121,7 @@ siluzan-tso google-analysis -a <id> --exclude materials,gold-account --json-out
 
 | 维度 | 说明 |
 |------|------|
-| `overview` | 总览 |
+| `overview` | 总览（实时，可查当天；当天高消耗账号排行首选） |
 | `keywords` | 关键词；可选 `--limit`、`--no-order-by-cost` |
 | `search-terms` | 搜索词 |
 | `campaigns` | 广告系列 |
@@ -120,7 +141,7 @@ siluzan-tso google-analysis -a <id> --exclude materials,gold-account --json-out
 | `ads-index` | 质量指标 |
 | `final-urls` | 最终到达网址（不传 `--start`/`--end`） |
 | `dimension-summary` | 账户汇总 |
-| `campaign-types` | 系列类型（不传 `--start`/`--end`） |
+| `campaign-types` | 系列类型（实时，可查当天；不传 `--start`/`--end`） |
 
 ### stdout 摘要
 

package/dist/skill/references/accounts.md

@@ -127,7 +127,9 @@ siluzan-tso balance -m Google -a 6326027735 --json
 
 ---
 
-## stats — 查询投放消耗数据
+## stats — 查询投放消耗数据（每日同步昨天数据）
+
+> **数据时效性**：本接口口径为 `accountsoverview`，每日凌晨同步昨天数据，**不能查今天**。判断「今天/当天/今日消耗」请走 `google-analysis(-batch) --sections overview`。完整时效性表见 `references/account-analytics.md` 顶部。
 
 ```bash
 siluzan-tso stats -m <媒体类型> [选项]

package/dist/skill/references/finance.md

@@ -7,7 +7,7 @@
 
 ## invoice-info — 发票抬头管理
 
-对应页面：`https://www.siluzan.com/v3/foreign_trade/settings/invoiceInformation`
+对应页面：`https://www-ci.siluzan.com/v3/foreign_trade/settings/invoiceInformation`
 
 发票抬头是开票申请时使用的公司/企业信息模板，支持三种类型：
 
@@ -133,10 +133,10 @@ siluzan-tso config show
 **示例：**
 
 ```
-- 现金充值（单笔）：https://www.siluzan.com/recharge/pay
-- 现金充值（批量）：https://www.siluzan.com/recharge/pay_batch
-- 月结充值：        https://www.siluzan.com/recharge/accountBillingQuota
-- 丝路赞钱包：      https://www.siluzan.com/recharge/siluzanWallet
+- 现金充值（单笔）：https://www-ci.siluzan.com/recharge/pay
+- 现金充值（批量）：https://www-ci.siluzan.com/recharge/pay_batch
+- 月结充值：        https://www-ci.siluzan.com/recharge/accountBillingQuota
+- 丝路赞钱包：      https://www-ci.siluzan.com/recharge/siluzanWallet
 ```
 
 ---

package/dist/skill/references/google-analysis-batch.md

@@ -1,6 +1,8 @@
 # `google-analysis-batch` —— 多账户 × 多维度 Google 数据批处理引擎
 
 > 适用：账户数 ≥ 5 且需拉 ≥ 2 个 google-analysis 维度。**禁止**外层 for-loop 替代。中断后**必须** `resume`，不得重跑 `run`。
+>
+> **数据时效性**：维度的实时 / 每日同步口径见 `references/account-analytics.md` 顶部「数据时效性」表。当天高消耗排行只能用 `--sections overview`，且**禁止**加 `--min-spend`（其预筛选来自非实时 `accountsoverview`）。
 
 单 Node 进程，复用 keep-alive，双层并发（账户级 × 维度级），断点续跑，错误自动分类重试。
 

package/dist/skill/references/reporting.md

@@ -214,8 +214,8 @@ siluzan-tso report list -m Google --json
 
 # 第二步：查看 webUrl
 siluzan-tso config show
-# webUrl: https://www.siluzan.com
+# webUrl: https://www-ci.siluzan.com
 
 # 第三步：拼接链接（Google 日报）
-# https://www.siluzan.com/media-report/publish/rpt_abc123?culture=zh-CN
+# https://www-ci.siluzan.com/media-report/publish/rpt_abc123?culture=zh-CN
 ```

package/dist/skill/references/setup.md

@@ -10,7 +10,7 @@
 ## 安装 CLI
 
 ```bash
-npm install -g siluzan-tso-cli
+npm install -g siluzan-tso-cli@beta
 ```
 
 ---
@@ -47,7 +47,7 @@ siluzan-tso config set --api-key <Key>     # 或通过 config set 直接写入
 siluzan-tso config set --token <Token>     # 备用：设置 JWT Token
 ```
 
-API Key 获取入口：`https://www.siluzan.com/v3/foreign_trade/settings/apiKeyManagement`
+API Key 获取入口：`https://www-ci.siluzan.com/v3/foreign_trade/settings/apiKeyManagement`
 
 ### 通过环境变量传入凭据（CI/CD 推荐）
 
@@ -82,9 +82,9 @@ siluzan-tso config show
 
 ```
   构建环境     : production
-  apiBaseUrl   : https://tso-api.siluzan.com
-  googleApiUrl : https://googleapi.mysiluzan.com
-  webUrl       : https://www.siluzan.com
+  apiBaseUrl   : https://tso-api-ci.siluzan.com
+  googleApiUrl : https://googleapi-ci.mysiluzan.com
+  webUrl       : https://www-ci.siluzan.com
   apiKey       : abcd****1234
 ```
 

package/dist/skill/references/tso-home.md

@@ -6,7 +6,7 @@
 
 用 `siluzan-tso config show` 读取 **`webUrl`**，再拼接路径：
 
-首页地址：`https://www.siluzan.com/v3/foreign_trade/tso/home`
+首页地址：`https://www-ci.siluzan.com/v3/foreign_trade/tso/home`
 
 > 若用户已登录 TSO，也可从左侧菜单进入「首页」。
 

package/dist/skill/scripts/install.ps1

@@ -10,12 +10,14 @@ $ErrorActionPreference = 'Stop'
 $PKG_NAME    = 'siluzan-tso-cli'
 $CLI_BIN     = 'siluzan-tso'
 $SKILL_LABEL = 'Siluzan TSO'
-$INSTALL_CMD = 'npm install -g siluzan-tso-cli'
-$WEB_BASE    = 'https://www.siluzan.com'
+$INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'
+$WEB_BASE    = 'https://www-ci.siluzan.com'
 
 # -- Constants ----------------------------------------------------------------
-$NODE_MAJOR_MIN = 18
-$NPM_MIRROR     = 'https://registry.npmmirror.com'
+$NODE_MAJOR_MIN    = 18
+$NPM_MIRROR        = 'https://registry.npmmirror.com'
+# Git for Windows installer (mirrored on Siluzan CDN; bump version here when needed)
+$GIT_INSTALLER_URL = 'https://staticpn.siluzan.com/assets/git/Git-2.54.0-64-bit.exe'
 
 # -- Helpers ------------------------------------------------------------------
 function Write-Info  { param([string]$Msg) Write-Host "[OK] $Msg" -ForegroundColor Green }
@@ -80,6 +82,85 @@ function Install-NodeFallback {
     throw 'Node.js is required'
 }
 
+# -- Git for Windows ----------------------------------------------------------
+# Some agent clients (Cursor / Claude Code / etc.) have known quirks running
+# PowerShell or cmd commands. We install Git for Windows ahead of time so the
+# user always has a Git Bash fallback to run the equivalent bash installer
+# (`bash <(curl -fsSL .../install.sh)`) when the PowerShell channel misbehaves.
+function Test-GitInstalled {
+    return $null -ne (Get-Command git -ErrorAction SilentlyContinue)
+}
+
+function Test-IsAdmin {
+    try {
+        $id = [Security.Principal.WindowsIdentity]::GetCurrent()
+        $principal = New-Object Security.Principal.WindowsPrincipal($id)
+        return $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+    } catch {
+        return $false
+    }
+}
+
+function Install-Git {
+    $tmpFile = Join-Path $env:TEMP 'siluzan-git-installer.exe'
+
+    Write-Info "Downloading Git for Windows: $GIT_INSTALLER_URL"
+    try {
+        $prevProgress = $ProgressPreference
+        $ProgressPreference = 'SilentlyContinue'
+        Invoke-WebRequest -Uri $GIT_INSTALLER_URL -OutFile $tmpFile -UseBasicParsing
+        $ProgressPreference = $prevProgress
+    } catch {
+        Write-Warn "Git installer download failed: $($_.Exception.Message)"
+        return $false
+    }
+
+    if (-not (Test-Path $tmpFile)) {
+        Write-Warn 'Git installer file not found after download'
+        return $false
+    }
+
+    # Inno Setup silent flags. When not admin we point /DIR to %LOCALAPPDATA% so
+    # the installer doesn't try to write to Program Files (which would trigger UAC
+    # or just fail). The installer auto-detects ALLUSERS vs CURRENTUSER mode based
+    # on whether the current process is elevated, so we don't pass /CURRENTUSER
+    # explicitly (not all Git for Windows builds accept that flag).
+    $installArgs = @('/VERYSILENT', '/NORESTART', '/NOCANCEL', '/SP-', '/CLOSEAPPLICATIONS', '/RESTARTAPPLICATIONS')
+    if (Test-IsAdmin) {
+        Write-Info 'Installing Git for Windows system-wide (admin detected)...'
+    } else {
+        $userDir = Join-Path $env:LOCALAPPDATA 'Programs\Git'
+        Write-Info "Installing Git for Windows for current user: $userDir"
+        $installArgs += @("/DIR=$userDir")
+    }
+
+    try {
+        Start-Process -FilePath $tmpFile -ArgumentList $installArgs -Wait -NoNewWindow
+    } catch {
+        Write-Warn "Git installer launch failed: $($_.Exception.Message)"
+        Remove-Item $tmpFile -ErrorAction SilentlyContinue
+        return $false
+    }
+    Remove-Item $tmpFile -ErrorAction SilentlyContinue
+
+    Refresh-Path
+    if (-not (Test-GitInstalled)) {
+        # 安装器有时不会立刻刷新 PATH，按已知路径手动补一次
+        $candidates = @(
+            (Join-Path $env:LOCALAPPDATA 'Programs\Git\cmd'),
+            (Join-Path $env:ProgramFiles 'Git\cmd')
+        )
+        foreach ($p in $candidates) {
+            if (Test-Path (Join-Path $p 'git.exe')) {
+                $env:Path = "$p;$env:Path"
+                break
+            }
+        }
+    }
+
+    return Test-GitInstalled
+}
+
 # -- Main ---------------------------------------------------------------------
 function Main {
     Write-Host ''
@@ -119,6 +200,23 @@ function Main {
     }
     Write-Info 'npm ready'
 
+    # Git for Windows: pre-install as a Bash fallback path for agent clients
+    # whose PowerShell/cmd channel is unreliable. Failure here is non-fatal.
+    if (Test-GitInstalled) {
+        Write-Info 'Git for Windows already installed (Git Bash fallback ready)'
+    } else {
+        Write-Warn 'Git for Windows not found, installing as Bash fallback for agent clients...'
+        $gitOk = $false
+        try { $gitOk = Install-Git } catch { Write-Warn "Git install error: $($_.Exception.Message)" }
+        if ($gitOk) {
+            Write-Info 'Git for Windows installed (Git Bash fallback ready)'
+        } else {
+            Write-Warn 'Git for Windows install was skipped or failed; CLI install will continue.'
+            Write-Host '  If your agent later fails to run PowerShell commands, install Git manually:' -ForegroundColor DarkGray
+            Write-Host "  $GIT_INSTALLER_URL" -ForegroundColor DarkGray
+        }
+    }
+
     $currentRegistry = ''
     try { $currentRegistry = (npm config get registry 2>$null).Trim() } catch {}
     if ($currentRegistry -ne $NPM_MIRROR -and $currentRegistry -ne "$NPM_MIRROR/") {
@@ -160,6 +258,11 @@ function Main {
     Write-Host ''
     Write-Host "  Update CLI & Skill files: $CLI_BIN update"
     Write-Host ''
+    if (Test-GitInstalled) {
+        Write-Host '  Tip: if your agent client has trouble running PowerShell/cmd commands later,' -ForegroundColor DarkGray
+        Write-Host '       open Git Bash and re-run the equivalent bash installer instead.' -ForegroundColor DarkGray
+        Write-Host ''
+    }
     Write-Info "Need help? Visit $WEB_BASE"
     Write-Host ''
 }

package/dist/skill/scripts/install.sh

@@ -10,8 +10,8 @@ set -euo pipefail
 readonly PKG_NAME="siluzan-tso-cli"
 readonly CLI_BIN="siluzan-tso"
 readonly SKILL_LABEL="Siluzan TSO"
-readonly INSTALL_CMD="npm install -g siluzan-tso-cli"
-readonly WEB_BASE="https://www.siluzan.com"
+readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"
+readonly WEB_BASE="https://www-ci.siluzan.com"
 
 # -- Constants ----------------------------------------------------------------
 readonly NODE_MAJOR_MIN=18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siluzan-tso-cli",
-  "version": "1.1.16",
+  "version": "1.1.17-beta.2",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",