代理信号
- 作者仓库星标 77,599
- 作者仓库 lobehub
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @lobehub · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Agent Signal
Use this skill to implement event-driven background work for agents without coupling the work to the foreground chat request.
Agent Signal has one consistent shape:
`source event` -> `signal interpretation` -> `action execution` -> built-in result signals
## Start Here
1. Read `references/architecture.md` to map the package boundary, runtime queue, scope model, and async workflow handoff.
2. Read `references/handlers.md` before writing any new policy, source handler, signal handler, or action handler.
3. Read `references/observability.md` when you need tracing, metrics, debugging, or workflow snapshot visibility.
## Use The Right Entry Point
- Use `emitAgentSignalSourceEvent(...)` when a server-owned producer should execute the pipeline immediately.
- Use `executeAgentSignalSourceEvent(...)` when a worker or controlled backend path already owns execution timing and may inject a runtime guard backend.
- Use `enqueueAgentSignalSourceEvent(...)` when the caller should return quickly and let Upstash Workflow process the event out-of-band.
- Use `emitAgentSignalSourceEventWithStore(...)` for isolated tests or evals that should avoid ambient Redis state.
Read:
- `src/server/services/agentSignal/index.ts`
- `src/server/workflows/agentSignal/index.ts`
- `src/server/workflows/agentSignal/run.ts`
## Core Model
- `source`: A normalized fact that happened. Sources come from producers such as runtime lifecycle events, user messages, or bot ingress.
- `signal`: A semantic interpretation derived from one source or from another signal. Signals express meaning, routing, or policy state.
- `action`: A concrete side effect planned from one signal. Actions do the work.
- `policy`: An installable middleware bundle that registers source, signal, and action handlers.
- `procedure`: Not a distinct runtime node. Treat "procedure" as the end-to-end flow for one use case: ingress source, matching handlers, planned actions, execution result, and observability.
Keep the boundaries strict:
- Add a new `source` when the outside world produced a new event.
- Add a new `signal` when the system needs a reusable semantic interpretation.
- Add a new `action` when the runtime needs a concrete side effect.
- Add or update a `policy` when you are wiring those pieces together.
## Implementation Workflow
1. Decide whether the use case is synchronous or quiet background work.
2. Define or reuse a source type in `src/server/services/agentSignal/sourceTypes.ts`.
3. Define or reuse signal and action types in `src/server/services/agentSignal/policies/types.ts`.
4. Implement handlers with `defineSourceHandler`, `defineSignalHandler`, or `defineActionHandler`.
5. Bundle handlers with `defineAgentSignalHandlers(...)`.
6. Register the policy in `src/server/services/agentSignal/policies/index.ts` and pass it into the runtime factory if needed.
7. Add or update ingress code that emits or enqueues the source event.
8. Add observability and tests before considering the flow complete.
## Default Reading Set
- Shared semantic core:
`packages/agent-signal/src/index.ts`
`packages/agent-signal/src/base/builders.ts`
`packages/agent-signal/src/base/types.ts`
- Server-owned runtime and middleware:
`src/server/services/agentSignal/runtime/AgentSignalRuntime.ts`
`src/server/services/agentSignal/runtime/AgentSignalScheduler.ts`
`src/server/services/agentSignal/runtime/middleware.ts`
`src/server/services/agentSignal/runtime/context.ts`
- Existing policy example:
`src/server/services/agentSignal/policies/analyzeIntent/index.ts`
`src/server/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.ts`
`src/server/services/agentSignal/policies/analyzeIntent/feedbackDomain.ts`
`src/server/services/agentSignal/policies/analyzeIntent/feedbackAction.ts`
`src/server/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts`
- Observability:
`src/server/services/agentSignal/observability/projector.ts`
`src/server/services/agentSignal/observability/traceEvents.ts`
`packages/observability-otel/src/modules/agent-signal/index.ts`
## Implementation Rules
- Reuse existing source, signal, and action types before adding new ones.
- Keep source handlers focused on interpretation and fan-out, not heavy side effects.
- Keep action handlers responsible for side effects, idempotency, and executor-style result reporting.
- Use stable ids and idempotency keys when the same source can arrive more than once.
- Preserve scope discipline. The runtime uses `scopeKey` to serialize related background work.
- Prefer the dedicated shared package types and builders from `@lobechat/agent-signal` for normalized nodes and result contracts.
- Add focused tests near the touched runtime, policy, or store module. Existing tests under `src/server/services/agentSignal/**/__tests__` are the reference pattern.
## References
- Architecture and boundaries: `references/architecture.md`
- Writing handlers and policies: `references/handlers.md`
- Observability, metrics, and debugging: `references/observability.md`
章节与文件索引
按说明文件中的顺序排列。
从这里开始
Use The Right Entry Point
核心模型
实施工作流程
默认阅读集
文件/命令 -> source event · signal interpretation · action execution · references/architecture.md · references/handlers.md · references/observability.md · emitAgentSignalSourceEvent(...) · executeAgentSignalSourceEvent(...)
内容校验值 -> 09ca41869e4c
当前原文的自动摘译,尚未人工审校。
从这里开始
阅读
references/architecture.md来映射包边界、运行时队列、范围模型和异步工作流程切换。在编写任何新策略、源处理程序、信号处理程序或操作处理程序之前,请阅读references/handlers.md。当您需要跟踪、指标、调试或工作流程快照可见性时,请阅读references/observability.md。Use The Right Entry Point
当服务器拥有的生产者应该立即执行管道时,请使用
emitAgentSignalSourceEvent(...)。当工作线程或受控后端路径已经拥有执行时序并可能注入运行时保护后端时,请使用executeAgentSignalSourceEvent(...)。当调用者应该快速返回并让 Upstash Workflow 在带外处理事件时,请使用enqueueAgentSignalSourceEvent(...)。使用emitAgentSignalSourceEventWithStore(...)进行隔离测试或评估,应避免环境 Redis 状态。核心模型
source: A normalized fact that happened.来源来自生产者,例如运行时生命周期事件、用户消息或机器人入口。signal:源自一个来源或另一个信号的语义解释。信号表达含义、路由或策略状态。action:从一个信号计划的具体副作用。行动才能发挥作用。policy:一个可安装的中间件包,用于注册源、信号和操作处理程序。实施工作流程
确定用例是同步还是安静的后台工作。 Define or reuse a source type in
src/server/services/agentSignal/sourceTypes.ts.在src/server/services/agentSignal/policies/types.ts中定义或重用信号和动作类型。使用defineSourceHandler、defineSignalHandler或defineActionHandler实现处理程序。 Bundle handlers withdefineAgentSignalHandlers(...).默认阅读集
共享语义核心:
packages/agent-signal/src/index.tspackages/agent-signal/src/base/builders.tspackages/agent-signal/src/base/types.ts服务器拥有的运行时和中间件: