Skip to content

第7章 Agent 技术和应用案例 ​

第六章讲完了方法:业务本质怎么问,架构的八根支柱怎么搭,任务怎么拆、怎么编排。

道理讲到这里,读者心里多半还压着一个问题:这套东西听着都对,真跑起来行不行?

这个问题不算刁难,软件工程史上从不缺漂亮的架构图,缺的是能在真实机器上长期跑着的工程实体。

方法论最怕的不是没人信,而是有人信了、照着做,走到某一步才发现,这一步在现实中根本没有对应的东西。

所以本章不谈新理论,只做一件事:我们把一个真实跑起来的项目拆开给你看。

项目叫 Agentgeex(仓库名 agentgeex),一个做 Agent 项目管理与调度的引擎。代码放在内部仓库,截至 2026-11-01 累计 842 次提交;公开版本随书发布。第六章里关于通信协议、状态机、人在回路、按需挂载的论述,部分来自它的开发实践。

这一章我们不讲它有多强,只讲三件事:它当初为什么被做出来,现在长成什么样,还有哪些问题没解决。

7.1 先认识这个项目 ​

先交代一句立场:我是这个项目的开发者,也是维护者,后面的判断难免带着这层身份。

认识一个系统,先看它为什么存在。功能列表可以抄,动机抄不走。

先看它解决了谁的什么问题,再看它把自己放在什么位置。位置看清了,结构和边界才有意义。

7.1.1 为什么做它:缺口不在模型,在治理 ​

这个项目的起点,不是一句“我要做一个 Agent 框架”,而是一句很朴素的抱怨:一个人,怎么同时推进十几条工程线,还不把事情搞砸。

设想一个很普通的下午,你手里有十几条线:一份报告要补数据,一个脚本要改,一套接口要对齐,还有一个方案等人拍板。

每条线都不难,难的是同时记住它们走到哪了。

派发一条出去,你得记着回来看。它跑完了没有,卡在哪一步,要不要重试。这些事没写进任何地方,只在你脑子里。

脑子装得下五条线,装不下十五条。

真正卡住人的,从来不是模型不够聪明。当时,市面上的框架都在解决同一个问题:怎么让单个 Agent 更聪明。

模型能力确实在涨,但一个真正用它干活的人,很快会撞上三堵墙。

第一堵墙是长任务没人守。派发一条出去,人得在旁边等,等它跑完,看它有没有卡,要不要重试。

等人这件事,本身就把人绑住了:你以为自己在管理任务,实际是在给任务当值班员。

第二堵墙是交接靠口头:一件事交给另一个 Agent,靠一段自然语言描述。说漏一句,对方就做偏。

做偏了还没人知道,因为它“按时完成了”,而按时和做对是两件事。

第三堵墙是经验留不住:这次踩过的坑,填好之后就散在会话里。换个会话,换台机器,过两周,同样的坑再踩一遍。

这三堵墙的共同点很清楚:它们都不是智能问题,而是治理问题。

我们的判断是:聪明是模型的事,靠谱是调度的事。这两件事不该由同一个东西承担。

这就是 Agentgeex 立项的全部动机:不是再造一个更聪明的 Agent,而是补上那个没人愿意做的调度层(治理层)。

调度层要回答四个问题:一条活派给谁,走到哪一步,结果谁读了,卡住了谁管。

模型不回答这些。模型只回答下一步该做什么。

7.1.2 它是什么,不是什么 ​

先把边界划清,否则后面全是误解。

它是 Agent 的项目管理与调度引擎,管的就是那四件事。

它是一层独立于运行框架的调度层,负责把执行现场留成可查的记录,让任务有编号、有状态、有结论。

它不是另一个 Agent 框架。模型怎么推理,工具怎么调用,不在它的职责里。

它也不是某个平台的插件。

它更不是一个更好用的对话框,对话框只负责说话,不负责结案,也不负责确认对方读没读。

一句话概括:它不产生智能,它管住智能。

这个定位听起来不性感,但决定了一件很实际的事:调度层的判据不随模型换代而变。

模型从这一代换到下一代,任务有没有结案、结论有没有被读到、失败有没有人接手,这些判据都不变。

就我们的经验,换过一次模型之后,结案规则没有改过一行;不过这也只是经验判断,模型能力面要是真的变了,判据也可能要跟着调。

模型更强,通常只让一次执行的产出更好。它不会自动让一条任务被签收,也不会自动让一次失败被复盘。

7.1.3 它的结构:五个核心概念 ​

整套系统往下拆,最基础的是五个核心概念。先把这五个立住;计划、主机、事件这些,都是在它们之上的组合。

  • 项目(Project):一条独立的业务边界。回答这件事归谁管。
  • Agent:干活的分身,带角色与权限等级。回答谁来做。
  • 任务模板(Task):一类工作的说明书。回答这类事该怎么做。
  • 执行(Execution):一次具体的派发与结案。回答这一次真的做了什么。
  • 会话(Session):一次执行的上下文现场。回答它当时在什么背景下想的。

这五个概念里,最容易被混淆的是任务模板和执行。

一句话区分:模板是能做什么,执行是这一次做了什么。

模板稳定,说明书随仓库版本化;同一套模板在项目内按名对齐,物理上是各 Agent 一份副本,改动靠批量同步。执行一次性,带时间戳,必须留痕。

举个眼前的例子:“写一个小节”是模板,全书每一节都复用它。“写 7.1 节,编号 run_w_ch07_s01(示例)”是执行,只发生一次,有开始时间、有结论、有耗时。

会话解决的是另一个工程问题:上下文不能混,默认每条任务一个独立现场,跑完就结束;主会话、助理会话,以及显式复用 session_key 的派发,是少数例外。

混在一起会怎样?第二十条任务开始时,前十九条的历史还在吃上下文。这是第六章讲上下文迷失的物理根源。

它们怎么协作,7.4 节会用一个任务走一遍完整旅程;执行与回执两条轴的代码实现,也在 7.4.2。这里先记住它们各自管什么。

项目圈边界,Agent 定责任,模板定方法,执行记事实,会话存现场。

7.1.4 最关键的特点:与运行框架解耦 ​

如果只能讲一个特点,就讲它与运行框架的解耦。

Agentgeex 不绑定在某一个运行框架上。它最初跑在 OpenClaw 上,后来接了第二个平台 DeepSeek-Harness(DSH),地址是 https://github.com/deepseek-ai/deepseek-harness。

现在同一套调度层可以同时驱动两个平台上的 Agent。同构(结构一样)只到派发与取结果这一层:唤醒这类运行中注入,仍要按平台各写一遍,DSH 侧尚未补齐。

它靠的是把契约压到最小,调度层对下层只要求两件事:能把一条任务投进去,能把一个结果取回来。

至于投进去是走 WebSocket,调 HTTP 接口,还是写文件,由平台适配层负责。取回来是轮询还是回调,也归适配层。

每一层适配就是一个桥。结构可以画成这样:

两个桥是同构的:走同一套队列协议,用同一套活跃度上报。所谓活跃度上报,是桥定期报一声“我还在、手上几个任务”。结果键也相同,都写回同一个位置,调度层不用问是哪个平台。这份同构只到投递与取结果的契约,不含会话寻址、事件格式与重连。

在结果契约这一层,调度层看 OpenClaw 和 DSH 上的 Agent,看到的东西一样。它不需要为哪个平台单独写一套读取结果的逻辑。

任务按 Agent 声明的平台类型分流到不同的桥。加一个平台,等于加一个桥,外加分发与唤醒两处适配;调度核心的判断逻辑不变。

这件事有一层工程意义,一层方法论意义。

工程上,运行框架会换,今天最合适的运行框架,两年后可能就落后了。如果调度逻辑绑死在运行框架内部,换一次运行框架等于重构一次系统。

方法论上,它是对第六章的补充:6.4.1 讲框架选型时给了三个选项,分别是托管平台、自建、完全自研。

这不是第四个选项,而是把“选哪个运行框架”下移到适配层:调度层独立出来,运行框架成为可替换的部件。详细选型见 7.3.1。

我们还要把边界说清楚,因为解耦很容易被吹过头。

  • 它不修改任何框架的源码。
  • 它不负责拉起框架实例,只连已经跑起来的那个。
  • 换平台不等于零成本。

这第三条最容易被低估:每个桥都要重新适配对方的会话模型。会话怎么寻址,事件长什么样,断线之后怎么重连,这三处每个平台都不一样;这部分工作量省不掉,只能重写一遍。

7.1.5 现在解决了什么,还有什么没解决 ​

讲完定位、结构和特点,回到最初那四个问题:一条活派给谁,走到哪一步,结果谁读了,卡住了谁管,现在可以逐条回答。这个项目到目前为止解决了四件事。

  • 派给谁:多条线并行不打架。项目圈边界,权限等级卡住谁能给谁派发。派给谁在派发时定下,权限只决定谁有资格发起。执行者之间不能互相指挥。
  • 走到哪一步:过程有痕迹。每次执行都留下编号、时间、指令、结论、耗时。当时派了什么、做到哪一步、结论是什么,查得到,入口是 ao_get_execution。
  • 结果谁读了:结论有人读。执行和回执是两条轴。干完了和对方知道了分开记,没签收就一直算没闭环,所以有催签收,见 7.4.4。
  • 卡住了谁管:长任务有人守。到了超时时长的 70%、80%、90%,看门狗(定时巡检任务状态的调度组件)会分层来问一次“还活着吗”,也就是一次唤醒。对应配置项是 watchdog_wake_tiers,默认 0.7/0.8/0.9,按已用时长与超时时长的比值判档。到点发一次唤醒,用尽就告警,告警到顶转人工。任务不再静默挂住。

还没解决的,同样要讲清楚。四条分两类。

设计上就不做的,有两条,它们不是欠账,而是刻意的边界。

  • 判断不能自动化。什么该做,什么该放弃,这个结果能不能接受,价值判断仍然全部由人定;规则内的处置,由系统自动执行。系统只是让判断之后的执行变快。
  • 成本随规模上涨。每多一个 Agent,每多一条任务,都是真实的算力支出。它不会自动变便宜。

还没做完的,也有两条,是工程量问题,不是设计取舍。

  • 跨主机部署仍是脏活。同一份代码要在不同环境里成立,靠的是纪律和反复校验,不是靠工具。解释器路径、安装根、端口,换个环境就得重新对一遍。这一点 7.6 节会讲。
  • 审计还有暗角。有一部分管理类操作没有落进持久的审计日志。系统能说清任务怎么跑的,说不清某个配置是谁、在什么时候改的;这类缺口,7.4.5 的“答不了四类”里有登记。

这个未解决清单不是谦虚,而是使用说明。一个系统如果只告诉你它能干什么,你迟早会在它干不了的地方翻车。

往下走,先看它怎么从一句抱怨变成一个需求。7.2 节从业务分析讲起,那里用四问把它拆了一遍。

7.2 业务分析:一个真实的起点 ​

第六章指出,业务分析的第一步是梳理业务本质。道理不难懂,难的是真坐下来,把自家的事一层层剥开,还不替自己遮丑。

这一节我们拿这个项目本身当样本,6.3.1.1 的四问照原样摊开,不修饰,也不挑好听的说。四问之后,还要盘一遍知识资产,算清这本账,再把组织映射过去。

7.2.1 四问核心:我到底要解决什么 ​

四问出自 6.3.1.1,原文四条:解决什么问题、替代哪段流程、提升多少效率、占据什么位置。下面按顺序过一遍,答案只取这个项目自己的。

第一问:解决什么问题 ​

7.1 开头那句抱怨,就是第一问:一个人,怎么同时推进十几条工程线,还不把事情搞砸。

这个瓶颈不是不会写代码。写了二十四年软件,代码本身早就不是难点,真正卡住人的是注意力。

注意力有三个漏点,每一个都在真实的一天里反复出现。

  • 一条线跑到一半,要等外部结果,编译、拉取、别人的回复都得等,一等思路就断了。
  • 上下文一满,前面几十轮的决策开始模糊,只能反复问自己上次改到哪了。
  • 做完的事不留痕迹,过两周连当时为什么这么定都说不清。

传统办法能缓解,写文档、开分支、记笔记,这些都有用。但它们有一个共同代价。缓解手段本身都要占用同一份注意力,这就是死结。

第二问:替代哪段流程 ​

第二问要替代的不是写代码,而是 7.1 里那三堵墙:人肉盯长任务、口头交接、记忆兜底。这里换业务语言重述一遍,因为这三笔账要到 7.2.3 才逐条算。

替代前后的差别,落在三处。

一项任务派出去,原来人要守在旁边等结果,等多久没有准数,等的时候什么也做不了;现在派完就进队列,人回来看的是结论。

一件事交给别人,原来靠一段话,说漏一句就做偏,做偏了还按时交付;现在交的是一份任务模板,没写清的字段空在那里,不会自己补。

上次那个坑怎么填的,原来靠人记着,或者翻聊天记录;现在进技能库和公告库,换个会话也查得到。

第三问:提升多少效率 ​

这个问题必须用数字回答,形容词不算数。

不过这一节换口径。不看效率百分比,看承载量。这个项目只有一个人。没有可比的对照团队,效率百分比也就没有分母。效率那笔账的算法在 6.3.3,本项目的具体数字见 7.6。

以这个项目自身的工程体量为例,四个数字足够说明问题。

指标数字说明
从零到可用约 6 个月首次提交到具备完整治理能力
代码总量约 9 万行内核、脚本、后端、前端,含 test/、docs/
对外暴露的调用接口98 个(92 静态 + 6 动态)调度层可被调用的方法总数
同时支撑的业务项目21 个活跃 18 个,各自独立的业务边界

按传统团队的分法,21 个项目要各配人手,98 个接口还要专人对接。这些任务现在压在同一个人身上,靠的是调度层替他分流。

这不是效率提升了百分之多少,而是一个人能同时握住多少条线。

这样的承载量在传统协作模式下很难做到,原因不在产能,在注意力。

第四问:占据什么位置 ​

这一点要提前想清楚,因为它决定整个架构。

答案是人在回路(Human-in-the-Loop,HITL),通俗说就是半自动,绝不是全自动。

人负责判断,做什么、为什么做、这个结果能不能接受。Agent 负责执行,怎么做、做掉它、留下痕迹。

这是责任归属决定的,不是技术妥协。系统可以替你干活,但不能替你担责。

