Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(cli): add Openviking asset manifest mode to add-resource (#3358)
zihengli47bbf7a66a89
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 22017ef62..b21371f5a 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -12,6 +12,7 @@ mod handlers;mod health_ui;mod help_ui;mod i18n;+mod openviking_assets;mod output;mod status_ui;mod terminal_ui;@@ -280,17 +281,60 @@ enum Commands {/// [Data] Add resources into OpenVikingAddResource {/// Local path or URL to import- #[arg(value_name = "path-or-url")]- path: String,+ #[arg(+ value_name = "path-or-url",+ required_unless_present = "manifest",+ conflicts_with = "manifest"+ )]+ path: Option<String>,+ /// Apply an OpenViking Assets manifest (openviking-assets/1): create or sync every selected asset+ #[arg(+ short = 'm',+ long = "manifest",+ value_name = "file",+ help_heading = "Manifest mode",+ conflicts_with_all = [+ "add_type", "to", "parent", "parent_auto_create", "resource_args",+ "strict_mode", "ignore_dirs", "include", "exclude",+ "no_directly_upload_media", "tags", "tag_mode"+ ]+ )]+ manifest: Option<String>,+ /// Manifest mode: separate catalog file for manifests that select assets by name+ /// (defaults to assets.yaml next to the manifest; not used when the manifest+ /// defines assets under 'catalog')+ #[arg(+ long = "catalog",+ value_name = "file",+ requires = "manifest",+ conflicts_with = "path",+ help_heading = "Manifest mode"+ )]+ catalog: Option<String>,+ /// Manifest mode: validate config and source access, then print the plan without submitting+ #[arg(+ long = "dry-run",+ requires = "manifest",+ help_heading = "Manifest mode"+ )]+ dry_run: bool,+ /// Manifest mode: continue with remaining assets when one fails+ #[arg(+ long = "skip-failed",+ requires = "manifest",+ help_heading = "Manifest mode"+ )]+ skip_failed: bool,/// Explicit Connector source type (e.g. "tos", "git"). Routes the import/// through the Connector integration (must be enabled server-side); the/// path is sent verbatim and never treated as a local file. Requires --to- /// and cannot be combined with --parent or --parent-auto-create+ /// and cannot be combined with Manifest mode, --parent, or+ /// --parent-auto-create#[arg(long = "add-type",value_name = "type",requires = "to",- conflicts_with_all = ["parent", "parent_auto_create"],+ conflicts_with_all = ["manifest", "parent", "parent_auto_create"],help_heading = "Common options")]add_type: Option<String>,@@ -354,13 +398,8 @@ enum Commands {)]no_directly_upload_media: bool,/// Watch interval in minutes for automatic resource monitoring (0 = no monitoring)- #[arg(- long,- default_value = "0",- value_name = "minutes",- help_heading = "Advanced options"- )]- watch_interval: f64,+ #[arg(long, value_name = "minutes", help_heading = "Advanced options")]+ watch_interval: Option<f64>,/// Resource processing mode#[arg(long = "processing-mode",@@ -2811,6 +2850,10 @@ async fn main() {Commands::AddResource {path,add_type,+ manifest,+ catalog,+ dry_run,+ skip_failed,to,parent,parent_auto_create,@@ -2832,29 +2875,50 @@ async fn main() {} => {let ctx =ctx.with_upload_options(upload_options.merged_with_legacy(legacy_upload_options));- handlers::handle_add_resource(- path,- add_type,- to,- parent,- parent_auto_create,- reason,- instruction,- wait,- timeout,- strict_mode,- ignore_dirs,- include,- exclude,- no_directly_upload_media,- watch_interval,- processing_mode,- resource_args,- tags,- tag_mode,- ctx,- )- .await+ if let Some(manifest) = manifest {+ openviking_assets::handle_manifest_apply(+ manifest,+ catalog,+ openviking_assets::ManifestRunOptions {+ dry_run,+ skip_failed,+ wait,+ watch_interval,+ processing_mode,+ },+ timeout,+ ctx,+ )+ .await+ } else if let Some(path) = path {+ handlers::handle_add_resource(+ path,+ add_type,+ to,+ parent,+ parent_auto_create,+ reason,+ instruction,+ wait,+ timeout,+ strict_mode,+ ignore_dirs,+ include,+ exclude,+ no_directly_upload_media,+ watch_interval.unwrap_or(0.0),+ processing_mode,+ resource_args,+ tags,+ tag_mode,+ ctx,+ )+ .await+ } else {+ Err(error::Error::Client(+ "a path/URL or --manifest is required".to_string(),+ ))+ }}Commands::AddSkill {data,@@ -4835,6 +4899,34 @@ mod tests {);}+ #[test]+ fn cli_manifest_mode_accepts_explicit_catalog() {+ let result = Cli::try_parse_from([+ "ov",+ "add-resource",+ "--manifest",+ "manifests/code-qa.yaml",+ "--catalog",+ "assets.yaml",+ "--dry-run",+ ]);++ assert!(result.is_ok(), "manifest and catalog flags should parse");+ }++ #[test]+ fn cli_catalog_requires_manifest_mode() {+ let result = Cli::try_parse_from([+ "ov",+ "add-resource",+ "https://github.com/org/repo",+ "--catalog",+ "assets.yaml",+ ]);++ assert!(result.is_err(), "--catalog without --manifest must fail");+ }+#[test]fn cli_parses_reindex_command() {let result = Cli::try_parse_from([diff --git a/crates/ov_cli/src/openviking_assets.rs b/crates/ov_cli/src/openviking_assets.rsnew file mode 100644index 000000000..8bf79e08d--- /dev/null+++ b/crates/ov_cli/src/openviking_assets.rs@@ -0,0 +1,1231 @@+//! OpenViking Assets manifest mode for `ov add-resource -m <manifest.yaml>`.+//!+//! Implements the declaration layer of the OpenViking Assets protocol+//! (`openviking-assets/1`): a manifest defines its assets directly under+//! `catalog:`, or — when several manifests share one asset catalog — selects+//! assets by name from a separate catalog file (`assets.yaml`).+//! Validation is strict by design — unknown+//! fields are errors, not warnings — so a mistyped manifest fails at parse+//! time instead of silently degrading. Fetching, parsing, vectorization and+//! watch-based refresh stay in the server and its connector plugins.++use std::collections::{BTreeMap, HashSet};+use std::path::{Path, PathBuf};++use serde::{Deserialize, Serialize};+use serde_json::{Map, Value, json};++use crate::CliContext;+use crate::error::{Error, Result};+use crate::output::OutputFormat;++pub const STATE_PROTOCOL: &str = "openviking-assets-state/1";+const DEFAULT_CATALOG_FILENAME: &str = "assets.yaml";+const CREDENTIALS_ENV: &str = "OPENVIKING_ASSETS_CREDENTIALS_FILE";++fn client_err(msg: impl Into<String>) -> Error {+ Error::Client(msg.into())+}++// The server owns OpenViking Assets syntax parsing and semantic validation.+// The CLI receives only the resolved execution plan.+#[derive(Debug, Clone, Deserialize)]+pub struct ResolvedAsset {+ pub name: String,+ pub connector: String,+ pub repo_url: String,+ pub branch: Option<String>,+ pub auth_ref: Option<String>,+ pub watch_interval: f64,+ pub locator: String,+ pub git_ref: String,+ pub asset_id: String,+}++#[derive(Deserialize)]+struct ResolveResponse {+ assets: Vec<ResolvedAsset>,+}++fn read_yaml<T: serde::de::DeserializeOwned>(path: &Path, what: &str) -> Result<T> {+ let text = std::fs::read_to_string(path)+ .map_err(|e| client_err(format!("cannot read {what} '{}': {e}", path.display())))?;+ serde_yaml::from_str(&text).map_err(|e| client_err(format!("{what} '{}': {e}", path.display())))+}++// ============================ Credentials layer ===========================++#[derive(Deserialize)]+#[serde(deny_unknown_fields)]+struct RawCredentialsFile {+ #[serde(default)]+ credentials: Option<BTreeMap<String, Option<BTreeMap<String, serde_yaml::Value>>>>,+}++pub fn credentials_path() -> PathBuf {+ if let Ok(path) = std::env::var(CREDENTIALS_ENV)+ && !path.is_empty()+ {+ return PathBuf::from(path);+ }+ dirs::home_dir()+ .unwrap_or_else(|| PathBuf::from("."))+ .join(".openviking")+ .join("openviking_assets_credentials.yaml")+}++/// Load the alias -> args mapping. A missing file is an empty mapping.+pub fn load_credentials(path: &Path) -> Result<BTreeMap<String, Map<String, Value>>> {+ if !path.is_file() {+ return Ok(BTreeMap::new());+ }+ let raw: RawCredentialsFile = read_yaml(path, "credentials file")?;+ let mut parsed = BTreeMap::new();+ for (alias, args) in raw.credentials.unwrap_or_default() {+ let mut map = Map::new();+ for (key, value) in args.unwrap_or_default() {+ let value = serde_json::to_value(&value).map_err(|e| {+ client_err(format!(+ "credentials file '{}': alias '{alias}' arg '{key}': {e}",+ path.display()+ ))+ })?;+ map.insert(key, value);+ }+ parsed.insert(alias, map);+ }+ Ok(parsed)+}++/// Return the args behind an alias; a declared but unresolvable alias is an error.+pub fn resolve_auth_ref(+ auth_ref: &str,+ credentials: &BTreeMap<String, Map<String, Value>>,+ path: &Path,+) -> Result<Map<String, Value>> {+ credentials.get(auth_ref).cloned().ok_or_else(|| {+ client_err(format!(+ "auth_ref '{auth_ref}' is not defined in the local credentials file '{}'; \+ add it under 'credentials:', or remove 'auth_ref' from the catalog entry if \+ the server's own auth (e.g. SSH keys) is sufficient",+ path.display()+ ))+ })+}++// =============================== State layer ==============================++#[derive(Serialize, Deserialize, Clone, Debug, Default)]+pub struct AssetStateEntry {+ pub name: String,+ pub connector: String,+ pub locator: String,+ #[serde(rename = "ref")]+ pub git_ref: String,+ #[serde(default)]+ pub status: String,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub resource_uri: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub task_id: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub error: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub last_applied_at: Option<String>,+}++#[derive(Serialize, Deserialize)]+struct RawStateFile {+ protocol: String,+ #[serde(default)]+ updated_at: Option<String>,+ #[serde(default)]+ assets: BTreeMap<String, AssetStateEntry>,+}++/// Manifest-level apply state (`<manifest>.state.json`).+///+/// Records only manifest-level facts: which asset became which resource and+/// how the last apply ended. Content-level sync watermarks stay with the+/// server-side connector/watch machinery. Assets that disappear from the+/// manifest are reported as orphans and kept — v1 never deletes resources.+#[derive(Debug)]+pub struct ManifestState {+ pub path: PathBuf,+ pub assets: BTreeMap<String, AssetStateEntry>,+}++impl ManifestState {+ pub fn orphans(&self, current_ids: &HashSet<String>) -> Vec<(&String, &AssetStateEntry)> {+ self.assets+ .iter()+ .filter(|(id, _)| !current_ids.contains(*id))+ .collect()+ }++ pub fn record(&mut self, asset_id: &str, mut entry: AssetStateEntry) {+ entry.last_applied_at = Some(now_iso());+ self.assets.insert(asset_id.to_string(), entry);+ }++ pub fn save(&self) -> Result<()> {+ let payload = RawStateFile {+ protocol: STATE_PROTOCOL.to_string(),+ updated_at: Some(now_iso()),+ assets: self.assets.clone(),+ };+ let text = serde_json::to_string_pretty(&payload)+ .map_err(|e| client_err(format!("cannot serialize state: {e}")))?;+ let tmp_path = self.path.with_extension("json.tmp");+ std::fs::write(&tmp_path, text + "\n")+ .map_err(|e| client_err(format!("cannot write '{}': {e}", tmp_path.display())))?;+ std::fs::rename(&tmp_path, &self.path)+ .map_err(|e| client_err(format!("cannot write '{}': {e}", self.path.display())))?;+ Ok(())+ }+}++fn now_iso() -> String {+ chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, false)+}++pub fn state_path_for(manifest_path: &Path) -> PathBuf {+ let name = manifest_path+ .file_name()+ .map(|n| n.to_string_lossy().to_string())+ .unwrap_or_default();+ manifest_path.with_file_name(format!("{name}.state.json"))+}++pub fn load_state(manifest_path: &Path) -> Result<ManifestState> {+ let path = state_path_for(manifest_path);+ if !path.is_file() {+ return Ok(ManifestState {+ path,+ assets: BTreeMap::new(),+ });+ }+ let text = std::fs::read_to_string(&path).map_err(|e| {+ client_err(format!(+ "state file '{}' is unreadable: {e}",+ path.display()+ ))+ })?;+ let raw: RawStateFile = serde_json::from_str(&text).map_err(|e| {+ client_err(format!(+ "state file '{}' is unreadable ({e}); fix or remove it and re-run",+ path.display()+ ))+ })?;+ if raw.protocol != STATE_PROTOCOL {+ return Err(client_err(format!(+ "state file '{}' has an unsupported protocol (expected '{STATE_PROTOCOL}'); \+ remove it to start fresh",+ path.display()+ )));+ }+ Ok(ManifestState {+ path,+ assets: raw.assets,+ })+}++// =============================== Apply layer ==============================++#[derive(Debug, Clone)]+pub struct ManifestRunOptions {+ pub dry_run: bool,+ pub skip_failed: bool,+ pub wait: bool,+ /// Overrides per-asset / catalog-default values when set.+ pub watch_interval: Option<f64>,+ pub processing_mode: String,+}++impl Default for ManifestRunOptions {+ fn default() -> Self {+ Self {+ dry_run: false,+ skip_failed: false,+ wait: false,+ watch_interval: None,+ processing_mode: "semantic_and_vectors".to_string(),+ }+ }+}++#[derive(Debug, Default)]+pub struct ApplySummary {+ pub total: usize,+ pub succeeded: Vec<String>,+ pub failed: BTreeMap<String, String>,+ pub not_attempted: Vec<String>,+}++impl ApplySummary {+ pub fn all_failed(&self) -> bool {+ self.total > 0 && self.failed.len() == self.total+ }+}++/// The one call the orchestrator needs; tests provide a fake implementation.+pub trait Submitter {+ async fn preflight(+ &self,+ asset: &ResolvedAsset,+ args: Option<Map<String, Value>>,+ ) -> Result<Value>;++ async fn submit(+ &self,+ asset: &ResolvedAsset,+ to: Option<String>,+ watch_interval: f64,+ args: Option<Map<String, Value>>,+ ) -> Result<Value>;+}++fn extract_str(result: &Value, keys: &[&str]) -> Option<String> {+ keys.iter().find_map(|key| {+ result+ .get(key)+ .and_then(Value::as_str)+ .filter(|s| !s.is_empty())+ .map(str::to_string)+ })+}++fn build_args(+ asset: &ResolvedAsset,+ credential_args: &Map<String, Value>,+) -> Option<Map<String, Value>> {+ let mut args = Map::new();+ if let Some(branch) = &asset.branch {+ args.insert("branch".to_string(), json!(branch));+ }+ for (key, value) in credential_args {+ args.insert(key.clone(), value.clone());+ }+ if args.is_empty() { None } else { Some(args) }+}++fn git_auth_config(args: Option<&Map<String, Value>>) -> Option<Value> {+ let args = args?;+ let mut auth = Map::new();+ for key in ["username", "token"] {+ if let Some(value) = args.get(key) {+ auth.insert(key.to_string(), value.clone());+ }+ }+ if auth.is_empty() {+ None+ } else {+ Some(Value::Object(auth))+ }+}++/// Preflight and then apply (or dry-run) a resolved manifest.+///+/// Every source is checked before the first mutation. A preflight failure+/// therefore aborts immediately even when `skip_failed` is set.+pub async fn apply_manifest_core<S: Submitter>(+ manifest_path: &Path,+ catalog_path: &Path,+ assets: &[ResolvedAsset],+ credentials_file: &Path,+ options: &ManifestRunOptions,+ submitter: &S,+ emit: &mut dyn FnMut(Value),+) -> Result<ApplySummary> {+ let mut state = load_state(manifest_path)?;++ // Pre-flight: every declared auth_ref must resolve before anything is submitted.+ let credentials = load_credentials(credentials_file)?;+ let mut credential_args: BTreeMap<String, Map<String, Value>> = BTreeMap::new();+ for asset in assets {+ let args = match &asset.auth_ref {+ Some(auth_ref) => resolve_auth_ref(auth_ref, &credentials, credentials_file)?,+ None => Map::new(),+ };+ credential_args.insert(asset.name.clone(), args);+ }++ let current_ids: HashSet<String> = assets.iter().map(|a| a.asset_id.clone()).collect();+ for (asset_id, orphan) in state.orphans(¤t_ids) {+ emit(json!({+ "event": "orphan",+ "asset_id": asset_id,+ "name": orphan.name,+ "resource_uri": orphan.resource_uri,+ "note": "no longer in manifest; OpenViking Assets never deletes resources automatically",+ }));+ }++ emit(json!({+ "event": "plan",+ "manifest": manifest_path.display().to_string(),+ "catalog": catalog_path.display().to_string(),+ "total": assets.len(),+ "dry_run": options.dry_run,+ }));++ // Source access is part of validation, including dry-run. Complete every+ // preflight before submitting the first asset so permission failures never+ // leave a partially applied manifest.+ for (index, asset) in assets.iter().enumerate() {+ let base = json!({+ "index": index + 1,+ "total": assets.len(),+ "name": asset.name,+ "connector": asset.connector,+ "locator": asset.locator,+ "ref": asset.git_ref,+ });+ emit({+ let mut event = base.as_object().cloned().unwrap_or_default();+ event.insert("event".to_string(), json!("asset_preflight_start"));+ Value::Object(event)+ });+ let args = build_args(asset, &credential_args[&asset.name]);+ match submitter.preflight(asset, args).await {+ Ok(_) => emit({+ let mut event = base.as_object().cloned().unwrap_or_default();+ event.insert("event".to_string(), json!("asset_preflight_ok"));+ Value::Object(event)+ }),+ Err(err) => {+ emit({+ let mut event = base.as_object().cloned().unwrap_or_default();+ event.insert("event".to_string(), json!("asset_preflight_failed"));+ event.insert("error".to_string(), json!(err.to_string()));+ Value::Object(event)+ });+ return Err(err);+ }+ }+ }++ let mut summary = ApplySummary {+ total: assets.len(),+ ..Default::default()+ };+ let mut stop = false;+ for (index, asset) in assets.iter().enumerate() {+ let existing = state.assets.get(&asset.asset_id).cloned();+ let action = match &existing {+ Some(entry) if entry.resource_uri.is_some() => "sync",+ _ => "create",+ };+ let watch_interval = options.watch_interval.unwrap_or(asset.watch_interval);+ let base = json!({+ "index": index + 1,+ "total": assets.len(),+ "name": asset.name,+ "asset_id": asset.asset_id,+ "connector": asset.connector,+ "locator": asset.locator,+ "ref": asset.git_ref,+ "action": action,+ "watch_interval": watch_interval,+ });+ let with = |base: &Value, extra: Value| {+ let mut merged = base.as_object().cloned().unwrap_or_default();+ if let Value::Object(extra) = extra {+ merged.extend(extra);+ }+ Value::Object(merged)+ };++ if stop {+ summary.not_attempted.push(asset.name.clone());+ emit(with(+ &base,+ json!({"event": "asset_skipped", "reason": "previous asset failed"}),+ ));+ continue;+ }+ if options.dry_run {+ emit(with(&base, json!({"event": "asset_planned"})));+ continue;+ }++ emit(with(&base, json!({"event": "asset_start"})));+ let mut entry = AssetStateEntry {+ name: asset.name.clone(),+ connector: asset.connector.clone(),+ locator: asset.locator.clone(),+ git_ref: asset.git_ref.clone(),+ resource_uri: existing.as_ref().and_then(|e| e.resource_uri.clone()),+ task_id: existing.as_ref().and_then(|e| e.task_id.clone()),+ ..Default::default()+ };+ let args = build_args(asset, &credential_args[&asset.name]);+ match submitter+ .submit(asset, entry.resource_uri.clone(), watch_interval, args)+ .await+ {+ Ok(response) => {+ entry.status = if options.wait { "ok" } else { "submitted" }.to_string();+ entry.error = None;+ if let Some(uri) =+ extract_str(&response, &["root_uri", "uri", "resource_uri", "to"])+ {+ entry.resource_uri = Some(uri);+ }+ if let Some(task_id) = extract_str(&response, &["task_id"]) {+ entry.task_id = Some(task_id);+ }+ let done = with(+ &base,+ json!({+ "event": "asset_done",+ "status": entry.status,+ "resource_uri": entry.resource_uri,+ "task_id": entry.task_id,+ }),+ );+ state.record(&asset.asset_id, entry);+ summary.succeeded.push(asset.name.clone());+ emit(done);+ }+ Err(err) => {+ let message = err.to_string();+ entry.status = "failed".to_string();+ entry.error = Some(message.clone());+ state.record(&asset.asset_id, entry);+ summary.failed.insert(asset.name.clone(), message.clone());+ emit(with(+ &base,+ json!({"event": "asset_failed", "error": message}),+ ));+ if !options.skip_failed {+ stop = true;+ }+ }+ }+ }++ if !options.dry_run {+ state.save()?;+ }++ emit(json!({+ "event": "summary",+ "total": summary.total,+ "succeeded": summary.succeeded.len(),+ "failed": summary.failed.len(),+ "not_attempted": summary.not_attempted.len(),+ "all_failed": summary.all_failed(),+ "dry_run": options.dry_run,+ "state": if options.dry_run { Value::Null } else { json!(state.path.display().to_string()) },+ }));+ Ok(summary)+}++// ================================ CLI entry ===============================++struct HttpSubmitter {+ client: crate::client::HttpClient,+ wait: bool,+ timeout: Option<f64>,+ processing_mode: String,+}++impl Submitter for HttpSubmitter {+ async fn preflight(+ &self,+ asset: &ResolvedAsset,+ args: Option<Map<String, Value>>,+ ) -> Result<Value> {+ self.client+ .post(+ "/api/v1/openviking-assets/preflight",+ &json!({+ "name": asset.name,+ "connector": asset.connector,+ "repo_url": asset.repo_url,+ "branch": asset.branch,+ "auth_config": git_auth_config(args.as_ref()),+ }),+ )+ .await+ }++ async fn submit(+ &self,+ asset: &ResolvedAsset,+ to: Option<String>,+ watch_interval: f64,+ args: Option<Map<String, Value>>,+ ) -> Result<Value> {+ self.client+ .add_resource(+ &asset.repo_url,+ Some("git".to_string()),+ to,+ None,+ None,+ "",+ "",+ self.wait,+ self.timeout,+ false,+ None,+ None,+ None,+ true,+ watch_interval,+ self.processing_mode.clone(),+ args,+ Vec::new(),+ "replace".to_string(),+ false,+ false,+ )+ .await+ }+}++fn render_event(event: &Value) {+ let kind = event.get("event").and_then(Value::as_str).unwrap_or("");+ let text = |key: &str| {+ event+ .get(key)+ .map(|v| match v {+ Value::String(s) => s.clone(),+ other => other.to_string(),+ })+ .unwrap_or_default()+ };+ let git_ref = text("ref");+ let ref_suffix = if git_ref.is_empty() {+ String::new()+ } else {+ format!("@{git_ref}")+ };+ match kind {+ "plan" => {+ let mode = if event["dry_run"].as_bool().unwrap_or(false) {+ "Dry run"+ } else {+ "Applying"+ };+ println!(+ "{mode}: {} ({} assets, catalog {})",+ text("manifest"),+ text("total"),+ text("catalog")+ );+ }+ "orphan" => {+ let uri = extract_str(event, &["resource_uri"])+ .unwrap_or_else(|| "unknown resource".to_string());+ eprintln!(+ "! orphan: '{}' left the manifest but its resource remains ({uri}); \+ OpenViking Assets never deletes automatically",+ text("name")+ );+ }+ "asset_planned" => {+ let watch = event["watch_interval"].as_f64().unwrap_or(0.0);+ let watch_suffix = if watch > 0.0 {+ format!(", watch={watch}min")+ } else {+ String::new()+ };+ println!(+ "[{}/{}] {}: {} (git:{}{ref_suffix}{watch_suffix})",+ text("index"),+ text("total"),+ text("action"),+ text("name"),+ text("locator")+ );+ }+ "asset_preflight_start" => {+ println!(+ "[{}/{}] checking access: {} (git:{}{ref_suffix}) ...",+ text("index"),+ text("total"),+ text("name"),+ text("locator")+ );+ }+ "asset_preflight_ok" => println!(" -> access ok"),+ "asset_preflight_failed" => eprintln!(" -> ACCESS FAILED: {}", text("error")),+ "asset_start" => {+ println!(+ "[{}/{}] {}: {} (git:{}{ref_suffix}) ...",+ text("index"),+ text("total"),+ text("action"),+ text("name"),+ text("locator")+ );+ }+ "asset_done" => {+ let uri = extract_str(event, &["resource_uri"])+ .unwrap_or_else(|| "(uri pending)".to_string());+ let task = extract_str(event, &["task_id"])+ .map(|t| format!(" task={t}"))+ .unwrap_or_default();+ println!(" -> {}: {uri}{task}", text("status"));+ }+ "asset_failed" => eprintln!(" -> FAILED: {}", text("error")),+ "asset_skipped" => println!(+ "[{}/{}] skipped: {} ({})",+ text("index"),+ text("total"),+ text("name"),+ text("reason")+ ),+ "summary" => {+ if event["dry_run"].as_bool().unwrap_or(false) {+ println!(+ "Plan complete: {} asset(s) validated, including source access.",+ text("total")+ );+ } else {+ println!(+ "Done: {} ok, {} failed, {} not attempted (state: {})",+ text("succeeded"),+ text("failed"),+ text("not_attempted"),+ text("state")+ );+ }+ }+ _ => {}+ }+}++/// True when the manifest defines its assets directly under a top-level+/// `catalog:` list, so no separate catalog file is needed. The server owns+/// full validation; this only decides whether to attach a catalog file.+fn manifest_defines_assets(manifest_yaml: &str) -> bool {+ serde_yaml::from_str::<serde_yaml::Value>(manifest_yaml)+ .map(|doc| {+ doc.get("catalog")+ .is_some_and(serde_yaml::Value::is_sequence)+ })+ .unwrap_or(false)+}++/// Entry point for `ov add-resource -m <manifest>`.+pub async fn handle_manifest_apply(+ manifest: String,+ catalog: Option<String>,+ options: ManifestRunOptions,+ timeout: Option<f64>,+ ctx: CliContext,+) -> Result<()> {+ let manifest_path = PathBuf::from(&manifest);+ let manifest_yaml = std::fs::read_to_string(&manifest_path).map_err(|e| {+ client_err(format!(+ "cannot read manifest '{}': {e}",+ manifest_path.display()+ ))+ })?;+ let catalog_path = match catalog {+ Some(path) => Some(PathBuf::from(path)),+ None if manifest_defines_assets(&manifest_yaml) => None,+ None => Some(+ manifest_path+ .parent()+ .unwrap_or(Path::new("."))+ .join(DEFAULT_CATALOG_FILENAME),+ ),+ };+ let catalog_yaml = catalog_path+ .as_ref()+ .map(|path| {+ std::fs::read_to_string(path).map_err(|e| {+ client_err(format!(+ "cannot read catalog '{}': {e}; define assets under 'catalog' in the manifest or pass --catalog <file>",+ path.display()+ ))+ })+ })+ .transpose()?;++ let effective_timeout = if options.wait {+ timeout.unwrap_or(60.0).max(ctx.config.timeout)+ } else {+ ctx.config.timeout.max(20.0)+ };+ let client = ctx.get_client_with_timeout(Some(effective_timeout));+ let mut request = json!({+ "manifest_yaml": manifest_yaml,+ "manifest_label": manifest_path.display().to_string(),+ });+ if let (Some(path), Some(yaml)) = (&catalog_path, &catalog_yaml) {+ request["catalog_yaml"] = json!(yaml);+ request["catalog_label"] = json!(path.display().to_string());+ }+ let resolved: ResolveResponse = client+ .post("/api/v1/openviking-assets/resolve", &request)+ .await?;++ let json_mode = matches!(ctx.output_format, OutputFormat::Json);+ let mut emit = |event: Value| {+ if json_mode {+ println!("{event}");+ } else {+ render_event(&event);+ }+ };++ let credentials_file = credentials_path();+ let submitter = HttpSubmitter {+ client,+ wait: options.wait,+ timeout,+ processing_mode: options.processing_mode.clone(),+ };+ let summary = apply_manifest_core(+ &manifest_path,+ // Single-file manifests are their own catalog in plan output.+ catalog_path.as_deref().unwrap_or(&manifest_path),+ &resolved.assets,+ &credentials_file,+ &options,+ &submitter,+ &mut emit,+ )+ .await?;++ if summary.all_failed() {+ return Err(client_err(+ "every asset failed; nothing was applied successfully",+ ));+ }+ if !summary.failed.is_empty() {+ let names = summary+ .failed+ .keys()+ .cloned()+ .collect::<Vec<_>>()+ .join(", ");+ return Err(client_err(format!(+ "{} asset(s) failed: {names}",+ summary.failed.len()+ )));+ }+ Ok(())+}++#[cfg(test)]+mod tests {+ use super::*;+ use std::sync::Mutex;++ #[test]+ fn manifest_defines_assets_detects_catalog_lists_only() {+ assert!(manifest_defines_assets(+ "protocol: openviking-assets/1\ncatalog:\n - name: alpha\n connector: git\n"+ ));+ assert!(!manifest_defines_assets("assets:\n - alpha\n"));+ assert!(!manifest_defines_assets(+ "catalog: ../assets.yaml\nassets:\n - alpha\n"+ ));+ assert!(!manifest_defines_assets(": not yaml ["));+ }++ type PreflightCall = (String, Option<Map<String, Value>>);+ type SubmitCall = (String, Option<String>, f64, Option<Map<String, Value>>);++ fn write(dir: &Path, name: &str, content: &str) -> PathBuf {+ let path = dir.join(name);+ if let Some(parent) = path.parent() {+ std::fs::create_dir_all(parent).unwrap();+ }+ std::fs::write(&path, content).unwrap();+ path+ }++ fn workspace() -> (tempfile::TempDir, PathBuf, PathBuf, Vec<ResolvedAsset>) {+ let dir = tempfile::tempdir().unwrap();+ let manifest = dir.path().join("manifest.yaml");+ let catalog = dir.path().join("assets.yaml");+ let assets = vec![+ ResolvedAsset {+ name: "alpha".into(),+ connector: "git".into(),+ repo_url: "https://github.com/org/alpha".into(),+ branch: Some("main".into()),+ auth_ref: None,+ watch_interval: 30.0,+ locator: "github.com/org/alpha".into(),+ git_ref: "main".into(),+ asset_id: "alpha-id".into(),+ },+ ResolvedAsset {+ name: "beta".into(),+ connector: "git".into(),+ repo_url: "https://github.com/org/beta".into(),+ branch: None,+ auth_ref: None,+ watch_interval: 30.0,+ locator: "github.com/org/beta".into(),+ git_ref: String::new(),+ asset_id: "beta-id".into(),+ },+ ResolvedAsset {+ name: "gamma".into(),+ connector: "git".into(),+ repo_url: "[email protected]:org/gamma.git".into(),+ branch: Some("dev".into()),+ auth_ref: None,+ watch_interval: 0.0,+ locator: "github.com/org/gamma".into(),+ git_ref: "dev".into(),+ asset_id: "gamma-id".into(),+ },+ ];+ (dir, manifest, catalog, assets)+ }++ #[test]+ fn state_roundtrip_and_orphans() {+ let dir = tempfile::tempdir().unwrap();+ let manifest = dir.path().join("manifest.yaml");+ let mut state = load_state(&manifest).unwrap();+ state.record(+ "abc",+ AssetStateEntry {+ name: "repo".into(),+ connector: "git".into(),+ locator: "github.com/org/repo".into(),+ git_ref: "main".into(),+ status: "submitted".into(),+ resource_uri: Some("viking://resources/repo".into()),+ task_id: Some("task-1".into()),+ ..Default::default()+ },+ );+ state.save().unwrap();++ let loaded = load_state(&manifest).unwrap();+ assert_eq!(+ loaded.assets["abc"].resource_uri.as_deref(),+ Some("viking://resources/repo")+ );+ assert!(loaded.assets["abc"].last_applied_at.is_some());+ let ids: HashSet<String> = HashSet::new();+ assert_eq!(loaded.orphans(&ids).len(), 1);++ std::fs::write(state_path_for(&manifest), "{not json").unwrap();+ assert!(load_state(&manifest).is_err());+ std::fs::write(+ state_path_for(&manifest),+ r#"{"protocol": "openviking-assets-state/99", "assets": {}}"#,+ )+ .unwrap();+ let err = load_state(&manifest).unwrap_err().to_string();+ assert!(err.contains("unsupported protocol"), "{err}");+ }++ struct FakeSubmitter {+ preflight_fail_names: Vec<&'static str>,+ fail_names: Vec<&'static str>,+ preflight_calls: Mutex<Vec<PreflightCall>>,+ calls: Mutex<Vec<SubmitCall>>,+ }++ impl FakeSubmitter {+ fn new(fail_names: Vec<&'static str>) -> Self {+ Self {+ preflight_fail_names: Vec::new(),+ fail_names,+ preflight_calls: Mutex::new(Vec::new()),+ calls: Mutex::new(Vec::new()),+ }+ }++ fn with_preflight_fail(preflight_fail_names: Vec<&'static str>) -> Self {+ Self {+ preflight_fail_names,+ fail_names: Vec::new(),+ preflight_calls: Mutex::new(Vec::new()),+ calls: Mutex::new(Vec::new()),+ }+ }+ }++ impl Submitter for FakeSubmitter {+ async fn preflight(+ &self,+ asset: &ResolvedAsset,+ args: Option<Map<String, Value>>,+ ) -> Result<Value> {+ self.preflight_calls+ .lock()+ .unwrap()+ .push((asset.name.clone(), args));+ if self.preflight_fail_names.contains(&asset.name.as_str()) {+ return Err(client_err(format!("access denied: {}", asset.name)));+ }+ Ok(json!({"accessible": true}))+ }++ async fn submit(+ &self,+ asset: &ResolvedAsset,+ to: Option<String>,+ watch_interval: f64,+ args: Option<Map<String, Value>>,+ ) -> Result<Value> {+ self.calls+ .lock()+ .unwrap()+ .push((asset.name.clone(), to, watch_interval, args));+ if self.fail_names.contains(&asset.name.as_str()) {+ return Err(client_err(format!("boom: {}", asset.name)));+ }+ Ok(json!({+ "root_uri": format!("viking://resources/{}", asset.name),+ "task_id": format!("task-{}", asset.name),+ }))+ }+ }++ fn run_opts() -> ManifestRunOptions {+ ManifestRunOptions::default()+ }++ async fn run(+ manifest: &Path,+ catalog: &Path,+ assets: &[ResolvedAsset],+ creds: &Path,+ opts: &ManifestRunOptions,+ submitter: &FakeSubmitter,+ ) -> (ApplySummary, Vec<Value>) {+ let mut events = Vec::new();+ let summary = {+ let mut emit = |event: Value| events.push(event);+ apply_manifest_core(manifest, catalog, assets, creds, opts, submitter, &mut emit)+ .await+ .unwrap()+ };+ (summary, events)+ }++ #[tokio::test]+ async fn fresh_apply_then_sync() {+ let (dir, manifest, catalog, assets) = workspace();+ let creds = dir.path().join("no-creds.yaml");+ let submitter = FakeSubmitter::new(vec![]);+ let (summary, _) = run(+ &manifest,+ &catalog,+ &assets,+ &creds,+ &run_opts(),+ &submitter,+ )+ .await;+ assert_eq!(summary.succeeded, ["alpha", "beta", "gamma"]);+ {+ let calls = submitter.calls.lock().unwrap();+ assert!(calls.iter().all(|(_, to, _, _)| to.is_none()));+ assert_eq!(calls[0].2, 30.0);+ assert_eq!(calls[2].2, 0.0);+ let alpha_args = calls[0].3.as_ref().unwrap();+ assert_eq!(alpha_args["branch"], json!("main"));+ assert!(calls[1].3.is_none());+ }++ // Second run syncs with to=<uri> from state.+ let submitter2 = FakeSubmitter::new(vec![]);+ let (summary2, events) = run(+ &manifest,+ &catalog,+ &assets,+ &creds,+ &run_opts(),+ &submitter2,+ )+ .await;+ assert_eq!(summary2.succeeded.len(), 3);+ let calls = submitter2.calls.lock().unwrap();+ assert_eq!(calls[0].1.as_deref(), Some("viking://resources/alpha"));+ let actions: Vec<&str> = events+ .iter()+ .filter(|e| e["event"] == "asset_done")+ .map(|e| e["action"].as_str().unwrap())+ .collect();+ assert_eq!(actions, ["sync", "sync", "sync"]);+ }++ #[tokio::test]+ async fn fail_fast_and_skip_failed() {+ let (dir, manifest, catalog, assets) = workspace();+ let creds = dir.path().join("no-creds.yaml");++ let submitter = FakeSubmitter::new(vec!["beta"]);+ let (summary, _) = run(+ &manifest,+ &catalog,+ &assets,+ &creds,+ &run_opts(),+ &submitter,+ )+ .await;+ assert_eq!(summary.succeeded, ["alpha"]);+ assert!(summary.failed.contains_key("beta"));+ assert_eq!(summary.not_attempted, ["gamma"]);+ assert_eq!(submitter.calls.lock().unwrap().len(), 2);++ let submitter = FakeSubmitter::new(vec!["beta"]);+ let opts = ManifestRunOptions {+ skip_failed: true,+ ..run_opts()+ };+ let (summary, _) = run(&manifest, &catalog, &assets, &creds, &opts, &submitter).await;+ assert_eq!(summary.succeeded, ["alpha", "gamma"]);+ assert!(!summary.all_failed());++ let submitter = FakeSubmitter::new(vec!["alpha", "beta", "gamma"]);+ let (summary, _) = run(&manifest, &catalog, &assets, &creds, &opts, &submitter).await;+ assert!(summary.all_failed());+ }++ #[tokio::test]+ async fn dry_run_submits_nothing_and_writes_no_state() {+ let (dir, manifest, catalog, assets) = workspace();+ let creds = dir.path().join("no-creds.yaml");+ let submitter = FakeSubmitter::new(vec![]);+ let opts = ManifestRunOptions {+ dry_run: true,+ ..run_opts()+ };+ let (summary, events) = run(&manifest, &catalog, &assets, &creds, &opts, &submitter).await;+ assert_eq!(summary.total, 3);+ assert_eq!(submitter.preflight_calls.lock().unwrap().len(), 3);+ assert!(submitter.calls.lock().unwrap().is_empty());+ assert!(!state_path_for(&manifest).exists());+ let planned = events+ .iter()+ .filter(|e| e["event"] == "asset_planned")+ .count();+ assert_eq!(planned, 3);+ }++ #[tokio::test]+ async fn preflight_failure_aborts_before_any_submission_or_state_write() {+ let (dir, manifest, catalog, assets) = workspace();+ let creds = dir.path().join("no-creds.yaml");+ let submitter = FakeSubmitter::with_preflight_fail(vec!["beta"]);+ let mut events = Vec::new();+ let err = {+ let mut emit = |event: Value| events.push(event);+ apply_manifest_core(+ &manifest,+ &catalog,+ &assets,+ &creds,+ &ManifestRunOptions {+ skip_failed: true,+ ..run_opts()+ },+ &submitter,+ &mut emit,+ )+ .await+ .unwrap_err()+ };++ assert!(err.to_string().contains("access denied: beta"));+ assert_eq!(submitter.preflight_calls.lock().unwrap().len(), 2);+ assert!(submitter.calls.lock().unwrap().is_empty());+ assert!(!state_path_for(&manifest).exists());+ assert!(+ events+ .iter()+ .any(|event| event["event"] == "asset_preflight_failed")+ );+ }++ #[tokio::test]+ async fn orphan_reported_but_kept() {+ let (dir, manifest, catalog, assets) = workspace();+ let creds = dir.path().join("no-creds.yaml");+ let submitter = FakeSubmitter::new(vec![]);+ run(+ &manifest,+ &catalog,+ &assets,+ &creds,+ &run_opts(),+ &submitter,+ )+ .await;++ let submitter = FakeSubmitter::new(vec![]);+ let (_, events) = run(+ &manifest,+ &catalog,+ &assets[..2],+ &creds,+ &run_opts(),+ &submitter,+ )+ .await;+ let orphans: Vec<&Value> = events.iter().filter(|e| e["event"] == "orphan").collect();+ assert_eq!(orphans.len(), 1);+ assert_eq!(orphans[0]["name"], json!("gamma"));+ assert_eq!(load_state(&manifest).unwrap().assets.len(), 3);+ }++ #[tokio::test]+ async fn auth_ref_precheck_and_merge() {+ let (dir, manifest, catalog, mut assets) = workspace();+ assets[0].auth_ref = Some("team-git".into());++ // Missing alias fails before anything is submitted.+ let submitter = FakeSubmitter::new(vec![]);+ let creds = dir.path().join("no-creds.yaml");+ let mut emit = |_event: Value| {};+ let err = apply_manifest_core(+ &manifest,+ &catalog,+ &assets,+ &creds,+ &run_opts(),+ &submitter,+ &mut emit,+ )+ .await+ .unwrap_err()+ .to_string();+ assert!(err.contains("team-git"), "{err}");+ assert!(submitter.calls.lock().unwrap().is_empty());++ // Resolvable alias merges its args into the submit args.+ let creds = write(+ dir.path(),+ "creds.yaml",+ "credentials:\n team-git:\n token: sekrit\n",+ );+ let submitter = FakeSubmitter::new(vec![]);+ run(+ &manifest,+ &catalog,+ &assets,+ &creds,+ &run_opts(),+ &submitter,+ )+ .await;+ let preflight_calls = submitter.preflight_calls.lock().unwrap();+ let alpha_preflight_args = preflight_calls[0].1.as_ref().unwrap();+ assert_eq!(alpha_preflight_args["token"], json!("sekrit"));+ drop(preflight_calls);+ let calls = submitter.calls.lock().unwrap();+ let alpha_args = calls[0].3.as_ref().unwrap();+ assert_eq!(alpha_args["token"], json!("sekrit"));+ assert_eq!(alpha_args["branch"], json!("main"));+ }+}diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsindex 75da20ddb..ae97e9cd9 100644--- a/crates/ragfs/src/lock/manager.rs+++ b/crates/ragfs/src/lock/manager.rs@@ -355,6 +355,23 @@ impl PathLockManager {PathLockError::Io(format!("lock path '{lock_path}' changed while releasing"))}+ /// Remove one owned token while treating an already-missing token as released.+ ///+ /// A tree lock is stored inside the directory it protects. A successful+ /// recursive delete therefore removes both the directory and its lock token+ /// before the outer lease is released. Keep wrong-owner/CAS changes strict,+ /// but make release idempotent when the token no longer exists.+ async fn remove_owned_token(&self, lock_path: &str, owner_id: &str) -> PathLockResult<()> {+ match self.provider.remove_token(lock_path, owner_id).await {+ Ok(true) => Ok(()),+ Ok(false) => match self.provider.read_token(lock_path).await? {+ None => Ok(()),+ Some(_) => Err(Self::release_changed_error(lock_path)),+ },+ Err(error) => Err(error),+ }+ }+/// Current nanosecond timestamp.fn now_ns() -> u128 {SystemTime::now()@@ -1075,23 +1092,13 @@ impl PathLockManager {let mut failed_paths = Vec::new();let mut first_error = None;for lock_path in release_paths {- match self- .provider- .remove_token(&lock_path, &entry.lease.owner_id)+ if let Err(error) = self+ .remove_owned_token(&lock_path, &entry.lease.owner_id).await{- Ok(true) => {}- Ok(false) => {- failed_paths.push(lock_path.clone());- if first_error.is_none() {- first_error = Some(Self::release_changed_error(&lock_path));- }- }- Err(error) => {- failed_paths.push(lock_path);- if first_error.is_none() {- first_error = Some(error);- }+ failed_paths.push(lock_path);+ if first_error.is_none() {+ first_error = Some(error);}}}@@ -1152,19 +1159,10 @@ impl PathLockManager {let mut failed_paths = Vec::new();let mut first_error = None;for lock_path in release_paths {- match self.provider.remove_token(&lock_path, &owner_id).await {- Ok(true) => {}- Ok(false) => {- failed_paths.push(lock_path.clone());- if first_error.is_none() {- first_error = Some(Self::release_changed_error(&lock_path));- }- }- Err(error) => {- failed_paths.push(lock_path);- if first_error.is_none() {- first_error = Some(error);- }+ if let Err(error) = self.remove_owned_token(&lock_path, &owner_id).await {+ failed_paths.push(lock_path);+ if first_error.is_none() {+ first_error = Some(error);}}}@@ -1630,6 +1628,30 @@ mod tests {)}+ #[tokio::test]+ async fn release_tree_lease_succeeds_after_locked_directory_is_deleted() {+ let fs = Arc::new(MemFileSystem::new());+ fs.mkdir("/data", 0o755).await.unwrap();+ fs.mkdir("/data/delete-me", 0o755).await.unwrap();+ let provider = Arc::new(crate::lock::provider::FilesystemPathLockProvider::new(+ fs.clone(),+ ));+ let mgr = PathLockManager::new(fs.clone(), provider, PathLockConfig::default());+ let lease = mgr+ .acquire_tree("/data/delete-me", Duration::ZERO, None)+ .await+ .unwrap();++ fs.remove_all("/data/delete-me").await.unwrap();++ mgr.release(&lease).await.unwrap();+ assert!(mgr+ .get_owned_lease_by_ref(&lease.lease.lease_ref)+ .await+ .is_none());+ assert_eq!(mgr.metrics_snapshot().await.active_lock_count, 0);+ }+#[tokio::test]async fn acquire_exact_reentrant_requires_local_owned_capability() {let mgr = make_manager().await;diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex f6309d90c..d0f8582ed 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -219,6 +219,7 @@ const apiReferenceSidebar = {{text: 'Protocols & Extensions',items: [+ ['22-openviking-assets.md', 'OpenViking Assets'],['20-webdav.md', 'WebDAV'],['24-vikingbot.md', 'VikingBot API']]@@ -278,6 +279,7 @@ const apiReferenceSidebar = {{text: '协议与扩展',items: [+ ['22-openviking-assets.md', 'OpenViking Assets'],['20-webdav.md', 'WebDAV'],['24-vikingbot.md', 'VikingBot API']]@@ -387,6 +389,7 @@ const guidesSidebar = {items: [['06-mcp-integration.md', 'MCP Integration'],['09-ovpack.md', 'OVPack'],+ ['18-openviking-assets.md', 'OpenViking Assets'],['10-prompt-guide.md', 'Prompt Customization'],['17-vikingbot.md', 'VikingBot']]@@ -429,6 +432,7 @@ const guidesSidebar = {items: [['06-mcp-integration.md', 'MCP 集成'],['09-ovpack.md', 'OVPack'],+ ['18-openviking-assets.md', 'OpenViking Assets'],['10-prompt-guide.md', 'Prompt 自定义'],['17-vikingbot.md', 'VikingBot']]diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.mdindex 074bb50bd..9d8d7385b 100644--- a/docs/en/api/01-overview.md+++ b/docs/en/api/01-overview.md@@ -550,10 +550,12 @@ This catalog follows the routes actually mounted by the server. Each group headi| POST | `/api/v1/privacy-configs/{category}/{target_key}` | Write and activate a new version || POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | Activate a version |-### [WebDAV](20-webdav.md) and [VikingBot API](24-vikingbot.md)+### [OpenViking Assets](22-openviking-assets.md), [WebDAV](20-webdav.md), and [VikingBot API](24-vikingbot.md)| Method | Path | Description ||--------|------|-------------|+| POST | `/api/v1/openviking-assets/resolve` | Parse and validate a Catalog and Manifest, returning a normalized asset plan |+| POST | `/api/v1/openviking-assets/preflight` | Read-only access check for a Git repository and ref || OPTIONS | `/webdav/resources`, `/webdav/resources/{resource_path}` | Query WebDAV capabilities || PROPFIND | `/webdav/resources`, `/webdav/resources/{resource_path}` | Query resource properties || GET / HEAD | `/webdav/resources`, `/webdav/resources/{resource_path}` | Read a file or directory |@@ -581,4 +583,4 @@ The sidebar is organized by responsibility rather than historical file size:| Data Lifecycle | Watches, snapshots, and OVPack || Operations & Observability | System, tasks, Observer, and Metrics || Identity & Governance | Administration and privacy configuration |-| Protocols & Extensions | WebDAV and VikingBot API |+| Protocols & Extensions | OpenViking Assets, WebDAV, and VikingBot API |diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.mdindex d0a2ccb64..2305e724b 100644--- a/docs/en/api/02-resources.md+++ b/docs/en/api/02-resources.md@@ -660,3 +660,4 @@ Possible shared response:- [Skills](04-skills.md) - Skill management APIs- [Retrieval](06-retrieval.md) - Search and context acquisition- [ovpack Guide](../guides/09-ovpack.md) - Detailed ovpack import/export documentation+- [OpenViking Assets](../guides/18-openviking-assets.md) - Declarative resource-set protocol and usage guidediff --git a/docs/en/api/22-openviking-assets.md b/docs/en/api/22-openviking-assets.mdnew file mode 100644index 000000000..59a4569aa--- /dev/null+++ b/docs/en/api/22-openviking-assets.md@@ -0,0 +1,178 @@+# OpenViking Assets Resolver++The OpenViking Assets Resolver parses and validates an+[`openviking-assets/1`](../guides/18-openviking-assets.md) Manifest — either+self-contained, with assets defined under its `catalog` field, or paired with a+separate Catalog file — then returns a normalized asset plan for a client to+execute. It does not clone repositories, create resources, or start+synchronization jobs.++In normal use, run `ov add-resource --manifest <file>`; the CLI calls the+Resolver and permission-preflight endpoints automatically. Call these endpoints+directly only when implementing a custom client.++## Resolve a Manifest++```http+POST /api/v1/openviking-assets/resolve+```++### Authentication++The endpoint uses the standard OpenViking Server authentication mechanism. When+API-key authentication is enabled, include:++```http+X-API-Key: <your-api-key>+```++### Request body++| Field | Type | Required | Default | Description |+| --- | --- | --- | --- | --- |+| `manifest_yaml` | string | Yes | — | Complete Manifest YAML, 1–4,000,000 characters |+| `catalog_yaml` | string | No | — | Complete Catalog YAML, 1–4,000,000 characters. Required when the Manifest selects assets by name; must be omitted when the Manifest defines assets under `catalog`. |+| `manifest_label` | string | No | `manifest.yaml` | Manifest source label used in errors, 1–1,024 characters |+| `catalog_label` | string | No | `assets.yaml` | Catalog source label used in errors, 1–1,024 characters |++Example with a self-contained Manifest:++```bash+curl -X POST "${OPENVIKING_BASE_URL}/api/v1/openviking-assets/resolve" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: ${OPENVIKING_API_KEY}" \+ --data-binary @- <<'JSON'+{+ "manifest_yaml": "protocol: openviking-assets/1\ncatalog:\n - name: openviking\n connector: git\n watch_interval: 1440\n params:\n repo_url: https://github.com/volcengine/OpenViking\n branch: main\n",+ "manifest_label": "manifest.yaml"+}+JSON+```++When a Manifest selects assets by name, send the Catalog YAML in `catalog_yaml`+and its label in `catalog_label`.++### Success response++```json+{+ "status": "ok",+ "result": {+ "protocol": "openviking-assets/1",+ "manifest": "manifest.yaml",+ "catalog": "manifest.yaml",+ "assets": [+ {+ "name": "openviking",+ "connector": "git",+ "repo_url": "https://github.com/volcengine/OpenViking",+ "branch": "main",+ "auth_ref": null,+ "watch_interval": 1440.0,+ "locator": "github.com/volcengine/OpenViking",+ "git_ref": "main",+ "asset_id": "a1b2c3d4e5f6"+ }+ ]+ }+}+```++Where:++- `locator` is the normalized repository locator.+- `git_ref` is the resolved Git reference.+- `asset_id` is a stable 12-character identifier derived from the connector,+ normalized locator, and Git reference. The value above illustrates the format.+- `watch_interval` is measured in minutes.+- `catalog` echoes `catalog_label`; for a self-contained Manifest it equals the+ Manifest label.++### Error responses++Protocol or content validation failures return HTTP `400` with the error code+`INVALID_ARGUMENT`. Common causes include:++- malformed YAML or unknown fields;+- a `protocol` other than `openviking-assets/1`, or a Manifest that defines+ `catalog` without declaring `protocol`;+- a non-empty `include`, which v1 does not support;+- a Manifest that defines `catalog` submitted together with `catalog_yaml`;+- a Manifest that selects assets by name without any `catalog_yaml`;+- a Manifest referencing an asset absent from the Catalog;+- an invalid connector, repository URL, Git reference, or asset identity;+- duplicate asset identities in one Manifest.++Empty fields, incorrect field types, or length-limit violations are rejected by+request validation with HTTP `422`.++## Preflight Git repository access++```http+POST /api/v1/openviking-assets/preflight+```++This endpoint runs read-only `git ls-remote` in the OpenViking Server execution+environment to verify that a repository and optional ref are readable. It does+not clone the repository, create a resource, or start a task. Manifest mode+calls it during both dry-run and pre-submission validation.++### Request body++| Field | Type | Required | Description |+| --- | --- | --- | --- |+| `name` | string | Yes | Asset name |+| `connector` | string | Yes | Must currently be `git` |+| `repo_url` | string | Yes | Git clone URL |+| `branch` | string | No | Branch or tag to verify; the remote `HEAD` is checked when omitted |+| `auth_config.username` | string | No | HTTP Basic username; defaults to `oauth2` |+| `auth_config.token` | string | No | One-shot Git token; never persisted |++```bash+curl -X POST "${OPENVIKING_BASE_URL}/api/v1/openviking-assets/preflight" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: ${OPENVIKING_API_KEY}" \+ -d '{+ "name": "private-repository",+ "connector": "git",+ "repo_url": "https://github.com/example/private-repository",+ "branch": "main",+ "auth_config": {+ "username": "oauth2",+ "token": "<github-token>"+ }+ }'+```++When a token is provided explicitly, preflight does not fall back to a server+Git credential helper. The token is passed through the child-process+environment and does not appear in Git command arguments or the response.++### Success response++```json+{+ "status": "ok",+ "result": {+ "name": "private-repository",+ "connector": "git",+ "locator": "github.com/example/private-repository",+ "git_ref": "main",+ "accessible": true+ }+}+```++### Error responses++| HTTP status | Error code | Meaning |+| --- | --- | --- |+| `403` | `PERMISSION_DENIED` | Repository missing, invalid credentials, or insufficient read permission |+| `404` | `NOT_FOUND` | Repository is readable, but the requested branch/tag is absent |+| `503` | `UNAVAILABLE` | DNS, connection, or Git executable unavailable |+| `504` | `DEADLINE_EXCEEDED` | Permission preflight exceeded 15 seconds |++## Related documentation++- [OpenViking Assets protocol and operations guide](../guides/18-openviking-assets.md)+- [Resource Management API](02-resources.md)diff --git a/docs/en/guides/18-openviking-assets.md b/docs/en/guides/18-openviking-assets.mdnew file mode 100644index 000000000..83868a4a5--- /dev/null+++ b/docs/en/guides/18-openviking-assets.md@@ -0,0 +1,460 @@+# OpenViking Assets++> Experimental. The `openviking-assets/1` protocol and CLI behavior may change in later releases.++OpenViking Assets describes what a knowledge base should contain as declarative files. In the+simplest form, one Manifest file defines the assets to ingest. A team can also keep its ingestible+sources in a shared Catalog and write Manifests that select named assets for different use cases.+Applying a Manifest creates or updates each resource and stores the mapping between assets and+`viking://` resources locally.++It is intended for multi-repository code knowledge bases, shared documentation sets, and other+resource collections that need to be reproducible and continuously refreshed.++## How It Differs from Other Resource Operations++| Capability | Description |+| --- | --- |+| `ov add-resource <source>` | Adds or updates one resource; it describes one operation. |+| OpenViking Assets | Declares the expected composition of a resource set for review, sharing, and repeated application. |+| OVPack | Exports or imports an existing data snapshot, including content and optional index data. |++OpenViking Assets does not replace the existing ingestion pipeline. Git fetching, parsing,+semantic extraction, vectorization, and Watch refreshes still use `add_resource` and server-side+connectors. Assets adds only the declaration, resolution, and per-asset orchestration layers.++## Conceptual Model++OpenViking Assets has three primary objects:++- **Manifest**: the file you apply. It defines the assets to ingest directly under `catalog:`, or+ selects assets by name from a separate Catalog file.+- **Catalog**: the inventory of sources a team can ingest, including source locations, branches,+ default refresh intervals, and credential aliases. It is a separate file only when several+ Manifests share it; otherwise it lives inside the Manifest.+- **State**: the result of the last Manifest application and the mapping from assets to+ `viking://` resources.++```text+manifest.yaml (+ assets.yaml when a shared Catalog is used)+ |+ v+Server resolves and validates openviking-assets/1+ |+ v+Resolved Assets+ |+ v+CLI resolves local credentials and State+ |+ v+One add_resource call per asset -> viking:// resources+```++The server is the authoritative protocol parser. The CLI sends the raw Manifest YAML — plus the+Catalog YAML when a separate Catalog file is used — to the configured OpenViking service. The+server validates them and returns an execution plan; the resolver endpoint itself does not create+resources.++## Protocol++### Manifest++A Manifest describes one knowledge-base build. In the simplest form it is the only file you need:+define the assets directly under `catalog:`:++```yaml+protocol: openviking-assets/1++defaults:+ git:+ auth_ref: team-git+ watch_interval: 1440++catalog:+ - name: openviking+ connector: git+ description: OpenViking main repository+ params:+ repo_url: https://github.com/volcengine/OpenViking+ branch: main++ - name: requests+ connector: git+ description: Requests HTTP client source+ watch_interval: 0+ params:+ repo_url: https://github.com/psf/requests+ branch: main++assets: [openviking] # optional; omit to apply every asset defined above+```++Manifest top-level fields:++| Field | Required | Description |+| --- | --- | --- |+| `protocol` | Yes when `catalog` is present | Must currently be `openviking-assets/1`. Optional for Manifests that only select names, but still checked when set. |+| `defaults` | No | Connector defaults for the assets defined in this Manifest; only allowed together with `catalog`. |+| `catalog` | No | The list of asset definitions (fields below). A Manifest that defines `catalog` is complete on its own. |+| `assets` | See description | Asset names to apply. Optional when `catalog` is in the same file — omitting it applies every defined asset. Required when the definitions live in a separate Catalog file. |+| `include` | No | v1 cannot compose other Manifests; a non-empty value fails resolution. |++Duplicate selected names are removed while preserving their first position. Selecting an unknown+asset fails the whole resolution.++`defaults.git` supports:++| Field | Description |+| --- | --- |+| `auth_ref` | Default alias in the local credentials file. |+| `watch_interval` | Default Watch interval in minutes; `0` disables automatic refresh. |++Git assets support:++| Field | Required | Description |+| --- | --- | --- |+| `name` | Yes | Unique asset name matching `[A-Za-z0-9][A-Za-z0-9._-]*`. |+| `connector` | Yes | v1 supports only `git`. |+| `description` | No | Human-readable purpose of the asset. |+| `params.repo_url` | Yes | Git clone URL. |+| `params.branch` | No | Branch to ingest; it cannot be empty when set. |+| `auth_ref` | No | Overrides `defaults.git.auth_ref`. |+| `watch_interval` | No | Overrides `defaults.git.watch_interval`. |++Validation is strict. Unknown fields, duplicate names, and unsupported connectors fail the whole+resolution, even for assets the current run does not select. `params` contents and clone URL+safety are validated for the selected assets. The same rules apply wherever the definitions live —+in the Manifest's `catalog` or in a separate Catalog file.++### Sharing a Catalog Across Manifests++When several Manifests reuse the same sources, move the asset definitions into a Catalog file,+normally named `assets.yaml`. A Catalog holds `protocol`, optional `defaults`, and the same asset+definitions under `assets`:++```yaml+protocol: openviking-assets/1++defaults:+ git:+ auth_ref: team-git+ watch_interval: 1440++assets:+ - name: openviking+ connector: git+ description: OpenViking main repository+ params:+ repo_url: https://github.com/volcengine/OpenViking+ branch: main++ - name: requests+ connector: git+ description: Requests HTTP client source+ watch_interval: 0+ params:+ repo_url: https://github.com/psf/requests+ branch: main+```++Each Manifest then only selects names:++```yaml+assets:+ - openviking+ - requests+```++The team maintains one Catalog; editing an asset there updates every Manifest that selects it.++The CLI locates the Catalog file as follows:++1. The path passed to `--catalog <file>`, resolved from the current working directory.+2. `assets.yaml` next to the Manifest when `--catalog` is omitted.++A Manifest that defines `catalog` itself never uses a separate Catalog file; passing one with it+fails resolution.++### Asset Identity++The server generates a stable `asset_id` from:++```text+connector + normalized locator + ref+```++Git URL normalization removes the protocol, user prefix, host port, trailing `.git`, and trailing+slashes, and lowercases the host. HTTPS, SSH, and SCP-style URLs for the same repository therefore+normally produce the same locator, while different branches produce different assets.++The asset name is not part of the identity. Renaming an asset without changing its source and+branch keeps it associated with the existing resource. Changing the source or branch produces a+new asset and leaves the previous one as an orphan.++For safety, clone URLs cannot:++- be empty or contain control characters;+- begin with `-`;+- use Git remote-helper transports such as `ext::` or `fd::`.++## Quick Start++### Prerequisites++1. Install an `ov` CLI version that supports OpenViking Assets.+2. Configure an OpenViking service that provides `/api/v1/openviking-assets/resolve`.+3. Verify the connection:++```bash+ov health+```++### Write and Validate a Manifest++Create `manifest.yaml`:++```yaml+protocol: openviking-assets/1++catalog:+ - name: openviking+ connector: git+ params:+ repo_url: https://github.com/volcengine/OpenViking+ branch: main+```++Validate it first:++```bash+ov add-resource --manifest manifest.yaml --dry-run+```++`--dry-run`:++- reads the local YAML file, plus the Catalog file when one is used;+- asks the configured OpenViking service to resolve and validate the protocol;+- checks that all selected `auth_ref` aliases resolve locally;+- asks the server to run a read-only `git ls-remote` permission preflight for every repository+ with the effective credentials;+- prints the create or sync action planned for each asset;+- does not clone repositories, submit resources, create tasks, or write State.++If any repository is unreadable, dry-run exits immediately with `PERMISSION_DENIED` and does not+produce an executable plan.++### Apply the Manifest++Remove `--dry-run` after reviewing the plan:++```bash+ov add-resource --manifest manifest.yaml+```++Wait for each resource to finish processing:++```bash+ov add-resource --manifest manifest.yaml --wait --timeout 600+```++The repository contains a complete example, including a shared Catalog with several Manifests,+under+[`examples/openviking-assets`](https://github.com/volcengine/OpenViking/tree/main/examples/openviking-assets).++## Credentials++Manifests and Catalogs carry only `auth_ref` aliases and must not contain tokens, passwords, or+private keys.+The CLI resolves aliases from this file by default:++```text+~/.openviking/openviking_assets_credentials.yaml+```++Example:++```yaml+credentials:+ team-git:+ username: oauth2+ token: replace-with-your-token+```++Override the path with:++```bash+export OPENVIKING_ASSETS_CREDENTIALS_FILE=/secure/path/assets-credentials.yaml+```++Before submitting any resource, the CLI resolves every selected `auth_ref`, then the server runs+`git ls-remote` in the execution environment to verify read access to every repository. A missing+alias or unreadable repository fails the whole operation before the first submission; dry-run+performs the same preflight. Resolved Git arguments are sent to the preflight and resource+endpoints over the configured OpenViking service connection. Use TLS for remote deployments and+restrict local access to the credentials file.++Omit `auth_ref` when the target service already has the SSH keys or other authentication needed to+access the repository.++## Create, Sync, and State++After a non-dry-run application, the CLI writes this file next to the Manifest:++```text+<manifest-file>.state.json+```++For example:++```text+code-qa.yaml.state.json+```++State uses the `openviking-assets-state/1` protocol and records:++- the `asset_id`, name, connector, locator, and ref;+- the corresponding `resource_uri` and `task_id`;+- the latest status, error, and application time.++Application rules:++| Condition | Behavior |+| --- | --- |+| State has no resource URI for the `asset_id` | Create a new resource. |+| State has an existing resource URI | Sync by passing the URI as `to` to `add_resource`. |+| An asset is no longer selected | Report it as an orphan; keep its resource and State entry. |+| The source or branch changes the `asset_id` | Create a new asset and report the old one as an orphan. |++State belongs to one execution environment and is not part of the Catalog or Manifest protocol.+A repository that shares Manifests should normally add this to its `.gitignore`:++```text+*.state.json+```++Do not apply the same Manifest concurrently. The current State file has no cross-process lock.++Content-level synchronization cursors do not live in Manifest State. Continuous refreshes are+managed by OpenViking Watches and connectors.++## Refresh Intervals++`watch_interval` precedence, from highest to lowest, is:++1. CLI `--watch-interval`;+2. per-asset `watch_interval`;+3. `defaults.git.watch_interval`;+4. `0`, which disables automatic refresh.++Temporarily apply a 60-minute interval to every selected asset:++```bash+ov add-resource --manifest manifest.yaml --watch-interval 60+```++Subsequent content refreshes are performed by Watches. You do not need to apply the Manifest on a+schedule. Reapply it to pick up Catalog or Manifest composition changes, retry failed assets, or+explicitly trigger synchronization.++## Failure Handling++Permission preflight runs before every resource submission. If any asset fails preflight:++1. the command exits immediately with the original error code, such as `PERMISSION_DENIED`;+2. no asset is submitted and no background task is created;+3. State is not written;+4. `--skip-failed` does not bypass the preflight failure.++Per-asset execution starts only after all preflights succeed.++The default behavior is fail-fast:++1. the current asset fails;+2. later assets are marked not attempted;+3. successful assets and the failure are written to State;+4. the command exits non-zero.++Use `--skip-failed` to continue with the remaining assets:++```bash+ov add-resource --manifest manifest.yaml --skip-failed+```++`--skip-failed` does not turn a partial failure into success. The command still exits non-zero when+any asset fails, and successfully created resources are not rolled back. If every asset fails, the+command reports that nothing was applied successfully.++## CLI Options++Primary Manifest-mode options:++| Option | Description |+| --- | --- |+| `-m, --manifest <file>` | Manifest file. |+| `--catalog <file>` | Separate Catalog file for Manifests that select assets by name; defaults to `assets.yaml` next to the Manifest. Not used when the Manifest defines `catalog` itself. |+| `--dry-run` | Resolve the protocol and validate read access to every repository without submitting resources, creating tasks, or writing State. |+| `--skip-failed` | Continue processing after an asset fails. |+| `--wait` | Wait for each resource to finish processing. |+| `--timeout <seconds>` | Timeout used with `--wait`. |+| `--watch-interval <minutes>` | Override the refresh interval for all assets. |+| `--processing-mode <mode>` | Use `semantic_and_vectors` or `vectors_only` for every asset. |++`--to`, `--parent`, `--parent-auto-create`, `--args`, `--strict`, `--ignore-dirs`, `--include`,+and `--exclude` belong to single-resource mode and cannot be combined with `--manifest`.++`--reason`, `--instruction`, `--no-directly-upload-media`, `--progress`, `--no-progress`, and+`--verbose` are not currently applied to assets in Manifest mode. Do not rely on them in Manifest+commands.++## Structured Output++Default output is intended for terminal use. With JSON output, Manifest mode emits NDJSON: one+complete JSON event per line rather than one JSON document.++```bash+ov --output json add-resource --manifest manifest.yaml --dry-run+```++Events can include:++- `plan`+- `orphan`+- `asset_preflight_start`+- `asset_preflight_ok`+- `asset_preflight_failed`+- `asset_planned`+- `asset_start`+- `asset_done`+- `asset_failed`+- `asset_skipped`+- `summary`++Automation should parse one line at a time and always use the process exit code. When a `summary`+event is emitted, it can provide additional result details. A preflight failure exits before+`summary`. Do not assume the first line is `plan`: `orphan` events, when present, are emitted+before it.++## Current Limitations++`openviking-assets/1` currently has these boundaries:++- only Git assets are supported;+- Manifests are flat and cannot recursively `include` other Manifests;+- the server resolver returns a plan and does not perform batch submission;+- the server preflight uses read-only `git ls-remote` to check repository access and does not+ download repository contents;+- the CLI executes assets sequentially;+- orphans are never deleted automatically;+- `ov share` pointer codes and exporting a Manifest from an existing knowledge base are not+ included;+- State is a local file and is not synchronized across machines;+- the CLI and server must both support the same protocol version.++## Related Documentation++- [OpenViking Assets API](../api/22-openviking-assets.md)+- [Resource Management API](../api/02-resources.md)+- [Resource Watch API](../api/15-watches.md)+- [OVPack Import and Export](09-ovpack.md)+- [OpenViking Assets Examples](https://github.com/volcengine/OpenViking/tree/main/examples/openviking-assets)diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex 862bc3d9b..9048e1ec0 100644--- a/docs/zh/api/01-overview.md+++ b/docs/zh/api/01-overview.md@@ -545,10 +545,12 @@ JSON 输出 - 错误:| POST | `/api/v1/privacy-configs/{category}/{target_key}` | 写入并激活新版本 || POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | 激活指定版本 |-### [WebDAV](20-webdav.md) 与 [VikingBot API](24-vikingbot.md)+### [OpenViking Assets](22-openviking-assets.md)、[WebDAV](20-webdav.md) 与 [VikingBot API](24-vikingbot.md)| 方法 | 路径 | 说明 ||------|------|------|+| POST | `/api/v1/openviking-assets/resolve` | 解析并校验 Catalog 与 Manifest,返回标准化资产计划 |+| POST | `/api/v1/openviking-assets/preflight` | 只读校验 Git 仓库和 ref 的访问权限 || OPTIONS | `/webdav/resources`、`/webdav/resources/{resource_path}` | 查询 WebDAV 能力 || PROPFIND | `/webdav/resources`、`/webdav/resources/{resource_path}` | 查询资源属性 || GET / HEAD | `/webdav/resources`、`/webdav/resources/{resource_path}` | 读取文件或目录 |@@ -576,4 +578,4 @@ JSON 输出 - 错误:| 数据生命周期 | Watch、快照、OVPack || 运维与观测 | 系统、任务、Observer、Metrics || 身份与治理 | 管理员、隐私配置 |-| 协议与扩展 | WebDAV、VikingBot API |+| 协议与扩展 | OpenViking Assets、WebDAV、VikingBot API |diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.mdindex e54daba18..7c3d284c7 100644--- a/docs/zh/api/02-resources.md+++ b/docs/zh/api/02-resources.md@@ -668,3 +668,4 @@ shared 模式的响应示例:- [技能](04-skills.md) - 技能管理 API- [检索](06-retrieval.md) - 搜索和上下文获取- [ovpack 指南](../guides/09-ovpack.md) - ovpack 导入导出详细说明+- [OpenViking Assets](../guides/18-openviking-assets.md) - 声明式资源集合协议和运行指南diff --git a/docs/zh/api/22-openviking-assets.md b/docs/zh/api/22-openviking-assets.mdnew file mode 100644index 000000000..5c6b9d60f--- /dev/null+++ b/docs/zh/api/22-openviking-assets.md@@ -0,0 +1,168 @@+# OpenViking Assets Resolver++OpenViking Assets Resolver 用于解析并校验+[`openviking-assets/1`](../guides/18-openviking-assets.md) Manifest——既支持在+`catalog` 字段中直接定义资产的单文件 Manifest,也支持搭配单独 Catalog 文件的+Manifest——并返回可供客户端执行的标准化资产计划。它不会克隆仓库、创建资源或启动+同步任务。++通常应直接使用 `ov add-resource --manifest <file>`;CLI 会自动调用 Resolver 和+权限预检接口。只有在开发自定义客户端时,才需要直接请求这些接口。++## 解析 Manifest++```http+POST /api/v1/openviking-assets/resolve+```++### 鉴权++接口沿用 OpenViking Server 的标准鉴权方式。启用 API Key 时,请在请求中传入:++```http+X-API-Key: <your-api-key>+```++### 请求体++| 字段 | 类型 | 必填 | 默认值 | 说明 |+| --- | --- | --- | --- | --- |+| `manifest_yaml` | string | 是 | — | Manifest 的完整 YAML 内容,长度为 1~4,000,000 字符 |+| `catalog_yaml` | string | 否 | — | Catalog 的完整 YAML 内容,长度为 1~4,000,000 字符。Manifest 按名称选择资产时必填;Manifest 在 `catalog` 中定义资产时必须省略。 |+| `manifest_label` | string | 否 | `manifest.yaml` | Manifest 的来源标签,用于错误信息,长度为 1~1,024 字符 |+| `catalog_label` | string | 否 | `assets.yaml` | Catalog 的来源标签,用于错误信息,长度为 1~1,024 字符 |++单文件 Manifest 示例:++```bash+curl -X POST "${OPENVIKING_BASE_URL}/api/v1/openviking-assets/resolve" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: ${OPENVIKING_API_KEY}" \+ --data-binary @- <<'JSON'+{+ "manifest_yaml": "protocol: openviking-assets/1\ncatalog:\n - name: openviking\n connector: git\n watch_interval: 1440\n params:\n repo_url: https://github.com/volcengine/OpenViking\n branch: main\n",+ "manifest_label": "manifest.yaml"+}+JSON+```++Manifest 按名称选择资产时,把 Catalog YAML 放入 `catalog_yaml`,来源标签放入+`catalog_label` 一并发送。++### 成功响应++```json+{+ "status": "ok",+ "result": {+ "protocol": "openviking-assets/1",+ "manifest": "manifest.yaml",+ "catalog": "manifest.yaml",+ "assets": [+ {+ "name": "openviking",+ "connector": "git",+ "repo_url": "https://github.com/volcengine/OpenViking",+ "branch": "main",+ "auth_ref": null,+ "watch_interval": 1440.0,+ "locator": "github.com/volcengine/OpenViking",+ "git_ref": "main",+ "asset_id": "a1b2c3d4e5f6"+ }+ ]+ }+}+```++其中:++- `locator` 是规范化后的仓库定位符。+- `git_ref` 是最终解析出的 Git 引用。+- `asset_id` 是由连接器、规范化定位符与 Git 引用生成的 12 位稳定标识;示例值仅作格式说明。+- `watch_interval` 的单位是分钟。+- `catalog` 回显 `catalog_label`;单文件 Manifest 时与 Manifest 标签相同。++### 错误响应++协议或内容校验失败时返回 HTTP `400`,错误码为 `INVALID_ARGUMENT`。常见原因包括:++- YAML 无法解析或包含未知字段;+- `protocol` 不是 `openviking-assets/1`,或 Manifest 定义了 `catalog` 却没有声明 `protocol`;+- Manifest 使用了 v1 尚不支持的非空 `include`;+- Manifest 定义了 `catalog`,请求却同时传入了 `catalog_yaml`;+- Manifest 按名称选择资产,请求却没有提供 `catalog_yaml`;+- Manifest 引用了 Catalog 中不存在的资产;+- 连接器、仓库 URL、Git 引用或资产身份不合法;+- 同一份 Manifest 中出现重复资产身份。++请求字段为空、类型错误或超过长度限制时,由请求模型返回 HTTP `422`。++## 预检 Git 仓库权限++```http+POST /api/v1/openviking-assets/preflight+```++该接口在 OpenViking Server 的实际运行环境执行只读 `git ls-remote`,校验仓库和可选 ref+是否可读。它不会克隆仓库、创建资源或启动任务。Manifest 模式在 dry-run 和正式提交之前+都会调用该接口。++### 请求体++| 字段 | 类型 | 必填 | 说明 |+| --- | --- | --- | --- |+| `name` | string | 是 | 资产名称 |+| `connector` | string | 是 | 当前必须是 `git` |+| `repo_url` | string | 是 | Git clone URL |+| `branch` | string | 否 | 要验证的 branch 或 tag;省略时验证远端 `HEAD` |+| `auth_config.username` | string | 否 | HTTP Basic 用户名,默认 `oauth2` |+| `auth_config.token` | string | 否 | 一次性 Git token,不持久化 |++```bash+curl -X POST "${OPENVIKING_BASE_URL}/api/v1/openviking-assets/preflight" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: ${OPENVIKING_API_KEY}" \+ -d '{+ "name": "private-repository",+ "connector": "git",+ "repo_url": "https://github.com/example/private-repository",+ "branch": "main",+ "auth_config": {+ "username": "oauth2",+ "token": "<github-token>"+ }+ }'+```++显式传入 token 时,preflight 不会回退到服务端 Git credential helper。token 通过子进程+环境传递,不出现在 Git 命令参数和响应中。++### 成功响应++```json+{+ "status": "ok",+ "result": {+ "name": "private-repository",+ "connector": "git",+ "locator": "github.com/example/private-repository",+ "git_ref": "main",+ "accessible": true+ }+}+```++### 错误响应++| HTTP 状态 | 错误码 | 说明 |+| --- | --- | --- |+| `403` | `PERMISSION_DENIED` | 仓库不存在、凭据无效或当前身份没有读取权限 |+| `404` | `NOT_FOUND` | 仓库可访问,但指定 branch/tag 不存在 |+| `503` | `UNAVAILABLE` | DNS、连接或 Git 可执行文件不可用 |+| `504` | `DEADLINE_EXCEEDED` | 权限预检超过 15 秒 |++## 相关文档++- [OpenViking Assets 协议与运行指南](../guides/18-openviking-assets.md)+- [资源管理 API](02-resources.md)diff --git a/docs/zh/guides/18-openviking-assets.md b/docs/zh/guides/18-openviking-assets.mdnew file mode 100644index 000000000..9ddc0c35a--- /dev/null+++ b/docs/zh/guides/18-openviking-assets.md@@ -0,0 +1,435 @@+# OpenViking Assets++> 实验性功能。`openviking-assets/1` 协议和命令行行为仍可能在后续版本中调整。++OpenViking Assets 用声明文件描述“一个知识库应该由哪些资源组成”。最简单的形态是+一个 Manifest 文件直接定义要接入的资产;团队也可以在共享的 Catalog 中维护可接入+资源的全集,再用多个 Manifest 按名称选择不同用途所需的资源。执行 Manifest 时,+OpenViking 会逐项创建或更新资源,并在本地保存资产与 `viking://` 资源之间的映射。++它适合管理多仓代码问答库、团队文档集和其他需要重复构建、持续更新的资源集合。++## 与其他资源操作的区别++| 能力 | 描述 |+| --- | --- |+| `ov add-resource <source>` | 添加或更新一个资源,描述的是一次资源操作。 |+| OpenViking Assets | 声明一组资源的预期构成,可以 review、共享并重复执行。 |+| OVPack | 导出或导入已经生成的数据快照,搬运的是内容和可选索引数据。 |++OpenViking Assets 不替代现有资源处理流程。Git 拉取、内容解析、语义提取、向量化和+Watch 更新仍由 `add_resource` 及服务端连接器完成;Assets 只增加声明、解析和逐项编排。++## 概念模型++OpenViking Assets 包含三个主要对象:++- **Manifest**:实际执行的文件。可以在 `catalog:` 下直接定义要接入的资产,也可以按名称+ 从单独的 Catalog 文件中选择资产。+- **Catalog**:团队可接入资源的目录,包含来源、分支、默认更新周期和凭据别名。只有在多个+ Manifest 需要共享时才作为单独文件存在,否则直接写在 Manifest 里。+- **State**:某个 Manifest 上次执行的结果,以及资产到 `viking://` 资源的映射。++```text+manifest.yaml(使用共享 Catalog 时再加 assets.yaml)+ |+ v+服务端解析和校验 openviking-assets/1+ |+ v+Resolved Assets+ |+ v+CLI 解析本地凭据和 State+ |+ v+逐个调用 add_resource -> viking:// resources+```++服务端是协议解析的权威实现。CLI 会把 Manifest 的原始 YAML(使用单独 Catalog 文件时+一并发送 Catalog YAML)发送到当前配置的 OpenViking 服务,由服务端完成严格校验并返回+执行计划;服务端的解析接口本身不会创建资源。++## 协议++### Manifest++Manifest 描述一次知识库构建。最简单的形态下它是唯一需要的文件:在 `catalog:` 下+直接定义资产:++```yaml+protocol: openviking-assets/1++defaults:+ git:+ auth_ref: team-git+ watch_interval: 1440++catalog:+ - name: openviking+ connector: git+ description: OpenViking 主仓库+ params:+ repo_url: https://github.com/volcengine/OpenViking+ branch: main++ - name: requests+ connector: git+ description: Requests HTTP 客户端源码+ watch_interval: 0+ params:+ repo_url: https://github.com/psf/requests+ branch: main++assets: [openviking] # 可选:省略 = 执行上面定义的全部资产+```++Manifest 顶层字段:++| 字段 | 必填 | 说明 |+| --- | --- | --- |+| `protocol` | 定义 `catalog` 时必填 | 当前必须为 `openviking-assets/1`;只按名称选择资产的 Manifest 可省略,但设置时同样会校验。 |+| `defaults` | 否 | 为本文件定义的资产设置连接器级默认值;只能与 `catalog` 一起使用。 |+| `catalog` | 否 | 资产定义列表(字段见下)。定义了 `catalog` 的 Manifest 自身就是完整配置。 |+| `assets` | 见说明 | 要执行的资产名称。`catalog` 在同一文件中时可省略——省略表示执行全部定义的资产;资产定义在单独 Catalog 文件中时必填。 |+| `include` | 否 | v1 不支持组合其他 Manifest;非空时解析失败。 |++重复的资产名称会按首次出现的位置去重。选择不存在的资产时,整个解析失败。++`defaults.git` 支持:++| 字段 | 说明 |+| --- | --- |+| `auth_ref` | 本地凭据文件中的默认别名。 |+| `watch_interval` | 默认 Watch 周期,单位为分钟;`0` 表示不自动刷新。 |++Git 资产支持:++| 字段 | 必填 | 说明 |+| --- | --- | --- |+| `name` | 是 | 唯一资产名称,必须匹配 `[A-Za-z0-9][A-Za-z0-9._-]*`。 |+| `connector` | 是 | v1 只支持 `git`。 |+| `description` | 否 | 资产用途说明。 |+| `params.repo_url` | 是 | Git clone URL。 |+| `params.branch` | 否 | 要接入的分支;设置时不能为空。 |+| `auth_ref` | 否 | 覆盖 `defaults.git.auth_ref`。 |+| `watch_interval` | 否 | 覆盖 `defaults.git.watch_interval`。 |++校验是严格的:未知字段、重复资产名和不支持的连接器都会使整个解析失败,即使有问题的资产+没有被本次执行选择。`params` 内容和 clone URL 安全性针对被选中的资产校验。这些规则与+资产定义所在的位置无关——写在 Manifest 的 `catalog` 里和写在单独的 Catalog 文件里完全相同。++### 多个 Manifest 共享一个 Catalog++当多个 Manifest 复用同一批资源时,把资产定义移到单独的 Catalog 文件中,通常命名为+`assets.yaml`。Catalog 包含 `protocol`、可选的 `defaults`,以及 `assets` 下的资产定义:++```yaml+protocol: openviking-assets/1++defaults:+ git:+ auth_ref: team-git+ watch_interval: 1440++assets:+ - name: openviking+ connector: git+ description: OpenViking 主仓库+ params:+ repo_url: https://github.com/volcengine/OpenViking+ branch: main++ - name: requests+ connector: git+ description: Requests HTTP 客户端源码+ watch_interval: 0+ params:+ repo_url: https://github.com/psf/requests+ branch: main+```++每个 Manifest 只需按名称选择:++```yaml+assets:+ - openviking+ - requests+```++全团队维护一份 Catalog;在 Catalog 中修改资产,所有选择它的 Manifest 都会生效。++CLI 按以下规则查找 Catalog 文件:++1. 传入 `--catalog <file>` 时使用该路径;相对路径基于当前工作目录。+2. 未传入时读取 Manifest 所在目录下的 `assets.yaml`。++定义了 `catalog` 的 Manifest 不使用单独的 Catalog 文件;同时传入会导致解析失败。++### 资产身份++服务端根据以下信息生成稳定的 `asset_id`:++```text+connector + normalized locator + ref+```++Git URL 会去除协议、用户名前缀、端口、结尾的 `.git` 和 `/`,并把主机名统一为小写。+因此,同一仓库的 HTTPS、SSH 和 SCP 风格地址通常会得到相同定位符;不同分支会得到不同资产。++资产名称不参与身份计算。重命名资产但保持来源和分支不变时,会继续关联原资源;修改来源或+分支时会产生新资产,旧资源被报告为 orphan。++出于安全原因,clone URL 不能:++- 为空或包含控制字符;+- 以 `-` 开头;+- 使用 `ext::`、`fd::` 等 Git remote-helper 传输格式。++## 快速开始++### 前置条件++1. 安装支持 OpenViking Assets 的 `ov` CLI。+2. 配置支持 `/api/v1/openviking-assets/resolve` 的 OpenViking 服务。+3. 确认 CLI 可以连接服务:++```bash+ov health+```++### 编写并验证 Manifest++创建 `manifest.yaml`:++```yaml+protocol: openviking-assets/1++catalog:+ - name: openviking+ connector: git+ params:+ repo_url: https://github.com/volcengine/OpenViking+ branch: main+```++先验证:++```bash+ov add-resource --manifest manifest.yaml --dry-run+```++`--dry-run` 会完成以下操作:++- 读取本地 YAML 文件(使用单独 Catalog 文件时一并读取);+- 调用当前 OpenViking 服务解析并校验协议;+- 检查所有 `auth_ref` 是否能在本地解析;+- 让服务端使用最终凭据对每个 Git 仓库执行只读 `git ls-remote` 权限预检;+- 输出每个资产将执行的 create 或 sync 操作;+- 不克隆仓库、不提交资源、不创建任务,也不写入 State。++任何仓库不可读时,dry-run 立即以 `PERMISSION_DENIED` 退出,不再输出可执行计划。++### 应用 Manifest++确认计划后去掉 `--dry-run`:++```bash+ov add-resource --manifest manifest.yaml+```++等待每个资源处理完成:++```bash+ov add-resource --manifest manifest.yaml --wait --timeout 600+```++仓库中包含一个完整示例(含共享 Catalog 和多个 Manifest),位于+[`examples/openviking-assets`](https://github.com/volcengine/OpenViking/tree/main/examples/openviking-assets)。++## 凭据++Manifest 和 Catalog 只保存 `auth_ref` 别名,不应保存 token、密码或私钥。CLI 默认从以下+文件解析别名:++```text+~/.openviking/openviking_assets_credentials.yaml+```++示例:++```yaml+credentials:+ team-git:+ username: oauth2+ token: replace-with-your-token+```++可以使用环境变量覆盖文件位置:++```bash+export OPENVIKING_ASSETS_CREDENTIALS_FILE=/secure/path/assets-credentials.yaml+```++执行前,CLI 会先解析所有选中资产的 `auth_ref`,然后由服务端在实际执行环境中用+`git ls-remote` 校验每个仓库的读取权限。只要有一个别名不存在或仓库不可读,整个操作都会+在提交任何资源之前失败;`--dry-run` 也执行相同预检。解析出的 Git 参数会通过当前配置的+OpenViking 服务连接发送给 preflight 和资源接口,因此远程部署应使用 TLS,并限制凭据文件+的本地访问权限。++如果目标服务已经具备访问仓库所需的 SSH key 或其他认证配置,可以不设置 `auth_ref`。++## Create、Sync 和 State++非 dry-run 执行后,CLI 在 Manifest 旁写入:++```text+<manifest-file>.state.json+```++例如:++```text+code-qa.yaml.state.json+```++State 使用 `openviking-assets-state/1` 协议,记录:++- `asset_id`、名称、连接器、定位符和 ref;+- 对应的 `resource_uri` 和 `task_id`;+- 最近一次执行状态、错误和时间。++执行规则:++| 条件 | 行为 |+| --- | --- |+| State 中没有该 `asset_id` 的资源 URI | create:创建新资源。 |+| State 中已有资源 URI | sync:把 URI 作为 `to` 再次调用 `add_resource`。 |+| 资产不再被 Manifest 选择 | 报告 orphan,保留资源和 State,不自动删除。 |+| `asset_id` 因来源或分支变化 | 创建新资产,旧资产成为 orphan。 |++State 属于执行环境,不是 Catalog 或 Manifest 协议的一部分。共享 Manifest 仓库通常应在+`.gitignore` 中加入:++```text+*.state.json+```++不要并发执行同一个 Manifest;当前 State 文件不提供跨进程锁。++内容级同步进度不保存在 Manifest State 中。持续刷新由 OpenViking Watch 和连接器负责。++## 更新周期++`watch_interval` 的优先级从高到低为:++1. CLI 的 `--watch-interval`;+2. 单个资产的 `watch_interval`;+3. `defaults.git.watch_interval`;+4. `0`,不自动刷新。++例如,临时把 Manifest 中全部资产调整为每 60 分钟刷新:++```bash+ov add-resource --manifest manifest.yaml --watch-interval 60+```++后续内容刷新由 Watch 执行,不需要周期性重新运行 Manifest。重新运行 Manifest 主要用于应用+Catalog 或 Manifest 的构成变化、恢复失败资产,或显式触发同步。++## 失败处理++权限预检先于所有资源提交。任一资产预检失败时:++1. 命令立即以原始错误码退出,例如 `PERMISSION_DENIED`;+2. 不提交任何资产,不创建后台任务;+3. 不写入 State;+4. `--skip-failed` 不会跳过预检失败。++只有全部预检成功后,才进入以下逐资产执行阶段。++默认采用 fail-fast:++1. 当前资产失败;+2. 后续资产标记为未尝试;+3. 已成功资产和失败记录写入 State;+4. 命令以非零状态退出。++使用 `--skip-failed` 可以继续处理其余资产:++```bash+ov add-resource --manifest manifest.yaml --skip-failed+```++`--skip-failed` 不会把部分失败转换为成功。只要有资产失败,命令最终仍以非零状态退出;+已经成功的资源不会回滚。全部资产失败时,命令会报告没有任何资产成功应用。++## 命令行选项++Manifest 模式的主要参数:++| 参数 | 说明 |+| --- | --- |+| `-m, --manifest <file>` | Manifest 文件。 |+| `--catalog <file>` | 按名称选择资产的 Manifest 使用的单独 Catalog 文件;省略时使用 Manifest 同目录的 `assets.yaml`。Manifest 自身定义了 `catalog` 时不使用。 |+| `--dry-run` | 解析协议并校验所有仓库的读取权限;不提交资源、不创建任务、不写 State。 |+| `--skip-failed` | 一个资产失败后继续处理其他资产。 |+| `--wait` | 等待每个资源处理完成。 |+| `--timeout <seconds>` | `--wait` 的超时时间。 |+| `--watch-interval <minutes>` | 覆盖全部资产的更新周期。 |+| `--processing-mode <mode>` | 所有资产使用 `semantic_and_vectors` 或 `vectors_only`。 |++`--to`、`--parent`、`--parent-auto-create`、`--args`、`--strict`、`--ignore-dirs`、+`--include` 和 `--exclude` 属于单资源模式,不能与 `--manifest` 一起使用。++`--reason`、`--instruction`、`--no-directly-upload-media`、`--progress`、`--no-progress` 和+`--verbose` 当前不会应用到 Manifest 中的资产,Manifest 模式下不要依赖这些参数。++## 结构化输出++默认输出适合终端阅读。使用 JSON 输出时,Manifest 模式会输出 NDJSON,即每行一个完整的+JSON 事件,而不是一个单独的 JSON 文档:++```bash+ov --output json add-resource --manifest manifest.yaml --dry-run+```++可能出现的事件包括:++- `plan`+- `orphan`+- `asset_preflight_start`+- `asset_preflight_ok`+- `asset_preflight_failed`+- `asset_planned`+- `asset_start`+- `asset_done`+- `asset_failed`+- `asset_skipped`+- `summary`++自动化程序应逐行解析,并始终以进程退出码判断结果;执行到 `summary` 时可结合该事件。+preflight 失败会在 `summary` 之前立即退出。注意不要假设第一行一定是 `plan`:存在 orphan+时,`orphan` 事件会先于 `plan` 输出。++## 当前限制++`openviking-assets/1` 当前具有以下边界:++- 只支持 Git 资产;+- Manifest 必须平铺,不支持递归 `include`;+- 服务端 resolver 只返回计划,不执行批量提交;+- 服务端 preflight 通过只读 `git ls-remote` 校验仓库权限,不下载仓库内容;+- CLI 按顺序逐个执行资产;+- 不自动删除 orphan;+- 不包含 `ov share` 指针码或从现有知识库导出 Manifest 的能力;+- State 是本地文件,不在多台机器之间自动同步;+- CLI 和服务端都必须支持同一协议版本。++## 相关文档++- [OpenViking Assets API](../api/22-openviking-assets.md)+- [资源管理 API](../api/02-resources.md)+- [资源 Watch API](../api/15-watches.md)+- [OVPack 导入导出](09-ovpack.md)+- [OpenViking Assets 示例](https://github.com/volcengine/OpenViking/tree/main/examples/openviking-assets)diff --git a/examples/openviking-assets/assets.yaml b/examples/openviking-assets/assets.yamlnew file mode 100644index 000000000..f8e166d18--- /dev/null+++ b/examples/openviking-assets/assets.yaml@@ -0,0 +1,31 @@+# OpenViking Assets catalog — the team-wide inventory of ingestable sources.+# Credentials never appear here; `auth_ref` aliases resolve on each+# consumer's machine (~/.openviking/openviking_assets_credentials.yaml).+protocol: openviking-assets/1++defaults:+ git:+ watch_interval: 1440 # minutes; refresh every repo daily unless overridden++assets:+ - name: openviking+ connector: git+ description: OpenViking main repository — server, CLI and SDKs+ params:+ repo_url: https://github.com/volcengine/OpenViking+ branch: main++ - name: requests+ connector: git+ description: python-requests source, for HTTP client Q&A+ params:+ repo_url: https://github.com/psf/requests+ branch: main++ - name: flask+ connector: git+ description: Flask source, small enough for quick pilot runs+ watch_interval: 0 # override: no automatic refresh for this one+ params:+ repo_url: [email protected]:pallets/flask.git+ branch: maindiff --git a/examples/openviking-assets/manifest.yaml b/examples/openviking-assets/manifest.yamlnew file mode 100644index 000000000..5c3ffcb08--- /dev/null+++ b/examples/openviking-assets/manifest.yaml@@ -0,0 +1,21 @@+# Self-contained OpenViking Assets manifest: assets are defined right here+# under `catalog:`, so no separate catalog file is needed.+# ov add-resource --manifest manifest.yaml --dry-run+# Credentials never appear here; `auth_ref` aliases resolve on each consumer's+# machine (~/.openviking/openviking_assets_credentials.yaml).+protocol: openviking-assets/1++catalog:+ - name: openviking+ connector: git+ description: OpenViking main repository — server, CLI and SDKs+ params:+ repo_url: https://github.com/volcengine/OpenViking+ branch: main++ - name: flask+ connector: git+ description: Flask source, small enough for quick pilot runs+ watch_interval: 0 # no automatic refresh for this one+ params:+ repo_url: [email protected]:pallets/flask.gitdiff --git a/examples/openviking-assets/manifests/code-qa.yaml b/examples/openviking-assets/manifests/code-qa.yamlnew file mode 100644index 000000000..2c0d031c3--- /dev/null+++ b/examples/openviking-assets/manifests/code-qa.yaml@@ -0,0 +1,7 @@+# OpenViking Assets build recipe for the "code Q&A" knowledge base.+# Selects assets by name from the shared catalog. Pass the catalog explicitly+# with `--catalog ../assets.yaml` when running this manifest from its directory.+assets:+ - openviking+ - requests+ - flaskdiff --git a/openviking/server/app.py b/openviking/server/app.pyindex 42169fd5e..08fbb64be 100644--- a/openviking/server/app.py+++ b/openviking/server/app.py@@ -39,6 +39,7 @@ from openviking.server.routers import (filesystem_router,metrics_router,observer_router,+ openviking_assets_router,pack_router,privacy_configs_router,relations_router,@@ -89,7 +90,6 @@ def create_worker_app() -> FastAPI:config.bot_api_url = bot_api_urlreturn create_app(config, config_path=config_path)-async def _initialize_auth_plugin(app: FastAPI,service: OpenVikingService,@@ -588,6 +588,7 @@ def create_app(app.include_router(pack_router)app.include_router(debug_router)app.include_router(observer_router)+ app.include_router(openviking_assets_router)app.include_router(metrics_router)app.include_router(tasks_router)app.include_router(user_settings_router)diff --git a/openviking/server/openviking_assets.py b/openviking/server/openviking_assets.pynew file mode 100644index 000000000..da4d077a8--- /dev/null+++ b/openviking/server/openviking_assets.py@@ -0,0 +1,487 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Server-side parsing and validation for OpenViking Assets manifests."""++from __future__ import annotations++import asyncio+import base64+import hashlib+import math+import os+import re+from typing import Any++import yaml+from pydantic import BaseModel, ConfigDict, ValidationError++from openviking.server.local_input_guard import require_remote_resource_source+from openviking_cli.exceptions import (+ DeadlineExceededError,+ InvalidArgumentError,+ NotFoundError,+ PermissionDeniedError,+ UnavailableError,+)++PROTOCOL = "openviking-assets/1"+GIT_PREFLIGHT_TIMEOUT_SECONDS = 15.0+_ASSET_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")+_REMOTE_HELPER_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*::")+_NETWORK_FAILURE_PATTERNS = (+ "could not resolve host",+ "connection refused",+ "connection timed out",+ "network is unreachable",+ "no route to host",+ "failed to connect",+ "temporary failure in name resolution",+)+++class _StrictModel(BaseModel):+ model_config = ConfigDict(extra="forbid", strict=True)+++class _GitDefaults(_StrictModel):+ auth_ref: str | None = None+ watch_interval: float | None = None+++class _Defaults(_StrictModel):+ git: _GitDefaults | None = None+++class _CatalogAsset(_StrictModel):+ name: str+ connector: str+ description: str = ""+ params: dict[str, Any]+ auth_ref: str | None = None+ watch_interval: float | None = None+++class _Catalog(_StrictModel):+ protocol: str+ defaults: _Defaults | None = None+ assets: list[_CatalogAsset]+++class _Manifest(_StrictModel):+ protocol: str | None = None+ defaults: _Defaults | None = None+ catalog: list[_CatalogAsset] | str | None = None+ include: list[str] | None = None+ assets: list[str] | None = None+++class _GitParams(_StrictModel):+ repo_url: str+ branch: str | None = None+++class ResolvedAsset(_StrictModel):+ """A manifest selection joined with its catalog entry and defaults."""++ name: str+ connector: str+ repo_url: str+ branch: str | None = None+ auth_ref: str | None = None+ watch_interval: float+ locator: str+ git_ref: str+ asset_id: str+++class ResolveResult(_StrictModel):+ protocol: str = PROTOCOL+ manifest: str+ catalog: str+ assets: list[ResolvedAsset]+++def _validation_message(what: str, label: str, exc: ValidationError) -> str:+ error = exc.errors(include_url=False)[0]+ location = ".".join(str(part) for part in error.get("loc", ()))+ detail = str(error.get("msg") or "invalid value")+ suffix = f" at '{location}'" if location else ""+ return f"{what} '{label}'{suffix}: {detail}"+++def _parse_yaml(text: str, model: type[_StrictModel], what: str, label: str) -> _StrictModel:+ try:+ value = yaml.safe_load(text)+ except yaml.YAMLError as exc:+ raise InvalidArgumentError(f"{what} '{label}': invalid YAML: {exc}") from exc+ if not isinstance(value, dict):+ raise InvalidArgumentError(f"{what} '{label}' must contain a YAML mapping")+ try:+ return model.model_validate(value)+ except ValidationError as exc:+ raise InvalidArgumentError(_validation_message(what, label, exc)) from exc+++def _check_watch_interval(value: float | None, where: str) -> float | None:+ if value is not None and (not math.isfinite(value) or value < 0):+ raise InvalidArgumentError(f"{where}: 'watch_interval' must be >= 0")+ return value+++def _strip_port(host: str) -> str:+ head, separator, tail = host.rpartition(":")+ if separator and tail and tail.isascii() and tail.isdigit():+ return head+ return host+++def normalize_repo_url(url: str) -> str:+ """Normalize supported Git URL forms into a stable host/path locator."""++ value = url.strip()+ if not value:+ return ""+ lowered = value.lower()+ protocol = next(+ (+ prefix+ for prefix in ("ssh://", "git://", "http://", "https://")+ if lowered.startswith(prefix)+ ),+ None,+ )+ if protocol:+ value = value[len(protocol) :]+ if "@" in value:+ user, remainder = value.split("@", 1)+ if user and "/" not in user and ":" not in user:+ value = remainder+ if protocol is None:+ slash = value.find("/")+ colon = value.find(":")+ if colon >= 0 and (slash < 0 or colon < slash):+ value = f"{value[:colon]}/{value[colon + 1 :]}"+ while "//" in value:+ value = value.replace("//", "/")+ if "/" in value:+ host, path = value.split("/", 1)+ value = f"{_strip_port(host).lower()}/{path}"+ else:+ value = _strip_port(value).lower()+ if value.lower().endswith(".git"):+ value = value[:-4]+ return value.rstrip("/")+++def _validate_clone_url(url: str, asset_name: str) -> None:+ label = f"asset '{asset_name}' params.repo_url"+ if not url.strip():+ raise InvalidArgumentError(f"{label} is empty")+ if any(ord(char) < 0x20 for char in url):+ raise InvalidArgumentError(f"{label} contains control characters")+ value = url.strip()+ if value.startswith("-"):+ raise InvalidArgumentError(f"{label} starts with '-' (git would read it as a flag)")+ if _REMOTE_HELPER_RE.match(value):+ raise InvalidArgumentError(+ f"{label} uses a git remote-helper transport ('helper::...'); "+ "use https://, ssh://, git://, or a git@host:path URL"+ )+++def _asset_id(connector: str, locator: str, git_ref: str) -> str:+ identity = f"{connector}\n{locator}\n{git_ref}".encode()+ return hashlib.sha1(identity).hexdigest()[:12] # noqa: S324 - stable identity, not security+++def _append_git_process_config(env: dict[str, str], key: str, value: str) -> None:+ """Append one process-local Git config entry without putting secrets in argv."""++ try:+ count = int(env.get("GIT_CONFIG_COUNT", "0"))+ except ValueError:+ count = 0+ env[f"GIT_CONFIG_KEY_{count}"] = key+ env[f"GIT_CONFIG_VALUE_{count}"] = value+ env["GIT_CONFIG_COUNT"] = str(count + 1)+++async def preflight_git_repository(+ *,+ asset_name: str,+ repo_url: str,+ branch: str | None = None,+ username: str | None = None,+ token: str | None = None,+ timeout: float = GIT_PREFLIGHT_TIMEOUT_SECONDS,+) -> dict[str, Any]:+ """Verify that the server can read a Git source without cloning or creating a task."""++ _validate_clone_url(repo_url, asset_name)+ repo_url = require_remote_resource_source(repo_url)+ if timeout <= 0 or not math.isfinite(timeout):+ raise InvalidArgumentError("Git preflight timeout must be a positive finite number")++ normalized_branch = branch.strip() if branch else ""+ if branch is not None and not normalized_branch:+ raise InvalidArgumentError(+ f"asset '{asset_name}': branch must be a non-empty string when set"+ )++ normalized_token = token or ""+ normalized_username = (username or ("oauth2" if normalized_token else "")).strip()+ if normalized_token and not repo_url.strip().lower().startswith(("http://", "https://")):+ raise InvalidArgumentError(+ f"asset '{asset_name}': token authentication requires an HTTP(S) Git URL"+ )+ if normalized_token and not normalized_username:+ raise InvalidArgumentError(+ f"asset '{asset_name}': username must be non-empty when token is set"+ )++ env = os.environ.copy()+ env["GIT_TERMINAL_PROMPT"] = "0"+ env["GCM_INTERACTIVE"] = "Never"+ env.setdefault("GIT_SSH_COMMAND", "ssh -o BatchMode=yes")+ if normalized_token:+ # An explicit auth_ref must be authoritative: disable credential-helper+ # fallback and pass HTTP Basic auth through process-local config.+ _append_git_process_config(env, "credential.helper", "")+ encoded = base64.b64encode(+ f"{normalized_username}:{normalized_token}".encode()+ ).decode()+ _append_git_process_config(env, "http.extraHeader", f"Authorization: Basic {encoded}")+ elif normalized_username:+ _append_git_process_config(env, "credential.username", normalized_username)++ command = ["git", "ls-remote", "--exit-code", repo_url]+ if normalized_branch:+ command.extend(+ [+ f"refs/heads/{normalized_branch}",+ f"refs/tags/{normalized_branch}",+ ]+ )+ else:+ command.append("HEAD")++ try:+ process = await asyncio.create_subprocess_exec(+ *command,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ env=env,+ )+ except FileNotFoundError as exc:+ raise UnavailableError("git", "executable not found on the OpenViking Server") from exc++ try:+ _stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)+ except TimeoutError as exc:+ process.kill()+ await process.communicate()+ raise DeadlineExceededError("Git repository permission preflight", timeout) from exc++ locator = normalize_repo_url(repo_url)+ if process.returncode == 0:+ return {+ "name": asset_name,+ "connector": "git",+ "locator": locator,+ "git_ref": normalized_branch,+ "accessible": True,+ }++ error_text = stderr.decode(errors="replace").lower()+ if any(pattern in error_text for pattern in _NETWORK_FAILURE_PATTERNS):+ raise UnavailableError(+ "Git repository",+ f"network preflight failed for asset '{asset_name}' ({locator})",+ )+ if process.returncode == 2 and normalized_branch:+ raise NotFoundError(normalized_branch, "git_ref")+ raise PermissionDeniedError(+ f"Cannot read Git repository for asset '{asset_name}' ({locator}); "+ "verify auth_ref and repository permissions",+ resource=locator,+ )+++def resolve_openviking_assets(+ *,+ manifest_yaml: str,+ catalog_yaml: str | None = None,+ manifest_label: str = "manifest.yaml",+ catalog_label: str = "assets.yaml",+) -> ResolveResult:+ """Parse and resolve one flat manifest, optionally against a separate catalog.++ A manifest either defines its assets directly under ``catalog`` or selects+ assets by name from a separate catalog file. This API deliberately does not+ follow ``include`` entries and does not submit resources. The caller+ remains responsible for execution.+ """++ manifest = _parse_yaml(manifest_yaml, _Manifest, "manifest", manifest_label)+ assert isinstance(manifest, _Manifest)++ if manifest.protocol is not None and manifest.protocol != PROTOCOL:+ raise InvalidArgumentError(+ f"manifest '{manifest_label}': unsupported protocol '{manifest.protocol}' "+ f"(expected '{PROTOCOL}')"+ )+ if manifest.include:+ raise InvalidArgumentError(+ f"manifest '{manifest_label}': 'include' is not supported by the server resolver; "+ "use a flat manifest"+ )+ if isinstance(manifest.catalog, str):+ raise InvalidArgumentError(+ f"manifest '{manifest_label}': 'catalog' holds asset definitions, not a file "+ "path; define assets under 'catalog' or pass the catalog file separately"+ )++ if manifest.catalog is not None:+ if catalog_yaml is not None:+ raise InvalidArgumentError(+ f"manifest '{manifest_label}' already defines 'catalog'; "+ "do not pass a separate catalog file"+ )+ if manifest.protocol is None:+ raise InvalidArgumentError(+ f"manifest '{manifest_label}': 'protocol' is required when the manifest "+ f"defines 'catalog' (expected '{PROTOCOL}')"+ )+ catalog = _Catalog(protocol=PROTOCOL, defaults=manifest.defaults, assets=manifest.catalog)+ catalog_label = manifest_label+ else:+ if manifest.defaults is not None:+ raise InvalidArgumentError(+ f"manifest '{manifest_label}': 'defaults' is only allowed when the manifest "+ "defines 'catalog'"+ )+ if catalog_yaml is None:+ raise InvalidArgumentError(+ f"manifest '{manifest_label}' selects assets by name but no catalog was "+ "provided; define assets under 'catalog' or pass a catalog file"+ )+ parsed_catalog = _parse_yaml(catalog_yaml, _Catalog, "catalog", catalog_label)+ assert isinstance(parsed_catalog, _Catalog)+ catalog = parsed_catalog+ if catalog.protocol != PROTOCOL:+ raise InvalidArgumentError(+ f"catalog '{catalog_label}': unsupported protocol '{catalog.protocol}' "+ f"(expected '{PROTOCOL}')"+ )++ names: list[str] = []+ seen_names: set[str] = set()+ for name in manifest.assets or []:+ if not name:+ raise InvalidArgumentError(+ f"manifest '{manifest_label}': 'assets' entries must be non-empty strings"+ )+ if name not in seen_names:+ names.append(name)+ seen_names.add(name)+ if manifest.assets is None and manifest.catalog is not None:+ # A single-file manifest without an explicit selection applies everything+ # it defines; duplicate definition names are rejected below.+ names = [asset.name for asset in catalog.assets]+ if not names:+ raise InvalidArgumentError(f"manifest '{manifest_label}' selects no assets")++ git_defaults = catalog.defaults.git if catalog.defaults else None+ default_auth_ref = git_defaults.auth_ref if git_defaults else None+ if default_auth_ref is not None and not default_auth_ref:+ raise InvalidArgumentError("catalog defaults.git: 'auth_ref' must be a non-empty string")+ default_watch = _check_watch_interval(+ git_defaults.watch_interval if git_defaults else None,+ "catalog defaults.git",+ )+ if default_watch is None:+ default_watch = 0.0++ catalog_by_name: dict[str, _CatalogAsset] = {}+ for asset in catalog.assets:+ where = f"catalog '{catalog_label}' asset '{asset.name}'"+ if not _ASSET_NAME_RE.fullmatch(asset.name):+ raise InvalidArgumentError(+ f"catalog '{catalog_label}': asset 'name' is required and must match "+ "[A-Za-z0-9][A-Za-z0-9._-]*"+ )+ if asset.connector != "git":+ raise InvalidArgumentError(+ f"{where}: connector '{asset.connector}' is not supported in {PROTOCOL} "+ "(supported: git)"+ )+ if asset.name in catalog_by_name:+ raise InvalidArgumentError(+ f"catalog '{catalog_label}': duplicate asset name '{asset.name}'"+ )+ if asset.auth_ref is not None and not asset.auth_ref:+ raise InvalidArgumentError(f"{where}: 'auth_ref' must be a non-empty string")+ _check_watch_interval(asset.watch_interval, where)+ catalog_by_name[asset.name] = asset++ missing = [name for name in names if name not in catalog_by_name]+ if missing:+ listed = ", ".join(f"'{name}'" for name in missing)+ if manifest.catalog is not None:+ raise InvalidArgumentError(+ f"manifest '{manifest_label}' selects asset(s) not defined in its "+ f"'catalog': {listed}"+ )+ raise InvalidArgumentError(+ f"manifest '{manifest_label}' references asset(s) not in catalog "+ f"'{catalog_label}': {listed}"+ )++ resolved: list[ResolvedAsset] = []+ identity_names: dict[str, str] = {}+ for name in names:+ asset = catalog_by_name[name]+ where = f"catalog '{catalog_label}' asset '{name}'"+ try:+ params = _GitParams.model_validate(asset.params)+ except ValidationError as exc:+ raise InvalidArgumentError(_validation_message("asset params", where, exc)) from exc+ repo_url = params.repo_url.strip()+ _validate_clone_url(repo_url, name)+ branch = params.branch.strip() if params.branch is not None else None+ if branch == "":+ raise InvalidArgumentError(+ f"{where}: params.branch must be a non-empty string when set"+ )+ locator = normalize_repo_url(repo_url)+ git_ref = branch or ""+ asset_id = _asset_id(asset.connector, locator, git_ref)+ if asset_id in identity_names:+ other = identity_names[asset_id]+ shown_ref = git_ref or "default"+ raise InvalidArgumentError(+ f"assets '{other}' and '{name}' resolve to the same source "+ f"(git:{locator}@{shown_ref}); remove one of them"+ )+ identity_names[asset_id] = name+ resolved.append(+ ResolvedAsset(+ name=name,+ connector=asset.connector,+ repo_url=repo_url,+ branch=branch,+ auth_ref=asset.auth_ref or default_auth_ref,+ watch_interval=(+ asset.watch_interval if asset.watch_interval is not None else default_watch+ ),+ locator=locator,+ git_ref=git_ref,+ asset_id=asset_id,+ )+ )++ return ResolveResult(+ manifest=manifest_label,+ catalog=catalog_label,+ assets=resolved,+ )diff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.pyindex 447a532c1..cd307fe3e 100644--- a/openviking/server/routers/__init__.py+++ b/openviking/server/routers/__init__.py@@ -11,6 +11,7 @@ from openviking.server.routers.debug import router as debug_routerfrom openviking.server.routers.filesystem import router as filesystem_routerfrom openviking.server.routers.metrics import router as metrics_routerfrom openviking.server.routers.observer import router as observer_router+from openviking.server.routers.openviking_assets import router as openviking_assets_routerfrom openviking.server.routers.pack import router as pack_routerfrom openviking.server.routers.privacy_configs import router as privacy_configs_routerfrom openviking.server.routers.relations import router as relations_router@@ -46,6 +47,7 @@ __all__ = ["debug_router","metrics_router","observer_router",+ "openviking_assets_router","tasks_router","user_settings_router","watches_router",diff --git a/openviking/server/routers/openviking_assets.py b/openviking/server/routers/openviking_assets.pynew file mode 100644index 000000000..fe8d590ff--- /dev/null+++ b/openviking/server/routers/openviking_assets.py@@ -0,0 +1,84 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""HTTP endpoint for resolving OpenViking Assets configuration."""++from typing import Literal++from fastapi import APIRouter, Depends+from pydantic import BaseModel, ConfigDict, Field, SecretStr++from openviking.server.auth import get_request_context+from openviking.server.identity import RequestContext+from openviking.server.openviking_assets import (+ preflight_git_repository,+ resolve_openviking_assets,+)+from openviking.server.responses import response_from_result++router = APIRouter(prefix="/api/v1/openviking-assets", tags=["openviking-assets"])+++class ResolveOpenVikingAssetsRequest(BaseModel):+ """Raw YAML inputs for resolving one flat manifest, with an optional separate catalog."""++ model_config = ConfigDict(extra="forbid")++ manifest_yaml: str = Field(min_length=1, max_length=4_000_000)+ catalog_yaml: str | None = Field(default=None, min_length=1, max_length=4_000_000)+ manifest_label: str = Field(default="manifest.yaml", min_length=1, max_length=1024)+ catalog_label: str = Field(default="assets.yaml", min_length=1, max_length=1024)+++class GitAuthConfig(BaseModel):+ """One-shot Git credentials; SecretStr keeps the token out of model reprs."""++ model_config = ConfigDict(extra="forbid")++ username: str = Field(default="oauth2", min_length=1, max_length=256)+ token: SecretStr | None = None+++class PreflightOpenVikingAssetRequest(BaseModel):+ """One resolved asset whose source access must be verified before apply."""++ model_config = ConfigDict(extra="forbid")++ name: str = Field(min_length=1, max_length=256)+ connector: Literal["git"]+ repo_url: str = Field(min_length=1, max_length=8192)+ branch: str | None = Field(default=None, min_length=1, max_length=1024)+ auth_config: GitAuthConfig | None = None++[email protected]("/resolve")+async def resolve_assets(+ request: ResolveOpenVikingAssetsRequest,+ _ctx: RequestContext = Depends(get_request_context),+):+ """Parse and validate configuration without submitting resources."""++ result = resolve_openviking_assets(+ manifest_yaml=request.manifest_yaml,+ catalog_yaml=request.catalog_yaml,+ manifest_label=request.manifest_label,+ catalog_label=request.catalog_label,+ )+ return response_from_result(result.model_dump())++[email protected]("/preflight")+async def preflight_asset(+ request: PreflightOpenVikingAssetRequest,+ _ctx: RequestContext = Depends(get_request_context),+):+ """Verify source readability without cloning, importing, or creating a task."""++ auth = request.auth_config+ result = await preflight_git_repository(+ asset_name=request.name,+ repo_url=request.repo_url,+ branch=request.branch,+ username=auth.username if auth else None,+ token=auth.token.get_secret_value() if auth and auth.token else None,+ )+ return response_from_result(result)diff --git a/tests/server/test_openviking_assets.py b/tests/server/test_openviking_assets.pynew file mode 100644index 000000000..286e66b1f--- /dev/null+++ b/tests/server/test_openviking_assets.py@@ -0,0 +1,304 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Tests for server-side OpenViking Assets configuration resolution."""++import hashlib++import httpx+import pytest++from openviking.server.openviking_assets import (+ normalize_repo_url,+ preflight_git_repository,+ resolve_openviking_assets,+)+from openviking_cli.exceptions import (+ InvalidArgumentError,+ NotFoundError,+ PermissionDeniedError,+)++CATALOG = """\+protocol: openviking-assets/1++defaults:+ git:+ watch_interval: 30++assets:+ - name: alpha+ connector: git+ description: alpha repo+ params:+ repo_url: https://github.com/org/alpha+ branch: main++ - name: beta+ connector: git+ params:+ repo_url: [email protected]:org/beta.git+ watch_interval: 0+"""++MANIFEST = """\+assets:+ - alpha+ - beta+"""++SINGLE_FILE_MANIFEST = """\+protocol: openviking-assets/1++defaults:+ git:+ watch_interval: 30++catalog:+ - name: alpha+ connector: git+ description: alpha repo+ params:+ repo_url: https://github.com/org/alpha+ branch: main++ - name: beta+ connector: git+ params:+ repo_url: [email protected]:org/beta.git+ watch_interval: 0+"""+++def _request(**overrides):+ body = {+ "manifest_yaml": MANIFEST,+ "catalog_yaml": CATALOG,+ "manifest_label": "manifests/code-qa.yaml",+ "catalog_label": "assets.yaml",+ }+ body.update(overrides)+ return body+++def test_resolver_normalizes_and_resolves_defaults():+ result = resolve_openviking_assets(+ manifest_yaml=MANIFEST,+ catalog_yaml=CATALOG,+ manifest_label="manifests/code-qa.yaml",+ catalog_label="assets.yaml",+ )++ assert [asset.name for asset in result.assets] == ["alpha", "beta"]+ assert result.assets[0].watch_interval == 30+ assert result.assets[1].watch_interval == 0+ assert result.assets[1].locator == "github.com/org/beta"+ identity = b"git\ngithub.com/org/alpha\nmain"+ assert result.assets[0].asset_id == hashlib.sha1(identity).hexdigest()[:12]+++def test_resolver_accepts_single_file_manifest():+ result = resolve_openviking_assets(+ manifest_yaml=SINGLE_FILE_MANIFEST,+ manifest_label="single-file.yaml",+ )++ assert [asset.name for asset in result.assets] == ["alpha", "beta"]+ assert result.manifest == "single-file.yaml"+ assert result.catalog == "single-file.yaml"+ assert result.assets[0].watch_interval == 30+ assert result.assets[1].watch_interval == 0+++def test_single_file_manifest_selects_subset():+ result = resolve_openviking_assets(+ manifest_yaml=SINGLE_FILE_MANIFEST + "\nassets:\n - beta\n",+ )++ assert [asset.name for asset in result.assets] == ["beta"]+++ ("url", "expected"),+ [+ ("[email protected]:volcengine/OpenViking.git", "github.com/volcengine/OpenViking"),+ ("https://[email protected]/Org/Repo.git", "github.com/Org/Repo"),+ ("ssh://[email protected]:29418/t/repo", "host.com/t/repo"),+ ],+)+def test_normalize_repo_url_forms(url: str, expected: str):+ assert normalize_repo_url(url) == expected+++ ("manifest", "catalog", "message"),+ [+ ("include:\n - base.yaml\nassets:\n - alpha\n", CATALOG, "flat manifest"),+ ("asets:\n - alpha\n", CATALOG, "Extra inputs are not permitted"),+ ("assets:\n - missing\n", CATALOG, "not in catalog"),+ (+ "assets:\n - alpha\n",+ CATALOG.replace("connector: git", "connector: rss", 1),+ "not supported",+ ),+ (+ "assets:\n - alpha\n",+ CATALOG.replace("https://github.com/org/alpha", "ext::sh -c whoami"),+ "remote-helper",+ ),+ (+ "assets:\n - alpha\n - beta\n",+ CATALOG.replace("[email protected]:org/beta.git", "https://github.com/org/alpha").replace(+ " watch_interval: 0", " branch: main\n watch_interval: 0"+ ),+ "same source",+ ),+ ("catalog: ../assets.yaml\nassets:\n - alpha\n", CATALOG, "not a file path"),+ (SINGLE_FILE_MANIFEST, CATALOG, "do not pass a separate catalog"),+ (+ SINGLE_FILE_MANIFEST.replace("protocol: openviking-assets/1\n\n", ""),+ None,+ "'protocol' is required",+ ),+ (SINGLE_FILE_MANIFEST + "\nassets:\n - missing\n", None, "not defined in its"),+ ("defaults:\n git:\n watch_interval: 5\nassets:\n - alpha\n", CATALOG, "only allowed"),+ (MANIFEST, None, "no catalog was provided"),+ ],+)+def test_resolver_rejects_invalid_configuration(manifest: str, catalog: str | None, message: str):+ with pytest.raises(InvalidArgumentError, match=message):+ resolve_openviking_assets(manifest_yaml=manifest, catalog_yaml=catalog)+++class _GitProcess:+ def __init__(self, returncode: int, stderr: bytes = b""):+ self.returncode = returncode+ self.stderr = stderr+ self.killed = False++ async def communicate(self):+ return b"", self.stderr++ def kill(self):+ self.killed = True+++async def test_git_preflight_uses_process_local_auth_without_secret_in_argv(monkeypatch):+ captured = {}++ async def fake_exec(*args, **kwargs):+ captured["args"] = args+ captured["env"] = kwargs["env"]+ return _GitProcess(0)++ monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)+ result = await preflight_git_repository(+ asset_name="private",+ repo_url="https://github.com/org/private",+ branch="main",+ username="oauth2",+ token="secret-token",+ )++ assert result["accessible"] is True+ assert result["git_ref"] == "main"+ assert "secret-token" not in " ".join(captured["args"])+ assert any(+ "b2F1dGgyOnNlY3JldC10b2tlbg==" in value+ for key, value in captured["env"].items()+ if key.startswith("GIT_CONFIG_VALUE_")+ )+ assert captured["env"]["GIT_TERMINAL_PROMPT"] == "0"+++async def test_git_preflight_maps_private_repository_failure_to_permission_denied(monkeypatch):+ async def fake_exec(*_args, **_kwargs):+ return _GitProcess(128, b"remote: Repository not found.")++ monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)+ with pytest.raises(PermissionDeniedError, match="verify auth_ref"):+ await preflight_git_repository(+ asset_name="private",+ repo_url="https://github.com/beleev/paper",+ )+++async def test_git_preflight_maps_missing_branch_to_not_found(monkeypatch):+ async def fake_exec(*_args, **_kwargs):+ return _GitProcess(2)++ monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)+ with pytest.raises(NotFoundError, match="Git_ref not found"):+ await preflight_git_repository(+ asset_name="private",+ repo_url="https://github.com/beleev/paper",+ branch="missing",+ )+++async def test_git_preflight_rejects_server_local_paths():+ with pytest.raises(PermissionDeniedError, match="only accepts remote"):+ await preflight_git_repository(+ asset_name="local",+ repo_url="file:///tmp/private.git",+ )+++async def test_resolve_endpoint_returns_standard_envelope(client: httpx.AsyncClient):+ response = await client.post("/api/v1/openviking-assets/resolve", json=_request())++ assert response.status_code == 200+ body = response.json()+ assert body["status"] == "ok"+ assert [asset["name"] for asset in body["result"]["assets"]] == ["alpha", "beta"]+ assert body["result"]["manifest"] == "manifests/code-qa.yaml"+++async def test_resolve_endpoint_accepts_single_file_manifest(client: httpx.AsyncClient):+ response = await client.post(+ "/api/v1/openviking-assets/resolve",+ json={"manifest_yaml": SINGLE_FILE_MANIFEST, "manifest_label": "single-file.yaml"},+ )++ assert response.status_code == 200+ body = response.json()+ assert body["status"] == "ok"+ assert [asset["name"] for asset in body["result"]["assets"]] == ["alpha", "beta"]+ assert body["result"]["catalog"] == "single-file.yaml"+++async def test_resolve_endpoint_maps_configuration_errors(client: httpx.AsyncClient):+ response = await client.post(+ "/api/v1/openviking-assets/resolve",+ json=_request(manifest_yaml="include:\n - base.yaml\nassets:\n - alpha\n"),+ )++ assert response.status_code == 400+ body = response.json()+ assert body["status"] == "error"+ assert body["error"]["code"] == "INVALID_ARGUMENT"+ assert "flat manifest" in body["error"]["message"]+++async def test_preflight_endpoint_maps_source_permission_errors(+ client: httpx.AsyncClient, monkeypatch+):+ async def deny(**_kwargs):+ raise PermissionDeniedError("repository access denied")++ monkeypatch.setattr(+ "openviking.server.routers.openviking_assets.preflight_git_repository",+ deny,+ )+ response = await client.post(+ "/api/v1/openviking-assets/preflight",+ json={+ "name": "private",+ "connector": "git",+ "repo_url": "https://github.com/beleev/paper",+ },+ )++ assert response.status_code == 403+ body = response.json()+ assert body["status"] == "error"+ assert body["error"]["code"] == "PERMISSION_DENIED"