TAPD 需求故事生成

把用户的一句话背景，扩充成一条可直接进 TAPD 的需求故事。核心判断：这是给研发/测试看的需求契约，不是方案文档。写清楚"为什么要做"和"做成什么样算完"，不写"怎么做"。

一、检查是否已初始化

满足以下三条就直接跳到「三、生成」：

• ~/.tapd/env 存在，且 TAPD_TOKEN 有值（不是空、不是 __PENDING__）
• ~/.tapd/env 里 TAPD_WORKSPACE_IDS 有值
• ~/.tapd/project-profile.md 存在

任一不满足 → 走「二、首次使用」。

二、首次使用：只问两条信息

新用户第一次用，不要问一堆配置，只要这两样：个人访问令牌 + 项目链接。

必须发给用户的引导（逐项讲清，不能只说"给我令牌和链接"）

首次使用时的回复必须完整覆盖下面 5 块。缺任何一块都算引导不到位：

① 我要什么、为什么要

> 第一次用需要两样东西：① TAPD 个人访问令牌 ② 你项目的链接。有了这两样，我就能自动认出项目、字段和模块词，以后你只说一句需求就行。

② 令牌去哪拿（给路径 + 给链接）

> 令牌获取：https://www.tapd.cn/personal_settings/index?tab=personal_token
> 位置是 TAPD 右上角头像 → 个人设置 → 安全设置 → API 令牌 → 创建。
> 只显示一次，生成后立刻复制，关掉就看不到了。

③ 项目链接怎么取（给示例 + 说明不用自己找 ID）

> 项目链接：随便打开项目里的一条需求，复制地址栏就行，例如
> https://www.tapd.cn/12345678/prong/stories/view/1130527882001122917
> 中间那段数字就是项目 ID，我来解析，你不用自己找。

④ 发我之后会发生什么（让用户知道下一步，不用他动手）

> 收到后我会：写入本机配置（~/.tapd/env，权限 600）→ 校验令牌和项目权限 → 探测一次项目配置（优先级/类别/分类/自定义字段/模块词表）存成档案。之后直接把一句话需求发我，我出草稿、你确认、我建单并回传链接。

⑤ 安全提醒（一次，不啰嗦）

> 令牌等同你的账号凭证，只在这条对话发我、只落到本机文件，不要发到群里或提交到 Git。

执行

拿到两条信息后：

1. 先确认 CLI 在位：tapd-cli --version（找不到就试 "$HOME/.local/bin/tapd-cli.exe" --version）。
   没有 → 按 references/onboarding.md 第 1 节安装（macOS/Linux 用 install.sh，Windows 直接下
   release 二进制，因为 irm | iex 常被安全策略拦），装完再继续。装的过程不用问用户任何信息。
2. 再跑初始化：

bash scripts/init.sh "<项目链接或项目ID>" "<个人访问令牌>"

脚本自动完成：解析 workspace_id → 写 ~/.tapd/env → 校验令牌与项目权限 → 打印项目 ID 与下一步。
脚本失败时按报错提示处理，不要反复重试（最多 2 次）。

3. 探测项目配置（只需一次），步骤见 references/onboarding.md 第 3-4 节，产物是
   ~/.tapd/project-profile.md：优先级枚举、需求类别、分类 ID、自定义字段、标题【模块】词表、近期迭代。

4. 回一句接入小结给用户：项目 ID（能取到项目名就带上）、默认分类（未分类）、默认优先级（P1）、
   以及"现在可以直接发需求了"。不报技术细节、不贴命令输出。

没有 project-profile.md 就不要猜字段值。 字段类参数（workitem_type_id、
category_id、自定义字段）必须先探测或先查询。

只给了一半信息怎么办

不要重新问一遍全部，只补缺的那一项，并把另一项记住：

