jira

Jira 技能

概述

此技能提供一个 Python CLI，用于处理常见的 Jira REST API 工作流：

• 使用 JQL 搜索
• 获取议题详情
• 使用 JSON 负载创建和更新议题
• 按名称或 ID 转换议题状态
• 添加评论并列出现有评论
• 查找创建议题所需的议题类型和必填字段

此技能支持 Jira Cloud 的电子邮件地址加 API 令牌身份验证，以及 Jira Server 或 Data Center 的个人访问令牌身份验证。

默认在读取命令中使用 --fields，以精简输出。脚本支持点号表示法，例如 fields.status.name，并以制表符分隔的格式打印列表。

前提条件

运行脚本前，请设置所需的环境变量。

平台	运行时
跨平台	Python 3.11+

身份验证变量

变量	何时需要	用途
JIRA_BASE_URL	始终	Jira 基础 URL，例如 https://company.atlassian.net
JIRA_USER_EMAIL	Jira Cloud	用于基本身份验证的账户电子邮件地址
JIRA_API_TOKEN	Jira Cloud	与 Jira Cloud 电子邮件地址配对的 API 令牌
JIRA_PAT	Jira Server 或 Data Center	用于持有者身份验证的个人访问令牌
JIRA_CLOUD_TOKEN_MODE	Jira Cloud 可选	unscoped（默认）或 scoped
JIRA_CLOUD_ID	Scoped Jira Cloud 令牌	Atlassian Cloud 资源标识符

系统会自动选择身份验证方式：

• 如果设置了 JIRA_PAT，脚本会为 Jira Server 或 Data Center 使用持有者身份验证。
• 否则，脚本会要求提供 JIRA_USER_EMAIL 和 JIRA_API_TOKEN，用于 Jira Cloud。
• Scoped Cloud 模式只会将请求路由至 https://api.atlassian.com/ex/jira/{cloudId}； 混用 Cloud 和 Data Center 凭据时会拒绝请求。

Scoped Cloud 令牌设置

Scoped 模式使用与 unscoped 模式相同的基本身份验证变量，并 额外需要 Cloud ID。此模式并非 OAuth 3LO 流程，因此 oauth/token/accessible-resources 端点不会用于发现或检查这些凭据。

1. 为你的 Atlassian 账户创建 scoped API 令牌，并在创建时选择其范围。 请参阅管理 Atlassian 账户的 API 令牌。
2. 为计划运行的命令选择范围。read:jira-work 适用于 search、get、comments 和 fields。对于 create、update、transition 和 comment，请添加 write:jira-work。粒度范围列于 适用于 OAuth 2.0 和 Forge 应用的 Jira 范围。 Jira 项目权限仍会独立于令牌范围生效。
3. 向可信的 Atlassian 管理员或从你站点的账户记录中获取该站点的 Cloud ID。 Cloud ID 并非机密信息，但它决定请求的目标地址。
4. 确认 Cloud ID 与 JIRA_BASE_URL 属于同一站点。CLI 无法验证此关联：在 scoped 模式下，它会将请求路由至 Atlassian 资源 API，而不会将 JIRA_BASE_URL 用作目标地址。 请将此关联视为由操作人员维护的配置。
5. 设置变量，然后使用只读命令确认访问权限：

export JIRA_BASE_URL="https://company.atlassian.net"
export JIRA_USER_EMAIL="[email protected]"
export JIRA_API_TOKEN="$(cat ~/.secrets/jira-token)"
export JIRA_CLOUD_TOKEN_MODE="scoped"
export JIRA_CLOUD_ID="your-cloud-id"
python scripts/jira.py --fields key search "ORDER BY created DESC" --max-results 1

读取成功可证明令牌和路由能够配合工作，但不能证明 Cloud ID 对应 JIRA_BASE_URL，因此请按照第 4 步单独验证。

运行变量