所以架构里必须有一层人类专家接口,而不是一个可选的对话框。这一点 7.3.5 会展开。

7.2.2 知识资产盘点:两半账 ​

第六章强调,Agent 项目的成败常常卡在知识资产盘点。这个项目盘下来,情况不太乐观。

我们先看已数字化的部分,账面并不难看。

资产形态状态
代码与提交历史Git 仓库,842 次提交(origin/master,截至 2026-11-01)已数字化,可检索
任务模板483 条结构化定义(在用 449 条)已数字化,可调度
执行记录与结论每次结案留一条结论(成功执行约 96% 有 summary)已数字化,可聚合
技能沉淀56 条可复用做法(在用 55 条)已数字化,带使用计数
工作公告1,140 条(有效 944;日志 579、决策 259、踩坑 171、交接 74、配置变更 57),截至 2026-11-04 12:15已数字化,可追溯

这张表看着不少,覆盖的只是可数字化的那一部分。未数字化的部分,才是值钱的那一半。

  • 判断力。什么时候该放弃一个方案,什么时候该硬扛过去,这类判断没有文档,只存在于做过的人脑子里。
  • 审美与语感。一段文字读起来对不对味,一个交互顺不顺手,这是本项目的真实卡点。本书审校最容易出问题的从来不是事实错误,而是 AI 味。
  • 对边界的直觉。哪件事看起来能做、其实不该做,这种直觉来自踩过的坑,而且有些坑只给一次机会。

这个盘点得出一个结论,这个结论直接决定了一条架构原则。

凡是人脑里的知识,都不能指望系统自己长出来。必须给这些知识留一条提取通道。

这就是 6.4.5 人类专家接口在这里的落地依据。不是抄来的通用做法,是被迫的选择。

顺带说一句:已数字化的那一半同样会过期。它有两个必须处理的问题,不处理就会反过来拖累系统。

第一,静态与动态分离。任务模板、角色定义属于静态知识,改一次生效全局。执行记录、技能使用计数属于动态知识,每次任务都在变。两者混在一张表里,必然互相拖累。

第二,时效性管理。技能库里有些条目会过时,比如某个 CLI 工具的用法变了。系统用 use_count、helpful_count 与新鲜度加权排序,让过时条目自然沉底,不靠人定期除草。

7.2.3 算账:这本账必须算清,也要算出上限 ​

第六章警示过花 100 块收 9 毛钱的陷阱。本项目在立项时要求自己回答三个问题:省了什么,花了什么,边界在哪。

7.2.3.1 收益的三本账 ​

第一笔是时间。

一项完整的长任务,从派出去到拿到产物,中间通常有十几到几十个往返。读材料、写、被指出问题、改、再被指出、再改、合并、校对。

这些往返里,人必须出场的只有少数几个节点。定方向、看结论、在卡住的地方做判断。

其余的读、改、复查、再改,全部可以由 Agent 承担。

省下来的是等结果与切上下文的时间,干活时间并没有省。等人等结果,等结果切回思路,这两样一天被切碎几十次,吃人的是这里。

第二笔是直接成本,不能不算,但它一次算不清这本账。

直接成本由三个变量决定:任务拆得多细,每个任务加载多少上下文,用的是哪个档位的模型。任何一个变量变动,总账就跟着变。

下面只算第一个变量,另外两个按固定值处理。这一节算结构,不给某一档的具体金额。

所以任何按单个任务估出来的平均价,都只是某个特定配置下的快照,给样本不等于承诺。

但有一条规律不变,它直接决定系统怎么设计。

拆得越细,单任务上下文越小,但任务数量越多。拆得越粗,任务数量越少,但每个任务的上下文成本会成倍上升。

原因不难理解,上下文是累积的。一个任务如果从第一步跑到第二十步,第二十步要背着前十九步的全部历史。而这些内容在第二十步多半已无用。

这不是线性增长,它随链条变长而迅速恶化。

下面这段代码能把这个判断变成数字。环境是 Python 3.10 以上,不需要第三方库。

python
steps = 20
per_step = 800  # 每一步新增的上下文字符数

cumulative = sum(per_step * i for i in range(1, steps + 1))
isolated = steps * per_step

print(f"串行累计: {cumulative}")
print(f"逐步隔离: {isolated}")
print(f"倍数: {cumulative / isolated:.1f}x")

运行结果是 168,000、16,000、10.5 倍。同一个任务拆成二十个独立步骤之后,重复加载的上下文少了九成。

另一侧是任务数本身。任务拆得越细,数量越多,调度、记录、验收的开销跟着涨。

所以拆到多细是工程选择,要在两头之间找一个平衡点。这也是 6.5.1.1 单一职责与上下文隔离的物理依据。

它不是省钱技巧,不这么做,成本与延迟会失控。

第三笔是人力与隐性损耗。管理成本、沟通摩擦、交接损失,这三样在人多的团队里是灾难;在一个人加一堆 Agent 的结构里,它们不再占用第二个人的时间,转而成为调度开销。

因为 Agent 不需要开会,不会像人那样忘掉没写下来的事,但会忘掉没进上下文的内容,也不需要被说服。

代价是另一面。它们也不会提醒你,这件事其实不该做。

7.2.3.2 两个必须承认的边界 ​

第六章要求盘清两条边界。这个项目上,两条都撞得很实,一条是人力底线,一条是串行等待。

边界一,人力节省有物理边界。这个项目只有一个人。所以人一个都省不掉,只是换了位置。一般情形是比例替代。十个人的团队,优化后可能只剩两个做复核。

原始设想是一个人变成零个人。现实是人从执行者变成了唯一的判断者与责任人。

系统跑得越欢,人要看的东西越多。区别在于,原来花 8 小时做 100 件具体的事。现在花 2 小时看 100 件已完成的事,并对其中 5 件做判断(示意)。

这个判断有一个残酷的推论。如果判断本身的质量不提高,Agent 只会让你更快地生产错误。快从来不等于对。

边界二在时间:卡死的不是算力,而是串行等待本身。

一条加工流水线里,环节之间往往是强依赖。没写完不能审,没审完不能改,没改完不能合。

能并行的,只有同一层里互不依赖的那几个节点,比如多个小节同时写、同时被审。

更要命的是,越靠后的环节越慢。因为它要通读的东西比前面多,要处理的分歧也比前面多,堆算力压不下去。

所以这类流水线的理论下限,不低于最慢一轮乘以轮数,更准确地说,是各轮最慢环节之和(第 1 轮审校 52、修订 36 分钟,第 2 轮 85、83 分钟,四段相加 256 分钟),而不是总工作量除以并行数。任何声称无限并行提速的说法,都是没算过依赖图。

7.2.3.3 一个必须写在明处的态度 ​

算完这本账,能落地的判断只有一条。

它不会把平庸的判断变成高明的判断。它只会让想清楚的人,把想法变成产物的速度提高数倍(估算:1 人 6 个月,对传统 3 人 12 个月,约 6 倍)。

7.2.4 从一个人到一支队伍:组织怎么映射 ​

第六章的原话是,Agent 改变分工,并不取消分工。本项目上,映射过程踩过两次坑,值得原样记下来。

7.2.4.1 第一次尝试:一个 Agent 包打天下 ​

最早的想法很朴素:既然模型什么都会,那就一个 Agent,什么都干。

结果一周就崩了。原因是 6.4.8 讲过的两条,一条都没有落下。

第一,角色冲突。同一个 Agent 既要写书稿、又要改代码、又要做运维检查。它会在不该谨慎的地方谨慎,在不该放手的地方放手。

第二,上下文过载。所有岗位的说明书、规范、历史经验堆在一个会话里,还没干活,上下文就吃掉一半。

7.2.4.2 第二次尝试:照抄人类组织架构 ​

第二个想法也自然:人类团队怎么分,Agent 就怎么分。

方向对了,但它栽在照抄得太细上。人类组织有大量隐含的协调机制:早会、口头确认、抬头不见低头见的默契。这些在 Agent 世界里一条都不存在。

照搬过来,等于给每个 Agent 配了一套它用不上的制度。

7.2.4.3 最终落地的三层结构 ​

真正的解法是把层级压到最薄,只保留三件事:谁调度,谁管项目,谁干活。

角色数量职责
workshop_manager(工作坊管理者)1 个跨项目的顶层调度、任务目录维护、系统级决策
project_manager(项目管理员,PM)21 个单个项目的边界、成员、质量、验收
worker(执行者)64 个只做被派给自己的那一项任务,不越界

此外还有 host_manager(主机管理者)3 个,agent_manager(Agent 管理者)1 个。这两个不占三层,挂在调度层旁边:前者管主机(注册、更新)并可派发任务,后者管 Agent 的创建、配置与下线。表里的 64 个 worker 是注册总数,当前活跃 57 个。这套结构能立住,靠的不是分工细致,而是权限等级把分工钉死了。

系统里的权限分为 0 到 7 级,共八级,各角色的等级集合如下。L0 只读、L1 公告与技能写入、L2 任务增删改查、L3 调度与执行(含自我调度与助理)、L4 Agent 生命周期、L5 项目管理(含派发)、L6 主机管理、L7 系统管理,越往上能碰的边界越远,要担的责任也越重。

等级语义与范围
L0只读:项目、任务、执行记录、公告
L1公告与技能写入
L2任务增删改查
L3调度与执行(含自我调度、建助理)
L4Agent 生命周期(创建、克隆、配置、部署、分组)
L5项目管理(建项目、绑成员、计划管理、派发)
L6主机管理(注册、更新)
L7系统管理(清缓存、重建索引)
角色可执行等级意味着什么
worker0, 1, 2, 3可读写自己的任务与执行记录,可自我调度、建助理、写公告与技能;不能给别的 Agent 派活
project_manager0, 1, 2, 3, 5多一级 L5,可建项目、绑成员、编排计划、派发任务
agent_manager0, 1, 2, 3, 4多一级 L4,可创建、配置、部署 Agent;可派发任务,不能管项目与主机
host_manager0, 1, 2, 3, 6多一级 L6,管主机(注册、更新)并可派发任务;不能创建、配置、部署 Agent
workshop_manager0 到 7全域

这里有个关键设计:派发任务是 L5。也就是说,一个 worker 天生无法给任何其他 Agent 派任务。这一条看着不起眼,却是整套系统不失控的第一道闸。

如果 64 个 worker 可以互相派发任务,很快就会陷入无休止的互相确认、委派、催办。这就是教科书级的 Agent 失控。

这一条后来遇到过一个现实挑战:确实存在某个 worker 临时需要指挥别人的场景。

解决方式不是把 L5 降级给所有人,而是加一个带过期时间的临时豁免。只放开三个调度工具(ao_dispatch_task、ao_schedule_task、ao_quick_cmd_send),建项目、改 Agent、主机管理一律仍然拒绝。

判据一句话:这是让他能派发任务,不是把他升成 PM。而且豁免用时间戳,不用开关,到期自动失效。因为忘了关的代价,是永久授权。

这一节按 6.3 的四节走了一遍:定位、盘点、算账、组织。四问是定位那一节的核心。手里这份蓝图足够清楚了,可以进入下一节:7.3 架构落地。

7.3 架构落地:八个支柱在真实项目里长什么样 ​

6.4 讲的八个支柱是一张标准图。标准图告诉你每根支柱该有,却不会告诉你它落地后长什么样。我们在这个项目里把八根支柱逐一试了一遍,没有一根和图纸完全一致。

这一节逐个交代每根支柱的具体形态、形成原因,以及它和理论图不一样的地方。

7.3.1 框架选型:为什么最后是自己搭 ​

6.4.1 给了三条路:托管平台、开源自建、完全自研。前两条我们真试过,都撞了墙;第三条评估后放弃,没有投产。

先说托管平台,Dify、Coze 这一类,上手确实快,可视化拖拽两个小时就能跑出一个能对话的 Agent,但一到真实场景就露馅,问题集中在三处。

数据出不去:Agent 的工作产物是本地仓库的代码、本地数据库的记录,云平台读不到,我们也不该让它读到。

长链状态看不见:假设一个跨 20 个节点的任务卡在第 13 个节点,平台只显示“运行中”,你分不出它是在思考、在等外部接口、还是已经死了。这一点在真实工程里是致命的。

生命周期接不上:任务需要挂起、人工审批、恢复,需要超时自动催办,需要失败局部重试而不是整体重来,而这些平台要么没有,要么改不动。

再说开源自建,LangGraph、CrewAI、AutoGen 这一类框架解决了数据问题,但撞上另一堵墙:它们把调度藏在框架里。

这正好是 6.5.4.1 描述的那个痛点,就像没有 Jira、没有 CI 的年代,项目经理靠口头派活。框架内部把谁派的、派给谁、对方接了没、结论读了没,全部消化在内存里,外面什么也看不见。

所以最终的选择是:运行时用成熟的开源 Agent 框架,调度层自己写。

为什么不干脆全自研?全自研要连运行时一起写,等于同时维护模型适配与治理两层,模型一更新就得跟一轮,收益抵不上成本,所以只自研调度层。

这 98 个是内核 MCP 服务器注册的全部工具,92 个静态定义加 6 个动态注册。清单对全体 Agent 可见;能不能调,按权限等级过滤。MySQL 与 Redis 两个 MCP 服务器分别有 5 个和 7 个工具,不在这个数里。

这个组合的好处,一句话说清:把不确定的推理和确定的治理彻底分开。

运行时负责聪明,调度层负责靠谱:换模型、换运行时,调度层一行不用改。桥的会话寻址、事件格式、重连适配仍要各写一遍(见 7.1)。反过来,调度逻辑要升级,也不影响任何一个 Agent 干活的方式。

代价也要说清楚:这条路需要我们自己维护约 19,800 行内核代码、10,800 行看护脚本、7,300 行后端接口,这不是轻量方案,是用工程换确定性。

如果你的场景就是一个人问一个问题、答一句话,选这条路是浪费。

7.3.2 通信协议解剖:一条真实消息长什么样 ​

6.4.2 给了五个顶层字段的通用消息模型:header、addressing、control、payload、context。这个模型作为教学示意是对的。但在真实系统里,这套字段几乎一条都不这么用。

原因很简单:消息不是数据仓库,它只需要把接收方带到那条记录上。

这个项目里,一条真实任务消息的全部内容是这样的(ID 已脱敏):

