| name | tapd-story |
| description | TAPD 需求技能，用于读取、更新 TAPD 需求，读取/新增/修改需求评论，以及通过 TestX design 接口读取需求；读取需求时只处理 API 返回的文本字段。依赖 tapd-base 提供 OAuth 和用户态 API token；需要把需求关联到 TestX 时可继续使用 tapd-testx。 |
TAPD Story 操作
使用这个 skill 处理 TAPD 需求读取、更新、需求评论读取/新增/修改，以及 TestX design 侧的需求读取。执行前必须先确认相邻目录存在 tapd-base，并按 tapd-base 完成配置和 token 检查。
串联方式
- 需求读取/更新/评论：
tapd-base -> tapd-story
- 读取需求后创建或关联 TestX 用例：
tapd-base -> tapd-story -> tapd-testx
前置检查
命令示例默认已设置 skills 根目录。Codex 全局安装通常是 ~/.codex/skills，Claude Code 全局安装通常是 ~/.claude/skills：
export TAPD_SKILLS_ROOT="${TAPD_SKILLS_ROOT:-$HOME/.codex/skills}"
先检查 TAPD 用户态配置：
python3 "$TAPD_SKILLS_ROOT/tapd-base/scripts/tapd_user_oauth_demo.py" check-config
如果没有可用 token，先通过 tapd-base 完成授权：
python3 "$TAPD_SKILLS_ROOT/tapd-base/scripts/tapd_user_oauth_demo.py" authorize
已验证规则
- 默认
TAPD_SCOPES=user story#read story#write comment#read comment#write 覆盖需求读取、更新和评论场景
- TestX design 读取需求时，路径里两个 workspace 都必须填真实
workspace_id
正确：
/api/testx/design/v2/namespaces/{workspace_id}/workspaces/{workspace_id}/stories
错误：
/api/testx/design/v2/namespaces/{workspace_id}/workspaces/0/stories
错误写法会触发：
项目关联的workspace不正确
需求读取边界
- 读取需求描述时，只使用
story-get 或 design-story-get 返回的文本字段，例如 name、description、status、owner、developer、created、modified。
description 可能是 HTML。可以基于其中的文字内容做摘要；遇到 <img>、附件、截图、相对图片路径或富文本媒体标签时，只说明“描述中包含图片/附件，未解析图片内容”。- 不要为了补全截图里的信息调用浏览器、chrome-devtools、图片下载、OCR、视觉模型或其它图像读取流程，除非用户在当前请求中明确要求解析图片。
- 当用户只是要求“看下需求描述”时，输出文本内容和必要的元信息即可；不要主动打开 TAPD 页面或截图资源。
读取 TAPD 需求
python3 "$TAPD_SKILLS_ROOT/tapd-story/scripts/tapd_story.py" \
story-get \
--workspace-id 32131908 \
--story-id 1132131908001006860
更新 TAPD 需求
按 TAPD 官方“更新需求”接口封装，使用 POST /stories，必填 id 和 workspace_id。payload-file 可以直接放需求字段对象，也可以放带 Story 键的对象。命令行里的 --workspace-id 和 --story-id 会覆盖 payload 中的同名字段，避免误更新其它需求。
python3 "$TAPD_SKILLS_ROOT/tapd-story/scripts/tapd_story.py" \
story-update \
--workspace-id 32131908 \
--story-id 1132131908001006860 \
--payload-file /absolute/path/to/story.json
payload 示例：
{
"Story": {
"name": "更新后的需求标题",
"priority_label": "高",
"owner": "tester;"
}
}
通过 TestX design 接口读取需求
python3 "$TAPD_SKILLS_ROOT/tapd-story/scripts/tapd_story.py" \
design-story-get \
--workspace-id 32131908 \
--story-id 1132131908001006860
读取 TAPD 需求评论
按 TAPD 官方“获取评论”接口封装，使用 GET /comments。读取某条需求的评论时传 --story-id，脚本会默认使用 entry_type=stories 和 entry_id=<story_id>。也可以传 --comment-id 读取指定评论，或传 --description、--limit、--page、--order、--fields 控制查询、分页、排序和字段。
注意：TAPD 的 description 参数不等同于稳定的“包含文本”搜索。需要按页面文本查找评论时，优先使用 comment-find，它会读取评论后在本地剥离 HTML 并做关键词包含匹配。
python3 "$TAPD_SKILLS_ROOT/tapd-story/scripts/tapd_story.py" \
comment-list \
--workspace-id 32131908 \
--story-id 1132131908001006860 \
--limit 50 \
--order "created desc"
按文本查找 TAPD 需求评论
python3 "$TAPD_SKILLS_ROOT/tapd-story/scripts/tapd_story.py" \
comment-find \
--workspace-id 32131908 \
--story-id 1132131908001006860 \
--keyword "hello from browser"
读取 TAPD 需求变更历史
需求评论也会出现在 story_changes 的 comment 或 field_changes 字段中。需要对照页面动态时可以使用：
python3 "$TAPD_SKILLS_ROOT/tapd-story/scripts/tapd_story.py" \
story-change-list \
--workspace-id 32131908 \
--story-id 1132131908001006860 \
--limit 100 \
--order "created desc"
新增 TAPD 需求评论
按 TAPD 官方“添加评论接口”封装，使用 POST /comments。需求评论默认 entry_type=stories，必填 workspace_id、story_id、description 和 author；回复评论时可选传 --root-id 或 --reply-id。
python3 "$TAPD_SKILLS_ROOT/tapd-story/scripts/tapd_story.py" \
comment-add \
--workspace-id 32131908 \
--story-id 1132131908001006860 \
--description "这个需求需要补充验收标准" \
--author tester
修改 TAPD 评论
按 TAPD 官方“更新评论接口”封装，使用 POST /comments。必填 workspace_id、comment_id 和 description；需要记录变更人时可选传 --change-creator。
python3 "$TAPD_SKILLS_ROOT/tapd-story/scripts/tapd_story.py" \
comment-update \
--workspace-id 32131908 \
--comment-id 1020355782058781915 \
--description "更新后的评论内容" \
--change-creator tester
