@fastmoss/cli 0.1.6 → 0.1.14

package/README.zh-CN.md

@@ -1,218 +1,171 @@
-# FastMoss CLI
+# @fastmoss/cli
 
 [English](./README.md)
 
-FastMoss CLI 用于在终端或 AI Agent 中发现并调用 FastMoss MCP 工具，覆盖 TikTok Shop 选品、达人发现、店铺分析、广告分析、市场洞察、视频/直播分析和 FastMoss 知识库查询等场景。
+`@fastmoss/cli` 只安装 `fastmoss` 命令。npm 包会解析精确同版本的平台包，安装时和运行时都不会下载二进制文件。
 
-CLI 需要配合 FastMoss CLI Agent Skill 一起使用：
-
-- `@fastmoss/cli` 安装 `fastmoss` 命令，用于真正执行工具调用。
-- `npx skills add FastMoss/cli` 安装 Agent Skill，让你的 Agent 知道有哪些 FastMoss 工具、什么时候使用、怎么调用。
+<!-- FASTMOSS_INSTALLATION_START -->
+## 安装
 
-安装 CLI：
+CLI 与 Agent Skill 相互独立，安装其中一个不会自动安装另一个。
 
-```bash
-npm install -g @fastmoss/cli
-```
+### npm
 
-单独安装 Skill：
+只安装 CLI：
 
 ```bash
-npx skills add FastMoss/cli -y -g
-npx skills add FastMoss/cli --agent claude-code
-# 如果你的 skills CLI 支持 --client：
-npx skills add FastMoss/cli --client claude
+npm install -g @fastmoss/cli@latest
 ```
 
