企业官网建设流程全解析

Agent Harness 长任务中断最常见的排障现场是这样的：两个市场研究 Agent 跑同一个选题，第五步抓取超时后重启，前四步的产物到底能不能复用说不清，于是要么重复创建，要么直接覆盖。遇到这种局面，把模型调用通道单独拎出来处理会省事很多——打开 TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 注册并创建 API Key，把 Harness 里的 Base URL 统一改成 https://taotoken.net/api，再回头补第三层规划与第七层恢复的检查点。通道的归通道，状态的归状态，两件事分开做，中断恢复时才不用一边猜 Key 一边猜逻辑。

这篇按排障视角来走：先复现「第五步超时」这个失败，再拆开看为什么断点续跑会被凭证和入口拖累，然后把 Harness 里模型调用的接入点改到统一通道上，最后回到检查点与工作区，验证一次真实的续跑。技术主线仍然贴着原文的七层结构，只是把 Level 3 / Level 4 的模型调用单独提到前面处理。

1. 第五步超时之后，两个市场研究 Agent 为什么开始重复劳动

1.1 把 timeout 打在第五步：一次可重复的复现

找两个市场研究 Agent 做对照，最省事的做法是只改结构、不改任务。任务都给同一句话：调研某个细分行业的规模、主要玩家和近一年的融资情况。Agent A 用一条长 prompt 一把梭，把检索、抓正文、抽取要点、成稿全塞在一次调用里；Agent B 显式拆成八步，每一步的输入输出都落盘到工作区目录，规划、执行、观测分层写在代码里。这个对照不是比谁写得漂亮，而是看第五步挂掉之后，谁还能接着跑。

复现的关键在第五步。把这一步定义成「批量抓取候选来源正文并抽取要点」，同时把 HTTP 超时压到 5 秒，候选源里必然有几个响应慢的站点，于是第五步稳定抛超时。这时候你会看到 A 的表现是整段重来，因为它的中间状态全在上下文里；B 的表现取决于它有没有把前四步的结果写入可被重新读到的位置。原文把这个现象归到失败四：任务在第五步中断、重新运行之后，Agent 无法判断前四步产物能否复用，结果就是重复创建文件，或者把上一轮已经修好的中间产物直接覆盖掉。

这里要强调一点，超时本身不是病，超时之后「谁拥有这些中间产物」没有记录才是病。很多 Harness 把工作区当成一个临时目录，跑完就删，或者用同一套文件名反复写。一旦第五步崩掉，第七层的恢复逻辑拿不到任何指纹信息，只能选择最安全的策略：全部重跑。安全是安全了，代价是钱和时间，还有可能把上一轮已经人工修过的内容冲掉。

1.2 失败四的成本不在超时，在产物归属没人记录

把「重复劳动」拆开看，其实分成三种不同的问题。第一种是重复调用模型，前四步的抽取结果明明还在磁盘上，恢复时却重新发起了一遍；第二种是重复创建产物，工作区里出现step3_result.json、step3_result_v2.json、step3_result_final.json这种命名失控的现场；第三种最麻烦，是覆盖写，新的一轮把旧的一轮盖掉，而旧的那一轮里可能包含着人工修正过的字段。

这三种问题的共同点是，它们都发生在恢复阶段，但根因分散在三个层。第三层规划没有给每一步一个稳定的step_id，第五层执行没有约定工作区路径和写入语义，第七层观测没有记录「这一步上一次跑到哪里、产物的指纹是什么」。原文用两个 Agent 对比，其实就是在说明一件事：光有分层这个形式不够，每一层还得留下可被恢复逻辑读取的痕迹。

所以排障顺序建议反过来。不要一上来就改 Prompt，也不要一上来就加 retry，而是先确认恢复逻辑依赖哪些字段、这些字段有没有真的落盘。确认完再动手改模型调用通道，这样即使改通道过程中出现新的报错，你也能分清是接入问题还是状态问题。

1.3 模型调用是所有层的公共依赖，先把它固定下来

第三层的 Planner 要调模型做任务拆解，第四层的工具选择要调模型做路由判断，第五层执行之后的摘要、抽取、交叉验证同样要调模型。也就是说，模型调用不是某一层的能力，而是贯穿整个 Harness 的公共依赖。公共依赖最容易出的事就是：今天这里写死一家，明天那里改成另一家，恢复阶段两边对不上。

固定它的方式很简单，只统一两样东西：Base URL 和 API Key。Agent 代码里所有发起模型请求的地方，都从一个配置源读取这两个值，不允许多处硬编码。至于模型 ID，建议也走配置，并且以 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 上的模型广场当时列表为准，不要凭记忆写一个带日期后缀的名字，那种 ID 往往在恢复的那一天已经不存在了。

