@fastmoss/cli 0.1.4 → 0.1.6

package/skills/fastmoss-cli/references/cli.md

@@ -0,0 +1,70 @@
+# FastMoss CLI Command Reference
+
+## Install
+
+Install the CLI before using this skill:
+
+```bash
+npm install -g @fastmoss/cli
+```
+
+After installation, the command is:
+
+```bash
+fastmoss
+```
+
+If `fastmoss` is not found, ask the user to make sure the npm global bin directory is in `PATH`.
+
+## Authentication and config
+
+```bash
+fastmoss login --api-key <api-key>
+fastmoss logout
+fastmoss whoami
+fastmoss show config
+fastmoss show auth
+fastmoss set api-key <api-key>
+fastmoss clear api-key
+fastmoss set language zh
+fastmoss set language en
+```
+
+`whoami`, `show config`, and `show auth` are safe first checks. Do not print or expose API keys in the final answer.
+
+## Tool discovery
+
+```bash
+fastmoss tools
+fastmoss tools --json
+fastmoss tools --search <tool_name>
+```
+
+Use `tools --json` when live metadata is needed. Use `tools --search <tool_name>` to inspect one exact tool.
+
+## Tool calls
+
+```bash
+fastmoss call --tool <tool_name> --args '<json>' --output mcp
+```
+
+Shortcut form:
+
+```bash
+fastmoss <tool_name> --args '<json>' --output mcp
+```
+
+Prefer the explicit `call --tool` form inside agents because it is clearer and easier to debug.
+
+## Common flags
+
+These flags are supported by networked tool commands:
+
+```bash
+--api-key <api-key>
+--base-url <url>
+--timeout <seconds>
+--insecure-skip-tls
+```
+
+Use config or environment defaults unless the user explicitly asks to override them.

package/skills/fastmoss-cli/references/tool-call.md

@@ -0,0 +1,103 @@
+# Calling FastMoss Tools from CLI
+
+## Basic pattern
+
+```bash
+FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool <tool_name> --args '<json>' --output mcp
+```
+
+## Client metadata
+
+Every `fastmoss call` MUST include agent client metadata. Prefer environment variables when making one or more calls in the same shell session:
+
+```bash
+FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool <tool_name> --args '<json>' --output mcp
+```
+
+Or pass explicit flags for a single call:
+
+```bash
+fastmoss call --client-name "<client-name>" --client-version "<client-version>" --tool <tool_name> --args '<json>' --output mcp
+```
+
+Use the actual client name and version when available. Do not invent a version number; if the runtime does not expose a version, use the client name and omit the version only if the CLI allows it.
+
+Always pass valid JSON to `--args`. On macOS/Linux shells, wrap JSON in single quotes:
+
+```bash
+FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool creator_search --args '{"keywords":"beauty","region":"US"}' --output mcp
+```
+
+If a value contains a single quote, write the JSON to a temporary file or carefully escape it before calling the CLI.
+
+## Choose the tool
+
+1. Read `references/tools.md` for the packaged static catalog index, then read the matching category file:
+   - `tools-advertising.md` for `ad_` tools.
+   - `tools-agency.md` for `agency_` tools.
+   - `tools-creator.md` for `creator_` tools.
+   - `tools-product.md` for `product_` tools.
+   - `tools-shop.md` for `shop_` tools.
+   - `tools-market.md` for `market_` tools.
+   - `tools-auxiliary-knowledge.md` for helper, link, document, category, live, video, and other tools.
+2. If the user is logged in and live metadata matters, run:
+
+   ```bash
+   fastmoss tools --json
+   fastmoss tools --search <tool_name>
+   ```
+
+3. Match the user's intent to the most specific tool. Prefer specific product, creator, shop, ad, video, category, or ranking tools over broad search tools.
+
+## Output modes
+
+Use:
+
+```bash
+--output mcp
+```
+
+when an LLM or agent will read and reason over the tool response.
+
+Use:
+
+```bash
+--output data
+```
+
+when the user needs a concise end-user payload without extra protocol wrapping.
+
+Use:
+
+```bash
+--output rpc
+```
+
+only when debugging raw RPC behavior.
+
+## Error handling
+
+- If the CLI is missing, tell the user to run `npm install -g @fastmoss/cli`.
+- If auth is missing, tell the user to run `fastmoss login --api-key <api-key>`.
+- If the tool name is unknown, check `references/tools.md` and the matching category file, then try `fastmoss tools --json` when live discovery is available.
+- If arguments are rejected, inspect the tool's parameter table in the matching category file or run `fastmoss tools --search <tool_name>`.
+- Do not invent unavailable fields. Ask a focused follow-up question when required parameters are missing.
+
+## Detail-page links
+
+When the answer should include FastMoss detail-page links, call this helper first:
+
+```bash
+FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool fastmoss_detail_url_examples --args '{}' --output mcp
+```
+
+Use the returned examples as the link assembly rules. Combine those rules with product IDs, creator IDs, shop IDs, video IDs, live IDs, or other IDs returned by the analysis tools.
+
+## Response pattern
+
+After a successful tool call:
+
+1. Summarize the answer in the user's language.
+2. Mention key filters or assumptions used in the call.
+3. Preserve IDs, URLs, categories, regions, dates, and numeric fields that the user may need next.
+4. If the result is empty, suggest one or two concrete next filters to broaden or correct the query.

