Electric Agents 模式触发识别：用 7 种协调模式把自然语言需求映射为 Entity 架构

Electric Agents 模式触发识别：用 7 种协调模式把自然语言需求映射为 Entity 架构

【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric

本篇技术指南围绕 pattern-triggers.md 展开，讲解 Electric Agents 的designing-entities技能如何在Phase 2（Clarify）阶段，将开发者对 Agent（Entity）的自然语言描述，通过"触发短语表 + 消歧问答流"精确映射到七种协调模式（single-agent、manager-worker、pipeline、map-reduce、dispatcher、blackboard、reactive-observers）。读完本文，你将掌握触发表的匹配规则、六步消歧问答的优先级顺序、四种典型工作示例的推导过程，以及模式推断结果的标准输出格式，并能结合 manager-worker、map-reduce 等模式参考文件与 agents-playground 的源码实现，直接动手设计出结构正确的 Entity。

一、模式触发器在整个技能工作流中的位置

pattern-triggers.md不是一份孤立的技术文档，它是 designing-entities 技能 五阶段工作流的第二阶段（Clarify）专用参考文件。整个技能的五阶段是：

1. Elicit：向开发者提出一个开放问题，获取 Entity 的描述（"这个 entity 要做什么？与谁交互？什么触发它？"）。
2. Clarify：按需加载references/pattern-triggers.md，将描述与触发表匹配；若模式唯一则跳过问答，否则每次只问一个消歧问题，直到模式明确。
3. Propose pattern and design：明确推断出的模式与理由，加载references/patterns/<name>.md，输出设计大纲（类型名、协调模式、creationSchema、state集合、inboxSchemas、handler 结构等）。
4. Review：加载 review-checklist.md，对照通用检查表与模式专属检查表逐条报告 ✓/✗/N/A，循环直到开发者明确批准。
5. Implement：写出恰好一个Entity 文件（entities/<type-name>.ts），采用registerXxx(registry)工厂模式。

从 SKILL.md 的流程定义可以看出 Phase 2 的核心约束：每条消息只能问一个消歧问题，且"切勿把整份问题清单一次性抛出"（Never ask a canned full list）。这正是pattern-triggers.md存在的意义——它把模糊的自然语言信号快速收敛为少数几个关键的结构性问题。

二、七种协调模式的速览

pattern-triggers.md将模式映射到七种协调模式。在进入触发表之前，先看每个模式在仓库中的"权威定义"入口（均位于references/patterns/目录，由 Phase 3 按需加载）：

注意 blackboard 与 reactive-observers 的特殊地位：前者是可叠加层（layered on top of any spawn pattern），后者本质是一种观察者关系，二者都不一定取代 handler 的主干形态——这一点在"模式可叠加"小节会展开。

三、触发短语表：从描述信号到模式候选

pattern-triggers.md的核心资产是触发短语表。匹配规则如下：

• 大小写不敏感匹配；
• 一个强匹配通常就足够确定模式；
• 若多个模式的短语同时命中，则进入消歧问答流程。

以下是原文完整保留的触发短语表（每行都对应一个或多个来自开发者描述中的典型措辞族）：

实战使用要点：

• 短语族之间存在大量语义重叠，例如 "N experts" 和 "chunks" 都可能暗示"多个子任务"，因此单看一个词不够，要看整体的协调结构信号：专家角色是否固定、数量是否随输入变化、执行是并行还是串行。
• 从仓库源码看，manager-worker与map-reduce的核心差异在于专家集合是否固定。对比 perspectives.ts 中写死的PERSPECTIVES数组（optimist / critic 两个固定角色）与 researcher.ts 中通过工具参数动态传入的specialists数组（数量不固定），可以直观看到：前者是 manager-worker，后者更接近 map-reduce / dispatcher 的变体。

四、消歧流程：六个问题的优先级顺序

当两个或以上模式平票（或描述完全没有给出协调信号）时，进入消歧问答。规则是：每条消息只问一个结构化问题，一旦模式明确立即停止提问。

消歧问题必须按以下优先级顺序提问：

