TAPD Skill

本 skill 提供与 TAPD 平台交互的 Python 脚本工具，统一通过

tapd.py

调用。

本Skill提供与TAPD平台交互的Python脚本工具，统一通过

tapd.py

调用。

环境配置

使用前需要配置以下环境变量：

bash

export TAPD_ACCESS_TOKEN="你的个人访问令牌"  # 推荐

使用前需要配置以下环境变量：

bash

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

undefined

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

undefined

使用方式

bash

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

所有命令默认输出 JSON 格式结果。

bash

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

所有命令默认输出JSON格式结果。

命令列表

项目与用户

命令	说明
`get_user_participant_projects`	获取用户参与的项目列表
`get_workspace_info`	获取项目信息
`get_workitem_types`	获取需求类别

命令	说明
`get_user_participant_projects`	获取用户参与的项目列表
`get_workspace_info`	获取项目信息
`get_workitem_types`	获取需求类别

需求/任务

命令	说明
`get_stories_or_tasks`	查询需求/任务
`create_story_or_task`	创建需求/任务
`update_story_or_task`	更新需求/任务
`get_story_or_task_count`	获取数量
`get_stories_fields_lable`	字段中英文对照
`get_stories_fields_info`	字段及候选值

命令	说明
`get_stories_or_tasks`	查询需求/任务
`create_story_or_task`	创建需求/任务
`update_story_or_task`	更新需求/任务
`get_story_or_task_count`	获取数量
`get_stories_fields_lable`	字段中英文对照
`get_stories_fields_info`	字段及候选值

缺陷

命令	说明
`get_bug`	查询缺陷
`create_bug`	创建缺陷
`update_bug`	更新缺陷
`get_bug_count`	获取数量

命令	说明
`get_bug`	查询缺陷
`create_bug`	创建缺陷
`update_bug`	更新缺陷
`get_bug_count`	获取数量

迭代

命令	说明
`get_iterations`	查询迭代
`create_iteration`	创建迭代
`update_iteration`	更新迭代

命令	说明
`get_iterations`	查询迭代
`create_iteration`	创建迭代
`update_iteration`	更新迭代

命令	说明
`get_comments`	查询评论
`create_comments`	创建评论
`update_comments`	更新评论

命令	说明
`get_comments`	查询评论
`create_comments`	创建评论
`update_comments`	更新评论

附件/图片

命令	说明
`get_entity_attachments`	获取附件
`get_image`	获取图片下载链接

命令	说明
`get_entity_attachments`	获取附件
`get_image`	获取图片下载链接

自定义字段

命令	说明
`get_entity_custom_fields`	获取自定义字段配置

命令	说明
`get_entity_custom_fields`	获取自定义字段配置

工作流

命令	说明
`get_workflows_status_map`	状态映射
`get_workflows_all_transitions`	状态流转
`get_workflows_last_steps`	结束状态

命令	说明
`get_workflows_status_map`	状态映射
`get_workflows_all_transitions`	状态流转
`get_workflows_last_steps`	结束状态

测试用例

命令	说明
`get_tcases`	查询测试用例
`create_or_update_tcases`	创建/更新测试用例
`create_tcases_batch`	批量创建测试用例

命令	说明
`get_tcases`	查询测试用例
`create_or_update_tcases`	创建/更新测试用例
`create_tcases_batch`	批量创建测试用例

Wiki

命令	说明
`get_wiki`	查询 Wiki
`create_wiki`	创建 Wiki
`update_wiki`	更新 Wiki

命令	说明
`get_wiki`	查询 Wiki
`create_wiki`	创建 Wiki
`update_wiki`	更新 Wiki

工时

命令	说明
`get_timesheets`	查询工时
`add_timesheets`	填写工时
`update_timesheets`	更新工时

命令	说明
`get_timesheets`	查询工时
`add_timesheets`	填写工时
`update_timesheets`	更新工时

待办

命令	说明
`get_todo`	获取待办

命令	说明
`get_todo`	获取待办

关联

命令	说明
`get_related_bugs`	获取关联缺陷
`entity_relations`	创建关联关系

命令	说明
`get_related_bugs`	获取关联缺陷
`entity_relations`	创建关联关系

发布计划

命令	说明
`get_release_info`	获取发布计划

命令	说明
`get_release_info`	获取发布计划

源码

命令	说明
`get_commit_msg`	获取提交关键字

命令	说明
`get_commit_msg`	获取提交关键字

消息

命令	说明
`send_qiwei_message`	发送企业微信消息

命令	说明
`send_qiwei_message`	发送企业微信消息

使用示例

查询需求

bash

undefined

bash

undefined

查询指定需求

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

undefined

python scripts/tapd.py get_stories_or_tasks --workspace_id 123 --entity_type stories --v_status "已验收"

undefined

创建需求

bash

python scripts/tapd.py create_story_or_task --workspace_id 123 \
    --name "用户登录功能" \
    --description "## 需求描述\n用户可以通过账号密码登录系统" \
    --priority_label "高" \
    --owner "zhangsan" \
    --iteration_name "Sprint 1"

bash

python scripts/tapd.py create_story_or_task --workspace_id 123 \
    --name "用户登录功能" \
    --description "## 需求描述\n用户可以通过账号密码登录系统" \
    --priority_label "高" \
    --owner "zhangsan" \
    --iteration_name "Sprint 1"

更新需求状态

bash

python scripts/tapd.py update_story_or_task --workspace_id 123 \
    --id 1167459320001114969 \
    --v_status "实现中"

