TAPD API Skill

完整的 TAPD 开放平台集成，实现所有 TAPD API 模块。基于 TAPD PHP SDK 用 Python 重新实现。

📋 功能特性

• ✅ 从 tapd.json 读取 OAuth 配置
• ✅ 自动换取和刷新 access_token
• ✅ 支持多工作空间切换
• ✅ 完整的 API 封装（18 个模块，70+ 方法）
• ✅ 命令行工具 + Python SDK
• ✅ 详细的使用文档和示例

🔧 配置

配置文件 (tapd.json)

所有配置存储在 tapd.json 文件中，支持多工作空间：

{
  "oauth": {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  },
  "workspaces": [
    {
      "id": "12345678",
      "name": "项目A",
      "default": true
    },
    {
      "id": "87654321",
      "name": "项目B"
    }
  ]
}

配置项说明

获取 OAuth 凭证

1. 登录 TAPD 开放平台: https://open.tapd.cn
2. 创建开放应用
3. 获取 应用ID (clientId) 和 应用密钥 (clientSecret)
4. 配置应用权限（需求、任务、缺陷等）
5. 将应用安装到目标项目

获取工作空间 ID

• 打开 TAPD 项目
• URL 中的数字即为 workspace_id
• 例如: https://www.tapd.cn/12345678/ → workspace_id 是 12345678

🚀 快速开始

1. 创建配置文件

# 创建 tapd.json
cat > tapd.json << 'EOF'
{
  "oauth": {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  },
  "workspaces": [
    {
      "id": "12345678",
      "name": "我的项目",
      "default": true
    }
  ]
}
EOF

# 设置权限
chmod 600 tapd.json

2. Python SDK 使用

from scripts.tapd_client import TapdClient
import json

# 读取配置
with open('tapd.json') as f:
    config = json.load(f)

# 获取默认工作空间
default_workspace = next(
    (ws for ws in config['workspaces'] if ws.get('default')),
    config['workspaces'][0]
)

# 初始化客户端
client = TapdClient(
    auth_type='oauth',
    client_id=config['oauth']['clientId'],
    client_secret=config['oauth']['clientSecret'],
    workspace_id=default_workspace['id']
)

# 获取需求列表
stories = client.story.list(
    workspace_id=default_workspace['id'],
    limit=10
)

print(f"获取到 {len(stories)} 条需求")

3. 多工作空间切换

# 遍历所有工作空间
for workspace in config['workspaces']:
    print(f"工作空间: {workspace['name']}")
    
    client = TapdClient(
        auth_type='oauth',
        client_id=config['oauth']['clientId'],
        client_secret=config['oauth']['clientSecret'],
        workspace_id=workspace['id']
    )
    
    stories = client.story.list(workspace_id=workspace['id'], limit=5)
    print(f"  需求数: {len(stories)}")

3. Shell 命令行使用

# 设置环境变量（从配置文件读取）
export TAPD_CLIENT_ID=$(cat tapd.json | jq -r '.oauth.clientId')
export TAPD_CLIENT_SECRET=$(cat tapd.json | jq -r '.oauth.clientSecret')
export TAPD_WORKSPACE_ID=$(cat tapd.json | jq -r '.workspace_id')

# 使用命令行工具
./scripts/tapd-api.sh story list --limit 10
./scripts/tapd-api.sh story count
./scripts/tapd-api.sh bug list --status new

获取需求列表

stories = client.get_stories(limit=10)

for story in stories:

print(f"{story['id']}: {story['name']}")

获取需求详情

story_detail = client.get_story(story_id="1112345678001000001")

获取任务列表

tasks = client.get_tasks(limit=5)

获取缺陷列表

bugs = client.get_bugs(limit=5)

## 📖 API 认证流程

### OAuth 流程图

┌─────────────────────────────────────────────────────────┐

│ 1. 从 tapd.json 读取 clientId + clientSecret │

└─────────────────────────────────────────────────────────┘

↓

┌─────────────────────────────────────────────────────────┐

│ 2. POST /tokens/request_token │

│ grant_type=client_credentials │

│ Authorization: Basic base64(clientId:clientSecret) │

└─────────────────────────────────────────────────────────┘

↓

┌─────────────────────────────────────────────────────────┐

│ 3. 获取 access_token (有效期 7200 秒 / 2 小时) │

└─────────────────────────────────────────────────────────┘

↓

┌─────────────────────────────────────────────────────────┐

│ 4. 调用 TAPD API │

│ Authorization: Bearer │

└─────────────────────────────────────────────────────────┘

### 认证代码示例

Shell 方式

CLIENT_ID="your-client-id"

CLIENT_SECRET="your-client-secret"

获取 access_token

ACCESS_TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \

-d "grant_type=client_credentials" \

"https://api.tapd.cn/tokens/request_token" \

| python3 -c "import json, sys; print(json.load(sys.stdin)['data']['access_token'])")

调用 API

curl -H "Authorization: Bearer $ACCESS_TOKEN" \

"https://api.tapd.cn/stories?workspace_id=12345678&limit=10"

## 🔌 API 端点

### 需求 (Stories)