1. 是否会孵化/协调其他 Entity？否 →single-agent；是 → 继续。
2. 并行还是顺序孵化？一次性全部孵化 →map-reduce或manager-worker；一个接一个 →pipeline。
3. 固定专家角色还是动态类型？（仅在并行分支时提问）固定集合（如 {economic, political, social}）→manager-worker；数量可变 / 运行时才确定类型 →map-reduce（按块）或dispatcher（按请求）。
4. 按块还是按请求选择类型？按数据集的块 →map-reduce；按到达的请求 →dispatcher。
5. 多个 Entity 是否读写同一份数据集？是 →blackboard（可叠加在任何孵化模式之上）。
6. 该 Entity 是否观察另一 Entity 的流以响应变化？是 →reactive-observers。

一个值得强调的设计原则：模式可以叠加（A pattern can layer on top of another）。例如manager-worker + blackboard——多个 worker 将发现写入共享黑板，manager 从中读取。此时主模式（primary pattern）决定 handler 的形态，次级模式（secondary pattern）体现为额外的 state 与 wake 需求。这一点与 blackboard.md 以及 review-checklist.md 中"共享状态父与子必须使用完全相同的 schema"（Gotcha 8）的要求直接呼应。

消歧问答的典型轮数

根据 SKILL.md 的说明，Phase 2 的典型问答轮数是2～4 个问题。这意味着：不要为了"确认"而无限追问，触发表已经提供了强先验，消歧只用来剔除并列候选。

五、四个工作示例：完整推导过程

pattern-triggers.md提供了四个从易到难的示例，覆盖了"单一强匹配""协调信号模糊""无协调信号""模式叠加"四类典型场景。以下是原文完整继承的推导过程：

示例 1 — 清晰的单一匹配

"I want an agent that summarizes PRs when they change."（我想要一个在 PR 变化时对其进行总结的 Agent。）

• 命中的触发词："when they change"（当它们变化时）→reactive-observers。
• 行动：推断为reactive-observers，用一个问题确认："每个 PR 是否有一个对应的 Entity（由你的总结器观察），还是一个单一 Entity 观察一整个 inbox 消息流？"若是前者：一个 reactive-observer 观察 PR Entity；若是后者：single-agent消费 inbox。

这个示例说明：reactive-observers与single-agent的边界在于被观察对象是"外部实体的流"还是"自己的消息队列"。

示例 2 — 模糊的协调信号

"Break a research question into 5 subtopics, research each in parallel, merge the findings."（把一个研究问题拆成 5 个子主题，并行研究每个子主题，合并发现。）

• 命中的触发词："in parallel"（并行）、"merge"（合并）→map-reduce；但 "subtopics"（子主题）也可读作固定专家集合。
• 行动：问"这 5 个子主题是固定专家（始终是同样的 5 个角色，例如经济/政治/社会/技术/历史），还是根据每个问题动态生成？"固定 →manager-worker；动态 →map-reduce。

示例 3 — 无协调信号

"An agent that answers questions using web search."（一个使用网络搜索回答问题的 Agent。）

• 命中的触发词：协调相关短语全部未命中。
• 行动：确认"这个 Entity 会孵化或观察其他 Entity，还是只是一个带工具的单一 LLM 循环？"→ 若只是带工具的循环 →single-agent。

示例 4 — 模式叠加

"Multiple workers research a topic and write their findings to a shared board that the manager reads to produce a final report."（多个 worker 研究一个主题，把发现写入共享看板，manager 读取后产出最终报告。）

• 命中的触发词："multiple workers"（多个 worker）→manager-worker；"shared board"（共享看板）→blackboard。
• 行动：确认"父 Entity 是等待所有 worker 全部完成后再综合，还是随着发现落上黑板就实时响应？"等待全部完成 →manager-worker叠加blackboard共享发现；实时响应 →manager-worker + blackboard，并在共享状态上配置wake: { on: "change" }。

示例 4 清晰演示了"主模式决定 handler 形态，次级模式补充 state/wake 需求"的叠加原则：实时响应场景下，blackboard 层的观察语义（wake: { on: "change" }）直接进入 wake 配置。

六、推断结果输出格式（Phase 3 衔接）

Phase 2 一旦完成，就进入 Phase 3 的模式提案。pattern-triggers.md明确要求总是显式打印匹配结果，以便开发者可以覆盖（override）：

Inferred pattern: map-reduce Why: "in parallel" + "merge findings" + "per-subtopic worker" (dynamic count) Canonical example: examples/durable-agents-playground/src/coordination/map-reduce.ts

三个字段的语义：