固定好之后，恢复流程会变得清爽：检查点校验的是任务状态，不是连接参数；日志里记录的是模型 ID 和通道标识，而不是某一次临时复制进来的 Key。后面几节就按这个顺序来，先把通道改好，再把检查点补齐。

2. 断点恢复最怕通道乱：Key 和 Base URL 不统一会吃掉半天

2.1 一个 Harness 里塞三套凭证的现场

做过一段时间 Agent 的人多半有过这种目录：根目录一个.env，工具目录一个config.yaml，某个实验脚本里还夹着一行硬编码的 Key。平时跑短任务没事，因为失败了重跑一次就完事；一旦任务长度拉到十几步、单次要跑几十分钟，问题就来了。第五步超时之后，你重启进程，读到的可能是第三套凭证，模型 ID 也换了个版本，于是恢复逻辑虽然触发了，但发出的请求和上一轮根本不是同一条路径。

更麻烦的是排查成本。日志里写着「模型返回 400」，你第一反应是 Prompt 太长，第二反应是模型不支持这个参数，第三才会想到是不是请求打到了另一个入口。中间这段时间都在做无效推理。把 Base URL 和 Key 收敛成一份配置，最大的收益不是省钱，而是把排障范围从「三条路径」压缩到「一条路径」。

原文在讲第五层执行与工作区时提到过，工作区要能被人和 Agent 同时看懂。这条经验对配置同样成立：配置项也要能让人一眼看懂「这次跑的是谁的模型、走的哪个入口」。

2.2 TaoToken 兼容通道：统一 Base URL 与 Key 两件事

TaoToken 在这里的角色是统一接入层，不是一个需要额外学习的协议。你仍然用 OpenAI 兼容的客户端、Anthropic 兼容的客户端，或者任何支持自定义 Base URL 的框架，只把入口地址换成 https://taotoken.net/api，Key 换成从控制台创建的那一把。注意这个地址末尾不带/v1，很多 404 就是这么来的，客户端自己会拼路径，你再补一层/v1就变成/v1/v1/...。

对断点续跑来说，统一入口带来的实际好处是：无论恢复时是 Planner 在发请求，还是执行层在发请求，日志里记录的都是同一个 base_url 前缀。对比两轮运行日志时，只要看到这个前缀不一致，就能立刻定位到「换过通道」，而不是去翻 prompt 差异。

模型 ID 同样集中管理。写代码时用一个环境变量占位，实际值去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 的模型广场挑，挑完填进去。不要在任务状态里存一个「模型显示名」，那是给日志看的，不是给请求用的。

2.3 拿 Key 的动作放进准备材料里

动手改代码之前，先把材料准备齐。打开 TaoToken 完成注册并登录，然后在控制台里创建一把 API Key，妥善保存，代码里统一用YOUR_API_KEY这个占位符代替，不要真的把明文提交进仓库。Key 的权限和额度信息在控制台都能看到，长任务跑之前顺手确认一下额度是否够用，可以避免跑到第七步才因为额度耗尽而中断。

准备清单只有三项：一把 API Key、一个确定的 Base URL（https://taotoken.net/api）、一个从模型广场选出来的模型 ID。把这三项写进.env，然后让 Harness 里的所有模型调用都只读这份配置。做完这一步，再去看检查点的代码，思路会清晰很多。

3. Harness 的模型接入点：.env、settings.json、config.toml 分别怎么改

3.1 Python 版 Harness：openai 客户端指向 https://taotoken.net/api

多数自研 Harness 是 Python 写的，模型调用集中在少数几个函数里。先建一份.env：

TAOTOKEN_API_KEY=YOUR_API_KEY TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL_ID=YOUR_MODEL_ID

然后在客户端初始化处统一读取，不要在业务函数里再写一遍地址：

import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], # https://taotoken.net/api ) def call_model(prompt: str) -> str: resp = client.chat.completions.create( model=os.environ["TAOTOKEN_MODEL_ID"], messages=[{"role": "user", "content": prompt}], ) return resp.choices[0].message.content

关键点有三个。base_url末尾不要加/v1；模型 ID 从环境变量读，方便中断恢复时对比日志；所有层（Planner、工具路由、摘要）都调用同一个call_model，不要在某一层单独 new 一个客户端。第三点看着琐碎，但它直接决定了恢复阶段能不能只改一处配置就切换通道。

如果你的 Harness 里同时存在异步客户端，做法一样，只是把AsyncOpenAI也指向同一个base_url。两套客户端指向同一份配置，日志里就能对齐。

3.2 执行环节交给 Claude Code 时，改 ~/.claude/settings.json 的 env

