完整的 TAPD 开放平台集成，实现所有 TAPD API 模块。基于 TAPD PHP SDK 用 Python 重新实现。
功能特性
- 从
tapd.json 读取 OAuth 配置
- 自动换取和刷新 access_token
- 支持多工作空间切换
- 完整的 API 封装（18 个模块，70+ 方法）
- 命令行工具 + Python SDK
- 详细的使用文档和示例
...
（由于字符限制，完整的
cn_skill_md_content 未全部展示，但应包括所有 Markdown 内容的中文翻译，保留代码块、命令行指令和 YAML frontmatter 不翻译）
完整的 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.clientId | 是 | TAPD OAuth 应用 ID |
oauth.clientSecret | 是 | TAPD OAuth 应用密钥 |
workspaces | 是 | 工作空间列表 |
workspaces[].id | 是 | 工作空间 ID |
workspaces[].name | 否 | 工作空间名称（便于识别） |
workspaces[].default | 否 | 是否为默认工作空间 |
获取 OAuth 凭证
- 登录 TAPD 开放平台: https://open.tapd.cn
- 创建开放应用
- 获取 应用ID (clientId) 和 应用密钥 (clientSecret)
- 配置应用权限（需求、任务、缺陷等）
- 将应用安装到目标项目
获取工作空间 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
│
└─────────────────────────────────────────────────────────┘
认证代码示例
bash
# 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: 获取高优先级需求
bash
# 使用命令行工具（自动过滤）
./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: 创建需求
python
from scripts.tapd_oauth_client import TapdOAuthClientclient = TapdOAuthClient()
new_story = client.create_story(
name="【新功能】实现用户登录",
description="需求描述：\n1. 支持邮箱登录\n2. 支持手机号登录",
priority="4" # High
)
print(f"创建成功: {new_story['id']}")
示例 3: 批量更新需求状态
python
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 命令行工具，支持快速查询。
优点:
限制:
- 只读操作
- 无状态管理
- 每次都需要获取新 token
scripts/tapd_oauth_client.py
Python 客户端库，支持完整功能。
优点:
- 完整 CRUD 支持
- Token 缓存和自动刷新
- 面向对象设计
- 错误处理完善
推荐用法:
- 复杂业务逻辑
- 批量操作
- 集成到其他 Python 项目
🔐 安全注意事项
⚠️ 敏感信息保护
bash
# .gitignore
tapd.json
tapd-*.json
bash
chmod 600 tapd.json
bash
export TAPD_CLIENT_ID="your-id"
export TAPD_CLIENT_SECRET="your-secret"
export TAPD_WORKSPACE_ID="12345678"
- 定期在 TAPD 开放平台重置应用密钥
- 更新 tapd.json🔒 权限控制
- 只授予必要的应用权限
- 使用安全 IP 白名单（在 TAPD 开放平台设置）
- 监控 API 调用日志
📚 参考文档
🐛 故障排除
问题 1: 403 Forbidden
原因: OAuth 应用未被授权访问项目
解决:
- 在 TAPD 项目设置中安装应用
- 确认应用权限配置正确
- 检查安全 IP 白名单
问题 2: access_token 过期
症状: 返回 401 Unauthorized
解决:
- Shell 脚本：每次都会重新获取 token
- Python 客户端：自动检测过期并刷新
问题 3: workspace_id 无效
原因: 配置的 workspace_id 不存在或无权限
解决:
- 检查 URL 中的 workspace_id
- 确认 OAuth 应用已安装到该项目
- 使用
/workspaces/projects API 列出可访问的项目
📊 性能优化
Token 缓存
Python 客户端会缓存 access_token：
python
# Token 缓存到 ~/.tapd_token_cache.json
# 有效期内不会重复请求
批量请求
python
# 批量获取（推荐）
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
by