变量	必需时机	用途
JIRA_AUDIT_LOG	可选	JSON Lines 审计日志的路径。设置后，将审计每个请求（参见审计日志）。
JIRA_AUDIT_ACTOR	可选	覆盖记录的操作者身份（例如，CI 服务主体）。
JIRA_DEBUG	可选	仅从继承的环境中读取。设为 1 可在失败时打印已编辑的回溯信息。绝不会停用脱敏。
JIRA_ALLOW_INSECURE	可选	设为 1 仅允许显式指定的环回 HTTP 开发端点。
JIRA_CONFIRM_WRITES	可选	仅从继承的环境中读取。设为 1，即可在不使用 --confirm 或 --yes 的情况下通过写入确认关卡。

审计日志

设置 JIRA_AUDIT_LOG 后，脚本会为每个 API 请求写入结构化的 JSON Lines 审计记录。审计采用失败即关闭和预写入机制：

• 在发送请求之前写入 attempt 记录。如果无法写入审计日志，则中止操作，且不会向 Jira 发送任何内容。
• 请求完成后写入 outcome 记录（success 或 error，失败时附带 HTTP 状态码）。

每条记录都包含 UTC 时间戳、actor（取自 JIRA_AUDIT_ACTOR，否则取自 JIRA_USER_EMAIL 或 jira-pat）、操作、HTTP 方法、规范化的源以及身份验证模式和事件。资源路径、Cloud ID、凭据、授权标头和查询字符串均不包含在内。请将此敏感运行文件放在访问受控的路径中，并仅在运行需要的期限内保留。请求发出后若审计失败，只会发出警告，不会更改结果。

凭据轮换

Atlassian Cloud API 令牌的选定有效期为 1 至 365 天。建议使用 范围受限的令牌，并设置 JIRA_CLOUD_TOKEN_MODE=scoped 和 JIRA_CLOUD_ID。 不使用 Atlassian 3LO，因为其令牌交换需要客户端密钥。 对于 Jira Data Center，请通过 Jira UI 创建有明确期限的 PAT，并在带外轮换。 CLI 不会签发 PAT，因为响应会包含新的密钥，且没有具备事务性、对模型不可见的接收端。

凭据设置

当凭据缺失、不完整或无法使用时，请运行此工作流。该工作流优先验证且不会造成破坏：它会审计当前状态、引导获取凭据、仅写入非敏感值，并在用户自行提供凭据后验证连接。

安全边界

这些规则不会因自主模式或用户请求而调整。

• 绝不在聊天中索要、接受或复述令牌或 PAT。每当指示用户添加令牌时，都要显示此警告：

  ⚠️ NEVER paste your API token or PAT into this chat.
     Tokens entered here are sent through the AI model and are not secure.
     Edit the credentials file directly in the editor instead.
  

• 绝不写入凭据值。非机密值（基本 URL、电子邮件）可以写入；令牌所在行是占位符，由用户在编辑器中替换。

• 绝不将凭据写入受版本控制的文件。~/.jira.env 位于用户主目录中，不属于任何代码仓库，因此不会被意外提交。不要写入 .vscode/mcp.json 或任何代码仓库文件。

• 未经用户明确确认，绝不修改 shell 配置文件。

• 绝不显示令牌值或其任何部分，包括前缀。凭据变量只能报告为已设置或缺失。

• 绝不运行会打印环境变量值的命令。禁止使用 printenv | grep -i JIRA 或任何其他筛选式转储：grep 只会选择要打印的行，并不会对其进行屏蔽，因此有效令牌会输出到标准输出并进入对话记录。请改用下方协议中的“已设置或缺失”探测方法。即使在排查问题时，也绝不能在回复中包含原始凭据值、完整请求标头或详细模式或跟踪模式下的 HTTP 输出。

• 在用户明确确认进行连接测试之前，不得发送任何网络请求。

终端会话隔离

Agent 的终端与用户的终端是不同的会话，因此，在一个会话中执行的 export 对另一个会话不可见。CLI 会在创建客户端之前，在进程内部从 ~/.jira.env 加载支持的 Jira 变量。它将所有值都视为数据，绝不会将文件作为 shell 代码执行，也不会覆盖终端中已继承的变量。

