TAPD API Skill

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

📋 功能特性

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

🔧 配置

配置文件 (tapd.json)

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

CODEBLOCK0

配置项说明

参数	必需	说明
INLINECODE2	是	TAPD OAuth 应用 ID
INLINECODE3

获取 OAuth 凭证

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

获取工作空间 ID

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

🚀 快速开始

1. 创建配置文件

CODEBLOCK1

2. Python SDK 使用

CODEBLOCK2

3. 多工作空间切换

CODEBLOCK3

3. Shell 命令行使用

CODEBLOCK4

获取需求列表

stories = client.get_stories(limit=10) for story in stories: print(f"{story['id']}: {story['name']}")

获取需求详情

storydetail = client.getstory(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 │ │ granttype=clientcredentials │ │ 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

ACCESSTOKEN=$(curl -s -u "$CLIENTID:$CLIENT_SECRET" \ -d "granttype=clientcredentials" \ "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.tapdoauthclient import TapdOAuthClient

client = TapdOAuthClient()

newstory = client.createstory(
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 命令行工具，支持快速查询。

**优点**:
- 简单易用
- 无需 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 TAPDCLIENTID="your-id" export TAPDCLIENTSECRET="your-secret" export TAPDWORKSPACEID="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：

python

Token 缓存到 ~/.tapdtokencache.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

TAPD API 技能

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

📋 功能特性

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

🔧 配置

配置文件 (tapd.json)

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

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

获取 OAuth 凭证

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

获取工作空间 ID

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

🚀 快速开始

1. 创建配置文件

bash

创建 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 使用

python
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], workspaceid=defaultworkspace[id] )

获取需求列表

stories = client.story.list( workspaceid=defaultworkspace[id], limit=10 )

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

3. 多工作空间切换

python

遍历所有工作空间

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 命令行使用

bash

设置环境变量（从配置文件读取）

export TAPDCLIENTID=$(cat tapd.json | jq -r .oauth.clientId)
export TAPDCLIENTSECRET=$(cat tapd.json | jq -r .oauth.clientSecret)
export TAPDWORKSPACEID=$(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]})

获取需求详情

storydetail = client.getstory(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 │
│ granttype=clientcredentials │
│ 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

ACCESSTOKEN=$(curl -s -u $CLIENTID:$CLIENT_SECRET \ -d granttype=clientcredentials \ 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	workspaceid, limit, page, status	获取需求列表
GET

任务 (Tasks)

方法	端点	参数	说明
GET	/tasks	workspaceid, limit, page	获取任务列表
POST

/tasks | workspaceid, name, ... | 创建/更新任务 |

缺陷 (Bugs)

方法	端点	参数	说明
GET	/bugs	workspaceid, limit, page, status	获取缺陷列表
POST

/bugs | workspaceid, 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]

tapd-apiTAPD API集成

tapd-api

TAPD API Skill

📋 功能特性

🔧 配置

配置文件 (tapd.json)

配置项说明

获取 OAuth 凭证

获取工作空间 ID

🚀 快速开始

1. 创建配置文件

2. Python SDK 使用

3. 多工作空间切换

3. Shell 命令行使用

获取需求列表

获取需求详情

获取任务列表

获取缺陷列表

Shell 方式

获取 access_token

调用 API

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

获取所有 planning 状态的需求

批量更新为进行中

Token 缓存到 ~/.tapdtokencache.json

有效期内不会重复请求

批量获取（推荐）

逐个获取（不推荐）

🔄 更新日志

TAPD API 技能

📋 功能特性

🔧 配置

配置文件 (tapd.json)

配置项说明

获取 OAuth 凭证

获取工作空间 ID

🚀 快速开始

1. 创建配置文件

创建 tapd.json

设置权限

2. Python SDK 使用

读取配置

获取默认工作空间

初始化客户端

获取需求列表

3. 多工作空间切换

遍历所有工作空间

3. Shell 命令行使用

设置环境变量（从配置文件读取）

使用命令行工具

获取需求列表

获取需求详情

获取任务列表

获取缺陷列表

📖 API 认证流程

OAuth 流程图

认证代码示例

Shell 方式

获取 access_token

调用 API

🔌 API 端点

需求 (Stories)

任务 (Tasks)

缺陷 (Bugs)

迭代 (Iterations)

其他

📝 使用示例

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

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

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement