企业官网建设流程全解析

一个人、九个月、20万行代码、每个月烧掉40亿+ token——这些数字放在一起，外人可能会以为是一个小团队在冲刺，但确实是一个人在造一款Harness架构应用时的真实账单。不是标题党，也不是段子，而是我过去九个月的真实节奏：白天写设计、晚上喂AI、周末重构，月均tokens消耗稳定在40亿以上。今天把这九个月的思路、踩坑和数据整理出来，对想用AI辅助独立开发的朋友应该有点参考价值。

先回答大家最关心的问题：这款Harness架构应用到底做什么？简单来说，它是一套面向AI工作流的执行框架，把模型调用、工具执行、状态管理和安全校验封装成可插拔的层，让AI能力可以稳定地接入业务场景。说白了，就是给AI这匹烈马套上马具，让它既能跑得快，又不会脱缰。

1. 先交代背景：为什么一个人敢碰Harness架构

1.1 一句话说清Harness架构

好多朋友第一次听到“Harness架构”都问同一个问题：这东西跟微服务、事件驱动有什么区别？是不是又一个造出来的概念？

我的回答是：Harness架构不是全新的架构范式，而是一种专门为AI应用设计的代码组织方式。它把应用拆成五层——模型接入层、工具执行层、状态管理层、安全校验层、编排层，每层有清晰边界，层与层之间只通过接口通信。这样做的直接好处是：AI生成代码时，只要约定好每层的接口，它就能按模板填代码，不大会出现“生成一个函数，结果它顺手改了别的模块”的情况。

Harness这个词的英文原意是“马具”。烈马有跨越复杂任务的潜力，但能不能安全地骑上去、控制方向，取决于缰绳、马鞍设计得好不好。Harness架构就是那副马具，它不提供模型能力，但决定了模型能力能不能被稳定地、安全地用起来。我见过太多AI应用，模型效果好得一塌糊涂，一接进生产环境就崩，原因不在模型，而在承载模型的这套“鞍具”做得太粗糙。

这个概念本身不是学术定义，更像是我在实践里总结的工程经验。对个人开发者来说，它的价值在于把“让AI做事”变成“让AI在我划定的安全区内做事”，这对后续九个月批量产代码至关重要。

1.2 为什么一个人花九个月做这个

很多人听到“一个人+20万行代码+九个月”会觉得我疯了。为什么不先做个简单的小工具，跑通一个需求，再慢慢迭代？其实这个选择背后有三层考虑。

第一，AI应用正在快速从“单一模型调用”走向“多工具编排”。真正卡住应用的往往不是模型效果，而是“代码架构扛不住复杂AI交互”。市面上的重框架适合团队，轻框架只适合做Demo，中间恰好空出一块“个人开发者用得上、又愿意接受低成本”的地带。我想填的就是这个空档。

第二，单人开发最大的优势是决策链路短。架构上任何地方不顺眼，我可以当天就暴力重构，不需要说服同事。团队里常见的“架构演进需要评审”在这里完全不成立。九个月里我确实重构了好几次，每次都是说改就改，这是我敢碰重架构的底气。

第三，我想真实验证一件事：在AI辅助编程已经足够成熟的今天，一个人到底能不能在九个月内交付一个团队级别复杂度的产品。结论是可以，但前提是——你得有意识地管理token、管理上下文、管理AI产出代码的质量，而不是把AI当无限生成器。

2. AI辅助开发：20万行代码是怎么和AI“结对”写完的

2.1 每个月的token账单到底花在哪

先放数据。不含闲聊和实验性调用，我每个月的token消耗大致分成四块：

按通用token计数规则，1个token大约对应0.75个英文单词。40亿token粗略折算就是30亿个单词，平均每天一亿多个token输入到模型API里。这大概是我这个项目最大的一笔运行成本，也是很多人听到数字就会被吓住的地方。

好在我消耗的不是一次性算力，而是有效产出。代码生成部分真正落进仓库的比例，前三个月只有三成左右，到后面稳定在六到七成——这说明AI辅助开发的效率，很大程度取决于你怎么提需求，而不只取决于模型有多强。

2.2 我拆任务的“代码原子化”方法

20万行代码如果指望AI一句话生成，结果大概率是一堆让人崩溃的垃圾。我摸索出一套叫“代码原子化”的拆解方法：把一个完整功能不断向下拆，拆到每个任务足够小，小到AI能稳定输出一个高内聚的文件或者函数。

一个“代码原子”的典型特征：

• 单个文件，最多不超过200行
• 只有一个核心职责，名字里就说得清
• 输入输出类型在任务描述里提前定义好，不允许AI自由发挥
• 依赖的外部接口在上下文里给全，不存在的模块绝不引入

