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(ov): harden CLI configuration and command behavior (#3552)
Hao Zhec4d2b27c6415
diff --git a/crates/ov_cli/README.md b/crates/ov_cli/README.mdindex f001c3732..043174c9a 100644--- a/crates/ov_cli/README.md+++ b/crates/ov_cli/README.md@@ -175,7 +175,7 @@ Run `ov --help` and `ov <command> --help` for the exact command surface of your- `observer vikingdb` - VikingDB status.- `observer models` - VLM, embedding, and rerank model status.- `observer retrieval` - Retrieval quality metrics.-- `observer fs` - Filesystem operation metrics.+- `observer filesystem` - Filesystem operation metrics.- `observer system` - Overall system status.### Configuration@@ -269,8 +269,8 @@ ov glob "**/*.md" --uri viking://resources# Session workflowSESSION=$(ov -o json session new | jq -r '.result.session_id')-ov session add-message --session-id "$SESSION" --role user --content "Hello"-ov session commit --session-id "$SESSION"+ov session add-message "$SESSION" --role user --content "Hello"+ov session commit "$SESSION"# Watch task managementov add-resource https://example.com/docs --to viking://resources/docs --watch-interval 60diff --git a/crates/ov_cli/README_CN.md b/crates/ov_cli/README_CN.mdindex 1caf66101..a264caead 100644--- a/crates/ov_cli/README_CN.md+++ b/crates/ov_cli/README_CN.md@@ -175,7 +175,7 @@ ov grep "openviking" --uri viking://resources- `observer vikingdb` - VikingDB 状态。- `observer models` - VLM、embedding 和 rerank 模型状态。- `observer retrieval` - 检索质量指标。-- `observer fs` - 文件系统操作指标。+- `observer filesystem` - 文件系统操作指标。- `observer system` - 整体系统状态。### 配置@@ -269,8 +269,8 @@ ov glob "**/*.md" --uri viking://resources# Session 工作流SESSION=$(ov -o json session new | jq -r '.result.session_id')-ov session add-message --session-id "$SESSION" --role user --content "Hello"-ov session commit --session-id "$SESSION"+ov session add-message "$SESSION" --role user --content "Hello"+ov session commit "$SESSION"# Watch 任务管理ov add-resource https://example.com/docs --to viking://resources/docs --watch-interval 60diff --git a/crates/ov_cli/src/commands/compile.rs b/crates/ov_cli/src/commands/compile.rsindex cf36d28f6..753a3bcf5 100644--- a/crates/ov_cli/src/commands/compile.rs+++ b/crates/ov_cli/src/commands/compile.rs@@ -18,8 +18,10 @@ pub async fn run(compact: bool,) -> Result<()> {let sources = normalize_sources(from_uris)?;- if timeout.is_some_and(|seconds| !seconds.is_finite() || seconds <= 0.0) {- return Err(Error::Client("--timeout must be a positive number".into()));+ if timeout.is_some_and(|seconds| !crate::config::timeout_is_valid(seconds)) {+ return Err(Error::Client(+ "--timeout must be a positive finite number of seconds".into(),+ ));}let reason = reason.as_deref()diff --git a/crates/ov_cli/src/commands/content.rs b/crates/ov_cli/src/commands/content.rsindex 3035bfd4e..b9b43e2a4 100644--- a/crates/ov_cli/src/commands/content.rs+++ b/crates/ov_cli/src/commands/content.rs@@ -3,7 +3,6 @@ use crate::error::Result;use crate::output::OutputFormat;use serde_json::{Value, json};use std::collections::BTreeSet;-use std::fs::File;use std::io::Write;use std::path::Path;@@ -100,7 +99,7 @@ pub async fn get(client: &HttpClient, uri: &str, local_path: &str) -> Result<()>let bytes = client.get_bytes(uri).await?;// Write to local file- let mut file = File::create(path)?;+ let mut file = create_download_target(path, local_path)?;file.write_all(&bytes)?;file.flush()?;@@ -108,6 +107,20 @@ pub async fn get(client: &HttpClient, uri: &str, local_path: &str) -> Result<()>Ok(())}+fn create_download_target(path: &Path, local_path: &str) -> Result<std::fs::File> {+ std::fs::OpenOptions::new()+ .write(true)+ .create_new(true)+ .open(path)+ .map_err(|error| {+ if error.kind() == std::io::ErrorKind::AlreadyExists {+ crate::error::Error::Client(format!("File already exists: {local_path}"))+ } else {+ crate::error::Error::Io(error)+ }+ })+}+fn output_content_result(result: Value, output_format: OutputFormat, compact: bool) -> Result<()> {match output_format {OutputFormat::Json => crate::output::output_success(result, output_format, compact),@@ -193,6 +206,7 @@ fn render_set_tags_result_for_table(result: &Value) -> Option<String> {#[cfg(test)]mod tests {+ use crate::error::Error;use serde_json::json;fn strip_ansi(input: &str) -> String {@@ -272,4 +286,20 @@ mod tests {));}++ #[test]+ fn download_target_creation_does_not_truncate_an_existing_file() {+ let dir = tempfile::tempdir().expect("tempdir should be created");+ let path = dir.path().join("result.bin");+ std::fs::write(&path, b"existing").expect("fixture should be written");++ let error = super::create_download_target(&path, &path.to_string_lossy())+ .expect_err("existing targets must be rejected atomically");++ assert!(matches!(error, Error::Client(_)));+ assert_eq!(+ std::fs::read(&path).expect("existing file should remain readable"),+ b"existing"+ );+ }}diff --git a/crates/ov_cli/src/commands/snapshot.rs b/crates/ov_cli/src/commands/snapshot.rsindex 4f8f32d16..9944f17fa 100644--- a/crates/ov_cli/src/commands/snapshot.rs+++ b/crates/ov_cli/src/commands/snapshot.rs@@ -213,11 +213,11 @@ fn handle_show(SnapshotShowResult::Blob { oid, bytes, size } => {if matches!(output_format, OutputFormat::Json) {let envelope = serde_json::json!({"oid": oid, "size": size});- output_success(&envelope, output_format, compact);if let Some(path) = out_path {let mut f = std::fs::File::create(&path)?;f.write_all(&bytes)?;}+ output_success(&envelope, output_format, compact);return Ok(());}match out_path {@@ -272,3 +272,51 @@ fn print_log(value: &Value, output_format: OutputFormat, compact: bool) {.collect();output_success(&rows, OutputFormat::Table, compact);}++#[cfg(test)]+mod tests {+ use super::handle_show;+ use crate::client::SnapshotShowResult;+ use crate::output::OutputFormat;++ #[test]+ fn json_blob_show_writes_requested_output_file() {+ let dir = tempfile::tempdir().expect("tempdir should be created");+ let path = dir.path().join("blob.bin");++ handle_show(+ SnapshotShowResult::Blob {+ oid: "abc123".to_string(),+ bytes: b"snapshot-bytes".to_vec(),+ size: 14,+ },+ Some(path.clone()),+ OutputFormat::Json,+ true,+ )+ .expect("blob output should be written");++ assert_eq!(+ std::fs::read(path).expect("blob output should be readable"),+ b"snapshot-bytes"+ );+ }++ #[test]+ fn json_blob_show_propagates_output_file_errors() {+ let dir = tempfile::tempdir().expect("tempdir should be created");++ let result = handle_show(+ SnapshotShowResult::Blob {+ oid: "abc123".to_string(),+ bytes: b"snapshot-bytes".to_vec(),+ size: 14,+ },+ Some(dir.path().to_path_buf()),+ OutputFormat::Json,+ true,+ );++ assert!(result.is_err());+ }+}diff --git a/crates/ov_cli/src/config.rs b/crates/ov_cli/src/config.rsindex 6b6b04425..7c3545613 100644--- a/crates/ov_cli/src/config.rs+++ b/crates/ov_cli/src/config.rs@@ -105,6 +105,23 @@ fn default_timeout() -> f64 {60.0}+pub(crate) fn timeout_is_valid(timeout: f64) -> bool {+ timeout > 0.0 && std::time::Duration::try_from_secs_f64(timeout).is_ok()+}++pub(crate) fn parse_positive_timeout(value: &str) -> std::result::Result<f64, String> {+ let timeout = value+ .parse::<f64>()+ .map_err(|_| format!("invalid timeout {value:?}: expected a positive number of seconds"))?;+ if timeout_is_valid(timeout) {+ Ok(timeout)+ } else {+ Err(format!(+ "invalid timeout {value:?}: expected a positive finite number of seconds"+ ))+ }+}+fn default_output_format() -> String {"table".to_string()}@@ -308,6 +325,22 @@ impl Config {Ok(())}+ pub(crate) fn validate_runtime_values(&self) -> Result<()> {+ if !timeout_is_valid(self.timeout) {+ return Err(Error::Config(format!(+ "Invalid timeout value {}: timeout must be a positive finite number of seconds",+ self.timeout+ )));+ }+ if !matches!(self.output.as_str(), "table" | "json") {+ return Err(Error::Config(format!(+ "Invalid output value {:?}: expected table or json",+ self.output+ )));+ }+ Ok(())+ }+pub(crate) fn effective_auth_with_overrides(&self,api_key_override: Option<String>,@@ -458,6 +491,49 @@ mod tests {assert!(error.to_string().contains("actor_peer_id cannot be used"));}+ #[test]+ fn runtime_validation_rejects_invalid_timeout_values() {+ for timeout in [-1.0, 0.0, f64::INFINITY, f64::NAN, 1e300] {+ let config = Config {+ timeout,+ ..Config::default()+ };+ let error = config+ .validate_runtime_values()+ .expect_err("invalid timeout should fail runtime validation");+ assert!(error.to_string().contains("Invalid timeout value"));+ }+ }++ #[test]+ fn config_file_with_invalid_timeout_still_loads_for_repair() {+ let dir = tempfile::tempdir().expect("tempdir should be created");+ let path = dir.path().join("ovcli.conf");+ std::fs::write(&path, r#"{"timeout": -1}"#).expect("config file should be written");++ let config =+ Config::from_file(&path.to_string_lossy()).expect("repair commands must load the file");++ assert_eq!(config.timeout, -1.0);+ assert!(config.validate_runtime_values().is_err());+ }++ #[test]+ fn config_file_with_invalid_output_still_loads_for_repair() {+ let dir = tempfile::tempdir().expect("tempdir should be created");+ let path = dir.path().join("ovcli.conf");+ std::fs::write(&path, r#"{"output": "yaml"}"#).expect("config file should be written");++ let config =+ Config::from_file(&path.to_string_lossy()).expect("repair commands must load the file");++ assert_eq!(config.output, "yaml");+ let error = config+ .validate_runtime_values()+ .expect_err("normal commands must reject an invalid output format");+ assert!(error.to_string().contains("Invalid output value \"yaml\""));+ }+#[test]fn config_deserializes_root_api_key() {let config: Config = serde_json::from_str(diff --git a/crates/ov_cli/src/config_wizard/store.rs b/crates/ov_cli/src/config_wizard/store.rsindex 393cb9fda..5ca559a08 100644--- a/crates/ov_cli/src/config_wizard/store.rs+++ b/crates/ov_cli/src/config_wizard/store.rs@@ -574,6 +574,8 @@ pub(crate) async fn validate_candidate_config_with_role(config: &Config,require_api_key: bool,) -> Result<Option<ApiKeyRole>> {+ config.validate_runtime_values()?;+let api_key = non_empty_option(config.api_key.as_deref());if require_api_key && api_key.is_none() {return Err(Error::Config("API key is required".to_string()));diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rsindex e49aa1bd9..93b2a6ca7 100644--- a/crates/ov_cli/src/handlers.rs+++ b/crates/ov_cli/src/handlers.rs@@ -37,6 +37,7 @@ pub async fn handle_add_resource() -> Result<()> {let is_url =path.starts_with("http://") || path.starts_with("https://") || path.starts_with("git@");+ validate_watch_source(is_url, watch_interval)?;// A declared Connector add_type sends the path verbatim to the server;// it is never a local file, so skip local-path existence validation.@@ -130,6 +131,16 @@ pub async fn handle_add_resource(.await}+fn validate_watch_source(is_remote: bool, watch_interval: f64) -> Result<()> {+ if !is_remote && watch_interval > 0.0 {+ return Err(Error::Client(+ "A local path cannot be watched. Use a URL, sitemap, or RSS source, or re-import the local content when it changes."+ .to_string(),+ ));+ }+ Ok(())+}+/// 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@@ -1816,3 +1827,17 @@ mod config_switch_prompt_tests {output}}++#[cfg(test)]+mod add_resource_validation_tests {+ #[test]+ fn local_watch_is_rejected_before_upload() {+ let error =+ super::validate_watch_source(false, 1.0).expect_err("local watch should be rejected");++ assert!(error.to_string().contains("local path cannot be watched"));+ assert!(super::validate_watch_source(false, 0.0).is_ok());+ assert!(super::validate_watch_source(false, -1.0).is_ok());+ assert!(super::validate_watch_source(true, 1.0).is_ok());+ }+}diff --git a/crates/ov_cli/src/help_ui.rs b/crates/ov_cli/src/help_ui.rsindex b35115dd5..e56b2e31c 100644--- a/crates/ov_cli/src/help_ui.rs+++ b/crates/ov_cli/src/help_ui.rs@@ -547,7 +547,7 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Compare one file between two snapshots.",},HelpItem {- label: "ov snapshot restore viking://projects/acme <commit> --dry-run",+ label: "ov snapshot restore <commit> viking://projects/acme --dry-run",description: "Preview restoring a directory to a past snapshot.",},],@@ -585,11 +585,11 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[purpose: "Restore a project directory to a past snapshot via a forward commit.",examples: &[HelpItem {- label: "ov snapshot restore viking://projects/acme <commit> --dry-run",+ label: "ov snapshot restore <commit> viking://projects/acme --dry-run",description: "Preview which files would change.",},HelpItem {- label: "ov snapshot restore viking://projects/acme <commit> -m \"rollback\"",+ label: "ov snapshot restore <commit> viking://projects/acme -m \"rollback\"",description: "Apply the restore as a new commit.",},],diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex bddf371d2..76607af15 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -119,12 +119,11 @@ struct Cli {short,long,value_enum,- default_value = "table",global = true,hide = true,value_name = "table|json")]- output: OutputFormat,+ output: Option<OutputFormat>,/// Use compact table/JSON rendering#[arg(@@ -349,7 +348,12 @@ enum Commands {#[arg(long, help_heading = "Common options")]wait: bool,/// Wait timeout in seconds (only used with --wait)- #[arg(long, value_name = "seconds", help_heading = "Common options")]+ #[arg(+ long,+ value_parser = config::parse_positive_timeout,+ value_name = "seconds",+ help_heading = "Common options"+ )]timeout: Option<f64>,/// Enable strict mode for directory scanning (fail if any unsupported files found)#[arg(@@ -414,7 +418,12 @@ enum Commands {#[arg(long, help_heading = "Common options")]wait: bool,/// Wait timeout in seconds- #[arg(long, value_name = "seconds", help_heading = "Common options")]+ #[arg(+ long,+ value_parser = config::parse_positive_timeout,+ value_name = "seconds",+ help_heading = "Common options"+ )]timeout: Option<f64>,/// Parent skill root URI (e.g. viking://agent/skills); defaults to user-private skills#[arg(@@ -462,6 +471,7 @@ enum Commands {short = 'n',alias = "limit",default_value = "256",+ value_parser = clap::value_parser!(i32).range(0..),value_name = "n",help_heading = "Common options")]@@ -490,6 +500,7 @@ enum Commands {short = 'n',alias = "limit",default_value = "256",+ value_parser = clap::value_parser!(i32).range(0..),value_name = "n",help_heading = "Common options")]@@ -526,7 +537,12 @@ enum Commands {#[arg(long, help_heading = "Common options")]wait: bool,/// Wait timeout in seconds (only used with --wait)- #[arg(long, value_name = "seconds", help_heading = "Common options")]+ #[arg(+ long,+ value_parser = config::parse_positive_timeout,+ value_name = "seconds",+ help_heading = "Common options"+ )]timeout: Option<f64>,},/// [Data] Move or rename resource@@ -604,7 +620,12 @@ enum Commands {#[arg(long, default_value = "false", help_heading = "Common options")]wait: bool,/// Optional wait timeout in seconds- #[arg(long, value_name = "seconds", help_heading = "Common options")]+ #[arg(+ long,+ value_parser = config::parse_positive_timeout,+ value_name = "seconds",+ help_heading = "Common options"+ )]timeout: Option<f64>,},/// [Data] Update explicit retrieval tags metadata for a file or directory@@ -658,6 +679,7 @@ enum Commands {long = "node-limit",alias = "limit",default_value = "10",+ value_parser = clap::value_parser!(i32).range(0..),value_name = "n",help_heading = "Common options")]@@ -726,6 +748,7 @@ enum Commands {long = "node-limit",alias = "limit",default_value = "10",+ value_parser = clap::value_parser!(i32).range(0..),value_name = "n",help_heading = "Common options")]@@ -795,6 +818,7 @@ enum Commands {long = "node-limit",alias = "limit",default_value = "256",+ value_parser = clap::value_parser!(i32).range(0..),value_name = "n",help_heading = "Common options")]@@ -829,6 +853,7 @@ enum Commands {long = "node-limit",alias = "limit",default_value = "256",+ value_parser = clap::value_parser!(i32).range(0..),value_name = "n",help_heading = "Common options")]@@ -1013,7 +1038,12 @@ enum Commands {#[arg(long)]wait: bool,/// Local wait timeout in seconds; does not cancel the task- #[arg(long, requires = "wait", value_name = "seconds")]+ #[arg(+ long,+ requires = "wait",+ value_parser = config::parse_positive_timeout,+ value_name = "seconds"+ )]timeout: Option<f64>,},@@ -1021,7 +1051,12 @@ enum Commands {/// [Status] Wait for queued async processing to completeWait {/// Wait timeout in seconds- #[arg(long, value_name = "seconds", help_heading = "Common options")]+ #[arg(+ long,+ value_parser = config::parse_positive_timeout,+ value_name = "seconds",+ help_heading = "Common options"+ )]timeout: Option<f64>,},/// [Status] Track async resource processing tasks@@ -1247,7 +1282,7 @@ enum SystemCommands {/// Wait for queued async processing to completeWait {/// Wait timeout in seconds- #[arg(long, value_name = "seconds")]+ #[arg(long, value_parser = config::parse_positive_timeout, value_name = "seconds")]timeout: Option<f64>,},/// Show component status@@ -1301,6 +1336,7 @@ enum ObserverCommands {/// Get retrieval quality metricsRetrieval,/// Get filesystem operation metrics+ #[command(alias = "fs")]Filesystem,/// Get overall system statusSystem,@@ -1406,6 +1442,7 @@ enum SkillCommands {long = "node-limit",alias = "limit",default_value = "1000",+ value_parser = clap::value_parser!(i32).range(0..),value_name = "n")]node_limit: i32,@@ -1424,6 +1461,7 @@ enum SkillCommands {long = "node-limit",alias = "limit",default_value = "10",+ value_parser = clap::value_parser!(i32).range(0..),value_name = "n")]node_limit: i32,@@ -1771,6 +1809,10 @@ impl Commands {} | Commands::Version)}++ fn allows_invalid_runtime_config(&self) -> bool {+ matches!(self, Commands::Config { .. })+ }}#[derive(Subcommand)]@@ -2634,11 +2676,39 @@ fn language_command_can_run_picker(has_language_value: bool, is_interactive: boohas_language_value || is_interactive}+fn resolve_output_format(cli_output: Option<OutputFormat>, config: &Config) -> OutputFormat {+ cli_output.unwrap_or_else(|| OutputFormat::from(config.output.as_str()))+}++fn render_pre_language_help_request(args: &[OsString]) -> Option<String> {+ if !args+ .iter()+ .skip(1)+ .any(|arg| matches!(arg.to_str(), Some("-h" | "--help")))+ {+ return None;+ }++ let error = Cli::try_parse_from(args).err()?;+ if error.kind() != clap::error::ErrorKind::DisplayHelp {+ return None;+ }++ if help_ui::is_top_level_help_request(args) {+ return Some(help_ui::render_top_level_help());+ }+ help_ui::render_command_help_request(args).or_else(|| Some(error.to_string()))+}+#[tokio::main]async fn main() {let args = preprocess_cli_args(std::env::args_os().collect());let command_display = error_ui::display_command(&args);let (pre_parse_output_format, pre_parse_compact) = pre_parse_output_options(&args);+ if let Some(help) = render_pre_language_help_request(&args) {+ print!("{help}");+ return;+ }match ensure_language_selected_before_command(&args).await {Ok(true) => {}Ok(false) => return,@@ -2699,7 +2769,7 @@ async fn main() {}};- let output_format = cli.output;+ let output_override = cli.output;let compact = cli.compact;let legacy_upload_options = UploadCliOptions {progress: cli.progress,@@ -2762,7 +2832,7 @@ async fn main() {error_ui::print_runtime_error(&command_display,&e,- output_format,+ pre_parse_output_format,compact,cli.verbose,);@@ -2785,13 +2855,20 @@ async fn main() {error_ui::print_runtime_error(&command_display,&e,- output_format,+ pre_parse_output_format,compact,cli.verbose,);std::process::exit(2);}};+ let output_format = resolve_output_format(output_override, &config);+ if !cli.command.allows_invalid_runtime_config()+ && let Err(e) = config.validate_runtime_values()+ {+ error_ui::print_runtime_error(&command_display, &e, output_format, compact, cli.verbose);+ std::process::exit(2);+ }let ctx = CliContext::from_config(config,output_format,@@ -3418,11 +3495,12 @@ async fn main() {mod tests {use super::{Cli, CliContext, Commands, ConfigAddTarget, ConfigCommands, LanguageGateAction,- PrivacyCommands, SkillCommands, SnapshotCmd, UploadCliOptions, find_command_index,- first_command_token, is_language_command_request, language_command_can_run_picker,- language_gate_action, language_required_message, legacy_upload_option_error,- plain_help_misuse, pre_parse_output_options, pre_parse_requires_cli_config_file,- preprocess_cli_args, preprocess_privacy_args,+ ObserverCommands, PrivacyCommands, SkillCommands, SnapshotCmd, UploadCliOptions,+ find_command_index, first_command_token, is_language_command_request,+ language_command_can_run_picker, language_gate_action, language_required_message,+ legacy_upload_option_error, plain_help_misuse, pre_parse_output_options,+ pre_parse_requires_cli_config_file, preprocess_cli_args, preprocess_privacy_args,+ render_pre_language_help_request, resolve_output_format,};use crate::config::{Config, DEFAULT_CUSTOM_URL};use crate::output::OutputFormat;@@ -4312,7 +4390,7 @@ mod tests {let show_global_output =Cli::try_parse_from(["ov", "skills", "show", "code-review", "-o", "json"]).expect("skills show should accept global -o after the subcommand");- assert_eq!(show_global_output.output, OutputFormat::Json);+ assert_eq!(show_global_output.output, Some(OutputFormat::Json));let remove = Cli::try_parse_from(["ov", "skills", "remove", "foo", "bar", "--yes"]).expect("skills remove --yes should parse");@@ -4465,6 +4543,154 @@ mod tests {}}+ #[test]+ fn all_timeout_options_require_positive_finite_seconds() {+ let command_prefixes = [+ vec!["ov", "add-resource", "https://example.com", "--timeout"],+ vec!["ov", "add-skill", "skill", "--timeout"],+ vec!["ov", "rm", "viking://resources/item", "--timeout"],+ vec![+ "ov",+ "write",+ "viking://resources/item",+ "--content",+ "value",+ "--timeout",+ ],+ vec![+ "ov",+ "compile",+ "--from",+ "viking://resources/source",+ "--to",+ "viking://resources/target",+ "--skill",+ "viking://user/skills/compiler",+ "--wait",+ "--timeout",+ ],+ vec!["ov", "wait", "--timeout"],+ vec!["ov", "system", "wait", "--timeout"],+ ];++ for prefix in command_prefixes {+ for invalid in ["0", "-1", "inf", "NaN", "1e300"] {+ let mut args = prefix.clone();+ args.push(invalid);+ assert!(+ Cli::try_parse_from(&args).is_err(),+ "{args:?} should reject an invalid timeout"+ );+ }++ let mut args = prefix;+ args.push("0.1");+ assert!(+ Cli::try_parse_from(&args).is_ok(),+ "{args:?} should accept a positive finite timeout"+ );+ }+ }++ #[test]+ fn all_node_limit_options_accept_zero_and_reject_negative_values() {+ let command_prefixes = [+ vec!["ov", "ls", "--node-limit"],+ vec!["ov", "tree", "viking://resources", "--node-limit"],+ vec!["ov", "find", "query", "--node-limit"],+ vec!["ov", "search", "query", "--node-limit"],+ vec!["ov", "grep", "query", "--node-limit"],+ vec!["ov", "glob", "**/*", "--node-limit"],+ vec!["ov", "skills", "list", "--node-limit"],+ vec!["ov", "skills", "find", "query", "--node-limit"],+ ];++ for prefix in command_prefixes {+ let mut negative_args = prefix.clone();+ negative_args.push("-1");+ assert!(+ Cli::try_parse_from(&negative_args).is_err(),+ "{negative_args:?} should reject a negative node limit"+ );++ let mut zero_args = prefix.clone();+ zero_args.push("0");+ assert!(+ Cli::try_parse_from(&zero_args).is_ok(),+ "{zero_args:?} should preserve the established zero-limit semantics"+ );++ let mut args = prefix;+ args.push("1");+ assert!(+ Cli::try_parse_from(&args).is_ok(),+ "{args:?} should accept a positive node limit"+ );+ }+ }++ #[test]+ fn config_commands_can_load_invalid_runtime_values_for_repair() {+ let cli = Cli::try_parse_from(["ov", "config", "show"]).expect("config show should parse");+ assert!(cli.command.allows_invalid_runtime_config());++ let status = Cli::try_parse_from(["ov", "status"]).expect("status should parse");+ assert!(!status.command.allows_invalid_runtime_config());+ }++ #[test]+ fn configured_output_is_used_unless_cli_overrides_it() {+ let config = Config {+ output: "json".to_string(),+ ..Config::default()+ };++ assert_eq!(resolve_output_format(None, &config), OutputFormat::Json);+ assert_eq!(+ resolve_output_format(Some(OutputFormat::Table), &config),+ OutputFormat::Table+ );+ let cli = Cli::try_parse_from(["ov", "status"]).unwrap();+ assert_eq!(cli.output, None);++ let invalid_config = Config {+ output: "yaml".to_string(),+ ..Config::default()+ };+ assert_eq!(+ resolve_output_format(None, &invalid_config),+ OutputFormat::Table,+ "repair commands need a safe fallback for invalid persisted output"+ );+ }++ #[test]+ fn only_explicit_clap_help_bypasses_language_setup() {+ for args in [+ ["ov", "--help"].as_slice(),+ ["ov", "-h"].as_slice(),+ ["ov", "status", "--help"].as_slice(),+ ["ov", "system", "wait", "-h"].as_slice(),+ ] {+ assert!(+ render_pre_language_help_request(&os_args(args)).is_some(),+ "{args:?} should render before language setup"+ );+ }++ for args in [+ ["ov", "status"].as_slice(),+ ["ov", "task"].as_slice(),+ ["ov", "-help"].as_slice(),+ ["ov", "--account", "--help", "status"].as_slice(),+ ] {+ assert!(+ render_pre_language_help_request(&os_args(args)).is_none(),+ "{args:?} should keep the language gate"+ );+ }+ }+#[test]fn language_gate_detects_language_command_after_global_flags() {assert!(is_language_command_request(&os_args(&["ov", "language"])));@@ -4849,6 +5075,36 @@ mod tests {assert_eq!(client.api_key(), Some("root-key"));}+ #[test]+ fn observer_alias_and_snapshot_restore_examples_parse() {+ let observer = Cli::try_parse_from(["ov", "observer", "fs"]).unwrap();+ assert!(matches!(+ observer.command,+ Commands::Observer {+ action: ObserverCommands::Filesystem+ }+ ));++ let snapshot = Cli::try_parse_from([+ "ov",+ "snapshot",+ "restore",+ "abc123",+ "viking://projects/acme",+ ])+ .unwrap();+ assert!(matches!(+ snapshot.command,+ Commands::Snapshot {+ cmd: SnapshotCmd::Restore {+ source_commit,+ project_dir,+ ..+ }+ } if source_commit == "abc123" && project_dir.as_deref() == Some("viking://projects/acme")+ ));+ }+#[test]fn cli_write_rejects_removed_semantic_flags() {let result = Cli::try_parse_from([diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.mdindex 5a393b6e0..a876481ca 100644--- a/docs/en/api/01-overview.md+++ b/docs/en/api/01-overview.md@@ -191,7 +191,7 @@ client.initialize()#### HTTP Call Examples- CLI, `SyncHTTPClient`, and `AsyncHTTPClient` automatically upload local files or directories before calling the server API.-- Python HTTP client and CLI can also opt into shared temporary uploads via client config (`ovcli.conf` -> `upload.mode = "shared"`).+- Python HTTP clients can opt into shared temporary uploads through `ovcli.conf` (`upload.mode = "shared"`). The Rust `ov` CLI does not read that field; set `OPENVIKING_UPLOAD_MODE=shared` for `ov` instead.- Raw HTTP calls don't get this convenience layer. When using `curl` or other HTTP clients, you need to first call `POST /api/v1/resources/temp_upload`, then pass the returned `temp_file_id` to the target API.- `temp_upload` defaults to `upload_mode=local`. Use `upload_mode=shared` only when you explicitly want distributed shared temporary uploads.- For raw HTTP imports of local directories, you need to first zip them into a `.zip` file and upload using the above method; the server does not accept direct host directory paths.diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.mdindex 662904b68..8d0bfe930 100644--- a/docs/en/api/04-skills.md+++ b/docs/en/api/04-skills.md@@ -183,7 +183,7 @@ Skills are a special type of resource that define actions or tools agents can pe- Send structured skill data directly in `data`- Send raw `SKILL.md` content in `data`- First call `POST /api/v1/resources/temp_upload` to upload a local `SKILL.md` file/zip directory, then call `POST /api/v1/skills` with `temp_file_id`- - `temp_upload` defaults to local temporary storage; pass `upload_mode=shared` only when you explicitly need distributed shared temporary uploads. In Python HTTP client / CLI flows, this can also be driven by `ovcli.conf` via `upload.mode = "shared"`+ - `temp_upload` defaults to local temporary storage; pass `upload_mode=shared` only when you explicitly need distributed shared temporary uploads. Python HTTP clients can set `upload.mode = "shared"` in `ovcli.conf`; the Rust `ov` CLI instead uses `OPENVIKING_UPLOAD_MODE=shared`- `POST /api/v1/skills` does not accept direct host filesystem paths in `data`.- **Targeting**:diff --git a/docs/en/api/99-api-doc-writing-guide.md b/docs/en/api/99-api-doc-writing-guide.mdindex c1fdee53a..26a411dff 100644--- a/docs/en/api/99-api-doc-writing-guide.md+++ b/docs/en/api/99-api-doc-writing-guide.md@@ -30,7 +30,7 @@ Explain the purpose of this API, point to the corresponding code entry, and brie**Code Entry**:- `openviking/<module>/<file>.py:<ClassName>.<MethodName>` - Core implementation- `openviking/server/routers/<router-file>.py` - HTTP router-- `openviking_cli/commands/<command-file>.py` - CLI command+- `crates/ov_cli/src/commands/<command-file>.rs` - CLI command#### 2. Interface and Parameter Description@@ -180,10 +180,11 @@ Add resources to the knowledge base, supporting various sources such as local fi5. Build vector index**Code Entry**:-- `openviking/core/client.py:OpenViking.add_resource()` - SDK entry-- `openviking/resource/importer.py:ResourceImporter.import_resource()` - Core implementation-- `openviking/server/routers/resources.py` - HTTP router-- `openviking_cli/commands/resources.py` - CLI command+- `openviking/async_client.py:AsyncOpenViking.add_resource()` - Async SDK entry+- `openviking/sync_client.py:SyncOpenViking.add_resource()` - Sync SDK entry+- `openviking/service/resource_service.py:ResourceService.add_resource()` - Core implementation+- `openviking/server/routers/resources.py:add_resource()` - HTTP router+- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - CLI handler#### 2. Interface and Parameter Descriptiondiff --git a/docs/en/concepts/04-viking-uri.md b/docs/en/concepts/04-viking-uri.mdindex 9d8b8d518..28d841969 100644--- a/docs/en/concepts/04-viking-uri.md+++ b/docs/en/concepts/04-viking-uri.md@@ -204,7 +204,7 @@ ov add-resource --parent-auto-create "viking://resources/emails/{calendar:today}ov read "viking://resources/logs/{calendar:yesterday}/app.log"# Prep tomorrow's tasks-ov write --uri "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "Plan the day"+ov write "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "Plan the day"# Upload monthly report, --parent-auto-create can be shortened to -pov add-resource --parent-auto-create "viking://resources/reports/{calendar:ym}" ./report.pdfdiff --git a/docs/en/concepts/10-encryption.md b/docs/en/concepts/10-encryption.mdindex db36dd366..6b49a3388 100644--- a/docs/en/concepts/10-encryption.md+++ b/docs/en/concepts/10-encryption.md@@ -85,7 +85,7 @@ Suitable for development and single-node deployments:**Initialization command**:```bash-ov system crypto init-key --output ~/.openviking/master.key+ov system crypto init-key --output-file ~/.openviking/master.key```### Vault (HashiCorp Vault)diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex edb1cec85..80b0e9dd9 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -13,7 +13,7 @@ openviking-server doctor## Configuration File-Create `~/.openviking/ov.conf` in your project directory:+Create `~/.openviking/ov.conf` in your home configuration directory:```json{@@ -1402,7 +1402,7 @@ Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI t| `upload.ignore_dirs` | Default directory ignore list for `add-resource` (CSV) | `null` || `upload.include` | Default include patterns for `add-resource` (CSV) | `null` || `upload.exclude` | Default exclude patterns for `add-resource` (CSV) | `null` |-| `upload.mode` | Temporary upload backend: `"local"` (per-instance disk) or `"shared"` (distributed shared store, required when consumer requests can land on a different server instance than the upload). Per-call override via `OPENVIKING_UPLOAD_MODE`. | `null` (server's `temp_upload.default_mode`, which itself defaults to `"local"`) |+| `upload.mode` | Python HTTP-client temporary upload backend: `"local"` (per-instance disk) or `"shared"` (distributed shared store). The Rust `ov` CLI does not read this field; set `OPENVIKING_UPLOAD_MODE=shared` for shared uploads. | `null` (server's `temp_upload.default_mode`, which itself defaults to `"local"`) |Local directory uploads respect `.gitignore` files (root and nested). `ignore_dirs/include/exclude` apply on top of that.diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.mdindex 5eb57b059..c51448849 100644--- a/docs/en/guides/03-deployment.md+++ b/docs/en/guides/03-deployment.md@@ -170,7 +170,7 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.confThen use the CLI:```bash-python -m openviking ls viking://resources/+ov ls viking://resources/```### curldiff --git a/docs/en/guides/07-operation-telemetry.md b/docs/en/guides/07-operation-telemetry.mdindex 4595ec6ed..a8c55a217 100644--- a/docs/en/guides/07-operation-telemetry.md+++ b/docs/en/guides/07-operation-telemetry.md@@ -120,7 +120,7 @@ curl -X POST http://localhost:1933/api/v1/resources/temp_upload \```This endpoint currently accepts the boolean form only.-`upload_mode` is also a form field for this endpoint; it defaults to `local` and should only be set to `shared` when you explicitly need distributed shared temporary uploads. Python HTTP client / CLI users can alternatively drive the same behavior with `ovcli.conf` -> `upload.mode = "shared"`.+`upload_mode` is also a form field for this endpoint; it defaults to `local` and should only be set to `shared` when you explicitly need distributed shared temporary uploads. Python HTTP clients can alternatively set `upload.mode = "shared"` in `ovcli.conf`; the Rust `ov` CLI uses `OPENVIKING_UPLOAD_MODE=shared` instead.## Common summary groupsdiff --git a/docs/en/guides/08-encryption.md b/docs/en/guides/08-encryption.mdindex 1c226b385..5700b632e 100644--- a/docs/en/guides/08-encryption.md+++ b/docs/en/guides/08-encryption.md@@ -31,7 +31,7 @@ See the [Multi-Write Storage Guide](./13-multi-write-storage.md) for more multi-### 1. Initialize Root Key (Local Mode)```bash-ov system crypto init-key --output ~/.openviking/master.key+ov system crypto init-key --output-file ~/.openviking/master.key```### 2. Configure Encryption@@ -176,10 +176,10 @@ For maximum API key protection, you can enable Argon2id one-way hashing:```bash# Generate and save to specified path-ov system crypto init-key --output ~/.openviking/master.key+ov system crypto init-key --output-file ~/.openviking/master.key# Or use short option-ov system crypto init-key -o ~/.openviking/master.key+ov system crypto init-key -f ~/.openviking/master.key```**Output example**:diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex e775110cb..905d7132e 100644--- a/docs/zh/api/01-overview.md+++ b/docs/zh/api/01-overview.md@@ -186,7 +186,7 @@ client.initialize()#### HTTP 调用示例- CLI、`SyncHTTPClient`、`AsyncHTTPClient` 遇到本地文件或目录时,会先自动上传,再调用服务端 API。-- Python HTTP client 和 CLI 也可以通过客户端配置启用 shared 临时上传(`ovcli.conf` 中设置 `upload.mode = "shared"`)。+- Python HTTP client 可以通过 `ovcli.conf` 启用 shared 临时上传(设置 `upload.mode = "shared"`)。Rust `ov` CLI 不读取这个字段;使用 `ov` 时请设置 `OPENVIKING_UPLOAD_MODE=shared`。- 裸 HTTP 调用没有这层封装。使用 `curl` 或其他 HTTP 客户端时,需要先调用 `POST /api/v1/resources/temp_upload`,再把返回的 `temp_file_id` 传给目标 API。- `temp_upload` 默认使用 `upload_mode=local`。只有在你显式需要分布式共享临时上传时,才应传 `upload_mode=shared`。- 裸 HTTP 如果导入本地目录,需要先自行打成 `.zip` 再通过上述方法上传;服务端不接受直接传宿主机目录路径。diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.mdindex 5385796ba..cd75b579c 100644--- a/docs/zh/api/04-skills.md+++ b/docs/zh/api/04-skills.md@@ -183,7 +183,7 @@ This tool wraps the MCP tool `search-web`. Call this when the user needs functio1. 在 `data` 中直接传结构化 skill 数据2. 在 `data` 中直接传原始 `SKILL.md` 内容3. 先调用 `POST /api/v1/resources/temp_upload` 上传本地 `SKILL.md` 文件/zip 目录,再调用 `POST /api/v1/skills` 并传入 `temp_file_id`- 4. `temp_upload` 默认使用本地临时存储;只有在明确需要分布式共享临时上传时,才传 `upload_mode=shared`。在 Python HTTP client / CLI 流程里,也可以通过 `ovcli.conf` 的 `upload.mode = "shared"` 驱动这一行为+ 4. `temp_upload` 默认使用本地临时存储;只有在明确需要分布式共享临时上传时,才传 `upload_mode=shared`。Python HTTP client 可以在 `ovcli.conf` 中设置 `upload.mode = "shared"`;Rust `ov` CLI 则使用 `OPENVIKING_UPLOAD_MODE=shared`- `POST /api/v1/skills` 不接受在 `data` 中直接传宿主机本地路径。- **目标规则**:diff --git a/docs/zh/api/99-api-doc-writing-guide.md b/docs/zh/api/99-api-doc-writing-guide.mdindex f94884a20..6d486112a 100644--- a/docs/zh/api/99-api-doc-writing-guide.md+++ b/docs/zh/api/99-api-doc-writing-guide.md@@ -30,7 +30,7 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号**代码入口**:- `openviking/<模块>/<文件>.py:<类名>.<方法名>` - 核心实现- `openviking/server/routers/<路由文件>.py` - HTTP 路由-- `openviking_cli/commands/<命令文件>.py` - CLI 命令+- `crates/ov_cli/src/commands/<命令文件>.rs` - CLI 命令#### 2. 接口和参数说明@@ -174,10 +174,11 @@ API 文档应按 API 模块和具体接口组织,而不是按客户端语言5. 建立向量索引**代码入口**:-- `openviking/core/client.py:OpenViking.add_resource()` - SDK 入口-- `openviking/resource/importer.py:ResourceImporter.import_resource()` - 核心实现-- `openviking/server/routers/resources.py` - HTTP 路由-- `openviking_cli/commands/resources.py` - CLI 命令+- `openviking/async_client.py:AsyncOpenViking.add_resource()` - 异步 SDK 入口+- `openviking/sync_client.py:SyncOpenViking.add_resource()` - 同步 SDK 入口+- `openviking/service/resource_service.py:ResourceService.add_resource()` - 核心实现+- `openviking/server/routers/resources.py:add_resource()` - HTTP 路由+- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - CLI 处理函数#### 2. 接口和参数说明diff --git a/docs/zh/concepts/04-viking-uri.md b/docs/zh/concepts/04-viking-uri.mdindex c0b61fa34..715e9bb44 100644--- a/docs/zh/concepts/04-viking-uri.md+++ b/docs/zh/concepts/04-viking-uri.md@@ -201,7 +201,7 @@ ov add-resource --parent-auto-create "viking://resources/emails/{calendar:today}ov read "viking://resources/logs/{calendar:yesterday}/app.log"# 准备明天的任务-ov write --uri "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "规划一天"+ov write "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "规划一天"# 上传月度报告 --parent-auto-create 可以简写为 -pov add-resource --parent-auto-create "viking://resources/reports/{calendar:ym}" ./report.pdfdiff --git a/docs/zh/concepts/10-encryption.md b/docs/zh/concepts/10-encryption.mdindex abe479f9b..34566e6b9 100644--- a/docs/zh/concepts/10-encryption.md+++ b/docs/zh/concepts/10-encryption.md@@ -85,7 +85,7 @@ OpenViking 支持三种密钥提供程序,适应不同的部署场景:**初始化命令**:```bash-ov crypto init-key --output ~/.openviking/master.key+ov system crypto init-key --output-file ~/.openviking/master.key```### Vault(HashiCorp Vault)diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 05dda0ca8..b16ed5fb4 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -13,7 +13,7 @@ openviking-server doctor## 快速开始-在项目目录创建 `~/.openviking/ov.conf`:+在用户配置目录 `~/.openviking/` 下创建 `ov.conf`:```json{@@ -1368,7 +1368,7 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远| `upload.ignore_dirs` | `add-resource` 默认忽略目录列表(CSV) | `null` || `upload.include` | `add-resource` 默认包含模式(CSV) | `null` || `upload.exclude` | `add-resource` 默认排除模式(CSV) | `null` |-| `upload.mode` | 临时上传后端:`"local"`(仅当前实例本地磁盘)或 `"shared"`(分布式共享存储,当消费请求可能落到不同实例时必需)。可通过 `OPENVIKING_UPLOAD_MODE` 单次覆盖。 | `null`(使用服务端 `temp_upload.default_mode`,默认仍为 `"local"`) |+| `upload.mode` | Python HTTP client 的临时上传后端:`"local"`(仅当前实例本地磁盘)或 `"shared"`(分布式共享存储)。Rust `ov` CLI 不读取这个字段;如需 shared 上传,请设置 `OPENVIKING_UPLOAD_MODE=shared`。 | `null`(使用服务端 `temp_upload.default_mode`,默认仍为 `"local"`) |本地目录上传会默认遵循 `.gitignore`(根目录和子目录,含 `!` 反向规则)。`ignore_dirs/include/exclude` 会在此基础上进一步过滤。diff --git a/docs/zh/guides/07-operation-telemetry.md b/docs/zh/guides/07-operation-telemetry.mdindex 5a5e4acb5..ef44541e9 100644--- a/docs/zh/guides/07-operation-telemetry.md+++ b/docs/zh/guides/07-operation-telemetry.md@@ -120,7 +120,7 @@ curl -X POST http://localhost:1933/api/v1/resources/temp_upload \```这个接口当前只支持布尔形态的表单参数。-这个接口的 `upload_mode` 也是表单字段;默认值为 `local`,只有在明确需要分布式共享临时上传时,才应设置为 `shared`。Python HTTP client / CLI 用户也可以通过 `ovcli.conf` 的 `upload.mode = "shared"` 达到同样效果。+这个接口的 `upload_mode` 也是表单字段;默认值为 `local`,只有在明确需要分布式共享临时上传时,才应设置为 `shared`。Python HTTP client 也可以在 `ovcli.conf` 中设置 `upload.mode = "shared"`;Rust `ov` CLI 则使用 `OPENVIKING_UPLOAD_MODE=shared`。## 常见 summary 分组diff --git a/docs/zh/guides/08-encryption.md b/docs/zh/guides/08-encryption.mdindex da12b8d5d..166ee5aeb 100644--- a/docs/zh/guides/08-encryption.md+++ b/docs/zh/guides/08-encryption.md@@ -31,7 +31,7 @@ OpenViking 提供透明的静态数据加密,确保多租户环境下的数据### 1. 初始化根密钥(Local 模式)```bash-ov system crypto init-key --output ~/.openviking/master.key+ov system crypto init-key --output-file ~/.openviking/master.key```### 2. 配置加密@@ -176,10 +176,10 @@ OpenViking 提供两层加密保护:```bash# 生成并保存到指定路径-ov system crypto init-key --output ~/.openviking/master.key+ov system crypto init-key --output-file ~/.openviking/master.key# 或者使用简短命令-ov system crypto init-key -o ~/.openviking/master.key+ov system crypto init-key -f ~/.openviking/master.key```**输出示例**: