新增 jira_cli 文章

content/posts/jira-cli-intro/img/cover.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1067" height="600" viewBox="0 0 1067 600" style="max-width:100%;height:auto;cursor:default;"><defs><pattern id="checkerboard" width="20" height="20" patternUnits="userSpaceOnUse"><rect width="10" height="10" fill="#e0e0e0"/><rect x="10" y="0" width="10" height="10" fill="#ffffff"/><rect x="0" y="10" width="10" height="10" fill="#ffffff"/><rect x="10" y="10" width="10" height="10" fill="#e0e0e0"/></pattern></defs><rect width="100%" height="100%" fill="url(#checkerboard)"/><rect width="100%" height="100%" fill="rgba(255, 255, 255, 1)"/><foreignObject x="0" y="0" width="100%" height="100%" style="pointer-events:none;"><div xmlns="http://www.w3.org/1999/xhtml" style="width: 100%; height: 100%; display: flex; align-items: center; justify-content: center; gap: 24px; font-family: sans-serif; font-weight: 700;"><div style="order: 0; width: 127px; height: 127px; display: flex; align-items: center; justify-content: center; background-color: #2684FF; border-radius: 24px;"><div style="max-width: 107px; max-height: 107px; flex-shrink: 0; color: #ffffff; display: flex; align-items: center; justify-content: center; border-radius: 0%; overflow: hidden;"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="100%" height="100%" preserveAspectRatio="xMidYMid meet"><path fill="#ffffff" d="M12 2C6.477 2 2 6.477 2 12s4.477 10 10 10s10-4.477 10-10S17.523 2 12 2m4.49 9.04l-.006.014c-.42.898-1.516 2.66-1.516 2.66l-.005-.012l-.32.558h1.543l-2.948 3.919l.67-2.666h-1.215l.422-1.763a17 17 0 0 0-1.223.349s-.646.378-1.862-.729c0 0-.82-.722-.344-.902c.202-.077.981-.175 1.595-.257a80 80 0 0 1 1.338-.172s-2.555.039-3.161-.057c-.606-.095-1.375-1.107-1.539-1.996c0 0-.253-.488.545-.257s4.101.9 4.101.9S8.27 9.312 7.983 8.99c-.286-.32-.841-1.754-.769-2.634c0 0 .031-.22.257-.16c0 0 3.176 1.45 5.347 2.245s4.06 1.199 3.816 2.228c-.02.087-.072.216-.144.37"/></svg></div></div><span style="order: 1; font-size: 72px; color: #2684FF; text-shadow: 0px 0px 0px rgba(0, 0, 0, 0); line-height: 1; white-space: nowrap;">jira_cli</span><span style="order: 2; font-size: 48px; color: #555555; text-shadow: 0px 0px 0px rgba(0, 0, 0, 0); line-height: 1; white-space: nowrap;">× AI Agent</span></div></foreignObject></svg>

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 <your-token> --global
+
+# 或用户名密码认证
+jira_cli set auth <username> <password> --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 <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 <work-token> --name work --global
+
+# 个人账号
+jira_cli set base-url https://jira.personal.com --name personal --global
+jira_cli set token <personal-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+