474 lines
20 KiB
Python
474 lines
20 KiB
Python
|
from __future__ import annotations
|
|||
|
|
|
|||
|
|
import base64
|
|||
|
|
import logging
|
|||
|
|
from typing import Any
|
|||
|
|
|
|||
|
|
import httpx
|
|||
|
|
|
|||
|
|
from yuxi.channel.extensions.jira.format import markdown_to_adf
|
|||
|
|
from yuxi.channel.extensions.jira.parse import adf_to_plain_text
|
|||
|
|
from yuxi.channel.protocols import AgentTool, AgentToolParam
|
|||
|
|
|
|||
|
|
logger = logging.getLogger(__name__)
|
|||
|
|
|
|||
|
|
|
|||
|
|
class JiraAgentTools:
|
|||
|
|
def __init__(self):
|
|||
|
|
self._clients: dict[str, httpx.AsyncClient] = {}
|
|||
|
|
|
|||
|
|
def get_tools(self) -> list[AgentTool]:
|
|||
|
|
return [
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_search_issues",
|
|||
|
|
description="使用 JQL 搜索 Jira Issue，如 'project = SUPPORT AND status = Open'",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="jql", type="string", description="JQL 查询语句", required=True),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="max_results",
|
|||
|
|
type="integer",
|
|||
|
|
description="最大返回数量，默认 10",
|
|||
|
|
required=False,
|
|||
|
|
default=10,
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_get_issue",
|
|||
|
|
description="获取指定 Issue 的详细信息，包括描述、状态、负责人、评论等",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="issue_key", type="string", description="Issue Key，如 SUPPORT-123", required=True
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_create_issue",
|
|||
|
|
description="在项目中创建新的 Issue",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="project_key", type="string", description="项目 Key，如 SUPPORT", required=True
|
|||
|
|
),
|
|||
|
|
AgentToolParam(name="summary", type="string", description="Issue 标题/摘要", required=True),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="description", type="string", description="Issue 描述 (Markdown 格式)", required=False
|
|||
|
|
),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="issue_type",
|
|||
|
|
type="string",
|
|||
|
|
description="Issue 类型，如 Bug/Task/Story，默认 Task",
|
|||
|
|
required=False,
|
|||
|
|
default="Task",
|
|||
|
|
),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="priority",
|
|||
|
|
type="string",
|
|||
|
|
description="优先级，如 High/Medium/Low，默认 Medium",
|
|||
|
|
required=False,
|
|||
|
|
default="Medium",
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_transition_issue",
|
|||
|
|
description="流转 Issue 的工作流状态，如 'In Progress' -> 'Done'",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="issue_key", type="string", description="Issue Key", required=True),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="transition_name",
|
|||
|
|
type="string",
|
|||
|
|
description="目标状态名称，如 'Done', 'In Progress'",
|
|||
|
|
required=True,
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_get_transitions",
|
|||
|
|
description="获取 Issue 当前可用的工作流状态流转选项",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="issue_key", type="string", description="Issue Key", required=True),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_assign_issue",
|
|||
|
|
description="分配 Issue 给指定用户",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="issue_key", type="string", description="Issue Key", required=True),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="account_id", type="string", description="目标用户的 Atlassian Account ID", required=True
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_update_issue",
|
|||
|
|
description="更新 Issue 的字段，如摘要、描述、优先级等",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="issue_key", type="string", description="Issue Key", required=True),
|
|||
|
|
AgentToolParam(name="summary", type="string", description="新的 Issue 标题", required=False),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="description", type="string", description="新的 Issue 描述 (Markdown 格式)", required=False
|
|||
|
|
),
|
|||
|
|
AgentToolParam(name="priority", type="string", description="新的优先级", required=False),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_get_comments",
|
|||
|
|
description="获取 Issue 的评论列表",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="issue_key", type="string", description="Issue Key", required=True),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="max_results",
|
|||
|
|
type="integer",
|
|||
|
|
description="最大返回数量，默认 20",
|
|||
|
|
required=False,
|
|||
|
|
default=20,
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_search_users",
|
|||
|
|
description="搜索 Jira 用户，用于 @mention 或分配 Issue",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="query", type="string", description="用户名或邮箱搜索关键词", required=True),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_get_projects",
|
|||
|
|
description="获取可访问的所有 Jira 项目列表",
|
|||
|
|
parameters=[],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_delete_issue",
|
|||
|
|
description="删除指定的 Jira Issue",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="issue_key", type="string", description="Issue Key，如 SUPPORT-123", required=True
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_get_changelog",
|
|||
|
|
description="获取 Issue 的变更历史记录",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="issue_key", type="string", description="Issue Key", required=True),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="max_results",
|
|||
|
|
type="integer",
|
|||
|
|
description="最大返回数量，默认 20",
|
|||
|
|
required=False,
|
|||
|
|
default=20,
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
AgentTool(
|
|||
|
|
name="jira_add_worklog",
|
|||
|
|
description="为 Issue 添加工作日志（工时记录）",
|
|||
|
|
parameters=[
|
|||
|
|
AgentToolParam(name="issue_key", type="string", description="Issue Key", required=True),
|
|||
|
|
AgentToolParam(
|
|||
|
|
name="time_spent", type="string", description="耗时，如 '1h 30m' 或 '2d'", required=True
|
|||
|
|
),
|
|||
|
|
AgentToolParam(name="comment", type="string", description="工作日志说明", required=False),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
]
|
|||
|
|
|
|||
|
|
async def execute(self, tool_name: str, params: dict, context: dict) -> dict:
|
|||
|
|
account = context.get("account", {})
|
|||
|
|
if not account or not account.get("site_url"):
|
|||
|
|
return {"success": False, "error": "Jira 账户未配置"}
|
|||
|
|
|
|||
|
|
client = await self._get_client(account)
|
|||
|
|
|
|||
|
|
handlers = {
|
|||
|
|
"jira_search_issues": self._search_issues,
|
|||
|
|
"jira_get_issue": self._get_issue,
|
|||
|
|
"jira_create_issue": self._create_issue,
|
|||
|
|
"jira_transition_issue": self._transition_issue,
|
|||
|
|
"jira_get_transitions": self._get_transitions,
|
|||
|
|
"jira_assign_issue": self._assign_issue,
|
|||
|
|
"jira_update_issue": self._update_issue,
|
|||
|
|
"jira_get_comments": self._get_comments,
|
|||
|
|
"jira_search_users": self._search_users,
|
|||
|
|
"jira_get_projects": self._get_projects,
|
|||
|
|
"jira_delete_issue": self._delete_issue,
|
|||
|
|
"jira_get_changelog": self._get_changelog,
|
|||
|
|
"jira_add_worklog": self._add_worklog,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
handler = handlers.get(tool_name)
|
|||
|
|
if not handler:
|
|||
|
|
return {"success": False, "error": f"Unknown tool: {tool_name}"}
|
|||
|
|
|
|||
|
|
try:
|
|||
|
|
result = await handler(client, params)
|
|||
|
|
return {"success": True, "result": result}
|
|||
|
|
except httpx.HTTPStatusError as e:
|
|||
|
|
logger.exception("jira tool %s HTTP error", tool_name)
|
|||
|
|
body = e.response.json() if e.response.content else {}
|
|||
|
|
msg = body.get("errorMessages", [str(e)])[0] if isinstance(body, dict) else str(e)
|
|||
|
|
return {"success": False, "error": msg}
|
|||
|
|
except Exception as e:
|
|||
|
|
logger.exception("jira tool %s failed", tool_name)
|
|||
|
|
return {"success": False, "error": str(e)}
|
|||
|
|
|
|||
|
|
async def _search_issues(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
jql = params["jql"]
|
|||
|
|
max_results = min(params.get("max_results", 10), 50)
|
|||
|
|
resp = await client.post(
|
|||
|
|
"/rest/api/3/search",
|
|||
|
|
json={
|
|||
|
|
"jql": jql,
|
|||
|
|
"maxResults": max_results,
|
|||
|
|
"fields": ["summary", "status", "priority", "assignee", "issuetype", "created"],
|
|||
|
|
},
|
|||
|
|
)
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
data = resp.json()
|
|||
|
|
return {
|
|||
|
|
"total": data.get("total", 0),
|
|||
|
|
"issues": [
|
|||
|
|
{
|
|||
|
|
"key": i.get("key"),
|
|||
|
|
"summary": i.get("fields", {}).get("summary"),
|
|||
|
|
"status": i.get("fields", {}).get("status", {}).get("name"),
|
|||
|
|
"priority": i.get("fields", {}).get("priority", {}).get("name"),
|
|||
|
|
"assignee": i.get("fields", {}).get("assignee", {}).get("displayName"),
|
|||
|
|
"issue_type": i.get("fields", {}).get("issuetype", {}).get("name"),
|
|||
|
|
}
|
|||
|
|
for i in data.get("issues", [])
|
|||
|
|
],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def _get_issue(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
fields = "summary,description,status,priority,assignee,reporter,issuetype,created,updated,comment,labels"
|
|||
|
|
resp = await client.get(
|
|||
|
|
f"/rest/api/3/issue/{issue_key}",
|
|||
|
|
params={"fields": fields},
|
|||
|
|
)
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
data = resp.json()
|
|||
|
|
fields = data.get("fields", {})
|
|||
|
|
return {
|
|||
|
|
"key": data.get("key"),
|
|||
|
|
"summary": fields.get("summary"),
|
|||
|
|
"description": _adf_to_summary(fields.get("description")),
|
|||
|
|
"status": fields.get("status", {}).get("name"),
|
|||
|
|
"priority": fields.get("priority", {}).get("name"),
|
|||
|
|
"assignee": fields.get("assignee", {}).get("displayName"),
|
|||
|
|
"reporter": fields.get("reporter", {}).get("displayName"),
|
|||
|
|
"issue_type": fields.get("issuetype", {}).get("name"),
|
|||
|
|
"created": fields.get("created"),
|
|||
|
|
"updated": fields.get("updated"),
|
|||
|
|
"labels": fields.get("labels", []),
|
|||
|
|
"comments_count": len(fields.get("comment", {}).get("comments", [])),
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def _create_issue(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
fields: dict[str, Any] = {
|
|||
|
|
"project": {"key": params["project_key"]},
|
|||
|
|
"summary": params["summary"],
|
|||
|
|
"issuetype": {"name": params.get("issue_type", "Task")},
|
|||
|
|
}
|
|||
|
|
if params.get("description"):
|
|||
|
|
fields["description"] = markdown_to_adf(params["description"])
|
|||
|
|
if params.get("priority"):
|
|||
|
|
fields["priority"] = {"name": params["priority"]}
|
|||
|
|
|
|||
|
|
resp = await client.post("/rest/api/3/issue", json={"fields": fields})
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
data = resp.json()
|
|||
|
|
return {"key": data.get("key"), "id": data.get("id"), "url": data.get("self")}
|
|||
|
|
|
|||
|
|
async def _transition_issue(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
transition_name = params["transition_name"].lower()
|
|||
|
|
|
|||
|
|
trans_resp = await client.get(f"/rest/api/3/issue/{issue_key}/transitions")
|
|||
|
|
trans_resp.raise_for_status()
|
|||
|
|
transitions = trans_resp.json().get("transitions", [])
|
|||
|
|
|
|||
|
|
transition_id = None
|
|||
|
|
for t in transitions:
|
|||
|
|
if (
|
|||
|
|
t.get("name", "").lower() == transition_name
|
|||
|
|
or t.get("to", {}).get("name", "").lower() == transition_name
|
|||
|
|
):
|
|||
|
|
transition_id = t["id"]
|
|||
|
|
break
|
|||
|
|
|
|||
|
|
if not transition_id:
|
|||
|
|
available = [t.get("name") for t in transitions]
|
|||
|
|
return {
|
|||
|
|
"success": False,
|
|||
|
|
"error": f"Transition '{params['transition_name']}' not found. Available: {available}",
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
resp = await client.post(
|
|||
|
|
f"/rest/api/3/issue/{issue_key}/transitions", json={"transition": {"id": transition_id}}
|
|||
|
|
)
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
return {"transitioned": True, "issue_key": issue_key}
|
|||
|
|
|
|||
|
|
async def _get_transitions(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
resp = await client.get(f"/rest/api/3/issue/{issue_key}/transitions")
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
transitions = resp.json().get("transitions", [])
|
|||
|
|
return {
|
|||
|
|
"transitions": [
|
|||
|
|
{"id": t["id"], "name": t["name"], "to_status": t.get("to", {}).get("name")} for t in transitions
|
|||
|
|
],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def _assign_issue(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
account_id = params["account_id"]
|
|||
|
|
resp = await client.put(f"/rest/api/3/issue/{issue_key}/assignee", json={"accountId": account_id})
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
return {"assigned": True, "issue_key": issue_key, "account_id": account_id}
|
|||
|
|
|
|||
|
|
async def _update_issue(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
fields: dict[str, Any] = {}
|
|||
|
|
if params.get("summary"):
|
|||
|
|
fields["summary"] = params["summary"]
|
|||
|
|
if params.get("description"):
|
|||
|
|
fields["description"] = markdown_to_adf(params["description"])
|
|||
|
|
if params.get("priority"):
|
|||
|
|
fields["priority"] = {"name": params["priority"]}
|
|||
|
|
|
|||
|
|
if not fields:
|
|||
|
|
return {"success": False, "error": "No fields to update"}
|
|||
|
|
|
|||
|
|
resp = await client.put(f"/rest/api/3/issue/{issue_key}", json={"fields": fields})
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
return {"updated": True, "issue_key": issue_key}
|
|||
|
|
|
|||
|
|
async def _get_comments(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
max_results = min(params.get("max_results", 20), 100)
|
|||
|
|
resp = await client.get(f"/rest/api/3/issue/{issue_key}/comment", params={"maxResults": max_results})
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
data = resp.json()
|
|||
|
|
return {
|
|||
|
|
"total": data.get("total", 0),
|
|||
|
|
"comments": [
|
|||
|
|
{
|
|||
|
|
"id": c.get("id"),
|
|||
|
|
"author": c.get("author", {}).get("displayName"),
|
|||
|
|
"body": _adf_to_summary(c.get("body")),
|
|||
|
|
"created": c.get("created"),
|
|||
|
|
}
|
|||
|
|
for c in data.get("comments", [])
|
|||
|
|
],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def _search_users(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
query = params["query"]
|
|||
|
|
resp = await client.get("/rest/api/3/user/search", params={"query": query, "maxResults": 20})
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
users = resp.json() if isinstance(resp.json(), list) else resp.json().get("values", [])
|
|||
|
|
return {
|
|||
|
|
"users": [
|
|||
|
|
{
|
|||
|
|
"account_id": u.get("accountId"),
|
|||
|
|
"display_name": u.get("displayName"),
|
|||
|
|
"email": u.get("emailAddress"),
|
|||
|
|
"active": u.get("active"),
|
|||
|
|
}
|
|||
|
|
for u in users
|
|||
|
|
],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def _get_projects(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
resp = await client.get("/rest/api/3/project")
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
projects = resp.json()
|
|||
|
|
return {
|
|||
|
|
"projects": [
|
|||
|
|
{
|
|||
|
|
"key": p.get("key"),
|
|||
|
|
"name": p.get("name"),
|
|||
|
|
"project_type": p.get("projectTypeKey"),
|
|||
|
|
}
|
|||
|
|
for p in projects
|
|||
|
|
],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def _delete_issue(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
resp = await client.delete(f"/rest/api/3/issue/{issue_key}")
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
return {"deleted": True, "issue_key": issue_key}
|
|||
|
|
|
|||
|
|
async def _get_changelog(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
max_results = min(params.get("max_results", 20), 100)
|
|||
|
|
resp = await client.get(
|
|||
|
|
f"/rest/api/3/issue/{issue_key}/changelog",
|
|||
|
|
params={"maxResults": max_results},
|
|||
|
|
)
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
data = resp.json()
|
|||
|
|
return {
|
|||
|
|
"total": data.get("total", 0),
|
|||
|
|
"histories": [
|
|||
|
|
{
|
|||
|
|
"id": h.get("id"),
|
|||
|
|
"author": h.get("author", {}).get("displayName"),
|
|||
|
|
"created": h.get("created"),
|
|||
|
|
"items": [
|
|||
|
|
{
|
|||
|
|
"field": item.get("field"),
|
|||
|
|
"from": item.get("fromString"),
|
|||
|
|
"to": item.get("toString"),
|
|||
|
|
}
|
|||
|
|
for item in h.get("items", [])
|
|||
|
|
],
|
|||
|
|
}
|
|||
|
|
for h in data.get("values", [])
|
|||
|
|
],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def _add_worklog(self, client: httpx.AsyncClient, params: dict) -> dict:
|
|||
|
|
issue_key = params["issue_key"]
|
|||
|
|
body: dict[str, Any] = {"timeSpent": params["time_spent"]}
|
|||
|
|
if params.get("comment"):
|
|||
|
|
body["comment"] = markdown_to_adf(params["comment"])
|
|||
|
|
resp = await client.post(f"/rest/api/3/issue/{issue_key}/worklog", json=body)
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
data = resp.json()
|
|||
|
|
return {
|
|||
|
|
"worklog_id": data.get("id"),
|
|||
|
|
"issue_key": issue_key,
|
|||
|
|
"time_spent": params["time_spent"],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def _get_client(self, account: dict) -> httpx.AsyncClient:
|
|||
|
|
account_key = account.get("account_id", "default")
|
|||
|
|
if account_key not in self._clients:
|
|||
|
|
credentials = f"{account['email']}:{account['api_token']}"
|
|||
|
|
auth = f"Basic {base64.b64encode(credentials.encode('utf-8')).decode('utf-8')}"
|
|||
|
|
self._clients[account_key] = httpx.AsyncClient(
|
|||
|
|
base_url=account["site_url"].rstrip("/"),
|
|||
|
|
headers={"Authorization": auth, "Accept": "application/json"},
|
|||
|
|
timeout=httpx.Timeout(30.0),
|
|||
|
|
)
|
|||
|
|
return self._clients[account_key]
|
|||
|
|
|
|||
|
|
async def close(self):
|
|||
|
|
for client in self._clients.values():
|
|||
|
|
await client.aclose()
|
|||
|
|
self._clients.clear()
|
|||
|
|
|
|||
|
|
|
|||
|
|
def _adf_to_summary(adf: dict | None, max_len: int = 500) -> str:
|
|||
|
|
if not adf or not isinstance(adf, dict):
|
|||
|
|
return ""
|
|||
|
|
text = adf_to_plain_text(adf)
|
|||
|
|
if len(text) > max_len:
|
|||
|
|
return text[:max_len] + "..."
|
|||
|
|
return text
|