企业官网建设流程全解析

t3code 这名字，老粉看到可能会愣一下：是 T3 Stack 那套技术栈？还是某个开源仓库？我刚听说时也这么猜过。真正把它跑起来用了两周，我现在的看法很直接：t3code 是一个以"整个仓库"为工作对象的 AI 编码代理，它和自动补全不是一个物种。它能自己读代码、改文件、跑测试、再迭代，直到把任务做完。这篇文章不是官方文档的复述，而是我把它塞进真实项目里的现场记录：哪些配置值得花时间，哪些坑我踩过了，什么任务能放心交给它，什么任务交给它，第二天可能给你造出"惊喜"。

我手上有两个业务系统，一个 8 万行，一个 20 万行，另外还有几个一次性脚本项目。之前用逐行补全类工具，感觉效率提升有限——它只给我补行，不帮我理解整个模块。改一个跨了四五个文件的老接口，该翻的代码一行都省不了。所以看到代理式的工作方式时，我心里有两个问题：它真能把"小活"直接干完吗？它会不会在我不注意的时候把我仓库搞乱？这两周里，两个问题都有答案了。

1. 为什么要把 t3code 放进日常开发流程

1.1 它想解决的不只是"补全代码"

先做一个类比：补全工具像是输入法的联想，你打一个字它猜下一个字；t3code 更像是给一个上手快但粗心的小实习生布置任务。你给一个目标，它自己会去翻资料、改草稿、跑一遍自检，然后把结果拿来给你看。这个区别很重要，因为它决定了你要用什么样的心态去用它——你不能像用补全工具那样一直盯着屏幕，你只能在几个关键节点做验收。

那它具体能做什么？我在第一个测试项目（一个小工具仓库）里给了它三件事：给一个老的 Python 模块补单元测试；把散落在三个文件里的常量收敛到一个配置类里；修掉 lint 配置升级后冒出来的一百多个告警。三件事都不难，但都属于"脏活累活"，逐个人工干至少要半天。t3code 处理这三件事，先把每个文件打开、把符号关系搞清楚，然后批量改，改完还自己跑了一遍测试。我检查结果时发现质量比我预想的稳定，但也发现它有几个固定的毛病，后面专门开一节说。

了解它的工作方式之后，我真正想问的是：它到底改变了开发流程里的哪个环节？结论是"理解成本"。传统方式下，改一处跨文件逻辑，你要先在脑子里建立一张影响面图；t3code 能替你把这步做了，它给出的 diff 本身就是在展示它对影响面的判断。省下的时间可以用来做更重要的代码审查，而不是花在"找出所有调用点"这种机械劳动上。

1.2 尝试前的三个判断标准

不是所有项目都适合立刻引入，我试之前给自己定了三个条件：

• 仓库必须能随时回滚。git 工作区要干净，分支要清楚，任何一次 t3code 的改动都能一条命令退回。别在改动了一半的本地分支上直接让它开工，否则它基于的基线是脏的，出了问题你分不清哪些是它的错、哪些是你改到一半的烂摊子。
• 有能跑的测试。哪怕是覆盖率很低的旧项目，至少有一个 make test 或者 npm test 能一键执行的东西。没有这个保护网，AI 跑得越快，你事后排查越慢——它改坏的代码不会自己告诉你。
• 任务结果可以被客观验证。比如"补测试""修 lint""重命名"这类有明确完成标准的任务；相反，"让这个模块更优雅"这种任务，AI 会给你做出非常主观的改动，你很难验收。

我的测试仓库三个条件都满足，所以我才敢让它放开手跑。如果你手头是个连 CI 都没有的历史遗留项目，我强烈建议先把最小测试链路搭起来，再考虑引入 t3code。这个顺序不能反。

2. 首次跑通 t3code 的最小化配置

2.1 环境准备与模型接入

我第一版接入方式非常朴素：一个干净的 Python 3.11 虚拟环境，装好 t3code 的命令行入口，然后在项目根目录放了一份模型接入的配置。它支持接入托管的模型服务，也支持对接私有化模型端点，我用的私有化端点，原因很简单：测试仓库里有一些内部业务的 schema，我不想把表结构送去外部服务。这个考虑在多数公司项目里都成立。

