Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(ovpack): add v2 manifest and backup restore (#1927)
Qin Haojiee648b2679c22
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 9e7da0819..e72cb80de 100644--- a/crates/ov_cli/src/client.rs+++ b/crates/ov_cli/src/client.rs@@ -638,12 +638,14 @@ impl HttpClient {// ============ Pack Methods ============- pub async fn export_ovpack(&self, uri: &str, to: &str) -> Result<String> {- let body = serde_json::json!({- "uri": uri,- });-- let url = format!("{}/api/v1/pack/export", self.base.base_url);+ async fn download_pack(+ &self,+ endpoint: &str,+ body: serde_json::Value,+ to: &str,+ default_name: &str,+ ) -> Result<String> {+ let url = format!("{}{}", self.base.base_url, endpoint);let response = self.base.http@@ -689,12 +691,7 @@ impl HttpClient {let to_path = Path::new(to);let final_path = if to_path.is_dir() {- let base_name = uri- .trim_end_matches('/')- .split('/')- .last()- .unwrap_or("export");- to_path.join(format!("{}.ovpack", base_name))+ to_path.join(format!("{}.ovpack", default_name))} else if !to.ends_with(".ovpack") {Path::new(&format!("{}.ovpack", to)).to_path_buf()} else {@@ -710,12 +707,34 @@ impl HttpClient {Ok(final_path.to_string_lossy().to_string())}+ pub async fn export_ovpack(&self, uri: &str, to: &str) -> Result<String> {+ let body = serde_json::json!({+ "uri": uri,+ });+ let base_name = uri+ .trim_end_matches('/')+ .split('/')+ .last()+ .unwrap_or("export");+ self.download_pack("/api/v1/pack/export", body, to, base_name)+ .await+ }++ pub async fn backup_ovpack(&self, to: &str) -> Result<String> {+ self.download_pack(+ "/api/v1/pack/backup",+ serde_json::json!({}),+ to,+ "openviking-backup",+ )+ .await+ }+pub async fn import_ovpack(&self,file_path: &str,parent: &str,- force: bool,- vectorize: bool,+ on_conflict: Option<&str>,) -> Result<serde_json::Value> {let file_path_obj = Path::new(file_path);@@ -730,15 +749,41 @@ impl HttpClient {}let temp_file_id = self.upload_temp_file(file_path_obj).await?;+ let conflict_policy = on_conflict.unwrap_or("fail");let body = serde_json::json!({"temp_file_id": temp_file_id,"parent": parent,- "force": force,- "vectorize": vectorize,+ "on_conflict": conflict_policy,});self.post("/api/v1/pack/import", &body).await}+ pub async fn restore_ovpack(+ &self,+ file_path: &str,+ on_conflict: Option<&str>,+ ) -> Result<serde_json::Value> {+ let file_path_obj = Path::new(file_path);++ if !file_path_obj.exists() {+ return Err(Error::Client(format!(+ "Local ovpack file not found: {}",+ file_path+ )));+ }+ if !file_path_obj.is_file() {+ return Err(Error::Client(format!("Path is not a file: {}", file_path)));+ }++ let temp_file_id = self.upload_temp_file(file_path_obj).await?;+ let conflict_policy = on_conflict.unwrap_or("fail");+ let body = serde_json::json!({+ "temp_file_id": temp_file_id,+ "on_conflict": conflict_policy,+ });+ self.post("/api/v1/pack/restore", &body).await+ }+// ============ Admin Methods ============pub async fn admin_create_account(diff --git a/crates/ov_cli/src/commands/pack.rs b/crates/ov_cli/src/commands/pack.rsindex 54341659a..5ab409b9f 100644--- a/crates/ov_cli/src/commands/pack.rs+++ b/crates/ov_cli/src/commands/pack.rs@@ -21,19 +21,46 @@ pub async fn export(Ok(())}+pub async fn backup(+ client: &HttpClient,+ to: &str,+ format: OutputFormat,+ compact: bool,+) -> Result<()> {+ let file_path = client.backup_ovpack(to).await?;++ let result = serde_json::json!({+ "file": file_path,+ "message": format!("Successfully backed up to {}", file_path)+ });++ output_success(&result, format, compact);+ Ok(())+}+pub async fn import(client: &HttpClient,file_path: &str,target: &str,- force: bool,- no_vectorize: bool,+ on_conflict: Option<&str>,format: OutputFormat,compact: bool,) -> Result<()> {- let vectorize = !no_vectorize;let result = client- .import_ovpack(file_path, target, force, vectorize)+ .import_ovpack(file_path, target, on_conflict).await?;output_success(&result, format, compact);Ok(())}++pub async fn restore(+ client: &HttpClient,+ file_path: &str,+ on_conflict: Option<&str>,+ format: OutputFormat,+ compact: bool,+) -> Result<()> {+ let result = client.restore_ovpack(file_path, on_conflict).await?;+ output_success(&result, format, compact);+ Ok(())+}diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rsindex 2c44a0ea0..10ff8a7db 100644--- a/crates/ov_cli/src/handlers.rs+++ b/crates/ov_cli/src/handlers.rs@@ -165,11 +165,15 @@ pub async fn handle_export(uri: String, to: String, ctx: CliContext) -> Result<(commands::pack::export(&client, &uri, &to, ctx.output_format, ctx.compact).await}+pub async fn handle_backup(to: String, ctx: CliContext) -> Result<()> {+ let client = ctx.get_client();+ commands::pack::backup(&client, &to, ctx.output_format, ctx.compact).await+}+pub async fn handle_import(file_path: String,target_uri: String,- force: bool,- no_vectorize: bool,+ on_conflict: Option<String>,ctx: CliContext,) -> Result<()> {let client = ctx.get_client();@@ -177,8 +181,23 @@ pub async fn handle_import(&client,&file_path,&target_uri,- force,- no_vectorize,+ on_conflict.as_deref(),+ ctx.output_format,+ ctx.compact,+ )+ .await+}++pub async fn handle_restore(+ file_path: String,+ on_conflict: Option<String>,+ ctx: CliContext,+) -> Result<()> {+ let client = ctx.get_client();+ commands::pack::restore(+ &client,+ &file_path,+ on_conflict.as_deref(),ctx.output_format,ctx.compact,)diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex c291f3bfa..1a2f54b99 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -494,18 +494,28 @@ enum Commands {/// Output .ovpack file pathto: String,},+ /// [Data] Back up public OpenViking scopes as a restore-only .ovpack+ Backup {+ /// Output .ovpack file path+ to: String,+ },/// [Data] Import .ovpack into target URIImport {/// Input .ovpack file pathfile_path: String,/// Target parent URItarget_uri: String,- /// Overwrite when conflicts exist- #[arg(long)]- force: bool,- /// Disable vectorization after import- #[arg(long)]- no_vectorize: bool,+ /// Conflict policy: fail, overwrite, or skip+ #[arg(long, value_parser = ["fail", "overwrite", "skip"])]+ on_conflict: Option<String>,+ },+ /// [Data] Restore a backup .ovpack to original public scope roots+ Restore {+ /// Input backup .ovpack file path+ file_path: String,+ /// Conflict policy: fail, overwrite, or skip+ #[arg(long, value_parser = ["fail", "overwrite", "skip"])]+ on_conflict: Option<String>,},// --- Interactive Tools ---/// [Interactive] Interactive TUI file explorer@@ -1058,12 +1068,18 @@ async fn main() {} => handlers::handle_link(from_uri, to_uris, reason, ctx).await,Commands::Unlink { from_uri, to_uri } => handlers::handle_unlink(from_uri, to_uri, ctx).await,Commands::Export { uri, to } => handlers::handle_export(uri, to, ctx).await,+ Commands::Backup { to } => handlers::handle_backup(to, ctx).await,Commands::Import {file_path,target_uri,- force,- no_vectorize,- } => handlers::handle_import(file_path, target_uri, force, no_vectorize, ctx).await,+ on_conflict,+ } => {+ handlers::handle_import(file_path, target_uri, on_conflict, ctx).await+ }+ Commands::Restore {+ file_path,+ on_conflict,+ } => handlers::handle_restore(file_path, on_conflict, ctx).await,Commands::Wait { timeout } => {let client = ctx.get_client();commands::system::wait(&client, timeout, ctx.output_format, ctx.compact).await@@ -1376,6 +1392,32 @@ mod tests {assert!(result.is_err(), "removed write flags should not parse");}+ #[test]+ fn cli_import_rejects_removed_vectorize_flag() {+ let result = Cli::try_parse_from([+ "ov",+ "import",+ "./exports/demo.ovpack",+ "viking://resources/imported/",+ "--no-vectorize",+ ]);++ assert!(result.is_err(), "removed import vectorize flag should not parse");+ }++ #[test]+ fn cli_import_rejects_removed_force_flag() {+ let result = Cli::try_parse_from([+ "ov",+ "import",+ "./exports/demo.ovpack",+ "viking://resources/imported/",+ "--force",+ ]);++ assert!(result.is_err(), "removed import force flag should not parse");+ }+#[test]fn cli_parses_reindex_command() {let result = Cli::try_parse_from([diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.mdindex cf46151d5..7a86389c0 100644--- a/docs/en/api/01-overview.md+++ b/docs/en/api/01-overview.md@@ -363,6 +363,8 @@ Below are all HTTP API endpoints provided by OpenViking, grouped by functional m|--------|------|-------------|------------|| POST | `/api/v1/pack/export` | Export .ovpack | ROOT/ADMIN || POST | `/api/v1/pack/import` | Import .ovpack | ROOT/ADMIN |+| POST | `/api/v1/pack/backup` | Back up public scopes | ROOT/ADMIN |+| POST | `/api/v1/pack/restore` | Restore backup package | ROOT/ADMIN |### File Systemdiff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.mdindex 6011c14c0..5e106fc6c 100644--- a/docs/en/api/03-filesystem.md+++ b/docs/en/api/03-filesystem.md@@ -986,8 +986,16 @@ Packages all resources under the specified URI into a `.ovpack` file for backup**Processing Flow**:1. Verify user permissions2. Traverse resources under the specified URI-3. Package into zip format (`.ovpack`)-4. Return as file stream+3. Write content files and the OVPack manifest+4. Package into zip format (`.ovpack`)+5. Return as file stream++**Format Notes**:+- The exported ZIP contains `<root>/_._ovpack_manifest.json`, the escaped ZIP name for `.ovpack_manifest.json`.+- `entries[].path` is relative to the exported root; `""` means the root directory itself.+- File entries include `size` and `sha256`; `content_sha256` covers the sorted file list of `path`, `size`, and `sha256`.+- Raw embedding vectors and runtime fields such as `created_at`, `updated_at`, and `active_count` are not exported.+- OVPack does not add package-size, file-count, or directory-depth limits; the practical limit comes from ZIP, the storage backend, and the runtime environment.**Code Entry Points**:- `openviking/server/routers/pack.py:export_ovpack` - HTTP router@@ -1059,8 +1067,9 @@ Imports a `.ovpack` file to a specified location for restoring or migrating data**Processing Flow**:1. Verify user permissions2. Parse uploaded `.ovpack` file-3. Import resources to target location-4. Optionally trigger vectorization+3. Validate manifest metadata, paths, file and directory sets, file sizes, and checksums+4. Apply `on_conflict`+5. Import resources to target location and rebuild vectors**Code Entry Points**:- `openviking/server/routers/pack.py:import_ovpack` - HTTP router@@ -1075,11 +1084,23 @@ Imports a `.ovpack` file to a specified location for restoring or migrating data|-----------|------|----------|---------|-------------|| temp_file_id | string | Yes | - | Temporary upload file ID (obtained via [temp_upload](02-resources.md#temp_upload)) || parent | string | Yes | - | Target parent URI (import to this location) |-| force | bool | No | False | Whether to overwrite existing resources |-| vectorize | bool | No | True | Whether to trigger vectorization |+| on_conflict | string | No | fail | Conflict policy: `fail`, `overwrite`, or `skip` |**Permission Requirements**: ROOT or ADMIN+**Behavior Notes**:+- Imports always rebuild vectors in the target environment. The API no longer accepts `vectorize` or `force`.+- Session imports restore session files and do not trigger vectorization.+- `on_conflict=fail` returns a structured `409 CONFLICT` when the target root already exists.+- `on_conflict=overwrite` replaces the existing target root. `on_conflict=skip` keeps the existing target root and returns it without writing package contents. `skip` is root-level, not file-level.+- Packages without a manifest are rejected by default because they cannot provide content integrity guarantees.+- Packages with manifest entries are rejected if content files or directories are missing, extra files or directories are present, file sizes differ, per-file `sha256` differs, or `content_sha256` is missing or differs.+- Packages whose manifest `format_version` is not the current supported version are rejected.+- `.abstract.md` and `.overview.md` are restored as semantic sidecars. `.relations.json` and OVPack internals are excluded.+- Manifest `context_type` must match the final import path semantics.+- Top-level scope packages such as `viking://resources/` must be imported to `viking://`.+- OVPack does not add import package-size, file-count, or directory-depth limits; the practical limit comes from ZIP, the storage backend, and the runtime environment.+#### 3. Usage Examples**HTTP API**@@ -1105,8 +1126,7 @@ curl -X POST http://localhost:1933/api/v1/pack/import \-d "{\"temp_file_id\": \"$TEMP_FILE_ID\",\"parent\": \"viking://resources/imported/\",- \"force\": true,- \"vectorize\": true+ \"on_conflict\": \"overwrite\"}"```@@ -1128,11 +1148,8 @@ client.initialize()# Import .ovpack fileov import ./exports/my-project.ovpack viking://resources/imported/-# Force overwrite existing content-ov import ./exports/my-project.ovpack viking://resources/imported/ --force--# Skip vectorization-ov import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize+# Explicit conflict policy+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite```**Response Example**@@ -1149,6 +1166,83 @@ ov import ./exports/my-project.ovpack viking://resources/imported/ --no-vectoriz}```+**Conflict Error Example**++```json+{+ "status": "error",+ "error": {+ "code": "CONFLICT",+ "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",+ "details": {+ "resource": "viking://resources/imported/my-project"+ }+ }+}+```++---++### backup_ovpack++Back up public scope roots as a restore-only `.ovpack` file. The backup includes+`resources`, `user`, `agent`, and `session`; it excludes internal runtime data+such as `temp` and `queue`.++```+POST /api/v1/pack/backup+```++```bash+curl -X POST http://localhost:1933/api/v1/pack/backup \+ -H "X-API-Key: your-admin-key" \+ --output openviking-backup.ovpack+```++CLI:++```bash+ov backup ./backups/openviking.ovpack+```++---++### restore_ovpack++Restore a backup package created by `backup_ovpack` to the original public scope+roots. Regular import rejects backup packages. Non-session content is+re-vectorized after restore; session files are restored without vectorization.++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| temp_file_id | string | Yes | - | Temporary upload file ID |+| on_conflict | string | No | fail | Conflict policy: `fail`, `overwrite`, or `skip` |++```+POST /api/v1/pack/restore+Content-Type: application/json+```++```bash+TEMP_FILE_ID=$(+ curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \+ -H "X-API-Key: your-admin-key" \+ -F "file=@./backups/openviking.ovpack" \+ | jq -r '.result.temp_file_id'+)++curl -X POST http://localhost:1933/api/v1/pack/restore \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-admin-key" \+ -d "{\"temp_file_id\":\"$TEMP_FILE_ID\",\"on_conflict\":\"overwrite\"}"+```++CLI:++```bash+ov restore ./backups/openviking.ovpack --on-conflict overwrite+```+---## Related Documentationdiff --git a/docs/en/concepts/01-architecture.md b/docs/en/concepts/01-architecture.mdindex f7e2c0388..ad8ff884d 100644--- a/docs/en/concepts/01-architecture.md+++ b/docs/en/concepts/01-architecture.md@@ -72,7 +72,7 @@ The Service layer decouples business logic from the transport layer, enabling re| **SessionService** | Session management | session, sessions, commit, delete || **ResourceService** | Resource import | add_resource, add_skill, wait_processed || **RelationService** | Relation management | relations, link, unlink |-| **PackService** | Import/export | export_ovpack, import_ovpack |+| **PackService** | Import/export and backup/restore | export_ovpack, import_ovpack, backup_ovpack, restore_ovpack || **DebugService** | Debug service | observer (ObserverService) |## Dual-Layer Storagediff --git a/docs/en/guides/09-ovpack.md b/docs/en/guides/09-ovpack.mdindex 46d97266f..e802e95da 100644--- a/docs/en/guides/09-ovpack.md+++ b/docs/en/guides/09-ovpack.md@@ -39,11 +39,8 @@ Import an `.ovpack` file into OpenViking.# Basic importopenviking import ./exports/my-project.ovpack viking://resources/imported/-# Force overwrite-openviking import ./exports/my-project.ovpack viking://resources/imported/ --force--# Skip vectorization (faster)-openviking import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize+# Explicit conflict policy+openviking import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite```**Python SDK**@@ -57,8 +54,7 @@ async def import_example():imported_uri = await client.import_ovpack(file_path="./exports/my-project.ovpack",parent="viking://resources/imported/",- force=True,- vectorize=True+ on_conflict="overwrite")print(f"Import successful: {imported_uri}")await client.wait_processed()@@ -86,11 +82,83 @@ curl -X POST http://localhost:1933/api/v1/pack/import \-d "{\"temp_file_id\": \"$TEMP_FILE_ID\",\"parent\": \"viking://resources/imported/\",- \"force\": true,- \"vectorize\": true+ \"on_conflict\": \"overwrite\"}"```+## Format Notes++OVPack v2 files are standard ZIP archives. Each package contains an OpenViking+manifest at `<root>/_._ovpack_manifest.json`; this is the ZIP-escaped form of the+hidden filename `.ovpack_manifest.json`.++The manifest records `kind`, `format_version`, the exported root, content+entries, and portable vector scalar metadata. In `entries`, `path` is relative to+the exported root. An empty path (`""`) means the root directory itself, for+example `my-project/`.++Example manifest for a package exported from `viking://resources/demo/`:++```json+{+ "kind": "openviking.ovpack",+ "format_version": 2,+ "root": {+ "name": "demo",+ "uri": "viking://resources/demo",+ "scope": "resources"+ },+ "entries": [+ {+ "path": "",+ "kind": "directory"+ },+ {+ "path": "notes.txt",+ "kind": "file",+ "size": 5,+ "sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"+ }+ ],+ "content_sha256": "b2a6e9582119c7510d68e3446de3e71a486934bf450d68f65596259ed1cf7997",+ "vectors": {}+}+```++For packages with manifest entries, import validates the ZIP file and directory+set, per-file `size`, per-file `sha256`, and top-level `content_sha256` before+writing any resources. Missing, extra, or modified content entries, and missing+or mismatched v2 `content_sha256`, are rejected. This is an integrity check for the package+contents, not a signature or authentication mechanism if both the manifest and+content can be rewritten.++Raw embedding vectors are not exported. Runtime fields such as `created_at`,+`updated_at`, and `active_count` are also not exported; imports rebuild vectors+and runtime state in the target environment. Session packages restore session+files and do not trigger vectorization. Packages without a manifest are rejected+by default because OpenViking cannot verify their file set or content checksums.+Packages with a manifest validate `kind` and `format_version`, and packages+whose format version is not the current supported version are rejected.+`.abstract.md` and `.overview.md` are restored as semantic sidecar files;+`.relations.json` and OVPack internals are excluded.++Manifest scalar `context_type`, when present, is treated as exported scalar+metadata only. Import compatibility is based on the source and target URI scopes;+the final `context_type` is derived again from the target URI during+vectorization.++Top-level scope packages such as `viking://resources/`, `viking://user/`,+`viking://agent/`, and `viking://session/` must be imported to `viking://`.+Regular import also requires the manifest root scope to match the final target+root scope. Structured scopes (`user`, `agent`, and `session`) cannot be imported+in a way that changes the root depth, such as importing a session package into a+concrete session URI and creating `session/sess_123/sess_123`.+Full backups use the separate `backup` / `restore` interface, not regular+import parent semantics.+OVPack itself does not add package-size, file-count, or directory-depth limits;+the practical limit comes from ZIP, the storage backend, and the runtime+environment.+## Memory Import and ExportOpenViking memories are stored under fixed directory structures:@@ -107,7 +175,7 @@ When migrating memories with OVPack, you must import the `.ovpack` into the pareopenviking export viking://user/default/memories/ ./exports/user-memories.ovpack# Import into the user space root (imports to viking://user/default/memories/)-openviking import ./exports/user-memories.ovpack viking://user/default/ --force+openviking import ./exports/user-memories.ovpack viking://user/default/ --on-conflict overwrite```### Export/Import Agent Memories (CLI)@@ -115,11 +183,11 @@ openviking import ./exports/user-memories.ovpack viking://user/default/ --force```bash# isolate_agent_scope_by_user = falseopenviking export viking://agent/default/memories/ ./exports/agent-memories.ovpack-openviking import ./exports/agent-memories.ovpack viking://agent/default/ --force+openviking import ./exports/agent-memories.ovpack viking://agent/default/ --on-conflict overwrite# isolate_agent_scope_by_user = trueopenviking export viking://agent/default/user/alice/memories/ ./exports/agent-memories.ovpack-openviking import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --force+openviking import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --on-conflict overwrite```### Export/Import Memories (Python SDK)@@ -139,8 +207,7 @@ async def export_import_user_memories():await client.import_ovpack(file_path="./exports/user-memories.ovpack",parent="viking://user/default/",- force=True,- vectorize=True,+ on_conflict="overwrite",)finally:await client.close()@@ -156,8 +223,7 @@ async def export_import_agent_memories():await client.import_ovpack(file_path="./exports/agent-memories.ovpack",parent="viking://agent/default/",- force=True,- vectorize=True,+ on_conflict="overwrite",)finally:await client.close()@@ -188,22 +254,51 @@ curl -X POST http://localhost:1933/api/v1/pack/import \-d "{\"temp_file_id\": \"$TEMP_FILE_ID\",\"parent\": \"viking://user/default/\",- \"force\": true,- \"vectorize\": true+ \"on_conflict\": \"overwrite\"}"```### Vectorization on Import-- Vectorization is enabled by default (useful for `find/search`).-- For faster restore, you can disable it and process later with `--no-vectorize`:+Imports always rebuild vectors in the target environment for `find/search`.+OVPack no longer exposes an import option to disable vectorization. Session+imports are restored as files only and are not vectorized.++### Session Import and Export```bash-openviking import ./exports/user-memories.ovpack viking://user/default/ --force --no-vectorize+openviking export viking://session/sess_123/ ./exports/sess_123.ovpack+openviking import ./exports/sess_123.ovpack viking://session/ --on-conflict overwrite```+The restored root is `viking://session/sess_123/`.++### Scope Root Import++```bash+openviking export viking://resources/ ./backups/resources.ovpack+openviking import ./backups/resources.ovpack viking:// --on-conflict overwrite+```++Scope-root packages cannot be imported under another scope directory.+## Use Cases+### Full Backup and Migration++Use a backup package for full migration instead of regular `export/import`+parent-directory semantics:++```bash+openviking backup ./backups/openviking.ovpack+openviking restore ./backups/openviking.ovpack --on-conflict overwrite+```++Backup packages restore to the original public scope roots: `resources`, `user`,+`agent`, and `session`. They exclude internal/runtime data such as `temp`,+`queue`, lock files, OVPack manifests, and `.relations.json`. Non-session+content is re-vectorized; session files are only restored.+### Resource Backup```bashDATE=$(date +%Y%m%d)@@ -216,7 +311,7 @@ openviking export viking://resources/ ./backups/backup_${DATE}.ovpackopenviking export viking://resources/my-project/ ./migration.ovpack# Import on Machine B-openviking import ./migration.ovpack viking://resources/ --force+openviking import ./migration.ovpack viking://resources/ --on-conflict overwrite```### Resource Sharing@@ -234,7 +329,7 @@ openviking import ./shared-docs.ovpack viking://resources/team-shared/A: Yes! OVPack is a standard ZIP format and can be opened with any compression tool.**Q: What if large OVPack imports are slow?**-A: Use `--no-vectorize` for fast import, then vectorize later.+A: Imports now always rebuild vectors. If import time is too high, split the content into smaller OVPack files and import them in batches.**Q: How to handle duplicate resources during import?**-A: Use `--force` to overwrite existing resources.+A: Use `--on-conflict overwrite` to replace existing resources, or `--on-conflict skip` to keep them.diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex 554244cb9..a59a1b942 100644--- a/docs/zh/api/01-overview.md+++ b/docs/zh/api/01-overview.md@@ -363,6 +363,8 @@ JSON 输出 - 错误:|------|------|------|------|| POST | `/api/v1/pack/export` | 导出 .ovpack 文件 | ROOT/ADMIN || POST | `/api/v1/pack/import` | 导入 .ovpack 文件 | ROOT/ADMIN |+| POST | `/api/v1/pack/backup` | 备份公开 scope | ROOT/ADMIN |+| POST | `/api/v1/pack/restore` | 恢复备份包 | ROOT/ADMIN |### 文件系统端点diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.mdindex 6dd230d34..2922095da 100644--- a/docs/zh/api/03-filesystem.md+++ b/docs/zh/api/03-filesystem.md@@ -986,8 +986,16 @@ openviking unlink viking://resources/docs/auth/ viking://resources/docs/security**处理流程**:1. 验证用户权限2. 遍历指定 URI 下的资源-3. 打包成 zip 格式(.ovpack)-4. 以文件流形式返回+3. 写入内容文件和 OVPack manifest+4. 打包成 zip 格式(.ovpack)+5. 以文件流形式返回++**格式说明**:+- 导出的 ZIP 会包含 `<root>/_._ovpack_manifest.json`,这是 `.ovpack_manifest.json` 在 ZIP 内的转义名称。+- `entries[].path` 是相对导出 root 的路径;`""` 表示 root 目录本身。+- 文件条目包含 `size` 和 `sha256`;`content_sha256` 覆盖按路径排序后的文件列表(`path`、`size`、`sha256`)。+- 原始 embedding 向量以及 `created_at`、`updated_at`、`active_count` 等运行态字段不会被导出。+- OVPack 不额外设置包大小、文件数量或目录深度上限;实际可处理规模由 ZIP、存储后端和运行环境决定。**代码入口**:- `openviking/server/routers/pack.py:export_ovpack` - HTTP 路由@@ -1059,8 +1067,9 @@ ov export viking://resources/my-project/ ./exports/my-project.ovpack**处理流程**:1. 验证用户权限2. 解析上传的 `.ovpack` 文件-3. 导入资源到目标位置-4. 可选地触发向量化+3. 校验 manifest 元数据、路径、文件和目录集合、文件大小和 checksum+4. 应用 `on_conflict`+5. 导入资源到目标位置,并重建向量**代码入口**:- `openviking/server/routers/pack.py:import_ovpack` - HTTP 路由@@ -1075,11 +1084,23 @@ ov export viking://resources/my-project/ ./exports/my-project.ovpack|------|------|------|--------|------|| temp_file_id | string | 是 | - | 临时上传文件 ID(通过 [temp_upload](02-resources.md#temp_upload) 获取) || parent | string | 是 | - | 目标父级 URI(导入到此处) |-| force | bool | 否 | False | 是否覆盖已有资源 |-| vectorize | bool | 否 | True | 是否触发向量化 |+| on_conflict | string | 否 | fail | 冲突策略:`fail`、`overwrite` 或 `skip` |**权限要求**:ROOT 或 ADMIN+**行为说明**:+- 导入后总是在目标环境重建向量。API 已不再接受 `vectorize` 或 `force`。+- Session 导入只恢复 session 文件状态,不触发向量化。+- `on_conflict=fail` 且目标 root 已存在时,会返回结构化的 `409 CONFLICT`。+- `on_conflict=overwrite` 会替换已有目标 root。`on_conflict=skip` 会保留已有目标 root,并直接返回该路径,不写入包内容。`skip` 是 root 级跳过,不是文件级补齐。+- 默认拒绝没有 manifest 的包,因为这类包无法提供内容完整性校验。+- 带 manifest entries 的包如果缺少内容文件或目录、混入额外文件或目录、文件大小不同、单文件 `sha256` 不同,或整体 `content_sha256` 缺失/不匹配,都会被拒绝导入。+- manifest `format_version` 不是当前支持版本的包会被拒绝。+- `.abstract.md` 和 `.overview.md` 会作为语义侧边文件恢复;`.relations.json` 和 OVPack 内部文件会被排除。+- manifest `context_type` 必须和最终导入路径语义一致。+- `viking://resources/` 这类顶级 scope 包必须导入到 `viking://`。+- OVPack 不额外设置导入包大小、文件数量或目录深度上限;实际可处理规模由 ZIP、存储后端和运行环境决定。+#### 3. 使用示例**HTTP API**@@ -1105,8 +1126,7 @@ curl -X POST http://localhost:1933/api/v1/pack/import \-d "{\"temp_file_id\": \"$TEMP_FILE_ID\",\"parent\": \"viking://resources/imported/\",- \"force\": true,- \"vectorize\": true+ \"on_conflict\": \"overwrite\"}"```@@ -1128,11 +1148,8 @@ client.initialize()# 导入 .ovpack 文件ov import ./exports/my-project.ovpack viking://resources/imported/-# 强制覆盖已有内容-ov import ./exports/my-project.ovpack viking://resources/imported/ --force--# 不进行向量化-ov import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize+# 显式冲突策略+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite```**响应示例**@@ -1149,6 +1166,81 @@ ov import ./exports/my-project.ovpack viking://resources/imported/ --no-vectoriz}```+**冲突错误示例**++```json+{+ "status": "error",+ "error": {+ "code": "CONFLICT",+ "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",+ "details": {+ "resource": "viking://resources/imported/my-project"+ }+ }+}+```++---++### backup_ovpack++将公开 scope root 备份为只能通过 restore 恢复的 `.ovpack` 文件。备份包含+`resources`、`user`、`agent`、`session`,不包含 `temp`、`queue` 等内部运行态数据。++```+POST /api/v1/pack/backup+```++```bash+curl -X POST http://localhost:1933/api/v1/pack/backup \+ -H "X-API-Key: your-admin-key" \+ --output openviking-backup.ovpack+```++CLI:++```bash+ov backup ./backups/openviking.ovpack+```++---++### restore_ovpack++恢复 `backup_ovpack` 生成的备份包到原始公开 scope root。普通 import 不接受备份包。+非 session 内容恢复后重新向量化;session 只恢复文件状态。++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| temp_file_id | string | 是 | - | 临时上传文件 ID |+| on_conflict | string | 否 | fail | 冲突策略:`fail`、`overwrite` 或 `skip` |++```+POST /api/v1/pack/restore+Content-Type: application/json+```++```bash+TEMP_FILE_ID=$(+ curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \+ -H "X-API-Key: your-admin-key" \+ -F "file=@./backups/openviking.ovpack" \+ | jq -r '.result.temp_file_id'+)++curl -X POST http://localhost:1933/api/v1/pack/restore \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-admin-key" \+ -d "{\"temp_file_id\":\"$TEMP_FILE_ID\",\"on_conflict\":\"overwrite\"}"+```++CLI:++```bash+ov restore ./backups/openviking.ovpack --on-conflict overwrite+```+---## 相关文档diff --git a/docs/zh/concepts/01-architecture.md b/docs/zh/concepts/01-architecture.mdindex a2e95ac39..ea569c8d5 100644--- a/docs/zh/concepts/01-architecture.md+++ b/docs/zh/concepts/01-architecture.md@@ -71,7 +71,7 @@ Service 层将业务逻辑与传输层解耦,便于 HTTP Server 和 CLI 复用| **SessionService** | 会话管理 | session, sessions, commit, delete || **ResourceService** | 资源导入 | add_resource, add_skill, wait_processed || **RelationService** | 关联管理 | relations, link, unlink |-| **PackService** | 导入导出 | export_ovpack, import_ovpack |+| **PackService** | 导入导出、备份恢复 | export_ovpack, import_ovpack, backup_ovpack, restore_ovpack || **DebugService** | 调试服务 | observer (ObserverService) |## 双层存储diff --git a/docs/zh/guides/09-ovpack.md b/docs/zh/guides/09-ovpack.mdindex a6e798fc6..f516e9311 100644--- a/docs/zh/guides/09-ovpack.md+++ b/docs/zh/guides/09-ovpack.md@@ -1,251 +1,394 @@# OVPack 导入导出-OVPack 是 OpenViking 的打包格式,用于导出/导入任意上下文子树(例如资源、记忆),以便备份、迁移和分享。+OVPack 是 OpenViking 的上下文打包格式,用来把一个 `viking://` 子树导出成+`.ovpack` 文件,再导入到另一个 OpenViking 环境。它适合备份、迁移、分享资源或记忆+目录;它不是长期归档格式,也不是带签名的安全发布格式。-## 快速开始+## 适用边界-### 导出资源+OVPack 可以处理这些公开作用域:-将 OpenViking 中的资源导出为 `.ovpack` 文件。+- `viking://resources/...`+- `viking://user/...`+- `viking://agent/...`+- `viking://session/...`-**CLI**-```bash-openviking export viking://resources/my-project/ ./exports/my-project.ovpack-```+OVPack 支持导出公开 scope root,例如 `viking://resources/`、`viking://user/`、+`viking://agent/`、`viking://session/`;这类顶级 scope 包只能导入到 `viking://`。+全量备份使用单独的 `backup` / `restore` 接口,自动包含这些公开 scope root。+`temp`、`queue` 等内部作用域不属于 OVPack 迁移范围。-**Python SDK**-```python-from openviking import AsyncOpenViking+`.abstract.md` 和 `.overview.md` 会作为语义侧边文件随包恢复;`.relations.json`、锁文件、+manifest 等内部文件不会进入包。导入后 OpenViking 会在目标环境重新生成语义和向量;session+包只恢复 session 文件状态,不触发向量化。导入接口不再提供 `vectorize` 或 `force` 参数;+冲突处理统一使用 `on_conflict`。OVPack 本身不再设置额外的包大小、文件数量或目录深度上限;+实际可处理规模由 ZIP、存储后端和运行环境决定。-async def export_example():- client = AsyncOpenViking()- await client.initialize()- try:- exported_path = await client.export_ovpack(- uri="viking://resources/my-project/",- to="./exports/my-project.ovpack"- )- print(f"导出成功: {exported_path}")- finally:- await client.close()-```+## 快速开始++### CLI-**HTTP API**```bash-curl -X POST http://localhost:1933/api/v1/pack/export \- -H "Content-Type: application/json" \- -H "X-API-Key: your-key" \- -d '{- "uri": "viking://resources/my-project/",- "to": "./exports/my-project.ovpack"- }'-```+# 导出资源目录+ov export viking://resources/my-project/ ./exports/my-project.ovpack++# 导入到目标父目录+ov import ./exports/my-project.ovpack viking://resources/imported/-### 导入资源+# 目标 root 已存在时覆盖+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite+```-将 `.ovpack` 文件导入到 OpenViking 中。+导入的第二个参数是“父目录”,不是最终 root。假设包内 root 名是 `my-project`:-**CLI**-```bash-# 基本导入-openviking import ./exports/my-project.ovpack viking://resources/imported/+```text+ov import ./exports/my-project.ovpack viking://resources/imported/+```-# 强制覆盖-openviking import ./exports/my-project.ovpack viking://resources/imported/ --force+导入结果是:-# 跳过向量化(更快)-openviking import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize+```text+viking://resources/imported/my-project```-**Python SDK**+### Python SDK+```pythonfrom openviking import AsyncOpenViking-async def import_example():++async def export_and_import():client = AsyncOpenViking()await client.initialize()try:+ await client.export_ovpack(+ uri="viking://resources/my-project/",+ to="./exports/my-project.ovpack",+ )+imported_uri = await client.import_ovpack(file_path="./exports/my-project.ovpack",parent="viking://resources/imported/",- force=True,- vectorize=True+ on_conflict="overwrite",)- print(f"导入成功: {imported_uri}")+ print(imported_uri)++ # 导入会触发目标环境重新向量化;需要检索前可等待后台任务完成。await client.wait_processed()finally:await client.close()```-**HTTP API**+### HTTP API++HTTP 导出接口直接返回文件流;HTTP 导入必须先上传本地 `.ovpack` 文件,再用+`temp_file_id` 导入。++```bash+# 导出+curl -X POST http://localhost:1933/api/v1/pack/export \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-admin-key" \+ -d '{"uri": "viking://resources/my-project/"}' \+ --output my-project.ovpack+```+```bash# 第一步:上传本地 ovpack 文件-# 默认使用本地临时存储。-# 只有在明确需要分布式共享临时上传时,才额外传:-F "upload_mode=shared"-# Python HTTP client / CLI 也可以改为在 ovcli.conf 中设置:upload.mode = "shared"TEMP_FILE_ID=$(curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \- -H "X-API-Key: your-key" \- -F 'file=@./exports/my-project.ovpack' \- | jq -r '.result.temp_file_id'+ -H "X-API-Key: your-admin-key" \+ -F "file=@./exports/my-project.ovpack" \+ | jq -r ".result.temp_file_id")-# 第二步:使用 temp_file_id 导入+# 第二步:导入curl -X POST http://localhost:1933/api/v1/pack/import \-H "Content-Type: application/json" \- -H "X-API-Key: your-key" \+ -H "X-API-Key: your-admin-key" \-d "{\"temp_file_id\": \"$TEMP_FILE_ID\",\"parent\": \"viking://resources/imported/\",- \"force\": true,- \"vectorize\": true+ \"on_conflict\": \"overwrite\"}"```-## 记忆导入导出+HTTP 接口不接受本机路径字段,例如 `file_path`、`temp_path`。本地文件读取和上传由 CLI 或+SDK 客户端完成,服务端只消费 `temp_file_id`。++## 冲突策略++`on_conflict` 只在导入 root 已存在时生效。++| 值 | 行为 |+| --- | --- |+| `fail` | 默认值。目标 root 已存在时返回 `409 CONFLICT`。 |+| `overwrite` | 删除已有 root,再写入包内容。 |+| `skip` | 保留已有 root,直接返回该 URI,不写入包内容。 |++`skip` 是 root 级跳过,不是文件级补齐导入:只要目标 root 已存在,就不会写入包内缺失文件。++示例错误:++```json+{+ "status": "error",+ "error": {+ "code": "CONFLICT",+ "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",+ "details": {+ "resource": "viking://resources/imported/my-project"+ }+ }+}+```++## 包结构++OVPack v2 是标准 ZIP 文件。ZIP 内部以一个 root 目录包住所有内容,并包含一个 manifest:++```text+my-project/+my-project/notes.txt+my-project/_._overview.md+my-project/_._ovpack_manifest.json+```++`_._ovpack_manifest.json` 是 `.ovpack_manifest.json` 在 ZIP 内的转义名称。OpenViking 会把+普通内容里的点文件名也按同一规则转义,例如 `.overview.md` 在 ZIP 内是 `_._overview.md`。++一个最小 manifest 示例:++```json+{+ "kind": "openviking.ovpack",+ "format_version": 2,+ "root": {+ "name": "my-project",+ "uri": "viking://resources/my-project",+ "scope": "resources"+ },+ "entries": [+ {+ "path": "",+ "kind": "directory"+ },+ {+ "path": "notes.txt",+ "kind": "file",+ "size": 5,+ "sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"+ }+ ],+ "content_sha256": "b2a6e9582119c7510d68e3446de3e71a486934bf450d68f65596259ed1cf7997",+ "vectors": {+ "": [+ {+ "level": 0,+ "text": "Project summary",+ "scalars": {+ "context_type": "resource",+ "level": 0,+ "abstract": "Project summary"+ }+ }+ ]+ }+}+```++字段说明:++- `kind` 固定为 `openviking.ovpack`。+- `format_version` 当前为 `2`。低于或高于当前支持版本的包都会被拒绝。+- `root.name` 是导入时创建的 root 名称。+- `entries[].path` 是相对 root 的路径。`""` 表示 root 目录本身。+- 文件条目包含 `size` 和 `sha256`。+- `content_sha256` 覆盖按路径排序后的文件列表,元素只包含 `path`、`size`、`sha256`。+- `vectors` 只保存可迁移的标量和目录摘要文本,不保存原始 embedding 向量。+- 包内如果带有 `context_type`,只作为导出时的标量信息;导入校验不依赖它,最终+ `context_type` 以目标路径推导结果为准。++当前会导出的向量标量字段是:++```text+type, context_type, level, name, description, tags, abstract+```++这些运行态字段不会导出,会在目标环境重新生成:++```text+created_at, updated_at, active_count+```++## 导入校验-OpenViking 的记忆会写入固定的目录结构中:+导入会先校验包,再写入目标目录。核心规则如下:-- 用户记忆:`viking://user/{user_space}/memories/`-- Agent 记忆:`viking://agent/{agent_id}/memories/` 或 `viking://agent/{agent_id}/user/{user_id}/memories/`+1. ZIP 路径必须在同一个 root 下,不能包含绝对路径、反斜杠、盘符或 `..`。+2. 必须存在 `<root>/_._ovpack_manifest.json`。+3. manifest 必须是合法 JSON,`kind` 和 `format_version` 必须可识别。+4. `entries` 中声明的文件和目录集合必须和 ZIP 内容一致。+5. 每个文件的 `size` 和 `sha256` 必须匹配实际内容。+6. v2 包必须带 `content_sha256`,并且整体 checksum 必须匹配。+7. manifest root 的 source scope 必须和最终导入 root 的 target scope 一致。+8. `user`、`agent`、`session` 这类结构化 scope 不能通过导入改变 root 层级。+9. `.relations.json`、manifest、锁文件等内部文件不会作为普通内容导入。-使用 OVPack 迁移记忆时,必须把 `.ovpack` 导入到对应 space 的父目录(而不是随便一个目录),否则会变成例如 `.../memories/memories/...` 的路径,OpenViking 将无法按“记忆”语义访问和使用这些文件。+如果旧包没有 manifest,会被拒绝:-### 导出/导入用户记忆(CLI)+```text+INVALID_ARGUMENT: Missing ovpack manifest+```++如果内容被改动,例如 manifest 里声明 `notes.txt` 的 sha256 是 `hello`,但 ZIP 里实际内容+变成 `jello`,会被拒绝:++```text+INVALID_ARGUMENT: ovpack file sha256 does not match manifest+```++这个校验保证的是“包内容没有偏离 manifest”。如果攻击者能同时改 manifest 和文件内容,+它不能替代签名、可信发布链或访问控制。++如果包从 `viking://session/sess_123` 导出,却导入到 `viking://resources/`,会因为+source scope 和 target scope 不一致被拒绝。导入到 `viking://session/sess_123/` 也会+被拒绝,因为它会生成 `viking://session/sess_123/sess_123` 这种嵌套 root。++## 旧包和未来版本++默认导入只接受带 manifest 的 OVPack。旧版无 manifest 包没有文件集合和 checksum 信息,+无法判断是否混入或删改内容,因此默认拒绝。需要迁移旧包时,应先在可信环境中用旧版本导入,+再用当前版本重新导出。++开发期间生成过的 v2 预览包如果缺少 `content_sha256`,也会被拒绝。处理方式同样是重新导出。++如果 manifest 的 `format_version` 不是当前支持版本,会返回不支持的版本错误。低版本不会自动+兼容;处理方式是在可信环境中重新导出为当前支持格式。未来版本包则应升级 OpenViking,或由+支持该版本的环境重新导出成当前支持的格式。++## 记忆迁移++记忆目录有固定结构。导入时要把包导入到“对应目录的父目录”,避免产生重复路径。++### 用户记忆```bash-# 导出:整个用户 memories 子树-openviking export viking://user/default/memories/ ./exports/user-memories.ovpack+# 导出整个用户 memories 子树+ov export viking://user/default/memories/ ./exports/user-memories.ovpack++# 导入到 user space 根目录,结果是 viking://user/default/memories/+ov import ./exports/user-memories.ovpack viking://user/default/ --on-conflict overwrite+```-# 导入:注意 parent 需要是 user space 根目录(导入后会生成 viking://user/default/memories/)-openviking import ./exports/user-memories.ovpack viking://user/default/ --force+不要导入到 `viking://user/default/memories/`,否则会得到:++```text+viking://user/default/memories/memories```-### 导出/导入 Agent 记忆(CLI)+### Agent 记忆```bash# isolate_agent_scope_by_user = false-openviking export viking://agent/default/memories/ ./exports/agent-memories.ovpack-openviking import ./exports/agent-memories.ovpack viking://agent/default/ --force+ov export viking://agent/default/memories/ ./exports/agent-memories.ovpack+ov import ./exports/agent-memories.ovpack viking://agent/default/ --on-conflict overwrite# isolate_agent_scope_by_user = true-openviking export viking://agent/default/user/alice/memories/ ./exports/agent-memories.ovpack-openviking import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --force+ov export viking://agent/default/user/alice/memories/ ./exports/agent-memories.ovpack+ov import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --on-conflict overwrite```-### 导出/导入记忆(Python SDK)+## Session 迁移-```python-from openviking import AsyncOpenViking+Session 包按备份恢复语义处理:恢复原 session id,不进行向量化。-async def export_import_user_memories():- client = AsyncOpenViking()- await client.initialize()- try:- await client.export_ovpack(- uri="viking://user/default/memories/",- to="./exports/user-memories.ovpack",- )+```bash+ov export viking://session/sess_123/ ./exports/sess_123.ovpack+ov import ./exports/sess_123.ovpack viking://session/ --on-conflict overwrite+```- await client.import_ovpack(- file_path="./exports/user-memories.ovpack",- parent="viking://user/default/",- force=True,- vectorize=True,- )- finally:- await client.close()+导入结果是:-async def export_import_agent_memories():- client = AsyncOpenViking()- await client.initialize()- try:- await client.export_ovpack(- uri="viking://agent/default/memories/",- to="./exports/agent-memories.ovpack",- )- await client.import_ovpack(- file_path="./exports/agent-memories.ovpack",- parent="viking://agent/default/",- force=True,- vectorize=True,- )- finally:- await client.close()+```text+viking://session/sess_123/```-### 导出/导入记忆(HTTP API)+如果导出整个 session scope:```bash-# 导出用户记忆-curl -X POST http://localhost:1933/api/v1/pack/export \- -H "Content-Type: application/json" \- -H "X-API-Key: your-key" \- -d '{- "uri": "viking://user/default/memories/",- "to": "./exports/user-memories.ovpack"- }'--# 导入用户记忆(先上传,再用 temp_file_id 导入)-TEMP_FILE_ID=$(- curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \- -H "X-API-Key: your-key" \- -F 'file=@./exports/user-memories.ovpack' \- | jq -r '.result.temp_file_id'-)-curl -X POST http://localhost:1933/api/v1/pack/import \- -H "Content-Type: application/json" \- -H "X-API-Key: your-key" \- -d "{- \"temp_file_id\": \"$TEMP_FILE_ID\",- \"parent\": \"viking://user/default/\",- \"force\": true,- \"vectorize\": true- }"+ov export viking://session/ ./exports/session.ovpack+ov import ./exports/session.ovpack viking:// --on-conflict overwrite```-### 导入后是否向量化+## 常见场景-- 默认会向量化(便于 `find/search` 检索)。-- 如果只做快速恢复、稍后再统一处理,可使用 `--no-vectorize`:+### 全量备份和迁移++全量迁移使用专门的备份包,而不是普通 `export/import` 的父目录语义:```bash-openviking import ./exports/user-memories.ovpack viking://user/default/ --force --no-vectorize+ov backup ./backups/openviking.ovpack+ov restore ./backups/openviking.ovpack --on-conflict overwrite```-## 使用场景+备份包恢复到原始公开 scope root:`resources`、`user`、`agent`、`session`。+它不包含 `temp`、`queue`、锁文件、manifest、`.relations.json` 等内部或运行态数据。+非 session 内容恢复后重新向量化;session 只恢复文件状态。++### 备份资源-### 资源备份```bashDATE=$(date +%Y%m%d)-openviking export viking://resources/ ./backups/backup_${DATE}.ovpack+ov export viking://resources/ ./backups/resources_${DATE}.ovpack++# 恢复整个 resources scope 时,父目录必须是 viking://+ov import ./backups/resources_${DATE}.ovpack viking:// --on-conflict overwrite```-### 资源迁移+### 跨环境迁移+```bash-# 机器 A 导出-openviking export viking://resources/my-project/ ./migration.ovpack+# 机器 A+ov export viking://resources/my-project/ ./migration.ovpack-# 机器 B 导入-openviking import ./migration.ovpack viking://resources/ --force+# 机器 B+ov import ./migration.ovpack viking://resources/ --on-conflict overwrite```-### 资源分享-```bash-# 导出-openviking export viking://resources/shared-docs/ ./shared-docs.ovpack+### 分享一组资源-# 接收者导入-openviking import ./shared-docs.ovpack viking://resources/team-shared/+```bash+ov export viking://resources/shared-docs/ ./shared-docs.ovpack+ov import ./shared-docs.ovpack viking://resources/team-shared/```+## 常见错误++| 错误 | 常见原因 | 处理方式 |+| --- | --- | --- |+| `Missing ovpack manifest` | 旧版无 manifest 包 | 在可信环境重新导出。 |+| `Missing ovpack manifest content_sha256` | 开发期 v2 预览包缺少整体 checksum | 重新导出。 |+| `sha256 does not match manifest` | 文件内容和 manifest 不一致 | 丢弃该包,或从可信源重新导出。 |+| `ovpack entries do not match manifest` | ZIP 中缺文件/目录,或混入额外文件/目录 | 丢弃该包,或重新导出。 |+| `source scope does not match target scope` | 将包导入到了不同 scope,例如 session 导入 resources | 导入到同 scope 的父目录。 |+| `source path is incompatible with target path` | 结构化 scope 的导入会改变 root 层级,例如 session 导入具体 session 内部 | 导入到正确的系统父目录。 |+| `Top-level scope ovpack packages must be imported to viking://` | 将 `resources`/`user`/`agent`/`session` 顶级包导入了非根父目录 | 改为导入 `viking://`。 |+| `Unsupported ovpack format_version` | 包格式版本不是当前支持版本 | 升级 OpenViking 或重新导出为当前支持版本。 |+| `Resource already exists` | 目标 root 已存在 | 使用 `--on-conflict overwrite` 或 `--on-conflict skip`。 |+## 常见问题-**Q: OVPack 文件可以手动解压查看吗?**-A: 可以!OVPack 是标准的 ZIP 格式,可以用任何解压工具打开。+**OVPack 可以手动解压查看吗?**++可以。OVPack 是 ZIP 文件,可以用普通解压工具查看。不要手动改包后再导入;修改内容会破坏+manifest 校验。++**大包导入很慢怎么办?**++导入会重建目标环境的语义和向量。大包迁移建议按目录拆成多个 OVPack 分批导入。-**Q: 大体积 OVPack 导入很慢怎么办?**-A: 使用 `--no-vectorize` 先快速导入,之后再统一向量化。+**为什么不兼容旧版无 manifest 包?**-**Q: 导入时如何处理重名资源?**-A: 使用 `--force` 参数覆盖已存在的资源。+旧包没有可验证的文件列表,也没有 checksum。默认兼容会让被删改或混入文件的包直接写入目标+环境,风险高于收益。diff --git a/openviking/async_client.py b/openviking/async_client.pyindex b68514577..61dd4436e 100644--- a/openviking/async_client.py+++ b/openviking/async_client.py@@ -563,8 +563,24 @@ class AsyncOpenViking:await self._ensure_initialized()return await self._client.export_ovpack(uri, to)+ async def backup_ovpack(self, to: str) -> str:+ """+ Back up public OpenViking scopes as a restore-only .ovpack file.++ Args:+ to: Target file path++ Returns:+ Exported backup file path+ """+ await self._ensure_initialized()+ return await self._client.backup_ovpack(to)+async def import_ovpack(- self, file_path: str, parent: str, force: bool = False, vectorize: bool = True+ self,+ file_path: str,+ parent: str,+ on_conflict: Optional[str] = None,) -> str:"""Import local .ovpack file to specified parent path.@@ -572,14 +588,38 @@ class AsyncOpenViking:Args:file_path: Local .ovpack file pathparent: Target parent URI (e.g., viking://user/alice/resources/references/)- force: Whether to force overwrite existing resources (default: False)- vectorize: Whether to trigger vectorization (default: True)+ on_conflict: One of "fail", "overwrite", or "skip"Returns:Imported root resource URI"""await self._ensure_initialized()- return await self._client.import_ovpack(file_path, parent, force=force, vectorize=vectorize)+ return await self._client.import_ovpack(+ file_path,+ parent,+ on_conflict=on_conflict,+ )++ async def restore_ovpack(+ self,+ file_path: str,+ on_conflict: Optional[str] = None,+ ) -> str:+ """+ Restore a backup .ovpack file to its original public scope roots.++ Args:+ file_path: Local backup .ovpack file path+ on_conflict: One of "fail", "overwrite", or "skip"++ Returns:+ Restored root URI+ """+ await self._ensure_initialized()+ return await self._client.restore_ovpack(+ file_path,+ on_conflict=on_conflict,+ )# ============= Debug methods =============diff --git a/openviking/client/local.py b/openviking/client/local.pyindex b080bb26a..9f1e1eac9 100644--- a/openviking/client/local.py+++ b/openviking/client/local.py@@ -553,16 +553,34 @@ class LocalClient(BaseClient):"""Export context as .ovpack file."""return await self._service.pack.export_ovpack(uri, to, ctx=self._ctx)+ async def backup_ovpack(self, to: str) -> str:+ """Back up public scopes as a restore-only .ovpack file."""+ return await self._service.pack.backup_ovpack(to, ctx=self._ctx)+async def import_ovpack(self,file_path: str,parent: str,- force: bool = False,- vectorize: bool = True,+ on_conflict: Optional[str] = None,) -> str:"""Import .ovpack file."""return await self._service.pack.import_ovpack(- file_path, parent, ctx=self._ctx, force=force, vectorize=vectorize+ file_path,+ parent,+ ctx=self._ctx,+ on_conflict=on_conflict,+ )++ async def restore_ovpack(+ self,+ file_path: str,+ on_conflict: Optional[str] = None,+ ) -> str:+ """Restore backup .ovpack file."""+ return await self._service.pack.restore_ovpack(+ file_path,+ ctx=self._ctx,+ on_conflict=on_conflict,)# ============= Debug =============diff --git a/openviking/server/error_mapping.py b/openviking/server/error_mapping.pyindex 505033b42..e9b8079b0 100644--- a/openviking/server/error_mapping.py+++ b/openviking/server/error_mapping.py@@ -391,6 +391,10 @@ def is_invalid_uri_error(exc: Exception) -> bool:)+def _not_found_error(resource: str | None, resource_type: str) -> NotFoundError:+ return NotFoundError(resource or "", resource_type)++def map_exception(exc: Exception,*,@@ -404,7 +408,7 @@ def map_exception(if isinstance(exc, PermissionError):return PermissionDeniedError(str(exc), resource=resource)if isinstance(exc, FileNotFoundError):- return NotFoundError(resource or str(exc), resource_type)+ return _not_found_error(resource, resource_type)if _is_model_api_key_configuration_error(exc):return FailedPreconditionError("Model provider API key is not configured",@@ -422,7 +426,7 @@ def map_exception(return UnavailableError("storage backend", reason=str(exc))if isinstance(exc, AGFSHTTPError):if exc.status_code == 404 or is_not_found_error(exc):- return NotFoundError(resource or str(exc), resource_type)+ return _not_found_error(resource, resource_type)if exc.status_code == 403:return PermissionDeniedError(str(exc), resource=resource)if exc.status_code == 409:@@ -436,7 +440,7 @@ def map_exception(if isinstance(exc, AGFSClientError):message = str(exc)if is_not_found_error(exc):- return NotFoundError(resource or message, resource_type)+ return _not_found_error(resource, resource_type)if is_invalid_uri_error(exc):return InvalidURIError(resource or message, message)lowered = message.lower()@@ -455,7 +459,7 @@ def map_exception(message = str(exc)lowered = message.lower()if is_not_found_error(exc):- return NotFoundError(resource or message, resource_type)+ return _not_found_error(resource, resource_type)if is_invalid_uri_error(exc):return InvalidURIError(resource or message, message)if "permission denied" in lowered or "access denied" in lowered:diff --git a/openviking/server/routers/pack.py b/openviking/server/routers/pack.pyindex 88b26a995..ee0f72f01 100644--- a/openviking/server/routers/pack.py+++ b/openviking/server/routers/pack.py@@ -4,6 +4,7 @@import osimport tempfile+from typing import Literal, Optionalfrom fastapi import APIRouter, Depends, Requestfrom fastapi.responses import FileResponse@@ -13,6 +14,7 @@ from starlette.background import BackgroundTaskfrom openviking.core.path_variables import resolve_path_variablesfrom openviking.server.auth import get_request_context, require_auth_root_or_adminfrom openviking.server.dependencies import get_service+from openviking.server.error_mapping import map_exceptionfrom openviking.server.identity import RequestContextfrom openviking.server.models import Responsefrom openviking.server.temp_upload_store import TempUploadStore@@ -32,16 +34,23 @@ class ImportRequest(BaseModel):Attributes:temp_file_id: Temporary upload id returned by /api/v1/resources/temp_upload.parent: Parent URI under which the imported pack will be placed.- force: Whether to overwrite existing content if needed.- vectorize: Whether to build vectors for imported content.+ on_conflict: Conflict policy: fail, overwrite, or skip."""model_config = ConfigDict(extra="forbid")temp_file_id: strparent: str- force: bool = False- vectorize: bool = True+ on_conflict: Optional[Literal["fail", "overwrite", "skip"]] = None+++class RestoreRequest(BaseModel):+ """Request model for backup restore."""++ model_config = ConfigDict(extra="forbid")++ temp_file_id: str+ on_conflict: Optional[Literal["fail", "overwrite", "skip"]] = None@router.post("/export")@@ -83,10 +92,46 @@ async def export_ovpack(filename=filename,background=BackgroundTask(cleanup),)- except Exception:+ except Exception as exc:# Clean up temp file on errorif os.path.exists(temp_file):os.unlink(temp_file)+ mapped = map_exception(exc, resource=uri, resource_type="resource")+ if mapped is not None:+ raise mapped from exc+ raise++[email protected]("/backup")+@require_auth_root_or_admin+async def backup_ovpack(+ request: Request,+ ctx: RequestContext = Depends(get_request_context),+):+ """Back up all public OpenViking scopes as a restore-only .ovpack file."""+ service = get_service()+ temp_dir = tempfile.gettempdir()+ temp_file = os.path.join(temp_dir, f"backup_{os.urandom(16).hex()}.ovpack")++ try:+ await service.pack.backup_ovpack(temp_file, ctx=ctx)++ def cleanup():+ if os.path.exists(temp_file):+ os.unlink(temp_file)++ return FileResponse(+ path=temp_file,+ media_type="application/zip",+ filename="openviking-backup.ovpack",+ background=BackgroundTask(cleanup),+ )+ except Exception as exc:+ if os.path.exists(temp_file):+ os.unlink(temp_file)+ mapped = map_exception(exc, resource="viking://", resource_type="resource")+ if mapped is not None:+ raise mapped from excraise@@ -110,8 +155,36 @@ async def import_ovpack(resolved.local_path,parent,ctx=ctx,- force=body.force,- vectorize=body.vectorize,+ on_conflict=body.on_conflict,+ )+ except Exception:+ await store.mark_failed(resolved, ctx)+ raise+ else:+ await store.mark_consumed(resolved, ctx)+ finally:+ await resolved.cleanup()++ return Response(status="ok", result={"uri": result})++[email protected]("/restore")+@require_auth_root_or_admin+async def restore_ovpack(+ request: Request,+ body: RestoreRequest,+ ctx: RequestContext = Depends(get_request_context),+):+ """Restore a backup .ovpack file."""+ service = get_service()+ store = TempUploadStore.build(request.app.state.config)+ resolved = await store.resolve_for_consume(body.temp_file_id, ctx)++ try:+ result = await service.pack.restore_ovpack(+ resolved.local_path,+ ctx=ctx,+ on_conflict=body.on_conflict,)except Exception:await store.mark_failed(resolved, ctx)diff --git a/openviking/service/core.py b/openviking/service/core.pyindex 0caab80e6..dd7ccea5c 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -337,7 +337,10 @@ class OpenVikingService:privacy_config_service=self._privacy_config_service,)self._relation_service.set_viking_fs(self._viking_fs)- self._pack_service.set_viking_fs(self._viking_fs)+ self._pack_service.set_dependencies(+ viking_fs=self._viking_fs,+ vector_store=self._vikingdb_manager,+ )self._search_service.set_viking_fs(self._viking_fs)self._resource_service.set_dependencies(vikingdb=self._vikingdb_manager,diff --git a/openviking/service/pack_service.py b/openviking/service/pack_service.pyindex 40969b117..adad20fb8 100644--- a/openviking/service/pack_service.py+++ b/openviking/service/pack_service.py@@ -3,15 +3,17 @@"""Pack Service for OpenViking.-Provides ovpack export/import operations.+Provides ovpack export/import and backup/restore operations."""from typing import Optionalfrom openviking.core.uri_validation import validate_viking_urifrom openviking.server.identity import RequestContext+from openviking.storage.local_fs import backup_ovpack as local_backup_ovpackfrom openviking.storage.local_fs import export_ovpack as local_export_ovpackfrom openviking.storage.local_fs import import_ovpack as local_import_ovpack+from openviking.storage.local_fs import restore_ovpack as local_restore_ovpackfrom openviking.storage.viking_fs import VikingFSfrom openviking_cli.exceptions import NotInitializedErrorfrom openviking_cli.utils import get_logger@@ -20,15 +22,21 @@ logger = get_logger(__name__)class PackService:- """OVPack export/import service."""+ """OVPack export/import and backup/restore service."""- def __init__(self, viking_fs: Optional[VikingFS] = None):+ def __init__(self, viking_fs: Optional[VikingFS] = None, vector_store=None):self._viking_fs = viking_fs+ self._vector_store = vector_storedef set_viking_fs(self, viking_fs: VikingFS) -> None:"""Set VikingFS instance (for deferred initialization)."""self._viking_fs = viking_fs+ def set_dependencies(self, viking_fs: VikingFS, vector_store=None) -> None:+ """Set pack service dependencies."""+ self._viking_fs = viking_fs+ self._vector_store = vector_store+def _ensure_initialized(self) -> VikingFS:"""Ensure VikingFS is initialized."""if not self._viking_fs:@@ -47,23 +55,37 @@ class PackService:"""viking_fs = self._ensure_initialized()uri = validate_viking_uri(uri)- return await local_export_ovpack(viking_fs, uri, to, ctx=ctx)+ return await local_export_ovpack(+ viking_fs,+ uri,+ to,+ ctx=ctx,+ vector_store=self._vector_store,+ )++ async def backup_ovpack(self, to: str, ctx: RequestContext) -> str:+ """Back up all public OpenViking scopes as a restore-only .ovpack file."""+ viking_fs = self._ensure_initialized()+ return await local_backup_ovpack(+ viking_fs,+ to,+ ctx=ctx,+ vector_store=self._vector_store,+ )async def import_ovpack(self,file_path: str,parent: str,ctx: RequestContext,- force: bool = False,- vectorize: bool = True,+ on_conflict: Optional[str] = None,) -> str:"""Import local .ovpack file to specified parent path.Args:file_path: Local .ovpack file pathparent: Target parent URI (e.g., viking://user/alice/resources/references/)- force: Whether to force overwrite existing resources- vectorize: Whether to trigger vectorization+ on_conflict: One of "fail", "overwrite", or "skip"Returns:Imported root resource URI@@ -71,5 +93,24 @@ class PackService:viking_fs = self._ensure_initialized()parent = validate_viking_uri(parent, field_name="parent")return await local_import_ovpack(- viking_fs, file_path, parent, force=force, vectorize=vectorize, ctx=ctx+ viking_fs,+ file_path,+ parent,+ on_conflict=on_conflict,+ ctx=ctx,+ )++ async def restore_ovpack(+ self,+ file_path: str,+ ctx: RequestContext,+ on_conflict: Optional[str] = None,+ ) -> str:+ """Restore a backup .ovpack file to its original public scope roots."""+ viking_fs = self._ensure_initialized()+ return await local_restore_ovpack(+ viking_fs,+ file_path,+ ctx=ctx,+ on_conflict=on_conflict,)diff --git a/openviking/storage/local_fs.py b/openviking/storage/local_fs.pyindex 03457b5cf..0731c5ead 100644--- a/openviking/storage/local_fs.py+++ b/openviking/storage/local_fs.py@@ -1,25 +1,88 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0import asyncio+import hashlibimport jsonimport osimport reimport zipfile+from typing import Any, Optionalfrom openviking.core.namespace import context_type_for_urifrom openviking.resource.watch_storage import is_watch_task_control_urifrom openviking.server.identity import RequestContext+from openviking.storage.expr import Eqfrom openviking.utils.embedding_utils import vectorize_directory_meta, vectorize_file-from openviking_cli.exceptions import InvalidArgumentError, NotFoundError+from openviking_cli.exceptions import ConflictError, InvalidArgumentError, NotFoundErrorfrom openviking_cli.utils.logger import get_loggerfrom openviking_cli.utils.uri import VikingURIlogger = get_logger(__name__)-_DERIVED_FILENAMES = frozenset({".relations.json"})+OVPACK_FORMAT_VERSION = 2+OVPACK_KIND = "openviking.ovpack"+OVPACK_MANIFEST_FILENAME = ".ovpack_manifest.json"+OVPACK_MANIFEST_ZIP_LEAF = "_._ovpack_manifest.json"+OVPACK_ON_CONFLICT_VALUES = frozenset({"fail", "overwrite", "skip"})+OVPACK_BACKUP_NAME = "openviking-backup"+OVPACK_BACKUP_TYPE = "backup"++_PUBLIC_SCOPES = ("resources", "user", "agent", "session")+_IMPORTABLE_SCOPES = frozenset(_PUBLIC_SCOPES)+_STRUCTURED_IMPORT_SCOPES = frozenset({"user", "agent", "session"})+_EXCLUDED_FILENAMES = frozenset({".relations.json", OVPACK_MANIFEST_FILENAME})+_NON_VECTOR_SCOPES = frozenset({"session"})+_PORTABLE_VECTOR_SCALAR_FIELDS = [+ "uri",+ "type",+ "context_type",+ "level",+ "name",+ "description",+ "tags",+ "abstract",+]_UNSAFE_PATH_RE = re.compile(r"(^|[\\/])\.\.($|[\\/])")_DRIVE_RE = re.compile(r"^[A-Za-z]:")+_SHA256_RE = re.compile(r"^[0-9a-fA-F]{64}$")+++def _strip_uri_trailing_slash(uri: str) -> str:+ normalized = VikingURI(uri.strip()).uri+ return normalized if normalized == "viking://" else normalized.rstrip("/")+++def _join_uri(base_uri: str, rel_path: str) -> str:+ base_uri = _strip_uri_trailing_slash(base_uri)+ if base_uri == "viking://":+ return f"viking://{rel_path}" if rel_path else base_uri+ return f"{base_uri}/{rel_path}" if rel_path else base_uri+++def _rel_path_for_uri(root_uri: str, uri: str) -> str:+ root_uri = _strip_uri_trailing_slash(root_uri)+ uri = _strip_uri_trailing_slash(uri)+ if uri == root_uri:+ return ""+ prefix = f"{root_uri}/"+ return uri[len(prefix) :] if uri.startswith(prefix) else ""+++def _leaf_name(uri_or_path: str) -> str:+ return uri_or_path.rstrip("/").split("/")[-1]+++def _sha256_hex(data: bytes) -> str:+ return hashlib.sha256(data).hexdigest()+++def _is_excluded_rel_path(rel_path: str) -> bool:+ return _leaf_name(rel_path) in _EXCLUDED_FILENAMES+++def _is_manifest_zip_path(zip_path: str, base_name: str) -> bool:+ return zip_path == f"{base_name}/{OVPACK_MANIFEST_ZIP_LEAF}"def _validate_ovpack_member_path(zip_path: str, base_name: str) -> str:@@ -59,98 +122,780 @@ def ensure_dir_exists(path: str) -> None:def get_ovpack_zip_path(base_name: str, rel_path: str) -> str:- """Generate ZIP internal path from relative path, converting components starting with . to _._"""+ """Generate ZIP internal path from a Viking relative path."""+ if not rel_path:+ return f"{base_name}/"parts = rel_path.split("/")- new_parts = []- for p in parts:- if p.startswith("."):- new_parts.append("_._" + p[1:])- else:- new_parts.append(p)- return f"{base_name}/{'/'.join(new_parts)}"+ escaped = [("_._" + part[1:]) if part.startswith(".") else part for part in parts]+ return f"{base_name}/{'/'.join(escaped)}"def get_viking_rel_path_from_zip(zip_path: str) -> str:- """Restore Viking relative path from ZIP path, converting components starting with _._ back to ."""- # Remove root directory prefix (base_name/)+ """Restore Viking relative path from ZIP path."""parts = zip_path.split("/")if len(parts) <= 1:return ""- # Remove first element (base_name)rel_parts = parts[1:]- new_parts = []- for p in rel_parts:- if p.startswith("_._"):- new_parts.append("." + p[3:])- else:- new_parts.append(p)+ restored = [("." + part[3:]) if part.startswith("_._") else part for part in rel_parts]+ return "/".join(restored)- return "/".join(new_parts)++def _validate_public_scope(uri: str, *, operation: str, allow_root: bool = False) -> None:+ parsed = VikingURI(uri)+ if parsed.uri == "viking://":+ if allow_root:+ return+ raise InvalidArgumentError(f"ovpack {operation} is not supported for root URI")+ if parsed.scope not in _IMPORTABLE_SCOPES:+ raise InvalidArgumentError(f"ovpack {operation} is not supported for scope: {parsed.scope}")def _validate_import_target_uri(uri: str) -> None:"""Enforce the same target-policy boundary as direct content writes."""- parsed = VikingURI(uri)- if parsed.scope not in {"resources", "user", "agent"}:- raise InvalidArgumentError(f"ovpack import is not supported for scope: {parsed.scope}")-- name = uri.rstrip("/").split("/")[-1]- if name in _DERIVED_FILENAMES:- raise InvalidArgumentError(f"cannot import derived semantic file: {uri}")+ _validate_public_scope(uri, operation="import")+ name = _leaf_name(uri)+ if name in _EXCLUDED_FILENAMES:+ raise InvalidArgumentError(f"cannot import internal ovpack file: {uri}")if is_watch_task_control_uri(uri):raise InvalidArgumentError(f"cannot import watch task control file: {uri}")-async def _enqueue_direct_vectorization(viking_fs, uri: str, ctx: RequestContext) -> None:- entries = await viking_fs.tree(uri, node_limit=100000, level_limit=1000, ctx=ctx)+def _validate_export_source_uri(uri: str) -> None:+ _validate_public_scope(uri, operation="export")+ name = _leaf_name(uri)+ if name in _EXCLUDED_FILENAMES:+ raise InvalidArgumentError(f"cannot export internal ovpack file: {uri}")+ if is_watch_task_control_uri(uri):+ raise InvalidArgumentError(f"cannot export watch task control file: {uri}")+++def _base_name_from_entries(infolist: list[zipfile.ZipInfo]) -> str:+ for info in infolist:+ filename = info.filename+ if filename:+ base_name = filename.replace("\\", "/").split("/")[0]+ if base_name:+ return base_name+ raise ValueError("Could not determine root directory name from ovpack")+++def _normalize_on_conflict(on_conflict: Optional[str]) -> str:+ if on_conflict is None:+ return "fail"+ if on_conflict not in OVPACK_ON_CONFLICT_VALUES:+ allowed = ", ".join(sorted(OVPACK_ON_CONFLICT_VALUES))+ raise InvalidArgumentError(+ f"Invalid on_conflict value: {on_conflict}. Must be one of: {allowed}"+ )+ return on_conflict+++def _portable_scalars(record: dict[str, Any]) -> dict[str, Any]:+ return {+ field: record[field]+ for field in _PORTABLE_VECTOR_SCALAR_FIELDS+ if field != "uri" and record.get(field) is not None+ }+++def _record_level(record: dict[str, Any], default: int = 2) -> int:+ try:+ return int(record.get("level", default))+ except (TypeError, ValueError):+ return default+++async def _call_vector_filter(vector_store, uri: str, ctx: RequestContext) -> list[dict[str, Any]]:+ if not vector_store or not hasattr(vector_store, "filter"):+ return []++ kwargs = {+ "filter": Eq("uri", uri),+ "limit": 10,+ "output_fields": _PORTABLE_VECTOR_SCALAR_FIELDS,+ }+ try:+ return await vector_store.filter(**kwargs, ctx=ctx)+ except TypeError:+ try:+ return await vector_store.filter(**kwargs)+ except Exception as exc:+ logger.warning(f"Failed to export vector scalars for {uri}: {exc}")+ except Exception as exc:+ logger.warning(f"Failed to export vector scalars for {uri}: {exc}")+ return []+++async def _read_text_if_exists(viking_fs, uri: str, ctx: RequestContext) -> str:+ try:+ if not await viking_fs.exists(uri, ctx=ctx):+ return ""+ content = await viking_fs.read_file(uri, ctx=ctx)+ return content.decode("utf-8") if isinstance(content, bytes) else content+ except Exception:+ return ""+++async def _directory_vector_texts(viking_fs, uri: str, ctx: RequestContext) -> dict[int, str]:+ abstract = await _read_text_if_exists(viking_fs, f"{uri}/.abstract.md", ctx)+ overview = await _read_text_if_exists(viking_fs, f"{uri}/.overview.md", ctx)+ return {0: abstract, 1: overview}+++async def _manifest_vector_records(+ viking_fs,+ vector_store,+ uri: str,+ is_dir: bool,+ ctx: RequestContext,+) -> list[dict[str, Any]]:+ records = await _call_vector_filter(vector_store, uri, ctx)+ records_by_level = {_record_level(record): record for record in records}+ texts = await _directory_vector_texts(viking_fs, uri, ctx) if is_dir else {}++ manifest_records: list[dict[str, Any]] = []+ for level in sorted(records_by_level):+ item = {+ "level": level,+ "scalars": _portable_scalars(records_by_level[level]),+ }+ text = texts.get(level)+ if text:+ item["text"] = text+ manifest_records.append(item)++ if is_dir:+ abstract = texts.get(0, "")+ for level, text in texts.items():+ if text and level not in records_by_level:+ manifest_records.append(+ {+ "level": level,+ "text": text,+ "scalars": {+ "context_type": context_type_for_uri(uri),+ "level": level,+ "abstract": abstract,+ },+ }+ )++ return sorted(manifest_records, key=lambda item: int(item.get("level", 2)))+++async def _build_manifest(+ viking_fs,+ vector_store,+ root_uri: str,+ base_name: str,+ entries: list[dict[str, Any]],+ ctx: RequestContext,+ package_type: Optional[str] = None,+ scopes: Optional[list[str]] = None,+) -> dict[str, Any]:+ manifest_entries = [{"path": "", "kind": "directory"}]+ vectors: dict[str, list[dict[str, Any]]] = {}++ if root_uri != "viking://":+ root_vectors = await _manifest_vector_records(+ viking_fs, vector_store, root_uri, is_dir=True, ctx=ctx+ )+ if root_vectors:+ vectors[""] = root_vectors++ for entry in entries:+ rel_path = entry["rel_path"]+ is_dir = bool(entry.get("isDir"))+ manifest_entries.append(+ {+ "path": rel_path,+ "kind": "directory" if is_dir else "file",+ "size": entry.get("size", 0) if not is_dir else 0,+ }+ )+ records = await _manifest_vector_records(+ viking_fs,+ vector_store,+ _join_uri(root_uri, rel_path),+ is_dir=is_dir,+ ctx=ctx,+ )+ if records:+ vectors[rel_path] = records++ root = {+ "name": base_name,+ "uri": root_uri,+ "scope": "root" if root_uri == "viking://" else VikingURI(root_uri).scope,+ }+ manifest: dict[str, Any] = {+ "kind": OVPACK_KIND,+ "format_version": OVPACK_FORMAT_VERSION,+ "root": root,+ "entries": manifest_entries,+ "vectors": vectors,+ }+ if package_type:+ root["package_type"] = package_type+ if scopes is not None:+ manifest["scopes"] = scopes+ return manifest+++def _invalid_manifest(message: str, manifest_path: str, **details: Any) -> InvalidArgumentError:+ return InvalidArgumentError(+ message,+ details={"manifest_path": manifest_path, **details},+ )+++def _read_manifest(zf: zipfile.ZipFile, base_name: str) -> dict[str, Any]:+ manifest_path = f"{base_name}/{OVPACK_MANIFEST_ZIP_LEAF}"+ try:+ raw = zf.read(manifest_path)+ except KeyError:+ raise _invalid_manifest(+ "Missing ovpack manifest",+ manifest_path,+ hint="Re-export this package with OVPack v2 checksum support before importing.",+ )++ try:+ manifest = json.loads(raw.decode("utf-8"))+ except json.JSONDecodeError as exc:+ raise _invalid_manifest(+ "Invalid JSON in ovpack manifest",+ manifest_path,+ reason=str(exc),+ ) from exc+ if not isinstance(manifest, dict):+ raise _invalid_manifest(+ "Invalid ovpack manifest",+ manifest_path,+ actual_type=type(manifest).__name__,+ )++ version = manifest.get("format_version")+ if version is None:+ raise _invalid_manifest(+ "Missing ovpack format_version",+ manifest_path,+ field="format_version",+ )+ try:+ version_int = int(version)+ except (TypeError, ValueError) as exc:+ raise _invalid_manifest(+ f"Invalid ovpack format_version {version!r}",+ manifest_path,+ field="format_version",+ value=version,+ ) from exc+ if version_int < 1:+ raise _invalid_manifest(+ f"Invalid ovpack format_version {version!r}",+ manifest_path,+ field="format_version",+ value=version,+ )+ if version_int != OVPACK_FORMAT_VERSION:+ raise _invalid_manifest(+ f"Unsupported ovpack format_version {version}; "+ f"this OpenViking requires {OVPACK_FORMAT_VERSION}",+ manifest_path,+ format_version=version_int,+ supported_format_version=OVPACK_FORMAT_VERSION,+ )+ if manifest.get("kind") != OVPACK_KIND:+ raise _invalid_manifest(+ "Invalid ovpack manifest kind",+ manifest_path,+ expected=OVPACK_KIND,+ actual=manifest.get("kind"),+ )+ return manifest+++def _manifest_root_uri(manifest: dict[str, Any]) -> str:+ root = manifest.get("root")+ if not isinstance(root, dict):+ return ""+ uri = root.get("uri")+ if isinstance(uri, str):+ try:+ return _strip_uri_trailing_slash(uri)+ except Exception:+ return uri.rstrip("/")+ return ""+++def _is_backup_package(manifest: dict[str, Any]) -> bool:+ root = manifest.get("root")+ return (+ isinstance(root, dict)+ and root.get("package_type") == OVPACK_BACKUP_TYPE+ and _manifest_root_uri(manifest) == "viking://"+ )+++def _is_top_level_scope_package(base_name: str, manifest: dict[str, Any]) -> bool:+ root_uri = _manifest_root_uri(manifest)+ return base_name in _IMPORTABLE_SCOPES and root_uri == f"viking://{base_name}"+++def _resolve_import_root_uri(parent: str, base_name: str, manifest: dict[str, Any]) -> str:+ if _is_backup_package(manifest):+ raise InvalidArgumentError(+ "Backup ovpack packages must be restored with ov restore or the restore API",+ details={"root": base_name, "parent": parent},+ )++ if parent == "viking://":+ if not _is_top_level_scope_package(base_name, manifest):+ raise InvalidArgumentError(+ "Only top-level scope ovpack packages can be imported to viking://",+ details={"root": base_name},+ )+ return f"viking://{base_name}"++ if _is_top_level_scope_package(base_name, manifest):+ raise InvalidArgumentError(+ "Top-level scope ovpack packages must be imported to viking://",+ details={"root": base_name, "parent": parent},+ )+ return _join_uri(parent, base_name)+++def _parse_import_uri(uri: str, *, field: str) -> VikingURI:+ if not uri:+ raise InvalidArgumentError(f"Missing ovpack {field}")+ try:+ return VikingURI(uri)+ except ValueError as exc:+ raise InvalidArgumentError(f"Invalid ovpack {field}", details={field: uri}) from exc+++def _uri_depth(parsed: VikingURI) -> int:+ return len([part for part in parsed.full_path.split("/") if part])+++def _validate_import_scope_compatibility(manifest: dict[str, Any], target_root_uri: str) -> None:+ source_root_uri = _manifest_root_uri(manifest)+ source = _parse_import_uri(source_root_uri, field="manifest root uri")+ target = _parse_import_uri(target_root_uri, field="target root uri")++ if source.scope not in _IMPORTABLE_SCOPES:+ raise InvalidArgumentError(+ "ovpack import is not supported for source scope",+ details={"source_scope": source.scope},+ )+ if source.scope != target.scope:+ raise InvalidArgumentError(+ "ovpack source scope does not match target scope",+ details={+ "source_scope": source.scope,+ "target_scope": target.scope,+ },+ )+ if source.scope in _STRUCTURED_IMPORT_SCOPES and _uri_depth(source) != _uri_depth(target):+ raise InvalidArgumentError(+ "ovpack source path is incompatible with target path",+ details={"source": source_root_uri, "target": target_root_uri},+ )+++def _manifest_records_by_level(+ manifest: dict[str, Any], rel_path: str+) -> dict[int, dict[str, Any]]:+ vectors = manifest.get("vectors") if isinstance(manifest, dict) else None+ records = vectors.get(rel_path, []) if isinstance(vectors, dict) else []+ if not isinstance(records, list):+ return {}++ by_level: dict[int, dict[str, Any]] = {}+ for record in records:+ if not isinstance(record, dict):+ continue+ try:+ level = int(record.get("level", 2))+ except (TypeError, ValueError):+ continue+ by_level[level] = record+ return by_level+++def _manifest_scalar_overrides(+ manifest: dict[str, Any], rel_path: str+) -> dict[int, dict[str, Any]]:+ overrides: dict[int, dict[str, Any]] = {}+ for level, record in _manifest_records_by_level(manifest, rel_path).items():+ scalars = record.get("scalars")+ if isinstance(scalars, dict):+ overrides[level] = dict(scalars)+ return overrides+++def _normalize_sha256(value: Any, *, field: str, path: str | None = None) -> str:+ if not isinstance(value, str) or not _SHA256_RE.fullmatch(value):+ details = {"field": field}+ if path is not None:+ details["path"] = path+ raise InvalidArgumentError(f"Invalid ovpack manifest {field}", details=details)+ return value.lower()+++def _manifest_entries_by_path(manifest: dict[str, Any]) -> dict[str, dict[str, Any]]:+ if not isinstance(manifest, dict) or "entries" not in manifest:+ return {}++ entries = manifest.get("entries")+ if not isinstance(entries, list):+ raise InvalidArgumentError("Invalid ovpack manifest: entries must be a list")++ by_path: dict[str, dict[str, Any]] = {}+ for index, entry in enumerate(entries):+ if not isinstance(entry, dict):+ raise InvalidArgumentError(+ "Invalid ovpack manifest entry",+ details={"index": index},+ )++ rel_path = entry.get("path")+ kind = entry.get("kind")+ if not isinstance(rel_path, str):+ raise InvalidArgumentError(+ "Invalid ovpack manifest entry path",+ details={"index": index},+ )+ if kind not in {"directory", "file"}:+ raise InvalidArgumentError(+ "Invalid ovpack manifest entry kind",+ details={"path": rel_path, "kind": kind},+ )+ if rel_path in by_path:+ raise InvalidArgumentError(+ "Duplicate ovpack manifest entry",+ details={"path": rel_path},+ )+ by_path[rel_path] = entry++ return by_path+++def _manifest_content_sha256(file_entries_by_path: dict[str, dict[str, Any]]) -> str:+ content_entries: list[dict[str, Any]] = []+ for rel_path, entry in sorted(file_entries_by_path.items()):+ size = entry.get("size")+ if not isinstance(size, int) or isinstance(size, bool) or size < 0:+ raise InvalidArgumentError(+ "Invalid ovpack manifest file size",+ details={"path": rel_path, "size": size},+ )+ content_entries.append(+ {+ "path": rel_path,+ "size": size,+ "sha256": _normalize_sha256(entry.get("sha256"), field="sha256", path=rel_path),+ }+ )++ payload = json.dumps(+ content_entries,+ ensure_ascii=False,+ sort_keys=True,+ separators=(",", ":"),+ ).encode("utf-8")+ return _sha256_hex(payload)+++def _zip_file_members_by_path(+ infolist: list[zipfile.ZipInfo], base_name: str+) -> dict[str, tuple[zipfile.ZipInfo, str]]:+ files: dict[str, tuple[zipfile.ZipInfo, str]] = {}+ for info in infolist:+ zip_path = info.filename+ if not zip_path:+ continue+ safe_zip_path = _validate_ovpack_member_path(zip_path, base_name)+ if _is_manifest_zip_path(safe_zip_path, base_name) or safe_zip_path.endswith("/"):+ continue++ rel_path = get_viking_rel_path_from_zip(safe_zip_path)+ if rel_path in files:+ raise InvalidArgumentError(+ "Duplicate ovpack file entry",+ details={"path": rel_path},+ )+ files[rel_path] = (info, safe_zip_path)+ return files+++def _zip_directory_members_by_path(infolist: list[zipfile.ZipInfo], base_name: str) -> set[str]:+ directories: set[str] = set()+ for info in infolist:+ zip_path = info.filename+ if not zip_path:+ continue+ safe_zip_path = _validate_ovpack_member_path(zip_path, base_name)+ if not safe_zip_path.endswith("/"):+ continue++ rel_path = get_viking_rel_path_from_zip(safe_zip_path.rstrip("/"))+ if rel_path in directories:+ raise InvalidArgumentError(+ "Duplicate ovpack directory entry",+ details={"path": rel_path},+ )+ directories.add(rel_path)+ return directories+++def _validate_manifest_content(+ zf: zipfile.ZipFile,+ manifest: dict[str, Any],+ infolist: list[zipfile.ZipInfo],+ base_name: str,+) -> None:+ if "entries" not in manifest:+ raise InvalidArgumentError(+ "Missing ovpack manifest entries",+ details={"field": "entries"},+ )++ manifest_entries = _manifest_entries_by_path(manifest)+ manifest_files = {+ rel_path: entry+ for rel_path, entry in manifest_entries.items()+ if entry.get("kind") == "file"+ }+ manifest_directories = {+ rel_path for rel_path, entry in manifest_entries.items() if entry.get("kind") == "directory"+ }+ zip_files = _zip_file_members_by_path(infolist, base_name)+ zip_directories = _zip_directory_members_by_path(infolist, base_name)++ missing_files = sorted(set(manifest_files) - set(zip_files))+ unexpected_files = sorted(set(zip_files) - set(manifest_files))+ missing_directories = sorted(manifest_directories - zip_directories)+ unexpected_directories = sorted(zip_directories - manifest_directories)+ if missing_files or unexpected_files or missing_directories or unexpected_directories:+ raise InvalidArgumentError(+ "ovpack entries do not match manifest",+ details={+ "missing_files": missing_files,+ "unexpected_files": unexpected_files,+ "missing_directories": missing_directories,+ "unexpected_directories": unexpected_directories,+ },+ )++ expected_content_sha256 = manifest.get("content_sha256")+ if expected_content_sha256 is None:+ raise InvalidArgumentError(+ "Missing ovpack manifest content_sha256",+ details={"field": "content_sha256"},+ )+ expected_content_sha256 = _normalize_sha256(+ expected_content_sha256,+ field="content_sha256",+ )+ actual_content_sha256 = _manifest_content_sha256(manifest_files)+ if actual_content_sha256 != expected_content_sha256:+ raise InvalidArgumentError(+ "ovpack manifest content_sha256 mismatch",+ details={+ "expected": expected_content_sha256,+ "actual": actual_content_sha256,+ },+ )++ for rel_path, (_, safe_zip_path) in sorted(zip_files.items()):+ entry = manifest_files[rel_path]+ data = zf.read(safe_zip_path)++ expected_size = entry.get("size")+ if expected_size is not None:+ if (+ not isinstance(expected_size, int)+ or isinstance(expected_size, bool)+ or expected_size < 0+ ):+ raise InvalidArgumentError(+ "Invalid ovpack manifest file size",+ details={"path": rel_path, "size": expected_size},+ )+ if len(data) != expected_size:+ raise InvalidArgumentError(+ "ovpack file size does not match manifest",+ details={+ "path": rel_path,+ "expected": expected_size,+ "actual": len(data),+ },+ )++ expected_sha256 = entry.get("sha256")+ if expected_sha256 is not None:+ expected_sha256 = _normalize_sha256(+ expected_sha256,+ field="sha256",+ path=rel_path,+ )+ actual_sha256 = _sha256_hex(data)+ if actual_sha256 != expected_sha256:+ raise InvalidArgumentError(+ "ovpack file sha256 does not match manifest",+ details={+ "path": rel_path,+ "expected": expected_sha256,+ "actual": actual_sha256,+ },+ )+++def _validated_import_members(+ infolist: list[zipfile.ZipInfo], base_name: str, root_uri: str+) -> list[tuple[zipfile.ZipInfo, str, str, str]]:+ members: list[tuple[zipfile.ZipInfo, str, str, str]] = []+ for info in infolist:+ zip_path = info.filename+ if not zip_path:+ continue++ safe_zip_path = _validate_ovpack_member_path(zip_path, base_name)+ if _is_manifest_zip_path(safe_zip_path, base_name):+ members.append((info, safe_zip_path, "manifest", ""))+ continue++ kind = "directory" if safe_zip_path.endswith("/") else "file"+ rel_path = get_viking_rel_path_from_zip(+ safe_zip_path.rstrip("/") if kind == "directory" else safe_zip_path+ )+ if root_uri == "viking://" and rel_path == "":+ members.append((info, safe_zip_path, kind, rel_path))+ continue+ target_uri = _join_uri(root_uri, rel_path)+ _validate_import_target_uri(target_uri)+ members.append((info, safe_zip_path, kind, rel_path))++ return members+++async def _root_exists(viking_fs, root_uri: str, ctx: RequestContext) -> bool:+ try:+ await viking_fs.ls(root_uri, ctx=ctx)+ return True+ except NotFoundError:+ return False+ except FileNotFoundError:+ return False+++async def _ensure_parent_exists(viking_fs, parent: str, ctx: RequestContext) -> None:+ try:+ await viking_fs.stat(parent, ctx=ctx)+ except Exception:+ await viking_fs.mkdir(parent, ctx=ctx)+++async def _remove_existing_root(viking_fs, root_uri: str, ctx: RequestContext) -> None:+ if not hasattr(viking_fs, "rm"):+ logger.warning(f"[local_fs] Cannot remove existing resource without rm(): {root_uri}")+ return+ try:+ await viking_fs.rm(root_uri, recursive=True, ctx=ctx)+ except NotFoundError:+ return+ except FileNotFoundError:+ return+++async def _existing_scope_roots(+ viking_fs, scopes: tuple[str, ...], ctx: RequestContext+) -> list[str]:+ existing: list[str] = []+ for scope in scopes:+ scope_uri = f"viking://{scope}"+ if await _root_exists(viking_fs, scope_uri, ctx):+ existing.append(scope_uri)+ return existing+++def _exportable_entries(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:+ return [entry for entry in entries if not _is_excluded_rel_path(entry.get("rel_path", ""))]+++async def _enqueue_direct_vectorization(+ viking_fs,+ uri: str,+ ctx: RequestContext,+ manifest: Optional[dict[str, Any]] = None,+ manifest_path_root_uri: Optional[str] = None,+) -> None:+ manifest = manifest or {}+ manifest_path_root_uri = manifest_path_root_uri or uri+ entries = await viking_fs.tree(uri, node_limit=None, level_limit=None, ctx=ctx)dir_uris = {uri}- file_entries: list[tuple[str, str, str]] = []+ file_entries: list[tuple[str, str, str, str]] = []for entry in entries:entry_uri = entry.get("uri")if not entry_uri:continue+ rel_path = entry.get("rel_path") or _rel_path_for_uri(uri, entry_uri)+ manifest_rel_path = _rel_path_for_uri(manifest_path_root_uri, entry_uri)if entry.get("isDir"):dir_uris.add(entry_uri)continue- name = entry.get("name", "")+ name = entry.get("name", "") or _leaf_name(rel_path)if name.startswith("."):continue- parent_uri = VikingURI(entry_uri).parent.uri- file_entries.append((entry_uri, parent_uri, name))+ parent = VikingURI(entry_uri).parent+ if parent:+ file_entries.append((entry_uri, parent.uri, name, manifest_rel_path))async def index_dir(dir_uri: str) -> None:- abstract_uri = f"{dir_uri}/.abstract.md"- overview_uri = f"{dir_uri}/.overview.md"- abstract = ""- overview = ""- try:- if await viking_fs.exists(abstract_uri, ctx=ctx):- content = await viking_fs.read_file(abstract_uri, ctx=ctx)- abstract = content.decode("utf-8") if isinstance(content, bytes) else content- if await viking_fs.exists(overview_uri, ctx=ctx):- content = await viking_fs.read_file(overview_uri, ctx=ctx)- overview = content.decode("utf-8") if isinstance(content, bytes) else content- except Exception:+ rel_path = _rel_path_for_uri(manifest_path_root_uri, dir_uri)+ records_by_level = _manifest_records_by_level(manifest, rel_path)+ scalar_overrides = _manifest_scalar_overrides(manifest, rel_path)+ abstract = str(records_by_level.get(0, {}).get("text") or "")+ overview = str(records_by_level.get(1, {}).get("text") or "")++ if not abstract:+ abstract = await _read_text_if_exists(viking_fs, f"{dir_uri}/.abstract.md", ctx)+ if not overview:+ overview = await _read_text_if_exists(viking_fs, f"{dir_uri}/.overview.md", ctx)++ if not abstract and not overview and not scalar_overrides:returnawait vectorize_directory_meta(- dir_uri, abstract, overview, context_type=context_type_for_uri(dir_uri), ctx=ctx+ dir_uri,+ abstract,+ overview,+ context_type=context_type_for_uri(dir_uri),+ ctx=ctx,+ include_overview=bool(overview),+ scalar_overrides=scalar_overrides,)- async def index_file(file_uri: str, parent_uri: str, name: str) -> None:+ async def index_file(file_uri: str, parent_uri: str, name: str, rel_path: str) -> None:+ overrides = _manifest_scalar_overrides(manifest, rel_path)+ scalar_override = overrides.get(2) or next(iter(overrides.values()), {})+ summary = str(scalar_override.get("abstract") or "")await vectorize_file(file_path=file_uri,- summary_dict={"name": name},+ summary_dict={"name": name, "summary": summary},parent_uri=parent_uri,context_type=context_type_for_uri(file_uri),ctx=ctx,+ scalar_override=scalar_override,)await asyncio.gather(*(index_dir(dir_uri) for dir_uri in dir_uris))await asyncio.gather(*(- index_file(file_uri, parent_uri, file_name)- for file_uri, parent_uri, file_name in file_entries+ index_file(file_uri, parent_uri, file_name, rel_path)+ for file_uri, parent_uri, file_name, rel_path in file_entries))@@ -160,8 +905,7 @@ async def import_ovpack(file_path: str,parent: str,ctx: RequestContext,- force: bool = False,- vectorize: bool = True,+ on_conflict: Optional[str] = None,) -> str:"""Import .ovpack file to the specified parent path.@@ -170,8 +914,7 @@ async def import_ovpack(viking_fs: VikingFS instancefile_path: Local .ovpack file pathparent: Target parent URI (e.g., viking://resources/...)- force: Whether to force overwrite existing resource (default: False)- vectorize: Whether to trigger vectorization (default: True)+ on_conflict: One of "fail", "overwrite", or "skip"Returns:Root resource URI after import@@ -179,100 +922,216 @@ async def import_ovpack(if not os.path.exists(file_path):raise FileNotFoundError(f"File not found: {file_path}")- parent = parent.strip().rstrip("/")-- try:- await viking_fs.stat(parent, ctx=ctx)- except Exception:- # Parent directory does not exist, create it- await viking_fs.mkdir(parent, ctx=ctx)+ parent = _strip_uri_trailing_slash(parent)+ _validate_public_scope(parent, operation="import", allow_root=True)+ conflict_action = _normalize_on_conflict(on_conflict)with zipfile.ZipFile(file_path, "r") as zf:- # 1. Get root directory name from ZIP and perform initial validationinfolist = zf.infolist()if not infolist:raise ValueError("Empty ovpack file")- # Extract root directory name (assuming first path component is root name)- first_path = infolist[0].filename- # Normalize path separators to handle Windows-created ZIPs- first_path = first_path.replace("\\", "/")- base_name = first_path.split("/")[0]- if not base_name:- raise ValueError("Could not determine root directory name from ovpack")-- root_uri = f"{parent}/{base_name}"+ base_name = _base_name_from_entries(infolist)+ manifest = _read_manifest(zf, base_name)+ root_uri = _resolve_import_root_uri(parent, base_name, manifest)+ _validate_import_scope_compatibility(manifest, root_uri)_validate_import_target_uri(root_uri)+ manifest_root = manifest.get("root") if isinstance(manifest.get("root"), dict) else {}+ if manifest_root.get("name") and manifest_root.get("name") != base_name:+ logger.warning(+ f"[local_fs] Manifest root name ({manifest_root.get('name')}) "+ f"does not match zip root ({base_name})"+ )- # 2. Conflict check- try:- await viking_fs.ls(root_uri, ctx=ctx)- if not force:- raise FileExistsError(- f"Resource already exists at {root_uri}. Use force=True to overwrite."- )- logger.info(f"[local_fs] Overwriting existing resource at {root_uri}")- except NotFoundError:- # Path does not exist, safe to import- pass+ members = _validated_import_members(infolist, base_name, root_uri)+ existing_roots = [root_uri] if await _root_exists(viking_fs, root_uri, ctx) else []- # 3. Validate core metadata _._meta.json (originally .meta.json)- meta_zip_path = f"{base_name}/_._meta.json"- try:- meta_content = zf.read(meta_zip_path)- meta_data = json.loads(meta_content.decode("utf-8"))- if "uri" in meta_data and not meta_data["uri"].endswith(base_name):- logger.warning(- f"[local_fs] URI in _._meta.json ({meta_data['uri']}) mismatch with base_name ({base_name})"+ if existing_roots:+ if conflict_action == "skip":+ logger.info(f"[local_fs] Skipped existing resource at {root_uri}")+ return root_uri+ if conflict_action == "fail":+ resource = existing_roots[0]+ raise ConflictError(+ f"Resource already exists at {resource}. "+ "Use on_conflict='overwrite' to replace it.",+ resource=resource,)- except KeyError:- logger.warning(- f"[local_fs] _._meta.json not found in {file_path}, importing without validation"- )- except json.JSONDecodeError:- raise ValueError(f"Invalid JSON in {meta_zip_path}")- # 4. Execute import- for info in infolist:- zip_path = info.filename- if not zip_path:- continue+ _validate_manifest_content(zf, manifest, infolist, base_name)+ if parent != "viking://":+ await _ensure_parent_exists(viking_fs, parent, ctx)- # Validate before normalization so backslash paths are rejected- safe_zip_path = _validate_ovpack_member_path(zip_path, base_name)- # Normalize path separators to handle Windows-created ZIPs- safe_zip_path = safe_zip_path.replace("\\", "/")+ for existing_root in existing_roots:+ logger.info(f"[local_fs] Overwriting existing resource at {existing_root}")+ await _remove_existing_root(viking_fs, existing_root, ctx)- # Handle directory entries- if safe_zip_path.endswith("/"):- rel_path = get_viking_rel_path_from_zip(safe_zip_path.rstrip("/"))- target_dir_uri = f"{root_uri}/{rel_path}" if rel_path else root_uri- await viking_fs.mkdir(target_dir_uri, exist_ok=True, ctx=ctx)+ for _, safe_zip_path, kind, rel_path in members:+ if kind == "manifest":+ continue+ if kind == "directory":+ await viking_fs.mkdir(_join_uri(root_uri, rel_path), exist_ok=True, ctx=ctx)continue- # Handle file entries- rel_path = get_viking_rel_path_from_zip(safe_zip_path)- target_file_uri = f"{root_uri}/{rel_path}" if rel_path else root_uri- _validate_import_target_uri(target_file_uri)-- try:- data = zf.read(safe_zip_path)- await viking_fs.write_file_bytes(target_file_uri, data, ctx=ctx)- except Exception as e:- logger.error(f"Failed to import {zip_path} to {target_file_uri}: {e}")- if not force: # In non-force mode, stop on error- raise e+ target_file_uri = _join_uri(root_uri, rel_path)+ data = zf.read(safe_zip_path)+ await viking_fs.write_file_bytes(target_file_uri, data, ctx=ctx)logger.info(f"[local_fs] Successfully imported {file_path} to {root_uri}")- if vectorize:- await _enqueue_direct_vectorization(viking_fs, root_uri, ctx=ctx)+ if VikingURI(root_uri).scope not in _NON_VECTOR_SCOPES:+ await _enqueue_direct_vectorization(viking_fs, root_uri, ctx=ctx, manifest=manifest)logger.info(f"[local_fs] Enqueued direct vectorization for: {root_uri}")+ else:+ logger.info(f"[local_fs] Skipped vectorization for non-vector scope: {root_uri}")return root_uri-async def export_ovpack(viking_fs, uri: str, to: str, ctx: RequestContext) -> str:+async def _backup_entries(viking_fs, ctx: RequestContext) -> list[dict[str, Any]]:+ entries: list[dict[str, Any]] = []+ for scope in _PUBLIC_SCOPES:+ scope_uri = f"viking://{scope}"+ entries.append(+ {+ "rel_path": scope,+ "uri": scope_uri,+ "isDir": True,+ "size": 0,+ }+ )+ try:+ scope_entries = await viking_fs.tree(+ scope_uri,+ show_all_hidden=True,+ node_limit=None,+ level_limit=None,+ ctx=ctx,+ )+ except (NotFoundError, FileNotFoundError):+ continue++ for entry in _exportable_entries(scope_entries):+ rel_path = entry.get("rel_path", "")+ if not rel_path:+ continue+ scoped_entry = dict(entry)+ scoped_entry["rel_path"] = f"{scope}/{rel_path}"+ scoped_entry["uri"] = _join_uri(scope_uri, rel_path)+ entries.append(scoped_entry)+ return entries+++def _backup_scopes_from_manifest(+ manifest: dict[str, Any], manifest_entries: dict[str, dict[str, Any]]+) -> tuple[str, ...]:+ roots = {rel_path.split("/", 1)[0] for rel_path in manifest_entries if rel_path}+ unexpected = sorted(root for root in roots if root not in _IMPORTABLE_SCOPES)+ if unexpected:+ raise InvalidArgumentError(+ "Backup ovpack contains unsupported roots",+ details={"roots": unexpected},+ )++ directory_scope_roots = {+ rel_path+ for rel_path, entry in manifest_entries.items()+ if rel_path in _IMPORTABLE_SCOPES and entry.get("kind") == "directory"+ }+ missing_scope_directories = sorted(roots - directory_scope_roots)+ if missing_scope_directories:+ raise InvalidArgumentError(+ "Backup ovpack scope roots must be directory entries",+ details={"missing_scope_directories": missing_scope_directories},+ )++ entry_scopes = tuple(scope for scope in _PUBLIC_SCOPES if scope in directory_scope_roots)+ declared_scopes = manifest.get("scopes")+ if not isinstance(declared_scopes, list) or any(+ not isinstance(scope, str) for scope in declared_scopes+ ):+ raise InvalidArgumentError(+ "Invalid backup ovpack scopes",+ details={"field": "scopes"},+ )+ duplicate_scopes = sorted(+ scope for scope in set(declared_scopes) if declared_scopes.count(scope) > 1+ )+ invalid_scopes = sorted(scope for scope in declared_scopes if scope not in _IMPORTABLE_SCOPES)+ if duplicate_scopes or invalid_scopes:+ raise InvalidArgumentError(+ "Invalid backup ovpack scopes",+ details={+ "duplicate_scopes": duplicate_scopes,+ "invalid_scopes": invalid_scopes,+ },+ )+ if set(declared_scopes) != set(entry_scopes):+ raise InvalidArgumentError(+ "Backup ovpack scopes do not match entries",+ details={+ "declared_scopes": declared_scopes,+ "entry_scopes": list(entry_scopes),+ },+ )+ return entry_scopes+++async def _write_ovpack_archive(+ viking_fs,+ root_uri: str,+ to: str,+ base_name: str,+ entries: list[dict[str, Any]],+ manifest: dict[str, Any],+ ctx: RequestContext,+) -> str:+ ensure_dir_exists(to)+ manifest_entries = _manifest_entries_by_path(manifest)+ manifest_file_entries = {+ rel_path: entry+ for rel_path, entry in manifest_entries.items()+ if entry.get("kind") == "file"+ }++ with zipfile.ZipFile(to, "w", zipfile.ZIP_DEFLATED, allowZip64=True) as zf:+ zf.writestr(base_name + "/", "")++ for entry in entries:+ rel_path = entry["rel_path"]+ zip_path = get_ovpack_zip_path(base_name, rel_path)++ if entry.get("isDir"):+ zf.writestr(zip_path + "/", "")+ else:+ full_uri = entry.get("uri") or _join_uri(root_uri, rel_path)+ try:+ data = await viking_fs.read_file_bytes(full_uri, ctx=ctx)+ except Exception as exc:+ logger.warning(f"Failed to export file {full_uri}: {exc}")+ raise++ manifest_entry = manifest_file_entries.get(rel_path)+ if manifest_entry is not None:+ manifest_entry["size"] = len(data)+ manifest_entry["sha256"] = _sha256_hex(data)+ zf.writestr(zip_path, data)++ manifest["content_sha256"] = _manifest_content_sha256(manifest_file_entries)+ zf.writestr(+ f"{base_name}/{OVPACK_MANIFEST_ZIP_LEAF}",+ json.dumps(manifest, ensure_ascii=False, sort_keys=True, indent=2).encode("utf-8"),+ )+ return to+++async def export_ovpack(+ viking_fs,+ uri: str,+ to: str,+ ctx: RequestContext,+ vector_store=None,+) -> str:"""Export the specified context path as a .ovpack file.@@ -280,71 +1139,141 @@ async def export_ovpack(viking_fs, uri: str, to: str, ctx: RequestContext) -> stviking_fs: VikingFS instanceuri: Viking URIto: Target file path (can be an existing directory or a path ending with .ovpack)+ vector_store: Optional vector store used to export portable scalar metadataReturns:Exported file path- Raises:- ValueError: If export size exceeds limits (65536 files or 2GB total size)"""- # Safety limits- MAX_FILES = 65536- MAX_TOTAL_SIZE = 2 * 1024 * 1024 * 1024 # 2GB+ uri = _strip_uri_trailing_slash(uri)+ _validate_export_source_uri(uri)- base_name = uri.strip().rstrip("/").split("/")[-1]- if not base_name:- base_name = "export"+ base_name = _leaf_name(uri) or "export"if os.path.isdir(to):to = os.path.join(to, f"{base_name}.ovpack")else:to = ensure_ovpack_extension(to)- ensure_dir_exists(to)+ entries = _exportable_entries(+ await viking_fs.tree(+ uri,+ show_all_hidden=True,+ node_limit=None,+ level_limit=None,+ ctx=ctx,+ )+ )+ manifest = await _build_manifest(viking_fs, vector_store, uri, base_name, entries, ctx)+ await _write_ovpack_archive(viking_fs, uri, to, base_name, entries, manifest, ctx)- entries = await viking_fs.tree(uri, show_all_hidden=True, ctx=ctx)+ logger.info(f"[local_fs] Exported {uri} to {to}")+ return to- # Check file count limit- file_count = sum(1 for entry in entries if not entry.get("isDir"))- if file_count > MAX_FILES:- raise ValueError(- f"Export aborted: too many files ({file_count} files, limit is {MAX_FILES}). "- f"Please export a smaller directory."- )- # Calculate total size and check limit- total_size = 0- for entry in entries:- if not entry.get("isDir"):- # Get file size from entry if available- size = entry.get("size", 0)- total_size += size+async def backup_ovpack(+ viking_fs,+ to: str,+ ctx: RequestContext,+ vector_store=None,+) -> str:+ """Export all public OpenViking scopes as a restore-only backup package."""+ base_name = OVPACK_BACKUP_NAME+ if os.path.isdir(to):+ to = os.path.join(to, f"{base_name}.ovpack")+ else:+ to = ensure_ovpack_extension(to)- if total_size > MAX_TOTAL_SIZE:- size_mb = total_size / (1024 * 1024)- limit_mb = MAX_TOTAL_SIZE / (1024 * 1024)- raise ValueError(- f"Export aborted: total size too large ({size_mb:.1f}MB, limit is {limit_mb:.0f}MB). "- f"Please export a smaller directory."- )+ entries = await _backup_entries(viking_fs, ctx)+ manifest = await _build_manifest(+ viking_fs,+ vector_store,+ "viking://",+ base_name,+ entries,+ ctx,+ package_type=OVPACK_BACKUP_TYPE,+ scopes=list(_PUBLIC_SCOPES),+ )+ await _write_ovpack_archive(viking_fs, "viking://", to, base_name, entries, manifest, ctx)- with zipfile.ZipFile(to, "w", zipfile.ZIP_DEFLATED, allowZip64=True) as zf:- # Write root directory entry- zf.writestr(base_name + "/", "")+ logger.info(f"[local_fs] Backed up OpenViking public scopes to {to}")+ return to- for entry in entries:- rel_path = entry["rel_path"]- zip_path = get_ovpack_zip_path(base_name, rel_path)- if entry.get("isDir"):- zf.writestr(zip_path + "/", "")- else:- full_uri = f"{uri}/{rel_path}"- try:- data = await viking_fs.read_file_bytes(full_uri, ctx=ctx)- zf.writestr(zip_path, data)- except Exception as e:- logger.warning(f"Failed to export file {full_uri}: {e}")+async def restore_ovpack(+ viking_fs,+ file_path: str,+ ctx: RequestContext,+ on_conflict: Optional[str] = None,+) -> str:+ """Restore a backup package to its original public scope roots."""+ if not os.path.exists(file_path):+ raise FileNotFoundError(f"File not found: {file_path}")- logger.info(f"[local_fs] Exported {uri} to {to}")- return to+ conflict_action = _normalize_on_conflict(on_conflict)+ root_uri = "viking://"++ with zipfile.ZipFile(file_path, "r") as zf:+ infolist = zf.infolist()+ if not infolist:+ raise ValueError("Empty ovpack file")++ base_name = _base_name_from_entries(infolist)+ manifest = _read_manifest(zf, base_name)+ if not _is_backup_package(manifest):+ raise InvalidArgumentError(+ "Only backup ovpack packages can be restored with ov restore or the restore API",+ details={"root": base_name},+ )++ manifest_entries = _manifest_entries_by_path(manifest)+ backup_scopes = _backup_scopes_from_manifest(manifest, manifest_entries)+ members = _validated_import_members(infolist, base_name, root_uri)+ existing_roots = await _existing_scope_roots(viking_fs, backup_scopes, ctx)++ if existing_roots:+ if conflict_action == "skip":+ logger.info("[local_fs] Skipped backup restore because target scopes exist")+ return root_uri+ if conflict_action == "fail":+ resource = existing_roots[0]+ raise ConflictError(+ f"Resource already exists at {resource}. "+ "Use on_conflict='overwrite' to replace it.",+ resource=resource,+ )++ _validate_manifest_content(zf, manifest, infolist, base_name)++ for existing_root in existing_roots:+ logger.info(f"[local_fs] Overwriting existing resource at {existing_root}")+ await _remove_existing_root(viking_fs, existing_root, ctx)++ for _, safe_zip_path, kind, rel_path in members:+ if kind == "manifest" or rel_path == "":+ continue+ if kind == "directory":+ await viking_fs.mkdir(_join_uri(root_uri, rel_path), exist_ok=True, ctx=ctx)+ continue++ data = zf.read(safe_zip_path)+ await viking_fs.write_file_bytes(_join_uri(root_uri, rel_path), data, ctx=ctx)++ logger.info(f"[local_fs] Successfully restored backup {file_path}")++ for scope in backup_scopes:+ if scope in _NON_VECTOR_SCOPES:+ logger.info(f"[local_fs] Skipped vectorization for non-vector scope: {scope}")+ continue+ scope_uri = f"viking://{scope}"+ await _enqueue_direct_vectorization(+ viking_fs,+ scope_uri,+ ctx=ctx,+ manifest=manifest,+ manifest_path_root_uri=root_uri,+ )+ logger.info(f"[local_fs] Enqueued direct vectorization for: {scope_uri}")++ return root_uridiff --git a/openviking/sync_client.py b/openviking/sync_client.pyindex db723f374..6940648fc 100644--- a/openviking/sync_client.py+++ b/openviking/sync_client.py@@ -297,11 +297,37 @@ class SyncOpenViking:"""Export .ovpack file"""return run_async(self._async_client.export_ovpack(uri, to))+ def backup_ovpack(self, to: str) -> str:+ """Back up public scopes as a restore-only .ovpack file."""+ return run_async(self._async_client.backup_ovpack(to))+def import_ovpack(- self, file_path: str, target: str, force: bool = False, vectorize: bool = True+ self,+ file_path: str,+ target: str,+ on_conflict: Optional[str] = None,) -> str:"""Import .ovpack file (triggers vectorization by default)"""- return run_async(self._async_client.import_ovpack(file_path, target, force, vectorize))+ return run_async(+ self._async_client.import_ovpack(+ file_path,+ target,+ on_conflict=on_conflict,+ )+ )++ def restore_ovpack(+ self,+ file_path: str,+ on_conflict: Optional[str] = None,+ ) -> str:+ """Restore backup .ovpack file."""+ return run_async(+ self._async_client.restore_ovpack(+ file_path,+ on_conflict=on_conflict,+ )+ )def close(self) -> None:"""Close OpenViking and release resources."""diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.pyindex 28b3d8959..b977a611e 100644--- a/openviking/utils/embedding_utils.py+++ b/openviking/utils/embedding_utils.py@@ -9,7 +9,7 @@ Common logic for creating Context objects and enqueuing them to EmbeddingQueue.import mathimport osfrom datetime import datetime, timezone-from typing import Dict, Optional+from typing import Any, Dict, Optionalfrom openviking.core.context import Context, ContextLevel, ResourceContentType, Vectorizefrom openviking.core.namespace import context_type_for_uri, owner_space_for_uri@@ -23,6 +23,25 @@ from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)_EMBEDDING_TRUNCATION_SUFFIX = "\n...(truncated for embedding)"+_PORTABLE_SCALAR_FIELDS = frozenset(+ {+ "type",+ "level",+ "name",+ "description",+ "tags",+ "abstract",+ }+)+++def _apply_scalar_overrides(embedding_msg, overrides: Optional[Dict[str, Any]]) -> None:+ if not embedding_msg or not overrides:+ return+ for field in _PORTABLE_SCALAR_FIELDS:+ value = overrides.get(field)+ if value is not None:+ embedding_msg.context_data[field] = valuedef _estimate_embedding_input_tokens(text: str) -> int:@@ -224,6 +243,7 @@ async def vectorize_directory_meta(ctx: Optional[RequestContext] = None,semantic_msg_id: Optional[str] = None,include_overview: bool = True,+ scalar_overrides: Optional[Dict[int, Dict[str, Any]]] = None,) -> None:"""Vectorize directory metadata (.abstract.md and .overview.md).@@ -261,6 +281,10 @@ async def vectorize_directory_meta()context_abstract.set_vectorize(Vectorize(text=abstract))msg_abstract = EmbeddingMsgConverter.from_context(context_abstract)+ _apply_scalar_overrides(+ msg_abstract,+ (scalar_overrides or {}).get(int(ContextLevel.ABSTRACT.value)),+ )if msg_abstract:msg_abstract.semantic_msg_id = semantic_msg_idtry:@@ -290,6 +314,10 @@ async def vectorize_directory_meta()context_overview.set_vectorize(Vectorize(text=overview))msg_overview = EmbeddingMsgConverter.from_context(context_overview)+ _apply_scalar_overrides(+ msg_overview,+ (scalar_overrides or {}).get(int(ContextLevel.OVERVIEW.value)),+ )if msg_overview:msg_overview.semantic_msg_id = semantic_msg_idtry:@@ -314,6 +342,7 @@ async def vectorize_file(semantic_msg_id: Optional[str] = None,use_summary: bool = False,preserve_existing_created_at: bool = False,+ scalar_override: Optional[Dict[str, Any]] = None,) -> None:"""Vectorize a single file.@@ -406,6 +435,7 @@ async def vectorize_file(if not embedding_msg:return+ _apply_scalar_overrides(embedding_msg, scalar_override)embedding_msg.semantic_msg_id = semantic_msg_idawait embedding_queue.enqueue(embedding_msg)enqueued = Truediff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.pyindex 1e13d6d6b..a25e10282 100644--- a/openviking_cli/client/base.py+++ b/openviking_cli/client/base.py@@ -302,13 +302,30 @@ class BaseClient(ABC):"""Export as .ovpack file."""...+ @abstractmethod+ async def backup_ovpack(self, to: str) -> str:+ """Back up public scopes as a restore-only .ovpack file."""+ ...+@abstractmethodasync def import_ovpack(- self, file_path: str, parent: str, force: bool = False, vectorize: bool = True+ self,+ file_path: str,+ parent: str,+ on_conflict: Optional[str] = None,) -> str:"""Import .ovpack file."""...+ @abstractmethod+ async def restore_ovpack(+ self,+ file_path: str,+ on_conflict: Optional[str] = None,+ ) -> str:+ """Restore backup .ovpack file."""+ ...+# ============= Debug =============@abstractmethoddiff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.pyindex b7018346e..828922707 100644--- a/openviking_cli/client/http.py+++ b/openviking_cli/client/http.py@@ -935,20 +935,38 @@ class AsyncHTTPClient(BaseClient):return str(to_path)+ async def backup_ovpack(self, to: str) -> str:+ """Back up public scopes as a restore-only .ovpack file."""+ to_path = Path(to)+ if to_path.is_dir():+ to_path = to_path / "openviking-backup.ovpack"+ elif not str(to_path).endswith(".ovpack"):+ to_path = Path(str(to_path) + ".ovpack")++ to_path.parent.mkdir(parents=True, exist_ok=True)++ response = await self._http.post("/api/v1/pack/backup", json={})+ if not response.is_success:+ self._handle_response(response)++ with open(to_path, "wb") as f:+ f.write(response.content)++ return str(to_path)+async def import_ovpack(self,file_path: str,parent: str,- force: bool = False,- vectorize: bool = True,+ on_conflict: Optional[str] = None,) -> str:"""Import .ovpack file."""parent = VikingURI.normalize(parent)request_data = {"parent": parent,- "force": force,- "vectorize": vectorize,}+ if on_conflict is not None:+ request_data["on_conflict"] = on_conflictfile_path_obj = Path(file_path)if not file_path_obj.exists():@@ -966,6 +984,32 @@ class AsyncHTTPClient(BaseClient):result = self._handle_response(response)return result.get("uri", "")+ async def restore_ovpack(+ self,+ file_path: str,+ on_conflict: Optional[str] = None,+ ) -> str:+ """Restore backup .ovpack file."""+ request_data = {}+ if on_conflict is not None:+ request_data["on_conflict"] = on_conflict++ file_path_obj = Path(file_path)+ if not file_path_obj.exists():+ raise FileNotFoundError(f"Local ovpack file not found: {file_path}")+ if not file_path_obj.is_file():+ raise ValueError(f"Path {file_path} is not a file")++ temp_file_id = await self._upload_temp_file(file_path)+ request_data["temp_file_id"] = temp_file_id++ response = await self._http.post(+ "/api/v1/pack/restore",+ json=request_data,+ )+ result = self._handle_response(response)+ return result.get("uri", "")+# ============= Debug =============async def health(self) -> bool:diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.pyindex e1a625bb8..293c900ba 100644--- a/openviking_cli/client/sync_http.py+++ b/openviking_cli/client/sync_http.py@@ -419,11 +419,37 @@ class SyncHTTPClient:"""return run_async(self._async_client.export_ovpack(uri, to))+ def backup_ovpack(self, to: str) -> str:+ """Back up public scopes as a restore-only .ovpack file."""+ return run_async(self._async_client.backup_ovpack(to))+def import_ovpack(- self, file_path: str, target: str, force: bool = False, vectorize: bool = True+ self,+ file_path: str,+ target: str,+ on_conflict: Optional[str] = None,) -> str:"""Import .ovpack file."""- return run_async(self._async_client.import_ovpack(file_path, target, force, vectorize))+ return run_async(+ self._async_client.import_ovpack(+ file_path,+ target,+ on_conflict=on_conflict,+ )+ )++ def restore_ovpack(+ self,+ file_path: str,+ on_conflict: Optional[str] = None,+ ) -> str:+ """Restore backup .ovpack file."""+ return run_async(+ self._async_client.restore_ovpack(+ file_path,+ on_conflict=on_conflict,+ )+ )# ============= Admin =============diff --git a/openviking_cli/exceptions.py b/openviking_cli/exceptions.pyindex 875e3acb0..9305a2c6d 100644--- a/openviking_cli/exceptions.py+++ b/openviking_cli/exceptions.py@@ -55,10 +55,13 @@ class NotFoundError(OpenVikingError):"""Resource not found."""def __init__(self, resource: str, resource_type: str = "resource"):- message = f"{resource_type.capitalize()} not found: {resource}"- super().__init__(- message, code="NOT_FOUND", details={"resource": resource, "type": resource_type}- )+ details = {"type": resource_type}+ if resource:+ details["resource"] = resource+ message = f"{resource_type.capitalize()} not found: {resource}"+ else:+ message = f"{resource_type.capitalize()} not found"+ super().__init__(message, code="NOT_FOUND", details=details)class AlreadyExistsError(OpenVikingError):diff --git a/tests/README.md b/tests/README.mdindex f59f4325a..b1e2ff977 100644--- a/tests/README.md+++ b/tests/README.md@@ -122,7 +122,7 @@ Tests for the OpenViking client API (`AsyncOpenViking` / `SyncOpenViking`).| `test_search.py` | Semantic search | `find()` fast vector search with limit/threshold/target_uri; `search()` with intent analysis and session context || `test_relations.py` | Resource linking | `link()` single/multiple URIs with reason; `unlink()` existing/nonexistent; `relations()` query || `test_file_operations.py` | File manipulation | `rm()` file/directory with recursive; `mv()` rename/move; `grep()` content search with case sensitivity; `glob()` pattern matching |-| `test_import_export.py` | Import/Export | `export_ovpack()` file/directory; `import_ovpack()` with force/vectorize options; roundtrip verification |+| `test_import_export.py` | Import/Export | `export_ovpack()` file/directory; `import_ovpack()` with conflict policy; roundtrip verification |### server/diff --git a/tests/api_test/api/client.py b/tests/api_test/api/client.pyindex b716a456b..2e883d132 100644--- a/tests/api_test/api/client.py+++ b/tests/api_test/api/client.py@@ -428,13 +428,18 @@ class OpenVikingAPIClient:return responsedef import_ovpack(- self, file_path: str, parent: str, force: bool = False, vectorize: bool = True+ self,+ file_path: str,+ parent: str,+ on_conflict: str | None = None,) -> requests.Response:endpoint = "/api/v1/pack/import"url = self._build_url(self.server_url, endpoint)if not os.path.isfile(file_path):raise FileNotFoundError(f"Local ovpack file not found: {file_path}")- payload = {"parent": parent, "force": force, "vectorize": vectorize}+ payload = {"parent": parent}+ if on_conflict is not None:+ payload["on_conflict"] = on_conflictpayload["temp_file_id"] = self._upload_temp_file(file_path)return self._request_with_retry("POST",diff --git a/tests/client/test_http_client_local_upload.py b/tests/client/test_http_client_local_upload.pyindex e08c9357d..f0c5b5e17 100644--- a/tests/client/test_http_client_local_upload.py+++ b/tests/client/test_http_client_local_upload.py@@ -113,12 +113,18 @@ async def test_import_ovpack_uploads_local_file_even_when_url_is_localhost(tmp_pclient._upload_temp_file = fake_uploadclient._handle_response = lambda _response: {"uri": "viking://resources/imported"}- await client.import_ovpack(str(pack_file), parent="viking://resources/")+ await client.import_ovpack(+ str(pack_file),+ parent="viking://resources/",+ on_conflict="skip",+ )call = fake_http.calls[-1]assert call["path"] == "/api/v1/pack/import"assert call["json"]["temp_file_id"] == "upload_pack.ovpack"+ assert call["json"]["on_conflict"] == "skip"assert "file_path" not in call["json"]+ assert "force" not in call["json"]@pytest.mark.asynciodiff --git a/tests/client/test_import_export.py b/tests/client/test_import_export.pyindex e6d28bc9f..ae776529a 100644--- a/tests/client/test_import_export.py+++ b/tests/client/test_import_export.py@@ -3,7 +3,9 @@"""Import/export tests"""+import hashlibimport io+import jsonimport zipfilefrom pathlib import Path@@ -53,29 +55,27 @@ class TestImportOvpack:await client.export_ovpack(uri, str(export_path))# Import to new location- import_uri = await client.import_ovpack(- str(export_path), "viking://resources/imported/", vectorize=False- )+ import_uri = await client.import_ovpack(str(export_path), "viking://resources/imported/")assert isinstance(import_uri, str)assert "imported" in import_uri- async def test_import_with_force(self, client_with_resource, temp_dir: Path):- """Test force overwrite import"""+ async def test_import_with_on_conflict_overwrite(self, client_with_resource, temp_dir: Path):+ """Test overwrite import."""client, uri = client_with_resource# Export first- export_path = temp_dir / "force_test.ovpack"+ export_path = temp_dir / "overwrite_test.ovpack"await client.export_ovpack(uri, str(export_path))# First import- await client.import_ovpack(- str(export_path), "viking://resources/force_test/", vectorize=False- )+ await client.import_ovpack(str(export_path), "viking://resources/overwrite_test/")- # Second force import (overwrite)+ # Second import overwrites the existing root.import_uri = await client.import_ovpack(- str(export_path), "viking://resources/force_test/", force=True, vectorize=False+ str(export_path),+ "viking://resources/overwrite_test/",+ on_conflict="overwrite",)assert isinstance(import_uri, str)@@ -104,9 +104,7 @@ class TestImportOvpack:await client.rm(original_uri, recursive=True)# Import- import_uri = await client.import_ovpack(- str(export_path), "viking://resources/roundtrip/", vectorize=False- )+ import_uri = await client.import_ovpack(str(export_path), "viking://resources/roundtrip/")# Read imported contentimported_content = ""@@ -120,8 +118,18 @@ class TestImportOvpack:@staticmethoddef _build_ovpack(zip_path: Path, entries: dict[str, str]) -> None:+ manifest = {+ "kind": "openviking.ovpack",+ "format_version": 2,+ "root": {"name": "pkg"},+ "entries": [{"path": "", "kind": "directory"}],+ "content_sha256": hashlib.sha256(b"[]").hexdigest(),+ "vectors": {},+ }buffer = io.BytesIO()with zipfile.ZipFile(buffer, "w") as zf:+ zf.writestr("pkg/", "")+ zf.writestr("pkg/_._ovpack_manifest.json", json.dumps(manifest))for name, content in entries.items():zf.writestr(name, content)zip_path.write_bytes(buffer.getvalue())@@ -131,35 +139,30 @@ class TestImportOvpack:[({- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',"pkg/../../escape.txt": "pwned",},"Unsafe ovpack entry path",),({- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',"/abs/path.txt": "pwned",},"Unsafe ovpack entry path",),({- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',"C:/drive/path.txt": "pwned",},"Unsafe ovpack entry path",),({- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',"pkg\\windows\\path.txt": "pwned",},"Unsafe ovpack entry path",),({- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',"other/file.txt": "pwned",},"Invalid ovpack entry root",@@ -173,6 +176,4 @@ class TestImportOvpack:self._build_ovpack(ovpack_path, entries)with pytest.raises(ValueError, match=error_pattern):- await client.import_ovpack(- str(ovpack_path), "viking://resources/security/", vectorize=False- )+ await client.import_ovpack(str(ovpack_path), "viking://resources/security/")diff --git a/tests/integration/test_full_workflow.py b/tests/integration/test_full_workflow.pyindex 5906af8bb..b14bd417b 100644--- a/tests/integration/test_full_workflow.py+++ b/tests/integration/test_full_workflow.py@@ -180,9 +180,7 @@ class TestImportExportWorkflow:await client.rm(original_uri, recursive=True)# 5. Import- import_uri = await client.import_ovpack(- str(export_path), "viking://resources/imported/", vectorize=False- )+ import_uri = await client.import_ovpack(str(export_path), "viking://resources/imported/")# 6. Verify content consistencyimported_content = ""diff --git a/tests/misc/test_ovpack_import_policy.py b/tests/misc/test_ovpack_import_policy.pyindex 74335d04e..77f318406 100644--- a/tests/misc/test_ovpack_import_policy.py+++ b/tests/misc/test_ovpack_import_policy.py@@ -4,6 +4,7 @@from __future__ import annotations+import hashlibimport jsonimport osimport tempfile@@ -13,7 +14,7 @@ from pathlib import Pathimport pytestfrom openviking.server.identity import RequestContext, Role-from openviking.storage.local_fs import import_ovpack+from openviking.storage.local_fs import backup_ovpack, export_ovpack, import_ovpack, restore_ovpackfrom openviking_cli.exceptions import InvalidArgumentError, NotFoundErrorfrom openviking_cli.session.user_id import UserIdentifier@@ -22,6 +23,7 @@ class FakeVikingFS:def __init__(self) -> None:self.written_files: list[str] = []self.created_dirs: list[str] = []+ self.tree_calls: list[str] = []async def stat(self, uri: str, ctx=None):return {"uri": uri, "isDir": True}@@ -35,7 +37,8 @@ class FakeVikingFS:async def write_file_bytes(self, uri: str, data: bytes, ctx=None):self.written_files.append(uri)- async def tree(self, uri: str, node_limit: int = 100000, level_limit: int = 1000, ctx=None):+ async def tree(self, uri: str, node_limit=None, level_limit=None, ctx=None):+ self.tree_calls.append(uri)return []async def exists(self, uri: str, ctx=None):@@ -45,6 +48,109 @@ class FakeVikingFS:raise FileNotFoundError(uri)+class FakeExportVikingFS:+ def __init__(self) -> None:+ self.binary_files = {+ "viking://resources/demo/notes.txt": b"hello",+ }+ self.text_files = {+ "viking://resources/demo/.abstract.md": "root abstract",+ "viking://resources/demo/.overview.md": "root overview",+ }++ async def tree(+ self,+ uri: str,+ show_all_hidden: bool = False,+ node_limit=None,+ level_limit=None,+ ctx=None,+ ):+ assert uri == "viking://resources/demo"+ assert show_all_hidden is True+ assert node_limit is None+ assert level_limit is None+ return [+ {+ "rel_path": ".overview.md",+ "uri": "viking://resources/demo/.overview.md",+ "isDir": False,+ "size": 13,+ },+ {+ "rel_path": "notes.txt",+ "uri": "viking://resources/demo/notes.txt",+ "isDir": False,+ "size": 5,+ },+ ]++ async def exists(self, uri: str, ctx=None):+ return uri in self.text_files++ async def read_file(self, uri: str, ctx=None):+ return self.text_files[uri]++ async def read_file_bytes(self, uri: str, ctx=None):+ if uri in self.text_files:+ return self.text_files[uri].encode("utf-8")+ return self.binary_files[uri]+++class FakeBackupVikingFS:+ def __init__(self) -> None:+ self.binary_files = {+ "viking://resources/README.md": b"hello",+ "viking://session/sess_1/.meta.json": b'{"session_id":"sess_1"}',+ }++ async def tree(+ self,+ uri: str,+ show_all_hidden: bool = False,+ node_limit=None,+ level_limit=None,+ ctx=None,+ ):+ assert show_all_hidden is True+ assert node_limit is None+ assert level_limit is None+ if uri == "viking://resources":+ return [+ {+ "rel_path": "README.md",+ "uri": "viking://resources/README.md",+ "isDir": False,+ "size": 5,+ }+ ]+ if uri == "viking://session":+ return [+ {+ "rel_path": "sess_1",+ "uri": "viking://session/sess_1",+ "isDir": True,+ "size": 0,+ },+ {+ "rel_path": "sess_1/.meta.json",+ "uri": "viking://session/sess_1/.meta.json",+ "isDir": False,+ "size": 23,+ },+ ]+ return []++ async def exists(self, uri: str, ctx=None):+ return False++ async def read_file(self, uri: str, ctx=None):+ raise FileNotFoundError(uri)++ async def read_file_bytes(self, uri: str, ctx=None):+ return self.binary_files[uri]++@pytest.fixturedef request_ctx() -> RequestContext:return RequestContext(user=UserIdentifier("acct", "alice", "agent1"), role=Role.USER)@@ -67,8 +173,137 @@ def _write_ovpack(path: Path, entries: dict[str, str]) -> None:zf.writestr(name, content)+def _content_sha256(entries: list[dict[str, object]]) -> str:+ payload = json.dumps(+ entries,+ ensure_ascii=False,+ sort_keys=True,+ separators=(",", ":"),+ ).encode("utf-8")+ return hashlib.sha256(payload).hexdigest()+++def _manifest_for_files(root_name: str, files: dict[str, str]) -> dict[str, object]:+ entries: list[dict[str, object]] = [{"path": "", "kind": "directory"}]+ content_entries: list[dict[str, object]] = []+ for rel_path, content in sorted(files.items()):+ data = content.encode("utf-8")+ file_entry = {+ "path": rel_path,+ "kind": "file",+ "size": len(data),+ "sha256": hashlib.sha256(data).hexdigest(),+ }+ entries.append(file_entry)+ content_entries.append(+ {+ "path": rel_path,+ "size": file_entry["size"],+ "sha256": file_entry["sha256"],+ }+ )++ return {+ "kind": "openviking.ovpack",+ "format_version": 2,+ "root": {+ "name": root_name,+ "uri": f"viking://resources/{root_name}",+ "scope": "resources",+ },+ "entries": entries,+ "content_sha256": _content_sha256(content_entries),+ "vectors": {},+ }+++def _write_ovpack_with_manifest(+ path: Path,+ root_name: str,+ files: dict[str, str],+ *,+ manifest: dict[str, object] | None = None,+) -> None:+ manifest = manifest or _manifest_for_files(root_name, files)+ entries = {+ f"{root_name}/": "",+ f"{root_name}/_._ovpack_manifest.json": json.dumps(manifest),+ }+ entries.update({f"{root_name}/{rel_path}": content for rel_path, content in files.items()})+ _write_ovpack(path, entries)+++async def test_export_ovpack_writes_v2_manifest_with_semantic_sidecars(+ temp_ovpack_path: Path, request_ctx: RequestContext+):+ await export_ovpack(+ FakeExportVikingFS(),+ "viking://resources/demo",+ str(temp_ovpack_path),+ ctx=request_ctx,+ )++ with zipfile.ZipFile(temp_ovpack_path, "r") as zf:+ names = set(zf.namelist())+ manifest = json.loads(zf.read("demo/_._ovpack_manifest.json").decode("utf-8"))++ assert "demo/notes.txt" in names+ assert "demo/_._overview.md" in names+ assert manifest["format_version"] == 2+ assert manifest["kind"] == "openviking.ovpack"+ note_entry = next(entry for entry in manifest["entries"] if entry["path"] == "notes.txt")+ note_sha256 = hashlib.sha256(b"hello").hexdigest()+ assert note_entry["size"] == 5+ assert note_entry["sha256"] == note_sha256+ overview_entry = next(entry for entry in manifest["entries"] if entry["path"] == ".overview.md")+ overview_sha256 = hashlib.sha256(b"root overview").hexdigest()+ assert overview_entry["sha256"] == overview_sha256+ assert manifest["content_sha256"] == _content_sha256(+ [+ {"path": ".overview.md", "size": 13, "sha256": overview_sha256},+ {"path": "notes.txt", "size": 5, "sha256": note_sha256},+ ]+ )+ assert manifest["vectors"][""][0]["text"] == "root abstract"++@pytest.mark.asyncio-async def test_import_ovpack_rejects_derived_semantic_files(+async def test_backup_restore_contract(temp_ovpack_path: Path, request_ctx: RequestContext):+ await backup_ovpack(+ FakeBackupVikingFS(),+ str(temp_ovpack_path),+ ctx=request_ctx,+ )++ with zipfile.ZipFile(temp_ovpack_path, "r") as zf:+ names = set(zf.namelist())+ manifest = json.loads(zf.read("openviking-backup/_._ovpack_manifest.json").decode("utf-8"))++ assert "openviking-backup/resources/README.md" in names+ assert "openviking-backup/session/sess_1/_._meta.json" in names+ assert manifest["root"] == {+ "name": "openviking-backup",+ "uri": "viking://",+ "scope": "root",+ "package_type": "backup",+ }+ assert manifest["scopes"] == ["resources", "user", "agent", "session"]++ with pytest.raises(InvalidArgumentError, match=r"must be restored"):+ await import_ovpack(FakeVikingFS(), str(temp_ovpack_path), "viking://", request_ctx)++ fake_fs = FakeVikingFS()+ assert await restore_ovpack(fake_fs, str(temp_ovpack_path), request_ctx) == "viking://"+ assert fake_fs.written_files == [+ "viking://resources/README.md",+ "viking://session/sess_1/.meta.json",+ ]+ assert fake_fs.tree_calls == ["viking://resources", "viking://user", "viking://agent"]+++async def test_import_legacy_ovpack_without_manifest_is_rejected(temp_ovpack_path: Path, request_ctx: RequestContext):_write_ovpack(@@ -80,36 +315,148 @@ async def test_import_ovpack_rejects_derived_semantic_files()fake_fs = FakeVikingFS()- with pytest.raises(- InvalidArgumentError,- match=r"cannot import derived semantic file: viking://resources/demo/\.overview\.md",- ):- await import_ovpack(- fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx, vectorize=False- )+ with pytest.raises(InvalidArgumentError, match=r"Missing ovpack manifest"):+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)assert fake_fs.written_files == []@pytest.mark.asyncio-async def test_import_ovpack_rejects_session_scope_targets(+async def test_import_ovpack_rejects_manifest_file_hash_mismatch(temp_ovpack_path: Path, request_ctx: RequestContext):+ manifest = _manifest_for_files("demo", {"notes.txt": "hello"})+ _write_ovpack_with_manifest(+ temp_ovpack_path,+ "demo",+ {"notes.txt": "jello"},+ manifest=manifest,+ )+ fake_fs = FakeVikingFS()++ with pytest.raises(InvalidArgumentError, match=r"sha256 does not match manifest"):+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)++ assert fake_fs.written_files == []+++async def test_import_ovpack_rejects_legacy_manifest_version(+ temp_ovpack_path: Path, request_ctx: RequestContext+):+ manifest = _manifest_for_files("demo", {"notes.txt": "hello"})+ manifest["format_version"] = 1+ _write_ovpack_with_manifest(temp_ovpack_path, "demo", {"notes.txt": "hello"}, manifest=manifest)+ fake_fs = FakeVikingFS()++ with pytest.raises(InvalidArgumentError, match=r"Unsupported ovpack format_version 1"):+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)++ assert fake_fs.written_files == []+++async def test_import_ovpack_rejects_manifest_unexpected_directory(+ temp_ovpack_path: Path, request_ctx: RequestContext+):+ manifest = _manifest_for_files("demo", {"notes.txt": "hello"})_write_ovpack(temp_ovpack_path,{- "victim/_._meta.json": json.dumps({"session_id": "victim"}),- "victim/messages.jsonl": '{"id":"msg_attacker","role":"user","parts":[{"type":"text","text":"forged"}],"created_at":"2026-01-01T00:00:00Z"}\n',+ "demo/": "",+ "demo/_._ovpack_manifest.json": json.dumps(manifest),+ "demo/notes.txt": "hello",+ "demo/empty/": "",},)fake_fs = FakeVikingFS()- with pytest.raises(- InvalidArgumentError,- match=r"ovpack import is not supported for scope: session",- ):+ with pytest.raises(InvalidArgumentError, match=r"entries do not match manifest") as exc_info:+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)++ assert exc_info.value.details["unexpected_directories"] == ["empty"]+ assert fake_fs.written_files == []+++async def test_import_ovpack_restores_session_without_vectorization(+ temp_ovpack_path: Path, request_ctx: RequestContext+):+ files = {+ ".meta.json": json.dumps({"session_id": "victim"}),+ "messages.jsonl": '{"id":"msg_1","role":"user","parts":[{"type":"text","text":"hi"}]}\n',+ }+ manifest = _manifest_for_files("victim", files)+ manifest["root"] = {+ "name": "victim",+ "uri": "viking://session/victim",+ "scope": "session",+ }+ _write_ovpack_with_manifest(+ temp_ovpack_path,+ "victim",+ files,+ manifest=manifest,+ )+ fake_fs = FakeVikingFS()++ result = await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://session", request_ctx)++ assert result == "viking://session/victim"+ assert fake_fs.written_files == [+ "viking://session/victim/.meta.json",+ "viking://session/victim/messages.jsonl",+ ]+ assert fake_fs.tree_calls == []++ invalid_fs = FakeVikingFS()+ with pytest.raises(InvalidArgumentError, match=r"source scope does not match target scope"):+ await import_ovpack(invalid_fs, str(temp_ovpack_path), "viking://resources", request_ctx)+ with pytest.raises(InvalidArgumentError, match=r"source path is incompatible"):await import_ovpack(- fake_fs, str(temp_ovpack_path), "viking://session/default", request_ctx, vectorize=False+ invalid_fs,+ str(temp_ovpack_path),+ "viking://session/victim",+ request_ctx,)+ assert invalid_fs.written_files == []+++async def test_import_ovpack_rejects_scope_mismatch(+ temp_ovpack_path: Path, request_ctx: RequestContext+):+ manifest = _manifest_for_files("demo", {"notes.txt": "hello"})+ _write_ovpack_with_manifest(temp_ovpack_path, "demo", {"notes.txt": "hello"}, manifest=manifest)+ fake_fs = FakeVikingFS()++ with pytest.raises(InvalidArgumentError, match=r"source scope does not match target scope"):+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://session", request_ctx)assert fake_fs.written_files == []+++async def test_import_top_level_scope_package_requires_root_target(+ temp_ovpack_path: Path, request_ctx: RequestContext+):+ manifest = _manifest_for_files("resources", {"README.md": "hello"})+ manifest["root"] = {+ "name": "resources",+ "uri": "viking://resources",+ "scope": "resources",+ }+ _write_ovpack_with_manifest(+ temp_ovpack_path,+ "resources",+ {"README.md": "hello"},+ manifest=manifest,+ )+ fake_fs = FakeVikingFS()++ with pytest.raises(InvalidArgumentError, match=r"must be imported to viking://"):+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)++ assert await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://", request_ctx) == (+ "viking://resources"+ )diff --git a/tests/server/conftest.py b/tests/server/conftest.pyindex 0bb79148c..22ca34a99 100644--- a/tests/server/conftest.py+++ b/tests/server/conftest.py@@ -32,6 +32,7 @@ from openviking_cli.utils.config.vlm_config import VLMConfigPROJECT_ROOT = Path(__file__).parent.parent.parentTEST_TMP_DIR = PROJECT_ROOT / "test_data" / "tmp_server"+SDK_ROOT_API_KEY = "test-root-api-key"# ---------------------------------------------------------------------------# Sample data@@ -51,7 +52,7 @@ This is a sample markdown document for server testing.def _install_fake_embedder(monkeypatch):"""Use an in-process fake embedder so server tests never hit external APIs."""- dimension = 2048+ dimension = 1024class FakeEmbedder(DenseEmbedderBase):def __init__(self):@@ -119,10 +120,16 @@ def upload_temp_dir(temp_dir: Path, monkeypatch) -> Path:monkeypatch.setattr("openviking.server.routers.resources.get_openviking_config",lambda: config,+ raising=False,)monkeypatch.setattr("openviking.server.routers.pack.get_openviking_config",lambda: config,+ raising=False,+ )+ monkeypatch.setattr(+ "openviking.server.temp_upload_store.get_openviking_config",+ lambda: config,)return temp_dir@@ -195,7 +202,7 @@ async def running_server(temp_dir: Path, monkeypatch):await svc.initialize()svc.viking_fs.query_embedder = fake_embedder_cls()- config = ServerConfig()+ config = ServerConfig(root_api_key=SDK_ROOT_API_KEY)fastapi_app = create_app(config=config, service=svc)# Find a free port@@ -217,6 +224,13 @@ async def running_server(temp_dir: Path, monkeypatch):except Exception:time.sleep(0.1)+ for _ in range(50):+ if getattr(fastapi_app.state, "api_key_manager", None) is not None:+ break+ time.sleep(0.1)+ else:+ raise RuntimeError("APIKeyManager did not initialize for SDK server test")+yield port, svcserver.should_exit = Truediff --git a/tests/server/ovpack_test_helpers.py b/tests/server/ovpack_test_helpers.pynew file mode 100644index 000000000..f9c4b15f4--- /dev/null+++ b/tests/server/ovpack_test_helpers.py@@ -0,0 +1,62 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++"""OVPack fixtures for server tests."""++import hashlib+import io+import json+import zipfile+++def _content_sha256(entries: list[dict[str, object]]) -> str:+ payload = json.dumps(+ entries,+ ensure_ascii=False,+ sort_keys=True,+ separators=(",", ":"),+ ).encode("utf-8")+ return hashlib.sha256(payload).hexdigest()+++def build_ovpack_bytes(+ root_name: str = "pkg",+ files: dict[str, bytes] | None = None,+) -> bytes:+ files = files or {"content.md": b"# Demo\n"}+ manifest_entries: list[dict[str, object]] = [{"path": "", "kind": "directory"}]+ content_entries: list[dict[str, object]] = []++ for rel_path, content in sorted(files.items()):+ file_sha256 = hashlib.sha256(content).hexdigest()+ file_entry = {+ "path": rel_path,+ "kind": "file",+ "size": len(content),+ "sha256": file_sha256,+ }+ manifest_entries.append(file_entry)+ content_entries.append(+ {+ "path": rel_path,+ "size": file_entry["size"],+ "sha256": file_entry["sha256"],+ }+ )++ manifest = {+ "kind": "openviking.ovpack",+ "format_version": 2,+ "root": {"name": root_name},+ "entries": manifest_entries,+ "content_sha256": _content_sha256(content_entries),+ "vectors": {},+ }++ buffer = io.BytesIO()+ with zipfile.ZipFile(buffer, "w") as zf:+ zf.writestr(f"{root_name}/", "")+ zf.writestr(f"{root_name}/_._ovpack_manifest.json", json.dumps(manifest))+ for rel_path, content in files.items():+ zf.writestr(f"{root_name}/{rel_path}", content)+ return buffer.getvalue()diff --git a/tests/server/test_api_local_input_security.py b/tests/server/test_api_local_input_security.pyindex f3c98914c..fffcc8292 100644--- a/tests/server/test_api_local_input_security.py+++ b/tests/server/test_api_local_input_security.py@@ -3,9 +3,7 @@"""Security tests for HTTP server local input handling."""-import ioimport threading-import zipfilefrom http.server import BaseHTTPRequestHandler, HTTPServerimport httpx@@ -14,6 +12,12 @@ import pytestfrom openviking.parse.parsers.html import URLTypeDetectorfrom openviking.utils.network_guard import ensure_public_remote_targetfrom openviking_cli.exceptions import PermissionDeniedError+from tests.server.ovpack_test_helpers import build_ovpack_bytes+++def _allow_admin_api_in_dev_mode(client: httpx.AsyncClient) -> None:+ # Admin routes require the app to have an API key manager, even in dev-mode tests.+ client._transport.app.state.api_key_manager = object()async def test_add_skill_accepts_temp_uploaded_file(@@ -57,7 +61,9 @@ async def test_add_skill_rejects_legacy_temp_path_field(client: httpx.AsyncClien"/api/v1/skills",json={"temp_path": "upload_skill.md"},)- assert resp.status_code == 422+ assert resp.status_code == 400+ body = resp.json()+ assert body["error"]["code"] == "INVALID_ARGUMENT"async def test_add_skill_accepts_raw_skill_content(client: httpx.AsyncClient):@@ -79,14 +85,6 @@ description: inlineassert body["result"]["uri"].startswith("viking://agent/default/skills/")-def _build_ovpack_bytes() -> bytes:- buffer = io.BytesIO()- with zipfile.ZipFile(buffer, "w") as zf:- zf.writestr("pkg/_._meta.json", '{"uri": "viking://resources/pkg"}')- zf.writestr("pkg/content.md", "# Demo\n")- return buffer.getvalue()--@pytest.fixturedef loopback_http_url():body = b"<html><body>loopback secret</body></html>"@@ -125,15 +123,15 @@ async def test_import_ovpack_accepts_temp_uploaded_file(client: httpx.AsyncClient,upload_temp_dir,):+ _allow_admin_api_in_dev_mode(client)ovpack_file = upload_temp_dir / "demo.ovpack"- ovpack_file.write_bytes(_build_ovpack_bytes())+ ovpack_file.write_bytes(build_ovpack_bytes())resp = await client.post("/api/v1/pack/import",json={"temp_file_id": ovpack_file.name,"parent": "viking://resources/imported",- "vectorize": False,},)assert resp.status_code == 200@@ -142,16 +140,51 @@ async def test_import_ovpack_accepts_temp_uploaded_file(assert body["result"]["uri"].startswith("viking://resources/imported/")+async def test_import_ovpack_conflict_returns_structured_conflict(+ client: httpx.AsyncClient,+ upload_temp_dir,+):+ _allow_admin_api_in_dev_mode(client)+ ovpack_file = upload_temp_dir / "demo_conflict.ovpack"+ ovpack_file.write_bytes(build_ovpack_bytes())++ first = await client.post(+ "/api/v1/pack/import",+ json={+ "temp_file_id": ovpack_file.name,+ "parent": "viking://resources/imported",+ },+ )+ assert first.status_code == 200++ ovpack_file.write_bytes(build_ovpack_bytes())+ resp = await client.post(+ "/api/v1/pack/import",+ json={+ "temp_file_id": ovpack_file.name,+ "parent": "viking://resources/imported",+ },+ )++ assert resp.status_code == 409+ body = resp.json()+ assert body["status"] == "error"+ assert body["error"]["code"] == "CONFLICT"+ assert "Use on_conflict='overwrite'" in body["error"]["message"]+ assert body["error"]["details"]["resource"] == "viking://resources/imported/pkg"++async def test_import_ovpack_rejects_direct_file_path_field(client: httpx.AsyncClient):resp = await client.post("/api/v1/pack/import",json={"file_path": "/tmp/demo.ovpack","parent": "viking://resources/imported",- "vectorize": False,},)- assert resp.status_code == 422+ assert resp.status_code == 400+ body = resp.json()+ assert body["error"]["code"] == "INVALID_ARGUMENT"async def test_import_ovpack_rejects_legacy_temp_path_field(client: httpx.AsyncClient):@@ -160,10 +193,29 @@ async def test_import_ovpack_rejects_legacy_temp_path_field(client: httpx.AsyncCjson={"temp_path": "upload_pack.ovpack","parent": "viking://resources/imported",+ },+ )+ assert resp.status_code == 400+ body = resp.json()+ assert body["error"]["code"] == "INVALID_ARGUMENT"+++async def test_import_ovpack_rejects_removed_fields(client: httpx.AsyncClient):+ resp = await client.post(+ "/api/v1/pack/import",+ json={+ "temp_file_id": "demo.ovpack",+ "parent": "viking://resources/imported","vectorize": False,+ "force": True,},)- assert resp.status_code == 422+ assert resp.status_code == 400+ body = resp.json()+ assert body["error"]["code"] == "INVALID_ARGUMENT"+ validation_errors = body["error"]["details"]["validation_errors"]+ assert any("vectorize" in error["loc"] for error in validation_errors)+ assert any("force" in error["loc"] for error in validation_errors)async def test_import_ovpack_rejects_forged_temp_file_id(@@ -171,14 +223,13 @@ async def test_import_ovpack_rejects_forged_temp_file_id(upload_temp_dir,):outside_file = upload_temp_dir.parent / "outside.ovpack"- outside_file.write_bytes(_build_ovpack_bytes())+ outside_file.write_bytes(build_ovpack_bytes())resp = await client.post("/api/v1/pack/import",json={"temp_file_id": "../outside.ovpack","parent": "viking://resources/imported",- "vectorize": False,},)assert resp.status_code == 403@@ -192,7 +243,9 @@ async def test_add_resource_rejects_legacy_temp_path_field(client: httpx.AsyncCl"/api/v1/resources",json={"temp_path": "upload_resource.md", "reason": "legacy field"},)- assert resp.status_code == 422+ assert resp.status_code == 400+ body = resp.json()+ assert body["error"]["code"] == "INVALID_ARGUMENT"async def test_add_resource_rejects_loopback_remote_url(client: httpx.AsyncClient):diff --git a/tests/server/test_http_client_sdk.py b/tests/server/test_http_client_sdk.pyindex 9d17a17e4..0d97e1690 100644--- a/tests/server/test_http_client_sdk.py+++ b/tests/server/test_http_client_sdk.py@@ -4,8 +4,6 @@"""SDK tests using AsyncHTTPClient against a real uvicorn server."""import asyncio-import io-import zipfileimport httpximport pytest@@ -13,7 +11,8 @@ import pytest_asynciofrom openviking_cli.client.http import AsyncHTTPClientfrom openviking_cli.exceptions import ConflictError, FailedPreconditionError, ProcessingError-from tests.server.conftest import SAMPLE_MD_CONTENT, TEST_TMP_DIR+from tests.server.conftest import SAMPLE_MD_CONTENT, SDK_ROOT_API_KEY, TEST_TMP_DIR+from tests.server.ovpack_test_helpers import build_ovpack_bytes@pytest_asyncio.fixture()@@ -22,6 +21,9 @@ async def http_client(running_server):port, svc = running_serverclient = AsyncHTTPClient(url=f"http://127.0.0.1:{port}",+ api_key=SDK_ROOT_API_KEY,+ account="default",+ user="sdk_test_user",)await client.initialize()yield client, svc@@ -114,25 +116,16 @@ description: SDK localhost upload testassert result["uri"].startswith("viking://agent/default/skills/")-def _build_ovpack_bytes() -> bytes:- buffer = io.BytesIO()- with zipfile.ZipFile(buffer, "w") as zf:- zf.writestr("pkg/_._meta.json", '{"uri": "viking://resources/pkg"}')- zf.writestr("pkg/content.md", "# Demo\n")- return buffer.getvalue()--async def test_sdk_import_ovpack_from_local_file(http_client):client, _ = http_clientf = TEST_TMP_DIR / "sdk_import.ovpack"f.parent.mkdir(parents=True, exist_ok=True)- f.write_bytes(_build_ovpack_bytes())+ f.write_bytes(build_ovpack_bytes())uri = await client.import_ovpack(str(f),parent="viking://resources/imported/",- force=True,- vectorize=False,+ on_conflict="overwrite",)assert uri.startswith("viking://resources/imported/")