有些 Harness 把「写脚本、改配置、跑一次校验」这类执行环节交给 Claude Code 来做。这种情况下要改的是 Claude Code 的配置，而不是 Harness 的.env。在~/.claude/settings.json里写：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "YOUR_MODEL_ID" } }

三个字段都要对。ANTHROPIC_BASE_URL填接口地址 https://taotoken.net/api，不带/v1，也不要附任何查询参数；ANTHROPIC_AUTH_TOKEN用YOUR_API_KEY占位，真实值从控制台取；ANTHROPIC_MODEL填模型广场里选定的 ID。改完之后重新打开终端会话，让环境变量生效，再启动 Claude Code。

要提醒一句边界：Claude Code 在这条链路里只负责生成和解释代码、比对配置，不会替你去连生产库、也不会替你在生产机器上执行命令。凡是需要真实执行的诊断脚本、校验命令，都由你在本地跑完之后，把输出贴回对话里让它继续分析。Harness 的检查点逻辑也一样，Claude Code 可以帮你写、帮你审，但跑不跑、在哪跑，决定权在你手上。

3.3 复核脚本交给 Codex 时，改 ~/.codex/config.toml 的 model_provider

另一条常见链路是用 Codex 复核恢复逻辑、审查 SQL 或者对账脚本。Codex 的配置文件是~/.codex/config.toml，注意别把 Anthropic 那套变量名套上来，两者不通用：

model = "YOUR_MODEL_ID" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY"

这里model_provider指向自定义 provider 段，base_url同样填 https://taotoken.net/api，env_key写的是保存 Key 的环境变量名。改完保存，重启 Codex 会话。如果你的 Codex 版本对 provider 字段有额外要求，以版本自带说明和接入文档为准，不要凭印象补字段，多一个键有时候会直接导致启动失败。

如果 Harness 同时用到 Claude Code 和 Codex，最好在项目 README 里写清楚「哪一步用哪个工具、各自读哪份配置」，避免恢复时两边模型 ID 不一致，日志对不上。

4. 第三层 Planner 的 State 里到底要落盘什么，才能让第五步挂掉不重来

4.1 每一步都要有 step_id、输入指纹、产物指纹

第三层规划最容易犯的错是把计划写成一个字符串数组，跑完就丢。正确的做法是每一步一条结构化记录，至少有这几个字段：稳定的step_id（比如s05_fetch_and_extract，不用数组下标，因为你以后会插步骤）、输入指纹（上游产物的哈希或者版本号）、产物路径、产物指纹、状态（pending / running / done / failed）、最后一次错误摘要。

有了这几个字段，第五步超时之后，恢复逻辑的判断就变成一行确定性的检查：step_id为 done 且产物指纹没变的步骤直接跳过；状态是 running 但超时的步骤重新执行，并且写入新版本而不是覆盖旧版本；状态是 failed 的步骤按策略重试，超过次数就停下来等人。这条规则写起来简单，但它把「能不能复用」从一个猜测变成了一个查表动作。

指纹怎么算不用复杂，对产物文件做一次内容哈希就行。关键是算完要落盘。只算不存，下次启动照样要重跑第一步来重新计算，等于白算。

4.2 第五层工作区：路径约定 + 不覆盖写

工作区的目录约定要跟step_id对齐，例如每步一个子目录，产物带步号和轮次：

workspace/ run_20250601_101500/ s01_plan/ s02_sources/ s05_fetch_and_extract/ result.r1.json result.r2.json

轮次编号是重点。第二次执行第五步时写入result.r2.json，同时把state.json里的产物指针指向 r2，上一轮的 r1 保留在原地。这样即使新的一轮结果更差，你也能回退，不会出现「上一版被人改好过，现在找不到了」的情况。

对应的写入代码要显式禁止覆盖：

def save_step_output(workspace, step_id, run_id, payload): step_dir = workspace / step_id step_dir.mkdir(parents=True, exist_ok=True) target = step_dir / f"result.{run_id}.json" if target.exists(): raise FileExistsError(f"{target} already exists") target.write_text(payload, encoding="utf-8") return target

抛异常看起来粗暴，但它能在开发阶段就把覆盖写的问题暴露出来，而不是等到线上跑了几十分钟之后才发现中间产物被冲掉了。

4.3 第七层观测：恢复日志的最小字段集

恢复日志不需要很花哨，但必须包含能回答三个问题的信息：这次是第几轮、从哪一步继续、用的是哪条通道和哪个模型。建议每条日志固定带上step_id、run_id、resumed_from、base_url_prefix、model_id、耗时、token 用量。其中base_url_prefix只记前缀就行，不要记完整地址带参数，更不要记 Key。

有了这组字段，验证阶段就很好做对照：第一轮和第二轮的base_url_prefix应该一致，model_id应该一致，resumed_from应该指向第五步，而不是从第一步开始。三项里任意一项对不上，都能立刻定位到具体原因。