我的配置大概长这样，路径和密钥做了脱敏处理：

T3_MODEL_ENDPOINT=https://内部网关/v1 T3_API_KEY=**** T3_MODEL_NAME=qwen2.5-coder:32b T3_CONTEXT_POLICY=repo-aware

这里最需要注意的是CONTEXT_POLICY。它决定了 t3code 会以多广的范围去理解仓库。我一开始用的默认策略，它只看当前工作区附近几个文件，遇到跨目录的引用就开始瞎猜；改成 repo-aware 之后，它会先建一次仓库索引，后面每次动手前把相关文件一起拉进上下文，准确率明显上了一个台阶。当然代价是慢，第一次索引一个 8 万行的仓库，在我的机器上跑了大概两分钟。这个时间值得花。

如果你用的是云端模型，注意把敏感信息和密钥管理好，别直接用真实 key 写进脚本里。我见过有人把密钥直接打在配置里然后推到远端仓库，这个失误比 t3code 本身容易出现。

2.2 第一次派活：任务描述怎么写

把任务描述清楚，是影响 t3code 输出质量的最大变量。我的第一个任务是这样写的：

任务目标：为 src/legacy_payment.py 中的 PaymentProcessor 类补充单元测试。 验收标准： 1. 覆盖 process() 的所有分支，包括成功、余额不足、重复回调三种情况； 2. 不修改业务代码，只新增测试文件； 3. 用 pytest 运行全部测试并通过； 4. 不要改动 src/ 目录下任何文件。 约束：如果发现测试需要 mock 数据库连接，请仅 mock 在 tests/conftest.py 中声明。

注意我做了什么：给了文件路径、类名、验收标准、明确的禁止项、以及 mock 的处理位置。这里面第二条是最关键的——AI 编码代理有一个倾向，就是"为了让测试好写"顺手去改业务代码，如果不提前禁止，它很可能给你返回一个"全绿"但已经悄悄重构过的仓库。

我后来给团队总结了写任务的四要素：做什么、在哪里做、怎样算完成、什么绝对不能做。四要素缺一个，输出质量就会肉眼可见地下降。

2.3 输出检查的第一站

t3code 完成后，我没有直接看测试结果，而是先看 diff 的统计和摘要。这一步别省。一个几千行改动的差异，第一眼就要判断它的改动范围是否合理。我那次任务它新增了一个测试文件，同时真的没有碰 src/，符合预期。

接着我逐个看 diff 的关键片段，重点关注 mock 是否写对、断言是否真的能生效。这里有个反直觉的点：AI 生成的测试代码，断言很容易写成"恒真"——比如 mock 了返回值之后又断言返回值等于那个 mock 值，这种测试什么都不验证。我抓到过不止一次。所以测试类任务，我会随机抽几个用例，把 mock 值改成明显不合理的"脏数据"，看断言会不会失败。不会失败，说明这条断言大概率在自说自话。

这样第一轮跑通之后，我对 t3code 的使用方式就有了底气：它可以干活，但必须配合一套固定的验收流程。这比任何参数调优都重要。

3. 真实项目里的 t3code 协作模式

3.1 把边界划清楚：哪些目录不归它管

跑过测试项目后，我把 t3code 引进了那个 20 万行的业务系统。进去之前我做的第一件事不是写任务，而是划边界。业务系统里有一些目录，AI 改不得：数据库迁移脚本、支付相关的核心领域对象、以及部署配置。我不是不相信它，而是这些目录一旦改错，代价是线上事故级别，不值得用"AI 试一下"去赌。

t3code 支持在配置里声明可写目录和只读目录。我的配置是这样：

[permissions] allowed = ["src/", "tests/", "scripts/"] read_only = ["src/main/java/com/company/payment/", "db/migrations/", "deploy/"]

这个设置效果非常直接：它彻底断了 AI 在我最担心的区域动手的可能性，同时在允许区域内它可以放心干。配置完之后我在 README 里给团队写了一句约定：进 CI 的任务，默认只能在允许目录内修改；如果任务确实要碰只读目录，必须显式在任务描述里说明理由，走一遍人工确认。

