456 lines
14 KiB
Markdown
456 lines
14 KiB
Markdown
# Jira Cloud API 技能集
|
||
|
||
`Jira` `Claude Code` `REST API` `SAFe` `项目管理`
|
||
|
||
# Claude Code 的 Jira 技能集
|
||
|
||
用于 Claude Code CLI 的 Jira Cloud REST API 技能集，专为下一代（团队管理型）项目构建。
|
||
|
||
## 目录
|
||
|
||
- [项目简介](#项目简介)
|
||
- [目录结构](#目录结构)
|
||
- [安装](#安装)
|
||
- [配置](#配置)
|
||
- [使用方法](#使用方法)
|
||
- [技能列表](#技能列表)
|
||
- [API 参考](#api-参考)
|
||
- [下一代项目与经典项目的区别](#下一代项目与经典项目的区别)
|
||
- [故障排查](#故障排查)
|
||
- [贡献指南](#贡献指南)
|
||
|
||
## 项目简介
|
||
|
||
这是一套用于与 Jira REST API 交互的 Claude Code 技能集合。每个技能都是一个独立的文件夹，包含：
|
||
|
||
- `SKILL.md` - 带有 YAML 前置元数据的 Markdown 文件，供 Claude 读取
|
||
- `scripts/` - 该领域可运行的 Node.js 和 Python 脚本
|
||
|
||
技能涵盖：身份验证、问题管理、搜索、流程转换、敏捷看板、项目管理、SAFe 模式以及 Confluence 空间管理。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
jira/
|
||
├── .env # 你的凭据（不提交到版本库）
|
||
├── .env.example # 配置模板
|
||
├── .gitignore
|
||
├── README.md
|
||
├── run.js # 脚本运行器
|
||
├── .github/
|
||
│ ├── workflows/
|
||
│ │ └── ci.yml # CI 检查
|
||
│ └── hooks/
|
||
│ └── pre-commit # 本地预提交钩子
|
||
├── templates/ # 组织标准模板
|
||
│ ├── TEMPLATES.md # 模板文档
|
||
│ ├── epic-template.json # Epic 结构模板
|
||
│ ├── story-template.json # 用户故事 SAFe 模板
|
||
│ ├── subtask-template.json # 子任务模式
|
||
│ └── python-jira-utils.py # 可复用的 Python 工具函数
|
||
├── jira-auth/
|
||
│ ├── SKILL.md
|
||
│ └── scripts/
|
||
│ ├── test.mjs
|
||
│ └── test.py
|
||
├── jira-issues/
|
||
│ ├── SKILL.md
|
||
│ └── scripts/
|
||
│ ├── create-one.mjs
|
||
│ ├── create-one.py
|
||
│ ├── delete-all.mjs
|
||
│ └── delete-all.py
|
||
├── jira-search/
|
||
│ ├── SKILL.md
|
||
│ └── scripts/
|
||
│ ├── check-issues.mjs
|
||
│ └── check-issues.py
|
||
├── jira-transitions/
|
||
│ ├── SKILL.md
|
||
│ └── scripts/
|
||
│ ├── workflow-demo.mjs
|
||
│ └── workflow-demo.py
|
||
├── jira-agile/
|
||
│ ├── SKILL.md
|
||
│ └── scripts/
|
||
│ ├── bulk-create.mjs
|
||
│ └── bulk-create.py
|
||
├── jira-projects/
|
||
│ ├── SKILL.md
|
||
│ └── scripts/
|
||
│ ├── check-fields.mjs
|
||
│ └── check-fields.py
|
||
├── jira-project-management/
|
||
│ └── SKILL.md
|
||
├── jira-workflow/
|
||
│ └── SKILL.md
|
||
├── jira-safe/
|
||
│ ├── SKILL.md
|
||
│ └── scripts/
|
||
│ ├── add-subtasks.mjs
|
||
│ ├── add-subtasks.py
|
||
│ ├── create-two-level.mjs
|
||
│ ├── create-two-level.py
|
||
│ ├── create-mvp.mjs
|
||
│ └── create-mvp.py
|
||
└── jira-spaces/
|
||
├── SKILL.md
|
||
└── scripts/
|
||
├── list-spaces.mjs
|
||
├── list-spaces.py
|
||
├── create-space.mjs
|
||
├── create-space.py
|
||
├── delete-space.mjs
|
||
└── delete-space.py
|
||
```
|
||
|
||
## 安装
|
||
|
||
### 用于 Claude Code CLI
|
||
|
||
Claude Code 会在 `.claude/skills/[skill-name]/SKILL.md` 路径下自动发现技能。每个技能的 YAML 前置元数据中包含 `name` 和 `description` 字段。
|
||
|
||
**方式一：克隆到 .claude/skills/**
|
||
|
||
```bash
|
||
cd your-project/.claude/skills
|
||
git clone https://github.com/your-repo/jira-skills.git jira
|
||
```
|
||
|
||
技能嵌套在 `jira/` 目录内，不会被自动发现。可在项目的 CLAUDE.md 中引用，或直接运行脚本。
|
||
|
||
**方式二：为单个技能创建符号链接**
|
||
|
||
```bash
|
||
cd your-project/.claude/skills
|
||
git clone https://github.com/your-repo/jira-skills.git jira
|
||
|
||
# 创建符号链接以支持自动发现
|
||
ln -s jira/jira-auth jira-auth
|
||
ln -s jira/jira-issues jira-issues
|
||
ln -s jira/jira-search jira-search
|
||
# ... 以此类推
|
||
```
|
||
|
||
**方式三：复制所需技能**
|
||
|
||
```bash
|
||
cp -r jira-skills/jira-auth your-project/.claude/skills/
|
||
cp -r jira-skills/jira-issues your-project/.claude/skills/
|
||
```
|
||
|
||
### 独立使用
|
||
|
||
克隆到任意目录并直接运行脚本：
|
||
|
||
```bash
|
||
git clone https://github.com/your-repo/jira-skills.git
|
||
cd jira-skills
|
||
cp .env.example .env
|
||
# 编辑 .env 填入你的凭据
|
||
node run.js test
|
||
```
|
||
|
||
## 配置
|
||
|
||
### 1. 获取 API Token
|
||
|
||
访问 https://id.atlassian.com/manage-profile/security/api-tokens 创建令牌。
|
||
|
||
### 2. 创建 .env 文件
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env`：
|
||
|
||
| 变量 | 是否必填 | 说明 |
|
||
|------|----------|------|
|
||
| `JIRA_EMAIL` | 是 | 你的 Atlassian 账户邮箱 |
|
||
| `JIRA_API_TOKEN` | 是 | 第一步创建的 API 令牌 |
|
||
| `JIRA_BASE_URL` | 是 | 你的实例 URL（例如 `https://yourcompany.atlassian.net`） |
|
||
| `JIRA_PROJECT_KEY` | 否 | 默认项目键（默认为 `SCRUM`） |
|
||
| `JIRA_BOARD_ID` | 否 | 默认看板 ID（默认为 `1`） |
|
||
|
||
### 3. 测试连接
|
||
|
||
```bash
|
||
node run.js test
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 脚本运行器
|
||
|
||
`run.js` 脚本可运行任意技能的 scripts 文件夹中的命令：
|
||
|
||
```bash
|
||
node run.js <命令> [参数...]
|
||
node run.js --python <命令> [参数...] # 强制使用 Python
|
||
node run.js --node <命令> [参数...] # 强制使用 Node.js
|
||
```
|
||
|
||
### 命令列表
|
||
|
||
| 命令 | 所属技能 | 说明 | Node.js | Python |
|
||
|------|----------|------|:-------:|:------:|
|
||
| `test` | jira-auth | 验证身份认证并运行测试套件 | 是 | 是 |
|
||
| `check-fields` | jira-projects | 列出项目字段和配置 | 是 | 是 |
|
||
| `check-issues` | jira-search | 列出项目中的问题 | 是 | 是 |
|
||
| `create-one` | jira-issues | 创建单个测试问题 | 是 | 是 |
|
||
| `delete-all` | jira-issues | 删除所有问题（默认为试运行） | 是 | 是 |
|
||
| `workflow-demo` | jira-transitions | 演示工作流转换 | 是 | 是 |
|
||
| `bulk-create` | jira-agile | 根据 git 提交批量创建问题 | 是 | 是 |
|
||
| `add-subtasks` | jira-safe | 为问题添加子任务 | 是 | 是 |
|
||
| `create-two-level` | jira-safe | 创建 Epic/Story/Subtask 层级结构 | 是 | 是 |
|
||
| `create-mvp` | jira-safe | 创建完整 MVP 待办事项 | 是 | 是 |
|
||
| `list-spaces` | jira-spaces | 列出 Confluence 空间 | 是 | 是 |
|
||
| `create-space` | jira-spaces | 创建 Confluence 空间 | 是 | 是 |
|
||
| `delete-space` | jira-spaces | 删除 Confluence 空间 | 是 | 是 |
|
||
|
||
### 命令示例
|
||
|
||
```bash
|
||
# 身份验证测试
|
||
node run.js test
|
||
|
||
# 列出所有问题
|
||
node run.js check-issues
|
||
|
||
# 创建测试问题
|
||
node run.js create-one
|
||
|
||
# 删除所有问题（先试运行）
|
||
node run.js delete-all
|
||
node run.js delete-all --confirm # 实际执行删除
|
||
|
||
# 工作流转换
|
||
node run.js workflow-demo status SCRUM-123 # 检查状态
|
||
node run.js workflow-demo start SCRUM-123 # 移至进行中
|
||
node run.js workflow-demo complete SCRUM-123 # 移至已完成
|
||
node run.js workflow-demo demo SCRUM-123 # 完整周期演示
|
||
|
||
# 添加子任务
|
||
node run.js add-subtasks demo # 创建带子任务的演示故事
|
||
node run.js add-subtasks SCRUM-123 "任务1" "任务2" # 添加到已有问题
|
||
|
||
# 创建层级结构
|
||
node run.js create-two-level # Epic -> Stories -> Subtasks
|
||
node run.js create-mvp # 完整 MVP 待办事项结构
|
||
|
||
# Confluence 空间
|
||
node run.js list-spaces # 列出所有空间
|
||
node run.js list-spaces --type global --limit 50 # 过滤并限制数量
|
||
node run.js create-space DOCS "Project Docs" # 创建空间
|
||
node run.js create-space DOCS "Docs" "描述"
|
||
node run.js delete-space DOCS # 交互式删除
|
||
node run.js delete-space DOCS --confirm # 强制删除
|
||
```
|
||
|
||
### 直接执行脚本
|
||
|
||
不使用运行器，直接运行脚本：
|
||
|
||
```bash
|
||
# Python（自动加载 .env）
|
||
python jira-auth/scripts/test.py
|
||
python jira-issues/scripts/create-one.py
|
||
|
||
# Node.js（需要预先设置环境变量）
|
||
export JIRA_EMAIL=... JIRA_API_TOKEN=... JIRA_BASE_URL=...
|
||
node jira-issues/scripts/create-one.mjs
|
||
```
|
||
|
||
### 平台说明
|
||
|
||
- **Windows**：Python 对控制台编码的处理更好，运行器会自动检测并优先选择 Python。
|
||
- **Linux/macOS**：Node.js 运行良好且启动更快。
|
||
- **CI/CD**：两种运行时均可，直接设置环境变量即可。
|
||
|
||
## 技能列表
|
||
|
||
| 技能 | 涵盖内容 |
|
||
|------|----------|
|
||
| `jira-auth` | 身份验证、请求头、速率限制 |
|
||
| `jira-issues` | 创建、读取、更新、删除问题 |
|
||
| `jira-search` | JQL 查询、分页、字段选择 |
|
||
| `jira-transitions` | 推动问题经历工作流状态 |
|
||
| `jira-agile` | 看板、冲刺、待办事项管理 |
|
||
| `jira-projects` | 项目信息、问题类型、状态 |
|
||
| `jira-project-management` | 组件、版本、角色、权限 |
|
||
| `jira-workflow` | 端到端工作流编排 |
|
||
| `jira-safe` | SAFe 模式（Epic/Story/Subtask 层级结构） |
|
||
| `jira-spaces` | Confluence 空间管理（创建、列出、删除） |
|
||
|
||
每个 `SKILL.md` 包含：
|
||
- 带有 `name` 和 `description` 的 YAML 前置元数据
|
||
- TypeScript/JavaScript/Python 实现模式
|
||
- curl 示例
|
||
- 常见错误及解决方案
|
||
|
||
## 模板
|
||
|
||
`templates/` 文件夹包含遵循 SAFe 方法论创建 Jira 问题的组织标准模板。
|
||
|
||
| 模板 | 用途 |
|
||
|------|------|
|
||
| `epic-template.json` | Epic 结构，包含业务成果、成功指标、范围 |
|
||
| `story-template.json` | 用户故事，包含验收标准（Given/When/Then）、完成定义 |
|
||
| `subtask-template.json` | 子任务命名规范和常见任务分解 |
|
||
| `python-jira-utils.py` | 可复用的 Jira API Python 工具函数 |
|
||
| `TEMPLATES.md` | 使用模板的完整文档 |
|
||
|
||
### 模板使用说明
|
||
|
||
模板遵循 SAFe（规模化敏捷框架）模式：
|
||
|
||
**Epic 格式：**
|
||
- 业务成果
|
||
- 成功指标（可衡量的 KPI）
|
||
- 范围（纳入/排除）
|
||
- 目标用户
|
||
|
||
**Story 格式：**
|
||
- 用户故事："作为 [用户]，我希望 [目标]，以便 [收益]"
|
||
- 验收标准：Given/When/Then 场景
|
||
- 完成定义清单
|
||
|
||
**子任务命名：**
|
||
- 动词开头格式："创建 X"、"实现 Y"、"添加 Z"
|
||
|
||
完整文档请参阅 `templates/TEMPLATES.md`。
|
||
|
||
## API 参考
|
||
|
||
### 核心 API（`/rest/api/3/`）
|
||
|
||
| 端点 | 方法 | 用途 |
|
||
|------|------|------|
|
||
| `/myself` | GET | 测试认证，获取当前用户 |
|
||
| `/project/{key}` | GET | 项目详情 |
|
||
| `/issue` | POST | 创建问题 |
|
||
| `/issue/{key}` | GET, PUT, DELETE | 读取、更新、删除问题 |
|
||
| `/issue/{key}/transitions` | GET, POST | 获取/执行流程转换 |
|
||
| `/search` | POST | JQL 搜索 |
|
||
|
||
### 敏捷 API（`/rest/agile/1.0/`）
|
||
|
||
| 端点 | 方法 | 用途 |
|
||
|------|------|------|
|
||
| `/board` | GET | 列出看板 |
|
||
| `/board/{id}/sprint` | GET | 列出冲刺 |
|
||
| `/sprint/{id}/issue` | GET, POST | 冲刺问题 |
|
||
| `/sprint` | POST | 创建冲刺 |
|
||
|
||
### 认证请求头
|
||
|
||
```javascript
|
||
const auth = Buffer.from(`${email}:${token}`).toString('base64');
|
||
headers['Authorization'] = `Basic ${auth}`;
|
||
```
|
||
|
||
### Atlassian 文档格式（ADF）
|
||
|
||
描述字段需要使用 ADF 格式，而非纯文本：
|
||
|
||
```json
|
||
{
|
||
"type": "doc",
|
||
"version": 1,
|
||
"content": [
|
||
{
|
||
"type": "paragraph",
|
||
"content": [{"type": "text", "text": "你的文字"}]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 下一代项目与经典项目的区别
|
||
|
||
这些技能专为**下一代（团队管理型）**项目构建。主要区别如下：
|
||
|
||
| 方面 | 经典（公司管理型） | 下一代（团队管理型） |
|
||
|------|-------------------|---------------------|
|
||
| Epic 关联 | `customfield_10014` | `parent: { key: 'EPIC-KEY' }` |
|
||
| Epic Name 字段 | `customfield_10011` | 不可用 |
|
||
| 子任务类型 | `'Sub-task'` | `'Subtask'` |
|
||
| 项目样式 | `classic` | `next-gen`，`simplified: true` |
|
||
|
||
检测项目类型：
|
||
|
||
```javascript
|
||
const project = await fetch(`${JIRA_URL}/rest/api/3/project/${key}`);
|
||
const isNextGen = project.style === 'next-gen' || project.simplified === true;
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
**401 未授权**
|
||
- 令牌已过期或无效
|
||
- 邮箱与 Atlassian 账户不匹配
|
||
- 令牌没有 API 权限
|
||
|
||
**403 禁止访问**
|
||
- 无权访问该项目/资源
|
||
- 检查项目角色和权限
|
||
|
||
**400 错误请求**
|
||
- 缺少必填字段（`project.key`、`summary`、`issuetype.name`）
|
||
- 描述中 ADF 格式无效
|
||
- 无效的转换 ID（请先查询可用的转换）
|
||
|
||
**404 未找到**
|
||
- 问题或项目不存在
|
||
- 键值拼写错误
|
||
|
||
**429 请求过多**
|
||
- 已触发速率限制。Jira Cloud 每用户每小时约允许 900 次请求。
|
||
- 退避并以指数级延迟重试。
|
||
|
||
## 速率限制
|
||
|
||
Jira Cloud 每用户每小时约允许 900 次请求。若收到 429 响应：
|
||
|
||
1. 检查 `X-RateLimit-Remaining` 响应头
|
||
2. 等待至 `X-RateLimit-Reset` 时间戳后再重试
|
||
3. 对重试实现指数退避策略
|
||
|
||
## 贡献指南
|
||
|
||
### CI 检查
|
||
|
||
Pull Request 会自动运行以下检查：
|
||
- SKILL.md 文件的 YAML 前置元数据验证
|
||
- Node.js 语法验证
|
||
- Python 语法验证
|
||
- 目录结构验证
|
||
- 敏感信息检测
|
||
|
||
### 本地预提交钩子
|
||
|
||
安装预提交钩子，在推送前捕获问题：
|
||
|
||
```bash
|
||
cp .github/hooks/pre-commit .git/hooks/pre-commit
|
||
chmod +x .git/hooks/pre-commit
|
||
```
|
||
|
||
### 添加新技能
|
||
|
||
1. 创建文件夹：`jira-newskill/`
|
||
2. 添加带有前置元数据的 `SKILL.md`：
|
||
```yaml
|
||
---
|
||
name: jira-newskill
|
||
description: 简要描述，让 Claude 了解何时使用此技能。
|
||
---
|
||
```
|
||
3. 添加包含 `.mjs` 和/或 `.py` 脚本的 `scripts/` 文件夹
|
||
4. 更新 `run.js` 中的脚本映射
|
||
5. 更新 README 命令表格
|
||
|
||
## 许可证
|
||
|
||
MIT |