基于 Git 的分布式 Issue Tracker：Epiq 工程实践解析

在团队协作场景中，Issue 追踪系统通常是集中式 SaaS 的天下：Jira 需要账号体系，GitHub Issues 依赖平台服务，Linear 需要网络连接。然而当网络不可达、需要在多个 Git 远程仓库间保持一致状态、或者希望将 Issue 与代码提交历史统一版本化管理时，传统方案就显得笨重。Epiq 作为一种新兴的分布式 Git-backed Issue Tracker，给出了不同的工程思路：把 Issue 数据完全存入 Git 分支，用纯终端的 TUI 界面操作，以事件溯源模式保证状态一致性，并通过 MCP 协议让 AI Agent 直接读写 Issue。

核心理念：让 Issue 成为 Git 的一等公民

Epiq 的设计哲学可以概括为「Repo-native」——Issue 不是附加在平台侧元数据，而是直接存在于代码仓库内部。初始化时，Epiq 在仓库中创建一个专门的状态分支，默认命名为 epiq/state。Issue 的每次变更（创建、移动标签、关闭、评论）都以追加事件的形式写入这个分支的 JSON 文件。这意味着 Issue 历史天然具备 Git 的全部能力：可审查、可回退、可分支实验、可以通过 standard push/pull 与任何 Git 远程同步。

这种设计带来的工程收益是显著的。团队可以在同一远程仓库下协作，无需额外部署数据库或账号系统；离线状态下可以继续操作 Issue，回连后一键同步；审计日志不需要依赖外部服务，直接在仓库中 git log 即可查看。在 monorepo 场景下，多个子项目的 Issue 可以共享同一个 Git 历史，跨仓库 Issue 关联只需通过 commit reference 实现。

事件溯源架构的技术实现

Epiq 采用纯事件溯源（Event Sourcing）而非传统的关系型或文档型存储。每一张 Issue 从创建到关闭，整条生命周期被建模为一系列不可变事件。事件结构大致包含 type（如 IssueCreated、LabelAdded、StatusChanged）、timestamp、user_id、payload 等字段。状态重建时，系统从事件日志头部按顺序重放，得出当前状态。

这种模型天然支持时间旅行查询：任意时刻的 Issue 状态只需回溯到对应 commit 的快照即可还原，而无需额外快照表。冲突处理也因此变得优雅 —— 不同用户在不同分支上追加的事件最终通过 Git merge 合并，Epiq 在内存中重放事件日志，自动解决无冲突的并发写入。只有真正语义冲突（如同一 Issue 被两人同时标为不同状态）才会暴露给用户人工解决。

工程实现上，Epiq 将事件日志存储为 JSON Lines 格式（.epiq/events.jsonl），每行一条事件。这种格式既保证了流式追加的写入效率，又避免了 JSON 数组整体解析的内存开销。Git diff 对单行追加格式极为友好 —— 每次 Issue 操作在 git diff 中仅显示新增的一行变更，非常适合 code review 场景。

ASCII TUI 的交互设计

终端界面是 Epiq 的核心用户交互层。它不依赖浏览器或 GUI，而是直接在终端渲染 ASCII 风格的 Kanban 看板。每个 Issue 被渲染为一列卡片，包含标题、标签、状态泳道（Backlog、In Progress、Done 等）。导航采用 Vim 的 hjkl 按键映射：h/l 在列之间切换，j/k 在卡片之间上下移动。

这种交互设计的工程价值在于极低的认知负荷。开发者无需在终端和浏览器之间切换，所有操作在同一个上下文完成；键盘驱动的流程适合长时间编码后的工作流保持；ASCII 渲染天然跨平台，不依赖图形库。Epiq 还支持命令历史、自动补全、过滤器等进阶功能，:filter tag:bug prio:high 这样的命令行过滤可以快速缩小看板视图。

渲染层面，Epiq 使用 ANSI escape code 控制光标位置和颜色，典型实现依赖于 crossterm（Rust 生态）或 blessed（Node.js 生态）等终端库。核心渲染循环读取当前状态快照，将 Kanban 布局映射为等宽字体的文本块，批量写入 stdout。为保证 60fps 的流畅感，通常采用 diff-only 策略 —— 仅在状态变更时重绘变化的行，而非全屏刷新。

MCP 协议集成：Agent 工作流

Epiq 的一项差异化能力是内置 MCP（Model Context Protocol）服务器。MCP 是一种标准化的 AI Agent 与工具之间的通信协议，允许 Claude、GPT 等大模型通过统一的接口调用工具。在 Epiq 语境下，这意味着 AI Agent 可以直接读取 Issue 列表、写新 Issue、甚至执行状态迁移。

MCP 集成的工程意义远超「给 AI 开放 Issue 读写权限」本身。它本质上是将 Issue Tracker 纳入 Agent 的感知上下文：Agent 在代码修改后可以自动创建关联 Issue，审查代码变更后可以更新 Issue 状态，错误定位时可以自动提 Bug Issue。Epiq 通过 MCP 把 Issue 变成了 Agent 决策闭环的一部分，而非独立的人工维护系统。

工程实现上，Epiq 的 MCP server 暴露了一组标准化工具：list_issues、create_issue、update_issue、add_comment 等。Agent 调用工具时，Epiq 内部将请求翻译为事件追加操作，写入 Git 分支。这一设计保证了 AI 的操作同样被版本化，与人类协作的历史统一管理。

与 git-bug 的定位差异

开源社区中已有类似项目 git-bug，采用 Go 语言实现，同样将 Issue 存储为 Git 对象。两者的主要差异在于：git-bug 偏向完整的离线 Bug 管理，提供 CLI + TUI + Web 三种界面；Epiq 则更聚焦于终端体验和 Agent 集成，采用 Node.js 实现降低了前端开发者参与门槛，ASCII TUI 风格更统一。

另一个显著差异在于同步模型。git-bug 支持点对点的桥接网络同步，适合在没有共享 Git 远程的场景下协作；Epiq 则假设团队至少有一个共享 Git 远程（GitHub、GitLab、自托管均可），通过标准 Git push/pull 同步。这种设计简化了架构，但也意味着 Epiq 在纯点对点协作场景中需要额外的网络发现层。

实践参数与落地建议

团队如果考虑引入 Epiq，以下参数值得关注。首先是事件日志大小控制：事件日志随着 Issue 操作线性增长，长期运行的仓库需要定期压缩事件快照，建议每 10000 条事件执行一次快照归档。其次是 Git 分支策略：epiq/state 分支应设为受保护分支或至少禁止 force push，避免事件历史被意外重写。

在多人协作场景中，冲突解决策略建议默认设置为「自动重放 + 人工确认」模式，即系统自动重放事件并在发现语义冲突时暂停等待人工决策。同步频率方面，建议配置 Webhook 或定时任务，每 5 分钟执行一次 git pull --rebase 拉取远程更新，保持本地状态新鲜。

对于 AI Agent 集成，建议为不同角色配置不同的 MCP 工具权限：Review Agent 仅开放读取权限，Automation Agent 开放创建 Issue 权限，全权限变更仅开放给经过审计的人工操作员。所有 MCP 调用操作同样追加事件日志，便于审计 AI 的行为轨迹。

资料来源

• Epiq 官网与 GitHub 仓库：https://github.com/ljtn/epiq，https://ljtn.github.io/epiq/

systems