siluzan-tso-cli 1.1.28-beta.3 → 1.1.28-beta.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/skill/SKILL.md +9 -8
- package/dist/skill/_meta.json +2 -2
- package/dist/skill/references/core/cli-enums.md +0 -2
- package/dist/skill/report-templates/google-inquiry-analysis.md +1 -1
- package/dist/skill/scripts/install.ps1 +1 -1
- package/dist/skill/scripts/install.sh +1 -1
- package/package.json +1 -1
- package/dist/skill/docs/skill-guide.md +0 -44
- package/dist/skill/references/core/skill-authoring.md +0 -196
package/README.md
CHANGED
|
@@ -51,7 +51,7 @@ siluzan-tso init -d /path/to/skills # 写入自定义目录
|
|
|
51
51
|
siluzan-tso init --force # 强制覆盖已存在文件
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
> **注意**：当前为测试版（1.1.28-beta.
|
|
54
|
+
> **注意**：当前为测试版（1.1.28-beta.4），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
|
|
55
55
|
|
|
56
56
|
| 助手 | 建议 `--ai` |
|
|
57
57
|
| ----------------------- | ------------------------------------ |
|
package/dist/skill/SKILL.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: siluzan-tso
|
|
3
|
-
description:
|
|
3
|
+
description: 通过 siluzan-tso-cli 操作丝路赞 TSO 广告账户（Google/Bing/Yandex/TikTok/Kwai/MetaAd）。（账户）列表、余额、统计、消耗、激活账单、历史、余额扫描 P2、账户摘要 P3、共享/取消共享、解绑、OAuth、MCC/BC/BM 绑定解绑、邮件邀请、TikTok 关闭、暂停撤回；（开户）六大媒体申请；（Google Ads）系列/广告组/广告/关键词 CRUD、附加信息、地理位置、PMax、搜索投放方案校验/创建、批量异步创建；（分析）google-analysis、google-analysis-batch P5、facebook-analysis P4-FB、网站诊断 P8、市场分析 P9、广告诊断；P1 账户画像、P4 周期报告、P6 OKKI 周报、P7 询盘分析；Google关键词推荐、RAG 检索、TSO 报告列表/创建/推送、智能预警、TikTok/Meta 线索、转账/发票/发票资料、审计恢复。当用户提及广告账户、余额、消耗、投放、关键词、开户、MCC/BC、报告、诊断、市场分析、开票或 TSO 时使用。
|
|
4
4
|
license: MIT
|
|
5
|
-
compatibility:
|
|
5
|
+
compatibility: 需要 Node.js 18+、已安装 siluzan-tso-cli，通过 send-login-code + login 或 config set 完成鉴权
|
|
6
6
|
metadata:
|
|
7
7
|
requires: nodejs,siluzan-tso-cli
|
|
8
8
|
allowed-tools: Bash(siluzan-tso:*) Read Write
|
|
@@ -44,13 +44,14 @@ Windows：部分 Agent 通过 PowerShell 代执行时可能失败，改在 [Git
|
|
|
44
44
|
|
|
45
45
|
---
|
|
46
46
|
|
|
47
|
-
## 可执行的操作范围
|
|
48
47
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
48
|
+
## 基本使用
|
|
49
|
+
|
|
50
|
+
siluzan-tso-cli只是报名, 安装后可执行的命令是 siluzan-tso
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
siluzan-tso -h // 查看帮助
|
|
54
|
+
```
|
|
54
55
|
|
|
55
56
|
---
|
|
56
57
|
|
package/dist/skill/_meta.json
CHANGED
|
@@ -159,7 +159,7 @@ Sheet 5 整段系列明细读：`./snap-inquiry/campaigns-<accountId>_<S>-<E>.js
|
|
|
159
159
|
|
|
160
160
|
## 国家 → 大洲映射
|
|
161
161
|
|
|
162
|
-
- **数据源**：`references/analytics/geo-continents.json
|
|
162
|
+
- **数据源**：`references/analytics/geo-continents.json`
|
|
163
163
|
- **默认 7 桶**：`亚洲` / `中东` / `欧洲` / `北美` / `南美` / `非洲` / `大洋洲`。
|
|
164
164
|
- **运营常用 5 桶合并**（与样表 Sheet 3 一致）：`<重点国>` / `中东` / `非洲` / `欧美` / `亚洲(除重点国)`。**由脚本在写表前做二次合并**，伪代码：
|
|
165
165
|
|
|
@@ -9,7 +9,7 @@ $ErrorActionPreference = 'Stop'
|
|
|
9
9
|
# -- Package info (injected at build time) ------------------------------------
|
|
10
10
|
$PKG_NAME = 'siluzan-tso-cli'
|
|
11
11
|
# PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
|
|
12
|
-
$PKG_VERSION = '1.1.28-beta.
|
|
12
|
+
$PKG_VERSION = '1.1.28-beta.4'
|
|
13
13
|
$CLI_BIN = 'siluzan-tso'
|
|
14
14
|
$SKILL_LABEL = 'Siluzan TSO'
|
|
15
15
|
$INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'
|
|
@@ -9,7 +9,7 @@ set -euo pipefail
|
|
|
9
9
|
# -- Package info (injected at build time) ------------------------------------
|
|
10
10
|
readonly PKG_NAME="siluzan-tso-cli"
|
|
11
11
|
# PKG_VERSION 锁定到与本脚本同批构建产物一致的版本，避免与 dist/skill 错位
|
|
12
|
-
readonly PKG_VERSION="1.1.28-beta.
|
|
12
|
+
readonly PKG_VERSION="1.1.28-beta.4"
|
|
13
13
|
readonly CLI_BIN="siluzan-tso"
|
|
14
14
|
readonly SKILL_LABEL="Siluzan TSO"
|
|
15
15
|
readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"
|
package/package.json
CHANGED
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
# Siluzan TSO Skill — 人类导读
|
|
2
|
-
|
|
3
|
-
Agent 运行时请用 `SKILL.md` + `AGENTS.md`；本文供维护者与产品经理深读。
|
|
4
|
-
|
|
5
|
-
## 设计理念（对齐 gstack）
|
|
6
|
-
|
|
7
|
-
1. **薄入口**：`SKILL.md` 仅路由，<150 行
|
|
8
|
-
2. **域化 references**：`core/`、`accounts/`、`google-ads/`、`analytics/`、`operations/`
|
|
9
|
-
3. **渐进披露**：Playbook、参数表、SOP 按需 Read，不塞进主文件
|
|
10
|
-
4. **模板分离**：`assets/*.json` 契约 vs `report-templates/*.md` 内容纲要
|
|
11
|
-
|
|
12
|
-
## 目录树
|
|
13
|
-
|
|
14
|
-
```
|
|
15
|
-
siluzan-ads/
|
|
16
|
-
├── AGENTS.md # Agent 域目录（类似 gstack AGENTS.md）
|
|
17
|
-
├── SKILL.md # 路由入口
|
|
18
|
-
├── docs/skill-guide.md # 本文件
|
|
19
|
-
├── references/
|
|
20
|
-
│ ├── core/ # 纪律、安装、playbooks
|
|
21
|
-
│ ├── accounts/ # 账户、开户、财务
|
|
22
|
-
│ ├── google-ads/ # CLI 命令 + rules/ SOP
|
|
23
|
-
│ ├── analytics/ # 拉数、批处理、拓词
|
|
24
|
-
│ └── operations/ # 预警、线索、自动化
|
|
25
|
-
├── assets/ # JSON/MD 创建契约
|
|
26
|
-
└── report-templates/ # 报告纲要 + HTML 样式
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
## 常见维护任务
|
|
30
|
-
|
|
31
|
-
| 任务 | 改哪里 |
|
|
32
|
-
| --- | --- |
|
|
33
|
-
| 新 CLI 命令 | `src/commands/` + 对应 `references/<域>/` |
|
|
34
|
-
| 新 Playbook | `references/core/playbooks.md` + `SKILL.md` 任务表 |
|
|
35
|
-
| 环境 URL | `scripts/write-defaults.mjs` + `copy-skill-assets.mjs` |
|
|
36
|
-
| 发布 Skill | `npm run build:prod` → `siluzan-tso init --force` |
|
|
37
|
-
|
|
38
|
-
## 与 eval 的关系
|
|
39
|
-
|
|
40
|
-
场景 JSON 中 `judgeReferencePaths` 须使用域路径，例如 `references/accounts/accounts.md`。改文档后运行：
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
pnpm --filter siluzan-tso-cli run eval:export-cases
|
|
44
|
-
```
|
|
@@ -1,196 +0,0 @@
|
|
|
1
|
-
# Agent SKILL 最佳实践（siluzan-tso 维护指南）
|
|
2
|
-
|
|
3
|
-
本文档基于 [Agent Skills 开放规范](https://agentskills.io/specification) 与 [Cursor Skills 文档](https://cursor.com/docs/skills)，结合 siluzan-skill monorepo 的 TSO 实践，供维护 `tso-cli/assets/siluzan-ads/` 时对照。
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## 1. 协议要点（agentskills.io）
|
|
8
|
-
|
|
9
|
-
### 1.1 目录结构
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
siluzan-tso/ # 安装后目录名
|
|
13
|
-
├── AGENTS.md # Agent 域目录（gstack 风格）
|
|
14
|
-
├── SKILL.md.tmpl → SKILL.md # 构建生成
|
|
15
|
-
├── snippets/ # 共享注入块
|
|
16
|
-
├── docs/skill-guide.md # 人类导读
|
|
17
|
-
├── snippets/ # agent-preamble、handoff-p5/p6/p7（构建时注入 SKILL 或随包复制）
|
|
18
|
-
├── references/
|
|
19
|
-
│ ├── core/ # 纪律、安装、playbooks、subagent-orchestration
|
|
20
|
-
│ ├── accounts/ # 账户、开户、财务
|
|
21
|
-
│ ├── google-ads/ # CLI + rules/
|
|
22
|
-
│ ├── analytics/ # 拉数、批处理、拓词
|
|
23
|
-
│ └── operations/ # 预警、线索、自动化
|
|
24
|
-
├── assets/
|
|
25
|
-
└── report-templates/
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
源码位于 `tso-cli/assets/siluzan-ads/`，构建时 `copy-skill-assets.mjs` 替换占位符后写入 `dist/skill/`。
|
|
29
|
-
|
|
30
|
-
### 1.2 SKILL.md frontmatter
|
|
31
|
-
|
|
32
|
-
| 字段 | 要求 | siluzan-tso 用法 |
|
|
33
|
-
| ---- | ---- | ---------------- |
|
|
34
|
-
| `name` | 小写+连字符，≤64 字，**须与安装目录名一致** | `siluzan-tso`（非 `siluzan-ads`） |
|
|
35
|
-
| `description` | ≤1024 字，**第三人称**，含 WHAT + WHEN + 触发词 | 列出媒体、开户、Google Ads、报告、预警等 |
|
|
36
|
-
| `license` | 可选 | `MIT` |
|
|
37
|
-
| `compatibility` | 可选，≤500 字，环境依赖 | Node 18+、`siluzan-tso-cli`、鉴权 |
|
|
38
|
-
| `metadata` | 可选键值 | `requires: nodejs,siluzan-tso-cli` |
|
|
39
|
-
| `allowed-tools` | 可选（实验性） | `Bash(siluzan-tso:*) Read Write` |
|
|
40
|
-
| `disable-model-invocation` | Cursor 扩展 | TSO 需自动激活，**不设** true |
|
|
41
|
-
|
|
42
|
-
### 1.3 渐进式披露（三层加载）
|
|
43
|
-
|
|
44
|
-
| 层级 | 内容 | Token 预算建议 |
|
|
45
|
-
| ---- | ---- | -------------- |
|
|
46
|
-
| L1 元数据 | `name` + `description` | ~100 tokens，启动时索引 |
|
|
47
|
-
| L2 指令 | `SKILL.md` 正文 | <500 行，<5000 tokens，激活时加载 |
|
|
48
|
-
| L3 资源 | `references/`、`assets/`、`report-templates/` | 任务相关时才 Read |
|
|
49
|
-
|
|
50
|
-
**原则**：SKILL.md 只做路由与不可妥协的纪律；参数表、Playbook 步骤、优化 SOP 放 references。
|
|
51
|
-
|
|
52
|
-
### 1.4 文件引用规则
|
|
53
|
-
|
|
54
|
-
- 从 SKILL.md **只链接一层**（`references/foo.md`），避免 A→B→C 链式引用。
|
|
55
|
-
- 路径用正斜杠，不用 Windows 反斜杠。
|
|
56
|
-
- 占位符 `https://www-ci.siluzan.com`、`https://tso-api-ci.siluzan.com`、`npm install -g siluzan-tso-cli@beta` 由构建脚本替换，文档中禁止硬编码环境 URL。
|
|
57
|
-
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## 2. 内容编写原则
|
|
61
|
-
|
|
62
|
-
### 2.1 简洁（Concise is Key）
|
|
63
|
-
|
|
64
|
-
Agent 已具备通用能力。文档只写 **CLI 特有** 内容：字段口径、批量命令、门禁流程、与前端不一致处。
|
|
65
|
-
|
|
66
|
-
❌ 解释「什么是 Google Ads」
|
|
67
|
-
✅ `budgetAmountYuan` 已是元，禁止再 ÷100
|
|
68
|
-
|
|
69
|
-
### 2.2 单一术语
|
|
70
|
-
|
|
71
|
-
全库统一：
|
|
72
|
-
|
|
73
|
-
| 概念 | 统一用词 | 禁止混用 |
|
|
74
|
-
| ---- | -------- | -------- |
|
|
75
|
-
| 广告账户 ID | `mediaCustomerId` | customer id、账户号（无上下文时） |
|
|
76
|
-
| 实体 ID | `entityId` | 内部 id |
|
|
77
|
-
| 落盘 | `--json-out` | --json-out ./snap（已移除） |
|
|
78
|
-
| 媒体 | `Google`、`TikTok`、`MetaAd`… | google、meta |
|
|
79
|
-
|
|
80
|
-
### 2.3 默认 + 逃生口
|
|
81
|
-
|
|
82
|
-
每个决策点给一个默认路径，例外单独一行：
|
|
83
|
-
|
|
84
|
-
```markdown
|
|
85
|
-
全量 Google 批处理：省略 `-a`（CLI 内部拉清单）。
|
|
86
|
-
仅当用户明确给出 ID 子集时才传 `-a id1,id2,...`。
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
### 2.4 反馈环（Feedback Loop）
|
|
90
|
-
|
|
91
|
-
写操作文档须含：**写命令 → 读命令复核 → 失败时查 reference**。
|
|
92
|
-
|
|
93
|
-
破坏性操作统一：**用户确认 → `--commit` → 读命令验证**。
|
|
94
|
-
|
|
95
|
-
### 2.5 禁止时间敏感表述
|
|
96
|
-
|
|
97
|
-
不写「2025 年 8 月前用旧 API」。废弃内容放 `## 已废弃` 折叠或删除。
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## 3. siluzan-tso 文档分层
|
|
102
|
-
|
|
103
|
-
| 文件 | 职责 |
|
|
104
|
-
| ---- | ---- |
|
|
105
|
-
| `SKILL.md` | 安装、能力边界、文档路由表、任务→文档速查、Playbook 索引 |
|
|
106
|
-
| `references/core/agent-conventions.md` | Agent 纪律：加载时机、硬规范、数据转换、时间/币种/批量 |
|
|
107
|
-
| `references/core/playbooks.md` | P1–P7 标准动作（可复制命令块） |
|
|
108
|
-
| `references/core/subagent-orchestration.md` | 主 Agent 自主委派决策矩阵（无 `agents/` 目录） |
|
|
109
|
-
| `snippets/handoff-p*.md` | Task handoff 模板（随 skill 安装根复制） |
|
|
110
|
-
| `references/core/tips.md` | `--json-out` 协议、outline 处理顺序 |
|
|
111
|
-
| `references/*.md` | 单功能域：命令、参数、输出示例 |
|
|
112
|
-
| `references/google-ads/rules/` | Google 优化/合规 SOP（非 CLI 参数） |
|
|
113
|
-
| `assets/*.json` / `*.md` | 创建类 JSON 契约 |
|
|
114
|
-
| `report-templates/*.md` | 报告内容纲要（优先于 HTML） |
|
|
115
|
-
| `report-templates/*.html` | 视觉样式，**不含业务数据** |
|
|
116
|
-
| `README.md` | 给「通过 URL 安装」的大模型说明（不进 dist 路由） |
|
|
117
|
-
|
|
118
|
-
### 3.1 与 CLI 代码同步
|
|
119
|
-
|
|
120
|
-
**代码变更 → 必须同步 Skill**（tutorial-10 #2）。新命令注册在 `_register.ts` / `index.ts` 后：
|
|
121
|
-
|
|
122
|
-
1. 更新对应 `references/*.md`
|
|
123
|
-
2. 更新 `SKILL.md` 路由表（若新功能域）
|
|
124
|
-
3. 评估场景：`tso-cli/eval/scenarios/` + `pnpm --filter siluzan-tso-cli run eval:export-cases`
|
|
125
|
-
|
|
126
|
-
### 3.2 灰度开关（tutorial-10 #11）
|
|
127
|
-
|
|
128
|
-
| 状态 | CLI 注册 | SKILL 文档 | AI 可见 |
|
|
129
|
-
| ---- | -------- | ---------- | ------- |
|
|
130
|
-
| 内测 | 是 | 否 | 否 |
|
|
131
|
-
| 公开 | 是 | 是 | 是 |
|
|
132
|
-
|
|
133
|
-
---
|
|
134
|
-
|
|
135
|
-
## 4. description 写法模板
|
|
136
|
-
|
|
137
|
-
```yaml
|
|
138
|
-
description: >-
|
|
139
|
-
Operates Siluzan TSO ad accounts via siluzan-tso-cli: Google/Bing/Yandex/TikTok/Kwai/Meta
|
|
140
|
-
account management, Google Ads CRUD, analytics, optimization reports, forewarning, leads,
|
|
141
|
-
invoicing, and RAG knowledge lookup. Use when the user mentions ad accounts, balance, spend,
|
|
142
|
-
campaigns, keywords, PMax, open account, MCC/BC binding, or TSO reporting.
|
|
143
|
-
Each new task requires re-reading routed references per SKILL.md.
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
中文项目可保留中文 description，但仍须：**第三人称 + 能力列表 + 触发场景 + 重读纪律一句**。
|
|
147
|
-
|
|
148
|
-
---
|
|
149
|
-
|
|
150
|
-
## 5. 体积与质量检查清单
|
|
151
|
-
|
|
152
|
-
发布前逐项确认：
|
|
153
|
-
|
|
154
|
-
### Frontmatter
|
|
155
|
-
- [ ] `name` === 安装目录名 `siluzan-tso`
|
|
156
|
-
- [ ] `description` 含 WHAT、WHEN、关键词
|
|
157
|
-
- [ ] `compatibility` 列出 Node + CLI + 鉴权
|
|
158
|
-
|
|
159
|
-
### SKILL.md
|
|
160
|
-
- [ ] 正文 < 500 行
|
|
161
|
-
- [ ] 无重复 parameters 表（细节在 references）
|
|
162
|
-
- [ ] 路由表覆盖所有 `references/*.md` 入口
|
|
163
|
-
- [ ] Playbook 仅索引，步骤在 `core/playbooks.md`
|
|
164
|
-
|
|
165
|
-
### References
|
|
166
|
-
- [ ] 每个 CLI 命令族有且仅有一个主 reference
|
|
167
|
-
- [ ] 含 `--json-out` 示例（查询类）
|
|
168
|
-
- [ ] 写命令含 `--commit` 与复核命令
|
|
169
|
-
- [ ] 无断链（如 `accounts/open-account-by-media.md` 必须存在）
|
|
170
|
-
|
|
171
|
-
### 构建
|
|
172
|
-
- [ ] `pnpm run build:tso:test` 后 `dist/skill/SKILL.md` 占位符已替换
|
|
173
|
-
- [ ] `_meta.json` 版本与 package.json 一致
|
|
174
|
-
|
|
175
|
-
---
|
|
176
|
-
|
|
177
|
-
## 6. 反模式（Avoid）
|
|
178
|
-
|
|
179
|
-
| 反模式 | 正确做法 |
|
|
180
|
-
| ------ | -------- |
|
|
181
|
-
| SKILL.md 内嵌 200 行 Playbook | 移至 `references/core/playbooks.md` |
|
|
182
|
-
| Agent 用 `--json` 落大 JSON 到对话 | 一律 `--json-out` + 脚本读盘 |
|
|
183
|
-
| 路由表缺文件 | 补文件或删链接 |
|
|
184
|
-
| google-ads-rules 深链三层 | SKILL → `google-ads/rules/README.md` → 具体规则 |
|
|
185
|
-
| HTML 模板假数据当示例 | 纲要 `.md` 定义维度，数据来自 CLI |
|
|
186
|
-
| 凭记忆跨任务复用参数 | 每任务重读 `core/agent-conventions.md` § 加载纪律 |
|
|
187
|
-
| 固定 `agents/` 与 skill 双源维护 | 用 `subagent-orchestration.md` + handoff snippets，主 Agent 自主决策 |
|
|
188
|
-
|
|
189
|
-
---
|
|
190
|
-
|
|
191
|
-
## 7. 相关仓库文档
|
|
192
|
-
|
|
193
|
-
- `.cursor/rules/tutorial-05-core/skill-authoring.mdc` — 项目内 Skill 结构速查
|
|
194
|
-
- `.cursor/rules/tutorial-10-best-practices.mdc` — CLI + Skill 同步等 12 条
|
|
195
|
-
- `cso-cli/assets/siluzan-cso/SKILL.md` — 姊妹包参考（命令索引表风格）
|
|
196
|
-
- https://agentskills.io/specification — 开放规范原文
|