TAPD OpenAPI 命令行工具，将 TAPD 平台的全量 OpenAPI 封装为 tapd-cli 命令，适用于终端脚本、自动化管线和 AI Agent（NPC Bot）调用。

实体	支持操作
story	add / list / update / count / fields / related-bugs / link
bug	add / list / update / count / fields / link-tcase
task	add / list / update / count
comment	add / list / count
iteration	list
wiki	add / list / update / count
tcase	add / batch-add / list / update / count / fields / categories / add-category / execute / assign / result / link-plan / remove-from-plan / unlink-story / count-by-category / category-count / custom-fields / story-by-tcase
testplan	add / list / update / count / details / progress / tcases / bugs / stories / link-story / unlink-story / by-iteration / fields
timesheet	add / list / update / count
attachment	list / by-entity / download / upload / upload-image / upload-image-base64 / get-image
document	download
user	info / workspaces

# 克隆仓库
git clone https://cnb.cool/tapd.cn/skills/tapd-cli
cd tapd-cli

# 安装依赖
npm install

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

变量	必填	说明
TAPD_API_ENDPOINT	是	TAPD API 端点，如 https://api.tapd.cn
TAPD_TOKEN	是	Bearer Token，从 TAPD 开放平台获取
TAPD_WORKSPACE_IDS	建议	项目 ID，逗号分隔多个，第一个为默认值
TAPD_NPC_ROLE	否	NPC 登录名，作为默认 author/creator
TAPD_SITE_URL	否	TAPD 前端域名，用于拼接实体链接
TAPD_COMPANY_ID	否	公司 ID
TAPD_USER_NAME	否	触发操作的用户名
TAPD_CONTEXT	否	当前上下文链接或描述
TAPD_ENTRY_TYPE	否	当前实体类型（如 stories、bug、tasks）
TAPD_ENTRY_ID	否	当前实体 ID
TAPD_COMMENT_ID	否	触发评论 ID
TAPD_COMMENT_ROOT_ID	否	根评论 ID（用于回复时定位根楼层）
TAPD_COMMENT_LOCATION	否	评论来源位置标识
TAPD_NPC_QUERY	否	NPC 收到的原始用户输入
TAPD_CLI_LOG	否	日志模式：1/text（文本）、json（JSON）、silent（关闭，默认）

export TAPD_API_ENDPOINT=https://api.tapd.cn
export TAPD_TOKEN=your_token_here
export TAPD_WORKSPACE_IDS=12345678

npx tsx src/index.ts <entity> <subcommand> [key=value ...]

# 或添加别名
alias tapd-cli="npx tsx /path/to/tapd-cli/src/index.ts"

所有参数使用 key=value 格式传入，workspaceid 可省略（自动读取 TAPD_WORKSPACE_IDS 第一个值）。

# 查询需求列表
tapd-cli story list workspaceid=12345678 v_status=规划中 limit=20

# 创建需求
tapd-cli story add workspaceid=12345678 name="新功能需求" priority_label=High owner=user1

# 更新需求状态
tapd-cli story update workspaceid=12345678 id=1149629175001000001 status=developing

# 查询缺陷
tapd-cli bug list workspaceid=12345678 status=new severity=fatal

# 创建缺陷
tapd-cli bug add workspaceid=12345678 title="登录页崩溃" severity=serious current_owner=user1

# 添加评论
tapd-cli comment add workspaceid=12345678 entry_type=stories entry_id=1149629175001000001 description="已处理"

# 批量创建测试用例
tapd-cli tcase batch-add workspaceid=12345678 names="用例1,用例2,用例3" category_id=456

# 上传附件
tapd-cli attachment upload workspaceid=12345678 type=bug entry-id=789 file=/tmp/screenshot.png

# 查询工时
tapd-cli timesheet list workspaceid=12345678 owner=user1

# 查看所有实体
tapd-cli --help

# 查看某实体的子命令
tapd-cli story --help
tapd-cli tcase --help

# 查看子命令详细参数
tapd-cli story add --help

修改 src/ 下的源码后，必须重新构建并将产物一起提交，否则 skill 实际运行的仍是旧版本：

npm run build:bundle
# 产出：skills/tapd-cli/scripts/tapd-cli.cjs

提交时需同时包含源码和产物：

git add src/ skills/tapd-cli/scripts/tapd-cli.cjs
git commit -m "feat: ..."

pre-push hook 会在每次 push 前自动执行构建，并在产物有未提交变更时阻止 push。

使用 Node.js SEA（Single Executable Application）打包为无需安装 Node.js 的独立二进制：

npm run build
# 产出：dist/tapd-cli-bin

• 语言：TypeScript 5.3
• 运行时：Node.js v18+（使用内置 fetch，无需额外 HTTP 库）
• CLI 框架：commander v11
• 开发运行：tsx（无需预编译直接运行 TS）
• 打包：esbuild + Node.js SEA

所有 description 参数支持纯文本输入，工具会自动包裹为 HTML（<p>内容</p>）。如需传入已有 HTML 则直接传入，不会二次处理。