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 2Clarify阶段将开发者对 AgentEntity的自然语言描述通过触发短语表 消歧问答流精确映射到七种协调模式single-agent、manager-worker、pipeline、map-reduce、dispatcher、blackboard、reactive-observers。读完本文你将掌握触发表的匹配规则、六步消歧问答的优先级顺序、四种典型工作示例的推导过程以及模式推断结果的标准输出格式并能结合 manager-worker、map-reduce 等模式参考文件与 agents-playground 的源码实现直接动手设计出结构正确的 Entity。一、模式触发器在整个技能工作流中的位置pattern-triggers.md不是一份孤立的技术文档它是 designing-entities 技能 五阶段工作流的第二阶段Clarify专用参考文件。整个技能的五阶段是Elicit向开发者提出一个开放问题获取 Entity 的描述这个 entity 要做什么与谁交互什么触发它。Clarify按需加载references/pattern-triggers.md将描述与触发表匹配若模式唯一则跳过问答否则每次只问一个消歧问题直到模式明确。Propose pattern and design明确推断出的模式与理由加载references/patterns/name.md输出设计大纲类型名、协调模式、creationSchema、state集合、inboxSchemas、handler 结构等。Review加载 review-checklist.md对照通用检查表与模式专属检查表逐条报告 ✓/✗/N/A循环直到开发者明确批准。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 按需加载模式一句话定义参考文件single-agent无其他 Entity 参与单一 LLM 循环 工具调用single-agent.mdmanager-worker父 Entity 孵化固定集合的专家子 Entity全部完成后由父 LLM 综合manager-worker.mdpipeline顺序执行的多阶段链式处理前一阶段输出作为后一阶段输入pipeline.mdmap-reduce将输入切分为块各块并行独立处理最后归并结果worker 数量随输入变化map-reduce.mddispatcher按请求类型将任务动态路由/分发给不同的专家dispatcher.mdblackboard多个 Entity 读写同一份共享数据共享黑板可叠加在其他孵化模式之上blackboard.mdreactive-observers一个 Entity 观察另一 Entity 的流/状态变化并作出响应reactive-observers.md注意 blackboard 与 reactive-observers 的特殊地位前者是可叠加层layered on top of any spawn pattern后者本质是一种观察者关系二者都不一定取代 handler 的主干形态——这一点在模式可叠加小节会展开。三、触发短语表从描述信号到模式候选pattern-triggers.md的核心资产是触发短语表。匹配规则如下大小写不敏感匹配一个强匹配通常就足够确定模式若多个模式的短语同时命中则进入消歧问答流程。以下是原文完整保留的触发短语表每行都对应一个或多个来自开发者描述中的典型措辞族描述中的短语族建议模式multiple perspectives多视角、specialists专家、different angles不同角度、fan out and synthesize扇出并综合、analyze from different viewpoints从不同观点分析、N expertsN 个专家manager-workersequential stages顺序阶段、step by step逐步、chain stages链式阶段、preprocessing then analysis先预处理再分析、pipeline流水线、feed output to next输出馈入下一步pipelineparallel并行、all at once一次性全部、chunks分块、divide and process切分并处理、batch批量、fan out and collect扇出并收集、process in parallel并行处理、map over映射遍历map-reduceclassify and route分类并路由、dispatch分发、different types of requests不同类型的请求、router路由器、distribute to specialists分发给专家、dynamic routing动态路由dispatchershared knowledge base共享知识库、collaborative writing协作写作、debate辩论、wiki、 shared state共享状态、collective intelligence集体智能、workers updating the same board多个 worker 更新同一块看板blackboardmonitor监控、watch观察、dashboard仪表盘、react to changes对变化作出反应、observe and report观察并报告、event-driven response事件驱动响应、track another entity跟踪另一个实体reactive-observers以上均未命中没有其他 Entity 参与单一 LLM 循环single-agent实战使用要点短语族之间存在大量语义重叠例如 N experts 和 chunks 都可能暗示多个子任务因此单看一个词不够要看整体的协调结构信号专家角色是否固定、数量是否随输入变化、执行是并行还是串行。从仓库源码看manager-worker与map-reduce的核心差异在于专家集合是否固定。对比 perspectives.ts 中写死的PERSPECTIVES数组optimist / critic 两个固定角色与 researcher.ts 中通过工具参数动态传入的specialists数组数量不固定可以直观看到前者是 manager-worker后者更接近 map-reduce / dispatcher 的变体。四、消歧流程六个问题的优先级顺序当两个或以上模式平票或描述完全没有给出协调信号时进入消歧问答。规则是每条消息只问一个结构化问题一旦模式明确立即停止提问。消歧问题必须按以下优先级顺序提问是否会孵化/协调其他 Entity否 →single-agent是 → 继续。并行还是顺序孵化一次性全部孵化 →map-reduce或manager-worker一个接一个 →pipeline。固定专家角色还是动态类型仅在并行分支时提问固定集合如 {economic, political, social}→manager-worker数量可变 / 运行时才确定类型 →map-reduce按块或dispatcher按请求。按块还是按请求选择类型按数据集的块 →map-reduce按到达的请求 →dispatcher。多个 Entity 是否读写同一份数据集是 →blackboard可叠加在任何孵化模式之上。该 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 中共享状态父与子必须使用完全相同的 schemaGotcha 8的要求直接呼应。消歧问答的典型轮数根据 SKILL.md 的说明Phase 2 的典型问答轮数是24 个问题。这意味着不要为了确认而无限追问触发表已经提供了强先验消歧只用来剔除并列候选。五、四个工作示例完整推导过程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-workershared 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明确要求总是显式打印匹配结果以便开发者可以覆盖overrideInferred 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(), // childs entityUrl, populated after spawn kind: z.string(), // specialist role (matches key) question: z.string(),// question delivered to this specialist }), primaryKey: key, }, }handler 骨架的关键约束摘自模式文件的 InvariantsSpawn-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.mdmap-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: ArrayWorkerToolName // 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→ 通用检查表兜底所有模式共有的硬性契约。通用检查表中的 H3handler 不得依赖闭包状态跨 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使用时请遵循以下实践一条强触发即优先候选多条命中才消歧避免过度提问保持 Phase 2 在 24 个问题内收敛。消歧问题按固定优先级顺序spawns→ 并行/顺序→ 固定/动态专家→ 按块/按请求→ 共享数据→ 观察流——顺序本身就是在教你区分模式。区分固定专家与动态数量固定角色集合是 manager-worker 与 map-reduce 的分水岭按请求动态路由则是 dispatcher。识别可叠加模式blackboard 叠加在任何孵化模式之上reactive-observers 描述的是观察关系——两者只改变 state/wake 需求不改变主模式。推断结果必须显式输出Inferred patternWhyCanonical example三要素齐全给开发者覆盖的机会开发者覆盖时切换而不争辩。从触发词到实现的每一步都要回到模式文件的 Invariantsspawn-once 守护、确定性 ID、runFinished 续传、Promise.all 并行收集、内置 worker 最小权限这些是七种模式共通的工程底线。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考