Jira API工具

通过托管OAuth集成，支持JQL搜索、创建更新问题和管理看板，实现Jira操作自动化和高效API对接。

核心功能: 本技能提供化工作流场景等能力。

Jira

付费版进阶功能

能力	免费版	付费版
基础功能	支持	支持
代码静态分析与质量评分	不支持	支持
依赖漏洞检测与升级建议	不支持	支持
批量代码审查与报告生成	不支持	支持
CI/CD流水线集成	不支持	支持
代码复杂度可视化与重构建议	不支持	支持

功能能力

• Jira API integration with managed OAuth
• Search issues with JQL, create and update issues, manage

初始配置

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

适用范围

场景	输入	输出
搜索检索	关键词与过滤条件	匹配结果与相关性排序
Jira API托管	目标数据与配置参数	处理结果与执行状态
JQL搜索	目标数据与配置参数	处理结果与执行状态

不适用于：需要人工判断的复杂决策场景

使用指南

详细内容已移至 references/detail.md

参数说明

参数名	类型	必填	说明
content	string	否	jira-api处理的内容输入
mode	string	否	处理模式, 可选: json/text/markdown,
max_retries	integer	否	单步最大重试次数, 默认: 2
skip_steps	array	否	跳过的步骤编号(用于断点续传), 默认: []

输出说明

json

{
  "success": true,
  "data": {
    "final_result": {
      "api_result": "api_result_value",
      "api_metadata": "api_metadata_value",
      "api_status": "api_status_value"
    },
    "execution_log": [
      {
        "step": 1,
        "name": "按流程执行",
        "status": "completed",
        "duration_ms": 1200,
        "output_summary": "按流程执行"
      },
      {
        "step": 2,
        "name": "按流程执行",
        "status": "completed",
        "duration_ms": 3500,
        "output_summary": "按流程执行"
      },
      {
        "step": 3,
        "name": "按流程执行",
        "status": "completed",
        "duration_ms": 2100,
        "output_summary": "按流程执行"
      },
      {
        "step": 4,
        "name": "按流程执行",
        "status": "completed",
        "duration_ms": 800,
        "output_summary": "按流程执行"
      }
    ],
    "total_duration_ms": 7600,
    "gates_passed": 3,
    "gates_total": 3
  },
  "error": null
}

中间产物模板参考: assets/jira-api_template

错误恢复

Status	Meaning
400	Missing Jira connection or invalid JQL
401	Invalid or missing Maton API key
429	Rate limited (10 req/sec per account)
4xx/5xx	Passthrough error from Jira API

错误恢复步骤

CLI:

1. Check your auth state:

bash

maton whoami

2. Verify the API key is valid by listing connections:

bash

maton connection list

Manual:

1. Check that the MATON_API_KEY environment variable is set:

bash

echo $MATON_API_KEY

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with jira. For example:

• Correct: https://api.maton.ai/jira/ex/jira/{cloudId}/rest/api/3/project
• Incorrect: https://api.maton.ai/ex/jira/{cloudId}/rest/api/3/project

处理方式: 参考上表中的错误场景说明,按照对应建议进行处理和恢复.

安装与配置

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux

依赖说明(补充)

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

可用性分类

• 分类: MD+execute()
• 说明: 基于Markdown的AI Skill,

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

案例展示

CLI

bash

maton jira cloud list
# ...
maton jira issue search 'project = PROJ AND status = "In Progress"' --cloud-id abc-123
# ...
maton jira issue search 'project = PROJ' --cloud-id abc-123 \
  --json --jq '.issues | map(select(.fields.status.name == "In Progress"))'
# ...
maton jira issue create --cloud-id abc-123 --project PROJ --summary 'Fix login'

JavaScript

javascript