json
{
  "task_run_uuid": "run_general_82a60b8f2a78",
  "send_agent": "agentos_core",
  "self_session_id": "agent:agentos_core:main",
  "msg_type": "dispatch"
}

只有四个字段,我们逐一说清它们为什么存在,以及别的字段为什么不要。

  • task_run_uuid:本次执行的唯一编号,是去数据库取指令、回写结案的唯一钥匙。不写,接收方不知道自己在干哪一件活。
  • send_agent:发送方是谁,决定回执往哪回、出事找谁。不写,回执找不到主人,告警找不到债主。
  • self_session_id:发送方自己所在的会话编号,回执按它归位。不写,回执错落主会话,污染人机对话通道。
  • msg_type:消息语义类型。它只有三个值,混一个就出错。
取值语义接收方该做什么
dispatch派活干活,结论写进结案
receipt回执读别人的结论、判断、然后签收,绝不重做
urge催办按告警说明响应,判断自己是真死还是假死

receipt 是最容易搞错的一种。它的正文里带着上一环的结论,看起来很像一个新任务。如果接收方把它当成新任务重做一遍,就白烧一整轮 Token,还会多出一条语义重复的执行记录(execution)。

所以设计上做了一件很实用的事:签收是强制的。

收到 receipt 之后,必须调一次签收接口,系统才认为这件事真的被读过了,否则发起方永远不知道对面读了没读,消息等于丢了。

这里有个反直觉但重要的决策:闭环点放在签收,而不是发出。如果消息一发出就算完成,那么没签也算完事,重发机制和漏签告警全都看不见。

再回到为什么只有四个字段。6.4.2 的五个顶层字段,在这个项目里压成了四个。那一节说消息要自包含,我们的理解是:自包含指的是接收方能独立完成任务,不是指消息里塞满所有数据。

真正的自包含是这样实现的。消息只带一个指针,接收方拿这个指针去数据库取出指令全文、任务模板、前置任务的结论、超时设置和会话归属。数据库才是自包含的载体,消息只是钥匙。

这样做有三个直接好处。

  • 消息不会过大。一条指令可能上千字,塞进消息里,队列和日志全部膨胀。
  • 结论可以回写。收到消息时任务还没干,结论根本不存在,塞不进消息。
  • 状态只有一份。消息里带一份、数据库里存一份,两者必然打架。

下面这段代码把这套设计落到最小可运行的形式。它只做一件事:把四个字段的消息推入目标主机、目标 Agent 的队列。示例里的主机名与 Agent 名都是示意,不对应真实部署。

python
# 环境:Python 3.10+,redis-py 5.x,Redis 7.x;示例省略认证,生产从环境变量读
import json
import os
import redis

r = redis.Redis(
    host=os.environ.get("AO_REDIS_HOST", "127.0.0.1"),
    port=6379,
    password=os.environ.get("AO_REDIS_PASSWORD") or None,
    decode_responses=True,
)
msg = {
    "task_run_uuid": "run_general_82a60b8f2a78",
    "send_agent": "agentos_core",
    "self_session_id": "agent:agentos_core:main",
    "msg_type": "dispatch",
}
queue = "ao:queue:robert_mac:agent:book_writer"
r.rpush(queue, json.dumps(msg, ensure_ascii=False))

队列键里带主机名,是下一小节要解释的细节。

7.3.3 存储分工:MySQL 是真相,Redis 是速度,文件是产物 ​

6.4.3 讲了文件、关系库、向量库、缓存四类存储。这里只用了三类,没有用向量库。

这个“不用”值得先解释。系统的知识检索量不大,关键查询都是按 ID 或状态做的精确匹配,不是从海量资料里找相似片段。用向量库存任务状态,属于缘木求鱼。

三类存储的分工如下。

三层之间只有一条原则:数据以 MySQL 为准,缓存只是加速。缓存丢了代价是变慢,真相丢了代价是重来。

边界要划清:队列与实体缓存可以丢,表现为变慢;计划索引不能丢。看门狗的读路径是:先取 ao:idx:plan:all 里的计划,再按 ao:idx:execution:by_plan:{plan_id} 取子任务,最后扫 ao:idx:execution:status:running 与 ao:idx:execution:status:pending 两条执行索引。

计划索引被清空,这条链第一环就断了,看门狗会停止调度,需要从 MySQL 全量重建,窗口在本项目是分钟级。

这条原则在实战中救过一次命。有一次计划索引被误清空,系统瞬间看不到任何计划,表面上全系统停摆,但数据一条没少,从 MySQL 重建索引之后完全恢复。如果当初把状态只存在 Redis 里,那次就是灾难而不是故障。

关于队列,只留一句。Redis 兼做任务投递队列,键是 ao:queue:{host_id}:agent:{agent_id}。带 host_id 是因为队列是进程级的。每个主机的 daemon 只订阅本机前缀的队列,按主机划分命名空间。工作节点上也起 daemon 时,两个进程不会争抢同一队列,回执也不会重复投递。投递出去之后怎么走、怎么编排,见 7.4.2 与 7.4.3。

7.3.4 知识数字化:三层记忆各管什么 ​

6.4.6.2 的输入向与输出向要求预置库与运行库分开。在这个项目上,这条原则落地成了四层:预置库一层,运行侧再分三层,每层管完全不同的事。这里的“三层记忆”,指的就是运行侧这三层。

预置库这一侧落在角色定义、项目说明书与 standards 文件,见 7.3.6。下表只列运行侧的三层。

层载体存什么谁写生命周期
工作记忆本地 memory/ 目录今天做了什么、遇到什么坑、明天的打算Agent 自己按日累积,可检索
技能库库表记录 56 条(启用 55);正文在各主机文件系统“怎么做”,可复用、有操作性的做法任何 Agent 贡献长期,靠信号排序
公告库(工作公告)数据库 1,140 条(有效 944;截至 2026-11-04 12:15)“谁干了什么”,决策、踩坑、交接、配置变更任何 Agent 发布长期,可追溯

6.4.4.1 的第一类工具负责非结构化介质的数据化:OCR 管图片和扫描件,语音转写管会议录音,视觉解析管图表和界面截图。

这一层在这里没有落点。这里要数字化的知识本来就是纯文本,书稿、代码、配置、任务说明全在文件系统里,没有扫描件,没有会议录音,没有界面截图。

隐性知识的抽取由人类专家接口承担,见 7.3.5。切片与索引的活儿还是有的,只是换了承担者:一部分交给文件系统,目录即分类,文本检索即索引;一部分交给数据库的字段与索引。

为什么工作记忆必须存在文件系统里,而不是数据库?因为它要能被人和 Agent 同时直接读写。人打开一个 Markdown 就能看、能改、能 diff,Agent 用普通文件读写就能追加。放进数据库,人和 Agent 之间就多了一层接口,任何多余的接口都会成为故障点。

为什么技能库的计数必须落数据库?因为它需要跨主机共享和按信号排序。技能正文留在各主机的文件系统里,能直接读、直接改;索引、白名单与计数落在库表。谁用过几次、谁觉得有用,只有集中到库里才统计得出来,use_count 和 helpful_count 也才有意义。这正是 7.3.6 要讲的循环。

7.3.5 人类专家接口:命令行最后一定不够用 ​

6.4.5 说人类专家接口要有三条通道:知识提取、知识判别、结果批判。这个项目全都有,只是不是照着图纸的顺序长出来的。

最早是没有界面的。所有操作靠命令行和对话。看任务状态要查数据库,催一个卡住的任务要发指令,审批要回一句话。

这套方式在一个人、几条任务线的时候够用,但三条线一开,立刻出现三个问题。

状态看不见:要判断现在有没有事要处理,必须一条条查,而人不会天天主动查。

判断无处下手:任务详情、前置结论、执行耗时分散在几个地方,做判断之前先花十分钟拼信息。

审计无从谈起:出问题要回溯,只能翻日志。

所以最后必须做一个企业级 Agent 控制台,一共八大模块。系统复杂到一定程度,它就是必需品。

模块职责
1. 项目管理业务边界、项目隔离
2. 项目组管理成员角色分配
3. Agent 管理以项目为维度挂载、角色映射(模型按会话绑定)
4. 会话管理上下文监控、历史记忆恢复
5. 任务管理执行链路追踪、全生命周期状态机
6. 快捷指令强类型任务接口、模板自动渲染
7. 技能共享库领域技能发布与更新
8. 审计与留痕过程溯源、日志分析

其中第 8 项审计与留痕,是控制台存在的真正理由。第 1 到第 7 项都可以用命令做到,只是麻烦。唯独审计这一项,命令行的效率低到不可接受。它需要按任意维度聚合:这个项目一共跑了多少、哪个环节最慢、哪类任务失败最多、某个 Agent 最近在干什么。

这里必须说一个真实的缺陷:某些管理操作的审计到最后也没有落盘。系统能回答任务怎么跑的,但有一部分谁改了什么配置,查不到。完整的边界清单见 7.4.5。

回头看开头那句话,现在可以交代“顺序反过来了”具体指什么。三条通道在这套系统里各落一处。

知识提取,落在角色定义与任务模板的配置上,靠人把判断规则写进去。知识判别,落在快捷指令和任务确认上,靠一次强类型的派发把人拉回来拍板。结果批判,落在审计留痕和结论复核上,靠事后回查。

图纸上的顺序是先提取、再判别、最后批判,一条线走下来。这里的顺序是反的:先有的是命令行里的提取,控制台补上的是判别,批判最晚做,也做得最浅。三条通道不是照着图纸的顺序长出来的,是各自长出来的,长短不齐。

7.3.6 知识预置与沉淀:技能库的闭环怎么转 ​

6.4.6 强调知识要预置进去,还要沉淀回来。在这个项目上,沉淀这一半做得比预置更有意思。

预置这一半是标准的:每个 Agent 启动时读自己的角色定义、读项目说明书、按需检索技能库,这三样都有明确路径,不靠猜。

三层的判据很好记:读了能照做,进技能库。读了只知道谁干了啥,进公告库。只对当下有用,进工作记忆。

三层不能混,混了会出两种病。

技能库被流水账污染,搜“怎么部署”搜出来一堆“我今天部署了一次”,技能库就废了。

公告库被操作手册污染,想查上周谁改了这个配置,翻出来一堆二十步的操作指南,公告库就废了。

沉淀这一半,设计上做了三个反常识的决定。

第一,开放写入,不设人工审核。任何 Agent 都可以往技能库贡献一条做法。没有评审委员会,没有提交工单。为什么敢这么干?人工审核会成为整条链路最慢的一环。56 条技能(启用 55)的时候,人工其实还审得过来;我们是为规模提前放弃这一环,免得库长起来就过时。

第二,用信号筛,不用人筛。既然不人工审,怎么保证质量?靠两个计数器:use_count 记录被取用几次,helpful_count 记录被认可几次。排序按一个加权分算,不只看谁多谁前。

python
# 环境:Python 3.10+;数据从 MySQL 查出后逐行计算
from datetime import date, datetime

def skill_score(helpful_count: int, use_count: int, updated_at: datetime) -> float:
    days = (date.today() - updated_at.date()).days
    freshness = max(0, 30 - days) * 0.3
    return helpful_count * 5 + use_count + freshness

这个公式解决一个很实际的问题:如果只按累积量排序,新技能永远沉底,因为它天然是 0,老技能靠历史积累霸榜。加了新鲜度加成和更高的认可权重之后,一条刚落地且被认可的新技能,有机会追上靠时间堆起来的老技能:新技能 1 次认可、30 天内更新,得分是 14;老技能 2 次认可、不再更新,得分是 10。

落到 SQL 上,查询是这样:

sql
-- 环境:MySQL 8.0+,表 ao_skill 需含 skill_name / helpful_count / use_count / updated_at / active_status 五列
SELECT skill_name,
       helpful_count * 5 + use_count
       + GREATEST(0, 30 - DATEDIFF(NOW(), updated_at)) * 0.3 AS score
FROM ao_skill
WHERE active_status = 1
ORDER BY score DESC
LIMIT 5;

第三,允许无用票。helpful 除了 1 还有 -1。一条技能被多人标记无用,会被扣减。这是让过时知识自然沉底的主要机制之一。不是靠人定期除草,而是靠使用者投票。

这套循环跑起来之后的真实状态,按累计取用次数排的前五名如下(数据截至 2026-11-04)。

技能分类被取用被认可
Playwright 无头浏览器browser141
本地文生图 API(SDXL + LoRA)ai120
Tavily CLI 联网检索search120
中文改稿诊断writing70
GitHub CLI 仓库与 CI 查询github60

请注意被认可这一列几乎全是 0。这不是缺陷,是真实状态:取用是自然动作,认可是刻意动作。大多数时候,人用完就走,不会回头投票。

这个数据反过来验证了一件事:如果只靠认可来排序,这个库基本等于没有排序。权重设计里把 use_count 也纳入,正是为了照顾这种真实行为。

7.3.7 人员与组织映射:落到实现上是什么 ​

7.2.4 讲了角色的三层结构。这一节讲它在代码和存储里到底长什么样。角色如果只写在文档里,它就不存在。

一个 Agent 在系统里由五样东西绑定。

绑定项实现形式作用
身份agent_id(全局唯一,仅小写字母数字下划线)寻址、队列、路径全部依赖它
归属project_id + host_id决定它在哪个业务边界、哪台主机上跑
职责agent_role(五类:三主两辅)+ 权限等级(L0–L7)决定它能调哪些工具
能力该 Agent 名下的任务模板 + 技能白名单决定它能干什么
会话归属main / task / oneshot 三类任务会话(另有 assistant)决定这次执行在哪个上下文里发生、回执落在哪

agent_id 的命名约束不是洁癖,是刚需。它同时被用作 Redis key 的一部分、文件系统路径的一部分、命令行参数的一部分。这三处任何一处出现大写、空格、中文,就会在某个意想不到的地方炸掉。所以约束必须在入口处卡死,而不是等到某次部署失败再回头查。

project_id 的作用比分组重得多,它决定任务模板的可见范围、项目管理员的管理边界、日志聚合的统计单元。不绑定项目,Agent 就是悬空节点,能干活,产出无处归档。职责与权限另挂在它名下:agent_role 分五类(三主两辅),权限分 L0–L7 八级;同一种角色在不同项目的信任程度不同,两者分开记。

