Skip to content

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

feat(resource): support Feishu/Lark URL imports via UnderstandingAPI (#3320)

ShaoZegangByte39dc01e2a55c
diff --git a/openviking/parse/image_rewrite.py b/openviking/parse/image_rewrite.py
index c971529e1..7dfe7d3f7 100644
--- a/openviking/parse/image_rewrite.py
+++ b/openviking/parse/image_rewrite.py
@@ -10,6 +10,7 @@ images themselves are stored next to the markdown file referencing them).
import json
import re
+from pathlib import Path
from typing import TYPE_CHECKING, Dict, Optional, Set
from openviking.server.identity import RequestContext
@@ -35,6 +36,67 @@ _FENCE_PATTERN = re.compile(r"^(\s{0,3})(`{3,}|~{3,})")
_LIST_ITEM_PATTERN = re.compile(r"^(\s{0,3})([-*+]|\d{1,9}[.)])(\s+)")
+def build_artifact_image_mappings(root_dir: Path) -> Dict[str, Dict[str, str]]:
+ """Build the sidecar mapping for an already-materialized parser artifact.
+
+ Understanding API artifacts already place each image next to the markdown
+ file that references it. Keep this helper deliberately narrower than
+ MarkdownParser's local-image ingestion: it records only existing sibling
+ files and never copies or renames artifact content.
+ """
+ root = root_dir.resolve()
+ mappings: Dict[str, Dict[str, str]] = {}
+
+ for md_path in root.rglob("*.md"):
+ if not md_path.is_file():
+ continue
+ try:
+ content = md_path.read_text(encoding="utf-8")
+ except (OSError, UnicodeError):
+ logger.warning(f"[image_rewrite] Failed to read artifact markdown: {md_path}")
+ continue
+
+ protected = _protected_ranges(content)
+
+ refs = [(match.start(), match.group(2)) for match in _IMAGE_PATTERN.finditer(content)]
+ refs.extend((match.start(), match.group(2)) for match in HTML_IMG_PATTERN.finditer(content))
+
+ file_mappings: Dict[str, str] = {}
+ md_dir = md_path.parent.resolve()
+ for pos, original_ref in refs:
+ if any(start <= pos < end for start, end in protected):
+ continue
+
+ ref = original_ref.strip()
+ if not ref or _is_remote_uri(ref):
+ continue
+
+ # Queries/fragments are not part of the local filesystem path, but
+ # the exact original reference remains the mapping key used later.
+ path_part = re.split(r"[?#]", ref, maxsplit=1)[0]
+ ref_path = Path(path_part)
+ if not path_part or ref_path.is_absolute():
+ continue
+
+ try:
+ candidate = (md_dir / ref_path).resolve()
+ candidate.relative_to(root)
+ except (OSError, ValueError):
+ continue
+
+ # The existing sidecar contract stores only the final filename and
+ # rewrite_image_uris resolves it beside the markdown file.
+ if candidate.parent != md_dir or not candidate.is_file():
+ continue
+
+ file_mappings[original_ref] = candidate.name
+
+ if file_mappings:
+ mappings[md_path.relative_to(root).as_posix()] = file_mappings
+
+ return mappings
+
+
def _is_remote_uri(path: str) -> bool:
return any(path.startswith(p) for p in _REMOTE_PREFIXES)
diff --git a/openviking/parse/parser_router.py b/openviking/parse/parser_router.py
index 4e1ccc064..0c2a4a3ae 100644
--- a/openviking/parse/parser_router.py
+++ b/openviking/parse/parser_router.py
@@ -45,13 +45,21 @@ class ParserRouter:
except Exception:
return False
- parser_api = getattr(ov_config, "parser_api", None)
- if not parser_api or not getattr(parser_api, "enable", False):
+ parser_api = ov_config.parser_api
+ if not parser_api.enable:
return False
+ if parser_api.enable_feishu_url:
+ try:
+ from openviking.parse.accessors.feishu_accessor import FeishuAccessor
+
+ if FeishuAccessor._is_feishu_url(str(source_path)):
+ return True
+ except Exception:
+ pass
+
ext = self._extract_extension(source_path)
- extensions = getattr(parser_api, "extensions", None) or []
- return ext in extensions
+ return ext in parser_api.extensions
def _extract_extension(self, source_path: Union[str, Path]) -> str:
source = str(source_path)
@@ -85,6 +93,11 @@ class ParserRouter:
logger.info(f"[ParserRouter] Using internal ParserRegistry for {display}")
return await self._parser_registry.parse(source_path, **kwargs)
+ async def submit_url(self, source: str, **kwargs) -> str:
+ if not self.should_use_understanding_api(source):
+ raise ValueError("source is not routed to UnderstandingAPI")
+ return await self._get_understanding_api().submit_url(source, **kwargs)
+
def _extract_source_path(self, source: Union[str, Path, "LocalResource"]) -> Union[str, Path]:
"""Extract a filesystem path from the source."""
if hasattr(source, "path"):
diff --git a/openviking/parse/understanding_api.py b/openviking/parse/understanding_api.py
index c0370d4ad..7831121d1 100644
--- a/openviking/parse/understanding_api.py
+++ b/openviking/parse/understanding_api.py
@@ -17,13 +17,17 @@ import json
import mimetypes
import tempfile
import zipfile
-from pathlib import Path
+from pathlib import Path, PurePosixPath
from typing import Any, Dict, List, Optional, Union
from urllib.parse import urlparse
import httpx
from openviking.parse.base import NodeType, ParseResult, ResourceNode
+from openviking.parse.image_rewrite import (
+ IMAGE_MAPPINGS_FILENAME,
+ build_artifact_image_mappings,
+)
from openviking.parse.parsers.base_parser import BaseParser
from openviking.parse.parsers.media.constants import (
AUDIO_EXTENSIONS,
@@ -31,11 +35,13 @@ from openviking.parse.parsers.media.constants import (
VIDEO_EXTENSIONS,
)
from openviking.storage.viking_fs import get_viking_fs
-from openviking.utils.zip_safe import safe_extract_zip
+from openviking.utils.zip_safe import normalize_zip_filenames, safe_extract_zip
from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
+PREPARED_RESPONSE_ID_ARG = "understanding_response_id"
+
class UnderstandingAPI(BaseParser):
"""
@@ -82,6 +88,21 @@ class UnderstandingAPI(BaseParser):
source_str = str(source)
original_source = kwargs.get("original_source")
candidate = original_source if isinstance(original_source, str) else source_str
+ explicit_name = kwargs.get("resource_name") or kwargs.get("source_name")
+ prepared_response_id = kwargs.get(PREPARED_RESPONSE_ID_ARG)
+ if prepared_response_id is not None:
+ if not isinstance(prepared_response_id, str) or not prepared_response_id.strip():
+ raise ValueError(f"{PREPARED_RESPONSE_ID_ARG} must be a non-empty string")
+ prepared_response_id = prepared_response_id.strip()
+ lark_file = self._normalize_lark_file(kwargs)
+ # Legacy accessor output may keep a Feishu URL in original_source while
+ # the actual parser input is a local Markdown file. Only direct URL
+ # routing may use the parser API Lark protocol.
+ is_feishu_url = self._is_feishu_url(source_str)
+ if is_feishu_url and not lark_file and not prepared_response_id:
+ raise ValueError(
+ "exactly one Feishu user or tenant access token is required for parser API imports"
+ )
url: Optional[str] = None
local_path: Optional[Path] = None
@@ -90,6 +111,12 @@ class UnderstandingAPI(BaseParser):
parsed = urlparse(url)
doc_name = Path(parsed.path).stem or "resource"
doc_type = Path(parsed.path).suffix.lower().lstrip(".") or "unknown"
+ if is_feishu_url:
+ path_parts = [part for part in parsed.path.split("/") if part]
+ doc_type = {
+ "sheets": "sheet",
+ "base": "bitable",
+ }.get(path_parts[0], path_parts[0])
else:
local_path = Path(candidate)
if not local_path.is_file():
@@ -100,9 +127,14 @@ class UnderstandingAPI(BaseParser):
doc_name = local_path.stem or "resource"
doc_type = local_path.suffix.lower().lstrip(".") or "unknown"
+ if explicit_name:
+ doc_name = Path(str(explicit_name)).name or doc_name
+
task_meta: Dict[str, Any] = {}
- if url is None and local_path is not None:
+ if prepared_response_id:
+ response_id = prepared_response_id
+ elif url is None and local_path is not None:
file_obj = await self._create_file(local_path=local_path)
file_id = file_obj.get("id")
if not file_id:
@@ -114,13 +146,19 @@ class UnderstandingAPI(BaseParser):
else:
if url is None:
raise RuntimeError("missing url for url mode")
- response_obj = await self._create_response_for_url(url=url, doc_type=doc_type)
-
- response_id = response_obj.get("id")
- if not response_id:
- raise RuntimeError(
- f"responses api missing id: {self._safe_error_summary(response_obj)}"
+ response_obj = await self._create_response_for_url(
+ url=url,
+ doc_type=doc_type,
+ lark_file=lark_file if is_feishu_url else None,
)
+
+ if not prepared_response_id:
+ response_id_value = response_obj.get("id")
+ if not response_id_value:
+ raise RuntimeError(
+ f"responses api missing id: {self._safe_error_summary(response_obj)}"
+ )
+ response_id = str(response_id_value)
task_meta["response_id"] = response_id
response_obj = await self._poll_response(response_id=response_id)
@@ -132,6 +170,10 @@ class UnderstandingAPI(BaseParser):
zip_path = await self._download_zip(zip_url)
try:
+ if is_feishu_url and not explicit_name:
+ archive_root = self._single_zip_root_name(zip_path)
+ if archive_root:
+ doc_name = archive_root
temp_dir_path = await self._unpack_zip_to_temp_dir(
zip_path=zip_path,
resource_name=doc_name,
@@ -160,7 +202,9 @@ class UnderstandingAPI(BaseParser):
meta={
"source_title": doc_name,
"semantic_name": doc_name,
- "original_filename": f"{doc_name}.{doc_type}" if doc_type else doc_name,
+ "original_filename": (
+ f"{doc_name}.{doc_type}" if doc_type and doc_type != "unknown" else doc_name
+ ),
},
content_type=content_type,
)
@@ -177,6 +221,39 @@ class UnderstandingAPI(BaseParser):
logger.info("[UnderstandingAPI] done")
return result
+ async def submit_url(self, source: str, **kwargs) -> str:
+ """Submit a URL without persisting its credentials in a queue payload."""
+ if not isinstance(source, str) or not source.startswith(("http://", "https://")):
+ raise ValueError("UnderstandingAPI URL submission requires an http(s) URL")
+
+ is_feishu_url = self._is_feishu_url(source)
+ lark_file = self._normalize_lark_file(kwargs)
+ if is_feishu_url and not lark_file:
+ raise ValueError(
+ "exactly one Feishu user or tenant access token is required for parser API imports"
+ )
+
+ parsed = urlparse(source)
+ doc_type = Path(parsed.path).suffix.lower().lstrip(".") or "unknown"
+ if is_feishu_url:
+ path_parts = [part for part in parsed.path.split("/") if part]
+ doc_type = {
+ "sheets": "sheet",
+ "base": "bitable",
+ }.get(path_parts[0], path_parts[0])
+
+ response_obj = await self._create_response_for_url(
+ url=source,
+ doc_type=doc_type,
+ lark_file=lark_file if is_feishu_url else None,
+ )
+ response_id = response_obj.get("id")
+ if not response_id:
+ raise RuntimeError(
+ f"responses api missing id: {self._safe_error_summary(response_obj)}"
+ )
+ return str(response_id)
+
async def parse_content(
self, content: str, source_path: Optional[str] = None, instruction: str = "", **kwargs
) -> ParseResult:
@@ -256,7 +333,13 @@ class UnderstandingAPI(BaseParser):
self._raise_if_error(body, context="responses api error")
return body
- async def _create_response_for_url(self, *, url: str, doc_type: str) -> Dict[str, Any]:
+ async def _create_response_for_url(
+ self,
+ *,
+ url: str,
+ doc_type: str,
+ lark_file: Optional[Dict[str, str]] = None,
+ ) -> Dict[str, Any]:
if doc_type in self._video_exts:
content: Dict[str, Any] = {"type": "input_video", "video_url": url}
elif doc_type in self._image_exts:
@@ -265,6 +348,8 @@ class UnderstandingAPI(BaseParser):
content = {"type": "input_audio", "audio_url": url}
else:
content = {"type": "input_file", "file_url": url}
+ if lark_file:
+ content["lark_file"] = dict(lark_file)
payload = {
"input": [{"role": "user", "content": [content]}],
"tools": [{"type": "understanding"}],
@@ -283,6 +368,53 @@ class UnderstandingAPI(BaseParser):
self._raise_if_error(body, context="responses api error")
return body
+ @staticmethod
+ def _is_feishu_url(source: str) -> bool:
+ try:
+ from openviking.parse.accessors.feishu_accessor import FeishuAccessor
+
+ return FeishuAccessor._is_feishu_url(source)
+ except Exception:
+ return False
+
+ @staticmethod
+ def _normalize_lark_file(kwargs: Dict[str, Any]) -> Optional[Dict[str, str]]:
+ raw_lark_file = kwargs.get("lark_file")
+ if raw_lark_file is None:
+ raw_lark_file = {"user_access_token": kwargs.get("feishu_access_token")}
+ if not isinstance(raw_lark_file, dict):
+ raise ValueError("lark_file must be an object")
+
+ auth = {}
+ for key in ("user_access_token", "tenant_access_token"):
+ value = raw_lark_file.get(key)
+ if isinstance(value, str) and value.strip():
+ auth[key] = value.strip()
+ if len(auth) > 1:
+ raise ValueError(
+ "lark_file must contain exactly one of user_access_token or tenant_access_token"
+ )
+ return auth or None
+
+ @staticmethod
+ def _single_zip_root_name(zip_path: Path) -> Optional[str]:
+ roots = set()
+ with zipfile.ZipFile(zip_path, "r") as zf:
+ normalize_zip_filenames(zf)
+ for info in zf.infolist():
+ raw_name = info.filename.rstrip("/")
+ if not raw_name:
+ continue
+ path = PurePosixPath(raw_name)
+ if path.is_absolute() or not path.parts or path.parts[0] in {".", ".."}:
+ return None
+ roots.add(path.parts[0])
+ if len(path.parts) == 1 and not info.is_dir():
+ return None
+ if len(roots) != 1:
+ return None
+ return next(iter(roots))
+
async def _poll_response(self, *, response_id: str) -> Dict[str, Any]:
deadline = asyncio.get_running_loop().time() + float(self._timeout_sec)
last_status = None
@@ -474,8 +606,10 @@ class UnderstandingAPI(BaseParser):
else:
root_dir = extract_path
+ image_mappings = await asyncio.to_thread(build_artifact_image_mappings, root_dir)
+
for child in root_dir.iterdir():
- if child.name in {".", ".."}:
+ if child.name in {".", "..", IMAGE_MAPPINGS_FILENAME}:
continue
if child.is_dir():
sub_uri = f"{temp_doc_uri}/{child.name}"
@@ -486,6 +620,12 @@ class UnderstandingAPI(BaseParser):
f"{temp_doc_uri}/{child.name}", child.read_bytes()
)
+ if image_mappings:
+ await viking_fs.write_file(
+ f"{temp_doc_uri}/{IMAGE_MAPPINGS_FILENAME}",
+ json.dumps(image_mappings, ensure_ascii=False),
+ )
+
return temp_uri
async def _copy_dir_to_fs(self, local_dir: Path, fs_uri: str):
@@ -495,7 +635,7 @@ class UnderstandingAPI(BaseParser):
viking_fs = get_viking_fs()
for item in local_dir.iterdir():
- if item.name in [".", ".."]:
+ if item.name in [".", "..", IMAGE_MAPPINGS_FILENAME]:
continue
if item.is_dir():
diff --git a/openviking/resource/feishu_watch_auth.py b/openviking/resource/feishu_watch_auth.py
index 071be63c1..1c72b7849 100644
--- a/openviking/resource/feishu_watch_auth.py
+++ b/openviking/resource/feishu_watch_auth.py
@@ -40,6 +40,10 @@ class FeishuTokenRefreshError(Exception):
self.permanent = permanent
+class FeishuTenantTokenError(Exception):
+ """Raised when an app credential cannot produce a tenant token."""
+
+
def load_feishu_app_credentials() -> FeishuAppCredentials:
"""Load Feishu app credentials from OpenViking config or environment."""
from openviking_cli.utils.config import get_openviking_config
@@ -113,7 +117,7 @@ def apply_feishu_refreshed_token(
class FeishuOAuthClient:
- """Small wrapper around lark-oapi user token refresh."""
+ """Small wrapper around lark-oapi user and tenant token operations."""
def __init__(self, credentials: FeishuAppCredentials):
self._credentials = credentials
@@ -123,6 +127,32 @@ class FeishuOAuthClient:
def from_config(cls) -> "FeishuOAuthClient":
return cls(load_feishu_app_credentials())
+ async def get_tenant_access_token(self) -> str:
+ return await asyncio.to_thread(self._get_tenant_access_token_sync)
+
+ def _get_tenant_access_token_sync(self) -> str:
+ try:
+ from lark_oapi.core.model import Config
+ from lark_oapi.core.token import TokenManager
+ except ImportError as exc:
+ raise FeishuTenantTokenError(
+ "lark-oapi is required to obtain a Feishu tenant token. "
+ "Install it with: pip install lark-oapi>=1.0.0"
+ ) from exc
+
+ config = Config()
+ config.app_id = self._credentials.app_id
+ config.app_secret = self._credentials.app_secret
+ config.domain = self._credentials.domain
+ config.timeout = self._credentials.request_timeout
+ try:
+ token = TokenManager.get_self_tenant_token(config)
+ except Exception as exc:
+ raise FeishuTenantTokenError("Failed to obtain Feishu tenant token.") from exc
+ if not isinstance(token, str) or not token.strip():
+ raise FeishuTenantTokenError("Feishu tenant token response is empty.")
+ return token.strip()
+
async def refresh_user_access_token(self, refresh_token: str) -> FeishuRefreshedToken:
if not isinstance(refresh_token, str) or not refresh_token.strip():
raise FeishuTokenRefreshError(
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index 44ec34c62..f961491a4 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -100,6 +100,7 @@ _ADD_RESOURCE_ARGS_RESERVED_FIELDS = frozenset(
"create_parent",
"telemetry",
"request_validator",
+ "understanding_response_id",
"defer_post_processing",
}
)
@@ -355,7 +356,7 @@ class ResourceService:
tracker = get_task_tracker()
task = await tracker.create(
"add_resource",
- resource_id=msg.root_uri,
+ resource_id=None if msg.defer_target_resolution else msg.root_uri,
account_id=msg.account_id,
user_id=msg.user_id,
task_id=msg.task_id,
@@ -379,10 +380,23 @@ class ResourceService:
"""Execute one durable add-resource job inside its QueueFS consumer."""
resource_lock = resource_lock or NO_LOCK
if msg.prepared is None:
+ target_uri = msg.root_uri
+ parent_uri = None
+ internal_kwargs: Dict[str, Any] = {}
+ if msg.defer_target_resolution:
+ from openviking_cli.utils.uri import VikingURI
+
+ target_uri = None
+ parent_uri = VikingURI(msg.root_uri).parent.uri
+ if msg.understanding_response_id is not None:
+ from openviking.parse.understanding_api import PREPARED_RESPONSE_ID_ARG
+
+ internal_kwargs[PREPARED_RESPONSE_ID_ARG] = msg.understanding_response_id
return await self.add_resource(
path=msg.path,
ctx=ctx,
- to=msg.root_uri,
+ to=target_uri,
+ parent=parent_uri,
reason=msg.reason,
instruction=msg.instruction,
wait=True,
@@ -404,6 +418,7 @@ class ResourceService:
preserve_structure=msg.preserve_structure,
create_parent=msg.create_parent,
args=msg.args,
+ **internal_kwargs,
)
telemetry_id = get_current_telemetry().telemetry_id
@@ -600,6 +615,15 @@ class ResourceService:
def _should_use_understanding_api(self, path: str) -> bool:
return self._get_parser_router().should_use_understanding_api(path)
+ @staticmethod
+ def _is_feishu_url(path: str) -> bool:
+ try:
+ from openviking.parse.accessors.feishu_accessor import FeishuAccessor
+
+ return FeishuAccessor._is_feishu_url(path)
+ except Exception:
+ return False
+
@staticmethod
def _target_doc_name(
path: str,
@@ -833,6 +857,12 @@ class ResourceService:
source_format=source_info.source_format,
create_parent=target.create_parent,
)
+ defer_target_resolution = bool(
+ candidate_uri
+ and not source_name
+ and not watch_enabled
+ and self._is_feishu_url(path)
+ )
if self._viking_fs is None:
raise NotInitializedError("VikingFS")
from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
@@ -855,44 +885,62 @@ class ResourceService:
retryable=True,
) from exc
- if candidate_uri:
+ if candidate_uri and not defer_target_resolution:
root_uri, lock_lease = await self._resource_processor.reserve_unique_candidate(
candidate_uri=candidate_uri,
ctx=ctx,
)
- else:
+ elif not defer_target_resolution:
lock_lease = await _reserve_tree(root_uri)
- lock_handoff = lock_lease.to_handoff()
- msg = AddResourceMsg(
- task_id=str(uuid4()),
- telemetry_id=telemetry_id or None,
- path=path,
- root_uri=root_uri,
- account_id=ctx.account_id,
- user_id=ctx.user.user_id,
- role=str(ctx.role),
- actor_peer_id=ctx.actor_peer_id,
- reason=reason,
- instruction=instruction,
- timeout=timeout,
- build_index=build_index,
- summarize=summarize,
- strict=bool(kwargs.get("strict", False)),
- ignore_dirs=kwargs.get("ignore_dirs"),
- include=kwargs.get("include"),
- exclude=kwargs.get("exclude"),
- directly_upload_media=bool(kwargs.get("directly_upload_media", True)),
- preserve_structure=kwargs.get("preserve_structure"),
- create_parent=bool(kwargs.get("create_parent", False)),
- allow_local_path_resolution=allow_local_path_resolution,
- enforce_public_remote_targets=enforce_public_remote_targets,
- args=self._sanitize_watch_processor_kwargs(normalized_args.processor_kwargs),
- source_name=source_name,
- lock_handoff=lock_handoff.to_dict() if lock_handoff else None,
- skip_watch_management=True,
- )
- task = await self._enqueue_add_resource_job(msg, resource_lock=lock_lease)
+ enqueue_started = False
+ try:
+ queued_args = dict(normalized_args.processor_kwargs)
+ feishu_access_token = queued_args.pop(FEISHU_ACCESS_TOKEN_ARG, None)
+ understanding_response_id = None
+ if self._is_feishu_url(path) and feishu_access_token:
+ understanding_response_id = await self._get_parser_router().submit_url(
+ path,
+ feishu_access_token=feishu_access_token,
+ )
+
+ lock_handoff = lock_lease.to_handoff()
+ msg = AddResourceMsg(
+ task_id=str(uuid4()),
+ telemetry_id=telemetry_id or None,
+ path=path,
+ root_uri=root_uri,
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ role=str(ctx.role),
+ actor_peer_id=ctx.actor_peer_id,
+ reason=reason,
+ instruction=instruction,
+ timeout=timeout,
+ build_index=build_index,
+ summarize=summarize,
+ strict=bool(kwargs.get("strict", False)),
+ ignore_dirs=kwargs.get("ignore_dirs"),
+ include=kwargs.get("include"),
+ exclude=kwargs.get("exclude"),
+ directly_upload_media=bool(kwargs.get("directly_upload_media", True)),
+ preserve_structure=kwargs.get("preserve_structure"),
+ create_parent=bool(kwargs.get("create_parent", False)),
+ allow_local_path_resolution=allow_local_path_resolution,
+ enforce_public_remote_targets=enforce_public_remote_targets,
+ args=self._sanitize_watch_processor_kwargs(queued_args),
+ source_name=source_name,
+ lock_handoff=lock_handoff.to_dict() if lock_handoff else None,
+ skip_watch_management=True,
+ defer_target_resolution=defer_target_resolution,
+ understanding_response_id=understanding_response_id,
+ )
+ enqueue_started = True
+ task = await self._enqueue_add_resource_job(msg, resource_lock=lock_lease)
+ except BaseException:
+ if not enqueue_started:
+ await lock_lease.close()
+ raise
lock_lease = NO_LOCK
job_enqueued = True
logger.info(
@@ -915,11 +963,13 @@ class ResourceService:
watch_auth_state=normalized_args.watch_auth_state,
ctx=ctx,
)
- return {
+ response = {
"status": "success",
- "root_uri": root_uri,
"task_id": task.task_id,
}
+ if not defer_target_resolution:
+ response["root_uri"] = root_uri
+ return response
result = await self._resource_processor.process_resource(
path=path,
diff --git a/openviking/service/task_tracker.py b/openviking/service/task_tracker.py
index 40e5b0a9f..07b0a94ea 100644
--- a/openviking/service/task_tracker.py
+++ b/openviking/service/task_tracker.py
@@ -368,6 +368,8 @@ class TaskTracker:
result: Optional[Dict[str, Any]] = None,
account_id: Optional[str] = None,
user_id: Optional[str] = None,
+ *,
+ resource_id: Optional[str] = None,
) -> None:
"""Transition task to COMPLETED with optional result."""
transitioned = False
@@ -377,6 +379,8 @@ class TaskTracker:
task.status = TaskStatus.COMPLETED
task.stage = "completed"
task.result = result
+ if resource_id is not None:
+ task.resource_id = resource_id
task.updated_at = time.time()
await self._store.update(task)
with self._lock:
diff --git a/openviking/storage/queuefs/add_resource_msg.py b/openviking/storage/queuefs/add_resource_msg.py
index 16dd5c624..a2416ba7e 100644
--- a/openviking/storage/queuefs/add_resource_msg.py
+++ b/openviking/storage/queuefs/add_resource_msg.py
@@ -37,6 +37,8 @@ class AddResourceMsg:
source_name: Optional[str] = None
watch_interval: float = 0
skip_watch_management: bool = True
+ defer_target_resolution: bool = False
+ understanding_response_id: Optional[str] = None
def to_dict(self) -> Dict[str, Any]:
data = asdict(self)
@@ -108,4 +110,10 @@ class AddResourceMsg:
prepared=prepared,
watch_interval=float(data.get("watch_interval", 0) or 0),
skip_watch_management=bool(data.get("skip_watch_management", True)),
+ defer_target_resolution=bool(data.get("defer_target_resolution", False)),
+ understanding_response_id=(
+ data.get("understanding_response_id")
+ if isinstance(data.get("understanding_response_id"), str)
+ else None
+ ),
)
diff --git a/openviking/storage/queuefs/add_resource_processor.py b/openviking/storage/queuefs/add_resource_processor.py
index d5e3ec6e5..f5ab2df82 100644
--- a/openviking/storage/queuefs/add_resource_processor.py
+++ b/openviking/storage/queuefs/add_resource_processor.py
@@ -78,7 +78,7 @@ class AddResourceProcessor(DequeueHandlerBase):
tracker = get_task_tracker()
task = await tracker.create(
"add_resource",
- resource_id=msg.root_uri,
+ resource_id=None if msg.defer_target_resolution else msg.root_uri,
account_id=ctx.account_id,
user_id=ctx.user.user_id,
task_id=msg.task_id,
@@ -158,6 +158,7 @@ class AddResourceProcessor(DequeueHandlerBase):
result,
account_id=ctx.account_id,
user_id=ctx.user.user_id,
+ resource_id=result.get("root_uri"),
)
self.report_success()
return None
diff --git a/openviking/utils/media_processor.py b/openviking/utils/media_processor.py
index ae13783c4..ab1785a76 100644
--- a/openviking/utils/media_processor.py
+++ b/openviking/utils/media_processor.py
@@ -140,6 +140,25 @@ class UnifiedResourceProcessor:
"direct host filesystem paths are not allowed."
)
+ if self._should_bypass_feishu_accessor(source, kwargs):
+ 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"] = {
+ "source_type": SourceType.FEISHU,
+ "original_url": source,
+ }
+ parse_kwargs["original_source"] = source
+ parse_kwargs.pop("feishu_access_token", None)
+ if not self._has_prepared_understanding_response(kwargs):
+ parse_kwargs["lark_file"] = await self._resolve_feishu_parser_auth(kwargs)
+
+ explicit_name = kwargs.get("resource_name") or kwargs.get("source_name")
+ if explicit_name:
+ parse_kwargs["resource_name"] = _smart_stem(explicit_name)
+ return await self._get_parser_router().parse(source, **parse_kwargs)
+
# Phase 1: Accessor - get local resource
registry = self._get_accessor_registry()
local_resource = await registry.access(source, **kwargs)
@@ -202,3 +221,49 @@ class UnifiedResourceProcessor:
def _is_url(self, source: str) -> bool:
"""Check if source is a URL."""
return is_remote_resource_source(source)
+
+ @staticmethod
+ def _is_feishu_url(source: str) -> bool:
+ """Backward-compatible Feishu URL detector used by legacy tests/callers."""
+ try:
+ from openviking.parse.accessors.feishu_accessor import FeishuAccessor
+
+ return FeishuAccessor._is_feishu_url(source)
+ except Exception:
+ return False
+
+ def _should_bypass_feishu_accessor(self, source: str, kwargs: dict) -> bool:
+ token = kwargs.get("feishu_access_token")
+ if not self._is_feishu_url(source):
+ return False
+ if not self._get_parser_router().should_use_understanding_api(source):
+ return False
+ if self._has_prepared_understanding_response(kwargs):
+ return True
+ if isinstance(token, str) and token.strip():
+ return True
+ try:
+ from openviking.resource.feishu_watch_auth import load_feishu_app_credentials
+
+ load_feishu_app_credentials()
+ return True
+ except ValueError:
+ return False
+
+ @staticmethod
+ def _has_prepared_understanding_response(kwargs: dict) -> bool:
+ from openviking.parse.understanding_api import PREPARED_RESPONSE_ID_ARG
+
+ value = kwargs.get(PREPARED_RESPONSE_ID_ARG)
+ return isinstance(value, str) and bool(value.strip())
+
+ @staticmethod
+ async def _resolve_feishu_parser_auth(kwargs: dict) -> dict[str, str]:
+ token = kwargs.get("feishu_access_token")
+ if isinstance(token, str) and token.strip():
+ return {"user_access_token": token.strip()}
+
+ from openviking.resource.feishu_watch_auth import FeishuOAuthClient
+
+ tenant_access_token = await FeishuOAuthClient.from_config().get_tenant_access_token()
+ return {"tenant_access_token": tenant_access_token}
diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.py
index d7c3fff34..dd6eabe6d 100644
--- a/openviking_cli/utils/config/open_viking_config.py
+++ b/openviking_cli/utils/config/open_viking_config.py
@@ -62,9 +62,7 @@ class ConnectorConfig(BaseModel):
tracker: str = ""
timeout_seconds: int = 3600
poll_interval_ms: int = 5000
- allowed_add_types: List[str] = Field(
- default_factory=lambda: ["tos"]
- )
+ allowed_add_types: List[str] = Field(default_factory=lambda: ["tos"])
model_config = {"extra": "forbid"}
@@ -93,6 +91,7 @@ class ParserApiConfig(BaseModel):
extensions: List[str] = Field(default_factory=list)
host: str = ""
api_key: str = ""
+ enable_feishu_url: bool = False
enable_resumable_upload: bool = False
upload_simple_max_bytes: int = 512 * 1024 * 1024
upload_part_size_bytes: int = 8 * 1024 * 1024
diff --git a/tests/parse/test_feishu_parser_api.py b/tests/parse/test_feishu_parser_api.py
new file mode 100644
index 000000000..fda71cc91
--- /dev/null
+++ b/tests/parse/test_feishu_parser_api.py
@@ -0,0 +1,685 @@
+import asyncio
+import json
+import zipfile
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from openviking.parse.understanding_api import PREPARED_RESPONSE_ID_ARG, UnderstandingAPI
+from openviking.server.identity import RequestContext, Role
+from openviking.service.resource_service import ResourceService
+from openviking.service.task_tracker import TaskStatus
+from openviking.storage.queuefs.add_resource_msg import AddResourceMsg
+from openviking.storage.queuefs.add_resource_processor import AddResourceProcessor
+from openviking.utils.media_processor import UnifiedResourceProcessor
+from openviking_cli.exceptions import InvalidArgumentError
+from openviking_cli.session.user_id import UserIdentifier
+
+
+async def test_feishu_parser_api_bypasses_accessor():
+ result = object()
+ router = SimpleNamespace(
+ should_use_understanding_api=lambda source: True,
+ parse=AsyncMock(return_value=result),
+ )
+ processor = UnifiedResourceProcessor(vlm_processor=object())
+ processor._parser_router = router
+ processor._accessor_registry = SimpleNamespace(
+ access=AsyncMock(side_effect=AssertionError("accessor should not be called"))
+ )
+ source = "https://example.larkoffice.com/docx/doxcnToken"
+
+ actual = await processor.process(source, feishu_access_token=" u-test ")
+
+ assert actual is result
+ router.parse.assert_awaited_once()
+ (call_source,) = router.parse.await_args.args
+ assert call_source == source
+ assert router.parse.await_args.kwargs["lark_file"] == {"user_access_token": "u-test"}
+ assert "resource_name" not in router.parse.await_args.kwargs
+
+
+async def test_feishu_parser_api_uses_app_credentials_for_tenant_token(monkeypatch):
+ result = object()
+ router = SimpleNamespace(
+ should_use_understanding_api=lambda source: True,
+ parse=AsyncMock(return_value=result),
+ )
+ oauth_client = SimpleNamespace(get_tenant_access_token=AsyncMock(return_value="t-test"))
+ processor = UnifiedResourceProcessor(vlm_processor=object())
+ processor._parser_router = router
+ processor._accessor_registry = SimpleNamespace(
+ access=AsyncMock(side_effect=AssertionError("accessor should not be called"))
+ )
+ monkeypatch.setattr(
+ "openviking.resource.feishu_watch_auth.load_feishu_app_credentials",
+ Mock(return_value=object()),
+ )
+ monkeypatch.setattr(
+ "openviking.resource.feishu_watch_auth.FeishuOAuthClient.from_config",
+ Mock(return_value=oauth_client),
+ )
+
+ actual = await processor.process("https://example.larkoffice.com/docx/doxcnToken")
+
+ assert actual is result
+ assert router.parse.await_args.kwargs["lark_file"] == {"tenant_access_token": "t-test"}
+ oauth_client.get_tenant_access_token.assert_awaited_once_with()
+
+
+async def test_prepared_feishu_response_bypasses_accessor_without_credentials(monkeypatch):
+ result = object()
+ router = SimpleNamespace(
+ should_use_understanding_api=lambda source: True,
+ parse=AsyncMock(return_value=result),
+ )
+ processor = UnifiedResourceProcessor(vlm_processor=object())
+ processor._parser_router = router
+ processor._accessor_registry = SimpleNamespace(
+ access=AsyncMock(side_effect=AssertionError("accessor should not be called"))
+ )
+ monkeypatch.setattr(
+ "openviking.resource.feishu_watch_auth.load_feishu_app_credentials",
+ Mock(side_effect=ValueError("missing credentials")),
+ )
+
+ actual = await processor.process(
+ "https://example.larkoffice.com/docx/doxcnToken",
+ **{PREPARED_RESPONSE_ID_ARG: "response-1"},
+ )
+
+ assert actual is result
+ assert router.parse.await_args.kwargs[PREPARED_RESPONSE_ID_ARG] == "response-1"
+ assert "lark_file" not in router.parse.await_args.kwargs
+
+
+def _understanding_api_for_parse() -> UnderstandingAPI:
+ api = UnderstandingAPI.__new__(UnderstandingAPI)
+ api._video_exts = {"mp4"}
+ api._audio_exts = {"mp3"}
+ api._image_exts = {"png"}
+ return api
+
+
+def test_single_zip_root_name_repairs_utf8_name_without_flag(tmp_path: Path):
+ zip_path = tmp_path / "result.zip"
+ member_name = "真实文档标题/0.md"
+ placeholder = "x" * len(member_name.encode("utf-8"))
+ with zipfile.ZipFile(zip_path, "w") as zf:
+ zf.writestr(placeholder, "content")
+
+ archive = zip_path.read_bytes()
+ placeholder_bytes = placeholder.encode("ascii")
+ assert archive.count(placeholder_bytes) == 2
+ zip_path.write_bytes(archive.replace(placeholder_bytes, member_name.encode("utf-8")))
+
+ assert UnderstandingAPI._single_zip_root_name(zip_path) == "真实文档标题"
+
+
+async def test_feishu_parse_sends_uat_and_uses_artifact_root(tmp_path: Path):
+ zip_path = tmp_path / "result.zip"
+ with zipfile.ZipFile(zip_path, "w") as zf:
+ zf.writestr("真实文档标题/0.md", "content")
+
+ api = _understanding_api_for_parse()
+ api._create_response_for_url = AsyncMock(return_value={"id": "response-1"})
+ api._poll_response = AsyncMock(
+ return_value={"status": "completed", "result": {"zip_url": "https://tos/result.zip"}}
+ )
+ api._download_zip = AsyncMock(return_value=zip_path)
+ api._unpack_zip_to_temp_dir = AsyncMock(return_value="viking://temp/result")
+
+ result = await api.parse(
+ "https://example.larkoffice.com/wiki/wikicnToken",
+ feishu_access_token="u-test",
+ )
+
+ api._create_response_for_url.assert_awaited_once_with(
+ url="https://example.larkoffice.com/wiki/wikicnToken",
+ doc_type="wiki",
+ lark_file={"user_access_token": "u-test"},
+ )
+ api._unpack_zip_to_temp_dir.assert_awaited_once_with(
+ zip_path=zip_path,
+ resource_name="真实文档标题",
+ )
+ assert result.root.title == "真实文档标题"
+ assert result.meta == {"response_id": "response-1"}
+ assert "u-test" not in repr(result.meta)
+
+
+async def test_feishu_parse_resumes_prepared_response_without_lark_auth(tmp_path: Path):
+ zip_path = tmp_path / "result.zip"
+ with zipfile.ZipFile(zip_path, "w") as zf:
+ zf.writestr("真实文档标题/0.md", "content")
+
+ api = _understanding_api_for_parse()
+ api._create_response_for_url = AsyncMock(
+ side_effect=AssertionError("prepared response must not be submitted again")
+ )
+ api._poll_response = AsyncMock(
+ return_value={"status": "completed", "result": {"zip_url": "https://tos/result.zip"}}
+ )
+ api._download_zip = AsyncMock(return_value=zip_path)
+ api._unpack_zip_to_temp_dir = AsyncMock(return_value="viking://temp/result")
+
+ result = await api.parse(
+ "https://example.larkoffice.com/docx/doxcnToken",
+ **{PREPARED_RESPONSE_ID_ARG: "response-1"},
+ )
+
+ api._poll_response.assert_awaited_once_with(response_id="response-1")
+ assert result.root.title == "真实文档标题"
+ assert result.meta == {"response_id": "response-1"}
+
+
+async def test_feishu_parse_keeps_explicit_resource_name(tmp_path: Path):
+ zip_path = tmp_path / "result.zip"
+ with zipfile.ZipFile(zip_path, "w") as zf:
+ zf.writestr("真实文档标题/0.md", "content")
+
+ api = _understanding_api_for_parse()
+ api._create_response_for_url = AsyncMock(return_value={"id": "response-1"})
+ api._poll_response = AsyncMock(
+ return_value={"status": "completed", "result": {"zip_url": "https://tos/result.zip"}}
+ )
+ api._download_zip = AsyncMock(return_value=zip_path)
+ api._unpack_zip_to_temp_dir = AsyncMock(return_value="viking://temp/result")
+
+ result = await api.parse(
+ "https://example.larkoffice.com/docx/doxcnToken",
+ resource_name="用户名称",
+ feishu_access_token="u-test",
+ )
+
+ api._unpack_zip_to_temp_dir.assert_awaited_once_with(
+ zip_path=zip_path,
+ resource_name="用户名称",
+ )
+ assert result.root.title == "用户名称"
+
+
+async def test_legacy_accessor_output_does_not_enable_lark_protocol(tmp_path: Path):
+ markdown_path = tmp_path / "document.md"
+ markdown_path.write_text("content", encoding="utf-8")
+ zip_path = tmp_path / "result.zip"
+ with zipfile.ZipFile(zip_path, "w") as zf:
+ zf.writestr("parsed/0.md", "content")
+
+ api = _understanding_api_for_parse()
+ api._create_response_for_url = AsyncMock(return_value={"id": "response-1"})
+ api._poll_response = AsyncMock(
+ return_value={"status": "completed", "result": {"zip_url": "https://tos/result.zip"}}
+ )
+ api._download_zip = AsyncMock(return_value=zip_path)
+ api._unpack_zip_to_temp_dir = AsyncMock(return_value="viking://temp/result")
+
+ await api.parse(
+ markdown_path,
+ original_source="https://example.larkoffice.com/docx/doxcnToken",
+ feishu_access_token="u-test",
+ )
+
+ api._create_response_for_url.assert_awaited_once_with(
+ url="https://example.larkoffice.com/docx/doxcnToken",
+ doc_type="unknown",
+ lark_file=None,
+ )
+
+
+async def test_feishu_parse_requires_lark_auth():
+ api = _understanding_api_for_parse()
+
+ with pytest.raises(ValueError, match="user or tenant access token is required"):
+ await api.parse("https://example.larkoffice.com/docx/doxcnToken")
+
+
+async def test_create_response_payload_contains_lark_file(monkeypatch):
+ seen = {}
+
+ class FakeResponse:
+ def raise_for_status(self):
+ return None
+
+ def json(self):
+ return {"id": "response-1"}
+
+ class FakeClient:
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb):
+ return None
+
+ async def post(self, url, *, content, headers):
+ seen["url"] = url
+ seen["payload"] = json.loads(content)
+ seen["headers"] = headers
+ return FakeResponse()
+
+ monkeypatch.setattr(
+ "openviking.parse.understanding_api.httpx.AsyncClient",
+ lambda **kwargs: FakeClient(),
+ )
+ api = _understanding_api_for_parse()
+ api._api_base = "https://parser.example/api/v3"
+ api._api_key = "parser-key"
+ api._http_timeout_sec = 10
+
+ result = await api._create_response_for_url(
+ url="https://example.larkoffice.com/base/bascnToken?table=tblToken",
+ doc_type="bitable",
+ lark_file={"user_access_token": "u-test"},
+ )
+
+ assert result == {"id": "response-1"}
+ assert seen["payload"]["input"][0]["content"] == [
+ {
+ "type": "input_file",
+ "file_url": "https://example.larkoffice.com/base/bascnToken?table=tblToken",
+ "lark_file": {"user_access_token": "u-test"},
+ }
+ ]
+
+
+async def test_submit_url_returns_response_id_without_persisting_auth():
+ api = _understanding_api_for_parse()
+ api._create_response_for_url = AsyncMock(return_value={"id": "response-1"})
+
+ response_id = await api.submit_url(
+ "https://example.larkoffice.com/docx/doxcnToken",
+ feishu_access_token="u-test",
+ )
+
+ assert response_id == "response-1"
+ api._create_response_for_url.assert_awaited_once_with(
+ url="https://example.larkoffice.com/docx/doxcnToken",
+ doc_type="docx",
+ lark_file={"user_access_token": "u-test"},
+ )
+
+
+def test_add_resource_message_round_trips_internal_fields():
+ msg = AddResourceMsg(
+ task_id="task-1",
+ path="https://example.larkoffice.com/docx/doxcnToken",
+ root_uri="viking://resources/doxcnToken",
+ account_id="account-1",
+ user_id="user-1",
+ role="user",
+ defer_target_resolution=True,
+ understanding_response_id="response-1",
+ )
+
+ restored = AddResourceMsg.from_dict(msg.to_dict())
+
+ assert restored.args == {}
+ assert "feishu_access_token" not in json.dumps(restored.to_dict())
+ assert restored.defer_target_resolution is True
+ assert restored.understanding_response_id == "response-1"
+
+
+async def test_uat_producer_payload_reaches_worker_without_persisting_token(monkeypatch):
+ source = "https://example.larkoffice.com/docx/doxcnToken"
+ root_uri = "viking://resources/lark/doxcnToken"
+ parser_router = SimpleNamespace(
+ should_use_understanding_api=lambda _source: True,
+ submit_url=AsyncMock(return_value="response-1"),
+ )
+ resource_processor = SimpleNamespace(
+ tree_builder=SimpleNamespace(
+ resolve_target_uri=AsyncMock(return_value=(root_uri, root_uri))
+ ),
+ process_resource=AsyncMock(
+ return_value={
+ "status": "success",
+ "root_uri": "viking://resources/lark/真实文档标题",
+ }
+ ),
+ )
+ task_tracker = SimpleNamespace(
+ create=AsyncMock(return_value=SimpleNamespace(task_id="task-1")),
+ start=AsyncMock(),
+ update_stage=AsyncMock(),
+ complete=AsyncMock(),
+ fail=AsyncMock(),
+ )
+ queue_manager = SimpleNamespace(enqueue=AsyncMock())
+ monkeypatch.setattr(
+ "openviking.service.task_tracker.get_task_tracker",
+ Mock(return_value=task_tracker),
+ )
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.get_queue_manager",
+ Mock(return_value=queue_manager),
+ )
+ monkeypatch.setattr(
+ "openviking.storage.transaction.get_lock_manager",
+ Mock(return_value=SimpleNamespace()),
+ )
+
+ service = ResourceService(
+ viking_fs=SimpleNamespace(),
+ resource_processor=resource_processor,
+ skill_processor=SimpleNamespace(),
+ )
+ service._parser_router = parser_router
+ monkeypatch.setattr("openviking.service.resource_service.uuid4", Mock(return_value="task-1"))
+ monkeypatch.setattr(service, "_is_feishu_url", Mock(return_value=True))
+ ctx = RequestContext(
+ user=UserIdentifier("account-1", "user-1"),
+ role=Role.USER,
+ )
+
+ initial_result = await service.add_resource(
+ path=source,
+ ctx=ctx,
+ parent="viking://resources/lark",
+ wait=False,
+ allow_local_path_resolution=False,
+ args={"feishu_access_token": "u-secret", "custom_option": "forwarded"},
+ )
+
+ assert initial_result == {"status": "success", "task_id": "task-1"}
+ assert task_tracker.create.await_args.kwargs["resource_id"] is None
+ parser_router.submit_url.assert_awaited_once_with(
+ source,
+ feishu_access_token="u-secret",
+ )
+ payload = queue_manager.enqueue.await_args.args[1]
+ assert "u-secret" not in json.dumps(payload)
+ assert payload["understanding_response_id"] == "response-1"
+ assert payload["args"] == {"custom_option": "forwarded"}
+
+ queued_msg = AddResourceMsg.from_dict(payload)
+ service.add_resource = AsyncMock(
+ return_value={
+ "status": "success",
+ "root_uri": "viking://resources/lark/真实文档标题",
+ }
+ )
+ await service.execute_add_resource_job(
+ queued_msg,
+ ctx=ctx,
+ resource_lock=None,
+ stage_callback=AsyncMock(),
+ )
+
+ call = service.add_resource.await_args
+ assert call.kwargs[PREPARED_RESPONSE_ID_ARG] == "response-1"
+ assert call.kwargs["args"] == {"custom_option": "forwarded"}
+
+
[email protected]("cancel_stage", ["submit", "enqueue", "handoff"])
+async def test_uat_producer_cancellation_respects_queue_ownership(
+ monkeypatch,
+ cancel_stage,
+):
+ source = "https://example.larkoffice.com/docx/doxcnToken"
+ root_uri = "viking://resources/fixed"
+ submit_url = AsyncMock(return_value="response-1")
+ enqueue = AsyncMock()
+ handoff = AsyncMock()
+ if cancel_stage == "submit":
+ submit_url.side_effect = asyncio.CancelledError
+ elif cancel_stage == "enqueue":
+ enqueue.side_effect = asyncio.CancelledError
+ else:
+ handoff.side_effect = asyncio.CancelledError
+
+ parser_router = SimpleNamespace(
+ should_use_understanding_api=lambda _source: True,
+ submit_url=submit_url,
+ )
+ resource_processor = SimpleNamespace(
+ tree_builder=SimpleNamespace(
+ resolve_target_uri=AsyncMock(return_value=(root_uri, None))
+ ),
+ )
+ task_tracker = SimpleNamespace(
+ create=AsyncMock(return_value=SimpleNamespace(task_id="task-1")),
+ update_stage=AsyncMock(),
+ fail=AsyncMock(),
+ )
+ queue_manager = SimpleNamespace(enqueue=enqueue)
+ lock_lease = SimpleNamespace(
+ to_handoff=Mock(
+ return_value=SimpleNamespace(
+ to_dict=Mock(
+ return_value={
+ "handle_id": "lock-1",
+ "lock_paths": ["/resources/fixed"],
+ }
+ )
+ )
+ ),
+ handoff=handoff,
+ close=AsyncMock(),
+ )
+ monkeypatch.setattr(
+ "openviking.service.task_tracker.get_task_tracker",
+ Mock(return_value=task_tracker),
+ )
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.get_queue_manager",
+ Mock(return_value=queue_manager),
+ )
+ monkeypatch.setattr(
+ "openviking.storage.transaction.get_lock_manager",
+ Mock(return_value=SimpleNamespace()),
+ )
+ monkeypatch.setattr(
+ "openviking.storage.transaction.OwnedLockLease.acquire_tree",
+ AsyncMock(return_value=lock_lease),
+ )
+
+ service = ResourceService(
+ viking_fs=SimpleNamespace(_uri_to_path=lambda _uri, ctx: "/resources/fixed"),
+ resource_processor=resource_processor,
+ skill_processor=SimpleNamespace(),
+ )
+ service._parser_router = parser_router
+ monkeypatch.setattr(service, "_is_feishu_url", Mock(return_value=True))
+ ctx = RequestContext(
+ user=UserIdentifier("account-1", "user-1"),
+ role=Role.USER,
+ )
+
+ with pytest.raises(asyncio.CancelledError):
+ await service.add_resource(
+ path=source,
+ ctx=ctx,
+ to=root_uri,
+ wait=False,
+ allow_local_path_resolution=False,
+ args={"feishu_access_token": "u-secret"},
+ )
+
+ lock_lease.close.assert_awaited_once_with()
+ task_tracker.create.assert_not_awaited()
+ task_tracker.fail.assert_not_awaited()
+ if cancel_stage == "submit":
+ enqueue.assert_not_awaited()
+ else:
+ enqueue.assert_awaited_once()
+
+
+def test_prepared_response_id_is_reserved_from_public_args():
+ service = ResourceService()
+
+ with pytest.raises(InvalidArgumentError, match=PREPARED_RESPONSE_ID_ARG):
+ service._normalize_add_resource_args(
+ {PREPARED_RESPONSE_ID_ARG: "response-1"},
+ watch_interval=0,
+ )
+
+
+async def test_add_resource_job_defers_target_and_expands_prepared_response():
+ service = ResourceService()
+ service.add_resource = AsyncMock(
+ return_value={
+ "status": "success",
+ "root_uri": "viking://resources/真实文档标题",
+ }
+ )
+ msg = AddResourceMsg(
+ task_id="task-1",
+ path="https://example.larkoffice.com/docx/doxcnToken",
+ root_uri="viking://resources/lark/doxcnToken",
+ account_id="account-1",
+ user_id="user-1",
+ role="user",
+ defer_target_resolution=True,
+ understanding_response_id="response-1",
+ )
+ ctx = RequestContext(
+ user=UserIdentifier("account-1", "user-1"),
+ role=Role.USER,
+ )
+
+ result = await service.execute_add_resource_job(
+ msg,
+ ctx=ctx,
+ resource_lock=None,
+ stage_callback=AsyncMock(),
+ )
+
+ call = service.add_resource.await_args
+ assert call.kwargs["to"] is None
+ assert call.kwargs["parent"] == "viking://resources/lark"
+ assert call.kwargs[PREPARED_RESPONSE_ID_ARG] == "response-1"
+ assert call.kwargs["args"] == {}
+ assert result["root_uri"] == "viking://resources/真实文档标题"
+
+
+async def test_add_resource_job_expands_parser_args():
+ service = ResourceService()
+ service.add_resource = AsyncMock(
+ return_value={
+ "status": "success",
+ "root_uri": "viking://resources/doxcnToken",
+ }
+ )
+ msg = AddResourceMsg(
+ task_id="task-1",
+ path="https://example.larkoffice.com/docx/doxcnToken",
+ root_uri="viking://resources/doxcnToken",
+ account_id="account-1",
+ user_id="user-1",
+ role="user",
+ args={"custom_option": "forwarded"},
+ )
+ ctx = RequestContext(
+ user=UserIdentifier("account-1", "user-1"),
+ role=Role.USER,
+ )
+
+ await service.execute_add_resource_job(
+ msg,
+ ctx=ctx,
+ resource_lock=None,
+ stage_callback=AsyncMock(),
+ )
+
+ call = service.add_resource.await_args
+ assert call.kwargs["to"] == "viking://resources/doxcnToken"
+ assert call.kwargs["parent"] is None
+ assert call.kwargs["args"] == {"custom_option": "forwarded"}
+
+
+async def test_add_resource_processor_persists_final_resource_uri(monkeypatch):
+ final_uri = "viking://resources/真实文档标题"
+ service = SimpleNamespace(
+ execute_add_resource_job=AsyncMock(
+ return_value={"status": "success", "root_uri": final_uri}
+ )
+ )
+ task_tracker = SimpleNamespace(
+ create=AsyncMock(return_value=SimpleNamespace(status=TaskStatus.PENDING)),
+ start=AsyncMock(),
+ update_stage=AsyncMock(),
+ complete=AsyncMock(),
+ fail=AsyncMock(),
+ )
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.add_resource_processor.get_task_tracker",
+ Mock(return_value=task_tracker),
+ )
+ processor = AddResourceProcessor(service, asyncio.get_running_loop())
+ msg = AddResourceMsg(
+ task_id="task-1",
+ path="https://example.larkoffice.com/docx/doxcnToken",
+ root_uri="viking://resources/lark/doxcnToken",
+ account_id="account-1",
+ user_id="user-1",
+ role="user",
+ defer_target_resolution=True,
+ understanding_response_id="response-1",
+ )
+
+ await processor._process(msg, msg.to_dict())
+
+ task_tracker.create.assert_awaited_once_with(
+ "add_resource",
+ resource_id=None,
+ account_id="account-1",
+ user_id="user-1",
+ task_id="task-1",
+ )
+ task_tracker.complete.assert_awaited_once_with(
+ "task-1",
+ {"status": "success", "root_uri": final_uri},
+ account_id="account-1",
+ user_id="user-1",
+ resource_id=final_uri,
+ )
+
+
+def test_feishu_bypass_requires_configured_auth(monkeypatch):
+ router = SimpleNamespace(
+ should_use_understanding_api=lambda source: True,
+ )
+ processor = UnifiedResourceProcessor(vlm_processor=object())
+ processor._parser_router = router
+ monkeypatch.setattr(
+ "openviking.resource.feishu_watch_auth.load_feishu_app_credentials",
+ Mock(side_effect=ValueError("missing credentials")),
+ )
+
+ assert not processor._should_bypass_feishu_accessor(
+ "https://example.larkoffice.com/docx/doxcnToken",
+ {},
+ )
+
+
+def test_normalize_lark_file_accepts_exactly_one_token():
+ assert UnderstandingAPI._normalize_lark_file(
+ {"lark_file": {"tenant_access_token": " t-test "}}
+ ) == {"tenant_access_token": "t-test"}
+
+ with pytest.raises(ValueError, match="exactly one"):
+ UnderstandingAPI._normalize_lark_file(
+ {
+ "lark_file": {
+ "user_access_token": "u-test",
+ "tenant_access_token": "t-test",
+ }
+ }
+ )
diff --git a/tests/parse/test_parser_router.py b/tests/parse/test_parser_router.py
index 03a48b7e6..6d289b063 100644
--- a/tests/parse/test_parser_router.py
+++ b/tests/parse/test_parser_router.py
@@ -5,7 +5,11 @@ from openviking.parse.parser_router import ParserRouter
def test_should_use_understanding_api_for_signed_video_url(monkeypatch):
config = SimpleNamespace(
- parser_api=SimpleNamespace(enable=True, extensions=["mp4"]),
+ parser_api=SimpleNamespace(
+ enable=True,
+ enable_feishu_url=False,
+ extensions=["mp4"],
+ ),
)
monkeypatch.setattr(
"openviking_cli.utils.config.open_viking_config.get_openviking_config",
@@ -17,3 +21,42 @@ def test_should_use_understanding_api_for_signed_video_url(monkeypatch):
assert router.should_use_understanding_api(
"https://example.com/media/video.mp4?X-Tos-Signature=abc&X-Tos-Expires=60"
)
+
+
+def test_should_use_understanding_api_for_feishu_url(monkeypatch):
+ config = SimpleNamespace(
+ parser_api=SimpleNamespace(
+ enable=True,
+ enable_feishu_url=True,
+ extensions=[],
+ ),
+ )
+ monkeypatch.setattr(
+ "openviking_cli.utils.config.open_viking_config.get_openviking_config",
+ lambda: config,
+ )
+
+ router = ParserRouter(parser_registry=object())
+
+ assert router.should_use_understanding_api("https://example.larkoffice.com/wiki/wikicnToken")
+ assert not router.should_use_understanding_api(
+ "https://larkoffice.com.evil.example/wiki/wikicnToken"
+ )
+
+
+def test_feishu_url_flag_defaults_to_extension_routing(monkeypatch):
+ config = SimpleNamespace(
+ parser_api=SimpleNamespace(
+ enable=True,
+ enable_feishu_url=False,
+ extensions=[],
+ ),
+ )
+ monkeypatch.setattr(
+ "openviking_cli.utils.config.open_viking_config.get_openviking_config",
+ lambda: config,
+ )
+
+ router = ParserRouter(parser_registry=object())
+
+ assert not router.should_use_understanding_api("https://example.larkoffice.com/docx/doxcnToken")
diff --git a/tests/parse/test_understanding_api_artifact_images.py b/tests/parse/test_understanding_api_artifact_images.py
new file mode 100644
index 000000000..e4db58118
--- /dev/null
+++ b/tests/parse/test_understanding_api_artifact_images.py
@@ -0,0 +1,82 @@
+import json
+import zipfile
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from openviking.parse.image_rewrite import (
+ IMAGE_MAPPINGS_FILENAME,
+ build_artifact_image_mappings,
+)
+from openviking.parse.understanding_api import UnderstandingAPI
+
+
+class _FakeVikingFS:
+ def __init__(self):
+ self.files = {}
+ self.dirs = set()
+
+ def create_temp_uri(self):
+ return "viking://temp/artifact"
+
+ async def mkdir(self, uri, exist_ok=False):
+ self.dirs.add(uri)
+
+ async def write_file_bytes(self, uri, content):
+ self.files[uri] = content
+
+ async def write_file(self, uri, content):
+ self.files[uri] = content.encode("utf-8")
+
+
+def test_build_artifact_image_mappings_uses_existing_sibling_images(tmp_path: Path):
+ chapter = tmp_path / "章节"
+ chapter.mkdir()
+ (chapter / "正文_img1.png").write_bytes(b"png")
+ (chapter / "正文_img2.jpg").write_bytes(b"jpg")
+ (chapter / "正文.md").write_text(
+ "\n".join(
+ [
+ "![image](正文_img1.png)",
+ '<img src="./正文_img2.jpg">',
+ "![remote](https://example.com/a.png)",
+ "![missing](missing.png)",
+ "```markdown",
+ "![example](正文_img1.png)",
+ "```",
+ ]
+ ),
+ encoding="utf-8",
+ )
+
+ assert build_artifact_image_mappings(tmp_path) == {
+ "章节/正文.md": {
+ "正文_img1.png": "正文_img1.png",
+ "./正文_img2.jpg": "正文_img2.jpg",
+ }
+ }
+
+
+async def test_unpack_artifact_writes_image_mapping_sidecar(tmp_path: Path):
+ zip_path = tmp_path / "artifact.zip"
+ with zipfile.ZipFile(zip_path, "w") as archive:
+ archive.writestr("artifact/Ov测试_1.md", "![image](Ov测试_1_img1.png)\n")
+ archive.writestr("artifact/Ov测试_1_img1.png", b"png")
+ archive.writestr(
+ f"artifact/{IMAGE_MAPPINGS_FILENAME}",
+ '{"untrusted.md":{"bad.png":"bad.png"}}',
+ )
+
+ fake_fs = _FakeVikingFS()
+ api = UnderstandingAPI.__new__(UnderstandingAPI)
+ with patch("openviking.parse.understanding_api.get_viking_fs", return_value=fake_fs):
+ temp_uri = await api._unpack_zip_to_temp_dir(zip_path, "resource")
+
+ assert temp_uri == "viking://temp/artifact"
+ sidecar_uri = f"{temp_uri}/resource/{IMAGE_MAPPINGS_FILENAME}"
+ assert json.loads(fake_fs.files[sidecar_uri]) == {
+ "Ov测试_1.md": {"Ov测试_1_img1.png": "Ov测试_1_img1.png"}
+ }
+ assert fake_fs.files[f"{temp_uri}/resource/Ov测试_1_img1.png"] == b"png"
diff --git a/tests/resource/test_feishu_watch_auth.py b/tests/resource/test_feishu_watch_auth.py
index b2ac45352..2f993b0af 100644
--- a/tests/resource/test_feishu_watch_auth.py
+++ b/tests/resource/test_feishu_watch_auth.py
@@ -5,6 +5,8 @@
from datetime import datetime, timedelta, timezone
from openviking.resource.feishu_watch_auth import (
+ FeishuAppCredentials,
+ FeishuOAuthClient,
FeishuRefreshedToken,
apply_feishu_refreshed_token,
create_feishu_auth_state,
@@ -33,3 +35,30 @@ def test_feishu_auth_state_refresh_window():
"expires_at": (now + timedelta(minutes=4)).isoformat(),
}
assert feishu_auth_state_needs_refresh(near_expiry, now=now) is True
+
+
+def test_get_tenant_access_token_uses_configured_app(monkeypatch):
+ seen = {}
+
+ def fake_get_token(config):
+ seen["config"] = config
+ return " t-test "
+
+ monkeypatch.setattr(
+ "lark_oapi.core.token.TokenManager.get_self_tenant_token",
+ fake_get_token,
+ )
+ client = FeishuOAuthClient(
+ FeishuAppCredentials(
+ app_id="cli-test",
+ app_secret="secret-test",
+ domain="https://open.feishu.cn",
+ request_timeout=12,
+ )
+ )
+
+ assert client._get_tenant_access_token_sync() == "t-test"
+ assert seen["config"].app_id == "cli-test"
+ assert seen["config"].app_secret == "secret-test"
+ assert seen["config"].domain == "https://open.feishu.cn"
+ assert seen["config"].timeout == 12
diff --git a/tests/test_task_tracker.py b/tests/test_task_tracker.py
index a8ddf5eb4..485c2dbfe 100644
--- a/tests/test_task_tracker.py
+++ b/tests/test_task_tracker.py
@@ -151,6 +151,21 @@ async def test_complete_task(tracker: TaskTracker):
assert retrieved.result == {"memories_extracted": 3}
+async def test_complete_task_updates_resource_id(tracker: TaskTracker):
+ task = await tracker.create("add_resource", resource_id=None, **_owner_kwargs())
+
+ await tracker.complete(
+ task.task_id,
+ {"root_uri": "viking://resources/real-title"},
+ resource_id="viking://resources/real-title",
+ )
+
+ retrieved = await tracker.get(task.task_id)
+ assert retrieved is not None
+ assert retrieved.resource_id == "viking://resources/real-title"
+ assert await tracker.list_tasks(resource_id="viking://resources/real-title") == [retrieved]
+
+
async def test_task_result_redacts_user_key(tracker: TaskTracker):
task = await tracker.create("legacy_migration", **_owner_kwargs())
await tracker.complete(