-## 关于 FastMoss
-
-[FastMoss](https://www.fastmoss.com/) 是面向全球 TikTok 品牌、商家、服务商、创作者和运营团队的数据分析平台。FastMoss 帮助用户洞察大盘趋势、发现爆品和品类机会、寻找达人与机构、监控竞店、分析广告投放，并研究直播生态。
-
-FastMoss 主要提供以 TikTok 和 TikTok Shop 为核心的大数据分析服务，覆盖直播、商品、店铺、达人、广告、视频、音乐、标签等版块，涵盖美国、英国、印尼、越南、菲律宾、泰国、马来西亚、西班牙、墨西哥、法国、德国、巴西等主要 TikTok 商业化国家和区域的数据。
-
-## 安装
-
-不安装，直接通过 npx 运行：
+不做全局安装，临时运行 CLI：
 
 ```bash
-npx @fastmoss/cli
+npx -y @fastmoss/cli@latest
 ```
 
-全局安装：
+只安装或更新 Agent Skill：
 
 ```bash
-npm install -g @fastmoss/cli
-fastmoss
+npx -y @fastmoss/skill@latest
 ```
 
-全局安装后，命令名是 `fastmoss`。如果终端提示 `command not found: fastmoss`，通常是 npm 全局 bin 目录没有加入 `PATH`。
+Skill 命令全程非交互，可以直接发送到 Agent 聊天框由 Agent 执行。默认会把 `fastmoss-cli` 安装到 Codex、Claude 和通用 Agents 三个目录，并输出实际 `SKILL.md` 路径和当前会话加载提示。
 
-如果你的 npm 配置禁止 lifecycle scripts，可以允许本包的 postinstall 脚本在安装期预下载二进制：
+指定 Agent 或卸载：
 
 ```bash
-npm install -g --allow-scripts=@fastmoss/cli @fastmoss/cli
+npx -y @fastmoss/skill@latest --agent codex
+npx -y @fastmoss/skill@latest --agent claude
+npx -y @fastmoss/skill@latest --agent agents
+npx -y @fastmoss/skill@latest --agent all
+npx -y @fastmoss/skill@latest uninstall --agent all
 ```
 
-## API Key 和积分
-
-FastMoss 工具调用需要 API Key，并会消耗积分。访问 [FastMoss 开发者平台](https://developers.fastmoss.com/mcp/overview.html) 登录、创建 MCP API Key、查看用量并管理积分。
+设置 `FASTMOSS_SKILL_DIR` 后只安装到一个自定义 skills 根目录。npm 安装只使用用户配置的 npm registry，不会从 GitHub 下载文件。
 
-常规配置：
+### GitHub clone
 
 ```bash
-fastmoss login --api-key <your-api-key>
-fastmoss whoami
+git clone --depth 1 https://github.com/FastMoss/cli.git
+cd cli
+./install.sh --cli
+./install.sh --skill
+./install.sh --all
 ```
 
-如果积分不足，请在开发者平台的计费/价格页面充值或升级套餐。计费和积分规则见 [FastMoss MCP Pricing](https://developers.fastmoss.com/mcp/pricing.html)。
+Windows PowerShell：
+
+```powershell
+git clone --depth 1 https://github.com/FastMoss/cli.git
+cd cli
+.\install.ps1 -Cli
+.\install.ps1 -Skill
+.\install.ps1 -All
+```
 
-## 命令
+`--all` 和 `-All` 只是依次执行两个独立安装动作。clone 或下载 GitHub Release 离线包后，安装过程只读取本地文件，不调用 npm，也不继续下载其他文件。
+<!-- FASTMOSS_INSTALLATION_END -->
 
-查看版本和帮助：
+## 使用
 
 ```bash
 fastmoss --version
 fastmoss help
-```
-
-登录和本地配置：
-
-```bash
 fastmoss login --api-key <your-api-key>
-fastmoss logout
-fastmoss whoami
-fastmoss set api-key <your-api-key>
-fastmoss clear api-key
-fastmoss set language zh
-fastmoss set language en
-fastmoss show config
-fastmoss show auth
-```
-
-发现工具：
-
-```bash
 fastmoss tools
-fastmoss tools --json
-fastmoss tools --search <tool_name>
-```
-
-调用工具：
-
-```bash
 fastmoss call --tool <tool_name> --args '<json>' --output mcp
-fastmoss <tool_name> --args '<json>' --output mcp
 ```
 
-LLM 或 Agent 读取结果时优先使用 `--output mcp`。终端里只想看简洁结果时使用 `--output data`。只有调试原始 RPC 响应时才使用 `--output rpc`。
-
-联网命令常用参数：
-
-```bash
---api-key <api-key>
---base-url <url>
---timeout <seconds>
---insecure-skip-tls
-```
-
-## 支持的工具
-
-随包发布的 Agent Skill 包含静态工具目录。你也可以执行 `fastmoss tools` 或 `fastmoss tools --json` 查看当前账号实时可用的工具列表。
-
-| 分类 | name | title |
-|---|---|---|
-| 广告工具 | `ad_data_overview` | Ad data overview |
-| 广告工具 | `ad_search` | Ad search |
-| 达人工具 | `creator_cargo_summary` | Creator ecommerce summary |
-| 达人工具 | `creator_data_trends` | Creator data trends |
-| 达人工具 | `creator_fans_distribution` | Creator fans distribution |
-| 达人工具 | `creator_product_list` | Creator product list |
-| 达人工具 | `creator_profile_overview` | Creator profile overview |
-| 达人工具 | `creator_rank_top_ecommerce` | Top ecommerce creators |
-| 达人工具 | `creator_rank_top_growth` | Top creator follower growth |
-| 达人工具 | `creator_rank_top_potential` | Top potential creators |
-| 达人工具 | `creator_search` | Creator search |
-| 达人工具 | `creator_video_analysis` | Creator video analysis |
-| 辅助和知识库工具 | `fastmoss_detail_url_examples` | FastMoss Detail URL Examples |
-| 辅助和知识库工具 | `live_detail_analysis` | Live detail analysis and category breakdown |
-| 辅助和知识库工具 | `live_products_list` | Live promoted product list |
-| 辅助和知识库工具 | `live_search` | Live search |
-| 市场洞察工具 | `market_category_analysis` | Category market analysis |
-| 市场洞察工具 | `market_category_author_sales_matrix` | Category creator sales matrix |
-| 市场洞察工具 | `market_category_ranking` | Category market ranking |
-| 商品工具 | `product_category_info` | Product category list |
-| 商品工具 | `product_creator_analysis` | Product creator analysis and creator list |
-| 商品工具 | `product_detail_info` | Product detail info |
-| 商品工具 | `product_investment` | Product ad investment analysis |
-| 商品工具 | `product_overview` | Product overview |
-| 商品工具 | `product_rank_new_listed` | New listed product ranking |
-| 商品工具 | `product_rank_top_selling` | Top selling products |
-| 商品工具 | `product_review_list` | Product review list |
-| 商品工具 | `product_sales_trend` | Product sales trend |
-| 商品工具 | `product_search` | Product search |
-| 商品工具 | `product_sku` | Product SKU analysis |
-| 商品工具 | `product_video_list` | Product video list |
-| 辅助和知识库工具 | `search_category_by_words` | Search TikTok Product Category by Keywords |
-| 辅助和知识库工具 | `search_fastmoss_documents` | FastMoss Knowledge Base Search |
-| 店铺工具 | `shop_base_info` | Shop base info |
-| 店铺工具 | `shop_creator_analysis` | Shop creator analysis and creator list |
-| 店铺工具 | `shop_data_trends` | Shop data trends |
-| 店铺工具 | `shop_investment_analysis` | Shop ad investment analysis |
-| 店铺工具 | `shop_live_analysis` | Shop live analysis and live list |
-| 店铺工具 | `shop_product_analysis` | Shop product analysis and product list |
-| 店铺工具 | `shop_rank_top_selling` | Top selling shops |
-| 店铺工具 | `shop_sale_analysis` | Shop sales analysis |
-| 店铺工具 | `shop_search` | Shop search |
-| 店铺工具 | `shop_video_analysis` | Shop video analysis and video list |
-| 辅助和知识库工具 | `video_data_trends` | Video data trends |
-| 辅助和知识库工具 | `video_detail_analysis` | Video detail analysis and product list |
-| 辅助和知识库工具 | `video_script_info` | Video subtitle script |
-| 辅助和知识库工具 | `video_search` | Video search |
-
-## 二进制下载
-
-本包会安装 `fastmoss` 命令。npm 包本身不内置 Go 二进制文件，而是在安装或首次运行时从 GitHub Releases 下载当前平台对应的 `fastmoss` 二进制，缓存到本地后转发所有 CLI 参数。
-
-安装时会尝试预下载当前平台二进制。如果下载失败，npm 安装仍会完成；首次运行 `fastmoss` 时会再次下载，并显示下载地址。
-
-你可以跳过安装期下载，让首次运行时再下载：
-
-```bash
-FASTMOSS_SKIP_DOWNLOAD=1 npm install -g @fastmoss/cli
-```
-
-内部调试或私有镜像可以覆盖下载地址：
-
-```bash
-FASTMOSS_DOWNLOAD_BASE_URL=https://downloads.example.com/releases npx @fastmoss/cli
-```
-
-## 缓存目录
-
-默认缓存目录：
-
-```text
-~/.fastmoss/bin/<version>/<platform>/
-```
-
-自定义缓存目录：
-
-```bash
-FASTMOSS_CACHE_DIR=/custom/cache/dir npx @fastmoss/cli
-```
-
-## 支持平台
-
-- macOS `amd64`
-- macOS `arm64`
-- Linux `amd64`
-- Linux `arm64`
-- Windows `amd64`
-
-wrapper 会根据当前平台请求以下资产之一：
-
-- `fastmoss-darwin-amd64`
-- `fastmoss-darwin-arm64`
-- `fastmoss-linux-amd64`
-- `fastmoss-linux-arm64`
-- `fastmoss-windows-amd64.exe`
+## CLI Tool Catalog
+
+### Advertising Tools
+
+| Tool | Description |
+|---|---|
+| `ad_data_overview` | Use when the user has a video_id and wants ad spend, ROAS, play, engagement, follower, and commerce performance over a date range. |
+| `ad_search` | Use when the user wants active ad creatives or needs to filter ads by country, category, landing page, spend, ROAS, plays, or run days. Returns ad, creator, shop, products, and performance sections. |
+
+### Agency Tools
+
+| Tool | Description |
+|---|---|
+| `agency_creator_analysis` | Use when the user wants agency creator structure, follower tiers, and individual collaborators. Returns distributions and a paginated creator list. |
+| `agency_product_analysis` | Use for agency product-category and price-band structure. Use agency_product_list for individual products. |
+| `agency_product_list` | Use when the user wants individual products promoted through an agency. Supports category, price, period, sorting, and pagination. |
+| `agency_profile_overview` | Use when the user wants an agency profile, historical performance, and recent 7/28/90-day data overview. |
+| `agency_rank_top` | Use when the user wants leading MCN agencies in a market. Returns weekly or monthly agency rankings and period performance. |
+| `agency_search` | Use when the user has an agency name or market clue but no agency_id. Returns matching agencies and recent 7-day performance. |
+| `agency_shop_analysis` | Use when the user wants agency collaborating-shop totals and individual shop performance. |
+
+### Creator Tools
+
+| Tool | Description |
+|---|---|
+| `creator_cargo_summary` | Use when the user wants a creator video-vs-live selling split and main promoted categories. |
+| `creator_data_trends` | Use when the user asks about creator follower, engagement, or commerce trends. Select field_type; returns daily series and period totals. |
+| `creator_fans_distribution` | Use when the user wants to check whether a creator audience matches a target market. Returns age, gender, location, and top segments. |
+| `creator_product_list` | Use when the user wants a creator showcase product list. Returns product GMV, units sold, category, price, commission, shop info, and time_range_days. |
+| `creator_profile_overview` | Use when the user wants a creator snapshot or partnership check. Returns profile and performance_overview; GMV/rankings are mostly historical cumulative, so use creator_search day28_gmv for current activity. |
+| `creator_rank_top_ecommerce` | Use when the user wants top ecommerce creators. Returns creator and ranking_metrics; date_value is returned as YYYY-Www for weekly rankings. |
+| `creator_rank_top_growth` | Use when the user wants fast-growing creators. Returns creator and growth_metrics; date_value is returned as YYYY-Www for weekly rankings. |
+| `creator_rank_top_potential` | Use when the user wants creators with ecommerce potential. Returns creator, potential_metrics, and audience_summary; date_value is returned as YYYY-Www for weekly rankings. |
+| `creator_search` | Use when the user has no UID and provides a nickname, keyword, niche, or region. Returns creator, commerce_summary, and audience_summary; day28_gmv is the key current-activity metric for tiering; has_email as a boolean, not the email address itself. |
+| `creator_video_analysis` | Use when the user wants creator content direction, tags, and selling videos. Returns video_tag_summary and video_list with interaction_rate_percent and linked_products so the model does not confuse video performance with product performance. |
+
+### Product Tools
+
+| Tool | Description |
+|---|---|
+| `product_category_info` | Use when the user needs the product category tree or category levels. Prefer search_category_by_words for natural-language category terms. |
+| `product_creator_analysis` | Use when the user wants who sells a product or the creator structure. Returns creator_summary with follower_tier_distribution and creator_category_distribution, plus linked_creators with creator, product_contribution, creator_cumulative_performance, and audience_summary. |
+| `product_detail_info` | Use when the user wants product basics, shop, price, rating, logistics, images, or ad status. Returns product and shop; detail_url points to TikTok. |
+| `product_investment` | Use when the user asks about product ads, spend, ROAS, or daily paid-traffic changes. Returns ad_performance_summary and daily_ad_performance_trend; ad_gmv is ad-attributed. |
+| `product_overview` | Use when the user wants product channel attribution, lifecycle/momentum, or ad-vs-organic structure. Returns period_summary, daily_trend, ads_distribution, channel_distribution, and content_distribution. |
+| `product_rank_new_listed` | Use when the user wants recently listed hot products. Returns FastMoss new-product ranking, first_3d_gmv/units_sold, and total_gmv/units_sold; new means listed within 30 days. |
+| `product_rank_top_selling` | Use when the user wants bestsellers or top products. Returns period_gmv/units_sold, total_gmv/units_sold, and units_sold_growth_rate_percent. |
+| `product_review_list` | Use when the user wants product reviews or buyer feedback. Returns review list and count; supports time_range_days and rating/create_time/review_id sorting. |
+| `product_sales_trend` | Use when the user wants a product GMV/units trend or traction check. Returns period_summary and daily_trend with period_gmv, period_units_sold, daily_gmv, and daily_units_sold. |
+| `product_search` | Use when the user has no product_id and provides a name, keyword, price band, category, bestseller clue, or new-product clue. Returns product, sales_summary, distribution_summary, and shop. |
+| `product_sku` | Use when the user wants SKU sales share, inventory share, or SKU health. Returns SKU-level sales and inventory shares. |
+| `product_video_list` | Use when the user wants videos selling a product, high-play videos, or paid-vs-organic video traffic. Filter with is_ad; returns GMV, plays, video_desc, and fastmoss_url. |
+
+### Shop Tools
+
+| Tool | Description |
+|---|---|
+| `shop_base_info` | Use when the user wants a shop snapshot, store type, rating, or profile. Returns cumulative GMV/units, ranks, age, product count, and creator/video/live counts. |
+| `shop_creator_analysis` | Use when the user wants shop collaborators, creator tiers, or video-vs-live selling structure. Returns creator list and distributions. |
+| `shop_data_trends` | Use when the user wants recent shop GMV, units, creator, live, video, or active-product trends. Returns daily trends. |
+| `shop_investment_analysis` | Use when the user asks about shop ads, spend, ROAS, ad GMV, or promoted assets. Returns ad estimates and daily changes. |
+| `shop_live_analysis` | Use when the user wants shop live performance, shop-live vs affiliate-live structure, or live sessions. |
+| `shop_product_analysis` | Use when the user wants shop categories, price bands, product mix, or product details. Returns distributions and product list. |
+| `shop_rank_top_selling` | Use when the user wants top shops in a market or category. Returns shop ranking and ecommerce metrics. |
+| `shop_sale_analysis` | Use when the user wants shop sales by short video, live, product card, creator, or self-operated channels. Returns channel_distribution and content_distribution. |
+| `shop_search` | Use when the user has no seller_id and provides a shop name, keyword, or region. Returns matching shops. |
+| `shop_video_analysis` | Use when the user wants shop selling videos, video performance, or ad status. |
+
+### Market Insight Tools
+
+| Tool | Description |
+|---|---|
+| `market_category_analysis` | Use when the user wants category size, growth, competition, or opportunity. analysis_type basic_metrics returns category, scale_metrics, growth_metrics, concentration_metrics; sales_trends returns trend_series; price_distribution returns sales_price_distribution with left-open right-closed price bands and sub_category_units_sold_total. |
+| `market_category_author_sales_matrix` | Use when the user wants category sales contribution by creator follower_tier. Returns creator_count, category_gmv, gmv_share_percent, units_sold, and avg_creator_gmv. |
+| `market_category_ranking` | Use when the user wants category ranking, growth, or concentration. Returns ranking_scope and ranked_categories; no category_id means level-1 category ranking, and a level-1 category_id means level-2 subcategory ranking. |
+
+### Auxiliary and Knowledge Base Tools
+
+| Tool | Description |
+|---|---|
+| `fastmoss_detail_url_examples` | Use when the AI needs FastMoss detail-page links. Takes no arguments and returns product, creator, shop, video, and live URL templates. |
+| `live_detail_analysis` | Use when the user wants one live session info, creator, key performance, and category breakdown. |
+| `live_products_list` | Use when the user wants products sold in a live session or high GMV/units within this live session. Returns live_units_sold, live_gmv, commission_rate_percent, sales_timeline only when pagesize <= 10, and shop_cumulative_units_sold. |
+| `live_search` | Use when the user has no room_id and provides a live title, host, or shop. Returns live, creator, and performance_summary. |
+| `search_category_by_words` | Use when the user knows a product/category term but does not have the category_id yet. Returns matched TikTok product category IDs and Chinese category paths. |
+| `search_fastmoss_documents` | Use when the user asks about FastMoss rules, features, terms, or operations rather than real-time business data. Returns knowledge snippets and documents. |
+| `video_data_trends` | Use when the user wants one video play, like, comment, or share trends. Returns daily interaction trends. |
+| `video_detail_analysis` | Use when the user wants one video basics, plays, engagement, interaction rate, IPM, and linked products. |
+| `video_script_info` | Use when the user wants video subtitles or line-by-line spoken copy. Returns start/end time and text; empty subtitles can fall back to video_desc. |
+| `video_search` | Use when the user has no video_id and provides video keywords, title, or creator. Returns matching videos. |
+
+
+这个包只负责 CLI。需要让 Agent 知道如何、何时调用 CLI 时，请单独安装 `@fastmoss/skill`。

package/bin/fastmoss.js

@@ -3,10 +3,15 @@
 const packageJSON = require("../package.json");
 const { runCLI } = require("../lib/runtime");
 
-runCLI({
-  version: packageJSON.version,
-  configuredDownloadBaseURL: packageJSON.fastmoss?.downloadBaseURL,
-}).catch((error) => {
-  process.stderr.write(`fastmoss wrapper error: ${error.message}\n`);
-  process.exit(1);
-});
+runCLI({ version: packageJSON.version })
+  .then(({ code, signal }) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code == null ? 1 : code;
+  })
+  .catch((error) => {
+    process.stderr.write(`fastmoss wrapper error: ${error.message}\n`);
+    process.exitCode = 1;
+  });