cawplan-ticket-create

CawPlan 工单创建

初始化

cawplan skill check

入口路由

开始操作前，先选择工作流：

输入	工作流
明确的单个工单请求（“为 X 创建工单”“针对 Y 提交一个 Bug”）	A — 单个工单
粘贴的 PRD、需求文档、Slack 讨论串或会议记录/纪要——无论是否明确要求“将其转换为工单”	B — 从文本中提取
“将 X 拆分/分解为子工单”、“拆分 sub-tickets”或任何要求在父工单下创建工单的请求（父工单可以是现有的 CawPlan 工单，也可以是先创建的工单）	C — 拆分为子工单

如果消息同时包含两种情况（明确的请求加上大量粘贴的上下文），则按 B 处理，让提取流程在源内容仅支持创建单个工单时只生成一个工单。如果消息还指定了父工单，或要求将提取的条目创建为子工单，则先运行 B 提取，再通过 C 提交这些条目。

工作流 A — 单个工单

使用用户提供的产品前，始终先解析该产品，即使用户同时提供了版本也不例外。可接受完全匹配的可访问名称（去除空格后不区分大小写）、唯一的简称/令牌前缀匹配，或用户明确确认的候选项。如果指定的产品不存在或存在歧义，则列出候选项并询问用户指的是哪个产品；不要为名称相似但无法唯一确定的产品创建工单。确认后，后续命令优先使用解析出的 product_id。

如果用户提供了产品但未提供版本：

1. 先解析产品：

   cawplan products list --search "<product name>"
   

   按照上述产品解析规则操作；如果产品尚未确认，不要列出版本或创建工单。
2. 列出已解析产品的版本：

   cawplan versions list <product_id> --page_size 100
   

3. 向用户展示进行中的版本（status/state 为 IN_PROGRESS、INPROGRESS，或显示文本为“In Progress”），并请用户选择一个。只有在用户无法提供版本时，才将“Backlog / 无版本”作为备用选项。

创建前先确认——即使用户明确要求创建单个工单，且已提供产品/版本，也要向用户说明已解析的产品、版本（或“Backlog”）、标题、类型、优先级和受派人（或 -），并取得明确同意后，再运行下方的创建命令。此 CLI 无法撤销工单创建（没有 tickets delete），因此即使请求听起来已经是最终决定，也不要跳过确认。

版本工单（指定版本）：

cawplan tickets create-version \
  --product "<product name>" \
  --ver "<version name>" \
  --description "<ticket title>" \
  --remarks "<html description body>" \
  --type FEATURE \
  --priority MEDIUM \
  --reporter <your-email> \
  --assignee <email>

Backlog 工单（仅在用户无法提供版本或明确要求使用 backlog 时作为备用选项）：

cawplan tickets create-backlog \
  --product "<product name>" \
  --description "<ticket title>" \
  --remarks "<html description body>" \
  --type FEATURE \
  --priority MEDIUM \
  --reporter <your-email>

获取你自己的邮箱以用于 --reporter：

cawplan auth status   # shows authenticated email

创建工单前必须先通过 OAuth 登录。

工作流 B — 从粘贴的文本中提取工单

适用于直接粘贴到对话中的 PRD、Slack 讨论串和会议记录——纯粘贴内容，不涉及上传或 Slack/会议集成。

1. 确定目标范围——单个产品，还是一个 Team 下按平台划分的多个产品：
   • 单个产品（常见情况）：按照 Workflow A 的相同方式确定产品，然后为其确定一个版本（列出进行中的版本，让用户选择，或确认使用待办事项）。如果文本中提到了版本，就使用该版本；否则询问用户。除非某个具体事项明确指定了不同的产品或版本，否则将此产品和版本应用于提取出的每个候选事项。
   • 一个 Team，平台分属不同产品（例如：“添加到 VN Team，FE/BE/iOS/Android 分别是不同的产品”）——仅搜索产品无法确定目标，因为目标并非单个产品：
     1. 将 Team 名称解析为 product_line_id（分页并在客户端按名称匹配，方式与 cawplan-product-report 的 Team 工作流相同）。必须满足以下任一条件：名称完全匹配（去除首尾空格后不区分大小写）、唯一的简称／令牌前缀匹配，或用户明确确认列出的候选项。如果找不到所述 Team，或匹配结果有歧义，请列出候选项并询问用户指的是哪个 Team；不要列出产品，也不要推测最接近的 Team：

        cawplan product-lines list --page_size 100
        

     2. 列出该 Team 的产品：

        cawplan products list --product_line_id <product_line_id>
        

     3. 请用户将提取过程中会出现的每个平台（FE/BE/iOS/Android，以及 QA）对应到列出的某个产品。不要仅凭产品名称猜测对应关系——例如，“VN Cloud”或“VN Roadmap”显然无法判断是 BE 还是 FE，猜错可能会让实际工作被悄悄归入错误的产品。如果用户没有明确指定 QA 对应的产品，请询问 QA 工单应归到哪里，不要自行假设——Team 通常没有专门的 QA 产品，因此 QA 工作一般会并入其他已映射的某个产品，或者跳过；无法猜出具体是哪种情况。
     4. 立即记录步骤 2 列表中每个已映射产品的 product_id，并与其名称一同保存——创建时不要再通过 products list --search 按名称重新解析。已通过实际情况验证：此系统中的一个真实产品名称含有不一致的双空格（“VN: iOS”），普通名称搜索无法匹配，导致 tickets create-version --product "<name>" 直接失败。步骤 2 的列表已包含每个候选产品准确的 product_id；请在后续步骤 4-5 中沿用该 ID，并在创建时传入 --product <product_id>，不要传显示名称，以免产品名称中的无关录入问题导致工单创建失败。
     5. 对最终映射中涉及的每个不同产品，按照 Workflow A 的相同方式为其确定一个版本（列出进行中的版本，让用户选择，或确认使用待办事项）——版本属于产品，而非 Team，因此只需为实际使用的每个产品确定一次，而不是为整批事项统一确定一次。
     6. 将此平台→产品／版本映射带入步骤 2：每个候选事项的产品／版本应根据其所属平台的映射确定，而不是使用所有事项共用的单个产品。