拆解的起点是架构图。我先把系统拆成模块，再拆服务，再拆函数，最后才算“可以交给AI的最小单元”。这一步看起来多花时间，但实际上是在替AI降低出错的概率。实测下来，直接让AI写一个20行函数，成功率高到离谱；让AI直接写一个完整业务模块，则大概率要返工两三轮。

举个例子，早期我做后台的订阅计费模块，让AI一口气生成“创建订单+校验套餐+扣费+生成发票”整个链路的代码，改了四遍才勉强通过。后来我把它拆成“校验套餐”“检查余额”“扣费”“生成发票”四个原子任务，每个任务单独交付，总耗时反而只有原来的三分之一。

2.3 四段式提示词模板和上下文“断舍离”

同样的模型，同样的量级，用不同的描述方式，AI产出质量能差三倍以上。我固定下来的模板是四段式：

【任务】你要实现什么功能，做到什么程度 【约束】不能用什么，必须遵守什么项目规范 【示例】给出输入输出的具体样例 【验收】代码满足什么标准才算通过

模板本身不神奇，神奇的是“强制AI按模板走”这个动作。它把模糊的开发意图变成了可校验的交付标准，返工率肉眼可见地下降。比如写一个接口服务，任务描述里如果不写“输入参数必须是字符串，非法输入返回400”，AI很可能自己发明一套异常处理逻辑，返回的格式跟全局协议对不上。

上下文管理是我控制token成本的关键。刚开始我走过一个弯路：把整个项目的说明文档、接口定义、所有相关代码全部都塞进上下文，生怕AI信息不足。结果token爆炸，而且模型处理长上下文时注意力会被稀释，垃圾代码反而变多。

后来我改成了“按模块开独立会话”：每个会话只携带当前模块的接口定义、关键代码片段和少量示例；每次对话快结束时，让AI生成一段精简的摘要，把它存到临时文件。下次继续时，只需要把摘要灌回上下文。实测下来，这种“上下文断舍离”让单次任务成本下降了将近40%，代码质量反而更稳定。

3. Harness架构落地：五个关键层的设计与实现

3.1 模型接入层：为多模型切换留好后路

Harness架构的最底层是模型接入层，核心是一个叫ModelPort的抽象接口：

from abc import ABC, abstractmethod from typing import Any class ModelPort(ABC): @abstractmethod async def chat(self, messages: list[dict], tools: list[dict] | None = None) -> dict: """统一对话入口""" @abstractmethod async def stream_chat(self, messages: list[dict], tools: list[dict] | None = None): """流式对话，供需要持续输出的场景使用"""

所有模型实现都实现这个接口，业务代码永远只依赖ModelPort，不关心底层是哪个模型。这块最大的难点不是模型能力的高低，而是协议差异：有的模型有function calling能力，有的没有；有的支持流式返回，有的不支持；有的参数命名还不一样。我在接入层里统一把这些差异拦掉，业务侧看到的永远是同一种消息格式，后面加新模型时，业务代码不需要跟着动。

这个设计在最开始显得有点“过度设计”，一上来就搞抽象。

到了第七个月，我要接入第二个模型做路由备份时，发现它值回了票价：只改一个配置文件，新增一个实现类，业务代码一行没动。如果你也在做AI相关应用，别嫌接口抽象麻烦，多花半天定义一个稳定的模型入口，后面能省好几个通宵。

3.2 工具执行层：让AI“动手”之前先过三关

工具执行层是Harness架构里最重的一层。它解决的核心问题是：当模型说“我想调用某个函数”时，系统怎么安全、可控地让这个调用真正发生。

我的实现是“注册表+沙箱”的组合。每个对外能力都注册成一个带schema描述的工具：

@tool("search_documents", description="搜索本地文档库") async def search_documents(query: str, top_k: int = 5) -> list[Document]: ...

工具执行之前，我一定会做三层检查：

• 参数类型校验：模型给出来的参数类型对不对、值是否在合法范围内
• 资源权限校验：这个工具在当前会话里是否有权限被调用
• 返回值容量校验：返回值会不会太大，撑爆后续流程

没有这三层检查，模型一旦产生幻觉输出，后果会直接传导到真实系统里。我把它设计成类似“安检门”的模式——每个工具调用都要过一次安检门，高危操作还需要额外人工确认。例如删除类工具、外发数据类工具默认都是拒绝状态，只有特定会话里手动放行。

3.3 状态管理层与安全校验层：Harness架构的“记忆”和“刹车”

