Skip to content

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

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.rs
index 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 OpenViking
AddResource {
/// 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.rs
new file mode 100644
index 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(&current_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.rs
index 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.ts
index 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.md
index 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.md
index 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 guide
diff --git a/docs/en/api/22-openviking-assets.md b/docs/en/api/22-openviking-assets.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.md
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.yaml
new file mode 100644
index 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: main
diff --git a/examples/openviking-assets/manifest.yaml b/examples/openviking-assets/manifest.yaml
new file mode 100644
index 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.git
diff --git a/examples/openviking-assets/manifests/code-qa.yaml b/examples/openviking-assets/manifests/code-qa.yaml
new file mode 100644
index 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
+ - flask
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 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_url
return 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.py
new file mode 100644
index 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__.py
index 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_router
from openviking.server.routers.filesystem import router as filesystem_router
from openviking.server.routers.metrics import router as metrics_router
from openviking.server.routers.observer import router as observer_router
+from openviking.server.routers.openviking_assets import router as openviking_assets_router
from openviking.server.routers.pack import router as pack_router
from openviking.server.routers.privacy_configs import router as privacy_configs_router
from 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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"