会话归属是最后一样。main 是长期的人机对话通道,也是所有回执的默认落点;task 一次执行一个现场,上下文独立,跑完即归档;oneshot 用完即弃;assistant 是常驻助理的专属会话,不承担任务执行。系统现在有 4,145 个会话(启用 4,136)。默认每派发一次就开一个 task 会话,一个执行对应一个现场;全挤在一个会话里,它早就爆了。

7.3.8 能力按需挂载:三种能力的边界在哪 ​

6.4.8 讲了一个很关键的原则:能力先精简,再按需挂载,挂载还要有退出条件。否则多个能力同时挂载、互相干扰判断,就是模型打架,最后还会演成 Token 灾难。

这套系统上有三种不同粒度的能力。它们的边界必须分清,否则会互相污染。

能力形态是什么挂在哪数量什么时候加载
任务模板(Task Base)一件完整工作的说明书Agent 名下483(启用 449)派活时随指令注入
MCP 工具(Tool)一个确定性的操作内核全局98(92 静态 + 6 动态)常驻注册,按权限过滤调用
技能(Skill)一套可复用的做法技能库 / 白名单56(启用 55)按需检索或按白名单挂载

三种能力形态的数量口径见上表,均截至 2026-11-04。

三者的分工,用一句话就能分清:任务是做什么,工具是能操作什么,技能是怎么做才好。

混淆三者的后果非常具体。

把技能写成任务:明明是一套操作手法,却被做成任务模板。结果是每次都要派一次活、走一遍完整生命周期,为了查个文档开一条执行记录。

把任务写成工具:明明是一件需要判断的复杂工作,却被做成 MCP 工具,结果是它只能在代码里硬编码逻辑。工具本身不承担判断;一旦让工具做判断,它就不再是确定性操作。

把工具写进技能:技能正文里让人去手敲命令,不让 Agent 调工具,结果是每次都要重新踩一遍参数格式的坑。

按需挂载在这个项目上有一个具体实现:技能白名单。每个 Agent 可以配置一份 skills_allowlist:配了就只加载白名单里的技能,不配就继承全局。这样一个专门写前端组件的 Agent,不会被一堆运维技能干扰上下文。

为什么这件事在 Token 上很敏感?回到 7.2.3 那条规律:上下文的成本是累积的,不是线性的。往每个任务的上下文里多塞两千字无关的技能说明,单看一条任务只是些许浪费。按一千次任务算,就是约两百万字,折合百万 token 量级;再乘单价,就是一笔看得见的支出。

所以按需挂载从来不是架构美学,它是账本上算得出来的钱。

至此,6.4 的八根支柱在这个项目上都有了明确形态。这里的“落到实处”指的是有明确形态,不等于每根都长齐:其中知识数字化的介质层只落了文本这一半,扫描件、录音、截图都没有落点。没有落点,也是一种落地结论。

它们没有一根是照抄标准图长出来的。每一根都是撞了墙之后,退回来看清边界,才定下形态。架构说完了,接下来看它怎么变成一条条可执行的任务:7.4 任务规划与执行流。

7.4 任务规划与执行流 ​

6.5 讲了任务规划与执行的全流程:怎么拆、人在哪里介入、用什么调度。这一节换一个视角,看这些机制落在一个真实写作项目上是什么形状。

先给结论:任务不是一段话,而是两份文本的合成,外加一段由系统注入的会话上下文。 执行不是一条状态线,而是两条;编排不是任意 DAG,而是三种够用的拓扑。 人在回路不是审批弹窗,而是三道自动机制用尽后的手动挡。 最后还要说清楚,这套系统查得到什么,查不到什么。

五件事连起来,就是一条任务从派发到归档的完整路径。

7.4.1 任务从哪来:两份文本,一段注入 ​

很多读者以为派任务就是发一段话,在这套系统里,发出去的那段话只占最终执行指令的一部分。 真正进入执行现场的是两份文本:任务模板(Task Base)与本次指令(Instruction)。 此外还有一段会话上下文,它不参与合并,只由系统在最前面注入。

图里的 483 条(活跃 449)是 2026-11-01 的快照。

为什么要拆成两份? 因为它们的更新频率不在一个量级上。

模板写的是这类活的标准做法。 比如写一节书稿,要读项目说明、要对齐术语、要跑风格检查、要写进指定目录。 这些规则半年可能才改一次。

本次指令写的是这一次的具体要求:写哪一章、第几节、上一节讲了什么、这一节要接住哪个概念、字数多少。 每派一次活,这些内容都不一样。

如果把两者写在一起,会出现两个后果。 第一,模板会被污染,每派一次活就多一个版本,最后没人说得清哪一版是标准。 第二,历史无法比较。 两次执行看起来完全不同,也就无法判断这次的结论为什么和上次不一样。

拆开之后,模板成了稳定的公共资产。 任务模板在系统里是一行 ao_task_base 记录,正文就是执行时看到的【任务说明书】。 每一条执行记录只携带自己那一段差异。 两次执行放在一起,模板部分相同,差异部分就是这次的特殊信息。

合并与注入的规则并不复杂。 系统先把会话上下文注入最前面,再把本次指令与任务模板合成一段。

装配顺序是:上下文 → 指令 → 模板。 理解顺序正好相反:先看上下文知道在哪,再看指令做什么,最后查模板怎么做。 模板是背景,指令是当前目标,上下文是执行位置,三者不能混成一句。

下面把合并过程写成代码,环境是 Python 3.7 及以上,不依赖第三方包;四处代码各自标注最低版本。

python
# compose_task.py
from dataclasses import dataclass
from hashlib import sha256


@dataclass(frozen=True)
class TaskBase:
    task_id: str
    version: int
    body: str

    def digest(self) -> str:
        return sha256(self.body.encode("utf-8")).hexdigest()[:12]


@dataclass(frozen=True)
class Instruction:
    run_id: str
    session_key: str
    body: str


def compose(base: TaskBase, inst: Instruction) -> str:
    context = (
        "【会话上下文】\n"
        f"run_id: {inst.run_id}\n"
        f"session: {inst.session_key}\n"
        f"template: {base.task_id}@v{base.version} ({base.digest()})\n"
    )
    return (
        f"{context}\n"
        f"【本次指令】\n{inst.body}\n\n"
        f"【任务说明书】\n{base.body}\n"
    )


if __name__ == "__main__":
    base = TaskBase(
        task_id="book_write_section",
        version=7,
        body="按小节写作,正文 2000 到 4000 字,代码必须可运行。",
    )
    first = compose(
        base,
        Instruction("run_001", "agent:writer:main", "写 7.4.1,主题是任务从哪来。"),
    )
    second = compose(
        base,
        Instruction("run_002", "agent:writer:main", "写 7.4.2,主题是状态机。"),
    )

    assert first.startswith("【会话上下文】")
    assert "【任务说明书】" in first
    assert base.digest() in first and base.digest() in second
    print(first)
    print("两次执行的模板摘要相同:", base.digest())

这段代码有两个刻意的设计。 模板正文摘要写进上下文,事后可以在日志里比对这次用的是哪一份模板正文,但摘要不防篡改。 摘要只哈希 body,不含 task_id 与 version;版本信息由 task_id@v{version} 单独标注。 摘要只取前十二位,够用,也不会把指令撑长。

还有一个细节必须讲:派发路径里的会话上下文为什么必须由系统注入。 它包含会话编号、计划编号、前置任务、回执落点,每次都不一样,不能写进模板。 上面的示例只保留了会话编号与模板摘要,真实派发会把其余字段一并注入。

更关键的是,这些字段决定回执回到哪里。 7.3.2 已经讲过缺发起方会话编号的后果:回执会按默认规则落回主会话。

所以这里只补一句:经由派发产生的执行,上下文由系统写进执行指令的第一段,调用方不能自己拼。 计划激活走另一条路径,只把上下文注入投递消息,不回写指令正文;session_id 与 plan_id 仍记在执行记录上。

模板管该怎么做,指令管这一次做什么,上下文管在哪里做。 两份文本加一段注入,齐了,一条任务才具备可复现的起点。 少任何一样,后面的状态、回执和审计都会跟着失真。

指令拼好了,接下来是派发。 派发不是把文本发出去就完事,它要做四步。

第一步,在 ao_task_execution 里创建一条执行记录,状态是 pending。 第二步,把拼好的指令、任务编号、目标会话组装成一条消息。 第三步,把消息推进目标 Agent 的队列,这里是 Redis 的 LPUSH。 第四步,执行方(即接收方)取走消息,只把状态从 pending 改成 running。 started_at 要等执行方真正进入本轮 run、读到指令时再写。

队列可能重复投递。 记录先建、消息后发,同一条 run 消息重发时按 run_id 去重,不会多出执行记录。 这种情形叫重复投递,去重管得住。 另有一种情形叫重复执行:重试时新建一条 run,去重管不了,只能靠上限封住。

这四步走完,一条任务才算真正在路上。 下面看它在路上会遇到什么。

7.4.2 两条状态轴与四条不变量 ​

6.5.1.2 讲过任务要有状态机。 我们这个项目上的状态机有两条平行的轴。 一条看事情干完没有,另一条看结论被读没有。

text
第一轴:执行轴(这件事干完了吗)
  draft ──→ pending ──→ running ──┬──→ succeeded
                                  └──→ failed
  终态:succeeded / failed / cancelled / archived
  计划里的步骤从 draft 起步,部署后转 pending

第二轴:回执轴(结论被读了吗)
  needs_reply = 0  不需要回执
  needs_reply = 1  待回执,任务已派,还没交作业
  needs_reply = 2  已认领(发送中或已发出)
  needs_reply = 3  已签收,闭环

为什么要两条轴? 因为干完了和对方知道了是两件事。

一条任务可以停在 succeeded,结论躺在库里,发起方却以为它还在跑。 只记执行轴的系统,会在这里丢东西。 它不会报错,也不会告警,只是安静地少了一次闭环。 不过它不是完全无声:回执会重发,最终置回执状态 ack_state='unacked' 待人工处理。

回执轴上另有四个时间戳、一个已读标记和一个回执状态,各记一件事。 这六个字段按发出、送达、阅读三组看。

  • reply_sent_at:结论发出的时间。重发会覆盖成最新一次,所以 reply_read_at − reply_sent_at 量的是距最近一次发出,不是首次。
  • reply_delivered_at:结论送达的时间。投递失败重试时,它和发出时间不同。
  • reply_read_at:首次读的时间。
  • reply_read_last_at:只记重复签收的最近一次。
  • reply_read:读了没有,只有 0 和 1。
  • ack_state:回执状态枚举,取 none / sent / delivered / read / unacked。它只是展示用的派生值,真值以 needs_reply 为准。

发出和送达必须分开记。 已发指消息成功入队,送达指执行端回 ACK 并写下 reply_delivered_at。 这个细节来自一次真实故障。 消息发出去了,系统认为已发,对面却没收到,因为投递层的目标进程不在。

如果只有一个已发标记,这件事永远发现不了。 分开之后,调度器的超时巡检(下称看门狗)能看见发了但没送达,直接重投。

注意:投递层的目标进程不在时,消息会显示已发,但对方永远收不到。

状态机要成立,需要四条不变量。 第一,执行轴只能单向走,draft 到 pending,pending 到 running,running 到 succeeded 或 failed,终态不再变化。

第二,run_status 不能被普通更新接口修改,只能由结案、取消、归档这些专用动作改变。 第三,回执轴由派发写入 0 → 1,之后按 1 → 2 → 3 推进;2 表示已认领,覆盖发送中与已发出,发送失败会显式回滚 2 → 1(UPDATE ... SET needs_reply=1 WHERE needs_reply=2 AND reply_sent_at IS NULL),签收接口不做跳级校验。 第四,四个时间戳、一个已读标记与一个回执状态各自独立,不能用一个字段兼任两件事。

第二条最容易被当成小题大做,它的真实作用不是防误操作,而是防统计失真。 如果一个任务可以被外部随手改成成功,那么成功率、耗时、告警、审计全部失去意义,账本可以记错,但不能被人改。

下面是一个最小实现,它不连接数据库,只把两条轴和四条不变量写成代码,需 Python 3.10 及以上。

python
# execution_state.py
from dataclasses import dataclass
from datetime import datetime, timezone


@dataclass
class Execution:
    run_id: str
    status: str = "pending"
    needs_reply: int = 0
    sent_at: datetime | None = None
    delivered_at: datetime | None = None
    read_at: datetime | None = None
    read_last_at: datetime | None = None

    def dispatch(self, need_reply: bool = True) -> None:
        if self.status != "pending":
            raise RuntimeError("只有 pending 状态能派发")
        self.needs_reply = 1 if need_reply else 0

    def start(self) -> None:
        if self.status != "pending":
            raise RuntimeError("只有 pending 状态能开工")
        self.status = "running"

    def finish(self, ok: bool) -> None:
        if self.status != "running":
            raise RuntimeError("只有 running 状态能结案")
        self.status = "succeeded" if ok else "failed"
        # 结案只推进执行轴,不动 needs_reply

    def claim_reply(self) -> None:
        if self.needs_reply != 1:
            raise RuntimeError("只有待回执的任务能被抢占")
        self.needs_reply = 2
        self.sent_at = datetime.now(timezone.utc)

    def deliver(self) -> None:
        if self.needs_reply != 2:
            raise RuntimeError("没有待送达的回执")
        self.delivered_at = datetime.now(timezone.utc)

    def ack(self) -> None:
        if self.needs_reply != 2 or self.delivered_at is None:
            raise RuntimeError("回执未送达,不能签收")
        now = datetime.now(timezone.utc)
        self.read_at = self.read_at or now
        self.read_last_at = now
        self.needs_reply = 3


if __name__ == "__main__":
    job = Execution("run_001")
    job.dispatch(need_reply=True)
    job.start()
    job.finish(ok=True)
    assert job.needs_reply == 1
    job.claim_reply()
    job.deliver()
    job.ack()

    assert job.status == "succeeded"
    assert job.needs_reply == 3
    assert job.sent_at <= job.read_at <= job.read_last_at
    print("执行轴与回执轴均已闭环")

这段代码里,结案只推进执行轴,不自动把回执标成已读,送达和签收也必须分开调用。 这不是啰嗦,而是让每个动作都能对应一个真实事件。

如果结案时顺手把 needs_reply 置为 3,系统就会认为对方已经读了。 可实际上,对方可能还没打开。 一旦这样写,重发机制和未读提醒都会失效。

