SuperAPI AI Directory

tapd-idle

General & other

View repository

Updated 10-16 09:30

About this skill

TAPD Skill

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

  1. Understand user intent → Determine the TAPD operation type
  2. Build the command → Use python scripts/tapd.py <command> [参数]
  3. Execute the script → Run using the Bash tool
  4. 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_members The command requires administrator privileges; regular users can use get_workspace_users combined with role_id to 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 --owner parameter 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 --owner parameter 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 1150372234001000020 corresponding 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 parameter current_owner(Assignee)
  • --developer → API parameter de(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:

  1. Read the images array from the returned result
  2. Use download_url to access or download images
  3. 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 Guide
  • bugs.md - Bug Operation Guide
  • iterations.md - Sprint Operation Guide
  • fields.md - Field Configuration Guide
  • testcases.md - Test Case Operation Guide