bash

python scripts/tapd.py update_story_or_task --workspace_id 123 \
    --id 1167459320001114969 \
    --v_status "实现中"

查询缺陷

bash

python scripts/tapd.py get_bug --workspace_id 123 --title "%登录失败%" --priority_label "高"

bash

python scripts/tapd.py get_bug --workspace_id 123 --title "%登录失败%" --priority_label "高"

创建缺陷

bash

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

bash

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

迭代管理

bash

undefined

bash

undefined

查询迭代

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"

undefined

python scripts/tapd.py create_iteration --workspace_id 123
--name "Sprint 1"
--startdate "2024-01-01"
--enddate "2024-01-14"
--creator "zhangsan"

undefined

工时管理

bash

undefined

bash

undefined

查询工时

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 "开发登录功能"

undefined

python scripts/tapd.py add_timesheets --workspace_id 123
--entity_type story
--entity_id 1167459320001114969
--timespent "4"
--spentdate "2024-01-08"
--memo "开发登录功能"

undefined

评论管理

bash

undefined

bash

undefined

查询评论

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

undefined

python scripts/tapd.py create_comments --workspace_id 123
--entry_type stories
--entry_id 1167459320001114969
--description "看起来不错，可以继续完善"

undefined

关联需求与缺陷

bash

undefined

bash

undefined

查询需求关联的缺陷

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

undefined

python scripts/tapd.py entity_relations --workspace_id 123
--source_type story
--target_type bug
--source_id 1167459320001114969
--target_id 1167459320001114970

undefined

工作流

bash

undefined

bash

undefined

获取状态映射

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

undefined

python scripts/tapd.py get_workflows_all_transitions --workspace_id 123 --system story

undefined

常用命令速查

bash

undefined

bash

undefined

需求

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"

类型	字段	可用值
需求优先级	`priority_label`	High / Middle / Low / Nice To Have
缺陷优先级	`priority_label`	urgent / high / medium / low / insignificant
缺陷严重程度	`severity`	fatal / serious / normal / prompt / advice
任务状态	`status`	open / progressing / done
迭代状态	`status`	open / done

类型	字段	可用值
需求优先级	`priority_label`	High / Middle / Low / Nice To Have
缺陷优先级	`priority_label`	urgent / high / medium / low / insignificant
缺陷严重程度	`severity`	fatal / serious / normal / prompt / advice
任务状态	`status`	open / progressing / done
迭代状态	`status`	open / done

Claude 使用方式

当用户需要与 TAPD 交互时：

读取脚本：了解命令用法
构建命令：根据需求构建参数
执行脚本：使用 Bash 工具运行
处理结果：解析输出，分析数据

示例工作流：

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

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

当用户需要与 TAPD 交互时：

读取脚本：了解命令用法
构建命令：根据需求构建参数
执行脚本：使用 Bash 工具运行
处理结果：解析输出，分析数据

示例工作流：

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

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

图片处理

当获取需求详情时，

get_stories_or_tasks

命令会自动解析 description 中的图片并获取下载链接。

返回结果包含
images
字段：

json

{
  "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"
        }
      ]
    }
  ]
}

处理步骤：

从返回结果中读取
```
images
```
数组
使用
```
download_url
```
访问或下载图片
图片链接有效期约 300 秒

手动获取图片（备用方式）：

bash

undefined

当获取需求详情时，

get_stories_or_tasks

命令会自动解析 description 中的图片并获取下载链接。

返回结果包含
images
字段：

json

{
  "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"
        }
      ]
    }
  ]
}

处理步骤：

从返回结果中读取
```
images
```
数组
使用
```
download_url
```
访问或下载图片
图片链接有效期约 300 秒

手动获取图片（备用方式）：

bash

undefined

如果需要单独获取某张图片

python scripts/tapd.py get_image --workspace_id 67459320 --image_path "/tfl/captures/2026-01/tapd_xxx.png"

undefined

python scripts/tapd.py get_image --workspace_id 67459320 --image_path "/tfl/captures/2026-01/tapd_xxx.png"

undefined

文件结构

scripts/
├── tapd.py           # 统一入口脚本（43个子命令）
├── tapd_client.py    # TAPD API 客户端
└── requirements.txt

scripts/
├── tapd.py           # 统一入口脚本（43个子命令）
├── tapd_client.py    # TAPD API 客户端
└── requirements.txt

tapd

Original

Translation

TAPD Skill

TAPD Skill

环境配置

环境配置

或

或

使用方式

使用方式

命令列表

命令列表

项目与用户

项目与用户

需求/任务

需求/任务

缺陷

缺陷

迭代

迭代

评论

评论

附件/图片

附件/图片

自定义字段

自定义字段

工作流

工作流

测试用例

测试用例

Wiki

Wiki

工时

工时

待办

待办

关联

关联

发布计划

发布计划

源码

源码

消息

消息

使用示例

使用示例

查询需求

查询需求

查询指定需求

查询指定需求

模糊搜索需求

模糊搜索需求

查询指定状态的需求

查询指定状态的需求

创建需求

创建需求

更新需求状态

更新需求状态

查询缺陷

查询缺陷

创建缺陷

创建缺陷

迭代管理

迭代管理

查询迭代

查询迭代

创建迭代

创建迭代

工时管理

工时管理

查询工时

查询工时

填写工时

填写工时

评论管理

评论管理

查询评论

查询评论

创建评论