扩展模型 · 如何新增一种能力

技术参考 · 深入原理(架构师向)。承接《组件全图》《运行时与事件流》。这是架构师最该懂的一篇:ClawCreek 的可扩展性是结构性的——新能力可以直接 slot in,不需要重写一个中心。想提"给平台加个 X"的提案,先想清楚 X 属于四层里的哪一层、以及怎么把它接上去。

先分层:X 到底是什么?

提案第一步,是把你想加的东西归到正确的层(放错层,提案就站不住):

你想加的	它是	关键判据
一种器官/能力(有 per-Agent 状态、订阅事件、有自己的世界观)	Module	它需要"记住 per-Agent 的东西"吗?需要在每个事件上表态吗?
一种平台共享服务(实例不持有某个 Agent 的可变状态,被调用)	Infra	它应由全局 InfraRegistry 持有一份吗?
一个动作(LLM 能主动调用去做一件事)	Tool	它是"让 LLM 做 X"的一个动词吗?
一段行为模式 / 知识(不需要新代码)	Skill / Directive / Playbook	它能用配置/提示表达,而不是写代码吗?

最容易混的是 Module vs Infra。通常:Module 实例拥有单个 Agent 的生命周期状态;全局 Infra 实例不把某个 Agent 的可变状态留在自身字段里,而是接收 agent_id,按需读写共享数据库。当前 EventBus 是例外:类型上继承 Infra,但实际每个 AgentLoop 一份。架构提案应明确是在延续这个过渡实现,还是进入全局 InfraRegistry。

自描述:每样东西都带一份 Spec

ClawCreek 的每一层都是自描述的——启动后冻结、全局唯一的一份契约:

Module → ModuleSpec(name / roles / priority / 订阅的事件 / 拥有的 tools / owner_docs …);
Infra → InfraSpec;
Tool → ToolDef(name / description / parameters / handler / risk_level);
Event → 有自己的类型定义。

为什么这对架构师重要: 名称、角色、世界观、事件、工具归属和说明尽量集中在对应 contract 里,供 introspection、Brain UI 和注册表消费。运行时状态仍在 Module/数据库中,具体工具权限主要由 ToolDef 和 handler 的执行检查保证,不能假定一份 ModuleSpec 包办所有边界。

特别地:owner_docs 是必须手工写准确的 Agent 自我说明。平台启动时还不能读取任何 per-Agent ModuleRegistry,所以当前由 core/module_doc_provider.py::_migrated_module_classes() 静态收集这些 class-level 文档,再写入平台知识库。漏掉 provider 注册会让 Module 已经运行、Agent 却搜不到说明;CI 的 drift test 只是兜底。

slot-in:怎么接上去

加 Module:定义 ModuleSpec,在 install_defaults() 注册;若订阅事件,声明 events_subscribe / 必要的 EventTypeSpec,并按 band 并行语义选择 priority。再编写 owner_docs,把 class 加进 module doc provider,让 Agent 的知识检索真正看得到它。
加 Infra:定义 InfraSpec + 在全局 InfraRegistry 注册;通过 agent_id 访问共享存储,不要把某个 Agent 的可变状态留在全局实例字段里。
加 Tool:定义 ToolDef + 由某个 module 在 spec.tools 里"认领" + 注册。工具走联邦式认领 + 自适应加载,LLM 在相关场景自动拿到它。

通常不需要修改 consciousness 或重写事件循环,但仍要更新明确的装配点(默认 Module/Infra 注册表、Tool 注册与 owner-doc provider)。这里的"不改中心"是核心执行器保持稳定,不是"零中心装配改动"。

这份"先难后易"的取舍

把每样东西都做成自描述、分层、可 slot-in,比"一个中心挂一堆工具"复杂。这份复杂是刻意的投资:它换来的是——平台可以持续长出新能力,而不需要谁去重写那个中心。一个任务执行器加到第 20 个能力时会变成意大利面;这套结构加到第 200 个仍然是"再插一个器官"。

这正是《平台架构》说的"是生命而非工具"在工程上的含义:结构本身为成长而设计。

提案 checklist(架构师自查)

提一个"加能力"的架构设计前,先答清楚:

它属于哪一层?(module / infra / tool / skill-directive-playbook)
如果是 Module:priority 多少?同 band 并行是否安全?订阅/发出哪些事件?是否要新增 EventTypeSpec?持什么 per-Agent 状态?拥有哪些 Tool?
它在事件流的哪个位置贡献? 要读哪个更高优先级 band、被谁读?
成本:它会让多少事件唤醒 LLM / 加多厚的 prompt?(见《一次思考的生命周期》)
边界:它碰不碰安全红线(动钱/群聊/权限)?(见《owner 权限与安全边界》)
它的自我描述怎么落地?写好 owner_docs / description,注册 module doc provider,添加防漂移测试,部署后确认知识库同步。

答得清楚,才是一个"有据"的架构提案——拿去《本源》走流程。

这一篇属于「深入原理(架构师向)」。回看全部零件《组件全图》、运行机制《运行时与事件流》、执行链路《一次思考的生命周期》;想把提案落到治理流程,看《本源》。