Skip to content

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

fix:openviking assets import external connector switch (#3634)

zihengli36d419aaa6e9
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index e5a5e4ff2..e49aa1bd9 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -80,6 +80,9 @@ pub async fn handle_add_resource(
let effective_include = merge_csv_options(ctx.config.upload.include.clone(), include);
let effective_exclude = merge_csv_options(ctx.config.upload.exclude.clone(), exclude);
let add_resource_args = parse_add_resource_args(resource_args.as_deref())?;
+ if let Some(args) = &add_resource_args {
+ reject_manifest_run_keys(args)?;
+ }
let effective_timeout = if wait {
timeout.unwrap_or(60.0).max(ctx.config.timeout)
@@ -127,7 +130,26 @@ pub async fn handle_add_resource(
.await
}
-fn parse_add_resource_args(raw: Option<&str>) -> Result<Option<Map<String, Value>>> {
+/// Single-resource `--args` go to the server as parser options; a manifest-run
+/// key here almost always means a forgotten `-m`. Fail instead of forwarding —
+/// the server treats unknown args keys of shared Connector sources by silently
+/// degrading to the standard pipeline, which would bury the mistake.
+fn reject_manifest_run_keys(args: &Map<String, Value>) -> Result<()> {
+ let run_keys: Vec<&str> = args
+ .keys()
+ .map(String::as_str)
+ .filter(|key| crate::openviking_assets::MANIFEST_RUN_ARG_KEYS.contains(key))
+ .collect();
+ if run_keys.is_empty() {
+ return Ok(());
+ }
+ Err(Error::Client(format!(
+ "--args {} are manifest-run options and need -m/--manifest.",
+ run_keys.join(", ")
+ )))
+}
+
+pub(crate) fn parse_add_resource_args(raw: Option<&str>) -> Result<Option<Map<String, Value>>> {
let Some(raw) = raw.map(str::trim).filter(|raw| !raw.is_empty()) else {
return Ok(None);
};
@@ -244,6 +266,48 @@ fn parse_add_resource_arg_value(raw: &str) -> Value {
Value::String(unquoted.to_string())
}
+#[cfg(test)]
+mod add_resource_args_tests {
+ use super::*;
+
+ #[test]
+ fn single_resource_mode_rejects_manifest_run_keys() {
+ let args = parse_add_resource_args(Some("dry_run:true,external_connector:true"))
+ .unwrap()
+ .unwrap();
+ let err = reject_manifest_run_keys(&args).unwrap_err();
+ let message = err.to_string();
+ assert!(message.contains("dry_run"), "{message}");
+ assert!(message.contains("--manifest"), "{message}");
+
+ let server_args = parse_add_resource_args(Some("feishu_access_token:u-xxx"))
+ .unwrap()
+ .unwrap();
+ assert!(reject_manifest_run_keys(&server_args).is_ok());
+ }
+
+ #[test]
+ fn manifest_run_args_share_single_resource_args_syntax() {
+ // Both --args forms of single-resource mode must drive manifest mode
+ // identically: the colon list and the JSON object go through the same
+ // parser, so neither mode grows its own syntax.
+ let colon = parse_add_resource_args(Some(
+ "catalog:shared/catalog.yaml,dry_run:true,skip_failed:false",
+ ))
+ .unwrap();
+ let json = parse_add_resource_args(Some(
+ r#"{"catalog": "shared/catalog.yaml", "dry_run": true, "skip_failed": false}"#,
+ ))
+ .unwrap();
+ assert_eq!(colon, json);
+
+ let run = crate::openviking_assets::parse_manifest_run_args(colon.as_ref()).unwrap();
+ assert_eq!(run.catalog.as_deref(), Some("shared/catalog.yaml"));
+ assert!(run.dry_run);
+ assert!(!run.skip_failed);
+ }
+}
+
pub async fn handle_add_skill(
data: String,
wait: bool,
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 1cdbeb746..bddf371d2 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -287,48 +287,25 @@ enum Commands {
conflicts_with = "manifest"
)]
path: Option<String>,
- /// Apply an OpenViking Assets manifest (openviking-assets/1): create or sync every selected asset
+ /// Apply an OpenViking Assets manifest (openviking-assets/1): create or sync every selected
+ /// asset. Run options go into --args (supported keys: catalog, dry_run, skip_failed)
#[arg(
short = 'm',
long = "manifest",
value_name = "file",
- help_heading = "Manifest mode",
+ help_heading = "Common options",
conflicts_with_all = [
- "add_type", "to", "parent", "parent_auto_create", "resource_args",
+ "add_type", "to", "parent", "parent_auto_create",
"strict_mode", "ignore_dirs", "include", "exclude",
- "no_directly_upload_media", "tags", "tag_mode"
+ "no_directly_upload_media", "tags", "tag_mode",
+ "reason", "instruction"
]
)]
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 Manifest mode, --parent, or
+ /// and cannot be combined with --manifest, --parent, or
/// --parent-auto-create
#[arg(
long = "add-type",
@@ -408,7 +385,10 @@ enum Commands {
help_heading = "Advanced options"
)]
processing_mode: String,
- /// Parser-specific import options, e.g. --args feishu_access_token:u-xxx
+ /// Extra options as key:value pairs or a JSON object. With a path/URL:
+ /// parser-specific import options sent to the server, e.g.
+ /// --args feishu_access_token:u-xxx. With --manifest: run options consumed
+ /// locally, e.g. --args dry_run:true (supported keys: catalog, dry_run, skip_failed)
#[arg(long = "args")]
resource_args: Option<String>,
/// Explicit k=v retrieval tag to apply after import. Can be repeated.
@@ -2857,9 +2837,6 @@ async fn main() {
path,
add_type,
manifest,
- catalog,
- dry_run,
- skip_failed,
to,
parent,
parent_auto_create,
@@ -2882,20 +2859,28 @@ async fn main() {
let ctx =
ctx.with_upload_options(upload_options.merged_with_legacy(legacy_upload_options));
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
+ match handlers::parse_add_resource_args(resource_args.as_deref())
+ .and_then(|args| openviking_assets::parse_manifest_run_args(args.as_ref()))
+ {
+ Err(e) => Err(e),
+ Ok(run) => {
+ openviking_assets::handle_manifest_apply(
+ manifest,
+ run.catalog,
+ openviking_assets::ManifestRunOptions {
+ dry_run: run.dry_run,
+ skip_failed: run.skip_failed,
+ wait,
+ watch_interval,
+ processing_mode,
+ external_connector: run.external_connector,
+ },
+ timeout,
+ ctx,
+ )
+ .await
+ }
+ }
} else if let Some(path) = path {
handlers::handle_add_resource(
path,
@@ -4912,31 +4897,54 @@ mod tests {
}
#[test]
- fn cli_manifest_mode_accepts_explicit_catalog() {
+ fn cli_manifest_mode_takes_run_options_via_args() {
let result = Cli::try_parse_from([
"ov",
"add-resource",
"--manifest",
"manifests/code-qa.yaml",
- "--catalog",
- "assets.yaml",
- "--dry-run",
+ "--args",
+ "catalog:catalog.yaml,dry_run:true,skip_failed:true",
]);
- assert!(result.is_ok(), "manifest and catalog flags should parse");
+ assert!(result.is_ok(), "manifest mode with --args 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",
- ]);
+ fn cli_manifest_mode_dropped_dedicated_run_flags() {
+ for flag in [
+ "--catalog=catalog.yaml",
+ "--dry-run",
+ "--skip-failed",
+ "--external-connector",
+ ] {
+ let result =
+ Cli::try_parse_from(["ov", "add-resource", "--manifest", "code-qa.yaml", flag]);
+ assert!(
+ result.is_err(),
+ "removed manifest flag {flag} should not parse"
+ );
+ }
+ }
- assert!(result.is_err(), "--catalog without --manifest must fail");
+ #[test]
+ fn cli_manifest_mode_rejects_silently_ignored_single_resource_options() {
+ for args in [
+ ["--reason", "why"],
+ ["--instruction", "how"],
+ ["--no-directly-upload-media", "--wait"],
+ ] {
+ let result = Cli::try_parse_from(
+ ["ov", "add-resource", "--manifest", "code-qa.yaml"]
+ .into_iter()
+ .chain(args),
+ );
+ assert!(
+ result.is_err(),
+ "{} must conflict with --manifest instead of being ignored",
+ args[0]
+ );
+ }
}
#[test]
diff --git a/crates/ov_cli/src/openviking_assets.rs b/crates/ov_cli/src/openviking_assets.rs
index 8bf79e08d..ed0b03c8e 100644
--- a/crates/ov_cli/src/openviking_assets.rs
+++ b/crates/ov_cli/src/openviking_assets.rs
@@ -1,9 +1,10 @@
//! 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`).
+//! (`openviking-assets/1`). Two keys carry the whole model: `catalog:` always
+//! holds asset definitions — inline in the manifest, or in a separate
+//! `catalog.yaml` shared by several manifests — and `assets:` always holds the
+//! names this build applies, defaulting to all of them.
//! 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
@@ -20,7 +21,7 @@ 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 DEFAULT_CATALOG_FILENAME: &str = "catalog.yaml";
const CREDENTIALS_ENV: &str = "OPENVIKING_ASSETS_CREDENTIALS_FILE";
fn client_err(msg: impl Into<String>) -> Error {
@@ -240,6 +241,33 @@ pub struct ManifestRunOptions {
/// Overrides per-asset / catalog-default values when set.
pub watch_interval: Option<f64>,
pub processing_mode: String,
+ /// Route assets through an external Connector service instead of the
+ /// standard ingestion pipeline.
+ pub external_connector: bool,
+}
+
+/// The `add_type` to submit for one asset.
+///
+/// Declaring it routes the source to an external Connector service, so it is
+/// sent only when the caller asked for that. The standard pipeline resolves
+/// the source from the URL itself and rejects `add_type` without an exact
+/// `to` target, which a first-time create does not have.
+fn effective_add_type(external_connector: bool, connector: &str) -> Option<String> {
+ external_connector.then(|| connector.to_string())
+}
+
+/// Where one asset lands.
+///
+/// A resource already recorded in State is synced in place. A first create
+/// normally lets the server name the resource, but a declared `add_type`
+/// requires an exact target, so external-Connector runs derive one from the
+/// asset name — unique within a manifest and already URI-safe.
+fn target_uri(
+ existing: Option<String>,
+ external_connector: bool,
+ asset_name: &str,
+) -> Option<String> {
+ existing.or_else(|| external_connector.then(|| format!("viking://resources/{asset_name}")))
}
impl Default for ManifestRunOptions {
@@ -250,10 +278,64 @@ impl Default for ManifestRunOptions {
wait: false,
watch_interval: None,
processing_mode: "semantic_and_vectors".to_string(),
+ external_connector: false,
}
}
}
+/// `--args` keys that are manifest-run options, consumed entirely by the CLI.
+/// They never reach the server: the submitted per-asset args come only from
+/// the catalog's params and credential resolution. Single-resource mode
+/// rejects these keys outright so a forgotten `-m` fails instead of sending
+/// them to the server as parser options.
+pub const MANIFEST_RUN_ARG_KEYS: &[&str] =
+ &["catalog", "dry_run", "skip_failed", EXTERNAL_CONNECTOR_KEY];
+
+/// Internal switch, deliberately absent from help and user docs.
+const EXTERNAL_CONNECTOR_KEY: &str = "external_connector";
+
+/// Manifest-run options carried by `--args` in manifest mode.
+#[derive(Debug, Default)]
+pub struct ManifestArgs {
+ pub catalog: Option<String>,
+ pub dry_run: bool,
+ pub skip_failed: bool,
+ pub external_connector: bool,
+}
+
+pub fn parse_manifest_run_args(args: Option<&Map<String, Value>>) -> Result<ManifestArgs> {
+ let mut run = ManifestArgs::default();
+ let Some(args) = args else {
+ return Ok(run);
+ };
+ for (key, value) in args {
+ match key.as_str() {
+ "catalog" => match value {
+ Value::String(path) if !path.trim().is_empty() => {
+ run.catalog = Some(path.clone());
+ }
+ _ => return Err(client_err("--args catalog expects a file path.")),
+ },
+ "dry_run" => run.dry_run = manifest_bool_arg(key, value)?,
+ "skip_failed" => run.skip_failed = manifest_bool_arg(key, value)?,
+ EXTERNAL_CONNECTOR_KEY => run.external_connector = manifest_bool_arg(key, value)?,
+ _ => {
+ return Err(client_err(format!(
+ "unknown manifest-run option '{key}' in --args; supported: \
+ catalog, dry_run, skip_failed"
+ )));
+ }
+ }
+ }
+ Ok(run)
+}
+
+fn manifest_bool_arg(key: &str, value: &Value) -> Result<bool> {
+ value
+ .as_bool()
+ .ok_or_else(|| client_err(format!("--args {key} expects true or false.")))
+}
+
#[derive(Debug, Default)]
pub struct ApplySummary {
pub total: usize,
@@ -461,7 +543,16 @@ pub async fn apply_manifest_core<S: Submitter>(
};
let args = build_args(asset, &credential_args[&asset.name]);
match submitter
- .submit(asset, entry.resource_uri.clone(), watch_interval, args)
+ .submit(
+ asset,
+ target_uri(
+ entry.resource_uri.clone(),
+ options.external_connector,
+ &asset.name,
+ ),
+ watch_interval,
+ args,
+ )
.await
{
Ok(response) => {
@@ -529,6 +620,7 @@ struct HttpSubmitter {
wait: bool,
timeout: Option<f64>,
processing_mode: String,
+ external_connector: bool,
}
impl Submitter for HttpSubmitter {
@@ -561,7 +653,7 @@ impl Submitter for HttpSubmitter {
self.client
.add_resource(
&asset.repo_url,
- Some("git".to_string()),
+ effective_add_type(self.external_connector, &asset.connector),
to,
None,
None,
@@ -714,7 +806,7 @@ fn manifest_defines_assets(manifest_yaml: &str) -> bool {
/// Entry point for `ov add-resource -m <manifest>`.
pub async fn handle_manifest_apply(
manifest: String,
- catalog: Option<String>,
+ catalog_file: Option<String>,
options: ManifestRunOptions,
timeout: Option<f64>,
ctx: CliContext,
@@ -726,7 +818,7 @@ pub async fn handle_manifest_apply(
manifest_path.display()
))
})?;
- let catalog_path = match catalog {
+ let catalog_path = match catalog_file {
Some(path) => Some(PathBuf::from(path)),
None if manifest_defines_assets(&manifest_yaml) => None,
None => Some(
@@ -741,7 +833,7 @@ pub async fn handle_manifest_apply(
.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>",
+ "cannot read asset definitions '{}': {e}; define assets under 'catalog' in the manifest or pass --catalog <file>",
path.display()
))
})
@@ -781,6 +873,7 @@ pub async fn handle_manifest_apply(
wait: options.wait,
timeout,
processing_mode: options.processing_mode.clone(),
+ external_connector: options.external_connector,
};
let summary = apply_manifest_core(
&manifest_path,
@@ -819,6 +912,67 @@ mod tests {
use super::*;
use std::sync::Mutex;
+ #[test]
+ fn add_type_is_declared_only_for_external_connector_runs() {
+ // The standard pipeline resolves the source from the URL and rejects
+ // add_type without an exact `to`, which a first create does not have.
+ assert_eq!(effective_add_type(false, "git"), None);
+ assert_eq!(effective_add_type(true, "git"), Some("git".to_string()));
+ assert_eq!(effective_add_type(true, "tos"), Some("tos".to_string()));
+ }
+
+ #[test]
+ fn manifest_run_args_parse_known_keys() {
+ let args = serde_json::json!({
+ "catalog": "shared/catalog.yaml",
+ "dry_run": true,
+ "skip_failed": true,
+ "external_connector": true,
+ });
+ let run = parse_manifest_run_args(args.as_object()).unwrap();
+ assert_eq!(run.catalog.as_deref(), Some("shared/catalog.yaml"));
+ assert!(run.dry_run && run.skip_failed && run.external_connector);
+
+ let run = parse_manifest_run_args(None).unwrap();
+ assert_eq!(run.catalog, None);
+ assert!(!run.dry_run && !run.skip_failed && !run.external_connector);
+ }
+
+ #[test]
+ fn manifest_run_args_reject_unknown_keys_and_bad_types() {
+ // Catalog params (e.g. git branch) belong in the catalog file, not
+ // here; an unknown key must not silently do nothing.
+ let unknown = serde_json::json!({"branch": "main"});
+ let err = parse_manifest_run_args(unknown.as_object()).unwrap_err();
+ assert!(err.to_string().contains("branch"), "{err}");
+ assert!(
+ err.to_string().contains("skip_failed"),
+ "should list keys: {err}"
+ );
+ // The internal switch stays out of the supported-keys hint.
+ assert!(!err.to_string().contains("external_connector"), "{err}");
+
+ let bad_bool = serde_json::json!({"dry_run": "yes"});
+ assert!(parse_manifest_run_args(bad_bool.as_object()).is_err());
+ let bad_catalog = serde_json::json!({"catalog": true});
+ assert!(parse_manifest_run_args(bad_catalog.as_object()).is_err());
+ }
+
+ #[test]
+ fn creates_get_an_exact_target_only_for_external_connector_runs() {
+ // Standard runs let the server name a new resource.
+ assert_eq!(target_uri(None, false, "alpha"), None);
+ // A declared add_type requires an exact target, derived from the name.
+ assert_eq!(
+ target_uri(None, true, "alpha"),
+ Some("viking://resources/alpha".to_string())
+ );
+ // An existing resource is synced in place under either mode.
+ let existing = Some("viking://resources/renamed".to_string());
+ assert_eq!(target_uri(existing.clone(), false, "alpha"), existing);
+ assert_eq!(target_uri(existing.clone(), true, "alpha"), existing);
+ }
+
#[test]
fn manifest_defines_assets_detects_catalog_lists_only() {
assert!(manifest_defines_assets(
@@ -826,7 +980,7 @@ mod tests {
));
assert!(!manifest_defines_assets("assets:\n - alpha\n"));
assert!(!manifest_defines_assets(
- "catalog: ../assets.yaml\nassets:\n - alpha\n"
+ "catalog: ../catalog.yaml\nassets:\n - alpha\n"
));
assert!(!manifest_defines_assets(": not yaml ["));
}
@@ -846,7 +1000,7 @@ mod tests {
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 catalog = dir.path().join("catalog.yaml");
let assets = vec![
ResolvedAsset {
name: "alpha".into(),
diff --git a/docs/en/api/22-openviking-assets.md b/docs/en/api/22-openviking-assets.md
index 59a4569aa..742a055e4 100644
--- a/docs/en/api/22-openviking-assets.md
+++ b/docs/en/api/22-openviking-assets.md
@@ -33,7 +33,7 @@ X-API-Key: <your-api-key>
| `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 |
+| `catalog_label` | string | No | `catalog.yaml` | Catalog source label used in errors, 1–1,024 characters |
Example with a self-contained Manifest:
diff --git a/docs/en/guides/18-openviking-assets.md b/docs/en/guides/18-openviking-assets.md
index 83868a4a5..57d934fd9 100644
--- a/docs/en/guides/18-openviking-assets.md
+++ b/docs/en/guides/18-openviking-assets.md
@@ -36,7 +36,7 @@ OpenViking Assets has three primary objects:
`viking://` resources.
```text
-manifest.yaml (+ assets.yaml when a shared Catalog is used)
+manifest.yaml (+ catalog.yaml when a shared Catalog is used)
|
v
Server resolves and validates openviking-assets/1
@@ -130,8 +130,8 @@ 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`:
+normally named `catalog.yaml`. A Catalog holds `protocol`, optional `defaults`, and the same
+`catalog` block — a Catalog file is simply a Manifest that selects nothing:
```yaml
protocol: openviking-assets/1
@@ -141,7 +141,7 @@ defaults:
auth_ref: team-git
watch_interval: 1440
-assets:
+catalog:
- name: openviking
connector: git
description: OpenViking main repository
@@ -167,11 +167,13 @@ assets:
```
The team maintains one Catalog; editing an asset there updates every Manifest that selects it.
+Because the two documents share a shape, a Catalog can also be applied directly with
+`ov add-resource -m catalog.yaml`, which ingests everything it defines.
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.
+1. The path passed to `--args catalog:<file>`, resolved from the current working directory.
+2. `catalog.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.
@@ -228,10 +230,10 @@ catalog:
Validate it first:
```bash
-ov add-resource --manifest manifest.yaml --dry-run
+ov add-resource --manifest manifest.yaml --args dry_run:true
```
-`--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;
@@ -246,7 +248,7 @@ produce an executable plan.
### Apply the Manifest
-Remove `--dry-run` after reviewing the plan:
+Remove `dry_run` after reviewing the plan:
```bash
ov add-resource --manifest manifest.yaml
@@ -258,8 +260,8 @@ Wait for each resource to finish processing:
ov add-resource --manifest manifest.yaml --wait --timeout 600
```
-The repository contains a complete example, including a shared Catalog with several Manifests,
-under
+The repository contains a complete example — a shared Catalog plus a Manifest that selects from
+it — under
[`examples/openviking-assets`](https://github.com/volcengine/OpenViking/tree/main/examples/openviking-assets).
## Credentials
@@ -308,7 +310,7 @@ After a non-dry-run application, the CLI writes this file next to the Manifest:
For example:
```text
-code-qa.yaml.state.json
+manifest.yaml.state.json
```
State uses the `openviking-assets-state/1` protocol and records:
@@ -364,7 +366,7 @@ Permission preflight runs before every resource submission. If any asset fails p
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.
+4. `skip_failed` does not bypass the preflight failure.
Per-asset execution starts only after all preflights succeed.
@@ -375,65 +377,41 @@ The default behavior is fail-fast:
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:
+Use `skip_failed` to continue with the remaining assets:
```bash
-ov add-resource --manifest manifest.yaml --skip-failed
+ov add-resource --manifest manifest.yaml --args skip_failed:true
```
-`--skip-failed` does not turn a partial failure into success. The command still exits non-zero when
+`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:
+Options used with `--manifest`:
| 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. |
+| `--args <key:value,...>` | Manifest-run options, comma-separated; supported keys below. |
| `--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
+Run options supported by `--args`:
-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.
+| Key | Description |
+| --- | --- |
+| `catalog:<file>` | Separate Catalog file for Manifests that select assets by name; defaults to `catalog.yaml` next to the Manifest. Not used when the Manifest defines `catalog` itself. |
+| `dry_run:true` | Resolve the protocol and validate read access to every repository without submitting resources, creating tasks, or writing State. |
+| `skip_failed:true` | Continue processing after an asset fails. |
-```bash
-ov --output json add-resource --manifest manifest.yaml --dry-run
-```
+`--args` accepts the comma-separated `key:value,...` form and a full JSON object, e.g.
+`--args '{"dry_run": true, "catalog": "shared/catalog.yaml"}'`.
-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.
+Run options are consumed locally by the CLI and are never sent to the server as resource
+arguments; an unknown key is an error.
## Current Limitations
diff --git a/docs/zh/api/22-openviking-assets.md b/docs/zh/api/22-openviking-assets.md
index 5c6b9d60f..69dd6c47d 100644
--- a/docs/zh/api/22-openviking-assets.md
+++ b/docs/zh/api/22-openviking-assets.md
@@ -30,7 +30,7 @@ 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 字符 |
+| `catalog_label` | string | 否 | `catalog.yaml` | Catalog 的来源标签,用于错误信息,长度为 1~1,024 字符 |
单文件 Manifest 示例:
diff --git a/docs/zh/guides/18-openviking-assets.md b/docs/zh/guides/18-openviking-assets.md
index 9ddc0c35a..f28cf7678 100644
--- a/docs/zh/guides/18-openviking-assets.md
+++ b/docs/zh/guides/18-openviking-assets.md
@@ -31,7 +31,7 @@ OpenViking Assets 包含三个主要对象:
- **State**:某个 Manifest 上次执行的结果,以及资产到 `viking://` 资源的映射。
```text
-manifest.yaml(使用共享 Catalog 时再加 assets.yaml)
+manifest.yaml(使用共享 Catalog 时再加 catalog.yaml)
|
v
服务端解析和校验 openviking-assets/1
@@ -122,7 +122,8 @@ Git 资产支持:
### 多个 Manifest 共享一个 Catalog
当多个 Manifest 复用同一批资源时,把资产定义移到单独的 Catalog 文件中,通常命名为
-`assets.yaml`。Catalog 包含 `protocol`、可选的 `defaults`,以及 `assets` 下的资产定义:
+`catalog.yaml`。Catalog 包含 `protocol`、可选的 `defaults`,以及同样的 `catalog` 块——
+一份 Catalog 文件就是一个不做选择的 Manifest:
```yaml
protocol: openviking-assets/1
@@ -132,7 +133,7 @@ defaults:
auth_ref: team-git
watch_interval: 1440
-assets:
+catalog:
- name: openviking
connector: git
description: OpenViking 主仓库
@@ -157,12 +158,13 @@ assets:
- requests
```
-全团队维护一份 Catalog;在 Catalog 中修改资产,所有选择它的 Manifest 都会生效。
+全团队维护一份 Catalog;在 Catalog 中修改资产,所有选择它的 Manifest 都会生效。因为两种
+文档同构,Catalog 也可以直接执行:`ov add-resource -m catalog.yaml` 会导入它定义的全部资产。
CLI 按以下规则查找 Catalog 文件:
-1. 传入 `--catalog <file>` 时使用该路径;相对路径基于当前工作目录。
-2. 未传入时读取 Manifest 所在目录下的 `assets.yaml`。
+1. 传入 `--args catalog:<file>` 时使用该路径;相对路径基于当前工作目录。
+2. 未传入时读取 Manifest 所在目录下的 `catalog.yaml`。
定义了 `catalog` 的 Manifest 不使用单独的 Catalog 文件;同时传入会导致解析失败。
@@ -216,10 +218,10 @@ catalog:
先验证:
```bash
-ov add-resource --manifest manifest.yaml --dry-run
+ov add-resource --manifest manifest.yaml --args dry_run:true
```
-`--dry-run` 会完成以下操作:
+`dry_run` 会完成以下操作:
- 读取本地 YAML 文件(使用单独 Catalog 文件时一并读取);
- 调用当前 OpenViking 服务解析并校验协议;
@@ -232,7 +234,7 @@ ov add-resource --manifest manifest.yaml --dry-run
### 应用 Manifest
-确认计划后去掉 `--dry-run`:
+确认计划后去掉 `dry_run`:
```bash
ov add-resource --manifest manifest.yaml
@@ -244,7 +246,7 @@ ov add-resource --manifest manifest.yaml
ov add-resource --manifest manifest.yaml --wait --timeout 600
```
-仓库中包含一个完整示例(含共享 Catalog 和多个 Manifest),位于
+仓库中包含一个完整示例(一份共享 Catalog 加一份按名选择的 Manifest),位于
[`examples/openviking-assets`](https://github.com/volcengine/OpenViking/tree/main/examples/openviking-assets)。
## 凭据
@@ -273,7 +275,7 @@ export OPENVIKING_ASSETS_CREDENTIALS_FILE=/secure/path/assets-credentials.yaml
执行前,CLI 会先解析所有选中资产的 `auth_ref`,然后由服务端在实际执行环境中用
`git ls-remote` 校验每个仓库的读取权限。只要有一个别名不存在或仓库不可读,整个操作都会
-在提交任何资源之前失败;`--dry-run` 也执行相同预检。解析出的 Git 参数会通过当前配置的
+在提交任何资源之前失败;`dry_run` 也执行相同预检。解析出的 Git 参数会通过当前配置的
OpenViking 服务连接发送给 preflight 和资源接口,因此远程部署应使用 TLS,并限制凭据文件
的本地访问权限。
@@ -290,7 +292,7 @@ OpenViking 服务连接发送给 preflight 和资源接口,因此远程部署
例如:
```text
-code-qa.yaml.state.json
+manifest.yaml.state.json
```
State 使用 `openviking-assets-state/1` 协议,记录:
@@ -344,7 +346,7 @@ Catalog 或 Manifest 的构成变化、恢复失败资产,或显式触发同
1. 命令立即以原始错误码退出,例如 `PERMISSION_DENIED`;
2. 不提交任何资产,不创建后台任务;
3. 不写入 State;
-4. `--skip-failed` 不会跳过预检失败。
+4. `skip_failed` 不会跳过预检失败。
只有全部预检成功后,才进入以下逐资产执行阶段。
@@ -355,62 +357,39 @@ Catalog 或 Manifest 的构成变化、恢复失败资产,或显式触发同
3. 已成功资产和失败记录写入 State;
4. 命令以非零状态退出。
-使用 `--skip-failed` 可以继续处理其余资产:
+使用 `skip_failed` 可以继续处理其余资产:
```bash
-ov add-resource --manifest manifest.yaml --skip-failed
+ov add-resource --manifest manifest.yaml --args skip_failed:true
```
-`--skip-failed` 不会把部分失败转换为成功。只要有资产失败,命令最终仍以非零状态退出;
+`skip_failed` 不会把部分失败转换为成功。只要有资产失败,命令最终仍以非零状态退出;
已经成功的资源不会回滚。全部资产失败时,命令会报告没有任何资产成功应用。
## 命令行选项
-Manifest 模式的主要参数:
+与 `--manifest` 搭配使用的参数:
| 参数 | 说明 |
| --- | --- |
| `-m, --manifest <file>` | Manifest 文件。 |
-| `--catalog <file>` | 按名称选择资产的 Manifest 使用的单独 Catalog 文件;省略时使用 Manifest 同目录的 `assets.yaml`。Manifest 自身定义了 `catalog` 时不使用。 |
-| `--dry-run` | 解析协议并校验所有仓库的读取权限;不提交资源、不创建任务、不写 State。 |
-| `--skip-failed` | 一个资产失败后继续处理其他资产。 |
+| `--args <key:value,...>` | Manifest 运行选项,多个选项用逗号分隔,支持的键见下表。 |
| `--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 模式下不要依赖这些参数。
-## 结构化输出
+`--args` 支持的运行选项:
-默认输出适合终端阅读。使用 JSON 输出时,Manifest 模式会输出 NDJSON,即每行一个完整的
-JSON 事件,而不是一个单独的 JSON 文档:
+| 键 | 说明 |
+| --- | --- |
+| `catalog:<file>` | 按名称选择资产的 Manifest 使用的单独 Catalog 文件;省略时使用 Manifest 同目录的 `catalog.yaml`。Manifest 自身定义了 `catalog` 时不使用。 |
+| `dry_run:true` | 解析协议并校验所有仓库的读取权限;不提交资源、不创建任务、不写 State。 |
+| `skip_failed:true` | 一个资产失败后继续处理其他资产。 |
-```bash
-ov --output json add-resource --manifest manifest.yaml --dry-run
-```
+`--args` 既支持 `key:value,...` 逗号分隔形式,也支持整段 JSON 对象,例如
+`--args '{"dry_run": true, "catalog": "shared/catalog.yaml"}'`。
-可能出现的事件包括:
-
-- `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` 输出。
+运行选项由 CLI 在本地消费,不会作为资源参数发送给服务端;未知的键会直接报错。
## 当前限制
diff --git a/examples/openviking-assets/assets.yaml b/examples/openviking-assets/catalog.yaml
similarity index 99%
rename from examples/openviking-assets/assets.yaml
rename to examples/openviking-assets/catalog.yaml
index f8e166d18..06edc8604 100644
--- a/examples/openviking-assets/assets.yaml
+++ b/examples/openviking-assets/catalog.yaml
@@ -7,7 +7,7 @@ defaults:
git:
watch_interval: 1440 # minutes; refresh every repo daily unless overridden
-assets:
+catalog:
- name: openviking
connector: git
description: OpenViking main repository — server, CLI and SDKs
diff --git a/examples/openviking-assets/manifest.yaml b/examples/openviking-assets/manifest.yaml
index 5c3ffcb08..5de5be7b2 100644
--- a/examples/openviking-assets/manifest.yaml
+++ b/examples/openviking-assets/manifest.yaml
@@ -1,21 +1,10 @@
-# 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
+# OpenViking Assets manifest: selects assets by name from the catalog.yaml
+# next to it (found automatically; override with --args catalog:<file>).
+# Validate first, then apply:
+# ov add-resource -m manifest.yaml --args dry_run:true
+# ov add-resource -m manifest.yaml
+# Simple setups can skip the separate catalog file and define assets inline
+# under `catalog:` — see the OpenViking Assets guide.
+assets:
+ - openviking
+ - flask
diff --git a/examples/openviking-assets/manifests/code-qa.yaml b/examples/openviking-assets/manifests/code-qa.yaml
deleted file mode 100644
index 2c0d031c3..000000000
--- a/examples/openviking-assets/manifests/code-qa.yaml
+++ /dev/null
@@ -1,7 +0,0 @@
-# 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/openviking_assets.py b/openviking/server/openviking_assets.py
index da4d077a8..4ccb0758f 100644
--- a/openviking/server/openviking_assets.py
+++ b/openviking/server/openviking_assets.py
@@ -64,10 +64,17 @@ class _CatalogAsset(_StrictModel):
class _Catalog(_StrictModel):
protocol: str
defaults: _Defaults | None = None
- assets: list[_CatalogAsset]
+ catalog: list[_CatalogAsset]
class _Manifest(_StrictModel):
+ """One build: asset definitions under ``catalog``, chosen names under ``assets``.
+
+ ``catalog`` holds the definitions themselves, inline here or supplied as a
+ separate catalog file. ``assets`` names which of them this build applies;
+ omitting it applies every defined asset.
+ """
+
protocol: str | None = None
defaults: _Defaults | None = None
catalog: list[_CatalogAsset] | str | None = None
@@ -312,7 +319,7 @@ def resolve_openviking_assets(
manifest_yaml: str,
catalog_yaml: str | None = None,
manifest_label: str = "manifest.yaml",
- catalog_label: str = "assets.yaml",
+ catalog_label: str = "catalog.yaml",
) -> ResolveResult:
"""Parse and resolve one flat manifest, optionally against a separate catalog.
@@ -352,7 +359,9 @@ def resolve_openviking_assets(
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 = _Catalog(
+ protocol=PROTOCOL, defaults=manifest.defaults, catalog=manifest.catalog
+ )
catalog_label = manifest_label
else:
if manifest.defaults is not None:
@@ -387,7 +396,7 @@ def resolve_openviking_assets(
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]
+ names = [asset.name for asset in catalog.catalog]
if not names:
raise InvalidArgumentError(f"manifest '{manifest_label}' selects no assets")
@@ -403,7 +412,7 @@ def resolve_openviking_assets(
default_watch = 0.0
catalog_by_name: dict[str, _CatalogAsset] = {}
- for asset in catalog.assets:
+ for asset in catalog.catalog:
where = f"catalog '{catalog_label}' asset '{asset.name}'"
if not _ASSET_NAME_RE.fullmatch(asset.name):
raise InvalidArgumentError(
diff --git a/openviking/server/routers/openviking_assets.py b/openviking/server/routers/openviking_assets.py
index fe8d590ff..7635ce9b9 100644
--- a/openviking/server/routers/openviking_assets.py
+++ b/openviking/server/routers/openviking_assets.py
@@ -26,7 +26,7 @@ class ResolveOpenVikingAssetsRequest(BaseModel):
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)
+ catalog_label: str = Field(default="catalog.yaml", min_length=1, max_length=1024)
class GitAuthConfig(BaseModel):
diff --git a/tests/integration/test_quick_start_lite.py b/tests/integration/test_quick_start_lite.py
index 513dd2000..468ff461a 100644
--- a/tests/integration/test_quick_start_lite.py
+++ b/tests/integration/test_quick_start_lite.py
@@ -13,7 +13,10 @@ PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../")
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
-from openviking.models.embedder.base import EmbedResult # noqa: E402
+from openviking.models.embedder.base import ( # noqa: E402
+ EmbedResult,
+ extract_text_from_content,
+)
from openviking_cli.utils.config import OPENVIKING_CONFIG_ENV # noqa: E402
@@ -28,6 +31,9 @@ class _FakeEmbedder:
def get_dimension(self):
return self._dimension
+ def prepare_embedding_input(self, content):
+ return extract_text_from_content(content)
+
def _generate_pseudo_embedding(self, text: str):
"""
Generate a deterministic pseudo-embedding based on text content.
@@ -65,6 +71,10 @@ class _FakeEmbedder:
def embed(self, text: str, is_query: bool = False) -> EmbedResult:
return EmbedResult(dense_vector=self._generate_pseudo_embedding(text))
+ async def embed_async(self, text: str, is_query: bool = False) -> EmbedResult:
+ return self.embed(text, is_query=is_query)
+
+
class TestQuickStartLite(unittest.TestCase):
def setUp(self):
# Clean up data directory if exists to ensure fresh start
diff --git a/tests/server/test_openviking_assets.py b/tests/server/test_openviking_assets.py
index 286e66b1f..cddade18a 100644
--- a/tests/server/test_openviking_assets.py
+++ b/tests/server/test_openviking_assets.py
@@ -25,7 +25,7 @@ defaults:
git:
watch_interval: 30
-assets:
+catalog:
- name: alpha
connector: git
description: alpha repo
@@ -74,7 +74,7 @@ def _request(**overrides):
"manifest_yaml": MANIFEST,
"catalog_yaml": CATALOG,
"manifest_label": "manifests/code-qa.yaml",
- "catalog_label": "assets.yaml",
+ "catalog_label": "catalog.yaml",
}
body.update(overrides)
return body
@@ -85,7 +85,7 @@ def test_resolver_normalizes_and_resolves_defaults():
manifest_yaml=MANIFEST,
catalog_yaml=CATALOG,
manifest_label="manifests/code-qa.yaml",
- catalog_label="assets.yaml",
+ catalog_label="catalog.yaml",
)
assert [asset.name for asset in result.assets] == ["alpha", "beta"]
@@ -152,7 +152,7 @@ def test_normalize_repo_url_forms(url: str, expected: str):
),
"same source",
),
- ("catalog: ../assets.yaml\nassets:\n - alpha\n", CATALOG, "not a file path"),
+ ("catalog: ../catalog.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", ""),