jira

用途

本技能用于直接与 Jira Cloud 交互，基于 REST API v3 和 JQL 查询，实现问题（工单）管理、搜索、创建、更新、评论、状态流转和分配等操作。适用于需要自动化处理 Jira 工单的开发、运维或项目管理场景。

前置条件

需要设置以下环境变量（或写入 .env 文件）：

JIRA_DOMAIN=company.atlassian.net
JIRA_EMAIL=user@company.com
JIRA_API_TOKEN=your-api-token

API 令牌生成地址：https://id.atlassian.com/manage-profile/security/api-tokens

主要能力与使用方式

技能提供 Python 辅助脚本 scripts/jira_api.py，通过命令行调用 Jira REST API。核心工作流包括：

获取问题详情：python scripts/jira_api.py GET /issue/PROJ-123，可指定字段如 ?fields=summary,status,assignee。
使用 JQL 搜索：python scripts/jira_api.py GET /search --query "jql=project=AOP AND status='In Progress'&maxResults=20"。常见 JQL 模式包括：我的未解决问题 assignee = currentUser() AND resolution = Unresolved；最近更新 updated >= -1d ORDER BY updated DESC；当前冲刺工作 sprint in openSprints() AND assignee = currentUser()。更多 JQL 语法见 references/jql-reference.md。
创建问题：使用 POST /issue，描述字段需采用 ADF 格式（Atlassian Document Format），示例见 references/adf-format.md。
更新问题：使用 PUT /issue/PROJ-123，可修改 summary、labels 等字段。
添加评论：POST /issue/PROJ-123/comment，评论正文同样需要 ADF 格式。
流转状态：先 GET /issue/PROJ-123/transitions 获取可用流转，再 POST /issue/PROJ-123/transitions 并指定 transition id。
分配问题：先通过 GET /user/search?query=username 获取用户 accountId，再 PUT /issue/PROJ-123/assignee 并传入 accountId；取消分配则传入 null。

此外，也可直接使用 curl 调用 REST API，需手动构造 Basic 认证头。

参考文件

references/api-endpoints.md：完整的 REST API v3 端点参考。
references/jql-reference.md：JQL 操作符、函数、字段和模式。
references/adf-format.md：富文本字段的 Atlassian Document Format 格式说明。

常见模式

批量操作：使用 JQL key in (PROJ-1,PROJ-2,PROJ-3) 一次获取多个问题。
获取项目信息：GET /project 列出项目，GET /project/PROJ 获取项目详情。
获取可用问题类型：GET /project/PROJ?expand=issueTypes。

错误处理

常见错误码：400（请求错误，检查 JSON 语法和字段名）、401（未授权，验证凭据）、403（禁止，检查用户权限）、404（未找到，验证问题键存在）、429（限流，等待后重试）。字段验证错误时，Jira 会返回详细的错误信息指明无效字段。

适用场景与限制

适用于需要自动化管理 Jira Cloud 工单的团队或个人，尤其是结合 AI 助手进行问题跟踪、搜索和批量操作的场景。限制方面：仅支持 Jira Cloud（REST API v3），不适用于 Jira Server/Data Center；需要有效的 API 令牌和相应权限；描述和评论必须使用 ADF 格式，不能直接使用纯文本或 Markdown；未提供关于收费、价格或具体平台兼容性的额外信息。