所以两条轴之间没有自动联动:结案后回执停在 1;看门狗抢占成功,把它推到 2 并发出回执;签收才到 3。 中间每一步都由独立动作完成,不会因为上游结案就替下游签字。

7.4.3 三种编排拓扑:串行、并行、扇入 ​

状态闭环了,接下来看这些任务怎么排。 6.5.1.3 讲过有向无环图(DAG),我们在这套系统里没有把它做成任意图,而是收敛成三种真实可用的形态。

原因是大多数业务场景只需要这三种,放开任意图只会增加调度器的复杂度。

第一种是串行链,节点之间有先后依赖。

实现方式是给每个执行记录(拓扑里的一个节点)记两个指针:前置任务 prev_task、后置任务 next_task。 前置成功了,后置才会被激活。 典型场景是日志管线:先做主会话快照,再聚合全项目执行记录。 顺序颠倒就会漏数据,因为快照还没进库,聚合就看不见当天的主会话现场。

第二种是并行扇出,节点之间互不依赖。

多个节点同时激活,看门狗同时扫描。 写一本书时,各小节之间没有依赖,这是最能提速的地方。 一章八节同时开工,理论上接近八倍;受并发配额与下游排队限制,实际倍数会低不少。

第三种是扇入(汇聚),等全部子节点完成再继续。

子节点在自己的执行记录里用 parent_run_uuid 指回父节点。 三个子节点全部成功,父节点才会被激活。 审校、试读与核查可以并行,三者都完成之后,才能进入汇总修订。 这一步不能提前,提前就会拿着半份意见改稿。

三种拓扑可以组合,但有一条绝对规则。 串行关系和扇入关系必须二选一:prev_task 与 parent_run_uuid 不能同时声明。

一个执行记录如果既有前置任务,又指回父节点时,调度器就无法判断该等哪一边。 逻辑上互斥,实现上必须卡死:计划创建或部署时直接拒绝,不会留到运行期。 这不是限制表达力,而是消灭歧义。

注意:校验不通过时,被拒绝的是整个计划,不会出现某条任务停在 pending 的中间态。

扇入还有一个边界条件:汇聚点的通知归属。 一条规则来自实战:父节点完成后,结论默认推给激活这个计划的那条执行记录。

真实路径是:ao_plan.task_run_uuid 指向激活计划的执行记录(execution),扇入完成时取它的 session_id 投递;这条链找不到,才回落到创建者的主会话。 所以归属由「谁激活」决定,而不是由「谁最初发起」决定。

一个助理替主会话激活了计划,结论就先回到助理的会话,发起方不会自动收到,搭计划时要自己安排转交。 这个坑不在任何架构图里,只在真实运行中才会出现。

校验函数做三件事:串行与扇入是否同时声明,子节点是否存在,子节点是否重复。环境是 Python 3.10 及以上。

python
# validate_topology.py
from collections import Counter
from dataclasses import dataclass


@dataclass
class Node:
    name: str
    prev_task: str | None = None
    next_task: str | None = None
    parent_run_uuid: str | None = None


def validate(nodes: list[Node]) -> None:
    names = {node.name for node in nodes}
    for node in nodes:
        if node.prev_task and node.parent_run_uuid:
            raise ValueError(
                f"{node.name}: prev_task 与 parent_run_uuid 不能同时声明"
            )
        for ref in (node.prev_task, node.next_task, node.parent_run_uuid):
            if ref and ref not in names:
                raise ValueError(f"{node.name}: 引用 {ref} 不存在")

    seen = Counter(
        (node.parent_run_uuid, node.name)
        for node in nodes
        if node.parent_run_uuid
    )
    for (parent, name), count in seen.items():
        if count > 1:
            raise ValueError(f"{parent}: 子节点 {name} 重复")


if __name__ == "__main__":
    graph = [
        Node("write_1"),
        Node("write_2"),
        Node("review", parent_run_uuid="merge"),
        Node("beta", parent_run_uuid="merge"),
        Node("merge"),
    ]
    validate(graph)

    cases = [
        (
            "串行与扇入同时声明",
            [Node("a", prev_task="b", parent_run_uuid="c"), Node("b"), Node("c")],
        ),
        ("引用不存在的节点", [Node("a", prev_task="ghost")]),
        (
            "子节点重复",
            [
                Node("merge"),
                Node("review", parent_run_uuid="merge"),
                Node("review", parent_run_uuid="merge"),
            ],
        ),
    ]
    for label, bad in cases:
        try:
            validate(bad)
        except ValueError as exc:
            print(f"按预期拒绝({label}):{exc}")

代码很短,但它守住的是调度器的底线,调度器可以复杂,规则必须简单。 节点用列表存放,同一个 name 出现两次,重复检查才有着落。 规则一旦含糊,出错时就无法判断是数据错了还是调度错了。

7.4.4 人在回路:三道自动机制用尽之后,人怎么推一把 ​

任务能排、能跑,接下来是它们卡住的时候,人怎么介入。 6.5.2 讲过人在回路要有挂起、通知、恢复,我们这个项目的实现方式比较特殊。 它没有阻塞式审批,用的是看门狗巡检加事后干预。

原因很实际:阻塞式审批在长链条里会把整条流水线冻住。 ch07 一个章的全管线计划就有 97 条执行记录,如果每条记录都等人确认,人立刻成了瓶颈。 并行本来是为了快,结果全卡在确认按钮上。

所以这里的「人在回路」是三道自动机制,外加一道人工干预,一层比一层重。

text
第一道:自动唤醒,免打扰
  任务跑到 70%、80%、90% 超时
  给执行方发一次「你还在吗」,让它自己汇报进展

第二道:自动告警,要人看
  超时仍未结案
  升级告警,记录告警次数与原因

第三道:自动重投,防丢件
  消息已发未送达,或回执一直未签收
  按上限重投,最多两次

人工干预:人直接推
  上面三道都用尽,任务仍然挂着
  人手动催办或催签收

三道自动机制都有上限,这是设计上的必然选择。

  • 唤醒每档只发一次,不封顶就是无限骚扰。
  • 告警按次数升级到顶,不封顶会淹没有效告警。
  • 重投最多两次,不封顶会制造重复执行,同一件事干三遍。

上限封死之后,出现了一个真实的问题。 一条任务,三道自动机制全部用尽,它仍然是运行中。 界面上看它还在跑,实际上已经没有任何机制会再推动它。

它会一直挂着,直到有人发现。 人工干预只做两个动作,另有一条明确禁止。

第一,催办:推执行方继续推进,或者判定无法完成,直接结案。

第二,催签收:提醒发起方,对方交作业了,你还没看。

一条禁止:不新建执行、不改状态、不改回执标记。

这条禁止是重点。卡住的任务如果再派一个新任务去解决,新任务同样会超时。 结果是用一个坑填另一个坑,问题原地放大一倍。

方向也必须严格区分:催办发给执行方,催签收发给发起方。 这两个方向搞反,就会出现催一个已经交了作业的人继续做作业。 他会莫名其妙地重做一遍,而真正该读结论的人仍然没读。

下面这个小函数把超时策略写成了可测试的规则,环境是 Python 3.9 及以上,list[int] 的写法即可。

python
# watchdog_policy.py
def wake_points(timeout_seconds: int) -> list[int]:
    return [int(timeout_seconds * ratio) for ratio in (0.7, 0.8, 0.9)]


def next_action(
    elapsed: int,
    timeout_seconds: int,
    fired: set[int],
    alerts: int,
    max_alerts: int = 3,
) -> str:
    for point in wake_points(timeout_seconds):
        if elapsed >= point and point not in fired:
            return f"wake:{point}"
    if elapsed >= timeout_seconds and alerts < max_alerts:
        return "alert"
    return "wait"


if __name__ == "__main__":
    timeout = 3600
    fired: set[int] = set()

    assert next_action(2520, timeout, fired, 0) == "wake:2520"
    fired.add(2520)
    assert next_action(2520, timeout, fired, 0) == "wait"
    fired.update({2880, 3240})
    assert next_action(3600, timeout, fired, 0) == "alert"
    assert next_action(3600, timeout, fired, 3) == "wait"
    print("超时策略符合预期")

策略只表达规则,不负责发消息。 真正的看门狗还要处理时区、持久化和重复投递。 但规则本身必须先能单独测试,否则线上出问题时,没人知道是规则错了还是实现错了。

这个功能的全部意义,可以压成一句话。 给系统的自动化补一个手动挡。 自动化能覆盖绝大多数情况,剩下的需要人拍一下。 有手动挡不是退步,假装 100% 自动才是。 读者如果自己搭一套,建议先保留这个手动挡。

7.4.5 审计边界:这套系统能回答什么,答不了什么 ​

任务跑完会留下记录,最后看它留下了什么证据。 6.5.5.2 讲审计四问时强调,企业级系统必须全过程可追溯。 我们这个项目做到了相当程度。 但边界必须说清楚。 读者如果听到一个系统宣称自己什么都能查,那它多半什么都没查。

能明确回答的问题,有九类。

  • 这件事是谁派的、派给谁:看 send_agent_id 与 agent_id。
  • 什么时候派的、什么时候结束:看 dispatched_at 与 finished_at。
  • 什么时候真正开始:看 started_at。它是懒写:领取消息时只改状态,真正进入本轮 run、读到指令时才写;从未被领取则为空。
  • 一共跑了多久:起止时间相减。started_at 为空(从未被领取)时算不出,只能看派发与结束。
  • 花了多少 Token:看 input_tokens、output_tokens、total_tokens、context_tokens 四个计数字段;tokens_consumed 目前是空列,不要拿它当口径。
  • 结论是什么:看 summary 与 result_data。
  • 结论被读了吗:看 reply_read、reply_read_at 与 ack_state。
  • 中途被催过几次、什么时候催的:看事件流,可按任务检索。
  • 一条任务挂在哪条链、哪个计划下:看 prev_task、next_task、plan_id。

不能回答的,也必须说清楚。

第一,这个结论对不对。 系统能记录结论,不能判断结论,判断永远在人这里,模型和调度器都不该替人下这个判断。

第二,某些配置改动的完整审计。 这是已知缺陷,改配置、改模型、改权限这几类管理操作没有落到持久审计日志里。 系统能告诉你现在是什么,说不清谁在什么时候改成了这样。

第三,模型内部的推理过程。 系统知道输入了什么、输出了什么,中间怎么想的,不可见,也不可复现。 同一个输入再跑一次,可能得到不同结果,原因无法从日志里还原。

第四,这个任务为什么慢。 系统能告诉你是哪个环节耗时,不能告诉你是模型慢、网络慢,还是它在反复犹豫。 归因需要更细的埋点,当前系统没有做到。

这份边界清单本身就是价值。 工程上最危险的不是能力不足,而是以为它什么都知道。

到这里,第 6 章讲的任务规划与执行流,已经在这套系统上落地;前面 7.1–7.3 讲的是这套系统的形态与设计。 下一节把镜头倒过来。 假设从零搭一支写书的 Agent 团队,这套设计该怎么落地。

7.5 案例推演:如果从零搭一支写书的 Agent 团队 ​

前四节讲的是已经跑起来的系统。这一节把镜头倒过来:假设现在什么都没有,任务是从零搭一支写书的 Agent 团队,要回答的是怎么搭。

之所以用推演而不是实录,理由很实际。真实项目的过程里混着试验、返工和临时验证,把它当成标准范本展示,既不严谨也没必要。推演不一样,每一步都必须自洽。哪一处设计得不合理,下一环就会暴露出来。

假设是这样的。

7.5.1 先把假设摆明 ​

目标:写一本有独立观点的技术书,不是资料汇编。规模按 8 章、每章 8 小节、每节 4000 字估,全稿约 26 万字。观点归作者,流水线只负责不把它磨掉。

作者:一个人。有判断力,有素材,有明确的读者画像。画像再具体一点:能读懂 Python,做过至少一个 Agent Demo,但没搭过生产系统。这个画像是后面所有取舍的前提。

约束:不追求一键成书,只追求把作者从重复往返里解放出来。

成功标准有四条:全篇术语一致,风格前后统一,结论有人验,改动能收敛。

把作者的时间算一遍,就知道这个约束从哪来。64 个小节,如果每节平均需要 3 次来回沟通,全稿就是 192 次。每次连读带改按 20 分钟算,仅沟通一项就是 64 小时(192 次 × 20 分钟),还没算写作本身。

作者只有一个人。增加人手就要把标准、体例和上下文重新讲一遍,协调成本会吃掉省下的时间的一大块。这个量级也决定了拆法:不能靠增加人手,只能把可重复的判断交给固定的角色。

这四条不是并列关系。我们的排序是:术语和风格是底线,结论有人验是门槛,收敛决定这套东西能不能长期用下去。最后一条最容易被忽略,却正是整套设计的前提:

能收敛,比能生成重要得多。

生成一版内容,今天的模型毫不费力,麻烦的是第二版、第三版,每改一次都可能引入新的不一致。一个不能收敛的流水线,跑得越快,烂得越快。

收敛可以定成可测的口径。同一小节连续两轮修订,按 diff 行粗算。本轮新增的行里,如果有超过三成是在回改上一轮已经改过的行,就说明流程在打转。三成是我们的经验阈值,不是统计结论。碰到这种情况,先停改,回头查标准,而不是继续改文字。

7.5.2 为什么是四条线 ​

第一个念头一定是一个 Agent 从目录写到定稿。这个念头通常撑不到第三章。不是因为它写得不好,而是因为它记不住自己第一章定过什么。

上下文窗口有限,跨会话默认又不会自动继承记忆。要可靠,得像 7.3.4 那样显式搭三层记忆,而那是另做的工程,不是一个 Agent 自带的。写到第七章时,第一章定下的称呼、体例、论证口径,早就模糊了。

所以必须拆。但拆的依据不是工作量大小,而是每种职能拒绝什么。“干什么”写在职责里,“拒绝什么”才真正划出边界。

生产线职责坚决拒绝
策划起草读者画像与写作标准、拆章节、做独立评议、收口章节合并读者是谁没定下来之前动笔;用“差不多就行”验收
写手按标准把素材改写成小节,交付正文与素材清单;按意见做针对性修订;在最后完成润色没有写作标准时动笔;推翻重来式的修订
审校查术语、风格、准确性、引用;维护术语表;归并多源意见只看对错不看可读性;把原始意见直接转给写手

