开发者文档中心

# skill.py - 最简技能示例
from xingling import Skill, SkillRequest, SkillResponse

class WeatherSkill(Skill):
    name = "天气查询"
    description = "查询指定城市的实时天气"
    version = "1.0.0"

    async def handle(self, req: SkillRequest) -> SkillResponse:
        city = req.params.get("city", "北京")
        weather = await self.fetch_weather(city)
        return SkillResponse(
            text=f"{city}今日天气：{weather.desc}，{weather.temp}°C",
            data=weather.to_dict()
        )

my-app/
├── xingling.toml          # 应用配置
├── app/
│   ├── __init__.py
│   ├── agent.py           # 智能体核心逻辑
│   ├── skills/             # 内置技能
│   │   ├── search.py
│   │   └── analysis.py
│   ├── prompts/            # 提示词模板
│   │   └── system.txt
│   └── ui/                 # 自定义界面组件
│       ├── chat.vue
│       └── dashboard.vue
├── tests/
└── docs/

[app]
name = "智能客服助手"
version = "2.1.0"
description = "全渠道AI客服，支持知识库问答和人工转接"
category = "customer-service"

[pricing]
model = "subscription"
plans = [
  { name = "基础版", price = 0, period = "monthly" },
  { name = "专业版", price = 99, period = "monthly" },
  { name = "企业版", price = "custom" }
]

[ai]
default_model = "xingling-gpt-4"
max_tokens = 4096
temperature = 0.7

[channels]
wechat = true
web_widget = true
app_sdk = true

# 安装星聆开发者 CLI
pip install xingling-cli

# 或使用 npm
npm install -g @xingling/cli

# 验证安装
xingling --version
# xingling-cli v3.2.1

# 登录星聆开发者账号
xingling login

# 或使用 API Key 登录（CI/CD 场景）
xingling login --api-key sk_your_api_key_here

# 创建技能项目
xingling init my-skill --type skill

# 创建应用项目
xingling init my-app --type app

# 使用模板创建
xingling init my-app --template customer-service

# 进入项目目录
cd my-skill

# 启动本地开发服务器
xingling dev

# ✓ 开发服务器已启动
# ✓ 本地地址: http://localhost:3456
# ✓ 调试面板: http://localhost:3456/__debug
# ✓ 文件监听中，修改自动重载...

POST /v3/chat/completions HTTP/1.1
Host: api.xingling.ai
Authorization: Bearer sk_your_api_key
Content-Type: application/json
X-Request-Id: req_unique_id

import requests

headers = {
    "Authorization": "Bearer sk_your_api_key",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.xingling.ai/v3/users/profile",
    headers=headers
)
print(response.json())

import requests, json

response = requests.post(
    "https://api.xingling.ai/v3/chat/completions",
    headers={
        "Authorization": "Bearer sk_test_xxx",
        "Content-Type": "application/json"
    },
    json={
        "app_id": "app_abc123",
        "session_id": "sess_xyz789",
        "messages": [
            { "role": "user", "content": "帮我分析上个月的销售数据" }
        ],
        "stream": True,
        "skills": ["data-analysis"]
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        data = json.loads(line.decode()[6:])
        print(data["choices"][0]["delta"].get("content", ""), end="")

{
  "user_id": "usr_8a3f2b",
  "nickname": "张明远",
  "plan": "professional",
  "status": "active",
  "created_at": "2026-01-15T08:30:00Z",
  "usage": {
    "total_messages": 12847,
    "this_month": 1523,
    "tokens_consumed": 2847392
  }
}

{
  "event": "payment.completed",
  "timestamp": "2026-04-03T06:30:00Z",
  "data": {
    "order_id": "ord_2f8a9c3d",
    "user_id": "usr_8a3f2b",
    "app_id": "app_abc123",
    "plan": "professional",
    "amount": 99.00,
    "currency": "CNY",
    "period": "monthly",
    "revenue_share": {
      "developer": 70.00,
      "platform": 29.00,
      "tax": 0.00
    }
  }
}

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    """验证 Webhook 签名，确保请求来自星聆"""
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# 在你的 Webhook 处理器中
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook/xingling", methods=["POST"])
def handle_webhook():
    sig = request.headers.get("X-Xingling-Signature")
    if not verify_webhook(request.data, sig, WEBHOOK_SECRET):
        return "Invalid signature", 401

    event = request.json
    if event["event"] == "payment.completed":
        handle_payment(event["data"])

    return "OK", 200

# 创建项目
xingling init <name> --type skill|app --template <template>

# 本地开发
xingling dev [--port 3456] [--verbose]

# 运行测试
xingling test [--coverage]

# 打包
xingling build [--production]

# 发布
xingling publish [--dry-run] [--version "1.2.0"]

# 查看日志
xingling logs --app <app_id> --follow

# 管理密钥
xingling keys list|create|rotate|delete

GET /v3/developer/revenue
Authorization: Bearer sk_live_xxx

# Response
{
  "total_revenue": 28640.00,
  "this_month": 5280.00,
  "pending_settlement": 3120.00,
  "available_balance": 25520.00,
  "developer_level": "premium",
  "share_ratio": 0.75
}