边界还有一个好处：它可以帮你做"影响面收敛"。AI 编码代理默认是无边界的，它不知道哪些文件"碰不得"，只靠自然语言约束很容易漏。给它的文件系统权限加上物理上的限制，比多写两行提示词靠谱得多。

3.2 上下文管理：仓库理解越深，幻觉越少

划线之后我用它做的第一个真实任务，是重构一个订单状态的枚举。这个状态枚举散在六个文件里，有的文件通过字符串比较，有的通过常量引用，还有一个老接口直接用了魔法值。我一开始试图用一段任务描述说清楚所有位置，结果漏了那个用魔法值的文件，t3code 改完之后那个文件的判断逻辑就断了。

那次翻车让我意识到：任务描述里写的位置总会有遗漏，更好的办法是让 t3code 先建好仓库索引，然后直接问它"订单状态一共有哪几种引用方式"。它会基于索引把引用点列出来，我再拿这个列表核对，比我自己回忆靠谱。从那以后，我的工作方式变成了两段式：先让它做一次"侦察"，再开始正式任务。

仓库理解深了之后，幻觉的概率明显下降。之前它在不确定某个符号含义时，会倾向于猜一个“看起来合理”的写法；有了索引和上下文，它更倾向于先查再答。代价是每次任务的启动时间变长，但换来的是后期 review 时间大幅缩短。两相对比，很划算。

3.3 擅长 vs 不擅长的任务

用了一个月，我整理了一张任务类型对照表，贴在团队文档里：

为什么批量重命名和样板代码这类任务效果好？因为它们本质上是确定性转换，规则清晰、验收标准客观。为什么产品判断类任务差？因为产品逻辑需要的是“为什么这么设计”的背景理解，而 t3code 能看到的是代码形态，不是决策过程。多出来的“历史包袱”它没法替你判断。

这张表的意义不在于清单本身，而在于让团队在使用前就对齐预期。预期对齐之后，AI 工具就不会被神化，也不会被一票否决。

4. 踩坑记录：t3code 翻车的四种典型场景

4.1 第三方依赖幻觉：一本正经地建议不存在的包

第一次翻车在一个日志改造任务上。我让 t3code 把项目里散落的logging.info统一到一个日志工具类。它改得很快，但改完之后的代码里出现了一个我从来没见过的包，我查了一下，那个包根本不存在于 PyPI。它不仅在 import 里写上了，还写了对应的调用代码，看起来完全自洽。这是因为模型在训练数据里见过类似的工具库命名，于是“合理地”编造了一个。

这类问题的危险在于：它埋在成百上千行 diff 里，不会自己报错。我后来养成了一个习惯，凡是用它引入的新依赖，必须单独列出来人工核对。还让 t3code 自己在任务描述里加一条约束：“不要引入任何新的第三方依赖；如果确有必要，请在结果里单列一个依赖变更清单。” 这比事后翻 diff 高效得多。

4.2 过度删除：“没用到”和“真的没用到”是两回事

另一个让我印象深刻的翻车，是它主动删掉了一个“看似没用”的函数。那次任务是清理一个模块的未使用代码，t3code 扫描引用关系后，发现某个内部函数的调用方都被替换成新实现了，于是把这个函数标记为 dead code 删除了。但它不知道的是，这个函数是留给外部系统回调用的，接口契约还在，只是项目内部不再有人调用。

我直到联调时才发现问题。修复的过程不难，但带来的教训很深：t3code 的判断基于它能看到的代码，而系统边界往往存在于它看不到的外部。从那以后，凡是涉及删除的任务，我都会明确写一条：“删除前先列出清单，我确认后再删”。它照做之后，我每次都能看到完整的删除预案，再也不会出现“被删了什么都不知道”的情况。

4.3 测试通过不等于需求完成

还有一次它给了我一个非常漂亮的测试报告：新代码覆盖率从 40% 提到 78%，全部用例通过。我一度很开心，但后来发现它绕过了最关键的异常分支：那个分支里调用了外部订单服务的接口，它通过 mock 把整个服务层全部替换掉了，断言只验证了 mock 被调用，没验证 mock 被调用时的参数是否正确。测试通过，但业务行为完全没有被保护。

