观远数据 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. 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

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

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: guanyuan login

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

• <filename>.csv: CSV data file
• <filename>_meta.json: Metadata file with field information

References

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

Commands Reference

Options Reference

Common Options

CSV Export Options

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

┌─────────────────────────────────────────────────────────────┐
│  User wants to access GuanYuan data                         │
└────────────────────┬────────────────────────────────────────┘
                     │
                     v
┌─────────────────────────────────────────────────────────────┐
│  Check ~/.guanyuan/user.token                               │
│  Is there a valid token?                                    │
└────────────────────┬────────────────────────────────────────┘
                     │
            ┌────────┴────────┐
            │                 │
         Yes │                 │ No
            │                 │
            v                 v
┌───────────────────┐  ┌──────────────────────────────────┐
│  Use saved token  │  │  Check config.json              │
└───────────────────┘  │  - Has loginId + password?       │
                      │  - Has token?                   │
                      │  - Neither? → Use token command  │
                      └────────────┬─────────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                Has Creds      Has Token    Neither
                    │              │              │
                    v              v              v
            ┌───────────┐  ┌───────────┐  ┌───────────────┐
            │  Auto     │  │  Use      │  │  Prompt user │
            │  Login    │  │  Config   │  │  to run      │
            │           │  │  Token   │  │  'guanyuan    │
            └───────────┘  └───────────┘  │   token'      │
                                         └───────────────┘

Metadata File Format

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

{
  "cardId": "card-id",
  "cardType": "CHART",
  "chartType": "PIVOT_TABLE",
  "view": "GRAPH",
  "exportTime": "2026-03-25T07:52:00.924Z",
  "totalRows": 10,
  "dataLimit": 10,
  "hasMoreData": false,
  "fields": [
    {
      "name": "字段显示名称",
      "originalName": "字段原始名称",
      "type": "STRING/TIMESTAMP/DOUBLE",
      "metaType": "DIM/METRIC",
      "fieldType": "dimension/metric",
      "fieldId": "field-id"
    }
  ]
}

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. ~/.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

# Via parameter
guanyuan token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

# Interactive mode
guanyuan token
# Then paste your token when prompted

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