sz_rust_capability/
capability.rs

1
2use async_trait::async_trait;
3use serde::Serialize;
4
5use crate::error::CapResult;
6use crate::source::CapabilitySource;
7
8/// 统一能力抽象 trait。
9///
10/// Skills（AI 内置能力）和 Plugins（业务插件）都实现此 trait，
11/// 通过 [`CapabilityRegistry`](crate::CapabilityRegistry) 统一注册、发现和调用。
12///
13/// # 实现示例
14///
15/// ```
16/// use async_trait::async_trait;
17/// use serde_json::{json, Value};
18/// use sz_rust_capability::{Capability, CapabilitySource, CapResult};
19///
20/// struct SearchCustomerCapability;
21///
22/// #[async_trait]
23/// impl Capability for SearchCustomerCapability {
24///     fn name(&self) -> &'static str { "crm.search_customer" }
25///     fn description(&self) -> &'static str { "搜索客户" }
26///     fn schema(&self) -> Value {
27///         json!({
28///             "type": "object",
29///             "properties": { "keyword": { "type": "string" } },
30///             "required": ["keyword"]
31///         })
32///     }
33///     fn tags(&self) -> &[&'static str] { &["crm", "search", "read"] }
34///     fn source(&self) -> CapabilitySource { CapabilitySource::Plugin }
35///     async fn call(&self, args: Value) -> CapResult<Value> {
36///         let keyword = args.get("keyword").and_then(|v| v.as_str()).unwrap_or("");
37///         Ok(json!({ "results": [keyword] }))
38///     }
39/// }
40/// ```
41#[async_trait]
42pub trait Capability: Send + Sync + 'static {
43    /// 能力名称，全局唯一，格式建议 `{source_prefix}.{capability_name}`。
44    fn name(&self) -> &'static str;
45
46    /// 人类可读的能力描述。
47    fn description(&self) -> &'static str;
48
49    /// 参数 JSON Schema，描述 `call` 方法的输入参数格式。
50    fn schema(&self) -> serde_json::Value;
51
52    /// 能力标签，用于 `find_by_tags` 搜索。多标签 AND 逻辑。
53    fn tags(&self) -> &[&'static str];
54
55    /// 能力来源类型（Skill/Plugin/Service）。
56    fn source(&self) -> CapabilitySource;
57
58    /// 执行能力，接受 JSON 参数，返回 JSON 结果。
59    async fn call(&self, args: serde_json::Value) -> CapResult<serde_json::Value>;
60
61    /// 能力版本，默认 "1.0.0"。
62    fn version(&self) -> &'static str {
63        "1.0.0"
64    }
65
66    /// 是否需要人工确认（HITL），默认 false。
67    fn requires_confirmation(&self) -> bool {
68        false
69    }
70
71    /// 参数校验，默认实现委托 [`validate_json_schema`](crate::registry::validate_json_schema) 做轻量校验。
72    /// 能力可覆盖此方法做完整 JSON Schema 校验。
73    async fn validate_args(&self, args: &serde_json::Value) -> CapResult<()> {
74        crate::registry::validate_json_schema(&self.schema(), args)
75    }
76}
77
78/// 能力元信息快照，用于列表/搜索返回。
79#[derive(Debug, Clone, Serialize)]
80pub struct CapabilityInfo {
81    pub name: &'static str,
82    pub description: &'static str,
83    pub tags: Vec<&'static str>,
84    pub source: CapabilitySource,
85    pub version: &'static str,
86    pub requires_confirmation: bool,
87}
88
89impl CapabilityInfo {
90    /// 从 Capability trait 对象提取元信息快照。
91    pub fn from_trait(cap: &dyn Capability) -> Self {
92        Self {
93            name: cap.name(),
94            description: cap.description(),
95            tags: cap.tags().to_vec(),
96            source: cap.source(),
97            version: cap.version(),
98            requires_confirmation: cap.requires_confirmation(),
99        }
100    }
101}
sz_rust_capability/capability.rs

sz_rust_capability/
capability.rs
