agent-signal

Agent Signal

使用此技能为 Agent 实现事件驱动的后台工作，同时避免将工作与前台聊天请求耦合。

Agent Signal 具有一致的运行时形态：

source event -> signal interpretation -> action execution -> 内置结果信号

持久化的自迭代工作多一个完成分支：

memory/skill action -> execAgent 入队 -> agent.execution.completed -> selfIteration 回执投影

从这里开始

1. 阅读 references/architecture.md，了解包边界、运行时队列、作用域模型和异步工作流交接。
2. 编写新的策略、源处理器、信号处理器或操作处理器之前，先阅读 references/handlers.md。
3. 需要追踪、指标、调试或工作流快照可见性时，阅读 references/observability.md。

选择正确的入口

• 当服务端拥有的生产者应立即执行管道时，使用 emitAgentSignalSourceEvent(...)。
• 当工作线程或受控后端路径已负责执行时机，并且可能注入运行时守卫后端时，使用 executeAgentSignalSourceEvent(...)。
• 当调用方应快速返回，并让 Upstash Workflow 在带外处理事件时，使用 enqueueAgentSignalSourceEvent(...)。
• 对于应避免使用环境中的 Redis 状态的隔离测试或评估，使用 emitAgentSignalSourceEventWithStore(...)。

阅读：

• apps/server/src/services/agentSignal/index.ts
• apps/server/src/workflows/agentSignal/index.ts
• apps/server/src/workflows/agentSignal/run.ts

核心模型

• source：已发生的规范化事实。来源包括运行时生命周期事件、用户消息或机器人入口等生产者。
• signal：根据一个来源或另一个信号推导出的语义解释。信号表达含义、路由或策略状态。
• action：根据一个信号规划的具体副作用。操作负责执行工作。
• policy：用于注册来源、信号和操作处理器的可安装中间件包。
• procedure：不是独立的运行时节点。将“过程”视为一个用例的端到端流程：入口来源、匹配的处理器、规划的操作、执行结果和可观测性。

严格遵守以下边界：

• 当外部世界产生了新事件时，添加新的 source。
• 当系统需要可复用的语义解释时，添加新的 signal。
• 当运行时需要具体的副作用时，添加新的 action。
• 将这些部分连接起来时，添加或更新 policy。

实现工作流

1. 判断用例属于同步工作还是静默后台工作。
2. 在 packages/agent-signal/src/source/sourceTypes.ts 中定义或复用来源类型。
3. 在 apps/server/src/services/agentSignal/policies/types.ts 中定义或复用信号和操作类型。
4. 使用 defineSourceHandler、defineSignalHandler 或 defineActionHandler 实现处理器。
5. 如果生产者负载需要整形，则在 apps/server/src/services/agentSignal/sources/** 下添加来源规范化或数据填充逻辑。
6. 使用 defineAgentSignalHandlers(...) 汇总处理器。
7. 在 apps/server/src/services/agentSignal/policies/index.ts 中注册策略，并在需要时将其传入运行时工厂。
8. 添加或更新入口代码，以发出或入队来源事件。
9. 对于异步自迭代写入，添加 Agent Signal 操作标记，并从完成路径投影面向用户的回执。
10. 在认为流程完成之前，添加可观测性和测试。

默认阅读集合

• 共享语义核心： packages/agent-signal/src/index.ts packages/agent-signal/src/base/builders.ts packages/agent-signal/src/base/types.ts packages/agent-signal/src/source/sourceTypes.ts packages/agent-signal/src/source/sourceEvent.ts
• 服务端拥有的运行时和中间件： apps/server/src/services/agentSignal/runtime/AgentSignalRuntime.ts apps/server/src/services/agentSignal/runtime/AgentSignalScheduler.ts apps/server/src/services/agentSignal/runtime/middleware.ts apps/server/src/services/agentSignal/runtime/context.ts
• 现有策略示例： apps/server/src/services/agentSignal/policies/analyzeIntent/index.ts apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.ts apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackDomain.ts apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackAction.ts apps/server/src/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts apps/server/src/services/agentSignal/policies/analyzeIntent/actions/skillManagement.ts apps/server/src/services/agentSignal/policies/analyzeIntent/completionSkillSynthesis.ts apps/server/src/services/agentSignal/policies/completionPolicy.ts apps/server/src/services/agentSignal/services/selfIteration/completion/buildSelfIterationReceipts.ts apps/server/src/services/agentSignal/services/selfIteration/completion/selfIterationCompletionHandler.ts
• 可观测性： apps/server/src/services/agentSignal/observability/projector.ts apps/server/src/services/agentSignal/observability/traceEvents.ts packages/observability-otel/src/modules/agent-signal/index.ts

实现规则

• 添加新类型前，先复用现有的来源、信号和操作类型。
• 来源处理器应专注于解释和分发，而不是执行繁重的副作用。
• 操作处理器负责副作用、幂等性和执行器式结果报告。对于记忆/技能自迭代操作，副作用是将 execAgent 加入队列；持久化写入和回执投影会在完成后进行。
• 当同一来源可能多次到达时，使用稳定 ID 和幂等键。
• 保持作用域纪律。运行时使用 scopeKey 串行处理相关的后台工作。
• 对于规范化节点和结果契约，优先使用 @lobechat/agent-signal 中专用的共享包类型和构建器。
• 不要从入队操作中投影记忆或技能回执。使用 agent.execution.completed + selfIteration 最终状态，并通过 createSelfIterationCompletionHandler(...) 处理。
• 在所修改的运行时、策略或存储模块附近添加有针对性的测试。apps/server/src/services/agentSignal/**/__test__ 和 **/__tests__ 下的现有测试可作为参考模式。

参考

• 架构和边界：references/architecture.md
• 编写处理器和策略：references/handlers.md
• 可观测性、指标和调试：references/observability.md