多渠道 AI Agent 架构设计

1. Positioning / 定位

This concept targets systems that receive requests from one or more chat-like or event-driven channels, interpret user intent through a single logical frontdoor, and execute work through a small set of stable contracts.

该设想面向这样一类系统：请求来自一个或多个聊天式或事件驱动式入口，由唯一的逻辑前门统一理解需求，再通过少量稳定执行契约来完成执行。

The main design goal is to keep channel-specific behavior out of business logic, while preventing the frontdoor from becoming an unbounded "do everything" layer.

核心目标是把渠道细节隔离在业务逻辑之外，同时避免业务前门膨胀成无边界的"万事通"层。

2. Terminology / 术语表

3. Core Objectives / 核心目标

• Isolate transport from business logic.
  把传输适配从业务决策中隔离出去。
• One frontdoor, one visible reply surface, one final writer per request.
  每个请求只有一个业务前门、一个可见回复面、一个 final writer。
• Compress unbounded business scenarios into a small set of stable execution contracts.
  用少量稳定执行契约承接不断增长的业务场景。
• Make long-running work recoverable, inspectable, and auditable.
  让长流程具备可恢复、可检查、可审计能力。
• Keep business execution separated from operations and control-plane actions.
  将业务面执行与运维控制面动作彻底分离。

4. Layered Model / 分层模型

5. Boundary Definitions / 边界定义

5.1 Transport Ingress — 传输归一层

The gateway layer that normalizes channel events into a stable inbound contract. It has no role in business logic.
将渠道事件归一为稳定入站契约的网关层，与业务逻辑完全无关。

Does / 负责

Does not / 不负责

5.2 Business Orchestrator — 业务编排前门

The single logical frontdoor. Exactly one orchestrator, one visible reply surface, one final writer per request.
唯一的逻辑业务前门。每个请求只有一个编排前门、一个可见回复面、一个 final writer。

Does / 负责

5.3 Execution Segments — 执行段

Stable execution contracts that own predictable, inspectable work. Segment contracts remain stable even as business scenarios change.
持有可预测、可检查执行语义的稳定契约。即使业务场景不断变化，执行段契约也保持稳定。

5.4 Risk Gate — 风险门

A pre-execution decision layer that sits between execution segments and the runtime. All side-effecting actions must pass through it.
位于执行段与 runtime 之间的预执行决策层。所有有副作用的动作都必须通过。

Evaluation dimensions / 评估维度

Decisions / 决策

5.5 Operations Control — 运维控制面

The control-plane function that manages the entire system. It is separate from the business plane and should never be reached via normal business requests.
管理整套系统的控制面职能，与业务面彻底分离，不通过普通业务请求触达。

6. Execution Model / 执行模型

6.1 Intent Segments — 意图识别段

These describe the shape of demand, not execution contracts.
这些段负责表达需求形态，而非执行契约。

6.2 Execution Segments — 执行段

Six recommended stable execution contracts:
建议保留的六类稳定执行契约：

Watcher Segment — 观察段

Continuous observation, scheduled checks, anomaly monitoring, and follow-up verification.
持续观察、定时检查、异常监测与后续回查。

Artifact Workflow Segment — 产物工作流段

Drafting, review, export, packaging, and publish flows centered on artifacts.
以产物为中心的草稿、审核、导出、打包与发布流程。

Case Flow Segment — Case 流程段

Long-running flows with waiting points, approval steps, reminders, or pause/resume behavior.
包含等待点、审批步骤、提醒点或暂停恢复能力的长流程。

System Action Segment — 系统写操作段

Side-effecting writes into external systems. Requires idempotency, preflight checks, and rollback awareness.
面向外部系统的有副作用写操作。需要幂等性、预检与回滚感知。

Knowledge Maintenance Segment — 知识维护段

Quiet refresh, cleanup, deduplication, and distillation. Must support inspect, pause, validate, and rollback.
静默刷新、清理、去重与蒸馏。必须支持检查、暂停、验证与回滚。

Ops Escalation Segment — 运维升级段

Explicit handoff to the operations and control plane.
显式升级到运维控制面。

