Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs(api): review API reference pages against the implementation (#5506)
Zayn Jarvis60a19ed02eb4
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.mdindex c756dc281..3ade32142 100644--- a/docs/en/api/01-overview.md+++ b/docs/en/api/01-overview.md@@ -96,20 +96,18 @@ It uses the same identity headers and response envelope as the Python and GoHTTP clients. See [`sdk/typescript/README.md`](../../../sdk/typescript/README.md)for package-level examples.-When `url` is not explicitly provided, the HTTP client automatically reads connection information from `ovcli.conf`. `ovcli.conf` is a configuration file shared between the HTTP client and CLI. Default path: `~/.openviking/ovcli.conf`. You can also specify the path via environment variable:+The Python HTTP client reads connection information from `ovcli.conf`; explicit constructor values override the corresponding settings. `ovcli.conf` is a configuration file shared between the HTTP client and CLI. Default path: `~/.openviking/ovcli.conf`. You can also specify the path via environment variable:```bashexport OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf```-Configuration file example:+Configuration file example using a user/admin key:```json{"url": "http://localhost:1933",- "api_key": "your-key",- "account": "acme",- "user": "alice"+ "api_key": "your-user-or-admin-key"}```@@ -119,8 +117,8 @@ Configuration field description:|-------|-------------|---------|| `url` | Server address | (required) || `api_key` | API Key | `null` (no auth) |-| `account` | Default account header for tenant-scoped requests | `null` |-| `user` | Default user header for tenant-scoped requests | `null` |+| `account` | Account header; used in trusted and dev modes, ignored in api_key mode | `null` |+| `user` | User header; used in trusted and dev modes, ignored in api_key mode | `null` || `timeout` | HTTP request timeout in seconds | `60.0` || `output` | Default output format: `"table"` or `"json"` | `"table"` |@@ -166,7 +164,7 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \#### CLI Mode-The OpenViking CLI command is `ov` (installed with `npm install -g @openviking/cli`). It connects to an OpenViking server and exposes all operations as shell commands. The CLI also reads connection information from `ovcli.conf` (shared with the HTTP client).+The OpenViking CLI command is `ov` (installed with `npm install -g @openviking/cli`). It connects to an OpenViking server and provides shell commands for common operations. The CLI also reads connection information from `ovcli.conf` (shared with the HTTP client).Basic usage:@@ -214,12 +212,12 @@ See the [Authentication Guide](../guides/04-authentication.md) for full details.- **Authorization Bearer** header: `Authorization: Bearer your-key` (recommended)- **X-API-Key** header: `X-API-Key: your-key`-- If the server doesn't have an API Key configured, authentication is skipped.+- Authentication is skipped only in dev mode, which is selected automatically when `server.root_api_key` is unset and `auth_mode` is not set. Other modes (api_key, trusted, OIDC, LDAP) resolve identity according to their configuration.- The `/health` and `/ready` endpoints never require authentication.## Response Format-All HTTP API responses follow a unified format:+Regular JSON API responses use the following envelope. File downloads, SSE, Metrics, and WebDAV use the formats documented for those endpoints:### Success Response@@ -305,8 +303,8 @@ JSON output - error:### Special Cases-- **String results** (`read`, `abstract`, `overview`): printed directly as plain text-- **None results** (`mkdir`, `rm`, `mv`): no output+- In table mode, `read`, `abstract`, and `overview` print text directly. `mkdir`, `rm`, and `mv` print a confirmation message.+- In JSON mode, these commands use the JSON output format described above.### Exit Codes@@ -357,7 +355,7 @@ This catalog follows the routes actually mounted by the server. Each group headi| Method | Path | Description ||--------|------|-------------|| GET | `/health` | Basic health check (no authentication) |-| GET | `/ready` | AGFS, VectorDB, and API key manager readiness (no authentication) |+| GET | `/ready` | AGFS, VectorDB, API key manager, and embedding readiness (no authentication) || GET | `/api/v1/system/status` | System status || POST | `/api/v1/system/wait` | Wait for background processing || POST | `/api/v1/system/consistency` | Check filesystem and vector-index consistency |@@ -401,7 +399,7 @@ This catalog follows the routes actually mounted by the server. Each group headi| GET | `/api/v1/content/overview` | Read an overview (L1) || GET | `/api/v1/content/download` | Download original file bytes || POST | `/api/v1/content/write` | Write content and refresh semantic indexes |-| POST | `/api/v1/content/batch-write` | Apply preconditioned multi-file writes |+| POST | `/api/v1/content/batch-write` | Write multiple files and refresh their indexes || POST | `/api/v1/content/set_tags` | Set retrieval tags || POST | `/api/v1/content/reindex` | Rebuild semantic or vector indexes |@@ -559,9 +557,9 @@ This catalog follows the routes actually mounted by the server. Each group headi----## Documentation Reading Plan+## Find an API by Task-The sidebar is organized by responsibility rather than historical file size:+Choose a reference page by operation type:| Group | What to look for ||-------|------------------|diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.mdindex 2ea8f0044..6017b382f 100644--- a/docs/en/api/02-resources.md+++ b/docs/en/api/02-resources.md@@ -1,6 +1,6 @@# Resource Management-Resources are external knowledge that agents can reference. This module provides functionality for adding, importing/exporting, and uploading temporary files for resources.+Resources are external knowledge that agents can reference. This page covers resource import, scheduled updates, and temporary uploads. For package export and import, see [OVPack](14-ovpack.md).## Core Concepts@@ -49,7 +49,7 @@ Audio/video parsers validate and store the original files. Content understanding| Type | Description ||------|-------------|-| Feishu/Lark | URL-based, supports doc/docx, wiki, sheets, bitable, and mindnote/mindnotes. By default uses app credentials from FEISHU_APP_ID and FEISHU_APP_SECRET; user-token imports can pass `args.feishu_access_token`, and user-token watches also pass `args.feishu_refresh_token` plus an optional `args.feishu_app_id` / `args.feishu_app_secret` pair. Mindnote and wiki-wrapped Mindnote require `mindnote:node:read` on the token used for import |+| Feishu/Lark | URL-based, supports doc/docx, wiki, sheets, bitable, mindnote/mindnotes, Drive files, and directory collections. Wiki imports include only the entry document by default; set `args.feishu_recursive=true` to include child nodes. By default uses app credentials from FEISHU_APP_ID and FEISHU_APP_SECRET; user-token imports can pass `args.feishu_access_token`, and user-token watches also pass `args.feishu_refresh_token` plus an optional `args.feishu_app_id` / `args.feishu_app_secret` pair. Mindnote and wiki-wrapped Mindnote require `mindnote:node:read` on the token used for import |**Web Pages (recursive web crawler)**@@ -63,11 +63,11 @@ Audio/video parsers validate and store the original files. Content understanding| Type | Resource Name | Description ||------|---------------|-------------|-| Sitemap | `https://host/sitemap.xml`, `https://host/sitemap-index.xml` | Parses the sitemap and ingests every listed page as a single resource tree (one child node per page). Nested `<sitemapindex>` is followed recursively. The whole site becomes one resource under `viking://resources/<host>`. |+| Sitemap | `https://host/sitemap.xml`, `https://host/sitemap-index.xml` | Parses the sitemap and ingests listed pages within the configured limits as a single resource tree (one child node per page). Nested `<sitemapindex>` is followed recursively. The whole site becomes one resource under `viking://resources/<host>`. || RSS / Atom feed | `https://host/rss.xml`, `https://host/atom.xml`, `https://host/feed` | Parses RSS 2.0 / Atom and ingests each entry as a tree node; the article body is fetched from its link (or taken inline when the feed carries full content). || Whole-site auto-discovery | `https://host` + `args.site=true` | Forces whole-site ingestion for a bare domain or ordinary page: discovers the site's sitemap/RSS via robots.txt, HTML `<link rel="alternate">` autodiscovery, and conventional paths, then ingests it. |-Crawling is bounded and non-recursive beyond the listed pages, and is governed by the `parsers.webfeed` config (`max_pages`, `max_concurrency`, `politeness_delay`, `same_host_only`, `respect_robots`, `max_depth`); robots.txt is honored. Set `watch_interval` on a sitemap/feed URL to keep the **whole site** refreshed: on each run new pages are added and removed pages drop automatically. When adding a single homepage (without `args.site`), the response may append a one-line hint suggesting whole-site ingestion — it never auto-crawls.+Crawling is bounded and non-recursive beyond the listed pages, and is governed by the `parsers.webfeed` config (`max_pages`, `max_concurrency`, `politeness_delay`, `same_host_only`, `respect_robots`, `max_depth`); robots.txt is honored when `respect_robots=true` (the default). Set `watch_interval` on a sitemap/feed URL to keep the listed pages refreshed: on each run new pages are added and removed pages drop automatically. When adding a single homepage (without `args.site`), the response may append a one-line hint suggesting whole-site ingestion — it never auto-crawls.### Resource Processing Pipeline@@ -83,7 +83,7 @@ Source Input -> Parse -> Resource Tree Build -> Persistence -> Semantic Processi- Uses `UnifiedResourceProcessor` to parse content based on resource type- Supports multiple formats: documents (PDF/Markdown/Word), spreadsheets (Excel/PPT), code, media files, etc.- Parsed results are written to a temporary VikingFS directory-- Media files have descriptions generated via VLM (Vision Language Model)+- Media parsers validate and store original files; VLM descriptions are generated later during semantic processing when the corresponding configuration is enabled#### Stage 2: Resource Tree Build (TreeBuilder)- `TreeBuilder.finalize_from_temp()` scans the temporary directory structure@@ -116,7 +116,7 @@ Resource incremental updates are implemented via the **Watch Task** mechanism:- Set `watch_interval > 0` (in minutes) when calling `add_resource` with a re-readable source, such as a URL, sitemap, or RSS feed, to create a watch task- Uploaded content referenced by `temp_file_id` is a static snapshot and cannot be watched. The Python HTTP SDK also uploads local files/directories as snapshots, so do not combine a local path with `watch_interval > 0`; re-add it when the local source changes- You may specify `to` to define the target URI; if omitted, the task binds to the `root_uri` returned by this import-- Pointing a watch at a sitemap/RSS/Atom URL keeps the **whole site** in sync: each refresh re-reads the feed and rebuilds the tree, so newly published pages are added and removed pages drop automatically+- Pointing a watch at a sitemap/RSS/Atom URL keeps the listed pages in sync: each refresh re-reads the feed and rebuilds the tree, so newly published pages are added and removed pages drop automatically- `WatchManager` handles task persistence- Supports multi-tenant permission control (ROOT/ADMIN/USER permission levels)@@ -127,9 +127,9 @@ Resource incremental updates are implemented via the **Watch Task** mechanism:- Connector Watches are created before the initial import and held by the scheduler until that import records its result.#### Task Scheduling & Execution-- `WatchScheduler` checks for expired tasks every 60 seconds+- `WatchScheduler` checks for due tasks every 60 seconds- Default concurrency control prevents duplicate execution-- Expired tasks automatically re-invoke `add_resource`+- Due tasks automatically re-invoke `add_resource`- Updates task's last execution time and next execution time#### Task Management Operations@@ -175,6 +175,8 @@ This endpoint is the core entry point for resource management. It supports vario| to | string | No | - | Final location for this import. If the target already exists, it is refreshed. Mutually exclusive with `parent` || parent | string | No | - | Parent Viking URI (resource placed under this directory). Mutually exclusive with `to` || create_parent | bool | No | False | Automatically create parent directory if it does not exist (server-side flag) |+| add_type | string | No | None | Explicit connector type; requires `path` and exact `to`, and cannot be combined with `parent` or `temp_file_id` |+| source_name | string | No | None | Source display name; uploaded files use their original filename when omitted || reason | string | No | "" | Reason for adding the resource. When non-empty, OpenViking runs it through the normal session memory extraction pipeline with the resource URI and records resource references in the resulting memory || instruction | string | No | "" | Processing instructions for semantic extraction (experimental feature) || wait | bool | No | False | Whether to wait for semantic processing and vectorization to complete before returning |@@ -185,7 +187,7 @@ This endpoint is the core entry point for resource management. It supports vario| 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. Native HTTPS Git imports and watches accept HTTP Basic credentials over TLS as `args.auth_config={"username":"oauth2","token":"..."}`; `username` defaults to `oauth2`. Git `branch` or `commit` remains at the top level of `args`. To import a private TOS object through its HTTP(S) URL, pass exactly one non-empty string: `args.tos_signature` (sent as `X-Tos-Signature`) or `args.tos_access` (sent as `X-Tos-Access`). TOS credentials are used only for the current HEAD/GET fetch, which is staged as a snapshot; they are not persisted to resource metadata or queue jobs. `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` |+| args | object | No | `{}` | Parser/accessor options; see the source-specific notes below. Core request fields remain outside `args`, except Connector-owned options described below. || watch_interval | float | No | 0 | Scheduled update interval (minutes). >0 creates a new Watch for a re-readable source, subject to target ownership rules; uploaded `temp_file_id` snapshots cannot be watched. <=0 creates no Watch: native imports with explicit `to` pause a single accessible task (409 if ambiguous), while Connector imports leave Watches untouched. Explicit `to` wins, otherwise the Watch binds to the imported `root_uri`. || is_active | bool | No | True | Initial Watch scheduling state. `false` requires `watch_interval > 0` and either `to` or `parent`. `parent` is supported for native Feishu URL and Git imports; Connector imports still require an exact `to`. The initial import still runs once and the Watch remains paused afterward || 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 |@@ -194,10 +196,19 @@ This endpoint is the core entry point for resource management. It supports vario| acl | object | No | None | Direct ACL for the final import root; requires manage. Omission preserves existing permissions. See [ACL API](12-acl.md). || telemetry | TelemetryRequest | No | False | Whether to return telemetry data |+**Source-specific `args`**++- Native HTTPS Git imports and watches accept HTTP Basic credentials over TLS as `args.auth_config={"username":"oauth2","token":"..."}`; `username` defaults to `oauth2`. Git `branch` or `commit` remains at the top level of `args`.+- To import a private TOS object through its HTTP(S) URL, pass exactly one non-empty string: `args.tos_signature` (sent as `X-Tos-Signature`) or `args.tos_access` (sent as `X-Tos-Access`). TOS credentials are used only for the current HEAD/GET fetch, which is staged as a snapshot; they are not persisted to resource metadata or queue jobs.+- `args.parse_mode` accepts `default` (existing splitting behavior) or `no_split` (parse and convert each source document to one Markdown body).+- `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`, and `include` are not allowed inside `args`. Native imports also reject `args.exclude`; TOS Connector imports accept it with `args.tos_prefix`.+**Additional Notes**:- `to` and `parent` cannot be specified together. `to` is the final save location: a missing target is created, and an existing target is refreshed. If the target is a directory, old files or subdirectories that are not produced by the current import may be removed. `parent` is the destination directory, and is the right option for adding a new resource under an existing directory; use `create_parent=true` or CLI `--parent-auto-create` when that directory should be created automatically. When the imported `root_uri` is the same as `to`, semantic and vector processing reuse unchanged content and process only the changed parts.- Creating a resource requires write access to its target parent; updating an existing explicit `to` requires write access to that target. These checks run before the task is queued. Automatic naming uses actual URI occupancy, so an unreadable collision selects `_1`, `_2`, and so on instead of attempting an overwrite.-- With `wait=false`, `status=accepted` means that preflight passed and the task was queued; it does not mean resource processing has completed. Use the returned `task_id` for the final status.+- With `wait=false`, native imports return `status=success` after queue submission; Connector imports return `status=accepted`. Neither means background processing has completed. Use the returned `task_id` for the final status.- If both `to` and `parent` are omitted, the server may use the current user's `add_targets.resource_uri` override, then `server.user_config_defaults.add_targets.resource_uri`. If neither is set, legacy target resolution is unchanged.- Resource targets may use public `viking://resources/...`, the home alias `viking://~/resources/...`, explicit user `viking://user/{user_id}/resources/...`, or peer `viking://user/{user_id}/peers/{peer_id}/resources/...` paths. The home alias is expanded to the canonical path using the authenticated request identity; the uid-less spelling `viking://user/resources/...` is rejected with an error pointing at `viking://~/resources/...`.- `user_id` and `peer_id` path segments must be safe single-segment identifiers, for example `alice` or `web-visitor-alice`. Values with path separators, `.`, `..`, `:`, or `+` are rejected.@@ -281,7 +292,7 @@ curl -X POST http://localhost:1933/api/v1/resources \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \-d '{- "path": "https://docs.openviking.ai/getting-started/01-introduction",+ "path": "https://docs.openviking.ai/en/getting-started/01-introduction","args": { "depth": 1, "max_pages": 10 }}'@@ -312,6 +323,17 @@ curl -X POST http://localhost:1933/api/v1/resources \\"create_parent\": true}"+# Add retrieval tags with the generated vector records for search/find filters+curl -X POST http://localhost:1933/api/v1/resources \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d "{+ \"temp_file_id\": \"$TEMP_FILE_ID\",+ \"to\": \"viking://resources/tagged-guide.md\",+ \"tags\": [\"team=search\", \"env=test\"],+ \"tag_mode\": \"replace\"+ }"+# Add a Feishu document with a one-time user access tokencurl -X POST http://localhost:1933/api/v1/resources \-H "Content-Type: application/json" \@@ -381,7 +403,7 @@ result = client.add_resource(# Recursively crawl a site (same-host BFS; depth levels, max_pages cap)result = client.add_resource(- path="https://docs.openviking.ai/getting-started/01-introduction",+ path="https://docs.openviking.ai/en/getting-started/01-introduction",options={"args": {"depth": 1, "max_pages": 10},},@@ -394,7 +416,7 @@ result = client.add_resource("args": {"depth": 2,"max_pages": 50,- "include_paths": ["/docs/"],+ "include_paths": ["/en/"],"exclude_paths": ["/changelog"],"skip_download_links": False,},@@ -486,12 +508,12 @@ ov add-resource ./documents --args parse_mode:no_splitov add-resource https://example.com/guide.md --to viking://resources/guide.md# Recursively crawl a site: only the entry page is fetched unless depth>0-ov add-resource "https://docs.openviking.ai/getting-started/01-introduction" \+ov add-resource "https://docs.openviking.ai/en/getting-started/01-introduction" \--args="depth:1,max_pages:10"-# Recursive crawl with path-prefix filters (only /docs/, exclude changelog)+# Recursive crawl with path-prefix filters (only /en/, exclude changelog)ov add-resource "https://docs.openviking.ai/" \- --args='{"depth":2,"max_pages":50,"include_paths":["/docs/"],"exclude_paths":["/changelog"]}'+ --args='{"depth":2,"max_pages":50,"include_paths":["/en/"],"exclude_paths":["/changelog"]}'# Download links on pages are skipped by default; opt in to fetch PDF/TXT/MD etc.ov add-resource "https://example.com/docs" \@@ -501,7 +523,7 @@ ov add-resource "https://example.com/docs" \ov task status TASK_ID# Enable scheduled updates (check every 60 minutes)-ov add-resource https://github.com/example/repo.git --to viking://resources/guide.md --watch-interval 60+ov add-resource https://github.com/example/repo.git --to viking://resources/my_repo --watch-interval 60# Enable scheduled updates and bind to the URI created by this importov add-resource https://github.com/example/repo.git --watch-interval 60@@ -549,7 +571,7 @@ ov add-resource ./documents/guide.md -p viking://resources/docs/{calendar:today}{"status": "ok","result": {- "status": "accepted",+ "status": "success","root_uri": "viking://resources/guide","task_id": "uuid-xxx"}@@ -563,7 +585,7 @@ Use the returned `task_id` to poll `/api/v1/tasks/{task_id}` for queue completio```Note: Resource is being processed in the background.Use 'ov task status <task_id>' to check progress, or 'ov task list' to see all tasks.-status accepted+status successroot_uri viking://resources/01-overviewtask_id uuid-xxx```@@ -572,9 +594,12 @@ task_id uuid-xxx```json{- "status": "accepted",- "root_uri": "viking://resources/01-overview",- "task_id": "uuid-xxx"+ "ok": true,+ "result": {+ "status": "success",+ "root_uri": "viking://resources/01-overview",+ "task_id": "uuid-xxx"+ }}```@@ -582,15 +607,16 @@ task_id uuid-xxx| Field | Type | Description ||-------|------|-------------|-| `status` | string | Processing status: `accepted` means queued, `success` means completed successfully, and `error` means failed. |+| `status` | string | Native imports return `success` for both queued and synchronous results; Connector submissions return `accepted`. With `wait=false`, poll `task_id` to confirm completion. Request failures use the top-level error envelope; background failures appear in the Task API. || `root_uri` | string | Final URI of the resource in OpenViking || `task_id` | string | (Optional, only when `wait=false`) Task ID for polling `/api/v1/tasks/{task_id}`. Non-Git imports use it for queue tracking; Git repository imports use it for full background import tracking. || `temp_uri` | string | Temporary URI produced during import || `source_path` | string | Original source file path or URL || `meta` | object | Metadata from resource parsing (file type, size, etc.) || `errors` | array | List of errors encountered during processing |-| `warnings` | array | (Optional) List of warnings (only when `strict=False`) |-| `queue_status` | object | (Optional, only when `wait=true`) Queue processing status with `pending`, `processing`, `completed` counts |+| `warnings` | array | Optional warnings, including partial processing or memory-linking failures |+| `queue_status` | object | Queue summary when waiting synchronously or reading a completed task result; grouped by queue with `processed`, `requeue_count`, `error_count`, and `errors` |+| `memory_linking` | object | Optional result of linking the resource URI to memories generated from `reason` |**Completed add-resource task result**diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.mdindex 01aab58c2..7af3faa1b 100644--- a/docs/en/api/03-filesystem.md+++ b/docs/en/api/03-filesystem.md@@ -4,6 +4,8 @@ OpenViking provides Unix-like file system operations for managing context.<a id="webdav"></a><a id="webdav-phase-1"></a>+For reading and writing file contents, see [Content](12-content.md). [WebDAV](20-webdav.md) provides file access through WebDAV clients.+## API Reference<a id="abstract"></a><a id="overview"></a><a id="read"></a><a id="write"></a>@@ -31,6 +33,7 @@ List directory contents.| sort_by | str | No | None | Sort directories and files within their groups by `name` or `mtime` before pagination; directories remain first || sort_order | str | No | `asc` | Sort direction: `asc` or `desc` || extra_fields | list[str] | No | None | Extra fields to include: `locked`, `id`, `count` |+| include_tags | bool | No | False | Return tags without requiring a tag filter || tags | string[] | No | Unset | Return only entries matching every supplied `k=v` retrieval tag |`tags` uses AND semantics and is applied before `offset` and `limit`. L0/L1 content is attached only to the selected page of directory entries and does not consume `node_limit`. An explicit `include_abstract=true|false` overrides the legacy behavior implied by `output`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).@@ -154,7 +157,7 @@ ov glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=search,envThe HTTP `result` remains an entry array. `has_more=true` means more matching nodes remain after visibility, tags, offset, and limit are applied. The Python, TypeScript, and Go SDKs continue to return the `result` array. When more nodes are available, the CLI appends a pagination hint to its output.-**Response**+**Response (`output=original`)**```json{@@ -196,6 +199,7 @@ Get directory tree structure.| limit | int | No | None | Alias for `node_limit` || level_limit | int | No | 3 | Maximum directory depth to traverse || extra_fields | list[str] | No | None | Extra fields to include: `locked`, `id`, `count` |+| include_tags | bool | No | False | Return tags without requiring a tag filter || tags | string[] | No | Unset | Retain only nodes matching every supplied `k=v` retrieval tag |Directory filtering and `tags` are applied before `offset` and `limit`. Abstracts and overviews are attached to the selected directory nodes and do not count toward `node_limit`. Explicit `include_abstract=true|false` overrides the legacy behavior implied by `output`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).@@ -272,7 +276,7 @@ ov tree viking://resources/my-project/ \As with `ls`, the HTTP `result` remains a node array and `has_more` is returned at the top level. When `has_more=true`, the CLI appends a pagination hint to the tree output.-**Response**+**Response (`output=original`)**```json{@@ -395,7 +399,7 @@ ov stat viking://resources/my-project/docs}```-The `isLocked` field reports whether the path is currently held by a path lock: the path itself has a valid lock (including an exact-path lock for the target), or any ancestor directory holds a TreeLock. Returns `false` when the LockManager is unavailable or the lookup fails, so callers can avoid attempting a write only to observe `ResourceBusyError`.+The `isLocked` field reports whether the path is currently held by a path lock: the path itself has a valid lock (including an exact-path lock for the target), or any ancestor directory holds a TreeLock. It returns `false` when the LockManager is unavailable or the lookup fails. This is an advisory check, not a lock reservation: another writer may acquire a lock after the check, so writes must still handle `ResourceBusyError`.The `id` field (files only) is the deterministic vector record primary key in VikingDB, computed as `md5(f"{account_id}:{uri}")` for level 2 (regular file) records. This value matches the `id` field in the vector collection schema and can be used to cross-reference vector records without an additional lookup. The field is omitted for directories because a directory may have multiple vector records across semantic levels (L0 abstract, L1 overview). Because indexing is asynchronous, a newly returned ID might not be resolvable immediately; lookup by ID can also fail after its vector record is deleted. In either case, `stat(id)` returns `NOT_FOUND` with a reason indicating that the data may not have been indexed yet or may have been deleted.@@ -466,7 +470,7 @@ ov attrs set-tags viking://resources/docs/api.md --tags team=search,env=prodov attrs set-tags viking://resources/docs --tags team=search --mode append --recursive```-Directory targets update the directory semantic records; `recursive=true` also updates existing descendant files and directory semantic records.+For `set-tags`, directory targets update the directory semantic records; `recursive=true` also updates existing descendant files and directory semantic records.**Response (Resource)**@@ -584,13 +588,15 @@ ov mkdir viking://resources/new-project/ --description "API docs directory"Remove file or directory. When removing directories recursively, returns the estimated number of items deleted.`rm` is idempotent: removing a valid URI that does not exist still succeeds.-Invalid URI formats, unsupported schemes, and non-public scopes return `INVALID_URI`.+Invalid URI formats, unsupported schemes, and internal scopes such as `temp` or `queue` return `INVALID_URI`.**Parameters**| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI to remove |+| wait | bool | No | False | Wait for the semantic refresh after deletion |+| timeout | float | No | None | Refresh timeout in seconds when `wait=true` || recursive | bool | No | False | Remove directory recursively |diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.mdindex e4762272e..4955ece42 100644--- a/docs/en/api/04-skills.md+++ b/docs/en/api/04-skills.md@@ -161,7 +161,7 @@ Add a skill to the knowledge base.#### 1. API Implementation Overview-Skills are a special type of resource that define actions or tools agents can perform.+This endpoint stores Skill instructions and supporting files, then generates summaries and indexes for retrieval. It does not execute the Skill or register tools.**Processing Flow**:1. Receive skill data or uploaded temporary file@@ -411,7 +411,7 @@ ov skills add ./skills/code-runner/ -p viking://agent/skills --waitov task status TASK_ID# Use JSON output format-ov add-skill ./skills/my-skill/ -o json+ov -o json add-skill ./skills/my-skill/```**Response Examples**@@ -446,12 +446,15 @@ task_id uuid-xxx**CLI response (JSON format, using -o json)**:```json{- "status": "success",- "root_uri": "viking://user/alice/skills/my-skill",- "uri": "viking://user/alice/skills/my-skill",- "name": "my-skill",- "auxiliary_files": 2,- "task_id": "uuid-xxx"+ "ok": true,+ "result": {+ "status": "success",+ "root_uri": "viking://user/alice/skills/my-skill",+ "uri": "viking://user/alice/skills/my-skill",+ "name": "my-skill",+ "auxiliary_files": 2,+ "task_id": "uuid-xxx"+ }}```@@ -517,7 +520,10 @@ console.log(await client.listSkills());```goskills, err := client.ListSkills(ctx, nil)-_ = skills+if err != nil {+ return err+}+fmt.Println(skills)```**HTTP API**@@ -567,7 +573,10 @@ skill, err := client.GetSkill(ctx, "search-web", &openviking.GetSkillOptions{IncludeContent: openviking.Bool(true),IncludeFiles: openviking.Bool(true),})-_ = skill+if err != nil {+ return err+}+fmt.Println(skill)```**HTTP API**@@ -663,7 +672,10 @@ console.log(await client.findSkills("database migration"));results, err := client.FindSkills(ctx, "search the internet", &openviking.FindSkillsOptions{Limit: 5,})-_ = results+if err != nil {+ return err+}+fmt.Println(results)```**HTTP API**@@ -727,8 +739,15 @@ validated, err := client.ValidateSkill(ctx, map[string]any{"name": "search-web","description": "...",}, nil)+if err != nil {+ return err+}+fmt.Println(validated)updated, err := client.UpdateSkill(ctx, "search-web", "./skills/search-web", nil)-_, _ = validated, updated+if err != nil {+ return err+}+fmt.Println(updated)```**HTTP API**@@ -791,7 +810,10 @@ await client.deleteSkill("my-skill");```godeleted, err := client.DeleteSkill(ctx, "old-skill")-_ = deleted+if err != nil {+ return err+}+fmt.Println(deleted)```**HTTP API**@@ -818,7 +840,7 @@ Without names, `ov skills update` attempts all installed Skills and reports unsu### Skill Management Responses-List and search return a `skills` array and `total`. Without `target_uri`, `root_uris` identifies the private user and shared Agent roots; with a target, the response contains a single `root_uri`.+List and search return a `skills` array and `total`. Without `target_uri`, `root_uris` identifies the private user and shared Agent roots; with a target, the response contains a single `root_uri`. The following search response uses an L0 hit. A list response uses the package URI and does not include search scores.```json{@@ -832,7 +854,7 @@ List and search return a `skills` array and `total`. Without `target_uri`, `root{"type": "skill","name": "search-web",- "uri": "viking://user/default/skills/search-web",+ "uri": "viking://user/default/skills/search-web/.abstract.md","root_uri": "viking://user/default/skills/search-web","skill_md_uri": "viking://user/default/skills/search-web/SKILL.md","description": "Search the web for current information",@@ -912,14 +934,9 @@ skill = {}```-### Comprehensive Content--Include in your skill content:+### Execution Conditions and Expected Results-- Clear parameter descriptions with types-- When to use the skill-- Concrete examples-- Edge cases and limitations+State when the Skill applies, the tools and dependencies it needs, its inputs, and the expected output. Give one concrete example and a way to check the result. Explain what the Agent should do when a dependency is missing or a step fails. OpenViking stores these instructions; the consuming Harness determines which tools can actually run.### Consistent Namingdiff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.mdindex fc6aeb1f0..7c12e90f9 100644--- a/docs/en/api/05-sessions.md+++ b/docs/en/api/05-sessions.md@@ -56,7 +56,7 @@ Create a new session. Sessions are containers for conversations, storing message| `keep_recent_count` | int | 0 | 500 | Number of recent live messages to keep (not archived) on a threshold-triggered auto commit. Idle-timeout commits ignore this and commit everything. || `min_commit_interval_seconds` | int | 0 | 604800 | Minimum seconds between two automatic commits (throttle). |-All fields have a minimum of `0` and are clamped into `[0, max]`. Unknown keys are rejected with `InvalidArgumentError`.+All fields have a minimum of `0` and are clamped into `[0, max]`. Unknown keys are rejected with `InvalidArgumentError`. Idle commits also require `memory.session_auto_commit.enabled` on the server; setting `idle_timeout_seconds` alone does not start the scanner.#### 3. Usage Examples@@ -463,7 +463,7 @@ curl -X PATCH http://localhost:1933/api/v1/sessions/a1b2c3d4/config \**Python SDK**```python-result = client.update_session_config(+result = await client.update_session_config(session_id="a1b2c3d4",options={"memory_extraction_config": {@@ -690,12 +690,12 @@ Get the assembled session context used for LLM context building. This endpoint r**Return Fields Description:**- `latest_archive_overview`: The `overview` of the latest completed archive, when it fits the token budget- `pre_archive_abstracts`: Kept for backward compatibility, returns empty array-- `messages`: All incomplete archive messages after the latest completed archive, plus current live session messages+- `messages`: Incomplete archive messages after the latest completed archive and current live messages, limited to the token budget- `estimatedTokens`: Estimated total tokens-- `stats`: Statistics+- `stats`: Statistics. `includedArchives` counts entries in `pre_archive_abstracts`, which is currently empty; check `latest_archive_overview` itself to see whether an overview is included**Token Budget Allocation Strategy:**-1. First allocate to current live messages+1. Fit the messages into the budget first, dropping or truncating messages when needed, then calculate the remaining budget2. Remaining budget prioritizes the latest archive overview3. Pre-archive abstracts are not currently returned@@ -712,7 +712,7 @@ Get the assembled session context used for LLM context building. This endpoint r| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| session_id | str | Yes | - | Session ID |-| token_budget | int | No | 128000 | Non-negative token budget for assembled archive payload after active `messages` |+| token_budget | int | No | 128000 | Non-negative budget for the entire returned context; messages are budgeted first, then the archive overview uses the remainder |#### 3. Usage Examples@@ -788,14 +788,14 @@ ov session get-session-context a1b2c3d4 --token-budget 128000"created_at": "2026-03-24T09:10:20Z"}],- "estimatedTokens": 160,+ "estimatedTokens": 29,"stats": {"totalArchives": 2,- "includedArchives": 1,- "droppedArchives": 0,+ "includedArchives": 0,+ "droppedArchives": 2,"failedArchives": 0,- "activeTokens": 98,- "archiveTokens": 62+ "activeTokens": 10,+ "archiveTokens": 19}}}@@ -927,7 +927,7 @@ If the archive does not exist, is incomplete, or does not belong to the session,#### 1. API Implementation Introduction-Delete a session and all its data, including messages, archive history, memories, etc. Deletion is irreversible.+Delete the session directory, including messages, archives, and session audit records. Long-term memories already extracted into user or Peer memory directories remain; locate and delete those URIs separately when needed. This endpoint has no automatic undo.**Code Entries:**- `openviking/server/routers/sessions.py:delete_session()` - HTTP route@@ -1026,8 +1026,8 @@ Add a message to the session. Supports two modes: simple text mode and Parts mod|-----------|------|----------|---------|-------------|| session_id | str | Yes | - | Session ID || role | str | Yes | - | Message role: "user" or "assistant" |-| parts | List[dict \| MessagePart] | Conditional | - | SDK part dictionaries or `TextPart`/`ContextPart`/`ImagePart`/`ToolPart` objects; HTTP API accepts dictionaries only; mutually exclusive with content |-| content | str | Conditional | - | Message text content (simple mode; mutually exclusive with parts) |+| parts | List[dict \| MessagePart] | Conditional | - | SDK part dictionaries or `TextPart`/`ContextPart`/`ImagePart`/`ToolPart` objects; HTTP API accepts dictionaries only; use instead of content |+| content | str | Conditional | - | Message text content (simple mode; use instead of parts) || peer_id | str | No | None | Optional stable interaction peer identity || options | AddMessageOptions | No | None | Advanced message options such as `created_at`, `telemetry`, `turn_id`, `message_kind`, and `source_message_ids` |@@ -1213,7 +1213,7 @@ ov session add-message a1b2c3d4 --role user --content "How do I authenticate use#### 1. API Implementation Introduction-Add multiple messages to a session in a single request. Suitable for scenarios that require writing a large number of messages at once (e.g., importing conversation history, memory extraction), offering significantly better performance than calling `add_message()` repeatedly.+Add multiple messages to a session in one request, for example when importing conversation history. Batching reduces the number of requests compared with calling `add_message()` for each message.**Difference from `add_message()`**:- `add_message()`: Add 1 message per request@@ -1331,14 +1331,14 @@ ov add-memory '[{"role":"user","content":"Hello"},{"role":"assistant","content":#### 1. API Implementation Introduction-Commit a session. Message archiving (Phase 1) completes immediately. Summary generation and memory extraction (Phase 2) run asynchronously in the background when messages are archived. Archived commits return `status: "accepted"` with a `task_id`; no-op commits return `status: "skipped"` with `task_id: null`.+Commit a session. Message archiving (Phase 1) completes before the response returns. Summary generation and memory extraction (Phase 2) run asynchronously in the background when messages are archived. Archived commits return `status: "accepted"` with a `task_id`; no-op commits return `status: "skipped"` with `task_id: null`.**Two-Phase Commit Flow:**-- **Phase 1 (Synchronous)**: Snapshot current messages, clear live session, create archive directory, write original messages+- **Phase 1 (Synchronous)**: Split messages according to the retention policy, persist the archive and recovery records, enqueue Phase 2, and write retained messages back to the live session- **Phase 2 (Asynchronous)**: Generate summaries (L0/L1) and extract long-term memories**Notes:**-- Rapid consecutive commits on the same session are accepted; each request gets its own `task_id`.+- Consecutive commits are accepted; only requests that produce an archive return a separate `task_id`. No-op commits do not create tasks.- Empty sessions, or commits where all messages remain inside `keep_recent_count`, complete synchronously with `archived: false`.- Background Phase 2 work is serialized by archive order: archive `N+1` waits until archive `N` writes `.done`.- If an earlier archive failed and left no `.done`, later commit requests fail with `FAILED_PRECONDITION` until that failure is resolved.@@ -1360,7 +1360,7 @@ Commit a session. Message archiving (Phase 1) completes immediately. Summary gen| keep_recent_count | int | No | 0 | Number of recent live messages to retain (kept live, not archived) after commit. `0` (default) archives all messages. || reset_context | bool | No | false | HTTP API: archive all live messages, then append a boundary archive containing only a `.done` marker with `context_reset`. Keeps the session ID and raw history, clears injected context and stops future summaries from inheriting pre-reset overviews. Requires `keep_recent_count=0` and no `retention_mode`. |-`reset_context` is used by the OpenClaw plugin reset hook and `Session.commit_async()`. It also creates a boundary when there are no live messages, unless the newest archive is already a reset boundary. Memory extraction for older archives can finish independently; long-term memories are preserved. SDK/CLI convenience options are not added in this change.+`reset_context` is used by the OpenClaw plugin reset hook and `Session.commit_async()`. It also creates a boundary when there are no live messages, unless the newest archive is already a reset boundary. Memory extraction for older archives can finish independently; long-term memories are preserved. The SDK and CLI do not expose a dedicated `reset_context` option; use the HTTP API when needed.The effective policy is resolved in this order: Session `.meta.json`, latest@@ -1394,17 +1394,18 @@ import openviking_sdk as ovclient = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")await client.initialize()-# Commit returns immediately with task_id; summary + memory extraction runs in background+# Commit finishes Phase 1; summary and memory extraction run in the backgroundresult = await client.commit_session(session_id="a1b2c3d4")print(f"Status: {result['status']}")print(f"Task ID: {result['task_id']}")-# Poll background task status-task = await client.get_task(task_id=result["task_id"])-if task["status"] == "completed":- memories = task["result"]["memories_extracted"]- total = sum(memories.values())- print(f"Memories extracted: {total}")+# Check once; poll again if the task is still pending or running+task_id = result.get("task_id")+if task_id:+ task = await client.get_task(task_id=task_id)+ print(task["status"])+ if task["status"] == "completed":+ print(task["result"]["memories_extracted"])```**TypeScript SDK**@@ -1417,7 +1418,7 @@ console.log(await client.commitSession("session-id"));```gocommit, err := client.CommitSession(ctx, "a1b2c3d4", &openviking.CommitSessionOptions{- KeepRecentCount: 0,+ KeepRecentCount: openviking.Int(0),})if err != nil {return err@@ -1425,11 +1426,13 @@ if err != nil {fmt.Println(commit["status"], commit["task_id"])taskID, _ := commit["task_id"].(string)-task, err := client.GetTask(ctx, taskID)-if err != nil {- return err+if taskID != "" {+ task, err := client.GetTask(ctx, taskID)+ if err != nil {+ return err+ }+ fmt.Println(task["status"])}-fmt.Println(task["status"])```**CLI**@@ -1475,7 +1478,7 @@ ov session commit a1b2c3d4#### 1. API Implementation Introduction-Trigger memory extraction immediately for an existing session without creating a new commit task.+Extract memories from the existing session’s current live messages and wait for the extraction result. This does not create a commit task or replace archiving; previously archived history is not included again as live input.**Code Entries:**- `openviking/server/routers/sessions.py:extract_session()` - HTTP route@@ -1504,7 +1507,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/extract \**Response Example**-The endpoint returns the extracted memory write results as a JSON list. The exact item shape depends on which memories were produced for that session.+The response’s `result` field contains the list of extracted memory writes. The exact item shape depends on which memories were produced for that session.<a id="get_task"></a><a id="list_tasks"></a>@@ -1544,7 +1547,7 @@ viking://user/{user_id}/sessions/{session_id}/### memory_diff.json Structure-When long-term memory extraction runs successfully, the commit writes a `memory_diff.json` to the archive directory, recording all memory changes for auditing and rollback:+When long-term memory extraction runs successfully, the commit writes a `memory_diff.json` to the archive directory, recording all memory changes for auditing and reviewing changes:```json{@@ -1553,23 +1556,23 @@ When long-term memory extraction runs successfully, the commit writes a `memory_"operations": {"adds": [{- "uri": "memory/user/xxx/identity.md",- "memory_type": "identity",+ "uri": "viking://user/alice/memories/profile.md",+ "memory_type": "profile","after": "Newly created file content"}],"updates": [{- "uri": "memory/user/xxx/context/project.md",- "memory_type": "context",+ "uri": "viking://user/alice/memories/preferences/project.md",+ "memory_type": "preferences","before": "Content before modification","after": "Content after modification"}],"deletes": [{- "uri": "memory/user/xxx/context/old.md",- "memory_type": "context",+ "uri": "viking://user/alice/memories/preferences/old.md",+ "memory_type": "preferences","deleted_content": "Deleted file content"}]@@ -1613,56 +1616,68 @@ An empty `memory_diff.json` (all counts zero) is written when long-term memory e**Python SDK**```python+import asyncio+from openviking_sdk import AsyncHTTPClient, ContextPart, TextPart# Initialize clientclient = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")await client.initialize()-# Create new session-session_result = await client.create_session()-session_id = session_result["session_id"]-print(f"Session created: {session_id}")--# Add user message-await client.add_message(- session_id=session_id,- role="user",- content="How do I configure embedding?",-)--# Search with session context-results = await client.search(- query="embedding configuration",- session_id=session_id,-)+try:+ # Create new session+ session_result = await client.create_session()+ session_id = session_result["session_id"]+ print(f"Session created: {session_id}")-# Add assistant message with context reference-resources = results.get("resources", [])-if resources:- resource = resources[0]+ # Add user messageawait client.add_message(session_id=session_id,- role="assistant",- parts=[- TextPart(text="Based on the documentation, you can configure embedding..."),- ContextPart(- uri=resource["uri"],- context_type="resource",- abstract=resource.get("abstract", ""),- ),- ],+ role="user",+ content="How do I configure embedding?",+ )++ # Search with session context+ results = await client.search(+ query="embedding configuration",+ session_id=session_id,)-# Commit session (returns immediately; summary + memory extraction runs in background)-commit_result = await client.commit_session(session_id=session_id)-print(f"Task ID: {commit_result['task_id']}")-# Optional: poll for completion-task = await client.get_task(task_id=commit_result["task_id"])-if task and task["status"] == "completed":- memories = task["result"]["memories_extracted"]- total = sum(memories.values())- print(f"Memories extracted: {total}")+ # Add assistant message with context reference+ resources = results.get("resources", [])+ if resources:+ resource = resources[0]+ await client.add_message(+ session_id=session_id,+ role="assistant",+ parts=[+ TextPart(text="Based on the documentation, you can configure embedding..."),+ ContextPart(+ uri=resource["uri"],+ context_type="resource",+ abstract=resource.get("abstract", ""),+ ),+ ],+ )+ # Commit session; summary and memory extraction run in the background+ commit_result = await client.commit_session(session_id=session_id)+ print(f"Task ID: {commit_result['task_id']}")++ # Optional: poll for completion+ task_id = commit_result.get("task_id")+ if task_id:+ for _ in range(30):+ task = await client.get_task(task_id=task_id)+ if task and task["status"] == "completed":+ print(task.get("result"))+ break+ if task and task["status"] in {"failed", "cancelled"}:+ raise RuntimeError(task)+ await asyncio.sleep(1)+ else:+ print(f"Still pending: {task_id}; check this task again later")+finally:+ await client.close()```**HTTP API**@@ -1692,13 +1707,13 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \-H "X-API-Key: your-key" \-d '{"role": "assistant", "content": "Based on the documentation, you can configure embedding..."}'-# Step 5: Commit session (returns immediately with task_id)+# Step 5: Commit session (an archived commit returns a task_id)curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \-H "Content-Type: application/json" \-H "X-API-Key: your-key"# Returns: {"status": "ok", "result": {"status": "accepted", "task_id": "uuid-xxx", ...}}-# Step 7: Poll background task status (optional)+# Step 6: Check the background task; poll again if it has not finishedcurl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \-H "X-API-Key: your-key"```@@ -1717,7 +1732,7 @@ if session_info["message_count"] > 10:### Use Session Context for Search```python-# Better search results with conversation context+# Interpret the query using session context; results depend on relevance and query-planning settingsresults = await client.search(query=query, session_id=session_id)```diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.mdindex b45be33ce..c3841f867 100644--- a/docs/en/api/06-retrieval.md+++ b/docs/en/api/06-retrieval.md@@ -6,10 +6,11 @@ OpenViking provides multiple retrieval methods, including simple vector similari| Aspect | find | search ||--------|------|--------|-| Intent Analysis | No | Yes |-| Session Context | No | Yes |-| Query Expansion | No | Yes |-| Default Limit | 10 | 10 |+| Intent Analysis | No | Requires session content and `retrieval.enable_intent=true` |+| Session Context | No | Optional |+| Query Expansion | No | When session content exists and intent analysis is enabled |+| Reranking | No | Used for text queries when a reranker is configured |+| Default Limit | 10 | 10 per planned query || Use Case | Simple queries | Conversational search |## Retrieval Pipeline@@ -29,7 +30,7 @@ Query → Intent Analysis (search only, optional) → Global Vector Search → R### find()-Basic vector similarity search without session context.+Semantic retrieval without session context.#### 1. API Implementation Introduction@@ -52,19 +53,20 @@ The `find()` method runs one global vector similarity search in QUICK mode for s| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|-| query | str | No | "" | Search query string. Required unless `image_url` is provided |+| query | str | No | "" | Search query string. May be omitted for an image query or a filter-only lookup || image_url | str | No | None | Image query as a `data:image/...;base64,...`, `http(s)://`, or `viking://` URI. Requires a multimodal embedding model || target_uri | str \| List[str] | No | "" | Limit search to specific URI prefix || events_time_decay_protection | str \| null | No | null | Omit or pass `null` to disable decay. Pass `"0"` to decay immediately, or a duration such as `"7d"` to preserve the original score during that period and decay afterward. Supports non-negative integer `Xm`/`Xh`/`Xd` || context_type | str \| List[str] | No | None | Limit results to one or more `ContextType` values: `memory`, `resource`, or `skill` || tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form. Multiple tags are combined with AND; a result must contain every requested tag |+| limit | int | No | 10 | Maximum returned results || node_limit | int | No | None | Optional HTTP alias; overrides `limit` when provided || score_threshold | float | No | None | Minimum relevance score threshold || filter | Dict | No | None | Metadata filter || since | str | No | None | Lower time bound, accepts `2h` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--after` maps to this field || until | str | No | None | Upper time bound, accepts `30m` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--before` maps to this field || time_field | "updated_at" \| "created_at" | No | "updated_at" | Metadata time field used by `since` / `until` |-| level | str | No | None | Limit results to specific level(s), e.g., `0`, `1`, `2`, or `0,1,2`. CLI `--level`/`-L` maps to this field |+| level | int \| str \| List[int] | No | None | Limit results to specific level(s), e.g., `0`, `1`, `2`, or `0,1,2`. CLI `--level`/`-L` maps to this field || include_provenance | bool | No | False | Include provenance/query-plan details in serialized result || read_content | bool | No | False | Read each final matched URI with the visible-content read semantics and inline the result as `content`. Individual read failures leave the hit unchanged. || telemetry | bool \| object | No | False | Attach telemetry data to response |@@ -183,7 +185,6 @@ Tags must use strict `k=v` strings. When multiple tags are provided, `find()` re```pythonimport openviking_sdk as ov-from openviking_sdk import TextPartclient = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")client.initialize()@@ -365,11 +366,11 @@ ov find "red poster style" --image ./poster.png --uri "viking://resources/images### search()-Intelligent retrieval with session context and intent analysis.+Semantic retrieval with optional session-aware query planning.#### 1. API Implementation Introduction-The `search()` method adds session context understanding and intent analysis capability on top of `find()`. It better understands user query intent based on conversation history, performs query expansion, and provides more relevant search results.+`search()` can plan queries from session context. It calls the LLM only when `retrieval.enable_intent=true` and the session has a summary or messages. Without a session, with an empty session, or with intent analysis disabled, it uses the original query. Image queries skip session planning.**Processing Pipeline**:1. Load session context (if session_id is provided)@@ -399,13 +400,14 @@ The `search()` method adds session context understanding and intent analysis cap| events_time_decay_protection | str \| null | No | null | Omit or pass `null` to disable decay. Pass `"0"` to decay immediately, or a duration such as `"7d"` to preserve the original score during that period and decay afterward. Supports non-negative integer `Xm`/`Xh`/`Xd` || context_type | str \| List[str] | No | None | Limit results to one or more `ContextType` values: `memory`, `resource`, or `skill` || tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form. Multiple tags are combined with AND; a result must contain every requested tag |+| limit | int | No | 10 | Maximum results per planned query; list mode concatenates the results, so its total may exceed this value || node_limit | int | No | None | Optional HTTP alias; overrides `limit` when provided || score_threshold | float | No | None | Minimum relevance score threshold || filter | Dict | No | None | Metadata filter || since | str | No | None | Lower time bound, accepts `2h` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--after` maps to this field || until | str | No | None | Upper time bound, accepts `30m` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--before` maps to this field || time_field | "updated_at" \| "created_at" | No | "updated_at" | Metadata time field used by `since` / `until` |-| level | str | No | None | Limit results to specific level(s), e.g., `0`, `1`, `2`, or `0,1,2`. CLI `--level`/`-L` maps to this field |+| level | int \| str \| List[int] | No | None | Limit results to specific level(s), e.g., `0`, `1`, `2`, or `0,1,2`. CLI `--level`/`-L` maps to this field || include_provenance | bool | No | False | Include provenance/query-plan details in serialized result || read_content | bool | No | False | Read each final matched URI with the visible-content read semantics and inline the result as `content`. Individual read failures leave the hit unchanged. Only supported by `mode="list"`. || telemetry | bool \| object | No | False | Attach telemetry data to response |@@ -486,6 +488,7 @@ curl -X POST http://localhost:1933/api/v1/search/search \```pythonimport openviking_sdk as ov+from openviking_sdk import TextPartclient = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")client.initialize()@@ -507,7 +510,7 @@ results = client.search(query="best practices",session_id=session.session_id,options={- "context_type": "skill",+ "context_type": "resource","since": "2h",},)@@ -550,7 +553,7 @@ console.log(await client.search("authentication", { targetUri: "viking://resourc```goresult, err := client.Search(ctx, "best practices", &openviking.SearchOptions{SessionID: "abc123",- ContextType: "skill",+ ContextType: "resource",Limit: 10,})if err != nil {@@ -575,7 +578,7 @@ ov search "watch vs scheduled" --after 2026-03-15 --before 2026-03-20ov search "recent decisions" --context-type memory --level 2 \--events-time-decay-protection 1d-# Search without session (still performs intent analysis)+# Search without session (uses the original query)ov search "how to implement OAuth 2.0 authorization code flow"# BM25 keyword retrieval@@ -601,7 +604,7 @@ ov search "similar poster" --image ./poster.png --uri "viking://resources/images"resources": [{"context_type": "resource",- "uri": "viking://resources/docs/oauth-best-practices",+ "uri": "viking://resources/docs/oauth-best-practices/.overview.md","level": 1,"score": 0.95,"category": "",@@ -637,7 +640,7 @@ ov search "similar poster" --image ./poster.png --uri "viking://resources/images### search(mode="context")-Assemble retrieval results into an injection-ready context block. `mode="list"` (the default) returns the ranked hit list and behaves exactly like the previous `search()`; `mode="context"` opens the assembly face: budgeting, tier degradation, cross-turn dedup and the optional LLM digest all happen server-side in one request.+Assemble retrieval results into an injection-ready context block. `mode="list"` (the default) returns the ranked hit list and behaves exactly like the previous `search()`; `mode="context"` applies the token budget, selects detail levels, deduplicates across turns, and optionally produces an LLM digest in one server request.#### 1. Implementation Overview@@ -690,7 +693,7 @@ Injecting context every turn used to mean searching per type, reading each hit b**Tier rules**- **Purpose presets**: `chat` uses `events:3, entities:3, preferences:1, experiences:1, resources:1, skills:1`; `coding` uses `events:1, entities:2, preferences:1, experiences:1, resources:3, skills:2`. These are absolute per-category ceilings, not weights. Results are deduplicated and globally sorted after gathering, but are not truncated by a second global `limit`-- **Default tier per category**: with `detail` omitted, each category lands on the tier below. Only `events` reads a file; every other category costs no read+- **Default tier per category**: with `detail` omitted, each category lands on the tier below. Among file entries, only `events` needs a body read at its default tier. Directory hits read `.overview.md`| Category | Default tier | Leftover budget may reach | Why ||----------|--------------|---------------------------|-----|@@ -698,7 +701,7 @@ Injecting context every turn used to mean searching per type, reading each hit b| `entities` / `preferences` / `experiences` | abstract | abstract | Short bodies, and the writer stores the whole body in the abstract scalar, so abstract already is the complete file || `resources` / `skills` | abstract | abstract | A resource shows the 256-char abstract from semantic processing, a skill the name/description generated from its `SKILL.md` frontmatter; bodies can be large or carry credentials, so deepening is opt-in || `memories` | abstract | abstract | Built-in memory types outside the four named ones — `cases`, `patterns`, `tools`, `trajectories`, skill-usage memories. Only quota-free retrieval reaches them; they own no bucket, so `quotas` cannot name them, but `detail` and `other_peer_penalty` can |- | Directory hits | overview | overview | A directory has no abstract, so it reads the `.overview.md` sidecar; a full tier is meaningless for a subtree. Skill package hits are the exception: they normalize onto `<package root>/SKILL.md` and follow the file rules above |+ | Directory hits | overview | overview | Directory entries use the `.overview.md` sidecar and do not expand the entire subtree. Skill package hits are the exception: they normalize onto `<package root>/SKILL.md` and follow the file rules above |- **Skill packages**: a package stores one vector per file and per directory level, and they all collapse into a single entry before the quotas apply — one entry per package, one quota slot, whichever file inside it matched. That entry's `uri` is `<package root>/SKILL.md`, the same path `/skills/find` reports as `skill_md_uri`, and its text is the package's own abstract; a package whose abstract has not been generated yet degrades to a bare `uri` rather than borrowing the summary of the file that matched. `dedup_turns` therefore cools a whole package: once one is served at `abstract` or deeper, a hit on any file inside it is skipped for the rest of the window- **Floor**: every result carries at least its `uri`. When a memory abstract is unavailable or busts the per-entry cap, the entry falls back to overview: the memory writer stores the whole body in that scalar, so for memory categories overview sits *below* abstract on the content ladder and the substitute discloses less. A `resources` or `skills` abstract is the short generated summary instead, so the same substitution would read a body the caller never asked for — those two degrade to a bare `uri` rather than deepen@@ -738,7 +741,9 @@ curl -X POST http://localhost:1933/api/v1/search/search \-d '{"query":"tier design","mode":"context","max_tokens":3000,"rewrite":true}'```-**Response**+**Response excerpt**++`entries`, text, and `rendered` are shortened below; the statistics describe the full 13-entry response.```json{@@ -945,24 +950,33 @@ For HTTP `POST /api/v1/search/grep`, set `include_tags: true` to include tags wi```json{- "status": "ok",- "result": {- "matches": [- {- "uri": "viking://resources/docs/auth.md",- "line": 15,- "content": "User authentication is handled by...",- "before_context": [- {"line": 14, "content": "## Authentication"}- ],- "after_context": [- {"line": 16, "content": "Configure an API key before sending requests."}- ],- "tags": ["team=search", "env=prod"]- }+ "status": "ok",+ "result": {+ "matches": [+ {+ "uri": "viking://resources/docs/auth.md",+ "line": 15,+ "content": "User authentication is handled by...",+ "before_context": [+ {+ "line": 14,+ "content": "## Authentication"+ }],- "count": 1- }+ "after_context": [+ {+ "line": 16,+ "content": "Configure an API key before sending requests."+ }+ ],+ "tags": [+ "team=search",+ "env=prod"+ ]+ }+ ],+ "count": 1+ }}```@@ -1036,7 +1050,7 @@ print(f"Found {results['count']} markdown files:")for uri in results['matches']:print(f" {uri}")-# Find all Python files with extra stat fields+# Find Markdown files matching all supplied tagsresults = client.glob(pattern="**/*.md",uri="viking://resources",@@ -1094,14 +1108,14 @@ Default (URI strings):```json{- "status": "ok",- "result": {- "matches": [- "viking://resources/docs/api.md",- "viking://resources/docs/guide.md"- ],- "count": 2- }+ "status": "ok",+ "result": {+ "matches": [+ "viking://resources/docs/api.md",+ "viking://resources/docs/guide.md"+ ],+ "count": 2+ }}```@@ -1109,14 +1123,24 @@ With `extra_fields=["name","size","mtime"]`:```json{- "status": "ok",- "result": {- "matches": [- {"name": "api.md", "uri": "viking://resources/docs/api.md", "size": 12345, "mtime": 1720000000},- {"name": "guide.md", "uri": "viking://resources/docs/guide.md", "size": 8234, "mtime": 1720000001}- ],- "count": 2- }+ "status": "ok",+ "result": {+ "matches": [+ {+ "name": "api.md",+ "uri": "viking://resources/docs/api.md",+ "size": 12345,+ "mtime": 1720000000+ },+ {+ "name": "guide.md",+ "uri": "viking://resources/docs/guide.md",+ "size": 8234,+ "mtime": 1720000001+ }+ ],+ "count": 2+ }}```@@ -1126,7 +1150,7 @@ With `extra_fields=["name","size","mtime"]`:### Read Content Progressively-Retrieval results usually only contain L0 summaries, you can progressively load more detailed content as needed.+Results include an abstract and the matched URI. Semantic L0/L1 hits point to `.abstract.md` or `.overview.md`; use their parent directory with `overview()`. L2 hits point to files that `read()` can return directly.**Python SDK**@@ -1144,7 +1168,8 @@ for context in results.get("resources", []):if context.get("level", 0) < 2:# Get L1 (overview) for directories- overview = client.overview(uri=context["uri"])+ directory_uri = context["uri"].rsplit("/", 1)[0]+ overview = client.overview(uri=directory_uri)print(f"Overview: {overview[:500]}...")else:# Load L2 (content) for filesdiff --git a/docs/en/api/07-system.md b/docs/en/api/07-system.mdindex 32593805a..bd62fa6e1 100644--- a/docs/en/api/07-system.md+++ b/docs/en/api/07-system.md@@ -8,7 +8,7 @@ The OpenViking System API provides health, readiness, consistency, and multi-wri#### 1. API Implementation Overview-Basic health check endpoint. No authentication required. Returns service version and health status. If authentication is provided, also returns auth mode and identity information.+Basic liveness check; no authentication is required. Returns the service version, health status, and auth mode. Supplied credentials trigger identity resolution; successful resolution adds identity fields, and invalid credentials are rejected with an authentication error.In trusted mode, a complete `X-OpenViking-Account` and `X-OpenViking-User` header pairrequests identity resolution, including on localhost deployments with `root_api_key`@@ -190,7 +190,6 @@ Get system status including initialization state and authenticated user info. `r**Code Entry Points**:- `openviking/server/routers/system.py:system_status` - HTTP route-- `sdk/python/openviking_sdk/client.py:SyncHTTPClient.get_status` - SDK entry- `crates/ov_cli/src/commands/system.rs` - CLI command#### 2. Interface and Parameters@@ -309,11 +308,11 @@ ov system consistency viking://resources/my-project{"status": "ok","result": {- "ok": false,- "expected_count": 3,- "missing_record_count": 1,- "missing_records_truncated": false,- "missing_records": [+ "ok": false,+ "expected_count": 3,+ "missing_record_count": 1,+ "missing_records_truncated": false,+ "missing_records": [{"uri": "viking://resources/my-project/README.md","path": "README.md",@@ -331,7 +330,7 @@ ov system consistency viking://resources/my-project#### 1. API Implementation Overview-Wait for all asynchronous processing (embedding, semantic generation) to complete. This method blocks until all queued tasks are processed or timeout occurs.+Wait until the processing queues are drained, or until the timeout. This check is not scoped to the caller’s last request and does not cover every asynchronous API. Check the returned `error_count` and `errors`; empty queues do not prove that every operation succeeded. To confirm one import or commit, poll its [task ID](17-tasks.md) instead.**Code Entry Points**:- `openviking/server/routers/system.py:wait_processed` - HTTP route@@ -366,12 +365,9 @@ curl -X POST http://localhost:1933/api/v1/system/wait \**Python SDK**```python-# Add resources-client.add_resource(path="./docs/")--# Wait for all processing to complete+# Wait for the current processing queues to drainstatus = client.wait_processed(timeout=60.0)-print(f"Processing complete: {status}")+print(status) # Inspect each queue’s error_count and errors```**TypeScript SDK**diff --git a/docs/en/api/09-metrics.md b/docs/en/api/09-metrics.mdindex d2ea466ad..12abace4a 100644--- a/docs/en/api/09-metrics.md+++ b/docs/en/api/09-metrics.md@@ -2,11 +2,7 @@OpenViking exposes a `/metrics` endpoint for Prometheus, Grafana Agent, and other monitoring systems that scrape Prometheus exposition text.-Unlike `/api/v1/observer/*`, `/metrics` is intended for:--- machine scraping rather than human-oriented inspection-- Prometheus exposition text rather than the standard JSON API wrapper-- runtime health and service quality signals rather than business analytics+It returns Prometheus text for scheduled collection: runtime health and service-quality signals, not business analytics. For a component status snapshot in JSON, use `/api/v1/observer/*`.## API Reference@@ -18,9 +14,7 @@ This endpoint is typically scraped by Prometheus on a schedule, but it is also u**Authentication**-- In the current implementation, `/metrics` is not wired to `get_request_context` or other auth dependencies.-- In other words, based on the current server code, `/metrics` is effectively a public scrape endpoint.-- If access control is tightened later through a gateway, reverse proxy, or deployment policy, follow the actual deployment configuration.+The server does not authenticate `/metrics` requests. If your gateway or reverse proxy restricts access, configure the scraper with that layer’s credentials.**HTTP API**diff --git a/docs/en/api/11-snapshot.md b/docs/en/api/11-snapshot.mdindex d339552b5..4048f078f 100644--- a/docs/en/api/11-snapshot.md+++ b/docs/en/api/11-snapshot.md@@ -1,8 +1,8 @@# Snapshots (Multi-Version Management)-On top of VikingFS, OpenViking provides Git-based multi-version management, called **Snapshots**. It saves an account's entire resource tree as a series of immutable commits, letting you walk history, compare versions, and restore the workspace to any past state.+Snapshots save immutable versions of a selected file tree. Use `commit` to save a version, `log` to browse history, `show` to read an older file, `diff` to compare a file between versions, and `restore` to recover saved content. Uncommitted or excluded files are outside the recovery scope; ACLs and vector indexes are not versioned.-Snapshots are powered by [gitoxide](https://github.com/Byron/gitoxide) embedded in the Rust RAGFS layer, maintaining one logical Git repository per `account_id`. This is fully transparent to callers — you never touch a `.ovgit` directory, the object store, or ref internals.+Snapshots are powered by [gitoxide](https://github.com/Byron/gitoxide) embedded in the Rust RAGFS layer, maintaining one logical Git repository per `account_id`. Use the snapshot APIs to manage versions; direct edits to the underlying repository are not part of this workflow.The five core commands:@@ -20,7 +20,7 @@ In addition, account-level `.ovgitignore` exclusion rules can be managed (`get`/- **Commit**: A snapshot is a commit, uniquely identified by a 40-hex SHA-1 `commit_oid`. Most commands also accept an abbreviated OID prefix or a branch name (e.g. `main`).- **Branch**: The default branch is `main`. Unless you pass one explicitly, every command operates on `main`.-- **Forward-commit restore**: `restore` does **not** rewind or rewrite history. It reads the content at `source_commit`, writes the diff back into the workspace, and creates a **new commit on top of the current HEAD**. The new commit's parent is therefore the HEAD that existed before the restore — **not** `source_commit`. HEAD always advances monotonically and history is never lost.+- **Forward-commit restore**: `restore` does **not** rewind or rewrite history. It reads the content at `source_commit`, writes the diff back into the workspace, and creates a **new commit on top of the current HEAD**. The new commit's parent is therefore the HEAD that existed before the restore — **not** `source_commit`. The restore preserves prior commits; when the selected source tree matches HEAD, it returns `noop` without creating a commit. This comparison does not inspect uncommitted workspace changes.- **Scope**: `commit` can be limited to specific URIs via `paths`; `restore` can be limited to a subtree via `project_dir`, leaving files outside it untouched.## ACL permissions@@ -34,7 +34,7 @@ Snapshots use the current ACL at operation time. ACLs are not stored in snapshot| `restore` overwriting a file | `write` on the file || `restore` creating a file | `write` on the parent directory || `restore` deleting a file | `write` on the file |-| Read/write/delete `.ovgitignore` | ADMIN |+| Read/write/delete `.ovgitignore` | ADMIN or ROOT |USER and ADMIN callers must provide `paths` for `commit` and `log`, `project_dir` for `restore`, and `path` for `show`; account-wide commit metadata lookup without `path` is reserved for local ROOT mode. A user can operate on accessible shared resources and their own `viking://user/{user_id}/...` space, but not another user's space. Directory operations preflight the complete scope instead of silently skipping denied descendants. `restore` authorizes every planned write and deletion before it mutates the workspace.@@ -406,13 +406,6 @@ This is a **forward-commit restore**: it computes the diff between `source_commi**Python SDK (HTTP)**```python-result = client.snapshot.restore(- project_dir="viking://resources/my_project",- source_commit="3f2a1b9c",- message="restore to v1",-)-print(result["result"], result["new_commit_oid"])-# Preview which files would change firstplan = client.snapshot.restore(project_dir="viking://resources/my_project",@@ -422,6 +415,18 @@ plan = client.snapshot.restore(print(plan["diff"])```+```python+# Apply after reviewing the plan+result = client.snapshot.restore(+ project_dir="viking://resources/my_project",+ source_commit="3f2a1b9c",+ message="restore to v1",+)+print(result["result"])+if result["result"] == "applied":+ print(result["new_commit_oid"])+```+**TypeScript SDK**```typescript@@ -452,10 +457,11 @@ curl -X POST "http://localhost:1933/api/v1/snapshot/restore" \```bash# Positional args are <source_commit> then <project_dir>-ov snapshot restore 3f2a1b9c viking://resources/my_project -m "restore to v1" -o json--# Dry run+# Preview firstov snapshot restore 3f2a1b9c viking://resources/my_project --dry-run -o json++# Apply after reviewing the plan+ov snapshot restore 3f2a1b9c viking://resources/my_project -m "restore to v1" -o json```**Response (applied)**@@ -525,7 +531,7 @@ The `.ovgitignore` file at the account root is an account-level exclusion file.The syntax is a common glob subset: blank lines are ignored, `#`-prefixed lines are comments, leading/trailing whitespace is trimmed; `!` negation and backslash escaping are **unsupported**; the file is capped at 64 KiB (validated on write). Matching uses account-relative Git tree paths (`/`-separated).-Three methods are provided: `get_gitignore` (read, empty string when absent), `set_gitignore` (write), and `delete_gitignore` (delete, missing is success and idempotent). All three require ADMIN permission, use the account from the request context, and take no path argument.+Three methods are provided: `get_gitignore` (read, empty string when absent), `set_gitignore` (write), and `delete_gitignore` (delete, missing is success and idempotent). All three require ADMIN or ROOT permission, use the account from the request context, and take no path argument.### get_gitignore()@@ -718,5 +724,5 @@ For more end-to-end examples, see the [examples/snapshot/](https://github.com/vo## Related Documentation- [File System](03-filesystem.md): snapshots build on filesystem resources-- [System](07-system.md): track the background vector rebuild triggered by restore via `GET /api/v1/tasks/{task_id}`+- [Background Tasks](17-tasks.md): track the background vector rebuild triggered by restore via `GET /api/v1/tasks/{task_id}`- [API Overview](01-overview.md): full endpoint referencediff --git a/docs/en/api/12-content.md b/docs/en/api/12-content.mdindex 4b1f03503..3c25829a7 100644--- a/docs/en/api/12-content.md+++ b/docs/en/api/12-content.md@@ -144,13 +144,13 @@ Read the complete text of an L0, L1, or L2 file.| uri | str | Yes | - | Viking URI (e.g. `viking://resources/docs/api.md`) or a 32-character hex vector record `id` (returned by `stat()`) || offset | int | No | 0 | Starting line number (0-indexed) || limit | int | No | -1 | Number of lines to read, `-1` means read to end |-| raw | bool | No | false | Return raw stored content without memory-field cleanup. HTTP API only (Python SDK does not expose it yet). |+| raw | bool | No | false | Return raw stored content without memory-field cleanup. In Python, use `client.read_raw(uri)` to read this form. |**Notes**- `read()` accepts file URIs only. Passing an existing directory URI returns `INVALID_ARGUMENT` (`400`), not `NOT_FOUND`. This error carries a structured `details` payload — `details.expected` is `"file"`, `details.actual` is `"directory"`, and `details.resource` is the offending URI (present on the HTTP path) — so clients can detect a file-vs-directory mismatch programmatically (for example, fall back to `list`) instead of string-matching the message.- Instead of a Viking URI, you may pass the 32-character hex `id` returned by `stat()` for a file. The server looks up the URI via the vector index and applies the same permission checks. Because indexing is asynchronous, a newly returned ID might not be resolvable immediately; lookup also fails if the corresponding vector record has been deleted. In both cases, the server returns `NOT_FOUND` and indicates that the data may not have been indexed yet or may have been deleted.-- Public URI parameters accept `resources` and `user` scopes. For session files, use `viking://user/{user_id}/sessions/{session_id}` or the backward-compatible `viking://session/{session_id}` alias. Internal scopes such as `temp` and `queue` return `INVALID_URI`.+- Public URI parameters accept `resources`, `user`, and `agent` scopes. For session files, use `viking://user/{user_id}/sessions/{session_id}/messages.jsonl` or the backward-compatible `viking://session/{session_id}/messages.jsonl` alias. Internal scopes such as `temp` and `queue` return `INVALID_URI`.**Python SDK**@@ -296,13 +296,13 @@ curl -X POST "http://localhost:1933/api/v1/content/write" \```bashov write viking://resources/docs/api.md \- --content "# Updated API\n\nFresh content." \+ --content $'# Updated API\n\nFresh content.' \--tags team=search,env=prod \--tag-mode replace```-**Response**+**Response when `wait=true` and refresh completes**```json{@@ -386,10 +386,36 @@ result = client.batch_write("mode": "upsert",},],- wait=False,+ wait=True,)```+**TypeScript SDK**++```typescript+const result = await client.batchWrite("viking://resources/wiki", [+ {+ uri: "viking://resources/wiki/new.md",+ content: "# New page\n",+ mode: "upsert",+ },+]);+console.log(result);+```++**Go SDK**++```go+content := "# New page\n"+result, err := client.BatchWrite(ctx, "viking://resources/wiki", []openviking.BatchWriteOperation{+ {URI: "viking://resources/wiki/new.md", Content: &content, Mode: "upsert"},+}, nil)+if err != nil {+ return err+}+fmt.Println(result)+```+**HTTP API**```@@ -409,11 +435,11 @@ curl -X POST http://localhost:1933/api/v1/content/batch-write \"mode": "upsert"}],- "wait": false+ "wait": true}'```-**Response**+**Response when `wait=true` and refresh completes**```json{@@ -436,7 +462,7 @@ curl -X POST http://localhost:1933/api/v1/content/batch-write \}```-The TypeScript and Go SDKs and the CLI do not currently expose batch write directly.+The CLI does not currently expose batch write directly.---@@ -448,6 +474,38 @@ Download a file as raw bytes. This is intended for images, PDFs, and other non-t|-----------|------|----------|-------------|| `uri` | string | Yes | File URI to download |+**Python SDK**++```python+from pathlib import Path++Path("logo.png").write_bytes(+ client.download_bytes("viking://resources/images/logo.png")+)+```++**TypeScript SDK**++```typescript+import { writeFile } from "node:fs/promises";++const bytes = await client.downloadBytes("viking://resources/images/logo.png");+await writeFile("logo.png", bytes);+```++**Go SDK**++```go+// Requires the os package.+data, err := client.DownloadBytes(ctx, "viking://resources/images/logo.png")+if err != nil {+ return err+}+if err := os.WriteFile("logo.png", data, 0600); err != nil {+ return err+}+```+**HTTP API**```http@@ -479,7 +537,7 @@ Content-Disposition: attachment; filename*=UTF-8''logo.png<binary body>```-`ov get <uri> <local-path>` downloads through the HTTP API above and writes the file to a local path. The Python, TypeScript, and Go SDKs do not currently expose a dedicated raw-byte download method.+`ov get <uri> <local-path>` downloads through the HTTP API above and writes the file to a local path.---@@ -699,8 +757,7 @@ There is no `/api/v1/maintenance/reindex` endpoint. Use `/api/v1/content/reindex```bashcurl -X POST http://localhost:1933/api/v1/content/reindex \-H "Content-Type: application/json" \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \+ -H "X-API-Key: your-admin-key" \-d '{"uri": "viking://resources","mode": "vectors_only",@@ -747,8 +804,7 @@ Poll the returned task through the task API:```bashcurl -X GET http://localhost:1933/api/v1/tasks/task_xxx \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default"+ -H "X-API-Key: your-admin-key"```Reindex background tasks use `task_type="admin_reindex"` and `resource_id` equal to the requested `uri`, so they can also be listed with:diff --git a/docs/en/api/14-ovpack.md b/docs/en/api/14-ovpack.mdindex 04fa1290c..50cc876c7 100644--- a/docs/en/api/14-ovpack.md+++ b/docs/en/api/14-ovpack.md@@ -73,8 +73,15 @@ import openviking_sdk as ovclient = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-admin-key")client.initialize()-# Export to local file (HTTP SDK automatically handles download)-# Note: Export functionality is primarily used via CLI+try:+ output_path = client.export_ovpack(+ "viking://resources/my-project/",+ "./exports/my-project.ovpack",+ include_vectors=False,+ )+ print(output_path)+finally:+ client.close()```**TypeScript SDK**@@ -116,7 +123,7 @@ ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-v**Response Example**-This endpoint directly returns a file stream (`Content-Type: application/zip`), does not return a JSON envelope.+This endpoint returns a file stream (`Content-Type: application/zip`) without a JSON envelope.---@@ -133,7 +140,7 @@ Imports a `.ovpack` file to a specified location for restoring or migrating data2. Parse uploaded `.ovpack` file3. Validate manifest metadata, paths, file and directory sets, file sizes, and checksums4. Apply `on_conflict`-5. Import resources to target location and rebuild vectors+5. Import resources to target location and restore compatible vectors or enqueue recomputation, according to `vector_mode`**Code Entry Points**:- `openviking/server/routers/pack.py:import_ovpack` - HTTP router@@ -194,7 +201,7 @@ curl -X POST http://localhost:1933/api/v1/pack/import \-d "{\"temp_file_id\": \"$TEMP_FILE_ID\",\"parent\": \"viking://resources/imported/\",- \"on_conflict\": \"overwrite\",+ \"on_conflict\": \"fail\",\"vector_mode\": \"auto\"}"```@@ -207,8 +214,16 @@ import openviking_sdk as ovclient = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-admin-key")client.initialize()-# Import .ovpack file (HTTP SDK automatically handles upload)-# Note: Import functionality is primarily used via CLI+try:+ uri = client.import_ovpack(+ "./exports/my-project.ovpack",+ "viking://resources/imported/",+ on_conflict="fail",+ vector_mode="auto",+ )+ print(uri)+finally:+ client.close()```**TypeScript SDK**@@ -218,7 +233,7 @@ const uri = await client.importOVPack("./exports/docs.ovpack","viking://resources/",{- onConflict: "overwrite",+ onConflict: "fail",vectorMode: "auto",},);@@ -233,7 +248,7 @@ uri, err := client.ImportOVPack("./exports/my-project.ovpack","viking://resources/imported/",&openviking.ImportPackOptions{- OnConflict: "overwrite",+ OnConflict: "fail",VectorMode: "auto",},)@@ -294,10 +309,12 @@ Back up public scope roots as a restore-only `.ovpack` file. The backup includes`resources` and all `user/{user_id}` content in the current account; sessionsare included through the user namespace under `user/{user_id}/sessions`. Itexcludes internal runtime data such as `temp` and `queue`, as well as user-accounts and API keys. Only ROOT or ADMIN can call this endpoint. Set+accounts and the keys used to authenticate to OpenViking. Files under user privacy-config directories are included and can contain external-service secrets. Only ROOT or ADMIN can call this endpoint. Set`include_vectors=true` to include compatiblepure-dense vector snapshots; hybrid index types reject vector snapshot export.+Here, “public scope” names the exportable URI roots; it does not mean that user files are public. The ZIP contains exported file contents and is not an encrypted backup format.+Backup reads live files and does not provide an atomic point-in-time snapshot.Callers that require strict consistency should pause writes during the backup window.diff --git a/docs/en/api/15-watches.md b/docs/en/api/15-watches.mdindex d9349bd5a..56ca5d493 100644--- a/docs/en/api/15-watches.md+++ b/docs/en/api/15-watches.md@@ -6,16 +6,16 @@ The Watch API manages periodic resource checks, pausing, resuming, and manual tr### Watch Management-List, inspect, update, and trigger watch tasks created via [`add_resource`](02-resources.md#add-resource) with `watch_interval > 0`. The control plane is mirrored across REST (`/api/v1/watches`), the `ov task watch` CLI subcommand group, and a minimum-closure MCP surface (`list_watches` / `cancel_watch`) for agents.+List, inspect, update, and trigger watch tasks created via [`add_resource`](02-resources.md#add-resource) with `watch_interval > 0`. Use REST (`/api/v1/watches`) or `ov task watch` for the full set of operations. MCP provides `list_watches` and `cancel_watch` for listing and removal.#### 1. API Implementation Overview-This control plane wraps the `WatchManager` primitives without changing any server-side behavior. Every endpoint and CLI command resolves the target task by either its `task_id` (path) or its `to_uri` (query). The two keys are interchangeable; if both are supplied they must refer to the same task, otherwise the request is rejected with 400.+Locate a task by `task_id`, or use `to_uri` when exactly one accessible task matches. Multiple Connector Watches can share a target; URI lookup then returns `409 Conflict` and requires a `task_id`. If both keys are supplied, they must identify the same task or the request returns `400`.**Operations**:- **List** (`GET /api/v1/watches`) — returns `{tasks, total}`; pass `?active_only=true` to filter; pass `?to_uri=...` to collapse to a single-task lookup- **Show** (`GET /api/v1/watches/{task_id}`) — inspect one task; optional `?to_uri=` performs a cross-key sanity check-- **Update** (`PATCH /api/v1/watches/{task_id}` or `PATCH /api/v1/watches?to_uri=...`) — partial update of `watch_interval`, `is_active`, `reason`, `instruction`. `is_active` is orthogonal to `watch_interval`: flip `is_active` to pause/resume without losing the configured cadence.+- **Update** (`PATCH /api/v1/watches/{task_id}` or `PATCH /api/v1/watches?to_uri=...`) — partial update of `watch_interval`, `is_active`, `reason`, `instruction`. `is_active` is independent of `watch_interval`: change `is_active` to pause/resume without losing the configured cadence.- **Delete** (`DELETE /api/v1/watches/{task_id}` or `DELETE /api/v1/watches?to_uri=...`)- **Trigger** (`POST /api/v1/watches/{task_id}/trigger` or `POST /api/v1/watches/trigger?to_uri=...`) — fire-and-forget refresh; returns immediately while the underlying re-ingest runs in the background@@ -65,6 +65,8 @@ curl -X DELETE "http://localhost:1933/api/v1/watches?to_uri=viking://resources/g**Python SDK**+The following uses `SyncHTTPClient`; await each call with `AsyncHTTPClient`.+```pythonwatches = client.list_watches(active_only=True)client.update_watch(to_uri="viking://resources/guide.md", is_active=False)@@ -204,14 +206,14 @@ Getting one task and a successful update return the same task object directly inre-ingestion has completed; read the task again until `last_execution_time` changes, then inspect`last_status` and `last_error`.-**MCP** (agent control plane — minimum closure only)+**MCP**```textlist_watches() # one line per task; URIs only, no task_ids surfacedcancel_watch(to_uri="viking://resources/guide.md") # idempotent removal by URI```-Pause / resume / trigger / update are intentionally not exposed via MCP — those power-user operations live on the CLI/REST surface to keep the agent system prompt compact. Creating a watch or changing its cadence from the agent side still goes through [`add_resource`](02-resources.md#add-resource) with `watch_interval`; pass `to` explicitly or let the system bind to the `root_uri` returned by this import.+Removing a Watch removes its schedule, not the imported resource. MCP exposes listing and removal. To create a Watch, use [`add_resource`](02-resources.md#add-resource) with `watch_interval`. Use the CLI or REST API to pause, resume, trigger, or change the cadence of an existing Watch. Re-importing does not update an existing Watch.---diff --git a/docs/en/api/16-memory.md b/docs/en/api/16-memory.mdindex 50802f092..dc592edf2 100644--- a/docs/en/api/16-memory.md+++ b/docs/en/api/16-memory.md@@ -6,117 +6,32 @@ Memory is produced by session commit or explicit extraction, stored in the user| Category | Location | Description ||----------|----------|-------------|-| profile | `user/memories/profile.md` | User profile information |-| preferences | `user/memories/preferences/` | User preferences by topic |-| entities | `user/memories/entities/` | Important entities (people, projects) |-| events | `user/memories/events/` | Significant events |-| identity | `user/memories/identity.md` | Assistant identity and self-introduction |-| soul | `user/memories/soul.md` | Assistant principles, boundaries, style, and continuity |-| cases | `user/memories/cases/` | Trainable and evaluable task cases |-| trajectories | `user/memories/trajectories/` | Reusable operation contracts |-| experiences | `user/memories/experiences/` | Reusable execution insights |-| tools | `user/memories/tools/` | Tool usage knowledge and best practices |-| skills | `user/memories/skills/` | Skill execution knowledge and workflow strategies |--These are the enabled built-in types. Deployments can extend or override them with custom memory templates.+| profile | `viking://user/{user_id}/memories/profile.md` | User profile information |+| preferences | `viking://user/{user_id}/memories/preferences/` | User preferences by topic |+| entities | `viking://user/{user_id}/memories/entities/` | Important entities (people, projects) |+| events | `viking://user/{user_id}/memories/events/` | Significant events |+| identity | `viking://user/{user_id}/memories/identity.md` | Assistant identity and self-introduction |+| soul | `viking://user/{user_id}/memories/soul.md` | Assistant principles, boundaries, style, and continuity |+| cases | `viking://user/{user_id}/memories/cases/` | Trainable and evaluable task cases |+| trajectories | `viking://user/{user_id}/memories/trajectories/` | Reusable operation contracts distilled from agent task trajectories |+| experiences | `viking://user/{user_id}/memories/experiences/` | Reusable execution insights |+| tools | `viking://user/{user_id}/memories/tools/` | Tool usage knowledge and best practices |+| skills | `viking://user/{user_id}/memories/skills/` | Skill execution knowledge and workflow strategies |++These are the bundled types. `tools` and `skills` are disabled by default; extraction also depends on the effective memory policy and Agent Evolution settings. The table shows Self paths. Peer-enabled types can also be stored under `viking://user/{user_id}/peers/{peer_id}/memories/`. Deployment templates can extend or override the registry; the account template API permits only its documented fields and types.----## API Reference--### recall()--> **Deprecated**: `/api/v1/search/recall` is now a thin preset over [`/api/v1/search/search` with `mode="context"`](06-retrieval.md#search-mode-context) and carries no assembly logic of its own. New integrations should target the context face directly; the v1 field aliases are accepted only here and will be removed in the next minor release. Responses carry a `Deprecation: true` header.--Search each memory type independently and assemble a bounded memory block that can be injected directly into Agent context. Relative to the context face, `/recall` overlays `purpose="coding"`, the v1-compatible `score_threshold=0.1`, `dedup_turns=5` when a `session_id` is present, and `query_expansion="auto"`. Coding Agent plugins explicitly send `score_threshold=0.35`; the public `/recall` default remains `0.1` so an unchanged request does not silently lose results after upgrading. Omitting `quotas` keeps v1's bucket defaults (`events=10, entities=10, preferences=3, experiences=0`); sending `"quotas": null` explicitly opts into the `purpose` preset ratios instead.--**v1 field folding**+## Memory Recall-| v1 field | Folds into | Notes |-|----------|------------|-------|-| `max_chars` | `max_tokens = max_chars / 4` | `6500` → `1625`; an explicit `max_tokens` wins |-| `min_score` | `score_threshold` | When neither is sent, the v1-compatible default `0.1` applies |-| `render: true` | No `detail` pin | Default behavior: each category takes its default tier |-| `render: false` | Returns `entries` only, `rendered` empty | |-| `render: "compact"` | `detail="abstract"` | The prototype-era compact mode; pins every category |-| v1 `quotas` keys | Overlaid on the v1 bucket defaults | Key names unchanged; a partial map keeps the other buckets |--Context-face parameters (`max_tokens`, `detail`, `dedup_turns`, `session_id`, `query_expansion`, `exclude_uris`, `purpose`, `rewrite`, `rewrite_max_bullets`) are also accepted here, so plugins can transition smoothly on deployments that have not been upgraded yet.--**HTTP API**+Use [`search(mode="context")`](06-retrieval.md#search-mode-context) to retrieve memories and assemble an injection-ready block. The server MCP exposes the same operation as `search(mode="context")`; there is no separate `recall` tool.```httpPOST /api/v1/search/recallContent-Type: application/json```-```bash-curl -X POST http://localhost:1933/api/v1/search/recall \- -H "Content-Type: application/json" \- -H "Authorization: Bearer $OPENVIKING_API_KEY" \- -d '{- "query":"API documentation preferences",- "quotas":{"events":5,"entities":5,"preferences":3,"experiences":2},- "max_chars":6500,- "peer_scope":"all"- }'-```--**MCP**--```text-recall(- query="API documentation preferences",- quotas={"events": 5, "entities": 5, "preferences": 3, "experiences": 2},- max_chars=6500,- peer_scope="all"-)-```--**Response**--The response shape matches the context face (flat entries, flat XML in `rendered`):--```json-{- "status": "ok",- "result": {- "entries": [- {- "uri": "viking://user/default/memories/preferences/api-docs.md",- "category": "preferences",- "score": 0.82,- "detail": "full",- "text": "User prefers API docs to show HTTP, SDK and CLI examples together.",- "origin": "self"- }- ],- "rendered": "<memory uri=\"viking://user/default/memories/preferences/api-docs.md\" type=\"preferences\" score=\"0.82\" detail=\"full\">\nUser prefers API docs to show HTTP, SDK and CLI examples together.\n</memory>",- "digest": "",- "stats": {- "quotas": {"events": 5, "entities": 5, "preferences": 3, "experiences": 2},- "candidates": 4,- "returned": 1,- "dropped": 0,- "max_tokens": 1625,- "used_tokens": 96,- "tier_counts": {"full": 1},- "peer_scope": "all",- "origins": {"actor_peer": 0, "self": 1, "other_peer": 0},- "deprecated": {- "endpoint": "/api/v1/search/recall",- "successor": "/api/v1/search/search",- "successor_body": {"mode": "context"},- "aliases_used": ["max_chars"]- }- }- }-}-```--See [Retrieval - search(mode="context")](06-retrieval.md#search-mode-context) for field meanings. Shape changes relative to v1: `type` → `category`, `mode` → `detail`, `content`/`summary` → `text`, `rendered` moves from three-level nesting to flat `<memory>` tags, and `rank` is no longer returned.--The public Python, TypeScript, Go SDKs and the `ov` CLI do not wrap this endpoint yet, so this section shows only the HTTP tab plus the MCP call that does exist.+`/api/v1/search/recall` is deprecated. It is a preset over `search(mode="context")` with `purpose="coding"` and the v1 defaults, kept for existing callers; responses carry a `Deprecation: true` header. Do not use it for new integrations.## Related Documentationdiff --git a/docs/en/api/17-tasks.md b/docs/en/api/17-tasks.mdindex 0fecd9ee1..341be0512 100644--- a/docs/en/api/17-tasks.md+++ b/docs/en/api/17-tasks.md@@ -150,10 +150,14 @@ Request `GET /api/v1/tasks/{task_id}?include_events=true` to also receive `resulHistory retains at most 64 events and 32 KiB of serialized event data. Older entries are removed first, `dropped_count` counts removed entries, and retained sequence numbers are not reset. Events expire with the task. Legacy tasks return `execution_events: null`; if an active legacy task later emits an event, `started_mid_task` is true. No earlier events are reconstructed. An older server can omit the field even when requested. Studio explains these cases and retains task metadata, results and errors.+::: details Extending events and downgrade compatibility+To instrument another execution point, register its kind in `openviking/service/task_events.py`, add Studio translations, and call `await tracker.record_event(task_id, kind, account_id=..., user_id=..., operation=...)`. This internal API records a fact without changing status or stage; it accepts bounded operation identifiers, not arbitrary log payloads. Existing lifecycle methods automatically record their accepted transitions.Persisted task files now contain `execution_events`. Rolling back requires a version that preserves unknown task fields (commit `a5166386` or later); older readers may reject these files. Rolling back also stops event reporting, so history for tasks active during a downgrade may be incomplete.+:::+**Response Example (completed)**```json@@ -205,6 +209,8 @@ Repeated cancellation of a task in `cancelling` or `cancelled` is idempotent.**Supported Task Types:**- `add_resource`+- `add_skill`+- `compile`- `session_commit`- `admin_reindex`- `snapshot_restore_reindex`@@ -311,7 +317,12 @@ List background tasks visible to the current caller, supporting filtering by typ| status | str | No | None | Filter by task status: `pending`, `running`, `cancelling`, `completed`, `failed`, `cancelled` || resource_id | str | No | None | Filter by task resource ID, for example a session ID || include_internal | bool | No | false | Include internal child tasks created by Connector imports |-| limit | int | No | 50 | Maximum number of task records to return |+| limit | int | No | 50 | Maximum records per response, 1–200 |+| pagination | str | No | None | HTTP-only; `cursor` returns a paginated result object |+| cursor | str | No | None | HTTP-only; continuation token from `next_cursor`, used with `pagination=cursor` |+| q | str | No | None | HTTP-only, cursor mode; case-insensitive substring match on task ID and Compile request `skill`, `to`, and `from` |++With `pagination=cursor`, `result` contains `items`, `has_more`, and `next_cursor` instead of an array. Pass `next_cursor` unchanged on the next request and keep the same filters and identity. Without cursor mode, `q` and `cursor` do not affect the result.By default, only user-visible tasks are returned. Pass `include_internal=true` when diagnosing a Connector import to include its internal `add_resource` child tasks.diff --git a/docs/en/api/18-observer.md b/docs/en/api/18-observer.mdindex 4816e4184..997b9a1c9 100644--- a/docs/en/api/18-observer.md+++ b/docs/en/api/18-observer.md@@ -172,7 +172,7 @@ The field describes only a pure-dense vector score. Sparse fusion, time decay, r#### 1. API Implementation Overview-Get aggregated model subsystem status (VLM, embedding, rerank). Checks if each model provider is healthy and available.+Get the current account’s VLM and embedding configuration and token-usage information. `is_healthy` is true when the observer resolves that account’s model information without an error; it does not probe every provider. Use `/ready` for the embedding connectivity probe and inspect actual request errors for other models.**Code Entry Points**:- `openviking/server/routers/observer.py:observer_models` - HTTP route@@ -236,7 +236,7 @@ ov observer models"name": "models","is_healthy": true,"has_errors": false,- "status": "provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ..."+ "status": "Account: default\nEmbedding dimension: 1024\nNo model usage data available."}}```@@ -252,7 +252,6 @@ Get distributed lock system status.**Code Entry Points**:- `openviking/server/routers/observer.py:observer_lock` - HTTP route- `openviking/service/debug_service.py:ObserverService.lock` - Core implementation-- `openviking/storage/observers/lock_observer.py` - Lock observer- `crates/ov_cli/src/commands/observer.rs` - CLI command#### 2. Interface and Parameters@@ -294,7 +293,7 @@ The public SDKs and CLI do not currently expose a lock-specific observer method.#### 1. API Implementation Overview-Get retrieval quality metrics.+Get recorded query counts, result counts, scores, rerank use, and latency. These are diagnostic statistics, not a relevance evaluation. Empty results are valid and do not make the component unhealthy.**Code Entry Points**:- `openviking/server/routers/observer.py:observer_retrieval` - HTTP route@@ -396,7 +395,7 @@ ov observer filesystem#### 1. API Implementation Overview-Get overall system status, including all components (queue, vikingdb, models, lock, retrieval).+Get overall system status, including all components (queue, vikingdb, models, lock, retrieval, filesystem).**Code Entry Points**:- `openviking/server/routers/observer.py:observer_system` - HTTP route@@ -488,6 +487,12 @@ ov observer system"is_healthy": true,"has_errors": false,"status": "..."+ },+ "filesystem": {+ "name": "filesystem",+ "is_healthy": true,+ "has_errors": false,+ "status": "..."}}}diff --git a/docs/en/api/19-agent-evolution.md b/docs/en/api/19-agent-evolution.mdindex 128bcdda7..af6950f66 100644--- a/docs/en/api/19-agent-evolution.md+++ b/docs/en/api/19-agent-evolution.md@@ -1,6 +1,6 @@# Agent Evolution-The Agent Evolution API reports trajectories that consumed a specific Experience and their outcome distribution. These operations are currently available through HTTP only.+The Agent Evolution API reports trajectories linked to a successful read of a specific Experience and their outcome distribution. These operations are currently available through HTTP only. A read establishes the link; it does not prove that the Agent followed the Experience or that the Experience caused an outcome.## API Reference@@ -64,7 +64,7 @@ Each item contains only the indexed fields that are present among `uri`, `name`,### Get Experience outcome distribution-Count trajectories that consumed the specified Experience across the five supported outcomes. The query uses exact scalar-tag aggregation and does not load every trajectory file.+Count trajectories linked to reads of the specified Experience across the five supported outcomes. The query uses exact scalar-tag aggregation and does not load every trajectory file.**Code Entry Points**:diff --git a/docs/en/api/20-webdav.md b/docs/en/api/20-webdav.mdindex 901c7605c..161ba6d19 100644--- a/docs/en/api/20-webdav.md+++ b/docs/en/api/20-webdav.md@@ -4,7 +4,7 @@ WebDAV provides file-protocol access to the `resources` namespace.**Code entry point**: `openviking/server/routers/webdav.py`-## WebDAV (Phase 1)+## Supported operationsOpenViking Server also exposes a minimal WebDAV adapter for resource files:@@ -12,7 +12,7 @@ OpenViking Server also exposes a minimal WebDAV adapter for resource files:/webdav/resources```-Phase 1 intentionally keeps the scope narrow:+The adapter supports the following scope:- Resources only. Memories, skills, sessions, and other namespaces are not exposed.- Text-first writes. `PUT` currently accepts UTF-8 text content only.@@ -43,7 +43,7 @@ Except for `OPTIONS`, WebDAV requests use the same authentication headers as oth| Header | Methods | Required | Description ||--------|---------|----------|-------------|-| `X-API-Key` | All except `OPTIONS` | Yes | OpenViking API key |+| `X-API-Key` | All except `OPTIONS` | Depends on auth mode | OpenViking API key; trusted mode may also require identity headers || `Depth` | `PROPFIND` | No | `0` returns only the target; other values use one level || `Destination` | `MOVE` | Yes | Target path below `/webdav/resources` || `Overwrite` | `MOVE` | No | Defaults to `T`; set `F` to preserve an existing target |diff --git a/docs/en/api/22-openviking-assets.md b/docs/en/api/22-openviking-assets.mdindex 4821958af..2756e37c6 100644--- a/docs/en/api/22-openviking-assets.md+++ b/docs/en/api/22-openviking-assets.md@@ -114,7 +114,7 @@ POST /api/v1/openviking-assets/preflightThis endpoint runs read-only `git ls-remote` in the OpenViking Server executionenvironment to verify that a repository and optional ref are readable. It does-not clone the repository, create a resource, or start a task. Manifest mode+not clone the repository, create a resource, or start a task. With `commit`, preflight checks repository access through HEAD; the import pipeline verifies that exact SHA during fetch/checkout. Manifest modecalls it during both dry-run and pre-submission validation.### Request body@@ -125,6 +125,7 @@ calls it during both dry-run and pre-submission validation.| `connector` | string | Yes | Must currently be `git` || `repo_url` | string | Yes | Git clone URL || `branch` | string | No | Branch or tag to verify; the remote `HEAD` is checked when omitted |+| `commit` | string | No | Full 40-character hexadecimal commit SHA; mutually exclusive with `branch` || `auth_config.username` | string | No | HTTP Basic username; defaults to `oauth2` || `auth_config.token` | string | No | One-shot Git token; never persisted |diff --git a/docs/en/api/23-agent-runtime.md b/docs/en/api/23-agent-runtime.mdindex 56e01d44a..95bc48803 100644--- a/docs/en/api/23-agent-runtime.md+++ b/docs/en/api/23-agent-runtime.md@@ -22,6 +22,8 @@ Agent Runtime Server executes Agent tasks and currently supports Compile. ApplicThe entire `args` object is optional, and the model endpoint ID is not a top-level field. Use `args.model_name` to select a model; when omitted, the execution backend uses its default model configuration.+The model-selection examples below require a backend that accepts `args.model_name`. When using bundled VikingBot, omit `args` and CLI `--args`; it rejects non-empty arguments. The Python example uses `SyncHTTPClient`; await `compile()` with `AsyncHTTPClient`.+**HTTP API**```http@@ -32,6 +34,7 @@ POST /api/v1/compilecurl -X POST http://localhost:1933/api/v1/compile \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \+ -H "Idempotency-Key: studio-compile-001" \-d '{"from": ["viking://resources/research"],"to": "viking://resources/research-wiki",@@ -157,7 +160,7 @@ To retry creation safely, reuse the same `Idempotency-Key` and request parameter### Get task status-A task is visible only to the principal that created it. A missing task and a task owned by another principal both return `404`.+For ordinary user requests, a task is visible only to its creator; missing tasks and tasks owned by another user return `404`. ROOT queries have separate administrative visibility and cannot cancel tasks.```httpGET /api/v1/tasks/{task_id}diff --git a/docs/en/api/24-vikingbot.md b/docs/en/api/24-vikingbot.mdindex d43c75392..a07393d25 100644--- a/docs/en/api/24-vikingbot.md+++ b/docs/en/api/24-vikingbot.md@@ -80,6 +80,8 @@ compatibility.**CLI**+`ov chat` streams by default through `/chat/stream`.+```bashov chat -m "Summarize my project progress"```diff --git a/docs/en/api/99-api-doc-writing-guide.md b/docs/en/api/99-api-doc-writing-guide.mdindex 665bf0a3e..3093decd9 100644--- a/docs/en/api/99-api-doc-writing-guide.md+++ b/docs/en/api/99-api-doc-writing-guide.md@@ -11,6 +11,15 @@ This document defines the unified structure and writing conventions for API modu- Link to official documentation for external tools and services. Describe only the setup needed here instead of duplicating their manuals.- Before submitting, run `npm run check:docs`, `npm run check:api`, and `npm run docs:build` from `docs/`. Automated checks cover structure and examples, not factual correctness or translation quality.+## Editorial Standards++- Start with what the API does, its prerequisites, and the result. Explain implementation details after the reader can decide what to do next.+- Use concrete actions and objects. Avoid vague claims about intelligence, transformation, or seamless workflows, and preserve conditions when shortening prose.+- Do not promise unmeasured quality, performance, costs, or security. Verify defaults, supported behavior, and failures against the implementation; label illustrative values.+- Distinguish accepted from completed, optional from required, and implemented from planned. Keep the overview, parameter tables, examples, and troubleshooting consistent.+- Write natural prose in each language while preserving the same facts and limits; avoid word-for-word translation.+- Preserve useful section links. Check old anchors when changing headings and add compatibility anchors where needed.+## Directory StructureAPI documentation is organized by module, with one file per module, using a two-digit numerical prefix.@@ -32,14 +41,9 @@ Brief introduction explaining the main features and purpose of this module.### API Method Name 1-#### 1. API Implementation Introduction+#### 1. Purpose and Prerequisites-Explain the purpose of this API, point to the corresponding code entry, and briefly describe the principles and workflow.--**Code Entry**:-- `openviking/<module>/<file>.py:<ClassName>.<MethodName>` - Core implementation-- `openviking/server/routers/<router-file>.py` - HTTP router-- `crates/ov_cli/src/commands/<command-file>.rs` - CLI command+Explain what the operation does, when to use it, and the required permissions or existing resources.#### 2. Interface and Parameter Description@@ -101,6 +105,10 @@ Explain the purpose of this API, point to the corresponding code entry, and brieEvery public operation must document its successful return value. JSON endpoints need at least one response-envelope example that matches the implementation. Non-JSON endpoints such as file downloads, SSE, and WebDAV must document the HTTP status, important response headers, body, or event format. A prose-only list of returned fields is not sufficient. Error and exception examples remain optional.+#### 5. Implementation Details (Optional)++Explain the processing steps and link to the implementation, router, or CLI handler when these help readers understand behavior or troubleshoot a failure.+---### API Method Name 2@@ -125,18 +133,13 @@ Every public operation must document its successful return value. JSON endpoints### API Reference Section-Each API is organized in the following three parts:--#### 1. API Implementation Introduction+Use the following sections for each API. Add implementation details after the response contract when they help explain behavior. Existing pages still use the legacy `API Implementation Overview` section with code entries; follow this structure for new pages and when migrating a page.-- Explain the purpose of this API-- Provide code entry paths for readers to reference the source code-- Briefly describe the implementation principles and processing workflow+#### 1. Purpose and Prerequisites-**Code Entry Notes**:-- Core implementation: points to the main business logic code-- HTTP router: points to the FastAPI route definition-- CLI command: points to the CLI command implementation (if available)+- Explain the operation and its intended use.+- State required permissions, configuration, and existing resources.+- Describe effects that matter before calling it, including replacement or deletion of existing data.#### 2. Interface and Parameter Description@@ -159,8 +162,8 @@ Example tabs are generated from bold labels. Put each invocation label in its owparagraph and use one of these fixed base forms: `**Python SDK**`, `**TypeScript SDK**`,`**Go SDK**`, `**HTTP API**`, or `**CLI**`. When a transport qualifier is useful,put it inside the same bold label with ASCII parentheses, for example-`**Python SDK (HTTP)**`. Do not put the qualifier after the bold label-or use full-width parentheses. Show only surfaces that are actually+`**Python SDK (HTTP)**`. Do not put the qualifier after the bold label or use+full-width parentheses. A label such as `**Python HTTP SDK**` does not match the tab matcher and renders as plain text. Show only surfaces that are actuallyimplemented. If an SDK or CLI does not expose the capability, omit that tab andbriefly identify the available alternative. Do not wrap a handwritten HTTP requestand present it as a nonexistent SDK method.@@ -179,24 +182,10 @@ adding language-owned sections to API module pages.````markdown### add_resource()-#### 1. API Implementation Introduction+#### 1. Purpose and PrerequisitesAdd resources to the knowledge base, supporting various sources such as local files, directories, URLs, etc.-**Processing Workflow**:-1. Identify resource type (local file/directory/URL)-2. Call corresponding parser to parse content-3. Build directory tree and write to AGFS-4. Asynchronously generate L0/L1 semantic abstracts-5. Build vector index--**Code Entry**:-- `sdk/python/openviking_sdk/client.py:AsyncHTTPClient.add_resource()` - Async SDK entry-- `sdk/python/openviking_sdk/client.py:SyncHTTPClient.add_resource()` - Sync SDK entry-- `openviking/service/resource_service.py:ResourceService.add_resource()` - Core implementation-- `openviking/server/routers/resources.py:add_resource()` - HTTP router-- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - CLI handler-#### 2. Interface and Parameter Description**Parameters**@@ -204,14 +193,14 @@ Add resources to the knowledge base, supporting various sources such as local fi| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| path | str | Yes | - | Local path, directory path, or URL |-| to | str | No | None | Target Viking URI (must be within the resources scope) |+| to | str | No | None | Final resource URI; an existing target is replaced || reason | str | No | "" | Reason for adding this resource || wait | bool | No | False | Whether to wait for semantic processing completion |**Notes**- SDK/CLI can directly pass local paths; raw HTTP requires `temp_upload` first-- When `to` is specified and the target already exists, an incremental update process is used+- An existing `to` target is replaced. For a directory, files absent from the new import may be removed; unchanged content is reused for semantic and vector processing. Use `parent` to add a new resource below an existing directory.#### 3. Usage Examples@@ -253,20 +242,35 @@ print(client.get_task(result["task_id"]))ov add-resource ./documents/guide.md --reason "User guide documentation"```-**Response Example**+#### 4. Response Contract```json{"status": "ok","result": {"status": "success",- "root_uri": "viking://resources/documents/guide.md",- "task_id": "uuid-xxx",- "errors": []+ "root_uri": "viking://resources/guide",+ "task_id": "uuid-xxx"}}```+#### 5. Implementation Details++**Processing Workflow**:+1. Identify resource type (local file/directory/URL)+2. Call corresponding parser to parse content+3. Build directory tree and write to AGFS+4. Asynchronously generate L0/L1 semantic abstracts+5. Build vector index++**Code Entry**:+- `sdk/python/openviking_sdk/client.py:AsyncHTTPClient.add_resource()` - Async SDK entry+- `sdk/python/openviking_sdk/client.py:SyncHTTPClient.add_resource()` - Sync SDK entry+- `openviking/service/resource_service.py:ResourceService.add_resource()` - Core implementation+- `openviking/server/routers/resources.py:add_resource()` - HTTP router+- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - CLI handler+---````@@ -274,7 +278,7 @@ ov add-resource ./documents/guide.md --reason "User guide documentation"When adding or modifying API documentation, please check:-- [ ] Implementation introduction is clear and code entry paths are correct+- [ ] Purpose, prerequisites, and effects are clear; any code entry paths are correct- [ ] Parameter table is complete and accurate- [ ] Example code is concise and runnable- [ ] Invocation examples use fixed bold labels and every SDK/CLI tab maps to a real implementationdiff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex 5c0ac45a3..13101dac1 100644--- a/docs/zh/api/01-overview.md+++ b/docs/zh/api/01-overview.md@@ -91,20 +91,18 @@ const results = await client.search("部署文档", {它与 Python、Go HTTP Client 使用相同的身份请求头和响应信封。更多示例见[`sdk/typescript/README_CN.md`](../../../sdk/typescript/README_CN.md)。-未显式传入 `url` 时,HTTP 客户端会自动从 `ovcli.conf` 读取连接信息。`ovcli.conf` 是 HTTP 客户端和 CLI 共享的配置文件,默认路径 `~/.openviking/ovcli.conf`,也可通过环境变量指定:+Python HTTP 客户端从 `ovcli.conf` 读取连接信息,显式传入的构造参数覆盖对应配置。`ovcli.conf` 是 HTTP 客户端和 CLI 共享的配置文件,默认路径 `~/.openviking/ovcli.conf`,也可通过环境变量指定:```bashexport OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf```-配置文件示例:+使用 user/admin key 的配置文件示例:```json{"url": "http://localhost:1933",- "api_key": "your-key",- "account": "acme",- "user": "alice"+ "api_key": "your-user-or-admin-key"}```@@ -114,8 +112,8 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf|------|------|--------|| `url` | 服务端地址 | (必填) || `api_key` | API Key | `null`(无认证) |-| `account` | 租户级请求的默认账户请求头 | `null` |-| `user` | 租户级请求的默认用户请求头 | `null` |+| `account` | 账户请求头;trusted 和 dev 模式使用,api_key 模式忽略 | `null` |+| `user` | 用户请求头;trusted 和 dev 模式使用,api_key 模式忽略 | `null` || `timeout` | HTTP 请求超时时间(秒) | `60.0` || `output` | 默认输出格式:`"table"` 或 `"json"` | `"table"` |@@ -161,7 +159,7 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \#### CLI 模式-OpenViking CLI 的命令是 `ov`(通过 `npm install -g @openviking/cli` 安装),连接到 OpenViking 服务端,将所有操作暴露为 Shell 命令。CLI 同样从 `ovcli.conf` 读取连接信息(与 HTTP 客户端共享)。+OpenViking CLI 的命令是 `ov`(通过 `npm install -g @openviking/cli` 安装),连接到 OpenViking 服务端,提供常用操作的 Shell 命令。CLI 同样从 `ovcli.conf` 读取连接信息(与 HTTP 客户端共享)。基本用法:@@ -209,12 +207,12 @@ ov -o json ls viking://resources/- **Authorization Bearer** 请求头:`Authorization: Bearer your-key` (建议的方式)- **X-API-Key** 请求头:`X-API-Key: your-key`-- 如果服务端未配置 API Key,则跳过认证。+- 只有 dev 模式跳过认证;未设置 `auth_mode` 且未设置 `server.root_api_key` 时自动选择 dev 模式。其他模式(api_key、trusted、OIDC、LDAP)按各自配置解析身份。- `/health` 和 `/ready` 端点始终不需要认证。## 响应格式-所有 HTTP API 响应遵循统一格式:+常规 JSON API 响应遵循以下格式;文件下载、SSE、Metrics 和 WebDAV 使用各接口说明的格式:### 成功响应@@ -300,8 +298,8 @@ JSON 输出 - 错误:### 特殊情况-- **字符串结果**(`read`、`abstract`、`overview`):直接打印原文-- **None 结果**(`mkdir`、`rm`、`mv`):无输出+- Table 模式下,`read`、`abstract`、`overview` 直接打印文本,`mkdir`、`rm`、`mv` 打印操作确认信息。+- JSON 模式下,这些命令按上文的 JSON 格式输出。### 退出码@@ -352,7 +350,7 @@ JSON 输出 - 错误:| 方法 | 路径 | 说明 ||------|------|------|| GET | `/health` | 基础健康检查(无需认证) |-| GET | `/ready` | AGFS、VectorDB 和 API Key 管理器就绪检查(无需认证) |+| GET | `/ready` | AGFS、VectorDB、API Key 管理器和 Embedding 就绪检查(无需认证) || GET | `/api/v1/system/status` | 系统状态 || POST | `/api/v1/system/wait` | 等待后台处理完成 || POST | `/api/v1/system/consistency` | 文件系统与向量索引一致性检查 |@@ -396,7 +394,7 @@ JSON 输出 - 错误:| GET | `/api/v1/content/overview` | 读取概览(L1) || GET | `/api/v1/content/download` | 下载原始文件字节 || POST | `/api/v1/content/write` | 写入内容并刷新语义索引 |-| POST | `/api/v1/content/batch-write` | 执行带前置条件的多文件写入 |+| POST | `/api/v1/content/batch-write` | 写入多个文件并刷新索引 || POST | `/api/v1/content/set_tags` | 设置检索标签 || POST | `/api/v1/content/reindex` | 重建语义或向量索引 |@@ -554,9 +552,9 @@ JSON 输出 - 错误:----## 文档阅读计划+## 按任务查找接口-左侧导航按职责而不是按历史文件体积组织:+按操作类型选择对应文档:| 分组 | 适合查找的内容 ||------|----------------|diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.mdindex 2daac93d1..a386fe06c 100644--- a/docs/zh/api/02-resources.md+++ b/docs/zh/api/02-resources.md@@ -1,6 +1,6 @@# 资源管理-资源是智能体可以引用的外部知识。本模块提供资源的添加、导入/导出、临时文件上传等功能。+资源是智能体可以引用的外部知识。本页介绍资源导入、定时更新和临时文件上传。数据包导出与导入见 [OVPack](14-ovpack.md)。## 核心概念@@ -8,7 +8,8 @@OpenViking 支持多种资源类型,按照功能分类如下:-文档类+**文档类**+| 类型 | 扩展名 | 说明 ||------|--------|------|| PDF | `.pdf` | 支持本地解析和 MinerU API 转换 |@@ -18,13 +19,15 @@ OpenViking 支持多种资源类型,按照功能分类如下:| 纯文本 | `.txt`, `.text` | 直接导入处理 || EPUB | `.epub` | 基于 anydoc 将电子书内容和嵌入图片转换为 Markdown |-表格类+**表格类**+| 类型 | 扩展名 | 说明 ||------|--------|------|| Excel | `.xlsx`, `.xls`, `.xlsm`, `.xlsb`, `.ods`, `.csv` | 基于 anydoc 按工作表转换为 Markdown 表格 || PowerPoint | `.pptx`, `.ppt`, `.pptm`, `.pps`, `.ppsx`, `.ppsm`, `.pot`, `.odp` | 基于 anydoc 按幻灯片提取内容和嵌入图片并转换为 Markdown |-代码类+**代码类**+| 类型 | 资源名 | 说明 ||------|--------|------|| 代码文件 | `*.py`, `*.js`, ... | 支持常见编程语言(Python, JavaScript, Go, Rust, Java 等) |@@ -32,7 +35,8 @@ OpenViking 支持多种资源类型,按照功能分类如下:| Git 代码托管平台 | `https://github.com/{org}/{repo}` | GitHub, GitLab, Bitbucket 等代码托管平台的 URL || Git 代码托管平台上的 raw 文件 | `https://github.com/{org}/{repo}/raw/{branch}/{path}` | GitHub, GitLab, Bitbucket 等代码托管平台的 raw 文件下载 URL |-媒体类+**媒体类**+| 类型 | 资源名 | 说明 ||------|--------|------|| 图片 | `*.jpg`, `*.jpeg`, `*.png`, `*.gif` ... | 多种图片格式,通过 VLM 生成描述(实验特性) |@@ -41,26 +45,29 @@ OpenViking 支持多种资源类型,按照功能分类如下:音视频解析器负责校验并保存原文件。内容理解在后续语义处理阶段执行,默认关闭(`vlm.media.enabled=false`),需启用兼容的供应商和模型;理解支持的格式与大小限制和导入格式不同。这不代表内置了 Whisper 转写或本地关键帧提取流程。详见[音视频配置](../guides/01-configuration.md)。-云文档类+**云文档类**+| 类型 | 说明 ||------|------|| 飞书/Lark | URL 方式,支持 doc/docx、wiki、sheets、bitable、mindnote/mindnotes、Drive 文件和目录集。Wiki 默认仅导入入口文档,设置 `args.feishu_recursive=true` 可递归导入子节点。默认使用 FEISHU_APP_ID 和 FEISHU_APP_SECRET 应用凭证;用户 token 导入可传 `args.feishu_access_token`,用户 token watch 还需传 `args.feishu_refresh_token`,并可选传入 `args.feishu_app_id` / `args.feishu_app_secret`。Mindnote 及 Wiki 中的 Mindnote 要求本次使用的 token 具备 `mindnote:node:read` |-网页类(递归网页爬虫)+**网页类(递归网页爬虫)**+| 类型 | 资源名 | 说明 ||------|--------|------|| 单页 / 递归抓取 | `https://host/path` | 默认仅抓入口页;设置 `args.depth > 0` 后,沿同域链接 BFS 递归展开,`args.max_pages` 只限制最多收集的页面数。每页用 trafilatura 抽成 Markdown。可选 `args`:`depth`、`max_pages`、`include_paths`、`exclude_paths`、`allow_external_links`、`skip_download_links`。页面中发现的下载链接默认跳过(`skip_download_links=true`),避免导入 `llms.txt` 等 sidecar 文件造成重复;设为 `false` 时会下载同域文件链接,并计入 `max_pages`。`include_paths`/`exclude_paths` 按**路径前缀**匹配(例如 `/docs/` 仅匹配以 `/docs/` 开头的路径,不会误命中 `/blog/docs-tips`)。|-> 路由说明:`https://host/sitemap.xml`、`https://host/feed.xml`、`*.atom` 等 sitemap-looking URL 和显式 `args.site=true` 让出给下表的整站导入;`https://github.com/{org}/{repo}` 等 Git 托管平台 URL 让出给上文的代码导入。+> 路由说明:`https://host/sitemap.xml`、`https://host/feed.xml`、`*.atom` 等站点索引 URL,以及显式 `args.site=true`,使用下表的站点导入流程;`https://github.com/{org}/{repo}` 等 Git 托管平台 URL 使用上文的代码导入流程。++**网站类(sitemap / RSS / Atom 整站导入)**-网站类(sitemap / RSS / Atom 整站导入)| 类型 | 资源名 | 说明 ||------|--------|------|-| 站点地图 Sitemap | `https://host/sitemap.xml`、`https://host/sitemap-index.xml` | 解析 sitemap,将站点所有页面抓取为**一棵资源树**(每页一个子节点),支持嵌套 `<sitemapindex>` 递归。整站只生成一个资源,落在 `viking://resources/<host>`。 |+| 站点地图 Sitemap | `https://host/sitemap.xml`、`https://host/sitemap-index.xml` | 解析 sitemap,在配置限制内将列出的页面抓取为一棵资源树(每页一个子节点),支持嵌套 `<sitemapindex>` 递归。整站只生成一个资源,落在 `viking://resources/<host>`。 || RSS / Atom 订阅源 | `https://host/rss.xml`、`https://host/atom.xml`、`https://host/feed` | 解析 RSS 2.0 / Atom,逐条把文章正文抓成树节点(feed 内含全文则直接使用,省一次抓取)。 || 整站自动发现 | `https://host` + `args.site=true` | 对裸域名/普通页面强制整站导入:自动通过 robots.txt、HTML `<link rel="alternate">` autodiscovery、常见路径发现 sitemap/RSS,再整站抓取。 |-抓取**有界、非递归**(不会超出所列页面继续爬),受 `parsers.webfeed` 配置约束(`max_pages`、`max_concurrency`、`politeness_delay`、`same_host_only`、`respect_robots`、`max_depth`),并遵守 robots.txt。对 sitemap/feed URL 设置 `watch_interval` 即可让**整站**周期刷新:每次运行自动纳入新增页面、移除已删除页面。添加单个首页(未带 `args.site`)时,返回信息可能附带一行"整站导入"提示——**只提示,绝不自动爬全站**。+抓取**有界、非递归**(不会超出所列页面继续爬),受 `parsers.webfeed` 配置约束(`max_pages`、`max_concurrency`、`politeness_delay`、`same_host_only`、`respect_robots`、`max_depth`),默认遵守 robots.txt(`respect_robots=true`)。对 sitemap/feed URL 设置 `watch_interval` 可定时刷新列表中的页面:每次运行自动纳入新增页面、移除已删除页面。添加单个首页(未带 `args.site`)时,响应可能提示可使用站点导入,但不会因此自动抓取全站。### 资源处理流程@@ -76,7 +83,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector- 使用 `UnifiedResourceProcessor` 根据资源类型解析内容- 支持多种格式:文档(PDF/Markdown/Word)、表格(Excel/PPT)、代码、媒体文件等- 解析结果写入临时 VikingFS 目录-- 媒体文件通过 VLM(视觉语言模型)生成描述+- 媒体解析器校验并保存原文件;启用相应配置后,在语义处理阶段调用 VLM 生成描述#### 阶段 2:资源树构建 (TreeBuilder)- `TreeBuilder.finalize_from_temp()` 扫描临时目录结构@@ -109,7 +116,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector- 调用 `add_resource` 时,为 URL、sitemap、RSS 等可重新读取的来源设置 `watch_interval > 0`(单位:分钟),即可创建监控任务- `temp_file_id` 引用的上传内容是一次性快照,不能创建监控任务。Python HTTP SDK 也会将本地文件/目录上传为快照,因此本地路径不能与 `watch_interval > 0` 组合使用;本地来源变化后请重新添加- 可指定 `to` 参数确定目标 URI;未指定时,系统会使用本次导入返回的 `root_uri` 作为监控目标-- 把监控对象设为 sitemap/RSS/Atom URL,即可让**整站**保持同步:每次刷新重新读取 feed 并重建资源树,新发布的页面自动入库、已删除的页面自动移除+- 把监控对象设为 sitemap/RSS/Atom URL,可定时同步列表中的页面:每次刷新重新读取 feed 并重建资源树,新发布的页面自动入库、已删除的页面自动移除- `WatchManager` 负责任务持久化存储- 支持多租户权限控制(ROOT/ADMIN/USER 权限分级)@@ -168,6 +175,8 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector| to | string | 否 | - | 本次导入的最终保存位置。目标已存在时会覆盖该目标;与 `parent` 互斥 || parent | string | 否 | - | 父级 Viking URI(资源放入此目录下)。与 `to` 互斥 || create_parent | bool | 否 | False | 如果父目录不存在,自动创建父目录(服务端标志) |+| add_type | string | 否 | None | 显式指定 Connector 类型;要求同时传 `path` 和精确的 `to`,不能与 `parent` 或 `temp_file_id` 组合 |+| source_name | string | 否 | None | 来源显示名;上传文件省略时使用原始文件名 || reason | string | 否 | "" | 添加资源的原因;非空时会随资源 URI 进入常规 session 记忆抽取链路,并在生成的记忆中记录资源引用 || instruction | string | 否 | "" | 语义提取的处理指令(实验特性) || wait | bool | 否 | False | 是否等待语义处理和向量化完成才返回 |@@ -178,7 +187,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector| exclude | string | 否 | None | 排除的文件模式(glob) || directly_upload_media | bool | 否 | True | 是否直接上传媒体文件 || preserve_structure | bool | 否 | None | 是否保留目录结构 |-| args | object | 否 | `{}` | 传给特定 parser/accessor 的导入参数。原生 HTTPS Git 导入和 Watch 可通过 `args.auth_config={"username":"oauth2","token":"..."}` 在 TLS 上传递 HTTP Basic 凭据;`username` 默认为 `oauth2`。Git 的 `branch` 或 `commit` 仍放在 `args` 顶层。通过 HTTP(S) URL 导入私有 TOS 对象时,二选一传入非空字符串:`args.tos_signature`(映射为 `X-Tos-Signature`)或 `args.tos_access`(映射为 `X-Tos-Access`)。TOS 凭证只用于当前 HEAD/GET 抓取;资源会先保存为快照,凭证不会写入资源元数据或队列任务。`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` |+| args | object | 否 | `{}` | 传给 Parser/Accessor 的参数,详见下文。核心请求字段不能放入 `args`,下文列出的 Connector 专用选项除外。 || watch_interval | float | 否 | 0 | 定时更新间隔(分钟)。>0 按目标占用规则为可重新读取的来源创建新 Watch;通过 `temp_file_id` 上传的一次性快照不能创建 Watch。≤0 不创建 Watch:原生导入显式指定 `to` 时暂停唯一可访问的任务(存在歧义时返回 409),Connector 导入不影响已有 Watch。显式 `to` 优先,否则绑定本次导入的 `root_uri`。 || is_active | bool | 否 | True | Watch 初始调度状态。设为 `false` 时要求 `watch_interval > 0`,并在 `to`、`parent` 中二选一。`parent` 支持原生飞书 URL 和 Git 导入;Connector 仍要求精确的 `to`。首次导入仍执行一次,随后保持暂停 || processing_mode | string | 否 | `semantic_and_vectors` | 入库后的处理模式。`semantic_and_vectors` 是默认流程:生成语义产物(`.abstract.md`、`.overview.md`)并生成向量。`vectors_only` 跳过语义理解/VLM 总结,只对当前资源文件生成向量 |@@ -187,10 +196,19 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector| acl | object | 否 | None | 设置最终导入根节点的直接 ACL,要求 manage;省略时保留已有权限。见 [ACL API](12-acl.md)。 || telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |+**来源专用参数 `args`**++- 原生 HTTPS Git 导入和 Watch 可通过 `args.auth_config={"username":"oauth2","token":"..."}` 在 TLS 上传递 HTTP Basic 凭据;`username` 默认为 `oauth2`。Git 的 `branch` 或 `commit` 仍放在 `args` 顶层。+- 通过 HTTP(S) URL 导入私有 TOS 对象时,二选一传入非空字符串:`args.tos_signature`(映射为 `X-Tos-Signature`)或 `args.tos_access`(映射为 `X-Tos-Access`)。TOS 凭证只用于当前 HEAD/GET 抓取;资源会先保存为快照,凭证不会写入资源元数据或队列任务。+- `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` 等 `add_resource` 核心字段不能放入 `args`。原生导入也拒绝 `args.exclude`;TOS Connector 导入允许它与 `args.tos_prefix` 一起使用。+**补充说明**:- `to` 和 `parent` 不能同时使用。`to` 是最终保存位置:目标不存在就创建,目标已存在就覆盖该目标;如果目标是目录,目录里本次导入没有生成的旧文件或子目录会被删除。`parent` 是保存目录,适合向已有目录追加新资源;父目录不存在时使用 `create_parent=true` 或 CLI 的 `--parent-auto-create`。当导入后的 `root_uri` 与 `to` 相同时,语义与向量处理会复用未变化内容,只处理变化部分。- 创建新资源要求目标父目录可写;显式更新已有 `to` 要求该目标可写。权限校验在任务入队前完成。自动命名按实际 URI 占用判断,即使同名资源不可读也会选择 `_1`、`_2` 等后缀,而不会尝试覆盖。-- `wait=false` 返回的 `status=accepted` 表示任务已通过预检查并入队,不表示资源处理已经完成;最终状态以对应 `task_id` 为准。+- `wait=false` 时,原生导入入队后返回 `status=success`,Connector 导入返回 `status=accepted`。两者都不表示后台处理已经完成;最终状态以对应 `task_id` 为准。- 如果同时省略 `to` 和 `parent`,服务端会先尝试使用当前用户的 `add_targets.resource_uri` 覆盖配置,再使用 `server.user_config_defaults.add_targets.resource_uri`。两者都没有配置时,保持旧的目标解析行为。- 资源目标可以使用公共 `viking://resources/...`、家目录别名 `viking://~/resources/...`、显式用户 `viking://user/{user_id}/resources/...`,或 peer 级 `viking://user/{user_id}/peers/{peer_id}/resources/...`。家目录别名会按请求身份展开为 canonical 路径;无 uid 的写法 `viking://user/resources/...` 会被拒绝,并提示改用 `viking://~/resources/...`。- `user_id` 和 `peer_id` 路径片段必须是安全的单段标识,例如 `alice` 或 `web-visitor-alice`。包含路径分隔符、`.`、`..`、`:` 或 `+` 的值会被拒绝。@@ -552,7 +570,7 @@ ov add-resource ./documents/guide.md -p viking://resources/docs/{calendar:today}{"status": "ok","result": {- "status": "accepted",+ "status": "success","root_uri": "viking://resources/guide","task_id": "uuid-xxx"}@@ -566,7 +584,7 @@ ov add-resource ./documents/guide.md -p viking://resources/docs/{calendar:today}```Note: Resource is being processed in the background.Use 'ov task status <task_id>' to check progress, or 'ov task list' to see all tasks.-status accepted+status successroot_uri viking://resources/01-overviewtask_id uuid-xxx```@@ -575,9 +593,12 @@ task_id uuid-xxx```json{- "status": "accepted",- "root_uri": "viking://resources/01-overview",- "task_id": "uuid-xxx"+ "ok": true,+ "result": {+ "status": "success",+ "root_uri": "viking://resources/01-overview",+ "task_id": "uuid-xxx"+ }}```@@ -585,15 +606,15 @@ task_id uuid-xxx| 字段 | 类型 | 说明 ||------|------|------|-| `status` | string | 处理状态:`accepted` 表示已入队,`success` 表示成功,`error` 表示失败 |+| `status` | string | 原生导入的入队结果和同步结果都返回 `success`;Connector 提交返回 `accepted`。`wait=false` 时需轮询 `task_id` 确认完成。请求失败通过顶层错误响应返回,后台失败通过任务 API 查询 || `root_uri` | string | 资源在 OpenViking 中的最终 URI || `task_id` | string | (可选,仅当 `wait=false` 时)可轮询 `/api/v1/tasks/{task_id}` 的任务 ID。非 Git 导入用于队列跟踪;Git 仓库导入用于完整后台导入跟踪。 || `temp_uri` | string | 导入过程中生成的临时 URI || `source_path` | string | 原始源文件路径或 URL || `meta` | object | 资源解析过程中的元数据(如文件类型、大小等) || `errors` | array | 处理过程中的错误列表 |-| `warnings` | array | (可选)处理过程中的警告列表(仅在 `strict=False` 时可能出现) |-| `queue_status` | object | (可选,仅当 `wait=true` 时)队列处理状态,包含 `pending`、`processing`、`completed` 计数 |+| `warnings` | array | 可选警告,包括部分处理失败或资源记忆关联失败 |+| `queue_status` | object | 同步等待或已完成任务结果中的队列汇总,按队列返回 `processed`、`requeue_count`、`error_count` 和 `errors` || `memory_linking` | object | (可选,仅当 `reason` 触发记忆生成时)本次资源 URI 与用户记忆的关联结果 |**完成后的资源添加任务结果**diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.mdindex 197353ef7..7a6e125bd 100644--- a/docs/zh/api/03-filesystem.md+++ b/docs/zh/api/03-filesystem.md@@ -4,6 +4,8 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。<a id="webdav"></a><a id="webdav-phase-1"></a>+读取或写入文件正文见[内容 API](12-content.md)。通过 WebDAV 客户端访问文件见 [WebDAV](20-webdav.md)。+## API 参考<a id="abstract"></a><a id="overview"></a><a id="read"></a><a id="write"></a>@@ -31,6 +33,7 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。| sort_by | str | 否 | None | 在分页前,分别按 `name` 或 `mtime` 排序目录组和文件组;目录仍优先 || sort_order | str | 否 | `asc` | 排序方向:`asc` 或 `desc` || extra_fields | list[str] | 否 | None | 额外返回的字段:`locked`、`id`、`count` |+| include_tags | bool | 否 | False | 不按标签过滤时,也返回 tags || tags | string[] | 否 | 未设置 | 仅返回同时匹配全部 `k=v` 检索标签的条目 |`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。L0/L1 内容只附加到分页选中的目录节点,不占用 `node_limit`。显式传入 `include_abstract=true|false` 会覆盖 `output` 隐含的旧行为。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。HTTP 的 `simple=true` 保持仅返回路径;CLI 同时指定 `--simple` 和 `--fields` 时会获取条目对象,再按指定列输出。@@ -173,7 +176,7 @@ CLI 会按所选列请求 `extra_fields`(`locked`、`id`、`count`);选择HTTP 响应中的 `result` 保持为条目数组。`has_more=true` 表示在应用可见性、tags、offset 和 limit 后仍有后续匹配节点;Python、TypeScript 和 Go SDK 继续返回 `result` 数组。CLI 检测到后续节点时会在输出末尾显示翻页提示。-**响应**+**响应(`output=original`、`include_tags=true`)**```json{@@ -216,6 +219,7 @@ HTTP 响应中的 `result` 保持为条目数组。`has_more=true` 表示在应| limit | int | 否 | None | `node_limit` 的别名 || level_limit | int | 否 | 3 | 最大目录遍历深度 || extra_fields | list[str] | 否 | None | 额外返回的字段:`locked`、`id`、`count` |+| include_tags | bool | 否 | False | 不按标签过滤时,也返回 tags || tags | string[] | 否 | 未设置 | 仅保留同时匹配全部 `k=v` 检索标签的节点 |目录过滤和 `tags` 均在 `offset`、`limit` 前应用。L0/L1 内容只附加到分页选中的目录节点,不占用 `node_limit`。显式传入 `include_abstract=true|false` 会覆盖 `output` 隐含的旧行为。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true` 才返回它们。@@ -305,7 +309,7 @@ ov tree viking://resources/my-project/ \与 `ls` 一致,HTTP 响应中的 `result` 保持为节点数组,`has_more` 位于响应顶层。CLI 检测到 `has_more=true` 时会在树输出末尾显示后续节点提示。-**响应**+**响应(`output=original`、`include_tags=true`)**```json{@@ -430,9 +434,9 @@ ov stat viking://resources/my-project/docs}```-`isLocked` 字段反映路径当前是否被路径锁持有:路径自身存在有效锁(包括目标路径对应的 exact-path lock),或者任一祖先目录持有 TreeLock。当 LockManager 不可用或查询失败时返回 `false`,调用方可据此避免先写入再观察到 `ResourceBusyError`。+`isLocked` 字段反映路径当前是否被路径锁持有:路径自身存在有效锁(包括目标路径对应的 exact-path lock),或者任一祖先目录持有 TreeLock。当 LockManager 不可用或查询失败时返回 `false`。这只是状态查询,不会预留锁;查询后仍可能有其他写入者取得锁,写入时仍需处理 `ResourceBusyError`。-`id` 字段(仅文件)是 VikingDB 中向量记录的确定性主键,对 level 2(常规文件)记录按 `md5(f"{account_id}:{uri}")` 计算。该值与向量集合 schema 中的 `id` 字段一致,可用于直接交叉引用向量记录而无需额外查询。目录不返回此字段,因为一个目录在多个语义层(L0 abstract、L1 overview、L2)下可能对应多条向量记录,id 不唯一。由于索引是异步生成的,新返回的 ID 可能暂时无法解析;对应向量记录被删除后,按 ID 查询也会失败。这两种情况下,`stat(id)` 都会返回 `NOT_FOUND`,并在原因中提示数据可能尚未索引或已经删除。+`id` 字段(仅文件)是 VikingDB 中向量记录的确定性主键,对 level 2(常规文件)记录按 `md5(f"{account_id}:{uri}")` 计算。该值与向量集合 schema 中的 `id` 字段一致,可用于直接交叉引用向量记录而无需额外查询。目录不返回此字段,因为一个目录在多个语义层(L0 abstract、L1 overview)下可能对应多条向量记录,id 不唯一。由于索引是异步生成的,新返回的 ID 可能暂时无法解析;对应向量记录被删除后,按 ID 查询也会失败。这两种情况下,`stat(id)` 都会返回 `NOT_FOUND`,并在原因中提示数据可能尚未索引或已经删除。`count` 字段(仅目录)包含该目录下的项目(文件和子目录)估计数量(来自向量索引)。@@ -501,7 +505,7 @@ ov attrs set-tags viking://resources/docs/api.md --tags team=search,env=prodov attrs set-tags viking://resources/docs --tags team=search --mode append --recursive```-目录目标会更新目录语义记录;`recursive=true` 还会更新已有子文件和子目录语义记录。+`set-tags` 的目录目标会更新目录语义记录;`recursive=true` 还会更新已有子文件和子目录语义记录。**响应(Resource)**@@ -619,13 +623,15 @@ ov mkdir viking://resources/new-project/ --description "接口文档目录"删除文件或目录。递归删除目录时会返回删除的项目估计数量。`rm` 是幂等操作:删除一个合法但不存在的 URI 仍会成功。-URI 格式非法、scheme 不支持或使用非公开作用域时返回 `INVALID_URI`。+URI 格式非法、scheme 不支持,或使用 `temp`、`queue` 等内部作用域时返回 `INVALID_URI`。**参数**| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| uri | str | 是 | - | 要删除的 Viking URI |+| wait | bool | 否 | False | 等待删除后的语义刷新完成 |+| timeout | float | 否 | None | `wait=true` 时的刷新超时,单位秒 || recursive | bool | 否 | False | 递归删除目录 |diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.mdindex 1f9fc6283..d65b08a9d 100644--- a/docs/zh/api/04-skills.md+++ b/docs/zh/api/04-skills.md@@ -161,7 +161,7 @@ This tool wraps the MCP tool `search-web`. Call this when the user needs functio#### 1. API 实现介绍-技能是一种特殊的资源,用于定义智能体可以执行的操作或工具。+此接口存储 Skill 指令和配套文件,并生成供检索使用的摘要与索引。它不会执行 Skill 或注册工具。**处理流程**:1. 接收技能数据或上传的临时文件@@ -411,7 +411,7 @@ ov skills add ./skills/code-runner/ -p viking://agent/skills --waitov task status TASK_ID# 使用 JSON 输出格式-ov add-skill ./skills/my-skill/ -o json+ov -o json add-skill ./skills/my-skill/```**响应示例**:@@ -446,12 +446,15 @@ task_id uuid-xxx**CLI 响应(JSON 格式,使用 -o json)**:```json{- "status": "success",- "root_uri": "viking://user/alice/skills/my-skill",- "uri": "viking://user/alice/skills/my-skill",- "name": "my-skill",- "auxiliary_files": 2,- "task_id": "uuid-xxx"+ "ok": true,+ "result": {+ "status": "success",+ "root_uri": "viking://user/alice/skills/my-skill",+ "uri": "viking://user/alice/skills/my-skill",+ "name": "my-skill",+ "auxiliary_files": 2,+ "task_id": "uuid-xxx"+ }}```@@ -517,7 +520,10 @@ console.log(skills);```goskills, err := client.ListSkills(ctx, nil)-_ = skills+if err != nil {+ return err+}+fmt.Println(skills)```**HTTP API**:@@ -568,7 +574,10 @@ skill, err := client.GetSkill(ctx, "search-web", &openviking.GetSkillOptions{IncludeContent: openviking.Bool(true),IncludeFiles: openviking.Bool(true),})-_ = skill+if err != nil {+ return err+}+fmt.Println(skill)```**HTTP API**:@@ -665,7 +674,10 @@ console.log(skills);results, err := client.FindSkills(ctx, "search the internet", &openviking.FindSkillsOptions{Limit: 5,})-_ = results+if err != nil {+ return err+}+fmt.Println(results)```**HTTP API**:@@ -730,8 +742,15 @@ validated, err := client.ValidateSkill(ctx, map[string]any{"name": "search-web","description": "...",}, nil)+if err != nil {+ return err+}+fmt.Println(validated)updated, err := client.UpdateSkill(ctx, "search-web", "./skills/search-web", nil)-_, _ = validated, updated+if err != nil {+ return err+}+fmt.Println(updated)```**HTTP API**:@@ -794,7 +813,10 @@ await client.deleteSkill("my-skill");```godeleted, err := client.DeleteSkill(ctx, "old-skill")-_ = deleted+if err != nil {+ return err+}+fmt.Println(deleted)```**HTTP API**:@@ -821,7 +843,7 @@ ov skills remove old-skill -p viking://~/skills --yes### 技能管理响应-列出和搜索都返回 `skills` 数组与 `total`。未指定 `target_uri` 时使用 `root_uris` 表示用户私有与 Agent 共享两个检索根;指定后返回单个 `root_uri`。+列出和搜索都返回 `skills` 数组与 `total`。未指定 `target_uri` 时使用 `root_uris` 表示用户私有与 Agent 共享两个检索根;指定后返回单个 `root_uri`。下面是命中 L0 的搜索响应;列表响应中的 URI 指向包根,且不包含检索分数。```json{@@ -835,7 +857,7 @@ ov skills remove old-skill -p viking://~/skills --yes{"type": "skill","name": "search-web",- "uri": "viking://user/default/skills/search-web",+ "uri": "viking://user/default/skills/search-web/.abstract.md","root_uri": "viking://user/default/skills/search-web","skill_md_uri": "viking://user/default/skills/search-web/SKILL.md","description": "Search the web for current information",@@ -915,6 +937,10 @@ skill = {}```+### 写清执行条件和输出++说明技能适用的任务、需要的工具与依赖、输入和预期输出。给出一个具体例子,以及检查结果的方法。依赖缺失或步骤失败时,也应说明 Agent 下一步怎么做。OpenViking 保存这些指令,实际能调用哪些工具由消费方 Harness 决定。+### 命名一致性建议技能名称使用 kebab-case:diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.mdindex 54274c3aa..188dc07f3 100644--- a/docs/zh/api/05-sessions.md+++ b/docs/zh/api/05-sessions.md@@ -43,7 +43,7 @@ Session API 按认证用户作用域访问会话,并返回 canonical user sess| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| session_id | str | 否 | None | 会话 ID。如果为 None,则创建一个自动生成 ID 的新会话 |-| memory_policy | object | 否 | None | 会话默认的记忆抽取策略。可选的 `self` 和 `peer` 开关控制写入目标;可选的 `working_memory.enabled=false` 跳过 archive summary;可选的顶层 `memory_types` 将抽取限制为指定的 enabled memory schema。包含 `experiences` 时会自动激活 `cases` 和 `trajectories`;不包含 `experiences` 时,显式传入的 `cases` 和 `trajectories` 会被忽略。所有 `enabled` 值都应使用 JSON 布尔值。旧版 boolean-like 值暂时仍兼容(字符串 `"false"` 会正确解析为 false),但会产生弃用警告。未传或为 `null` 时允许所有 enabled memory schema。非法结构或未知 memory type 会以 `InvalidArgumentError` 拒绝。 |+| memory_policy | object | 否 | None | 会话默认的记忆抽取策略。可选的 `self` 和 `peer` 开关控制写入目标;可选的 `working_memory.enabled=false` 跳过 archive summary;可选的顶层 `memory_types` 将抽取限制为指定的 enabled memory schema。包含 `experiences` 时会自动激活 `cases` 和 `trajectories`;不包含 `experiences` 时,显式传入的 `cases` 和 `trajectories` 会被忽略。所有 `enabled` 值都应使用 JSON 布尔值。旧版 boolean-like 值暂时仍兼容(字符串 `"false"` 会正确解析为 false),但会产生弃用警告。`memory_types` 未传或为 `null` 时允许所有 enabled memory schema。非法结构或未知 memory type 会以 `InvalidArgumentError` 拒绝。 || auto_commit_policy | object | 否 | None | 可选的自动 commit 策略(见下表)。传入的字段会被校验并 clamp 到取值范围,然后合并到默认值之上;最终生效的策略会在响应的 `result.auto_commit_policy` 中返回,并持久化到 session meta。省略时,新 Session 先继承 `server.user_config_defaults.auto_commit_policy`,再沿用现有 `memory.session_auto_commit.enabled` 行为。之后可通过 `update_session_config()` 部分更新或禁用该策略。 |`auto_commit_policy` 字段(均为可选;存在 policy 时,未传字段回退到默认值):@@ -56,7 +56,7 @@ Session API 按认证用户作用域访问会话,并返回 canonical user sess| `keep_recent_count` | int | 0 | 500 | 阈值触发的自动 commit 后保留(不归档)的最近 live message 数量。idle 超时触发的 commit 会忽略该值并归档所有消息。 || `min_commit_interval_seconds` | int | 0 | 604800 | 两次自动 commit 之间的最小间隔秒数(节流)。 |-所有字段最小值为 `0`,会被 clamp 到 `[0, 上限]`。未知字段会以 `InvalidArgumentError` 拒绝。+所有字段最小值为 `0`,会被 clamp 到 `[0, 上限]`。未知字段会以 `InvalidArgumentError` 拒绝。idle 超时还要求服务端开启 `memory.session_auto_commit.enabled`;仅设置 `idle_timeout_seconds` 不会启动扫描器。#### 3. 使用示例@@ -461,7 +461,7 @@ curl -X PATCH http://localhost:1933/api/v1/sessions/a1b2c3d4/config \**Python SDK**```python-result = client.update_session_config(+result = await client.update_session_config(session_id="a1b2c3d4",options={"memory_extraction_config": {@@ -688,12 +688,12 @@ curl --get http://localhost:1933/api/v1/sessions/session-id/tool-results/tool-re**返回字段说明**:- `latest_archive_overview`: 最新一个已完成归档的 overview 文本,在 token budget 足够时返回- `pre_archive_abstracts`: 保持 API 向下兼容,返回空数组-- `messages`: 最新已完成归档之后的所有未完成归档消息,再加上当前 live session 消息+- `messages`: 最新已完成归档之后的未完成归档消息和当前 live session 消息,受 token budget 限制- `estimatedTokens`: 预估总 token 数-- `stats`: 统计信息+- `stats`: 统计信息。`includedArchives` 统计 `pre_archive_abstracts` 的条目数,该数组目前为空;是否包含 overview 应查看 `latest_archive_overview` 本身**token budget 分配策略**:-1. 先分配给当前活跃消息+1. 先把待返回消息适配到预算内;必要时丢弃或截断消息,再计算剩余预算2. 剩余预算优先给最新归档的 overview3. pre_archive_abstracts 目前不返回@@ -710,7 +710,7 @@ curl --get http://localhost:1933/api/v1/sessions/session-id/tool-results/tool-re| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| session_id | str | 是 | - | 会话 ID |-| token_budget | int | 否 | 128000 | active messages 之后留给 assembled archive payload 的非负 token 预算 |+| token_budget | int | 否 | 128000 | 整个返回上下文的非负 token 预算;先为消息分配,再用剩余预算容纳归档概览 |#### 3. 使用示例@@ -786,14 +786,14 @@ ov session get-session-context a1b2c3d4 --token-budget 128000"created_at": "2026-03-24T09:10:20Z"}],- "estimatedTokens": 160,+ "estimatedTokens": 29,"stats": {"totalArchives": 2,- "includedArchives": 1,- "droppedArchives": 0,+ "includedArchives": 0,+ "droppedArchives": 2,"failedArchives": 0,- "activeTokens": 98,- "archiveTokens": 62+ "activeTokens": 10,+ "archiveTokens": 19}}}@@ -925,7 +925,7 @@ ov session get-session-archive a1b2c3d4 archive_002#### 1. API 实现介绍-删除会话及其所有数据,包括消息、归档历史、记忆等。删除操作不可逆。+删除该会话目录,包括消息、归档历史和会话内的审计记录。已经抽取到用户或 Peer 记忆目录的长期记忆不会随之删除;需要删除这些记忆时,单独定位并删除对应 URI。此接口不提供自动撤销。**代码入口**:- `openviking/server/routers/sessions.py:delete_session()` - HTTP 路由@@ -1006,6 +1006,7 @@ ov session delete a1b2c3d4**Part 类型**:- `TextPart`: 纯文本内容+- `ImagePart`: OpenAI 风格的图片 URL 内容。记忆提取时,OpenViking 可调用配置的 VLM 将图片转为文字描述- `ContextPart`: 上下文引用,指向资源或记忆- `ToolPart`: 工具调用和结果@@ -1042,6 +1043,9 @@ from openviking_sdk import ContextPart, ImagePart, TextPart, ToolPart# 文本内容TextPart(text="Hello, how can I help?")+# 图片 URL+ImagePart(url="https://example.com/photo.png", detail="auto")+# 上下文引用ContextPart(uri="viking://resources/docs/auth/",@@ -1108,13 +1112,25 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \{"type": "tool", "tool_id": "call_123", "tool_name": "search_web", "tool_input": {"query": "OAuth"}, "tool_status": "completed", "tool_output": "Results..."}]}'++# 添加包含图片 URL 的用户消息+curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "role": "user",+ "parts": [+ {"type": "text", "text": "Remember this studio layout."},+ {"type": "image_url", "image_url": {"url": "https://example.com/studio.png", "detail": "auto"}}+ ]+ }'```**Python SDK**```pythonimport openviking_sdk as ov-from openviking_sdk import ContextPart, TextPart+from openviking_sdk import ContextPart, ImagePart, TextPartclient = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")await client.initialize()@@ -1139,6 +1155,16 @@ await client.add_message(),],)++# Parts 模式:添加包含图片 URL 的用户消息+await client.add_message(+ session_id="a1b2c3d4",+ role="user",+ parts=[+ TextPart(text="Remember this studio layout."),+ ImagePart(url="https://example.com/studio.png", detail="auto"),+ ],+)```**TypeScript SDK**@@ -1184,7 +1210,7 @@ ov session add-message a1b2c3d4 --role user --content "How do I authenticate use#### 1. API 实现介绍-向会话中批量添加多条消息。适用于需要一次性写入大量消息的场景(如历史对话导入、记忆抽取),相比逐条调用 `add_message()` 可显著提升性能。+在一次请求中向会话添加多条消息,适合导入历史对话。与逐条调用 `add_message()` 相比,批量提交可减少请求次数。**与 `add_message()` 的区别**:- `add_message()`:单次请求添加 1 条消息@@ -1302,14 +1328,14 @@ ov add-memory '[{"role":"user","content":"Hello"},{"role":"assistant","content":#### 1. API 实现介绍-提交会话。归档消息(Phase 1)立即完成;有消息被归档时,摘要生成和记忆提取(Phase 2)在后台异步执行。产生归档的 commit 返回 `status: "accepted"` 和 `task_id`;没有可归档内容的 no-op commit 返回 `status: "skipped"` 和 `task_id: null`。+提交会话。归档消息(Phase 1)在响应返回前完成;有消息被归档时,摘要生成和记忆提取(Phase 2)在后台异步执行。产生归档的 commit 返回 `status: "accepted"` 和 `task_id`;没有可归档内容的 no-op commit 返回 `status: "skipped"` 和 `task_id: null`。**两阶段提交流程**:-- **Phase 1(同步)**: 快照当前消息,清空 live session,创建归档目录,写入原始消息+- **Phase 1(同步)**: 按保留策略拆分消息,写入归档和恢复记录,入队 Phase 2,并将保留消息写回 live session- **Phase 2(异步)**: 生成摘要(L0/L1),提取长期记忆并更新关系**注意事项**:-- 同一 session 的多次快速连续 commit 会被接受;每次请求都会拿到独立的 `task_id`+- 同一 session 可连续提交;只有实际产生归档的请求返回独立的 `task_id`,no-op 请求不创建任务- 空 session,或所有消息都仍在 `keep_recent_count` 保留窗口内时,会同步完成并返回 `archived: false`- 后台 Phase 2 会按 archive 顺序串行推进:`archive_N+1` 会等待 `archive_N` 写出 `.done` 后再继续- 如果更早的 archive 已失败且没有 `.done`,后续 commit 会直接返回错误,直到该失败被处理@@ -1331,7 +1357,7 @@ ov add-memory '[{"role":"user","content":"Hello"},{"role":"assistant","content":| keep_recent_count | int | 否 | 0 | 提交后保留为 live 状态的最近消息数 (保持 live, 不归档)。`0` (默认) 归档全部消息。 || reset_context | bool | 否 | false | HTTP API:归档全部 live messages 后追加只含 `.done`(带 `context_reset`)的边界 archive,目录内没有消息文件。保留 session ID 和原始历史,清空注入上下文,并阻止后续摘要继承 reset 前的 overview。要求 `keep_recent_count=0`,且不设置 `retention_mode`。 |-`reset_context` 供 OpenClaw 插件 reset hook 和 `Session.commit_async()` 使用;没有 live messages 时也会创建边界;若最新 archive 已是 reset 边界则不重复创建。旧 archive 的记忆提取可以继续完成,长期记忆保留。本次未增加 SDK/CLI 的专用参数。+`reset_context` 供 OpenClaw 插件 reset hook 和 `Session.commit_async()` 使用;没有 live messages 时也会创建边界;若最新 archive 已是 reset 边界则不重复创建。旧 archive 的记忆提取可以继续完成,长期记忆保留。SDK 和 CLI 没有专用的 `reset_context` 参数,需要时使用 HTTP API。有效策略按 Session `.meta.json`、最新 `settings/user_config.json`、内核默认值的@@ -1364,17 +1390,18 @@ from openviking_sdk import AsyncHTTPClientclient = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")await client.initialize()-# commit 立即返回 task_id,后台异步执行摘要生成和记忆提取+# commit 完成 Phase 1 后返回,摘要生成和记忆提取在后台执行result = await client.commit_session(session_id="a1b2c3d4")print(f"Status: {result['status']}")print(f"Task ID: {result['task_id']}")-# 查询后台任务状态-task = await client.get_task(task_id=result["task_id"])-if task["status"] == "completed":- memories = task["result"]["memories_extracted"]- total = sum(memories.values())- print(f"Memories extracted: {total}")+# 查询一次;若任务仍在等待或运行中,稍后继续查询+task_id = result.get("task_id")+if task_id:+ task = await client.get_task(task_id=task_id)+ print(task["status"])+ if task["status"] == "completed":+ print(task["result"]["memories_extracted"])```**TypeScript SDK**@@ -1387,7 +1414,7 @@ console.log(await client.commitSession("session-id"));```gocommit, err := client.CommitSession(ctx, "a1b2c3d4", &openviking.CommitSessionOptions{- KeepRecentCount: 0,+ KeepRecentCount: openviking.Int(0),})if err != nil {return err@@ -1395,11 +1422,13 @@ if err != nil {fmt.Println(commit["status"], commit["task_id"])taskID, _ := commit["task_id"].(string)-task, err := client.GetTask(ctx, taskID)-if err != nil {- return err+if taskID != "" {+ task, err := client.GetTask(ctx, taskID)+ if err != nil {+ return err+ }+ fmt.Println(task["status"])}-fmt.Println(task["status"])```**CLI**@@ -1445,7 +1474,7 @@ ov session commit a1b2c3d4#### 1. API 实现介绍-立即对已有会话触发一次记忆提取,不会额外创建新的 commit 任务。+对已有会话的当前 live 消息执行记忆提取,等待本次提取结果后返回。它不创建新的 commit 任务,也不替代归档;已归档历史不会作为本次 live 消息重复输入。**代码入口**:- `openviking/server/routers/sessions.py:extract_session()` - HTTP 路由@@ -1474,7 +1503,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/extract \**响应示例**-该接口会直接返回本次提取产生的记忆写入结果列表。列表项的具体结构取决于该会话实际提取出了哪些记忆。+响应的 `result` 是本次提取产生的记忆写入结果列表。列表项的具体结构取决于该会话实际提取出了哪些记忆。<a id="get_task"></a><a id="list_tasks"></a>@@ -1523,23 +1552,23 @@ viking://user/{user_id}/sessions/{session_id}/"operations": {"adds": [{- "uri": "memory/user/xxx/identity.md",- "memory_type": "identity",+ "uri": "viking://user/alice/memories/profile.md",+ "memory_type": "profile","after": "新创建的文件内容"}],"updates": [{- "uri": "memory/user/xxx/context/project.md",- "memory_type": "context",+ "uri": "viking://user/alice/memories/preferences/project.md",+ "memory_type": "preferences","before": "修改前的文件内容","after": "修改后的文件内容"}],"deletes": [{- "uri": "memory/user/xxx/context/old.md",- "memory_type": "context",+ "uri": "viking://user/alice/memories/preferences/old.md",+ "memory_type": "preferences","deleted_content": "被删除的文件内容"}]@@ -1583,56 +1612,68 @@ viking://user/{user_id}/sessions/{session_id}/**Python SDK**```python+import asyncio+from openviking_sdk import AsyncHTTPClient, ContextPart, TextPart# 初始化客户端client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")await client.initialize()-# 创建新会话-session_result = await client.create_session()-session_id = session_result["session_id"]-print(f"Session created: {session_id}")--# 添加用户消息-await client.add_message(- session_id=session_id,- role="user",- content="How do I configure embedding?",-)--# 使用会话上下文进行搜索-results = await client.search(- query="embedding configuration",- session_id=session_id,-)+try:+ # 创建新会话+ session_result = await client.create_session()+ session_id = session_result["session_id"]+ print(f"Session created: {session_id}")-# 添加带有上下文引用的助手回复-resources = results.get("resources", [])-if resources:- resource = resources[0]+ # 添加用户消息await client.add_message(session_id=session_id,- role="assistant",- parts=[- TextPart(text="Based on the documentation, you can configure embedding..."),- ContextPart(- uri=resource["uri"],- context_type="resource",- abstract=resource.get("abstract", ""),- ),- ],+ role="user",+ content="How do I configure embedding?",+ )++ # 使用会话上下文进行搜索+ results = await client.search(+ query="embedding configuration",+ session_id=session_id,)-# 提交会话(立即返回,后台执行摘要生成和记忆提取)-commit_result = await client.commit_session(session_id=session_id)-print(f"Task ID: {commit_result['task_id']}")-# 可选:等待后台任务完成-task = await client.get_task(task_id=commit_result["task_id"])-if task and task["status"] == "completed":- memories = task["result"]["memories_extracted"]- total = sum(memories.values())- print(f"Memories extracted: {total}")+ # 添加带有上下文引用的助手回复+ resources = results.get("resources", [])+ if resources:+ resource = resources[0]+ await client.add_message(+ session_id=session_id,+ role="assistant",+ parts=[+ TextPart(text="Based on the documentation, you can configure embedding..."),+ ContextPart(+ uri=resource["uri"],+ context_type="resource",+ abstract=resource.get("abstract", ""),+ ),+ ],+ )+ # 提交会话;摘要生成和记忆提取在后台执行+ commit_result = await client.commit_session(session_id=session_id)+ print(f"Task ID: {commit_result['task_id']}")++ # 可选:等待后台任务完成+ task_id = commit_result.get("task_id")+ if task_id:+ for _ in range(30):+ task = await client.get_task(task_id=task_id)+ if task and task["status"] == "completed":+ print(task.get("result"))+ break+ if task and task["status"] in {"failed", "cancelled"}:+ raise RuntimeError(task)+ await asyncio.sleep(1)+ else:+ print(f"Still pending: {task_id}; check this task again later")+finally:+ await client.close()```**HTTP API**@@ -1662,13 +1703,13 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \-H "X-API-Key: your-key" \-d '{"role": "assistant", "content": "Based on the documentation, you can configure embedding..."}'-# 步骤 5:提交会话(立即返回 task_id)+# 步骤 5:提交会话(产生归档时返回 task_id)curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \-H "Content-Type: application/json" \-H "X-API-Key: your-key"# 返回:{"status": "ok", "result": {"status": "accepted", "task_id": "uuid-xxx", ...}}-# 步骤 7:查询后台任务状态(可选)+# 步骤 6:查询后台任务状态;未完成时稍后再查curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \-H "X-API-Key: your-key"```@@ -1687,7 +1728,7 @@ if session_info["message_count"] > 10:### 使用会话上下文进行搜索```python-# 结合对话上下文可获得更好的搜索结果+# 用会话上下文解释当前查询;效果取决于上下文相关性和查询规划配置results = await client.search(query=query, session_id=session_id)```diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.mdindex b1cb53a66..302c27614 100644--- a/docs/zh/api/06-retrieval.md+++ b/docs/zh/api/06-retrieval.md@@ -6,10 +6,11 @@ OpenViking 提供多种检索方法,包括简单的向量相似度搜索、关| 方面 | find | search ||------|------|--------|-| 意图分析 | 否 | 是 |-| 会话上下文 | 否 | 是 |-| 查询扩展 | 否 | 是 |-| 默认结果数 | 10 | 10 |+| 意图分析 | 否 | 有会话内容且 `retrieval.enable_intent=true` 时执行 |+| 会话上下文 | 不使用 | 可选 |+| 查询扩展 | 否 | 意图分析启用且有会话内容时执行 |+| 重排序 | 不使用 | 配置了重排序模型时用于文本查询 |+| 默认结果数 | 10 | 每条规划查询最多 10 条 || 使用场景 | 简单查询 | 对话式搜索 |## 检索流程@@ -29,7 +30,7 @@ OpenViking 提供多种检索方法,包括简单的向量相似度搜索、关### find()-基本向量相似度搜索,无需会话上下文。+按查询检索相关内容,不使用会话上下文。#### 1. API 实现介绍@@ -52,7 +53,7 @@ OpenViking 提供多种检索方法,包括简单的向量相似度搜索、关| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|-| query | str | 否 | "" | 搜索查询字符串;未提供 `image_url` 时必填 |+| query | str | 否 | "" | 查询文本;图片查询或仅按过滤条件查询时可省略 || image_url | str | 否 | None | 图片查询,支持 `data:image/...;base64,...`、`http(s)://` 或 `viking://` URI;需要 multimodal embedding 模型 || target_uri | str \| List[str] | 否 | "" | 限制搜索范围到指定的 URI 前缀 || events_time_decay_protection | str \| null | 否 | null | 不传或传 `null` 关闭衰减;传 `"0"` 立即衰减;传 `"7d"` 等时长则在保护期内保持原分,之后衰减。支持非负整数 `Xm`/`Xh`/`Xd` |@@ -65,7 +66,7 @@ OpenViking 提供多种检索方法,包括简单的向量相似度搜索、关| since | str | 否 | None | 时间下界,支持 `2h` 或 ISO 8601 / `YYYY-MM-DD`。不带时区的值按 UTC 解释。CLI `--after` 会映射到这个字段 || until | str | 否 | None | 时间上界,支持 `30m` 或 ISO 8601 / `YYYY-MM-DD`。不带时区的值按 UTC 解释。CLI `--before` 会映射到这个字段 || time_field | "updated_at" \| "created_at" | 否 | "updated_at" | since/until 使用的元数据时间字段 |-| level | str | 否 | None | 限定结果的层级范围,例如 `0`、`1`、`2` 或 `0,1,2`。CLI `--level`/`-L` 会映射到这个字段 |+| level | int \| str \| List[int] | 否 | None | 限定结果的层级范围,例如 `0`、`1`、`2` 或 `0,1,2`。CLI `--level`/`-L` 会映射到这个字段 || include_provenance | bool | 否 | False | 在序列化结果中附带 provenance / query-plan 细节 || read_content | bool | 否 | False | 按可见内容 read 语义读取每个最终命中的 URI,并以内联 `content` 返回。单个读取失败时保留原命中,不附加内容。 || telemetry | bool \| object | 否 | False | 在响应中附带遥测数据 |@@ -184,7 +185,6 @@ Tags 必须使用严格的 `k=v` 字符串。传入多个 tags 时,`find()````pythonimport openviking_sdk as ov-from openviking_sdk import TextPartclient = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")client.initialize()@@ -366,11 +366,11 @@ ov find "红色海报风格" --image ./poster.png --uri "viking://resources/imag### search()-带会话上下文和意图分析的智能检索。+可结合会话上下文规划查询的语义检索。#### 1. API 实现介绍-`search()` 方法在 `find()` 的基础上增加了会话上下文理解和意图分析能力。它可以根据历史对话更好地理解用户查询意图,执行查询扩展,提供更相关的搜索结果。+`search()` 可根据会话规划查询。仅当 `retrieval.enable_intent=true` 且会话有摘要或消息时,才调用 LLM 分析意图;未传会话、会话为空或关闭意图分析时,使用原始查询。图片查询跳过会话规划。**处理流程**:1. 加载会话上下文(如果提供了 session_id)@@ -400,14 +400,14 @@ ov find "红色海报风格" --image ./poster.png --uri "viking://resources/imag| events_time_decay_protection | str \| null | 否 | null | 不传或传 `null` 关闭衰减;传 `"0"` 立即衰减;传 `"7d"` 等时长则在保护期内保持原分,之后衰减。支持非负整数 `Xm`/`Xh`/`Xd` || context_type | str \| List[str] | 否 | None | 限定一个或多个 `ContextType` 取值:`memory`、`resource` 或 `skill` || tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 |-| limit | int | 否 | 10 | 最大返回结果数 |+| limit | int | 否 | 10 | 每条规划查询的结果上限;list 模式直接汇总各查询结果,总数可能超过此值 || node_limit | int | 否 | None | 可选 HTTP 别名;如果提供,会覆盖 limit || score_threshold | float | 否 | None | 最低相关性分数阈值 || filter | Dict | 否 | None | 元数据过滤器 || since | str | 否 | None | 时间下界,支持 `2h` 或 ISO 8601 / `YYYY-MM-DD`。不带时区的值按 UTC 解释。CLI `--after` 会映射到这个字段 || until | str | 否 | None | 时间上界,支持 `30m` 或 ISO 8601 / `YYYY-MM-DD`。不带时区的值按 UTC 解释。CLI `--before` 会映射到这个字段 || time_field | "updated_at" \| "created_at" | 否 | "updated_at" | since/until 使用的元数据时间字段 |-| level | str | 否 | None | 限定结果的层级范围,例如 `0`、`1`、`2` 或 `0,1,2`。CLI `--level`/`-L` 会映射到这个字段 |+| level | int \| str \| List[int] | 否 | None | 限定结果的层级范围,例如 `0`、`1`、`2` 或 `0,1,2`。CLI `--level`/`-L` 会映射到这个字段 || include_provenance | bool | 否 | False | 在序列化结果中附带 provenance / query-plan 细节 || read_content | bool | 否 | False | 按可见内容 read 语义读取每个最终命中的 URI,并以内联 `content` 返回。单个读取失败时保留原命中,不附加内容;仅支持 `mode="list"`。 || telemetry | bool \| object | 否 | False | 在响应中附带遥测数据 |@@ -488,6 +488,7 @@ curl -X POST http://localhost:1933/api/v1/search/search \```pythonimport openviking_sdk as ov+from openviking_sdk import TextPartclient = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")client.initialize()@@ -509,7 +510,7 @@ results = client.search(query="best practices",session_id=session.session_id,options={- "context_type": "skill",+ "context_type": "resource","since": "2h",},)@@ -552,7 +553,7 @@ console.log(await client.search("authentication", { targetUri: "viking://resourc```goresult, err := client.Search(ctx, "best practices", &openviking.SearchOptions{SessionID: "abc123",- ContextType: "skill",+ ContextType: "resource",Limit: 10,})if err != nil {@@ -577,7 +578,7 @@ ov search "watch vs scheduled" --after 2026-03-15 --before 2026-03-20ov search "recent decisions" --context-type memory --level 2 \--events-time-decay-protection 1d-# 不带会话的搜索(仍进行意图分析)+# 不带会话的搜索(使用原始查询)ov search "how to implement OAuth 2.0 authorization code flow"# BM25 关键词检索@@ -603,7 +604,7 @@ ov search "similar poster" --image ./poster.png --uri "viking://resources/images"resources": [{"context_type": "resource",- "uri": "viking://resources/docs/oauth-best-practices",+ "uri": "viking://resources/docs/oauth-best-practices/.overview.md","level": 1,"score": 0.95,"category": "",@@ -639,7 +640,7 @@ ov search "similar poster" --image ./poster.png --uri "viking://resources/images### search(mode="context")-把检索结果直接组装成可注入的上下文块。`mode="list"`(默认)返回排序命中列表,行为与旧版 `search()` 完全一致;`mode="context"` 打开组装面:预算控制、档位降级、跨轮去重和可选的 LLM 摘要都在服务端一次请求内完成。+把检索结果直接组装成可注入的上下文块。`mode="list"`(默认)返回排序命中列表,行为与旧版 `search()` 完全一致;`mode="context"` 在一次服务端请求中按 token 预算选择内容层级、跨轮去重,并可生成 LLM 摘要。#### 1. API 实现介绍@@ -692,7 +693,7 @@ Agent 插件每轮注入上下文时,过去需要按类型逐个检索、再**档位规则**- **Purpose 预设**:`chat` 使用 `events:3, entities:3, preferences:1, experiences:1, resources:1, skills:1`;`coding` 使用 `events:1, entities:2, preferences:1, experiences:1, resources:3, skills:2`。这些值是每个分类的绝对上限,不是权重。各桶结果汇总后仍会去重并全局排序,但不会再被第二个全局 `limit` 截断-- **按类别的默认档**:省略 `detail` 时,各类别落在下表的档位;只有 `events` 会因此读文件,其余类别零 I/O+- **按类别的默认档**:省略 `detail` 时,各类别落在下表的档位;文件条目中只有 `events` 的默认档需要回读正文;目录命中会读取 `.overview.md`| 类别 | 默认档 | 剩余预算可加深到 | 原因 ||------|--------|------------------|------|@@ -700,7 +701,7 @@ Agent 插件每轮注入上下文时,过去需要按类型逐个检索、再| `entities` / `preferences` / `experiences` | 摘要档 | 摘要档 | 正文本身很短,且写入侧把整篇正文存进了摘要标量,摘要档即完整内容 || `resources` / `skills` | 摘要档 | 摘要档 | 资源取语义处理生成的 256 字符摘要,skill 取 `SKILL.md` frontmatter 生成的 name/description;正文可能很大或含凭据,加深需显式指定 || `memories` | 摘要档 | 摘要档 | 四个具名类型之外的内置记忆类型——`cases`、`patterns`、`tools`、`trajectories`、技能使用记忆。只有 quota-free 检索会命中它们;它们没有自己的检索桶,`quotas` 不能指定,但 `detail` 和 `other_peer_penalty` 可以 |- | 目录命中 | 概览档 | 概览档 | 目录没有摘要,读 `.overview.md` 侧车;全文档对目录无意义。skill 包命中除外:它们归一到 `<包根>/SKILL.md`,按上面的文件档位处理 |+ | 目录命中 | 概览档 | 概览档 | 目录条目读取 `.overview.md`,不展开整个子树。skill 包命中除外:它们归一到 `<包根>/SKILL.md`,按上面的文件档位处理 |- **Skill 包**:一个包的每个文件、每层目录各存一条向量记录,它们在配额生效之前先合并成一条——不管命中的是包里哪个文件,每个包只出一条 entry、只占一个名额。这条 entry 的 `uri` 是 `<包根>/SKILL.md`,和 `/skills/find` 返回的 `skill_md_uri` 是同一条路径,正文是包自己的摘要;包的摘要还没生成时退成裸 `uri`,不拿命中的那个文件的摘要顶替。因此 `dedup_turns` 是按包冷却的:某个包以摘要档或更深的档位注入过之后,冷却窗口内命中包里任何文件都会被排除- **保底**:每条结果至少给出 `uri`。记忆类摘要缺失或超出单条上限时回落到概览档:写入侧把整篇正文存进了摘要标量,所以对记忆类别而言概览档在内容阶梯上位于摘要档*之下*,这次替换披露得更少。而 `resources` / `skills` 的摘要是语义处理生成的短摘要,同样的替换会去读调用方没有请求的正文,因此这两类直接退成裸 `uri`,不向上加深@@ -740,7 +741,9 @@ curl -X POST http://localhost:1933/api/v1/search/search \-d '{"query":"档位设计","mode":"context","max_tokens":3000,"rewrite":true}'```-**响应**+**响应节选**++下例缩短了 `entries`、正文和 `rendered`;统计字段对应完整的 13 条结果。```json{@@ -946,24 +949,33 @@ HTTP `POST /api/v1/search/grep` 在不做过滤时可传 `include_tags: true````json{- "status": "ok",- "result": {- "matches": [- {- "uri": "viking://resources/docs/auth.md",- "line": 15,- "content": "User authentication is handled by...",- "before_context": [- {"line": 14, "content": "## Authentication"}- ],- "after_context": [- {"line": 16, "content": "Configure an API key before sending requests."}- ],- "tags": ["team=search", "env=prod"]- }+ "status": "ok",+ "result": {+ "matches": [+ {+ "uri": "viking://resources/docs/auth.md",+ "line": 15,+ "content": "User authentication is handled by...",+ "before_context": [+ {+ "line": 14,+ "content": "## Authentication"+ }],- "count": 1- }+ "after_context": [+ {+ "line": 16,+ "content": "Configure an API key before sending requests."+ }+ ],+ "tags": [+ "team=search",+ "env=prod"+ ]+ }+ ],+ "count": 1+ }}```@@ -1085,14 +1097,14 @@ ov glob "**/*.md" -f tags```json{- "status": "ok",- "result": {- "matches": [- "viking://resources/docs/api.md",- "viking://resources/docs/guide.md"- ],- "count": 2- }+ "status": "ok",+ "result": {+ "matches": [+ "viking://resources/docs/api.md",+ "viking://resources/docs/guide.md"+ ],+ "count": 2+ }}```@@ -1102,7 +1114,7 @@ ov glob "**/*.md" -f tags### 渐进式读取内容-检索结果通常只包含 L0 摘要,你可以根据需要渐进式加载更多详细内容。+结果包含摘要和命中 URI。语义检索的 L0/L1 命中指向 `.abstract.md` 或 `.overview.md`,调用 `overview()` 时需传入其父目录;L2 命中指向文件,可直接用 `read()` 读取。**Python SDK**@@ -1120,7 +1132,8 @@ for context in results.get("resources", []):if context.get("level", 0) < 2:# 获取 L1(概览)用于目录- overview = client.overview(uri=context["uri"])+ directory_uri = context["uri"].rsplit("/", 1)[0]+ overview = client.overview(uri=directory_uri)print(f"Overview: {overview[:500]}...")else:# 加载 L2(内容)用于文件diff --git a/docs/zh/api/07-system.md b/docs/zh/api/07-system.mdindex 0e5010aa2..b5ce70c24 100644--- a/docs/zh/api/07-system.md+++ b/docs/zh/api/07-system.md@@ -8,7 +8,7 @@ OpenViking 系统 API 提供健康检查、就绪检查、一致性检查和多#### 1. API 实现介绍-基础健康检查端点,无需认证。返回服务版本号和健康状态。如果提供认证信息,还会返回认证模式和身份信息。+基础存活检查,无需认证。返回版本号、健康状态和认证模式。提供凭据后会尝试解析身份,成功时补充身份字段;凭据无效时返回认证错误。Trusted 模式下,完整的 `X-OpenViking-Account` 和 `X-OpenViking-User` 请求头会触发身份解析,包括省略 `root_api_key` 的 localhost 部署。配置了 Root 密钥的服务继续校验认证请求中的密钥。@@ -188,7 +188,6 @@ curl -X GET http://localhost:1933/ready**代码入口**:- `openviking/server/routers/system.py:system_status` - HTTP 路由-- `sdk/python/openviking_sdk/client.py:SyncHTTPClient.get_status` - SDK 入口- `crates/ov_cli/src/commands/system.rs` - CLI 命令#### 2. 接口和参数说明@@ -301,11 +300,11 @@ ov system consistency viking://resources/my-project{"status": "ok","result": {- "ok": false,- "expected_count": 3,- "missing_record_count": 1,- "missing_records_truncated": false,- "missing_records": [+ "ok": false,+ "expected_count": 3,+ "missing_record_count": 1,+ "missing_records_truncated": false,+ "missing_records": [{"uri": "viking://resources/my-project/README.md","path": "README.md",@@ -323,7 +322,7 @@ ov system consistency viking://resources/my-project#### 1. API 实现介绍-等待所有异步处理(embedding、语义生成)完成。该方法会阻塞直到所有队列中的任务处理完毕或超时。+等待处理队列排空,或在超时后结束。该检查不限定为调用方刚提交的请求,也不覆盖所有异步 API。需检查返回的 `error_count` 和 `errors`,队列排空不代表所有操作成功。确认某次导入或 commit 的结果,应查询它的[任务 ID](17-tasks.md)。**代码入口**:- `openviking/server/routers/system.py:wait_processed` - HTTP 路由@@ -358,12 +357,9 @@ curl -X POST http://localhost:1933/api/v1/system/wait \**Python SDK**```python-# 添加资源-client.add_resource(path="./docs/")--# 等待所有处理完成+# 等待当前处理队列排空status = client.wait_processed(timeout=60.0)-print(f"Processing complete: {status}")+print(status) # 检查各队列的 error_count 和 errors```**TypeScript SDK**diff --git a/docs/zh/api/09-metrics.md b/docs/zh/api/09-metrics.mdindex b2d9a1b8f..251f0ddbd 100644--- a/docs/zh/api/09-metrics.md+++ b/docs/zh/api/09-metrics.md@@ -2,11 +2,7 @@OpenViking 提供 `/metrics` 端点,用于向 Prometheus、Grafana Agent 等监控系统导出运行时指标。-与 `/api/v1/observer/*` 不同,`/metrics` 的定位是:--- 面向机器抓取,而不是面向人工阅读-- 返回 Prometheus exposition 文本,而不是统一 JSON 包装-- 偏系统运行态与服务运行质量,不承担业务分析接口职责+该端点返回供监控系统定时抓取的 Prometheus 文本,内容是系统运行状态和服务质量信号,不用于业务分析。需要组件状态的 JSON 快照时,使用 `/api/v1/observer/*`。## API 参考@@ -18,9 +14,7 @@ OpenViking 提供 `/metrics` 端点,用于向 Prometheus、Grafana Agent 等**认证**-- 当前实现中,`/metrics` 未接入 `get_request_context` 等鉴权依赖,因此可直接访问。-- 也就是说,从代码实现角度看,`/metrics` 当前等价于公开抓取端点。-- 如果后续通过网关、反向代理或服务端策略收紧访问控制,应以实际部署配置为准。+服务端不对 `/metrics` 请求鉴权。若网关或反向代理限制访问,抓取任务需使用该层要求的凭据。**HTTP API**diff --git a/docs/zh/api/11-snapshot.md b/docs/zh/api/11-snapshot.mdindex 7958c3356..5675d728f 100644--- a/docs/zh/api/11-snapshot.md+++ b/docs/zh/api/11-snapshot.md@@ -1,8 +1,8 @@# 多版本管理(快照)-OpenViking 在 VikingFS 之上提供了一套基于 Git 的多版本管理能力,称为**快照(Snapshot)**。它把某个账号(account)下的整棵资源树保存成一系列不可变的提交(commit),让你能够回溯历史、对比版本,并把工作区恢复到任意一个历史状态。+快照将指定范围内的文件树保存为不可变版本。使用 `commit` 保存、`log` 查看历史、`show` 读取旧版文件、`diff` 对比文件在两个版本间的差异、`restore` 恢复已保存的内容。未提交或被排除的文件不在恢复范围内,ACL 和向量索引也不保存历史版本。-快照能力底层由内嵌在 Rust RAGFS 层的 [gitoxide](https://github.com/Byron/gitoxide) 驱动,按 `account_id` 维护一个逻辑 Git 仓库(每个账号一个仓库),对调用方完全透明——你无需关心 `.ovgit` 目录、对象库或引用细节。+快照能力底层由内嵌在 Rust RAGFS 层的 [gitoxide](https://github.com/Byron/gitoxide) 驱动,按 `account_id` 维护一个逻辑 Git 仓库(每个账号一个仓库),使用快照 API 管理版本即可,无需直接修改底层仓库。五个核心命令:@@ -20,7 +20,7 @@ OpenViking 在 VikingFS 之上提供了一套基于 Git 的多版本管理能力- **提交(commit)**:一个快照对应一个提交,由 40 位十六进制的 SHA-1 `commit_oid` 唯一标识。多数命令也接受 OID 的缩写前缀,或分支名(如 `main`)。- **分支(branch)**:默认分支为 `main`。除非显式传入,所有命令都作用在 `main` 上。-- **正向恢复(forward-commit restore)**:`restore` **不会**回退或改写历史。它会读取 `source_commit` 的内容,把差异写回工作区,并在当前 HEAD 之上**生成一个新的提交**。因此新提交的父提交是恢复操作发生前的 HEAD,而**不是** `source_commit`。HEAD 始终单调向前推进,历史永远不会丢失。+- **正向恢复(forward-commit restore)**:`restore` **不会**回退或改写历史。它会读取 `source_commit` 的内容,把差异写回工作区,并在当前 HEAD 之上**生成一个新的提交**。因此新提交的父提交是恢复操作发生前的 HEAD,而**不是** `source_commit`。恢复保留此前的提交;选定的源文件树与 HEAD 一致时返回 `noop`,不生成新提交。该比较不检查工作区中未提交的改动。- **作用范围**:`commit` 可以通过 `paths` 限定只快照部分 URI;`restore` 可以通过 `project_dir` 限定只恢复某个子目录,目录之外的文件保持不变。## ACL 权限@@ -34,7 +34,7 @@ OpenViking 在 VikingFS 之上提供了一套基于 Git 的多版本管理能力| `restore` 覆盖已有文件 | 文件的 `write` || `restore` 新建文件 | 父目录的 `write` || `restore` 删除文件 | 文件的 `write` |-| `.ovgitignore` 读写删除 | ADMIN |+| `.ovgitignore` 读写删除 | ADMIN 或 ROOT |USER 和 ADMIN 调用 `commit`、`log`、`restore` 时必须显式传入 `paths` 或 `project_dir`;`show` 必须传入 `path`,不带 `path` 的全局提交元数据查询只保留给本地 ROOT 模式。用户可以操作自己有权访问的公共资源和自己的 `viking://user/{user_id}/...`,不能访问其他用户空间。目录操作会先完整鉴权,不会静默跳过无权子节点;`restore` 会先鉴权全部写入和删除项,再开始修改。@@ -406,13 +406,6 @@ ov snapshot diff viking://resources/my_project/guide.md \**Python SDK (HTTP)**```python-result = client.snapshot.restore(- project_dir="viking://resources/my_project",- source_commit="3f2a1b9c",- message="restore to v1",-)-print(result["result"], result["new_commit_oid"])-# 先预演,确认要改动哪些文件plan = client.snapshot.restore(project_dir="viking://resources/my_project",@@ -422,6 +415,18 @@ plan = client.snapshot.restore(print(plan["diff"])```+```python+# 核对计划后,再执行恢复+result = client.snapshot.restore(+ project_dir="viking://resources/my_project",+ source_commit="3f2a1b9c",+ message="restore to v1",+)+print(result["result"])+if result["result"] == "applied":+ print(result["new_commit_oid"])+```+**TypeScript SDK**```typescript@@ -452,10 +457,11 @@ curl -X POST "http://localhost:1933/api/v1/snapshot/restore" \```bash# 位置参数依次为 <source_commit> <project_dir>-ov snapshot restore 3f2a1b9c viking://resources/my_project -m "restore to v1" -o json--# 预演+# 先预演ov snapshot restore 3f2a1b9c viking://resources/my_project --dry-run -o json++# 核对计划后,再执行恢复+ov snapshot restore 3f2a1b9c viking://resources/my_project -m "restore to v1" -o json```**响应(applied)**@@ -525,7 +531,7 @@ ov snapshot restore 3f2a1b9c viking://resources/my_project --dry-run -o json语法为常见 glob 子集:空行被忽略、`#` 开头为注释、行首尾空白被裁剪;**不支持** `!` 取反与反斜杠转义;文件大小上限 64 KiB(写入时即校验)。匹配路径为账号相对 Git 树路径(`/` 分隔)。-提供三个方法:`get_gitignore`(读取,缺失返回空串)、`set_gitignore`(写入)、`delete_gitignore`(删除,缺失即成功、幂等)。三者都要求 ADMIN 权限,只需请求上下文中的账号,无路径参数。+提供三个方法:`get_gitignore`(读取,缺失返回空串)、`set_gitignore`(写入)、`delete_gitignore`(删除,缺失即成功、幂等)。三者都要求 ADMIN 或 ROOT 权限,只需请求上下文中的账号,无路径参数。### get_gitignore()@@ -718,5 +724,5 @@ client.close()## 相关文档- [文件系统](03-filesystem.md):快照建立在文件系统资源之上-- [系统](07-system.md):通过 `GET /api/v1/tasks/{task_id}` 跟踪 restore 触发的后台向量重建+- [后台任务](17-tasks.md):通过 `GET /api/v1/tasks/{task_id}` 跟踪 restore 触发的后台向量重建- [API 概览](01-overview.md):完整端点总览diff --git a/docs/zh/api/12-content.md b/docs/zh/api/12-content.mdindex 3823486df..690f8a1fa 100644--- a/docs/zh/api/12-content.md+++ b/docs/zh/api/12-content.md@@ -144,13 +144,13 @@ ov overview viking://resources/docs/| uri | str | 是 | - | Viking URI(如 `viking://resources/docs/api.md`)或 32 字符十六进制向量记录 `id`(由 `stat()` 返回) || offset | int | 否 | 0 | 起始行号(0 开始) || limit | int | 否 | -1 | 读取的行数,`-1` 表示读到结尾 |-| raw | bool | 否 | false | 返回未过滤 MEMORY_FIELDS 的原始存储内容(仅 HTTP API,Python SDK 暂未暴露)。 |+| raw | bool | 否 | false | 返回未过滤 MEMORY_FIELDS 的原始存储内容;Python 中使用 `client.read_raw(uri)` 读取此格式。 |**说明**-- `read()` 只接受文件 URI。传入已存在的目录 URI 时返回 `INVALID_ARGUMENT`(`400`),而不是 `NOT_FOUND`。该错误会携带结构化的 `details` 字段——`details.expected` 为 `"file"`,`details.actual` 为 `"directory"`,`details.resource` 为出错的 URI(HTTP 路径上会带上)——客户端据此即可以编程方式判断"文件 vs 目录"不匹配(例如回退到 `list`),而无需对错误消息做字符串匹配。+- `read()` 只接受文件 URI。传入已存在的目录时返回 `INVALID_ARGUMENT`(HTTP `400`)。HTTP 响应的 `details` 包含 `expected: "file"`、`actual: "directory"` 和目标 `resource` URI,客户端可据此改用目录列表接口,无需解析错误消息。- 除 Viking URI 外,还可以传入 `stat()` 返回的 32 字符十六进制文件 `id`。服务端通过向量索引查找对应 URI 并执行相同的权限校验。由于索引是异步生成的,新返回的 ID 可能暂时无法解析;对应向量记录被删除后,按 ID 查询也会失败。这两种情况下,服务端都会返回 `NOT_FOUND`,并提示数据可能尚未索引或已经删除。-- 公开 URI 参数接受 `resources` 和 `user` 作用域。访问 session 文件时,使用 `viking://user/{user_id}/sessions/{session_id}`,也可以使用向后兼容的 `viking://session/{session_id}` 别名。`temp`、`queue` 等内部作用域会返回 `INVALID_URI`。+- 公开 URI 参数接受 `resources`、`user` 和 `agent` 作用域。访问 session 文件时,使用 `viking://user/{user_id}/sessions/{session_id}/messages.jsonl`,也可以使用向后兼容的 `viking://session/{session_id}/messages.jsonl` 别名。`temp`、`queue` 等内部作用域会返回 `INVALID_URI`。**Python SDK**@@ -296,13 +296,13 @@ curl -X POST "http://localhost:1933/api/v1/content/write" \```bashov write viking://resources/docs/api.md \- --content "# Updated API\n\nFresh content." \+ --content $'# Updated API\n\nFresh content.' \--tags team=search,env=prod \--tag-mode replace```-**响应**+**`wait=true` 且刷新完成时的响应**```json{@@ -386,10 +386,36 @@ result = client.batch_write("mode": "upsert",},],- wait=False,+ wait=True,)```+**TypeScript SDK**++```typescript+const result = await client.batchWrite("viking://resources/wiki", [+ {+ uri: "viking://resources/wiki/new.md",+ content: "# New page\n",+ mode: "upsert",+ },+]);+console.log(result);+```++**Go SDK**++```go+content := "# New page\n"+result, err := client.BatchWrite(ctx, "viking://resources/wiki", []openviking.BatchWriteOperation{+ {URI: "viking://resources/wiki/new.md", Content: &content, Mode: "upsert"},+}, nil)+if err != nil {+ return err+}+fmt.Println(result)+```+**HTTP API**```@@ -409,11 +435,11 @@ curl -X POST http://localhost:1933/api/v1/content/batch-write \"mode": "upsert"}],- "wait": false+ "wait": true}'```-**响应**+**`wait=true` 且刷新完成时的响应**```json{@@ -436,7 +462,7 @@ curl -X POST http://localhost:1933/api/v1/content/batch-write \}```-TypeScript、Go SDK 和 CLI 当前不直接暴露 batch write。+CLI 当前不直接提供批量写入命令。---@@ -448,6 +474,38 @@ TypeScript、Go SDK 和 CLI 当前不直接暴露 batch write。|------|------|------|------|| `uri` | string | 是 | 要下载的文件 URI |+**Python SDK**++```python+from pathlib import Path++Path("logo.png").write_bytes(+ client.download_bytes("viking://resources/images/logo.png")+)+```++**TypeScript SDK**++```typescript+import { writeFile } from "node:fs/promises";++const bytes = await client.downloadBytes("viking://resources/images/logo.png");+await writeFile("logo.png", bytes);+```++**Go SDK**++```go+// Requires the os package.+data, err := client.DownloadBytes(ctx, "viking://resources/images/logo.png")+if err != nil {+ return err+}+if err := os.WriteFile("logo.png", data, 0600); err != nil {+ return err+}+```+**HTTP API**```http@@ -479,7 +537,7 @@ Content-Disposition: attachment; filename*=UTF-8''logo.png<binary body>```-`ov get <uri> <local-path>` 通过上述 HTTP API 下载文件并写入本地路径。Python、TypeScript 和 Go SDK 当前没有独立的原始字节下载方法。+`ov get <uri> <local-path>` 通过上述 HTTP API 下载文件并写入本地路径。---@@ -699,8 +757,7 @@ POST /api/v1/content/reindex```bashcurl -X POST http://localhost:1933/api/v1/content/reindex \-H "Content-Type: application/json" \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \+ -H "X-API-Key: your-admin-key" \-d '{"uri": "viking://resources","mode": "vectors_only",@@ -747,8 +804,7 @@ ov reindex viking://user/default/skills --mode semantic_and_vectors --wait false```bashcurl -X GET http://localhost:1933/api/v1/tasks/task_xxx \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default"+ -H "X-API-Key: your-admin-key"```Reindex 后台任务的 `task_type` 为 `admin_reindex`,`resource_id` 等于请求中的 `uri`,也可以这样列出:diff --git a/docs/zh/api/14-ovpack.md b/docs/zh/api/14-ovpack.mdindex dab6037ea..8d4ffdb23 100644--- a/docs/zh/api/14-ovpack.md+++ b/docs/zh/api/14-ovpack.md@@ -73,8 +73,15 @@ import openviking_sdk as ovclient = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-admin-key")client.initialize()-# 导出到本地文件(HTTP SDK 会自动处理下载)-# 注意:导出功能主要通过 CLI 使用+try:+ output_path = client.export_ovpack(+ "viking://resources/my-project/",+ "./exports/my-project.ovpack",+ include_vectors=False,+ )+ print(output_path)+finally:+ client.close()```**TypeScript SDK**@@ -133,7 +140,7 @@ ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-v2. 解析上传的 `.ovpack` 文件3. 校验 manifest 元数据、路径、文件和目录集合、文件大小和 checksum4. 应用 `on_conflict`-5. 导入资源到目标位置,并重建向量+5. 导入资源到目标位置,并按 `vector_mode` 恢复兼容向量或安排重新向量化**代码入口**:- `openviking/server/routers/pack.py:import_ovpack` - HTTP 路由@@ -194,7 +201,7 @@ curl -X POST http://localhost:1933/api/v1/pack/import \-d "{\"temp_file_id\": \"$TEMP_FILE_ID\",\"parent\": \"viking://resources/imported/\",- \"on_conflict\": \"overwrite\",+ \"on_conflict\": \"fail\",\"vector_mode\": \"auto\"}"```@@ -207,8 +214,16 @@ import openviking_sdk as ovclient = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-admin-key")client.initialize()-# 导入 .ovpack 文件(HTTP SDK 会自动处理上传)-# 注意:导入功能主要通过 CLI 使用+try:+ uri = client.import_ovpack(+ "./exports/my-project.ovpack",+ "viking://resources/imported/",+ on_conflict="fail",+ vector_mode="auto",+ )+ print(uri)+finally:+ client.close()```**TypeScript SDK**@@ -218,7 +233,7 @@ const uri = await client.importOVPack("./exports/docs.ovpack","viking://resources/",{- onConflict: "overwrite",+ onConflict: "fail",vectorMode: "auto",},);@@ -233,7 +248,7 @@ uri, err := client.ImportOVPack("./exports/my-project.ovpack","viking://resources/imported/",&openviking.ImportPackOptions{- OnConflict: "overwrite",+ OnConflict: "fail",VectorMode: "auto",},)@@ -293,9 +308,11 @@ ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode将公开 scope root 备份为只能通过 restore 恢复的 `.ovpack` 文件。备份包含`resources` 和当前账号下所有 `user/{user_id}` 内容;session 会通过 user 命名空间下的`user/{user_id}/sessions` 一起包含,不包含 `temp`、`queue` 等内部运行态数据,也不包含-用户账号或 API Key。该接口仅允许 ROOT 或 ADMIN 调用。+用户账号或用于登录 OpenViking 的 API Key。用户 privacy 配置目录会包含在备份中,其中可能有外部服务密钥。该接口仅允许 ROOT 或 ADMIN 调用。设置 `include_vectors=true` 时,会额外导出兼容的纯 dense 向量快照;底层 index type 为 hybrid 时会拒绝导出向量快照。+这里的“公开 scope”指可导出的 URI 根目录,不表示用户文件公开可读。ZIP 包含导出文件的内容,本身不提供备份加密。+备份是在线逐文件读取,不保证同一时刻的原子快照。需要严格一致性时,调用方应在备份窗口暂停写入。```diff --git a/docs/zh/api/15-watches.md b/docs/zh/api/15-watches.mdindex 627591a67..32e57dabe 100644--- a/docs/zh/api/15-watches.md+++ b/docs/zh/api/15-watches.md@@ -6,16 +6,16 @@ Watch API 管理资源的周期检查、暂停、恢复和手动触发。### Watch Management(监控任务管理)-列出、查看、更新和触发通过 [`add_resource`](02-resources.md#add-resource) 配合 `watch_interval > 0` 创建的监控任务。控制面在 REST(`/api/v1/watches`)、`ov task watch` CLI 子命令组以及面向 Agent 的最小闭包 MCP 接口(`list_watches` / `cancel_watch`)三处镜像。+列出、查看、更新和触发通过 [`add_resource`](02-resources.md#add-resource) 配合 `watch_interval > 0` 创建的监控任务。REST(`/api/v1/watches`)和 `ov task watch` 提供完整管理操作;MCP 提供 `list_watches` 和 `cancel_watch`,用于列出和删除 Watch。#### 1. API 实现介绍-此控制面封装了 `WatchManager` 原语,未改动任何服务端行为。每个端点和 CLI 命令都支持通过 `task_id`(路径)或 `to_uri`(查询参数)定位目标任务,两种键可以互换;如果同时提供,二者必须指向同一任务,否则返回 400。+通过 `task_id` 定位任务,或通过 `to_uri` 查找唯一可访问的任务。多个 Connector Watch 可以共享目标;此时按 URI 操作会返回 `409 Conflict`,需要改用 `task_id`。同时提供两个参数时,它们必须指向同一任务,否则返回 `400`。**操作**:- **列出**(`GET /api/v1/watches`)— 返回 `{tasks, total}`;可传 `?active_only=true` 过滤;传 `?to_uri=...` 时降级为单任务查找- **查看**(`GET /api/v1/watches/{task_id}`)— 查看单个任务;可选 `?to_uri=` 做跨键一致性校验-- **更新**(`PATCH /api/v1/watches/{task_id}` 或 `PATCH /api/v1/watches?to_uri=...`)— 部分更新 `watch_interval`、`is_active`、`reason`、`instruction`。`is_active` 与 `watch_interval` 正交:翻转 `is_active` 可在不丢失配置周期的前提下暂停/恢复任务。+- **更新**(`PATCH /api/v1/watches/{task_id}` 或 `PATCH /api/v1/watches?to_uri=...`)— 部分更新 `watch_interval`、`is_active`、`reason`、`instruction`。`is_active` 与 `watch_interval` 独立:修改 `is_active` 可在不丢失配置周期的前提下暂停/恢复任务。- **删除**(`DELETE /api/v1/watches/{task_id}` 或 `DELETE /api/v1/watches?to_uri=...`)- **触发**(`POST /api/v1/watches/{task_id}/trigger` 或 `POST /api/v1/watches/trigger?to_uri=...`)— 触发即返回(fire-and-forget),重新摄取在后台异步执行@@ -65,6 +65,8 @@ curl -X DELETE "http://localhost:1933/api/v1/watches?to_uri=viking://resources/g**Python SDK**+以下使用 `SyncHTTPClient`;使用 `AsyncHTTPClient` 时,每次调用都需加 `await`。+```pythonwatches = client.list_watches(active_only=True)client.update_watch(to_uri="viking://resources/guide.md", is_active=False)@@ -202,14 +204,14 @@ ov task watch rm viking://resources/guide.md`scheduled=true` 只表示后台执行已调度,不表示重新摄取已经完成;应再次查看任务,直到`last_execution_time` 更新,并检查 `last_status` 和 `last_error`。-**MCP**(Agent 控制面——仅最小闭包)+**MCP**```textlist_watches() # 每个任务一行;只暴露 URI,不暴露 task_idcancel_watch(to_uri="viking://resources/guide.md") # 按 URI 幂等删除```-暂停 / 恢复 / 触发 / 更新故意不通过 MCP 暴露——这些 power-user 操作放在 CLI/REST 一侧,以保持 Agent 系统提示词的紧凑。Agent 侧若需创建监控任务或调整周期,仍走 [`add_resource`](02-resources.md#add-resource) 配合 `watch_interval`;可显式传 `to`,也可让系统绑定本次导入返回的 `root_uri`。+删除 Watch 会移除定时任务,已导入的资源保留。MCP 只提供列出和删除 Watch。创建 Watch 时,使用 [`add_resource`](02-resources.md#add-resource) 并设置 `watch_interval`;暂停、恢复、触发和调整已有 Watch 的周期使用 CLI 或 REST。重复导入不会更新已有 Watch。---diff --git a/docs/zh/api/16-memory.md b/docs/zh/api/16-memory.mdindex d8825521e..fce2ff8c4 100644--- a/docs/zh/api/16-memory.md+++ b/docs/zh/api/16-memory.md@@ -6,117 +6,32 @@| 分类 | 位置 | 说明 ||------|------|------|-| profile | `user/memories/profile.md` | 用户个人信息 |-| preferences | `user/memories/preferences/` | 按主题分类的用户偏好 |-| entities | `user/memories/entities/` | 重要实体(人物、项目等) |-| events | `user/memories/events/` | 重要事件 |-| identity | `user/memories/identity.md` | 助手身份与自我介绍 |-| soul | `user/memories/soul.md` | 助手原则、边界、风格和连续性 |-| cases | `user/memories/cases/` | 可训练、可评估的任务案例 |-| trajectories | `user/memories/trajectories/` | 可复用的操作契约 |-| experiences | `user/memories/experiences/` | 可复用的执行经验 |-| tools | `user/memories/tools/` | 工具使用经验与最佳实践 |-| skills | `user/memories/skills/` | 技能执行经验与工作流策略 |--以上是当前启用的内置类型;部署可以通过自定义记忆模板扩展或覆盖。+| profile | `viking://user/{user_id}/memories/profile.md` | 用户个人信息 |+| preferences | `viking://user/{user_id}/memories/preferences/` | 按主题分类的用户偏好 |+| entities | `viking://user/{user_id}/memories/entities/` | 重要实体(人物、项目等) |+| events | `viking://user/{user_id}/memories/events/` | 重要事件 |+| identity | `viking://user/{user_id}/memories/identity.md` | 助手身份与自我介绍 |+| soul | `viking://user/{user_id}/memories/soul.md` | 助手原则、边界、风格和连续性 |+| cases | `viking://user/{user_id}/memories/cases/` | 可训练、可评估的任务案例 |+| trajectories | `viking://user/{user_id}/memories/trajectories/` | 从 Agent 任务轨迹提炼的可复用操作契约 |+| experiences | `viking://user/{user_id}/memories/experiences/` | 可复用的执行经验 |+| tools | `viking://user/{user_id}/memories/tools/` | 工具使用经验与最佳实践 |+| skills | `viking://user/{user_id}/memories/skills/` | 技能执行经验与工作流策略 |++以上是随部署提供的内置类型,`tools` 和 `skills` 默认关闭;实际抽取还取决于生效的记忆策略和 Agent 进化设置。表中为 Self 路径,支持 Peer 的类型也可存放在 `viking://user/{user_id}/peers/{peer_id}/memories/` 下。部署模板可以扩展或覆盖 Registry;Account 模板 API 只允许修改其列出的字段和类型。----## API 参考--### recall()--> **已弃用**:`/api/v1/search/recall` 现在只是 [`/api/v1/search/search` 的 `mode="context"`](06-retrieval.md#search-mode-context) 之上的轻量预设,自身不再包含独立的组装逻辑。新接入请直接使用 context 面;v1 字段别名仅在本端点保留,将在下一个 minor 版本移除。响应会带上 `Deprecation: true` 头。--按记忆类型分别检索,并在预算内组合成可直接注入 Agent 上下文的记忆块。相对 context 面,`/recall` 会叠加 `purpose="coding"`、兼容 v1 的 `score_threshold=0.1`、带 `session_id` 时 `dedup_turns=5`、`query_expansion="auto"`。Coding Agent 插件会显式发送 `score_threshold=0.35`;公共 `/recall` 默认值仍为 `0.1`,避免相同请求在升级后静默减少结果。省略 `quotas` 时沿用 v1 的分桶默认值(`events=10, entities=10, preferences=3, experiences=0`);显式传 `"quotas": null` 才改用 `purpose` 预设配比。--**v1 字段折叠**+## 记忆召回-| v1 字段 | 折叠为 | 说明 |-|---------|--------|------|-| `max_chars` | `max_tokens = max_chars / 4` | `6500` → `1625`;显式传 `max_tokens` 时以后者为准 |-| `min_score` | `score_threshold` | 都未提供时取兼容 v1 的默认值 `0.1` |-| `render: true` | 不钉档位 | 默认行为:各类别取自己的默认档 |-| `render: false` | 只返回 `entries`,`rendered` 为空 | |-| `render: "compact"` | `detail="abstract"` | 原型期的紧凑模式;把所有类别钉在摘要档 |-| v1 `quotas` 键 | 叠加在 v1 分桶默认值之上 | 键名未变;只传一部分键时其余桶保留默认值 |--context 面的参数(`max_tokens`、`detail`、`dedup_turns`、`session_id`、`query_expansion`、`exclude_uris`、`purpose`、`rewrite`、`rewrite_max_bullets`)在本端点同样接受,便于插件在尚未升级的部署上平滑过渡。--**HTTP API**+用 [`search(mode="context")`](06-retrieval.md#search-mode-context) 检索记忆并组装可直接注入的记忆块。服务端 MCP 以 `search(mode="context")` 提供同一能力,没有单独的 `recall` 工具。```httpPOST /api/v1/search/recallContent-Type: application/json```-```bash-curl -X POST http://localhost:1933/api/v1/search/recall \- -H "Content-Type: application/json" \- -H "Authorization: Bearer $OPENVIKING_API_KEY" \- -d '{- "query":"OpenViking API 文档偏好",- "quotas":{"events":5,"entities":5,"preferences":3,"experiences":2},- "max_chars":6500,- "peer_scope":"all"- }'-```--**MCP**--```text-recall(- query="OpenViking API 文档偏好",- quotas={"events": 5, "entities": 5, "preferences": 3, "experiences": 2},- max_chars=6500,- peer_scope="all"-)-```--**响应**--响应形状与 context 面一致(entries 扁平化、`rendered` 为扁平 XML):--```json-{- "status": "ok",- "result": {- "entries": [- {- "uri": "viking://user/default/memories/preferences/api-docs.md",- "category": "preferences",- "score": 0.82,- "detail": "full",- "text": "用户偏好在 API 文档中同时提供 HTTP、SDK 和 CLI 示例。",- "origin": "self"- }- ],- "rendered": "<memory uri=\"viking://user/default/memories/preferences/api-docs.md\" type=\"preferences\" score=\"0.82\" detail=\"full\">\n用户偏好在 API 文档中同时提供 HTTP、SDK 和 CLI 示例。\n</memory>",- "digest": "",- "stats": {- "quotas": {"events": 5, "entities": 5, "preferences": 3, "experiences": 2},- "candidates": 4,- "returned": 1,- "dropped": 0,- "max_tokens": 1625,- "used_tokens": 96,- "tier_counts": {"full": 1},- "peer_scope": "all",- "origins": {"actor_peer": 0, "self": 1, "other_peer": 0},- "deprecated": {- "endpoint": "/api/v1/search/recall",- "successor": "/api/v1/search/search",- "successor_body": {"mode": "context"},- "aliases_used": ["max_chars"]- }- }- }-}-```--字段含义见 [检索 - search(mode="context")](06-retrieval.md#search-mode-context)。相对 v1 的形状变化:`type` → `category`、`mode` → `detail`、`content`/`summary` → `text`,`rendered` 由三层嵌套改为扁平 `<memory>` 标签,`rank` 不再返回。--公共 Python、TypeScript、Go SDK 和 `ov` CLI 当前尚未封装该端点,因此本节只展示 HTTP Tab,并补充实际存在的 MCP 调用。+`/api/v1/search/recall` 已弃用。它只是 `search(mode="context")` 叠加 `purpose="coding"` 和 v1 默认值的预设,为现有调用方保留;响应带 `Deprecation: true` 头。新接入不要使用。## 相关文档diff --git a/docs/zh/api/17-tasks.md b/docs/zh/api/17-tasks.mdindex e02e9436a..8f9755a53 100644--- a/docs/zh/api/17-tasks.md+++ b/docs/zh/api/17-tasks.md@@ -150,10 +150,14 @@ ov task status uuid-xxx每个任务最多保留 64 条事件,序列化事件数据不超过 32 KiB。超限时优先删除较早事件,`dropped_count` 记录删除数量,保留事件的序号不重置。事件随任务过期清理。旧任务返回 `execution_events: null`;若旧的活跃任务后来产生事件,则 `started_mid_task` 为 true,不会重建此前的历史。旧版本服务即使收到参数也可能不返回该字段。Studio 会说明这些情况,并保留任务元数据、结果和错误展示。+::: details 扩展事件与版本回滚兼容性+扩展执行事件时,在 `openviking/service/task_events.py` 注册事件类型、补充 Studio 翻译,然后在实际执行点调用 `await tracker.record_event(task_id, kind, account_id=..., user_id=..., operation=...)`。这个内部接口不修改任务状态或阶段,只接受有长度限制的操作标识,不接受任意日志内容。现有生命周期方法会自动记录它们接受的状态变化。持久化任务文件新增 `execution_events` 字段。回滚目标需要具备未知任务字段的保留能力(提交 `a5166386` 或之后的版本);更早的读取实现可能拒绝这些文件。回滚期间也会停止上报事件,因此跨降级执行的任务历史可能不完整。+:::+**响应示例(完成)**```json@@ -203,6 +207,8 @@ ov task status uuid-xxx**支持的任务类型**:- `add_resource`+- `add_skill`+- `compile`- `session_commit`- `admin_reindex`- `snapshot_restore_reindex`@@ -309,7 +315,12 @@ ov task cancel uuid-xxx| status | str | 否 | None | 按任务状态过滤:`pending`、`running`、`cancelling`、`completed`、`failed`、`cancelled` || resource_id | str | 否 | None | 按资源 ID 过滤,例如会话 ID || include_internal | bool | 否 | false | 是否包含 Connector 导入产生的内部子任务 |-| limit | int | 否 | 50 | 最多返回的任务条数 |+| limit | int | 否 | 50 | 每次最多返回的任务条数,范围 1~200 |+| pagination | str | 否 | None | 仅 HTTP;传 `cursor` 后以分页对象返回 |+| cursor | str | 否 | None | 仅 HTTP;上一页的 `next_cursor`,与 `pagination=cursor` 一起使用 |+| q | str | 否 | None | 仅 HTTP cursor 模式;在 task ID 和 Compile 请求的 `skill`、`to`、`from` 中做不区分大小写的包含匹配 |++使用 `pagination=cursor` 时,`result` 是包含 `items`、`has_more` 和 `next_cursor` 的对象,而不是数组。请求下一页时原样传入 `next_cursor`,并保持相同的过滤条件和身份。未使用 cursor 模式时,`q` 和 `cursor` 不影响结果。默认仅返回用户可见任务;排查 Connector 导入时可传 `include_internal=true` 查看其内部 `add_resource` 子任务。diff --git a/docs/zh/api/18-observer.md b/docs/zh/api/18-observer.mdindex 484d9b69f..db7cb5bd2 100644--- a/docs/zh/api/18-observer.md+++ b/docs/zh/api/18-observer.md@@ -172,7 +172,7 @@ ov observer vikingdb#### 1. API 实现介绍-获取模型子系统的聚合状态(VLM、embedding、rerank)。检查各模型提供者是否健康可用。+获取当前账号的 VLM、Embedding 配置和 token 用量信息。观察器解析账号模型信息时未发生错误,`is_healthy` 才为 true;它不会逐一探测提供者是否可达。Embedding 连通性可查看 `/ready`,其他模型应结合实际请求错误排查。**代码入口**:- `openviking/server/routers/observer.py:observer_models` - HTTP 路由@@ -236,7 +236,7 @@ ov observer models"name": "models","is_healthy": true,"has_errors": false,- "status": "provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ..."+ "status": "Account: default\nEmbedding dimension: 1024\nNo model usage data available."}}```@@ -252,7 +252,6 @@ ov observer models**代码入口**:- `openviking/server/routers/observer.py:observer_lock` - HTTP 路由- `openviking/service/debug_service.py:ObserverService.lock` - 核心实现-- `openviking/storage/observers/lock_observer.py` - 锁观察者- `crates/ov_cli/src/commands/observer.rs` - CLI 命令#### 2. 接口和参数说明@@ -294,7 +293,7 @@ curl -X GET http://localhost:1933/api/v1/observer/lock \#### 1. API 实现介绍-获取检索质量指标。+获取已记录的查询次数、结果数、分数、Rerank 使用情况和延迟。这些数据用于诊断,不能直接衡量结果相关性;空结果也是有效结果,不会使该组件被判定为不健康。**代码入口**:- `openviking/server/routers/observer.py:observer_retrieval` - HTTP 路由@@ -396,7 +395,7 @@ ov observer filesystem#### 1. API 实现介绍-获取整体系统状态,包括所有组件(queue、vikingdb、models、lock、retrieval)。+获取整体系统状态,包括所有组件(queue、vikingdb、models、lock、retrieval、filesystem)。**代码入口**:- `openviking/server/routers/observer.py:observer_system` - HTTP 路由@@ -488,6 +487,12 @@ ov observer system"is_healthy": true,"has_errors": false,"status": "..."+ },+ "filesystem": {+ "name": "filesystem",+ "is_healthy": true,+ "has_errors": false,+ "status": "..."}}}diff --git a/docs/zh/api/19-agent-evolution.md b/docs/zh/api/19-agent-evolution.mdindex 9bcbdb91a..ccc0204dd 100644--- a/docs/zh/api/19-agent-evolution.md+++ b/docs/zh/api/19-agent-evolution.md@@ -1,6 +1,6 @@# Agent 进化-Agent Evolution API 用于查询某条 Experience 被实际应用后的 Trajectory 记录及结果分布。当前仅提供 HTTP API。+Agent Evolution API 用于查询与某条 Experience 成功读取记录关联的 Trajectory 及结果分布。当前仅提供 HTTP API。读取记录用于建立关联,不能据此认定 Agent 遵循了这条经验,或结果由该经验造成。## API 参考@@ -64,7 +64,7 @@ curl -X GET "http://localhost:1933/api/v1/agent-evolution/experiences/trajectori### 查询 Experience 应用结果分布-统计应用过指定 Experience 的 Trajectory 在五种结果状态下的数量。该查询使用精确标量标签聚合,不读取全部 Trajectory 文件。+统计与指定 Experience 读取记录关联的 Trajectory 在五种结果状态下的数量。该查询使用精确标量标签聚合,不读取全部 Trajectory 文件。**代码入口**:diff --git a/docs/zh/api/20-webdav.md b/docs/zh/api/20-webdav.mdindex 44df8f59d..5cddc92ae 100644--- a/docs/zh/api/20-webdav.md+++ b/docs/zh/api/20-webdav.md@@ -4,7 +4,7 @@ WebDAV 为 `resources` 命名空间提供文件协议访问。**代码入口**:`openviking/server/routers/webdav.py`-## WebDAV(Phase 1)+## 支持范围OpenViking Server 也提供了一个面向资源文件的精简 WebDAV 适配层:@@ -12,7 +12,7 @@ OpenViking Server 也提供了一个面向资源文件的精简 WebDAV 适配层/webdav/resources```-Phase 1 有意把范围控制得比较小:+当前支持以下范围:- 仅开放 `resources` 命名空间,不暴露 memories、skills、sessions 等其他空间。- 以文本写入为主,当前 `PUT` 只接受 UTF-8 文本内容。@@ -43,7 +43,7 @@ Phase 1 有意把范围控制得比较小:| 请求头 | 使用方法 | 必填 | 说明 ||--------|----------|------|------|-| `X-API-Key` | 除 `OPTIONS` 外 | 是 | OpenViking API Key |+| `X-API-Key` | 除 `OPTIONS` 外 | 取决于鉴权模式 | OpenViking API Key;trusted 模式还可能需要身份头 || `Depth` | `PROPFIND` | 否 | `0` 仅返回目标;其他值按一级深度处理 || `Destination` | `MOVE` | 是 | `/webdav/resources` 下的目标路径 || `Overwrite` | `MOVE` | 否 | 默认 `T`;设为 `F` 时不覆盖已有目标 |diff --git a/docs/zh/api/22-openviking-assets.md b/docs/zh/api/22-openviking-assets.mdindex bbaf85a45..df9093892 100644--- a/docs/zh/api/22-openviking-assets.md+++ b/docs/zh/api/22-openviking-assets.md@@ -1,9 +1,9 @@# OpenViking Assets ResolverOpenViking Assets Resolver 用于解析并校验-[`openviking-assets/1`](../guides/18-openviking-assets.md) Manifest——既支持在+[`openviking-assets/1`](../guides/18-openviking-assets.md) Manifest。支持在`catalog` 字段中直接定义资产的单文件 Manifest,也支持搭配单独 Catalog 文件的-Manifest——并返回可供客户端执行的标准化资产计划。它不会克隆仓库、创建资源或启动+Manifest,并返回可供客户端执行的标准化资产计划。它不会克隆仓库、创建资源或启动同步任务。通常应直接使用 `ov add-resource --manifest <file>`;CLI 会自动调用 Resolver 和@@ -105,7 +105,7 @@ POST /api/v1/openviking-assets/preflight```该接口在 OpenViking Server 的实际运行环境执行只读 `git ls-remote`,校验仓库和可选 ref-是否可读。它不会克隆仓库、创建资源或启动任务。Manifest 模式在 dry-run 和正式提交之前+是否可读。指定 `commit` 时只验证仓库的 HEAD 可读;精确 SHA 是否存在并可获取,由正式导入时的 fetch/checkout 校验。它不会克隆仓库、创建资源或启动任务。Manifest 模式在 dry-run 和正式提交之前都会调用该接口。### 请求体@@ -116,6 +116,7 @@ POST /api/v1/openviking-assets/preflight| `connector` | string | 是 | 当前必须是 `git` || `repo_url` | string | 是 | Git clone URL || `branch` | string | 否 | 要验证的 branch 或 tag;省略时验证远端 `HEAD` |+| `commit` | string | 否 | 完整的 40 位十六进制 commit SHA,与 `branch` 互斥 || `auth_config.username` | string | 否 | HTTP Basic 用户名,默认 `oauth2` || `auth_config.token` | string | 否 | 一次性 Git token,不持久化 |diff --git a/docs/zh/api/23-agent-runtime.md b/docs/zh/api/23-agent-runtime.mdindex 4ffc99bf0..0d19d5b78 100644--- a/docs/zh/api/23-agent-runtime.md+++ b/docs/zh/api/23-agent-runtime.md@@ -22,6 +22,8 @@ Agent Runtime Server 负责执行 Agent 任务,当前支持 Compile。应用`args` 整体可省略,模型 Endpoint ID 也不是顶层字段。需要指定模型时使用 `args.model_name`;不传时由执行端使用其默认模型配置。+下面的模型选择示例要求执行端支持 `args.model_name`。使用内置 VikingBot 时,省略 `args` 和 CLI 的 `--args`,它不接受非空扩展参数。Python 示例使用 `SyncHTTPClient`;使用 `AsyncHTTPClient` 时需 `await compile()`。+**HTTP API**```http@@ -32,6 +34,7 @@ POST /api/v1/compilecurl -X POST http://localhost:1933/api/v1/compile \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \+ -H "Idempotency-Key: studio-compile-001" \-d '{"from": ["viking://resources/research"],"to": "viking://resources/research-wiki",@@ -157,7 +160,7 @@ curl http://localhost:1933/api/v1/compile/submissions/studio-compile-001 \### 查询任务-任务仅对创建它的 principal 可见;任务不存在或属于其他 principal 时均返回 `404`。+普通用户只能查询自己创建的任务;任务不存在或属于其他用户时均返回 `404`。ROOT 查询使用独立的管理可见范围,且不能取消任务。```httpGET /api/v1/tasks/{task_id}diff --git a/docs/zh/api/24-vikingbot.md b/docs/zh/api/24-vikingbot.mdindex 8e9d0c0b1..a04074123 100644--- a/docs/zh/api/24-vikingbot.md+++ b/docs/zh/api/24-vikingbot.md@@ -77,6 +77,8 @@ curl -X POST http://localhost:1933/bot/v1/chat \**CLI**+`ov chat` 默认通过 `/chat/stream` 流式输出。+```bashov chat -m "总结我的项目进展"```diff --git a/docs/zh/api/99-api-doc-writing-guide.md b/docs/zh/api/99-api-doc-writing-guide.mdindex b9296ccec..1c6aefe0f 100644--- a/docs/zh/api/99-api-doc-writing-guide.md+++ b/docs/zh/api/99-api-doc-writing-guide.md@@ -11,6 +11,15 @@- 外部工具和服务引用官方文档,只介绍当前任务需要的配置,不复制整套手册。- 提交前在 `docs/` 运行 `npm run check:docs`、`npm run check:api` 和 `npm run docs:build`。自动检查覆盖结构与示例,不能替代事实核验和翻译 review。+## 文案标准++- 先说明接口做什么、适用条件和调用结果,再解释实现。读者应能据此决定下一步。+- 用具体动作和对象代替“赋能”“闭环”“智能升级”等空泛表述。术语保留准确含义,不为缩短句子省掉前提。+- 不写无依据的效果、性能、费用或安全承诺。默认值、支持范围和失败行为以当前实现为准;示例值明确标注。+- 区分已提交与已完成、可选与必需、当前能力与规划。总览、参数表、示例和排障说明应一致。+- 中文按自然语序写,英文按英文习惯写;两者保持相同的事实和限制,不逐词硬译。+- 保留有用的章节链接;改标题时检查旧锚点,必要时添加兼容锚点。+## 目录结构API 文档按模块组织,每个模块一个文件,使用两位数字序号前缀。@@ -32,14 +41,9 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号### <API 方法名 1>-#### 1. API 实现介绍+#### 1. 用途与前置条件-<介绍该 API 的用途,指向对应的代码入口,简单介绍原理和流程>--**代码入口**:-- `openviking/<模块>/<文件>.py:<类名>.<方法名>` - 核心实现-- `openviking/server/routers/<路由文件>.py` - HTTP 路由-- `crates/ov_cli/src/commands/<命令文件>.rs` - CLI 命令+<说明接口的操作、适用场景,以及需要的权限、配置或已有资源>#### 2. 接口和参数说明@@ -100,6 +104,10 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号每个公开操作都必须说明成功返回值。JSON 接口至少给出一个与实现一致的响应包示例;文件下载、SSE、WebDAV 等非 JSON 接口必须说明 HTTP 状态、关键响应头、响应体或事件格式。不能只写“返回某些字段”而不展示结构。错误和异常处理示例可按需补充。+#### 5. 实现细节(可选)++按需解释处理流程,并链接到核心实现、HTTP 路由或 CLI 处理函数,帮助读者理解行为或排查问题。+---### <API 方法名 2>@@ -124,18 +132,13 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号### API 参考章节-每个接口按以下三个部分组织:--#### 1. API 实现介绍+每个接口按以下章节组织。实现细节放在响应契约之后,仅保留有助于理解行为或排障的内容。现有页面仍使用旧的“API 实现介绍”章节和代码入口;新页面及迁移页面时按本结构编写。-- 说明该 API 的用途-- 提供代码入口路径,方便读者查阅源码-- 简单介绍实现原理和处理流程+#### 1. 用途与前置条件-**代码入口说明**:-- 核心实现:指向主要业务逻辑代码-- HTTP 路由:指向 FastAPI 路由定义-- CLI 命令:指向 CLI 命令实现(如有)+- 说明接口做什么、适合什么场景。+- 列出必需的权限、配置和已有资源。+- 提前说明调用会产生的影响,包括覆盖或删除已有数据。#### 2. 接口和参数说明@@ -156,8 +159,8 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号示例切换由加粗标签自动生成。调用方式标签必须单独成段,并使用以下固定基础写法:`**Python SDK**`、`**TypeScript SDK**`、`**Go SDK**`、`**HTTP API**`、`**CLI**`。-需要区分调用形态时,可以在同一个加粗标签内追加半角括号限定词,例如-`**Python SDK (HTTP)**`;不要把限定词写在加粗标签外,也不要使用全角括号。+需要区分调用形态时,把限定词用半角括号写在同一个加粗标签内,例如+`**Python SDK (HTTP)**`;不要把限定词写在加粗标签外,也不要使用全角括号。`**Python HTTP SDK**` 这类写法匹配不到 Tab 规则,只会渲染成普通文本。只展示实现中真实存在的调用方式;某个 SDK 或 CLI 没有对应能力时应省略该 Tab,并简短说明可用的替代入口。不要把手写 HTTP 请求包装成不存在的 SDK 方法。@@ -173,24 +176,10 @@ API 文档应按 API 模块和具体接口组织,而不是按客户端语言````markdown### add_resource()-#### 1. API 实现介绍+#### 1. 用途与前置条件向知识库添加资源,支持本地文件、目录、URL 等多种来源。-**处理流程**:-1. 识别资源类型(本地文件/目录/URL)-2. 调用对应 Parser 解析内容-3. 构建目录树并写入 AGFS-4. 异步生成 L0/L1 语义摘要-5. 建立向量索引--**代码入口**:-- `sdk/python/openviking_sdk/client.py:AsyncHTTPClient.add_resource()` - 异步 SDK 入口-- `sdk/python/openviking_sdk/client.py:SyncHTTPClient.add_resource()` - 同步 SDK 入口-- `openviking/service/resource_service.py:ResourceService.add_resource()` - 核心实现-- `openviking/server/routers/resources.py:add_resource()` - HTTP 路由-- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - CLI 处理函数-#### 2. 接口和参数说明**参数**@@ -198,14 +187,14 @@ API 文档应按 API 模块和具体接口组织,而不是按客户端语言| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| path | str | 是 | - | 本地路径、目录路径或 URL |-| to | str | 否 | None | 目标 Viking URI(必须在 resources 作用域内) |+| to | str | 否 | None | 最终资源 URI;目标已存在时会覆盖 || reason | str | 否 | "" | 添加该资源的原因 || wait | bool | 否 | False | 是否等待语义处理完成 |**说明**- SDK/CLI 可直接传本地路径;裸 HTTP 需要先用 `temp_upload` 上传-- 当指定 `to` 且目标已存在时,走增量更新流程+- 已存在的 `to` 目标会被覆盖。目标为目录时,本次导入未生成的旧文件可能被删除;未变化的内容在语义和向量处理中会复用。向已有目录新增资源时使用 `parent`。#### 3. 使用示例@@ -247,20 +236,35 @@ print(client.get_task(result["task_id"]))ov add-resource ./documents/guide.md --reason "User guide documentation"```-**响应示例**+#### 4. 响应契约```json{"status": "ok","result": {"status": "success",- "root_uri": "viking://resources/documents/guide.md",- "task_id": "uuid-xxx",- "errors": []+ "root_uri": "viking://resources/guide",+ "task_id": "uuid-xxx"}}```+#### 5. 实现细节++**处理流程**:+1. 识别资源类型(本地文件/目录/URL)+2. 调用对应 Parser 解析内容+3. 构建目录树并写入 AGFS+4. 异步生成 L0/L1 语义摘要+5. 建立向量索引++**代码入口**:+- `sdk/python/openviking_sdk/client.py:AsyncHTTPClient.add_resource()` - 异步 SDK 入口+- `sdk/python/openviking_sdk/client.py:SyncHTTPClient.add_resource()` - 同步 SDK 入口+- `openviking/service/resource_service.py:ResourceService.add_resource()` - 核心实现+- `openviking/server/routers/resources.py:add_resource()` - HTTP 路由+- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - CLI 处理函数+---````@@ -268,7 +272,7 @@ ov add-resource ./documents/guide.md --reason "User guide documentation"新增或修改 API 文档时,请检查:-- [ ] 实现介绍清晰,代码入口路径正确+- [ ] 用途、前置条件和调用影响清楚,引用的代码入口路径正确- [ ] 参数表完整且准确- [ ] 示例代码简洁且可运行- [ ] 调用示例使用固定加粗标签,并且每个 SDK/CLI Tab 都有真实实现