excel-toolkit/python_auth_runtime/README.md

# @clawd/auth-runtime-py

Python 版本的 OpenClaw Auth Runtime。

## 全局配置

**所有 skill 共享同一份全局配置**，无需在每个 skill 中重复配置。

### 创建全局配置文件

```bash
# 复制模板
cp ~/.openclaw/.env.example ~/.openclaw/.env

# 编辑配置文件
vi ~/.openclaw/.env
```

### 配置文件内容

```bash
# ~/.openclaw/.env

# Auth Runtime 配置
CLIENT_KEY=sk_ae28fc4e.xxx
AUTH_BASE=https://api-gw-test.yuanwei-lnc.com

# Gemini API 配置（可选）
GEMINI_API_KEY=your-gemini-api-key
```

**注意**: `~/.openclaw/.env` 包含敏感信息，不要提交到 git。

---

## 安装

```bash
uv pip install /path/to/python_auth_runtime
```

---

## 使用方式

### 最简单的用法

```python
from python_auth_runtime import create_env_config, request_api_with_auto_refresh

# 自动从 ~/.openclaw/.env 加载配置
config = create_env_config()

# 调用 API
response = request_api_with_auto_refresh(
    method="POST",
    url=f"{config.auth_base}/ecom/tasks/scrape",
    dry_run=False,
    config=config,
    body={"url": "https://detail.1688.com/offer/123.html"},
)
```

### 配置加载优先级

1. **环境变量**（最高优先级）
   ```bash
   export CLIENT_KEY="override-key"
   python script.py
   ```

2. **全局配置文件** `~/.openclaw/.env`
   ```bash
   CLIENT_KEY=sk_ae28fc4e.xxx
   ```

3. **默认值**
   - `AUTH_BASE`: `https://api-gw-test.yuanwei-lnc.com`
   - `AUTH_CACHE_DIR`: `/tmp/skill-auth-cache`
   - `AUTH_MIN_TTL_SEC`: `60`

---

## 完整示例

```python
#!/usr/bin/env python3
# your-skill/scripts/main.py

from python_auth_runtime import create_env_config, request_api_with_auto_refresh
import json

def main():
    # 自动从 ~/.openclaw/.env 加载配置
    config = create_env_config()
    
    # 验证配置
    if not config.client_key:
        print("❌ CLIENT_KEY not found!")
        print("Please create ~/.openclaw/.env with your CLIENT_KEY")
        print("See: ~/.openclaw/.env.example")
        return 1
    
    # 调用 1688 API
    response = request_api_with_auto_refresh(
        method="POST",
        url=f"{config.auth_base}/ecom/tasks/scrape",
        dry_run=False,
        config=config,
        body={"url": "https://detail.1688.com/offer/123.html"},
    )
    
    if response.status == 200:
        data = json.loads(response.body)
        print("商品价格:", data.get("price"))
    else:
        print(f"❌ 失败：{response.status}")
        print(response.body)
    
    return 0

if __name__ == "__main__":
    exit(main())
```

---

## API 参考

### 配置

#### `create_env_config() -> EnvConfig`

从环境变量创建配置（自动加载 `~/.openclaw/.env`）。

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `AUTH_BASE` | `https://api-gw-test.yuanwei-lnc.com` | 认证基础 URL |
| `CLIENT_KEY` | **必需** | 客户端密钥（从全局配置加载） |
| `AUTH_CACHE_DIR` | `/tmp/skill-auth-cache` | 缓存目录 |
| `AUTH_MIN_TTL_SEC` | `60` | 最小令牌 TTL（秒） |

### 令牌管理

#### `get_access_token(dry_run, config) -> str`

获取访问令牌（带缓存）。

#### `refresh_access_token(dry_run, config) -> str`

刷新访问令牌（绕过缓存）。

### API 请求

#### `request_api(method, url, auth_token, body) -> ApiResponse`

发送 HTTP 请求。

#### `request_api_with_auto_refresh(method, url, dry_run, config, body) -> ApiResponse`

发送 API 请求并自动刷新令牌。

---

## 多 Agent Skill 配置

对于多 Agent skill，可以在全局配置中添加：

```bash
# ~/.openclaw/.env

# 主配置
CLIENT_KEY=sk_ae28fc4e.xxx

# Agent 特定配置
AGENT_1_CLIENT_KEY=sk_agent1.xxx
AGENT_2_CLIENT_KEY=sk_agent2.xxx

# 或者使用统一配置
# 所有 agent 共享同一个 CLIENT_KEY
```

在代码中：

```python
import os
from python_auth_runtime import create_env_config

# 主配置
config = create_env_config()

# 或者访问特定 agent 的配置
agent1_key = os.getenv("AGENT_1_CLIENT_KEY", config.client_key)
```

---

## 环境变量列表

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CLIENT_KEY` | **必需** | 客户端密钥 |
| `AUTH_BASE` | `https://api-gw-test.yuanwei-lnc.com` | 认证基础 URL |
| `AUTH_CACHE_DIR` | `/tmp/skill-auth-cache` | 缓存目录 |
| `AUTH_MIN_TTL_SEC` | `60` | 最小令牌 TTL（秒） |
| `GEMINI_API_KEY` | - | Gemini API Key（用于翻译） |
| `ECOM_BASE` | - | 1688 API 基础 URL |

---

## 测试

```bash
cd /Users/xiaolongxia/Documents/ai-build-app/skills/excel-toolkit/python_auth_runtime
uv run python scripts/example_usage.py
```

---

## 项目结构

```
python_auth_runtime/
├── src/python_auth_runtime/
│   └── __init__.py         # 核心实现（自动加载全局配置）
├── scripts/
│   ├── load_env.py         # .env 加载工具（可选使用）
│   └── example_usage.py    # 使用示例
├── pyproject.toml
└── README.md
```

---

## 许可证

MIT