From a2738fb71aa669e8c5b804fb7bfe850c0ae6f538 Mon Sep 17 00:00:00 2001 From: Kaxi <1042864399@qq.com> Date: Fri, 17 Jul 2026 23:46:07 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20jira=5Fcli=20=E6=96=87?= =?UTF-8?q?=E7=AB=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/posts/jira-cli-intro/img/cover.svg | 1 + content/posts/jira-cli-intro/index.md | 261 +++++++++++++++++++++ 2 files changed, 262 insertions(+) create mode 100644 content/posts/jira-cli-intro/img/cover.svg create mode 100644 content/posts/jira-cli-intro/index.md diff --git a/content/posts/jira-cli-intro/img/cover.svg b/content/posts/jira-cli-intro/img/cover.svg new file mode 100644 index 0000000..85ca019 --- /dev/null +++ b/content/posts/jira-cli-intro/img/cover.svg @@ -0,0 +1 @@ +
jira_cli× AI Agent
 diff --git a/content/posts/jira-cli-intro/index.md b/content/posts/jira-cli-intro/index.md new file mode 100644 index 0000000..5c74121 --- /dev/null +++ b/content/posts/jira-cli-intro/index.md @@ -0,0 +1,261 @@ +--- +title: jira_cli — 把企业 Jira 装进命令行，AI Agent 直接调用 +published: 2026-07-17 +updated: 2026-07-17 +description: 介绍 jira_cli，一个开源的企业 Jira CLI 命令行工具和MCP，支持 Jira Server / Data Center，自带 MCP stdio server，让 Claude Code、Codex 等 AI 编程工具直接读写 Jira 任务。 +image: /posts/jira-cli-intro/img/cover.svg +tags: ['Jira', 'CLI', 'MCP', 'Go', 'AI Agent', '效率工具'] +difficulty: 入门 +--- + +## jira_cli 是什么 + +[jira_cli](https://github.com/wishesl/jira_cli) 是一个面向企业 Jira（Server / Data Center）的本地命令行工具，Go 语言编写，MIT 协议开源。它同时提供 **Cobra CLI** 和 **MCP stdio server** 两种入口，既能当日常命令行用，又能直接接入 AI 编程工具。 + +```bash +# CLI 日常使用 +jira_cli issue search "project = PROJ ORDER BY updated DESC" +jira_cli issue get PROJ-123 +jira_cli issue comment PROJ-123 "处理完成，请测试验证" + +# MCP 模式 — 给 AI 装上操作 Jira 的手 +jira_cli mcp --user=work +``` + +## 为什么需要它 + +大多数 Jira 命令行工具只解决"开发者手动操作 Jira"这一个场景。但 2026 年 AI 编程工具已经普及，你的 AI Agent（Claude Code、Codex、Cursor 等）也需要读写 Jira。痛点就来了： + +| 痛点 | jira_cli 怎么解 | +|------|---------------| +| 企业 Jira 在内网，没有公网 API | 本地 stdio MCP server，不经过外网 | +| AI 可能误删、误写 Jira 数据 | 账号级只读策略，AI 只能查不能改 | +| 团队多人多 Jira 实例 | 多 Profile 管理，`--user=work` 切换 | +| Windows 终端体验差 | 原生 `.exe` 构建 + 一键安装脚本 | +| AI 生成 JQL 困难 | 字段元数据发现：`field list --query xxx` | +| MCP 直接拿原始 JSON 太冗长 | 紧凑视图 + `--view summary` 减少 token 消耗 | + +## 安装 + +```bash +# 从源码安装（要求 Go 1.26.3+） +go install github.com/wishesl/jira_cli@latest + +# 或下载预编译二进制 +# https://github.com/wishesl/jira_cli/releases +``` + +Windows 用户下载 zip 包解压后双击 `install.bat` 即可全局安装，自动加入 PATH。 + +## 快速上手 + +### 1. 配置认证 + +```bash +# 设置 Jira 地址 +jira_cli set base-url https://jira.your-company.com --global + +# Token 认证（推荐） +jira_cli set token --global + +# 或用户名密码认证 +jira_cli set auth --global + +# 验证一下 +jira_cli user me +``` + +### 2. 日常使用 + +```bash +# 查自己今天的任务 +jira_cli issue search "assignee = currentUser() ORDER BY updated DESC" + +# 看某个任务详情 +jira_cli issue get PROJ-123 + +# 流转状态 +jira_cli issue transitions PROJ-123 # 可以转哪些 +jira_cli issue do-transition PROJ-123 21 # 执行流转 + +# 添加备注 +jira_cli issue comment PROJ-123 "已定位到问题，正在修复" + +# 创建任务 +jira_cli issue create PROJ Task --fields @fields.json +``` + +### 3. 配给 AI 使用 + +```bash +# 先配置一个只读账号给 AI 用 +jira_cli set base-url https://jira.your-company.com --name ai --global +jira_cli set token --name ai --global +jira_cli set readonly on --name ai --global +``` + +然后在 AI 工具的 MCP 配置里加上： + +```json +{ + "mcpServers": { + "jira": { + "command": "jira_cli", + "args": ["mcp", "--user=ai"] + } + } +} +``` + +这样 AI 就能查 Jira 但不能修改，既有了上下文，又不用担心误操作。 + +## 亮点 + +### 1. 账号级只读策略 + +这是 jira_cli 最实用的设计。给 AI Agent 配置只读账号： + +```bash +jira_cli set readonly on --name ai +``` + +只读模式下： +- CLI 写命令被隐藏和拒绝 +- MCP 的写入工具不会注册 +- 环境变量 `JIRA_READONLY=true` 也可以临时覆盖 + +AI 只能查 JQL、看任务、查字段、读评论，绝对不会误改数据。需要创建/更新时，另配一个有写入权限的账号由开发者自己操作。 + +### 2. 多 Profile 切换 + +一个配置文件里管理多个 Jira 账号，`--user` 切换： + +```bash +# 工作账号 +jira_cli set base-url https://jira.company.com --name work --global +jira_cli set token --name work --global + +# 个人账号 +jira_cli set base-url https://jira.personal.com --name personal --global +jira_cli set token --name personal --global + +# 使用时切换 +jira_cli --user=work issue search "project = PROJ" +jira_cli --user=personal issue search "project = SIDE" +``` + +同时支持**项目级配置**（`--local`）和工作目录绑定： + +```bash +# 在项目目录下，配置只对当前项目生效 +cd ~/projects/backend +jira_cli set base-url https://jira-backend.company.com --local +``` + +### 3. 对 AI 友好的输出 + +jira_cli 在输出设计上充分考虑了 AI Agent 的 token 消耗： + +```bash +# 紧凑视图 — 去掉 self/avatar/缩略图等无用字段 +jira_cli issue get PROJ-123 --view summary + +# 表格输出 — 一眼看到关键信息 +jira_cli issue search "project = PROJ" --output table + +# JSON 输出 — 程序解析，不转义 Unicode +jira_cli --output json issue get PROJ-123 + +# 自定义搜索列 — 只要需要的字段 +jira_cli set search-columns key,summary,fixVersions +``` + +### 4. 字段元数据发现 + +Jira 的 customfield 让人头疼，jira_cli 提供了完整的字段发现能力： + +```bash +# 列出所有字段及其类型 +jira_cli field list + +# 搜索包含特定关键词的字段 +jira_cli field list --query "版本" + +# 只看自定义字段 +jira_cli field list --custom-only + +# 创建任务前，先看看需要哪些字段 +jira_cli issue create-meta PROJ --issue-type Task + +# 分页查看可选值 +jira_cli issue create-meta-values PROJ Task priority --query High +``` + +### 5. MCP 写入控制 + +除了全局只读，MCP 还有更细粒度的控制： + +| 环境变量 | 作用 | +|----------|------| +| `JIRA_CREATE_OPEN=false` | 禁用创建/更新工具 | +| `JIRA_DISABLE_DISCLAIMER=true` | 去掉 AI 自动添加的备注声明 | +| `JIRA_CREATE_SUMMARY_MAX` | 限制摘要长度 | +| `JIRA_CREATE_DESCRIPTION_MAX` | 限制描述长度 | +| `JIRA_CREATE_FIELDS_MAX_BYTES` | 限制创建字段的 JSON 大小 | + +这些限制确保 AI 即使有写入权限也不会"失控"——例如防止 AI 往描述里塞几万字的废话。 + +### 6. 中英双语帮助 + +帮助信息默认中文，也支持一键切英文： + +```bash +# 保存英文偏好 +jira_cli set help-language en + +# 切回中文 +jira_cli set help-language zh + +# 临时覆盖 +jira_cli --lang en issue search -h +``` + +## 架构一览 + +``` +main.go + cmd/ CLI 命令、MCP 启动、访问策略 + internal/config/ 运行时配置、Profile 持久化 + internal/tools/jira_tools/ MCP 输入/输出适配层 + pkg/jira/ 可复用的 Jira REST 客户端 +``` + +设计原则清晰： + +- **`pkg/jira`** 是纯 Jira 客户端，HTTP、认证、上下文处理都在这里 +- **`cmd`** 只管 Cobra 解析和呈现 +- **`internal/tools/jira_tools`** 只管 MCP schema 验证和结果适配 +- **`internal/config`** 拥有 Profile 的全部逻辑，不分散到 cmd + +每一层职责单一，新增 Jira 能力时按 `endpoints.go → Client 方法 → CLI 命令 → MCP tool → 策略注册` 的路径走就行。 + +## 和已有方案的对比 + +| 方案 | 适合场景 | jira_cli 的区别 | +|------|---------|---------------| +| Atlassian Rovo MCP Server | Jira Cloud、官方 OAuth | jira_cli 是本地 stdio，适合内网 Server/DC | +| go-jira / jira-cli 社区版 | 纯命令行管理 | jira_cli 同时提供 MCP server，面向 AI 工作流 | +| 直接调 REST API | 自定义集成 | jira_cli 封装了认证、只读策略、字段元数据 | +| Jira 网页 | 日常使用 | jira_cli 把 Jira 变成终端里的一行命令 | + +## 总结 + +如果你的团队满足以下任一条件，jira_cli 值得一试： + +- 企业 Jira 部署在内网，想接入 AI 编程工具 +- 想给 AI Agent 只读权限来查 Jira 上下文 +- 需要命令行快速查看/操作 Jira，不想切浏览器 +- 需要管理多个 Jira 实例和多套账号 +- Windows 用户想要无摩擦的 CLI 体验 + +GitHub：[github.com/wishesl/jira_cli](https://github.com/wishesl/jira_cli) | MIT 协议 | Go 1.26.3+