gadak

在待办列表中找到线索。

_{English · 한국어 · 日本語}

使用 SQL 查询 Jira 待办列表。

gadak 会将你选择的 Jira Cloud 项目和 Confluence 空间（问题、 评论、历史记录、Wiki 页面）镜像到你设备上的一个 SQLite 文件中， 统一建立索引，并支持离线搜索。你可以通过 桌面应用、浏览器标签页（gadak serve）、命令行或 MCP 使用镜像。 写入会先提交到 Jira。一个二进制文件，无需 gadak 账户。这是由一位维护者开发的 0.x 软件；状态与承诺 见下文。Atlassian 自家的 Rovo MCP 服务由云端托管，无需安装任何内容， 但没有聚合工具，也无法离线读取；相关取舍见 替代方案与先前工作。

▶  打开在线演示  ·  534 个问题，现在即可在浏览器中体验。
更新日志  ·  已发布的内容。

使用 SQL 查询 Jira

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"

JQL 不支持 GROUP BY。此查询会统计每个史诗中尚未解决的问题；REST API 会返回各行数据，并将计数工作留给你。Datasette Lite 会在你的浏览器中 对演示快照运行此查询， 无需安装任何内容。更多 JQL 无法回答的问题，可用 SQL 查询： docs/RECIPES.md。

于 2026-08-26 在一个实时 Cloud 站点上测得（3,296 个问题；中位数，包含命令行启动时间）：

问题	REST API	gadak
简单筛选，100 个问题	583 ms	19 ms	31×
单个问题及其完整历史记录	710 ms	28 ms	25×
全文搜索	543 ms	41 ms	13×
按史诗统计未解决的问题（GROUP BY）	4,761 ms — 本次测量中需调用 8 个 API 页面，并在客户端聚合	22 ms — 一次查询	214×
对变更历史进行计数	无原生聚合功能 — 需约 28 分钟遍历历史记录并在客户端计数	14 ms	—

测量方法、重新测量记录，以及 gadak 表现较慢的项目（首次完整同步、 安静站点上的监视器轮询、一个同步间隔的陈旧数据）见 docs/BENCHMARKS.md。

▶ 20 秒列表演示（GIF）

_{20 秒了解这个窗口。根据演示快照，通过 e2e/demo/web-demo.spec.ts 生成。}

## 安装

macOS 应用，包含 CLI：

brew install --cask midagedev/tap/gadak

仅 CLI，适用于 macOS 或 Linux。通过 gadak serve 打开的同一界面会显示在浏览器标签页中：

brew install midagedev/tap/gadak-cli

连接到 Jira Cloud，然后打开 gadak serve 输出的地址（http://gadak.localhost:7777）。首次同步会在 serve 中运行，先同步最新的问题；同步过程中，列表会逐渐填充：

gadak init && gadak serve         # mirror a Jira Cloud site
gadak init --local && gadak serve # no Jira — start on the tracker gadak ships with

每个站点需要一个 API token，即一个不设作用域的用户令牌；它适用于同一站点上的 Jira 和 Confluence，镜像会显示你的账户可见的内容。由你选择镜像的内容：Jira 使用 --projects，Wiki 使用 --spaces；除非你指定空间，否则 Wiki 会保持关闭。Jira Server 和 Data Center 使用 gadak init --server 和个人访问令牌进行连接；此时 Wiki 会保持关闭（没有 Confluence Server 客户端）。

gadak init --projects ENG,PROD --spaces ENG

**Windows：**桌面应用可在 Microsoft Store 获取。Store 会为应用签名，因此 SmartScreen 和 Smart App Control 都不会拦截；通过 Store 安装也会将 gadak 命令加入 PATH（自 0.20.2 起）。如需不通过 Store 安装 CLI，请从最新版本下载 gadak_<version>_windows_amd64.zip（或 arm64），解压后将 gadak.exe 放入 PATH。版本发布中的桌面版压缩包（Gadak-<version>-windows-x64.zip）仍未签名，SmartScreen 在此拦截是因为缺少签名，而非发现病毒（原因）。如果遭到拦截，请从 Store 安装，不要关闭 Smart App Control。

窗口会跟随浏览器或操作系统的语言（英语、韩语或日语；可在设置中切换）。已签名的 dmg、Linux tarball、Docker、升级方式：docs/INSTALL.md。

其他工作区。gadak --workspace <new> migrate --from <old> 可将已同步的工作区迁移到另一个源；添加 --to linear 可将目标设为 Linear 团队。第二台设备可与家中的 serve 配对：gadak --workspace laptop init --pairing-code-stdin。

