jira-communication

Jira 沟通

通过 uv run 运行 CLI 脚本，均支持 --help、--json、--quiet 和 --debug。

自动触发

遇到 Jira URL 或问题键（PROJ-123）时，按意图选择工具——每项只需调用一次：

意图	工具
分诊 / 处理工单	jira-issue.py work KEY
开始 QA 审查	jira-issue.py qa KEY
QA 失败后续处理	jira-issue.py qa-fail KEY
仅查询字段	jira-issue.py get KEY --fields ...
更改状态	jira-issue.py act KEY → jira-transition.py do
审计 / 查找同类工单 /“我是在审查自己的工作吗？”	jira-qa-gather.py KEY

遇到身份验证问题 → jira-setup.py。**反模式：**使用 get + comment list——请使用相应的动词。

**work 会标记尚未由你接手的工单：**如果工单尚未分配给你，或其状态表明无人处理（To Do 类别、QA 等审查状态，或已解决），stderr 会显示 !! CLAIM KEY 提示（--json 中为 claim），其中列出相关命令——jira-issue.py update KEY --assignee me，然后运行 jira-transition.py list KEY 中的开始或重新打开转换。在发表第一条评论、进行测量或编辑前，先运行这些命令。如果工单既不属于你、也不处于处理中状态，jira-comment.py add 会在发布前警告一次；但仍会发布。

脚本

位于 ${CLAUDE_SKILL_DIR}/scripts/{core,workflow,utility}/。

核心：jira-issue.py、jira-search.py、jira-worklog.py、jira-attachment.py、jira-setup.py、jira-validate.py 工作流：jira-create.py、jira-transition.py、jira-comment.py、jira-move.py、jira-sprint.py、jira-board.py、jira-version.py、tempo-account.py 实用工具：jira-user.py、jira-fields.py、jira-link.py、jira-weblink.py、jira-worklog-query.py、jira-watchers.py、jira-qa-gather.py

执行方式

直接运行。脚本会报告 ✓/✗。破坏性操作使用 --dry-run。全局标志放在子命令之前：jira-issue.py --json get PROJ-123。

每次写入后都会显示工单状态

成功写入后，以下命令会将工单状态打印到 stderr：jira-comment.py add/edit、jira-transition.py do/path、jira-issue.py update、jira-worklog.py add、jira-weblink.py add、jira-link.py create（FROM_KEY，即命名形式中的 --target）、jira-attachment.py add 和 jira-create.py issue：

── PROJ-123 · Task · Open · resolution: – · assignee: unassigned
   time: logged 15m / estimate – / remaining – · labels: –
(!) ticket is "Open" while you work on it: claim it (assign + start work)

**读取 (!) 行，并在报告工作完成前采取相应行动。**当你写入工单时，如果工单处于 Open 或 Backlog、处于 In Progress 但未分配、已分配给其他人、已完成、已完成但没有解决方案、未完成却带有解决方案，或登记的工时超过预估工时，就会显示这些提示。处于 QA 等审查状态的未分配工单不会显示提示：按设计，它会等待团队池处理。执行转换或创建操作后，只会运行解决方案和工时检查，因为状态和经办人正是该命令刚设置的内容。

使用 --json 时，相同信息会作为 ticket_state 字段出现在输出对象中，与已有键并列：key、status、status_category、issuetype、resolution、assignee、assignee_is_you、time_spent_seconds、original_estimate_seconds、remaining_estimate_seconds、labels 和 hints；最后一个字段包含作为字符串的 (!) 行。请像处理 (!) 行一样读取 ticket_state.hints。jira-attachment.py add --json 会打印列表，因此其状态仍以文本形式输出到 stderr。--quiet 不会打印状态。

每次写入会多进行一次读取，以获取状态（jira-comment.py add 会在发布前再读取一次，以显示接手警告），且读取失败不会导致命令失败：查询错误时会打印一行，或在 JSON 中变为 "ticket_state": {"key": …, "error": "<type>"}。JIRA_TICKET_STATE=0 会在所有地方关闭此功能，同时关闭 jira-comment.py add 发布前显示的警告；work 的接手提示仍会显示。logged 是 Jira 自带的工时跟踪：在其他地方登记的工时只有同步到 Jira 工作日志后才会显示。

发布维基标记内容前会先重写并检查

