Skip to content

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

资源导入:支持解析后不拆分文档 (#3645)

Kchen8d1d52fe5dcb
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index b487d5a4a..6a34df5f3 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -1821,7 +1821,7 @@ mod tests {
use super::{BaseClient, HttpClient, TimeoutConfig};
use crate::base_client::api_error_from_envelope;
use reqwest::StatusCode;
- use serde_json::json;
+ use serde_json::{Map, json};
use std::collections::HashMap;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
@@ -1858,6 +1858,78 @@ mod tests {
assert!(body.as_object().unwrap().contains_key("args"));
}
+ #[tokio::test]
+ async fn add_resource_sends_parse_mode_through_args() {
+ let (default_url, default_request_rx) = spawn_request_capture_server().await;
+ let default_client = HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
+ default_client
+ .add_resource(
+ "https://example.com/default.md",
+ None,
+ None,
+ None,
+ None,
+ "",
+ "",
+ false,
+ None,
+ false,
+ None,
+ None,
+ None,
+ true,
+ 0.0,
+ "semantic_and_vectors".to_string(),
+ None,
+ Vec::new(),
+ "replace".to_string(),
+ false,
+ false,
+ )
+ .await
+ .expect("default add-resource request should succeed");
+ let default_request = default_request_rx
+ .await
+ .expect("request should be captured");
+ assert!(!default_request.contains("parse_mode"));
+
+ let (no_split_url, no_split_request_rx) = spawn_request_capture_server().await;
+ let no_split_client =
+ HttpClient::new(no_split_url, None, None, None, None, 5.0, false, None);
+ let mut no_split_args = Map::new();
+ no_split_args.insert("parse_mode".to_string(), json!("no_split"));
+ no_split_client
+ .add_resource(
+ "https://example.com/manual.pdf",
+ None,
+ None,
+ None,
+ None,
+ "",
+ "",
+ false,
+ None,
+ false,
+ None,
+ None,
+ None,
+ true,
+ 0.0,
+ "semantic_and_vectors".to_string(),
+ Some(no_split_args),
+ Vec::new(),
+ "replace".to_string(),
+ false,
+ false,
+ )
+ .await
+ .expect("no_split add-resource request should succeed");
+ let no_split_request = no_split_request_rx
+ .await
+ .expect("request should be captured");
+ assert!(no_split_request.contains(r#""args":{"parse_mode":"no_split"}"#));
+ }
+
#[test]
fn compact_request_body_drops_default_processing_mode_for_legacy_servers() {
let mut body = json!({
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 76607af15..5f62aa244 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -4118,6 +4118,22 @@ mod tests {
assert!(help.contains("--progress"));
assert!(help.contains("--no-progress"));
assert!(help.contains("--verbose"));
+ assert!(!help.contains("--parse-mode"));
+ assert!(help.contains("--args"));
+ }
+
+ #[test]
+ fn cli_add_resource_rejects_top_level_parse_mode() {
+ assert!(
+ Cli::try_parse_from([
+ "ov",
+ "add-resource",
+ "./README.md",
+ "--parse-mode",
+ "no_split",
+ ])
+ .is_err()
+ );
}
#[test]
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index 2305e724b..311d70552 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -143,7 +143,7 @@ This endpoint is the core entry point for resource management, supporting adding
**Processing Flow**:
1. Identify and validate the resource source (URL or uploaded temporary file)
2. Resolve the target URI
-3. Call the corresponding Parser to parse content
+3. Call the corresponding format Parser; `args.parse_mode` controls whether the converted Markdown body may be split
4. Build the directory tree and write to AGFS
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
@@ -178,7 +178,7 @@ This endpoint is the core entry point for resource management, supporting adding
| exclude | string | No | None | File patterns to exclude (glob) |
| directly_upload_media | bool | No | True | Whether to directly upload media files |
| 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` |
+| args | object | No | `{}` | Parser-specific import options forwarded to the source parser/accessor. `args.parse_mode` accepts `default` (existing splitting behavior) or `no_split` (parse and convert each source document to one Markdown body). 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 |
@@ -204,6 +204,9 @@ This endpoint is the core entry point for resource management, supporting adding
- Feishu/Lark user-token watches require `FEISHU_APP_ID` and `FEISHU_APP_SECRET` (or `feishu.app_id` and `feishu.app_secret` in `ov.conf`) because Feishu refresh tokens are bound to the app that issued them. The supplied user token must come from the same Feishu app configured in OpenViking.
- Watch task token state is stored in the internal `viking://resources/.watch_tasks.json` control file and is hidden from watch API/MCP/CLI responses. If VikingFS file encryption is enabled, this control file is encrypted at rest; otherwise the server-side control file contains plaintext token state.
- For local directory inputs, scanning respects `.gitignore` files (root and nested) with standard Git semantics; `ignore_dirs`, `include`, and `exclude` further refine what is ingested.
+- `args.parse_mode=no_split` still invokes the normal format Parser. PDF, Word, PowerPoint, HTML, and other supported documents are converted to Markdown, but heading-, paragraph-, and size-based splitting is skipped. A directory import applies this independently to each supported document and continues to honor `.gitignore`, filters, and `preserve_structure`.
+- For a single-file input in `no_split` mode, when parsing produces exactly one visible file and `to` is omitted, that file is stored directly under the resolved parent (for example, `guide.md` becomes `viking://resources/guide.md`). No wrapper directory or directory-level `.abstract.md` / `.overview.md` is created. If parsing also produces images or other visible files, the wrapper directory is retained. An explicit `to` is always preserved as the exact final URI.
+- `no_split` changes only the stored Markdown layout. Semantic processing, file vectorization, and any internal embedding chunking remain unchanged. Relative Markdown links are resolved against the same no-split output layout, so links do not point to split-only paths. A configured Understanding parser that cannot guarantee a single Markdown body returns an explicit unsupported-mode error.
- To create or update plain text directly, use [content/write](03-filesystem.md#write) instead of `add_resource`. Semantic processing and embeddings are refreshed automatically after resource ingestion and content writes.
#### 3. Usage Examples
@@ -322,6 +325,12 @@ result = client.add_resource(
)
print(f"Added: {result['root_uri']}")
+# Parse each document to Markdown without splitting its body
+result = client.add_resource(
+ "./documents",
+ args={"parse_mode": "no_split"},
+)
+
# Add from URL to specific location
result = client.add_resource(
"https://example.com/api-docs.md",
@@ -390,6 +399,7 @@ client.add_resource(
const task = await client.addResource("https://example.com/docs", {
to: "viking://resources/docs/",
wait: true,
+ args: { parse_mode: "no_split" },
});
console.log(task);
```
@@ -400,6 +410,7 @@ console.log(task);
result, err := client.AddResource(ctx, "./documents/guide.md", &openviking.AddResourceOptions{
Reason: "User guide documentation",
Wait: true,
+ Args: map[string]any{"parse_mode": "no_split"},
})
if err != nil {
return err
@@ -413,6 +424,9 @@ fmt.Println(result["root_uri"])
# Add local file
ov add-resource ./documents/guide.md --reason "User guide"
+# Parse each document to one Markdown body
+ov add-resource ./documents --args parse_mode:no_split
+
# Add from URL
ov add-resource https://example.com/guide.md --to viking://resources/guide.md
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md
index 88bffcea3..4a48511d1 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 13 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), `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) |
+| `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, including `{"parse_mode":"no_split"}` to parse each source document into one Markdown body, `{"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` |
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index 7c3d284c7..4d022ce7e 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -136,7 +136,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
**处理流程**:
1. 识别并校验资源来源(URL 或上传的临时文件)
2. 解析目标 URI
-3. 调用对应 Parser 解析内容
+3. 调用对应格式 Parser;`args.parse_mode` 控制转换后的 Markdown 正文是否允许拆分
4. 构建目录树并写入 AGFS
5. 按 `processing_mode` 执行入库后的处理:`semantic_and_vectors` 生成语义产物和向量;`vectors_only` 跳过语义理解,只提交文件向量化
6. `wait=true` 时等待语义处理/向量化完成;`wait=false` 时返回 `task_id` 用于队列跟踪
@@ -171,7 +171,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
| exclude | string | 否 | None | 排除的文件模式(glob) |
| directly_upload_media | bool | 否 | True | 是否直接上传媒体文件 |
| 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` |
+| args | object | 否 | `{}` | 传给特定 parser/accessor 的导入参数。`args.parse_mode` 支持 `default`(保持现有拆分行为)和 `no_split`(正常解析并将每个源文档正文保存为一个 Markdown 文件)。例如 `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 总结,只对当前资源文件生成向量 |
| tags | string[] | 否 | None | 导入时写入向量检索记录的显式检索标签,格式必须是 `k=v`,例如 `["team=search", "env=test"]`。搜索接口可用同名 `tags` 参数过滤召回 |
@@ -198,6 +198,9 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
- 飞书/Lark 用户 token watch 需要 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`,或 `ov.conf` 中的 `feishu.app_id` 和 `feishu.app_secret`。飞书 refresh token 绑定签发它的应用,因此传入的用户 token 必须来自 OpenViking 当前配置的同一个飞书应用。
- Watch task 的 token 状态保存在内部控制文件 `viking://resources/.watch_tasks.json` 中,不会出现在 watch API/MCP/CLI 返回里。若启用了 VikingFS 文件加密,该控制文件会静态加密;否则服务端控制文件中会包含明文 token 状态。
- 本地目录输入会遵循 `.gitignore`(根目录和子目录,标准 Git 语义);`ignore_dirs`、`include`、`exclude` 会在此基础上进一步过滤。
+- `args.parse_mode=no_split` 仍调用正常的格式 Parser。PDF、Word、PowerPoint、HTML 等受支持文档会转换为 Markdown,但跳过按标题、段落和长度拆分。目录导入会对每个受支持文档分别应用该规则,并继续遵循 `.gitignore`、筛选参数和 `preserve_structure`。
+- 对单文件输入使用 `no_split` 时,如果解析结果恰好只有一个可见文件且未指定 `to`,该文件会直接放到解析出的父目录下(例如 `guide.md` 写入 `viking://resources/guide.md`),不会创建同名上层目录,也不会生成目录级 `.abstract.md` / `.overview.md`。如果解析结果还包含图片等其他可见文件,则保留上层目录。显式指定的 `to` 始终作为最终 URI 原样保留。
+- `no_split` 只改变 Markdown 正文的存储布局,不改变语义处理、文件向量化和内部 embedding 分块。Markdown 相对链接会按同一个 no-split 输出布局解析,不会再指向仅拆分模式存在的路径。如果配置的 Understanding 解析器无法保证单一 Markdown 正文,接口会明确返回不支持该模式的错误。
- 如果要直接创建或更新纯文本内容,请使用 [content/write](03-filesystem.md#write),不要使用 `add_resource`。资源导入和内容写入后都会自动刷新语义与 embedding。
#### 3. 使用示例
@@ -327,6 +330,12 @@ result = client.add_resource(
)
print(f"Added: {result['root_uri']}")
+## 正常解析并转换为 Markdown,但每个文档正文不拆分
+result = client.add_resource(
+ "./documents",
+ args={"parse_mode": "no_split"},
+)
+
## 从 URL 添加到指定位置
result = client.add_resource(
"https://example.com/api-docs.md",
@@ -395,6 +404,7 @@ client.add_resource(
const task = await client.addResource("https://example.com/docs", {
to: "viking://resources/docs/",
wait: true,
+ args: { parse_mode: "no_split" },
});
console.log(task);
```
@@ -405,6 +415,7 @@ console.log(task);
result, err := client.AddResource(ctx, "./documents/guide.md", &openviking.AddResourceOptions{
Reason: "User guide documentation",
Wait: true,
+ Args: map[string]any{"parse_mode": "no_split"},
})
if err != nil {
return err
@@ -418,6 +429,9 @@ fmt.Println(result["root_uri"])
# 添加本地文件
ov add-resource ./documents/guide.md --reason "User guide"
+# 正常解析,每个源文档只生成一个 Markdown 正文
+ov add-resource ./documents --args parse_mode:no_split
+
# 从 URL 添加
ov add-resource https://example.com/guide.md --to viking://resources/guide.md
diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.md
index e51909290..14c8560fe 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 的自动刷新周期), `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-..."}`) |
+| `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 参数,包括 `{"parse_mode":"no_split"}` 用于正常解析但每个源文档只生成一个 Markdown 正文、飞书一次性用户 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` |
diff --git a/openviking/connector/delegate.py b/openviking/connector/delegate.py
index 93eb56138..6ce988044 100644
--- a/openviking/connector/delegate.py
+++ b/openviking/connector/delegate.py
@@ -32,6 +32,7 @@ from openviking.connector.routing import (
is_full_commit_sha,
)
from openviking.core.content_targets import ContentTargetSpec
+from openviking.parse.mode import ParseMode
from openviking.resource.processing_mode import (
DEFAULT_PROCESSING_MODE,
VECTORS_ONLY,
@@ -113,6 +114,7 @@ class ConnectorDelegate:
build_index: bool = True,
summarize: bool = False,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
+ parse_mode: ParseMode = ParseMode.DEFAULT,
watch_interval: float = 0,
connector_args: Optional[Dict[str, Any]] = None,
kwargs: Optional[Dict[str, Any]] = None,
@@ -203,6 +205,7 @@ class ConnectorDelegate:
build_index=build_index,
summarize=summarize,
processing_mode=processing_mode,
+ parse_mode=parse_mode,
watch_interval=watch_interval,
connector_args=connector_args,
kwargs=kwargs or {},
@@ -234,6 +237,7 @@ class ConnectorDelegate:
build_index: bool,
summarize: bool,
processing_mode: ProcessingMode,
+ parse_mode: ParseMode,
watch_interval: float,
connector_args: Dict[str, Any],
kwargs: Dict[str, Any],
@@ -245,6 +249,8 @@ class ConnectorDelegate:
Returns an empty list when the request is fully supported.
"""
unsupported: List[str] = []
+ if parse_mode is ParseMode.NO_SPLIT:
+ unsupported.append("parse_mode=no_split")
if wait:
unsupported.append("wait=true (Connector imports run asynchronously)")
if parent:
diff --git a/openviking/core/building_tree.py b/openviking/core/building_tree.py
index 5517a269f..b726f953a 100644
--- a/openviking/core/building_tree.py
+++ b/openviking/core/building_tree.py
@@ -29,6 +29,7 @@ class BuildingTree:
self._uri_map: Dict[str, "Context"] = {}
self._root_uri: Optional[str] = None
self._candidate_uri: Optional[str] = None
+ self._root_is_file = False
def add_context(self, context: "Context") -> None:
"""Add a context to the tree."""
diff --git a/openviking/parse/__init__.py b/openviking/parse/__init__.py
index d4b4f0370..f2a1231ab 100644
--- a/openviking/parse/__init__.py
+++ b/openviking/parse/__init__.py
@@ -11,6 +11,7 @@ from openviking.parse.directory_scan import (
DirectoryScanResult,
scan_directory,
)
+from openviking.parse.mode import ParseMode, ParseModeInput
from openviking.parse.parsers.base_parser import BaseParser
from openviking.parse.parsers.html import HTMLParser
from openviking.parse.parsers.markdown import MarkdownParser
@@ -42,4 +43,6 @@ __all__ = [
"ClassifiedFile",
"DirectoryScanResult",
"scan_directory",
+ "ParseMode",
+ "ParseModeInput",
]
diff --git a/openviking/parse/mode.py b/openviking/parse/mode.py
new file mode 100644
index 000000000..0d802d511
--- /dev/null
+++ b/openviking/parse/mode.py
@@ -0,0 +1,26 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Shared add-resource parsing modes."""
+
+from enum import Enum
+from typing import Literal, TypeAlias
+
+from openviking_cli.exceptions import InvalidArgumentError
+
+
+class ParseMode(str, Enum):
+ """Controls whether parsed Markdown is split into multiple files."""
+
+ DEFAULT = "default"
+ NO_SPLIT = "no_split"
+
+
+ParseModeInput: TypeAlias = ParseMode | Literal["default", "no_split"]
+
+
+def normalize_parse_mode(value: str | ParseMode) -> ParseMode:
+ """Return a validated parse mode for HTTP and embedded callers."""
+ try:
+ return ParseMode(value)
+ except (TypeError, ValueError) as exc:
+ raise InvalidArgumentError("parse_mode must be one of: default, no_split.") from exc
diff --git a/openviking/parse/parser_router.py b/openviking/parse/parser_router.py
index d629b78ee..5b8a1c01b 100644
--- a/openviking/parse/parser_router.py
+++ b/openviking/parse/parser_router.py
@@ -13,6 +13,7 @@ from urllib.parse import urlparse
from openviking.parse.accessors.base import LocalResource, SourceType
from openviking.parse.base import ParseResult
from openviking.parse.registry import ParserRegistry
+from openviking_cli.exceptions import InvalidArgumentError
from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
@@ -120,6 +121,12 @@ class ParserRouter:
)
)
+ if use_understanding and kwargs.get("split_content") is False:
+ raise InvalidArgumentError(
+ "parse_mode='no_split' is not supported by the configured "
+ "Understanding parser."
+ )
+
if use_understanding:
display = source_path
if isinstance(source_path, str) and source_path.startswith(("http://", "https://")):
diff --git a/openviking/parse/parsers/directory.py b/openviking/parse/parsers/directory.py
index b1056aea5..f01291703 100644
--- a/openviking/parse/parsers/directory.py
+++ b/openviking/parse/parsers/directory.py
@@ -204,6 +204,7 @@ class DirectoryParser(BaseParser):
warnings,
preserve_structure=preserve_structure,
import_root=str(source_path),
+ split_content=kwargs.get("split_content", True),
)
if ok:
@@ -358,6 +359,7 @@ class DirectoryParser(BaseParser):
warnings: List[str],
preserve_structure: bool = True,
import_root: Optional[str] = None,
+ split_content: bool = True,
) -> bool:
"""Process one file into the VikingFS directory temp.
@@ -388,6 +390,8 @@ class DirectoryParser(BaseParser):
# an md may reference shared images outside its own directory
# (e.g. ../images/x.gif) that still live inside the import.
allowed_media_dirs=[Path(import_root)] if import_root else None,
+ split_content=split_content,
+ flatten_single_output=bool(not split_content and preserve_structure),
)
if sub_result.temp_dir_path:
if preserve_structure:
@@ -399,6 +403,7 @@ class DirectoryParser(BaseParser):
viking_fs,
sub_result.temp_dir_path,
dest,
+ flatten_single_output=bool(not split_content and preserve_structure),
)
return True
except Exception as exc:
@@ -466,15 +471,77 @@ class DirectoryParser(BaseParser):
viking_fs: Any,
src_temp_uri: str,
dest_uri: str,
+ *,
+ flatten_single_output: bool = False,
) -> None:
"""Move all content from a parser's temp directory into *dest_uri*.
After the move the source temp is deleted. Hidden files stay filtered,
except the sidecars in :data:`_MERGE_SIDECAR_ALLOWLIST` that downstream
steps depend on (e.g. ``.image_mappings.json`` for the post-commit
- image rewrite).
+ image rewrite). In no-split directory imports, a wrapper containing one
+ standalone file is promoted into ``dest_uri``; wrappers with additional
+ files, directories, sidecars, or destination-name conflicts are retained.
"""
entries = await viking_fs.ls(src_temp_uri, show_all_hidden=True, node_limit=LS_ALL_NODES)
+ merge_entries = [
+ entry
+ for entry in entries
+ if entry.get("name") not in ("", ".", "..")
+ and (
+ DirectoryParser._is_dir_entry(entry)
+ or not entry.get("name", "").startswith(".")
+ or entry.get("name") in _MERGE_SIDECAR_ALLOWLIST
+ )
+ ]
+ if flatten_single_output and len(merge_entries) == 1:
+ wrapper = merge_entries[0]
+ if DirectoryParser._is_dir_entry(wrapper):
+ wrapper_uri = wrapper.get(
+ "uri",
+ f"{src_temp_uri.rstrip('/')}/{wrapper['name']}",
+ )
+ wrapper_entries = await viking_fs.ls(
+ wrapper_uri,
+ show_all_hidden=True,
+ node_limit=LS_ALL_NODES,
+ )
+ payloads = [
+ entry
+ for entry in wrapper_entries
+ if entry.get("name") not in ("", ".", "..")
+ and (
+ not entry.get("name", "").startswith(".")
+ or entry.get("name") in _MERGE_SIDECAR_ALLOWLIST
+ )
+ ]
+ if len(payloads) == 1 and not DirectoryParser._is_dir_entry(payloads[0]):
+ payload = payloads[0]
+ await viking_fs.mkdir(dest_uri, exist_ok=True)
+ destination_entries = await viking_fs.ls(
+ dest_uri,
+ show_all_hidden=True,
+ node_limit=LS_ALL_NODES,
+ )
+ destination_names = {
+ entry.get("name")
+ for entry in destination_entries
+ if entry.get("name") not in ("", ".", "..")
+ }
+ if payload.get("name") not in destination_names:
+ src = payload.get(
+ "uri",
+ f"{wrapper_uri.rstrip('/')}/{payload['name']}",
+ )
+ await viking_fs.move_file(
+ src,
+ f"{dest_uri.rstrip('/')}/{payload['name']}",
+ )
+ try:
+ await viking_fs.delete_temp(src_temp_uri)
+ except Exception:
+ pass
+ return
for entry in entries:
name = entry.get("name", "")
if not name or name in (".", ".."):
diff --git a/openviking/parse/parsers/excel.py b/openviking/parse/parsers/excel.py
index c1f23bd6d..d8c610c77 100644
--- a/openviking/parse/parsers/excel.py
+++ b/openviking/parse/parsers/excel.py
@@ -212,11 +212,13 @@ class ExcelParser(BaseParser):
parse_started = time.perf_counter()
loop = asyncio.get_running_loop()
temp_uri = self._md_parser._create_temp_uri()
- layout_kwargs = {
+ layout_kwargs: Dict[str, Any] = {
key: value
for key, value in kwargs.items()
if key in {"resource_name", "source_name"} and isinstance(value, str)
}
+ if isinstance(kwargs.get("split_content"), bool):
+ layout_kwargs["split_content"] = kwargs["split_content"]
future = loop.run_in_executor(
_get_excel_layout_executor(self._process_pool_workers()),
partial(
diff --git a/openviking/parse/parsers/markdown.py b/openviking/parse/parsers/markdown.py
index e80b46ab7..3a10c9111 100644
--- a/openviking/parse/parsers/markdown.py
+++ b/openviking/parse/parsers/markdown.py
@@ -263,12 +263,29 @@ class MarkdownParser(BaseParser):
start_time = time.time()
try:
+ split_content = bool(kwargs.get("split_content", True))
+ adaptive_flatten_requested = bool(
+ kwargs.get("flatten_single_output", False) and not split_content
+ )
+ flatten_single_output = adaptive_flatten_requested
+ if flatten_single_output:
+ flatten_single_output = not await self._has_ingestable_local_image(
+ content,
+ base_dir=base_dir,
+ allowed_media_dirs=allowed_media_dirs,
+ )
# Phase 1 — parse only: turn the markdown into an ordered VikingFS write
# plan, touching nothing. The temp URI is allocated here (the one
# FS-scoped step) and threaded in so layout planning stays side-effect free.
temp_uri = self._create_temp_uri()
+ layout_kwargs = dict(kwargs)
+ layout_kwargs["flatten_single_output"] = flatten_single_output
layout = await self._compute_layout(
- content, temp_uri, source_path=source_path, instruction=instruction, **kwargs
+ content,
+ temp_uri,
+ source_path=source_path,
+ instruction=instruction,
+ **layout_kwargs,
)
# Set up relative-link rewrite context consumed by _write_section during
@@ -284,6 +301,9 @@ class MarkdownParser(BaseParser):
"import_root": kwargs.get("link_rewrite_root"),
"base_dir": base_dir,
"allowed_media_dirs": allowed_media_dirs,
+ "split_content": split_content,
+ "adaptive_flatten_requested": adaptive_flatten_requested,
+ "flatten_single_output": flatten_single_output,
}
# Phase 2 — write only: replay the plan against the real VikingFS,
@@ -367,14 +387,26 @@ class MarkdownParser(BaseParser):
root_name = (
source_name if source_name and supports_code_skeleton(source_name) else doc_name
)
- root_dir = f"{temp_uri}/{self._sanitize_for_path(root_name)}"
+ root_dir = (
+ temp_uri
+ if kwargs.get("flatten_single_output", False)
+ else f"{temp_uri}/{self._sanitize_for_path(root_name)}"
+ )
# Find all headings
headings = self._find_headings(content)
# The temp dir is the first thing materialized on apply.
ops: List[_LayoutOp] = [_LayoutOp("mkdir", temp_uri)]
- await self._build_structure(ops, content, headings, root_dir, source_path, doc_name)
+ await self._build_structure(
+ ops,
+ content,
+ headings,
+ root_dir,
+ source_path,
+ doc_name,
+ split_content=kwargs.get("split_content", True),
+ )
return _Layout(
temp_uri=temp_uri,
@@ -470,6 +502,34 @@ class MarkdownParser(BaseParser):
return True
return False
+ async def _has_ingestable_local_image(
+ self,
+ content: str,
+ *,
+ base_dir: Optional[Path],
+ allowed_media_dirs: Optional[List[Path]],
+ ) -> bool:
+ """Return whether parsing will materialize at least one local image."""
+ from openviking.parse.image_rewrite import HTML_IMG_PATTERN
+
+ image_refs = [match.group(2) for match in self._image_pattern.finditer(content)]
+ image_refs.extend(match.group(2) for match in HTML_IMG_PATTERN.finditer(content))
+ seen: set[Path] = set()
+ for image_ref in image_refs:
+ if self._is_remote_uri(image_ref):
+ continue
+ resolved = self._resolve_image_path(image_ref, base_dir, allowed_media_dirs)
+ if resolved is None or resolved in seen:
+ continue
+ seen.add(resolved)
+ try:
+ image_bytes = await asyncio.to_thread(resolved.read_bytes)
+ if await asyncio.to_thread(self._is_valid_image, image_bytes, resolved):
+ return True
+ except Exception:
+ continue
+ return False
+
def _extract_frontmatter(self, content: str) -> Tuple[str, Optional[Dict[str, Any]]]:
"""
Extract YAML frontmatter from content.
@@ -1060,7 +1120,10 @@ class MarkdownParser(BaseParser):
src_dir = os.path.dirname(os.path.abspath(source_path))
import_root_abs = os.path.abspath(import_root)
- source_new_dir = os.path.join(src_dir, doc_name, section_subpath)
+ if (self._rewrite_ctx or {}).get("flatten_single_output", False):
+ source_new_dir = os.path.join(src_dir, section_subpath)
+ else:
+ source_new_dir = os.path.join(src_dir, doc_name, section_subpath)
out: List[str] = []
last = 0
@@ -1100,12 +1163,24 @@ class MarkdownParser(BaseParser):
side-effect-free parse, cached per parse_content() call. None on parse failure."""
ctx = self._rewrite_ctx or {}
cache = ctx.setdefault("_split_cache", {})
- key = os.path.abspath(target_path)
+ split_content = bool(ctx.get("split_content", True))
+ flatten_single_output = bool(ctx.get("adaptive_flatten_requested", False))
+ key = (os.path.abspath(target_path), split_content, flatten_single_output)
if key not in cache:
- cache[key] = await self._probe_split_layout(target_path)
+ cache[key] = await self._probe_split_layout(
+ target_path,
+ split_content=split_content,
+ flatten_single_output=flatten_single_output,
+ )
return cache[key]
- async def _probe_split_layout(self, target_path: str) -> Optional[Dict[str, str]]:
+ async def _probe_split_layout(
+ self,
+ target_path: str,
+ *,
+ split_content: bool,
+ flatten_single_output: bool = False,
+ ) -> Optional[Dict[str, str]]:
"""Plan the target's layout WITHOUT writing anything, returning
{"<doc_dir>/<section...>": text} keyed by path relative to the temp root, i.e.
INCLUDING the doc-root dir segment so callers can map each key straight onto
@@ -1113,8 +1188,19 @@ class MarkdownParser(BaseParser):
with a throwaway temp URI, so no fake FS and no side effects are involved."""
try:
probe_root = "viking://temp/_probe"
+ content = self._read_file(target_path)
+ if flatten_single_output:
+ flatten_single_output = not await self._has_ingestable_local_image(
+ content,
+ base_dir=Path(target_path).parent,
+ allowed_media_dirs=(self._rewrite_ctx or {}).get("allowed_media_dirs"),
+ )
layout = await self._compute_layout(
- self._read_file(target_path), probe_root, source_path=str(target_path)
+ content,
+ probe_root,
+ source_path=str(target_path),
+ split_content=split_content,
+ flatten_single_output=flatten_single_output,
)
root = layout.temp_uri.rstrip("/")
out: Dict[str, str] = {}
@@ -1165,6 +1251,7 @@ class MarkdownParser(BaseParser):
root_dir: str,
source_path: Optional[str] = None,
doc_name: Optional[str] = None,
+ split_content: bool = True,
) -> None:
"""
Plan the document's directory/file layout into ``ops`` (no VikingFS writes).
@@ -1182,6 +1269,7 @@ class MarkdownParser(BaseParser):
headings: List of (start, end, title, level) tuples
root_dir: Root directory URI
source_path: Source file path for naming
+ split_content: Whether large Markdown may be split into multiple files
"""
max_size = self.config.max_section_size or self.DEFAULT_MAX_SECTION_SIZE
max_chars = self.config.max_section_chars
@@ -1198,6 +1286,12 @@ class MarkdownParser(BaseParser):
_smart_stem(source_path) if source_path else "content"
)
+ if not split_content:
+ file_path = f"{root_dir}/{doc_name}.md"
+ ops.append(_LayoutOp("write", file_path, content))
+ logger.debug(f"[MarkdownParser] No-split document planned as: {file_path}")
+ return
+
# Small document: save as single file (check both token and char limits)
if estimated_tokens <= max_size and len(content) <= max_chars:
file_path = f"{root_dir}/{doc_name}.md"
diff --git a/openviking/parse/parsers/pdf.py b/openviking/parse/parsers/pdf.py
index d6a56301a..4d7acca20 100644
--- a/openviking/parse/parsers/pdf.py
+++ b/openviking/parse/parsers/pdf.py
@@ -140,6 +140,7 @@ class PDFParser(BaseParser):
source_name=resource_name,
base_dir=pdf_path.parent,
allowed_media_dirs=[storage.media_dir],
+ split_content=kwargs.get("split_content", True),
)
# Step 3: Update metadata for PDF origin
diff --git a/openviking/parse/parsers/word.py b/openviking/parse/parsers/word.py
index e2c7ae20e..0a76f110a 100644
--- a/openviking/parse/parsers/word.py
+++ b/openviking/parse/parsers/word.py
@@ -69,6 +69,7 @@ class WordParser(BaseParser):
# docx images are extracted into storage.media_dir, so (like pdf)
# that is the only derived-media root needed.
allowed_media_dirs=[storage.media_dir],
+ split_content=kwargs.get("split_content", True),
)
else:
result = await self._md_parser.parse_content(
@@ -76,6 +77,7 @@ class WordParser(BaseParser):
instruction=instruction,
resource_name=kwargs.get("resource_name"),
source_name=kwargs.get("source_name"),
+ split_content=kwargs.get("split_content", True),
)
result.source_format = "docx"
result.parser_name = "WordParser"
diff --git a/openviking/parse/tree_builder.py b/openviking/parse/tree_builder.py
index 0ae3b2e07..a44109813 100644
--- a/openviking/parse/tree_builder.py
+++ b/openviking/parse/tree_builder.py
@@ -153,6 +153,7 @@ class TreeBuilder:
source_path: Optional[str] = None,
source_format: Optional[str] = None,
create_parent: bool = False,
+ flatten_single_file: bool = False,
) -> "BuildingTree":
"""
Finalize URI metadata for a temp parse result.
@@ -181,6 +182,18 @@ class TreeBuilder:
original_name = doc_dirs[0]["name"]
doc_name = VikingURI.sanitize_segment(original_name)
temp_doc_uri = f"{temp_uri}/{original_name}" # use original name to find temp dir
+ root_is_file = False
+ if flatten_single_file:
+ doc_entries = [
+ entry
+ for entry in await viking_fs.ls(temp_doc_uri, ctx=ctx)
+ if entry.get("name") not in [".", ".."]
+ ]
+ if len(doc_entries) == 1 and not doc_entries[0].get("isDir"):
+ original_name = doc_entries[0]["name"]
+ doc_name = VikingURI.sanitize_segment(original_name)
+ temp_doc_uri = f"{temp_doc_uri}/{original_name}"
+ root_is_file = True
if original_name != doc_name:
logger.debug(f"[TreeBuilder] Sanitized doc name: {original_name!r} -> {doc_name!r}")
@@ -200,6 +213,7 @@ class TreeBuilder:
source_format=source_format,
)
tree._root_uri = planned_uri
+ tree._root_is_file = root_is_file
if unique_candidate_uri:
tree._candidate_uri = unique_candidate_uri
diff --git a/openviking/resource/watch_manager.py b/openviking/resource/watch_manager.py
index ec4a93db8..de8b841b2 100644
--- a/openviking/resource/watch_manager.py
+++ b/openviking/resource/watch_manager.py
@@ -62,6 +62,10 @@ class WatchTask(BaseModel):
)
path: str = Field(..., description="Resource path to monitor")
to_uri: Optional[str] = Field(None, description="Target URI")
+ to_is_directory: Optional[bool] = Field(
+ None,
+ description="Whether the target URI is a directory destination",
+ )
parent_uri: Optional[str] = Field(None, description="Parent URI")
reason: str = Field(default="", description="Reason for monitoring")
instruction: str = Field(default="", description="Monitoring instruction")
@@ -120,6 +124,7 @@ class WatchTask(BaseModel):
def to_storage_dict(self) -> Dict[str, Any]:
"""Convert task to dictionary for watch-task persistence."""
data = self.to_dict()
+ data["to_is_directory"] = self.to_is_directory
if self.auth_state is not None:
data["auth_state"] = self.auth_state
return data
@@ -384,6 +389,7 @@ class WatchManager:
user_id: str = "default",
original_role: str = "user",
to_uri: Optional[str] = None,
+ to_is_directory: Optional[bool] = None,
parent_uri: Optional[str] = None,
reason: str = "",
instruction: str = "",
@@ -428,6 +434,7 @@ class WatchManager:
task = WatchTask(
path=path,
to_uri=to_uri,
+ to_is_directory=to_is_directory,
parent_uri=parent_uri,
reason=reason,
instruction=instruction,
@@ -463,6 +470,7 @@ class WatchManager:
role: str,
path: Optional[str] = None,
to_uri: Optional[str] = None,
+ to_is_directory: Optional[bool] = None,
parent_uri: Optional[str] = None,
reason: Optional[str] = None,
instruction: Optional[str] = None,
@@ -521,6 +529,8 @@ class WatchManager:
task.path = path
if to_uri is not None:
task.to_uri = to_uri
+ if to_is_directory is not None:
+ task.to_is_directory = to_is_directory
if parent_uri is not None:
task.parent_uri = parent_uri
if reason is not None:
diff --git a/openviking/resource/watch_scheduler.py b/openviking/resource/watch_scheduler.py
index 8e7e3aca5..3e6cbfa85 100644
--- a/openviking/resource/watch_scheduler.py
+++ b/openviking/resource/watch_scheduler.py
@@ -286,6 +286,7 @@ class WatchScheduler:
path=task.path,
ctx=ctx,
to=task.to_uri,
+ to_is_directory=getattr(task, "to_is_directory", None),
parent=task.parent_uri,
reason=task.reason,
instruction=task.instruction,
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index 712a4ff9f..0999cbd52 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -29,6 +29,7 @@ from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.types import ASGIApp, Receive, Scope, Send
+from openviking.parse.mode import ParseMode, normalize_parse_mode
from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.retrieve.type_quota_recall import (
DEFAULT_MAX_CHARS,
@@ -578,13 +579,19 @@ async def add_resource(
tags: Optional explicit k=v retrieval tags to apply after ingestion.
tag_mode: Tag update mode, "replace" or "append". Defaults to "replace".
args: Parser-specific options, e.g. {"feishu_access_token": "..."} for Feishu imports,
- or {"site": true} for whole-site ingestion.
+ {"site": true} for whole-site ingestion, or {"parse_mode": "no_split"}
+ to keep each parsed document body in one file.
"""
from openviking.server.local_input_guard import require_remote_resource_source
service = get_service()
ctx = _get_ctx()
+ try:
+ mode = normalize_parse_mode((args or {}).get("parse_mode", ParseMode.DEFAULT))
+ except InvalidArgumentError as exc:
+ return f"Error: {exc}"
+
if watch_interval < 0:
return (
"Error: watch_interval must be >= 0. Use 0 for one-shot add (no watch); "
@@ -717,6 +724,7 @@ async def add_resource(
processing_mode=processing_mode,
tags=tags,
tag_mode=tag_mode,
+ parse_mode=mode.value,
)
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.py
index a8b60e240..83480425c 100644
--- a/openviking/server/resource_ingest.py
+++ b/openviking/server/resource_ingest.py
@@ -12,6 +12,7 @@ from __future__ import annotations
from typing import Any, Optional
+from openviking.parse.mode import ParseMode
from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
@@ -29,6 +30,7 @@ async def ingest_temp_upload(
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
tags: Optional[list[str]] = None,
tag_mode: str = "replace",
+ parse_mode: ParseMode | str = ParseMode.DEFAULT,
) -> dict[str, Any]:
"""Resolve a temp upload and ingest it as a resource; return the raw add_resource result.
@@ -44,6 +46,9 @@ async def ingest_temp_upload(
resolved = await store.resolve_for_consume(temp_file_id, ctx)
try:
try:
+ ingest_args = dict(args or {})
+ if parse_mode != ParseMode.DEFAULT and parse_mode != ParseMode.DEFAULT.value:
+ ingest_args.setdefault("parse_mode", str(parse_mode.value if isinstance(parse_mode, ParseMode) else parse_mode))
result = await get_service().resources.add_resource(
path=resolved.local_path,
ctx=ctx,
@@ -54,7 +59,7 @@ async def ingest_temp_upload(
processing_mode=processing_mode,
allow_local_path_resolution=True,
enforce_public_remote_targets=True,
- args=args,
+ args=ingest_args,
tags=tags,
tag_mode=tag_mode,
)
diff --git a/openviking/server/routers/resources.py b/openviking/server/routers/resources.py
index eaa142aa3..55cf40f0a 100644
--- a/openviking/server/routers/resources.py
+++ b/openviking/server/routers/resources.py
@@ -182,6 +182,7 @@ async def temp_upload(
processing_mode=signed.processing_mode,
tags=signed.tags,
tag_mode=signed.tag_mode,
+ parse_mode=signed.parse_mode,
)
try:
diff --git a/openviking/server/upload_token_store.py b/openviking/server/upload_token_store.py
index 35d8f61c6..046698be8 100644
--- a/openviking/server/upload_token_store.py
+++ b/openviking/server/upload_token_store.py
@@ -9,7 +9,7 @@ key, no on-disk state, no replay-set bookkeeping. ``dict.pop`` doubles as the
consume-and-burn primitive.
The token carries the identity bound at issue time (account/user), the caller's actor peer
-scope (``actor_peer_id``), and the business params (``to``/``reason``) so the server can
+scope (``actor_peer_id``), and the business params (``to``/``reason``/``parse_mode``) so the server can
finish ingestion automatically once the file lands — the caller does not re-invoke
``add_resource``, and the ingest keeps the original peer scope. The ``temp_file_id`` is minted by
:class:`openviking.server.temp_upload_store.TempUploadStore` at upload time, so the token
@@ -49,6 +49,7 @@ class _TokenInfo:
processing_mode: ProcessingMode
tags: Optional[list[str]]
tag_mode: str
+ parse_mode: str
expires_at: float
@@ -61,9 +62,10 @@ class ConsumedUploadToken:
to: str
reason: str
actor_peer_id: str
- processing_mode: ProcessingMode
- tags: Optional[list[str]]
- tag_mode: str
+ processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
+ tags: Optional[list[str]] = None
+ tag_mode: str = "replace"
+ parse_mode: str = "default"
class UploadTokenStore:
@@ -82,6 +84,7 @@ class UploadTokenStore:
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
tags: Optional[list[str]] = None,
tag_mode: str = "replace",
+ parse_mode: str = "default",
) -> Tuple[str, float]:
"""Mint a fresh token bound to (account, user) plus ``to``/``reason``/``actor_peer_id``.
@@ -101,6 +104,7 @@ class UploadTokenStore:
processing_mode,
tags,
tag_mode,
+ parse_mode,
expires_at,
)
for _ in range(8):
@@ -128,6 +132,7 @@ class UploadTokenStore:
info.processing_mode,
info.tags,
info.tag_mode,
+ info.parse_mode,
)
def peek(self, token: str) -> Optional[_TokenInfo]:
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index f7cc59ca5..d45598b79 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -19,6 +19,7 @@ from uuid import uuid4
from openviking.core.content_targets import ContentTargetSpec
from openviking.core.uri_validation import validate_optional_content_target_uri
+from openviking.parse.mode import ParseMode, normalize_parse_mode
from openviking.parse.parsers.constants import MPEG_TS_EXTENSION_ALIAS
from openviking.resource.feishu_watch_auth import (
FEISHU_ACCESS_TOKEN_ARG,
@@ -78,6 +79,7 @@ _ADD_RESOURCE_ARGS_RESERVED_FIELDS = frozenset(
"path",
"ctx",
"to",
+ "to_is_directory",
"parent",
"reason",
"instruction",
@@ -121,6 +123,7 @@ _INTERNAL_INGESTION_FIELDS = frozenset(
"route_source",
"skip_watch_management",
"stage_callback",
+ "to_is_directory",
"watch_auth_state",
"understanding_response_id",
"parser_backend",
@@ -140,6 +143,7 @@ class _ResourceSourceInfo:
class _NormalizedAddResourceArgs:
processor_kwargs: Dict[str, Any]
watch_auth_state: Optional[Dict[str, Any]] = None
+ parse_mode: ParseMode = ParseMode.DEFAULT
class ResourceService:
@@ -236,6 +240,7 @@ class ResourceService:
manage_watch: bool,
watch_interval: float,
target: ContentTargetSpec,
+ to_is_directory: bool,
root_uri: str,
path: str,
reason: str,
@@ -287,6 +292,7 @@ class ResourceService:
await self._handle_watch_task_creation(
path=path,
to_uri=watch_to,
+ to_is_directory=to_is_directory,
parent_uri=parent_uri,
reason=reason,
instruction=instruction,
@@ -332,6 +338,13 @@ class ResourceService:
)
normalized = dict(args)
+ raw_parse_mode = normalized.pop("parse_mode", ParseMode.DEFAULT)
+ try:
+ parse_mode = normalize_parse_mode(raw_parse_mode)
+ except InvalidArgumentError as exc:
+ raise InvalidArgumentError(
+ str(exc).replace("parse_mode", "args.parse_mode")
+ ) from exc
token = normalized.get(FEISHU_ACCESS_TOKEN_ARG)
refresh_token = normalized.pop(FEISHU_REFRESH_TOKEN_ARG, None)
watch_auth_state = None
@@ -358,7 +371,7 @@ class ResourceService:
"args.feishu_refresh_token requires args.feishu_access_token."
)
- return _NormalizedAddResourceArgs(normalized, watch_auth_state)
+ return _NormalizedAddResourceArgs(normalized, watch_auth_state, parse_mode)
def _ensure_feishu_credentials_for_watch(self) -> None:
try:
@@ -510,6 +523,7 @@ class ResourceService:
build_index=msg.build_index,
summarize=msg.summarize,
processing_mode=msg.processing_mode,
+ parse_mode=msg.parse_mode,
watch_interval=msg.watch_interval,
manage_watch=not msg.skip_watch_management,
tags=msg.tags,
@@ -577,6 +591,7 @@ class ResourceService:
build_index: bool = True,
summarize: bool = False,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
+ parse_mode: ParseMode | str | None = None,
watch_interval: float = 0,
manage_watch: bool = True,
tags: Optional[List[str]] = None,
@@ -591,6 +606,11 @@ class ResourceService:
processing_mode = normalize_processing_mode(processing_mode)
self._validate_add_resource_tag_policy(tags=tags, tag_mode=tag_mode)
normalized_args = self._normalize_add_resource_args(args, watch_interval=watch_interval)
+ mode = (
+ normalize_parse_mode(parse_mode)
+ if parse_mode is not None
+ else normalized_args.parse_mode
+ )
kwargs.update(normalized_args.processor_kwargs)
from openviking.connector.routing import credential_arg_names
@@ -659,6 +679,7 @@ class ResourceService:
build_index=build_index,
summarize=summarize,
processing_mode=processing_mode,
+ parse_mode=mode.value,
watch_interval=watch_interval,
skip_watch_management=not manage_watch,
tags=tags,
@@ -837,6 +858,7 @@ class ResourceService:
path: str,
ctx: RequestContext,
to: Optional[str] = None,
+ to_is_directory: Optional[bool] = None,
parent: Optional[str] = None,
reason: str = "",
instruction: str = "",
@@ -854,6 +876,7 @@ class ResourceService:
path=path,
ctx=ctx,
to=to,
+ to_is_directory=to_is_directory,
parent=parent,
reason=reason,
instruction=instruction,
@@ -876,6 +899,7 @@ class ResourceService:
ctx: RequestContext,
add_type: Optional[str] = None,
to: Optional[str] = None,
+ to_is_directory: Optional[bool] = None,
parent: Optional[str] = None,
reason: str = "",
instruction: str = "",
@@ -888,6 +912,7 @@ class ResourceService:
manage_watch: bool = True,
tags: Optional[List[str]] = None,
tag_mode: str = "replace",
+ parse_mode: ParseMode | str | None = None,
allow_local_path_resolution: bool = True,
enforce_public_remote_targets: bool = False,
args: Optional[Dict[str, Any]] = None,
@@ -940,6 +965,11 @@ class ResourceService:
processing_mode = normalize_processing_mode(processing_mode)
self._validate_add_resource_tag_policy(tags=tags, tag_mode=tag_mode)
normalized_args = self._normalize_add_resource_args(args, watch_interval=watch_interval)
+ mode = (
+ normalize_parse_mode(parse_mode)
+ if parse_mode is not None
+ else normalized_args.parse_mode
+ )
kwargs.update(normalized_args.processor_kwargs)
if watch_interval > 0 and kwargs.get("temp_file_id"):
# Fail fast, before any ingestion: an uploaded source is a one-time
@@ -976,8 +1006,9 @@ class ResourceService:
build_index=build_index,
summarize=summarize,
processing_mode=processing_mode,
+ parse_mode=mode,
watch_interval=watch_interval,
- connector_args=args or {},
+ connector_args=normalized_args.processor_kwargs,
kwargs=kwargs,
):
return await self._connector.submit(
@@ -986,7 +1017,7 @@ class ResourceService:
declared_add_type=add_type,
to=to,
reason=reason,
- connector_args=args or {},
+ connector_args=normalized_args.processor_kwargs,
tags=tags,
tag_mode=tag_mode,
**kwargs,
@@ -997,6 +1028,7 @@ class ResourceService:
path=path,
ctx=ctx,
to=to,
+ to_is_directory=to_is_directory,
parent=parent,
reason=reason,
instruction=instruction,
@@ -1004,6 +1036,7 @@ class ResourceService:
build_index=build_index,
summarize=summarize,
processing_mode=processing_mode,
+ parse_mode=mode,
watch_interval=watch_interval,
manage_watch=manage_watch,
tags=tags,
@@ -1017,6 +1050,7 @@ class ResourceService:
path=path,
ctx=ctx,
to=to,
+ to_is_directory=to_is_directory,
parent=parent,
reason=reason,
instruction=instruction,
@@ -1025,6 +1059,7 @@ class ResourceService:
build_index=build_index,
summarize=summarize,
processing_mode=processing_mode,
+ parse_mode=mode,
watch_interval=watch_interval,
manage_watch=manage_watch,
tags=tags,
@@ -1070,6 +1105,7 @@ class ResourceService:
ctx: RequestContext,
defer_post_processing: bool,
to: Optional[str] = None,
+ to_is_directory: Optional[bool] = None,
parent: Optional[str] = None,
reason: str = "",
instruction: str = "",
@@ -1077,6 +1113,7 @@ class ResourceService:
build_index: bool = True,
summarize: bool = False,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
+ parse_mode: ParseMode | str = ParseMode.DEFAULT,
watch_interval: float = 0,
manage_watch: bool = True,
tags: Optional[List[str]] = None,
@@ -1091,6 +1128,9 @@ class ResourceService:
) -> Dict[str, Any]:
"""Execute an already-routed resource ingestion."""
self._ensure_initialized()
+ mode = normalize_parse_mode(parse_mode)
+ if mode is ParseMode.NO_SPLIT:
+ kwargs["parse_mode"] = mode.value
request_start = time.perf_counter()
telemetry = get_current_telemetry()
telemetry_id = telemetry.telemetry_id
@@ -1117,6 +1157,9 @@ class ResourceService:
parent=parent,
create_parent=bool(kwargs.get("create_parent", False)),
)
+ if to_is_directory is None:
+ to_is_directory = bool(target.to)
+ watch_to_is_directory = to_is_directory
if enforce_public_remote_targets and is_remote_resource_source(path):
path = require_remote_resource_source(path)
kwargs.setdefault("request_validator", ensure_public_remote_target)
@@ -1124,7 +1167,8 @@ class ResourceService:
kwargs["resource_lock"] = resource_lock
async_understanding_candidate = (
- defer_post_processing
+ mode is ParseMode.DEFAULT
+ and defer_post_processing
and not is_git_repo_url(path)
and not allow_local_path_resolution
and self._resource_processor is not None
@@ -1305,6 +1349,7 @@ class ResourceService:
manage_watch=manage_watch,
watch_interval=watch_interval,
target=target,
+ to_is_directory=watch_to_is_directory,
root_uri=root_uri,
path=path,
reason=reason,
@@ -1332,6 +1377,7 @@ class ResourceService:
scope="resources",
to=target.to,
parent=target.parent,
+ to_is_directory=to_is_directory,
build_index=build_index,
summarize=summarize,
processing_mode=processing_mode,
@@ -1348,6 +1394,12 @@ class ResourceService:
return result
prepared = result.pop("_post_process", None)
deferred_lock = result.pop("_resource_lock", None)
+ if (
+ not target.to
+ and isinstance(prepared, dict)
+ and isinstance(prepared.get("root_is_file"), bool)
+ ):
+ watch_to_is_directory = not prepared["root_is_file"]
if defer_post_processing:
from openviking.storage.queuefs.add_resource_msg import AddResourceMsg
@@ -1404,6 +1456,7 @@ class ResourceService:
manage_watch=manage_watch,
watch_interval=watch_interval,
target=target,
+ to_is_directory=watch_to_is_directory,
root_uri=str(result.get("root_uri") or ""),
path=path,
reason=reason,
@@ -1519,6 +1572,7 @@ class ResourceService:
self,
path: str,
to_uri: str,
+ to_is_directory: bool,
parent_uri: Optional[str],
reason: str,
instruction: str,
@@ -1568,6 +1622,7 @@ class ResourceService:
role=str(ctx.role),
path=path,
to_uri=to_uri,
+ to_is_directory=to_is_directory,
parent_uri=parent_uri,
reason=reason,
instruction=instruction,
@@ -1589,6 +1644,7 @@ class ResourceService:
user_id=ctx.user.user_id,
original_role=str(ctx.role),
to_uri=to_uri,
+ to_is_directory=to_is_directory,
parent_uri=parent_uri,
reason=reason,
instruction=instruction,
diff --git a/openviking/storage/queuefs/add_resource_msg.py b/openviking/storage/queuefs/add_resource_msg.py
index 78a4b6b2d..bfbc187a7 100644
--- a/openviking/storage/queuefs/add_resource_msg.py
+++ b/openviking/storage/queuefs/add_resource_msg.py
@@ -43,6 +43,7 @@ class AddResourceMsg:
defer_target_resolution: bool = False
understanding_response_id: Optional[str] = None
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE
+ parse_mode: str = "default"
tags: Optional[list[str]] = None
tag_mode: str = "replace"
@@ -124,6 +125,7 @@ class AddResourceMsg:
else None
),
processing_mode=data.get("processing_mode", DEFAULT_PROCESSING_MODE),
+ parse_mode=str(data.get("parse_mode") or "default"),
tags=(
list(data["tags"])
if isinstance(data.get("tags"), list)
diff --git a/openviking/utils/media_processor.py b/openviking/utils/media_processor.py
index 347376838..15a04fcde 100644
--- a/openviking/utils/media_processor.py
+++ b/openviking/utils/media_processor.py
@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Optional
from openviking.parse.accessors.base import LocalResource, SourceType
from openviking.parse.accessors.mime_types import IANA_MEDIA_TYPE_TO_EXTENSION
from openviking.parse.base import ParseResult
+from openviking.parse.mode import ParseMode, normalize_parse_mode
from openviking.parse.parsers.constants import (
CODE_EXTENSIONS,
DOCUMENTATION_EXTENSIONS,
@@ -174,6 +175,7 @@ class UnifiedResourceProcessor:
instruction: str = "",
allow_local_path_resolution: bool = True,
prepared_resource: Optional[LocalResource] = None,
+ parse_mode: ParseMode | str = ParseMode.DEFAULT,
**kwargs,
) -> ParseResult:
"""Process any source (file/URL/content) with two-layer architecture.
@@ -186,15 +188,25 @@ class UnifiedResourceProcessor:
- Directories needed for TreeBuilder are preserved via ParseResult.temp_dir_path
"""
+ mode = normalize_parse_mode(parse_mode)
+
# First check if source is raw content (not URL/path)
is_potential_path = (
allow_local_path_resolution and len(source) <= 1024 and "\n" not in source
)
if not is_potential_path and not self._is_url(source):
# Treat as raw content
- return await parse(source, instruction=instruction)
+ return await parse(
+ source,
+ instruction=instruction,
+ split_content=mode is ParseMode.DEFAULT,
+ )
- if prepared_resource is None and self._has_prepared_understanding_response(kwargs):
+ if (
+ mode is ParseMode.DEFAULT
+ and prepared_resource is None
+ and self._has_prepared_understanding_response(kwargs)
+ ):
parse_kwargs = dict(kwargs)
parse_kwargs["instruction"] = instruction
parse_kwargs["vlm_processor"] = self._get_vlm_processor()
@@ -212,7 +224,11 @@ class UnifiedResourceProcessor:
parse_kwargs["resource_name"] = _smart_stem(explicit_name)
return await self._get_parser_router().parse(source, **parse_kwargs)
- if prepared_resource is None and self.should_use_understanding_directly(source, **kwargs):
+ if (
+ mode is ParseMode.DEFAULT
+ and prepared_resource is None
+ and self.should_use_understanding_directly(source, **kwargs)
+ ):
parse_kwargs = dict(kwargs)
parse_kwargs["instruction"] = instruction
parse_kwargs["vlm_processor"] = self._get_vlm_processor()
@@ -241,8 +257,6 @@ class UnifiedResourceProcessor:
# Phase 2: Parser - parse the local resource
parse_kwargs = dict(kwargs)
parse_kwargs["instruction"] = instruction
- parse_kwargs["vlm_processor"] = self._get_vlm_processor()
- parse_kwargs["storage"] = self.storage
parse_kwargs["_source_meta"] = local_resource.meta
parse_kwargs["resolved_extension"] = kwargs.get(
"resolved_extension"
@@ -273,6 +287,12 @@ class UnifiedResourceProcessor:
else:
parse_kwargs.setdefault("resource_name", _smart_stem(local_resource.path))
+ if mode is ParseMode.NO_SPLIT:
+ parse_kwargs["split_content"] = False
+
+ parse_kwargs["vlm_processor"] = self._get_vlm_processor()
+ parse_kwargs["storage"] = self.storage
+
# If it's a directory, use DirectoryParser which will delegate to CodeRepositoryParser if it's a git repo
if local_resource.path.is_dir():
from openviking.parse.parsers.directory import DirectoryParser
diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.py
index 27b45b13b..ffdc9a287 100644
--- a/openviking/utils/resource_processor.py
+++ b/openviking/utils/resource_processor.py
@@ -16,6 +16,7 @@ from openviking.core.context import ContextLevel
from openviking.utils.ingest_options import IngestOptions
from openviking.core.namespace import context_type_for_uri
from openviking.parse.image_rewrite import rewrite_image_uris
+from openviking.parse.mode import ParseMode, normalize_parse_mode
from openviking.parse.tree_builder import TreeBuilder
from openviking.resource.processing_mode import (
DEFAULT_PROCESSING_MODE,
@@ -184,6 +185,7 @@ class ResourceProcessor:
defer_post_processing = bool(kwargs.pop("defer_post_processing", False))
preacquired_lock = kwargs.pop("resource_lock", None)
ingest_options = IngestOptions.from_value(kwargs.pop("ingest_options", None))
+ to_is_directory = bool(kwargs.pop("to_is_directory", False))
telemetry = get_current_telemetry()
async def _set_stage(stage: str) -> None:
@@ -287,10 +289,21 @@ class ResourceProcessor:
source_path=parse_result.source_path,
source_format=parse_result.source_format,
create_parent=kwargs.get("create_parent", False),
+ flatten_single_file=(
+ normalize_parse_mode(
+ kwargs.get("parse_mode", ParseMode.DEFAULT)
+ )
+ is ParseMode.NO_SPLIT
+ and parse_result.source_format not in {"directory", "repository"}
+ and not to_is_directory
+ ),
)
if context_tree and context_tree.root:
result["root_uri"] = context_tree.root.uri
result["temp_uri"] = context_tree.root.temp_uri
+ root_is_file = bool(
+ getattr(context_tree, "_root_is_file", False)
+ )
telemetry.set(
"resource.finalize.duration_ms",
round((time.perf_counter() - finalize_start) * 1000, 3),
@@ -341,6 +354,7 @@ class ResourceProcessor:
root_uri, resource_lock = await self.reserve_unique_candidate(
candidate_uri=candidate_uri,
ctx=ctx,
+ root_is_file=root_is_file,
)
result["root_uri"] = root_uri
if root_uri != candidate_uri:
@@ -372,7 +386,11 @@ class ResourceProcessor:
pass
if resource_lock is None:
dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)
- resource_lock = await self.acquire_resource_lock(dst_path, uri=root_uri)
+ resource_lock = await self.acquire_resource_lock(
+ dst_path,
+ uri=root_uri,
+ root_is_file=root_is_file,
+ )
if not target_preexisting:
await viking_fs.persist_temp_tree(
temp_uri,
@@ -380,7 +398,12 @@ class ResourceProcessor:
ctx=ctx,
lease_ref=resource_lock,
)
- await rewrite_image_uris(root_uri, ctx=ctx, lease_ref=resource_lock)
+ if not root_is_file:
+ await rewrite_image_uris(
+ root_uri,
+ ctx=ctx,
+ lease_ref=resource_lock,
+ )
await viking_fs.delete_temp(
parse_result.temp_dir_path,
ctx=ctx,
@@ -417,6 +440,7 @@ class ResourceProcessor:
"source_committed": source_committed,
"target_preexisting": target_preexisting,
"is_code_repo": parse_result.source_format == "repository",
+ "root_is_file": root_is_file,
}
if defer_post_processing:
result["_post_process"] = prepared
@@ -460,8 +484,12 @@ class ResourceProcessor:
build_index = bool(kwargs.get("build_index", True))
processing_mode = normalize_processing_mode(processing_mode)
vectors_only = processing_mode == VECTORS_ONLY
+ root_is_file = bool(prepared.get("root_is_file"))
ingest_options = IngestOptions.from_value(kwargs.pop("ingest_options", None))
- should_summarize = not vectors_only and (summarize or build_index)
+ should_summarize = not root_is_file and not vectors_only and (summarize or build_index)
+ should_refresh_file_parent = (
+ root_is_file and not vectors_only and (summarize or build_index)
+ )
result: Dict[str, Any] = {"status": "success", "root_uri": root_uri}
if should_summarize:
@@ -508,7 +536,7 @@ class ResourceProcessor:
sync_deleted_dirs: list[str] = []
if not should_summarize and temp_uri and not source_committed:
viking_fs = get_viking_fs()
- if vectors_only and target_preexisting:
+ if vectors_only and target_preexisting and not root_is_file:
diff = await SemanticProcessor()._sync_topdown_recursive(
temp_uri,
root_uri,
@@ -524,11 +552,12 @@ class ResourceProcessor:
ctx=ctx,
lease_ref=resource_lock,
)
- await rewrite_image_uris(
- root_uri,
- ctx=ctx,
- lease_ref=resource_lock,
- )
+ if not root_is_file:
+ await rewrite_image_uris(
+ root_uri,
+ ctx=ctx,
+ lease_ref=resource_lock,
+ )
if temp_dir_path:
await viking_fs.delete_temp(temp_dir_path, ctx=ctx)
if vectors_only:
@@ -538,22 +567,42 @@ class ResourceProcessor:
dirs=sync_deleted_dirs,
ctx=ctx,
)
- if vectors_only and build_index:
- await self._vectorize_resource_files(
- root_uri,
+ if should_refresh_file_parent:
+ await self._get_summarizer().refresh_file_parent(
+ file_uri=root_uri,
ctx=ctx,
+ skip_vectorization=not build_index,
ingest_options=ingest_options,
)
+ elif build_index:
+ if root_is_file:
+ await self._vectorize_resource_file(
+ root_uri, ctx=ctx, ingest_options=ingest_options
+ )
+ elif vectors_only:
+ await self._vectorize_resource_files(
+ root_uri, ctx=ctx, ingest_options=ingest_options
+ )
finally:
await get_viking_fs()._async_agfs.pathlock_release(resource_lock)
- elif vectors_only:
- if not build_index:
- return result
- await self._vectorize_resource_files(
- root_uri,
+ elif should_refresh_file_parent:
+ await self._get_summarizer().refresh_file_parent(
+ file_uri=root_uri,
ctx=ctx,
+ skip_vectorization=not build_index,
ingest_options=ingest_options,
)
+ elif vectors_only or root_is_file:
+ if not build_index:
+ return result
+ if root_is_file:
+ await self._vectorize_resource_file(
+ root_uri, ctx=ctx, ingest_options=ingest_options
+ )
+ else:
+ await self._vectorize_resource_files(
+ root_uri, ctx=ctx, ingest_options=ingest_options
+ )
return result
async def _delete_removed_resource_vectors(
@@ -623,14 +672,36 @@ class ResourceProcessor:
register_request_wait=True,
)
+ async def _vectorize_resource_file(
+ self,
+ file_uri: str,
+ *,
+ ctx: RequestContext,
+ ingest_options: IngestOptions | None = None,
+ ) -> None:
+ parent = VikingURI(file_uri).parent
+ if parent is None:
+ return
+ name = file_uri.rsplit("/", 1)[-1]
+ await vectorize_file(
+ file_path=file_uri,
+ summary_dict={"name": name, "summary": ""},
+ parent_uri=parent.uri,
+ context_type=context_type_for_uri(file_uri),
+ ctx=ctx,
+ ingest_options=IngestOptions.from_value(ingest_options),
+ register_request_wait=True,
+ )
+
async def reserve_unique_candidate(
self,
*,
candidate_uri: str,
ctx: RequestContext,
max_attempts: int = 100,
+ root_is_file: bool = False,
) -> tuple[str, Dict[str, Any]]:
- """Pick the first free candidate URI and reserve it with a resource TreeLock."""
+ """Pick the first free candidate URI and reserve it with a type-aware lock."""
from openviking.storage.errors import ResourceBusyError
viking_fs = get_viking_fs()
@@ -644,7 +715,10 @@ class ResourceProcessor:
dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)
try:
resource_lock = await self.acquire_resource_lock(
- dst_path, uri=root_uri, timeout=0.0
+ dst_path,
+ uri=root_uri,
+ timeout=0.0,
+ root_is_file=root_is_file,
)
return root_uri, resource_lock
except ResourceBusyError as exc:
@@ -670,14 +744,19 @@ class ResourceProcessor:
*,
uri: str = "",
timeout: float = 0.0,
+ root_is_file: bool = False,
) -> Dict[str, Any]:
- """Acquire the per-resource TreeLock or raise a structured conflict."""
+ """Acquire a file-exact or directory-tree resource lock."""
from openviking.storage.errors import ResourceBusyError
try:
- return await get_viking_fs()._async_agfs.pathlock_acquire_tree(
- path, timeout_secs=timeout
+ pathlock = get_viking_fs()._async_agfs
+ acquire = (
+ pathlock.pathlock_acquire_exact
+ if root_is_file
+ else pathlock.pathlock_acquire_tree
)
+ return await acquire(path, timeout_secs=timeout)
except LockAcquisitionError as exc:
logger.warning(f"[ResourceProcessor] Failed to acquire resource lock on {path}")
raise ResourceBusyError(
diff --git a/openviking/utils/summarizer.py b/openviking/utils/summarizer.py
index d7e519471..66e7e7f83 100644
--- a/openviking/utils/summarizer.py
+++ b/openviking/utils/summarizer.py
@@ -7,12 +7,13 @@ Handles summarization and key information extraction.
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
-from openviking.utils.ingest_options import IngestOptions
from openviking.core.namespace import context_type_for_uri
from openviking.storage.queuefs import SemanticMsg, get_queue_manager
+from openviking.storage.queuefs.semantic_msg import build_semantic_coalesce_key
from openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fs
from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
+from openviking.utils.ingest_options import IngestOptions
from openviking_cli.utils import get_logger
from openviking_cli.utils.uri import VikingURI
@@ -31,6 +32,65 @@ class Summarizer:
def __init__(self, vlm_processor: "VLMProcessor"):
self.vlm_processor = vlm_processor
+ async def refresh_file_parent(
+ self,
+ *,
+ file_uri: str,
+ ctx: "RequestContext",
+ skip_vectorization: bool = False,
+ ingest_options: IngestOptions | None = None,
+ ) -> Dict[str, Any]:
+ """Summarize one flat file and refresh its parent directory semantics."""
+ parent = VikingURI(file_uri).parent
+ if parent is None:
+ return {"status": "error", "message": f"file has no parent URI: {file_uri}"}
+
+ queue_manager = get_queue_manager()
+ semantic_queue = queue_manager.get_queue(queue_manager.SEMANTIC, allow_create=True)
+ telemetry_id = get_current_telemetry().telemetry_id
+ parent_uri = parent.uri.rstrip("/")
+ msg = SemanticMsg(
+ uri=parent_uri,
+ context_type=context_type_for_uri(file_uri),
+ recursive=False,
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ peer_id=ctx.user.user_id,
+ role=str(ctx.role),
+ skip_vectorization=skip_vectorization,
+ telemetry_id=telemetry_id,
+ changes={"modified": [file_uri]},
+ coalesce_key=build_semantic_coalesce_key(
+ context_type=context_type_for_uri(file_uri),
+ uri=parent_uri,
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ peer_id=ctx.user.user_id,
+ ),
+ ingest_options=ingest_options,
+ )
+ if telemetry_id:
+ get_request_wait_tracker().register_semantic_root(telemetry_id, msg.id)
+ try:
+ enqueue_id = await semantic_queue.enqueue(msg)
+ except Exception as exc:
+ if telemetry_id:
+ get_request_wait_tracker().mark_semantic_failed(
+ telemetry_id,
+ msg.id,
+ str(exc),
+ )
+ raise
+ if enqueue_id == "deduplicated":
+ if telemetry_id:
+ get_request_wait_tracker().mark_semantic_done(
+ telemetry_id,
+ msg.id,
+ processed_delta=0,
+ )
+ return {"status": "success", "enqueued_count": 0}
+ return {"status": "success", "enqueued_count": 1}
+
async def summarize(
self,
resource_uris: List[str],
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 8d024d36d..15e0b02fe 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -11,10 +11,17 @@ import (
"net/http/httptest"
"os"
"path/filepath"
+ "reflect"
"strings"
"testing"
)
+func TestAddResourceOptionsHasNoTopLevelParseMode(t *testing.T) {
+ if _, ok := reflect.TypeOf(AddResourceOptions{}).FieldByName("ParseMode"); ok {
+ t.Fatal("AddResourceOptions must configure parse_mode through Args")
+ }
+}
+
func testClient(t *testing.T, handler http.Handler) (*Client, func()) {
t.Helper()
server := httptest.NewServer(handler)
@@ -576,7 +583,7 @@ func TestAddResourceUploadsLocalFile(t *testing.T) {
// args must be omitted when the caller does not pass any, so the
// request is accepted by pre-#2549 instances whose resources route
// uses model_config=ConfigDict(extra="forbid").
- requireBodyKeysAbsent(t, body, "args")
+ requireBodyKeysAbsent(t, body, "args", "parse_mode")
writeOK(t, w, map[string]any{"uri": "viking://resources/note.md"})
default:
t.Fatalf("unexpected path %s", r.URL.Path)
@@ -593,6 +600,27 @@ func TestAddResourceUploadsLocalFile(t *testing.T) {
}
}
+func TestAddResourceSendsNoSplitMode(t *testing.T) {
+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ body := readJSONBody(t, r)
+ args, ok := body["args"].(map[string]any)
+ if !ok || args["parse_mode"] != "no_split" {
+ t.Fatalf("args = %#v", body["args"])
+ }
+ requireBodyKeysAbsent(t, body, "parse_mode")
+ writeOK(t, w, map[string]any{"uri": "viking://resources/manual"})
+ }))
+ defer closeServer()
+
+ if _, err := client.AddResource(
+ context.Background(),
+ "https://example.com/manual.pdf",
+ &AddResourceOptions{Args: map[string]any{"parse_mode": "no_split"}},
+ ); err != nil {
+ t.Fatal(err)
+ }
+}
+
func TestAddResourceSendsArgsWhenProvided(t *testing.T) {
dir := t.TempDir()
filePath := filepath.Join(dir, "note.md")
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 77db3ddd5..1d22abfac 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -67,6 +67,7 @@ GATEWAY_MARKER_HEADER = "X-VikingBot-Gateway"
GATEWAY_TOKEN_HEADER = "X-Gateway-Token"
+
def _image_mime_type(file_name: str = "") -> str:
mime_type, _ = mimetypes.guess_type(file_name or "")
if mime_type and mime_type.startswith("image/"):
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index ca8d4ca39..2acfc8873 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -7,6 +7,7 @@ import {
OpenVikingError,
normalizeURI,
} from "../src/index.js";
+import type { AddResourceOptions } from "../src/index.js";
const ok = (result: unknown) =>
new Response(JSON.stringify({ status: "ok", result }), {
@@ -15,6 +16,16 @@ const ok = (result: unknown) =>
});
describe("OpenVikingClient", () => {
+ it("does not expose a top-level resource parse mode option", () => {
+ const options: AddResourceOptions = {
+ // @ts-expect-error parse_mode is configured through args
+ parseMode: "no_split",
+ };
+ expect((options as unknown as Record<string, unknown>).parseMode).toBe(
+ "no_split",
+ );
+ });
+
it("normalizes URIs", () => {
expect(normalizeURI("resources/docs")).toBe("viking://resources/docs");
expect(normalizeURI("viking://resources/docs")).toBe(
@@ -379,6 +390,27 @@ describe("OpenVikingClient", () => {
}
});
+ it("serializes resource parse mode through args", async () => {
+ const fetcher = vi
+ .fn<typeof fetch>()
+ .mockImplementation(async () => ok({}));
+ const client = new OpenVikingClient({
+ baseUrl: "https://example.com",
+ fetch: fetcher,
+ });
+
+ await client.addResource("https://example.com/default.md");
+ await client.addResource("https://example.com/raw.pdf", {
+ args: { parse_mode: "no_split" },
+ });
+
+ const defaultBody = JSON.parse(String(fetcher.mock.calls[0]![1]?.body));
+ const noSplitBody = JSON.parse(String(fetcher.mock.calls[1]![1]?.body));
+ expect(defaultBody).not.toHaveProperty("parse_mode");
+ expect(noSplitBody).not.toHaveProperty("parse_mode");
+ expect(noSplitBody.args).toEqual({ parse_mode: "no_split" });
+ });
+
it("streams OVPack exports to a normalized local file", async () => {
const directory = await mkdtemp(join(tmpdir(), "openviking-sdk-pack-"));
try {
diff --git a/tests/agfs/test_fs_binding.py b/tests/agfs/test_fs_binding.py
index ef074e043..22976aa2b 100644
--- a/tests/agfs/test_fs_binding.py
+++ b/tests/agfs/test_fs_binding.py
@@ -14,6 +14,7 @@ import uuid
import pytest
from openviking.storage.viking_fs import init_viking_fs
+from openviking.utils.resource_processor import ResourceProcessor
from openviking_cli.utils.config.agfs_config import AGFSConfig
# Direct configuration for testing
@@ -91,6 +92,42 @@ class TestVikingFSBindingLocal:
root_entries = await vfs.ls("viking://temp/")
assert not any(e["name"] == test_dir for e in root_entries)
+ async def test_flat_file_lock_keeps_persisted_target_a_file(
+ self,
+ viking_fs_binding_instance,
+ ):
+ """An exact resource lock must not materialize a file target as a directory."""
+ vfs = viking_fs_binding_instance
+ unique = uuid.uuid4().hex
+ temp_uri = f"viking://temp/flat_lock_{unique}.md"
+ target_uri = f"viking://resources/flat_lock_{unique}.md"
+ target_path = vfs._uri_to_path(target_uri)
+ lease = None
+
+ try:
+ await vfs.write(temp_uri, "flat file content")
+ lease = await ResourceProcessor.acquire_resource_lock(
+ target_path,
+ uri=target_uri,
+ root_is_file=True,
+ )
+ await vfs.persist_temp_tree(
+ temp_uri,
+ target_uri,
+ lease_ref=lease,
+ )
+
+ stat_info = await vfs.stat(target_uri)
+ assert stat_info["isDir"] is False
+ assert await vfs.read(target_uri) == b"flat file content"
+ finally:
+ if lease is not None:
+ await vfs._async_agfs.pathlock_release(lease)
+ for uri in (temp_uri, target_uri):
+ if await vfs.exists(uri):
+ stat_info = await vfs.stat(uri)
+ await vfs.rm(uri, recursive=bool(stat_info.get("isDir")))
+
async def test_borrowed_pathlock_cannot_release_via_raw_ref(self, viking_fs_binding_instance):
"""Reject borrowed lifecycle control through typed and raw lease refs."""
vfs = viking_fs_binding_instance
diff --git a/tests/client/test_http_client_compact.py b/tests/client/test_http_client_compact.py
index 547b4e289..f0d41d3c6 100644
--- a/tests/client/test_http_client_compact.py
+++ b/tests/client/test_http_client_compact.py
@@ -103,6 +103,7 @@ async def test_add_resource_omits_empty_args_and_null_fields():
assert payload["path"] == "https://example.com/doc"
# `args` is the field that breaks `add-resource` against pre-#2549 instances.
assert "args" not in payload
+ assert "parse_mode" not in payload
for dropped in (
"add_type",
"to",
@@ -122,3 +123,16 @@ async def test_add_resource_keeps_explicit_args():
payload = fake.calls[-1]["json"]
assert payload["args"] == {"feishu_access_token": "u-x"}
+
+
+async def test_add_resource_keeps_explicit_no_split_mode():
+ client, fake = _client_with_fake()
+
+ await client.add_resource(
+ "https://example.com/doc",
+ args={"parse_mode": "no_split"},
+ )
+
+ payload = fake.calls[-1]["json"]
+ assert payload["args"] == {"parse_mode": "no_split"}
+ assert "parse_mode" not in payload
diff --git a/tests/client/test_resource_parse_mode_clients.py b/tests/client/test_resource_parse_mode_clients.py
new file mode 100644
index 000000000..6745108c8
--- /dev/null
+++ b/tests/client/test_resource_parse_mode_clients.py
@@ -0,0 +1,76 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""Public Python client coverage for args.parse_mode."""
+
+import inspect
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.async_client import AsyncOpenViking
+from openviking.client.local import LocalClient
+from openviking.server.identity import RequestContext, Role
+from openviking.sync_client import SyncOpenViking
+from openviking_cli.client.sync_http import SyncHTTPClient
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def test_public_python_clients_do_not_expose_parse_mode_parameter():
+ for method in (
+ AsyncOpenViking.add_resource,
+ SyncOpenViking.add_resource,
+ LocalClient.add_resource,
+ SyncHTTPClient.add_resource,
+ ):
+ assert "parse_mode" not in inspect.signature(method).parameters
+
+
+async def test_async_embedded_client_forwards_no_split():
+ downstream = AsyncMock(return_value={"root_uri": "viking://resources/test"})
+ client = object.__new__(AsyncOpenViking)
+ client._client = SimpleNamespace(add_resource=downstream)
+ client._ensure_initialized = AsyncMock()
+
+ await AsyncOpenViking.add_resource(
+ client,
+ path="/tmp/manual.pdf",
+ args={"parse_mode": "no_split"},
+ )
+
+ assert downstream.await_args.kwargs["args"] == {"parse_mode": "no_split"}
+
+
+def test_sync_embedded_client_forwards_no_split():
+ downstream = AsyncMock(return_value={"root_uri": "viking://resources/test"})
+ client = object.__new__(SyncOpenViking)
+ client._async_client = SimpleNamespace(add_resource=downstream)
+
+ SyncOpenViking.add_resource(
+ client,
+ path="/tmp/manual.pdf",
+ args={"parse_mode": "no_split"},
+ )
+
+ assert downstream.await_args.kwargs["args"] == {"parse_mode": "no_split"}
+
+
+async def test_local_client_forwards_no_split():
+ downstream = AsyncMock(return_value={"root_uri": "viking://resources/test"})
+ client = object.__new__(LocalClient)
+ client._ctx = RequestContext(
+ user=UserIdentifier("test_account", "test_user"),
+ role=Role.USER,
+ )
+ client._service = SimpleNamespace(resources=SimpleNamespace(add_resource=downstream))
+
+ await LocalClient.add_resource(
+ client,
+ path="/tmp/manual.pdf",
+ args={"parse_mode": "no_split"},
+ )
+
+ assert downstream.await_args.kwargs["args"] == {"parse_mode": "no_split"}
diff --git a/tests/misc/test_resource_processor_mv.py b/tests/misc/test_resource_processor_mv.py
index 9090efbd0..0cfc0cceb 100644
--- a/tests/misc/test_resource_processor_mv.py
+++ b/tests/misc/test_resource_processor_mv.py
@@ -42,7 +42,9 @@ class _CtxMgr:
class _FakePathLock:
def __init__(self, *, busy_tree_paths=None):
self._next_id = 0
+ self.acquired_exact_paths: list[str] = []
self.acquired_tree_paths: list[str] = []
+ self.exact_attempts: list[tuple[str, float]] = []
self.tree_attempts: list[tuple[str, float]] = []
self.busy_tree_paths = set(busy_tree_paths or [])
@@ -59,6 +61,11 @@ class _FakePathLock:
self.acquired_tree_paths.append(path)
return self._new_lease()
+ async def pathlock_acquire_exact(self, path, timeout_secs=0.0):
+ self.exact_attempts.append((path, timeout_secs))
+ self.acquired_exact_paths.append(path)
+ return self._new_lease()
+
async def pathlock_release(self, lease):
pass
@@ -156,6 +163,119 @@ async def test_resource_processor_first_add_summarizes_from_committed_uri(monkey
assert summarize_calls[0]["target_preexisting"] is False
[email protected]("auto_candidate", [False, True])
+async def test_resource_processor_allows_flat_root_only_for_single_no_split_source(
+ monkeypatch,
+ auto_candidate,
+):
+ from openviking.utils.resource_processor import ResourceProcessor
+
+ fake_fs = _FakeVikingFS()
+ fake_fs.glob = AsyncMock(
+ side_effect=NotADirectoryError("flat resource roots cannot be globbed")
+ )
+ monkeypatch.setattr(
+ "openviking.utils.resource_processor.get_current_telemetry",
+ lambda: _DummyTelemetry(),
+ )
+ _patch_viking_fs(monkeypatch, fake_fs)
+
+ rp = ResourceProcessor(vikingdb=_DummyVikingDB(), media_storage=None)
+ rp._get_media_processor = MagicMock()
+ rp._get_media_processor.return_value.process = AsyncMock(
+ return_value=SimpleNamespace(
+ temp_dir_path="viking://temp/tmpdir",
+ source_path="神雕_副本.md",
+ source_format="markdown",
+ meta={},
+ warnings=[],
+ )
+ )
+ root_uri = "viking://resources/神雕_副本.md"
+ rp.tree_builder.finalize_from_temp = AsyncMock(
+ return_value=SimpleNamespace(
+ root=SimpleNamespace(
+ uri=root_uri,
+ temp_uri="viking://temp/tmpdir/神雕_副本/神雕_副本.md",
+ ),
+ _root_is_file=True,
+ _candidate_uri=root_uri if auto_candidate else None,
+ )
+ )
+ rp._summarizer = SimpleNamespace(
+ summarize=AsyncMock(return_value={"status": "success"}),
+ refresh_file_parent=AsyncMock(return_value={"status": "success"}),
+ )
+
+ result = await rp.process_resource(
+ path="神雕_副本.md",
+ ctx=object(),
+ build_index=True,
+ parse_mode="no_split",
+ )
+
+ assert result["status"] == "success"
+ assert result["root_uri"] == root_uri
+ assert fake_fs._async_agfs.exact_attempts == [
+ ("/mock/resources/神雕_副本.md", 0.0)
+ ]
+ assert fake_fs._async_agfs.tree_attempts == []
+ assert rp.tree_builder.finalize_from_temp.await_args.kwargs[
+ "flatten_single_file"
+ ] is True
+
+
+async def test_resource_processor_keeps_wrapper_for_directory_to_no_split(monkeypatch):
+ from openviking.utils.resource_processor import ResourceProcessor
+
+ fake_fs = _FakeVikingFS()
+ monkeypatch.setattr(
+ "openviking.utils.resource_processor.get_current_telemetry",
+ lambda: _DummyTelemetry(),
+ )
+ _patch_viking_fs(monkeypatch, fake_fs)
+
+ rp = ResourceProcessor(vikingdb=_DummyVikingDB(), media_storage=None)
+ rp._get_media_processor = MagicMock()
+ rp._get_media_processor.return_value.process = AsyncMock(
+ return_value=SimpleNamespace(
+ temp_dir_path="viking://temp/tmpdir",
+ source_path="神雕.md",
+ source_format="markdown",
+ meta={},
+ warnings=[],
+ )
+ )
+ rp.tree_builder.finalize_from_temp = AsyncMock(
+ return_value=SimpleNamespace(
+ root=SimpleNamespace(
+ uri="viking://resources/0803_shendiao_01",
+ temp_uri="viking://temp/tmpdir/神雕",
+ ),
+ _root_is_file=False,
+ )
+ )
+ rp._summarizer = SimpleNamespace(
+ summarize=AsyncMock(return_value={"status": "success"})
+ )
+
+ result = await rp.process_resource(
+ path="神雕.md",
+ ctx=object(),
+ to="viking://resources/0803_shendiao_01",
+ to_is_directory=True,
+ build_index=True,
+ parse_mode="no_split",
+ )
+
+ assert result["root_uri"] == "viking://resources/0803_shendiao_01"
+ assert rp.tree_builder.finalize_from_temp.await_args.kwargs[
+ "flatten_single_file"
+ ] is False
+
+
@pytest.mark.asyncio
async def test_resource_processor_second_add_preserves_temp_uri_for_incremental(monkeypatch):
from openviking.utils.resource_processor import ResourceProcessor
diff --git a/tests/misc/test_tree_builder_dedup.py b/tests/misc/test_tree_builder_dedup.py
index 645095bdd..4f1412b86 100644
--- a/tests/misc/test_tree_builder_dedup.py
+++ b/tests/misc/test_tree_builder_dedup.py
@@ -84,7 +84,7 @@ class TestFinalizeFromTemp:
assert tree._candidate_uri == "viking://resources/tt_b"
@pytest.mark.asyncio
- async def test_resources_root_to_keeps_single_file_wrapper_directory(self):
+ async def test_resources_root_to_flattens_single_no_split_file(self):
from openviking.parse.tree_builder import TreeBuilder
from openviking.server.identity import RequestContext, Role
from openviking_cli.session.user_id import UserIdentifier
@@ -103,8 +103,87 @@ class TestFinalizeFromTemp:
ctx=ctx,
scope="resources",
to_uri="viking://resources",
+ flatten_single_file=True,
+ )
+
+ assert tree.root.uri == "viking://resources/aa.md"
+ assert tree.root.temp_uri == "viking://temp/import/aa/aa.md"
+ assert tree._candidate_uri == "viking://resources/aa.md"
+ assert tree._root_is_file is True
+
+ @pytest.mark.asyncio
+ async def test_explicit_to_is_preserved_for_single_no_split_file(self):
+ from openviking.parse.tree_builder import TreeBuilder
+ from openviking.server.identity import RequestContext, Role
+ from openviking_cli.session.user_id import UserIdentifier
+
+ entries = {
+ "viking://temp/import": [{"name": "aa", "isDir": True}],
+ "viking://temp/import/aa": [{"name": "aa.md", "isDir": False}],
+ }
+ fs = self._make_fs(entries, {"viking://resources"})
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)
+
+ with patch("openviking.parse.tree_builder.get_viking_fs", return_value=fs):
+ tree = await TreeBuilder().finalize_from_temp(
+ temp_dir_path="viking://temp/import",
+ ctx=ctx,
+ to_uri="viking://resources/custom-name",
+ flatten_single_file=True,
+ )
+
+ assert tree.root.uri == "viking://resources/custom-name"
+ assert tree.root.temp_uri == "viking://temp/import/aa/aa.md"
+ assert tree._root_is_file is True
+
+ @pytest.mark.asyncio
+ async def test_explicit_directory_to_keeps_single_no_split_wrapper(self):
+ from openviking.parse.tree_builder import TreeBuilder
+ from openviking.server.identity import RequestContext, Role
+ from openviking_cli.session.user_id import UserIdentifier
+
+ entries = {
+ "viking://temp/import": [{"name": "aa", "isDir": True}],
+ }
+ fs = self._make_fs(entries, {"viking://resources"})
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)
+
+ with patch("openviking.parse.tree_builder.get_viking_fs", return_value=fs):
+ tree = await TreeBuilder().finalize_from_temp(
+ temp_dir_path="viking://temp/import",
+ ctx=ctx,
+ to_uri="viking://resources/custom-dir",
+ flatten_single_file=False,
+ )
+
+ assert tree.root.uri == "viking://resources/custom-dir"
+ assert tree.root.temp_uri == "viking://temp/import/aa"
+ assert tree._root_is_file is False
+
+ @pytest.mark.asyncio
+ async def test_multiple_outputs_keep_no_split_wrapper_directory(self):
+ from openviking.parse.tree_builder import TreeBuilder
+ from openviking.server.identity import RequestContext, Role
+ from openviking_cli.session.user_id import UserIdentifier
+
+ entries = {
+ "viking://temp/import": [{"name": "aa", "isDir": True}],
+ "viking://temp/import/aa": [
+ {"name": "aa.md", "isDir": False},
+ {"name": "cover.png", "isDir": False},
+ ],
+ }
+ fs = self._make_fs(entries, {"viking://resources"})
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)
+
+ with patch("openviking.parse.tree_builder.get_viking_fs", return_value=fs):
+ tree = await TreeBuilder().finalize_from_temp(
+ temp_dir_path="viking://temp/import",
+ ctx=ctx,
+ to_uri="viking://resources",
+ flatten_single_file=True,
)
assert tree.root.uri == "viking://resources/aa"
assert tree.root.temp_uri == "viking://temp/import/aa"
- assert tree._candidate_uri == "viking://resources/aa"
+ assert tree._root_is_file is False
diff --git a/tests/parse/test_add_directory.py b/tests/parse/test_add_directory.py
index 1b3f687e4..70269b62d 100644
--- a/tests/parse/test_add_directory.py
+++ b/tests/parse/test_add_directory.py
@@ -65,8 +65,9 @@ class FakeVikingFS:
async def read(self, uri: str, offset: int = 0, size: int = -1) -> bytes:
return self.files.get(uri, b"")
- async def ls(self, uri: str) -> List[Dict[str, Any]]:
+ async def ls(self, uri: str, **kw: Any) -> List[Dict[str, Any]]:
"""List direct children of *uri* (mirrors real AGFS entry format)."""
+ del kw
prefix = uri.rstrip("/") + "/"
children: Dict[str, bool] = {} # name → is_dir
for key in list(self.files.keys()) + self.dirs:
@@ -392,6 +393,32 @@ class TestParserDelegation:
assert result.meta["file_count"] == 1
assert len(fake_fs.files) > 0
+ @pytest.mark.asyncio
+ async def test_no_split_flattens_single_markdown_to_original_relative_parent(
+ self,
+ tmp_path: Path,
+ parser,
+ fake_fs: FakeVikingFS,
+ ) -> None:
+ nested = tmp_path / "scripts"
+ nested.mkdir()
+ content = "\n\n".join(
+ f"paragraph {index} " + "x" * 1000 for index in range(20)
+ )
+ (nested / "screenplay.md").write_text(content, encoding="utf-8")
+
+ result = await parser.parse(str(tmp_path), split_content=False)
+
+ root = f"{result.temp_dir_path}/{tmp_path.name}"
+ body_files = {
+ uri: value
+ for uri, value in fake_fs.files.items()
+ if uri.startswith(root) and uri.endswith(".md")
+ }
+ assert body_files == {
+ f"{root}/scripts/screenplay.md": content.encode("utf-8")
+ }
+
@pytest.mark.asyncio
async def test_txt_file_goes_through_parser(self, tmp_path: Path, parser, fake_fs) -> None:
"""Text files should be processed by TextParser (delegates to Markdown)."""
@@ -663,6 +690,136 @@ class TestPDFConversion:
)
assert found_md, f"document.md not found. Files: {list(fake_fs.files.keys())}"
+ @pytest.mark.asyncio
+ async def test_no_split_flattens_single_pdf_markdown_output(
+ self,
+ tmp_path: Path,
+ parser,
+ fake_fs,
+ ) -> None:
+ pdf_file = tmp_path / "report.pdf"
+ pdf_file.write_bytes(b"%PDF-1.4 fake pdf")
+ mock_temp = fake_fs.create_temp_uri()
+ doc_dir = f"{mock_temp}/report"
+ await fake_fs.mkdir(mock_temp)
+ await fake_fs.mkdir(doc_dir)
+ await fake_fs.write_file(f"{doc_dir}/report.md", "# Converted PDF")
+ fake_result = create_parse_result(
+ root=ResourceNode(type=NodeType.ROOT),
+ source_path=str(pdf_file),
+ source_format="pdf",
+ parser_name="PDFParser",
+ parse_time=0.1,
+ )
+ fake_result.temp_dir_path = mock_temp
+
+ with patch(
+ "openviking.parse.parsers.directory.DirectoryParser._assign_parser",
+ ) as mock_assign:
+ from openviking.parse.parsers.pdf import PDFParser as _PDF
+
+ mock_pdf = AsyncMock(spec=_PDF)
+ mock_pdf.parse = AsyncMock(return_value=fake_result)
+ mock_assign.side_effect = lambda cf, _registry: (
+ mock_pdf if cf.path.suffix == ".pdf" else None
+ )
+ result = await parser.parse(str(tmp_path), split_content=False)
+
+ root = f"{result.temp_dir_path}/{tmp_path.name}"
+ assert fake_fs.files[f"{root}/report.md"] == b"# Converted PDF"
+ assert not any(uri.startswith(f"{root}/report/") for uri in fake_fs.files)
+
+ @pytest.mark.asyncio
+ async def test_no_split_flattens_nested_pdf_when_parent_does_not_exist(
+ self,
+ tmp_path: Path,
+ parser,
+ fake_fs,
+ ) -> None:
+ nested = tmp_path / "novel"
+ nested.mkdir()
+ pdf_file = nested / "report.pdf"
+ pdf_file.write_bytes(b"%PDF-1.4 fake pdf")
+ mock_temp = fake_fs.create_temp_uri()
+ doc_dir = f"{mock_temp}/report"
+ await fake_fs.mkdir(mock_temp)
+ await fake_fs.mkdir(doc_dir)
+ await fake_fs.write_file(f"{doc_dir}/report.md", "# Converted PDF")
+ fake_result = create_parse_result(
+ root=ResourceNode(type=NodeType.ROOT),
+ source_path=str(pdf_file),
+ source_format="pdf",
+ parser_name="PDFParser",
+ parse_time=0.1,
+ )
+ fake_result.temp_dir_path = mock_temp
+
+ original_ls = fake_fs.ls
+
+ async def strict_ls(uri: str, **kwargs: Any) -> List[Dict[str, Any]]:
+ if uri not in fake_fs.dirs:
+ raise FileNotFoundError(uri)
+ return await original_ls(uri, **kwargs)
+
+ fake_fs.ls = strict_ls
+
+ with patch(
+ "openviking.parse.parsers.directory.DirectoryParser._assign_parser",
+ ) as mock_assign:
+ from openviking.parse.parsers.pdf import PDFParser as _PDF
+
+ mock_pdf = AsyncMock(spec=_PDF)
+ mock_pdf.parse = AsyncMock(return_value=fake_result)
+ mock_assign.side_effect = lambda cf, _registry: (
+ mock_pdf if cf.path.suffix == ".pdf" else None
+ )
+ result = await parser.parse(str(tmp_path), split_content=False)
+
+ root = f"{result.temp_dir_path}/{tmp_path.name}"
+ assert result.meta["failed_files"] == []
+ assert fake_fs.files[f"{root}/novel/report.md"] == b"# Converted PDF"
+ assert not any(uri.startswith(f"{root}/novel/report/") for uri in fake_fs.files)
+
+ @pytest.mark.asyncio
+ async def test_no_split_keeps_pdf_wrapper_for_markdown_and_image_outputs(
+ self,
+ tmp_path: Path,
+ parser,
+ fake_fs,
+ ) -> None:
+ pdf_file = tmp_path / "report.pdf"
+ pdf_file.write_bytes(b"%PDF-1.4 fake pdf")
+ mock_temp = fake_fs.create_temp_uri()
+ doc_dir = f"{mock_temp}/report"
+ await fake_fs.mkdir(mock_temp)
+ await fake_fs.mkdir(doc_dir)
+ await fake_fs.write_file(f"{doc_dir}/report.md", "# Converted PDF")
+ await fake_fs.write_file(f"{doc_dir}/page1.png", b"image")
+ fake_result = create_parse_result(
+ root=ResourceNode(type=NodeType.ROOT),
+ source_path=str(pdf_file),
+ source_format="pdf",
+ parser_name="PDFParser",
+ parse_time=0.1,
+ )
+ fake_result.temp_dir_path = mock_temp
+
+ with patch(
+ "openviking.parse.parsers.directory.DirectoryParser._assign_parser",
+ ) as mock_assign:
+ from openviking.parse.parsers.pdf import PDFParser as _PDF
+
+ mock_pdf = AsyncMock(spec=_PDF)
+ mock_pdf.parse = AsyncMock(return_value=fake_result)
+ mock_assign.side_effect = lambda cf, _registry: (
+ mock_pdf if cf.path.suffix == ".pdf" else None
+ )
+ result = await parser.parse(str(tmp_path), split_content=False)
+
+ root = f"{result.temp_dir_path}/{tmp_path.name}"
+ assert fake_fs.files[f"{root}/report/report.md"] == b"# Converted PDF"
+ assert fake_fs.files[f"{root}/report/page1.png"] == b"image"
+
@pytest.mark.asyncio
async def test_pdf_parse_failure_adds_warning(self, tmp_path: Path, parser, fake_fs) -> None:
pdf_file = tmp_path / "bad.pdf"
diff --git a/tests/parse/test_document_parser_threading.py b/tests/parse/test_document_parser_threading.py
index b4e39ba9c..35e9165a0 100644
--- a/tests/parse/test_document_parser_threading.py
+++ b/tests/parse/test_document_parser_threading.py
@@ -101,6 +101,22 @@ async def test_word_parser_forwards_original_name_to_markdown(monkeypatch, tmp_p
assert forwarded == "季度报告.docx", seen["kwargs"]
+async def test_word_parser_forwards_no_split_to_markdown(monkeypatch, tmp_path: Path):
+ parser = word.WordParser()
+ seen = _stub_markdown_parse(parser)
+ _patch_to_thread(monkeypatch, word)
+ monkeypatch.setitem(sys.modules, "docx", SimpleNamespace())
+ monkeypatch.setattr(parser, "_convert_to_markdown", lambda *args, **kwargs: "# converted docx")
+
+ upload = tmp_path / "screenplay.docx"
+ upload.write_bytes(b"placeholder")
+
+ await parser.parse(upload, split_content=False)
+
+ assert seen["kwargs"]["split_content"] is False
+
+
@pytest.mark.asyncio
async def test_excel_parser_offloads_xlsx_conversion(monkeypatch, tmp_path: Path):
parser = excel.ExcelParser()
diff --git a/tests/parse/test_excel_process_pool.py b/tests/parse/test_excel_process_pool.py
index 736d6038e..2f376a7d5 100644
--- a/tests/parse/test_excel_process_pool.py
+++ b/tests/parse/test_excel_process_pool.py
@@ -14,6 +14,7 @@ from pathlib import Path
import pytest
+from openviking.parse.parsers import excel as excel_module
from openviking.parse.parsers.excel import (
ExcelParser,
_EXCEL_PROCESS_POOL_MIN_BYTES,
@@ -78,6 +79,36 @@ class TestShouldUseProcessPool:
)
+async def test_process_pool_forwards_no_split_layout_flag(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+):
+ path = tmp_path / "sheet.xlsx"
+ path.write_bytes(b"xlsx")
+ parser = ExcelParser(config=ExcelConfig(enable_process_pool=True))
+ monkeypatch.setattr(
+ parser._md_parser,
+ "_create_temp_uri",
+ lambda: "viking://temp/test/excel",
+ )
+ captured = {}
+
+ class _CapturingLoop:
+ def run_in_executor(self, _executor, callback):
+ captured["callback"] = callback
+ raise RuntimeError("layout callback captured")
+
+ monkeypatch.setattr(excel_module.asyncio, "get_running_loop", lambda: _CapturingLoop())
+ monkeypatch.setattr(excel_module, "_get_excel_layout_executor", lambda _workers: object())
+
+ with pytest.raises(RuntimeError, match="layout callback captured"):
+ await parser._parse_existing_path_process_pool(path, split_content=False)
+
+ callback = captured["callback"]
+ assert callback.keywords["layout_kwargs"]["split_content"] is False
+
+
class TestExcelConfig:
def test_defaults(self):
cfg = ExcelConfig()
diff --git a/tests/parse/test_markdown_filename_collision.py b/tests/parse/test_markdown_filename_collision.py
index 1ff44a254..5ce209265 100644
--- a/tests/parse/test_markdown_filename_collision.py
+++ b/tests/parse/test_markdown_filename_collision.py
@@ -78,7 +78,7 @@ class TestMarkdownSourceNameLayout:
layout = await parser._compute_layout(
"echo hello\n",
"viking://temp/test",
- source_name="script.sh",
+ source_name="script.css",
)
assert layout.root_dir == "viking://temp/test/script"
diff --git a/tests/parse/test_markdown_link_rewrite.py b/tests/parse/test_markdown_link_rewrite.py
index a1f26f494..9c0ad23fb 100644
--- a/tests/parse/test_markdown_link_rewrite.py
+++ b/tests/parse/test_markdown_link_rewrite.py
@@ -5,6 +5,8 @@
from pathlib import Path
from unittest.mock import patch
+import pytest
+
from openviking.parse.parsers.base_parser import BaseParser
from openviking.parse.parsers.directory import DirectoryParser
from openviking.parse.parsers.markdown import MarkdownParser
@@ -335,6 +337,32 @@ class TestComputeLayoutPurity:
class TestParseContentRewiring:
+ async def test_no_split_probe_rewrites_anchor_to_actual_single_file(
+ self,
+ tmp_path: Path,
+ ):
+ kb = tmp_path / "knowledge"
+ kb.mkdir()
+ manual = kb / "manual.md"
+ manual.write_text(
+ "# 安装\n\n" + ("这是一段足够长的安装说明。" * 1200),
+ encoding="utf-8",
+ )
+ index = kb / "index.md"
+ index.write_text("[安装说明](manual.md#安装)", encoding="utf-8")
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ await MarkdownParser().parse(
+ str(index),
+ enable_link_rewrite=True,
+ link_rewrite_root=str(kb),
+ split_content=False,
+ )
+
+ written = [_decode(value) for uri, value in fake.files.items() if uri.endswith(".md")]
+ assert written == ["[安装说明](../manual/manual.md#安装)"]
+
async def test_parse_content_rewrites_link_when_enabled(self, tmp_path: Path):
kb = tmp_path / "knowledge"
tgt = kb / "目录甲" / "目录乙" / "目录丙"
@@ -389,6 +417,64 @@ class TestParseContentRewiring:
class TestDirectoryEndToEnd:
+ async def test_no_split_flat_markdown_keeps_cross_file_link_valid(self, tmp_path: Path):
+ kb = tmp_path / "knowledge"
+ kb.mkdir()
+ (kb / "target.md").write_text("# 目标\n\n内容", encoding="utf-8")
+ (kb / "source.md").write_text(
+ "见 [目标](target.md#目标)",
+ encoding="utf-8",
+ )
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ result = await DirectoryParser().parse(str(kb), split_content=False)
+
+ root = f"{result.temp_dir_path}/{kb.name}"
+ assert _decode(fake.files[f"{root}/source.md"]) == "见 [目标](target.md#目标)"
+ assert _decode(fake.files[f"{root}/target.md"]) == "# 目标\n\n内容"
+
+ async def test_no_split_wrapped_source_links_to_flat_target(self, tmp_path: Path):
+ kb = tmp_path / "knowledge"
+ kb.mkdir()
+ _write_valid_png(kb / "cover.png")
+ (kb / "target.md").write_text("# 目标\n\n内容", encoding="utf-8")
+ (kb / "source.md").write_text(
+ "![封面](cover.png)\n\n见 [目标](target.md#目标)",
+ encoding="utf-8",
+ )
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ result = await DirectoryParser().parse(str(kb), split_content=False)
+
+ root = f"{result.temp_dir_path}/{kb.name}"
+ source = _decode(fake.files[f"{root}/source/source.md"])
+ assert "见 [目标](../target.md#目标)" in source
+ assert f"{root}/target.md" in fake.files
+
+ async def test_no_split_flat_source_links_to_wrapped_target(self, tmp_path: Path):
+ kb = tmp_path / "knowledge"
+ kb.mkdir()
+ _write_valid_png(kb / "cover.png")
+ (kb / "target.md").write_text(
+ "# 目标\n\n![封面](cover.png)",
+ encoding="utf-8",
+ )
+ (kb / "source.md").write_text(
+ "见 [目标](target.md#目标)",
+ encoding="utf-8",
+ )
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ result = await DirectoryParser().parse(str(kb), split_content=False)
+
+ root = f"{result.temp_dir_path}/{kb.name}"
+ source = _decode(fake.files[f"{root}/source.md"])
+ assert source == "见 [目标](target/target.md#目标)"
+ assert f"{root}/target/cover.png" in fake.files
+
async def test_directory_ingest_rewrites_cross_file_link(self, tmp_path: Path):
kb = tmp_path / "knowledge"
tgt = kb / "目录甲" / "目录乙" / "目录丙"
@@ -673,6 +759,51 @@ class TestRewriteImageUris:
assert f"{dest}/doc/doc.md" in fake.files
assert not any(u.endswith(".stray_hidden") for u in fake.files), fake.files
+ async def test_flatten_single_output_does_not_overwrite_existing_destination(self):
+ fake = FakeVikingFS()
+ src = "viking://temp/source"
+ wrapper = f"{src}/report"
+ dest = "viking://resources/import"
+ await fake.mkdir(src)
+ await fake.mkdir(wrapper)
+ await fake.mkdir(dest)
+ await fake.write_file(f"{wrapper}/report.md", b"new")
+ await fake.write_file(f"{dest}/report.md", b"existing")
+
+ await DirectoryParser._merge_temp(
+ fake,
+ src,
+ dest,
+ flatten_single_output=True,
+ )
+
+ assert fake.files[f"{dest}/report.md"] == b"existing"
+ assert fake.files[f"{dest}/report/report.md"] == b"new"
+
+ async def test_flatten_single_output_keeps_wrapper_with_mapping_sidecar(self):
+ fake = FakeVikingFS()
+ src = "viking://temp/source"
+ wrapper = f"{src}/report"
+ dest = "viking://resources/import"
+ await fake.mkdir(src)
+ await fake.mkdir(wrapper)
+ await fake.mkdir(dest)
+ await fake.write_file(f"{wrapper}/report.md", b"body")
+ await fake.write_file(
+ f"{wrapper}/.image_mappings.json",
+ b'{"report.md": {}}',
+ )
+
+ await DirectoryParser._merge_temp(
+ fake,
+ src,
+ dest,
+ flatten_single_output=True,
+ )
+
+ assert fake.files[f"{dest}/report/report.md"] == b"body"
+ assert f"{dest}/report/.image_mappings.json" in fake.files
+
async def test_sync_path_carries_nested_mappings_to_target(self):
# Re-ingest of an existing resource goes through SemanticProcessor's
# temp->target sync, which MOVES the visible files into the target and
@@ -708,7 +839,12 @@ class TestRewriteImageUris:
assert _decode(fake.files[f"{target}/index/index.md"]) == (f"![p]({target}/index/logo.png)")
- async def test_directory_ingest_images_become_viking_uris(self, tmp_path: Path):
+ @pytest.mark.parametrize("split_content", [True, False])
+ async def test_directory_ingest_images_become_viking_uris(
+ self,
+ tmp_path: Path,
+ split_content: bool,
+ ):
# End to end: directory ingest -> persist -> rewrite. Every md referencing
# an ingestable image must end up with a viking:// URI.
from openviking.parse.image_rewrite import rewrite_image_uris
@@ -721,7 +857,10 @@ class TestRewriteImageUris:
fake = FakeVikingFS()
with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
- result = await DirectoryParser().parse(str(kb))
+ result = await DirectoryParser().parse(
+ str(kb),
+ split_content=split_content,
+ )
# Simulate finalize_from_temp + persist_temp_tree: the single doc dir
# under the temp root is mirrored onto the final resource root.
diff --git a/tests/parse/test_markdown_no_split.py b/tests/parse/test_markdown_no_split.py
new file mode 100644
index 000000000..62f5d18a6
--- /dev/null
+++ b/tests/parse/test_markdown_no_split.py
@@ -0,0 +1,133 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Tests for parsed documents whose Markdown body must remain in one file."""
+
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.parse.mode import ParseMode, normalize_parse_mode
+from openviking.parse.parsers.markdown import MarkdownParser
+from openviking.parse.parsers.pdf import PDFParser
+from openviking_cli.exceptions import InvalidArgumentError
+from openviking_cli.utils.config.parser_config import ParserConfig, PDFConfig
+
+
+class _FakeVikingFS:
+ def __init__(self) -> None:
+ self.files: dict[str, str] = {}
+ self.directories: set[str] = set()
+
+ def create_temp_uri(self) -> str:
+ return "viking://temp/pdf-no-split"
+
+ async def mkdir(self, uri: str, exist_ok: bool = False) -> None:
+ del exist_ok
+ self.directories.add(uri)
+
+ async def write_file(self, uri: str, content: str) -> None:
+ self.files[uri] = content
+
+
+def _long_markdown(*, with_headings: bool = False) -> str:
+ sections = []
+ for index in range(30):
+ heading = f"## Scene {index}\n\n" if with_headings else ""
+ sections.append(f"{heading}paragraph {index} " + "x" * 500)
+ return "\n\n".join(sections)
+
+
+def test_normalize_parse_mode_accepts_no_split_and_rejects_no_parse() -> None:
+ assert normalize_parse_mode("default") is ParseMode.DEFAULT
+ assert normalize_parse_mode("no_split") is ParseMode.NO_SPLIT
+ assert normalize_parse_mode(ParseMode.NO_SPLIT) is ParseMode.NO_SPLIT
+
+ with pytest.raises(InvalidArgumentError, match="default, no_split"):
+ normalize_parse_mode("no_parse")
+
+
[email protected]("with_headings", [False, True])
+async def test_long_markdown_no_split_plans_one_complete_file(
+ with_headings: bool,
+) -> None:
+ content = _long_markdown(with_headings=with_headings)
+ parser = MarkdownParser(
+ config=ParserConfig(max_section_size=32, max_section_chars=128)
+ )
+
+ layout = await parser._compute_layout(
+ content,
+ "viking://temp/test",
+ source_path="/tmp/社交网络中英文剧本.pdf",
+ resource_name="社交网络中英文剧本",
+ split_content=False,
+ )
+
+ writes = [op for op in layout.ops if op.kind == "write"]
+ assert [(op.uri, op.content) for op in writes] == [
+ (
+ "viking://temp/test/社交网络中英文剧本/社交网络中英文剧本.md",
+ content,
+ )
+ ]
+
+
+async def test_long_markdown_default_mode_still_splits() -> None:
+ content = _long_markdown()
+ parser = MarkdownParser(
+ config=ParserConfig(max_section_size=32, max_section_chars=128)
+ )
+
+ layout = await parser._compute_layout(
+ content,
+ "viking://temp/test",
+ source_path="/tmp/社交网络中英文剧本.pdf",
+ resource_name="社交网络中英文剧本",
+ )
+
+ writes = [op for op in layout.ops if op.kind == "write"]
+ assert len(writes) > 1
+
+
+async def test_pdf_no_split_converts_to_one_complete_markdown(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+) -> None:
+ source = tmp_path / "社交网络中英文剧本.pdf"
+ source.write_bytes(b"%PDF-fixture")
+ content = _long_markdown(with_headings=True)
+ fake_fs = _FakeVikingFS()
+ parser = PDFParser(
+ PDFConfig(strategy="local", max_section_size=32, max_section_chars=128)
+ )
+ markdown_parser = parser._get_markdown_parser()
+ monkeypatch.setattr(markdown_parser, "_get_viking_fs", lambda: fake_fs)
+ monkeypatch.setattr(
+ parser,
+ "_convert_to_markdown",
+ AsyncMock(return_value=(content, {})),
+ )
+ monkeypatch.setattr(
+ "openviking_cli.utils.storage.get_storage",
+ lambda: SimpleNamespace(media_dir=tmp_path),
+ )
+
+ result = await parser.parse(
+ source,
+ resource_name="社交网络中英文剧本",
+ split_content=False,
+ )
+
+ assert result.parser_name == "PDFParser"
+ assert fake_fs.files == {
+ (
+ "viking://temp/pdf-no-split/社交网络中英文剧本/"
+ "社交网络中英文剧本.md"
+ ): content
+ }
+ assert not any(uri.endswith(".pdf") for uri in fake_fs.files)
diff --git a/tests/parse/test_resource_processor_no_split.py b/tests/parse/test_resource_processor_no_split.py
new file mode 100644
index 000000000..ea55ce7fc
--- /dev/null
+++ b/tests/parse/test_resource_processor_no_split.py
@@ -0,0 +1,82 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Tests for routing parsed resources through no-split mode."""
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from openviking.parse.accessors.base import LocalResource, SourceType
+from openviking.parse.base import NodeType, ResourceNode, create_parse_result
+from openviking.parse.parser_router import ParserRouter
+from openviking.utils.media_processor import UnifiedResourceProcessor
+from openviking_cli.exceptions import InvalidArgumentError
+
+
+class _AccessorRegistry:
+ def __init__(self, resource: LocalResource) -> None:
+ self.resource = resource
+
+ async def access(self, _source: str, **_kwargs: Any) -> LocalResource:
+ return self.resource
+
+
+class _RecordingParserRouter:
+ def __init__(self) -> None:
+ self.kwargs: dict[str, Any] | None = None
+
+ async def parse(self, resource: LocalResource, **kwargs: Any):
+ self.kwargs = kwargs
+ return create_parse_result(
+ root=ResourceNode(type=NodeType.ROOT, title=resource.path.stem),
+ source_path=str(resource.path),
+ source_format="markdown",
+ parser_name="RecordingParser",
+ )
+
+
+class _UnusedRegistry:
+ async def parse(self, _source: Any, **_kwargs: Any):
+ raise AssertionError("internal parser must not run when Understanding is selected")
+
+
+def _local_resource(path: Path) -> LocalResource:
+ return LocalResource(
+ path=path,
+ source_type=SourceType.LOCAL,
+ original_source=str(path),
+ is_temporary=False,
+ )
+
+
+async def test_unified_processor_no_split_still_uses_parser_router(
+ tmp_path: Path,
+) -> None:
+ source = tmp_path / "guide.md"
+ source.write_text("# guide", encoding="utf-8")
+ router = _RecordingParserRouter()
+ processor = UnifiedResourceProcessor(vlm_processor=object())
+ processor._accessor_registry = _AccessorRegistry(_local_resource(source))
+ processor._parser_router = router
+
+ result = await processor.process(str(source), parse_mode="no_split")
+
+ assert result.parser_name == "RecordingParser"
+ assert router.kwargs is not None
+ assert router.kwargs["split_content"] is False
+
+
+async def test_parser_router_rejects_no_split_for_understanding_backend(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+) -> None:
+ source = tmp_path / "manual.pdf"
+ source.write_bytes(b"%PDF-fixture")
+ router = ParserRouter(_UnusedRegistry()) # type: ignore[arg-type]
+ monkeypatch.setattr(router, "should_use_understanding_api", lambda *_args, **_kwargs: True)
+
+ with pytest.raises(InvalidArgumentError, match="no_split.*Understanding"):
+ await router.parse(_local_resource(source), split_content=False)
diff --git a/tests/resource/test_watch_manager.py b/tests/resource/test_watch_manager.py
index 3493b4032..66c13dc33 100644
--- a/tests/resource/test_watch_manager.py
+++ b/tests/resource/test_watch_manager.py
@@ -171,6 +171,7 @@ class TestWatchTask:
task = WatchTask.from_dict({"path": "/test/path"})
assert task.processing_mode == "semantic_and_vectors"
+ assert task.to_is_directory is None
def test_calculate_next_execution_time(self):
"""Test calculating next execution time."""
diff --git a/tests/server/test_mcp_parse_mode.py b/tests/server/test_mcp_parse_mode.py
new file mode 100644
index 000000000..609e222a0
--- /dev/null
+++ b/tests/server/test_mcp_parse_mode.py
@@ -0,0 +1,116 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""MCP add_resource parse-mode propagation tests."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.server import mcp_endpoint
+from openviking.server.identity import RequestContext, Role
+from openviking.server.upload_token_store import upload_token_store
+from openviking_cli.session.user_id import UserIdentifier
+
+
[email protected](autouse=True)
+def mcp_context(monkeypatch: pytest.MonkeyPatch):
+ ctx = RequestContext(
+ user=UserIdentifier("test_account", "test_user"),
+ role=Role.USER,
+ )
+ token = mcp_endpoint._mcp_ctx.set(ctx)
+ service = SimpleNamespace(
+ resources=SimpleNamespace(
+ add_resource=AsyncMock(
+ return_value={"root_uri": "viking://resources/test", "task_id": "task-1"}
+ )
+ )
+ )
+ monkeypatch.setattr(mcp_endpoint, "get_service", lambda: service)
+ upload_token_store.clear()
+ yield service
+ upload_token_store.clear()
+ mcp_endpoint._mcp_ctx.reset(token)
+
+
+async def test_mcp_add_resource_schema_exposes_parse_mode_only_through_args(mcp_context):
+ tools = {tool.name: tool for tool in await mcp_endpoint.mcp.list_tools()}
+ schema = tools["add_resource"].inputSchema
+
+ assert "parse_mode" not in schema["properties"]
+ assert "args" in schema["properties"]
+
+
+async def test_mcp_remote_add_forwards_no_split(
+ monkeypatch: pytest.MonkeyPatch,
+ mcp_context,
+):
+ monkeypatch.setattr(mcp_endpoint, "_maybe_sitemap_hint", AsyncMock(return_value=""))
+
+ result = await mcp_endpoint.add_resource(
+ path="https://example.com/manual.pdf",
+ args={"parse_mode": "no_split"},
+ )
+
+ assert "Resource added" in result
+ assert mcp_context.resources.add_resource.await_args.kwargs["args"] == {
+ "parse_mode": "no_split"
+ }
+
+
+async def test_mcp_temp_file_id_forwards_no_split(
+ monkeypatch: pytest.MonkeyPatch,
+ mcp_context,
+):
+ ingest = AsyncMock(return_value={"root_uri": "viking://resources/upload"})
+ monkeypatch.setattr(mcp_endpoint, "ingest_temp_upload", ingest)
+ monkeypatch.setattr(
+ mcp_endpoint.TempUploadStore,
+ "build",
+ lambda _config: object(),
+ )
+
+ result = await mcp_endpoint.add_resource(
+ temp_file_id="upload_abcdef123.md",
+ args={"parse_mode": "no_split"},
+ )
+
+ assert "Resource added" in result
+ assert ingest.await_args.kwargs["args"] == {"parse_mode": "no_split"}
+
+
+async def test_mcp_local_upload_token_binds_no_split(
+ monkeypatch: pytest.MonkeyPatch,
+ mcp_context,
+):
+ monkeypatch.setattr(
+ mcp_endpoint,
+ "_resolve_public_base_url",
+ lambda: ("https://ov.example.com", "config"),
+ )
+
+ await mcp_endpoint.add_resource(
+ path="/tmp/manual.pdf",
+ args={"parse_mode": "no_split"},
+ )
+
+ assert len(upload_token_store._store) == 1
+ token_info = next(iter(upload_token_store._store.values()))
+ assert token_info.parse_mode == "no_split"
+
+
+async def test_mcp_rejects_invalid_parse_mode(mcp_context):
+ result = await mcp_endpoint.add_resource(
+ path="https://example.com/manual.pdf",
+ args={"parse_mode": "unsupported"},
+ )
+
+ assert "Error" in result
+ assert "parse_mode" in result
diff --git a/tests/server/test_resource_ingest_parse_mode.py b/tests/server/test_resource_ingest_parse_mode.py
new file mode 100644
index 000000000..072facb86
--- /dev/null
+++ b/tests/server/test_resource_ingest_parse_mode.py
@@ -0,0 +1,49 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""parse_mode propagation through shared temp-upload ingestion."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.server import resource_ingest
+from openviking.server.identity import RequestContext, Role
+from openviking_cli.session.user_id import UserIdentifier
+
+
+async def test_ingest_temp_upload_forwards_no_split(monkeypatch: pytest.MonkeyPatch):
+ resolved = SimpleNamespace(
+ local_path="/tmp/upload.bin",
+ original_filename="upload.bin",
+ cleanup=AsyncMock(),
+ )
+ store = SimpleNamespace(
+ resolve_for_consume=AsyncMock(return_value=resolved),
+ mark_consumed=AsyncMock(),
+ mark_failed=AsyncMock(),
+ )
+ add_resource = AsyncMock(
+ return_value={"status": "success", "root_uri": "viking://resources/upload"}
+ )
+ monkeypatch.setattr(
+ resource_ingest,
+ "get_service",
+ lambda: SimpleNamespace(resources=SimpleNamespace(add_resource=add_resource)),
+ )
+ ctx = RequestContext(
+ user=UserIdentifier("test_account", "test_user"),
+ role=Role.USER,
+ )
+
+ await resource_ingest.ingest_temp_upload(
+ store,
+ "upload-id",
+ ctx,
+ parse_mode="no_split",
+ )
+
+ assert add_resource.await_args.kwargs["args"] == {"parse_mode": "no_split"}
+ assert "parse_mode" not in add_resource.await_args.kwargs
diff --git a/tests/server/test_resource_parse_mode_request.py b/tests/server/test_resource_parse_mode_request.py
new file mode 100644
index 000000000..9a283737a
--- /dev/null
+++ b/tests/server/test_resource_parse_mode_request.py
@@ -0,0 +1,89 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""Request-boundary coverage for add_resource parse modes."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from openviking.server.identity import RequestContext, Role
+from openviking.server.routers import resources as resources_router
+from openviking.server.routers.resources import AddResourceRequest
+from openviking.server.upload_token_store import ConsumedUploadToken
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def test_add_resource_request_exposes_parse_mode_only_inside_args():
+ request = AddResourceRequest(
+ path="https://example.com/demo.md",
+ args={"parse_mode": "no_split"},
+ preserve_structure=False,
+ )
+
+ assert "parse_mode" not in AddResourceRequest.model_json_schema()["properties"]
+ assert request.args == {"parse_mode": "no_split"}
+
+
+async def test_add_resource_route_forwards_no_split_mode(monkeypatch: pytest.MonkeyPatch):
+ add_resource = AsyncMock(
+ return_value={"status": "success", "root_uri": "viking://resources/demo"}
+ )
+ service = SimpleNamespace(resources=SimpleNamespace(add_resource=add_resource))
+ monkeypatch.setattr(resources_router, "get_service", lambda: service)
+ ctx = RequestContext(
+ user=UserIdentifier("test_account", "test_user"),
+ role=Role.USER,
+ )
+
+ await resources_router.add_resource(
+ SimpleNamespace(),
+ AddResourceRequest(
+ path="https://example.com/demo.md",
+ args={"parse_mode": "no_split"},
+ ),
+ ctx,
+ )
+
+ assert add_resource.await_args.kwargs["args"] == {"parse_mode": "no_split"}
+
+
+async def test_signed_temp_upload_forwards_token_bound_parse_mode(
+ monkeypatch: pytest.MonkeyPatch,
+):
+ signed = ConsumedUploadToken(
+ account_id="test_account",
+ user_id="test_user",
+ to="",
+ reason="",
+ actor_peer_id="",
+ parse_mode="no_split",
+ )
+ request = SimpleNamespace(
+ state=SimpleNamespace(signed_upload=signed),
+ app=SimpleNamespace(state=SimpleNamespace(config=object())),
+ )
+ store = SimpleNamespace(save_upload=AsyncMock(return_value="upload-id"))
+ monkeypatch.setattr(resources_router.TempUploadStore, "build", lambda _config: store)
+ ingest = AsyncMock(return_value={"root_uri": "viking://resources/upload"})
+ monkeypatch.setattr(resources_router, "ingest_temp_upload", ingest)
+
+ async def run_operation(*, operation, telemetry, fn):
+ return SimpleNamespace(result=await fn(), telemetry=None)
+
+ monkeypatch.setattr(resources_router, "run_operation", run_operation)
+
+ await resources_router.temp_upload(
+ request,
+ object(),
+ False,
+ "local",
+ RequestContext(
+ user=UserIdentifier("test_account", "test_user"),
+ role=Role.USER,
+ ),
+ )
+
+ assert ingest.await_args.kwargs["parse_mode"] == "no_split"
diff --git a/tests/server/test_upload_token_store.py b/tests/server/test_upload_token_store.py
index 4cb6dced8..13baad07e 100644
--- a/tests/server/test_upload_token_store.py
+++ b/tests/server/test_upload_token_store.py
@@ -32,6 +32,7 @@ def test_consume_roundtrip(store):
assert (consumed.account_id, consumed.user_id) == ("acct", "user")
# Business params default to empty when not supplied at issue time.
assert (consumed.to, consumed.reason, consumed.actor_peer_id) == ("", "", "")
+ assert consumed.parse_mode == "default"
def test_consume_returns_bound_business_params(store):
@@ -43,12 +44,14 @@ def test_consume_returns_bound_business_params(store):
reason="quarterly",
actor_peer_id="bot-a",
processing_mode="vectors_only",
+ parse_mode="no_split",
)
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"
+ assert consumed.parse_mode == "no_split"
def test_consume_burns_token(store):
diff --git a/tests/service/test_resource_service_connector.py b/tests/service/test_resource_service_connector.py
index 16ebc0956..cb930deb3 100644
--- a/tests/service/test_resource_service_connector.py
+++ b/tests/service/test_resource_service_connector.py
@@ -10,6 +10,7 @@ import httpx
import pytest
from openviking.connector import delegate as connector_delegate_module
+from openviking.parse.mode import ParseMode
from openviking.server.identity import RequestContext, Role
from openviking.service import resource_service as resource_service_module
from openviking.service.resource_service import ResourceService
@@ -489,6 +490,12 @@ def test_connector_only_route_rejects_disabled_or_unsupported_requests(
with pytest.raises(InvalidArgumentError, match="args keys"):
service._connector.should_delegate("tos://bucket/prefix", connector_args={"parser": "pdf"})
+ with pytest.raises(InvalidArgumentError, match="parse_mode=no_split"):
+ service._connector.should_delegate(
+ "tos://bucket/prefix",
+ parse_mode=ParseMode.NO_SPLIT,
+ )
+
connector_config.enable = False
with pytest.raises(InvalidArgumentError, match="Connector integration"):
service._connector.should_delegate("tos://bucket/prefix")
@@ -534,6 +541,18 @@ def test_git_connector_detection_accepts_explicit_protocol_repo(monkeypatch, pat
assert detect_connector_add_type(path) == ("git", False)
+def test_shared_connector_source_falls_back_for_no_split(connector_config, service):
+ connector_config.allowed_add_types = ["https"]
+
+ assert (
+ service._connector.should_delegate(
+ "https://example.com/manual.pdf",
+ parse_mode=ParseMode.NO_SPLIT,
+ )
+ is False
+ )
+
+
@pytest.mark.parametrize(
"path",
[
diff --git a/tests/service/test_resource_service_parse_mode.py b/tests/service/test_resource_service_parse_mode.py
new file mode 100644
index 000000000..ae0b6c2e9
--- /dev/null
+++ b/tests/service/test_resource_service_parse_mode.py
@@ -0,0 +1,306 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""ResourceService coverage for add_resource parse modes."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from openviking.resource.watch_manager import WatchManager, WatchTask
+from openviking.resource.watch_scheduler import WatchScheduler
+from openviking.server.identity import RequestContext, Role
+from openviking.service import resource_service as resource_service_module
+from openviking.service.resource_service import ResourceService
+from openviking.storage.queuefs.add_resource_msg import AddResourceMsg
+from openviking_cli.exceptions import InvalidArgumentError
+from openviking_cli.session.user_id import UserIdentifier
+
+
+class _ResourceProcessor:
+ def __init__(self):
+ self.calls = []
+ self.root_is_file = True
+
+ async def process_resource(self, **kwargs):
+ self.calls.append(kwargs)
+ return {
+ "status": "success",
+ "root_uri": "viking://resources/test",
+ "_post_process": {"root_is_file": self.root_is_file},
+ }
+
+
+class _DiscardedBackgroundTask:
+ def add_done_callback(self, callback):
+ callback(self)
+
+
+def ctx() -> RequestContext:
+ return RequestContext(
+ user=UserIdentifier("test_account", "test_user"),
+ role=Role.USER,
+ )
+
+
+def service(monkeypatch: pytest.MonkeyPatch) -> ResourceService:
+ tracker = SimpleNamespace(
+ create=AsyncMock(return_value=SimpleNamespace(task_id="task-1")),
+ fail=AsyncMock(),
+ )
+ monkeypatch.setattr(
+ "openviking.service.task_tracker.get_task_tracker",
+ lambda: tracker,
+ )
+ monkeypatch.setattr(resource_service_module, "is_git_repo_url", lambda _path: False)
+
+ def discard_background(coro):
+ coro.close()
+ return _DiscardedBackgroundTask()
+
+ monkeypatch.setattr(resource_service_module.asyncio, "create_task", discard_background)
+
+ instance = ResourceService(
+ vikingdb=object(),
+ viking_fs=object(),
+ resource_processor=_ResourceProcessor(),
+ skill_processor=object(),
+ )
+ monkeypatch.setattr(instance._connector, "should_delegate", lambda *_args, **_kwargs: False)
+ monkeypatch.setattr(
+ instance,
+ "_enqueue_add_resource_job",
+ AsyncMock(return_value=SimpleNamespace(task_id="task-1")),
+ )
+ return instance
+
+
+async def test_no_split_is_forwarded_and_persisted_for_watch_replay(
+ service: ResourceService,
+ ctx: RequestContext,
+):
+ watch_manager = SimpleNamespace(
+ get_task_by_uri=AsyncMock(return_value=None),
+ create_task=AsyncMock(return_value=SimpleNamespace(task_id="watch-1")),
+ )
+ scheduler = SimpleNamespace(watch_manager=watch_manager)
+ service._watch_scheduler = scheduler
+
+ await service.add_resource(
+ path="/test/path",
+ ctx=ctx,
+ to="viking://resources/no_split_watch",
+ watch_interval=30.0,
+ args={"parse_mode": "no_split"},
+ )
+
+ processor = service._resource_processor
+ assert processor.calls[-1]["parse_mode"] == "no_split"
+ assert watch_manager.create_task.await_args.kwargs["processor_kwargs"]["parse_mode"] == (
+ "no_split"
+ )
+
+
+async def test_no_split_watch_replay_preserves_auto_bound_file_target(
+ service: ResourceService,
+ ctx: RequestContext,
+):
+ watch_manager = WatchManager(viking_fs=None)
+ await watch_manager.initialize()
+ scheduler = WatchScheduler(resource_service=service, check_interval=1)
+ scheduler._watch_manager = watch_manager
+ service._watch_scheduler = scheduler
+
+ await service.add_resource(
+ path="https://example.com/guide.md",
+ ctx=ctx,
+ watch_interval=30.0,
+ args={"parse_mode": "no_split"},
+ )
+
+ tasks = await watch_manager.get_all_tasks(
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ role=str(ctx.role),
+ )
+ assert len(tasks) == 1
+ task = tasks[0]
+ assert task.to_uri == "viking://resources/test"
+ assert task.to_is_directory is False
+ task = WatchTask.from_dict(task.to_storage_dict())
+
+ await scheduler._execute_task(task)
+
+ processor = service._resource_processor
+ assert processor.calls[-1]["to"] == "viking://resources/test"
+ assert processor.calls[-1]["to_is_directory"] is False
+
+
+async def test_no_split_watch_persists_auto_bound_multi_artifact_directory(
+ service: ResourceService,
+ ctx: RequestContext,
+):
+ service._resource_processor.root_is_file = False
+ watch_manager = WatchManager(viking_fs=None)
+ await watch_manager.initialize()
+ service._watch_scheduler = SimpleNamespace(watch_manager=watch_manager)
+
+ await service.add_resource(
+ path="https://example.com/guide.md",
+ ctx=ctx,
+ watch_interval=30.0,
+ args={"parse_mode": "no_split"},
+ )
+
+ tasks = await watch_manager.get_all_tasks(
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ role=str(ctx.role),
+ )
+ assert len(tasks) == 1
+ assert tasks[0].to_is_directory is True
+
+
+async def test_accepts_parse_mode_inside_args_without_mutating_input(
+ service: ResourceService,
+ ctx: RequestContext,
+):
+ args = {"parse_mode": "no_split", "site": False}
+
+ await service.add_resource(
+ path="/test/path",
+ ctx=ctx,
+ to="viking://resources/test",
+ args=args,
+ )
+
+ assert args == {"parse_mode": "no_split", "site": False}
+ processor = service._resource_processor
+ assert processor.calls[-1]["parse_mode"] == "no_split"
+ assert processor.calls[-1]["site"] is False
+
+
+async def test_rejects_invalid_parse_mode(service: ResourceService, ctx: RequestContext):
+ with pytest.raises(InvalidArgumentError, match="parse_mode"):
+ await service.add_resource(
+ path="/test/path",
+ ctx=ctx,
+ to="viking://resources/test",
+ args={"parse_mode": "unsupported"},
+ )
+
+
+async def test_no_split_allows_directory_flattening(
+ service: ResourceService,
+ ctx: RequestContext,
+):
+ await service.add_resource(
+ path="/test/path",
+ ctx=ctx,
+ to="viking://resources/test",
+ args={"parse_mode": "no_split"},
+ preserve_structure=False,
+ )
+
+ processor = service._resource_processor
+ assert processor.calls[-1]["parse_mode"] == "no_split"
+ assert processor.calls[-1]["preserve_structure"] is False
+
+
+ "to_uri",
+ [
+ "viking://resources/0803_shendiao_01",
+ "viking://resources/0803_shendiao_01/",
+ ],
+)
+async def test_no_split_treats_explicit_to_as_directory_target(
+ service: ResourceService,
+ ctx: RequestContext,
+ to_uri: str,
+):
+ await service.add_resource(
+ path="/test/神雕.md",
+ ctx=ctx,
+ to=to_uri,
+ args={"parse_mode": "no_split"},
+ )
+
+ processor = service._resource_processor
+ assert processor.calls[-1]["to"] == "viking://resources/0803_shendiao_01"
+ assert processor.calls[-1]["to_is_directory"] is True
+
+
+async def test_no_split_bypasses_understanding_shortcut(
+ monkeypatch: pytest.MonkeyPatch,
+ service: ResourceService,
+ ctx: RequestContext,
+):
+ direct_probe = MagicMock(
+ side_effect=AssertionError("Understanding shortcut must not run in no_split mode")
+ )
+ api_probe = MagicMock(
+ side_effect=AssertionError("Understanding shortcut must not run in no_split mode")
+ )
+ monkeypatch.setattr(
+ service._resource_processor,
+ "should_use_understanding_directly",
+ direct_probe,
+ raising=False,
+ )
+ monkeypatch.setattr(
+ service._resource_processor,
+ "understanding_api_enabled",
+ api_probe,
+ raising=False,
+ )
+
+ await service.add_resource(
+ path="https://example.com/manual.pdf",
+ ctx=ctx,
+ to="viking://resources/manual",
+ args={"parse_mode": "no_split"},
+ allow_local_path_resolution=False,
+ )
+
+ direct_probe.assert_not_called()
+ api_probe.assert_not_called()
+
+
+async def test_native_git_enqueue_persists_internal_no_split_mode(
+ service: ResourceService,
+ ctx: RequestContext,
+):
+ service._preflight_git_source = AsyncMock(
+ return_value=SimpleNamespace(source_name="repo", source_path=None)
+ )
+ service._plan_resource_target = AsyncMock(
+ return_value=("viking://resources/repo", None)
+ )
+ service._enqueue_add_resource_job = AsyncMock(
+ return_value=SimpleNamespace(task_id="task-git")
+ )
+
+ result = await service.enqueue_git_add_resource(
+ path="https://github.com/volcengine/OpenViking.git",
+ ctx=ctx,
+ to="viking://resources/repo",
+ parse_mode="no_split",
+ )
+
+ assert result["task_id"] == "task-git"
+ message = service._enqueue_add_resource_job.await_args.args[0]
+ assert isinstance(message, AddResourceMsg)
+ assert message.parse_mode == "no_split"
diff --git a/tests/storage/test_semantic_dag_incremental.py b/tests/storage/test_semantic_dag_incremental.py
index b478c5fd0..1d9e8ed73 100644
--- a/tests/storage/test_semantic_dag_incremental.py
+++ b/tests/storage/test_semantic_dag_incremental.py
@@ -134,7 +134,8 @@ async def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypa
target_uri=root_uri,
changes={"modified": [f"{root_uri}/a.txt"]},
)
- monkeypatch.setattr(executor, "_add_vectorize_task", AsyncMock())
+ add_vectorize_task = AsyncMock()
+ monkeypatch.setattr(executor, "_add_vectorize_task", add_vectorize_task)
await executor.run(root_uri)
@@ -143,6 +144,17 @@ async def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypa
overview = fake_fs._file_contents[f"{root_uri}/.overview.md"]
assert "- a.txt: summary" in overview
assert "- b.txt: old-b" in overview
+ changed_file_tasks = [
+ call.args[0]
+ for call in add_vectorize_task.await_args_list
+ if call.args[0].task_type == "file"
+ ]
+ assert len(changed_file_tasks) == 1
+ assert changed_file_tasks[0].file_path == f"{root_uri}/a.txt"
+ assert changed_file_tasks[0].summary_dict == {
+ "name": "a.txt",
+ "summary": "summary",
+ }
if __name__ == "__main__":
diff --git a/tests/unit/test_summarizer_resources_root_split.py b/tests/unit/test_summarizer_resources_root_split.py
index ff16d0f0f..170408ae3 100644
--- a/tests/unit/test_summarizer_resources_root_split.py
+++ b/tests/unit/test_summarizer_resources_root_split.py
@@ -19,6 +19,11 @@ class _DummyQueue:
self.msgs.append(msg)
+class _FailingQueue:
+ async def enqueue(self, msg):
+ raise RuntimeError("queue unavailable")
+
+
class _DummyQueueManager:
SEMANTIC = "semantic"
@@ -32,10 +37,14 @@ class _DummyQueueManager:
class _DummyWaitTracker:
def __init__(self):
self.registered = []
+ self.failed = []
def register_semantic_root(self, telemetry_id, msg_id):
self.registered.append((telemetry_id, msg_id))
+ def mark_semantic_failed(self, telemetry_id, msg_id, error):
+ self.failed.append((telemetry_id, msg_id, error))
+
class _DummyVikingFS:
def __init__(self, entries_by_uri):
@@ -178,3 +187,67 @@ async def test_resources_root_empty_import_is_error():
assert res["status"] == "error"
assert queue.msgs == []
+
+
+async def test_flat_file_refresh_enqueues_incremental_parent_summary():
+ queue = _DummyQueue()
+ qm = _DummyQueueManager(queue)
+ wait_tracker = _DummyWaitTracker()
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)
+
+ with (
+ patch("openviking.utils.summarizer.get_queue_manager", return_value=qm),
+ patch(
+ "openviking.utils.summarizer.get_current_telemetry",
+ return_value=SimpleNamespace(telemetry_id="tid"),
+ ),
+ patch(
+ "openviking.utils.summarizer.get_request_wait_tracker",
+ return_value=wait_tracker,
+ ),
+ ):
+ result = await Summarizer(vlm_processor=None).refresh_file_parent(
+ file_uri="viking://resources/神雕.md",
+ ctx=ctx,
+ skip_vectorization=False,
+ )
+
+ assert result == {"status": "success", "enqueued_count": 1}
+ assert len(queue.msgs) == 1
+ msg = queue.msgs[0]
+ assert msg.uri == "viking://resources"
+ assert msg.recursive is False
+ assert msg.changes == {"modified": ["viking://resources/神雕.md"]}
+ assert msg.skip_vectorization is False
+ assert msg.telemetry_id == "tid"
+ assert wait_tracker.registered == [("tid", msg.id)]
+
+
+async def test_flat_file_refresh_marks_wait_failed_when_enqueue_fails():
+ qm = _DummyQueueManager(_FailingQueue())
+ wait_tracker = _DummyWaitTracker()
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)
+
+ with (
+ patch("openviking.utils.summarizer.get_queue_manager", return_value=qm),
+ patch(
+ "openviking.utils.summarizer.get_current_telemetry",
+ return_value=SimpleNamespace(telemetry_id="tid"),
+ ),
+ patch(
+ "openviking.utils.summarizer.get_request_wait_tracker",
+ return_value=wait_tracker,
+ ),
+ ):
+ with pytest.raises(RuntimeError, match="queue unavailable"):
+ await Summarizer(vlm_processor=None).refresh_file_parent(
+ file_uri="viking://resources/神雕.md",
+ ctx=ctx,
+ )
+
+ assert len(wait_tracker.registered) == 1
+ assert wait_tracker.failed == [
+ (*wait_tracker.registered[0], "queue unavailable"),
+ ]
diff --git a/tests/utils/test_resource_processor_processing_mode.py b/tests/utils/test_resource_processor_processing_mode.py
index 6c199a7cf..58a92bcd8 100644
--- a/tests/utils/test_resource_processor_processing_mode.py
+++ b/tests/utils/test_resource_processor_processing_mode.py
@@ -47,6 +47,145 @@ def ctx() -> RequestContext:
)
+async def test_flat_file_refreshes_parent_semantics_and_vectorizes_via_summary(
+ monkeypatch,
+ ctx,
+):
+ viking_fs = SimpleNamespace(
+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),
+ tree=AsyncMock(return_value=[]),
+ )
+ monkeypatch.setattr(
+ "openviking.utils.resource_processor.get_viking_fs",
+ lambda: viking_fs,
+ )
+ processor = ResourceProcessor(_FakeVikingDB())
+ summarizer = SimpleNamespace(
+ refresh_file_parent=AsyncMock(return_value={"status": "success"})
+ )
+ processor._get_summarizer = Mock(return_value=summarizer)
+
+ result = await processor.finish_prepared_resource(
+ {
+ "root_uri": "viking://resources/神雕_副本.md",
+ "temp_uri": "viking://resources/神雕_副本.md",
+ "source_committed": True,
+ "root_is_file": True,
+ },
+ ctx=ctx,
+ resource_lock={"lease_ref": "flat-file"},
+ build_index=True,
+ processing_mode="semantic_and_vectors",
+ )
+
+ assert result == {
+ "status": "success",
+ "root_uri": "viking://resources/神雕_副本.md",
+ }
+ summarizer.refresh_file_parent.assert_awaited_once_with(
+ file_uri="viking://resources/神雕_副本.md",
+ ctx=ctx,
+ skip_vectorization=False,
+ ingest_options=IngestOptions(),
+ )
+
+
+async def test_flat_file_skips_all_post_processing_when_build_index_false(
+ monkeypatch,
+ ctx,
+):
+ vectorize_file = AsyncMock()
+ monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", vectorize_file)
+ processor = ResourceProcessor(_FakeVikingDB())
+ processor._get_summarizer = Mock(
+ side_effect=AssertionError("flat files have no directory semantics")
+ )
+
+ await processor.finish_prepared_resource(
+ {
+ "root_uri": "viking://resources/神雕_副本.md",
+ "temp_uri": "viking://resources/神雕_副本.md",
+ "source_committed": True,
+ "root_is_file": True,
+ },
+ ctx=ctx,
+ build_index=False,
+ )
+
+ vectorize_file.assert_not_awaited()
+
+
+async def test_vectors_only_replaces_preexisting_flat_file_without_directory_sync(
+ monkeypatch,
+ ctx,
+):
+ viking_fs = SimpleNamespace(
+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),
+ exists=AsyncMock(return_value=True),
+ ls=AsyncMock(
+ side_effect=NotADirectoryError("flat resource roots cannot be listed")
+ ),
+ persist_temp_tree=AsyncMock(),
+ delete_temp=AsyncMock(),
+ )
+ vectorize_file = AsyncMock()
+ rewrite_image_uris = AsyncMock()
+ monkeypatch.setattr(
+ "openviking.utils.resource_processor.get_viking_fs",
+ lambda: viking_fs,
+ )
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.semantic_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("flat files have no directory semantics")
+ )
+ lock = {"lease_ref": "flat-file"}
+
+ result = await processor.finish_prepared_resource(
+ {
+ "root_uri": "viking://resources/神雕_副本.md",
+ "temp_uri": "viking://temp/神雕_副本.md",
+ "temp_dir_path": "viking://temp/job-1",
+ "source_committed": False,
+ "target_preexisting": True,
+ "root_is_file": True,
+ },
+ ctx=ctx,
+ resource_lock=lock,
+ build_index=True,
+ processing_mode="vectors_only",
+ )
+
+ assert result == {
+ "status": "success",
+ "root_uri": "viking://resources/神雕_副本.md",
+ }
+ viking_fs.persist_temp_tree.assert_awaited_once_with(
+ "viking://temp/神雕_副本.md",
+ "viking://resources/神雕_副本.md",
+ ctx=ctx,
+ lease_ref=lock,
+ )
+ viking_fs.delete_temp.assert_awaited_once_with("viking://temp/job-1", ctx=ctx)
+ rewrite_image_uris.assert_not_awaited()
+ vectorize_file.assert_awaited_once()
+ viking_fs._async_agfs.pathlock_release.assert_awaited_once_with(lock)
+
+
@pytest.mark.asyncio
async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch, ctx):
viking_fs = SimpleNamespace(