2. 仅从源文本中提取候选工单：
   • PRD／需求文档 → 对文档实际提到的每个目标平台／组件分别创建一个工单（例如 FE/BE/iOS/Android/QA）。如果文档描述的是一个完整连贯的工作，且没有按平台拆分，则创建单个工单——不要自行编造拆分。在 Team 模式（上一步）中，为每个候选事项标注其平台对应的产品／版本。
   • Slack 线程／会议记录 → 每个不同的行动项对应一个工单。符合条件的事项包括：(a) 明确、无条件地指定负责人（“X 会做 Y”、“我来处理”，或带有具体后续工作的决策）；或 (b) 具体描述的 Bug／问题（包含明确的症状、触发条件或复现条件），即使没有负责人也符合。带有条件或面向未来的主动提议（“弄清根因后我可以帮忙”）不会指定负责人，但不影响其他具体 Bug 成为候选事项。纯闲聊——没有决策的问题、“只是好奇”的旁枝话题，或某人明确表示不负责且没有后续行动——不属于行动项，即使提到了已知的问题领域也不例外。
   • 如果线程撤回或更正了之前的陈述（“其实不对，我觉得是 X，不是 Y”），只采用更正后的最终版本。不要根据发言者已撤回的说法创建工单。
   • 绝不要编造源文本中没有的工单、负责人或细节。如果源文本过于含糊，无法整理出清晰的事项，请先询问澄清问题，而不是自行猜测如何拆分。
3. 将每个候选事项映射到工单字段：
   • description（标题）：用自己的话简短概括，不要直接复制粘贴记录中的句子。
   • remarks（正文）：将相关摘录／上下文转换为 HTML（见规则）。
   • type：默认使用 FEATURE，仅在事项明确属于 Bug／缺陷时使用 BUGFIX。
   • priority：默认使用 MEDIUM；如果源文本表明紧急程度较高，则提高为 HIGH／CRITICAL；如果源文本明确表示不紧急或可以等待，则降低为 LOW。
   • assignee：仅在存在明确、无条件的承诺时才设置（见上文），并且仅当 cawplan users query --keyword "<name>" 能将姓名解析为唯一人员时才设置；如果没有明确承诺，或查询返回零个或多个匹配结果，则留空（按照产品／版本的相同消歧规则向用户询问）。
   • 平台标签：仅当用户要求按平台拆分且存在匹配标签时才添加——使用 cawplan labels list --product_id <product_id> --search "<platform>" 检查（在 Team 模式中，使用每个候选事项各自映射的 product_id，而非共用一个 ID）。不要编造标签名称；如果没有匹配项，请在标题／备注中提及平台，而不要添加标签。在 Team 模式中，候选事项归属的产品已经体现了平台；标签只是锦上添花，不能替代这种路由映射。
4. 创建前先预览。 多工单提取属于推断，并非明确要求——始终展示候选事项列表并获得用户确认后，才运行任何创建命令，即使用户的消息已经说了“为这些事项创建工单”也不例外。请确认提取出的列表，而不是原始要求。无论源文本使用何种语言，都应使用用户正在使用的语言展示列表。
   • 单产品模式：标题 | 类型 | 优先级 | 负责人 | 平台；不适用的字段用 - 表示。
   • Team 模式：增加 Product 列（如果映射产品间的版本不同，则还需增加 Version 列），让用户在创建任何工单前核对平台→产品的路由——这是最容易在无提示的情况下出错的映射，因此不要在预览中省略。
