Jira 工具箱（免费版）

概述

本 Skill 帮助 Agent 通过托管 OAuth 认证访问 Jira Cloud API，完成 JQL 搜索、议题查看、项目列表等只读操作。免费版聚焦个人开发者与小团队的"查询与浏览"场景：无需手动管理 OAuth 令牌，通过统一的 API 代理自动注入认证，降低接入门槛。所有写操作（创建、更新、删除、流转）需使用专业版。

核心能力

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：只读集成、查看议题与项目列、核心能力、通过托管、认证访问、API、支持字段过滤与分、议题类型与状态、多连接管理与等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

1. 站会前快速拉取进行中议题：用 JQL project = PROJ AND status = "In Progress" ORDER BY updated DESC 拉取最近更新的议题，作为站会发言素材。
2. 个人议题进度自查：开发者查询分配给自己的议题，按优先级排序，规划当日工作。
3. 项目元数据浏览：项目经理查看项目列表、议题类型、状态流转定义，了解项目配置。
4. 自动化只读采集：CI/CD 流水线中读取议题状态，决定是否触发下游任务。

不适用场景

以下场景Jira工具箱(免费版)不适合处理：

• 逆向工程闭源API
• API安全渗透测试
• 非标准协议集成

触发条件

需要API集成、接口对接、Webhook配置、系统连接时使用。不适用于非本工具能力范围的需求。

快速开始

上手时间：< 120 秒。需先安装 CLI 并完成 OAuth 连接。

依赖详情

npm install -g @maton/cli

或使用 Homebrew：

brew install maton-ai/cli/maton

Step 2：登录并创建 Jira 连接

maton login                          # 浏览器打开获取 API Key
maton connection create jira          # 创建 Jira OAuth 连接，浏览器完成授权

Step 3：获取 cloud-id

Jira Cloud 需要 cloud-id，先获取可访问资源：

maton jira cloud list

返回示例：

[{
  "id": "62909843-b784-4c35-b770-e4e2a26f024b",
  "url": "https://yoursite.atlassian.net",
  "name": "yoursite"
}]

Step 4：JQL 搜索议题

maton jira issue search 'project = PROJ AND status = "In Progress"' --cloud-id abc-123 --limit 20 --fields summary,status,assignee

示例

认证方式

常用只读命令

JQL 常用示例

最佳实践

1. 先取 cloud-id：所有操作都需要 cloud-id，建议缓存避免重复请求。
2. JQL 必须有界：始终包含 project=KEY 限定范围，避免全库扫描触发性能问题。
3. 字段过滤减负：--fields summary,status,assignee 只取需要的字段，降低响应体积与速率消耗。
4. URL 编码 JQL：直接调用 REST API 时 JQL 参数需 URL 编码（%3D 等）。
5. 分页控制：--limit 控制单次返回条数，默认 20，建议不超过 50。
6. 多连接显式指定：多个 Jira 账号时务必 --connection <id> 指定，避免请求到错误账号。
7. curl 用 -g：URL 含方括号（fields[]）时用 curl -g 禁用 glob 解析。

常见问题

Q1：报 401 Invalid API key 怎么办？

A：(1) 运行 maton whoami 检查登录状态；(2) 重新 maton login；(3) 确认 MATON_API_KEY 环境变量已设置且未过期。

Q2：报 400 Missing Jira connection？

A：未创建 Jira OAuth 连接。运行 maton connection create jira，在浏览器完成授权。

Q3：报 429 Rate limited？

A：Jira Cloud 限制 10 请求/秒/账号。建议：(1) 降低查询频率；(2) 加 --limit 减少单次返回；(3) 缓存结果复用。

Q4：JQL 报错语法错误？

A：(1) 字符串值用双引号包裹（status = "In Progress"）；(2) 字段名区分大小写；(3) 使用 URL 编码（%3D 表示 =）。

Q5：免费版能否创建/更新议题？

A：免费版仅支持只读操作。创建、更新、删除、流转等写操作需使用专业版。

已知限制

本免费体验版限制以下高级功能：

• 创建议题（专业版支持）
• 更新/删除议题（专业版支持）
• 流转议题状态（专业版支持）
• 评论管理（专业版支持）
• 用户搜索（专业版支持）
• 批量操作与自动化工作流（专业版支持）
• 多连接高级管理与优先支持（专业版支持）

解锁全部功能请使用专业版：jira-api-toolkit-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• Node.js：16+（用于运行 CLI）

第三方依赖

API Key 配置

• maton API Key：通过 maton login 获取，存储于环境变量 MATON_API_KEY，禁止硬编码
• Jira OAuth 连接：通过 maton connection create jira 在浏览器完成授权，无需手动管理令牌
• 禁止：在 SKILL.md 或脚本中硬编码 API Key 与 OAuth 令牌

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分功能需要 exec 命令行执行能力）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 执行任务，仅支持只读操作

错误处理