sz_rust_capability/
capability.rs

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

sz_rust_capability/
capability.rs
