TAPD OpenAPI

环境变量（已预置）

TAPD_API_ENDPOINT - API 地址, 如果 TAPD_API_ENDPOINT 已配置，则优先使用 TAPD_API_ENDPOINT 的替换文档中的 ${TAPD_API_ENDPOINT}
TAPD_WORKSPACE_IDS - 项目 ID 列表，逗号分隔，优先级高于 TAPD_WORKSPACE_ID
TAPD_WORKSPACE_ID - 单个项目 ID（兼容旧配置）
TAPD_TOKEN - 认证 Token（Bearer 方式）

Workspace 处理规则

调用前必须先确定实际使用的 workspace 列表：

# 优先取 TAPD_WORKSPACE_IDS，回退到 TAPD_WORKSPACE_ID
if [ -n "$TAPD_WORKSPACE_IDS" ]; then
  WS_LIST=$(echo "$TAPD_WORKSPACE_IDS" | tr ',' ' ')
else
  WS_LIST="$TAPD_WORKSPACE_ID"
fi

若 WS_LIST 只有一个 ID，按单 workspace 正常请求即可
若有多个 ID，需对每个 ID 分别调用 API，再汇总结果（求和、合并列表等，根据用户意图决定）
注意 curl 的时候 workspace_id 用逗号分隔后的，例如 $TAPD_WORKSPACE_IDS 是 "31372104,68119668"，则 curl 的时候需要分别调用 workspace_id=31372104 和 workspace_id=68119668

请求模板

# GET
curl -s -H "Authorization: Bearer $TAPD_TOKEN" \
  "${TAPD_API_ENDPOINT}/${path}?workspace_id=${ws_id}"

# POST
curl -s -X POST -H "Authorization: Bearer $TAPD_TOKEN" \
  -H "Content-Type: application/json" \
  "${TAPD_API_ENDPOINT}/${path}" \
  -d '{"workspace_id":"'"${ws_id}"'","key":"value"}'

查询 API 文档

API 文档位于 ~/.codebuddy/skills/tapd-openapi/references/ 目录。

1. 列出所有服务：

ls ~/.codebuddy/skills/tapd-openapi/references/

2. 列出服务下的 API：

ls ~/.codebuddy/skills/tapd-openapi/references/stories/

3. 查看 API 详情：

cat ~/.codebuddy/skills/tapd-openapi/references/stories/liststories.md

常用服务

服务	说明	常用 API 文件
stories	需求管理	liststories, countstories, addstory, updatestory, getrelatedbugs, getstoryfieldsinfo
bugs	缺陷管理	listbugs, countbugs, addbug, updatebug, getbugfieldsinfo
iterations	迭代管理	listiterations
tasks	任务管理	listtasks, counttasks, addtask, updatetask
comments	评论管理	listcomments, countcomments, addcomment
wikis	Wiki 管理	listwikis, countwikis, addwiki, updatewiki, searchwiki（见下方）
timesheets	工时花费	listtimesheets, counttimesheets, addtimesheet, updatetimesheet
attachments	附件管理	listattachments, downloadattachment, getimage, downloaddocument
users	用户信息	getuserinfo, listworkspaces

调用流程

确定服务：根据需求从常用服务中选择，或用 ls 查看全部
查找 API：用 ls ~/.codebuddy/skills/tapd-openapi/references/{服务}/ 找到具体操作
获取详情：用 cat 读取 API 文档，获取请求方法、路径、参数
执行请求：按模板构造 curl 命令，workspace_id 必传

Wiki 搜索

TAPD API 不支持 Wiki 全文搜索，通过本地脚本实现。详见：

cat ~/.codebuddy/skills/tapd-openapi/references/wikis/searchwiki.md