| 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|
| GET | `/stories` | workspace_id, limit, page, status | 获取需求列表 |
| GET | `/stories/count` | workspace_id, status | 获取需求数量 |
| POST | `/stories` | workspace_id, name, description | 创建需求 |
| POST | `/stories` | workspace_id, id, ... | 更新需求 |

### 任务 (Tasks)

| 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|
| GET | `/tasks` | workspace_id, limit, page | 获取任务列表 |
| POST | `/tasks` | workspace_id, name, ... | 创建/更新任务 |

### 缺陷 (Bugs)

| 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|
| GET | `/bugs` | workspace_id, limit, page, status | 获取缺陷列表 |
| POST | `/bugs` | workspace_id, title, ... | 创建/更新缺陷 |

### 迭代 (Iterations)

| 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|
| GET | `/iterations` | workspace_id, limit, page | 获取迭代列表 |

### 其他

- `/workspaces/projects` - 获取项目列表
- `/releases` - 发布计划
- `/tcases` - 测试用例
- `/comments` - 评论

## 📝 使用示例

### 示例 1: 获取高优先级需求

使用命令行工具（自动过滤）

./scripts/tapd-api.sh stories 50 | python3 -c "

import json, sys

data = json.load(sys.stdin)

for item in data['data']:

story = item['Story']

if story.get('priority') == '4': # High priority

print(f\"{story['id']}: {story['name']}\")

"

### 示例 2: 创建需求

from scripts.tapd_oauth_client import TapdOAuthClient

client = TapdOAuthClient()

new_story = client.create_story(

name="【新功能】实现用户登录",

description="需求描述：\n1. 支持邮箱登录\n2. 支持手机号登录",

priority="4" # High

)

print(f"创建成功: {new_story['id']}")

### 示例 3: 批量更新需求状态

client = TapdOAuthClient()

获取所有 planning 状态的需求

stories = client.get_stories(status="planning", limit=100)

批量更新为进行中

for story in stories:

client.update_story(

story_id=story['id'],

status="status_3" # 进行中

)

## 🛠️ 脚本说明

### `scripts/tapd-api.sh`

Shell 命令行工具，支持快速查询。

**优点**:
- 简单易用
- 无需 Python 环境
- 适合快速查询

**限制**:
- 只读操作
- 无状态管理
- 每次都需要获取新 token

### `scripts/tapd_oauth_client.py`

Python 客户端库，支持完整功能。

**优点**:
- 完整 CRUD 支持
- Token 缓存和自动刷新
- 面向对象设计
- 错误处理完善

**推荐用法**:
- 复杂业务逻辑
- 批量操作
- 集成到其他 Python 项目

## 🔐 安全注意事项

### ⚠️ 敏感信息保护

1. **不要提交 tapd.json 到 Git**
   ```bash
   # .gitignore
   tapd.json
   tapd-*.json
   ```

2. **设置文件权限**
   ```bash
   chmod 600 tapd.json
   ```

3. **使用环境变量（可选）**
   ```bash
   export TAPD_CLIENT_ID="your-id"
   export TAPD_CLIENT_SECRET="your-secret"
   export TAPD_WORKSPACE_ID="12345678"
   ```

4. **定期更换密钥**
   - 定期在 TAPD 开放平台重置应用密钥
   - 更新 tapd.json

### 🔒 权限控制

- 只授予必要的应用权限
- 使用安全 IP 白名单（在 TAPD 开放平台设置）
- 监控 API 调用日志

## 📚 参考文档

- [TAPD 开放平台文档](https://open.tapd.cn/document/api-doc/)
- [OAuth 认证流程](https://open.tapd.cn/document/api-doc/API文档/授权凭证/项目态.html)
- [API 使用必读](https://open.tapd.cn/document/api-doc/API文档/使用必读.html)
- [完整 API 列表](https://open.tapd.cn/document/api-doc/API文档/)

## 🐛 故障排除

### 问题 1: 403 Forbidden

**原因**: OAuth 应用未被授权访问项目

**解决**:
1. 在 TAPD 项目设置中安装应用
2. 确认应用权限配置正确
3. 检查安全 IP 白名单

### 问题 2: access_token 过期

**症状**: 返回 401 Unauthorized

**解决**:
- Shell 脚本：每次都会重新获取 token
- Python 客户端：自动检测过期并刷新

### 问题 3: workspace_id 无效

**原因**: 配置的 workspace_id 不存在或无权限

**解决**:
1. 检查 URL 中的 workspace_id
2. 确认 OAuth 应用已安装到该项目
3. 使用 `/workspaces/projects` API 列出可访问的项目

## 📊 性能优化

### Token 缓存

Python 客户端会缓存 access_token：

Token 缓存到 ~/.tapd_token_cache.json

有效期内不会重复请求

### 批量请求

批量获取（推荐）

stories = client.get_stories(limit=100)

逐个获取（不推荐）

for id in story_ids:

story = client.get_story(id) # 会触发多次 API 请求

### 并发限制

TAPD API 有频率限制，建议：
- 使用 `limit` 参数批量获取
- 添加请求间隔（0.1-0.5 秒）
- 缓存不常变化的数据

## 🔄 更新日志

---

**作者**: OpenClaw Community  
**许可**: MIT  
**支持**: https://github.com/openclaw/skills