刚把团队从 4 个人扩到 12 个人的时候，我发现最痛苦的不是写代码，而是“对齐”。每个人都埋头在自己的分支里，代码 review 没问题，但“这个需求到底做完了没”“这个 commit 对应哪个任务”“测试环境部署的是哪一版”全靠 IM 群里翻聊天记录。后来我们内部做了一个叫做 t3code 的轻量级代码协作工具，用了一年多，帮我把“任务状态”和“代码提交”之间的缝隙补上了。这篇文章就把 t3code 从需求、设计、实现到踩坑的完整过程讲清楚，适合正在头疼小团队研发协作、又不想被重型项目管理工具绑死的人参考。
1. 为什么会有 t3code：小团队协作的隐形成本
1.1 问题从一次线上事故开始
事情是这样的：有个客户反馈线上某个页面数据一直不对，我们查了半天，发现功能代码在两天前就合并进主干并部署了，但对应的数据库迁移脚本被另一个同事误以为已经执行过，实际只跑了一部分。代码层面毫无问题，问题是“谁在什么时候做了什么、还差什么”这件事，在团队里根本没有一个地方能说清楚。
这类问题靠人盯人是盯不住的。我们试着在群里发状态表，用在线文档记账式更新，一周之后就没人维护了。核心矛盾在于：任务管理系统和代码系统是两套逻辑，中间没有关联。任务说“做完了”，代码里可能还没合；代码里有 commit，任务里可能连记录都没有。
1.2 为什么市面上现成的工具都不够用
我们当时的备选项包括 Jira、禅道、Trello、Asana，还有 GitHub Projects。坦白说，功能都很强大，但放到我们 12 个人的团队里，总觉得有点“过载”。我列了一个简单的对比表，这里可以看得很清楚：
| 工具 | 核心优势 | 在小团队实际遇到的障碍 |
|---|---|---|
| Jira | 完整的工作流与权限体系 | 配置成本高，一套工作流字段就要折腾半天，统计报表用处不大 |
| 禅道 | 覆盖需求、任务、缺陷、测试 | 概念太多，开发只用了其中的“任务”，其余全是噪音 |
| Trello | 卡片操作直观，拖拽方便 | 和 Git 完全没有天然关联，状态全靠手动同步 |
| GitHub Projects | 和仓库结合紧密 | 对非程序员不友好，而且 sprint 和迭代管理做得较浅 |
| 自研 t3code | 只做“任务+提交+同步”三件事 | 初期需要自己写代码维护，但内部场景完全可控 |
有个核心点让我下了决心：我们真正需要的不是更新的项目管理方法，而是一个能把代码提交历史和任务进度天然绑定的同步机制。如果这个机制能直接嵌在 Git 工作流里，团队就不需要养成“额外记录”的习惯，也就不存在“忘了填”的问题。
1.3 t3code 的项目定位：终端优先的团队协作层
所以 t3code 的定位从一开始就很清晰——它不是要替代 Jira，而是做开发团队和 Git 仓库之间的协作粘合层。核心解决的问题是三条链路：
- 任务从“待开始”到“已完成”的状态变化，必须能被追踪。
- 代码提交必须能和具体任务产生明确关联。
- 团队里任何人想了解“当前迭代进度”，一条命令就能看到。
为了不增加 UI 维护负担，我们选了终端优先的设计。所有操作都在命令行完成，服务端只提供 API 和实时推送能力，不需要单独开发前端页面。这个决定后来被证明是 t3code 活下来的关键——没有前端，维护成本直接降了一个量级。
2. t3code 的架构设计与数据模型
2.1 技术选型：从 Node.js 换成 Go 的过程
最初版本我用 Node.js 快速搭了一个原型，三天就通了。但做到第三周，问题开始暴露：客户端工具要分发到每个开发者的机器上，Node.js 需要运行时环境，Windows 和 Linux 上还偶尔出现版本不一致。后来我们统一用 Go 重写了服务端和命令行客户端。Go 编译完是单个二进制文件，分发就是一个可执行文件的事情。SQLite 做本地缓存和离线队列非常合适，部署服务端时也只需要一个二进制加一个数据目录。
提示：如果你也打算做团队内部工具，选型时优先考虑“分发成本”和“运行依赖”。原型阶段可以随便选，转正阶段一定要考虑每个同事机器上的环境差异。
t3code 的整体结构分三块：
- 服务端（t3d）：负责任务数据存储、状态流转校验、变更广播。
- 命令行客户端（t3）：开发者在终端里执行命令，所有操作先写本地 SQLite，再异步同步。
- Git 钩子与命令别名：在 commit、push、checkout 等关键节点自动收集代码上下文。
2.2 数据模型：任务与提交的绑定关系
数据模型是整件事的心脏。t3code 的核心表只有五张，没有冗余。我把核心结构贴出来：
-- 团队与成员 CREATE TABLE team ( id TEXT PRIMARY KEY, name TEXT NOT NULL ); CREATE TABLE member ( id TEXT PRIMARY KEY, name TEXT NOT NULL, role TEXT NOT NULL DEFAULT 'dev', team_id TEXT REFERENCES team(id) ); -- 任务本身 CREATE TABLE task ( id TEXT PRIMARY KEY, title TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'todo', owner_id TEXT REFERENCES member(id), iteration TEXT NOT NULL DEFAULT 'backlog', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL ); -- 代码提交与任务的绑定 CREATE TABLE commit_bind ( id TEXT PRIMARY KEY, task_id TEXT NOT NULL REFERENCES task(id), commit_sha TEXT NOT NULL UNIQUE, bind_msg TEXT NOT NULL, bound_by TEXT REFERENCES member(id), created_at INTEGER NOT NULL ); -- 状态变更日志 CREATE TABLE status_log ( id TEXT PRIMARY KEY, task_id TEXT NOT NULL REFERENCES task(id), from_status TEXT NOT NULL, to_status TEXT NOT NULL, changed_by TEXT REFERENCES member(id), changed_at INTEGER NOT NULL );用 commit_bind 表把一次代码提交和一个任务关联起来，是整个设计的核心。后面 t3code 能自动生成“这个迭代哪几个任务已经有关联提交、哪几个还没有”的统计，全靠这张表。
2.3 数据同步的天然难题：离线缓存与最后写者胜
因为我们的发布环境是老旧的物理机房，部分同事的办公网络访问服务端时延迟很高，甚至偶尔断连，所以客户端必须支持离线操作。这里被问得最多的问题是：“离线状态下，两个人同时把同一个任务改成了不同状态怎么办？”
t3code 采用“最后写者胜（Last Write Wins）+ 操作日志”的策略。每条状态变更都带服务端时间戳，后提交的覆盖先提交的，同时把被覆盖的那次变更保存到 status_log 里，管理员随时能看到“这个任务发生过一次冲突覆盖”。这个设计对 12 人的团队来说足够简单粗暴，也避免了复杂向量时钟或 CRDT 带来的实现成本。
2.4 实时性方案：用 SSE 而不是 WebSocket
服务端需要把任务状态变化推给所有在线客户端，这样一个人完成任务，其他人终端上能立刻看到。我第一反应是 WebSocket，但仔细评估后发现，我们这种低频推送场景用 SSE（Server-Sent Events）就够了，而且实现简单得多。WebSocket 需要维护双向连接和心跳，SSE 就是普通的 HTTP 长连接，服务端往一个连接里写数据就行。
Go 标准库加 net/http 就能处理 SSE 流，客户端用 http 包读 body 流也可以。唯一要处理的是断线重连和最后事件的偏移续传。
3. 服务端和客户端的核心实现细节
3.1 服务端：SQLite 的 WAL 模式与写并发控制
服务端存储直接用 SQLite，设置 WAL 模式后，读写并发表现远好于默认的 rollback journal。这个选择后来被证明非常正确：SQLite 单文件备份方便，而且我们对事务强度要求不高。唯一的坑是 SQLite 写锁是库级别的，当多个请求同时写时，容易出现 “database is locked”。解决方案是加一个简单的内存写队列，把实际写操作串行化，同时读操作直接走 WAL 快照，不阻塞。
核心伪代码如下：
var writeCh = make(chan func(), 256) func init() { go func() { for fn := range writeCh { fn() } }() } // 写操作统一提交到队列 func queuedWrite(db *sql.DB, fn func(tx *sql.Tx) error) error { result := make(chan error, 1) writeCh <- func() { tx, err := db.Begin() if err != nil { result <- err; return } if err := fn(tx); err != nil { tx.Rollback(); result <- err; return } tx.Commit() result <- nil } return <-result }这样多个 goroutine 同时写入时，实际上只有一个在操作数据库，彻底避免了锁冲突。
3.2 客户端命令设计：能用一条命令绝不用两条
t3code 的命令设计我一直遵循“频率决定长度”的原则。使用频率最高的操作，字符数越少越好。核心命令如下：
# 初始化项目并关联团队 t3 init --team myteam # 创建任务（默认状态为 todo） t3 task add "修复登录态过期问题" --owner zhangsan --iter iter-23 # 查看当前迭代所有任务 t3 task list --iter iter-23 # 查看某个任务的详细信息和关联提交 t3 task show TSK-1042 # 手动绑定当前 HEAD 到任务 t3 bind TSK-1042 "完成登录态过期修复" # 把任务推送到服务端 t3 sync为了让任务和 commit 的关系更自然，我们在 pre-commit 钩子里加入了一段识别逻辑：如果当前分支名是一次提交信息里包含任务号，自动提示是否绑定。
3.3 Git 钩子：自动关联提交与任务
git hooks 是实现自动关联的关键点。pre-commit 阶段，t3code 会在当前分支名里查找类似 “feature/TSK-1042-login-expire” 的模式，提取任务号并提示绑定。commit-msg 阶段，如果钩子发现提交信息里写了 “#TSK-1042” 这样的标记，也会触发绑定。
这里上了一个很实用的钩子脚本片段：
#!/bin/sh # .git/hooks/commit-msg MSG_FILE=$1 MSG=$(cat "$MSG_FILE") TASK_ID=$(echo "$MSG" | grep -oE '#TSK-[0-9]+' | head -1) if [ -n "$TASK_ID" ]; then /usr/local/bin/t3 bind "$TASK_ID" "$MSG" --from-hook fi exit 0之所以放在 commit-msg 而不是 post-commit，是因为一旦提交完成再去绑定，如果绑定失败就很难补救。commit-msg 阶段失败会阻塞提交，更安全。
3.4 离线队列：客户端本地 SQLite 的重放机制
客户端的每次写操作，都先记录到本地 SQLite 的 outbox 表，然后定期或手动触发 push。服务端返回成功后，更新 outbox 的状态为 synced。断网时所有操作都标记为 pending，等网络恢复后按顺序重放。
CREATE TABLE outbox ( id INTEGER PRIMARY KEY AUTOINCREMENT, op_type TEXT NOT NULL, op_payload TEXT NOT NULL, server_ts INTEGER, status TEXT NOT NULL DEFAULT 'pending' );这里有个顺序敏感问题：任务 A 从 todo 改成 in_progress，紧接着又改成 done，这两条操作如果乱序重放，最终状态可能是错的。所以重放逻辑严格按 outbox.id 排序，且必须等上一条操作确认后再发下一条。吞吐量虽然低了，但对 12 人的团队来说完全够用。
4. 开发过程中踩过的大坑和完整的排查链路
4.1 SQLite 写锁风暴：从偶尔超时到服务端雪崩
第一次联调时，团队四个人同时执行 t3 sync，服务端突然大面积报错 “database is locked”。起初我以为是并发太高，加了个连接池上限，结果好了一天，第二天又出现。当时排查的思路是：
- 先看服务端日志，发现锁错误集中在同一秒，而且来自不同的 HTTP 请求。
- 手动用 sqlite3 执行写操作，确认数据库本身没有损坏。
- 在服务端加了页面的并发写测试脚本，模拟 50 个并发写，结果立刻复现锁错误。
- 查阅 Go 的 database/sql 实现，确认连接池里同时可能有多个写连接在竞争 SQLite 的单写锁。
最终确认问题不是连接池不够，而是多个物理写连接同时抢锁。解决方案就是前面提到的串行写队列，把所有写请求放到同一个通道里按序执行。上线后测试，50 并发写不再报任何锁错误。
提示：如果只用 SQLite 做服务端存储，一个强制建议是永远不要直接并发写数据库，无论用不用队列，至少在应用层加一个写锁。SQLite 的设计前提就是写是少数、串行才安全。
4.2 SSE 连接风暴与客户端内存泄漏
SSE 连接初始版本里，服务端为每个客户端开一个 goroutine 写数据，看起来没什么问题。但测试时发现客户端连接后长时间不操作，服务端内存稳步上涨。定位过程如下：
- 用 pprof 抓了 goroutine 和 heap 的 profile，发现大量 goroutine 阻塞在 channel send 上。
- 检查代码，发现很多连接建立后客户端没有及时读消息，而服务端广播时向所有连接写入，写不进去就阻塞。
- 此时连接超时又没有设置，导致这些 goroutine 越积越多。
解决办法是每个连接设置写超时，写不进去直接断开，并限制每个 ip 的最大连接数，以及定期清理僵尸连接。同时客户端侧也加了心跳检测，5 分钟没有收到数据就主动重连。
4.3 Git 时区与时间戳的差异导致任务超时误判
还有一次比较隐蔽的问题：任务显示“已超时”，但查看提交时间明明是当天。最后查出来是 Git 的提交时间用的是提交者本地时区，而服务端判断超时用的是 UTC 时间。一个同事在非标准的时区配置下，提交记录的时间戳和服务器相差了十几个小时。
修复方式是在 commit-bind 表里额外存一个 client_local_ts 字段，并记录时区偏移。所有涉及“超时判断”的逻辑一律用服务端时间戳，展示层才用本地时间。这里给我的教训是：任何时候涉及跨时区的时间计算，服务端永远是唯一事实来源，客户端传上来的时间只能做参考。
4.4 Windows 开发者的 Git Bash 与路径兼容问题
团队里有两位同事主力开发机器是 Windows，然后用 Git Bash 操作。t3 客户端在 Windows 上的路径处理出了不少幺蛾子。最典型的问题是客户端安装路径里如果有空格，git hook 脚本里的命令解析就会出错。修复方法是在所有调用 t3 的地方都用引号包裹完整路径，并在启动时检测执行目录的权限。
这个问题没有完全根治，最后我们让 Windows 同事统一用 WSL 环境，t3code 在 WSL 内部安装。这不是脚本问题，而是 Windows 的文件系统和 Unix 权限模型差异带来的长期维护成本。
5. t3code 的实际运行效果与团队反馈
5.1 半年运行后的数据表现
t3code 正式上线后的半年里，我们积累了一些数据，直接反映了这个工具的效果：
| 指标 | 使用前 | 使用 6 个月后 |
|---|---|---|
| 任务与代码提交的关联率 | 几乎没有系统化记录 | 91% 的迭代任务有关联提交 |
| “当前迭代进度”询问次数 | 每周平均 12 次 | 降到约 1 次 |
| 因手工同步导致的失误 | 每月平均 2-3 次 | 约等于 0 |
| 新增任务创建耗时 | 需要登录网页、填若干字段 | 平均 4 秒一条命令 |
特别值得注意的是那个从 12 次降到 1 次的数据。问“进度”的场景在研发管理里看着很小，但每次打断都会消耗上下文。一天被别人问三四次，相当于多写一小时代码的成本。
5.2 团队真正的使用方式：比预期更轻
让我意外的是，最终团队用得最熟练的业务场景是iteration review 时的命令导出。开会前，谁执行一下t3 task list --iter iter-24 --format table，输出直接贴到会议文档里，讨论哪几个任务没有 commit_bind 记录，一眼就知道哪些工作没完成代码关联。这套流程比在网页里反复筛选字段直观得多。
另一个高频场景是新人入职。新同事配完仓库后跑一次t3 init，随便执行t3 task show TSK-1042，就能看到这个任务的全部历史、绑定提交时间线、状态变更记录。这比任何文档培训都高效。
5.3 我自己的体会：小而精准的工具才是内部工具的未来
做了 t3code 之后，我对内部工具开发有了一个更明确的判断：内部工具的核心不是功能多，而是精准匹配“团队的实际行为模式”。大而全的平台提供的 90% 功能，在一个中型技术团队里根本不会用到，而那 10% 的常用功能又往往因为入口太深、流程太重而被滥用。
t3code 恰好只做到了三件事：任务状态可见、提交与任务绑定、状态变化可追溯。这三件事恰恰是“代码协作”里最容易被忽略的核心。至于以后要不要加甘特图、工时统计、绩效报表，我的回答是暂时不考虑。已经满足需求，就不要轻易扩大边界。
6. 给想自建类似工具的人几个关键建议
6.1 分阶段上线，而不是一次交付全部功能
t3code 第一版其实只有三个命令：init、task add、bind。能“创建任务”和“绑定提交”之后，团队就已经进入了一个正循环。迭代管理、SSE 推送、离线队列这些功能都是后面根据真实反馈逐步加的。如果你一开始就把所有功能想完再开发，大概率会造出一个没人用的东西。
6.2 Git 钩子的健壮性要单独测试
Git hooks 是 t3code 自动化的关键，也是最容易出问题的部分。我建议在 CI 里专门加一个测试任务，模拟各种异常场景：分支名没有任务号、commit message 非 UTF-8 编码、在 detached HEAD 状态下提交。任何一个场景如果处理不当，都会导致开发者的本地提交失败，引发团队负面情绪。
6.3 监控工具自身的健康度
内部工具最怕的是“坏了没人知道”。t3code 服务端提供了一个心跳接口，返回当前任务总量、今日操作数、SSE 在线客户端数量。我用一个简单的定时脚本每天检查接口，连续失败三次就告警到团队 IM 群。维护内部工具和写业务代码不一样，它最需要的是“润物细无声”的稳定。
最后再分享一个实际操作里非常有用的小技巧：在团队里挑选一个熟悉命令行、并且愿意提意见的同事作为 t3code 的“内部体验官”。每次新功能上线前，先让这个人试用三天，通不过他这关就不推给大家。工具好不好用不是看文档写得多完善，而是看有没有人愿意每天用。t3code 能有今天这个状态，很多修改灵感都来自这位体验官的吐槽。