JIRA_DEBUG 和 JIRA_CONFIRM_WRITES 是仅从继承环境读取的控制变量。未经确认的写入会在读取凭据文件之前被拒绝，因此该文件无法授予修改权限。

在 POSIX 平台上，CLI 要求该文件归当前用户所有，且只有该用户有权访问。它会以不跟随符号链接的方式并以非阻塞模式打开该路径，然后在加载值之前拒绝非普通文件、超大文件、格式错误的赋值，以及具有组或其他用户权限的文件。Windows 无法通过此路径执行等效的所有者和权限检查；请使用仅限用户访问的 ACL 保护该文件。错误信息会说明配置问题，但不会打印凭据值。

环境文件用于连接两个会话：

1. 在 POSIX 上，运行 umask 077; touch ~/.jira.env; chmod 0600 ~/.jira.env，以仅限所有者访问的权限创建文件。在 Windows 上，在用户配置文件目录下创建文件，并设置仅限用户访问的 ACL。填写非机密值和凭据占位符。
2. 解析并显示绝对路径，让用户确切知道要编辑哪个文件。
3. 使用 code ~/.jira.env 打开文件。
4. 用户替换占位符并保存。
5. 运行 Jira CLI 命令。CLI 会直接读取该文件；不要对其执行 source。

协议

1. 审计。 CLI 会从 ~/.jira.env 加载受支持的值，因此仅探测继承的进程环境变量并不能完成全面的配置审计。检查文件是否存在，但不要读取或打印文件内容。对于仅限继承的环境变量，将已知名称分类为已设置或缺失，不要打印任何值：

    for v in JIRA_BASE_URL JIRA_USER_EMAIL JIRA_API_TOKEN JIRA_PAT JIRA_CLOUD_TOKEN_MODE JIRA_CLOUD_ID JIRA_AUDIT_LOG JIRA_AUDIT_ACTOR; do
     if printenv "$v" >/dev/null 2>&1; then echo "$v: set"; else echo "$v: missing"; fi
   done
   

printenv 仅在继承的环境变量存在时才会以零状态码退出，且其输出会被丢弃，因此分类结果不会泄露任何值。审计期间不要使用任何会修改内容的命令。让 Jira CLI 在进程内加载文件后，通过不显示值的验证来识别仍然缺失的变量。 2. 检测平台。 设置了 JIRA_PAT 表示使用 Server 或 Data Center。设置了 JIRA_USER_EMAIL 和 JIRA_API_TOKEN 表示使用 Cloud。如果存在混合或模糊的情况，请询问用户使用的是哪个平台，而不是猜测，因为选择错误会导致身份验证失败，看起来像是凭据无效。 3. 验证现有值。 确认 JIRA_BASE_URL 以 https:// 开头，并指出格式错误的值。找出检测到的平台所需的缺失变量。 4. 指导获取凭据。 对于 Cloud，引导用户前往 Atlassian 账户的令牌页面；对于 Server 或 Data Center，引导用户前往其实例的个人访问令牌设置。说明操作步骤，但绝不索要令牌。 5. 写入文件。 创建或更新 ~/.jira.env，其中包含非机密值和凭据占位符，并加入请勿提交的警告注释。 6. 验证连接。 用户确认已保存凭据后，运行一次只读调用。CLI 会在进程内加载文件。401 或 403 表示凭据错误、已过期或已撤销；连接错误表示基础 URL 有误。 7. 总结。 报告更改内容、尚待完成的事项，以及每个变量的已设置或缺失状态。

完成条件

当检测到的平台所需的所有变量均已设置、基础 URL 格式正确，且一次只读调用成功时，配置才算完成。未达到上述条件时，应报告为未完成，并指出具体的后续步骤，绝不可称为部分成功。

快速开始

搜索当前 Jira 问题并返回简洁的表格：

python scripts/jira.py --fields key,fields.summary,fields.status.name search 'assignee = currentUser() ORDER BY updated DESC'

使用简洁的字段列表检查一个问题：