数据和网络

• **复制多少内容。**你指定的 Cloud 项目和空间，与你的账户所见内容一致；gadak 不会提升权限，也不会使用服务账户。
• **哪些内容留在本地，以及数据有多新。**一个 SQLite 文件。首次完整同步耗时最长：基准站点（3,514 个问题和 462 个页面）耗时 3.7 分钟。之后，gadak serve 默认每 60 秒同步一次（syncIntervalSec），并每小时执行一次对账，移除你已无法查看的问题。读取的数据会比 Jira 延迟一个同步间隔。
• 令牌存放位置。~/.gadak/config.json，权限模式为 0600。凭据不会进入 SQLite、日志或快照。
• **哪些内容会离开设备。**没有遥测数据。gadak 只与已配置的服务通信；SECURITY.md 列出了完整清单， docs/NETWORK.md 逐一说明每个连接及其关闭方式。以下四种读取仍会请求 Jira：查看附件、gadak issue --editmeta、gadak fields 和 gadak api（透传）。
• **写入会做什么。**写入会先发送到 Jira；Jira 接受后，镜像才会刷新。Jira 拒绝的写入会立即失败。不会将任何内容排入队列。
• **使用 Agent 后有什么变化。**Agent 会将读取的内容发送给其模型；请参阅 Agent。

**镜像是可随时丢弃的缓存。**删除目录不会丢失任何内容。

Agents

让你的编码 Agent 通过命令行或 MCP 查询同一个镜像。参考： docs/MIRROR.md；每个主机只需粘贴一次： docs/AGENT_SETUP.md。

gadak skill install

这会为 Claude Code 复制一个 SKILL.md，且不会启动任何进程；Agent 会运行短时的 gadak 命令。指定另一个主机，即可在那里安装同一个文件： gadak skill install codex，agents、cursor、 gemini、opencode 和 grok 也同样适用。对于没有 shell 的 Claude Desktop，将同一个镜像注册为 MCP 服务（gadak mcp install claude 是 Claude Code 的注册命令；Claude Desktop 不会看到它）：

gadak mcp install claude-desktop

