观远数据 API Skill

Description

This skill provides a command-line interface for GuanYuan Data (观远数据) API. It supports multiple authentication methods, automatic token management, card data retrieval, and CSV export with metadata generation.

Usage Instructions

When a user requests GuanYuan data operations:

1. 1. Choose authentication method:

- Method 1: Provide loginId and password in config for automatic login - Method 2: Provide token directly in config file - Method 3: Use guanyuan token <token> command to set token interactively

1. 2. Get card data: Use guanyuan card <cardId> to retrieve data in JSON format

1. 3. Export to CSV: Use guanyuan csv <cardId> --output file.csv to export data

Authentication Methods

Method 1: Automatic Login with Credentials

{
  "baseUrl": "https://your-guanyuan-domain.com",
  "domain": "your-domain",
  "loginId": "your-login-id",
  "password": "your-password"
}

Then run: INLINECODE6

Method 2: Direct Token in Config

{
  "baseUrl": "https://your-guanyuan-domain.com",
  "domain": "your-domain",
  "token": "your-token-here"
}

No login needed, directly use commands.

Method 3: Token Command (Interactive)

{
  "baseUrl": "https://your-guanyuan-domain.com",
  "domain": "your-domain"
}

Then run: guanyuan token <your-token> or guanyuan token (interactive)

Available Resources

Main Script

• - scripts/guanyuan.js: Main CLI tool

- login(): Authenticate and save token - getCardData(cardId, options): Retrieve card data - convertToCSV(cardData, sampleRows): Convert data to CSV format - extractMetadata(cardData): Extract field metadata - saveCSVWithMetadata(csv, filename, metadata, cardId): Save CSV and metadata files - getValidToken(config): Auto-discover and use valid token from multiple sources

Configuration Files

• - ~/.guanyuan/config.json: API credentials and settings

- Required: baseUrl, domain - Optional (one of): loginId + password, token, or none (use token command)

• - ~/.guanyuan/user.token: Stored authentication token (auto-managed)

Export Files

• - .csv: CSV data file
• _meta.json: Metadata file with field information

References

• - references/README.md: Detailed user documentation in Chinese

Commands Reference

Command	Description	Example
INLINECODE20	Initialize configuration (show setup instructions)	INLINECODE21
INLINECODE22

Login with credentials from config | guanyuan login | | token [token] | Set token (via parameter or interactive) | guanyuan token eyJ0eX... | | card <id> | Get card data (JSON) | guanyuan card abc123 --limit 50 | | csv <id> | Export to CSV | guanyuan csv abc123 --output data.csv | | status | Show config and token status | guanyuan status | | help | Show help | guanyuan help |

Options Reference

Common Options

Option	Description	Default
INLINECODE34	Data view type	GRAPH
INLINECODE35

Number of rows | 100 |

| --offset <number> | Data offset | 0 |

CSV Export Options

Option	Description	Default
INLINECODE37	Output to file	stdout
INLINECODE38

Sample N rows | all rows |

Example Prompts

• - "使用账号密码登录观远数据并获取卡片abc123的数据"
• "使用token设置观远数据认证"
• "Export card data to CSV with metadata"
• "Get the first 50 rows of card l059d768f28bd404caf8df3e"
• "导出卡片数据到CSV文件，只采样前10行"
• "Check GuanYuan API configuration status"
• "Save card data as query_data.csv with metadata"
• "Set token for GuanYuan API without providing credentials"

Authentication Workflow

CODEBLOCK3

Metadata File Format

When exporting CSV with --output, a _meta.json file is automatically generated:

CODEBLOCK4

Output Format

JSON Output

• - Full API response with chart data
• Includes dimensions, metrics, and formatting info
• Suitable for debugging and data inspection

CSV Output

• - Tabular format with headers
• Dimensions first, then metrics
• Proper CSV escaping for special characters
• Metadata file with field types and descriptions

Token Management

Token Sources (Priority Order)

1. 1. ~/.guanyuan/user.token - Saved token (highest priority)
2. config.json - Token field in config
3. Auto-login - Using loginId + password from config

Token Behavior

• - With expireAt: Automatically validated against expiration time
• Without expireAt: Used indefinitely (user-manually set tokens)
• Expired/Invalid: Triggers auto-refresh (if credentials available) or prompts user

Manual Token Setting

CODEBLOCK5

Notes

• - Flexible Authentication: Three authentication methods for different use cases
• Token Management: Tokens are automatically discovered from multiple sources
• Auto-Login: Credentials-based auth with automatic token refresh
• Password Handling: Passwords are automatically Base64 encoded before API call
• URL Support: baseUrl can include protocol prefix (http:// or https://)
• CSV Escaping: Special characters (commas, quotes, newlines) are properly escaped
• File Safety: Existing files are overwritten without warning
• Data Limits: Use --limit to control API response size
• Sampling: Use --sample to export only N rows without fetching all data
• No Credentials Required: Can work with just baseUrl + domain + token command

API References

• - User Login API
• Get Card Data API