TAPD agile R&D management platform integration, calling the TAPD API via Python scripts.
Agent Usage Guide
When to Use This Skill
When the user needs to interact with the TAPD platform, proactively invoke this skill:
Trigger Keywords:
- TAPD, kanban, agile, requirements management
- Query/Create/Update requirements, defects, tasks, iterations
- Work hour entry, comment management
- Test cases, Wiki management
Agent Workflow
- Understand user intent → Determine the TAPD operation type
- Build the command → Use
python scripts/tapd.py <command> [参数] - Execute the script → Run using the Bash tool
- Process the results → Parse the JSON output and report to the user
Example Conversation
用户: "查看需求 1167459320001114969 的详情"
Agent:
1. 识别操作:查询需求详情
2. 执行: python scripts/tapd.py get_stories_or_tasks --workspace_id 67459320 --entity_type stories --id 1167459320001114969
3. 解析返回的需求信息并向用户报告
Environment Configuration
The following environment variables need to be configured before use:
export TAPD_ACCESS_TOKEN="你的个人访问令牌" # 推荐
# 或
export TAPD_API_USER="API账号"
export TAPD_API_PASSWORD="API密钥"
export TAPD_API_BASE_URL="https://api.tapd.cn" # 可选,默认
export TAPD_BASE_URL="https://www.tapd.cn" # 可选,默认
export CURRENT_USER_NICK="你的昵称" # 可选
Common Project IDs
| Project Name | workspace_id |
|---|---|
| Jubaozan | 50372234 |
Common User Group role_id
Note:
get_group_membersThe command requires administrator privileges; regular users can useget_workspace_userscombined withrole_idto filter members of a specific group.
| User Group Name | role_id |
|---|---|
| Administrator | 1000000000000000002 |
| Regular Member | 1000000000000000089 |
| QA Department | 1150372234001000002 |
| Product | 1150372234001000004 |
| Customer Success | 1150372234001000008 |
| Product Group | 1150372234001000009 |
| Funds Group | 1150372234001000010 |
| Trading Group | 1150372234001000011 |
| Architecture Group | 1150372234001000015 |
| Supervisor | 1150372234001000016 |
| Scenario Group | 1150372234001000017 |
| User Group | 1150372234001000018 |
| Frontend Group | 1150372234001000020 |
| Operations | 1150372234001000021 |
Command Quick Reference
Projects and Users
| Command | Description |
|---|---|
get_user_participant_projects |
Get the list of projects the user participates in |
get_workspace_info |
Get project information |
get_workitem_types |
Get requirement categories |
get_roles |
Get user group ID mapping |
get_workspace_users |
Get project member list |
get_group_members |
Get members of a specified user group |
Requirements/Tasks
| Command | Description |
|---|---|
get_stories_or_tasks |
Query requirements/tasks |
create_story_or_task |
Create requirements/tasks |
update_story_or_task |
Update requirements/tasks |
get_story_or_task_count |
Get count |
get_stories_fields_lable |
Chinese-English Field Mapping |
get_stories_fields_info |
Fields and candidate values |
Defects
| Command | Description |
|---|---|
get_bug |
Query defects |
create_bug |
Create defects |
update_bug |
Update defects |
get_bug_count |
Get count |
Iterations
| Command | Description |
|---|---|
get_iterations |
Query iterations |
create_iteration |
Create iterations |
update_iteration |
Update iterations |
Comments
| Command | Description |
|---|---|
get_comments |
Query comments |
create_comments |
Create comments |
update_comments |
Update Comment |
Work Hours
| Command | Description |
|---|---|
get_timesheets |
Query Work Hours |
add_timesheets |
Fill in Work Hours |
update_timesheets |
Update Work Hours |
Other Commands
| Category | Command |
|---|---|
| Attachments | get_entity_attachments, get_image |
| Custom Fields | get_entity_custom_fields |
| Workflow | get_workflows_status_map, get_workflows_all_transitions, get_workflows_last_steps |
| Test Cases | get_tcases, create_or_update_tcases, create_tcases_batch |
| Wiki | get_wiki, create_wiki, update_wiki |
| Associations | get_related_bugs, entity_relations |
| Source Code | get_commit_msg |
| Messages | send_qiwei_message |
Usage
python scripts/tapd.py <command> [参数]
All commands output results in JSON format by default.
Usage Examples
Query Requirements
# 查询指定需求
python scripts/tapd.py get_stories_or_tasks --workspace_id 123 --entity_type stories --id 1167459320001114969
# 模糊搜索需求
python scripts/tapd.py get_stories_or_tasks --workspace_id 123 --entity_type stories --name "%登录%" --limit 20
# 查询指定状态的需求
python scripts/tapd.py get_stories_or_tasks --workspace_id 123 --entity_type stories --v_status "已验收"
Query Tasks
Important: Using the
--ownerparameter to specify a Chinese name when querying tasks may return empty results. It is recommended to query all tasks first and then filter.
Task Time-related Fields:
| Field | Description |
|---|---|
begin |
Estimated Start Time |
due |
Estimated End Time |
effort |
Estimated Work Hours |
effort_completed |
Completed Work Hours |
remain |
Remaining Work Hours |
created |
Creation Time |
modified |
Last Modified Time |
completed |
Completion Time |
Task Status Values:open(Not Started),progressing(In Progress),done(Completed)
# 查询任务(包含时间相关字段)
python scripts/tapd.py get_stories_or_tasks --workspace_id 50372234 --entity_type tasks \
--fields "id,name,owner,status,begin,due,effort,effort_completed,remain,created,modified"
Frontend Team Task Statistics (Recommended Method)
Important: Directly using the
--ownerparameter to specify a Chinese name may fail to match. It is recommended to query all tasks and then filter the results.Frontend team members are dynamically queried via role_id,role_id
1150372234001000020corresponding to the frontend team.
Query by status and filter frontend team members:
# 1. 查询已完成任务
python scripts/tapd.py get_stories_or_tasks --workspace_id 50372234 --entity_type tasks \
--fields "id,name,owner,status,begin,due,effort,effort_completed,remain" \
--status done --limit 200
# 2. 查询进行中任务
python scripts/tapd.py get_stories_or_tasks --workspace_id 50372234 --entity_type tasks \
--fields "id,name,owner,status,begin,due,effort,effort_completed,remain" \
--status progressing --limit 200
# 3. 查询未开始任务
python scripts/tapd.py get_stories_or_tasks --workspace_id 50372234 --entity_type tasks \
--fields "id,name,owner,status,begin,due,effort,effort_completed,remain" \
--status open --limit 200
Complete Statistics Script(this week's task progress, by member, time range, work hours, status):
# 查询并统计(合并已完成和进行中任务)
# 先获取前端组成员(通过 role_id),再筛选任务
{
python scripts/tapd.py get_workspace_users --workspace_id 50372234
sleep 1
python scripts/tapd.py get_stories_or_tasks --workspace_id 50372234 --entity_type tasks \
--fields "id,name,owner,status,begin,due,effort,effort_completed" \
--status done --limit 200
sleep 2
python scripts/tapd.py get_stories_or_tasks --workspace_id 50372234 --entity_type tasks \
--fields "id,name,owner,status,begin,due,effort,effort_completed" \
--status progressing --limit 200
} | python3 -c "
import json
import sys
from datetime import datetime
# 前端组 role_id
FRONTEND_ROLE_ID = '1150372234001000020'
# 本周时间范围
week_start = datetime.strptime('2026-03-03', '%Y-%m-%d')
week_end = datetime.strptime('2026-03-10', '%Y-%m-%d')
# 解析所有输入
all_json = []
for line in sys.stdin:
line = line.strip()
if line and line.startswith('{'):
try:
all_json.append(json.loads(line))
except:
pass
# 提取前端组成员
frontend_members = set()
for data in all_json:
if data.get('status') == 1:
for item in data.get('data', []):
user = item.get('UserWorkspace', {})
if FRONTEND_ROLE_ID in user.get('role_id', []):
name = user.get('name') or user.get('user')
if name:
frontend_members.add(name)
# 合并任务数据
all_tasks = []
for data in all_json:
all_tasks.extend(data.get('data', []))
# 筛选前端组成员任务
member_stats = {}
for item in all_tasks:
task = item.get('Task', {})
if not task:
continue
owner = task.get('owner', '').rstrip(';')
# 筛选前端组成员
if owner not in frontend_members:
continue
effort = float(task.get('effort', 0) or 0)
effort_completed = float(task.get('effort_completed', 0) or 0)
status = task.get('status', '')
if owner not in member_stats:
member_stats[owner] = {'effort': 0, 'completed': 0, 'count': 0, 'status': {}}
member_stats[owner]['effort'] += effort
member_stats[owner]['completed'] += effort_completed
member_stats[owner]['count'] += 1
member_stats[owner]['status'][status] = member_stats[owner]['status'].get(status, 0) + 1
# 输出统计结果
print('前端组本周任务进度统计')
print('=' * 70)
print(f\"{'成员':<10} {'任务数':<6} {'预估工时':<8} {'完成工时':<8} {'状态分布'}\")
print('-' * 70)
for member, stats in sorted(member_stats.items(), key=lambda x: -x[1]['effort']):
status_str = ', '.join([f\"{k}:{v}\" for k, v in stats['status'].items()])
print(f\"{member:<10} {stats['count']:<6} {stats['effort']:<8.0f} {stats['completed']:<8.0f} {status_str}\")
print('-' * 70)
print(f\"{'合计':<10} {sum(s['count'] for s in member_stats.values()):<6} {sum(s['effort'] for s in member_stats.values()):<8.0f} {sum(s['completed'] for s in member_stats.values()):<8.0f}\")
"
Filter tasks within this week's time range
# 筛选预计时间在本周范围内的任务(通过 role_id 动态获取前端组成员)
{
python scripts/tapd.py get_workspace_users --workspace_id 50372234
sleep 1
python scripts/tapd.py get_stories_or_tasks --workspace_id 50372234 --entity_type tasks \
--fields "id,name,owner,status,begin,due,effort,effort_completed,remain" \
--limit 500
} | python3 -c "
import json
import sys
from datetime import datetime
FRONTEND_ROLE_ID = '1150372234001000020'
all_json = []
for line in sys.stdin:
line = line.strip()
if line and line.startswith('{'):
try:
all_json.append(json.loads(line))
except:
pass
# 提取前端组成员
frontend_members = set()
for data in all_json:
if data.get('status') == 1:
for item in data.get('data', []):
user = item.get('UserWorkspace', {})
if FRONTEND_ROLE_ID in user.get('role_id', []):
name = user.get('name') or user.get('user')
if name:
frontend_members.add(name)
week_start = datetime.strptime('2026-03-03', '%Y-%m-%d')
week_end = datetime.strptime('2026-03-10', '%Y-%m-%d')
print('本周任务列表(预计时间在范围内):')
for data in all_json:
for item in data.get('data', []):
task = item.get('Task', {})
if not task:
continue
owner = task.get('owner', '').rstrip(';')
if owner not in frontend_members:
continue
begin = task.get('begin', '')
due = task.get('due', '')
effort = task.get('effort', '0')
if begin:
begin_dt = datetime.strptime(begin[:10], '%Y-%m-%d')
if week_start <= begin_dt <= week_end:
print(f\" {owner} | {task.get('name')[:30]} | {begin}~{due} | 预估: {effort}h\")
"
Create Requirement
python scripts/tapd.py create_story_or_task --workspace_id 123 \
--name "用户登录功能" \
--description "## 需求描述\n用户可以通过账号密码登录系统" \
--priority_label "高" \
--owner "zhangsan" \
--iteration_name "Sprint 1"
Update Requirement Status
python scripts/tapd.py update_story_or_task --workspace_id 123 \
--id 1167459320001114969 \
--v_status "实现中"
Query Defects
python scripts/tapd.py get_bug --workspace_id 123 --title "%登录失败%" --priority_label "高"
Defect Query Parameter Description
Important: Correspondence between TAPD API parameters and script parameters:
--owner→ API parametercurrent_owner(Assignee)--developer→ API parameterde(Developer)
| Script Parameter | API Parameter | Description |
|---|---|---|
--owner |
current_owner |
Assignee |
--developer |
de |
Developer |
--created |
created |
Creation Time Range |
--version_report |
version_report |
Found Version |
--closed |
status |
Closed status aliases (closed|rejected|suspended) |
--open |
status |
Unclosed status aliases (unconfirmed|in_progress|resolved|verified) |
--exclude_status |
- | Exclude specified statuses (result filtering) |
Defect Status Description
| English Status | Chinese Status | Type |
|---|---|---|
unconfirmed |
Defect Pool | Unclosed |
in_progress |
Fixing | Unclosed |
resolved |
Pending Test | Unclosed |
verified |
Testing | Unclosed |
closed |
Completed | Closed |
rejected |
Rejected | Closed |
suspended |
Closed | End |
Bug Query Examples
Filter by developer: use the --developer parameter
# 按开发人员查询缺陷
python scripts/tapd.py get_bug --workspace_id 50372234 --developer "张三"
Filter by assignee: use the --owner parameter
# 按处理人查询缺陷
python scripts/tapd.py get_bug --workspace_id 50372234 --owner "张三"
Query by status alias: use the --closed or --open parameter
# 查询结束状态的缺陷(closed|rejected|suspended)
python scripts/tapd.py get_bug --workspace_id 50372234 --closed --developer "陈方杰"
# 查询未结束状态的缺陷(unconfirmed|in_progress|resolved|verified)
python scripts/tapd.py get_bug --workspace_id 50372234 --open --developer "陈方杰"
Exclude specified statuses: use the --exclude_status parameter
# 查询全部状态,排除完成和挂起
python scripts/tapd.py get_bug --workspace_id 50372234 --exclude_status "closed|suspended" --developer "陈方杰"
Query by time range:
python scripts/tapd.py get_bug --workspace_id 50372234 \
--created "2026-02-01~2026-02-28"
Query by found version:
# 查询线上版本缺陷
python scripts/tapd.py get_bug --workspace_id 50372234 \
--version_report "线上版本"
# 查询测试版本缺陷
python scripts/tapd.py get_bug --workspace_id 50372234 \
--version_report "测试版本"
Personnel Bug Statistics
Query all bugs of a person in a certain month:
python scripts/tapd.py get_bug --workspace_id 50372234 \
--developer "姓名" \
--created "2026-02-01~2026-02-28" \
--fields "id,title,severity,status,version_report,created"
Count a person's bugs:
python scripts/tapd.py get_bug_count --workspace_id 50372234 \
--developer "姓名" \
--created "2026-02-01~2026-02-28"
Distinguish online/test bugs:
# 线上缺陷(生产质量)
python scripts/tapd.py get_bug_count --workspace_id 50372234 \
--developer "姓名" \
--version_report "线上版本" \
--created "2026-02-01~2026-02-28"
# 测试缺陷(测试质量)
python scripts/tapd.py get_bug_count --workspace_id 50372234 \
--developer "姓名" \
--version_report "测试版本" \
--created "2026-02-01~2026-02-28"
Create Bug
python scripts/tapd.py create_bug --workspace_id 123 \
--title "登录页面显示异常" \
--description "输入正确密码后提示错误" \
--priority_label "高" \
--severity "严重"
Sprint Management
# 查询迭代
python scripts/tapd.py get_iterations --workspace_id 123
# 创建迭代
python scripts/tapd.py create_iteration --workspace_id 123 \
--name "Sprint 1" \
--startdate "2024-01-01" \
--enddate "2024-01-14" \
--creator "zhangsan"
Work Hour Management
# 查询指定实体的工时
python scripts/tapd.py get_timesheets --workspace_id 123 --entity_type story --entity_id 1167459320001114969
# 查询指定日期的工时
python scripts/tapd.py get_timesheets --workspace_id 123 --spentdate "2026-03-10"
# 查询时间范围的工时
python scripts/tapd.py get_timesheets --workspace_id 123 --spentdate "2026-03-03~2026-03-10"
# 查询指定人员的工时
python scripts/tapd.py get_timesheets --workspace_id 123 --owner "张三" --spentdate "2026-03-10"
# 填写工时
python scripts/tapd.py add_timesheets --workspace_id 123 \
--entity_type story \
--entity_id 1167459320001114969 \
--timespent "4" \
--spentdate "2024-01-08" \
--memo "开发登录功能"
Work Hour Statistics Examples
Filter frontend team work hours by member:
# 查询本周工时并筛选前端组成员(通过 role_id 动态获取)
{
python scripts/tapd.py get_workspace_users --workspace_id 50372234
sleep 1
python scripts/tapd.py get_timesheets --workspace_id 50372234 --spentdate "2026-03-03~2026-03-10"
} | python3 -c "
import json
import sys
FRONTEND_ROLE_ID = '1150372234001000020'
all_json = []
for line in sys.stdin:
line = line.strip()
if line and line.startswith('{'):
try:
all_json.append(json.loads(line))
except:
pass
# 提取前端组成员
frontend_members = set()
for data in all_json:
if data.get('status') == 1:
for item in data.get('data', []):
user = item.get('UserWorkspace', {})
if FRONTEND_ROLE_ID in user.get('role_id', []):
name = user.get('name') or user.get('user')
if name:
frontend_members.add(name)
member_stats = {}
for data in all_json:
for item in data.get('data', []):
ts = item.get('Timesheet', {})
if not ts:
continue
owner = ts.get('owner', '')
timespent = float(ts.get('timespent', 0))
spentdate = ts.get('spentdate', '')
if owner in frontend_members:
if owner not in member_stats:
member_stats[owner] = {'total_hours': 0, 'days': {}}
member_stats[owner]['total_hours'] += timespent
if spentdate not in member_stats[owner]['days']:
member_stats[owner]['days'][spentdate] = 0
member_stats[owner]['days'][spentdate] += timespent
print('前端组本周工时统计')
for member, stats in sorted(member_stats.items(), key=lambda x: -x[1]['total_hours']):
print(f\"{member}: {stats['total_hours']:.0f}h\")
print(f\"总计: {sum(s['total_hours'] for s in member_stats.values()):.0f}h\")
"
Comment Management
# 查询评论
python scripts/tapd.py get_comments --workspace_id 123 \
--entry_type stories \
--entry_id 1167459320001114969
# 创建评论
python scripts/tapd.py create_comments --workspace_id 123 \
--entry_type stories \
--entry_id 1167459320001114969 \
--description "看起来不错,可以继续完善"
User Groups and Members
# 获取用户组ID对照关系
python scripts/tapd.py get_roles --workspace_id 123
# 获取项目成员列表
python scripts/tapd.py get_workspace_users --workspace_id 123
# 获取指定用户组的成员(如:前端开发组)- 需要管理员权限
python scripts/tapd.py get_group_members --workspace_id 123 --group_name "前端开发"
# 通过 role_id 筛选前端组成员(替代方案)
python scripts/tapd.py get_workspace_users --workspace_id 50372234 | python3 -c "
import json
import sys
data = json.load(sys.stdin)
if data.get('status') == 1:
members = []
for item in data.get('data', []):
user = item.get('UserWorkspace', {})
if '1150372234001000020' in user.get('role_id', []):
members.append({
'user': user.get('user'),
'name': user.get('name') or user.get('user') or 'Unknown'
})
print(f'前端组共有 {len(members)} 人:')
for m in sorted(members, key=lambda x: x['name'] or ''):
print(f\" - {m['name']} ({m['user']})\")
"
Common Commands Quick Reference
# 需求
python scripts/tapd.py get_stories_or_tasks --workspace_id $WS_ID --entity_type stories
python scripts/tapd.py create_story_or_task --workspace_id $WS_ID --name "标题"
python scripts/tapd.py update_story_or_task --workspace_id $WS_ID --id $ID --v_status "状态"
# 缺陷
python scripts/tapd.py get_bug --workspace_id $WS_ID
python scripts/tapd.py create_bug --workspace_id $WS_ID --title "标题"
# 迭代
python scripts/tapd.py get_iterations --workspace_id $WS_ID
python scripts/tapd.py create_iteration --workspace_id $WS_ID --name "Sprint X" --startdate "2024-01-01" --enddate "2024-01-14"
# 工时
python scripts/tapd.py add_timesheets --workspace_id $WS_ID --entity_type story --entity_id $ID --timespent 4 --spentdate "2024-01-08"
# 评论
python scripts/tapd.py create_comments --workspace_id $WS_ID --entry_type stories --entry_id $ID --description "评论内容"
Status Value Description
| Type | Field | Available Values |
|---|---|---|
| Requirement Priority | priority_label |
High / Middle / Low / Nice To Have |
| Bug Priority | priority_label |
urgent / high / medium / low / insignificant |
| Bug Severity | severity |
fatal / serious / normal / prompt / advice |
| Task Status | status |
open / progressing / done |
| Sprint Status | status |
open / done |
Image Processing
When retrieving requirement details, theget_stories_or_tasks command automatically parses images in the description and obtains download links.
The returned result contains the images field:
{
"data": [
{
"Story": { "id": "1167459320001114969", "name": "需求标题", ... },
"images": [
{
"path": "/tfl/captures/2026-01/tapd_67459320_base64_1767668922_121.png",
"download_url": "https://file.tapd.cn/attachments/tmp_download/...?salt=...&time=...",
"filename": "tapd_67459320_base64_1767668922_121.png"
}
]
}
]
}
Processing Steps:
- Read the
imagesarray from the returned result - Use
download_urlto access or download images - Image links are valid for about 300 seconds
Manually Obtain Images(alternative method):
python scripts/tapd.py get_image --workspace_id 67459320 --image_path "/tfl/captures/2026-01/tapd_xxx.png"
File Structure
scripts/
├── tapd.py # 统一入口脚本(46个子命令)
├── tapd_client.py # TAPD API 客户端
└── requirements.txt
Reference Documentation
For detailed API usage instructions, please refer to the references/ directory:
stories-tasks.md- Requirement/Task Operation Guidebugs.md- Bug Operation Guideiterations.md- Sprint Operation Guidefields.md- Field Configuration Guidetestcases.md- Test Case Operation Guide