// Get cloud ID first
const resources = await fetch(
  'https://api.maton.ai/jira/oauth/token/accessible-resources',
  { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } }
).then(r => r.json());
// ...
const cloudId = resources[0].id;
// ...
// Search issues
const issues = await fetch(
  `https://api.maton.ai/jira/ex/jira/${cloudId}/rest/api/3/search/jql?jql=project=KEY`,
env.MATON_API_KEY}` } }
).then(r => r.json());

Python

问答汇总

Q1: 如何开始使用Jira？

A: 请参考使用流程和依赖说明章节，确保运行环境满足要求后调用本技能。

注意事项

• 需要API Key，无Key环境无法使用

创新优势

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
搜索特定Jira问题	30分钟	5分钟	25分钟	5%
创建新问题	15分钟	2分钟	13分钟	10%
更新现有问题	20分钟	3分钟	17分钟	8%
批量修改问题状态	2小时	30分钟	1小时30分钟	3%
自动生成报告	4小时	1小时	3小时	7%
集成Webhook通知	2小时	30分钟	1小时30分钟	5%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
易用性	高	低	中	高
功能丰富度	高	低	中	高
成本	低	高	中	高
扩展性	高	低	中	高
学习曲线	中	高	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
手动操作效率低	Jira问题管理需要大量手动操作，耗时且容易出错。	整个团队效率	自动化处理，减少人工操作。	时间节约20%
数据同步困难	不同系统间的数据同步需要大量手动操作。	数据准确性	API集成，实现自动同步。	准确率提升5%
问题追踪困难	问题追踪需要跨多个系统，难以统一管理。	问题解决效率	Jira API集成，实现问题追踪。	效率提升10%

常见问题FAQ

Q1: 如何配置Jira API工具？

A: 首先，您需要在Jira系统中创建OAuth应用以获取客户端ID和客户端密钥。然后，使用这些凭据配置Jira API工具，确保它能够与您的Jira实例进行安全通信。

Q2: JQL搜索功能如何使用？

A: JQL搜索是Jira查询语言，用于搜索特定的问题。您可以在Jira API工具中输入JQL查询语句，如project = "MyProject" AND status = "Open"，来搜索特定项目中的开放状态的问题。

Q3: 如何创建和更新问题？

A: 使用Jira API，您可以通过发送HTTP请求来创建和更新问题。创建问题通常涉及发送POST请求，而更新问题则是通过发送PUT请求。

Q4: Jira API工具支持哪些操作？

A: Jira API工具支持多种操作，包括搜索、创建、更新、关闭和删除问题，以及管理看板和版本。

Q5: 如何处理Jira API工具返回的错误？

A: 当Jira API工具遇到错误时，它会返回相应的HTTP状态码和错误信息。您可以根据状态码和错误信息进行故障排除，并采取相应的解决措施。

排障手册

错误现象	可能原因	诊断步骤	解决方案
无法连接到Jira	网络问题或Jira服务不可用	检查网络连接和Jira服务状态	确保网络连接正常，并尝试重新连接Jira
JQL查询无结果	JQL查询错误或数据问题	检查JQL查询语法和数据	修正JQL查询，确保数据正确
创建问题失败	权限问题或数据格式错误	检查权限和数据格式	确保用户有足够的权限，并检查数据格式
更新问题失败	问题不存在或权限问题	检查问题ID和权限	确保问题存在，并检查用户权限
API响应时间过长	网络延迟或Jira服务问题	检查网络延迟和Jira服务状态	确保网络连接良好，并联系Jira支持

安全提示

1. 确保使用强密码和安全的OAuth密钥。
2. 限制API访问权限，仅允许必要的操作。
3. 定期检查和更新API密钥和访问令牌。
4. 避免在公共或不安全的网络上发送敏感信息。
5. 监控API使用情况，以便及时发现异常活动。

安全风险防范

风险项	等级	防护措施	验证方法
未授权访问	高	实施OAuth 2.0授权	定期检查授权状态
数据泄露	高	加密敏感数据	定期进行安全审计
恶意软件	中	使用防病毒软件	定期更新和扫描
网络钓鱼	中	教育用户识别钓鱼攻击	定期进行安全意识培训
拒绝服务攻击	高	实施流量监控和限制	使用防火墙和流量分析工具

功能介绍

• 自动化执行: Jira API托管OAuth集成,JQL搜索/建改issue/管看板。Jira API integration wit
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

Jira API工具通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

Jira API工具通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块