@tronscanteam/cli 1.0.0 → 1.0.1

package/README.md

@@ -6,7 +6,38 @@ A CLI tool built on [TronScan API](https://docs.tronscan.org/), providing 80+ su
 
 Two ways to use: **`ts` in the terminal** (after global install) and **natural language in AI IDEs** ([Claude Code](https://claude.ai/code), [Cursor](https://cursor.com), VS Code Copilot, etc.).
 
-## Install (global `ts` command)
+## Install
+
+### 1. Install from npm
+
+```bash
+npm install -g @tronscanteam/cli
+```
+
+This registers the global command **`ts`** for use in any directory. Run `ts help` to see all commands.
+
+**API Key**:
+
+Get your API Key: https://docs.tronscan.org/zh/api/api-keys
+
+**Method A: `ts setup`**
+
+```bash
+ts setup YOUR_API_KEY
+```
+
+**Method B: environment variable**
+
+Persist it in your shell config, then `source` once. zsh example:
+
+```bash
+echo 'export TRONSCAN_API_KEY="your-api-key"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+For bash, use `~/.bashrc` or `~/.bash_profile` instead of `~/.zshrc`.
+
+### 2. Install from source (clone)
 
 ```bash
 git clone https://github.com/sshnii/tronscan-cli.git
@@ -16,9 +47,7 @@ cp .env.example .env
 # Edit .env and set TRONSCAN_API_KEY
 ```
 
-Get your API Key: https://docs.tronscan.org/zh/api/api-keys
-
-Register **`ts`** on your machine (use either one):
+Register **`ts`** on your machine:
 
 ```bash
 npm link
@@ -26,13 +55,13 @@ npm link
 npm install -g .
 ```
 
-The CLI loads `.env` from the **cloned project root** (same folder as `package.json`). Keep your API Key there; you can run `ts` from any working directory.
+The CLI reads `.env` from the **cloned project root** (next to `package.json`). After that, run `ts` from any working directory.
 
 ## Usage
 
 ### 1. In the terminal
 
-After installing `ts` globally, run commands directly (`ts help` lists all subcommands):
+After installing `ts` globally, run commands directly:
 
 ```bash
 ts help                         # list all subcommands
@@ -48,7 +77,7 @@ ts security-account TXxx...     # account risk check
 
 ### 2. In AI IDEs
 
-Open this repo as your working directory and describe what you need in natural language. The AI reads the rule files, infers intent, picks the right API, and interprets the response.
+To use with AI IDEs, we recommend installing from source (clone). Cloning downloads the full set of rule files (`CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`), which improve AI response accuracy. Run `ts setup` on first use to quickly configure your API Key.
 
 Built-in rule files:
 
@@ -94,14 +123,12 @@ No need to memorize commands or API paths — the AI matches the best endpoint f
 | Account | 11 | Balance, holdings, resources, approvals, votes, analysis |
 | Super Representative | 4 | SR list, votes, chain parameters, proposals |
 | Transaction | 10 | Transaction details, transfers (TRX/TRC20/TRC721/TRC1155) |
-| Statistics | 19 | TRX supply, transaction trends, active accounts, energy, DeFi TVL |
-| Contract | 10 | Contract details, callers, energy consumption, daily analysis |
+| Statistics | 17 | TRX supply, transaction trends, active accounts, energy, DeFi TVL |
+| Contract | 9 | Contract details, callers, energy consumption, daily analysis |
 | Security | 6 | Account/token/URL/transaction risk detection, authorization check |
 | Deep Analysis | 4 | Related accounts, fund flow, large transactions |
 | Stablecoin | 11 | Holder distribution, top holders, mint/burn, liquidity pools |
 
-Run `ts help` for the full command list.
-
 ## API Reference
 
 See [api-reference.md](api-reference.md) for the complete API endpoint list.

package/README_CN.md

@@ -6,7 +6,38 @@
 
 支持两种使用方式：**终端全局命令 `ts`** 和 **在 AI IDE 中用自然语言查询**（支持 [Claude Code](https://claude.ai/code)、[Cursor](https://cursor.com)、VS Code Copilot 等）。
 
-## 安装（全局命令 `ts`）
+## 安装
+
+### 一、通过 npm 全局安装
+
+```bash
+npm install -g @tronscanteam/cli
+```
+
+安装后即可在任意目录使用全局命令 **`ts`**，输入 `ts help` 查看全部命令。
+
+**配置 API Key**：
+
+API Key 申请：https://docs.tronscan.org/zh/api/api-keys
+
+**方式 A：`ts setup`**
+
+```bash
+ts setup YOUR_API_KEY
+```
+
+**方式 B：环境变量**
+
+长期生效：把密钥写进 shell 配置文件，保存后执行一次 `source`。zsh 示例：
+
+```bash
+echo 'export TRONSCAN_API_KEY="你的密钥"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+使用 bash 时，将 `~/.zshrc` 换成 `~/.bashrc` 或 `~/.bash_profile`。
+
+### 二、从源码克隆安装
 
 ```bash
 git clone https://github.com/sshnii/tronscan-cli.git
@@ -16,9 +47,7 @@ cp .env.example .env
 # 编辑 .env，设置 TRONSCAN_API_KEY
 ```
 
-API Key 申请：https://docs.tronscan.org/zh/api/api-keys
-
-在本机注册全局命令 **`ts`**（任选其一）：
+在本机注册全局命令 **`ts`**：
 
 ```bash
 npm link
@@ -26,13 +55,13 @@ npm link
 npm install -g .
 ```
 
-CLI 会从**你克隆下来的项目根目录**（与 `package.json` 同级）读取 `.env`。请在该目录配置好 API Key；之后在任意工作目录都可以直接执行 `ts`。
+CLI 会从**克隆下来的项目根目录**（与 `package.json` 同级）读取 `.env`；配置好后在任意工作目录都可执行 `ts`。
 
 ## 使用方式
 
 ### 一、在终端中使用
 
-全局安装 `ts` 后，在终端直接输入命令（`ts help` 可查看全部子命令）：
+全局安装 `ts` 后，在终端直接输入命令：
 
 ```bash
 ts help                         # 查看所有子命令
@@ -48,9 +77,7 @@ ts security-account TXxx...     # 账户风险检测
 
 ### 二、在 AI IDE 中使用
 
-将本项目作为工作目录打开，用自然语言描述需求即可；AI 会读取规则文件，识别意图、选择接口并解读返回结果。
-
-已内置规则文件：
+若要在 AI IDE 中使用，建议优先通过从源码克隆的方式安装。克隆会下载完整的规则文件（`CLAUDE.md`、`.cursorrules`、`.github/copilot-instructions.md`），提升 AI 回复的准确性。首次使用运行 `ts setup` 即可快速完成 API Key 配置。
 
 | AI IDE | 规则文件 |
 |--------|----------|
@@ -94,14 +121,12 @@ AI：自动执行 ts tps 并返回结果
 | 账户 | 11 | 余额、持仓、资源、授权、投票、分析 |
 | 超级代表 | 4 | SR 列表、投票、链参数、提案 |
 | 交易 | 10 | 交易详情、转账记录(TRX/TRC20/TRC721/TRC1155) |
-| 统计 | 19 | TRX 供应、交易趋势、活跃账户、能量、DeFi TVL |
-| 合约 | 10 | 合约详情、调用者、能量消耗、日度分析 |
+| 统计 | 17 | TRX 供应、交易趋势、活跃账户、能量、DeFi TVL |
+| 合约 | 9 | 合约详情、调用者、能量消耗、日度分析 |
 | 安全 | 6 | 账户/代币/URL/交易风险检测、授权检查 |
 | 深度分析 | 4 | 关联账户、资金流向、大额交易 |
 | 稳定币 | 11 | 持仓分布、大户、增发/销毁、流动性池 |
 
-输入 `ts help` 查看完整命令列表。
-
 ## API 参考
 
 完整 API 接口列表见 [api-reference.md](api-reference.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tronscanteam/cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "TronScan API CLI tool - 80+ commands for TRON blockchain data",
   "type": "module",
   "repository": {

package/src/api.js

@@ -7,9 +7,9 @@ import { dirname } from 'path';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = resolve(__dirname, '..');
+export const PROJECT_ROOT = resolve(__dirname, '..');
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.0.1';
 const BASE_URL = 'https://apilist.tronscanapi.com';
 
 let apiKey = process.env.TRONSCAN_API_KEY || '';
@@ -29,7 +29,8 @@ export function loadConfig() {
   }
   if (!apiKey) {
     err('未找到 API Key');
-    warn('请设置 TRONSCAN_API_KEY 环境变量或创建 .env 文件');
+    warn('API Key 申请: https://tronscan.org/#/developer/api');
+    warn('运行 ts setup YOUR_API_KEY 快速配置');
     process.exit(2);
   }
 }
@@ -82,7 +83,12 @@ export async function get(path) {
     if (body) console.error(body);
     process.exit(4);
   }
-  return res.json();
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`API 返回非 JSON: ${text.slice(0, 200)}`);
+  }
 }
 
 export async function post(path, body) {
@@ -108,7 +114,12 @@ export async function post(path, body) {
     if (text) console.error(text);
     process.exit(4);
   }
-  return res.json();
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`API 返回非 JSON: ${text.slice(0, 200)}`);
+  }
 }
 
 // ============ Output ============