package/skills/fastmoss-cli/references/tools-advertising.md

@@ -0,0 +1,48 @@
+# Advertising Tools
+
+> Advertising tools for ad creatives, ad spend, ROAS, engagement, and paid-traffic performance analysis.
+
+## Tool summary
+
+| 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... |
+| ad_search | Use when the user wants active ad creatives or needs to filter ads by country, category, landing page, spend, ROAS, p... |
+
+## Tool details
+
+### 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.
+
+Example:
+
+```bash
+fastmoss call --tool ad_data_overview --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+
+### 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.
+
+Example:
+
+```bash
+fastmoss call --tool ad_search --args '{"filter":{},"orderby":[],"page":1}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | no | Filter parameters. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+

package/skills/fastmoss-cli/references/tools-agency.md

@@ -0,0 +1,145 @@
+# Agency Tools
+
+> Agency tools for MCN agency search, rankings, profiles, creator collaborations, promoted products, and collaborating-shop analysis.
+
+## Tool summary
+
+| Tool | Description |
+|---|---|
+| agency_creator_analysis | Use when the user wants agency creator structure, follower tiers, and individual collaborators. Returns distributions... |
+| 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, an... |
+| 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 perfor... |
+| agency_search | Use when the user has an agency name or market clue but no agency_id. Returns matching agencies and recent 7-day perf... |
+| agency_shop_analysis | Use when the user wants agency collaborating-shop totals and individual shop performance. |
+
+## Tool details
+
+### agency_creator_analysis
+
+Use when the user wants agency creator structure, follower tiers, and individual collaborators. Returns distributions and a paginated creator list.
+
+Example:
+
+```bash
+fastmoss call --tool agency_creator_analysis --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+
+### agency_product_analysis
+
+Use for agency product-category and price-band structure. Use agency_product_list for individual products.
+
+Example:
+
+```bash
+fastmoss call --tool agency_product_analysis --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+
+### agency_product_list
+
+Use when the user wants individual products promoted through an agency. Supports category, price, period, sorting, and pagination.
+
+Example:
+
+```bash
+fastmoss call --tool agency_product_list --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+
+### agency_profile_overview
+
+Use when the user wants an agency profile, historical performance, and recent 7/28/90-day data overview.
+
+Example:
+
+```bash
+fastmoss call --tool agency_profile_overview --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+
+### agency_rank_top
+
+Use when the user wants leading MCN agencies in a market. Returns weekly or monthly agency rankings and period performance.
+
+Example:
+
+```bash
+fastmoss call --tool agency_rank_top --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+
+### 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.
+
+Example:
+
+```bash
+fastmoss call --tool agency_search --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+
+### agency_shop_analysis
+
+Use when the user wants agency collaborating-shop totals and individual shop performance.
+
+Example:
+
+```bash
+fastmoss call --tool agency_shop_analysis --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+

package/skills/fastmoss-cli/references/tools-auxiliary-knowledge.md

@@ -0,0 +1,200 @@
+# Auxiliary and Knowledge Base Tools
+
+> Auxiliary and knowledge base tools for category keyword matching, FastMoss documentation, detail-page URL rules, live/video analysis, and tools outside the main business prefixes.
+
+## Tool summary
+
+| 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 l... |
+| 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_unit... |
+| live_search | Use when the user has no room_id and provides a live title, host, or shop. Returns live, creator, and performance_sum... |
+| 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... |
+| search_fastmoss_documents | Use when the user asks about FastMoss rules, features, terms, or operations rather than real-time business data. Retu... |
+| 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... |
+| video_search | Use when the user has no video_id and provides video keywords, title, or creator. Returns matching videos. |
+
+## Tool details
+
+### 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.
+
+Example:
+
+```bash
+fastmoss call --tool fastmoss_detail_url_examples --args '{}' --output mcp
+```
+
+Parameters: none documented.
+
+### live_detail_analysis
+
+Use when the user wants one live session info, creator, key performance, and category breakdown.
+
+Example:
+
+```bash
+fastmoss call --tool live_detail_analysis --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+| lang | string | no | Language. Default EN_US, optional ZH_CN. |
+
+### 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.
+
+Example:
+
+```bash
+fastmoss call --tool live_products_list --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+| lang | string | no | Language. Default EN_US, optional ZH_CN. |
+| orderby | array | no | Sort options; only the first sort rule takes effect. Fields: units_sold, gmv. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10; timeline snapshots are returned only when pagesize <= 10. |
+
+### live_search
+
+Use when the user has no room_id and provides a live title, host, or shop. Returns live, creator, and performance_summary.
+
+Example:
+
+```bash
+fastmoss call --tool live_search --args '{"filter":{},"keywords":"value","lang":"value"}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | no | Filter parameters. |
+| keywords | string | no | Search keywords: product, shop, creator, video, live, or category terms. |
+| lang | string | no | Language. Default EN_US, optional ZH_CN. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+
+### 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.
+
+Example:
+
+```bash
+fastmoss call --tool search_category_by_words --args '{"query":[]}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| max_total_results | integer | no | Max deduplicated candidates. Default 15. |
+| query | array \| string | yes | Product or category terms, string or array; map natural-language category clues into category_id. |
+| top_k | integer | no | Candidate categories per keyword. Default 5. |
+
+### 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.
+
+Example:
+
+```bash
+fastmoss call --tool search_fastmoss_documents --args '{"query":[]}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| query | array \| string | yes | Feature terms, terminology, rule questions, or operation questions; string or array. |
+| source_file | string | no | Optional source file; use it to narrow the search scope and reduce noise. |
+| top_k | integer | no | Knowledge snippets per query. Default 5. |
+
+### video_data_trends
+
+Use when the user wants one video play, like, comment, or share trends. Returns daily interaction trends.
+
+Example:
+
+```bash
+fastmoss call --tool video_data_trends --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+
+### video_detail_analysis
+
+Use when the user wants one video basics, plays, engagement, interaction rate, IPM, and linked products.
+
+Example:
+
+```bash
+fastmoss call --tool video_detail_analysis --args '{"filter":{}}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | yes | Filter parameters. |
+| lang | string | no | Language. Default EN_US, optional ZH_CN. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+
+### 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.
+
+Example:
+
+```bash
+fastmoss call --tool video_script_info --args '{"video_id":"value"}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| video_id | string | yes | Video ID; use video_search first if only a title/creator is known. |
+
+### video_search
+
+Use when the user has no video_id and provides video keywords, title, or creator. Returns matching videos.
+
+Example:
+
+```bash
+fastmoss call --tool video_search --args '{"filter":{},"keywords":"value","lang":"value"}' --output mcp
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| filter | object | no | Filter parameters. |
+| keywords | string | no | Search keywords: product, shop, creator, video, live, or category terms. |
+| lang | string | no | Language. Default EN_US, optional ZH_CN. |
+| orderby | array | no | Sort options. |
+| page | integer | no | Page number. Default 1, max 10. |
+| pagesize | integer | no | Page size. Default 10, max 10. |
+