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/add resource processing mode (#3566)
Jiahui Zhou5d1ba45be49e
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex e2bd1ebb5..87ad102da 100644--- a/crates/ov_cli/src/client.rs+++ b/crates/ov_cli/src/client.rs@@ -31,6 +31,9 @@ fn compact_request_body(body: &mut Value) {return !map.is_empty();}}+ if key == "processing_mode" {+ return value != "semantic_and_vectors";+ }true});}@@ -616,6 +619,7 @@ impl HttpClient {exclude: Option<String>,directly_upload_media: bool,watch_interval: f64,+ processing_mode: String,resource_args: Option<Map<String, Value>>,show_progress: bool,verbose: bool,@@ -678,6 +682,7 @@ impl HttpClient {"exclude": exclude,"directly_upload_media": directly_upload_media,"watch_interval": watch_interval,+ "processing_mode": processing_mode.as_str(),"args": args.clone(),}));@@ -713,6 +718,7 @@ impl HttpClient {"exclude": exclude,"directly_upload_media": directly_upload_media,"watch_interval": watch_interval,+ "processing_mode": processing_mode.as_str(),"args": args.clone(),}));@@ -736,6 +742,7 @@ impl HttpClient {"exclude": exclude,"directly_upload_media": directly_upload_media,"watch_interval": watch_interval,+ "processing_mode": processing_mode.as_str(),"args": args.clone(),}));@@ -756,6 +763,7 @@ impl HttpClient {"exclude": exclude,"directly_upload_media": directly_upload_media,"watch_interval": watch_interval,+ "processing_mode": processing_mode.as_str(),"args": args,}));@@ -1752,6 +1760,26 @@ mod tests {assert!(body.as_object().unwrap().contains_key("args"));}+ #[test]+ fn compact_request_body_drops_default_processing_mode_for_legacy_servers() {+ let mut body = json!({+ "path": "https://example.com/guide.md",+ "processing_mode": "semantic_and_vectors",+ });+ super::compact_request_body(&mut body);+ assert!(!body.as_object().unwrap().contains_key("processing_mode"));+ }++ #[test]+ fn compact_request_body_keeps_non_default_processing_mode() {+ let mut body = json!({+ "path": "https://example.com/guide.md",+ "processing_mode": "vectors_only",+ });+ super::compact_request_body(&mut body);+ assert_eq!(body["processing_mode"], "vectors_only");+ }+#[test]fn timeout_config_calculation() {let config = TimeoutConfig::new(60, 2.0);diff --git a/crates/ov_cli/src/commands/resources.rs b/crates/ov_cli/src/commands/resources.rsindex 3520827a2..ccc777c0f 100644--- a/crates/ov_cli/src/commands/resources.rs+++ b/crates/ov_cli/src/commands/resources.rs@@ -19,6 +19,7 @@ pub async fn add_resource(exclude: Option<String>,directly_upload_media: bool,watch_interval: f64,+ processing_mode: String,resource_args: Option<Map<String, Value>>,format: OutputFormat,compact: bool,@@ -41,6 +42,7 @@ pub async fn add_resource(exclude,directly_upload_media,watch_interval,+ processing_mode,resource_args,show_progress,verbose,diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rsindex 8ff7447f0..2947d5e11 100644--- a/crates/ov_cli/src/handlers.rs+++ b/crates/ov_cli/src/handlers.rs@@ -28,6 +28,7 @@ pub async fn handle_add_resource(exclude: Option<String>,no_directly_upload_media: bool,watch_interval: f64,+ processing_mode: String,resource_args: Option<String>,ctx: CliContext,) -> Result<()> {@@ -108,6 +109,7 @@ pub async fn handle_add_resource(effective_exclude,directly_upload_media,watch_interval,+ processing_mode,add_resource_args,ctx.output_format,ctx.compact,diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 7178d4801..43ad4adbd 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -349,6 +349,14 @@ enum Commands {help_heading = "Advanced options")]watch_interval: f64,+ /// Resource processing mode+ #[arg(+ long = "processing-mode",+ default_value = "semantic_and_vectors",+ value_parser = ["semantic_and_vectors", "vectors_only"],+ help_heading = "Advanced options"+ )]+ processing_mode: String,/// Parser-specific import options, e.g. --args feishu_access_token:u-xxx#[arg(long = "args")]resource_args: Option<String>,@@ -2766,6 +2774,7 @@ async fn main() {exclude,no_directly_upload_media,watch_interval,+ processing_mode,resource_args,upload_options,} => {@@ -2786,6 +2795,7 @@ async fn main() {exclude,no_directly_upload_media,watch_interval,+ processing_mode,resource_args,ctx,)diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.mdindex 301b4fbc9..d0a2ccb64 100644--- a/docs/en/api/02-resources.md+++ b/docs/en/api/02-resources.md@@ -138,16 +138,17 @@ Add a resource to the knowledge base. The SDK supports local files/directories,#### 1. API Implementation Overview-This endpoint is the core entry point for resource management, supporting adding resources from various sources with optional waiting for semantic processing completion.+This endpoint is the core entry point for resource management, supporting adding resources from various sources with optional waiting for semantic processing and vectorization completion.**Processing Flow**:1. Identify and validate the resource source (URL or uploaded temporary file)2. Resolve the target URI3. Call the corresponding Parser to parse content4. Build the directory tree and write to AGFS-5. Wait for semantic processing completion when `wait=true`; with `wait=false`, return a `task_id` for queue tracking-6. If `reason` is non-empty, append it to the fixed resource reason session and commit through the normal memory extraction pipeline so suitable user memories can reference the resource URI-7. Set up scheduled update task if `watch_interval` is specified+5. Run post-ingest processing according to `processing_mode`: `semantic_and_vectors` generates semantic artifacts and vectors; `vectors_only` skips semantic understanding and only enqueues file vectorization+6. Wait for semantic processing/vectorization completion when `wait=true`; with `wait=false`, return a `task_id` for queue tracking+7. If `reason` is non-empty, append it to the fixed resource reason session and commit through the normal memory extraction pipeline so suitable user memories can reference the resource URI+8. Set up scheduled update task if `watch_interval` is specified**Code Entry Points**:- `openviking/client/local.py:LocalClient.add_resource` - SDK entry (embedded)@@ -179,6 +180,7 @@ This endpoint is the core entry point for resource management, supporting adding| preserve_structure | bool | No | None | Whether to preserve directory structure || args | object | No | `{}` | Parser-specific import options forwarded to the source parser/accessor. E.g. `args.site=true/false` forces/opts out of whole-site (sitemap/RSS) ingestion, `args.max_pages` etc. override the `webfeed` config; the recursive web crawler accepts `args.depth`, `args.max_pages`, `args.include_paths`, `args.exclude_paths`, `args.allow_external_links`, `args.skip_download_links`; Feishu user-token imports pass `args.feishu_access_token`. Core `add_resource` fields such as `path`, `to`, `watch_interval`, `include`, and `exclude` are not allowed inside `args` || watch_interval | float | No | 0 | Scheduled update interval (minutes). >0 creates a task for a re-readable URL/sitemap/RSS source; uploaded `temp_file_id` content is a one-time snapshot and must be re-added when it changes. <=0 cancels a task; explicit `to` wins, otherwise binds to the imported `root_uri` |+| processing_mode | string | No | `semantic_and_vectors` | Post-ingest processing mode. `semantic_and_vectors` is the normal flow: generate semantic artifacts (`.abstract.md`, `.overview.md`) and vectors. `vectors_only` skips semantic understanding/VLM summarization and only vectorizes current resource files || telemetry | TelemetryRequest | No | False | Whether to return telemetry data |**Additional Notes**:@@ -193,6 +195,8 @@ This endpoint is the core entry point for resource management, supporting adding- Memory generated from `reason` is extracted through the same pipeline as `session.commit`. It uses `reason`, the resource URI, available source name, and available directory abstract; it does not inspect or expand the full resource content. OpenViking writes to existing memory types such as `entities`, `events`, or `preferences`, not a dedicated resource memory directory.- When deleting a resource, OpenViking scans the self or peer memories targeted by the current context before deletion, removes the matching resource URI and content introduced by that `reason`, and refreshes the semantic index for the affected memories.- Other sources with `wait=false` finish source parsing, target resolution, and AGFS writes before returning. Only semantic and embedding queues continue asynchronously.+- `processing_mode=vectors_only` does not call the VLM semantic-understanding stage and does not generate or refresh `.abstract.md` / `.overview.md`. For existing targets, it preserves existing semantic artifacts and existing semantic vectors. It still updates the resource tree, vectorizes current non-hidden files when `build_index=true`, and removes detail vectors for files deleted during refresh.+- `processing_mode` belongs to `add_resource`. The admin `reindex` API/CLI continues to use `mode` (`vectors_only`, `semantic_and_vectors`, `prune_orphans`) for maintenance operations on already-ingested data.- When `watch_interval > 0`, the watch task binds to `to` if provided; otherwise it binds to the `root_uri` returned by this import. If no stable `root_uri` is available, the request fails and asks for an explicit `to`.- Feishu/Lark app-token imports do not pass `args.feishu_access_token`. OpenViking keeps the existing app credential flow and the SDK obtains an app/tenant token from `app_id` and `app_secret`. This mode supports both one-time imports and `watch_interval > 0`.- Feishu/Lark one-time user-token imports pass `args={"feishu_access_token": "u-..."}` with `watch_interval <= 0`. OpenViking uses that user token only for the current import and does not store it.@@ -222,6 +226,17 @@ curl -X POST http://localhost:1933/api/v1/resources \"wait": true}'+# Add a resource and only build vectors, without VLM semantic understanding+curl -X POST http://localhost:1933/api/v1/resources \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "path": "https://example.com/guide.md",+ "to": "viking://resources/guide",+ "processing_mode": "vectors_only",+ "wait": true+ }'+# Recursively crawl a site: expand along same-host links; depth bounds# how many levels, max_pages bounds how many pages are collectedcurl -X POST http://localhost:1933/api/v1/resources \diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex b20ffc7e4..929d69b52 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -139,7 +139,7 @@ Once connected, OpenViking exposes 16 tools:| `read` | Read one or more `viking://` URIs | `uris` (single string or array) || `list` | List entries under a `viking://` directory | `uri`, `recursive` (optional) || `remember` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) |-| `add_resource` | Add a local file or URL as a resource (local files trigger a progressive upload flow) | `path`, `temp_file_id` (optional), `description` (optional), `watch_interval` (optional, minutes — auto-refresh cadence for remote URLs), `to` (optional, target `viking://resources/...` URI; if omitted when `watch_interval > 0`, the watch auto-binds to the resource's created URI), `args` (optional parser-specific options, such as `{"feishu_access_token":"u-..."}` for one-time Feishu user-token imports, or `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}` for Feishu user-token watches) |+| `add_resource` | Add a local file or URL as a resource (local files trigger a progressive upload flow) | `path`, `temp_file_id` (optional), `description` (optional), `watch_interval` (optional, minutes — auto-refresh cadence for remote URLs), `processing_mode` (optional: `semantic_and_vectors` default, or `vectors_only` to skip VLM semantic understanding and only vectorize current files), `to` (optional, target `viking://resources/...` URI; if omitted when `watch_interval > 0`, the watch auto-binds to the resource's created URI), `args` (optional parser-specific options, such as `{"feishu_access_token":"u-..."}` for one-time Feishu user-token imports, or `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}` for Feishu user-token watches) || `list_watches` | List watch tasks (auto-refresh subscriptions) visible to the current agent. Each entry shows target URI, refresh interval (minutes), active/paused status, and next scheduled execution time | none || `cancel_watch` | Cancel (delete) a watch task by its target URI. To change the cadence or pause temporarily, cancel and re-add with a new `watch_interval` | `to_uri` (must match the watch task's `to` value, e.g. `viking://resources/...`) || `grep` | Regex content search across `viking://` files | `uri`, `pattern` (string or array), `case_insensitive`, `node_limit` |@@ -154,6 +154,8 @@ Once connected, OpenViking exposes 16 tools:> Feishu/Lark imports without `args.feishu_access_token` keep the existing app/tenant-token behavior and can be watched. Feishu/Lark one-time user-token imports pass only `args.feishu_access_token`; Feishu/Lark user-token watches must also pass `args.feishu_refresh_token` and require the same Feishu app credentials configured on the OpenViking server.+> `processing_mode=vectors_only` skips the VLM semantic-understanding stage. It does not generate or refresh `.abstract.md` / `.overview.md`; it only vectorizes current non-hidden resource files, preserving any older semantic artifacts that already exist.+### Adding local-file resources (single-step upload)The `add_resource` tool accepts both **remote URLs** and **local file paths**, handled differently:diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.mdindex f3e0d8064..f2338a5e0 100644--- a/docs/zh/api/02-resources.md+++ b/docs/zh/api/02-resources.md@@ -138,9 +138,10 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector2. 解析目标 URI3. 调用对应 Parser 解析内容4. 构建目录树并写入 AGFS-5. `wait=true` 时等待语义处理完成;`wait=false` 时返回 `task_id` 用于队列跟踪-6. 如果 `reason` 非空,将其追加到固定的资源 reason session 并 commit,复用常规记忆抽取链路,让合适的用户记忆引用该资源 URI-7. 如指定 `--watch-interval`,设置定时更新任务+5. 按 `processing_mode` 执行入库后的处理:`semantic_and_vectors` 生成语义产物和向量;`vectors_only` 跳过语义理解,只提交文件向量化+6. `wait=true` 时等待语义处理/向量化完成;`wait=false` 时返回 `task_id` 用于队列跟踪+7. 如果 `reason` 非空,将其追加到固定的资源 reason session 并 commit,复用常规记忆抽取链路,让合适的用户记忆引用该资源 URI+8. 如指定 `--watch-interval`,设置定时更新任务**代码入口**:- `openviking/client/local.py:LocalClient.add_resource` - SDK 入口(嵌入式)@@ -172,6 +173,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector| preserve_structure | bool | 否 | None | 是否保留目录结构 || args | object | 否 | `{}` | 传给特定 parser/accessor 的导入参数。例如 `args.site=true/false` 强制/禁用整站(sitemap/RSS)导入,`args.max_pages` 等可覆盖 `webfeed` 配置;递归网页爬虫支持 `args.depth`、`args.max_pages`、`args.include_paths`、`args.exclude_paths`、`args.allow_external_links`、`args.skip_download_links`;飞书用户 token 导入传 `args.feishu_access_token`。`path`、`to`、`watch_interval`、`include`、`exclude` 等 `add_resource` 核心字段不能放入 `args` || watch_interval | float | 否 | 0 | 定时更新间隔(分钟)。>0 为 URL/sitemap/RSS 等可重新读取的来源创建任务;通过 `temp_file_id` 上传的内容是一次性快照,变化后需重新添加。≤0 取消任务;显式 `to` 优先,否则绑定本次导入的 `root_uri` |+| processing_mode | string | 否 | `semantic_and_vectors` | 入库后的处理模式。`semantic_and_vectors` 是默认流程:生成语义产物(`.abstract.md`、`.overview.md`)并生成向量。`vectors_only` 跳过语义理解/VLM 总结,只对当前资源文件生成向量 || telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |**补充说明**:@@ -184,6 +186,8 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector- `reason` 触发的记忆生成复用 `session.commit` 的抽取链路,只使用 `reason`、资源 URI、可用的资源名称和目录摘要,不会读取或展开完整资源正文;系统会写入 `entities`、`events`、`preferences` 等已有记忆类型,不创建独立的资源记忆目录。- 删除资源时,系统会在删除前扫描本次上下文对应的 self 或 peer 记忆中的 `resource_refs`,清理对应资源 URI 和由该 `reason` 引入的内容,并重新刷新相关记忆的语义索引。- 其他来源在 `wait=false` 时会在响应前完成来源解析、目标解析和 AGFS 写入,仅 semantic 与 embedding 队列继续异步处理。+- `processing_mode=vectors_only` 不调用 VLM 语义理解阶段,也不会生成或刷新 `.abstract.md` / `.overview.md`。对已存在目标,它会保留旧的语义产物和旧的语义向量;仍会更新资源树,在 `build_index=true` 时向量化当前非隐藏文件,并清理由本次刷新删除的文件 detail 向量。+- `processing_mode` 只属于 `add_resource`。管理员维护已有数据时,`reindex` API/CLI 仍使用 `mode`(`vectors_only`、`semantic_and_vectors`、`prune_orphans`)。- `watch_interval > 0` 时,如果指定了 `to`,监控任务绑定该目标;如果未指定 `to`,监控任务绑定本次导入返回的 `root_uri`。如果无法得到稳定 `root_uri`,请求会报错并要求显式传 `to`。- 飞书/Lark 应用 token 导入不传 `args.feishu_access_token`。OpenViking 保持原有应用凭证流程,由 SDK 使用 `app_id` 和 `app_secret` 自动获取 app/tenant token。该模式支持一次性导入和 `watch_interval > 0`。- 飞书/Lark 一次性用户 token 导入通过 `args={"feishu_access_token": "u-..."}` 传入,且 `watch_interval <= 0`。OpenViking 只在本次导入使用该用户 token,不保存。@@ -213,6 +217,17 @@ curl -X POST http://localhost:1933/api/v1/resources \"wait": true}'+# 添加资源但只生成向量,不走 VLM 语义理解+curl -X POST http://localhost:1933/api/v1/resources \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "path": "https://example.com/guide.md",+ "to": "viking://resources/guide",+ "processing_mode": "vectors_only",+ "wait": true+ }'+# 递归抓取网页:从入口页沿同域链接展开,depth 控制层数,max_pages 限制页数curl -X POST http://localhost:1933/api/v1/resources \-H "Content-Type: application/json" \diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.mdindex 2fad231da..0cf549f44 100644--- a/docs/zh/guides/06-mcp-integration.md+++ b/docs/zh/guides/06-mcp-integration.md@@ -131,7 +131,7 @@ claude mcp add --transport http openviking \| `read` | 读取一个或多个 `viking://` URI 的内容 | `uris`(单个字符串或数组) || `list` | 列出 `viking://` 目录下的条目 | `uri`, `recursive`(可选) || `remember` | 存储消息到长期记忆(触发记忆提取) | `messages`(`{role, content}` 列表) |-| `add_resource` | 添加本地文件或 URL 作为资源(本地文件触发渐进式上传流) | `path`, `temp_file_id`(可选), `description`(可选), `watch_interval`(可选,分钟数 — 远程 URL 的自动刷新周期), `to`(可选,目标 `viking://resources/...` URI;`watch_interval > 0` 时若省略 `to`,watch 将自动绑定到本次 add 创建的资源 URI), `args`(可选,特定 parser 参数,例如飞书一次性用户 token 导入使用 `{"feishu_access_token":"u-..."}`,飞书用户 token watch 使用 `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}`) |+| `add_resource` | 添加本地文件或 URL 作为资源(本地文件触发渐进式上传流) | `path`, `temp_file_id`(可选), `description`(可选), `watch_interval`(可选,分钟数 — 远程 URL 的自动刷新周期), `processing_mode`(可选:默认 `semantic_and_vectors`;传 `vectors_only` 时跳过 VLM 语义理解,只向量化当前文件), `to`(可选,目标 `viking://resources/...` URI;`watch_interval > 0` 时若省略 `to`,watch 将自动绑定到本次 add 创建的资源 URI), `args`(可选,特定 parser 参数,例如飞书一次性用户 token 导入使用 `{"feishu_access_token":"u-..."}`,飞书用户 token watch 使用 `{"feishu_access_token":"u-...","feishu_refresh_token":"r-..."}`) || `list_watches` | 列出当前 Agent 可见的 watch 任务(自动刷新订阅),每行显示目标 URI、刷新间隔(分钟)、active/paused 状态以及下一次调度时间 | 无 || `cancel_watch` | 按目标 URI 取消(删除)watch 任务。若需调整刷新周期或临时暂停,请取消后使用新的 `watch_interval` 重新添加 | `to_uri`(必须匹配 watch 任务的 `to` 值,例如 `viking://resources/...`) || `grep` | 在 `viking://` 文件中进行正则内容搜索 | `uri`, `pattern`(字符串或数组), `case_insensitive`, `node_limit` |@@ -146,6 +146,8 @@ claude mcp add --transport http openviking \> 未传 `args.feishu_access_token` 的飞书/Lark 导入保持现有应用/tenant token 行为,也支持 watch。飞书/Lark 一次性用户 token 导入只传 `args.feishu_access_token`;飞书/Lark 用户 token watch 还必须传 `args.feishu_refresh_token`,并要求 OpenViking 服务端配置同一个飞书应用凭证。+> `processing_mode=vectors_only` 会跳过 VLM 语义理解阶段,不生成或刷新 `.abstract.md` / `.overview.md`;它只向量化当前非隐藏资源文件,并保留已存在的旧语义产物。+### 添加本地文件资源(单步上传)`add_resource` 工具同时接受**远程 URL** 和**本地文件路径**。两者的处理路径不同:diff --git a/openviking/async_client.py b/openviking/async_client.pyindex ae71027bd..19b75be32 100644--- a/openviking/async_client.py+++ b/openviking/async_client.py@@ -329,6 +329,7 @@ class AsyncOpenViking:watch_interval: float = 0,args: Optional[Dict[str, Any]] = None,telemetry: TelemetryRequest = False,+ processing_mode: str = "semantic_and_vectors",**kwargs,) -> Dict[str, Any]:"""@@ -345,6 +346,8 @@ class AsyncOpenViking:parent: Target parent URI (must already exist).build_index: Whether to build vector index immediately (default: True).summarize: Whether to generate summary (default: False).+ processing_mode: "semantic_and_vectors" for normal semantic processing,+ or "vectors_only" to only build vector indexes.watch_interval: Auto-refresh interval in minutes (>0 enables a watch).On a sitemap/feed URL this keeps the whole site refreshed.args: Parser/accessor-specific options (e.g. ``site``, ``max_pages``).@@ -365,6 +368,7 @@ class AsyncOpenViking:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,telemetry=telemetry,watch_interval=watch_interval,args=args,diff --git a/openviking/client/local.py b/openviking/client/local.pyindex 0233b28d0..ae56c5c8e 100644--- a/openviking/client/local.py+++ b/openviking/client/local.py@@ -138,6 +138,7 @@ class LocalClient(BaseClient):telemetry: TelemetryRequest = False,watch_interval: float = 0,args: Optional[Dict[str, Any]] = None,+ processing_mode: str = "semantic_and_vectors",**kwargs,) -> Dict[str, Any]:"""Add resource to OpenViking."""@@ -158,6 +159,7 @@ class LocalClient(BaseClient):timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,watch_interval=watch_interval,args=args,**kwargs,diff --git a/openviking/resource/processing_mode.py b/openviking/resource/processing_mode.pynew file mode 100644index 000000000..b169bfb42--- /dev/null+++ b/openviking/resource/processing_mode.py@@ -0,0 +1,20 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Resource post-ingest processing modes."""++from typing import Literal++SEMANTIC_AND_VECTORS = "semantic_and_vectors"+VECTORS_ONLY = "vectors_only"++ProcessingMode = Literal["semantic_and_vectors", "vectors_only"]+DEFAULT_PROCESSING_MODE: ProcessingMode = SEMANTIC_AND_VECTORS+SUPPORTED_PROCESSING_MODES = frozenset({SEMANTIC_AND_VECTORS, VECTORS_ONLY})+++def normalize_processing_mode(value: str | None) -> ProcessingMode:+ mode = value or DEFAULT_PROCESSING_MODE+ if mode not in SUPPORTED_PROCESSING_MODES:+ supported = ", ".join(sorted(SUPPORTED_PROCESSING_MODES))+ raise ValueError(f"Invalid processing_mode '{mode}'. Supported values: {supported}")+ return mode # type: ignore[return-value]diff --git a/openviking/resource/watch_manager.py b/openviking/resource/watch_manager.pyindex de6a9b499..ec4a93db8 100644--- a/openviking/resource/watch_manager.py+++ b/openviking/resource/watch_manager.py@@ -15,6 +15,7 @@ from typing import Any, Awaitable, Callable, Dict, List, Optionalfrom pydantic import BaseModel, Field+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingModefrom openviking.resource.watch_storage import (WATCH_TASK_STORAGE_BAK_URI,WATCH_TASK_STORAGE_TMP_URI,@@ -67,6 +68,10 @@ class WatchTask(BaseModel):watch_interval: float = Field(default=60.0, description="Monitoring interval in minutes")build_index: bool = Field(default=True, description="Whether to build vector index")summarize: bool = Field(default=False, description="Whether to generate summary")+ processing_mode: ProcessingMode = Field(+ default=DEFAULT_PROCESSING_MODE,+ description="Post-ingest processing mode for scheduled add_resource runs",+ )processor_kwargs: Dict[str, Any] = Field(default_factory=dict, description="Extra kwargs forwarded to processor")@@ -97,6 +102,7 @@ class WatchTask(BaseModel):"watch_interval": self.watch_interval,"build_index": self.build_index,"summarize": self.summarize,+ "processing_mode": self.processing_mode,"processor_kwargs": self.processor_kwargs,"created_at": self.created_at.isoformat() if self.created_at else None,"last_execution_time": self.last_execution_time.isoformat()@@ -384,6 +390,7 @@ class WatchManager:watch_interval: float = 60.0,build_index: bool = True,summarize: bool = False,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,processor_kwargs: Optional[Dict[str, Any]] = None,auth_state: Optional[Dict[str, Any]] = None,) -> WatchTask:@@ -427,6 +434,7 @@ class WatchManager:watch_interval=watch_interval,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,processor_kwargs=processor_kwargs or {},auth_state=auth_state,account_id=account_id,@@ -461,6 +469,7 @@ class WatchManager:watch_interval: Optional[float] = None,build_index: Optional[bool] = None,summarize: Optional[bool] = None,+ processing_mode: Optional[ProcessingMode] = None,processor_kwargs: Optional[Dict[str, Any]] = None,auth_state: Any = _UNSET,is_active: Optional[bool] = None,@@ -531,6 +540,8 @@ class WatchManager:task.build_index = build_indexif summarize is not None:task.summarize = summarize+ if processing_mode is not None:+ task.processing_mode = processing_modeif processor_kwargs is not None:task.processor_kwargs = processor_kwargsif auth_state is not _UNSET:diff --git a/openviking/resource/watch_scheduler.py b/openviking/resource/watch_scheduler.pyindex d3fa5e063..8e7e3aca5 100644--- a/openviking/resource/watch_scheduler.py+++ b/openviking/resource/watch_scheduler.py@@ -291,6 +291,7 @@ class WatchScheduler:instruction=task.instruction,build_index=getattr(task, "build_index", True),summarize=getattr(task, "summarize", False),+ processing_mode=getattr(task, "processing_mode", "semantic_and_vectors"),watch_interval=task.watch_interval,**processor_kwargs,)diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pyindex 88fb8a7d4..f9650f661 100644--- a/openviking/server/mcp_endpoint.py+++ b/openviking/server/mcp_endpoint.py@@ -38,6 +38,7 @@ from openviking.parse.parsers.code.ast.code_tools import (outline_file,search_symbols,)+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingModefrom openviking.retrieve.type_quota_recall import (DEFAULT_MAX_CHARS,DEFAULT_MIN_SCORE,@@ -549,6 +550,7 @@ async def add_resource(temp_file_id: str = "",description: str = "",watch_interval: float = 0,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,to: str = "",parent: str = "",args: Optional[dict[str, Any]] = None,@@ -570,6 +572,8 @@ async def add_resource(watch_interval: Auto-refresh cadence in minutes. 0 = no watch. Prefer >=1440 (24h)unless the source changes faster — every refresh re-embeds the whole resource.Only applies to remote-URL invocations.+ processing_mode: "semantic_and_vectors" for normal semantic processing, or+ "vectors_only" to skip semantic understanding and only build vector indexes.to: Target URI under viking://resources/ (e.g. "viking://resources/volcengine/OpenViking").Leave empty to derive a URI from the source.parent: Parent URI under viking://resources/ for remote imports. Mutually exclusive@@ -597,7 +601,13 @@ async def add_resource(store = TempUploadStore.build(server_config)try:result = await ingest_temp_upload(- store, temp_file_id, ctx, to=to, reason=description, args=args+ store,+ temp_file_id,+ ctx,+ to=to,+ reason=description,+ args=args,+ processing_mode=processing_mode,)except (PermissionDeniedError, InvalidArgumentError) as exc:return f"Error: {exc}"@@ -642,6 +652,7 @@ async def add_resource(reason=description,wait=False,watch_interval=watch_interval,+ processing_mode=processing_mode,enforce_public_remote_targets=True,args=args,)@@ -684,6 +695,7 @@ async def add_resource(to=to,reason=description,actor_peer_id=ctx.actor_peer_id or "",+ processing_mode=processing_mode,)base_url, url_source = _resolve_public_base_url()upload_url = f"{base_url}/api/v1/resources/temp_upload?token={quote(token, safe='')}"diff --git a/openviking/server/resource_ingest.py b/openviking/server/resource_ingest.pyindex 23f9760e2..267bfc0b1 100644--- a/openviking/server/resource_ingest.py+++ b/openviking/server/resource_ingest.py@@ -12,6 +12,7 @@ from __future__ import annotationsfrom typing import Any, Optional+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingModefrom openviking.server.dependencies import get_servicefrom openviking.server.identity import RequestContextfrom openviking.server.temp_upload_store import TempUploadStore@@ -25,6 +26,7 @@ async def ingest_temp_upload(to: str = "",reason: str = "",args: Optional[dict[str, Any]] = None,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,) -> dict[str, Any]:"""Resolve a temp upload and ingest it as a resource; return the raw add_resource result.@@ -47,6 +49,7 @@ async def ingest_temp_upload(reason=reason,source_name=resolved.original_filename,wait=False,+ processing_mode=processing_mode,allow_local_path_resolution=True,enforce_public_remote_targets=True,args=args,diff --git a/openviking/server/routers/resources.py b/openviking/server/routers/resources.pyindex 75d21b55d..ed73f8fab 100644--- a/openviking/server/routers/resources.py+++ b/openviking/server/routers/resources.py@@ -7,6 +7,7 @@ from typing import Any, Dict, Literal, Optionalfrom fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFilefrom pydantic import BaseModel, ConfigDict, Field, model_validator+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingModefrom openviking.server.auth import get_request_context, get_upload_request_contextfrom openviking.server.dependencies import get_servicefrom openviking.server.identity import RequestContext@@ -85,6 +86,7 @@ class AddResourceRequest(BaseModel):args: Dict[str, Any] = Field(default_factory=dict)telemetry: TelemetryRequest = Falsewatch_interval: float = 0+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE@model_validator(mode="after")def check_path_or_temp_file_id(self):@@ -148,7 +150,12 @@ async def temp_upload(if signed is None:return {"temp_file_id": temp_file_id}return await ingest_temp_upload(- store, temp_file_id, _ctx, to=signed.to, reason=signed.reason+ store,+ temp_file_id,+ _ctx,+ to=signed.to,+ reason=signed.reason,+ processing_mode=signed.processing_mode,)try:@@ -207,6 +214,7 @@ async def add_resource("exclude": request.exclude,"directly_upload_media": request.directly_upload_media,"watch_interval": request.watch_interval,+ "processing_mode": request.processing_mode,}# Connector routing needs to distinguish an omitted create_parent from an# explicit false. Standard imports still observe false when the field isdiff --git a/openviking/server/upload_token_store.py b/openviking/server/upload_token_store.pyindex 7b9c765da..705170f9e 100644--- a/openviking/server/upload_token_store.py+++ b/openviking/server/upload_token_store.py@@ -29,6 +29,8 @@ import timefrom dataclasses import dataclassfrom typing import Optional, Tuple+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode+_TOKEN_ALPHABET = string.ascii_letters + string.digits # base62_TOKEN_LENGTH = 6@@ -44,6 +46,7 @@ class _TokenInfo:to: strreason: stractor_peer_id: str+ processing_mode: ProcessingModeexpires_at: float@@ -56,6 +59,7 @@ class ConsumedUploadToken:to: strreason: stractor_peer_id: str+ processing_mode: ProcessingModeclass UploadTokenStore:@@ -71,6 +75,7 @@ class UploadTokenStore:to: str = "",reason: str = "",actor_peer_id: str = "",+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,) -> Tuple[str, float]:"""Mint a fresh token bound to (account, user) plus ``to``/``reason``/``actor_peer_id``.@@ -81,7 +86,15 @@ class UploadTokenStore:"""self._purge_expired()expires_at = time.time() + max(1, ttl_seconds)- info = _TokenInfo(account_id, user_id, to, reason, actor_peer_id, expires_at)+ info = _TokenInfo(+ account_id,+ user_id,+ to,+ reason,+ actor_peer_id,+ processing_mode,+ expires_at,+ )for _ in range(8):token = "".join(secrets.choice(_TOKEN_ALPHABET) for _ in range(_TOKEN_LENGTH))if token not in self._store:@@ -99,7 +112,12 @@ class UploadTokenStore:if info.expires_at < time.time():raise UploadTokenError("upload token expired")return ConsumedUploadToken(- info.account_id, info.user_id, info.to, info.reason, info.actor_peer_id+ info.account_id,+ info.user_id,+ info.to,+ info.reason,+ info.actor_peer_id,+ info.processing_mode,)def peek(self, token: str) -> Optional[_TokenInfo]:diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.pyindex 343181746..6c762168c 100644--- a/openviking/service/resource_service.py+++ b/openviking/service/resource_service.py@@ -28,6 +28,12 @@ from openviking.resource.feishu_watch_auth import (create_feishu_auth_state,load_feishu_app_credentials,)+from openviking.resource.processing_mode import (+ DEFAULT_PROCESSING_MODE,+ VECTORS_ONLY,+ ProcessingMode,+ normalize_processing_mode,+)from openviking.server.identity import RequestContextfrom openviking.server.local_input_guard import (is_remote_resource_source,@@ -84,6 +90,7 @@ _ADD_RESOURCE_ARGS_RESERVED_FIELDS = frozenset("timeout","build_index","summarize",+ "processing_mode","watch_interval","skip_watch_management","allow_local_path_resolution",@@ -202,6 +209,7 @@ class ResourceService:instruction: str,build_index: bool,summarize: bool,+ processing_mode: ProcessingMode,processor_kwargs: Dict[str, Any],watch_auth_state: Optional[Dict[str, Any]],ctx: RequestContext,@@ -252,6 +260,7 @@ class ResourceService:watch_interval=watch_interval,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,processor_kwargs=sanitized,auth_state=watch_auth_state,ctx=ctx,@@ -423,6 +432,7 @@ class ResourceService:timeout=msg.timeout,build_index=msg.build_index,summarize=msg.summarize,+ processing_mode=msg.processing_mode,watch_interval=msg.watch_interval,manage_watch=not msg.skip_watch_management,allow_local_path_resolution=msg.allow_local_path_resolution,@@ -454,6 +464,7 @@ class ResourceService:resource_lock=resource_lock,summarize=msg.summarize,build_index=msg.build_index,+ processing_mode=msg.processing_mode,)await request_wait_tracker.wait_for_request(telemetry_id,@@ -504,6 +515,7 @@ class ResourceService:timeout: Optional[float] = None,build_index: bool = True,summarize: bool = False,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,watch_interval: float = 0,manage_watch: bool = True,allow_local_path_resolution: bool = True,@@ -513,6 +525,7 @@ class ResourceService:) -> Dict[str, Any]:"""Start background ingestion for Git repositories while reserving the target URI."""self._ensure_initialized()+ processing_mode = normalize_processing_mode(processing_mode)normalized_args = self._normalize_add_resource_args(args, watch_interval=watch_interval)kwargs.update(normalized_args.processor_kwargs)from openviking.connector.routing import CONNECTOR_CREDENTIAL_ARGS@@ -578,6 +591,7 @@ class ResourceService:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,watch_interval=watch_interval,skip_watch_management=not manage_watch,allow_local_path_resolution=allow_local_path_resolution,@@ -709,6 +723,7 @@ class ResourceService:timeout: Optional[float] = None,build_index: bool = True,summarize: bool = False,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,watch_interval: float = 0,allow_local_path_resolution: bool = True,enforce_public_remote_targets: bool = False,@@ -733,6 +748,7 @@ class ResourceService:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,watch_interval=watch_interval,manage_watch=True,allow_local_path_resolution=allow_local_path_resolution,@@ -752,6 +768,7 @@ class ResourceService:timeout: Optional[float] = None,build_index: bool = True,summarize: bool = False,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,watch_interval: float = 0,allow_local_path_resolution: bool = True,enforce_public_remote_targets: bool = False,@@ -769,6 +786,7 @@ class ResourceService:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,watch_interval=watch_interval,manage_watch=False,allow_local_path_resolution=allow_local_path_resolution,@@ -789,6 +807,7 @@ class ResourceService:timeout: Optional[float] = None,build_index: bool = True,summarize: bool = False,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,watch_interval: float = 0,manage_watch: bool = True,allow_local_path_resolution: bool = True,@@ -808,6 +827,7 @@ class ResourceService:timeout: Wait timeout in secondsbuild_index: Whether to build vector index immediately (default: True)summarize: Whether to generate summary (default: False)+ processing_mode: Post-ingest processing mode for semantic/vector workwatch_interval: Watch interval in minutes for automatic resource monitoring.- watch_interval > 0: Creates or updates a watch task. The resource will beautomatically re-processed at the specified interval by the scheduler.@@ -832,6 +852,7 @@ class ResourceService:InvalidArgumentError: If the URI scope is not 'resources'"""self._ensure_initialized()+ processing_mode = normalize_processing_mode(processing_mode)normalized_args = self._normalize_add_resource_args(args, watch_interval=watch_interval)kwargs.update(normalized_args.processor_kwargs)if watch_interval > 0 and kwargs.get("temp_file_id"):@@ -867,6 +888,7 @@ class ResourceService:instruction=instruction,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,watch_interval=watch_interval,connector_args=args or {},kwargs=kwargs,@@ -891,6 +913,7 @@ class ResourceService:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,watch_interval=watch_interval,manage_watch=manage_watch,allow_local_path_resolution=allow_local_path_resolution,@@ -909,6 +932,7 @@ class ResourceService:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,watch_interval=watch_interval,manage_watch=manage_watch,allow_local_path_resolution=allow_local_path_resolution,@@ -930,6 +954,7 @@ class ResourceService:timeout: Optional[float] = None,build_index: bool = True,summarize: bool = False,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,watch_interval: float = 0,manage_watch: bool = True,allow_local_path_resolution: bool = True,@@ -1105,6 +1130,7 @@ class ResourceService:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,strict=bool(kwargs.get("strict", False)),ignore_dirs=kwargs.get("ignore_dirs"),include=kwargs.get("include"),@@ -1149,6 +1175,7 @@ class ResourceService:instruction=instruction,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,processor_kwargs=kwargs,watch_auth_state=watch_auth_state,ctx=ctx,@@ -1171,6 +1198,7 @@ class ResourceService:parent=target.parent,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,stage_callback=stage_callback,allow_local_path_resolution=allow_local_path_resolution,prepared_resource=prepared_resource,@@ -1252,6 +1280,7 @@ class ResourceService:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,strict=bool(kwargs.get("strict", False)),ignore_dirs=kwargs.get("ignore_dirs"),include=kwargs.get("include"),@@ -1283,6 +1312,7 @@ class ResourceService:instruction=instruction,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,processor_kwargs=kwargs,watch_auth_state=watch_auth_state,ctx=ctx,@@ -1394,6 +1424,7 @@ class ResourceService:instruction: str = "",build_index: bool = True,summarize: bool = False,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,watch_interval: float = 0,connector_args: Optional[Dict[str, Any]] = None,kwargs: Optional[Dict[str, Any]] = None,@@ -1479,6 +1510,7 @@ class ResourceService:instruction=instruction,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,watch_interval=watch_interval,connector_args=connector_args,kwargs=kwargs or {},@@ -1509,6 +1541,7 @@ class ResourceService:instruction: str,build_index: bool,summarize: bool,+ processing_mode: ProcessingMode,watch_interval: float,connector_args: Dict[str, Any],kwargs: Dict[str, Any],@@ -1541,6 +1574,8 @@ class ResourceService:unsupported.append("build_index=false")if summarize:unsupported.append("summarize=true")+ if processing_mode == VECTORS_ONLY:+ unsupported.append("processing_mode=vectors_only")if kwargs.get("strict"):unsupported.append("strict=true (Connector imports fail per file, not all-or-nothing)")for field in ("ignore_dirs", "include", "exclude"):@@ -1860,6 +1895,7 @@ class ResourceService:watch_interval: float,build_index: bool,summarize: bool,+ processing_mode: ProcessingMode,processor_kwargs: Dict[str, Any],auth_state: Optional[Dict[str, Any]],ctx: RequestContext,@@ -1908,6 +1944,7 @@ class ResourceService:watch_interval=watch_interval,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,processor_kwargs=processor_kwargs,auth_state=auth_state,is_active=True,@@ -1928,6 +1965,7 @@ class ResourceService:watch_interval=watch_interval,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,processor_kwargs=processor_kwargs,auth_state=auth_state,)diff --git a/openviking/storage/queuefs/add_resource_msg.py b/openviking/storage/queuefs/add_resource_msg.pyindex a2416ba7e..6db4e47cd 100644--- a/openviking/storage/queuefs/add_resource_msg.py+++ b/openviking/storage/queuefs/add_resource_msg.py@@ -5,6 +5,8 @@from dataclasses import asdict, dataclass, fieldfrom typing import Any, Dict, Optional+from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode+@dataclass(kw_only=True)class AddResourceMsg:@@ -39,6 +41,7 @@ class AddResourceMsg:skip_watch_management: bool = Truedefer_target_resolution: bool = Falseunderstanding_response_id: Optional[str] = None+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODEdef to_dict(self) -> Dict[str, Any]:data = asdict(self)@@ -116,4 +119,5 @@ class AddResourceMsg:if isinstance(data.get("understanding_response_id"), str)else None),+ processing_mode=data.get("processing_mode", DEFAULT_PROCESSING_MODE),)diff --git a/openviking/sync_client.py b/openviking/sync_client.pyindex 7c36ad3bf..974b89e7e 100644--- a/openviking/sync_client.py+++ b/openviking/sync_client.py@@ -237,6 +237,7 @@ class SyncOpenViking:summarize: bool = False,args: Optional[Dict[str, Any]] = None,telemetry: TelemetryRequest = False,+ processing_mode: str = "semantic_and_vectors",**kwargs,) -> Dict[str, Any]:"""Add resource to OpenViking (resources scope only)@@ -267,6 +268,7 @@ class SyncOpenViking:timeout=timeout,build_index=build_index,summarize=summarize,+ processing_mode=processing_mode,args=args,telemetry=telemetry,**kwargs,diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.pyindex b4fc89b0c..e7d7e7d97 100644--- a/openviking/utils/embedding_utils.py+++ b/openviking/utils/embedding_utils.py@@ -18,6 +18,7 @@ from openviking.server.identity import RequestContextfrom openviking.storage.queuefs import get_queue_managerfrom openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverterfrom openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fs+from openviking.telemetry.request_wait_tracker import get_request_wait_trackerfrom openviking.utils.image_search import image_bytes_to_data_urifrom openviking.utils.time_utils import parse_iso_datetimefrom openviking_cli.utils import VikingURI, get_logger@@ -422,6 +423,7 @@ async def vectorize_file(use_summary: bool = False,preserve_existing_created_at: bool = False,scalar_override: Optional[Dict[str, Any]] = None,+ register_request_wait: bool = False,) -> None:"""Vectorize a single file.@@ -431,6 +433,7 @@ async def vectorize_file(`use_summary` flag (code path override) or the embedding config."""enqueued = False+ registered_wait_root: Optional[tuple[str, str]] = Nonetry:if not ctx:@@ -541,12 +544,31 @@ async def vectorize_file(_apply_scalar_overrides(embedding_msg, scalar_override)embedding_msg.semantic_msg_id = semantic_msg_id- await embedding_queue.enqueue(embedding_msg)+ if register_request_wait:+ get_request_wait_tracker().register_embedding_root(+ embedding_msg.telemetry_id,+ embedding_msg.id,+ )+ registered_wait_root = (embedding_msg.telemetry_id, embedding_msg.id)+ enqueued_id = await embedding_queue.enqueue(embedding_msg)+ if register_request_wait and not enqueued_id:+ get_request_wait_tracker().mark_embedding_failed(+ embedding_msg.telemetry_id,+ embedding_msg.id,+ f"Failed to enqueue file vector for {file_path}",+ )+ returnenqueued = Truelogger.debug(f"Enqueued file for vectorization: {file_path}")except Exception as e:logger.error(f"Failed to vectorize file {file_path}: {e}", exc_info=True)+ if registered_wait_root is not None:+ get_request_wait_tracker().mark_embedding_failed(+ registered_wait_root[0],+ registered_wait_root[1],+ f"Failed to enqueue file vector for {file_path}: {e}",+ )finally:if not enqueued:await _decrement_embedding_tracker(semantic_msg_id, 1)diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.pyindex cf42b59a2..5ded05951 100644--- a/openviking/utils/resource_processor.py+++ b/openviking/utils/resource_processor.py@@ -12,11 +12,20 @@ import timefrom collections.abc import Callablefrom typing import TYPE_CHECKING, Any, Dict, List, Optional, Union+from openviking.core.context import ContextLevel+from openviking.core.namespace import context_type_for_urifrom openviking.parse.image_rewrite import rewrite_image_urisfrom openviking.parse.tree_builder import TreeBuilder+from openviking.resource.processing_mode import (+ DEFAULT_PROCESSING_MODE,+ VECTORS_ONLY,+ ProcessingMode,+ normalize_processing_mode,+)from openviking.server.identity import RequestContextfrom openviking.storage import VikingDBManagerfrom openviking.storage.errors import LockAcquisitionError+from openviking.storage.expr import And, Eq, PathScopefrom openviking.storage.internal_names import STORAGE_INTERNAL_ENTRY_NAMESfrom openviking.storage.transaction import (LOCK_TIMEOUT_DEFAULT,@@ -24,12 +33,13 @@ from openviking.storage.transaction import (LockLease,OwnedLockLease,)+from openviking.storage.queuefs.semantic_processor import SemanticProcessorfrom openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fsfrom openviking.telemetry import get_current_telemetry-from openviking.utils.embedding_utils import index_resource+from openviking.utils.embedding_utils import index_resource, vectorize_filefrom openviking.utils.summarizer import Summarizerfrom openviking_cli.exceptions import OpenVikingError-from openviking_cli.utils import get_logger+from openviking_cli.utils import VikingURI, get_loggerfrom openviking_cli.utils.storage import StoragePathif TYPE_CHECKING:@@ -37,6 +47,7 @@ if TYPE_CHECKING:from openviking.parse.vlm import VLMProcessorlogger = get_logger(__name__)+VECTORDB_MAX_QUERY_LIMIT = 100_000class ResourceProcessor:@@ -427,6 +438,7 @@ class ResourceProcessor:ctx: RequestContext,resource_lock: LockLease = NO_LOCK,summarize: bool = False,+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,**kwargs: Any,) -> Dict[str, Any]:"""Run the queue-producing phase for a resource already stored in VikingFS."""@@ -438,7 +450,9 @@ class ResourceProcessor:source_committed = bool(prepared.get("source_committed"))target_preexisting = bool(prepared.get("target_preexisting"))build_index = bool(kwargs.get("build_index", True))- should_summarize = summarize or build_index+ processing_mode = normalize_processing_mode(processing_mode)+ vectors_only = processing_mode == VECTORS_ONLY+ should_summarize = not vectors_only and (summarize or build_index)result: Dict[str, Any] = {"status": "success", "root_uri": root_uri}if should_summarize:@@ -480,9 +494,21 @@ class ResourceProcessor:if resource_lock.active:try:+ sync_deleted_files: list[str] = []+ sync_deleted_dirs: list[str] = []if not should_summarize and temp_uri and not source_committed:viking_fs = get_viking_fs()- await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)+ if vectors_only and target_preexisting:+ diff = await SemanticProcessor()._sync_topdown_recursive(+ temp_uri,+ root_uri,+ ctx=ctx,+ lock=resource_lock,+ )+ sync_deleted_files = list(getattr(diff, "deleted_files", []))+ sync_deleted_dirs = list(getattr(diff, "deleted_dirs", []))+ else:+ await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)await rewrite_image_uris(root_uri,ctx=ctx,@@ -490,10 +516,84 @@ class ResourceProcessor:)if temp_dir_path:await viking_fs.delete_temp(temp_dir_path, ctx=ctx)+ if vectors_only:+ if sync_deleted_files or sync_deleted_dirs:+ await self._delete_removed_resource_vectors(+ files=sync_deleted_files,+ dirs=sync_deleted_dirs,+ ctx=ctx,+ )+ if vectors_only and build_index:+ await self._vectorize_resource_files(root_uri, ctx=ctx)finally:await resource_lock.close()+ elif vectors_only:+ if not build_index:+ return result+ await self._vectorize_resource_files(root_uri, ctx=ctx)return result+ async def _delete_removed_resource_vectors(+ self,+ *,+ files: list[str],+ dirs: list[str],+ ctx: RequestContext,+ ) -> None:+ for uri in dict.fromkeys(files):+ records = await self.vikingdb.get_context_by_uri(+ uri=uri,+ level=int(ContextLevel.DETAIL),+ limit=100,+ ctx=ctx,+ )+ ids = [str(record["id"]) for record in records if record.get("id")]+ if ids:+ await self.vikingdb.delete(ids, ctx=ctx)+ for uri in dict.fromkeys(dirs):+ records = await self.vikingdb.filter(+ filter=And(+ [+ PathScope("uri", uri, depth=-1),+ Eq("level", int(ContextLevel.DETAIL)),+ Eq("account_id", ctx.account_id),+ ]+ ),+ limit=VECTORDB_MAX_QUERY_LIMIT,+ output_fields=["id"],+ ctx=ctx,+ )+ ids = [str(record["id"]) for record in records if record.get("id")]+ if ids:+ await self.vikingdb.delete(ids, ctx=ctx)++ async def _vectorize_resource_files(self, root_uri: str, *, ctx: RequestContext) -> None:+ viking_fs = get_viking_fs()+ entries = await viking_fs.tree(+ root_uri,+ node_limit=None,+ level_limit=None,+ ctx=ctx,+ )+ for entry in entries:+ entry_uri = entry.get("uri") if isinstance(entry, dict) else None+ if not entry_uri or entry.get("isDir"):+ continue+ name = entry.get("name") or entry_uri.rsplit("/", 1)[-1]+ if str(name).startswith("."):+ continue+ parent = VikingURI(entry_uri).parent+ if parent is None:+ continue+ await vectorize_file(+ file_path=entry_uri,+ summary_dict={"name": name, "summary": ""},+ parent_uri=parent.uri,+ context_type=context_type_for_uri(entry_uri),+ ctx=ctx,+ register_request_wait=True,+ )+async def reserve_unique_candidate(self,*,diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.pyindex f7f3efd1e..e1cdbfd60 100644--- a/openviking_cli/client/base.py+++ b/openviking_cli/client/base.py@@ -43,6 +43,7 @@ class BaseClient(ABC):wait: bool = False,timeout: Optional[float] = None,watch_interval: float = 0,+ processing_mode: str = "semantic_and_vectors",args: Optional[Dict[str, Any]] = None,telemetry: TelemetryRequest = False,) -> Dict[str, Any]:diff --git a/sdk/python/README.md b/sdk/python/README.mdindex c0292ae3c..5ebd617c1 100644--- a/sdk/python/README.md+++ b/sdk/python/README.md@@ -166,6 +166,19 @@ result = client.add_resource(print(result)```+To ingest content without VLM semantic understanding, pass `processing_mode="vectors_only"`.+This writes/syncs the resource tree and vectorizes current files, but does not generate+or refresh `.abstract.md` / `.overview.md`.++```python+result = client.add_resource(+ "/path/to/notes.md",+ to="viking://resources/demo-notes",+ processing_mode="vectors_only",+ wait=True,+)+```+### Filesystem Operations```pythondiff --git a/sdk/python/README_CN.md b/sdk/python/README_CN.mdindex b63bf82ab..b1b334018 100644--- a/sdk/python/README_CN.md+++ b/sdk/python/README_CN.md@@ -166,6 +166,18 @@ result = client.add_resource(print(result)```+如果只希望入库并生成向量、不走 VLM 语义理解,可以传 `processing_mode="vectors_only"`。+该模式会写入/同步资源树并向量化当前文件,但不会生成或刷新 `.abstract.md` / `.overview.md`。++```python+result = client.add_resource(+ "/path/to/notes.md",+ to="viking://resources/demo-notes",+ processing_mode="vectors_only",+ wait=True,+)+```+### 文件系统操作```pythondiff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.pyindex 0eb22a7e3..36ed96c48 100644--- a/sdk/python/openviking_sdk/client.py+++ b/sdk/python/openviking_sdk/client.py@@ -641,6 +641,7 @@ class AsyncHTTPClient:watch_interval: float = 0,args: Optional[Dict[str, Any]] = None,telemetry: Any = False,+ processing_mode: Optional[str] = None,) -> Dict[str, Any]:if to and parent:raise ValueError("Cannot specify both 'to' and 'parent' at the same time.")@@ -661,6 +662,8 @@ class AsyncHTTPClient:"args": args or {},"telemetry": telemetry,}+ if processing_mode is not None:+ request_data["processing_mode"] = processing_modeif preserve_structure is not None:request_data["preserve_structure"] = preserve_structure@@ -1786,6 +1789,7 @@ class SyncHTTPClient:watch_interval: float = 0,args: Optional[Dict[str, Any]] = None,telemetry: Any = False,+ processing_mode: Optional[str] = None,) -> Dict[str, Any]:return run_async(self._async_client.add_resource(@@ -1803,6 +1807,7 @@ class SyncHTTPClient:directly_upload_media=directly_upload_media,preserve_structure=preserve_structure,watch_interval=watch_interval,+ processing_mode=processing_mode,args=args,telemetry=telemetry,)diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.pyindex b45968af1..bef039399 100644--- a/sdk/python/tests/test_async_client_behaviors.py+++ b/sdk/python/tests/test_async_client_behaviors.py@@ -453,6 +453,77 @@ async def test_add_resource_uploads_local_file_even_when_url_is_localhost(tmp_paassert "path" not in payload+async def test_add_resource_forwards_processing_mode():+ client = AsyncHTTPClient(url="http://127.0.0.1:1933")+ fake_http = SimpleNamespace(post=AsyncMock(return_value=object()))+ client._http = fake_http+ client._handle_response_data = lambda _response: {+ "result": {"root_uri": "viking://resources/demo"}+ }++ await client.add_resource(+ "https://example.com/demo.md",+ processing_mode="vectors_only",+ )++ fake_http.post.assert_awaited_once()+ payload = fake_http.post.await_args.kwargs["json"]+ assert payload["processing_mode"] == "vectors_only"+++async def test_add_resource_omits_default_processing_mode_for_legacy_servers():+ client = AsyncHTTPClient(url="http://127.0.0.1:1933")+ fake_http = SimpleNamespace(post=AsyncMock(return_value=object()))+ client._http = fake_http+ client._handle_response_data = lambda _response: {+ "result": {"root_uri": "viking://resources/demo"}+ }++ await client.add_resource("https://example.com/demo.md")++ fake_http.post.assert_awaited_once()+ payload = fake_http.post.await_args.kwargs["json"]+ assert "processing_mode" not in payload+++async def test_add_resource_preserves_positional_watch_args_for_legacy_callers():+ client = AsyncHTTPClient(url="http://127.0.0.1:1933")+ fake_http = SimpleNamespace(post=AsyncMock(return_value=object()))+ client._http = fake_http+ client._handle_response_data = lambda _response: {+ "result": {"root_uri": "viking://resources/demo"}+ }++ await client.add_resource(+ "https://example.com/demo.md",+ None,+ None,+ "",+ "",+ False,+ None,+ False,+ None,+ None,+ None,+ True,+ None,+ 1440,+ {"site": True},+ False,+ )++ fake_http.post.assert_awaited_once()+ payload = fake_http.post.await_args.kwargs["json"]+ assert payload["watch_interval"] == 1440+ assert payload["args"] == {"site": True}+ assert payload["telemetry"] is False+ assert "processing_mode" not in payload++@pytest.mark.asyncioasync def test_admin_create_paths_accept_initial_user_config():client = AsyncHTTPClient(url="http://localhost:1933")diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 8b66df46d..22bc07715 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -24,6 +24,16 @@ The client follows the same HTTP API, identity headers, response envelope and erExisting local file paths are uploaded automatically, and local directories are zipped before upload. Other strings are sent to the server as URLs or server-side paths.+To ingest content without VLM semantic understanding, pass `processingMode: "vectors_only"` to `addResource`. This writes or syncs the resource tree and vectorizes current files, but does not generate or refresh `.abstract.md` / `.overview.md`.++```ts+await client.addResource("./docs/guide.md", {+ to: "viking://resources/guide",+ processingMode: "vectors_only",+ wait: true,+});+```+Deployments using shared temporary storage can set `uploadMode: "shared"`; the server also accepts `"local"` (the default).OVPack exports and backups follow the Python and Go SDK contract: they are streamed to a Node.js local file and return its final path.diff --git a/sdk/typescript/README_CN.md b/sdk/typescript/README_CN.mdindex 10a6b2802..c7fe75490 100644--- a/sdk/typescript/README_CN.md+++ b/sdk/typescript/README_CN.md@@ -24,6 +24,16 @@ SDK 与 Python `openviking-sdk`、Go SDK 使用相同的 HTTP API、身份请求Node.js 中存在的本地文件路径会自动上传,目录会先压缩后上传;其他字符串会作为 URL 或服务端路径发送。+如果只希望入库并生成向量、不走 VLM 语义理解,可以给 `addResource` 传 `processingMode: "vectors_only"`。该模式会写入/同步资源树并向量化当前文件,但不会生成或刷新 `.abstract.md` / `.overview.md`。++```ts+await client.addResource("./docs/guide.md", {+ to: "viking://resources/guide",+ processingMode: "vectors_only",+ wait: true,+});+```+使用共享临时存储的部署可设置 `uploadMode: "shared"`;服务端也接受 `"local"`(默认值)。OVPack 导出和备份与 Python、Go SDK 契约一致:内容会流式写入 Node.js 本地文件,并返回最终文件路径。diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.tsindex 58d727424..f35c39213 100644--- a/sdk/typescript/src/client.ts+++ b/sdk/typescript/src/client.ts@@ -119,6 +119,7 @@ export class OpenVikingClient {directly_upload_media: options.directlyUploadMedia ?? true,preserve_structure: options.preserveStructure,watch_interval: options.watchInterval ?? 0,+ processing_mode: options.processingMode,args:options.args && Object.keys(options.args).length? options.argsdiff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.tsindex d4b178fa2..455e6cb6b 100644--- a/sdk/typescript/src/types.ts+++ b/sdk/typescript/src/types.ts@@ -7,6 +7,8 @@ export type ClientHeaders =Headers | Record<string, string> | [string, string][];/** Temporary upload storage mode supported by the OpenViking server. */export type UploadMode = "local" | "shared";+/** Resource post-ingest processing modes accepted by addResource. */+export type ProcessingMode = "semantic_and_vectors" | "vectors_only";/** Conflict policy accepted when importing an OVPack. */export type PackConflictPolicy = "fail" | "overwrite" | "skip";/** Vector handling strategy accepted when importing an OVPack. */@@ -83,6 +85,7 @@ export interface AddResourceOptions extends WaitOptions {directlyUploadMedia?: boolean;preserveStructure?: boolean;watchInterval?: number;+ processingMode?: ProcessingMode;args?: JsonObject;}/** Semantic retrieval options. */diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.tsindex e79268d60..b8194e4d3 100644--- a/sdk/typescript/tests/client.test.ts+++ b/sdk/typescript/tests/client.test.ts@@ -88,6 +88,29 @@ describe("OpenVikingClient", () => {});});+ it("sends processing_mode for addResource requests", async () => {+ const fetcher = vi.fn<typeof fetch>().mockResolvedValue(ok({}));+ const client = new OpenVikingClient({+ baseUrl: "https://example.com",+ fetch: fetcher,+ });++ await client.addResource("https://example.com/guide.md", {+ to: "viking://resources/guide",+ processingMode: "vectors_only",+ wait: true,+ });++ const [url, init] = fetcher.mock.calls[0]!;+ expect(String(url)).toBe("https://example.com/api/v1/resources");+ expect(JSON.parse(String(init?.body))).toMatchObject({+ path: "https://example.com/guide.md",+ to: "viking://resources/guide",+ processing_mode: "vectors_only",+ wait: true,+ });+ });+it("maps response envelopes to typed errors", async () => {const fetcher = vi.fn<typeof fetch>().mockResolvedValue(new Response(diff --git a/tests/api_test/api/client.py b/tests/api_test/api/client.pyindex e0525feba..5b5b92241 100644--- a/tests/api_test/api/client.py+++ b/tests/api_test/api/client.py@@ -277,6 +277,7 @@ class OpenVikingAPIClient:parent: Optional[str] = None,instruction: Optional[str] = None,wait: bool = False,+ processing_mode: Optional[str] = None,) -> requests.Response:endpoint = "/api/v1/resources"url = self._build_url(self.server_url, endpoint)@@ -299,6 +300,8 @@ class OpenVikingAPIClient:payload["instruction"] = instructionif wait:payload["wait"] = wait+ if processing_mode:+ payload["processing_mode"] = processing_modetry:return self._request_with_retry("POST", url, json=payload)finally:diff --git a/tests/client/test_add_resource_signature_compat.py b/tests/client/test_add_resource_signature_compat.pynew file mode 100644index 000000000..76185fe2c--- /dev/null+++ b/tests/client/test_add_resource_signature_compat.py@@ -0,0 +1,126 @@+import inspect++from openviking import AsyncOpenViking, SyncOpenViking+from openviking.client.local import LocalClient+from openviking_sdk.client import AsyncHTTPClient, SyncHTTPClient+++def test_async_openviking_add_resource_preserves_positional_watch_args():+ bound = inspect.signature(AsyncOpenViking.add_resource).bind_partial(+ object(),+ "doc.md",+ None,+ None,+ "",+ "",+ False,+ None,+ True,+ False,+ 1440,+ {"site": True},+ False,+ )++ assert bound.arguments["watch_interval"] == 1440+ assert bound.arguments["args"] == {"site": True}+ assert bound.arguments["telemetry"] is False+ assert "processing_mode" not in bound.arguments+++def test_sync_openviking_add_resource_preserves_positional_args_and_telemetry():+ bound = inspect.signature(SyncOpenViking.add_resource).bind_partial(+ object(),+ "doc.md",+ None,+ None,+ "",+ "",+ False,+ None,+ True,+ False,+ {"site": True},+ False,+ )++ assert bound.arguments["args"] == {"site": True}+ assert bound.arguments["telemetry"] is False+ assert "processing_mode" not in bound.arguments+++def test_local_client_add_resource_preserves_positional_watch_args():+ bound = inspect.signature(LocalClient.add_resource).bind_partial(+ object(),+ "doc.md",+ None,+ None,+ "",+ "",+ False,+ None,+ True,+ False,+ False,+ 1440,+ {"site": True},+ )++ assert bound.arguments["telemetry"] is False+ assert bound.arguments["watch_interval"] == 1440+ assert bound.arguments["args"] == {"site": True}+ assert "processing_mode" not in bound.arguments+++def test_async_http_client_add_resource_preserves_positional_watch_args():+ bound = inspect.signature(AsyncHTTPClient.add_resource).bind_partial(+ object(),+ "doc.md",+ None,+ None,+ "",+ "",+ False,+ None,+ False,+ None,+ None,+ None,+ True,+ None,+ 1440,+ {"site": True},+ False,+ )++ assert bound.arguments["watch_interval"] == 1440+ assert bound.arguments["args"] == {"site": True}+ assert bound.arguments["telemetry"] is False+ assert "processing_mode" not in bound.arguments+++def test_sync_http_client_add_resource_preserves_positional_watch_args():+ bound = inspect.signature(SyncHTTPClient.add_resource).bind_partial(+ object(),+ "doc.md",+ None,+ None,+ "",+ "",+ False,+ None,+ False,+ None,+ None,+ None,+ True,+ None,+ 1440,+ {"site": True},+ False,+ )++ assert bound.arguments["watch_interval"] == 1440+ assert bound.arguments["args"] == {"site": True}+ assert bound.arguments["telemetry"] is False+ assert "processing_mode" not in bound.argumentsdiff --git a/tests/parse/test_feishu_parser_api.py b/tests/parse/test_feishu_parser_api.pyindex 039b9b679..4dbbded75 100644--- a/tests/parse/test_feishu_parser_api.py+++ b/tests/parse/test_feishu_parser_api.py@@ -390,6 +390,22 @@ def test_add_resource_message_round_trips_internal_fields():assert restored.understanding_response_id == "response-1"+def test_add_resource_message_round_trips_processing_mode():+ msg = AddResourceMsg(+ task_id="task-1",+ path="https://example.com/demo.md",+ root_uri="viking://resources/demo",+ account_id="account-1",+ user_id="user-1",+ role="user",+ processing_mode="vectors_only",+ )++ restored = AddResourceMsg.from_dict(msg.to_dict())++ assert restored.processing_mode == "vectors_only"++@pytest.mark.asyncioasync def test_uat_producer_payload_reaches_worker_without_persisting_token(monkeypatch):source = "https://example.larkoffice.com/docx/doxcnToken"@@ -702,6 +718,7 @@ async def test_add_resource_job_expands_parser_args():user_id="user-1",role="user",args={"custom_option": "forwarded"},+ processing_mode="vectors_only",)ctx = RequestContext(user=UserIdentifier("account-1", "user-1"),@@ -719,6 +736,41 @@ async def test_add_resource_job_expands_parser_args():assert call.kwargs["to"] == "viking://resources/doxcnToken"assert call.kwargs["parent"] is Noneassert call.kwargs["custom_option"] == "forwarded"+ assert call.kwargs["processing_mode"] == "vectors_only"+++async def test_prepared_add_resource_job_forwards_processing_mode():+ resource_processor = SimpleNamespace(+ finish_prepared_resource=AsyncMock(+ return_value={"status": "success", "root_uri": "viking://resources/demo"}+ )+ )+ service = ResourceService(resource_processor=resource_processor)+ msg = AddResourceMsg(+ task_id="task-1",+ path="/tmp/demo.md",+ root_uri="viking://resources/demo",+ account_id="account-1",+ user_id="user-1",+ role="user",+ prepared={"root_uri": "viking://resources/demo"},+ processing_mode="vectors_only",+ )+ ctx = RequestContext(+ user=UserIdentifier("account-1", "user-1"),+ role=Role.USER,+ )++ await service.execute_add_resource_job(+ msg,+ ctx=ctx,+ resource_lock=None,+ stage_callback=AsyncMock(),+ )++ call = resource_processor.finish_prepared_resource.await_args+ assert call.kwargs["processing_mode"] == "vectors_only"@pytest.mark.asynciodiff --git a/tests/resource/test_watch_manager.py b/tests/resource/test_watch_manager.pyindex 39f5a0f38..3493b4032 100644--- a/tests/resource/test_watch_manager.py+++ b/tests/resource/test_watch_manager.py@@ -80,6 +80,7 @@ class TestWatchTask:assert task.created_at is not Noneassert task.last_execution_time is Noneassert task.next_execution_time is None+ assert task.processing_mode == "semantic_and_vectors"def test_create_task_with_all_fields(self):"""Test creating a task with all fields specified."""@@ -92,6 +93,7 @@ class TestWatchTask:reason="Test reason",instruction="Test instruction",watch_interval=30.0,+ processing_mode="vectors_only",created_at=now,last_execution_time=now,next_execution_time=now + timedelta(minutes=30),@@ -105,6 +107,7 @@ class TestWatchTask:assert task.reason == "Test reason"assert task.instruction == "Test instruction"assert task.watch_interval == 30.0+ assert task.processing_mode == "vectors_only"assert task.is_active is Falseassert task.created_at == nowassert task.last_execution_time == now@@ -132,6 +135,7 @@ class TestWatchTask:assert data["to_uri"] == "viking://test"assert data["created_at"] == now.isoformat()assert data["is_active"] is True+ assert data["processing_mode"] == "semantic_and_vectors"assert "auth_state" not in datadef test_from_dict(self):@@ -145,6 +149,7 @@ class TestWatchTask:"reason": "Test","instruction": "Instruction","watch_interval": 45.0,+ "processing_mode": "vectors_only","created_at": now.isoformat(),"last_execution_time": now.isoformat(),"next_execution_time": (now + timedelta(minutes=45)).isoformat(),@@ -157,10 +162,16 @@ class TestWatchTask:assert task.path == "/test/path"assert task.to_uri == "viking://test"assert task.watch_interval == 45.0+ assert task.processing_mode == "vectors_only"assert task.is_active is Falseassert task.created_at == nowassert task.last_execution_time == now+ def test_from_dict_defaults_legacy_processing_mode(self):+ task = WatchTask.from_dict({"path": "/test/path"})++ assert task.processing_mode == "semantic_and_vectors"+def test_calculate_next_execution_time(self):"""Test calculating next execution time."""now = datetime.now()diff --git a/tests/resource/test_watch_scheduler.py b/tests/resource/test_watch_scheduler.pyindex 36557e4cc..43e5097d0 100644--- a/tests/resource/test_watch_scheduler.py+++ b/tests/resource/test_watch_scheduler.py@@ -110,3 +110,34 @@ class TestWatchSchedulerResourceExistence:assert updated.is_active is Trueassert resource_service.calls and resource_service.calls[0]["to"] == task.to_urimanager.update_execution_time.assert_awaited_once_with(task.task_id)++ @pytest.mark.asyncio+ async def test_execute_task_forwards_processing_mode(self, tmp_path):+ class FakeResourceService(ResourceService):+ def __init__(self):+ super().__init__()+ self.calls = []++ async def refresh_resource(self, **kwargs):+ self.calls.append(kwargs)+ return {"root_uri": kwargs.get("to")}++ source = tmp_path / "source.txt"+ source.write_text("ok")+ resource_service = FakeResourceService()+ scheduler = WatchScheduler(resource_service=resource_service, check_interval=1)+ manager = WatchManager(viking_fs=None)+ await manager.initialize()+ scheduler._watch_manager = manager+ manager.update_execution_time = AsyncMock()+ task = await manager.create_task(+ path=str(source),+ to_uri="viking://resources/codeask/wiki",+ watch_interval=30.0,+ processing_mode="vectors_only",+ )++ await scheduler._execute_task(task)++ assert resource_service.calls+ assert resource_service.calls[0]["processing_mode"] == "vectors_only"diff --git a/tests/server/test_api_resources.py b/tests/server/test_api_resources.pyindex 84a751244..d7ea3bcd6 100644--- a/tests/server/test_api_resources.py+++ b/tests/server/test_api_resources.py@@ -9,9 +9,27 @@ from types import SimpleNamespaceimport httpx+from openviking.server.identity import RequestContext, Rolefrom openviking.server.routers import resources as resources_router+from openviking.server.routers.resources import AddResourceRequestfrom openviking.storage.viking_fs import get_viking_fsfrom openviking.telemetry import get_current_telemetry+from openviking_cli.session.user_id import UserIdentifier+++def test_add_resource_request_accepts_processing_mode():+ request = AddResourceRequest(+ path="https://example.com/demo.md",+ processing_mode="vectors_only",+ )++ assert request.processing_mode == "vectors_only"+++def test_add_resource_request_defaults_processing_mode():+ request = AddResourceRequest(path="https://example.com/demo.md")++ assert request.processing_mode == "semantic_and_vectors"async def _wait_task_terminal(client: httpx.AsyncClient, task_id: str, timeout: float = 10.0):@@ -99,6 +117,35 @@ async def test_add_resource_forwards_args_to_service(assert seen["args"] == {"feishu_access_token": "u-test"}+async def test_add_resource_forwards_processing_mode_to_service(monkeypatch):+ seen = {}++ async def fake_add_resource(**kwargs):+ seen.update(kwargs)+ return {+ "status": "success",+ "root_uri": "viking://resources/demo",+ }++ service = SimpleNamespace(resources=SimpleNamespace(add_resource=fake_add_resource))+ monkeypatch.setattr(resources_router, "get_service", lambda: service)++ response = await resources_router.add_resource(+ SimpleNamespace(app=SimpleNamespace(state=SimpleNamespace(config=None))),+ AddResourceRequest(+ path="https://example.com/demo.md",+ processing_mode="vectors_only",+ ),+ RequestContext(+ user=UserIdentifier("account-1", "user-1"),+ role=Role.USER,+ ),+ )++ assert response["status"] == "ok"+ assert seen["processing_mode"] == "vectors_only"++async def test_add_resource_preserves_create_parent_field_presence(client: httpx.AsyncClient,service,diff --git a/tests/server/test_upload_token_store.py b/tests/server/test_upload_token_store.pyindex 96395f37d..4cb6dced8 100644--- a/tests/server/test_upload_token_store.py+++ b/tests/server/test_upload_token_store.py@@ -42,11 +42,13 @@ def test_consume_returns_bound_business_params(store):to="viking://resources/team/proj",reason="quarterly",actor_peer_id="bot-a",+ processing_mode="vectors_only",)consumed = store.consume(token)assert consumed.to == "viking://resources/team/proj"assert consumed.reason == "quarterly"assert consumed.actor_peer_id == "bot-a"+ assert consumed.processing_mode == "vectors_only"def test_consume_burns_token(store):diff --git a/tests/service/test_resource_service_watch.py b/tests/service/test_resource_service_watch.pyindex 2bfe6c838..fba22225c 100644--- a/tests/service/test_resource_service_watch.py+++ b/tests/service/test_resource_service_watch.py@@ -34,7 +34,16 @@ class MockResourceProcessor:async def process_resource(self, **kwargs):self.calls.append(kwargs)- return {"root_uri": kwargs.get("to") or "viking://resources/test"}+ root_uri = kwargs.get("to") or "viking://resources/test"+ return {+ "root_uri": root_uri,+ "_post_process": {"root_uri": root_uri},+ "_resource_lock": SimpleNamespace(+ active=False,+ to_handoff=MagicMock(return_value=None),+ close=AsyncMock(),+ ),+ }class MockSkillProcessor:@@ -91,6 +100,13 @@ def isolate_service_dependencies(monkeypatch: pytest.MonkeyPatch) -> None:monkeypatch.setattr(resource_service_module, "is_git_repo_url", lambda _path: False)+@pytest_asyncio.fixture+async def watch_manager() -> AsyncGenerator[WatchManager, None]:+ manager = WatchManager(viking_fs=None)+ await manager.initialize()+ yield manager++@pytest_asyncio.fixtureasync def resource_service(watch_manager: WatchManager) -> AsyncGenerator[ResourceService, None]:"""Create ResourceService instance with watch support."""@@ -103,6 +119,9 @@ async def resource_service(watch_manager: WatchManager) -> AsyncGenerator[Resourskill_processor=MockSkillProcessor(),watch_scheduler=scheduler,)+ service._enqueue_add_resource_job = AsyncMock(+ return_value=SimpleNamespace(task_id="test-task")+ )yield service@@ -199,6 +218,7 @@ class TestWatchTaskCreation:watch_interval=30.0,build_index=False,summarize=True,+ processing_mode="vectors_only",custom_option="x",)@@ -206,7 +226,9 @@ class TestWatchTaskCreation:assert task is not Noneassert task.build_index is Falseassert task.summarize is True+ assert task.processing_mode == "vectors_only"assert task.processor_kwargs.get("custom_option") == "x"+ assert "processing_mode" not in task.processor_kwargs@pytest.mark.asyncioasync def test_create_watch_task_with_default_interval(diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.pyindex f234bc07f..d3f139098 100644--- a/tests/unit/test_vectorize_file_strategy.py+++ b/tests/unit/test_vectorize_file_strategy.py@@ -14,6 +14,18 @@ class DummyQueue:self.items.append(msg)+class DummyQueueWithId(DummyQueue):+ async def enqueue(self, msg):+ self.items.append(msg)+ return "queue-message-id"+++class FailingQueue(DummyQueue):+ async def enqueue(self, msg):+ self.items.append(msg)+ raise RuntimeError("queue unavailable")++class DummyQueueManager:EMBEDDING = "embedding"@@ -119,6 +131,83 @@ async def test_vectorize_file_uses_summary_first(monkeypatch):assert queue.items[0].get_vectorization_text() == "short summary"+async def test_vectorize_file_registers_request_wait_with_embedding_msg_id(monkeypatch):+ queue = DummyQueueWithId()+ registered = []+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("hello"))+ monkeypatch.setattr(+ embedding_utils,+ "get_openviking_config",+ lambda: types.SimpleNamespace(+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=1000)+ ),+ )+ monkeypatch.setattr(+ embedding_utils,+ "get_request_wait_tracker",+ lambda: types.SimpleNamespace(+ register_embedding_root=lambda telemetry_id, root_id: registered.append(+ (telemetry_id, root_id)+ )+ ),+ )++ await embedding_utils.vectorize_file(+ file_path="viking://user/default/resources/test.md",+ summary_dict={"name": "test.md", "summary": ""},+ parent_uri="viking://user/default/resources",+ ctx=DummyReq(),+ register_request_wait=True,+ )++ assert len(queue.items) == 1+ assert registered == [(queue.items[0].telemetry_id, queue.items[0].id)]+ assert registered[0][1] != "queue-message-id"+++async def test_vectorize_file_marks_registered_wait_root_failed_when_enqueue_raises(monkeypatch):+ queue = FailingQueue()+ registered = []+ failed = []+ monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("hello"))+ monkeypatch.setattr(+ embedding_utils,+ "get_openviking_config",+ lambda: types.SimpleNamespace(+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=1000)+ ),+ )+ monkeypatch.setattr(+ embedding_utils,+ "get_request_wait_tracker",+ lambda: types.SimpleNamespace(+ register_embedding_root=lambda telemetry_id, root_id: registered.append(+ (telemetry_id, root_id)+ ),+ mark_embedding_failed=lambda telemetry_id, root_id, message: failed.append(+ (telemetry_id, root_id, message)+ ),+ ),+ )++ await embedding_utils.vectorize_file(+ file_path="viking://user/default/resources/test.md",+ summary_dict={"name": "test.md", "summary": ""},+ parent_uri="viking://user/default/resources",+ ctx=DummyReq(),+ register_request_wait=True,+ )++ assert len(queue.items) == 1+ assert registered == [(queue.items[0].telemetry_id, queue.items[0].id)]+ assert failed+ assert failed[0][0:2] == registered[0]++@pytest.mark.asyncioasync def test_vectorize_unknown_text_file_embeds_summary_but_indexes_raw_content(monkeypatch):queue = DummyQueue()diff --git a/tests/utils/test_resource_processor_processing_mode.py b/tests/utils/test_resource_processor_processing_mode.pynew file mode 100644index 000000000..274f03aa4--- /dev/null+++ b/tests/utils/test_resource_processor_processing_mode.py@@ -0,0 +1,289 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++from types import SimpleNamespace+from unittest.mock import AsyncMock, Mock++import pytest++from openviking.server.identity import RequestContext, Role+from openviking.utils.resource_processor import ResourceProcessor+from openviking_cli.session.user_id import UserIdentifier+++class _FakeVikingDB:+ def get_embedder(self):+ return None+++class _RecordingVikingDB:+ def __init__(self):+ self.lookup_calls = []+ self.filter_calls = []+ self.delete_calls = []++ def get_embedder(self):+ return None++ async def get_context_by_uri(self, *, uri, level, limit, ctx):+ self.lookup_calls.append((uri, level, limit, ctx))+ return [{"id": f"{uri}:{level}"}]++ async def delete(self, ids, *, ctx):+ self.delete_calls.append((ids, ctx))+ return len(ids)++ async def filter(self, *, filter, limit, output_fields, ctx):+ self.filter_calls.append((filter, limit, output_fields, ctx))+ return [{"id": "recursive-child-detail"}]+++def ctx() -> RequestContext:+ return RequestContext(+ user=UserIdentifier("account-1", "user-1"),+ role=Role.USER,+ )+++async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch, ctx):+ viking_fs = SimpleNamespace(+ persist_temp_tree=AsyncMock(),+ delete_temp=AsyncMock(),+ tree=AsyncMock(+ return_value=[+ {"uri": "viking://resources/demo/section", "isDir": True},+ {+ "uri": "viking://resources/demo/section/page.md",+ "isDir": False,+ "name": "page.md",+ },+ {+ "uri": "viking://resources/demo/section/.abstract.md",+ "isDir": False,+ "name": ".abstract.md",+ },+ ]+ ),+ )+ vectorize_file = AsyncMock()+ rewrite_image_uris = AsyncMock()+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", rewrite_image_uris)+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", vectorize_file)+ processor = ResourceProcessor(_FakeVikingDB())+ processor._get_summarizer = Mock(side_effect=AssertionError("summarizer should not run"))+ processor._delete_resource_semantic_markers = AsyncMock()+ processor._delete_resource_semantic_vectors = AsyncMock()+ processor._delete_removed_resource_vectors = AsyncMock()+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())++ result = await processor.finish_prepared_resource(+ {+ "root_uri": "viking://resources/demo",+ "temp_uri": "viking://temp/demo",+ "temp_dir_path": "tmp/demo",+ "source_committed": False,+ },+ ctx=ctx,+ resource_lock=lock,+ build_index=True,+ processing_mode="vectors_only",+ )++ assert result == {"status": "success", "root_uri": "viking://resources/demo"}+ viking_fs.persist_temp_tree.assert_awaited_once_with(+ "viking://temp/demo", "viking://resources/demo", ctx=ctx+ )+ rewrite_image_uris.assert_awaited_once_with(+ "viking://resources/demo",+ ctx=ctx,+ lock_handle="lock-1",+ )+ viking_fs.delete_temp.assert_awaited_once_with("tmp/demo", ctx=ctx)+ vectorize_file.assert_awaited_once()+ assert vectorize_file.await_args.kwargs["file_path"] == (+ "viking://resources/demo/section/page.md"+ )+ assert vectorize_file.await_args.kwargs["parent_uri"] == "viking://resources/demo/section"+ assert vectorize_file.await_args.kwargs["summary_dict"] == {+ "name": "page.md",+ "summary": "",+ }+ assert vectorize_file.await_args.kwargs["register_request_wait"] is True+ processor._delete_resource_semantic_markers.assert_not_awaited()+ processor._delete_resource_semantic_vectors.assert_not_awaited()+ lock.close.assert_awaited_once()+++async def test_vectors_only_skips_vectorization_when_build_index_false(monkeypatch, ctx):+ viking_fs = SimpleNamespace(+ persist_temp_tree=AsyncMock(),+ delete_temp=AsyncMock(),+ tree=AsyncMock(return_value=[]),+ )+ vectorize_file = AsyncMock()+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", AsyncMock())+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", vectorize_file)+ processor = ResourceProcessor(_FakeVikingDB())+ processor._delete_resource_semantic_markers = AsyncMock()+ processor._delete_resource_semantic_vectors = AsyncMock()+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())++ await processor.finish_prepared_resource(+ {+ "root_uri": "viking://resources/demo",+ "temp_uri": "viking://temp/demo",+ "source_committed": False,+ },+ ctx=ctx,+ resource_lock=lock,+ build_index=False,+ processing_mode="vectors_only",+ )++ processor._delete_resource_semantic_markers.assert_not_awaited()+ processor._delete_resource_semantic_vectors.assert_not_awaited()+ vectorize_file.assert_not_awaited()+++async def test_vectors_only_syncs_preexisting_target_instead_of_merging(monkeypatch, ctx):+ viking_fs = SimpleNamespace(+ persist_temp_tree=AsyncMock(),+ delete_temp=AsyncMock(),+ tree=AsyncMock(return_value=[]),+ )+ sync = AsyncMock()+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)+ monkeypatch.setattr("openviking.utils.resource_processor.SemanticProcessor", Mock())+ monkeypatch.setattr(+ "openviking.utils.resource_processor.SemanticProcessor.return_value._sync_topdown_recursive",+ sync,+ )+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", AsyncMock())+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", AsyncMock())+ processor = ResourceProcessor(_FakeVikingDB())+ processor._delete_resource_semantic_vectors = AsyncMock()+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())++ await processor.finish_prepared_resource(+ {+ "root_uri": "viking://resources/demo",+ "temp_uri": "viking://temp/demo",+ "temp_dir_path": "viking://temp/demo",+ "source_committed": False,+ "target_preexisting": True,+ },+ ctx=ctx,+ resource_lock=lock,+ build_index=True,+ processing_mode="vectors_only",+ )++ viking_fs.persist_temp_tree.assert_not_awaited()+ sync.assert_awaited_once_with(+ "viking://temp/demo",+ "viking://resources/demo",+ ctx=ctx,+ lock=lock,+ )+++async def test_vectors_only_leaves_existing_semantic_vectors_untouched(monkeypatch, ctx):+ viking_fs = SimpleNamespace(+ persist_temp_tree=AsyncMock(),+ delete_temp=AsyncMock(),+ tree=AsyncMock(return_value=[]),+ )+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", AsyncMock())+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", AsyncMock())+ processor = ResourceProcessor(_FakeVikingDB())+ processor._delete_resource_semantic_vectors = AsyncMock()+ processor._delete_removed_resource_vectors = AsyncMock()+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())++ await processor.finish_prepared_resource(+ {+ "root_uri": "viking://resources/demo",+ "temp_uri": "viking://temp/demo",+ "source_committed": False,+ },+ ctx=ctx,+ resource_lock=lock,+ build_index=True,+ processing_mode="vectors_only",+ )++ processor._delete_resource_semantic_vectors.assert_not_awaited()+++async def test_vectors_only_deletes_sync_removed_detail_vectors(monkeypatch, ctx):+ viking_fs = SimpleNamespace(+ persist_temp_tree=AsyncMock(),+ delete_temp=AsyncMock(),+ tree=AsyncMock(return_value=[]),+ )+ diff = SimpleNamespace(+ deleted_files=["viking://resources/demo/old.md"],+ deleted_dirs=["viking://resources/demo/old-dir"],+ )+ monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)+ monkeypatch.setattr("openviking.utils.resource_processor.SemanticProcessor", Mock())+ monkeypatch.setattr(+ "openviking.utils.resource_processor.SemanticProcessor.return_value._sync_topdown_recursive",+ AsyncMock(return_value=diff),+ )+ monkeypatch.setattr("openviking.utils.resource_processor.rewrite_image_uris", AsyncMock())+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", AsyncMock())+ processor = ResourceProcessor(_FakeVikingDB())+ processor._delete_resource_semantic_vectors = AsyncMock()+ processor._delete_removed_resource_vectors = AsyncMock()+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())++ await processor.finish_prepared_resource(+ {+ "root_uri": "viking://resources/demo",+ "temp_uri": "viking://temp/demo",+ "source_committed": False,+ "target_preexisting": True,+ },+ ctx=ctx,+ resource_lock=lock,+ build_index=True,+ processing_mode="vectors_only",+ )++ processor._delete_removed_resource_vectors.assert_awaited_once_with(+ files=["viking://resources/demo/old.md"],+ dirs=["viking://resources/demo/old-dir"],+ ctx=ctx,+ )+++async def test_delete_removed_resource_vectors_deletes_detail_records(ctx):+ vikingdb = _RecordingVikingDB()+ processor = ResourceProcessor(vikingdb)++ await processor._delete_removed_resource_vectors(+ files=["viking://resources/demo/old.md"],+ dirs=["viking://resources/demo/old-dir"],+ ctx=ctx,+ )++ assert vikingdb.lookup_calls == [+ ("viking://resources/demo/old.md", 2, 100, ctx),+ ]+ assert len(vikingdb.filter_calls) == 1+ assert vikingdb.filter_calls[0][1] == 100_000+ assert vikingdb.delete_calls == [+ (["viking://resources/demo/old.md:2"], ctx),+ (["recursive-child-detail"], ctx),+ ]