Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix:openviking assets import external connector switch (#3634)
zihengli36d419aaa6e9
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rsindex 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.rsindex 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.rsindex 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.## 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 p1. 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 whenany asset fails, and successfully created resources are not rolled back. If every asset fails, thecommand 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 Limitationsdiff --git a/docs/zh/api/22-openviking-assets.md b/docs/zh/api/22-openviking-assets.mdindex 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.mdindex 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:```yamlprotocol: openviking-assets/1@@ -132,7 +133,7 @@ defaults:auth_ref: team-gitwatch_interval: 1440-assets:+catalog:- name: openvikingconnector: gitdescription: 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`:```bashov add-resource --manifest manifest.yaml@@ -244,7 +246,7 @@ ov add-resource --manifest manifest.yamlov 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.yamlsimilarity index 99%rename from examples/openviking-assets/assets.yamlrename to examples/openviking-assets/catalog.yamlindex 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: openvikingconnector: gitdescription: OpenViking main repository — server, CLI and SDKsdiff --git a/examples/openviking-assets/manifest.yaml b/examples/openviking-assets/manifest.yamlindex 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+ - flaskdiff --git a/examples/openviking-assets/manifests/code-qa.yaml b/examples/openviking-assets/manifests/code-qa.yamldeleted file mode 100644index 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- - flaskdiff --git a/openviking/server/openviking_assets.py b/openviking/server/openviking_assets.pyindex 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: strdefaults: _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 = Nonedefaults: _Defaults | None = Nonecatalog: 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_labelelse: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.0catalog_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.pyindex 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.pyindex 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 startdiff --git a/tests/server/test_openviking_assets.py b/tests/server/test_openviking_assets.pyindex 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: alphaconnector: gitdescription: 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", ""),