这个案例告诉我一个通用结论：AI 生成的测试通过，只能说明“它自己定义的世界里一切正常”，不代表“真实世界里的行为符合预期”。所以我给测试类任务的验收清单多加了一条“打断点看关键路径的真实取值”，人为把真实函数拉进测试路径，验证它确实在用真实逻辑跑。

4.4 权限过低时它反复绕圈

最后一种翻车不是代码问题，是行为问题。在某个子项目里我把权限配得过严，允许目录只剩一个src/tmp/，结果它面对一个本来 10 分钟能完成的任务，绕了二十多分钟：找不到可以落笔的文件，就开始不停读文件、猜测、自我怀疑，最后给出一个“我无法完成任务”的长篇解释。整个过程消耗了大量 token，产出为零。

这次之后我学到的经验是：给 AI 的权限既不能太大，也不能太小。太小会让它陷入“探索死循环”，看起来在干活，实际上在原地打转。合理的做法是给一个“最小但完整”的工作区——它要完成某个任务，需要的相关目录都要可写，但绝不能碰的区域必须锁死。这个尺度要根据任务类型动态调整，而不是一刀切。

5. 我给团队定下的 t3code 落地规范

5.1 任务分级：哪些可以自动，哪些必须人来写

经过几次踩坑，我总结了一套任务分级，现在团队里新需求进来第一件事就是给需求定级：

• 全自动档：批量重命名、补注释、格式化、按模板生成。这些任务验收客观、风险低，t3code 做完后只要 CI 通过就能合入。
• 半自动档：补测试、小范围重构、依赖升级。这些任务需要 t3code 先出方案，我 review 方案后再让它执行。
• 人工专享档：涉及支付、权限、数据删除、对外接口契约的改动。这些任务 t3code 可以参与代码解读和方案讨论，但不能直接改代码。

这个分级本质上是在回答一个问题：我们愿意为 AI 的失误付出多大的修复成本。修复成本越低的任务，越可以放手；修复成本越高的任务，越要早做拦截。

5.2 产出校验：接入 CI 之前先过三关

任何 t3code 的产出，在进入正式 CI 之前，都要过我自己定义的三关：

第一关，diff 范围关。打开变更统计，看它改了哪些文件，是否在允许目录内，有没有不该出现的大段删除。这一关 30 秒就能完成，却能把绝大多数事故拦在外面。

第二关，新依赖关。把新增的 import 和依赖声明扫一遍，逐个确认来源和版本。这关是专门针对“依赖幻觉”设计的。

第三关，关键路径抽查关。随机挑两到三个任务描述里提到的核心场景，人工走读一遍代码路径，确认逻辑确实按照预期在走，而不是“输出看起来合理”。

我后来把这套流程做成了一段脚本，用 diff 的元数据做硬校验，人工只负责抽查。这套组合拳下来，t3code 的产出质量稳定了不少，团队对它的信任度也上来了。信任不是靠感觉，是靠可重复的校验流程。

5.3 失误记录与提示词复盘

最后是一点长期经验。每次 t3code 翻车，我都会把当时的任务描述、它的错误输出、以及正确的做法整理成一则“失误样本”，放进项目里一个专门的目录。这有几个实际用处：

• 下次再写类似任务时，我会把过去的失误直接写进约束里，比如“注意外部回调函数不可删”“不要引入新依赖”。
• 失误样本积累了十几条之后，能明显看出 t3code 的失误模式是有限的，集中在那几类。知道了底牌之后，使用它的时候心里非常踏实。
• 这些样本还可以作为后续接入其他 AI 编码工具的验收测试集。谁能在这些场景下不犯同样的错，谁就更有资格接管你的代码库。

做这件事不需要花很多时间，每次翻车花五分钟记录一下，累积起来就是一笔只属于你自己的“AI 使用手册”。

我现在的状态是：t3code 进了日常工作流，但没有被当成“自动驾驶”。它帮我处理了大量脏活累活，也帮我更快地摸清了老仓库里那些没人愿意碰的角落；同时我也付出了更严格的审查流程和时间成本。这两周体验下来，最深刻的感受是：AI 编码代理真正的门槛不在工具本身，而在使用者在多大程度上愿意为它的输出负责。把它当成一个执行力很强但缺乏判断力的同事，各取所长，才是比较健康的位置。