sh_layer3/tool_executor/
mod.rs

1//! # Tool Executor
2//!
3//! 工具执行器：负责执行工具调用并返回结果。
4
5pub mod executor;
6
7use crate::types::{Layer3Result, ToolMeta, ToolRequest, ToolResponse};
8use async_trait::async_trait;
9
10// Re-export executor implementation
11pub use executor::{DefaultToolExecutor, ExecutionRecord, JsonSchemaValidator};
12
13/// 工具执行器 trait
14///
15/// 定义工具执行的核心接口。实现者负责：
16/// 1. 接收工具调用请求
17/// 2. 验证参数
18/// 3. 执行工具逻辑
19/// 4. 返回执行结果
20#[async_trait]
21pub trait ToolExecutor: Send + Sync {
22    /// 执行单个工具调用
23    ///
24    /// # Arguments
25    /// * `request` - 工具调用请求
26    ///
27    /// # Returns
28    /// * `ToolResponse` - 执行结果
29    async fn execute(&self, request: ToolRequest) -> Layer3Result<ToolResponse>;
30
31    /// 执行多个工具调用（并行）
32    ///
33    /// # Arguments
34    /// * `requests` - 多个工具调用请求
35    ///
36    /// # Returns
37    /// * `Vec<ToolResponse>` - 所有执行结果
38    async fn execute_batch(&self, requests: Vec<ToolRequest>) -> Layer3Result<Vec<ToolResponse>>;
39
40    /// 检查工具是否可用
41    ///
42    /// # Arguments
43    /// * `name` - 工具名称
44    fn is_available(&self, name: &str) -> bool;
45
46    /// 获取工具元数据
47    ///
48    /// # Arguments
49    /// * `name` - 工具名称
50    fn get_meta(&self, name: &str) -> Option<ToolMeta>;
51
52    /// 获取所有已注册工具的元数据
53    fn list_tools(&self) -> Vec<ToolMeta>;
54}
55
56/// 工具验证 trait
57///
58/// 定义参数验证接口。
59pub trait ToolValidator: Send + Sync {
60    /// 验证工具调用参数
61    ///
62    /// # Arguments
63    /// * `request` - 工具调用请求
64    ///
65    /// # Returns
66    /// * `bool` - 参数是否有效
67    fn validate(&self, request: &ToolRequest) -> bool;
68
69    /// 获取验证失败原因
70    ///
71    /// # Arguments
72    /// * `request` - 工具调用请求
73    fn validate_with_reason(&self, request: &ToolRequest) -> Result<(), String>;
74}
75
76/// 工具执行上下文
77///
78/// 提供工具执行时需要的上下文信息。
79#[derive(Debug, Clone)]
80pub struct ExecutionContext {
81    /// 当前会话 ID
82    pub session_id: String,
83    /// 当前工作目录
84    pub working_dir: std::path::PathBuf,
85    /// 用户 ID（用于权限检查）
86    pub user_id: Option<String>,
87    /// 环境变量
88    pub env_vars: std::collections::HashMap<String, String>,
89    /// 最大执行时间（秒）
90    pub timeout_secs: u64,
91    /// 是否允许危险操作
92    pub allow_dangerous: bool,
93}
94
95impl Default for ExecutionContext {
96    fn default() -> Self {
97        Self {
98            session_id: String::new(),
99            working_dir: std::path::PathBuf::from("."),
100            user_id: None,
101            env_vars: std::collections::HashMap::new(),
102            timeout_secs: 30,
103            allow_dangerous: false,
104        }
105    }
106}
107
108/// 带上下文的工具执行器
109///
110/// 扩展 ToolExecutor，支持上下文传递。
111#[async_trait]
112pub trait ContextualExecutor: ToolExecutor {
113    /// 带上下文执行工具
114    ///
115    /// # Arguments
116    /// * `request` - 工具调用请求
117    /// * `context` - 执行上下文
118    async fn execute_with_context(
119        &self,
120        request: ToolRequest,
121        context: ExecutionContext,
122    ) -> Layer3Result<ToolResponse>;
123
124    /// 带上下文批量执行
125    async fn execute_batch_with_context(
126        &self,
127        requests: Vec<ToolRequest>,
128        context: ExecutionContext,
129    ) -> Layer3Result<Vec<ToolResponse>>;
130}
131
132#[cfg(test)]
133mod tests {
134    use super::*;
135
136    #[test]
137    fn test_execution_context_default() {
138        let ctx = ExecutionContext::default();
139        assert_eq!(ctx.timeout_secs, 30);
140        assert!(!ctx.allow_dangerous);
141    }
142}
sh_layer3/tool_executor/mod.rs

sh_layer3/tool_executor/
mod.rs