第四条线是读者,不在生产线上:由真人承担,不占 Agent 编制,是流程的外部验收角色。

容易混淆的地方:三条生产线是职能,不是三个 Agent。一个 Agent 可以兼两个职能,前提是换职能时换掉验收标准。最小配置是 3 个 Agent:策划、写手、审校。

兼岗的分法是:策划兼章节收口,写手兼润色,审校独立。这里要把两个“终”分开:章节收口由策划做,全书终审归作者;标准也是策划起草、作者拍板。读者必须独立于写手,最好由真人承担,这条和审校独立一样不能省。

四条线各有理由。少一条,就有一个维度没人负责:

  • 没有策划,就没有标准。每条生产线按自己的理解写,全篇散架。
  • 没有写手,策划就得自己动手写。标准从此没人守。
  • 没有审校,术语和引用无人统一,越写越乱。
  • 没有真人读者,全篇正确,但没人想读。

多一条,协调成本就开始吞掉收益。每加一个 Agent 角色,就多一组“谁听谁、谁验谁”的关系要维护。

一句话记住这套分工:策划定标准、写手出货、审校挑错、读者验货。

这也是读者必须独立于写手、最好由真人承担的原因。写手(模型)评自己的产出,会自带宽容,也会下意识地用写的时候那套理由替自己辩护。让同一个模型既写又评,评出来的往往不是阅读体验,而是创作意图的复述。模型能挑出错字和逻辑跳跃,却常常放过“读起来累”;真人读到第三段就会说“这段我跳过了”。

7.5.3 一章怎么走:九个环节 ​

把三条生产线和真人读者接起来,一章的完整旅程是这样:

⑦、⑧ 之后如果没收敛,要回到 ③ 重走一轮,最多三轮;连续两轮的回改都超过 7.5.1 的三成口径,就停改、查标准。

这条链上的中间产物要尽可能结构化。策划交出来的不是一句“写第三章”,而是一份可以直接执行的标准:本章字数区间、要回答的几个问题、小节清单、每节可用的素材指针。

我们要求写手交出来的不只是正文,还要附一份用到的素材清单,方便审校核对引用。中间产物越结构化,后面的环节越不需要猜。

这条链上有四个设计点,值得逐个说清。

设计点一:扇出与扇入 ​

②之后扇出到 ③④⑤,⑥是扇入。审校、试读、核查三路互不依赖,可以同时跑。但反馈归并必须等三路都完成。否则归并的依据不全,等于拿半份材料做决策。这就是 7.4.3 讲的扇入汇聚。依赖关系不是画着好看的,它决定哪一步能并行、哪一步必须等。

归并这个动作看着不起眼,却是审校和写手之间的减压阀。审校负责指出哪里不对,写手需要知道先改哪里。两者之间如果没有一份统一清单,意见就会以原始形态直接压到写手头上。

举个具体的例子:读者说第三节读起来累,策划说第三节论证跳步,两条意见指向同一段,改法却不同。归并环节要做的是判断它们是不是同一个问题的两种说法,再决定先改哪一个。

设计点二:修订不是重写 ​

⑦是修订,不是重写。审校和读者的意见,经⑥归并,再由策划定出优先级,成一份清单。写手按清单改,不改清单外的东西。

这条约束看起来是在限制它,实际上是在保护它。如果允许推翻重来,审校提的意见就白提了。它会用另一种方式犯同一个错:上一轮指出的术语不一致没改,重写时又换了个新叫法。

设计点三:润色是工序不是岗位 ​

⑧润色不是独立岗位,而是写手这条线上的最后一道工序。润色必须单列,因为“说得对”和“读着顺”是两种能力,方向甚至冲突。为了准确,文字会变密、变硬、信息过载。为了顺,文字会变松、变软。但润色有一条硬边界:只改语气、句长和连接,不动事实性限定。把“在多数情况下”删成“一定”,就是越界。

混在一个环节里,模型会在两者之间反复妥协,结果是两头都不讨好。分开之后,前一个环节专心把话说准,后一个环节专心把它说顺。

设计点四:合并不是拼接 ​

⑨合并由策划收口,不是简单拼接。它要检查相邻小节的标题层级、术语和过渡句,还要确认合并后的目录与正文编号一致。小节编号与合并后的目录不一致,会导致交叉引用全部指错位置。

四个设计点合起来,构成了前面说的收敛:每一步都在原有基础上小幅修正,而不是重新掷一次骰子。

把这套依赖关系写成代码,不到三十行。这段代码不调用模型,只演示调度形状。

python
# Python 3.10+,只依赖标准库
import time
from concurrent.futures import ThreadPoolExecutor


def stage(name: str, seconds: float) -> str:
    time.sleep(seconds)
    return name


def main() -> None:
    started = time.perf_counter()

    stage("① 策划定本章标准", 0.2)

    # ② 各小节互不依赖,可以扇出
    with ThreadPoolExecutor(max_workers=3) as pool:
        drafts = [pool.submit(stage, f"② 写第 {i} 节", 0.6) for i in range(1, 4)]
        for draft in drafts:
            print(draft.result())

    # ③、④、⑤ 互不依赖,三路并行;⑥ 必须等三路都完成
    with ThreadPoolExecutor(max_workers=3) as pool:
        review = pool.submit(stage, "③ 审校术语、风格、准确性、引用", 0.3)
        reader = pool.submit(stage, "④ 真人读者试读", 0.5)
        judge = pool.submit(stage, "⑤ 独立评议(核查)", 0.5)
        print(review.result())
        print(reader.result())
        print(judge.result())

    stage("⑥ 归并意见,策划定优先级", 0.2)
    stage("⑦ 写手按清单修订", 0.3)
    stage("⑧ 写手润色去 AI 味", 0.3)
    stage("⑨ 策划合并为整章", 0.1)

    print(f"总耗时 {time.perf_counter() - started:.2f} 秒")


if __name__ == "__main__":
    main()

把 stage() 换成真实的派发与回收,九环节与分工不变,具体做法可换。本书这套系统用的不是线程池,而是任务队列加状态机,等待点和依赖关系完全一致。并行的关键不在线程数,而在依赖关系:先明确哪些步骤之间没有依赖。

7.5.4 三个必然出现的难题,以及为什么只能缓解 ​

推演到这里,一定会撞上三堵墙。它们不是实现不力,而是由问题的性质决定的:术语、风格和语感都没有唯一的正确答案。

难题一:术语漂移。

一章之内统一容易,全书统一极难,人多会漂,Agent 多了漂得更快。因为记忆默认不跨会话继承,它每次都是从零开始,没有“上次已经统一成这个词了”这层账。

缓解手段很直接。把术语表做成独立资产,由审校负责维护,每一轮都对照检查。已登记的术语可以写成脚本逐处查,没登记的同义替换,脚本查不出来。

但这只是缓解,不是解决,因为术语表本身也会过时。新概念出现了,没人告诉你该加进去。同一个概念换了叫法,术语表不会自动察觉。所以必须留一个人为闸门:术语的增删改,必须有人拍板。

维护方式可以做得更细。新词先进入待定区,不直接写进正文,等作者确认后再转入正式术语表。这样每次新增和修改都留有痕迹,不会某天突然发现全书换了叫法。

难题二:风格漂移。

同一句话,不同环节写出来味道不一样。写手偏理性,审校偏挑错,润色阶段又偏文艺,三段拼在一起,读者能感觉到接缝。比如一段判断刚说完,审校习惯在后面补一句保留条件,润色又嫌它啰嗦,把限定当冗余删掉。这已经越过润色的边界。下一轮审校再把条件加回来。

缓解手段是写作标准模板。字数区间、例子密度、称呼统一、禁用句式。再叠一层读者试读,让“读起来顺不顺”有人负责。

但模板只能约束形状,约束不了语气,语气的最终判断只有真人读者能做。

难题三:AI 味。

这是三堵墙里最难的一堵。

一段文字,事实完全准确,术语完全统一,结构完全完整,读起来还是让人想跳过。这种失败最隐蔽,因为它所有可量化的指标都是满分。

它的规则无法穷尽。所有能被写下来的规则,比如少用“首先其次最后”、别堆排比、少用总结句,早就被写进模板了。剩下那部分,是一种说不清来源的语感。

更麻烦的是,按我们的经验,AI 味和规范常常同源。为了统一风格而加的规则,执行到极致就会变成整齐的套话。规则越细,文字越像按模板填出来的,每一句都正确,每一句都不像人在说话。

缓解手段只有一个:在写手这条线上单开一道润色工序,反复试,反复自我否定。

这一环天生就慢,而且是全流水线最慢的一环。原因很简单:

写手的润色阶段,是主链上没有量化验收标准的工序:合并查编号一致,审校查术语命中,都有可核的口径;润色只有“读着顺不顺”。

有标准的事,跑一遍就知道过不过。没标准的事,只能一遍遍改到自己觉得可以了为止。所以它不靠流程收敛,而靠外部检查收口:人工抽检查硬伤,真人读者管读感,两道都过才算完。

三个难题,其实指向同一句话。

那句结论中间还有一层。规则能描述的,模型执行;描述不了的,模型反复试,由人定标准、做全书终审。

能被规则描述的,可以被自动化;不能被规则描述的,只能由人来兜底。

所以读者这条线不能省。它不产出正文,只产出反馈,恰恰是唯一站在目标读者位置上的防线。它不是加工环节,而是验收环节。

7.5.5 这套推演的边界 ​

最后必须交代清楚这套东西不解决什么,以及它要求你付出什么,否则它会变成另一种“一看就会、一用就废”。

第一,它缓解不一致,不解决价值。

九个环节能维持术语统一、约束风格连贯,也能让结论有真人核验。前两项只是缓解,不是解决:流程能保证可查、可回退,不能保证达标。它保证不了这本书值得读。有没有观点、观点对不对、值不值得花别人的时间,全在流水线之外。按 7.5.1 的分工,观点归作者;流水线的职责只是不把观点磨掉。

第二,输入错了,流水线只会更快地错。

读者画像定偏了,后面各环节会非常高效地把一个错误方向执行到底。流水线不会质疑你,它只会放大你。

第三,人必须留在两个位置,而且不能挪。

一个是定标准,读者是谁、写好是什么样。一个是做全书终审,这一版能不能过。我们把这两处叫作流程的两个锚点:标准定得偏,后面全偏;全书终审松一次,整条链的可信度就降一级。

这两处一旦交出去,整套流程就从“放大你的判断”变成“替代你的判断”。而后者,恰恰是它做不到也不想做的事。

第四,它便宜不了。九个环节意味着同一段文字至少被完整读三遍。按我们的口径估算,模型侧把全文完整读一遍算一轮。再加上写作、修订、润色的输出,Token 成本大约是一遍成稿的三到五倍。

真人阅读单列,不耗 Token。这只是经验估计,我们没有逐本记过账。如果一本书的收益撑不起这个成本,缩减环节通常比优化提示词(Prompt)更有效。

这套推演不是纸上架构。本书自己的写作流水线就是按这个形状搭的;支撑它的那套引擎,是从六个月的 842 次提交里长出来的(origin/master,截至 2026-11-01)。下一节讲引擎。推演给的是骨架,实现给的是代价:哪些地方看起来能省,实际省不了;哪些地方看起来复杂,反而是最省事的选择。

7.6 如何实现:这套系统是怎么被搭出来的 ​

前五节讲的是形态与推演,这一节换成实现视角,讲这套系统怎么一层层长出来,以及为什么它不是设计出来的。设计图看着总是干净,实现过程从来是脏的,只看图会以为照着画就能搭,走过一遍才知道卡在哪。这一节给的是代价,7.5 结尾说的那件事,在这里落地。

7.6.1 六个月三段:842 次提交的背后 ​

先给硬数据,口径放在后面说。

项数值
起点2026-04-30(首次提交)
终点2026-11-01(第 842 次提交 8ad5ad3,11:05)
跨度约 6 个月
提交总数842 次(含 1 次合并提交)
Python 代码58,909 行
TypeScript 代码31,804 行(207 个文件)
合计90,713 行

我们把六个月大致分三段。每段目标完全不同,第一段约一个月,只求闭环,任务能派出去就算成功。

text
第一段(约 1 个月):跑通骨架
  目标:让一条任务从「派出去」到「结案」完整走一遍
  产出:任务模板(Task Base)、执行记录、队列投递、最朴素的结案
  特点:一切都是硬编码,状态也只有两三个,能用就行

第二段(约 3 个月):补治理
  目标:让它能连续跑几十天不散架
  产出:状态机完善、回执与签收、看门狗、计划编排、权限分级
  特点:几乎每一个功能都对应一次真实事故

第三段(约 2 个月):补人机接口
  目标:让人不用敲命令也能管住它
  产出:后端接口、控制台、快捷指令、技能库
  特点:这一段的全部动机,是「人受不了了」,不是「技术不到位」

三段的顺序有一处反直觉:界面放在最后,很多项目先做界面,因为界面能演示。

这个项目反着来,界面展示的是状态,状态机改一次,界面就要跟着改,返工成本比忍两个月高。

治理逻辑稳定之前做的界面,基本都要重做。宁可先忍两个月命令行,也不要返工三次。

平均每天约 490 行代码,这个密度不算惊人,资深工程师单干时也常在这一档,差别在构成。九万多行里,至少有三分之一不是人手直接写的(估算),代码量只说明规模,说明不了来源。

本书数据取自 2026-11-01 的仓库快照(提交 8ad5ad3),只统计 Git 跟踪的源文件。行数用 wc -l 口径,包含 test/ 与 docs/ 里的 .py。

复核时用下面三条命令,环境需要 Git,命令在仓库根目录执行。口径不同,数字就会差,先问怎么数的,再看大小。脱离口径的代码量没有意义,它只能证明规模,证明不了质量;规模可以堆,质量堆不出来。

bash
git rev-list --count HEAD
git ls-files '*.py' | xargs wc -l | tail -1
git ls-files '*.ts' '*.tsx' | xargs wc -l | tail -1

三段时间线到这里讲完。接下来换一个切法,不按时间,按职责,看这套代码分成几层。

7.6.2 四层分层:每一层解决的是不同性质的问题 ​

代码不是平铺的。按职责拆开大致是四层,下表只统计主要业务代码,测试与共享库不在其中。