状态管理层负责记录整个任务的当前状态：对话历史、任务进度、临时变量、已完成的工具调用。没有这层记忆，AI就只是无状态的接话机器人，根本做不了跨多轮的复杂任务。我把状态做成可持久化结构，任务中断后能恢复，这是Harness架构跟普通脚本最大的区别。

实现上我用的是一个全局状态对象，支持序列化和快照回滚。某次任务跑了很长链条，中途某一步参数错了，我只需要回滚到上一个快照，重新调整参数再跑，不用整条链路推倒重来。这一点在长任务里的价值是决定性的。

安全校验层则是我给自己留的“后悔药”。只要是AI生成的内容，我默认不信任。输入侧会检查提示词注入，输出侧会检查有没有异常内容，执行侧所有高危操作统一走人工确认队列。这套机制在项目后期发挥了巨大作用，因为我开始允许第三方集成调用部分工具后，安全边界的压力一下就上来了。

3.4 编排层：把零散工具串成一条生产流程

最后是编排层。它负责定义“模型在什么条件下调用哪个工具，调用完怎么处理结果，失败怎么重试”。我把它设计成声明式的工作流脚本，用JSON描述即可，不需要写代码去改逻辑。比如：

{ "steps": [ {"action": "search_documents", "on_success": "summarize_result"}, {"action": "summarize_result", "on_failure": "retry_once"} ] }

好处是调试方便，出问题可以在编排文件里直接改，不用重新构建整个服务。这个五层架构花了比较多的时间在前三层，但后期开发效率也因此明显提升。每个模块的职责都非常清楚，AI生成代码时只需要对准某一层，不会陷入“不知道该改哪”的混乱。

4. 九个月研发节奏：一个人如何不掉链子

4.1 三阶段规划与“关门标准”

九个月我切成三段，每段都有一个明确的关门标准，不达标就砍功能，不延后：

• 第1-3个月：架构设计与核心骨架。目标是把上述五层架构跑通，搭出一个可运行的MVP，核心链路能端到端走通。
• 第4-6个月：功能密集开发。订阅计费、管理后台、第三方集成、前端页面都在这个阶段铺开。
• 第7-9个月：性能优化、兼容性修复、安全加固和发布准备。存量代码全面过一遍，修掉各种边角问题。

每段结束我复盘一次“数据指标”：MVP阶段看链路通过率和单轮响应时延，密集开发阶段看功能完成率和bug密度，发布准备阶段看崩溃率和异常回放成功率。复盘时如果发现某项目标没到，我会当场决定砍掉它而不是延后——因为九个月的时间盒是硬约束，拖了第一阶段，后面阶段都会连锁爆炸。

4.2 每周一个“北极星目标”的进度法则

一个人开发最大的敌人其实不是技术难题，而是“每天都在忙，月底一看啥也没落地”的虚无感。我用来对抗这个问题的方法很朴素：每周只设一个“北极星目标”。

比如第一周的北极星是“让X模型能稳定往返调用工具10次不报错”，这一周所有每天的任务都围绕它展开。目标必须是可验证的，不是“尽量稳定”，而是“10次里面成功多少次有明确数字”。周中如果偏离目标，我会立刻纠偏。

我在代码仓库里还放了一个《WEEKLY.md》，每周日晚上强制更新四行信息：本周做了什么、数据指标、下周计划、风险项。别小看这四行，它让我在第九个月回顾时能清楚看到每一个阶段到底做了什么，哪周效率暴跌，哪周出了严重事故。对单人项目来说，这是最廉价又最高效的项目管理工具，比任何看板软件都管用。

4.3 时间账本：1600小时做了什么

有朋友问我20万行代码是怎么用时间堆出来的。我算过一笔账：工作日晚上8点到凌晨2点，周末两天各8到10小时，按每周25到30小时计算，九个月大概1600小时。

这1600小时里，真正手写代码的时间不到一半。我大部分时间花在架构决策、接口定义、代码评审和关键算法上。AI负责代码生成，我负责“决定生成什么、怎么生成、生成之后要不要”。这种分工模式是AI辅助开发的正确姿势——不是让AI包办一切，而是让AI当高效的执行者，人当决策者。

我自己最深的感受是，代码量并不是衡量进度的可靠指标。AI能一小时写出几百行代码，但真正该关心的指标是：线上功能有多少是稳定可用的？核心链路的故障率是多少？用户遇到的问题能不能24小时内解决？这几项比代码行数有意义得多。

5. 常见问题与排查实录：一个人debug靠什么兜底

5.1 token过期与鉴权错误排查顺序

九个月里遇到最多的一类“环境问题”，其实是token鉴权错误。不管是登录应用、调用API还是刷新授权，这类问题本质上都是OAuth/API鉴权故障。

