cawplan-plan-track

CawPlan 计划跟踪

初始化

cawplan skill check

重要的工单查询规则

cawplan tickets search 必须提供 --time_range 或 --start_date+--end_date，除非是使用 --unique_ids/--display_ids/--parent_ids 进行精确查询。版本跟踪需要包含所有工单，无论其创建时间，因此此技能中的所有版本范围查询都使用 --start_date 2000-01-01 --end_date <today>，并分页查询至 total。在托管 Agent 中，每一页都需要单独调用工具（不能使用 shell 循环或 jq），且每轮大约有 16 次调用；请使用 --page_size 100。后续查询沿用之前的产品/版本范围（如果上下文中可见则复用 ID，否则重新解析名称），绝不能将名称作为 ID 传入，并如实说明部分结果——参见 references/QUERY_RESILIENCE.md。

标签是分类的唯一可信来源。不要使用旧版工单 type、--type 搜索选项或返回的 .type 来判断工单属于 bug 还是功能。对于特定类别的查询，应先列出已确认产品可见的标签，再仅从该目录中选择，并使用 --label_ids 筛选。

响应中的 description 是规范的工单标题。请原样显示：不要翻译、总结、缩短、规范标点或空格、删除前缀或省略括号内文本。允许使用 Markdown 转义，但必须保留标题的可见内容；任何摘要都应放在单独的字段中。

工作流

必需的产品访问验证

在查询任何产品、版本、发布或工单范围的数据之前，必须通过 products list 验证调用者是否可以查看该产品。即使用户直接提供了 product_id，或该 ID 来自之前的对话，也必须执行此验证——不要将已知 ID 视为有权访问的证明。

cawplan products list --search <product-name-word-or-product_id>

将搜索文本作为一个不带引号的词传入（--search CawPlan，绝不要写成 --search "CawPlan"）：托管 Agent 会拒绝带引号的值。对于名称中包含空格的产品，搜索一个有辨识度的词，并在结果中匹配完整名称。

只有当响应包含一个符合预期的产品（product_id / unique_id）时才继续。用户提供了产品名称时，需精确匹配该名称（不区分大小写，并在去除首尾空格后比较），或者接受唯一的简称/令牌前缀匹配；名称相似但不唯一的结果只能视为候选项，绝不能自动替换。如果没有唯一且可访问的产品匹配，不要调用 versions、tickets、product-lines statuses 或任何其他产品范围的端点。如果返回了候选项，请列出其名称并询问用户确认要查找哪个产品。如果没有返回候选项，请说明所述产品可能不存在，或调用者无权访问；不要报告工单数量，也不要暗示其工单列表为空。只有在 API 明确报告访问被拒时，才返回 NO_PERMISSION。

NO_PERMISSION: You do not have access to product "CawCut Cloud".

绝不能将不可用的产品转换为空结果，例如 Open Tickets: 0；只有通过此访问验证后，空工单列表才有意义。

1. 将产品名称解析为 product_id，并完成必需的产品访问验证：

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

如果没有精确匹配或唯一的简称匹配，请列出所有候选项（名称 + product_id），并询问用户要查找哪个产品；不要猜测。如果查询没有返回候选项，请说明：未找到可访问的 product “<name>”：该 product 可能不存在，或你当前没有访问权限，因此无法查询其 tickets。如果存在多个匹配项，请让用户选择。保留已确认记录中的 product_line_id（或嵌套字段 product_line.unique_id——请检查响应中的实际字段名）。

2. 将版本名称解析为 version_id（如果已知则跳过）：

   cawplan versions list <product_id>
   

3. 一次调用获取进度和发布历史：

   cawplan versions track <product_id> <version_id>
   

   返回：

   • detail.data.progress — complete_percent、status_counts（COMPLETE / UNSTARTED / STARTED / TESTING / CANCELED）
   • detail.data.risk — LOW / MEDIUM / HIGH
   • detail.data.risk_reason
   • detail.data.extra.target_release — 渠道名称和 release_at 时间戳
   • detail.data.status — NOT_STARTED / INPROGRESS / RELEASED
   • release.data — 发布历史事件（状态变更、风险变更）

4. 解析产品线的状态键（以下每个步骤都需要，普通进度检查除外——在第 5 步之前运行一次即可）：

   cawplan product-lines statuses <product_line_id>
   

   返回每个状态的 key 及其 category（UNSTARTED / STARTED / TESTING / COMPLETE / CANCELED）。为以下步骤中的客户端检查构建 key→category 映射。

4a. 解析分类标签（将运行第 6 步或第 7 步时）：

cawplan labels list --product_id <product_id> --page_size 200 --page_num 1

分页至 total。仅选择此产品范围目录返回的标签；绝不要臆造名称或 ID，也不要回退到旧版 type。

