企业官网建设流程全解析

1. 多 Agent 协作里最隐蔽的串稿：路径对了，内容错了

如果你正在跑多 Agent 并行开发，大概率遇到过这种场景：调度器把work/article.md这个路径交给下游 Agent，下游读到了文件，任务显示成功，结果打开一看——是另一个项目刚覆盖进去的正文。路径没变，文件名没变，修改时间看起来也正常，但内容身份已经换了。

这就是「串稿」。它不是模型写错一句话，而是交接链本身缺少内容身份校验。文件路径只是地址，不是内容身份。在多项目并行、异步队列、长任务恢复的场景里，只传路径会留下四个无法回答的问题：这是不是预期的那篇文章？是不是批准时看到的那个修订？素材集合有没有在交接后变化？上一次导入超时时，目标系统到底有没有已经写入？

我试过在一个三 Agent 并行写稿的流水线里踩过这个坑：A 项目写完drafts/technical-blog.md，B 项目同名的草稿文件被另一个任务覆盖，消费 Agent 拿到的路径完全合法，但 SHA 已经变了。从那之后，我在交接协议里强制加了 SHA 回执。

这篇给出一套可复现的最小协议：内容 ID + 修订号 + SHA-256 + 无正文回执 + 消费后现场复核，遇到不确定写入先进入 ambiguous 状态，回读事实再决定是否恢复。适合多 Agent、多仓库、异步队列和长任务恢复；如果只有一个进程同步处理临时文件，协议可以简化，但内容哈希和幂等边界仍值得保留。

2. 前置准备：TaoToken 接入与项目骨架

在写回执逻辑之前，先把模型调用链路搭好。多 Agent 协作通常需要一个统一的模型入口，避免每个 Agent 各自维护一套 Key 和端点。我用 TaoToken 做统一接入，官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数。

先到控制台创建 API Key，入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有针对不同客户端的配置说明。

项目骨架建议这样组织，让回执和正文分离：

project-root/ agents/ writer/ reviewer/ publisher/ work/ article.md # 正文，由所属项目管理 receipts/ handoff.json # 无正文回执 config/ settings.json config.toml

关键原则：正文永远留在所属项目里，跨项目传递的只有回执的相对路径和哈希。回执里不存正文，避免日志、消息队列、数据库复制完整内容，扩大数据暴露面。

3. 可复制配置：settings.json 与 config.toml 骨架

下面这份settings.json是给 Agent 运行时用的，定义回执路径、哈希算法和状态机字段。你可以直接复制改路径。

{ "handoff": { "receiptDir": "receipts", "receiptFile": "handoff.json", "hashAlgorithm": "sha256", "chunkSize": 1048576, "requireRevisionMatch": true, "requireShaMatch": true, "allowAbsolutePath": false }, "stateMachine": { "states": ["intake", "receipt", "record", "completed", "ambiguous"], "onRestartRunning": "ambiguous", "autoRetryOnAmbiguous": false }, "publication": { "authorized": false, "note": "接稿成功不等于允许公开发布" } }

config.toml是给调度器或 CLI 工具用的，字段和上面保持一致，方便不同语言读取：

[handoff] receipt_dir = "receipts" receipt_file = "handoff.json" hash_algorithm = "sha256" chunk_size = 1048576 require_revision_match = true require_sha_match = true allow_absolute_path = false [state_machine] states = ["intake", "receipt", "record", "completed", "ambiguous"] on_restart_running = "ambiguous" auto_retry_on_ambiguous = false [publication] authorized = false

一份最小交接凭证长这样，注意publicationAuthorized默认 false：

{ "packageId": "2026-08-agent-handoff-receipts", "packageRevision": 3, "targetType": "technical_blog", "contentId": "agent-handoff-receipts", "sourceRef": "drafts/technical-blog.md", "sourceSha256": "e3b0c44298fc1c149afbf4c8996fb924...", "assetCount": 0, "publicationAuthorized": false }

这里有四层身份，缺一不可：packageId是这次内容生产任务是谁；packageRevision是消费的是哪一轮决策；contentId是平台文章的稳定身份；sourceSha256是正文原始字节到底是哪一份。修订号防止并发决策覆盖，正文哈希防止路径内内容漂移。

4. 幂等验证：SHA 计算、乐观锁与消费后回执

4.1 生成内容身份

Python 标准库就能算稳定哈希，注意必须基于原始字节，不能读取文本后重新编码，否则 CRLF/LF、BOM 或编码归一化会让验证结果漂移：

