写 t3code 这个工具纯粹是被三个重复劳动逼出来的。日常开发里我同时维护前端项目和几个三维展示页面还要时不时代管一些文本预处理脚本时间长了就发现三件事特别烦手写 TypeScript 接口定义、反复调 Three.js 的场景初始化模板、提交代码前估算 token 消耗。t3code 就是我把这三件事揉到一起做的一个本地命令行工具核心能力是类型生成、Three.js 代码补全和 token 统计。它不会替代你的工程化体系但能把那些“谈不上难、就是费时间”的环节压缩到一条命令以内。如果你也经常跟 TS 类型、WebGL 场景或文本 token 打交道这篇文章值得读完。1. t3code 要解决的真实痛点与设计取舍1.1 三个让我想写工具的日常场景先说 TypeScript 类型生成。我接手过一个数据中台项目后端接口返回几十个字段的 JSON手写 interface 不算难但架不住字段多、嵌套深而且后端经常改字段名。每次联调都要对着接口文档敲一遍类型定义改一处就要顺着引用链改一串那段时间我一度怀疑自己是个“类型打字员”。后来我意识到大部分这类工作完全可以交给程序自动推断只要给它一份真实的接口返回样例。再说 Three.js。我经常要快速搭一个三维演示页面灯光、相机、渲染器、动画循环这些代码其实高度模板化但每次都要重新翻文档回忆参数。比如 PerspectiveCamera 的视野角度、近远裁剪面PointLight 的颜色、强度、衰减距离这些参数不查一下容易记错。更麻烦的是不同的性能面板、不同的环境光方案模板差异不算大却总得手打一遍。最后是 token 统计。我在给一些本地模型整理训练语料也在做 RAG 检索的文本切分需要提前知道一批文本大概会消耗多少 token。OpenAI 提供了 tiktoken但它是 Python 库命令行调用要包一层而且我们的文本里有大量中文注释和代码片段直接拿官方统计跟实际需求对不上。既然都要封装一版工具不如干脆做成一个通用 CLI。1.2 为什么是命令行而不是 IDE 插件我一开始想过做成 VS Code 插件但很快就否了。这种工具的使用场景很杂生成类型可能是在终端里跑的也可能是在 CI 流程里跑的Three.js 模板可能要在其他编辑器里用token 统计则几乎总是出现在 shell 脚本里。插件形态绑死了编辑器环境而命令行工具可以自由组合比如把 t3code 的生成结果通过管道交给 prettier 格式化再写进文件这在插件里不容易做到。另外命令行工具的测试和发布也更轻量。我没有精力维护多端插件市场CLI 只需要一个 npm 包名一条 install 命令用户环境里有 Node.js 就能跑不需要依赖具体 IDE 的 API 变化。1.3 项目架构一个入口三种能力t3code 整体结构并不复杂我把三个功能模块做成三个子命令主入口只负责参数解析和配置加载。仓库目录大概是这样的t3code/ ├── bin/ │ └── t3code.js # 入口解析子命令 ├── src/ │ ├── commands/ │ │ ├── type.js # 类型生成 │ │ ├── three.js # Three.js 辅助 │ │ └── token.js # token 统计 │ ├── core/ │ │ ├── config.js # 配置文件加载 │ │ └── logger.js # 输出格式化 │ └── utils/ ├── templates/ │ └── three/ # Three.js 代码模板 ├── t3code.config.json └── package.json架构上我坚持一个原则三个模块之间不共享复杂状态只复用最底层的配置和输出工具。这样做的原因是避免过度设计。以前我写工具容易犯一个毛病就是试图把所有功能抽象成一套“引擎”结果改一个功能要动全局。t3code 明确走“多个小工具、一个壳”的路线每个模块可以独立升级单独测试出问题也不至于互相拖累。2. 三大核心模块的实现原理与关键参数2.1 TypeScript 类型生成从样例到 interface类型生成的核心逻辑是读入一个 JSON 或 JS 对象样例递归遍历每个字段根据值的运行类型推断出对应的 TypeScript 类型节点。具体步骤如下解析输入文件支持 .json 和 .js 两种格式JS 文件会先通过 AST 解析找出默认导出或指定的对象。遍历对象属性判断值类型字符串映射为 string数字映射为 number布尔映射为 boolean数组则递归推断元素类型对象则继续深入。特殊值单独处理null 会被映射为 null 类型并登记为“可选字段候选”空数组被映射为unknown[]并给出提示日期字符串默认保留为 string除非开启--detect-date。组装成interface或type按缩进和排序规则输出。举个最简单的例子假设后端返回的用户信息长这样{ id: 1001, name: 北极, tags: [前端, 工具], profile: { age: 18, vip: true } }直接跑t3code type gen user.json --name ApiUser生成结果就是export interface ApiUser { id: number; name: string; tags: string[]; profile: { age: number; vip: boolean; }; }这里有个关键参数值得展开说。默认情况下单个数字、字符串会被推断成字面量类型还是基础类型取决于--literal-threshold这个参数。阈值的意思是当一个字段在多个样例中出现的不同值数量小于等于该阈值时推断为字面量联合类型超过阈值则退化为基础类型。我默认设成 3原因是阈值太小无法表达联盟类型阈值太大又容易把真实业务数据里的枚举值误当成固定常量。还要处理“可空字段”。接口返回里经常出现null比如一个用户可能没有手机号字段值为 null。t3code 提供了三种可选模式可选模式生成结果适用场景--optional-mode questionphone?: string字段可能不存在时--optional-mode unionphone: string | null字段存在但值为空时--optional-mode nullablephone: string | null同时生成type而不是interface需要严格空值语义时接入后端时我几乎总是选union模式因为接口契约里如果明确返回了null说明这个字段“在响应里出现过”用可选符号反而掩盖了真实结构。这个坑我一开始踩过生成的类型看起来挺干净但真正解析数据时空值判断逻辑全乱了。2.2 Three.js 辅助场景描述到可运行代码Three.js 模块不是什么“人工智能生成代码”而是一套把场景描述关键词映射到模板的匹配引擎。实现思路很简单我把最常见的三维场景初始化和常用元素拆成模板片段每个模板片段带有若干标签比如cube、rotate、point-light、orbit-controls。当你输入自然语言描述时t3code 会做关键词切分和权重匹配把命中的模板组装起来。比如输入t3code three scene 旋转立方体 点光源 背景色匹配到的模板组合会生成这样的代码import * as THREE from three; const scene new THREE.Scene(); scene.background new THREE.Color(0x20232a); const camera new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100); camera.position.set(3, 2, 5); camera.lookAt(0, 0, 0); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(innerWidth, innerHeight); document.body.appendChild(renderer.domElement); const cube new THREE.Mesh( new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ color: 0xffffff }) ); scene.add(cube); const light new THREE.PointLight(0xffffff, 1, 10); light.position.set(2, 3, 4); scene.add(light); function animate() { requestAnimationFrame(animate); cube.rotation.x 0.01; cube.rotation.y 0.01; renderer.render(scene, camera); } animate();注意这里有几个参数不是随便给的。视野角度默认 45 度是因为这个值最接近人眼自然视角不容易产生畸变near 和 far 裁剪面设成 0.1 和 100覆盖了绝大多数演示场景的尺寸范围点光源的强度给到 1、距离给到 10是配合默认尺寸的立方体来调的太暗或太远都会让物体看起来发灰。这些默认值不是死规矩它们只是为了让你第一次运行就能看到东西想微调再改参数也不迟。模板匹配最有意思的问题是权重。一个场景描述里可能同时出现“红色立方体”和“旋转动画”模板库里的 cube 模板和 rotation 模板都能命中。t3code 会给每个关键词算一个相关度得分命中次数多且标签权重高的模板排在前面。如果描述太复杂导致匹配结果不理想可以直接指定模板名t3code three scene 红色茶壶 --template teapot开发过程中我最怕模板库无限膨胀。目前 templates/three 目录下有 40 多个模板覆盖了初始化、基础几何体、灯光、相机控制、粒子、后处理这几大类。超过 50 个以后模板解析启动时间会明显变长而且匹配时产生歧义的概率也变大。这个数量级是我测试下来比较舒服的平衡点。2.3 Token 统计为什么自己造轮子Token 统计算是最有“复用”价值的功能因为 tiktoken 本身就是 OpenAI 开源的成熟库。但直接拿来用有几个问题第一tiktoken 官方是 Python 库在 Node 生态里要借助绑定包安装步骤多了好几层第二很多项目并不只用 OpenAI 的模型本地模型用的词表可能是其他 BPE 实现统计口径不一致第三我需要的是对目录级别做批量的 token 估算而不是在 Python 脚本里手动循环调用。所以 t3code 的 token 模块做了一层兼容层底层词表可以加载多种 BPE 编码默认是cl100k_base也就是 GPT-4 系列用的词表也支持通过--model参数切换其他编码。核心统计流程是遍历目标目录按扩展名过滤代码、Markdown、纯文本等类型。读取文件内容按配置决定是否剥离注释。默认剥离//、/* */、!-- --和#开头的注释行。对文本做预分词中文按字符切分后合并英文和数字按空格和标点粗分。用 BPE 词表对粗分结果做合并累加得到 token 总数。输出统计表包括文件数、总 token 数、代码 token 占比、注释 token 占比。跑一下t3code token count src/ --model cl100k_base --detail输出大概是文件数 12 总 token 18,432 代码 token 11,205 注释 token 5,217 中文字符占比 31.2%这里最需要注意的是统计口径的对齐。同样一段代码开不开注释剥离token 数可能差出一大截不同模型的 BPE 词表不同同一个句子的 token 数也可能不同。我踩过比较深的一个坑是用cl100k_base统计的数据去预估某个本地模型的训练成本结果偏差接近 15%。后来所有统计都显式传--model参数并把模型名一并写进输出结果里才彻底解决这个“数字对不上”的困惑。3. 从安装到写进工作流t3code 实操全记录3.1 三分钟装好并初始化安装条件只有一个本机有 Node.js 18 以上版本。直接全局安装npm install -g t3code装完先初始化配置文件这样不用每次敲一堆参数t3code init运行后会在当前目录生成一个t3code.config.json我的推荐配置是这样{ type: { optionalMode: union, literalThreshold: 3, indent: 2, detectDate: false }, three: { templateDir: ./templates/three, defaultBackground: #20232a, preferModule: true }, token: { defaultModel: cl100k_base, includeComments: false, chunkSize: 512KB } }indent控制输出缩进接进前端项目时建议跟 ESLint 的缩进规则统一preferModule让三模块输出 ES module 风格的导入语句chunkSize是 token 统计时按块读取文件的大小目录特别大时可以调小避免内存暴涨。3.2 高频命令实战type、three、token类型生成最常用的命令是这样的t3code type gen ./mock/api-user.json --name ApiUser --optional-mode union --out ./src/types这条命令会根据样例文件生成ApiUser接口并写到src/types目录下。如果不想输出到文件也可以去掉--out结果会直接打到标准输出方便你 pipe 给别的工具比如t3code type gen sample.json | prettier --stdin-filepath sample.tsThree.js 辅助命令的完整用法t3code three scene 带轨道控制的地球模型有环境光 --template orbit-earth --out ./src/three/scene.ts场景描述匹配不到合适模板时先看看t3code three list里有哪些可用模板再决定是换关键词还是指定模板名。模板列表我按功能做了分组初始化类basic-scene、full-scene、ssr-scene几何体类cube、sphere、plane、torus-knot、text-geometry灯光类ambient-light、point-light、directional-light、spot-light控制类orbit-controls、pointer-lock特效类particles、post-processing、glowtoken 统计最实用的命令t3code token count ./docs --model cl100k_base --include-commentstrue --detail如果你只想快速算一段文本也可以直接从标准输入读echo hello world | t3code token count --stdin3.3 把 t3code 接进脚本、编辑器和提交流程真正让 t3code 发挥价值的是跟现有工作流串起来。我在package.json里加了这么几个 script{ scripts: { gen:types: t3code type gen ./mock/*.json --out ./src/types, scene:init: t3code three scene \rotation cube point light\ --out ./src/three/init.ts, tokens: t3code token count ./src --include-commentsfalse } }这样团队里其他成员不用记 t3code 的参数直接npm run gen:types就行。编辑器里我把它配成了 VS Code 的 task按快捷键就能生成类型定义并自动格式化省得来回切换终端。提交前流程我只建议加 token 统计这一步别把类型生成设成提交钩子。原因后面会讲。4. 我踩过的坑t3code 常见问题排查速查表4.1 类型生成最常见的“过度推断”问题我最早版本的类型生成器有个毛病会把样例里的单个值直接推断成字面量类型。比如样例里status: 1生成的是status: 1而不是status: number看起来精确实际害死人因为后端只要多返回一个 2这个类型就崩了。后来加了--literal-threshold参数默认 3意思是同一个字段在多个样例中出现不同值的数量不超过 3 时才推断为字面量联合类型。如果你手上只有一条样例建议干脆设成 0彻底关掉字面量推断全部用基础类型。4.2 Three.js 匹配不准模板与权重调整“旋转立方体”这种描述匹配率一直不错但碰上“一个发光的红色球体在转”这种口语化描述就会在球体、灯光、旋转三个模板之间摇摆。我的解决方法是两层第一层是给模板加同义词标签比如“球”和“ball”都映射到 sphere 模板第二层是支持手动覆盖匹配结果不满意就用--template直接指定。这不算优雅但在实际使用里够用毕竟三维场景的初始化代码就那么几种变体。4.3 Token 口径不一致如何对齐官方统计如果你拿 t3code 统计出来的数字跟 OpenAI 接口返回的usage.prompt_tokens对不上先检查两件事。第一注释有没有被剥离官方接口统计的是完整输入内容包括注释所以对比时要不就两边都算注释要不就两边都不算。第二词表是否一致cl100k_base和p50k_base对同一段文本的结果不同必须显式指定模型。我在输出里加了一行模型标识就是为了避免隔几天回来忘了这组数据是用哪个词表算的。4.4 问题排查速查表现象原因解决方法类型生成把0推出0而不是number字面量阈值太低--literal-threshold 0或用多条样例JSON 样例里有空数组生成unknown[]无法推断元素类型换一条更完整的样例或手动给该字段加类型注释Three.js 模板匹配到无关模板描述里关键词权重过低t3code three list查模板名后--template指定token 统计跟官方对不上注释统计口径或词表不同对齐--include-comments并--model指定词表大目录统计时内存飙升一次性读入全部文件设置--chunk-size按块读取中文长文本 token 数偏高中文按字切分后再 BPE 合并与真实分词有差距有自定义词表时挂载--vocab没有则接受近似结果最后分享两个我实际用下来的小经验。第一别把 t3code 类型生成接进提交钩子。自动生成类型后如果直接提交很容易产生大量无意义的 diff尤其是接口字段顺序一变整个文件都跟着重排评审的人会疯掉。我现在的做法是生成到临时目录人工 diff 之后再合并。第二token 统计除了算成本还能当“代码可读性探测器”。如果一段代码注释占比超过 40%说明注释多到可能影响整洁度如果低于 5%说明关键逻辑缺少说明该补文档了。这个指标不严谨但用来提醒自己挺有效。t3code 算是我个人工具列表里“小但高频”的那一类它不解决架构问题也不替代任何重型框架只是把三件琐碎事压成了三条命令。如果你也想复制这套思路记住一点就够了命令行工具最怕的不是功能少而是边界失控。t3code 从第一天就限定自己只做类型、三维辅助、token 这三件事其他需求一概不进主仓库这种“克制”反而是它到现在还没被我丢掉的原因。