package/src/commands.js

@@ -54,7 +54,7 @@ export const commands = {
   },
   'account-votes': {
     usage: 'ts account-votes <address>', desc: '投票记录',
-    run: (a) => get(`/api/vote?address=${require(a, 0, 'address', 'ts account-votes <address>')}`)
+    run: (a) => get(`/api/vote?voter=${require(a, 0, 'address', 'ts account-votes <address>')}`)
   },
   'account-analysis': {
     usage: 'ts account-analysis <address>', desc: '日度分析',
@@ -360,8 +360,12 @@ export const commands = {
     run: () => get('/api/tokenTvc')
   },
   'token-analysis': {
-    usage: 'ts token-analysis', desc: '代币交易分析',
-    run: () => get('/api/token/analysis')
+    usage: 'ts token-analysis <contract|symbol>', desc: '代币交易分析',
+    run: async (a) => {
+      require(a, 0, 'contract|symbol', 'ts token-analysis <contract|symbol>');
+      const contract = await resolveAndLog(a[0], resolveContract);
+      return get(`/api/token/analysis?token=${contract}`);
+    }
   },
   'token-transfer-analysis': {
     usage: 'ts token-transfer-analysis', desc: '代币转账分析',
@@ -383,8 +387,12 @@ export const commands = {
     run: (a) => get(`/api/deep/account/token/bigAmount?address=${require(a, 0, 'address', 'ts deep-big-tx <address>')}`)
   },
   'deep-token-transfer': {
-    usage: 'ts deep-token-transfer <address>', desc: '代币转账次数',
-    run: (a) => get(`/api/deep/account/holderToken/basicInfo/trc20/transfer?address=${require(a, 0, 'address', 'ts deep-token-transfer <address>')}`)
+    usage: 'ts deep-token-transfer <address> <contract>', desc: '代币转账次数',
+    run: (a) => {
+      require(a, 0, 'address', 'ts deep-token-transfer <address> <contract>');
+      require(a, 1, 'contract', 'ts deep-token-transfer <address> <contract>');
+      return get(`/api/deep/account/holderToken/basicInfo/trc20/transfer?accountAddress=${a[0]}&tokenAddress=${a[1]}`);
+    }
   },
 
   // --- 稳定币 ---
@@ -402,32 +410,32 @@ export const commands = {
     run: () => get('/api/stableCoin/holder/top')
   },
   'stable-big-tx': {
-    usage: 'ts stable-big-tx', desc: '大额交易',
-    run: () => get('/api/deep/stableCoin/bigAmount')
+    usage: 'ts stable-big-tx [types]', desc: '大额交易 (types: 1=USDT 2=USDJ 3=TUSD 4=USDC)',
+    run: (a, o) => get(`/api/deep/stableCoin/bigAmount?types=${a[0] || '1'}&start=${o.start}&limit=${o.limit}`)
   },
   'stable-events': {
-    usage: 'ts stable-events', desc: '增发/销毁/黑名单事件',
-    run: () => get('/api/deep/stableCoin/totalSupply/keyEvents')
+    usage: 'ts stable-events [--sort 0|1] [--start N] [--limit N]', desc: '增发/销毁/黑名单事件 (sort: 0=asc 1=desc)',
+    run: (a, o) => get(`/api/deep/stableCoin/totalSupply/keyEvents?direction=1&sort=${o.sort || '1'}&start=${o.start}&limit=${o.limit}`)
   },
   'stable-dist': {
-    usage: 'ts stable-dist', desc: '交易所/DeFi 分布',
-    run: () => get('/api/stableCoin/distribution')
+    usage: 'ts stable-dist <contract>', desc: '交易所/DeFi 分布',
+    run: (a) => get(`/api/stableCoin/distribution?token=${require(a, 0, 'contract', 'ts stable-dist <contract>  (如 USDT: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t)')}`)
   },
   'stable-liquidity': {
     usage: 'ts stable-liquidity', desc: '流动性操作记录',
     run: () => get('/api/deep/stableCoin/liquidity/transaction')
   },
   'stable-pool': {
-    usage: 'ts stable-pool', desc: '池子概览(TVL)',
-    run: () => get('/api/stableCoin/pool/overview')
+    usage: 'ts stable-pool <pool_address>', desc: '池子概览(TVL)',
+    run: (a) => get(`/api/stableCoin/pool/overview?pool=${require(a, 0, 'pool_address', 'ts stable-pool <pool_address>')}`)
   },
   'stable-pool-trend': {
-    usage: 'ts stable-pool-trend', desc: '池子趋势',
-    run: () => get('/api/stableCoin/pool/trend')
+    usage: 'ts stable-pool-trend <pool_address>', desc: '池子趋势',
+    run: (a) => get(`/api/stableCoin/pool/trend?pool=${require(a, 0, 'pool_address', 'ts stable-pool-trend <pool_address>')}`)
   },
   'stable-pool-change': {
-    usage: 'ts stable-pool-change', desc: '池子历史变化',
-    run: () => get('/api/stableCoin/pool/change')
+    usage: 'ts stable-pool-change <pool_address>', desc: '池子历史变化',
+    run: (a) => get(`/api/stableCoin/pool/change?pool=${require(a, 0, 'pool_address', 'ts stable-pool-change <pool_address>')}`)
   },
   'stable-tvl': {
     usage: 'ts stable-tvl', desc: '稳定币 TVL 分布',

package/src/help.js

@@ -17,6 +17,9 @@ ${B('全局选项:')}
   --help, -h    显示命令帮助
   --version, -V 显示版本号
 
+  配置:
+    ts setup [api-key]              配置 API Key（首次使用必须）
+
   代币:
     ts token <contract|symbol>      TRC20 代币详情（支持 USDT 等符号）
     ts token-trc10 <id|symbol>      TRC10 代币详情
@@ -85,7 +88,7 @@ ${B('全局选项:')}
     ts bandwidth-daily              每日带宽消耗
     ts trigger-stats                合约调用分布
     ts token-tvc                    代币链上价值(TVC)
-    ts token-analysis               代币交易分析
+    ts token-analysis <contract|symbol> 代币交易分析
     ts token-transfer-analysis      代币转账分析
 
   合约:
@@ -112,19 +115,19 @@ ${B('全局选项:')}
     ts deep-related <addr>          关联账户
     ts deep-flow <addr>             资金流向
     ts deep-big-tx <addr>           大额交易
-    ts deep-token-transfer <addr>   代币转账次数
+    ts deep-token-transfer <addr> <contract> 代币转账次数
 
   稳定币:
     ts stable-holders               持仓分布概览
     ts stable-change                持有者变化趋势
     ts stable-top                   大户排行
-    ts stable-big-tx                大额交易
+    ts stable-big-tx [types]        大额交易 (1=USDT 2=USDJ 3=TUSD 4=USDC)
     ts stable-events                增发/销毁/黑名单事件
-    ts stable-dist                  交易所/DeFi 分布
+    ts stable-dist <contract>       交易所/DeFi 分布
     ts stable-liquidity             流动性操作记录
-    ts stable-pool                  池子概览(TVL)
-    ts stable-pool-trend            池子趋势
-    ts stable-pool-change           池子历史变化
+    ts stable-pool <pool_address>   池子概览(TVL)
+    ts stable-pool-trend <pool_address> 池子趋势
+    ts stable-pool-change <pool_address> 池子历史变化
     ts stable-tvl                   稳定币 TVL 分布
 `);
 }

package/src/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 
-import { loadConfig, output, err, warn, VERSION } from './api.js';
+import { resolve } from 'path';
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
+import { loadConfig, output, err, warn, VERSION, PROJECT_ROOT } from './api.js';
 import { commands } from './commands.js';
 import { printHelp, printCommandHelp } from './help.js';
 
@@ -44,6 +46,59 @@ while (i < rest.length) {
   }
 }
 
+// ============ Setup (before loadConfig) ============
+
+if (cmd === 'setup') {
+  const envPath = resolve(PROJECT_ROOT, '.env');
+  const examplePath = resolve(PROJECT_ROOT, '.env.example');
+  const isTTY = process.stderr.isTTY ?? false;
+  const green = (s) => (isTTY ? `\x1b[32m${s}\x1b[0m` : s);
+  const bold = (s) => (isTTY ? `\x1b[1m${s}\x1b[0m` : s);
+  const dim = (s) => (isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+
+  const inputKey = positional[0];
+
+  if (inputKey) {
+    // 校验：过滤明显无效的输入
+    if (/[<>]/.test(inputKey) || inputKey === 'your-api-key' || inputKey === 'your_api_key_here') {
+      err('请替换为你的真实 API Key');
+      warn('API Key 申请: https://tronscan.org/#/developer/api');
+      process.exit(2);
+    }
+    // 直接写入 API Key
+    writeFileSync(envPath, `TRONSCAN_API_KEY=${inputKey}\n`);
+    console.log(green('✓ API Key 已写入 .env'));
+    console.log(dim(`  路径: ${envPath}`));
+    console.log(`\n  现在可以使用 ${bold('ts')} 命令了，试试: ${bold('ts tps')}`);
+    process.exit(0);
+  }
+
+  // 检查现有配置
+  if (existsSync(envPath)) {
+    const content = readFileSync(envPath, 'utf-8');
+    const match = content.match(/^\s*TRONSCAN_API_KEY\s*=\s*(.+?)\s*$/m);
+    const key = match?.[1]?.replace(/^["']|["']$/g, '');
+    if (key && key !== 'your_api_key_here') {
+      console.log(green('✓ API Key 已配置'));
+      console.log(dim(`  路径: ${envPath}`));
+      console.log(dim(`  Key: ${key.slice(0, 8)}...${key.slice(-4)}`));
+      process.exit(0);
+    }
+  }
+
+  // 未配置，引导用户
+  if (!existsSync(envPath) && existsSync(examplePath)) {
+    copyFileSync(examplePath, envPath);
+  }
+
+  console.log(bold('TronScan CLI 配置向导\n'));
+  console.log(`  1. 申请 API Key: ${bold('https://tronscan.org/#/developer/api')}`);
+  console.log(`  2. 运行: ${bold('ts setup <your-api-key>')}`);
+  console.log(`     或手动编辑: ${dim(envPath)}`);
+  console.log(`\n  也可设置环境变量: ${bold('export TRONSCAN_API_KEY=<your-api-key>')}`);
+  process.exit(0);
+}
+
 // ============ Dispatch ============
 
 const command = commands[cmd];