• 只给了令牌 → 「令牌收到。还差项目链接：打开项目里任意一条需求，复制地址栏 URL 给我就行。」
• 只给了链接 → 「项目 ID 已解析为 <id>。还差令牌：https://www.tapd.cn/personal_settings/index?tab=personal_token
  （个人设置 → 安全设置 → API 令牌 → 创建，只显示一次，生成后立刻复制）」
• 给了令牌但项目里没权限 → 直接说清原因和解决动作（找项目管理员加权限，或换本人有权限的项目链接），
  不要让用户自己猜。

引导的反面（不要这样做）

• ❌ 只说"请提供令牌和项目链接"，不说去哪拿、怎么复制
• ❌ 一次抛出 5 个问题（端点、项目 ID、分类、优先级、迭代），第一次只需要两样
• ❌ 让用户自己去 TAPD 里找项目 ID 数字
• ❌ 让用户自己配环境变量、自己装依赖，却不说装在哪、怎么验证

三、生成

输入

用户通常只给一句话，可能只有场景，缺角色、缺痛点、缺范围。处理顺序：

1. 先判断这句话属于哪个业务域（学生端 / 教师端 / 家长端 / 后台 / 内容），角色是谁。
2. 信息缺口最多问 1 个真正卡住的关键问题（通常是"给谁用、解决什么问题"）。其余缺口直接写「（待确认）」占位，不要反复追问。
3. 直接出草稿。宁可带着待确认项先出来，也不要空转。

输出格式（严格遵守）

【标题】【模块】用户 + 可执行动作

【需求背景】
- 现状与痛点（2-3 条）
- 影响范围 / 谁在抱怨
- 用户故事：作为 XX / 我希望 XX / 以此 XX

【需求目标】
- 3-4 条

【优化方案】
- 一句话概述（由背景与目标推导）
- 以下空白，待人工补充

【验收标准】
- 3-4 条，每条 "当用户…时，应该…"

草稿的小标题与 TAPD 正文完全一致，用户看到什么就落库成什么，不做二次翻译。

标题

• 格式：【模块】用户 + 可执行动作，如「【首页】运营可配置灰度发布范围」。
• 模块要自己判断：从一句话背景推断这个需求落在哪个功能域，不要照抄用户原话、也不要反问"这属于哪个模块"。
• 模块词必须来自项目词表：判断后去 ~/.tapd/project-profile.md 的「标题模块词表」里比对。
  命中就用；没命中就是新模块，要主动提示用户「XX 是词表里没有的新模块，确认用这个吗」，不要默默生造。
• 反面：【牛听听】【付费模块】【模考模块】【硬件适配】【教材】——这些看着合理但都不在词表里。
  正确做法分别落到词表已有的【听力机】【付费】【听说模考】。
• 判断不出来时标「（待确认模块）」，不要硬填。
• 动词用书面正式词：获取、创建、配置、筛选、导出、查看（避免"收到""看到""搞"等口语）。
• 简短，一句话说完，不带标点尾巴，不写"需求""优化"这类空词（除非模块本身就是"优化"）。
• 标题里不要出现这些（都是雷区，写完自查一遍）：
• 括号补充说明：…（支持管理员） → 把内容并进正文或标题主干
• 动词重复：听力机支持 XX 设备支持 → 新增兼容 XX 机型
• 多余标点：页面根据，教材是否收费显示标签
• 用 / & 拼接 → 改用「、」或「与」
• 句中夹空格：超记牛 2 Pro 这类型号名除外，普通中文词之间不留空格

需求背景

• 项目符号，不用表格。
• 只写真实存在的客户反馈、既有事实。没有真实来源就写「（待确认）」，禁止编造数据、用户原话、调研结论。
• 末尾必须有用户故事三句式：作为 XX / 我希望 XX / 以此 XX。
• 不写实现思路，不写方案对比。

需求目标