5. 验证：跑一轮市场研究任务，看它是续跑还是重跑

5.1 三种人为打断方式

不要等真实超时，那样太随机。三种可控的打断方式更实用。第一种是在第五步里插入一个if len(items) > 3: raise TimeoutError，让它在固定位置挂；第二种是直接用系统的进程终止信号，在日志输出到第五步时手动结束进程；第三种是临时把网络超时改成极小的值，让所有抓取都失败。第一种最推荐，因为位置确定，恢复时的行为最好观察。

打断之后，不要清理工作区。直接重启 Harness，观察它第一件事做了什么。如果它先读了state.json并打印出resumed_from=s05_fetch_and_extract，说明恢复逻辑生效了；如果它从s01_plan开始重新执行，那就去第三节的配置和第四节的检查点里找原因。

5.2 日志对照：续跑与重跑的判别

把两轮日志并排看，续跑应该长这样：第一轮有 s01 到 s04 的完成记录，第五步开始后中断；第二轮启动时只有 s05 及之后的记录，前面的步骤被标记为 reused。重跑则相反，第二轮里 s01 到 s04 又完整出现了一遍，而且run_id换了新的一轮，说明状态没有被读到。

这时候可以顺手确认一件事：这些复用的步骤有没有产生新的模型调用。如果日志里 s02、s03 又出现了 token 消耗记录，那就是典型的重复劳动，即使产物没被覆盖，钱也已经花了。这一步的检查直接对应失败四里的第一种成本。

5.3 容易误判的两种情况

第一种误判是「看起来续跑了，其实只是跳过了缓存」。有些框架会在同一进程内做内存缓存，进程重启之后就没了，表现为第一次恢复像续跑、第二次恢复又变成重跑。判断方法是彻底重启环境，包括清掉内存状态，看行为是否稳定。

第二种误判是「产物文件名相同就认为可复用」。文件名相同不代表内容一致，如果第五步的输入变了（比如上游来源列表更新了），旧产物就不能直接复用。这就是输入指纹存在的意义。对照state.json里记录的输入指纹和当前实际输入，不一致就必须重跑该步，而不是盲目复用。

6. 排障对照表：401、模型 not found、多了 /v1、产物重复创建

6.1 凭证与地址类报错

这三类错误里，404 最常见也最容易被忽略。因为很多客户端示例里默认就带/v1，复制过来不删，请求路径就多了一层。判断方法很简单：把实际发出的完整 URL 打印出来看一眼。

6.2 模型 ID 类报错

模型相关报错通常提示model not found或者权限不足。出现这类提示，第一件事是回到 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 的模型广场，核对当前可用的模型 ID，把.env里的值替换掉。不要靠猜，也不要把某个带日期后缀的名字当成通用别名，这类 ID 的可用性会随时间变化。

第二件事是确认 Harness 的每一层读的是同一份配置。常见情况是 Planner 读.env，摘要层读的是配置文件里另一处写死的旧 ID，结果第五步正常、第七步报错，看起来像恢复逻辑的问题，其实是模型 ID 不一致。

6.3 恢复逻辑类问题

如果日志显示续跑，但你发现有些步骤还是重复执行了，重点检查三处：step_id是否稳定（用了数组下标就会随插入步骤而漂移）、产物指纹是否真的写进了state.json、读取状态时是否用了最新的那一轮run_id。这三处任意一处出问题，都会让恢复逻辑退化成重跑。

如果确认是重复创建而不是覆盖，说明你的写入保护起作用了，只是复用判断没生效。这种情况下先把resumed_from打到日志里，再对照状态文件逐条排查，通常很快就能定位。

7. 跑通之后，回控制台对一下这次长任务的调用

验证跑完之后，最好回控制台对一下账：这次长任务一共消耗了多少、中断重跑带来的额外消耗是多少、哪些步骤被正确复用了。这些数字比任何主观感受都更能说明检查点有没有起作用。如果发现额外消耗偏高，回到第四节的指纹和轮次编号上去找原因。

需要长期跑 Agent 任务的话，可以先在 TaoToken 模型对话 里用同一把 Key 发一条测试消息，确认模型 ID 和 Base URL 没有填错；接着看 Coding Plan 的额度是否够覆盖你的任务频率；Key 本身在 控制台 API Keys 里创建和管理。如果你的执行环节用的是 Claude Code，环境变量字段对照可以看 Claude Code 接入文档。

最后留一个顺序上的建议：先领 Key、把通道固定成一处配置，再按第三层和第七层的结构补检查点。顺序反过来的话，你会同时面对「请求打不通」和「状态读不到」两类问题，日志里混在一起，排查时间会长出一大截。