Jira API工具

支持OAuth集成，通过JQL搜索、创建、更新Jira问题及管理看板，实现Jira API调用的自动化和效率提升。

功能说明: 本技能涵盖 化工作流场景 等核心能力。

Jira

安装步骤

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

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

适用范围

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

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

参数说明

参数名	类型	必填	说明
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

注意事项

• 需要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状态码和错误信息。您可以根据状态码和错误信息进行故障排除，并采取相应的解决措施。

安全提示

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. 逐步调试: 缩小问题范围,隔离故障模块