sz_rust_capability/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright (c) 2024-2026 SZ-Rust Team
3//
4#![forbid(unsafe_code)]
5//! # SZ-Rust Capability Registry
6//!
7//! 统一能力注册表，将 Skills（AI 内置能力）与 Plugins（业务插件）抽象为统一的 [`Capability`] 接口。
8//!
9//! ## 核心组件
10//!
11//! - [`Capability`] trait — 统一能力抽象（name/description/schema/tags/source/call）
12//! - [`CapabilityRegistry`] — 中心注册表（注册/发现/调用）
13//! - [`Cap`] facade — 静态 API（OnceLock 全局实例）
14//! - [`CapabilitySource`] — 能力来源枚举（Skill/Plugin/Service）
15//! - [`CapError`] — 错误类型（6 变体，non_exhaustive）
16//! - [`McpCapabilityAdapter`] — MCP 工具适配为 Capability
17//!
18//! ## 快速开始
19//!
20//! ### 使用 facade（推荐）
21//!
22//! ```no_run
23//! use std::sync::Arc;
24//! use async_trait::async_trait;
25//! use serde_json::{json, Value};
26//! use sz_rust_capability::{Cap, Capability, CapabilitySource, CapError, CapResult};
27//!
28//! struct MyCapability;
29//!
30//! #[async_trait]
31//! impl Capability for MyCapability {
32//!     fn name(&self) -> &'static str { "my.cap" }
33//!     fn description(&self) -> &'static str { "自定义能力" }
34//!     fn schema(&self) -> Value { json!({}) }
35//!     fn tags(&self) -> &[&'static str] { &["custom"] }
36//!     fn source(&self) -> CapabilitySource { CapabilitySource::Plugin }
37//!     async fn call(&self, args: Value) -> CapResult<Value> { Ok(args) }
38//! }
39//!
40//! // 初始化 facade
41//! Cap::init().ok();
42//!
43//! // 注册能力
44//! Cap::register(Arc::new(MyCapability)).unwrap();
45//!
46//! // 发现能力
47//! let caps = Cap::find_by_tags(&["custom"], None).unwrap();
48//! assert_eq!(caps.len(), 1);
49//! ```
50//!
51//! ### 使用 Registry 实例（多实例场景）
52//!
53//! ```
54//! use std::sync::Arc;
55//! use async_trait::async_trait;
56//! use serde_json::{json, Value};
57//! use sz_rust_capability::{Capability, CapabilityRegistry, CapabilitySource, CapResult};
58//!
59//! struct EchoCap;
60//! #[async_trait]
61//! impl Capability for EchoCap {
62//!     fn name(&self) -> &'static str { "echo" }
63//!     fn description(&self) -> &'static str { "回显" }
64//!     fn schema(&self) -> Value { json!({}) }
65//!     fn tags(&self) -> &[&'static str] { &["test"] }
66//!     fn source(&self) -> CapabilitySource { CapabilitySource::Skill }
67//!     async fn call(&self, args: Value) -> CapResult<Value> { Ok(args) }
68//! }
69//!
70//! let registry = CapabilityRegistry::new();
71//! registry.register(Arc::new(EchoCap));
72//! assert_eq!(registry.len(), 1);
73//! ```
74//!
75//! ### 注册 MCP 工具
76//!
77//! ```no_run
78//! use sz_rust_capability::{CapabilityRegistry, register_mcp_tools};
79//!
80//! let registry = CapabilityRegistry::new();
81//! let names = register_mcp_tools(&registry).unwrap();
82//! assert_eq!(names.len(), 7); // 7 个 MCP 工具
83//! ```
84//!
85//! ## 性能指标
86//!
87//! | 操作 | 延迟 | spec 要求 |
88//! |------|------|-----------|
89//! | 注册 | 187 ns | <1 ms |
90//! | 查找 | 38 ns | <100 μs |
91//! | 标签搜索（1000 能力） | 20 μs | <5 ms |
92
93pub mod builtin;
94pub mod capability;
95pub mod error;
96pub mod facade;
97pub mod metrics;
98pub mod permission;
99pub mod registry;
100pub mod source;
101
102pub use builtin::{
103    register_builtin_skills, register_extended_mcp_tools, register_mcp_tools, ExtendedMcpAdapter,
104    McpCapabilityAdapter,
105};
106pub use capability::{Capability, CapabilityInfo};
107pub use error::{CapError, CapResult};
108pub use facade::Cap;
109pub use metrics::CapMetrics;
110pub use permission::{AllowAll, PermissionChecker, TenantScopeChecker};
111pub use registry::CapabilityRegistry;
112pub use source::CapabilitySource;
sz_rust_capability/lib.rs

sz_rust_capability/
lib.rs