• Bug 意图：behavior=BUGFIX 是强匹配信号。名称中出现 bug、bugs、bugfix、bug fix、defect、defects、regression 和 regressions 是强信号。将 fix、fixing、hotfix、issue、crash、incident 和 blocker 视为取决于上下文；仅当目录和用户意图明确表明它们是分类标签时才选择。
• 功能意图：behavior=FEATURE 是强匹配信号。与目录含义一致的精确语义名称（例如 feature 或 enhancement）可作为候选项。
• 匹配时统一大小写、空白、连字符和下划线，但保留返回的确切 ID/名称。如果多个标签都能安全匹配，则全部使用（label_ids 内为 OR）。如果没有安全匹配项，则展示候选项并询问；不要使用 type。

5. 通过一个共享的完整详情数据集获取此版本的所有工单（仅当进行普通进度检查且未要求工单级详情时才跳过）：

   cawplan tickets search --version_ids <version_id> --start_date 2000-01-01 --end_date <today> --page_size 100 --page_num 1
   

   当 page_num * page_size < total 时继续分页。搜索会返回此处所需的完整工单结构，包括 description、labels、status_display、priority、assignees、updated_at、version_id 和 parent_id。第 5a 步和第 8-13 步会筛选此共享数据集；第 6-7 步则特意执行带标签筛选的搜索，以便由 API 强制执行分类选择。

   此集合包含子议题（已设置 parent_id），以及顶层工单。以下所有列表（第 6-13 步）都要保留子议题——CRITICAL 子议题 Bug 仍是真实存在的工单，具有独立的标签、优先级和负责人，需要让人看到。但如果你报告的工单数量（例如“31 个未开始工单”）看起来比同一版本的 versions get 所显示的 progress.status_counts 更多，也不必惊讶——该字段只统计顶层工单，因此这两个数字统计的并非同一集合，不应将它们呈现为必须相符的数字。

5a. 开放工单（用户询问当前版本的 Open Tickets 时）：从第 5 步按版本筛选的集合中，纳入所有状态键映射到非 COMPLETE 或 CANCELED 类别的工单。UNSTARTED、STARTED 和 TESTING 都属于开放类别。 不要使用硬编码的状态键白名单，也不要根据键名/显示名称推断终止状态： 类别为 TESTING 的自定义状态 Testing 属于开放工单，必须返回。 按解析出的状态显示名称/类别对结果分组。

6. 未解决的关键 Bug（仅当用户询问发布风险/阻塞项时——普通进度检查时跳过）：CawPlan 工单没有单独的“Blocker”优先级；将 priority=CRITICAL 视为“Blocker”级别。使用第 4a 步选出的 Bug 标签 ID：

   cawplan tickets search --version_ids <version_id> --label_ids <bug-label-ids> --priority CRITICAL --start_date 2000-01-01 --end_date <today> --excluded_status_categories COMPLETE,CANCELED --page_size 100 --page_num 1
   

   分页至 total，然后单独排除所有内联 status_display.category 为 COMPLETE 或 CANCELED 的结果。

7. 尚未进入 QA 测试的功能（与步骤 6 使用相同的触发条件）：使用步骤 4a 中选定的功能标签 ID：

   cawplan tickets search --version_ids <version_id> --label_ids <feature-label-ids> --status_categories UNSTARTED,STARTED --start_date 2000-01-01 --end_date <today> --page_size 100 --page_num 1
   

   将页面设为 total，然后独立筛选出行内 status_display.category 为 UNSTARTED 或 STARTED 的结果。

8. 可进行 QA / QA 测试工单列表（仅在用户询问时——例如“哪些可以进行 QA”“哪些正在进行 QA 测试”）：从步骤 5 的集合中筛选状态类别为 TESTING 的工单，不受标签限制。步骤 10 和 12 会复用这个确切列表——不要为此再次筛选步骤 5。

9. 建议取消范围（仅在用户明确询问要取消哪些范围或如何降低延迟风险时——切勿主动提出）：

   • 候选范围：步骤 5 中经过版本筛选的集合。不要建议此范围之外的工单，也不要猜测未返回的优先级；如果确实缺少候选工单的优先级，则将其排除，不要臆造。
   • 仅建议取消状态类别为 UNSTARTED（尚未开始）的工单——绝不要建议取消 STARTED、TESTING 或 COMPLETE 状态的工作。
   • 建议顺序为先 LOW 优先级，再 MEDIUM；绝不要建议取消 HIGH 或 CRITICAL 优先级的工单。
   • 每条建议都必须以 risk_reason 和步骤 5 中的实际工单列表为依据——不要臆造 risk_reason 中未提及的理由。

10. 哪些因素阻碍了 QA 测试（仅在用户询问时）：检查步骤 8 中每个可进行 QA／状态为 TESTING 的工单的阻塞关系：

    cawplan tickets relate list <product_id> <version_id> <ticket_id>
    

    对于每条 relation_type=BLOCKED_BY 关系，如果被阻塞的工单与当前工单属于同一版本，则从步骤 5 的数据集中查询其状态；否则，使用 cawplan tickets get <product_id> <version_id_of_that_ticket> <ticket_id> 查询——不要仅仅因为该工单不在目标版本中，就假定它已解决。仅报告状态类别（步骤 4 的映射）不是 COMPLETE／CANCELED 的阻塞项。每个测试中工单都需要调用一次 relate list；如果工单很多，请告知用户你只在检查测试中的工单，不要默默抽样。

