# 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