6.3 Triage Stage — 前置判断阶段

The Triage Stage lives inside the Business Orchestrator. It is not an execution segment and owns no runtime.
Triage Stage 位于 Business Orchestrator 内部，不是执行段，也不持有独立 runtime。

7. Composition Protocol / 组合协议

When one intent maps to more than one execution segment, an explicit composition protocol must be used.
当一个意图需要映射到多个执行段时，必须使用显式的组合协议。

7.1 Composition Modes / 组合模式

7.2 Ownership Rules / 所有权规则

• Exactly one primary segment may write to the DeliveryContext.
  只有一个 primary segment 可以写 DeliveryContext。
• All secondary segments may produce intermediate data or artifacts, but must never become the visible final writer.
  所有 secondary segment 只能产出中间数据或产物，不能成为可见 final writer。
• The orchestrator must declare final_writer_step before execution begins.
  编排层必须在执行开始前声明 final_writer_step。

7.3 Execution Plan Requirement / 执行计划要求

All multi-segment executions must be backed by a durable ExecutionPlan using either a clear state machine or a deterministic pipeline definition. Loose event choreography alone is insufficient for checkpointing, replay, audit, and recovery.

所有多段执行都必须有可持久化的 ExecutionPlan 支撑，底层基于明确状态机或确定性 pipeline。单靠松散事件编排不足以支撑 checkpoint、重放、审计与恢复。

8. Delivery Invariants / 交付不变量

These invariants must hold regardless of how many channels or long-running workflows the system supports:
无论系统支持多少渠道或长流程，以下不变量必须始终成立：

9. Context Model / 上下文模型

9.1 DeliveryContext — 单次交付上下文

Used for short-lived, single request-response interactions. Created at request start, closed on completion or failure.
用于短生命周期的单次请求交付，随请求创建、随完成或失败关闭。

9.2 CaseContext — 长流程上下文

Used for flows that span waiting points, multiple user turns, or background progression.
用于跨等待点、多轮交互或后台持续推进的长流程。

9.3 Serialization Rule / 可序列化规则

All durable contexts and plans must be serializable and hydratable after restart. Never store live process handles, active sockets, or transient runtime objects inside them.

所有可持久化的上下文与计划必须支持序列化与重启后 hydrate。不允许将活跃进程句柄、socket 或瞬时 runtime 对象存入其中。

10. Execution Primitives / 执行原语

direct — 直接执行

Use only when all of the following conditions are true. Otherwise use an execution segment.
仅当以下所有条件都满足时才使用，否则必须进入执行段。

pipeline — 流水线

For tightly coupled multi-step work that requires inspection, replay, and rollback.
适用于步骤强耦合、需要 inspect、重放与回滚能力的多步骤任务。

queue or job — 队列或定时任务

For background work, scheduled checks, pause/resume flows, or long-running cases.
适用于后台任务、定时检查、暂停恢复流程或长时间运行 case。

11. Risk Gate / 风险门

Evaluation Dimensions / 评估维度

Decision Outcomes / 决策结果

Approval for confirm decisions may come from policy rules or human-in-the-loop review.
confirm 决策的审批既可来自策略规则，也可来自人工参与审批。

12. Error Handling and Recovery / 错误处理与恢复

Error Flow / 错误流转

Recovery Principles / 恢复原则

13. Observability / 可观测性

A trace_id generated at the gateway layer must propagate end to end through every layer.
由网关层生成的 trace_id 必须端到端贯穿每一层。

14. Adoption Path / 演进路径

Phase 1 — Stabilize the Execution Skeleton / 稳定执行骨架

Phase 2 — Introduce the Gateway Layer / 引入网关层

Phase 3 — Add More Transport Channels / 接入更多渠道

15. Open-Source Note / 开源说明

This document is intentionally generalized for public sharing:
本文档有意为公开发布做了泛化处理：

The patterns described here are reusable for any multi-channel, long-running AI agent or workflow system. They are not specific to any single product.

本文描述的模式适用于任何多渠道、长流程 AI Agent 或工作流系统，不特定于任何单一产品。