先说清它与 7.3 的关系:八个支柱是设计维度,四层是代码落点,一根支柱通常横跨两层。框架与协议落在内核层,人类专家接口落在服务层与界面层,组织映射与能力提取落在内核层。下面按层讲代码,支柱落地后的形态仍看 7.3。

层代码量解决什么
④ 界面层31,804 行 TypeScript(207 个文件)人怎么看见、怎么判断、怎么干预
③ 服务层7,296 行 Python(后端接口)界面要的数据怎么安全地取出来
② 脚本层10,821 行 Python(看护 / 部署 / 打包 / 校验)系统怎么自己看着自己、怎么可靠地落到主机上
① 内核层19,837 行 Python(98 个工具定义)状态怎么定义、怎么流转、怎么留痕

四层的划分依据不是技术栈,而是改动的性质:内核层是状态机与数据模型,动一次影响全局;界面层跟着人的使用习惯走,改动频繁但影响面窄。

哪层改得多、哪层改得少,这里给的是经验判断,不是精确统计。提交数会被重构、文档与测试带偏,拿它逐层比较并不严谨。各层行数 7.3.1 给过量级,这里给准确数,只关心变更频率的读者可以跳过数字。

这个分层最大的收益是改界面不动内核。界面代码占了全部代码的三成五(31,804 / 90,713),耦合一深,改动成本就指数上涨。如果它和内核搅在一起,改一次布局就要动一次数据模型。那样的项目撑不过三个月。

这不是夸张,是耦合的必然结果。分层也有代价,四层之间的契约必须稳定,契约一破返工就来。

四层合计约 7 万行,其余约 2.1 万行是测试与共享库(test 7,430 / docs 6,203 / skills 1,834 / tools 1,789 / common 604,余为根目录脚本;内核层含工具实现与调度,tools 只计工具定义目录)。

写操作与状态变更只走内核工具;读侧报表为性能保留了只读直连,代价是改表结构要同步改服务层。服务层的接口,又是界面层取数的唯一入口。

任何一层绕过上一层直接改库,都会在下次改结构时炸掉。

关于这个数字,先统一口径:内核 MCP 服务器一共 98 个工具,全部注册,按权限可用。其中 92 个来自 @mcp.tool() 装饰器,6 个在运行时动态注册(5 个研究成果发布只读工具,加 1 个探活工具)。

建组、加成员、移出成员这三个函数只供内部调用,不计入。此外还有 MySQL、Redis 两个 MCP 服务器,分别提供 5 个和 7 个工具(合计 12 个),不算在这 98 个里。

数字本身还要说一句克制的话:工具数量不是指标,它只是需求的沉淀。98 个工具是六个月里一件件长出来的,每一个都对应一个具体需求,查任务、改字段、催办、签收。

如果有人把做出 100 个工具当成目标,他一定会造出一堆没人用的工具。指标错了,动作就会变形。这是内核层六个月长出来的结果,不是起点。

分层讲的是同一份代码怎么组织。下一节换到主机上,看这份代码怎么在三台主机上同时成立。

7.6.3 跨主机实现:同一份代码怎么在三种环境里成立 ​

这是实现期最脏的一部分。系统当前跑在三台主机上,分属两类平台,真正要处理的差异有三类,比想象中大。

主机平台承载 Agent 数(注册 / 活跃)
robert_macDarwin arm6476 / 70
gm118Linux x86_642 / 1
sgaiedge17Linux x86_6412 / 12

表内为截至 2026-11-04 的项目库数字:注册数含模板与已停用,活跃数只计 active_status=1。

同一条代码,要在三台主机上成立。三类差异都藏在路径与依赖里。

第一类是解释器路径,macOS 主机上有自己的虚拟环境,Linux 主机上未必有,启动脚本不能写死解释器路径。

必须按主机解析出可用路径。写错的症状很隐蔽,任务派出去了,对面报找不到命令。状态会一直停在已派发,看日志才知道根本没启动,这种错最容易误判成网络问题。

第二类是依赖状态。加一个字段不是推一次代码就完事,数据库的 DDL(数据定义语言)必须每台主机各自执行。

注意:只同步代码而不同步 DDL,另一台主机会报字段不存在,任务在派发阶段就失败。

第三类是文件系统布局,两类安装布局的路径结构不一样,部署脚本不能假设固定路径。

必须做探测。针对这三类差异,实现上定了三条硬纪律。

第一条,改完必须双端比对校验和。代码在仓库里一份,在安装目录里另一份,不一致,跑的就是旧代码。

比对对象是仓库 HEAD 与安装树。不是你本地的工作区,工作区可能有未提交改动,拿它比会得出错误结论。

bash
# 示例路径,按实际安装位置替换
# macOS 用 shasum -a 256,Linux 用 sha256sum
git -C /srv/agentos show HEAD:config_loader.py | sha256sum
sha256sum /opt/agentos/config_loader.py

# 写入后做语法检查
python3 -m py_compile /opt/agentos/config_loader.py

示例用的是 sha256,实现里用的是 md5。算法不限,双端一致即可。

第二条,改完必须做语法编译检查。这条看着基础,拦的是文件写进去后已经损坏的情况。

跨主机场景下,一个坏文件影响整台主机。影响面按主机算,不按文件算,这是最容易低估的地方。

第三条,部署脚本必须能识别主机,不能假设环境固定。

我们最后没做成一份脚本,改成三台主机各一份 sync_deploy.sh,差异只有 5 行,内容是解释器路径、安装根和端口这三类,而且不入库。

没做成参数化,是因为三台主机的布局还在变,过早抽象会把未定的东西固化进脚本;代价是三份脚本各漂各的。三份脚本就是三份会漂移的真相。这是一处我们没守住的纪律,也是一处省不掉的代价。

这三条没有一条是最佳实践。全部是被事故逼出来的,事故记不住,纪律才记得住。

跨主机最阴险的地方是延迟暴露。它不会当场报错,而是过一段时间才以不相干的症状出现。

某台主机少了一列,一个多月后才因为统计报表报错被发现,到那时没人记得是哪次部署漏了。

跨主机讲完,这套系统已经能在几台主机上跑。最后一步,是让它开始用自己:拿自己当第一个用户,做最后一个功能。

7.6.4 用它自己开发自己:最后那个功能是怎么做出来的 ​

讲一个具体例子,把实现这件事说透。这是用它自己开发自己,也就是自举。最后落地的功能,是 7.4.4 讲的人工干预,也就是催办与催签收。

它的实现过程,完整走了一遍这套系统自己的分工流程。先看分工,再看边界,最后看一个坑。

text
①  人做判断
    判断:看门狗三道机制都有上限,用完之后任务会静默挂住
    判断:解决方式不是「再加一道自动机制」,而是「补一个手动挡」,也不是再派一个任务
    判断:催办方向必须区分,催执行方还是催签收方
    判断:人工干预只做催办;建任务、改状态、终止都不在范围内
    ↑ 这一段全部由人完成,Agent 不参与

②  Agent 做实现(拆成两条线并行)
    线 A:内核方法,新增一个 MCP 工具,按状态自动选方向
    线 B:后端接口加前端按钮,让它在控制台上可点

③  联调与复核
    真实 HTTP 链路打一遍:成功的返回、限流的 429、权限的 403
    副作用核对:有没有多建执行记录、状态有没有被改
    ↑ 这一段由人复核,不轻信 Agent 的自述

分工的边界可以压成一句话。做什么、为什么、能不能做归人;怎么做、做掉它、留痕归 Agent。

这次实现里,判断层面有四件事是人定的,据我们记录,Agent 没有参与,这四件事都指向一个问题:边界画在哪。这四件事 7.4.4 已经论证过,这里只对齐,不展开。

为什么要这个功能:三道机制都有上限,用完任务会静默挂住。为什么不能靠再派一个任务解决:那会制造第二个同样超时的任务,问题会复制,不会消失。

为什么方向必须严格区分:催办给执行方,催签收给发起方,方向错了催办就变成打扰。为什么只催不终止:终止是另一件事,破坏半径大得多,催是提醒,终止是夺权。

实现层面,两条线的接法是这样的。接口在开工前就定死,然后并行推进。

线 A 的契约是:工具只收执行实例 ID(task_run_uuid),方向默认由当前状态推导(auto),也可以显式指定 urge(催执行方)或 ack_remind(催签收),但方向仍以状态校验为前提。

线 B 不碰判断,只做透传和后端校验。前端只负责按钮与提示,读到的状态全部来自内核,自己不存一份。

联调的顺序是从内往外。内核方法先单独跑通,再用真实 HTTP 链路把成功、429、403 三种返回各打一遍,最后才接前端按钮。这样出问题能定位在哪一段,而不是一口锅里搅。两条线并行时没有互相等,真正卡住的不是接口,是最后一步的验收。

联调时还发现了一个假绿灯。验收脚本里有一条检查,要求这次操作不产生多余事件。写法是打印一个对勾,然后不管实际值。跑出来事件数从 0 变成 2,脚本照样打勾。

假绿灯比红灯危险,因为它让人放心。这个坑说明一件事:Agent 写的测试,人必须复核断言。它会忠实实现你描述的检查,包括你描述错的那部分,这一点比代码错误更难发现。

这件事至少说明一件事:AI 能写代码,这早就是共识。

真正值得说的是,在契约明确的系统里,判断与执行可以被干净切开。切开之后,整体效率显著高于不切开的做法;不过这只是我们这一个案例的经验判断(n=1),没有留下可比的耗时与返工记录,不能当作统计结论。

回头看,这套系统的复杂度不是设计出来的,是被事故推出来的。四层、跨主机、自举,看着是三件事,背后是同一个判断:边界画清楚,剩下的交给执行。

7.5 结尾说,实现给的是代价。代价可以归成两组。看起来能省,实际省不了的三处:跨主机的三条纪律、四层的契约、人工干预这个手动挡。看起来复杂,反而最省事的三处:先内核后界面、四层分开、用它自己开发自己。

下一节给一份复制清单。如果你要自己搭一套,可以从那里开始,清单不长,哪些必须落、哪些可以换,里面都标了。

7.7 复制清单:如果你想自己搭一套 ​

看完前面六节,最容易冒出来的念头是:我也要搭一个一模一样的。这个念头得先按住,因为它的方向从起点就错了。

照抄这套系统的形态,是性价比最低的一条路。它今天的样子,是六个月里被事故一点点砸出来的。

你没有经历那些事故,抄过来的就是一堆用不上的复杂度。这一点必须先说清楚,否则后面讲的每一条都会被误解。

所以这一节只讲三件事,不讲它到底有多少功能。下限在哪,动手前该想清楚什么,以及哪些部分不要抄,这三件事才是能带走的。本节提到的次数与时长多是经验值,不是统计结论。

7.7.1 最小可用配置:一个人能跑起来的下限 ​

一个人要跑起来,真正需要的东西比你想象的少。四张表、一个队列、一个看门狗、一个入口,就够开工了,剩下的都能后补。

下面七条,前四条就是那四张表。

  • Agent 名册(agent):一张表,记 id、角色、项目、状态四项就够用。没有它,你不知道该把活派给谁,也统计不出谁在忙,更排不出优先级。

  • 任务模板(task):一张表,存模板正文和归属 Agent。没有模板,每次只能发自由文本,结果每次都不一样,出了问题也没法复盘。

  • 执行记录(execution):一张表,记执行编号(run_id)、指令、状态、结论、回执五个状态字段,另加 send_agent 记归属(第六列;表共十列,其余是定位与时间戳)。这是整个系统的核心,别的都能省,它不能省,省了就没有真相。 reply_read 这一列是回执轴的最小实现,只保留“读没读”一位,不保留发出、送达、已读三态。没有它,“已发送”就会被当成“已读过”,回执轴等于没接上。少了 send_agent,“谁派的”就答不出来。

  • 事件流(event):一张表,记谁(actor)在什么时候(created_at)催过、告警过、签收过。没有它,事后无法回答这件事到底卡在哪一步。

  • 队列:Redis 一个 list 就够了。你只需要先进先出,不需要引入消息中间件,也不需要为它额外做运维,出问题也好查。

  • 看门狗(定时脚本):扫超时任务并发提醒。没有它,长任务会静默挂住,没人知道它到底还在不在跑,也没人敢继续等。

  • 入口:一个命令行,或者一个单页。开始时只需要两个动作,派活和看结果,别的功能都可以先不做,先用两周再说。入口可以用 SQL 查询顶。

这七样东西里,真正不能省的只有两样,执行记录和事件流。其余五样都能先用最土的办法顶一阵,不影响开工。这两样一旦省掉,你会在几周后遇到一件很具体、也很难受的事。你明明记得自己派过活,却完全想不起来结果是什么。这不是记性问题,是系统没有留下任何可查的证据。

这套最小配置里没有的东西,同样值得列清楚。它们不是不重要,是现在还不该有,加了只会拖慢你的第一步。

  • 没有多项目。一个项目够用,多项目会先把你自己的注意力拆散,最后两个项目都做不完,还都很粗糙。

  • 没有技能库。你自己的笔记就是技能库,先写到一张 Markdown 文件里,够查就够用,不必急着做检索和权限。

权限分级、控制台(八大模块的 Web 界面,起步时只是一个单页)、内容流水线也不该有,但那是另一类判断。它们不是你现在用不上,而是别人长出来的复杂度,抄进来自带债务。三条都放到 7.7.3 一起说,那里的判据不是暂时不用,而是抄了要还。

下面这份配置可以直接跑,不需要框架。环境只需要 Python 3.8 以上(示例在 3.10 下验证),以及一个本地 redis-server 和 redis-cli;执行前先 redis-server --daemonize yes,不然会报 Connection refused。

先建库。四张表的字段刻意压到最少,既够你现在开工,也够你之后往上加,不用一次就把结构设计完。正文只留核心建表语句,约束与完整版见 source/ch07_minimal/schema.sql。

sql
-- schema.sql:四张表,字段压到最少
CREATE TABLE agent (id TEXT PRIMARY KEY, role TEXT, project TEXT, status TEXT);
CREATE TABLE task (id TEXT PRIMARY KEY, agent_id TEXT, body TEXT, created_at TEXT DEFAULT (datetime('now')));
CREATE TABLE execution (run_id TEXT PRIMARY KEY, task_id TEXT, agent_id TEXT,
  send_agent TEXT, instruction TEXT, status TEXT DEFAULT 'running', summary TEXT,
  reply_read INTEGER DEFAULT 0, started_at TEXT, finished_at TEXT);
