写代码这行当干得越久越觉得真正折磨人的不是写业务逻辑而是“让一群人长期稳定地把代码写规范”。我前前后后折腾过格式化工具、静态检查、复杂度检测、提交信息校验每一样单独拎出来都挺好用但凑在一起就是一团乱麻新成员要装一堆插件老成员各有各的配置PR 里永远在争论换行和缩进。后来我实在受不了自己动手收拢了一条命令行工具代号就叫t3code。t3code不是某个语言的新框架也不是又一个 lint 规则的集合。它是一条把代码规范校验、复杂度评估、重复检测、变更影响分析全部收口在一起的命令。核心思路是把“代码规范”从一份写在 Wiki 里的文档变成一套可执行、可量化、可追踪的工程化流水线让机器在提交前就把大部分质量问题挡在门外。这篇文章我把它的设计思路、核心配置、踩坑实录都摊开来讲适合正在做技术基建、带团队、或者被存量代码质量问题折磨得想换行的同学参考。1. 为什么叫 t3code第三代编码规范工程化思路1.1 “三代”到底指哪三代“T3”这个后缀不是随手起的。我在设计这套东西之前认真梳理过代码规范在团队里落地的方式演进大致能分成三代第一代是“人肉规范”。规范写在文档里、贴在群里、刻在老员工的脑子里。代码行没行尾分号、函数是不是写得太长、那个变量命名到底啥意思全靠 review 时人眼去挑。这套做法的问题很明显不可执行不可度量每个人对规范的理解都带私人滤镜。第二代是“工具约束”。ESLint、Prettier、TypeScript 类型检查、Stylelint 这些工具纷纷进场把格式问题和明显的逻辑问题交给机器。但这一代又走了另一个极端每个阶段只解决一个点彼此之间数据不相通。我用 ESLint 管代码风格用 Prettier 管格式用 SonarQube 管复杂度用 Commitlint 管提交信息结果 CI 跑了五六道独立的检查每次报错格式都不一样修完一个又冒出来另一个。第三代就是我想要的形态规范即代码门禁即命令。把分散在各个环节的检查聚合成一条流水线规则放在同一个配置文件里结果输出同一种格式的报告能力上做成可插拔。t3code 这个名字一是 Third-generation 的意思二是它给自己立了三个指标Predictable可预期、Traceable可追溯、Sustainable可维护。这三条我一直当成设计的北极星每个功能砍不砍拿这三条过一遍就清楚了。1.2 t3code 要解决的核心痛点我在维护 t3code 的过程里最常听到的一句话是“我们团队其实挺规范的就是没人监督。”这话翻译过来的意思是规范有但没落地工具也有但散落一地。具体拆解一下痛点其实是四个第一工具链七零八落。新成员入职光环境配置就能耗掉半天。每个人本地的插件版本还不一样同一段代码在不同人机器上检查结果可能都不一样。每个工具都有自己的配置文件、自己的忽略机制、自己的错误输出格式拼在一起就是一份冗长的“新手踩坑文档”。第二规范无法量化。文档里的规范写得再漂亮也回答不了“这个函数到底能不能超过 100 行”“重复代码比例多高就该重构”“复杂度上涨到多少会让下一个人读不懂”这类问题。没有量化就没有门禁没有门禁就谈不上规范。第三存量代码没有中间态。大多数团队不是从零开始接工具而是要面对跑了三五年、几万行甚至几十万行的老项目。全量开规则报错上万条开发直接宕机不开规则又等于没有接入。工具如果只有 0 和 1 两种状态那基本等于不适合真实团队。第四个痛点是最近一年特别明显的AI 生成代码多了机器审查必须跟上。过去代码是人写的风格相对统一review 盯逻辑就行。现在代码是 AI 补全的AI 写起来又稳又快但重复代码、过度封装、风格漂移这些问题呈指数级冒出来。靠人审已经审不过来了必须有一套能从结构和统计层面批量筛选的自动化审查机制。1.3 为什么选聚合式 CLI而不是做一个 IDE 插件我当时也有过要不要做 IDE 插件的念头后来果断放弃了。IDE 插件的问题是它管得住编辑器里的事管不住 CI 和 Git 的事。代码质量的门禁最终必须落在“提交”和“合并”这两个节点上而不是落在开发者本地按没按快捷键上。聚合式 CLI 的好处是它可以在开发者本地、CI 流水线、甚至服务器上的定时任务里跑同一个命令保证所有环境看到的结果一致。它不是一个编辑器插件而是凌驾于各种插件之上的统一入口。t3code check 这条命令执行的时候会先扫描项目当前的工具链再决定怎么调度有 ESLint 就调 ESLint有 Prettier 就调 Prettier在这基础上再做它自己独有的那部分——复杂度分析、重复代码检测、目录结构约束、提交信息校验。它不去替代你现有的工具而是把你的工具和缺失的环节一起收口。2. 核心细节解析与实操要点2.1 先看懂命令一条命令干了四件事t3code 的命令体系不长核心就是几条# 初始化配置生成 t3.config.ts 和 .t3ignore t3 init # 全量检查lint format 复杂度 重复度 提交信息 t3 check # 只看本次变更影响的范围 t3 check --diff # 尝试自动修复 t3 fix # 输出可视化的质量报告 t3 report这里面最核心的是 t3 check。它并不是只跑一种检查而是默认按顺序完成四层校验规范层调用项目里已有的 ESLint、Stylelint如果没有就用内置的轻量规则兜底复杂度层基于抽象语法树AST计算循环复杂度、认知复杂度、嵌套深度、函数行长重复度层对文件做标记化处理检测代码克隆找出 Copy-Paste 的重灾区变更层校验提交信息是否符合团队的约定格式同时对比 Git 基线识别本次改动有没有触碰“红线目录”。一次命令四种能力最后统一输出一份带文件级明细的报告。这不只是省几条命令关键是节省了“上下文切换”你不用在五个工具之间来回跳一份报告里就能定位所有问题。2.2 阈值不是拍脑袋复杂度与重复度的量化逻辑这一节我想重点聊因为这是 t3code 里最容易被人忽视也最值得琢磨的部分。很多人一上来就问“循环复杂度阈值默认多少”默认值是 15。但这个数字不是随便填的它的依据是业界多年积累的统计数据当函数循环复杂度超过 10 的时候缺陷率会明显上升超过 15缺陷率曲线会陡增。对于绝大多数业务代码函数能控制在 15 以内说明它逻辑分支不算失控。不过我这里要强调一个点阈值必须跟着团队现状走而不是跟着工具默认值走。新生项目可以从严直接设 10老项目建议从 20 甚至 25 起步然后每个迭代往下降。这个“降阈值”的过程本身就是一种技术债偿还机制比一次性推到 10 然后面对几千条报错要友好得多。除了复杂度还有一个参数也要重点关注重复度阈值。t3code 检测重复代码的默认策略是连续超过 6 个标记token的近似片段会被标记为可疑重复并且会计算每个文件的重复率。重复率超过 5% 就提示超过 10% 就报错。这里为什么用标记而不是用行数因为行数太容易被注释和换行干扰标记序列更能反映出“这段代码是从别处复制粘贴”的实质。认知复杂度这个概念也值得单独点一下。循环复杂度衡量的是“程序有多绕”认知复杂度衡量的是“人读起来有多烧脑”。二者是互补关系一个函数可能循环复杂度不高但多层嵌套加布尔表达式交叉人读起来照样很累。所以我在默认规则里对循环复杂度和认知复杂度是分别设阈值、分别报告的。2.3 忽略与渐进式接入别让历史债务阻塞新代码用过各种 lint 工具的人都知道忽略文件是接入时的生死线。t3code 的忽略机制借鉴了 .gitignore 的思路用独立的 .t3ignore 文件来控制# 构建产物与第三方代码 dist/ build/ coverage/ node_modules/ # 自动生成的 SDK 代码 vendor/stubs/** schema/generated/** # 存量代码库暂时豁免的区域 legacy/modules/legacy-order/**这套机制看起来简单实际上藏着两个关键设计。第一个是忽略是分层的。文件级的 ignore 只是最低一层上面还有规则级开关和目录级白名单。比如你可以对一个特定函数只关掉复杂度检查但保留其他所有检查而不是整段全部跳过。这比简单的“忽略文件”要精细得多团队里那种“这个文件问题太多干脆全部 ignore”的极端操作会被规则设计本身压制住。第二个是渐进式接入依赖 ignore但最终要脱离 ignore。我建议每个团队接入 t3code 时先允许把存量问题多的地方划入 ignore但同时要求每迭代清理一块并把对应目录从 ignore 里移除。这个过程虽然痛苦但不是技术问题而是项目管理问题。工具能做的是保证“新增代码必须过门禁”至于历史债怎么还节奏由团队自己定工具不越权。3. 实操过程与核心环节实现3.1 从零接入一个前端项目我拿一个标准的前端 monorepo 举例带大家过一遍真实接入流程。第一步是安装。t3code 发布在 npm 上也提供二进制安装方式我平时推荐使用 npm 全局安装或者通过项目内的初始化脚本拉起npm install -g t3code注意我建议把 t3code 装成全局 CLI 用于初始化但实际项目的命令最好还是走本地依赖。这样 CI 环境和本地环境才能锁定同一个版本避免“本地能过、CI 挂了”这种尴尬。第二步是初始化cd my-monorepo t3 init这一步会自动探测项目里的 package.json、ESLint 配置、TypeScript 配置然后生成一份初始的 t3.config.ts。这份配置会尽可能继承项目现有的生活习惯不会一上来就把所有东西推翻。第三步是跑首次全量检查但带上回顾基线的参数t3 check --baseline它会把当前的所有存量问题记录成一个基线文件。接下来团队要做的是确保新提交的代码不产生新的基线外问题而不是一口气把存量问题清零。存量问题的修复放在日常迭代里慢慢消化。3.2 t3.config.ts 核心配置逐项拆解初始化生成的 t3.config.ts 是整套工具的枢纽我用一个经过实际调优的例子来拆import { defineConfig } from t3code; export default defineConfig({ // 工具链集成优先复用项目现有的 ESLint 和 Prettier toolchain: { eslint: { useProjectConfig: true }, prettier: { useProjectConfig: true }, }, // 复杂度阈值 complexity: { cyclomatic: 15, // 循环复杂度警戒线 cognitive: 20, // 认知复杂度警戒线 maxDepth: 4, // 最大嵌套深度 maxLinesPerFunction: 80, }, // 重复代码检测 duplication: { enabled: true, minTokens: 6, // 连续 6 个 token 相同才认为可疑 fileThreshold: 0.05, // 单文件重复率超过 5% 提示 reportOnly: false, // 超过阈值是否直接报错 }, // 提交信息校验 commit: { types: [feat, fix, docs, refactor, test, chore], requireScope: false, maxLength: 100, }, // 目录结构约束红线规则 structure: { forbid: [src/utils/**/temp-*.ts], enforce: [src/modules/**/index.ts], }, // 忽略配置也可以直接写在 .t3ignore 文件里 ignore: { paths: [dist, build, node_modules], }, });几个容易被忽略的点我展开说一下。toolchain 里的 useProjectConfig 非常重要。t3code 的理念是“融入”而不是“取代”。如果项目里已经有一份精心调校过的 ESLint 配置那就直接复用t3 只负责调度让 ESLint 这部分的心智负担保持不变如果项目还没有任何配置再启用它内置的保守规则集。这样团队在迁移过程中只需要面对新工具带来的一小部分改变而不是一次面对全部改变。complexity 里的阈值我强烈建议把默认值当作上限而不是必须达到的目标。我见过很多团队用默认值跑完发现过了就觉得万事大吉了。实际上默认值是“通用场景下不至于太吵”的平衡点不是“高质量”的标准。如果团队里都是资深开发者可以考虑把循环复杂度压到 10 以下如果刚起步就先从 18 跑起来每月降 1慢慢逼近目标值。duplication 的 minTokens 参数也值得细抠。把 minTokens 调小比如调到 3会抓到大量无关的相似结构误报率飙升调到 10 以上又容易放过真正的复制粘贴块。6 这个数值是我在多个项目里试出来的中间点但如果您面对的是 SQL 这类重复文本特别多的场景可能需要上调到 8 或 9避免 SQL 片段因为结构相似而被误伤。structure 这块是 t3code 很特别的能力。它允许你把“这个目录禁止出现临时代码”“那个模块必须提供 index 出口”这类规则写进配置用机器强制取代口头约定。比如我上面的例子 forbid 了 src/utils 下的 temp- 开头文件这个规则看起来简单实际上能堵住非常多规范跑偏的情况。3.3 接入 Git Hook 与 CI 的完整链路命令行工具再强如果只靠人自觉去跑等于没装。t3code 必须跟 Git Hook 和 CI 结合起来。在接入方式上我首选Lefthook而不是早期的 husky。Lefthook 用 YAML 配置、直接原生跑二进制、速度更快且对 monorepo 的支持更好。不过这不重要大家用自己顺手的方式就行关键是 hook 里要跑什么。一个典型的 pre-commit 配置会做这几件事# .lefthook.yml 里的关键片段 pre-commit: parallel: true commands: t3code-staged: run: npx t3code check --diff --staged看明白了吗关键是两个参数的组合--diff 代表只检查相对于基线的差异部分--staged 代表只检入暂存区的文件。这两个参数配合能保证每次提交的检查范围足够小速度足够快不会出现“改一行代码结果跑全量检查等半分钟”的体验。CI 里的配置逻辑则完全相反CI 上要跑全量、要出报告、要留证据# GitHub Actions 的简化示例 - run: npm ci - run: npx t3code check --ci - run: npx t3code report --output coverage/t3code-report.json这里用了 --ci 参数它会自动做三件事从环境变量获取本次提交哈希和分支信息、屏蔽本地开发路径相关的误报、开启严格模式——任何一条警告都会导致退出码非零。报告文件会作为 CI artifact 保留下来方便之后回溯质量趋势。有一个细节我踩过坑一定要提醒本地 hook 和 CI 的检查范围必须一致否则会出现人格分裂。本地跑 --diff --stagedCI 跑全量那么本地永远不会发现的存量问题会在每次合并时变成红牌。这不是 bug恰恰是设计的一部分——本地管增量CI 管存量。如果团队暂时消化不了存量红牌就在 CI 配置里传入--baseline 文件让 CI 只对新增问题报红。4. 常见问题与排查技巧实录4.1 存量代码误报太多怎么让团队不炸锅这几乎是每个团队接入时第一个要面对的问题。处理不好工具上线当天就会被要求下线。我的建议是分层处理千万别“一刀切”。第一先分误报和真雷。跑完 t3code check --baseline 后把产物里的问题按规则类型做个分组。你会发现复杂度类问题最多重复类其次结构类最少。这三类问题的处理策略完全不同。复杂度类的用 ignore 白名单先豁免然后每个月重点清理 20 个最严重的函数作为专项排期推进重复类的挑出重复度最高的几个文件优先抽取公共函数这类清理收益立竿见影结构类的直接改存量里一般不多改完就能让整体结构立正。基线的意义在于它把“所有问题”变成了“新增问题”。团队的压力从“一次性解决所有历史债务”变成了“只要你不新增垃圾代码就行”。这个心态转变非常关键。4.2 t3 check 跑得慢先查三件事接入一段时间后最常见的抱怨是“命令越跑越慢”。我排查过各团队的情况九成问题出在以下三件事。第一全量扫描了不该扫描的目录。构建产物、第三方代码、庞大的测试 fixture 目录这些都要在 .t3ignore 里排除。我见过某团队把 coverage 目录代码覆盖率报告扫了十几秒纯属浪费。第二重复度检测的内存峰值过高。大仓库里标记化后的 AST 节点非常占内存。如果仓库超过十万行代码建议把 detection 调整为按文件并行处理并用增量模式运行。t3code 默认会做缓存只要文件没变二次运行会直接读缓存磁盘快照热启动通常能压到几百毫秒。第三误把 t3 check 当成了 t3 check --diff 在本地跑。日常开发只需要检查暂存区的变更即可没必要每跑一次全量。本地用 --diff --stagedCI 用全量这是效率和质量两全的核心编排。4.3 Hook 不生效多半不是工具问题我之前帮一个团队排查他们的 pre-commit hook 偶尔生效偶尔失效排了半天发现是切换分支时 Lefthook 的安装钩子没有同步更新。这种问题用一句经验总结就是钩子配置改了之后必须重新执行一次安装命令。另外还有一种常见情况hook 脚本里执行了 npx t3code但 npx 在 CI 容器或者某些受限环境里下载包很慢导致 hook 超时被杀。这种情况下不要用 npx 动态解析直接在 package.json 里声明 t3code 为 devDependencyhook 里调用 node_modules/.bin/t3code速度立刻提升。虽然 npx 很智能但在 hook 这种对耗时极敏感的场景里别让网络波动影响执行稳定性。4.4 本地绿、CI 红的版本漂移问题“在我机器上是好的”这句话在工程化不完善的团队里几乎是每日金句。t3code 本身对这个问题有明确解法项目级依赖 lockfile。具体操作是在 package.json 里把 t3code 固化到 devDependencies并提交 package-lock.json 或 pnpm-lock.yaml。这样本地和 CI 会从同一个锁文件解析出相同版本。同时在 CI 跑 t3 check 前最好加一步版本核对npx t3code --version不是看个热闹而是把这个版本号打进 CI 日志方便日后回溯“是不是这个版本引入的新规则导致红牌”。很多时候本地绿 CI 红不是逻辑差异单纯就是新版本里某个规则的默认行为变了。确认了版本漂移比抓瞎改代码要高效十倍。5. 后面我还想做的两个方向工具发布之后陆续收到不少反馈有两个方向我自己也一直在打磨顺手分享出来。第一个是把 t3code 从“检查工具”升级成“质量度量平台”。目前 t3code report 已经能输出 JSON 格式的质量快照我在做一个简单的趋势面板每个迭代对比平均复杂度、重复率、新引入问题数用趋势线告诉团队规范是在变好还是在偷偷腐烂。很多团队不是不想重视质量而是看不到量化趋势就不知道该什么时候出手全靠感觉。第二个是让规则能感知 AI 生成代码。现在很多编辑器里 AI 补全的代码和手写代码混在一起批量生成时最容易产生结构类似的重复块。我计划在重复度检测模块里加入对“高相似度片段密集区”的聚合提示让 t3code check 直接告诉你在哪个文件里存在“疑似整段 AI 生成且未 review 的高风险区域”。机器写代码不可怕可怕的是机器写完了没有人认真看。从我自己做 t3code 的整个经历来看工具本身的编码其实占不到一半工作量真正耗时的是琢磨“怎么让一个几十人的团队愿意用同一套标准、且不会觉得被束缚”。阈值怎么定、误报怎么处理、存量债怎么分期还这些听起来不像写代码那么酷但才是工程化真正落地的地方。t3code 解决的问题其实很朴素让代码规范这件事从靠人盯变成靠机制盯从藏在文档里变成跑在流水线里。 
长河君 · 2026/10/9 20:44:22 · 阅读 1.2k t3code：第三代代码规范工程化实践，一条命令统一质量检查
写代码这行当干得越久越觉得真正折磨人的不是写业务逻辑而是“让一群人长期稳定地把代码写规范”。我前前后后折腾过格式化工具、静态检查、复杂度检测、提交信息校验每一样单独拎出来都挺好用但凑在一起就是一团乱麻新成员要装一堆插件老成员各有各的配置PR 里永远在争论换行和缩进。后来我实在受不了自己动手收拢了一条命令行工具代号就叫t3code。t3code不是某个语言的新框架也不是又一个 lint 规则的集合。它是一条把代码规范校验、复杂度评估、重复检测、变更影响分析全部收口在一起的命令。核心思路是把“代码规范”从一份写在 Wiki 里的文档变成一套可执行、可量化、可追踪的工程化流水线让机器在提交前就把大部分质量问题挡在门外。这篇文章我把它的设计思路、核心配置、踩坑实录都摊开来讲适合正在做技术基建、带团队、或者被存量代码质量问题折磨得想换行的同学参考。1. 为什么叫 t3code第三代编码规范工程化思路1.1 “三代”到底指哪三代“T3”这个后缀不是随手起的。我在设计这套东西之前认真梳理过代码规范在团队里落地的方式演进大致能分成三代第一代是“人肉规范”。规范写在文档里、贴在群里、刻在老员工的脑子里。代码行没行尾分号、函数是不是写得太长、那个变量命名到底啥意思全靠 review 时人眼去挑。这套做法的问题很明显不可执行不可度量每个人对规范的理解都带私人滤镜。第二代是“工具约束”。ESLint、Prettier、TypeScript 类型检查、Stylelint 这些工具纷纷进场把格式问题和明显的逻辑问题交给机器。但这一代又走了另一个极端每个阶段只解决一个点彼此之间数据不相通。我用 ESLint 管代码风格用 Prettier 管格式用 SonarQube 管复杂度用 Commitlint 管提交信息结果 CI 跑了五六道独立的检查每次报错格式都不一样修完一个又冒出来另一个。第三代就是我想要的形态规范即代码门禁即命令。把分散在各个环节的检查聚合成一条流水线规则放在同一个配置文件里结果输出同一种格式的报告能力上做成可插拔。t3code 这个名字一是 Third-generation 的意思二是它给自己立了三个指标Predictable可预期、Traceable可追溯、Sustainable可维护。这三条我一直当成设计的北极星每个功能砍不砍拿这三条过一遍就清楚了。1.2 t3code 要解决的核心痛点我在维护 t3code 的过程里最常听到的一句话是“我们团队其实挺规范的就是没人监督。”这话翻译过来的意思是规范有但没落地工具也有但散落一地。具体拆解一下痛点其实是四个第一工具链七零八落。新成员入职光环境配置就能耗掉半天。每个人本地的插件版本还不一样同一段代码在不同人机器上检查结果可能都不一样。每个工具都有自己的配置文件、自己的忽略机制、自己的错误输出格式拼在一起就是一份冗长的“新手踩坑文档”。第二规范无法量化。文档里的规范写得再漂亮也回答不了“这个函数到底能不能超过 100 行”“重复代码比例多高就该重构”“复杂度上涨到多少会让下一个人读不懂”这类问题。没有量化就没有门禁没有门禁就谈不上规范。第三存量代码没有中间态。大多数团队不是从零开始接工具而是要面对跑了三五年、几万行甚至几十万行的老项目。全量开规则报错上万条开发直接宕机不开规则又等于没有接入。工具如果只有 0 和 1 两种状态那基本等于不适合真实团队。第四个痛点是最近一年特别明显的AI 生成代码多了机器审查必须跟上。过去代码是人写的风格相对统一review 盯逻辑就行。现在代码是 AI 补全的AI 写起来又稳又快但重复代码、过度封装、风格漂移这些问题呈指数级冒出来。靠人审已经审不过来了必须有一套能从结构和统计层面批量筛选的自动化审查机制。1.3 为什么选聚合式 CLI而不是做一个 IDE 插件我当时也有过要不要做 IDE 插件的念头后来果断放弃了。IDE 插件的问题是它管得住编辑器里的事管不住 CI 和 Git 的事。代码质量的门禁最终必须落在“提交”和“合并”这两个节点上而不是落在开发者本地按没按快捷键上。聚合式 CLI 的好处是它可以在开发者本地、CI 流水线、甚至服务器上的定时任务里跑同一个命令保证所有环境看到的结果一致。它不是一个编辑器插件而是凌驾于各种插件之上的统一入口。t3code check 这条命令执行的时候会先扫描项目当前的工具链再决定怎么调度有 ESLint 就调 ESLint有 Prettier 就调 Prettier在这基础上再做它自己独有的那部分——复杂度分析、重复代码检测、目录结构约束、提交信息校验。它不去替代你现有的工具而是把你的工具和缺失的环节一起收口。2. 核心细节解析与实操要点2.1 先看懂命令一条命令干了四件事t3code 的命令体系不长核心就是几条# 初始化配置生成 t3.config.ts 和 .t3ignore t3 init # 全量检查lint format 复杂度 重复度 提交信息 t3 check # 只看本次变更影响的范围 t3 check --diff # 尝试自动修复 t3 fix # 输出可视化的质量报告 t3 report这里面最核心的是 t3 check。它并不是只跑一种检查而是默认按顺序完成四层校验规范层调用项目里已有的 ESLint、Stylelint如果没有就用内置的轻量规则兜底复杂度层基于抽象语法树AST计算循环复杂度、认知复杂度、嵌套深度、函数行长重复度层对文件做标记化处理检测代码克隆找出 Copy-Paste 的重灾区变更层校验提交信息是否符合团队的约定格式同时对比 Git 基线识别本次改动有没有触碰“红线目录”。一次命令四种能力最后统一输出一份带文件级明细的报告。这不只是省几条命令关键是节省了“上下文切换”你不用在五个工具之间来回跳一份报告里就能定位所有问题。2.2 阈值不是拍脑袋复杂度与重复度的量化逻辑这一节我想重点聊因为这是 t3code 里最容易被人忽视也最值得琢磨的部分。很多人一上来就问“循环复杂度阈值默认多少”默认值是 15。但这个数字不是随便填的它的依据是业界多年积累的统计数据当函数循环复杂度超过 10 的时候缺陷率会明显上升超过 15缺陷率曲线会陡增。对于绝大多数业务代码函数能控制在 15 以内说明它逻辑分支不算失控。不过我这里要强调一个点阈值必须跟着团队现状走而不是跟着工具默认值走。新生项目可以从严直接设 10老项目建议从 20 甚至 25 起步然后每个迭代往下降。这个“降阈值”的过程本身就是一种技术债偿还机制比一次性推到 10 然后面对几千条报错要友好得多。除了复杂度还有一个参数也要重点关注重复度阈值。t3code 检测重复代码的默认策略是连续超过 6 个标记token的近似片段会被标记为可疑重复并且会计算每个文件的重复率。重复率超过 5% 就提示超过 10% 就报错。这里为什么用标记而不是用行数因为行数太容易被注释和换行干扰标记序列更能反映出“这段代码是从别处复制粘贴”的实质。认知复杂度这个概念也值得单独点一下。循环复杂度衡量的是“程序有多绕”认知复杂度衡量的是“人读起来有多烧脑”。二者是互补关系一个函数可能循环复杂度不高但多层嵌套加布尔表达式交叉人读起来照样很累。所以我在默认规则里对循环复杂度和认知复杂度是分别设阈值、分别报告的。2.3 忽略与渐进式接入别让历史债务阻塞新代码用过各种 lint 工具的人都知道忽略文件是接入时的生死线。t3code 的忽略机制借鉴了 .gitignore 的思路用独立的 .t3ignore 文件来控制# 构建产物与第三方代码 dist/ build/ coverage/ node_modules/ # 自动生成的 SDK 代码 vendor/stubs/** schema/generated/** # 存量代码库暂时豁免的区域 legacy/modules/legacy-order/**这套机制看起来简单实际上藏着两个关键设计。第一个是忽略是分层的。文件级的 ignore 只是最低一层上面还有规则级开关和目录级白名单。比如你可以对一个特定函数只关掉复杂度检查但保留其他所有检查而不是整段全部跳过。这比简单的“忽略文件”要精细得多团队里那种“这个文件问题太多干脆全部 ignore”的极端操作会被规则设计本身压制住。第二个是渐进式接入依赖 ignore但最终要脱离 ignore。我建议每个团队接入 t3code 时先允许把存量问题多的地方划入 ignore但同时要求每迭代清理一块并把对应目录从 ignore 里移除。这个过程虽然痛苦但不是技术问题而是项目管理问题。工具能做的是保证“新增代码必须过门禁”至于历史债怎么还节奏由团队自己定工具不越权。3. 实操过程与核心环节实现3.1 从零接入一个前端项目我拿一个标准的前端 monorepo 举例带大家过一遍真实接入流程。第一步是安装。t3code 发布在 npm 上也提供二进制安装方式我平时推荐使用 npm 全局安装或者通过项目内的初始化脚本拉起npm install -g t3code注意我建议把 t3code 装成全局 CLI 用于初始化但实际项目的命令最好还是走本地依赖。这样 CI 环境和本地环境才能锁定同一个版本避免“本地能过、CI 挂了”这种尴尬。第二步是初始化cd my-monorepo t3 init这一步会自动探测项目里的 package.json、ESLint 配置、TypeScript 配置然后生成一份初始的 t3.config.ts。这份配置会尽可能继承项目现有的生活习惯不会一上来就把所有东西推翻。第三步是跑首次全量检查但带上回顾基线的参数t3 check --baseline它会把当前的所有存量问题记录成一个基线文件。接下来团队要做的是确保新提交的代码不产生新的基线外问题而不是一口气把存量问题清零。存量问题的修复放在日常迭代里慢慢消化。3.2 t3.config.ts 核心配置逐项拆解初始化生成的 t3.config.ts 是整套工具的枢纽我用一个经过实际调优的例子来拆import { defineConfig } from t3code; export default defineConfig({ // 工具链集成优先复用项目现有的 ESLint 和 Prettier toolchain: { eslint: { useProjectConfig: true }, prettier: { useProjectConfig: true }, }, // 复杂度阈值 complexity: { cyclomatic: 15, // 循环复杂度警戒线 cognitive: 20, // 认知复杂度警戒线 maxDepth: 4, // 最大嵌套深度 maxLinesPerFunction: 80, }, // 重复代码检测 duplication: { enabled: true, minTokens: 6, // 连续 6 个 token 相同才认为可疑 fileThreshold: 0.05, // 单文件重复率超过 5% 提示 reportOnly: false, // 超过阈值是否直接报错 }, // 提交信息校验 commit: { types: [feat, fix, docs, refactor, test, chore], requireScope: false, maxLength: 100, }, // 目录结构约束红线规则 structure: { forbid: [src/utils/**/temp-*.ts], enforce: [src/modules/**/index.ts], }, // 忽略配置也可以直接写在 .t3ignore 文件里 ignore: { paths: [dist, build, node_modules], }, });几个容易被忽略的点我展开说一下。toolchain 里的 useProjectConfig 非常重要。t3code 的理念是“融入”而不是“取代”。如果项目里已经有一份精心调校过的 ESLint 配置那就直接复用t3 只负责调度让 ESLint 这部分的心智负担保持不变如果项目还没有任何配置再启用它内置的保守规则集。这样团队在迁移过程中只需要面对新工具带来的一小部分改变而不是一次面对全部改变。complexity 里的阈值我强烈建议把默认值当作上限而不是必须达到的目标。我见过很多团队用默认值跑完发现过了就觉得万事大吉了。实际上默认值是“通用场景下不至于太吵”的平衡点不是“高质量”的标准。如果团队里都是资深开发者可以考虑把循环复杂度压到 10 以下如果刚起步就先从 18 跑起来每月降 1慢慢逼近目标值。duplication 的 minTokens 参数也值得细抠。把 minTokens 调小比如调到 3会抓到大量无关的相似结构误报率飙升调到 10 以上又容易放过真正的复制粘贴块。6 这个数值是我在多个项目里试出来的中间点但如果您面对的是 SQL 这类重复文本特别多的场景可能需要上调到 8 或 9避免 SQL 片段因为结构相似而被误伤。structure 这块是 t3code 很特别的能力。它允许你把“这个目录禁止出现临时代码”“那个模块必须提供 index 出口”这类规则写进配置用机器强制取代口头约定。比如我上面的例子 forbid 了 src/utils 下的 temp- 开头文件这个规则看起来简单实际上能堵住非常多规范跑偏的情况。3.3 接入 Git Hook 与 CI 的完整链路命令行工具再强如果只靠人自觉去跑等于没装。t3code 必须跟 Git Hook 和 CI 结合起来。在接入方式上我首选Lefthook而不是早期的 husky。Lefthook 用 YAML 配置、直接原生跑二进制、速度更快且对 monorepo 的支持更好。不过这不重要大家用自己顺手的方式就行关键是 hook 里要跑什么。一个典型的 pre-commit 配置会做这几件事# .lefthook.yml 里的关键片段 pre-commit: parallel: true commands: t3code-staged: run: npx t3code check --diff --staged看明白了吗关键是两个参数的组合--diff 代表只检查相对于基线的差异部分--staged 代表只检入暂存区的文件。这两个参数配合能保证每次提交的检查范围足够小速度足够快不会出现“改一行代码结果跑全量检查等半分钟”的体验。CI 里的配置逻辑则完全相反CI 上要跑全量、要出报告、要留证据# GitHub Actions 的简化示例 - run: npm ci - run: npx t3code check --ci - run: npx t3code report --output coverage/t3code-report.json这里用了 --ci 参数它会自动做三件事从环境变量获取本次提交哈希和分支信息、屏蔽本地开发路径相关的误报、开启严格模式——任何一条警告都会导致退出码非零。报告文件会作为 CI artifact 保留下来方便之后回溯质量趋势。有一个细节我踩过坑一定要提醒本地 hook 和 CI 的检查范围必须一致否则会出现人格分裂。本地跑 --diff --stagedCI 跑全量那么本地永远不会发现的存量问题会在每次合并时变成红牌。这不是 bug恰恰是设计的一部分——本地管增量CI 管存量。如果团队暂时消化不了存量红牌就在 CI 配置里传入--baseline 文件让 CI 只对新增问题报红。4. 常见问题与排查技巧实录4.1 存量代码误报太多怎么让团队不炸锅这几乎是每个团队接入时第一个要面对的问题。处理不好工具上线当天就会被要求下线。我的建议是分层处理千万别“一刀切”。第一先分误报和真雷。跑完 t3code check --baseline 后把产物里的问题按规则类型做个分组。你会发现复杂度类问题最多重复类其次结构类最少。这三类问题的处理策略完全不同。复杂度类的用 ignore 白名单先豁免然后每个月重点清理 20 个最严重的函数作为专项排期推进重复类的挑出重复度最高的几个文件优先抽取公共函数这类清理收益立竿见影结构类的直接改存量里一般不多改完就能让整体结构立正。基线的意义在于它把“所有问题”变成了“新增问题”。团队的压力从“一次性解决所有历史债务”变成了“只要你不新增垃圾代码就行”。这个心态转变非常关键。4.2 t3 check 跑得慢先查三件事接入一段时间后最常见的抱怨是“命令越跑越慢”。我排查过各团队的情况九成问题出在以下三件事。第一全量扫描了不该扫描的目录。构建产物、第三方代码、庞大的测试 fixture 目录这些都要在 .t3ignore 里排除。我见过某团队把 coverage 目录代码覆盖率报告扫了十几秒纯属浪费。第二重复度检测的内存峰值过高。大仓库里标记化后的 AST 节点非常占内存。如果仓库超过十万行代码建议把 detection 调整为按文件并行处理并用增量模式运行。t3code 默认会做缓存只要文件没变二次运行会直接读缓存磁盘快照热启动通常能压到几百毫秒。第三误把 t3 check 当成了 t3 check --diff 在本地跑。日常开发只需要检查暂存区的变更即可没必要每跑一次全量。本地用 --diff --stagedCI 用全量这是效率和质量两全的核心编排。4.3 Hook 不生效多半不是工具问题我之前帮一个团队排查他们的 pre-commit hook 偶尔生效偶尔失效排了半天发现是切换分支时 Lefthook 的安装钩子没有同步更新。这种问题用一句经验总结就是钩子配置改了之后必须重新执行一次安装命令。另外还有一种常见情况hook 脚本里执行了 npx t3code但 npx 在 CI 容器或者某些受限环境里下载包很慢导致 hook 超时被杀。这种情况下不要用 npx 动态解析直接在 package.json 里声明 t3code 为 devDependencyhook 里调用 node_modules/.bin/t3code速度立刻提升。虽然 npx 很智能但在 hook 这种对耗时极敏感的场景里别让网络波动影响执行稳定性。4.4 本地绿、CI 红的版本漂移问题“在我机器上是好的”这句话在工程化不完善的团队里几乎是每日金句。t3code 本身对这个问题有明确解法项目级依赖 lockfile。具体操作是在 package.json 里把 t3code 固化到 devDependencies并提交 package-lock.json 或 pnpm-lock.yaml。这样本地和 CI 会从同一个锁文件解析出相同版本。同时在 CI 跑 t3 check 前最好加一步版本核对npx t3code --version不是看个热闹而是把这个版本号打进 CI 日志方便日后回溯“是不是这个版本引入的新规则导致红牌”。很多时候本地绿 CI 红不是逻辑差异单纯就是新版本里某个规则的默认行为变了。确认了版本漂移比抓瞎改代码要高效十倍。5. 后面我还想做的两个方向工具发布之后陆续收到不少反馈有两个方向我自己也一直在打磨顺手分享出来。第一个是把 t3code 从“检查工具”升级成“质量度量平台”。目前 t3code report 已经能输出 JSON 格式的质量快照我在做一个简单的趋势面板每个迭代对比平均复杂度、重复率、新引入问题数用趋势线告诉团队规范是在变好还是在偷偷腐烂。很多团队不是不想重视质量而是看不到量化趋势就不知道该什么时候出手全靠感觉。第二个是让规则能感知 AI 生成代码。现在很多编辑器里 AI 补全的代码和手写代码混在一起批量生成时最容易产生结构类似的重复块。我计划在重复度检测模块里加入对“高相似度片段密集区”的聚合提示让 t3code check 直接告诉你在哪个文件里存在“疑似整段 AI 生成且未 review 的高风险区域”。机器写代码不可怕可怕的是机器写完了没有人认真看。从我自己做 t3code 的整个经历来看工具本身的编码其实占不到一半工作量真正耗时的是琢磨“怎么让一个几十人的团队愿意用同一套标准、且不会觉得被束缚”。阈值怎么定、误报怎么处理、存量债怎么分期还这些听起来不像写代码那么酷但才是工程化真正落地的地方。t3code 解决的问题其实很朴素让代码规范这件事从靠人盯变成靠机制盯从藏在文档里变成跑在流水线里。