sz_rust_capability/
lib.rs

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

sz_rust_capability/
lib.rs