• 3-4 条，写做成之后带来的变化，不是功能清单。
• 优先业务/用户价值，能量化就量化（覆盖率、耗时、完成率），量化不了的写清楚方向。
• 不写"开发 XX 接口""新增 XX 字段"这类实现。

优化方案

• 先写一句话概述：从【需求背景】的痛点和【需求目标】的预期反推，说清"大体怎么做"，
  例如「后台新增首页灰度配置，运营按比例与人群分批放开，未命中用户保持旧版，异常时可关闭并回滚」。
  一句话，不展开。
• 概述下方留空白行，供人工补充实现细节、PRD/原型链接。
• 用户已给出方案或链接时，直接采用，不要用自己的概述覆盖。

验收标准

• 3-4 条，统一句式：当用户…时，应该…。
• 宏观简短，只写行为结果，不写页面细节、不写接口字段、不写具体交互参数。
• 覆盖正常路径 + 1 条边界/异常（如无数据、权限不足、弱网）。
• 一条一个断言，可测、不歧义。
• 必带一条存量/回归项：改动类需求一定要写"原有功能不受影响、存量数据兼容"，
  例如「当用户使用原有已支持机型时，应该功能无退化」。这是最容易漏、也最容易出线上事故的一条。
• 禁止过程性描述：记录适配问题并修复完成 联调通过 完成自测 这类不算验收标准，
  测不出来也判不了完成，一律不写。
• 不写实现路径：读取配置 上报数据 调用 XX 接口 属于怎么做，留给优化方案或开发细化。

单行卡片（可选输出）

用户要贴到飞书、群里或做任务看板时，额外给一个单行精简版，不要替代完整草稿：

【模块】标题 ｜ 价值：一句话说清做成后的变化 ｜ 验收：要点1 / 要点2 / 要点3

三个验收要点从完整版里挑最关键的，不再新增内容。

四、写入 TAPD

草稿经用户确认后再写入，不要自作主张创建。

默认值

步骤（必须走两步，不要一次带 description）

> 踩过的坑：story add 里同时传长 HTML description，会导致其他字段被错误覆盖——
> 实测类别从「故事」变成「子任务」、name 被写成状态枚举名「产品验收」。
> 而 story update 不支持改 workitem_type_id，add 阶段错了就改不回来。
> 所以：先建骨架、验字段、再补正文。

第 1 步：建骨架（不带 description）

tapd-cli story add workspaceid=<id> name="【模块】标题" \
  workitem_type_id=<故事id> priority_label=P1 category_id=-1

第 2 步：立刻读回验证，有一项不对就停手

tapd-cli story list workspaceid=<id> id=<新id> | jq '.data[0].Story | {name,status,priority_label,workitem_type_id,category_id}'

核对四项：name 完整无截断、status 为初始态（如 status_4 待评审）、类别是「故事」、分类是预期值。
发现异常先修这一条（改名标记作废 + 状态置挂起），再排查原因，不要继续往错数据上写正文。

第 3 步：补正文（只用 update）

tapd-cli story update workspaceid=<id> id=<新id> \
  description="<b>需求背景</b><br />- …<br /><br /><b>需求目标</b><br />- …<br /><br /><b>优化方案</b><br />- 一句话概述<br /><br /><br /><b>验收标准</b><br />- 当…时，应该…"

• CLI 会自动在最外层包一层 <p>，所以正文内部用 <br /> 分段，不要拆成多个 <p>——否则变成 <p><p>…</p></p> 嵌套。
• 段落顺序固定为：需求背景 → 需求目标 → 优化方案 → 验收标准（目标在方案之前，便于人工按"为什么→要什么→怎么做"读）。
• 固定结构：<b>小标题</b><br />- 条目<br /><br />；「优化方案」段写成
  <b>优化方案</b><br />- 一句话概述<br /><br /><br />，即概述后留空白行供人工补充。
• 四个小标题固定为 需求背景 / 优化方案 / 需求目标 / 验收标准，不自创同义词、不擅自改名。
• 只用 <b> / <br /> 这类简单标签，不塞 style。

