tapd

TAPD Skill

This skill provides a Python script tool for interacting with the TAPD platform, uniformly called through tapd.py .

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="你的昵称"               # 可选

Usage

python scripts/tapd.py <command> [参数]

All commands output results in JSON format by default.

Command List

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

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`	Field Chinese-English comparison
`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 comments

Attachments/Images

Command	Description
`get_entity_attachments`	Get attachments
`get_image`	Get image download links

Custom Fields

Command	Description
`get_entity_custom_fields`	Get custom field configuration

Workflow

Command	Description
`get_workflows_status_map`	Status mapping
`get_workflows_all_transitions`	Status transition
`get_workflows_last_steps`	End status

Test Cases

Command	Description
`get_tcases`	Query test cases
`create_or_update_tcases`	Create/update test cases
`create_tcases_batch`	Batch create test cases

Wiki

Command	Description
`get_wiki`	Query Wiki
`create_wiki`	Create Wiki
`update_wiki`	Update Wiki

Work Hours

Command	Description
`get_timesheets`	Query work hours
`add_timesheets`	Fill in work hours
`update_timesheets`	Update work hours

To-dos

Command	Description
`get_todo`	Get to-dos

Associations

Command	Description
`get_related_bugs`	Get associated defects
`entity_relations`	Create association relationship

Release Plans

Command	Description
`get_release_info`	Get release plans

Source Code

Command	Description
`get_commit_msg`	Get submission keywords

Message

Command	Description
`send_qiwei_message`	Send WeCom message

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 "已验收"

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 "高"

Create defect

python scripts/tapd.py create_bug --workspace_id 123 \
    --title "登录页面显示异常" \
    --description "输入正确密码后提示错误" \
    --priority_label "高" \
    --severity "严重"

Iteration 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 add_timesheets --workspace_id 123 \
    --entity_type story \
    --entity_id 1167459320001114969 \
    --timespent "4" \
    --spentdate "2024-01-08" \
    --memo "开发登录功能"

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 "看起来不错，可以继续完善"

Link requirements and defects

# 查询需求关联的缺陷
python scripts/tapd.py get_related_bugs --workspace_id 123 --story_id 1167459320001114969

# 创建关联
python scripts/tapd.py entity_relations --workspace_id 123 \
    --source_type story \
    --target_type bug \
    --source_id 1167459320001114969 \
    --target_id 1167459320001114970

Workflow

# 获取状态映射
python scripts/tapd.py get_workflows_status_map --workspace_id 123 --system story

# 获取可流转状态
python scripts/tapd.py get_workflows_all_transitions --workspace_id 123 --system story

Common command 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 descriptions

Type	Field	Available values
Requirement priority	`priority_label`	High / Middle / Low / Nice To Have
Defect priority	`priority_label`	urgent / high / medium / low / insignificant
Defect severity	`severity`	fatal / serious / normal / prompt / advice
Task status	`status`	open / progressing / done
Iteration status	`status`	open / done

How to use with Claude

When the user needs to interact with TAPD:

Read script: Learn command usage
Build command: Build parameters based on requirements
Execute script: Run with the Bash tool
Process result: Parse output, analyze data

Example workflow:

用户: "查看需求 1167459320001114969 的详情"

Claude:
1. python scripts/tapd.py get_stories_or_tasks --workspace_id 67459320 --entity_type stories --id 1167459320001114969
2. 分析返回的需求信息

Image processing

When getting requirement details,get_stories_or_tasks The 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 from the returned result the images array
Use download_url to access or download images
Image links are valid for about 300 seconds

Manually get 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           # 统一入口脚本（43个子命令）
├── tapd_client.py    # TAPD API 客户端
└── requirements.txt

About this skill

Environment Configuration

Usage

Command List

Projects and Users

Requirements/Tasks

Defects

Iterations

Comments

Attachments/Images

Custom Fields

Workflow

Test Cases

Wiki

Work Hours

To-dos

Associations

Release Plans

Source Code

Message

Usage examples

Query requirements

Create requirement

Update requirement status

Query defects

Create defect

Iteration management

Work hour management

Comment management

Link requirements and defects

Workflow

Common command quick reference

Status value descriptions

How to use with Claude

Image processing

File structure