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

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.1），供内部测试使用。正式发布后安装命令将改为 `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.1",
+  "publishedAt": 1778229807646
 }

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,8 +10,8 @@ $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
@@ -87,6 +87,10 @@ function Main {
     Write-Host "|  $SKILL_LABEL -- Install                    |" -ForegroundColor White
     Write-Host '+---------------------------------------------+' -ForegroundColor White
     Write-Host ''
+    Write-Warn 'Windows note: some agent clients may fail when running PowerShell/cmd commands.'
+    Write-Host '  If this install fails unexpectedly, install Git for Windows and rerun the Bash installer in Git Bash:' -ForegroundColor DarkGray
+    Write-Host '  https://git-scm.com/download/win' -ForegroundColor DarkGray
+    Write-Host ''
 
     # Step 1: Environment check
     Write-Step 'Step 1/4: Environment check'

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.1",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",