_{shell 位于窗口中（⌘K → Terminal，或 Ctrl+`）。gadak claim 将面板绑定到该事项，在其中启动的 Claude Code 会话会筛选列表，然后在同一窗口中保存并打开仪表板。除两条提示词外，其他操作都没有脚本自动执行；Agent 工作期间的片段采用了延时摄影。韩文和日文 README 也以各自语言记录了同一体验。录制自 e2e/demo/terminal-claude-demo.spec.ts，通过 record-terminal-claude.sh 完成。}

两条规则最为重要。请使用 status_category 和 priority_rank 进行筛选，而不是显示名称：Jira 会针对不同账户翻译这些名称， 因此在韩语站点上，priority = High 会悄无声息地返回零行。并且请在 gadak 窗口中打开查询返回的事项： gadak sql --no-header "…" | gadak views open --keys - 会将 Agent 的答案 显示在你的屏幕上，而 gadak views open --jql '…' 会将粘贴的 JQL 转换为标签。

写入操作（create、edit、comment、transition、claim、link 和 wiki 的 page 动词）会先发送到源端，再刷新镜像。在 Jira 和 Linear 上，Agent 的评论和创建的事项都会显示其名称（关闭此功能： gadak config set actor.trailer false）。在内置跟踪器中， 机器前的用户也会显示为署名者：gadak me set "Your Name" 会让其本人署名自己 执行的写入操作。

读取镜像的 Agent 会将读取到的内容发送给它所使用的模型。 gadak 本身不会发送任何内容。请将镜像范围限定为 Agent 应该看到的内容。

手机应用（测试版）

iOS 应用通过你自己的网络连接到你已运行的 gadak serve。 无需 gadak 账户，也没有中间托管服务。缓存中有什么，手机上就显示什么：字段、附件、关联问题、Wiki 页面、当前冲刺及之前的所有冲刺。要说什么，手机就先写入源系统，和桌面端的做法一样：评论、标签、截止日期、照片，或一个归属某个史诗的问题。编辑页面或自定义字段、编写视图、布局仪表板和移动卡片仍需在桌面端完成，应用会在相应控件所在的位置说明这一点。

_{一次演示中的写入部分——完整片段可在网站上播放，因为 GitHub 的 Markdown 不支持 <video>。这里没有任何预先安排：演示快照作为独立跟踪器提供服务，因此每次写入都会生效。}

**测试版，仅此而已。**构建版本会发布到 TestFlight，供内部测试人员使用，目前没有公开下载。App Store 上架还在等待一种方式，让审核人员无需加入你的网络即可查看应用。

数据源与限制

四种数据源，一套操作：Atlassian Cloud、Jira Server / Data Center（gadak init --server 和 Personal Access Token）、Linear（工作区配置中的 "linear" 区块，以及 gadak sync --source linear），还有随应用提供的内置跟踪器。四种数据源都支持读取、写入、层级结构、附件、历史记录和看板布局；有 Wiki 的三种数据源也支持 Wiki。每种数据源不支持的功能，以及每个单元格背后的代码引用，见： docs/SUPPORT_MATRIX.md。有三项功能在所有数据源上都不可用，只能在 Jira 中使用：作为界面的冲刺、Jira 仪表板，以及 Jira 通知收件箱。

**适用 / 不适用场景。**适合降低日常搜索延迟、同时基于跟踪器和 Wiki 使用 Agent，以及离线读取。若要进行冲刺规划、管理、在界面中编辑页面，或无法容忍一分钟的数据延迟：请继续使用 Jira。 docs/CONCEPT.md。

**工作原理。**单个二进制文件、单个 SQLite 文件；增量同步加一次校准：docs/ARCHITECTURE.md。为什么选择本地进程，而不是扩展或 Forge 应用： docs/decisions/0003-local-process.md。 配置、扩展数据和 SQL 让你无需派生项目即可按需定制： docs/EXTENDING.md。

替代方案与先前项目

jira-cli 每条命令都会调用实时 API。Rovo MCP 由 Atlassian 托管，可搜索 Jira 和 Confluence；它提供写入工具，但没有原生聚合工具，也不支持离线读取。gadak 对本地镜像运行 SQL，代价是需要本地二进制文件和首次同步；读取来自你的磁盘，因此不会受到速率限制，而你信任的是一位采用 Apache-2.0 许可的维护者，而不是 Atlassian。该领域的早期项目包括 Scrumdog、jira-offline 和 jira-cache；gadak 将本地 Jira 和 Confluence 镜像与 SQL、桌面端和浏览器界面、CLI 及 MCP 结合起来。 docs/FAQ.md。

状态、兼容性与维护

状态：0.24，仍处于 0.x 阶段。 同步、读取 API、写入直通、桌面应用、Web、命令行和 MCP 均已通过实时站点验证。目前项目由一位维护者维护。在 0.x 阶段，我们承诺兼容以下三项，详见 specs/000-product/data-model.md：issues_full 和 RECIPES 查询、gadak sql 的标准输出，以及 gadak views open --keys -。项目采用 Apache-2.0 许可证，镜像是普通的 SQLite。名称来自韩语： gadak（가닥）意为一缕——从纠缠中抽出的一根线。你无需盲目信任的内容，以及用于验证各项承诺的命令： docs/PROMISES.md。

文档

• CHANGELOG.md：已发布的内容
• docs/INSTALL.md · docs/DESKTOP.md：安装、首次运行、桌面应用
• SECURITY.md · docs/NETWORK.md：威胁模型、每个连接及其关闭方式
• docs/MIRROR.md · docs/MCP.md · docs/AGENT_SETUP.md：SQL、CLI、REST、MCP，以及各主机的一次粘贴式配置
• docs/RECIPES.md · docs/DASHBOARDS.md：JQL 无法提出的问题，用 SQL 解答；由 Agent 编写的仪表盘
• docs/SHOWCASE.md：窗口、启动器，以及 Agent 如何操控二者，均有视频记录
• docs/FAQ.md · docs/MAINTENANCE.md：站点负载、比较、维护者介绍
• docs/README.md：其余文档

反馈与贡献

如果你在自己的项目中使用了 gadak，请创建一个 GitHub issue，或发送邮件至 [email protected]：它回答了什么问题？你之后是否再次使用？欢迎先分享日常使用体验，再参与贡献。

请勿在公开 issue 中包含真实的 issue 数据、令牌和站点 URL。Bug 报告需要注明你的 Jira 部署类型（Cloud 或 Server）、gadak 提交版本以及运行的命令。维护者会将 issue 镜像到 公开待办列表，其中提交版本 GDK-nnn 可用于定位。

参与贡献：.github/CONTRIBUTING.md 和 docs/project/GOOD_FIRST_ISSUES.md。下一批功能为何如此安排及其参考资料： docs/project/THEORY.md。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。