我总结了一套排查顺序，遇到“token exchange failed”这类提示时逐项对照：

1. 确认token是否还在有效期内。很多坑来自本地缓存了过期值，代码没重新拉取。
2. 确认refresh_token是否为空或已经被消费过。刷新接口返回400 bad request，最常见的元凶就是refresh_token为空字符串，或者被并发请求重复消费。
3. 确认鉴权接口的日志里记录的报错码和状态码，重点区分401和403的差异。
4. 区分HTTP状态码的语义：401大概率是token过期，403大概率是权限不足或业务规则拦截，不要去改token，先检查请求头和账号权限。

我自己就在这块吃过大亏。有一次线上服务连续报错一小时，排查半天才发现是refresh_token缓存逻辑写错了：新拿到的刷新token覆盖了还在用的旧token，导致所有并发请求都拿着同一个失效值去刷新。修复后我加了一条铁律：任何鉴权模块都禁止修改正在使用的token对象，必须先生成新token再切换引用。这话听着像常识，但代码一复杂，类飞了。

5.2 AI生成“幻觉代码”的两道拦截闸门

AI用久了，一定会遇到它一本正经地调用一个根本不存在的库函数，或者导入一个不存在的模块。这种幻觉代码如果直接进生产环境，轻则运行时报错，重则数据错乱。

我的拦截方式分两道：

第一道是编译和类型检查。生成代码后立即跑类型检查，大部分幻觉API会被直接拦下来。Python本身是动态语言，类型检查的效果弱一些，但也能挡掉“属性不存在”这类低级问题。如果是强类型语言，这道闸门的效率会更高。

第二道是强制AI为自己生成的代码写单元测试。这一步很有用——如果AI自己生成的测试也引用了同一个幻觉函数，测试执行时会直接暴露问题。这个机制把“看起来能跑”变成“跑起来验证过”。

还有一个小技巧：如果运行时报“某某模块找不到”，优先怀疑不是环境问题，而是AI把“子虚乌有”的库当成了标准库。这时候把当前项目真实的模块列表发给AI，让它重新生成导入部分，往往比折腾环境配置快得多。

5.3 那个最贵的三周重构

九个月里唯一一次让我感觉“撑不下去”的时刻，是第五个月的一次大重构。当时早期模型接入层用的是同步调用，到了功能密集期，并发一上来就卡死。没办法，只能把模型接入层全面改成异步。

这次重构前后花了三周，调用链遍布整个系统，改到后面我一度想推倒重来。后来是怎么走出来的？我把模块依赖图画在一张白板上，每天只改一条链路，每条链路改完跑一遍全量测试，然后坐回去复盘全局。AI在这个过程中帮我完成了大量机械性的变更，但架构决策和影响面分析始终是我自己做的。

这次重构留下的经验很直接：涉及全局架构的改动，AI只能做执行者，不能做决策者。重构前先把依赖关系梳理清楚，画一张真实的依赖图，比让AI直接动手改靠谱得多。依赖图就是你在重构里的地图，手上有地图，AI作为“施工队”才不会把墙拆歪。

6. 最后分享一点我的真实体会

6.1 对AI辅助开发的新认知

九个月做下来，我对AI辅助开发有了跟刚开始完全不同的看法。最初我以为AI能帮我写代码，后来发现它更像一个“超高效率的初级工程师”——你给它清晰的任务，它能快速产出；但什么是好架构、什么逻辑要保留、什么模块要砍掉，这些判断必须由人来完成。

这种“AI当执行者、人当决策者”的模式，听起来很简单，执行起来却很考验人的自控力。因为AI产出太快了，你很容易陷入“让它继续写、写完再说”的惯性，结果代码库膨胀，技术债爆炸。我后期专门给自己定了一条规矩：AI生成的代码必须经过评审和测试才能合入主干，绝不允许为了省事跳过。

6.2 三个值得坚持的习惯

如果你想用类似方式做独立项目，我的建议是：

第一，小目标起步。不要一开始就把目标定成20万行代码，先定一个“让AI帮我把最难的核心链路跑通”的小目标，然后一层一层往上加。

第二，token预算一定要提前规划。不是不花钱，而是把每一分花在刀刃上。上下文管理一定要抠细节，该断舍离就断舍离，不要图省事把一大堆无关代码塞给AI。

第三，AI生成代码一定要过校验和测试。任何跳过验证的效率提升，都会在后期用更大的返工成本还回来。

我始终觉得，Harness架构的核心其实不是那五层代码框架，而是一套“人和AI协作的安全边界”。你给AI多大的自由度，决定了它能跑多快；但你为这个自由度设了多少约束，决定了项目能活多久。这句话，算是我这九个月最值钱的总结。