Skip to content

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

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.md
index 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.md
index 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"
```python
result = 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)**
```python
client.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
Export 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.md
index 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.md
index 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 skill
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}}'
```
**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.md
index 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 skills
results = 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.md
index 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.system
Get 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.md
index 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.md
index 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"
```python
result = 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
+# 增量更新到已有 URI
openviking 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)**
```python
client.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.md
index 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.md
index 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.md
index 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.md
index 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)