python scripts/jira.py --fields key,fields.summary,fields.status.name,fields.assignee.displayName get PROJ-123

通过管道将 JSON 输入并创建问题：

cat <<'EOF' | python scripts/jira.py create
{
  "fields": {
    "project": { "key": "PROJ" },
    "summary": "Fix login timeout on mobile",
    "issuetype": { "name": "Bug" }
  }
}
EOF

参数参考

命令或选项	语法	默认值	描述
search	python scripts/jira.py search '<jql>' [max_results]	max_results = 50	使用 JQL 搜索问题
get	python scripts/jira.py get <ISSUE-KEY>	无	获取单个问题
create	python scripts/jira.py create '<json>'	未提供时读取标准输入	根据 JSON 创建问题
update	python scripts/jira.py update <ISSUE-KEY> '<json>'	未提供时读取标准输入	根据 JSON 更新问题
transition	python scripts/jira.py transition <ISSUE-KEY> '<name-or-id>'	无	将问题转到其他工作流状态
comment	python scripts/jira.py comment <ISSUE-KEY> '<body>'	未提供时读取标准输入	为问题添加评论
comments	python scripts/jira.py comments <ISSUE-KEY> [ISSUE-KEY ...]	无	列出一个或多个问题的评论
fields	python scripts/jira.py fields <PROJECT-KEY> [issue-type-id]	无	查询问题类型或必填的创建字段
--fields	--fields key,fields.summary,...	无	从 search、get 和 comments 的输出中提取指定字段

脚本参考

搜索问题

对 Jira Cloud 查询使用范围明确的 JQL。请包含项目、经办人、冲刺或其他筛选条件，不要只使用 ORDER BY 查询。 有关本技能所需的查询模式，请参阅 JQL 参考。

python scripts/jira.py --fields key,fields.summary,fields.status.name search 'project = PROJ AND status = "In Progress"'
python scripts/jira.py --fields key,fields.summary search 'assignee = currentUser() ORDER BY updated DESC' 10

获取单个问题

python scripts/jira.py --fields key,fields.summary,fields.priority.name,fields.status.name get PROJ-123

创建问题

首先查询有效的问题类型：

python scripts/jira.py fields PROJ

检查某个问题类型的必填字段：

python scripts/jira.py fields PROJ 10045

创建问题：

python scripts/jira.py create '{
  "fields": {
    "project": { "key": "PROJ" },
    "summary": "Document rollout checklist",
    "issuetype": { "name": "Task" },
    "labels": ["docs", "release"]
  }
}'

更新问题

python scripts/jira.py update PROJ-123 '{
  "fields": {
    "summary": "Updated summary",
    "priority": { "name": "High" },
    "labels": ["backend", "urgent"]
  }
}'

转换问题状态

使用转换显示名称或数字转换 ID：

python scripts/jira.py transition PROJ-123 'In Progress'
python scripts/jira.py transition PROJ-123 31

如果未找到转换名称，脚本会在错误输出中返回可用的转换名称。

评论问题

python scripts/jira.py comment PROJ-123 'PR #42 addresses this issue.'
printf 'Deployed to staging.\n' | python scripts/jira.py comment PROJ-123

列出评论

python scripts/jira.py --fields _issue,author.displayName,created,body comments PROJ-123 PROJ-456

故障排查

症状	可能原因	解决方法
JIRA_BASE_URL is not set	缺少基础 URL	在当前 shell 中导出 JIRA_BASE_URL
身份验证错误	令牌错误或缺少身份验证变量	对于 Jira Server 或 Data Center，请验证 JIRA_PAT；对于 Jira Cloud，请验证 JIRA_USER_EMAIL 和 JIRA_API_TOKEN
Invalid issue key	问题键格式不正确	使用 PROJ-123 格式的键
未找到转换	请求的工作流转换不可用	使用错误输出中返回的转换名称重新运行命令
JSON 负载错误	传递给 create 或 update 的 JSON 无效	验证负载，并使用格式正确的 JSON 重试
网络连接错误	无法访问 Jira 实例 URL	验证基础 URL 和本地网络访问权限