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): align reference docs with current server behavior (#1483)
Qin Haojieb43cf313f5d5
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.mdindex 80982a5f7..19d74bd5d 100644--- a/docs/en/api/01-overview.md+++ b/docs/en/api/01-overview.md@@ -280,6 +280,7 @@ Compact JSON with status wrapper (when `--compact` is true, which is the default| Method | Path | Description ||--------|------|-------------|| GET | `/health` | Health check (no auth) |+| GET | `/ready` | Readiness probe (no auth) || GET | `/metrics` | Prometheus metrics export || GET | `/api/v1/system/status` | System status || POST | `/api/v1/system/wait` | Wait for processing |@@ -288,6 +289,7 @@ Compact JSON with status wrapper (when `--compact` is true, which is the default| Method | Path | Description ||--------|------|-------------|+| POST | `/api/v1/resources/temp_upload` | Upload local file for raw HTTP resource / pack import || POST | `/api/v1/resources` | Add resource || POST | `/api/v1/skills` | Add skill || POST | `/api/v1/pack/export` | Export .ovpack |@@ -311,7 +313,9 @@ Compact JSON with status wrapper (when `--compact` is true, which is the default| GET | `/api/v1/content/read` | Read full content (L2) || GET | `/api/v1/content/abstract` | Read abstract (L0) || GET | `/api/v1/content/overview` | Read overview (L1) |+| GET | `/api/v1/content/download` | Download raw file bytes || POST | `/api/v1/content/write` | Update an existing file and refresh semantics/vectors |+| POST | `/api/v1/content/reindex` | Rebuild semantic/vector index for existing content |### Search@@ -340,7 +344,16 @@ Compact JSON with status wrapper (when `--compact` is true, which is the default| GET | `/api/v1/sessions/{id}/context` | Get assembled session context || DELETE | `/api/v1/sessions/{id}` | Delete session || POST | `/api/v1/sessions/{id}/commit` | Commit session |+| POST | `/api/v1/sessions/{id}/extract` | Extract memories from a session || POST | `/api/v1/sessions/{id}/messages` | Add message |+| POST | `/api/v1/sessions/{id}/used` | Record contexts / skills actually used |++### Tasks++| Method | Path | Description |+|--------|------|-------------|+| GET | `/api/v1/tasks/{task_id}` | Get background task status |+| GET | `/api/v1/tasks` | List background tasks |### Observer@@ -348,9 +361,18 @@ Compact JSON with status wrapper (when `--compact` is true, which is the default|--------|------|-------------|| GET | `/api/v1/observer/queue` | Queue status || GET | `/api/v1/observer/vikingdb` | VikingDB status |-| GET | `/api/v1/observer/vlm` | VLM status |+| GET | `/api/v1/observer/models` | Models status (VLM / embedding / rerank) |+| GET | `/api/v1/observer/lock` | Lock subsystem status |+| GET | `/api/v1/observer/retrieval` | Retrieval subsystem status || GET | `/api/v1/observer/system` | System status |++### Debug++| Method | Path | Description |+|--------|------|-------------|| GET | `/api/v1/debug/health` | Quick health check |+| GET | `/api/v1/debug/vector/scroll` | Paginated vector record inspection |+| GET | `/api/v1/debug/vector/count` | Count vector records |### Admin (Multi-tenant)diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.mdindex 409a96d13..71421350f 100644--- a/docs/en/api/02-resources.md+++ b/docs/en/api/02-resources.md@@ -42,12 +42,15 @@ Add a resource to the knowledge base.|-----------|------|----------|---------|-------------|| path | str | Yes | - | SDK/CLI: local path, directory path, or URL. Raw HTTP: remote URL only || temp_file_id | str | No | None | Upload ID returned by `POST /api/v1/resources/temp_upload` for raw HTTP local file ingestion |-| target | str | No | None | Target Viking URI (must be in `resources` scope) |+| to | str | No | None | Exact target Viking URI (must be in `resources` scope) |+| parent | str | No | None | Parent URI under which the resource will be stored. Cannot be combined with `to` || reason | str | No | "" | Why this resource is being added (improves search relevance) || instruction | str | No | "" | Special processing instructions || wait | bool | No | False | Wait for semantic processing to complete || timeout | float | No | None | Timeout in seconds (only used when wait=True) |-| watch_interval | float | No | 0 | Watch interval (minutes). >0 enables/updates watch; <=0 disables watch. Only takes effect when target is provided |+| watch_interval | float | No | 0 | Watch interval (minutes). >0 enables/updates watch; <=0 disables watch. Only takes effect when `to` is provided |++`POST /api/v1/resources` uses `to` in JSON. CLI uses `--to`.**How local files and directories work**@@ -62,13 +65,13 @@ Add a resource to the knowledge base.When you call `add_resource()` repeatedly for the same resource URI, the system performs an incremental update instead of rebuilding everything from scratch:-- **Trigger**: `target` is provided and already exists in the knowledge base.-- **High-level idea**: each ingestion first builds a temporary resource tree from the new input. During asynchronous semantic processing, the temporary tree is compared against the existing tree at `target`, and only the changed parts are re-processed and synchronized.+- **Trigger**: `to` is provided and already exists in the knowledge base.+- **High-level idea**: each ingestion first builds a temporary resource tree from the new input. During asynchronous semantic processing, the temporary tree is compared against the existing tree at `to`, and only the changed parts are re-processed and synchronized.- **Incremental behavior in the semantic stage**:- **Unchanged files**: reuse existing L0 summaries and vector index records; skip vectorization.- **Changed files**: regenerate summaries and vector index entries.- **Directory-level L0/L1 (abstract/overview)**: if the child set and their change status are unchanged, reuse existing results and skip vectorization; otherwise recompute and update.-- **Filesystem + index sync**: after the semantic DAG finishes, a top-down diff is applied from the temporary tree to `target` to synchronize additions, deletions, and updates. Vector store records are kept consistent: deletions remove corresponding vectors, while moves/overwrites update vector records’ URI mapping, completing an incremental update of both the resource tree and the semantic index.+- **Filesystem + index sync**: after the semantic DAG finishes, a top-down diff is applied from the temporary tree to `to` to synchronize additions, deletions, and updates. Vector store records are kept consistent: deletions remove corresponding vectors, while moves/overwrites update vector records’ URI mapping, completing an incremental update of both the resource tree and the semantic index.**Python SDK (Embedded / HTTP)**@@ -126,7 +129,7 @@ openviking add-resource ./documents/guide.md --reason "User guide documentation"```pythonresult = client.add_resource("https://example.com/api-docs.md",- target="viking://resources/external/",+ to="viking://resources/external/",reason="External API documentation")client.wait_processed()@@ -140,7 +143,7 @@ curl -X POST http://localhost:1933/api/v1/resources \-H "X-API-Key: your-key" \-d '{"path": "https://example.com/api-docs.md",- "target": "viking://resources/external/",+ "to": "viking://resources/external/","reason": "External API documentation","wait": true}'@@ -299,18 +302,18 @@ openviking add-resource ./documents/guide.md --wait`watch_interval` is in minutes and periodically triggers re-processing for the specified target URI:-- `watch_interval > 0`: create (or reactivate and update) a watch task for the `target`-- `watch_interval <= 0`: disable (deactivate) the watch task for the `target`-- watch tasks are only managed when `target` / CLI `--to` is provided+- `watch_interval > 0`: create (or reactivate and update) a watch task for the `to`+- `watch_interval <= 0`: disable (deactivate) the watch task for the `to`+- watch tasks are only managed when `to` / CLI `--to` is provided-If there is already an active watch task for the same `target`, submitting another request with `watch_interval > 0` returns a conflict error. Disable it first (`watch_interval = 0`) and then set a new interval.+If there is already an active watch task for the same `to`, submitting another request with `watch_interval > 0` returns a conflict error. Disable it first (`watch_interval = 0`) and then set a new interval.**Python SDK (Embedded / HTTP)**```pythonclient.add_resource("./documents/guide.md",- target="viking://resources/documents/guide.md",+ to="viking://resources/documents/guide.md",watch_interval=60,)```@@ -323,7 +326,7 @@ curl -X POST http://localhost:1933/api/v1/resources \-H "X-API-Key: your-key" \-d '{"path": "https://example.com/guide.md",- "target": "viking://resources/documents/guide.md",+ "to": "viking://resources/documents/guide.md","watch_interval": 60}'```@@ -343,13 +346,19 @@ openviking add-resource ./documents/guide.md --to viking://resources/documents/gExport a resource tree as a `.ovpack` file.-**Parameters**+**SDK / CLI parameters**| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI to export || to | str | Yes | - | Target file path |+**Raw HTTP request body**++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| uri | str | Yes | - | Viking URI to export |+**Python SDK (Embedded / HTTP)**```python@@ -371,8 +380,7 @@ curl -X POST http://localhost:1933/api/v1/pack/export \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \-d '{- "uri": "viking://resources/my-project/",- "to": "./exports/my-project.ovpack"+ "uri": "viking://resources/my-project/"}'```@@ -384,15 +392,7 @@ openviking export viking://resources/my-project/ ./exports/my-project.ovpack**Response**-```json-{- "status": "ok",- "result": {- "file": "./exports/my-project.ovpack"- },- "time": 0.1-}-```+The HTTP API streams the `.ovpack` file directly as a download (`Content-Type: application/zip`). It does not return a JSON envelope for this endpoint.---diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.mdindex 1fce1976e..78abfd589 100644--- a/docs/en/api/03-filesystem.md+++ b/docs/en/api/03-filesystem.md@@ -127,6 +127,8 @@ Read L2 full content.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI |+| offset | int | No | 0 | Starting line number (0-indexed) |+| limit | int | No | -1 | Number of lines to read, `-1` means read to end |**Python SDK (Embedded / HTTP)**@@ -264,6 +266,11 @@ List directory contents.| uri | str | Yes | - | Viking URI || simple | bool | No | False | Return only relative paths || recursive | bool | No | False | List all subdirectories recursively |+| output | str | No | `agent` | Output format: `agent` or `original` |+| abs_limit | int | No | 256 | Abstract length limit for `agent` output |+| show_all_hidden | bool | No | False | Include hidden files like `-a` |+| node_limit | int | No | 1000 | Maximum number of nodes to return |+| limit | int | No | None | Alias for `node_limit` |**Entry Structure**@@ -344,6 +351,12 @@ Get directory tree structure.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| uri | str | Yes | - | Viking URI |+| output | str | No | `agent` | Output format: `agent` or `original` |+| abs_limit | int | No | 256 | Abstract length limit for `agent` output |+| show_all_hidden | bool | No | False | Include hidden files like `-a` |+| node_limit | int | No | 1000 | Maximum number of nodes to return |+| limit | int | No | None | Alias for `node_limit` |+| level_limit | int | No | 3 | Maximum directory depth to traverse |**Python SDK (Embedded / HTTP)**@@ -632,6 +645,9 @@ Search content by pattern.| uri | str | Yes | - | Viking URI to search in || pattern | str | Yes | - | Search pattern (regex) || case_insensitive | bool | No | False | Ignore case |+| exclude_uri | str | No | None | URI prefix to exclude from search |+| node_limit | int | No | None | Maximum number of nodes to search |+| level_limit | int | No | 5 | Maximum directory depth to traverse |**Python SDK (Embedded / HTTP)**@@ -702,6 +718,7 @@ Match files by pattern.|-----------|------|----------|---------|-------------|| pattern | str | Yes | - | Glob pattern (e.g., `**/*.md`) || uri | str | No | "viking://" | Starting URI |+| node_limit | int | No | None | Maximum number of matches to return |**Python SDK (Embedded / HTTP)**@@ -766,7 +783,7 @@ Create relations between resources.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| from_uri | str | Yes | - | Source URI |-| uris | str or List[str] | Yes | - | Target URI(s) |+| to_uris | str or List[str] | Yes | - | Target URI(s) || reason | str | No | "" | Reason for the link |**Python SDK (Embedded / HTTP)**@@ -899,7 +916,7 @@ Remove a relation.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| from_uri | str | Yes | - | Source URI |-| uri | str | Yes | - | Target URI to unlink |+| to_uri | str | Yes | - | Target URI to unlink |**Python SDK (Embedded / HTTP)**diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.mdindex c2341e2c4..b1d31f9f3 100644--- a/docs/en/api/05-sessions.md+++ b/docs/en/api/05-sessions.md@@ -58,7 +58,11 @@ openviking session new"status": "ok","result": {"session_id": "a1b2c3d4",- "user": "alice"+ "user": {+ "account_id": "default",+ "user_id": "alice",+ "agent_id": "default"+ }},"time": 0.1}@@ -73,9 +77,9 @@ List all sessions.**Python SDK (Embedded / HTTP)**```python-sessions = client.ls("viking://session/")+sessions = client.list_sessions()for s in sessions:- print(f"{s['name']}")+ print(f"{s['session_id']} -> {s['uri']}")```**HTTP API**@@ -101,8 +105,8 @@ openviking session list{"status": "ok","result": [- {"session_id": "a1b2c3d4", "user": "alice"},- {"session_id": "e5f6g7h8", "user": "bob"}+ {"session_id": "a1b2c3d4", "uri": "viking://session/alice/a1b2c3d4", "is_dir": true},+ {"session_id": "e5f6g7h8", "uri": "viking://session/alice/e5f6g7h8", "is_dir": true}],"time": 0.1}@@ -178,6 +182,7 @@ openviking session get a1b2c3d4"total_tokens": 7000},"user": {+ "account_id": "default","user_id": "alice","agent_id": "default"}@@ -430,6 +435,7 @@ Add a message to the session.| role | str | Yes | - | Message role: "user" or "assistant" || parts | List[Part] | Conditional | - | List of message parts (Required for Python SDK; Optional for HTTP API, mutually exclusive with content) || content | str | Conditional | - | Message text content (HTTP API simple mode, mutually exclusive with parts) |+| created_at | str | No | None | Optional ISO 8601 timestamp to persist on the message |> **Note**: HTTP API supports two modes:> 1. **Simple mode**: Use `content` string (backward compatible)@@ -456,7 +462,7 @@ ContextPart(ToolPart(tool_id="call_123",tool_name="search_web",- skill_uri="viking://skills/search-web/",+ skill_uri="viking://agent/skills/search-web/",tool_input={"query": "OAuth best practices"},tool_output="",tool_status="pending" # "pending", "running", "completed", "error"@@ -571,7 +577,7 @@ session.used(contexts=["viking://resources/docs/auth/"])# Record used skillsession.used(skill={- "uri": "viking://skills/search-web/",+ "uri": "viking://agent/skills/search-web/","input": {"query": "OAuth"},"output": "Results...","success": True@@ -595,7 +601,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \- -d '{"skill": {"uri": "viking://skills/search-web/", "input": {"query": "OAuth"}, "output": "Results...", "success": true}}'+ -d '{"skill": {"uri": "viking://agent/skills/search-web/", "input": {"query": "OAuth"}, "output": "Results...", "success": true}}'```**Response**@@ -686,6 +692,34 @@ openviking session commit a1b2c3d4---+### extract()++HTTP API only. Trigger memory extraction immediately for an existing session without creating a new commit task.++**Parameters**++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| session_id | str | Yes | - | Session ID to extract memories from |++**HTTP API**++```+POST /api/v1/sessions/{session_id}/extract+```++```bash+curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/extract \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key"+```++**Response**++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.++---+### get_task()Query background task status (e.g., commit summary generation and memory extraction progress).@@ -755,6 +789,52 @@ curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \---+### list_tasks()++HTTP API only. List background tasks visible to the current caller.++**Parameters**++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| task_type | str | No | None | Filter by task type, for example `session_commit` |+| status | str | No | None | Filter by task status: `pending`, `running`, `completed`, `failed` |+| resource_id | str | No | None | Filter by task resource ID, for example a session ID |+| limit | int | No | 50 | Maximum number of task records to return |++**HTTP API**++```+GET /api/v1/tasks+```++```bash+curl -X GET "http://localhost:1933/api/v1/tasks?task_type=session_commit&status=running&limit=20" \+ -H "X-API-Key: your-key"+```++**Response**++```json+{+ "status": "ok",+ "result": [+ {+ "task_id": "uuid-xxx",+ "task_type": "session_commit",+ "status": "running",+ "resource_id": "a1b2c3d4",+ "created_at": 1770000000.0,+ "updated_at": 1770000005.0,+ "result": null,+ "error": null+ }+ ]+}+```++---+## Session Properties| Property | Type | Description |diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.mdindex c3559a9c9..580b132ee 100644--- a/docs/en/api/06-retrieval.md+++ b/docs/en/api/06-retrieval.md@@ -25,11 +25,14 @@ Basic vector similarity search.| query | str | Yes | - | Search query string || target_uri | str | No | "" | Limit search to specific URI prefix || limit | int | No | 10 | Maximum number of results |+| node_limit | int | No | None | Optional HTTP alias that overrides `limit` when provided || score_threshold | float | No | None | Minimum relevance score threshold || filter | Dict | No | None | Metadata filters |-| since | str | No | None | Lower time bound, accepts `2h` or ISO 8601 / `YYYY-MM-DD`, timezone-less values use local time. CLI `--after` maps to this field |-| until | str | No | None | Upper time bound, accepts `30m` or ISO 8601 / `YYYY-MM-DD`, timezone-less values use local time. CLI `--before` maps to this field |+| 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"` or `"created_at"` | No | `"updated_at"` | Metadata time field used by `since` / `until` |+| include_provenance | bool | No | False | Include provenance/query-plan details in the serialized result |+| telemetry | bool or object | No | False | Attach telemetry data to the response |**FindResult Structure**@@ -146,7 +149,7 @@ results = client.find(# Search only in skillsresults = client.find("web search",- target_uri="viking://skills/"+ target_uri="viking://agent/skills/")# Search in specific project@@ -195,11 +198,14 @@ Search with session context and intent analysis.| session | Session | No | None | Session for context-aware search (SDK) || session_id | str | No | None | Session ID for context-aware search (HTTP) || limit | int | No | 10 | Maximum number of results |+| node_limit | int | No | None | Optional HTTP alias that overrides `limit` when provided || score_threshold | float | No | None | Minimum relevance score threshold || filter | Dict | No | None | Metadata filters |-| since | str | No | None | Lower time bound, accepts `2h` or ISO 8601 / `YYYY-MM-DD`, timezone-less values use local time. CLI `--after` maps to this field |-| until | str | No | None | Upper time bound, accepts `30m` or ISO 8601 / `YYYY-MM-DD`, timezone-less values use local time. CLI `--before` maps to this field |+| 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"` or `"created_at"` | No | `"updated_at"` | Metadata time field used by `since` / `until` |+| include_provenance | bool | No | False | Include provenance/query-plan details in the serialized result |+| telemetry | bool or object | No | False | Attach telemetry data to the response |**Python SDK (Embedded / HTTP)**@@ -321,8 +327,9 @@ Search content by pattern (regex).| uri | str | Yes | - | Viking URI to search in || pattern | str | Yes | - | Search pattern (regex) || case_insensitive | bool | No | False | Ignore case |-| node_limit | int | No | None | Maximum number of nodes to search || exclude_uri | str | No | None | URI prefix to exclude from search |+| node_limit | int | No | None | Maximum number of nodes to search |+| level_limit | int | No | 5 | Maximum directory depth to traverse |**Python SDK (Embedded / HTTP)**@@ -393,6 +400,7 @@ Match files by glob pattern.|-----------|------|----------|---------|-------------|| pattern | str | Yes | - | Glob pattern (e.g., `**/*.md`) || uri | str | No | "viking://" | Starting URI |+| node_limit | int | No | None | Maximum number of matches to return |**Python SDK (Embedded / HTTP)**diff --git a/docs/en/api/07-system.md b/docs/en/api/07-system.mdindex adad373ec..03bedbab7 100644--- a/docs/en/api/07-system.md+++ b/docs/en/api/07-system.md@@ -36,7 +36,39 @@ openviking health```json{- "status": "ok"+ "status": "ok",+ "healthy": true,+ "version": "0.1.x"+}+```++---++### ready()++Readiness probe for deployment environments. Returns `200` when core subsystems are ready and `503` otherwise.++**HTTP API**++```+GET /ready+```++```bash+curl -X GET http://localhost:1933/ready+```++**Response**++```json+{+ "status": "ready",+ "checks": {+ "agfs": "ok",+ "vectordb": "ok",+ "api_key_manager": "ok",+ "ollama": "not_configured"+ }}```@@ -132,10 +164,18 @@ openviking wait [--timeout 60]{"status": "ok","result": {- "pending": 0,- "in_progress": 0,- "processed": 20,- "errors": 0+ "Embedding": {+ "processed": 10,+ "requeue_count": 0,+ "error_count": 0,+ "errors": []+ },+ "Semantic": {+ "processed": 10,+ "requeue_count": 0,+ "error_count": 0,+ "errors": []+ }},"time": 0.1}@@ -250,36 +290,37 @@ openviking observer vikingdb----### observer.vlm+### observer.models-Get VLM (Vision Language Model) token usage status.+Get aggregated model subsystem status (VLM, embedding, rerank).**Python SDK (Embedded / HTTP)**```python-print(client.observer.vlm)+print(client.observer.models)# Output:-# [vlm] (healthy)-# Model Provider Prompt Completion Total Last Updated-# doubao-1-5-vision-pro-32k volcengine 1000 500 1500 2024-01-01 12:00:00-# TOTAL 1000 500 1500+# [models] (healthy)+# provider_model healthy detail+# dense_embedding yes ...+# rerank yes ...+# vlm yes ...```**HTTP API**```-GET /api/v1/observer/vlm+GET /api/v1/observer/models``````bash-curl -X GET http://localhost:1933/api/v1/observer/vlm \+curl -X GET http://localhost:1933/api/v1/observer/models \-H "X-API-Key: your-key"```**CLI**```bash-openviking observer vlm+openviking observer models```**Response**@@ -288,10 +329,10 @@ openviking observer vlm{"status": "ok","result": {- "name": "vlm",+ "name": "models","is_healthy": true,"has_errors": false,- "status": "Model Provider Prompt Completion Total Last Updated\ndoubao-1-5-vision-pro-32k volcengine 1000 500 1500 2024-01-01 12:00:00\nTOTAL 1000 500 1500"+ "status": "provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ..."},"time": 0.1}@@ -299,6 +340,11 @@ openviking observer vlm---+Additional HTTP observer endpoints are also available:++- `GET /api/v1/observer/lock`+- `GET /api/v1/observer/retrieval`+### observer.systemGet overall system status including all components.@@ -314,7 +360,7 @@ print(client.observer.system())# [vikingdb] (healthy)# ...#-# [vlm] (healthy)+# [models] (healthy)# ...## [system] (healthy)diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex 7b5949e6d..7887400eb 100644--- a/docs/zh/api/01-overview.md+++ b/docs/zh/api/01-overview.md@@ -281,6 +281,7 @@ openviking -o json ls viking://resources/| 方法 | 路径 | 说明 ||------|------|------|| GET | `/health` | 健康检查(无需认证) |+| GET | `/ready` | 就绪探针(无需认证) || GET | `/metrics` | Prometheus 指标导出 || GET | `/api/v1/system/status` | 系统状态 || POST | `/api/v1/system/wait` | 等待处理完成 |@@ -289,6 +290,7 @@ openviking -o json ls viking://resources/| 方法 | 路径 | 说明 ||------|------|------|+| POST | `/api/v1/resources/temp_upload` | 裸 HTTP 导入资源 / pack 时上传本地文件 || POST | `/api/v1/resources` | 添加资源 || POST | `/api/v1/skills` | 添加技能 || POST | `/api/v1/pack/export` | 导出 .ovpack |@@ -312,7 +314,9 @@ openviking -o json ls viking://resources/| GET | `/api/v1/content/read` | 读取完整内容(L2) || GET | `/api/v1/content/abstract` | 读取摘要(L0) || GET | `/api/v1/content/overview` | 读取概览(L1) |+| GET | `/api/v1/content/download` | 下载原始文件字节流 || POST | `/api/v1/content/write` | 修改已有文件并自动刷新语义与向量 |+| POST | `/api/v1/content/reindex` | 重新构建已有内容的语义/向量索引 |### 搜索@@ -341,7 +345,16 @@ openviking -o json ls viking://resources/| GET | `/api/v1/sessions/{id}/context` | 获取组装后的会话上下文 || DELETE | `/api/v1/sessions/{id}` | 删除会话 || POST | `/api/v1/sessions/{id}/commit` | 提交会话 |+| POST | `/api/v1/sessions/{id}/extract` | 从会话提取记忆 || POST | `/api/v1/sessions/{id}/messages` | 添加消息 |+| POST | `/api/v1/sessions/{id}/used` | 记录实际使用的上下文 / 技能 |++### 任务++| 方法 | 路径 | 说明 |+|------|------|------|+| GET | `/api/v1/tasks/{task_id}` | 获取后台任务状态 |+| GET | `/api/v1/tasks` | 列出后台任务 |### Observer@@ -349,9 +362,18 @@ openviking -o json ls viking://resources/|------|------|------|| GET | `/api/v1/observer/queue` | 队列状态 || GET | `/api/v1/observer/vikingdb` | VikingDB 状态 |-| GET | `/api/v1/observer/vlm` | VLM 状态 |+| GET | `/api/v1/observer/models` | 模型状态(VLM / embedding / rerank) |+| GET | `/api/v1/observer/lock` | 锁子系统状态 |+| GET | `/api/v1/observer/retrieval` | 检索子系统状态 || GET | `/api/v1/observer/system` | 系统状态 |++### 调试++| 方法 | 路径 | 说明 |+|------|------|------|| GET | `/api/v1/debug/health` | 快速健康检查 |+| GET | `/api/v1/debug/vector/scroll` | 分页查看向量记录 |+| GET | `/api/v1/debug/vector/count` | 统计向量记录数量 |### 管理员(多租户)diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.mdindex 04a9c184d..de0d9f28b 100644--- a/docs/zh/api/02-resources.md+++ b/docs/zh/api/02-resources.md@@ -42,12 +42,15 @@ Input -> Parser -> TreeBuilder -> AGFS -> SemanticQueue -> Vector Index|------|------|------|--------|------|| path | str | 是 | - | SDK/CLI 可传本地路径、目录路径或 URL;裸 HTTP 仅支持远端 URL || temp_file_id | str | 否 | None | `POST /api/v1/resources/temp_upload` 返回的上传 ID,用于裸 HTTP 导入本地文件 |-| target | str | 否 | None | 目标 Viking URI(必须在 `resources` 作用域内) |+| to | str | 否 | None | 精确目标 Viking URI(必须在 `resources` 作用域内) |+| parent | str | 否 | None | 资源将被放入的父级 URI,不能与 `to` 同时使用 || reason | str | 否 | "" | 添加该资源的原因(可提升搜索相关性) || instruction | str | 否 | "" | 特殊处理指令 || wait | bool | 否 | False | 等待语义处理完成 || timeout | float | 否 | None | 超时时间(秒),仅在 wait=True 时生效 |-| watch_interval | float | 否 | 0 | 定时更新间隔(分钟)。>0 开启/更新定时任务;<=0 关闭(停用)定时任务。仅在指定 target 时生效 |+| watch_interval | float | 否 | 0 | 定时更新间隔(分钟)。>0 开启/更新定时任务;<=0 关闭(停用)定时任务。仅在指定 `to` 时生效 |++`POST /api/v1/resources` 的 JSON 字段名是 `to`;CLI 对应参数是 `--to`。**本地文件和目录如何处理**@@ -62,13 +65,13 @@ Input -> Parser -> TreeBuilder -> AGFS -> SemanticQueue -> Vector Index当你为同一个资源 URI 反复调用 `add_resource()` 时,系统会走“增量更新”而不是每次全量重建:-- **触发条件**:请求里显式指定 `target`,且该 `target` 在知识库中已存在。-- **总体思路**:每次导入都会先把新内容解析/构建成一棵“临时资源树”,随后在异步语义处理阶段,将临时树与 `target` 对应的现有资源树进行对比,只对发生变化的部分做重算与同步。+- **触发条件**:请求里显式指定 `to`,且该 `to` 在知识库中已存在。+- **总体思路**:每次导入都会先把新内容解析/构建成一棵“临时资源树”,随后在异步语义处理阶段,将临时树与 `to` 对应的现有资源树进行对比,只对发生变化的部分做重算与同步。- **语义阶段的增量**:- 对**未变化的文件**:复用已有 L0(摘要)与向量索引记录,跳过向量化。- 对**发生变化的文件**:重新生成摘要/向量索引。- 对**目录级 L0/L1(abstract/overview)**:若目录下子项及其变更状态不变,则复用已有结果并跳过向量化;否则重算并更新。-- **落盘与索引同步**:语义 DAG 结束后会对临时树与 `target` 做一次 top-down diff,同步三类变更:新增(添加新文件/目录)、删除(移除消失项)、更新(覆盖变化项)。同步过程中会同时联动更新向量库中的记录:删除项会删除对应向量记录;移动/覆盖会同步更新向量记录的 URI 映射,从而完成“文件树与向量索引的一致性增量更新”。+- **落盘与索引同步**:语义 DAG 结束后会对临时树与 `to` 做一次 top-down diff,同步三类变更:新增(添加新文件/目录)、删除(移除消失项)、更新(覆盖变化项)。同步过程中会同时联动更新向量库中的记录:删除项会删除对应向量记录;移动/覆盖会同步更新向量记录的 URI 映射,从而完成“文件树与向量索引的一致性增量更新”。**Python SDK (Embedded / HTTP)**@@ -126,7 +129,7 @@ openviking add-resource ./documents/guide.md --reason "User guide documentation"```pythonresult = client.add_resource("https://example.com/api-docs.md",- target="viking://resources/external/",+ to="viking://resources/external/",reason="External API documentation")client.wait_processed()@@ -140,7 +143,7 @@ curl -X POST http://localhost:1933/api/v1/resources \-H "X-API-Key: your-key" \-d '{"path": "https://example.com/api-docs.md",- "target": "viking://resources/external/",+ "to": "viking://resources/external/","reason": "External API documentation","wait": true}'@@ -251,7 +254,7 @@ openviking add-resource "https://example.feishu.cn/docx/doxcnABC123" --reason "# 导入知识库页面openviking add-resource "https://example.feishu.cn/wiki/wikiXYZ"-# 增量更新到已有 target+# 增量更新到已有 URIopenviking add-resource "https://example.feishu.cn/docx/doxcnABC123" --to viking://resources/design-doc```@@ -297,20 +300,20 @@ openviking add-resource ./documents/guide.md --wait**示例:开启定时更新(watch_interval)**-`watch_interval` 的单位为分钟,用于对指定的目标 URI 定期触发更新处理:+`watch_interval` 的单位为分钟,用于对指定目标 URI 定期触发更新处理:-- `watch_interval > 0`:创建(或重新激活并更新)该 `target` 的定时任务-- `watch_interval <= 0`:关闭(停用)该 `target` 的定时任务-- 只有在指定 `target` / CLI `--to` 时才会创建定时任务+- `watch_interval > 0`:创建(或重新激活并更新)该 `to` 的定时任务+- `watch_interval <= 0`:关闭(停用)该 `to` 的定时任务+- 只有在指定 `to` / CLI `--to` 时才会创建定时任务-如果同一个 `target` 已存在激活中的定时任务,再次以 `watch_interval > 0` 提交会返回冲突错误;需要先将 `watch_interval` 设为 `0`(取消/停用)后再重新设置新的间隔。+如果同一个 `to` 已存在激活中的定时任务,再次以 `watch_interval > 0` 提交会返回冲突错误;需要先将 `watch_interval` 设为 `0`(取消/停用)后再重新设置新的间隔。**Python SDK (Embedded / HTTP)**```pythonclient.add_resource("./documents/guide.md",- target="viking://resources/documents/guide.md",+ to="viking://resources/documents/guide.md",watch_interval=60,)```@@ -323,7 +326,7 @@ curl -X POST http://localhost:1933/api/v1/resources \-H "X-API-Key: your-key" \-d '{"path": "https://example.com/guide.md",- "target": "viking://resources/documents/guide.md",+ "to": "viking://resources/documents/guide.md","watch_interval": 60}'```@@ -343,13 +346,19 @@ openviking add-resource ./documents/guide.md --to viking://resources/documents/g将资源树导出为 `.ovpack` 文件。-**参数**+**SDK / CLI 参数**| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| uri | str | 是 | - | 要导出的 Viking URI || to | str | 是 | - | 目标文件路径 |+**裸 HTTP 请求体**++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| uri | str | 是 | - | 要导出的 Viking URI |+**Python SDK (Embedded / HTTP)**```python@@ -371,8 +380,7 @@ curl -X POST http://localhost:1933/api/v1/pack/export \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \-d '{- "uri": "viking://resources/my-project/",- "to": "./exports/my-project.ovpack"+ "uri": "viking://resources/my-project/"}'```@@ -384,15 +392,7 @@ openviking export viking://resources/my-project/ ./exports/my-project.ovpack**响应**-```json-{- "status": "ok",- "result": {- "file": "./exports/my-project.ovpack"- },- "time": 0.1-}-```+该 HTTP 接口会直接以下载流的形式返回 `.ovpack` 文件(`Content-Type: application/zip`),不会返回 JSON 包装体。---diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.mdindex 79bd9040c..bb0960889 100644--- a/docs/zh/api/03-filesystem.md+++ b/docs/zh/api/03-filesystem.md@@ -127,6 +127,8 @@ openviking overview viking://resources/docs/| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| uri | str | 是 | - | Viking URI |+| offset | int | 否 | 0 | 起始行号(0 开始) |+| limit | int | 否 | -1 | 读取的行数,`-1` 表示读到结尾 |**Python SDK (Embedded / HTTP)**@@ -264,6 +266,11 @@ openviking write viking://resources/docs/api.md \| uri | str | 是 | - | Viking URI || simple | bool | 否 | False | 仅返回相对路径 || recursive | bool | 否 | False | 递归列出所有子目录 |+| output | str | 否 | `agent` | 输出格式:`agent` 或 `original` |+| abs_limit | int | 否 | 256 | `agent` 输出中的摘要长度限制 |+| show_all_hidden | bool | 否 | False | 像 `-a` 一样包含隐藏文件 |+| node_limit | int | 否 | 1000 | 最大返回节点数 |+| limit | int | 否 | None | `node_limit` 的别名 |**条目结构**@@ -344,6 +351,12 @@ openviking ls viking://resources/ [--simple] [--recursive]| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| uri | str | 是 | - | Viking URI |+| output | str | 否 | `agent` | 输出格式:`agent` 或 `original` |+| abs_limit | int | 否 | 256 | `agent` 输出中的摘要长度限制 |+| show_all_hidden | bool | 否 | False | 像 `-a` 一样包含隐藏文件 |+| node_limit | int | 否 | 1000 | 最大返回节点数 |+| limit | int | 否 | None | `node_limit` 的别名 |+| level_limit | int | 否 | 3 | 最大目录遍历深度 |**Python SDK (Embedded / HTTP)**@@ -632,6 +645,9 @@ openviking mv viking://resources/old-name/ viking://resources/new-name/| uri | str | 是 | - | 要搜索的 Viking URI || pattern | str | 是 | - | 搜索模式(正则表达式) || case_insensitive | bool | 否 | False | 忽略大小写 |+| exclude_uri | str | 否 | None | 搜索时要排除的 URI 前缀 |+| node_limit | int | 否 | None | 最大搜索节点数 |+| level_limit | int | 否 | 5 | 最大目录遍历深度 |**Python SDK (Embedded / HTTP)**@@ -702,6 +718,7 @@ openviking grep viking://resources/ "authentication" [--ignore-case]|------|------|------|--------|------|| pattern | str | 是 | - | Glob 模式(例如 `**/*.md`) || uri | str | 否 | "viking://" | 起始 URI |+| node_limit | int | 否 | None | 最大返回匹配数 |**Python SDK (Embedded / HTTP)**@@ -766,7 +783,7 @@ openviking glob "**/*.md" [--uri viking://resources/]| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| from_uri | str | 是 | - | 源 URI |-| uris | str 或 List[str] | 是 | - | 目标 URI |+| to_uris | str 或 List[str] | 是 | - | 目标 URI || reason | str | 否 | "" | 关联原因 |**Python SDK (Embedded / HTTP)**@@ -899,7 +916,7 @@ openviking relations viking://resources/docs/auth/| 参数 | 类型 | 必填 | 默认值 | 说明 ||------|------|------|--------|------|| from_uri | str | 是 | - | 源 URI |-| uri | str | 是 | - | 要取消关联的目标 URI |+| to_uri | str | 是 | - | 要取消关联的目标 URI |**Python SDK (Embedded / HTTP)**diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.mdindex bc911736c..16c1ee2ae 100644--- a/docs/zh/api/05-sessions.md+++ b/docs/zh/api/05-sessions.md@@ -58,7 +58,11 @@ openviking session new"status": "ok","result": {"session_id": "a1b2c3d4",- "user": "alice"+ "user": {+ "account_id": "default",+ "user_id": "alice",+ "agent_id": "default"+ }},"time": 0.1}@@ -73,9 +77,9 @@ openviking session new**Python SDK (Embedded / HTTP)**```python-sessions = client.ls("viking://session/")+sessions = client.list_sessions()for s in sessions:- print(f"{s['name']}")+ print(f"{s['session_id']} -> {s['uri']}")```**HTTP API**@@ -101,8 +105,8 @@ openviking session list{"status": "ok","result": [- {"session_id": "a1b2c3d4", "user": "alice"},- {"session_id": "e5f6g7h8", "user": "bob"}+ {"session_id": "a1b2c3d4", "uri": "viking://session/alice/a1b2c3d4", "is_dir": true},+ {"session_id": "e5f6g7h8", "uri": "viking://session/alice/e5f6g7h8", "is_dir": true}],"time": 0.1}@@ -178,6 +182,7 @@ openviking session get a1b2c3d4"total_tokens": 7000},"user": {+ "account_id": "default","user_id": "alice","agent_id": "default"}@@ -430,6 +435,7 @@ openviking session delete a1b2c3d4| role | str | 是 | - | 消息角色:"user" 或 "assistant" || parts | List[Part] | 条件必填 | - | 消息部分列表(Python SDK 必填;HTTP API 可选,与 content 二选一) || content | str | 条件必填 | - | 消息文本内容(HTTP API 简单模式,与 parts 二选一) |+| created_at | str | 否 | None | 可选的 ISO 8601 时间戳,会原样保存到消息中 |> **注意**:HTTP API 支持两种模式:> 1. **简单模式**:使用 `content` 字符串(向后兼容)@@ -456,7 +462,7 @@ ContextPart(ToolPart(tool_id="call_123",tool_name="search_web",- skill_uri="viking://skills/search-web/",+ skill_uri="viking://agent/skills/search-web/",tool_input={"query": "OAuth best practices"},tool_output="",tool_status="pending" # "pending"、"running"、"completed"、"error"@@ -571,7 +577,7 @@ session.used(contexts=["viking://resources/docs/auth/"])# 记录使用的技能session.used(skill={- "uri": "viking://skills/search-web/",+ "uri": "viking://agent/skills/search-web/","input": {"query": "OAuth"},"output": "Results...","success": True@@ -595,7 +601,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \- -d '{"skill": {"uri": "viking://skills/search-web/", "input": {"query": "OAuth"}, "output": "Results...", "success": true}}'+ -d '{"skill": {"uri": "viking://agent/skills/search-web/", "input": {"query": "OAuth"}, "output": "Results...", "success": true}}'```**响应**@@ -686,6 +692,34 @@ openviking session commit a1b2c3d4---+### extract()++仅 HTTP API。立即对已有会话触发一次记忆提取,不会额外创建新的 commit 任务。++**参数**++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| session_id | str | 是 | - | 要提取记忆的会话 ID |++**HTTP API**++```+POST /api/v1/sessions/{session_id}/extract+```++```bash+curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/extract \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key"+```++**响应**++该接口会直接返回本次提取产生的记忆写入结果列表。列表项的具体结构取决于该会话实际提取出了哪些记忆。++---+### get_task()查询后台任务状态(如 commit 的摘要生成和记忆提取进度)。@@ -755,6 +789,52 @@ curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \---+### list_tasks()++仅 HTTP API。列出当前调用方可见的后台任务。++**参数**++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| task_type | str | 否 | None | 按任务类型过滤,例如 `session_commit` |+| status | str | 否 | None | 按任务状态过滤:`pending`、`running`、`completed`、`failed` |+| resource_id | str | 否 | None | 按资源 ID 过滤,例如会话 ID |+| limit | int | 否 | 50 | 最多返回的任务条数 |++**HTTP API**++```+GET /api/v1/tasks+```++```bash+curl -X GET "http://localhost:1933/api/v1/tasks?task_type=session_commit&status=running&limit=20" \+ -H "X-API-Key: your-key"+```++**响应**++```json+{+ "status": "ok",+ "result": [+ {+ "task_id": "uuid-xxx",+ "task_type": "session_commit",+ "status": "running",+ "resource_id": "a1b2c3d4",+ "created_at": 1770000000.0,+ "updated_at": 1770000005.0,+ "result": null,+ "error": null+ }+ ]+}+```++---+## 会话属性| 属性 | 类型 | 说明 |diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.mdindex a1f932744..e65d6d7f9 100644--- a/docs/zh/api/06-retrieval.md+++ b/docs/zh/api/06-retrieval.md@@ -25,11 +25,14 @@ OpenViking 提供两种搜索方法:`find` 用于简单的语义搜索,`sear| query | str | 是 | - | 搜索查询字符串 || target_uri | str | 否 | "" | 限制搜索范围到指定的 URI 前缀 || limit | int | 否 | 10 | 最大返回结果数 |+| node_limit | int | 否 | None | 可选 HTTP 别名;如果提供,会覆盖 `limit` || score_threshold | float | 否 | None | 最低相关性分数阈值 || filter | Dict | 否 | None | 元数据过滤器 |-| since | str | 否 | None | 时间下界,支持 `2h` 或 ISO 8601 / `YYYY-MM-DD`,不带时区的值按本地时间解释。CLI `--after` 会映射到这个字段 |-| until | str | 否 | None | 时间上界,支持 `30m` 或 ISO 8601 / `YYYY-MM-DD`,不带时区的值按本地时间解释。CLI `--before` 会映射到这个字段 |+| 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` 使用的元数据时间字段 |+| include_provenance | bool | 否 | False | 在序列化结果中附带 provenance / query-plan 细节 |+| telemetry | bool 或 object | 否 | False | 在响应中附带遥测数据 |**FindResult 结构**@@ -146,7 +149,7 @@ results = client.find(# 仅在技能中搜索results = client.find("web search",- target_uri="viking://skills/"+ target_uri="viking://agent/skills/")# 在特定项目中搜索@@ -195,11 +198,14 @@ curl -X POST http://localhost:1933/api/v1/search/find \| session | Session | 否 | None | 用于上下文感知搜索的会话(SDK) || session_id | str | 否 | None | 用于上下文感知搜索的会话 ID(HTTP) || limit | int | 否 | 10 | 最大返回结果数 |+| node_limit | int | 否 | None | 可选 HTTP 别名;如果提供,会覆盖 `limit` || score_threshold | float | 否 | None | 最低相关性分数阈值 || filter | Dict | 否 | None | 元数据过滤器 |-| since | str | 否 | None | 时间下界,支持 `2h` 或 ISO 8601 / `YYYY-MM-DD`,不带时区的值按本地时间解释。CLI `--after` 会映射到这个字段 |-| until | str | 否 | None | 时间上界,支持 `30m` 或 ISO 8601 / `YYYY-MM-DD`,不带时区的值按本地时间解释。CLI `--before` 会映射到这个字段 |+| 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` 使用的元数据时间字段 |+| include_provenance | bool | 否 | False | 在序列化结果中附带 provenance / query-plan 细节 |+| telemetry | bool 或 object | 否 | False | 在响应中附带遥测数据 |**Python SDK (Embedded / HTTP)**@@ -323,6 +329,7 @@ curl -X POST http://localhost:1933/api/v1/search/search \| case_insensitive | bool | 否 | False | 忽略大小写 || node_limit | int | 否 | None | 最大搜索节点数 || exclude_uri | str | 否 | None | 要排除在搜索之外的 URI 前缀 |+| level_limit | int | 否 | 5 | 最大目录遍历深度 |**Python SDK (Embedded / HTTP)**@@ -393,6 +400,7 @@ openviking grep viking://resources/ "authentication" [--ignore-case]|------|------|------|--------|------|| pattern | str | 是 | - | Glob 模式(例如 `**/*.md`) || uri | str | 否 | "viking://" | 起始 URI |+| node_limit | int | 否 | None | 最大返回匹配数 |**Python SDK (Embedded / HTTP)**diff --git a/docs/zh/api/07-system.md b/docs/zh/api/07-system.mdindex d146f66b0..7b024cf68 100644--- a/docs/zh/api/07-system.md+++ b/docs/zh/api/07-system.md@@ -36,7 +36,39 @@ openviking health```json{- "status": "ok"+ "status": "ok",+ "healthy": true,+ "version": "0.1.x"+}+```++---++### ready()++部署环境使用的就绪探针。当核心子系统都准备完成时返回 `200`,否则返回 `503`。++**HTTP API**++```+GET /ready+```++```bash+curl -X GET http://localhost:1933/ready+```++**响应**++```json+{+ "status": "ready",+ "checks": {+ "agfs": "ok",+ "vectordb": "ok",+ "api_key_manager": "ok",+ "ollama": "not_configured"+ }}```@@ -132,10 +164,18 @@ openviking wait [--timeout 60]{"status": "ok","result": {- "pending": 0,- "in_progress": 0,- "processed": 20,- "errors": 0+ "Embedding": {+ "processed": 10,+ "requeue_count": 0,+ "error_count": 0,+ "errors": []+ },+ "Semantic": {+ "processed": 10,+ "requeue_count": 0,+ "error_count": 0,+ "errors": []+ }},"time": 0.1}@@ -250,36 +290,37 @@ openviking observer vikingdb----### observer.vlm+### observer.models-获取 VLM(视觉语言模型)token 使用状态。+获取模型子系统的聚合状态(VLM、embedding、rerank)。**Python SDK (Embedded / HTTP)**```python-print(client.observer.vlm)+print(client.observer.models)# Output:-# [vlm] (healthy)-# Model Provider Prompt Completion Total Last Updated-# doubao-1-5-vision-pro-32k volcengine 1000 500 1500 2024-01-01 12:00:00-# TOTAL 1000 500 1500+# [models] (healthy)+# provider_model healthy detail+# dense_embedding yes ...+# rerank yes ...+# vlm yes ...```**HTTP API**```-GET /api/v1/observer/vlm+GET /api/v1/observer/models``````bash-curl -X GET http://localhost:1933/api/v1/observer/vlm \+curl -X GET http://localhost:1933/api/v1/observer/models \-H "X-API-Key: your-key"```**CLI**```bash-openviking observer vlm+openviking observer models```**响应**@@ -288,10 +329,10 @@ openviking observer vlm{"status": "ok","result": {- "name": "vlm",+ "name": "models","is_healthy": true,"has_errors": false,- "status": "Model Provider Prompt Completion Total Last Updated\ndoubao-1-5-vision-pro-32k volcengine 1000 500 1500 2024-01-01 12:00:00\nTOTAL 1000 500 1500"+ "status": "provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ..."},"time": 0.1}@@ -299,6 +340,11 @@ openviking observer vlm---+另外还有两个仅 HTTP 暴露的 Observer 端点:++- `GET /api/v1/observer/lock`+- `GET /api/v1/observer/retrieval`+### observer.system获取整体系统状态,包括所有组件。@@ -314,7 +360,7 @@ print(client.observer.system())# [vikingdb] (healthy)# ...#-# [vlm] (healthy)+# [models] (healthy)# ...## [system] (healthy)