• Inferred pattern：最终推断的模式名，必须是七种模式之一。
• Why：命中的触发短语 + 结构性信号，作为推断理由的可追溯依据。
• Canonical example：指向该模式的权威示例实现路径，供开发者深入研读。

如果开发者明确覆盖（例如 "actually use blackboard"），要求是不做争辩地切换（switch without arguing）——加载新的模式文件，并针对该模式重做 Phase 3。这是技能设计中的一个重要交互原则：推断结果只是建议，开发者对架构拥有最终决定权。

说明：原文档引用的 canonical example 路径examples/durable-agents-playground/src/coordination/...在当前仓库中对应的是 examples/agents-playground/entities/ 目录下的实现（perspectives、researcher 等），本仓库中以该路径为准。

七、从触发表到源码：两种核心模式的实现纵深

触发表只是"入口"，模式真正落地依赖references/patterns/下的模式文件与仓库中的示例代码。以下用manager-worker与map-reduce两个最典型的孵化型模式，展示从触发词到实现的完整链路。

7.1 manager-worker：固定专家集合的 spawn-once 守护

根据 manager-worker.md，该模式的适用条件非常明确：

• 固定、具名的专家角色集合（不是每个输入数量可变）；
• 每个专家从不同角度考察同一个主题；
• 父 Entity 等待全部专家完成后才产出综合结果；
• 父 Entity 的最终回复整合所有子 Entity 的输出。

若专家数量随输入变化（每块一个 worker），应改用 map-reduce；若专家逐个串行执行（A 的输出是 B 的输入），应改用 pipeline；若专家按请求动态选择，应改用 dispatcher。

该模式的必需 state设计如下（原文完整保留）：

