Jira Agile API技能：管理看板、冲刺和问题 | 敏捷开发集成指南 | SkillsMDJira Agile API技能：管理看板、冲刺和问题 | 敏捷开发集成指南
jira-agile by 01000001-01001110/agent-jira-skills
npx skills add https://github.com/01000001-01001110/agent-jira-skills --skill jira-agile🇨🇳中文介绍
Jira Agile Skill
目的
管理 Jira Agile 看板和冲刺 - 列出看板、管理冲刺、将问题移至冲刺。
使用场景
- 列出 Scrum/Kanban 看板
- 管理冲刺（创建、开始、结束）
- 将问题移入/移出冲刺
- 获取冲刺中的问题
先决条件
- 已认证的 JiraClient（参见 jira-auth skill）
- 看板/冲刺管理权限
- 注意：使用
/rest/agile/1.0/ 而非 /rest/api/3/
实现模式
步骤 1：创建 Agile 客户端扩展
class JiraAgileClient extends JiraClient {
async agileRequest<T>(path: string, options: RequestInit = {}): Promise<T> {
const url = `${this.baseUrl}/rest/agile/1.0${path}`;
const response = await fetch(url, {
...options,
headers: { ...this.headers, ...options.headers },
});
if (!response.ok) {
const error = await response.json().catch(() => ({}));
throw new Error(`Jira Agile API error: ${response.status} - ${JSON.stringify(error)}`);
}
return response.json();
}
}
步骤 2：列出看板
interface Board {
id: number;
self: string;
name: string;
type: 'scrum' | 'kanban';
projectKey?: string;
}
interface BoardsResponse {
values: Board[];
startAt: number;
maxResults: number;
total: number;
isLast: boolean;
}
async function listBoards(
client: JiraAgileClient,
options: {
type?: 'scrum' | 'kanban';
projectKeyOrId?: string;
maxResults?: number;
} = {}
): Promise<Board[]> {
const params = new URLSearchParams();
if (options.type) params.set('type', options.type);
if (options.projectKeyOrId) params.set('projectKeyOrId', options.projectKeyOrId);
if (options.maxResults) params.set('maxResults', String(options.maxResults));
const response = await client.agileRequest<BoardsResponse>(
`/board?${params.toString()}`
);
return response.values;
}
🇺🇸English
Jira Agile Skill
Purpose
Manage Jira Agile boards and sprints - list boards, manage sprints, move issues to sprints.
When to Use
- Listing Scrum/Kanban boards
- Managing sprints (create, start, end)
- Moving issues to/from sprints
- Getting sprint issues
Prerequisites
- Authenticated JiraClient (see jira-auth skill)
- Board/sprint management permissions
- Note: Uses
/rest/agile/1.0/ NOT /rest/api/3/
Implementation Pattern
Step 1: Create Agile Client Extension
class JiraAgileClient extends JiraClient {
async agileRequest<T>(path: string, options: RequestInit = {}): Promise<T> {
const url = `${this.baseUrl}/rest/agile/1.0${path}`;
const response = await fetch(url, {
...options,
headers: { ...this.headers, ...options.headers },
});
if (!response.ok) {
const error = await response.json().catch(() => ({}));
throw new Error(`Jira Agile API error: ${response.status} - ${JSON.stringify(error)}`);
}
return response.json();
}
}
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
步骤 3：获取看板冲刺
interface Sprint {
id: number;
self: string;
state: 'future' | 'active' | 'closed';
name: string;
startDate?: string;
endDate?: string;
goal?: string;
}
async function getBoardSprints(
client: JiraAgileClient,
boardId: number,
state?: 'future' | 'active' | 'closed' | string
): Promise<Sprint[]> {
const params = state ? `?state=${state}` : '';
const response = await client.agileRequest<{ values: Sprint[] }>(
`/board/${boardId}/sprint${params}`
);
return response.values;
}
步骤 4：获取冲刺问题
interface SprintIssue {
id: string;
key: string;
self: string;
fields: {
summary: string;
status: { name: string };
assignee?: { displayName: string };
};
}
async function getSprintIssues(
client: JiraAgileClient,
sprintId: number,
options: {
maxResults?: number;
startAt?: number;
} = {}
): Promise<SprintIssue[]> {
const params = new URLSearchParams();
if (options.maxResults) params.set('maxResults', String(options.maxResults));
if (options.startAt) params.set('startAt', String(options.startAt));
const response = await client.agileRequest<{ issues: SprintIssue[] }>(
`/sprint/${sprintId}/issue?${params.toString()}`
);
return response.issues;
}
步骤 5：将问题移至冲刺
async function moveIssuesToSprint(
client: JiraAgileClient,
sprintId: number,
issueKeys: string[],
options: {
rankBeforeIssue?: string;
rankAfterIssue?: string;
} = {}
): Promise<void> {
await client.agileRequest(`/sprint/${sprintId}/issue`, {
method: 'POST',
body: JSON.stringify({
issues: issueKeys,
...options,
}),
});
}
步骤 6：创建冲刺
interface CreateSprintInput {
name: string;
boardId: number;
startDate?: string;
endDate?: string;
goal?: string;
}
async function createSprint(
client: JiraAgileClient,
input: CreateSprintInput
): Promise<Sprint> {
return client.agileRequest<Sprint>('/sprint', {
method: 'POST',
body: JSON.stringify({
name: input.name,
originBoardId: input.boardId,
startDate: input.startDate,
endDate: input.endDate,
goal: input.goal,
}),
});
}
步骤 7：开始/结束冲刺
async function startSprint(
client: JiraAgileClient,
sprintId: number,
startDate: string,
endDate: string
): Promise<void> {
await client.agileRequest(`/sprint/${sprintId}`, {
method: 'POST',
body: JSON.stringify({
state: 'active',
startDate,
endDate,
}),
});
}
async function endSprint(
client: JiraAgileClient,
sprintId: number
): Promise<void> {
await client.agileRequest(`/sprint/${sprintId}`, {
method: 'POST',
body: JSON.stringify({
state: 'closed',
}),
});
}
curl 示例
列出看板
curl -X GET "https://mycompany.atlassian.net/rest/agile/1.0/board?type=scrum" \
-H "Authorization: Basic $(echo -n 'email:token' | base64)" \
-H "Accept: application/json"
获取看板冲刺
curl -X GET "https://mycompany.atlassian.net/rest/agile/1.0/board/1/sprint?state=active,future" \
-H "Authorization: Basic $(echo -n 'email:token' | base64)" \
-H "Accept: application/json"
将问题移至冲刺
curl -X POST "https://mycompany.atlassian.net/rest/agile/1.0/sprint/1/issue" \
-H "Authorization: Basic $(echo -n 'email:token' | base64)" \
-H "Content-Type: application/json" \
-d '{"issues": ["PROJ-123", "PROJ-124"]}'
创建冲刺
curl -X POST "https://mycompany.atlassian.net/rest/agile/1.0/sprint" \
-H "Authorization: Basic $(echo -n 'email:token' | base64)" \
-H "Content-Type: application/json" \
-d '{"name": "Sprint 1", "originBoardId": 1, "goal": "Complete MVP"}'
API 端点摘要
| 操作 | 方法 | 路径 |
|---|
| 列出看板 | GET | /board |
| 获取看板 | GET | /board/{boardId} |
| 获取看板冲刺 | GET | /board/{boardId}/sprint |
| 获取冲刺 | GET | /sprint/{sprintId} |
| 创建冲刺 | POST | /sprint |
| 更新冲刺 | PUT | /sprint/{sprintId} |
| 删除冲刺 | DELETE | /sprint/{sprintId} |
| 获取冲刺问题 | GET | /sprint/{sprintId}/issue |
| 将问题移至冲刺 | POST | /sprint/{sprintId}/issue |
常见错误
- 使用
/rest/api/3/ 而不是 /rest/agile/1.0/
- 尝试将问题添加到已关闭的冲刺
- Kanban 看板没有冲刺
- 冲刺 ID 是看板特定的
参考
版本历史
Step 2: List Boards
interface Board {
id: number;
self: string;
name: string;
type: 'scrum' | 'kanban';
projectKey?: string;
}
interface BoardsResponse {
values: Board[];
startAt: number;
maxResults: number;
total: number;
isLast: boolean;
}
async function listBoards(
client: JiraAgileClient,
options: {
type?: 'scrum' | 'kanban';
projectKeyOrId?: string;
maxResults?: number;
} = {}
): Promise<Board[]> {
const params = new URLSearchParams();
if (options.type) params.set('type', options.type);
if (options.projectKeyOrId) params.set('projectKeyOrId', options.projectKeyOrId);
if (options.maxResults) params.set('maxResults', String(options.maxResults));
const response = await client.agileRequest<BoardsResponse>(
`/board?${params.toString()}`
);
return response.values;
}
Step 3: Get Board Sprints
interface Sprint {
id: number;
self: string;
state: 'future' | 'active' | 'closed';
name: string;
startDate?: string;
endDate?: string;
goal?: string;
}
async function getBoardSprints(
client: JiraAgileClient,
boardId: number,
state?: 'future' | 'active' | 'closed' | string
): Promise<Sprint[]> {
const params = state ? `?state=${state}` : '';
const response = await client.agileRequest<{ values: Sprint[] }>(
`/board/${boardId}/sprint${params}`
);
return response.values;
}
Step 4: Get Sprint Issues
interface SprintIssue {
id: string;
key: string;
self: string;
fields: {
summary: string;
status: { name: string };
assignee?: { displayName: string };
};
}
async function getSprintIssues(
client: JiraAgileClient,
sprintId: number,
options: {
maxResults?: number;
startAt?: number;
} = {}
): Promise<SprintIssue[]> {
const params = new URLSearchParams();
if (options.maxResults) params.set('maxResults', String(options.maxResults));
if (options.startAt) params.set('startAt', String(options.startAt));
const response = await client.agileRequest<{ issues: SprintIssue[] }>(
`/sprint/${sprintId}/issue?${params.toString()}`
);
return response.issues;
}
Step 5: Move Issues to Sprint
async function moveIssuesToSprint(
client: JiraAgileClient,
sprintId: number,
issueKeys: string[],
options: {
rankBeforeIssue?: string;
rankAfterIssue?: string;
} = {}
): Promise<void> {
await client.agileRequest(`/sprint/${sprintId}/issue`, {
method: 'POST',
body: JSON.stringify({
issues: issueKeys,
...options,
}),
});
}
Step 6: Create Sprint
interface CreateSprintInput {
name: string;
boardId: number;
startDate?: string;
endDate?: string;
goal?: string;
}
async function createSprint(
client: JiraAgileClient,
input: CreateSprintInput
): Promise<Sprint> {
return client.agileRequest<Sprint>('/sprint', {
method: 'POST',
body: JSON.stringify({
name: input.name,
originBoardId: input.boardId,
startDate: input.startDate,
endDate: input.endDate,
goal: input.goal,
}),
});
}
Step 7: Start/End Sprint
async function startSprint(
client: JiraAgileClient,
sprintId: number,
startDate: string,
endDate: string
): Promise<void> {
await client.agileRequest(`/sprint/${sprintId}`, {
method: 'POST',
body: JSON.stringify({
state: 'active',
startDate,
endDate,
}),
});
}
async function endSprint(
client: JiraAgileClient,
sprintId: number
): Promise<void> {
await client.agileRequest(`/sprint/${sprintId}`, {
method: 'POST',
body: JSON.stringify({
state: 'closed',
}),
});
}
curl Examples
List Boards
curl -X GET "https://mycompany.atlassian.net/rest/agile/1.0/board?type=scrum" \
-H "Authorization: Basic $(echo -n 'email:token' | base64)" \
-H "Accept: application/json"
Get Board Sprints
curl -X GET "https://mycompany.atlassian.net/rest/agile/1.0/board/1/sprint?state=active,future" \
-H "Authorization: Basic $(echo -n 'email:token' | base64)" \
-H "Accept: application/json"
Move Issues to Sprint
curl -X POST "https://mycompany.atlassian.net/rest/agile/1.0/sprint/1/issue" \
-H "Authorization: Basic $(echo -n 'email:token' | base64)" \
-H "Content-Type: application/json" \
-d '{"issues": ["PROJ-123", "PROJ-124"]}'
Create Sprint
curl -X POST "https://mycompany.atlassian.net/rest/agile/1.0/sprint" \
-H "Authorization: Basic $(echo -n 'email:token' | base64)" \
-H "Content-Type: application/json" \
-d '{"name": "Sprint 1", "originBoardId": 1, "goal": "Complete MVP"}'
API Endpoints Summary
| Operation | Method | Path |
|---|
| List boards | GET | /board |
| Get board | GET | /board/{boardId} |
| Get board sprints | GET | /board/{boardId}/sprint |
| Get sprint | GET | /sprint/{sprintId} |
| Create sprint | POST | /sprint |
| Update sprint | PUT | /sprint/{sprintId} |
| Delete sprint | DELETE | /sprint/{sprintId} |
| Get sprint issues | GET | /sprint/{sprintId}/issue |
| Move issues to sprint | POST | /sprint/{sprintId}/issue |
Common Mistakes
- Using
/rest/api/3/ instead of /rest/agile/1.0/
- Trying to add issues to closed sprints
- Kanban boards don't have sprints
- Sprint IDs are board-specific
References
Version History
AI新闻播客制作技能：实时新闻转对话式播客脚本与音频生成