第 4 步：回传

需求 ID + 链接 https://www.tapd.cn/<workspace_id>/prong/stories/view/<story_id>，
外加状态、优先级、类别、分类四项。不要只说"创建成功"。

其他规则

• workspaceid 取 TAPD_WORKSPACE_IDS；用户要落到别的项目则显式传。
• 分类会随项目调整变化（用户可能刚在 TAPD 新建）。用户报分类名时，先
  tapd-cli story categories workspaceid=<id> 查真实 id，不要凭记忆填。
• 创建前先 tapd-cli story add --help / story update --help 确认参数，禁止猜参数。
• 命令失败说明原因，最多重试 2 次。

注意

• story 没有删除子命令，禁止创建"测试需求"来验证链路。首次验证直接用用户的真实需求，不要造数据污染项目。
• 万一建错了（字段错乱、重复建）：删不掉，只能改名成「【作废-勿用】…请在 TAPD 中删除」+ status=status_11（挂起），
  然后如实告诉用户这条脏数据的 ID 和链接，请他在 TAPD 界面删掉，不要假装没发生。
• 需求创建人 = 令牌所属账号。如果 creator 显示的不是使用者本人，提示令牌可能属于他人账号。
• 令牌等同于账号凭证：不写入 Git、不回显完整值、不在群里传播。

五、核实与学习外来需求

触发场景：用户贴来别人/其他 AI 写的需求、说"AI 生成可能有误 请核实"、或甩一个外部链接说"学习一下"。

核实清单（拿到外来内容逐项过）

按本文件第三节的规范对照，输出一张问题表，每条给判断 + 怎么改，不要笼统说"看起来还行"：

1. 模块词 —— 在不在 project-profile.md 的词表里。不在 → 给出词表里的正确模块。
2. 标题 —— 括号补注、动词重复、多余标点、/ & 拼接、句中空格，五项自查。
3. 结构 —— 是不是四段（需求背景 / 需求目标 / 优化方案 / 验收标准）。缺段指出。
4. 用户故事 —— 背景末尾有没有「作为 XX / 我希望 XX / 以此 XX」。没有就补。
5. 验收标准句式 —— 是不是「当用户…时，应该…」。陈述句要改写。
6. 验收标准内容 —— 挑出三类要删的：过程性描述（记录问题、联调通过、完成自测）、
   实现细节（读取配置、调用接口、上报数据）、超出 3-4 条的冗余项。
7. 有没有存量/回归项 —— 改动类需求缺这条必补。
8. 事实性风险 —— 涉及外部机型、品牌、产品名、时间节点的，要真的去搜一遍核实，
   不要默认外来内容写的是对的。例如核实到某机型已退市，就直接提出来问是否还要适配。

外链抓不到正文怎么办

豆包、飞书这类页面是登录态 + JS 异步渲染，直接抓取通常只能拿到标题。
抓不到就一句话说明 + 请用户把正文贴过来，不要反复换工具硬试、不要编造链接内容。

学习模式

用户说"学习一下风格/内容"时：

• 只提炼规律，不改用户已明确定下的规范。用户定的硬规范（四段结构、用户故事三句式、
  「当用户…时，应该…」句式、分类默认值）优先于外来样本；外来样本若与之冲突，按"不符合规范"报出来，
  而不是反过来改规范。
• 样本里确实更好的部分才写回本文件，例如：标题雷区清单、验收标准必带回归项、禁止过程性描述。
• 学完告诉用户改了哪几条规则，让他能复核。

六、依赖

• tapd-cli（TAPD 官方 OpenAPI CLI，v1.x）。安装方式见 references/onboarding.md。
• 令牌只需个人访问令牌，不需要 API 账号密码。
• Windows 下 bash 传中文参数正常；jq 表达式里避免 \n，用 @tsv 拼接更稳。