state: { children: { schema: z.object({ key: z.string(), // specialist role identifier url: z.string(), // child's entityUrl, populated after spawn kind: z.string(), // specialist role (matches key) question: z.string(),// question delivered to this specialist }), primaryKey: "key", }, }

handler 骨架的关键约束（摘自模式文件的 Invariants）：

• Spawn-once 守护：每次 spawn 前必须读取ctx.db.collections.children?.get(id)，已存在则通过ctx.observe(entity(url))复用，否则ctx.spawn(...)。违反它会因重复 spawn 相同 child ID 而报错。
• 确定性 child ID：子 ID 从专家角色 key 派生（如p.id），严禁使用Date.now()或计数器——重唤醒（re-wake）后 ID 必须稳定。
• 每个产出结果的 spawn 都要带wake: { on: "runFinished", includeResponse: true }：否则父 Entity 永远收不到子完成后的续传唤醒。
• 收集阶段用Promise.all：子任务相互独立，绝不能顺序 await（否则退化为 ad-hoc pipeline）。
• 综合步骤交给父 LLM：工具返回的是聚合结果，不是最终综合——父 LLM 看到聚合文本后产出最终答案。

仓库中 perspectives.ts 是该模式最直接的落地佐证：工具analyze_question遍历固定的PERSPECTIVES数组，用ctx.spawn("worker", childId, { systemPrompt, tools: ["bash"] }, { initialMessage: question, wake: { on: "runFinished", includeResponse: true } })孵化两个专家，并立即children_insert记录元数据——这正是 spawn-once 守护与确定性 ID 的实例。

7.2 map-reduce：按块并行与 spawn 计数器

根据 map-reduce.md，map-reduce 与 manager-worker 的本质区别是：worker 数量随输入变化（每个 chunk 一个）。适用条件：

• 输入是可以并行处理的集合（数据行、文档、URL、搜索查询等）；
• 每个 chunk 用相同systemPrompt、不同 payload 做相同处理；
• worker 数量取决于输入规模而非固定；
• 末尾有 reduce 步骤聚合所有结果。

其必需 state 比 manager-worker 多出status（状态机）与spawnCounter（孵化计数器）两个集合：

state: { children: { schema: z.object({ key: z.string(), // `chunk-${i}-${timestamp}-${counter}` url: z.string(), chunk: z.number(), // index in the chunks array }), primaryKey: "key", }, status: { schema: z.object({ key: z.literal("current"), value: z.enum(["idle", "mapping", "reducing"]), }), primaryKey: "key", }, spawnCounter: { schema: z.object({ key: z.literal("value"), count: z.number() }), primaryKey: "key", }, }

spawn 计数器是 map-reduce 的命门：它防止同一 map 操作在多次调用、多次重唤醒时重复生成相同的 child ID。骨架中子 ID 的构造是chunk-${i}-${Date.now()}-${spawnNum}——单独用Date.now()在快速连续调用时可能碰撞，所以必须叠加单调递增的计数器。状态机idle → mapping → reducing → idle用于阻止并发的 map 阶段交错执行。

仓库中 researcher.ts 展示了动态孵化多个专家的工作方式：通过工具参数传入specialists数组，childId = ${parentId}-${specialist.id}保证确定性，每个 spawn 都带runFinished唤醒，并记录到children集合。这与 map-reduce 的动态数量特征一致，是"动态专家"场景的实际参考。

7.3 内置 worker 的最小权限契约

无论哪种孵化模式，只要ctx.spawn("worker", ...)使用的是服务端内置 worker 类型，就必须遵守其严格契约（manager-worker.md 与 review-checklist.md 的 W1–W4 一致强调）：

interface WorkerArgs { systemPrompt: string tools: Array<WorkerToolName> // non-empty subset of: bash | read | write | edit | web_search | fetch_url | spawn_worker }

• worker不会收到ctx.electricTools——它是最小权限沙箱；省略tools或传空数组会在孵化时抛错。
• 需要共享状态 / 自定义工具时，必须注册自定义 worker 类型，而不是内置worker。
• 严禁在 worker 的systemPrompt或initialMessage中插值 API token、OAuth bearer、Cookie、签名 URL——这些会被持久化进 Entity 流，任何能读流的人都能读到密钥。认证型 fetch 应在 manager（可信代码）中完成，把原始响应作为数据传给 worker。

八、与评审检查表的衔接：Phase 2 的决策如何被验证

pattern-triggers.md推断出的模式，最终要在 Phase 4 通过 review-checklist.md 的通用检查表 + 模式专属检查表逐条验证。触发表与检查表之间存在直接的"因果链"：

• 触发表把描述映射为模式 → 模式文件定义该模式的专属检查规则（如 manager-worker 的 MW1–MW7、map-reduce 的 MR1–MR7）→ 通用检查表兜底所有模式共有的硬性契约。
• 通用检查表中的 H3（handler 不得依赖闭包状态跨 wake）、M4（产出结果的 spawn 必须带 runFinished 续传唤醒）、W1（内置 worker 必须传非空 tools）等规则，与模式文件中的 Invariants 完全同源。
• review-checklist 还收录了 15 条"坑目录"（Gotchas catalogue），其中第 1 条"spawn-once 违规"、第 4 条"缺少 runFinished 续传唤醒"、第 8 条"共享状态 schema 不一致"、第 14 条"worker 提示词中的密钥泄露"，都直接对应触发表模式落码后最常见的实现错误。

因此，从使用者的视角看，整个链路是自洽的：描述 → 触发表（Phase 2 收敛模式）→ 模式文件（Phase 3 定义形态）→ 检查表（Phase 4 验证契约）→ 单文件实现（Phase 5 落码）。pattern-triggers.md是这条链路的第一道闸门，它的准确与否直接决定后续所有阶段的效率。

九、最佳实践速查

综合 pattern-triggers.md、SKILL.md、模式参考文件与 review-checklist.md，使用时请遵循以下实践：

1. 一条强触发即优先候选，多条命中才消歧：避免过度提问，保持 Phase 2 在 2～4 个问题内收敛。
2. 消歧问题按固定优先级顺序：spawns？→ 并行/顺序？→ 固定/动态专家？→ 按块/按请求？→ 共享数据？→ 观察流？——顺序本身就是在教你区分模式。
3. 区分固定专家与动态数量：固定角色集合是 manager-worker 与 map-reduce 的分水岭；按请求动态路由则是 dispatcher。
4. 识别可叠加模式：blackboard 叠加在任何孵化模式之上，reactive-observers 描述的是观察关系——两者只改变 state/wake 需求，不改变主模式。
5. 推断结果必须显式输出：Inferred pattern+Why+Canonical example三要素齐全，给开发者覆盖的机会；开发者覆盖时切换而不争辩。
6. 从触发词到实现的每一步都要回到模式文件的 Invariants：spawn-once 守护、确定性 ID、runFinished 续传、Promise.all 并行收集、内置 worker 最小权限，这些是七种模式共通的工程底线。

【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric