midagedev/gadak · 上手攻略

  • 仓库：midagedev/gadak
  • 链接：https://github.com/midagedev/gadak
  • 分类：开发者工具 · 本地知识库 · Jira/Confluence 同步
  • 作者：Jay
  • 更新：2026-08-30

这是什么

gadak 是一个把 Jira 和 Confluence 同步到本地 SQLite 文件的开发者工具。它的核心价值主张很简单：把远程 API 调用变成本地 SQL 查询，让"哪个 Epic 实际卡住了？"这种需要 GROUP BY 的问题，从"无法回答"变成一条 SQL。

支持 macOS 桌面 App、Web UI、CLI 和 MCP 服务器（供 AI 编码助手直接查询），开箱即用，无需账号。

解决什么问题

Jira REST API 的根本局限：它能给你行，但你拿不到聚合。JQL 没有 GROUP BY，所以每当你问"哪些 Epic 未完成且堆积最多？"这种问题时，API 的答案永远是"一页一页地遍历，然后自己算"——3296 个 issue 的站点，Open issues per epic 这个查询在 API 上要跑 4.7 秒，且代码里要写一个分页循环。

gadak 把整个 Jira（issues、comments、history）和 Confluence（wiki pages）全部镜像到一个 SQLite 文件，本地查询：

  • 简单过滤：19 ms vs REST API 583 ms（31×）
  • 带完整历史的 issue：28 ms vs REST API 710 ms（25×）
  • Free-text 搜索：41 ms vs REST API 543 ms（13×）
  • Open issues per epic（GROUP BY）：22 ms vs REST API 4.7 秒（214×）
  • Change history 聚合查询：API 不可表达（约 28 分钟 crawl），gadak 14 ms

⚠️ 性能数字来源 README，测量时间 2026-08-26，硬件为测量者本地环境，未控制变量，参考值请以实际部署环境为准。

快速安装

macOS（推荐：桌面 App + CLI）

# 桌面 App（含 CLI）
brew install --cask midagedev/tap/gadak

# 或 CLI only（Web UI 通过浏览器访问）
brew install midagedev/tap/gadak-cli

Windows

从 Releases 下载 gadak_<version>_windows_amd64.zip（或 windows_arm64），解压后把 gadak.exe 加入 PATH。

⚠️ Windows 桌面版未签名（是主动选择，非遗漏）。如果 SmartScreen 拦截，用 CLI zip 版本 + gadak serve 代替，不要关闭 Smart App Control。

Linux

从 Releases 下载 tarball，或从源码构建（参考 desktop/build-linux.sh）。

即开即用（在线 Demo）

不想安装？直接在浏览器里体验 Demo 快照（534 个 issue）：

👉 https://gadak.dev/demo/

核心用法

连接 Jira（首次同步）

# 交互式初始化，填写 Jira 站点、邮箱、API Token
gadak init

# 拉取 Jira 数据到本地 SQLite
gadak sync

# 启动 Web UI
gadak serve
# 输出类似：→ Listening on http://gadak.localhost:7777
# 浏览器打开即可看到本地 Jira 视图

API Token 在 https://id.atlassian.com/manage-profile/security/api-tlasses 生成，一个 Token 同时覆盖 Jira 和 Confluence。

离线独立模式（无需 Jira 账号）

# 完全本地，不连任何远程服务
gadak init --standalone

# 手动创建 issue
gadak create "the thing I just noticed"

# 启动 Web UI
gadak serve

CLI 查询（SQL 直接查）

# 哪个 Epic 未完成 issue 最多？（这是 API 根本回答不了的问题）
gadak sql "SELECT epic_key, COUNT(*) FROM issues_full \
  WHERE resolved_at IS NULL AND epic_key <> '' \
  GROUP BY epic_key ORDER BY 2 DESC"

# 自由全文搜索
gadak search "性能 优化"

# FTS（全文搜索）
gadak search --f ts "memory leak" --explain

# JQL 风格过滤
gadak search --jql "project = ENG AND status = Open AND assignee = currentUser()"

# Jira URL 直接查
gadak search https://your-company.atlassian.net/browse/PROJ-123

写操作（通过本地修改，自动同步回 Jira）

# 创建 issue
gadak create "New feature request"

# 评论
gadak comment PROJ-123 "This is now fixed in v2.1"

# 状态流转
gadak transition PROJ-123 --resolution Done

# 批量创建
gadak create --batch issues.csv

AI Agent 集成（MCP）

gadak 提供了 MCP 服务器，让 AI 编码助手直接用自然语言查 Jira：

# Claude Code 中安装 skill
gadak skill install

# 或 Claude Desktop（无 shell 环境）
gadak mcp install claude