11. 受派人负载过重（仅在用户询问时——“有人负载过重吗”“谁有太多高优先级问题”）：从步骤 5 的集合中筛选 priority 为 CRITICAL／HIGH 且状态类别不是 COMPLETE／CANCELED 的工单。工单可以有多个 assignees；对每位受派人各计一次，而不是每张工单总共只计一次。如果工单完全没有受派人，不要将其排除——单独报告为“未分配”；无人负责的未关闭高优先级工单值得单独指出。按受派人分组，并按数量降序排列。如果最高数量有两名或更多受派人并列，则将他们全部列为并列第一——不要随意挑选一人。不要臆造“负载过重”的判定阈值（例如“3 张以上就算太多”）——团队的容量标准并非你所知；请报告每位受派人的实际数量，并指出排名第一的人员（如有并列则全部列出），作为“谁”的最可能答案。 如果本次对话中尚未获取步骤 5 的集合，且只需要数量，则通过一次服务器端调用获取，而不是分页：cawplan tickets stats --version_ids <version_id> --priority CRITICAL,HIGH --excluded_status_categories COMPLETE,CANCELED --start_date 2000-01-01 --end_date <today> --group_by assignee（每张工单对每位受派人各计一次；值为 null 的分组为未分配项）。如果该命令不可用，则回退到步骤 5（references/QUERY_RESILIENCE.md）。

12. 每位 QA 的待验证数量（仅在用户询问“每位 QA 还有多少项需要验证”时）：复用步骤 8 中的待 QA/QA 测试列表。按工单的 QA 负责人 qa_assignees 分组（若只返回 qa_assignee，则使用该字段），不要按 assignees 分组；多位 QA 负责的工单，每位 QA 都计一次，并分别报告人数。如果列表中的工单没有 QA 负责人，应单独报告为“未分配 QA”，不要将其忽略，也不要默默归到无人名下。每人的数量应与其名下列出的工单数一致，各分组数量之和应等于列表数量（多 QA 工单会额外计数）。

13. 超过 N 天未更新的工单（仅在用户询问“哪些工单在 N 天内没有动过”时）：如果用户没有提供 N，应询问其所说的“很久”具体是多久，不要自行选取默认值——对于多长时间算作过期，并没有通用标准。确定 N 后：从步骤 5 的集合中排除 COMPLETE/CANCELED 类别的工单（已解决的工单即使此后未更新，也不算“未修复”），计算其余工单的 (now - updated_at) 天数，并按从旧到新的顺序列出超过 N 天的工单。

输出

按照 references/QUERY_RESILIENCE.md §5 的规则撰写答复：不要包含 CLI 命令、内部字段名或推理文本。

仅报告用户实际询问的内容（对于简单的“跟踪此版本”请求，不要执行步骤 4–13）：

• 版本名称、状态和风险等级（如果为 MEDIUM 或 HIGH，需说明原因）。
• 完成度：X% complete (N done / M total)（将 X 四舍五入为整数）。
• 各渠道的目标发布时间（将 release_at Unix 时间戳转换为易读日期）。
• 如果执行了步骤 5a：未完成工单——显示 ID、标签、优先级、负责人和原样的 description 标题， 按解析后的状态分组。包括所有非终态类别，包含 TESTING。
• 阻塞项：任何优先级为 CRITICAL 或 HIGH 的未完成工单。
• 如果执行了步骤 6/7：尚未解决的严重 Bug 和尚未进入 QA 测试的功能，分别列出（显示 ID、标题、负责人）。
• 如果执行了步骤 8：待 QA / QA 测试列表——显示 ID、标签、原样的 description 标题、负责人。
• 如果执行了步骤 9：按排名列出建议取消范围的事项，每项附上对应工单及其符合条件的单行原因（优先级 + 状态类别）——不要重复陈述 risk_reason。
• 如果执行了步骤 10：列出正在测试但受阻的工单、阻塞原因及阻塞项自身的状态；或者明确说明没有正在测试的工单存在未解决的阻塞项。
• 如果执行了步骤 11：按高优先级未完成工单数量对负责人排序，数量最多者在前（并列最高者一起列出）——不要给出“负荷过重”的判断，只列出排名和数量；如果有符合条件的工单未分配负责人，也要列出“未分配”数量。
• 如果执行了步骤 12：按 QA 负责人报告待验证数量；如果有待 QA 工单没有 QA 负责人，也要列出“未分配 QA”分组。
• 如果执行了步骤 13：列出超过 N 天的工单（显示 ID、标题、负责人、距上次更新的天数），按从旧到新的顺序排列；或者明确说明没有超过 N 天的工单。

如果所有工单都已完成，请明确说明。

参考资料

• references/CAWPLAN_OPEN_API.md
• references/QUERY_RESILIENCE.md