CREATE TABLE event (id INTEGER PRIMARY KEY AUTOINCREMENT, run_id TEXT, kind TEXT,
  note TEXT, actor TEXT, created_at TEXT DEFAULT (datetime('now')));

建表只是第一步。要让任务真的跑,还得写执行记录、入队、启动消费端。四步都在当前目录执行,并且需要先把 schema.sql 放在这里。

bash
python3 -c "import sqlite3; con=sqlite3.connect('queue.db'); con.executescript(open('schema.sql').read()); con.commit()"
python3 seed.py
redis-cli LPUSH agent:queue '{"run_id":"run_0001","task_id":"task_write_7_7"}'
python3 worker.py --once

第一条建表;第二条写 agent、task、execution 三行,外加一条人工催办事件;第三条把 run_id 推进队列;第四条启动消费端,取一条消息,按 execution.instruction 执行,再把 summary、finished_at、started_at 和 reply_read 写回去。四条跑完,四张表都不是空的。

消费端是最容易漏掉的一环。只入队没有消费端,消息就一直躺在 Redis 里,表里除了种子数据什么都不会多。

看门狗负责兜住超时,逻辑要简单到你能背下来。它只做三件事,找超时记录、写告警事件、把状态改成卡住。完整脚本在 source/ch07_minimal/watchdog.py,正文只留核心的三句 SQL。

sql
-- 看门狗每分钟执行这三句
SELECT run_id, agent_id FROM execution
 WHERE status = 'running' AND started_at < datetime('now', '-30 minutes');
INSERT INTO event (run_id, kind, note, actor) VALUES ('run_0001', 'alert', '超过 30 分钟未结案', 'watchdog');
UPDATE execution SET status = 'stuck' WHERE run_id = 'run_0001';

正文写成示例值 run_0001,脚本里由 watchdog.py 绑定上一步查出的 run_id;直接粘进 sqlite3 也能执行,只是只命中这一条。

这里没有重试,也不该自动加。重试是另一个判断,脚本不该替你决定,更不该偷偷扩大事故的破坏半径。这条线要划清。

注意:started_at 一处写本地时间、另一处写 UTC 时,超时判断会整体偏移,偏移量等于时区差,东八区就是 8 小时,看门狗会扫错任务。当前示例两处都写 UTC,不会触发,但换成宿主本地时间就会踩到。

跑起来之后,你就有了一套能回答五个问题的系统。谁派的(send_agent),什么时候结束(finished_at),结论是什么(summary),读过没有(reply_read),中途催过几次(event 里 kind='manual_nudge' 的条数,示例里预先放了一条)。这五个问题,7.8 会再问一遍,答得出来,下限就在,答不出来,记录就只是存下来了。

7.7.2 动手前必须想清楚的三件事 ​

配置可以照抄,判断不能。动手之前有三件事必须先有答案,答不上来就先别自动化,抄了也不会有用。

第一件:谁来判断对错。

如果答案是没人能判断,那就不该自动化,再省人力也不该开这个口子。

能验收,是自动化的前提条件,不是自动化的结果。这个顺序一旦反了,后面每一步都会变成返工,而且越返越贵。

第二件:取消是不是正常动作。

先看你的系统敢不敢取消任务。如果一套系统从来不敢取消任务,那只有两种可能,而且都很糟。

要么任务拆得不够细,小到没有取消的价值。要么流程太脆,取消一步整条链就断,最后没人敢按这个按钮。

取消比例没有统一阈值,长期接近零或高得离谱都值得查,按下去不该有心理负担,也不该需要谁批准。

我们这套系统上,全库 7,529 次执行里取消 484 次,占 6.43%;本书项目 1,506 次里取消 14 次,占 0.93%(2026-11-04 现算,全表、含测试数据,来源 ao_task_execution)。这个比例只能证明取消动作存在,证明不了它健康;可核对的部分全是人工清理、误激活和测试残留,没有一次是取消动作本身出事,所以没人怕按。

第三件:失败和卡住分开了吗。

这是最容易被忽略的一条。这两件事在工程上完全不是一回事,混在一起就没人能做出正确判断。

失败是跑完了,结论错了或者做不到。卡住(stuck)是还在跑,但其实已经没人推它,也没有任何新进展出现。

如果系统只有一个未完成状态,你永远分不清它坏了还是在等。这个区别直接决定你该修还是该催,动作完全不同。

上面那个看护脚本把状态写成 stuck,就是为了保住这个区别。字段多一个,判断就少绕一圈,告警也更准。

我们把这条归进了 7.8 的“状态有人管”。状态一旦合并,告警就会失去方向,人只能凭感觉去猜,最后谁也不信告警。

这三件事想不清楚,你抄来的每一张表都会变成负担。想清楚了也一样:字段名可以换,表可以并,但执行记录与事件流这两张不能省。

7.7.3 不要照抄的部分 ​

最后说不要抄什么。7.7.1 末尾说的是现在还用不上,这一节说的是抄了就变成债务。这两笔账要分开算清楚。抄错东西的代价会一直跟着你,越往后越贵。

  • 98 个 MCP 工具(92 个静态 + 6 个动态注册),全部对外暴露,MySQL 与 Redis 的 12 个另计。这是六个月里一件件长出来的,每一件对应一个真实需求。只抄数量,造出来的都是没人用的工具。

  • 八大模块。起点只需要任务列表和任务详情两屏,即其中两个模块。其余六个模块是需求长出来的,不是设计出来的,多一个都是负担。

  • 跨主机。单机能跑通再谈多机。路径差异、DDL 不同步、校验和比对,会吃掉你前两个月几乎全部精力,还不一定成。

  • 三层记忆。起步阶段一个 Markdown 笔记文件就是全部记忆。分层是信息量涨上来之后才需要的,早了就是空转。

  • 0 到 7 级(共八级)权限。权限收成三档就够,管理员、操作员和只读。八级是为几十个执行者之间不许互相派活这种具体场景准备的。

  • 完整流水线的九个环节。你的场景可能只需要三个。多出来的环节没有对应判断,就只是空转,还增加故障点。

这一节归结起来,抄结构等于抄债务。

这个系统今天的每一处复杂度,背后都对应一次真实事故。复杂不是设计出来的,是事故换来的。

你只抄结构不抄事故,等于把别人付过的账接到自己头上,却拿不到对应的收益。这笔账怎么算都是亏的。

正确的做法是从最小配置起步,让复杂度被真实需求逼出来。需求没到,就先不加那一层,加了也守不住。慢一点没关系。

读者如果只记一句,就记这一句。先让它能跑,再让它像样,这个顺序反了,按我们的经验,会浪费你很长时间。

下一节是本章的最后一节。它会讲这套方法在哪里失效,以及失效的时候,读者该看什么信号去判断,又该怎么退。

7.8 本章小结:方法的边界 ​

写到这里,本章该说的都说了。七节从一个项目的由来(7.1)讲到怎么照着搭一套(7.7)。最后收口,只讲三句真话,外加一张验收清单、一个前提、四条失效信号和一个退路。

先说这个前提。这三句话都默认团队里有一个能判断的人。如果没有这个人,方法很难失效,它会变成一个更高效的空转机器。先找到那个能说“这一版可以”的人,再谈自动化,顺序不能反。

第一句:方法能保证下限,不能抬高上限。

7.4 那套执行流,能把你的 Agent 应用塌掉的概率压到很低。状态有人管,结论有人读,卡住有人催,出错有据可查。这四件事听起来平常,但每一件都对应一条硬机制。

状态有人管,是 7.4 的两条轴:执行轴回答“干完了吗”,回执轴回答“对方读了吗”。结论有人读,靠的是签收,不是“已发送”。卡住有人催,是看门狗三道自动机制之后的人工干预。出错有据可查,是 7.4.5 的审计边界清单:能回答九类,答不了四类。

这些机制保证系统不会静默散架。任务可以失败、超时、被人取消,但不会消失得无声无息。这是下限。

我们检验下限的方式是抽查,不是证明:按我们的经验,随便挑一条三十天前的任务,看你还能不能答出五个问题。谁派的,什么时候结束,结论是什么,读过没有,中途催过几次。答得出来,下限就在;答不出来,说明记录只是存下来了,没有被人用过。

下限本身有价值。我们见过的多数 Agent 演示能生成一版内容,却跑不过三十天。7.6 的六个月、842 次提交、90,713 行代码里,内核加脚本约三成,不是在增加能力,而是在补这些下限。

补下限很枯燥,不产生演示效果,也不增加模型智商。这些机制要写代码、维护、处理边界,不出现在架构图的高光位置,却是长期运行的真正原因。但没有它,系统跑得越久,丢的东西越多。

但下限不是上限。7.5 的推演里,那条流水线能把一章稿子改到收敛,前提是有人先定了读者是谁、标准在哪、什么程度算过。方法负责让想法落地,不负责让想法值得落地。

7.5 有一句更狠的话:一个不能收敛的流水线,跑得越快,烂得越快。读者画像定偏了,后面各环节会非常高效地把一个错误方向执行到底。

所以下限和上限要分开看。下限解决“会不会散架”,上限回答“值不值得做”。把下限当成上限,会得到一套跑得很稳、却没人想读的系统。下限有机制兜底,上限没有机制,只有人的判断。

更麻烦的是,这种系统很难从内部看出来:指标全部正常,任务成功率很高,告警也干净,就是没有人因为它改变了什么。

第二句:流程可以复用,判断不能。

九个环节的编排骨架可以固化成模板,三条生产线加一条外部读者线的边界可以照搬。可照搬的是职能边界,不是复杂度。策划定标准,写手出货,审校挑错,读者验货。这套分工换成另一个题材,照样成立。

但“写给谁看”“这段文字对不对味”“这个方案该不该放弃”,每一件都得人重新来一遍。模板能规定字数区间、例子密度、称呼统一,规定不了语气。

判断不能复用,是因为它依赖具体情境。同样是取消一个任务,7.7 里全库取消率 6.43%,本书项目 0.93%,可核对的部分全是人工清理、误激活与测试残留,真正该不该按的那一下,仍然只能由人当场判断。流程只能提供取消的入口,不能替你决定该不该按:数据只告诉你按了多少次,不告诉你这次该不该按。

7.6.4 那个催办功能的实现,把这条边界写得很清楚。“为什么需要、为什么不能再派一个任务解决、为什么方向必须区分、为什么只催不终止”,这四个判断全部由人定。Agent 负责内核方法、后端接口、前端按钮和测试。

这不是说执行不重要。执行又快又稳,整体效率才显著高于不切分。但前提是判断和执行能被干净地分开。

判断可以被记录,但不能被模板化。一次次判断留下的理由,会变成下一次判断的参考。它变成经验,不会变成规则。规则处理已知,判断面对未知。

判断也可以分层,但只有两层:定标准,做全书终审,而章节收口有标准判据(如 7.7 的验收项),由策划执行,不计入人的判断层。这两层可以由同一个人承担,也可以分开,但任何一层都不能整体交给流程。两层之外只剩兜底:异常发生时人必须到场,但那是救火,不是一层流程。流程能提醒你“该做全书终审了”,不能替你决定“这一版能不能过”。

7.5 里那条读者线,就是专门为这类判断留的位置。它不产出交付物,只产出主观感受。所有指标都满分、读起来却想跳过的稿子,读者最容易抓住。

所以一套自动化系统真正省掉的,从来不是思考,而是思考之后那 1,506 次执行里的重复往返。流程可以标准化,判断不能标准化。

第三句:系统的形态是被事故砸出来的,不是设计出来的。

这是最后一重边界:方法给得了方向,给不了形状。

回头看这一章里那些“为什么是这个形态”的解释。调度层为什么独立于框架,回执为什么分成两条轴,看门狗三道机制之后为什么还要补一个手动挡,跨主机部署为什么必须算双端校验和。没有一条是坐在书房里想出来的,每一条背后都有一次返工。

7.6 那组数据能说明这件事。它分成跑通骨架、补治理、补人机接口三段。每一段的目标不是实现设计,而是解决上一段暴露的问题。界面放在最后,是因为治理逻辑稳定之前做的界面,基本要重做。

这大概是所有工程系统的共同命运。没有一个是按图施工建成的,都是在施工中不断改图。设计图给的是方向,事故给的是形状。

这两件事不对立:没有方向,事故只是补丁;没有事故,方向只是图纸。真正可用的架构,是两者反复校正的结果。

但事故驱动不等于不要图纸。每一处复杂度都该追溯到一次真实的失败或需求。7.7 说抄结构等于抄债务,正是此意:你抄了别人的复杂度,没抄到逼出它的事故。

事故驱动也有代价:复杂度会长出来,却不容易缩回去。这也是复制系统最难的地方。表结构、队列和看护脚本都能复制,事故留下的判断不能。

7.7.1 的最小配置之所以够用,是因为它只留下产生记录和推动闭环的部分,把靠事故长出来的复杂度留在别人那里。

这套方法会在哪里失效

这套方法失效,不会以报错的形式出现。它会安静地空转。看到下面四条信号,就该往回退。

其一,任务都能结案,结论却没人读。执行记录很漂亮,回执长期停在“已认领(发送中或已发出,needs_reply=2)”。

其二,催办次数在涨,返工没有减少。卡住的不是推进,是判断。

其三,新增的环节只增加审批,不增加判断。流程在变长,质量没有变。

其四,清单越抄越长,事故没有变少。复杂度已经和真实问题脱钩。

该做的事也只有三件,不按上面四条一一对应,而按退的深度排三步。退回 7.7.1 的最小配置,先保住执行记录和事件流。把判断收回两个锚点:定标准,做全书终审。停掉那些只剩审批、没有判断的自动机制。

三句话也可以当成一张验收清单。上线一套自动化之前,先过三个自查项:下限在哪里,判断归谁,每一处复杂度对应哪次事故。三个自查项里有一个答不上来,这套系统就还没有到可以放手的程度。

如果这三句话只能记住一句,请记住中间那句:

流程可以标准化,判断不能标准化。

这一条决定的不只是架构,也大致标出了人在 Agent 时代该站在哪个位置。

判断力不是流程的替代品,是流程的入口。本章到此结束。下一章换一个视角,讨论 Agent 和人的关系。那是另一重边界,也是这套方法最终要回答的问题。

文字 CC BY-NC-SA 4.0 | 代码 Apache-2.0