from hashlib import sha256 from pathlib import Path def file_sha256(path: Path) -> str: digest = sha256() with path.open("rb") as stream: for chunk in iter(lambda: stream.read(1024 * 1024), b""): digest.update(chunk) return digest.hexdigest()

4.2 只传相对引用

持久化记录里保存仓库名和仓库相对 POSIX 路径，不要把D:\...这类工作站绝对路径写进跨项目记录：

receipt_pointer = { "repository": "TargetBlogProject", "receiptRef": "docs/evidence/agent-handoff-receipt.json", "receiptSha256": "...", }

4.3 消费前做乐观锁

目标项目导入前同时检查修订号和正文哈希，二者缺一不可：

def verify_handoff(receipt: dict, expected_revision: int, source: Path) -> None: if receipt["packageRevision"] != expected_revision: raise RuntimeError("stale package revision") if file_sha256(source) != receipt["sourceSha256"]: raise RuntimeError("source content drifted")

4.4 消费后导出目标回执

源回执只能证明「准备交付的文件」。目标项目要重新计算受管正文和全部素材哈希，再导出自己的接稿回执：

{ "state": "accepted", "targetType": "technical_blog", "packageId": "2026-08-agent-handoff-receipts", "packageRevision": 3, "sourceSha256": "...", "managedSha256": "...", "assets": [], "bodyStored": false }

共享调度器只登记这个回执的相对路径和哈希。以后每次恢复，都重新打开目标正文、回执和素材做现场验证。

4.5 用显式状态机处理副作用

接稿周期拆成intake -> receipt -> record -> completed。每一步执行前写running，成功后写completed。如果进程在外部命令运行期间崩溃，遗留的running不能直接重试，而应转为ambiguous：

if step.state == "running" and process_restarted: step.state = "ambiguous"

接下来只读检查标准回执、目标正文和素材。事实已经完整就补记完成；没有就按明确恢复动作处理。恢复顺序固定：读取当前状态不执行写动作，复核回执文件本身的 SHA，复核目标正文和素材集合，匹配内容 ID、revision 与平台，事实完整则补记完成，否则返回唯一恢复动作。

5. 本篇常见错排查

报错一：stale package revision。说明消费方拿到的修订号落后于当前决策。先查调度器是否把旧 revision 的任务重新入队，再确认packageRevision是否在写入回执后被并发任务覆盖。不要直接改大 revision 绕过，那等于放弃乐观锁。

报错二：source content drifted。路径存在但字节变了。常见原因是另一个任务覆盖了同名文件，或 Git 切换分支后工作区内容变化。处理方式是重新生成回执，而不是放宽校验。

反例一：只比较文件名。article.md在每个任务里都可能存在，文件名和目录结构相同不代表内容身份相同。

反例二：只比较修改时间。时间戳可能被复制、Git 操作或同步工具改变，也可能因为精度不足无法区分两次快速写入。

反例三：把正文放进回执。回执应证明正文，而不是保存正文。正文进日志、数据库、消息队列会扩大暴露面。

反例四：命令超时就立即重试。超时表示调用方没拿到确定结果，不代表目标系统没有写入。对有副作用的动作直接重试，可能产生重复草稿、重复发布或重复扣费。正确做法是进入ambiguous，回读事实后再决定。

验收清单。上线前至少验证：正文不变时重复消费不制造第二份结果；正文改一个字节后旧回执立即失效；revision 落后时拒绝导入；回执路径正确但回执字节变化时拒绝恢复；图片新增、删除或替换后能检测到资产集合漂移；外部命令遗留 running 时进入 ambiguous 不自动重放；回执、状态日志和数据库中不保存完整正文与工作站绝对路径；接稿成功不会自动获得公开发布权限。

6. 把事实链补齐，再谈更聪明的调度

多 Agent 系统真正难的不是「把文件传过去」，而是让下一个执行者能够证明：它拿到的是正确任务、正确修订、正确字节，并且上一次副作用处于可确认状态。

如果你在排障阶段需要快速验证模型返回是否符合预期，可以用模型对话入口 https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 做单轮校验；如果是长期编码或 Agent 流水线，建议走 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 统一管理额度；接入细节和字段说明以接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 为准，Key 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 管理。

先把回执、修订号、SHA 和状态机这四件事补齐，再谈更聪明的调度。路径正确却读错版本、超时后重复执行，这两个问题解决了，多项目并行的串稿率会明显下降。