jira

Jira

通过 Jira 进行问题跟踪、搜索和工作流管理。

解析脚本路径

示例中的 SKILL_DIR 是已加载 SKILL.md 所在的目录。 运行命令前，请将其设置为该目录的绝对路径；不要假设 Agent 会设置此 shell 变量。如果脚本路径包含空格，请用引号括起来。

安装

1. 安装 Python 依赖项：

   pip install --user requests keyring pyyaml pyadf
   

2. 下载此技能：从 Releases 下载，或直接使用此代码仓库中的版本。

设置验证

安装后，运行以下命令验证技能配置：

$SKILL_DIR/scripts/jira.py check

此命令将检查：

• Python 依赖项（requests、keyring、pyyaml、pyadf）
• 身份验证配置
• 与 Jira 的连接

如果缺少任何内容，检查命令会提供设置说明。

网络访问

Jira API 命令需要通过 HTTPS 向配置的 Jira 主机发起出站连接。远程操作需要出站网络访问。如果 Agent 环境限制了网络访问，请在首次运行远程命令前，通过该环境的审批或网络控制申请访问权限，并重复使用已授予的授权。本地帮助和文件处理不需要网络访问。技能说明不会授予网络访问权限。请将 DNS、连接和超时故障报告为网络错误；不要通过重置凭据来解决这些问题。如果已获批准的访问仍然失败，请停止并报告。身份验证和权限错误需要用户采取行动。

身份验证

请使用以下任一方法配置 Jira 身份验证：

选项 1：环境变量（推荐）

export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-token"

如需持久保存，请将这些内容添加到 ~/.bashrc 或 ~/.zshrc。

选项 2：配置文件

创建 ~/.config/agent-skills/jira.yaml：

url: https://yourcompany.atlassian.net
email: [email protected]
token: your-token

必需凭据

• URL：你的 Jira 实例 URL（例如，https://yourcompany.atlassian.net）
• Email：你的 Atlassian 账户邮箱
• API Token：在 https://id.atlassian.com/manage-profile/security/api-tokens 创建

配置默认值

你可以选择在 ~/.config/agent-skills/jira.yaml 中配置默认值（JQL 范围、字段、自定义字段、项目默认值）。CLI 参数始终会覆盖配置默认值。有关完整的配置格式和默认值行为，请参阅 configuration.md。

# Show all configuration
$SKILL_DIR/scripts/jira.py config show

# Show project-specific defaults
$SKILL_DIR/scripts/jira.py config show --project DEMO

命令

有关各命令的读写分类，请参阅 permissions.md。

check

验证配置和连接状态。

$SKILL_DIR/scripts/jira.py check

此命令会验证：

• 已安装 Python 依赖项
• 已配置身份验证
• 能够连接到 Jira
• 已检测到 API 版本，且版本兼容

search

使用 JQL（Jira 查询语言）搜索问题。

$SKILL_DIR/scripts/jira.py search "project = DEMO AND status = Open"
$SKILL_DIR/scripts/jira.py search "assignee = currentUser() ORDER BY updated DESC" --max-results 20

参数：

• jql：JQL 查询字符串（必需，除非使用 --contributor）
• --contributor：搜索该用户作为参与者（报告人、经办人或评论者）的所有问题。在 Jira Cloud 上，会自动将邮箱或姓名解析为 accountId。
• --project：用于限定 --contributor 搜索范围的项目键
• --max-results：结果数量上限（默认值：50）
• --fields：要包含的字段，以逗号分隔

因部署类型而异的查询：

可用的 JQL 函数取决于 Jira 的部署类型。运行 check 可查看部署类型以及 ScriptRunner 是否可用。

• 所有部署类型：参阅 jql-reference.md， 了解标准 JQL 模式（状态、日期、字段、排序）。
• 带 ScriptRunner 的 Data Center/Server：参阅 scriptrunner.md，了解 linkedIssuesOf()、 subtasksOf()、commentedByUser() 等高级函数。
• Jira Cloud：不支持 ScriptRunner 函数。请使用 jql-reference.md 中记录的 Cloud 原生替代方案。

问题

获取、创建、更新问题，或对问题发表评论。

# Get issue details (--fields, --contributors)
$SKILL_DIR/scripts/jira.py issue get DEMO-123
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --fields "summary,status,assignee" --contributors

# List comments
$SKILL_DIR/scripts/jira.py issue comments DEMO-123

# Create (--project, --type, --summary required; --description, --priority, --labels, --assignee, --parent, --set-field, --link, --from-file, --json)
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Task --summary "New task"
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Story --summary "New story" --parent EPIC-123
$SKILL_DIR/scripts/jira.py issue create --from-file issue.md --priority Critical

# Update (--summary, --description, --priority, --labels, --assignee, --parent, --remove-parent, --set-field, --link, --unlink, --from-file)
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --summary "Updated" --set-field story_points=5
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --parent EPIC-456
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --remove-parent
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --link "Blocks:DEMO-456"
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --unlink "Blocks:DEMO-456"

# Comment (--security-level for private comments)
$SKILL_DIR/scripts/jira.py issue comment DEMO-123 "This is a comment"

关于 --from-file Markdown 格式，请参阅 from-file-format.md；关于更多模式，请参阅 examples.md。

转换

管理问题工作流转换。

# List available transitions
$SKILL_DIR/scripts/jira.py transitions list DEMO-123

# Transition issue
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "In Progress"
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Completed"

# Transition with private comment
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Internal resolution notes" --security-level "Internal"

其他命令

这些命令的完整文档请参阅 advanced-commands.md：

• config — 查看／管理配置默认值，并发现自定义字段映射
• fields — 列出可用字段（全局或按项目／问题类型）
• statuses — 列出状态和状态类别
• user — 按电子邮件／姓名搜索用户（在 Cloud 上返回 accountId）
• collaboration — 发现史诗中的跨团队协作模式
• automations — 列出并检查 Jira 自动化规则（仅限 Cloud）
• versions — 列出项目版本（发行版）并查看发行报告

JQL 参考

常见 JQL 查询和模式：请参阅 jql-reference.md。

快速参考 — 可与 AND、OR 和 ORDER BY 组合使用：

assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC

对于可跨项目使用的查询，请使用 statusCategory（"To Do"、"In Progress"、Done）。

示例

常见 Jira 工作流：

搜索和查看：

# Find all open tasks assigned to you
jira search "assignee = currentUser() AND status = Open"

# Get issue details
jira issue get DEMO-123 --fields "summary,status,assignee"

# List issue comments
jira issue comments DEMO-123

创建和更新：

# Create a new bug
jira issue create --project DEMO --type Bug --summary "Login page broken"

# Create a story under an epic
jira issue create --project DEMO --type Story --summary "Implement feature" --parent EPIC-123

# Set or change an issue's parent (works for any hierarchy level)
jira issue update DEMO-123 --parent EPIC-456

# Remove an issue's parent
jira issue update DEMO-123 --remove-parent

# Update an issue and add a comment
jira issue update DEMO-123 --priority High --assignee "[email protected]"
jira issue comment DEMO-123 "Assigned to review"

工作流：

# List available transitions
jira transitions list DEMO-123

# Move issue to Done
jira transitions do DEMO-123 "Done" --comment "Completed"

模型指南

此技能会发起需要结构化输入／输出的 API 调用。建议使用具备标准能力的模型。