pp-youtrack-state

pp-youtrack-state — YouTrack 状态流转

适用范围

仅负责 YouTrack issue 的 workflow 状态流转(待办 → 进行中 → 自测 → 完成 这类)。一件事就干这一件,不管评论、不管创建 issue、不管 assignee、不管搜索。

其他 YouTrack 操作属于独立的 skill(例如未来的 pp-youtrack-comment、pp-youtrack-search 等),本 skill 不跨职责。

不适用于 Atlassian Jira 任务(用 common-skills:jira-cli skill)。

环境前提

• mcp__pp-youtrack__* 系列 MCP 工具已加载(通过 /plugin 启用 pp-youtrack MCP)
• 调用方持有合法的 YouTrack issue id(例如 PP-123、SHOWCASE-456,具体格式取决于目标 project)

状态流转(核心功能)

基本用法(严格按 4 步走,任何一步省略都会吃静默失败)

mcp__pp-youtrack__update_issue 没有顶层 state 参数。state 是 YouTrack 的 custom field,必须通过 customFields 对象传入,而且值必须是该 project schema 里的 enum 原文(可能是英文 In Progress,即使你传的目标状态是中文 进行中)。完整流程:

Step A: 从 schema 拿 State 的 enum 列表

schema = mcp__pp-youtrack__get_issue_fields_schema(project_key)

在 schema 输出里找 $type: StateProjectCustomField(或类似的 state-type custom field),读出两样东西:

1. 字段 key 名(通常是 State,但个别 project 会用 状态 / Workflow State 之类,不要写死)
2. enum 值列表——这个 project 下 State 允许的所有原文值。例如 ["Submitted", "Open", "In Progress", "Review", "Self Test", "Done"]

把 key 名和 enum 列表缓存到本会话,同一 project 复用,不重复 get schema。

Step B: 把用户给的目标状态名映射到 enum 原文

caller 传过来的目标状态很可能是本 skill 已知列表里的本地化名(中文 进行中、自测、完成)。直接这样传进 update_issue 大概率打不中,因为 YouTrack 后台存的是 schema enum 原文(英文 In Progress、Self Test、Done)。

映射步骤:

1. 用本 skill 的"已知生命周期顺序表"(下面规则 1 里那张)把 caller 给的名字归到某个生命周期阶段(例如 进行中 → "In Progress 阶段")
2. 在 Step A 拿到的 enum 列表里找同一阶段的 enum 原文(例如 In Progress)
3. 找到 → 用这个 enum 原文作为后面 update_issue 的 value
4. 两个名字都不在已知表里(enum 原文也是自定义的,例如 Hotfix Pending)→ 走规则 2.5 的 AskUserQuestion fallback,让用户告诉你 enum 列表里哪一项对应目标生命周期阶段,绝不猜

Step C: 调 update_issue(正确写法 vs 错误写法)

正确写法:

result = mcp__pp-youtrack__update_issue(
  issue_id = "<ISSUE-ID>",
  customFields = { "<State 的 key 名>": "<映射后的 enum 原文>" }
)

错误写法(会静默失败——这是踩过的坑):

# ❌ MCP 会忽略未知顶层字段 `state` 并返回成功,看起来流转成功但 issue 实际没动
mcp__pp-youtrack__update_issue(
  issue_id = "<ISSUE-ID>",
  state = "<target-state-name>"
)

硬规则:所有 state 流转一律通过 customFields 传,绝对不要写成顶层 state=。即使你觉得"试试看"也不行——MCP 的成功返回值在这种情况下是假阳性,没有任何报错。

Step D: 检查 failedToUpdateFields,空数组才算真成功

update_issue 的返回值里有一个 failedToUpdateFields 数组。这是唯一可靠的成功判定信号:

• failedToUpdateFields 是空数组 [] → 真成功,流转生效
• failedToUpdateFields 非空(列出了某几个字段) → 失败,对应字段没更新。不要当成功。常见原因:enum 值拼错、key 名拼错、workflow 禁止该 transition、权限不足。按规则 3 的"流转失败"流程走 AskUserQuestion,把 failedToUpdateFields 原文贴给用户

绝不仅凭 update_issue "没抛错" 就当真成功——必须读 failedToUpdateFields。这是本 skill 对抗静默假阳性的最后一道闸。

已知状态名(按生命周期顺序)

下面是 pp-youtrack 常见的 state 名,以 project 实际 workflow 为准:

阶段	状态名	含义
入口	Open / 提交	新创建,未分配
—	待办 / Backlog	在队列里等待处理
—	进行中	正在设计/分析/实施
—	Review / 待评审	等待 review
—	自测	开发完成,进入自测阶段
—	测试中 / QA	QA 验证中
终态	完成 / Done	闭环

如果你不确定目标 project 用的是哪个名字,先 mcp__pp-youtrack__get_issue(issue_id) 拿当前 issue 的 state 值,观察命名风格,再决定传什么。

调用方契约(给 caller 的硬规则)

1. 只推进,不回退

默认不允许把 issue 从后面的状态往前拉(例如 自测 → 进行中)。原因:回退状态通常意味着"发现 bug 重新开工",这是人为决策,不应该由自动流程决定。

