Skip to main content

acosmi/skills/
skills.rs

1//! 技能商店 + 生产器业务方法。端口自 `skills/skills.ts`
2//! (declaration-merging → 此处 `impl Client` 块)。
3
4use super::types::{
5    CertificationStatus, GenerateSkillRequest, GenerateSkillResult, OptimizeSkillRequest,
6    OptimizeSkillResult, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem,
7    SkillStoreQuery, SkillSummary,
8};
9use crate::billing::entitlements::urlencoding;
10use crate::core::client::Client;
11use crate::core::http::{
12    parse_http_error_with_retry_after, read_limited_result as read_limited,
13    read_limited_text_result as read_limited_text, CHAT_REQUEST_TIMEOUT_MS, MAX_DOWNLOAD_SIZE,
14    MAX_ERROR_BODY_SIZE,
15};
16use crate::shared::{ApiResponse, Error, Result};
17use tokio_util::sync::CancellationToken;
18
19/// 技能 ZIP 下载/上传超时(5min,大文件)。
20const SKILL_TRANSFER_TIMEOUT_MS: u64 = 5 * 60 * 1000;
21
22/// 技能 ZIP 下载结果。对应 TS `{ data, filename }`。
23#[derive(Debug, Clone)]
24pub struct SkillDownload {
25    pub data: Vec<u8>,
26    pub filename: String,
27}
28
29impl Client {
30    /// 浏览技能商店(公共端点,无需认证)。对应 TS `browseSkillStore`。
31    pub async fn browse_skill_store(
32        &self,
33        query: &SkillStoreQuery,
34        signal: Option<CancellationToken>,
35    ) -> Result<Vec<SkillStoreItem>> {
36        let resp = self
37            .browse_skills(
38                1,
39                50,
40                query.category.as_deref().unwrap_or(""),
41                query.keyword.as_deref().unwrap_or(""),
42                query.tag.as_deref().unwrap_or(""),
43                "",
44                signal,
45            )
46            .await?;
47        Ok(resp.items)
48    }
49
50    /// 浏览公共技能商店(V3 分页接口)。对应 TS `browseSkills`。
51    #[allow(clippy::too_many_arguments)]
52    pub async fn browse_skills(
53        &self,
54        page: i64,
55        page_size: i64,
56        category: &str,
57        keyword: &str,
58        tag: &str,
59        source: &str,
60        signal: Option<CancellationToken>,
61    ) -> Result<SkillBrowseResponse> {
62        let qs = build_skill_query(page, page_size, category, keyword, tag, source, false);
63        let env: ApiResponse<SkillBrowseResponse> = self
64            .do_public_json_full(&format!("/skill-store?{qs}"), signal)
65            .await?;
66        unwrap_public(&env)
67    }
68
69    /// 轻量浏览公共技能商店(fields=minimal,响应体积缩减 90%+)。对应 TS `browseSkillsList`。
70    #[allow(clippy::too_many_arguments)]
71    pub async fn browse_skills_list(
72        &self,
73        page: i64,
74        page_size: i64,
75        category: &str,
76        keyword: &str,
77        tag: &str,
78        source: &str,
79        signal: Option<CancellationToken>,
80    ) -> Result<SkillBrowseListResponse> {
81        let qs = build_skill_query(page, page_size, category, keyword, tag, source, true);
82        let env: ApiResponse<SkillBrowseListResponse> = self
83            .do_public_json_full(&format!("/skill-store?{qs}"), signal)
84            .await?;
85        unwrap_public(&env)
86    }
87
88    /// 获取技能商店中某个技能的详情(公共端点)。对应 TS `getSkillDetail`。
89    pub async fn get_skill_detail(
90        &self,
91        skill_id: &str,
92        signal: Option<CancellationToken>,
93    ) -> Result<SkillStoreItem> {
94        let env: ApiResponse<SkillStoreItem> = self
95            .do_public_json_full(&format!("/skill-store/{}", urlencoding(skill_id)), signal)
96            .await?;
97        unwrap_public(&env)
98    }
99
100    /// 按 key 精确查找公共技能(公共端点)。对应 TS `resolveSkill`。
101    pub async fn resolve_skill(
102        &self,
103        key: &str,
104        signal: Option<CancellationToken>,
105    ) -> Result<SkillStoreItem> {
106        let env: ApiResponse<SkillStoreItem> = self
107            .do_public_json_full(
108                &format!("/skill-store/resolve/{}", urlencoding(key)),
109                signal,
110            )
111            .await?;
112        unwrap_public(&env)
113    }
114
115    /// 安装技能到当前用户的租户空间(需 OAuth scope: skill_store)。对应 TS `installSkill`。
116    pub async fn install_skill(
117        &self,
118        skill_id: &str,
119        signal: Option<CancellationToken>,
120    ) -> Result<SkillStoreItem> {
121        self.billing_post(
122            &format!("/skill-store/{}/install", urlencoding(skill_id)),
123            signal,
124        )
125        .await
126    }
127
128    /// 下载技能 ZIP 包(公共端点,双模式)。对应 TS `downloadSkill`。
129    ///
130    /// 有 token 时自动附带(享受无限流),无 token 时匿名(受限流)。
131    /// 50MB 上限走 [`MAX_DOWNLOAD_SIZE`] + [`crate::core::http::read_limited_result`];限流时抛 [`Error::RateLimit`]。
132    pub async fn download_skill(
133        &self,
134        skill_id: &str,
135        signal: Option<CancellationToken>,
136    ) -> Result<SkillDownload> {
137        // 5min 超时(大文件下载):派生子 token,超时或 parent 取消任一触发即 abort。
138        let ctl = self.derive_timeout_token(SKILL_TRANSFER_TIMEOUT_MS, signal);
139
140        let path = format!("/skill-store/{}/download", urlencoding(skill_id));
141        let url = self.api_url(&path);
142
143        // 公共端点允许无 token:拿不到 token 时匿名访问。
144        let mut rb = self.http().get(&url).cancel(ctl.clone()).context(
145            crate::core::transport::HttpContext::buffered(
146                crate::core::transport::HttpPurpose::Transfer,
147                SKILL_TRANSFER_TIMEOUT_MS,
148            ),
149        );
150        let token_result = self.ensure_token(ctl.clone()).await;
151        let token_result = if self.uses_strict_authority() {
152            Ok(token_result?)
153        } else {
154            token_result
155        };
156        if let Ok(token) = token_result {
157            if !token.is_empty() {
158                rb = rb.header(http::header::AUTHORIZATION, format!("Bearer {token}"));
159            }
160        }
161
162        let send = rb.send();
163        let resp = match &ctl {
164            Some(c) => tokio::select! {
165                r = send => r,
166                _ = c.cancelled() => return Err(Error::other("download skill: aborted")),
167            },
168            None => send.await,
169        }?;
170
171        let status = resp.status();
172        if status.as_u16() == 429 {
173            let retry_after = resp
174                .headers()
175                .get(http::header::RETRY_AFTER)
176                .and_then(|v| v.to_str().ok())
177                .unwrap_or("")
178                .to_string();
179            let body_text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
180            return Err(Error::rate_limit(
181                "匿名下载已达限制",
182                retry_after,
183                body_text,
184            ));
185        }
186
187        if !status.is_success() {
188            let body = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
189            let he = parse_http_error_with_retry_after(status.as_u16(), &body, 0);
190            return Err(Error::other(format!("download skill: {he}")));
191        }
192
193        let headers = resp.headers().clone();
194        // 读至 MAX_DOWNLOAD_SIZE + 1:超过即超限报错(对齐 TS)。
195        let data = read_limited(resp.bytes_stream(), MAX_DOWNLOAD_SIZE + 1).await?;
196        if data.len() > MAX_DOWNLOAD_SIZE {
197            return Err(Error::other(format!(
198                "download skill: response exceeds {}MB limit",
199                MAX_DOWNLOAD_SIZE >> 20
200            )));
201        }
202
203        let filename = parse_content_disposition_filename(&headers);
204        Ok(SkillDownload { data, filename })
205    }
206
207    /// 上传技能 ZIP 包。对应 TS `uploadSkill`。
208    ///
209    /// - `scope`:`"TENANT"`。
210    /// - `intent`:`"PERSONAL"`(仅自己用)或 `"PUBLIC_INTENT"`(走认证→公开)。
211    pub async fn upload_skill(
212        &self,
213        zip_data: Vec<u8>,
214        scope: &str,
215        intent: &str,
216        signal: Option<CancellationToken>,
217    ) -> Result<SkillStoreItem> {
218        self.upload_skill_internal(&zip_data, scope, intent, false, signal)
219            .await
220    }
221
222    #[cfg(not(feature = "native-http"))]
223    async fn upload_skill_internal(
224        &self,
225        _data: &[u8],
226        _scope: &str,
227        _intent: &str,
228        _retried: bool,
229        _signal: Option<CancellationToken>,
230    ) -> Result<SkillStoreItem> {
231        Err(crate::core::TransportError::UnsupportedBody.into())
232    }
233
234    #[cfg(feature = "native-http")]
235    async fn upload_skill_internal(
236        &self,
237        zip_data: &[u8],
238        scope: &str,
239        intent: &str,
240        retried: bool,
241        signal: Option<CancellationToken>,
242    ) -> Result<SkillStoreItem> {
243        let ctl = self.derive_timeout_token(SKILL_TRANSFER_TIMEOUT_MS, signal.clone());
244        let token = self.ensure_token(ctl.clone()).await?;
245
246        // multipart/form-data(对齐 Go mime/multipart)。
247        let part = reqwest::multipart::Part::bytes(zip_data.to_vec())
248            .file_name("skill.zip")
249            .mime_str("application/zip")
250            .map_err(|e| Error::other(format!("upload: build part: {e}")))?;
251        let form = reqwest::multipart::Form::new()
252            .text("scope", scope.to_string())
253            .text("intent", intent.to_string())
254            .part("file", part);
255
256        let url = self.api_url("/skill-store/upload");
257        let send = self
258            .http()
259            .post(&url)
260            .cancel(ctl.clone())
261            .context(crate::core::transport::HttpContext::buffered(
262                crate::core::transport::HttpPurpose::Transfer,
263                SKILL_TRANSFER_TIMEOUT_MS,
264            ))
265            .header(http::header::AUTHORIZATION, format!("Bearer {token}"))
266            .multipart(form)
267            .send();
268        let resp = match &ctl {
269            Some(c) => tokio::select! {
270                r = send => r,
271                _ = c.cancelled() => return Err(Error::other("upload: aborted".to_string())),
272            },
273            None => send.await,
274        }?;
275
276        // 401:单次 force_refresh 重试(防递归)。
277        if resp.status().as_u16() == 401 && !retried {
278            drop(resp);
279            self.force_refresh(ctl.clone()).await.map_err(|e| {
280                Error::other(format!("upload: unauthorized and refresh failed: {e}"))
281            })?;
282            return Box::pin(self.upload_skill_internal(zip_data, scope, intent, true, signal))
283                .await;
284        }
285
286        if !resp.status().is_success() {
287            let status = resp.status().as_u16();
288            let body = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
289            let he = parse_http_error_with_retry_after(status, &body, 0);
290            return Err(Error::other(format!("upload: {he}")));
291        }
292
293        // 响应形状:`{ data: { skill: SkillStoreItem } }`。
294        let text = resp
295            .text()
296            .await
297            .map_err(|e| Error::other(format!("upload: read body: {e}")))?;
298        let env: ApiResponse<UploadData> = serde_json::from_str(&text)
299            .map_err(|e| Error::other(format!("upload: decode: {e}")))?;
300        if let Some(err) = env.business_error() {
301            return Err(err);
302        }
303        Ok(env.data.skill)
304    }
305
306    /// 获取技能统计概览。对应 TS `getSkillSummary`。
307    pub async fn get_skill_summary(
308        &self,
309        signal: Option<CancellationToken>,
310    ) -> Result<SkillSummary> {
311        self.billing_get("/skills/summary", signal).await
312    }
313
314    /// 触发技能认证管线(异步)。对应 TS `certifySkill`。
315    pub async fn certify_skill(
316        &self,
317        skill_id: &str,
318        signal: Option<CancellationToken>,
319    ) -> Result<()> {
320        // POST 端点返回 ApiResponse<unknown>,只需确认成功(业务码检查)。
321        let _: serde_json::Value = self
322            .billing_post(
323                &format!("/skill-store/{}/certify", urlencoding(skill_id)),
324                signal,
325            )
326            .await?;
327        Ok(())
328    }
329
330    /// 查询技能认证状态。对应 TS `getCertificationStatus`。
331    pub async fn get_certification_status(
332        &self,
333        skill_id: &str,
334        signal: Option<CancellationToken>,
335    ) -> Result<CertificationStatus> {
336        self.billing_get(
337            &format!("/skill-store/{}/certification", urlencoding(skill_id)),
338            signal,
339        )
340        .await
341    }
342
343    /// 根据自然语言描述生成技能定义(基于独立 LLM)。对应 TS `generateSkill`。
344    pub async fn generate_skill(
345        &self,
346        req: &GenerateSkillRequest,
347        signal: Option<CancellationToken>,
348    ) -> Result<GenerateSkillResult> {
349        let body = serde_json::to_string(req)
350            .map_err(|e| Error::other(format!("serialize generate request: {e}")))?;
351        self.billing_post_body_with_timeout(
352            "/skill-generator/generate",
353            Some(&body),
354            signal,
355            CHAT_REQUEST_TIMEOUT_MS,
356        )
357        .await
358    }
359
360    /// 优化已有技能定义。对应 TS `optimizeSkill`。
361    pub async fn optimize_skill(
362        &self,
363        req: &OptimizeSkillRequest,
364        signal: Option<CancellationToken>,
365    ) -> Result<OptimizeSkillResult> {
366        let body = serde_json::to_string(req)
367            .map_err(|e| Error::other(format!("serialize optimize request: {e}")))?;
368        self.billing_post_body_with_timeout(
369            "/skill-generator/optimize",
370            Some(&body),
371            signal,
372            CHAT_REQUEST_TIMEOUT_MS,
373        )
374        .await
375    }
376
377    /// 校验技能定义正确性。对应 TS `validateSkill`。
378    pub async fn validate_skill(
379        &self,
380        skill_name: &str,
381        signal: Option<CancellationToken>,
382    ) -> Result<()> {
383        let body = serde_json::json!({ "skillName": skill_name }).to_string();
384        let _: serde_json::Value = self
385            .billing_post_body_with_timeout(
386                "/skill-generator/validate",
387                Some(&body),
388                signal,
389                CHAT_REQUEST_TIMEOUT_MS,
390            )
391            .await?;
392        Ok(())
393    }
394}
395
396/// 上传响应内层 `data.skill`。
397#[derive(serde::Deserialize)]
398#[cfg(feature = "native-http")]
399struct UploadData {
400    skill: SkillStoreItem,
401}
402
403/// `ApiResponse<T>` → `data`(公共端点;`code != 0` 抛 BusinessError)。
404fn unwrap_public<T: Clone>(env: &ApiResponse<T>) -> Result<T> {
405    if let Some(err) = env.business_error() {
406        return Err(err);
407    }
408    Ok(env.data.clone())
409}
410
411/// 构造 skill-store 浏览 query string(对应 TS URLSearchParams 序列;仅非空键写入)。
412fn build_skill_query(
413    page: i64,
414    page_size: i64,
415    category: &str,
416    keyword: &str,
417    tag: &str,
418    source: &str,
419    minimal: bool,
420) -> String {
421    let mut parts: Vec<String> = vec![format!("page={page}"), format!("pageSize={page_size}")];
422    if minimal {
423        parts.push("fields=minimal".to_string());
424    }
425    if !category.is_empty() {
426        parts.push(format!("category={}", urlencoding(category)));
427    }
428    if !keyword.is_empty() {
429        parts.push(format!("keyword={}", urlencoding(keyword)));
430    }
431    if !tag.is_empty() {
432        parts.push(format!("tag={}", urlencoding(tag)));
433    }
434    if !source.is_empty() {
435        parts.push(format!("source={}", urlencoding(source)));
436    }
437    parts.join("&")
438}
439
440/// 从 `Content-Disposition` 头提取 filename(对应 TS 的简易解析;默认 `skill.zip`)。
441fn parse_content_disposition_filename(headers: &http::header::HeaderMap) -> String {
442    let default = "skill.zip".to_string();
443    let cd = match headers
444        .get(http::header::CONTENT_DISPOSITION)
445        .and_then(|v| v.to_str().ok())
446    {
447        Some(s) => s,
448        None => return default,
449    };
450    let idx = match cd.find("filename") {
451        Some(i) => i,
452        None => return default,
453    };
454    let tail = &cd[idx..];
455    // split('=', 2):取 `=` 后第一段。
456    let parts: Vec<&str> = tail.splitn(2, '=').collect();
457    if parts.len() != 2 {
458        return default;
459    }
460    let trimmed = parts[1]
461        .trim()
462        .trim_matches(|c| c == '"' || c == '\'' || c == ' ');
463    if trimmed.is_empty() {
464        default
465    } else {
466        trimmed.to_string()
467    }
468}