所有用于写入维基标记内容的 --comment 和 --description 选项都会在写入前通过三个检查，默认全部启用，因为渲染错误不会有任何提示——无论如何，API 都会返回 2xx。这七个选项分别是：jira-comment.py add/edit、jira-transition.py do --comment、jira-transition.py path --comment、jira-worklog.py add --comment，以及 jira-create.py issue 和 jira-issue.py update 的 --description。通过 --fields-json 偷渡的正文不会经过检查——该选项按设计会写入原始字段。jira-version.py 的两个 --description 字段（create 和 update）都不会经过检查；Jira 是否会将版本描述渲染为维基标记尚未验证，而其帮助文本声称会渲染也可能只是错误的说法。

1. Jira 会将其渲染为删除线的短横线会被转义。 \- 会显示为普通连字符，因此发布的文本会按原样显示；stderr 会说明更改了多少行，并展示前五行。（只有一种情况下转义符会显示出来：两个宏紧挨着书写时，短横线可能会落入链接目标中。普通文本不会触发这种情况。）--no-auto-escape 会保留原样标记，但单独使用时不会发布刻意写出的 -strikethrough-：lint 和渲染检查仍会拒绝这段内容。要发布这种内容，请使用 --no-auto-escape --force。
2. 会对标记和工单语言进行 lint 检查。 将块级标签用于行内（{code}、{noformat}、{quote}、{panel} 都是块级标签）、标签数量不匹配，以及仅限英语的项目中出现德语文本，都会中止写入。--force 会将检查结果转为警告并继续发布。
3. 文本会由实例渲染；如果返回结果中包含删除线，则会拒绝发布。 每次发布需要额外调用一次 API，并能捕获本地检查无法发现的问题——自动链接的工单键会产生一个边界，而这个边界只存在于能解析该键的实例上。已解析工单的键会被 Jira 作为状态样式显示为删除线，不会被报告。--no-preflight 会跳过此检查；如果渲染器不可达，则会警告一次并继续发布。

无论三项检查中的哪一项发现问题，--force 都会继续发布。所有命令的标志名称都相同。七个选项也都支持 --dry-run：仍会执行转义和 lint 检查——预览会显示实际写入时将发布的文本——但不会调用渲染器或执行写入。详情请参阅 references/comments.md。

基本用法

uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py get PROJ-123
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-search.py query "assignee = currentUser() AND status != Closed" -n 5 -f key,summary,status
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 --assignee me --priority Critical
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text"
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text" --no-auto-escape --force  # deliberate -strikethrough-
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-transition.py do PROJ-123 "In Progress"
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 2h --comment "Work done"
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "Summary" --type Task

转换：list 会显示每个转换的 ID 及其界面要求；将 ID 传给 do——名称或目标状态并不总是唯一的，如果存在歧义，系统会拒绝操作，而不是猜测。 终止转换：传入 --resolution <value>（Done、Won't do）；如果被拒绝（“cannot be set”），请不带该参数重试——参阅 references/intent-verbs.md。版本：使用 jira-version.py 前请先阅读 references/versions.md。 提及用户：发布命令会验证 [~username]（未匹配时会提供建议）；get/work 会打印用户名（参阅 references/fields-and-users.md）。

相关技能

jira-syntax：描述和评论使用 Jira 维基标记，而不是 Markdown。

不加主观评论

陈述发生了什么，不要评价好坏——参阅 references/no-editorializing.md。

参考资料

• references/jql-quick-reference.md、references/jql-cookbook.md
• references/multi-profile.md — --profile
• references/troubleshooting.md — 身份验证、401/403
• references/issue-editing.md — 编辑、删除、清除字段、--fields-json
• references/creation.md — 创建、--parent、字段、管理员范围（project、tempo-account.py）
• references/comments.md — 编辑、删除、检查、通过 - 提供正文、受限评论（--visibility）
• references/worklog.md — --started、范围、--tempo-account、delete
• references/attachments.md — 上传、下载
• references/links.md — 链接
• references/agile.md — 冲刺/看板
• references/no-editorializing.md — 不要自我吹嘘
• references/fields-and-users.md — 自定义字段 ID、用户、问题类型、屏幕字段（jira-fields.py meta）
• references/watchers.md — 关注、订阅、列出关注者
• references/versions.md — 修复版本/影响版本、发行版、版本 CRUD
• references/qa-gather.md — 审计包（相关项、文字中的 URL、通过变更日志和工作日志进行的自我审核检查——不是经办人）
• references/intent-verbs.md — work / qa / qa-fail / act、准确的转换名称

身份验证

Cloud：JIRA_URL + JIRA_USERNAME + JIRA_API_TOKEN。Server/DC：JIRA_URL + JIRA_PERSONAL_TOKEN。在 ~/.env.jira 或 ~/.jira/profiles.json 中配置。