流转前检查:先 get_issue 看当前状态,判断目标状态是不是生命周期顺序上的向前移动。

判定方式:用下面这张已知生命周期顺序表(数字越大越靠后,只对已知名字有效):

阶段	已知 state 名	序号
入口	Open / 提交 / Submitted	0
—	待办 / Backlog / To Do	1
—	进行中 / In Progress	2
—	Review / 待评审 / In Review	3
—	自测 / Self Test	4
—	测试中 / QA / In Testing	5
终态	完成 / Done / Closed	6

例子:

• 当前 待办(1) → 目标 进行中(2):✅ 正常前进
• 当前 进行中(2) → 目标 自测(4):✅ 正常前进
• 当前 自测(4) → 目标 进行中(2):❌ 回退,跳过(走规则 2)
• 当前 完成(6) → 目标任意非完成:❌ 跳过,不回退已关闭的 issue

2. 已在目标状态或更后 → 跳过 + 提示

如果当前状态已经等于目标状态,或者在生命周期上已经超过目标状态,不报错也不流转,只在对话里输出一行提示:

YouTrack issue <ID> 当前状态 "<current>" 已经在或超过目标状态 "<target>",跳过流转。

这样 caller 能知道"skill 已经识别了,没做多余动作",而不是沉默跳过。

2.5. 未知状态名 → 立即 AskUserQuestion(关键 fallback)

如果从 get_issue 拿到的当前 state 名或 caller 传入的目标 state 名有任意一个不在上面的已知生命周期表内(例如 project 用了自定义 workflow Code Review / UAT / Hotfix Pending / Blocked / Cancelled 等),你没有能力判断它的生命周期序号,绝对不能猜。立即:

1. 用 AskUserQuestion 把以下信息告诉用户:
   • issue id 和当前状态名
   • 目标状态名
   • 不在已知表内的那个名字是哪一个(或两个都不在)
2. 让用户选:
   • 告诉我顺序关系(用户回答"自定义状态在 进行中 之后、自测 之前"这种)然后基于用户的判断决定推进/跳过/回退
   • 直接推进,不做顺序检查(用户明确放弃保护)→ 跳到规则 3 直接 update_issue
   • 跳过本次流转(用户决定不动 state)
3. 绝不默认按"未知 = 推进"或"未知 = 跳过"处理——两种行为都可能导致数据错乱

这条规则比规则 1 和规则 2 的优先级更高:在跑顺序判断之前必须先确认两端的 state 名都在已知表内。

如果未来这个 project 用一组新的 state 名,正确做法是把它们补进上面的表(改本 skill),而不是在 caller 那边硬编绕过本 skill。

3. 流转失败 → 立即 AskUserQuestion

任何 update_issue 调用失败(API 报错、状态名不存在、权限不足、project workflow 禁止该 transition 等)都不能绕过。立即:

1. 把 MCP 返回的完整错误消息贴出来
2. 用 AskUserQuestion 问用户选择:
   • 手动流转:用户自行到 YouTrack 网页流转,然后告诉你继续
   • 重试:用户确认问题已修复后重试
   • 跳过流转继续后续流程:用户明确接受 issue 状态不变
3. 绝不沉默跳过或自动重试——状态不一致是团队协作的风险

4. 调用格式(给 caller 参考)

caller 应该以这样的自然语言交代意图:

调用 pp-youtrack-state skill,把 <ISSUE-ID> 流转到 <target-state> 状态。

skill 内部按严格顺序负责(任何一步省略都可能踩假阳性):

1. (仅每个 project 首次) get_issue_fields_schema(project_key) 拿到 State 字段的 key 名 + enum 值列表,缓存到本会话
2. get_issue(issue_id) 读当前状态原文
3. 按已知生命周期表判断目标状态是否向前移动(未知名字 → 立即 AskUserQuestion,见规则 2.5)
4. 把 caller 给的目标状态名(可能是中文)映射到 schema enum 原文(可能是英文)——见上面 Step B。映射不出来 → AskUserQuestion,不要猜
5. 调 update_issue(issue_id, customFields={ "<key>": "<enum 原文>" })——永远走 customFields,不写顶层 state=
6. 读返回值的 failedToUpdateFields,空数组才算真成功;非空 → AskUserQuestion 把原文贴给用户
7. 任一步报错或静默失败 → 规则 3 的 AskUserQuestion,不静默重试

典型 caller

• obsidian-design command:在开始设计/分析之前把 YouTrack issue 从 待办 流转到 进行中
• code-execute command:在 Opus review 通过后把 YouTrack issue 从 进行中 流转到 自测
• 未来的 youtrack-close command:类似 jira-close,把 issue 推到最终完成状态

什么时候不要用本 skill

• 目标 issue 是 Atlassian Jira(用 common-skills:jira-cli skill)
• 需要做 issue 内容的拉取/创建/评论等非状态操作(直接用 mcp__pp-youtrack__* 对应工具;本 skill 只管状态)
• 需要批量流转多个 issue(本 skill 目前按单 issue 设计,批量操作要 caller 自己循环调用)