我在去年年底的时候被一个很老套的问题折腾得够呛手上四个正在维护的项目分别用了不同的语言和技术栈前端一个 Vue、一个 React后端是 Go 和 Rust 的微服务。每个项目都有自己的 lint 脚本、格式配置甚至提交信息规范。最痛苦的是团队里每次来了新人光是把这些乱七八糟的检查规则跑明白就得花两三天。也就是从那时候起我开始认真考虑一件事有没有可能做一个统一的命令行入口把代码质量检查、规范校验和团队协作相关的零碎流程全部收敛到一个工具里统一管理后来这个项目被我取名为 t3code断断续续打磨了近一年现在拿出来写一篇完整的复盘。如果你也经历过“规范碎片化”的折磨——ESLint 管 JS、Stylelint 管 CSS、gofmt 管 Go、rustfmt 管 Rust每个工具各有各的配置文件和输出格式生态还不断更新那你应该能理解我做这个工具的动机。t3code 不是什么颠覆性的发明它更像一个把所有检查动作收拢到同一把伞底下的“调度中枢”目标只有一个让开发者在跑代码质量检查时只记住一条命令。这篇文章会拆解 t3code 的定位、核心模块、完整接入流程以及我在真实项目里踩过的坑和调优经验。1. t3code 的定位一个命令解决“多语言规范碎片化”的基础问题1.1 为什么我不满足于串行执行 lint 脚本在我自己的项目里一个前端的“全量检查”大概长这样eslint src config --ext .js,.ts stylelint **/*.{css,scss} prettier --check .后端还要再来一遍go vet ./... golangci-lint run ./... cargo clippy --all -- -D warnings cargo fmt --check这些命令如果只是偶尔跑一次问题不大。但一旦要接入 CI、要做 pre-commit 钩子、要在不同团队之间复用同一套规则你就会发现巨大的成本每个人都有自己熟悉的工具集每个人的 shell 别名不一样每个人的 CI 管道脚本也不同最后只能靠文档沟通。更麻烦的是不同工具的退出码语义不一致、输出格式各成一派要做自动化和统计都很难。t3code 的第一个设计决策就是把自己定位成“统一入口”而不是替代品。它不重写 ESLint也不重写 clippy而是把它们的执行、解析、汇总统一起来。你对 t3code 发起一次扫描它去调度后端各自的检查器然后标准化输出成一份报告并按统一规则返回退出码。这个思路听起来不复杂但在实际工程中要处理的事情比想象中多得多后面详细说。1.2 “第三代代码治理”这个命名背后想表达什么t3code 里的 “t3” 我习惯解读为 “Third-generation Tool”也就是第三代代码治理工具。第一代是单语言的 lint 工具比如最早的 JSLint、C 语言的 lint第二代是打补丁式的规范全家桶典型代表是 Prettier ESLint husky lint-staged 这种管线组合第三代应该解决的是“工具足够多了但开发者记不住、用不齐、管不过来”的问题。这不是说第二代工具不好。恰恰相反没有它们打底我不会想着去开发 t3code。t3code 更像是一个对第二代资产进行编排的“编排层”它的价值在于你已有的 ESLint 规则、已有的 golangci-lint 配置、已有的 prettier 设置全部不需要重写t3code 只是帮你用统一的方式把它们触发起来。这样做的好处非常明显团队不需要学习一套全新的代码检查哲学只是把原来散落在 package.json、Makefile、CI 脚本里的命令收敛成一个入口。出去的是一致性省下来的是心智负担。1.3 t3code 适合谁用我的使用体会是t3code 最适合两类场景。一类是中小型团队大家的技术栈比较多没人专职维护工程效率基础设施需要用最小成本把规范统一起来另一类是偏平台化的团队有多个仓库、多语言服务想把代码检查结果汇总到某个可视化面板或做达标率度量那么 t3code 的标准化输出就会很有价值。如果只是个人维护一个纯 Python 项目那我可能不会推荐上 t3code因为直接用 ruff 就够了。但只要你面前摆着两种以上语言的仓库或者一个人要维护三个以上技术栈t3code 带来的“统一命令、统一输出、统一退出码”就值回成本了。2. t3code 的三大核心模块调度、规则集与增量缓存2.1 调度模块把“检查后端”做成可插拔协议t3code 的核心是一个调度器它不关心底层的检查器用什么语言写的只要对方实现了“t3code Protocol”即可。这个协议是我自己定义的本质上就是三点接受固定参数、输出 JSON 到 stdout、退出码遵循规范。每个检查器被封装成一个 adapter。比如我写的 eslint-adapter 会去读项目里的 .eslintrc 或 eslint.config.js然后用 ESLint 的 Node API 执行扫描再把结果转换为 t3code 统一的 JSON 结果格式。同理clippy-adapter 就是一条带 json 格式的 cargo clippy 命令封装。这里有个非常关键的工程决策调度器默认串行执行各 adapter。为什么不并行因为很多仓库的检查器会读取和修改文件最典型的是 prettier 的 --write 和 eslint 的 --fix并行调度会产生不可预期的竞争条件。t3code 会先生成一份执行计划把 adapter 分为“只读类”和“可写类”在完全无冲突的情况下才允许并行的只读任务同时跑。t3code scan --staged这条命令是我平时用得最多的它只对暂存区内的文件执行检查在 pre-commit 阶段非常快几百毫秒到一两秒就能跑完不会像全量扫描那样让人等得想放弃。2.2 规则集模块预设、覆盖与继承的三层结构规则集是 t3code 配置体系里最有意思的部分。它把规则组织成三层base 层预设、项目层覆盖、开发者层补充。base 层的逻辑很简单t3code 默认内置一组比较保守但合理的规则预设比如所有 lint 检查都必须打开 error 级警告、文件末尾必须要有换行符、commit message 必须符合 Conventional Commits 规范。这组预设不是给每个项目定制的而是为了保证“最低限度的体面”。项目层配置在 t3code.yaml 里格式大概长这样project: languages: - typescript - go - rust rules: typescript: eslint: extends: airbnb-base severity: error go: golangci: enable: - govet - staticcheck disable: - errcheck # 历史代码太多暂时关掉 rust: clippy: warn: - pedantic deny: - unsafe_code commit: enabled: true allow_types: - feat - fix - refactor开发者层则是对应个人的本地覆盖放在个人目录里默认不提交到仓库。这个层级的意义在于个人的风格偏好不应该影响项目的统一标准。比如我在本地习惯把 prettier 的 printWidth 调成 100但项目固定 80那项目层会覆盖掉我这个个人设置。不过有一种情况例外——如果项目层没有显式声明某个参数而开发者层声明了那开发者层就直接生效。这个优先级设计很实用保证了“项目说了算但夹缝里有个人弹性”。2.3 增量缓存用一个本地索引解决全量扫描慢的问题t3code 做得最值回票价的一个功能我认为是增量扫描。全量扫描在大型 monorepo 里会慢到让人崩溃我实测过一个包含 300 多个 Go package 的仓库golangci-lint 全量跑一遍要三分钟以上根本没人在每次提交前跑。t3code 的处理方式是维护一个本地缓存索引简单说就是每个被扫描过的文件t3code 会记录文件路径、大小、Mtime、以及对应检查器的结果指纹。下次扫描时如果文件没有变化就直接从缓存里拿上次的结果如果有变化就只对变化的文件重新跑检查器然后跟缓存结果合并成完整报告。需要注意这个缓存机制只对“只读检查器”有效。涉及代码修正的 --fix 操作不能走增量因为文件内容变了之后必须重新完整执行一遍检查器才有意义。t3code 在这个地方做了一个安全保护如果扫描命令带 fix 参数缓存路径会自动临时关闭。我测试过在 monorepo 里跑全量扫描第一次大概需要 2 分 40 秒缓存建立后第二次只用了 7 秒第三次因为在 pre-commit 阶段只改了两个文件用时不到 1 秒。这种体验上的差距直接决定了开发者愿不愿意每次提交都跑一遍检查。3. 快速上手指南十分钟把 t3code 接进现有项目的操作链路3.1 安装 t3code 的三种方式t3code 的安装很简单目前我提供了三种主流途径Homebrewbrew install t3code/tap/t3codeGo 安装go install github.com/t3code/t3codelatestDockerdocker run --rm -v $(pwd):/repo t3code/t3code scan个人开发者电脑上我推荐用 Homebrew 或 Go 安装Docker 版本主要给 CI 流水线用避免每台构建机器都要装一堆语言的运行时。这个设计有个细节安装 t3code 本身是二进制的但它要调度 ESLint、clippy 这些后端后端的依赖还得项目自身安装好——t3code 只负责调度不负责替你装语言工具链。3.2 初始化配置t3code init 会生成什么在一个已有项目里跑t3code init它会做三件事检测项目里的语言与技术栈生成一份合适的 t3code.yaml 基础配置并且提示你当前缺失哪些检查器。比如我去年把一个 Vue 2 项目接进来时init 检测到 JavaScript TypeScript SCSS于是自动生成了 typescript 的 eslint adapter 配置和 stylelint adapter 配置。它没有自动安装依赖但会把推荐的依赖列表直接写在终端提示上。这里有一件我很在意的事init 生成的内容默认可读性要足够好所以每条配置后面都带注释说明这个字段影响什么新人看了不会一头雾水。3.3 第一跑看懂 t3code 的输出报告第一次执行t3code scan时终端会打印一份分组的 Markdown 报告大致结构是t3code report (took 38.2s) [error] 45 issues found in 12 files typescript/eslint: src/utils/format.ts:12:4 [error] Unexpected any. Use unknown instead. (no-explicit-any) [error] Missing return type on function. (explicit-function-return-type) go/golangci: internal/service/order.go:30:9 [warning] G404: Use of weak random number generator rust/clippy: src/parser.rs:108:14 [deny] unsafe_code: usage of unsafe block Exit code: 1每一条结果都会带上“检查器名 规则名 文件位置 严重级别”。我给 t3code 设定了一个统一的严重级别体系error、warning、info。所有后端的原有级别都会被映射到这三级比如 clippy 的 deny 映射成 errorwarn 映射成 warningallow 则不输出。很多第一次用 t3code 的人会疑惑为什么退出码永远是 1不管是有 error 还是 warning只要发现问题就返回 1。这个策略是为了保证 CI 的最小惊讶原则——哪怕只有一条 warning也应该让构建红掉否则 warning 就慢慢变得没人看。如果你确实想忽略 warning 级别可以在配置里把exit_on设置成error让它只对 error 级别返回非 0 退出码。3.4 接入 CI 流水线的最小配置文件接入 CI 是我使用率最高的场景之一。一个最小可用的 GitHub Actions workflow 大概这样name: code-quality on: [push, pull_request] jobs: t3code: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - uses: actions/setup-gov5 with: go-version: 1.22 - uses: dtolnay/rust-toolchainstable - run: npm ci - run: go mod download - run: cargo build - run: docker run --rm -v ${{ github.workspace }}:/repo t3code/t3code scan --ci--ci参数是我针对流水线场景做的优化它会自动关闭彩色输出、把日志压缩到每类问题只展示前 10 条摘要并生成一份可上传的 JSON 报告。后面如果你想做增量统计比如“每千行代码缺陷率”这种度量这份报告可以直接喂给数据管道。接入 CI 时还有一件容易被忽略的事必须显式地安装所有后端工具链。如果你只安装了 t3code它找不到 eslint 和 clippy只会报 adapter 未初始化。我在 README 里把每个 adapter 需要的运行时环境列了一个表但实际踩过坑的人应该都懂CI 上最常出现的问题就是“本地能跑CI 上找不到工具”。4. 我在真实项目里验证过的东西踩坑、误报与大仓库调优4.1 “误报”到底是不是误报我如何定位 t3code 的误报来源我在一个 Go 项目里集成 t3code 时第一天就收到了将近 200 条 warning团队里的同事第一反应是“这个工具有毛病误报率太高了”。但我把报告逐条筛了一遍之后发现问题其实集中在三类来源上。第一类是 dead code有些工具函数在重构之后已经没有任何调用方但 Go 编译器默认不会报错只有 staticcheck 这类高级检查器能识别出来。第二类是资源泄漏隐患比如defer resp.Body.Close()没做 error 处理这类问题严格来说不算误报但历史上没人关注。第三类是 t3code 的 adapter 没正确处理语言版本——最典型的是 TypeScript 项目没设置tsconfig里的strict模式ESLint 的规则拿到的类型信息特别少导致大量no-any之类规则被误触发。所以我的经验是第一次接入 t3code 时不要直接上 error 级全部拦截。先在 CI 里跑一段时间“仅报告、不阻断”模式让团队花两周时间把噪音过滤干净再把退出码策略收紧。t3code 里有一个baseline配置项可以把这一次扫描发现的所有问题固化成基线文件之后每次都只统计新增问题。这个思路跟 eslint 的--max-warnings和 clang-tidy 的 baseline 很像但 t3code 把基线做到了跨检查器统一管理可以对着整份报告生成基线。4.2 历史债怎么还渐进式治理的手段接入 t3code 的最大矛盾在于项目里积累了多年的历史问题如果不处理新问题混在里面根本看不清如果一次性全处理工作量又大到无法推进。我的做法是用 t3code 的 apply-baseline 子命令步骤很简单t3code scan --output baseline.json t3code apply-baseline --input baseline.json执行完之后t3code 会在仓库里生成一个.t3code/baseline.json之后每次扫描baseline 里记录的老问题会被自动标记为legacy级别默认不在报告中显示但也不会被忘掉——它会被单独统计进“历史遗留债务”这张表。这样新代码的问题检测完全不受历史问题干扰团队可以专心地在新代码上保持高标准再安排专门的时间逐步清理 legacy。这个机制让我想起了一个很朴素的道理代码治理的本质不是“把问题一次性清零”而是“让问题的增量变成可见、可控的”。t3code 的 baseline 能做到这一点已经不单单是一个 lint 工具了。4.3 monorepo 大型仓库的性能优化我试过的几个配置组合在 CICD 流水线上跑 t3code性能是有优化余地的但优化手段各有取舍。我实验过的有效配置大概有这么几种只让tsc或go build的编译产物进入 cache不做无意义重扫开启--include-changed-only让它只扫描最近一次提交涉及的文件把低频检查器放到单独的weeklyad hoc 命令里不让它们进每次提交的阻塞链路。实际数据是这样的我有一个 20 万行 TypeScript 的 monorepo不做增量扫描时全量 3 分多钟开了增量之后 5 秒CI 上因为每次都是全新容器没有本地缓存所以 CI 阶段我会刻意用--full参数跑全量但会把 t3code 的 JSON 结果上传到 S3 之类的存储里供后续缓存预热。这里要注意t3code 的缓存目录默认就是~/.cache/t3codeCI 容器里它是空的。如果你想让 CI 也能享受增量得自己把 cache 目录持久化在 runner 之间共享比如 GitHub Actions 的 actions/cache。我一开始偷懒没做结果 CI 每次全量扫慢倒是能忍主要是日志太长团队同事抬头看到一片全是 red error反馈很负面。4.4 规则集合并顺序的坑预设被覆盖的顺序问题t3code 的规则集合并逻辑按优先级从高到低依次是命令行参数 项目配置 个人配置 内置预设。听起来很清晰但实际使用中发生了一个意想不到的坑。我在一个前端项目里配了rules.typescript.eslint.extends: airbnb-base但发现 t3code 最终执行时还是会额外带上我内置预设里的no-console规则而且死活关不掉。排查了很久才发现原因内置预设和项目的 extends 都是“叠加生效”的而不是“替换生效”。也就是说项目里选择了 airbnb-base并不会覆盖掉 t3code 内置的 base 层两个规则集是合并在一起的。如果你想严格只用一个规则集必须显式设置extends: base然后规则集引擎会知道你要清空 base 层重新定义整套规则。这个设计在当时是有意为之的——为了避免项目配置里遗漏必要的安全门槛比如no-unsafe-optional-chaining这类规则即使你不喜欢 base 层其他规则安全类规则也得保留。但设计归设计没有在文档里写清楚就成了一个真实的坑。现在我在模块文档开头统一放了这么一句提示“默认叠加合并除非你显式声明替换。” 这大概就是自研工具最好的地方踩过的坑自己会记得修。5. t3code 的边界地带哪些事我故意没做以及后续方向5.1 边界一不做代码编辑器的实时诊断很多人在第一次看完 t3code 的 demo 后会问“它支持 VS Code 的实时诊断吗” 答案是目前不支持而且我短期也没打算做。原因是编辑器的实时诊断有它自己的完整生态每个语言都有极其优秀的插件比如 ESLint 的 VS Code 扩展、rust-analyzer 自带的 lints这些工具的实时体验是 t3code 无论如何都追不上的。t3code 存在的场景跟编辑器是完全分开的它更像“提交前和 CI 里的统一裁决者”而编辑器插件是“写代码时的随行顾问”。两者可以共存不需要互相替代。很多项目在使用 t3code 之后编辑器插件照常能用t3code 只负责最终把关二者并不会产生冲突。5.2 边界二不做死代码分析、依赖漏洞扫描这类“重活”死代码分析比如 Rust 的 dead_code lint 加强版和依赖漏洞扫描npm audit、dependabot也是一些用户会顺手提的需求。但我明确把这些排除在 t3code 的核心范围之外。原因很简单这些功能需要非常深的语言语义分析能力和持续的漏洞情报更新把它塞进一个通用统一的 CLI 里只会让安装包和工程复杂度双双膨胀。真要找死代码和漏洞有专门的工具比如 ts-prune、cargo-udeps、npm audit、trivy它们在这条赛道上的专注度极高。t3code 的做法是通过hooks机制把它们串进检查流程比如在 pre-commit 和 CI 阶段让 t3code 顺带执行一条npm audit --omitdev并把结果并入统一报告但不会用自己的代码去实现这些检测。hooks: before_scan: - command: npm audit --omitdev allowed_exit_codes: [0] after_scan: - command: make check-unused-deps allowed_exit_codes: [0, 1]hooks 配置让 t3code 成为“流程编排者”而不是“万能检测器”我觉得这个边界感特别重要。5.3 插件化的下一步为内部平台预留扩展点t3code 目前的 adapter 都是内置的但我在设计时预留了一套插件机制允许团队开发自定义检查器。插件本质上就是一个可执行文件加上一个 manifest.json。manifest 里声明了这个插件叫什么名字、支持哪些语言、应该接收什么参数、输出什么格式。你写好之后放到项目的.t3code/plugins目录下t3code init 会自动发现。这套机制看起来简单但已经足够让不少团队把公司内部自研的代码风格检查、目录结构约束、TODO 时效检查这类特殊规则直接挂进 t3code 的流程里。我认识的一个中型平台团队甚至把内部的接口契约检查器做成 t3code 插件所有微服务仓库只要接入 t3code就自动被检查 API 定义跟注册中心是否一致。从小工具变成平台基础设施的一部分这是我觉得最有成就感的用法。5.4 我并不打算支持的功能t3code 不会成为“包管理器式的巨型框架”我明确不打算做依赖安装器类似于自动 pip install 缺失包、构建系统类似于 turbo 或 nx 的任务编排、以及代码生成器。这些领域已经有很成熟的产品硬挤进去只会让 t3code 的定位模糊。我始终觉得一个好的开发者工具应该像一把大小合适的多功能折刀而不是一把什么都想装的瑞士军刀——后者看起来功能很多但真正要用的时候每一样都不称手。6. 给想试 t3code 的人一点我自己的体验参照如果你也想在自己的项目里试一下 t3code我建议按这样的节奏推进第一个星期先只在自己最熟悉的一个仓库里跑t3code scan把报告当作周报素材不急着接 CI也不急着配置 hook。第二个星期把 baseline 建好开始日常提交前跑t3code scan --staged熟悉它在你这个技术栈里的行为。第三个星期再接 CI加上--ci参数先观察一周的假阳性数量再做拦截。如果跑了三周之后你发现团队里的同事开始主动问“这个红的是什么意思”那说明这套工具的推进已经成功了一半。我自己的经验是工具的价值不是来自它多聪明而是来自团队形成统一工作流之后那些省下来的沟通成本和被消灭的“本地跑不过CI 却过了”之类的灵异事件。最后分享一个小技巧t3code 的t3code why子命令可以在报告里追着一条问题反查它来自哪个检查器、被哪条规则触发、又因为什么配置被应用上。这个命令是我在调校团队规则时最常用的功能遇到任何“为什么这里会报”的疑问先跑一下t3code why比翻配置文件猜快太多。就写到这里。如果你手里也有一个多语言仓库建议找个周末把它接进 t3code 跑一次全量扫描看看报告里“老债”有多少、“新问题”有多容易被埋没答案通常会让你挺意外的。