Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(skills): 支持服务端导入 Git 技能 (#4957)

bot-of-qin-ctxfafccb1c2bb3
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index bd8b1c5fc..b53e0c492 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -1,5 +1,5 @@
use serde::de::DeserializeOwned;
-use serde_json::{Map, Value};
+use serde_json::{Map, Value, json};
use std::env;
use std::path::Path;
@@ -1004,85 +1004,48 @@ impl HttpClient {
verbose: bool,
source_metadata: Option<Value>,
target_uri: Option<&str>,
+ skills: &[String],
+ list_only: bool,
) -> Result<serde_json::Value> {
- let path_obj = Path::new(data);
-
- if path_obj.exists() {
- if path_obj.is_dir() {
- let zip_file = if show_progress {
- self.zip_directory_with_progress(path_obj, verbose, None)?
- } else {
- self.zip_directory(path_obj, None)?
- };
- let temp_file_id = if show_progress {
- self.upload_temp_file_with_progress(zip_file.path(), verbose)
- .await?
- } else {
- self.upload_temp_file(zip_file.path()).await?
- };
-
- let mut body = serde_json::json!({
- "temp_file_id": temp_file_id,
- "wait": wait,
- });
- if let Some(source_metadata) = source_metadata.clone() {
- body["source_metadata"] = source_metadata;
- }
- if let Some(target_uri) = target_uri {
- body["target_uri"] = serde_json::Value::String(target_uri.to_string());
- }
- let dynamic_timeout =
- TimeoutConfig::for_resource_processing().calculate(zip_file.path())?;
- self.base
- .post_with_timeout("/api/v1/skills", &body, dynamic_timeout)
- .await
- } else if path_obj.is_file() {
- let temp_file_id = if show_progress {
- self.upload_temp_file_with_progress(path_obj, verbose)
- .await?
+ let path = Path::new(data);
+ let mut body = json!({"wait": wait});
+ if !skills.is_empty() {
+ body["skills"] = json!(skills);
+ }
+ if list_only {
+ body["list_only"] = json!(true);
+ }
+ if let Some(target_uri) = target_uri {
+ body["target_uri"] = json!(target_uri);
+ }
+ if let Some(metadata) = source_metadata {
+ body["source_metadata"] = metadata;
+ } else if path.exists() {
+ body["source_metadata"] = json!({"type": "local", "source": data, "path": data});
+ }
+ if path.is_dir() || path.is_file() {
+ let archive = if path.is_dir() {
+ Some(if show_progress {
+ self.zip_directory_with_progress(path, verbose, None)?
} else {
- self.upload_temp_file(path_obj).await?
- };
-
- let mut body = serde_json::json!({
- "temp_file_id": temp_file_id,
- "wait": wait,
- });
- if let Some(source_metadata) = source_metadata.clone() {
- body["source_metadata"] = source_metadata;
- }
- if let Some(target_uri) = target_uri {
- body["target_uri"] = serde_json::Value::String(target_uri.to_string());
- }
- let dynamic_timeout =
- TimeoutConfig::for_resource_processing().calculate(path_obj)?;
- self.base
- .post_with_timeout("/api/v1/skills", &body, dynamic_timeout)
- .await
+ self.zip_directory(path, None)?
+ })
} else {
- let mut body = serde_json::json!({
- "data": data,
- "wait": wait,
- });
- if let Some(source_metadata) = source_metadata.clone() {
- body["source_metadata"] = source_metadata;
- }
- if let Some(target_uri) = target_uri {
- body["target_uri"] = serde_json::Value::String(target_uri.to_string());
- }
- self.post("/api/v1/skills", &body).await
- }
+ None
+ };
+ let upload = archive.as_ref().map(|file| file.path()).unwrap_or(path);
+ let id = if show_progress {
+ self.upload_temp_file_with_progress(upload, verbose).await?
+ } else {
+ self.upload_temp_file(upload).await?
+ };
+ body["temp_file_id"] = json!(id);
+ let dynamic_timeout = TimeoutConfig::for_resource_processing().calculate(upload)?;
+ self.base
+ .post_with_timeout("/api/v1/skills", &body, dynamic_timeout)
+ .await
} else {
- let mut body = serde_json::json!({
- "data": data,
- "wait": wait,
- });
- if let Some(source_metadata) = source_metadata {
- body["source_metadata"] = source_metadata;
- }
- if let Some(target_uri) = target_uri {
- body["target_uri"] = serde_json::Value::String(target_uri.to_string());
- }
+ body["data"] = json!(data);
self.post("/api/v1/skills", &body).await
}
}
@@ -2315,8 +2278,7 @@ mod tests {
assert!(!request.contains("include_mod_time_iso="));
let (default_url, default_request_rx) = spawn_request_capture_server().await;
- let default_client =
- HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
+ let default_client = HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
default_client
.ls(
"viking://resources",
@@ -2507,8 +2469,7 @@ mod tests {
assert!(!request.contains("include_mod_time_iso="));
let (default_url, default_request_rx) = spawn_request_capture_server().await;
- let default_client =
- HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
+ let default_client = HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
default_client
.tree(
"viking://resources",
diff --git a/crates/ov_cli/src/commands/skills.rs b/crates/ov_cli/src/commands/skills.rs
index f3c76ae95..07c82a314 100644
--- a/crates/ov_cli/src/commands/skills.rs
+++ b/crates/ov_cli/src/commands/skills.rs
@@ -7,43 +7,10 @@ use crate::terminal_ui::{
};
use crate::theme;
use colored::Colorize;
-use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use std::collections::BTreeSet;
use std::io::{self, IsTerminal, Write};
-use std::path::{Component, Path, PathBuf};
-use std::process::Command;
-use tempfile::TempDir;
-use url::Url;
-
-enum PreparedSource {
- Raw(String),
- Path {
- path: PathBuf,
- _temp_dir: Option<TempDir>,
- origin: SourceOrigin,
- },
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct GitSource {
- clone_url: String,
- ref_name: Option<String>,
- subdir: Option<PathBuf>,
-}
-
-#[derive(Debug, Clone)]
-enum SourceOrigin {
- Local { source: String },
- Git(GitSource),
-}
-
-#[derive(Debug)]
-struct AddTarget {
- data: String,
- source: Option<SkillSourceRecord>,
- _temp_dir: Option<TempDir>,
-}
+use std::path::Path;
#[derive(Debug, Clone)]
struct InstalledSkillSummary {
@@ -51,34 +18,6 @@ struct InstalledSkillSummary {
description: String,
}
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-struct SkillSourceRecord {
- #[serde(rename = "type")]
- source_type: String,
- #[serde(skip_serializing_if = "Option::is_none")]
- source: Option<String>,
- #[serde(skip_serializing_if = "Option::is_none")]
- path: Option<String>,
- #[serde(skip_serializing_if = "Option::is_none")]
- clone_url: Option<String>,
- #[serde(skip_serializing_if = "Option::is_none")]
- ref_name: Option<String>,
- #[serde(skip_serializing_if = "Option::is_none")]
- subdir: Option<String>,
- #[serde(skip_serializing_if = "Option::is_none")]
- skill_name: Option<String>,
-}
-
-impl PreparedSource {
- fn path(&self) -> Option<&Path> {
- match self {
- Self::Path { path, .. } => Some(path.as_path()),
- Self::Raw(_) => None,
- }
- }
-}
-
pub async fn add(
client: &HttpClient,
data: &str,
@@ -92,44 +31,51 @@ pub async fn add(
compact: bool,
parent: Option<&str>,
) -> Result<()> {
- let source = prepare_source(data)?;
- if list_only {
- return list_source_skills(&source, output_format, compact);
- }
-
- let targets = resolve_add_targets(&source, &skill_names)?;
- if targets.is_empty() {
- return Err(Error::Client("No skills to install.".to_string()));
- }
- if targets.len() > 1 && !yes {
- let names = targets.iter().map(skill_target_label).collect::<Vec<_>>();
- if !confirm_action("Install", &names)? {
- output_message_result(
- serde_json::json!({ "cancelled": true, "skills": names }),
- "Aborted.".to_string(),
- output_format,
- compact,
- );
- return Ok(());
- }
- }
-
- let mut installed = Vec::new();
-
- for target in targets {
- let source_metadata = source_record_value(target.source.as_ref())?;
- let result = client
+ if list_only || (!yes && !data.contains('\n')) {
+ let listing = client
.add_skill(
- &target.data,
- wait,
+ data,
+ false,
show_progress,
verbose,
- source_metadata,
+ None,
parent,
+ &skill_names,
+ true,
)
.await?;
- installed.push(result);
+ if list_only {
+ output_success(listing, output_format, compact);
+ return Ok(());
+ }
+ let names = listing["skills"]
+ .as_array()
+ .ok_or_else(|| Error::Parse("Invalid skill source listing".into()))?
+ .iter()
+ .filter_map(|skill| skill["path"].as_str().map(String::from))
+ .collect::<Vec<_>>();
+ if names.len() > 1 && !confirm_action("Install", &names)? {
+ output_message_result(
+ json!({"cancelled": true, "skills": names}),
+ "Aborted.".into(),
+ output_format,
+ compact,
+ );
+ return Ok(());
+ }
}
+ let result = client
+ .add_skill(
+ data,
+ wait,
+ show_progress,
+ verbose,
+ None,
+ parent,
+ &skill_names,
+ false,
+ )
+ .await?;
if !wait && matches!(output_format, OutputFormat::Table) {
eprintln!("Note: Skill processing may continue in the background.");
@@ -138,19 +84,7 @@ pub async fn add(
);
}
- if installed.len() == 1 {
- output_success(installed.remove(0), output_format, compact);
- } else {
- let total = installed.len();
- output_success(
- serde_json::json!({
- "installed": installed,
- "total": total,
- }),
- output_format,
- compact,
- );
- }
+ output_success(result, output_format, compact);
Ok(())
}
@@ -244,31 +178,35 @@ pub async fn update(
let mut updated = Vec::new();
let mut skipped = Vec::new();
for name in names {
- let update_target = match resolve_update_target(client, &name, !update_all).await {
- Ok(target) => target,
+ let result = async {
+ let detail = client.skill_show(&name, false, false, true, Some(0), parent).await?;
+ if detail["source"]["type"].as_str() == Some("git") {
+ let mut body = json!({"from_source": true, "wait": wait});
+ if let Some(parent) = parent {
+ body["target_uri"] = json!(parent);
+ }
+ client.put(&format!("/api/v1/skills/{}", name), &body).await
+ } else if !update_all && can_prompt() {
+ print!("Source for skill '{}' is not a Git source. Enter a local path or Git URL (blank to abort): ", name);
+ io::stdout().flush()?;
+ let mut input = String::new();
+ io::stdin().read_line(&mut input)?;
+ let data = input.trim();
+ if data.is_empty() {
+ return Err(Error::Client("No update source supplied.".into()));
+ }
+ client.skill_update(&name, data, wait, None, false, false, None, parent).await
+ } else {
+ Err(Error::Client(format!("Skill '{}' has no recorded Git source; supply a local path or Git URL interactively.", name)))
+ }
+ }.await;
+ match result {
+ Ok(result) => updated.push(result),
Err(error) if update_all => {
- skipped.push(json!({
- "name": name,
- "reason": error.to_string(),
- }));
- continue;
+ skipped.push(json!({"name": name, "reason": error.to_string()}))
}
Err(error) => return Err(error),
- };
- let source_metadata = source_record_value(update_target.source.as_ref())?;
- let result = client
- .skill_update(
- &name,
- &update_target.data,
- wait,
- None,
- false,
- false,
- source_metadata,
- parent,
- )
- .await?;
- updated.push(result);
+ }
}
let total = updated.len();
let skipped_total = skipped.len();
@@ -720,579 +658,6 @@ fn output_skill_validate_success(result: &Value, output_format: OutputFormat, co
println!("{}", lines.join("\n"));
}
-fn prepare_source(data: &str) -> Result<PreparedSource> {
- let path = Path::new(data);
- if path.exists() {
- return Ok(PreparedSource::Path {
- path: path.to_path_buf(),
- _temp_dir: None,
- origin: SourceOrigin::Local {
- source: data.to_string(),
- },
- });
- }
- if let Some(git_source) = parse_git_source(data) {
- return prepare_git_source(git_source);
- }
- Ok(PreparedSource::Raw(data.to_string()))
-}
-
-fn prepare_git_source(git_source: GitSource) -> Result<PreparedSource> {
- let temp_dir = tempfile::tempdir()?;
- let status = Command::new("git")
- .arg("clone")
- .arg("--depth")
- .arg("1")
- .args(
- git_source
- .ref_name
- .iter()
- .flat_map(|ref_name| ["--branch", ref_name.as_str()]),
- )
- .arg(&git_source.clone_url)
- .arg(temp_dir.path())
- .status()
- .map_err(|e| Error::Client(format!("Failed to run git clone: {}", e)))?;
- if !status.success() {
- return Err(Error::Client(format!(
- "Failed to clone skill source: {}",
- git_source.clone_url
- )));
- }
- let path = if let Some(subdir) = git_source.subdir.as_ref() {
- let normalized_subdir = normalize_git_subdir(subdir)?;
- let repo_root = std::fs::canonicalize(temp_dir.path()).map_err(|e| {
- Error::Client(format!(
- "Failed to resolve cloned repository root '{}': {}",
- temp_dir.path().display(),
- e
- ))
- })?;
- let requested_path = temp_dir.path().join(&normalized_subdir);
- let canonical_path = std::fs::canonicalize(&requested_path).map_err(|e| {
- Error::Client(format!(
- "Skill path '{}' was not found in cloned repository '{}': {}",
- normalized_subdir.display(),
- git_source.clone_url,
- e
- ))
- })?;
- if !canonical_path.starts_with(&repo_root) {
- return Err(Error::Client(format!(
- "Git skill subdir '{}' escapes cloned repository '{}'.",
- normalized_subdir.display(),
- git_source.clone_url
- )));
- }
- canonical_path
- } else {
- temp_dir.path().to_path_buf()
- };
- Ok(PreparedSource::Path {
- path,
- _temp_dir: Some(temp_dir),
- origin: SourceOrigin::Git(git_source),
- })
-}
-
-fn normalize_git_subdir(subdir: &Path) -> Result<PathBuf> {
- let mut normalized = PathBuf::new();
- for component in subdir.components() {
- match component {
- Component::Normal(part) => normalized.push(part),
- Component::CurDir => {}
- Component::ParentDir => {
- return Err(Error::Parse(format!(
- "Git source metadata contains unsafe subdir '{}': parent directory components are not allowed.",
- subdir.display()
- )));
- }
- Component::RootDir | Component::Prefix(_) => {
- return Err(Error::Parse(format!(
- "Git source metadata contains absolute subdir '{}', which is not allowed.",
- subdir.display()
- )));
- }
- }
- }
-
- if normalized.as_os_str().is_empty() {
- return Err(Error::Parse(
- "Git source metadata missing subdir".to_string(),
- ));
- }
-
- Ok(normalized)
-}
-
-fn parse_git_source(data: &str) -> Option<GitSource> {
- if let Some(source) = parse_github_tree_source(data) {
- return Some(source);
- }
- let is_plain_git_source = data.starts_with("git@")
- || data.starts_with("ssh://")
- || data.starts_with("git://")
- || ((data.starts_with("https://") || data.starts_with("http://"))
- && (data.ends_with(".git")
- || data.contains("github.com/")
- || data.contains("gitlab.com/")
- || data.contains("bitbucket.org/")));
- is_plain_git_source.then(|| GitSource {
- clone_url: data.to_string(),
- ref_name: None,
- subdir: None,
- })
-}
-
-fn parse_github_tree_source(data: &str) -> Option<GitSource> {
- let url = Url::parse(data).ok()?;
- if url.host_str()? != "github.com" {
- return None;
- }
-
- let segments = url.path_segments()?.collect::<Vec<_>>();
- if segments.len() < 5 || segments.get(2) != Some(&"tree") {
- return None;
- }
-
- let owner = segments[0];
- let repo = segments[1].trim_end_matches(".git");
- let (branch, subdir_segments) = split_github_tree_ref_and_subdir(&segments)?;
- let subdir = subdir_segments
- .iter()
- .fold(PathBuf::new(), |mut path, segment| {
- path.push(segment);
- path
- });
- if owner.is_empty() || repo.is_empty() || branch.is_empty() || subdir.as_os_str().is_empty() {
- return None;
- }
-
- Some(GitSource {
- clone_url: format!("https://github.com/{owner}/{repo}.git"),
- ref_name: Some(branch),
- subdir: Some(subdir),
- })
-}
-
-fn split_github_tree_ref_and_subdir(segments: &[&str]) -> Option<(String, Vec<String>)> {
- if segments.len() < 5 {
- return None;
- }
- let default_branch = segments[3];
- let default_subdir = &segments[4..];
- if default_branch.is_empty() || default_subdir.is_empty() {
- return None;
- }
-
- if let Some(skill_root_index) = segments[4..]
- .iter()
- .position(|segment| *segment == "skills")
- {
- let split_at = 4 + skill_root_index;
- let branch = segments[3..split_at].join("/");
- let subdir = segments[split_at..]
- .iter()
- .map(|segment| (*segment).to_string())
- .collect::<Vec<_>>();
- if !branch.is_empty() && !subdir.is_empty() {
- return Some((branch, subdir));
- }
- }
-
- Some((
- default_branch.to_string(),
- default_subdir
- .iter()
- .map(|segment| (*segment).to_string())
- .collect::<Vec<_>>(),
- ))
-}
-
-fn resolve_add_targets(source: &PreparedSource, skill_names: &[String]) -> Result<Vec<AddTarget>> {
- if skill_names.is_empty() {
- return match source {
- PreparedSource::Raw(data) => Ok(vec![AddTarget {
- data: data.clone(),
- source: None,
- _temp_dir: None,
- }]),
- PreparedSource::Path { path, .. } => resolve_default_add_targets(source, path),
- };
- }
-
- let Some(root) = source.path() else {
- return Err(Error::Client(
- "--skill can only be used with a local or git skill source.".to_string(),
- ));
- };
- if !root.is_dir() {
- return Err(Error::Client(
- "--skill requires a directory source.".to_string(),
- ));
- }
-
- let requested = normalize_skill_names(skill_names.to_vec())?;
- if requested.iter().any(|name| name == "*") {
- if requested.len() > 1 {
- return Err(Error::Client(
- "Use --skill '*' by itself when installing all skills.".to_string(),
- ));
- }
- let targets = discover_skill_dirs(root)?;
- if targets.is_empty() {
- return Err(Error::Client(format!(
- "No skill directories found under '{}'.",
- root.display()
- )));
- }
- return targets
- .into_iter()
- .map(|path| add_target_from_path(source, root, path))
- .collect();
- }
-
- requested
- .into_iter()
- .map(|name| {
- resolve_named_skill_dir(root, &name)
- .and_then(|path| add_target_from_path(source, root, path))
- })
- .collect()
-}
-
-fn resolve_default_add_targets(source: &PreparedSource, path: &Path) -> Result<Vec<AddTarget>> {
- if !path.is_dir() {
- return Ok(vec![add_target_from_path(
- source,
- path,
- path.to_path_buf(),
- )?]);
- }
- if path.join("SKILL.md").is_file() {
- return Ok(vec![add_target_from_path(
- source,
- path,
- path.to_path_buf(),
- )?]);
- }
-
- let targets = discover_skill_dirs(path)?;
- if targets.is_empty() {
- return Err(Error::Client(format!(
- "SKILL.md not found in '{}'.",
- path.display()
- )));
- }
- targets
- .into_iter()
- .map(|target| add_target_from_path(source, path, target))
- .collect()
-}
-
-fn add_target_from_path(
- source: &PreparedSource,
- root: &Path,
- target: PathBuf,
-) -> Result<AddTarget> {
- Ok(AddTarget {
- data: path_to_string(&target),
- source: source_record_for_target(source, root, &target)?,
- _temp_dir: None,
- })
-}
-
-fn source_record_for_target(
- source: &PreparedSource,
- root: &Path,
- target: &Path,
-) -> Result<Option<SkillSourceRecord>> {
- let PreparedSource::Path { origin, .. } = source else {
- return Ok(None);
- };
-
- match origin {
- SourceOrigin::Local { source } => Ok(Some(SkillSourceRecord {
- source_type: "local".to_string(),
- source: Some(source.clone()),
- path: Some(path_to_string(target)),
- clone_url: None,
- ref_name: None,
- subdir: None,
- skill_name: None,
- })),
- SourceOrigin::Git(git_source) => {
- let subdir = git_subdir_for_target(git_source.subdir.as_ref(), root, target)?;
- Ok(Some(SkillSourceRecord {
- source_type: "git".to_string(),
- source: Some(git_source_source(git_source)),
- path: None,
- clone_url: Some(git_source.clone_url.clone()),
- ref_name: git_source.ref_name.clone(),
- subdir: subdir.map(|path| path_to_string(&path)),
- skill_name: None,
- }))
- }
- }
-}
-
-fn git_subdir_for_target(
- source_subdir: Option<&PathBuf>,
- root: &Path,
- target: &Path,
-) -> Result<Option<PathBuf>> {
- let relative = target
- .strip_prefix(root)
- .ok()
- .filter(|path| !path.as_os_str().is_empty());
- let mut subdir = source_subdir.cloned().unwrap_or_default();
- if let Some(relative) = relative {
- subdir.push(relative);
- }
- if subdir.as_os_str().is_empty() {
- Ok(None)
- } else {
- Ok(Some(subdir))
- }
-}
-
-fn git_source_source(git_source: &GitSource) -> String {
- if git_source.clone_url.contains("github.com/")
- && let (Some(ref_name), Some(subdir)) = (&git_source.ref_name, &git_source.subdir)
- {
- let repo = git_source
- .clone_url
- .trim_end_matches(".git")
- .trim_start_matches("https://github.com/");
- return format!(
- "https://github.com/{}/tree/{}/{}",
- repo,
- ref_name,
- path_to_string(subdir)
- );
- }
- git_source.clone_url.clone()
-}
-
-fn list_source_skills(
- source: &PreparedSource,
- output_format: OutputFormat,
- compact: bool,
-) -> Result<()> {
- let Some(root) = source.path() else {
- return Err(Error::Client(
- "--list can only be used with a local or git skill source.".to_string(),
- ));
- };
- if !root.is_dir() {
- return Err(Error::Client(
- "--list requires a directory skill source.".to_string(),
- ));
- }
-
- let dirs = discover_skill_dirs(root)?;
- let skills = dirs
- .iter()
- .map(|dir| skill_dir_summary(dir, root))
- .collect::<Result<Vec<_>>>()?;
- output_success(
- serde_json::json!({
- "source": path_to_string(root),
- "skills": skills,
- "total": skills.len(),
- }),
- output_format,
- compact,
- );
- Ok(())
-}
-
-fn skill_dir_summary(dir: &Path, root: &Path) -> Result<Value> {
- let skill_md = dir.join("SKILL.md");
- let content = std::fs::read_to_string(&skill_md).map_err(|e| {
- Error::Client(format!(
- "Failed to read skill file '{}': {}",
- skill_md.display(),
- e
- ))
- })?;
- let parsed = parse_skill_md(&content).ok();
- let name = parsed
- .as_ref()
- .and_then(|parsed| yaml_mapping_get_str(&parsed.meta, "name"))
- .map(ToString::to_string)
- .or_else(|| {
- dir.file_name()
- .and_then(|name| name.to_str())
- .map(ToString::to_string)
- })
- .unwrap_or_default();
- let description = parsed
- .as_ref()
- .and_then(|parsed| yaml_mapping_get_str(&parsed.meta, "description"))
- .unwrap_or("")
- .to_string();
- let relative_path = dir.strip_prefix(root).unwrap_or(dir);
-
- Ok(serde_json::json!({
- "name": name,
- "description": description,
- "path": path_to_string(relative_path),
- }))
-}
-
-fn skill_target_label(target: &AddTarget) -> String {
- let path = Path::new(&target.data);
- path.file_name()
- .and_then(|name| name.to_str())
- .unwrap_or(&target.data)
- .to_string()
-}
-
-async fn resolve_update_target(
- client: &HttpClient,
- name: &str,
- allow_prompt: bool,
-) -> Result<AddTarget> {
- if let Some(record) = read_skill_source_record(client, name).await? {
- return update_target_from_record(&record, name, allow_prompt);
- }
-
- if allow_prompt && let Some(target) = prompt_update_source(name)? {
- return Ok(target);
- }
-
- Err(Error::Client(format!(
- "Skill '{}' has no recorded updateable source metadata. Reinstall it with 'ov skills add <source>' or run update interactively to provide a new source.",
- name
- )))
-}
-
-async fn read_skill_source_record(
- client: &HttpClient,
- name: &str,
-) -> Result<Option<SkillSourceRecord>> {
- let result = client
- .skill_show(name, false, false, true, Some(0), None)
- .await?;
- let Some(source) = result.get("source") else {
- return Ok(None);
- };
- if !source
- .get("tracked")
- .and_then(Value::as_bool)
- .unwrap_or(false)
- {
- return Ok(None);
- }
- let mut record: SkillSourceRecord = serde_json::from_value(source.clone())
- .map_err(|e| Error::Parse(format!("Invalid source metadata for '{}': {}", name, e)))?;
- record.skill_name = Some(name.to_string());
- Ok(Some(record))
-}
-
-fn update_target_from_record(
- record: &SkillSourceRecord,
- name: &str,
- allow_prompt: bool,
-) -> Result<AddTarget> {
- match record.source_type.as_str() {
- "git" => {
- let prepared = prepare_source_from_git_record(record)?;
- let PreparedSource::Path {
- path, _temp_dir, ..
- } = prepared
- else {
- return Err(Error::Parse(format!(
- "Skill '{}' git source did not resolve to a path",
- name
- )));
- };
- Ok(AddTarget {
- data: path_to_string(&path),
- source: Some(record.clone()),
- _temp_dir,
- })
- }
- "local" => {
- if allow_prompt {
- if let Some(target) = prompt_update_source(name)? {
- return Ok(target);
- }
- return Err(Error::Client(format!(
- "Local source metadata for skill '{}' is not trusted. Provide a local path or git source to continue.",
- name
- )));
- }
- Err(Error::Client(format!(
- "Skill '{}' was installed from a local source, but server-recorded local paths are not trusted for non-interactive update. Re-run 'ov skills update {}' interactively to provide a local path or git source.",
- name, name
- )))
- }
- other => Err(Error::Parse(format!(
- "Unsupported source type '{}' for skill '{}'",
- other, name
- ))),
- }
-}
-
-fn prepare_source_from_git_record(record: &SkillSourceRecord) -> Result<PreparedSource> {
- let clone_url = record
- .clone_url
- .as_deref()
- .ok_or_else(|| Error::Parse("Git source metadata missing clone_url".to_string()))?;
- let subdir = record
- .subdir
- .as_ref()
- .map(PathBuf::from)
- .map(|path| normalize_git_subdir(&path))
- .transpose()?;
- let git_source = GitSource {
- clone_url: clone_url.to_string(),
- ref_name: record.ref_name.clone(),
- subdir,
- };
- prepare_git_source(git_source)
-}
-
-fn prompt_update_source(name: &str) -> Result<Option<AddTarget>> {
- if !io::stdin().is_terminal() || !io::stdout().is_terminal() {
- return Ok(None);
- }
-
- print!(
- "Source for skill '{}' is missing or untracked. Enter a local path or git source to update it (blank to abort): ",
- name
- );
- io::stdout().flush()?;
-
- let mut answer = String::new();
- io::stdin().read_line(&mut answer)?;
- let source_text = answer.trim();
- if source_text.is_empty() {
- return Ok(None);
- }
- let source = prepare_source(source_text)?;
- let targets = resolve_add_targets(&source, &[name.to_string()])?;
- let mut target = targets.into_iter().next().ok_or_else(|| {
- Error::Client(format!(
- "Skill '{}' was not found in source '{}'.",
- name, source_text
- ))
- })?;
- if let PreparedSource::Path { _temp_dir, .. } = source {
- target._temp_dir = _temp_dir;
- }
- Ok(Some(target))
-}
-
-fn source_record_value(source: Option<&SkillSourceRecord>) -> Result<Option<Value>> {
- source
- .map(serde_json::to_value)
- .transpose()
- .map_err(|e| Error::Parse(format!("Failed to serialize source metadata: {}", e)))
-}
-
fn normalize_skill_names(names: Vec<String>) -> Result<Vec<String>> {
let mut seen = BTreeSet::new();
let mut out = Vec::new();
@@ -1308,45 +673,6 @@ fn normalize_skill_names(names: Vec<String>) -> Result<Vec<String>> {
Ok(out)
}
-fn discover_skill_dirs(root: &Path) -> Result<Vec<PathBuf>> {
- let mut dirs = Vec::new();
- if root.join("SKILL.md").is_file() {
- dirs.push(root.to_path_buf());
- }
- for entry in std::fs::read_dir(root)? {
- let entry = entry?;
- let path = entry.path();
- if path.is_dir() && path.join("SKILL.md").is_file() {
- dirs.push(path);
- }
- }
- dirs.sort();
- dirs.dedup();
- Ok(dirs)
-}
-
-fn resolve_named_skill_dir(root: &Path, name: &str) -> Result<PathBuf> {
- let child = root.join(name);
- if child.is_dir() && child.join("SKILL.md").is_file() {
- return Ok(child);
- }
-
- if root.join("SKILL.md").is_file()
- && root
- .file_name()
- .and_then(|value| value.to_str())
- .is_some_and(|root_name| root_name == name)
- {
- return Ok(root.to_path_buf());
- }
-
- Err(Error::Client(format!(
- "Skill '{}' was not found under '{}'.",
- name,
- root.display()
- )))
-}
-
async fn resolve_installed_skill_names(
client: &HttpClient,
requested: Vec<String>,
@@ -1617,10 +943,6 @@ fn format_name_list(names: &[String]) -> String {
)
}
-fn path_to_string(path: &Path) -> String {
- path.to_string_lossy().to_string()
-}
-
fn output_skill_show(result: &Value, output_format: OutputFormat, compact: bool) {
if matches!(output_format, OutputFormat::Table)
&& let Some(rendered) = render_skill_show_for_table(result)
@@ -1774,13 +1096,10 @@ fn output_message_result(
#[cfg(test)]
mod tests {
use super::{
- PreparedSource, RenderedSkillSelectRegion, SkillSourceRecord, SourceOrigin,
- filter_skill_show_level, parse_github_tree_source, parse_skill_md,
- prepare_source_from_git_record, render_skill_show_for_table, rendered_skill_select_rows,
- resolve_add_targets, update_target_from_record,
+ RenderedSkillSelectRegion, filter_skill_show_level, parse_skill_md,
+ render_skill_show_for_table, rendered_skill_select_rows,
};
use serde_json::json;
- use std::path::Path;
#[test]
fn skill_show_table_renders_complete_skill_information() {
@@ -1865,159 +1184,6 @@ mod tests {
assert_eq!(parsed.body, "# Demo");
}
- #[test]
- fn github_tree_skill_url_resolves_to_repo_and_subdir() {
- let source = parse_github_tree_source(
- "https://github.com/anthropics/skills/tree/main/skills/algorithmic-art",
- )
- .expect("github tree source");
-
- assert_eq!(source.clone_url, "https://github.com/anthropics/skills.git");
- assert_eq!(source.ref_name.as_deref(), Some("main"));
- assert_eq!(
- source.subdir.as_deref(),
- Some(Path::new("skills/algorithmic-art"))
- );
- }
-
- #[test]
- fn github_tree_skill_url_supports_slash_branch_before_skills_dir() {
- let source = parse_github_tree_source(
- "https://github.com/acme/skills/tree/feature/foo/skills/demo-skill",
- )
- .expect("github tree source");
-
- assert_eq!(source.clone_url, "https://github.com/acme/skills.git");
- assert_eq!(source.ref_name.as_deref(), Some("feature/foo"));
- assert_eq!(
- source.subdir.as_deref(),
- Some(Path::new("skills/demo-skill"))
- );
- }
-
- #[test]
- fn update_target_rejects_api_source_record_without_prompt() {
- let record = SkillSourceRecord {
- source_type: "api".to_string(),
- source: Some("inline_content".to_string()),
- path: None,
- clone_url: None,
- ref_name: None,
- subdir: None,
- skill_name: Some("api-skill".to_string()),
- };
-
- let error = update_target_from_record(&record, "api-skill", false)
- .expect_err("api source should not be directly updateable");
- assert!(
- error
- .to_string()
- .contains("Unsupported source type 'api' for skill 'api-skill'")
- );
- }
-
- #[test]
- fn update_target_rejects_local_source_record_without_prompt() {
- let record = SkillSourceRecord {
- source_type: "local".to_string(),
- source: Some("/tmp/demo-skill".to_string()),
- path: Some("/tmp/demo-skill".to_string()),
- clone_url: None,
- ref_name: None,
- subdir: None,
- skill_name: Some("local-skill".to_string()),
- };
-
- let error = update_target_from_record(&record, "local-skill", false)
- .expect_err("local source should not be trusted for non-interactive update");
- assert!(
- error
- .to_string()
- .contains("server-recorded local paths are not trusted")
- );
- }
-
- #[test]
- fn prepare_source_from_git_record_rejects_parent_dir_subdir() {
- let record = SkillSourceRecord {
- source_type: "git".to_string(),
- source: Some("https://github.com/acme/skills/tree/main/skills/demo".to_string()),
- path: None,
- clone_url: Some("https://github.com/acme/skills.git".to_string()),
- ref_name: Some("main".to_string()),
- subdir: Some("../outside".to_string()),
- skill_name: Some("demo".to_string()),
- };
-
- let error = prepare_source_from_git_record(&record)
- .err()
- .expect("parent dir subdir should be rejected before clone");
- assert!(
- error
- .to_string()
- .contains("parent directory components are not allowed")
- );
- }
-
- #[test]
- fn prepare_source_from_git_record_rejects_absolute_subdir() {
- let record = SkillSourceRecord {
- source_type: "git".to_string(),
- source: Some("https://github.com/acme/skills/tree/main/skills/demo".to_string()),
- path: None,
- clone_url: Some("https://github.com/acme/skills.git".to_string()),
- ref_name: Some("main".to_string()),
- subdir: Some("/tmp/escape".to_string()),
- skill_name: Some("demo".to_string()),
- };
-
- let error = prepare_source_from_git_record(&record)
- .err()
- .expect("absolute subdir should be rejected before clone");
- assert!(error.to_string().contains("absolute subdir"));
- }
-
- #[test]
- fn default_add_targets_expand_skill_collection_directory() {
- let temp_dir = tempfile::tempdir().expect("tempdir");
- let root = temp_dir.path().join("skills");
- let skill_a = root.join("skill-a");
- let skill_b = root.join("skill-b");
- std::fs::create_dir_all(&skill_a).expect("skill-a dir");
- std::fs::create_dir_all(&skill_b).expect("skill-b dir");
- std::fs::write(
- skill_a.join("SKILL.md"),
- "---\nname: skill-a\ndescription: A\n---\n",
- )
- .expect("skill-a md");
- std::fs::write(
- skill_b.join("SKILL.md"),
- "---\nname: skill-b\ndescription: B\n---\n",
- )
- .expect("skill-b md");
-
- let source = PreparedSource::Path {
- path: root,
- _temp_dir: None,
- origin: SourceOrigin::Local {
- source: temp_dir.path().to_string_lossy().to_string(),
- },
- };
- let targets = resolve_add_targets(&source, &[]).expect("targets");
-
- assert_eq!(targets.len(), 2);
- assert!(
- targets
- .iter()
- .any(|target| target.data.ends_with("skill-a"))
- );
- assert!(
- targets
- .iter()
- .any(|target| target.data.ends_with("skill-b"))
- );
- }
-
#[test]
fn skill_remove_selector_counts_wrapped_ansi_rows() {
let lines = vec![
diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.md
index 169463afe..d1034199e 100644
--- a/docs/en/api/04-skills.md
+++ b/docs/en/api/04-skills.md
@@ -341,18 +341,13 @@ fmt.Println(result["task_id"])
**CLI**
-`ov add-skill` and `ov skills add` share the same options and import flow. The CLI
-clones Git repositories or GitHub `tree` directories locally, then packages and
-uploads the selected skills. The server API still receives inline content or
-temporary uploads. Supporting files such as `references/` and `scripts/` are included.
+`ov add-skill` and `ov skills add` share the same options and import flow.
Use `--list` to inspect a collection and `--skill` to select skills. Batch imports
-require confirmation unless `--yes` is set. By default, the command waits for downloading,
-uploading, server-side parsing, overview generation, and file writes, but not vectorization.
-`--wait` additionally waits for vectorization.
+require confirmation unless `--yes` is set.
```bash
# Import one skill from the standalone skills branch; ov skills add also works
-ov add-skill https://github.com/volcengine/OpenViking/tree/skills/llm-wiki --wait
+ov add-skill https://github.com/volcengine/OpenViking/tree/skills/llm-wiki
# Inspect a local collection, then select skills to import
ov add-skill ./examples/compile/ov-compile-skills --list
diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.md
index 2041cfba0..6e296ae41 100644
--- a/docs/zh/api/04-skills.md
+++ b/docs/zh/api/04-skills.md
@@ -340,16 +340,12 @@ fmt.Println(result["task_id"])
**CLI**:
-`ov add-skill` 与 `ov skills add` 使用同一套参数和导入流程。Git 仓库或
-GitHub `tree` 目录由 CLI 克隆到本地,再将选中的技能打包上传;服务端 API
-仍接收内联内容或临时上传文件。目录中的 `references/`、`scripts/` 等附件一并上传。
+`ov add-skill` 与 `ov skills add` 使用同一套参数和导入流程。
技能集合可以用 `--list` 查看、`--skill` 选择;批量导入需要确认,或使用 `--yes`。
-默认不等待向量化完成,但仍需完成下载、上传,以及服务端的解析、overview 生成和文件写入。
-`--wait` 额外等待向量化完成。
```bash
# 从独立 skills 分支导入一个技能;也可以写成 ov skills add
-ov add-skill https://github.com/volcengine/OpenViking/tree/skills/llm-wiki --wait
+ov add-skill https://github.com/volcengine/OpenViking/tree/skills/llm-wiki
# 查看本地技能集合,再选择导入
ov add-skill ./examples/compile/ov-compile-skills --list
diff --git a/openviking/parse/accessors/git_accessor.py b/openviking/parse/accessors/git_accessor.py
index 7752ea49b..999f9b5c0 100644
--- a/openviking/parse/accessors/git_accessor.py
+++ b/openviking/parse/accessors/git_accessor.py
@@ -200,7 +200,7 @@ class GitAccessor(DataAccessor):
# Build metadata
# repo_name is in "org/repo" format (e.g. "volcengine/OpenViking")
# This is extracted via parse_code_hosting_url() from the original URL
- meta = {"repo_name": repo_name}
+ meta = {"repo_name": repo_name, "_cleanup_path": temp_local_dir}
if branch:
meta["repo_ref"] = branch
if commit:
diff --git a/openviking/server/routers/resources.py b/openviking/server/routers/resources.py
index bd617446a..f79b11aa7 100644
--- a/openviking/server/routers/resources.py
+++ b/openviking/server/routers/resources.py
@@ -2,6 +2,8 @@
# SPDX-License-Identifier: AGPL-3.0
"""Resource endpoints for OpenViking HTTP Server."""
+import asyncio
+from pathlib import Path
from typing import Any, Dict, Literal, Optional
from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
@@ -19,6 +21,7 @@ from openviking.server.responses import response_from_result
from openviking.server.skill_source_metadata import persist_skill_source_metadata
from openviking.server.telemetry import run_operation
from openviking.server.temp_upload_store import TempUploadStore
+from openviking.service.skill_sources import describe_skill_sources, resolve_skill_source
from openviking.telemetry import TelemetryRequest
from openviking_cli.exceptions import InvalidArgumentError
@@ -138,8 +141,8 @@ class AddSkillRequest(BaseModel):
"""Request model for add_skill.
Attributes:
- data: Inline skill content or structured skill data. HTTP requests do not treat
- string values as host filesystem paths.
+ data: Git skill URL, inline skill content, or structured skill data.
+ HTTP requests do not treat strings as host filesystem paths.
temp_file_id: Temporary upload id returned by /api/v1/resources/temp_upload.
wait: Whether to wait for skill processing to complete.
timeout: Timeout in seconds when wait=True.
@@ -149,6 +152,8 @@ class AddSkillRequest(BaseModel):
data: Any = None
temp_file_id: Optional[str] = None
+ skills: list[str] = Field(default_factory=list)
+ list_only: bool = False
wait: bool = False
timeout: Optional[float] = None
source_metadata: Optional[Dict[str, Any]] = None
@@ -377,20 +382,43 @@ async def add_skill(
async def _add() -> dict[str, Any]:
try:
- result = await service.resources.add_skill(
- data=data,
- ctx=_ctx,
- wait=request.wait,
- timeout=request.timeout,
+ async with resolve_skill_source(
+ data,
+ names=request.skills,
allow_local_path_resolution=allow_local_path_resolution,
- source_path_hint=source_path_hint,
- target_uri=target_uri,
- )
- await persist_skill_source_metadata(service, _ctx, result, source_metadata)
- except Exception:
- raise
- else:
- return result
+ source_metadata=source_metadata,
+ ) as targets:
+ if request.list_only:
+ return await asyncio.to_thread(describe_skill_sources, targets)
+ installed = []
+ for skill_data, skill_source in targets:
+
+ async def _install(skill_data=skill_data, skill_source=skill_source):
+ result = await service.resources.add_skill(
+ data=skill_data,
+ ctx=_ctx,
+ wait=request.wait,
+ timeout=request.timeout,
+ allow_local_path_resolution=isinstance(skill_data, Path),
+ source_path_hint=source_path_hint,
+ target_uri=target_uri,
+ )
+ await persist_skill_source_metadata(service, _ctx, result, skill_source)
+ return result
+
+ # Each skill owns its own queue wait tracker and task ID.
+ if len(targets) == 1:
+ installed.append(await _install())
+ else:
+ execution = await run_operation(
+ operation="resources.add_skill",
+ telemetry=request.telemetry,
+ fn=_install,
+ )
+ installed.append(execution.result)
+ if len(installed) == 1:
+ return installed[0]
+ return {"installed": installed, "total": len(installed)}
finally:
if resolved:
await resolved.cleanup()
diff --git a/openviking/server/routers/skills.py b/openviking/server/routers/skills.py
index 63ae2b843..9b3d593cf 100644
--- a/openviking/server/routers/skills.py
+++ b/openviking/server/routers/skills.py
@@ -33,6 +33,7 @@ from openviking.server.skill_source_metadata import (
)
from openviking.server.telemetry import run_operation
from openviking.server.temp_upload_store import TempUploadStore
+from openviking.service.skill_sources import resolve_skill_source
from openviking.telemetry import TelemetryRequest
from openviking.utils.skill_processor import validate_skill_name
from openviking_cli.exceptions import InvalidArgumentError, NotFoundError, ResourceExhaustedError
@@ -52,6 +53,7 @@ class UpdateSkillRequest(BaseModel):
data: Any = None
temp_file_id: Optional[str] = None
+ from_source: bool = False
wait: bool = False
timeout: Optional[float] = None
source_metadata: Optional[Dict[str, Any]] = None
@@ -60,8 +62,11 @@ class UpdateSkillRequest(BaseModel):
@model_validator(mode="after")
def check_data_or_temp_file_id(self):
- if self.data is None and not self.temp_file_id:
- raise ValueError("Either 'data' or 'temp_file_id' must be provided")
+ if self.from_source:
+ if self.data is not None or self.temp_file_id:
+ raise ValueError("from_source cannot be combined with data or temp_file_id")
+ elif self.data is None and not self.temp_file_id:
+ raise ValueError("Either data, temp_file_id, or from_source must be provided")
return self
@@ -742,7 +747,21 @@ async def update_skill(
if resolved.original_filename and request.source_metadata is None:
source_metadata["original_filename"] = resolved.original_filename
+ git_source = None
+ if request.from_source:
+ git_source = await read_skill_source_metadata(service, _ctx, root_uri)
+ if git_source.get("type") != "git":
+ raise InvalidArgumentError(
+ "Skill has no recorded Git source; supply content or an upload"
+ )
+ git_source = {
+ key: git_source.get(key)
+ for key in ("type", "source", "clone_url", "ref_name", "subdir")
+ }
+ data = git_source.get("clone_url")
+
source_path_hint = resolved.original_filename if resolved else None
+
async def _update() -> Dict[str, Any]:
# Derive backup root from the actual skill root URI to keep backup in the same scope.
skill_root_parent = root_uri.rsplit("/", 1)[0]
@@ -755,43 +774,56 @@ async def update_skill(
try:
if privacy is not None:
previous_privacy = await privacy.get_current(_ctx, "skill", skill_name)
- preparation = await service.resources._skill_processor.prepare_skill_processing( # noqa: SLF001
+ async with resolve_skill_source(
data,
- ctx=_ctx,
allow_local_path_resolution=allow_local_path_resolution,
- source_path_hint=source_path_hint,
- )
- expected_name = _validate_skill_name(skill_name)
- if preparation.skill_dict.get("name") != expected_name:
- raise InvalidArgumentError(
- f"Skill name mismatch: path name is '{expected_name}', content name is '{preparation.skill_dict.get('name')}'",
- details={
- "expected": expected_name,
- "actual": preparation.skill_dict.get("name"),
- },
+ source_metadata=source_metadata,
+ git_source=git_source,
+ ) as targets:
+ if len(targets) > 1:
+ targets = [
+ (item, metadata) for item, metadata in targets if item.name == skill_name
+ ]
+ if len(targets) != 1:
+ raise InvalidArgumentError("Update source must identify exactly one skill")
+ skill_data, skill_source = targets[0]
+ preparation = await service.resources._skill_processor.prepare_skill_processing( # noqa: SLF001
+ skill_data,
+ ctx=_ctx,
+ allow_local_path_resolution=isinstance(skill_data, Path),
+ source_path_hint=source_path_hint,
+ )
+ expected_name = _validate_skill_name(skill_name)
+ if preparation.skill_dict.get("name") != expected_name:
+ raise InvalidArgumentError(
+ f"Skill name mismatch: path name is '{expected_name}', content name is '{preparation.skill_dict.get('name')}'",
+ details={
+ "expected": expected_name,
+ "actual": preparation.skill_dict.get("name"),
+ },
+ )
+ await service.fs.mv(root_uri, backup_uri, ctx=_ctx)
+ backup_created = True
+ result = await service.resources.add_skill(
+ data=preparation,
+ ctx=_ctx,
+ wait=request.wait,
+ timeout=request.timeout,
+ allow_local_path_resolution=False,
+ source_path_hint=source_path_hint,
+ apply_privacy=False,
+ privacy_change_reason="auto-extracted from update_skill",
+ target_uri=skill_root_parent,
+ )
+ await persist_skill_source_metadata(service, _ctx, result, skill_source)
+ privacy_update_attempted = True
+ await service.resources._skill_processor.apply_skill_privacy( # noqa: SLF001
+ preparation.skill_dict,
+ preparation.privacy_values,
+ _ctx,
+ change_reason="auto-extracted from update_skill",
+ delete_if_empty=True,
)
- await service.fs.mv(root_uri, backup_uri, ctx=_ctx)
- backup_created = True
- result = await service.resources.add_skill(
- data=preparation,
- ctx=_ctx,
- wait=request.wait,
- timeout=request.timeout,
- allow_local_path_resolution=False,
- source_path_hint=source_path_hint,
- apply_privacy=False,
- privacy_change_reason="auto-extracted from update_skill",
- target_uri=skill_root_parent,
- )
- await persist_skill_source_metadata(service, _ctx, result, source_metadata)
- privacy_update_attempted = True
- await service.resources._skill_processor.apply_skill_privacy( # noqa: SLF001
- preparation.skill_dict,
- preparation.privacy_values,
- _ctx,
- change_reason="auto-extracted from update_skill",
- delete_if_empty=True,
- )
except Exception:
if backup_created:
try:
diff --git a/openviking/service/skill_sources.py b/openviking/service/skill_sources.py
new file mode 100644
index 000000000..b63ddc17f
--- /dev/null
+++ b/openviking/service/skill_sources.py
@@ -0,0 +1,164 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Resolve skill sources for server-side discovery, import, and updates."""
+
+import asyncio
+import os
+import shutil
+from contextlib import asynccontextmanager
+from pathlib import Path, PurePosixPath
+from urllib.parse import unquote, urlparse
+
+from openviking.core.skill_loader import SkillLoader
+from openviking.parse.accessors.git_accessor import GitAccessor
+from openviking.server.local_input_guard import deny_direct_local_skill_input
+from openviking.utils.code_hosting_utils import is_github_url, parse_git_repo_url
+from openviking.utils.network_guard import ensure_public_remote_target
+from openviking.utils.skill_processor import SkillProcessor, validate_skill_name
+from openviking_cli.exceptions import InvalidArgumentError
+
+
+def parse_git_skill_source(source: str) -> dict:
+ """Parse a Git URL into repository, revision, and skill subdirectory."""
+ parsed = urlparse(source)
+ parts = parsed.path.strip("/").split("/")
+ subdir = None
+ ref = None
+ repo_url = source
+ if is_github_url(source) and len(parts) > 4 and parts[2] == "tree":
+ # In tree/<ref>/skills/..., <ref> may contain slashes.
+ split = parts.index("skills", 4) if "skills" in parts[4:] else 4
+ ref = unquote("/".join(parts[3:split]))
+ subdir = unquote("/".join(parts[split:]))
+ repo_url = parsed._replace(path="/" + "/".join(parts[:2]), query="", fragment="").geturl()
+ repo = parse_git_repo_url(repo_url)
+ if repo is None:
+ raise InvalidArgumentError("Unsupported Git skill source URL")
+ return {
+ "type": "git",
+ "source": source,
+ "clone_url": repo.clone_url,
+ "ref_name": ref or repo.branch or repo.commit,
+ "subdir": subdir,
+ }
+
+
+def _skill_paths(root: Path, names: list[str], repo_root: Path | None) -> list[Path]:
+ paths = []
+ # A SKILL.md owns its whole subtree, including nested SKILL.md attachments.
+ for directory, dirs, files in os.walk(root):
+ dirs[:] = sorted(name for name in dirs if name != ".git")
+ if "SKILL.md" in files:
+ paths.append(Path(directory))
+ dirs.clear()
+ if not paths:
+ raise InvalidArgumentError("No SKILL.md found in the skill source")
+ names = list(dict.fromkeys(name.strip() for name in names))
+ selected = paths
+ if names and names != ["*"]:
+ selected = []
+ for name in names:
+ validate_skill_name(name)
+ matches = [path for path in paths if path.name == name]
+ if len(matches) != 1:
+ raise InvalidArgumentError(
+ f"Skill '{name}' must identify exactly one source directory"
+ )
+ selected.append(matches[0])
+ if repo_root is not None:
+ # A cloned symlink must never import files outside the repository.
+ for path in selected:
+ for entry in path.rglob("*"):
+ if not entry.resolve().is_relative_to(repo_root):
+ raise InvalidArgumentError("Skill file escapes the source repository")
+ return selected
+
+
+@asynccontextmanager
+async def resolve_skill_source(
+ data,
+ *,
+ names: list[str] | None = None,
+ allow_local_path_resolution: bool = False,
+ source_metadata: dict | None = None,
+ git_source: dict | None = None,
+):
+ """Yield (skill data, source metadata) pairs; retain files until processing ends.
+
+ Only trusted temp uploads may resolve local paths. Recorded Git metadata is
+ accepted for updates, but is validated again before any network or file I/O.
+ """
+ resource = None
+ repo_root = None
+ cleanup_path = None
+ names = names or []
+ try:
+ if (
+ isinstance(data, str)
+ and data.startswith(("https://", "http://", "git@", "ssh://", "git://"))
+ and "\n" not in data
+ ):
+ git_source = git_source or parse_git_skill_source(data)
+ if git_source is not None:
+ clone_url = git_source.get("clone_url")
+ if not isinstance(clone_url, str) or parse_git_repo_url(clone_url) is None:
+ raise InvalidArgumentError("Invalid recorded Git skill source")
+ subdir = git_source.get("subdir") or ""
+ if (
+ not isinstance(subdir, str)
+ or "\\" in subdir
+ or PurePosixPath(subdir).is_absolute()
+ or ".." in PurePosixPath(subdir).parts
+ ):
+ raise InvalidArgumentError("Skill source subdir must stay inside the repository")
+ await asyncio.to_thread(ensure_public_remote_target, clone_url)
+ resource = await GitAccessor().access(clone_url, ref=git_source.get("ref_name"))
+ repo_root = resource.path.resolve()
+ data = (repo_root / subdir).resolve()
+ if not data.is_relative_to(repo_root) or not data.is_dir():
+ raise InvalidArgumentError(
+ "Skill source subdir is not a directory inside the repository"
+ )
+ # Git transport metadata is not skill content.
+ await asyncio.to_thread(shutil.rmtree, repo_root / ".git", ignore_errors=True)
+ (repo_root / ".git_source_repo").unlink(missing_ok=True)
+ elif allow_local_path_resolution:
+ data, cleanup_path = SkillProcessor._resolve_skill_path(Path(data))
+ elif isinstance(data, str):
+ deny_direct_local_skill_input(data)
+
+ if not isinstance(data, Path) or not data.is_dir():
+ if names:
+ raise InvalidArgumentError("Skill selection requires a directory or Git source")
+ yield [(data, source_metadata)]
+ return
+
+ paths = await asyncio.to_thread(_skill_paths, data, names, repo_root)
+ targets = []
+ for path in paths:
+ metadata = source_metadata
+ if git_source is not None:
+ metadata = {
+ **git_source,
+ "subdir": path.relative_to(repo_root).as_posix(),
+ }
+ targets.append((path, metadata))
+ yield targets
+ finally:
+ if resource is not None:
+ await asyncio.to_thread(resource.cleanup)
+ if cleanup_path:
+ await asyncio.to_thread(shutil.rmtree, cleanup_path, ignore_errors=True)
+
+
+def describe_skill_sources(targets: list[tuple]) -> dict:
+ """Describe source skills without persisting content or invoking models."""
+ skills = []
+ for data, _metadata in targets:
+ if not isinstance(data, Path):
+ raise InvalidArgumentError("Listing skills requires a directory or Git source")
+ skill = SkillLoader.load(str(data / "SKILL.md" if data.is_dir() else data))
+ skills.append(
+ {"name": skill["name"], "description": skill["description"], "path": data.name}
+ )
+ return {"skills": skills, "total": len(skills)}
diff --git a/tests/server/test_api_skills.py b/tests/server/test_api_skills.py
index a72ede6f2..14df14bdc 100644
--- a/tests/server/test_api_skills.py
+++ b/tests/server/test_api_skills.py
@@ -466,7 +466,7 @@ async def test_skills_api_show_reads_source_metadata_and_hides_internal_file(cli
assert all(file["path"] != ".source.json" for file in shown["files"])
-async def test_skills_api_add_accepts_source_metadata_override(client):
+async def test_skills_api_add_accepts_source_metadata_override(client, monkeypatch, tmp_path):
response = await client.post(
"/api/v1/skills",
json={
@@ -496,6 +496,69 @@ async def test_skills_api_add_accepts_source_metadata_override(client):
assert source["subdir"] == "skills/git-source-skill"
assert source["skill_name"] == "git-source-skill"
+ from openviking.parse.accessors.base import LocalResource, SourceType
+ from openviking.parse.accessors.git_accessor import GitAccessor
+
+ downloads = []
+
+ async def download(_accessor, source, **kwargs):
+ root = tmp_path / f"download-{len(downloads)}"
+ for name in ("remote-a", "remote-b"):
+ path = root / "skills" / name
+ path.mkdir(parents=True)
+ (path / "SKILL.md").write_text(_skill_md(name, f"Revision {len(downloads)}"))
+ (path / "asset.bin").write_bytes(b"\x00\xff")
+ downloads.append((root, source, kwargs.get("ref")))
+ return LocalResource(path=root, source_type=SourceType.GIT, original_source=source)
+
+ monkeypatch.setattr(GitAccessor, "access", download)
+ url = "https://github.com/acme/skills/tree/feature/foo/skills"
+ listing = await client.post("/api/v1/skills", json={"data": url, "list_only": True})
+ assert listing.status_code == 200, listing.text
+ assert {item["name"] for item in listing.json()["result"]["skills"]} == {"remote-a", "remote-b"}
+ assert (await client.get("/api/v1/skills/remote-a")).status_code == 404
+ assert downloads[-1][2] == "feature/foo"
+ assert not downloads[-1][0].exists()
+
+ selected = await client.post(
+ "/api/v1/skills", json={"data": url, "skills": ["remote-a"], "wait": True}
+ )
+ assert selected.status_code == 200, selected.text
+ assert selected.json()["result"]["name"] == "remote-a"
+ assert (await client.get("/api/v1/skills/remote-b")).status_code == 404
+ detail = (await client.get("/api/v1/skills/remote-a", params={"include_source": True})).json()[
+ "result"
+ ]
+ assert detail["source"]["subdir"] == "skills/remote-a"
+ assert detail["source"]["ref_name"] == "feature/foo"
+ assert any(item["name"] == "asset.bin" for item in detail["files"])
+
+ refreshed = await client.put(
+ "/api/v1/skills/remote-a", json={"from_source": True, "wait": True}
+ )
+ assert refreshed.status_code == 200, refreshed.text
+ assert refreshed.json()["result"]["name"] == "remote-a"
+ assert downloads[-1][2] == "feature/foo"
+
+ batch = await client.post("/api/v1/skills", json={"data": url, "skills": ["*"]})
+ assert batch.status_code == 200, batch.text
+ installed = batch.json()["result"]["installed"]
+ assert {item["name"] for item in installed} == {"remote-a", "remote-b"}
+ assert len({item["task_id"] for item in installed}) == 2
+ assert all(not root.exists() for root, _, _ in downloads)
+
+ missing = await client.post("/api/v1/skills", json={"data": url, "skills": ["missing"]})
+ assert missing.status_code == 400, missing.text
+ assert not downloads[-1][0].exists()
+ count = len(downloads)
+ traversal = await client.post(
+ "/api/v1/skills", json={"data": "https://github.com/acme/skills/tree/main/%2e%2e/outside"}
+ )
+ assert traversal.status_code == 400, traversal.text
+ local = await client.post("/api/v1/skills", json={"data": str(tmp_path)})
+ assert local.status_code == 403, local.text
+ assert len(downloads) == count
+
async def test_skills_api_update_accepts_binary_auxiliary_files(client, tmp_path):
await _add_skill(client, "binary-skill", "Original binary skill")