# jira-skill

**Repository Path**: wufeifei_admin/jira-skill

## Basic Information

- **Project Name**: jira-skill
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Jira Skill

查询、创建、更新 Jira 问题/任务，管理 Sprint 和看板。

## 安装位置

**用户级安装（全局）**：
```
~/.qoder/skills/jira-skill/          # Qoder
~/.cursor/skills/jira-skill/         # Cursor
~/.vscode/extensions/jira-skill/     # VS Code
```

**项目级安装**：
```
项目根目录/.qoder/skills/jira-skill/          # Qoder
项目根目录/.cursor/skills/jira-skill/         # Cursor
项目根目录/.vscode/extensions/jira-skill/     # VS Code
```

## 依赖

```bash
pip install requests
```

## 环境变量配置

### 环境变量读取优先级

1. **项目根目录的 `.env` 文件**（强烈推荐）
   - ⚠️ **只读**：如果文件不存在，**不要创建或修改它**

2. **系统环境变量**

3. **读不到就报错**

### ⚠️ 重要规则

- ❌ **禁止创建或修改 `.env` 文件**
- ✅ 只读取已存在的 `.env` 文件

#### 方式 A：系统环境变量

```bash
# Jira Configuration
export JIRA_URL=http://jira.example.com
export JIRA_USER=your_username
export JIRA_PASSWORD=your_password_or_token
```

⚠️ **重要提示**：
- 敏感字段（密码等）**不要**在调用 Skill 的 `params` 中传入
- 因为明文会显示在日志和输出中，不安全
- 必须在调用前设置环境变量，Skill 会自动从环境变量读取

#### 方式 B：项目级 .env

```bash
# 项目根目录/.env
JIRA_URL=http://jira.example.com
JIRA_USER=your_username
JIRA_PASSWORD=your_password_or_token
```

#### 环境变量说明

| 变量名 | 必填 | 说明 | 示例值 |
|--------|------|------|--------|
| `JIRA_URL` | ✅ | Jira 服务器地址 | `http://jira.example.com` |
| `JIRA_USER` | ✅ | Jira 用户名或邮箱 | `your_username` |
| `JIRA_PASSWORD` | ✅ | Jira 密码或 API Token | `your_password` |
| `JIRA_SKILL_GLOBAL_CONFIG` | ❌ | 全局配置文件路径 | `~/.qoder/skills/jira-skill/config/project.json` |
| `JIRA_SKILL_PROJECT_CONFIG` | ❌ | 项目配置文件路径 | `项目/.qoder/skills/jira-skill/config/project.json` |

#### 参数获取规则

**优先级顺序**：
1. 优先从**当前对话**获取参数值
2. 其次从**配置文件** (project.json) 读取参数定义和默认值
3. **禁止使用历史记忆**中的参数值

**重要规则**：

1. ❌ **禁止传入配置中不存在的参数**

2. ✅ **必填参数必须从对话获取**
   - 只能从当前对话中获取，不能使用默认值
   - ⚠️ **如果必填参数未提供，Skill 会报错并终止任务**

3. ✅ **非必填参数可以使用默认值**

## 功能列表

| 功能 | 说明 |
|------|------|
| `get_issue` | 获取问题详情 |
| `search_issues` | 搜索问题（JQL 查询） |
| `create_issue` | 创建新问题 |
| `update_issue` | 更新问题 |
| `transition_issue` | 转换问题状态 |
| `get_transitions` | 获取可用的状态转换 |
| `add_comment` | 添加评论 |
| `get_comments` | 获取评论列表 |
| `get_projects` | 获取所有项目 |
| `get_project` | 获取项目详情 |
| `list_sprints` | 获取 Sprint 列表 |
| `get_sprint_issues` | 获取 Sprint 中的问题 |
| `add_worklog` | 添加工作日志 |
| `get_worklogs` | 获取工作日志 |

## 使用示例

### 获取问题详情

```python
import os
import sys

os.environ['JIRA_URL'] = 'http://jira.example.com'
os.environ['JIRA_USER'] = 'your_username'
os.environ['JIRA_PASSWORD'] = 'your_password'
os.environ['JIRA_SKILL_GLOBAL_CONFIG'] = '<user_home>/.qoder/skills/jira-skill/config/project.json'

sys.path.insert(0, '<user_home>/.qoder/skills/jira-skill/scripts')
import main

result = main.get_issue({
    "issue_key": "PRJ-123"
})
```

### 搜索问题

```python
result = main.search_issues({
    "jql": "project = PRJ AND status = 'In Progress'",
    "max_results": 20
})
```

### 创建问题

```python
result = main.create_issue({
    "project_key": "PRJ",
    "summary": "修复登录问题",
    "issue_type": "Bug",
    "description": "用户无法正常登录",
    "priority": "High"
})
```

### 更新问题

```python
result = main.update_issue({
    "issue_key": "PRJ-123",
    "priority": "High",
    "assignee": "username"
})
```

### 添加评论

```python
result = main.add_comment({
    "issue_key": "PRJ-123",
    "comment": "这个问题已经在 v1.2.3 版本中修复"
})
```

### 获取项目列表

```python
result = main.get_projects({})
```

### 添加工作日志

```python
result = main.add_worklog({
    "issue_key": "PRJ-123",
    "time_spent": "2h",
    "comment": "修复了登录 bug"
})
```