5. 用户确认后，按照 Workflow A 中相同的 tickets create-version／tickets create-backlog 命令创建每个工单；每个候选事项分别调用一次——在 Team 模式中，每次调用都使用该候选事项对应的 --product／--ver，而不是一组共用的参数。

工作流 C — 拆分为子工单

子工单是使用 --parent_id <parent> 创建的普通工单。--parent_id 接受父工单的唯一 ID 或显示 ID（例如 CWP-14556）；CLI 会解析显示 ID。

1. 解析父工单。
   • 已有父工单（URL、显示 ID 或唯一 ID）：查找该工单，并保留其 unique_id、display_id、product_id、version_id、description（标题）和 remarks（正文）：

     cawplan tickets search --display_ids CWP-14556
     

     如果没有匹配项，请说明并停止；不要猜测其他前缀。
   • 新建父工单：解析产品/版本，并完全按照工作流 A 的方式创建（同样需要先确认再创建），然后使用返回的工单作为父工单。
2. 根据用户提供的内容推导子工单——可以是明确的列表、父工单的 remarks 或粘贴的文本（应用工作流 B 的提取规则）。每个可独立交付的部分对应一个子工单；不要创建来源内容不支持的部分，如果拆分方式不明确，则提出一个澄清问题。
3. **范围：**默认情况下，每个子工单都归入父工单的产品和版本。只有用户提出要求时才使用不同的产品/版本（例如工作流 B 中 Team 模式下的平台路由）。如果子工单的产品不属于父工单所在的产品线，服务端会拒绝该子工单；父工单链最多为 5 层。
4. 创建前预览——始终执行，即使用户已经说“创建”：显示父工单（显示 ID + 标题），并列出一张包含 Title | Type | Priority | Assignee | Product/Version 的表格（与父工单相同时用 - 表示），然后等待确认。
5. 创建：每个子工单调用一次，并附上父工单的 ID：

   cawplan tickets create-version \
     --product <parent product_id> \
     --ver <parent version_id> \
     --parent_id <parent unique_id or display_id> \
     --description "<sub-ticket title>" \
     --remarks "<html body>" \
     --reporter <your-email>
   

   如果父工单属于待办（is_backlog: true），则改用 tickets create-backlog --product <product_id> --parent_id ...。

规则

• 默认类型为 FEATURE；只有用户提到 bug、defect 或 issue 时才使用 BUGFIX。
• 未指定时，默认优先级为 MEDIUM。
• 标题和描述/正文须分开处理：
  • CLI 的 --description 仅用于工单标题/摘要。
  • CLI 的 --remarks 用于页面描述/正文。它支持 HTML，也是用户通常所说的“description”字段。
  • 不要将长正文、验收标准、PRD 文本或多行描述放入 --description。
• 将纯文本正文转换为精简 HTML 后再传入 --remarks。不要传入仅用换行分隔的原始文本，因为它可能会显示成一整行混杂内容。根据需要使用 <p>、<br>、<ul> 和 <li>。
• 如果用户提供多行请求（工作流 A），将第一条简短内容或精炼摘要用作标题，其余细节放入 HTML --remarks。如果无法安全地识别标题，则提出一个澄清问题。
• 如果用户未指定版本，则解析产品、列出进行中的版本，并在创建工单前请用户选择一个版本。
• 默认不要创建待办工单。仅当用户明确要求创建待办/不指定版本，或在用户确认无法提供版本后，才使用 create-backlog。
• 创建待办工单时，告知用户：“此工单已创建为待办事项，未分配给任何版本。”
• 不要猜测工单标题/摘要。如果缺少标题，则提出一个澄清问题。
• 如果 CLI 在产品、版本或指派对象查询中报告多个匹配项，请用户消除歧义。

确认

创建后，报告：

• 工单显示 ID 和唯一 ID。

• 产品 / 版本范围（或“Backlog”）。

• 类型、优先级、状态。

• 受理人；如果没有则写 -。

• 标题（来自 CLI --description，较长时去除多余内容或截断）。

• 描述 / 正文（来自 CLI --remarks，去除 HTML 并在较长时截断）；如果没有则写 -。

• 子工单的父工单（显示 ID + 标题）；如果没有则写 -。

对于工作流 C，先报告父工单，然后每个已创建的子工单各占一行。

对于工作流 B，报告完整列表（每个已创建的工单各占一行），并列出用户在预览期间放弃或编辑的候选项。在团队模式下，按产品分组报告（每个工单自己的“产品 / 版本范围”行已包含此信息，但分组后更便于核对平台→产品的路由是否与用户在预览中确认的一致）。

参考资料

• references/CAWPLAN_OPEN_API.md