mofa_kernel/agent/secretary/mod.rs
1//! 秘书Agent抽象层
2//!
3//! 秘书Agent是一种特殊的Agent模式，提供持续在线的交互式助手能力。
4//! 本模块定义了秘书Agent的核心抽象，具体实现在 mofa-foundation 中。
5//!
6//! ## 设计理念
7//!
8//! - **核心抽象层**：框架只提供最核心的抽象与协议
9//! - **行为可插拔**：通过 `SecretaryBehavior` trait 定义秘书行为
10//! - **连接可扩展**：通过 `UserConnection` trait 支持多种通信方式
11//!
12//! ## 核心组件
13//!
14//! - [`SecretaryBehavior`]: 秘书行为trait，开发者实现此trait定义秘书逻辑
15//! - [`SecretaryContext`]: 秘书上下文
16//! - [`UserConnection`]: 用户连接抽象
17//!
18//! ## 使用方式
19//!
20//! ```rust,ignore
21//! use mofa_kernel::agent::secretary::{SecretaryBehavior, SecretaryContext};
22//! use mofa_foundation::secretary::SecretaryCore;
23//!
24//! struct MySecretary { /* ... */ }
25//!
26//! #[async_trait]
27//! impl SecretaryBehavior for MySecretary {
28//! type Input = MyInput;
29//! type Output = MyOutput;
30//! type State = MyState;
31//!
32//! async fn handle_input(
33//! &self,
34//! input: Self::Input,
35//! ctx: &mut SecretaryContext<Self::State>,
36//! ) -> anyhow::Result<Vec<Self::Output>> {
37//! // 自定义处理逻辑
38//! }
39//!
40//! fn initial_state(&self) -> Self::State {
41//! MyState::new()
42//! }
43//! }
44//!
45//! // 创建并启动秘书 (Foundation 层提供具体引擎)
46//! let core = SecretaryCore::new(MySecretary::new());
47//! let (handle, join) = core.start(connection).await;
48//! ```
49
50mod connection;
51mod context;
52mod traits;
53
54// 核心导出
55pub use connection::{ConnectionFactory, UserConnection};
56pub use context::{SecretaryContext, SecretaryContextBuilder, SharedSecretaryContext};
57pub use traits::{
58 EventListener, InputHandler, Middleware, PhaseHandler, PhaseResult, SecretaryBehavior,
59 SecretaryEvent, SecretaryInput, SecretaryOutput, WorkflowOrchestrator, WorkflowResult,
60};
61
62/// Prelude 模块
63pub mod prelude {
64 pub use super::{
65 PhaseHandler, PhaseResult, SecretaryBehavior, SecretaryContext, SecretaryInput,
66 SecretaryOutput, UserConnection, WorkflowOrchestrator, WorkflowResult,
67 };
68 pub use async_trait::async_trait;
69}