安装后，Claude Code 可以直接问："这个 Epic 还有哪些 open 的子任务？"而不需要你写 JQL 或打开 Jira 界面。

桌面 App（macOS 推荐）

macOS 版 Gadak.app 是 Web UI 的独立窗口版，优势： - 不监听端口，无端口冲突 - App、CLI、Agent 可以同时读写同一个 SQLite（WAL 模式） - 启动两次会自动 focus 已有窗口

首次启动会引导你完成 Jira 连接配置，全程 GUI，无需终端。

典型适用场景

  1. Agent 辅助开发：AI 编码助手通过 MCP 查 Jira，在 code review 或 PR 描述中自动带入相关 issue 上下文
  2. 离线工作：飞机上、地铁里查 Jira，不依赖网络
  3. 数据聚合分析：谁分配最多任务？哪个 Epic 进展最慢？GROUP BY 在 Jira 里从来都不简单
  4. 团队知识库：Jira + Confluence 统一索引，⌘K 一个搜索框搞定 issue 和 wiki 页面
  5. 写 Jira 报告/自动化脚本：用 gadak sql 的输出接 Pipedream/Zapier/自有 pipeline

坑与注意

  1. 0.x 版本，生产谨慎：当前 v0.18，功能已验证，但尚未稳定，升级前看 CHANGELOG。
  2. 首次全量同步耗时：3296 个 issue 实测首次同步约 7.2 分钟；后续增量同步每次约 4.7 秒（Jira watch tick），这是网络调用成本。
  3. 一个 API Token 覆盖 Jira + Confluence：但必须是同一个 Atlassian 站点；如果 Jira 和 Confluence 在不同站点，需要分开配置。
  4. 镜像是缓存，不是源：gadak 数据可随时删除，Jira 永远是源。但写操作（comment、transition）会写回 Jira，不是本地只读。
  5. Windows 桌面版签名：未签名是主动决定（见 WINDOWS-SIGNING.md），不是漏签；如果担心 SmartScreen 误报，用 CLI 版本。
  6. Intel Mac 无 dmg：Release 只有 arm64 dmg，Intel Mac 需要从源码构建（desktop/build-app.sh）。
  7. Linux 无发布包：需要从源码构建 AppDir/AppImage，或用 CLI 模式。

与同类对比

工具 数据源 本地格式 CLI Agent/MCP 多站点
gadak Jira + Confluence SQLite ✅ ✅ ⚠️ 同站点
jira-cli Jira only 无 ✅ ❌ ✅
atlassian-python-api Jira only 无 ⚠️ 脚本 ❌ ✅
Notion API Notion 无 ⚠️ 脚本 ❌ ✅
手动导出 CSV Jira CSV ❌ ❌ ❌

gadak 核心差异：把 Jira 当数据库查，是唯一把 JQL 的缺失能力（GROUP BY、跨 issue 聚合）补回来的本地工具，且同时覆盖 Confluence。

⚠️ 注意：gadak 目前不支持跨 Jira 站点聚合（multi-instance），如果管理多个 Atlassian Cloud 站点，需要分别同步。

一句话推荐结论

如果你每天都在 Jira 里查东西、写脚本、做报告，或者在用 AI 编码助手做需要 Jira 上下文的开发，花 5 分钟装上 gadak——把 4.7 秒的 API 查询变成 22 ms 的 SQL，你不会再想切回浏览器。

最小可跑命令清单

# 环境：macOS/Windows/Linux（见安装）
# Jira 账号 + API Token（https://id.atlassian.com/manage-profile/security/api-tokens）
# 步骤（在线）：
gadak init          # 交互式配置 Jira 站点/邮箱/Token
gadak sync          # 首次全量同步（3296 issues 约 7 分钟）
gadak serve         # 启动 Web UI → http://gadak.localhost:7777
# 步骤（离线）：
gadak init --standalone
gadak create "note"
gadak serve
# CLI 查询（无需 serve 运行）：
gadak sql "SELECT epic_key, COUNT(*) FROM issues_full WHERE resolved_at IS NULL AND epic_key <> '' GROUP BY epic_key ORDER BY 2 DESC"

来源

  • 仓库：https://github.com/midagedev/gadak
  • 在线 Demo：https://gadak.dev/demo/
  • Benchmarks 原始数据：https://github.com/midagedev/gadak/blob/main/docs/BENCHMARKS.md
  • 桌面 App 文档：https://github.com/midagedev/gadak/blob/main/docs/DESKTOP.md
  • Recipes（SQL 示例）：https://github.com/midagedev/gadak/blob/main/docs/RECIPES.md
  • Changelog：https://github.com/midagedev/gadak/blob/main/CHANGELOG.md